agent-director 0.11.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/types.d.ts CHANGED
@@ -10,13 +10,13 @@ export interface Logger {
10
10
  error?: (message: string, ...args: unknown[]) => void;
11
11
  }
12
12
  /**
13
- * Options accepted by the `Client` constructor (SRD SR-1.2).
13
+ * Options accepted by the `Client` constructor.
14
14
  *
15
- * All fields are optional. When omitted, the bundled CLI binary's own
15
+ * All fields are optional. When omitted, the installed CLI binary's own
16
16
  * three-tier default resolution applies (config.toml value, then the CLI's
17
- * hardcoded fallback such as `~/.agent-director/state.db`). The TS Client
17
+ * hardcoded fallback such as `~/.config/agent-director/state.db`). The TS Client
18
18
  * does NOT provide a fallback; it forwards user input verbatim to keep the
19
- * CLI as the single source of truth for default resolution. See bug b.32k.
19
+ * CLI as the single source of truth for default resolution.
20
20
  *
21
21
  * `storePath`, `home` and `tmuxCommand` are forwarded verbatim; the TS Client
22
22
  * does no tilde expansion of its own. The CLI subprocess, which inherits this
@@ -27,11 +27,11 @@ export interface Logger {
27
27
  * passwd home: with `HOME` unset or empty, a `~` or `~/` `home` rejects every
28
28
  * call with `ErrInvalidFlags`, and with no `home` either, every call that
29
29
  * opens the store is refused. Other values, relative paths included, are
30
- * forwarded unchanged and the CLI resolves them. b.38a.
30
+ * forwarded unchanged and the CLI resolves them.
31
31
  *
32
32
  * An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
33
33
  * `--store-path ""`); the CLI rejects it on every verb call, which then
34
- * rejects with `ErrInvalidFlags`. It never falls back to the default. b.pu2.
34
+ * rejects with `ErrInvalidFlags`. It never falls back to the default.
35
35
  */
36
36
  export interface ClientOptions {
37
37
  /**
@@ -39,11 +39,11 @@ export interface ClientOptions {
39
39
  * CLI subprocess, which expands a leading `~/`.
40
40
  *
41
41
  * When omitted, the CLI's three-tier default resolution applies:
42
- * 1. CLI flag (this field, when set) → 2. cfg.Store.DbPath in
43
- * ~/.agent-director/config.toml → 3. hardcoded fallback
44
- * ~/.agent-director/state.db.
42
+ * 1. CLI flag (this field, when set) → 2. [store] db_path in
43
+ * ~/.config/agent-director/config.toml → 3. hardcoded fallback
44
+ * ~/.config/agent-director/state.db.
45
45
  *
46
- * The TS Client no longer provides a fallback (b.32k).
46
+ * The TS Client forwards the option unchanged.
47
47
  */
48
48
  storePath?: string;
49
49
  /**
@@ -61,64 +61,201 @@ export interface ClientOptions {
61
61
  * environment (which is the correct default — set HOME at the
62
62
  * test-process level via withTempHome or similar). Set this only when you
63
63
  * need the CLI to resolve `~/...` paths against a specific directory that
64
- * differs from the calling process's HOME. b.32k.
64
+ * differs from the calling process's HOME.
65
65
  */
66
66
  home?: string;
67
67
  /**
68
- * When `true`, create the store and initialize the database schema if the
69
- * store file does not yet exist. When `false` (the default), opening a
70
- * non-existent store returns an error. Mirrors `pkg/api.Options.CreateIfMissing`.
68
+ * Whether a call that opens the store creates it when it does not exist.
69
+ *
70
+ * - Omitted: the CLI's default, which creates a missing store.
71
+ * - `true`: a missing store is created (parent directories, file and
72
+ * schema) by the first call that opens it. No flag is forwarded, since
73
+ * this is the CLI's default.
74
+ * - `false`: forwarded as `--create-if-missing false`. A call that opens a
75
+ * missing store rejects with `ErrStoreOpen` (its cause: the store is not
76
+ * initialized) and creates none of it. Calls that open no store, such as
77
+ * `version`, are unaffected.
78
+ *
79
+ * `true` and `false` mirror `pkg/api.Options.CreateIfMissing`; unlike that
80
+ * field, omitting this one keeps the CLI's default, which creates the store.
81
+ * `false` needs a CLI binary that knows `--create-if-missing`: an older
82
+ * binary rejects every call made with it.
71
83
  */
72
84
  createIfMissing?: boolean;
73
85
  /** Optional logger for client-side warnings (e.g., non-fatal close errors). */
74
86
  logger?: Logger;
75
87
  /**
76
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.
77
91
  *
78
92
  * When a subprocess call exceeds this threshold the Client sends SIGTERM,
79
93
  * waits up to 2 seconds for a graceful exit, then sends SIGKILL. The
80
94
  * in-flight call's promise rejects with ErrCallTimeout.
81
95
  *
82
96
  * Zero or negative values are rejected at Client construction time.
83
- * (SRD SR-6.1)
97
+ *
98
+ * Each store statement a call runs can wait up to the store's busy
99
+ * timeout (`[store] busy_timeout_ms`, 10 s by default) while another
100
+ * process holds the store locked. A call whose waits add up to this
101
+ * timeout, one wait at this length or more or several shorter ones, is
102
+ * cut off with ErrCallTimeout before SQLite gives up. Nothing adjusts this
103
+ * timeout to that key: raise it to match when raising the key.
84
104
  */
85
105
  callTimeoutMs?: number;
86
106
  }
87
- /** Mirrors pkg/api.VerbSummary — one entry in the `help` verb result. */
107
+ /** One entry in the `help` verb result. */
88
108
  export interface VerbSummary {
89
109
  /** Canonical CLI/MCP verb name (e.g. "spawn", "send-keys"). */
90
110
  name: string;
91
111
  /** One-line verb description from the manifest. */
92
112
  description: string;
93
113
  }
94
- /** Mirrors pkg/api/get.go::PermissionRequestInfo — embedded in GetResult when state=check_permission. */
95
- export interface PermissionRequestInfo {
114
+ /**
115
+ * A permission request's delivery state:
116
+ * - `"delivered"`: the relay durably acknowledged a verdict before enqueue/write;
117
+ * this is not agent receipt, tool execution or dialog closure.
118
+ * - `"not_confirmed"`: no ack yet and the relay hook may still run; it ends by `confirm_by`.
119
+ * - `"fallen_back"`: no ack, and the relay hook is gone (or cannot be checked and `confirm_by`
120
+ * has passed): no answer from the relay reached the agent. While `pane_answer` is `"none"` or
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.
124
+ */
125
+ export type Delivery = "delivered" | "not_confirmed" | "fallen_back";
126
+ /**
127
+ * How a permission request was answered at the pane:
128
+ * - `"none"`: no pane answer recorded through agent-director (something outside it, such as a
129
+ * person at tmux, may still have answered it).
130
+ * - `"intent"`: a pane answer through `sendKeys` was started; whether its key was typed is unknown.
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.
133
+ * - `"outside"`: a caller recorded it answered outside agent-director (`recordPaneAnswer`,
134
+ * `decision_reason` `"pane_outside"`).
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"`.
139
+ * `"sent"`, `"outside"` and `"tool_ran"` close the request; its `delivery` stays `"fallen_back"`.
140
+ */
141
+ export type PaneAnswer = "none" | "intent" | "sent" | "outside" | "tool_ran";
142
+ /**
143
+ * A permission request's delivery facts, with whether agent evidence proved its dialog gone, on every
144
+ * `get` / `list` permission request and `get`'s `unproven_requests`, on `getPermission` and on
145
+ * `decide`'s result. Derived on every read. A recorded `decision` is not the outcome:
146
+ * `delivery` is.
147
+ */
148
+ export interface RequestDelivery {
149
+ /** Delivery state; see {@link Delivery}. */
150
+ delivery: Delivery;
151
+ /**
152
+ * RFC3339 time by which `not_confirmed` ends: the relay hook's kill instant plus 2 s. For a
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.
156
+ */
157
+ confirm_by: string;
158
+ /**
159
+ * Whether the relay hook process runs: true, false, or null when it cannot be checked
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.
162
+ */
163
+ hook_alive: boolean | null;
164
+ /** When a reader first found the request fallen back; null until then. */
165
+ hook_gone_at: string | null;
166
+ /** The verdict a decide refused as fallen back tried to record; null when none. Never acted on. */
167
+ attempted_decision: "allow" | "deny" | null;
168
+ /** When that refused decide ran; null when none. */
169
+ attempted_at: string | null;
170
+ /** Hook tool_use_id or Cursor's supplied toolCallId; null when none was given. */
171
+ tool_use_id: string | null;
172
+ /** How the request was answered at the pane; see {@link PaneAnswer}. */
173
+ pane_answer: PaneAnswer;
174
+ /**
175
+ * The verdict a pane answer claims: allow, deny, or unknown (an outside record that did not see
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.
179
+ */
180
+ pane_as: "allow" | "deny" | "unknown" | null;
181
+ /**
182
+ * When agent evidence proved the request's permission dialog gone; null until
183
+ * then. agent-director's own records (`delivered`, a pane answer, `recordPaneAnswer`) are not
184
+ * proof. While it is null, a plain `sendKeys` to the live Spawn without `expect_pane_sha256`,
185
+ * and a `pause`, reject with `ErrDialogMaybeOpen`.
186
+ */
187
+ proven_gone_at: string | null;
188
+ /** How it was proven gone; see {@link ProvenGoneHow}. Null until proven. */
189
+ proven_gone_how: ProvenGoneHow | null;
190
+ /**
191
+ * For a request not proven gone that no longer awaits an answer in agent-director's records:
192
+ * when its record stopped awaiting one (its relay hook's ack, its pane answer's or
193
+ * `recordPaneAnswer`'s write, or the close of its Spawn's requests; a request with no recorded settle instant: its recorded verdict). Null while it still awaits an answer, and once proven
194
+ * gone. A request that stays unproven a while after it is a reason to read the pane.
195
+ */
196
+ unproven_since: string | null;
197
+ }
198
+ /**
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).
202
+ * - `"turn_end"`: the turn of the agent that asked ended after it was written; the main agent's
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.
208
+ * - `"agent_gone"`: its Spawn was marked missing, ended or resumed.
209
+ */
210
+ export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
211
+ /**
212
+ * One permission request with its delivery facts:
213
+ * an open one (still awaiting an answer) in the `permission_requests` of a `get` or `list` row in
214
+ * state check_permission; one not proven gone, open or read closed, in `get`'s
215
+ * `unproven_requests`; and the request an `errDetails` names (the base of
216
+ * `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
217
+ */
218
+ export interface PermissionRequestInfo extends RequestDelivery {
96
219
  /** Autoincrement primary key of the permission_requests row. */
97
220
  request_id: number;
98
- /** 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. */
99
222
  request_token: string;
100
- /** Claude Code tool that triggered the permission request (e.g. "Bash"). */
223
+ /** Supplied tool name (e.g. "Bash") or Cursor action title/plan name. */
101
224
  tool_name: string;
102
- /** 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. */
103
227
  tool_input: string;
104
228
  /** RFC3339 timestamp when the permission request row was created. */
105
229
  requested_at: string;
230
+ /** The recorded verdict, not the outcome (read `delivery`); null while none is recorded. */
231
+ decision: "allow" | "deny" | null;
232
+ /** The recorded verdict's decision_reason; null when none is recorded. */
233
+ decision_reason: string | null;
106
234
  }
107
- /** Mirrors pkg/api/list.go::ListRow — one Spawn row returned by the list verb. */
235
+ /** One Spawn row returned by the list verb. */
108
236
  export interface ListRow {
109
237
  /** Stable Spawn id. */
110
- claude_instance_id: string;
238
+ instance_id: string;
111
239
  /** Parent Spawn id (omitted when launched from a plain shell). */
112
240
  parent_id?: string;
113
241
  /**
114
242
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
115
243
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
116
- * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
244
+ * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
117
245
  * prompt. A resumed pending row keeps its session id and history.
246
+ *
247
+ * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
248
+ * off), this is the settled state: a state a hook wrote shows only once it has held for
249
+ * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
250
+ * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
251
+ * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
252
+ * its live state, which can be newer: a refusal can name a state this field does not show yet.
118
253
  */
119
254
  state: string;
120
255
  /** Canonicalized working directory. */
121
256
  cwd: string;
257
+ /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
258
+ agent: string;
122
259
  /** tmux session name. */
123
260
  tmux_session_name: string;
124
261
  /** "on" or "off". */
@@ -131,13 +268,20 @@ export interface ListRow {
131
268
  last_seen_at: string;
132
269
  /** Set when state moves to ended (omitted while live). */
133
270
  ended_at?: string | null;
134
- /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
271
+ /**
272
+ * Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
273
+ * pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
274
+ * set, a row whose agent has reported in can read pending without it for up to settle_ms.
275
+ */
135
276
  launch_started_at?: string | null;
136
277
  /**
137
- * RFC3339 timestamp of the first sweep that left this live row unverified;
138
- * kept while later sweeps change `liveness_note`. Cleared together with
139
- * `liveness_note` when a sweep finds the agent process alive; omitted/null
140
- * while not unverified.
278
+ * RFC3339 timestamp of the first sweep that noted this live row (left it
279
+ * unverified, or noted it `unreported`); kept while later sweeps change
280
+ * `liveness_note`, `unreported` included. Cleared together with
281
+ * `liveness_note` when a sweep finds the agent process alive, except on a
282
+ * pending row it notes `unreported` and a pending row noted
283
+ * `provenance_conflict`, which keeps it; omitted/null while the row has no
284
+ * note.
141
285
  */
142
286
  liveness_unverified_since?: string | null;
143
287
  /**
@@ -147,18 +291,45 @@ export interface ListRow {
147
291
  * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
148
292
  * or `provenance_conflict`; overwritten when the reason changes. Cleared
149
293
  * together with `liveness_unverified_since` when a sweep finds the agent
150
- * process alive; omitted/null while not unverified.
294
+ * process alive, except on a pending row it notes `unreported` and a
295
+ * pending row noted `provenance_conflict`, which keeps it; omitted/null
296
+ * while the row has no note. Or `unreported`, on a pending row past the
297
+ * pending grace period: its agent is alive, but no hook has reported since
298
+ * its launch, so it may sit at an agent startup screen or idle at its
299
+ * prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
300
+ * with `allow_pending`; only a caller that looked should type. A later
301
+ * sweep that finds the agent alive keeps the note; the agent's next hook
302
+ * clears it. `unreported` never replaces `provenance_conflict`.
151
303
  */
152
304
  liveness_note?: string | null;
305
+ /**
306
+ * The row's open permission requests (those still awaiting an answer), each with its
307
+ * delivery facts; populated only when the row's live state is check_permission, `[]`
308
+ * otherwise. A row can read waiting, working or ask_user while a request is still open:
309
+ * follow a tracked request with `getPermission`. Requests are never delayed by
310
+ * `[state] settle_ms`, so with it set a row can also read any state (even ended or missing)
311
+ * with open requests listed, or check_permission with `[]`, for up to settle_ms.
312
+ */
313
+ permission_requests: PermissionRequestInfo[];
153
314
  }
154
- /** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
315
+ /** Parameters for launching a tracked agent. */
155
316
  export interface SpawnParams {
156
- /** Absolute (or ~/-prefixed) path the Spawn's Claude starts in. Required. */
317
+ /** Absolute (or ~/-prefixed) path the Spawn's agent starts in. Required. */
157
318
  cwd: string;
158
- /** Named template under ~/.agent-director/templates/. */
319
+ /** Named template under ~/.config/agent-director/templates/. */
159
320
  template?: string;
321
+ /**
322
+ * The agent to launch: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor); case-sensitive,
323
+ * empty or absent means not given. Spawn resolves it per call, else from `template`'s
324
+ * `agent`; with neither, the spawn is refused with `ErrAgentMissing`. Any other value is
325
+ * refused with `ErrAgentInvalid`. A template's `agent_args` belong to the template's agent
326
+ * and are refused with `ErrAgentArgsMismatch` when the spawn's agent differs, unless this call
327
+ * passes its own non-empty `agent_args`. The
328
+ * row records it for life; `get` and `list` show it.
329
+ */
330
+ agent?: string;
160
331
  /** Explicit instance id (UUID4 minted when absent). */
161
- claude_instance_id?: string;
332
+ instance_id?: string;
162
333
  /** KEY=VALUE label pairs. */
163
334
  label?: string[];
164
335
  /** permissions.allow entries. */
@@ -169,88 +340,164 @@ export interface SpawnParams {
169
340
  ask?: string[];
170
341
  /** "on" | "off" | "" (use config default). */
171
342
  relay_mode?: string;
172
- /** KEY→VALUE env-var overrides injected on the tmux session. */
343
+ /**
344
+ * KEY→VALUE env-var overrides injected on the tmux session. `AGENT_DIRECTOR_*`
345
+ * keys and `HOME` (any value) are refused with `ErrReservedEnvKey`, a template's
346
+ * included: an extra_env `HOME` would move the agent's hook to another
347
+ * agent-director store. Set an absolute `CLAUDE_CONFIG_DIR` (Claude Code) or
348
+ * `CODEX_HOME` (Codex) to give the agent its own config folder. A key that is not a valid env-var name (empty, or
349
+ * containing `=` or a NUL character, which tmux would read as a different
350
+ * variable) is refused with `ErrReservedEnvKey` too, a template's included,
351
+ * and never rewritten; the description says what is wrong with it, and
352
+ * nothing is launched.
353
+ */
173
354
  extra_env?: Record<string, string>;
174
- /** Pass-through argv to `claude` after --settings. */
175
- claude_args?: string[];
176
355
  /**
177
- * Skip pre-writing the folder-trust entry for `cwd` (into
178
- * `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets `CLAUDE_CONFIG_DIR`,
179
- * otherwise `~/.claude.json`). The choice is recorded on the row for its life,
180
- * and every `resume` of that life follows it. The result then reports
356
+ * Pass-through argv to the agent's program. Claude always refuses `--settings`,
357
+ * `--output-format` and print (`-p`/`--print`, parsed clusters included). Session
358
+ * selectors and owned values are refused except on a finished-agent switch:
359
+ * removed tokens appear in `dropped_args`; the agent starts fresh and resumes nothing.
360
+ * Exact denied long tokens owned as option values always refuse. For codex, a Codex subcommand in
361
+ * command position, `--remote`, `--remote-auth-token-env`, `-c`/`--config` keys at, above or
362
+ * under `hooks`, `tui.disable_paste_burst` or `features.hooks`, and `--disable hooks` are
363
+ * refused (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
364
+ * default_mode_request_user_input` and the question-tool keys are refused too. agent-director
365
+ * adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
366
+ * `--enable write_stdin_approval` when the arguments already carry one before any `--`;
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.
373
+ */
374
+ agent_args?: string[];
375
+ /**
376
+ * Skip the folder pre-trust for `cwd`. For a claude agent, that is pre-writing the
377
+ * folder-trust entry (into `<CLAUDE_CONFIG_DIR>/.claude.json` when `extra_env` sets
378
+ * `CLAUDE_CONFIG_DIR`, otherwise `~/.claude.json`). For a codex agent, it is putting the
379
+ * folder trust and the hook-trust bypass on the launch's command line (no file is
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,
383
+ * and every `resume` follows it. The result then reports
181
384
  * `pre_trust: "skipped"`. Default false.
182
385
  */
183
386
  no_pre_trust?: boolean;
184
387
  /** Explicit tmux session name. Auto-derived when absent. */
185
388
  tmux_session_name?: string;
186
389
  /**
187
- * Reuse an explicit `claude_instance_id` whose row is `ended` or `missing`;
390
+ * Reuse an explicit `instance_id` whose row is `ended` or `missing`;
188
391
  * a live row, `pending` included, still collides. No effect without an
189
- * explicit `claude_instance_id`; applies to this call only. Default false:
190
- * any existing row with the id collides with `ErrInstanceIdCollision`.
392
+ * explicit `instance_id`; applies to this call only. The spawn names its
393
+ * agent (`agent`, or the template's) and the reused row takes it; to reuse
394
+ * a row for the agent it ran, pass the row's agent, which `get` shows.
395
+ * Same-agent reuse starts a fresh conversation and retains history and subagent records.
396
+ * An agent switch or switch back starts a new life, hiding earlier lives.
397
+ * Resume continues only the latest session; older sessions are for inspection only.
398
+ * Default false: any existing row with the id collides with
399
+ * `ErrInstanceIdCollision`.
191
400
  */
192
401
  reuse_finished?: boolean;
193
402
  }
194
403
  /**
195
- * Mirrors pkg/api/spawn.go::SpawnResult. The row is `pending` from its insert until
196
- * the agent reports in (Claude Code's SessionStart), then `waiting`.
404
+ * The launch result. The row is `pending` from its insert until
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.
197
409
  */
198
410
  export interface SpawnResult {
199
411
  /** The id the new Spawn is tracked under. */
200
- claude_instance_id: string;
412
+ instance_id: string;
201
413
  /**
202
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
203
- * written. `"skipped"`: pre-trust was off for this launch because the caller passed
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
417
+ * (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
418
+ * trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the caller passed
204
419
  * `no_pre_trust`; nothing was attempted. `"failed"`: pre-trust was attempted and the
205
- * entry was not written (the `.claude.json` file is missing, or could not be read,
206
- * parsed or written); the agent may stop at Claude Code's folder-trust prompt.
207
- * A pre-trust failure never fails the spawn.
420
+ * entry was not written (a claude agent: the `.claude.json` file is missing, or could not
421
+ * be read, parsed or written, or `extra_env` sets `CLAUDE_CONFIG_DIR` to a path that is
422
+ * not absolute; a codex agent: `extra_env` sets `CODEX_HOME` to a path that is not
423
+ * absolute, and the launch carries neither the folder trust nor the hook-trust bypass);
424
+ * the agent may stop at its folder-trust prompt. A pre-trust failure never fails the
425
+ * spawn.
208
426
  */
209
427
  pre_trust: "ok" | "skipped" | "failed";
428
+ /** Original resume tokens removed on a finished-agent switch, in argv order; omitted when empty. */
429
+ dropped_args?: string[];
210
430
  }
211
- /** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
431
+ /** The id whose state is requested. */
212
432
  export interface StatusParams {
213
433
  /** Id of the Spawn to inspect. */
214
- claude_instance_id: string;
434
+ instance_id: string;
215
435
  }
216
- /** Mirrors pkg/api/status.go::StatusResult */
436
+ /** The row's reported lifecycle state. */
217
437
  export interface StatusResult {
218
438
  /**
219
439
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
220
440
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
221
- * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
441
+ * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
222
442
  * prompt. A resumed pending row keeps its session id and history; a caller tells it
223
- * from a fresh one by its non-empty `claude_session_id`, shown by `get`.
443
+ * from a fresh one by its non-empty `session_id`, shown by `get`.
444
+ *
445
+ * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
446
+ * off), this is the settled state: a state a hook wrote shows only once it has held for
447
+ * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
448
+ * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
449
+ * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
450
+ * can be newer: a refusal can name a state status does not show yet.
224
451
  */
225
452
  state: string;
226
- /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
453
+ /**
454
+ * Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
455
+ * pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
456
+ * set, a row whose agent has reported in can read pending without it for up to settle_ms.
457
+ */
227
458
  launch_started_at?: string | null;
228
459
  }
229
- /** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
460
+ /** The id whose row is requested. */
230
461
  export interface GetParams {
231
462
  /** Id of the Spawn to fetch. */
232
- claude_instance_id: string;
463
+ instance_id: string;
233
464
  }
234
- /** Mirrors pkg/api/get.go::SpawnRow */
465
+ /** One tracked agent row, with its current session and request facts. */
235
466
  export interface GetResult {
236
- claude_instance_id: string;
467
+ instance_id: string;
237
468
  parent_id: string;
238
469
  /**
239
470
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
240
471
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
241
- * reported in yet (Claude Code's SessionStart); it may be loading or waiting at a startup
472
+ * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
242
473
  * prompt. A resumed pending row keeps its session id and history; a non-empty
243
- * `claude_session_id` tells it from a fresh one.
474
+ * `session_id` tells it from a fresh one.
475
+ *
476
+ * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
477
+ * off), this is the settled state: a state a hook wrote shows only once it has held for
478
+ * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
479
+ * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
480
+ * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
481
+ * its live state, which can be newer: a refusal can name a state this field does not show yet.
244
482
  */
245
483
  state: string;
246
484
  cwd: string;
485
+ /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
486
+ agent: string;
247
487
  tmux_session_name: string;
248
- /** The tmux socket the row's launch uses; omitted for a row from before this release. */
488
+ /** The tmux socket the row's launch uses; omitted when the row has no recorded socket. */
249
489
  tmux_socket?: string | null;
250
- claude_args: string[];
490
+ agent_args: string[];
251
491
  relay_mode: string;
492
+ /**
493
+ * Current session's transcript path, persisted by its hooks; legacy rows may be empty.
494
+ * Resume tries it, then for Claude recomputes the current session's path from `cwd`
495
+ * and `session_id`, under a usable absolute `CLAUDE_CONFIG_DIR` from `extra_env`
496
+ * (otherwise `~/.claude`). Codex uses only its recorded path. Older sessions remain
497
+ * listed for inspection only and are never resume candidates.
498
+ */
252
499
  jsonl_path: string;
253
- claude_session_id: string;
500
+ session_id: string;
254
501
  labels: Record<string, string>;
255
502
  /** Row insert time (RFC3339). */
256
503
  started_at: string;
@@ -258,13 +505,20 @@ export interface GetResult {
258
505
  last_seen_at: string;
259
506
  /** Set when state moves to ended; omitted while live. */
260
507
  ended_at?: string | null;
261
- /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
508
+ /**
509
+ * Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
510
+ * pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
511
+ * set, a row whose agent has reported in can read pending without it for up to settle_ms.
512
+ */
262
513
  launch_started_at?: string | null;
263
514
  /**
264
- * RFC3339 timestamp of the first sweep that left this live row unverified;
265
- * kept while later sweeps change `liveness_note`. Cleared together with
266
- * `liveness_note` when a sweep finds the agent process alive; omitted/null
267
- * while not unverified.
515
+ * RFC3339 timestamp of the first sweep that noted this live row (left it
516
+ * unverified, or noted it `unreported`); kept while later sweeps change
517
+ * `liveness_note`, `unreported` included. Cleared together with
518
+ * `liveness_note` when a sweep finds the agent process alive, except on a
519
+ * pending row it notes `unreported` and a pending row noted
520
+ * `provenance_conflict`, which keeps it; omitted/null while the row has no
521
+ * note.
268
522
  */
269
523
  liveness_unverified_since?: string | null;
270
524
  /**
@@ -274,22 +528,55 @@ export interface GetResult {
274
528
  * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
275
529
  * or `provenance_conflict`; overwritten when the reason changes. Cleared
276
530
  * together with `liveness_unverified_since` when a sweep finds the agent
277
- * process alive; omitted/null while not unverified.
531
+ * process alive, except on a pending row it notes `unreported` and a
532
+ * pending row noted `provenance_conflict`, which keeps it; omitted/null
533
+ * while the row has no note. Or `unreported`, on a pending row past the
534
+ * pending grace period: its agent is alive, but no hook has reported since
535
+ * its launch, so it may sit at an agent startup screen or idle at its
536
+ * prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
537
+ * with `allow_pending`; only a caller that looked should type. A later
538
+ * sweep that finds the agent alive keeps the note; the agent's next hook
539
+ * clears it. `unreported` never replaces `provenance_conflict`.
278
540
  */
279
541
  liveness_note?: string | null;
280
- /** Open permission request; present only when state=check_permission with an undecided row. */
281
- permission_request?: PermissionRequestInfo | null;
542
+ /**
543
+ * The row's open permission requests (those still awaiting an answer: not acked by their relay
544
+ * hook and not answered at the pane, decided or not), each with its delivery facts; populated
545
+ * only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
546
+ * working or ask_user while a request is still open: follow a tracked request with
547
+ * `getPermission`.
548
+ * Requests are never delayed by `[state] settle_ms`, so with it set a row can also read any
549
+ * state (even ended or missing) with open requests listed, or check_permission with `[]`, for
550
+ * up to settle_ms.
551
+ */
552
+ permission_requests: PermissionRequestInfo[];
553
+ /**
554
+ * Every permission request of the row that the agent's hooks have not proven gone (`proven_gone_at`
555
+ * null), oldest first, in any live state but ended and missing (`[]` on those). Unlike
556
+ * `permission_requests` it also lists requests agent-director's records read closed
557
+ * (delivered, answered at the pane, or recorded answered outside it), each with
558
+ * `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
559
+ * and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
560
+ * row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
561
+ * with `state` for up to settle_ms.
562
+ */
563
+ unproven_requests: PermissionRequestInfo[];
282
564
  }
283
- /** Mirrors pkg/api.SendKeysParams (json tags). */
565
+ /**
566
+ * Parameters for sending keys. A call is plain, or a pane answer when
567
+ * `request_token` is set: a pane answer needs `as`, `key` and
568
+ * `expect_pane_sha256`, takes no `text`, and sends exactly one key with no Enter.
569
+ */
284
570
  export interface SendKeysParams {
285
- /** Id of the Spawn whose pane will receive the text. */
286
- claude_instance_id: string;
571
+ /** Id of the Spawn whose pane will receive the keys. */
572
+ instance_id: string;
287
573
  /**
288
- * Text to deliver to the pane. CR bytes stripped; LF preserved; Enter
289
- * appended. Empty text sends Enter only: it submits what is already typed,
290
- * such as a text a failed sendKeys left unsubmitted.
574
+ * Text to deliver to the pane on a plain call. CR bytes stripped; LF preserved; Enter
575
+ * appended unless `no_enter`. Empty or omitted text sends Enter only: it submits what is
576
+ * already typed, such as a text a failed sendKeys left unsubmitted. Exclusive with `key`;
577
+ * must be empty on a pane answer.
291
578
  */
292
- text: string;
579
+ text?: string;
293
580
  /**
294
581
  * When true, also allows a pending row: a launch (spawn, reuse or resume)
295
582
  * whose agent has not reported in yet. Keys are delivered only to a
@@ -297,15 +584,45 @@ export interface SendKeysParams {
297
584
  * still rejected.
298
585
  */
299
586
  allow_pending?: boolean;
587
+ /** Type `text` with no Enter after it (plain calls; a pane answer never presses Enter). */
588
+ no_enter?: boolean;
589
+ /**
590
+ * One key to send instead of text, never followed by Enter: a named key (`"Escape"`,
591
+ * `"Enter"`, `"Up"`, `"Down"`, `"Tab"`) or one character. Required on a pane answer.
592
+ */
593
+ key?: string;
594
+ /**
595
+ * The `pane_sha256` of the readPane the keys were chosen from: the pane is captured again
596
+ * with the same `n_lines` (ANSI stripped) and compared byte for byte, `ErrPaneChanged` when it
597
+ * differs (the error does not carry the new hash). Required on a pane answer. On a plain call
598
+ * a matching hash also passes the hold of a request not proven gone (`ErrDialogMaybeOpen`);
599
+ * every other refusal still applies. Never pass it from an automatic flow: it means a person
600
+ * or LLM judged this exact screen.
601
+ */
602
+ expect_pane_sha256?: string;
603
+ /** The `n_lines` of the readPane `expect_pane_sha256` came from. Defaults to 25. */
604
+ n_lines?: number;
605
+ /**
606
+ * Makes the call a pane answer to this fallen-back permission request of the Spawn: one key
607
+ * (`key`), no Enter, recorded as `pane_answer` `"sent"` with `decision` = `as`.
608
+ * This records the key send, not ACP delivery, receipt or proof.
609
+ */
610
+ request_token?: string;
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
+ */
616
+ as?: "allow" | "deny";
300
617
  }
301
- /** Mirrors pkg/api/sendkeys.go::SendKeysResult (empty; reserved for future fields). */
618
+ /** Successful sendKeys calls return an empty object. */
302
619
  export interface SendKeysResult {
303
620
  }
304
- /** Mirrors pkg/api.ReadPaneParams (json tags). */
621
+ /** Parameters for capturing the agent's pane. */
305
622
  export interface ReadPaneParams {
306
623
  /** Id of the Spawn whose pane will be captured. */
307
- claude_instance_id: string;
308
- /** Trailing lines to return. Defaults to 25 when 0/omitted. */
624
+ instance_id: string;
625
+ /** Trailing lines to return. Defaults to 25 when 0/omitted. A negative value is refused (ErrInvalidFlags). */
309
626
  n_lines?: number;
310
627
  /** When true return raw bytes (ANSI preserved); when false strip ANSI (default). */
311
628
  ansi?: boolean;
@@ -316,79 +633,245 @@ export interface ReadPaneParams {
316
633
  */
317
634
  allow_pending?: boolean;
318
635
  }
319
- /** Mirrors pkg/api/readpane.go::ReadPaneResult */
636
+ /** Captured pane text and its checksum. */
320
637
  export interface ReadPaneResult {
321
638
  /** Captured pane text. */
322
639
  pane: string;
640
+ /**
641
+ * SHA-256, lowercase hex, of exactly the bytes of `pane`. Pass it as sendKeys' or
642
+ * recordPaneAnswer's `expect_pane_sha256`, with the same `n_lines`, when acting on what this
643
+ * pane shows; those compare it with the pane as readPane gives it by default (ANSI stripped).
644
+ */
645
+ pane_sha256: string;
323
646
  }
324
- /** Mirrors pkg/api.KillParams. */
647
+ /** Parameters for stopping the tracked agent. */
325
648
  export interface KillParams {
326
649
  /** Id of the Spawn to kill. */
327
- claude_instance_id: string;
650
+ instance_id: string;
328
651
  }
329
- /** Mirrors pkg/api/kill.go::KillResult (json tags). */
652
+ /** Whether the call sent a kill. */
330
653
  export interface KillResult {
331
654
  /** True exactly when a pane kill or a session kill was sent. */
332
655
  kill_sent: boolean;
333
656
  }
334
- /** Mirrors pkg/api.DecideParams (json tags). */
657
+ /** Parameters for deciding one permission request. */
335
658
  export interface DecideParams {
336
659
  /** Id of the Spawn whose open permission request is being decided. */
337
- claude_instance_id: string;
338
- /** UUIDv4 token identifying the specific permission request to decide. Required by the Go backend (ErrMissingRequestToken returned when absent); optional here for backward-compatible call shape. */
660
+ instance_id: string;
661
+ /** UUIDv4 token identifying the specific permission request to decide. Required (`ErrMissingRequestToken` when absent); optional here for backward-compatible call shape. */
339
662
  request_token?: string;
340
663
  /** Orchestrator verdict. */
341
664
  decision: "allow" | "deny";
342
- /** Optional free-text message surfaced to Claude on deny. */
665
+ /** Accepted but ignored; a deny records decision_reason operator regardless of this value. */
343
666
  reason?: string;
667
+ /**
668
+ * Optional bound on the whole call, in milliseconds from its start (no default). Required
669
+ * waits before recording, for the store or a request with no recorded settle instant, must
670
+ * fit within it; otherwise `ErrStoreBusy`, nothing recorded, so a retry is safe. With no time
671
+ * left, recording proceeds only if the store is free at once. Once
672
+ * the verdict is recorded the call never rejects with `ErrStoreBusy`: the wait for the relay
673
+ * hook's ack ends at the bound with `not_confirmed`. Pass at most your deadline minus 1 s.
674
+ * Negative: `ErrInvalidFlags`.
675
+ */
676
+ max_wait_ms?: number;
344
677
  }
345
- /** Mirrors pkg/api/decide.go::DecideResult (empty; reserved for future fields). */
346
- export interface DecideResult {
678
+ /**
679
+ * The request's delivery facts once the verdict is
680
+ * recorded, read after decide's wait of at most 1 s for the relay hook's ack. `delivery` is
681
+ * `"delivered"` or `"not_confirmed"` (poll `getPermission`, at the latest at `confirm_by`); a
682
+ * request whose relay hook fell back rejects with `ErrRelayFallenBack` instead.
683
+ */
684
+ export interface DecideResult extends RequestDelivery {
685
+ delivery: "delivered" | "not_confirmed";
347
686
  }
348
- /** Mirrors pkg/api.GetPermissionParams (json tags). */
687
+ /** Parameters for reading one permission request. */
349
688
  export interface GetPermissionParams {
350
689
  /** UUIDv4 token identifying the permission_requests row to fetch. Required; empty string rejected by the backend. */
351
690
  request_token: string;
352
691
  }
353
- /** Mirrors pkg/api/get_permission.go::GetPermissionResult */
354
- export interface GetPermissionResult {
692
+ /**
693
+ * One permission request with its delivery facts.
694
+ * A decided request can remain open until acknowledged. A recorded `decision` is not
695
+ * the outcome: `delivery` is.
696
+ */
697
+ export interface GetPermissionResult extends RequestDelivery {
355
698
  /** UUIDv4 token the row is keyed under (echoed back). */
356
699
  request_token: string;
357
700
  /** Autoincrement primary key of the permission_requests row. */
358
701
  request_id: number;
359
- /** Claude Code tool that triggered the permission request (e.g. "Bash", "Write"). */
702
+ /** Agent tool that triggered the permission request (e.g. "Bash", "Write"). */
360
703
  tool_name: string;
361
704
  /** Raw JSON string of the tool's input as stored in the DB. NOT a nested object — callers parse it themselves. */
362
705
  tool_input: string;
363
706
  /** RFC3339 timestamp when the permission request row was created. */
364
707
  requested_at: string;
365
- /** "allow" or "deny" once decided; null while the row is open (decision IS NULL in the DB). */
708
+ /**
709
+ * "allow" or "deny" once decided; null while undecided, and
710
+ * for a recordPaneAnswer claiming unknown.
711
+ */
366
712
  decision?: "allow" | "deny" | null;
367
- /** Canonical decision-reason string ("operator" | "timeout" | "find_missing") for deny rows; null for open rows and for allow rows. */
368
- decision_reason?: "operator" | "timeout" | "find_missing" | null;
369
- /** RFC3339 timestamp when the verdict was written; null while the row is open. */
713
+ /**
714
+ * Canonical decision-reason string: "operator" | "timeout" | "find_missing" | "ended" for deny
715
+ * rows ("find_missing" / "ended": still undecided when find-missing marked its spawn missing, or
716
+ * when its spawn ended or was resumed, and closed); "pane" | "pane_outside" | "tool_ran" for a
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.
722
+ */
723
+ decision_reason?: "operator" | "timeout" | "find_missing" | "ended" | "pane" | "pane_outside" | "tool_ran" | null;
724
+ /** RFC3339 timestamp when the verdict was written; null while undecided. */
370
725
  decided_at?: string | null;
371
726
  }
372
- /** Mirrors pkg/api.ResumeParams (json tags). */
727
+ /**
728
+ * Record that a fallen-back permission
729
+ * request was answered outside agent-director. It types nothing.
730
+ */
731
+ export interface RecordPaneAnswerParams {
732
+ /** Token of the permission request answered outside agent-director. */
733
+ request_token: string;
734
+ /**
735
+ * How it was answered, as the caller claims: "allow", "deny", or "unknown" when the answer was
736
+ * not seen (pass "unknown" unless it was). Stored, never checked; it never authorizes a Cursor
737
+ * ACP answer or supplies execution proof.
738
+ */
739
+ as: "allow" | "deny" | "unknown";
740
+ /** The `pane_sha256` of the readPane that showed it answered; compared byte for byte. */
741
+ expect_pane_sha256: string;
742
+ /** The `n_lines` of that readPane. Defaults to 25. */
743
+ n_lines?: number;
744
+ }
745
+ /** The request as recordPaneAnswer recorded it. */
746
+ export interface RecordPaneAnswerResult {
747
+ /** The request's token (echoed back). */
748
+ request_token: string;
749
+ /** Always "outside". */
750
+ pane_answer: "outside";
751
+ /** The claim recorded. */
752
+ pane_as: "allow" | "deny" | "unknown";
753
+ /** The claim when "allow" or "deny"; null for "unknown". */
754
+ decision: "allow" | "deny" | null;
755
+ /** Always "pane_outside". */
756
+ decision_reason: "pane_outside";
757
+ }
758
+ /**
759
+ * One other open request of the Spawn in
760
+ * {@link RelayFallenBackDetails}.
761
+ */
762
+ export interface OpenRequestFacts {
763
+ request_token: string;
764
+ tool_name: string;
765
+ requested_at: string;
766
+ delivery: Delivery;
767
+ hook_alive: boolean | null;
768
+ pane_answer: PaneAnswer;
769
+ }
770
+ /**
771
+ * ErrRelayFallenBack's errDetails (from decide, a plain
772
+ * sendKeys and pause): the request that fell back (its fields and delivery facts), the Spawn's
773
+ * state and its other open requests (null when they could not be read).
774
+ */
775
+ export interface RelayFallenBackDetails extends PermissionRequestInfo {
776
+ state: string;
777
+ open_requests: OpenRequestFacts[] | null;
778
+ }
779
+ /**
780
+ * ErrDialogMaybeOpen's errDetails (from a plain
781
+ * sendKeys without `expect_pane_sha256`, and from pause): the oldest request of the Spawn that
782
+ * the agent's hooks have not proven gone (its fields and delivery facts: how agent-director's records
783
+ * say it closed, `delivery` and `pane_answer`, and since when, `unproven_since`), the Spawn's
784
+ * state, and the Spawn's other requests not proven gone, oldest first.
785
+ */
786
+ export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
787
+ state: string;
788
+ unproven_requests: PermissionRequestInfo[];
789
+ }
790
+ /**
791
+ * ErrPaneAnswerInProgress's errDetails: another
792
+ * pane answer on the request is still being sent.
793
+ */
794
+ export interface PaneAnswerInProgressDetails {
795
+ request_token: string;
796
+ pane_as: string;
797
+ pane_intent_at: string;
798
+ /** true when its sender process runs; null when it cannot be checked. */
799
+ sender_alive: boolean | null;
800
+ /** When the sender cannot be checked, the time the intent stops counting; else null. */
801
+ not_before: string | null;
802
+ }
803
+ /**
804
+ * ErrClaimTooSoon's errDetails: retry recordPaneAnswer
805
+ * at `not_before` (null only while the request's relay hook is seen running).
806
+ */
807
+ export interface ClaimTooSoonDetails {
808
+ request_token: string;
809
+ hook_alive: boolean | null;
810
+ hook_gone_at: string | null;
811
+ not_before: string | null;
812
+ }
813
+ /**
814
+ * The errDetails of an ErrInternal from a pane answer
815
+ * (`sendKeys` with `request_token`) whose key was sent but whose record of it failed: the key
816
+ * reached the pane, so read it before anything else is sent.
817
+ */
818
+ export interface PaneKeySentDetails {
819
+ key_sent: true;
820
+ request_token: string;
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
+ }
828
+ /**
829
+ * ErrPaneChanged's errDetails. It never carries the pane's
830
+ * new hash: read the pane again before any retry.
831
+ */
832
+ export interface PaneChangedDetails {
833
+ n_lines: number;
834
+ request_token?: string;
835
+ }
836
+ /** Parameters for relaunching the latest session. */
373
837
  export interface ResumeParams {
374
- /** Id of the finished (ended or missing) row to resume. */
375
- claude_instance_id: string;
838
+ /** Id of the finished (ended or missing) row whose latest session is resumed. */
839
+ instance_id: string;
376
840
  }
377
841
  /**
378
- * Mirrors pkg/api/resume.go::ResumeResult. Resume moved the row to `pending`, keeping
379
- * its session id and history, until the agent reports in (Claude Code's SessionStart),
842
+ * Resume relaunches only the latest session
843
+ * of the row's recorded agent. Older sessions remain listed for inspection only.
844
+ * Stored session selectors and Claude print mode are removed from replay;
845
+ * cloud controls also lose their values when selector removal leaves no parsed
846
+ * environment/pool context. Other arguments and option-owned values survive.
847
+ * Claude inputs missing a recognized required value get literal filtering only;
848
+ * parsed-role preservation applies when all required values are present.
849
+ * Claude prompts move behind surviving options and --, and altered short clusters
850
+ * are re-encoded, only when needed to preserve their original parsed meaning;
851
+ * otherwise their order and spelling survive. Stored agent_args are unchanged.
852
+ * Resume moved the row to `pending`, keeping
853
+ * its session id and history, until the agent reports in (Cursor: verified first prompt),
380
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.
381
857
  */
382
858
  export interface ResumeResult {
383
859
  /** Same id that was passed in (resume preserves it). */
384
- claude_instance_id: string;
860
+ instance_id: string;
385
861
  /**
386
- * What the launch's folder-trust pre-trust did. `"ok"`: the folder-trust entry was
387
- * written. `"skipped"`: pre-trust was off for this launch because the row records that
388
- * the spawn that began its life turned it off (`no_pre_trust`); nothing was attempted.
389
- * `"failed"`: pre-trust was attempted and the entry was not written (the `.claude.json`
390
- * file is missing, or could not be read, parsed or written); the agent may stop at
391
- * Claude Code's folder-trust prompt. A pre-trust failure never fails the resume.
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
866
+ * (claude: the entry was written to `.claude.json`; codex: the launch carries the folder
867
+ * trust and the hook-trust bypass). `"skipped"`: pre-trust was off for this launch because the row records that
868
+ * the row's latest spawn turned it off (`no_pre_trust`); nothing was attempted.
869
+ * `"failed"`: pre-trust was attempted and the entry was not written (a claude agent: the
870
+ * `.claude.json` file is missing, or could not be read, parsed or written, or the row's
871
+ * `extra_env` sets `CLAUDE_CONFIG_DIR` to a path that is not absolute; a codex agent: the
872
+ * row's `extra_env` sets `CODEX_HOME` to a path that is not absolute, and the launch
873
+ * carries neither the folder trust nor the hook-trust bypass); the agent may stop at its
874
+ * folder-trust prompt. A pre-trust failure never fails the resume.
392
875
  */
393
876
  pre_trust: "ok" | "skipped" | "failed";
394
877
  }
@@ -401,11 +884,12 @@ export interface FindMissingParams {
401
884
  */
402
885
  timeout_ms?: number;
403
886
  }
404
- /** Mirrors pkg/api/find_missing.go::FindMissingResult */
887
+ /** Rows marked missing, ended or left unverified by the sweep. */
405
888
  export interface FindMissingResult {
406
889
  /**
407
- * Number of rows this sweep marked `missing` (the length of `ids`). Zero is
408
- * a normal result when nothing needed marking.
890
+ * Number of rows this sweep marked `missing` (the length of `ids`); a Codex
891
+ * row it moved to `ended` is not counted. Zero is a normal result when
892
+ * nothing needed marking.
409
893
  */
410
894
  count: number;
411
895
  /**
@@ -413,10 +897,13 @@ export interface FindMissingResult {
413
897
  * evidence: rows whose agent process (the SessionStart one or the recorded
414
898
  * pane's) is dead, and rows whose process could not be checked and tmux
415
899
  * found no session or pane of their current launch; a pending row only past
416
- * the pending grace period. A row whose guarded write found it changed or
417
- * gone, or failed, is in neither list. `missing` is the sweep's judgement
418
- * on the evidence available to it, not proof that the agent has exited.
419
- * Never null; [] when none.
900
+ * the pending grace period, and never while the spawn, reuse or resume that
901
+ * began its launch still runs. A row whose guarded write found it changed or
902
+ * gone, or failed, is in neither list, and so is a Codex row the sweep moved
903
+ * to `ended` (its agent process gone and an end report held) and a pending
904
+ * row the sweep notes `unreported` (its agent alive) or finds already noted
905
+ * so. `missing` is the sweep's judgement on the evidence available to it, not
906
+ * proof that the agent has exited. Never null; [] when none.
420
907
  */
421
908
  ids: string[];
422
909
  /** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
@@ -427,13 +914,15 @@ export interface FindMissingResult {
427
914
  * process could not be checked and which tmux did not mark, for example
428
915
  * because their own session is present, tmux could not tell or was
429
916
  * unavailable, or tmux was not called. Never a pending row inside the
430
- * pending grace period. A row whose guarded write found it changed or gone,
431
- * or failed, and a row whose note was cleared, is in neither list. Never
432
- * null; [] when none.
917
+ * pending grace period or while its launch runs. A row whose guarded write
918
+ * found it changed or gone, or failed, a row whose note was cleared, and a
919
+ * pending row noted `unreported` (its agent alive, no hook reported since
920
+ * its launch; find it by `liveness_note` in `get` or `list`) are in neither
921
+ * list. Never null; [] when none.
433
922
  */
434
923
  unverified_ids: string[];
435
924
  }
436
- /** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
925
+ /** The minimum finished-row age for cleanup. */
437
926
  export interface ExpireParams {
438
927
  /**
439
928
  * Duration override (e.g. "7d", "2h", "0d"). When omitted, the config
@@ -441,7 +930,7 @@ export interface ExpireParams {
441
930
  */
442
931
  older_than?: string;
443
932
  }
444
- /** Mirrors pkg/api/expire.go::ExpireResult */
933
+ /** Rows deleted or kept by the cleanup. */
445
934
  export interface ExpireResult {
446
935
  /**
447
936
  * Number of rows deleted (the length of `ids`): rows deleted after tmux
@@ -474,17 +963,33 @@ export interface ExpireResult {
474
963
  */
475
964
  kept_ids: string[];
476
965
  }
477
- /** Mirrors pkg/api.MakeTemplateParams (json tags). */
966
+ /** Parameters for writing a named template. */
478
967
  export interface MakeTemplateParams {
479
968
  /** Template filename (without extension). Must be filename-safe. Required. */
480
969
  name: string;
481
970
  /** Default working directory to bake in. */
482
971
  cwd?: string;
972
+ /**
973
+ * The agent the template belongs to: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor);
974
+ * case-sensitive, empty or absent means not given. Required when the template bakes in
975
+ * `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex or Cursor template cannot bake in
976
+ * `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). Any other value is refused
977
+ * with `ErrTemplateMalformed` (`ErrAgentInvalid` is spawn's per-call refusal). A spawn
978
+ * that names no agent takes it from the template.
979
+ */
980
+ agent?: string;
483
981
  /** Default relay mode: "on" | "off" | "" (inherit). */
484
982
  relay_mode?: string;
485
- /** Default claude argv. Per-call --claude-args replaces wholesale. */
486
- claude_args?: string[];
487
- /** Env-var overrides to bake in. */
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. */
984
+ agent_args?: string[];
985
+ /**
986
+ * Env-var overrides to bake in. A key spawn would refuse is refused here with
987
+ * `ErrReservedEnvKey` and nothing is written: `AGENT_DIRECTOR_*` keys, `HOME`
988
+ * (any value), and a key that is not a valid env-var name (empty, or
989
+ * containing `=` or a NUL character); the description says which. Set an absolute
990
+ * `CLAUDE_CONFIG_DIR` (Claude Code) or `CODEX_HOME` (Codex) to give the agent its
991
+ * own config folder.
992
+ */
488
993
  extra_env?: Record<string, string>;
489
994
  /** Label k=v entries to bake in. */
490
995
  label?: string[];
@@ -501,14 +1006,17 @@ export interface MakeTemplateParams {
501
1006
  */
502
1007
  overwrite?: boolean;
503
1008
  }
504
- /** Mirrors pkg/api/make_template.go::MakeTemplateResult */
1009
+ /** The template's saved path. */
505
1010
  export interface MakeTemplateResult {
506
1011
  /** Absolute path of the written template TOML file. */
507
1012
  path: string;
508
1013
  }
509
- /** Mirrors pkg/api.ListParams (json tags). */
1014
+ /** Filters for listing tracked agent rows. */
510
1015
  export interface ListParams {
511
- /** Filter by state (multiple values OR together). */
1016
+ /**
1017
+ * Filter by state (multiple values OR together). With `[state] settle_ms` set it matches the
1018
+ * settled state each row's `state` shows, before `limit` applies.
1019
+ */
512
1020
  state?: string[];
513
1021
  /** Filter by label k=v pairs (multiple entries AND together). */
514
1022
  label?: string[];
@@ -518,29 +1026,100 @@ export interface ListParams {
518
1026
  cwd?: string;
519
1027
  /** Filter by tmux session name exact match. */
520
1028
  tmux_session_name?: string;
521
- /** Cap result count. 0/omitted means no cap. */
1029
+ /** Cap result count. 0/omitted means no cap. A negative value is refused (ErrInvalidFlags). */
522
1030
  limit?: number;
523
1031
  }
524
- /** Mirrors pkg/api/list.go::ListResult */
1032
+ /** Matching tracked agent rows. */
525
1033
  export interface ListResult {
526
1034
  /** Matching Spawn rows. Empty array when none match. */
527
1035
  spawns: ListRow[];
528
1036
  }
529
- /** Mirrors pkg/api.PauseParams (json tags). */
1037
+ /** The id whose subagent records are requested. */
1038
+ export interface ListSubagentsParams {
1039
+ /** Id of the Spawn whose subagents to list. */
1040
+ instance_id: string;
1041
+ }
1042
+ /**
1043
+ * One subagent record. Every key is always present; a field with
1044
+ * no known value is `null`. Each time is an RFC3339 UTC string with millisecond precision
1045
+ * (trailing zeros dropped, no fraction on a whole second), exactly as the CLI prints it.
1046
+ */
1047
+ export interface SubagentRecord {
1048
+ /** The subagent's id, unique among the records shown for its row. */
1049
+ subagent_id: string;
1050
+ /** The id of the row (agent) the subagent belongs to. */
1051
+ instance_id: string;
1052
+ /** The session of the event that created the record; never changed after. */
1053
+ session_id: string | null;
1054
+ /** The subagent's type. */
1055
+ subagent_type: string | null;
1056
+ /** The short description the launching call gave the subagent; never the prompt text. */
1057
+ description: string | null;
1058
+ /** The model the subagent runs. */
1059
+ model: string | null;
1060
+ /**
1061
+ * What launched the subagent: `"agent"` (the row's own agent, so `parent_id` is the row's
1062
+ * instance_id) or `"subagent"` (another subagent, so `parent_id` is that subagent's id).
1063
+ */
1064
+ parent_type: "agent" | "subagent" | null;
1065
+ /** The instance_id or the parent subagent's id, as `parent_type` says. */
1066
+ parent_id: string | null;
1067
+ /** The id of the tool call that launched the subagent. */
1068
+ tool_use_id: string | null;
1069
+ /** `"background"` or `"foreground"`. */
1070
+ run_mode: "background" | "foreground" | null;
1071
+ /** When the subagent first started. */
1072
+ first_started_at: string | null;
1073
+ /** When the subagent's latest run started. */
1074
+ started_at: string | null;
1075
+ /** When the subagent last stopped; null if it never has (kept when it runs again). */
1076
+ stopped_at: string | null;
1077
+ /** When the subagent was judged lost; null unless it was. */
1078
+ lost_at: string | null;
1079
+ /**
1080
+ * `"running"` (started, neither stopped nor judged lost), `"stopped"` (its agent reported it
1081
+ * finished) or `"lost"` (judged gone without a stop report).
1082
+ */
1083
+ state: string;
1084
+ /**
1085
+ * Why the subagent is no longer running; null exactly while `state` is `"running"`:
1086
+ * `"stop_event"` (its agent reported it finished), `"absent_from_snapshot"` (a snapshot of the
1087
+ * agent's running background tasks did not list it) or `"agent_gone"` (its agent ended, went
1088
+ * missing or began a new launch).
1089
+ */
1090
+ close_reason: "stop_event" | "absent_from_snapshot" | "agent_gone" | null;
1091
+ }
1092
+ /** The current life's subagent records and tracking status. */
1093
+ export interface ListSubagentsResult {
1094
+ /**
1095
+ * Whether the row's launch registered subagent tracking: false for a row launched before
1096
+ * subagent tracking existed, which has no records, and false for a row whose launch
1097
+ * registers no subagent events; true for any other row.
1098
+ */
1099
+ tracked: boolean;
1100
+ /**
1101
+ * Every subagent record of the row's current life, across every launch of it, ordered by
1102
+ * `first_started_at` ascending (a null one last), then `subagent_id`. Empty array when it has none.
1103
+ */
1104
+ subagents: SubagentRecord[];
1105
+ }
1106
+ /** Parameters for asking a waiting agent to exit. */
530
1107
  export interface PauseParams {
531
1108
  /** Id of the Spawn to pause gracefully. */
532
- claude_instance_id: string;
1109
+ instance_id: string;
533
1110
  }
534
- /** Mirrors pkg/api/pause.go::PauseResult (empty; reserved for future fields). */
1111
+ /** Successful pause calls return an empty object. */
535
1112
  export interface PauseResult {
536
1113
  }
537
- /** Mirrors the `version` CLI verb (no user params; pkg/api.Client.Version takes none). */
1114
+ /** The version call takes no parameters. */
538
1115
  export interface VersionParams {
539
1116
  }
540
- /** Mirrors pkg/api/version.go::VersionResult */
1117
+ /** The installed npm package's version. */
541
1118
  export interface VersionResult {
542
- /** npm package version (e.g. "0.5.0"). Sourced from the installed agent-director package's package.json — not the CLI binary. See b.6o1. */
1119
+ /** npm package version (e.g. "0.5.0"). Sourced from the installed agent-director package's package.json — not the CLI binary. */
543
1120
  version: string;
544
1121
  /** CLI binary's full git SHA. "unknown" for unstamped builds. */
545
1122
  commit: string;
1123
+ /** Directory the CLI binary keeps agent-director's files in: "~/.config/agent-director", unexpanded, for every HOME. */
1124
+ config_dir: string;
546
1125
  }