agent-director 0.11.1 → 0.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +416 -148
- package/dist/errors.d.ts +115 -9
- package/dist/index.d.ts +4 -3
- package/dist/index.js +328 -40
- package/dist/internal/argv.d.ts +25 -11
- package/dist/internal/discovery.d.ts +3 -2
- package/dist/internal/errorMap.d.ts +10 -7
- package/dist/internal/subprocessClient.d.ts +37 -6
- package/dist/internal/verbs.d.ts +4 -4
- package/dist/types.d.ts +722 -143
- package/dist/version-floor.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# agent-director
|
|
2
2
|
|
|
3
|
-
TypeScript/Bun client for the agent-director CLI. Shares the Go API
|
|
4
|
-
|
|
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
|
|
5
7
|
`agent-director` CLI binary at construction time and drives it as a
|
|
6
8
|
subprocess per verb call — no FFI, no network hop, no bundled binary.
|
|
7
9
|
|
|
@@ -16,32 +18,17 @@ Requires Bun >=1.0.21. The package ships pure JavaScript — there are
|
|
|
16
18
|
optional platform dependencies. `bun add --ignore-scripts agent-director`
|
|
17
19
|
is a no-op and installs the library with identical functionality.
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
from the [latest release](https://github.com/gabemahoney/agent-director/releases/latest)
|
|
23
|
-
and sets up `~/.agent-director/`:
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/skills/install-agent-director/install.sh | bash -s -- --from-release
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`Client.create()` discovers the installed binary at construction time
|
|
30
|
-
(either at `~/.agent-director/bin/agent-director` or anywhere on
|
|
31
|
-
`$PATH`) and rejects if it cannot find one. Other supported install
|
|
32
|
-
mechanisms — `install.sh --binary <path> --admin-binary <path>` with
|
|
33
|
-
locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
|
|
34
|
-
[repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
|
|
21
|
+
Install the CLI separately using the [install guide](../../docs/install.md).
|
|
22
|
+
`Client.create()` finds it at the standard install path or on `$PATH`;
|
|
23
|
+
its version must meet the client floor.
|
|
35
24
|
|
|
36
25
|
## Supported platforms
|
|
37
26
|
|
|
38
27
|
- `linux/x64` (Linux on x86_64)
|
|
39
28
|
- `darwin/arm64` (Apple Silicon Mac)
|
|
40
29
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
the CLI binary's own platform coverage. The CLI must be installed
|
|
44
|
-
separately per the platform list above.
|
|
30
|
+
Package installation may also succeed on `linux/arm64` and `darwin/x64`;
|
|
31
|
+
those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
|
|
45
32
|
|
|
46
33
|
## Quick start
|
|
47
34
|
|
|
@@ -53,6 +40,9 @@ const v = await client.version({});
|
|
|
53
40
|
console.log(v.version);
|
|
54
41
|
```
|
|
55
42
|
|
|
43
|
+
The `version` result is `{ version, commit, config_dir }`; `config_dir` is the
|
|
44
|
+
directory the CLI keeps its files in, `~/.config/agent-director` (unexpanded).
|
|
45
|
+
|
|
56
46
|
Explicit `try/finally` (portable fallback):
|
|
57
47
|
|
|
58
48
|
```ts
|
|
@@ -65,112 +55,215 @@ try {
|
|
|
65
55
|
}
|
|
66
56
|
```
|
|
67
57
|
|
|
68
|
-
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
|
|
58
|
+
All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.config/agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
|
|
69
59
|
|
|
70
|
-
`ClientOptions` overrides forward
|
|
60
|
+
`ClientOptions` overrides forward to the CLI subprocess as global flags:
|
|
71
61
|
|
|
72
62
|
- `storePath` → `--store-path`
|
|
73
63
|
- `home` → `--home`
|
|
74
64
|
- `tmuxCommand` → `--tmux-command`
|
|
65
|
+
- `createIfMissing: false` → `--create-if-missing false` (`true` forwards nothing)
|
|
75
66
|
|
|
76
|
-
The CLI, not the client, expands a `~` in
|
|
77
|
-
else (never the passwd entry's home). It applies `home` first, so with `home`
|
|
67
|
+
The paths are forwarded verbatim. The CLI, not the client, expands a `~` in
|
|
68
|
+
them, against `HOME` and nothing else (never the passwd entry's home). It applies `home` first, so with `home`
|
|
78
69
|
set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
|
|
79
70
|
`HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
|
|
80
71
|
`ErrInvalidFlags`, and with no `home` either, every call that opens the store
|
|
81
72
|
is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
|
|
82
|
-
expand its config path `~/.agent-director/config.toml`.
|
|
73
|
+
expand its config path `~/.config/agent-director/config.toml`.
|
|
74
|
+
|
|
75
|
+
Set them when the consumer needs to override that field's CLI default.
|
|
83
76
|
|
|
84
|
-
|
|
77
|
+
`callTimeoutMs` defaults to 30,000 ms per subprocess call. Cursor's separate
|
|
78
|
+
45-second ACP operation bound does not extend that client budget. Spawn and
|
|
79
|
+
resume do not wait for initialization, load, generation, a dialog answer or
|
|
80
|
+
readiness. For a deliberately longer
|
|
81
|
+
configured `pause.timeout_seconds`, give the client enough `callTimeoutMs`
|
|
82
|
+
for that wait and reply overhead; 30 seconds is not a universal operation cap.
|
|
83
|
+
|
|
84
|
+
By default, the first call that opens the store creates it when it does not
|
|
85
|
+
exist (parent directories, file and schema). With `createIfMissing: false`,
|
|
86
|
+
such a call rejects with `ErrStoreOpen` (`database not initialized`) and
|
|
87
|
+
creates none of it; an existing store opens as usual, and calls that open no
|
|
88
|
+
store, such as `version`, are unaffected.
|
|
89
|
+
|
|
90
|
+
For spawning under another home or store, use
|
|
91
|
+
[Permissions](../../docs/permissions.md#one-spawn-under-another-home-or-store).
|
|
85
92
|
|
|
86
93
|
## Verb examples
|
|
87
94
|
|
|
88
|
-
|
|
95
|
+
Shared CLI use is in [Usage](../../docs/usage.md).
|
|
89
96
|
|
|
90
|
-
|
|
97
|
+
A call that carries an old name of a renamed key (on any verb) throws
|
|
98
|
+
`ErrInvalidFlags` before the client starts any process; its description names
|
|
99
|
+
the new key.
|
|
91
100
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
101
|
+
### spawn
|
|
102
|
+
|
|
103
|
+
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.
|
|
95
104
|
|
|
96
105
|
```ts
|
|
97
|
-
const result = await client.spawn({ cwd: "~/my-project" });
|
|
98
|
-
console.log(result.
|
|
106
|
+
const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
|
|
107
|
+
console.log(result.instance_id);
|
|
99
108
|
```
|
|
100
109
|
|
|
110
|
+
The `SpawnResult` has `instance_id`, `pre_trust` and optional
|
|
111
|
+
`dropped_args?: string[]`. On a switching reuse, `dropped_args` contains
|
|
112
|
+
removed original argument tokens in argv order; it is omitted when empty.
|
|
113
|
+
The switch starts fresh and resumes nothing. Selector lists and reporting
|
|
114
|
+
rules are in the
|
|
115
|
+
[caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals).
|
|
116
|
+
|
|
117
|
+
`pre_trust` uses the existing `"ok"`, `"skipped"` and `"failed"` values.
|
|
118
|
+
Cursor reports `"failed"` for unsupported pre-trust or `"skipped"` for its saved
|
|
119
|
+
opt-out, never a validated `"ok"`; see
|
|
120
|
+
[Cursor launch settings](../../docs/settings.md#cursor-launch-settings).
|
|
121
|
+
|
|
122
|
+
For all agents, same-agent reuse retains current-life session history and subagent records;
|
|
123
|
+
switching agents starts another life, including when switching back.
|
|
124
|
+
`resume` continues only the recorded agent's latest reported session and
|
|
125
|
+
never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
|
|
126
|
+
and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
|
|
127
|
+
|
|
128
|
+
Cursor uses the existing result and row fields; `status` keeps its existing
|
|
129
|
+
shape. `resume({ instance_id: id })` launches load of only its latest saved session;
|
|
130
|
+
the row can remain `pending` until a real first prompt. After inspecting the
|
|
131
|
+
pane, pass `allow_pending: true` to `sendKeys` for that prompt; binding and
|
|
132
|
+
dialog guards still apply. Saved configuration and initial-prompt replay are
|
|
133
|
+
defined in [Pause and resume](../../docs/usage.md#pause-and-resume).
|
|
134
|
+
`reuse_finished: true` supports Cursor and agent switches under the linked
|
|
135
|
+
life rules. `makeTemplate`
|
|
136
|
+
and `spawn` refuse nonempty Cursor permission lists with
|
|
137
|
+
`ErrPermissionsUnsupported`. The fresh workflow is in
|
|
138
|
+
[Usage](../../docs/usage.md#fresh-cursor-use); argument and asynchronous failure
|
|
139
|
+
handling are in the [caller contract](../../docs/caller-contract.md#cursor-operation-boundaries).
|
|
140
|
+
|
|
101
141
|
### status
|
|
102
142
|
|
|
103
143
|
Get the current lifecycle state of a Spawn.
|
|
104
144
|
|
|
105
|
-
```sh
|
|
106
|
-
agent-director status --claude-instance-id <id>
|
|
107
|
-
```
|
|
108
|
-
|
|
109
145
|
```ts
|
|
110
|
-
const result = await client.status({
|
|
146
|
+
const result = await client.status({ instance_id: "<id>" });
|
|
111
147
|
console.log(result.state);
|
|
112
148
|
```
|
|
113
149
|
|
|
150
|
+
With `[state] settle_ms` set in the CLI's `~/.config/agent-director/config.toml`,
|
|
151
|
+
`status`, `get` and `list` report the settled state: a state a hook wrote
|
|
152
|
+
shows only once it has held that long, the last settled state until then;
|
|
153
|
+
`ended`, `missing` and a state a verb wrote show at once, and `list`'s
|
|
154
|
+
`state` filter matches the settled state. Every verb that acts on a Spawn
|
|
155
|
+
judges its live state, which can be newer. The client adds no field and
|
|
156
|
+
no state value for it.
|
|
157
|
+
|
|
114
158
|
### list
|
|
115
159
|
|
|
116
160
|
Query Spawns with optional filters.
|
|
117
161
|
|
|
118
|
-
```sh
|
|
119
|
-
agent-director list --state waiting
|
|
120
|
-
```
|
|
121
|
-
|
|
122
162
|
```ts
|
|
123
163
|
const result = await client.list({ state: ["waiting"] });
|
|
124
164
|
for (const spawn of result.spawns) {
|
|
125
|
-
console.log(spawn.
|
|
165
|
+
console.log(spawn.instance_id, spawn.state, spawn.agent);
|
|
126
166
|
}
|
|
127
167
|
```
|
|
128
168
|
|
|
129
|
-
|
|
169
|
+
Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
|
|
130
170
|
|
|
131
|
-
|
|
132
|
-
`text` sends the Enter only, submitting what is already typed.
|
|
171
|
+
### listSubagents
|
|
133
172
|
|
|
134
|
-
|
|
135
|
-
|
|
173
|
+
Read the subagent records across launches of one agent's current life, and
|
|
174
|
+
whether the agent is tracked. `subagent_id` is unique among the returned
|
|
175
|
+
records; earlier-life records remain stored but are hidden. See
|
|
176
|
+
[visibility and retention](../../docs/usage.md#read-an-agents-subagent-records).
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
const result = await client.listSubagents({ instance_id: "<id>" });
|
|
180
|
+
console.log(result.tracked);
|
|
181
|
+
for (const sub of result.subagents) {
|
|
182
|
+
console.log(sub.subagent_id, sub.state, sub.subagent_type ?? "unknown type");
|
|
183
|
+
}
|
|
136
184
|
```
|
|
137
185
|
|
|
186
|
+
`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).
|
|
187
|
+
|
|
188
|
+
### sendKeys
|
|
189
|
+
|
|
190
|
+
Send text to the agent's own pane, then one Enter to submit it. An empty
|
|
191
|
+
or omitted `text` sends the Enter only, submitting what is already typed.
|
|
192
|
+
`no_enter: true` types the text without the Enter, and `key` sends one key
|
|
193
|
+
alone (`"Escape"`, `"Enter"`, `"Up"`, `"Down"`, `"Tab"`, or one character),
|
|
194
|
+
never followed by Enter. With `expect_pane_sha256` (the `pane_sha256` of
|
|
195
|
+
the `readPane` you looked at, with its `n_lines`), nothing is sent if the
|
|
196
|
+
pane changed since (`ErrPaneChanged`); on a relayed Spawn a match also
|
|
197
|
+
passes the dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
|
|
198
|
+
the pane" below). Pass it only for a pane a person or an LLM judged, never
|
|
199
|
+
from an automatic flow.
|
|
200
|
+
|
|
138
201
|
```ts
|
|
139
|
-
await client.sendKeys({
|
|
202
|
+
await client.sendKeys({
|
|
203
|
+
instance_id: "<id>",
|
|
204
|
+
text: "what is 2+2?",
|
|
205
|
+
});
|
|
140
206
|
```
|
|
141
207
|
|
|
208
|
+
On a supported native launch, ordinary nonempty text with Enter and no pane
|
|
209
|
+
hash returns runtime proof fields
|
|
210
|
+
`outcome: "submitted"`, `request_id`, `session_id`, `record_sha256` and
|
|
211
|
+
`record_id` when the native record supplies it. They confirm the exact
|
|
212
|
+
normalized text in the launch's native transcript. The published
|
|
213
|
+
`SendKeysParams` and `SendKeysResult` declarations do not expose native request
|
|
214
|
+
IDs or proof fields; use the Go API or CLI for explicit delivery request IDs.
|
|
215
|
+
Launches without
|
|
216
|
+
native capability retain literal text and one Enter, return an empty object on
|
|
217
|
+
success and make no exact transcript-confirmation claim. Manual
|
|
218
|
+
operations (`no_enter`, `key`, empty text, pane hashes and permission answers)
|
|
219
|
+
return an empty object on success; their input-ownership refusals are in
|
|
220
|
+
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
221
|
+
Supported launches, omitted-ID behavior, structured
|
|
222
|
+
outcomes and recovery are in
|
|
223
|
+
[Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
|
|
224
|
+
Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
|
|
225
|
+
cancel submission.
|
|
226
|
+
|
|
142
227
|
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
143
228
|
reuse or resume) whose agent has not reported in yet, for example to dismiss a
|
|
144
229
|
prompt the agent shows before it reports in. Keys are delivered only to a
|
|
145
230
|
session started by the row's current launch. `ended` and `missing` rows are
|
|
146
|
-
|
|
231
|
+
rejected, including retries of an existing delivery request. State, relay and
|
|
232
|
+
dialog guards precede native capability selection and request reconciliation.
|
|
233
|
+
A `pending` row whose launch start or launch token is not recorded, or where
|
|
147
234
|
only a session an earlier launch left behind is found, gets
|
|
148
235
|
`ErrSpawnNotInteractive` and nothing is sent.
|
|
149
236
|
|
|
150
|
-
|
|
151
|
-
a
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
237
|
+
`allow_pending` preserves native readiness and transcript requirements on
|
|
238
|
+
supported launches; it does not make a startup dialog an ordinary composer.
|
|
239
|
+
For fallback input to a pending Codex row, the bounded hook-state observation
|
|
240
|
+
and its unconfirmed result are described in the caller contract.
|
|
241
|
+
`SubmissionUnconfirmedDetails` describes that fallback payload only:
|
|
242
|
+
`keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
|
|
243
|
+
uncertainty adds `outcome`, `request_id`, `phase`, `bytes_attempted`,
|
|
244
|
+
`enter_may_have_been_sent`, optional `last_queue` and `reason` at runtime.
|
|
245
|
+
Read these through `AgentDirectorError.errDetails`, whose type is
|
|
246
|
+
`Readonly<Record<string, unknown>> | null`, and check their values; see
|
|
247
|
+
[Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission)
|
|
248
|
+
for the fields and recovery.
|
|
249
|
+
|
|
250
|
+
`liveness_note: "unreported"` means an alive agent has not reported since
|
|
251
|
+
launch. Action on a pending row belongs to the
|
|
252
|
+
[caller contract](../../docs/caller-contract.md#caller-contract).
|
|
160
253
|
|
|
161
254
|
### readPane
|
|
162
255
|
|
|
163
256
|
Read the last N lines of the agent's own pane (default 25).
|
|
164
257
|
|
|
165
|
-
```sh
|
|
166
|
-
agent-director read-pane --claude-instance-id <id> --n-lines 50
|
|
167
|
-
```
|
|
168
|
-
|
|
169
258
|
```ts
|
|
170
|
-
const result = await client.readPane({
|
|
171
|
-
console.log(result.pane);
|
|
259
|
+
const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
|
|
260
|
+
console.log(result.pane, result.pane_sha256);
|
|
172
261
|
```
|
|
173
262
|
|
|
263
|
+
`pane_sha256` is the SHA-256 of exactly the bytes of `pane`; pass it back as
|
|
264
|
+
`sendKeys`' or `recordPaneAnswer`'s `expect_pane_sha256`, with the same
|
|
265
|
+
`n_lines`, when you act on what this pane shows.
|
|
266
|
+
|
|
174
267
|
`readPane` has no state guard — it works on `pending`, `ended`, and `missing`
|
|
175
268
|
rows as well as live ones. The `allow_pending` flag is accepted for symmetry
|
|
176
269
|
with `sendKeys` but has no behavioral effect.
|
|
@@ -187,47 +280,194 @@ resolves with `kill_sent: false`; that is not verification that the agent
|
|
|
187
280
|
exited. `kill` never changes the row's state: `find-missing` marks the row once
|
|
188
281
|
its agent process is gone.
|
|
189
282
|
|
|
190
|
-
```sh
|
|
191
|
-
agent-director kill --claude-instance-id <id>
|
|
192
|
-
```
|
|
193
|
-
|
|
194
283
|
```ts
|
|
195
|
-
const { kill_sent } = await client.kill({
|
|
284
|
+
const { kill_sent } = await client.kill({ instance_id: "<id>" });
|
|
196
285
|
console.log(kill_sent);
|
|
197
286
|
```
|
|
198
287
|
|
|
199
288
|
Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
|
|
200
|
-
retry later), `ErrTmuxSessionConflict` (CONFLICT
|
|
201
|
-
`ErrTmuxNotAvailable` (ENVIRONMENT
|
|
202
|
-
`ErrSpawnNotFound`. None of these
|
|
203
|
-
|
|
204
|
-
|
|
289
|
+
retry later), `ErrTmuxSessionConflict` (CONFLICT),
|
|
290
|
+
`ErrTmuxNotAvailable` (ENVIRONMENT) and
|
|
291
|
+
`ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
|
|
292
|
+
for the live-row sequence and finished-row limits.
|
|
293
|
+
|
|
294
|
+
### pause
|
|
295
|
+
|
|
296
|
+
Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
|
|
297
|
+
`pause.timeout_seconds` for `ended`. A finished Spawn is a no-op. A live Codex
|
|
298
|
+
Spawn whose agent already exited with an end report resolves, in any live
|
|
299
|
+
state, having typed nothing, and its row is `ended`; otherwise any live state
|
|
300
|
+
but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
|
|
301
|
+
`pause` ends the row itself once the agent exits (see the
|
|
302
|
+
[caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits)).
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
await client.pause({ instance_id: "<id>" });
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
For input ownership or journal failures (`ErrInternal` before any input), see
|
|
309
|
+
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
310
|
+
|
|
311
|
+
`pause` is held like a `sendKeys` without `request_token` and without
|
|
312
|
+
`expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
|
|
313
|
+
`ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
|
|
314
|
+
with the same `errDetails`, typing nothing and starting no wait, whenever
|
|
315
|
+
that `sendKeys` would. It takes no pane hash, so it stays held until
|
|
316
|
+
valid agent evidence proves each request gone; see
|
|
317
|
+
[The dialog hold](../../docs/permissions.md#the-dialog-hold).
|
|
318
|
+
Stopping a held spawn and handling these refusals are in the
|
|
319
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
205
320
|
|
|
206
321
|
### makeTemplate
|
|
207
322
|
|
|
208
|
-
Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
323
|
+
Save a reusable spawn preset. Pass `agent` to bake in the template's agent; a template with `agent_args` needs one. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
|
|
209
324
|
|
|
210
|
-
|
|
211
|
-
|
|
325
|
+
Cursor templates use the same argument validation as `spawn` and can throw
|
|
326
|
+
`ErrSpawnDeniedFlag` before writing. Supported arguments and asynchronous mode
|
|
327
|
+
configuration failures are in
|
|
328
|
+
[Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries).
|
|
329
|
+
Argument replacement, including TypeScript's empty-list omission, is defined in
|
|
330
|
+
[Settings](../../docs/settings.md#the-agent-and-its-arguments).
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
|
|
212
334
|
```
|
|
213
335
|
|
|
336
|
+
### decide
|
|
337
|
+
|
|
338
|
+
Answer a relayed permission request of a Spawn launched with
|
|
339
|
+
`relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for
|
|
340
|
+
relay acknowledgement, and resolves with the request's
|
|
341
|
+
`delivery`.
|
|
342
|
+
|
|
214
343
|
```ts
|
|
215
|
-
await client.
|
|
344
|
+
const result = await client.decide({
|
|
345
|
+
instance_id: "<id>",
|
|
346
|
+
request_token: "<token>",
|
|
347
|
+
decision: "allow",
|
|
348
|
+
max_wait_ms: 2000, // at most your deadline minus 1 s
|
|
349
|
+
});
|
|
350
|
+
if (result.delivery === "not_confirmed") {
|
|
351
|
+
const later = await client.getPermission({ request_token: "<token>" });
|
|
352
|
+
console.log(later.delivery, later.confirm_by);
|
|
353
|
+
}
|
|
216
354
|
```
|
|
217
355
|
|
|
218
|
-
|
|
356
|
+
`"delivered"` means durable relay acknowledgement, not agent receipt,
|
|
357
|
+
execution or dialog closure. `"not_confirmed"` means no acknowledgement yet;
|
|
358
|
+
`getPermission` exposes subsequent delivery and `confirm_by`. See the
|
|
359
|
+
[caller contract](../../docs/caller-contract.md#permission-relay) for
|
|
360
|
+
confirmation handling. `decision`
|
|
361
|
+
is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
|
|
362
|
+
bounds the verb's reads, write, cleanup and reporting under one original
|
|
363
|
+
deadline, and has no default; without it `decide` can wait up to the store's
|
|
364
|
+
busy timeout. Allow the reply margin shown above for CLI audit teardown;
|
|
365
|
+
its stderr diagnostic does not change the structured verdict/error. Exact
|
|
366
|
+
timing and audit limits are owned by the
|
|
367
|
+
[caller contract](../../docs/caller-contract.md#permission-relay). `decide` rejects,
|
|
368
|
+
recording no verdict, with `ErrRelayFallenBack` when the request's relay
|
|
369
|
+
settled without acknowledgement, with `ErrStoreBusy` when `max_wait_ms`
|
|
370
|
+
ran out before the verdict was recorded, and with
|
|
371
|
+
`ErrNoOpenPermissionRequest` when no open request has that token or the
|
|
372
|
+
request is closed. Pane answers, retries and closed-request handling are
|
|
373
|
+
in the [caller contract](../../docs/caller-contract.md#permission-relay). The
|
|
374
|
+
`permission_requests` of `get` and of each `list` row carry the same
|
|
375
|
+
delivery fields, `pane_answer` and `pane_as` included, for requests that
|
|
376
|
+
still await an answer only; a row can read `waiting`, `working` or
|
|
377
|
+
`ask_user` while a request is still open, so follow the requests you track
|
|
378
|
+
with `getPermission`.
|
|
379
|
+
|
|
380
|
+
Cursor uses these same methods and fields for permissions and blocking plans.
|
|
381
|
+
Its `hook_alive` is null; `confirm_by` is finite and unchanged by recreating
|
|
382
|
+
a client. Without acknowledgement, no relay answer is sent, including a denial. Cursor's once-only decisions,
|
|
383
|
+
native choices, question denial and conservative unknown-origin holds are
|
|
384
|
+
defined in [Cursor permissions](../../docs/permissions.md#cursor-spawns);
|
|
385
|
+
uncertain answers and fallback follow the
|
|
386
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
387
|
+
|
|
388
|
+
`decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
|
|
389
|
+
`"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
|
|
390
|
+
do not know, read the recorded verdict from `decision` (`null` for a
|
|
391
|
+
`"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
|
|
392
|
+
`pane_answer`; never read a reason as a verdict.
|
|
393
|
+
|
|
394
|
+
`proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Claude's
|
|
395
|
+
tool ran or Cursor supplied validated exact matching invocation proof under
|
|
396
|
+
[Cursor permissions](../../docs/permissions.md#cursor-spawns), including a failed
|
|
397
|
+
MCP invocation that proves dialog closure without inferring execution or changing
|
|
398
|
+
decision, delivery or pane-answer fields;
|
|
399
|
+
`"turn_end"`, an eligible main request's turn ended under the age and identity
|
|
400
|
+
guards; or `"agent_gone"`, the agent ended) say when and how the request's
|
|
401
|
+
dialog was proven gone; `"delivered"` and a pane answer are
|
|
402
|
+
agent-director's own records, not proof. `get`'s `unproven_requests` lists
|
|
403
|
+
every request not yet proven gone, each with `unproven_since`. A request
|
|
404
|
+
that reads `"delivered"` or closed at the pane can remain unproven; its dialog
|
|
405
|
+
may still be there. Handling is in the
|
|
406
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
407
|
+
|
|
408
|
+
### Answering a request at the pane
|
|
409
|
+
|
|
410
|
+
`sendKeys` with a `request_token` answers a request at the pane.
|
|
411
|
+
The [caller contract](../../docs/caller-contract.md#permission-relay) owns
|
|
412
|
+
when to use a pane answer and how to judge the screen. Example:
|
|
219
413
|
|
|
220
|
-
|
|
414
|
+
```ts
|
|
415
|
+
const seen = await client.readPane({ instance_id: "<id>" });
|
|
416
|
+
// having looked at seen.pane, the caller picks the key and the verdict it gives
|
|
417
|
+
await client.sendKeys({
|
|
418
|
+
instance_id: "<id>",
|
|
419
|
+
request_token: "<token>",
|
|
420
|
+
as: "deny",
|
|
421
|
+
key: "<key>",
|
|
422
|
+
expect_pane_sha256: seen.pane_sha256,
|
|
423
|
+
});
|
|
424
|
+
```
|
|
221
425
|
|
|
222
|
-
|
|
223
|
-
|
|
426
|
+
It sends exactly that key and no Enter, then records the request
|
|
427
|
+
`pane_answer` `"sent"` with `decision` your `as` and `decision_reason`
|
|
428
|
+
`"pane"`. `as`, `key` and `expect_pane_sha256` are required.
|
|
429
|
+
An `ErrInternal` whose `errDetails` is a `PaneKeySentDetails`
|
|
430
|
+
(`key_sent` `true`) means the key was sent but not recorded; hash use and
|
|
431
|
+
recovery are in the [caller contract](../../docs/caller-contract.md#permission-relay).
|
|
432
|
+
`recordPaneAnswer` records an answer made outside agent-director and types
|
|
433
|
+
nothing:
|
|
434
|
+
|
|
435
|
+
```ts
|
|
436
|
+
try {
|
|
437
|
+
await client.recordPaneAnswer({
|
|
438
|
+
request_token: "<token>",
|
|
439
|
+
as: "unknown",
|
|
440
|
+
expect_pane_sha256: "<pane_sha256>",
|
|
441
|
+
});
|
|
442
|
+
} catch (e) {
|
|
443
|
+
if (e instanceof ErrClaimTooSoon) {
|
|
444
|
+
// errDetails is a ClaimTooSoonDetails here.
|
|
445
|
+
console.log("retry at", e.errDetails?.["not_before"]);
|
|
446
|
+
} else {
|
|
447
|
+
throw e;
|
|
448
|
+
}
|
|
449
|
+
}
|
|
224
450
|
```
|
|
225
451
|
|
|
452
|
+
`as` is the caller's claim; use `"unknown"` when the answer was not seen.
|
|
453
|
+
`ErrPaneChanged`, `ErrPaneAnswerInProgress`, `ErrClaimTooSoon` and
|
|
454
|
+
`ErrDialogMaybeOpen` carry structured facts in `errDetails`.
|
|
455
|
+
`recordPaneAnswer` types nothing; `sendKeys` with a request token sends one
|
|
456
|
+
key and records it. Delivery does not prove the dialog gone. See
|
|
457
|
+
[Permissions](../../docs/permissions.md) and the
|
|
458
|
+
[caller contract](../../docs/caller-contract.md#permission-relay) for the
|
|
459
|
+
complete pane-answer and held-agent procedures.
|
|
460
|
+
|
|
461
|
+
## Consumption
|
|
462
|
+
|
|
463
|
+
The supported consumption mode is Bun-runtime ESM:
|
|
464
|
+
|
|
226
465
|
```ts
|
|
227
466
|
import { Client } from "agent-director";
|
|
228
467
|
```
|
|
229
468
|
|
|
230
|
-
|
|
469
|
+
Bundling without support for module-relative resource resolution is unsupported.
|
|
470
|
+
Use the package as Bun-runtime ESM.
|
|
231
471
|
|
|
232
472
|
## Versioning
|
|
233
473
|
|
|
@@ -240,8 +480,7 @@ The library version equals the agent-director release tag — released in lockst
|
|
|
240
480
|
## Minimum required CLI binary version
|
|
241
481
|
|
|
242
482
|
The library declares the minimum CLI-binary version it requires on two
|
|
243
|
-
surfaces,
|
|
244
|
-
published npm package at `dist/version-floor.json`.
|
|
483
|
+
surfaces, available from the published package at `dist/version-floor.json`.
|
|
245
484
|
|
|
246
485
|
**TS export (preferred for JS/TS consumers):**
|
|
247
486
|
|
|
@@ -256,8 +495,7 @@ if (binaryVersion === DEV_SENTINEL_VERSION) {
|
|
|
256
495
|
```
|
|
257
496
|
|
|
258
497
|
`MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
|
|
259
|
-
`0.7.0-rc1`).
|
|
260
|
-
runtime file read. `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
|
|
498
|
+
`0.7.0-rc1`). `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
|
|
261
499
|
— a dev-built CLI binary stamps this value and satisfies any floor by
|
|
262
500
|
short-circuit. The library returns the binary's reported version
|
|
263
501
|
verbatim — no leading-`v` stripping, no normalization. Consumers
|
|
@@ -273,21 +511,24 @@ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
|
|
|
273
511
|
This pattern is part of the public contract. It does not require the
|
|
274
512
|
agent-director CLI to be installed, does not spawn a JS runtime, and
|
|
275
513
|
does not require any agent-director-specific environment setup — read
|
|
276
|
-
the field from the file at the stable documented path.
|
|
277
|
-
returns a bare string suitable for shell comparison.
|
|
514
|
+
the field from the file at the stable documented path.
|
|
278
515
|
|
|
279
516
|
## Supported Bun versions
|
|
280
517
|
|
|
281
|
-
Minimum: `>=1.0.21` (set in `engines.bun`).
|
|
518
|
+
Minimum: `>=1.0.21` (set in `engines.bun`). The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
|
|
282
519
|
|
|
283
520
|
## Errors
|
|
284
521
|
|
|
285
|
-
|
|
522
|
+
Named client and CLI errors extend `AgentDirectorError`, so you can catch
|
|
523
|
+
by subclass with `instanceof`. Subprocess spawn failures can also surface
|
|
524
|
+
as their original errors: an unclassified `ENOENT` (neither the binary nor
|
|
525
|
+
the caller's cwd is verifiably gone) and every other spawn failure are
|
|
526
|
+
re-thrown unchanged. Keep a general fallback catch for these paths:
|
|
286
527
|
|
|
287
528
|
```ts
|
|
288
529
|
import { Client, ErrSpawnNotFound } from "agent-director";
|
|
289
530
|
try {
|
|
290
|
-
await client.status({
|
|
531
|
+
await client.status({ instance_id: "bogus" });
|
|
291
532
|
} catch (e) {
|
|
292
533
|
if (e instanceof ErrSpawnNotFound) {
|
|
293
534
|
// recover
|
|
@@ -297,24 +538,27 @@ try {
|
|
|
297
538
|
}
|
|
298
539
|
```
|
|
299
540
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
541
|
+
Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
|
|
542
|
+
the error envelope's optional `err_details` object, or `null`. Six errors
|
|
543
|
+
carry one, typed as exported interfaces: `ErrRelayFallenBack`
|
|
544
|
+
(`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
|
|
545
|
+
(`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
|
|
546
|
+
`ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
|
|
547
|
+
(`DialogMaybeOpenDetails`) and `ErrSubmissionUnconfirmed`
|
|
548
|
+
(`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
|
|
549
|
+
Native submission facts remain available through the generic `errDetails`
|
|
550
|
+
record. So does the `ErrInternal` of a
|
|
551
|
+
pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
|
|
552
|
+
`key_sent` `true` and `request_token`). Read facts from `errDetails`, never
|
|
553
|
+
from `errDescription`.
|
|
554
|
+
|
|
555
|
+
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.
|
|
556
|
+
|
|
557
|
+
For retry, escalation and shared CLI refusal handling see the
|
|
558
|
+
[caller contract](../../docs/caller-contract.md). Binary installation and
|
|
559
|
+
upgrade procedures are in [Installation](../../docs/install.md), and
|
|
560
|
+
human repairs in [Operator actions](../../docs/operator-actions.md).
|
|
561
|
+
The tables below describe the typed classes and their fields.
|
|
318
562
|
|
|
319
563
|
### 1. Library lifecycle
|
|
320
564
|
|
|
@@ -323,19 +567,19 @@ Raised by the client wrapper itself, independent of any agent-director binary.
|
|
|
323
567
|
| Error | When it fires |
|
|
324
568
|
|---|---|
|
|
325
569
|
| `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
|
|
326
|
-
| `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum.
|
|
570
|
+
| `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Fires at construction. |
|
|
327
571
|
|
|
328
572
|
### 2. System install (agent-director binary)
|
|
329
573
|
|
|
330
|
-
|
|
574
|
+
**Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
|
|
331
575
|
|
|
332
576
|
| Error | Phase | When it fires |
|
|
333
577
|
|---|---|---|
|
|
334
578
|
| `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
|
|
335
579
|
| `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
|
|
336
580
|
| `ErrSystemInstallUnreachable` | Construction | A binary was found but failed the version probe (not executable, wrong arch, non-zero exit, killed). Carries `binaryPath`, `reason`, `diagnostic`, `exitCode`, `signal`. |
|
|
337
|
-
| `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`.
|
|
338
|
-
| `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`.
|
|
581
|
+
| `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. See [Installation](../../docs/install.md) for environment requirements. |
|
|
582
|
+
| `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Installation repair is owned by [Installation](../../docs/install.md). |
|
|
339
583
|
|
|
340
584
|
### 3. Per-call infrastructure
|
|
341
585
|
|
|
@@ -343,13 +587,13 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
|
|
|
343
587
|
|
|
344
588
|
| Error | When it fires | Category |
|
|
345
589
|
|---|---|---|
|
|
346
|
-
| `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational
|
|
590
|
+
| `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational; see the caller contract. |
|
|
347
591
|
| `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
|
|
348
|
-
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for
|
|
592
|
+
| `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for. This client has a class for every `err_name` the binary of its own version gives, so the binary is of a different version, most often a newer one. Carries `unknownName` (the real `err_name`) and `envelope`. | Version error; see [Installation](../../docs/install.md). |
|
|
349
593
|
|
|
350
594
|
### 4. Catalog-derived (CLI-side validation)
|
|
351
595
|
|
|
352
|
-
These
|
|
596
|
+
These classes correspond to the shared CLI `err_name` contract. They surface bad input, a verb's own state preconditions, a config or store the CLI cannot open, or a failure of the CLI itself — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
|
|
353
597
|
|
|
354
598
|
**cwd validation** (bad `cwd` argument to `spawn` — programmer error):
|
|
355
599
|
|
|
@@ -360,14 +604,19 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
360
604
|
| `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
|
|
361
605
|
| `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
|
|
362
606
|
|
|
363
|
-
**spawn config validation** (bad `spawn` arguments — programmer error):
|
|
607
|
+
**spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
|
|
364
608
|
|
|
365
609
|
| Error | When it fires |
|
|
366
610
|
|---|---|
|
|
367
611
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
368
|
-
| `ErrSpawnDeniedFlag` | `
|
|
369
|
-
| `
|
|
370
|
-
| `
|
|
612
|
+
| `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` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
|
|
613
|
+
| `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. |
|
|
614
|
+
| `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
|
|
615
|
+
| `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. |
|
|
616
|
+
| `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`. |
|
|
617
|
+
| `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). |
|
|
618
|
+
| `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. |
|
|
619
|
+
| `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
|
|
371
620
|
|
|
372
621
|
**tmux session naming** (bad `tmux_session_name` — programmer error):
|
|
373
622
|
|
|
@@ -381,13 +630,14 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
381
630
|
|
|
382
631
|
| Error | When it fires |
|
|
383
632
|
|---|---|
|
|
384
|
-
| `ErrSpawnNotFound` | No spawn row matches the supplied `
|
|
385
|
-
| `ErrSpawnNotInteractive` |
|
|
633
|
+
| `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
|
|
634
|
+
| `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). |
|
|
635
|
+
| `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes fallback pending-Codex uncertainty; native outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
|
|
386
636
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
387
|
-
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`.
|
|
388
|
-
| `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included.
|
|
389
|
-
| `ErrNoSessionId` | The spawn has no `
|
|
390
|
-
| `ErrJsonlMissing` | The
|
|
637
|
+
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
|
|
638
|
+
| `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. |
|
|
639
|
+
| `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). |
|
|
640
|
+
| `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). |
|
|
391
641
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
392
642
|
| `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
|
|
393
643
|
|
|
@@ -396,10 +646,10 @@ These 44 classes are generated one-to-one from the shared `err_name` catalog ([`
|
|
|
396
646
|
| Error | Class | When it fires |
|
|
397
647
|
|---|---|---|
|
|
398
648
|
| `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
|
|
399
|
-
| `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled
|
|
400
|
-
| `ErrTmuxUnresponsive` | UNAVAILABLE
|
|
401
|
-
| `ErrTmuxSessionConflict` | CONFLICT
|
|
402
|
-
| `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry
|
|
649
|
+
| `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. |
|
|
650
|
+
| `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. |
|
|
651
|
+
| `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). |
|
|
652
|
+
| `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry and refusal handling is owned by [Caller contract](../../docs/caller-contract.md). |
|
|
403
653
|
| `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
|
|
404
654
|
| `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
|
|
405
655
|
|
|
@@ -409,13 +659,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
409
659
|
|
|
410
660
|
| Error | When it fires |
|
|
411
661
|
|---|---|
|
|
412
|
-
| `ErrSendKeysWhileRelayed` | `
|
|
413
|
-
| `ErrRelayFallenBack` | `
|
|
662
|
+
| `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). |
|
|
663
|
+
| `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`. |
|
|
664
|
+
| `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 (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). |
|
|
665
|
+
| `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). |
|
|
666
|
+
| `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
|
|
667
|
+
| `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
414
668
|
| `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
|
|
415
|
-
| `ErrInvalidDecision` |
|
|
669
|
+
| `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
|
|
416
670
|
| `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
|
|
417
|
-
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was
|
|
418
|
-
| `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. |
|
|
671
|
+
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request relay acknowledged its recorded verdict, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (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. |
|
|
672
|
+
| `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 `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay acknowledged, or one already closed at the pane, throws it too. |
|
|
673
|
+
| `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). |
|
|
419
674
|
| `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
|
|
420
675
|
| `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
|
|
421
676
|
|
|
@@ -425,22 +680,35 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
425
680
|
|---|---|
|
|
426
681
|
| `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
|
|
427
682
|
| `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
|
|
428
|
-
| `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
|
|
429
|
-
| `ErrTemplateExists` | `make-template` target already exists
|
|
683
|
+
| `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`. |
|
|
684
|
+
| `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
|
|
430
685
|
|
|
431
686
|
**misc**:
|
|
432
687
|
|
|
433
688
|
| Error | When it fires |
|
|
434
689
|
|---|---|
|
|
435
|
-
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation,
|
|
690
|
+
| `ErrInvalidFlags` | CLI flag parsing rejected the invocation; a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
|
|
691
|
+
|
|
692
|
+
**CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
|
|
693
|
+
|
|
694
|
+
| Error | When it fires |
|
|
695
|
+
|---|---|
|
|
696
|
+
| `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. |
|
|
697
|
+
| `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. |
|
|
698
|
+
| `ErrSchemaMismatch` | The CLI refused to open its store: the store was written by a newer agent-director than the binary (`found user_version=<N>, want <M>`), or it has no valid store id. The description says which. Nothing was written, and every call that opens the store fails this way until an operator acts: a newer store needs the agent-director release that wrote it. See Operator actions for recovery. It says nothing about any agent. |
|
|
699
|
+
| `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. |
|
|
700
|
+
| `ErrOldLayout` | The CLI refused to open its store: it was about to open the default store (no `storePath`, and no `[store] db_path` in its config file), no store exists in `~/.config/agent-director`, and the old directory exists. Nothing was created, and every call that opens the store fails this way until an operator runs this release's `install.sh`. See the caller contract for handling. It says nothing about any agent. |
|
|
436
701
|
|
|
437
|
-
**CLI
|
|
702
|
+
**CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
|
|
438
703
|
|
|
439
704
|
| Error | When it fires |
|
|
440
705
|
|---|---|
|
|
441
|
-
| `
|
|
442
|
-
| `
|
|
706
|
+
| `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). |
|
|
707
|
+
| `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. |
|
|
708
|
+
| `ErrUnknownVerb` | The binary does not know the called verb. No verb ran; binary and client versions differ. See [Installation](../../docs/install.md). |
|
|
709
|
+
| `ErrTrailWrite` | Only the CLI's internal `trail-emit` command gives it, when it cannot write its trail event. No method of this client runs `trail-emit`, so a call through this client does not get it. |
|
|
443
710
|
|
|
444
|
-
##
|
|
711
|
+
## See also
|
|
445
712
|
|
|
446
|
-
|
|
713
|
+
[Caller contract](../../docs/caller-contract.md), [Permissions](../../docs/permissions.md)
|
|
714
|
+
and [Installation](../../docs/install.md) own shared procedures.
|