agent-director 0.18.3 → 0.18.5

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.
Files changed (2) hide show
  1. package/README.md +227 -338
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,11 +1,8 @@
1
1
  # agent-director
2
2
 
3
- TypeScript/Bun client for the agent-director CLI. Shares the Go API's verbs
4
- and CLI semantics; native request and proof fields have the declaration and
5
- runtime limitations described under [sendKeys](#sendkeys).
6
- The `Client` discovers the system-installed
7
- `agent-director` CLI binary at construction time and drives it as a
8
- subprocess per verb call — no FFI, no network hop, no bundled binary.
3
+ TypeScript/Bun client for agent-director. `Client.create()` discovers the
4
+ installed binary and each verb call runs it as a subprocess. Native request
5
+ and proof fields have the declaration limits described under [sendKeys](#sendkeys).
9
6
 
10
7
  ## Install
11
8
 
@@ -13,23 +10,18 @@ subprocess per verb call — no FFI, no network hop, no bundled binary.
13
10
  bun add agent-director
14
11
  ```
15
12
 
16
- Requires Bun >=1.0.21. The package ships pure JavaScript — there are
17
- **no lifecycle scripts** (`postinstall`, `prepare`, etc.) and no
18
- optional platform dependencies. `bun add --ignore-scripts agent-director`
19
- is a no-op and installs the library with identical functionality.
13
+ Requires Bun >=1.0.21. The package contains JavaScript with no lifecycle
14
+ scripts, optional platform dependencies or bundled binary. Installing with
15
+ `bun add --ignore-scripts agent-director` gives identical functionality.
20
16
 
21
- Install the CLI separately using the [install guide](../../docs/install.md).
17
+ Install the binary separately using the [install guide](../../docs/install.md).
22
18
  `Client.create()` finds it at the standard install path or on `$PATH`;
23
- its version must meet the client floor.
19
+ its version must meet the [client floor](#minimum-required-cli-binary-version).
24
20
 
25
21
  ## Supported platforms
26
22
 
27
- - `linux/x64` (Linux on x86_64)
28
- - `linux/arm64` (Linux on arm64/aarch64)
29
- - `darwin/arm64` (Apple Silicon Mac, macOS 13 or later)
30
-
31
- Package installation may also succeed on `darwin/x64`, where no CLI installs.
32
- See [Requirements](../../docs/install.md#requirements).
23
+ See [Requirements](../../docs/install.md#requirements) for supported binary
24
+ platforms. Package installation alone does not establish platform support.
33
25
 
34
26
  ## Quick start
35
27
 
@@ -56,45 +48,31 @@ try {
56
48
  }
57
49
  ```
58
50
 
59
- 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"]`).
60
-
61
- `ClientOptions` overrides forward to the CLI subprocess as global flags:
62
-
63
- - `storePath` → `--store-path`
64
- - `home` → `--home`
65
- - `tmuxCommand` → `--tmux-command`
66
- - `createIfMissing: false` → `--create-if-missing false` (`true` forwards nothing)
67
-
68
- The paths are forwarded verbatim. The CLI, not the client, expands a `~` in
69
- them, against `HOME` and nothing else (never the passwd entry's home). It applies `home` first, so with `home`
70
- set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
71
- `HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
72
- `ErrInvalidFlags`, and with no `home` either, every call that opens the store
73
- is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
74
- expand its config path `~/.config/agent-director/config.toml`.
75
-
76
- Set them when the consumer needs to override that field's CLI default.
77
-
78
- `callTimeoutMs` defaults to 30,000 ms per subprocess call. Cursor's separate
79
- 45-second ACP operation bound does not extend that client budget. Spawn and
80
- resume do not wait for initialization, load, generation, a dialog answer or
81
- readiness. For a deliberately longer
82
- configured `pause.timeout_seconds`, give the client enough `callTimeoutMs`
83
- for that wait and reply overhead; 30 seconds is not a universal operation cap.
84
-
85
- By default, the first call that opens the store creates it when it does not
86
- exist (parent directories, file and schema). With `createIfMissing: false`,
87
- such a call rejects with `ErrStoreOpen` (`database not initialized`) and
88
- creates none of it; an existing store opens as usual, and calls that open no
89
- store, such as `version`, are unaffected.
51
+ All `ClientOptions` fields are optional. Omitted store, home and tmux options
52
+ use the binary's configuration and defaults. The `using` form calls
53
+ `client.close()` at block exit; TypeScript projects need
54
+ `"lib": ["ESNext.Disposable"]`.
55
+
56
+ - `storePath`: store path.
57
+ - `home`: home used for configuration and path expansion.
58
+ - `tmuxCommand`: tmux executable.
59
+ - `createIfMissing`: defaults to true; create the store on its first use.
60
+ False leaves an absent store uncreated and returns `ErrStoreOpen`.
61
+ Calls such as `version` that do not open the store are unaffected.
62
+ - `callTimeoutMs`: defaults to 30,000 ms per subprocess call. Allow enough
63
+ time for configured pause waits, input delivery and reply overhead.
64
+
65
+ Paths are forwarded verbatim. The binary expands `~` against `home` when
66
+ set, otherwise `HOME`, never the passwd home. It applies `home` before
67
+ expanding `storePath` or `tmuxCommand`. Environment refusals and timeout handling are in the
68
+ [caller contract](../../docs/caller-contract.md#caller-contract); a timeout
69
+ does not prove the operation stopped.
90
70
 
91
71
  For spawning under another home or store, use
92
72
  [Permissions](../../docs/permissions.md#one-spawn-under-another-home-or-store).
93
73
 
94
74
  ## Verb examples
95
75
 
96
- Shared CLI use is in [Usage](../../docs/usage.md).
97
-
98
76
  A call that carries an old name of a renamed key (on any verb) throws
99
77
  `ErrInvalidFlags` before the client starts any process; its description names
100
78
  the new key.
@@ -103,6 +81,11 @@ the new key.
103
81
 
104
82
  Launch a tracked agent in a new tmux session. A spawn names its agent, `"claude"`, `"codex"` or `"cursor"` (case-sensitive), in `agent` or through its template; with neither it throws `ErrAgentMissing`. An empty `agent` counts as not given.
105
83
 
84
+ An explicit `instance_id` cannot contain ASCII control bytes (`0x00`–`0x1f`
85
+ or `0x7f`). Each `extra_env` key must be nonempty with no `=` or NUL;
86
+ reserved keys and account selection are covered by
87
+ [Settings](../../docs/settings.md#templates-and-per-call-merge).
88
+
106
89
  ```ts
107
90
  const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
108
91
  console.log(result.instance_id);
@@ -124,24 +107,12 @@ opt-out, never a validated `"ok"`; see
124
107
  whole seconds (`0`, `null` or omitted for none); its range and lifecycle are
125
108
  in [Configuration](../../docs/configuration.md#idle-screen-timeout-state).
126
109
 
127
- For all agents, same-agent reuse retains current-life session history and subagent records;
128
- switching agents starts another life, including when switching back.
129
- `resume` continues only the recorded agent's latest reported session and
130
- never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
131
- and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
132
-
133
- Cursor uses the existing result and row fields; `status` keeps its existing
134
- shape. `resume({ instance_id: id })` launches load of only its latest saved session;
135
- the row can remain `pending` until a real first prompt. After inspecting the
136
- pane, pass `allow_pending: true` to `sendKeys` for that prompt; binding and
137
- dialog guards still apply. Saved configuration replay, which never includes
138
- the initial prompt, is defined in [Pause and resume](../../docs/usage.md#pause-and-resume).
139
- `reuse_finished: true` supports Cursor and agent switches under the linked
140
- life rules. `makeTemplate`
141
- and `spawn` refuse nonempty Cursor permission lists with
142
- `ErrPermissionsUnsupported`. The fresh workflow is in
143
- [Usage](../../docs/usage.md#fresh-cursor-use); argument and asynchronous failure
144
- handling are in the [caller contract](../../docs/caller-contract.md#cursor-operation-boundaries).
110
+ `reuse_finished: true` starts a fresh conversation on a finished id.
111
+ `resume({ instance_id: id })` continues the latest recorded session.
112
+ Life and replay rules are in [Usage](../../docs/usage.md#naming-the-agent)
113
+ and [Pause and resume](../../docs/usage.md#pause-and-resume).
114
+ Cursor startup, argument refusals and asynchronous failures are covered by
115
+ [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries).
145
116
 
146
117
  ### status
147
118
 
@@ -156,46 +127,32 @@ const result = await client.status({ instance_id: "<id>" });
156
127
  console.log(result.state);
157
128
  ```
158
129
 
159
- `StatusResult`, `GetResult` and each `ListRow` expose
160
- `family_state: "working" | "waiting"`, separately from `state`.
161
- [Usage](../../docs/usage.md#family-state) defines membership and
162
- aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
163
- defines reporting limits.
164
-
165
- They also carry `process_liveness: ProcessLiveness` (`"alive" | "exited" |
166
- "unknown"`) and `confirmations: Confirmations`, with exactly `state`,
167
- `process_liveness` and `displayed_state`. Each is a `Confirmation`: a non-null
168
- `status` (`ConfirmationStatus`) and the nullable `confirmed_at`, `source`
169
- (`ConfirmationSource`), `checked_at` and `reason` (`ConfirmationReason`), all
170
- five always present. The [caller contract](../../docs/caller-contract.md#confirmations)
171
- defines the values and when each is `null`. `confirmations.displayed_state`
172
- describes the returned display, including an omitted `displayed_state` or a
173
- retained display whose exit is settling. Cursor's record is
174
- `unknown`/`unsupported`.
175
-
176
- `state` is always the lifecycle state. While a row shows a
177
- Displayed State, `StatusResult`, `GetResult` and each `ListRow` carry it in
178
- `displayed_state` (`"idle_screen"`; `"needs_intelligence"` is defined, but
179
- nothing shows it yet). `StatusResult` and `GetResult` then also carry
180
- `since` and, for `"idle_screen"`, `unchanged_minutes`; `StatusResult` also
181
- carries `tmux_session_name`. A `ListRow` carries no detail. A key that does
182
- not apply is absent from the result, never `null`, so test for presence
183
- (`result.displayed_state !== undefined`). Test `displayed_state`, never
184
- `state`, for `"idle_screen"` or `"needs_intelligence"`. Every `StatusResult`, `GetResult` and
185
- `ListRow` carries `idle_screen_availability` (`IdleScreenAvailability`:
186
- `"available"` for Claude and Codex, `"unavailable"` for Cursor).
187
- The [caller contract](../../docs/caller-contract.md#needs-intelligence-and-idle-screen-rows)
188
- defines the states, fields, omissions and detection.
189
-
190
- `GetResult` and each `ListRow` carry `state_changed_at: string`, when the raw
191
- state last changed; `StatusResult` does not. The
192
- [caller contract](../../docs/caller-contract.md#state-change-time) defines it
193
- and how it differs from `last_seen_at`, the settled `state` and `since`.
194
-
195
- `status`, `get`, `getMany` and `list` use `[state] settle_ms` in the CLI's
196
- `~/.config/agent-director/config.toml` for [independent state and family
197
- settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
198
- Spawn judge its live state, which can be newer than its reported state.
130
+ `StatusResult`, `GetResult` and each `ListRow` carry:
131
+
132
+ - `family_state: "working" | "waiting"`; see
133
+ [Family state](../../docs/usage.md#family-state) and
134
+ [Family reporting limits](../../docs/caller-contract.md#family-reporting-limits).
135
+ - `process_liveness: ProcessLiveness` (`"alive" | "exited" | "unknown"`).
136
+ - `confirmations: Confirmations`: exactly `state`, `process_liveness` and
137
+ `displayed_state`. Each `Confirmation` has non-null `status`
138
+ (`ConfirmationStatus`) and nullable `confirmed_at`, `source`
139
+ (`ConfirmationSource`), `checked_at` and `reason` (`ConfirmationReason`).
140
+ All five keys are present; see [Confirmations](../../docs/caller-contract.md#confirmations).
141
+ - Optional `displayed_state`: `"idle_screen"` or the defined-but-unused
142
+ `"needs_intelligence"`. Test this field, not `state`, for a display.
143
+ - `idle_screen_availability: IdleScreenAvailability`: `"available"` for
144
+ Claude/Codex, `"unavailable"` for Cursor.
145
+
146
+ `StatusResult` and `GetResult` also carry display detail, `since` and
147
+ `unchanged_minutes`; `StatusResult` adds `tmux_session_name`. Non-applicable
148
+ display keys are absent, never null (`result.displayed_state !== undefined`).
149
+ See [Displayed states](../../docs/caller-contract.md#needs-intelligence-and-idle-screen-rows).
150
+ `GetResult` and `ListRow`, but not `StatusResult`, carry
151
+ `state_changed_at: string`; see [State change time](../../docs/caller-contract.md#state-change-time).
152
+
153
+ State and family settling use the binary's
154
+ [`[state] settle_ms`](../../docs/configuration.md#settle-time-state).
155
+ Commands judge live state, which may differ from the reported state.
199
156
 
200
157
  ### getMany
201
158
 
@@ -219,7 +176,8 @@ error names its 1-based position.
219
176
 
220
177
  ### list
221
178
 
222
- Query Spawns with optional filters.
179
+ Query Spawns with optional filters. `limit` is nonnegative; 0 or omitted means
180
+ no cap.
223
181
 
224
182
  ```ts
225
183
  const result = await client.list({ state: ["waiting"] });
@@ -251,7 +209,9 @@ for (const sub of result.subagents) {
251
209
  }
252
210
  ```
253
211
 
254
- `tracked` is `false`, with `subagents` `[]`, for a `"cursor"` agent, and 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).
212
+ `subagents` is never null; an unknown field is `null`, and times are RFC 3339
213
+ UTC strings. Agent support, `tracked`, field values and retention are defined
214
+ in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
255
215
 
256
216
  ### sendKeys
257
217
 
@@ -266,6 +226,9 @@ passes the API's dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
266
226
  the pane" below). Pass it only for a pane a person or an LLM judged, never
267
227
  from an automatic flow.
268
228
 
229
+ `key` cannot accompany nonempty `text`; `no_enter` needs text or a key.
230
+ `as` requires `request_token`, and pane hashes must be valid SHA-256 values.
231
+
269
232
  ```ts
270
233
  await client.sendKeys({
271
234
  instance_id: "<id>",
@@ -273,67 +236,35 @@ await client.sendKeys({
273
236
  });
274
237
  ```
275
238
 
276
- On a supported native launch, ordinary nonempty text with Enter and no pane
277
- hash returns runtime proof fields
278
- `outcome: "submitted"`, `request_id`, `session_id`, `record_sha256` and
279
- `record_id` when the native record supplies it. They confirm the exact
280
- normalized text in the launch's native transcript. The published
281
- `SendKeysParams` and `SendKeysResult` declarations do not expose native request
282
- IDs or proof fields; use the Go API or CLI for explicit delivery request IDs.
283
- Launches without native capability use fallback input, return an empty object on
284
- success and make no exact transcript-confirmation claim. Manual
285
- operations (`no_enter`, `key`, empty text, pane hashes and permission answers)
286
- return an empty object on success; their input-ownership refusals are in
287
- [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
288
- Supported launches, fallback readiness and input restrictions, omitted-ID
289
- behavior, structured outcomes and recovery are in
290
- [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
291
- Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
292
- cancel submission.
293
- After confirmed native delivery, a cleanup `ErrInternal` retains the submitted
294
- receipt through `AgentDirectorError.errDetails`; follow the caller contract's
295
- cleanup and no-replay rules. No additional typed proof fields are exposed.
296
- Cursor sends with Enter can return `ErrSubmissionUnconfirmed`
297
- with `outcome: "gateway_refused"`; see
298
- [Cursor input outcomes](../../docs/caller-contract.md#cursor-input-outcomes).
299
-
300
- Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
301
- reuse or resume) whose agent has not reported in yet, for example to answer a
302
- startup choice with `key` (including `key: "Enter"`). See
303
- [pending startup screens](../../docs/caller-contract.md#pending-rows-and-startup-screens)
304
- for text answers and Enter-only sends. Keys are delivered only to a
305
- session started by the row's current launch. `ended` and `missing` rows are
306
- rejected, including retries of an existing delivery request. State, relay and
307
- dialog guards precede native capability selection and request reconciliation.
308
- A `pending` row whose launch start or launch token is not recorded, or where
309
- only a session an earlier launch left behind is found, gets
310
- `ErrSpawnNotInteractive` and nothing is sent.
311
-
312
- `allow_pending` preserves native readiness and transcript requirements on
313
- supported launches; it does not make a startup dialog an ordinary composer.
314
- Ordinary pending Claude fallback has a readiness wait, and pending Claude and
315
- Codex fallback have a hook check; see
316
- [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
317
- `SubmissionUnconfirmedDetails` describes only a failed fallback hook observation:
318
- `keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
319
- uncertainty, Claude fallback's `not_started` refusals, Claude paced typing
320
- failures, Codex fallback failures and Cursor gateway refusals carry additional
321
- runtime fields, including `outcome`, `phase`, `bytes_attempted`,
322
- `enter_may_have_been_sent` and `reason`;
323
- native attempts can also carry
324
- `request_id` and `last_queue`.
325
- Read these through `AgentDirectorError.errDetails`, whose type is
326
- `Readonly<Record<string, unknown>> | null`, and check their values; see
239
+ On a supported native launch, ordinary text submission returns runtime proof
240
+ fields `outcome: "submitted"`, `request_id`, `session_id`, `record_sha256`
241
+ and optional `record_id`. The published `SendKeysParams` and `SendKeysResult`
242
+ do not expose request IDs or proof fields; use the Go API or CLI for explicit
243
+ delivery request IDs. Fallback and manual operations return `{}` on success.
244
+ Supported launches, proof, input restrictions and recovery are in
327
245
  [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission)
328
- for the fields and recovery.
246
+ and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
247
+
248
+ `ErrSubmissionUnconfirmed.errDetails` is a
249
+ `Readonly<Record<string, unknown>> | null`. The exported
250
+ `SubmissionUnconfirmedDetails` covers only failed fallback hook observation
251
+ (`keys_sent: true`, `submission_confirmed: false`, `row_state`). Additional
252
+ runtime fields include `outcome`, `phase`, `bytes_attempted`,
253
+ `enter_may_have_been_sent`, `reason`, and native `request_id` and `last_queue`.
254
+ A cleanup `ErrInternal` after native confirmation retains the submitted
255
+ receipt in `errDetails`. Read these fields with runtime value checks; their
256
+ meanings and no-replay rules are in the linked contract, including
257
+ [Cursor input outcomes](../../docs/caller-contract.md#cursor-input-outcomes).
329
258
 
330
- `liveness_note: "unreported"` means an alive agent has not reported since
331
- launch. Action on a pending row belongs to the
332
- [caller contract](../../docs/caller-contract.md#pending-rows-and-startup-screens).
259
+ Pass `allow_pending: true` to allow input to a pending launch, for example a
260
+ startup choice with `key: "Enter"`. It defaults to false and preserves
261
+ ownership, readiness, relay and dialog guards; see
262
+ [Pending rows and startup screens](../../docs/caller-contract.md#pending-rows-and-startup-screens).
333
263
 
334
264
  ### readPane
335
265
 
336
- Read the last N lines of the agent's own pane (default 25).
266
+ Read the last N lines of the agent's own pane. `n_lines` is nonnegative;
267
+ 0 or omitted selects 25 lines.
337
268
 
338
269
  ```ts
339
270
  const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
@@ -366,11 +297,10 @@ const { kill_sent } = await client.kill({ instance_id: "<id>" });
366
297
  console.log(kill_sent);
367
298
  ```
368
299
 
369
- Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
370
- retry later), `ErrTmuxSessionConflict` (CONFLICT),
371
- `ErrTmuxNotAvailable` (ENVIRONMENT) and
372
- `ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
373
- for the live-row sequence and finished-row limits.
300
+ Errors include `ErrTmuxKillFailed`, `ErrTmuxUnresponsive`,
301
+ `ErrTmuxSessionConflict`, `ErrTmuxNotAvailable` and `ErrSpawnNotFound`.
302
+ Handling and the live-row sequence are in the
303
+ [caller contract](../../docs/caller-contract.md#caller-contract).
374
304
 
375
305
  ### sweep
376
306
 
@@ -389,35 +319,22 @@ neither rollback nor completion and need not return partial checks.
389
319
 
390
320
  ### pause
391
321
 
392
- Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
393
- `pause.timeout_seconds` for `ended`. A finished Spawn is a no-op. A live Codex
394
- Spawn whose agent already exited with an end report resolves, in any live
395
- state, having typed nothing, and its row is `ended`; otherwise any live state
396
- but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
397
- `pause` ends the row itself once the agent exits (see the
398
- [caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits)).
322
+ Shut down a `waiting` Spawn and wait up to `pause.timeout_seconds` for `ended`.
323
+ A finished Spawn is a no-op. Codex exit handling is defined in the
324
+ [caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits).
399
325
 
400
326
  ```ts
401
327
  await client.pause({ instance_id: "<id>" });
402
328
  ```
403
329
 
404
- For input ownership or journal failures (`ErrInternal` before any input), see
405
- [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
330
+ `pause` takes no pane hash. It shares plain `sendKeys` permission and input
331
+ guards; see [Permission relay](../../docs/caller-contract.md#permission-relay)
332
+ and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
406
333
 
407
334
  For `ErrPauseTimeout`, `errDetails` has the exported `PauseTimeoutDetails`
408
- shape. Its fields and required inspection procedure are defined in
335
+ shape. Its fields and handling are defined in
409
336
  [When pause cannot confirm exit](../../docs/caller-contract.md#when-pause-cannot-confirm-exit).
410
337
 
411
- `pause` is held like a `sendKeys` without `request_token` and without
412
- `expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
413
- `ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
414
- with the same `errDetails`, typing nothing and starting no wait, whenever
415
- that `sendKeys` would. It takes no pane hash, so it stays held until
416
- valid agent evidence proves each request gone; see
417
- [The dialog hold](../../docs/permissions.md#the-dialog-hold).
418
- Stopping a held spawn and handling these refusals are in the
419
- [caller contract](../../docs/caller-contract.md#permission-relay).
420
-
421
338
  ### makeTemplate
422
339
 
423
340
  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.
@@ -453,59 +370,25 @@ if (result.delivery === "not_confirmed") {
453
370
  }
454
371
  ```
455
372
 
456
- `"delivered"` means durable relay acknowledgement, not agent receipt,
457
- execution or dialog closure. `"not_confirmed"` means no acknowledgement yet;
458
- `getPermission` exposes subsequent delivery and `confirm_by`. See the
459
- [caller contract](../../docs/caller-contract.md#permission-relay) for
460
- confirmation handling. `decision`
461
- is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
462
- bounds the verb's reads, write, cleanup and reporting under one original
463
- deadline, and has no default; without it `decide` can wait up to the store's
464
- busy timeout. Allow the reply margin shown above for CLI audit teardown;
465
- its stderr diagnostic does not change the structured verdict/error. Exact
466
- timing and audit limits are owned by the
467
- [caller contract](../../docs/caller-contract.md#permission-relay). `decide` rejects,
468
- recording no verdict, with `ErrRelayFallenBack` when the request's relay
469
- settled without acknowledgement, with `ErrStoreBusy` when `max_wait_ms`
470
- ran out before the verdict was recorded, and with
471
- `ErrNoOpenPermissionRequest` when no eligible request has that token,
472
- including a closed, proven-gone or obsolete request. Pane answers, retries and closed-request handling are
473
- in the [caller contract](../../docs/caller-contract.md#permission-relay). The
474
- `permission_requests` of `get` and of each `list` row carry the same
475
- delivery fields, `pane_answer` and `pane_as` included, for requests that
476
- still await an answer only; a row can read `waiting`, `working` or
477
- `ask_user` while a request is still open, so follow the requests you track
478
- with `getPermission`.
479
-
480
- Cursor uses these same methods and fields for permissions and blocking plans.
481
- Its `hook_alive` is null; `confirm_by` is finite and unchanged by recreating
482
- a client. Without acknowledgement, no relay answer is sent, including a denial. Cursor's once-only decisions,
483
- native choices, question denial and conservative unknown-origin holds are
484
- defined in [Cursor permissions](../../docs/permissions.md#cursor-spawns);
485
- uncertain answers and fallback follow the
486
- [caller contract](../../docs/caller-contract.md#permission-relay).
487
-
488
- `decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
489
- `"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
490
- do not know, read the recorded verdict from `decision` (`null` for a
491
- `"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
492
- `pane_answer`; never read a reason as a verdict.
493
-
494
- `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Cursor
495
- supplied validated exact matching invocation proof under
496
- [Cursor permissions](../../docs/permissions.md#cursor-spawns), including a failed
497
- MCP invocation that proves dialog closure without inferring execution or changing
498
- decision, delivery or pane-answer fields;
499
- `"turn_end"`, an eligible main request's turn ended under the age and identity
500
- guards, a Claude subagent's turn ended after its request (its
501
- `SubagentStop`), or a Cursor turn ended with the request still unanswered; or
502
- `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
503
- dialog was proven gone; `"delivered"` and a pane answer are
504
- agent-director's own records, not proof. `get`'s `unproven_requests` lists
505
- every request still holding the dialog, each with `unproven_since`. A request
506
- that reads `"delivered"` or closed at the pane can remain unproven; its dialog
507
- may still be there. Handling is in the
508
- [caller contract](../../docs/caller-contract.md#permission-relay).
373
+ Read `delivery` (`"delivered"` or `"not_confirmed"`), not the recorded
374
+ `decision`. `getPermission` exposes subsequent delivery (also `"fallen_back"`)
375
+ and `confirm_by`. `max_wait_ms` bounds the whole call
376
+ and has no default; it must be nonnegative and at most your deadline minus 1 s.
377
+ The [caller contract](../../docs/caller-contract.md#permission-relay) owns
378
+ confirmation, timing, refusal and closed-request handling.
379
+
380
+ `get` and each `list` row expose still-unanswered `permission_requests`.
381
+ Use `getPermission` to follow a request by token after it leaves those lists.
382
+ Cursor uses the same fields for permissions and blocking plans, with
383
+ `hook_alive: null`; see [Cursor permissions](../../docs/permissions.md#cursor-spawns).
384
+
385
+ `decision_reason` is `"operator"`, `"timeout"`, `"find_missing"`, `"ended"`,
386
+ `"pane"`, `"pane_outside"` or `"tool_ran"`. Read the verdict from `decision`,
387
+ not its reason. `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`:
388
+ `"tool_ran"`, `"turn_end"` or `"agent_gone"`) describe dialog proof;
389
+ `get.unproven_requests` lists remaining holds with `unproven_since`.
390
+ Delivery and pane-answer records are not dialog proof. The field meanings
391
+ are in [Permissions](../../docs/permissions.md#delivery).
509
392
 
510
393
  ### Answering a request at the pane
511
394
 
@@ -528,6 +411,7 @@ await client.sendKeys({
528
411
  It sends exactly that key and no Enter, then records the request
529
412
  `pane_answer` `"sent"` with `decision` your `as` and `decision_reason`
530
413
  `"pane"`. `as`, `key` and `expect_pane_sha256` are required.
414
+ Pane-answer calls cannot include `text`.
531
415
  An `ErrInternal` whose `errDetails` is a `PaneKeySentDetails`
532
416
  (`key_sent` `true`) means the key was sent but not recorded; hash use and
533
417
  recovery are in the [caller contract](../../docs/caller-contract.md#permission-relay).
@@ -551,7 +435,8 @@ try {
551
435
  }
552
436
  ```
553
437
 
554
- `as` is the caller's claim; use `"unknown"` when the answer was not seen.
438
+ `as` is `"allow"`, `"deny"` or `"unknown"`; use `"unknown"` when the answer
439
+ was not seen. `recordPaneAnswer` requires a valid `expect_pane_sha256`.
555
440
  `ErrPaneChanged`, `ErrPaneAnswerInProgress`, `ErrClaimTooSoon` and
556
441
  `ErrDialogMaybeOpen` carry structured facts in `errDetails`.
557
442
  `recordPaneAnswer` types nothing; `sendKeys` with a request token sends one
@@ -573,11 +458,9 @@ Use the package as Bun-runtime ESM.
573
458
 
574
459
  ## Versioning
575
460
 
576
- The library version equals the agent-director release tag — released in lockstep:
577
-
578
- | npm package | CLI binary |
579
- |---|---|
580
- | `agent-director@v0.5.0` | `agent-director CLI v0.5.0` |
461
+ The package version equals its release tag. Use the matching binary release
462
+ for the full API; the [minimum version check](#minimum-required-cli-binary-version)
463
+ does not negotiate features.
581
464
 
582
465
  ## Minimum required CLI binary version
583
466
 
@@ -664,13 +547,10 @@ facts remain available through the generic `errDetails` record. So does the
664
547
  (`PaneKeySentDetails`: `key_sent` `true` and `request_token`). Read facts from
665
548
  `errDetails`, never from `errDescription`.
666
549
 
667
- 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.
668
-
669
- For retry, escalation and shared CLI refusal handling see the
670
- [caller contract](../../docs/caller-contract.md). Binary installation and
671
- upgrade procedures are in [Installation](../../docs/install.md), and
672
- human repairs in [Operator actions](../../docs/operator-actions.md).
673
- The tables below describe the typed classes and their fields.
550
+ All classes below are exported from the package entry point. The tables name
551
+ what to catch and any client-specific fields. Shared retry, escalation and
552
+ refusal handling belong to the [caller contract](../../docs/caller-contract.md);
553
+ human repairs belong to [Operator actions](../../docs/operator-actions.md).
674
554
 
675
555
  ### 1. Library lifecycle
676
556
 
@@ -678,8 +558,8 @@ Raised by the client wrapper itself, independent of any agent-director binary.
678
558
 
679
559
  | Error | When it fires |
680
560
  |---|---|
681
- | `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
682
- | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Fires at construction. |
561
+ | `ErrClientClosed` | A verb was called after `close()` or disposal. |
562
+ | `ErrBunVersionTooOld` | The Bun runtime is below the package minimum; thrown at construction. |
683
563
 
684
564
  ### 2. System install (agent-director binary)
685
565
 
@@ -697,129 +577,138 @@ Raised by the client wrapper itself, independent of any agent-director binary.
697
577
 
698
578
  Thrown per verb call by the subprocess transport, not by the CLI's own validation.
699
579
 
700
- | Error | When it fires | Category |
701
- |---|---|---|
702
- | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational; see the caller contract. |
703
- | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
704
- | `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). |
580
+ | Error | Meaning |
581
+ |---|---|
582
+ | `ErrCallTimeout` | The subprocess exceeded `callTimeoutMs`; carries `verb`, `elapsedMs`, `timeoutMs`. |
583
+ | `ErrConsumerSignal` | The subprocess ended by signal; carries `verb`, `signal`. |
584
+ | `ErrUnknownErrorName` | An unmapped `err_name`; carries `unknownName` and the original `envelope`. |
705
585
 
706
586
  ### 4. Catalog-derived (CLI-side validation)
707
587
 
708
- 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.
588
+ These classes map the binary's `err_name` contract; each row gives a short
589
+ meaning. Input rules are in
590
+ [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals),
591
+ [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries)
592
+ and [Settings](../../docs/settings.md). Request handling is in
593
+ [Permission relay](../../docs/caller-contract.md#permission-relay).
709
594
 
710
- **cwd validation** (spawn's `cwd` argument — programmer error — or resume's saved cwd, gone since the row finished):
595
+ **cwd validation**:
711
596
 
712
597
  | Error | When it fires |
713
598
  |---|---|
714
- | `ErrCwdMissing` | No `cwd` was supplied; spawn requires it to derive the JSONL/resume path. |
715
- | `ErrCwdNotAPath` | `cwd` is neither absolute nor a `~/` form (URLs, bare relative paths, non-path values). |
716
- | `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk, or that cannot be accessed or entered (no search permission on it or a parent). `resume` also returns it when the row's saved cwd is gone or cannot be entered; nothing is written or launched. |
717
- | `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). `resume` also returns it when the row's saved cwd is no longer a directory. |
599
+ | `ErrCwdMissing` | No `cwd` was supplied to `spawn`. |
600
+ | `ErrCwdNotAPath` | `cwd` is neither absolute nor a `~/` path. |
601
+ | `ErrCwdNotFound` | The supplied or saved `cwd` does not exist or cannot be entered. |
602
+ | `ErrCwdNotADirectory` | The supplied or saved `cwd` is not a directory. |
718
603
 
719
- **spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
604
+ **spawn and template config validation**:
720
605
 
721
606
  | Error | When it fires |
722
607
  |---|---|
723
- | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
724
- | `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). 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`, `features.hooks` or its alias `features.codex_hooks`, `--disable hooks` or `--disable codex_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). |
725
- | `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"`, `"codex"` or `"cursor"`), or put one in the template. |
726
- | `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
727
- | `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. |
728
- | `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`. |
729
- | `ErrPermissionsUnsupported` | A `"codex"` or `"cursor"` spawn/template carries an `allow`, `deny` or `ask` entry; nothing is written. Handling is in [Permissions](../../docs/permissions.md#codex-spawns) and [Cursor permissions](../../docs/permissions.md#cursor-spawns). |
730
- | `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. |
608
+ | `ErrRelayModeInvalid` | `relay_mode` is not `on`, `off` or empty. |
609
+ | `ErrSpawnDeniedFlag` | `agent_args` contains a supervisor-owned or unsupported argument. |
610
+ | `ErrAgentMissing` | Neither the call nor its template names an agent. |
611
+ | `ErrAgentInvalid` | `agent` is not exactly `claude`, `codex` or `cursor`. |
612
+ | `ErrAgentArgsMismatch` | The template's `agent_args` belong to another agent. |
613
+ | `ErrTemplateAgentMissing` | A template has `agent_args` without an `agent`. |
614
+ | `ErrPermissionsUnsupported` | A Codex or Cursor spawn/template carries `allow`, `deny` or `ask` entries. |
615
+ | `ErrReservedEnvKey` | An `extra_env` key is reserved or invalid. |
731
616
  | `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. |
732
617
 
733
- **tmux session naming** (bad `tmux_session_name` — programmer error):
618
+ **tmux session naming**:
734
619
 
735
620
  | Error | When it fires |
736
621
  |---|---|
737
- | `ErrTmuxSessionNameEmpty` | `tmux_session_name` was explicitly supplied but empty. |
738
- | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character, or is invalid UTF-8. |
739
- | `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
622
+ | `ErrTmuxSessionNameEmpty` | An explicitly supplied `tmux_session_name` is empty. |
623
+ | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character or invalid UTF-8. |
624
+ | `ErrTmuxSessionNameTooLong` | The session name exceeds the byte cap. |
740
625
 
741
- **spawn state / lookup** (verb preconditions — mostly normal operational signals):
626
+ **spawn state / lookup**:
742
627
 
743
628
  | Error | When it fires |
744
629
  |---|---|
745
- | `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
746
- | `ErrSpawnNotInteractive` | New input requires 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. `ended` and `missing` rows are refused even when observing an existing delivery request; see [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission). |
747
- | `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes failed fallback hook observation; native, Claude readiness, Claude paced typing, Codex paste and Cursor gateway outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery, [Cursor input outcomes](../../docs/caller-contract.md#cursor-input-outcomes) for `gateway_refused`, and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
748
- | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
749
- | `ErrPauseTimeout` | Exit keys were sent but `ended` was not observed; `errDetails` has the `PauseTimeoutDetails` shape. See [When pause cannot confirm exit](../../docs/caller-contract.md#when-pause-cannot-confirm-exit). |
750
- | `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. |
630
+ | `ErrSpawnNotFound` | No row matches the supplied `instance_id`. |
631
+ | `ErrSpawnNotInteractive` | The row cannot accept input under the current launch guards. |
632
+ | `ErrSubmissionUnconfirmed` | Submission is unconfirmed; inspect `errDetails` as described under [sendKeys](#sendkeys). |
633
+ | `ErrSpawnNotPausable` | The row is not in a pausable state. |
634
+ | `ErrPauseTimeout` | Exit input was sent but `ended` was not observed; carries `PauseTimeoutDetails`. |
635
+ | `ErrSpawnNotResumable` | The row is live, including `pending`, or changed during resume. |
751
636
  | `ErrNoSessionId` | The spawn has no `session_id`, so there is nothing to resume. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
752
637
  | `ErrJsonlMissing` | The current session's transcript is unavailable. Cursor requires its protected gateway transcript; native session availability is decided later during load. Older sessions are never tried. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
753
- | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
754
- | `ErrProbeUnsupported` | No verb returns it. The name stays catalogued (and listed for `sweep` and `find-missing`) so the client still maps it. |
638
+ | `ErrListInvalidLabel` | A label filter is not in `key=value` form. |
639
+ | `ErrProbeUnsupported` | Retained error class; no current verb returns it. |
755
640
 
756
- **tmux transport** (infrastructure failures at the tmux layer — runtime). Each name has a class: GONE (the row's session is not there), UNAVAILABLE (transient; retry later), CONFLICT (permanent until a human looks), ENVIRONMENT (an environment problem for an operator to fix) or LAUNCH FAILURE (the launch failed).
641
+ **tmux transport**:
757
642
 
758
- | Error | Class | When it fires |
759
- |---|---|---|
760
- | `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. |
761
- | `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. |
762
- | `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. |
763
- | `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). |
764
- | `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). |
765
- | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
766
- | `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
643
+ | Error | Meaning |
644
+ |---|---|
645
+ | `ErrTmuxNotAvailable` | tmux or its socket is unavailable |
646
+ | `ErrTmuxSessionCreate` | The session could not be created or labelled |
647
+ | `ErrTmuxUnresponsive` | tmux did not answer usably or a launch is still starting/stopping |
648
+ | `ErrTmuxSessionConflict` | Session or pane ownership conflicts |
649
+ | `ErrTmuxKillFailed` | Exit could not be confirmed |
650
+ | `ErrTmuxSendKeys` | The target session or pane is absent |
651
+ | `ErrTmuxCaptureFailed` | The target session or pane is absent |
767
652
 
768
- Only a GONE error means the row's session is not there (for `kill`, GONE is success); no other tmux error ever means the agent is dead.
653
+ Each error's class is in the
654
+ [caller contract](../../docs/caller-contract.md#caller-contract).
769
655
 
770
- **relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
656
+ **relay / permissions**:
771
657
 
772
658
  | Error | When it fires |
773
659
  |---|---|
774
- | `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while the request relay may still answer. 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). |
775
- | `ErrRelayFallenBack` | The request's relay settled without acknowledgement and no pane answer is recorded through agent-director. Cursor uses finite `confirm_by` with null per-request hook process evidence; see [Cursor permissions](../../docs/permissions.md#cursor-spawns). 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`. |
776
- | `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 valid agent evidence and is not a Cursor request of an earlier launch (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), 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). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
777
- | `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). |
778
- | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
779
- | `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). |
780
- | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
781
- | `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
782
- | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
783
- | `ErrNoOpenPermissionRequest` | No eligible permission request matches the `(instance_id, request_token)` pair, including a closed, proven-gone or obsolete request. `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 shared recovery or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when shared recovery marked it `missing`) before the request relay acknowledged its recorded verdict, the missing mark'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 (for a request with a settle instant, `"delivered"` requires durable relay acknowledgement; requests recorded by an older binary retain the [legacy delivery rules](../../docs/permissions.md#requests-recorded-by-an-older-binary), including derived delivery after expiry even when closed). 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. |
784
- | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the recorded decision and acknowledgement prevent a second API answer. Acknowledgement does not establish agent receipt or dialog closure; see [Permission relay](../../docs/caller-contract.md#permission-relay). It also includes a request shared recovery 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 acknowledged, or one already closed at the pane, throws it too. |
785
- | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). `status`, `get`, `getMany`, `list`, `sweep` and `findMissing` throw it when a bounded store read does not finish in time; see [Bounded recovery on state reads](../../docs/caller-contract.md#bounded-recovery-on-state-reads). |
786
- | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
787
- | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
788
-
789
- **config templates** (template-management verbs — mixed programmer error / operational signal):
660
+ | `ErrSendKeysWhileRelayed` | A permission relay may still answer. |
661
+ | `ErrRelayFallenBack` | The relay settled without acknowledgement or a recorded pane answer; carries `RelayFallenBackDetails`. |
662
+ | `ErrDialogMaybeOpen` | A permission dialog is not proven gone; carries `DialogMaybeOpenDetails`. |
663
+ | `ErrPaneChanged` | The pane no longer matches `expect_pane_sha256`; carries `PaneChangedDetails` without a new hash. |
664
+ | `ErrPaneAnswerInProgress` | Another sender owns the request; carries `PaneAnswerInProgressDetails`. |
665
+ | `ErrClaimTooSoon` | An outside-answer claim is not yet allowed; carries `ClaimTooSoonDetails` with `not_before`. |
666
+ | `ErrRelayModeOff` | `decide` requires `relay_mode: "on"`. |
667
+ | `ErrInvalidDecision` | `decision` is neither `allow` nor `deny`. |
668
+ | `ErrMissingRequestToken` | `decide` received an empty `request_token`. |
669
+ | `ErrNoOpenPermissionRequest` | No eligible request matches the instance and token. |
670
+ | `ErrAlreadyDecided` | The request has a verdict, relay acknowledgement or completed pane answer. |
671
+ | `ErrStoreBusy` | A bounded store operation did not finish in time. |
672
+ | `ErrPermissionRequestNotFound` | No permission-request row matches `request_token`. |
673
+ | `ErrAmbiguousRequest` | No token was supplied and multiple open requests exist. |
674
+
675
+ **config templates**:
790
676
 
791
677
  | Error | When it fires |
792
678
  |---|---|
793
- | `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
794
- | `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
795
- | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude`, `codex` or `cursor`, 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`, `codex` or `cursor`. |
796
- | `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
679
+ | `ErrTemplateNameUnsafe` | The template name fails path/name safety checks. |
680
+ | `ErrTemplateNotFound` | The named template does not exist. |
681
+ | `ErrTemplateMalformed` | The template has invalid, unknown, duplicate case-insensitive or wrong-typed keys/values. |
682
+ | `ErrTemplateExists` | The template exists and `overwrite` is not true. |
797
683
 
798
684
  **misc**:
799
685
 
800
686
  | Error | When it fires |
801
687
  |---|---|
802
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; `getMany` received no IDs, an empty or repeated ID, or an ID the client [cannot pass to the CLI](#getmany); 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. |
803
- | `ErrTooManyIds` | `getMany` received more IDs than the configured Id Cap; `errDetails` is `TooManyIdsDetails` with `id_cap`. See [Reading many agents](../../docs/caller-contract.md#reading-many-agents) for handling. |
688
+ | `ErrInvalidFlags` | A parameter, key or parameter combination is invalid; no change or input occurred. |
689
+ | `ErrTooManyIds` | `getMany` exceeds the configured Id Cap; carries `TooManyIdsDetails.id_cap`. |
804
690
 
805
- **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
691
+ **Configuration and store setup**:
806
692
 
807
693
  | Error | When it fires |
808
694
  |---|---|
809
- | `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. |
810
- | `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. |
811
- | `ErrSchemaMismatch` | The CLI refused to open its store: its schema is newer than the binary (`found user_version=<N>, want <M>`), its store id is invalid, or its current-schema input authority is incompatible or uncommitted. The description says which. Nothing was written; an operator must act before store-opening calls can run. A newer store needs the release that wrote it. See [Operator actions](../../docs/operator-actions.md#upgrading-the-native-input-journal) for input-authority recovery. This says nothing about any agent. |
812
- | `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. |
813
- | `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. |
695
+ | `ErrConfigMalformed` | The binary cannot read or validate its configuration. |
696
+ | `ErrStoreOpen` | The store cannot be opened, including an absent store with `createIfMissing: false`. |
697
+ | `ErrSchemaMismatch` | The store schema, store id or input authority is incompatible. |
698
+ | `ErrSchemaMigrationRequired` | The store needs an administrator-run migration. |
699
+ | `ErrOldLayout` | The default store still uses the old directory layout. |
814
700
 
815
- **CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
701
+ **Other binary errors**:
816
702
 
817
703
  | Error | When it fires |
818
704
  |---|---|
819
- | `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). |
820
- | `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. |
821
- | `ErrUnknownVerb` | The binary does not know the called verb. No verb ran; binary and client versions differ. See [Installation](../../docs/install.md). |
822
- | `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. |
705
+ | `ErrInternal` | An otherwise unclassified failure; pane input may carry `PaneKeySentDetails`. |
706
+ | `ErrJSONMarshal` | The verb succeeded but its result could not be serialized. |
707
+ | `ErrUnknownVerb` | The installed binary does not know the requested verb. |
708
+ | `ErrTrailWrite` | Internal trail-writing failure; no client method returns it. |
709
+
710
+ Requests with no recorded settle instant follow
711
+ [time-derived delivery](../../docs/permissions.md#requests-with-no-recorded-settle-instant).
823
712
 
824
713
  ## See also
825
714
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.18.3",
3
+ "version": "0.18.5",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],