agent-director 0.16.0 → 0.17.1

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
@@ -157,13 +157,15 @@ console.log(result.state);
157
157
  aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
158
158
  defines reporting limits.
159
159
 
160
- `state` is a `string` and can be `"needs_intelligence"` or `"idle_screen"`.
161
- Then `StatusResult` and `GetResult` carry `since` and that state's detail:
162
- `request_token` and `tool_name` for `"needs_intelligence"`, or
163
- `unchanged_minutes` for `"idle_screen"`; `StatusResult` also carries
164
- `tmux_session_name`, and each `ListRow` carries `state`, no detail. A key that
165
- does not apply is absent from the result, never `null`, so test for presence
166
- (`result.since !== undefined`). Every `StatusResult`, `GetResult` and
160
+ `state` is always the lifecycle state. While a row shows a
161
+ Displayed State, `StatusResult`, `GetResult` and each `ListRow` carry it in
162
+ `displayed_state` (`"idle_screen"`; `"needs_intelligence"` is defined, but
163
+ nothing shows it yet). `StatusResult` and `GetResult` then also carry
164
+ `since` and, for `"idle_screen"`, `unchanged_minutes`; `StatusResult` also
165
+ carries `tmux_session_name`. A `ListRow` carries no detail. A key that does
166
+ not apply is absent from the result, never `null`, so test for presence
167
+ (`result.displayed_state !== undefined`). Test `displayed_state`, never
168
+ `state`, for `"idle_screen"` or `"needs_intelligence"`. Every `StatusResult`, `GetResult` and
167
169
  `ListRow` carries `idle_screen_availability` (`IdleScreenAvailability`:
168
170
  `"available"` for Claude and Codex, `"unavailable"` for Cursor).
169
171
  The [caller contract](../../docs/caller-contract.md#needs-intelligence-and-idle-screen-rows)
@@ -191,8 +193,9 @@ for (const spawn of result.spawns) {
191
193
  ```
192
194
 
193
195
  Each row, like `get`'s result, carries `agent` (`"claude"`, `"codex"` or `"cursor"`), the agent the row runs.
194
- A `state` filter of `"needs_intelligence"` or `"idle_screen"` is matched on
195
- the displayed state, before any `limit`.
196
+ A `state` filter keeps a row whose `state` or `displayed_state` is one of its
197
+ values, before any `limit`, so `["working"]` keeps a working row that shows
198
+ `"idle_screen"`.
196
199
 
197
200
  ### listSubagents
198
201
 
@@ -238,14 +241,13 @@ hash returns runtime proof fields
238
241
  normalized text in the launch's native transcript. The published
239
242
  `SendKeysParams` and `SendKeysResult` declarations do not expose native request
240
243
  IDs or proof fields; use the Go API or CLI for explicit delivery request IDs.
241
- Launches without
242
- native capability retain literal text and one Enter, return an empty object on
244
+ Launches without native capability use fallback input, return an empty object on
243
245
  success and make no exact transcript-confirmation claim. Manual
244
246
  operations (`no_enter`, `key`, empty text, pane hashes and permission answers)
245
247
  return an empty object on success; their input-ownership refusals are in
246
248
  [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
247
- Supported launches, omitted-ID behavior, structured
248
- outcomes and recovery are in
249
+ Supported launches, Codex fallback paste and input restrictions, omitted-ID
250
+ behavior, structured outcomes and recovery are in
249
251
  [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission).
250
252
  Allow sufficient `callTimeoutMs` for that delivery window; a timeout does not
251
253
  cancel submission.
@@ -264,10 +266,12 @@ only a session an earlier launch left behind is found, gets
264
266
  supported launches; it does not make a startup dialog an ordinary composer.
265
267
  For fallback input to a pending Codex row, the bounded hook-state observation
266
268
  and its unconfirmed result are described in the caller contract.
267
- `SubmissionUnconfirmedDetails` describes that fallback payload only:
269
+ `SubmissionUnconfirmedDetails` describes only a failed fallback hook observation:
268
270
  `keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
269
- uncertainty adds `outcome`, `request_id`, `phase`, `bytes_attempted`,
270
- `enter_may_have_been_sent`, optional `last_queue` and `reason` at runtime.
271
+ uncertainty and Codex fallback refusals or paste failures carry additional
272
+ runtime fields, including `outcome`, `phase`, `bytes_attempted`,
273
+ `enter_may_have_been_sent` and `reason`; native attempts can also carry
274
+ `request_id` and `last_queue`.
271
275
  Read these through `AgentDirectorError.errDetails`, whose type is
272
276
  `Readonly<Record<string, unknown>> | null`, and check their values; see
273
277
  [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission)
@@ -427,10 +431,11 @@ tool ran or Cursor supplied validated exact matching invocation proof under
427
431
  MCP invocation that proves dialog closure without inferring execution or changing
428
432
  decision, delivery or pane-answer fields;
429
433
  `"turn_end"`, an eligible main request's turn ended under the age and identity
430
- guards; or `"agent_gone"`, the agent ended) say when and how the request's
434
+ guards, or a Cursor turn ended with the request still unanswered; or
435
+ `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
431
436
  dialog was proven gone; `"delivered"` and a pane answer are
432
437
  agent-director's own records, not proof. `get`'s `unproven_requests` lists
433
- every request not yet proven gone, each with `unproven_since`. A request
438
+ every request still holding the dialog, each with `unproven_since`. A request
434
439
  that reads `"delivered"` or closed at the pane can remain unproven; its dialog
435
440
  may still be there. Handling is in the
436
441
  [caller contract](../../docs/caller-contract.md#permission-relay).
@@ -576,8 +581,8 @@ carry one, typed as exported interfaces: `ErrRelayFallenBack`
576
581
  `ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
577
582
  (`DialogMaybeOpenDetails`), `ErrPauseTimeout` (`PauseTimeoutDetails`) and
578
583
  `ErrSubmissionUnconfirmed`
579
- (`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
580
- Native submission facts remain available through the generic `errDetails`
584
+ (`SubmissionUnconfirmedDetails`, for failed fallback hook observation).
585
+ Native and fallback paste facts remain available through the generic `errDetails`
581
586
  record. So does the `ErrInternal` of a
582
587
  pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
583
588
  `key_sent` `true` and `request_token`). Read facts from `errDetails`, never
@@ -663,7 +668,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
663
668
  |---|---|
664
669
  | `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
665
670
  | `ErrSpawnNotInteractive` | New input requires a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. `ended` and `missing` rows are refused even when observing an existing delivery request; see [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission). |
666
- | `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes fallback pending-Codex uncertainty; native outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
671
+ | `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes failed fallback hook observation; native and fallback paste outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
667
672
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
668
673
  | `ErrPauseTimeout` | Exit keys were sent but `ended` was not observed; `errDetails` has the `PauseTimeoutDetails` shape. See [When pause cannot confirm exit](../../docs/caller-contract.md#when-pause-cannot-confirm-exit). |
669
674
  | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
@@ -692,7 +697,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
692
697
  |---|---|
693
698
  | `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while the request relay may still answer. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
694
699
  | `ErrRelayFallenBack` | The request's relay settled without acknowledgement and no pane answer is recorded through agent-director. Cursor uses finite `confirm_by` with null per-request hook process evidence; see [Cursor permissions](../../docs/permissions.md#cursor-spawns). Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
695
- | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
700
+ | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence and is not a Cursor request of an earlier launch (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
696
701
  | `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
697
702
  | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
698
703
  | `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
package/dist/errors.d.ts CHANGED
@@ -364,8 +364,9 @@ export declare class ErrClaimTooSoon extends AgentDirectorError {
364
364
  /**
365
365
  * Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
366
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 the agent's end), whatever
368
- * agent-director's records say of it; its dialog may still be on the pane. Nothing was sent.
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.
369
+ * A Cursor request of an earlier launch of the Spawn does not count. Nothing was sent.
369
370
  * `errDetails` is a `DialogMaybeOpenDetails`. A plain `sendKeys` whose `expect_pane_sha256`
370
371
  * matches the pane is not rejected with it; pass that hash only from a pane a person or LLM
371
372
  * judged, never from an automatic flow.
package/dist/types.d.ts CHANGED
@@ -182,7 +182,8 @@ export interface RequestDelivery {
182
182
  * When agent evidence proved the request's permission dialog gone; null until
183
183
  * then. agent-director's own records (`delivered`, a pane answer, `recordPaneAnswer`) are not
184
184
  * proof. While it is null, a plain `sendKeys` to the live Spawn without `expect_pane_sha256`,
185
- * and a `pause`, reject with `ErrDialogMaybeOpen`.
185
+ * and a `pause`, reject with `ErrDialogMaybeOpen`, unless it is a Cursor request of an earlier
186
+ * launch of the row.
186
187
  */
187
188
  proven_gone_at: string | null;
188
189
  /** How it was proven gone; see {@link ProvenGoneHow}. Null until proven. */
@@ -205,15 +206,15 @@ export interface RequestDelivery {
205
206
  * before the hook began. Legacy non-Cursor main requests retain eligibility; Cursor
206
207
  * unknown-origin and child requests remain ineligible even without a child id. Decisions,
207
208
  * delivery acknowledgements and pane-answer claims do not grant eligibility.
208
- * - `"agent_gone"`: its Spawn was marked missing, ended or resumed.
209
+ * - `"agent_gone"`: its non-Cursor Spawn was marked missing, ended or resumed.
209
210
  */
210
211
  export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
211
212
  /**
212
213
  * One permission request with its delivery facts:
213
214
  * an open one (still awaiting an answer) in the `permission_requests` of a `get` or `list` row in
214
- * state check_permission; one not proven gone, open or read closed, in `get`'s
215
- * `unproven_requests`; and the request an `errDetails` names (the base of
216
- * `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
215
+ * state check_permission; one that holds the dialog (not proven gone, less a Cursor request of an
216
+ * earlier launch), open or read closed, in `get`'s `unproven_requests`; and the request an
217
+ * `errDetails` names (the base of `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
217
218
  */
218
219
  export interface PermissionRequestInfo extends RequestDelivery {
219
220
  /** Autoincrement primary key of the permission_requests row. */
@@ -247,8 +248,8 @@ export interface ListRow {
247
248
  parent_id?: string;
248
249
  /**
249
250
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
250
- * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
251
- * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
251
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
252
+ * keeps its row check_permission however long it waits.
252
253
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
253
254
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
254
255
  * prompt. A resumed pending row keeps its session id and history.
@@ -257,20 +258,26 @@ export interface ListRow {
257
258
  * off), this is the settled state: a state a hook wrote shows only once it has held for
258
259
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
259
260
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
260
- * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
261
- * times settle_ms from the read that commits its candidate; a later read commits the change.
262
261
  * Nothing marks a state as late. `family_state` settles independently. Fields such as
263
262
  * `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
264
263
  * live state, which can be newer: a refusal can name a state this field does not show yet.
265
264
  */
266
265
  state: string;
266
+ /**
267
+ * 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
269
+ * `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.
272
+ */
273
+ displayed_state?: "needs_intelligence" | "idle_screen";
267
274
  /**
268
275
  * Complete stored family: self and live descendants, including through retained terminal
269
- * intermediates. A live member counts as working while its raw state is not waiting or its
270
- * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
271
- * commits. Waiting means no member counts as working, or no live members remain. Settles once
272
- * in either direction with `[state] settle_ms`, independently of `state`. This report does
273
- * not establish readiness or task success.
276
+ * intermediates. A live member counts as working while its raw state is not waiting or it
277
+ * shows `idle_screen`, until that display's exit commits. Waiting means no member
278
+ * counts as working, or no live members remain. Settles once in either direction with
279
+ * `[state] settle_ms`, independently of `state`. This report does not establish readiness or
280
+ * task success.
274
281
  */
275
282
  family_state: "working" | "waiting";
276
283
  /** Canonicalized working directory. */
@@ -339,8 +346,8 @@ export interface ListRow {
339
346
  * follow a tracked request with `getPermission`. Requests are never delayed by
340
347
  * `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
341
348
  * (even ended or missing) with open requests listed, or check_permission with `[]`, for up
342
- * to settle_ms; entering or leaving `needs_intelligence` or `idle_screen` has no such bound
343
- * (see `state`).
349
+ * to settle_ms; entering or leaving a `displayed_state` has no such bound (see
350
+ * `displayed_state`).
344
351
  */
345
352
  permission_requests: PermissionRequestInfo[];
346
353
  }
@@ -478,20 +485,25 @@ export interface StatusParams {
478
485
  /** The row's reported lifecycle state. */
479
486
  export interface StatusResult {
480
487
  /**
481
- * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
482
- * only while `needs_intelligence` or `idle_screen` is displayed.
488
+ * 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
490
+ * `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.
483
493
  */
484
- since?: string;
494
+ displayed_state?: "needs_intelligence" | "idle_screen";
485
495
  /**
486
- * The representative unanswered request (earliest qualifying fallback, lexical
487
- * request-token tie break); only while `needs_intelligence`.
496
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
497
+ * only while `displayed_state` is present.
488
498
  */
499
+ since?: string;
500
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
489
501
  request_token?: string;
490
- /** That request's tool; only while `needs_intelligence`. */
502
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
491
503
  tool_name?: string;
492
504
  /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
493
505
  unchanged_minutes?: number;
494
- /** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
506
+ /** Attach target, present only while `displayed_state` is. */
495
507
  tmux_session_name?: string;
496
508
  /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
497
509
  idle_screen_availability: IdleScreenAvailability;
@@ -499,8 +511,8 @@ export interface StatusResult {
499
511
  context: ContextReading;
500
512
  /**
501
513
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
502
- * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
503
- * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
514
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
515
+ * keeps its row check_permission however long it waits.
504
516
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
505
517
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
506
518
  * prompt. A resumed pending row keeps its session id and history; a caller tells it
@@ -510,19 +522,17 @@ export interface StatusResult {
510
522
  * off), this is the settled state: a state a hook wrote shows only once it has held for
511
523
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
512
524
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
513
- * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
514
- * times settle_ms from the read that commits its candidate; a later read commits the change.
515
525
  * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
516
526
  * can be newer: a refusal can name a state status does not show yet.
517
527
  */
518
528
  state: string;
519
529
  /**
520
530
  * Complete stored family: self and live descendants, including through retained terminal
521
- * intermediates. A live member counts as working while its raw state is not waiting or its
522
- * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
523
- * commits. Waiting means no member counts as working, or no live members remain. Settles once
524
- * in either direction with `[state] settle_ms`, independently of `state`. This report does
525
- * not establish readiness or task success.
531
+ * intermediates. A live member counts as working while its raw state is not waiting or it
532
+ * shows `idle_screen`, until that display's exit commits. Waiting means no member
533
+ * counts as working, or no live members remain. Settles once in either direction with
534
+ * `[state] settle_ms`, independently of `state`. This report does not establish readiness or
535
+ * task success.
526
536
  */
527
537
  family_state: "working" | "waiting";
528
538
  /**
@@ -559,16 +569,21 @@ export interface GetParams {
559
569
  /** One tracked agent row, with its current session and request facts. */
560
570
  export interface GetResult {
561
571
  /**
562
- * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
563
- * only while `needs_intelligence` or `idle_screen` is displayed.
572
+ * 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
574
+ * `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.
564
577
  */
565
- since?: string;
578
+ displayed_state?: "needs_intelligence" | "idle_screen";
566
579
  /**
567
- * The representative unanswered request (earliest qualifying fallback, lexical
568
- * request-token tie break); only while `needs_intelligence`.
580
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
581
+ * only while `displayed_state` is present.
569
582
  */
583
+ since?: string;
584
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
570
585
  request_token?: string;
571
- /** That request's tool; only while `needs_intelligence`. */
586
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
572
587
  tool_name?: string;
573
588
  /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
574
589
  unchanged_minutes?: number;
@@ -580,8 +595,8 @@ export interface GetResult {
580
595
  parent_id: string;
581
596
  /**
582
597
  * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
583
- * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
584
- * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
598
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
599
+ * keeps its row check_permission however long it waits.
585
600
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
586
601
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
587
602
  * prompt. A resumed pending row keeps its session id and history; a non-empty
@@ -591,10 +606,8 @@ export interface GetResult {
591
606
  * off), this is the settled state: a state a hook wrote shows only once it has held for
592
607
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
593
608
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
594
- * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
595
- * times settle_ms from the read that commits its candidate; a later read commits the change.
596
- * Nothing marks a state as late. While an exit or direct move settles, `since` and that
597
- * state's detail keep the previous display's committed values, and `family_state` settles
609
+ * Nothing marks a state as late. While a `displayed_state` exit settles, it, `since` and its
610
+ * detail keep the previous display's committed values, and `family_state` settles
598
611
  * independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
599
612
  * that act on the row, follow its live state, which can be newer: a refusal can name a state
600
613
  * this field does not show yet.
@@ -602,11 +615,11 @@ export interface GetResult {
602
615
  state: string;
603
616
  /**
604
617
  * Complete stored family: self and live descendants, including through retained terminal
605
- * intermediates. A live member counts as working while its raw state is not waiting or its
606
- * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
607
- * commits. Waiting means no member counts as working, or no live members remain. Settles once
608
- * in either direction with `[state] settle_ms`, independently of `state`. This report does
609
- * not establish readiness or task success.
618
+ * intermediates. A live member counts as working while its raw state is not waiting or it
619
+ * shows `idle_screen`, until that display's exit commits. Waiting means no member
620
+ * counts as working, or no live members remain. Settles once in either direction with
621
+ * `[state] settle_ms`, independently of `state`. This report does not establish readiness or
622
+ * task success.
610
623
  */
611
624
  family_state: "working" | "waiting";
612
625
  cwd: string;
@@ -684,20 +697,19 @@ export interface GetResult {
684
697
  * `getPermission`.
685
698
  * Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
686
699
  * settling can also show any state (even ended or missing) with open requests listed, or
687
- * check_permission with `[]`, for up to settle_ms; entering or leaving `needs_intelligence`
688
- * or `idle_screen` has no such bound (see `state`).
700
+ * check_permission with `[]`, for up to settle_ms; entering or leaving a `displayed_state`
701
+ * has no such bound (see `displayed_state`).
689
702
  */
690
703
  permission_requests: PermissionRequestInfo[];
691
704
  /**
692
- * Every permission request of the row that the agent's hooks have not proven gone (`proven_gone_at`
693
- * null), oldest first, in any live state but ended and missing (`[]` on those). Unlike
694
- * `permission_requests` it also lists requests agent-director's records read closed
695
- * (delivered, answered at the pane, or recorded answered outside it), each with
696
- * `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
697
- * and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
698
- * row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
699
- * with `state` for up to settle_ms under ordinary raw-state settling, and without that bound
700
- * while entering or leaving `needs_intelligence` or `idle_screen` (see `state`).
705
+ * Every permission request of the row that the agent's hooks have not proven gone
706
+ * (`proven_gone_at` null), less Cursor requests of an earlier launch of the row, oldest first,
707
+ * in any live state but ended and missing (`[]` on those). Unlike `permission_requests` it
708
+ * also lists requests agent-director's records read closed (delivered, answered at the pane,
709
+ * or recorded answered outside it), each with `unproven_since`. While it is not empty, a plain
710
+ * `sendKeys` without `expect_pane_sha256`, and a `pause`, reject (`ErrDialogMaybeOpen`, or an
711
+ * earlier relay refusal). It follows the row's live state and is never delayed by
712
+ * `[state] settle_ms`, so with it set it can disagree with `state` for up to settle_ms.
701
713
  */
702
714
  unproven_requests: PermissionRequestInfo[];
703
715
  }
@@ -931,11 +943,12 @@ export interface RelayFallenBackDetails extends PermissionRequestInfo {
931
943
  open_requests: OpenRequestFacts[] | null;
932
944
  }
933
945
  /**
934
- * ErrDialogMaybeOpen's errDetails (from a plain
935
- * sendKeys without `expect_pane_sha256`, and from pause): the oldest request of the Spawn that
936
- * the agent's hooks have not proven gone (its fields and delivery facts: how agent-director's records
937
- * say it closed, `delivery` and `pane_answer`, and since when, `unproven_since`), the Spawn's
938
- * state, and the Spawn's other requests not proven gone, oldest first.
946
+ * ErrDialogMaybeOpen's errDetails (from a plain sendKeys without `expect_pane_sha256`, and
947
+ * from pause): the oldest request of the Spawn that holds the dialog (not proven gone, less a
948
+ * Cursor request of an earlier launch), with its fields and delivery facts (how
949
+ * agent-director's records say it closed, `delivery` and `pane_answer`, and since when,
950
+ * `unproven_since`), the Spawn's state, and the Spawn's other such requests (as
951
+ * `unproven_requests` lists them), oldest first.
939
952
  */
940
953
  export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
941
954
  state: string;
@@ -973,7 +986,11 @@ export interface PaneKeySentDetails {
973
986
  key_sent: true;
974
987
  request_token: string;
975
988
  }
976
- /** ErrSubmissionUnconfirmed's errDetails; submission remains unknown despite keys_sent. */
989
+ /**
990
+ * ErrSubmissionUnconfirmed's three-field errDetails for failed pending-Codex hook
991
+ * observation; submission remains unknown despite keys_sent. Native and paste
992
+ * outcomes use the generic errDetails record.
993
+ */
977
994
  export interface SubmissionUnconfirmedDetails {
978
995
  keys_sent: true;
979
996
  submission_confirmed: false;
@@ -1168,9 +1185,10 @@ export interface MakeTemplateResult {
1168
1185
  /** Filters for listing tracked agent rows. */
1169
1186
  export interface ListParams {
1170
1187
  /**
1171
- * Filter by state (multiple values OR together). The filter matches the displayed state,
1172
- * including `needs_intelligence` and `idle_screen` (a row showing either does not match its
1173
- * raw state), and is applied before `limit`.
1188
+ * Filter by state (multiple values OR together). A row matches when its `state` or its
1189
+ * `displayed_state` is one of the values, so `"working"` keeps a working row that shows
1190
+ * `idle_screen`, and `"idle_screen"` keeps it too; `"needs_intelligence"` is accepted and
1191
+ * matches only a row showing it. Applied before `limit`.
1174
1192
  */
1175
1193
  state?: string[];
1176
1194
  /** Filter by label k=v pairs (multiple entries AND together). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.16.0",
3
+ "version": "0.17.1",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],