@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/platform/consent-cache.test.ts

@@ -0,0 +1,267 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { OwnerConsent } from "./client.js";
+
+// ---------------------------------------------------------------------------
+// Mutable mock state
+// ---------------------------------------------------------------------------
+
+let mockClient: {
+  platformAssistantId: string;
+  getOwnerConsent: () => Promise<OwnerConsent | null>;
+} | null = null;
+let createCallCount = 0;
+// Legacy fail-closed opt-out marker surfaced via getConfigReadOnly(). Default
+// off/absent so existing behavior is unchanged.
+let mockLegacyTelemetryOptOut: boolean | undefined = false;
+
+// ---------------------------------------------------------------------------
+// Module mocks (must precede the import under test)
+// ---------------------------------------------------------------------------
+
+mock.module("./client.js", () => ({
+  VellumPlatformClient: {
+    create: async () => {
+      createCallCount += 1;
+      return mockClient;
+    },
+  },
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfigReadOnly: () => ({
+    legacyTelemetryOptOut: mockLegacyTelemetryOptOut,
+  }),
+}));
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// ---------------------------------------------------------------------------
+// Import under test (after mocks)
+// ---------------------------------------------------------------------------
+
+import {
+  __setCachedShareAnalyticsForTest,
+  __setCachedShareDiagnosticsForTest,
+  __setCachedShareDiagnosticsVersionForTest,
+  getCachedShareAnalytics,
+  getCachedShareDiagnostics,
+  getCachedShareDiagnosticsVersion,
+  refreshConsentCache,
+  startConsentRefresh,
+  stopConsentRefresh,
+} from "./consent-cache.js";
+
+/**
+ * Build a mock owner consent. Fields default to `false` so existing
+ * share_analytics-focused cases don't have to spell them out.
+ */
+function makeConsent(overrides: Partial<OwnerConsent> = {}): OwnerConsent {
+  return {
+    shareAnalytics: false,
+    shareDiagnostics: false,
+    shareDiagnosticsAcceptedVersion: "",
+    ...overrides,
+  };
+}
+
+function makeClient(consent: OwnerConsent | null, assistantId = "asst_1") {
+  return {
+    platformAssistantId: assistantId,
+    getOwnerConsent: async () => consent,
+  };
+}
+
+describe("consent-cache", () => {
+  beforeEach(() => {
+    mockClient = null;
+    createCallCount = 0;
+    mockLegacyTelemetryOptOut = false;
+    __setCachedShareAnalyticsForTest(false);
+    __setCachedShareDiagnosticsForTest(false);
+    __setCachedShareDiagnosticsVersionForTest("");
+  });
+
+  afterEach(async () => {
+    await stopConsentRefresh();
+  });
+
+  test("defaults to false before any refresh", () => {
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("stays false when no platform client is available", async () => {
+    mockClient = null;
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("becomes true after a successful fetch reporting shareAnalytics: true", async () => {
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(true);
+  });
+
+  test("a null fetch keeps the last known value", async () => {
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(true);
+
+    // Transient failure: consent endpoint returns null.
+    mockClient = makeClient(null);
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(true);
+  });
+
+  test("a missing client flips a prior opt-in back to false", async () => {
+    __setCachedShareAnalyticsForTest(true);
+    mockClient = null;
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("a client without a resolvable assistant identity fails closed", async () => {
+    __setCachedShareAnalyticsForTest(true);
+    // Identity cleared mid-session (e.g. assistantId emptied while base URL +
+    // API key persist). getOwnerConsent must not be relied upon to preserve the
+    // prior opt-in here — fail closed instead.
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }), "");
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("legacy opt-out marker keeps analytics off despite platform opt-in", async () => {
+    mockLegacyTelemetryOptOut = true;
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }));
+    await refreshConsentCache();
+    // Platform reports opt-in, but the fail-closed marker forces off.
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("a fetch reporting shareAnalytics: false turns the cache off", async () => {
+    __setCachedShareAnalyticsForTest(true);
+    mockClient = makeClient(makeConsent({ shareDiagnostics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareAnalytics()).toBe(false);
+  });
+
+  test("startConsentRefresh is idempotent and runs an immediate refresh", async () => {
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }));
+
+    startConsentRefresh();
+    startConsentRefresh(); // no-op: timer already running
+    // Let the fire-and-forget immediate refresh settle.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(getCachedShareAnalytics()).toBe(true);
+    // One immediate refresh from the first call; the second is a no-op.
+    expect(createCallCount).toBe(1);
+  });
+
+  test("stopConsentRefresh clears the timer (start can run again)", async () => {
+    startConsentRefresh();
+    await stopConsentRefresh();
+    // A fresh start after stop performs another immediate refresh.
+    mockClient = makeClient(makeConsent({ shareAnalytics: true }));
+    startConsentRefresh();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(getCachedShareAnalytics()).toBe(true);
+  });
+
+  // share_diagnostics tracks the same refresh as share_analytics; Sentry's
+  // beforeSend re-reads it per event so a revocation is honored within a cycle.
+  test("diagnostics defaults to false before any refresh", () => {
+    expect(getCachedShareDiagnostics()).toBe(false);
+  });
+
+  test("diagnostics becomes true after a fetch reporting shareDiagnostics: true", async () => {
+    mockClient = makeClient(makeConsent({ shareDiagnostics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(true);
+  });
+
+  test("a later fetch reporting shareDiagnostics: false honors the revocation", async () => {
+    mockClient = makeClient(makeConsent({ shareDiagnostics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(true);
+
+    mockClient = makeClient(makeConsent({ shareDiagnostics: false }));
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(false);
+  });
+
+  test("a null diagnostics fetch keeps the last known value", async () => {
+    mockClient = makeClient(makeConsent({ shareDiagnostics: true }));
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(true);
+
+    mockClient = makeClient(null);
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(true);
+  });
+
+  test("a missing client flips a prior diagnostics opt-in back to false", async () => {
+    __setCachedShareDiagnosticsForTest(true);
+    mockClient = null;
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(false);
+  });
+
+  test("a client without a resolvable assistant identity fails diagnostics closed", async () => {
+    __setCachedShareDiagnosticsForTest(true);
+    mockClient = makeClient(makeConsent({ shareDiagnostics: true }), "");
+    await refreshConsentCache();
+    expect(getCachedShareDiagnostics()).toBe(false);
+  });
+
+  test("caches the accepted diagnostics-consent version from a successful fetch", async () => {
+    mockClient = makeClient(
+      makeConsent({
+        shareDiagnostics: true,
+        shareDiagnosticsAcceptedVersion: "2026-06-18",
+      }),
+    );
+    await refreshConsentCache();
+    expect(getCachedShareDiagnosticsVersion()).toBe("2026-06-18");
+  });
+
+  test("a missing client clears a prior cached diagnostics version", async () => {
+    __setCachedShareDiagnosticsVersionForTest("2026-06-18");
+    mockClient = null;
+    await refreshConsentCache();
+    expect(getCachedShareDiagnosticsVersion()).toBe("");
+  });
+
+  test("a client without a resolvable assistant identity clears the diagnostics version", async () => {
+    __setCachedShareDiagnosticsVersionForTest("2026-06-18");
+    mockClient = makeClient(
+      makeConsent({
+        shareDiagnostics: true,
+        shareDiagnosticsAcceptedVersion: "2026-06-18",
+      }),
+      "",
+    );
+    await refreshConsentCache();
+    expect(getCachedShareDiagnosticsVersion()).toBe("");
+  });
+
+  test("a null fetch keeps the last known diagnostics version", async () => {
+    mockClient = makeClient(
+      makeConsent({
+        shareDiagnostics: true,
+        shareDiagnosticsAcceptedVersion: "2026-06-18",
+      }),
+    );
+    await refreshConsentCache();
+    expect(getCachedShareDiagnosticsVersion()).toBe("2026-06-18");
+
+    mockClient = makeClient(null);
+    await refreshConsentCache();
+    expect(getCachedShareDiagnosticsVersion()).toBe("2026-06-18");
+  });
+});

package/src/platform/consent-cache.ts

@@ -0,0 +1,174 @@
+/**
+ * In-memory cache of the platform owner's telemetry consent.
+ *
+ * Three values are cached, all refreshed from the same owner-consent fetch:
+ *  - `share_analytics`: gates usage telemetry collection.
+ *  - `share_diagnostics`: gates crash diagnostics (read by Sentry `beforeSend`),
+ *    and composes the per-turn trace-collection gate alongside the
+ *    `trace-collection` feature flag.
+ *  - `share_diagnostics_accepted_version`: the consent version the owner
+ *    accepted; the disclosing-version half of the trace-collection gate (see
+ *    telemetry/trace-collection-policy.ts).
+ *
+ * Hot-path gates (record-time telemetry writes, Sentry `beforeSend`) need a
+ * synchronous, I/O-free read, so this module owns the values and refreshes them
+ * periodically in the background. Default-off until the first successful fetch:
+ * an absent session, a disabled platform, or a transient fetch failure all leave
+ * the values untouched (initial `false`), so we never report analytics or send
+ * crash diagnostics without a confirmed opt-in.
+ */
+
+import { getConfigReadOnly } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import { VellumPlatformClient } from "./client.js";
+
+const log = getLogger("consent-cache");
+
+const REFRESH_INTERVAL_MS = 5 * 60_000; // refresh consent every 5 min
+
+let cachedShareAnalytics = false; // default-off until first success
+let cachedShareDiagnostics = false; // default-off until first success
+let cachedShareDiagnosticsVersion = ""; // "" fails the trace disclosure gate
+// Fail-closed marker for a workspace that locally opted out of usage data
+// before telemetry moved to platform `share_analytics` consent (migration 106).
+// While set, telemetry stays off regardless of platform consent. Cleared by a
+// future cross-repo reconciliation once the platform exposes an explicit
+// re-consent signal; not auto-cleared here.
+let legacyOptOut = false;
+let refreshTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Synchronous hot-path accessor for the effective `share_analytics` consent.
+ * Never does I/O; returns `false` until a successful refresh proves otherwise,
+ * and stays `false` while the legacy fail-closed opt-out marker is set.
+ */
+export function getCachedShareAnalytics(): boolean {
+  return cachedShareAnalytics && !legacyOptOut;
+}
+
+/**
+ * Synchronous hot-path accessor for the `share_diagnostics` consent (read by
+ * Sentry `beforeSend`). Never does I/O; returns `false` until a successful
+ * refresh proves otherwise. Because every Sentry event re-reads this, a
+ * mid-session opt-out is honored within one refresh cycle.
+ */
+export function getCachedShareDiagnostics(): boolean {
+  return cachedShareDiagnostics;
+}
+
+/**
+ * Synchronous hot-path accessor for the owner's accepted diagnostics-consent
+ * version ("YYYY-MM-DD", or "" until a successful refresh / if never accepted).
+ * The disclosing-version half of the per-turn trace-collection gate.
+ */
+export function getCachedShareDiagnosticsVersion(): string {
+  return cachedShareDiagnosticsVersion;
+}
+
+/**
+ * Refresh the cached consent from the platform.
+ *
+ * No platform session / features disabled (`create()` is null) → default-off.
+ * No resolvable assistant identity (no owner whose consent we can attest to) →
+ * fail closed. A successful fetch adopts the reported values. A `null` fetch
+ * (transient failure / undeployed endpoint) leaves the previous values
+ * unchanged so a known opt-in is not flipped off mid-session.
+ */
+export async function refreshConsentCache(): Promise<void> {
+  legacyOptOut = getConfigReadOnly().legacyTelemetryOptOut === true;
+
+  const client = await VellumPlatformClient.create();
+  if (!client) {
+    setCachedShareAnalytics(false);
+    setCachedShareDiagnostics(false);
+    setCachedShareDiagnosticsVersion("");
+    return;
+  }
+
+  // No resolvable owner identity → fail closed (don't ride a stale opt-in).
+  if (!client.platformAssistantId) {
+    setCachedShareAnalytics(false);
+    setCachedShareDiagnostics(false);
+    setCachedShareDiagnosticsVersion("");
+    return;
+  }
+
+  const consent = await client.getOwnerConsent();
+  if (consent) {
+    setCachedShareAnalytics(consent.shareAnalytics);
+    setCachedShareDiagnostics(consent.shareDiagnostics);
+    setCachedShareDiagnosticsVersion(consent.shareDiagnosticsAcceptedVersion);
+  }
+}
+
+function setCachedShareAnalytics(value: boolean): void {
+  if (value !== cachedShareAnalytics) {
+    log.debug(
+      { from: cachedShareAnalytics, to: value },
+      "share_analytics consent changed",
+    );
+    cachedShareAnalytics = value;
+  }
+}
+
+function setCachedShareDiagnostics(value: boolean): void {
+  if (value !== cachedShareDiagnostics) {
+    log.debug(
+      { from: cachedShareDiagnostics, to: value },
+      "share_diagnostics consent changed",
+    );
+    cachedShareDiagnostics = value;
+  }
+}
+
+function setCachedShareDiagnosticsVersion(value: string): void {
+  if (value !== cachedShareDiagnosticsVersion) {
+    log.debug(
+      { from: cachedShareDiagnosticsVersion, to: value },
+      "share_diagnostics_accepted_version changed",
+    );
+    cachedShareDiagnosticsVersion = value;
+  }
+}
+
+/**
+ * Begin periodic consent refresh. Idempotent — a second call is a no-op while a
+ * timer is already running. Runs one immediate refresh, then every 5 minutes.
+ */
+export function startConsentRefresh(): void {
+  if (refreshTimer) {
+    return;
+  }
+
+  refreshConsentCache().catch((err) => {
+    log.debug({ err }, "initial consent refresh failed");
+  });
+  refreshTimer = setInterval(() => {
+    refreshConsentCache().catch((err) => {
+      log.debug({ err }, "consent refresh failed");
+    });
+  }, REFRESH_INTERVAL_MS);
+}
+
+/** Stop periodic consent refresh and clear the timer. */
+export async function stopConsentRefresh(): Promise<void> {
+  if (refreshTimer) {
+    clearInterval(refreshTimer);
+    refreshTimer = null;
+  }
+}
+
+/** Test-only: override the cached analytics value without going through a refresh. */
+export function __setCachedShareAnalyticsForTest(value: boolean): void {
+  cachedShareAnalytics = value;
+}
+
+/** Test-only: override the cached diagnostics value without going through a refresh. */
+export function __setCachedShareDiagnosticsForTest(value: boolean): void {
+  cachedShareDiagnostics = value;
+}
+
+/** Test-only: override the cached diagnostics-consent version directly. */
+export function __setCachedShareDiagnosticsVersionForTest(value: string): void {
+  cachedShareDiagnosticsVersion = value;
+}

package/src/plugin-api/constants.ts

@@ -20,7 +20,7 @@ export const HOOKS = {
   SHUTDOWN: "shutdown",
   /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
   USER_PROMPT_SUBMIT: "user-prompt-submit",
-  /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt) and opt the turn into deferred output streaming. */
+  /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt), route the call to a different inference profile, and opt the turn into deferred output streaming. */
   PRE_MODEL_CALL: "pre-model-call",
   /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
   POST_TOOL_USE: "post-tool-use",

package/src/plugin-api/index.ts

@@ -32,6 +32,11 @@
  *
  * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
  * - {@link getSecureKeyAsync} — read a secret from secure storage
+ * - {@link getModelProfiles} — list the workspace inference profiles a plugin
+ *   can route to (e.g. a model router building its category → profile map)
+ * - {@link getConfiguredProvider} — resolve a {@link Provider} for a call site
+ *   (optionally overriding the profile) and run inference through the
+ *   workspace's configured profiles and credentials — no plugin-supplied API key
  *
  * - {@link PluginInitContext} — passed to `init` hook at bootstrap
  * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
@@ -40,7 +45,8 @@
  * - {@link PostCompactContext} — passed to `post-compact` hook, fired after
  *   the agent loop compacts a conversation mid-turn to re-apply injections
  * - {@link PreModelCallContext} — passed to `pre-model-call` hook, fired
- *   before each provider call to edit the request / defer output streaming
+ *   before each provider call to edit the request, route it to a different
+ *   inference profile, or defer output streaming
  * - {@link PostToolUseContext} — passed to `post-tool-use` hook, fired once
  *   per tool result before it joins the provider-bound history
  * - {@link StopContext} — passed to `stop` hook, the definitive terminal hook
@@ -77,8 +83,23 @@ export type {
   ToolUseContent,
   WebSearchToolResultContent,
 } from "../providers/types.js";
+// Provider + inference types. A plugin that runs its own inference through
+// `getConfiguredProvider` names these to type the provider handle it gets back,
+// the request options it passes to `sendMessage`, and the response.
+export type {
+  Provider,
+  ProviderEvent,
+  ProviderResponse,
+  SendMessageConfig,
+  SendMessageOptions,
+} from "../providers/types.js";
+// Call-site identifier accepted by `getConfiguredProvider`. Plugins typically
+// pass `"inference"` (the general-purpose call site) and pick the model via the
+// `overrideProfile` option.
+export type { LLMCallSite } from "../config/schemas/llm.js";
 export type {
   AgentLoopExitReason,
+  ModelProfileInfo,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
@@ -110,3 +131,14 @@ export type {
 } from "../runtime/assistant-event-hub.js";
 export { assistantEventHub } from "../runtime/assistant-event-hub.js";
 export { getSecureKeyAsync } from "../security/secure-keys.js";
+export { getModelProfiles } from "./model-profiles.js";
+// Resolve a provider for a call site (optionally overriding the profile) so a
+// plugin can run inference through the workspace's configured profiles and
+// credentials — managed-proxy or BYOK — without supplying its own API key.
+// Pair with `getModelProfiles` to pick a profile. Returns `null` when no
+// provider is configured. By default `overrideProfile` layers below any
+// per-call-site config the workspace has pinned (e.g. a cheap `inference`
+// profile), so it loses to that pin; pass `forceOverrideProfile: true` to
+// float the chosen profile above the call-site layers when the plugin must
+// run on a specific profile regardless of workspace tuning.
+export { getConfiguredProvider } from "../providers/provider-send-message.js";

package/src/plugin-api/model-profiles.ts

@@ -0,0 +1,33 @@
+import { getConfig } from "../config/loader.js";
+import { orderProfileKeys } from "../config/profile-order.js";
+import type { ModelProfileInfo } from "./types.js";
+
+/**
+ * List the workspace inference profiles a plugin can route to, in the order the
+ * `/model` picker presents them (`llm.profileOrder` first, then the rest
+ * alphabetically). Disabled profiles are included and flagged via
+ * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
+ * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
+ * routing target (it resolves to one constituent per conversation).
+ *
+ * Reads the live in-memory config, so the result reflects the current profile
+ * set each time it is called.
+ */
+export function getModelProfiles(): ModelProfileInfo[] {
+  const { llm } = getConfig();
+  const { profiles, activeProfile } = llm;
+  const result: ModelProfileInfo[] = [];
+  for (const key of orderProfileKeys(profiles, llm.profileOrder)) {
+    const entry = profiles[key];
+    if (entry == null) continue;
+    result.push({
+      key,
+      label: entry.label ?? key,
+      description: entry.description ?? null,
+      isActive: key === activeProfile,
+      isDisabled: entry.status === "disabled",
+      isMix: entry.mix != null,
+    });
+  }
+  return result;
+}

package/src/plugin-api/types.ts

@@ -94,6 +94,35 @@ export interface PluginInitContext {
   assistantVersion: string;
 }
 
+// ─── Model profiles ──────────────────────────────────────────────────────────
+
+/**
+ * A workspace inference profile a plugin can route to. Returned by
+ * {@link getModelProfiles}; {@link key} is the value a `pre-model-call` hook
+ * assigns to `PreModelCallContext.modelProfile` to route a call. A model router
+ * reads this list (typically at `init`) to learn which profiles exist before
+ * mapping a classified message onto one.
+ */
+export interface ModelProfileInfo {
+  /** Profile key in `llm.profiles`; assignable to `PreModelCallContext.modelProfile`. */
+  readonly key: string;
+  /** Human-readable label, falling back to {@link key} when none is set. */
+  readonly label: string;
+  /** Author-supplied description, or `null` when none is set. */
+  readonly description: string | null;
+  /** Whether this is the workspace's active profile. */
+  readonly isActive: boolean;
+  /** Whether the profile is disabled; routing to it is rejected by the resolver. */
+  readonly isDisabled: boolean;
+  /**
+   * Whether this is a weighted "mix" profile — an A/B blend that resolves to one
+   * of its constituent profiles per conversation via a seeded weighted pick.
+   * Routing to its {@link key} is valid; it directs the call into the blend
+   * rather than at a single fixed model.
+   */
+  readonly isMix: boolean;
+}
+
 // ─── Shutdown context ────────────────────────────────────────────────────────
 
 /**
@@ -438,8 +467,9 @@ export interface StopContext {
  * and compaction work can share a conversation), hooks MUST self-gate on
  * {@link callSite} / {@link conversationId} before acting.
  *
- * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
- * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, route
+ * the call to a different inference profile via {@link modelProfile}, and opt
+ * this turn into deferred output streaming via {@link deferAssistantOutput}.
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
@@ -456,6 +486,24 @@ export interface PreModelCallContext {
    * append a section); the loop sends the resulting value.
    */
   systemPrompt: string | null;
+  /**
+   * Inference profile to route THIS provider call to, named by its key in the
+   * workspace `llm.profiles`. Seeded with the call's already-resolved override
+   * profile, or `null` when none applies. A hook may replace it to select a
+   * different profile per call — the lever a model router uses to map a
+   * classified message onto a profile (model + provider connection + sampling
+   * settings). For the user-facing `mainAgent` call the resolver layers the
+   * named profile at the top of precedence (above the workspace active
+   * profile), so the hook's choice wins; a key with no matching profile falls
+   * through unchanged (no throw). Honored only when {@link callSite} is set.
+   * Set to `null` to apply no override.
+   *
+   * Context-window sizing and overflow recovery for this call are computed from
+   * the profile resolved before the hook runs. Routing a near-budget
+   * conversation to a profile with a smaller context window relies on the loop's
+   * overflow recovery (compact and retry) rather than proactive compaction.
+   */
+  modelProfile: string | null;
   /**
    * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
    * live assistant `text_delta` stream; a `post-model-call` hook is then

package/src/plugins/defaults/advisor/__tests__/advisor-gate.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// Drive the gate off a controllable llm config + a stubbed default-profile
+// resolver, so we can assert the default-on semantics precisely.
+let mockLlm: {
+  profiles: Record<string, { advisorEnabled?: boolean | null }>;
+  activeProfile?: string;
+} = { profiles: {} };
+
+mock.module("../../../../config/loader.js", () => ({
+  getConfig: () => ({ llm: mockLlm }),
+}));
+mock.module("../../../../config/llm-resolver.js", () => ({
+  resolveDefaultProfileKey: () => "balanced",
+}));
+
+const { advisorEnabledForProfile } = await import("../advisor-gate.js");
+
+describe("advisorEnabledForProfile", () => {
+  test("default-on when the profile omits the flag", () => {
+    mockLlm = { profiles: { p: {} }, activeProfile: "p" };
+    expect(advisorEnabledForProfile("p")).toBe(true);
+  });
+
+  test("default-on when the flag is null", () => {
+    mockLlm = { profiles: { p: { advisorEnabled: null } }, activeProfile: "p" };
+    expect(advisorEnabledForProfile("p")).toBe(true);
+  });
+
+  test("disabled only on an explicit false", () => {
+    mockLlm = {
+      profiles: { p: { advisorEnabled: false } },
+      activeProfile: "p",
+    };
+    expect(advisorEnabledForProfile("p")).toBe(false);
+  });
+
+  test("enabled on an explicit true", () => {
+    mockLlm = { profiles: { p: { advisorEnabled: true } }, activeProfile: "p" };
+    expect(advisorEnabledForProfile("p")).toBe(true);
+  });
+
+  test("falls back to the active profile when modelProfile is null", () => {
+    mockLlm = {
+      profiles: { a: { advisorEnabled: false } },
+      activeProfile: "a",
+    };
+    expect(advisorEnabledForProfile(null)).toBe(false);
+  });
+
+  test("falls back to the call-site default profile when neither is set", () => {
+    // resolveDefaultProfileKey is stubbed to "balanced".
+    mockLlm = { profiles: { balanced: { advisorEnabled: false } } };
+    expect(advisorEnabledForProfile(null)).toBe(false);
+  });
+});