agent-director 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,8 +29,8 @@ curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/ski
29
29
  `Client.create()` discovers the installed binary at construction time
30
30
  (either at `~/.agent-director/bin/agent-director` or anywhere on
31
31
  `$PATH`) and rejects if it cannot find one. Other supported install
32
- mechanisms — `install.sh --binary <path>` with a locally-staged
33
- artifact, or any drop-in copy onto `$PATH` — are documented in the
32
+ mechanisms — `install.sh --binary <path> --admin-binary <path>` with
33
+ locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
34
34
  [repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
35
35
 
36
36
  ## Supported platforms
@@ -120,7 +120,8 @@ for (const spawn of result.spawns) {
120
120
 
121
121
  ### sendKeys
122
122
 
123
- Send text to a Spawn's tmux pane.
123
+ Send text to the agent's own pane, then one Enter to submit it. An empty
124
+ `text` sends the Enter only, submitting what is already typed.
124
125
 
125
126
  ```sh
126
127
  agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
@@ -130,14 +131,16 @@ agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
130
131
  await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
131
132
  ```
132
133
 
133
- Pass `allow_pending: true` to also permit sending to a `pending` Spawn (state
134
- before `SessionStart` fires). The primary use case is dismissing interactive
135
- prompts that Claude Code renders before the session becomes interactive — for
136
- example the `--dangerously-load-development-channels` safety warning. `ended`
137
- and `missing` Spawns are still rejected regardless of the flag.
134
+ Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
135
+ reuse or resume) whose agent has not reported in yet, for example to dismiss a
136
+ prompt the agent shows before it reports in. Keys are delivered only to a
137
+ session started by the row's current launch. `ended` and `missing` rows are
138
+ still rejected. A `pending` row whose launch start or launch token is not recorded, or where
139
+ only a session an earlier launch left behind is found, gets
140
+ `ErrSpawnNotInteractive` and nothing is sent.
138
141
 
139
- Send an empty string with `allow_pending: true` to press Enter and dismiss the
140
- pre-`SessionStart` prompt:
142
+ Send an empty string with `allow_pending: true` to press Enter and dismiss such
143
+ a prompt:
141
144
 
142
145
  ```ts
143
146
  await client.sendKeys({
@@ -149,7 +152,7 @@ await client.sendKeys({
149
152
 
150
153
  ### readPane
151
154
 
152
- Read the last N lines of a Spawn's tmux pane (default 25).
155
+ Read the last N lines of the agent's own pane (default 25).
153
156
 
154
157
  ```sh
155
158
  agent-director read-pane --claude-instance-id <id> --n-lines 50
@@ -161,23 +164,37 @@ console.log(result.pane);
161
164
  ```
162
165
 
163
166
  `readPane` has no state guard — it works on `pending`, `ended`, and `missing`
164
- Spawns as well as live ones. The `allow_pending` flag is accepted for symmetry
167
+ rows as well as live ones. The `allow_pending` flag is accepted for symmetry
165
168
  with `sendKeys` but has no behavioral effect.
166
169
 
167
170
  ---
168
171
 
169
172
  ### kill
170
173
 
171
- Terminate a Spawn's tmux session.
174
+ End the agent of a live Spawn's current launch (`pending` included). `kill`
175
+ resolves only once the agent process is gone, and returns `{ kill_sent }`:
176
+ `true` when a kill was sent to the agent's pane or its session, `false` when
177
+ none was. On a finished Spawn (`ended` or `missing`) `kill` is a no-op that
178
+ resolves with `kill_sent: false`; that is not verification that the agent
179
+ exited. `kill` never changes the row's state: `find-missing` marks the row once
180
+ its agent process is gone.
172
181
 
173
182
  ```sh
174
183
  agent-director kill --claude-instance-id <id>
175
184
  ```
176
185
 
177
186
  ```ts
178
- await client.kill({ claude_instance_id: "<id>" });
187
+ const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
188
+ console.log(kill_sent);
179
189
  ```
180
190
 
191
+ Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
192
+ retry later), `ErrTmuxSessionConflict` (CONFLICT: a human must look),
193
+ `ErrTmuxNotAvailable` (ENVIRONMENT: an operator must fix the environment) and
194
+ `ErrSpawnNotFound`. None of these means the agent is dead. The caller must run
195
+ as the same user and in the same tmux environment as the agents. See the "tmux
196
+ transport" table under [Errors](#errors).
197
+
181
198
  ### makeTemplate
182
199
 
183
200
  Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
@@ -320,7 +337,7 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
320
337
 
321
338
  ### 4. Catalog-derived (CLI-side validation)
322
339
 
323
- These 37 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input or a verb's own state preconditions — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
340
+ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input or a verb's own state preconditions — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
324
341
 
325
342
  **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
326
343
 
@@ -338,14 +355,14 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
338
355
  | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
339
356
  | `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
340
357
  | `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
341
- | `ErrInstanceIdCollision` | The supplied `claude_instance_id` is already in use by a live spawn. |
358
+ | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `claude_instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
342
359
 
343
- **tmux session naming** (bad `--tmux-session-name` — programmer error):
360
+ **tmux session naming** (bad `tmux_session_name` — programmer error):
344
361
 
345
362
  | Error | When it fires |
346
363
  |---|---|
347
- | `ErrTmuxSessionNameEmpty` | `--tmux-session-name` was explicitly supplied but empty. |
348
- | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, an ASCII control character, or is invalid UTF-8. |
364
+ | `ErrTmuxSessionNameEmpty` | `tmux_session_name` was explicitly supplied but empty. |
365
+ | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, `$`, `\`, an ASCII control character, or is invalid UTF-8. |
349
366
  | `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
350
367
 
351
368
  **spawn state / lookup** (verb preconditions — mostly normal operational signals):
@@ -353,23 +370,28 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
353
370
  | Error | When it fires |
354
371
  |---|---|
355
372
  | `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
356
- | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected (`AllowPending=true` relaxes the `pending` rejection). |
373
+ | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
357
374
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
358
- | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry or `kill`. |
359
- | `ErrSpawnNotResumable` | The target spawn is not terminal (`ended`/`missing`), so it cannot be resumed. |
360
- | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — `delete` and spawn fresh. |
361
- | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — `delete` and spawn fresh. |
375
+ | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
376
+ | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Also returned when the row changed after `resume` examined it; nothing is written. |
377
+ | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
378
+ | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
362
379
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
363
- | `ErrProbeUnsupported` | The liveness probe has no implementation for the current platform (`find-missing`). |
380
+ | `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
364
381
 
365
- **tmux transport** (infrastructure failures at the tmux layer — runtime):
382
+ **tmux transport** (infrastructure failures at the tmux layer — runtime). Each name has a class: GONE (the row's session is not there), UNAVAILABLE (transient; retry later), CONFLICT (permanent until a human looks), ENVIRONMENT (an environment problem for an operator to fix) or LAUNCH FAILURE (the launch failed).
366
383
 
367
- | Error | When it fires |
368
- |---|---|
369
- | `ErrTmuxNotAvailable` | The `tmux` binary is not on PATH or refuses to execute. |
370
- | `ErrTmuxSessionCreate` | `tmux new-session` exited non-zero (name collision, invalid cwd, missing default-shell). |
371
- | `ErrTmuxSendKeys` | `tmux send-keys` exited non-zero (typically no live pane). |
372
- | `ErrTmuxCaptureFailed` | `tmux capture-pane` exited non-zero (session/pane vanished mid-call). |
384
+ | Error | Class | When it fires |
385
+ |---|---|---|
386
+ | `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
387
+ | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled; the new row stays `pending`. After tmux answers "duplicate session", `spawn` returns it only when the session holding the requested name was gone by the re-lookup; the new row is then ended (the error says if it was not), and the error names the instance id (a minted one included) and the retry: spawn that `claude_instance_id` again with `reuse_finished: true` once the name is free (if the row was not ended, once `get` shows it `ended` or `missing`), since a plain `spawn` of the id collides with its row. From `resume`, the session could not be created or labelled, or after "duplicate session" no session held the name when it was looked up again; the row is restored to `ended` or `missing` (the error says if it was not). A name found held is never this error. |
388
+ | `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
389
+ | `ErrTmuxSessionConflict` | CONFLICT (permanent until a human looks) | A tmux session conflict that needs a human. From `spawn` with an explicit `claude_instance_id` that has no row: a session of this store still labelled with that id is left over from an earlier life, or labels conflict; nothing is written. From a plain `spawn` whose requested tmux session name is already held (tmux answered "duplicate session"): the holder is a session left over from an earlier life of this id, another row's session, a session of another agent-director store, or one with no valid instance id, or labels conflict; the new row is ended (the error says if it was not) and the error names the blocking session. Another row's or another store's session is another agent and is never ended; the holding session is never read or typed into. From `resume` of a finished row, before anything is written and with no session touched: a session holds the row's session name (another row's session, a session of another agent-director store, or one with no valid instance id), a session is left over from an earlier life of this id, the row's own old session (or its agent process still running with no session) is past the stopping window and the starting-session bound, or labels conflict; the error names the blocking session. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). None of these means the agent is dead. From `kill` on a live row: the session found is not this launch's session (it carries the label of an earlier launch with this row's own id), or labels conflict; no kill was sent. From `readPane`, `sendKeys` and `pause`: the agent's pane was not found, a session an earlier launch left behind is there (for `readPane`, more than one; for `sendKeys`, on a live row), or labels conflict; nothing was read or sent. See "Operator actions" in the agent-director README. |
390
+ | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry `kill` later; never `delete` the row. |
391
+ | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
392
+ | `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
393
+
394
+ Only a GONE error means the row's session is not there (for `kill`, GONE is success); no other tmux error ever means the agent is dead.
373
395
 
374
396
  **relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
375
397
 
@@ -397,7 +419,7 @@ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`
397
419
 
398
420
  | Error | When it fires |
399
421
  |---|---|
400
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; not tied to any single verb handler. |
422
+ | `ErrInvalidFlags` | CLI flag parsing rejected the invocation, or `spawn` was given an explicit `claude_instance_id` containing an ASCII control character (0x00–0x1f or 0x7f). |
401
423
 
402
424
  ## Architecture
403
425
 
package/dist/errors.d.ts CHANGED
@@ -237,6 +237,15 @@ export declare class ErrTmuxSendKeys extends AgentDirectorError {
237
237
  /** Mirrors ErrTmuxCaptureFailed (package: tmux) */
238
238
  export declare class ErrTmuxCaptureFailed extends AgentDirectorError {
239
239
  }
240
+ /** Mirrors ErrTmuxUnresponsive (package: tmux) */
241
+ export declare class ErrTmuxUnresponsive extends AgentDirectorError {
242
+ }
243
+ /** Mirrors ErrTmuxSessionConflict (package: tmux) */
244
+ export declare class ErrTmuxSessionConflict extends AgentDirectorError {
245
+ }
246
+ /** Mirrors ErrTmuxKillFailed (package: tmux) */
247
+ export declare class ErrTmuxKillFailed extends AgentDirectorError {
248
+ }
240
249
  /** Mirrors ErrSpawnNotInteractive (package: api) */
241
250
  export declare class ErrSpawnNotInteractive extends AgentDirectorError {
242
251
  }
@@ -276,6 +285,9 @@ export declare class ErrNoSessionId extends AgentDirectorError {
276
285
  /** Mirrors ErrJsonlMissing (package: api) */
277
286
  export declare class ErrJsonlMissing extends AgentDirectorError {
278
287
  }
288
+ /** Mirrors ErrJsonlNeverWritten (package: api) */
289
+ export declare class ErrJsonlNeverWritten extends AgentDirectorError {
290
+ }
279
291
  /** Mirrors ErrRelayModeOff (package: api) */
280
292
  export declare class ErrRelayModeOff extends AgentDirectorError {
281
293
  }
package/dist/index.d.ts CHANGED
@@ -7,8 +7,8 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
8
  export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
9
9
  ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
10
- ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
11
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
12
12
  export type { ClientOptions, Logger } from "./types.js";
13
13
  export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
14
- export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
14
+ export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
package/dist/index.js CHANGED
@@ -28,12 +28,15 @@ __export(exports_errors, {
28
28
  errorFromEnvelope: () => errorFromEnvelope,
29
29
  TS_ONLY_ERROR_NAMES: () => TS_ONLY_ERROR_NAMES,
30
30
  ErrUnknownErrorName: () => ErrUnknownErrorName,
31
+ ErrTmuxUnresponsive: () => ErrTmuxUnresponsive,
31
32
  ErrTmuxSessionNameTooLong: () => ErrTmuxSessionNameTooLong,
32
33
  ErrTmuxSessionNameInvalid: () => ErrTmuxSessionNameInvalid,
33
34
  ErrTmuxSessionNameEmpty: () => ErrTmuxSessionNameEmpty,
34
35
  ErrTmuxSessionCreate: () => ErrTmuxSessionCreate,
36
+ ErrTmuxSessionConflict: () => ErrTmuxSessionConflict,
35
37
  ErrTmuxSendKeys: () => ErrTmuxSendKeys,
36
38
  ErrTmuxNotAvailable: () => ErrTmuxNotAvailable,
39
+ ErrTmuxKillFailed: () => ErrTmuxKillFailed,
37
40
  ErrTmuxCaptureFailed: () => ErrTmuxCaptureFailed,
38
41
  ErrTemplateNotFound: () => ErrTemplateNotFound,
39
42
  ErrTemplateNameUnsafe: () => ErrTemplateNameUnsafe,
@@ -60,6 +63,7 @@ __export(exports_errors, {
60
63
  ErrNoOpenPermissionRequest: () => ErrNoOpenPermissionRequest,
61
64
  ErrMissingRequestToken: () => ErrMissingRequestToken,
62
65
  ErrListInvalidLabel: () => ErrListInvalidLabel,
66
+ ErrJsonlNeverWritten: () => ErrJsonlNeverWritten,
63
67
  ErrJsonlMissing: () => ErrJsonlMissing,
64
68
  ErrInvalidFlags: () => ErrInvalidFlags,
65
69
  ErrInvalidDecision: () => ErrInvalidDecision,
@@ -287,6 +291,15 @@ class ErrTmuxSendKeys extends AgentDirectorError {
287
291
  class ErrTmuxCaptureFailed extends AgentDirectorError {
288
292
  }
289
293
 
294
+ class ErrTmuxUnresponsive extends AgentDirectorError {
295
+ }
296
+
297
+ class ErrTmuxSessionConflict extends AgentDirectorError {
298
+ }
299
+
300
+ class ErrTmuxKillFailed extends AgentDirectorError {
301
+ }
302
+
290
303
  class ErrSpawnNotInteractive extends AgentDirectorError {
291
304
  }
292
305
 
@@ -326,6 +339,9 @@ class ErrNoSessionId extends AgentDirectorError {
326
339
  class ErrJsonlMissing extends AgentDirectorError {
327
340
  }
328
341
 
342
+ class ErrJsonlNeverWritten extends AgentDirectorError {
343
+ }
344
+
329
345
  class ErrRelayModeOff extends AgentDirectorError {
330
346
  }
331
347
 
@@ -373,6 +389,9 @@ var ERROR_TABLE = {
373
389
  ErrTmuxSessionCreate,
374
390
  ErrTmuxSendKeys,
375
391
  ErrTmuxCaptureFailed,
392
+ ErrTmuxUnresponsive,
393
+ ErrTmuxSessionConflict,
394
+ ErrTmuxKillFailed,
376
395
  ErrSpawnNotInteractive,
377
396
  ErrSendKeysWhileRelayed,
378
397
  ErrSpawnNotPausable,
@@ -381,6 +400,7 @@ var ERROR_TABLE = {
381
400
  ErrSpawnNotResumable,
382
401
  ErrNoSessionId,
383
402
  ErrJsonlMissing,
403
+ ErrJsonlNeverWritten,
384
404
  ErrRelayModeOff,
385
405
  ErrRelayFallenBack,
386
406
  ErrInvalidDecision,
@@ -809,7 +829,7 @@ function expandTilde(p) {
809
829
  return "";
810
830
  if (p !== "~" && !p.startsWith("~/"))
811
831
  return p;
812
- const home = process.env["HOME"] ?? os.homedir();
832
+ const home = process.env["HOME"] || os.homedir();
813
833
  if (p === "~")
814
834
  return home;
815
835
  return home + p.slice(1);
@@ -859,8 +879,6 @@ function buildVerbFlags(verb, params) {
859
879
  return buildFindMissing();
860
880
  case "expire":
861
881
  return buildExpire(params);
862
- case "delete":
863
- return buildDelete(params);
864
882
  case "make-template":
865
883
  return buildMakeTemplate(params);
866
884
  case "list":
@@ -889,6 +907,8 @@ function buildSpawn(p) {
889
907
  f.push("--relay-mode", p.relay_mode);
890
908
  if (p.no_pre_trust === true)
891
909
  f.push("--no-pre-trust");
910
+ if (p.reuse_finished === true)
911
+ f.push("--reuse-finished");
892
912
  if (p.label) {
893
913
  for (const lv of p.label)
894
914
  f.push("--label", lv);
@@ -974,12 +994,6 @@ function buildExpire(p) {
974
994
  f.push("--older-than", p.older_than);
975
995
  return f;
976
996
  }
977
- function buildDelete(p) {
978
- const f = ["delete"];
979
- for (const id of p.claude_instance_id)
980
- f.push("--claude-instance-id", id);
981
- return f;
982
- }
983
997
  function buildMakeTemplate(p) {
984
998
  const f = ["make-template", "--name", p.name];
985
999
  if (p.cwd !== undefined)
@@ -1135,6 +1149,21 @@ var catalog_default = [
1135
1149
  package: "tmux",
1136
1150
  description: ""
1137
1151
  },
1152
+ {
1153
+ name: "ErrTmuxUnresponsive",
1154
+ package: "tmux",
1155
+ description: ""
1156
+ },
1157
+ {
1158
+ name: "ErrTmuxSessionConflict",
1159
+ package: "tmux",
1160
+ description: ""
1161
+ },
1162
+ {
1163
+ name: "ErrTmuxKillFailed",
1164
+ package: "tmux",
1165
+ description: ""
1166
+ },
1138
1167
  {
1139
1168
  name: "ErrSpawnNotInteractive",
1140
1169
  package: "api",
@@ -1200,6 +1229,11 @@ var catalog_default = [
1200
1229
  package: "api",
1201
1230
  description: ""
1202
1231
  },
1232
+ {
1233
+ name: "ErrJsonlNeverWritten",
1234
+ package: "api",
1235
+ description: ""
1236
+ },
1203
1237
  {
1204
1238
  name: "ErrRelayModeOff",
1205
1239
  package: "api",
@@ -1507,10 +1541,6 @@ class SubprocessClient {
1507
1541
  this.#assertOpen();
1508
1542
  return this.#enqueue("expire", params);
1509
1543
  }
1510
- async delete(params) {
1511
- this.#assertOpen();
1512
- return this.#enqueue("delete", params);
1513
- }
1514
1544
  async makeTemplate(params) {
1515
1545
  this.#assertOpen();
1516
1546
  return this.#enqueue("make-template", params);
@@ -1625,12 +1655,15 @@ export {
1625
1655
  errorFromEnvelope,
1626
1656
  MIN_BINARY_VERSION,
1627
1657
  ErrUnknownErrorName,
1658
+ ErrTmuxUnresponsive,
1628
1659
  ErrTmuxSessionNameTooLong,
1629
1660
  ErrTmuxSessionNameInvalid,
1630
1661
  ErrTmuxSessionNameEmpty,
1631
1662
  ErrTmuxSessionCreate,
1663
+ ErrTmuxSessionConflict,
1632
1664
  ErrTmuxSendKeys,
1633
1665
  ErrTmuxNotAvailable,
1666
+ ErrTmuxKillFailed,
1634
1667
  ErrTmuxCaptureFailed,
1635
1668
  ErrTemplateNotFound,
1636
1669
  ErrTemplateNameUnsafe,
@@ -1657,6 +1690,7 @@ export {
1657
1690
  ErrNoOpenPermissionRequest,
1658
1691
  ErrMissingRequestToken,
1659
1692
  ErrListInvalidLabel,
1693
+ ErrJsonlNeverWritten,
1660
1694
  ErrJsonlMissing,
1661
1695
  ErrInvalidFlags,
1662
1696
  ErrInvalidDecision,
@@ -12,11 +12,11 @@
12
12
  * - Mapping between camelCase method name and kebab CLI verb follows the
13
13
  * same mapping in src/internal/verbs.ts.
14
14
  * - Optional fields are omitted when undefined / falsy.
15
- * - Boolean flags (--no-pre-trust, --ansi, --overwrite) are only appended
16
- * when the field is explicitly true.
15
+ * - Boolean flags (--no-pre-trust, --reuse-finished, --ansi, --overwrite)
16
+ * are only appended when the field is explicitly true.
17
17
  * - Global flags (b.32k: --store-path, --home, --tmux-command) appear
18
18
  * BEFORE the verb token so the CLI's global-flag parser in
19
- * cmd/agent-director/global_flags.go strips them prior to verb dispatch.
19
+ * internal/clisetup/globalflags.go strips them prior to verb dispatch.
20
20
  *
21
21
  * Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
22
22
  *
@@ -46,8 +46,8 @@ export interface GlobalArgvOptions {
46
46
  * [cliPath, ...globalFlags, verbName, ...verbFlags]
47
47
  *
48
48
  * Global flags are inserted BEFORE the verb token because the CLI's
49
- * `parseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
50
- * (see cmd/agent-director/global_flags.go). b.32k.
49
+ * `ParseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
50
+ * (see internal/clisetup/globalflags.go). b.32k.
51
51
  *
52
52
  * @param cliPath The absolute path to the CLI binary (argv[0]).
53
53
  * @param verb The kebab-case verb name (must be a VerbName).
@@ -24,7 +24,7 @@
24
24
  * and the timeout was not the cause, ErrConsumerSignal is thrown.
25
25
  */
26
26
  import type { ClientOptions } from "../types.js";
27
- import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
27
+ import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
28
28
  /**
29
29
  * Internal construction parameters. Carries pre-resolved binaryPath +
30
30
  * binaryVersion so the runtime constructor doesn't run discovery itself.
@@ -111,14 +111,15 @@ export declare class SubprocessClient {
111
111
  decide(params: DecideParams): Promise<DecideResult>;
112
112
  /** getPermission — fetch a permission_requests row by request_token. */
113
113
  getPermission(params: GetPermissionParams): Promise<GetPermissionResult>;
114
- /** resume — restart a terminated Spawn. */
114
+ /** resume — relaunch a finished (ended or missing) row. */
115
115
  resume(params: ResumeParams): Promise<ResumeResult>;
116
- /** findMissing — reconcile Spawns whose tmux sessions have disappeared. */
116
+ /** findMissing — sweep live Spawns, marking each `missing` or leaving it unverified on process and tmux evidence; see FindMissingResult. */
117
117
  findMissing(params: FindMissingParams): Promise<FindMissingResult>;
118
- /** expire — remove terminal-state rows older than the retention window. */
118
+ /**
119
+ * expire — remove finished rows older than the retention window whose
120
+ * agent is gone, and report the rows it keeps.
121
+ */
119
122
  expire(params: ExpireParams): Promise<ExpireResult>;
120
- /** delete — hard-delete Spawn rows by id. */
121
- delete(params: DeleteParams): Promise<DeleteResult>;
122
123
  /** makeTemplate — save a reusable spawn preset. */
123
124
  makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
124
125
  /** list — query Spawns with optional filter params. */
@@ -6,14 +6,14 @@
6
6
  * pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
7
7
  * and excludes the three non-callable verbs (help, serve, hook).
8
8
  *
9
- * Currently 16 callable verbs: spawn, status, get, send-keys, read-pane,
10
- * kill, decide, get-permission, resume, find-missing, expire, delete,
9
+ * Currently 15 callable verbs: spawn, status, get, send-keys, read-pane,
10
+ * kill, decide, get-permission, resume, find-missing, expire,
11
11
  * make-template, list, pause, version.
12
12
  *
13
13
  * NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
14
14
  * intentionally excluded here. The .go source wins.
15
15
  */
16
16
  /** All callable verbs in their canonical kebab form (matches manifest). */
17
- export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "delete", "make-template", "list", "pause", "version"];
17
+ export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "resume", "find-missing", "expire", "make-template", "list", "pause", "version"];
18
18
  /** Union type of every callable verb name. */
19
19
  export type VerbName = (typeof VERBS)[number];
package/dist/types.d.ts CHANGED
@@ -18,9 +18,15 @@ export interface Logger {
18
18
  * does NOT provide a fallback; it forwards user input verbatim to keep the
19
19
  * CLI as the single source of truth for default resolution. See bug b.32k.
20
20
  *
21
- * Tilde expansion is handled TS-side by `src/internal/tilde.ts` before paths
22
- * are forwarded to the CLI subprocess, so the subprocess never receives a
23
- * leading `~`.
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.
26
+ *
27
+ * An empty `storePath`, `home` or `tmuxCommand` is forwarded as given (e.g.
28
+ * `--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.
24
30
  */
25
31
  export interface ClientOptions {
26
32
  /**
@@ -99,7 +105,12 @@ export interface ListRow {
99
105
  claude_instance_id: string;
100
106
  /** Parent Spawn id (omitted when launched from a plain shell). */
101
107
  parent_id?: string;
102
- /** Current lifecycle state. */
108
+ /**
109
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
110
+ * 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
112
+ * prompt. A resumed pending row keeps its session id and history.
113
+ */
103
114
  state: string;
104
115
  /** Canonicalized working directory. */
105
116
  cwd: string;
@@ -115,9 +126,24 @@ export interface ListRow {
115
126
  last_seen_at: string;
116
127
  /** Set when state moves to ended (omitted while live). */
117
128
  ended_at?: string | null;
118
- /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
129
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
130
+ launch_started_at?: string | null;
131
+ /**
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.
136
+ */
119
137
  liveness_unverified_since?: string | null;
120
- /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
138
+ /**
139
+ * Reason token of the latest sweep that left this live row unverified (its
140
+ * agent process could not be checked and tmux did not settle it), for
141
+ * example `process_not_seen_session_present`,
142
+ * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
143
+ * or `provenance_conflict`; overwritten when the reason changes. Cleared
144
+ * together with `liveness_unverified_since` when a sweep finds the agent
145
+ * process alive; omitted/null while not unverified.
146
+ */
121
147
  liveness_note?: string | null;
122
148
  }
123
149
  /** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
@@ -142,15 +168,40 @@ export interface SpawnParams {
142
168
  extra_env?: Record<string, string>;
143
169
  /** Pass-through argv to `claude` after --settings. */
144
170
  claude_args?: string[];
145
- /** Skip pre-writing workspace-trust into ~/.claude.json. Default false. */
171
+ /**
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
176
+ * `pre_trust: "skipped"`. Default false.
177
+ */
146
178
  no_pre_trust?: boolean;
147
179
  /** Explicit tmux session name. Auto-derived when absent. */
148
180
  tmux_session_name?: string;
181
+ /**
182
+ * Reuse an explicit `claude_instance_id` whose row is `ended` or `missing`;
183
+ * 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`.
186
+ */
187
+ reuse_finished?: boolean;
149
188
  }
150
- /** Mirrors pkg/api/spawn.go::SpawnResult */
189
+ /**
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`.
192
+ */
151
193
  export interface SpawnResult {
152
194
  /** The id the new Spawn is tracked under. */
153
195
  claude_instance_id: string;
196
+ /**
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
199
+ * `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.
203
+ */
204
+ pre_trust: "ok" | "skipped" | "failed";
154
205
  }
155
206
  /** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
156
207
  export interface StatusParams {
@@ -159,8 +210,16 @@ export interface StatusParams {
159
210
  }
160
211
  /** Mirrors pkg/api/status.go::StatusResult */
161
212
  export interface StatusResult {
162
- /** Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing). */
213
+ /**
214
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
215
+ * 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
217
+ * 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`.
219
+ */
163
220
  state: string;
221
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
222
+ launch_started_at?: string | null;
164
223
  }
165
224
  /** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
166
225
  export interface GetParams {
@@ -171,9 +230,18 @@ export interface GetParams {
171
230
  export interface GetResult {
172
231
  claude_instance_id: string;
173
232
  parent_id: string;
233
+ /**
234
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
235
+ * 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
237
+ * prompt. A resumed pending row keeps its session id and history; a non-empty
238
+ * `claude_session_id` tells it from a fresh one.
239
+ */
174
240
  state: string;
175
241
  cwd: string;
176
242
  tmux_session_name: string;
243
+ /** The tmux socket the row's launch uses; omitted for a row from before this release. */
244
+ tmux_socket?: string | null;
177
245
  claude_args: string[];
178
246
  relay_mode: string;
179
247
  jsonl_path: string;
@@ -185,9 +253,24 @@ export interface GetResult {
185
253
  last_seen_at: string;
186
254
  /** Set when state moves to ended; omitted while live. */
187
255
  ended_at?: string | null;
188
- /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
256
+ /** Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a pending row, omitted otherwise. */
257
+ launch_started_at?: string | null;
258
+ /**
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.
263
+ */
189
264
  liveness_unverified_since?: string | null;
190
- /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
265
+ /**
266
+ * Reason token of the latest sweep that left this live row unverified (its
267
+ * agent process could not be checked and tmux did not settle it), for
268
+ * example `process_not_seen_session_present`,
269
+ * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
270
+ * or `provenance_conflict`; overwritten when the reason changes. Cleared
271
+ * together with `liveness_unverified_since` when a sweep finds the agent
272
+ * process alive; omitted/null while not unverified.
273
+ */
191
274
  liveness_note?: string | null;
192
275
  /** Open permission request; present only when state=check_permission with an undecided row. */
193
276
  permission_request?: PermissionRequestInfo | null;
@@ -196,11 +279,17 @@ export interface GetResult {
196
279
  export interface SendKeysParams {
197
280
  /** Id of the Spawn whose pane will receive the text. */
198
281
  claude_instance_id: string;
199
- /** Text to deliver to the pane. CR bytes stripped; LF preserved; Enter appended. */
282
+ /**
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.
286
+ */
200
287
  text: string;
201
288
  /**
202
- * When true, also permit send-keys on a pending Spawn (pre-SessionStart
203
- * use case). ended/missing Spawns are still rejected even with this flag.
289
+ * When true, also allows a pending row: a launch (spawn, reuse or resume)
290
+ * whose agent has not reported in yet. Keys are delivered only to a
291
+ * session started by the row's current launch. ended and missing rows are
292
+ * still rejected.
204
293
  */
205
294
  allow_pending?: boolean;
206
295
  }
@@ -227,13 +316,15 @@ export interface ReadPaneResult {
227
316
  /** Captured pane text. */
228
317
  pane: string;
229
318
  }
230
- /** Mirrors pkg/api.KillParams (json tags). */
319
+ /** Mirrors pkg/api.KillParams. */
231
320
  export interface KillParams {
232
321
  /** Id of the Spawn to kill. */
233
322
  claude_instance_id: string;
234
323
  }
235
- /** Mirrors pkg/api/kill.go::KillResult (empty; reserved for future fields). */
324
+ /** Mirrors pkg/api/kill.go::KillResult (json tags). */
236
325
  export interface KillResult {
326
+ /** True exactly when a pane kill or a session kill was sent. */
327
+ kill_sent: boolean;
237
328
  }
238
329
  /** Mirrors pkg/api.DecideParams (json tags). */
239
330
  export interface DecideParams {
@@ -275,31 +366,66 @@ export interface GetPermissionResult {
275
366
  }
276
367
  /** Mirrors pkg/api.ResumeParams (json tags). */
277
368
  export interface ResumeParams {
278
- /** Id of the terminated Spawn to resurrect. */
369
+ /** Id of the finished (ended or missing) row to resume. */
279
370
  claude_instance_id: string;
280
371
  }
281
- /** Mirrors pkg/api/resume.go::ResumeResult */
372
+ /**
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),
375
+ * then `waiting`.
376
+ */
282
377
  export interface ResumeResult {
283
- /** Same id that was passed in (preserved across resurrection). */
378
+ /** Same id that was passed in (resume preserves it). */
284
379
  claude_instance_id: string;
380
+ /**
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.
387
+ */
388
+ pre_trust: "ok" | "skipped" | "failed";
285
389
  }
286
- /** Mirrors the `find-missing` CLI verb's --timeout flag (pkg/api.Client.FindMissing ctx deadline). */
390
+ /** Params for the `find-missing` verb, which takes no CLI flags. */
287
391
  export interface FindMissingParams {
288
- /** Optional deadline for the OS probe sweep (milliseconds). 0/omitted = no deadline. */
392
+ /**
393
+ * Accepted but not sent: the `find-missing` CLI verb takes no flags, so
394
+ * this value has no effect. The call is bounded by the Client's
395
+ * `callTimeoutMs` like every other verb.
396
+ */
289
397
  timeout_ms?: number;
290
398
  }
291
399
  /** Mirrors pkg/api/find_missing.go::FindMissingResult */
292
400
  export interface FindMissingResult {
293
- /** Number of rows transitioned to missing on this sweep. */
401
+ /**
402
+ * Number of rows this sweep marked `missing` (the length of `ids`). Zero is
403
+ * a normal result when nothing needed marking.
404
+ */
294
405
  count: number;
295
- /** Sorted ids of rows transitioned to missing. */
296
- ids: string[];
297
406
  /**
298
- * Number of live rows left untouched this sweep because their liveness
299
- * could not be established (an unknown verdict, e.g. a permission wall).
407
+ * Sorted ids of rows this sweep marked `missing`, on process or tmux
408
+ * evidence: rows whose agent process (the SessionStart one or the recorded
409
+ * pane's) is dead, and rows whose process could not be checked and tmux
410
+ * 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.
300
415
  */
416
+ ids: string[];
417
+ /** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
301
418
  unverified: number;
302
- /** Sorted ids of rows left untouched as unverified. Non-nil; [] when none. */
419
+ /**
420
+ * Sorted ids of live rows this sweep left unverified with a liveness note,
421
+ * whether it wrote the note or found it already current: rows whose agent
422
+ * process could not be checked and which tmux did not mark, for example
423
+ * because their own session is present, tmux could not tell or was
424
+ * 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.
428
+ */
303
429
  unverified_ids: string[];
304
430
  }
305
431
  /** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
@@ -312,20 +438,36 @@ export interface ExpireParams {
312
438
  }
313
439
  /** Mirrors pkg/api/expire.go::ExpireResult */
314
440
  export interface ExpireResult {
315
- /** Number of terminal rows removed. */
441
+ /**
442
+ * Number of rows deleted (the length of `ids`): rows deleted after tmux
443
+ * showed no session of the agent (Gone) and its recorded process was not
444
+ * seen running. Zero is a legitimate result when no row was deleted.
445
+ */
316
446
  count: number;
317
- /** Sorted ids of rows removed. */
447
+ /**
448
+ * Sorted ids of the rows deleted after tmux showed no session of the agent
449
+ * (Gone) and its recorded process was not seen running, each only while
450
+ * the row was unchanged since expire examined it. Never null; `[]` when
451
+ * none.
452
+ */
318
453
  ids: string[];
319
- }
320
- /** Mirrors the `delete` CLI verb's --claude-instance-id flag(s) (pkg/api.Client.Delete arg). */
321
- export interface DeleteParams {
322
- /** Id(s) to delete. */
323
- claude_instance_id: string[];
324
- }
325
- /** Mirrors pkg/api/delete.go::DeleteResult */
326
- export interface DeleteResult {
327
- /** Per-id outcome: "ok" on success, err_name on failure. */
328
- results: Record<string, string>;
454
+ /**
455
+ * Number of selected rows kept rather than deleted (the length of
456
+ * `kept_ids`), for example because the agent's process or a session of the
457
+ * agent (its own, or a leftover of an earlier launch) may still run, tmux
458
+ * could not be checked or answered from a different server, the run's tmux
459
+ * time budget (`sweep_budget_seconds`) was spent, or the row changed after
460
+ * it was examined.
461
+ */
462
+ kept: number;
463
+ /**
464
+ * Sorted ids of the selected rows kept rather than deleted, each reported
465
+ * with its reason in the trail (`ad.expire.kept`). tmux problems and a
466
+ * failed delete of one row never fail the run: the row is kept. A failed
467
+ * read of the selected rows fails the run. A row another caller removed
468
+ * first is in neither list. Never null; `[]` when none.
469
+ */
470
+ kept_ids: string[];
329
471
  }
330
472
  /** Mirrors pkg/api.MakeTemplateParams (json tags). */
331
473
  export interface MakeTemplateParams {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],