agent-director 0.6.3 → 0.7.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.
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Build-time constants sourced from the version-floor.json single source of
3
+ * truth (SR-5.3). Bun inlines the JSON import as a string literal in
4
+ * dist/index.js; consumers never re-read the file at runtime (SR-5.0).
5
+ *
6
+ * The companion `dist/version-floor.json` (copied by build.ts) is the
7
+ * bash-readable surface (SR-5.5). Both sites trace to the same source
8
+ * byte sequence and are kept in lockstep by the version-coherence script
9
+ * (SR-5.4).
10
+ */
11
+ export declare const MIN_BINARY_VERSION: string;
12
+ export declare const DEV_SENTINEL_VERSION: "0.0.0-dev";
@@ -0,0 +1,50 @@
1
+ /**
2
+ * discovery.ts — system-install discovery pipeline (b.ue3 / SR-1).
3
+ *
4
+ * Implements the two-step lookup defined in SR-1.1:
5
+ * 1. Standard install path: $HOME/.agent-director/bin/agent-director.
6
+ * Skipped (no candidate manufactured) when HOME is unset/empty/non-absolute.
7
+ * 2. PATH lookup for "agent-director", first match.
8
+ *
9
+ * Each candidate is validated against SR-1.2 (regular-file + exec-bit) before
10
+ * being returned. Standard-install-path validation failures do NOT fall
11
+ * through to PATH (SR-1.2).
12
+ *
13
+ * Internal — not re-exported from src/index.ts.
14
+ */
15
+ import { dirname } from "node:path";
16
+ declare const STANDARD_INSTALL_PATH_RELATIVE = ".agent-director/bin/agent-director";
17
+ /** Result of a successful candidate validation. */
18
+ export interface DiscoveredCandidate {
19
+ /** Canonicalized absolute path to the binary (symlinks resolved). */
20
+ path: string;
21
+ /** Which step produced this candidate. */
22
+ kind: "standard-install-path" | "path-lookup";
23
+ }
24
+ /**
25
+ * canonicalizePath canonicalizes a candidate path the way SR-1.1 step 2
26
+ * canonicalizes PATH lookups. Used by the _cliPath DI hook (SR-4.1) so the
27
+ * "binaryPath is unconditionally absolute" invariant holds in tests too.
28
+ *
29
+ * Returns the canonicalized absolute path on success; throws
30
+ * ErrSystemInstallUnreachable on canonicalization failure.
31
+ */
32
+ export declare function canonicalizePath(candidatePath: string): string;
33
+ /**
34
+ * discoverSystemBinary runs SR-1.1 + SR-1.2 against the supplied env.
35
+ *
36
+ * Returns a validated candidate (canonicalized absolute path + which kind of
37
+ * lookup produced it) on success. Rejects with ErrSystemInstallNotFound when
38
+ * no candidate exists; rejects with ErrSystemInstallUnreachable when the
39
+ * standard-install-path candidate exists but fails validation (no fallthrough
40
+ * to PATH, per SR-1.2).
41
+ *
42
+ * The env arg is injectable so tests can drive HOME/PATH variants without
43
+ * mutating process.env.
44
+ */
45
+ export declare function discoverSystemBinary(env: {
46
+ HOME: string | undefined;
47
+ PATH: string | undefined;
48
+ }): DiscoveredCandidate;
49
+ export { STANDARD_INSTALL_PATH_RELATIVE };
50
+ export { dirname };
@@ -1,69 +1,20 @@
1
1
  /**
2
- * platformResolve.ts — CLI binary resolver for the subprocess Client.
2
+ * platformResolve.ts — Bun runtime-version guard.
3
3
  *
4
- * Resolves the path to the bundled agent-director CLI binary at Client
5
- * construction time (one-shot; not per-call). Resolution steps:
4
+ * The vendored-binary resolution logic that used to live here is gone as of
5
+ * b.ue3 (Stream A). Discovery is now run by src/internal/discovery.ts
6
+ * against the system install (HOME → PATH). The only piece this file still
7
+ * owns is the Bun-runtime-version check, fired at the top of every
8
+ * Client.create() and resolveSystemBinary() call before any filesystem stat
9
+ * (SR-7.7).
6
10
  *
7
- * 1. Check Bun.version against MIN_BUN_VERSION → ErrBunVersionTooOld
8
- * 2. Map process.platform + process.arch to an npm sub-package name →
9
- * ErrUnsupportedPlatform for unknown tuples
10
- * 3. Locate the CLI binary path:
11
- * - In production: resolve the sub-package via import.meta.resolve on
12
- * its package.json, then construct `<pkgDir>/bin/agent-director`.
13
- * - In tests: a `_requireResolve` DI hook can short-circuit step 3 and
14
- * return the binary path directly.
15
- * 4. Stat the resolved binary path → ErrPlatformPackageMissing when absent.
16
- * 5. Check execute bits against current process effective uid/gid →
17
- * ErrCliNotExecutable when not executable.
18
- *
19
- * Implements SRD SR-2.1 (resolution at construction), SR-2.2
20
- * (ErrPlatformPackageMissing), SR-2.3 (ErrCliNotExecutable), SR-2.4
21
- * (one-shot; no per-call re-check).
22
- *
23
- * Internal — NOT re-exported from src/index.ts.
11
+ * Internal — not re-exported from src/index.ts.
24
12
  */
25
- export { ErrPlatformPackageMissing, ErrCliNotExecutable } from "../errors.js";
26
13
  /** Minimum Bun runtime version required by this package. */
27
14
  export declare const MIN_BUN_VERSION = "1.0.21";
28
15
  /**
29
- * ResolveCliPathOpts provides dependency-injection hooks for testing without
30
- * requiring a real installed platform package.
31
- *
32
- * When `_requireResolve` is provided it is called with the full package
33
- * specifier and must return the absolute path to the CLI binary directly
34
- * (not a package.json path). Throwing from it simulates a missing package.
35
- */
36
- export interface ResolveCliPathOpts {
37
- /** Override process.platform (e.g. "linux"). Falls back to the real value. */
38
- platform?: string;
39
- /** Override process.arch (e.g. "x64"). Falls back to the real value. */
40
- arch?: string;
41
- /**
42
- * Override the module-resolution step (step 3).
43
- *
44
- * When supplied, this function is called with the platform sub-package name
45
- * and must return the **absolute path to the CLI binary** directly.
46
- * Throwing from it signals that the package is not installed and will cause
47
- * resolveCliPath to throw ErrPlatformPackageMissing.
48
- *
49
- * In production, `import.meta.resolve` is used instead; the package.json is
50
- * resolved and then `<pkgDir>/bin/agent-director` is constructed from it.
51
- */
52
- _requireResolve?: (pkg: string) => string;
53
- }
54
- /**
55
- * resolveCliPath resolves the absolute path to the bundled CLI binary for the
56
- * current platform. Throws typed errors on every failure path; never returns
57
- * a path that does not point at an executable file.
58
- *
59
- * The returned path is intended to be cached on the Client instance.
60
- *
61
- * @param opts Optional DI overrides for testing.
62
- *
63
- * Throws one of:
64
- * ErrBunVersionTooOld — Bun version < MIN_BUN_VERSION
65
- * ErrUnsupportedPlatform — platform/arch tuple not in SUPPORTED_TUPLES
66
- * ErrPlatformPackageMissing — sub-package not installed or binary absent
67
- * ErrCliNotExecutable — binary exists but lacks execute permission
16
+ * checkBunVersion throws ErrBunVersionTooOld when the running Bun runtime is
17
+ * below MIN_BUN_VERSION. Called once per Client.create() / resolveSystemBinary()
18
+ * at the top of the pipeline (SR-7.7).
68
19
  */
69
- export declare function resolveCliPath(opts?: ResolveCliPathOpts): string;
20
+ export declare function checkBunVersion(): void;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * probe.ts — bounded version-probe subprocess invocation (SR-1.3).
3
+ *
4
+ * Spawns `<candidate> version --json` with the SR-1.3 invocation policy:
5
+ * - 5000 ms timeout (SR-1.3.1), then SIGTERM → 2000 ms grace → SIGKILL (SR-1.3.2)
6
+ * - allowlist-only env scrub (SR-1.3.3)
7
+ * - stdin piped + closed before any byte is written (SR-1.3.4)
8
+ * - cwd = "/" (SR-1.3.5)
9
+ * - stdout/stderr piped, each capped at 64 KiB (SR-1.3.6 / .7 / .8)
10
+ *
11
+ * Returns the parsed-and-classified probe result. Every probe failure is
12
+ * surfaced via ProbeOutcome; the caller maps to ErrSystemInstall* in the
13
+ * discovery pipeline.
14
+ *
15
+ * Internal — not re-exported from src/index.ts.
16
+ */
17
+ import type { UnreachableReason } from "../errors.js";
18
+ export declare const PROBE_TIMEOUT_MS = 5000;
19
+ export declare const SIGKILL_GRACE_MS = 2000;
20
+ export declare const STDOUT_CAP_BYTES: number;
21
+ export declare const STDERR_CAP_BYTES: number;
22
+ /** Result of a probe that classified successfully into a version string. */
23
+ export interface ProbeSuccess {
24
+ ok: true;
25
+ /** Byte-exact `version` field from the binary's `version --json` envelope. */
26
+ version: string;
27
+ }
28
+ /** Result of a probe that failed; reason is the SR-3.3 enum value. */
29
+ export interface ProbeFailure {
30
+ ok: false;
31
+ reason: UnreachableReason;
32
+ diagnostic: string | null;
33
+ exitCode: number | null;
34
+ signal: string | null;
35
+ }
36
+ export type ProbeOutcome = ProbeSuccess | ProbeFailure;
37
+ /**
38
+ * runProbe spawns the candidate with SR-1.3 invocation hygiene and classifies
39
+ * the outcome. Never throws — always returns a ProbeOutcome.
40
+ *
41
+ * Caller is expected to have already validated the candidate per SR-1.2.
42
+ */
43
+ export declare function runProbe(candidatePath: string): Promise<ProbeOutcome>;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Internal strict-SemVer-2.0 parser + 3-way comparator with dev-sentinel
3
+ * short-circuit. Internal-only per SR-2.4 — not re-exported from src/index.ts.
4
+ *
5
+ * Parse rules (SR-2.2):
6
+ * 1. Sentinel short-circuit: byte-exact "0.0.0-dev" returns a tagged
7
+ * sentinel result that satisfies any minimum.
8
+ * 2. Strict regex /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/. No
9
+ * canonicalization, no leading-v stripping, no build-metadata stripping,
10
+ * no whitespace trimming. The build pipeline (SR-2.6) owns "clean string
11
+ * at the source".
12
+ *
13
+ * Compare rules (SR-2.3):
14
+ * - Sentinel side always satisfies (`compare(sentinel, anything)` >= 0).
15
+ * - Otherwise compare core (major, minor, patch) numerically.
16
+ * - Equal cores: no-prerelease > has-prerelease (SemVer 2.0 §11.4).
17
+ * - Both have prerelease: lexicographic ASCII byte compare (simplified
18
+ * rule per SRD cross-piece commitment).
19
+ */
20
+ export declare const DEV_SENTINEL = "0.0.0-dev";
21
+ export interface ParsedVersion {
22
+ readonly kind: "real";
23
+ readonly major: number;
24
+ readonly minor: number;
25
+ readonly patch: number;
26
+ readonly prerelease: string | null;
27
+ }
28
+ export interface SentinelVersion {
29
+ readonly kind: "sentinel";
30
+ }
31
+ export type ParseResult = {
32
+ ok: true;
33
+ value: ParsedVersion | SentinelVersion;
34
+ } | {
35
+ ok: false;
36
+ };
37
+ export declare function parseVersion(input: string): ParseResult;
38
+ export declare function compareParsed(a: ParsedVersion | SentinelVersion, b: ParsedVersion | SentinelVersion): -1 | 0 | 1;
39
+ /**
40
+ * Three-way compare two version strings. Returns -1, 0, +1; throws if either
41
+ * input fails SR-2.2 parsing. Callers that need to classify unparseable
42
+ * inputs as ErrSystemInstallUnreachable(reason="unparseable-version") must
43
+ * pre-parse with `parseVersion` instead of catching this throw.
44
+ */
45
+ export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
@@ -1,71 +1,90 @@
1
1
  /**
2
2
  * subprocessClient.ts — subprocess-based Client implementation.
3
3
  *
4
- * Wires the platform resolver (A2), argv builder (A3), spawner (A4), and
5
- * typed-error map (A5) into a full Client class that drives the bundled CLI
6
- * binary one subprocess per verb call.
4
+ * Construction is async (see Client.create() in client.ts). The runtime
5
+ * constructor is private — production code instantiates via the factory,
6
+ * which runs the SR-1 discovery + SR-1.3 probe pipeline first and passes
7
+ * the resolved binaryPath + binaryVersion in via an internal-only options
8
+ * object (private symbol).
7
9
  *
8
- * Per-Client serialization: each `SubprocessClient` instance owns a private
9
- * `#tail: Promise<unknown>` queue. Every call chains its spawn body onto the
10
- * tail so that at most one subprocess per Client is running at any time (SRD
11
- * SR-3.1/SR-3.2/SR-3.4). Rejection does not wedge the queue (SR-3.3).
10
+ * Per-Client serialization: each instance owns a private `#tail: Promise<unknown>`
11
+ * queue. Every call chains its spawn body onto the tail so that at most one
12
+ * subprocess per Client is running at any time (SR-3.1/3.2/3.4). Rejection
13
+ * does not wedge the queue (SR-3.3).
12
14
  *
13
- * Timeout handling (SRD SR-6.2):
15
+ * Timeout handling (SR-6.2):
14
16
  * 1. setTimeout fires after callTimeoutMs.
15
17
  * 2. SIGTERM is sent to the subprocess.
16
18
  * 3. A 2-second graceful window waits for the subprocess to exit.
17
19
  * 4. SIGKILL is sent if still running after the window.
18
20
  * 5. After subprocess.exited resolves, ErrCallTimeout is thrown.
19
21
  *
20
- * Signal handling (SRD SR-5.2):
22
+ * Signal handling (SR-5.2):
21
23
  * After subprocess.exited resolves, signalCode is inspected. If non-null
22
24
  * and the timeout was not the cause, ErrConsumerSignal is thrown.
23
- *
24
- * IMPORTANT: This class does NOT modify src/index.ts's `Client` export.
25
- * The public surface continues to point at the existing FFI Client until
26
- * Epic B's cutover. Only the four new typed-error classes are added to
27
- * index.ts (done in Task A1).
28
- *
29
- * Internal — NOT re-exported from src/index.ts until Epic B.
30
25
  */
31
26
  import type { ClientOptions } from "../types.js";
32
27
  import 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";
33
28
  /**
34
- * SubprocessClient drives the bundled agent-director CLI binary as one
35
- * subprocess per verb call. Intended as the replacement for the FFI Client
36
- * but NOT yet wired to the public `Client` export (that is Epic B).
29
+ * Internal construction parameters. Carries pre-resolved binaryPath +
30
+ * binaryVersion so the runtime constructor doesn't run discovery itself.
31
+ * The factory (Client.create) supplies these by running discoverSystemBinary
32
+ * and runProbe upstream.
33
+ *
34
+ * @internal
35
+ */
36
+ export interface InternalClientInit {
37
+ /** Canonicalized absolute path produced by SR-1.1 discovery or SR-4.1 _cliPath canonicalization. */
38
+ binaryPath: string;
39
+ /** Byte-exact version string captured from the probe envelope (SR-2.5). */
40
+ binaryVersion: string;
41
+ }
42
+ /**
43
+ * SubprocessClient drives the agent-director CLI binary as one subprocess
44
+ * per verb call against a binary located by the SR-1 discovery pipeline.
37
45
  *
38
- * Construction resolves the CLI binary path (throws on any resolution error)
39
- * and validates callTimeoutMs.
46
+ * Constructed via Client.create() — the public surface. The runtime
47
+ * constructor is private; tests reach instances only through the factory.
40
48
  */
41
49
  export declare class SubprocessClient {
42
50
  #private;
43
51
  /**
44
- * FFI-shape parity stub. The FFI Client stores a handle string here; the
45
- * subprocess model has no handle concept (each call opens and closes the
46
- * store independently), so this is always null. Exposed for tests that
47
- * cast to the FFI Client shape to inspect lifecycle state.
48
- *
49
- * @internal Tests only.
52
+ * FFI-shape parity stub. Always null in the subprocess model.
53
+ * @internal
50
54
  */
51
55
  readonly _handle: null;
52
- constructor(opts: ClientOptions);
53
56
  /**
54
- * close marks this client as closed. Subsequent verb calls throw
55
- * ErrClientClosed. Idempotent.
57
+ * Protected constructor — production code uses Client.create() instead.
58
+ * Protected so that the public Client class (which extends this) can call
59
+ * super() via SubprocessClient._construct(). External code cannot reach
60
+ * the constructor: `new SubprocessClient(...)` and `new Client(...)` are
61
+ * both compile-time TS errors.
56
62
  *
57
- * Unlike the FFI Client there is no handle to release: the subprocess
58
- * model requires no teardown — each call's subprocess is already reaped.
63
+ * @internal
64
+ */
65
+ protected constructor(opts: ClientOptions, init: InternalClientInit);
66
+ /**
67
+ * Internal-only factory entry point. Callers in the same module use
68
+ * `(SubprocessClient as any)._construct(...)`; we publish this as a
69
+ * non-typed method so the TS `private constructor` fence holds for
70
+ * external consumers while client.ts can still build an instance.
71
+ *
72
+ * @internal
73
+ */
74
+ static _construct(opts: ClientOptions, init: InternalClientInit): SubprocessClient;
75
+ /** Canonicalized absolute path to the CLI binary (SR-1.5 / SR-4.1). */
76
+ get binaryPath(): string;
77
+ /** Byte-exact version string the CLI binary reported (SR-2.5 / SR-4.1). */
78
+ get binaryVersion(): string;
79
+ /**
80
+ * close marks this client as closed. Idempotent. Subsequent verb calls
81
+ * throw ErrClientClosed.
59
82
  */
60
83
  close(): void;
61
84
  /** [Symbol.dispose] delegates to close() for `using` blocks. */
62
85
  [Symbol.dispose](): void;
63
86
  /**
64
- * _assertOpenForTests exposes #assertOpen to test code without forcing
65
- * public visibility. Mirrors the same helper on the FFI Client so that
66
- * client-lifecycle tests compile against either implementation.
67
- *
68
- * @internal Tests only — do not call from application code.
87
+ * @internal Tests only.
69
88
  */
70
89
  _assertOpenForTests(): void;
71
90
  /** spawn — launch a tracked Claude Code instance in a new tmux session. */
@@ -12,18 +12,23 @@
12
12
  * at pkg/api/errnames/catalog.json.
13
13
  *
14
14
  * Membership criteria:
15
- * - ErrClientClosed — client lifecycle error, no Go equivalent.
16
- * - ErrUnsupportedPlatform — platform detection error, raised before any IPC.
17
- * - ErrPlatformPackageMissing — optional sub-package absent; no Go equivalent.
18
- * - ErrBunVersionTooOld — runtime version guard; no Go equivalent.
19
- * - ErrCliNotExecutable — binary lacks execute permission; no Go equivalent (SRD SR-2.3).
20
- * - ErrConsumerSignal — subprocess killed by OS signal; no Go equivalent (SRD SR-5.4).
21
- * - ErrCallTimeout — per-call timeout elapsed; no Go equivalent (SRD SR-6.5).
22
- * - ErrUnknownErrorName — unrecognised err_name in envelope; no Go equivalent (SRD SR-4.3).
15
+ * - ErrClientClosed — client lifecycle error, no Go equivalent.
16
+ * - ErrBunVersionTooOld — runtime version guard; no Go equivalent.
17
+ * - ErrConsumerSignal — subprocess killed by OS signal (SR-5.4).
18
+ * - ErrCallTimeout — per-call timeout elapsed (SR-6.5).
19
+ * - ErrUnknownErrorName — unrecognised err_name in envelope (SR-4.3).
20
+ * - ErrSystemInstallNotFound — discovery found no AD binary (b.ue3 / SR-3.1).
21
+ * - ErrSystemInstallTooOld — discovered binary is below floor (b.ue3 / SR-3.2).
22
+ * - ErrSystemInstallUnreachable — discovered binary failed probe (b.ue3 / SR-3.3).
23
+ *
24
+ * Removed in b.ue3 (vendored-binary surface dropped):
25
+ * - ErrUnsupportedPlatform
26
+ * - ErrPlatformPackageMissing
27
+ * - ErrCliNotExecutable
23
28
  *
24
29
  * When adding a new TS-only subclass: add its name here AND add a comment in
25
30
  * src/errors.ts near the subclass cross-referencing this allow-list.
26
31
  */
27
- export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrUnsupportedPlatform", "ErrPlatformPackageMissing", "ErrBunVersionTooOld", "ErrCliNotExecutable", "ErrConsumerSignal", "ErrCallTimeout", "ErrUnknownErrorName"];
32
+ export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrBunVersionTooOld", "ErrConsumerSignal", "ErrCallTimeout", "ErrUnknownErrorName", "ErrSystemInstallNotFound", "ErrSystemInstallTooOld", "ErrSystemInstallUnreachable"];
28
33
  /** Type alias for the individual allow-listed names. */
29
34
  export type TsOnlyErrorName = (typeof TS_ONLY_ERROR_NAMES)[number];
@@ -0,0 +1,3 @@
1
+ {
2
+ "min_binary_version": "0.7.0"
3
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-director",
3
- "version": "0.6.3",
3
+ "version": "0.7.0",
4
4
  "type": "module",
5
5
  "os": [
6
6
  "linux",
@@ -16,16 +16,16 @@
16
16
  "files": [
17
17
  "dist/**/*.js",
18
18
  "dist/**/*.d.ts",
19
+ "dist/version-floor.json",
19
20
  "!dist/**/*.test.*",
20
- "README.md",
21
- "scripts/postinstall.ts",
22
- "skills/install-agent-director/**"
21
+ "README.md"
23
22
  ],
24
23
  "exports": {
25
24
  ".": {
26
25
  "import": "./dist/index.js",
27
26
  "types": "./dist/index.d.ts"
28
- }
27
+ },
28
+ "./dist/version-floor.json": "./dist/version-floor.json"
29
29
  },
30
30
  "scripts": {
31
31
  "build": "bun run build.ts",
@@ -34,18 +34,9 @@
34
34
  "test": "bun test",
35
35
  "smoke": "bun test test/smoke/ test/smoke-invariants.test.ts",
36
36
  "envelope-diff": "bun test test/envelope-diff.test.ts test/envelope-diff-invariants.test.ts",
37
- "prepare-platforms": "bun run scripts/prepare-platforms.ts",
38
- "stage-skill": "bun run scripts/stage-skill.ts",
39
- "prepack": "bun run build && bun run scripts/stage-skill.ts",
40
- "postinstall": "bun run scripts/postinstall.ts",
41
37
  "version-bump-publish": "bun run scripts/version-bump.ts",
42
- "prepublishOnly": "bun run scripts/prepublish-guards.ts",
43
38
  "verify-installed-pkg": "bun run scripts/verify-installed-pkg.ts"
44
39
  },
45
- "optionalDependencies": {
46
- "@agent-director/linux-x64": "^0.6.3",
47
- "@agent-director/darwin-arm64": "^0.6.3"
48
- },
49
40
  "devDependencies": {
50
41
  "typescript": ">=5.2.0",
51
42
  "bun-types": "latest",