agent-director 0.11.0 → 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,8 +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
- * This indicates the Go-side catalog has a new entry that the TS catalog has
73
- * not yet been regenerated to include.
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.
74
85
  *
75
86
  * Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
76
87
  * - `unknownName` — the unrecognised err_name string from the envelope.
@@ -204,12 +215,24 @@ export declare class ErrCwdNotADirectory extends AgentDirectorError {
204
215
  /** Mirrors ErrRelayModeInvalid (package: spawn) */
205
216
  export declare class ErrRelayModeInvalid extends AgentDirectorError {
206
217
  }
207
- /** 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. */
208
219
  export declare class ErrSpawnDeniedFlag extends AgentDirectorError {
209
220
  }
210
221
  /** Mirrors ErrReservedEnvKey (package: spawn) */
211
222
  export declare class ErrReservedEnvKey extends AgentDirectorError {
212
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
+ }
213
236
  /** Mirrors ErrInstanceIdCollision (package: spawn) */
214
237
  export declare class ErrInstanceIdCollision extends AgentDirectorError {
215
238
  }
@@ -249,7 +272,10 @@ export declare class ErrTmuxKillFailed extends AgentDirectorError {
249
272
  /** Mirrors ErrSpawnNotInteractive (package: api) */
250
273
  export declare class ErrSpawnNotInteractive extends AgentDirectorError {
251
274
  }
252
- /** 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
+ */
253
279
  export declare class ErrSendKeysWhileRelayed extends AgentDirectorError {
254
280
  }
255
281
  /** Mirrors ErrSpawnNotPausable (package: api) */
@@ -273,6 +299,9 @@ export declare class ErrTemplateMalformed extends AgentDirectorError {
273
299
  /** Mirrors ErrTemplateExists (package: config) */
274
300
  export declare class ErrTemplateExists extends AgentDirectorError {
275
301
  }
302
+ /** Mirrors ErrTemplateAgentMissing (package: config) */
303
+ export declare class ErrTemplateAgentMissing extends AgentDirectorError {
304
+ }
276
305
  /** Mirrors ErrProbeUnsupported (package: probe) */
277
306
  export declare class ErrProbeUnsupported extends AgentDirectorError {
278
307
  }
@@ -291,9 +320,47 @@ export declare class ErrJsonlNeverWritten extends AgentDirectorError {
291
320
  /** Mirrors ErrRelayModeOff (package: api) */
292
321
  export declare class ErrRelayModeOff extends AgentDirectorError {
293
322
  }
294
- /** 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
+ */
295
331
  export declare class ErrRelayFallenBack extends AgentDirectorError {
296
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
+ }
297
364
  /** Mirrors ErrInvalidDecision (package: api) */
298
365
  export declare class ErrInvalidDecision extends AgentDirectorError {
299
366
  }
@@ -309,12 +376,51 @@ export declare class ErrPermissionRequestNotFound extends AgentDirectorError {
309
376
  /** Mirrors ErrAmbiguousRequest (package: store) */
310
377
  export declare class ErrAmbiguousRequest extends AgentDirectorError {
311
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
+ }
312
386
  /** Mirrors ErrMissingRequestToken (package: api) */
313
387
  export declare class ErrMissingRequestToken extends AgentDirectorError {
314
388
  }
315
389
  /** Mirrors ErrInvalidFlags (package: api) */
316
390
  export declare class ErrInvalidFlags extends AgentDirectorError {
317
391
  }
392
+ /** Mirrors ErrConfigMalformed (package: clisetup) */
393
+ export declare class ErrConfigMalformed extends AgentDirectorError {
394
+ }
395
+ /** Mirrors ErrStoreOpen (package: clisetup) */
396
+ export declare class ErrStoreOpen extends AgentDirectorError {
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
+ }
318
424
  /**
319
425
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
320
426
  * subprocess error envelope fields.
@@ -322,7 +428,8 @@ export declare class ErrInvalidFlags extends AgentDirectorError {
322
428
  * @param verb The verb name that produced the error (e.g. "spawn").
323
429
  * @param err_name The canonical error name from the envelope.
324
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).
325
432
  * @returns A typed subclass when err_name matches the catalog; a plain
326
433
  * AgentDirectorError (with a console.warn) for unknown names.
327
434
  */
328
- 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, } 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";