Provider and adapter
A provider is an existing coding agent. An adapter is the piece that tells uuldana-cli how to start that agent, which flags enforce which permissions, and how to resume a session. No adapter is written by hand for a particular agent: uuldana-cli learns them from what each program prints for --help, and a provider that needs correcting or is not found can be described with a JSON manifest.
An account is one entry in your providers list. The same provider can appear several times, each with its own environment, which is how a second account is selected.
Transport
A transport moves bytes or messages across the process boundary.
| Transport | Native terminal UI | Main tradeoff |
|---|---|---|
| Native PTY | Preserved | Events derived from screen text are inferred, not exact. |
| ACP | Not provided | Structured protocol; capabilities have to be negotiated. |
| Custom CLI | Not provided | Uses a provider’s documented structured CLI mode. |
Every learned adapter runs the agent’s own interface through a pseudo terminal (ConPTY on Windows, a Unix PTY elsewhere). The ACP and custom CLI transports exist in the runtime for adapters that need a structured mode. Native transport explains the terminal relay.
Session and run
A uuldana-cli session groups work in one absolute workspace. A run is one provider execution inside that session. Failover ends one run and starts another in the same session. At most one run is active at a time.
A native session id belongs to the provider. It can change during a run and only means something to the provider that issued it. uuldana-cli’s unified history does not make native ids interchangeable between agents.
Capabilities and fidelity
An adapter states each capability as Supported, Unsupported, or Unknown, with the evidence behind it. Unknown never satisfies a requirement: if an adapter cannot show that a provider accepts an initial prompt, a handoff to that provider is refused instead of guessed.
Each normalized event is labeled Native, Inferred, or Synthetic. A usage limit read from terminal text is labeled inferred, and a handoff keeps those labels.