@vellumai/cli 0.10.12 → 0.11.0-dev.202607290139.f1746d4

package/src/__tests__/drain.test.ts

@@ -0,0 +1,337 @@
+import { describe, expect, test } from "bun:test";
+
+import { drainAssistant, parseWaitDuration } from "../lib/drain.js";
+
+const BASE = "http://127.0.0.1:7823";
+
+interface RecordedCall {
+  url: string;
+  method: string;
+}
+
+/**
+ * Fetch stub: routes requests through `handler` and records every call.
+ * Throwing from the handler simulates a network failure.
+ */
+function fetchStub(
+  handler: (url: string, method: string) => Response | Promise<Response>,
+): {
+  impl: (url: string, init?: RequestInit) => Promise<Response>;
+  calls: RecordedCall[];
+} {
+  const calls: RecordedCall[] = [];
+  const impl = async (url: string, init?: RequestInit): Promise<Response> => {
+    const method = init?.method ?? "GET";
+    calls.push({ url, method });
+    return handler(url, method);
+  };
+  return { impl, calls };
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function busyStatus(): unknown {
+  return {
+    quiescedUntil: Date.now() + 60_000,
+    idle: false,
+    activeConversations: [],
+    memoryJobs: [
+      { id: "job-1", type: "memory_retrospective", startedAt: Date.now() },
+    ],
+    scheduleRuns: [],
+    workflowRuns: [],
+    heartbeatRuns: [],
+  };
+}
+
+function workflowBusyStatus(): unknown {
+  return {
+    quiescedUntil: Date.now() + 60_000,
+    idle: false,
+    activeConversations: [],
+    memoryJobs: [],
+    scheduleRuns: [],
+    workflowRuns: [
+      { runId: "wf-1", name: "nightly-report", startedAt: Date.now() },
+    ],
+    heartbeatRuns: [],
+  };
+}
+
+function idleStatus(): unknown {
+  return {
+    quiescedUntil: Date.now() + 60_000,
+    idle: true,
+    activeConversations: [],
+    memoryJobs: [],
+    scheduleRuns: [],
+    workflowRuns: [],
+    heartbeatRuns: [],
+  };
+}
+
+function idleExpiredLeaseStatus(): unknown {
+  return { ...(idleStatus() as Record<string, unknown>), quiescedUntil: null };
+}
+
+describe("parseWaitDuration", () => {
+  test("parses bare seconds, seconds, and minutes", () => {
+    expect(parseWaitDuration("90")).toBe(90_000);
+    expect(parseWaitDuration("90s")).toBe(90_000);
+    expect(parseWaitDuration("10m")).toBe(600_000);
+    expect(parseWaitDuration(" 5s ")).toBe(5_000);
+  });
+
+  test("rejects invalid durations", () => {
+    expect(parseWaitDuration("0")).toBeNull();
+    expect(parseWaitDuration("abc")).toBeNull();
+    expect(parseWaitDuration("5x")).toBeNull();
+    expect(parseWaitDuration("-5")).toBeNull();
+    expect(parseWaitDuration("")).toBeNull();
+  });
+});
+
+describe("drainAssistant", () => {
+  test("arms the lease, narrates, and returns drained when work finishes", async () => {
+    let statusCalls = 0;
+    const { impl, calls } = fetchStub((url, method) => {
+      if (url.endsWith("/v1/lifecycle/quiesce") && method === "POST") {
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      statusCalls += 1;
+      return jsonResponse(statusCalls < 3 ? busyStatus() : idleStatus());
+    });
+    const lines: string[] = [];
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: (line) => lines.push(line),
+    });
+
+    expect(outcome).toBe("drained");
+    expect(calls[0]).toEqual({
+      url: `${BASE}/v1/lifecycle/quiesce`,
+      method: "POST",
+    });
+    expect(lines.join("\n")).toContain("memory memory_retrospective");
+  });
+
+  test("a running workflow keeps the drain busy and is narrated", async () => {
+    let statusCalls = 0;
+    const { impl } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      statusCalls += 1;
+      return jsonResponse(
+        statusCalls < 2 ? workflowBusyStatus() : idleStatus(),
+      );
+    });
+    const lines: string[] = [];
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: (line) => lines.push(line),
+    });
+
+    expect(outcome).toBe("drained");
+    expect(lines.join("\n")).toContain('workflow "nightly-report"');
+  });
+
+  test("a single idle snapshot is not enough — drained needs two in a row", async () => {
+    let statusCalls = 0;
+    const sequence = [idleStatus(), busyStatus(), idleStatus(), idleStatus()];
+    const { impl } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      const status = sequence[Math.min(statusCalls, sequence.length - 1)];
+      statusCalls += 1;
+      return jsonResponse(status);
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("drained");
+    // idle, busy (streak reset), idle, idle — four reads, not one.
+    expect(statusCalls).toBe(4);
+  });
+
+  test("idle without a live lease re-arms instead of counting toward drained", async () => {
+    let statusCalls = 0;
+    let armCalls = 0;
+    const { impl } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        armCalls += 1;
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      statusCalls += 1;
+      // The lease has lapsed on the first idle read; once re-armed, the
+      // subsequent idle reads carry a live lease.
+      return jsonResponse(
+        statusCalls === 1 ? idleExpiredLeaseStatus() : idleStatus(),
+      );
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("drained");
+    // Initial arm + the re-arm triggered by the lapsed lease.
+    expect(armCalls).toBeGreaterThanOrEqual(2);
+    // The expired-lease idle read did not count: two live-lease reads follow.
+    expect(statusCalls).toBeGreaterThanOrEqual(3);
+  });
+
+  test("an unmaintainable lease fails the drain instead of trusting idle", async () => {
+    let armCalls = 0;
+    const { impl } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        armCalls += 1;
+        if (armCalls === 1) {
+          return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+        }
+        return jsonResponse({ error: "boom" }, 500);
+      }
+      return jsonResponse(idleExpiredLeaseStatus());
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("unreachable");
+  });
+
+  test("returns unsupported when the assistant lacks the quiesce route", async () => {
+    const { impl } = fetchStub(() => jsonResponse({ error: "nope" }, 404));
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("unsupported");
+  });
+
+  test("returns unreachable when the initial lease request fails", async () => {
+    const { impl } = fetchStub(() => {
+      throw new Error("connection refused");
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("unreachable");
+  });
+
+  test("returns timeout when the deadline passes while still busy", async () => {
+    const { impl } = fetchStub((_url, method) =>
+      method === "POST"
+        ? jsonResponse({ quiescedUntil: Date.now() + 60_000 })
+        : jsonResponse(busyStatus()),
+    );
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: Date.now() + 40,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("timeout");
+  });
+
+  test("returns unreachable after sustained status failures", async () => {
+    const { impl } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      throw new Error("boom");
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("unreachable");
+  });
+
+  test("cancel releases the lease and returns cancelled", async () => {
+    const controller = new AbortController();
+    const { impl, calls } = fetchStub((_url, method) => {
+      if (method === "POST") {
+        return jsonResponse({ quiescedUntil: Date.now() + 60_000 });
+      }
+      if (method === "DELETE") {
+        return jsonResponse({ released: true });
+      }
+      // First busy status arrives, then the user hits Ctrl-C.
+      controller.abort();
+      return jsonResponse(busyStatus());
+    });
+
+    const outcome = await drainAssistant({
+      baseUrl: BASE,
+      token: "tok",
+      deadlineAt: null,
+      pollIntervalMs: 1,
+      fetchImpl: impl,
+      signal: controller.signal,
+      log: () => {},
+    });
+
+    expect(outcome).toBe("cancelled");
+    expect(
+      calls.some(
+        (c) => c.method === "DELETE" && c.url.endsWith("/v1/lifecycle/quiesce"),
+      ),
+    ).toBe(true);
+  });
+});

package/src/__tests__/flags.test.ts

@@ -83,7 +83,7 @@ describe("vellum flags --assistant routing", () => {
       fetchCalls.push({ url, method });
       if (method === "PATCH") {
         return jsonResponse({
-          key: "voice-mode",
+          key: "browser",
           enabled: true,
           defaultEnabled: false,
           label: "Voice Mode",
@@ -133,7 +133,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "voice-mode",
+      "browser",
       "true",
       "--assistant",
       "Bob",
@@ -146,7 +146,7 @@ describe("vellum flags --assistant routing", () => {
     // bob-2 has assistantId.length === 5, so port = 7800 + 5 = 7805.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7805");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/voice-mode",
+      "/v1/assistants/bob-2/feature-flags/browser",
     );
   });
 
@@ -166,7 +166,7 @@ describe("vellum flags --assistant routing", () => {
       "--assistant",
       "Bob",
       "set",
-      "voice-mode",
+      "browser",
       "true",
     ];
 
@@ -174,7 +174,7 @@ describe("vellum flags --assistant routing", () => {
 
     expect(fetchCalls.length).toBe(1);
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/bob-2/feature-flags/voice-mode",
+      "/v1/assistants/bob-2/feature-flags/browser",
     );
   });
 
@@ -188,7 +188,7 @@ describe("vellum flags --assistant routing", () => {
       ],
       "alice-1",
     );
-    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    process.argv = ["bun", "vellum", "flags", "set", "browser", "true"];
 
     await flags();
 
@@ -196,7 +196,7 @@ describe("vellum flags --assistant routing", () => {
     // alice-1 has assistantId.length === 7, so port = 7800 + 7 = 7807.
     expect(fetchCalls[0].url).toContain("http://127.0.0.1:7807");
     expect(fetchCalls[0].url).toContain(
-      "/v1/assistants/alice-1/feature-flags/voice-mode",
+      "/v1/assistants/alice-1/feature-flags/browser",
     );
   });
 
@@ -207,7 +207,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "voice-mode",
+      "browser",
       "true",
       "--assistant",
       "Ghost",
@@ -227,7 +227,7 @@ describe("vellum flags --assistant routing", () => {
       "vellum",
       "flags",
       "set",
-      "voice-mode",
+      "browser",
       "true",
       "--assistant",
     ];
@@ -298,14 +298,14 @@ describe("vellum flags cross-environment hint", () => {
   test("gateway-unreachable error gains the hint when another env has assistants", async () => {
     writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
     seedDevAssistant();
-    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    process.argv = ["bun", "vellum", "flags", "set", "browser", "true"];
     await expect(flags()).rejects.toThrow(/Install vellum Command/);
   });
 
   test("gateway-unreachable error stays bare when no other env has assistants", async () => {
     writeLockfile([makeEntry("alice-1", { name: "Alice" })], "alice-1");
     // xdgDataHome is empty — detection finds nothing, so the message is intact.
-    process.argv = ["bun", "vellum", "flags", "set", "voice-mode", "true"];
+    process.argv = ["bun", "vellum", "flags", "set", "browser", "true"];
     let error: Error | undefined;
     try {
       await flags();

package/src/__tests__/local-hatch-lock.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import {
+  resolveLocalHatchLockPath,
+  withLocalHatchLock,
+} from "../lib/local-hatch-lock.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const tempDir of tempDirs.splice(0)) {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+function makeLockPath(): string {
+  const tempDir = mkdtempSync(join(tmpdir(), "vellum-hatch-lock-test-"));
+  tempDirs.push(tempDir);
+  return join(tempDir, "local-hatch.lock");
+}
+
+describe("withLocalHatchLock", () => {
+  test("uses the same machine lock when callers have different temp directories", () => {
+    const originalTmpDir = process.env.TMPDIR;
+    const firstTmpDir = mkdtempSync(join(tmpdir(), "vellum-tmp-a-"));
+    const secondTmpDir = mkdtempSync(join(tmpdir(), "vellum-tmp-b-"));
+    tempDirs.push(firstTmpDir, secondTmpDir);
+
+    try {
+      process.env.TMPDIR = firstTmpDir;
+      const firstPath = resolveLocalHatchLockPath();
+      process.env.TMPDIR = secondTmpDir;
+      const secondPath = resolveLocalHatchLockPath();
+
+      expect(secondPath).toBe(firstPath);
+      expect(firstPath.startsWith(firstTmpDir)).toBe(false);
+      expect(firstPath.startsWith(secondTmpDir)).toBe(false);
+    } finally {
+      if (originalTmpDir === undefined) {
+        delete process.env.TMPDIR;
+      } else {
+        process.env.TMPDIR = originalTmpDir;
+      }
+    }
+  });
+
+  test("serializes startup work that shares the machine-wide lock", async () => {
+    const lockPath = makeLockPath();
+    let releaseFirst!: () => void;
+    let firstStarted!: () => void;
+    const firstStartedPromise = new Promise<void>((resolve) => {
+      firstStarted = resolve;
+    });
+    const firstReleasePromise = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    let secondEntered = false;
+
+    const first = withLocalHatchLock(
+      async () => {
+        firstStarted();
+        await firstReleasePromise;
+      },
+      { lockPath, timeoutMs: 1_000, retryMs: 5 },
+    );
+    await firstStartedPromise;
+
+    const second = withLocalHatchLock(
+      async () => {
+        secondEntered = true;
+      },
+      { lockPath, timeoutMs: 1_000, retryMs: 5 },
+    );
+    await Bun.sleep(20);
+    expect(secondEntered).toBe(false);
+
+    releaseFirst();
+    await Promise.all([first, second]);
+
+    expect(secondEntered).toBe(true);
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers a lock owned by a dead process", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({ pid: 2_147_483_647, token: "stale-owner" }) + "\n",
+    );
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers an expired lock even when its PID has been reused", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({
+        pid: process.pid,
+        processStartedAt: "not-the-current-process",
+        token: "reused-pid-owner",
+      }) + "\n",
+    );
+    const expired = new Date(Date.now() - 300_000);
+    utimesSync(lockPath, expired, expired);
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      liveOwnerRecoveryGraceMs: 0,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("recovers a fresh lock when its PID has been reused", async () => {
+    const lockPath = makeLockPath();
+    writeFileSync(
+      lockPath,
+      JSON.stringify({
+        pid: process.pid,
+        processStartedAt: "not-the-current-process",
+        token: "fresh-reused-pid-owner",
+      }) + "\n",
+    );
+
+    const result = await withLocalHatchLock(async () => "started", {
+      lockPath,
+      timeoutMs: 1_000,
+      retryMs: 5,
+    });
+
+    expect(result).toBe("started");
+    expect(existsSync(lockPath)).toBe(false);
+  });
+
+  test("releases the lock when startup fails", async () => {
+    const lockPath = makeLockPath();
+
+    await expect(
+      withLocalHatchLock(
+        async () => {
+          throw new Error("startup failed");
+        },
+        { lockPath },
+      ),
+    ).rejects.toThrow("startup failed");
+
+    expect(existsSync(lockPath)).toBe(false);
+  });
+});