agent-director 0.15.0 → 0.16.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 +25 -2
- package/dist/index.d.ts +1 -1
- package/dist/index.js +3 -0
- package/dist/internal/platformResolve.d.ts +3 -6
- package/dist/internal/tsOnlyErrors.d.ts +0 -5
- package/dist/types.d.ts +122 -26
- package/package.json +1 -1
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
|
|
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
|
|
|
@@ -617,7 +640,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
617
640
|
| Error | When it fires |
|
|
618
641
|
|---|---|
|
|
619
642
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
620
|
-
| `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.
|
|
643
|
+
| `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst`, `features.hooks` or its alias `features.codex_hooks`, `--disable hooks` or `--disable codex_hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
|
|
621
644
|
| `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"`, `"codex"` or `"cursor"`), or put one in the template. |
|
|
622
645
|
| `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
|
|
623
646
|
| `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
|
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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
|
@@ -232,14 +232,23 @@ export interface PermissionRequestInfo extends RequestDelivery {
|
|
|
232
232
|
/** The recorded verdict's decision_reason; null when none is recorded. */
|
|
233
233
|
decision_reason: string | null;
|
|
234
234
|
}
|
|
235
|
+
/**
|
|
236
|
+
* Whether `idle_screen` can apply to a row's agent: `"available"` for Claude and Codex,
|
|
237
|
+
* `"unavailable"` for Cursor. A capability outcome, never a state.
|
|
238
|
+
*/
|
|
239
|
+
export type IdleScreenAvailability = "available" | "unavailable";
|
|
235
240
|
/** One Spawn row returned by the list verb. */
|
|
236
241
|
export interface ListRow {
|
|
242
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
243
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
237
244
|
/** Stable Spawn id. */
|
|
238
245
|
instance_id: string;
|
|
239
246
|
/** Parent Spawn id (omitted when launched from a plain shell). */
|
|
240
247
|
parent_id?: string;
|
|
241
248
|
/**
|
|
242
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
249
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
250
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
251
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
243
252
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
244
253
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
245
254
|
* prompt. A resumed pending row keeps its session id and history.
|
|
@@ -248,15 +257,20 @@ export interface ListRow {
|
|
|
248
257
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
249
258
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
250
259
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
251
|
-
*
|
|
252
|
-
*
|
|
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
|
+
* Nothing marks a state as late. `family_state` settles independently. Fields such as
|
|
263
|
+
* `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
|
|
264
|
+
* live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
253
265
|
*/
|
|
254
266
|
state: string;
|
|
255
267
|
/**
|
|
256
268
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
257
|
-
* intermediates.
|
|
258
|
-
*
|
|
259
|
-
*
|
|
269
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
270
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
271
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
272
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
273
|
+
* not establish readiness or task success.
|
|
260
274
|
*/
|
|
261
275
|
family_state: "working" | "waiting";
|
|
262
276
|
/** Canonicalized working directory. */
|
|
@@ -273,6 +287,15 @@ export interface ListRow {
|
|
|
273
287
|
started_at: string;
|
|
274
288
|
/** Most recent hook UPSERT time (RFC3339). */
|
|
275
289
|
last_seen_at: string;
|
|
290
|
+
/**
|
|
291
|
+
* When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
|
|
292
|
+
* Soft refreshes and same-state writes leave it; `state` may still show the earlier
|
|
293
|
+
* settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
|
|
294
|
+
* agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
|
|
295
|
+
* or list finds lost reads `missing` at once; this moves when that mark is stored, which
|
|
296
|
+
* can be after the read that first shows `missing`.
|
|
297
|
+
*/
|
|
298
|
+
state_changed_at: string;
|
|
276
299
|
/** Set when state moves to ended (omitted while live). */
|
|
277
300
|
ended_at?: string | null;
|
|
278
301
|
/**
|
|
@@ -314,8 +337,10 @@ export interface ListRow {
|
|
|
314
337
|
* delivery facts; populated only when the row's live state is check_permission, `[]`
|
|
315
338
|
* otherwise. A row can read waiting, working or ask_user while a request is still open:
|
|
316
339
|
* follow a tracked request with `getPermission`. Requests are never delayed by
|
|
317
|
-
* `[state] settle_ms`, so with it set
|
|
318
|
-
* with open requests listed, or check_permission with `[]`, for up
|
|
340
|
+
* `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
|
|
341
|
+
* (even ended or missing) with open requests listed, or check_permission with `[]`, for up
|
|
342
|
+
* to settle_ms; entering or leaving `needs_intelligence` or `idle_screen` has no such bound
|
|
343
|
+
* (see `state`).
|
|
319
344
|
*/
|
|
320
345
|
permission_requests: PermissionRequestInfo[];
|
|
321
346
|
}
|
|
@@ -366,8 +391,9 @@ export interface SpawnParams {
|
|
|
366
391
|
* removed tokens appear in `dropped_args`; the agent starts fresh and resumes nothing.
|
|
367
392
|
* Exact denied long tokens owned as option values always refuse. For codex, a Codex subcommand in
|
|
368
393
|
* command position, `--remote`, `--remote-auth-token-env`, `-c`/`--config` keys at, above or
|
|
369
|
-
* under `hooks`, `tui.disable_paste_burst
|
|
370
|
-
*
|
|
394
|
+
* under `hooks`, `tui.disable_paste_burst`, `features.hooks` or its alias
|
|
395
|
+
* `features.codex_hooks`, and `--disable hooks` or `codex_hooks` are refused
|
|
396
|
+
* (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
|
|
371
397
|
* default_mode_request_user_input` and the question-tool keys are refused too. agent-director
|
|
372
398
|
* adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
|
|
373
399
|
* `--enable write_stdin_approval` when the arguments already carry one before any `--`;
|
|
@@ -406,6 +432,15 @@ export interface SpawnParams {
|
|
|
406
432
|
* `ErrInstanceIdCollision`.
|
|
407
433
|
*/
|
|
408
434
|
reuse_finished?: boolean;
|
|
435
|
+
/**
|
|
436
|
+
* This row's `idle_screen` timeout in whole seconds, 1 to 9223372036, used by every
|
|
437
|
+
* `status`, `get` and `list` in place of `[state] idle_screen_timeout_seconds`.
|
|
438
|
+
* `0`, `null` or omitted gives no override. A negative, fractional, non-numeric or larger
|
|
439
|
+
* value is refused with `ErrInvalidFlags` before anything is written or launched. Recorded
|
|
440
|
+
* on the row: `resume` keeps it; the next spawn or reuse replaces it, clearing it when that
|
|
441
|
+
* call gives none. Cursor rows keep it, but `idle_screen` is unavailable for them.
|
|
442
|
+
*/
|
|
443
|
+
idle_screen_timeout_seconds?: number | null;
|
|
409
444
|
}
|
|
410
445
|
/**
|
|
411
446
|
* The launch result. The row is `pending` from its insert until
|
|
@@ -442,10 +477,30 @@ export interface StatusParams {
|
|
|
442
477
|
}
|
|
443
478
|
/** The row's reported lifecycle state. */
|
|
444
479
|
export interface StatusResult {
|
|
480
|
+
/**
|
|
481
|
+
* When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
|
|
482
|
+
* only while `needs_intelligence` or `idle_screen` is displayed.
|
|
483
|
+
*/
|
|
484
|
+
since?: string;
|
|
485
|
+
/**
|
|
486
|
+
* The representative unanswered request (earliest qualifying fallback, lexical
|
|
487
|
+
* request-token tie break); only while `needs_intelligence`.
|
|
488
|
+
*/
|
|
489
|
+
request_token?: string;
|
|
490
|
+
/** That request's tool; only while `needs_intelligence`. */
|
|
491
|
+
tool_name?: string;
|
|
492
|
+
/** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
|
|
493
|
+
unchanged_minutes?: number;
|
|
494
|
+
/** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
|
|
495
|
+
tmux_session_name?: string;
|
|
496
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
497
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
445
498
|
/** Experimental context estimate for the current session. */
|
|
446
499
|
context: ContextReading;
|
|
447
500
|
/**
|
|
448
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
501
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
502
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
503
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
449
504
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
450
505
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
451
506
|
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
@@ -455,15 +510,19 @@ export interface StatusResult {
|
|
|
455
510
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
456
511
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
457
512
|
* 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.
|
|
458
515
|
* Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
|
|
459
516
|
* can be newer: a refusal can name a state status does not show yet.
|
|
460
517
|
*/
|
|
461
518
|
state: string;
|
|
462
519
|
/**
|
|
463
520
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
464
|
-
* intermediates.
|
|
465
|
-
*
|
|
466
|
-
*
|
|
521
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
522
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
523
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
524
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
525
|
+
* not establish readiness or task success.
|
|
467
526
|
*/
|
|
468
527
|
family_state: "working" | "waiting";
|
|
469
528
|
/**
|
|
@@ -499,12 +558,30 @@ export interface GetParams {
|
|
|
499
558
|
}
|
|
500
559
|
/** One tracked agent row, with its current session and request facts. */
|
|
501
560
|
export interface GetResult {
|
|
561
|
+
/**
|
|
562
|
+
* When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
|
|
563
|
+
* only while `needs_intelligence` or `idle_screen` is displayed.
|
|
564
|
+
*/
|
|
565
|
+
since?: string;
|
|
566
|
+
/**
|
|
567
|
+
* The representative unanswered request (earliest qualifying fallback, lexical
|
|
568
|
+
* request-token tie break); only while `needs_intelligence`.
|
|
569
|
+
*/
|
|
570
|
+
request_token?: string;
|
|
571
|
+
/** That request's tool; only while `needs_intelligence`. */
|
|
572
|
+
tool_name?: string;
|
|
573
|
+
/** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
|
|
574
|
+
unchanged_minutes?: number;
|
|
575
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
576
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
502
577
|
/** Experimental context estimate for the current session. */
|
|
503
578
|
context: ContextReading;
|
|
504
579
|
instance_id: string;
|
|
505
580
|
parent_id: string;
|
|
506
581
|
/**
|
|
507
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
582
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
583
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
584
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
508
585
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
509
586
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
510
587
|
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
@@ -514,15 +591,22 @@ export interface GetResult {
|
|
|
514
591
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
515
592
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
516
593
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
517
|
-
*
|
|
518
|
-
*
|
|
594
|
+
* Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
|
|
595
|
+
* times settle_ms from the read that commits its candidate; a later read commits the change.
|
|
596
|
+
* Nothing marks a state as late. While an exit or direct move settles, `since` and that
|
|
597
|
+
* state's detail keep the previous display's committed values, and `family_state` settles
|
|
598
|
+
* independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
|
|
599
|
+
* that act on the row, follow its live state, which can be newer: a refusal can name a state
|
|
600
|
+
* this field does not show yet.
|
|
519
601
|
*/
|
|
520
602
|
state: string;
|
|
521
603
|
/**
|
|
522
604
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
523
|
-
* intermediates.
|
|
524
|
-
*
|
|
525
|
-
*
|
|
605
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
606
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
607
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
608
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
609
|
+
* not establish readiness or task success.
|
|
526
610
|
*/
|
|
527
611
|
family_state: "working" | "waiting";
|
|
528
612
|
cwd: string;
|
|
@@ -547,6 +631,15 @@ export interface GetResult {
|
|
|
547
631
|
started_at: string;
|
|
548
632
|
/** Last hook UPSERT time (RFC3339). */
|
|
549
633
|
last_seen_at: string;
|
|
634
|
+
/**
|
|
635
|
+
* When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
|
|
636
|
+
* Soft refreshes and same-state writes leave it; `state` may still show the earlier
|
|
637
|
+
* settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
|
|
638
|
+
* agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
|
|
639
|
+
* or list finds lost reads `missing` at once; this moves when that mark is stored, which
|
|
640
|
+
* can be after the read that first shows `missing`.
|
|
641
|
+
*/
|
|
642
|
+
state_changed_at: string;
|
|
550
643
|
/** Set when state moves to ended; omitted while live. */
|
|
551
644
|
ended_at?: string | null;
|
|
552
645
|
/**
|
|
@@ -589,9 +682,10 @@ export interface GetResult {
|
|
|
589
682
|
* only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
|
|
590
683
|
* working or ask_user while a request is still open: follow a tracked request with
|
|
591
684
|
* `getPermission`.
|
|
592
|
-
* Requests are never delayed by `[state] settle_ms`, so with it set
|
|
593
|
-
* state (even ended or missing) with open requests listed, or
|
|
594
|
-
* up to settle_ms
|
|
685
|
+
* Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
|
|
686
|
+
* settling can also show any state (even ended or missing) with open requests listed, or
|
|
687
|
+
* check_permission with `[]`, for up to settle_ms; entering or leaving `needs_intelligence`
|
|
688
|
+
* or `idle_screen` has no such bound (see `state`).
|
|
595
689
|
*/
|
|
596
690
|
permission_requests: PermissionRequestInfo[];
|
|
597
691
|
/**
|
|
@@ -602,7 +696,8 @@ export interface GetResult {
|
|
|
602
696
|
* `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
|
|
603
697
|
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
|
|
604
698
|
* row's live state and is never delayed by `[state] settle_ms`, so with it set it can disagree
|
|
605
|
-
* with `state` for up to settle_ms
|
|
699
|
+
* with `state` for up to settle_ms under ordinary raw-state settling, and without that bound
|
|
700
|
+
* while entering or leaving `needs_intelligence` or `idle_screen` (see `state`).
|
|
606
701
|
*/
|
|
607
702
|
unproven_requests: PermissionRequestInfo[];
|
|
608
703
|
}
|
|
@@ -1073,8 +1168,9 @@ export interface MakeTemplateResult {
|
|
|
1073
1168
|
/** Filters for listing tracked agent rows. */
|
|
1074
1169
|
export interface ListParams {
|
|
1075
1170
|
/**
|
|
1076
|
-
* Filter by state (multiple values OR together).
|
|
1077
|
-
*
|
|
1171
|
+
* Filter by state (multiple values OR together). The filter matches the displayed state,
|
|
1172
|
+
* including `needs_intelligence` and `idle_screen` (a row showing either does not match its
|
|
1173
|
+
* raw state), and is applied before `limit`.
|
|
1078
1174
|
*/
|
|
1079
1175
|
state?: string[];
|
|
1080
1176
|
/** Filter by label k=v pairs (multiple entries AND together). */
|