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 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`. Six errors
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`) and `ErrSubmissionUnconfirmed`
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` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
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
- /** Mirrors ErrPauseTimeout (package: api) */
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}.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],