agent-director 0.4.5 → 0.5.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.
- package/README.md +10 -4
- package/dist/client.d.ts +7 -96
- package/dist/errors.d.ts +61 -0
- package/dist/index.d.ts +1 -3
- package/dist/index.js +743 -315
- package/dist/internal/argv.d.ts +32 -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/types.d.ts +15 -3
- 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,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* argv.ts — verb-driven argv builder for the subprocess Client.
|
|
3
|
+
*
|
|
4
|
+
* Exports a single pure function `buildArgv(cliPath, verb, params)` that
|
|
5
|
+
* converts typed verb parameters into a complete CLI argv array:
|
|
6
|
+
*
|
|
7
|
+
* [cliPath, verbName, ...flags]
|
|
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
|
+
*
|
|
18
|
+
* Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
|
|
19
|
+
*
|
|
20
|
+
* Internal — NOT re-exported from src/index.ts.
|
|
21
|
+
*/
|
|
22
|
+
import type { VerbName } from "./verbs.js";
|
|
23
|
+
/**
|
|
24
|
+
* buildArgv converts a CLI binary path, verb name, and typed parameters into
|
|
25
|
+
* a complete CLI argv array: [cliPath, verbName, ...flags].
|
|
26
|
+
*
|
|
27
|
+
* @param cliPath The absolute path to the CLI binary (argv[0]).
|
|
28
|
+
* @param verb The kebab-case verb name (must be a VerbName).
|
|
29
|
+
* @param params The typed params object for the verb.
|
|
30
|
+
* @returns The full argv array starting with cliPath.
|
|
31
|
+
*/
|
|
32
|
+
export declare function buildArgv(cliPath: string, verb: VerbName, params: unknown): 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` (34 entries as of 2026-05-24). 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 binary's build-time version stamp. */
|
|
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/types.d.ts
CHANGED
|
@@ -17,12 +17,13 @@ export interface Logger {
|
|
|
17
17
|
* (config-file value, then hardcoded fallback).
|
|
18
18
|
*
|
|
19
19
|
* Tilde expansion is handled TS-side by `src/internal/tilde.ts` before paths
|
|
20
|
-
*
|
|
20
|
+
* are forwarded to the CLI subprocess, so the subprocess never receives a
|
|
21
|
+
* leading `~`.
|
|
21
22
|
*/
|
|
22
23
|
export interface ClientOptions {
|
|
23
|
-
/** Path to the SQLite store file. Tilde-expanded before
|
|
24
|
+
/** Path to the SQLite store file. Tilde-expanded before being forwarded. */
|
|
24
25
|
storePath: string;
|
|
25
|
-
/** Path to the TOML config file. Tilde-expanded before
|
|
26
|
+
/** Path to the TOML config file. Tilde-expanded before being forwarded. */
|
|
26
27
|
configPath?: string;
|
|
27
28
|
/** Override the tmux binary. Defaults to the binary on PATH. */
|
|
28
29
|
tmuxCommand?: string;
|
|
@@ -34,6 +35,17 @@ export interface ClientOptions {
|
|
|
34
35
|
createIfMissing?: boolean;
|
|
35
36
|
/** Optional logger for client-side warnings (e.g., non-fatal close errors). */
|
|
36
37
|
logger?: Logger;
|
|
38
|
+
/**
|
|
39
|
+
* Per-call timeout for the subprocess Client, in milliseconds. Default: 30000 (30 s).
|
|
40
|
+
*
|
|
41
|
+
* When a subprocess call exceeds this threshold the Client sends SIGTERM,
|
|
42
|
+
* waits up to 2 seconds for a graceful exit, then sends SIGKILL. The
|
|
43
|
+
* in-flight call's promise rejects with ErrCallTimeout.
|
|
44
|
+
*
|
|
45
|
+
* Zero or negative values are rejected at Client construction time.
|
|
46
|
+
* (SRD SR-6.1)
|
|
47
|
+
*/
|
|
48
|
+
callTimeoutMs?: number;
|
|
37
49
|
}
|
|
38
50
|
/** Mirrors pkg/api.VerbSummary — one entry in the `help` verb result. */
|
|
39
51
|
export interface VerbSummary {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-director",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"os": [
|
|
6
6
|
"linux",
|
|
@@ -39,11 +39,12 @@
|
|
|
39
39
|
"prepack": "bun run build && bun run scripts/stage-skill.ts",
|
|
40
40
|
"postinstall": "bun run scripts/postinstall.ts",
|
|
41
41
|
"version-bump-publish": "bun run scripts/version-bump.ts",
|
|
42
|
-
"prepublishOnly": "bun run scripts/prepublish-guards.ts"
|
|
42
|
+
"prepublishOnly": "bun run scripts/prepublish-guards.ts",
|
|
43
|
+
"verify-installed-pkg": "bun run scripts/verify-installed-pkg.ts"
|
|
43
44
|
},
|
|
44
45
|
"optionalDependencies": {
|
|
45
|
-
"@agent-director/linux-x64": "^0.
|
|
46
|
-
"@agent-director/darwin-arm64": "^0.
|
|
46
|
+
"@agent-director/linux-x64": "^0.5.0",
|
|
47
|
+
"@agent-director/darwin-arm64": "^0.5.0"
|
|
47
48
|
},
|
|
48
49
|
"devDependencies": {
|
|
49
50
|
"typescript": ">=5.2.0",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: install-agent-director
|
|
3
3
|
description: Install (or upgrade) agent-director on this machine. Runs the bundled install.sh against the user's ~/ — creates ~/.agent-director/ with the binary, warms up state.db, and injects two persistent `agent-director help` hooks into ~/.claude/settings.json (SessionStart + SessionEnd reason=compact). Use this skill when the user says "install agent-director", "set up agent-director", or "upgrade agent-director on this machine".
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.5.0
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
## When to invoke
|
package/dist/ffi.d.ts
DELETED
|
@@ -1,42 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* ffi.ts — public facade for the C-ABI call recipe.
|
|
3
|
-
*
|
|
4
|
-
* The six-step FFI recipe is split across three files:
|
|
5
|
-
*
|
|
6
|
-
* src/internal/worker.ts — steps 1–4 (runs inside the worker thread)
|
|
7
|
-
* 1. Encode params as null-terminated UTF-8 JSON
|
|
8
|
-
* 2. Call the C symbol via Bun dlopen
|
|
9
|
-
* 3. Copy the returned CString to a JS string
|
|
10
|
-
* 4. Free the C pointer via ad_free_cstring (try/finally — error path frees too)
|
|
11
|
-
*
|
|
12
|
-
* src/internal/workerProxy.ts — steps 5–6 (main thread, post-worker)
|
|
13
|
-
* 5. Parse the raw JSON string
|
|
14
|
-
* 6. If err_name present → throw typed error via errorFromEnvelope;
|
|
15
|
-
* else → return parsed result
|
|
16
|
-
*
|
|
17
|
-
* src/ffi.ts (this file) — thin public facade
|
|
18
|
-
* Exposes callVerb<P, R> that routes to workerProxy.dispatch and casts.
|
|
19
|
-
*
|
|
20
|
-
* WHY a worker?
|
|
21
|
-
* Bun FFI has no per-symbol `async: true` marker. Without the worker, every
|
|
22
|
-
* C call would block the JS event loop. The worker runs in a separate thread
|
|
23
|
-
* so verb calls are off-main-thread and the event loop stays responsive.
|
|
24
|
-
* See src/internal/workerProxy.ts for the singleton design rationale.
|
|
25
|
-
*
|
|
26
|
-
* Internal — NOT re-exported from src/index.ts.
|
|
27
|
-
*/
|
|
28
|
-
export { VERBS, KEBAB_TO_CAMEL } from "./internal/verbs.js";
|
|
29
|
-
export type { VerbName } from "./internal/verbs.js";
|
|
30
|
-
export { BINDING_SYMBOL_NAMES } from "./internal/bindingSpec.js";
|
|
31
|
-
export { shutdown as shutdownWorker } from "./internal/workerProxy.js";
|
|
32
|
-
/**
|
|
33
|
-
* callVerb dispatches a verb call through the dedicated worker thread and
|
|
34
|
-
* returns a Promise that resolves with the typed result R or rejects with a
|
|
35
|
-
* typed AgentDirectorError.
|
|
36
|
-
*
|
|
37
|
-
* @param verb Kebab-case verb name (e.g. "send-keys", "make-template")
|
|
38
|
-
* @param handle Opaque Client handle from ad_open, or null for handle-free
|
|
39
|
-
* verbs (currently only "version")
|
|
40
|
-
* @param params Verb-specific params object; JSON-serialized inside dispatch
|
|
41
|
-
*/
|
|
42
|
-
export declare function callVerb<P, R>(verb: string, handle: string | null, params: P): Promise<R>;
|
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* bindingSpec — canonical set of C-ABI symbol names expected in the dlopen
|
|
3
|
-
* binding object, plus a factory that builds the runtime FFI binding spec.
|
|
4
|
-
*
|
|
5
|
-
* BINDING_SYMBOL_NAMES is exported as a plain string array so the
|
|
6
|
-
* binding-coverage test can import it WITHOUT spawning a worker or loading
|
|
7
|
-
* the native library.
|
|
8
|
-
*
|
|
9
|
-
* buildBindingSpec() returns the full FFI binding object suitable for passing
|
|
10
|
-
* directly to Bun's dlopen(). It is the single source of truth consumed by
|
|
11
|
-
* platform.ts::loadNative() so that worker.ts and bootstrapFfi.ts both
|
|
12
|
-
* resolve the same symbols without duplication.
|
|
13
|
-
*
|
|
14
|
-
* Any drift between BINDING_SYMBOL_NAMES and buildBindingSpec() is caught
|
|
15
|
-
* by test/ffi-binding-coverage.test.ts.
|
|
16
|
-
*/
|
|
17
|
-
import { FFIType } from "bun:ffi";
|
|
18
|
-
/**
|
|
19
|
-
* BINDING_SYMBOL_NAMES is the exhaustive list of C symbols that the worker's
|
|
20
|
-
* dlopen binding object must declare.
|
|
21
|
-
*/
|
|
22
|
-
export declare const BINDING_SYMBOL_NAMES: readonly string[];
|
|
23
|
-
/** A single FFI function declaration (args + return type). */
|
|
24
|
-
export interface FFISymbolDef {
|
|
25
|
-
args: FFIType[];
|
|
26
|
-
returns: FFIType;
|
|
27
|
-
}
|
|
28
|
-
/** The full dlopen binding spec as a plain object — pass to Bun's dlopen(). */
|
|
29
|
-
export type BindingSpec = Record<string, FFISymbolDef>;
|
|
30
|
-
/**
|
|
31
|
-
* buildBindingSpec constructs the full FFI binding map for the native library.
|
|
32
|
-
*
|
|
33
|
-
* Includes lifecycle symbols (ad_open, ad_close, ad_free_cstring) plus one
|
|
34
|
-
* entry per callable verb. All verb symbols take a single cstring argument and
|
|
35
|
-
* return a ptr (raw pointer, freed via ad_free_cstring).
|
|
36
|
-
*/
|
|
37
|
-
export declare function buildBindingSpec(): BindingSpec;
|
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* bootstrapFfi — thin synchronous dlopen wrapper used by the Client
|
|
3
|
-
* constructor and close().
|
|
4
|
-
*
|
|
5
|
-
* Only three symbols are needed here: ad_open, ad_close, ad_free_cstring.
|
|
6
|
-
* The full binding spec (all 18 symbols) is used by worker.ts via loadNative().
|
|
7
|
-
*
|
|
8
|
-
* Library path resolution delegates to platform.ts::resolveNativePath() so
|
|
9
|
-
* that all platforms (linux-x64, darwin-arm64) resolve their binary from the
|
|
10
|
-
* correct optional sub-package, and so this file shares the same path logic
|
|
11
|
-
* as the worker.
|
|
12
|
-
*
|
|
13
|
-
* Internal — NOT re-exported from src/index.ts.
|
|
14
|
-
*/
|
|
15
|
-
/**
|
|
16
|
-
* callOpen encodes params as JSON, calls ad_open, copies the returned C
|
|
17
|
-
* string into a JS string, frees the C pointer, and returns the envelope
|
|
18
|
-
* JSON string.
|
|
19
|
-
*
|
|
20
|
-
* Throws if the library call itself fails (i.e. the function pointer is
|
|
21
|
-
* null) — normal Go-level errors are returned as error envelopes, not
|
|
22
|
-
* thrown.
|
|
23
|
-
*/
|
|
24
|
-
export declare function callOpen(params: {
|
|
25
|
-
store_path: string;
|
|
26
|
-
config_path?: string;
|
|
27
|
-
tmux_command?: string;
|
|
28
|
-
create_if_missing?: boolean;
|
|
29
|
-
}): string;
|
|
30
|
-
/**
|
|
31
|
-
* callClose encodes params as JSON, calls ad_close, copies the returned C
|
|
32
|
-
* string into a JS string, frees the C pointer, and returns the envelope
|
|
33
|
-
* JSON string.
|
|
34
|
-
*/
|
|
35
|
-
export declare function callClose(params: {
|
|
36
|
-
handle: string;
|
|
37
|
-
}): string;
|
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* FreeGuard — single-free wrapper for native pointers.
|
|
3
|
-
*
|
|
4
|
-
* Every C-ABI call that returns a pointer must pass it to `ad_free_cstring`
|
|
5
|
-
* exactly once. FreeGuard enforces this:
|
|
6
|
-
*
|
|
7
|
-
* const guard = new FreeGuard(rawPtr, (p) => lib.symbols.ad_free_cstring(p));
|
|
8
|
-
* try {
|
|
9
|
-
* const str = new CString(guard.ptr!).toString();
|
|
10
|
-
* return str;
|
|
11
|
-
* } finally {
|
|
12
|
-
* guard.free(); // safe to call even on error path; no-op on second call
|
|
13
|
-
* }
|
|
14
|
-
*
|
|
15
|
-
* Design constraints:
|
|
16
|
-
* - No bun:ffi imports — accepts the free function as a constructor arg so
|
|
17
|
-
* tests can stub it without loading a native library.
|
|
18
|
-
* - Generic over T so the same guard works for Pointer (branded number) or
|
|
19
|
-
* any other pointer-like primitive without widening to `any`.
|
|
20
|
-
* - `free()` nulls the internal reference before calling the underlying
|
|
21
|
-
* free function, so a synchronous exception inside the free function
|
|
22
|
-
* cannot cause a double-free on a subsequent call.
|
|
23
|
-
*/
|
|
24
|
-
export declare class FreeGuard<T> {
|
|
25
|
-
private _ptr;
|
|
26
|
-
private readonly _free;
|
|
27
|
-
constructor(ptr: T, free: (p: T) => void);
|
|
28
|
-
/**
|
|
29
|
-
* ptr returns the guarded pointer, or null if `free()` has already been
|
|
30
|
-
* called. Callers must check for null before dereferencing.
|
|
31
|
-
*/
|
|
32
|
-
get ptr(): T | null;
|
|
33
|
-
/**
|
|
34
|
-
* free calls the underlying free function with the guarded pointer exactly
|
|
35
|
-
* once. After the first call, the internal reference is nulled and
|
|
36
|
-
* subsequent calls are silent no-ops.
|
|
37
|
-
*/
|
|
38
|
-
free(): void;
|
|
39
|
-
}
|
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* worker.ts — worker-thread entry-point for all C-ABI FFI calls.
|
|
3
|
-
*
|
|
4
|
-
* This module runs INSIDE a node:worker_threads Worker. It is never imported
|
|
5
|
-
* by the main thread. Its sole job is:
|
|
6
|
-
*
|
|
7
|
-
* 1. At startup: resolve the native library path via loadNative(), post {type:"ready"}.
|
|
8
|
-
* 2. On every message: receive {id, op, handle, paramsJSON}, build the
|
|
9
|
-
* single-arg JSON for the C symbol, call it, copy the returned C string
|
|
10
|
-
* to JS, free the native pointer (try/finally so the error path also
|
|
11
|
-
* frees), and post the raw JSON string back to the main thread.
|
|
12
|
-
*
|
|
13
|
-
* WHY a dedicated worker?
|
|
14
|
-
* ───────────────────────
|
|
15
|
-
* Bun's dlopen has no per-symbol `async: true` marker. Calling a C function
|
|
16
|
-
* directly on the main thread blocks the JS event loop for the duration of
|
|
17
|
-
* that call. By running all FFI in a dedicated worker, verb calls are truly
|
|
18
|
-
* off-main-thread — the event loop remains responsive during long-running
|
|
19
|
-
* Go-side operations.
|
|
20
|
-
*
|
|
21
|
-
* One worker per process (singleton, not a pool): the Go runtime inside the
|
|
22
|
-
* shared library carries process-global state (the handle registry). Multiple
|
|
23
|
-
* parallel dlopen handles would split that state and break audit-trail
|
|
24
|
-
* invariants. A single serialized worker is the correct model.
|
|
25
|
-
*
|
|
26
|
-
* Wire format for C calls
|
|
27
|
-
* ───────────────────────
|
|
28
|
-
* Every C-ABI function takes exactly ONE `char* params_json` argument and
|
|
29
|
-
* returns `char* result_json` (which the caller must release via
|
|
30
|
-
* ad_free_cstring). The handle field is embedded inside the JSON:
|
|
31
|
-
* - ad_open → paramsJSON (no handle)
|
|
32
|
-
* - ad_close → {"handle":"<token>"}
|
|
33
|
-
* - ad_<verb> → {"handle":"<token>", ...verb-params}
|
|
34
|
-
* - ad_version → {} (handle-free)
|
|
35
|
-
*/
|
|
36
|
-
export {};
|