@vellumai/assistant 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/src/config/__tests__/sync-gated-profiles.test.ts

@@ -0,0 +1,368 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of [
+    "info",
+    "warn",
+    "error",
+    "debug",
+    "trace",
+    "fatal",
+    "silent",
+    "child",
+  ]) {
+    stub[m] = m === "child" ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+afterAll(() => {
+  mock.restore();
+});
+
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
+import { invalidateConfigCache } from "../loader.js";
+import { LLMSchema } from "../schemas/llm.js";
+import { seedInferenceProfiles } from "../seed-inference-profiles.js";
+import { reconcileFlagGatedProfiles } from "../sync-gated-profiles.js";
+
+type RawConfig = {
+  llm: {
+    profiles: Record<string, Record<string, unknown>>;
+    profileOrder: string[];
+    activeProfile?: string;
+    advisorProfile?: string;
+  };
+};
+
+function writeConfig(obj: unknown): void {
+  writeFileSync(CONFIG_PATH, JSON.stringify(obj, null, 2) + "\n");
+}
+
+function readConfig(): RawConfig {
+  return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+}
+
+function seedBalancedConfig(): void {
+  writeConfig({ llm: { default: { provider: "anthropic" } } });
+  invalidateConfigCache();
+  seedInferenceProfiles({});
+}
+
+describe("reconcileFlagGatedProfiles", () => {
+  beforeEach(() => {
+    ensureTestDir();
+    if (existsSync(CONFIG_PATH)) rmSync(CONFIG_PATH, { force: true });
+    delete process.env.IS_PLATFORM;
+    setOverridesForTesting({});
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    delete process.env.IS_PLATFORM;
+    setOverridesForTesting({});
+    invalidateConfigCache();
+  });
+
+  test("flag on materializes the managed os-beta profile after balanced", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const raw = readConfig();
+    const osBeta = raw.llm.profiles["os-beta"]!;
+    expect(osBeta.model).toBe("accounts/fireworks/models/glm-5p2");
+    expect(osBeta.provider_connection).toBe("fireworks-managed");
+    expect(osBeta.source).toBe("managed");
+    expect(osBeta.label).toBe("OS Beta");
+
+    const order = raw.llm.profileOrder;
+    expect(order.indexOf("os-beta")).toBe(order.indexOf("balanced") + 1);
+  });
+
+  test("flag on in BYOK mode seeds the os-beta profile disabled", () => {
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const osBeta = readConfig().llm.profiles["os-beta"]!;
+    expect(osBeta.status).toBe("disabled");
+    expect(osBeta.label).toBe("OS Beta (Managed)");
+    expect(osBeta.source).toBe("managed");
+  });
+
+  test("flag on is idempotent across repeated runs", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+    invalidateConfigCache();
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag on preserves user overrides on the managed profile", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["os-beta"]!.label = "My OS Beta";
+    raw.llm.profiles["os-beta"]!.status = "disabled";
+    raw.llm.profiles["os-beta"]!.advisorEnabled = true;
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    reconcileFlagGatedProfiles();
+
+    const after = readConfig().llm.profiles["os-beta"]!;
+    expect(after.label).toBe("My OS Beta");
+    expect(after.status).toBe("disabled");
+    expect(after.advisorEnabled).toBe(true);
+    expect(after.model).toBe("accounts/fireworks/models/glm-5p2");
+  });
+
+  test("flag off removes a managed os-beta and applies fallbacks", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.activeProfile = "os-beta";
+    raw.llm.advisorProfile = "os-beta";
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
+    expect(after.llm.activeProfile).toBe("balanced");
+    expect(after.llm.advisorProfile).toBe("quality-optimized");
+  });
+
+  test("flag off with no os-beta present is a no-op", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": false });
+
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag off scrubs os-beta from user mix arms, keeping >= 2-arm mixes", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["my-mix"] = {
+      source: "user",
+      label: "My Mix",
+      mix: [
+        { profile: "balanced", weight: 70 },
+        { profile: "quality-optimized", weight: 20 },
+        { profile: "os-beta", weight: 30 },
+      ],
+    };
+    raw.llm.profileOrder.push("my-mix");
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    const mix = after.llm.profiles["my-mix"]!;
+    expect(mix.mix).toEqual([
+      { profile: "balanced", weight: 70 },
+      { profile: "quality-optimized", weight: 20 },
+    ]);
+    expect(mix.source).toBe("user");
+    expect(mix.label).toBe("My Mix");
+
+    invalidateConfigCache();
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag off removes a two-arm mix that loses os-beta and repoints refs", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["experiment"] = {
+      source: "user",
+      label: "Experiment",
+      mix: [
+        { profile: "balanced", weight: 50 },
+        { profile: "os-beta", weight: 50 },
+      ],
+    };
+    raw.llm.profileOrder.push("experiment");
+    raw.llm.activeProfile = "experiment";
+    raw.llm.advisorProfile = "os-beta";
+    (raw.llm as Record<string, unknown>).callSites = {
+      mainAgent: { profile: "experiment" },
+    };
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profiles["experiment"]).toBeUndefined();
+    expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
+    expect(after.llm.profileOrder.includes("experiment")).toBe(false);
+    expect(after.llm.activeProfile).toBe("balanced");
+    expect(after.llm.advisorProfile).toBe("quality-optimized");
+    expect(
+      (
+        after.llm as unknown as Record<
+          string,
+          Record<string, Record<string, unknown>>
+        >
+      ).callSites.mainAgent.profile,
+    ).toBeUndefined();
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("flag off shortens a three-arm mix to two surviving arms", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["blend"] = {
+      source: "user",
+      label: "Blend",
+      mix: [
+        { profile: "balanced", weight: 40 },
+        { profile: "os-beta", weight: 30 },
+        { profile: "quality-optimized", weight: 30 },
+      ],
+    };
+    raw.llm.profileOrder.push("blend");
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profiles["blend"]!.mix).toEqual([
+      { profile: "balanced", weight: 40 },
+      { profile: "quality-optimized", weight: 30 },
+    ]);
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("flag off clears a call-site profile reference to os-beta", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    (raw.llm as Record<string, unknown>).callSites = {
+      advisor: { profile: "os-beta", temperature: 0.3 },
+    };
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    const advisor = (
+      after.llm as unknown as Record<
+        string,
+        Record<string, Record<string, unknown>>
+      >
+    ).callSites.advisor;
+    expect(advisor.profile).toBeUndefined();
+    expect(advisor.temperature).toBe(0.3);
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("a user-owned os-beta profile is never touched", () => {
+    process.env.IS_PLATFORM = "true";
+    writeConfig({
+      llm: {
+        default: { provider: "anthropic" },
+        profiles: {
+          "os-beta": {
+            source: "user",
+            label: "Mine",
+            provider: "anthropic",
+            model: "claude-x",
+            provider_connection: "anthropic-personal",
+          },
+        },
+        profileOrder: ["os-beta"],
+      },
+    });
+    invalidateConfigCache();
+    const before = readFileSync(CONFIG_PATH, "utf-8");
+
+    setOverridesForTesting({ "os-beta": true });
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+    expect(readFileSync(CONFIG_PATH, "utf-8")).toBe(before);
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+    expect(readFileSync(CONFIG_PATH, "utf-8")).toBe(before);
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -103,7 +103,11 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
     const entry = flag as Record<string, unknown>;
     if (entry.scope !== "assistant" && entry.scope !== "both") continue;
     if (typeof entry.key !== "string") continue;
-    if (typeof entry.defaultEnabled !== "boolean" && typeof entry.defaultEnabled !== "string") continue;
+    if (
+      typeof entry.defaultEnabled !== "boolean" &&
+      typeof entry.defaultEnabled !== "string"
+    )
+      continue;
 
     result[entry.key as string] = {
       defaultEnabled: entry.defaultEnabled,
@@ -178,6 +182,12 @@ const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
  * tests preseed flag state via `setOverridesForTesting()` (in
  * `__tests__/feature-flag-test-helpers.ts`) without the gateway IPC call
  * clobbering their setup.
+ *
+ * Resolves `true` when the override cache is populated from the gateway and
+ * `false` when the cache is left unset (exhausted retries / unreachable
+ * gateway). Callers that mutate persisted state from flag values gate that
+ * work on a `true` result so a failed fetch never resolves a flag to its
+ * registry default and drops user state.
  */
 export async function initFeatureFlagOverrides(options?: {
   retryBackoffsMs?: readonly number[];
@@ -188,8 +198,8 @@ export async function initFeatureFlagOverrides(options?: {
    * instead of blocking startup.
    */
   callTimeoutMs?: number;
-}): Promise<void> {
-  if (isCachedFromGateway()) return;
+}): Promise<boolean> {
+  if (isCachedFromGateway()) return true;
 
   const backoffs = options?.retryBackoffsMs ?? DEFAULT_INIT_RETRY_BACKOFFS_MS;
   const callTimeoutMs = options?.callTimeoutMs;
@@ -205,7 +215,7 @@ export async function initFeatureFlagOverrides(options?: {
       // Re-check after the wait: a concurrent caller (e.g. a test using
       // `setOverridesForTesting`) may have populated the cache while we
       // were sleeping. Bail out so we don't clobber their setup.
-      if (isCachedFromGateway()) return;
+      if (isCachedFromGateway()) return true;
     }
 
     const gatewayOverrides = await fetchOverridesFromGateway(callTimeoutMs);
@@ -217,7 +227,7 @@ export async function initFeatureFlagOverrides(options?: {
           "Feature flag overrides loaded from gateway after retry",
         );
       }
-      return;
+      return true;
     }
   }
 
@@ -230,6 +240,7 @@ export async function initFeatureFlagOverrides(options?: {
       "Feature flag overrides empty after all retries; falling back to registry defaults and fail-closed undeclared flags",
     );
   }
+  return false;
 }
 
 /**
@@ -262,10 +273,14 @@ export function clearFeatureFlagOverridesCache(): void {
  * retries (the gateway is known to be up because it just pushed an event).
  * Called by the gateway flag listener when a `feature_flags_changed` event
  * arrives.
+ *
+ * Resolves `true` when the cache was repopulated from the gateway, `false`
+ * when the fetch came back empty/failed — callers gate persisted-state
+ * reconciliation on a `true` result.
  */
-export async function refreshOverridesFromGateway(): Promise<void> {
+export async function refreshOverridesFromGateway(): Promise<boolean> {
   clearFeatureFlagOverridesCache();
-  await initFeatureFlagOverrides({ retryBackoffsMs: [] });
+  return initFeatureFlagOverrides({ retryBackoffsMs: [] });
 }
 
 // ---------------------------------------------------------------------------

package/src/config/bundled-skills/contacts/tools/contact-search.ts

@@ -18,7 +18,6 @@ function formatContactSummary(c: ContactWithChannels): string {
       .map((ch) => {
         let s = `${ch.type}:${ch.address}${ch.isPrimary ? "*" : ""}`;
         const extras: string[] = [];
-        if (ch.externalUserId) extras.push(`userId: ${ch.externalUserId}`);
         if (ch.externalChatId) extras.push(`chatId: ${ch.externalChatId}`);
         if (extras.length > 0) s += ` (${extras.join(", ")})`;
         return s;

package/src/config/bundled-skills/document-editor/SKILL.md

@@ -33,13 +33,13 @@ Write and edit long-form documents using the built-in rich text editor. Document
 
 This is the default path when the user asks you to write something.
 
-1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Capture the `surface_id` from the response — every subsequent `document_update` call must reference it.
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
-3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
+3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. When you are streaming into the document you just created, `surface_id` is optional — omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
 
 ### Recovering from a failed update
 
-If a `document_update` call fails with an `Invalid input` error (for example because `surface_id` was missing), do NOT call `document_create` again. The `surface_id` you need is in the tool result of the most recent `document_create` call in this turn. Retry `document_update` with that `surface_id` and the same content. Creating a second document with the same title produces a duplicate for the user.
+If a `document_update` call fails with an `Invalid input` error, do NOT call `document_create` again — that produces a duplicate for the user. The most common cause is a missing `content` field: resend the call with the chunk's Markdown in `content`. You can omit `surface_id` to target the document you are currently writing; pass it explicitly only when editing a different existing document.
 
 ## Editing an existing document
 

package/src/config/bundled-skills/document-editor/TOOLS.json

@@ -50,7 +50,7 @@
         "properties": {
           "surface_id": {
             "type": "string",
-            "description": "The ID of the document surface to update"
+            "description": "The ID of the document surface to update. Optional — when omitted, the most recently updated document in this conversation is used, so streaming successive chunks needs only `content`."
           },
           "content": {
             "type": "string",
@@ -62,7 +62,7 @@
             "description": "Whether to replace all content or append to the end. Defaults to append."
           }
         },
-        "required": ["surface_id", "content"]
+        "required": ["content"]
       },
       "executor": "tools/document-update.ts",
       "execution_target": "host"

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

@@ -28,6 +28,8 @@ 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.
 
+Reading, searching, or summarizing the user's inbox is a **messaging task** — use the messaging tools (or the Gmail connection flow below if nothing is connected). Never run `assistant channels` commands for a mailbox request: channels are the assistant's own inbound delivery routes, not the user's mailbox, and inspecting them sends you down the wrong path.
+
 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.
@@ -50,13 +52,13 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 
 ### Gmail
 
-1. **Try connecting directly first.** Run `assistant oauth status google`. This will show whether or not the user had previously connected their google account. If so, they are ready to go.
-2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
+1. **Check the connection.** Run `assistant oauth status google`. If a connection exists, the user is ready to go — proceed with their request.
+2. **If no connections are found, render the connect button in one step:** call `ui_show` with `surface_type: "oauth_connect"` and `data.providerKey: "google"`. That surface is always available — do **not** run `assistant channels`, `oauth providers get`, or load `vellum-oauth-integrations` just to display the button, and do **not** fall back to `assistant oauth connect`. Only load `vellum-oauth-integrations` when the managed-vs-your-own-credentials decision genuinely needs handling (e.g. a BYOK setup where the managed connect surface isn't available).
 
 ### Outlook
 
-1. **Try connecting directly first.** Run `assistant oauth status outlook`. This will show whether the user has previously connected their Outlook account.
-2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
+1. **Check the connection.** Run `assistant oauth status outlook`. If a connection exists, the user is ready to go — proceed with their request.
+2. **If no connections are found, render the connect button in one step:** call `ui_show` with `surface_type: "oauth_connect"` and `data.providerKey: "outlook"`. The same rules as Gmail apply — don't probe further or load a setup skill just to show the button; only load `vellum-oauth-integrations` when a managed-vs-your-own-credentials decision genuinely needs handling.
 
 ### Slack
 

package/src/config/bundled-skills/messaging/tools/messaging-archive-by-sender.ts

@@ -1,3 +1,4 @@
+import { isArchiveBySenderAuthorized } from "../../../../runtime/effective-capabilities.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -8,14 +9,14 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const userApproved =
-    input.user_approved === true && context.trustClass === "guardian";
-  if (
-    !context.triggeredBySurfaceAction &&
-    !context.batchAuthorizedByTask &&
-    !context.approvedViaPrompt &&
-    !userApproved
-  ) {
+  const authorized = isArchiveBySenderAuthorized({
+    trustClass: context.trustClass,
+    triggeredBySurfaceAction: context.triggeredBySurfaceAction,
+    batchAuthorizedByTask: context.batchAuthorizedByTask,
+    approvedViaPrompt: context.approvedViaPrompt,
+    userApproved: input.user_approved === true,
+  });
+  if (!authorized) {
     return err(
       "This tool requires either a surface action or a scheduled task run with this tool in required_tools. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
     );

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

@@ -71,6 +71,10 @@ Only the parent conversation that spawned a subagent can interact with it (check
 
 Set `send_result_to_user: false` when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.
 
+## Inference Profile
+
+Set `inference_profile` to an `llm.profiles` key when a subagent should run under a specific model profile. When omitted, the subagent inherits the parent turn's active profile if one exists; otherwise it uses the `subagentSpawn` call site's default model selection.
+
 ## Fork Mode
 
 Forks are sub-agents that inherit the parent's full context -- messages, system prompt, and memory -- sharing the KV cache for near-free context inheritance. Use forks when the task benefits from knowing what you've been discussing; use a regular sub-agent when the task is self-contained.

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

@@ -39,6 +39,10 @@
               "investigator"
             ],
             "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'investigator': root-cause analysis — debugging, log forensics, tracing behavior across many files; has bash for read-only investigation (grep/find/log inspection) and returns a compact root-cause report. 'general': full access (default). Ignored when fork: true (forks always use general)."
+          },
+          "inference_profile": {
+            "type": "string",
+            "description": "Optional llm.profiles key this subagent should run under. When omitted, the subagent inherits the parent turn's profile when one is active; otherwise it uses the subagentSpawn call site's default model selection."
           }
         },
         "required": ["label", "objective"]

package/src/config/bundled-skills/system-storage-cleanup/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: system-storage-cleanup
+description: "Handle disk pressure, critically low storage, safe storage limits, and storage cleanup mode by inspecting disk usage and proposing safe cleanup steps."
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "\U0001F9F9"
+  vellum:
+    display-name: "System Storage Cleanup"
+    category: "system"
+    activation-hints:
+      - "Critical disk usage or disk-pressure lock is blocking normal work"
+      - "The assistant is in storage cleanup mode or normal work is suspended due to low storage"
+      - "User asks to inspect large files or find what is using disk space"
+      - "User asks to free workspace storage safely"
+      - "User asks to delete caches, logs, temp files, Docker artifacts, or other storage safely"
+---
+
+You are operating under a critical storage cleanup contract. Your only goal is to free enough storage for the assistant to resume normal work without damaging user data.
+
+## Cleanup Contract
+
+Start by warning the user that storage is critically low and normal work is suspended until storage cleanup mode clears. Stay scoped to freeing storage until the disk-pressure lock clears or the guardian explicitly overrides it.
+
+Prefer foreground inspection with available cleanup-safe tools before any mutation. Identify both the target volume that is actually full and the workspace path before proposing deletions. Do not work on unrelated tasks, refactors, installs, upgrades, or product changes while the storage lock is active.
+
+Ask for explicit approval before deleting files, caches, logs, package caches, Docker artifacts, or any other data unless the user has already approved that exact action. Before asking, present each proposed deletion with:
+
+- Exact path or artifact name.
+- Estimated reclaimable size.
+- Expected consequence, including whether it is regenerable or may remove user-visible history.
+
+If the user approves a broad category, narrow it to exact paths or artifacts before deleting. If the user approves one exact path, do not treat that as approval for adjacent paths.
+
+Never delete credentials, security material, workspace database files, config files, active profiler runs, migrations, skill source, app source, conversation records, memory graph nodes or segments, `journal/`, `data/reflections/`, PKB files, backups, or backup keys unless the user explicitly names that path and accepts the consequence.
+
+## Inspection Procedure
+
+Use local/container-visible inspection first. Prefer `df -h` on the current workspace path and on `VELLUM_WORKSPACE_DIR` when that variable is available. In Docker/container mode, `/workspace` is the persistent volume and cleanup should normally focus there.
+
+Use `du` one level at a time and sort by size to identify large directories before drilling deeper. Keep each pass readable and bounded to the volume or workspace that is actually full. Avoid whole-filesystem scans unless the target volume cannot be isolated.
+
+Use `host_bash` only when the sandbox cannot see the volume that is actually full and host-level inspection is necessary. Explain why host-level inspection is needed before using it.
+
+## SQLite Diagnosis Only
+
+If `data/db/assistant.db` dominates disk usage, inspect it only through read-only `sqlite3` access. Diagnostics may use `PRAGMA` and `SELECT` queries for:
+
+- `page_size`
+- `page_count`
+- `freelist_count`
+- `dbstat` object-size breakdowns
+
+The purpose is to determine whether growth comes from specific tables/indexes or from free-page bloat. Do not edit the database manually.
+
+Never run ad hoc `DELETE`, `UPDATE`, `INSERT`, `DROP`, `REINDEX`, schema changes, `VACUUM`, `PRAGMA writable_schema`, or any other mutating SQLite command from this skill. If SQLite tables are the main culprit, tell the user this needs product-owned retention or maintenance work rather than manual database editing.
+
+## Safer Cleanup Candidates
+
+Good candidates to inspect and propose, when they are clearly nonessential and user-approved, include:
+
+- Scratch or temporary downloads created by the assistant.
+- Generated build artifacts.
+- Old logs.
+- Stale temporary directories.
+- Completed profiler runs that are no longer active.
+- Stale caches.
+- Large old diagnostic text attachments such as spindumps.
+- Package cache cleanup or Docker cache/artifact cleanup after the user approves the exact package manager or Docker action.
+
+Treat source files, persistent records, and user-authored content as protected unless the user explicitly names them for deletion and accepts the consequence.
+
+## Non-Goals
+
+ATL-450 product work is out of scope for this skill. Do not implement configurable trace or audit retention jobs, attachment retention or compression jobs, upload-time image re-encoding, first-class disk-usage UI, one-click cleanup buttons, or scheduled SQLite vacuuming. If inspection shows those are needed, report that as follow-up product work after the immediate storage cleanup path is safe.