agent-dispatch 0.16.0__tar.gz → 0.18.0__tar.gz
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.
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/AGENTS.md +7 -2
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/CHANGELOG.md +93 -1
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/PKG-INFO +48 -11
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/README.md +47 -10
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/agents.example.yaml +6 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/pyproject.toml +1 -1
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/__init__.py +1 -1
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/cli.py +93 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/config.py +5 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/jobs.py +97 -16
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/models.py +17 -3
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/runner.py +272 -55
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/server.py +145 -45
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/usage.py +106 -1
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/conftest.py +7 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_cli.py +133 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_config.py +17 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_jobs.py +111 -1
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_models.py +9 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_runner.py +544 -25
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_server.py +446 -15
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_usage.py +106 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/.github/dependabot.yml +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/.github/workflows/ci.yml +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/.github/workflows/publish.yml +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/.gitignore +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/LICENSE +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/SECURITY.md +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/assets/mascot.png +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/scripts/check_install.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/cache.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/concurrency.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/progress.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/src/agent_dispatch/servers.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/__init__.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_cache.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_concurrency.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_progress.py +0 -0
- {agent_dispatch-0.16.0 → agent_dispatch-0.18.0}/tests/test_servers.py +0 -0
|
@@ -12,7 +12,7 @@ MCP server + CLI that lets Claude Code agents delegate tasks to agents in other
|
|
|
12
12
|
|------|------|
|
|
13
13
|
| `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
|
|
14
14
|
| `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread` with a shared process limit |
|
|
15
|
-
| `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome) + aggregation for `stats` and the `typical` block |
|
|
15
|
+
| `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome/tokens/model) + aggregation for `stats` and the `typical` block |
|
|
16
16
|
| `src/agent_dispatch/servers.py` | Registry of live `serve` processes and the version each one runs (`doctor` reads it) |
|
|
17
17
|
| `src/agent_dispatch/cli.py` | Click CLI: `init`, `add`, `update`, `remove`, `list`, `describe`, `test`, `doctor`, `jobs`, `job`, `cancel`, `gc`, `group` (add/list/inspect/update/remove), `serve` |
|
|
18
18
|
| `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `DispatchGroup`/`GroupMember`, `Settings`, `DispatchResult`) |
|
|
@@ -48,6 +48,8 @@ The autouse guard in `tests/conftest.py` rejects real Claude process launches wh
|
|
|
48
48
|
- `--session-id` and `--resume` conflict — never pass both to `claude`.
|
|
49
49
|
- Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
|
|
50
50
|
- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting. `mark_running` likewise refuses any job that isn't `pending`, so a stale or duplicate worker can't resurrect a finished one.
|
|
51
|
+
- **A running job's liveness is its file's mtime, kept fresh by a heartbeat, not by progress.** `_run_owned_job` starts a thread that calls `JobStore.touch` every `_JOB_HEARTBEAT_INTERVAL` (60 s), stops it in `finally`, and bounds it at the dispatch timeout + `_JOB_HEARTBEAT_GRACE` so a worker stuck past its own deadline still comes to look abandoned. Progress writes alone left a job silent inside one long tool call (a nested dispatch runs up to two hours) looking abandoned after an hour: `recover_stale` on any starting server failed it and `finish()` then refused the paid result. Tests that fake an abandoned running job must age the file as well as `started_at`.
|
|
52
|
+
- `JobStore.create` checks for an active job with the requested resume session ID while holding the lock used to publish the new record. It skips running jobs that meet the startup recovery check; a `pending` job holds the session until it runs, is cancelled, or passes the sweep bound (24x the running threshold), at which point `create` **fails** it rather than skipping it — a skipped job stays runnable and would resume the session beside its replacement. The conflict error names `dispatch_wait` / `dispatch_cancel` — never `dispatch_session`, which does not check the reservation. `dispatch_status`, `dispatch_wait`, and `fetch_result` without a result share the polling serializer. The stored job retains the full task, context, and result.
|
|
51
53
|
- "Is this group member missing?" has exactly one implementation: `DispatchConfig.unknown_group_members()`. Any new surface that lists or validates membership calls it instead of re-deriving the check.
|
|
52
54
|
- Cancelling a *running* job requires the in-memory registry (server.py): `_owned_jobs` records ownership **before** `mark_running`, `_running_procs` the Popen once spawned — a cancel landing between the two is still honored, and the late process is killed on registration. The job is marked `cancelled` **before** the subprocess is killed. A job record that is merely *unreadable* at spawn is not treated as terminal. Don't persist PIDs to disk (PID reuse after restart could kill an unrelated process).
|
|
53
55
|
- `max_budget_usd` is enforced **by the claude CLI** (`_build_command` passes `--max-budget-usd`): a run stopped at the cap comes back `is_error` with no `result` text, and `_build_error_result` turns it into `error_type="budget"` + `budget_exceeded=True` + a resumable `session_id`. `_apply_budget` is the *secondary*, post-hoc signal for an overshoot that didn't stop the run; it never fails a dispatch.
|
|
@@ -71,9 +73,12 @@ The autouse guard in `tests/conftest.py` rejects real Claude process launches wh
|
|
|
71
73
|
- **`--json` output must be valid JSON on the empty path too.** `stats --json` printed prose when the journal had no records — i.e. on a fresh install, which is exactly when a script first pipes it somewhere.
|
|
72
74
|
- **The usage journal is written by a decorator, not at each return.** `runner._journaled` wraps `dispatch`/`dispatch_stream` because each has a dozen early returns; instrumenting them one by one guarantees the next new return path goes unrecorded. It records the outermost call only (`_use_session_flag` is False on the stream's old-CLI retry, which would otherwise double-count one dispatch). It also swallows exceptions itself even though `usage.record` already does: the result in hand is billed, and the guarantee has to hold at the boundary that owns the damage rather than on another module's promise (`test_a_broken_journal_never_breaks_a_paid_dispatch` removes record()'s guard to prove it).
|
|
73
75
|
- **A journal record is one `O_APPEND` write under `PIPE_BUF`**, never a locked read-modify-write: the CLI and every running server share one file, and this user has 14+ servers alive. Every field is capped so the line cannot approach 4096 bytes. Rotation is an atomic rename at ~2 MB, two generations kept.
|
|
76
|
+
- **`total_cost_usd` is per SESSION on `--resume`** (claude ≥ 2.1.277; verified live on 2.1.322: $0.0798, then $0.0953 after a resume that cost $0.0155). `runner._call_cost` turns it into the call's own cost by subtracting `usage.session_total(session_id)` — the newest journal record for that `sid` (`cum`, or `cost` for a session's first call) — read **before** the spawn, and carries the reported cumulative figure as `cum` in the journal telemetry. Amounts cannot tell cumulative from per-call reporting, so the CLI **version** decides (`_cli_reports_session_totals`: `claude --version` ≥ 2.1.277, memoized per binary+mtime, probe failure = do not adjust; `tests/conftest.py` stubs it to True). It subtracts only when the reported total is a finite number ≥ the prior total within `_COST_EPSILON` (the journal rounds to 6 places — without the tolerance an unchanged total was charged whole again), and not at all when the session is unknown to the journal or `usage_log` is off: those keep the reported figure. `session_total` reads the live generation before `.1` (the other order loses the newest records to a concurrent rotation) and never takes `cost` from a record that has a `cum` key. Known limits, accepted: two processes resuming one session at once can both subtract the same baseline; a costless record in between (timeout) folds its spend into the next call — the sum stays right, the split does not. `_apply_budget` therefore judges the call, not the session. The streaming runner also resumes for `dispatch_async`, using the same pre-spawn baseline.
|
|
77
|
+
- **Token usage is journal-only.** `DispatchResult.token_usage` has `exclude=True`: never expose it in tool payloads or job files. `runner._token_usage` extracts `in`/`out`/`cr`/`cw` and the highest-cost `model` from CLI results, including failures; `_journaled` passes it to `usage.record`, which revalidates counts in `[0, 10**12)` and caps model names at 60 characters. Cache hits have no tokens. `stats` reports separate token sums, measured `records`, cache-read share, and model counts; text shows combined input/cache percentages plus output totals and each agent's most frequent model (`+N more` when needed). Old records remain valid, disk counts go through `as_float` plus plausibility bounds, and `_profile` must not grow.
|
|
74
78
|
- **Profiles are memoized on the journal's (path, size, mtime) and read a NARROWER tail than `stats`.** `list_agents`/`inspect_agent` run on the event-loop thread: a full 2 MB journal cost **24.8 ms** per discovery call at the 512 KB report window — 33x the config parse that 0.13.0 exists to have fixed. Now 3.3 ms cold, ~0 warm. Every profile consumer goes through `usage.profiles()`; never add a caller that re-parses per agent.
|
|
75
|
-
- **`usage_limit` is its own error type** (observed live: `You've hit your session limit · resets 6pm`). It is checked
|
|
79
|
+
- **`usage_limit` is its own error type** (observed live: `You've hit your session limit · resets 6pm`). It is checked before the permission patterns. Its hint names the model or period and reset time when present. A period phrase ("daily limit") counts only in Claude's own shapes — followed by "reached", "resets" or "· resets" (checked against code.claude.com/docs/en/errors; "exceeded" is Google's wording) — because the text is whatever the subprocess printed, and a third-party API's limit or a permission error mentioning one must not be answered with "wait for the reset". Text-classified errors attach their advisory through `_classification_hint`.
|
|
76
80
|
- **Server liveness is an advisory lock, not a PID.** `servers.register` holds an exclusive `flock` on `<config dir>/servers/<pid>.json` for the process lifetime; a reader that *takes* that lock owns a dead entry and deletes it. `os.kill(pid, 0)` would believe a recycled PID and would never notice a SIGKILLed server. Never close that fd (re-registering closes the old one first).
|
|
81
|
+
- **Startup trims are opt-in flags, never defaults.** `AgentConfig.skills` (default true; false → `--disable-slash-commands`) and `strict_mcp` (default false; true → `--strict-mcp-config`, plus `--mcp-config <dir>/.mcp.json` when that file exists) come from `runner._startup_trim_flags`, are sent on `--resume` too, and are pruned from YAML at their defaults. `--mcp-config` is variadic in the CLI: keep a flag right after its path. Mutation is CLI-only (`update --no-skills/--skills`, `--strict-mcp/--no-strict-mcp`); `doctor` probes the flags only when some agent uses them. Measured basis (claude 2.1.322): a new task text re-creates ~32k preamble tokens per dispatch; a stable `--append-system-prompt` does not help. A resumed session, by contrast, re-reads its preamble from cache: live, a follow-up via `dispatch_session` cost $0.005–0.017 against $0.089 for a fresh dispatch of the same agent.
|
|
77
82
|
- **The dispatch protocol goes in the system prompt, not the task.** `_build_system_prompt` (runner.py) renders the protocol (non-interactive, time/spend budget, lead with the outcome, trailing `STATUS:` line) plus the agent's `instructions`, and `_build_command` passes it as `--append-system-prompt` — on `--resume` too, since the CLI re-applies an appended prompt on every launch. `_build_prompt` (the `-p` text) is unchanged. Standing instructions and protocol settings are captured separately in `_cache_config_key`. The text always starts with a `##` header line so it can never be read as a flag. `settings.dispatch_protocol: false` turns the protocol off (for CLIs that predate the flag; `doctor` probes `claude --help` for it); per-agent `instructions` still go through when set.
|
|
78
83
|
- **`outcome` is lifted from the LAST line of the result** (`_split_outcome`), before JSON parsing, by the shared `_build_success_result` (the success-side twin of `_build_error_result` — both `dispatch` and `dispatch_stream` go through it) and by the plain-text fallback tier. A bare marker line is removed from `result`; a marker with a trailing reason stays. `outcome` never flips `success`; `partial`/`blocked` add a `hint` with the `dispatch_session(...)` continuation, after the denial hint. In JSON mode the protocol omits the STATUS instruction (the JSON footer governs), but a STATUS line that arrives anyway is still stripped so `parsed_result` survives.
|
|
79
84
|
- Remediation text is a contract: a hint that names a flag must name one that exists (`test_printed_budget_hint_is_a_runnable_command` feeds the printed flags back into the CLI). Run the command you print.
|
|
@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.18.0] - 2026-11-20
|
|
11
|
+
|
|
12
|
+
The background-continuation round: an async job can now continue a session,
|
|
13
|
+
join a group and hand back a reference instead of the full text, and polling a
|
|
14
|
+
job no longer returns the whole task and context on every call.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
- `dispatch_async(session_id=...)` continues an existing agent session in the
|
|
18
|
+
background (the streaming runner now passes `--resume`, with the same
|
|
19
|
+
per-call cost accounting as `dispatch_session`). A session holds at most one
|
|
20
|
+
pending or running job: a second `dispatch_async` for it returns `error` plus
|
|
21
|
+
`active_job_id`, and the error names the `dispatch_wait` / `dispatch_cancel`
|
|
22
|
+
calls for that job. The check and the new record are published under the
|
|
23
|
+
cross-process job lock. A running job whose start time and last file update
|
|
24
|
+
are both over an hour old no longer holds the session; a pending job older
|
|
25
|
+
than a day is failed and replaced (the bounds startup recovery already uses).
|
|
26
|
+
Limit: `dispatch_session` does not check this reservation — do not use it on
|
|
27
|
+
a session whose async job is still active.
|
|
28
|
+
- `group=` on `dispatch_async` and `dispatch_session`: membership is validated
|
|
29
|
+
before anything runs, and the group's `shared_context` goes before the
|
|
30
|
+
caller's context — the same string in the job record and in the prompt.
|
|
31
|
+
- `dispatch_async(return_ref=True)`: a successful job's `result` in
|
|
32
|
+
`dispatch_status` / `dispatch_wait` is `{ref, summary, session_id, ...}`
|
|
33
|
+
instead of the full text; `fetch_result(ref)` reads it. Failed jobs keep their
|
|
34
|
+
error and result inline.
|
|
35
|
+
- A `usage_limit` failure also carries its advice in `hint` (it stays in
|
|
36
|
+
`error` too), so a caller can act on it without parsing the error text.
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
- **Polling payload shape.** `dispatch_status`, `dispatch_wait` and
|
|
40
|
+
`fetch_result` on a job without a result return `task_preview` and
|
|
41
|
+
`context_preview` (first 120 characters, one line) instead of the full `task`
|
|
42
|
+
and `context`. The job file and `agent-dispatch job <id> --json` keep the
|
|
43
|
+
complete text. A caller that read `task` / `context` from these tools must
|
|
44
|
+
switch to the previews or to the CLI.
|
|
45
|
+
- The usage-limit hint names the limit Claude reported — a model
|
|
46
|
+
("Fable limit") or a period ("weekly limit") — and its reset time. It no
|
|
47
|
+
longer claims the limit is account-wide: a model limit is not.
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
- Model and period limits (`You've hit your Fable limit`, `Weekly limit
|
|
51
|
+
reached`, `5-hour limit reached ∙ resets 3pm`) were reported as `cli_error`;
|
|
52
|
+
they are `usage_limit` now. A period phrase counts only in the shapes Claude
|
|
53
|
+
prints (`… limit reached`, `… limit · resets …`, `… session limit resets …`),
|
|
54
|
+
so another service's `daily limit of 5000 requests reached` or `Daily Limit
|
|
55
|
+
Exceeded`, or `Permission denied while changing the daily limit`, is not
|
|
56
|
+
mistaken for it.
|
|
57
|
+
- A worker thread that cannot start fails its job instead of leaving it
|
|
58
|
+
`pending`.
|
|
59
|
+
- A running job whose agent stayed silent for over an hour — one long tool
|
|
60
|
+
call, such as a nested dispatch — looked abandoned: the next server to start
|
|
61
|
+
marked it failed, and the worker's result, already paid for, was then
|
|
62
|
+
refused. The worker now touches its job file once a minute, so liveness no
|
|
63
|
+
longer depends on the agent emitting progress.
|
|
64
|
+
- A task, context or group `shared_context` containing a NUL character raised
|
|
65
|
+
out of `dispatch` / `dispatch_session` / `dispatch_stream` instead of
|
|
66
|
+
returning a `cli_error` result.
|
|
67
|
+
|
|
68
|
+
## [0.17.0] - 2026-11-10
|
|
69
|
+
|
|
70
|
+
The cost round, driven by measurements on the live CLI rather than by reading
|
|
71
|
+
code: what a dispatch pays for before the agent does anything, and what the
|
|
72
|
+
journal was getting wrong about resumed sessions.
|
|
73
|
+
|
|
74
|
+
### Added
|
|
75
|
+
- Per-agent startup-context trims, both opt-in: `agent-dispatch update <name>
|
|
76
|
+
--no-skills` (sends `--disable-slash-commands`) and `--strict-mcp` (sends
|
|
77
|
+
`--strict-mcp-config` with the agent directory's own `.mcp.json`). A dispatch
|
|
78
|
+
with a new task re-writes the whole session preamble to the prompt cache —
|
|
79
|
+
about 32k tokens on claude 2.1.322 — and these cut the cold-start cost by 27%
|
|
80
|
+
and 11% (43% together) in a live measurement. `describe` and `inspect_agent`
|
|
81
|
+
show them when set; `doctor` checks that the installed CLI knows the flags.
|
|
82
|
+
Restart running sessions before enabling them: a server on an older release
|
|
83
|
+
drops keys it does not know the next time it saves the config.
|
|
84
|
+
- Usage journal records input, output, cache-read and cache-write tokens plus
|
|
85
|
+
the highest-cost model reported by the CLI, including failed and budget-stopped
|
|
86
|
+
runs. `agent-dispatch stats` shows token totals, cache percentages and each
|
|
87
|
+
agent's most frequent model; `--json` includes counts and measurement coverage.
|
|
88
|
+
Token metadata stays out of tool responses, job files and discovery profiles.
|
|
89
|
+
|
|
90
|
+
### Fixed
|
|
91
|
+
- A resumed session's cost was counted again on every `dispatch_session`.
|
|
92
|
+
Since claude 2.1.277 `total_cost_usd` covers the whole session on `--resume`;
|
|
93
|
+
the result and the journal now carry the call's own cost (the difference from
|
|
94
|
+
the session's last journaled total), so `stats` no longer overstates spend and
|
|
95
|
+
a cheap follow-up no longer raises `budget_exceeded` on the session's history.
|
|
96
|
+
Sessions the journal has not seen, and runs with `usage_log: false`, keep the
|
|
97
|
+
reported figure.
|
|
98
|
+
- `return_ref` payloads dropped `budget_exceeded`.
|
|
99
|
+
|
|
10
100
|
## [0.16.0] - 2026-09-30
|
|
11
101
|
|
|
12
102
|
The process-control round. One concurrency limit now covers every dispatch
|
|
@@ -906,7 +996,9 @@ cache bounding, and stale-job recovery.
|
|
|
906
996
|
- Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
|
|
907
997
|
commit SHAs for supply-chain integrity.
|
|
908
998
|
|
|
909
|
-
[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.
|
|
999
|
+
[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.18.0...HEAD
|
|
1000
|
+
[0.18.0]: https://github.com/ginkida/agent-dispatch/compare/v0.17.0...v0.18.0
|
|
1001
|
+
[0.17.0]: https://github.com/ginkida/agent-dispatch/compare/v0.16.0...v0.17.0
|
|
910
1002
|
[0.16.0]: https://github.com/ginkida/agent-dispatch/compare/v0.15.1...v0.16.0
|
|
911
1003
|
[0.15.1]: https://github.com/ginkida/agent-dispatch/compare/v0.15.0...v0.15.1
|
|
912
1004
|
[0.15.0]: https://github.com/ginkida/agent-dispatch/compare/v0.14.0...v0.15.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: agent-dispatch
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.18.0
|
|
4
4
|
Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
|
|
5
5
|
Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
|
|
6
6
|
Project-URL: Repository, https://github.com/ginkida/agent-dispatch
|
|
@@ -179,7 +179,7 @@ Members reference agents by name; membership is many-to-many (a shared gateway c
|
|
|
179
179
|
|
|
180
180
|
**`inspect_group(name)`** — one group's full brief: `description`, the complete `shared_context`, and the member list. For a deep dive on a specific member, call `inspect_agent(member)` — `inspect_group` deliberately stays a cheap membership readout.
|
|
181
181
|
|
|
182
|
-
|
|
182
|
+
Pass `group=` to `dispatch`, `dispatch_session`, `dispatch_async`, or an item in `dispatch_parallel`. The agent must be a member of the group. The group’s `shared_context` goes before the caller’s context.
|
|
183
183
|
|
|
184
184
|
```python
|
|
185
185
|
# From the shop-web codebase, hand the deploy to the infra gateway.
|
|
@@ -246,7 +246,7 @@ dispatch(
|
|
|
246
246
|
}
|
|
247
247
|
```
|
|
248
248
|
|
|
249
|
-
**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (
|
|
249
|
+
**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (Claude reached a usage limit), `cli_error` (other failures). Permission, budget, usage-limit and timeout errors include an actionable hint.
|
|
250
250
|
|
|
251
251
|
**Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
|
|
252
252
|
|
|
@@ -301,6 +301,8 @@ Check container logs for recent errors related to the scheduler service
|
|
|
301
301
|
|
|
302
302
|
That last line is lifted out of `result` into **`outcome`** — the agent's own verdict, deterministic to check: `"done"` means complete; `"partial"` / `"blocked"` mean the agent says the work is unfinished, the result names what is missing, and a `hint` spells out the continuation (usually `dispatch_session(..., session_id=...)`). Read `outcome` before reading the text. It never flips `success`, `partial` / `blocked` results are **not cached**, and a `dispatch_parallel(..., aggregate=...)` labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (`settings.dispatch_protocol: false`), `response_format="json"` was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
|
|
303
303
|
|
|
304
|
+
**Startup cost.** Each dispatch is a fresh `claude` session, and a session's preamble — the project's `CLAUDE.md`, the skill listing, MCP server instructions and tool names — is written to the prompt cache again for every new task text (the task sits in front of it, so two different tasks share none of it). Measured on claude 2.1.322 in a gateway directory: ~32k tokens per dispatch before the agent does anything, which is most of what a short run costs. Two opt-in per-agent switches trim it — `agent-dispatch update <name> --no-skills` (no skill/command listing, user-level skills included: −27% in that measurement) and `--strict-mcp` (only the directory's own `.mcp.json`, no user-scope servers or connectors: −11%; the agent then cannot dispatch others, and loses any tool it got from a user-scope server). Check what an agent actually uses before turning either on; `--skills` / `--no-strict-mcp` undo them. A follow-up to the same agent is the opposite case: `dispatch_session` with the `session_id` from the previous result re-reads that preamble from cache (measured: $0.005–0.017 per follow-up against $0.089 for a fresh dispatch), so continue a session rather than re-dispatching when the question builds on the last answer. The larger levers stay outside this tool: a cheaper `model` for gateway agents and a shorter agent `CLAUDE.md`.
|
|
305
|
+
|
|
304
306
|
**Standing orders.** Per-agent `instructions` (set via `add_agent` / `update_agent` or `agent-dispatch update <name> --instructions "..."`) follow the protocol in the same system prompt on **every** dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike `context`, which is per call, and unlike the project's own `CLAUDE.md`, which is written for an interactive session, these are the rules for *being dispatched*.
|
|
305
307
|
|
|
306
308
|
```json
|
|
@@ -328,6 +330,7 @@ Multi-turn: continue a conversation with an agent. First call starts a session,
|
|
|
328
330
|
| `caller` | string | no | Who is dispatching |
|
|
329
331
|
| `goal` | string | no | Broader objective |
|
|
330
332
|
| `timeout_seconds` | int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
|
|
333
|
+
| `group` | string | no | Require group membership and prepend the group's `shared_context` to `context` |
|
|
331
334
|
|
|
332
335
|
`dispatch_session` is also the **timeout recovery path**: a timed-out `dispatch` returns a `session_id` — pass it here with `task="Continue where you left off"` to salvage the partial work instead of restarting.
|
|
333
336
|
|
|
@@ -392,7 +395,7 @@ Disconnecting or cancelling the tool call discards pending notifications and
|
|
|
392
395
|
stops buffering new ones. The worker still holds its concurrency slot until it
|
|
393
396
|
finishes.
|
|
394
397
|
|
|
395
|
-
|
|
398
|
+
`dispatch_stream` accepts `agent`, `task`, `context`, `caller`, `goal`, `response_format`, and `timeout_seconds`.
|
|
396
399
|
|
|
397
400
|
### `dispatch_dialogue`
|
|
398
401
|
|
|
@@ -490,10 +493,17 @@ fetch_result(ref="8f3a...e1", max_chars=2000) -> truncated, plus {"truncated":
|
|
|
490
493
|
```
|
|
491
494
|
|
|
492
495
|
Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
|
|
496
|
+
If the job has yet to produce a result, `fetch_result` returns the same snapshot as `dispatch_status`.
|
|
493
497
|
|
|
494
498
|
### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_cancel`, `dispatch_jobs`, `dispatch_gc`
|
|
495
499
|
|
|
496
|
-
|
|
500
|
+
Async dispatch returns a `job_id` immediately. It accepts `agent`, `task`, `context`, `caller`, `goal`, `response_format`, and `timeout_seconds`, plus the following optional parameters. Async results bypass the result cache.
|
|
501
|
+
|
|
502
|
+
| Parameter | Type | Default | Description |
|
|
503
|
+
|-----------|------|---------|-------------|
|
|
504
|
+
| `group` | string | `""` | Require group membership and prepend the group's `shared_context` to `context`. An unknown group or non-member is rejected before creating a job. |
|
|
505
|
+
| `session_id` | string | `""` | Continue an existing session for the same agent. A conflict returns `error` and `active_job_id`. The error gives the job's status and age and names the `dispatch_wait` / `dispatch_cancel` calls for that job. `dispatch_session` does not check this reservation, so do not use it to get around a busy session. |
|
|
506
|
+
| `return_ref` | bool | `False` | On success, `dispatch_status` and `dispatch_wait` return `result.ref` and `result.summary` in place of `result.result`. Call `fetch_result(ref)` for the full text. Failed jobs retain their error and result. |
|
|
497
507
|
|
|
498
508
|
```
|
|
499
509
|
// 1. fire and forget (timeout_seconds= works here too for known-long tasks)
|
|
@@ -503,17 +513,23 @@ dispatch_async(agent="infra", task="audit every container log for OOM kills toda
|
|
|
503
513
|
// 2. do other work, then check progress (non-blocking)
|
|
504
514
|
// `progress` is a rolling tail of what the agent is doing right now
|
|
505
515
|
dispatch_status(job_id="8f3a...e1")
|
|
506
|
-
-> {"id": "8f3a...e1", "status": "running", "
|
|
516
|
+
-> {"id": "8f3a...e1", "status": "running", "task_preview": "audit every container log...",
|
|
517
|
+
"started_at": 1730000123.4,
|
|
507
518
|
"progress": ["Using tool: Bash", "Scanning container logs for OOM events..."], ...}
|
|
508
519
|
|
|
509
520
|
// 3. or block until done (timeout_seconds default: 60, capped at 3600)
|
|
510
521
|
dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
|
|
511
|
-
-> {"id": "8f3a...e1", "status": "done",
|
|
522
|
+
-> {"id": "8f3a...e1", "status": "done",
|
|
523
|
+
"result": {"agent": "infra", "success": true, "session_id": "sess-abc", ...}}
|
|
512
524
|
|
|
513
|
-
// If the timeout fires, the job keeps running
|
|
525
|
+
// If the timeout fires, the job keeps running. Call dispatch_wait again with the same job_id.
|
|
514
526
|
-> {"id": "...", "status": "running", "timed_out_waiting": true}
|
|
515
527
|
```
|
|
516
528
|
|
|
529
|
+
Both polling tools show one-line previews of the first 120 characters as `task_preview` and, when a context was supplied or added by a group, `context_preview`. The job file and `agent-dispatch job <id> --json` retain the complete task and context. Use the completed job's `result.session_id` for a follow-up with `dispatch_async` or `dispatch_session`.
|
|
530
|
+
|
|
531
|
+
Async continuation skips a stale running job when its start time and last file update are both at least an hour old; a pending job older than a day is marked failed and replaced. A live worker touches its job file once a minute, so a job whose agent is silent inside one long tool call is not mistaken for an abandoned one.
|
|
532
|
+
|
|
517
533
|
`dispatch_cancel(job_id)` cancels a **pending** job, and also kills a **running** job's `claude` process group when the job was started by the same server instance (the job is marked `cancelled` first, so the worker's trailing write can't undo it; partial work is lost but the progress tail is preserved). On POSIX, descendants in that process group are killed too, releasing inherited pipes and the concurrency slot. A cancel that lands after the job was claimed but before its process spawned is honored too: the process is killed as soon as it starts. A compatibility retry that races cancellation is killed when it registers. A running job started by a *previous* server run can't be killed safely and is left to finish. The response carries an `outcome` of `cancelled`, `cancelled_running`, `running` (not owned by this server), `already_terminal`, or `not_found`.
|
|
518
534
|
|
|
519
535
|
Async workers run with streaming under the hood: the job file keeps a rolling tail (last 20 lines, ~1 write/sec) of assistant text and tool-use events. `dispatch_status` shows it as `progress` while the job runs and keeps it afterwards as a post-mortem trace; `dispatch_jobs` shows `last_progress` for running jobs.
|
|
@@ -556,7 +572,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
|
|
|
556
572
|
| `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
|
|
557
573
|
| `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
|
|
558
574
|
| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
|
|
559
|
-
| `usage_limit` |
|
|
575
|
+
| `usage_limit` | Claude reached a usage limit, including model-specific limits and time windows | Wait for the reset before retrying. The `hint` and `error` include the model or period and reset time when Claude reports them. If this recurs under load, lower `settings.max_concurrency`. |
|
|
560
576
|
| `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
|
|
561
577
|
|
|
562
578
|
Three soft signals that arrive with `success: true`:
|
|
@@ -587,6 +603,8 @@ agents:
|
|
|
587
603
|
- deploy_debug
|
|
588
604
|
risky_capabilities: # high-risk labels, surfaced for visibility
|
|
589
605
|
- restart_services
|
|
606
|
+
# skills: false # no skill/command listing at startup (cheaper dispatches)
|
|
607
|
+
# strict_mcp: true # load only this directory's .mcp.json, no user-scope MCP servers
|
|
590
608
|
# instructions: | # standing orders, appended to the system prompt on every dispatch
|
|
591
609
|
# Read-only: never restart or redeploy unless the task says so.
|
|
592
610
|
# Quote exact log lines with timestamps.
|
|
@@ -643,7 +661,11 @@ Config is reloaded on every tool call — add agents without restarting.
|
|
|
643
661
|
|
|
644
662
|
Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
|
|
645
663
|
(override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
|
|
646
|
-
turns, `outcome`, error type, caller
|
|
664
|
+
turns, `outcome`, error type, caller, plus token counts and the model when the
|
|
665
|
+
CLI reports them. Token fields are `in` (uncached input), `out` (output),
|
|
666
|
+
`cr` (cache read), and `cw` (cache write). `model` is the highest-cost model
|
|
667
|
+
in that dispatch's `modelUsage` (first on ties or when no cost is reported).
|
|
668
|
+
Cache hits are recorded too, flagged
|
|
647
669
|
`cached`, so the report can show what the cache saves.
|
|
648
670
|
|
|
649
671
|
```console
|
|
@@ -651,18 +673,33 @@ $ agent-dispatch stats --days 7
|
|
|
651
673
|
Usage (last 7 day(s))
|
|
652
674
|
dispatches: 33, 1 served from cache
|
|
653
675
|
spend: $13.0390
|
|
676
|
+
tokens: in 1.2M (cache read 62%, cache write 35%), out 310k
|
|
654
677
|
duration: median 87s, p90 2m40s, max 10m00s
|
|
655
678
|
outcomes: blocked 1, done 27, partial 3
|
|
656
679
|
failures: timeout 1, usage_limit 1
|
|
657
680
|
|
|
658
681
|
Per agent
|
|
659
682
|
analytic 18 runs $ 8.9441 median 2m04s p90 2m51s
|
|
683
|
+
tokens: in 800k (cache read 62%, cache write 35%), out 210k
|
|
684
|
+
model: claude-fable-5-2 +1 more
|
|
660
685
|
done 15, partial 3
|
|
661
686
|
gitlab 12 runs $ 3.7949 median 60s p90 86s
|
|
687
|
+
tokens: in 400k (cache read 62%, cache write 35%), out 100k
|
|
688
|
+
model: claude-fable-5-2
|
|
662
689
|
done 12 | 1 cached
|
|
663
690
|
```
|
|
664
691
|
|
|
665
692
|
`--agent NAME` narrows it, `--json` emits the same report as JSON.
|
|
693
|
+
The text's `in` includes uncached input, cache reads, and cache writes; its
|
|
694
|
+
percentages use that combined input. JSON keeps those counts separate in
|
|
695
|
+
`tokens: {input, output, cache_read, cache_write, records}`, adds
|
|
696
|
+
`cache_read_share` rounded to three decimals when total input is nonzero,
|
|
697
|
+
and counts dispatches by primary model in `models`. `records` counts live
|
|
698
|
+
dispatches with valid token measurements; older records and cache hits do
|
|
699
|
+
not dilute the share. Each agent's text shows its most frequent model and
|
|
700
|
+
how many other models were recorded. Runs that fail or reach the spend cap
|
|
701
|
+
still contribute their reported usage. Token telemetry is journal-only:
|
|
702
|
+
tool responses, job files, and discovery's `typical` block stay compact.
|
|
666
703
|
|
|
667
704
|
The journal is what makes three other things work: the `typical` block in
|
|
668
705
|
`list_agents` / `inspect_agent`, the timeout error naming a value derived from
|
|
@@ -776,7 +813,7 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
|
|
|
776
813
|
|---------|-------------|
|
|
777
814
|
| `agent-dispatch init` | Create config + register MCP server with Claude Code |
|
|
778
815
|
| `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
|
|
779
|
-
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
|
|
816
|
+
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, `--no-skills`, `--strict-mcp`, etc.) |
|
|
780
817
|
| `agent-dispatch remove <name>` | Remove an agent |
|
|
781
818
|
| `agent-dispatch list` | List agents with health status and permissions |
|
|
782
819
|
| `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
|
|
@@ -149,7 +149,7 @@ Members reference agents by name; membership is many-to-many (a shared gateway c
|
|
|
149
149
|
|
|
150
150
|
**`inspect_group(name)`** — one group's full brief: `description`, the complete `shared_context`, and the member list. For a deep dive on a specific member, call `inspect_agent(member)` — `inspect_group` deliberately stays a cheap membership readout.
|
|
151
151
|
|
|
152
|
-
|
|
152
|
+
Pass `group=` to `dispatch`, `dispatch_session`, `dispatch_async`, or an item in `dispatch_parallel`. The agent must be a member of the group. The group’s `shared_context` goes before the caller’s context.
|
|
153
153
|
|
|
154
154
|
```python
|
|
155
155
|
# From the shop-web codebase, hand the deploy to the infra gateway.
|
|
@@ -216,7 +216,7 @@ dispatch(
|
|
|
216
216
|
}
|
|
217
217
|
```
|
|
218
218
|
|
|
219
|
-
**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (
|
|
219
|
+
**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (Claude reached a usage limit), `cli_error` (other failures). Permission, budget, usage-limit and timeout errors include an actionable hint.
|
|
220
220
|
|
|
221
221
|
**Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
|
|
222
222
|
|
|
@@ -271,6 +271,8 @@ Check container logs for recent errors related to the scheduler service
|
|
|
271
271
|
|
|
272
272
|
That last line is lifted out of `result` into **`outcome`** — the agent's own verdict, deterministic to check: `"done"` means complete; `"partial"` / `"blocked"` mean the agent says the work is unfinished, the result names what is missing, and a `hint` spells out the continuation (usually `dispatch_session(..., session_id=...)`). Read `outcome` before reading the text. It never flips `success`, `partial` / `blocked` results are **not cached**, and a `dispatch_parallel(..., aggregate=...)` labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (`settings.dispatch_protocol: false`), `response_format="json"` was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
|
|
273
273
|
|
|
274
|
+
**Startup cost.** Each dispatch is a fresh `claude` session, and a session's preamble — the project's `CLAUDE.md`, the skill listing, MCP server instructions and tool names — is written to the prompt cache again for every new task text (the task sits in front of it, so two different tasks share none of it). Measured on claude 2.1.322 in a gateway directory: ~32k tokens per dispatch before the agent does anything, which is most of what a short run costs. Two opt-in per-agent switches trim it — `agent-dispatch update <name> --no-skills` (no skill/command listing, user-level skills included: −27% in that measurement) and `--strict-mcp` (only the directory's own `.mcp.json`, no user-scope servers or connectors: −11%; the agent then cannot dispatch others, and loses any tool it got from a user-scope server). Check what an agent actually uses before turning either on; `--skills` / `--no-strict-mcp` undo them. A follow-up to the same agent is the opposite case: `dispatch_session` with the `session_id` from the previous result re-reads that preamble from cache (measured: $0.005–0.017 per follow-up against $0.089 for a fresh dispatch), so continue a session rather than re-dispatching when the question builds on the last answer. The larger levers stay outside this tool: a cheaper `model` for gateway agents and a shorter agent `CLAUDE.md`.
|
|
275
|
+
|
|
274
276
|
**Standing orders.** Per-agent `instructions` (set via `add_agent` / `update_agent` or `agent-dispatch update <name> --instructions "..."`) follow the protocol in the same system prompt on **every** dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike `context`, which is per call, and unlike the project's own `CLAUDE.md`, which is written for an interactive session, these are the rules for *being dispatched*.
|
|
275
277
|
|
|
276
278
|
```json
|
|
@@ -298,6 +300,7 @@ Multi-turn: continue a conversation with an agent. First call starts a session,
|
|
|
298
300
|
| `caller` | string | no | Who is dispatching |
|
|
299
301
|
| `goal` | string | no | Broader objective |
|
|
300
302
|
| `timeout_seconds` | int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
|
|
303
|
+
| `group` | string | no | Require group membership and prepend the group's `shared_context` to `context` |
|
|
301
304
|
|
|
302
305
|
`dispatch_session` is also the **timeout recovery path**: a timed-out `dispatch` returns a `session_id` — pass it here with `task="Continue where you left off"` to salvage the partial work instead of restarting.
|
|
303
306
|
|
|
@@ -362,7 +365,7 @@ Disconnecting or cancelling the tool call discards pending notifications and
|
|
|
362
365
|
stops buffering new ones. The worker still holds its concurrency slot until it
|
|
363
366
|
finishes.
|
|
364
367
|
|
|
365
|
-
|
|
368
|
+
`dispatch_stream` accepts `agent`, `task`, `context`, `caller`, `goal`, `response_format`, and `timeout_seconds`.
|
|
366
369
|
|
|
367
370
|
### `dispatch_dialogue`
|
|
368
371
|
|
|
@@ -460,10 +463,17 @@ fetch_result(ref="8f3a...e1", max_chars=2000) -> truncated, plus {"truncated":
|
|
|
460
463
|
```
|
|
461
464
|
|
|
462
465
|
Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
|
|
466
|
+
If the job has yet to produce a result, `fetch_result` returns the same snapshot as `dispatch_status`.
|
|
463
467
|
|
|
464
468
|
### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_cancel`, `dispatch_jobs`, `dispatch_gc`
|
|
465
469
|
|
|
466
|
-
|
|
470
|
+
Async dispatch returns a `job_id` immediately. It accepts `agent`, `task`, `context`, `caller`, `goal`, `response_format`, and `timeout_seconds`, plus the following optional parameters. Async results bypass the result cache.
|
|
471
|
+
|
|
472
|
+
| Parameter | Type | Default | Description |
|
|
473
|
+
|-----------|------|---------|-------------|
|
|
474
|
+
| `group` | string | `""` | Require group membership and prepend the group's `shared_context` to `context`. An unknown group or non-member is rejected before creating a job. |
|
|
475
|
+
| `session_id` | string | `""` | Continue an existing session for the same agent. A conflict returns `error` and `active_job_id`. The error gives the job's status and age and names the `dispatch_wait` / `dispatch_cancel` calls for that job. `dispatch_session` does not check this reservation, so do not use it to get around a busy session. |
|
|
476
|
+
| `return_ref` | bool | `False` | On success, `dispatch_status` and `dispatch_wait` return `result.ref` and `result.summary` in place of `result.result`. Call `fetch_result(ref)` for the full text. Failed jobs retain their error and result. |
|
|
467
477
|
|
|
468
478
|
```
|
|
469
479
|
// 1. fire and forget (timeout_seconds= works here too for known-long tasks)
|
|
@@ -473,17 +483,23 @@ dispatch_async(agent="infra", task="audit every container log for OOM kills toda
|
|
|
473
483
|
// 2. do other work, then check progress (non-blocking)
|
|
474
484
|
// `progress` is a rolling tail of what the agent is doing right now
|
|
475
485
|
dispatch_status(job_id="8f3a...e1")
|
|
476
|
-
-> {"id": "8f3a...e1", "status": "running", "
|
|
486
|
+
-> {"id": "8f3a...e1", "status": "running", "task_preview": "audit every container log...",
|
|
487
|
+
"started_at": 1730000123.4,
|
|
477
488
|
"progress": ["Using tool: Bash", "Scanning container logs for OOM events..."], ...}
|
|
478
489
|
|
|
479
490
|
// 3. or block until done (timeout_seconds default: 60, capped at 3600)
|
|
480
491
|
dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
|
|
481
|
-
-> {"id": "8f3a...e1", "status": "done",
|
|
492
|
+
-> {"id": "8f3a...e1", "status": "done",
|
|
493
|
+
"result": {"agent": "infra", "success": true, "session_id": "sess-abc", ...}}
|
|
482
494
|
|
|
483
|
-
// If the timeout fires, the job keeps running
|
|
495
|
+
// If the timeout fires, the job keeps running. Call dispatch_wait again with the same job_id.
|
|
484
496
|
-> {"id": "...", "status": "running", "timed_out_waiting": true}
|
|
485
497
|
```
|
|
486
498
|
|
|
499
|
+
Both polling tools show one-line previews of the first 120 characters as `task_preview` and, when a context was supplied or added by a group, `context_preview`. The job file and `agent-dispatch job <id> --json` retain the complete task and context. Use the completed job's `result.session_id` for a follow-up with `dispatch_async` or `dispatch_session`.
|
|
500
|
+
|
|
501
|
+
Async continuation skips a stale running job when its start time and last file update are both at least an hour old; a pending job older than a day is marked failed and replaced. A live worker touches its job file once a minute, so a job whose agent is silent inside one long tool call is not mistaken for an abandoned one.
|
|
502
|
+
|
|
487
503
|
`dispatch_cancel(job_id)` cancels a **pending** job, and also kills a **running** job's `claude` process group when the job was started by the same server instance (the job is marked `cancelled` first, so the worker's trailing write can't undo it; partial work is lost but the progress tail is preserved). On POSIX, descendants in that process group are killed too, releasing inherited pipes and the concurrency slot. A cancel that lands after the job was claimed but before its process spawned is honored too: the process is killed as soon as it starts. A compatibility retry that races cancellation is killed when it registers. A running job started by a *previous* server run can't be killed safely and is left to finish. The response carries an `outcome` of `cancelled`, `cancelled_running`, `running` (not owned by this server), `already_terminal`, or `not_found`.
|
|
488
504
|
|
|
489
505
|
Async workers run with streaming under the hood: the job file keeps a rolling tail (last 20 lines, ~1 write/sec) of assistant text and tool-use events. `dispatch_status` shows it as `progress` while the job runs and keeps it afterwards as a post-mortem trace; `dispatch_jobs` shows `last_progress` for running jobs.
|
|
@@ -526,7 +542,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
|
|
|
526
542
|
| `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
|
|
527
543
|
| `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
|
|
528
544
|
| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
|
|
529
|
-
| `usage_limit` |
|
|
545
|
+
| `usage_limit` | Claude reached a usage limit, including model-specific limits and time windows | Wait for the reset before retrying. The `hint` and `error` include the model or period and reset time when Claude reports them. If this recurs under load, lower `settings.max_concurrency`. |
|
|
530
546
|
| `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
|
|
531
547
|
|
|
532
548
|
Three soft signals that arrive with `success: true`:
|
|
@@ -557,6 +573,8 @@ agents:
|
|
|
557
573
|
- deploy_debug
|
|
558
574
|
risky_capabilities: # high-risk labels, surfaced for visibility
|
|
559
575
|
- restart_services
|
|
576
|
+
# skills: false # no skill/command listing at startup (cheaper dispatches)
|
|
577
|
+
# strict_mcp: true # load only this directory's .mcp.json, no user-scope MCP servers
|
|
560
578
|
# instructions: | # standing orders, appended to the system prompt on every dispatch
|
|
561
579
|
# Read-only: never restart or redeploy unless the task says so.
|
|
562
580
|
# Quote exact log lines with timestamps.
|
|
@@ -613,7 +631,11 @@ Config is reloaded on every tool call — add agents without restarting.
|
|
|
613
631
|
|
|
614
632
|
Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
|
|
615
633
|
(override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
|
|
616
|
-
turns, `outcome`, error type, caller
|
|
634
|
+
turns, `outcome`, error type, caller, plus token counts and the model when the
|
|
635
|
+
CLI reports them. Token fields are `in` (uncached input), `out` (output),
|
|
636
|
+
`cr` (cache read), and `cw` (cache write). `model` is the highest-cost model
|
|
637
|
+
in that dispatch's `modelUsage` (first on ties or when no cost is reported).
|
|
638
|
+
Cache hits are recorded too, flagged
|
|
617
639
|
`cached`, so the report can show what the cache saves.
|
|
618
640
|
|
|
619
641
|
```console
|
|
@@ -621,18 +643,33 @@ $ agent-dispatch stats --days 7
|
|
|
621
643
|
Usage (last 7 day(s))
|
|
622
644
|
dispatches: 33, 1 served from cache
|
|
623
645
|
spend: $13.0390
|
|
646
|
+
tokens: in 1.2M (cache read 62%, cache write 35%), out 310k
|
|
624
647
|
duration: median 87s, p90 2m40s, max 10m00s
|
|
625
648
|
outcomes: blocked 1, done 27, partial 3
|
|
626
649
|
failures: timeout 1, usage_limit 1
|
|
627
650
|
|
|
628
651
|
Per agent
|
|
629
652
|
analytic 18 runs $ 8.9441 median 2m04s p90 2m51s
|
|
653
|
+
tokens: in 800k (cache read 62%, cache write 35%), out 210k
|
|
654
|
+
model: claude-fable-5-2 +1 more
|
|
630
655
|
done 15, partial 3
|
|
631
656
|
gitlab 12 runs $ 3.7949 median 60s p90 86s
|
|
657
|
+
tokens: in 400k (cache read 62%, cache write 35%), out 100k
|
|
658
|
+
model: claude-fable-5-2
|
|
632
659
|
done 12 | 1 cached
|
|
633
660
|
```
|
|
634
661
|
|
|
635
662
|
`--agent NAME` narrows it, `--json` emits the same report as JSON.
|
|
663
|
+
The text's `in` includes uncached input, cache reads, and cache writes; its
|
|
664
|
+
percentages use that combined input. JSON keeps those counts separate in
|
|
665
|
+
`tokens: {input, output, cache_read, cache_write, records}`, adds
|
|
666
|
+
`cache_read_share` rounded to three decimals when total input is nonzero,
|
|
667
|
+
and counts dispatches by primary model in `models`. `records` counts live
|
|
668
|
+
dispatches with valid token measurements; older records and cache hits do
|
|
669
|
+
not dilute the share. Each agent's text shows its most frequent model and
|
|
670
|
+
how many other models were recorded. Runs that fail or reach the spend cap
|
|
671
|
+
still contribute their reported usage. Token telemetry is journal-only:
|
|
672
|
+
tool responses, job files, and discovery's `typical` block stay compact.
|
|
636
673
|
|
|
637
674
|
The journal is what makes three other things work: the `typical` block in
|
|
638
675
|
`list_agents` / `inspect_agent`, the timeout error naming a value derived from
|
|
@@ -746,7 +783,7 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
|
|
|
746
783
|
|---------|-------------|
|
|
747
784
|
| `agent-dispatch init` | Create config + register MCP server with Claude Code |
|
|
748
785
|
| `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
|
|
749
|
-
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
|
|
786
|
+
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, `--no-skills`, `--strict-mcp`, etc.) |
|
|
750
787
|
| `agent-dispatch remove <name>` | Remove an agent |
|
|
751
788
|
| `agent-dispatch list` | List agents with health status and permissions |
|
|
752
789
|
| `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
|
|
@@ -16,6 +16,12 @@ agents:
|
|
|
16
16
|
instructions: |
|
|
17
17
|
Read-only unless the task explicitly asks to restart or redeploy.
|
|
18
18
|
Quote exact log lines with timestamps; never paraphrase an error.
|
|
19
|
+
# Startup-context trims: every dispatch pays for the session preamble, so
|
|
20
|
+
# drop what this agent never uses. `skills: false` removes the skill/command
|
|
21
|
+
# listing; `strict_mcp: true` loads only this directory's .mcp.json (no
|
|
22
|
+
# user-scope MCP servers — the agent can no longer dispatch others).
|
|
23
|
+
skills: false
|
|
24
|
+
strict_mcp: true
|
|
19
25
|
|
|
20
26
|
# Analytics gateway — a browser + Yandex Metrica agent, no codebase of its own.
|
|
21
27
|
# Its value is its MCP servers + access, not its source. Shared across groups.
|