agent-director 0.6.3 → 0.7.1

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
@@ -1,8 +1,9 @@
1
1
  # agent-director
2
2
 
3
3
  TypeScript/Bun client for the agent-director CLI. Shares the Go API
4
- surface 1:1. The `Client` spawns the bundled `agent-director` CLI
5
- binary as a subprocess per verb call — no FFI, no network hop.
4
+ surface 1:1. The `Client` discovers the system-installed
5
+ `agent-director` CLI binary at construction time and drives it as a
6
+ subprocess per verb call — no FFI, no network hop, no bundled binary.
6
7
 
7
8
  ## Install
8
9
 
@@ -10,81 +11,33 @@ binary as a subprocess per verb call — no FFI, no network hop.
10
11
  bun add agent-director
11
12
  ```
12
13
 
13
- Requires Bun >=1.0.21. The package ships the prebuilt CLI binary for
14
- each supported platform via optional dependencies — they install
15
- automatically on `bun add`. The `Client` verifies the binary is present at construction time so install
16
- errors surface immediately, then re-resolves its path on every verb call so
17
- a binary replacement (e.g. a background `bun install`) is handled
18
- transparently.
14
+ Requires Bun >=1.0.21. The package ships pure JavaScript — there are
15
+ **no lifecycle scripts** (`postinstall`, `prepare`, etc.) and no
16
+ optional platform dependencies. `bun add --ignore-scripts agent-director`
17
+ is a no-op and installs the library with identical functionality.
19
18
 
20
- On install, a postinstall script copies the `install-agent-director` skill body into `~/.claude/skills/install-agent-director/` so `claude /install-agent-director` is immediately discoverable in Claude Code. The postinstall only writes under `~/.claude/skills/`; it does not touch PATH, `~/.agent-director/`, or your Claude Code settings.
21
-
22
- Bun blocks dependency postinstalls by default. Trust this package so the skill copy can run:
23
-
24
- ```sh
25
- bun pm trust agent-director
26
- ```
27
-
28
- Or pre-declare it in your `package.json` before `bun add`:
29
-
30
- ```json
31
- {
32
- "trustedDependencies": ["agent-director"]
33
- }
34
- ```
35
-
36
- ### Verbose install logs
37
-
38
- Set `AD_POSTINSTALL_VERBOSE=1` (also accepts `true` / `yes`, case-insensitive) before `bun add` to see what the postinstall resolved and decided. The default is quiet — five lines maximum.
39
-
40
- ### Skipping the postinstall
41
-
42
- `bun add --ignore-scripts agent-director` installs the library without running the postinstall. The skill is not copied. To get skill discoverability after the fact, either:
43
-
44
- ```sh
45
- cp -r node_modules/agent-director/skills/install-agent-director ~/.claude/skills/
46
- ```
47
-
48
- or, once the library is on disk, invoke `claude /install-agent-director` from any Claude Code session — the install skill copies itself into `~/.claude/skills/` as a side effect of running.
49
-
50
- ### How the postinstall decides whether to overwrite
51
-
52
- The skill body carries a `version:` field in its YAML frontmatter. On every install the postinstall reads the bundled version and the version already on disk:
53
-
54
- - **Same version** — no filesystem changes, no output.
55
- - **Older or missing on disk** — overwrite, leaving a timestamped `install-agent-director.bak.<unix-ts>` sibling under `~/.claude/skills/`.
56
- - **Newer on disk** — leave it alone, single-line warning to stderr.
57
-
58
- The authoritative behavior contract lives in Idea Bee `b.fg3`.
19
+ **You must separately install the CLI binary on the host.** Use
20
+ `install.sh` from the agent-director release tarball or any other
21
+ mechanism that drops an executable at `~/.agent-director/bin/agent-director`
22
+ or somewhere on `$PATH`. `Client.create()` discovers the binary at
23
+ construction time and rejects if it cannot find one.
59
24
 
60
25
  ## Supported platforms
61
26
 
62
- **Supported** — install + library + skill all work:
63
-
64
27
  - `linux/x64` (Linux on x86_64)
65
28
  - `darwin/arm64` (Apple Silicon Mac)
66
29
 
67
- **Refused at install time by npm/bun** — the umbrella's `os`/`cpu` fields fail resolution and no postinstall runs:
68
-
69
- - Windows (any architecture)
70
- - FreeBSD, OpenBSD, and other non-Linux/non-Darwin OSes
71
- - any architecture not in `[x64, arm64]` (e.g. `ia32`, `mips`, `arm`)
72
-
73
- **Refused by the postinstall after npm/bun admits the install** — the umbrella runs but the postinstall exits non-zero with an `agent-director: unsupported host` message before any filesystem write:
74
-
75
- - `darwin/x64` (Intel Mac)
76
- - `linux/arm64`
77
-
78
- The refusal is two-layered because npm/bun's `os` and `cpu` fields are a cross-product, not a per-pair set: the coarse gate cannot distinguish "supported pair" from "supported OS plus supported arch in any combination." The postinstall's host-pair check catches the two cross-product members that should not actually install.
79
-
80
- See Idea Bee `b.fg3` for cross-platform expansion status.
30
+ The library's published npm package admits installs on any host (no
31
+ `os`/`cpu` restrictions on the library itself); the platform gate is
32
+ the CLI binary's own platform coverage. The CLI must be installed
33
+ separately per the platform list above.
81
34
 
82
35
  ## Quick start
83
36
 
84
37
  `using` block (preferred):
85
38
 
86
39
  ```ts
87
- using client = new Client({});
40
+ using client = await Client.create({});
88
41
  const v = await client.version({});
89
42
  console.log(v.version);
90
43
  ```
@@ -92,7 +45,7 @@ console.log(v.version);
92
45
  Explicit `try/finally` (portable fallback):
93
46
 
94
47
  ```ts
95
- const client = new Client({});
48
+ const client = await Client.create({});
96
49
  try {
97
50
  const v = await client.version({});
98
51
  console.log(v.version);
@@ -248,6 +201,45 @@ The library version equals the agent-director release tag — released in lockst
248
201
  |---|---|
249
202
  | `agent-director@v0.5.0` | `agent-director CLI v0.5.0` |
250
203
 
204
+ ## Minimum required CLI binary version
205
+
206
+ The library declares the minimum CLI-binary version it requires on two
207
+ surfaces, both backed by the same single source of truth shipped in the
208
+ published npm package at `dist/version-floor.json`.
209
+
210
+ **TS export (preferred for JS/TS consumers):**
211
+
212
+ ```ts
213
+ import { MIN_BINARY_VERSION, DEV_SENTINEL_VERSION } from "agent-director";
214
+
215
+ console.log(`requires agent-director >= ${MIN_BINARY_VERSION}`);
216
+
217
+ if (binaryVersion === DEV_SENTINEL_VERSION) {
218
+ // dev-built binary stamps the sentinel; accept it as satisfying the floor.
219
+ }
220
+ ```
221
+
222
+ `MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
223
+ `0.7.0-rc1`). The value is inlined into the bundle at build time; no
224
+ runtime file read. `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
225
+ — a dev-built CLI binary stamps this value and satisfies any floor by
226
+ short-circuit. The library returns the binary's reported version
227
+ verbatim — no leading-`v` stripping, no normalization. Consumers
228
+ comparing two real versions should use a standard semver library;
229
+ agent-director does not export a comparator.
230
+
231
+ **Bash read pattern (for install scripts and non-JS consumers):**
232
+
233
+ ```sh
234
+ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
235
+ ```
236
+
237
+ This pattern is part of the public contract. It does not require the
238
+ agent-director CLI to be installed, does not spawn a JS runtime, and
239
+ does not require any agent-director-specific environment setup — read
240
+ the field from the file at the stable documented path. The `-r` flag
241
+ returns a bare string suitable for shell comparison.
242
+
251
243
  ## Supported Bun versions
252
244
 
253
245
  Minimum: `>=1.0.21` (set in `engines.bun`). Tested on Bun 1.3.x as of this release. The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
package/dist/client.d.ts CHANGED
@@ -1,10 +1,73 @@
1
1
  /**
2
- * client.ts — public Client export.
2
+ * client.ts — public Client class + standalone resolveSystemBinary().
3
3
  *
4
- * The subprocess implementation lives in internal/subprocessClient.ts; this
5
- * file aliases it as the public `Client` and re-exports the two error symbols
6
- * commonly imported alongside it so callers don't need separate imports.
4
+ * Construction (SR-4.1): `Client.create(opts)` is the only sanctioned entry
5
+ * point. The runtime constructor is private — `new Client(...)` is a
6
+ * compile-time TS error.
7
+ *
8
+ * The factory runs the SR-1 discovery pipeline (HOME/standard-install-path →
9
+ * PATH lookup), validates the candidate, probes its version, compares
10
+ * against MIN_BINARY_VERSION, and only then allocates the underlying
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)
16
+ *
17
+ * The DI hatch `_cliPath` (SR-4.1) skips discovery, canonicalizes the
18
+ * injected path, and runs the probe so that `binaryPath` and `binaryVersion`
19
+ * always carry production-shape values. `_cliPath` is not on the public
20
+ * `ClientOptions` interface — it lives on the runtime object only.
21
+ */
22
+ import { MIN_BUN_VERSION } from "./internal/platformResolve.js";
23
+ import { SubprocessClient } from "./internal/subprocessClient.js";
24
+ import { AgentDirectorError, ErrClientClosed } from "./errors.js";
25
+ import type { ClientOptions } from "./types.js";
26
+ export { AgentDirectorError, ErrClientClosed };
27
+ export type { ClientOptions };
28
+ /**
29
+ * Public Client surface — drives the agent-director CLI binary via one
30
+ * subprocess per verb call. Construct via `Client.create(opts)`; the
31
+ * runtime constructor is private (SR-4.1).
32
+ */
33
+ export declare class Client extends SubprocessClient {
34
+ /**
35
+ * Async factory — runs SR-1 discovery + SR-2.3 floor comparison, then
36
+ * allocates the underlying SubprocessClient.
37
+ *
38
+ * Rejects with:
39
+ * - ErrBunVersionTooOld
40
+ * - ErrSystemInstallNotFound
41
+ * - ErrSystemInstallTooOld
42
+ * - ErrSystemInstallUnreachable
43
+ */
44
+ static create(opts?: ClientOptions): Promise<Client>;
45
+ }
46
+ /**
47
+ * Result shape returned by resolveSystemBinary() (SR-4.3).
48
+ */
49
+ export interface ResolveSystemBinaryResult {
50
+ readonly path: string;
51
+ readonly version: string;
52
+ }
53
+ /**
54
+ * Options for resolveSystemBinary() (SR-4.3). Reserved for future expansion;
55
+ * deliberately exposes no `_cliPath` analogue (SR-4.3 intentional asymmetry
56
+ * with ClientOptions).
57
+ */
58
+ export interface ResolveSystemBinaryOptions {
59
+ }
60
+ /**
61
+ * resolveSystemBinary — standalone discovery + probe entry point.
62
+ *
63
+ * Runs the same SR-1.1 → SR-2.3 pipeline as Client.create() and resolves
64
+ * with `{ path, version }`. No Client is allocated, no cache is warmed.
65
+ *
66
+ * Rejects with the same four error classes as Client.create():
67
+ * - ErrBunVersionTooOld
68
+ * - ErrSystemInstallNotFound
69
+ * - ErrSystemInstallTooOld
70
+ * - ErrSystemInstallUnreachable
7
71
  */
8
- export { SubprocessClient as Client } from "./internal/subprocessClient.js";
9
- export { AgentDirectorError, ErrClientClosed } from "./errors.js";
10
- export type { ClientOptions } from "./types.js";
72
+ export declare function resolveSystemBinary(_opts?: ResolveSystemBinaryOptions): Promise<ResolveSystemBinaryResult>;
73
+ export { MIN_BUN_VERSION };
package/dist/errors.d.ts CHANGED
@@ -28,27 +28,6 @@ export declare class AgentDirectorError extends Error {
28
28
  export declare class ErrClientClosed extends AgentDirectorError {
29
29
  constructor();
30
30
  }
31
- /**
32
- * ErrUnsupportedPlatform — thrown when `process.platform` + `process.arch`
33
- * produce a tuple that has no corresponding native sub-package.
34
- *
35
- * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
36
- * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
37
- */
38
- export declare class ErrUnsupportedPlatform extends AgentDirectorError {
39
- constructor(tuple: string);
40
- }
41
- /**
42
- * ErrPlatformPackageMissing — thrown when the optional npm sub-package for
43
- * the current platform is not installed, or when its native binary file is
44
- * absent from the installed package directory.
45
- *
46
- * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
47
- * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
48
- */
49
- export declare class ErrPlatformPackageMissing extends AgentDirectorError {
50
- constructor(pkgName: string, detail?: string);
51
- }
52
31
  /**
53
32
  * ErrBunVersionTooOld — thrown when Bun.version is below the declared minimum.
54
33
  *
@@ -58,17 +37,6 @@ export declare class ErrPlatformPackageMissing extends AgentDirectorError {
58
37
  export declare class ErrBunVersionTooOld extends AgentDirectorError {
59
38
  constructor(actual: string, minimum: string);
60
39
  }
61
- /**
62
- * ErrCliNotExecutable — thrown when the resolved CLI binary exists on disk but
63
- * does not have execute permission for the current process's effective uid/gid.
64
- *
65
- * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
66
- * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
67
- * Implements SRD SR-2.3.
68
- */
69
- export declare class ErrCliNotExecutable extends AgentDirectorError {
70
- constructor(path: string);
71
- }
72
40
  /**
73
41
  * ErrConsumerSignal — thrown when an in-flight subprocess call is killed by an
74
42
  * OS signal (e.g. SIGTERM, SIGINT delivered to the consumer process group).
@@ -119,6 +87,71 @@ export declare class ErrUnknownErrorName extends AgentDirectorError {
119
87
  readonly envelope: unknown;
120
88
  constructor(unknownName: string, envelope: unknown);
121
89
  }
90
+ /**
91
+ * CheckedLocation — one entry in ErrSystemInstallNotFound.checkedLocations.
92
+ * Names a discovery step and what it consulted. Per SR-3.1.
93
+ */
94
+ export interface CheckedLocation {
95
+ /** Which discovery step consulted this location. */
96
+ kind: "standard-install-path" | "path-lookup";
97
+ /**
98
+ * For "standard-install-path": absolute resolved candidate path that was
99
+ * stat'd, or null when the path could not be computed (HOME unset/empty/
100
+ * non-absolute per SR-1.1).
101
+ * For "path-lookup": value of PATH at lookup time, or null when PATH was
102
+ * unset or empty.
103
+ */
104
+ detail: string | null;
105
+ }
106
+ /**
107
+ * UnreachableReason — closed-with-escape-hatch enum of failure modes that
108
+ * surface as ErrSystemInstallUnreachable. Per SR-3.3.
109
+ */
110
+ export type UnreachableReason = "not-executable" | "not-a-regular-file" | "probe-timeout" | "probe-nonzero-exit" | "probe-killed-by-signal" | "unparseable-version" | "spawn-failed" | "other";
111
+ /**
112
+ * ErrSystemInstallNotFound — thrown by Client.create() / resolveSystemBinary()
113
+ * when the discovery pipeline (SR-1.1) consults every documented location
114
+ * without finding a candidate file that exists on disk. Per SR-3.1.
115
+ *
116
+ * TS-ONLY ERROR. Listed in TS_ONLY_ERROR_NAMES.
117
+ */
118
+ export declare class ErrSystemInstallNotFound extends AgentDirectorError {
119
+ readonly checkedLocations: ReadonlyArray<CheckedLocation>;
120
+ constructor(checkedLocations: ReadonlyArray<CheckedLocation>);
121
+ }
122
+ /**
123
+ * ErrSystemInstallTooOld — thrown by Client.create() / resolveSystemBinary()
124
+ * when the probed binary's version is below MIN_BINARY_VERSION. Per SR-3.2.
125
+ * Data-only: no upgrade URL or command; presentation belongs to the consumer.
126
+ *
127
+ * TS-ONLY ERROR. Listed in TS_ONLY_ERROR_NAMES.
128
+ */
129
+ export declare class ErrSystemInstallTooOld extends AgentDirectorError {
130
+ readonly actualVersion: string;
131
+ readonly requiredVersion: string;
132
+ readonly binaryPath: string;
133
+ constructor(actualVersion: string, requiredVersion: string, binaryPath: string);
134
+ }
135
+ /**
136
+ * ErrSystemInstallUnreachable — thrown by Client.create() /
137
+ * resolveSystemBinary() when discovery produced a candidate but the binary
138
+ * failed validation or the version probe. Reason carries the specific
139
+ * failure mode. Per SR-3.3.
140
+ *
141
+ * TS-ONLY ERROR. Listed in TS_ONLY_ERROR_NAMES.
142
+ */
143
+ export declare class ErrSystemInstallUnreachable extends AgentDirectorError {
144
+ readonly binaryPath: string;
145
+ readonly reason: UnreachableReason;
146
+ readonly diagnostic: string | null;
147
+ readonly exitCode: number | null;
148
+ readonly signal: string | null;
149
+ constructor(binaryPath: string, reason: UnreachableReason, opts?: {
150
+ diagnostic?: string | null;
151
+ exitCode?: number | null;
152
+ signal?: string | null;
153
+ });
154
+ }
122
155
  /** Mirrors ErrCwdMissing (package: spawn) */
123
156
  export declare class ErrCwdMissing extends AgentDirectorError {
124
157
  }
package/dist/index.d.ts CHANGED
@@ -2,7 +2,11 @@
2
2
  * Public entry point for agent-director.
3
3
  */
4
4
  export { Client } from "./client.js";
5
- export { AgentDirectorError, ErrClientClosed, ErrUnsupportedPlatform, ErrPlatformPackageMissing, ErrBunVersionTooOld, ErrCliNotExecutable, 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";
5
+ export { resolveSystemBinary } from "./client.js";
6
+ export type { ResolveSystemBinaryResult, ResolveSystemBinaryOptions, } from "./client.js";
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";
9
+ export type { CheckedLocation, UnreachableReason } from "./errors.js";
6
10
  export type { ClientOptions, Logger } from "./types.js";
7
11
  export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
8
12
  export type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, GetPermissionParams, GetPermissionResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult, } from "./types.js";