retoor
cc1c130b51
- Agent side: --cap-manifest plus --cap-speak stream-json binding with transcript-diff frames, diff/transcript artifacts, session config - Orchestrator: PTY driver (settle heuristics on PtyProc/TuiVtScreen), stream-json, ACP-stdio (permission/elicit/fs/terminal serving) and A2A drivers (dual draft/current spelling, SSE mapping) - Sessions, fleets: worktrees, master plans, mediated routing, budget refusal, audit log, research auto-answerer, --cap CLI - cap.md contract with drift tests; research/cap-protocol archive - Suites 1119 + 16 green
57 lines
3.7 KiB
Markdown
57 lines
3.7 KiB
Markdown
# CAP Core v1 specification
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
|
| Subject | cap-protocol |
|
|
| Document type | Source Dossier |
|
|
| Tier | 1 |
|
|
| Source title | CAP CLI Agent Protocol (Core v1) |
|
|
| Source URL | https://github.com/rsclaw-ai/cap-protocol/blob/main/docs/cap-v1.md |
|
|
| Source type | specification |
|
|
| Source date (published) | 2026-05-18 (draft, public review) |
|
|
| Date researched | 2026-10-18 |
|
|
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
|
|
| Research method | direct raw-file fetch, read in full (1036 lines) |
|
|
| Confidence | High |
|
|
| Status | Active |
|
|
|
|
## Summary
|
|
|
|
The normative core: PTY is the REQUIRED universal binding, four OPTIONAL fast-paths (stream-json, gRPC, ACP-stdio, A2A), 14 core event kinds, 3 core reverse-RPC methods, a lifecycle starting with `cap.session.config` then `cap.session.ready`, first-class multi-agent orchestration (§10), A2A interop both directions (§11), and a dual numeric/string error registry (§14.2).
|
|
|
|
## Key findings
|
|
|
|
- Agent conformance = CLI-invokable + publishes Manifest + matches one binding contract; orchestrator conformance = reads manifests + PTY binding + §10 semantics + required reverse RPC.
|
|
- Manifest resolution order: in-package, user-local (`~/.config/cap/agents/`), system-wide (`/usr/share/cap-agents/`), `--cap-manifest` probe.
|
|
- Parse regexes use a POSIX ERE subset (no backrefs/lookaround); drivers MUST reject richer patterns. Note: the spec's own examples use `(?P<tool>...)` named groups, which are NOT in that subset.
|
|
- PTY details: ANSI/VT100 screen buffer, regexes against rendered text on line boundaries, idle = idle-regex on last line + 200ms silence, bracketed paste over 1KB, cancel graceful/hard/none, 10k scrollback SHOULD, `pty_died` error on unexpected exit.
|
|
- Orchestration: `cap://` URNs, master plan with `_meta.cap.assigned_to`, no direct sub-agent contact (all mediated + audited), git worktrees SHOULD, orchestrator MUST aggregate usage and hard-cancel over budget, cooperative interruption pattern (cancel + preserve + resend).
|
|
- Reverse RPC has no defined wire encoding for stream-json/gRPC bindings; only the ACP binding gives it a native transport (JSON-RPC methods).
|
|
- Error registry: -32001..-32010 with string twins; `cap.error` string codes include `rate_limit`, `pty_died`, `parse_failed`, `context_overflow`.
|
|
|
|
## Pros / strengths
|
|
|
|
- Complete contract in one file: events, lifecycle, orchestration, errors, and informative binding mappings (C.1-C.4) sufficient to implement drivers without guessing.
|
|
- PTY-required/fast-path-optional layering matches tai's stdlib-only reality: full conformance is reachable without gRPC or any dependency.
|
|
- The §10 orchestration semantics (URNs, mediated routing, budget aggregation) map directly onto tai's existing subagent + scheduler machinery.
|
|
|
|
## Cons / limitations / caveats
|
|
|
|
- Draft status with real drift risk: A2A method names in §6.5/C.4 (`message/send`, `tasks/cancel`) do not match current A2A (PascalCase / colon-REST); see the naming-drift conclusion.
|
|
- Self-contradiction on regex flavor (§5.4 ERE-only vs `(?P<>)` in §5.1 examples); tai must decide what to accept.
|
|
- Reverse RPC over stream-json is unspecified, so tai-as-agent cannot offer fs/terminal mediation on its speak path without inventing framing.
|
|
- No conformance test suite ships with the spec; interop is validated against the reference Rust implementation only.
|
|
|
|
## Relevance to tai
|
|
|
|
The build blueprint for both directions: tai-as-agent implements §3.1 via `--cap-manifest` + stream-json speak; tai-as-orchestrator implements §3.2 minus gRPC. The §7 event table and §14.2 error table become `cap.md` drift tables.
|
|
|
|
## Changelog
|
|
|
|
| Date | Change |
|
|
|---|---|
|
|
| 2026-10-18 | Initial dossier created. |
|