agent-director 0.4.0 → 0.4.2

package/README.md

@@ -10,6 +10,68 @@ bun add agent-director
 
 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`.
 
+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.
+
+Bun blocks dependency postinstalls by default. Trust this package so the skill copy can run:
+
+```sh
+bun pm trust agent-director
+```
+
+Or pre-declare it in your `package.json` before `bun add`:
+
+```json
+{
+  "trustedDependencies": ["agent-director"]
+}
+```
+
+### Verbose install logs
+
+Set `AD_POSTINSTALL_VERBOSE=1` (also accepts `true` / `yes`, case-insensitive) before `bun add` to see what the postinstall resolved and decided. The default is quiet — five lines maximum.
+
+### Skipping the postinstall
+
+`bun add --ignore-scripts agent-director` installs the library without running the postinstall. The skill is not copied. To get skill discoverability after the fact, either:
+
+```sh
+cp -r node_modules/agent-director/skills/install-agent-director ~/.claude/skills/
+```
+
+or, once the library is on disk, invoke `claude /install-agent-director` from any Claude Code session — the install skill copies itself into `~/.claude/skills/` as a side effect of running.
+
+### How the postinstall decides whether to overwrite
+
+The skill body carries a `version:` field in its YAML frontmatter. On every install the postinstall reads the bundled version and the version already on disk:
+
+- **Same version** — no filesystem changes, no output.
+- **Older or missing on disk** — overwrite, leaving a timestamped `install-agent-director.bak.<unix-ts>` sibling under `~/.claude/skills/`.
+- **Newer on disk** — leave it alone, single-line warning to stderr.
+
+The authoritative behavior contract lives in Idea Bee `b.fg3`.
+
+## Supported platforms
+
+**Supported** — install + library + skill all work:
+
+- `linux/x64` (Linux on x86_64)
+- `darwin/arm64` (Apple Silicon Mac)
+
+**Refused at install time by npm/bun** — the umbrella's `os`/`cpu` fields fail resolution and no postinstall runs:
+
+- Windows (any architecture)
+- FreeBSD, OpenBSD, and other non-Linux/non-Darwin OSes
+- any architecture not in `[x64, arm64]` (e.g. `ia32`, `mips`, `arm`)
+
+**Refused by the postinstall after npm/bun admits the install** — the umbrella runs but the postinstall exits non-zero with an `agent-director: unsupported host` message before any filesystem write:
+
+- `darwin/x64` (Intel Mac)
+- `linux/arm64`
+
+The refusal is two-layered because npm/bun's `os` and `cpu` fields are a cross-product, not a per-pair set: the coarse gate cannot distinguish "supported pair" from "supported OS plus supported arch in any combination." The postinstall's host-pair check catches the two cross-product members that should not actually install.
+
+See Idea Bee `b.fg3` for cross-platform expansion status.
+
 ## Quick start
 
 `using` block (preferred):

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+import type { ClientOptions } from "./types.js";
+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";
+export { AgentDirectorError, ErrClientClosed } from "./errors.js";
+export type { ClientOptions } from "./types.js";
+/**
+ * Client — the public entry point for agent-director.
+ *
+ * Construction is synchronous: the constructor calls `ad_open` over Bun FFI,
+ * receives an opaque handle, and stores it. Every subsequent verb call will
+ * carry this handle across the FFI boundary.
+ *
+ * Lifecycle:
+ *   1. `new Client(opts)` → calls ad_open; throws on error envelope.
+ *   2. `client.close()` → calls ad_close; idempotent, never throws.
+ *   3. `[Symbol.dispose]()` → delegates to close() for `using` blocks.
+ *   4. Any verb method calls `_assertOpen()` first; post-close calls throw
+ *      ErrClientClosed.
+ *
+ * Tilde expansion (`~` → home directory) is applied to `storePath` and
+ * `configPath` TS-side before the paths cross the FFI boundary. The C-ABI
+ * never receives a leading `~`.
+ */
+export declare class Client {
+    /** Opaque handle returned by ad_open. Nulled after close(). */
+    private _handle;
+    /** Whether this client is still open and usable. */
+    private _open;
+    /** Optional logger for non-fatal warnings (e.g. ad_close error envelopes). */
+    private _logger;
+    constructor(opts: ClientOptions);
+    /**
+     * _assertOpen throws ErrClientClosed if the client has been closed.
+     * Called at the top of every verb method. May also be invoked from tests
+     * via `(client as any)._assertOpen()` — TS private fields are erased at
+     * runtime, so the cast works.
+     */
+    private _assertOpen;
+    /**
+     * close releases the ad_open handle via ad_close.
+     *
+     * - Idempotent: a second call is a no-op.
+     * - Never throws: if ad_close returns an error envelope, the error is
+     *   logged via the optional logger (warn level) but the handle is still
+     *   nulled and _open set to false.
+     */
+    close(): void;
+    /**
+     * [Symbol.dispose] enables `using` block syntax (Explicit Resource Management).
+     *
+     *   {
+     *     using client = new Client(opts);
+     *     // ... client.someVerb() ...
+     *   } // client.close() called automatically here
+     */
+    [Symbol.dispose](): void;
+    /** spawn — launch a tracked Claude Code instance in a new tmux session. */
+    spawn(params: SpawnParams): Promise<SpawnResult>;
+    /** status — get the current state of a Spawn. */
+    status(params: StatusParams): Promise<StatusResult>;
+    /** get — fetch the full Spawn record. */
+    get(params: GetParams): Promise<GetResult>;
+    /** sendKeys — send keystrokes to a Spawn's tmux pane. */
+    sendKeys(params: SendKeysParams): Promise<SendKeysResult>;
+    /** readPane — read the current contents of a Spawn's tmux pane. */
+    readPane(params: ReadPaneParams): Promise<ReadPaneResult>;
+    /** kill — terminate a Spawn's tmux session. */
+    kill(params: KillParams): Promise<KillResult>;
+    /** decide — resolve a pending permission request. */
+    decide(params: DecideParams): Promise<DecideResult>;
+    /** resume — restart a terminated Spawn via `claude --resume`. */
+    resume(params: ResumeParams): Promise<ResumeResult>;
+    /** findMissing — reconcile Spawns whose tmux sessions have disappeared. */
+    findMissing(params: FindMissingParams): Promise<FindMissingResult>;
+    /** expire — remove terminal-state rows older than the retention window. */
+    expire(params: ExpireParams): Promise<ExpireResult>;
+    /** delete — hard-delete Spawn rows by id. */
+    delete(params: DeleteParams): Promise<DeleteResult>;
+    /** makeTemplate — save a reusable spawn preset. */
+    makeTemplate(params: MakeTemplateParams): Promise<MakeTemplateResult>;
+    /** list — query Spawns with optional filter params. */
+    list(params: ListParams): Promise<ListResult>;
+    /** pause — politely shut down a waiting Spawn. */
+    pause(params: PauseParams): Promise<PauseResult>;
+    /**
+     * version — return the binary's build-time version stamp.
+     *
+     * This is the only handle-free verb: it passes null instead of the Client
+     * handle because the C-ABI ignores any handle field for ad_version.
+     */
+    version(params: VersionParams): Promise<VersionResult>;
+    /**
+     * _assertOpenForTests exposes _assertOpen to test code without forcing
+     * public visibility. TypeScript `private` is erased at runtime, but this
+     * alias makes the intent explicit and avoids the `(client as any)` cast.
+     *
+     * @internal Tests only — do not call from application code.
+     */
+    _assertOpenForTests(): void;
+}

package/dist/errors.d.ts

@@ -0,0 +1,173 @@
+export { TS_ONLY_ERROR_NAMES } from "./internal/tsOnlyErrors.js";
+/**
+ * AgentDirectorError — base class for all typed errors surfaced by this
+ * client library.
+ *
+ * `verb` names the callable verb that triggered the error (e.g. "spawn").
+ * `errName` is the canonical error name from the Go errnames catalog.
+ * `errDescription` is the human-readable description from the C-ABI envelope.
+ * `message` is formatted as "${errName}: ${errDescription}".
+ */
+export declare class AgentDirectorError extends Error {
+    /** Verb that triggered this error (e.g. "spawn", "status"). Empty for lifecycle ops. */
+    readonly verb: string;
+    /** Canonical error name, matching the Go errnames catalog (e.g. "ErrSpawnNotFound"). */
+    readonly errName: string;
+    /** Human-readable description forwarded from the C-ABI envelope. */
+    readonly errDescription: string;
+    constructor(verb: string, err_name: string, err_description: string);
+}
+/**
+ * ErrClientClosed — thrown when a verb method (or _assertOpen) is called on a
+ * Client that has already been closed.
+ *
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES` so the
+ * catalog-drift test never flags it as an unexpected class.
+ */
+export declare class ErrClientClosed extends AgentDirectorError {
+    constructor();
+}
+/**
+ * ErrUnsupportedPlatform — thrown when `process.platform` + `process.arch`
+ * produce a tuple that has no corresponding native sub-package.
+ *
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
+ */
+export declare class ErrUnsupportedPlatform extends AgentDirectorError {
+    constructor(tuple: string);
+}
+/**
+ * ErrPlatformPackageMissing — thrown when the optional npm sub-package for
+ * the current platform is not installed, or when its native binary file is
+ * absent from the installed package directory.
+ *
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
+ */
+export declare class ErrPlatformPackageMissing extends AgentDirectorError {
+    constructor(pkgName: string, detail?: string);
+}
+/**
+ * ErrBunVersionTooOld — thrown when Bun.version is below the declared minimum.
+ *
+ * TS-ONLY ERROR — no counterpart in pkg/api/errnames/catalog.json.
+ * Listed in `src/internal/tsOnlyErrors.ts::TS_ONLY_ERROR_NAMES`.
+ */
+export declare class ErrBunVersionTooOld extends AgentDirectorError {
+    constructor(actual: string, minimum: string);
+}
+/** Mirrors ErrCwdMissing (package: spawn) */
+export declare class ErrCwdMissing extends AgentDirectorError {
+}
+/** Mirrors ErrCwdNotAPath (package: spawn) */
+export declare class ErrCwdNotAPath extends AgentDirectorError {
+}
+/** Mirrors ErrCwdNotFound (package: spawn) */
+export declare class ErrCwdNotFound extends AgentDirectorError {
+}
+/** Mirrors ErrCwdNotADirectory (package: spawn) */
+export declare class ErrCwdNotADirectory extends AgentDirectorError {
+}
+/** Mirrors ErrRelayModeInvalid (package: spawn) */
+export declare class ErrRelayModeInvalid extends AgentDirectorError {
+}
+/** Mirrors ErrSpawnDeniedFlag (package: spawn) */
+export declare class ErrSpawnDeniedFlag extends AgentDirectorError {
+}
+/** Mirrors ErrReservedEnvKey (package: spawn) */
+export declare class ErrReservedEnvKey extends AgentDirectorError {
+}
+/** Mirrors ErrInstanceIdCollision (package: spawn) */
+export declare class ErrInstanceIdCollision extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxSessionNameEmpty (package: spawn) */
+export declare class ErrTmuxSessionNameEmpty extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxSessionNameInvalid (package: spawn) */
+export declare class ErrTmuxSessionNameInvalid extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxSessionNameTooLong (package: spawn) */
+export declare class ErrTmuxSessionNameTooLong extends AgentDirectorError {
+}
+/** Mirrors ErrSpawnNotFound (package: store) */
+export declare class ErrSpawnNotFound extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxNotAvailable (package: tmux) */
+export declare class ErrTmuxNotAvailable extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxSessionCreate (package: tmux) */
+export declare class ErrTmuxSessionCreate extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxSendKeys (package: tmux) */
+export declare class ErrTmuxSendKeys extends AgentDirectorError {
+}
+/** Mirrors ErrTmuxCaptureFailed (package: tmux) */
+export declare class ErrTmuxCaptureFailed extends AgentDirectorError {
+}
+/** Mirrors ErrSpawnNotInteractive (package: api) */
+export declare class ErrSpawnNotInteractive extends AgentDirectorError {
+}
+/** Mirrors ErrSendKeysWhileRelayed (package: api) */
+export declare class ErrSendKeysWhileRelayed extends AgentDirectorError {
+}
+/** Mirrors ErrSpawnNotPausable (package: api) */
+export declare class ErrSpawnNotPausable extends AgentDirectorError {
+}
+/** Mirrors ErrPauseTimeout (package: api) */
+export declare class ErrPauseTimeout extends AgentDirectorError {
+}
+/** Mirrors ErrListInvalidLabel (package: api) */
+export declare class ErrListInvalidLabel extends AgentDirectorError {
+}
+/** Mirrors ErrTemplateNameUnsafe (package: config) */
+export declare class ErrTemplateNameUnsafe extends AgentDirectorError {
+}
+/** Mirrors ErrTemplateNotFound (package: config) */
+export declare class ErrTemplateNotFound extends AgentDirectorError {
+}
+/** Mirrors ErrTemplateMalformed (package: config) */
+export declare class ErrTemplateMalformed extends AgentDirectorError {
+}
+/** Mirrors ErrTemplateExists (package: config) */
+export declare class ErrTemplateExists extends AgentDirectorError {
+}
+/** Mirrors ErrProbeUnsupported (package: probe) */
+export declare class ErrProbeUnsupported extends AgentDirectorError {
+}
+/** Mirrors ErrSpawnNotResumable (package: api) */
+export declare class ErrSpawnNotResumable extends AgentDirectorError {
+}
+/** Mirrors ErrNoSessionId (package: api) */
+export declare class ErrNoSessionId extends AgentDirectorError {
+}
+/** Mirrors ErrJsonlMissing (package: api) */
+export declare class ErrJsonlMissing extends AgentDirectorError {
+}
+/** Mirrors ErrRelayModeOff (package: api) */
+export declare class ErrRelayModeOff extends AgentDirectorError {
+}
+/** Mirrors ErrInvalidDecision (package: api) */
+export declare class ErrInvalidDecision extends AgentDirectorError {
+}
+/** Mirrors ErrNoOpenPermissionRequest (package: store) */
+export declare class ErrNoOpenPermissionRequest extends AgentDirectorError {
+}
+/** Mirrors ErrAlreadyDecided (package: store) */
+export declare class ErrAlreadyDecided extends AgentDirectorError {
+}
+/** Mirrors ErrUnknownHandle (package: cabi, scope: cabi) */
+export declare class ErrUnknownHandle extends AgentDirectorError {
+}
+/**
+ * errorFromEnvelope creates a typed AgentDirectorError subclass from the
+ * C-ABI error envelope fields.
+ *
+ * @param verb            The verb name that produced the error (e.g. "spawn").
+ * @param err_name        The canonical error name from the envelope.
+ * @param err_description The human-readable description from the envelope.
+ * @returns A typed subclass when err_name matches the catalog; a plain
+ *          AgentDirectorError (with a console.warn) for unknown names.
+ */
+export declare function errorFromEnvelope(verb: string, err_name: string, err_description: string): AgentDirectorError;

package/dist/ffi.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ffi.ts — public facade for the C-ABI call recipe.
+ *
+ * The six-step FFI recipe is split across three files:
+ *
+ *   src/internal/worker.ts      — steps 1–4 (runs inside the worker thread)
+ *     1. Encode params as null-terminated UTF-8 JSON
+ *     2. Call the C symbol via Bun dlopen
+ *     3. Copy the returned CString to a JS string
+ *     4. Free the C pointer via ad_free_cstring (try/finally — error path frees too)
+ *
+ *   src/internal/workerProxy.ts — steps 5–6 (main thread, post-worker)
+ *     5. Parse the raw JSON string
+ *     6. If err_name present → throw typed error via errorFromEnvelope;
+ *        else → return parsed result
+ *
+ *   src/ffi.ts (this file)      — thin public facade
+ *     Exposes callVerb<P, R> that routes to workerProxy.dispatch and casts.
+ *
+ * WHY a worker?
+ * Bun FFI has no per-symbol `async: true` marker. Without the worker, every
+ * C call would block the JS event loop. The worker runs in a separate thread
+ * so verb calls are off-main-thread and the event loop stays responsive.
+ * See src/internal/workerProxy.ts for the singleton design rationale.
+ *
+ * Internal — NOT re-exported from src/index.ts.
+ */
+export { VERBS, KEBAB_TO_CAMEL } from "./internal/verbs.js";
+export type { VerbName } from "./internal/verbs.js";
+export { BINDING_SYMBOL_NAMES } from "./internal/bindingSpec.js";
+export { shutdown as shutdownWorker } from "./internal/workerProxy.js";
+/**
+ * callVerb dispatches a verb call through the dedicated worker thread and
+ * returns a Promise that resolves with the typed result R or rejects with a
+ * typed AgentDirectorError.
+ *
+ * @param verb    Kebab-case verb name (e.g. "send-keys", "make-template")
+ * @param handle  Opaque Client handle from ad_open, or null for handle-free
+ *                verbs (currently only "version")
+ * @param params  Verb-specific params object; JSON-serialized inside dispatch
+ */
+export declare function callVerb<P, R>(verb: string, handle: string | null, params: P): Promise<R>;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public entry point for agent-director.
+ *
+ * ffi.ts and platform.ts are internal — they are NOT re-exported here.
+ */
+export { Client } from "./client.js";
+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";
+export type { ClientOptions, Logger } from "./types.js";
+export type { VerbSummary, PermissionRequestInfo, ListRow } from "./types.js";
+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";