agent-director 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +317 -144
- package/dist/errors.d.ts +108 -9
- package/dist/index.d.ts +4 -3
- package/dist/index.js +317 -40
- package/dist/internal/argv.d.ts +25 -11
- package/dist/internal/discovery.d.ts +3 -2
- package/dist/internal/errorMap.d.ts +10 -7
- package/dist/internal/subprocessClient.d.ts +37 -6
- package/dist/internal/verbs.d.ts +4 -4
- package/dist/types.d.ts +671 -141
- package/dist/version-floor.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -16,32 +16,17 @@ Requires Bun >=1.0.21. The package ships pure JavaScript — there are
|
|
|
16
16
|
optional platform dependencies. `bun add --ignore-scripts agent-director`
|
|
17
17
|
is a no-op and installs the library with identical functionality.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
from the [latest release](https://github.com/gabemahoney/agent-director/releases/latest)
|
|
23
|
-
and sets up `~/.agent-director/`:
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/skills/install-agent-director/install.sh | bash -s -- --from-release
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`Client.create()` discovers the installed binary at construction time
|
|
30
|
-
(either at `~/.agent-director/bin/agent-director` or anywhere on
|
|
31
|
-
`$PATH`) and rejects if it cannot find one. Other supported install
|
|
32
|
-
mechanisms — `install.sh --binary <path> --admin-binary <path>` with
|
|
33
|
-
locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
|
|
34
|
-
[repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
|
|
19
|
+
Install the CLI separately using the [install guide](../../docs/install.md).
|
|
20
|
+
`Client.create()` finds it at the standard install path or on `$PATH`;
|
|
21
|
+
its version must meet the client floor.
|
|
35
22
|
|
|
36
23
|
## Supported platforms
|
|
37
24
|
|
|
38
25
|
- `linux/x64` (Linux on x86_64)
|
|
39
26
|
- `darwin/arm64` (Apple Silicon Mac)
|
|
40
27
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
the CLI binary's own platform coverage. The CLI must be installed
|
|
44
|
-
separately per the platform list above.
|
|
28
|
+
Package installation may also succeed on `linux/arm64` and `darwin/x64`;
|
|
29
|
+
those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
|
|
45
30
|
|
|
46
31
|
## Quick start
|
|
47
32
|
|
|
@@ -53,6 +38,9 @@ const v = await client.version({});
|
|
|
53
38
|
console.log(v.version);
|
|
54
39
|
```
|
|
55
40
|
|
|
41
|
+
The `version` result is `{ version, commit, config_dir }`; `config_dir` is the
|
|
42
|
+
directory the CLI keeps its files in, `~/.config/agent-director` (unexpanded).
|
|
43
|
+
|
|
56
44
|
Explicit `try/finally` (portable fallback):
|
|
57
45
|
|
|
58
46
|
```ts
|
|
@@ -65,78 +53,126 @@ try {
|
|
|
65
53
|
}
|
|
66
54
|
```
|
|
67
55
|
|
|
68
|
-
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
|
|
56
|
+
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.config/agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
|
|
69
57
|
|
|
70
|
-
`ClientOptions` overrides forward
|
|
58
|
+
`ClientOptions` overrides forward to the CLI subprocess as global flags:
|
|
71
59
|
|
|
72
60
|
- `storePath` → `--store-path`
|
|
73
61
|
- `home` → `--home`
|
|
74
62
|
- `tmuxCommand` → `--tmux-command`
|
|
63
|
+
- `createIfMissing: false` → `--create-if-missing false` (`true` forwards nothing)
|
|
75
64
|
|
|
76
|
-
The CLI, not the client, expands a `~` in
|
|
77
|
-
else (never the passwd entry's home). It applies `home` first, so with `home`
|
|
65
|
+
The paths are forwarded verbatim. The CLI, not the client, expands a `~` in
|
|
66
|
+
them, against `HOME` and nothing else (never the passwd entry's home). It applies `home` first, so with `home`
|
|
78
67
|
set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
|
|
79
68
|
`HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
|
|
80
69
|
`ErrInvalidFlags`, and with no `home` either, every call that opens the store
|
|
81
70
|
is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
|
|
82
|
-
expand its config path `~/.agent-director/config.toml`.
|
|
71
|
+
expand its config path `~/.config/agent-director/config.toml`.
|
|
72
|
+
|
|
73
|
+
Set them when the consumer needs to override that field's CLI default.
|
|
83
74
|
|
|
84
|
-
|
|
75
|
+
By default, the first call that opens the store creates it when it does not
|
|
76
|
+
exist (parent directories, file and schema). With `createIfMissing: false`,
|
|
77
|
+
such a call rejects with `ErrStoreOpen` (`database not initialized`) and
|
|
78
|
+
creates none of it; an existing store opens as usual, and calls that open no
|
|
79
|
+
store, such as `version`, are unaffected.
|
|
80
|
+
|
|
81
|
+
For spawning under another home or store, use
|
|
82
|
+
[Permissions](../../docs/permissions.md#one-spawn-under-another-home-or-store).
|
|
85
83
|
|
|
86
84
|
## Verb examples
|
|
87
85
|
|
|
88
|
-
|
|
86
|
+
Shared CLI use is in [Usage](../../docs/usage.md).
|
|
89
87
|
|
|
90
|
-
|
|
88
|
+
A call that carries an old name of a renamed key (on any verb) throws
|
|
89
|
+
`ErrInvalidFlags` before the client starts any process; its description names
|
|
90
|
+
the new key.
|
|
91
91
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
92
|
+
### spawn
|
|
93
|
+
|
|
94
|
+
Launch a tracked agent in a new tmux session. A spawn names its agent, `"claude"` or `"codex"` (case-sensitive), in `agent` or through its template; with neither it throws `ErrAgentMissing`. An empty `agent` counts as not given.
|
|
95
95
|
|
|
96
96
|
```ts
|
|
97
|
-
const result = await client.spawn({ cwd: "~/my-project" });
|
|
98
|
-
console.log(result.
|
|
97
|
+
const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
|
|
98
|
+
console.log(result.instance_id);
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
+
The `SpawnResult` has `instance_id`, `pre_trust` and optional
|
|
102
|
+
`dropped_args?: string[]`. On a switching reuse, `dropped_args` contains
|
|
103
|
+
removed original argument tokens in argv order; it is omitted when empty.
|
|
104
|
+
The switch starts fresh and resumes nothing. Selector lists and reporting
|
|
105
|
+
rules are in the
|
|
106
|
+
[caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals).
|
|
107
|
+
|
|
108
|
+
Same-agent reuse retains current-life session history and subagent records;
|
|
109
|
+
switching agents starts another life, including when switching back.
|
|
110
|
+
`resume` continues only the recorded agent's latest reported session and
|
|
111
|
+
never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
|
|
112
|
+
and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
|
|
113
|
+
|
|
101
114
|
### status
|
|
102
115
|
|
|
103
116
|
Get the current lifecycle state of a Spawn.
|
|
104
117
|
|
|
105
|
-
```sh
|
|
106
|
-
agent-director status --claude-instance-id <id>
|
|
107
|
-
```
|
|
108
|
-
|
|
109
118
|
```ts
|
|
110
|
-
const result = await client.status({
|
|
119
|
+
const result = await client.status({ instance_id: "<id>" });
|
|
111
120
|
console.log(result.state);
|
|
112
121
|
```
|
|
113
122
|
|
|
123
|
+
With `[state] settle_ms` set in the CLI's `~/.config/agent-director/config.toml`,
|
|
124
|
+
`status`, `get` and `list` report the settled state: a state a hook wrote
|
|
125
|
+
shows only once it has held that long, the last settled state until then;
|
|
126
|
+
`ended`, `missing` and a state a verb wrote show at once, and `list`'s
|
|
127
|
+
`state` filter matches the settled state. Every verb that acts on a Spawn
|
|
128
|
+
judges its live state, which can be newer. The client adds no field and
|
|
129
|
+
no state value for it.
|
|
130
|
+
|
|
114
131
|
### list
|
|
115
132
|
|
|
116
133
|
Query Spawns with optional filters.
|
|
117
134
|
|
|
118
|
-
```sh
|
|
119
|
-
agent-director list --state waiting
|
|
120
|
-
```
|
|
121
|
-
|
|
122
135
|
```ts
|
|
123
136
|
const result = await client.list({ state: ["waiting"] });
|
|
124
137
|
for (const spawn of result.spawns) {
|
|
125
|
-
console.log(spawn.
|
|
138
|
+
console.log(spawn.instance_id, spawn.state, spawn.agent);
|
|
126
139
|
}
|
|
127
140
|
```
|
|
128
141
|
|
|
129
|
-
|
|
142
|
+
Each row, like `get`'s result, carries `agent` (`"claude"` or `"codex"`), the agent the row runs.
|
|
130
143
|
|
|
131
|
-
|
|
132
|
-
`text` sends the Enter only, submitting what is already typed.
|
|
144
|
+
### listSubagents
|
|
133
145
|
|
|
134
|
-
|
|
135
|
-
|
|
146
|
+
Read the subagent records across launches of one agent's current life, and
|
|
147
|
+
whether the agent is tracked. `subagent_id` is unique among the returned
|
|
148
|
+
records; earlier-life records remain stored but are hidden. See
|
|
149
|
+
[visibility and retention](../../docs/usage.md#read-an-agents-subagent-records).
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
const result = await client.listSubagents({ instance_id: "<id>" });
|
|
153
|
+
console.log(result.tracked);
|
|
154
|
+
for (const sub of result.subagents) {
|
|
155
|
+
console.log(sub.subagent_id, sub.state, sub.subagent_type ?? "unknown type");
|
|
156
|
+
}
|
|
136
157
|
```
|
|
137
158
|
|
|
159
|
+
`tracked` is `false`, with `subagents` `[]`, for a `"codex"` agent (from its spawn, and after every `resume` or reuse of its id) and for a `"claude"` agent that predates subagent tracking (it becomes `true` when that agent is next resumed or its id is reused). `subagents` is never null; a field with no known value is `null`, and times are RFC 3339 UTC strings. The fields and values are described in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
|
|
160
|
+
|
|
161
|
+
### sendKeys
|
|
162
|
+
|
|
163
|
+
Send text to the agent's own pane, then one Enter to submit it. An empty
|
|
164
|
+
or omitted `text` sends the Enter only, submitting what is already typed.
|
|
165
|
+
`no_enter: true` types the text without the Enter, and `key` sends one key
|
|
166
|
+
alone (`"Escape"`, `"Enter"`, `"Up"`, `"Down"`, `"Tab"`, or one character),
|
|
167
|
+
never followed by Enter. With `expect_pane_sha256` (the `pane_sha256` of
|
|
168
|
+
the `readPane` you looked at, with its `n_lines`), nothing is sent if the
|
|
169
|
+
pane changed since (`ErrPaneChanged`); on a relayed Spawn a match also
|
|
170
|
+
passes the dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
|
|
171
|
+
the pane" below). Pass it only for a pane a person or an LLM judged, never
|
|
172
|
+
from an automatic flow.
|
|
173
|
+
|
|
138
174
|
```ts
|
|
139
|
-
await client.sendKeys({
|
|
175
|
+
await client.sendKeys({ instance_id: "<id>", text: "what is 2+2?" });
|
|
140
176
|
```
|
|
141
177
|
|
|
142
178
|
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
@@ -147,30 +183,23 @@ still rejected. A `pending` row whose launch start or launch token is not record
|
|
|
147
183
|
only a session an earlier launch left behind is found, gets
|
|
148
184
|
`ErrSpawnNotInteractive` and nothing is sent.
|
|
149
185
|
|
|
150
|
-
|
|
151
|
-
a
|
|
152
|
-
|
|
153
|
-
```ts
|
|
154
|
-
await client.sendKeys({
|
|
155
|
-
claude_instance_id: "<id>",
|
|
156
|
-
text: "",
|
|
157
|
-
allow_pending: true,
|
|
158
|
-
});
|
|
159
|
-
```
|
|
186
|
+
`liveness_note: "unreported"` means an alive agent has not reported since
|
|
187
|
+
launch. Action on a pending row belongs to the
|
|
188
|
+
[caller contract](../../docs/caller-contract.md#caller-contract).
|
|
160
189
|
|
|
161
190
|
### readPane
|
|
162
191
|
|
|
163
192
|
Read the last N lines of the agent's own pane (default 25).
|
|
164
193
|
|
|
165
|
-
```sh
|
|
166
|
-
agent-director read-pane --claude-instance-id <id> --n-lines 50
|
|
167
|
-
```
|
|
168
|
-
|
|
169
194
|
```ts
|
|
170
|
-
const result = await client.readPane({
|
|
171
|
-
console.log(result.pane);
|
|
195
|
+
const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
|
|
196
|
+
console.log(result.pane, result.pane_sha256);
|
|
172
197
|
```
|
|
173
198
|
|
|
199
|
+
`pane_sha256` is the SHA-256 of exactly the bytes of `pane`; pass it back as
|
|
200
|
+
`sendKeys`' or `recordPaneAnswer`'s `expect_pane_sha256`, with the same
|
|
201
|
+
`n_lines`, when you act on what this pane shows.
|
|
202
|
+
|
|
174
203
|
`readPane` has no state guard — it works on `pending`, `ended`, and `missing`
|
|
175
204
|
rows as well as live ones. The `allow_pending` flag is accepted for symmetry
|
|
176
205
|
with `sendKeys` but has no behavioral effect.
|
|
@@ -187,47 +216,167 @@ resolves with `kill_sent: false`; that is not verification that the agent
|
|
|
187
216
|
exited. `kill` never changes the row's state: `find-missing` marks the row once
|
|
188
217
|
its agent process is gone.
|
|
189
218
|
|
|
190
|
-
```sh
|
|
191
|
-
agent-director kill --claude-instance-id <id>
|
|
192
|
-
```
|
|
193
|
-
|
|
194
219
|
```ts
|
|
195
|
-
const { kill_sent } = await client.kill({
|
|
220
|
+
const { kill_sent } = await client.kill({ instance_id: "<id>" });
|
|
196
221
|
console.log(kill_sent);
|
|
197
222
|
```
|
|
198
223
|
|
|
199
224
|
Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
|
|
200
|
-
retry later), `ErrTmuxSessionConflict` (CONFLICT
|
|
201
|
-
`ErrTmuxNotAvailable` (ENVIRONMENT
|
|
202
|
-
`ErrSpawnNotFound`. None of these
|
|
203
|
-
|
|
204
|
-
|
|
225
|
+
retry later), `ErrTmuxSessionConflict` (CONFLICT),
|
|
226
|
+
`ErrTmuxNotAvailable` (ENVIRONMENT) and
|
|
227
|
+
`ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
|
|
228
|
+
for the live-row sequence and finished-row limits.
|
|
229
|
+
|
|
230
|
+
### pause
|
|
231
|
+
|
|
232
|
+
Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
|
|
233
|
+
`pause.timeout_seconds` for `ended`. A finished Spawn is a no-op. A live Codex
|
|
234
|
+
Spawn whose agent already exited with an end report resolves, in any live
|
|
235
|
+
state, having typed nothing, and its row is `ended`; otherwise any live state
|
|
236
|
+
but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
|
|
237
|
+
`pause` ends the row itself once the agent exits (see the
|
|
238
|
+
[caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits)).
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
await client.pause({ instance_id: "<id>" });
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
`pause` is held like a `sendKeys` without `request_token` and without
|
|
245
|
+
`expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
|
|
246
|
+
`ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
|
|
247
|
+
with the same `errDetails`, typing nothing and starting no wait, whenever
|
|
248
|
+
that `sendKeys` would. It takes no pane hash, so it stays held until the
|
|
249
|
+
agent's hooks prove each request gone (after a subagent's denied request, or on
|
|
250
|
+
a Codex Spawn an allowed one, until the agent ends). Stopping a held spawn and handling these refusals are in the
|
|
251
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
205
252
|
|
|
206
253
|
### makeTemplate
|
|
207
254
|
|
|
208
|
-
Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
255
|
+
Save a reusable spawn preset. Pass `agent` to bake in the template's agent; a template with `agent_args` needs one. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
209
256
|
|
|
210
|
-
```
|
|
211
|
-
|
|
257
|
+
```ts
|
|
258
|
+
await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
|
|
212
259
|
```
|
|
213
260
|
|
|
261
|
+
### decide
|
|
262
|
+
|
|
263
|
+
Answer a relayed permission request of a Spawn launched with
|
|
264
|
+
`relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for the
|
|
265
|
+
agent's relay hook to confirm it, and resolves with the request's
|
|
266
|
+
`delivery`.
|
|
267
|
+
|
|
214
268
|
```ts
|
|
215
|
-
await client.
|
|
269
|
+
const result = await client.decide({
|
|
270
|
+
instance_id: "<id>",
|
|
271
|
+
request_token: "<token>",
|
|
272
|
+
decision: "allow",
|
|
273
|
+
max_wait_ms: 2000, // at most your deadline minus 1 s
|
|
274
|
+
});
|
|
275
|
+
if (result.delivery === "not_confirmed") {
|
|
276
|
+
const later = await client.getPermission({ request_token: "<token>" });
|
|
277
|
+
console.log(later.delivery, later.confirm_by);
|
|
278
|
+
}
|
|
216
279
|
```
|
|
217
280
|
|
|
218
|
-
|
|
281
|
+
`"delivered"`: the relay hook confirmed the verdict before handing it to
|
|
282
|
+
the agent. `"not_confirmed"`: the relay hook has not confirmed the verdict;
|
|
283
|
+
`getPermission` exposes subsequent delivery and `confirm_by`. See the
|
|
284
|
+
[caller contract](../../docs/caller-contract.md#permission-relay) for
|
|
285
|
+
confirmation handling. `decision`
|
|
286
|
+
is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
|
|
287
|
+
bounds the whole call, its reads and its write, and has no default; without
|
|
288
|
+
it `decide` can wait up to the store's busy timeout. `decide` rejects,
|
|
289
|
+
recording no verdict, with `ErrRelayFallenBack` when the request's relay
|
|
290
|
+
hook is gone and took no verdict, with `ErrStoreBusy` when `max_wait_ms`
|
|
291
|
+
ran out before the verdict was recorded, and with
|
|
292
|
+
`ErrNoOpenPermissionRequest` when no open request has that token or the
|
|
293
|
+
request is closed. Pane answers, retries and closed-request handling are
|
|
294
|
+
in the [caller contract](../../docs/caller-contract.md#permission-relay). The
|
|
295
|
+
`permission_requests` of `get` and of each `list` row carry the same
|
|
296
|
+
delivery fields, `pane_answer` and `pane_as` included, for requests that
|
|
297
|
+
still await an answer only; a row can read `waiting`, `working` or
|
|
298
|
+
`ask_user` while a request is still open, so follow the requests you track
|
|
299
|
+
with `getPermission`.
|
|
300
|
+
`decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
|
|
301
|
+
`"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
|
|
302
|
+
do not know, read the recorded verdict from `decision` (`null` for a
|
|
303
|
+
`"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
|
|
304
|
+
`pane_answer`; never read a reason as a verdict.
|
|
305
|
+
|
|
306
|
+
`proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, its
|
|
307
|
+
tool ran (a Claude Spawn only); `"turn_end"`, the turn of the agent that asked
|
|
308
|
+
ended after it was written, which a Codex main agent's Interrupt also proves; or
|
|
309
|
+
`"agent_gone"`, the agent ended) say when and how the agent's
|
|
310
|
+
hooks showed the request's dialog gone; `"delivered"` and a pane answer are
|
|
311
|
+
agent-director's own records, not proof. `get`'s `unproven_requests` lists
|
|
312
|
+
every request not yet proven gone, each with `unproven_since`. A request
|
|
313
|
+
that reads `"delivered"` or closed at the pane can remain unproven; its dialog
|
|
314
|
+
may still be there. Handling is in the
|
|
315
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
316
|
+
|
|
317
|
+
### Answering a request at the pane
|
|
318
|
+
|
|
319
|
+
`sendKeys` with a `request_token` answers a request at the pane.
|
|
320
|
+
The [caller contract](../../docs/caller-contract.md#permission-relay) owns
|
|
321
|
+
when to use a pane answer and how to judge the screen. Example:
|
|
219
322
|
|
|
220
|
-
|
|
323
|
+
```ts
|
|
324
|
+
const seen = await client.readPane({ instance_id: "<id>" });
|
|
325
|
+
// having looked at seen.pane, the caller picks the key and the verdict it gives
|
|
326
|
+
await client.sendKeys({
|
|
327
|
+
instance_id: "<id>",
|
|
328
|
+
request_token: "<token>",
|
|
329
|
+
as: "deny",
|
|
330
|
+
key: "<key>",
|
|
331
|
+
expect_pane_sha256: seen.pane_sha256,
|
|
332
|
+
});
|
|
333
|
+
```
|
|
221
334
|
|
|
222
|
-
|
|
223
|
-
|
|
335
|
+
It sends exactly that key and no Enter, then records the request
|
|
336
|
+
`pane_answer` `"sent"` with `decision` your `as` and `decision_reason`
|
|
337
|
+
`"pane"`. `as`, `key` and `expect_pane_sha256` are required.
|
|
338
|
+
An `ErrInternal` whose `errDetails` is a `PaneKeySentDetails`
|
|
339
|
+
(`key_sent` `true`) means the key was sent but not recorded; hash use and
|
|
340
|
+
recovery are in the [caller contract](../../docs/caller-contract.md#permission-relay).
|
|
341
|
+
`recordPaneAnswer` records an answer made outside agent-director and types
|
|
342
|
+
nothing:
|
|
343
|
+
|
|
344
|
+
```ts
|
|
345
|
+
try {
|
|
346
|
+
await client.recordPaneAnswer({
|
|
347
|
+
request_token: "<token>",
|
|
348
|
+
as: "unknown",
|
|
349
|
+
expect_pane_sha256: "<pane_sha256>",
|
|
350
|
+
});
|
|
351
|
+
} catch (e) {
|
|
352
|
+
if (e instanceof ErrClaimTooSoon) {
|
|
353
|
+
// errDetails is a ClaimTooSoonDetails here.
|
|
354
|
+
console.log("retry at", e.errDetails?.["not_before"]);
|
|
355
|
+
} else {
|
|
356
|
+
throw e;
|
|
357
|
+
}
|
|
358
|
+
}
|
|
224
359
|
```
|
|
225
360
|
|
|
361
|
+
`as` is the caller's claim; use `"unknown"` when the answer was not seen.
|
|
362
|
+
`ErrPaneChanged`, `ErrPaneAnswerInProgress`, `ErrClaimTooSoon` and
|
|
363
|
+
`ErrDialogMaybeOpen` carry structured facts in `errDetails`.
|
|
364
|
+
`recordPaneAnswer` types nothing; `sendKeys` with a request token sends one
|
|
365
|
+
key and records it. Delivery does not prove the dialog gone. See
|
|
366
|
+
[Permissions](../../docs/permissions.md) and the
|
|
367
|
+
[caller contract](../../docs/caller-contract.md#permission-relay) for the
|
|
368
|
+
complete pane-answer and held-agent procedures.
|
|
369
|
+
|
|
370
|
+
## Consumption
|
|
371
|
+
|
|
372
|
+
The supported consumption mode is Bun-runtime ESM:
|
|
373
|
+
|
|
226
374
|
```ts
|
|
227
375
|
import { Client } from "agent-director";
|
|
228
376
|
```
|
|
229
377
|
|
|
230
|
-
|
|
378
|
+
Bundling without support for module-relative resource resolution is unsupported.
|
|
379
|
+
Use the package as Bun-runtime ESM.
|
|
231
380
|
|
|
232
381
|
## Versioning
|
|
233
382
|
|
|
@@ -240,8 +389,7 @@ The library version equals the agent-director release tag — released in lockst
|
|
|
240
389
|
## Minimum required CLI binary version
|
|
241
390
|
|
|
242
391
|
The library declares the minimum CLI-binary version it requires on two
|
|
243
|
-
surfaces,
|
|
244
|
-
published npm package at `dist/version-floor.json`.
|
|
392
|
+
surfaces, available from the published package at `dist/version-floor.json`.
|
|
245
393
|
|
|
246
394
|
**TS export (preferred for JS/TS consumers):**
|
|
247
395
|
|
|
@@ -256,8 +404,7 @@ if (binaryVersion === DEV_SENTINEL_VERSION) {
|
|
|
256
404
|
```
|
|
257
405
|
|
|
258
406
|
`MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
|
|
259
|
-
`0.7.0-rc1`).
|
|
260
|
-
runtime file read. `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
|
|
407
|
+
`0.7.0-rc1`). `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
|
|
261
408
|
— a dev-built CLI binary stamps this value and satisfies any floor by
|
|
262
409
|
short-circuit. The library returns the binary's reported version
|
|
263
410
|
verbatim — no leading-`v` stripping, no normalization. Consumers
|
|
@@ -273,21 +420,24 @@ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
|
|
|
273
420
|
This pattern is part of the public contract. It does not require the
|
|
274
421
|
agent-director CLI to be installed, does not spawn a JS runtime, and
|
|
275
422
|
does not require any agent-director-specific environment setup — read
|
|
276
|
-
the field from the file at the stable documented path.
|
|
277
|
-
returns a bare string suitable for shell comparison.
|
|
423
|
+
the field from the file at the stable documented path.
|
|
278
424
|
|
|
279
425
|
## Supported Bun versions
|
|
280
426
|
|
|
281
|
-
Minimum: `>=1.0.21` (set in `engines.bun`).
|
|
427
|
+
Minimum: `>=1.0.21` (set in `engines.bun`). The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
|
|
282
428
|
|
|
283
429
|
## Errors
|
|
284
430
|
|
|
285
|
-
|
|
431
|
+
Named client and CLI errors extend `AgentDirectorError`, so you can catch
|
|
432
|
+
by subclass with `instanceof`. Subprocess spawn failures can also surface
|
|
433
|
+
as their original errors: an unclassified `ENOENT` (neither the binary nor
|
|
434
|
+
the caller's cwd is verifiably gone) and every other spawn failure are
|
|
435
|
+
re-thrown unchanged. Keep a general fallback catch for these paths:
|
|
286
436
|
|
|
287
437
|
```ts
|
|
288
438
|
import { Client, ErrSpawnNotFound } from "agent-director";
|
|
289
439
|
try {
|
|
290
|
-
await client.status({
|
|
440
|
+
await client.status({ instance_id: "bogus" });
|
|
291
441
|
} catch (e) {
|
|
292
442
|
if (e instanceof ErrSpawnNotFound) {
|
|
293
443
|
// recover
|
|
@@ -297,24 +447,24 @@ try {
|
|
|
297
447
|
}
|
|
298
448
|
```
|
|
299
449
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
450
|
+
Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
|
|
451
|
+
the error envelope's optional `err_details` object, or `null`. Five errors
|
|
452
|
+
carry one, typed as exported interfaces: `ErrRelayFallenBack`
|
|
453
|
+
(`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
|
|
454
|
+
(`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
|
|
455
|
+
`ErrPaneChanged` (`PaneChangedDetails`) and `ErrDialogMaybeOpen`
|
|
456
|
+
(`DialogMaybeOpenDetails`). So does the `ErrInternal` of a
|
|
457
|
+
pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
|
|
458
|
+
`key_sent` `true` and `request_token`). Read facts from `errDetails`, never
|
|
459
|
+
from `errDescription`.
|
|
460
|
+
|
|
461
|
+
The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the CLI error contract also applies to group 4.
|
|
462
|
+
|
|
463
|
+
For retry, escalation and shared CLI refusal handling see the
|
|
464
|
+
[caller contract](../../docs/caller-contract.md). Binary installation and
|
|
465
|
+
upgrade procedures are in [Installation](../../docs/install.md), and
|
|
466
|
+
human repairs in [Operator actions](../../docs/operator-actions.md).
|
|
467
|
+
The tables below describe the typed classes and their fields.
|
|
318
468
|
|
|
319
469
|
### 1. Library lifecycle
|
|
320
470
|
|
|
@@ -323,19 +473,19 @@ Raised by the client wrapper itself, independent of any agent-director binary.
|
|
|
323
473
|
| Error | When it fires |
|
|
324
474
|
|---|---|
|
|
325
475
|
| `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
|
|
326
|
-
| `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum.
|
|
476
|
+
| `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Fires at construction. |
|
|
327
477
|
|
|
328
478
|
### 2. System install (agent-director binary)
|
|
329
479
|
|
|
330
|
-
|
|
480
|
+
**Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
|
|
331
481
|
|
|
332
482
|
| Error | Phase | When it fires |
|
|
333
483
|
|---|---|---|
|
|
334
484
|
| `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
|
|
335
485
|
| `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
|
|
336
486
|
| `ErrSystemInstallUnreachable` | Construction | A binary was found but failed the version probe (not executable, wrong arch, non-zero exit, killed). Carries `binaryPath`, `reason`, `diagnostic`, `exitCode`, `signal`. |
|
|
337
|
-
| `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`.
|
|
338
|
-
| `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`.
|
|
487
|
+
| `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. See [Installation](../../docs/install.md) for environment requirements. |
|
|
488
|
+
| `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Installation repair is owned by [Installation](../../docs/install.md). |
|
|
339
489
|
|
|
340
490
|
### 3. Per-call infrastructure
|
|
341
491
|
|
|
@@ -343,13 +493,13 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
|
|
|
343
493
|
|
|
344
494
|
| Error | When it fires | Category |
|
|
345
495
|
|---|---|---|
|
|
346
|
-
| `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational
|
|
496
|
+
| `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational; see the caller contract. |
|
|
347
497
|
| `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
|
|
348
|
-
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for
|
|
498
|
+
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for. This client has a class for every `err_name` the binary of its own version gives, so the binary is of a different version, most often a newer one. Carries `unknownName` (the real `err_name`) and `envelope`. | Version error; see [Installation](../../docs/install.md). |
|
|
349
499
|
|
|
350
500
|
### 4. Catalog-derived (CLI-side validation)
|
|
351
501
|
|
|
352
|
-
These
|
|
502
|
+
These classes correspond to the shared CLI `err_name` contract. They surface bad input, a verb's own state preconditions, a config or store the CLI cannot open, or a failure of the CLI itself — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
|
|
353
503
|
|
|
354
504
|
**cwd validation** (bad `cwd` argument to `spawn` — programmer error):
|
|
355
505
|
|
|
@@ -360,14 +510,19 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
360
510
|
| `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
|
|
361
511
|
| `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
|
|
362
512
|
|
|
363
|
-
**spawn config validation** (bad `spawn` arguments — programmer error):
|
|
513
|
+
**spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
|
|
364
514
|
|
|
365
515
|
| Error | When it fires |
|
|
366
516
|
|---|---|
|
|
367
517
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
368
|
-
| `ErrSpawnDeniedFlag` | `
|
|
369
|
-
| `
|
|
370
|
-
| `
|
|
518
|
+
| `ErrSpawnDeniedFlag` | The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
|
|
519
|
+
| `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"` or `"codex"`), or put one in the template. |
|
|
520
|
+
| `ErrAgentInvalid` | `agent` is neither `"claude"` nor `"codex"` (the value is case-sensitive); nothing is written. |
|
|
521
|
+
| `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
|
|
522
|
+
| `ErrTemplateAgentMissing` | A template has `agent_args` and names no agent. From `makeTemplate` (`agent_args` without `agent`) and from a `spawn` that loads such a template; nothing is written. Give the template an `agent`, or remove its `agent_args`. |
|
|
523
|
+
| `ErrPermissionsUnsupported` | A `"codex"` spawn, or a `makeTemplate` with `agent: "codex"`, carries an `allow`, `deny` or `ask` entry; nothing is written. Drop the lists and set permission rules in the group's Codex folder, with Codex's own permission controls. |
|
|
524
|
+
| `ErrReservedEnvKey` | From `spawn`: an `extra_env` key (a template's included) is reserved or is not a valid env-var name; nothing is written or launched, and the description says which. Reserved: an `AGENT_DIRECTOR_*` key, or a key that sets `HOME` (`HOME` itself, or one such as `HOME=/x`), with any value, an empty one included. An `extra_env` `HOME` would send the agent's hook events to another agent-director store; set an absolute `CLAUDE_CONFIG_DIR` (a Claude Code agent) or `CODEX_HOME` (a Codex agent) to give the agent its own config. Not a valid name: the key is empty, or contains `=` or a NUL character; give each variable its own name as the key and its value as the value (`{ CLAUDE_CONFIG_DIR: "/cfg" }`, not `{ "CLAUDE_CONFIG_DIR=/cfg": "" }`). This client refuses an invalid key in the call's `extra_env` itself, before it runs the CLI. From `makeTemplate`: the template's `extra_env` has such a key, reserved or not a valid name, refused by spawn's own check; no template is written or replaced, so none is saved that `spawn` would refuse (this client refuses an invalid key itself, as for `spawn`). From `resume`: the row's stored `extra_env` has a key that sets `HOME` or is not a valid name (a row spawned before spawn refused it); nothing is written or launched. Shared repair and reuse handling is in [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals); a fresh conversation has no memory of the old conversation. |
|
|
525
|
+
| `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
|
|
371
526
|
|
|
372
527
|
**tmux session naming** (bad `tmux_session_name` — programmer error):
|
|
373
528
|
|
|
@@ -381,13 +536,13 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
381
536
|
|
|
382
537
|
| Error | When it fires |
|
|
383
538
|
|---|---|
|
|
384
|
-
| `ErrSpawnNotFound` | No spawn row matches the supplied `
|
|
539
|
+
| `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
|
|
385
540
|
| `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
|
|
386
541
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
387
|
-
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`.
|
|
388
|
-
| `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included.
|
|
389
|
-
| `ErrNoSessionId` | The spawn has no `
|
|
390
|
-
| `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path
|
|
542
|
+
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
|
|
543
|
+
| `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
|
|
544
|
+
| `ErrNoSessionId` | The spawn has no `session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume; recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
|
|
545
|
+
| `ErrJsonlMissing` | The current session's resume JSONL could not be located at any candidate path (for a Codex agent, only its current recorded path; older sessions are never tried); recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
|
|
391
546
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
392
547
|
| `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
|
|
393
548
|
|
|
@@ -396,10 +551,10 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
396
551
|
| Error | Class | When it fires |
|
|
397
552
|
|---|---|---|
|
|
398
553
|
| `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
|
|
399
|
-
| `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled
|
|
400
|
-
| `ErrTmuxUnresponsive` | UNAVAILABLE
|
|
401
|
-
| `ErrTmuxSessionConflict` | CONFLICT
|
|
402
|
-
| `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry
|
|
554
|
+
| `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled. A plain launch normally stays `pending`; a duplicate-name re-lookup finding no holder ends its new row. Resume and reuse attempt a guarded restore after a non-timeout failure; the description reports whether it applied. |
|
|
555
|
+
| `ErrTmuxUnresponsive` | UNAVAILABLE | tmux did not answer usably, or a launch still appears to be starting or stopping. A timed-out launch stays `pending`; after a timed-out send, keys may have been delivered. See the [caller contract](../../docs/caller-contract.md#caller-contract) before retrying. |
|
|
556
|
+
| `ErrTmuxSessionConflict` | CONFLICT | A held name, a session left over from an earlier life (an earlier launch), conflicting labels, or the agent pane was not found. The description names the blocker and whether a new row was ended or a prior row restored. Nothing is sent to a conflicting session. Human repair is owned by [Operator actions](../../docs/operator-actions.md). |
|
|
557
|
+
| `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry and refusal handling is owned by [Caller contract](../../docs/caller-contract.md). |
|
|
403
558
|
| `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
|
|
404
559
|
| `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
|
|
405
560
|
|
|
@@ -409,13 +564,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
409
564
|
|
|
410
565
|
| Error | When it fires |
|
|
411
566
|
|---|---|
|
|
412
|
-
| `ErrSendKeysWhileRelayed` | `
|
|
413
|
-
| `ErrRelayFallenBack` | `decide`
|
|
567
|
+
| `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while a relay hook may still answer a request. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
|
|
568
|
+
| `ErrRelayFallenBack` | A request's relay hook is gone and acked no verdict, with no pane answer recorded through agent-director: no answer from the relay reached the agent. Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
|
|
569
|
+
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by the agent's hooks (a Claude agent's tool's PostToolUse, the main agent's end of turn after it (on a Codex Spawn, its `Stop` or Interrupt), or the agent's end), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A subagent's denied request holds until the agent ends, and on a Codex Spawn so does an allowed one. `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
|
|
570
|
+
| `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
571
|
+
| `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
|
|
572
|
+
| `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
414
573
|
| `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
|
|
415
|
-
| `ErrInvalidDecision` |
|
|
574
|
+
| `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
|
|
416
575
|
| `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
|
|
417
|
-
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was
|
|
418
|
-
| `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. |
|
|
576
|
+
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request's relay hook confirmed a verdict recorded on it, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (`"delivered"` only if its relay hook confirmed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
|
|
577
|
+
| `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay hook denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the hook recorded that deny with its confirmation before returning it to the agent, so there is nothing to answer at the pane. It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay hook confirmed, or one already closed at the pane, throws it too. |
|
|
578
|
+
| `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and the bound ran out, during its reads or its write, before its verdict was recorded: another agent-director process held the store that long (or, for a request recorded by an older binary, `decide` would have had to wait past the bound for the end of its relay window). Nothing was recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). Once the verdict is recorded, `decide` never throws it: a bound reached while it waits for the relay hook's confirmation resolves with `delivery` `"not_confirmed"`. Without `max_wait_ms`, `decide` never throws it. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout; nothing was sent or recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). |
|
|
419
579
|
| `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
|
|
420
580
|
| `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
|
|
421
581
|
|
|
@@ -425,22 +585,35 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
425
585
|
|---|---|
|
|
426
586
|
| `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
|
|
427
587
|
| `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
|
|
428
|
-
| `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
|
|
429
|
-
| `ErrTemplateExists` | `make-template` target already exists
|
|
588
|
+
| `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude` or `codex`, the old name of the `agent_args` key, wrong types, bad enums, or one key set under names that differ only in letter case, such as `RELAY_MODE` and `relay_mode`). `makeTemplate` also throws it, before writing anything, for an `agent` that is not exactly `claude` or `codex`. |
|
|
589
|
+
| `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
|
|
430
590
|
|
|
431
591
|
**misc**:
|
|
432
592
|
|
|
433
593
|
| Error | When it fires |
|
|
434
594
|
|---|---|
|
|
435
|
-
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation,
|
|
595
|
+
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation; a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
|
|
596
|
+
|
|
597
|
+
**CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
|
|
598
|
+
|
|
599
|
+
| Error | When it fires |
|
|
600
|
+
|---|---|
|
|
601
|
+
| `ErrConfigMalformed` | The CLI refused its config file, `~/.config/agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. See the caller contract for handling. |
|
|
602
|
+
| `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. With `createIfMissing: false` it includes a store that does not exist (`database not initialized`); nothing was created. It says nothing about any agent. |
|
|
603
|
+
| `ErrSchemaMismatch` | The CLI refused to open its store: the store was written by a newer agent-director than the binary (`found user_version=<N>, want <M>`), or it has no valid store id. The description says which. Nothing was written, and every call that opens the store fails this way until an operator acts: a newer store needs the agent-director release that wrote it. See Operator actions for recovery. It says nothing about any agent. |
|
|
604
|
+
| `ErrSchemaMigrationRequired` | The CLI refused to open its store: the store is older than the binary and must be migrated first. The description gives both schema versions. Nothing was written, and every call that opens the store fails this way until an administrator migrates the store; no call through this client can. See the caller contract for handling. It says nothing about any agent. |
|
|
605
|
+
| `ErrOldLayout` | The CLI refused to open its store: it was about to open the default store (no `storePath`, and no `[store] db_path` in its config file), no store exists in `~/.config/agent-director`, and the old directory exists. Nothing was created, and every call that opens the store fails this way until an operator runs this release's `install.sh`. See the caller contract for handling. It says nothing about any agent. |
|
|
436
606
|
|
|
437
|
-
**CLI
|
|
607
|
+
**CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
|
|
438
608
|
|
|
439
609
|
| Error | When it fires |
|
|
440
610
|
|---|---|
|
|
441
|
-
| `
|
|
442
|
-
| `
|
|
611
|
+
| `ErrInternal` | A CLI failure with no more specific name. Its description reports what failed and whether anything changed. A pane answer whose key was sent but not recorded carries `PaneKeySentDetails` with `key_sent: true`; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
|
|
612
|
+
| `ErrJSONMarshal` | The verb ran and succeeded, but the CLI could not write its JSON result, so the result is lost and whatever the call changes was changed (a `spawn` launched its agent). A bug in agent-director. Check with `get`, `status` or `list` before you repeat a call that changes something. |
|
|
613
|
+
| `ErrUnknownVerb` | The binary does not know the called verb. No verb ran; binary and client versions differ. See [Installation](../../docs/install.md). |
|
|
614
|
+
| `ErrTrailWrite` | Only the CLI's internal `trail-emit` command gives it, when it cannot write its trail event. No method of this client runs `trail-emit`, so a call through this client does not get it. |
|
|
443
615
|
|
|
444
|
-
##
|
|
616
|
+
## See also
|
|
445
617
|
|
|
446
|
-
|
|
618
|
+
[Caller contract](../../docs/caller-contract.md), [Permissions](../../docs/permissions.md)
|
|
619
|
+
and [Installation](../../docs/install.md) own shared procedures.
|