Process-boundary architecture
uuldana-cli runs existing coding agents through their native terminal interfaces or documented structured modes. Its guiding boundary is explicit: the adapter describes, the transport moves bytes, the supervisor decides.
The supervisor does not reason about code, invoke an LLM, replace native tools, or discover instructions for the provider. The provider remains the coding agent.
Components
| Component | Responsibility |
|---|---|
uuldana-cli |
The uuldana binary: argument parsing, the terminal frame and scrolling, the /agent menu, session start and resume. |
uuldana-core |
Synchronous, I/O-free contracts with no third-party dependencies. |
uuldana-provider-sdk |
Stable adapter-facing re-exports of core contracts. |
uuldana-providers |
Finding programs on the search path, reading their --help, learning adapters from it, manifest adapters, and the usage-limit phrases of manifests. |
uuldana-runtime |
Supervisor, terminal relay, ACP client, journal, configuration, cooldowns, handoff, and the orchestrator that runs failover. |
uuldana-transport |
Process execution: PTY, ACP, and custom CLI transports. |
Data flow
Registry -> adapter detection and capability statements
-> permission mapping and core validation
-> LaunchPlan + TransportSpec
-> runtime / transport execute the plan
-> frames -> decoder -> normalized events
-> supervisor updates the session, run, and journal
-> orchestrator watches for a usage limit and starts the next entryOwnership
Provider configuration, authentication, native transcripts, and hidden state remain provider-owned. uuldana-cli owns its session record, run history, normalized event log, and journal. No agent’s own session files are read; a handoff uses the text uuldana-cli saw on the agent’s screen.
The permission ceiling is user-controlled and enforced by contract checks. It is not an independent operating system sandbox. Adapter trust and conformance review remain part of the architecture.
Availability
Core contracts are frozen at 0.2. Runtime, providers, sessions, failover, and the command line are implemented in this early version. Current implementation status separates what was tested against real programs from what was not.