agent-director 0.14.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 +8 -3
- package/dist/errors.d.ts +5 -1
- package/dist/index.d.ts +1 -1
- package/dist/internal/subprocessClient.d.ts +3 -1
- package/dist/types.d.ts +15 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -311,6 +311,10 @@ await client.pause({ instance_id: "<id>" });
|
|
|
311
311
|
For input ownership or journal failures (`ErrInternal` before any input), see
|
|
312
312
|
[Manual input ownership](../../docs/caller-contract.md#manual-input-ownership).
|
|
313
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
|
+
|
|
314
318
|
`pause` is held like a `sendKeys` without `request_token` and without
|
|
315
319
|
`expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
|
|
316
320
|
`ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
|
|
@@ -542,12 +546,13 @@ try {
|
|
|
542
546
|
```
|
|
543
547
|
|
|
544
548
|
Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
|
|
545
|
-
the error envelope's optional `err_details` object, or `null`.
|
|
549
|
+
the error envelope's optional `err_details` object, or `null`. Seven errors
|
|
546
550
|
carry one, typed as exported interfaces: `ErrRelayFallenBack`
|
|
547
551
|
(`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
|
|
548
552
|
(`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
|
|
549
553
|
`ErrPaneChanged` (`PaneChangedDetails`), `ErrDialogMaybeOpen`
|
|
550
|
-
(`DialogMaybeOpenDetails`)
|
|
554
|
+
(`DialogMaybeOpenDetails`), `ErrPauseTimeout` (`PauseTimeoutDetails`) and
|
|
555
|
+
`ErrSubmissionUnconfirmed`
|
|
551
556
|
(`SubmissionUnconfirmedDetails`, for fallback pending-Codex uncertainty).
|
|
552
557
|
Native submission facts remain available through the generic `errDetails`
|
|
553
558
|
record. So does the `ErrInternal` of a
|
|
@@ -637,7 +642,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
637
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). |
|
|
638
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`. |
|
|
639
644
|
| `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
|
|
640
|
-
| `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). |
|
|
641
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. |
|
|
642
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). |
|
|
643
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";
|
|
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";
|
|
@@ -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
|
@@ -799,6 +799,21 @@ export interface RecordPaneAnswerResult {
|
|
|
799
799
|
/** Always "pane_outside". */
|
|
800
800
|
decision_reason: "pane_outside";
|
|
801
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
|
+
}
|
|
802
817
|
/**
|
|
803
818
|
* One other open request of the Spawn in
|
|
804
819
|
* {@link RelayFallenBackDetails}.
|