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 +119 -14
- package/dist/errors.d.ts +3 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +12 -1
- package/dist/types.d.ts +15 -0
- package/package.json +1 -1
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
280
|
-
| `
|
|
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
|
-
###
|
|
299
|
+
### 2. System install (agent-director binary)
|
|
285
300
|
|
|
286
|
-
|
|
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 |
|
|
303
|
+
| Error | Phase | When it fires |
|
|
289
304
|
|---|---|---|
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
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
|
-
|
|
334
|
+
**spawn config validation** (bad `spawn` arguments — programmer error):
|
|
294
335
|
|
|
295
|
-
|
|
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
|
|
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 {
|