agent-director 0.17.7 → 0.18.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
@@ -25,7 +25,7 @@ its version must meet the client floor.
25
25
  ## Supported platforms
26
26
 
27
27
  - `linux/x64` (Linux on x86_64)
28
- - `darwin/arm64` (Apple Silicon Mac)
28
+ - `darwin/arm64` (Apple Silicon Mac, macOS 13 or later)
29
29
 
30
30
  Package installation may also succeed on `linux/arm64` and `darwin/x64`;
31
31
  those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
@@ -146,6 +146,10 @@ handling are in the [caller contract](../../docs/caller-contract.md#cursor-opera
146
146
 
147
147
  Get the current lifecycle state of a Spawn.
148
148
 
149
+ `status`, `get`, `list` and `sweep` (also `findMissing`) share
150
+ [bounded recovery](../../docs/caller-contract.md#bounded-recovery-on-state-reads).
151
+ Single-row reads check only that row; read success does not confirm every write.
152
+
149
153
  ```ts
150
154
  const result = await client.status({ instance_id: "<id>" });
151
155
  console.log(result.state);
@@ -157,6 +161,17 @@ console.log(result.state);
157
161
  aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
158
162
  defines reporting limits.
159
163
 
164
+ They also carry `process_liveness: ProcessLiveness` (`"alive" | "exited" |
165
+ "unknown"`) and `confirmations: Confirmations`, with exactly `state`,
166
+ `process_liveness` and `displayed_state`. Each is a `Confirmation`: a non-null
167
+ `status` (`ConfirmationStatus`) and the nullable `confirmed_at`, `source`
168
+ (`ConfirmationSource`), `checked_at` and `reason` (`ConfirmationReason`), all
169
+ five always present. The [caller contract](../../docs/caller-contract.md#confirmations)
170
+ defines the values and when each is `null`. `confirmations.displayed_state`
171
+ describes the returned display, including an omitted `displayed_state` or a
172
+ retained display whose exit is settling. Cursor's record is
173
+ `unknown`/`unsupported`.
174
+
160
175
  `state` is always the lifecycle state. While a row shows a
161
176
  Displayed State, `StatusResult`, `GetResult` and each `ListRow` carry it in
162
177
  `displayed_state` (`"idle_screen"`; `"needs_intelligence"` is defined, but
@@ -195,7 +210,10 @@ for (const spawn of result.spawns) {
195
210
  Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
196
211
  A `state` filter keeps a row whose `state` or `displayed_state` is one of its
197
212
  values, before any `limit`, so `["working"]` keeps a working row that shows
198
- `"idle_screen"`.
213
+ `"idle_screen"`. Filters and limit select stored IDs before recovery checks.
214
+ The result keeps those IDs even if refreshed values no longer match; it does
215
+ not refill slots or add newly matching rows. Recovery and family freshness
216
+ follow the [caller contract](../../docs/caller-contract.md#bounded-recovery-on-state-reads).
199
217
 
200
218
  ### listSubagents
201
219
 
@@ -221,7 +239,7 @@ or omitted `text` sends the Enter only, submitting what is already typed.
221
239
  `no_enter: true` types the text without the Enter, and `key` sends one key
222
240
  alone (`"Escape"`, `"Enter"`, `"Up"`, `"Down"`, `"Tab"`, or one character),
223
241
  never followed by Enter. With `expect_pane_sha256` (the `pane_sha256` of
224
- the `readPane` you looked at, with its `n_lines`), nothing is sent if the
242
+ the plain `readPane` you looked at, with its `n_lines`), nothing is sent if the
225
243
  pane changed since (`ErrPaneChanged`); on a relayed Spawn a match also
226
244
  passes the API's dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
227
245
  the pane" below). Pass it only for a pane a person or an LLM judged, never
@@ -250,7 +268,11 @@ Supported launches, fallback readiness and input restrictions, omitted-ID
250
268
  behavior, structured outcomes and recovery are in
251
269
  [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
252
270
  Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
253
- cancel submission. Cursor sends with Enter can return `ErrSubmissionUnconfirmed`
271
+ cancel submission.
272
+ After confirmed native delivery, a cleanup `ErrInternal` retains the submitted
273
+ receipt through `AgentDirectorError.errDetails`; follow the caller contract's
274
+ cleanup and no-replay rules. No additional typed proof fields are exposed.
275
+ Cursor sends with Enter can return `ErrSubmissionUnconfirmed`
254
276
  with `outcome: "gateway_refused"`; see
255
277
  [Cursor input outcomes](../../docs/caller-contract.md#cursor-input-outcomes).
256
278
 
@@ -299,7 +321,8 @@ console.log(result.pane, result.pane_sha256);
299
321
 
300
322
  `pane_sha256` is the SHA-256 of exactly the bytes of `pane`; pass it back as
301
323
  `sendKeys`' or `recordPaneAnswer`'s `expect_pane_sha256`, with the same
302
- `n_lines`, when you act on what this pane shows.
324
+ `n_lines`, when you act on what this pane shows. Use the default ANSI-stripped
325
+ read for this guard; the hash of an `ansi: true` read never matches.
303
326
 
304
327
  `readPane` has no state guard — it works on `pending`, `ended`, and `missing`
305
328
  rows as well as live ones. The `allow_pending` flag is accepted for symmetry
@@ -314,8 +337,8 @@ resolves only once the agent process is gone, and returns `{ kill_sent }`:
314
337
  `true` when a kill was sent to the agent's pane or its session, `false` when
315
338
  none was. On a finished Spawn (`ended` or `missing`) `kill` is a no-op that
316
339
  resolves with `kill_sent: false`; that is not verification that the agent
317
- exited. `kill` never changes the row's state: `find-missing` marks the row once
318
- its agent process is gone.
340
+ exited. `kill` never changes the row's state: a state read or `sweep` marks it
341
+ once its agent process is gone.
319
342
 
320
343
  ```ts
321
344
  const { kill_sent } = await client.kill({ instance_id: "<id>" });
@@ -328,6 +351,21 @@ retry later), `ErrTmuxSessionConflict` (CONFLICT),
328
351
  `ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
329
352
  for the live-row sequence and finished-row limits.
330
353
 
354
+ ### sweep
355
+
356
+ `client.sweep()` returns `Promise<SweepResult>` for one bounded all-agent pass.
357
+ `checks: SweepCheck[]` carries each selected identity's values, three
358
+ confirmation records and independent `completion`/`reason`. Legacy counters
359
+ remain in the same result. See [Sweep results](../../docs/caller-contract.md#sweep-results)
360
+ for membership, coverage and failure handling.
361
+
362
+ `findMissing()` remains supported and invokes the CLI's `find-missing` alias;
363
+ `sweep()` invokes `sweep`. `SweepParams`, `SweepResult` and `SweepCheck` are
364
+ exported alongside the retained `FindMissingParams` and `FindMissingResult`
365
+ types. Both parameter types accept `timeout_ms` but ignore it: neither command
366
+ receives that flag. `callTimeoutMs` bounds the transport call; timeout proves
367
+ neither rollback nor completion and need not return partial checks.
368
+
331
369
  ### pause
332
370
 
333
371
  Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
@@ -409,8 +447,8 @@ timing and audit limits are owned by the
409
447
  recording no verdict, with `ErrRelayFallenBack` when the request's relay
410
448
  settled without acknowledgement, with `ErrStoreBusy` when `max_wait_ms`
411
449
  ran out before the verdict was recorded, and with
412
- `ErrNoOpenPermissionRequest` when no open request has that token or the
413
- request is closed. Pane answers, retries and closed-request handling are
450
+ `ErrNoOpenPermissionRequest` when no eligible request has that token,
451
+ including a closed, proven-gone or obsolete request. Pane answers, retries and closed-request handling are
414
452
  in the [caller contract](../../docs/caller-contract.md#permission-relay). The
415
453
  `permission_requests` of `get` and of each `list` row carry the same
416
454
  delivery fields, `pane_answer` and `pane_as` included, for requests that
@@ -432,13 +470,14 @@ do not know, read the recorded verdict from `decision` (`null` for a
432
470
  `"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
433
471
  `pane_answer`; never read a reason as a verdict.
434
472
 
435
- `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Claude's
436
- tool ran or Cursor supplied validated exact matching invocation proof under
473
+ `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, Cursor
474
+ supplied validated exact matching invocation proof under
437
475
  [Cursor permissions](../../docs/permissions.md#cursor-spawns), including a failed
438
476
  MCP invocation that proves dialog closure without inferring execution or changing
439
477
  decision, delivery or pane-answer fields;
440
478
  `"turn_end"`, an eligible main request's turn ended under the age and identity
441
- guards, or a Cursor turn ended with the request still unanswered; or
479
+ guards, a Claude subagent's turn ended after its request (its
480
+ `SubagentStop`), or a Cursor turn ended with the request still unanswered; or
442
481
  `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
443
482
  dialog was proven gone; `"delivered"` and a pane answer are
444
483
  agent-director's own records, not proof. `get`'s `unproven_requests` lists
@@ -544,6 +583,14 @@ verbatim — no leading-`v` stripping, no normalization. Consumers
544
583
  comparing two real versions should use a standard semver library;
545
584
  agent-director does not export a comparator.
546
585
 
586
+ The floor is a construction check, not feature negotiation: an older CLI
587
+ that meets it can lack `sweep` (an unknown-verb error) and return
588
+ `status`/`get`/`list`/`findMissing` results without `process_liveness`,
589
+ `confirmations` or `checks`, which the client does not synthesize. Those
590
+ need the CLI release matching this package ([install guide](../../docs/install.md)).
591
+ `client.binaryVersion` is the installed CLI's version; `client.version()`
592
+ reports this package's version.
593
+
547
594
  **Bash read pattern (for install scripts and non-JS consumers):**
548
595
 
549
596
  ```sh
@@ -682,7 +729,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
682
729
  | `ErrNoSessionId` | The spawn has no `session_id`, so there is nothing to resume. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
683
730
  | `ErrJsonlMissing` | The current session's transcript is unavailable. Cursor requires its protected gateway transcript; native session availability is decided later during load. Older sessions are never tried. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
684
731
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
685
- | `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. |
732
+ | `ErrProbeUnsupported` | No verb returns it. The name stays catalogued (and listed for `sweep` and `find-missing`) so the client still maps it. |
686
733
 
687
734
  **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).
688
735
 
@@ -711,9 +758,9 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
711
758
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
712
759
  | `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
713
760
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
714
- | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request relay acknowledged its recorded verdict, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (for a request with a settle instant, `"delivered"` requires durable relay acknowledgement; requests recorded by an older binary retain the [legacy delivery rules](../../docs/permissions.md#requests-recorded-by-an-older-binary), including derived delivery after expiry even when closed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
715
- | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the recorded decision and acknowledgement prevent a second API answer. Acknowledgement does not establish agent receipt or dialog closure; see [Permission relay](../../docs/caller-contract.md#permission-relay). It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay acknowledged, or one already closed at the pane, throws it too. |
716
- | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). |
761
+ | `ErrNoOpenPermissionRequest` | No eligible permission request matches the `(instance_id, request_token)` pair, including a closed, proven-gone or obsolete request. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or shared recovery or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when shared recovery marked it `missing`) before the request relay acknowledged its recorded verdict, the missing mark's own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (for a request with a settle instant, `"delivered"` requires durable relay acknowledgement; requests recorded by an older binary retain the [legacy delivery rules](../../docs/permissions.md#requests-recorded-by-an-older-binary), including derived delivery after expiry even when closed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
762
+ | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the recorded decision and acknowledgement prevent a second API answer. Acknowledgement does not establish agent receipt or dialog closure; see [Permission relay](../../docs/caller-contract.md#permission-relay). It also includes a request shared recovery denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay acknowledged, or one already closed at the pane, throws it too. |
763
+ | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and its precommit budget ran out, including acquisition or SQL work. It does not establish another process held the store. Once the verdict is confirmed committed, `decide` never throws it: a bound reached while it waits for confirmation resolves with `delivery` `"not_confirmed"`. An unconfirmed commit is an internal error instead. Without `max_wait_ms`, `decide` never throws `ErrStoreBusy`. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout. Recovery and zero-wait semantics are in the [caller contract](../../docs/caller-contract.md#permission-relay). `status`, `get`, `list`, `sweep` and `findMissing` throw it when a bounded store read does not finish in time; see [Bounded recovery on state reads](../../docs/caller-contract.md#bounded-recovery-on-state-reads). |
717
764
  | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
718
765
  | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
719
766
 
@@ -738,7 +785,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
738
785
  |---|---|
739
786
  | `ErrConfigMalformed` | The CLI refused its config file, `~/.config/agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. See the caller contract for handling. |
740
787
  | `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. With `createIfMissing: false` it includes a store that does not exist (`database not initialized`); nothing was created. It says nothing about any agent. |
741
- | `ErrSchemaMismatch` | The CLI refused to open its store: the store was written by a newer agent-director than the binary (`found user_version=<N>, want <M>`), or it has no valid store id. The description says which. Nothing was written, and every call that opens the store fails this way until an operator acts: a newer store needs the agent-director release that wrote it. See Operator actions for recovery. It says nothing about any agent. |
788
+ | `ErrSchemaMismatch` | The CLI refused to open its store: its schema is newer than the binary (`found user_version=<N>, want <M>`), its store id is invalid, or its current-schema input authority is incompatible or uncommitted. The description says which. Nothing was written; an operator must act before store-opening calls can run. A newer store needs the release that wrote it. See [Operator actions](../../docs/operator-actions.md#upgrading-the-native-input-journal) for input-authority recovery. This says nothing about any agent. |
742
789
  | `ErrSchemaMigrationRequired` | The CLI refused to open its store: the store is older than the binary and must be migrated first. The description gives both schema versions. Nothing was written, and every call that opens the store fails this way until an administrator migrates the store; no call through this client can. See the caller contract for handling. It says nothing about any agent. |
743
790
  | `ErrOldLayout` | The CLI refused to open its store: it was about to open the default store (no `storePath`, and no `[store] db_path` in its config file), no store exists in `~/.config/agent-director`, and the old directory exists. Nothing was created, and every call that opens the store fails this way until an operator runs this release's `install.sh`. See the caller contract for handling. It says nothing about any agent. |
744
791
 
package/dist/errors.d.ts CHANGED
@@ -221,6 +221,15 @@ export declare class ErrSpawnDeniedFlag extends AgentDirectorError {
221
221
  /** Mirrors ErrReservedEnvKey (package: spawn) */
222
222
  export declare class ErrReservedEnvKey extends AgentDirectorError {
223
223
  }
224
+ /** The requested experimental agent is disabled. */
225
+ export declare class ErrExperimentalAgentDisabled extends AgentDirectorError {
226
+ }
227
+ /** The pane-only agent does not support the requested capability. */
228
+ export declare class ErrAgentCapabilityUnsupported extends AgentDirectorError {
229
+ }
230
+ /** The pane-only launch has no explicit model. */
231
+ export declare class ErrModelMissing extends AgentDirectorError {
232
+ }
224
233
  /** Mirrors ErrAgentMissing (package: spawn) */
225
234
  export declare class ErrAgentMissing extends AgentDirectorError {
226
235
  }
@@ -363,9 +372,11 @@ export declare class ErrClaimTooSoon extends AgentDirectorError {
363
372
  }
364
373
  /**
365
374
  * Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
366
- * a `pause`, while a permission request of the Spawn is not proven gone by the agent's hooks
367
- * (its tool's PostToolUse, the main agent's end of turn after it, or, on a non-Cursor Spawn, the
368
- * agent's end), whatever agent-director's records say of it; its dialog may still be on the pane.
375
+ * a `pause`, while a permission request of the Spawn is not proven gone (on a Cursor row, the
376
+ * gateway's validated proof that its tool ran; the end of the asking agent's turn: the main
377
+ * agent's for a request with no agent_id, and on a Claude row the subagent's SubagentStop for one
378
+ * with an agent_id; or, on a non-Cursor Spawn, the agent's end), whatever agent-director's
379
+ * records say of it; its dialog may still be on the pane.
369
380
  * A Cursor request of an earlier launch of the Spawn does not count. Nothing was sent.
370
381
  * `errDetails` is a `DialogMaybeOpenDetails`. A plain `sendKeys` whose `expect_pane_sha256`
371
382
  * matches the pane is not rejected with it; pass that hash only from a pane a person or LLM
@@ -391,7 +402,8 @@ export declare class ErrAmbiguousRequest extends AgentDirectorError {
391
402
  /**
392
403
  * Mirrors ErrStoreBusy (package: store): decide's `max_wait_ms` bound was reached before its
393
404
  * verdict was recorded (another process held the store's write lock). Nothing was recorded, so
394
- * the call can be retried.
405
+ * the call can be retried. These statements apply to decide; other verbs that list it say in
406
+ * their own Errors when they return it.
395
407
  */
396
408
  export declare class ErrStoreBusy extends AgentDirectorError {
397
409
  }
package/dist/index.d.ts CHANGED
@@ -7,9 +7,9 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
8
  export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
9
9
  ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
10
- ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrExperimentalAgentDisabled, ErrAgentCapabilityUnsupported, ErrModelMissing, ErrAgentMissing, ErrAgentInvalid, ErrAgentArgsMismatch, ErrPermissionsUnsupported, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSubmissionUnconfirmed, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrTemplateAgentMissing, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrPaneChanged, ErrPaneAnswerInProgress, ErrClaimTooSoon, ErrDialogMaybeOpen, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrStoreBusy, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, ErrSchemaMismatch, ErrSchemaMigrationRequired, ErrOldLayout, ErrUnknownVerb, ErrJSONMarshal, ErrTrailWrite, ErrInternal, } from "./errors.js";
11
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
12
12
  export type { ClientOptions, Logger } from "./types.js";
13
- export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, IdleScreenAvailability, } from "./types.js";
13
+ export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, IdleScreenAvailability, ProcessLiveness, Confirmation, Confirmations, ConfirmationStatus, ConfirmationSource, ConfirmationReason, } from "./types.js";
14
14
  export type { PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
- export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
15
+ export type { SpawnParams, SpawnResult, StatusParams, StatusResult, ContextReading, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, SweepCheck, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, SubagentRecord, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
package/dist/index.js CHANGED
@@ -73,6 +73,7 @@ __export(exports_errors, {
73
73
  ErrOldLayout: () => ErrOldLayout,
74
74
  ErrNoSessionId: () => ErrNoSessionId,
75
75
  ErrNoOpenPermissionRequest: () => ErrNoOpenPermissionRequest,
76
+ ErrModelMissing: () => ErrModelMissing,
76
77
  ErrMissingRequestToken: () => ErrMissingRequestToken,
77
78
  ErrListInvalidLabel: () => ErrListInvalidLabel,
78
79
  ErrJsonlNeverWritten: () => ErrJsonlNeverWritten,
@@ -82,6 +83,7 @@ __export(exports_errors, {
82
83
  ErrInvalidDecision: () => ErrInvalidDecision,
83
84
  ErrInternal: () => ErrInternal,
84
85
  ErrInstanceIdCollision: () => ErrInstanceIdCollision,
86
+ ErrExperimentalAgentDisabled: () => ErrExperimentalAgentDisabled,
85
87
  ErrDialogMaybeOpen: () => ErrDialogMaybeOpen,
86
88
  ErrCwdNotFound: () => ErrCwdNotFound,
87
89
  ErrCwdNotAPath: () => ErrCwdNotAPath,
@@ -98,6 +100,7 @@ __export(exports_errors, {
98
100
  ErrAlreadyDecided: () => ErrAlreadyDecided,
99
101
  ErrAgentMissing: () => ErrAgentMissing,
100
102
  ErrAgentInvalid: () => ErrAgentInvalid,
103
+ ErrAgentCapabilityUnsupported: () => ErrAgentCapabilityUnsupported,
101
104
  ErrAgentArgsMismatch: () => ErrAgentArgsMismatch,
102
105
  AgentDirectorError: () => AgentDirectorError
103
106
  });
@@ -286,6 +289,15 @@ class ErrSpawnDeniedFlag extends AgentDirectorError {
286
289
  class ErrReservedEnvKey extends AgentDirectorError {
287
290
  }
288
291
 
292
+ class ErrExperimentalAgentDisabled extends AgentDirectorError {
293
+ }
294
+
295
+ class ErrAgentCapabilityUnsupported extends AgentDirectorError {
296
+ }
297
+
298
+ class ErrModelMissing extends AgentDirectorError {
299
+ }
300
+
289
301
  class ErrAgentMissing extends AgentDirectorError {
290
302
  }
291
303
 
@@ -458,6 +470,9 @@ var ERROR_TABLE = {
458
470
  ErrRelayModeInvalid,
459
471
  ErrSpawnDeniedFlag,
460
472
  ErrReservedEnvKey,
473
+ ErrExperimentalAgentDisabled,
474
+ ErrAgentCapabilityUnsupported,
475
+ ErrModelMissing,
461
476
  ErrAgentMissing,
462
477
  ErrAgentInvalid,
463
478
  ErrAgentArgsMismatch,
@@ -982,8 +997,9 @@ function buildVerbFlags(verb, params) {
982
997
  return buildRecordPaneAnswer(params);
983
998
  case "resume":
984
999
  return buildResume(params);
1000
+ case "sweep":
985
1001
  case "find-missing":
986
- return buildFindMissing();
1002
+ return [verb];
987
1003
  case "expire":
988
1004
  return buildExpire(params);
989
1005
  case "make-template":
@@ -1150,9 +1166,6 @@ function buildRecordPaneAnswer(p) {
1150
1166
  function buildResume(p) {
1151
1167
  return ["resume", "--instance-id", p.instance_id];
1152
1168
  }
1153
- function buildFindMissing() {
1154
- return ["find-missing"];
1155
- }
1156
1169
  function buildExpire(p) {
1157
1170
  const f = ["expire"];
1158
1171
  if (p.older_than !== undefined)
@@ -1272,6 +1285,21 @@ var catalog_default = [
1272
1285
  package: "spawn",
1273
1286
  description: ""
1274
1287
  },
1288
+ {
1289
+ name: "ErrExperimentalAgentDisabled",
1290
+ package: "spawn",
1291
+ description: ""
1292
+ },
1293
+ {
1294
+ name: "ErrAgentCapabilityUnsupported",
1295
+ package: "spawn",
1296
+ description: ""
1297
+ },
1298
+ {
1299
+ name: "ErrModelMissing",
1300
+ package: "spawn",
1301
+ description: ""
1302
+ },
1275
1303
  {
1276
1304
  name: "ErrAgentMissing",
1277
1305
  package: "spawn",
@@ -1527,6 +1555,11 @@ var catalog_default = [
1527
1555
  package: "clisetup",
1528
1556
  description: ""
1529
1557
  },
1558
+ {
1559
+ name: "ErrJournalMigrationRefused",
1560
+ package: "adminapi",
1561
+ description: ""
1562
+ },
1530
1563
  {
1531
1564
  name: "ErrUnknownVerb",
1532
1565
  package: "clisetup",
@@ -1809,6 +1842,10 @@ class SubprocessClient {
1809
1842
  this.#assertOpen();
1810
1843
  return this.#enqueue("resume", params);
1811
1844
  }
1845
+ async sweep(params = {}) {
1846
+ this.#assertOpen();
1847
+ return this.#enqueue("sweep", params);
1848
+ }
1812
1849
  async findMissing(params) {
1813
1850
  this.#assertOpen();
1814
1851
  return this.#enqueue("find-missing", params);
@@ -1980,6 +2017,7 @@ export {
1980
2017
  ErrOldLayout,
1981
2018
  ErrNoSessionId,
1982
2019
  ErrNoOpenPermissionRequest,
2020
+ ErrModelMissing,
1983
2021
  ErrMissingRequestToken,
1984
2022
  ErrListInvalidLabel,
1985
2023
  ErrJsonlNeverWritten,
@@ -1989,6 +2027,7 @@ export {
1989
2027
  ErrInvalidDecision,
1990
2028
  ErrInternal,
1991
2029
  ErrInstanceIdCollision,
2030
+ ErrExperimentalAgentDisabled,
1992
2031
  ErrDialogMaybeOpen,
1993
2032
  ErrCwdNotFound,
1994
2033
  ErrCwdNotAPath,
@@ -2005,6 +2044,7 @@ export {
2005
2044
  ErrAlreadyDecided,
2006
2045
  ErrAgentMissing,
2007
2046
  ErrAgentInvalid,
2047
+ ErrAgentCapabilityUnsupported,
2008
2048
  ErrAgentArgsMismatch,
2009
2049
  DEV_SENTINEL_VERSION,
2010
2050
  Client,
@@ -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, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, 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, RecordPaneAnswerParams, RecordPaneAnswerResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, SweepParams, SweepResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, ListSubagentsParams, ListSubagentsResult, 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.
@@ -130,7 +130,9 @@ export declare class SubprocessClient {
130
130
  * saved prompt is never replayed, and altered Claude short clusters are
131
131
  * re-encoded only when needed to preserve their original parsed meaning. */
132
132
  resume(params: ResumeParams): Promise<ResumeResult>;
133
- /** findMissing — sweep live Spawns, marking each `missing` (a Codex row with its end report: `ended`) or leaving it unverified on process and tmux evidence; see FindMissingResult. */
133
+ /** One bounded all-agent check. A transport timeout proves neither rollback nor completion. */
134
+ sweep(params?: SweepParams): Promise<SweepResult>;
135
+ /** Compatibility entry for sweep; uses the retained CLI spelling for older binaries. */
134
136
  findMissing(params: FindMissingParams): Promise<FindMissingResult>;
135
137
  /**
136
138
  * expire — remove finished rows older than the retention window whose
@@ -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 17 callable verbs: spawn, status, get, send-keys, read-pane,
10
- * kill, decide, get-permission, record-pane-answer, resume, find-missing,
9
+ * Currently 18 callable verbs: spawn, status, get, send-keys, read-pane,
10
+ * kill, decide, get-permission, record-pane-answer, resume, sweep, find-missing,
11
11
  * expire, make-template, list, list-subagents, 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", "record-pane-answer", "resume", "find-missing", "expire", "make-template", "list", "list-subagents", "pause", "version"];
17
+ export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "get-permission", "record-pane-answer", "resume", "sweep", "find-missing", "expire", "make-template", "list", "list-subagents", "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
@@ -114,8 +114,9 @@ export interface VerbSummary {
114
114
  /**
115
115
  * A permission request's delivery state:
116
116
  * - `"delivered"`: the relay durably acknowledged a verdict before enqueue/write;
117
- * this is not agent receipt, tool execution or dialog closure.
117
+ * this is not transport completion, agent receipt, tool execution or dialog closure.
118
118
  * - `"not_confirmed"`: no ack yet and the relay hook may still run; it ends by `confirm_by`.
119
+ * This grants no response authority to a closed or proven-gone request.
119
120
  * - `"fallen_back"`: no ack, and the relay hook is gone (or cannot be checked and `confirm_by`
120
121
  * has passed): no answer from the relay reached the agent. While `pane_answer` is `"none"` or
121
122
  * `"intent"` the request awaits an answer unless acknowledged or closed with its Spawn. A pane
@@ -132,10 +133,11 @@ export type Delivery = "delivered" | "not_confirmed" | "fallen_back";
132
133
  * (`decision_reason` `"pane"`); this does not establish ACP delivery, receipt or proof.
133
134
  * - `"outside"`: a caller recorded it answered outside agent-director (`recordPaneAnswer`,
134
135
  * `decision_reason` `"pane_outside"`).
135
- * - `"tool_ran"`: agent hooks or validated correlated Cursor execution output established
136
- * its tool ran. The hook close records `decision` `"allow"` and `decision_reason` `"tool_ran"`;
137
- * Cursor proof preserves any earlier verdict and non-null reason, filling a missing reason
138
- * with `"tool_ran"`.
136
+ * - `"tool_ran"`: validated correlated Cursor execution output established its tool ran (in
137
+ * practice never on a Claude or Codex row, whose requests carry no `tool_use_id`). That
138
+ * close preserves any earlier verdict and non-null reason, inferring allow only when
139
+ * undecided and filling a missing reason with `"tool_ran"`. This history supplies no
140
+ * response authority.
139
141
  * `"sent"`, `"outside"` and `"tool_ran"` close the request; its `delivery` stays `"fallen_back"`.
140
142
  */
141
143
  export type PaneAnswer = "none" | "intent" | "sent" | "outside" | "tool_ran";
@@ -198,12 +200,13 @@ export interface RequestDelivery {
198
200
  }
199
201
  /**
200
202
  * How agent evidence proved a permission request's dialog gone:
201
- * - `"tool_ran"`: a Claude PostToolUse or PostToolUseFailure carried its `tool_use_id`, or
202
- * validated correlated Cursor execution output established that exact tool ran (never on a Codex row).
203
+ * - `"tool_ran"`: validated correlated Cursor execution output established that exact tool ran
204
+ * (in practice never on a Claude or Codex row, whose requests carry no `tool_use_id`).
203
205
  * - `"turn_end"`: the turn of the agent that asked ended after it was written; the main agent's
204
206
  * Stop or idle-prompt Notification, a Codex main agent's Interrupt (Esc), or a verified
205
207
  * Cursor main Stop/Interrupt proves only a durably main-turn-eligible request recorded
206
- * before the hook began. Legacy non-Cursor main requests retain eligibility; Cursor
208
+ * before the hook began; a Claude subagent's SubagentStop proves only that subagent's
209
+ * requests recorded before that hook began. Legacy non-Cursor main requests retain eligibility; Cursor
207
210
  * unknown-origin and child requests remain ineligible even without a child id. Decisions,
208
211
  * delivery acknowledgements and pane-answer claims do not grant eligibility.
209
212
  * - `"agent_gone"`: its non-Cursor Spawn was marked missing, ended or resumed.
@@ -235,12 +238,54 @@ export interface PermissionRequestInfo extends RequestDelivery {
235
238
  }
236
239
  /**
237
240
  * Whether `idle_screen` can apply to a row's agent: `"available"` for Claude and Codex,
238
- * `"unavailable"` for Cursor. A capability outcome, never a state.
241
+ * `"unavailable"` for Cursor and pane-only agents. A capability outcome, never a state.
239
242
  */
240
243
  export type IdleScreenAvailability = "available" | "unavailable";
244
+ /** The recorded agent process at its recorded start identity; never a Helper, tmux or a descendant. */
245
+ export type ProcessLiveness = "alive" | "exited" | "unknown";
246
+ /** A main-field confirmation's status. `confirmed` never means continuously true since `confirmed_at`. */
247
+ export type ConfirmationStatus = "confirmed" | "not_confirmed" | "unknown" | "pending";
248
+ /** The kind of evidence behind `confirmed_at`; `store` is a durable agent-director record, never provider receipt. */
249
+ export type ConfirmationSource = "agent_event" | "caller_command" | "process" | "tmux" | "pane" | "transcript" | "store";
250
+ /** Why the latest attempt did not confirm the field. */
251
+ export type ConfirmationReason = "no_evidence" | "unreadable" | "busy" | "stale_observation" | "deadline" | "operation_pending" | "pending_grace" | "unsupported" | "commit_unconfirmed";
252
+ /**
253
+ * One main field's last-confirmed evidence. Every key is always present; unknown values are null.
254
+ * `confirmed` means the value has supporting evidence with no later unresolved failed attempt.
255
+ * A failed latest attempt is `not_confirmed` (or `pending` for a still-owned operation or a
256
+ * pending-launch protection) and keeps only an older applicable `confirmed_at`.
257
+ */
258
+ export interface Confirmation {
259
+ status: ConfirmationStatus;
260
+ /** First confirmation of this exact returned value and owner in its current stay, RFC3339 UTC milliseconds; null when none is known. Later same-value evidence advances only `checked_at`. */
261
+ confirmed_at: string | null;
262
+ /** That evidence's kind; null exactly when `confirmed_at` is. */
263
+ source: ConfirmationSource | null;
264
+ /** Latest attempt, an unsuccessful one included; null when none is known. Reading stored facts never advances it. */
265
+ checked_at: string | null;
266
+ /** Null when confirmed; otherwise why not. */
267
+ reason: ConfirmationReason | null;
268
+ }
269
+ /**
270
+ * Exactly the three main-field records. `displayed_state` covers the display returned, a
271
+ * Displayed State or none (`displayed_state` omitted): only a successful sample of the row's own
272
+ * pane confirms it (source `pane`), and the display shown while an entry or exit settles keeps its
273
+ * own record. `confirmed_at` is the first confirmation in its current stay; later same-value
274
+ * samples advance only `checked_at`. No applicable evidence or attempt is `unknown`/`no_evidence`.
275
+ * A failed latest attempt is `not_confirmed` with its reason, even without an earlier confirmation
276
+ * (`confirmed_at` and `source` then stay null). Cursor's is always unknown (reason `unsupported`).
277
+ * `family_state` has no record: its freshness is unconfirmed. Freshness never authorizes a command.
278
+ */
279
+ export interface Confirmations {
280
+ state: Confirmation;
281
+ process_liveness: Confirmation;
282
+ displayed_state: Confirmation;
283
+ }
241
284
  /** One Spawn row returned by the list verb. */
242
285
  export interface ListRow {
243
- /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
286
+ /** Fixed supervised-pane contract; omitted for native integrations. Live rows stay pending, context is null, idle screen unavailable and subagents untracked. */
287
+ integration_mode?: "pane_only";
288
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor and pane-only agents. */
244
289
  idle_screen_availability: IdleScreenAvailability;
245
290
  /** Stable Spawn id. */
246
291
  instance_id: string;
@@ -257,7 +302,7 @@ export interface ListRow {
257
302
  * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
258
303
  * off), this is the settled state: a state a hook wrote shows only once it has held for
259
304
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
260
- * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
305
+ * shows; ended, missing and a state a command wrote (spawn, resume, sweep/find-missing) show at once.
261
306
  * Nothing marks a state as late. `family_state` settles independently. Fields such as
262
307
  * `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
263
308
  * live state, which can be newer: a refusal can name a state this field does not show yet.
@@ -265,10 +310,10 @@ export interface ListRow {
265
310
  state: string;
266
311
  /**
267
312
  * The report-only Displayed State the row shows beside `state`, present only while one
268
- * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across reads), or
313
+ * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across checks), or
269
314
  * `needs_intelligence` (an unknown prompt inferred on the agent's screen), which nothing
270
- * shows yet. Entering or leaving it times `[state] settle_ms` from the read that commits its
271
- * candidate; a later read commits the change. Live command guards follow the raw state.
315
+ * shows yet. Entering or leaving it times `[state] settle_ms` from the check that commits its
316
+ * candidate; a later check commits the change. Live command guards follow the raw state.
272
317
  */
273
318
  displayed_state?: "needs_intelligence" | "idle_screen";
274
319
  /**
@@ -280,9 +325,13 @@ export interface ListRow {
280
325
  * task success.
281
326
  */
282
327
  family_state: "working" | "waiting";
328
+ /** The recorded agent process at its recorded start identity; Cursor is `"unknown"` (unsupported). Never refreshes `state`. */
329
+ process_liveness: ProcessLiveness;
330
+ /** Exactly the `state`, `process_liveness` and `displayed_state` records. */
331
+ confirmations: Confirmations;
283
332
  /** Canonicalized working directory. */
284
333
  cwd: string;
285
- /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
334
+ /** The agent the row runs. Set at spawn; resume follows it. */
286
335
  agent: string;
287
336
  /** tmux session name. */
288
337
  tmux_session_name: string;
@@ -312,22 +361,22 @@ export interface ListRow {
312
361
  */
313
362
  launch_started_at?: string | null;
314
363
  /**
315
- * RFC3339 timestamp of the first sweep that noted this live row (left it
316
- * unverified, or noted it `unreported`); kept while later sweeps change
364
+ * RFC3339 timestamp of the first check that noted this live row (left it
365
+ * unverified, or noted it `unreported`); kept while later checks change
317
366
  * `liveness_note`, `unreported` included. Cleared together with
318
- * `liveness_note` when a sweep finds the agent process alive, except on a
367
+ * `liveness_note` when a check finds the agent process alive, except on a
319
368
  * pending row it notes `unreported` and a pending row noted
320
369
  * `provenance_conflict`, which keeps it; omitted/null while the row has no
321
370
  * note.
322
371
  */
323
372
  liveness_unverified_since?: string | null;
324
373
  /**
325
- * Reason token of the latest sweep that left this live row unverified (its
374
+ * Reason token of the latest check that left this live row unverified (its
326
375
  * agent process could not be checked and tmux did not settle it), for
327
376
  * example `process_not_seen_session_present`,
328
377
  * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
329
378
  * or `provenance_conflict`; overwritten when the reason changes. Cleared
330
- * together with `liveness_unverified_since` when a sweep finds the agent
379
+ * together with `liveness_unverified_since` when a check finds the agent
331
380
  * process alive, except on a pending row it notes `unreported` and a
332
381
  * pending row noted `provenance_conflict`, which keeps it; omitted/null
333
382
  * while the row has no note. Or `unreported`, on a pending row past the
@@ -335,7 +384,7 @@ export interface ListRow {
335
384
  * its launch, so it may sit at an agent startup screen or idle at its
336
385
  * prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
337
386
  * with `allow_pending`; only a caller that looked should type. A later
338
- * sweep that finds the agent alive keeps the note; the agent's next hook
387
+ * check that finds the agent alive keeps the note; the agent's next hook
339
388
  * clears it. `unreported` never replaces `provenance_conflict`.
340
389
  */
341
390
  liveness_note?: string | null;
@@ -358,9 +407,9 @@ export interface SpawnParams {
358
407
  /** Named template under ~/.config/agent-director/templates/. */
359
408
  template?: string;
360
409
  /**
361
- * The agent to launch: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor); case-sensitive,
410
+ * The agent to launch, such as `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor); case-sensitive,
362
411
  * empty or absent means not given. Spawn resolves it per call, else from `template`'s
363
- * `agent`; with neither, the spawn is refused with `ErrAgentMissing`. Any other value is
412
+ * `agent`; with neither, the spawn is refused with `ErrAgentMissing`. An unrecognized value is
364
413
  * refused with `ErrAgentInvalid`. A template's `agent_args` belong to the template's agent
365
414
  * and are refused with `ErrAgentArgsMismatch` when the spawn's agent differs, unless this call
366
415
  * passes its own non-empty `agent_args`. The
@@ -484,12 +533,14 @@ export interface StatusParams {
484
533
  }
485
534
  /** The row's reported lifecycle state. */
486
535
  export interface StatusResult {
536
+ /** Fixed supervised-pane contract; omitted for native integrations. Live rows stay pending, context is null, idle screen unavailable and subagents untracked. */
537
+ integration_mode?: "pane_only";
487
538
  /**
488
539
  * The report-only Displayed State the row shows beside `state`, present only while one
489
- * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across reads), or
540
+ * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across checks), or
490
541
  * `needs_intelligence` (an unknown prompt inferred on the agent's screen), which nothing
491
- * shows yet. Entering or leaving it times `[state] settle_ms` from the read that commits its
492
- * candidate; a later read commits the change. Live command guards follow the raw state.
542
+ * shows yet. Entering or leaving it times `[state] settle_ms` from the check that commits its
543
+ * candidate; a later check commits the change. Live command guards follow the raw state.
493
544
  */
494
545
  displayed_state?: "needs_intelligence" | "idle_screen";
495
546
  /**
@@ -505,7 +556,7 @@ export interface StatusResult {
505
556
  unchanged_minutes?: number;
506
557
  /** Attach target, present only while `displayed_state` is. */
507
558
  tmux_session_name?: string;
508
- /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
559
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor and pane-only agents. */
509
560
  idle_screen_availability: IdleScreenAvailability;
510
561
  /** Experimental context estimate for the current session. */
511
562
  context: ContextReading;
@@ -521,7 +572,7 @@ export interface StatusResult {
521
572
  * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
522
573
  * off), this is the settled state: a state a hook wrote shows only once it has held for
523
574
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
524
- * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
575
+ * shows; ended, missing and a state a command wrote (spawn, resume, sweep/find-missing) show at once.
525
576
  * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
526
577
  * can be newer: a refusal can name a state status does not show yet.
527
578
  */
@@ -535,6 +586,10 @@ export interface StatusResult {
535
586
  * task success.
536
587
  */
537
588
  family_state: "working" | "waiting";
589
+ /** The recorded agent process at its recorded start identity; Cursor is `"unknown"` (unsupported). Never refreshes `state`. */
590
+ process_liveness: ProcessLiveness;
591
+ /** Exactly the `state`, `process_liveness` and `displayed_state` records. */
592
+ confirmations: Confirmations;
538
593
  /**
539
594
  * Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
540
595
  * pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
@@ -568,12 +623,14 @@ export interface GetParams {
568
623
  }
569
624
  /** One tracked agent row, with its current session and request facts. */
570
625
  export interface GetResult {
626
+ /** Fixed supervised-pane contract; omitted for native integrations. Live rows stay pending, context is null, idle screen unavailable and subagents untracked. */
627
+ integration_mode?: "pane_only";
571
628
  /**
572
629
  * The report-only Displayed State the row shows beside `state`, present only while one
573
- * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across reads), or
630
+ * shows: `idle_screen` (a working Claude or Codex row's pane unchanged across checks), or
574
631
  * `needs_intelligence` (an unknown prompt inferred on the agent's screen), which nothing
575
- * shows yet. Entering or leaving it times `[state] settle_ms` from the read that commits its
576
- * candidate; a later read commits the change. Live command guards follow the raw state.
632
+ * shows yet. Entering or leaving it times `[state] settle_ms` from the check that commits its
633
+ * candidate; a later check commits the change. Live command guards follow the raw state.
577
634
  */
578
635
  displayed_state?: "needs_intelligence" | "idle_screen";
579
636
  /**
@@ -587,7 +644,7 @@ export interface GetResult {
587
644
  tool_name?: string;
588
645
  /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
589
646
  unchanged_minutes?: number;
590
- /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
647
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor and pane-only agents. */
591
648
  idle_screen_availability: IdleScreenAvailability;
592
649
  /** Experimental context estimate for the current session. */
593
650
  context: ContextReading;
@@ -605,7 +662,7 @@ export interface GetResult {
605
662
  * With `[state] settle_ms` set in the CLI's config.toml (whole milliseconds; 0 or unset is
606
663
  * off), this is the settled state: a state a hook wrote shows only once it has held for
607
664
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
608
- * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
665
+ * shows; ended, missing and a state a command wrote (spawn, resume, sweep/find-missing) show at once.
609
666
  * Nothing marks a state as late. While a `displayed_state` exit settles, it, `since` and its
610
667
  * detail keep the previous display's committed values, and `family_state` settles
611
668
  * independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
@@ -622,8 +679,12 @@ export interface GetResult {
622
679
  * task success.
623
680
  */
624
681
  family_state: "working" | "waiting";
682
+ /** The recorded agent process at its recorded start identity; Cursor is `"unknown"` (unsupported). Never refreshes `state`. */
683
+ process_liveness: ProcessLiveness;
684
+ /** Exactly the `state`, `process_liveness` and `displayed_state` records. */
685
+ confirmations: Confirmations;
625
686
  cwd: string;
626
- /** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
687
+ /** The agent the row runs. Set at spawn; resume follows it. */
627
688
  agent: string;
628
689
  tmux_session_name: string;
629
690
  /** The tmux socket the row's launch uses; omitted when the row has no recorded socket. */
@@ -662,22 +723,22 @@ export interface GetResult {
662
723
  */
663
724
  launch_started_at?: string | null;
664
725
  /**
665
- * RFC3339 timestamp of the first sweep that noted this live row (left it
666
- * unverified, or noted it `unreported`); kept while later sweeps change
726
+ * RFC3339 timestamp of the first check that noted this live row (left it
727
+ * unverified, or noted it `unreported`); kept while later checks change
667
728
  * `liveness_note`, `unreported` included. Cleared together with
668
- * `liveness_note` when a sweep finds the agent process alive, except on a
729
+ * `liveness_note` when a check finds the agent process alive, except on a
669
730
  * pending row it notes `unreported` and a pending row noted
670
731
  * `provenance_conflict`, which keeps it; omitted/null while the row has no
671
732
  * note.
672
733
  */
673
734
  liveness_unverified_since?: string | null;
674
735
  /**
675
- * Reason token of the latest sweep that left this live row unverified (its
736
+ * Reason token of the latest check that left this live row unverified (its
676
737
  * agent process could not be checked and tmux did not settle it), for
677
738
  * example `process_not_seen_session_present`,
678
739
  * `process_not_seen_tmux_unchecked`, `probe_eacces`, `tmux_server_changed`
679
740
  * or `provenance_conflict`; overwritten when the reason changes. Cleared
680
- * together with `liveness_unverified_since` when a sweep finds the agent
741
+ * together with `liveness_unverified_since` when a check finds the agent
681
742
  * process alive, except on a pending row it notes `unreported` and a
682
743
  * pending row noted `provenance_conflict`, which keeps it; omitted/null
683
744
  * while the row has no note. Or `unreported`, on a pending row past the
@@ -685,7 +746,7 @@ export interface GetResult {
685
746
  * its launch, so it may sit at an agent startup screen or idle at its
686
747
  * prompt. The row stays pending. To act on it: `readPane`, then `sendKeys`
687
748
  * with `allow_pending`; only a caller that looked should type. A later
688
- * sweep that finds the agent alive keeps the note; the agent's next hook
749
+ * check that finds the agent alive keeps the note; the agent's next hook
689
750
  * clears it. `unreported` never replaces `provenance_conflict`.
690
751
  */
691
752
  liveness_note?: string | null;
@@ -863,7 +924,7 @@ export interface GetPermissionResult extends RequestDelivery {
863
924
  decision?: "allow" | "deny" | null;
864
925
  /**
865
926
  * Canonical decision-reason string: "operator" | "timeout" | "find_missing" | "ended" for deny
866
- * rows ("find_missing" / "ended": still undecided when find-missing marked its spawn missing, or
927
+ * rows ("find_missing" / "ended": still undecided when a shared check marked its spawn missing, or
867
928
  * when its spawn ended or was resumed, and closed); "pane" | "pane_outside" | "tool_ran" for a
868
929
  * request answered through sendKeys or a Cursor native choice ("pane"), recorded outside
869
930
  * ("pane_outside"), or carrying tool execution evidence ("tool_ran"). Pane claims do not establish
@@ -1047,17 +1108,38 @@ export interface ResumeResult {
1047
1108
  */
1048
1109
  pre_trust: "ok" | "skipped" | "failed";
1049
1110
  }
1050
- /** Params for the `find-missing` verb, which takes no CLI flags. */
1051
- export interface FindMissingParams {
1111
+ /** Params for sweep and its find-missing alias; neither takes CLI flags. */
1112
+ export interface SweepParams {
1052
1113
  /**
1053
- * Accepted but not sent: the `find-missing` CLI verb takes no flags, so
1114
+ * Accepted but not sent: neither CLI spelling takes flags, so
1054
1115
  * this value has no effect. The call is bounded by the Client's
1055
1116
  * `callTimeoutMs` like every other verb.
1056
1117
  */
1057
1118
  timeout_ms?: number;
1058
1119
  }
1059
- /** Rows marked missing, ended or left unverified by the sweep. */
1060
- export interface FindMissingResult {
1120
+ /** Retained compatibility name for sweep parameters. */
1121
+ export interface FindMissingParams extends SweepParams {
1122
+ }
1123
+ /** A fixed-snapshot agent, including finished and unattempted rows. */
1124
+ export interface SweepCheck {
1125
+ instance_id: string;
1126
+ state: StatusResult["state"];
1127
+ displayed_state?: StatusResult["displayed_state"];
1128
+ /** Stored family projection; its freshness is unconfirmed. */
1129
+ family_state: "working" | "waiting";
1130
+ idle_screen_availability: IdleScreenAvailability;
1131
+ process_liveness: ProcessLiveness;
1132
+ /** Exactly the three independent main-field records, including unknowns. */
1133
+ confirmations: Confirmations;
1134
+ /** Coverage: eligible adapters attempted or inapplicable, not fields confirmed. */
1135
+ completion: "complete" | "incomplete";
1136
+ /** Null when complete. Unattempted work adds no evidence timestamps. */
1137
+ reason: "deadline" | "busy" | "unreadable" | "stale_observation" | "no_evidence" | "commit_unconfirmed" | "unsupported" | "unattempted" | null;
1138
+ }
1139
+ /** One bounded shared check pass; no input, answer, restart or signal authority. */
1140
+ export interface SweepResult {
1141
+ /** Sorted fixed all-agent selection; never null. Failed/remaining rows stay represented. */
1142
+ checks: SweepCheck[];
1061
1143
  /**
1062
1144
  * Number of rows this sweep marked `missing` (the length of `ids`); a Codex
1063
1145
  * row it moved to `ended` is not counted. Zero is a normal result when
@@ -1070,12 +1152,13 @@ export interface FindMissingResult {
1070
1152
  * pane's) is dead, and rows whose process could not be checked and tmux
1071
1153
  * found no session or pane of their current launch; a pending row only past
1072
1154
  * the pending grace period, and never while the spawn, reuse or resume that
1073
- * began its launch still runs. A row whose guarded write found it changed or
1074
- * gone, or failed, is in neither list, and so is a Codex row the sweep moved
1075
- * to `ended` (its agent process gone and an end report held) and a pending
1076
- * row the sweep notes `unreported` (its agent alive) or finds already noted
1077
- * so. `missing` is the sweep's judgement on the evidence available to it, not
1078
- * proof that the agent has exited. Never null; [] when none.
1155
+ * began its launch still runs, except a Cursor row whose exact recorded
1156
+ * gateway is gone, which neither protects. A row whose guarded write found
1157
+ * it changed or gone, or failed, is in neither list, and so is a Codex row
1158
+ * the sweep moved to `ended` (its agent process gone and an end report held)
1159
+ * and a pending row the sweep notes `unreported` (its agent alive) or finds
1160
+ * already noted so. `missing` is a check's judgement on available evidence,
1161
+ * not proof that the agent has exited. Never null; [] when none.
1079
1162
  */
1080
1163
  ids: string[];
1081
1164
  /** Number of live rows this sweep left unverified (the length of `unverified_ids`). */
@@ -1094,6 +1177,9 @@ export interface FindMissingResult {
1094
1177
  */
1095
1178
  unverified_ids: string[];
1096
1179
  }
1180
+ /** Retained compatibility name for the common sweep result. */
1181
+ export interface FindMissingResult extends SweepResult {
1182
+ }
1097
1183
  /** The minimum finished-row age for cleanup. */
1098
1184
  export interface ExpireParams {
1099
1185
  /**
@@ -1142,10 +1228,10 @@ export interface MakeTemplateParams {
1142
1228
  /** Default working directory to bake in. */
1143
1229
  cwd?: string;
1144
1230
  /**
1145
- * The agent the template belongs to: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor);
1231
+ * The agent the template belongs to, such as `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor);
1146
1232
  * case-sensitive, empty or absent means not given. Required when the template bakes in
1147
1233
  * `agent_args` (otherwise `ErrTemplateAgentMissing`); a Codex or Cursor template cannot bake in
1148
- * `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). Any other value is refused
1234
+ * `allow`, `deny` or `ask` (`ErrPermissionsUnsupported`). An unrecognized value is refused
1149
1235
  * with `ErrTemplateMalformed` (`ErrAgentInvalid` is spawn's per-call refusal). A spawn
1150
1236
  * that names no agent takes it from the template.
1151
1237
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.17.7",
3
+ "version": "0.18.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],