agent-dispatch 0.15.1__tar.gz → 0.17.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.17.0/.github/workflows/ci.yml +58 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.gitignore +3 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/AGENTS.md +20 -12
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/CHANGELOG.md +143 -1
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/PKG-INFO +98 -20
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/README.md +97 -19
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/agents.example.yaml +7 -1
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/pyproject.toml +7 -1
- agent_dispatch-0.17.0/scripts/check_install.py +116 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/__init__.py +1 -1
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/cache.py +20 -9
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/cli.py +314 -67
- agent_dispatch-0.17.0/src/agent_dispatch/concurrency.py +158 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/config.py +5 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/jobs.py +74 -31
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/models.py +48 -5
- agent_dispatch-0.17.0/src/agent_dispatch/progress.py +43 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/runner.py +592 -52
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/server.py +286 -160
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/servers.py +5 -3
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/usage.py +133 -8
- agent_dispatch-0.17.0/tests/conftest.py +136 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_cli.py +559 -7
- agent_dispatch-0.17.0/tests/test_concurrency.py +277 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_config.py +17 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_jobs.py +241 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_models.py +46 -1
- agent_dispatch-0.17.0/tests/test_progress.py +44 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_runner.py +949 -80
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_server.py +706 -11
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_usage.py +151 -0
- agent_dispatch-0.15.1/.coverage +0 -0
- agent_dispatch-0.15.1/.github/workflows/ci.yml +0 -34
- agent_dispatch-0.15.1/tests/conftest.py +0 -68
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.github/dependabot.yml +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.github/workflows/publish.yml +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/LICENSE +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/SECURITY.md +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/assets/mascot.png +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/__init__.py +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_cache.py +0 -0
- {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_servers.py +0 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
# Least privilege: CI only needs to read the repo.
|
|
10
|
+
permissions:
|
|
11
|
+
contents: read
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
test:
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
strategy:
|
|
17
|
+
matrix:
|
|
18
|
+
python-version: ["3.10", "3.11", "3.12", "3.13"]
|
|
19
|
+
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
|
22
|
+
|
|
23
|
+
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
|
24
|
+
with:
|
|
25
|
+
python-version: ${{ matrix.python-version }}
|
|
26
|
+
|
|
27
|
+
- name: Install dependencies
|
|
28
|
+
run: pip install -e ".[dev]"
|
|
29
|
+
|
|
30
|
+
- name: Lint
|
|
31
|
+
run: ruff check src/ tests/ scripts/
|
|
32
|
+
|
|
33
|
+
- name: Test
|
|
34
|
+
run: pytest tests/ -v
|
|
35
|
+
|
|
36
|
+
installed-package:
|
|
37
|
+
runs-on: ubuntu-latest
|
|
38
|
+
timeout-minutes: 10
|
|
39
|
+
strategy:
|
|
40
|
+
matrix:
|
|
41
|
+
python-version: ["3.10", "3.13"]
|
|
42
|
+
steps:
|
|
43
|
+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
|
|
44
|
+
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
|
|
45
|
+
with:
|
|
46
|
+
python-version: ${{ matrix.python-version }}
|
|
47
|
+
- name: Build wheel and source distribution
|
|
48
|
+
run: |
|
|
49
|
+
python -m pip install build twine
|
|
50
|
+
python -m build
|
|
51
|
+
python -m twine check dist/*
|
|
52
|
+
- name: Install wheel into a clean environment
|
|
53
|
+
run: |
|
|
54
|
+
python -m venv "$RUNNER_TEMP/package-check"
|
|
55
|
+
"$RUNNER_TEMP/package-check/bin/python" -m pip install dist/*.whl
|
|
56
|
+
"$RUNNER_TEMP/package-check/bin/python" -m pip check
|
|
57
|
+
- name: Verify CLI and MCP transport from installed wheel
|
|
58
|
+
run: '"$RUNNER_TEMP/package-check/bin/python" -I scripts/check_install.py'
|
|
@@ -11,13 +11,15 @@ MCP server + CLI that lets Claude Code agents delegate tasks to agents in other
|
|
|
11
11
|
| File | Role |
|
|
12
12
|
|------|------|
|
|
13
13
|
| `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
|
|
14
|
-
| `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread`
|
|
15
|
-
| `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome) + aggregation for `stats` and the `typical` block |
|
|
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/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`) |
|
|
19
19
|
| `src/agent_dispatch/config.py` | YAML config load/save + project auto-description |
|
|
20
20
|
| `src/agent_dispatch/cache.py` | Thread-safe in-memory TTL cache |
|
|
21
|
+
| `src/agent_dispatch/concurrency.py` | Resizable process limit shared by async callers and background workers |
|
|
22
|
+
| `src/agent_dispatch/progress.py` | Bounded progress buffer, discarded when a streaming client disconnects |
|
|
21
23
|
| `src/agent_dispatch/jobs.py` | Persistent per-job JSON files for async dispatch |
|
|
22
24
|
|
|
23
25
|
## Dev setup
|
|
@@ -29,11 +31,13 @@ pip install -e ".[dev]"
|
|
|
29
31
|
## Gates — both must pass before a change is done (CI rejects otherwise)
|
|
30
32
|
|
|
31
33
|
```bash
|
|
32
|
-
ruff check src/ tests/
|
|
33
|
-
python3 -m pytest tests/ -v
|
|
34
|
+
ruff check src/ tests/ scripts/
|
|
35
|
+
python3 -m pytest tests/ -v
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `
|
|
38
|
+
Tests must **never** invoke the real `claude` CLI. Runner unit tests mock `shutil.which` + `_run_captured`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. Pipe and decoding integration tests spawn short-lived *python* subprocesses: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
|
|
39
|
+
|
|
40
|
+
The autouse guard in `tests/conftest.py` rejects real Claude process launches when a test forgets its mock. Diagnostic tests must mock discovery or CLI probes too.
|
|
37
41
|
|
|
38
42
|
## Non-obvious invariants (violating these breaks real behavior)
|
|
39
43
|
|
|
@@ -45,32 +49,35 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
|
|
|
45
49
|
- Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
|
|
46
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.
|
|
47
51
|
- "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.
|
|
48
|
-
- Cancelling a *running* job requires the in-memory
|
|
52
|
+
- 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).
|
|
49
53
|
- `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.
|
|
50
54
|
- A CLI error payload can have no `result` field at all — the reason lives in `errors` / `subtype`. Read it via `_cli_error_details`, never assume `result` is populated on failure.
|
|
51
|
-
- **Both subprocess pipes must be drained concurrently.** `dispatch_stream` reads stdout in a loop while a daemon thread drains stderr; reading stderr only after the loop deadlocks any child that writes more than ~64 KiB to it (the child blocks in `write(2)`, never emits its result, and the dispatch dies at the timeout). `dispatch
|
|
55
|
+
- **Both subprocess pipes must be drained concurrently.** `dispatch_stream` reads stdout in a loop while a daemon thread drains stderr; reading stderr only after the loop deadlocks any child that writes more than ~64 KiB to it (the child blocks in `write(2)`, never emits its result, and the dispatch dies at the timeout). Ordinary `dispatch` uses `_run_captured` with two readers; binary `read1` retains flushed output even without a newline. Readers own their pipes, and stop retaining output when the caller returns. **Completion is stdout EOF + leader exit, never stderr EOF**: a stdio MCP server started by `claude` inherits fd 2 and outlives it, so waiting for stderr EOF turned every such dispatch into a full-timeout wait and a real CLI error into `error_type="timeout"`. stderr gets a short bounded join afterwards, then the leftover group is killed. `dispatch_stream` reads stdout through a reader thread too, so a descendant that *detached* from the group (unreachable by `killpg`) cannot park it forever once the run was killed.
|
|
52
56
|
- **A received `result` event outranks the timeout flag.** The agent finished and was billed; a lingering process is a cleanup problem, reported as a `hint`, not a failure.
|
|
53
|
-
- **The timeout must kill the process *tree*, not the child.**
|
|
57
|
+
- **The timeout must kill the process *tree*, not the child.** Both runners spawn with `start_new_session=True` and `_kill_process_tree` sends SIGKILL to the group: a grandchild that inherited stdout keeps the read loop parked long past the deadline otherwise. `killpg` is guarded on a positive pid — `killpg(0)` would signal the dispatcher's own group — and on `proc.returncode is None`: a reaped leader's PID may already belong to an unrelated group. So nothing may reap the leader (`poll()`/`wait()`) before the kill decision; `_wait_leader_exit` observes exit without reaping (`waitid(WNOWAIT)` on Linux, a kqueue exit watch on macOS). `_run_captured` drains pipes before reaping the leader, so its PID cannot be recycled before a timeout kill. Cleanup waits are bounded even when a descendant deliberately leaves the process group. A full CLI `type=result` JSON payload outranks the ordinary timeout too; incomplete output does not.
|
|
54
58
|
- **Never `close()` a pipe another thread may still be reading.** `close()` waits on the reader's buffer lock with *no timeout*, so it would hang the dispatch forever — the bounded `join()` before it buys nothing. `dispatch_stream` skips the stderr close while the drain thread is alive and lets the daemon reader + Popen finalizer release the fd. This is not hypothetical: a stdio MCP server inherits the child's `stderr`, so the pipe often has no EOF even after `claude` exits cleanly.
|
|
55
59
|
- **No `await` inside `config_lock()`.** `ProcessLock`'s in-process guard is a `threading.RLock` — re-entrant per *thread* — and every MCP tool coroutine runs on the one event-loop thread. Suspending in the critical section lets a second coroutine re-enter the "held" lock and interleave its own load/mutate/save. Collect warnings as data, emit them after the `with` block (`test_no_await_inside_the_config_lock` enforces this by AST).
|
|
56
60
|
- Cross-process locks are acquired with a **bounded** wait, never a blocking `flock`: the server takes them on its event-loop thread, so a wedged holder would freeze every tool. After the deadline it proceeds unlocked and logs — a possible lost update beats a permanent freeze.
|
|
57
61
|
- `recover_stale` sweeps `pending` on a **much longer** threshold than `running`: the jobs directory is shared by every `agent-dispatch serve`, so an hours-old pending job may still be queued behind another live server's semaphore. For a *running* job, `started_at` alone does **not** prove abandonment — a dispatch may legitimately run to the 7200s timeout ceiling, so the file's own mtime is checked too (a live worker rewrites it on every progress flush). That check can only ever *skip* a recovery, never add one.
|
|
58
62
|
- Deleting job records is **opt-in** (`settings.job_retention_days`, default `0` = off) and only ever happens at server start, never inside a tool. They are the user's dispatch history and the deletion is irreversible, so an unreadable config is treated as "do nothing" rather than falling back to a default retention.
|
|
59
|
-
- `max_concurrency` must bound *subprocesses*, not coroutines.
|
|
63
|
+
- `max_concurrency` must bound *subprocesses*, not coroutines. All dispatch paths share one `DispatchLimiter` per server, resized in place so changing the limit cannot erase occupied slots. Ordinary and streaming dispatches go through `_start_guarded`, which releases from the future's done-callback; awaits on that future are shielded. Background jobs hold the same limiter in their worker thread. The limiter is **FIFO across threads and coroutines** — a freed slot is handed to the head waiter in `release()`; otherwise parked job threads, woken in microseconds, starved a queued synchronous `dispatch` indefinitely. A waiter cancelled after its grant passes the slot on exactly once. Cancelling a coroutine does not stop its thread: never release its slot from an `async with` or caller-side `finally`.
|
|
60
64
|
- Tool responses are serialized through `server._dumps`, never bare `json.dumps`: the stdlib default (`ensure_ascii=True`) turns every non-ASCII character into a `\uXXXX` escape, tripling the bytes and tokenizing badly, for no gain — the stdio transport emits raw UTF-8 via pydantic anyway. A real `list_groups()` carried 8520 escapes and weighed 59 KB instead of 25 KB.
|
|
61
65
|
- `agents.yaml` is parsed with libyaml's `CSafeLoader` when available (`config._YamlLoader`), falling back to the pure-Python **safe** loader — never `yaml.Loader`. The config is re-read on every tool call, so this parse is on the hot path of all 21 tools *and* blocks the event-loop thread: 9.80 ms → 0.76 ms on a real 38 KB config.
|
|
62
66
|
- Pydantic does **not** validate on assignment. `Field(ge=...)` guards only the *load* path; every mutation surface (CLI `add`/`update`, MCP `add_agent`/`update_agent`) needs its own boundary check, or the bound escapes as a raw `ValidationError`.
|
|
63
67
|
- Every state file (`agents.yaml`, job files) is written **temp file + `os.replace`**, never in place, and every load/mutate/save is wrapped in `config.ProcessLock` — the CLI and the MCP server are separate processes writing the same files, so a thread lock alone loses updates.
|
|
64
|
-
- Anything that changes an agent's config must call `_invalidate_agent_cache`
|
|
68
|
+
- Anything that changes an agent's config must call `_invalidate_agent_cache` to reclaim old entries. Cache lookups and writes also receive the same `_cache_config_key` snapshot, captured before awaiting work: this covers CLI/YAML/other-server edits and prevents an old worker from repopulating the current configuration's cache. Include new dispatch-affecting settings in this snapshot.
|
|
65
69
|
- Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, `budget_exceeded` results, and results whose `outcome` is `partial`/`blocked`, so the documented "grant access / fix the cause, then re-dispatch" recovery is never short-circuited.
|
|
66
70
|
- **Coerce every number read off disk through `usage.as_float`.** `float("abc")` raises **ValueError** — not `JSONDecodeError`, not `OSError` — so it escaped the per-line handler in `usage.load` and the sort key in `servers.live_servers`, turning `agent-dispatch stats --days 7` and `doctor` into tracebacks over one hand-edited character. Same escape route as the `UnicodeDecodeError`-is-a-`ValueError` round. A journal or registry field is untrusted input: skip the record or sort it last, never raise from the command someone ran *because* something is already wrong.
|
|
67
71
|
- **`--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.
|
|
68
72
|
- **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).
|
|
69
73
|
- **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.
|
|
74
|
+
- **`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. Only `dispatch` resumes; `dispatch_stream` has no `session_id`.
|
|
75
|
+
- **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.
|
|
70
76
|
- **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.
|
|
71
77
|
- **`usage_limit` is its own error type** (observed live: `You've hit your session limit · resets 6pm`). It is checked *before* the permission patterns and its hint says the limit is account-wide, so "try another agent" is not a workaround. Text-classified errors attach their advisory through the single `_classification_hint`, not per site.
|
|
72
78
|
- **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).
|
|
73
|
-
- **
|
|
79
|
+
- **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.
|
|
80
|
+
- **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.
|
|
74
81
|
- **`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.
|
|
75
82
|
- 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.
|
|
76
83
|
- The config error sets are declared **once** and in two halves: `config.CONFIG_LOAD_ERRORS` (read) and `config.CONFIG_SAVE_ERRORS` (write — `yaml.dump`'s `RepresenterError` is a `yaml.YAMLError`, therefore neither `OSError` nor `ConfigLoadError`, and used to escape both the MCP guard and the CLI's `_save_or_exit`). Two halves, not one set, because the remediations differ: a failed write is atomic so the old config survives, while a failed read needs the YAML fixed.
|
|
@@ -80,6 +87,7 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
|
|
|
80
87
|
|
|
81
88
|
- `mcp` is pinned **`>=1.2.0,<2`** deliberately: 2.0 removed `mcp.server.fastmcp`, which `server.py` imports, so an unbounded range gives every fresh install a dead `agent-dispatch serve`. Lifting the cap means porting to `mcp.server.mcpserver.MCPServer` — it is not a dependency bump.
|
|
82
89
|
- Verify packaging in a **clean venv**, never the dev machine: build the wheel, install it fresh, import the server. A stale pin in local site-packages hides exactly the failure a new user hits first.
|
|
90
|
+
- CI's `installed-package` job builds wheel and sdist, checks metadata with twine, then installs only the wheel and runtime dependencies into a fresh venv on Python 3.10 and 3.13. Run `python -I scripts/check_install.py` with that venv's Python to verify the installed CLI and a real MCP stdio connection. The check isolates all state in a temporary directory and cannot discover Claude on PATH.
|
|
83
91
|
- Run **`twine check dist/*`** before cutting the tag, with a *current* twine. The clean-venv check does not cover this: it proves the wheel installs, not that PyPI's uploader will accept its metadata. `python -m build` pulls the newest hatchling at build time, so the emitted `Metadata-Version` climbs on its own, and `pypa/gh-action-pypi-publish` is pinned to a SHA that bundles a fixed twine — v0.13.0's publish failed on exactly that mismatch (hatchling 1.32 → metadata 2.5; pinned twine 6.1.0 → "not a valid metadata version"). When it happens, bump the action pin rather than pinning the backend down.
|
|
84
92
|
|
|
85
93
|
## Deliberately not built
|
|
@@ -96,4 +104,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
|
|
|
96
104
|
|
|
97
105
|
## More detail
|
|
98
106
|
|
|
99
|
-
[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests
|
|
107
|
+
[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).
|
|
@@ -7,6 +7,142 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.17.0] - 2026-11-10
|
|
11
|
+
|
|
12
|
+
The cost round, driven by measurements on the live CLI rather than by reading
|
|
13
|
+
code: what a dispatch pays for before the agent does anything, and what the
|
|
14
|
+
journal was getting wrong about resumed sessions.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
- Per-agent startup-context trims, both opt-in: `agent-dispatch update <name>
|
|
18
|
+
--no-skills` (sends `--disable-slash-commands`) and `--strict-mcp` (sends
|
|
19
|
+
`--strict-mcp-config` with the agent directory's own `.mcp.json`). A dispatch
|
|
20
|
+
with a new task re-writes the whole session preamble to the prompt cache —
|
|
21
|
+
about 32k tokens on claude 2.1.322 — and these cut the cold-start cost by 27%
|
|
22
|
+
and 11% (43% together) in a live measurement. `describe` and `inspect_agent`
|
|
23
|
+
show them when set; `doctor` checks that the installed CLI knows the flags.
|
|
24
|
+
Restart running sessions before enabling them: a server on an older release
|
|
25
|
+
drops keys it does not know the next time it saves the config.
|
|
26
|
+
- Usage journal records input, output, cache-read and cache-write tokens plus
|
|
27
|
+
the highest-cost model reported by the CLI, including failed and budget-stopped
|
|
28
|
+
runs. `agent-dispatch stats` shows token totals, cache percentages and each
|
|
29
|
+
agent's most frequent model; `--json` includes counts and measurement coverage.
|
|
30
|
+
Token metadata stays out of tool responses, job files and discovery profiles.
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
- A resumed session's cost was counted again on every `dispatch_session`.
|
|
34
|
+
Since claude 2.1.277 `total_cost_usd` covers the whole session on `--resume`;
|
|
35
|
+
the result and the journal now carry the call's own cost (the difference from
|
|
36
|
+
the session's last journaled total), so `stats` no longer overstates spend and
|
|
37
|
+
a cheap follow-up no longer raises `budget_exceeded` on the session's history.
|
|
38
|
+
Sessions the journal has not seen, and runs with `usage_log: false`, keep the
|
|
39
|
+
reported figure.
|
|
40
|
+
- `return_ref` payloads dropped `budget_exceeded`.
|
|
41
|
+
|
|
42
|
+
## [0.16.0] - 2026-09-30
|
|
43
|
+
|
|
44
|
+
The process-control round. One concurrency limit now covers every dispatch
|
|
45
|
+
path and serves callers in arrival order; ordinary dispatch runs on the same
|
|
46
|
+
bounded two-reader design as streaming; and a round of adversarial review
|
|
47
|
+
aimed at pipes, process groups and cancellation closed the cases where a
|
|
48
|
+
finished run waited out its whole timeout, a detached descendant hung a
|
|
49
|
+
dispatch forever, or a paid result was thrown away over optional metadata.
|
|
50
|
+
Scripts get machine-readable `doctor`, `jobs` and `job` output.
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
- CI verifies clean wheel installation on Python 3.10 and 3.13, distribution
|
|
54
|
+
metadata, and a real MCP stdio connection. `scripts/check_install.py` checks
|
|
55
|
+
CLI/MCP interoperability and full-result export with isolated temporary data.
|
|
56
|
+
- `doctor --json` emits a versioned diagnostic report with checks, severity,
|
|
57
|
+
counts, and remediation details. `--strict` makes warnings fail the command,
|
|
58
|
+
for installation checks in scripts.
|
|
59
|
+
- `agent-dispatch jobs --json` exports compact summaries; `job <id> --json`
|
|
60
|
+
exports the full record, including untruncated results and session metadata.
|
|
61
|
+
- Filter job history by exact agent name with `jobs --agent NAME` or
|
|
62
|
+
`dispatch_jobs(agent="NAME")`, including history for removed agents.
|
|
63
|
+
- Preview history cleanup with `agent-dispatch gc --dry-run` and
|
|
64
|
+
`dispatch_gc(dry_run=True)`. Both use the same eligibility rules as deletion.
|
|
65
|
+
|
|
66
|
+
### Fixed
|
|
67
|
+
- Non-finite budgets are rejected before CLI/MCP mutations and during YAML
|
|
68
|
+
loading. Invalid numeric fields in parallel dispatch return an error before
|
|
69
|
+
any task starts, including values that overflow integer conversion.
|
|
70
|
+
- Ordinary dispatch now kills the process group on timeout, stopping descendants
|
|
71
|
+
that could continue work after the call failed. Pipe reads are concurrent and
|
|
72
|
+
cleanup is bounded even when a descendant detaches from the group.
|
|
73
|
+
- A complete CLI result from ordinary dispatch survives a cleanup timeout,
|
|
74
|
+
preserving the paid answer, cost, session and error classification. Partial
|
|
75
|
+
output still returns a resumable timeout.
|
|
76
|
+
- Running-job cancellation kills the process group, including descendants
|
|
77
|
+
holding output pipes open. A compatibility retry racing cancellation is
|
|
78
|
+
stopped too; the cancelled state is persisted before any kill.
|
|
79
|
+
- Streaming ignores malformed progress events without losing the final paid
|
|
80
|
+
result. Failed process registration cleans up the child and its pipes.
|
|
81
|
+
- Cache keys include the agent configuration and dispatch defaults. Edits from
|
|
82
|
+
the CLI, another server, or YAML cannot reuse an old answer, and workers
|
|
83
|
+
finishing under an older configuration cannot overwrite current answers.
|
|
84
|
+
- The process-tree timeout regression test synchronizes subprocess setup before
|
|
85
|
+
its one-second deadline, avoiding startup-related failures on busy machines.
|
|
86
|
+
- Non-finite and overflowing numeric metadata no longer poison usage reports
|
|
87
|
+
or crash server diagnostics. Invalid optional result costs are omitted while
|
|
88
|
+
preserving the dispatch output; journal records omit non-finite costs.
|
|
89
|
+
- Doctor's server counts and version drift now use one registry snapshot,
|
|
90
|
+
avoiding inconsistent totals when servers start or exit during a check.
|
|
91
|
+
- Two diagnostic tests now mock Claude discovery; a shared test guard rejects
|
|
92
|
+
accidental launches of the real Claude CLI.
|
|
93
|
+
- Streaming progress uses a bounded tail instead of an unlimited queue.
|
|
94
|
+
Slow clients receive an explicit omitted-message count; disconnected clients
|
|
95
|
+
stop retaining progress. Full dispatch results remain intact.
|
|
96
|
+
- All dispatch paths now share `max_concurrency` within a server process.
|
|
97
|
+
Mixing ordinary and background jobs no longer allows twice the configured
|
|
98
|
+
number of subprocesses. Changing the limit preserves occupied slots.
|
|
99
|
+
- Cancelling a streaming tool call keeps its concurrency reservation until the
|
|
100
|
+
worker finishes, just like an ordinary dispatch.
|
|
101
|
+
- Damaged job records cannot redirect status updates or stale recovery to a
|
|
102
|
+
different job: all reads verify the internal ID against the filename.
|
|
103
|
+
- Invalid and non-finite job timestamps are rejected at the read boundary.
|
|
104
|
+
Unreadable records are preserved, including during history cleanup.
|
|
105
|
+
- Job IDs with trailing newlines are rejected before file access.
|
|
106
|
+
- Agent and group name validation rejects trailing newlines instead of accepting
|
|
107
|
+
a partial regular-expression match.
|
|
108
|
+
- Ordinary dispatch completes when the CLI exits and its stdout closes, instead
|
|
109
|
+
of waiting for stderr. A stdio MCP server that inherited stderr no longer
|
|
110
|
+
turns a finished run into a full-timeout wait, and a real CLI error (for
|
|
111
|
+
example a usage limit) is no longer reported as a timeout.
|
|
112
|
+
- Streaming dispatch and running-job cancellation are bounded even when a
|
|
113
|
+
descendant leaves the process group while holding stdout; the concurrency
|
|
114
|
+
slot is released.
|
|
115
|
+
- A process group is never signalled after its leader was reaped, so a recycled
|
|
116
|
+
PID cannot direct the kill at an unrelated process group.
|
|
117
|
+
- The shared concurrency limit serves waiters in arrival order. Background jobs
|
|
118
|
+
queued later can no longer starve an ordinary, streaming or parallel call.
|
|
119
|
+
- Cancelling an owned job between its start and its process spawn now cancels
|
|
120
|
+
it instead of reporting it as belonging to another server. A job record that
|
|
121
|
+
cannot be read at spawn no longer makes the worker kill its own process.
|
|
122
|
+
- Malformed `duration_ms`, `num_turns` or `session_id` in CLI output no longer
|
|
123
|
+
discard the paid result; a bad session id falls back to the generated one.
|
|
124
|
+
- Usage reports ignore implausible journal values, so totals cannot overflow;
|
|
125
|
+
`stats --json` never prints `Infinity`.
|
|
126
|
+
- `doctor` survives non-UTF-8 `claude mcp list` output and an unreadable config
|
|
127
|
+
directory (JSON is still emitted). Its old-CLI warning accounts for
|
|
128
|
+
`dispatch_protocol` and per-agent instructions, so applying its remedy clears
|
|
129
|
+
it under `--strict`.
|
|
130
|
+
- `gc`, `gc --dry-run` and `cancel` report job-storage errors instead of
|
|
131
|
+
printing a traceback.
|
|
132
|
+
- The test guard against launching the real Claude CLI now fails the test even
|
|
133
|
+
when the launch happens in a background worker thread.
|
|
134
|
+
- A failing progress callback (for example a full disk while an async job
|
|
135
|
+
writes its progress) no longer kills the run or discards its paid result and
|
|
136
|
+
session. If the reader threads cannot be started, the spawned process is
|
|
137
|
+
killed instead of running unsupervised.
|
|
138
|
+
- `dispatch_cancel` reports `already_terminal` when this server's own job
|
|
139
|
+
finishes during the cancel, instead of claiming another server owns it.
|
|
140
|
+
- A lone surrogate escape in an agent's answer (typically a hand-escaped emoji
|
|
141
|
+
in a `response_format="json"` reply) no longer makes `dispatch`,
|
|
142
|
+
`dispatch_session`, `dispatch_stream` or `return_ref` raise instead of
|
|
143
|
+
answering, and no longer costs an async job its paid result. It is replaced
|
|
144
|
+
with U+FFFD where the CLI output is parsed.
|
|
145
|
+
|
|
10
146
|
## [0.15.1] - 2026-09-09
|
|
11
147
|
|
|
12
148
|
Three defects in 0.15.0's own new code, found by re-auditing it the way this
|
|
@@ -802,7 +938,13 @@ cache bounding, and stale-job recovery.
|
|
|
802
938
|
- Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
|
|
803
939
|
commit SHAs for supply-chain integrity.
|
|
804
940
|
|
|
805
|
-
[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.
|
|
941
|
+
[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.17.0...HEAD
|
|
942
|
+
[0.17.0]: https://github.com/ginkida/agent-dispatch/compare/v0.16.0...v0.17.0
|
|
943
|
+
[0.16.0]: https://github.com/ginkida/agent-dispatch/compare/v0.15.1...v0.16.0
|
|
944
|
+
[0.15.1]: https://github.com/ginkida/agent-dispatch/compare/v0.15.0...v0.15.1
|
|
945
|
+
[0.15.0]: https://github.com/ginkida/agent-dispatch/compare/v0.14.0...v0.15.0
|
|
946
|
+
[0.14.0]: https://github.com/ginkida/agent-dispatch/compare/v0.13.0...v0.14.0
|
|
947
|
+
[0.13.0]: https://github.com/ginkida/agent-dispatch/compare/v0.12.1...v0.13.0
|
|
806
948
|
[0.12.1]: https://github.com/ginkida/agent-dispatch/compare/v0.12.0...v0.12.1
|
|
807
949
|
[0.12.0]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...v0.12.0
|
|
808
950
|
[0.11.0]: https://github.com/ginkida/agent-dispatch/compare/v0.10.0...v0.11.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: agent-dispatch
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.17.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
|
|
@@ -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
|
|
@@ -385,6 +387,13 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
|
|
|
385
387
|
|
|
386
388
|
Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
|
|
387
389
|
|
|
390
|
+
Progress notifications keep the latest 100 pending messages, capped at 300
|
|
391
|
+
characters each. If output arrives faster than the client can receive it,
|
|
392
|
+
older notifications are omitted with a count; the final result is unaffected.
|
|
393
|
+
Disconnecting or cancelling the tool call discards pending notifications and
|
|
394
|
+
stops buffering new ones. The worker still holds its concurrency slot until it
|
|
395
|
+
finishes.
|
|
396
|
+
|
|
388
397
|
Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode) and `group` (group context injection is supported only on `dispatch` and per-item in `dispatch_parallel`).
|
|
389
398
|
|
|
390
399
|
### `dispatch_dialogue`
|
|
@@ -426,7 +435,7 @@ Register a new project directory as an agent. Description is auto-generated from
|
|
|
426
435
|
| `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
|
|
427
436
|
| `description` | string | no | What this agent can do — auto-generated if empty |
|
|
428
437
|
| `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
|
|
429
|
-
| `max_budget_usd` | float | no |
|
|
438
|
+
| `max_budget_usd` | float | no | Finite max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
|
|
430
439
|
| `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
|
|
431
440
|
| `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
|
|
432
441
|
| `disallowed_tools` | string | no | Comma-separated disallowed tools |
|
|
@@ -452,7 +461,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
|
|
|
452
461
|
| `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
|
|
453
462
|
| `instructions` | string | no | Standing orders for every dispatch (replaces the text). `"none"` to clear |
|
|
454
463
|
|
|
455
|
-
Changing an agent's config drops
|
|
464
|
+
Changing an agent's config through an MCP mutation tool drops its cached results immediately. Cache keys also include the agent configuration and dispatch defaults, so edits through the CLI, another server, or YAML take effect on the next request. A worker finishing with an older configuration cannot overwrite answers for the new configuration. Unchanged agents keep their cache.
|
|
456
465
|
|
|
457
466
|
### `remove_agent`
|
|
458
467
|
|
|
@@ -507,11 +516,11 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
|
|
|
507
516
|
-> {"id": "...", "status": "running", "timed_out_waiting": true}
|
|
508
517
|
```
|
|
509
518
|
|
|
510
|
-
`dispatch_cancel(job_id)` cancels a **pending** job, and also kills a **running** job's `claude`
|
|
519
|
+
`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`.
|
|
511
520
|
|
|
512
521
|
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.
|
|
513
522
|
|
|
514
|
-
`dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
|
|
523
|
+
`dispatch_jobs(status?, limit=50, agent?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `agent` matches an exact name, including agents since removed from configuration; both filters apply before the limit. `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted. Use `dry_run=True` to preview eligible job IDs without deleting them.
|
|
515
524
|
|
|
516
525
|
Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server recovers jobs a crashed instance abandoned: `running` ones stuck over an hour, and `pending` ones over 24 hours, are marked `failed` so they stop being polled forever and become collectable by `dispatch_gc`. (The `pending` threshold is deliberately long — the jobs directory is shared by every running server, so a job queued behind another server's concurrency limit must not be swept.)
|
|
517
526
|
|
|
@@ -545,7 +554,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
|
|
|
545
554
|
| `error_type` | Meaning | Recovery |
|
|
546
555
|
|--------------|---------|----------|
|
|
547
556
|
| `permission` | A tool call was denied | `update_agent(name, allowed_tools="Bash,Read")` (least privilege) or `update_agent(name, permission_mode="bypassPermissions")`, then re-dispatch. The `error` text includes a hint with the exact fix. |
|
|
548
|
-
| `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`.
|
|
557
|
+
| `timeout` | Process group killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`. Both ordinary and streaming dispatches preserve a complete CLI result received before termination; a successful result includes a cleanup `hint`. Partial output remains a timeout. |
|
|
549
558
|
| `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. |
|
|
550
559
|
| `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. |
|
|
551
560
|
| `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>)`. |
|
|
@@ -580,6 +589,8 @@ agents:
|
|
|
580
589
|
- deploy_debug
|
|
581
590
|
risky_capabilities: # high-risk labels, surfaced for visibility
|
|
582
591
|
- restart_services
|
|
592
|
+
# skills: false # no skill/command listing at startup (cheaper dispatches)
|
|
593
|
+
# strict_mcp: true # load only this directory's .mcp.json, no user-scope MCP servers
|
|
583
594
|
# instructions: | # standing orders, appended to the system prompt on every dispatch
|
|
584
595
|
# Read-only: never restart or redeploy unless the task says so.
|
|
585
596
|
# Quote exact log lines with timestamps.
|
|
@@ -617,7 +628,7 @@ settings:
|
|
|
617
628
|
# - Read
|
|
618
629
|
# - Edit
|
|
619
630
|
max_dispatch_depth: 3 # recursion protection
|
|
620
|
-
max_concurrency: 5 # max parallel claude -p processes
|
|
631
|
+
max_concurrency: 5 # max parallel claude -p processes per server, across all tools
|
|
621
632
|
# dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
|
|
622
633
|
# # time budget, STATUS line → `outcome`). false = raw claude -p.
|
|
623
634
|
# usage_log: true # record every dispatch in usage.jsonl (cost, duration, outcome).
|
|
@@ -636,7 +647,11 @@ Config is reloaded on every tool call — add agents without restarting.
|
|
|
636
647
|
|
|
637
648
|
Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
|
|
638
649
|
(override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
|
|
639
|
-
turns, `outcome`, error type, caller
|
|
650
|
+
turns, `outcome`, error type, caller, plus token counts and the model when the
|
|
651
|
+
CLI reports them. Token fields are `in` (uncached input), `out` (output),
|
|
652
|
+
`cr` (cache read), and `cw` (cache write). `model` is the highest-cost model
|
|
653
|
+
in that dispatch's `modelUsage` (first on ties or when no cost is reported).
|
|
654
|
+
Cache hits are recorded too, flagged
|
|
640
655
|
`cached`, so the report can show what the cache saves.
|
|
641
656
|
|
|
642
657
|
```console
|
|
@@ -644,18 +659,33 @@ $ agent-dispatch stats --days 7
|
|
|
644
659
|
Usage (last 7 day(s))
|
|
645
660
|
dispatches: 33, 1 served from cache
|
|
646
661
|
spend: $13.0390
|
|
662
|
+
tokens: in 1.2M (cache read 62%, cache write 35%), out 310k
|
|
647
663
|
duration: median 87s, p90 2m40s, max 10m00s
|
|
648
664
|
outcomes: blocked 1, done 27, partial 3
|
|
649
665
|
failures: timeout 1, usage_limit 1
|
|
650
666
|
|
|
651
667
|
Per agent
|
|
652
668
|
analytic 18 runs $ 8.9441 median 2m04s p90 2m51s
|
|
669
|
+
tokens: in 800k (cache read 62%, cache write 35%), out 210k
|
|
670
|
+
model: claude-fable-5-2 +1 more
|
|
653
671
|
done 15, partial 3
|
|
654
672
|
gitlab 12 runs $ 3.7949 median 60s p90 86s
|
|
673
|
+
tokens: in 400k (cache read 62%, cache write 35%), out 100k
|
|
674
|
+
model: claude-fable-5-2
|
|
655
675
|
done 12 | 1 cached
|
|
656
676
|
```
|
|
657
677
|
|
|
658
678
|
`--agent NAME` narrows it, `--json` emits the same report as JSON.
|
|
679
|
+
The text's `in` includes uncached input, cache reads, and cache writes; its
|
|
680
|
+
percentages use that combined input. JSON keeps those counts separate in
|
|
681
|
+
`tokens: {input, output, cache_read, cache_write, records}`, adds
|
|
682
|
+
`cache_read_share` rounded to three decimals when total input is nonzero,
|
|
683
|
+
and counts dispatches by primary model in `models`. `records` counts live
|
|
684
|
+
dispatches with valid token measurements; older records and cache hits do
|
|
685
|
+
not dilute the share. Each agent's text shows its most frequent model and
|
|
686
|
+
how many other models were recorded. Runs that fail or reach the spend cap
|
|
687
|
+
still contribute their reported usage. Token telemetry is journal-only:
|
|
688
|
+
tool responses, job files, and discovery's `typical` block stay compact.
|
|
659
689
|
|
|
660
690
|
The journal is what makes three other things work: the `typical` block in
|
|
661
691
|
`list_agents` / `inspect_agent`, the timeout error naming a value derived from
|
|
@@ -689,8 +719,19 @@ past dispatches and deleting them cannot be undone. Pending and running jobs are
|
|
|
689
719
|
never touched.
|
|
690
720
|
|
|
691
721
|
`agent-dispatch gc --days N` and the `dispatch_gc` tool apply the same rule as a
|
|
692
|
-
one-off.
|
|
693
|
-
|
|
722
|
+
one-off. Preview eligible records before deleting them:
|
|
723
|
+
|
|
724
|
+
```bash
|
|
725
|
+
agent-dispatch gc --days 30 --dry-run
|
|
726
|
+
agent-dispatch gc --days 30
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
`--dry-run` also works with `--all`. The MCP equivalent is
|
|
730
|
+
`dispatch_gc(max_age_days=30, dry_run=True)`, returning `dry_run: true`,
|
|
731
|
+
`purged: 0`, `would_purge`, `job_ids`, and `max_age_days`.
|
|
732
|
+
A preview is a snapshot; deletion checks eligibility again, so its count can
|
|
733
|
+
change as jobs finish. Unreadable records, invalid timestamps, and records whose
|
|
734
|
+
internal ID differs from their filename are skipped and preserved for inspection.
|
|
694
735
|
|
|
695
736
|
### Auto-Description
|
|
696
737
|
|
|
@@ -725,8 +766,8 @@ Your Claude Code session
|
|
|
725
766
|
▼
|
|
726
767
|
agent-dispatch MCP server
|
|
727
768
|
├─ cache check → hit? return cached result
|
|
728
|
-
├─
|
|
729
|
-
└─ subprocess.
|
|
769
|
+
├─ shared process limit → bound concurrency across all dispatch tools
|
|
770
|
+
└─ subprocess.Popen(["claude", "-p", ...], cwd=~/projects/infra/)
|
|
730
771
|
│
|
|
731
772
|
▼
|
|
732
773
|
New Claude Code session in ~/projects/infra/
|
|
@@ -745,9 +786,9 @@ agent-dispatch MCP server
|
|
|
745
786
|
- **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
|
|
746
787
|
- **Owner-only state** — job files, `agents.yaml`, the usage journal and the server registry are all written `0o600`; their directories are `0o700`.
|
|
747
788
|
- **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
|
|
748
|
-
- **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes.
|
|
749
|
-
- **Timeout** — per-agent or global (default: 300s).
|
|
750
|
-
- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
|
|
789
|
+
- **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes across all dispatch tools within one server process. Ordinary, streaming, and background dispatches share the same limit, and waiting calls are served in arrival order, so a queue of background jobs cannot starve an interactive call. Cancelling a waiting call never starts its process; cancelling an already-started ordinary or streaming call keeps its slot occupied until the worker ends. Reloading a changed limit preserves occupied slots: lowering it lets existing work finish and holds new launches until capacity is available. Separate server processes each have their own limit.
|
|
790
|
+
- **Timeout** — per-agent or global (default: 300s). Both ordinary and streaming dispatches run the agent in its own process group. On POSIX, the deadline kills that group, including descendants that inherited output pipes. Ordinary dispatch also bounds cleanup to one additional second if a descendant deliberately detached from the group; that detached process is outside the group's reach. A complete CLI result survives cleanup timeout, with a hint on successful results.
|
|
791
|
+
- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests under the same agent configuration and dispatch defaults return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
|
|
751
792
|
- **Durable config** — `agents.yaml` is written atomically (temp file + rename), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
|
|
752
793
|
|
|
753
794
|
See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
|
|
@@ -758,20 +799,57 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
|
|
|
758
799
|
|---------|-------------|
|
|
759
800
|
| `agent-dispatch init` | Create config + register MCP server with Claude Code |
|
|
760
801
|
| `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
|
|
761
|
-
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
|
|
802
|
+
| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, `--no-skills`, `--strict-mcp`, etc.) |
|
|
762
803
|
| `agent-dispatch remove <name>` | Remove an agent |
|
|
763
804
|
| `agent-dispatch list` | List agents with health status and permissions |
|
|
764
805
|
| `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
|
|
765
806
|
| `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
|
|
766
807
|
| `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
|
|
767
808
|
| `agent-dispatch stats [--days N --agent X --json]` | What dispatches cost: spend, durations, outcomes and failures per agent |
|
|
768
|
-
| `agent-dispatch doctor` | Diagnose installation
|
|
769
|
-
| `agent-dispatch jobs [--status --limit]` | List
|
|
770
|
-
| `agent-dispatch job <id
|
|
809
|
+
| `agent-dispatch doctor [--json --strict]` | Diagnose installation, stale servers, MCP registration, agent health, and group membership; `--strict` also fails on warnings |
|
|
810
|
+
| `agent-dispatch jobs [--status STATUS --agent NAME --limit N --json]` | List recent job summaries, including results stored with `return_ref` |
|
|
811
|
+
| `agent-dispatch job <id> [--json]` | Show one job; `--json` exports the full record without truncation |
|
|
771
812
|
| `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |
|
|
772
|
-
| `agent-dispatch gc [--days N \| --all]` | Purge terminal jobs older than N days (default 7; `--all` purges every age) |
|
|
813
|
+
| `agent-dispatch gc [--days N \| --all] [--dry-run]` | Purge terminal jobs older than N days (default 7; `--all` purges every age); `--dry-run` previews without deleting |
|
|
773
814
|
| `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
|
|
774
815
|
|
|
816
|
+
To check an installation from a script:
|
|
817
|
+
|
|
818
|
+
```bash
|
|
819
|
+
agent-dispatch doctor --json --strict > diagnostics.json
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
The report contains `schema_version: 1`, overall `status` (`ok`, `warn`, or
|
|
823
|
+
`fail`), `issues` and `warnings` counts, and a `checks` array. Each check has a
|
|
824
|
+
`section`, `status`, `message`, and `details` array containing any remediation
|
|
825
|
+
steps or supporting information. JSON is emitted even when checks fail.
|
|
826
|
+
Failures exit with code 1; warnings exit with code 0 unless `--strict` is set.
|
|
827
|
+
The same checks and exit policy apply to the normal human-readable output.
|
|
828
|
+
This checks installation and configuration; it does not run a paid dispatch.
|
|
829
|
+
|
|
830
|
+
To inspect history from scripts or save a full result:
|
|
831
|
+
|
|
832
|
+
```bash
|
|
833
|
+
agent-dispatch jobs --agent infra --status failed --limit 10 --json
|
|
834
|
+
agent-dispatch job <job_id> --json > job.json
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
`jobs --json` returns an array of compact summaries in the same format as
|
|
838
|
+
`dispatch_jobs`, or `[]` if no jobs match. Each summary includes the ID, agent,
|
|
839
|
+
status, first 120 task characters, and timestamps; result cost, success, outcome,
|
|
840
|
+
error type, and latest running progress are included when available.
|
|
841
|
+
`job --json` returns the full stored job, including task/context, progress,
|
|
842
|
+
result text, structured result, session ID, and recovery hints when present.
|
|
843
|
+
Both formats preserve Unicode. Reading a failed job still exits successfully:
|
|
844
|
+
check its `status` and `result.success` to determine the dispatch outcome.
|
|
845
|
+
Missing/invalid job IDs and storage-open failures return `{"error": "..."}`
|
|
846
|
+
with exit code 1. Invalid command-line options are reported by Click on stderr.
|
|
847
|
+
|
|
848
|
+
Invalid or non-finite cost metadata is treated as unknown and omitted from
|
|
849
|
+
result exports; it does not hide the stored result text. Usage summaries ignore
|
|
850
|
+
unusable numeric measurements, and doctor omits uptime when a server's start
|
|
851
|
+
timestamp is unreadable.
|
|
852
|
+
|
|
775
853
|
## Requirements
|
|
776
854
|
|
|
777
855
|
- Python >= 3.10
|