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.
- package/README.md +20 -6
- package/dist/client.d.ts +7 -96
- package/dist/errors.d.ts +64 -6
- package/dist/index.d.ts +1 -3
- package/dist/index.js +802 -321
- package/dist/internal/argv.d.ts +61 -0
- package/dist/internal/errorMap.d.ts +55 -0
- package/dist/internal/platformResolve.d.ts +69 -0
- package/dist/internal/spawner.d.ts +75 -0
- package/dist/internal/subprocessClient.d.ts +101 -0
- package/dist/internal/tsOnlyErrors.d.ts +8 -4
- package/dist/internal/verbs.d.ts +1 -39
- package/dist/types.d.ts +64 -26
- package/package.json +5 -4
- package/skills/install-agent-director/SKILL.md +1 -1
- package/dist/ffi.d.ts +0 -42
- package/dist/internal/bindingSpec.d.ts +0 -37
- package/dist/internal/bootstrapFfi.d.ts +0 -37
- package/dist/internal/freeGuard.d.ts +0 -39
- package/dist/internal/worker.d.ts +0 -36
- package/dist/internal/worker.js +0 -415
- package/dist/internal/workerProxy.d.ts +0 -45
- package/dist/platform.d.ts +0 -80
|
@@ -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
|
|
16
|
-
* - ErrUnsupportedPlatform
|
|
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
|
|
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];
|
package/dist/internal/verbs.d.ts
CHANGED
|
@@ -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
|
|
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
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
-
*
|
|
22
|
+
* are forwarded to the CLI subprocess, so the subprocess never receives a
|
|
23
|
+
* leading `~`.
|
|
21
24
|
*/
|
|
22
25
|
export interface ClientOptions {
|
|
23
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
343
|
+
/** CLI binary's full git SHA. "unknown" for unstamped builds. */
|
|
306
344
|
commit: string;
|
|
307
345
|
}
|