@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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/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/workflows/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: workflows
-description: Author and run autonomous multi-agent workflows that fan work across parallel leaf agents
+description: Delegate a big or high-stakes job to a fleet of parallel subagents, orchestrated deterministically; runs unattended and reports back
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "⚙️"
   vellum:
     display-name: "Workflows"
     category: "system"
-    feature-flag: "workflows"
+    always-candidate: true
     activation-hints:
-      - "A task decomposes into many similar sub-tasks that can run concurrently (score every item, extract a field from each of many documents, draft-then-verify a batch)"
-      - "You want fan-out orchestrated deterministically and the result reported back when the whole run finishes"
+      - "Batch — apply one operation to each of MANY items (score / rate / rank / classify / extract / summarize each of a large set)"
+      - "Comprehensive coverage — exhaustively sweep, audit, or find EVERY instance across a large surface"
+      - "Research & synthesize — gather across many sources or pages and combine into one answer"
+      - "Confidence — generate several independent attempts and judge them, or adversarially verify findings before trusting the result"
+      - "Scale — work too large to finish well in one inline pass"
     avoid-when:
-      - "The task is a single tool call or a quick lookup — do it inline"
-      - "The work needs interactive, conversational back-and-forth rather than unattended fan-out"
+      - "A single inline answer, a quick lookup, or a small one-off"
+      - "Interactive, conversational back-and-forth rather than unattended fan-out"
 ---
 
 A workflow is a short JS/TS script you author that runs in a sandbox and fans work
@@ -22,8 +25,11 @@ one with `run_workflow` (inline `script` OR saved `name`, exactly one). It retur
 `runId` immediately; the run is asynchronous and you are notified in this
 conversation when it completes — **do NOT poll**.
 
-Reach for one when a task decomposes into many similar small sub-tasks that can run
-concurrently. For a single task or a quick lookup, do it inline.
+Reach for one when a job is too big, too parallel, or too important for one inline
+pass. That is more than batch/map-reduce over many items — it also covers exhaustively
+sweeping or auditing a large surface, researching across many sources and synthesizing,
+and generating several independent attempts to judge or adversarially verify before
+trusting the result. For a single task or a quick lookup, do it inline.
 
 ## The script model
 

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

@@ -24,7 +24,7 @@ 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 appBuilder_appRefresh from "./bundled-skills/app-builder/tools/app-refresh.js";
+import * as appRefresh from "./bundled-skills/app-builder/tools/app-refresh.js";
 import * as appUpdate from "./bundled-skills/app-builder/tools/app-update.js";
 // ── app-control ────────────────────────────────────────────────────────────────
 import * as appControlClick from "./bundled-skills/app-control/tools/app-control-click.js";
@@ -88,8 +88,6 @@ import * as messagingRead from "./bundled-skills/messaging/tools/messaging-read.
 import * as messagingSearch from "./bundled-skills/messaging/tools/messaging-search.js";
 import * as messagingSend from "./bundled-skills/messaging/tools/messaging-send.js";
 import * as messagingSenderDigest from "./bundled-skills/messaging/tools/messaging-sender-digest.js";
-// ── personal-page ──────────────────────────────────────────────────────────────
-import * as personalPage_appRefresh from "./bundled-skills/personal-page/tools/app-refresh.js";
 // ── phone-calls ────────────────────────────────────────────────────────────────
 import * as callEnd from "./bundled-skills/phone-calls/tools/call-end.js";
 import * as callStart from "./bundled-skills/phone-calls/tools/call-start.js";
@@ -148,7 +146,7 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["app-builder:tools/app-create.ts", appCreate],
   ["app-builder:tools/app-update.ts", appUpdate],
   ["app-builder:tools/app-delete.ts", appDelete],
-  ["app-builder:tools/app-refresh.ts", appBuilder_appRefresh],
+  ["app-builder:tools/app-refresh.ts", appRefresh],
   ["app-builder:tools/app-generate-icon.ts", appGenerateIcon],
   ["app-builder:tools/app-list.ts", appList],
 
@@ -228,9 +226,6 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["messaging:tools/messaging-sender-digest.ts", messagingSenderDigest],
   ["messaging:tools/messaging-archive-by-sender.ts", messagingArchiveBySender],
 
-  // personal-page
-  ["personal-page:tools/app-refresh.ts", personalPage_appRefresh],
-
   // phone-calls
   ["phone-calls:tools/call-start.ts", callStart],
   ["phone-calls:tools/call-status.ts", callStatus],

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

@@ -1,7 +1,13 @@
 import { type LLMCallSite } from "./schemas/llm.js";
 
 type CallSiteDefaultConfig = {
-  profile: string;
+  /**
+   * Named profile the call site resolves to. Omit to inherit the workspace
+   * default config (`llm.default`, with the active profile applied) — used for
+   * call sites that must resolve to a credentialed provider on every install
+   * rather than pinning a profile that may be unavailable.
+   */
+  profile?: string;
   maxTokens?: number;
   effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
   temperature?: number | null;
@@ -63,6 +69,9 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   meetConsentMonitor: { profile: "cost-optimized" },
   meetChatOpportunity: { profile: "cost-optimized" },
   inference: { profile: "cost-optimized" },
+  // The advisor consults the strongest managed profile by default; a workspace
+  // overrides this via `llm.advisorProfile` (which floats above this).
+  advisor: { profile: "quality-optimized" },
 
   heartbeatAgent: {
     profile: "cost-optimized",
@@ -125,8 +134,12 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
     thinking: { enabled: false },
     disableCache: true,
   },
+  // Anonymous and schema leaves inherit the workspace default config (no pinned
+  // profile) so they always resolve to a credentialed provider. Pinning a
+  // managed profile like `cost-optimized` breaks BYOK installs where the managed
+  // profiles are uncredentialed. A per-leaf `profile` option or a `workflowLeaf`
+  // call-site override still takes precedence for cost control.
   workflowLeaf: {
-    profile: "cost-optimized",
     effort: "low",
     thinking: { enabled: false },
   },