tai/cap.md

CAP support in tai (Cap*)

Tai speaks the CLI Agent Protocol both directions: as an agent (--cap-manifest, --cap-speak) and as an orchestrator driving other CLI agents. Normative upstream: CAP Core v1 plus the coding profile; research archive is research/cap-protocol/. Protocol id CAP_VERSION, manifest schema CAP_MANIFEST_SCHEMA, coding profile id CAP_PROFILE_CODING, shipped manifest revision CAP_MANIFEST_REVISION.

Conformance claim

• Agent: CLI-invokable, publishes TAI_CAP_MANIFEST via --cap-manifest, matches the PTY contract and speaks stream-json via --cap-speak. Claims the coding profile.
• Orchestrator: reads manifests via CapRegistry, implements PTY plus stream-json plus ACP-stdio plus A2A bindings (gRPC excluded, see Deviations), honors the §10 rules below, and serves the reverse RPC it advertises.

Phases

1. Events, errors, manifest registry, --cap-manifest. DONE.
2. Agent --cap-speak stream-json binding, coding artifacts. DONE.
3. Orchestrator PTY driver (CapPtyDriver on PtyProc plus TuiVtScreen, parse). DONE.
4. Orchestrator stream-json driver plus §10 orchestration (CapSession, CapFleet, worktrees, budget). DONE.
5. ACP-stdio and A2A drivers, reverse RPC serving, research auto-answerer (CapAnswerer). DONE.

Core events (CapEvent)

Kinds in CapEvent.KINDS:

Agent to orchestrator: cap.session.ready, cap.text_chunk, cap.tool_call.start, cap.tool_call.delta, cap.tool_call.end, cap.plan, cap.thought, cap.ask_user, cap.permission.request, cap.usage, cap.error, cap.artifact, cap.fs.change, cap.pty.raw_bytes. Orchestrator to agent: cap.user_input.inject, cap.cancel, cap.session.config, plus answers cap.ask_user.answer and cap.permission.response. Directions live in CapEvent.DIRECTIONS, required fields in CapEvent.REQUIRED.

Enum vocab: channel is assistant, thought or system; status is pending, in_progress, completed, cancelled or blocked; priority is urgent, high, medium or low; scope (cancel) is current_turn or session; risk_level is low, medium or high; decision is allow_once, allow_always or deny; permission_mode is none, confirm or interactive; stop_reason is end_turn, max_tokens, tool_use, stop_sequence, cancelled or error.

Errors

CAP_ERROR_CODES maps numerics to symbols, CAP_ERROR_SYMBOLS maps back. Core: -32001 cap_manifest_missing, -32002 cap_session_config_missing, -32003 cap_unsupported_capability, -32004 cap_budget_exceeded, -32005 cap_invalid_answer, -32006 cap_unknown_permission, -32007 cap_queued_input_unsupported, -32008 cap_cancel_unsupported, -32009 cap_binding_unavailable, -32010 cap_profile_unsupported. Coding: -32020 cap_scope_violation, -32021 cap_path_not_found, -32022 cap_io_error, -32023 cap_terminal_unavailable, -32024 cap_terminal_killed.

CAP_ERROR_STRINGS holds the cap.error string codes: core rate_limit, auth_error, tool_timeout, context_overflow, model_unavailable, pty_died, parse_failed; coding git_dirty, test_failed, merge_conflict, language_server_down. Wire failures raise CapError.

Manifests (CapManifest, CapRegistry)

Required (§5.2): agent.name, agent.binary, agent.profiles, startup.command, startup.ready_when, pty.cols, pty.rows, capabilities.streaming_output. Defaults (§5.3) in CapManifest.DEFAULTS: pty.bracketed_paste false, pty.sigint_cancels_turn hard, pty.queued_input_supported false, capabilities.multi_session false, capabilities.ask_user.* all false, capabilities.streaming_tool_output false, cost.metered false, parse.idle the >/❯ pair, all other parse.* unset, parse.error_lines empty.

Resolution order in CapRegistry: binary sibling cap-agent.toml, user-local ~/.config/cap/agents/, system-wide /usr/share/cap-agents/, probe <binary> --cap-manifest with timeout CAP_PROBE_TIMEOUT seconds. Override dirs via constructor args in tests.

Bindings (CapBinding)

Priority CapBinding.ORDER: grpc, stream_json, acp_stdio, a2a, pty. CapBinding.UNSUPPORTED is grpc only (stdlib has no HTTP/2 or protobuf); selection falls through past it. Manifest booleans false and absent fields mean the same: not supported. A2A tries draft endpoints first (POST /message/send, /tasks/cancel), then current A2A (POST /message:send, POST /tasks/{id}:cancel). The ACP server argv is out-of-band (fleet argv, chat --argv): the manifest carries no ACP command. Pipe drivers share CapPipeReader (non-blocking NDJSON, CAP_STREAM_LINE_MAX shared cap), cap_stderr_drain, cap_proc_kill and cap_proc_reap.

Reverse RPC served by the orchestrator

Core: cap.user_io.show, cap.user_io.input, cap.notify. Coding fs: cap.fs.read, cap.fs.write, cap.fs.list, cap.fs.exists, cap.fs.delete, cap.fs.watch. Coding terminal: cap.terminal.create, cap.terminal.output, cap.terminal.wait, cap.terminal.kill, cap.terminal.release. Scope enforcement: workspace_only is the session cwd subtree, project_root the VCS-root ancestor subtree, unrestricted nothing (discouraged); symlinks resolve before the check and MUST NOT escape.

CapAcpDriver speaks ACP v1 (CAP_ACP_VERSION) over stdio: initialize handshake, session/new, prompt turns with the C.3 update mapping (message/thought chunks, tool calls, plan, usage deltas). It serves fs/read_text_file and fs/write_text_file (line windows, CAP_ACP_FS_MAX bytes), terminal/* (grants, CAP_ACP_TERMINALS_MAX concurrent, CAP_ACP_TERM_BUF retention, CAP_ACP_TERM_WAIT_MAX wait cap), form elicitation/create (URL declined), and tai _cap/* extensions for fs.list/exists/delete plus user_io.show/input and notify. Permission, elicitation and input answers flow through the unified open_asks stash.

CapA2aDriver refuses cards without the cap-protocol/v1 extension, posts messages (flavor sticky after discovery), and maps SSE payloads: raw cap.* events, _meta.cap.kind data parts, text parts, task states (input-required opens an ask, terminal states end the turn), plain artifacts. Answers return as marked data parts. HTTP timeout CAP_A2A_TIMEOUT (30). Tai does not expose sessions over A2A (server side unbuilt).

Orchestration (§10)

Sessions get cap:// URNs stable per orchestrator. Master plans carry _meta.cap.assigned_to and _meta.cap.depends_on; sub-agents never talk directly, every @cap:// directive routes through the orchestrator into the audit log. Coding sub-agents get git worktrees under .cap-worktrees/, merged by the orchestrator. Usage aggregates across the fleet and the orchestrator hard-cancels past budget. Interruption is cooperative: cancel the turn, keep partial text, resend with the correction.

CapSession pumps one driver on its own thread, queues events, and blocks per turn in ask with CAP_TURN_TIMEOUT (600); CapTurnResult carries the turn events, end state, usage delta and joined text. CapFleet provisions git worktrees per coding session (plain dirs outside git, both tracked and removed on close), publishes validated master plans, routes @cap:// mentions (CAP_MENTION_RE) through per-session pending queues (CAP_ROUTE_QUEUE_MAX, 16, idle-only delivery), refuses new turns past budget_usd, and keeps every mediation in the audit log. collect_diffs reports bounded per-worktree diffs (CAP_FLEET_DIFF_MAX, 65536); merging stays the operator's call. Poll cadence CAP_SESSION_POLL (0.1), worktree root CAP_WORKTREE_DIR.

CapFleet.set_answerer installs a CapAnswerer: open asks and permission requests each get one daemon research thread (deduped, counted busy by wait_idle, audited). Policy first (deny list, allow list, max_risk over CAP_ANSWER_RISKS), then an isolated tai one-shot (--auto, own vault under cap-research) bounded by CAP_ANSWER_TIMEOUT (300) and CAP_ANSWER_PARALLEL (4); the value comes from the last CAP_ANSWER_MARKER line. Failures fall back safe (deny, False, unknown). CLI: --auto-answer, --allow-tool, --deny-tool, --max-risk (cap_answer_flags, cap_build_answerer); fleet file auto_answer, allow_tools, deny_tools, max_risk.

Stream driver (CapStreamDriver)

NDJSON over pipes with the C.1 mapping (init to ready, assistant blocks to chunk/thought/tool start, tool results to tool end, result to usage or error, tai artifact frames to cap.artifact, unknown lines counted in ignored_frames). stdout is non-blocking with a manual line buffer capped at CAP_STREAM_LINE_MAX (1048576); stderr drains on a daemon thread into the last CAP_STREAM_STDERR_KEEP (50) lines, quoted on unexpected exit. Turn cancel kills the one-shot process and the next send respawns lazily.

PTY heuristics (CapPtyDriver)

CapDriver is the shared base (identity, event queue, id sequences, send guards, spawn-then-ready start). States in CapDriver.STATES: starting, ready, working, input_required, done, failed, closed. done ends the turn with the session alive; closed and failed are terminal.

Spawns under PtyProc, renders through TuiVtScreen (text_lines), writes terminal replies back. Settle window CAP_PTY_SETTLE_MS (800), prompt gate (no Done before the first real prompt), bounded resubmits CAP_PTY_RESUBMITS_MAX (3), wait-for-ready before the first prompt, 150ms text-to-Enter gap CAP_PTY_SUBMIT_GAP_MS, scrollback CAP_PTY_SCROLLBACK (10000), raw-bytes stream opt-in only via raw_sink. Idle is the idle regex on the last line plus 200ms silence CAP_PTY_IDLE_MS; boot ready needs the marker plus the same silence. Boot timeout CAP_PTY_INIT_TIMEOUT (60) when the manifest sets none.

Line events from fresh rendered rows, first match wins: error lines to cap.error (rate_limit/auth_error by substring, else error), tool start/end pairing by call id, ask patterns to cap.ask_user (answered via CapPtyDriver.answer), plan/thought markers to cap.plan / cap.thought. Identical line events suppress repeats per turn. Cancel consults capabilities.mid_turn_cancel over pty.sigint_cancels_turn over hard; queued input consults capabilities.queued_input over pty.queued_input_supported over false.

CLI surface

• --cap-manifest: print TAI_CAP_MANIFEST and exit 0. No vault, no network, no boot. Phase 1.
• --cap-speak: stream-json over stdio (agent side). Bulk session config via CAP_SESSION_CONFIG (JSON cap.session.config); --cap-cwd, --cap-model, --cap-permission-mode, --cap-max-turns override single fields. Phase 2.
• cap orchestrator commands via --cap (cap_cli_main, cap_cli_help): resolve (cap_resolve_main), chat (cap_chat_main, task once plus tty REPL, --argv for ACP servers), run (cap_run_main over a fleet.toml validated by cap_fleet_plan). Results print via cap_print_result. Phase 4.

fleet.toml schema: [fleet] with start (a session URN), task, optional budget_usd, auto_answer, allow_tools, deny_tools, max_risk; [[sessions]] with name, agent (registry key), optional cwd/model/argv; [[routes]] with when (source URN, .done suffix allowed) and route_to. Routes run statically in order, each feeding the source's last text into the target.

Speak path (CapSpeakSession)

CapSessionConfig parses env plus flags; CapStreamJson builds Claude-compatible frames and parses inbound user frames; CapSpeakSession runs each turn through Agent.run_turn with stdout parked on stderr and emits the transcript diff (assistant frames, grouped tool results, result frame) plus a diff artifact when the tree changed. CAP_SPEAK_MAX_TURNS (50) caps turns when unset; CAP_SPEAK_DIFF_MAX (65536) caps inline diff bytes.

Permission mapping: none boots yolo, confirm and interactive boot auto (research instead of asking); stdin is never read for prompts. Artifacts travel as tai artifact frames (receivers ignore unknown types); the transcript artifact is a file:// URI under cap-transcripts/, written at session end. Constants CAP_SESSION_CONFIG_ENV, CAP_SPEAK_MAX_TURNS, CAP_SPEAK_DIFF_MAX; entry cap_speak_main; cancel via cap_interrupt (SIGTERM acts like Ctrl-C, emits an error result, exits 130).

Deviations from upstream

• gRPC binding not implemented (stdlib).
• Regex flavor: tai accepts Python named groups (?P<>) (every shipped example uses them) and rejects only lookaround and backreferences, against the letter of §5.4.
• No fs/terminal mediation on the agent speak path: reverse RPC framing over stream-json is unspecified upstream.
• A2A dual spelling (draft first, current fallback).
• Worktrees under .cap-worktrees/ per the profile text, not the reference CLI's .cap/.
• PTY submit sends CR, not the spec's LF: CR is Enter in both canonical and raw terminal modes.
• Idle/prompt rows never emit cap.text_chunk; no usage events on the PTY path (agents report none).
• Tool end output is empty (PTY shows no result payload); plan entries carry the marker line as content.
• A2A expose (serving tai sessions over A2A) is not built; tai drives A2A agents but does not serve them.
• ACP terminal/wait_for_exit is capped at 600s and reports null exit codes when still running; v2 renames deferred.
• _cap/fs.list/exists/delete and _cap/user_io.* shapes are tai-defined (the profile fixes methods, not JSON shapes).