agent-director 0.13.0 → 0.15.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 +18 -10
- package/dist/errors.d.ts +5 -1
- package/dist/index.d.ts +2 -2
- package/dist/internal/subprocessClient.d.ts +3 -1
- package/dist/types.d.ts +61 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -147,13 +147,16 @@ const result = await client.status({ instance_id: "<id>" });
|
|
|
147
147
|
console.log(result.state);
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
|
|
151
|
-
`
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
150
|
+
`StatusResult`, `GetResult` and each `ListRow` expose
|
|
151
|
+
`family_state: "working" | "waiting"`, separately from `state`.
|
|
152
|
+
[Usage](../../docs/usage.md#family-state) defines membership and raw
|
|
153
|
+
aggregation; the [caller contract](../../docs/caller-contract.md#family-reporting-limits)
|
|
154
|
+
defines reporting limits.
|
|
155
|
+
|
|
156
|
+
`status`, `get` and `list` use `[state] settle_ms` in the CLI's
|
|
157
|
+
`~/.config/agent-director/config.toml` for [independent state and family
|
|
158
|
+
settling](../../docs/configuration.md#settle-time-state). Verbs that act on a
|
|
159
|
+
Spawn judge its live state, which can be newer than its reported state.
|
|
157
160
|
|
|
158
161
|
### list
|
|
159
162
|
|
|
@@ -308,6 +311,10 @@ await client.pause({ instance_id: "<id>" });
|
|
|
308
311
|
For input ownership or journal failures (`ErrInternal` before any input), see
|
|
309
312
|
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
310
313
|
|
|
314
|
+
For `ErrPauseTimeout`, `errDetails` has the exported `PauseTimeoutDetails`
|
|
315
|
+
shape. Its fields and required inspection procedure are defined in
|
|
316
|
+
[When pause cannot confirm exit](../../docs/caller-contract.md#when-pause-cannot-confirm-exit).
|
|
317
|
+
|
|
311
318
|
`pause` is held like a `sendKeys` without `request_token` and without
|
|
312
319
|
`expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
|
|
313
320
|
`ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
|
|
@@ -539,12 +546,13 @@ try {
|
|
|
539
546
|
```
|
|
540
547
|
|
|
541
548
|
Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
|
|
542
|
-
the error envelope's optional `err_details` object, or `null`.
|
|
549
|
+
the error envelope's optional `err_details` object, or `null`. Seven errors
|
|
543
550
|
carry one, typed as exported interfaces: `ErrRelayFallenBack`
|
|
544
551
|
(`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
|
|
545
552
|
(`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
|
|
546
553
|
`ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
|
|
547
|
-
(`DialogMaybeOpenDetails`)
|
|
554
|
+
(`DialogMaybeOpenDetails`), `ErrPauseTimeout` (`PauseTimeoutDetails`) and
|
|
555
|
+
`ErrSubmissionUnconfirmed`
|
|
548
556
|
(`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
|
|
549
557
|
Native submission facts remain available through the generic `errDetails`
|
|
550
558
|
record. So does the `ErrInternal` of a
|
|
@@ -634,7 +642,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
634
642
|
| `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). |
|
|
635
643
|
| `ErrSubmissionUnconfirmed` | `SubmissionUnconfirmedDetails` describes fallback pending-Codex uncertainty; native outcome fields are available through the generic `errDetails` record. See [Ordinary text submission](../../docs/caller-contract.md#ordinary-text-submission) for automatic delivery and [Manual input ownership](../../docs/caller-contract.md#manual-input-ownership) for manual `sendKeys`. |
|
|
636
644
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
637
|
-
| `ErrPauseTimeout` |
|
|
645
|
+
| `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). |
|
|
638
646
|
| `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. |
|
|
639
647
|
| `ErrNoSessionId` | The spawn has no `session_id`, so there is nothing to resume. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
|
|
640
648
|
| `ErrJsonlMissing` | The current session's transcript is unavailable. Cursor requires its protected gateway transcript; native session availability is decided later during load. Older sessions are never tried. For any agent, spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), starting a fresh conversation with no memory of the old conversation; see [Transcript recovery](../../docs/caller-contract.md#transcript-recovery). For an artifact-preserving fresh generated-ID alternative, follow [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). |
|
package/dist/errors.d.ts
CHANGED
|
@@ -288,7 +288,11 @@ export declare class ErrSendKeysWhileRelayed extends AgentDirectorError {
|
|
|
288
288
|
/** Mirrors ErrSpawnNotPausable (package: api) */
|
|
289
289
|
export declare class ErrSpawnNotPausable extends AgentDirectorError {
|
|
290
290
|
}
|
|
291
|
-
/**
|
|
291
|
+
/**
|
|
292
|
+
* Exit keys were sent but ended was not observed before the pause deadline.
|
|
293
|
+
* `errDetails` is a `PauseTimeoutDetails` requiring session inspection and a caller's
|
|
294
|
+
* decision before more input. It does not prove a prompt is open; never retry pause automatically.
|
|
295
|
+
*/
|
|
292
296
|
export declare class ErrPauseTimeout extends AgentDirectorError {
|
|
293
297
|
}
|
|
294
298
|
/** Mirrors ErrListInvalidLabel (package: api) */
|
package/dist/index.d.ts
CHANGED
|
@@ -11,5 +11,5 @@ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCw
|
|
|
11
11
|
export type { CheckedLocation, UnreachableReason } from "./errors.js";
|
|
12
12
|
export type { ClientOptions, Logger } from "./types.js";
|
|
13
13
|
export type { VerbSummary, PermissionRequestInfo, ListRow, Delivery, RequestDelivery, PaneAnswer, ProvenGoneHow, } from "./types.js";
|
|
14
|
-
export type { RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
|
|
15
|
-
export type { SpawnParams, SpawnResult, StatusParams, StatusResult, 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";
|
|
14
|
+
export type { PauseTimeoutDetails, RelayFallenBackDetails, OpenRequestFacts, PaneAnswerInProgressDetails, ClaimTooSoonDetails, PaneChangedDetails, PaneKeySentDetails, SubmissionUnconfirmedDetails, DialogMaybeOpenDetails, } from "./types.js";
|
|
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";
|
|
@@ -154,7 +154,9 @@ export declare class SubprocessClient {
|
|
|
154
154
|
* done at the pane. Past it: readPane, answer any dialog, then sendKeys `/exit` with the judged
|
|
155
155
|
* pane's expect_pane_sha256; or kill. On a Codex row whose agent process is gone and which
|
|
156
156
|
* holds an end report, pause moves the row to `ended` (before typing anything, or while it
|
|
157
|
-
* waits) and succeeds.
|
|
157
|
+
* waits) and succeeds. ErrPauseTimeout carries PauseTimeoutDetails with
|
|
158
|
+
* inspection_required: true: pass it to a caller that can inspect get/readPane and decide
|
|
159
|
+
* before more input. A prompt may be open, but is not proven; never retry pause automatically.
|
|
158
160
|
*/
|
|
159
161
|
pause(params: PauseParams): Promise<PauseResult>;
|
|
160
162
|
/** version — return the npm package version (b.6o1) plus the CLI's commit SHA. */
|
package/dist/types.d.ts
CHANGED
|
@@ -252,6 +252,13 @@ export interface ListRow {
|
|
|
252
252
|
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
253
253
|
*/
|
|
254
254
|
state: string;
|
|
255
|
+
/**
|
|
256
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
257
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
258
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
259
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
260
|
+
*/
|
|
261
|
+
family_state: "working" | "waiting";
|
|
255
262
|
/** Canonicalized working directory. */
|
|
256
263
|
cwd: string;
|
|
257
264
|
/** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
|
|
@@ -435,6 +442,8 @@ export interface StatusParams {
|
|
|
435
442
|
}
|
|
436
443
|
/** The row's reported lifecycle state. */
|
|
437
444
|
export interface StatusResult {
|
|
445
|
+
/** Experimental context estimate for the current session. */
|
|
446
|
+
context: ContextReading;
|
|
438
447
|
/**
|
|
439
448
|
* Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing).
|
|
440
449
|
* pending means a launch (spawn, reuse or resume) is in progress and the agent has not
|
|
@@ -450,6 +459,13 @@ export interface StatusResult {
|
|
|
450
459
|
* can be newer: a refusal can name a state status does not show yet.
|
|
451
460
|
*/
|
|
452
461
|
state: string;
|
|
462
|
+
/**
|
|
463
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
464
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
465
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
466
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
467
|
+
*/
|
|
468
|
+
family_state: "working" | "waiting";
|
|
453
469
|
/**
|
|
454
470
|
* Start of the launch in progress (RFC3339 UTC, millisecond precision); present only on a
|
|
455
471
|
* pending row, omitted otherwise. It follows the row's live state: with `[state] settle_ms`
|
|
@@ -457,6 +473,25 @@ export interface StatusResult {
|
|
|
457
473
|
*/
|
|
458
474
|
launch_started_at?: string | null;
|
|
459
475
|
}
|
|
476
|
+
/**
|
|
477
|
+
* Experimental: agent internals and this output shape have no stable-format guarantee.
|
|
478
|
+
* Unavailable readings retain all five null fields. The Codex 0.159.2 OpenAI rollout
|
|
479
|
+
* source estimates last-response occupancy from its own usage and reported usable window;
|
|
480
|
+
* it does not represent cumulative billing. Claude 2.1.280 first-party pairs native capacity
|
|
481
|
+
* callbacks with transcript usage for the same resolved model and response, without provider,
|
|
482
|
+
* endpoint or window overrides. Cursor remains unknown: managed ACP lacks the ordinary
|
|
483
|
+
* usage-bearing afterAgentResponse/stop path and manual /summarize; its prompt result has only
|
|
484
|
+
* stopReason. Both captured Cursor versions have a shared-resource native preCompact executor
|
|
485
|
+
* path, but automatic managed delivery remains unqualified and managed support incomplete.
|
|
486
|
+
*/
|
|
487
|
+
export interface ContextReading {
|
|
488
|
+
used_tokens: number | null;
|
|
489
|
+
window_tokens: number | null;
|
|
490
|
+
fraction: number | null;
|
|
491
|
+
source: string | null;
|
|
492
|
+
/** Measurement time in RFC3339 UTC, never the time of the read. */
|
|
493
|
+
as_of: string | null;
|
|
494
|
+
}
|
|
460
495
|
/** The id whose row is requested. */
|
|
461
496
|
export interface GetParams {
|
|
462
497
|
/** Id of the Spawn to fetch. */
|
|
@@ -464,6 +499,8 @@ export interface GetParams {
|
|
|
464
499
|
}
|
|
465
500
|
/** One tracked agent row, with its current session and request facts. */
|
|
466
501
|
export interface GetResult {
|
|
502
|
+
/** Experimental context estimate for the current session. */
|
|
503
|
+
context: ContextReading;
|
|
467
504
|
instance_id: string;
|
|
468
505
|
parent_id: string;
|
|
469
506
|
/**
|
|
@@ -481,6 +518,13 @@ export interface GetResult {
|
|
|
481
518
|
* its live state, which can be newer: a refusal can name a state this field does not show yet.
|
|
482
519
|
*/
|
|
483
520
|
state: string;
|
|
521
|
+
/**
|
|
522
|
+
* Complete stored family: self and live descendants, including through retained terminal
|
|
523
|
+
* intermediates. Waiting means every live member is waiting, or no live members remain.
|
|
524
|
+
* Uses raw member states and settles once in either direction with `[state] settle_ms`,
|
|
525
|
+
* independently of `state`. This report does not establish readiness or task success.
|
|
526
|
+
*/
|
|
527
|
+
family_state: "working" | "waiting";
|
|
484
528
|
cwd: string;
|
|
485
529
|
/** The agent the row runs: `"claude"` (Claude Code), `"codex"` (Codex) or `"cursor"` (Cursor). Set at spawn; resume follows it. */
|
|
486
530
|
agent: string;
|
|
@@ -755,6 +799,21 @@ export interface RecordPaneAnswerResult {
|
|
|
755
799
|
/** Always "pane_outside". */
|
|
756
800
|
decision_reason: "pane_outside";
|
|
757
801
|
}
|
|
802
|
+
/**
|
|
803
|
+
* ErrPauseTimeout's errDetails after exit keys were sent but ended was not
|
|
804
|
+
* observed. Pass the outcome to a caller that can inspect the session and
|
|
805
|
+
* decide before more input; it does not prove a prompt is open or why exit is delayed.
|
|
806
|
+
*/
|
|
807
|
+
export interface PauseTimeoutDetails {
|
|
808
|
+
/** Session inspection and a caller's decision are required before further input. */
|
|
809
|
+
inspection_required: true;
|
|
810
|
+
/** tmux accepted /exit and Enter; the agent's consumption is unknown. */
|
|
811
|
+
exit_keys_sent: true;
|
|
812
|
+
/** The row was not observed to reach ended before the deadline. */
|
|
813
|
+
exit_confirmed: false;
|
|
814
|
+
/** Last raw state read, not a judgement about the pane. */
|
|
815
|
+
row_state: string;
|
|
816
|
+
}
|
|
758
817
|
/**
|
|
759
818
|
* One other open request of the Spawn in
|
|
760
819
|
* {@link RelayFallenBackDetails}.
|
|
@@ -1045,6 +1104,8 @@ export interface ListSubagentsParams {
|
|
|
1045
1104
|
* (trailing zeros dropped, no fraction on a whole second), exactly as the CLI prints it.
|
|
1046
1105
|
*/
|
|
1047
1106
|
export interface SubagentRecord {
|
|
1107
|
+
/** Experimental reading; unknown without evidence belonging to this child. */
|
|
1108
|
+
context: ContextReading;
|
|
1048
1109
|
/** The subagent's id, unique among the records shown for its row. */
|
|
1049
1110
|
subagent_id: string;
|
|
1050
1111
|
/** The id of the row (agent) the subagent belongs to. */
|