agent-director 0.18.2 → 0.18.4
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 +227 -338
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,11 +1,8 @@
|
|
|
1
1
|
# agent-director
|
|
2
2
|
|
|
3
|
-
TypeScript/Bun client for
|
|
4
|
-
and
|
|
5
|
-
|
|
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
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
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
|
-
|
|
28
|
-
|
|
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
|
|
60
|
-
|
|
61
|
-
`
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
- `
|
|
65
|
-
- `
|
|
66
|
-
- `
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
and
|
|
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`
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
`
|
|
168
|
-
`
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
`
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
`
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
`
|
|
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
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
331
|
-
|
|
332
|
-
|
|
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
|
|
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
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
|
393
|
-
|
|
394
|
-
|
|
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
|
-
|
|
405
|
-
[
|
|
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
|
|
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"`
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
`
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
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
|
|
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
|
|
577
|
-
|
|
578
|
-
|
|
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
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
[
|
|
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
|
|
682
|
-
| `ErrBunVersionTooOld` | The
|
|
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 |
|
|
701
|
-
|
|
702
|
-
| `ErrCallTimeout` | The subprocess
|
|
703
|
-
| `ErrConsumerSignal` | The subprocess
|
|
704
|
-
| `ErrUnknownErrorName` |
|
|
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
|
|
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
|
|
595
|
+
**cwd validation**:
|
|
711
596
|
|
|
712
597
|
| Error | When it fires |
|
|
713
598
|
|---|---|
|
|
714
|
-
| `ErrCwdMissing` | No `cwd` was supplied
|
|
715
|
-
| `ErrCwdNotAPath` | `cwd` is neither absolute nor a `~/`
|
|
716
|
-
| `ErrCwdNotFound` |
|
|
717
|
-
| `ErrCwdNotADirectory` |
|
|
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
|
|
604
|
+
**spawn and template config validation**:
|
|
720
605
|
|
|
721
606
|
| Error | When it fires |
|
|
722
607
|
|---|---|
|
|
723
|
-
| `ErrRelayModeInvalid` | `relay_mode`
|
|
724
|
-
| `ErrSpawnDeniedFlag` |
|
|
725
|
-
| `ErrAgentMissing` |
|
|
726
|
-
| `ErrAgentInvalid` | `agent` is
|
|
727
|
-
| `ErrAgentArgsMismatch` | The template's `agent_args`
|
|
728
|
-
| `ErrTemplateAgentMissing` | A template has `agent_args`
|
|
729
|
-
| `ErrPermissionsUnsupported` | A
|
|
730
|
-
| `ErrReservedEnvKey` |
|
|
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
|
|
618
|
+
**tmux session naming**:
|
|
734
619
|
|
|
735
620
|
| Error | When it fires |
|
|
736
621
|
|---|---|
|
|
737
|
-
| `ErrTmuxSessionNameEmpty` |
|
|
738
|
-
| `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character
|
|
739
|
-
| `ErrTmuxSessionNameTooLong` | The name exceeds the
|
|
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
|
|
626
|
+
**spawn state / lookup**:
|
|
742
627
|
|
|
743
628
|
| Error | When it fires |
|
|
744
629
|
|---|---|
|
|
745
|
-
| `ErrSpawnNotFound` | No
|
|
746
|
-
| `ErrSpawnNotInteractive` |
|
|
747
|
-
| `ErrSubmissionUnconfirmed` |
|
|
748
|
-
| `ErrSpawnNotPausable` | The
|
|
749
|
-
| `ErrPauseTimeout` | Exit
|
|
750
|
-
| `ErrSpawnNotResumable` |
|
|
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
|
|
754
|
-
| `ErrProbeUnsupported` |
|
|
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
|
|
641
|
+
**tmux transport**:
|
|
757
642
|
|
|
758
|
-
| Error |
|
|
759
|
-
|
|
760
|
-
| `ErrTmuxNotAvailable` |
|
|
761
|
-
| `ErrTmuxSessionCreate` |
|
|
762
|
-
| `ErrTmuxUnresponsive` |
|
|
763
|
-
| `ErrTmuxSessionConflict` |
|
|
764
|
-
| `ErrTmuxKillFailed` |
|
|
765
|
-
| `ErrTmuxSendKeys` |
|
|
766
|
-
| `ErrTmuxCaptureFailed` |
|
|
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
|
-
|
|
653
|
+
Each error's class is in the
|
|
654
|
+
[caller contract](../../docs/caller-contract.md#caller-contract).
|
|
769
655
|
|
|
770
|
-
**relay / permissions
|
|
656
|
+
**relay / permissions**:
|
|
771
657
|
|
|
772
658
|
| Error | When it fires |
|
|
773
659
|
|---|---|
|
|
774
|
-
| `ErrSendKeysWhileRelayed` | A
|
|
775
|
-
| `ErrRelayFallenBack` | The
|
|
776
|
-
| `ErrDialogMaybeOpen` | A
|
|
777
|
-
| `ErrPaneChanged` |
|
|
778
|
-
| `ErrPaneAnswerInProgress` |
|
|
779
|
-
| `ErrClaimTooSoon` |
|
|
780
|
-
| `ErrRelayModeOff` | `decide`
|
|
781
|
-
| `ErrInvalidDecision` | `decision`
|
|
782
|
-
| `ErrMissingRequestToken` | `decide`
|
|
783
|
-
| `ErrNoOpenPermissionRequest` | No eligible
|
|
784
|
-
| `ErrAlreadyDecided` |
|
|
785
|
-
| `ErrStoreBusy` |
|
|
786
|
-
| `ErrPermissionRequestNotFound` | No permission-request row
|
|
787
|
-
| `ErrAmbiguousRequest` |
|
|
788
|
-
|
|
789
|
-
**config templates
|
|
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` |
|
|
794
|
-
| `ErrTemplateNotFound` | The named template
|
|
795
|
-
| `ErrTemplateMalformed` |
|
|
796
|
-
| `ErrTemplateExists` |
|
|
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` |
|
|
803
|
-
| `ErrTooManyIds` | `getMany`
|
|
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
|
-
**
|
|
691
|
+
**Configuration and store setup**:
|
|
806
692
|
|
|
807
693
|
| Error | When it fires |
|
|
808
694
|
|---|---|
|
|
809
|
-
| `ErrConfigMalformed` | The
|
|
810
|
-
| `ErrStoreOpen` | The
|
|
811
|
-
| `ErrSchemaMismatch` | The
|
|
812
|
-
| `ErrSchemaMigrationRequired` | The
|
|
813
|
-
| `ErrOldLayout` | The
|
|
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
|
-
**
|
|
701
|
+
**Other binary errors**:
|
|
816
702
|
|
|
817
703
|
| Error | When it fires |
|
|
818
704
|
|---|---|
|
|
819
|
-
| `ErrInternal` |
|
|
820
|
-
| `ErrJSONMarshal` | The verb
|
|
821
|
-
| `ErrUnknownVerb` | The binary does not know the
|
|
822
|
-
| `ErrTrailWrite` |
|
|
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
|
|