agent-director 0.11.1 → 0.12.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. */
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,10 @@ 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
+ * Mirrors ErrSendKeysWhileRelayed (package: api): from `sendKeys` and `pause` while a relay hook
277
+ * of the Spawn may still answer its request; nothing was sent.
278
+ */
255
279
  export declare class ErrSendKeysWhileRelayed extends AgentDirectorError {
256
280
  }
257
281
  /** Mirrors ErrSpawnNotPausable (package: api) */
@@ -275,6 +299,9 @@ export declare class ErrTemplateMalformed extends AgentDirectorError {
275
299
  /** Mirrors ErrTemplateExists (package: config) */
276
300
  export declare class ErrTemplateExists extends AgentDirectorError {
277
301
  }
302
+ /** Mirrors ErrTemplateAgentMissing (package: config) */
303
+ export declare class ErrTemplateAgentMissing extends AgentDirectorError {
304
+ }
278
305
  /** Mirrors ErrProbeUnsupported (package: probe) */
279
306
  export declare class ErrProbeUnsupported extends AgentDirectorError {
280
307
  }
@@ -293,9 +320,47 @@ export declare class ErrJsonlNeverWritten extends AgentDirectorError {
293
320
  /** Mirrors ErrRelayModeOff (package: api) */
294
321
  export declare class ErrRelayModeOff extends AgentDirectorError {
295
322
  }
296
- /** Mirrors ErrRelayFallenBack (package: api) */
323
+ /**
324
+ * Mirrors ErrRelayFallenBack (package: api): a permission request's relay hook is gone and acked
325
+ * no verdict, and no pane answer is recorded on it through agent-director. It arrives within
326
+ * seconds of the hook's end, from `decide` (for its request) and from a plain `sendKeys` and
327
+ * `pause` (for the Spawn's oldest such request). `errDetails` is a `RelayFallenBackDetails`:
328
+ * answer the request with `sendKeys` and its `request_token`, or close it with
329
+ * `recordPaneAnswer`.
330
+ */
297
331
  export declare class ErrRelayFallenBack extends AgentDirectorError {
298
332
  }
333
+ /**
334
+ * Mirrors ErrPaneChanged (package: api): the pane no longer has `expect_pane_sha256`; nothing was
335
+ * sent or recorded. Read the pane again. `errDetails` is a `PaneChangedDetails` (never the new
336
+ * hash).
337
+ */
338
+ export declare class ErrPaneChanged extends AgentDirectorError {
339
+ }
340
+ /**
341
+ * Mirrors ErrPaneAnswerInProgress (package: api): another pane answer on the request is still
342
+ * being sent; nothing was sent or recorded. `errDetails` is a `PaneAnswerInProgressDetails`.
343
+ */
344
+ export declare class ErrPaneAnswerInProgress extends AgentDirectorError {
345
+ }
346
+ /**
347
+ * Mirrors ErrClaimTooSoon (package: api): `recordPaneAnswer` before the request's relay hook has
348
+ * been gone 2 s (or while it may still answer); nothing was recorded. `errDetails` is a
349
+ * `ClaimTooSoonDetails`: retry at its `not_before`.
350
+ */
351
+ export declare class ErrClaimTooSoon extends AgentDirectorError {
352
+ }
353
+ /**
354
+ * Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
355
+ * a `pause`, while a permission request of the Spawn is not proven gone by the agent's hooks
356
+ * (its tool's PostToolUse, the main agent's end of turn after it, or the agent's end), whatever
357
+ * agent-director's records say of it; its dialog may still be on the pane. Nothing was sent.
358
+ * `errDetails` is a `DialogMaybeOpenDetails`. A plain `sendKeys` whose `expect_pane_sha256`
359
+ * matches the pane is not rejected with it; pass that hash only from a pane a person or LLM
360
+ * judged, never from an automatic flow.
361
+ */
362
+ export declare class ErrDialogMaybeOpen extends AgentDirectorError {
363
+ }
299
364
  /** Mirrors ErrInvalidDecision (package: api) */
300
365
  export declare class ErrInvalidDecision extends AgentDirectorError {
301
366
  }
@@ -311,6 +376,13 @@ export declare class ErrPermissionRequestNotFound extends AgentDirectorError {
311
376
  /** Mirrors ErrAmbiguousRequest (package: store) */
312
377
  export declare class ErrAmbiguousRequest extends AgentDirectorError {
313
378
  }
379
+ /**
380
+ * Mirrors ErrStoreBusy (package: store): decide's `max_wait_ms` bound was reached before its
381
+ * verdict was recorded (another process held the store's write lock). Nothing was recorded, so
382
+ * the call can be retried.
383
+ */
384
+ export declare class ErrStoreBusy extends AgentDirectorError {
385
+ }
314
386
  /** Mirrors ErrMissingRequestToken (package: api) */
315
387
  export declare class ErrMissingRequestToken extends AgentDirectorError {
316
388
  }
@@ -323,6 +395,32 @@ export declare class ErrConfigMalformed extends AgentDirectorError {
323
395
  /** Mirrors ErrStoreOpen (package: clisetup) */
324
396
  export declare class ErrStoreOpen extends AgentDirectorError {
325
397
  }
398
+ /** Mirrors ErrSchemaMismatch (package: clisetup) */
399
+ export declare class ErrSchemaMismatch extends AgentDirectorError {
400
+ }
401
+ /** Mirrors ErrSchemaMigrationRequired (package: clisetup) */
402
+ export declare class ErrSchemaMigrationRequired extends AgentDirectorError {
403
+ }
404
+ /**
405
+ * Mirrors ErrOldLayout (package: clisetup): the call would open the default store, no store exists
406
+ * there and the old directory (the one agent-director used before it moved to the standard config
407
+ * location) is present. Nothing was opened or created. Run this release's install.sh, which moves
408
+ * the old directory; see the {@link https://github.com/gabemahoney/agent-director/blob/main/docs/install.md#upgrade | Upgrade section of docs/install.md}.
409
+ */
410
+ export declare class ErrOldLayout extends AgentDirectorError {
411
+ }
412
+ /** Mirrors ErrUnknownVerb (package: clisetup) */
413
+ export declare class ErrUnknownVerb extends AgentDirectorError {
414
+ }
415
+ /** Mirrors ErrJSONMarshal (package: clisetup) */
416
+ export declare class ErrJSONMarshal extends AgentDirectorError {
417
+ }
418
+ /** Mirrors ErrTrailWrite (package: clisetup) */
419
+ export declare class ErrTrailWrite extends AgentDirectorError {
420
+ }
421
+ /** Mirrors ErrInternal (package: errnames) */
422
+ export declare class ErrInternal extends AgentDirectorError {
423
+ }
326
424
  /**
327
425
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
328
426
  * subprocess error envelope fields.
@@ -330,7 +428,8 @@ export declare class ErrStoreOpen extends AgentDirectorError {
330
428
  * @param verb The verb name that produced the error (e.g. "spawn").
331
429
  * @param err_name The canonical error name from the envelope.
332
430
  * @param err_description The human-readable description from the envelope.
431
+ * @param err_details The envelope's optional err_details object (b.146 rule 15).
333
432
  * @returns A typed subclass when err_name matches the catalog; a plain
334
433
  * AgentDirectorError (with a console.warn) for unknown names.
335
434
  */
336
- export declare function errorFromEnvelope(verb: string, err_name: string, err_description: string): AgentDirectorError;
435
+ 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, 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, 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";