@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/config/bundled-skills/messaging/SKILL.md

@@ -27,13 +27,6 @@ When the user mentions "email" - sending, reading, checking, decluttering, draft
 
 Do not offer the assistant's own email as an option unless the user specifically asks. If Gmail and Outlook are not connected, guide them through setup.
 
-## Communication Style
-
-- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.
-- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" - not "the OAuth2 access token for google has expired."
-- **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
-- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do - just do it and narrate lightly.
-
 When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally - never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
 
 **Exception: Slack.** Slack messaging should use the Slack Web API directly via CLI, not messaging tools. See the **slack** skill for details.

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -238,8 +238,13 @@ export async function run(
             binding.conversationId,
             "assistant",
             JSON.stringify([{ type: "text", text }]),
-            { automated: true, crossPostedFrom: context.conversationId },
-            { skipIndexing: true },
+            {
+              metadata: {
+                automated: true,
+                crossPostedFrom: context.conversationId,
+              },
+              skipIndexing: true,
+            },
           );
           syncMessageToDisk(
             binding.conversationId,

package/src/config/bundled-skills/schedule/SKILL.md

@@ -94,13 +94,13 @@ The `mode` parameter controls what happens when a schedule fires:
 
 - **execute** (default) - sends the schedule's message to a background assistant conversation for autonomous handling. The assistant processes the message as if the user sent it.
 - **notify** - sends a notification to the user via the notification pipeline. No assistant processing occurs.
-- **script** - runs the `script` field as a shell command directly. No LLM invoked, no conversation created. stdout/stderr are captured in the schedule run record. Exit code 0 = success, non-zero = error. Commands run in the workspace directory with a 60-second timeout.
+- **script** - runs the `script` field as a shell command directly. No LLM invoked, no conversation created. stdout/stderr are captured in the schedule run record. Exit code 0 = success, non-zero = error. Commands run in the workspace directory with a 60-second timeout by default. Override the timeout per schedule with `timeout_ms` (range 1000–1800000 ms) when a script needs more or less time; pass `timeout_ms: null` on update to revert to the default. The guardian can also adjust this from the /assistant/settings/schedules page.
 
 Use `notify` for simple reminders ("remind me to take medicine at 9am"), `execute` for tasks that need assistant action ("check my calendar at 8am and send me a digest"), and `script` for lightweight shell automations that don't need LLM involvement ("refresh a cache", "poll an API", "rotate logs").
 
 ## Conversation Reuse
 
-By default, each schedule run creates a new conversation. For recurring schedules that benefit from accumulating context across runs (e.g. polling-style jobs, daily digests that reference prior results), set `reuse_conversation: true`. When enabled, subsequent runs reuse the conversation from the last successful run instead of creating a new one.
+Recurring schedules reuse the same conversation across runs by default — subsequent runs continue the conversation from the last successful run, preserving context and channel thread continuity. Set `reuse_conversation: false` explicitly if each run should start with a fresh conversation (e.g. independent reports that shouldn't accumulate prior context). One-shot schedules always create a fresh conversation.
 
 - Only applies to **recurring** schedules; ignored for one-shot schedules.
 - If the prior conversation has been deleted, a new one is created automatically.

package/src/config/bundled-skills/schedule/TOOLS.json

@@ -62,7 +62,7 @@
           },
           "reuse_conversation": {
             "type": "boolean",
-            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Useful for polling-style schedules that accumulate context over time. Ignored for one-shot schedules. Defaults to false."
+            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Defaults to true for recurring schedules, false for one-shot. Set to false explicitly if each run should start fresh."
           },
           "max_retries": {
             "type": "integer",
@@ -71,6 +71,10 @@
           "retry_backoff_ms": {
             "type": "integer",
             "description": "Base backoff delay in milliseconds between retries. Exponential backoff is applied. Defaults to 60000."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "description": "For script mode: maximum time in milliseconds the shell command may run before it is killed. Defaults to 60000 (60s). Allowed range: 1000 to 1800000."
           }
         },
         "required": ["name"]
@@ -161,7 +165,7 @@
           },
           "reuse_conversation": {
             "type": "boolean",
-            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Useful for polling-style schedules that accumulate context over time. Ignored for one-shot schedules."
+            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Defaults to true for recurring schedules. Set to false explicitly if each run should start fresh."
           },
           "max_retries": {
             "type": "integer",
@@ -170,6 +174,10 @@
           "retry_backoff_ms": {
             "type": "integer",
             "description": "Base backoff delay in milliseconds between retries. Exponential backoff is applied. Defaults to 60000."
+          },
+          "timeout_ms": {
+            "type": ["integer", "null"],
+            "description": "For script mode: maximum time in milliseconds the shell command may run before it is killed (default 60000, range 1000 to 1800000). Pass null to clear a custom timeout and revert to the default."
           }
         },
         "required": ["job_id"]

package/src/config/bundled-skills/settings/tools/open-system-settings.ts

@@ -42,6 +42,7 @@ export async function run(
     context.sendToClient({
       type: "open_url",
       url: meta.url,
+      conversationId: context.conversationId,
     });
   }
 

package/src/config/bundled-tool-registry.ts

@@ -23,6 +23,7 @@ import * as acpSteer from "./bundled-skills/acp/tools/acp-steer.js";
 import * as appCreate from "./bundled-skills/app-builder/tools/app-create.js";
 import * as appDelete from "./bundled-skills/app-builder/tools/app-delete.js";
 import * as appGenerateIcon from "./bundled-skills/app-builder/tools/app-generate-icon.js";
+import * as appList from "./bundled-skills/app-builder/tools/app-list.js";
 import * as appRefresh from "./bundled-skills/app-builder/tools/app-refresh.js";
 // ── app-control ────────────────────────────────────────────────────────────────
 import * as appControlClick from "./bundled-skills/app-control/tools/app-control-click.js";
@@ -142,6 +143,7 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["app-builder:tools/app-delete.ts", appDelete],
   ["app-builder:tools/app-refresh.ts", appRefresh],
   ["app-builder:tools/app-generate-icon.ts", appGenerateIcon],
+  ["app-builder:tools/app-list.ts", appList],
 
   // app-control
   ["app-control:tools/app-control-start.ts", appControlStart],

package/src/config/call-site-defaults.ts

@@ -23,9 +23,11 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   emptyStateGreeting: { profile: "balanced" },
 
   memoryRouter: {
-    profile: "balanced",
+    profile: "cost-optimized",
     contextWindow: { maxInputTokens: 1000000 },
   },
+  memoryV3RouteL1: { profile: "balanced", temperature: 0 },
+  memoryV3SelectL2: { profile: "balanced", temperature: 0 },
   recall: {
     profile: "balanced",
     maxTokens: 4096,
@@ -47,13 +49,6 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   memoryV2Migration: { profile: "cost-optimized" },
   memoryV2Sweep: { profile: "cost-optimized" },
   memoryV2Consolidation: { profile: "balanced" },
-  // memory v3: cheap filter + descent, capable gate. All three are
-  // selection/classification calls, not generation — pin temperature to 0 so
-  // the same candidate set yields the same keep/descend/select decision instead
-  // of sampling-driven variance.
-  memoryV3Filter: { profile: "cost-optimized", temperature: 0 },
-  memoryV3Descent: { profile: "cost-optimized", temperature: 0 },
-  memoryV3Gate: { profile: "balanced", temperature: 0 },
   conversationSummarization: { profile: "cost-optimized" },
   conversationTitle: { profile: "cost-optimized" },
   approvalCopy: { profile: "cost-optimized" },

package/src/config/feature-flag-cache.ts

@@ -0,0 +1,86 @@
+/**
+ * Module-level cache for resolved feature flag override values.
+ *
+ * Lives in its own module (rather than alongside the resolver in
+ * `assistant-feature-flags.ts`) so test code can read/write the cache
+ * without going through `assistant-feature-flags.ts` — which transitively
+ * pulls `util/logger.js` (pino) and the gateway IPC client. Stdlib-only
+ * by design: this file must remain safe to import from the test
+ * preload's load-time chain, where a broken `node_modules` symlink has
+ * historically tripped the env override (see DB ghost #3,
+ * /workspace/journal/2026-05-25-db-ghost-3-recovery.md).
+ *
+ * State is held on `globalThis.vellumAssistant.featureFlagCache` so test
+ * helpers in `__tests__/` can read/write it WITHOUT importing this
+ * module — they declare the same slot shape locally and access the
+ * globalThis namespace directly. See
+ * `__tests__/feature-flag-test-helpers.ts` for the test-side mirror;
+ * the slot shape MUST stay in sync between the two.
+ *
+ * Both `overrides` and `fromGateway` were previously module-level `let`
+ * bindings inside `assistant-feature-flags.ts`. The semantics are
+ * preserved exactly: `overrides === null` means "no fetch has populated
+ * the cache yet"; `fromGateway === true` means "the cache is
+ * authoritative — `initFeatureFlagOverrides()` should not clobber it".
+ *
+ * Consumers:
+ *   - `assistant-feature-flags.ts` (resolver — reads/writes via gateway fetch)
+ *   - `__tests__/feature-flag-test-helpers.ts` (seeds for tests, via globalThis)
+ */
+
+type FlagSlot = {
+  overrides: Record<string, boolean | string> | null;
+  fromGateway: boolean;
+};
+
+type VellumAssistantNamespace = {
+  featureFlagCache?: FlagSlot;
+};
+
+function slot(): FlagSlot {
+  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
+  const ns = (g.vellumAssistant ??= {});
+  return (ns.featureFlagCache ??= { overrides: null, fromGateway: false });
+}
+
+/** Read the current override cache. `null` means not yet populated. */
+export function getCachedOverrides(): Record<string, boolean | string> | null {
+  return slot().overrides;
+}
+
+/**
+ * True when the cache was populated by either a gateway IPC fetch or by a
+ * test helper. Used by `initFeatureFlagOverrides()` to short-circuit a
+ * second fetch (e.g. when a CLI entry point runs after the daemon has
+ * already initialized) and by tests to prevent the retry loop from
+ * clobbering preseeded state.
+ */
+export function isCachedFromGateway(): boolean {
+  return slot().fromGateway;
+}
+
+/**
+ * Replace the cache with a clone of `overrides`. The `fromGateway` flag
+ * is set by the caller — production callers pass `true` after a
+ * successful gateway fetch; test helpers also pass `true` so subsequent
+ * `initFeatureFlagOverrides()` calls are no-ops.
+ */
+export function setCachedOverrides(
+  overrides: Record<string, boolean | string>,
+  options: { fromGateway: boolean },
+): void {
+  const s = slot();
+  s.overrides = { ...overrides };
+  s.fromGateway = options.fromGateway;
+}
+
+/**
+ * Drop the cache. The next `loadOverrides()` returns an empty record (so
+ * flag checks fall through to registry defaults) and the next
+ * `initFeatureFlagOverrides()` re-fetches from the gateway.
+ */
+export function clearCachedOverrides(): void {
+  const s = slot();
+  s.overrides = null;
+  s.fromGateway = false;
+}

package/src/config/feature-flag-registry.json

@@ -25,6 +25,22 @@
       "description": "Enable user-hosted onboarding flow",
       "defaultEnabled": false
     },
+    {
+      "id": "pre-chat-onboarding-experiment-2026-06-06",
+      "scope": "client",
+      "key": "pre-chat-onboarding-experiment-2026-06-06",
+      "label": "Pre-chat Onboarding Experiment 2026-06-06",
+      "description": "Pre-chat onboarding experiment with control and variant-a arms. Control shows the full funnel; variant-a shows the condensed pared-down flow.",
+      "defaultEnabled": "control"
+    },
+    {
+      "id": "experiment-activation-flow-2026-06-03",
+      "scope": "client",
+      "key": "experiment-activation-flow-2026-06-03",
+      "label": "Activation Flow Experiment 2026-06-03",
+      "description": "Route allowlisted users to the activation-rail bootstrap template after pre-chat. Off by default and targeted through LaunchDarkly.",
+      "defaultEnabled": false
+    },
     {
       "id": "local-docker-enabled",
       "scope": "client",
@@ -41,14 +57,6 @@
       "description": "Enable the A2A (Agent-to-Agent) channel for inter-assistant communication via the open A2A protocol",
       "defaultEnabled": false
     },
-    {
-      "id": "email-channel",
-      "scope": "assistant",
-      "key": "email-channel",
-      "label": "Email Channel",
-      "description": "Enable the entire email integration: email CLI commands, email channel, domain registration, sequences, email readiness probes, invite adapters, and the email-setup skill",
-      "defaultEnabled": false
-    },
     {
       "id": "settings-developer-nav",
       "scope": "assistant",
@@ -57,6 +65,14 @@
       "description": "Control Developer nav visibility in macOS settings",
       "defaultEnabled": false
     },
+    {
+      "id": "system-schedule-toggles",
+      "scope": "assistant",
+      "key": "system-schedule-toggles",
+      "label": "System Schedule Toggles",
+      "description": "Show Heartbeat and Consolidation pause toggles on the schedules settings page. The toggles only pause automatic runs; manual Run now remains available.",
+      "defaultEnabled": false
+    },
     {
       "id": "developer-menu-items",
       "scope": "client",
@@ -190,7 +206,7 @@
       "scope": "assistant",
       "key": "fast-mode",
       "label": "Fast Mode",
-      "description": "Enable Anthropic fast mode for Opus models (4.6, 4.7), delivering up to 2.5x higher output tokens per second at premium pricing",
+      "description": "Enable Anthropic fast mode for Opus models (4.6, 4.7, 4.8), delivering up to 2.5x higher output tokens per second at premium pricing",
       "defaultEnabled": false
     },
     {
@@ -281,14 +297,6 @@
       "description": "Expose the developer-only Compaction Playground tab in macOS Settings and enable the /playground/* HTTP endpoints for exercising compaction conditions. Dev-only; default off.",
       "defaultEnabled": false
     },
-    {
-      "id": "safe-storage-limits",
-      "scope": "assistant",
-      "key": "safe-storage-limits",
-      "label": "Safe Storage Limits",
-      "description": "Enable disk pressure protection flows that block background work and remote actors while storage is critically low.",
-      "defaultEnabled": false
-    },
     {
       "id": "account-deletion",
       "scope": "assistant",
@@ -313,14 +321,6 @@
       "description": "Show the 'Analyze' / 'Analyze conversation' option in conversation context menus and the conversation title actions dropdown.",
       "defaultEnabled": false
     },
-    {
-      "id": "pro-plan-adjust",
-      "scope": "client",
-      "key": "pro-plan-adjust",
-      "label": "Pro Plan Adjust",
-      "description": "Show the rich Plan card (current plan, features, Manage/Upgrade CTA) at the top of the macOS Settings \u2192 Billing tab.",
-      "defaultEnabled": false
-    },
     {
       "id": "external-plugins",
       "scope": "assistant",
@@ -440,6 +440,62 @@
       "label": "Memory Router Playground",
       "description": "Expose the developer-only Memory Router Playground tab in macOS Settings and the /assistant/memory-router-playground web page for dry-running v4 router config overrides against the live page index. Dev-only; default off.",
       "defaultEnabled": false
+    },
+    {
+      "id": "platform-features-in-local-mode",
+      "scope": "assistant",
+      "key": "platform-features-in-local-mode",
+      "label": "Platform Features in Local Mode",
+      "description": "When enabled, the assistant can call the Vellum platform API from local mode. When disabled, all platform API clients in the daemon, gateway, CES, and web UI no-op with a debug log instead of making outbound requests.",
+      "defaultEnabled": true
+    },
+    {
+      "id": "memory-v3-shadow",
+      "scope": "assistant",
+      "key": "memory-v3-shadow",
+      "label": "Memory v3 Shadow",
+      "description": "When on, runs the new memory-v3 topic-tree retrieval alongside v2 in shadow mode: logs selections to memory_v3_selections, does not modify injected context. Off by default.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "memory-v3-live",
+      "scope": "assistant",
+      "key": "memory-v3-live",
+      "label": "Memory v3 Live",
+      "description": "When on, memory-v3 topic-tree retrieval becomes the live injected memory source (suppressing v2 injection). Off by default; only enable after shadow telemetry validates the design.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "empty-state-dynamic-greetings",
+      "scope": "assistant",
+      "key": "empty-state-dynamic-greetings",
+      "label": "Dynamic Empty-State Greetings",
+      "description": "Enable the empty new-chat screen to refresh cached greeting options via the empty-state greeting LLM call site. When off, the assistant serves workspace-authored greetings or static fallbacks only.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "self-intro-greeting",
+      "scope": "both",
+      "key": "self-intro-greeting",
+      "label": "Self-intro first message",
+      "description": "On the first conversation, send a natural self-introduction (e.g. \"Hi Vela, I'm alex. Nice to meet you.\") on the user's behalf and route it through real LLM inference, instead of serving the canned first greeting. Names come from the onboarding context; falls back to the canned greeting when no name is known. Exposed to clients so pre-hatch onboarding can compute the source-of-truth initial message, and to the assistant so older clients can still be gated server-side. See assistant/src/daemon/first-greeting.ts (buildSelfIntroMessage).",
+      "defaultEnabled": false
+    },
+    {
+      "id": "provider-first-profile-creation",
+      "scope": "client",
+      "key": "provider-first-profile-creation",
+      "label": "Provider-First Profile Creation",
+      "description": "New profile creation flow: pick (or inline-create) a provider first, then a model, with pre-filled provider and profile name/key, plus a quick-add \"+\" in the chat composer's Model Profile menu. When off, profile creation uses the previous field order and there is no composer quick-add.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "acp",
+      "scope": "assistant",
+      "key": "acp",
+      "label": "ACP Coding Agents",
+      "description": "Enable spawning and steering external coding agents (Claude Code, Codex, Gemini) via the Agent Client Protocol. Alternative gate to the acp.enabled workspace config field; either enables the subsystem.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/llm-context-resolution.ts

@@ -27,12 +27,21 @@ export function resolveEffectiveContextWindow({
   llm,
   callSite,
   overrideProfile,
+  selectionSeed,
 }: {
   llm: LLMConfig;
   callSite: LLMCallSite;
   overrideProfile?: string;
+  /**
+   * Per-conversation mix seed (the conversation id). Threaded so context-window
+   * sizing for a mix profile reflects the same arm the dispatch path picks.
+   */
+  selectionSeed?: string;
 }): EffectiveContextWindow {
-  const resolved = resolveCallSiteConfig(callSite, llm, { overrideProfile });
+  const resolved = resolveCallSiteConfig(callSite, llm, {
+    overrideProfile,
+    selectionSeed,
+  });
   const catalogModel = PROVIDER_CATALOG.find(
     (provider) => provider.id === resolved.provider,
   )?.models.find((model) => model.id === resolved.model);

package/src/config/llm-resolver.ts

@@ -42,33 +42,60 @@ import {
  * resolver stays pure; schema validation in `LLMSchema.superRefine` catches
  * unknown `activeProfile` references at config-load time.
  *
- * Pure & synchronous: no I/O, no async work.
+ * A profile reference that points at a "mix" profile is expanded to one of its
+ * constituent profiles by a seeded weighted pick (see `resolveProfileFragment`
+ * and `opts.selectionSeed`). Expansion happens uniformly at every dereference
+ * spot, so a mix works as `activeProfile`, `overrideProfile`, or a call-site
+ * `profile`.
+ *
+ * Pure & synchronous: no I/O, no async work. (Random selection only occurs for
+ * mix profiles when no `selectionSeed` is supplied; with a seed the pick is
+ * deterministic.)
  */
+export interface ResolveCallSiteOpts {
+  overrideProfile?: string;
+  /**
+   * Per-conversation seed for expanding `mix` profiles. The chosen constituent
+   * is a deterministic function of `selectionSeed` + the mix profile's own
+   * name, so every `resolveCallSiteConfig` call for the same conversation picks
+   * the SAME arm (stable across turns, retries, and restarts). Pass the
+   * conversation id. When absent, the resolver falls back to a fresh random
+   * pick per call — acceptable only for one-shot/background call sites that
+   * resolve config exactly once per invocation.
+   */
+  selectionSeed?: string;
+  /**
+   * Invoked once for each mix profile the resolver expands, reporting which
+   * constituent was chosen. Used by A/B-eval recording (usage attribution).
+   */
+  onMixSelected?: (info: { mixProfile: string; chosenProfile: string }) => void;
+}
+
 export function resolveCallSiteConfig(
   callSite: LLMCallSite,
   llm: z.infer<typeof LLMSchema>,
-  opts: { overrideProfile?: string } = {},
+  opts: ResolveCallSiteOpts = {},
 ): z.infer<typeof LLMConfigBase> {
   const layers: Mergeable[] = [llm.default as Mergeable];
 
-  const activeFragment =
-    llm.activeProfile != null ? llm.profiles?.[llm.activeProfile] : undefined;
-  const overrideFragment =
-    opts.overrideProfile != null
-      ? llm.profiles?.[opts.overrideProfile]
-      : undefined;
+  const activeFragment = resolveProfileFragment(llm.activeProfile, llm, opts);
+  const overrideFragment = resolveProfileFragment(
+    opts.overrideProfile,
+    llm,
+    opts,
+  );
   const site =
     llm.callSites?.[callSite] ??
     effectiveDefault(callSite, llm, opts.overrideProfile != null);
 
   if (callSite === "mainAgent") {
-    appendCallSiteLayers(layers, callSite, llm, site);
+    appendCallSiteLayers(layers, callSite, llm, site, opts);
     appendProfileLayer(layers, activeFragment);
     appendProfileLayer(layers, overrideFragment);
   } else {
     appendProfileLayer(layers, activeFragment);
     appendProfileLayer(layers, overrideFragment);
-    appendCallSiteLayers(layers, callSite, llm, site);
+    appendCallSiteLayers(layers, callSite, llm, site, opts);
   }
 
   return finalize(deepMerge(...layers.map(withImpliedProviderForKnownModel)));
@@ -80,6 +107,81 @@ export function resolveCallSiteConfig(
 
 type Mergeable = Record<string, unknown>;
 
+/**
+ * FNV-1a 32-bit string hash → unit float in [0, 1). Deterministic and stable
+ * across runtimes — the mix-pick contract depends on identical output for
+ * identical input forever, so the constants must never change. (Mirrors the
+ * private hash in `memory/v2/page-index.ts`; intentionally re-declared here so
+ * the resolver's determinism contract is self-contained and cannot be broken
+ * by an unrelated edit to that module.)
+ */
+function seededUnitFloat(seed: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  // `>>> 0` → unsigned 32-bit; divide by 2^32 to land in [0, 1).
+  return (h >>> 0) / 0x100000000;
+}
+
+/**
+ * Pick one entry from a weighted list given a unit float in [0, 1). Weights
+ * are relative and normalized by their sum. Assumes `entries` is non-empty
+ * with positive weights (guaranteed by `MixSchema`: `.min(2)` + positive).
+ */
+function weightedPick<T extends { weight: number }>(
+  entries: readonly T[],
+  unit: number,
+): T {
+  const total = entries.reduce((sum, e) => sum + e.weight, 0);
+  // Defensive: a degenerate total (unreachable post-schema) → first arm.
+  if (!(total > 0)) return entries[0];
+  let threshold = unit * total;
+  for (const entry of entries) {
+    threshold -= entry.weight;
+    if (threshold < 0) return entry;
+  }
+  // Floating-point fall-through (unit ≈ 1): return the last arm.
+  return entries[entries.length - 1];
+}
+
+/**
+ * Dereference a profile name to its concrete `ProfileEntry`, expanding a mix
+ * profile by a seeded weighted pick. Returns `undefined` when the name is
+ * unknown (parity with the silent fall-through callers already rely on).
+ *
+ * Mix expansion is one level only — `LLMSchema.superRefine` guarantees arms
+ * are standard (non-mix) profiles, so this never recurses unboundedly. A
+ * chosen arm pointing at a missing profile (only reachable in hand-crafted,
+ * unparsed configs) falls through to `undefined`.
+ *
+ * Pure & synchronous (the only impurity is `Math.random()` in the no-seed
+ * fallback path).
+ */
+function resolveProfileFragment(
+  name: string | undefined,
+  llm: z.infer<typeof LLMSchema>,
+  opts: ResolveCallSiteOpts,
+): ProfileEntry | undefined {
+  if (name == null) return undefined;
+  const entry = llm.profiles?.[name];
+  if (entry?.mix == null) return entry;
+
+  // Mix: pick one constituent. Seed by per-conversation seed + the mix's own
+  // name so two different mixes in the same conversation pick independently,
+  // but the same mix always resolves to the same arm within the conversation.
+  const unit =
+    opts.selectionSeed != null
+      ? seededUnitFloat(`${opts.selectionSeed}\u0000${name}`)
+      : Math.random();
+  const chosen = weightedPick(entry.mix, unit);
+  opts.onMixSelected?.({ mixProfile: name, chosenProfile: chosen.profile });
+
+  // The chosen arm must be a standard profile (enforced by superRefine).
+  return llm.profiles?.[chosen.profile];
+}
+
 /**
  * Returns the effective default profile key the resolver would actually
  * select for a call site when no per-turn `overrideProfile` is supplied.
@@ -170,16 +272,16 @@ function appendCallSiteLayers(
   callSite: LLMCallSite,
   llm: z.infer<typeof LLMSchema>,
   site: z.infer<typeof LLMSchema>["callSites"][LLMCallSite] | undefined,
+  opts: ResolveCallSiteOpts,
 ): void {
   if (site != null) {
     if (site.profile != null) {
-      const profileFragment: ProfileEntry | undefined =
-        llm.profiles?.[site.profile];
+      const profileFragment = resolveProfileFragment(site.profile, llm, opts);
       if (profileFragment == null) {
         // Defensive: `LLMSchema.superRefine` already rejects unknown profile
-        // references at config load, so this branch is unreachable for any
-        // config that survived schema validation. Throw a clear error in case
-        // a hand-crafted (un-parsed) config slips through.
+        // references (and unknown mix arms) at config load, so this branch is
+        // unreachable for any config that survived schema validation. Throw a
+        // clear error in case a hand-crafted (un-parsed) config slips through.
         throw new Error(
           `LLM call site "${callSite}" references undefined profile "${site.profile}"`,
         );
@@ -198,6 +300,10 @@ function profileConfigFragment(profile: ProfileEntry): Mergeable {
     source: _source,
     label: _label,
     description: _description,
+    // `mix` never reaches here in practice (a mix expands to a standard
+    // profile before this point), but strip it defensively so it can never
+    // leak into the merged `LLMConfigBase`.
+    mix: _mix,
     ...config
   } = profile;
   return config as Mergeable;

package/src/config/loader.ts

@@ -122,6 +122,9 @@ export function getDeploymentContextDefaults(): Record<string, unknown> {
   if (process.env.IS_PLATFORM !== "true" && process.env.IS_PLATFORM !== "1") {
     return {};
   }
+  // `web-search.mode = managed` enables platform-backed app-executed search
+  // for non-native inference providers while preserving provider-native hosted
+  // search for providers/models that support it.
   const managed = { mode: "managed" as const };
   return {
     services: {
@@ -161,11 +164,7 @@ export function fillContextDefaultsForMissingKeys(
 ): void {
   for (const [key, value] of Object.entries(contextDefaults)) {
     const fileVal = fileConfig[key];
-    if (
-      value !== null &&
-      typeof value === "object" &&
-      !Array.isArray(value)
-    ) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
       const targetChild = readPlainObject(target[key]);
       const fileChild = readPlainObject(fileVal);
       if (targetChild) {