agent-director 0.11.1 → 0.13.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/dist/errors.d.ts CHANGED
@@ -6,6 +6,10 @@ export { TS_ONLY_ERROR_NAMES } from "./internal/tsOnlyErrors.js";
6
6
  * `verb` names the callable verb that triggered the error (e.g. "spawn").
7
7
  * `errName` is the canonical error name from the Go errnames catalog.
8
8
  * `errDescription` is the human-readable description from the subprocess error envelope.
9
+ * `errDetails` is the envelope's optional `err_details` object (b.146 rule 15): the facts of a
10
+ * refusal that gives them as fields (ErrRelayFallenBack, ErrPaneAnswerInProgress,
11
+ * ErrClaimTooSoon, ErrPaneChanged, ErrDialogMaybeOpen, and the ErrInternal of a pane answer whose key was sent; see
12
+ * `RelayFallenBackDetails` and its siblings in types.ts), or null when the envelope carries none.
9
13
  * `message` is formatted as "${errName}: ${errDescription}".
10
14
  */
11
15
  export declare class AgentDirectorError extends Error {
@@ -15,7 +19,12 @@ export declare class AgentDirectorError extends Error {
15
19
  readonly errName: string;
16
20
  /** Human-readable description forwarded from the subprocess error envelope. */
17
21
  readonly errDescription: string;
18
- constructor(verb: string, err_name: string, err_description: string);
22
+ /**
23
+ * The envelope's `err_details` object, as sent; null when it carries none (b.146 rule 15).
24
+ * Read fields from it, never from errDescription.
25
+ */
26
+ readonly errDetails: Readonly<Record<string, unknown>> | null;
27
+ constructor(verb: string, err_name: string, err_description: string, err_details?: Readonly<Record<string, unknown>> | null);
19
28
  }
20
29
  /**
21
30
  * ErrClientClosed — thrown when a verb method (or _assertOpen) is called on a
@@ -69,10 +78,10 @@ export declare class ErrCallTimeout extends AgentDirectorError {
69
78
  /**
70
79
  * ErrUnknownErrorName — thrown when a subprocess JSON envelope contains an
71
80
  * `err_name` field that is not present in the static catalog-derived error map.
72
- * Either the binary is newer than this client, or the name is one the binary
73
- * emits but the shared catalog leaves out (for example ErrInternal or
74
- * ErrSchemaMismatch; cross-ref: b.cm7). Read `unknownName` for the
75
- * real err_name.
81
+ * The catalog lists every err_name the binary of this client's version emits
82
+ * (b.cm7), so an unknown name means the binary is a different version that
83
+ * emits a name this client does not know, most often a binary newer than this
84
+ * client. Read `unknownName` for the real err_name.
76
85
  *
77
86
  * Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
78
87
  * - `unknownName` — the unrecognised err_name string from the envelope.
@@ -206,12 +215,24 @@ export declare class ErrCwdNotADirectory extends AgentDirectorError {
206
215
  /** Mirrors ErrRelayModeInvalid (package: spawn) */
207
216
  export declare class ErrRelayModeInvalid extends AgentDirectorError {
208
217
  }
209
- /** Mirrors ErrSpawnDeniedFlag (package: spawn) */
218
+ /** Mirrors ErrSpawnDeniedFlag (spawn): forbidden agent arguments. A finished-agent switch drops session selectors; Claude print and exact denied long tokens owned as values always refuse. Cursor spawn/make-template refuse unsupported or malformed arguments; remove the named argument and any owned value, then retry. */
210
219
  export declare class ErrSpawnDeniedFlag extends AgentDirectorError {
211
220
  }
212
221
  /** Mirrors ErrReservedEnvKey (package: spawn) */
213
222
  export declare class ErrReservedEnvKey extends AgentDirectorError {
214
223
  }
224
+ /** Mirrors ErrAgentMissing (package: spawn) */
225
+ export declare class ErrAgentMissing extends AgentDirectorError {
226
+ }
227
+ /** Mirrors ErrAgentInvalid (package: spawn) */
228
+ export declare class ErrAgentInvalid extends AgentDirectorError {
229
+ }
230
+ /** Mirrors ErrAgentArgsMismatch (package: spawn) */
231
+ export declare class ErrAgentArgsMismatch extends AgentDirectorError {
232
+ }
233
+ /** Mirrors ErrPermissionsUnsupported (package: spawn) */
234
+ export declare class ErrPermissionsUnsupported extends AgentDirectorError {
235
+ }
215
236
  /** Mirrors ErrInstanceIdCollision (package: spawn) */
216
237
  export declare class ErrInstanceIdCollision extends AgentDirectorError {
217
238
  }
@@ -251,7 +272,17 @@ export declare class ErrTmuxKillFailed extends AgentDirectorError {
251
272
  /** Mirrors ErrSpawnNotInteractive (package: api) */
252
273
  export declare class ErrSpawnNotInteractive extends AgentDirectorError {
253
274
  }
254
- /** Mirrors ErrSendKeysWhileRelayed (package: api) */
275
+ /**
276
+ * tmux accepted the pending Codex row's keys and Enter, but submission could not be confirmed.
277
+ * The keys were sent; do not repeat text or Enter automatically. Check hook-derived get
278
+ * or status; if submission remains unknown, escalate to the caller or a human.
279
+ */
280
+ export declare class ErrSubmissionUnconfirmed extends AgentDirectorError {
281
+ }
282
+ /**
283
+ * Mirrors ErrSendKeysWhileRelayed (package: api): from `sendKeys` and `pause` while a relay hook
284
+ * of the Spawn may still answer its request; nothing was sent.
285
+ */
255
286
  export declare class ErrSendKeysWhileRelayed extends AgentDirectorError {
256
287
  }
257
288
  /** Mirrors ErrSpawnNotPausable (package: api) */
@@ -275,6 +306,9 @@ export declare class ErrTemplateMalformed extends AgentDirectorError {
275
306
  /** Mirrors ErrTemplateExists (package: config) */
276
307
  export declare class ErrTemplateExists extends AgentDirectorError {
277
308
  }
309
+ /** Mirrors ErrTemplateAgentMissing (package: config) */
310
+ export declare class ErrTemplateAgentMissing extends AgentDirectorError {
311
+ }
278
312
  /** Mirrors ErrProbeUnsupported (package: probe) */
279
313
  export declare class ErrProbeUnsupported extends AgentDirectorError {
280
314
  }
@@ -293,9 +327,47 @@ export declare class ErrJsonlNeverWritten extends AgentDirectorError {
293
327
  /** Mirrors ErrRelayModeOff (package: api) */
294
328
  export declare class ErrRelayModeOff extends AgentDirectorError {
295
329
  }
296
- /** Mirrors ErrRelayFallenBack (package: api) */
330
+ /**
331
+ * Mirrors ErrRelayFallenBack (package: api): a permission request's relay hook is gone and acked
332
+ * no verdict, and no pane answer is recorded on it through agent-director. It arrives within
333
+ * seconds of the hook's end, from `decide` (for its request) and from a plain `sendKeys` and
334
+ * `pause` (for the Spawn's oldest such request). `errDetails` is a `RelayFallenBackDetails`:
335
+ * answer the request with `sendKeys` and its `request_token`, or close it with
336
+ * `recordPaneAnswer`.
337
+ */
297
338
  export declare class ErrRelayFallenBack extends AgentDirectorError {
298
339
  }
340
+ /**
341
+ * Mirrors ErrPaneChanged (package: api): the pane no longer has `expect_pane_sha256`; nothing was
342
+ * sent or recorded. Read the pane again. `errDetails` is a `PaneChangedDetails` (never the new
343
+ * hash).
344
+ */
345
+ export declare class ErrPaneChanged extends AgentDirectorError {
346
+ }
347
+ /**
348
+ * Mirrors ErrPaneAnswerInProgress (package: api): another pane answer on the request is still
349
+ * being sent; nothing was sent or recorded. `errDetails` is a `PaneAnswerInProgressDetails`.
350
+ */
351
+ export declare class ErrPaneAnswerInProgress extends AgentDirectorError {
352
+ }
353
+ /**
354
+ * Mirrors ErrClaimTooSoon (package: api): `recordPaneAnswer` before the request's relay hook has
355
+ * been gone 2 s (or while it may still answer); nothing was recorded. `errDetails` is a
356
+ * `ClaimTooSoonDetails`: retry at its `not_before`.
357
+ */
358
+ export declare class ErrClaimTooSoon extends AgentDirectorError {
359
+ }
360
+ /**
361
+ * Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
362
+ * a `pause`, while a permission request of the Spawn is not proven gone by the agent's hooks
363
+ * (its tool's PostToolUse, the main agent's end of turn after it, or the agent's end), whatever
364
+ * agent-director's records say of it; its dialog may still be on the pane. Nothing was sent.
365
+ * `errDetails` is a `DialogMaybeOpenDetails`. A plain `sendKeys` whose `expect_pane_sha256`
366
+ * matches the pane is not rejected with it; pass that hash only from a pane a person or LLM
367
+ * judged, never from an automatic flow.
368
+ */
369
+ export declare class ErrDialogMaybeOpen extends AgentDirectorError {
370
+ }
299
371
  /** Mirrors ErrInvalidDecision (package: api) */
300
372
  export declare class ErrInvalidDecision extends AgentDirectorError {
301
373
  }
@@ -311,6 +383,13 @@ export declare class ErrPermissionRequestNotFound extends AgentDirectorError {
311
383
  /** Mirrors ErrAmbiguousRequest (package: store) */
312
384
  export declare class ErrAmbiguousRequest extends AgentDirectorError {
313
385
  }
386
+ /**
387
+ * Mirrors ErrStoreBusy (package: store): decide's `max_wait_ms` bound was reached before its
388
+ * verdict was recorded (another process held the store's write lock). Nothing was recorded, so
389
+ * the call can be retried.
390
+ */
391
+ export declare class ErrStoreBusy extends AgentDirectorError {
392
+ }
314
393
  /** Mirrors ErrMissingRequestToken (package: api) */
315
394
  export declare class ErrMissingRequestToken extends AgentDirectorError {
316
395
  }
@@ -323,6 +402,32 @@ export declare class ErrConfigMalformed extends AgentDirectorError {
323
402
  /** Mirrors ErrStoreOpen (package: clisetup) */
324
403
  export declare class ErrStoreOpen extends AgentDirectorError {
325
404
  }
405
+ /** Mirrors ErrSchemaMismatch (package: clisetup) */
406
+ export declare class ErrSchemaMismatch extends AgentDirectorError {
407
+ }
408
+ /** Mirrors ErrSchemaMigrationRequired (package: clisetup) */
409
+ export declare class ErrSchemaMigrationRequired extends AgentDirectorError {
410
+ }
411
+ /**
412
+ * Mirrors ErrOldLayout (package: clisetup): the call would open the default store, no store exists
413
+ * there and the old directory (the one agent-director used before it moved to the standard config
414
+ * location) is present. Nothing was opened or created. Run this release's install.sh, which moves
415
+ * the old directory; see the {@link https://github.com/gabemahoney/agent-director/blob/main/docs/install.md#upgrade | Upgrade section of docs/install.md}.
416
+ */
417
+ export declare class ErrOldLayout extends AgentDirectorError {
418
+ }
419
+ /** Mirrors ErrUnknownVerb (package: clisetup) */
420
+ export declare class ErrUnknownVerb extends AgentDirectorError {
421
+ }
422
+ /** Mirrors ErrJSONMarshal (package: clisetup) */
423
+ export declare class ErrJSONMarshal extends AgentDirectorError {
424
+ }
425
+ /** Mirrors ErrTrailWrite (package: clisetup) */
426
+ export declare class ErrTrailWrite extends AgentDirectorError {
427
+ }
428
+ /** Mirrors ErrInternal (package: errnames) */
429
+ export declare class ErrInternal extends AgentDirectorError {
430
+ }
326
431
  /**
327
432
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
328
433
  * subprocess error envelope fields.
@@ -330,7 +435,8 @@ export declare class ErrStoreOpen extends AgentDirectorError {
330
435
  * @param verb The verb name that produced the error (e.g. "spawn").
331
436
  * @param err_name The canonical error name from the envelope.
332
437
  * @param err_description The human-readable description from the envelope.
438
+ * @param err_details The envelope's optional err_details object (b.146 rule 15).
333
439
  * @returns A typed subclass when err_name matches the catalog; a plain
334
440
  * AgentDirectorError (with a console.warn) for unknown names.
335
441
  */
336
- export declare function errorFromEnvelope(verb: string, err_name: string, err_description: string): AgentDirectorError;
442
+ export declare function errorFromEnvelope(verb: string, err_name: string, err_description: string, err_details?: Readonly<Record<string, unknown>> | null): AgentDirectorError;
package/dist/index.d.ts CHANGED
@@ -7,8 +7,9 @@ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./c
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
8
  export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
9
9
  ErrSystemInstallDisappeared, // b.xht — binary gone at verb-dispatch after valid construction
10
- ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrTmuxUnresponsive, ErrTmuxSessionConflict, ErrTmuxKillFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrJsonlNeverWritten, ErrRelayModeOff, ErrRelayFallenBack, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, ErrConfigMalformed, ErrStoreOpen, } from "./errors.js";
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 } from "./types.js";
14
- export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";
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";