agent-director 0.4.1 → 0.4.2

package/dist/index.js

@@ -0,0 +1,603 @@
+// @bun
+// src/internal/tilde.ts
+import * as os from "os";
+function expandTilde(p) {
+  if (p === "")
+    return "";
+  if (p !== "~" && !p.startsWith("~/"))
+    return p;
+  const home = process.env["HOME"] ?? os.homedir();
+  if (p === "~")
+    return home;
+  return home + p.slice(1);
+}
+
+// src/internal/bootstrapFfi.ts
+import { dlopen, FFIType, CString, ptr } from "bun:ffi";
+
+// src/platform.ts
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+
+// src/errors.ts
+class AgentDirectorError extends Error {
+  verb;
+  errName;
+  errDescription;
+  constructor(verb, err_name, err_description) {
+    super(`${err_name}: ${err_description}`);
+    this.verb = verb;
+    this.errName = err_name;
+    this.errDescription = err_description;
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class ErrClientClosed extends AgentDirectorError {
+  constructor() {
+    super("", "ErrClientClosed", "client is closed: call new Client() to obtain a fresh handle");
+    this.name = "ErrClientClosed";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class ErrUnsupportedPlatform extends AgentDirectorError {
+  constructor(tuple) {
+    super("", "ErrUnsupportedPlatform", `platform/arch tuple "${tuple}" is not supported; supported: linux-x64, darwin-arm64`);
+    this.name = "ErrUnsupportedPlatform";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class ErrPlatformPackageMissing extends AgentDirectorError {
+  constructor(pkgName, detail) {
+    const desc = detail ? `native sub-package "${pkgName}" is not usable: ${detail}` : `native sub-package "${pkgName}" is not installed or its binary is absent`;
+    super("", "ErrPlatformPackageMissing", desc);
+    this.name = "ErrPlatformPackageMissing";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class ErrBunVersionTooOld extends AgentDirectorError {
+  constructor(actual, minimum) {
+    super("", "ErrBunVersionTooOld", `Bun ${actual} is below the minimum required version ${minimum}; upgrade Bun to continue`);
+    this.name = "ErrBunVersionTooOld";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class ErrCwdMissing extends AgentDirectorError {
+}
+
+class ErrCwdNotAPath extends AgentDirectorError {
+}
+
+class ErrCwdNotFound extends AgentDirectorError {
+}
+
+class ErrCwdNotADirectory extends AgentDirectorError {
+}
+
+class ErrRelayModeInvalid extends AgentDirectorError {
+}
+
+class ErrSpawnDeniedFlag extends AgentDirectorError {
+}
+
+class ErrReservedEnvKey extends AgentDirectorError {
+}
+
+class ErrInstanceIdCollision extends AgentDirectorError {
+}
+
+class ErrTmuxSessionNameEmpty extends AgentDirectorError {
+}
+
+class ErrTmuxSessionNameInvalid extends AgentDirectorError {
+}
+
+class ErrTmuxSessionNameTooLong extends AgentDirectorError {
+}
+
+class ErrSpawnNotFound extends AgentDirectorError {
+}
+
+class ErrTmuxNotAvailable extends AgentDirectorError {
+}
+
+class ErrTmuxSessionCreate extends AgentDirectorError {
+}
+
+class ErrTmuxSendKeys extends AgentDirectorError {
+}
+
+class ErrTmuxCaptureFailed extends AgentDirectorError {
+}
+
+class ErrSpawnNotInteractive extends AgentDirectorError {
+}
+
+class ErrSendKeysWhileRelayed extends AgentDirectorError {
+}
+
+class ErrSpawnNotPausable extends AgentDirectorError {
+}
+
+class ErrPauseTimeout extends AgentDirectorError {
+}
+
+class ErrListInvalidLabel extends AgentDirectorError {
+}
+
+class ErrTemplateNameUnsafe extends AgentDirectorError {
+}
+
+class ErrTemplateNotFound extends AgentDirectorError {
+}
+
+class ErrTemplateMalformed extends AgentDirectorError {
+}
+
+class ErrTemplateExists extends AgentDirectorError {
+}
+
+class ErrProbeUnsupported extends AgentDirectorError {
+}
+
+class ErrSpawnNotResumable extends AgentDirectorError {
+}
+
+class ErrNoSessionId extends AgentDirectorError {
+}
+
+class ErrJsonlMissing extends AgentDirectorError {
+}
+
+class ErrRelayModeOff extends AgentDirectorError {
+}
+
+class ErrInvalidDecision extends AgentDirectorError {
+}
+
+class ErrNoOpenPermissionRequest extends AgentDirectorError {
+}
+
+class ErrAlreadyDecided extends AgentDirectorError {
+}
+
+class ErrUnknownHandle extends AgentDirectorError {
+}
+var ERROR_TABLE = {
+  ErrCwdMissing,
+  ErrCwdNotAPath,
+  ErrCwdNotFound,
+  ErrCwdNotADirectory,
+  ErrRelayModeInvalid,
+  ErrSpawnDeniedFlag,
+  ErrReservedEnvKey,
+  ErrInstanceIdCollision,
+  ErrTmuxSessionNameEmpty,
+  ErrTmuxSessionNameInvalid,
+  ErrTmuxSessionNameTooLong,
+  ErrSpawnNotFound,
+  ErrNoOpenPermissionRequest,
+  ErrAlreadyDecided,
+  ErrTmuxNotAvailable,
+  ErrTmuxSessionCreate,
+  ErrTmuxSendKeys,
+  ErrTmuxCaptureFailed,
+  ErrSpawnNotInteractive,
+  ErrSendKeysWhileRelayed,
+  ErrSpawnNotPausable,
+  ErrPauseTimeout,
+  ErrListInvalidLabel,
+  ErrSpawnNotResumable,
+  ErrNoSessionId,
+  ErrJsonlMissing,
+  ErrRelayModeOff,
+  ErrInvalidDecision,
+  ErrTemplateNameUnsafe,
+  ErrTemplateNotFound,
+  ErrTemplateMalformed,
+  ErrTemplateExists,
+  ErrProbeUnsupported,
+  ErrUnknownHandle
+};
+function errorFromEnvelope(verb, err_name, err_description) {
+  const Ctor = ERROR_TABLE[err_name];
+  if (Ctor) {
+    return new Ctor(verb, err_name, err_description);
+  }
+  console.warn(`agent-director: unknown err_name "${err_name}" (verb=${verb}); returning base AgentDirectorError`);
+  return new AgentDirectorError(verb, err_name, err_description);
+}
+
+// src/internal/verbs.ts
+var VERBS = [
+  "spawn",
+  "status",
+  "get",
+  "send-keys",
+  "read-pane",
+  "kill",
+  "decide",
+  "resume",
+  "find-missing",
+  "expire",
+  "delete",
+  "make-template",
+  "list",
+  "pause",
+  "version"
+];
+function kebabToUnderscore(v) {
+  return v.replace(/-/g, "_");
+}
+var HANDLE_FREE_VERBS = new Set(["version"]);
+
+// src/internal/bindingSpec.ts
+var BINDING_SYMBOL_NAMES = [
+  "ad_open",
+  "ad_close",
+  "ad_free_cstring",
+  ...VERBS.map((v) => "ad_" + kebabToUnderscore(v))
+];
+
+// src/platform.ts
+var MIN_BUN_VERSION = "1.0.21";
+var SUPPORTED_TUPLES = new Map([
+  ["linux-x64", "@agent-director/linux-x64"],
+  ["darwin-arm64", "@agent-director/darwin-arm64"]
+]);
+function compareSemver(a, b) {
+  const parse = (s) => s.split(".").map((p) => parseInt(p, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0;i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0)
+      return diff;
+  }
+  return 0;
+}
+function resolveNativePath(opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const arch = opts.arch ?? process.arch;
+  const bunVersion = opts.bunVersion ?? Bun.version;
+  if (compareSemver(bunVersion, MIN_BUN_VERSION) < 0) {
+    throw new ErrBunVersionTooOld(bunVersion, MIN_BUN_VERSION);
+  }
+  const tuple = `${platform}-${arch}`;
+  const subpkgName = SUPPORTED_TUPLES.get(tuple);
+  if (!subpkgName) {
+    throw new ErrUnsupportedPlatform(tuple);
+  }
+  const binaryExt = platform === "darwin" ? "dylib" : "so";
+  const binaryName = `libagent_director.${binaryExt}`;
+  const cabiDir = process.env.AD_CABI_DIR;
+  if (cabiDir) {
+    const cabiPath = join(cabiDir, binaryName);
+    if (!existsSync(cabiPath)) {
+      throw new ErrPlatformPackageMissing(subpkgName, `AD_CABI_DIR is set but "${binaryName}" not found in ${cabiDir}`);
+    }
+    return cabiPath;
+  }
+  let pkgDir;
+  try {
+    const resolved = import.meta.resolve(`${subpkgName}/package.json`);
+    pkgDir = dirname(fileURLToPath(resolved));
+  } catch {
+    throw new ErrPlatformPackageMissing(subpkgName);
+  }
+  const libPath = join(pkgDir, binaryName);
+  if (!existsSync(libPath)) {
+    throw new ErrPlatformPackageMissing(subpkgName, `binary "${binaryName}" not found in package directory ${pkgDir}`);
+  }
+  return libPath;
+}
+
+// src/internal/bootstrapFfi.ts
+var _soPath = resolveNativePath();
+var _lib = dlopen(_soPath, {
+  ad_open: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr
+  },
+  ad_close: {
+    args: [FFIType.cstring],
+    returns: FFIType.ptr
+  },
+  ad_free_cstring: {
+    args: [FFIType.ptr],
+    returns: FFIType.void
+  }
+});
+function callOpen(params) {
+  const jsonBytes = Buffer.from(JSON.stringify(params) + "\x00");
+  const rawPtr = _lib.symbols.ad_open(ptr(jsonBytes));
+  return _readAndFree(rawPtr);
+}
+function callClose(params) {
+  const jsonBytes = Buffer.from(JSON.stringify(params) + "\x00");
+  const rawPtr = _lib.symbols.ad_close(ptr(jsonBytes));
+  return _readAndFree(rawPtr);
+}
+function _readAndFree(rawPtr) {
+  if (rawPtr === null || rawPtr === 0) {
+    throw new Error("bootstrapFfi: ad_* returned a null pointer");
+  }
+  const result = new CString(rawPtr).toString();
+  _lib.symbols.ad_free_cstring(rawPtr);
+  return result;
+}
+
+// src/internal/workerProxy.ts
+import { Worker } from "worker_threads";
+function isErrorEnvelope(v) {
+  return typeof v === "object" && v !== null && typeof v.err_name === "string";
+}
+var _worker = null;
+var _nextId = 1;
+var _pending = new Map;
+var _readyResolve = null;
+var _readyReject = null;
+var _readyPromise = null;
+function _rejectAll(reason) {
+  for (const entry of _pending.values()) {
+    entry.reject(reason);
+  }
+  _pending.clear();
+}
+function _spawnWorker() {
+  const worker = new Worker(new URL("./worker.ts", import.meta.url));
+  if (typeof worker.unref === "function") {
+    worker.unref();
+  }
+  _readyPromise = new Promise((resolve, reject) => {
+    _readyResolve = resolve;
+    _readyReject = reject;
+  });
+  worker.on("message", (msg) => {
+    if (msg.type === "ready") {
+      _readyResolve?.();
+      _readyResolve = null;
+      _readyReject = null;
+      return;
+    }
+    if (msg.type === "startup-error") {
+      const err = new Error(`agent-director worker failed to start: ${msg.message ?? "(unknown)"}`);
+      _readyReject?.(err);
+      _readyResolve = null;
+      _readyReject = null;
+      _rejectAll(err);
+      return;
+    }
+    const entry = _pending.get(msg.id);
+    if (!entry)
+      return;
+    _pending.delete(msg.id);
+    if (msg.type === "ffi-error") {
+      entry.reject(new Error(`FFI error: ${msg.message ?? "(unknown)"}`));
+      return;
+    }
+    const jsonString = msg.jsonString ?? "";
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonString);
+    } catch (e) {
+      entry.reject(new Error(`Failed to parse C-ABI response JSON: ${e instanceof Error ? e.message : String(e)}`));
+      return;
+    }
+    if (isErrorEnvelope(parsed)) {
+      entry.reject(errorFromEnvelope(entry.op, parsed.err_name, parsed.err_description));
+      return;
+    }
+    entry.resolve(parsed);
+  });
+  worker.on("error", (err) => {
+    const reason = new Error(`agent-director worker error: ${err.message}`);
+    _readyReject?.(reason);
+    _readyResolve = null;
+    _readyReject = null;
+    _rejectAll(reason);
+  });
+  worker.on("exit", (code) => {
+    const reason = new Error(`agent-director worker exited with code ${code}`);
+    _readyReject?.(reason);
+    _readyResolve = null;
+    _readyReject = null;
+    if (_pending.size > 0) {
+      _rejectAll(reason);
+    }
+    _worker = null;
+    _readyPromise = null;
+  });
+  _worker = worker;
+}
+async function _ensureWorker() {
+  if (_worker === null) {
+    _spawnWorker();
+  }
+  await _readyPromise;
+}
+var workerProxy = {
+  async dispatch(op, handle, params) {
+    await _ensureWorker();
+    const id = _nextId++;
+    const paramsJSON = JSON.stringify(params ?? {});
+    return new Promise((resolve, reject) => {
+      _pending.set(id, { resolve, reject, op });
+      _worker.postMessage({ id, op, handle, paramsJSON });
+    });
+  }
+};
+
+// src/ffi.ts
+async function callVerb(verb, handle, params) {
+  return workerProxy.dispatch(verb, handle, params);
+}
+
+// src/client.ts
+function isErrorEnvelope2(env) {
+  return typeof env === "object" && env !== null && "err_name" in env && typeof env.err_name === "string";
+}
+
+class Client {
+  _handle;
+  _open;
+  _logger;
+  constructor(opts) {
+    this._handle = null;
+    this._open = false;
+    this._logger = opts.logger;
+    const storePath = expandTilde(opts.storePath);
+    const configPath = opts.configPath !== undefined ? expandTilde(opts.configPath) : undefined;
+    const params = { store_path: storePath };
+    if (configPath !== undefined)
+      params.config_path = configPath;
+    if (opts.tmuxCommand !== undefined)
+      params.tmux_command = opts.tmuxCommand;
+    if (opts.createIfMissing !== undefined)
+      params.create_if_missing = opts.createIfMissing;
+    const envelopeJSON = callOpen(params);
+    const env = JSON.parse(envelopeJSON);
+    if (isErrorEnvelope2(env)) {
+      throw errorFromEnvelope("open", env.err_name, env.err_description);
+    }
+    this._handle = env.handle;
+    this._open = true;
+  }
+  _assertOpen() {
+    if (!this._open) {
+      throw new ErrClientClosed;
+    }
+  }
+  close() {
+    if (!this._open)
+      return;
+    const handle = this._handle;
+    try {
+      const envelopeJSON = callClose({ handle });
+      const env = JSON.parse(envelopeJSON);
+      if (isErrorEnvelope2(env)) {
+        this._logger?.warn?.(`Client.close(): ad_close returned error envelope`, { err_name: env.err_name, err_description: env.err_description });
+      }
+    } catch (e) {
+      this._logger?.warn?.("Client.close(): unexpected error calling ad_close", e);
+    } finally {
+      this._handle = null;
+      this._open = false;
+    }
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+  async spawn(params) {
+    this._assertOpen();
+    return callVerb("spawn", this._handle, params);
+  }
+  async status(params) {
+    this._assertOpen();
+    return callVerb("status", this._handle, params);
+  }
+  async get(params) {
+    this._assertOpen();
+    return callVerb("get", this._handle, params);
+  }
+  async sendKeys(params) {
+    this._assertOpen();
+    return callVerb("send-keys", this._handle, params);
+  }
+  async readPane(params) {
+    this._assertOpen();
+    return callVerb("read-pane", this._handle, params);
+  }
+  async kill(params) {
+    this._assertOpen();
+    return callVerb("kill", this._handle, params);
+  }
+  async decide(params) {
+    this._assertOpen();
+    return callVerb("decide", this._handle, params);
+  }
+  async resume(params) {
+    this._assertOpen();
+    return callVerb("resume", this._handle, params);
+  }
+  async findMissing(params) {
+    this._assertOpen();
+    return callVerb("find-missing", this._handle, params);
+  }
+  async expire(params) {
+    this._assertOpen();
+    return callVerb("expire", this._handle, params);
+  }
+  async delete(params) {
+    this._assertOpen();
+    return callVerb("delete", this._handle, params);
+  }
+  async makeTemplate(params) {
+    this._assertOpen();
+    return callVerb("make-template", this._handle, params);
+  }
+  async list(params) {
+    this._assertOpen();
+    return callVerb("list", this._handle, params);
+  }
+  async pause(params) {
+    this._assertOpen();
+    return callVerb("pause", this._handle, params);
+  }
+  async version(params) {
+    this._assertOpen();
+    return callVerb("version", null, params);
+  }
+  _assertOpenForTests() {
+    this._assertOpen();
+  }
+}
+export {
+  errorFromEnvelope,
+  ErrUnsupportedPlatform,
+  ErrUnknownHandle,
+  ErrTmuxSessionNameTooLong,
+  ErrTmuxSessionNameInvalid,
+  ErrTmuxSessionNameEmpty,
+  ErrTmuxSessionCreate,
+  ErrTmuxSendKeys,
+  ErrTmuxNotAvailable,
+  ErrTmuxCaptureFailed,
+  ErrTemplateNotFound,
+  ErrTemplateNameUnsafe,
+  ErrTemplateMalformed,
+  ErrTemplateExists,
+  ErrSpawnNotResumable,
+  ErrSpawnNotPausable,
+  ErrSpawnNotInteractive,
+  ErrSpawnNotFound,
+  ErrSpawnDeniedFlag,
+  ErrSendKeysWhileRelayed,
+  ErrReservedEnvKey,
+  ErrRelayModeOff,
+  ErrRelayModeInvalid,
+  ErrProbeUnsupported,
+  ErrPlatformPackageMissing,
+  ErrPauseTimeout,
+  ErrNoSessionId,
+  ErrNoOpenPermissionRequest,
+  ErrListInvalidLabel,
+  ErrJsonlMissing,
+  ErrInvalidDecision,
+  ErrInstanceIdCollision,
+  ErrCwdNotFound,
+  ErrCwdNotAPath,
+  ErrCwdNotADirectory,
+  ErrCwdMissing,
+  ErrClientClosed,
+  ErrBunVersionTooOld,
+  ErrAlreadyDecided,
+  Client,
+  AgentDirectorError
+};

package/dist/internal/bindingSpec.d.ts

@@ -0,0 +1,37 @@
+/**
+ * bindingSpec — canonical set of C-ABI symbol names expected in the dlopen
+ * binding object, plus a factory that builds the runtime FFI binding spec.
+ *
+ * BINDING_SYMBOL_NAMES is exported as a plain string array so the
+ * binding-coverage test can import it WITHOUT spawning a worker or loading
+ * the native library.
+ *
+ * buildBindingSpec() returns the full FFI binding object suitable for passing
+ * directly to Bun's dlopen(). It is the single source of truth consumed by
+ * platform.ts::loadNative() so that worker.ts and bootstrapFfi.ts both
+ * resolve the same symbols without duplication.
+ *
+ * Any drift between BINDING_SYMBOL_NAMES and buildBindingSpec() is caught
+ * by test/ffi-binding-coverage.test.ts.
+ */
+import { FFIType } from "bun:ffi";
+/**
+ * BINDING_SYMBOL_NAMES is the exhaustive list of C symbols that the worker's
+ * dlopen binding object must declare.
+ */
+export declare const BINDING_SYMBOL_NAMES: readonly string[];
+/** A single FFI function declaration (args + return type). */
+export interface FFISymbolDef {
+    args: FFIType[];
+    returns: FFIType;
+}
+/** The full dlopen binding spec as a plain object — pass to Bun's dlopen(). */
+export type BindingSpec = Record<string, FFISymbolDef>;
+/**
+ * buildBindingSpec constructs the full FFI binding map for the native library.
+ *
+ * Includes lifecycle symbols (ad_open, ad_close, ad_free_cstring) plus one
+ * entry per callable verb. All verb symbols take a single cstring argument and
+ * return a ptr (raw pointer, freed via ad_free_cstring).
+ */
+export declare function buildBindingSpec(): BindingSpec;

package/dist/internal/bootstrapFfi.d.ts

@@ -0,0 +1,37 @@
+/**
+ * bootstrapFfi — thin synchronous dlopen wrapper used by the Client
+ * constructor and close().
+ *
+ * Only three symbols are needed here: ad_open, ad_close, ad_free_cstring.
+ * The full binding spec (all 18 symbols) is used by worker.ts via loadNative().
+ *
+ * Library path resolution delegates to platform.ts::resolveNativePath() so
+ * that all platforms (linux-x64, darwin-arm64) resolve their binary from the
+ * correct optional sub-package, and so this file shares the same path logic
+ * as the worker.
+ *
+ * Internal — NOT re-exported from src/index.ts.
+ */
+/**
+ * callOpen encodes params as JSON, calls ad_open, copies the returned C
+ * string into a JS string, frees the C pointer, and returns the envelope
+ * JSON string.
+ *
+ * Throws if the library call itself fails (i.e. the function pointer is
+ * null) — normal Go-level errors are returned as error envelopes, not
+ * thrown.
+ */
+export declare function callOpen(params: {
+    store_path: string;
+    config_path?: string;
+    tmux_command?: string;
+    create_if_missing?: boolean;
+}): string;
+/**
+ * callClose encodes params as JSON, calls ad_close, copies the returned C
+ * string into a JS string, frees the C pointer, and returns the envelope
+ * JSON string.
+ */
+export declare function callClose(params: {
+    handle: string;
+}): string;

package/dist/internal/freeGuard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FreeGuard — single-free wrapper for native pointers.
+ *
+ * Every C-ABI call that returns a pointer must pass it to `ad_free_cstring`
+ * exactly once. FreeGuard enforces this:
+ *
+ *   const guard = new FreeGuard(rawPtr, (p) => lib.symbols.ad_free_cstring(p));
+ *   try {
+ *     const str = new CString(guard.ptr!).toString();
+ *     return str;
+ *   } finally {
+ *     guard.free();  // safe to call even on error path; no-op on second call
+ *   }
+ *
+ * Design constraints:
+ *   - No bun:ffi imports — accepts the free function as a constructor arg so
+ *     tests can stub it without loading a native library.
+ *   - Generic over T so the same guard works for Pointer (branded number) or
+ *     any other pointer-like primitive without widening to `any`.
+ *   - `free()` nulls the internal reference before calling the underlying
+ *     free function, so a synchronous exception inside the free function
+ *     cannot cause a double-free on a subsequent call.
+ */
+export declare class FreeGuard<T> {
+    private _ptr;
+    private readonly _free;
+    constructor(ptr: T, free: (p: T) => void);
+    /**
+     * ptr returns the guarded pointer, or null if `free()` has already been
+     * called. Callers must check for null before dereferencing.
+     */
+    get ptr(): T | null;
+    /**
+     * free calls the underlying free function with the guarded pointer exactly
+     * once. After the first call, the internal reference is nulled and
+     * subsequent calls are silent no-ops.
+     */
+    free(): void;
+}