@vellumai/assistant 0.8.1 → 0.8.3

package/src/config/llm-resolver.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { getCatalogProviderForModel } from "../providers/model-catalog.js";
+import { CALL_SITE_DEFAULTS } from "./call-site-defaults.js";
 import {
   type LLMCallSite,
   LLMConfigBase,
@@ -56,7 +57,9 @@ export function resolveCallSiteConfig(
     opts.overrideProfile != null
       ? llm.profiles?.[opts.overrideProfile]
       : undefined;
-  const site = llm.callSites?.[callSite];
+  const site =
+    llm.callSites?.[callSite] ??
+    effectiveDefault(callSite, llm, opts.overrideProfile != null);
 
   if (callSite === "mainAgent") {
     appendCallSiteLayers(layers, callSite, llm, site);
@@ -77,6 +80,54 @@ export function resolveCallSiteConfig(
 
 type Mergeable = Record<string, unknown>;
 
+/**
+ * Returns the resolved default profile key for a call site, accounting for
+ * the `custom-*` user-profile fallback when the managed profile is unavailable.
+ */
+export function resolveDefaultProfileKey(
+  callSite: LLMCallSite,
+  llm: z.infer<typeof LLMSchema>,
+): string | undefined {
+  const dflt = CALL_SITE_DEFAULTS[callSite];
+  if (dflt?.profile == null) return undefined;
+  const target = llm.profiles?.[dflt.profile];
+  if (target != null && target.status !== "disabled") return dflt.profile;
+  const customKey = `custom-${dflt.profile}`;
+  const customTarget = llm.profiles?.[customKey];
+  if (customTarget != null && customTarget.status !== "disabled")
+    return customKey;
+  return undefined;
+}
+
+function effectiveDefault(
+  callSite: LLMCallSite,
+  llm: z.infer<typeof LLMSchema>,
+  hasOverrideProfile = false,
+): z.infer<typeof LLMSchema>["callSites"][LLMCallSite] | undefined {
+  const dflt = CALL_SITE_DEFAULTS[callSite];
+  if (dflt == null) return undefined;
+  const targetProfile =
+    dflt.profile != null ? llm.profiles?.[dflt.profile] : undefined;
+  const profileUnavailable =
+    dflt.profile != null &&
+    (targetProfile == null || targetProfile.status === "disabled");
+
+  if (profileUnavailable && !hasOverrideProfile) {
+    const customKey = `custom-${dflt.profile}`;
+    const customProfile = llm.profiles?.[customKey];
+    if (customProfile != null && customProfile.status !== "disabled") {
+      return { ...dflt, profile: customKey };
+    }
+  }
+
+  const stripProfile = hasOverrideProfile || profileUnavailable;
+  if (stripProfile) {
+    const { profile: _profile, ...rest } = dflt;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+  }
+  return dflt;
+}
+
 function withImpliedProviderForKnownModel(source: Mergeable): Mergeable {
   if (source.provider !== undefined) return source;
   const model = source.model;

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 =
   | {
@@ -683,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,
-          );
-          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)",
+    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",
           );
-          // 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",
-        );
       }
     }
 
@@ -763,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)) {
@@ -842,6 +848,26 @@ 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.

package/src/config/schema.ts

@@ -20,11 +20,13 @@ import { AnalysisConfigSchema } from "./schemas/analysis.js";
 import { BackupConfigSchema } from "./schemas/backup.js";
 import { CallsConfigSchema } from "./schemas/calls.js";
 import {
+  A2AConfigSchema,
   SlackConfigSchema,
   TelegramConfigSchema,
   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";
@@ -52,6 +54,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";
 
@@ -82,9 +85,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.default(
-      LlmRequestLogsConfigSchema.parse({}),
-    ),
+    llmRequestLogs: LlmRequestLogsConfigSchema,
     filing: FilingConfigSchema.default(FilingConfigSchema.parse({})),
     heartbeat: HeartbeatConfigSchema.default(HeartbeatConfigSchema.parse({})),
     updates: UpdatesConfigSchema.default(UpdatesConfigSchema.parse({})),
@@ -103,11 +104,15 @@ 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({})),
     telegram: TelegramConfigSchema.default(TelegramConfigSchema.parse({})),
     slack: SlackConfigSchema.default(SlackConfigSchema.parse({})),
+    a2a: A2AConfigSchema.default(A2AConfigSchema.parse({})),
     ingress: IngressConfigSchema,
     platform: PlatformConfigSchema.default(PlatformConfigSchema.parse({})),
     daemon: DaemonConfigSchema.default(DaemonConfigSchema.parse({})),
@@ -115,6 +120,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
@@ -145,13 +151,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

@@ -33,7 +33,7 @@ describe("MemoryV2ConfigSchema", () => {
         dtype: "q8",
       },
       router: {
-        enabled: false,
+        enabled: true,
         max_page_ids: 25,
         router_prompt_path: null,
       },
@@ -161,9 +161,9 @@ describe("MemoryV2ConfigSchema", () => {
     expect(() => MemoryV2ConfigSchema.parse({ epsilon: 1.5 })).toThrow();
   });
 
-  test("router defaults to disabled with max_page_ids=25", () => {
+  test("router defaults to enabled with max_page_ids=25", () => {
     const parsed = MemoryV2ConfigSchema.parse({});
-    expect(parsed.router.enabled).toBe(false);
+    expect(parsed.router.enabled).toBe(true);
     expect(parsed.router.max_page_ids).toBe(25);
   });
 

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");
 
@@ -95,6 +99,15 @@ export const TelegramConfigSchema = z
   })
   .describe("Telegram bot channel configuration");
 
+export const A2AConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "a2a.enabled must be a boolean" })
+      .default(false)
+      .describe("Whether the A2A channel is enabled"),
+  })
+  .describe("Agent-to-Agent protocol channel configuration");
+
 export const SlackConfigSchema = z
   .object({
     deliverAuthBypass: z
@@ -111,6 +124,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/conversations.ts

@@ -10,6 +10,16 @@ export const ConversationsConfigSchema = z
       .describe(
         "When true, skip the second-pass title regeneration that fires after the third user turn. The initial auto-generated title and manual renames are unaffected.",
       ),
+    backgroundInjection: z
+      .string({
+        error: "conversations.backgroundInjection must be a string",
+      })
+      .default(
+        "This is a background turn — your guardian isn't watching. If anything noteworthy comes up, send them a notification so they see it when they're back by invoking the `notifications` skill (`assistant notifications send --message \"...\"`)",
+      )
+      .describe(
+        "Inner text injected into the tail user message of non-interactive turns in background/scheduled conversations. The injector wraps this in <background_turn>...</background_turn> tags. Empty string disables the injection.",
+      ),
   })
   .describe("Conversation behavior configuration");
 

package/src/config/schemas/heartbeat.ts

@@ -47,6 +47,29 @@ 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.",
+      ),
+    disposition: z
+      .string({ error: "heartbeat.disposition must be a string" })
+      .default(
+        `This is your time to do something useful, interesting, or creative while your guardian is away.
+
+Before checking on anything, ask yourself: is there something I want to work on, think about, or make progress on right now? A project, an idea, something I noticed, something I've been meaning to get to. If so, do it.
+
+If you do something worth sharing — built something, noticed something, had an idea — send your guardian a notification so they see it when they're back.
+
+If nothing needs attention and nothing stirs, that's fine. But make sure you actually considered it first rather than defaulting to "nothing to do."`,
+      )
+      .describe(
+        "Inner text injected into the heartbeat prompt. The service wraps this in <heartbeat-disposition>...</heartbeat-disposition> tags. Empty string disables the block.",
+      ),
   })
   .describe("Periodic heartbeat configuration for health monitoring")
   .superRefine((config, ctx) => {

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

@@ -8,6 +8,10 @@
  * from the credential store (`clickhouse:url`, `clickhouse:password`).
  * The connection options below describe everything else (database/table/user).
  *
+ * The shape is a discriminated union on `readSource` so the `clickhouse`
+ * block only exists on the ClickHouse branch — there's no stray defaults
+ * sitting around when the source is local.
+ *
  * Note: the existing retention setting lives under
  * `memory.cleanup.llmRequestLogRetentionMs` and is independent of this block.
  * That covers when local rows get pruned; this block governs where reads
@@ -37,18 +41,38 @@ export const LlmRequestLogsClickHouseConfigSchema = z
     "ClickHouse connection settings used when `readSource` is `clickhouse`",
   );
 
-export const LlmRequestLogsConfigSchema = z
+const LocalLlmRequestLogsConfigSchema = z
+  .object({
+    readSource: z.literal("local"),
+  })
+  .describe("Read LLM request logs from local SQLite (default).");
+
+const ClickHouseLlmRequestLogsConfigSchema = z
   .object({
-    readSource: z
-      .enum(["local", "clickhouse"])
-      .default("local")
-      .describe(
-        "Where to read LLM request logs from for Inspector queries. `local` reads the SQLite source-of-truth (default, lowest latency). `clickhouse` reads the mirror, which retains data longer than local but only sees writes that the mirror job has flushed.",
-      ),
+    readSource: z.literal("clickhouse"),
     clickhouse: LlmRequestLogsClickHouseConfigSchema.default(
       LlmRequestLogsClickHouseConfigSchema.parse({}),
     ),
   })
+  .describe(
+    "Read LLM request logs from the ClickHouse mirror. Requires the `clickhouse:url` and `clickhouse:password` credentials to be set.",
+  );
+
+// The default is baked into the export so the schema matches the sibling
+// pattern across `assistant/src/config/schemas/*` — `Schema.parse(undefined)`
+// returns documented defaults. The discriminated union has no inherent
+// default (no shared discriminator value), so we explicitly select the
+// `local` branch.
+//
+// Note: `LlmRequestLogsConfigSchema.parse({})` still throws — a discriminated
+// union cannot pick a branch without a discriminator. Use `parse(undefined)`
+// or omit the field entirely to get the default.
+export const LlmRequestLogsConfigSchema = z
+  .discriminatedUnion("readSource", [
+    LocalLlmRequestLogsConfigSchema,
+    ClickHouseLlmRequestLogsConfigSchema,
+  ])
+  .default({ readSource: "local" })
   .describe("LLM request log read source configuration");
 
 export type LlmRequestLogsConfig = z.infer<typeof LlmRequestLogsConfigSchema>;

package/src/config/schemas/llm.ts

@@ -20,6 +20,7 @@ const LLMProvider = z.enum([
   "ollama",
   "fireworks",
   "openrouter",
+  "openai-compatible",
 ]);
 type LLMProvider = z.infer<typeof LLMProvider>;
 

package/src/config/schemas/memory-retrieval.ts

@@ -284,6 +284,21 @@ const MemoryInjectionConfigSchema = z
     "Controls how many memory items are injected at conversation start and per turn",
   );
 
+const ScratchpadInjectionConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({
+        error: "memory.retrieval.scratchpadInjection.enabled must be a boolean",
+      })
+      .default(true)
+      .describe(
+        "Whether NOW.md scratchpad content is injected into the conversation prompt. Injection occurs on the first turn and post-compaction; flipping this off takes effect on the next conversation or compaction.",
+      ),
+  })
+  .describe(
+    "Controls whether the user-maintained NOW.md scratchpad is injected into prompts",
+  );
+
 export const MemoryRetrievalConfigSchema = z
   .object({
     maxInjectTokens: z
@@ -312,6 +327,9 @@ export const MemoryRetrievalConfigSchema = z
     injection: MemoryInjectionConfigSchema.default(
       MemoryInjectionConfigSchema.parse({}),
     ),
+    scratchpadInjection: ScratchpadInjectionConfigSchema.default(
+      ScratchpadInjectionConfigSchema.parse({}),
+    ),
   })
   .describe(
     "Controls how memories are retrieved and injected into conversations",

package/src/config/schemas/memory-retrospective.ts

@@ -40,7 +40,7 @@ export const MemoryRetrospectiveConfigSchema = z
       ),
   })
   .describe(
-    "Controls the memory-retrospective background pass triggered by the `memory-retrospective` feature flag. Model selection lives under llm.callSites.memoryRetrospective.",
+    "Controls the memory-retrospective background pass. Model selection lives under llm.callSites.memoryRetrospective.",
   );
 
 export type MemoryRetrospectiveConfig = z.infer<

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

@@ -260,9 +260,9 @@ export const MemoryV2ConfigSchema = z
       .object({
         enabled: z
           .boolean()
-          .default(false)
+          .default(true)
           .describe(
-            "Whether to use the LLM router as the per-turn page-selection mechanism in place of spreading activation. Disabled by default — opt in once the router orchestration and dispatcher land.",
+            "Whether to use the LLM router as the per-turn page-selection mechanism in place of spreading activation. Enabled by default.",
           ),
         max_page_ids: z
           .number()
@@ -283,9 +283,9 @@ export const MemoryV2ConfigSchema = z
             "Optional path to a file whose contents replace the bundled router prompt. Absolute paths are used as-is, a leading `~/` is expanded to the home directory, otherwise the path is resolved under the workspace root. The loaded contents may include `{{ASSISTANT_NAME}}`, `{{USER_NAME}}`, and `{{PAGE_INDEX}}`, which are substituted at runtime. If the file is missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
           ),
       })
-      .default({ enabled: false, max_page_ids: 25, router_prompt_path: null })
+      .default({ enabled: true, max_page_ids: 25, router_prompt_path: null })
       .describe(
-        "LLM router configuration. When enabled, a single Sonnet router call replaces spreading activation for per-turn page selection.",
+        "LLM router configuration. When enabled, a single router LLM call replaces spreading activation for per-turn page selection.",
       ),
   })
   .describe(

package/src/config/schemas/memory.ts

@@ -23,7 +23,9 @@ export const MemoryConfigSchema = z
     enabled: z
       .boolean({ error: "memory.enabled must be a boolean" })
       .default(true)
-      .describe("Whether the long-term memory system is enabled"),
+      .describe(
+        "Whether the long-term memory system is enabled — gates background memory jobs, embedding generation, and `<memory>` block injection into user messages",
+      ),
     embeddings: MemoryEmbeddingsConfigSchema.default(
       MemoryEmbeddingsConfigSchema.parse({}),
     ),

package/src/config/schemas/tools.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const ToolsConfigSchema = z
+  .object({
+    exclude: z
+      .array(z.string(), { error: "tools.exclude must be an array of strings" })
+      .default([])
+      .describe(
+        "Tool names to suppress. Excluded tools are not sent to the LLM. Names match `ToolDefinition.name` exactly (e.g. `bash`, `mcp__server__tool`).",
+      ),
+  })
+  .describe("Tool visibility configuration");
+
+export type ToolsConfig = z.infer<typeof ToolsConfigSchema>;