agent-director 0.5.0 → 0.5.3
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 +15 -6
- package/dist/errors.d.ts +3 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +94 -35
- package/dist/internal/argv.d.ts +38 -9
- package/dist/internal/errorMap.d.ts +1 -1
- package/dist/internal/subprocessClient.d.ts +1 -1
- package/dist/internal/verbs.d.ts +1 -39
- package/dist/types.d.ts +51 -25
- package/package.json +3 -3
- package/skills/install-agent-director/SKILL.md +1 -1
package/README.md
CHANGED
|
@@ -12,9 +12,10 @@ bun add agent-director
|
|
|
12
12
|
|
|
13
13
|
Requires Bun >=1.0.21. The package ships the prebuilt CLI binary for
|
|
14
14
|
each supported platform via optional dependencies — they install
|
|
15
|
-
automatically on `bun add`. The `Client`
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
automatically on `bun add`. The `Client` verifies the binary is present at construction time so install
|
|
16
|
+
errors surface immediately, then re-resolves its path on every verb call so
|
|
17
|
+
a binary replacement (e.g. a background `bun install`) is handled
|
|
18
|
+
transparently.
|
|
18
19
|
|
|
19
20
|
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.
|
|
20
21
|
|
|
@@ -83,7 +84,7 @@ See Idea Bee `b.fg3` for cross-platform expansion status.
|
|
|
83
84
|
`using` block (preferred):
|
|
84
85
|
|
|
85
86
|
```ts
|
|
86
|
-
using client = new Client({
|
|
87
|
+
using client = new Client({});
|
|
87
88
|
const v = await client.version({});
|
|
88
89
|
console.log(v.version);
|
|
89
90
|
```
|
|
@@ -91,7 +92,7 @@ console.log(v.version);
|
|
|
91
92
|
Explicit `try/finally` (portable fallback):
|
|
92
93
|
|
|
93
94
|
```ts
|
|
94
|
-
const client = new Client({
|
|
95
|
+
const client = new Client({});
|
|
95
96
|
try {
|
|
96
97
|
const v = await client.version({});
|
|
97
98
|
console.log(v.version);
|
|
@@ -100,7 +101,15 @@ try {
|
|
|
100
101
|
}
|
|
101
102
|
```
|
|
102
103
|
|
|
103
|
-
`
|
|
104
|
+
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"]`).
|
|
105
|
+
|
|
106
|
+
`ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
|
|
107
|
+
|
|
108
|
+
- `storePath` → `--store-path`
|
|
109
|
+
- `home` → `--home`
|
|
110
|
+
- `tmuxCommand` → `--tmux-command`
|
|
111
|
+
|
|
112
|
+
Set them only when the consumer needs to override the CLI's default for that field.
|
|
104
113
|
|
|
105
114
|
## Verb examples
|
|
106
115
|
|
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
|
|
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
|
|
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
|
}
|
|
@@ -218,12 +218,9 @@ export declare class ErrNoOpenPermissionRequest extends AgentDirectorError {
|
|
|
218
218
|
/** Mirrors ErrAlreadyDecided (package: store) */
|
|
219
219
|
export declare class ErrAlreadyDecided extends AgentDirectorError {
|
|
220
220
|
}
|
|
221
|
-
/** Mirrors ErrUnknownHandle (package: cabi, scope: cabi) */
|
|
222
|
-
export declare class ErrUnknownHandle extends AgentDirectorError {
|
|
223
|
-
}
|
|
224
221
|
/**
|
|
225
222
|
* errorFromEnvelope creates a typed AgentDirectorError subclass from the
|
|
226
|
-
*
|
|
223
|
+
* subprocess error envelope fields.
|
|
227
224
|
*
|
|
228
225
|
* @param verb The verb name that produced the error (e.g. "spawn").
|
|
229
226
|
* @param err_name The canonical error name from the envelope.
|
package/dist/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Public entry point for agent-director.
|
|
3
3
|
*/
|
|
4
4
|
export { Client } from "./client.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,
|
|
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";
|
|
6
6
|
export type { ClientOptions, Logger } from "./types.js";
|
|
7
7
|
export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
|
|
8
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";
|
package/dist/index.js
CHANGED
|
@@ -14,9 +14,6 @@ var __export = (target, all) => {
|
|
|
14
14
|
});
|
|
15
15
|
};
|
|
16
16
|
|
|
17
|
-
// src/internal/subprocessClient.ts
|
|
18
|
-
import { dirname as dirname2, basename } from "path";
|
|
19
|
-
|
|
20
17
|
// src/internal/platformResolve.ts
|
|
21
18
|
import { statSync } from "fs";
|
|
22
19
|
import { fileURLToPath } from "url";
|
|
@@ -28,7 +25,6 @@ __export(exports_errors, {
|
|
|
28
25
|
errorFromEnvelope: () => errorFromEnvelope,
|
|
29
26
|
TS_ONLY_ERROR_NAMES: () => TS_ONLY_ERROR_NAMES,
|
|
30
27
|
ErrUnsupportedPlatform: () => ErrUnsupportedPlatform,
|
|
31
|
-
ErrUnknownHandle: () => ErrUnknownHandle,
|
|
32
28
|
ErrUnknownErrorName: () => ErrUnknownErrorName,
|
|
33
29
|
ErrTmuxSessionNameTooLong: () => ErrTmuxSessionNameTooLong,
|
|
34
30
|
ErrTmuxSessionNameInvalid: () => ErrTmuxSessionNameInvalid,
|
|
@@ -272,9 +268,6 @@ class ErrNoOpenPermissionRequest extends AgentDirectorError {
|
|
|
272
268
|
|
|
273
269
|
class ErrAlreadyDecided extends AgentDirectorError {
|
|
274
270
|
}
|
|
275
|
-
|
|
276
|
-
class ErrUnknownHandle extends AgentDirectorError {
|
|
277
|
-
}
|
|
278
271
|
var ERROR_TABLE = {
|
|
279
272
|
ErrCwdMissing,
|
|
280
273
|
ErrCwdNotAPath,
|
|
@@ -308,8 +301,7 @@ var ERROR_TABLE = {
|
|
|
308
301
|
ErrTemplateNotFound,
|
|
309
302
|
ErrTemplateMalformed,
|
|
310
303
|
ErrTemplateExists,
|
|
311
|
-
ErrProbeUnsupported
|
|
312
|
-
ErrUnknownHandle
|
|
304
|
+
ErrProbeUnsupported
|
|
313
305
|
};
|
|
314
306
|
function errorFromEnvelope(verb, err_name, err_description) {
|
|
315
307
|
const Ctor = ERROR_TABLE[err_name];
|
|
@@ -400,9 +392,22 @@ function expandTilde(p) {
|
|
|
400
392
|
}
|
|
401
393
|
|
|
402
394
|
// src/internal/argv.ts
|
|
403
|
-
function buildArgv(cliPath, verb, params) {
|
|
395
|
+
function buildArgv(cliPath, verb, params, globalOpts) {
|
|
396
|
+
const globalFlags = buildGlobalFlags(globalOpts);
|
|
404
397
|
const verbFlags = buildVerbFlags(verb, params);
|
|
405
|
-
return [cliPath, ...verbFlags];
|
|
398
|
+
return [cliPath, ...globalFlags, ...verbFlags];
|
|
399
|
+
}
|
|
400
|
+
function buildGlobalFlags(opts) {
|
|
401
|
+
if (!opts)
|
|
402
|
+
return [];
|
|
403
|
+
const f = [];
|
|
404
|
+
if (opts.storePath !== undefined)
|
|
405
|
+
f.push("--store-path", opts.storePath);
|
|
406
|
+
if (opts.home !== undefined)
|
|
407
|
+
f.push("--home", opts.home);
|
|
408
|
+
if (opts.tmuxCommand !== undefined)
|
|
409
|
+
f.push("--tmux-command", opts.tmuxCommand);
|
|
410
|
+
return f;
|
|
406
411
|
}
|
|
407
412
|
function buildVerbFlags(verb, params) {
|
|
408
413
|
switch (verb) {
|
|
@@ -778,12 +783,6 @@ var catalog_default = [
|
|
|
778
783
|
name: "ErrAlreadyDecided",
|
|
779
784
|
package: "store",
|
|
780
785
|
description: ""
|
|
781
|
-
},
|
|
782
|
-
{
|
|
783
|
-
name: "ErrUnknownHandle",
|
|
784
|
-
package: "cabi",
|
|
785
|
-
description: "",
|
|
786
|
-
scope: "cabi"
|
|
787
786
|
}
|
|
788
787
|
];
|
|
789
788
|
|
|
@@ -811,18 +810,75 @@ function throwFromEnvelope(verb, envelope) {
|
|
|
811
810
|
}
|
|
812
811
|
throw new ErrUnknownErrorName(errName, envelope);
|
|
813
812
|
}
|
|
813
|
+
// package.json
|
|
814
|
+
var package_default = {
|
|
815
|
+
name: "agent-director",
|
|
816
|
+
version: "0.5.3",
|
|
817
|
+
type: "module",
|
|
818
|
+
os: [
|
|
819
|
+
"linux",
|
|
820
|
+
"darwin"
|
|
821
|
+
],
|
|
822
|
+
cpu: [
|
|
823
|
+
"x64",
|
|
824
|
+
"arm64"
|
|
825
|
+
],
|
|
826
|
+
engines: {
|
|
827
|
+
bun: ">=1.0.21"
|
|
828
|
+
},
|
|
829
|
+
files: [
|
|
830
|
+
"dist/**/*.js",
|
|
831
|
+
"dist/**/*.d.ts",
|
|
832
|
+
"!dist/**/*.test.*",
|
|
833
|
+
"README.md",
|
|
834
|
+
"scripts/postinstall.ts",
|
|
835
|
+
"skills/install-agent-director/**"
|
|
836
|
+
],
|
|
837
|
+
exports: {
|
|
838
|
+
".": {
|
|
839
|
+
import: "./dist/index.js",
|
|
840
|
+
types: "./dist/index.d.ts"
|
|
841
|
+
}
|
|
842
|
+
},
|
|
843
|
+
scripts: {
|
|
844
|
+
build: "bun run build.ts",
|
|
845
|
+
lint: "eslint src/ --ext .ts",
|
|
846
|
+
typecheck: "tsc --noEmit --project tsconfig.typecheck.json",
|
|
847
|
+
test: "bun test",
|
|
848
|
+
smoke: "bun test test/smoke/ test/smoke-invariants.test.ts",
|
|
849
|
+
"envelope-diff": "bun test test/envelope-diff.test.ts test/envelope-diff-invariants.test.ts",
|
|
850
|
+
"prepare-platforms": "bun run scripts/prepare-platforms.ts",
|
|
851
|
+
"stage-skill": "bun run scripts/stage-skill.ts",
|
|
852
|
+
prepack: "bun run build && bun run scripts/stage-skill.ts",
|
|
853
|
+
postinstall: "bun run scripts/postinstall.ts",
|
|
854
|
+
"version-bump-publish": "bun run scripts/version-bump.ts",
|
|
855
|
+
prepublishOnly: "bun run scripts/prepublish-guards.ts",
|
|
856
|
+
"verify-installed-pkg": "bun run scripts/verify-installed-pkg.ts"
|
|
857
|
+
},
|
|
858
|
+
optionalDependencies: {
|
|
859
|
+
"@agent-director/linux-x64": "^0.5.3",
|
|
860
|
+
"@agent-director/darwin-arm64": "^0.5.3"
|
|
861
|
+
},
|
|
862
|
+
devDependencies: {
|
|
863
|
+
typescript: ">=5.2.0",
|
|
864
|
+
"bun-types": "latest",
|
|
865
|
+
eslint: "^8.0.0",
|
|
866
|
+
"@typescript-eslint/parser": "^7.0.0",
|
|
867
|
+
"@typescript-eslint/eslint-plugin": "^7.0.0"
|
|
868
|
+
}
|
|
869
|
+
};
|
|
814
870
|
|
|
815
871
|
// src/internal/subprocessClient.ts
|
|
816
872
|
var DEFAULT_CALL_TIMEOUT_MS = 30000;
|
|
817
873
|
var SIGKILL_GRACE_MS = 2000;
|
|
874
|
+
var NPM_PACKAGE_VERSION = package_default.version;
|
|
818
875
|
|
|
819
876
|
class SubprocessClient {
|
|
820
|
-
#
|
|
877
|
+
#cliPathOverride;
|
|
821
878
|
#callTimeoutMs;
|
|
822
879
|
#logger;
|
|
823
880
|
#open;
|
|
824
|
-
#
|
|
825
|
-
#tmuxDir;
|
|
881
|
+
#globalOpts;
|
|
826
882
|
_handle = null;
|
|
827
883
|
#tail;
|
|
828
884
|
constructor(opts) {
|
|
@@ -833,11 +889,20 @@ class SubprocessClient {
|
|
|
833
889
|
this.#callTimeoutMs = rawTimeout;
|
|
834
890
|
this.#logger = opts.logger;
|
|
835
891
|
const opts2 = opts;
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
892
|
+
if (opts2._cliPath !== undefined) {
|
|
893
|
+
this.#cliPathOverride = opts2._cliPath;
|
|
894
|
+
} else {
|
|
895
|
+
resolveCliPath();
|
|
896
|
+
this.#cliPathOverride = undefined;
|
|
897
|
+
}
|
|
898
|
+
const g = {};
|
|
899
|
+
if (opts.storePath !== undefined)
|
|
900
|
+
g.storePath = expandTilde(opts.storePath);
|
|
901
|
+
if (opts.tmuxCommand !== undefined)
|
|
902
|
+
g.tmuxCommand = expandTilde(opts.tmuxCommand);
|
|
903
|
+
if (opts.home !== undefined)
|
|
904
|
+
g.home = expandTilde(opts.home);
|
|
905
|
+
this.#globalOpts = g;
|
|
841
906
|
this.#open = true;
|
|
842
907
|
this.#tail = Promise.resolve();
|
|
843
908
|
}
|
|
@@ -872,16 +937,10 @@ class SubprocessClient {
|
|
|
872
937
|
return callPromise;
|
|
873
938
|
}
|
|
874
939
|
async#doCall(verb, params) {
|
|
875
|
-
const
|
|
940
|
+
const cliPath = this.#cliPathOverride ?? resolveCliPath();
|
|
941
|
+
const argv = buildArgv(cliPath, verb, params, this.#globalOpts);
|
|
876
942
|
const startMs = Date.now();
|
|
877
943
|
const spawnEnv = { ...process.env };
|
|
878
|
-
if (this.#homeOverride !== null) {
|
|
879
|
-
spawnEnv["HOME"] = this.#homeOverride;
|
|
880
|
-
}
|
|
881
|
-
if (this.#tmuxDir !== null) {
|
|
882
|
-
const priorPath = spawnEnv["PATH"] ?? "";
|
|
883
|
-
spawnEnv["PATH"] = priorPath ? `${this.#tmuxDir}:${priorPath}` : this.#tmuxDir;
|
|
884
|
-
}
|
|
885
944
|
const proc = Bun.spawn({
|
|
886
945
|
cmd: argv,
|
|
887
946
|
stdin: "pipe",
|
|
@@ -1012,13 +1071,13 @@ class SubprocessClient {
|
|
|
1012
1071
|
}
|
|
1013
1072
|
async version(params) {
|
|
1014
1073
|
this.#assertOpen();
|
|
1015
|
-
|
|
1074
|
+
const cliResp = await this.#enqueue("version", params);
|
|
1075
|
+
return { ...cliResp, version: NPM_PACKAGE_VERSION };
|
|
1016
1076
|
}
|
|
1017
1077
|
}
|
|
1018
1078
|
export {
|
|
1019
1079
|
errorFromEnvelope,
|
|
1020
1080
|
ErrUnsupportedPlatform,
|
|
1021
|
-
ErrUnknownHandle,
|
|
1022
1081
|
ErrUnknownErrorName,
|
|
1023
1082
|
ErrTmuxSessionNameTooLong,
|
|
1024
1083
|
ErrTmuxSessionNameInvalid,
|
package/dist/internal/argv.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* argv.ts — verb-driven argv builder for the subprocess Client.
|
|
3
3
|
*
|
|
4
|
-
* Exports a single pure function `buildArgv(cliPath, verb, params)`
|
|
5
|
-
* converts typed verb parameters into a complete CLI argv array:
|
|
4
|
+
* Exports a single pure function `buildArgv(cliPath, verb, params, globalOpts?)`
|
|
5
|
+
* that converts typed verb parameters into a complete CLI argv array:
|
|
6
6
|
*
|
|
7
|
-
* [cliPath, verbName, ...
|
|
7
|
+
* [cliPath, ...globalFlags, verbName, ...verbFlags]
|
|
8
8
|
*
|
|
9
9
|
* Rules:
|
|
10
10
|
* - Long-flag form only (e.g. --cwd, --claude-instance-id).
|
|
@@ -14,19 +14,48 @@
|
|
|
14
14
|
* - Optional fields are omitted when undefined / falsy.
|
|
15
15
|
* - Boolean flags (--no-pre-trust, --ansi, --overwrite) are only appended
|
|
16
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.
|
|
17
20
|
*
|
|
18
21
|
* Implements SRD SR-1.2 (argv construction is verb-driven and shell-free).
|
|
19
22
|
*
|
|
20
23
|
* Internal — NOT re-exported from src/index.ts.
|
|
21
24
|
*/
|
|
22
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
|
+
}
|
|
23
42
|
/**
|
|
24
43
|
* buildArgv converts a CLI binary path, verb name, and typed parameters into
|
|
25
|
-
* a complete CLI argv array:
|
|
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.
|
|
26
51
|
*
|
|
27
|
-
* @param cliPath
|
|
28
|
-
* @param verb
|
|
29
|
-
* @param params
|
|
30
|
-
* @
|
|
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.
|
|
31
60
|
*/
|
|
32
|
-
export declare function buildArgv(cliPath: string, verb: VerbName, params: unknown): string[];
|
|
61
|
+
export declare function buildArgv(cliPath: string, verb: VerbName, params: unknown, globalOpts?: GlobalArgvOptions): string[];
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* errorMap.ts — catalog-driven static error map for the subprocess Client.
|
|
3
3
|
*
|
|
4
4
|
* Builds a `Map<string, ErrConstructor>` at module load time by iterating
|
|
5
|
-
* `pkg/api/errnames/catalog.json` (
|
|
5
|
+
* `pkg/api/errnames/catalog.json` (33 entries as of 2026-05-25). The map
|
|
6
6
|
* keys are the canonical `err_name` strings (e.g. "ErrSpawnNotFound");
|
|
7
7
|
* values are the typed constructors already exported from `src/errors.ts`.
|
|
8
8
|
*
|
|
@@ -96,6 +96,6 @@ export declare class SubprocessClient {
|
|
|
96
96
|
list(params: ListParams): Promise<ListResult>;
|
|
97
97
|
/** pause — politely shut down a waiting Spawn. */
|
|
98
98
|
pause(params: PauseParams): Promise<PauseResult>;
|
|
99
|
-
/** version — return the
|
|
99
|
+
/** version — return the npm package version (b.6o1) plus the CLI's commit SHA. */
|
|
100
100
|
version(params: VersionParams): Promise<VersionResult>;
|
|
101
101
|
}
|
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,21 +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
|
|
21
23
|
* leading `~`.
|
|
22
24
|
*/
|
|
23
25
|
export interface ClientOptions {
|
|
24
|
-
/**
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
+
*/
|
|
29
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;
|
|
30
56
|
/**
|
|
31
57
|
* When `true`, create the store and initialize the database schema if the
|
|
32
58
|
* store file does not yet exist. When `false` (the default), opening a
|
|
@@ -88,7 +114,7 @@ export interface ListRow {
|
|
|
88
114
|
/** Set when state moves to ended (omitted while live). */
|
|
89
115
|
ended_at?: string | null;
|
|
90
116
|
}
|
|
91
|
-
/** Mirrors pkg/
|
|
117
|
+
/** Mirrors pkg/api.SpawnParams (json tags) — alias of internal/spawn.SpawnParams. */
|
|
92
118
|
export interface SpawnParams {
|
|
93
119
|
/** Absolute (or ~/-prefixed) path the Spawn's Claude starts in. Required. */
|
|
94
120
|
cwd: string;
|
|
@@ -120,7 +146,7 @@ export interface SpawnResult {
|
|
|
120
146
|
/** The id the new Spawn is tracked under. */
|
|
121
147
|
claude_instance_id: string;
|
|
122
148
|
}
|
|
123
|
-
/** Mirrors pkg/
|
|
149
|
+
/** Mirrors the `status` CLI verb's --claude-instance-id flag (pkg/api.Client.Status arg). */
|
|
124
150
|
export interface StatusParams {
|
|
125
151
|
/** Id of the Spawn to inspect. */
|
|
126
152
|
claude_instance_id: string;
|
|
@@ -130,7 +156,7 @@ export interface StatusResult {
|
|
|
130
156
|
/** Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing). */
|
|
131
157
|
state: string;
|
|
132
158
|
}
|
|
133
|
-
/** Mirrors pkg/
|
|
159
|
+
/** Mirrors the `get` CLI verb's --claude-instance-id flag (pkg/api.Client.Get arg). */
|
|
134
160
|
export interface GetParams {
|
|
135
161
|
/** Id of the Spawn to fetch. */
|
|
136
162
|
claude_instance_id: string;
|
|
@@ -156,7 +182,7 @@ export interface GetResult {
|
|
|
156
182
|
/** Open permission request; present only when state=check_permission with an undecided row. */
|
|
157
183
|
permission_request?: PermissionRequestInfo | null;
|
|
158
184
|
}
|
|
159
|
-
/** Mirrors pkg/
|
|
185
|
+
/** Mirrors pkg/api.SendKeysParams (json tags). */
|
|
160
186
|
export interface SendKeysParams {
|
|
161
187
|
/** Id of the Spawn whose pane will receive the text. */
|
|
162
188
|
claude_instance_id: string;
|
|
@@ -166,7 +192,7 @@ export interface SendKeysParams {
|
|
|
166
192
|
/** Mirrors pkg/api/sendkeys.go::SendKeysResult (empty; reserved for future fields). */
|
|
167
193
|
export interface SendKeysResult {
|
|
168
194
|
}
|
|
169
|
-
/** Mirrors pkg/
|
|
195
|
+
/** Mirrors pkg/api.ReadPaneParams (json tags). */
|
|
170
196
|
export interface ReadPaneParams {
|
|
171
197
|
/** Id of the Spawn whose pane will be captured. */
|
|
172
198
|
claude_instance_id: string;
|
|
@@ -180,7 +206,7 @@ export interface ReadPaneResult {
|
|
|
180
206
|
/** Captured pane text. */
|
|
181
207
|
pane: string;
|
|
182
208
|
}
|
|
183
|
-
/** Mirrors pkg/
|
|
209
|
+
/** Mirrors pkg/api.KillParams (json tags). */
|
|
184
210
|
export interface KillParams {
|
|
185
211
|
/** Id of the Spawn to kill. */
|
|
186
212
|
claude_instance_id: string;
|
|
@@ -188,7 +214,7 @@ export interface KillParams {
|
|
|
188
214
|
/** Mirrors pkg/api/kill.go::KillResult (empty; reserved for future fields). */
|
|
189
215
|
export interface KillResult {
|
|
190
216
|
}
|
|
191
|
-
/** Mirrors pkg/
|
|
217
|
+
/** Mirrors pkg/api.DecideParams (json tags). */
|
|
192
218
|
export interface DecideParams {
|
|
193
219
|
/** Id of the Spawn whose open permission request is being decided. */
|
|
194
220
|
claude_instance_id: string;
|
|
@@ -200,7 +226,7 @@ export interface DecideParams {
|
|
|
200
226
|
/** Mirrors pkg/api/decide.go::DecideResult (empty; reserved for future fields). */
|
|
201
227
|
export interface DecideResult {
|
|
202
228
|
}
|
|
203
|
-
/** Mirrors pkg/
|
|
229
|
+
/** Mirrors pkg/api.ResumeParams (json tags). */
|
|
204
230
|
export interface ResumeParams {
|
|
205
231
|
/** Id of the terminated Spawn to resurrect. */
|
|
206
232
|
claude_instance_id: string;
|
|
@@ -210,7 +236,7 @@ export interface ResumeResult {
|
|
|
210
236
|
/** Same id that was passed in (preserved across resurrection). */
|
|
211
237
|
claude_instance_id: string;
|
|
212
238
|
}
|
|
213
|
-
/** Mirrors pkg/
|
|
239
|
+
/** Mirrors the `find-missing` CLI verb's --timeout flag (pkg/api.Client.FindMissing ctx deadline). */
|
|
214
240
|
export interface FindMissingParams {
|
|
215
241
|
/** Optional deadline for the OS probe sweep (milliseconds). 0/omitted = no deadline. */
|
|
216
242
|
timeout_ms?: number;
|
|
@@ -222,7 +248,7 @@ export interface FindMissingResult {
|
|
|
222
248
|
/** Sorted ids of rows transitioned to missing. */
|
|
223
249
|
ids: string[];
|
|
224
250
|
}
|
|
225
|
-
/** Mirrors pkg/
|
|
251
|
+
/** Mirrors the `expire` CLI verb's --older-than flag (pkg/api.Client.Expire arg). */
|
|
226
252
|
export interface ExpireParams {
|
|
227
253
|
/**
|
|
228
254
|
* Duration override (e.g. "7d", "2h", "0d"). When omitted, the config
|
|
@@ -237,7 +263,7 @@ export interface ExpireResult {
|
|
|
237
263
|
/** Sorted ids of rows removed. */
|
|
238
264
|
ids: string[];
|
|
239
265
|
}
|
|
240
|
-
/** Mirrors pkg/
|
|
266
|
+
/** Mirrors the `delete` CLI verb's --claude-instance-id flag(s) (pkg/api.Client.Delete arg). */
|
|
241
267
|
export interface DeleteParams {
|
|
242
268
|
/** Id(s) to delete. */
|
|
243
269
|
claude_instance_id: string[];
|
|
@@ -247,7 +273,7 @@ export interface DeleteResult {
|
|
|
247
273
|
/** Per-id outcome: "ok" on success, err_name on failure. */
|
|
248
274
|
results: Record<string, string>;
|
|
249
275
|
}
|
|
250
|
-
/** Mirrors pkg/
|
|
276
|
+
/** Mirrors pkg/api.MakeTemplateParams (json tags). */
|
|
251
277
|
export interface MakeTemplateParams {
|
|
252
278
|
/** Template filename (without extension). Must be filename-safe. Required. */
|
|
253
279
|
name: string;
|
|
@@ -279,7 +305,7 @@ export interface MakeTemplateResult {
|
|
|
279
305
|
/** Absolute path of the written template TOML file. */
|
|
280
306
|
path: string;
|
|
281
307
|
}
|
|
282
|
-
/** Mirrors pkg/
|
|
308
|
+
/** Mirrors pkg/api.ListParams (json tags). */
|
|
283
309
|
export interface ListParams {
|
|
284
310
|
/** Filter by state (multiple values OR together). */
|
|
285
311
|
state?: string[];
|
|
@@ -299,7 +325,7 @@ export interface ListResult {
|
|
|
299
325
|
/** Matching Spawn rows. Empty array when none match. */
|
|
300
326
|
spawns: ListRow[];
|
|
301
327
|
}
|
|
302
|
-
/** Mirrors pkg/
|
|
328
|
+
/** Mirrors pkg/api.PauseParams (json tags). */
|
|
303
329
|
export interface PauseParams {
|
|
304
330
|
/** Id of the Spawn to pause gracefully. */
|
|
305
331
|
claude_instance_id: string;
|
|
@@ -307,13 +333,13 @@ export interface PauseParams {
|
|
|
307
333
|
/** Mirrors pkg/api/pause.go::PauseResult (empty; reserved for future fields). */
|
|
308
334
|
export interface PauseResult {
|
|
309
335
|
}
|
|
310
|
-
/** Mirrors
|
|
336
|
+
/** Mirrors the `version` CLI verb (no user params; pkg/api.Client.Version takes none). */
|
|
311
337
|
export interface VersionParams {
|
|
312
338
|
}
|
|
313
339
|
/** Mirrors pkg/api/version.go::VersionResult */
|
|
314
340
|
export interface VersionResult {
|
|
315
|
-
/**
|
|
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. */
|
|
316
342
|
version: string;
|
|
317
|
-
/**
|
|
343
|
+
/** CLI binary's full git SHA. "unknown" for unstamped builds. */
|
|
318
344
|
commit: string;
|
|
319
345
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-director",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"os": [
|
|
6
6
|
"linux",
|
|
@@ -43,8 +43,8 @@
|
|
|
43
43
|
"verify-installed-pkg": "bun run scripts/verify-installed-pkg.ts"
|
|
44
44
|
},
|
|
45
45
|
"optionalDependencies": {
|
|
46
|
-
"@agent-director/linux-x64": "^0.5.
|
|
47
|
-
"@agent-director/darwin-arm64": "^0.5.
|
|
46
|
+
"@agent-director/linux-x64": "^0.5.3",
|
|
47
|
+
"@agent-director/darwin-arm64": "^0.5.3"
|
|
48
48
|
},
|
|
49
49
|
"devDependencies": {
|
|
50
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.5.
|
|
4
|
+
version: 0.5.3
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
## When to invoke
|