@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/plugins/defaults/image-fallback/src/caption-blocks.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared image→text substitution for the image-fallback plugin's hooks.
+ *
+ * Two hooks replace `image` content blocks with a text caption when the turn's
+ * model can't process images: `user-prompt-submit` handles user-attached
+ * images, and `post-tool-use` handles images a tool returns (e.g. a browser
+ * screenshot). This module holds what they share — deciding whether a profile
+ * needs the fallback ({@link needsImageFallback}) and the per-block
+ * substitution ({@link captionImageBlocks}): persist the original image to a
+ * known location, caption it via a vision-capable profile, and swap in a
+ * `[Image …]` text block.
+ *
+ * The substitution mutates the blocks in place, so the caption replaces the
+ * image everywhere the block is referenced (the provider-bound history and the
+ * persisted/displayed copy alike) — a text-only turn does not keep the raw
+ * image around.
+ *
+ * The caption text states up front that the model can't view images and the
+ * image was auto-described to text, so the model treats the block as a derived
+ * description rather than a verbatim transcript.
+ *
+ * Fail-open is the dominant error mode: a captioning failure leaves a
+ * placeholder text block rather than the raw image (which a text-only provider
+ * would reject) or nothing (which would lose information).
+ */
+
+import {
+  type ContentBlock,
+  doesSupportVision,
+  getModelProfiles,
+  type ImageContent,
+  type PluginLogger,
+} from "@vellumai/plugin-api";
+
+import { persistImage } from "./image-persist.js";
+import { captionImage } from "./vision-caption.js";
+
+/**
+ * Whether the profile a turn runs needs image→text fallback (i.e. it can't
+ * process images itself).
+ *
+ * Used by `user-prompt-submit`, whose context carries the profile key rather
+ * than the resolved model id: prefer the turn's `modelProfileKey` — which
+ * carries a text-only override even when the workspace's active profile is
+ * vision-capable — and fall back to the active profile only when the key is
+ * `null` (profile unchanged since the last notified turn). Returns `false` when
+ * no profile resolves or the resolved model already supports vision, in which
+ * case the image reaches the model untouched.
+ */
+export function needsImageFallback(modelProfileKey: string | null): boolean {
+  const profiles = getModelProfiles();
+  const activeProfile =
+    modelProfileKey != null
+      ? profiles.find((p) => p.key === modelProfileKey)
+      : profiles.find((p) => p.isActive);
+  if (activeProfile == null) return false;
+  return !doesSupportVision(activeProfile);
+}
+
+/**
+ * Replace every `image` block in `blocks` (in place) with a text caption so a
+ * text-only model can still reason about the image's content. Returns the
+ * number of image blocks replaced.
+ *
+ * @param blocks            Content-block array to scan and mutate in place.
+ * @param visionProfileKey  Key of a vision-capable profile for captioning, or
+ *                          `null` when none is configured (fail-open
+ *                          placeholder).
+ * @param logger            Turn-scoped logger for attribution.
+ */
+export async function captionImageBlocks(
+  blocks: ContentBlock[],
+  visionProfileKey: string | null,
+  logger: PluginLogger,
+): Promise<number> {
+  let imageCount = 0;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (block.type !== "image") continue;
+
+    imageCount++;
+    const image = block as ImageContent;
+
+    // Persist the original to a known, content-hash-deduped location so it
+    // survives the text substitution and stays findable on disk.
+    persistImage(image.source.data, image.source.media_type);
+
+    if (visionProfileKey != null) {
+      const caption = await captionImage(image, visionProfileKey, logger);
+      blocks[i] = {
+        type: "text",
+        text:
+          caption != null
+            ? `[Image auto-described for text-only model: ${caption}]`
+            : `[Image: auto-description failed (text-only model)]`,
+      };
+    } else {
+      // No vision profile configured at all — fail-open placeholder.
+      blocks[i] = {
+        type: "text",
+        text: `[Image: no vision-capable model configured to describe it]`,
+      };
+    }
+  }
+
+  return imageCount;
+}

package/src/plugins/defaults/image-fallback/src/caption-cache.ts

@@ -0,0 +1,49 @@
+/**
+ * In-memory LRU cache for image captions, keyed by the sha-256 hash of the
+ * image's base64 data.
+ *
+ * The cache survives across turns within a session, which is the primary
+ * correctness concern: without it, the same image would be re-captioned
+ * (and re-billed) on every turn because `user-prompt-submit` rebuilds
+ * `latestMessages` from the stored conversation each time. Re-captioning
+ * on a daemon restart is acceptable — captions are cheap and the image
+ * is still in the history.
+ */
+
+import { createHash } from "node:crypto";
+
+const MAX_ENTRIES = 500;
+
+const cache = new Map<string, string>();
+
+/** sha-256 hex digest of an image's base64 payload. */
+export function imageHash(data: string): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/** Look up a cached caption. `undefined` = miss; a string (even empty) = hit. */
+export function getCachedCaption(hash: string): string | undefined {
+  const value = cache.get(hash);
+  if (value !== undefined) {
+    // Move to end (most-recently-used) for LRU eviction.
+    cache.delete(hash);
+    cache.set(hash, value);
+  }
+  return value;
+}
+
+/** Store a caption, evicting the least-recently-used entry if at capacity. */
+export function setCachedCaption(hash: string, caption: string): void {
+  if (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next();
+    if (!oldest.done) {
+      cache.delete(oldest.value as string);
+    }
+  }
+  cache.set(hash, caption);
+}
+
+/** Test-only: clear the cache. */
+export function resetCaptionCacheForTests(): void {
+  cache.clear();
+}

package/src/plugins/defaults/image-fallback/src/image-persist.ts

@@ -0,0 +1,56 @@
+/**
+ * Persist image data to the workspace attachments directory.
+ *
+ * When the active model is text-only, the image-fallback plugin captions the
+ * image and substitutes a text block. Saving the raw image to a known,
+ * content-hash-deduped location means the original survives the text
+ * substitution and stays findable on disk for the user (or a subagent with a
+ * vision-capable model that reads it via file_read).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { imageHash } from "./caption-cache.js";
+
+/** The workspace attachments directory. */
+const ATTACHMENTS_DIR = "/workspace/data/attachments";
+
+/** File extension for a given media type, falling back to `.bin`. */
+function extensionForMediaType(mediaType: string): string {
+  switch (mediaType) {
+    case "image/png":
+      return ".png";
+    case "image/jpeg":
+      return ".jpg";
+    case "image/gif":
+      return ".gif";
+    case "image/webp":
+      return ".webp";
+    default:
+      return ".bin";
+  }
+}
+
+/**
+ * Save an image's base64 data to the attachments dir if not already present.
+ * Returns the absolute file path, or `null` when the write fails.
+ */
+export function persistImage(data: string, mediaType: string): string | null {
+  try {
+    mkdirSync(ATTACHMENTS_DIR, { recursive: true });
+
+    const hash = imageHash(data);
+    const ext = extensionForMediaType(mediaType);
+    const filename = `${hash}${ext}`;
+    const filepath = join(ATTACHMENTS_DIR, filename);
+
+    // Skip if already saved (content-hash dedup).
+    if (existsSync(filepath)) return filepath;
+
+    writeFileSync(filepath, Buffer.from(data, "base64"));
+    return filepath;
+  } catch {
+    return null;
+  }
+}

package/src/plugins/defaults/image-fallback/src/vision-caption.ts

@@ -0,0 +1,120 @@
+/**
+ * Vision-based image captioning for the image-fallback plugin.
+ *
+ * When the active model cannot process images, this module finds a
+ * vision-capable profile in the workspace's configured profiles and runs a
+ * one-shot captioning call through the assistant's own inference (no
+ * plugin-supplied API key). The caption replaces the image block in the
+ * outgoing message history.
+ */
+
+import {
+  doesSupportVision,
+  getConfiguredProvider,
+  getModelProfiles,
+  type ImageContent,
+  type PluginLogger,
+} from "@vellumai/plugin-api";
+
+import { extractAllText } from "../../../../providers/provider-send-message.js";
+import {
+  getCachedCaption,
+  imageHash,
+  setCachedCaption,
+} from "./caption-cache.js";
+
+const CAPTION_TIMEOUT_MS = 30_000;
+
+const CAPTION_SYSTEM_PROMPT =
+  "You are a vision assistant. Describe the image concisely in 1-2 sentences. " +
+  "Focus on the key visual content, text, charts, or UI elements that would be " +
+  "relevant for a text-based assistant to understand and reason about.";
+
+const CAPTION_USER_PROMPT = "Describe this image concisely for a text-only assistant.";
+
+/**
+ * Find a vision-capable, enabled profile key for captioning.
+ *
+ * Scans the workspace's profiles in `getModelProfiles()` order (the same order
+ * the `/model` picker shows them) and returns the first enabled profile whose
+ * resolved model supports vision. Returns `null` when no vision profile exists
+ * — the hook fails-open in that case, leaving a placeholder text block.
+ */
+export function findVisionProfile(): string | null {
+  for (const profile of getModelProfiles()) {
+    if (profile.isDisabled) continue;
+    if (doesSupportVision(profile)) {
+      return profile.key;
+    }
+  }
+  return null;
+}
+
+/**
+ * Caption a single image block via a vision-capable profile.
+ *
+ * @param image     The image content block to caption.
+ * @param profileKey  Key of a vision-capable profile (from {@link findVisionProfile}).
+ * @param logger    Turn-scoped logger for attribution.
+ * @returns The caption text, or `null` when captioning failed (caller should
+ *          use a fail-open placeholder).
+ */
+export async function captionImage(
+  image: ImageContent,
+  profileKey: string,
+  logger: PluginLogger,
+): Promise<string | null> {
+  const hash = imageHash(image.source.data);
+  const cached = getCachedCaption(hash);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  try {
+    const provider = await getConfiguredProvider("vision", {
+      overrideProfile: profileKey,
+      forceOverrideProfile: true,
+    });
+    if (!provider) {
+      logger.warn(
+        { plugin: "image-fallback" },
+        "No provider resolved for vision captioning profile",
+      );
+      return null;
+    }
+
+    const response = await provider.sendMessage(
+      [
+        {
+          role: "user",
+          content: [image, { type: "text", text: CAPTION_USER_PROMPT }],
+        },
+      ],
+      {
+        systemPrompt: CAPTION_SYSTEM_PROMPT,
+        config: {
+          callSite: "vision",
+          overrideProfile: profileKey,
+          forceOverrideProfile: true,
+          tool_choice: { type: "none" },
+        },
+        signal: AbortSignal.timeout(CAPTION_TIMEOUT_MS),
+      },
+    );
+
+    const caption = extractAllText(response).trim();
+    if (caption.length > 0) {
+      setCachedCaption(hash, caption);
+      return caption;
+    }
+
+    logger.warn({ plugin: "image-fallback" }, "Vision captioning returned empty text");
+    return null;
+  } catch (err) {
+    logger.warn(
+      { plugin: "image-fallback", err },
+      "Vision captioning call failed",
+    );
+    return null;
+  }
+}

package/src/plugins/defaults/index.ts

@@ -47,6 +47,10 @@ import historyRepairStop from "./history-repair/hooks/stop.js";
 import historyRepairUserPromptSubmit from "./history-repair/hooks/user-prompt-submit.js";
 import historyRepairPkg from "./history-repair/package.json" with { type: "json" };
 import { resetRepairStateStoreForTests } from "./history-repair/repair-state-store.js";
+import imageFallbackPostToolUse from "./image-fallback/hooks/post-tool-use.js";
+import imageFallbackUserPromptSubmit from "./image-fallback/hooks/user-prompt-submit.js";
+import imageFallbackPkg from "./image-fallback/package.json" with { type: "json" };
+import { resetCaptionCacheForTests } from "./image-fallback/src/caption-cache.js";
 import imageRecoveryPostModelCall from "./image-recovery/hooks/post-model-call.js";
 import imageRecoveryStop from "./image-recovery/hooks/stop.js";
 import { resetImageRecoveryStoreForTests } from "./image-recovery/image-recovery-state-store.js";
@@ -77,6 +81,27 @@ import toolErrorPkg from "./tool-error/package.json" with { type: "json" };
 import toolResultTruncatePostToolUse from "./tool-result-truncate/hooks/post-tool-use.js";
 import toolResultTruncatePkg from "./tool-result-truncate/package.json" with { type: "json" };
 
+/**
+ * `image-fallback` — captions image blocks via a vision-capable profile when
+ * the active model is text-only, substituting the caption as an `[Image …]`
+ * text block so the model can still reason about the image's content. The
+ * `user-prompt-submit` hook handles user-attached images; the `post-tool-use`
+ * hook handles images a tool returns (e.g. a browser screenshot) nested in the
+ * tool result's `contentBlocks`. Fail-open with a placeholder when no vision
+ * profile is configured or captioning fails. An in-memory content-hash cache
+ * avoids re-captioning the same image across turns.
+ */
+export const defaultImageFallbackPlugin: Plugin = {
+  manifest: {
+    name: imageFallbackPkg.name,
+    version: imageFallbackPkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": imageFallbackUserPromptSubmit,
+    "post-tool-use": imageFallbackPostToolUse,
+  },
+};
+
 /**
  * `compaction` — compaction is implemented in `compaction/compact.ts` as
  * `defaultCompact`, which the agent loop calls directly. The plugin stays
@@ -337,6 +362,7 @@ export const defaultAdvisorPlugin: Plugin = {
 function getAllDefaultPlugins(): readonly Plugin[] {
   return [
     defaultMemoryRetrievalPlugin,
+    defaultImageFallbackPlugin,
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultMaxTokensContinuePlugin,
@@ -399,5 +425,6 @@ export function resetPluginRegistryAndRegisterDefaults(): void {
   resetTaskProgressNudgeStateForTests();
   resetSurfaceCompletionNudgeStoreForTests();
   resetAdvisorStateForTests();
+  resetCaptionCacheForTests();
   registerDefaultPlugins();
 }

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit.ts

@@ -194,6 +194,9 @@ function persistInjectionBlocks(
     !blocks.pkbContextBlock &&
     !blocks.memoryV2StaticBlock &&
     !blocks.memoryV3InjectedBlock &&
+    !blocks.backgroundTurnBlock &&
+    !blocks.channelCapabilitiesBlock &&
+    !blocks.nonInteractiveContextBlock &&
     !removeV2Block
   ) {
     return;
@@ -229,6 +232,17 @@ function persistInjectionBlocks(
     if (blocks.memoryV2StaticBlock) {
       metadataUpdates.memoryV2StaticBlock = blocks.memoryV2StaticBlock;
     }
+    if (blocks.backgroundTurnBlock) {
+      metadataUpdates.backgroundTurnBlock = blocks.backgroundTurnBlock;
+    }
+    if (blocks.channelCapabilitiesBlock) {
+      metadataUpdates.channelCapabilitiesBlock =
+        blocks.channelCapabilitiesBlock;
+    }
+    if (blocks.nonInteractiveContextBlock) {
+      metadataUpdates.nonInteractiveContextBlock =
+        blocks.nonInteractiveContextBlock;
+    }
     updateMessageMetadata(ctx.userMessageId, metadataUpdates);
   } catch (err) {
     ctx.logger.warn(
@@ -264,7 +278,6 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
     resolveTrustClass(conversation?.trustContext) === "guardian";
   const actorContext = resolveTurnInboundActorContext(
     conversation?.trustContext,
-    conversation?.assistantId,
   );
 
   // v2 graph retrieval is the deprecated path: `shouldRunV2Retrieval` skips it

package/src/plugins/defaults/memory-retrieval/injectors.ts

@@ -117,13 +117,13 @@ export const DEFAULT_INJECTOR_ORDER = {
 } as const satisfies Record<string, number>;
 
 export const DISK_PRESSURE_WARNING_PROMPT = `<disk_pressure_warning>
-Disk usage is critically low: this assistant is in storage cleanup mode because the workspace volume is critically full.
+Storage is critically low and normal work is suspended until space is freed.
 
-In your first paragraph, warn the user that storage is critically low and that normal work is suspended until space is freed.
+Your first user-visible paragraph must warn the user that storage is critically low and normal work is suspended.
 
-Then help the user clean up storage. Prefer safe inspection steps first, such as checking available space and finding large directories. Ask before deleting files or caches unless the user has already clearly approved the specific cleanup action.
+Before taking cleanup actions, call \`skill_load\` with \`skill: "system-storage-cleanup"\` and follow the cleanup skill.
 
-Do not work on unrelated tasks until enough space is freed to clear the lock or the user explicitly overrides it. Background processes and messages from trusted contacts are blocked while this cleanup mode is active.
+Unrelated work remains blocked until disk usage drops below the critical threshold or the guardian explicitly overrides the lock. Background processes and trusted-contact messages remain blocked while this cleanup mode is active.
 </disk_pressure_warning>`;
 
 /**

package/src/plugins/defaults/memory-v3-shadow/__tests__/pool-select.test.ts

@@ -49,6 +49,7 @@ interface ProviderCall {
   options: SendMessageOptions | undefined;
 }
 const providerCalls: ProviderCall[] = [];
+const warnCalls: Array<{ args: unknown[] }> = [];
 
 mock.module("../../../../providers/provider-send-message.js", () => ({
   getConfiguredProvider: async () => providerStub,
@@ -57,10 +58,12 @@ mock.module("../../../../providers/provider-send-message.js", () => ({
 }));
 
 mock.module("../../../../util/logger.js", () => ({
-  getLogger: () =>
-    new Proxy({} as Record<string, unknown>, {
-      get: (_t, prop) => (prop === "child" ? () => ({}) : () => {}),
+  getLogger: () => ({
+    warn: (...args: unknown[]) => warnCalls.push({ args }),
+    child: () => ({
+      warn: (...args: unknown[]) => warnCalls.push({ args }),
     }),
+  }),
 }));
 
 const { selectPool, MemoryV3RetrievalUnavailableError } =
@@ -97,10 +100,21 @@ function noToolResponse(): ProviderResponse {
     model: "stub-model",
     stopReason: "end_turn",
     usage: { inputTokens: 0, outputTokens: 0 },
+    rawRequest: { model: "MiniMaxAI/MiniMax-M3" },
+    rawResponse: { model: "accounts/fireworks/models/minimax-m3" },
     content: [{ type: "text", text: "no tool call" }],
   };
 }
 
+function wrongToolResponse(): ProviderResponse {
+  return {
+    model: "stub-model",
+    stopReason: "tool_use",
+    usage: { inputTokens: 0, outputTokens: 0 },
+    content: [{ type: "tool_use", id: "tu-1", name: "wrong_tool", input: {} }],
+  };
+}
+
 /** Provider returning a different response per call (the i-th call returns
  * responses[i], or the last entry once exhausted). */
 function makeSequenceProvider(responses: ProviderResponse[]): Provider {
@@ -118,12 +132,12 @@ function makeSequenceProvider(responses: ProviderResponse[]): Provider {
 
 /** Provider that records each call and then throws — the throw-after-retries
  * path (the provider's own RetryProvider has already exhausted its backoff). */
-function makeThrowingProvider(): Provider {
+function makeThrowingProvider(message = "boom"): Provider {
   return {
     name: "throwing",
     sendMessage: async (messages, options) => {
       providerCalls.push({ messages, options });
-      throw new Error("boom");
+      throw new Error(message);
     },
   };
 }
@@ -167,9 +181,19 @@ function sentBlocks(callIndex = 0): RenderedBlock[] {
     .content as unknown as RenderedBlock[];
 }
 
+function warnPayloads(): Array<Record<string, unknown>> {
+  return warnCalls
+    .map((call) => call.args[0])
+    .filter(
+      (payload): payload is Record<string, unknown> =>
+        payload !== null && typeof payload === "object",
+    );
+}
+
 beforeEach(() => {
   providerStub = null;
   providerCalls.length = 0;
+  warnCalls.length = 0;
 });
 
 // ---------------------------------------------------------------------------
@@ -250,6 +274,62 @@ describe("selectPool — infrastructure failures throw", () => {
       MemoryV3RetrievalUnavailableError,
     );
     expect(providerCalls).toHaveLength(3);
+    const payloads = warnPayloads();
+    const attemptPayloads = payloads.filter(
+      (payload) => payload.reason === "missing_tool_use",
+    );
+    expect(attemptPayloads).toHaveLength(3);
+    expect(attemptPayloads[0]).toMatchObject({
+      attempt: 1,
+      reason: "missing_tool_use",
+      providerName: "stub",
+      candidateCount: 4,
+      stableCount: 2,
+      finderCount: 2,
+      response: {
+        model: "stub-model",
+        stopReason: "end_turn",
+        requestModel: "MiniMaxAI/MiniMax-M3",
+        responseModel: "accounts/fireworks/models/minimax-m3",
+        contentBlockTypes: ["text"],
+        toolUseNames: [],
+      },
+    });
+    const aggregatePayload = payloads.find((payload) =>
+      Array.isArray(payload.failures),
+    );
+    expect(aggregatePayload?.providerName).toBe("stub");
+    const failures = aggregatePayload?.failures as
+      | Array<Record<string, unknown>>
+      | undefined;
+    expect(failures?.[0]).toMatchObject({ reason: "missing_tool_use" });
+  });
+
+  test("wrong tool_use name logs the unexpected name before throwing", async () => {
+    providerStub = makeProvider(wrongToolResponse());
+    await expect(selectPool(makePool(), makeTurn("x"))).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
+    expect(providerCalls).toHaveLength(3);
+    expect(
+      warnPayloads().filter(
+        (payload) => payload.reason === "unexpected_tool_name",
+      ),
+    ).toEqual([
+      expect.objectContaining({
+        attempt: 1,
+        reason: "unexpected_tool_name",
+        providerName: "stub",
+        toolName: "wrong_tool",
+        response: expect.objectContaining({
+          stopReason: "tool_use",
+          contentBlockTypes: ["tool_use"],
+          toolUseNames: ["wrong_tool"],
+        }),
+      }),
+      expect.objectContaining({ attempt: 2 }),
+      expect.objectContaining({ attempt: 3 }),
+    ]);
   });
 
   test("schema mismatch → throws after retrying", async () => {
@@ -258,6 +338,17 @@ describe("selectPool — infrastructure failures throw", () => {
       MemoryV3RetrievalUnavailableError,
     );
     expect(providerCalls).toHaveLength(3);
+    expect(
+      warnPayloads().filter((payload) => payload.reason === "schema_mismatch"),
+    ).toEqual([
+      expect.objectContaining({
+        attempt: 1,
+        reason: "schema_mismatch",
+        schemaIssues: [expect.objectContaining({ path: "ids" })],
+      }),
+      expect.objectContaining({ attempt: 2 }),
+      expect.objectContaining({ attempt: 3 }),
+    ]);
   });
 
   test("provider throw → throws after retrying", async () => {
@@ -266,6 +357,44 @@ describe("selectPool — infrastructure failures throw", () => {
       MemoryV3RetrievalUnavailableError,
     );
     expect(providerCalls).toHaveLength(3);
+    expect(
+      warnPayloads().filter((payload) => payload.reason === "provider_error"),
+    ).toEqual([
+      expect.objectContaining({
+        attempt: 1,
+        reason: "provider_error",
+        providerName: "throwing",
+        error: { name: "Error", message: "boom" },
+      }),
+      expect.objectContaining({ attempt: 2 }),
+      expect.objectContaining({ attempt: 3 }),
+    ]);
+  });
+
+  test("provider throw redacts sensitive message details in diagnostics", async () => {
+    const providerSecret = ["sk-proj-", "a".repeat(40)].join("");
+    const message = `provider rejected Authorization: Bearer ${providerSecret}`;
+    providerStub = makeThrowingProvider(message);
+
+    let thrown: unknown;
+    try {
+      await selectPool(makePool(), makeTurn("x"));
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(MemoryV3RetrievalUnavailableError);
+    expect((thrown as Error).message).not.toContain(providerSecret);
+    expect((thrown as Error).message).toContain("[REDACTED]");
+
+    const providerErrors = warnPayloads().filter(
+      (payload) => payload.reason === "provider_error",
+    );
+    const error = providerErrors[0]?.error as
+      | Record<string, unknown>
+      | undefined;
+    expect(error?.message).not.toContain(providerSecret);
+    expect(error?.message).toContain("[REDACTED]");
   });
 
   test("a malformed response that recovers on retry returns its pages", async () => {

package/src/plugins/defaults/memory-v3-shadow/orchestrate.ts

@@ -119,6 +119,10 @@ export interface OrchestrateDeps {
   /** Hard cap on total learned-lane surfaced articles; `0` disables the pass
    *  (canonical value: `memory.v3.learnedEdges.cap`). */
   learnedCap?: number;
+  /** The selector's system prompt. Omitted → the selector's bundled default.
+   *  The live caller resolves `memory.v3.selectorPromptPath` (workspace-relative
+   *  file override) via `resolveSelectorPrompt` and threads the result here. */
+  selectorPrompt?: string;
 }
 
 /** A finder-lane candidate: the slug, the descriptor that justified it, and
@@ -378,8 +382,13 @@ export async function orchestrate(
 
   // Step 3: a SINGLE forced-tool select over the cache-ordered pool. The
   // selections come back slug-deduped (pinned flags ORed) — `selectPool`'s
-  // contract.
-  const selections = await selectPool({ stable, finder: finderTail }, turn);
+  // contract. `selectorPrompt` is the (optionally overridden) instruction
+  // scaffold; `undefined` falls through to the bundled default.
+  const selections = await selectPool(
+    { stable, finder: finderTail },
+    turn,
+    deps.selectorPrompt,
+  );
 
   return {
     selections,