agent-director 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md 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.
@@ -139,7 +166,7 @@ for (const spawn of result.spawns) {
139
166
  }
140
167
  ```
141
168
 
142
- Each row, like `get`'s result, carries `agent` (`"claude"` or `"codex"`), the agent the row runs.
169
+ Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
143
170
 
144
171
  ### listSubagents
145
172
 
@@ -156,7 +183,7 @@ for (const sub of result.subagents) {
156
183
  }
157
184
  ```
158
185
 
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).
186
+ `tracked` is `false`, with `subagents` `[]`, for a `"cursor"` agent, and for a `"codex"` agent (from its spawn, and after every `resume` or reuse of its id) and for a `"claude"` agent that predates subagent tracking (it becomes `true` when that agent is next resumed or its id is reused). `subagents` is never null; a field with no known value is `null`, and times are RFC 3339 UTC strings. The fields and values are described in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
160
187
 
161
188
  ### sendKeys
162
189
 
@@ -172,17 +199,54 @@ the pane" below). Pass it only for a pane a person or an LLM judged, never
172
199
  from an automatic flow.
173
200
 
174
201
  ```ts
175
- await client.sendKeys({ instance_id: "<id>", text: "what is 2+2?" });
202
+ await client.sendKeys({
203
+ instance_id: "<id>",
204
+ text: "what is 2+2?",
205
+ });
176
206
  ```
177
207
 
208
+ On a supported native launch, ordinary nonempty text with Enter and no pane
209
+ hash returns runtime proof fields
210
+ `outcome: "submitted"`, `request_id`, `session_id`, `record_sha256` and
211
+ `record_id` when the native record supplies it. They confirm the exact
212
+ normalized text in the launch's native transcript. The published
213
+ `SendKeysParams` and `SendKeysResult` declarations do not expose native request
214
+ IDs or proof fields; use the Go API or CLI for explicit delivery request IDs.
215
+ Launches without
216
+ native capability retain literal text and one Enter, return an empty object on
217
+ success and make no exact transcript-confirmation claim. Manual
218
+ operations (`no_enter`, `key`, empty text, pane hashes and permission answers)
219
+ return an empty object on success; their input-ownership refusals are in
220
+ [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
221
+ Supported launches, omitted-ID behavior, structured
222
+ outcomes and recovery are in
223
+ [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
224
+ Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
225
+ cancel submission.
226
+
178
227
  Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
179
228
  reuse or resume) whose agent has not reported in yet, for example to dismiss a
180
229
  prompt the agent shows before it reports in. Keys are delivered only to a
181
230
  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
231
+ rejected, including retries of an existing delivery request. State, relay and
232
+ dialog guards precede native capability selection and request reconciliation.
233
+ A `pending` row whose launch start or launch token is not recorded, or where
183
234
  only a session an earlier launch left behind is found, gets
184
235
  `ErrSpawnNotInteractive` and nothing is sent.
185
236
 
237
+ `allow_pending` preserves native readiness and transcript requirements on
238
+ supported launches; it does not make a startup dialog an ordinary composer.
239
+ For fallback input to a pending Codex row, the bounded hook-state observation
240
+ and its unconfirmed result are described in the caller contract.
241
+ `SubmissionUnconfirmedDetails` describes that fallback payload only:
242
+ `keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
243
+ uncertainty adds `outcome`, `request_id`, `phase`, `bytes_attempted`,
244
+ `enter_may_have_been_sent`, optional `last_queue` and `reason` at runtime.
245
+ Read these through `AgentDirectorError.errDetails`, whose type is
246
+ `Readonly<Record<string, unknown>> | null`, and check their values; see
247
+ [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission)
248
+ for the fields and recovery.
249
+
186
250
  `liveness_note: "unreported"` means an alive agent has not reported since
187
251
  launch. Action on a pending row belongs to the
188
252
  [caller contract](../../docs/caller-contract.md#caller-contract).
@@ -241,19 +305,30 @@ but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
241
305
  await client.pause({ instance_id: "<id>" });
242
306
  ```
243
307
 
308
+ For input ownership or journal failures (`ErrInternal` before any input), see
309
+ [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
310
+
244
311
  `pause` is held like a `sendKeys` without `request_token` and without
245
312
  `expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
246
313
  `ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
247
314
  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
315
+ that `sendKeys` would. It takes no pane hash, so it stays held until
316
+ valid agent evidence proves each request gone; see
317
+ [The dialog hold](../../docs/permissions.md#the-dialog-hold).
318
+ Stopping a held spawn and handling these refusals are in the
251
319
  [caller contract](../../docs/caller-contract.md#permission-relay).
252
320
 
253
321
  ### makeTemplate
254
322
 
255
323
  Save a reusable spawn preset. Pass `agent` to bake in the template's agent; a template with `agent_args` needs one. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
256
324
 
325
+ Cursor templates use the same argument validation as `spawn` and can throw
326
+ `ErrSpawnDeniedFlag` before writing. Supported arguments and asynchronous mode
327
+ configuration failures are in
328
+ [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries).
329
+ Argument replacement, including TypeScript's empty-list omission, is defined in
330
+ [Settings](../../docs/settings.md#the-agent-and-its-arguments).
331
+
257
332
  ```ts
258
333
  await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
259
334
  ```
@@ -261,8 +336,8 @@ await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude",
261
336
  ### decide
262
337
 
263
338
  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
339
+ `relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for
340
+ relay acknowledgement, and resolves with the request's
266
341
  `delivery`.
267
342
 
268
343
  ```ts
@@ -278,16 +353,20 @@ if (result.delivery === "not_confirmed") {
278
353
  }
279
354
  ```
280
355
 
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;
356
+ `"delivered"` means durable relay acknowledgement, not agent receipt,
357
+ execution or dialog closure. `"not_confirmed"` means no acknowledgement yet;
283
358
  `getPermission` exposes subsequent delivery and `confirm_by`. See the
284
359
  [caller contract](../../docs/caller-contract.md#permission-relay) for
285
360
  confirmation handling. `decision`
286
361
  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,
362
+ bounds the verb's reads, write, cleanup and reporting under one original
363
+ deadline, and has no default; without it `decide` can wait up to the store's
364
+ busy timeout. Allow the reply margin shown above for CLI audit teardown;
365
+ its stderr diagnostic does not change the structured verdict/error. Exact
366
+ timing and audit limits are owned by the
367
+ [caller contract](../../docs/caller-contract.md#permission-relay). `decide` rejects,
289
368
  recording no verdict, with `ErrRelayFallenBack` when the request's relay
290
- hook is gone and took no verdict, with `ErrStoreBusy` when `max_wait_ms`
369
+ settled without acknowledgement, with `ErrStoreBusy` when `max_wait_ms`
291
370
  ran out before the verdict was recorded, and with
292
371
  `ErrNoOpenPermissionRequest` when no open request has that token or the
293
372
  request is closed. Pane answers, retries and closed-request handling are
@@ -297,17 +376,29 @@ delivery fields, `pane_answer` and `pane_as` included, for requests that
297
376
  still await an answer only; a row can read `waiting`, `working` or
298
377
  `ask_user` while a request is still open, so follow the requests you track
299
378
  with `getPermission`.
379
+
380
+ Cursor uses these same methods and fields for permissions and blocking plans.
381
+ Its `hook_alive` is null; `confirm_by` is finite and unchanged by recreating
382
+ a client. Without acknowledgement, no relay answer is sent, including a denial. Cursor's once-only decisions,
383
+ native choices, question denial and conservative unknown-origin holds are
384
+ defined in [Cursor permissions](../../docs/permissions.md#cursor-spawns);
385
+ uncertain answers and fallback follow the
386
+ [caller contract](../../docs/caller-contract.md#permission-relay).
387
+
300
388
  `decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
301
389
  `"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
302
390
  do not know, read the recorded verdict from `decision` (`null` for a
303
391
  `"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
304
392
  `pane_answer`; never read a reason as a verdict.
305
393
 
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
394
+ `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Claude's
395
+ tool ran or Cursor supplied validated exact matching invocation proof under
396
+ [Cursor permissions](../../docs/permissions.md#cursor-spawns), including a failed
397
+ MCP invocation that proves dialog closure without inferring execution or changing
398
+ decision, delivery or pane-answer fields;
399
+ `"turn_end"`, an eligible main request's turn ended under the age and identity
400
+ guards; or `"agent_gone"`, the agent ended) say when and how the request's
401
+ dialog was proven gone; `"delivered"` and a pane answer are
311
402
  agent-director's own records, not proof. `get`'s `unproven_requests` lists
312
403
  every request not yet proven gone, each with `unproven_since`. A request
313
404
  that reads `"delivered"` or closed at the pane can remain unproven; its dialog
@@ -448,12 +539,15 @@ try {
448
539
  ```
449
540
 
450
541
  Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
451
- the error envelope's optional `err_details` object, or `null`. Five errors
542
+ the error envelope's optional `err_details` object, or `null`. Six errors
452
543
  carry one, typed as exported interfaces: `ErrRelayFallenBack`
453
544
  (`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
454
545
  (`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
455
- `ErrPaneChanged` (`PaneChangedDetails`) and `ErrDialogMaybeOpen`
456
- (`DialogMaybeOpenDetails`). So does the `ErrInternal` of a
546
+ `ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
547
+ (`DialogMaybeOpenDetails`) and `ErrSubmissionUnconfirmed`
548
+ (`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
549
+ Native submission facts remain available through the generic `errDetails`
550
+ record. So does the `ErrInternal` of a
457
551
  pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
458
552
  `key_sent` `true` and `request_token`). Read facts from `errDetails`, never
459
553
  from `errDescription`.
@@ -515,12 +609,12 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
515
609
  | Error | When it fires |
516
610
  |---|---|
517
611
  | `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. |
612
+ | `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
613
+ | `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"`, `"codex"` or `"cursor"`), or put one in the template. |
614
+ | `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
521
615
  | `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
522
616
  | `ErrTemplateAgentMissing` | A template has `agent_args` and names no agent. From `makeTemplate` (`agent_args` without `agent`) and from a `spawn` that loads such a template; nothing is written. Give the template an `agent`, or remove its `agent_args`. |
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. |
617
+ | `ErrPermissionsUnsupported` | A `"codex"` or `"cursor"` spawn/template carries an `allow`, `deny` or `ask` entry; nothing is written. Handling is in [Permissions](../../docs/permissions.md#codex-spawns) and [Cursor permissions](../../docs/permissions.md#cursor-spawns). |
524
618
  | `ErrReservedEnvKey` | From `spawn`: an `extra_env` key (a template's included) is reserved or is not a valid env-var name; nothing is written or launched, and the description says which. Reserved: an `AGENT_DIRECTOR_*` key, or a key that sets `HOME` (`HOME` itself, or one such as `HOME=/x`), with any value, an empty one included. An `extra_env` `HOME` would send the agent's hook events to another agent-director store; set an absolute `CLAUDE_CONFIG_DIR` (a Claude Code agent) or `CODEX_HOME` (a Codex agent) to give the agent its own config. Not a valid name: the key is empty, or contains `=` or a NUL character; give each variable its own name as the key and its value as the value (`{ CLAUDE_CONFIG_DIR: "/cfg" }`, not `{ "CLAUDE_CONFIG_DIR=/cfg": "" }`). This client refuses an invalid key in the call's `extra_env` itself, before it runs the CLI. From `makeTemplate`: the template's `extra_env` has such a key, reserved or not a valid name, refused by spawn's own check; no template is written or replaced, so none is saved that `spawn` would refuse (this client refuses an invalid key itself, as for `spawn`). From `resume`: the row's stored `extra_env` has a key that sets `HOME` or is not a valid name (a row spawned before spawn refused it); nothing is written or launched. Shared repair and reuse handling is in [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals); a fresh conversation has no memory of the old conversation. |
525
619
  | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
526
620
 
@@ -537,12 +631,13 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
537
631
  | Error | When it fires |
538
632
  |---|---|
539
633
  | `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. |
634
+ | `ErrSpawnNotInteractive` | New input requires a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. `ended` and `missing` rows are refused even when observing an existing delivery request; see [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission). |
635
+ | `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes fallback pending-Codex uncertainty; native outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
541
636
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
542
637
  | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
543
638
  | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
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. |
639
+ | `ErrNoSessionId` | The spawn has no `session_id`, so there is nothing to resume. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
640
+ | `ErrJsonlMissing` | The current session's transcript is unavailable. Cursor requires its protected gateway transcript; native session availability is decided later during load. Older sessions are never tried. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
546
641
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
547
642
  | `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
548
643
 
@@ -564,18 +659,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
564
659
 
565
660
  | Error | When it fires |
566
661
  |---|---|
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). |
662
+ | `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while the request relay may still answer. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
663
+ | `ErrRelayFallenBack` | The request's relay settled without acknowledgement and no pane answer is recorded through agent-director. Cursor uses finite `confirm_by` with null per-request hook process evidence; see [Cursor permissions](../../docs/permissions.md#cursor-spawns). Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
664
+ | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
570
665
  | `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
571
666
  | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
572
667
  | `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
573
668
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
574
669
  | `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
575
670
  | `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). |
671
+ | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request relay acknowledged its recorded verdict, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (for a request with a settle instant, `"delivered"` requires durable relay acknowledgement; requests recorded by an older binary retain the [legacy delivery rules](../../docs/permissions.md#requests-recorded-by-an-older-binary), including derived delivery after expiry even when closed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
672
+ | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the recorded decision and acknowledgement prevent a second API answer. Acknowledgement does not establish agent receipt or dialog closure; see [Permission relay](../../docs/caller-contract.md#permission-relay). It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay acknowledged, or one already closed at the pane, throws it too. |
673
+ | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). |
579
674
  | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
580
675
  | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
581
676
 
@@ -585,7 +680,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
585
680
  |---|---|
586
681
  | `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
587
682
  | `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`. |
683
+ | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude`, `codex` or `cursor`, the old name of the `agent_args` key, wrong types, bad enums, or one key set under names that differ only in letter case, such as `RELAY_MODE` and `relay_mode`). `makeTemplate` also throws it, before writing anything, for an `agent` that is not exactly `claude`, `codex` or `cursor`. |
589
684
  | `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
590
685
 
591
686
  **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";
14
+ export type { RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
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";
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;
@@ -238,7 +254,7 @@ export interface ListRow {
238
254
  state: string;
239
255
  /** Canonicalized working directory. */
240
256
  cwd: string;
241
- /** The agent the row runs: `"claude"` (Claude Code) or `"codex"` (Codex). Set at spawn; resume follows it. */
257
+ /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
242
258
  agent: string;
243
259
  /** tmux session name. */
244
260
  tmux_session_name: string;
@@ -303,7 +319,7 @@ export interface SpawnParams {
303
319
  /** Named template under ~/.config/agent-director/templates/. */
304
320
  template?: string;
305
321
  /**
306
- * The agent to launch: `"claude"` (Claude Code) or `"codex"` (Codex); case-sensitive,
322
+ * The agent to launch: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor); case-sensitive,
307
323
  * empty or absent means not given. Spawn resolves it per call, else from `template`'s
308
324
  * `agent`; with neither, the spawn is refused with `ErrAgentMissing`. Any other value is
309
325
  * refused with `ErrAgentInvalid`. A template's `agent_args` belong to the template's agent
@@ -349,6 +365,11 @@ export interface SpawnParams {
349
365
  * adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
350
366
  * `--enable write_stdin_approval` when the arguments already carry one before any `--`;
351
367
  * Codex rejects a flag the arguments themselves repeat.
368
+ * Cursor accepts `--model`/`-m` (split or equals), `--mode` (agent/plan/ask),
369
+ * `--plan`, and one final initial prompt (use `--` before a flag-like prompt).
370
+ * Explicit mode is configured through ACP before prompt admission; launch
371
+ * success alone does not confirm it. Other or malformed arguments are refused
372
+ * with `ErrSpawnDeniedFlag`; remove the named argument and any owned value, then retry.
352
373
  */
353
374
  agent_args?: string[];
354
375
  /**
@@ -356,7 +377,9 @@ export interface SpawnParams {
356
377
  * folder-trust entry (into `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets
357
378
  * `CLAUDE_CONFIG_DIR`, otherwise `~/.claude.json`). For a codex agent, it is putting the
358
379
  * 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,
380
+ * written). Cursor grants no trust: default false reports `failed` (ACP
381
+ * pre-trust unsupported); true reports `skipped`. Permission policy is independent.
382
+ * The choice is recorded on the row until the next spawn or reuse,
360
383
  * and every `resume` follows it. The result then reports
361
384
  * `pre_trust: "skipped"`. Default false.
362
385
  */
@@ -379,13 +402,18 @@ export interface SpawnParams {
379
402
  }
380
403
  /**
381
404
  * The launch result. The row is `pending` from its insert until
382
- * the agent reports in (its SessionStart hook), then `waiting`.
405
+ * the agent reports in (Cursor: verified first prompt), then `waiting`.
406
+ * Cursor initialization, session creation and requested mode validation happen
407
+ * asynchronously. This result does not confirm them; later failure appears in
408
+ * the pane and ad.cursor.failed. Missing still requires process evidence.
383
409
  */
384
410
  export interface SpawnResult {
385
411
  /** The id the new Spawn is tracked under. */
386
412
  instance_id: string;
387
413
  /**
388
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
414
+ * Cursor grants no trust: `"failed"` by default (ACP pre-trust unsupported),
415
+ * `"skipped"` with `no_pre_trust`; never `"ok"`. Permission policy is independent.
416
+ * For Claude/Codex, what the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
389
417
  * (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
390
418
  * trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the caller passed
391
419
  * `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
@@ -454,7 +482,7 @@ export interface GetResult {
454
482
  */
455
483
  state: string;
456
484
  cwd: string;
457
- /** The agent the row runs: `"claude"` (Claude Code) or `"codex"` (Codex). Set at spawn; resume follows it. */
485
+ /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
458
486
  agent: string;
459
487
  tmux_session_name: string;
460
488
  /** The tmux socket the row's launch uses; omitted when the row has no recorded socket. */
@@ -577,9 +605,14 @@ export interface SendKeysParams {
577
605
  /**
578
606
  * Makes the call a pane answer to this fallen-back permission request of the Spawn: one key
579
607
  * (`key`), no Enter, recorded as `pane_answer` `"sent"` with `decision` = `as`.
608
+ * This records the key send, not ACP delivery, receipt or proof.
580
609
  */
581
610
  request_token?: string;
582
- /** A pane answer's claimed verdict, recorded as its decision; never checked against the key. */
611
+ /**
612
+ * A pane answer's claimed verdict, recorded as its decision without screen verification or proof.
613
+ * Before answering ACP, Cursor additionally requires the sent claim to match the selected
614
+ * offered option's verdict.
615
+ */
583
616
  as?: "allow" | "deny";
584
617
  }
585
618
  /** Successful sendKeys calls return an empty object. */
@@ -681,7 +714,11 @@ export interface GetPermissionResult extends RequestDelivery {
681
714
  * Canonical decision-reason string: "operator" | "timeout" | "find_missing" | "ended" for deny
682
715
  * rows ("find_missing" / "ended": still undecided when find-missing marked its spawn missing, or
683
716
  * 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.
717
+ * request answered through sendKeys or a Cursor native choice ("pane"), recorded outside
718
+ * ("pane_outside"), or carrying tool execution evidence ("tool_ran"). Pane claims do not establish
719
+ * ACP delivery, receipt or proof. Initially null while undecided without an outside claim, and
720
+ * for an allow from decide. Validated Cursor execution proof fills a missing reason with
721
+ * "tool_ran" while preserving any earlier verdict and non-null reason.
685
722
  */
686
723
  decision_reason?: "operator" | "timeout" | "find_missing" | "ended" | "pane" | "pane_outside" | "tool_ran" | null;
687
724
  /** RFC3339 timestamp when the verdict was written; null while undecided. */
@@ -696,7 +733,8 @@ export interface RecordPaneAnswerParams {
696
733
  request_token: string;
697
734
  /**
698
735
  * 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.
736
+ * not seen (pass "unknown" unless it was). Stored, never checked; it never authorizes a Cursor
737
+ * ACP answer or supplies execution proof.
700
738
  */
701
739
  as: "allow" | "deny" | "unknown";
702
740
  /** The `pane_sha256` of the readPane that showed it answered; compared byte for byte. */
@@ -781,6 +819,12 @@ export interface PaneKeySentDetails {
781
819
  key_sent: true;
782
820
  request_token: string;
783
821
  }
822
+ /** ErrSubmissionUnconfirmed's errDetails; submission remains unknown despite keys_sent. */
823
+ export interface SubmissionUnconfirmedDetails {
824
+ keys_sent: true;
825
+ submission_confirmed: false;
826
+ row_state: string;
827
+ }
784
828
  /**
785
829
  * ErrPaneChanged's errDetails. It never carries the pane's
786
830
  * new hash: read the pane again before any retry.
@@ -806,14 +850,19 @@ export interface ResumeParams {
806
850
  * are re-encoded, only when needed to preserve their original parsed meaning;
807
851
  * otherwise their order and spelling survive. Stored agent_args are unchanged.
808
852
  * Resume moved the row to `pending`, keeping
809
- * its session id and history, until the agent reports in (its SessionStart hook),
853
+ * its session id and history, until the agent reports in (Cursor: verified first prompt),
810
854
  * then `waiting`.
855
+ * Cursor loads the latest saved session asynchronously with no fresh fallback;
856
+ * returning does not confirm runtime, load or requested mode success.
811
857
  */
812
858
  export interface ResumeResult {
813
859
  /** Same id that was passed in (resume preserves it). */
814
860
  instance_id: string;
815
861
  /**
816
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
862
+ * Cursor grants no trust: `"failed"` by default (ACP pre-trust unsupported),
863
+ * `"skipped"` with the stored opt-out; never `"ok"`. Resume preserves that choice
864
+ * until the next spawn or reuse. Permission policy is independent.
865
+ * For Claude/Codex, what the launch's folder-trust pre-trust did. `"ok"`: the folder trust took effect
817
866
  * (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
818
867
  * trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the row records that
819
868
  * the row's latest spawn turned it off (`no_pre_trust`); nothing was attempted.
@@ -921,9 +970,9 @@ export interface MakeTemplateParams {
921
970
  /** Default working directory to bake in. */
922
971
  cwd?: string;
923
972
  /**
924
- * The agent the template belongs to: `"claude"` (Claude Code) or `"codex"` (Codex);
973
+ * The agent the template belongs to: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor);
925
974
  * 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
975
+ * `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex or Cursor template cannot bake in
927
976
  * `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). Any other value is refused
928
977
  * with `ErrTemplateMalformed` (`ErrAgentInvalid` is spawn's per-call refusal). A spawn
929
978
  * that names no agent takes it from the template.
@@ -931,7 +980,7 @@ export interface MakeTemplateParams {
931
980
  agent?: string;
932
981
  /** Default relay mode: "on" | "off" | "" (inherit). */
933
982
  relay_mode?: string;
934
- /** Default agent argv. Per-call `agent_args` replaces wholesale. */
983
+ /** 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
984
  agent_args?: string[];
936
985
  /**
937
986
  * Env-var overrides to bake in. A key spawn would refuse is refused here with
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],