@vellumai/assistant 0.11.9-dev.202609082015.1ff08e1 → 0.11.9-dev.202609082126.a4f0fef

package/openapi.yaml

@@ -13753,6 +13753,13 @@ paths:
                     anyOf:
                       - type: string
                       - type: "null"
+                  effectiveTimezone:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description:
+                      Timezone used for cron and active-hours evaluation after resolving heartbeat.timezone, then the user's
+                      configured or detected zone
                   nextRunAt:
                     anyOf:
                       - type: number
@@ -13770,6 +13777,7 @@ paths:
                   - activeHoursEnd
                   - cronExpression
                   - timezone
+                  - effectiveTimezone
                   - nextRunAt
                   - lastRunAt
                   - success
@@ -13809,7 +13817,7 @@ paths:
                     - type: string
                     - type: "null"
                 timezone:
-                  description: Timezone for cron evaluation
+                  description: Timezone for cron and active-hours evaluation
                   anyOf:
                     - type: string
                     - type: "null"
@@ -13841,6 +13849,13 @@ paths:
                     anyOf:
                       - type: string
                       - type: "null"
+                  effectiveTimezone:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description:
+                      Timezone used for cron and active-hours evaluation after resolving heartbeat.timezone, then the user's
+                      configured or detected zone
                   nextRunAt:
                     anyOf:
                       - type: number
@@ -13858,6 +13873,7 @@ paths:
                   - activeHoursEnd
                   - cronExpression
                   - timezone
+                  - effectiveTimezone
                   - nextRunAt
                   - lastRunAt
                   - success

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.9-dev.202609082015.1ff08e1",
+  "version": "0.11.9-dev.202609082126.a4f0fef",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/headless-browser-mode.test.ts

@@ -304,9 +304,11 @@ describe("formatModeSelectionFailure", () => {
     expect(formatted).toContain(
       "host browser proxy exists but is not connected",
     );
-    expect(formatted).toContain("Remediation:");
-    expect(formatted).toContain("extension is installed and enabled");
+    expect(formatted).toContain("Setup details:");
+    expect(formatted).toContain("Chrome extension");
     expect(formatted).toContain(CHROME_WEB_STORE_INSTALL_URL);
+    expect(formatted).toContain("www.vellum.ai/download");
+    expect(formatted).toContain("Offer those first");
   });
 
   test("renders cdp-inspect transport_error with remediation", () => {
@@ -330,8 +332,9 @@ describe("formatModeSelectionFailure", () => {
     expect(formatted).toContain('Browser mode "cdp-inspect" failed');
     expect(formatted).toContain("cdp-inspect: FAILED at send");
     expect(formatted).toContain("Discovery code: unreachable");
-    expect(formatted).toContain("Remediation:");
+    expect(formatted).toContain("Setup details:");
     expect(formatted).toContain("--remote-debugging-port");
+    expect(formatted).toContain(CHROME_WEB_STORE_INSTALL_URL);
   });
 
   test("includes the Chrome Web Store install URL for host-bridge failures", () => {
@@ -353,8 +356,32 @@ describe("formatModeSelectionFailure", () => {
 
     const formatted = formatModeSelectionFailure("auto", error);
 
-    expect(formatted).toContain("Remediation:");
+    expect(formatted).toContain("Setup details:");
+    expect(formatted).toContain(CHROME_WEB_STORE_INSTALL_URL);
+    expect(formatted).toContain("www.vellum.ai/download");
+  });
+
+  test("phone surfaces do not invent an in-app browser panel", () => {
+    const diagnostics: AttemptDiagnostic[] = [
+      {
+        candidateKind: "extension",
+        inclusionReason: "pinned mode: extension",
+        stage: "candidate_selection",
+        errorCode: "transport_error",
+        errorMessage: "not connected",
+      },
+    ];
+    const formatted = formatModeSelectionFailure(
+      "extension",
+      new CdpError("transport_error", "not connected", {
+        attemptDiagnostics: diagnostics,
+      }),
+      { transportInterface: "ios", clientOs: "ios" },
+    );
+    expect(formatted).toContain("no in-app browser");
+    expect(formatted).toContain("Do not describe a browser panel");
     expect(formatted).toContain(CHROME_WEB_STORE_INSTALL_URL);
+    expect(formatted).toContain("www.vellum.ai/download");
   });
 });
 
@@ -372,6 +399,7 @@ describe("browser_mode wiring through tool execution", () => {
     );
     expect(result.isError).toBe(true);
     expect(result.content).toContain('Invalid browser_mode "bogus"');
+    expect(result.content).not.toContain(CHROME_WEB_STORE_INSTALL_URL);
     expect(cdpSendCalls).toEqual([]);
   });
 
@@ -394,6 +422,28 @@ describe("browser_mode wiring through tool execution", () => {
 
   // ── Pinned extension with no proxy returns remediation error ───
 
+  test("navigation timeout offers the desktop app and Chrome extension", async () => {
+    cdpSendHandler = (method, params) => {
+      if (method === "Page.navigate") {
+        throw new Error(
+          "Navigation to https://intranet.example.com timed out after 15000ms",
+        );
+      }
+      return defaultCdpHandler(method, params);
+    };
+
+    const result = await executeBrowserNavigate(
+      { url: "https://intranet.example.com" },
+      ctx,
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Navigation failed");
+    expect(result.content).toContain("timed out");
+    expect(result.content).toContain(CHROME_WEB_STORE_INSTALL_URL);
+    expect(result.content).toContain("www.vellum.ai/download");
+    expect(result.content).toContain("Offer those first");
+  });
+
   test("pinned extension with no proxy returns remediation-rich error in navigate", async () => {
     factoryThrowError = new CdpError(
       "transport_error",
@@ -421,8 +471,8 @@ describe("browser_mode wiring through tool execution", () => {
     expect(result.content).toContain(
       "extension: FAILED at candidate_selection",
     );
-    expect(result.content).toContain("Remediation:");
-    expect(result.content).toContain("extension is installed and enabled");
+    expect(result.content).toContain("Setup details:");
+    expect(result.content).toContain("Chrome extension");
     expect(result.content).toContain(CHROME_WEB_STORE_INSTALL_URL);
     // Factory should not have been called for CDP
     expect(cdpSendCalls).toEqual([]);
@@ -451,7 +501,7 @@ describe("browser_mode wiring through tool execution", () => {
     );
     expect(result.isError).toBe(true);
     expect(result.content).toContain('Browser mode "extension" failed');
-    expect(result.content).toContain("Remediation:");
+    expect(result.content).toContain("Setup details:");
   });
 
   // ── cdp-debugger alias normalization ──────────────────────────
@@ -482,7 +532,7 @@ describe("browser_mode wiring through tool execution", () => {
     // The error should reference the canonical cdp-inspect name
     expect(result.content).toContain('Browser mode "cdp-inspect" failed');
     expect(result.content).toContain("Discovery code: unreachable");
-    expect(result.content).toContain("Remediation:");
+    expect(result.content).toContain("Setup details:");
     expect(result.content).toContain("--remote-debugging-port");
   });
 
@@ -544,7 +594,7 @@ describe("browser_mode wiring through tool execution", () => {
       "Reason: HTTP discovery failed (unreachable)",
     );
     expect(result.content).toContain("Discovery code: unreachable");
-    expect(result.content).toContain("Remediation:");
+    expect(result.content).toContain("Setup details:");
   });
 
   test("click tool returns remediation error on pinned mode failure", async () => {
@@ -576,7 +626,7 @@ describe("browser_mode wiring through tool execution", () => {
     expect(result.content).toContain(
       "extension: FAILED at candidate_selection",
     );
-    expect(result.content).toContain("Remediation:");
+    expect(result.content).toContain("Setup details:");
   });
 
   // ── Transport-classified host-browser errors produce failover diagnostics ──
@@ -609,8 +659,8 @@ describe("browser_mode wiring through tool execution", () => {
     expect(result.content).toContain('Browser mode "extension" failed');
     expect(result.content).toContain("extension: FAILED at send");
     expect(result.content).toContain("Reason: Host browser not reachable");
-    expect(result.content).toContain("Remediation:");
-    expect(result.content).toContain("extension is installed and enabled");
+    expect(result.content).toContain("Setup details:");
+    expect(result.content).toContain("Chrome extension");
     expect(result.content).toContain(CHROME_WEB_STORE_INSTALL_URL);
   });
 
@@ -634,7 +684,7 @@ describe("browser_mode wiring through tool execution", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain('Browser mode "extension" failed');
     expect(result.content).toContain("extension: FAILED at send");
-    expect(result.content).toContain("Remediation:");
+    expect(result.content).toContain("Setup details:");
   });
 
   // ── Per-conversation sticky backend kind ─────────────────────────

package/src/__tests__/heartbeat-disk-pressure.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { hasSetConstructs } from "../schedule/recurrence-engine.js";
 import { setConfig } from "./helpers/set-config.js";
 
 // Default the warm-pool gate to OPEN — these tests probe disk-pressure
@@ -30,6 +31,7 @@ mock.module("../heartbeat/heartbeat-run-store.js", () => ({
 }));
 
 mock.module("../schedule/recurrence-engine.js", () => ({
+  hasSetConstructs,
   computeNextRunAt: () => Date.now() + 60_000,
 }));
 

package/src/__tests__/heartbeat-service.test.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { hasSetConstructs } from "../schedule/recurrence-engine.js";
+
 const testWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
 
 // Default the warm-pool gate to OPEN for existing tests — they predate
@@ -80,11 +82,14 @@ function setHeartbeatConfig(overrides: Partial<HeartbeatSeed> = {}): void {
 //
 // HeartbeatService imports computeNextRunAt for cron scheduling.
 // Tests mutate `mockComputeNextRunAt` to control the next cron occurrence.
+// `hasSetConstructs` is re-exported because `schedule-timezone` imports it
+// from the same module and must keep working under this mock.
 let mockComputeNextRunAtResult: number | null = null;
 let mockComputeNextRunAtError: Error | null = null;
 let computeNextRunAtCallCount = 0;
 
 mock.module("../schedule/recurrence-engine.js", () => ({
+  hasSetConstructs,
   computeNextRunAt: (_spec: {
     syntax: string;
     expression: string;
@@ -303,8 +308,11 @@ export function setTestProcessMessage(
 }
 
 // Import after mocks are set up
-const { HeartbeatService, isShallowProfile } =
-  await import("../heartbeat/heartbeat-service.js");
+const {
+  HeartbeatService,
+  isShallowProfile,
+  shouldRescheduleHeartbeatForTimezoneChange,
+} = await import("../heartbeat/heartbeat-service.js");
 
 // Read the bundled template files so we can write them into the test workspace
 const templatesDir = join(import.meta.dirname!, "..", "prompts", "templates");
@@ -410,17 +418,20 @@ describe("HeartbeatService", () => {
 
     heartbeatConfig = defaultHeartbeatSeed();
     setHeartbeatConfig();
+    setConfig("ui", {});
   });
 
   function createService(overrides?: {
     processMessage?: (...args: unknown[]) => Promise<{ messageId: string }>;
     getCurrentHour?: () => number;
+    now?: () => Date;
   }) {
     if (overrides?.processMessage) {
       setTestProcessMessage(overrides.processMessage);
     }
     return new HeartbeatService({
       getCurrentHour: overrides?.getCurrentHour,
+      now: overrides?.now,
     });
   }
 
@@ -546,21 +557,52 @@ describe("HeartbeatService", () => {
     expect(processMessageCalls).toHaveLength(1);
   });
 
-  test("active hours handles overnight window", async () => {
-    setHeartbeatConfig({ activeHoursStart: 22, activeHoursEnd: 6 });
+    test("active hours handles overnight window", async () => {
+      setHeartbeatConfig({ activeHoursStart: 22, activeHoursEnd: 6 });
 
-    // 23:00 should be within the window
-    const service = createService({ getCurrentHour: () => 23 });
-    await service.runOnce();
-    expect(processMessageCalls).toHaveLength(1);
+      // 23:00 should be within the window
+      const service = createService({ getCurrentHour: () => 23 });
+      await service.runOnce();
+      expect(processMessageCalls).toHaveLength(1);
 
-    // 10:00 should be outside the window
-    processMessageCalls.length = 0;
-    createdConversations.length = 0;
-    const service2 = createService({ getCurrentHour: () => 10 });
-    await service2.runOnce();
-    expect(processMessageCalls).toHaveLength(0);
-  });
+      // 10:00 should be outside the window
+      processMessageCalls.length = 0;
+      createdConversations.length = 0;
+      const service2 = createService({ getCurrentHour: () => 10 });
+      await service2.runOnce();
+      expect(processMessageCalls).toHaveLength(0);
+    });
+
+    test("active hours guard uses user timezone in interval mode", async () => {
+      setConfig("ui", { detectedTimezone: "America/Los_Angeles" });
+      setHeartbeatConfig({
+        cronExpression: null,
+        timezone: null,
+        activeHoursStart: 8,
+        activeHoursEnd: 22,
+      });
+
+      // 23:00 UTC is 16:00 Pacific (inside 8-22) and 23:00 host-local
+      // (outside 8-22). If the guard still used the host clock this would skip.
+      const inside = createService({
+        now: () => new Date("2026-09-08T23:00:00Z"),
+        getCurrentHour: () => 23,
+      });
+      expect(await inside.runOnce()).toBe(true);
+      expect(processMessageCalls).toHaveLength(1);
+
+      processMessageCalls.length = 0;
+      createdConversations.length = 0;
+
+      // 06:00 UTC is 23:00 Pacific, outside 8-22, even though 6 is inside
+      // a naive UTC 8-22 window.
+      const outside = createService({
+        now: () => new Date("2026-09-09T06:00:00Z"),
+        getCurrentHour: () => 6,
+      });
+      expect(await outside.runOnce()).toBe(false);
+      expect(processMessageCalls).toHaveLength(0);
+    });
 
   test("overlap prevention works", async () => {
     let resolveFirst: () => void;
@@ -1307,26 +1349,25 @@ describe("HeartbeatService", () => {
     test("active hours guard uses cron timezone when configured", async () => {
       setHeartbeatConfig({
         cronExpression: "0 9,12,15,18 * * *",
-        timezone: "UTC",
-        activeHoursStart: 9,
-        activeHoursEnd: 17,
+        timezone: "America/Los_Angeles",
+        activeHoursStart: 8,
+        activeHoursEnd: 22,
       });
       mockComputeNextRunAtResult = Date.now() + 3_600_000;
 
-      const service = createService();
+      // 23:00 UTC = 16:00 PDT, inside 8-22 Pacific.
+      const service = createService({
+        now: () => new Date("2026-09-08T23:00:00Z"),
+        getCurrentHour: () => 23,
+      });
       service.start();
-
-      // In cron mode with timezone, the hour is computed via Intl.DateTimeFormat
-      // rather than getCurrentHour(). The test verifies the code path runs without
-      // error — the actual hour depends on the system clock and UTC conversion.
-      // We just verify it doesn't throw and returns a boolean result.
       const result = await service.runOnce();
-      // Result depends on current UTC hour vs active window — either outcome is valid
-      expect(typeof result).toBe("boolean");
+      expect(result).toBe(true);
+      expect(processMessageCalls).toHaveLength(1);
       service.stop();
     });
 
-    test("active hours guard falls back to getCurrentHour when cron mode has no timezone", async () => {
+    test("active hours guard falls back to getCurrentHour when no timezone is known", async () => {
       setHeartbeatConfig({
         cronExpression: "0 9,12,15,18 * * *",
         timezone: null,
@@ -1705,3 +1746,53 @@ describe("HeartbeatService", () => {
     });
   });
 });
+
+describe("shouldRescheduleHeartbeatForTimezoneChange", () => {
+  test("reschedules cron heartbeats when the fallback user timezone changes", () => {
+    expect(
+      shouldRescheduleHeartbeatForTimezoneChange(
+        {
+          ui: { userTimezone: "America/New_York" },
+          heartbeat: { cronExpression: "0 9 * * *" },
+        },
+        {
+          ui: { userTimezone: "America/Los_Angeles" },
+          heartbeat: { cronExpression: "0 9 * * *" },
+        },
+      ),
+    ).toBe(true);
+  });
+
+  test("ignores ui timezone changes in interval mode", () => {
+    expect(
+      shouldRescheduleHeartbeatForTimezoneChange(
+        { ui: { userTimezone: "America/New_York" }, heartbeat: {} },
+        {
+          ui: { userTimezone: "America/Los_Angeles" },
+          heartbeat: {},
+        },
+      ),
+    ).toBe(false);
+  });
+
+  test("ignores ui timezone changes when heartbeat.timezone is set", () => {
+    expect(
+      shouldRescheduleHeartbeatForTimezoneChange(
+        {
+          ui: { userTimezone: "America/New_York" },
+          heartbeat: {
+            cronExpression: "0 9 * * *",
+            timezone: "UTC",
+          },
+        },
+        {
+          ui: { userTimezone: "America/Los_Angeles" },
+          heartbeat: {
+            cronExpression: "0 9 * * *",
+            timezone: "UTC",
+          },
+        },
+      ),
+    ).toBe(false);
+  });
+});

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

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { setConfig } from "../__tests__/helpers/set-config.js";
+import { hasSetConstructs } from "../schedule/recurrence-engine.js";
 
 type MockHeartbeatConfig = {
   enabled: boolean;
@@ -44,6 +45,7 @@ mock.module("../heartbeat/heartbeat-service.js", () => ({
 }));
 
 mock.module("../schedule/recurrence-engine.js", () => ({
+  hasSetConstructs,
   computeNextRunAt: () => computedCronNextRunAt,
 }));
 
@@ -80,6 +82,7 @@ describe("computeNextBackgroundWakeIntent", () => {
     heartbeatConsecutiveRunCapReached = false;
     schedules = [];
     computedCronNextRunAt = NOW + 3_600_000;
+    setConfig("ui", {});
   });
 
   test("returns heartbeat-only interval wake intent", () => {
@@ -109,6 +112,16 @@ describe("computeNextBackgroundWakeIntent", () => {
     expect(intent!.reason).toBe("heartbeat");
   });
 
+  test("resolves heartbeat timezone from the user zone when unset", () => {
+    setConfig("ui", { detectedTimezone: "America/Los_Angeles" });
+    const intent = computeWakeIntent(NOW);
+    expect(intent).not.toBeNull();
+    expect(intent!.sourcePayload.heartbeat!.timezone).toBe(
+      "America/Los_Angeles",
+    );
+    setConfig("ui", {});
+  });
+
   test("returns heartbeat-only cron wake intent", () => {
     heartbeatConfig.cronExpression = "0 9 * * *";
     heartbeatConfig.timezone = "America/New_York";

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

@@ -4,6 +4,7 @@ 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";
+import { resolveScheduleTimezone } from "../schedule/schedule-timezone.js";
 
 export type BackgroundWakeIntentReason = "heartbeat" | "schedule" | "mixed";
 
@@ -110,6 +111,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
   const serviceNextRunAt = service?.nextRunAt ?? null;
   let nextRunAt = serviceNextRunAt;
   const mode = config.cronExpression != null ? "cron" : "interval";
+  const timezone = resolveScheduleTimezone(config.timezone);
 
   if (nextRunAt == null) {
     if (config.cronExpression != null) {
@@ -118,7 +120,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
           {
             syntax: "cron",
             expression: config.cronExpression,
-            timezone: config.timezone,
+            timezone,
           },
           now,
         );
@@ -139,7 +141,7 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
     mode,
     intervalMs: config.intervalMs,
     cronExpression: config.cronExpression,
-    timezone: config.timezone,
+    timezone,
     activeHoursStart: config.activeHoursStart,
     activeHoursEnd: config.activeHoursEnd,
     maxConsecutiveRuns: config.maxConsecutiveRuns,

package/src/config/schemas/heartbeat.ts

@@ -25,7 +25,7 @@ export const HeartbeatConfigSchema = z
       .nullable()
       .default(null)
       .describe(
-        "Timezone for cron expression evaluation, e.g. 'America/New_York'. Ignored when cronExpression is null.",
+        "Timezone for cron expression and active-hours evaluation, e.g. 'America/New_York'. When null, uses the user's configured or detected timezone, then the host clock.",
       ),
     activeHoursStart: z
       .number({ error: "heartbeat.activeHoursStart must be a number" })
@@ -35,7 +35,7 @@ export const HeartbeatConfigSchema = z
       .nullable()
       .default(8)
       .describe(
-        "Hour of the day (0-23) when heartbeat checks begin, or null to disable active hours restriction",
+        "Hour of the day (0-23) in the heartbeat timezone when heartbeat checks begin, or null to disable active hours restriction",
       ),
     activeHoursEnd: z
       .number({ error: "heartbeat.activeHoursEnd must be a number" })
@@ -45,7 +45,7 @@ export const HeartbeatConfigSchema = z
       .nullable()
       .default(22)
       .describe(
-        "Hour of the day (0-23) when heartbeat checks stop, or null to disable active hours restriction",
+        "Hour of the day (0-23) in the heartbeat timezone when heartbeat checks stop, or null to disable active hours restriction",
       ),
     maxConsecutiveRuns: z
       .number({ error: "heartbeat.maxConsecutiveRuns must be a number" })