agent-director 0.17.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.
Files changed (3) hide show
  1. package/README.md +25 -20
  2. package/dist/types.d.ts +68 -53
  3. package/package.json +1 -1
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,7 +431,8 @@ 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"`, a non-Cursor 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
438
  every request still holding the dialog, each with `unproven_since`. A request
@@ -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. |
package/dist/types.d.ts CHANGED
@@ -248,8 +248,8 @@ export interface ListRow {
248
248
  parent_id?: string;
249
249
  /**
250
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.
251
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
252
+ * keeps its row check_permission however long it waits.
253
253
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
254
254
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
255
255
  * prompt. A resumed pending row keeps its session id and history.
@@ -258,20 +258,26 @@ export interface ListRow {
258
258
  * off), this is the settled state: a state a hook wrote shows only once it has held for
259
259
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
260
260
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
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
261
  * Nothing marks a state as late. `family_state` settles independently. Fields such as
264
262
  * `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
265
263
  * live state, which can be newer: a refusal can name a state this field does not show yet.
266
264
  */
267
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";
268
274
  /**
269
275
  * Complete stored family: self and live descendants, including through retained terminal
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.
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.
275
281
  */
276
282
  family_state: "working" | "waiting";
277
283
  /** Canonicalized working directory. */
@@ -340,8 +346,8 @@ export interface ListRow {
340
346
  * follow a tracked request with `getPermission`. Requests are never delayed by
341
347
  * `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
342
348
  * (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`).
349
+ * to settle_ms; entering or leaving a `displayed_state` has no such bound (see
350
+ * `displayed_state`).
345
351
  */
346
352
  permission_requests: PermissionRequestInfo[];
347
353
  }
@@ -479,20 +485,25 @@ export interface StatusParams {
479
485
  /** The row's reported lifecycle state. */
480
486
  export interface StatusResult {
481
487
  /**
482
- * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
483
- * 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.
484
493
  */
485
- since?: string;
494
+ displayed_state?: "needs_intelligence" | "idle_screen";
486
495
  /**
487
- * The representative unanswered request (earliest qualifying fallback, lexical
488
- * 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.
489
498
  */
499
+ since?: string;
500
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
490
501
  request_token?: string;
491
- /** That request's tool; only while `needs_intelligence`. */
502
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
492
503
  tool_name?: string;
493
504
  /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
494
505
  unchanged_minutes?: number;
495
- /** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
506
+ /** Attach target, present only while `displayed_state` is. */
496
507
  tmux_session_name?: string;
497
508
  /** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
498
509
  idle_screen_availability: IdleScreenAvailability;
@@ -500,8 +511,8 @@ export interface StatusResult {
500
511
  context: ContextReading;
501
512
  /**
502
513
  * 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.
514
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
515
+ * keeps its row check_permission however long it waits.
505
516
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
506
517
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
507
518
  * prompt. A resumed pending row keeps its session id and history; a caller tells it
@@ -511,19 +522,17 @@ export interface StatusResult {
511
522
  * off), this is the settled state: a state a hook wrote shows only once it has held for
512
523
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
513
524
  * 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.
516
525
  * Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
517
526
  * can be newer: a refusal can name a state status does not show yet.
518
527
  */
519
528
  state: string;
520
529
  /**
521
530
  * Complete stored family: self and live descendants, including through retained terminal
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.
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.
527
536
  */
528
537
  family_state: "working" | "waiting";
529
538
  /**
@@ -560,16 +569,21 @@ export interface GetParams {
560
569
  /** One tracked agent row, with its current session and request facts. */
561
570
  export interface GetResult {
562
571
  /**
563
- * When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
564
- * 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.
565
577
  */
566
- since?: string;
578
+ displayed_state?: "needs_intelligence" | "idle_screen";
567
579
  /**
568
- * The representative unanswered request (earliest qualifying fallback, lexical
569
- * 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.
570
582
  */
583
+ since?: string;
584
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
571
585
  request_token?: string;
572
- /** That request's tool; only while `needs_intelligence`. */
586
+ /** Only while `displayed_state` is `needs_intelligence`; a permission request never sets it. */
573
587
  tool_name?: string;
574
588
  /** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
575
589
  unchanged_minutes?: number;
@@ -581,8 +595,8 @@ export interface GetResult {
581
595
  parent_id: string;
582
596
  /**
583
597
  * 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.
598
+ * never a Displayed State: `displayed_state` carries that beside it. A permission request
599
+ * keeps its row check_permission however long it waits.
586
600
  * pending means a launch (spawn, reuse or resume) is in progress and the agent has not
587
601
  * reported in yet (its SessionStart hook); it may be loading or waiting at a startup
588
602
  * prompt. A resumed pending row keeps its session id and history; a non-empty
@@ -592,10 +606,8 @@ export interface GetResult {
592
606
  * off), this is the settled state: a state a hook wrote shows only once it has held for
593
607
  * settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
594
608
  * shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
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
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
599
611
  * independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
600
612
  * that act on the row, follow its live state, which can be newer: a refusal can name a state
601
613
  * this field does not show yet.
@@ -603,11 +615,11 @@ export interface GetResult {
603
615
  state: string;
604
616
  /**
605
617
  * Complete stored family: self and live descendants, including through retained terminal
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.
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.
611
623
  */
612
624
  family_state: "working" | "waiting";
613
625
  cwd: string;
@@ -685,8 +697,8 @@ export interface GetResult {
685
697
  * `getPermission`.
686
698
  * Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
687
699
  * 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`).
700
+ * check_permission with `[]`, for up to settle_ms; entering or leaving a `displayed_state`
701
+ * has no such bound (see `displayed_state`).
690
702
  */
691
703
  permission_requests: PermissionRequestInfo[];
692
704
  /**
@@ -697,9 +709,7 @@ export interface GetResult {
697
709
  * or recorded answered outside it), each with `unproven_since`. While it is not empty, a plain
698
710
  * `sendKeys` without `expect_pane_sha256`, and a `pause`, reject (`ErrDialogMaybeOpen`, or an
699
711
  * 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`).
712
+ * `[state] settle_ms`, so with it set it can disagree with `state` for up to settle_ms.
703
713
  */
704
714
  unproven_requests: PermissionRequestInfo[];
705
715
  }
@@ -976,7 +986,11 @@ export interface PaneKeySentDetails {
976
986
  key_sent: true;
977
987
  request_token: string;
978
988
  }
979
- /** 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
+ */
980
994
  export interface SubmissionUnconfirmedDetails {
981
995
  keys_sent: true;
982
996
  submission_confirmed: false;
@@ -1171,9 +1185,10 @@ export interface MakeTemplateResult {
1171
1185
  /** Filters for listing tracked agent rows. */
1172
1186
  export interface ListParams {
1173
1187
  /**
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`.
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`.
1177
1192
  */
1178
1193
  state?: string[];
1179
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.17.0",
3
+ "version": "0.17.1",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],