@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240206.7c2bca6

package/src/plugins/defaults/image-fallback/__tests__/image-fallback.test.ts

@@ -0,0 +1,441 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type {
+  ContentBlock,
+  ImageContent,
+  Message,
+  ModelProfileInfo,
+  PostToolUseContext,
+  ToolResultContent,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+
+// Control doesSupportVision from the test: by profile key for the
+// user-prompt-submit path (ModelProfileInfo) and by model id for the
+// post-tool-use path (bare string).
+let visionProfiles: Set<string>;
+let visionModels: Set<string>;
+let mockProfiles: ModelProfileInfo[];
+let sendMessageResponse = {
+  content: [{ type: "text", text: "A red chart showing Q3 revenue." }],
+};
+let providerResolves = true;
+
+const fakeProvider = {
+  name: "mock-vision-provider",
+  async sendMessage() {
+    return sendMessageResponse;
+  },
+};
+
+// Mock @vellumai/plugin-api — only the runtime handles the plugin imports.
+// `extractAllText` stays real (imported from the relative path, not plugin-api).
+mock.module("@vellumai/plugin-api", () => ({
+  doesSupportVision: (arg: ModelProfileInfo | string) =>
+    typeof arg === "string"
+      ? visionModels.has(arg)
+      : visionProfiles.has(arg.key),
+  getModelProfiles: () => mockProfiles,
+  getConfiguredProvider: async () => (providerResolves ? fakeProvider : null),
+}));
+
+// Mock the image-persist module to avoid filesystem side effects in tests.
+let mockPersistPath: string | null =
+  "/workspace/data/attachments/mock-hash.png";
+mock.module("../src/image-persist.js", () => ({
+  persistImage: () => mockPersistPath,
+}));
+
+// ─── Imports (after mocks are registered) ───────────────────────────────────
+
+const userPromptSubmit = (await import("../hooks/user-prompt-submit.js"))
+  .default;
+const postToolUse = (await import("../hooks/post-tool-use.js")).default;
+const { findVisionProfile } = await import("../src/vision-caption.js");
+const { resetCaptionCacheForTests } = await import("../src/caption-cache.js");
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+const logger = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  warnOnce() {},
+};
+
+function profile(
+  key: string,
+  overrides: Partial<ModelProfileInfo> = {},
+): ModelProfileInfo {
+  return {
+    key,
+    label: key,
+    description: null,
+    isActive: false,
+    isDisabled: false,
+    isMix: false,
+    ...overrides,
+  };
+}
+
+function imageBlock(data = "base64data"): ImageContent {
+  return {
+    type: "image",
+    source: { type: "base64", media_type: "image/png", data },
+  };
+}
+
+function imageMsg(data = "base64data"): Message {
+  return { role: "user", content: [imageBlock(data)] };
+}
+
+function textMsg(text: string): Message {
+  return { role: "user", content: [{ type: "text", text }] };
+}
+
+function makeCtx(
+  overrides: Partial<UserPromptSubmitContext> = {},
+): UserPromptSubmitContext {
+  return {
+    conversationId: "c1",
+    userMessageId: "m1",
+    requestId: "r1",
+    modelProfileKey: "text-only",
+    isNonInteractive: false,
+    prompt: "What is in this image?",
+    originalMessages: [],
+    latestMessages: [],
+    logger,
+    ...overrides,
+  } as unknown as UserPromptSubmitContext;
+}
+
+function toolResult(contentBlocks?: ContentBlock[]): ToolResultContent {
+  return {
+    type: "tool_result",
+    tool_use_id: "tu1",
+    content: "Took a screenshot.",
+    ...(contentBlocks ? { contentBlocks } : {}),
+  };
+}
+
+function makeToolCtx(
+  overrides: Partial<PostToolUseContext> = {},
+): PostToolUseContext {
+  return {
+    conversationId: "c1",
+    toolResponse: toolResult(),
+    messages: [],
+    additionalContext: null,
+    model: "text-only-model",
+    maxInputTokens: 100_000,
+    logger,
+    ...overrides,
+  } as unknown as PostToolUseContext;
+}
+
+// ─── Setup ──────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  visionProfiles = new Set<string>(["vision-profile"]);
+  // "text-only-model" (the default post-tool-use ctx.model) is absent, so it
+  // reads as text-only; a vision model id is added per-test.
+  visionModels = new Set<string>();
+  mockProfiles = [
+    profile("text-only", { label: "Text Only", isActive: true }),
+    profile("vision-profile", { label: "Vision" }),
+  ];
+  sendMessageResponse = {
+    content: [{ type: "text", text: "A red chart showing Q3 revenue." }],
+  };
+  providerResolves = true;
+  mockPersistPath = "/workspace/data/attachments/mock-hash.png";
+  resetCaptionCacheForTests();
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("image-fallback user-prompt-submit hook", () => {
+  test("is a no-op when the active model supports vision", async () => {
+    visionProfiles = new Set(["text-only"]); // active profile supports vision
+    const messages = [imageMsg()];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("image");
+  });
+
+  test("does not gate on isNonInteractive — captions even for background runs", async () => {
+    const messages = [imageMsg()];
+    const ctx = makeCtx({ latestMessages: messages, isNonInteractive: true });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+    expect(
+      (ctx.latestMessages[0].content[0] as { text: string }).text,
+    ).toContain("[Image auto-described");
+  });
+
+  test("replaces image blocks with captions when active model is text-only", async () => {
+    const messages = [imageMsg("img1")];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+    expect((ctx.latestMessages[0].content[0] as { text: string }).text).toBe(
+      "[Image auto-described for text-only model: A red chart showing Q3 revenue.]",
+    );
+  });
+
+  test("caption states the model can't view images and the text is derived", async () => {
+    const messages = [imageMsg("img1")];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    const text = (ctx.latestMessages[0].content[0] as { text: string }).text;
+    expect(text).toContain("text-only model");
+    expect(text).toContain("auto-described");
+  });
+
+  test("does not embed the saved image path in the caption text", async () => {
+    const messages = [imageMsg("img1")];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    const text = (ctx.latestMessages[0].content[0] as { text: string }).text;
+    expect(text).not.toContain("saved to");
+    expect(text).not.toContain("/workspace/data/attachments/");
+  });
+
+  test("preserves non-image blocks and captions only images", async () => {
+    const messages: Message[] = [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "Look at this:" },
+          imageBlock("img1"),
+          { type: "text", text: "What do you see?" },
+        ],
+      },
+    ];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect((ctx.latestMessages[0].content[0] as { text: string }).text).toBe(
+      "Look at this:",
+    );
+    expect(ctx.latestMessages[0].content[1].type).toBe("text");
+    expect(
+      (ctx.latestMessages[0].content[1] as { text: string }).text,
+    ).toContain("[Image auto-described");
+    expect((ctx.latestMessages[0].content[2] as { text: string }).text).toBe(
+      "What do you see?",
+    );
+  });
+
+  test("uses fail-open placeholder when no vision profile is configured", async () => {
+    visionProfiles = new Set<string>(); // no vision profiles
+    const messages = [imageMsg()];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+    expect(
+      (ctx.latestMessages[0].content[0] as { text: string }).text,
+    ).toContain("no vision-capable model");
+  });
+
+  test("uses fail-open placeholder when provider resolution returns null", async () => {
+    providerResolves = false;
+    const messages = [imageMsg()];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+    expect(
+      (ctx.latestMessages[0].content[0] as { text: string }).text,
+    ).toContain("auto-description failed");
+  });
+
+  test("caches captions — second call with same image does not invoke provider", async () => {
+    let callCount = 0;
+    const trackingProvider = {
+      name: "mock-vision-provider",
+      async sendMessage() {
+        callCount++;
+        return sendMessageResponse;
+      },
+    };
+    // Override the mock to track calls.
+    mock.module("@vellumai/plugin-api", () => ({
+      doesSupportVision: (arg: ModelProfileInfo | string) =>
+        typeof arg === "string"
+          ? visionModels.has(arg)
+          : visionProfiles.has(arg.key),
+      getModelProfiles: () => mockProfiles,
+      getConfiguredProvider: async () => trackingProvider,
+    }));
+
+    const messages1 = [imageMsg("same-data")];
+    const ctx1 = makeCtx({ latestMessages: messages1 });
+    await userPromptSubmit(ctx1);
+    expect(callCount).toBe(1);
+
+    // Second turn with the same image — should hit cache, no new provider call.
+    const messages2 = [imageMsg("same-data")];
+    const ctx2 = makeCtx({ latestMessages: messages2 });
+    await userPromptSubmit(ctx2);
+    expect(callCount).toBe(1); // still 1 — cache hit
+
+    // Restore the original mock for other tests.
+    mock.module("@vellumai/plugin-api", () => ({
+      doesSupportVision: (arg: ModelProfileInfo | string) =>
+        typeof arg === "string"
+          ? visionModels.has(arg)
+          : visionProfiles.has(arg.key),
+      getModelProfiles: () => mockProfiles,
+      getConfiguredProvider: async () =>
+        providerResolves ? fakeProvider : null,
+    }));
+  });
+
+  test("handles multiple images across multiple messages", async () => {
+    const messages: Message[] = [
+      imageMsg("img-a"),
+      textMsg("and another:"),
+      {
+        role: "user",
+        content: [imageBlock("img-b"), { type: "text", text: "both?" }],
+      },
+    ];
+    const ctx = makeCtx({ latestMessages: messages });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+    expect(
+      (ctx.latestMessages[0].content[0] as { text: string }).text,
+    ).toContain("[Image auto-described");
+    expect(ctx.latestMessages[2].content[0].type).toBe("text");
+    expect(
+      (ctx.latestMessages[2].content[0] as { text: string }).text,
+    ).toContain("[Image auto-described");
+    expect((ctx.latestMessages[2].content[1] as { text: string }).text).toBe(
+      "both?",
+    );
+  });
+
+  test("resolves active profile via isActive when modelProfileKey is null", async () => {
+    const messages = [imageMsg()];
+    const ctx = makeCtx({ latestMessages: messages, modelProfileKey: null });
+    await userPromptSubmit(ctx);
+    // The active profile is "text-only" (isActive: true), which doesn't support
+    // vision, so images should be captioned.
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+  });
+});
+
+describe("findVisionProfile", () => {
+  test("returns the first enabled vision-capable profile", () => {
+    expect(findVisionProfile()).toBe("vision-profile");
+  });
+
+  test("skips disabled vision profiles", () => {
+    mockProfiles = [
+      profile("text-only", { label: "Text", isActive: true }),
+      profile("vision-profile", { label: "Vision", isDisabled: true }),
+    ];
+    expect(findVisionProfile()).toBeNull();
+  });
+
+  test("returns null when no profiles support vision", () => {
+    visionProfiles = new Set<string>();
+    expect(findVisionProfile()).toBeNull();
+  });
+});
+
+describe("image-fallback post-tool-use hook", () => {
+  test("captions image blocks nested in a tool result for a text-only model", async () => {
+    const ctx = makeToolCtx({
+      toolResponse: toolResult([imageBlock("shot1")]),
+    });
+    await postToolUse(ctx);
+    const block = ctx.toolResponse.contentBlocks![0];
+    expect(block.type).toBe("text");
+    expect((block as { text: string }).text).toBe(
+      "[Image auto-described for text-only model: A red chart showing Q3 revenue.]",
+    );
+  });
+
+  test("is a no-op when the model that ran supports vision", async () => {
+    visionModels = new Set(["vision-model"]);
+    const ctx = makeToolCtx({
+      model: "vision-model",
+      toolResponse: toolResult([imageBlock("shot1")]),
+    });
+    await postToolUse(ctx);
+    expect(ctx.toolResponse.contentBlocks![0].type).toBe("image");
+  });
+
+  test("is a no-op when the tool result has no contentBlocks", async () => {
+    const ctx = makeToolCtx({ toolResponse: toolResult() });
+    await postToolUse(ctx);
+    expect(ctx.toolResponse.contentBlocks).toBeUndefined();
+  });
+
+  test("preserves non-image contentBlocks and captions only images", async () => {
+    const ctx = makeToolCtx({
+      toolResponse: toolResult([
+        { type: "text", text: "page title" },
+        imageBlock("shot1"),
+      ]),
+    });
+    await postToolUse(ctx);
+    const blocks = ctx.toolResponse.contentBlocks!;
+    expect((blocks[0] as { text: string }).text).toBe("page title");
+    expect(blocks[1].type).toBe("text");
+    expect((blocks[1] as { text: string }).text).toContain(
+      "[Image auto-described",
+    );
+  });
+
+  test("uses fail-open placeholder when no vision profile is configured", async () => {
+    visionProfiles = new Set<string>(); // no vision profiles
+    const ctx = makeToolCtx({
+      toolResponse: toolResult([imageBlock("shot1")]),
+    });
+    await postToolUse(ctx);
+    const block = ctx.toolResponse.contentBlocks![0];
+    expect(block.type).toBe("text");
+    expect((block as { text: string }).text).toContain(
+      "no vision-capable model",
+    );
+  });
+
+  test("does not embed the saved image path in the caption text", async () => {
+    const ctx = makeToolCtx({
+      toolResponse: toolResult([imageBlock("shot1")]),
+    });
+    await postToolUse(ctx);
+    const text = (ctx.toolResponse.contentBlocks![0] as { text: string }).text;
+    expect(text).not.toContain("saved to");
+  });
+
+  test("is a no-op when contentBlocks carry no image", async () => {
+    const textBlock = { type: "text" as const, text: "just text" };
+    const ctx = makeToolCtx({ toolResponse: toolResult([textBlock]) });
+    await postToolUse(ctx);
+    expect(ctx.toolResponse.contentBlocks![0]).toEqual(textBlock);
+  });
+
+  test("gates on ctx.model, not the workspace active profile", async () => {
+    // The active profile is vision-capable, but the model that actually ran
+    // (ctx.model) is text-only — the model that ran must win, so the image is
+    // captioned.
+    mockProfiles = [
+      profile("vision-active", { isActive: true }),
+      profile("vision-profile", {}),
+    ];
+    visionProfiles = new Set(["vision-active", "vision-profile"]);
+    visionModels = new Set<string>(); // "text-only-model" is text-only
+    const ctx = makeToolCtx({
+      model: "text-only-model",
+      toolResponse: toolResult([imageBlock("shot1")]),
+    });
+    await postToolUse(ctx);
+    expect(ctx.toolResponse.contentBlocks![0].type).toBe("text");
+  });
+});

package/src/plugins/defaults/image-fallback/hooks/post-tool-use.ts

@@ -0,0 +1,57 @@
+/**
+ * Default `post-tool-use` hook: when the turn's model is text-only, captions
+ * the image blocks a tool returns (e.g. a `browser_screenshot`) and
+ * substitutes the caption as a text block so the result stays sendable to a
+ * provider that would otherwise reject the raw image.
+ *
+ * Tool images arrive nested in `toolResponse.contentBlocks` (the rich-content
+ * companion to the tool result's text `content`), so the hook scans there
+ * rather than the top-level message content the `user-prompt-submit` hook
+ * handles. Both share {@link captionImageBlocks}.
+ *
+ * Capability is read straight off `ctx.model` — the provider-reported model id
+ * for the turn that issued this tool call — so the decision tracks the model
+ * that actually ran, including a text-only override. The substitution is in
+ * place, so the persisted/displayed tool result carries the caption too.
+ */
+
+import {
+  doesSupportVision,
+  type PluginHookFn,
+  type PostToolUseContext,
+} from "@vellumai/plugin-api";
+
+import { captionImageBlocks } from "../src/caption-blocks.js";
+import { findVisionProfile } from "../src/vision-caption.js";
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  // Cheapest gate first: bail unless the tool actually returned an image,
+  // before touching the model catalog or resolving a vision profile.
+  const blocks = ctx.toolResponse.contentBlocks;
+  if (blocks == null || !blocks.some((b) => b.type === "image")) return;
+
+  // If the model that ran already supports vision, leave the image in place.
+  if (doesSupportVision(ctx.model)) return;
+
+  // Find a vision-capable profile for captioning.
+  const visionProfileKey = findVisionProfile();
+
+  const imageCount = await captionImageBlocks(
+    blocks,
+    visionProfileKey,
+    ctx.logger,
+  );
+
+  if (imageCount > 0) {
+    ctx.logger.info(
+      {
+        plugin: "image-fallback",
+        toolUseId: ctx.toolResponse.tool_use_id,
+        imageCount,
+      },
+      "Replaced tool-result image blocks with text captions for text-only model",
+    );
+  }
+};
+
+export default postToolUse;

package/src/plugins/defaults/image-fallback/hooks/user-prompt-submit.ts

@@ -0,0 +1,61 @@
+/**
+ * Default `user-prompt-submit` hook: when the turn's model is text-only,
+ * captions image blocks via a vision-capable profile and substitutes the
+ * caption as a text block so the model can still reason about the image's
+ * content.
+ *
+ * The hook runs once per user turn, after the assistant assembles
+ * `latestMessages` and before they flow into `agentLoop.run()`. It:
+ *
+ * 1. Checks whether the turn's model needs image→text fallback via
+ *    {@link needsImageFallback} (resolving the turn's `modelProfileKey`, or the
+ *    workspace's active profile when the key is `null`). If the model handles
+ *    images, the hook is a no-op.
+ * 2. Finds a vision-capable profile for captioning via `findVisionProfile`.
+ *    If none exists, images are replaced with a fail-open placeholder so the
+ *    model at least knows an image was present.
+ * 3. Replaces each image block with a `[Image …]` text caption via
+ *    {@link captionImageBlocks} (which also persists the original and caches
+ *    captions across turns).
+ *
+ * The companion `post-tool-use` hook applies the same substitution to images a
+ * tool returns (e.g. a browser screenshot).
+ */
+
+import {
+  type PluginHookFn,
+  type UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import {
+  captionImageBlocks,
+  needsImageFallback,
+} from "../src/caption-blocks.js";
+import { findVisionProfile } from "../src/vision-caption.js";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+  // If the turn's model already supports vision, nothing to do.
+  if (!needsImageFallback(ctx.modelProfileKey)) return;
+
+  // Find a vision-capable profile for captioning.
+  const visionProfileKey = findVisionProfile();
+
+  // Scan all messages for image blocks and replace them with captions.
+  let imageCount = 0;
+  for (const message of ctx.latestMessages) {
+    imageCount += await captionImageBlocks(
+      message.content,
+      visionProfileKey,
+      ctx.logger,
+    );
+  }
+
+  if (imageCount > 0) {
+    ctx.logger.info(
+      { plugin: "image-fallback", imageCount },
+      "Replaced image blocks with text captions for text-only model",
+    );
+  }
+};
+
+export default userPromptSubmit;

package/src/plugins/defaults/image-fallback/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-image-fallback",
+  "version": "1.0.0",
+  "description": "First-party default plugin that captions image attachments via a vision-capable profile when the active model is text-only, substituting the caption as a text block so the model can still reason about the image's content.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

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;
+}