agent-director 0.8.0 → 0.10.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
@@ -257,7 +257,7 @@ Minimum: `>=1.0.21` (set in `engines.bun`). Tested on Bun 1.3.x as of this relea
257
257
 
258
258
  ## Errors
259
259
 
260
- Every error thrown by this package extends `AgentDirectorError`. A typed subclass is generated for each `err_name` in the shared catalog so you can catch by subclass:
260
+ Every error thrown by this package extends `AgentDirectorError`, so you can catch by subclass with `instanceof`:
261
261
 
262
262
  ```ts
263
263
  import { Client, ErrSpawnNotFound } from "agent-director";
@@ -272,27 +272,132 @@ try {
272
272
  }
273
273
  ```
274
274
 
275
- Errors thrown at construction time by `Client.create()` and `resolveSystemBinary()`:
275
+ The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the raw generated catalog for the group-4 classes lives in [`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json).
276
276
 
277
- | Error | When |
277
+ ### Realistic catch-site shortlist
278
+
279
+ Most services only need to route on the "agent-director is sick" set. Alert on these six and let everything else propagate:
280
+
281
+ - `ErrSystemInstallNotFound`
282
+ - `ErrSystemInstallTooOld`
283
+ - `ErrSystemInstallUnreachable`
284
+ - `ErrCallerCwdUnreachable`
285
+ - `ErrSystemInstallDisappeared`
286
+ - `ErrCallTimeout`
287
+
288
+ Everything else is either **programmer error** (bad arguments — fix the call site, do not retry) or a **normal operational signal** (an expected verb outcome you branch on, like "no such spawn" or "already decided"). `ErrConsumerSignal` sits in between: it is a runtime infrastructure failure, but a routine one during shutdown, so treat it as an operational signal rather than a page.
289
+
290
+ ### 1. Library lifecycle
291
+
292
+ Raised by the client wrapper itself, independent of any agent-director binary.
293
+
294
+ | Error | When it fires |
278
295
  |---|---|
279
- | `ErrSystemInstallNotFound` | No agent-director binary found on disk. |
280
- | `ErrSystemInstallTooOld` | Binary exists but is below the minimum required version. |
281
- | `ErrSystemInstallUnreachable` | Binary exists but failed validation or the version probe. |
282
- | `ErrCallerCwdUnreachable` | `process.cwd()` does not resolve to a real directory. Restart your service from a valid directory. |
296
+ | `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
297
+ | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Upgrade Bun. Fires at construction. |
283
298
 
284
- ### Errors a long-lived client must handle
299
+ ### 2. System install (agent-director binary)
285
300
 
286
- Long-lived clients (services that hold a `Client` instance across many verb calls) can encounter these errors at verb-dispatch time, after construction succeeded:
301
+ The "AD is sick" group. **Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
287
302
 
288
- | Error | When | Remediation |
303
+ | Error | Phase | When it fires |
289
304
  |---|---|---|
290
- | `ErrSystemInstallDisappeared` | The binary path resolved at construction no longer exists — e.g. the binary was uninstalled or replaced mid-flight. Carries `binaryPath` and `verb`. | Re-install the agent-director binary, then create a new `Client`. |
291
- | `ErrCallerCwdUnreachable` | The process working directory has disappeared since the client was constructed. Same class as the construction-time variant (see b.cot); here it is detected at the first verb call that follows the cwd disappearing. Carries `cwd` and `cause`. | Restart your service from a valid working directory. |
305
+ | `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
306
+ | `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
307
+ | `ErrSystemInstallUnreachable` | Construction | A binary was found but failed the version probe (not executable, wrong arch, non-zero exit, killed). Carries `binaryPath`, `reason`, `diagnostic`, `exitCode`, `signal`. |
308
+ | `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. Restart your service from a valid directory. |
309
+ | `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Re-install the binary, then create a new `Client`. |
310
+
311
+ ### 3. Per-call infrastructure
312
+
313
+ Thrown per verb call by the subprocess transport, not by the CLI's own validation.
314
+
315
+ | Error | When it fires | Category |
316
+ |---|---|---|
317
+ | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational — include in your "AD is sick" alert set. |
318
+ | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
319
+ | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client version does not recognize (client older than the binary). Carries `unknownName`, `envelope`. | Programmer/version error — upgrade the client. |
320
+
321
+ ### 4. Catalog-derived (CLI-side validation)
322
+
323
+ These 37 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input or a verb's own state preconditions — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
324
+
325
+ **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
326
+
327
+ | Error | When it fires |
328
+ |---|---|
329
+ | `ErrCwdMissing` | No `cwd` was supplied; spawn requires it to derive the JSONL/resume path. |
330
+ | `ErrCwdNotAPath` | `cwd` is neither absolute nor a `~/` form (URLs, bare relative paths, non-path values). |
331
+ | `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
332
+ | `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
292
333
 
293
- Both errors extend `AgentDirectorError` and are catchable with `instanceof`.
334
+ **spawn config validation** (bad `spawn` arguments — programmer error):
294
335
 
295
- The full `err_name` catalog is in [`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json).
336
+ | Error | When it fires |
337
+ |---|---|
338
+ | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
339
+ | `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
340
+ | `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
341
+ | `ErrInstanceIdCollision` | The supplied `claude_instance_id` is already in use by a live spawn. |
342
+
343
+ **tmux session naming** (bad `--tmux-session-name` — programmer error):
344
+
345
+ | Error | When it fires |
346
+ |---|---|
347
+ | `ErrTmuxSessionNameEmpty` | `--tmux-session-name` was explicitly supplied but empty. |
348
+ | `ErrTmuxSessionNameInvalid` | The name contains `#`, `:`, `.`, an ASCII control character, or is invalid UTF-8. |
349
+ | `ErrTmuxSessionNameTooLong` | The name exceeds the app-layer byte cap. |
350
+
351
+ **spawn state / lookup** (verb preconditions — mostly normal operational signals):
352
+
353
+ | Error | When it fires |
354
+ |---|---|
355
+ | `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
356
+ | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected (`AllowPending=true` relaxes the `pending` rejection). |
357
+ | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
358
+ | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry or `kill`. |
359
+ | `ErrSpawnNotResumable` | The target spawn is not terminal (`ended`/`missing`), so it cannot be resumed. |
360
+ | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — `delete` and spawn fresh. |
361
+ | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — `delete` and spawn fresh. |
362
+ | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
363
+ | `ErrProbeUnsupported` | The liveness probe has no implementation for the current platform (`find-missing`). |
364
+
365
+ **tmux transport** (infrastructure failures at the tmux layer — runtime):
366
+
367
+ | Error | When it fires |
368
+ |---|---|
369
+ | `ErrTmuxNotAvailable` | The `tmux` binary is not on PATH or refuses to execute. |
370
+ | `ErrTmuxSessionCreate` | `tmux new-session` exited non-zero (name collision, invalid cwd, missing default-shell). |
371
+ | `ErrTmuxSendKeys` | `tmux send-keys` exited non-zero (typically no live pane). |
372
+ | `ErrTmuxCaptureFailed` | `tmux capture-pane` exited non-zero (session/pane vanished mid-call). |
373
+
374
+ **relay / permissions** (relay-mode and permission-decision preconditions — normal operational signals):
375
+
376
+ | Error | When it fires |
377
+ |---|---|
378
+ | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. |
379
+ | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
380
+ | `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
381
+ | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
382
+ | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was already decided). |
383
+ | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. |
384
+ | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
385
+ | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
386
+
387
+ **config templates** (template-management verbs — mixed programmer error / operational signal):
388
+
389
+ | Error | When it fires |
390
+ |---|---|
391
+ | `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
392
+ | `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
393
+ | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
394
+ | `ErrTemplateExists` | `make-template` target already exists; the verb never overwrites. |
395
+
396
+ **misc**:
397
+
398
+ | Error | When it fires |
399
+ |---|---|
400
+ | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; not tied to any single verb handler. |
296
401
 
297
402
  ## Architecture
298
403
 
package/dist/errors.d.ts CHANGED
@@ -276,9 +276,15 @@ export declare class ErrNoSessionId extends AgentDirectorError {
276
276
  /** Mirrors ErrJsonlMissing (package: api) */
277
277
  export declare class ErrJsonlMissing extends AgentDirectorError {
278
278
  }
279
+ /** Mirrors ErrJsonlNeverWritten (package: api) */
280
+ export declare class ErrJsonlNeverWritten extends AgentDirectorError {
281
+ }
279
282
  /** Mirrors ErrRelayModeOff (package: api) */
280
283
  export declare class ErrRelayModeOff extends AgentDirectorError {
281
284
  }
285
+ /** Mirrors ErrRelayFallenBack (package: api) */
286
+ export declare class ErrRelayFallenBack extends AgentDirectorError {
287
+ }
282
288
  /** Mirrors ErrInvalidDecision (package: api) */
283
289
  export declare class ErrInvalidDecision extends AgentDirectorError {
284
290
  }
package/dist/index.d.ts CHANGED
@@ -7,7 +7,7 @@ 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, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrRelayModeOff, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrPermissionRequestNotFound, ErrAmbiguousRequest, ErrMissingRequestToken, ErrInvalidFlags, } from "./errors.js";
10
+ ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, 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";
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 } from "./types.js";
package/dist/index.js CHANGED
@@ -52,6 +52,7 @@ __export(exports_errors, {
52
52
  ErrReservedEnvKey: () => ErrReservedEnvKey,
53
53
  ErrRelayModeOff: () => ErrRelayModeOff,
54
54
  ErrRelayModeInvalid: () => ErrRelayModeInvalid,
55
+ ErrRelayFallenBack: () => ErrRelayFallenBack,
55
56
  ErrProbeUnsupported: () => ErrProbeUnsupported,
56
57
  ErrPermissionRequestNotFound: () => ErrPermissionRequestNotFound,
57
58
  ErrPauseTimeout: () => ErrPauseTimeout,
@@ -59,6 +60,7 @@ __export(exports_errors, {
59
60
  ErrNoOpenPermissionRequest: () => ErrNoOpenPermissionRequest,
60
61
  ErrMissingRequestToken: () => ErrMissingRequestToken,
61
62
  ErrListInvalidLabel: () => ErrListInvalidLabel,
63
+ ErrJsonlNeverWritten: () => ErrJsonlNeverWritten,
62
64
  ErrJsonlMissing: () => ErrJsonlMissing,
63
65
  ErrInvalidFlags: () => ErrInvalidFlags,
64
66
  ErrInvalidDecision: () => ErrInvalidDecision,
@@ -108,7 +110,7 @@ class AgentDirectorError extends Error {
108
110
 
109
111
  class ErrClientClosed extends AgentDirectorError {
110
112
  constructor() {
111
- super("", "ErrClientClosed", "client is closed: call new Client() to obtain a fresh handle");
113
+ super("", "ErrClientClosed", "client is closed: call Client.create() to obtain a fresh handle");
112
114
  this.name = "ErrClientClosed";
113
115
  Object.setPrototypeOf(this, new.target.prototype);
114
116
  }
@@ -325,9 +327,15 @@ class ErrNoSessionId extends AgentDirectorError {
325
327
  class ErrJsonlMissing extends AgentDirectorError {
326
328
  }
327
329
 
330
+ class ErrJsonlNeverWritten extends AgentDirectorError {
331
+ }
332
+
328
333
  class ErrRelayModeOff extends AgentDirectorError {
329
334
  }
330
335
 
336
+ class ErrRelayFallenBack extends AgentDirectorError {
337
+ }
338
+
331
339
  class ErrInvalidDecision extends AgentDirectorError {
332
340
  }
333
341
 
@@ -377,7 +385,9 @@ var ERROR_TABLE = {
377
385
  ErrSpawnNotResumable,
378
386
  ErrNoSessionId,
379
387
  ErrJsonlMissing,
388
+ ErrJsonlNeverWritten,
380
389
  ErrRelayModeOff,
390
+ ErrRelayFallenBack,
381
391
  ErrInvalidDecision,
382
392
  ErrMissingRequestToken,
383
393
  ErrInvalidFlags,
@@ -1195,11 +1205,21 @@ var catalog_default = [
1195
1205
  package: "api",
1196
1206
  description: ""
1197
1207
  },
1208
+ {
1209
+ name: "ErrJsonlNeverWritten",
1210
+ package: "api",
1211
+ description: ""
1212
+ },
1198
1213
  {
1199
1214
  name: "ErrRelayModeOff",
1200
1215
  package: "api",
1201
1216
  description: ""
1202
1217
  },
1218
+ {
1219
+ name: "ErrRelayFallenBack",
1220
+ package: "api",
1221
+ description: ""
1222
+ },
1203
1223
  {
1204
1224
  name: "ErrInvalidDecision",
1205
1225
  package: "api",
@@ -1639,6 +1659,7 @@ export {
1639
1659
  ErrReservedEnvKey,
1640
1660
  ErrRelayModeOff,
1641
1661
  ErrRelayModeInvalid,
1662
+ ErrRelayFallenBack,
1642
1663
  ErrProbeUnsupported,
1643
1664
  ErrPermissionRequestNotFound,
1644
1665
  ErrPauseTimeout,
@@ -1646,6 +1667,7 @@ export {
1646
1667
  ErrNoOpenPermissionRequest,
1647
1668
  ErrMissingRequestToken,
1648
1669
  ErrListInvalidLabel,
1670
+ ErrJsonlNeverWritten,
1649
1671
  ErrJsonlMissing,
1650
1672
  ErrInvalidFlags,
1651
1673
  ErrInvalidDecision,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],