agent-director 0.7.7 → 0.7.8

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
@@ -272,6 +272,26 @@ try {
272
272
  }
273
273
  ```
274
274
 
275
+ Errors thrown at construction time by `Client.create()` and `resolveSystemBinary()`:
276
+
277
+ | Error | When |
278
+ |---|---|
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. |
283
+
284
+ ### Errors a long-lived client must handle
285
+
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:
287
+
288
+ | Error | When | Remediation |
289
+ |---|---|---|
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. |
292
+
293
+ Both errors extend `AgentDirectorError` and are catchable with `instanceof`.
294
+
275
295
  The full `err_name` catalog is in [`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json).
276
296
 
277
297
  ## Architecture
package/dist/client.d.ts CHANGED
@@ -9,10 +9,11 @@
9
9
  * PATH lookup), validates the candidate, probes its version, compares
10
10
  * against MIN_BINARY_VERSION, and only then allocates the underlying
11
11
  * SubprocessClient. Each failure mode surfaces as one of:
12
- * - ErrBunVersionTooOld (Bun runtime below MIN_BUN_VERSION)
13
- * - ErrSystemInstallNotFound (no candidate exists)
14
- * - ErrSystemInstallTooOld (candidate is below floor)
15
- * - ErrSystemInstallUnreachable (candidate failed validation or probe)
12
+ * - ErrBunVersionTooOld (Bun runtime below MIN_BUN_VERSION)
13
+ * - ErrSystemInstallNotFound (no candidate exists)
14
+ * - ErrSystemInstallTooOld (candidate is below floor)
15
+ * - ErrSystemInstallUnreachable (candidate failed validation or probe)
16
+ * - ErrCallerCwdUnreachable (caller's process.cwd() is gone — b.cot)
16
17
  *
17
18
  * The DI hatch `_cliPath` (SR-4.1) skips discovery, canonicalizes the
18
19
  * injected path, and runs the probe so that `binaryPath` and `binaryVersion`
@@ -40,6 +41,7 @@ export declare class Client extends SubprocessClient {
40
41
  * - ErrSystemInstallNotFound
41
42
  * - ErrSystemInstallTooOld
42
43
  * - ErrSystemInstallUnreachable
44
+ * - ErrCallerCwdUnreachable (b.cot — caller's process.cwd() is gone)
43
45
  */
44
46
  static create(opts?: ClientOptions): Promise<Client>;
45
47
  }
@@ -63,11 +65,12 @@ export interface ResolveSystemBinaryOptions {
63
65
  * Runs the same SR-1.1 → SR-2.3 pipeline as Client.create() and resolves
64
66
  * with `{ path, version }`. No Client is allocated, no cache is warmed.
65
67
  *
66
- * Rejects with the same four error classes as Client.create():
68
+ * Rejects with the same error classes as Client.create():
67
69
  * - ErrBunVersionTooOld
68
70
  * - ErrSystemInstallNotFound
69
71
  * - ErrSystemInstallTooOld
70
72
  * - ErrSystemInstallUnreachable
73
+ * - ErrCallerCwdUnreachable (b.cot — caller's process.cwd() is gone)
71
74
  */
72
75
  export declare function resolveSystemBinary(_opts?: ResolveSystemBinaryOptions): Promise<ResolveSystemBinaryResult>;
73
76
  export { MIN_BUN_VERSION };
package/dist/errors.d.ts CHANGED
@@ -152,6 +152,43 @@ export declare class ErrSystemInstallUnreachable extends AgentDirectorError {
152
152
  signal?: string | null;
153
153
  });
154
154
  }
155
+ /**
156
+ * ErrCallerCwdUnreachable — thrown by Client.create() / resolveSystemBinary()
157
+ * when the caller's process.cwd() does not resolve to a real directory at
158
+ * construction time. AD subprocess calls inherit cwd from the caller; if the
159
+ * cwd is gone every spawn fails with a misleading ENOENT on the binary path.
160
+ * Fail-fast here so the error is surfaced at the construction boundary.
161
+ *
162
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
163
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES` so the
164
+ * catalog-drift test never flags it as an unexpected class. Cross-ref: b.cot.
165
+ */
166
+ export declare class ErrCallerCwdUnreachable extends AgentDirectorError {
167
+ /** The offending cwd path the constructor was told about. */
168
+ readonly cwd: string;
169
+ /** The underlying error caught when statting (preserved for debugging). */
170
+ readonly cause: unknown;
171
+ constructor(cwd: string, cause?: unknown);
172
+ }
173
+ /**
174
+ * ErrSystemInstallDisappeared — thrown by SubprocessClient#doCall when
175
+ * Bun.spawn fails with ENOENT and a subsequent statSync confirms the
176
+ * resolved AD binary path no longer exists on disk. Distinct from
177
+ * ErrSystemInstallNotFound (which fires at Client.create() when the binary
178
+ * was never found) by lifecycle: this error fires mid-life, after a
179
+ * previously-valid binary has disappeared.
180
+ *
181
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
182
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES` so the
183
+ * catalog-drift test never flags it as an unexpected class. Cross-ref: b.xht.
184
+ */
185
+ export declare class ErrSystemInstallDisappeared extends AgentDirectorError {
186
+ /** The binary path that was confirmed missing. */
187
+ readonly binaryPath: string;
188
+ /** The underlying error caught when spawning (preserved for debugging). */
189
+ readonly cause: unknown;
190
+ constructor(verb: string, binaryPath: string, cause?: unknown);
191
+ }
155
192
  /** Mirrors ErrCwdMissing (package: spawn) */
156
193
  export declare class ErrCwdMissing extends AgentDirectorError {
157
194
  }
package/dist/index.d.ts CHANGED
@@ -5,7 +5,9 @@ export { Client } from "./client.js";
5
5
  export { resolveSystemBinary } from "./client.js";
6
6
  export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./client.js";
7
7
  export { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION, } from "./internal/constants.js";
8
- export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, 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";
8
+ export { AgentDirectorError, ErrClientClosed, ErrBunVersionTooOld, ErrSystemInstallNotFound, ErrSystemInstallTooOld, ErrSystemInstallUnreachable, ErrCallerCwdUnreachable, // b.cot — fail-fast when caller's cwd is unreachable
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";
9
11
  export type { CheckedLocation, UnreachableReason } from "./errors.js";
10
12
  export type { ClientOptions, Logger } from "./types.js";
11
13
  export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
package/dist/index.js CHANGED
@@ -14,6 +14,9 @@ var __export = (target, all) => {
14
14
  });
15
15
  };
16
16
 
17
+ // src/client.ts
18
+ import { statSync as statSync3 } from "fs";
19
+
17
20
  // src/internal/discovery.ts
18
21
  import { statSync, realpathSync, accessSync, constants as fsConstants } from "fs";
19
22
  import { resolve, isAbsolute, join, dirname } from "path";
@@ -39,6 +42,7 @@ __export(exports_errors, {
39
42
  ErrSystemInstallUnreachable: () => ErrSystemInstallUnreachable,
40
43
  ErrSystemInstallTooOld: () => ErrSystemInstallTooOld,
41
44
  ErrSystemInstallNotFound: () => ErrSystemInstallNotFound,
45
+ ErrSystemInstallDisappeared: () => ErrSystemInstallDisappeared,
42
46
  ErrSpawnNotResumable: () => ErrSpawnNotResumable,
43
47
  ErrSpawnNotPausable: () => ErrSpawnNotPausable,
44
48
  ErrSpawnNotInteractive: () => ErrSpawnNotInteractive,
@@ -65,6 +69,7 @@ __export(exports_errors, {
65
69
  ErrCwdMissing: () => ErrCwdMissing,
66
70
  ErrConsumerSignal: () => ErrConsumerSignal,
67
71
  ErrClientClosed: () => ErrClientClosed,
72
+ ErrCallerCwdUnreachable: () => ErrCallerCwdUnreachable,
68
73
  ErrCallTimeout: () => ErrCallTimeout,
69
74
  ErrBunVersionTooOld: () => ErrBunVersionTooOld,
70
75
  ErrAmbiguousRequest: () => ErrAmbiguousRequest,
@@ -81,7 +86,9 @@ var TS_ONLY_ERROR_NAMES = [
81
86
  "ErrUnknownErrorName",
82
87
  "ErrSystemInstallNotFound",
83
88
  "ErrSystemInstallTooOld",
84
- "ErrSystemInstallUnreachable"
89
+ "ErrSystemInstallUnreachable",
90
+ "ErrCallerCwdUnreachable",
91
+ "ErrSystemInstallDisappeared"
85
92
  ];
86
93
 
87
94
  // src/errors.ts
@@ -206,6 +213,31 @@ class ErrSystemInstallUnreachable extends AgentDirectorError {
206
213
  }
207
214
  }
208
215
 
216
+ class ErrCallerCwdUnreachable extends AgentDirectorError {
217
+ cwd;
218
+ cause;
219
+ constructor(cwd, cause) {
220
+ const causeMsg = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : String(cause ?? "unknown");
221
+ super("", "ErrCallerCwdUnreachable", `process working directory ${cwd} is unreachable: ${causeMsg}. AD subprocess calls inherit cwd from the caller and will fail. Restart your service from a valid directory.`);
222
+ this.cwd = cwd;
223
+ this.cause = cause ?? null;
224
+ this.name = "ErrCallerCwdUnreachable";
225
+ Object.setPrototypeOf(this, new.target.prototype);
226
+ }
227
+ }
228
+
229
+ class ErrSystemInstallDisappeared extends AgentDirectorError {
230
+ binaryPath;
231
+ cause;
232
+ constructor(verb, binaryPath, cause) {
233
+ super(verb, "ErrSystemInstallDisappeared", `agent-director binary at ${binaryPath} has disappeared since Client construction; the file no longer exists`);
234
+ this.binaryPath = binaryPath;
235
+ this.cause = cause ?? null;
236
+ this.name = "ErrSystemInstallDisappeared";
237
+ Object.setPrototypeOf(this, new.target.prototype);
238
+ }
239
+ }
240
+
209
241
  class ErrCwdMissing extends AgentDirectorError {
210
242
  }
211
243
 
@@ -763,6 +795,7 @@ function checkBunVersion() {
763
795
 
764
796
  // src/internal/subprocessClient.ts
765
797
  import { readFile } from "fs/promises";
798
+ import { statSync as statSync2 } from "fs";
766
799
 
767
800
  // src/internal/tilde.ts
768
801
  import * as os from "os";
@@ -1317,14 +1350,45 @@ class SubprocessClient {
1317
1350
  const argv = buildArgv(cliPath, verb, params, this.#globalOpts);
1318
1351
  const startMs = Date.now();
1319
1352
  const spawnEnv = { ...process.env };
1320
- const proc = Bun.spawn({
1321
- cmd: argv,
1322
- stdin: "pipe",
1323
- stdout: "pipe",
1324
- stderr: "pipe",
1325
- detached: false,
1326
- env: spawnEnv
1327
- });
1353
+ let proc;
1354
+ try {
1355
+ proc = Bun.spawn({
1356
+ cmd: argv,
1357
+ stdin: "pipe",
1358
+ stdout: "pipe",
1359
+ stderr: "pipe",
1360
+ detached: false,
1361
+ env: spawnEnv
1362
+ });
1363
+ } catch (err) {
1364
+ if (err instanceof Error && err.code === "ENOENT") {
1365
+ let bucket1Fired = false;
1366
+ try {
1367
+ const st = statSync2(this.#binaryPath);
1368
+ if (!st.isFile()) {
1369
+ bucket1Fired = true;
1370
+ }
1371
+ } catch (statErr) {
1372
+ if (statErr instanceof Error && statErr.code === "ENOENT") {
1373
+ bucket1Fired = true;
1374
+ }
1375
+ }
1376
+ if (bucket1Fired) {
1377
+ throw new ErrSystemInstallDisappeared(verb, this.#binaryPath, err);
1378
+ }
1379
+ let cwd;
1380
+ try {
1381
+ cwd = process.cwd();
1382
+ const st = statSync2(cwd);
1383
+ if (!st.isDirectory())
1384
+ throw new Error("not a directory");
1385
+ } catch (cwdErr) {
1386
+ throw new ErrCallerCwdUnreachable(cwd ?? "<process.cwd() unavailable>", cwdErr);
1387
+ }
1388
+ throw err;
1389
+ }
1390
+ throw err;
1391
+ }
1328
1392
  proc.stdin.end();
1329
1393
  let timedOut = false;
1330
1394
  const timeoutHandle = setTimeout(() => {
@@ -1460,6 +1524,19 @@ class SubprocessClient {
1460
1524
  }
1461
1525
 
1462
1526
  // src/client.ts
1527
+ function assertCallerCwdReachable() {
1528
+ let cwd;
1529
+ try {
1530
+ cwd = process.cwd();
1531
+ const st = statSync3(cwd);
1532
+ if (!st.isDirectory())
1533
+ throw new Error("not a directory");
1534
+ } catch (err) {
1535
+ if (err instanceof ErrCallerCwdUnreachable)
1536
+ throw err;
1537
+ throw new ErrCallerCwdUnreachable(typeof cwd === "string" ? cwd : "<process.cwd() unavailable>", err);
1538
+ }
1539
+ }
1463
1540
  class Client extends SubprocessClient {
1464
1541
  static async create(opts = {}) {
1465
1542
  checkBunVersion();
@@ -1495,6 +1572,7 @@ class Client extends SubprocessClient {
1495
1572
  if (compareParsed(probed.value, floor.value) < 0) {
1496
1573
  throw new ErrSystemInstallTooOld(probe.version, MIN_BINARY_VERSION, binaryPath);
1497
1574
  }
1575
+ assertCallerCwdReachable();
1498
1576
  return new Client(opts, {
1499
1577
  binaryPath,
1500
1578
  binaryVersion: probe.version
@@ -1529,6 +1607,7 @@ async function resolveSystemBinary(_opts = {}) {
1529
1607
  if (compareParsed(probed.value, floor.value) < 0) {
1530
1608
  throw new ErrSystemInstallTooOld(probe.version, MIN_BINARY_VERSION, binaryPath);
1531
1609
  }
1610
+ assertCallerCwdReachable();
1532
1611
  return { path: binaryPath, version: probe.version };
1533
1612
  }
1534
1613
  export {
@@ -1550,6 +1629,7 @@ export {
1550
1629
  ErrSystemInstallUnreachable,
1551
1630
  ErrSystemInstallTooOld,
1552
1631
  ErrSystemInstallNotFound,
1632
+ ErrSystemInstallDisappeared,
1553
1633
  ErrSpawnNotResumable,
1554
1634
  ErrSpawnNotPausable,
1555
1635
  ErrSpawnNotInteractive,
@@ -1576,6 +1656,7 @@ export {
1576
1656
  ErrCwdMissing,
1577
1657
  ErrConsumerSignal,
1578
1658
  ErrClientClosed,
1659
+ ErrCallerCwdUnreachable,
1579
1660
  ErrCallTimeout,
1580
1661
  ErrBunVersionTooOld,
1581
1662
  ErrAmbiguousRequest,
@@ -45,6 +45,14 @@ export interface InternalClientInit {
45
45
  *
46
46
  * Constructed via Client.create() — the public surface. The runtime
47
47
  * constructor is private; tests reach instances only through the factory.
48
+ *
49
+ * Spawn-time failure buckets (b.xht):
50
+ * 1. Binary gone — Bun.spawn throws ENOENT and statSync(binaryPath) fails
51
+ * → ErrSystemInstallDisappeared
52
+ * 2. CWD gone — Bun.spawn throws ENOENT and statSync(process.cwd()) fails
53
+ * (or process.cwd() itself throws) → ErrCallerCwdUnreachable
54
+ * 3. Neither / other — re-thrown as-is so it surfaces via the ErrSubprocessCrash
55
+ * path or as the original error.
48
56
  */
49
57
  export declare class SubprocessClient {
50
58
  #private;
@@ -20,6 +20,8 @@
20
20
  * - ErrSystemInstallNotFound — discovery found no AD binary (b.ue3 / SR-3.1).
21
21
  * - ErrSystemInstallTooOld — discovered binary is below floor (b.ue3 / SR-3.2).
22
22
  * - ErrSystemInstallUnreachable — discovered binary failed probe (b.ue3 / SR-3.3).
23
+ * - ErrCallerCwdUnreachable — caller's process.cwd() is gone at construction (b.cot).
24
+ * - ErrSystemInstallDisappeared — binary gone at verb-dispatch time, after valid construction (b.xht).
23
25
  *
24
26
  * Removed in b.ue3 (vendored-binary surface dropped):
25
27
  * - ErrUnsupportedPlatform
@@ -29,6 +31,6 @@
29
31
  * When adding a new TS-only subclass: add its name here AND add a comment in
30
32
  * src/errors.ts near the subclass cross-referencing this allow-list.
31
33
  */
32
- export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrBunVersionTooOld", "ErrConsumerSignal", "ErrCallTimeout", "ErrUnknownErrorName", "ErrSystemInstallNotFound", "ErrSystemInstallTooOld", "ErrSystemInstallUnreachable"];
34
+ export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrBunVersionTooOld", "ErrConsumerSignal", "ErrCallTimeout", "ErrUnknownErrorName", "ErrSystemInstallNotFound", "ErrSystemInstallTooOld", "ErrSystemInstallUnreachable", "ErrCallerCwdUnreachable", "ErrSystemInstallDisappeared"];
33
35
  /** Type alias for the individual allow-listed names. */
34
36
  export type TsOnlyErrorName = (typeof TS_ONLY_ERROR_NAMES)[number];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.7.7",
3
+ "version": "0.7.8",
4
4
  "type": "module",
5
5
  "os": ["linux", "darwin"],
6
6
  "cpu": ["x64", "arm64"],