@vellumai/assistant 0.7.3 → 0.8.0

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.test.ts

@@ -0,0 +1,430 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  rmSync,
+  unlinkSync,
+} from "node:fs";
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SocketWatchdog, type SocketWatchdogLogger } from "./socket-watchdog.js";
+
+// macOS caps Unix-socket paths at sizeof(sun_path)-1 == 103 bytes, so the
+// shared test-preload temp dir is too long. Mint a short path under tmpdir
+// for these tests.
+const shortRoot = mkdtempSync(join(tmpdir(), "vmw-"));
+const socketPath = join(shortRoot, "g.sock");
+
+afterAll(() => {
+  try {
+    rmSync(shortRoot, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+});
+
+interface TestHarness {
+  watchdog: SocketWatchdog;
+  /** Mutated by tests to simulate stop()/restart. */
+  serverRef: { current: Server | null };
+  /** Servers handed to onRebind, captured for assertions + cleanup. */
+  rebinds: Array<{ newServer: Server; oldServer: Server }>;
+  log: SocketWatchdogLogger;
+  loggedErrors: Array<{ obj: object; msg?: string }>;
+  /** Tracks every server the harness factory produced, for cleanup. */
+  spawnedServers: Server[];
+}
+
+interface BuildOptions {
+  intervalMs?: number;
+  createServerOverride?: () => Server;
+  /** Override `getServer` to simulate races. */
+  getServerOverride?: () => Server | null;
+}
+
+function buildHarness(opts: BuildOptions): TestHarness {
+  const serverRef: { current: Server | null } = { current: null };
+  const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+  const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+  const spawnedServers: Server[] = [];
+
+  const log: SocketWatchdogLogger = {
+    info: () => {},
+    warn: () => {},
+    error: (obj, msg) => {
+      loggedErrors.push({ obj, msg });
+    },
+  };
+
+  const defaultFactory = () => {
+    const s = createServer();
+    s.on("error", () => {
+      /* tests don't care; suppress */
+    });
+    spawnedServers.push(s);
+    return s;
+  };
+
+  const watchdog = new SocketWatchdog({
+    socketPath,
+    intervalMs: opts.intervalMs ?? 0,
+    getServer: opts.getServerOverride ?? (() => serverRef.current),
+    createServer: opts.createServerOverride ?? defaultFactory,
+    onRebind: (newServer, oldServer) => {
+      rebinds.push({ newServer, oldServer });
+      serverRef.current = newServer;
+      // Mirror gateway behavior: close old server gracefully so its
+      // accept-loop drains. Close errors are not the watchdog's concern.
+      oldServer.close(() => {
+        /* drained */
+      });
+    },
+    log,
+  });
+
+  return { watchdog, serverRef, rebinds, log, loggedErrors, spawnedServers };
+}
+
+/**
+ * Spin up a real listening server and install it into the harness. Returns
+ * once the kernel reports the socket file present on disk.
+ */
+async function startInitialServer(harness: TestHarness): Promise<Server> {
+  const server = createServer();
+  server.on("error", () => {
+    /* ignore */
+  });
+  harness.spawnedServers.push(server);
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.once("listening", () => resolve());
+    server.listen(socketPath);
+  });
+  harness.serverRef.current = server;
+  return server;
+}
+
+function connectClient(path: string): Promise<Socket> {
+  return new Promise<Socket>((resolve, reject) => {
+    const client: Socket = createConnection(path, () => resolve(client));
+    client.on("error", reject);
+  });
+}
+
+async function closeServer(server: Server): Promise<void> {
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+describe("SocketWatchdog", () => {
+  let harness: TestHarness | undefined;
+  const sockets: Socket[] = [];
+
+  beforeEach(() => {
+    harness = undefined;
+    // Defensive: clean up any leftover socket file from a previous test
+    // whose afterEach didn't fully drain.
+    if (existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  afterEach(async () => {
+    for (const s of sockets) {
+      if (!s.destroyed) s.destroy();
+    }
+    sockets.length = 0;
+
+    if (harness) {
+      harness.watchdog.stop();
+      // Close every server the harness produced, regardless of how the
+      // test left things. Closing an already-closed server is a no-op.
+      for (const s of harness.spawnedServers) {
+        try {
+          await closeServer(s);
+        } catch {
+          /* already closed */
+        }
+      }
+      harness = undefined;
+    }
+
+    if (existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  test("rebindIfMissing is a no-op when the socket path exists", async () => {
+    harness = buildHarness({});
+    await startInitialServer(harness);
+
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(harness.rebinds).toHaveLength(0);
+    expect(existsSync(socketPath)).toBe(true);
+  });
+
+  test("rebindIfMissing is a no-op when getServer returns null", async () => {
+    harness = buildHarness({});
+    // serverRef.current stays null.
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(harness.rebinds).toHaveLength(0);
+  });
+
+  test("rebindIfMissing recreates the listener when the path is gone", async () => {
+    harness = buildHarness({});
+    const initial = await startInitialServer(harness);
+    expect(existsSync(socketPath)).toBe(true);
+
+    // Simulate the cleanup that wipes /run/* — unlink the path while the
+    // listener fd is still alive in the kernel.
+    unlinkSync(socketPath);
+    expect(existsSync(socketPath)).toBe(false);
+
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(true);
+    expect(existsSync(socketPath)).toBe(true);
+    expect(harness.rebinds).toHaveLength(1);
+    expect(harness.rebinds[0]!.oldServer).toBe(initial);
+    expect(harness.serverRef.current).toBe(harness.rebinds[0]!.newServer);
+
+    // A fresh client can connect to the re-bound listener.
+    const client = await connectClient(socketPath);
+    sockets.push(client);
+    expect(client.destroyed).toBe(false);
+  });
+
+  test("connected clients survive a rebind", async () => {
+    harness = buildHarness({});
+    await startInitialServer(harness);
+
+    const survivor = await connectClient(socketPath);
+    sockets.push(survivor);
+    expect(survivor.destroyed).toBe(false);
+
+    unlinkSync(socketPath);
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(true);
+
+    // Give the close-callback a moment to settle without churning the EL.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(survivor.destroyed).toBe(false);
+  });
+
+  test("rebindIfMissing aborts when getServer changes mid-listen (shutdown race)", async () => {
+    // Drive the race deterministically by mutating what getServer returns
+    // between its first call (precondition check) and its second call
+    // (post-listen race guard).
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    let getServerCalls = 0;
+    const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+    const spawnedNewServers: Server[] = [];
+
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 0,
+      getServer: () => {
+        getServerCalls++;
+        // First call: precondition — initialServer is still around.
+        // Subsequent calls (race guard): null, simulating stop().
+        return getServerCalls === 1 ? initial : null;
+      },
+      createServer: () => {
+        const s = createServer();
+        s.on("error", () => {});
+        spawnedNewServers.push(s);
+        return s;
+      },
+      onRebind: (n, o) => {
+        rebinds.push({ newServer: n, oldServer: o });
+      },
+      log: { info: () => {}, warn: () => {}, error: () => {} },
+    });
+
+    unlinkSync(socketPath);
+    expect(existsSync(socketPath)).toBe(false);
+
+    const rebound = await watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(rebinds).toHaveLength(0);
+    // The race guard should have unlinked the path the discarded server
+    // recreated, so a future start() doesn't see a phantom listener.
+    expect(existsSync(socketPath)).toBe(false);
+    // getServer was called at least twice — once for precondition, once
+    // for the race guard.
+    expect(getServerCalls).toBeGreaterThanOrEqual(2);
+
+    // Cleanup: initial is still listening on the unlinked path; close it.
+    await closeServer(initial);
+    for (const s of spawnedNewServers) {
+      try {
+        await closeServer(s);
+      } catch {
+        /* already closed by race guard */
+      }
+    }
+  });
+
+  test("rebindIfMissing returns false and logs when listen() rejects", async () => {
+    // Provide a factory whose listen() always errors, so rebindIfMissing
+    // hits the catch branch.
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+    const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+    const failingFactory = () => {
+      const s = createServer();
+      s.on("error", () => {});
+      // Replace listen to immediately error.
+      const realListen = s.listen.bind(s);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (s as any).listen = (_path: string) => {
+        queueMicrotask(() => s.emit("error", new Error("simulated EADDRINUSE")));
+        return s;
+      };
+      // Keep realListen reference alive so TS doesn't complain
+      void realListen;
+      return s;
+    };
+
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 0,
+      getServer: () => initial,
+      createServer: failingFactory,
+      onRebind: (n, o) => rebinds.push({ newServer: n, oldServer: o }),
+      log: {
+        info: () => {},
+        warn: () => {},
+        error: (obj, msg) => loggedErrors.push({ obj, msg }),
+      },
+    });
+
+    unlinkSync(socketPath);
+    const rebound = await watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(rebinds).toHaveLength(0);
+    expect(loggedErrors.length).toBeGreaterThan(0);
+
+    await closeServer(initial);
+  });
+
+  test("watchdog timer catches synchronous rebind errors so unhandled rejections don't escape", async () => {
+    // createServer factory throws synchronously — simulates EACCES on
+    // mkdir / a broken factory dependency.
+    const throwingFactory = () => {
+      throw new Error("boom — synchronous factory failure");
+    };
+
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 5,
+      getServer: () => initial,
+      createServer: throwingFactory,
+      onRebind: () => {},
+      log: {
+        info: () => {},
+        warn: () => {},
+        error: (obj, msg) => loggedErrors.push({ obj, msg }),
+      },
+    });
+
+    unlinkSync(socketPath);
+
+    const seenRejections: unknown[] = [];
+    const onRejection = (reason: unknown) => seenRejections.push(reason);
+    process.on("unhandledRejection", onRejection);
+
+    try {
+      watchdog.start();
+      // Let the timer fire several times.
+      await new Promise((r) => setTimeout(r, 30));
+      watchdog.stop();
+    } finally {
+      process.off("unhandledRejection", onRejection);
+    }
+
+    expect(seenRejections).toHaveLength(0);
+    expect(loggedErrors.length).toBeGreaterThan(0);
+
+    await closeServer(initial);
+  });
+
+  test("start() polls and rebinds without manual ticking", async () => {
+    harness = buildHarness({ intervalMs: 10 });
+    await startInitialServer(harness);
+    harness.watchdog.start();
+
+    unlinkSync(socketPath);
+
+    // Wait up to 500ms for the timer to recover.
+    const deadline = Date.now() + 500;
+    while (harness.rebinds.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+
+    expect(harness.rebinds).toHaveLength(1);
+    expect(existsSync(socketPath)).toBe(true);
+  });
+
+  test("stop() prevents future rebinds from firing", async () => {
+    harness = buildHarness({ intervalMs: 10 });
+    await startInitialServer(harness);
+    harness.watchdog.start();
+
+    // First recovery cycle.
+    unlinkSync(socketPath);
+    let deadline = Date.now() + 500;
+    while (harness.rebinds.length < 1 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    expect(harness.rebinds).toHaveLength(1);
+
+    harness.watchdog.stop();
+    const stoppedAt = harness.rebinds.length;
+
+    // Unlink again. Wait three intervals; no new rebind should appear.
+    unlinkSync(socketPath);
+    await new Promise((r) => setTimeout(r, 50));
+    expect(harness.rebinds).toHaveLength(stoppedAt);
+    expect(existsSync(socketPath)).toBe(false);
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.ts

@@ -0,0 +1,221 @@
+/**
+ * Resilience helper for Unix-domain-socket IPC servers: re-binds the
+ * listening socket when its on-disk path entry has been removed (e.g. by a
+ * tmpfs sweep or rogue cleanup of `/run/*`).
+ *
+ * Existing connected sockets survive the re-bind because the kernel keeps
+ * connection inodes alive independently of the listener path; only new
+ * `connect()` calls require the path to exist.
+ *
+ * Consumers wire their `Server` reference into the watchdog via callbacks
+ * rather than passing the server directly so the watchdog can guard against
+ * shutdown/restart races mid-rebind.
+ */
+
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import type { Server } from "node:net";
+import { dirname } from "node:path";
+
+/**
+ * Minimal logger surface (pino-compatible). Each method receives a context
+ * object plus an optional human-readable message.
+ */
+export interface SocketWatchdogLogger {
+  info(obj: object, msg?: string): void;
+  warn(obj: object, msg?: string): void;
+  error(obj: object, msg?: string): void;
+}
+
+export interface SocketWatchdogOptions {
+  /** Absolute path to the Unix socket file the consumer is listening on. */
+  socketPath: string;
+  /**
+   * How often to stat the socket path. Set to `0` to disable. Defaults to
+   * 5000ms.
+   */
+  intervalMs?: number;
+  /**
+   * Returns the consumer's current listening server. The watchdog uses this
+   * both as a precondition (no rebind when null) and as a generation marker
+   * to detect shutdown/restart races mid-rebind.
+   */
+  getServer: () => Server | null;
+  /**
+   * Factory for a fresh listening Server. Called by the watchdog when a
+   * rebind is needed; the watchdog drives `.listen(socketPath)` and waits
+   * for the `listening` event before installing.
+   */
+  createServer: () => Server;
+  /**
+   * Invoked when a rebind succeeds. The consumer is responsible for
+   * swapping its primary server reference to `newServer` and disposing of
+   * `oldServer` (typically by tracking it as a legacy listener while
+   * in-flight clients drain, then closing it).
+   */
+  onRebind: (newServer: Server, oldServer: Server) => void;
+  /** Pino-compatible logger. */
+  log: SocketWatchdogLogger;
+}
+
+const DEFAULT_INTERVAL_MS = 5000;
+
+/**
+ * Ensure the directory containing `socketPath` exists. Created with mode
+ * `0o700` so a freshly-spawned dir on a tmpfs mount doesn't leak the IPC
+ * surface to other UIDs. Existing directories keep their permissions —
+ * `mkdir` only applies the mode to directories it creates.
+ */
+export function ensureSocketDir(socketPath: string): void {
+  const socketDir = dirname(socketPath);
+  if (!existsSync(socketDir)) {
+    mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Watchdog that periodically stats a Unix socket file and re-binds the
+ * listener when the path has been removed.
+ *
+ * Lifecycle:
+ *   - Construct with the consumer's callbacks.
+ *   - Call {@link start} after the consumer's initial `listen()` succeeds.
+ *   - Call {@link stop} during shutdown (before closing the underlying
+ *     server) so an in-flight rebind doesn't resurrect the listener.
+ *
+ * The watchdog timer is `unref`-ed so it never keeps the event loop alive
+ * on its own.
+ */
+export class SocketWatchdog {
+  private readonly socketPath: string;
+  private readonly intervalMs: number;
+  private readonly getServer: () => Server | null;
+  private readonly createServer: () => Server;
+  private readonly onRebind: (newServer: Server, oldServer: Server) => void;
+  private readonly log: SocketWatchdogLogger;
+
+  private handle: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: SocketWatchdogOptions) {
+    this.socketPath = options.socketPath;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.getServer = options.getServer;
+    this.createServer = options.createServer;
+    this.onRebind = options.onRebind;
+    this.log = options.log;
+  }
+
+  /**
+   * Begin polling the socket path. No-op if `intervalMs <= 0` or the
+   * watchdog is already running.
+   */
+  start(): void {
+    if (this.intervalMs <= 0 || this.handle !== null) return;
+    this.handle = setInterval(() => {
+      // The async entry path of rebindIfMissing performs filesystem work
+      // (ensureSocketDir, createServer) before its inner try/catch, so a
+      // synchronous throw — e.g. EACCES on a read-only fs — would surface
+      // as an unhandled rejection on every tick. Catch here so the timer
+      // stays quiet on persistent failure modes.
+      this.rebindIfMissing().catch((err) => {
+        this.log.error(
+          { err, path: this.socketPath },
+          "Watchdog rebind failed unexpectedly",
+        );
+      });
+    }, this.intervalMs);
+    this.handle.unref?.();
+  }
+
+  /** Stop the polling timer. Safe to call multiple times. */
+  stop(): void {
+    if (this.handle !== null) {
+      clearInterval(this.handle);
+      this.handle = null;
+    }
+  }
+
+  /**
+   * Re-bind the listening socket if its path entry is missing on disk.
+   *
+   * Public for tests so the watchdog can be exercised deterministically
+   * without waiting for the interval. Returns `true` when a re-bind was
+   * performed, `false` when the socket was already healthy, the consumer
+   * is not running, or a shutdown/restart raced the rebind.
+   */
+  async rebindIfMissing(): Promise<boolean> {
+    const initialServer = this.getServer();
+    if (initialServer === null) return false;
+    if (existsSync(this.socketPath)) return false;
+
+    this.log.warn(
+      { path: this.socketPath },
+      "IPC socket path missing on disk — re-binding listener",
+    );
+
+    ensureSocketDir(this.socketPath);
+
+    const newServer = this.createServer();
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (err: unknown) => {
+          newServer.off("listening", onListening);
+          reject(err);
+        };
+        const onListening = () => {
+          newServer.off("error", onError);
+          resolve();
+        };
+        newServer.once("error", onError);
+        newServer.once("listening", onListening);
+        newServer.listen(this.socketPath);
+      });
+    } catch (err) {
+      this.log.error(
+        { err, path: this.socketPath },
+        "Failed to re-bind IPC socket — will retry on next watchdog tick",
+      );
+      try {
+        newServer.close();
+      } catch {
+        /* ignore */
+      }
+      return false;
+    }
+
+    // Race guard: while we were awaiting listen(), the consumer may have
+    // stopped, restarted, or otherwise replaced its server reference.
+    // Installing newServer would resurrect a listener after shutdown
+    // (keeping the process alive and accepting IPC again). Discard the
+    // new server instead.
+    if (this.getServer() !== initialServer) {
+      try {
+        newServer.close();
+      } catch {
+        /* ignore */
+      }
+      // newServer.listen() recreated the path on disk. If our listen won
+      // the race, the file is sitting there — clean it up so it doesn't
+      // shadow a future start().
+      if (existsSync(this.socketPath)) {
+        try {
+          unlinkSync(this.socketPath);
+        } catch {
+          /* ignore */
+        }
+      }
+      this.log.warn(
+        { path: this.socketPath },
+        "IPC server state changed during rebind — discarded new listener",
+      );
+      return false;
+    }
+
+    this.onRebind(newServer, initialServer);
+
+    this.log.info(
+      { path: this.socketPath },
+      "IPC socket re-bound after path loss",
+    );
+    return true;
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}