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 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
- surface 1:1. The `Client` discovers the system-installed
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 `"codex"` (case-sensitive), in `agent` or through its template; with neither it throws `ErrAgentMissing`. An empty `agent` counts as not given.
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
- Same-agent reuse retains current-life session history and subagent records;
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
- With `[state] settle_ms` set in the CLI's `~/.config/agent-director/config.toml`,
124
- `status`, `get` and `list` report the settled state: a state a hook wrote
125
- shows only once it has held that long, the last settled state until then;
126
- `ended`, `missing` and a state a verb wrote show at once, and `list`'s
127
- `state` filter matches the settled state. Every verb that acts on a Spawn
128
- judges its live state, which can be newer. The client adds no field and
129
- no state value for it.
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 `"codex"`), the agent the row runs.
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({ instance_id: "<id>", text: "what is 2+2?" });
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
- still rejected. A `pending` row whose launch start or launch token is not recorded, or where
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 the
249
- agent's hooks prove each request gone (after a subagent's denied request, or on
250
- a Codex Spawn an allowed one, until the agent ends). Stopping a held spawn and handling these refusals are in the
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 the
265
- agent's relay hook to confirm it, and resolves with the request's
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"`: the relay hook confirmed the verdict before handing it to
282
- the agent. `"not_confirmed"`: the relay hook has not confirmed the verdict;
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 whole call, its reads and its write, and has no default; without
288
- it `decide` can wait up to the store's busy timeout. `decide` rejects,
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
- hook is gone and took no verdict, with `ErrStoreBusy` when `max_wait_ms`
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"`, its
307
- tool ran (a Claude Spawn only); `"turn_end"`, the turn of the agent that asked
308
- ended after it was written, which a Codex main agent's Interrupt also proves; or
309
- `"agent_gone"`, the agent ended) say when and how the agent's
310
- hooks showed the request's dialog gone; `"delivered"` and a pane answer are
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`. Five errors
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`) and `ErrDialogMaybeOpen`
456
- (`DialogMaybeOpenDetails`). So does the `ErrInternal` of a
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 `"codex"`), or put one in the template. |
520
- | `ErrAgentInvalid` | `agent` is neither `"claude"` nor `"codex"` (the value is case-sensitive); nothing is written. |
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"` spawn, or a `makeTemplate` with `agent: "codex"`, carries an `allow`, `deny` or `ask` entry; nothing is written. Drop the lists and set permission rules in the group's Codex folder, with Codex's own permission controls. |
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` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
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` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume; recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
545
- | `ErrJsonlMissing` | The current session's resume JSONL could not be located at any candidate path (for a Codex agent, only its current recorded path; older sessions are never tried); recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
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 a relay hook may still answer a request. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
568
- | `ErrRelayFallenBack` | A request's relay hook is gone and acked no verdict, with no pane answer recorded through agent-director: no answer from the relay reached the agent. Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
569
- | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by the agent's hooks (a Claude agent's tool's PostToolUse, the main agent's end of turn after it (on a Codex Spawn, its `Stop` or Interrupt), or the agent's end), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A subagent's denied request holds until the agent ends, and on a Codex Spawn so does an allowed one. `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
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's relay hook confirmed a verdict recorded on it, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (`"delivered"` only if its relay hook confirmed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
577
- | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay hook denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the hook recorded that deny with its confirmation before returning it to the agent, so there is nothing to answer at the pane. It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay hook confirmed, or one already closed at the pane, throws it too. |
578
- | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and the bound ran out, during its reads or its write, before its verdict was recorded: another agent-director process held the store that long (or, for a request recorded by an older binary, `decide` would have had to wait past the bound for the end of its relay window). Nothing was recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). Once the verdict is recorded, `decide` never throws it: a bound reached while it waits for the relay hook's confirmation resolves with `delivery` `"not_confirmed"`. Without `max_wait_ms`, `decide` never throws it. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout; nothing was sent or recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). |
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 `codex`, the old name of the `agent_args` key, wrong types, bad enums, or one key set under names that differ only in letter case, such as `RELAY_MODE` and `relay_mode`). `makeTemplate` also throws it, before writing anything, for an `agent` that is not exactly `claude` or `codex`. |
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 request's relay hook acknowledged a verdict.
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 is open and only an answer at the pane, or `recordPaneAnswer`, closes
119
- * it; with `"sent"`, `"outside"` or `"tool_ran"` it is closed.
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 (`decision_reason` `"pane"`).
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"`: the agent's hooks reported its tool ran (`decision` `"allow"`, `decision_reason`
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 the agent's hooks proved its dialog gone, on every
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
- /** The request's tool_use_id from the agent's hook input; null when none was given. */
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. The caller's claim, stored and never checked.
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 the agent's hooks proved the request's permission dialog gone; null until
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 the agent's hooks proved a permission request's dialog gone:
188
- * - `"tool_ran"`: a Claude PostToolUse or PostToolUseFailure carried its `tool_use_id` (never on a
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, or a Codex main agent's Interrupt (Esc), proves a request
192
- * with no agent_id (including a main-agent request).
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 runRelay for this request. Pass to the decide verb to target a specific row. */
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
- /** Agent tool that triggered the permission request (e.g. "Bash"). */
223
+ /** Supplied tool name (e.g. "Bash") or Cursor action title/plan name. */
209
224
  tool_name: string;
210
- /** Raw JSON string of the tool input as stored in the DB. NOT a nested object. */
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) or `"codex"` (Codex). Set at spawn; resume follows it. */
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) or `"codex"` (Codex); case-sensitive,
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). The choice is recorded on the row until the next spawn or reuse,
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 (its SessionStart hook), then `waiting`.
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
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
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) or `"codex"` (Codex). Set at spawn; resume follows it. */
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
- /** A pane answer's claimed verdict, recorded as its decision; never checked against the key. */
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 closed at the pane; null while undecided and for allow rows decided by decide.
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 (its SessionStart hook),
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
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
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) or `"codex"` (Codex);
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. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],