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