@vellumai/assistant 0.7.0 → 0.7.2

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

@@ -0,0 +1,271 @@
+import { type LLMCallSite } from "./llm.js";
+
+export const CALL_SITE_DOMAINS = [
+  { id: "agentLoop", displayName: "Agent Loop" },
+  { id: "memory", displayName: "Memory" },
+  { id: "workspace", displayName: "Workspace" },
+  { id: "ui", displayName: "UI" },
+  { id: "notifications", displayName: "Notifications" },
+  { id: "skills", displayName: "Skills" },
+] as const;
+
+export type CallSiteDomainId = (typeof CALL_SITE_DOMAINS)[number]["id"];
+
+export interface CallSiteDomainEntry {
+  id: CallSiteDomainId;
+  displayName: string;
+}
+
+export interface CallSiteEntry {
+  id: LLMCallSite;
+  displayName: string;
+  description: string;
+  domain: CallSiteDomainId;
+}
+
+/**
+ * Keyed by every member of LLMCallSite. TypeScript enforces exhaustiveness:
+ * adding or removing a value from LLMCallSiteEnum without updating this object
+ * is a compile error — no runtime drift guard needed.
+ */
+type CatalogRecord = {
+  [K in LLMCallSite]: {
+    id: K;
+    displayName: string;
+    description: string;
+    domain: CallSiteDomainId;
+  };
+};
+
+const CATALOG_RECORD: CatalogRecord = {
+  // agentLoop
+  mainAgent: {
+    id: "mainAgent",
+    displayName: "Main Agent",
+    description: "The primary conversation agent that handles user messages.",
+    domain: "agentLoop",
+  },
+  subagentSpawn: {
+    id: "subagentSpawn",
+    displayName: "Subagent Spawn",
+    description: "Spawns a subagent to handle a delegated subtask.",
+    domain: "agentLoop",
+  },
+  heartbeatAgent: {
+    id: "heartbeatAgent",
+    displayName: "Heartbeat Agent",
+    description: "Runs background tasks and proactive checks on a schedule.",
+    domain: "agentLoop",
+  },
+  filingAgent: {
+    id: "filingAgent",
+    displayName: "Filing Agent",
+    description:
+      "Files memories and updates the knowledge base after conversations.",
+    domain: "agentLoop",
+  },
+  compactionAgent: {
+    id: "compactionAgent",
+    displayName: "Compaction Agent",
+    description: "Compacts conversation history to stay within context limits.",
+    domain: "agentLoop",
+  },
+  analyzeConversation: {
+    id: "analyzeConversation",
+    displayName: "Analyze Conversation",
+    description: "Analyzes conversation content for summaries and insights.",
+    domain: "agentLoop",
+  },
+  callAgent: {
+    id: "callAgent",
+    displayName: "Call Agent",
+    description: "Handles voice call conversations.",
+    domain: "agentLoop",
+  },
+
+  // memory
+  memoryExtraction: {
+    id: "memoryExtraction",
+    displayName: "Memory Extraction",
+    description: "Extracts memorable facts from conversation turns.",
+    domain: "memory",
+  },
+  memoryConsolidation: {
+    id: "memoryConsolidation",
+    displayName: "Memory Consolidation",
+    description: "Merges and deduplicates related memories.",
+    domain: "memory",
+  },
+  memoryRetrieval: {
+    id: "memoryRetrieval",
+    displayName: "Memory Retrieval",
+    description: "Retrieves relevant memories to augment the agent context.",
+    domain: "memory",
+  },
+  memoryV2Migration: {
+    id: "memoryV2Migration",
+    displayName: "Memory V2 Migration",
+    description: "One-time migration of memories to the V2 storage format.",
+    domain: "memory",
+  },
+  memoryV2Sweep: {
+    id: "memoryV2Sweep",
+    displayName: "Memory V2 Sweep",
+    description: "Background sweep pass for V2 memory maintenance.",
+    domain: "memory",
+  },
+  recall: {
+    id: "recall",
+    displayName: "Recall",
+    description: "Searches memory to answer a specific question during a turn.",
+    domain: "memory",
+  },
+  narrativeRefinement: {
+    id: "narrativeRefinement",
+    displayName: "Narrative Refinement",
+    description: "Refines the autobiographical narrative stored in memory.",
+    domain: "memory",
+  },
+  patternScan: {
+    id: "patternScan",
+    displayName: "Pattern Scan",
+    description: "Scans memories for recurring behavioral patterns.",
+    domain: "memory",
+  },
+
+  // workspace
+  conversationSummarization: {
+    id: "conversationSummarization",
+    displayName: "Conversation Summarization",
+    description: "Generates a summary of a completed conversation.",
+    domain: "workspace",
+  },
+  commitMessage: {
+    id: "commitMessage",
+    displayName: "Commit Message",
+    description: "Generates a git commit message for staged changes.",
+    domain: "workspace",
+  },
+
+  // ui
+  conversationStarters: {
+    id: "conversationStarters",
+    displayName: "Conversation Starters",
+    description:
+      "Generates suggested conversation openers for the home screen.",
+    domain: "ui",
+  },
+  conversationTitle: {
+    id: "conversationTitle",
+    displayName: "Conversation Title",
+    description: "Generates a title for a conversation from its content.",
+    domain: "ui",
+  },
+  identityIntro: {
+    id: "identityIntro",
+    displayName: "Identity Intro",
+    description: "Generates the assistant's introductory identity text.",
+    domain: "ui",
+  },
+  emptyStateGreeting: {
+    id: "emptyStateGreeting",
+    displayName: "Empty State Greeting",
+    description: "Generates a greeting shown on the empty conversation screen.",
+    domain: "ui",
+  },
+  guardianQuestionCopy: {
+    id: "guardianQuestionCopy",
+    displayName: "Guardian Question Copy",
+    description: "Generates copy for guardian onboarding questions.",
+    domain: "ui",
+  },
+  approvalCopy: {
+    id: "approvalCopy",
+    displayName: "Approval Copy",
+    description: "Generates copy for tool approval prompts shown to the user.",
+    domain: "ui",
+  },
+  approvalConversation: {
+    id: "approvalConversation",
+    displayName: "Approval Conversation",
+    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",
+    description:
+      "Suggests a trust rule pattern when the user creates a new rule.",
+    domain: "ui",
+  },
+
+  // notifications
+  notificationDecision: {
+    id: "notificationDecision",
+    displayName: "Notification Decision",
+    description:
+      "Decides whether a background event warrants sending a notification.",
+    domain: "notifications",
+  },
+  preferenceExtraction: {
+    id: "preferenceExtraction",
+    displayName: "Preference Extraction",
+    description:
+      "Extracts notification and communication preferences from messages.",
+    domain: "notifications",
+  },
+
+  // skills
+  interactionClassifier: {
+    id: "interactionClassifier",
+    displayName: "Interaction Classifier",
+    description: "Classifies the type of interaction to route it correctly.",
+    domain: "skills",
+  },
+  styleAnalyzer: {
+    id: "styleAnalyzer",
+    displayName: "Style Analyzer",
+    description: "Analyzes the user's communication style for personalization.",
+    domain: "skills",
+  },
+  inviteInstructionGenerator: {
+    id: "inviteInstructionGenerator",
+    displayName: "Invite Instruction Generator",
+    description: "Generates setup instructions for new skill invites.",
+    domain: "skills",
+  },
+  skillCategoryInference: {
+    id: "skillCategoryInference",
+    displayName: "Skill Category Inference",
+    description: "Infers the category of a skill from its description.",
+    domain: "skills",
+  },
+  meetConsentMonitor: {
+    id: "meetConsentMonitor",
+    displayName: "Meet Consent Monitor",
+    description: "Monitors meeting consent signals during live calls.",
+    domain: "skills",
+  },
+  meetChatOpportunity: {
+    id: "meetChatOpportunity",
+    displayName: "Meet Chat Opportunity",
+    description: "Identifies opportunities to engage in meeting chat.",
+    domain: "skills",
+  },
+  inference: {
+    id: "inference",
+    displayName: "Inference",
+    description: "General-purpose LLM inference call site for skill use.",
+    domain: "skills",
+  },
+};
+
+// Source of truth for call-site display metadata. API responses and usage
+// display paths should reuse this catalog instead of defining separate labels.
+export const CALL_SITE_CATALOG: CallSiteEntry[] = Object.values(CATALOG_RECORD);

package/src/config/schemas/calls.ts

@@ -5,7 +5,7 @@ export const VALID_CALLER_IDENTITY_MODES = [
   "assistant_number",
   "user_number",
 ] as const;
-export const CallsDisclosureConfigSchema = z
+const CallsDisclosureConfigSchema = z
   .object({
     enabled: z
       .boolean({ error: "calls.disclosure.enabled must be a boolean" })
@@ -26,7 +26,7 @@ export const CallsDisclosureConfigSchema = z
     "Controls whether and how the assistant discloses its nature at the start of a phone call",
   );
 
-export const CallsSafetyConfigSchema = z
+const CallsSafetyConfigSchema = z
   .object({
     denyCategories: z
       .array(
@@ -41,7 +41,7 @@ export const CallsSafetyConfigSchema = z
   })
   .describe("Safety guardrails for phone calls");
 
-export const CallsVoiceConfigSchema = z
+const CallsVoiceConfigSchema = z
   .object({
     language: z
       .string({ error: "calls.voice.language must be a string" })
@@ -65,7 +65,7 @@ export const CallsVoiceConfigSchema = z
   })
   .describe("Voice and speech settings for phone calls");
 
-export const CallerIdentityConfigSchema = z
+const CallerIdentityConfigSchema = z
   .object({
     allowPerCallOverride: z
       .boolean({
@@ -82,7 +82,7 @@ export const CallerIdentityConfigSchema = z
   })
   .describe("Controls which phone number is shown as the caller ID");
 
-export const CallsVerificationConfigSchema = z
+const CallsVerificationConfigSchema = z
   .object({
     enabled: z
       .boolean({ error: "calls.verification.enabled must be a boolean" })
@@ -232,12 +232,3 @@ export const CallsConfigSchema = z
   .describe(
     "Phone call configuration — controls telephony, voice, safety, and call behavior",
   );
-
-export type CallsConfig = z.infer<typeof CallsConfigSchema>;
-export type CallsDisclosureConfig = z.infer<typeof CallsDisclosureConfigSchema>;
-export type CallsSafetyConfig = z.infer<typeof CallsSafetyConfigSchema>;
-export type CallsVoiceConfig = z.infer<typeof CallsVoiceConfigSchema>;
-export type CallerIdentityConfig = z.infer<typeof CallerIdentityConfigSchema>;
-export type CallsVerificationConfig = z.infer<
-  typeof CallsVerificationConfigSchema
->;

package/src/config/schemas/heartbeat.ts

@@ -1,3 +1,4 @@
+import { Cron } from "croner";
 import { z } from "zod";
 
 export const HeartbeatConfigSchema = z
@@ -12,6 +13,20 @@ export const HeartbeatConfigSchema = z
       .positive("heartbeat.intervalMs must be a positive integer")
       .default(6 * 3_600_000)
       .describe("Time between heartbeat checks in milliseconds"),
+    cronExpression: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Cron expression for heartbeat timing. When set, heartbeats fire at the specified clock times instead of using intervalMs.",
+      ),
+    timezone: z
+      .string()
+      .nullable()
+      .default(null)
+      .describe(
+        "Timezone for cron expression evaluation, e.g. 'America/New_York'. Ignored when cronExpression is null.",
+      ),
     activeHoursStart: z
       .number({ error: "heartbeat.activeHoursStart must be a number" })
       .int("heartbeat.activeHoursStart must be an integer")
@@ -80,6 +95,54 @@ export const HeartbeatConfigSchema = z
         message,
       });
     }
+
+    // Validate cronExpression and timezone when cronExpression is set.
+    // Separate the validations so timezone errors are attributed to the
+    // timezone path — if both paths point at cronExpression, the config
+    // loader's delete-and-retry would strip cronExpression but leave the
+    // invalid timezone, cascading to a full defaults reset.
+    if (config.cronExpression != null) {
+      try {
+        new Cron(config.cronExpression, { maxRuns: 0 });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["cronExpression"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      if (config.timezone != null) {
+        try {
+          new Cron(config.cronExpression, {
+            maxRuns: 0,
+            timezone: config.timezone,
+          });
+        } catch {
+          // The cron expression itself is valid (or already flagged above),
+          // so a failure here is from the timezone.
+          try {
+            Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+          } catch (tzErr) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["timezone"],
+              message: tzErr instanceof Error ? tzErr.message : String(tzErr),
+            });
+          }
+        }
+      }
+    } else if (config.timezone != null) {
+      // cronExpression is null but timezone is set — validate timezone independently
+      try {
+        Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+      } catch (err) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["timezone"],
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
   });
 
 export type HeartbeatConfig = z.infer<typeof HeartbeatConfigSchema>;

package/src/config/schemas/inference.ts

@@ -98,7 +98,7 @@ export const ContextWindowConfigSchema = z
       .positive("contextWindow.maxInputTokens must be a positive integer")
       .default(200000)
       .describe(
-        "Conservative cap on input tokens allowed in the context window. Acts as an override that further constrains the model's catalog `contextWindow`; the effective budget is `min(catalog.contextWindow, maxInputTokens)`. Leave at the default to use the model's full native window.",
+        "Conservative cap on input tokens allowed in the context window. Acts as an override that further constrains the model's catalog `contextWindow`; the effective budget is `min(catalog.contextWindow, maxInputTokens)`. Increase this value to opt into larger model-native windows where supported.",
       ),
     targetBudgetRatio: z
       .number({ error: "contextWindow.targetBudgetRatio must be a number" })

package/src/config/schemas/ingress.ts

@@ -1,5 +1,14 @@
 import { z } from "zod";
 
+function emptyOrAbsoluteHttpUrl(fieldPath: string) {
+  return z
+    .string({ error: `${fieldPath} must be a string` })
+    .refine(
+      (val) => val === "" || /^https?:\/\//i.test(val),
+      `${fieldPath} must be an absolute URL starting with http:// or https://`,
+    );
+}
+
 const IngressWebhookConfigSchema = z
   .object({
     secret: z
@@ -39,7 +48,7 @@ const IngressWebhookConfigSchema = z
   })
   .describe("Webhook configuration for ingress event delivery");
 
-export const IngressRateLimitConfigSchema = z
+const IngressRateLimitConfigSchema = z
   .object({
     maxRequestsPerMinute: z
       .number({
@@ -74,12 +83,7 @@ const IngressBaseSchema = z
       .boolean({ error: "ingress.enabled must be a boolean" })
       .optional()
       .describe("Whether the ingress HTTP server is enabled"),
-    publicBaseUrl: z
-      .string({ error: "ingress.publicBaseUrl must be a string" })
-      .refine(
-        (val) => val === "" || /^https?:\/\//i.test(val),
-        "ingress.publicBaseUrl must be an absolute URL starting with http:// or https://",
-      )
+    publicBaseUrl: emptyOrAbsoluteHttpUrl("ingress.publicBaseUrl")
       .default("")
       .describe(
         "Public-facing base URL for the ingress server (used in webhook callbacks)",

package/src/config/schemas/llm.ts

@@ -91,7 +91,6 @@ export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
  * mapping table.
  */
 const EffortEnum = z.enum(["none", "low", "medium", "high", "xhigh", "max"]);
-export type Effort = z.infer<typeof EffortEnum>;
 
 export const SpeedEnum = z.enum(["standard", "fast"]);
 export type Speed = z.infer<typeof SpeedEnum>;
@@ -102,7 +101,6 @@ export type Speed = z.infer<typeof SpeedEnum>;
  * are stripped in `retry.ts` normalization.
  */
 const VerbosityEnum = z.enum(["low", "medium", "high"]);
-export type Verbosity = z.infer<typeof VerbosityEnum>;
 
 // ---------------------------------------------------------------------------
 // Leaf primitives (shared between LLMConfigBase and LLMConfigFragment)
@@ -150,7 +148,6 @@ const ThinkingSchema = z.object({
   enabled: ThinkingEnabledSchema.default(true),
   streamThinking: ThinkingStreamThinkingSchema.default(true),
 });
-export type Thinking = z.infer<typeof ThinkingSchema>;
 
 // Fragment view: every field optional, no defaults injected. Defining this
 // separately (rather than `ThinkingSchema.partial()`) avoids having Zod
@@ -193,6 +190,8 @@ const ContextOverflowRecoveryFragmentSchema = z.object({
 
 // Leaf primitives for context-window fields.
 const ContextEnabledSchema = z.boolean();
+export const DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS = 200000;
+
 const ContextMaxInputTokensSchema = z.number().int().positive();
 const ContextTargetBudgetRatioSchema = z.number().finite().gt(0).lte(1);
 const ContextCompactThresholdSchema = z.number().finite().gt(0).lte(1);
@@ -200,7 +199,9 @@ const ContextSummaryBudgetRatioSchema = z.number().finite().gt(0).lte(1);
 
 const ContextWindowSchema = z.object({
   enabled: ContextEnabledSchema.default(true),
-  maxInputTokens: ContextMaxInputTokensSchema.default(200000),
+  maxInputTokens: ContextMaxInputTokensSchema.default(
+    DEFAULT_CONTEXT_WINDOW_MAX_INPUT_TOKENS,
+  ),
   targetBudgetRatio: ContextTargetBudgetRatioSchema.default(0.3),
   compactThreshold: ContextCompactThresholdSchema.default(0.8),
   summaryBudgetRatio: ContextSummaryBudgetRatioSchema.default(0.05),
@@ -239,12 +240,22 @@ const OpenRouterOnlyItemSchema = z.string().min(1);
 const OpenRouterSchema = z.object({
   only: z.array(OpenRouterOnlyItemSchema).default([]),
 });
-export type OpenRouter = z.infer<typeof OpenRouterSchema>;
 
 const OpenRouterDeepPartialSchema = z.object({
   only: z.array(OpenRouterOnlyItemSchema).optional(),
 });
 
+// ---------------------------------------------------------------------------
+// Profile metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Distinguishes daemon-managed profiles (overwritten on every startup) from
+ * user-created ones (never touched by the daemon).
+ */
+const ProfileSource = z.enum(["managed", "user"]);
+type ProfileSource = z.infer<typeof ProfileSource>;
+
 // ---------------------------------------------------------------------------
 // Pricing overrides
 // ---------------------------------------------------------------------------
@@ -255,7 +266,6 @@ const PricingOverrideSchema = z.object({
   inputPer1M: z.number().nonnegative(),
   outputPer1M: z.number().nonnegative(),
 });
-export type PricingOverride = z.infer<typeof PricingOverrideSchema>;
 
 // ---------------------------------------------------------------------------
 // Base config (all fields defaulted) and Fragment (all fields optional)
@@ -287,7 +297,7 @@ export type LLMConfigBase = z.infer<typeof LLMConfigBase>;
  * objects so callers can override individual leaves (e.g. `{ thinking:
  * { enabled: false } }`).
  */
-export const LLMConfigFragment = z.object({
+const LLMConfigFragment = z.object({
   provider: LLMProvider.optional(),
   model: ModelSchema.optional(),
   maxTokens: MaxTokensSchema.optional(),
@@ -299,17 +309,30 @@ export const LLMConfigFragment = z.object({
   contextWindow: ContextWindowDeepPartialSchema.optional(),
   openrouter: OpenRouterDeepPartialSchema.optional(),
 });
-export type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
+type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
+
+/**
+ * A named profile entry: an `LLMConfigFragment` augmented with
+ * presentation/ownership metadata. These fields are intentionally kept off
+ * `LLMConfigFragment` so they don't leak into `LLMCallSiteConfig` or the
+ * resolver's deep-merge output.
+ */
+export const ProfileEntry = LLMConfigFragment.extend({
+  source: ProfileSource.optional(),
+  label: z.string().min(1).optional(),
+  description: z.string().optional(),
+});
+export type ProfileEntry = z.infer<typeof ProfileEntry>;
 
 /**
  * Per-call-site config: a fragment plus an optional `profile` reference.
  * The resolver merges in the named profile (if any) before applying
  * call-site-level overrides.
  */
-export const LLMCallSiteConfig = LLMConfigFragment.extend({
+const LLMCallSiteConfig = LLMConfigFragment.extend({
   profile: z.string().min(1).optional(),
 });
-export type LLMCallSiteConfig = z.infer<typeof LLMCallSiteConfig>;
+type LLMCallSiteConfig = z.infer<typeof LLMCallSiteConfig>;
 
 // ---------------------------------------------------------------------------
 // Top-level LLM schema
@@ -318,7 +341,7 @@ export type LLMCallSiteConfig = z.infer<typeof LLMCallSiteConfig>;
 export const LLMSchema = z
   .object({
     default: LLMConfigBase.default(LLMConfigBase.parse({})),
-    profiles: z.record(z.string().min(1), LLMConfigFragment).default({}),
+    profiles: z.record(z.string().min(1), ProfileEntry).default({}),
     // Presentation-only order for named profiles. The resolver ignores this;
     // clients use it to render profile pickers consistently.
     profileOrder: z.array(z.string().min(1)).default([]),

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

@@ -1,29 +1,82 @@
 import { z } from "zod";
 
-export const MemoryJobsConfigSchema = z
-  .object({
-    workerConcurrency: z
-      .number({ error: "memory.jobs.workerConcurrency must be a number" })
-      .int("memory.jobs.workerConcurrency must be an integer")
-      .positive("memory.jobs.workerConcurrency must be a positive integer")
-      .default(2)
-      .describe("Number of concurrent workers processing memory jobs"),
-    batchSize: z
-      .number({ error: "memory.jobs.batchSize must be a number" })
-      .int("memory.jobs.batchSize must be an integer")
-      .positive("memory.jobs.batchSize must be a positive integer")
-      .default(10)
-      .describe("Number of memory items processed per batch"),
-    stalledJobTimeoutMs: z
-      .number({ error: "memory.jobs.stalledJobTimeoutMs must be a number" })
-      .int("memory.jobs.stalledJobTimeoutMs must be an integer")
-      .positive("memory.jobs.stalledJobTimeoutMs must be a positive integer")
-      .default(30 * 60 * 1000)
-      .describe(
-        "Timeout in milliseconds after which a stalled memory job is considered failed",
-      ),
-  })
-  .describe("Memory background job processing configuration");
+const DEFAULT_WORKER_CONCURRENCY = 2;
+const DEFAULT_SLOW_LLM_CONCURRENCY = 1;
+const DEFAULT_FAST_CONCURRENCY = 2;
+const DEFAULT_EMBED_CONCURRENCY = 2;
+
+const positiveInt = (field: string) =>
+  z
+    .number({ error: `memory.jobs.${field} must be a number` })
+    .int(`memory.jobs.${field} must be an integer`)
+    .positive(`memory.jobs.${field} must be a positive integer`);
+
+// Input shape allows all fields to be omitted so we can distinguish
+// "user explicitly set workerConcurrency" from "user accepted the default"
+// when deriving lane caps. The output shape (after transform) always has
+// all four fields populated.
+const MemoryJobsConfigInputSchema = z.object({
+  workerConcurrency: positiveInt("workerConcurrency")
+    .optional()
+    .describe("Number of concurrent workers processing memory jobs"),
+  stalledJobTimeoutMs: positiveInt("stalledJobTimeoutMs")
+    .default(30 * 60 * 1000)
+    .describe(
+      "Timeout in milliseconds after which a stalled memory job is considered failed",
+    ),
+  slowLlmConcurrency: positiveInt("slowLlmConcurrency")
+    .optional()
+    .describe(
+      "Concurrent slow LLM-bound jobs (graph consolidation, narrative refine, etc.)",
+    ),
+  fastConcurrency: positiveInt("fastConcurrency")
+    .optional()
+    .describe(
+      "Concurrent fast jobs (concept-page embed, prunes, media processing, etc.)",
+    ),
+  embedConcurrency: positiveInt("embedConcurrency")
+    .optional()
+    .describe(
+      "Concurrent segment-embed jobs (gated by Qdrant circuit breaker)",
+    ),
+});
+
+export const MemoryJobsConfigSchema = MemoryJobsConfigInputSchema.transform(
+  (input) => {
+    // When `workerConcurrency` is explicitly set but lane caps are not,
+    // derive lane caps so existing user configs gain the per-lane fix
+    // without edits. Explicit lane caps always win.
+    const workerConcurrencyExplicit = input.workerConcurrency !== undefined;
+    const workerConcurrency =
+      input.workerConcurrency ?? DEFAULT_WORKER_CONCURRENCY;
+
+    const slowLlmConcurrency =
+      input.slowLlmConcurrency ??
+      (workerConcurrencyExplicit
+        ? Math.max(1, Math.floor(workerConcurrency / 2))
+        : DEFAULT_SLOW_LLM_CONCURRENCY);
+
+    const fastConcurrency =
+      input.fastConcurrency ??
+      (workerConcurrencyExplicit
+        ? workerConcurrency
+        : DEFAULT_FAST_CONCURRENCY);
+
+    const embedConcurrency =
+      input.embedConcurrency ??
+      (workerConcurrencyExplicit
+        ? workerConcurrency
+        : DEFAULT_EMBED_CONCURRENCY);
+
+    return {
+      workerConcurrency,
+      stalledJobTimeoutMs: input.stalledJobTimeoutMs,
+      slowLlmConcurrency,
+      fastConcurrency,
+      embedConcurrency,
+    };
+  },
+).describe("Memory background job processing configuration");
 
 export const MemoryRetentionConfigSchema = z
   .object({