agent-director 0.7.8 → 0.9.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
@@ -279,6 +279,9 @@ export declare class ErrJsonlMissing extends AgentDirectorError {
279
279
  /** Mirrors ErrRelayModeOff (package: api) */
280
280
  export declare class ErrRelayModeOff extends AgentDirectorError {
281
281
  }
282
+ /** Mirrors ErrRelayFallenBack (package: api) */
283
+ export declare class ErrRelayFallenBack extends AgentDirectorError {
284
+ }
282
285
  /** Mirrors ErrInvalidDecision (package: api) */
283
286
  export declare class ErrInvalidDecision extends AgentDirectorError {
284
287
  }
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, 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,
@@ -108,7 +109,7 @@ class AgentDirectorError extends Error {
108
109
 
109
110
  class ErrClientClosed extends AgentDirectorError {
110
111
  constructor() {
111
- super("", "ErrClientClosed", "client is closed: call new Client() to obtain a fresh handle");
112
+ super("", "ErrClientClosed", "client is closed: call Client.create() to obtain a fresh handle");
112
113
  this.name = "ErrClientClosed";
113
114
  Object.setPrototypeOf(this, new.target.prototype);
114
115
  }
@@ -328,6 +329,9 @@ class ErrJsonlMissing extends AgentDirectorError {
328
329
  class ErrRelayModeOff extends AgentDirectorError {
329
330
  }
330
331
 
332
+ class ErrRelayFallenBack extends AgentDirectorError {
333
+ }
334
+
331
335
  class ErrInvalidDecision extends AgentDirectorError {
332
336
  }
333
337
 
@@ -378,6 +382,7 @@ var ERROR_TABLE = {
378
382
  ErrNoSessionId,
379
383
  ErrJsonlMissing,
380
384
  ErrRelayModeOff,
385
+ ErrRelayFallenBack,
381
386
  ErrInvalidDecision,
382
387
  ErrMissingRequestToken,
383
388
  ErrInvalidFlags,
@@ -1200,6 +1205,11 @@ var catalog_default = [
1200
1205
  package: "api",
1201
1206
  description: ""
1202
1207
  },
1208
+ {
1209
+ name: "ErrRelayFallenBack",
1210
+ package: "api",
1211
+ description: ""
1212
+ },
1203
1213
  {
1204
1214
  name: "ErrInvalidDecision",
1205
1215
  package: "api",
@@ -1639,6 +1649,7 @@ export {
1639
1649
  ErrReservedEnvKey,
1640
1650
  ErrRelayModeOff,
1641
1651
  ErrRelayModeInvalid,
1652
+ ErrRelayFallenBack,
1642
1653
  ErrProbeUnsupported,
1643
1654
  ErrPermissionRequestNotFound,
1644
1655
  ErrPauseTimeout,
package/dist/types.d.ts CHANGED
@@ -115,6 +115,10 @@ export interface ListRow {
115
115
  last_seen_at: string;
116
116
  /** Set when state moves to ended (omitted while live). */
117
117
  ended_at?: string | null;
118
+ /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
119
+ liveness_unverified_since?: string | null;
120
+ /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
121
+ liveness_note?: string | null;
118
122
  }
119
123
  /** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
120
124
  export interface SpawnParams {
@@ -181,6 +185,10 @@ export interface GetResult {
181
185
  last_seen_at: string;
182
186
  /** Set when state moves to ended; omitted while live. */
183
187
  ended_at?: string | null;
188
+ /** RFC3339 timestamp of the first sweep that could not verify this live row's liveness; omitted/null when never unverified. */
189
+ liveness_unverified_since?: string | null;
190
+ /** Human-readable reason liveness could not be verified; omitted/null when never unverified. */
191
+ liveness_note?: string | null;
184
192
  /** Open permission request; present only when state=check_permission with an undecided row. */
185
193
  permission_request?: PermissionRequestInfo | null;
186
194
  }
@@ -286,6 +294,13 @@ export interface FindMissingResult {
286
294
  count: number;
287
295
  /** Sorted ids of rows transitioned to missing. */
288
296
  ids: string[];
297
+ /**
298
+ * Number of live rows left untouched this sweep because their liveness
299
+ * could not be established (an unknown verdict, e.g. a permission wall).
300
+ */
301
+ unverified: number;
302
+ /** Sorted ids of rows left untouched as unverified. Non-nil; [] when none. */
303
+ unverified_ids: string[];
289
304
  }
290
305
  /** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
291
306
  export interface ExpireParams {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.7.8",
3
+ "version": "0.9.0",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],