mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-16 19:29:33 +01:00
docs(agent): mark coordination API experimental
This commit is contained in:
1 parent
4c2f050a96
commit
1a2c3be0ea
12 files changed
+61
-12
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
+5
-3
@@ -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')
|
||||
|
||||
Reference in new issue
Block a user