@vellumai/assistant 0.10.3 → 0.10.4-dev.202607010028.1a4efcc

package/src/plugin-api/types.ts

@@ -75,13 +75,23 @@ export type HookFunction<TCtx = unknown> = (
  * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
  * config, a pino-compatible logger scoped to the plugin, a per-plugin
  * writable data directory, and the assistant's version metadata.
+ *
+ * For user-installed plugins, config is read from `<pluginDir>/config.json`
+ * and `pluginStorageDir` points at `<pluginDir>/data/`. For first-party
+ * default plugins and standalone workspace hooks, config comes from the
+ * global `config.plugins.<name>` block and `pluginStorageDir` points at
+ * `<workspaceDir>/plugins-data/<name>/`.
  */
 export interface InitContext {
   /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
   config: unknown;
   /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
   logger: PluginLogger;
-  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+  /**
+   * Absolute path to the per-plugin writable data directory. For user plugins
+   * this is `<pluginDir>/data/`; for defaults and workspace hooks it falls back
+   * to `<workspaceDir>/plugins-data/<plugin>/`. Created by bootstrap.
+   */
   pluginStorageDir: string;
   /**
    * Assistant semver. Plugins can compare against this for defensive
@@ -124,20 +134,32 @@ export interface ModelProfileInfo {
 // ─── Shutdown context ────────────────────────────────────────────────────────
 
 /**
- * Context passed to the `shutdown` hook during daemon teardown. Kept
- * intentionally narrower than {@link InitContext} — most teardown
- * paths only need to know which assistant version they're shutting
- * down against (e.g. for version-conditional cleanup of state files
- * written by a previous boot).
+ * Why a plugin's `shutdown` hook is firing.
+ *
+ * - `shutdown` — the daemon is tearing down (process exit).
+ * - `uninstall` — the plugin's directory was removed at runtime.
+ * - `disable` — the plugin was disabled at runtime (e.g. a `.disabled`
+ *   sentinel was added, or a feature flag turned it off).
+ */
+export type ShutdownReason = "shutdown" | "uninstall" | "disable";
+
+/**
+ * Context passed to the `shutdown` hook. Kept intentionally narrower than
+ * {@link InitContext} — teardown paths only need to know which assistant
+ * version they're shutting down against (e.g. for version-conditional cleanup
+ * of state files written by a previous boot) and {@link ShutdownReason why}
+ * they're being torn down (so a plugin can, e.g., delete its state on
+ * `uninstall` but preserve it across a plain `shutdown`).
  *
- * Additional fields may be added as concrete plugin needs surface; the
- * `assistantVersion` field mirrors the init context's so plugins that
- * stash a version stamp at init can compare against the same name on
- * tear-down without keeping their own copy.
+ * The `assistantVersion` field mirrors the init context's so plugins that stash
+ * a version stamp at init can compare against the same name on tear-down
+ * without keeping their own copy.
  */
 export interface ShutdownContext {
   /** Assistant semver for compatibility checks inside the plugin. */
   assistantVersion: string;
+  /** Why the plugin is shutting down. */
+  reason: ShutdownReason;
 }
 
 // ─── User-prompt-submit hook context ─────────────────────────────────────────
@@ -182,14 +204,13 @@ export interface UserPromptSubmitContext {
    */
   readonly requestId: string;
   /**
-   * Active inference profile key to surface in this turn's context, or `null`
-   * when the profile is unchanged since the one last announced to the model.
-   * Hooks that emit the `model_profile` grounding line resolve the
-   * human-readable label (and model id) from this key via the workspace LLM
-   * config rather than receiving the rendered string — the key is the minimal
-   * turn input the message arrays cannot carry.
+   * Effective inference profile identity for the model this turn will use.
+   * Named-profile configs receive a profile key; profileless configs receive
+   * the resolved model id. Hooks that need model capabilities should resolve
+   * them from this value rather than the workspace active profile, because a
+   * conversation can be pinned to a different profile.
    */
-  readonly modelProfileKey: string | null;
+  readonly modelProfileKey: string;
   /**
    * Whether the turn has no human present to answer clarification questions
    * (e.g. a scheduled, background, or headless run). Resolved once at turn
@@ -275,13 +296,10 @@ export interface PostCompactContext {
    */
   readonly isNonInteractive: boolean;
   /**
-   * Active inference profile key to surface in the re-injected context, or
-   * `null` when the profile is unchanged since the one last announced to the
-   * model. Mirrors {@link UserPromptSubmitContext.modelProfileKey}: hooks that
-   * emit the `model_profile` grounding line resolve the human-readable label
-   * from this key rather than receiving the rendered string.
+   * Effective inference profile identity for the model the compacted turn will
+   * keep using. Mirrors {@link UserPromptSubmitContext.modelProfileKey}.
    */
-  readonly modelProfileKey: string | null;
+  readonly modelProfileKey: string;
   /**
    * Volume of runtime injection to re-apply. `"full"` restores the complete
    * runtime context; `"minimal"` is the reduced volume overflow recovery's
@@ -345,9 +363,28 @@ export interface PostToolUseContext {
    * Model id reported by the provider for the assistant turn that issued
    * this tool call (e.g. `claude-opus-4-8`,
    * `accounts/fireworks/models/kimi-k2p6`). Hooks use it to vary coaching by
-   * model family — some models need earlier or firmer steering than others.
+   * model family — each plugin owns its own model policy (e.g. which families
+   * need firmer steering) and matches against this string directly.
    */
   readonly model: string;
+  /**
+   * The LLM call site driving this turn — `mainAgent` for a live user-facing
+   * turn, `subagentSpawn` for a subagent, or a background site (e.g.
+   * `heartbeatAgent`, `titleGenerate`). `null` when the run tagged none. A hook
+   * that should only act on a live user-facing turn gates on
+   * `callSite === "mainAgent"`; one that should skip subagents checks
+   * `callSite === "subagentSpawn"`.
+   */
+  readonly callSite: LLMCallSite | null;
+  /**
+   * Whether the connected client can render dynamic UI surfaces this turn —
+   * `true` unless the channel explicitly lacks the capability (SMS, phone,
+   * email, and most chat bridges). A fact about what the model can *do* this
+   * turn, not who is calling: a hook that prompts a surface tool (e.g. the
+   * `ui_show` progress card) gates on this so it does not coach the model
+   * toward a tool the channel filters out of the tool set.
+   */
+  readonly supportsDynamicUi: boolean;
   /**
    * The model's context-window size in tokens. Plugins derive their own
    * character budget from this (e.g. a share of the window) rather than

package/src/plugins/defaults/channel/injectors.ts

@@ -0,0 +1,101 @@
+/**
+ * `channel` plugin injectors.
+ *
+ * Contributes the Slack channel per-turn injections: the chronological
+ * transcript that replaces the conversation's run messages, and the
+ * `<active_thread>` focus block for non-DM threads. Both read their inputs off
+ * the {@link TurnContext}; see {@link DEFAULT_INJECTOR_ORDER} for the global
+ * ordering contract.
+ */
+
+import {
+  type InjectionBlock,
+  type Injector,
+  type TurnContext,
+} from "../../types.js";
+import { DEFAULT_INJECTOR_ORDER } from "../injector-order.js";
+
+/**
+ * `slack-messages` injector — order 60, replace-run-messages.
+ *
+ * Swaps the conversation's `runMessages` array with a pre-rendered
+ * chronological Slack transcript built from the persisted message rows.
+ * Applied to every Slack conversation (channels and DMs alike). The
+ * orchestrator builds the transcript via `loadSlackChronologicalContext`
+ * before the chain runs.
+ *
+ * Memory-block prepending is preserved across the replacement:
+ * `extractMemoryPrefixBlocks` is re-applied to the Slack transcript's tail
+ * user message inside `applyRuntimeInjections` when the replacement fires.
+ *
+ * Active in both `full` and `minimal` mode — Slack transcript replacement
+ * is not a high-token optional block, it's the canonical view of Slack
+ * history for the model.
+ *
+ * Gating:
+ *  - `channelCapabilities.channel === "slack"`.
+ *  - `slackChronologicalMessages` has at least one entry.
+ */
+const slackMessagesInjector: Injector = {
+  name: "slack-messages",
+  order: DEFAULT_INJECTOR_ORDER.slackMessages,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    if (ctx.channelCapabilities?.channel !== "slack") return null;
+    const messages = ctx.slackChronologicalMessages;
+    if (!messages || messages.length === 0) return null;
+    return {
+      id: "slack-messages",
+      // `text` is informational only — `replace-run-messages` placements
+      // bypass the tail-user-message splice path. Kept non-empty so
+      // `composeInjectorChain` (text-only consumers) still counts this
+      // injector as contributing content.
+      text: "[slack-chronological-transcript]",
+      placement: "replace-run-messages",
+      messagesOverride: messages,
+    };
+  },
+};
+
+/**
+ * `thread-focus` injector — order 70, append-user-tail.
+ *
+ * Appends a non-persisted `<active_thread>` block listing the parent +
+ * replies of the thread the current inbound user message belongs to, so
+ * the model can orient even when the channel-wide chronological transcript
+ * is long and interleaved.
+ *
+ * The orchestrator builds the block via `loadSlackActiveThreadFocusBlock`
+ * (which short-circuits for DMs). This injector wraps the value so the
+ * block is applied declaratively through the chain.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `channelCapabilities.channel === "slack"` and `chatType === "channel"`
+ *    (non-DM Slack conversation).
+ *  - `slackActiveThreadFocusBlock` is a non-empty string.
+ */
+const threadFocusInjector: Injector = {
+  name: "thread-focus",
+  order: DEFAULT_INJECTOR_ORDER.threadFocus,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const mode = ctx.mode ?? "full";
+    if (mode !== "full") return null;
+    const caps = ctx.channelCapabilities;
+    if (!caps || caps.channel !== "slack" || caps.chatType !== "channel") {
+      return null;
+    }
+    const block = ctx.slackActiveThreadFocusBlock;
+    if (typeof block !== "string" || block.length === 0) return null;
+    return {
+      id: "thread-focus",
+      text: block,
+      placement: "append-user-tail",
+    };
+  },
+};
+
+/** The `channel` plugin's runtime injectors, in ascending `order`. */
+export const channelInjectors: Injector[] = [
+  slackMessagesInjector,
+  threadFocusInjector,
+];

package/src/plugins/defaults/channel/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-channel",
+  "version": "1.0.0",
+  "description": "First-party default plugin contributing the Slack channel runtime injectors (chronological transcript and active-thread focus).",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/compaction/compact.ts

@@ -10,7 +10,8 @@
  * This module is side-effect free: importing it does not register any plugin.
  */
 
-import type { Message } from "../../../providers/types.js";
+import type { Message } from "@vellumai/plugin-api";
+
 import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
 import { PluginExecutionError } from "../../types.js";
 import { getContextWindowManager } from "./manager-store.js";

package/src/plugins/defaults/compaction/context-overflow-reducer.ts

@@ -25,6 +25,8 @@
  * `state.exhausted` is true.
  */
 
+import type { Message } from "@vellumai/plugin-api";
+
 import type { ContextWindowConfig } from "../../../config/types.js";
 import {
   estimateContentBlockTokens,
@@ -37,7 +39,6 @@ import {
   stripMediaPayloadsForRetry,
 } from "../../../daemon/conversation-media-retry.js";
 import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
-import type { Message } from "../../../providers/types.js";
 import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
 import { getLogger } from "../../../util/logger.js";
 import { defaultCompact, defaultEmergencyCompact } from "./compact.js";

package/src/plugins/defaults/compaction/window-manager.ts

@@ -14,9 +14,15 @@
  * marker is wrapped around the assistant-role memory message we emit on
  * successful compaction so those code paths keep working unchanged.
  */
+import type {
+  ContentBlock,
+  LLMCallSite,
+  Message,
+  Provider,
+} from "@vellumai/plugin-api";
+
 import { getConfig } from "../../../config/loader.js";
 import type { CompactionConfig } from "../../../config/schemas/compaction.js";
-import type { LLMCallSite } from "../../../config/schemas/llm.js";
 import type { ContextWindowConfig } from "../../../config/types.js";
 import {
   type CompactionRunArgs,
@@ -30,12 +36,7 @@ import {
 } from "../../../context/token-estimator.js";
 import { findConversationOrSubagent } from "../../../daemon/conversation-registry.js";
 import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
-import type {
-  ContentBlock,
-  Message,
-  Provider,
-  ToolDefinition,
-} from "../../../providers/types.js";
+import type { ToolDefinition } from "../../../providers/types.js";
 import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
 import { getLogger } from "../../../util/logger.js";
 import {

package/src/plugins/defaults/documents/injectors.ts

@@ -0,0 +1,125 @@
+/**
+ * `documents` plugin injectors.
+ *
+ * Contributes the open-document per-turn injections: the `<active_documents>`
+ * list (so the assistant edits existing documents instead of duplicating them)
+ * and `<document_comments>` (open comments to address). Both read the open
+ * documents off the {@link TurnContext}; see {@link DEFAULT_INJECTOR_ORDER} for
+ * the global ordering contract.
+ */
+
+import { listComments } from "../../../documents/document-comments-store.js";
+import {
+  type InjectionBlock,
+  type Injector,
+  type TurnContext,
+} from "../../types.js";
+import { DEFAULT_INJECTOR_ORDER } from "../injector-order.js";
+
+/**
+ * `active-documents` injector — order 45, prepend-user-tail.
+ *
+ * Injects an `<active_documents>` block listing open documents in the
+ * conversation so the assistant can target them with `document_update`
+ * instead of creating duplicates via `document_create`.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `activeDocuments` has at least one entry.
+ */
+const activeDocumentsInjector: Injector = {
+  name: "active-documents",
+  order: DEFAULT_INJECTOR_ORDER.activeDocuments,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const mode = ctx.mode ?? "full";
+    if (mode !== "full") return null;
+    const docs = ctx.activeDocuments;
+    if (!docs || docs.length === 0) return null;
+    const lines = docs.map(
+      (d) =>
+        `- surface_id: "${d.surfaceId}", title: "${d.title}", words: ${d.wordCount}`,
+    );
+    const text = `<active_documents>\nThe following documents are open in this conversation. Use document_update with the surface_id to edit them — do NOT call document_create for documents that already exist.\n${lines.join("\n")}\n</active_documents>`;
+    return {
+      id: "active-documents",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
+/** Maximum open comments surfaced per document to limit context bloat. */
+const DOCUMENT_COMMENTS_CAP = 10;
+
+/**
+ * Escape closing `</document_comments>` inside user-controlled strings so
+ * they cannot break out of the XML wrapper — same pattern as the
+ * `<knowledge_base>` and `<info>` memory blocks.
+ */
+function escapeDocCommentTag(s: string): string {
+  return s.replace(/<\/document_comments\s*>/gi, "&lt;/document_comments&gt;");
+}
+
+/**
+ * `document-comments` injector — order 46, prepend-user-tail.
+ *
+ * Surfaces open top-level comments on active documents so the assistant
+ * knows what feedback to address. For each active document, queries the
+ * comment store for open top-level comments (capped at
+ * {@link DOCUMENT_COMMENTS_CAP} most recent per document). Inline comments
+ * include the quoted anchor text; doc-level comments are labelled as such.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `activeDocuments` has at least one entry.
+ *  - At least one document has open comments (returns null otherwise).
+ */
+const documentCommentsInjector: Injector = {
+  name: "document-comments",
+  order: DEFAULT_INJECTOR_ORDER.documentComments,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const mode = ctx.mode ?? "full";
+    if (mode !== "full") return null;
+    const docs = ctx.activeDocuments;
+    if (!docs || docs.length === 0) return null;
+
+    const sections: string[] = [];
+    for (const doc of docs) {
+      const comments = listComments(doc.surfaceId, {
+        status: "open",
+        topLevelOnly: true,
+      }).slice(-DOCUMENT_COMMENTS_CAP);
+      if (comments.length === 0) continue;
+
+      const lines = comments.map((c) => {
+        const anchor =
+          c.anchorText != null ? escapeDocCommentTag(c.anchorText) : null;
+        const label =
+          anchor != null ? `inline, anchored to "${anchor}"` : "doc-level";
+        return `- Comment #${c.id} (${label}): "${escapeDocCommentTag(c.content)}"`;
+      });
+      sections.push(
+        `Document: "${escapeDocCommentTag(doc.title)}" (surface_id: "${doc.surfaceId}")\n${lines.join("\n")}`,
+      );
+    }
+
+    if (sections.length === 0) return null;
+
+    const text = `<document_comments>
+Open comments on your documents. Address these by editing the document, then use comment_resolve to mark each resolved.
+
+${sections.join("\n\n")}
+</document_comments>`;
+    return {
+      id: "document-comments",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
+/** The `documents` plugin's runtime injectors, in ascending `order`. */
+export const documentsInjectors: Injector[] = [
+  activeDocumentsInjector,
+  documentCommentsInjector,
+];

package/src/plugins/defaults/documents/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-documents",
+  "version": "1.0.0",
+  "description": "First-party default plugin contributing the open-document runtime injectors (active documents and their open comments).",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/empty-response/hooks/post-model-call.ts

@@ -46,9 +46,13 @@
  * ignores the decision — so the hook returns early for both.
  */
 
-import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
+import type {
+  ContentBlock,
+  HookFunction,
+  Message,
+  PostModelCallContext,
+} from "@vellumai/plugin-api";
 
-import type { ContentBlock, Message } from "../../../../providers/types.js";
 import {
   isEmptyResponseNudged,
   markEmptyResponseNudged,

package/src/plugins/defaults/exploration-drift/hooks/post-tool-use.ts

@@ -50,14 +50,15 @@
  *
  * Subagent conversations are exempt: an investigator is *supposed* to dig at
  * length, and subagents cannot nest (`SUBAGENT_LIMITS.maxDepth`), so the
- * delegation advice would be wrong there. The check is a lazy import on the
- * rare nudge path so the subagent manager's module graph stays out of the
- * per-tool-result hot path.
+ * delegation advice would be wrong there. Subagents run under the
+ * `subagentSpawn` call site, so the exemption is a cheap `ctx.callSite` read.
  */
 
-import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
-
-import type { Message } from "../../../../providers/types.js";
+import type {
+  HookFunction,
+  Message,
+  PostToolUseContext,
+} from "@vellumai/plugin-api";
 
 /**
  * Canonical long-dig notice. Module-level constant so tests and wrapping
@@ -273,11 +274,9 @@ const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
 
   if (!longDigNudge && !loopNudge) return;
 
-  // Subagent conversations are exempt — see module doc.
-  const { getSubagentManager } = await import("../../../../subagent/index.js");
-  if (getSubagentManager().getParentInfo(ctx.conversationId) !== undefined) {
-    return;
-  }
+  // Subagent conversations are exempt — see module doc. Subagents run under
+  // the `subagentSpawn` call site.
+  if (ctx.callSite === "subagentSpawn") return;
 
   lastNudgedStreakByConversation.set(ctx.conversationId, streak);
   const nudgeText = loopNudge

package/src/plugins/defaults/history-repair/terminal.ts

@@ -18,7 +18,7 @@ import type {
   ServerToolUseContent,
   ToolResultContent,
   ToolUseContent,
-} from "../../../providers/types.js";
+} from "@vellumai/plugin-api";
 
 interface RepairStats {
   assistantToolResultsMigrated: number;

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

@@ -167,6 +167,29 @@ describe("image-fallback user-prompt-submit hook", () => {
     expect(ctx.latestMessages[0].content[0].type).toBe("image");
   });
 
+  test("uses the model id fallback when no named profile exists", async () => {
+    mockProfiles = [];
+    const messages = [imageMsg()];
+    const ctx = makeCtx({
+      latestMessages: messages,
+      modelProfileKey: "text-only-model",
+    });
+    await userPromptSubmit(ctx);
+    expect(ctx.latestMessages[0].content[0].type).toBe("text");
+  });
+
+  test("leaves images alone when the profileless model id supports vision", async () => {
+    mockProfiles = [];
+    visionModels = new Set(["vision-model"]);
+    const messages = [imageMsg()];
+    const ctx = makeCtx({
+      latestMessages: messages,
+      modelProfileKey: "vision-model",
+    });
+    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 });
@@ -317,15 +340,6 @@ describe("image-fallback user-prompt-submit hook", () => {
       "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", () => {

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

@@ -8,9 +8,8 @@
  * `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.
+ *    {@link needsImageFallback}, using the turn's effective `modelProfileKey`.
+ *    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.

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

@@ -39,22 +39,15 @@ 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.
+ * Used by `user-prompt-submit`, whose context carries the effective profile
+ * identity. Profileless configs use the resolved model id, which
+ * `doesSupportVision` can check directly.
  */
-export function needsImageFallback(modelProfileKey: string | null): boolean {
+export function needsImageFallback(modelProfileKey: string): 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);
+  const profile = profiles.find((p) => p.key === modelProfileKey);
+  if (profile == null) return !doesSupportVision(modelProfileKey);
+  return !doesSupportVision(profile);
 }
 
 /**

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

@@ -16,7 +16,6 @@ import {
   type PluginLogger,
 } from "@vellumai/plugin-api";
 
-import { extractAllText } from "../../../../providers/provider-send-message.js";
 import {
   getCachedCaption,
   imageHash,
@@ -30,7 +29,8 @@ const CAPTION_SYSTEM_PROMPT =
   "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.";
+const CAPTION_USER_PROMPT =
+  "Describe this image concisely for a text-only assistant.";
 
 /**
  * Find a vision-capable, enabled profile key for captioning.
@@ -102,13 +102,21 @@ export async function captionImage(
       },
     );
 
-    const caption = extractAllText(response).trim();
+    // Vision captioning returns text content; concatenate any text blocks
+    // (effectively always one here, since tool use is disabled).
+    const caption = response.content
+      .flatMap((block) => (block.type === "text" ? [block.text] : []))
+      .join(" ")
+      .trim();
     if (caption.length > 0) {
       setCachedCaption(hash, caption);
       return caption;
     }
 
-    logger.warn({ plugin: "image-fallback" }, "Vision captioning returned empty text");
+    logger.warn(
+      { plugin: "image-fallback" },
+      "Vision captioning returned empty text",
+    );
     return null;
   } catch (err) {
     logger.warn(