agent-director 0.15.1 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -4
- package/dist/errors.d.ts +3 -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 +139 -41
- 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
|
|
|
@@ -404,10 +427,10 @@ tool ran or Cursor supplied validated exact matching invocation proof under
|
|
|
404
427
|
MCP invocation that proves dialog closure without inferring execution or changing
|
|
405
428
|
decision, delivery or pane-answer fields;
|
|
406
429
|
`"turn_end"`, an eligible main request's turn ended under the age and identity
|
|
407
|
-
guards; or `"agent_gone"`,
|
|
430
|
+
guards; or `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
|
|
408
431
|
dialog was proven gone; `"delivered"` and a pane answer are
|
|
409
432
|
agent-director's own records, not proof. `get`'s `unproven_requests` lists
|
|
410
|
-
every request
|
|
433
|
+
every request still holding the dialog, each with `unproven_since`. A request
|
|
411
434
|
that reads `"delivered"` or closed at the pane can remain unproven; its dialog
|
|
412
435
|
may still be there. Handling is in the
|
|
413
436
|
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
@@ -669,7 +692,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
669
692
|
|---|---|
|
|
670
693
|
| `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while the request relay may still answer. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
|
|
671
694
|
| `ErrRelayFallenBack` | The request's relay settled without acknowledgement and no pane answer is recorded through agent-director. Cursor uses finite `confirm_by` with null per-request hook process evidence; see [Cursor permissions](../../docs/permissions.md#cursor-spawns). Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
|
|
672
|
-
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
|
|
695
|
+
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence and is not a Cursor request of an earlier launch (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
|
|
673
696
|
| `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
674
697
|
| `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
|
|
675
698
|
| `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
package/dist/errors.d.ts
CHANGED
|
@@ -364,8 +364,9 @@ export declare class ErrClaimTooSoon extends AgentDirectorError {
|
|
|
364
364
|
/**
|
|
365
365
|
* Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
|
|
366
366
|
* a `pause`, while a permission request of the Spawn is not proven gone by the agent's hooks
|
|
367
|
-
* (its tool's PostToolUse, the main agent's end of turn after it, or
|
|
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/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
|
@@ -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. */
|
|
@@ -232,14 +233,23 @@ export interface PermissionRequestInfo extends RequestDelivery {
|
|
|
232
233
|
/** The recorded verdict's decision_reason; null when none is recorded. */
|
|
233
234
|
decision_reason: string | null;
|
|
234
235
|
}
|
|
236
|
+
/**
|
|
237
|
+
* Whether `idle_screen` can apply to a row's agent: `"available"` for Claude and Codex,
|
|
238
|
+
* `"unavailable"` for Cursor. A capability outcome, never a state.
|
|
239
|
+
*/
|
|
240
|
+
export type IdleScreenAvailability = "available" | "unavailable";
|
|
235
241
|
/** One Spawn row returned by the list verb. */
|
|
236
242
|
export interface ListRow {
|
|
243
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
244
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
237
245
|
/** Stable Spawn id. */
|
|
238
246
|
instance_id: string;
|
|
239
247
|
/** Parent Spawn id (omitted when launched from a plain shell). */
|
|
240
248
|
parent_id?: string;
|
|
241
249
|
/**
|
|
242
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
250
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
251
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
252
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
243
253
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
244
254
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
245
255
|
* prompt. A resumed pending row keeps its session id and history.
|
|
@@ -248,15 +258,20 @@ export interface ListRow {
|
|
|
248
258
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
249
259
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
250
260
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
251
|
-
*
|
|
252
|
-
*
|
|
261
|
+
* Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
|
|
262
|
+
* times settle_ms from the read that commits its candidate; a later read commits the change.
|
|
263
|
+
* Nothing marks a state as late. `family_state` settles independently. Fields such as
|
|
264
|
+
* `state_changed_at` and `permission_requests`, and the verbs that act on the row, follow its
|
|
265
|
+
* live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
253
266
|
*/
|
|
254
267
|
state: string;
|
|
255
268
|
/**
|
|
256
269
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
257
|
-
* intermediates.
|
|
258
|
-
*
|
|
259
|
-
*
|
|
270
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
271
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
272
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
273
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
274
|
+
* not establish readiness or task success.
|
|
260
275
|
*/
|
|
261
276
|
family_state: "working" | "waiting";
|
|
262
277
|
/** Canonicalized working directory. */
|
|
@@ -273,6 +288,15 @@ export interface ListRow {
|
|
|
273
288
|
started_at: string;
|
|
274
289
|
/** Most recent hook UPSERT time (RFC3339). */
|
|
275
290
|
last_seen_at: string;
|
|
291
|
+
/**
|
|
292
|
+
* When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
|
|
293
|
+
* Soft refreshes and same-state writes leave it; `state` may still show the earlier
|
|
294
|
+
* settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
|
|
295
|
+
* agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
|
|
296
|
+
* or list finds lost reads `missing` at once; this moves when that mark is stored, which
|
|
297
|
+
* can be after the read that first shows `missing`.
|
|
298
|
+
*/
|
|
299
|
+
state_changed_at: string;
|
|
276
300
|
/** Set when state moves to ended (omitted while live). */
|
|
277
301
|
ended_at?: string | null;
|
|
278
302
|
/**
|
|
@@ -314,8 +338,10 @@ export interface ListRow {
|
|
|
314
338
|
* delivery facts; populated only when the row's live state is check_permission, `[]`
|
|
315
339
|
* otherwise. A row can read waiting, working or ask_user while a request is still open:
|
|
316
340
|
* follow a tracked request with `getPermission`. Requests are never delayed by
|
|
317
|
-
* `[state] settle_ms`, so with it set
|
|
318
|
-
* with open requests listed, or check_permission with `[]`, for up
|
|
341
|
+
* `[state] settle_ms`, so with it set ordinary raw-state settling can also show any state
|
|
342
|
+
* (even ended or missing) with open requests listed, or check_permission with `[]`, for up
|
|
343
|
+
* to settle_ms; entering or leaving `needs_intelligence` or `idle_screen` has no such bound
|
|
344
|
+
* (see `state`).
|
|
319
345
|
*/
|
|
320
346
|
permission_requests: PermissionRequestInfo[];
|
|
321
347
|
}
|
|
@@ -407,6 +433,15 @@ export interface SpawnParams {
|
|
|
407
433
|
* `ErrInstanceIdCollision`.
|
|
408
434
|
*/
|
|
409
435
|
reuse_finished?: boolean;
|
|
436
|
+
/**
|
|
437
|
+
* This row's `idle_screen` timeout in whole seconds, 1 to 9223372036, used by every
|
|
438
|
+
* `status`, `get` and `list` in place of `[state] idle_screen_timeout_seconds`.
|
|
439
|
+
* `0`, `null` or omitted gives no override. A negative, fractional, non-numeric or larger
|
|
440
|
+
* value is refused with `ErrInvalidFlags` before anything is written or launched. Recorded
|
|
441
|
+
* on the row: `resume` keeps it; the next spawn or reuse replaces it, clearing it when that
|
|
442
|
+
* call gives none. Cursor rows keep it, but `idle_screen` is unavailable for them.
|
|
443
|
+
*/
|
|
444
|
+
idle_screen_timeout_seconds?: number | null;
|
|
410
445
|
}
|
|
411
446
|
/**
|
|
412
447
|
* The launch result. The row is `pending` from its insert until
|
|
@@ -443,10 +478,30 @@ export interface StatusParams {
|
|
|
443
478
|
}
|
|
444
479
|
/** The row's reported lifecycle state. */
|
|
445
480
|
export interface StatusResult {
|
|
481
|
+
/**
|
|
482
|
+
* When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
|
|
483
|
+
* only while `needs_intelligence` or `idle_screen` is displayed.
|
|
484
|
+
*/
|
|
485
|
+
since?: string;
|
|
486
|
+
/**
|
|
487
|
+
* The representative unanswered request (earliest qualifying fallback, lexical
|
|
488
|
+
* request-token tie break); only while `needs_intelligence`.
|
|
489
|
+
*/
|
|
490
|
+
request_token?: string;
|
|
491
|
+
/** That request's tool; only while `needs_intelligence`. */
|
|
492
|
+
tool_name?: string;
|
|
493
|
+
/** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
|
|
494
|
+
unchanged_minutes?: number;
|
|
495
|
+
/** Attach target, present only while `needs_intelligence` or `idle_screen` is displayed. */
|
|
496
|
+
tmux_session_name?: string;
|
|
497
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
498
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
446
499
|
/** Experimental context estimate for the current session. */
|
|
447
500
|
context: ContextReading;
|
|
448
501
|
/**
|
|
449
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
502
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
503
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
504
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
450
505
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
451
506
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
452
507
|
* prompt. A resumed pending row keeps its session id and history; a caller tells it
|
|
@@ -456,15 +511,19 @@ export interface StatusResult {
|
|
|
456
511
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
457
512
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
458
513
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
514
|
+
* Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
|
|
515
|
+
* times settle_ms from the read that commits its candidate; a later read commits the change.
|
|
459
516
|
* Nothing marks a state as late. The verbs that act on the Spawn follow its live state, which
|
|
460
517
|
* can be newer: a refusal can name a state status does not show yet.
|
|
461
518
|
*/
|
|
462
519
|
state: string;
|
|
463
520
|
/**
|
|
464
521
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
465
|
-
* intermediates.
|
|
466
|
-
*
|
|
467
|
-
*
|
|
522
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
523
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
524
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
525
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
526
|
+
* not establish readiness or task success.
|
|
468
527
|
*/
|
|
469
528
|
family_state: "working" | "waiting";
|
|
470
529
|
/**
|
|
@@ -500,12 +559,30 @@ export interface GetParams {
|
|
|
500
559
|
}
|
|
501
560
|
/** One tracked agent row, with its current session and request facts. */
|
|
502
561
|
export interface GetResult {
|
|
562
|
+
/**
|
|
563
|
+
* When the row entered the Displayed State it shows (RFC3339 UTC, millisecond precision);
|
|
564
|
+
* only while `needs_intelligence` or `idle_screen` is displayed.
|
|
565
|
+
*/
|
|
566
|
+
since?: string;
|
|
567
|
+
/**
|
|
568
|
+
* The representative unanswered request (earliest qualifying fallback, lexical
|
|
569
|
+
* request-token tie break); only while `needs_intelligence`.
|
|
570
|
+
*/
|
|
571
|
+
request_token?: string;
|
|
572
|
+
/** That request's tool; only while `needs_intelligence`. */
|
|
573
|
+
tool_name?: string;
|
|
574
|
+
/** Completed minutes of the committed unchanged pane period; only while `idle_screen`. */
|
|
575
|
+
unchanged_minutes?: number;
|
|
576
|
+
/** Whether `idle_screen` can apply to the row's agent: `"unavailable"` for Cursor. */
|
|
577
|
+
idle_screen_availability: IdleScreenAvailability;
|
|
503
578
|
/** Experimental context estimate for the current session. */
|
|
504
579
|
context: ContextReading;
|
|
505
580
|
instance_id: string;
|
|
506
581
|
parent_id: string;
|
|
507
582
|
/**
|
|
508
|
-
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing)
|
|
583
|
+
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing),
|
|
584
|
+
* or a report-only Displayed State: `needs_intelligence` (an unanswered permission request)
|
|
585
|
+
* or `idle_screen` (an unchanged working pane); live command guards still follow the raw state.
|
|
509
586
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
510
587
|
* reported in yet (its SessionStart hook); it may be loading or waiting at a startup
|
|
511
588
|
* prompt. A resumed pending row keeps its session id and history; a non-empty
|
|
@@ -515,15 +592,22 @@ export interface GetResult {
|
|
|
515
592
|
* off), this is the settled state: a state a hook wrote shows only once it has held for
|
|
516
593
|
* settle_ms, and the last settled state shows meanwhile, so a change that reverts sooner never
|
|
517
594
|
* shows; ended, missing and a state a command wrote (spawn, resume, find-missing) show at once.
|
|
518
|
-
*
|
|
519
|
-
*
|
|
595
|
+
* Entering or leaving `needs_intelligence` or `idle_screen`, or moving between them, instead
|
|
596
|
+
* times settle_ms from the read that commits its candidate; a later read commits the change.
|
|
597
|
+
* Nothing marks a state as late. While an exit or direct move settles, `since` and that
|
|
598
|
+
* state's detail keep the previous display's committed values, and `family_state` settles
|
|
599
|
+
* independently. Fields such as `state_changed_at` and `permission_requests`, and the verbs
|
|
600
|
+
* that act on the row, follow its live state, which can be newer: a refusal can name a state
|
|
601
|
+
* this field does not show yet.
|
|
520
602
|
*/
|
|
521
603
|
state: string;
|
|
522
604
|
/**
|
|
523
605
|
* Complete stored family: self and live descendants, including through retained terminal
|
|
524
|
-
* intermediates.
|
|
525
|
-
*
|
|
526
|
-
*
|
|
606
|
+
* intermediates. A live member counts as working while its raw state is not waiting or its
|
|
607
|
+
* committed display is `needs_intelligence` or `idle_screen`, until that display's exit
|
|
608
|
+
* commits. Waiting means no member counts as working, or no live members remain. Settles once
|
|
609
|
+
* in either direction with `[state] settle_ms`, independently of `state`. This report does
|
|
610
|
+
* not establish readiness or task success.
|
|
527
611
|
*/
|
|
528
612
|
family_state: "working" | "waiting";
|
|
529
613
|
cwd: string;
|
|
@@ -548,6 +632,15 @@ export interface GetResult {
|
|
|
548
632
|
started_at: string;
|
|
549
633
|
/** Last hook UPSERT time (RFC3339). */
|
|
550
634
|
last_seen_at: string;
|
|
635
|
+
/**
|
|
636
|
+
* When the raw state last changed (RFC3339 UTC, millisecond precision), on every row.
|
|
637
|
+
* Soft refreshes and same-state writes leave it; `state` may still show the earlier
|
|
638
|
+
* settled value. `1970-01-01T00:00:00Z` when the raw state has not changed since
|
|
639
|
+
* agent-director began recording it. Not a Displayed State's `since`. A Cursor row that get
|
|
640
|
+
* or list finds lost reads `missing` at once; this moves when that mark is stored, which
|
|
641
|
+
* can be after the read that first shows `missing`.
|
|
642
|
+
*/
|
|
643
|
+
state_changed_at: string;
|
|
551
644
|
/** Set when state moves to ended; omitted while live. */
|
|
552
645
|
ended_at?: string | null;
|
|
553
646
|
/**
|
|
@@ -590,20 +683,23 @@ export interface GetResult {
|
|
|
590
683
|
* only when the row's live state is check_permission, `[]` otherwise. A row can read waiting,
|
|
591
684
|
* working or ask_user while a request is still open: follow a tracked request with
|
|
592
685
|
* `getPermission`.
|
|
593
|
-
* Requests are never delayed by `[state] settle_ms`, so with it set
|
|
594
|
-
* state (even ended or missing) with open requests listed, or
|
|
595
|
-
* up to settle_ms
|
|
686
|
+
* Requests are never delayed by `[state] settle_ms`, so with it set ordinary raw-state
|
|
687
|
+
* settling can also show any state (even ended or missing) with open requests listed, or
|
|
688
|
+
* check_permission with `[]`, for up to settle_ms; entering or leaving `needs_intelligence`
|
|
689
|
+
* or `idle_screen` has no such bound (see `state`).
|
|
596
690
|
*/
|
|
597
691
|
permission_requests: PermissionRequestInfo[];
|
|
598
692
|
/**
|
|
599
|
-
* Every permission request of the row that the agent's hooks have not proven gone
|
|
600
|
-
* null),
|
|
601
|
-
*
|
|
602
|
-
* (delivered, answered at the pane,
|
|
603
|
-
* `unproven_since`. While it is not empty, a plain
|
|
604
|
-
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an
|
|
605
|
-
* row's live state and is never delayed by
|
|
606
|
-
* with `state` for up to settle_ms
|
|
693
|
+
* Every permission request of the row that the agent's hooks have not proven gone
|
|
694
|
+
* (`proven_gone_at` null), less Cursor requests of an earlier launch of the row, oldest first,
|
|
695
|
+
* in any live state but ended and missing (`[]` on those). Unlike `permission_requests` it
|
|
696
|
+
* also lists requests agent-director's records read closed (delivered, answered at the pane,
|
|
697
|
+
* or recorded answered outside it), each with `unproven_since`. While it is not empty, a plain
|
|
698
|
+
* `sendKeys` without `expect_pane_sha256`, and a `pause`, reject (`ErrDialogMaybeOpen`, or an
|
|
699
|
+
* earlier relay refusal). It follows the row's live state and is never delayed by
|
|
700
|
+
* `[state] settle_ms`, so with it set it can disagree with `state` for up to settle_ms under
|
|
701
|
+
* ordinary raw-state settling, and without that bound while entering or leaving
|
|
702
|
+
* `needs_intelligence` or `idle_screen` (see `state`).
|
|
607
703
|
*/
|
|
608
704
|
unproven_requests: PermissionRequestInfo[];
|
|
609
705
|
}
|
|
@@ -837,11 +933,12 @@ export interface RelayFallenBackDetails extends PermissionRequestInfo {
|
|
|
837
933
|
open_requests: OpenRequestFacts[] | null;
|
|
838
934
|
}
|
|
839
935
|
/**
|
|
840
|
-
* ErrDialogMaybeOpen's errDetails (from a plain
|
|
841
|
-
*
|
|
842
|
-
*
|
|
843
|
-
* say it closed, `delivery` and `pane_answer`, and since when,
|
|
844
|
-
* state, and the Spawn's other requests
|
|
936
|
+
* ErrDialogMaybeOpen's errDetails (from a plain sendKeys without `expect_pane_sha256`, and
|
|
937
|
+
* from pause): the oldest request of the Spawn that holds the dialog (not proven gone, less a
|
|
938
|
+
* Cursor request of an earlier launch), with its fields and delivery facts (how
|
|
939
|
+
* agent-director's records say it closed, `delivery` and `pane_answer`, and since when,
|
|
940
|
+
* `unproven_since`), the Spawn's state, and the Spawn's other such requests (as
|
|
941
|
+
* `unproven_requests` lists them), oldest first.
|
|
845
942
|
*/
|
|
846
943
|
export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
|
|
847
944
|
state: string;
|
|
@@ -1074,8 +1171,9 @@ export interface MakeTemplateResult {
|
|
|
1074
1171
|
/** Filters for listing tracked agent rows. */
|
|
1075
1172
|
export interface ListParams {
|
|
1076
1173
|
/**
|
|
1077
|
-
* Filter by state (multiple values OR together).
|
|
1078
|
-
*
|
|
1174
|
+
* Filter by state (multiple values OR together). The filter matches the displayed state,
|
|
1175
|
+
* including `needs_intelligence` and `idle_screen` (a row showing either does not match its
|
|
1176
|
+
* raw state), and is applied before `limit`.
|
|
1079
1177
|
*/
|
|
1080
1178
|
state?: string[];
|
|
1081
1179
|
/** Filter by label k=v pairs (multiple entries AND together). */
|