@agent-deck/cli 2.3.2 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/agent-harness.js
CHANGED
|
@@ -40,10 +40,10 @@ Before declining for missing tools (Slack, Linear, GitHub, etc.), use agent-deck
|
|
|
40
40
|
|
|
41
41
|
**Deck admin (create/edit deck):** Normal agents get \`ADMIN_REQUIRED\`. Call \`request_admin_elevation\`; user approves in the dashboard/menubar. After approval, \`mode\` is \`agent-admin\` until lease expiry or \`exit_admin_mode\`. Surface shared-deck workspace counts before mutating a deck used elsewhere. Deck switches never use elevation — request them with \`switch_deck\` and wait for human approval.
|
|
42
42
|
|
|
43
|
-
**Delegating to another session:** When the user asks to hand a task to another
|
|
44
|
-
The orchestrator must not choose the deck — the user names it; never pick or change it yourself.
|
|
45
|
-
|
|
46
|
-
For the brief–
|
|
43
|
+
**Delegating to another session:** When the user asks to hand a task to another session, delegate only through Agent Deck MCP: \`start_run\`, then \`get_run\` until terminal, then \`start_run\` with \`resumeSessionId\` or \`cancel_run\`; your shell is not the Agent Deck host, so if MCP or the launch workspace is unavailable, report the error and stop.
|
|
44
|
+
The orchestrator must not choose the deck — the user names it; never pick or change it yourself (a move is a human-approved \`switch_deck\`).
|
|
45
|
+
Pass \`tools: "readonly"\` unless the brief owner says \`edit\`, and never raise the profile on your own.
|
|
46
|
+
For the brief–start–monitor–review–resume protocol read the \`agent-deck-run\` skill (\`skills/agent-deck-run/SKILL.md\`); for per-client resume ids and trust behavior read \`docs/DELEGATION.md\`.
|
|
47
47
|
For corrections from a delegated run, who files and with what evidence is defined in the "Corrections from a delegated run" block of \`skills/agent-deck-run/SKILL.md\`.
|
|
48
48
|
|
|
49
49
|
**Playbooks — runtime discovery (no generated stubs):** Playbook triggers and bodies live only on the bound deck — \`agent-deck use\` and bind/switch write no per-playbook files, so switching decks never requires regenerating workspace files for discovery. On every task, match the task against the playbook \`triggers\` returned by \`get_bound_deck\` and call \`get_playbook\` for every match before acting. A playbook that exists only on the newly active deck is discovered the same way (\`get_bound_deck\` lists its triggers; \`get_playbook\` fetches its body) — never rely on checked-in stub or skill files, which may belong to a previously bound deck. **Never** mirror playbook bodies into \`.cursor/skills/\`, rules, or Claude skills — one source of truth on the deck.
|
|
@@ -1,86 +1,88 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agent-deck-run
|
|
3
|
-
description: "Use when delegating a task to
|
|
3
|
+
description: "Use when delegating a task to another coding session on a deck: brief it, start it through Agent Deck MCP (start_run), monitor it (get_run), review the result against the goal, and resume (start_run with resumeSessionId) or cancel (cancel_run) until done."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Agent Deck run (orchestrator)
|
|
7
7
|
|
|
8
|
-
You are the caller of a session, not the session.
|
|
8
|
+
You are the caller of a session, not the session. The run executes on the Agent Deck host, in the workspace your session was launched for, on your session's current deck. You drive it only through Agent Deck MCP tools: `get_session_context`, optional `switch_deck`, `start_run`, `get_run`, and `cancel_run`. Your own shell is not the Agent Deck host.
|
|
9
9
|
|
|
10
|
-
## 0.
|
|
10
|
+
## 0. Bootstrap
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Call `get_session_context`. It names the effective deck. If the user wants the run on another deck, call `switch_deck` with the deck the user named and wait for human approval, then call `get_session_context` again and confirm the new deck. Use "This session only" unless the user asks to change the workspace default.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
agent-deck --version # >= 2.1.0
|
|
16
|
-
agent-deck status # Status: running
|
|
17
|
-
agent-deck deck list # the deck the user named exists
|
|
18
|
-
claude auth status # or: codex login status | cursor-agent status | muse --version
|
|
19
|
-
```
|
|
14
|
+
Leave the user's uncommitted changes alone.
|
|
20
15
|
|
|
21
|
-
|
|
16
|
+
## 1. Write the brief
|
|
22
17
|
|
|
23
|
-
|
|
18
|
+
Build the brief in memory as the `prompt` text; no prompt file is needed. It must state the goal, the constraints, the definition of done, what the session must not do, the tool profile the brief owner chose, and "if unclear, end your turn with the question". For code changes, the definition of done includes committing and pushing a named branch. Keep the user's decisions; label any number you had to assume as an assumption. Never put secrets or host credentials in the brief.
|
|
24
19
|
|
|
25
|
-
|
|
26
|
-
cd <dir> && agent-deck use <deck> --client <client>
|
|
27
|
-
```
|
|
20
|
+
## 2. Start
|
|
28
21
|
|
|
29
|
-
|
|
22
|
+
The user names the deck; the brief owner picks the tool profile: `readonly` for research, planning, and review, `edit` for coding work. When the brief owner has not said, use `readonly`. Always pass `tools` explicitly.
|
|
30
23
|
|
|
31
|
-
|
|
24
|
+
```json
|
|
25
|
+
start_run { "client": "claude", "prompt": "<brief>", "tools": "readonly" }
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `client`: `claude`, `codex`, `cursor`, or `muse`.
|
|
29
|
+
- `prepareFinalization: true` only with `tools: "edit"` when the brief owner wants a finalization-ready edit run (clean Git worktree required).
|
|
30
|
+
- `playbookVersion: { "playbookId": "pb_…", "versionId": "…" }` only when the user asks to pin one playbook version (for example a baseline evaluation).
|
|
31
|
+
- `start_run` takes no deck and no cwd: the deck is the session's current deck and the cwd is the launch workspace.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
It returns `{ runId, state }`.
|
|
34
34
|
|
|
35
|
-
##
|
|
35
|
+
## 3. Monitor
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
Call `get_run { "runId": "<runId>" }` about every 30 seconds. Read-only runs typically take 1–3 minutes, so this cadence catches the end within one interval without busy-polling. Pass the returned `nextCursor` back as `after` to read only new events. The run is finished when `state` is `ended`, `error`, `died`, or `canceled`; the terminal event is then already in the page. Keep paging until a page returns no events.
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
agent-deck run <deck> --client <client> --cwd <dir> --prompt-file <brief-file> --tools readonly --detach
|
|
41
|
-
```
|
|
39
|
+
Take the final answer from the `result` event, not from the last `text` event. Read `text` events for questions and answer them from verified facts or ask the human. Record `runId`, `sessionId`, `tools`, and `state`.
|
|
42
40
|
|
|
43
|
-
|
|
41
|
+
## 4. Review
|
|
44
42
|
|
|
45
|
-
|
|
43
|
+
Judge the output against the goal and definition of done from step 1, not against the session's own summary. Check the real artifacts you can reach: files in your workspace, the diff, tickets, the PR. For code work, confirm the pushed branch and commit the session names. If it meets the goal, report to the human and stop.
|
|
46
44
|
|
|
47
|
-
##
|
|
45
|
+
## 5. Resume or cancel
|
|
48
46
|
|
|
49
|
-
|
|
47
|
+
To resume, call `start_run` again with a feedback brief that quotes the gap you found in step 4. Pass `resumeSessionId` set to the run's `sessionId` and pass `tools` again with the same profile, because the profile is not inherited. Then return to step 3.
|
|
50
48
|
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
agent-deck run status <runId> --json
|
|
54
|
-
agent-deck run log <runId> --follow
|
|
55
|
-
agent-deck run log <runId> --tail 50
|
|
56
|
-
agent-deck run list
|
|
49
|
+
```json
|
|
50
|
+
start_run { "client": "claude", "prompt": "<feedback brief>", "tools": "readonly", "resumeSessionId": "<sessionId>" }
|
|
57
51
|
```
|
|
58
52
|
|
|
59
|
-
|
|
53
|
+
You can resume for at most 3 feedback rounds. If the goal is still not met after round 3, stop and bring the blocker to the human instead of resuming again.
|
|
60
54
|
|
|
61
|
-
|
|
55
|
+
To stop a live run (the human asks for it, or the brief is wrong), call `cancel_run { "runId": "<runId>" }`. Canceling twice is safe: a repeat, or a cancel on a finished run, returns the current status unchanged.
|
|
62
56
|
|
|
63
|
-
|
|
57
|
+
## Failures: stop and report
|
|
64
58
|
|
|
65
|
-
|
|
59
|
+
On each failure below, report it in one or two sentences with the error code and stop. Do not work around it from your own shell.
|
|
66
60
|
|
|
67
|
-
|
|
61
|
+
| Failure | What you see | Next action |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| Agent Deck MCP missing | No `get_session_context` / `start_run` tools, the tool call fails, or `GRANT_REQUIRED` | Report that Agent Deck MCP is unavailable in this session. Stop. The human fixes the connection. |
|
|
64
|
+
| No launch workspace | `WORKSPACE_REQUIRED` | Report that this session was launched without an execution workspace. Stop. Only the launcher can supply it. |
|
|
65
|
+
| Workspace gone | `WORKSPACE_INVALID` | Report that the launch workspace no longer exists on the host. Stop. |
|
|
66
|
+
| Provider unavailable | `CLIENT_UNAVAILABLE`, or `PROFILE_UNSUPPORTED` | Report which client is unavailable on the host (missing or signed out) or cannot enforce the profile. Stop. Do not pick a different client unless the user says so. |
|
|
67
|
+
| Deck switch not approved | `switch_deck` rejected or expired, `DECK_FIXED`, or `ADMIN_REQUIRED` | Report that the deck was not switched and that the session is still on the previous deck. Do not start the run on the old deck unless the user says so. Stop. |
|
|
68
|
+
| Run failed | `state` is `error` or `died` | Report the `runId`, `sessionId`, state, and the error event's message. Stop. Do not start it again on your own. |
|
|
69
|
+
| Run canceled | `state` is `canceled` | Report that the run was canceled and by whom, if known. Stop. |
|
|
70
|
+
| Out of scope | `RESOURCE_OUT_OF_SCOPE` or `RUN_NOT_FOUND` | Report that the run is not reachable from this session's deck and workspace. Stop. |
|
|
71
|
+
| Bad request | `INVALID_REQUEST`, `RESUME_UNVERIFIED`, `FINALIZATION_INVALID`, `INDEX_DIRTY` | Fix the argument only if the brief owner's intent is clear (for example, a wrong `sessionId`). Otherwise report and stop. |
|
|
68
72
|
|
|
69
|
-
|
|
70
|
-
agent-deck run <deck> --client <client> --cwd <dir> --prompt-file <feedback-file> --tools readonly --resume <sessionId> --detach
|
|
71
|
-
```
|
|
73
|
+
## Report
|
|
72
74
|
|
|
73
|
-
|
|
75
|
+
Report the `runId`, `sessionId`, tool profile, terminal state, and the result (or the failure) to the human. Do not report a host log path; the durable record is `get_run`.
|
|
74
76
|
|
|
75
77
|
### Corrections from a delegated run
|
|
76
78
|
- The party that observed and made the correction files it: the orchestrator files `propose_playbook_patch` on its own bound deck; the delegated session files only when a human corrects it directly.
|
|
77
|
-
- Evidence quotes the review gap as `user_feedback_excerpt` plus `runId`, `sessionId`, tool profile
|
|
79
|
+
- Evidence quotes the review gap as `user_feedback_excerpt` plus `runId`, `sessionId`, and tool profile; no secrets in evidence.
|
|
78
80
|
- Clearly general lesson: `update` with `add_item` (or `create` when no playbook covers it); not yet general: `signal_only`.
|
|
79
81
|
- Cross-deck: `create`/`signal_only` land on the caller's bound deck and `get_playbook` reads only that deck, so for a playbook on another deck file `signal_only` with the ids above.
|
|
80
82
|
|
|
81
83
|
## Hard rules
|
|
82
84
|
|
|
83
|
-
-
|
|
85
|
+
- Delegate only through Agent Deck MCP. Never run the Agent Deck command-line tool, call the host's loopback ports, inspect host processes, or install a second Agent Deck copy as a fallback. If MCP cannot do it, report and stop.
|
|
86
|
+
- Never pick or change the deck on your own; the user names it, and a switch needs human approval.
|
|
84
87
|
- Never raise the tool profile from `readonly` to `edit` on your own; only the brief owner does.
|
|
85
|
-
- No secrets in briefs or
|
|
86
|
-
- Report the `runId`, `sessionId`, tool profile, and log path back to the human.
|
|
88
|
+
- No secrets in briefs, prompts, or reports.
|
|
@@ -24,7 +24,7 @@ Treat setup as three separate layers: daemon health, host transport, then folder
|
|
|
24
24
|
that host.
|
|
25
25
|
4. Check the folder assignment reported by `agent-deck status`. If it is missing or legacy,
|
|
26
26
|
tell the user to run `agent-deck use <deck>` in that folder, then reload or retry MCP.
|
|
27
|
-
5. For delegation (`
|
|
27
|
+
5. For delegation (agents use the MCP `start_run` tool; the run executes on this host), the client CLI must also be installed and signed in on the host. Check `claude auth status`, `codex login status`, `cursor-agent status`, or `muse --version`; if missing, point the user to the official install docs ([Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup), [Codex](https://developers.openai.com/codex/cli), [Cursor CLI](https://cursor.com/docs/cli/installation); muse per its distribution) and its sign-in (`claude`, `codex login`, `cursor-agent login`, `muse login`).
|
|
28
28
|
6. If no deck exists (`agent-deck deck list`), the user creates one in the dashboard (`agent-deck open` → My Decks) or imports one: `agent-deck import <file>.agent-deck.json`.
|
|
29
29
|
7. Once transport and assignment are valid, use the session skill and require
|
|
30
30
|
`get_session_binding` followed by `get_bound_deck`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-deck/cli",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "Local MCP proxy — decks of tools, keys, and self-improving playbooks",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
@@ -40,8 +40,8 @@
|
|
|
40
40
|
"prepublishOnly": "node ../../scripts/pre-publish-check.mjs && npm run build"
|
|
41
41
|
},
|
|
42
42
|
"dependencies": {
|
|
43
|
-
"@agent-deck/backend": "^2.
|
|
44
|
-
"@agent-deck/shared": "^2.
|
|
43
|
+
"@agent-deck/backend": "^2.4.0",
|
|
44
|
+
"@agent-deck/shared": "^2.4.0",
|
|
45
45
|
"@anthropic-ai/claude-agent-sdk": "^0.3.296"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|