agent-director 0.4.4 → 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
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# agent-director
|
|
2
2
|
|
|
3
|
-
TypeScript/Bun client for the agent-director CLI
|
|
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
|
|
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
|
|
|
@@ -94,7 +100,7 @@ try {
|
|
|
94
100
|
}
|
|
95
101
|
```
|
|
96
102
|
|
|
97
|
-
`storePath` is the only required constructor option. Tilde expansion (`~` → home directory) is handled automatically before paths
|
|
103
|
+
`storePath` is the only required constructor option. 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"]`).
|
|
98
104
|
|
|
99
105
|
## Verb examples
|
|
100
106
|
|
|
@@ -208,4 +214,4 @@ The full `err_name` catalog is in [`../../pkg/api/errnames/catalog.json`](../../
|
|
|
208
214
|
|
|
209
215
|
## Architecture
|
|
210
216
|
|
|
211
|
-
See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle,
|
|
217
|
+
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
|
-
*
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
|
24
|
-
|
|
25
|
-
|
|
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
|
@@ -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
|
}
|
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, ErrUnknownHandle, } 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";
|