@vellumai/assistant 0.8.4 → 0.8.5

package/src/agent/loop.ts

@@ -103,6 +103,14 @@ export type AgentLoopExitReason =
   | "checkpoint_handoff"
   /** Context-window recovery exhausted and the turn ended with an error. */
   | "context_too_large"
+  /**
+   * Auto-compress rerun (post-emergency-compaction, post-tier reducer)
+   * still yielded at the mid-loop budget checkpoint — the turn silently
+   * terminated with no further recovery layer to re-enter. Pure
+   * observability signal so the silent stall is attributable instead of
+   * leaving `agent_loop_exit_reason` NULL.
+   */
+  | "budget_yield_unrecovered"
   /** User cancellation landed after a non-terminal checkpoint yield. */
   | "aborted_after_checkpoint"
   /** Signal aborted while the catch handler was synthesizing an error turn. */

package/src/api/README.md

@@ -0,0 +1,5 @@
+# @vellumai/assistant-api
+
+Public API surface for consumers of the assistant API (web client, gateway,
+evals, future external clients). This directory is the **source of truth** for
+the wire contracts the assistant exposes: schemas, types, and pure helpers.

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export {
+  type RelationshipStateUpdated,
+  RelationshipStateUpdatedSchema,
+} from "../events/relationship-state-updated.js";

package/src/api/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@vellumai/assistant-api",
+  "version": "0.0.0-source",
+  "description": "Public API surface for consumers of the assistant API (web client, gateway, evals, etc.).",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/src/background-wake/background-wake-routes.test.ts

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { BackgroundWakeIntent } from "./next-wake.js";
+import {
+  clearBackgroundWakeRuntime,
+  registerBackgroundWakeRuntime,
+} from "./runtime-registry.js";
+
+type MockIntent = BackgroundWakeIntent;
+
+let computedIntent: MockIntent | null;
+let computeCalls: number;
+
+const { ROUTES, setBackgroundWakeIntentComputerForTest } =
+  await import("../runtime/routes/background-wake-routes.js");
+
+function findHandler(operationId: string) {
+  const route = ROUTES.find(
+    (candidate) => candidate.operationId === operationId,
+  );
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+const NOW = 1_800_000_000_000;
+
+describe("background wake runtime routes", () => {
+  beforeEach(() => {
+    clearBackgroundWakeRuntime();
+    computeCalls = 0;
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 10 * 60_000 });
+    setBackgroundWakeIntentComputerForTest(() => {
+      computeCalls += 1;
+      return computedIntent;
+    });
+  });
+
+  afterEach(() => {
+    setBackgroundWakeIntentComputerForTest(null);
+  });
+
+  test("intent route returns the current computed wake intent", async () => {
+    const handler = findHandler("getBackgroundWakeIntent");
+
+    expect(await handler({})).toEqual({ intent: computedIntent });
+    expect(computeCalls).toBe(1);
+  });
+
+  test("intent route returns null when no wake intent exists", async () => {
+    computedIntent = null;
+    const handler = findHandler("getBackgroundWakeIntent");
+
+    expect(await handler({})).toEqual({ intent: null });
+  });
+
+  test("prepare-sleep defers when the next wake is inside the local window", async () => {
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 30_000 });
+    const handler = findHandler("prepareBackgroundWakeSleep");
+
+    expect(await handler({})).toEqual({
+      intent: computedIntent,
+      deferSleep: true,
+    });
+  });
+
+  test("prepare-sleep allows sleep when the next wake is outside the local window", async () => {
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 5 * 60_000 });
+    const handler = findHandler("prepareBackgroundWakeSleep");
+
+    expect(await handler({})).toEqual({
+      intent: computedIntent,
+      deferSleep: false,
+    });
+  });
+
+  test("drain-due fails when the runtime registry is missing", async () => {
+    const handler = findHandler("drainDueBackgroundWake");
+
+    await expect(handler({ body: drainBodyFixture() })).rejects.toThrow(
+      "Background wake runtime is not registered",
+    );
+  });
+
+  test("drain-due invokes due heartbeat and scheduler work", async () => {
+    const heartbeatRunOnce = mock(async () => true);
+    const schedulerRunOnce = mock(async () => 2);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: Date.now() - 1,
+        runOnce: heartbeatRunOnce,
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    computedIntent = intentFixture({
+      nextWakeAt: NOW + 60_000,
+      sourceGeneration: "next-generation",
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = await handler({ body: drainBodyFixture() });
+
+    expect(heartbeatRunOnce).toHaveBeenCalledTimes(1);
+    expect(heartbeatRunOnce).toHaveBeenCalledWith();
+    expect(schedulerRunOnce).toHaveBeenCalledTimes(1);
+    expect(response).toEqual({
+      leaseId: "lease-123",
+      reason: "schedule",
+      sourceGeneration: "source-generation",
+      startedAt: NOW,
+      deadlineAt: NOW + 30_000,
+      counts: {
+        heartbeat: 1,
+        scheduler: 2,
+        total: 3,
+      },
+      nextIntent: computedIntent,
+    });
+  });
+
+  test("drain-due skips heartbeat when it is not due and reports no scheduler work", async () => {
+    const heartbeatRunOnce = mock(async () => true);
+    const schedulerRunOnce = mock(async () => 0);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: Date.now() + 5 * 60_000,
+        runOnce: heartbeatRunOnce,
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = (await handler({ body: drainBodyFixture() })) as {
+      counts: { heartbeat: number; scheduler: number; total: number };
+    };
+
+    expect(heartbeatRunOnce).not.toHaveBeenCalled();
+    expect(schedulerRunOnce).toHaveBeenCalledTimes(1);
+    expect(response.counts).toEqual({
+      heartbeat: 0,
+      scheduler: 0,
+      total: 0,
+    });
+  });
+
+  test("drain-due recomputes the next intent after due work drains", async () => {
+    const recomputedIntent = intentFixture({
+      nextWakeAt: NOW + 2 * 60_000,
+      sourceGeneration: "after-drain",
+    });
+    const schedulerRunOnce = mock(async () => {
+      computedIntent = recomputedIntent;
+      return 1;
+    });
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: null,
+        runOnce: mock(async () => true),
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = (await handler({ body: drainBodyFixture() })) as {
+      nextIntent: MockIntent | null;
+    };
+
+    expect(response.nextIntent).toEqual(recomputedIntent);
+  });
+
+  test("drain-due accepts vembda snake_case payload aliases", async () => {
+    const schedulerRunOnce = mock(async () => 0);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: null,
+        runOnce: mock(async () => false),
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = await handler({
+      body: {
+        lease_id: "lease-snake",
+        reason: "refresh",
+        source_generation: "generation-snake",
+        started_at: new Date(NOW).toISOString(),
+        deadline_at: String(NOW + 30_000),
+      },
+    });
+
+    expect(response).toMatchObject({
+      leaseId: "lease-snake",
+      reason: "refresh",
+      sourceGeneration: "generation-snake",
+      startedAt: NOW,
+      deadlineAt: NOW + 30_000,
+    });
+  });
+});
+
+function drainBodyFixture() {
+  return {
+    leaseId: "lease-123",
+    reason: "schedule",
+    sourceGeneration: "source-generation",
+    startedAt: NOW,
+    deadlineAt: NOW + 30_000,
+  };
+}
+
+function intentFixture(overrides: Partial<MockIntent>): MockIntent {
+  const nextWakeAt = overrides.nextWakeAt ?? NOW + 60_000;
+  return {
+    nextWakeAt,
+    actualNextDueAt: nextWakeAt,
+    reason: "schedule",
+    sourceGeneration: "source-generation",
+    computedAt: NOW - 1_000,
+    sourcePayload: {
+      heartbeat: null,
+      schedules: [],
+    },
+    ...overrides,
+  };
+}

package/src/background-wake/runtime-registry.ts

@@ -0,0 +1,24 @@
+import type { HeartbeatService } from "../heartbeat/heartbeat-service.js";
+import type { SchedulerHandle } from "../schedule/scheduler.js";
+
+export interface BackgroundWakeRuntime {
+  scheduler: Pick<SchedulerHandle, "runOnce">;
+  heartbeat: Pick<HeartbeatService, "nextRunAt" | "runOnce">;
+}
+
+let runtime: BackgroundWakeRuntime | null = null;
+
+export function registerBackgroundWakeRuntime(
+  nextRuntime: BackgroundWakeRuntime,
+): void {
+  runtime = nextRuntime;
+}
+
+export function getBackgroundWakeRuntime(): BackgroundWakeRuntime | null {
+  return runtime;
+}
+
+/** @internal Test helper for module-level route state. */
+export function clearBackgroundWakeRuntime(): void {
+  runtime = null;
+}

package/src/cli/commands/__tests__/browser.test.ts

@@ -131,26 +131,44 @@ beforeEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("subcommand registration", () => {
-  test("registers exactly 17 subcommands", () => {
+  test("registers one direct subcommand per BROWSER_OPERATIONS entry plus 'tabs' group", () => {
     const program = new Command();
     registerBrowserCommand(program);
     const browser = program.commands.find((c) => c.name() === "browser");
     expect(browser).toBeDefined();
-    const subcommands = browser!.commands;
-    expect(subcommands).toHaveLength(17);
+    // 17 operation commands + 1 'tabs' grouping subcommand
+    expect(browser!.commands).toHaveLength(BROWSER_OPERATIONS.length + 1);
   });
 
-  test("subcommand names match kebab-cased BROWSER_OPERATIONS", () => {
+  test("operation subcommand names match kebab-cased BROWSER_OPERATIONS", () => {
     const program = new Command();
     registerBrowserCommand(program);
     const browser = program.commands.find((c) => c.name() === "browser");
-    const subcommandNames = browser!.commands.map((c) => c.name()).sort();
+    // Filter out the 'tabs' grouping subcommand — it's not a BROWSER_OPERATIONS entry.
+    const subcommandNames = browser!.commands
+      .filter((c) => c.name() !== "tabs")
+      .map((c) => c.name())
+      .sort();
     const expectedNames = BROWSER_OPERATIONS.map((op) =>
       op.replace(/_/g, "-"),
     ).sort();
     expect(subcommandNames).toEqual(expectedNames);
   });
 
+  test("registers 'tabs' subcommand group with list/select/new/close", () => {
+    const program = new Command();
+    registerBrowserCommand(program);
+    const browser = program.commands.find((c) => c.name() === "browser");
+    const tabs = browser!.commands.find((c) => c.name() === "tabs");
+    expect(tabs).toBeDefined();
+    expect(tabs!.commands.map((c) => c.name()).sort()).toEqual([
+      "close",
+      "list",
+      "new",
+      "select",
+    ]);
+  });
+
   test("all 17 operations from BROWSER_OPERATIONS are covered", () => {
     expect(BROWSER_OPERATIONS).toHaveLength(17);
     expect(BROWSER_OPERATION_META).toHaveLength(17);

package/src/cli/commands/__tests__/domain-register.test.ts

@@ -204,4 +204,114 @@ describe("assistant domain register", () => {
     await runDomainCommand("domain", "register", "velly");
     expect(process.exitCode).not.toBe(0);
   });
+
+  test("--email-username is included in IPC body", async () => {
+    mockIpcCallFn = mock(() =>
+      Promise.resolve({
+        ok: true,
+        result: {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          domain: "velly.vellum.me",
+          status: "active",
+          verified: true,
+        },
+      }),
+    );
+
+    await runDomainCommand(
+      "domain",
+      "register",
+      "velly",
+      "--email-username",
+      "hello",
+    );
+
+    expect(mockIpcCallFn).toHaveBeenCalledWith("domain_register", {
+      body: { subdomain: "velly", email_username: "hello" },
+    });
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("email error in response is surfaced as warning", async () => {
+    mockIpcCallFn = mock(() =>
+      Promise.resolve({
+        ok: true,
+        result: {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          domain: "velly.vellum.me",
+          status: "active",
+          verified: true,
+          email_error: {
+            detail: "MX records not ready",
+            code: "email_setup_failed",
+          },
+        },
+      }),
+    );
+
+    await runDomainCommand(
+      "domain",
+      "register",
+      "velly",
+      "--email-username",
+      "hello",
+    );
+
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("--json includes email_error in output", async () => {
+    mockIpcCallFn = mock(() =>
+      Promise.resolve({
+        ok: true,
+        result: {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          domain: "velly.vellum.me",
+          status: "active",
+          verified: true,
+          email_error: {
+            detail: "MX records not ready",
+            code: "email_setup_failed",
+          },
+        },
+      }),
+    );
+
+    const output = await runDomainCommand(
+      "domain",
+      "--json",
+      "register",
+      "velly",
+      "--email-username",
+      "hello",
+    );
+
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.email_error).toEqual({
+      detail: "MX records not ready",
+      code: "email_setup_failed",
+    });
+    expect(process.exitCode).toBe(0);
+  });
+
+  test("without --email-username behavior is unchanged", async () => {
+    mockIpcCallFn = mock(() =>
+      Promise.resolve({
+        ok: true,
+        result: {
+          id: "550e8400-e29b-41d4-a716-446655440000",
+          domain: "velly.vellum.me",
+          status: "active",
+          verified: true,
+        },
+      }),
+    );
+
+    await runDomainCommand("domain", "register", "velly");
+
+    expect(mockIpcCallFn).toHaveBeenCalledWith("domain_register", {
+      body: { subdomain: "velly" },
+    });
+    expect(process.exitCode).toBe(0);
+  });
 });

package/src/cli/commands/__tests__/domain-status.test.ts

@@ -2,9 +2,9 @@
  * Tests for the domain status CLI subcommand (thin IPC wrapper).
  *
  * Validates:
- *   - status calls domain_status
+ *   - status calls domain_status then domain_verification_status
  *   - --json outputs structured response
- *   - no domain shows helpful message
+ *   - unknown subdomain shows helpful message
  *   - error responses are surfaced correctly
  */
 
@@ -99,15 +99,16 @@ async function runDomainCommand(...args: string[]) {
 // status
 // ---------------------------------------------------------------------------
 
-describe("assistant domain status", () => {
-  test("calls domain_status", async () => {
-    mockIpcCallFn = mock(() =>
-      Promise.resolve({
+function mockDomainStatusWithVerification() {
+  mockIpcCallFn = mock((method: string) => {
+    if (method === "domain_status") {
+      return Promise.resolve({
         ok: true,
         result: {
           results: [
             {
               id: "550e8400-e29b-41d4-a716-446655440000",
+              subdomain: "becky",
               domain: "becky.vellum.me",
               status: "active",
               verified: true,
@@ -115,38 +116,37 @@ describe("assistant domain status", () => {
             },
           ],
         },
-      }),
-    );
+      });
+    }
+    return Promise.resolve({
+      ok: true,
+      result: {
+        domain: "becky.vellum.me",
+        status: "verified",
+        message: "DNS records have been verified.",
+      },
+    });
+  }) as unknown as typeof mockIpcCallFn;
+}
 
-    await runDomainCommand("domain", "status");
+describe("assistant domain status", () => {
+  test("calls domain_status and domain_verification_status", async () => {
+    mockDomainStatusWithVerification();
 
-    expect(mockIpcCallFn).toHaveBeenCalledWith("domain_status");
+    await runDomainCommand("domain", "status", "becky");
+
+    expect(mockIpcCallFn).toHaveBeenCalledTimes(2);
     expect(process.exitCode).toBe(0);
   });
 
   test("--json outputs structured response", async () => {
-    mockIpcCallFn = mock(() =>
-      Promise.resolve({
-        ok: true,
-        result: {
-          results: [
-            {
-              id: "550e8400-e29b-41d4-a716-446655440000",
-              domain: "becky.vellum.me",
-              status: "active",
-              verified: true,
-              created_at: "2026-04-15T19:00:00Z",
-            },
-          ],
-        },
-      }),
-    );
+    mockDomainStatusWithVerification();
 
-    const output = await runDomainCommand("domain", "--json", "status");
+    const output = await runDomainCommand("domain", "--json", "status", "becky");
 
     const parsed = JSON.parse(output.trim());
-    expect(parsed.results).toHaveLength(1);
-    expect(parsed.results[0].domain).toBe("becky.vellum.me");
+    expect(parsed.domain.domain).toBe("becky.vellum.me");
+    expect(parsed.verification.status).toBe("verified");
     expect(process.exitCode).toBe(0);
   });
 
@@ -158,8 +158,8 @@ describe("assistant domain status", () => {
       }),
     );
 
-    await runDomainCommand("domain", "status");
-    expect(process.exitCode).toBe(0);
+    await runDomainCommand("domain", "status", "becky");
+    expect(process.exitCode).toBe(1);
   });
 
   test("IPC error with --json outputs error envelope", async () => {
@@ -171,7 +171,7 @@ describe("assistant domain status", () => {
       }),
     ) as unknown as typeof mockIpcCallFn;
 
-    const output = await runDomainCommand("domain", "--json", "status");
+    const output = await runDomainCommand("domain", "--json", "status", "becky");
 
     expect(process.exitCode).not.toBe(0);
     const parsed = JSON.parse(output.trim());
@@ -187,7 +187,7 @@ describe("assistant domain status", () => {
       }),
     ) as unknown as typeof mockIpcCallFn;
 
-    await runDomainCommand("domain", "status");
+    await runDomainCommand("domain", "status", "becky");
     expect(process.exitCode).not.toBe(0);
   });
 });