agent-director 0.11.0 → 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 +326 -133
- package/dist/errors.d.ts +114 -7
- package/dist/index.d.ts +4 -3
- package/dist/index.js +342 -56
- package/dist/internal/argv.d.ts +28 -15
- package/dist/internal/discovery.d.ts +3 -2
- package/dist/internal/errorMap.d.ts +11 -5
- package/dist/internal/subprocessClient.d.ts +37 -6
- package/dist/internal/verbs.d.ts +4 -4
- package/dist/types.d.ts +687 -152
- package/dist/version-floor.json +1 -1
- package/package.json +1 -1
- package/dist/internal/tilde.d.ts +0 -16
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,70 +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.
|
|
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)
|
|
64
|
+
|
|
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`
|
|
67
|
+
set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
|
|
68
|
+
`HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
|
|
69
|
+
`ErrInvalidFlags`, and with no `home` either, every call that opens the store
|
|
70
|
+
is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
|
|
71
|
+
expand its config path `~/.config/agent-director/config.toml`.
|
|
75
72
|
|
|
76
|
-
Set them
|
|
73
|
+
Set them when the consumer needs to override that field's CLI default.
|
|
74
|
+
|
|
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).
|
|
77
83
|
|
|
78
84
|
## Verb examples
|
|
79
85
|
|
|
80
|
-
|
|
86
|
+
Shared CLI use is in [Usage](../../docs/usage.md).
|
|
81
87
|
|
|
82
|
-
|
|
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.
|
|
83
91
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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.
|
|
87
95
|
|
|
88
96
|
```ts
|
|
89
|
-
const result = await client.spawn({ cwd: "~/my-project" });
|
|
90
|
-
console.log(result.
|
|
97
|
+
const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
|
|
98
|
+
console.log(result.instance_id);
|
|
91
99
|
```
|
|
92
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
|
+
|
|
93
114
|
### status
|
|
94
115
|
|
|
95
116
|
Get the current lifecycle state of a Spawn.
|
|
96
117
|
|
|
97
|
-
```sh
|
|
98
|
-
agent-director status --claude-instance-id <id>
|
|
99
|
-
```
|
|
100
|
-
|
|
101
118
|
```ts
|
|
102
|
-
const result = await client.status({
|
|
119
|
+
const result = await client.status({ instance_id: "<id>" });
|
|
103
120
|
console.log(result.state);
|
|
104
121
|
```
|
|
105
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
|
+
|
|
106
131
|
### list
|
|
107
132
|
|
|
108
133
|
Query Spawns with optional filters.
|
|
109
134
|
|
|
110
|
-
```sh
|
|
111
|
-
agent-director list --state waiting
|
|
112
|
-
```
|
|
113
|
-
|
|
114
135
|
```ts
|
|
115
136
|
const result = await client.list({ state: ["waiting"] });
|
|
116
137
|
for (const spawn of result.spawns) {
|
|
117
|
-
console.log(spawn.
|
|
138
|
+
console.log(spawn.instance_id, spawn.state, spawn.agent);
|
|
118
139
|
}
|
|
119
140
|
```
|
|
120
141
|
|
|
121
|
-
|
|
142
|
+
Each row, like `get`'s result, carries `agent` (`"claude"` or `"codex"`), the agent the row runs.
|
|
122
143
|
|
|
123
|
-
|
|
124
|
-
`text` sends the Enter only, submitting what is already typed.
|
|
144
|
+
### listSubagents
|
|
125
145
|
|
|
126
|
-
|
|
127
|
-
|
|
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
|
+
}
|
|
128
157
|
```
|
|
129
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
|
+
|
|
130
174
|
```ts
|
|
131
|
-
await client.sendKeys({
|
|
175
|
+
await client.sendKeys({ instance_id: "<id>", text: "what is 2+2?" });
|
|
132
176
|
```
|
|
133
177
|
|
|
134
178
|
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
@@ -139,30 +183,23 @@ still rejected. A `pending` row whose launch start or launch token is not record
|
|
|
139
183
|
only a session an earlier launch left behind is found, gets
|
|
140
184
|
`ErrSpawnNotInteractive` and nothing is sent.
|
|
141
185
|
|
|
142
|
-
|
|
143
|
-
a
|
|
144
|
-
|
|
145
|
-
```ts
|
|
146
|
-
await client.sendKeys({
|
|
147
|
-
claude_instance_id: "<id>",
|
|
148
|
-
text: "",
|
|
149
|
-
allow_pending: true,
|
|
150
|
-
});
|
|
151
|
-
```
|
|
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).
|
|
152
189
|
|
|
153
190
|
### readPane
|
|
154
191
|
|
|
155
192
|
Read the last N lines of the agent's own pane (default 25).
|
|
156
193
|
|
|
157
|
-
```sh
|
|
158
|
-
agent-director read-pane --claude-instance-id <id> --n-lines 50
|
|
159
|
-
```
|
|
160
|
-
|
|
161
194
|
```ts
|
|
162
|
-
const result = await client.readPane({
|
|
163
|
-
console.log(result.pane);
|
|
195
|
+
const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
|
|
196
|
+
console.log(result.pane, result.pane_sha256);
|
|
164
197
|
```
|
|
165
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
|
+
|
|
166
203
|
`readPane` has no state guard — it works on `pending`, `ended`, and `missing`
|
|
167
204
|
rows as well as live ones. The `allow_pending` flag is accepted for symmetry
|
|
168
205
|
with `sendKeys` but has no behavioral effect.
|
|
@@ -179,47 +216,167 @@ resolves with `kill_sent: false`; that is not verification that the agent
|
|
|
179
216
|
exited. `kill` never changes the row's state: `find-missing` marks the row once
|
|
180
217
|
its agent process is gone.
|
|
181
218
|
|
|
182
|
-
```sh
|
|
183
|
-
agent-director kill --claude-instance-id <id>
|
|
184
|
-
```
|
|
185
|
-
|
|
186
219
|
```ts
|
|
187
|
-
const { kill_sent } = await client.kill({
|
|
220
|
+
const { kill_sent } = await client.kill({ instance_id: "<id>" });
|
|
188
221
|
console.log(kill_sent);
|
|
189
222
|
```
|
|
190
223
|
|
|
191
224
|
Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
|
|
192
|
-
retry later), `ErrTmuxSessionConflict` (CONFLICT
|
|
193
|
-
`ErrTmuxNotAvailable` (ENVIRONMENT
|
|
194
|
-
`ErrSpawnNotFound`. None of these
|
|
195
|
-
|
|
196
|
-
|
|
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).
|
|
197
252
|
|
|
198
253
|
### makeTemplate
|
|
199
254
|
|
|
200
|
-
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.
|
|
201
256
|
|
|
202
|
-
```
|
|
203
|
-
|
|
257
|
+
```ts
|
|
258
|
+
await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
|
|
204
259
|
```
|
|
205
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
|
+
|
|
206
268
|
```ts
|
|
207
|
-
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
|
+
}
|
|
208
279
|
```
|
|
209
280
|
|
|
210
|
-
|
|
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:
|
|
211
322
|
|
|
212
|
-
|
|
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
|
+
```
|
|
213
334
|
|
|
214
|
-
|
|
215
|
-
|
|
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
|
+
}
|
|
216
359
|
```
|
|
217
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
|
+
|
|
218
374
|
```ts
|
|
219
375
|
import { Client } from "agent-director";
|
|
220
376
|
```
|
|
221
377
|
|
|
222
|
-
|
|
378
|
+
Bundling without support for module-relative resource resolution is unsupported.
|
|
379
|
+
Use the package as Bun-runtime ESM.
|
|
223
380
|
|
|
224
381
|
## Versioning
|
|
225
382
|
|
|
@@ -232,8 +389,7 @@ The library version equals the agent-director release tag — released in lockst
|
|
|
232
389
|
## Minimum required CLI binary version
|
|
233
390
|
|
|
234
391
|
The library declares the minimum CLI-binary version it requires on two
|
|
235
|
-
surfaces,
|
|
236
|
-
published npm package at `dist/version-floor.json`.
|
|
392
|
+
surfaces, available from the published package at `dist/version-floor.json`.
|
|
237
393
|
|
|
238
394
|
**TS export (preferred for JS/TS consumers):**
|
|
239
395
|
|
|
@@ -248,8 +404,7 @@ if (binaryVersion === DEV_SENTINEL_VERSION) {
|
|
|
248
404
|
```
|
|
249
405
|
|
|
250
406
|
`MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
|
|
251
|
-
`0.7.0-rc1`).
|
|
252
|
-
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"`
|
|
253
408
|
— a dev-built CLI binary stamps this value and satisfies any floor by
|
|
254
409
|
short-circuit. The library returns the binary's reported version
|
|
255
410
|
verbatim — no leading-`v` stripping, no normalization. Consumers
|
|
@@ -265,21 +420,24 @@ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
|
|
|
265
420
|
This pattern is part of the public contract. It does not require the
|
|
266
421
|
agent-director CLI to be installed, does not spawn a JS runtime, and
|
|
267
422
|
does not require any agent-director-specific environment setup — read
|
|
268
|
-
the field from the file at the stable documented path.
|
|
269
|
-
returns a bare string suitable for shell comparison.
|
|
423
|
+
the field from the file at the stable documented path.
|
|
270
424
|
|
|
271
425
|
## Supported Bun versions
|
|
272
426
|
|
|
273
|
-
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+.
|
|
274
428
|
|
|
275
429
|
## Errors
|
|
276
430
|
|
|
277
|
-
|
|
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:
|
|
278
436
|
|
|
279
437
|
```ts
|
|
280
438
|
import { Client, ErrSpawnNotFound } from "agent-director";
|
|
281
439
|
try {
|
|
282
|
-
await client.status({
|
|
440
|
+
await client.status({ instance_id: "bogus" });
|
|
283
441
|
} catch (e) {
|
|
284
442
|
if (e instanceof ErrSpawnNotFound) {
|
|
285
443
|
// recover
|
|
@@ -289,20 +447,24 @@ try {
|
|
|
289
447
|
}
|
|
290
448
|
```
|
|
291
449
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
-
|
|
304
|
-
|
|
305
|
-
|
|
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.
|
|
306
468
|
|
|
307
469
|
### 1. Library lifecycle
|
|
308
470
|
|
|
@@ -311,19 +473,19 @@ Raised by the client wrapper itself, independent of any agent-director binary.
|
|
|
311
473
|
| Error | When it fires |
|
|
312
474
|
|---|---|
|
|
313
475
|
| `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
|
|
314
|
-
| `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. |
|
|
315
477
|
|
|
316
478
|
### 2. System install (agent-director binary)
|
|
317
479
|
|
|
318
|
-
|
|
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.
|
|
319
481
|
|
|
320
482
|
| Error | Phase | When it fires |
|
|
321
483
|
|---|---|---|
|
|
322
484
|
| `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
|
|
323
485
|
| `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
|
|
324
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`. |
|
|
325
|
-
| `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`.
|
|
326
|
-
| `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). |
|
|
327
489
|
|
|
328
490
|
### 3. Per-call infrastructure
|
|
329
491
|
|
|
@@ -331,13 +493,13 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
|
|
|
331
493
|
|
|
332
494
|
| Error | When it fires | Category |
|
|
333
495
|
|---|---|---|
|
|
334
|
-
| `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. |
|
|
335
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. |
|
|
336
|
-
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client
|
|
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). |
|
|
337
499
|
|
|
338
500
|
### 4. Catalog-derived (CLI-side validation)
|
|
339
501
|
|
|
340
|
-
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.
|
|
341
503
|
|
|
342
504
|
**cwd validation** (bad `cwd` argument to `spawn` — programmer error):
|
|
343
505
|
|
|
@@ -348,14 +510,19 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
348
510
|
| `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
|
|
349
511
|
| `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
|
|
350
512
|
|
|
351
|
-
**spawn config validation** (bad `spawn` arguments — programmer error):
|
|
513
|
+
**spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
|
|
352
514
|
|
|
353
515
|
| Error | When it fires |
|
|
354
516
|
|---|---|
|
|
355
517
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
356
|
-
| `ErrSpawnDeniedFlag` | `
|
|
357
|
-
| `
|
|
358
|
-
| `
|
|
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. |
|
|
359
526
|
|
|
360
527
|
**tmux session naming** (bad `tmux_session_name` — programmer error):
|
|
361
528
|
|
|
@@ -369,13 +536,13 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
369
536
|
|
|
370
537
|
| Error | When it fires |
|
|
371
538
|
|---|---|
|
|
372
|
-
| `ErrSpawnNotFound` | No spawn row matches the supplied `
|
|
539
|
+
| `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
|
|
373
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. |
|
|
374
541
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
375
|
-
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`.
|
|
376
|
-
| `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. Also returned when the row changed after `resume` examined it; nothing is written. |
|
|
377
|
-
| `ErrNoSessionId` | The spawn has no `
|
|
378
|
-
| `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. |
|
|
379
546
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
380
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. |
|
|
381
548
|
|
|
@@ -384,10 +551,10 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
384
551
|
| Error | Class | When it fires |
|
|
385
552
|
|---|---|---|
|
|
386
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. |
|
|
387
|
-
| `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled
|
|
388
|
-
| `ErrTmuxUnresponsive` | UNAVAILABLE
|
|
389
|
-
| `ErrTmuxSessionConflict` | CONFLICT
|
|
390
|
-
| `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). |
|
|
391
558
|
| `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
|
|
392
559
|
| `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
|
|
393
560
|
|
|
@@ -397,12 +564,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
397
564
|
|
|
398
565
|
| Error | When it fires |
|
|
399
566
|
|---|---|
|
|
400
|
-
| `ErrSendKeysWhileRelayed` | `
|
|
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). |
|
|
401
573
|
| `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
|
|
402
|
-
| `ErrInvalidDecision` |
|
|
574
|
+
| `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
|
|
403
575
|
| `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
|
|
404
|
-
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was
|
|
405
|
-
| `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). |
|
|
406
579
|
| `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
|
|
407
580
|
| `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
|
|
408
581
|
|
|
@@ -412,15 +585,35 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
412
585
|
|---|---|
|
|
413
586
|
| `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
|
|
414
587
|
| `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
|
|
415
|
-
| `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
|
|
416
|
-
| `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`. |
|
|
417
590
|
|
|
418
591
|
**misc**:
|
|
419
592
|
|
|
420
593
|
| Error | When it fires |
|
|
421
594
|
|---|---|
|
|
422
|
-
| `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. |
|
|
606
|
+
|
|
607
|
+
**CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
|
|
608
|
+
|
|
609
|
+
| Error | When it fires |
|
|
610
|
+
|---|---|
|
|
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. |
|
|
423
615
|
|
|
424
|
-
##
|
|
616
|
+
## See also
|
|
425
617
|
|
|
426
|
-
|
|
618
|
+
[Caller contract](../../docs/caller-contract.md), [Permissions](../../docs/permissions.md)
|
|
619
|
+
and [Installation](../../docs/install.md) own shared procedures.
|