@vellumai/assistant 0.8.0 → 0.8.2

package/src/config/llm-resolver.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { getCatalogProviderForModel } from "../providers/model-catalog.js";
 import {
   type LLMCallSite,
   LLMConfigBase,
@@ -67,7 +68,7 @@ export function resolveCallSiteConfig(
     appendCallSiteLayers(layers, callSite, llm, site);
   }
 
-  return finalize(deepMerge(...layers));
+  return finalize(deepMerge(...layers.map(withImpliedProviderForKnownModel)));
 }
 
 // ---------------------------------------------------------------------------
@@ -76,6 +77,20 @@ export function resolveCallSiteConfig(
 
 type Mergeable = Record<string, unknown>;
 
+function withImpliedProviderForKnownModel(source: Mergeable): Mergeable {
+  if (source.provider !== undefined) return source;
+  const model = source.model;
+  if (typeof model !== "string" || model.length === 0) return source;
+
+  const provider = getCatalogProviderForModel(model);
+  if (provider === undefined) return source;
+
+  return {
+    ...source,
+    provider,
+  };
+}
+
 function appendProfileLayer(
   layers: Mergeable[],
   profile: ProfileEntry | undefined,

package/src/config/loader.ts

@@ -25,6 +25,7 @@ const log = getLogger("config");
 let cached: AssistantConfig | null = null;
 let cachedFileSignature: ConfigFileSignature | null = null;
 let loading = false;
+let suppressConfigDiskWritesDepth = 0;
 
 type ConfigFileSignature =
   | {
@@ -124,7 +125,6 @@ export function getDeploymentContextDefaults(): Record<string, unknown> {
   const managed = { mode: "managed" as const };
   return {
     services: {
-      inference: managed,
       "image-generation": managed,
       "web-search": managed,
       "google-oauth": managed,
@@ -520,12 +520,14 @@ export function deepMergeOverwrite(
 }
 
 export type DefaultWorkspaceConfigMergeResult = {
+  hadOverlay: boolean;
   providedLlmProfileNames: Set<string>;
   providedLlmActiveProfile: boolean;
 };
 
 function emptyDefaultWorkspaceConfigMergeResult(): DefaultWorkspaceConfigMergeResult {
   return {
+    hadOverlay: false,
     providedLlmProfileNames: new Set(),
     providedLlmActiveProfile: false,
   };
@@ -571,6 +573,7 @@ export function mergeDefaultWorkspaceConfig(): DefaultWorkspaceConfigMergeResult
   );
   const providedProfiles = readPlainObject(llmDefaults?.profiles);
   const mergeResult: DefaultWorkspaceConfigMergeResult = {
+    hadOverlay: true,
     providedLlmProfileNames: new Set(
       providedProfiles ? Object.keys(providedProfiles) : [],
     ),
@@ -649,7 +652,24 @@ export function loadConfig(): AssistantConfig {
     let configFileExisted = true;
     if (existsSync(configPath)) {
       try {
-        fileConfig = JSON.parse(readFileSync(configPath, "utf-8"));
+        const parsed: unknown = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!isPlainObject(parsed)) {
+          // Same shape contract as `loadRawConfig`: top-level value must be a
+          // plain object. A `null`, primitive, or array is treated like a
+          // parse error so downstream code (`warnAndStripDeprecatedFields`,
+          // `setNestedValue` in the managed-Gemini migration block, etc.)
+          // never iterates a non-record. Quarantine + fall through to defaults.
+          quarantineCorruptConfig(
+            configPath,
+            new Error(
+              `config.json must contain a JSON object at the top level; got ${describeJsonShape(parsed)}`,
+            ),
+          );
+          fileConfig = {};
+          configFileExisted = false;
+        } else {
+          fileConfig = parsed;
+        }
       } catch (err) {
         // The daemon must never block startup (assistant/CLAUDE.md). A config
         // file that fails JSON.parse — truncated during a mid-write crash, or
@@ -664,49 +684,54 @@ export function loadConfig(): AssistantConfig {
       configFileExisted = false;
     }
 
-    // Warn about and strip deprecated config fields so users know their
-    // settings are no longer honored rather than silently dropping them.
-    warnAndStripDeprecatedFields(fileConfig, configPath);
+    if (suppressConfigDiskWritesDepth === 0) {
+      warnAndStripDeprecatedFields(fileConfig, configPath);
+    }
 
     // Validate and apply defaults via Zod schema
     let config = validateWithSchema(fileConfig);
 
-    // Managed Gemini embedding defaults migration.
-    // When on a managed platform (IS_PLATFORM=true) with the feature flag
-    // enabled and no explicit embedding provider chosen (provider=auto),
-    // persist Gemini embedding defaults into the raw config file.
-    // Idempotent: once provider=gemini is written, subsequent loads skip this.
-    if (config.memory.embeddings.provider === "auto") {
-      try {
-        if (
-          (process.env.IS_PLATFORM === "true" ||
-            process.env.IS_PLATFORM === "1") &&
-          isManagedGeminiFFEnabled(config)
-        ) {
-          setNestedValue(fileConfig, "memory.embeddings.provider", "gemini");
-          setNestedValue(
-            fileConfig,
-            "memory.embeddings.geminiModel",
-            "gemini-embedding-2",
-          );
-          setNestedValue(
-            fileConfig,
-            "memory.embeddings.geminiDimensions",
-            3072,
+    if (suppressConfigDiskWritesDepth === 0) {
+      // Managed Gemini embedding defaults migration.
+      // When on a managed platform (IS_PLATFORM=true) with the feature flag
+      // enabled and no explicit embedding provider chosen (provider=auto),
+      // persist Gemini embedding defaults into the raw config file.
+      // Idempotent: once provider=gemini is written, subsequent loads skip this.
+      if (config.memory.embeddings.provider === "auto") {
+        try {
+          if (
+            (process.env.IS_PLATFORM === "true" ||
+              process.env.IS_PLATFORM === "1") &&
+            isManagedGeminiFFEnabled(config)
+          ) {
+            setNestedValue(fileConfig, "memory.embeddings.provider", "gemini");
+            setNestedValue(
+              fileConfig,
+              "memory.embeddings.geminiModel",
+              "gemini-embedding-2",
+            );
+            setNestedValue(
+              fileConfig,
+              "memory.embeddings.geminiDimensions",
+              3072,
+            );
+            setNestedValue(fileConfig, "memory.qdrant.vectorSize", 3072);
+            writeFileSync(
+              configPath,
+              JSON.stringify(fileConfig, null, 2) + "\n",
+            );
+            log.info(
+              "Applied managed Gemini embedding defaults (provider=gemini, model=gemini-embedding-2, dimensions=3072, vectorSize=3072)",
+            );
+            // Re-validate so the returned config reflects the migration.
+            config = validateWithSchema(fileConfig);
+          }
+        } catch (err) {
+          log.warn(
+            { err },
+            "Managed Gemini defaults migration failed — continuing with existing config",
           );
-          setNestedValue(fileConfig, "memory.qdrant.vectorSize", 3072);
-          writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + "\n");
-          log.info(
-            "Applied managed Gemini embedding defaults (provider=gemini, model=gemini-embedding-2, dimensions=3072, vectorSize=3072)",
-          );
-          // Re-validate so the returned config reflects the migration.
-          config = validateWithSchema(fileConfig);
         }
-      } catch (err) {
-        log.warn(
-          { err },
-          "Managed Gemini defaults migration failed — continuing with existing config",
-        );
       }
     }
 
@@ -744,7 +769,7 @@ export function loadConfig(): AssistantConfig {
     // changes were inert because the merge only filled absent keys and never
     // reconciled existing values. Contract: disk = user intent, in-memory
     // cache = effective values.
-    if (!configFileExisted) {
+    if (!configFileExisted && suppressConfigDiskWritesDepth === 0) {
       try {
         const dir = dirname(configPath);
         if (!existsSync(dir)) {
@@ -823,28 +848,91 @@ export function invalidateConfigCache(): void {
   loading = false;
 }
 
+export async function withSuppressedConfigDiskWrites<T>(
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  suppressConfigDiskWritesDepth++;
+  try {
+    return await fn();
+  } finally {
+    suppressConfigDiskWritesDepth--;
+  }
+}
+
+export function withSuppressedConfigDiskWritesSync<T>(fn: () => T): T {
+  suppressConfigDiskWritesDepth++;
+  try {
+    return fn();
+  } finally {
+    suppressConfigDiskWritesDepth--;
+  }
+}
+
 /**
  * Load the raw config from disk without any secure-storage merging.
  * Used by CLI config commands to read/write the file directly.
  * API keys in secure storage are managed via `assistant keys` commands.
+ *
+ * Contract: returns a plain object (`Record<string, unknown>`). When
+ * `config.json` is missing → returns `{}`. When the file is unparseable
+ * (truncated, hand-edited to invalid JSON) OR when it parses to a value
+ * that is technically valid JSON but NOT a plain object (`null`, a
+ * primitive like `42`, `"hello"`, `true`, or an array `[…]`) → quarantines
+ * the file and returns `{}`. Callers can therefore rely on the return
+ * type without runtime shape-checking — the boundary check happens here.
  */
 export function loadRawConfig(): Record<string, unknown> {
   ensureMigratedDataDir();
   const configPath = getConfigPath();
-  let raw: Record<string, unknown> = {};
-  if (existsSync(configPath)) {
-    try {
-      raw = JSON.parse(readFileSync(configPath, "utf-8"));
-    } catch (err) {
-      // Mirror loadConfig(): quarantine the corrupt file and return an empty
-      // object rather than throwing. This prevents /v1/config from surfacing
-      // a 500 when the user's config.json is malformed.
-      quarantineCorruptConfig(configPath, err);
-      raw = {};
-    }
+  if (!existsSync(configPath)) {
+    return {};
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    // Mirror loadConfig(): quarantine the corrupt file and return an empty
+    // object rather than throwing. This prevents /v1/config from surfacing
+    // a 500 when the user's config.json is malformed.
+    quarantineCorruptConfig(configPath, err);
+    return {};
+  }
+
+  if (!isPlainObject(parsed)) {
+    // Valid JSON but the wrong shape — `null`, a primitive, or an array.
+    // Treat the same as a parse error so the return-type contract above is
+    // truthful and downstream callers (e.g. /v1/config handlers, twilio
+    // integration routes, settings routes) can iterate keys safely.
+    quarantineCorruptConfig(
+      configPath,
+      new Error(
+        `config.json must contain a JSON object at the top level; got ${describeJsonShape(parsed)}`,
+      ),
+    );
+    return {};
   }
 
-  return raw;
+  return parsed;
+}
+
+/**
+ * Predicate for "the value is a plain JSON object" — i.e. not `null`, not
+ * a primitive, and not an array. The cast on the truthy branch is safe
+ * because the caller's static type narrowed accordingly.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Human-readable shape label for error messages. Distinguishes the four
+ * non-object JSON shapes the loader rejects.
+ */
+function describeJsonShape(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
 }
 
 export function saveRawConfig(config: Record<string, unknown>): void {

package/src/config/raw-config-utils.ts

@@ -1,39 +1,11 @@
-/**
- * Safely set a nested field on a raw config object's `llm.default` map.
- *
- * Ensures the `llm` and `llm.default` objects exist before writing, so
- * callers don't need to guard against undefined intermediate keys.
- *
- * Example: `setLlmDefaultField(raw, "model", "claude-sonnet-4-6")`
- * produces `raw.llm.default.model = "claude-sonnet-4-6"`.
- */
-export function setLlmDefaultField(
-  raw: Record<string, unknown>,
-  field: string,
-  value: unknown,
-): void {
-  const llm: Record<string, unknown> =
-    raw.llm != null && typeof raw.llm === "object" && !Array.isArray(raw.llm)
-      ? (raw.llm as Record<string, unknown>)
-      : {};
-  const existing = llm.default;
-  const defaultBlock: Record<string, unknown> =
-    existing != null && typeof existing === "object" && !Array.isArray(existing)
-      ? (existing as Record<string, unknown>)
-      : {};
-  defaultBlock[field] = value;
-  llm.default = defaultBlock;
-  raw.llm = llm;
-}
-
 /**
  * Safely set a nested field on a raw config object's `services` map.
  *
  * Ensures the `services` and service-level objects exist before writing,
  * so callers don't need to guard against undefined intermediate keys.
  *
- * Example: `setServiceField(raw, "inference", "mode", "managed")`
- * produces `raw.services.inference.mode = "managed"`.
+ * Example: `setServiceField(raw, "image-generation", "mode", "managed")`
+ * produces `raw.services["image-generation"].mode = "managed"`.
  */
 export function setServiceField(
   raw: Record<string, unknown>,

package/src/config/schema.ts

@@ -25,6 +25,7 @@ import {
   TwilioConfigSchema,
   WhatsAppConfigSchema,
 } from "./schemas/channels.js";
+import { CompactionConfigSchema } from "./schemas/compaction.js";
 import { ConversationsConfigSchema } from "./schemas/conversations.js";
 import { FilingConfigSchema } from "./schemas/filing.js";
 import { HeartbeatConfigSchema } from "./schemas/heartbeat.js";
@@ -32,6 +33,7 @@ import { HostBrowserConfigSchema } from "./schemas/host-browser.js";
 import { IngressConfigSchema } from "./schemas/ingress.js";
 import { JournalConfigSchema } from "./schemas/journal.js";
 import { LLMSchema } from "./schemas/llm.js";
+import { LlmRequestLogsConfigSchema } from "./schemas/llm-request-logs.js";
 import {
   AuditLogConfigSchema,
   LogFileConfigSchema,
@@ -51,6 +53,7 @@ import {
   RateLimitConfigSchema,
   TimeoutConfigSchema,
 } from "./schemas/timeouts.js";
+import { ToolsConfigSchema } from "./schemas/tools.js";
 import { UpdatesConfigSchema } from "./schemas/updates.js";
 import { WorkspaceGitConfigSchema } from "./schemas/workspace-git.js";
 
@@ -81,6 +84,7 @@ export const AssistantConfigSchema = z
     // ensures the loader's leaf-deletion recovery path can repair a partially
     // invalid `llm` block without falling back to `cloneDefaultConfig()`.
     llm: LLMSchema.default(LLMSchema.parse({})),
+    llmRequestLogs: LlmRequestLogsConfigSchema,
     filing: FilingConfigSchema.default(FilingConfigSchema.parse({})),
     heartbeat: HeartbeatConfigSchema.default(HeartbeatConfigSchema.parse({})),
     updates: UpdatesConfigSchema.default(UpdatesConfigSchema.parse({})),
@@ -99,6 +103,9 @@ export const AssistantConfigSchema = z
     workspaceGit: WorkspaceGitConfigSchema.default(
       WorkspaceGitConfigSchema.parse({}),
     ),
+    compaction: CompactionConfigSchema.default(
+      CompactionConfigSchema.parse({}),
+    ),
     twilio: TwilioConfigSchema.default(TwilioConfigSchema.parse({})),
     calls: CallsConfigSchema.default(CallsConfigSchema.parse({})),
     whatsapp: WhatsAppConfigSchema.default(WhatsAppConfigSchema.parse({})),
@@ -111,6 +118,7 @@ export const AssistantConfigSchema = z
       NotificationsConfigSchema.parse({}),
     ),
     ui: UiConfigSchema.default(UiConfigSchema.parse({})),
+    tools: ToolsConfigSchema.default(ToolsConfigSchema.parse({})),
     // Per-plugin config blocks keyed by plugin name. The schema is intentionally
     // permissive — each plugin's manifest supplies its own validator which the
     // plugin bootstrap (`external-plugins-bootstrap.ts`) runs against the raw
@@ -141,13 +149,6 @@ export const AssistantConfigSchema = z
       .max(200, "maxStepsPerSession must be <= 200")
       .default(50)
       .describe("Maximum number of computer-use steps per session"),
-    systemPromptPrefix: z
-      .string({ error: "systemPromptPrefix must be a string" })
-      .nullable()
-      .default(null)
-      .describe(
-        "Custom text injected at the very beginning of the system prompt. Defaults to null (no injection).",
-      ),
   })
   .superRefine((config, ctx) => {
     const llmContextWindow = config.llm?.default?.contextWindow;

package/src/config/schemas/__tests__/llm-request-logs.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+
+import { LlmRequestLogsConfigSchema } from "../llm-request-logs.js";
+
+describe("LlmRequestLogsConfigSchema", () => {
+  test("parses undefined to the local default", () => {
+    expect(LlmRequestLogsConfigSchema.parse(undefined)).toEqual({
+      readSource: "local",
+    });
+  });
+
+  test("parses an explicit local readSource", () => {
+    expect(
+      LlmRequestLogsConfigSchema.parse({ readSource: "local" }),
+    ).toEqual({ readSource: "local" });
+  });
+
+  test("parses an explicit clickhouse readSource with defaulted connection fields", () => {
+    expect(
+      LlmRequestLogsConfigSchema.parse({ readSource: "clickhouse" }),
+    ).toEqual({
+      readSource: "clickhouse",
+      clickhouse: {
+        database: "default",
+        table: "llm_request_logs",
+        user: "default",
+      },
+    });
+  });
+
+  test("rejects an unknown readSource", () => {
+    expect(() =>
+      LlmRequestLogsConfigSchema.parse({ readSource: "postgres" }),
+    ).toThrow();
+  });
+});

package/src/config/schemas/__tests__/memory-v2.test.ts

@@ -32,6 +32,11 @@ describe("MemoryV2ConfigSchema", () => {
         model: "Alibaba-NLP/gte-reranker-modernbert-base",
         dtype: "q8",
       },
+      router: {
+        enabled: false,
+        max_page_ids: 25,
+        router_prompt_path: null,
+      },
     });
   });
 
@@ -155,6 +160,50 @@ describe("MemoryV2ConfigSchema", () => {
     expect(() => MemoryV2ConfigSchema.parse({ epsilon: -0.01 })).toThrow();
     expect(() => MemoryV2ConfigSchema.parse({ epsilon: 1.5 })).toThrow();
   });
+
+  test("router defaults to disabled with max_page_ids=25", () => {
+    const parsed = MemoryV2ConfigSchema.parse({});
+    expect(parsed.router.enabled).toBe(false);
+    expect(parsed.router.max_page_ids).toBe(25);
+  });
+
+  test("accepts explicit router overrides", () => {
+    const parsed = MemoryV2ConfigSchema.parse({
+      router: { enabled: true, max_page_ids: 50 },
+    });
+    expect(parsed.router.enabled).toBe(true);
+    expect(parsed.router.max_page_ids).toBe(50);
+  });
+
+  test("rejects router.max_page_ids below 1", () => {
+    expect(() =>
+      MemoryV2ConfigSchema.parse({ router: { max_page_ids: 0 } }),
+    ).toThrow();
+  });
+
+  test("rejects router.max_page_ids above 100", () => {
+    expect(() =>
+      MemoryV2ConfigSchema.parse({ router: { max_page_ids: 101 } }),
+    ).toThrow();
+  });
+
+  test("router_prompt_path defaults to null", () => {
+    const parsed = MemoryV2ConfigSchema.parse({});
+    expect(parsed.router.router_prompt_path).toBeNull();
+  });
+
+  test("accepts an explicit router_prompt_path override", () => {
+    const parsed = MemoryV2ConfigSchema.parse({
+      router: { router_prompt_path: "~/prompts/router.md" },
+    });
+    expect(parsed.router.router_prompt_path).toBe("~/prompts/router.md");
+  });
+
+  test("rejects non-string router_prompt_path", () => {
+    expect(() =>
+      MemoryV2ConfigSchema.parse({ router: { router_prompt_path: 42 } }),
+    ).toThrow();
+  });
 });
 
 describe("MemoryConfigSchema integration with v2 block", () => {

package/src/config/schemas/call-site-catalog.ts

@@ -114,6 +114,27 @@ const CATALOG_RECORD: CatalogRecord = {
     description: "Background sweep pass for V2 memory maintenance.",
     domain: "memory",
   },
+  memoryRouter: {
+    id: "memoryRouter",
+    displayName: "Memory Router",
+    description:
+      "Selects which concept pages to inject for the next agent turn by routing over a cached page index.",
+    domain: "memory",
+  },
+  memoryV2Consolidation: {
+    id: "memoryV2Consolidation",
+    displayName: "Memory V2 Consolidation",
+    description:
+      "Routes accumulated buffer entries into concept pages and rewrites the recent summary during V2 memory maintenance.",
+    domain: "memory",
+  },
+  memoryRetrospective: {
+    id: "memoryRetrospective",
+    displayName: "Memory Retrospective",
+    description:
+      "Background agent that re-reads recent conversation messages and saves what wasn't captured in the moment by calling the `remember` tool.",
+    domain: "memory",
+  },
   recall: {
     id: "recall",
     displayName: "Recall",
@@ -152,7 +173,14 @@ const CATALOG_RECORD: CatalogRecord = {
     id: "conversationStarters",
     displayName: "Conversation Starters",
     description:
-      "Generates suggested conversation openers for the home screen.",
+      "Generates the personalized starter chips on the empty conversation page.",
+    domain: "ui",
+  },
+  replySuggestion: {
+    id: "replySuggestion",
+    displayName: "Reply Suggestion",
+    description:
+      "Generates the tab-to-accept reply hint shown in the chat composer after each assistant turn.",
     domain: "ui",
   },
   conversationTitle: {
@@ -191,12 +219,6 @@ const CATALOG_RECORD: CatalogRecord = {
     description: "Handles conversational approval flows.",
     domain: "ui",
   },
-  feedEventCopy: {
-    id: "feedEventCopy",
-    displayName: "Feed Event Copy",
-    description: "Generates copy for home feed event cards.",
-    domain: "ui",
-  },
   trustRuleSuggestion: {
     id: "trustRuleSuggestion",
     displayName: "Trust Rule Suggestion",

package/src/config/schemas/channels.ts

@@ -10,6 +10,10 @@ export const TwilioConfigSchema = z
       .string({ error: "twilio.phoneNumber must be a string" })
       .default("")
       .describe("Twilio phone number used for outbound calls and SMS"),
+    setupStarted: z
+      .boolean({ error: "twilio.setupStarted must be a boolean" })
+      .default(false)
+      .describe("Whether Twilio setup has ever been started"),
   })
   .describe("Twilio account configuration");
 
@@ -111,6 +115,10 @@ export const SlackConfigSchema = z
       .string({ error: "slack.teamName must be a string" })
       .default("")
       .describe("Slack workspace team name"),
+    teamUrl: z
+      .string({ error: "slack.teamUrl must be a string" })
+      .default("")
+      .describe("Slack workspace URL"),
     botUserId: z
       .string({ error: "slack.botUserId must be a string" })
       .default("")

package/src/config/schemas/compaction.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const CompactionConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "compaction.enabled must be a boolean" })
+      .default(true)
+      .describe("Whether assistant-driven context compaction is enabled"),
+    autoThreshold: z
+      .number({ error: "compaction.autoThreshold must be a number" })
+      .finite("compaction.autoThreshold must be finite")
+      .gt(0, "compaction.autoThreshold must be greater than 0")
+      .lte(1, "compaction.autoThreshold must be less than or equal to 1")
+      .default(0.7)
+      .describe(
+        "Fraction of the context window at which automatic compaction fires",
+      ),
+    prompt: z
+      .string({ error: "compaction.prompt must be a string" })
+      .nullable()
+      .optional()
+      .describe(
+        "Custom compaction instruction. When set, replaces the generic default verbatim. The `{image_manifest}` placeholder is still interpolated.",
+      ),
+  })
+  .describe("Assistant-driven context compaction");
+
+export type CompactionConfig = z.infer<typeof CompactionConfigSchema>;

package/src/config/schemas/heartbeat.ts

@@ -47,6 +47,15 @@ export const HeartbeatConfigSchema = z
       .describe(
         "Hour of the day (0-23) when heartbeat checks stop, or null to disable active hours restriction",
       ),
+    maxConsecutiveRuns: z
+      .number({ error: "heartbeat.maxConsecutiveRuns must be a number" })
+      .int("heartbeat.maxConsecutiveRuns must be an integer")
+      .positive("heartbeat.maxConsecutiveRuns must be a positive integer")
+      .nullable()
+      .default(3)
+      .describe(
+        "Maximum heartbeats that can run consecutively without a guardian message. Counter resets when the guardian sends a message. Set to null for unlimited.",
+      ),
   })
   .describe("Periodic heartbeat configuration for health monitoring")
   .superRefine((config, ctx) => {