agent-director 0.12.0 → 0.14.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 +145 -47
- package/dist/errors.d.ts +8 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +11 -0
- package/dist/types.d.ts +127 -32
- 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
|
|
|
@@ -72,6 +74,13 @@ expand its config path `~/.config/agent-director/config.toml`.
|
|
|
72
74
|
|
|
73
75
|
Set them when the consumer needs to override that field's CLI default.
|
|
74
76
|
|
|
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
|
+
|
|
75
84
|
By default, the first call that opens the store creates it when it does not
|
|
76
85
|
exist (parent directories, file and schema). With `createIfMissing: false`,
|
|
77
86
|
such a call rejects with `ErrStoreOpen` (`database not initialized`) and
|
|
@@ -91,7 +100,7 @@ the new key.
|
|
|
91
100
|
|
|
92
101
|
### spawn
|
|
93
102
|
|
|
94
|
-
Launch a tracked agent in a new tmux session. A spawn names its agent, `"claude"` or `"
|
|
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
106
|
const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
|
|
@@ -105,12 +114,30 @@ The switch starts fresh and resumes nothing. Selector lists and reporting
|
|
|
105
114
|
rules are in the
|
|
106
115
|
[caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals).
|
|
107
116
|
|
|
108
|
-
|
|
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;
|
|
109
123
|
switching agents starts another life, including when switching back.
|
|
110
124
|
`resume` continues only the recorded agent's latest reported session and
|
|
111
125
|
never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
|
|
112
126
|
and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
|
|
113
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
|
+
|
|
114
141
|
### status
|
|
115
142
|
|
|
116
143
|
Get the current lifecycle state of a Spawn.
|
|
@@ -120,13 +147,16 @@ const result = await client.status({ instance_id: "<id>" });
|
|
|
120
147
|
console.log(result.state);
|
|
121
148
|
```
|
|
122
149
|
|
|
123
|
-
|
|
124
|
-
`
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
150
|
+
`StatusResult`, `GetResult` and each `ListRow` expose
|
|
151
|
+
`family_state: "working" | "waiting"`, separately from `state`.
|
|
152
|
+
[Usage](../../docs/usage.md#family-state) defines membership and raw
|
|
153
|
+
aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
|
|
154
|
+
defines reporting limits.
|
|
155
|
+
|
|
156
|
+
`status`, `get` and `list` use `[state] settle_ms` in the CLI's
|
|
157
|
+
`~/.config/agent-director/config.toml` for [independent state and family
|
|
158
|
+
settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
|
|
159
|
+
Spawn judge its live state, which can be newer than its reported state.
|
|
130
160
|
|
|
131
161
|
### list
|
|
132
162
|
|
|
@@ -139,7 +169,7 @@ for (const spawn of result.spawns) {
|
|
|
139
169
|
}
|
|
140
170
|
```
|
|
141
171
|
|
|
142
|
-
Each row, like `get`'s result, carries `agent` (`"claude"` or `"
|
|
172
|
+
Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
|
|
143
173
|
|
|
144
174
|
### listSubagents
|
|
145
175
|
|
|
@@ -156,7 +186,7 @@ for (const sub of result.subagents) {
|
|
|
156
186
|
}
|
|
157
187
|
```
|
|
158
188
|
|
|
159
|
-
`tracked` is `false`, with `subagents` `[]`, for a `"codex"` agent (from its spawn, and after every `resume` or reuse of its id) and for a `"claude"` agent that predates subagent tracking (it becomes `true` when that agent is next resumed or its id is reused). `subagents` is never null; a field with no known value is `null`, and times are RFC 3339 UTC strings. The fields and values are described in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
|
|
189
|
+
`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).
|
|
160
190
|
|
|
161
191
|
### sendKeys
|
|
162
192
|
|
|
@@ -172,17 +202,54 @@ the pane" below). Pass it only for a pane a person or an LLM judged, never
|
|
|
172
202
|
from an automatic flow.
|
|
173
203
|
|
|
174
204
|
```ts
|
|
175
|
-
await client.sendKeys({
|
|
205
|
+
await client.sendKeys({
|
|
206
|
+
instance_id: "<id>",
|
|
207
|
+
text: "what is 2+2?",
|
|
208
|
+
});
|
|
176
209
|
```
|
|
177
210
|
|
|
211
|
+
On a supported native launch, ordinary nonempty text with Enter and no pane
|
|
212
|
+
hash returns runtime proof fields
|
|
213
|
+
`outcome: "submitted"`, `request_id`, `session_id`, `record_sha256` and
|
|
214
|
+
`record_id` when the native record supplies it. They confirm the exact
|
|
215
|
+
normalized text in the launch's native transcript. The published
|
|
216
|
+
`SendKeysParams` and `SendKeysResult` declarations do not expose native request
|
|
217
|
+
IDs or proof fields; use the Go API or CLI for explicit delivery request IDs.
|
|
218
|
+
Launches without
|
|
219
|
+
native capability retain literal text and one Enter, return an empty object on
|
|
220
|
+
success and make no exact transcript-confirmation claim. Manual
|
|
221
|
+
operations (`no_enter`, `key`, empty text, pane hashes and permission answers)
|
|
222
|
+
return an empty object on success; their input-ownership refusals are in
|
|
223
|
+
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
224
|
+
Supported launches, omitted-ID behavior, structured
|
|
225
|
+
outcomes and recovery are in
|
|
226
|
+
[Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
|
|
227
|
+
Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
|
|
228
|
+
cancel submission.
|
|
229
|
+
|
|
178
230
|
Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
|
|
179
231
|
reuse or resume) whose agent has not reported in yet, for example to dismiss a
|
|
180
232
|
prompt the agent shows before it reports in. Keys are delivered only to a
|
|
181
233
|
session started by the row's current launch. `ended` and `missing` rows are
|
|
182
|
-
|
|
234
|
+
rejected, including retries of an existing delivery request. State, relay and
|
|
235
|
+
dialog guards precede native capability selection and request reconciliation.
|
|
236
|
+
A `pending` row whose launch start or launch token is not recorded, or where
|
|
183
237
|
only a session an earlier launch left behind is found, gets
|
|
184
238
|
`ErrSpawnNotInteractive` and nothing is sent.
|
|
185
239
|
|
|
240
|
+
`allow_pending` preserves native readiness and transcript requirements on
|
|
241
|
+
supported launches; it does not make a startup dialog an ordinary composer.
|
|
242
|
+
For fallback input to a pending Codex row, the bounded hook-state observation
|
|
243
|
+
and its unconfirmed result are described in the caller contract.
|
|
244
|
+
`SubmissionUnconfirmedDetails` describes that fallback payload only:
|
|
245
|
+
`keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
|
|
246
|
+
uncertainty adds `outcome`, `request_id`, `phase`, `bytes_attempted`,
|
|
247
|
+
`enter_may_have_been_sent`, optional `last_queue` and `reason` at runtime.
|
|
248
|
+
Read these through `AgentDirectorError.errDetails`, whose type is
|
|
249
|
+
`Readonly<Record<string, unknown>> | null`, and check their values; see
|
|
250
|
+
[Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission)
|
|
251
|
+
for the fields and recovery.
|
|
252
|
+
|
|
186
253
|
`liveness_note: "unreported"` means an alive agent has not reported since
|
|
187
254
|
launch. Action on a pending row belongs to the
|
|
188
255
|
[caller contract](../../docs/caller-contract.md#caller-contract).
|
|
@@ -241,19 +308,30 @@ but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
|
|
|
241
308
|
await client.pause({ instance_id: "<id>" });
|
|
242
309
|
```
|
|
243
310
|
|
|
311
|
+
For input ownership or journal failures (`ErrInternal` before any input), see
|
|
312
|
+
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
313
|
+
|
|
244
314
|
`pause` is held like a `sendKeys` without `request_token` and without
|
|
245
315
|
`expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
|
|
246
316
|
`ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
|
|
247
317
|
with the same `errDetails`, typing nothing and starting no wait, whenever
|
|
248
|
-
that `sendKeys` would. It takes no pane hash, so it stays held until
|
|
249
|
-
agent
|
|
250
|
-
|
|
318
|
+
that `sendKeys` would. It takes no pane hash, so it stays held until
|
|
319
|
+
valid agent evidence proves each request gone; see
|
|
320
|
+
[The dialog hold](../../docs/permissions.md#the-dialog-hold).
|
|
321
|
+
Stopping a held spawn and handling these refusals are in the
|
|
251
322
|
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
252
323
|
|
|
253
324
|
### makeTemplate
|
|
254
325
|
|
|
255
326
|
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.
|
|
256
327
|
|
|
328
|
+
Cursor templates use the same argument validation as `spawn` and can throw
|
|
329
|
+
`ErrSpawnDeniedFlag` before writing. Supported arguments and asynchronous mode
|
|
330
|
+
configuration failures are in
|
|
331
|
+
[Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries).
|
|
332
|
+
Argument replacement, including TypeScript's empty-list omission, is defined in
|
|
333
|
+
[Settings](../../docs/settings.md#the-agent-and-its-arguments).
|
|
334
|
+
|
|
257
335
|
```ts
|
|
258
336
|
await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
|
|
259
337
|
```
|
|
@@ -261,8 +339,8 @@ await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude",
|
|
|
261
339
|
### decide
|
|
262
340
|
|
|
263
341
|
Answer a relayed permission request of a Spawn launched with
|
|
264
|
-
`relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for
|
|
265
|
-
|
|
342
|
+
`relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for
|
|
343
|
+
relay acknowledgement, and resolves with the request's
|
|
266
344
|
`delivery`.
|
|
267
345
|
|
|
268
346
|
```ts
|
|
@@ -278,16 +356,20 @@ if (result.delivery === "not_confirmed") {
|
|
|
278
356
|
}
|
|
279
357
|
```
|
|
280
358
|
|
|
281
|
-
`"delivered"
|
|
282
|
-
|
|
359
|
+
`"delivered"` means durable relay acknowledgement, not agent receipt,
|
|
360
|
+
execution or dialog closure. `"not_confirmed"` means no acknowledgement yet;
|
|
283
361
|
`getPermission` exposes subsequent delivery and `confirm_by`. See the
|
|
284
362
|
[caller contract](../../docs/caller-contract.md#permission-relay) for
|
|
285
363
|
confirmation handling. `decision`
|
|
286
364
|
is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
|
|
287
|
-
bounds the
|
|
288
|
-
it `decide` can wait up to the store's
|
|
365
|
+
bounds the verb's reads, write, cleanup and reporting under one original
|
|
366
|
+
deadline, and has no default; without it `decide` can wait up to the store's
|
|
367
|
+
busy timeout. Allow the reply margin shown above for CLI audit teardown;
|
|
368
|
+
its stderr diagnostic does not change the structured verdict/error. Exact
|
|
369
|
+
timing and audit limits are owned by the
|
|
370
|
+
[caller contract](../../docs/caller-contract.md#permission-relay). `decide` rejects,
|
|
289
371
|
recording no verdict, with `ErrRelayFallenBack` when the request's relay
|
|
290
|
-
|
|
372
|
+
settled without acknowledgement, with `ErrStoreBusy` when `max_wait_ms`
|
|
291
373
|
ran out before the verdict was recorded, and with
|
|
292
374
|
`ErrNoOpenPermissionRequest` when no open request has that token or the
|
|
293
375
|
request is closed. Pane answers, retries and closed-request handling are
|
|
@@ -297,17 +379,29 @@ delivery fields, `pane_answer` and `pane_as` included, for requests that
|
|
|
297
379
|
still await an answer only; a row can read `waiting`, `working` or
|
|
298
380
|
`ask_user` while a request is still open, so follow the requests you track
|
|
299
381
|
with `getPermission`.
|
|
382
|
+
|
|
383
|
+
Cursor uses these same methods and fields for permissions and blocking plans.
|
|
384
|
+
Its `hook_alive` is null; `confirm_by` is finite and unchanged by recreating
|
|
385
|
+
a client. Without acknowledgement, no relay answer is sent, including a denial. Cursor's once-only decisions,
|
|
386
|
+
native choices, question denial and conservative unknown-origin holds are
|
|
387
|
+
defined in [Cursor permissions](../../docs/permissions.md#cursor-spawns);
|
|
388
|
+
uncertain answers and fallback follow the
|
|
389
|
+
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
390
|
+
|
|
300
391
|
`decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
|
|
301
392
|
`"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
|
|
302
393
|
do not know, read the recorded verdict from `decision` (`null` for a
|
|
303
394
|
`"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
|
|
304
395
|
`pane_answer`; never read a reason as a verdict.
|
|
305
396
|
|
|
306
|
-
`proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`,
|
|
307
|
-
tool ran
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
397
|
+
`proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Claude's
|
|
398
|
+
tool ran or Cursor supplied validated exact matching invocation proof under
|
|
399
|
+
[Cursor permissions](../../docs/permissions.md#cursor-spawns), including a failed
|
|
400
|
+
MCP invocation that proves dialog closure without inferring execution or changing
|
|
401
|
+
decision, delivery or pane-answer fields;
|
|
402
|
+
`"turn_end"`, an eligible main request's turn ended under the age and identity
|
|
403
|
+
guards; or `"agent_gone"`, the agent ended) say when and how the request's
|
|
404
|
+
dialog was proven gone; `"delivered"` and a pane answer are
|
|
311
405
|
agent-director's own records, not proof. `get`'s `unproven_requests` lists
|
|
312
406
|
every request not yet proven gone, each with `unproven_since`. A request
|
|
313
407
|
that reads `"delivered"` or closed at the pane can remain unproven; its dialog
|
|
@@ -448,12 +542,15 @@ try {
|
|
|
448
542
|
```
|
|
449
543
|
|
|
450
544
|
Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
|
|
451
|
-
the error envelope's optional `err_details` object, or `null`.
|
|
545
|
+
the error envelope's optional `err_details` object, or `null`. Six errors
|
|
452
546
|
carry one, typed as exported interfaces: `ErrRelayFallenBack`
|
|
453
547
|
(`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
|
|
454
548
|
(`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
|
|
455
|
-
`ErrPaneChanged` (`PaneChangedDetails`)
|
|
456
|
-
(`DialogMaybeOpenDetails`)
|
|
549
|
+
`ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
|
|
550
|
+
(`DialogMaybeOpenDetails`) and `ErrSubmissionUnconfirmed`
|
|
551
|
+
(`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
|
|
552
|
+
Native submission facts remain available through the generic `errDetails`
|
|
553
|
+
record. So does the `ErrInternal` of a
|
|
457
554
|
pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
|
|
458
555
|
`key_sent` `true` and `request_token`). Read facts from `errDetails`, never
|
|
459
556
|
from `errDescription`.
|
|
@@ -515,12 +612,12 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
515
612
|
| Error | When it fires |
|
|
516
613
|
|---|---|
|
|
517
614
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
518
|
-
| `ErrSpawnDeniedFlag` | The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
|
|
519
|
-
| `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"` or `"
|
|
520
|
-
| `ErrAgentInvalid` | `agent` is
|
|
615
|
+
| `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). |
|
|
616
|
+
| `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. |
|
|
617
|
+
| `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
|
|
521
618
|
| `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
|
|
522
619
|
| `ErrTemplateAgentMissing` | A template has `agent_args` and names no agent. From `makeTemplate` (`agent_args` without `agent`) and from a `spawn` that loads such a template; nothing is written. Give the template an `agent`, or remove its `agent_args`. |
|
|
523
|
-
| `ErrPermissionsUnsupported` | A `"codex"`
|
|
620
|
+
| `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). |
|
|
524
621
|
| `ErrReservedEnvKey` | From `spawn`: an `extra_env` key (a template's included) is reserved or is not a valid env-var name; nothing is written or launched, and the description says which. Reserved: an `AGENT_DIRECTOR_*` key, or a key that sets `HOME` (`HOME` itself, or one such as `HOME=/x`), with any value, an empty one included. An `extra_env` `HOME` would send the agent's hook events to another agent-director store; set an absolute `CLAUDE_CONFIG_DIR` (a Claude Code agent) or `CODEX_HOME` (a Codex agent) to give the agent its own config. Not a valid name: the key is empty, or contains `=` or a NUL character; give each variable its own name as the key and its value as the value (`{ CLAUDE_CONFIG_DIR: "/cfg" }`, not `{ "CLAUDE_CONFIG_DIR=/cfg": "" }`). This client refuses an invalid key in the call's `extra_env` itself, before it runs the CLI. From `makeTemplate`: the template's `extra_env` has such a key, reserved or not a valid name, refused by spawn's own check; no template is written or replaced, so none is saved that `spawn` would refuse (this client refuses an invalid key itself, as for `spawn`). From `resume`: the row's stored `extra_env` has a key that sets `HOME` or is not a valid name (a row spawned before spawn refused it); nothing is written or launched. Shared repair and reuse handling is in [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals); a fresh conversation has no memory of the old conversation. |
|
|
525
622
|
| `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. |
|
|
526
623
|
|
|
@@ -537,12 +634,13 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
537
634
|
| Error | When it fires |
|
|
538
635
|
|---|---|
|
|
539
636
|
| `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
|
|
540
|
-
| `ErrSpawnNotInteractive` |
|
|
637
|
+
| `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). |
|
|
638
|
+
| `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`. |
|
|
541
639
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
542
640
|
| `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
|
|
543
641
|
| `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
|
|
544
|
-
| `ErrNoSessionId` | The spawn has no `session_id
|
|
545
|
-
| `ErrJsonlMissing` | The current session's
|
|
642
|
+
| `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). |
|
|
643
|
+
| `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). |
|
|
546
644
|
| `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
|
|
547
645
|
| `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. |
|
|
548
646
|
|
|
@@ -564,18 +662,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
564
662
|
|
|
565
663
|
| Error | When it fires |
|
|
566
664
|
|---|---|
|
|
567
|
-
| `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while
|
|
568
|
-
| `ErrRelayFallenBack` |
|
|
569
|
-
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by
|
|
665
|
+
| `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). |
|
|
666
|
+
| `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`. |
|
|
667
|
+
| `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). |
|
|
570
668
|
| `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
571
669
|
| `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
|
|
572
670
|
| `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). |
|
|
573
671
|
| `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
|
|
574
672
|
| `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
|
|
575
673
|
| `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
|
|
576
|
-
| `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request
|
|
577
|
-
| `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay
|
|
578
|
-
| `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and
|
|
674
|
+
| `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. |
|
|
675
|
+
| `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. |
|
|
676
|
+
| `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). |
|
|
579
677
|
| `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
|
|
580
678
|
| `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
|
|
581
679
|
|
|
@@ -585,7 +683,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
585
683
|
|---|---|
|
|
586
684
|
| `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
|
|
587
685
|
| `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
|
|
588
|
-
| `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude` or `
|
|
686
|
+
| `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`. |
|
|
589
687
|
| `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
|
|
590
688
|
|
|
591
689
|
**misc**:
|
package/dist/errors.d.ts
CHANGED
|
@@ -215,7 +215,7 @@ export declare class ErrCwdNotADirectory extends AgentDirectorError {
|
|
|
215
215
|
/** Mirrors ErrRelayModeInvalid (package: spawn) */
|
|
216
216
|
export declare class ErrRelayModeInvalid extends AgentDirectorError {
|
|
217
217
|
}
|
|
218
|
-
/** Mirrors ErrSpawnDeniedFlag (spawn): forbidden agent arguments. A finished-agent switch drops session selectors; Claude print and exact denied long tokens owned as values always refuse. */
|
|
218
|
+
/** Mirrors ErrSpawnDeniedFlag (spawn): forbidden agent arguments. A finished-agent switch drops session selectors; Claude print and exact denied long tokens owned as values always refuse. Cursor spawn/make-template refuse unsupported or malformed arguments; remove the named argument and any owned value, then retry. */
|
|
219
219
|
export declare class ErrSpawnDeniedFlag extends AgentDirectorError {
|
|
220
220
|
}
|
|
221
221
|
/** Mirrors ErrReservedEnvKey (package: spawn) */
|
|
@@ -272,6 +272,13 @@ export declare class ErrTmuxKillFailed extends AgentDirectorError {
|
|
|
272
272
|
/** Mirrors ErrSpawnNotInteractive (package: api) */
|
|
273
273
|
export declare class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
274
274
|
}
|
|
275
|
+
/**
|
|
276
|
+
* tmux accepted the pending Codex row's keys and Enter, but submission could not be confirmed.
|
|
277
|
+
* The keys were sent; do not repeat text or Enter automatically. Check hook-derived get
|
|
278
|
+
* or status; if submission remains unknown, escalate to the caller or a human.
|
|
279
|
+
*/
|
|
280
|
+
export declare class ErrSubmissionUnconfirmed extends AgentDirectorError {
|
|
281
|
+
}
|
|
275
282
|
/**
|
|
276
283
|
* Mirrors ErrSendKeysWhileRelayed (package: api): from `sendKeys` and `pause` while a relay hook
|
|
277
284
|
* of the Spawn may still answer its request; nothing was sent.
|
package/dist/index.d.ts
CHANGED
|
@@ -7,9 +7,9 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
|
|
|
7
7
|
export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
|
|
8
8
|
export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
|
|
9
9
|
ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
|
|
10
|
-
ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
|
|
10
|
+
ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
|
|
11
11
|
export type { CheckedLocation, UnreachableReason } from "./errors.js";
|
|
12
12
|
export type { ClientOptions, Logger } from "./types.js";
|
|
13
13
|
export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, } from "./types.js";
|
|
14
|
-
export type { RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, DialogMaybeOpenDetails, } from "./types.js";
|
|
15
|
-
export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
|
|
14
|
+
export type { RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
|
|
15
|
+
export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
|
package/dist/index.js
CHANGED
|
@@ -49,6 +49,7 @@ __export(exports_errors, {
|
|
|
49
49
|
ErrSystemInstallTooOld: () => ErrSystemInstallTooOld,
|
|
50
50
|
ErrSystemInstallNotFound: () => ErrSystemInstallNotFound,
|
|
51
51
|
ErrSystemInstallDisappeared: () => ErrSystemInstallDisappeared,
|
|
52
|
+
ErrSubmissionUnconfirmed: () => ErrSubmissionUnconfirmed,
|
|
52
53
|
ErrStoreOpen: () => ErrStoreOpen,
|
|
53
54
|
ErrStoreBusy: () => ErrStoreBusy,
|
|
54
55
|
ErrSpawnNotResumable: () => ErrSpawnNotResumable,
|
|
@@ -336,6 +337,9 @@ class ErrTmuxKillFailed extends AgentDirectorError {
|
|
|
336
337
|
class ErrSpawnNotInteractive extends AgentDirectorError {
|
|
337
338
|
}
|
|
338
339
|
|
|
340
|
+
class ErrSubmissionUnconfirmed extends AgentDirectorError {
|
|
341
|
+
}
|
|
342
|
+
|
|
339
343
|
class ErrSendKeysWhileRelayed extends AgentDirectorError {
|
|
340
344
|
}
|
|
341
345
|
|
|
@@ -476,6 +480,7 @@ var ERROR_TABLE = {
|
|
|
476
480
|
ErrTmuxSessionConflict,
|
|
477
481
|
ErrTmuxKillFailed,
|
|
478
482
|
ErrSpawnNotInteractive,
|
|
483
|
+
ErrSubmissionUnconfirmed,
|
|
479
484
|
ErrSendKeysWhileRelayed,
|
|
480
485
|
ErrSpawnNotPausable,
|
|
481
486
|
ErrPauseTimeout,
|
|
@@ -1364,6 +1369,11 @@ var catalog_default = [
|
|
|
1364
1369
|
package: "api",
|
|
1365
1370
|
description: ""
|
|
1366
1371
|
},
|
|
1372
|
+
{
|
|
1373
|
+
name: "ErrSubmissionUnconfirmed",
|
|
1374
|
+
package: "api",
|
|
1375
|
+
description: ""
|
|
1376
|
+
},
|
|
1367
1377
|
{
|
|
1368
1378
|
name: "ErrListInvalidLabel",
|
|
1369
1379
|
package: "api",
|
|
@@ -1943,6 +1953,7 @@ export {
|
|
|
1943
1953
|
ErrSystemInstallTooOld,
|
|
1944
1954
|
ErrSystemInstallNotFound,
|
|
1945
1955
|
ErrSystemInstallDisappeared,
|
|
1956
|
+
ErrSubmissionUnconfirmed,
|
|
1946
1957
|
ErrStoreOpen,
|
|
1947
1958
|
ErrStoreBusy,
|
|
1948
1959
|
ErrSpawnNotResumable,
|
package/dist/types.d.ts
CHANGED
|
@@ -86,6 +86,8 @@ export interface ClientOptions {
|
|
|
86
86
|
logger?: Logger;
|
|
87
87
|
/**
|
|
88
88
|
* Per-call timeout for the subprocess Client, in milliseconds. Default: 30000 (30 s).
|
|
89
|
+
* Cursor launch returns before ACP readiness; initialize and session creation/load
|
|
90
|
+
* have separate 45 s bounds. Generation or an unanswered dialog is not the launch call.
|
|
89
91
|
*
|
|
90
92
|
* When a subprocess call exceeds this threshold the Client sends SIGTERM,
|
|
91
93
|
* waits up to 2 seconds for a graceful exit, then sends SIGKILL. The
|
|
@@ -111,12 +113,14 @@ export interface VerbSummary {
|
|
|
111
113
|
}
|
|
112
114
|
/**
|
|
113
115
|
* A permission request's delivery state:
|
|
114
|
-
* - `"delivered"`: the
|
|
116
|
+
* - `"delivered"`: the relay durably acknowledged a verdict before enqueue/write;
|
|
117
|
+
* this is not agent receipt, tool execution or dialog closure.
|
|
115
118
|
* - `"not_confirmed"`: no ack yet and the relay hook may still run; it ends by `confirm_by`.
|
|
116
119
|
* - `"fallen_back"`: no ack, and the relay hook is gone (or cannot be checked and `confirm_by`
|
|
117
120
|
* has passed): no answer from the relay reached the agent. While `pane_answer` is `"none"` or
|
|
118
|
-
* `"intent"` the request
|
|
119
|
-
* it; with `"sent"`,
|
|
121
|
+
* `"intent"` the request awaits an answer unless acknowledged or closed with its Spawn. A pane
|
|
122
|
+
* answer, `recordPaneAnswer` or validated execution proof can close it; with `"sent"`,
|
|
123
|
+
* `"outside"` or `"tool_ran"` it is closed.
|
|
120
124
|
*/
|
|
121
125
|
export type Delivery = "delivered" | "not_confirmed" | "fallen_back";
|
|
122
126
|
/**
|
|
@@ -124,16 +128,19 @@ export type Delivery = "delivered" | "not_confirmed" | "fallen_back";
|
|
|
124
128
|
* - `"none"`: no pane answer recorded through agent-director (something outside it, such as a
|
|
125
129
|
* person at tmux, may still have answered it).
|
|
126
130
|
* - `"intent"`: a pane answer through `sendKeys` was started; whether its key was typed is unknown.
|
|
127
|
-
* - `"sent"`: a pane answer's key was sent
|
|
131
|
+
* - `"sent"`: a pane answer's key was sent or Cursor recorded its native choice
|
|
132
|
+
* (`decision_reason` `"pane"`); this does not establish ACP delivery, receipt or proof.
|
|
128
133
|
* - `"outside"`: a caller recorded it answered outside agent-director (`recordPaneAnswer`,
|
|
129
134
|
* `decision_reason` `"pane_outside"`).
|
|
130
|
-
* - `"tool_ran"`:
|
|
131
|
-
* `"tool_ran"
|
|
135
|
+
* - `"tool_ran"`: agent hooks or validated correlated Cursor execution output established
|
|
136
|
+
* its tool ran. The hook close records `decision` `"allow"` and `decision_reason` `"tool_ran"`;
|
|
137
|
+
* Cursor proof preserves any earlier verdict and non-null reason, filling a missing reason
|
|
138
|
+
* with `"tool_ran"`.
|
|
132
139
|
* `"sent"`, `"outside"` and `"tool_ran"` close the request; its `delivery` stays `"fallen_back"`.
|
|
133
140
|
*/
|
|
134
141
|
export type PaneAnswer = "none" | "intent" | "sent" | "outside" | "tool_ran";
|
|
135
142
|
/**
|
|
136
|
-
* A permission request's delivery facts, with whether
|
|
143
|
+
* A permission request's delivery facts, with whether agent evidence proved its dialog gone, on every
|
|
137
144
|
* `get` / `list` permission request and `get`'s `unproven_requests`, on `getPermission` and on
|
|
138
145
|
* `decide`'s result. Derived on every read. A recorded `decision` is not the outcome:
|
|
139
146
|
* `delivery` is.
|
|
@@ -144,11 +151,14 @@ export interface RequestDelivery {
|
|
|
144
151
|
/**
|
|
145
152
|
* RFC3339 time by which `not_confirmed` ends: the relay hook's kill instant plus 2 s. For a
|
|
146
153
|
* request with no recorded settle instant: `requested_at` plus the relay window plus 2 s.
|
|
154
|
+
* Cursor uses its finite persisted per-request settlement, independent of gateway lifetime;
|
|
155
|
+
* relay-off requests settle immediately.
|
|
147
156
|
*/
|
|
148
157
|
confirm_by: string;
|
|
149
158
|
/**
|
|
150
159
|
* Whether the relay hook process runs: true, false, or null when it cannot be checked
|
|
151
160
|
* (another or unreadable pid namespace, unreadable /proc, or no recorded hook identity).
|
|
161
|
+
* Cursor gateway-local controllers have no hook identity: null, never the gateway PID.
|
|
152
162
|
*/
|
|
153
163
|
hook_alive: boolean | null;
|
|
154
164
|
/** When a reader first found the request fallen back; null until then. */
|
|
@@ -157,17 +167,19 @@ export interface RequestDelivery {
|
|
|
157
167
|
attempted_decision: "allow" | "deny" | null;
|
|
158
168
|
/** When that refused decide ran; null when none. */
|
|
159
169
|
attempted_at: string | null;
|
|
160
|
-
/**
|
|
170
|
+
/** Hook tool_use_id or Cursor's supplied toolCallId; null when none was given. */
|
|
161
171
|
tool_use_id: string | null;
|
|
162
172
|
/** How the request was answered at the pane; see {@link PaneAnswer}. */
|
|
163
173
|
pane_answer: PaneAnswer;
|
|
164
174
|
/**
|
|
165
175
|
* The verdict a pane answer claims: allow, deny, or unknown (an outside record that did not see
|
|
166
|
-
* the answer); null when none was recorded.
|
|
176
|
+
* the answer); null when none was recorded. Public send-keys and outside records store a claim
|
|
177
|
+
* without screen verification or proof. Before answering ACP, Cursor additionally requires a sent
|
|
178
|
+
* claim to match the actual selected option verdict. An outside record never authorizes an ACP answer.
|
|
167
179
|
*/
|
|
168
180
|
pane_as: "allow" | "deny" | "unknown" | null;
|
|
169
181
|
/**
|
|
170
|
-
* When
|
|
182
|
+
* When agent evidence proved the request's permission dialog gone; null until
|
|
171
183
|
* then. agent-director's own records (`delivered`, a pane answer, `recordPaneAnswer`) are not
|
|
172
184
|
* proof. While it is null, a plain `sendKeys` to the live Spawn without `expect_pane_sha256`,
|
|
173
185
|
* and a `pause`, reject with `ErrDialogMaybeOpen`.
|
|
@@ -184,12 +196,15 @@ export interface RequestDelivery {
|
|
|
184
196
|
unproven_since: string | null;
|
|
185
197
|
}
|
|
186
198
|
/**
|
|
187
|
-
* How
|
|
188
|
-
* - `"tool_ran"`: a Claude PostToolUse or PostToolUseFailure carried its `tool_use_id
|
|
189
|
-
* Codex row).
|
|
199
|
+
* How agent evidence proved a permission request's dialog gone:
|
|
200
|
+
* - `"tool_ran"`: a Claude PostToolUse or PostToolUseFailure carried its `tool_use_id`, or
|
|
201
|
+
* validated correlated Cursor execution output established that exact tool ran (never on a Codex row).
|
|
190
202
|
* - `"turn_end"`: the turn of the agent that asked ended after it was written; the main agent's
|
|
191
|
-
* Stop or idle-prompt Notification,
|
|
192
|
-
*
|
|
203
|
+
* Stop or idle-prompt Notification, a Codex main agent's Interrupt (Esc), or a verified
|
|
204
|
+
* Cursor main Stop/Interrupt proves only a durably main-turn-eligible request recorded
|
|
205
|
+
* before the hook began. Legacy non-Cursor main requests retain eligibility; Cursor
|
|
206
|
+
* unknown-origin and child requests remain ineligible even without a child id. Decisions,
|
|
207
|
+
* delivery acknowledgements and pane-answer claims do not grant eligibility.
|
|
193
208
|
* - `"agent_gone"`: its Spawn was marked missing, ended or resumed.
|
|
194
209
|
*/
|
|
195
210
|
export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
|
|
@@ -203,11 +218,12 @@ export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
|
|
|
203
218
|
export interface PermissionRequestInfo extends RequestDelivery {
|
|
204
219
|
/** Autoincrement primary key of the permission_requests row. */
|
|
205
220
|
request_id: number;
|
|
206
|
-
/** UUIDv4 token minted by
|
|
221
|
+
/** UUIDv4 token minted by the relay controller for this request. Pass to the decide verb to target a specific row. */
|
|
207
222
|
request_token: string;
|
|
208
|
-
/**
|
|
223
|
+
/** Supplied tool name (e.g. "Bash") or Cursor action title/plan name. */
|
|
209
224
|
tool_name: string;
|
|
210
|
-
/** Raw JSON string
|
|
225
|
+
/** Raw JSON string, not a nested object. Cursor preserves the entire received permission/plan
|
|
226
|
+
* params envelope byte for byte, including options and absent/null fields, without internal context. */
|
|
211
227
|
tool_input: string;
|
|
212
228
|
/** RFC3339 timestamp when the permission request row was created. */
|
|
213
229
|
requested_at: string;
|
|
@@ -236,9 +252,16 @@ export interface ListRow {
|
|
|
236
252
|
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
237
253
|
*/
|
|
238
254
|
state: string;
|
|
255
|
+
/**
|
|
256
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
257
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
258
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
259
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
260
|
+
*/
|
|
261
|
+
family_state: "working" | "waiting";
|
|
239
262
|
/** Canonicalized working directory. */
|
|
240
263
|
cwd: string;
|
|
241
|
-
/** The agent the row runs: `"claude"` (Claude Code)
|
|
264
|
+
/** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
|
|
242
265
|
agent: string;
|
|
243
266
|
/** tmux session name. */
|
|
244
267
|
tmux_session_name: string;
|
|
@@ -303,7 +326,7 @@ export interface SpawnParams {
|
|
|
303
326
|
/** Named template under ~/.config/agent-director/templates/. */
|
|
304
327
|
template?: string;
|
|
305
328
|
/**
|
|
306
|
-
* The agent to launch: `"claude"` (Claude Code)
|
|
329
|
+
* The agent to launch: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor); case-sensitive,
|
|
307
330
|
* empty or absent means not given. Spawn resolves it per call, else from `template`'s
|
|
308
331
|
* `agent`; with neither, the spawn is refused with `ErrAgentMissing`. Any other value is
|
|
309
332
|
* refused with `ErrAgentInvalid`. A template's `agent_args` belong to the template's agent
|
|
@@ -349,6 +372,11 @@ export interface SpawnParams {
|
|
|
349
372
|
* adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
|
|
350
373
|
* `--enable write_stdin_approval` when the arguments already carry one before any `--`;
|
|
351
374
|
* Codex rejects a flag the arguments themselves repeat.
|
|
375
|
+
* Cursor accepts `--model`/`-m` (split or equals), `--mode` (agent/plan/ask),
|
|
376
|
+
* `--plan`, and one final initial prompt (use `--` before a flag-like prompt).
|
|
377
|
+
* Explicit mode is configured through ACP before prompt admission; launch
|
|
378
|
+
* success alone does not confirm it. Other or malformed arguments are refused
|
|
379
|
+
* with `ErrSpawnDeniedFlag`; remove the named argument and any owned value, then retry.
|
|
352
380
|
*/
|
|
353
381
|
agent_args?: string[];
|
|
354
382
|
/**
|
|
@@ -356,7 +384,9 @@ export interface SpawnParams {
|
|
|
356
384
|
* folder-trust entry (into `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets
|
|
357
385
|
* `CLAUDE_CONFIG_DIR`, otherwise `~/.claude.json`). For a codex agent, it is putting the
|
|
358
386
|
* folder trust and the hook-trust bypass on the launch's command line (no file is
|
|
359
|
-
* written).
|
|
387
|
+
* written). Cursor grants no trust: default false reports `failed` (ACP
|
|
388
|
+
* pre-trust unsupported); true reports `skipped`. Permission policy is independent.
|
|
389
|
+
* The choice is recorded on the row until the next spawn or reuse,
|
|
360
390
|
* and every `resume` follows it. The result then reports
|
|
361
391
|
* `pre_trust: "skipped"`. Default false.
|
|
362
392
|
*/
|
|
@@ -379,13 +409,18 @@ export interface SpawnParams {
|
|
|
379
409
|
}
|
|
380
410
|
/**
|
|
381
411
|
* The launch result. The row is `pending` from its insert until
|
|
382
|
-
* the agent reports in (
|
|
412
|
+
* the agent reports in (Cursor: verified first prompt), then `waiting`.
|
|
413
|
+
* Cursor initialization, session creation and requested mode validation happen
|
|
414
|
+
* asynchronously. This result does not confirm them; later failure appears in
|
|
415
|
+
* the pane and ad.cursor.failed. Missing still requires process evidence.
|
|
383
416
|
*/
|
|
384
417
|
export interface SpawnResult {
|
|
385
418
|
/** The id the new Spawn is tracked under. */
|
|
386
419
|
instance_id: string;
|
|
387
420
|
/**
|
|
388
|
-
*
|
|
421
|
+
* Cursor grants no trust: `"failed"` by default (ACP pre-trust unsupported),
|
|
422
|
+
* `"skipped"` with `no_pre_trust`; never `"ok"`. Permission policy is independent.
|
|
423
|
+
* For Claude/Codex, what the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
|
|
389
424
|
* (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
|
|
390
425
|
* trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the caller passed
|
|
391
426
|
* `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
|
|
@@ -407,6 +442,8 @@ export interface StatusParams {
|
|
|
407
442
|
}
|
|
408
443
|
/** The row's reported lifecycle state. */
|
|
409
444
|
export interface StatusResult {
|
|
445
|
+
/** Experimental context estimate for the current session. */
|
|
446
|
+
context: ContextReading;
|
|
410
447
|
/**
|
|
411
448
|
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
412
449
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
@@ -422,6 +459,13 @@ export interface StatusResult {
|
|
|
422
459
|
* can be newer: a refusal can name a state status does not show yet.
|
|
423
460
|
*/
|
|
424
461
|
state: string;
|
|
462
|
+
/**
|
|
463
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
464
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
465
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
466
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
467
|
+
*/
|
|
468
|
+
family_state: "working" | "waiting";
|
|
425
469
|
/**
|
|
426
470
|
* Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
|
|
427
471
|
* pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
|
|
@@ -429,6 +473,25 @@ export interface StatusResult {
|
|
|
429
473
|
*/
|
|
430
474
|
launch_started_at?: string | null;
|
|
431
475
|
}
|
|
476
|
+
/**
|
|
477
|
+
* Experimental: agent internals and this output shape have no stable-format guarantee.
|
|
478
|
+
* Unavailable readings retain all five null fields. The Codex 0.159.2 OpenAI rollout
|
|
479
|
+
* source estimates last-response occupancy from its own usage and reported usable window;
|
|
480
|
+
* it does not represent cumulative billing. Claude 2.1.280 first-party pairs native capacity
|
|
481
|
+
* callbacks with transcript usage for the same resolved model and response, without provider,
|
|
482
|
+
* endpoint or window overrides. Cursor remains unknown: managed ACP lacks the ordinary
|
|
483
|
+
* usage-bearing afterAgentResponse/stop path and manual /summarize; its prompt result has only
|
|
484
|
+
* stopReason. Both captured Cursor versions have a shared-resource native preCompact executor
|
|
485
|
+
* path, but automatic managed delivery remains unqualified and managed support incomplete.
|
|
486
|
+
*/
|
|
487
|
+
export interface ContextReading {
|
|
488
|
+
used_tokens: number | null;
|
|
489
|
+
window_tokens: number | null;
|
|
490
|
+
fraction: number | null;
|
|
491
|
+
source: string | null;
|
|
492
|
+
/** Measurement time in RFC3339 UTC, never the time of the read. */
|
|
493
|
+
as_of: string | null;
|
|
494
|
+
}
|
|
432
495
|
/** The id whose row is requested. */
|
|
433
496
|
export interface GetParams {
|
|
434
497
|
/** Id of the Spawn to fetch. */
|
|
@@ -436,6 +499,8 @@ export interface GetParams {
|
|
|
436
499
|
}
|
|
437
500
|
/** One tracked agent row, with its current session and request facts. */
|
|
438
501
|
export interface GetResult {
|
|
502
|
+
/** Experimental context estimate for the current session. */
|
|
503
|
+
context: ContextReading;
|
|
439
504
|
instance_id: string;
|
|
440
505
|
parent_id: string;
|
|
441
506
|
/**
|
|
@@ -453,8 +518,15 @@ export interface GetResult {
|
|
|
453
518
|
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
454
519
|
*/
|
|
455
520
|
state: string;
|
|
521
|
+
/**
|
|
522
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
523
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
524
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
525
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
526
|
+
*/
|
|
527
|
+
family_state: "working" | "waiting";
|
|
456
528
|
cwd: string;
|
|
457
|
-
/** The agent the row runs: `"claude"` (Claude Code)
|
|
529
|
+
/** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
|
|
458
530
|
agent: string;
|
|
459
531
|
tmux_session_name: string;
|
|
460
532
|
/** The tmux socket the row's launch uses; omitted when the row has no recorded socket. */
|
|
@@ -577,9 +649,14 @@ export interface SendKeysParams {
|
|
|
577
649
|
/**
|
|
578
650
|
* Makes the call a pane answer to this fallen-back permission request of the Spawn: one key
|
|
579
651
|
* (`key`), no Enter, recorded as `pane_answer` `"sent"` with `decision` = `as`.
|
|
652
|
+
* This records the key send, not ACP delivery, receipt or proof.
|
|
580
653
|
*/
|
|
581
654
|
request_token?: string;
|
|
582
|
-
/**
|
|
655
|
+
/**
|
|
656
|
+
* A pane answer's claimed verdict, recorded as its decision without screen verification or proof.
|
|
657
|
+
* Before answering ACP, Cursor additionally requires the sent claim to match the selected
|
|
658
|
+
* offered option's verdict.
|
|
659
|
+
*/
|
|
583
660
|
as?: "allow" | "deny";
|
|
584
661
|
}
|
|
585
662
|
/** Successful sendKeys calls return an empty object. */
|
|
@@ -681,7 +758,11 @@ export interface GetPermissionResult extends RequestDelivery {
|
|
|
681
758
|
* Canonical decision-reason string: "operator" | "timeout" | "find_missing" | "ended" for deny
|
|
682
759
|
* rows ("find_missing" / "ended": still undecided when find-missing marked its spawn missing, or
|
|
683
760
|
* when its spawn ended or was resumed, and closed); "pane" | "pane_outside" | "tool_ran" for a
|
|
684
|
-
* request
|
|
761
|
+
* request answered through sendKeys or a Cursor native choice ("pane"), recorded outside
|
|
762
|
+
* ("pane_outside"), or carrying tool execution evidence ("tool_ran"). Pane claims do not establish
|
|
763
|
+
* ACP delivery, receipt or proof. Initially null while undecided without an outside claim, and
|
|
764
|
+
* for an allow from decide. Validated Cursor execution proof fills a missing reason with
|
|
765
|
+
* "tool_ran" while preserving any earlier verdict and non-null reason.
|
|
685
766
|
*/
|
|
686
767
|
decision_reason?: "operator" | "timeout" | "find_missing" | "ended" | "pane" | "pane_outside" | "tool_ran" | null;
|
|
687
768
|
/** RFC3339 timestamp when the verdict was written; null while undecided. */
|
|
@@ -696,7 +777,8 @@ export interface RecordPaneAnswerParams {
|
|
|
696
777
|
request_token: string;
|
|
697
778
|
/**
|
|
698
779
|
* How it was answered, as the caller claims: "allow", "deny", or "unknown" when the answer was
|
|
699
|
-
* not seen (pass "unknown" unless it was). Stored, never checked
|
|
780
|
+
* not seen (pass "unknown" unless it was). Stored, never checked; it never authorizes a Cursor
|
|
781
|
+
* ACP answer or supplies execution proof.
|
|
700
782
|
*/
|
|
701
783
|
as: "allow" | "deny" | "unknown";
|
|
702
784
|
/** The `pane_sha256` of the readPane that showed it answered; compared byte for byte. */
|
|
@@ -781,6 +863,12 @@ export interface PaneKeySentDetails {
|
|
|
781
863
|
key_sent: true;
|
|
782
864
|
request_token: string;
|
|
783
865
|
}
|
|
866
|
+
/** ErrSubmissionUnconfirmed's errDetails; submission remains unknown despite keys_sent. */
|
|
867
|
+
export interface SubmissionUnconfirmedDetails {
|
|
868
|
+
keys_sent: true;
|
|
869
|
+
submission_confirmed: false;
|
|
870
|
+
row_state: string;
|
|
871
|
+
}
|
|
784
872
|
/**
|
|
785
873
|
* ErrPaneChanged's errDetails. It never carries the pane's
|
|
786
874
|
* new hash: read the pane again before any retry.
|
|
@@ -806,14 +894,19 @@ export interface ResumeParams {
|
|
|
806
894
|
* are re-encoded, only when needed to preserve their original parsed meaning;
|
|
807
895
|
* otherwise their order and spelling survive. Stored agent_args are unchanged.
|
|
808
896
|
* Resume moved the row to `pending`, keeping
|
|
809
|
-
* its session id and history, until the agent reports in (
|
|
897
|
+
* its session id and history, until the agent reports in (Cursor: verified first prompt),
|
|
810
898
|
* then `waiting`.
|
|
899
|
+
* Cursor loads the latest saved session asynchronously with no fresh fallback;
|
|
900
|
+
* returning does not confirm runtime, load or requested mode success.
|
|
811
901
|
*/
|
|
812
902
|
export interface ResumeResult {
|
|
813
903
|
/** Same id that was passed in (resume preserves it). */
|
|
814
904
|
instance_id: string;
|
|
815
905
|
/**
|
|
816
|
-
*
|
|
906
|
+
* Cursor grants no trust: `"failed"` by default (ACP pre-trust unsupported),
|
|
907
|
+
* `"skipped"` with the stored opt-out; never `"ok"`. Resume preserves that choice
|
|
908
|
+
* until the next spawn or reuse. Permission policy is independent.
|
|
909
|
+
* For Claude/Codex, what the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
|
|
817
910
|
* (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
|
|
818
911
|
* trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the row records that
|
|
819
912
|
* the row's latest spawn turned it off (`no_pre_trust`); nothing was attempted.
|
|
@@ -921,9 +1014,9 @@ export interface MakeTemplateParams {
|
|
|
921
1014
|
/** Default working directory to bake in. */
|
|
922
1015
|
cwd?: string;
|
|
923
1016
|
/**
|
|
924
|
-
* The agent the template belongs to: `"claude"` (Claude Code)
|
|
1017
|
+
* The agent the template belongs to: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor);
|
|
925
1018
|
* case-sensitive, empty or absent means not given. Required when the template bakes in
|
|
926
|
-
* `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex template cannot bake in
|
|
1019
|
+
* `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex or Cursor template cannot bake in
|
|
927
1020
|
* `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). Any other value is refused
|
|
928
1021
|
* with `ErrTemplateMalformed` (`ErrAgentInvalid` is spawn's per-call refusal). A spawn
|
|
929
1022
|
* that names no agent takes it from the template.
|
|
@@ -931,7 +1024,7 @@ export interface MakeTemplateParams {
|
|
|
931
1024
|
agent?: string;
|
|
932
1025
|
/** Default relay mode: "on" | "off" | "" (inherit). */
|
|
933
1026
|
relay_mode?: string;
|
|
934
|
-
/** Default agent argv. Per-call `agent_args` replaces wholesale. */
|
|
1027
|
+
/** Default agent argv. Per-call `agent_args` replaces wholesale. Cursor uses the same supported argument subset as spawn; unsupported forms return `ErrSpawnDeniedFlag` before writing. */
|
|
935
1028
|
agent_args?: string[];
|
|
936
1029
|
/**
|
|
937
1030
|
* Env-var overrides to bake in. A key spawn would refuse is refused here with
|
|
@@ -996,6 +1089,8 @@ export interface ListSubagentsParams {
|
|
|
996
1089
|
* (trailing zeros dropped, no fraction on a whole second), exactly as the CLI prints it.
|
|
997
1090
|
*/
|
|
998
1091
|
export interface SubagentRecord {
|
|
1092
|
+
/** Experimental reading; unknown without evidence belonging to this child. */
|
|
1093
|
+
context: ContextReading;
|
|
999
1094
|
/** The subagent's id, unique among the records shown for its row. */
|
|
1000
1095
|
subagent_id: string;
|
|
1001
1096
|
/** The id of the row (agent) the subagent belongs to. */
|