agent-director 0.4.5 → 0.5.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.
@@ -0,0 +1,61 @@
1
+ /**
2
+ * argv.ts — verb-driven argv builder for the subprocess Client.
3
+ *
4
+ * Exports a single pure function `buildArgv(cliPath, verb, params, globalOpts?)`
5
+ * that converts typed verb parameters into a complete CLI argv array:
6
+ *
7
+ * [cliPath, ...globalFlags, verbName, ...verbFlags]
8
+ *
9
+ * Rules:
10
+ * - Long-flag form only (e.g. --cwd, --claude-instance-id).
11
+ * - No shell interpolation, no sh -c.
12
+ * - Mapping between camelCase method name and kebab CLI verb follows the
13
+ * same mapping in src/internal/verbs.ts.
14
+ * - Optional fields are omitted when undefined / falsy.
15
+ * - Boolean flags (--no-pre-trust, --ansi, --overwrite) are only appended
16
+ * when the field is explicitly true.
17
+ * - Global flags (b.32k: --store-path, --home, --tmux-command) appear
18
+ * BEFORE the verb token so the CLI's global-flag parser in
19
+ * cmd/agent-director/global_flags.go strips them prior to verb dispatch.
20
+ *
21
+ * Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
22
+ *
23
+ * Internal — NOT re-exported from src/index.ts.
24
+ */
25
+ import type { VerbName } from "./verbs.js";
26
+ /**
27
+ * GlobalArgvOptions — values for the three global CLI flags introduced by
28
+ * bug b.32k. Each field is optional; when undefined the corresponding flag
29
+ * is omitted from argv and the CLI's own default-resolution kicks in.
30
+ *
31
+ * Tilde-expansion is the caller's responsibility (typically done at Client
32
+ * construction time via src/internal/tilde.ts).
33
+ */
34
+ export interface GlobalArgvOptions {
35
+ /** Tilde-expanded path forwarded to the CLI as `--store-path`. */
36
+ storePath?: string;
37
+ /** Tilde-expanded path forwarded to the CLI as `--home`. */
38
+ home?: string;
39
+ /** Tilde-expanded path forwarded to the CLI as `--tmux-command`. */
40
+ tmuxCommand?: string;
41
+ }
42
+ /**
43
+ * buildArgv converts a CLI binary path, verb name, and typed parameters into
44
+ * a complete CLI argv array:
45
+ *
46
+ * [cliPath, ...globalFlags, verbName, ...verbFlags]
47
+ *
48
+ * Global flags are inserted BEFORE the verb token because the CLI's
49
+ * `parseGlobalFlags` pre-scan operates on os.Args[1:] before verb dispatch
50
+ * (see cmd/agent-director/global_flags.go). b.32k.
51
+ *
52
+ * @param cliPath The absolute path to the CLI binary (argv[0]).
53
+ * @param verb The kebab-case verb name (must be a VerbName).
54
+ * @param params The typed params object for the verb.
55
+ * @param globalOpts Optional global-flag values (--store-path / --home /
56
+ * --tmux-command). When undefined or all-fields-omitted,
57
+ * no global flags appear in argv and the CLI applies its
58
+ * own default-resolution.
59
+ * @returns The full argv array starting with cliPath.
60
+ */
61
+ export declare function buildArgv(cliPath: string, verb: VerbName, params: unknown, globalOpts?: GlobalArgvOptions): string[];
@@ -0,0 +1,55 @@
1
+ /**
2
+ * errorMap.ts — catalog-driven static error map for the subprocess Client.
3
+ *
4
+ * Builds a `Map<string, ErrConstructor>` at module load time by iterating
5
+ * `pkg/api/errnames/catalog.json` (33 entries as of 2026-05-25). The map
6
+ * keys are the canonical `err_name` strings (e.g. "ErrSpawnNotFound");
7
+ * values are the typed constructors already exported from `src/errors.ts`.
8
+ *
9
+ * Exports `throwFromEnvelope(verb, envelope)` which:
10
+ * - Looks up `envelope.err_name` in the static map.
11
+ * - Throws the typed subclass when found (carrying verb + envelope fields).
12
+ * - Throws `ErrUnknownErrorName` when the err_name is not in the map
13
+ * (SRD SR-4.3 — defensive against Go-side catalog additions that race
14
+ * the TS-side regen).
15
+ *
16
+ * Implements SRD SR-4.1 (static module-load-time map), SR-4.2 (throw by
17
+ * constructor with envelope fields), SR-4.3 (ErrUnknownErrorName for
18
+ * unknown names), SR-4.4 (envelope key name is err_name).
19
+ *
20
+ * Internal — NOT re-exported from src/index.ts.
21
+ */
22
+ import * as errors from "../errors.js";
23
+ type ErrConstructor = new (verb: string, err_name: string, err_description: string) => errors.AgentDirectorError;
24
+ /**
25
+ * errorMap maps every err_name string from catalog.json to its typed
26
+ * AgentDirectorError constructor. Built once at module load.
27
+ *
28
+ * Entries not present in errors.ts (e.g. a future catalog addition that
29
+ * hasn't been regenerated on the TS side yet) are silently omitted; the
30
+ * throwFromEnvelope helper handles the miss via ErrUnknownErrorName.
31
+ */
32
+ export declare const errorMap: ReadonlyMap<string, ErrConstructor>;
33
+ /** Shape of a JSON envelope that carries a typed error. */
34
+ interface ErrorEnvelope {
35
+ err_name: string;
36
+ err_description: string;
37
+ }
38
+ /**
39
+ * isErrorEnvelope returns true when the parsed envelope contains an err_name
40
+ * field (indicating a typed error, not a success result).
41
+ */
42
+ export declare function isErrorEnvelope(envelope: unknown): envelope is ErrorEnvelope;
43
+ /**
44
+ * throwFromEnvelope inspects an envelope for `err_name` and throws the
45
+ * corresponding typed AgentDirectorError subclass.
46
+ *
47
+ * Call this only when `isErrorEnvelope(envelope)` is true.
48
+ *
49
+ * @param verb The verb name that produced the envelope (for error context).
50
+ * @param envelope The parsed JSON envelope object.
51
+ * @throws The typed subclass from SUBPROCESS_ERROR_MAP, or
52
+ * ErrUnknownErrorName when the name is not in the map.
53
+ */
54
+ export declare function throwFromEnvelope(verb: string, envelope: unknown): never;
55
+ export {};
@@ -0,0 +1,69 @@
1
+ /**
2
+ * platformResolve.ts — CLI binary resolver for the subprocess Client.
3
+ *
4
+ * Resolves the path to the bundled agent-director CLI binary at Client
5
+ * construction time (one-shot; not per-call). Resolution steps:
6
+ *
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.
24
+ */
25
+ export { ErrPlatformPackageMissing, ErrCliNotExecutable } from "../errors.js";
26
+ /** Minimum Bun runtime version required by this package. */
27
+ export declare const MIN_BUN_VERSION = "1.0.21";
28
+ /**
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
68
+ */
69
+ export declare function resolveCliPath(opts?: ResolveCliPathOpts): string;
@@ -0,0 +1,75 @@
1
+ /**
2
+ * spawner.ts — Bun.spawn wrapper for the subprocess Client.
3
+ *
4
+ * Provides `runSubprocess(argv)` which:
5
+ * 1. Spawns argv[0] with argv[1..] using Bun.spawn (stdin/stdout/stderr
6
+ * piped, detached: false).
7
+ * 2. Closes stdin immediately after spawn (no verb requires stdin input).
8
+ * 3. Drains stdout and stderr concurrently with the subprocess running via
9
+ * `new Response(stream).text()` + `Promise.all` alongside
10
+ * `subprocess.exited` (SR-7.1 — prevents pipe-buffer deadlock on large
11
+ * payloads).
12
+ * 4. Returns a `SpawnOutcome` with the raw text and exit metadata.
13
+ * 5. Throws `ErrSubprocessCrash` when the subprocess exits non-zero
14
+ * without a signal (normal crash path).
15
+ *
16
+ * Signal-killed subprocesses (signalCode != null) are returned, not thrown;
17
+ * the SubprocessClient (A6) inspects signalCode and throws ErrConsumerSignal.
18
+ *
19
+ * Implements SRD SR-1.1 (Bun.spawn, detached:false), SR-1.3
20
+ * (stdin/stdout/stderr), SR-1.4 (cwd/env inheritance), SR-1.5 (exit
21
+ * semantics), SR-7.1 (concurrent drain), SR-7.2 (no size cap), SR-7.3
22
+ * (stderr preserved for diagnostics).
23
+ *
24
+ * Internal — NOT re-exported from src/index.ts.
25
+ */
26
+ /**
27
+ * ErrSubprocessCrash is thrown by runSubprocess when the CLI subprocess exits
28
+ * with a non-zero exit code (not caused by a signal). It carries the exit code,
29
+ * the captured signal (null for normal crashes), and the first ~1 KB of stderr.
30
+ *
31
+ * This is an implementation-level error distinct from the catalog-derived
32
+ * AgentDirectorError subclasses; it signals a crash in the CLI binary itself
33
+ * (e.g. config-load failure, store-open failure), not a domain error.
34
+ */
35
+ export declare class ErrSubprocessCrash extends Error {
36
+ /** Exit code from the subprocess (null when killed by signal). */
37
+ readonly exitCode: number | null;
38
+ /** Signal name if killed by signal, null otherwise. */
39
+ readonly signalCode: string | null;
40
+ /** Full stderr output from the subprocess (not truncated; caller truncates). */
41
+ readonly stderrFull: string;
42
+ constructor(exitCode: number | null, signalCode: string | null, stderrFull: string);
43
+ }
44
+ /**
45
+ * SpawnOutcome is the raw result of a successful (exit-code-0, valid-JSON-stdout)
46
+ * subprocess run or a signal-killed run.
47
+ *
48
+ * Invariants:
49
+ * - When signalCode is non-null, exitCode is null (killed by signal).
50
+ * - When signalCode is null, exitCode is 0 (success path; crashes throw).
51
+ * - stdout is always a valid-JSON string on the success path (signalCode null,
52
+ * exitCode 0). On the signal path, stdout may be partial/empty.
53
+ */
54
+ export interface SpawnOutcome {
55
+ /** Raw stdout text drained from the subprocess. */
56
+ readonly stdout: string;
57
+ /** Raw stderr text drained from the subprocess. */
58
+ readonly stderr: string;
59
+ /** Exit code: 0 on success, null when killed by signal. */
60
+ readonly exitCode: number | null;
61
+ /** Signal name if the process was killed by a signal, null otherwise. */
62
+ readonly signalCode: string | null;
63
+ }
64
+ /**
65
+ * runSubprocess spawns `argv[0]` with arguments `argv[1..]` and returns a
66
+ * `SpawnOutcome` describing the completed run.
67
+ *
68
+ * Stdin is closed immediately after spawn.
69
+ * Stdout and stderr are drained concurrently with the subprocess running
70
+ * so that large outputs do not fill the kernel pipe buffer and deadlock.
71
+ *
72
+ * @param argv Full argv: [cliPath, verbName, ...flags]
73
+ * @throws ErrSubprocessCrash when exitCode is non-zero and signalCode is null.
74
+ */
75
+ export declare function runSubprocess(argv: string[]): Promise<SpawnOutcome>;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * subprocessClient.ts — subprocess-based Client implementation.
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.
7
+ *
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).
12
+ *
13
+ * Timeout handling (SRD SR-6.2):
14
+ * 1. setTimeout fires after callTimeoutMs.
15
+ * 2. SIGTERM is sent to the subprocess.
16
+ * 3. A 2-second graceful window waits for the subprocess to exit.
17
+ * 4. SIGKILL is sent if still running after the window.
18
+ * 5. After subprocess.exited resolves, ErrCallTimeout is thrown.
19
+ *
20
+ * Signal handling (SRD SR-5.2):
21
+ * After subprocess.exited resolves, signalCode is inspected. If non-null
22
+ * 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
+ */
31
+ import type { ClientOptions } from "../types.js";
32
+ import type { SpawnParams, SpawnResult, StatusParams, StatusResult, GetParams, GetResult, SendKeysParams, SendKeysResult, ReadPaneParams, ReadPaneResult, KillParams, KillResult, DecideParams, DecideResult, ResumeParams, ResumeResult, FindMissingParams, FindMissingResult, ExpireParams, ExpireResult, DeleteParams, DeleteResult, MakeTemplateParams, MakeTemplateResult, ListParams, ListResult, PauseParams, PauseResult, VersionParams, VersionResult } from "../types.js";
33
+ /**
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).
37
+ *
38
+ * Construction resolves the CLI binary path (throws on any resolution error)
39
+ * and validates callTimeoutMs.
40
+ */
41
+ export declare class SubprocessClient {
42
+ #private;
43
+ /**
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.
50
+ */
51
+ readonly _handle: null;
52
+ constructor(opts: ClientOptions);
53
+ /**
54
+ * close marks this client as closed. Subsequent verb calls throw
55
+ * ErrClientClosed. Idempotent.
56
+ *
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.
59
+ */
60
+ close(): void;
61
+ /** [Symbol.dispose] delegates to close() for `using` blocks. */
62
+ [Symbol.dispose](): void;
63
+ /**
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.
69
+ */
70
+ _assertOpenForTests(): void;
71
+ /** spawn — launch a tracked Claude Code instance in a new tmux session. */
72
+ spawn(params: SpawnParams): Promise<SpawnResult>;
73
+ /** status — get the current state of a Spawn. */
74
+ status(params: StatusParams): Promise<StatusResult>;
75
+ /** get — fetch the full Spawn record. */
76
+ get(params: GetParams): Promise<GetResult>;
77
+ /** sendKeys — send keystrokes to a Spawn's tmux pane. */
78
+ sendKeys(params: SendKeysParams): Promise<SendKeysResult>;
79
+ /** readPane — read the current contents of a Spawn's tmux pane. */
80
+ readPane(params: ReadPaneParams): Promise<ReadPaneResult>;
81
+ /** kill — terminate a Spawn's tmux session. */
82
+ kill(params: KillParams): Promise<KillResult>;
83
+ /** decide — resolve a pending permission request. */
84
+ decide(params: DecideParams): Promise<DecideResult>;
85
+ /** resume — restart a terminated Spawn. */
86
+ resume(params: ResumeParams): Promise<ResumeResult>;
87
+ /** findMissing — reconcile Spawns whose tmux sessions have disappeared. */
88
+ findMissing(params: FindMissingParams): Promise<FindMissingResult>;
89
+ /** expire — remove terminal-state rows older than the retention window. */
90
+ expire(params: ExpireParams): Promise<ExpireResult>;
91
+ /** delete — hard-delete Spawn rows by id. */
92
+ delete(params: DeleteParams): Promise<DeleteResult>;
93
+ /** makeTemplate — save a reusable spawn preset. */
94
+ makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
95
+ /** list — query Spawns with optional filter params. */
96
+ list(params: ListParams): Promise<ListResult>;
97
+ /** pause — politely shut down a waiting Spawn. */
98
+ pause(params: PauseParams): Promise<PauseResult>;
99
+ /** version — return the npm package version (b.6o1) plus the CLI's commit SHA. */
100
+ version(params: VersionParams): Promise<VersionResult>;
101
+ }
@@ -12,14 +12,18 @@
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.
15
+ * - ErrClientClosed — client lifecycle error, no Go equivalent.
16
+ * - ErrUnsupportedPlatform — platform detection error, raised before any IPC.
17
17
  * - ErrPlatformPackageMissing — optional sub-package absent; no Go equivalent.
18
- * - ErrBunVersionTooOld — runtime version guard; 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).
19
23
  *
20
24
  * When adding a new TS-only subclass: add its name here AND add a comment in
21
25
  * src/errors.ts near the subclass cross-referencing this allow-list.
22
26
  */
23
- export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrUnsupportedPlatform", "ErrPlatformPackageMissing", "ErrBunVersionTooOld"];
27
+ export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrUnsupportedPlatform", "ErrPlatformPackageMissing", "ErrBunVersionTooOld", "ErrCliNotExecutable", "ErrConsumerSignal", "ErrCallTimeout", "ErrUnknownErrorName"];
24
28
  /** Type alias for the individual allow-listed names. */
25
29
  export type TsOnlyErrorName = (typeof TS_ONLY_ERROR_NAMES)[number];
@@ -11,47 +11,9 @@
11
11
  * pause, version.
12
12
  *
13
13
  * NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
14
- * intentionally excluded here even though earlier epic-spec drafts assumed
15
- * otherwise. The .go source wins.
14
+ * intentionally excluded here. The .go source wins.
16
15
  */
17
16
  /** All callable verbs in their canonical kebab form (matches manifest). */
18
17
  export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "resume", "find-missing", "expire", "delete", "make-template", "list", "pause", "version"];
19
18
  /** Union type of every callable verb name. */
20
19
  export type VerbName = (typeof VERBS)[number];
21
- /**
22
- * kebabToUnderscore converts a kebab-case verb name to the underscore form
23
- * used in the C-ABI symbol name.
24
- *
25
- * Examples:
26
- * "send-keys" → "send_keys"
27
- * "find-missing" → "find_missing"
28
- * "make-template" → "make_template"
29
- * "read-pane" → "read_pane"
30
- * "version" → "version"
31
- */
32
- export declare function kebabToUnderscore(v: string): string;
33
- /**
34
- * kebabToCamel converts a kebab-case verb name to the camelCase form used
35
- * as a method name on the Client class.
36
- *
37
- * Examples:
38
- * "send-keys" → "sendKeys"
39
- * "find-missing" → "findMissing"
40
- * "make-template" → "makeTemplate"
41
- * "read-pane" → "readPane"
42
- * "version" → "version"
43
- */
44
- export declare function kebabToCamel(v: string): string;
45
- /**
46
- * KEBAB_TO_CAMEL is a static map from every VerbName to its camelCase form.
47
- * Prefer this over calling kebabToCamel() at runtime when the input is always
48
- * a VerbName (avoids a string scan in hot code paths).
49
- */
50
- export declare const KEBAB_TO_CAMEL: Record<VerbName, string>;
51
- /**
52
- * HANDLE_FREE_VERBS is the set of verbs that do not require a Client handle.
53
- * Currently only "version". Mirrors pkg/cabi/dispatch.go's handleFreeVerbs map.
54
- */
55
- export declare const HANDLE_FREE_VERBS: ReadonlySet<string>;
56
- /** Returns true if the given verb does not require a Client handle. */
57
- export declare function isHandleFree(verb: string): boolean;
package/dist/types.d.ts CHANGED
@@ -12,20 +12,47 @@ export interface Logger {
12
12
  /**
13
13
  * Options accepted by the `Client` constructor (SRD SR-1.2).
14
14
  *
15
- * `storePath` is the only required field. The others are optional overrides;
16
- * absent fields fall back to the same three-tier defaults as `pkg/api.Options`
17
- * (config-file value, then hardcoded fallback).
15
+ * All fields are optional. When omitted, the bundled CLI binary's own
16
+ * three-tier default resolution applies (config.toml value, then the CLI's
17
+ * hardcoded fallback such as `~/.agent-director/state.db`). The TS Client
18
+ * does NOT provide a fallback; it forwards user input verbatim to keep the
19
+ * CLI as the single source of truth for default resolution. See bug b.32k.
18
20
  *
19
21
  * Tilde expansion is handled TS-side by `src/internal/tilde.ts` before paths
20
- * cross the FFI boundary, so the C-ABI never receives a leading `~`.
22
+ * are forwarded to the CLI subprocess, so the subprocess never receives a
23
+ * leading `~`.
21
24
  */
22
25
  export interface ClientOptions {
23
- /** Path to the SQLite store file. Tilde-expanded before crossing FFI. */
24
- storePath: string;
25
- /** Path to the TOML config file. Tilde-expanded before crossing FFI. */
26
- configPath?: string;
27
- /** Override the tmux binary. Defaults to the binary on PATH. */
26
+ /**
27
+ * Path to the SQLite store file. Tilde-expanded before being forwarded as
28
+ * `--store-path` to the CLI subprocess.
29
+ *
30
+ * When omitted, the CLI's three-tier default resolution applies:
31
+ * 1. CLI flag (this field, when set) → 2. cfg.Store.DbPath in
32
+ * ~/.agent-director/config.toml → 3. hardcoded fallback
33
+ * ~/.agent-director/state.db.
34
+ *
35
+ * The TS Client no longer provides a fallback (b.32k).
36
+ */
37
+ storePath?: string;
38
+ /**
39
+ * Override the tmux binary. Tilde-expanded before being forwarded as
40
+ * `--tmux-command` to the CLI subprocess. When omitted, the CLI looks up
41
+ * `tmux` on PATH.
42
+ */
28
43
  tmuxCommand?: string;
44
+ /**
45
+ * Override HOME for the duration of every subprocess call this Client
46
+ * issues. Tilde-expanded before being forwarded as `--home` to the CLI
47
+ * subprocess.
48
+ *
49
+ * When omitted, the CLI subprocess inherits HOME from the calling process
50
+ * environment (which is the correct default — set HOME at the
51
+ * test-process level via withTempHome or similar). Set this only when you
52
+ * need the CLI to resolve `~/...` paths against a specific directory that
53
+ * differs from the calling process's HOME. b.32k.
54
+ */
55
+ home?: string;
29
56
  /**
30
57
  * When `true`, create the store and initialize the database schema if the
31
58
  * store file does not yet exist. When `false` (the default), opening a
@@ -34,6 +61,17 @@ export interface ClientOptions {
34
61
  createIfMissing?: boolean;
35
62
  /** Optional logger for client-side warnings (e.g., non-fatal close errors). */
36
63
  logger?: Logger;
64
+ /**
65
+ * Per-call timeout for the subprocess Client, in milliseconds. Default: 30000 (30 s).
66
+ *
67
+ * When a subprocess call exceeds this threshold the Client sends SIGTERM,
68
+ * waits up to 2 seconds for a graceful exit, then sends SIGKILL. The
69
+ * in-flight call's promise rejects with ErrCallTimeout.
70
+ *
71
+ * Zero or negative values are rejected at Client construction time.
72
+ * (SRD SR-6.1)
73
+ */
74
+ callTimeoutMs?: number;
37
75
  }
38
76
  /** Mirrors pkg/api.VerbSummary — one entry in the `help` verb result. */
39
77
  export interface VerbSummary {
@@ -76,7 +114,7 @@ export interface ListRow {
76
114
  /** Set when state moves to ended (omitted while live). */
77
115
  ended_at?: string | null;
78
116
  }
79
- /** Mirrors pkg/cabi/verbs_read.go::ad_spawn params */
117
+ /** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
80
118
  export interface SpawnParams {
81
119
  /** Absolute (or ~/-prefixed) path the Spawn's Claude starts in. Required. */
82
120
  cwd: string;
@@ -108,7 +146,7 @@ export interface SpawnResult {
108
146
  /** The id the new Spawn is tracked under. */
109
147
  claude_instance_id: string;
110
148
  }
111
- /** Mirrors pkg/cabi/verbs_read.go::ad_status params */
149
+ /** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
112
150
  export interface StatusParams {
113
151
  /** Id of the Spawn to inspect. */
114
152
  claude_instance_id: string;
@@ -118,7 +156,7 @@ export interface StatusResult {
118
156
  /** Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing). */
119
157
  state: string;
120
158
  }
121
- /** Mirrors pkg/cabi/verbs_read.go::ad_get params */
159
+ /** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
122
160
  export interface GetParams {
123
161
  /** Id of the Spawn to fetch. */
124
162
  claude_instance_id: string;
@@ -144,7 +182,7 @@ export interface GetResult {
144
182
  /** Open permission request; present only when state=check_permission with an undecided row. */
145
183
  permission_request?: PermissionRequestInfo | null;
146
184
  }
147
- /** Mirrors pkg/cabi/verbs_read.go::ad_send_keys params (pkg/api.SendKeysParams json tags) */
185
+ /** Mirrors pkg/api.SendKeysParams (json tags). */
148
186
  export interface SendKeysParams {
149
187
  /** Id of the Spawn whose pane will receive the text. */
150
188
  claude_instance_id: string;
@@ -154,7 +192,7 @@ export interface SendKeysParams {
154
192
  /** Mirrors pkg/api/sendkeys.go::SendKeysResult (empty; reserved for future fields). */
155
193
  export interface SendKeysResult {
156
194
  }
157
- /** Mirrors pkg/cabi/verbs_read.go::ad_read_pane params (pkg/api.ReadPaneParams json tags) */
195
+ /** Mirrors pkg/api.ReadPaneParams (json tags). */
158
196
  export interface ReadPaneParams {
159
197
  /** Id of the Spawn whose pane will be captured. */
160
198
  claude_instance_id: string;
@@ -168,7 +206,7 @@ export interface ReadPaneResult {
168
206
  /** Captured pane text. */
169
207
  pane: string;
170
208
  }
171
- /** Mirrors pkg/cabi/verbs_control.go::ad_kill params (pkg/api.KillParams json tags) */
209
+ /** Mirrors pkg/api.KillParams (json tags). */
172
210
  export interface KillParams {
173
211
  /** Id of the Spawn to kill. */
174
212
  claude_instance_id: string;
@@ -176,7 +214,7 @@ export interface KillParams {
176
214
  /** Mirrors pkg/api/kill.go::KillResult (empty; reserved for future fields). */
177
215
  export interface KillResult {
178
216
  }
179
- /** Mirrors pkg/cabi/verbs_control.go::ad_decide params (pkg/api.DecideParams json tags) */
217
+ /** Mirrors pkg/api.DecideParams (json tags). */
180
218
  export interface DecideParams {
181
219
  /** Id of the Spawn whose open permission request is being decided. */
182
220
  claude_instance_id: string;
@@ -188,7 +226,7 @@ export interface DecideParams {
188
226
  /** Mirrors pkg/api/decide.go::DecideResult (empty; reserved for future fields). */
189
227
  export interface DecideResult {
190
228
  }
191
- /** Mirrors pkg/cabi/verbs_control.go::ad_resume params (pkg/api.ResumeParams json tags) */
229
+ /** Mirrors pkg/api.ResumeParams (json tags). */
192
230
  export interface ResumeParams {
193
231
  /** Id of the terminated Spawn to resurrect. */
194
232
  claude_instance_id: string;
@@ -198,7 +236,7 @@ export interface ResumeResult {
198
236
  /** Same id that was passed in (preserved across resurrection). */
199
237
  claude_instance_id: string;
200
238
  }
201
- /** Mirrors pkg/cabi/verbs_control.go::ad_find_missing params */
239
+ /** Mirrors the `find-missing` CLI verb's --timeout flag (pkg/api.Client.FindMissing ctx deadline). */
202
240
  export interface FindMissingParams {
203
241
  /** Optional deadline for the OS probe sweep (milliseconds). 0/omitted = no deadline. */
204
242
  timeout_ms?: number;
@@ -210,7 +248,7 @@ export interface FindMissingResult {
210
248
  /** Sorted ids of rows transitioned to missing. */
211
249
  ids: string[];
212
250
  }
213
- /** Mirrors pkg/cabi/verbs_admin.go::ad_expire params */
251
+ /** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
214
252
  export interface ExpireParams {
215
253
  /**
216
254
  * Duration override (e.g. "7d", "2h", "0d"). When omitted, the config
@@ -225,7 +263,7 @@ export interface ExpireResult {
225
263
  /** Sorted ids of rows removed. */
226
264
  ids: string[];
227
265
  }
228
- /** Mirrors pkg/cabi/verbs_admin.go::ad_delete params */
266
+ /** Mirrors the `delete` CLI verb's --claude-instance-id flag(s) (pkg/api.Client.Delete arg). */
229
267
  export interface DeleteParams {
230
268
  /** Id(s) to delete. */
231
269
  claude_instance_id: string[];
@@ -235,7 +273,7 @@ export interface DeleteResult {
235
273
  /** Per-id outcome: "ok" on success, err_name on failure. */
236
274
  results: Record<string, string>;
237
275
  }
238
- /** Mirrors pkg/cabi/verbs_admin.go::ad_make_template params */
276
+ /** Mirrors pkg/api.MakeTemplateParams (json tags). */
239
277
  export interface MakeTemplateParams {
240
278
  /** Template filename (without extension). Must be filename-safe. Required. */
241
279
  name: string;
@@ -267,7 +305,7 @@ export interface MakeTemplateResult {
267
305
  /** Absolute path of the written template TOML file. */
268
306
  path: string;
269
307
  }
270
- /** Mirrors pkg/cabi/verbs_read.go::ad_list params */
308
+ /** Mirrors pkg/api.ListParams (json tags). */
271
309
  export interface ListParams {
272
310
  /** Filter by state (multiple values OR together). */
273
311
  state?: string[];
@@ -287,7 +325,7 @@ export interface ListResult {
287
325
  /** Matching Spawn rows. Empty array when none match. */
288
326
  spawns: ListRow[];
289
327
  }
290
- /** Mirrors pkg/cabi/verbs_control.go::ad_pause params (pkg/api.PauseParams json tags) */
328
+ /** Mirrors pkg/api.PauseParams (json tags). */
291
329
  export interface PauseParams {
292
330
  /** Id of the Spawn to pause gracefully. */
293
331
  claude_instance_id: string;
@@ -295,13 +333,13 @@ export interface PauseParams {
295
333
  /** Mirrors pkg/api/pause.go::PauseResult (empty; reserved for future fields). */
296
334
  export interface PauseResult {
297
335
  }
298
- /** Mirrors pkg/cabi/verbs_admin.go::ad_version params (handle-free; no user params). */
336
+ /** Mirrors the `version` CLI verb (no user params; pkg/api.Client.Version takes none). */
299
337
  export interface VersionParams {
300
338
  }
301
339
  /** Mirrors pkg/api/version.go::VersionResult */
302
340
  export interface VersionResult {
303
- /** Human-readable version stamp. "dev" for unstamped builds. */
341
+ /** npm package version (e.g. "0.5.0"). Sourced from the installed agent-director package's package.json — not the CLI binary. See b.6o1. */
304
342
  version: string;
305
- /** Full git SHA. "unknown" for unstamped builds. */
343
+ /** CLI binary's full git SHA. "unknown" for unstamped builds. */
306
344
  commit: string;
307
345
  }