Monorepo core for the
supinfrastructure platform — an agentic execution and coding harness built for structured tool orchestration, runtime observability, contextual memory, and multi-runtime experimentation.
- Background
- Architecture Overview
- Repository Layout
- Quick Start
- Development Model
- TUI Runtime Notes
- Known Issues
- Advanced Runtime Debugging
- Component Status
This repository began as sup, an enterprise support agent named for its habit of greeting with "Sup?" It evolved into Coda: a full agentic coding harness and infrastructure platform. The codebase retains the sup namespace across package names and tooling conventions.
Q: What do you call a programmer from Boston? A: "a coda"
This is not merely an application repository. It is an agent systems platform — a substrate for building, running, and observing autonomous agents across heterogeneous runtimes.
The monorepo uses strict workspace resolution with no TypeScript path aliases, no bundler alias rewrites, and no virtual import indirection. Imports resolve exclusively through native workspace topology and package boundaries.
// Correct — resolves through workspace topology
import { adapters } from "@sup/tools"
// Never — alias indirection is not used here
import { adapters } from "@/tools"This preserves explicit dependency graphs and prevents resolver drift across runtimes, tooling chains, and build systems. The dependency graph is always what it appears to be.
The platform implements a protocol abstraction layer via ProtocolResolver and a family of adapters. Rather than coupling agent logic to specific execution transports, the architecture routes execution through protocol-aware adapters. This enables:
- Runtime-independent agent execution
- Swappable transport bindings
- Structured protocol lifecycle management
Protocol execution is a first-class concern, not an implementation detail.
Agents are specialized by domain with distinct model specifications and runtime selection:
| Domain | Purpose |
|---|---|
coding |
Agentic coding tasks, code generation, repository interaction |
support |
Enterprise support workflows, conversational resolution |
This is not just a configuration split — it reflects capability partitioning and domain-aware execution routing. Each agent domain carries its own model binding, tool permissions, and runtime context.
Feature control follows the OpenFeature specification. The platform supports provider-driven flag evaluation and runtime capability gating:
- Multi-provider evaluation
- Environment and provider-backed configuration
- Progressive enablement and isolation of agent capabilities
Agent behavior and infrastructure capabilities can be enabled, isolated, or experimentally deployed without touching execution logic. This is a provider-first infrastructure model — features are managed at the platform layer, not embedded in business logic.
Agent memory is modeled as a knowledge-linked contextual system rather than a flat conversational buffer. The architecture supports:
- Structured memory persistence
- Relationship-aware retrieval
- Contextual problem solving
- Cross-session state recovery
Memory is treated as navigable context capable of supporting longer-horizon reasoning and operational continuity — not merely prompt accumulation.
Coda treats observability as a first-class runtime primitive. Execution surfaces emit structured telemetry across:
- Tool invocation
- Protocol execution
- Runtime events
- Agent state transitions
- Infrastructure interactions
This enables debugging, tracing, and behavioral analysis at the agent execution layer — not just at the application boundary. Telemetry is wired in, not bolted on.
The platform runs primarily on Bun. Active work is underway to ensure full Node.js compatibility, driven in part by the non-trivial effort required to get the TUI stable under Bun's runtime constraints.
Current runtime surface:
- Bun — primary runtime across services and the TUI
- Node.js — compatibility target; full support in progress
- Terminal-native interfaces — experimental TUI via
@opentui/corewith native FFI - Runtime-dependent transport and FFI systems — per-runtime capability binding
apps/
cli/ Streaming agentic CLI (token-level output, interactive)
tui/ Experimental terminal UI (Bun-only, see TUI Runtime Notes)
packages/
agents/ Agent definitions, domain routing, orchestration logic
infra/ Providers, adapters, OpenFeature bindings, infrastructure interfaces
lib/ Cross-cutting runtime and protocol logic
tools/ Shared utility libraries (declaration-only during development)
.auth Local credential file (not committed)
package.json Workspace configuration
tsconfig.json Shared compiler configuration
Bun is the primary runtime. Node.js (LTS) is also required for certain workspace tooling. Ensure Bun is available on your shell path before proceeding. (Or file any issues you run into with Node.)
If an NVM switch or local Node upgrade resets your path configuration:
export PATH="$HOME/.bun/bin:$PATH"From the repository root:
bun installMost backend services and shared packages run through standard workspace tooling:
bun run dev --workspace=<target-package>Example:
bun run dev --workspace=apps/apiThe terminal interface lives at apps/tui. It requires Bun and has specific environment requirements:
AGENT=coding PINOLOGGER_DISABLED=true bun run apps/tui/index.tsxSee TUI Runtime Notes for the full explanation of these requirements.
TypeScript paths mappings and bundler alias rewrites are not used. All imports resolve through native workspace topology.
This keeps dependency relationships explicit and prevents resolver divergence across runtimes and build systems. The dependency graph is legible without toolchain knowledge.
Some packages — notably packages/tools — are configured with:
"emitDeclarationOnly": trueThese packages emit TypeScript declarations but produce no compiled JavaScript locally. Consumers either execute upstream source directly or use runtimes capable of source evaluation (e.g., Bun, ts-node).
This keeps workspace iteration lightweight and avoids redundant local compilation steps during development.
The TUI runs on Bun — but getting it there was non-trivial. Several compatibility constraints made Bun a challenging target, and full Node.js support remains an active goal for exactly this reason.
Remote Loki logging is currently disabled within the TUI runtime. Observed behavior:
- TUI startup succeeds with Loki disabled
- TUI startup crashes under Bun when Loki transport initialization is enabled (Believe me, I've tried to get this working, without using a really egregious hack.)
PINOLOGGER_DISABLED=true is required when launching the TUI until the transport layer is isolated and restructured.
@opentui/core relies on Bun-native FFI bindings via bun:ffi and related memory structures to communicate with low-level terminal rendering systems. This is one of the primary constraints driving Bun as the TUI runtime.
Portions of the workspace emit TypeScript declarations rather than compiled JS. Standard Node ESM execution cannot resolve these internal package dependencies without additional transpilation or pre-emitted output, producing module resolution failures at TUI entrypoints. Resolving this is part of the broader Node compatibility work.
The TUI may occasionally render a blank viewport immediately after startup. This occurs when terminal dimensions are not fully available before framebuffer initialization.
Workaround: Resize the terminal window slightly. This emits a SIGWINCH event and forces viewport recalculation. The interface repaints immediately.
Do not remove PINOLOGGER_DISABLED=true without first isolating the Loki transport layer.
One experimental approach: intercept the runtime dependency during Bun startup and substitute a minimal transport implementation.
apps/tui/dev-bootstrap.ts
import { plugin } from "bun";
plugin({
setup(build) {
build.onLoad({ filter: /pino-loki/ }, () => ({
contents: `
export default () => ({ stream: process.stdout });
`,
loader: "js",
}));
},
});
import "./index.tsx";Run with:
bun run apps/tui/dev-bootstrap.tsThis approach is intended for debugging and local experimentation. It is not a production transport solution.
| Component | Status |
|---|---|
| Shared packages | Stable |
| Backend services | Stable |
| Agent runtime | Active development |
| TUI | Experimental |
As GitBook documentation matures, deeper architectural and runtime material will migrate there. This README serves as the primary onboarding and operational reference in the interim.