agent-director 0.14.0 → 0.15.1
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 +9 -4
- 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 +18 -2
- 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
|
|
@@ -612,7 +617,7 @@ These classes correspond to the shared CLI `err_name` contract. They surface bad
|
|
|
612
617
|
| Error | When it fires |
|
|
613
618
|
|---|---|
|
|
614
619
|
| `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
|
|
615
|
-
| `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.
|
|
620
|
+
| `ErrSpawnDeniedFlag` | Cursor argument refusals and switch selector rules are in [Cursor operation boundaries](../../docs/caller-contract.md#cursor-operation-boundaries). The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst`, `features.hooks` or its alias `features.codex_hooks`, `--disable hooks` or `--disable codex_hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
|
|
616
621
|
| `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"`, `"codex"` or `"cursor"`), or put one in the template. |
|
|
617
622
|
| `ErrAgentInvalid` | `agent` is none of `"claude"`, `"codex"` or `"cursor"` (the value is case-sensitive); nothing is written. |
|
|
618
623
|
| `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
|
|
@@ -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
|
@@ -366,8 +366,9 @@ export interface SpawnParams {
|
|
|
366
366
|
* removed tokens appear in `dropped_args`; the agent starts fresh and resumes nothing.
|
|
367
367
|
* Exact denied long tokens owned as option values always refuse. For codex, a Codex subcommand in
|
|
368
368
|
* command position, `--remote`, `--remote-auth-token-env`, `-c`/`--config` keys at, above or
|
|
369
|
-
* under `hooks`, `tui.disable_paste_burst
|
|
370
|
-
*
|
|
369
|
+
* under `hooks`, `tui.disable_paste_burst`, `features.hooks` or its alias
|
|
370
|
+
* `features.codex_hooks`, and `--disable hooks` or `codex_hooks` are refused
|
|
371
|
+
* (`ErrSpawnDeniedFlag`); with `disable_ask_user` on, `--enable
|
|
371
372
|
* default_mode_request_user_input` and the question-tool keys are refused too. agent-director
|
|
372
373
|
* adds no second `--no-daemon`, `--dangerously-bypass-hook-trust` (pre-trust ok) or
|
|
373
374
|
* `--enable write_stdin_approval` when the arguments already carry one before any `--`;
|
|
@@ -799,6 +800,21 @@ export interface RecordPaneAnswerResult {
|
|
|
799
800
|
/** Always "pane_outside". */
|
|
800
801
|
decision_reason: "pane_outside";
|
|
801
802
|
}
|
|
803
|
+
/**
|
|
804
|
+
* ErrPauseTimeout's errDetails after exit keys were sent but ended was not
|
|
805
|
+
* observed. Pass the outcome to a caller that can inspect the session and
|
|
806
|
+
* decide before more input; it does not prove a prompt is open or why exit is delayed.
|
|
807
|
+
*/
|
|
808
|
+
export interface PauseTimeoutDetails {
|
|
809
|
+
/** Session inspection and a caller's decision are required before further input. */
|
|
810
|
+
inspection_required: true;
|
|
811
|
+
/** tmux accepted /exit and Enter; the agent's consumption is unknown. */
|
|
812
|
+
exit_keys_sent: true;
|
|
813
|
+
/** The row was not observed to reach ended before the deadline. */
|
|
814
|
+
exit_confirmed: false;
|
|
815
|
+
/** Last raw state read, not a judgement about the pane. */
|
|
816
|
+
row_state: string;
|
|
817
|
+
}
|
|
802
818
|
/**
|
|
803
819
|
* One other open request of the Spawn in
|
|
804
820
|
* {@link RelayFallenBackDetails}.
|