@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -0,0 +1,289 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+type MockHeartbeatConfig = {
+  enabled: boolean;
+  intervalMs: number;
+  cronExpression: string | null;
+  timezone: string | null;
+  activeHoursStart: number | null;
+  activeHoursEnd: number | null;
+  maxConsecutiveRuns: number | null;
+};
+
+type MockSchedule = {
+  id: string;
+  nextRunAt: number;
+  enabled: boolean;
+  mode: "notify" | "execute" | "script" | "wake";
+  createdBy: string;
+  status: "active" | "firing" | "fired" | "cancelled";
+  syntax: "cron" | "rrule";
+  expression: string | null;
+  timezone: string | null;
+  updatedAt: number;
+};
+
+let heartbeatConfig: MockHeartbeatConfig;
+let heartbeatNextRunAt: number | null;
+let schedules: MockSchedule[];
+let computedCronNextRunAt: number;
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    heartbeat: heartbeatConfig,
+  }),
+}));
+
+mock.module("../heartbeat/heartbeat-service.js", () => ({
+  HeartbeatService: {
+    getInstance: () =>
+      heartbeatNextRunAt == null
+        ? undefined
+        : { nextRunAt: heartbeatNextRunAt },
+  },
+}));
+
+mock.module("../schedule/recurrence-engine.js", () => ({
+  computeNextRunAt: () => computedCronNextRunAt,
+}));
+
+mock.module("../schedule/schedule-store.js", () => ({
+  listSchedules: (options?: { enabledOnly?: boolean }) =>
+    options?.enabledOnly
+      ? schedules.filter((schedule) => schedule.enabled)
+      : schedules,
+}));
+
+const { computeNextBackgroundWakeIntent } = await import("./next-wake.js");
+
+const NOW = 1_800_000_000_000;
+
+describe("computeNextBackgroundWakeIntent", () => {
+  beforeEach(() => {
+    heartbeatConfig = {
+      enabled: true,
+      intervalMs: 30 * 60_000,
+      cronExpression: null,
+      timezone: null,
+      activeHoursStart: 8,
+      activeHoursEnd: 22,
+      maxConsecutiveRuns: 3,
+    };
+    heartbeatNextRunAt = null;
+    schedules = [];
+    computedCronNextRunAt = NOW + 3_600_000;
+  });
+
+  test("returns heartbeat-only interval wake intent", () => {
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(NOW + heartbeatConfig.intervalMs);
+    expect(intent!.actualNextDueAt).toBe(NOW + heartbeatConfig.intervalMs);
+    expect(intent!.reason).toBe("heartbeat");
+    expect(intent!.sourcePayload.heartbeat).toMatchObject({
+      nextRunAt: NOW + heartbeatConfig.intervalMs,
+      mode: "interval",
+      intervalMs: heartbeatConfig.intervalMs,
+      cronExpression: null,
+    });
+    expect(intent!.sourcePayload.schedules).toEqual([]);
+  });
+
+  test("uses the running heartbeat service next run when available", () => {
+    heartbeatNextRunAt = NOW + 12_345;
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(heartbeatNextRunAt);
+    expect(intent!.actualNextDueAt).toBe(heartbeatNextRunAt);
+    expect(intent!.reason).toBe("heartbeat");
+  });
+
+  test("returns heartbeat-only cron wake intent", () => {
+    heartbeatConfig.cronExpression = "0 9 * * *";
+    heartbeatConfig.timezone = "America/New_York";
+    computedCronNextRunAt = NOW + 42_000;
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(computedCronNextRunAt);
+    expect(intent!.reason).toBe("heartbeat");
+    expect(intent!.sourcePayload.heartbeat).toMatchObject({
+      nextRunAt: computedCronNextRunAt,
+      mode: "cron",
+      cronExpression: "0 9 * * *",
+      timezone: "America/New_York",
+    });
+  });
+
+  test("returns schedule-only wake intent", () => {
+    heartbeatConfig.enabled = false;
+    schedules = [
+      scheduleFixture({
+        id: "schedule-later",
+        nextRunAt: NOW + 60_000,
+      }),
+      scheduleFixture({
+        id: "schedule-sooner",
+        nextRunAt: NOW + 30_000,
+      }),
+    ];
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(NOW + 30_000);
+    expect(intent!.actualNextDueAt).toBe(NOW + 30_000);
+    expect(intent!.reason).toBe("schedule");
+    expect(intent!.sourcePayload.heartbeat).toBeNull();
+    expect(intent!.sourcePayload.schedules.map((s) => s.id)).toEqual([
+      "schedule-sooner",
+      "schedule-later",
+    ]);
+  });
+
+  test("includes defer-created wake schedules", () => {
+    heartbeatConfig.enabled = false;
+    schedules = [
+      scheduleFixture({
+        id: "defer-wake",
+        nextRunAt: NOW + 10_000,
+        mode: "wake",
+        createdBy: "defer",
+      }),
+    ];
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(NOW + 10_000);
+    expect(intent!.sourcePayload.schedules).toEqual([
+      expect.objectContaining({
+        id: "defer-wake",
+        mode: "wake",
+        createdBy: "defer",
+      }),
+    ]);
+  });
+
+  test("returns mixed when heartbeat and schedule are co-due", () => {
+    heartbeatNextRunAt = NOW + 50_000;
+    schedules = [
+      scheduleFixture({
+        id: "co-due",
+        nextRunAt: NOW + 50_000,
+      }),
+    ];
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.nextWakeAt).toBe(NOW + 50_000);
+    expect(intent!.actualNextDueAt).toBe(NOW + 50_000);
+    expect(intent!.reason).toBe("mixed");
+  });
+
+  test("ignores disabled heartbeat and disabled schedules", () => {
+    heartbeatConfig.enabled = false;
+    schedules = [
+      scheduleFixture({
+        id: "disabled",
+        enabled: false,
+        nextRunAt: NOW + 10_000,
+      }),
+    ];
+
+    expect(computeNextBackgroundWakeIntent(NOW)).toBeNull();
+  });
+
+  test("ignores inactive enabled schedules", () => {
+    heartbeatConfig.enabled = false;
+    schedules = [
+      scheduleFixture({
+        id: "fired",
+        status: "fired",
+        nextRunAt: NOW + 10_000,
+      }),
+      scheduleFixture({
+        id: "zero",
+        nextRunAt: 0,
+      }),
+    ];
+
+    expect(computeNextBackgroundWakeIntent(NOW)).toBeNull();
+  });
+
+  test("reports far-future due work without applying storage horizon", () => {
+    heartbeatConfig.enabled = false;
+    const actualNextDueAt = NOW + 45 * 24 * 60 * 60 * 1000;
+    schedules = [
+      scheduleFixture({
+        id: "far-future",
+        nextRunAt: actualNextDueAt,
+      }),
+    ];
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    expect(intent).not.toBeNull();
+    expect(intent!.reason).toBe("schedule");
+    expect(intent!.actualNextDueAt).toBe(actualNextDueAt);
+    expect(intent!.nextWakeAt).toBe(actualNextDueAt);
+  });
+
+  test("sets computedAt to the local snapshot time", () => {
+    heartbeatConfig.enabled = false;
+    schedules = [
+      scheduleFixture({
+        id: "scheduled",
+        nextRunAt: NOW + 10_000,
+      }),
+    ];
+    const before = Date.now();
+
+    const intent = computeNextBackgroundWakeIntent(NOW);
+
+    const after = Date.now();
+    expect(intent).not.toBeNull();
+    expect(intent!.computedAt).toBeGreaterThanOrEqual(before);
+    expect(intent!.computedAt).toBeLessThanOrEqual(after);
+  });
+
+  test("keeps sourceGeneration stable for unchanged sources", async () => {
+    heartbeatNextRunAt = NOW + 10_000;
+    schedules = [
+      scheduleFixture({
+        id: "scheduled",
+        nextRunAt: NOW + 20_000,
+      }),
+    ];
+
+    const first = computeNextBackgroundWakeIntent(NOW);
+    await new Promise((resolve) => setTimeout(resolve, 2));
+    const second = computeNextBackgroundWakeIntent(NOW);
+
+    expect(first).not.toBeNull();
+    expect(second).not.toBeNull();
+    expect(first!.computedAt).not.toBe(second!.computedAt);
+    expect(first!.sourceGeneration).toBe(second!.sourceGeneration);
+  });
+});
+
+function scheduleFixture(overrides: Partial<MockSchedule>): MockSchedule {
+  return {
+    id: "schedule",
+    nextRunAt: NOW + 60_000,
+    enabled: true,
+    mode: "execute",
+    createdBy: "agent",
+    status: "active",
+    syntax: "cron",
+    expression: "*/5 * * * *",
+    timezone: null,
+    updatedAt: NOW - 1_000,
+    ...overrides,
+  };
+}

package/src/background-wake/next-wake.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+
+import { getConfig } from "../config/loader.js";
+import { HeartbeatService } from "../heartbeat/heartbeat-service.js";
+import { computeNextRunAt } from "../schedule/recurrence-engine.js";
+import { listSchedules, type ScheduleJob } from "../schedule/schedule-store.js";
+
+export type BackgroundWakeIntentReason = "heartbeat" | "schedule" | "mixed";
+
+export interface BackgroundWakeSourcePayload {
+  heartbeat: HeartbeatWakeSource | null;
+  schedules: ScheduleWakeSource[];
+}
+
+export interface BackgroundWakeIntent {
+  nextWakeAt: number;
+  actualNextDueAt: number;
+  reason: BackgroundWakeIntentReason;
+  sourceGeneration: string;
+  computedAt: number;
+  sourcePayload: BackgroundWakeSourcePayload;
+}
+
+interface HeartbeatWakeSource {
+  nextRunAt: number;
+  mode: "cron" | "interval";
+  intervalMs: number;
+  cronExpression: string | null;
+  timezone: string | null;
+  activeHoursStart: number | null;
+  activeHoursEnd: number | null;
+  maxConsecutiveRuns: number | null;
+}
+
+interface ScheduleWakeSource {
+  id: string;
+  nextRunAt: number;
+  mode: ScheduleJob["mode"];
+  createdBy: string;
+  status: ScheduleJob["status"];
+  updatedAt: number;
+}
+
+type WakeCandidate = {
+  nextRunAt: number;
+  source: "heartbeat" | "schedule";
+};
+
+export function computeNextBackgroundWakeIntent(
+  now = Date.now(),
+): BackgroundWakeIntent | null {
+  const heartbeat = getHeartbeatWakeSource(now);
+  const schedules = getScheduleWakeSources();
+  const computedAt = Date.now();
+  const candidates: WakeCandidate[] = [];
+
+  if (heartbeat) {
+    candidates.push({ nextRunAt: heartbeat.nextRunAt, source: "heartbeat" });
+  }
+  for (const schedule of schedules) {
+    candidates.push({ nextRunAt: schedule.nextRunAt, source: "schedule" });
+  }
+
+  if (candidates.length === 0) return null;
+
+  const actualNextDueAt = Math.min(...candidates.map((c) => c.nextRunAt));
+  const nextWakeAt = actualNextDueAt;
+  const dueSources = new Set(
+    candidates
+      .filter((candidate) => candidate.nextRunAt === actualNextDueAt)
+      .map((candidate) => candidate.source),
+  );
+  const reason =
+    dueSources.size > 1
+      ? "mixed"
+      : dueSources.has("heartbeat")
+        ? "heartbeat"
+        : "schedule";
+  const sourcePayload = { heartbeat, schedules };
+
+  return {
+    nextWakeAt,
+    actualNextDueAt,
+    reason,
+    sourceGeneration: computeSourceGeneration({
+      actualNextDueAt,
+      sourcePayload,
+    }),
+    computedAt,
+    sourcePayload,
+  };
+}
+
+function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
+  const config = getConfig().heartbeat;
+  if (!config.enabled) return null;
+
+  const serviceNextRunAt = HeartbeatService.getInstance()?.nextRunAt ?? null;
+  let nextRunAt = serviceNextRunAt;
+  const mode = config.cronExpression != null ? "cron" : "interval";
+
+  if (nextRunAt == null) {
+    if (config.cronExpression != null) {
+      try {
+        nextRunAt = computeNextRunAt(
+          {
+            syntax: "cron",
+            expression: config.cronExpression,
+            timezone: config.timezone,
+          },
+          now,
+        );
+      } catch {
+        nextRunAt = now + config.intervalMs;
+      }
+    } else {
+      nextRunAt = now + config.intervalMs;
+    }
+  }
+
+  if (!Number.isFinite(nextRunAt) || nextRunAt <= 0) return null;
+
+  return {
+    nextRunAt,
+    mode,
+    intervalMs: config.intervalMs,
+    cronExpression: config.cronExpression,
+    timezone: config.timezone,
+    activeHoursStart: config.activeHoursStart,
+    activeHoursEnd: config.activeHoursEnd,
+    maxConsecutiveRuns: config.maxConsecutiveRuns,
+  };
+}
+
+function getScheduleWakeSources(): ScheduleWakeSource[] {
+  return listSchedules({ enabledOnly: true })
+    .filter((schedule) => schedule.status === "active")
+    .filter((schedule) => Number.isFinite(schedule.nextRunAt))
+    .filter((schedule) => schedule.nextRunAt > 0)
+    .sort((a, b) => a.nextRunAt - b.nextRunAt || a.id.localeCompare(b.id))
+    .map((schedule) => ({
+      id: schedule.id,
+      nextRunAt: schedule.nextRunAt,
+      mode: schedule.mode,
+      createdBy: schedule.createdBy,
+      status: schedule.status,
+      updatedAt: schedule.updatedAt,
+    }));
+}
+
+function computeSourceGeneration(input: {
+  actualNextDueAt: number;
+  sourcePayload: BackgroundWakeSourcePayload;
+}): string {
+  return `bw1:${createHash("sha256")
+    .update(stableStringify(input))
+    .digest("hex")}`;
+}
+
+function stableStringify(value: unknown): string {
+  if (value == null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+    .join(",")}}`;
+}

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/browser/operations.ts

@@ -177,13 +177,28 @@ export const BROWSER_OPERATION_META: readonly BrowserOperationMeta[] = [
         description: "Allow navigation to localhost/private-network hosts.",
         required: false,
       },
+      {
+        name: "new_tab",
+        type: "boolean",
+        description:
+          "Open the URL in a new browser tab and pin subsequent operations on this session to it. Extension backend only; ignored on other backends.",
+        required: false,
+      },
     ],
     helpText: `Loads the given URL and waits for the page to reach a stable state.
 Returns the page title on success.
 
+By default on the Chrome extension backend, navigate attaches the
+debugger to whichever tab is currently active. Pass --new-tab to
+open a fresh tab instead and pin this session's subsequent
+operations to it — useful when the active tab is one you don't
+want disturbed (for example, the tab you're chatting with the
+assistant from).
+
 Examples:
   $ assistant browser navigate --url https://example.com
   $ assistant browser navigate --url http://localhost:3000 --allow-private-network
+  $ assistant browser navigate --url https://github.com --new-tab
   $ assistant browser --session s1 navigate --url https://github.com`,
   },
   {

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);