@vellumai/assistant 0.11.4-staging.2 → 0.11.4-staging.3

package/src/config/bundled-skills/image-studio/SKILL.md

@@ -69,10 +69,11 @@ Edits on large photos are slow (1 to 2 minutes). If the tool reports a timeout (
 
 ## Output handling
 
-Images return as inline content blocks in the tool result; they are not written to disk automatically.
+Each generated image is saved into the workspace under `media/generated/` and the tool result lists the saved paths. The images also come back as inline content blocks so you can judge the result before presenting it.
 
-- If the user just wants to see the image, the inline result is enough.
-- If the user wants a file or you need to iterate on the result, save it to disk and deliver it through the conversation's attachment mechanism.
+- Present an image to the user by embedding its saved path in your reply: `![short description](vellum://workspace/media/generated/<file>.png)`. The app renders it inline where your text refers to it, and chat channels (Slack, Telegram, WhatsApp) deliver it as a native image upload.
+- If you do not embed it, the image is still auto-attached to your reply as a file, so it is never lost. Prefer embedding: an attachment chip at the end of the message is a worse presentation than the image inline.
+- To iterate on a result, pass its saved path via `source_paths` with `mode: "edit"`.
 
 ## Error handling
 
@@ -88,4 +89,4 @@ Do NOT rephrase the prompt and retry on the same model, even if the error sugges
 
 ## Complete when
 
-The tool has returned at least one image and the user can see it: either the inline result in chat or an attached saved file. An error report counts as complete only after the retry path in Error handling has been exhausted.
+The tool has returned at least one image and your reply presents it to the user, preferably as an inline `![description](vellum://workspace/...)` embed of the saved path. An error report counts as complete only after the retry path in Error handling has been exhausted.

package/src/config/bundled-skills/image-studio/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "media_generate_image",
-      "description": "Generate or edit images using AI. Supports text-to-image generation and image editing with source images.",
+      "description": "Generate or edit images using AI. Supports text-to-image generation and image editing with source images. Saves results into the workspace and returns their file paths; present a result to the user by embedding its path in your reply as ![description](vellum://workspace/<path>).",
       "category": "media",
       "risk": "low",
       "input_schema": {

package/src/config/bundled-skills/image-studio/tools/media-generate-image.ts

@@ -1,3 +1,6 @@
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
 import {
   resolveImageGenCredentials,
   resolveImageGenRouting,
@@ -19,6 +22,87 @@ import type {
 } from "../../../../tools/types.js";
 import { getConfig } from "../../../loader.js";
 
+/** Workspace-relative directory where generated images are saved. */
+const GENERATED_MEDIA_DIR = "media/generated";
+
+/**
+ * Derive a filesystem-safe base name for a generated image from its title
+ * (when the provider returns one) or the generation prompt.
+ */
+function imageFileSlug(title: string | undefined, prompt: string): string {
+  const base = (title?.trim() || prompt)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, 48)
+    .replace(/-+$/, "");
+  return base || "image";
+}
+
+/** Upper bound on filename-collision retries per image. */
+const MAX_FILENAME_ATTEMPTS = 1000;
+
+/**
+ * Save generated images under `media/generated/` in the workspace so the
+ * model can reference them by path (inline embeds, edit-mode iteration).
+ * Each target path is validated through `sandboxPolicy` so a symlinked
+ * directory cannot redirect the write outside the workspace, and files are
+ * created exclusively (`wx`) so concurrent generations cannot claim the
+ * same filename. Returns workspace-relative paths for the images written
+ * before any failure; a failure stops the loop and is reported, not
+ * thrown, so the inline content blocks still reach the model.
+ */
+function saveGeneratedImages(
+  images: Array<{ mimeType: string; dataBase64: string; title?: string }>,
+  prompt: string,
+  workingDir: string,
+): { savedPaths: string[]; saveError?: string } {
+  const savedPaths: string[] = [];
+  try {
+    for (const img of images) {
+      const ext = img.mimeType.split("/")[1] ?? "png";
+      const slug = imageFileSlug(img.title, prompt);
+      let written = false;
+      for (let attempt = 1; attempt <= MAX_FILENAME_ATTEMPTS; attempt++) {
+        const relPath =
+          attempt === 1
+            ? `${GENERATED_MEDIA_DIR}/${slug}.${ext}`
+            : `${GENERATED_MEDIA_DIR}/${slug}-${attempt}.${ext}`;
+        const pathCheck = sandboxPolicy(join(workingDir, relPath), workingDir, {
+          mustExist: false,
+        });
+        if (!pathCheck.ok) {
+          throw new Error(pathCheck.error);
+        }
+        mkdirSync(dirname(pathCheck.resolved), { recursive: true });
+        try {
+          writeFileSync(
+            pathCheck.resolved,
+            Buffer.from(img.dataBase64, "base64"),
+            { flag: "wx" },
+          );
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+            continue;
+          }
+          throw error;
+        }
+        savedPaths.push(relPath);
+        written = true;
+        break;
+      }
+      if (!written) {
+        throw new Error(
+          `Could not find a free filename for "${slug}.${ext}" after ${MAX_FILENAME_ATTEMPTS} attempts.`,
+        );
+      }
+    }
+  } catch (error) {
+    return { savedPaths, saveError: (error as Error).message };
+  }
+  return { savedPaths };
+}
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -127,7 +211,24 @@ export async function run(
     });
 
     const imageCount = result.images.length;
+    const { savedPaths, saveError } = saveGeneratedImages(
+      result.images,
+      prompt,
+      context.workingDir,
+    );
+
     let content = `Generated ${imageCount} image${imageCount !== 1 ? "s" : ""} using ${result.resolvedModel}.`;
+    if (savedPaths.length === 1) {
+      content += ` Saved to ${savedPaths[0]}.`;
+    } else if (savedPaths.length > 1) {
+      content += ` Saved to:\n${savedPaths.map((p) => `- ${p}`).join("\n")}`;
+    }
+    if (savedPaths.length > 0) {
+      content += `\n\nShow the user an image by embedding it in your reply: ![description](vellum://workspace/${savedPaths[0]}). To iterate on a result, pass its saved path via source_paths with mode "edit".`;
+    }
+    if (saveError) {
+      content += `\n\nCould not save to the workspace (${saveError}); the image${imageCount !== 1 ? "s" : ""} will be attached to your reply automatically instead.`;
+    }
     if (result.text) {
       content += `\n\n${result.text}`;
     }

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -40,12 +40,12 @@
           "includes": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional list of child skill IDs that this skill includes (metadata only, no auto-activation)."
+            "description": "Optional list of child skill IDs this skill composes. When this skill is loaded via skill_load, each child's body is inlined after the parent's and the child's tools are projected, so the parent can rely on the child's procedure without re-stating it. Does not affect which skills get selected for a turn."
           },
           "activation_hints": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name."
+            "description": "Required. 1-4 short trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name. Scaffolding rewrites the whole SKILL.md, so an overwrite must pass the hints the skill should keep, revised if the procedure changed."
           },
           "avoid_when": {
             "type": "array",
@@ -79,7 +79,13 @@
             "description": "Deprecated no-op compatibility field. Skills are discovered from top-level SKILL.md files."
           }
         },
-        "required": ["skill_id", "name", "description", "body_markdown"]
+        "required": [
+          "skill_id",
+          "name",
+          "description",
+          "body_markdown",
+          "activation_hints"
+        ]
       },
       "executor": "tools/scaffold-managed.ts",
       "execution_target": "host"

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

@@ -12,7 +12,7 @@ metadata:
       - "Delegate a self-contained research or implementation task off the main thread"
       - "Multiple agents at once, or a context-inheriting fork"
     avoid-when:
-      - "Task is small enough to do inline (single tool call, quick lookup)"
+      - "Task is small enough to do inline (a handful of tool calls, quick lookups or reads)"
       - "User wants Claude Code or Codex — use the acp skill instead"
 ---
 
@@ -37,7 +37,7 @@ There are three subagent types. Pick one with two questions: **does it need to c
 |---|---|---|---|---|
 | `researcher` | No | No | `web_search`, `web_fetch`, `file_read`, `file_list`, `code_search`, `recall`, `skill_execute`, `notify_parent` | Web research, codebase exploration, reading documentation, root-cause investigation, reviewing an approach against the code |
 | `builder` | Yes | No | Your whole tool surface, unrestricted: shell, file writes and edits, and every connector, MCP, and browser tool you can reach | Code changes, file output, build/test runs, anything that must run a command or act on an outside system |
-| `advisor` | No | Yes | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Runs on a stronger model, inherits full parent context, and BLOCKS until it returns guidance |
+| `advisor` | No | Yes | Read-only fact checking in the workspace: `file_read`, `file_list`, `code_search` | Read-only senior-advisor consult. Reads the brief you write in `objective`, runs on a stronger model, and BLOCKS until it returns guidance |
 
 Both background types can call `notify_parent` for mid-run communication with the parent.
 
@@ -65,17 +65,23 @@ The other contracts: `output_contract: "artifact"` tells a `builder` that the de
 
 ## Consulting the Advisor
 
-The `advisor` is the one type you spawn on your own judgment, unprompted: you do NOT wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it. The advisor is different: proactively consult it whenever the conditions below are met.
+The `advisor` is the one type you may spawn on your own judgment, unprompted: you do not wait for the user to ask for a subagent. The background types (`researcher`, `builder`) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it.
 
-Orient yourself first (read the relevant files, understand the task), then consult the advisor:
+A consult is expensive (a stronger model reviews your brief and answers), so reserve it for moments where a second perspective can genuinely change the outcome. Most tasks need no consult at all: a routine task with an obvious approach does not require sign-off, before you start or after you finish. Orient yourself first (read the relevant files, understand the task), then consult the advisor:
 
-- **Before you commit to an approach and start building** — to shape a plan when you don't have one, or to pressure-test and sharpen a plan you've already drafted.
+- **Before you commit to an approach on a consequential or ambiguous task**: the design space is wide, a wrong approach would be costly to unwind, or requirements pull against each other.
 - **When you get stuck or are weighing a change in direction.**
-- **Once before you declare the task done.**
 
-The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model and inherits your full context, so it sees the task, your tool calls, and their results without you re-explaining. It also receives a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace) so its guidance can point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
+The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model, and it sees ONLY the brief you write in `objective` plus a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace). It cannot read this conversation, so the quality of its guidance tracks the quality of your brief. Write a substantive one:
 
-The advisor has read-only workspace tools (`file_read`, `file_list`, `code_search`) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and every lookup it has to make delays your answer, so surface the evidence you already have (a file's contents, a command's output, results gathered elsewhere) in the conversation or the spawn objective before consulting.
+- The task or goal, stated in full.
+- Your plan, or the options you are weighing against each other.
+- The key evidence you already have: file paths, command output, results, decisions already made.
+- The specific question you want answered.
+
+The environment snapshot is what lets its guidance point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
+
+The advisor has read-only workspace tools (`file_read`, `file_list`, `code_search`) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and every lookup it has to make delays your answer, so put the evidence you already have (a file's contents, a command's output, results gathered elsewhere) into the objective rather than making it go find them.
 
 Spawn the advisor **alone** — do NOT batch the consult in the same turn as other tool calls (especially file edits, shell commands, or anything destructive or expensive). Tool calls you issue in the same turn run concurrently with the consult, so they would execute before you see its guidance. Consult the advisor by itself, read its guidance, then act.
 
@@ -151,7 +157,6 @@ Rule of thumb: "Does this task need to know what we've been talking about?" If y
 - Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.
-- Default to spawning subagents for any task that involves web research, multi-file exploration, or independent coding work. Serial execution should be the exception, not the rule.
-- Delegate root-cause investigations ("why is X happening?", debugging, log forensics) to a `researcher` instead of grepping inline. A long investigation done inline floods your own context with file slices and grep output, crowding out the conversation; the researcher does the digging in its own context and returns a compact root-cause report.
-- When a user request has both an information-gathering component and an action component, spawn a researcher immediately rather than doing the research inline yourself.
-- Prefer spawning 2-3 focused subagents over one broad one. Smaller scopes finish faster and fail more gracefully.
+- Spawn a subagent when the work is extensive: a sweep across a large codebase, deep research across many sources, or an investigation whose raw output (file slices, grep output, logs) would flood your context. Do quick work inline -- a few file reads or searches, an ordinary web lookup -- since a spawn pays for a whole fresh context and is slower than just doing the work.
+- Delegate long root-cause investigations (log forensics, multi-file "why is X happening?" digs) to a `researcher`: it does the digging in its own context and returns a compact root-cause report, instead of crowding your conversation with intermediate output.
+- Scale the fan-out to the task. Most tasks need zero or one subagent. Split work across multiple subagents only when the parts are genuinely independent and each is substantial on its own.

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Pick its type with role: 'researcher' (read-only, fixed tool list) or 'builder' (write-capable, your whole tool surface).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. A fork that names a role runs scoped to it; a fork that names none keeps your full tool surface. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), has read-only workspace tools for checking a decisive fact (file_read, file_list, code_search), and BLOCKS until it returns focused strategic guidance in a single response. It cannot change anything, persist output, or see other conversations.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Pick its type with role: 'researcher' (read-only, fixed tool list) or 'builder' (write-capable, your whole tool surface).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. A fork that names a role runs scoped to it; a fork that names none keeps your full tool surface. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it sees ONLY the brief you write in 'objective' plus a snapshot of your environment (available tools, skill catalog, workspace), has read-only workspace tools for checking a decisive fact (file_read, file_list, code_search), and BLOCKS until it returns focused strategic guidance in a single response. It cannot read this conversation, change anything, persist output, or see other conversations, so the quality of its guidance tracks the quality of your brief.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -15,11 +15,11 @@
           },
           "objective": {
             "type": "string",
-            "description": "The task objective \u2014 what the subagent should accomplish"
+            "description": "The task objective: what the subagent should accomplish. For role 'advisor' this field IS the brief the advisor reads, and the only account of the work it gets, so write it out in full: the task or goal, the approach you have chosen or the options you are weighing, the key evidence you already gathered (file paths, command output, decisions made), and the specific question you want answered."
           },
           "context": {
             "type": "string",
-            "description": "Optional additional context to pass to the subagent. Ignored when fork is true; forks inherit the parent's full context."
+            "description": "Optional additional context to pass to the subagent. Ignored when fork is true (forks inherit the parent's full context), and ignored for role 'advisor', which reads only the objective brief."
           },
           "fork": {
             "type": "boolean",
@@ -31,7 +31,7 @@
           },
           "role": {
             "type": "string",
-            "description": "Which of the three subagent types to run, chosen by two questions: does it need to change anything, and do you need the answer before you can continue? 'researcher': changes nothing, runs in the background, scoped to a fixed read-only list (web_search, web_fetch, file_read, file_list, code_search, recall, skill_execute) for research, exploration, root-cause investigation, and review. 'builder': changes things, runs in the background on this conversation's whole tool surface (shell, file writes and edits, plus every connector, MCP, and browser tool you can reach) for code changes, file output, and anything that must run a command or act on an outside system. 'advisor': changes nothing and BLOCKS your turn until it answers; inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), can read files and search code (file_read, file_list, code_search) to check a decisive fact, and returns focused strategic guidance. Default when omitted: 'builder', so a spawn that names no type keeps the full tool surface. The older names are still accepted as aliases ('planner' and 'investigator' run as researcher, 'coder' and 'general' run as builder). Any other text is not a type: the subagent runs as a researcher with that text as its persona, so if the task must write files or run commands, name 'builder' explicitly. A read-only subagent asked to produce a file finishes without producing anything. Roles apply to forks too; a fork that names no role runs as a builder and keeps this conversation's full tool surface, and a fork's persona reaches it through its task framing."
+            "description": "Which of the three subagent types to run, chosen by two questions: does it need to change anything, and do you need the answer before you can continue? 'researcher': changes nothing, runs in the background, scoped to a fixed read-only list (web_search, web_fetch, file_read, file_list, code_search, recall, skill_execute) for research, exploration, root-cause investigation, and review. 'builder': changes things, runs in the background on this conversation's whole tool surface (shell, file writes and edits, plus every connector, MCP, and browser tool you can reach) for code changes, file output, and anything that must run a command or act on an outside system. 'advisor': changes nothing and BLOCKS your turn until it answers; reads the brief you write in 'objective' plus a snapshot of your environment (available tools, skill catalog, workspace), can read files and search code (file_read, file_list, code_search) to check a decisive fact, and returns focused strategic guidance. It cannot see this conversation, so a thin objective gets thin advice. Default when omitted: 'builder', so a spawn that names no type keeps the full tool surface. The older names are still accepted as aliases ('planner' and 'investigator' run as researcher, 'coder' and 'general' run as builder). Any other text is not a type: the subagent runs as a researcher with that text as its persona, so if the task must write files or run commands, name 'builder' explicitly. A read-only subagent asked to produce a file finishes without producing anything. Roles apply to forks too; a fork that names no role runs as a builder and keeps this conversation's full tool surface, and a fork's persona reaches it through its task framing."
           },
           "inference_profile": {
             "type": "string",

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

@@ -45,9 +45,16 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
     profile: "cost-optimized",
     contextWindow: { maxInputTokens: 1000000 },
   },
+  // Forced-tool selection over a numbered candidate pool: the model picks ids,
+  // it does not reason its way to an answer. `effort` has to be named here
+  // because a call-site tweak only overrides the fields it lists, so leaving it
+  // off inherits `balanced`'s `effort: "high"` (see default-profile-catalog).
+  // Low effort matches `recall`, the sibling site doing the same kind of
+  // bounded judgment, and keeps retrieval latency low on escalated voice turns.
   memoryV3SelectL2: {
     profile: "balanced",
     temperature: 0,
+    effort: "low",
     thinking: { enabled: false, streamThinking: false },
   },
   recall: {

package/src/config/default-profile-catalog.ts

@@ -7,6 +7,7 @@ import { resolveModelIntent } from "../providers/model-intents.js";
 import { isCodexSubscriptionModel } from "../providers/openai/codex-models.js";
 import type { ModelIntent } from "../providers/types.js";
 import { getManagedUpstream } from "../providers/vellum-model-routing.js";
+import { getBalancedModelExperimentArm } from "./balanced-model-experiment.js";
 import {
   DEFAULT_PROFILE_KEYS,
   DEFAULT_PROFILE_PROVIDERS,
@@ -149,6 +150,45 @@ const VELLUM_PROFILE_IMPLS: ProfileImpls = {
   },
 };
 
+/**
+ * Arm to managed model pin for the `experiment-balanced-model-2026-08-06` A/B
+ * test (`balanced-model-experiment.ts` owns the flag read). An arm repoints
+ * the model of the managed (`vellum`) implementation of `balanced` and nothing
+ * else: effort, thinking, token budget, label and description all stay on the
+ * shipped body, and the `chatgpt` and BYOK columns are untouched because those
+ * installs run the provider their user chose and sit outside the experiment.
+ *
+ * `control` is absent by design. It, an arm this build does not know, and an
+ * unset flag all resolve to the shipped body, so no LaunchDarkly value can
+ * strand an install on a model that is not pinned here. A `Map` rather than an
+ * object literal keeps that true for every string LaunchDarkly can send: the
+ * arm is remote input, and an object lookup would resolve `constructor` or
+ * `toString` to an inherited `Object.prototype` member instead of missing.
+ *
+ * `glm-5p2` is text-only: Balanced does not pass `doesSupportVision` on that
+ * arm, so image input routes through the image-fallback captioning plugin.
+ */
+const BALANCED_EXPERIMENT_MODELS = new Map<string, string>([
+  ["terra", "gpt-5.6-terra"],
+  ["glm-5p2", "accounts/fireworks/models/glm-5p2"],
+]);
+
+/**
+ * The managed (`vellum`) implementation of a default profile, carrying the
+ * balanced-model experiment arm. Resolved per call rather than materialized
+ * once: the gateway pushes flag changes to a running daemon, so the arm can
+ * move under a live process.
+ */
+function managedProfileImpl(key: DefaultProfileKey): DefaultProfileTemplate {
+  const impl = VELLUM_PROFILE_IMPLS[key];
+  if (key !== "balanced") {
+    return impl;
+  }
+  const arm = getBalancedModelExperimentArm();
+  const model = arm == null ? undefined : BALANCED_EXPERIMENT_MODELS.get(arm);
+  return model == null ? impl : { ...impl, model };
+}
+
 /**
  * The `chatgpt` column: ChatGPT-subscription implementations, stamped
  * `provider: "chatgpt"` so dispatch routes through the canonical
@@ -463,6 +503,19 @@ for (const key of DEFAULT_PROFILE_KEYS) {
   }
 }
 
+// The experiment arms substitute into the managed column at request time, so
+// they need the same routability guarantee as the pins validated above: a
+// LaunchDarkly arm must never select a model no managed upstream serves.
+for (const [arm, model] of BALANCED_EXPERIMENT_MODELS) {
+  if (getManagedUpstream(model) === null) {
+    throw new Error(
+      `BALANCED_EXPERIMENT_MODELS["${arm}"] references model "${model}" which ` +
+        `is not served by any managed upstream. ` +
+        `Update model-catalog.ts or default-profile-catalog.ts.`,
+    );
+  }
+}
+
 // Provider choices without a named column materialize from the shared BYOK
 // templates; verify each one's resolved model lands in the catalog.
 for (const provider of DEFAULT_PROVIDER_CHOICES) {
@@ -501,6 +554,14 @@ function buildDefaultProfileEntries(): Record<string, ProfileEntry> {
  * The materialized code-default bodies keyed by profile name — the
  * code-owned content a managed-source workspace entry resolves to. These are
  * the `vellum` column (the managed implementations).
+ *
+ * Materialized once at module load, so this is the shipped catalog: the
+ * balanced-model experiment arm is applied by the provider-aware resolvers
+ * (`resolveDefaultProfileForProvider`, `getEffectiveProfilesForProvider`),
+ * which are what every runtime and client-facing reader of a default profile's
+ * content goes through. The name-only readers that serve from this record
+ * (`getEffectiveProfile`, `getEffectiveProfiles`) consume a profile's
+ * existence and status, never its model.
  */
 export const CODE_DEFAULT_PROFILE_ENTRIES: Readonly<
   Record<string, ProfileEntry>
@@ -614,17 +675,48 @@ export function isDefaultProfileKey(name: string): name is DefaultProfileKey {
   return (DEFAULT_PROFILE_KEYS as readonly string[]).includes(name);
 }
 
+/**
+ * The implementation of default profile `key` on `provider`: the named matrix
+ * column when the provider has one, the shared BYOK template otherwise. The
+ * managed column carries the balanced-model experiment arm, which is why the
+ * lookup runs through here rather than reading `PROFILE_IMPLS` directly.
+ */
+function defaultProfileImplForProvider(
+  key: DefaultProfileKey,
+  provider: NonNullable<ProfileEntry["provider"]>,
+): DefaultProfileTemplate {
+  if (!isDefaultProfileProvider(provider)) {
+    return { ...BYOK_PROFILE_IMPLS[key], provider };
+  }
+  if (provider === "vellum") {
+    return managedProfileImpl(key);
+  }
+  return PROFILE_IMPLS[key][provider];
+}
+
+/**
+ * The code-owned body a default profile name resolves to under the given
+ * default provider. This is the single choke point where a default profile key
+ * becomes a concrete body, so every consumer (the runtime resolver through
+ * `resolveDefaultProfileForProvider`, the client-facing listing through
+ * `getEffectiveProfilesForProvider`) reports the same model the request runs
+ * on, experiment arm included.
+ */
 function defaultProfileBodyForProvider(
   name: string,
   defaultProvider: DefaultProviderConfig | null,
 ): ProfileEntry | undefined {
-  if (defaultProvider == null || !isDefaultProfileKey(name)) {
+  if (!isDefaultProfileKey(name)) {
     return CODE_DEFAULT_PROFILE_ENTRIES[name];
   }
+  if (defaultProvider == null) {
+    // The frozen `CODE_DEFAULT_PROFILE_ENTRIES` body, re-materialized so an
+    // install that predates `llm.defaultProvider` still sees the arm.
+    const managed = managedProfileImpl(name);
+    return materializeProfile(managed, managed.provider);
+  }
   const { provider } = defaultProvider;
-  const impl = isDefaultProfileProvider(provider)
-    ? PROFILE_IMPLS[name][provider]
-    : { ...BYOK_PROFILE_IMPLS[name], provider };
+  const impl = defaultProfileImplForProvider(name, provider);
   return clampMaxTokensToModelCap({
     ...materializeProfile(
       impl,

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

@@ -36,15 +36,6 @@
       "defaultEnabled": "control",
       "values": ["control", "variant-a", "personal-page"]
     },
-    {
-      "id": "experiment-billing-cta-2026-07-23",
-      "scope": "client",
-      "key": "experiment-billing-cta-2026-07-23",
-      "label": "Experiment: Billing CTA 2026-07-23",
-      "description": "Credit paywall CTA experiment. control = single Add Credits CTA for everyone (opens Add Credits modal). upgrade-cta = FREE users (plan_id base) get a single Upgrade CTA (View Plans takeover) instead; PAID users still get Add Credits.",
-      "defaultEnabled": "control",
-      "values": ["control", "upgrade-cta"]
-    },
     {
       "id": "local-docker-enabled",
       "scope": "client",
@@ -247,10 +238,10 @@
     },
     {
       "id": "web-remote-ingress",
-      "scope": "assistant",
+      "scope": "client",
       "key": "web-remote-ingress",
       "label": "Web Remote Ingress",
-      "description": "Serve the web client over a public tunnel and enable browser pairing for self-hosted assistants.",
+      "description": "Show the pair-a-device card in web settings. Visibility only; pairing itself is always available.",
       "defaultEnabled": false
     },
     {
@@ -372,6 +363,15 @@
       "label": "Plugin Schedules",
       "description": "Plugins declare recurring schedules as files that register and run automatically",
       "defaultEnabled": false
+    },
+    {
+      "id": "experiment-balanced-model-2026-08-06",
+      "scope": "assistant",
+      "key": "experiment-balanced-model-2026-08-06",
+      "label": "Experiment: Balanced Profile Model",
+      "description": "Multivariate experiment on the model the managed Balanced inference profile resolves to. control = gpt-5.6-luna (the shipped pin); terra = gpt-5.6-terra; glm-5p2 = accounts/fireworks/models/glm-5p2. Only the managed (vellum) implementation moves: ChatGPT-subscription and BYOK installs run the provider the user chose and are outside the experiment. Rollout and targeting are managed in the LaunchDarkly dashboard; any value that is not an arm name resolves to control.",
+      "defaultEnabled": "control",
+      "values": ["control", "terra", "glm-5p2"]
     }
   ]
 }

package/src/config/skills.ts

@@ -104,11 +104,18 @@ export interface SkillSummary {
   owner?: OwnerInfo;
   /** Parsed tool manifest metadata, if the skill has a valid TOOLS.json. */
   toolManifest?: SkillToolManifestMeta;
-  /** IDs of child skills that this skill includes (metadata-only, not auto-activated). */
+  /**
+   * IDs of child skills this skill composes. `skill_load` inlines each child's
+   * body and projects its tools when the parent loads (tools/skills/load.ts);
+   * they play no part in which skills get selected for a turn.
+   */
   includes?: string[];
   /** Feature flag ID declared in frontmatter. Only skills with this field are subject to feature flag gating. */
   featureFlag?: string;
-  /** Compact routing cues projected into <available_skills> XML to guide skill selection. */
+  /**
+   * Intent phrases rendered into the skill's capability card as "Use when: ..."
+   * (memory substrate/skill-content.ts), which is the text skill routing scores.
+   */
   activationHints?: string[];
   /** Conditions under which this skill should NOT be loaded. */
   avoidWhen?: string[];

package/src/daemon/__tests__/conversation-surfaces-launch.test.ts

@@ -158,7 +158,7 @@ function makeContext(overrides?: Partial<Conversation>): HarnessContext {
 
   const base = asConversation({
     conversationId: "origin-conv-id",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/daemon/conversation-agent-loop.ts

@@ -320,6 +320,8 @@ export async function runAgentLoopImpl(
      * the turn.
      */
     isHiddenPrompt?: boolean;
+    /** Daemon-authored kind of the user row that triggered this turn. */
+    messageKind?: string;
     /**
      * Row the end-of-turn reply notification should treat as the prompt this
      * turn answers. Defaults to `userMessageId`; a coalesced batch overrides it
@@ -404,6 +406,17 @@ export async function runAgentLoopImpl(
   // LUM-3148 removes the ambiguity by making trust ride the turn.
   ctx.currentTurnTrustContext = options?.turnTrustContext ?? ctx.trustContext;
   ctx.currentTurnChannelCapabilities = ctx.channelCapabilities;
+  // Presence is the third per-turn snapshot: whether a human is present to see
+  // UI and answer prompts. Callers declare it via `isInteractive`; a caller
+  // that omits it gets a non-interactive turn. Set before the prompt build
+  // below, which reads it (through `hasNoClient`).
+  const isInteractiveResolved = options?.isInteractive ?? false;
+  // Resolved once and threaded into every re-injection (including the
+  // post-compaction hook) rather than re-read per assembly call, and exposed
+  // to tool execution so tools (e.g. ask_question) see whether a human is
+  // present rather than re-deriving it from live state.
+  const isNonInteractive = !isInteractiveResolved;
+  ctx.currentTurnIsNonInteractive = isNonInteractive;
 
   // Re-resolve the system prompt under the snapshots just set and push it into
   // the loop when the persona changed. The loop reuses the prompt frozen at
@@ -678,19 +691,6 @@ export async function runAgentLoopImpl(
     };
   })();
 
-  const isInteractiveResolved =
-    options?.isInteractive ?? (!ctx.hasNoClient && !ctx.headlessLock);
-  // Whether the in-flight turn has no human present to answer clarification
-  // questions. Derived from the loop's `isInteractive` option (which can fall
-  // back to mutable client/headless state that flips mid-turn), so it is
-  // resolved once here and threaded into every re-injection — including the
-  // post-compaction hook — rather than re-read per assembly call.
-  const isNonInteractive = !isInteractiveResolved;
-  // Expose the resolved turn-level interactivity to tool execution so tools
-  // (e.g. ask_question) see whether a human is present to answer, rather than
-  // re-deriving it from live client state that misclassifies a scheduled turn
-  // running on a client-attached conversation.
-  ctx.currentTurnIsNonInteractive = isNonInteractive;
   const diskPressureDecision = classifyDiskPressureTurnPolicy(
     getDiskPressureStatus(),
     {
@@ -1204,6 +1204,7 @@ export async function runAgentLoopImpl(
       requestId: reqId,
       prompt: options?.titleText ?? content,
       isHiddenPrompt: options?.isHiddenPrompt === true,
+      messageKind: options?.messageKind,
       originalMessages: Object.freeze([...ctx.messages]),
       latestMessages: ctx.messages,
       modelProfileKey,