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 CHANGED
@@ -1,6 +1,8 @@
1
1
  # agent-director
2
2
 
3
- TypeScript/Bun client for the agent-director CLI (FFI-backed; shares the Go API surface 1:1).
3
+ TypeScript/Bun client for the agent-director CLI. Shares the Go API
4
+ surface 1:1. The `Client` spawns the bundled `agent-director` CLI
5
+ binary as a subprocess per verb call — no FFI, no network hop.
4
6
 
5
7
  ## Install
6
8
 
@@ -8,7 +10,11 @@ TypeScript/Bun client for the agent-director CLI (FFI-backed; shares the Go API
8
10
  bun add agent-director
9
11
  ```
10
12
 
11
- Requires Bun >=1.0.21. The package ships a prebuilt shared library for each supported platform via optional dependencies — they install automatically on `bun add`.
13
+ Requires Bun >=1.0.21. The package ships the prebuilt CLI binary for
14
+ each supported platform via optional dependencies — they install
15
+ automatically on `bun add`. The `Client` resolves the host's binary
16
+ at construction time via `import.meta.resolve('@agent-director/<host>/package.json')`
17
+ and spawns it for every verb call.
12
18
 
13
19
  On install, a postinstall script copies the `install-agent-director` skill body into `~/.claude/skills/install-agent-director/` so `claude /install-agent-director` is immediately discoverable in Claude Code. The postinstall only writes under `~/.claude/skills/`; it does not touch PATH, `~/.agent-director/`, or your Claude Code settings.
14
20
 
@@ -77,7 +83,7 @@ See Idea Bee `b.fg3` for cross-platform expansion status.
77
83
  `using` block (preferred):
78
84
 
79
85
  ```ts
80
- using client = new Client({ storePath: "~/.agent-director/state.db" });
86
+ using client = new Client({});
81
87
  const v = await client.version({});
82
88
  console.log(v.version);
83
89
  ```
@@ -85,7 +91,7 @@ console.log(v.version);
85
91
  Explicit `try/finally` (portable fallback):
86
92
 
87
93
  ```ts
88
- const client = new Client({ storePath: "~/.agent-director/state.db" });
94
+ const client = new Client({});
89
95
  try {
90
96
  const v = await client.version({});
91
97
  console.log(v.version);
@@ -94,7 +100,15 @@ try {
94
100
  }
95
101
  ```
96
102
 
97
- `storePath` is the only required constructor option. Tilde expansion (`~` → home directory) is handled automatically before paths cross the FFI boundary. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
103
+ All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. Tilde expansion (`~` → home directory) is handled automatically before paths are forwarded to the CLI subprocess. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
104
+
105
+ `ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
106
+
107
+ - `storePath` → `--store-path`
108
+ - `home` → `--home`
109
+ - `tmuxCommand` → `--tmux-command`
110
+
111
+ Set them only when the consumer needs to override the CLI's default for that field.
98
112
 
99
113
  ## Verb examples
100
114
 
@@ -208,4 +222,4 @@ The full `err_name` catalog is in [`../../pkg/api/errnames/catalog.json`](../../
208
222
 
209
223
  ## Architecture
210
224
 
211
- See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle, FFI call recipe, Per-platform packaging, Error mapping, TS smoke-test harness, and TS envelope-diff regression.
225
+ See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle, the subprocess call recipe, Per-platform packaging, Error mapping, TS smoke-test harness, and TS envelope-diff regression.
package/dist/client.d.ts CHANGED
@@ -1,99 +1,10 @@
1
- import type { ClientOptions } from "./types.js";
2
- 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";
3
- export { AgentDirectorError, ErrClientClosed } from "./errors.js";
4
- export type { ClientOptions } from "./types.js";
5
1
  /**
6
- * Client — the public entry point for agent-director.
7
- *
8
- * Construction is synchronous: the constructor calls `ad_open` over Bun FFI,
9
- * receives an opaque handle, and stores it. Every subsequent verb call will
10
- * carry this handle across the FFI boundary.
2
+ * client.ts — public Client export.
11
3
  *
12
- * Lifecycle:
13
- * 1. `new Client(opts)` → calls ad_open; throws on error envelope.
14
- * 2. `client.close()` → calls ad_close; idempotent, never throws.
15
- * 3. `[Symbol.dispose]()` → delegates to close() for `using` blocks.
16
- * 4. Any verb method calls `_assertOpen()` first; post-close calls throw
17
- * ErrClientClosed.
18
- *
19
- * Tilde expansion (`~` → home directory) is applied to `storePath` and
20
- * `configPath` TS-side before the paths cross the FFI boundary. The C-ABI
21
- * never receives a leading `~`.
4
+ * The subprocess implementation lives in internal/subprocessClient.ts; this
5
+ * file aliases it as the public `Client` and re-exports the two error symbols
6
+ * commonly imported alongside it so callers don't need separate imports.
22
7
  */
23
- export declare class Client {
24
- /** Opaque handle returned by ad_open. Nulled after close(). */
25
- private _handle;
26
- /** Whether this client is still open and usable. */
27
- private _open;
28
- /** Optional logger for non-fatal warnings (e.g. ad_close error envelopes). */
29
- private _logger;
30
- constructor(opts: ClientOptions);
31
- /**
32
- * _assertOpen throws ErrClientClosed if the client has been closed.
33
- * Called at the top of every verb method. May also be invoked from tests
34
- * via `(client as any)._assertOpen()` — TS private fields are erased at
35
- * runtime, so the cast works.
36
- */
37
- private _assertOpen;
38
- /**
39
- * close releases the ad_open handle via ad_close.
40
- *
41
- * - Idempotent: a second call is a no-op.
42
- * - Never throws: if ad_close returns an error envelope, the error is
43
- * logged via the optional logger (warn level) but the handle is still
44
- * nulled and _open set to false.
45
- */
46
- close(): void;
47
- /**
48
- * [Symbol.dispose] enables `using` block syntax (Explicit Resource Management).
49
- *
50
- * {
51
- * using client = new Client(opts);
52
- * // ... client.someVerb() ...
53
- * } // client.close() called automatically here
54
- */
55
- [Symbol.dispose](): void;
56
- /** spawn — launch a tracked Claude Code instance in a new tmux session. */
57
- spawn(params: SpawnParams): Promise<SpawnResult>;
58
- /** status — get the current state of a Spawn. */
59
- status(params: StatusParams): Promise<StatusResult>;
60
- /** get — fetch the full Spawn record. */
61
- get(params: GetParams): Promise<GetResult>;
62
- /** sendKeys — send keystrokes to a Spawn's tmux pane. */
63
- sendKeys(params: SendKeysParams): Promise<SendKeysResult>;
64
- /** readPane — read the current contents of a Spawn's tmux pane. */
65
- readPane(params: ReadPaneParams): Promise<ReadPaneResult>;
66
- /** kill — terminate a Spawn's tmux session. */
67
- kill(params: KillParams): Promise<KillResult>;
68
- /** decide — resolve a pending permission request. */
69
- decide(params: DecideParams): Promise<DecideResult>;
70
- /** resume — restart a terminated Spawn via `claude --resume`. */
71
- resume(params: ResumeParams): Promise<ResumeResult>;
72
- /** findMissing — reconcile Spawns whose tmux sessions have disappeared. */
73
- findMissing(params: FindMissingParams): Promise<FindMissingResult>;
74
- /** expire — remove terminal-state rows older than the retention window. */
75
- expire(params: ExpireParams): Promise<ExpireResult>;
76
- /** delete — hard-delete Spawn rows by id. */
77
- delete(params: DeleteParams): Promise<DeleteResult>;
78
- /** makeTemplate — save a reusable spawn preset. */
79
- makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
80
- /** list — query Spawns with optional filter params. */
81
- list(params: ListParams): Promise<ListResult>;
82
- /** pause — politely shut down a waiting Spawn. */
83
- pause(params: PauseParams): Promise<PauseResult>;
84
- /**
85
- * version — return the binary's build-time version stamp.
86
- *
87
- * This is the only handle-free verb: it passes null instead of the Client
88
- * handle because the C-ABI ignores any handle field for ad_version.
89
- */
90
- version(params: VersionParams): Promise<VersionResult>;
91
- /**
92
- * _assertOpenForTests exposes _assertOpen to test code without forcing
93
- * public visibility. TypeScript `private` is erased at runtime, but this
94
- * alias makes the intent explicit and avoids the `(client as any)` cast.
95
- *
96
- * @internal Tests only — do not call from application code.
97
- */
98
- _assertOpenForTests(): void;
99
- }
8
+ export { SubprocessClient as Client } from "./internal/subprocessClient.js";
9
+ export { AgentDirectorError, ErrClientClosed } from "./errors.js";
10
+ export type { ClientOptions } from "./types.js";
package/dist/errors.d.ts CHANGED
@@ -5,7 +5,7 @@ export { TS_ONLY_ERROR_NAMES } from "./internal/tsOnlyErrors.js";
5
5
  *
6
6
  * `verb` names the callable verb that triggered the error (e.g. "spawn").
7
7
  * `errName` is the canonical error name from the Go errnames catalog.
8
- * `errDescription` is the human-readable description from the C-ABI envelope.
8
+ * `errDescription` is the human-readable description from the subprocess error envelope.
9
9
  * `message` is formatted as "${errName}: ${errDescription}".
10
10
  */
11
11
  export declare class AgentDirectorError extends Error {
@@ -13,7 +13,7 @@ export declare class AgentDirectorError extends Error {
13
13
  readonly verb: string;
14
14
  /** Canonical error name, matching the Go errnames catalog (e.g. "ErrSpawnNotFound"). */
15
15
  readonly errName: string;
16
- /** Human-readable description forwarded from the C-ABI envelope. */
16
+ /** Human-readable description forwarded from the subprocess error envelope. */
17
17
  readonly errDescription: string;
18
18
  constructor(verb: string, err_name: string, err_description: string);
19
19
  }
@@ -58,6 +58,67 @@ export declare class ErrPlatformPackageMissing extends AgentDirectorError {
58
58
  export declare class ErrBunVersionTooOld extends AgentDirectorError {
59
59
  constructor(actual: string, minimum: string);
60
60
  }
61
+ /**
62
+ * ErrCliNotExecutable — thrown when the resolved CLI binary exists on disk but
63
+ * does not have execute permission for the current process's effective uid/gid.
64
+ *
65
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
66
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
67
+ * Implements SRD SR-2.3.
68
+ */
69
+ export declare class ErrCliNotExecutable extends AgentDirectorError {
70
+ constructor(path: string);
71
+ }
72
+ /**
73
+ * ErrConsumerSignal — thrown when an in-flight subprocess call is killed by an
74
+ * OS signal (e.g. SIGTERM, SIGINT delivered to the consumer process group).
75
+ *
76
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
77
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
78
+ * Implements SRD SR-5.2/SR-5.4.
79
+ */
80
+ export declare class ErrConsumerSignal extends AgentDirectorError {
81
+ /** The signal name that killed the subprocess (e.g. "SIGTERM", "SIGINT"). */
82
+ readonly signal: string;
83
+ constructor(verb: string, signal: string);
84
+ }
85
+ /**
86
+ * ErrCallTimeout — thrown when the per-call timeout (ClientOptions.callTimeoutMs,
87
+ * default 30 s) elapses before the subprocess exits. The subprocess is sent SIGTERM
88
+ * then SIGKILL before the error is surfaced.
89
+ *
90
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
91
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
92
+ * Implements SRD SR-6.2/SR-6.5.
93
+ */
94
+ export declare class ErrCallTimeout extends AgentDirectorError {
95
+ /** Approximate elapsed time in milliseconds when the timeout fired. */
96
+ readonly elapsedMs: number;
97
+ /** The configured timeout threshold in milliseconds. */
98
+ readonly timeoutMs: number;
99
+ constructor(verb: string, elapsedMs: number, timeoutMs: number);
100
+ }
101
+ /**
102
+ * ErrUnknownErrorName — thrown when a subprocess JSON envelope contains an
103
+ * `err_name` field that is not present in the static catalog-derived error map.
104
+ * This indicates the Go-side catalog has a new entry that the TS catalog has
105
+ * not yet been regenerated to include.
106
+ *
107
+ * Constructor: `new ErrUnknownErrorName(unknownName, envelope)`
108
+ * - `unknownName` — the unrecognised err_name string from the envelope.
109
+ * - `envelope` — the full envelope payload for diagnostic use.
110
+ *
111
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
112
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
113
+ * Implements SRD SR-4.3.
114
+ */
115
+ export declare class ErrUnknownErrorName extends AgentDirectorError {
116
+ /** The unrecognised err_name string from the envelope. Also in `.message`. */
117
+ readonly unknownName: string;
118
+ /** The full envelope payload for diagnostic use. */
119
+ readonly envelope: unknown;
120
+ constructor(unknownName: string, envelope: unknown);
121
+ }
61
122
  /** Mirrors ErrCwdMissing (package: spawn) */
62
123
  export declare class ErrCwdMissing extends AgentDirectorError {
63
124
  }
@@ -157,12 +218,9 @@ export declare class ErrNoOpenPermissionRequest extends AgentDirectorError {
157
218
  /** Mirrors ErrAlreadyDecided (package: store) */
158
219
  export declare class ErrAlreadyDecided extends AgentDirectorError {
159
220
  }
160
- /** Mirrors ErrUnknownHandle (package: cabi, scope: cabi) */
161
- export declare class ErrUnknownHandle extends AgentDirectorError {
162
- }
163
221
  /**
164
222
  * errorFromEnvelope creates a typed AgentDirectorError subclass from the
165
- * C-ABI error envelope fields.
223
+ * subprocess error envelope fields.
166
224
  *
167
225
  * @param verb The verb name that produced the error (e.g. "spawn").
168
226
  * @param err_name The canonical error name from the envelope.
package/dist/index.d.ts CHANGED
@@ -1,10 +1,8 @@
1
1
  /**
2
2
  * Public entry point for agent-director.
3
- *
4
- * ffi.ts and platform.ts are internal — they are NOT re-exported here.
5
3
  */
6
4
  export { Client } from "./client.js";
7
- export { AgentDirectorError, ErrClientClosed, ErrUnsupportedPlatform, ErrPlatformPackageMissing, ErrBunVersionTooOld, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrRelayModeOff, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, ErrUnknownHandle, } from "./errors.js";
5
+ export { AgentDirectorError, ErrClientClosed, ErrUnsupportedPlatform, ErrPlatformPackageMissing, ErrBunVersionTooOld, ErrCliNotExecutable, ErrConsumerSignal, ErrCallTimeout, ErrUnknownErrorName, errorFromEnvelope, ErrCwdMissing, ErrCwdNotAPath, ErrCwdNotFound, ErrCwdNotADirectory, ErrRelayModeInvalid, ErrSpawnDeniedFlag, ErrReservedEnvKey, ErrInstanceIdCollision, ErrTmuxSessionNameEmpty, ErrTmuxSessionNameInvalid, ErrTmuxSessionNameTooLong, ErrSpawnNotFound, ErrTmuxNotAvailable, ErrTmuxSessionCreate, ErrTmuxSendKeys, ErrTmuxCaptureFailed, ErrSpawnNotInteractive, ErrSendKeysWhileRelayed, ErrSpawnNotPausable, ErrPauseTimeout, ErrListInvalidLabel, ErrTemplateNameUnsafe, ErrTemplateNotFound, ErrTemplateMalformed, ErrTemplateExists, ErrProbeUnsupported, ErrSpawnNotResumable, ErrNoSessionId, ErrJsonlMissing, ErrRelayModeOff, ErrInvalidDecision, ErrNoOpenPermissionRequest, ErrAlreadyDecided, } from "./errors.js";
8
6
  export type { ClientOptions, Logger } from "./types.js";
9
7
  export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
10
8
  export 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";