@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/config/__tests__/deployment-context-defaults.test.ts

@@ -164,6 +164,15 @@ describe("deployment-context embedding-provider default (via loadConfig)", () =>
     >;
     expect(webSearchRaw.mode).not.toBe("managed");
 
+    // image-generation's managed axis is its provider: the seeded value is
+    // the platform fill "vellum", never an injected managed mode.
+    const imageGenRaw = (servicesRaw["image-generation"] ?? {}) as Record<
+      string,
+      unknown
+    >;
+    expect(imageGenRaw.provider).toBe("vellum");
+    expect(imageGenRaw.mode).not.toBe("managed");
+
     // Regression guard: on the NEXT load (config.json now exists with the
     // provider leaf absent), the platform default re-applies in memory rather
     // than being lost to a persisted "auto" read back as an explicit choice.

package/src/config/__tests__/substrate-twin-shadowing.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+
+import { MemorySubstrateConfigSchema } from "../schemas/memory-substrate.js";
+import { MemoryV2ConfigSchema } from "../schemas/memory-v2.js";
+import {
+  describeShadowedConfigGet,
+  describeShadowedConfigSet,
+  findSubstrateShadowing,
+  SUBSTRATE_TWIN_BY_V2_KEY,
+} from "../substrate-twin-shadowing.js";
+
+describe("substrate twin table", () => {
+  test("pairs exactly the memory.substrate schema's keys", () => {
+    // Drift guard: a substrate key with no entry here is a tunable whose
+    // shadowing goes unreported, which is the silent no-op this module exists
+    // to prevent.
+    expect(
+      new Set(
+        Object.values(SUBSTRATE_TWIN_BY_V2_KEY).map((t) => t.substrateKey),
+      ),
+    ).toEqual(new Set(Object.keys(MemorySubstrateConfigSchema.shape)));
+  });
+
+  test("names a real memory.v2 key on every left-hand side", () => {
+    const v2Keys = new Set(Object.keys(MemoryV2ConfigSchema.shape));
+    for (const v2Key of Object.keys(SUBSTRATE_TWIN_BY_V2_KEY)) {
+      expect(v2Keys).toContain(v2Key);
+    }
+  });
+
+  test("flags exactly the three twins the v2 injection engine reads directly", () => {
+    // `v2/injection.ts` destructures `k` / `hops` off `config.memory.v2` (as
+    // does `v2/backfill-jobs.ts`) and `v2/activation.ts` reads
+    // `config.memory.v2.ann_candidate_limit`. Every other twin's only reader
+    // is `resolveSubstrateTuning`. Widening this set without a matching
+    // direct read makes the warnings claim a divergence that cannot happen.
+    const engineRead = Object.entries(SUBSTRATE_TWIN_BY_V2_KEY)
+      .filter(([, twin]) => twin.alsoReadByV2Engine)
+      .map(([v2Key]) => v2Key)
+      .sort();
+    expect(engineRead).toEqual(["ann_candidate_limit", "hops", "k"]);
+  });
+});
+
+describe("findSubstrateShadowing", () => {
+  test("reports the winning substrate twin for a shadowed memory.v2 key", () => {
+    const raw = {
+      memory: {
+        v2: { consolidation_interval_hours: 4 },
+        substrate: { consolidation_interval_hours: 876000 },
+      },
+    };
+
+    expect(
+      findSubstrateShadowing(raw, "memory.v2.consolidation_interval_hours"),
+    ).toEqual({
+      substratePath: "memory.substrate.consolidation_interval_hours",
+      substrateValue: 876000,
+      alsoReadByV2Engine: false,
+    });
+  });
+
+  test("maps the renamed spread keys to their substrate names", () => {
+    const raw = { memory: { v2: {}, substrate: { spread_k: 0.4 } } };
+
+    expect(findSubstrateShadowing(raw, "memory.v2.k")).toEqual({
+      substratePath: "memory.substrate.spread_k",
+      substrateValue: 0.4,
+      alsoReadByV2Engine: true,
+    });
+    // hops has no twin set, so nothing shadows it.
+    expect(findSubstrateShadowing(raw, "memory.v2.hops")).toBeUndefined();
+  });
+
+  test("treats an explicit null twin as set, matching resolveSubstrateTuning", () => {
+    // `orV2` falls back only on `undefined`, so a null substrate value wins —
+    // and it is exactly the value the consolidation freeze writes.
+    const raw = {
+      memory: {
+        v2: { consolidation_max_buffer_lines: 100 },
+        substrate: { consolidation_max_buffer_lines: null },
+      },
+    };
+
+    expect(
+      findSubstrateShadowing(raw, "memory.v2.consolidation_max_buffer_lines"),
+    ).toEqual({
+      substratePath: "memory.substrate.consolidation_max_buffer_lines",
+      substrateValue: null,
+      alsoReadByV2Engine: false,
+    });
+  });
+
+  test("returns nothing for unshadowed paths", () => {
+    const raw = {
+      memory: {
+        v2: { bm25_b: 0.6, enabled: true },
+        substrate: { bm25_b: 0.3 },
+      },
+    };
+
+    // No memory.substrate subtree at all.
+    expect(
+      findSubstrateShadowing(
+        { memory: { v2: { bm25_b: 0.6 } } },
+        "memory.v2.bm25_b",
+      ),
+    ).toBeUndefined();
+    // A v2 key with no substrate twin.
+    expect(findSubstrateShadowing(raw, "memory.v2.enabled")).toBeUndefined();
+    // The substrate key itself is what wins — writing it is never shadowed.
+    expect(
+      findSubstrateShadowing(raw, "memory.substrate.bm25_b"),
+    ).toBeUndefined();
+    // Paths outside the memory namespace, and the wrong depth.
+    expect(findSubstrateShadowing(raw, "memory.v2")).toBeUndefined();
+    expect(findSubstrateShadowing(raw, "llm.v2.bm25_b")).toBeUndefined();
+  });
+});
+
+describe("describeShadowedConfigSet", () => {
+  test("a substrate-only twin reads as the no-op it is", () => {
+    const message = describeShadowedConfigSet(
+      {
+        substratePath: "memory.substrate.consolidation_interval_hours",
+        substrateValue: 876000,
+        alsoReadByV2Engine: false,
+      },
+      "memory.v2.consolidation_interval_hours",
+    );
+
+    expect(message).toContain(
+      "memory.substrate.consolidation_interval_hours is set (876000)",
+    );
+    expect(message).toContain("does not change the effective value");
+    expect(message).toContain(
+      "assistant config set memory.substrate.consolidation_interval_hours",
+    );
+  });
+
+  test("an engine-read twin reports divergence, never inertness", () => {
+    // `memory.v2.k` still tunes the live v2 injection engine, so claiming the
+    // write is inert would send an operator chasing a phantom.
+    const message = describeShadowedConfigSet(
+      {
+        substratePath: "memory.substrate.spread_k",
+        substrateValue: 0.4,
+        alsoReadByV2Engine: true,
+      },
+      "memory.v2.k",
+    );
+
+    expect(message).toContain("does change its behavior");
+    expect(message).toContain("memory.substrate.spread_k (0.4)");
+    expect(message).toContain("diverge");
+    expect(message).not.toContain("does not change the effective value");
+  });
+});
+
+describe("describeShadowedConfigGet", () => {
+  test("a substrate-only twin names the key that is the effective value", () => {
+    const message = describeShadowedConfigGet(
+      {
+        substratePath: "memory.substrate.bm25_b",
+        substrateValue: 0.3,
+        alsoReadByV2Engine: false,
+      },
+      "memory.v2.bm25_b",
+    );
+
+    expect(message).toContain("Shadowed: memory.substrate.bm25_b = 0.3");
+    expect(message).toContain("is the effective value");
+  });
+
+  test("an engine-read twin names both readers", () => {
+    const message = describeShadowedConfigGet(
+      {
+        substratePath: "memory.substrate.ann_candidate_limit",
+        substrateValue: null,
+        alsoReadByV2Engine: true,
+      },
+      "memory.v2.ann_candidate_limit",
+    );
+
+    expect(message).toContain(
+      "Split: memory.substrate.ann_candidate_limit = null",
+    );
+    expect(message).toContain("substrate recall");
+    expect(message).toContain("memory.v2.ann_candidate_limit");
+  });
+});

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

@@ -10,7 +10,7 @@
  *   3. `false`                                    (for undeclared keys)
  *
  * Key format:
- *   Canonical:  simple kebab-case string (e.g., "browser", "voice-mode")
+ *   Canonical:  simple kebab-case string (e.g., "browser", "contacts")
  */
 
 import { existsSync, readFileSync } from "node:fs";

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

@@ -1,4 +1,7 @@
-import { resolveImageGenCredentials } from "../../../../media/image-credentials.js";
+import {
+  resolveImageGenCredentials,
+  resolveImageGenRouting,
+} from "../../../../media/image-credentials.js";
 import {
   describeImageModels,
   resolveImageModel,
@@ -6,7 +9,6 @@ import {
 import {
   generateImage,
   mapImageGenError,
-  providerForModel,
 } from "../../../../media/image-service.js";
 import { getFilePathBySourcePath } from "../../../../persistence/attachments-store.js";
 import type { ImageContent } from "../../../../providers/types.js";
@@ -37,13 +39,17 @@ export async function run(
     }
     modelOverride = entry.id;
   }
-  // Derive provider from the explicit model when supplied so that requesting
-  // e.g. `gpt-image-2` while config.provider === "gemini" routes to OpenAI
-  // instead of silently falling back to the Gemini default model.
-  const provider = providerForModel(modelOverride, svc.provider);
+  // Backend and managed-ness resolve together: an explicit model re-routes
+  // to the model's backend (e.g. `gpt-image-2` under a gemini config routes
+  // to OpenAI), and provider "vellum" runs managed with a model-derived
+  // backend.
+  const { backendProvider: provider, managed } = resolveImageGenRouting(
+    svc,
+    modelOverride,
+  );
   const { credentials, errorHint } = await resolveImageGenCredentials({
     provider,
-    mode: svc.mode,
+    managed,
   });
   if (!credentials) {
     return {

package/src/config/feature-flag-cache.ts

@@ -12,10 +12,10 @@
  *
  * State is held on `globalThis.vellumAssistant.featureFlagCache` so test
  * helpers in `__tests__/` can read/write it WITHOUT importing this
- * module — they declare the same slot shape locally and access the
- * globalThis namespace directly. See
- * `__tests__/feature-flag-test-helpers.ts` for the test-side mirror;
- * the slot shape MUST stay in sync between the two.
+ * module. Both sides reference the shared ambient `VellumFeatureFlagCache`
+ * type (declared in `src/vellum-assistant-namespace.d.ts`), which types the
+ * slot without adding a runtime import between them. See
+ * `__tests__/feature-flag-test-helpers.ts` for the test-side writer.
  *
  * Both `overrides` and `fromGateway` were previously module-level `let`
  * bindings inside `assistant-feature-flags.ts`. The semantics are
@@ -28,18 +28,8 @@
  *   - `__tests__/feature-flag-test-helpers.ts` (seeds for tests, via globalThis)
  */
 
-type FlagSlot = {
-  overrides: Record<string, boolean | string> | null;
-  fromGateway: boolean;
-};
-
-type VellumAssistantNamespace = {
-  featureFlagCache?: FlagSlot;
-};
-
-function slot(): FlagSlot {
-  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
-  const ns = (g.vellumAssistant ??= {});
+function slot(): VellumFeatureFlagCache {
+  const ns = (globalThis.vellumAssistant ??= {});
   return (ns.featureFlagCache ??= { overrides: null, fromGateway: false });
 }
 

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

@@ -6,7 +6,7 @@
       "scope": "client",
       "key": "in-chat-onboarding-tour",
       "label": "In-Chat Onboarding Tour",
-      "description": "Multivariate experiment for the eyes-led in-chat onboarding tour. control = straight to chat after research onboarding (current behavior); tour = the extended tour auto-plays on first workspace entry, and the header replay button shows. Desktop-only: phone-width viewports and the native shell get neither the tour nor its telemetry (not even the exposure event), so the funnel measures desktop sessions exclusively. Targeted via LaunchDarkly (planned 70% tour / 30% control).",
+      "description": "Multivariate experiment for the eyes-led in-chat onboarding tour. control = straight to chat after research onboarding (current behavior); tour = the extended tour auto-plays on first workspace entry. Desktop-only: phone-width viewports and the native shell get neither the tour nor its telemetry (not even the exposure event), so the funnel measures desktop sessions exclusively. Targeted via LaunchDarkly (70% tour / 30% control).",
       "defaultEnabled": "control",
       "values": ["control", "tour"]
     },
@@ -117,14 +117,6 @@
       "description": "Show older versions in the version picker, allowing rollback to previous releases",
       "defaultEnabled": false
     },
-    {
-      "id": "voice-mode",
-      "scope": "assistant",
-      "key": "voice-mode",
-      "label": "Voice Mode",
-      "description": "Show the live voice conversation button in the composer",
-      "defaultEnabled": false
-    },
     {
       "id": "voice-duplex-handoff",
       "scope": "assistant",
@@ -293,14 +285,6 @@
       "description": "Expose the developer-only Memory Router Playground tab in macOS Settings and the /assistant/memory-router-playground web page for dry-running v4 router config overrides against the live page index. Dev-only; default off.",
       "defaultEnabled": false
     },
-    {
-      "id": "memory-v3-injection-gate",
-      "scope": "assistant",
-      "key": "memory-v3-injection-gate",
-      "label": "Memory v3 injection gate",
-      "description": "Per-turn injection gate for memory v3: after the BM25F needle + dense cosine finder lanes run, skip the selectPool LLM call (inject nothing) when finder-lane scores fall below the configured thresholds (memory.v3.gate). Default on (flipped remotely July 2026); this registry value is the fallback when no platform snapshot is available.",
-      "defaultEnabled": true
-    },
     {
       "id": "self-intro-greeting",
       "scope": "both",
@@ -350,27 +334,27 @@
       "defaultEnabled": false
     },
     {
-      "id": "credentials-settings",
+      "id": "chat-credential-reveal",
       "scope": "assistant",
-      "key": "credentials-settings",
-      "label": "Credentials settings page",
-      "description": "Show the Credentials page in web settings for listing, adding, and deleting stored credentials.",
+      "key": "chat-credential-reveal",
+      "label": "Chat Credential Reveal",
+      "description": "Persist chat secret redactions as sentinel markers instead of the legacy HTML marker, enriched with the vault identity when the value byte-matches a credential revealed this turn. Also gates the `credentials reveal --for-chat` channel and the live-stream swap that replaces an echoed reveal plaintext with its sentinel before emission. Redaction itself is NOT gated: a route-proven reveal plaintext stays out of persisted rows in both modes. Client chip rendering is gated on daemon version, not on this flag.",
       "defaultEnabled": false
     },
     {
-      "id": "credential-requests",
+      "id": "composer-secret-guard",
       "scope": "assistant",
-      "key": "credential-requests",
-      "label": "One-time credential request links",
-      "description": "Enable one-time credential-request links: the generate-link action in settings, the public credential entry page, and assistant-initiated links on channels without secure input.",
+      "key": "composer-secret-guard",
+      "label": "Composer Secret Guard",
+      "description": "Detect API keys/secrets typed into the chat composer and offer secure credential storage before send",
       "defaultEnabled": false
     },
     {
-      "id": "chat-credential-reveal",
-      "scope": "assistant",
-      "key": "chat-credential-reveal",
-      "label": "Chat Credential Reveal",
-      "description": "Persist chat secret redactions as sentinel markers instead of the legacy HTML marker, enriched with the vault identity when the value byte-matches a credential revealed this turn. Also gates the `credentials reveal --for-chat` channel and the live-stream swap that replaces an echoed reveal plaintext with its sentinel before emission. Redaction itself is NOT gated: a route-proven reveal plaintext stays out of persisted rows in both modes. Client chip rendering is gated on daemon version, not on this flag.",
+      "id": "marketing-pricing-takeover",
+      "scope": "client",
+      "key": "marketing-pricing-takeover",
+      "label": "Marketing Pricing Takeover",
+      "description": "Gates the marketing pricing takeover page (www.vellum.ai/pricing) and the `/assistant/checkout?package=<slug>` deep link its package CTAs target. One flag covers both halves of the funnel so they can never be enabled independently and strand a CTA. When off, the checkout deep link redirects to the in-app plans takeover.",
       "defaultEnabled": false
     }
   ]

package/src/config/loader.ts

@@ -156,7 +156,13 @@ export function getDeploymentContextDefaults(): Record<string, unknown> {
     // default (`gemini-embedding-2`).
     memory: { embeddings: { provider: "gemini" } },
     services: {
-      "image-generation": managed,
+      // Image-generation is provider-only for the managed axis: `vellum`
+      // generates through the platform runtime proxy (the backend derives
+      // from the selected model's prefix at request time). Hosted assistants
+      // default to it here; fill-only, so an explicit on-disk BYOK provider
+      // (gemini/openai) always wins. Filling a `mode` instead would
+      // re-manage BYOK configs on every load.
+      "image-generation": { provider: "vellum" },
       "google-oauth": managed,
       "outlook-oauth": managed,
       "linear-oauth": managed,

package/src/config/memory-tier.ts

@@ -1,30 +1,35 @@
-import { isMemoryV3Live } from "./memory-v3-gate.js";
+import {
+  isMemoryEnabled,
+  isMemoryV3Live,
+  isV2InjectionEngineActive,
+} from "./memory-v3-gate.js";
 import type { AssistantConfig } from "./schema.js";
 
 export type MemoryTier = "off" | "v1" | "v2" | "v3";
 
 /**
  * Derive the coarse memory tier for an assistant, as a single bucket for
- * telemetry. Precedence mirrors the runtime memory-source semantics:
+ * telemetry. Precedence is defined by the named gate predicates in
+ * `memory-v3-gate.ts` — this function is fully derived from them, so the tier
+ * buckets and the runtime gates can never disagree:
  *
- * - `"off"` wins over everything: an explicit `memory.enabled === false`
- *   disables the whole memory system regardless of v2/v3 settings.
+ * - `"off"` wins over everything: {@link isMemoryEnabled} is false when an
+ *   explicit `memory.enabled === false` disables the whole memory system,
+ *   regardless of v2/v3 settings.
  * - `"v3"` wins over `"v2"`: when memory-v3 is live it suppresses v2 injection
  *   (see {@link isMemoryV3Live}).
- * - `"v2"` when v2 is explicitly enabled and v3 is not live.
+ * - `"v2"` when the v2 injection engine performs turn-time selection
+ *   (see {@link isV2InjectionEngineActive}).
  * - `"v1"` otherwise (memory on, neither v2 nor v3 selected).
- *
- * Optional chaining is defensive — a partial config (e.g. a mocked config in
- * tests) resolves to the correct bucket rather than throwing.
  */
 export function memoryTier(config: AssistantConfig): MemoryTier {
-  if (config.memory?.enabled === false) {
+  if (!isMemoryEnabled(config)) {
     return "off";
   }
   if (isMemoryV3Live(config)) {
     return "v3";
   }
-  if (config.memory?.v2?.enabled === true) {
+  if (isV2InjectionEngineActive(config)) {
     return "v2";
   }
   return "v1";