agent-director 0.15.1 → 0.17.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
@@ -119,6 +119,10 @@ Cursor reports `"failed"` for unsupported pre-trust or `"skipped"` for its saved
119
119
  opt-out, never a validated `"ok"`; see
120
120
  [Cursor launch settings](../../docs/settings.md#cursor-launch-settings).
121
121
 
122
+ `idle_screen_timeout_seconds` gives the row its own `idle_screen` timeout in
123
+ whole seconds (`0`, `null` or omitted for none); its range and lifecycle are
124
+ in [Configuration](../../docs/configuration.md#idle-screen-timeout-state).
125
+
122
126
  For all agents, same-agent reuse retains current-life session history and subagent records;
123
127
  switching agents starts another life, including when switching back.
124
128
  `resume` continues only the recorded agent's latest reported session and
@@ -149,10 +153,27 @@ console.log(result.state);
149
153
 
150
154
  `StatusResult`, `GetResult` and each `ListRow` expose
151
155
  `family_state: "working" | "waiting"`, separately from `state`.
152
- [Usage](../../docs/usage.md#family-state) defines membership and raw
156
+ [Usage](../../docs/usage.md#family-state) defines membership and
153
157
  aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
154
158
  defines reporting limits.
155
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
167
+ `ListRow` carries `idle_screen_availability` (`IdleScreenAvailability`:
168
+ `"available"` for Claude and Codex, `"unavailable"` for Cursor).
169
+ The [caller contract](../../docs/caller-contract.md#needs-intelligence-and-idle-screen-rows)
170
+ defines the states, fields, omissions and detection.
171
+
172
+ `GetResult` and each `ListRow` carry `state_changed_at: string`, when the raw
173
+ state last changed; `StatusResult` does not. The
174
+ [caller contract](../../docs/caller-contract.md#state-change-time) defines it
175
+ and how it differs from `last_seen_at`, the settled `state` and `since`.
176
+
156
177
  `status`, `get` and `list` use `[state] settle_ms` in the CLI's
157
178
  `~/.config/agent-director/config.toml` for [independent state and family
158
179
  settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
@@ -170,6 +191,8 @@ for (const spawn of result.spawns) {
170
191
  ```
171
192
 
172
193
  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`.
173
196
 
174
197
  ### listSubagents
175
198
 
@@ -404,10 +427,10 @@ tool ran or Cursor supplied validated exact matching invocation proof under
404
427
  MCP invocation that proves dialog closure without inferring execution or changing
405
428
  decision, delivery or pane-answer fields;
406
429
  `"turn_end"`, an eligible main request's turn ended under the age and identity
407
- guards; or `"agent_gone"`, the agent ended) say when and how the request's
430
+ guards; or `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
408
431
  dialog was proven gone; `"delivered"` and a pane answer are
409
432
  agent-director's own records, not proof. `get`'s `unproven_requests` lists
410
- every request not yet proven gone, each with `unproven_since`. A request
433
+ every request still holding the dialog, each with `unproven_since`. A request
411
434
  that reads `"delivered"` or closed at the pane can remain unproven; its dialog
412
435
  may still be there. Handling is in the
413
436
  [caller contract](../../docs/caller-contract.md#permission-relay).
@@ -669,7 +692,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
669
692
  |---|---|
670
693
  | `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). |
671
694
  | `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`. |
672
- | `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). |
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 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). |
673
696
  | `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). |
674
697
  | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
675
698
  | `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/index.d.ts CHANGED
@@ -10,6 +10,6 @@ ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after val
10
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";
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, } from "./types.js";
13
+ export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, IdleScreenAvailability, } from "./types.js";
14
14
  export type { PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
15
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";
package/dist/index.js CHANGED
@@ -1020,6 +1020,9 @@ function buildSpawn(p) {
1020
1020
  f.push("--no-pre-trust");
1021
1021
  if (p.reuse_finished === true)
1022
1022
  f.push("--reuse-finished");
1023
+ const timeout = p.idle_screen_timeout_seconds;
1024
+ if (timeout !== undefined && timeout !== null && timeout !== 0)
1025
+ f.push("--idle-screen-timeout-seconds", String(timeout));
1023
1026
  if (p.label) {
1024
1027
  for (const lv of p.label)
1025
1028
  f.push("--label", lv);
@@ -1,12 +1,9 @@
1
1
  /**
2
2
  * platformResolve.ts — Bun runtime-version guard.
3
3
  *
4
- * The vendored-binary resolution logic that used to live here is gone as of
5
- * b.ue3 (Stream A). Discovery is now run by src/internal/discovery.ts
6
- * against the system install (HOME → PATH). The only piece this file still
7
- * owns is the Bun-runtime-version check, fired at the top of every
8
- * Client.create() and resolveSystemBinary() call before any filesystem stat
9
- * (SR-7.7).
4
+ * Checks the Bun runtime version at the top of every Client.create() and
5
+ * resolveSystemBinary() call, before any filesystem stat (SR-7.7). Binary
6
+ * discovery lives in src/internal/discovery.ts.
10
7
  *
11
8
  * Internal — not re-exported from src/index.ts.
12
9
  */
@@ -23,11 +23,6 @@
23
23
  * - ErrCallerCwdUnreachable — caller's process.cwd() is gone at construction (b.cot).
24
24
  * - ErrSystemInstallDisappeared — binary gone at verb-dispatch time, after valid construction (b.xht).
25
25
  *
26
- * Removed in b.ue3 (vendored-binary surface dropped):
27
- * - ErrUnsupportedPlatform
28
- * - ErrPlatformPackageMissing
29
- * - ErrCliNotExecutable
30
- *
31
26
  * When adding a new TS-only subclass: add its name here AND add a comment in
32
27
  * src/errors.ts near the subclass cross-referencing this allow-list.
33
28
  */
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. */
@@ -232,14 +233,23 @@ export interface PermissionRequestInfo extends RequestDelivery {
232
233
  /** The recorded verdict's decision_reason; null when none is recorded. */
233
234
  decision_reason: string | null;
234
235
  }
236
+ /**
237
+ * 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.
239
+ */
240
+ export type IdleScreenAvailability = "available" | "unavailable";
235
241
  /** One Spawn row returned by the list verb. */
236
242
  export interface ListRow {
243
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
244
+ idle_screen_availability: IdleScreenAvailability;
237
245
  /** Stable Spawn id. */
238
246
  instance_id: string;
239
247
  /** Parent Spawn id (omitted when launched from a plain shell). */
240
248
  parent_id?: string;
241
249
  /**
242
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
250
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
251
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
252
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
243
253
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
244
254
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
245
255
  * prompt. A resumed pending row keeps its session id and history.
@@ -248,15 +258,20 @@ export interface ListRow {
248
258
  * off), this is the settled state: a state a hook wrote shows only once it has held for
249
259
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
250
260
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
251
- * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
252
- * its live state, which can be newer: a refusal can name a state this field does not show yet.
261
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
262
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
263
+ * Nothing marks a state as late. `family_state` settles independently. Fields such as
264
+ * `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
265
+ * live state, which can be newer: a refusal can name a state this field does not show yet.
253
266
  */
254
267
  state: string;
255
268
  /**
256
269
  * Complete stored family: self and live descendants, including through retained terminal
257
- * intermediates. Waiting means every live member is waiting, or no live members remain.
258
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
259
- * independently of `state`. This report does not establish readiness or task success.
270
+ * intermediates. A live member counts as working while its raw state is not waiting or its
271
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
272
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
273
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
274
+ * not establish readiness or task success.
260
275
  */
261
276
  family_state: "working" | "waiting";
262
277
  /** Canonicalized working directory. */
@@ -273,6 +288,15 @@ export interface ListRow {
273
288
  started_at: string;
274
289
  /** Most recent hook UPSERT time (RFC3339). */
275
290
  last_seen_at: string;
291
+ /**
292
+ * When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
293
+ * Soft refreshes and same-state writes leave it; `state` may still show the earlier
294
+ * settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
295
+ * agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
296
+ * or list finds lost reads `missing` at once; this moves when that mark is stored, which
297
+ * can be after the read that first shows `missing`.
298
+ */
299
+ state_changed_at: string;
276
300
  /** Set when state moves to ended (omitted while live). */
277
301
  ended_at?: string | null;
278
302
  /**
@@ -314,8 +338,10 @@ export interface ListRow {
314
338
  * delivery facts; populated only when the row's live state is check_permission, `[]`
315
339
  * otherwise. A row can read waiting, working or ask_user while a request is still open:
316
340
  * follow a tracked request with `getPermission`. Requests are never delayed by
317
- * `[state] settle_ms`, so with it set a row can also read any state (even ended or missing)
318
- * with open requests listed, or check_permission with `[]`, for up to settle_ms.
341
+ * `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
342
+ * (even ended or missing) with open requests listed, or check_permission with `[]`, for up
343
+ * to settle_ms; entering or leaving `needs_intelligence` or `idle_screen` has no such bound
344
+ * (see `state`).
319
345
  */
320
346
  permission_requests: PermissionRequestInfo[];
321
347
  }
@@ -407,6 +433,15 @@ export interface SpawnParams {
407
433
  * `ErrInstanceIdCollision`.
408
434
  */
409
435
  reuse_finished?: boolean;
436
+ /**
437
+ * This row's `idle_screen` timeout in whole seconds, 1 to 9223372036, used by every
438
+ * `status`, `get` and `list` in place of `[state] idle_screen_timeout_seconds`.
439
+ * `0`, `null` or omitted gives no override. A negative, fractional, non-numeric or larger
440
+ * value is refused with `ErrInvalidFlags` before anything is written or launched. Recorded
441
+ * on the row: `resume` keeps it; the next spawn or reuse replaces it, clearing it when that
442
+ * call gives none. Cursor rows keep it, but `idle_screen` is unavailable for them.
443
+ */
444
+ idle_screen_timeout_seconds?: number | null;
410
445
  }
411
446
  /**
412
447
  * The launch result. The row is `pending` from its insert until
@@ -443,10 +478,30 @@ export interface StatusParams {
443
478
  }
444
479
  /** The row's reported lifecycle state. */
445
480
  export interface StatusResult {
481
+ /**
482
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
483
+ * only while `needs_intelligence` or `idle_screen` is displayed.
484
+ */
485
+ since?: string;
486
+ /**
487
+ * The representative unanswered request (earliest qualifying fallback, lexical
488
+ * request-token tie break); only while `needs_intelligence`.
489
+ */
490
+ request_token?: string;
491
+ /** That request's tool; only while `needs_intelligence`. */
492
+ tool_name?: string;
493
+ /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
494
+ unchanged_minutes?: number;
495
+ /** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
496
+ tmux_session_name?: string;
497
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
498
+ idle_screen_availability: IdleScreenAvailability;
446
499
  /** Experimental context estimate for the current session. */
447
500
  context: ContextReading;
448
501
  /**
449
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
502
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
503
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
504
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
450
505
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
451
506
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
452
507
  * prompt. A resumed pending row keeps its session id and history; a caller tells it
@@ -456,15 +511,19 @@ export interface StatusResult {
456
511
  * off), this is the settled state: a state a hook wrote shows only once it has held for
457
512
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
458
513
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
514
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
515
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
459
516
  * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
460
517
  * can be newer: a refusal can name a state status does not show yet.
461
518
  */
462
519
  state: string;
463
520
  /**
464
521
  * Complete stored family: self and live descendants, including through retained terminal
465
- * intermediates. Waiting means every live member is waiting, or no live members remain.
466
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
467
- * independently of `state`. This report does not establish readiness or task success.
522
+ * intermediates. A live member counts as working while its raw state is not waiting or its
523
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
524
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
525
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
526
+ * not establish readiness or task success.
468
527
  */
469
528
  family_state: "working" | "waiting";
470
529
  /**
@@ -500,12 +559,30 @@ export interface GetParams {
500
559
  }
501
560
  /** One tracked agent row, with its current session and request facts. */
502
561
  export interface GetResult {
562
+ /**
563
+ * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
564
+ * only while `needs_intelligence` or `idle_screen` is displayed.
565
+ */
566
+ since?: string;
567
+ /**
568
+ * The representative unanswered request (earliest qualifying fallback, lexical
569
+ * request-token tie break); only while `needs_intelligence`.
570
+ */
571
+ request_token?: string;
572
+ /** That request's tool; only while `needs_intelligence`. */
573
+ tool_name?: string;
574
+ /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
575
+ unchanged_minutes?: number;
576
+ /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
577
+ idle_screen_availability: IdleScreenAvailability;
503
578
  /** Experimental context estimate for the current session. */
504
579
  context: ContextReading;
505
580
  instance_id: string;
506
581
  parent_id: string;
507
582
  /**
508
- * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
583
+ * Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
584
+ * or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
585
+ * or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
509
586
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
510
587
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
511
588
  * prompt. A resumed pending row keeps its session id and history; a non-empty
@@ -515,15 +592,22 @@ export interface GetResult {
515
592
  * off), this is the settled state: a state a hook wrote shows only once it has held for
516
593
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
517
594
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
518
- * Nothing marks a state as late. The row's other fields, and the verbs that act on it, follow
519
- * its live state, which can be newer: a refusal can name a state this field does not show yet.
595
+ * Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
596
+ * times settle_ms from the read that commits its candidate; a later read commits the change.
597
+ * Nothing marks a state as late. While an exit or direct move settles, `since` and that
598
+ * state's detail keep the previous display's committed values, and `family_state` settles
599
+ * independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
600
+ * that act on the row, follow its live state, which can be newer: a refusal can name a state
601
+ * this field does not show yet.
520
602
  */
521
603
  state: string;
522
604
  /**
523
605
  * Complete stored family: self and live descendants, including through retained terminal
524
- * intermediates. Waiting means every live member is waiting, or no live members remain.
525
- * Uses raw member states and settles once in either direction with `[state] settle_ms`,
526
- * independently of `state`. This report does not establish readiness or task success.
606
+ * intermediates. A live member counts as working while its raw state is not waiting or its
607
+ * committed display is `needs_intelligence` or `idle_screen`, until that display's exit
608
+ * commits. Waiting means no member counts as working, or no live members remain. Settles once
609
+ * in either direction with `[state] settle_ms`, independently of `state`. This report does
610
+ * not establish readiness or task success.
527
611
  */
528
612
  family_state: "working" | "waiting";
529
613
  cwd: string;
@@ -548,6 +632,15 @@ export interface GetResult {
548
632
  started_at: string;
549
633
  /** Last hook UPSERT time (RFC3339). */
550
634
  last_seen_at: string;
635
+ /**
636
+ * When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
637
+ * Soft refreshes and same-state writes leave it; `state` may still show the earlier
638
+ * settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
639
+ * agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
640
+ * or list finds lost reads `missing` at once; this moves when that mark is stored, which
641
+ * can be after the read that first shows `missing`.
642
+ */
643
+ state_changed_at: string;
551
644
  /** Set when state moves to ended; omitted while live. */
552
645
  ended_at?: string | null;
553
646
  /**
@@ -590,20 +683,23 @@ export interface GetResult {
590
683
  * only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
591
684
  * working or ask_user while a request is still open: follow a tracked request with
592
685
  * `getPermission`.
593
- * Requests are never delayed by `[state] settle_ms`, so with it set a row can also read any
594
- * state (even ended or missing) with open requests listed, or check_permission with `[]`, for
595
- * up to settle_ms.
686
+ * Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
687
+ * settling can also show any state (even ended or missing) with open requests listed, or
688
+ * check_permission with `[]`, for up to settle_ms; entering or leaving `needs_intelligence`
689
+ * or `idle_screen` has no such bound (see `state`).
596
690
  */
597
691
  permission_requests: PermissionRequestInfo[];
598
692
  /**
599
- * Every permission request of the row that the agent's hooks have not proven gone (`proven_gone_at`
600
- * null), oldest first, in any live state but ended and missing (`[]` on those). Unlike
601
- * `permission_requests` it also lists requests agent-director's records read closed
602
- * (delivered, answered at the pane, or recorded answered outside it), each with
603
- * `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
604
- * and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
605
- * row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
606
- * with `state` for up to settle_ms.
693
+ * Every permission request of the row that the agent's hooks have not proven gone
694
+ * (`proven_gone_at` null), less Cursor requests of an earlier launch of the row, oldest first,
695
+ * in any live state but ended and missing (`[]` on those). Unlike `permission_requests` it
696
+ * also lists requests agent-director's records read closed (delivered, answered at the pane,
697
+ * or recorded answered outside it), each with `unproven_since`. While it is not empty, a plain
698
+ * `sendKeys` without `expect_pane_sha256`, and a `pause`, reject (`ErrDialogMaybeOpen`, or an
699
+ * earlier relay refusal). It follows the row's live state and is never delayed by
700
+ * `[state] settle_ms`, so with it set it can disagree with `state` for up to settle_ms under
701
+ * ordinary raw-state settling, and without that bound while entering or leaving
702
+ * `needs_intelligence` or `idle_screen` (see `state`).
607
703
  */
608
704
  unproven_requests: PermissionRequestInfo[];
609
705
  }
@@ -837,11 +933,12 @@ export interface RelayFallenBackDetails extends PermissionRequestInfo {
837
933
  open_requests: OpenRequestFacts[] | null;
838
934
  }
839
935
  /**
840
- * ErrDialogMaybeOpen's errDetails (from a plain
841
- * sendKeys without `expect_pane_sha256`, and from pause): the oldest request of the Spawn that
842
- * the agent's hooks have not proven gone (its fields and delivery facts: how agent-director's records
843
- * say it closed, `delivery` and `pane_answer`, and since when, `unproven_since`), the Spawn's
844
- * state, and the Spawn's other requests not proven gone, oldest first.
936
+ * ErrDialogMaybeOpen's errDetails (from a plain sendKeys without `expect_pane_sha256`, and
937
+ * from pause): the oldest request of the Spawn that holds the dialog (not proven gone, less a
938
+ * Cursor request of an earlier launch), with its fields and delivery facts (how
939
+ * agent-director's records say it closed, `delivery` and `pane_answer`, and since when,
940
+ * `unproven_since`), the Spawn's state, and the Spawn's other such requests (as
941
+ * `unproven_requests` lists them), oldest first.
845
942
  */
846
943
  export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
847
944
  state: string;
@@ -1074,8 +1171,9 @@ export interface MakeTemplateResult {
1074
1171
  /** Filters for listing tracked agent rows. */
1075
1172
  export interface ListParams {
1076
1173
  /**
1077
- * Filter by state (multiple values OR together). With `[state] settle_ms` set it matches the
1078
- * settled state each row's `state` shows, before `limit` applies.
1174
+ * Filter by state (multiple values OR together). The filter matches the displayed state,
1175
+ * including `needs_intelligence` and `idle_screen` (a row showing either does not match its
1176
+ * raw state), and is applied before `limit`.
1079
1177
  */
1080
1178
  state?: string[];
1081
1179
  /** 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.15.1",
3
+ "version": "0.17.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],