@vellumai/assistant 0.7.0 → 0.7.2

package/src/runtime/routes/events-routes.ts

@@ -11,30 +11,23 @@
  * that conversation. When omitted, subscribers receive events from ALL
  * conversations for this assistant (unfiltered).
  *
- * If the conversationKey has no server-side mapping yet (e.g. a client-
- * generated draft UUID that has not been sent a first message), this
- * handler eagerly materialises the conversation so the subscriber's
- * `filter.conversationId` matches the id under which the first turn's
- * scoped events (text deltas, tool calls, message_complete) will be
- * published by `handleSendMessage`. The `conversation_list_invalidated`
- * notification for other clients is driven by `handleSendMessage`'s
- * first-message check, so eager materialisation here is safe and does
- * not hide the first-message notification from other clients.
- *
  * Client registration:
  *   Clients may send `X-Vellum-Client-Id` and `X-Vellum-Interface-Id`
- *   request headers to register in the ClientRegistry on connect and
- *   automatically unregister on disconnect. When both headers are present,
- *   the client is registered immediately, touched on each heartbeat, and
- *   unregistered when the stream closes. When either header is missing,
- *   registration is skipped (backwards compat).
+ *   request headers. When both are present, the subscriber is registered
+ *   as a client in the event hub with derived capabilities. The hub
+ *   handles registration, touch (heartbeat), and unregistration (dispose).
  */
 
-import { parseInterfaceId } from "../../channels/types.js";
+import type { HostProxyCapability } from "../../channels/types.js";
+import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
 import { getOrCreateConversation } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
-import { formatSseFrame, formatSseHeartbeat } from "../assistant-event.js";
+import {
+  formatSseFrame,
+  formatSseHeartbeatWithData,
+} from "../assistant-event.js";
 import type {
+  AssistantEventCallback,
   AssistantEventFilter,
   AssistantEventSubscription,
 } from "../assistant-event-hub.js";
@@ -42,15 +35,13 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
-import { getClientRegistry } from "../client-registry.js";
 import { BadRequestError, ServiceUnavailableError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
 
-/** Keep-alive comment sent to idle clients every 30 s by default. */
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+/** Keep-alive comment sent to idle clients every 5 s by default. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
 
 /**
  * Stream assistant events as Server-Sent Events.
@@ -64,12 +55,13 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
  *   X-Vellum-Client-Id    -- stable per-install UUID identifying this client.
  *   X-Vellum-Interface-Id -- interface type (e.g. "macos", "ios", "web").
  *
- *   When both are present the client is registered in the ClientRegistry on
- *   connect and unregistered on disconnect.
+ *   When both are present, the subscriber is registered as a client in the
+ *   event hub with metadata (interfaceId, capabilities). The hub handles
+ *   lifecycle — dispose() unregisters the client automatically.
  *
  * Options (for testing):
  *   hub               -- override the event hub (defaults to process singleton).
- *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 30 s).
+ *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 5 s).
  */
 export function handleSubscribeAssistantEvents(
   args: RouteHandlerArgs,
@@ -85,9 +77,10 @@ export function handleSubscribeAssistantEvents(
     throw new BadRequestError("conversationKey must not be empty");
   }
 
-  // ── Client registration from headers ──────────────────────────────────
+  // ── Client identity from headers ──────────────────────────────────────
   const rawClientId = headers?.["x-vellum-client-id"];
   const rawInterfaceId = headers?.["x-vellum-interface-id"];
+  const rawMachineName = headers?.["x-vellum-machine-name"];
   const clientId = rawClientId?.trim() || null;
   const interfaceId = clientId
     ? parseInterfaceId(rawInterfaceId?.trim())
@@ -103,32 +96,24 @@ export function handleSubscribeAssistantEvents(
     );
   }
 
-  const registry = getClientRegistry();
-  if (clientId && interfaceId) {
-    registry.register({ clientId, interfaceId });
-    log.info(
-      { clientId, interfaceId },
-      "client registered via /events SSE connect",
-    );
-  }
-
   const hub = options?.hub ?? assistantEventHub;
   const heartbeatIntervalMs =
     options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
 
-  const filter: AssistantEventFilter = {
-    assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
-  };
+  const ALL_CAPABILITIES: HostProxyCapability[] = [
+    "host_bash",
+    "host_file",
+    "host_cu",
+    "host_app_control",
+    "host_browser",
+  ];
+
+  const filter: AssistantEventFilter = {};
   if (conversationKey) {
-    // Eagerly resolve (and if necessary create) the conversation so the
-    // subscriber's filter matches the id under which first-turn scoped
-    // events will be published. The `conversation_list_invalidated`
-    // publish is driven by `handleSendMessage`'s first-message check,
-    // so eager materialisation here is safe and does not suppress the
-    // cross-client notification.
     const mapping = getOrCreateConversation(conversationKey);
     filter.conversationId = mapping.conversationId;
   }
+
   const encoder = new TextEncoder();
 
   // -- Eager subscribe --------------------------------------------------------
@@ -145,9 +130,6 @@ export function handleSubscribeAssistantEvents(
       clearInterval(heartbeatTimer);
       heartbeatTimer = null;
     }
-    if (clientId) {
-      registry.unregister(clientId);
-    }
     try {
       controllerRef?.close();
     } catch {
@@ -155,85 +137,77 @@ export function handleSubscribeAssistantEvents(
     }
   }
 
+  const callback: AssistantEventCallback = (event) => {
+    const controller = controllerRef;
+    if (!controller) return;
+    try {
+      if (controller.desiredSize != null && controller.desiredSize <= 0) {
+        sub.dispose();
+        cleanup();
+        return;
+      }
+      controller.enqueue(encoder.encode(formatSseFrame(event)));
+    } catch {
+      sub.dispose();
+      cleanup();
+    }
+  };
+
   try {
-    sub = hub.subscribe(
+    const subscriberBase = {
       filter,
-      (event) => {
-        const controller = controllerRef;
-        if (!controller) return;
-        try {
-          // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
-          // is full and the client isn't draining it.
-          if (controller.desiredSize != null && controller.desiredSize <= 0) {
-            sub.dispose();
-            cleanup();
-            return;
-          }
-          controller.enqueue(encoder.encode(formatSseFrame(event)));
-        } catch {
-          sub.dispose();
-          cleanup();
-        }
-      },
-      {
-        // Called by the hub when a newer connection evicts this one (capacity
-        // management: oldest subscriber out, newest in).
-        onEvict: cleanup,
-      },
-    );
+      callback,
+      onEvict: cleanup,
+    };
+
+    sub =
+      clientId && interfaceId
+        ? hub.subscribe({
+            ...subscriberBase,
+            type: "client" as const,
+            clientId,
+            interfaceId,
+            capabilities: ALL_CAPABILITIES.filter((cap) =>
+              supportsHostProxy(interfaceId, cap),
+            ),
+            machineName: rawMachineName?.trim() || undefined,
+          })
+        : hub.subscribe({
+            ...subscriberBase,
+            type: "process" as const,
+          });
   } catch (err) {
     if (err instanceof RangeError) {
-      if (clientId) {
-        registry.unregister(clientId);
-      }
       throw new ServiceUnavailableError("Too many concurrent connections");
     }
     throw err;
   }
 
-  // Allow up to 16 queued frames before treating the consumer as stalled.
-  // This absorbs normal token-stream bursts without prematurely closing the
-  // connection, while still shedding genuinely slow clients.
   const stream = new ReadableStream<Uint8Array>(
     {
       start(controller) {
         controllerRef = controller;
 
-        // If the client already disconnected before start() ran, clean up
-        // immediately -- the abort event fires once and won't be re-dispatched.
         if (abortSignal?.aborted) {
           sub.dispose();
           cleanup();
           return;
         }
 
-        // Immediately enqueue a heartbeat comment so the HTTP status line and
-        // headers are flushed to the client without waiting for a real event.
-        // Without this, Bun may buffer the headers until the first data chunk
-        // arrives, causing clients (e.g. Python `requests`) to hang until the
-        // periodic heartbeat fires or an event is published.
-        controller.enqueue(encoder.encode(formatSseHeartbeat()));
+        controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
 
-        // Send a keep-alive comment on each interval to prevent proxies and
-        // load-balancers from treating idle connections as timed out.
         heartbeatTimer = setInterval(() => {
           try {
-            // Apply the same slow-consumer guard as the event path: stop
-            // feeding heartbeats into a queue the client is not draining.
             if (controller.desiredSize != null && controller.desiredSize <= 0) {
               sub.dispose();
               cleanup();
               return;
             }
-            // Touch the client on each heartbeat to keep it fresh in the
-            // registry. Without this, long-idle SSE connections would be
-            // evicted by the staleness sweep despite being connected.
             if (clientId) {
-              registry.touch(clientId);
+              hub.touchClient(clientId);
             }
-            controller.enqueue(encoder.encode(formatSseHeartbeat()));
+            controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
           } catch {
-            // Controller already closed (e.g. client disconnected).
             sub.dispose();
             cleanup();
           }

package/src/runtime/routes/filing-routes.ts

@@ -1,17 +1,27 @@
 /**
  * Route handlers for filing management.
+ *
+ * `available` reflects whether the filing service is the active background
+ * memory job for this instance. When the `memory-v2-enabled` flag is on,
+ * filing yields to the consolidation job (see consolidation-routes.ts) and
+ * returns `available: false` so the UI can hide the row.
  */
 
 import { z } from "zod";
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { FilingService } from "../../filing/filing-service.js";
 import { getLogger } from "../../util/logger.js";
-import { InternalError } from "./errors.js";
+import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("filing-routes");
 
+function isFilingAvailable(): boolean {
+  return !isAssistantFeatureFlagEnabled("memory-v2-enabled", getConfig());
+}
+
 // ---------------------------------------------------------------------------
 // Shared ROUTES
 // ---------------------------------------------------------------------------
@@ -27,6 +37,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Return the current filing schedule configuration.",
     tags: ["filing"],
     responseBody: z.object({
+      available: z.boolean(),
       enabled: z.boolean(),
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
@@ -39,6 +50,7 @@ export const ROUTES: RouteDefinition[] = [
       const config = getConfig().filing;
       const svc = FilingService.getInstance();
       return {
+        available: isFilingAvailable(),
         enabled: config.enabled,
         intervalMs: config.intervalMs,
         activeHoursStart: config.activeHoursStart ?? null,
@@ -63,6 +75,11 @@ export const ROUTES: RouteDefinition[] = [
       ran: z.boolean().describe("Whether the filing actually ran"),
     }),
     handler: async (_args: RouteHandlerArgs) => {
+      if (!isFilingAvailable()) {
+        throw new BadRequestError(
+          "Filing is not the active background memory job (memory v2 is enabled)",
+        );
+      }
       const svc = FilingService.getInstance();
       if (!svc) {
         throw new InternalError("Filing service not available");

package/src/runtime/routes/gateway-log-routes.ts

@@ -0,0 +1,79 @@
+/**
+ * Gateway log tail route — gateway HTTP proxy.
+ *
+ * The handler makes a single HTTP call to the gateway's log-tail API
+ * and surfaces the body's `.error` message on non-OK responses.
+ */
+import { z } from "zod";
+
+import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Shared helper ───────────────────────────────────────────────────────
+
+async function gatewayFetch(
+  path: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const base = getGatewayInternalBaseUrl();
+  const res = await fetch(`${base}${path}`, init);
+  if (!res.ok) {
+    let message = `Gateway request failed (${res.status})`;
+    try {
+      const body = (await res.json()) as { error?: unknown };
+      if (typeof body.error === "string") {
+        message = body.error;
+      }
+    } catch {
+      // ignore JSON parse failures
+    }
+    throw new Error(message);
+  }
+  return res.json();
+}
+
+// ── Schemas ─────────────────────────────────────────────────────────────
+
+const LEVEL_NAMES = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
+
+const GatewayLogsTailParams = z
+  .object({
+    n: z.coerce.number().int().min(1).max(1000).optional(),
+    level: z.enum(LEVEL_NAMES).optional(),
+    module: z.string().optional(),
+  })
+  .strict();
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+  // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
+  const source = Object.keys(queryParams).length > 0 ? queryParams : body;
+  const p = GatewayLogsTailParams.parse(source);
+  const qs = new URLSearchParams();
+  if (p.n !== undefined) qs.set("n", String(p.n));
+  if (p.level !== undefined) qs.set("level", p.level);
+  if (p.module !== undefined) qs.set("module", p.module);
+  const query = qs.toString();
+  return gatewayFetch(`/v1/logs/tail${query ? `?${query}` : ""}`);
+}
+
+// ── Route definitions ───────────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "gateway_logs_tail",
+    method: "GET",
+    endpoint: "gateway/logs/tail",
+    handler: handleGatewayLogsTail,
+    summary: "Tail gateway log entries",
+    description:
+      "Return the last N structured log entries from the gateway log files.",
+    tags: ["gateway-logs"],
+    queryParams: [
+      { name: "n", description: "Number of lines to return (1–1000, default: 10)" },
+      { name: "level", description: "Minimum pino level name (default: info)" },
+      { name: "module", description: "Filter to exact pino module name" },
+    ],
+  },
+];

package/src/runtime/routes/guardian-action-routes.ts

@@ -29,15 +29,11 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // GET /v1/guardian-actions/pending?conversationId=...
 // ---------------------------------------------------------------------------
 
-function handleGuardianActionsPending({
-  queryParams = {},
-}: RouteHandlerArgs) {
+function handleGuardianActionsPending({ queryParams = {} }: RouteHandlerArgs) {
   const conversationId = queryParams.conversationId;
 
   if (!conversationId) {
-    throw new BadRequestError(
-      "conversationId query parameter is required",
-    );
+    throw new BadRequestError("conversationId query parameter is required");
   }
 
   const prompts = listGuardianDecisionPrompts({
@@ -51,7 +47,7 @@ function handleGuardianActionsPending({
 // POST /v1/guardian-actions/decision
 // ---------------------------------------------------------------------------
 
-export async function handleGuardianActionDecision({
+async function handleGuardianActionDecision({
   body,
   headers = {},
 }: RouteHandlerArgs) {
@@ -231,8 +227,7 @@ export const ROUTES: RouteDefinition[] = [
     endpoint: "guardian-actions/pending",
     method: "GET",
     summary: "List pending guardian actions",
-    description:
-      "Return pending guardian decision prompts for a conversation.",
+    description: "Return pending guardian decision prompts for a conversation.",
     tags: ["guardian"],
     queryParams: [
       {

package/src/runtime/routes/guardian-approval-interception.ts

@@ -71,14 +71,8 @@ export interface ApprovalInterceptionParams {
   approvalMessageTs?: string;
 }
 
-export interface ApprovalInterceptionResult {
-  handled: boolean;
-  type?:
-    | "decision_applied"
-    | "assistant_turn"
-    | "guardian_decision_applied"
-    | "stale_ignored";
-}
+import type { ApprovalInterceptionResult } from "./approval-interception-types.js";
+export type { ApprovalInterceptionResult } from "./approval-interception-types.js";
 
 /**
  * Check for pending approvals and handle inbound messages accordingly.

package/src/runtime/routes/heartbeat-routes.ts

@@ -8,13 +8,16 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
-import { desc, eq } from "drizzle-orm";
 import { z } from "zod";
 
-import { getConfig, saveConfig } from "../../config/loader.js";
+import {
+  getConfig,
+  invalidateConfigCache,
+  loadRawConfig,
+  saveRawConfig,
+} from "../../config/loader.js";
+import { listHeartbeatRuns } from "../../heartbeat/heartbeat-run-store.js";
 import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
-import { getDb } from "../../memory/db-connection.js";
-import { conversations } from "../../memory/schema/conversations.js";
 import { readTextFileSync } from "../../util/fs.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
@@ -32,25 +35,20 @@ function handleListRuns(queryParams: Record<string, string>) {
   const limit = Number.isFinite(rawLimit)
     ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
     : 20;
-  const db = getDb();
-  const rows = db
-    .select({
-      id: conversations.id,
-      title: conversations.title,
-      createdAt: conversations.createdAt,
-    })
-    .from(conversations)
-    .where(eq(conversations.source, "heartbeat"))
-    .orderBy(desc(conversations.createdAt))
-    .limit(limit)
-    .all();
 
+  const runs = listHeartbeatRuns(limit);
   return {
-    runs: rows.map((r) => ({
+    runs: runs.map((r) => ({
       id: r.id,
-      title: r.title ?? "Heartbeat",
+      scheduledFor: r.scheduledFor,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      durationMs: r.durationMs,
+      status: r.status,
+      skipReason: r.skipReason,
+      error: r.error,
+      conversationId: r.conversationId,
       createdAt: r.createdAt,
-      result: "ok",
     })),
   };
 }
@@ -102,7 +100,22 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      runs: z.array(z.unknown()).describe("Heartbeat run records"),
+      runs: z
+        .array(
+          z.object({
+            id: z.string(),
+            scheduledFor: z.number(),
+            startedAt: z.number().nullable(),
+            finishedAt: z.number().nullable(),
+            durationMs: z.number().nullable(),
+            status: z.string(),
+            skipReason: z.string().nullable(),
+            error: z.string().nullable(),
+            conversationId: z.string().nullable(),
+            createdAt: z.number(),
+          }),
+        )
+        .describe("Heartbeat run records"),
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListRuns(queryParams ?? {}),
@@ -135,8 +148,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       success: z.boolean(),
     }),
-    handler: ({ body }: RouteHandlerArgs) =>
-      handleWriteChecklist(body ?? {}),
+    handler: ({ body }: RouteHandlerArgs) => handleWriteChecklist(body ?? {}),
   },
   {
     operationId: "getHeartbeatConfig",
@@ -152,6 +164,8 @@ export const ROUTES: RouteDefinition[] = [
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
@@ -164,6 +178,8 @@ export const ROUTES: RouteDefinition[] = [
         intervalMs: config.intervalMs,
         activeHoursStart: config.activeHoursStart ?? null,
         activeHoursEnd: config.activeHoursEnd ?? null,
+        cronExpression: config.cronExpression ?? null,
+        timezone: config.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,
@@ -180,46 +196,95 @@ export const ROUTES: RouteDefinition[] = [
     description: "Update the heartbeat schedule configuration.",
     tags: ["heartbeat"],
     requestBody: z.object({
-      enabled: z.boolean().describe("Enable or disable heartbeat"),
-      intervalMs: z.number().describe("Heartbeat interval in ms"),
-      activeHoursStart: z.number().describe("Active hours start (0–23)"),
-      activeHoursEnd: z.number().describe("Active hours end (0–23)"),
+      enabled: z.boolean().optional().describe("Enable or disable heartbeat"),
+      intervalMs: z.number().optional().describe("Heartbeat interval in ms"),
+      activeHoursStart: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours start (0–23)"),
+      activeHoursEnd: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours end (0–23)"),
+      cronExpression: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          "Cron expression for heartbeat timing, or null for fixed interval",
+        ),
+      timezone: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Timezone for cron evaluation"),
     }),
     responseBody: z.object({
       enabled: z.boolean(),
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
     }),
     handler: async ({ body = {} }: RouteHandlerArgs) => {
-      const config = getConfig();
-      const heartbeat = { ...config.heartbeat };
-
-      if (typeof body.enabled === "boolean") heartbeat.enabled = body.enabled;
-      if (typeof body.intervalMs === "number")
-        heartbeat.intervalMs = body.intervalMs;
-      if (typeof body.activeHoursStart === "number")
-        heartbeat.activeHoursStart = body.activeHoursStart;
-      if (typeof body.activeHoursEnd === "number")
-        heartbeat.activeHoursEnd = body.activeHoursEnd;
+      // Build a patch containing only the fields the caller actually set.
+      // Writing back the full Zod-defaulted heartbeat object would bake
+      // defaults onto disk, masking later schema changes from the user.
+      // Use "key in body" checks for nullable fields so explicit null clears them.
+      const heartbeatPatch: Record<string, unknown> = {};
+      if ("enabled" in body && typeof body.enabled === "boolean")
+        heartbeatPatch.enabled = body.enabled;
+      if ("intervalMs" in body && typeof body.intervalMs === "number")
+        heartbeatPatch.intervalMs = body.intervalMs;
+      if ("activeHoursStart" in body)
+        heartbeatPatch.activeHoursStart =
+          typeof body.activeHoursStart === "number"
+            ? body.activeHoursStart
+            : null;
+      if ("activeHoursEnd" in body)
+        heartbeatPatch.activeHoursEnd =
+          typeof body.activeHoursEnd === "number" ? body.activeHoursEnd : null;
+      if ("cronExpression" in body)
+        heartbeatPatch.cronExpression =
+          typeof body.cronExpression === "string" ? body.cronExpression : null;
+      if ("timezone" in body)
+        heartbeatPatch.timezone =
+          typeof body.timezone === "string" ? body.timezone : null;
 
       try {
-        saveConfig({ ...config, heartbeat });
-        log.info({ heartbeat }, "Heartbeat config updated");
+        const raw = loadRawConfig();
+        raw.heartbeat = {
+          ...((raw.heartbeat as Record<string, unknown>) ?? {}),
+          ...heartbeatPatch,
+        };
+        saveRawConfig(raw);
+        invalidateConfigCache();
+        log.info({ heartbeat: heartbeatPatch }, "Heartbeat config updated");
       } catch (err) {
         log.error({ err }, "Failed to save heartbeat config");
         throw new InternalError("Failed to save config");
       }
 
+      // Read effective values back through the schema-defaulting loader so
+      // callers that only set a subset of fields still see the resolved
+      // (post-default) shape in the response.
+      const heartbeat = getConfig().heartbeat;
       const svc = HeartbeatService.getInstance();
+      svc?.reconfigure();
+
       return {
         enabled: heartbeat.enabled,
         intervalMs: heartbeat.intervalMs,
         activeHoursStart: heartbeat.activeHoursStart ?? null,
         activeHoursEnd: heartbeat.activeHoursEnd ?? null,
+        cronExpression: heartbeat.cronExpression ?? null,
+        timezone: heartbeat.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,