@vellumai/assistant 0.9.1-staging.1 → 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/index.ts

@@ -34,6 +34,9 @@
  * - {@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
@@ -80,6 +83,20 @@ 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,
@@ -115,3 +132,13 @@ export type {
 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/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);
+  });
+});

package/src/plugins/defaults/advisor/__tests__/advisor-state-store.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { Message } from "../../../../providers/types.js";
+import {
+  getCapture,
+  recordMessages,
+  recordSystemPrompt,
+  resetAdvisorStateForTests,
+  seedCapture,
+} from "../advisor-state-store.js";
+
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+afterEach(() => {
+  resetAdvisorStateForTests();
+});
+
+describe("advisor state store", () => {
+  test("records system prompt and messages independently per conversation", () => {
+    recordSystemPrompt("c1", "system A");
+    recordMessages("c1", [userMsg("hello")]);
+    recordSystemPrompt("c2", "system B");
+
+    expect(getCapture("c1")?.systemPrompt).toBe("system A");
+    expect(getCapture("c1")?.messages).toEqual([userMsg("hello")]);
+    expect(getCapture("c2")?.systemPrompt).toBe("system B");
+    expect(getCapture("c2")?.messages).toEqual([]);
+  });
+
+  test("seedCapture snapshots (copies) the array", () => {
+    const live: Message[] = [userMsg("one")];
+    seedCapture("c1", live);
+    live.push(userMsg("two"));
+    expect(getCapture("c1")?.messages).toEqual([userMsg("one")]);
+  });
+
+  test("getCapture returns undefined for an unseen conversation", () => {
+    expect(getCapture("nope")).toBeUndefined();
+  });
+});