agent-director 0.15.1 → 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 +24 -1
- 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 +119 -24
- 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
|
|
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
|
}
|
|
@@ -407,6 +432,15 @@ export interface SpawnParams {
|
|
|
407
432
|
* `ErrInstanceIdCollision`.
|
|
408
433
|
*/
|
|
409
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;
|
|
410
444
|
}
|
|
411
445
|
/**
|
|
412
446
|
* The launch result. The row is `pending` from its insert until
|
|
@@ -443,10 +477,30 @@ export interface StatusParams {
|
|
|
443
477
|
}
|
|
444
478
|
/** The row's reported lifecycle state. */
|
|
445
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;
|
|
446
498
|
/** Experimental context estimate for the current session. */
|
|
447
499
|
context: ContextReading;
|
|
448
500
|
/**
|
|
449
|
-
* 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.
|
|
450
504
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
451
505
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
452
506
|
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
@@ -456,15 +510,19 @@ export interface StatusResult {
|
|
|
456
510
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
457
511
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
458
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.
|
|
459
515
|
* Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
|
|
460
516
|
* can be newer: a refusal can name a state status does not show yet.
|
|
461
517
|
*/
|
|
462
518
|
state: string;
|
|
463
519
|
/**
|
|
464
520
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
465
|
-
* intermediates.
|
|
466
|
-
*
|
|
467
|
-
*
|
|
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.
|
|
468
526
|
*/
|
|
469
527
|
family_state: "working" | "waiting";
|
|
470
528
|
/**
|
|
@@ -500,12 +558,30 @@ export interface GetParams {
|
|
|
500
558
|
}
|
|
501
559
|
/** One tracked agent row, with its current session and request facts. */
|
|
502
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;
|
|
503
577
|
/** Experimental context estimate for the current session. */
|
|
504
578
|
context: ContextReading;
|
|
505
579
|
instance_id: string;
|
|
506
580
|
parent_id: string;
|
|
507
581
|
/**
|
|
508
|
-
* 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.
|
|
509
585
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
510
586
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
511
587
|
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
@@ -515,15 +591,22 @@ export interface GetResult {
|
|
|
515
591
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
516
592
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
517
593
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
518
|
-
*
|
|
519
|
-
*
|
|
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.
|
|
520
601
|
*/
|
|
521
602
|
state: string;
|
|
522
603
|
/**
|
|
523
604
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
524
|
-
* intermediates.
|
|
525
|
-
*
|
|
526
|
-
*
|
|
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.
|
|
527
610
|
*/
|
|
528
611
|
family_state: "working" | "waiting";
|
|
529
612
|
cwd: string;
|
|
@@ -548,6 +631,15 @@ export interface GetResult {
|
|
|
548
631
|
started_at: string;
|
|
549
632
|
/** Last hook UPSERT time (RFC3339). */
|
|
550
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;
|
|
551
643
|
/** Set when state moves to ended; omitted while live. */
|
|
552
644
|
ended_at?: string | null;
|
|
553
645
|
/**
|
|
@@ -590,9 +682,10 @@ export interface GetResult {
|
|
|
590
682
|
* only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
|
|
591
683
|
* working or ask_user while a request is still open: follow a tracked request with
|
|
592
684
|
* `getPermission`.
|
|
593
|
-
* Requests are never delayed by `[state] settle_ms`, so with it set
|
|
594
|
-
* state (even ended or missing) with open requests listed, or
|
|
595
|
-
* 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`).
|
|
596
689
|
*/
|
|
597
690
|
permission_requests: PermissionRequestInfo[];
|
|
598
691
|
/**
|
|
@@ -603,7 +696,8 @@ export interface GetResult {
|
|
|
603
696
|
* `unproven_since`. While it is not empty, a plain `sendKeys` without `expect_pane_sha256`,
|
|
604
697
|
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an earlier relay refusal). It follows the
|
|
605
698
|
* 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
|
|
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`).
|
|
607
701
|
*/
|
|
608
702
|
unproven_requests: PermissionRequestInfo[];
|
|
609
703
|
}
|
|
@@ -1074,8 +1168,9 @@ export interface MakeTemplateResult {
|
|
|
1074
1168
|
/** Filters for listing tracked agent rows. */
|
|
1075
1169
|
export interface ListParams {
|
|
1076
1170
|
/**
|
|
1077
|
-
* Filter by state (multiple values OR together).
|
|
1078
|
-
*
|
|
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`.
|
|
1079
1174
|
*/
|
|
1080
1175
|
state?: string[];
|
|
1081
1176
|
/** Filter by label k=v pairs (multiple entries AND together). */
|