docs(agent): mark coordination API experimental

This commit is contained in:
Aamer Akhter committed 2026-10-24 22:37:18 -04:00
1 parent 4c2f050a96
commit 1a2c3be0ea
12 files changed
+61 -12

No files matched your search

+3 -1
View File
@@ -2,7 +2,9 @@
"aicodeman": minor
---
Add bounded agent inspection with expiring scoped cursors and explicit pane snapshots, plus staged local Codex input and single-use hash-confirmed submission receipts. Verify the exact composer, caret, lifecycle and input revision before sending Enter, and serialize dispatch against managed input and auxiliary key operations.
Add experimental bounded agent inspection with expiring scoped cursors and explicit pane snapshots, plus staged local Codex input and single-use hash-confirmed submission receipts. Verify the exact composer, caret, lifecycle and input revision before sending Enter, and serialize dispatch against managed input and auxiliary key operations.
Explicitly exclude the three new CLI verbs and matching HTTP routes (including `/api/v1` and `/api` aliases) from the stable contract while experimental; their shape and behavior may change in minor or patch releases.
Document the initial local Codex support and conversation-attribution limits in the API, CLI and packaged skill. Other modes retain labeled snapshots or refuse unverifiable guarded input.
+1 -1
View File
@@ -977,7 +977,7 @@ codeman tui 3 # attach to session 3 of that list
### `codeman agent` — session-to-session verbs in every CLI mode
The skill above drives the API with `curl` and `jq` from a preamble Codeman seeds per session. Where it does not reach (a `pi` or `shell` session, a machine without `jq`), the same environment is still there (`CODEMAN_MUX=1`, `CODEMAN_SESSION_ID`, `CODEMAN_API_URL` are exported into every pane), so `codeman agent` packages the same verbs as commands. It is a thin client over the endpoints listed under [API](#api): auth and ownership apply to every endpoint, including bounded inspection and guarded input. One line in a case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
The skill above drives the API with `curl` and `jq` from a preamble Codeman seeds per session. Where it does not reach (a `pi` or `shell` session, a machine without `jq`), the same environment is still there (`CODEMAN_MUX=1`, `CODEMAN_SESSION_ID`, `CODEMAN_API_URL` are exported into every pane), so `codeman agent` packages the same verbs as commands. It is a thin client over the endpoints listed under [API](#api): auth and ownership apply to every endpoint, including bounded inspection and guarded input. The new `inspect`, `stage` and `submit` commands and their HTTP routes are **experimental**: commands, flags, paths, payloads and behavior may change or be removed in minor or patch releases. Pin a compatible version when automating them; see the [stability exception](docs/versioning-policy.md#experimental-agent-coordination). One line in a case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
```bash
codeman agent ls # sessions; * marks this one
+8 -1
View File
@@ -589,7 +589,14 @@ request returns. The capture runs synchronous tmux calls on the server; the
| `lines=<n>` | With `full=1` only: read at most `<n>` lines of tmux history above the visible frame. An integer of at least 1, clamped to the configured history limit; absent or malformed, the whole limit (100,000 lines by default), as before. When a bound below the configured limit left older lines in tmux (its `history_size` is deeper), `truncated` is true with `truncationReason: 'tail'`; a byte cap still reports `'capped'`. Without it a full capture reads all of that history before `tail` cuts it, so a client that keeps a fixed number of lines (the tile grid sends its xterm's scrollback plus its rows) should send it. |
| `alt=recording` | With `full=1` only: if the pane is in the alternate screen (a nested tmux, where tmux keeps no history, or any full-screen app such as vim or less while it is open), answer with the visible frame over the byte recording instead (`source: 'mux-visible'`, `tail` applied as without `full=1`). Shells' automatic loads send it. |
## Bounded agent inspection and guarded input
## Experimental bounded agent inspection and guarded input
**Experimental:** `codeman agent inspect`, `stage` and `submit`, and their
`/api/v1/sessions/:id/inspect|stage|submit` routes (including `/api` aliases),
are excluded from the stable CLI/HTTP contract. Their commands, flags, paths,
payloads and behavior may change or be removed in a minor or patch release.
Pin a compatible Codeman version when automating them. Authentication and
session ownership checks still apply.
These authenticated routes use the standard envelope and session ownership checks.
`/api/v1` aliases `/api`; an inaccessible session returns `404 NOT_FOUND` before
+4
View File
@@ -1263,6 +1263,10 @@ Its CLI knowledge is a GENERATED block (`npm run generate:cli-catalog`, markers
## Agent inspection and guarded submission
These three operations are experimental across both CLI and HTTP, including the
`/api/v1` paths and unversioned aliases. See `docs/versioning-policy.md` for the
explicit stability exception; do not infer stability from the URL prefix.
`agent-session-routes.ts` is registered by `WebServer` with the other route
modules. Ownership is checked before transcript/pane/receipt lookup. Inspection
uses strict native metadata attribution, bounded traversal, separate prefix and
+14
View File
@@ -62,6 +62,20 @@ These may change in a **MINOR** (or even PATCH) release without a MAJOR bump:
anything labeled experimental in the UI or docs. These may change or be
removed at any time.
### Experimental agent coordination
`codeman agent inspect`, `codeman agent stage` and `codeman agent submit` are
experimental. The matching `GET /api/v1/sessions/:id/inspect`,
`POST /api/v1/sessions/:id/stage` and `POST /api/v1/sessions/:id/submit` routes,
including their unversioned `/api` aliases, share this designation. This is an
explicit exception to both the CLI and HTTP stability promises above: these
commands, flags, endpoint paths, payloads and behavior may change or be removed
in a MINOR or PATCH release without a stable-surface deprecation period. Pin a
compatible Codeman version when automating them. Existing authentication,
ownership and shared response-envelope rules still apply. Other agent commands
and API routes retain their existing stability guarantees. Promotion to stable
requires an explicit documented decision.
## Deprecation policy
When we need to change a covered surface:
+1 -1
View File
@@ -30,7 +30,7 @@ through: the verbs in detail (the old §5) in [reference/verbs.md](reference/ver
worked multi-worker flows in [reference/recipes.md](reference/recipes.md), endpoint
tables and a symptom gallery in [reference/endpoints.md](reference/endpoints.md), and
direct messaging to claude workers in [reference/messaging.md](reference/messaging.md).
Bounded inspection and guarded stage/submit load only when needed from
Experimental bounded inspection and guarded stage/submit load only when needed from
[reference/inspection-and-staging.md](reference/inspection-and-staging.md).
This skill works the same whichever CLI you are: Codeman puts it where each CLI looks
@@ -1,4 +1,11 @@
# Bounded inspection and guarded submission
# Experimental bounded inspection and guarded submission
**Experimental:** `codeman agent inspect`, `stage` and `submit`, and their
`/api/v1/sessions/:id/inspect|stage|submit` routes (including `/api` aliases),
are excluded from the stable CLI/HTTP contract. Their commands, flags, paths,
payloads and behavior may change or be removed in a minor or patch release.
Pin a compatible Codeman version when automating them. Authentication and
session ownership checks still apply.
Use these commands inside a Codeman session. They use its authenticated HTTP API.
They supplement `send`, `wait` and `read` over the same HTTP transport; no direct
@@ -814,7 +814,10 @@ Rules that matter:
- **Lifetime.** An inbox goes with its session on delete. A server restart empties all
inboxes unless the user turned on *Keep agent inbox across restarts* in Settings.
## Bounded inspection and guarded submission
## Experimental bounded inspection and guarded submission
These three commands and their HTTP routes may change or be removed in minor or
patch releases; they are excluded from the stable CLI/HTTP contract.
Use `codeman agent inspect` for bounded evidence and incremental local Codex cursors.
Use `codeman agent stage --message-file` followed by one hash-confirmed
+1 -1
View File
@@ -30,7 +30,7 @@ through: the verbs in detail (the old §5) in [reference/verbs.md](reference/ver
worked multi-worker flows in [reference/recipes.md](reference/recipes.md), endpoint
tables and a symptom gallery in [reference/endpoints.md](reference/endpoints.md), and
direct messaging to claude workers in [reference/messaging.md](reference/messaging.md).
Bounded inspection and guarded stage/submit load only when needed from
Experimental bounded inspection and guarded stage/submit load only when needed from
[reference/inspection-and-staging.md](reference/inspection-and-staging.md).
This skill works the same whichever CLI you are: Codeman puts it where each CLI looks
@@ -1,4 +1,11 @@
# Bounded inspection and guarded submission
# Experimental bounded inspection and guarded submission
**Experimental:** `codeman agent inspect`, `stage` and `submit`, and their
`/api/v1/sessions/:id/inspect|stage|submit` routes (including `/api` aliases),
are excluded from the stable CLI/HTTP contract. Their commands, flags, paths,
payloads and behavior may change or be removed in a minor or patch release.
Pin a compatible Codeman version when automating them. Authentication and
session ownership checks still apply.
Use these commands inside a Codeman session. They use its authenticated HTTP API.
They supplement `send`, `wait` and `read` over the same HTTP transport; no direct
+4 -1
View File
@@ -814,7 +814,10 @@ Rules that matter:
- **Lifetime.** An inbox goes with its session on delete. A server restart empties all
inboxes unless the user turned on *Keep agent inbox across restarts* in Settings.
## Bounded inspection and guarded submission
## Experimental bounded inspection and guarded submission
These three commands and their HTTP routes may change or be removed in minor or
patch releases; they are excluded from the stable CLI/HTTP contract.
Use `codeman agent inspect` for bounded evidence and incremental local Codex cursors.
Use `codeman agent stage --message-file` followed by one hash-confirmed
+5 -3
View File
@@ -1272,7 +1272,7 @@ export function registerAgentCommands(program: Command): Command {
agent
.command('inspect <id>')
.description('Bounded transcript evidence or a labeled pane snapshot; opaque incremental cursors')
.description('Experimental: bounded transcript evidence or a labeled pane snapshot; opaque incremental cursors')
.option('--max-bytes <n>', 'UTF8 evidence budget (1–65536)', '8192')
.option('--since <cursor>', 'Resume a cursor from the same owner, pane and transcript')
.option('--json', 'Machine-readable output')
@@ -1288,7 +1288,9 @@ export function registerAgentCommands(program: Command): Command {
agent
.command('stage <id>')
.description('Type a printable single-line UTF8 file without Enter; requires a verifiable local Codex composer')
.description(
'Experimental: type a printable single-line UTF8 file without Enter; requires a verifiable local Codex composer'
)
.requiredOption('--message-file <path>', 'Regular UTF8 file, at most 8192 bytes, no trailing newline')
.option('--json', 'Machine-readable output')
.action((id: string, options: { messageFile: string; json?: boolean }) =>
@@ -1297,7 +1299,7 @@ export function registerAgentCommands(program: Command): Command {
agent
.command('submit <id>')
.description('Send Enter once only when the staged composer, pane and hash still match')
.description('Experimental: send Enter once only when the staged composer, pane and hash still match')
.requiredOption('--stage-id <receipt>', 'One-shot stage receipt')
.requiredOption('--confirm-sha <hash>', 'Exact SHA-256 returned by stage')
.option('--json', 'Machine-readable output')