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 +27 -22
- package/dist/errors.d.ts +3 -2
- package/dist/types.d.ts +87 -69
- 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
|
|
161
|
-
|
|
162
|
-
`
|
|
163
|
-
|
|
164
|
-
`
|
|
165
|
-
|
|
166
|
-
|
|
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
|
|
195
|
-
|
|
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
|
|
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
|
|
269
|
+
`SubmissionUnconfirmedDetails` describes only a failed fallback hook observation:
|
|
268
270
|
`keys_sent: true`, `submission_confirmed: false` and `row_state`. Native
|
|
269
|
-
uncertainty
|
|
270
|
-
`
|
|
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
|
|
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
|
|
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
|
|
580
|
-
Native
|
|
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
|
|
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
|
|
368
|
-
* agent-director's records say of it; its dialog may still be on the pane.
|
|
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,
|
|
215
|
-
*
|
|
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
|
-
*
|
|
251
|
-
*
|
|
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
|
|
270
|
-
*
|
|
271
|
-
*
|
|
272
|
-
*
|
|
273
|
-
*
|
|
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
|
|
343
|
-
*
|
|
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
|
-
*
|
|
482
|
-
*
|
|
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
|
-
|
|
494
|
+
displayed_state?: "needs_intelligence" | "idle_screen";
|
|
485
495
|
/**
|
|
486
|
-
*
|
|
487
|
-
*
|
|
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
|
-
/**
|
|
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 `
|
|
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
|
-
*
|
|
503
|
-
*
|
|
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
|
|
522
|
-
*
|
|
523
|
-
*
|
|
524
|
-
*
|
|
525
|
-
*
|
|
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
|
-
*
|
|
563
|
-
*
|
|
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
|
-
|
|
578
|
+
displayed_state?: "needs_intelligence" | "idle_screen";
|
|
566
579
|
/**
|
|
567
|
-
*
|
|
568
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
584
|
-
*
|
|
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
|
-
*
|
|
595
|
-
*
|
|
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
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
609
|
-
*
|
|
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 `
|
|
688
|
-
*
|
|
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
|
|
693
|
-
* null),
|
|
694
|
-
*
|
|
695
|
-
* (delivered, answered at the pane,
|
|
696
|
-
* `unproven_since`. While it is not empty, a plain
|
|
697
|
-
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an
|
|
698
|
-
* row's live state and is never delayed by
|
|
699
|
-
*
|
|
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
|
-
*
|
|
936
|
-
*
|
|
937
|
-
* say it closed, `delivery` and `pane_answer`, and since when,
|
|
938
|
-
* state, and the Spawn's other requests
|
|
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
|
-
/**
|
|
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).
|
|
1172
|
-
*
|
|
1173
|
-
*
|
|
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). */
|