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 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` 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.
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({ storePath: "~/.agent-director/state.db" });
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({ storePath: "~/.agent-director/state.db" });
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
- `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"]`).
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 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
  }
@@ -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
- * C-ABI error envelope fields.
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, 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";
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
- #cliPath;
877
+ #cliPathOverride;
821
878
  #callTimeoutMs;
822
879
  #logger;
823
880
  #open;
824
- #homeOverride;
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
- this.#cliPath = opts2._cliPath ?? resolveCliPath();
837
- const expandedStore = expandTilde(opts.storePath);
838
- const storeParent = dirname2(expandedStore);
839
- this.#homeOverride = basename(storeParent) === ".agent-director" ? dirname2(storeParent) : null;
840
- this.#tmuxDir = opts.tmuxCommand ? dirname2(expandTilde(opts.tmuxCommand)) : null;
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 argv = buildArgv(this.#cliPath, verb, params);
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
- return this.#enqueue("version", params);
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,
@@ -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)` that
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, ...flags]
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: [cliPath, verbName, ...flags].
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 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.
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` (34 entries as of 2026-05-24). The map
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 binary's build-time version stamp. */
99
+ /** version — return the npm package version (b.6o1) plus the CLI's commit SHA. */
100
100
  version(params: VersionParams): Promise<VersionResult>;
101
101
  }
@@ -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 even though earlier epic-spec drafts assumed
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
- * `storePath` is the only required field. The others are optional overrides;
16
- * absent fields fall back to the same three-tier defaults as `pkg/api.Options`
17
- * (config-file value, then hardcoded fallback).
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
- /** Path to the SQLite store file. Tilde-expanded before being forwarded. */
25
- storePath: string;
26
- /** Path to the TOML config file. Tilde-expanded before being forwarded. */
27
- configPath?: string;
28
- /** Override the tmux binary. Defaults to the binary on PATH. */
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/cabi/verbs_read.go::ad_spawn params */
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/cabi/verbs_read.go::ad_status params */
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/cabi/verbs_read.go::ad_get params */
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/cabi/verbs_read.go::ad_send_keys params (pkg/api.SendKeysParams json tags) */
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/cabi/verbs_read.go::ad_read_pane params (pkg/api.ReadPaneParams json tags) */
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/cabi/verbs_control.go::ad_kill params (pkg/api.KillParams json tags) */
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/cabi/verbs_control.go::ad_decide params (pkg/api.DecideParams json tags) */
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/cabi/verbs_control.go::ad_resume params (pkg/api.ResumeParams json tags) */
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/cabi/verbs_control.go::ad_find_missing params */
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/cabi/verbs_admin.go::ad_expire params */
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/cabi/verbs_admin.go::ad_delete params */
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/cabi/verbs_admin.go::ad_make_template params */
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/cabi/verbs_read.go::ad_list params */
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/cabi/verbs_control.go::ad_pause params (pkg/api.PauseParams json tags) */
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 pkg/cabi/verbs_admin.go::ad_version params (handle-free; no user params). */
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
- /** Human-readable version stamp. "dev" for unstamped builds. */
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
- /** Full git SHA. "unknown" for unstamped builds. */
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.0",
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.0",
47
- "@agent-director/darwin-arm64": "^0.5.0"
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.0
4
+ version: 0.5.3
5
5
  ---
6
6
 
7
7
  ## When to invoke