agent-director 0.4.0 → 0.4.2

package/dist/internal/tilde.d.ts

@@ -0,0 +1,16 @@
+/**
+ * expandTilde resolves a leading `~` or `~/` to the user's home directory.
+ *
+ * Resolution order:
+ *   1. `process.env.HOME` if set and non-empty.
+ *   2. `os.homedir()` from node:os as fallback.
+ *
+ * Behaviour by input:
+ *   - `""` → `""`  (empty string unchanged)
+ *   - `"~"` → `"/home/user"` (bare tilde → home directory)
+ *   - `"~/foo"` → `"/home/user/foo"` (tilde-prefix → home + rest)
+ *   - `"/abs/path"` → `"/abs/path"` (absolute path unchanged)
+ *   - `"relative/path"` → `"relative/path"` (relative path unchanged)
+ *   - `"foo~bar"` → `"foo~bar"` (tilde not at start → unchanged)
+ */
+export declare function expandTilde(p: string): string;

package/dist/internal/tsOnlyErrors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * tsOnlyErrors.ts — centralized allow-list for TS-only AgentDirectorError
+ * subclasses that have no counterpart in pkg/api/errnames/catalog.json.
+ *
+ * The catalog-drift regression test (T10) imports this constant so it never
+ * flags these classes as unexpected. Each name must also have a corresponding
+ * subclass in src/errors.ts with a comment cross-referencing this module.
+ */
+/**
+ * TS_ONLY_ERROR_NAMES lists every AgentDirectorError subclass that is defined
+ * in this package but intentionally absent from the shared Go err_name catalog
+ * at pkg/api/errnames/catalog.json.
+ *
+ * Membership criteria:
+ *  - ErrClientClosed       — client lifecycle error, no Go equivalent.
+ *  - ErrUnsupportedPlatform — platform detection error, raised before any IPC.
+ *  - ErrPlatformPackageMissing — optional sub-package absent; no Go equivalent.
+ *  - ErrBunVersionTooOld   — runtime version guard; no Go equivalent.
+ *
+ * When adding a new TS-only subclass: add its name here AND add a comment in
+ * src/errors.ts near the subclass cross-referencing this allow-list.
+ */
+export declare const TS_ONLY_ERROR_NAMES: readonly ["ErrClientClosed", "ErrUnsupportedPlatform", "ErrPlatformPackageMissing", "ErrBunVersionTooOld"];
+/** Type alias for the individual allow-listed names. */
+export type TsOnlyErrorName = (typeof TS_ONLY_ERROR_NAMES)[number];

package/dist/internal/verbs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Canonical callable verb list — source of truth for all TS/Bun client code
+ * that needs to iterate, type-check, or map verb names.
+ *
+ * This list is hand-authored from `manifest.CallableVerbs()` in
+ * pkg/api/manifest/manifest.go. It includes every verb where `Callable: true`
+ * and excludes the three non-callable verbs (help, serve, hook).
+ *
+ * Currently 15 callable verbs: spawn, status, get, send-keys, read-pane,
+ * kill, decide, resume, find-missing, expire, delete, make-template, list,
+ * pause, version.
+ *
+ * NOTE: `help` has `Callable: false` in manifest.go (source of truth); it is
+ * intentionally excluded here even though earlier epic-spec drafts assumed
+ * otherwise. The .go source wins.
+ */
+/** All callable verbs in their canonical kebab form (matches manifest). */
+export declare const VERBS: readonly ["spawn", "status", "get", "send-keys", "read-pane", "kill", "decide", "resume", "find-missing", "expire", "delete", "make-template", "list", "pause", "version"];
+/** Union type of every callable verb name. */
+export type VerbName = (typeof VERBS)[number];
+/**
+ * kebabToUnderscore converts a kebab-case verb name to the underscore form
+ * used in the C-ABI symbol name.
+ *
+ * Examples:
+ *   "send-keys"     → "send_keys"
+ *   "find-missing"  → "find_missing"
+ *   "make-template" → "make_template"
+ *   "read-pane"     → "read_pane"
+ *   "version"       → "version"
+ */
+export declare function kebabToUnderscore(v: string): string;
+/**
+ * kebabToCamel converts a kebab-case verb name to the camelCase form used
+ * as a method name on the Client class.
+ *
+ * Examples:
+ *   "send-keys"     → "sendKeys"
+ *   "find-missing"  → "findMissing"
+ *   "make-template" → "makeTemplate"
+ *   "read-pane"     → "readPane"
+ *   "version"       → "version"
+ */
+export declare function kebabToCamel(v: string): string;
+/**
+ * KEBAB_TO_CAMEL is a static map from every VerbName to its camelCase form.
+ * Prefer this over calling kebabToCamel() at runtime when the input is always
+ * a VerbName (avoids a string scan in hot code paths).
+ */
+export declare const KEBAB_TO_CAMEL: Record<VerbName, string>;
+/**
+ * HANDLE_FREE_VERBS is the set of verbs that do not require a Client handle.
+ * Currently only "version". Mirrors pkg/cabi/dispatch.go's handleFreeVerbs map.
+ */
+export declare const HANDLE_FREE_VERBS: ReadonlySet<string>;
+/** Returns true if the given verb does not require a Client handle. */
+export declare function isHandleFree(verb: string): boolean;

package/dist/internal/worker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * worker.ts — worker-thread entry-point for all C-ABI FFI calls.
+ *
+ * This module runs INSIDE a node:worker_threads Worker. It is never imported
+ * by the main thread. Its sole job is:
+ *
+ *  1. At startup: resolve the native library path via loadNative(), post {type:"ready"}.
+ *  2. On every message: receive {id, op, handle, paramsJSON}, build the
+ *     single-arg JSON for the C symbol, call it, copy the returned C string
+ *     to JS, free the native pointer (try/finally so the error path also
+ *     frees), and post the raw JSON string back to the main thread.
+ *
+ * WHY a dedicated worker?
+ * ───────────────────────
+ * Bun's dlopen has no per-symbol `async: true` marker. Calling a C function
+ * directly on the main thread blocks the JS event loop for the duration of
+ * that call. By running all FFI in a dedicated worker, verb calls are truly
+ * off-main-thread — the event loop remains responsive during long-running
+ * Go-side operations.
+ *
+ * One worker per process (singleton, not a pool): the Go runtime inside the
+ * shared library carries process-global state (the handle registry). Multiple
+ * parallel dlopen handles would split that state and break audit-trail
+ * invariants. A single serialized worker is the correct model.
+ *
+ * Wire format for C calls
+ * ───────────────────────
+ * Every C-ABI function takes exactly ONE `char* params_json` argument and
+ * returns `char* result_json` (which the caller must release via
+ * ad_free_cstring). The handle field is embedded inside the JSON:
+ *   - ad_open  → paramsJSON (no handle)
+ *   - ad_close → {"handle":"<token>"}
+ *   - ad_<verb> → {"handle":"<token>", ...verb-params}
+ *   - ad_version → {} (handle-free)
+ */
+export {};

package/dist/internal/workerProxy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * workerProxy.ts — main-thread singleton proxy for the FFI worker.
+ *
+ * The six-step C-ABI call recipe splits across two files:
+ *   worker.ts      → steps 1–4: encode JSON → call C symbol → copy CString →
+ *                    free pointer (try/finally)
+ *   workerProxy.ts → steps 5–6: parse raw JSON string → check err_name →
+ *                    throw typed error (via errorFromEnvelope) or return result
+ *
+ * See src/ffi.ts for the public callVerb facade that drives this module.
+ *
+ * Architecture
+ * ────────────
+ * A single dedicated Worker is spawned lazily on the first call to dispatch.
+ * The Worker lives for the lifetime of the process (or until shutdown() is
+ * called). All Client instances in the process share the same worker.
+ *
+ * Correlation IDs
+ * ───────────────
+ * Each dispatch call mints a monotonically increasing id and inserts a
+ * {resolve, reject} pair into `_pending`. The worker echoes the id back in
+ * every response so the correct Promise can be settled.
+ *
+ * Error envelope decoding
+ * ───────────────────────
+ * The worker returns raw JSON strings only. This module parses them and, if
+ * `err_name` is present, calls errorFromEnvelope() so the error-class graph
+ * is loaded once (on the main thread), not inside every worker thread.
+ */
+/**
+ * workerProxy is the mutable singleton used by callVerb (and tests).
+ * Exporting an object (rather than a bare function) allows tests to replace
+ * `workerProxy.dispatch` without module-level mocking:
+ *
+ *   import { workerProxy } from "../src/internal/workerProxy.js";
+ *   workerProxy.dispatch = mock(async () => '{"version":"test"}');
+ */
+export declare const workerProxy: {
+    dispatch: (op: string, handle: string | null, params: unknown) => Promise<unknown>;
+};
+/**
+ * shutdown terminates the worker and rejects all pending dispatches. Call
+ * this in tests (afterAll) to prevent lingering worker threads.
+ */
+export declare function shutdown(): void;

package/dist/platform.d.ts

@@ -0,0 +1,80 @@
+/**
+ * platform — native library resolver for agent-director.
+ *
+ * Implements the five-step resolution sequence:
+ *   1. Check Bun.version against MIN_BUN_VERSION → ErrBunVersionTooOld
+ *   2. Map process.platform + process.arch to an npm sub-package name →
+ *      ErrUnsupportedPlatform for unknown tuples
+ *   3. Locate the sub-package on disk via import.meta.resolve →
+ *      ErrPlatformPackageMissing when not installed
+ *   4. Compute binary path inside the package and verify existence →
+ *      ErrPlatformPackageMissing when binary absent (e.g. CI host mismatch)
+ *   5. dlopen with the full binding spec → return { lib: symbols, libPath }
+ *
+ * resolveNativePath() exports just the path (used by bootstrapFfi.ts which
+ * keeps its own minimal dlopen).
+ *
+ * loadNative() / _loadNativeInternal() dlopen the full binding spec and return
+ * the symbols object together with the resolved path.
+ *
+ * _loadNativeInternal() accepts a PlatformLoadOpts bag for test injection
+ * (override platform, arch, bunVersion without monkey-patching globals).
+ *
+ * Internal — NOT re-exported from src/index.ts.
+ */
+/** Minimum Bun runtime version required by this package (from T1). */
+export declare const MIN_BUN_VERSION = "1.0.21";
+/**
+ * PlatformLoadOpts — dependency-injection bag for loadNative / resolveNativePath.
+ *
+ * All fields are optional; missing fields fall back to the real process
+ * globals. Pass these in unit tests to exercise error branches without
+ * monkey-patching process.platform or Bun.version.
+ */
+export interface PlatformLoadOpts {
+    /** Override process.platform (e.g. "linux", "darwin"). */
+    platform?: string;
+    /** Override process.arch (e.g. "x64", "arm64"). */
+    arch?: string;
+    /** Override Bun.version (e.g. "1.0.0" to trigger ErrBunVersionTooOld). */
+    bunVersion?: string;
+}
+/**
+ * resolveNativePath performs the platform check and sub-package lookup,
+ * returning the absolute path to the native shared library.
+ *
+ * If process.env.AD_CABI_DIR is set, the binary is loaded from
+ * "${AD_CABI_DIR}/libagent_director.{so,dylib}" instead of the npm
+ * sub-package. release.sh's verify_phase exports this so smoke tests
+ * can run before the cabi artifacts have been staged into platforms/.
+ *
+ * Throws one of:
+ *   ErrBunVersionTooOld      — Bun version < MIN_BUN_VERSION
+ *   ErrUnsupportedPlatform   — platform/arch tuple not in SUPPORTED_TUPLES
+ *   ErrPlatformPackageMissing — sub-package not installed or binary absent
+ */
+export declare function resolveNativePath(opts?: PlatformLoadOpts): string;
+/** Symbols returned by dlopen with the full binding spec. */
+export type NativeLib = Record<string, unknown>;
+/**
+ * _loadNativeInternal is the testable core of loadNative().
+ *
+ * Accepts PlatformLoadOpts for dependency injection of platform / arch /
+ * Bun.version so tests can exercise every error branch without live binaries.
+ *
+ * @returns { lib, libPath } — lib is the dlopen symbols object; libPath is the
+ *   absolute path to the .so/.dylib that was loaded (useful for logging).
+ */
+export declare function _loadNativeInternal(opts?: PlatformLoadOpts): {
+    lib: NativeLib;
+    libPath: string;
+};
+/**
+ * loadNative is the public entry point called by worker.ts at startup.
+ *
+ * Uses the real process.platform, process.arch, and Bun.version.
+ */
+export declare function loadNative(): {
+    lib: NativeLib;
+    libPath: string;
+};

package/dist/types.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Structural logger interface — mirrors the four conventional log levels.
+ * All methods are optional; callers may pass any object that implements the
+ * subset they care about (e.g., `console`).
+ */
+export interface Logger {
+    debug?: (message: string, ...args: unknown[]) => void;
+    info?: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+    error?: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Options accepted by the `Client` constructor (SRD SR-1.2).
+ *
+ * `storePath` is the only required field. The others are optional overrides;
+ * absent fields fall back to the same three-tier defaults as `pkg/api.Options`
+ * (config-file value, then hardcoded fallback).
+ *
+ * Tilde expansion is handled TS-side by `src/internal/tilde.ts` before paths
+ * cross the FFI boundary, so the C-ABI never receives a leading `~`.
+ */
+export interface ClientOptions {
+    /** Path to the SQLite store file. Tilde-expanded before crossing FFI. */
+    storePath: string;
+    /** Path to the TOML config file. Tilde-expanded before crossing FFI. */
+    configPath?: string;
+    /** Override the tmux binary. Defaults to the binary on PATH. */
+    tmuxCommand?: string;
+    /**
+     * When `true`, create the store and initialize the database schema if the
+     * store file does not yet exist. When `false` (the default), opening a
+     * non-existent store returns an error. Mirrors `pkg/api.Options.CreateIfMissing`.
+     */
+    createIfMissing?: boolean;
+    /** Optional logger for client-side warnings (e.g., non-fatal close errors). */
+    logger?: Logger;
+}
+/** Mirrors pkg/api.VerbSummary — one entry in the `help` verb result. */
+export interface VerbSummary {
+    /** Canonical CLI/MCP verb name (e.g. "spawn", "send-keys"). */
+    name: string;
+    /** One-line verb description from the manifest. */
+    description: string;
+}
+/** Mirrors pkg/api/get.go::PermissionRequestInfo — embedded in GetResult when state=check_permission. */
+export interface PermissionRequestInfo {
+    /** Autoincrement primary key of the permission_requests row. */
+    request_id: number;
+    /** Claude Code tool that triggered the permission request (e.g. "Bash"). */
+    tool_name: string;
+    /** Raw JSON string of the tool input as stored in the DB. NOT a nested object. */
+    tool_input: string;
+    /** RFC3339 timestamp when the permission request row was created. */
+    requested_at: string;
+}
+/** Mirrors pkg/api/list.go::ListRow — one Spawn row returned by the list verb. */
+export interface ListRow {
+    /** Stable Spawn id. */
+    claude_instance_id: string;
+    /** Parent Spawn id (omitted when launched from a plain shell). */
+    parent_id?: string;
+    /** Current lifecycle state. */
+    state: string;
+    /** Canonicalized working directory. */
+    cwd: string;
+    /** tmux session name. */
+    tmux_session_name: string;
+    /** "on" or "off". */
+    relay_mode: string;
+    /** Caller-supplied key-value tags. */
+    labels: Record<string, string>;
+    /** Row insert time (RFC3339). */
+    started_at: string;
+    /** Most recent hook UPSERT time (RFC3339). */
+    last_seen_at: string;
+    /** Set when state moves to ended (omitted while live). */
+    ended_at?: string | null;
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_spawn params */
+export interface SpawnParams {
+    /** Absolute (or ~/-prefixed) path the Spawn's Claude starts in. Required. */
+    cwd: string;
+    /** Named template under ~/.agent-director/templates/. */
+    template?: string;
+    /** Explicit instance id (UUID4 minted when absent). */
+    claude_instance_id?: string;
+    /** KEY=VALUE label pairs. */
+    label?: string[];
+    /** permissions.allow entries. */
+    allow?: string[];
+    /** permissions.deny entries. */
+    deny?: string[];
+    /** permissions.ask entries. */
+    ask?: string[];
+    /** "on" | "off" | "" (use config default). */
+    relay_mode?: string;
+    /** KEY→VALUE env-var overrides injected on the tmux session. */
+    extra_env?: Record<string, string>;
+    /** Pass-through argv to `claude` after --settings. */
+    claude_args?: string[];
+    /** Skip pre-writing workspace-trust into ~/.claude.json. Default false. */
+    no_pre_trust?: boolean;
+    /** Explicit tmux session name. Auto-derived when absent. */
+    tmux_session_name?: string;
+}
+/** Mirrors pkg/api/spawn.go::SpawnResult */
+export interface SpawnResult {
+    /** The id the new Spawn is tracked under. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_status params */
+export interface StatusParams {
+    /** Id of the Spawn to inspect. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/api/status.go::StatusResult */
+export interface StatusResult {
+    /** Current lifecycle state (pending/waiting/working/ask_user/check_permission/ended/missing). */
+    state: string;
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_get params */
+export interface GetParams {
+    /** Id of the Spawn to fetch. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/api/get.go::SpawnRow */
+export interface GetResult {
+    claude_instance_id: string;
+    parent_id: string;
+    state: string;
+    cwd: string;
+    tmux_session_name: string;
+    claude_args: string[];
+    relay_mode: string;
+    jsonl_path: string;
+    claude_session_id: string;
+    labels: Record<string, string>;
+    /** Row insert time (RFC3339). */
+    started_at: string;
+    /** Last hook UPSERT time (RFC3339). */
+    last_seen_at: string;
+    /** Set when state moves to ended; omitted while live. */
+    ended_at?: string | null;
+    /** Open permission request; present only when state=check_permission with an undecided row. */
+    permission_request?: PermissionRequestInfo | null;
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_send_keys params (pkg/api.SendKeysParams json tags) */
+export interface SendKeysParams {
+    /** Id of the Spawn whose pane will receive the text. */
+    claude_instance_id: string;
+    /** Text to deliver to the pane. CR bytes stripped; LF preserved; Enter appended. */
+    text: string;
+}
+/** Mirrors pkg/api/sendkeys.go::SendKeysResult (empty; reserved for future fields). */
+export interface SendKeysResult {
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_read_pane params (pkg/api.ReadPaneParams json tags) */
+export interface ReadPaneParams {
+    /** Id of the Spawn whose pane will be captured. */
+    claude_instance_id: string;
+    /** Trailing lines to return. Defaults to 25 when 0/omitted. */
+    n_lines?: number;
+    /** When true return raw bytes (ANSI preserved); when false strip ANSI (default). */
+    ansi?: boolean;
+}
+/** Mirrors pkg/api/readpane.go::ReadPaneResult */
+export interface ReadPaneResult {
+    /** Captured pane text. */
+    pane: string;
+}
+/** Mirrors pkg/cabi/verbs_control.go::ad_kill params (pkg/api.KillParams json tags) */
+export interface KillParams {
+    /** Id of the Spawn to kill. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/api/kill.go::KillResult (empty; reserved for future fields). */
+export interface KillResult {
+}
+/** Mirrors pkg/cabi/verbs_control.go::ad_decide params (pkg/api.DecideParams json tags) */
+export interface DecideParams {
+    /** Id of the Spawn whose open permission request is being decided. */
+    claude_instance_id: string;
+    /** Orchestrator verdict. */
+    decision: "allow" | "deny";
+    /** Optional free-text message surfaced to Claude on deny. */
+    reason?: string;
+}
+/** Mirrors pkg/api/decide.go::DecideResult (empty; reserved for future fields). */
+export interface DecideResult {
+}
+/** Mirrors pkg/cabi/verbs_control.go::ad_resume params (pkg/api.ResumeParams json tags) */
+export interface ResumeParams {
+    /** Id of the terminated Spawn to resurrect. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/api/resume.go::ResumeResult */
+export interface ResumeResult {
+    /** Same id that was passed in (preserved across resurrection). */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/cabi/verbs_control.go::ad_find_missing params */
+export interface FindMissingParams {
+    /** Optional deadline for the OS probe sweep (milliseconds). 0/omitted = no deadline. */
+    timeout_ms?: number;
+}
+/** Mirrors pkg/api/find_missing.go::FindMissingResult */
+export interface FindMissingResult {
+    /** Number of rows transitioned to missing on this sweep. */
+    count: number;
+    /** Sorted ids of rows transitioned to missing. */
+    ids: string[];
+}
+/** Mirrors pkg/cabi/verbs_admin.go::ad_expire params */
+export interface ExpireParams {
+    /**
+     * Duration override (e.g. "7d", "2h", "0d"). When omitted, the config
+     * default (defaults.expire_retention_days) applies.
+     */
+    older_than?: string;
+}
+/** Mirrors pkg/api/expire.go::ExpireResult */
+export interface ExpireResult {
+    /** Number of terminal rows removed. */
+    count: number;
+    /** Sorted ids of rows removed. */
+    ids: string[];
+}
+/** Mirrors pkg/cabi/verbs_admin.go::ad_delete params */
+export interface DeleteParams {
+    /** Id(s) to delete. */
+    claude_instance_id: string[];
+}
+/** Mirrors pkg/api/delete.go::DeleteResult */
+export interface DeleteResult {
+    /** Per-id outcome: "ok" on success, err_name on failure. */
+    results: Record<string, string>;
+}
+/** Mirrors pkg/cabi/verbs_admin.go::ad_make_template params */
+export interface MakeTemplateParams {
+    /** Template filename (without extension). Must be filename-safe. Required. */
+    name: string;
+    /** Default working directory to bake in. */
+    cwd?: string;
+    /** Default relay mode: "on" | "off" | "" (inherit). */
+    relay_mode?: string;
+    /** Default claude argv. Per-call --claude-args replaces wholesale. */
+    claude_args?: string[];
+    /** Env-var overrides to bake in. */
+    extra_env?: Record<string, string>;
+    /** Label k=v entries to bake in. */
+    label?: string[];
+    /** permissions.allow entries. */
+    allow?: string[];
+    /** permissions.deny entries. */
+    deny?: string[];
+    /** permissions.ask entries. */
+    ask?: string[];
+}
+/** Mirrors pkg/api/make_template.go::MakeTemplateResult */
+export interface MakeTemplateResult {
+    /** Absolute path of the written template TOML file. */
+    path: string;
+}
+/** Mirrors pkg/cabi/verbs_read.go::ad_list params */
+export interface ListParams {
+    /** Filter by state (multiple values OR together). */
+    state?: string[];
+    /** Filter by label k=v pairs (multiple entries AND together). */
+    label?: string[];
+    /** Filter by parent_id exact match. */
+    parent?: string;
+    /** Filter by canonicalized cwd exact match. */
+    cwd?: string;
+    /** Filter by tmux session name exact match. */
+    tmux_session_name?: string;
+    /** Cap result count. 0/omitted means no cap. */
+    limit?: number;
+}
+/** Mirrors pkg/api/list.go::ListResult */
+export interface ListResult {
+    /** Matching Spawn rows. Empty array when none match. */
+    spawns: ListRow[];
+}
+/** Mirrors pkg/cabi/verbs_control.go::ad_pause params (pkg/api.PauseParams json tags) */
+export interface PauseParams {
+    /** Id of the Spawn to pause gracefully. */
+    claude_instance_id: string;
+}
+/** Mirrors pkg/api/pause.go::PauseResult (empty; reserved for future fields). */
+export interface PauseResult {
+}
+/** Mirrors pkg/cabi/verbs_admin.go::ad_version params (handle-free; no user params). */
+export interface VersionParams {
+}
+/** Mirrors pkg/api/version.go::VersionResult */
+export interface VersionResult {
+    /** Human-readable version stamp. "dev" for unstamped builds. */
+    version: string;
+    /** Full git SHA. "unknown" for unstamped builds. */
+    commit: string;
+}

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "agent-director",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
   "engines": {
     "bun": ">=1.0.21"
   },
@@ -9,7 +17,9 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "!dist/**/*.test.*",
-    "README.md"
+    "README.md",
+    "scripts/postinstall.ts",
+    "skills/install-agent-director/**"
   ],
   "exports": {
     ".": {
@@ -25,12 +35,15 @@
     "smoke": "bun test test/smoke/ test/smoke-invariants.test.ts",
     "envelope-diff": "bun test test/envelope-diff.test.ts test/envelope-diff-invariants.test.ts",
     "prepare-platforms": "bun run scripts/prepare-platforms.ts",
+    "stage-skill": "bun run scripts/stage-skill.ts",
+    "prepack": "bun run build && bun run scripts/stage-skill.ts",
+    "postinstall": "bun run scripts/postinstall.ts",
     "version-bump-publish": "bun run scripts/version-bump.ts",
-    "prepublishOnly": "bun run scripts/check-not-placeholder.ts"
+    "prepublishOnly": "bun run scripts/prepublish-guards.ts"
   },
   "optionalDependencies": {
-    "@agent-director/linux-x64": "^0.4.0",
-    "@agent-director/darwin-arm64": "^0.4.0"
+    "@agent-director/linux-x64": "^0.4.2",
+    "@agent-director/darwin-arm64": "^0.4.2"
   },
   "devDependencies": {
     "typescript": ">=5.2.0",