@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/plugins/defaults/memory-v3-shadow/section-dense-store.ts

@@ -86,7 +86,40 @@ export async function ensureSectionCollection(
   const onDisk = config.memory.qdrant.onDisk;
 
   const exists = await client.collectionExists(SECTION_COLLECTION);
-  if (!exists.exists) {
+  let needsCreate = !exists.exists;
+
+  // An existing collection sized to a different embedding dimension (e.g. a
+  // 384-dim collection now serving a 3072-dim embedder) carries the right
+  // vector at the wrong size — every upsert then fails with HTTP 400 and the
+  // collection is never repaired. Probe the schema and recreate on dimension
+  // drift; on a probe failure, assume compatible rather than risk a destructive
+  // recreate (mirrors the v2 concept-page collection posture). The next
+  // `backfillAllSections` regenerates the embeddings.
+  if (exists.exists) {
+    try {
+      const info = await client.getCollection(SECTION_COLLECTION);
+      const vectors = info.config?.params?.vectors;
+      const size =
+        vectors && typeof vectors === "object" && "size" in vectors
+          ? (vectors as { size?: unknown }).size
+          : undefined;
+      if (typeof size === "number" && size !== vectorSize) {
+        log.warn(
+          { collection: SECTION_COLLECTION, expected: vectorSize, found: size },
+          "Memory v3 section collection dimension drift — deleting and recreating; embeddings will be regenerated by the next backfill",
+        );
+        await client.deleteCollection(SECTION_COLLECTION);
+        needsCreate = true;
+      }
+    } catch (err) {
+      log.warn(
+        { err, collection: SECTION_COLLECTION },
+        "Failed to probe v3 section collection schema; assuming compatible",
+      );
+    }
+  }
+
+  if (needsCreate) {
     log.info(
       { collection: SECTION_COLLECTION, vectorSize },
       "Creating Qdrant collection for memory v3 sections",

package/src/plugins/defaults/memory-v3-shadow/selection-log-store.ts

@@ -1,25 +1,32 @@
 /**
- * Read-side store for the inspector's Memory V3 section. Reads the persisted
- * `memory_v3_selections` rows for a turn and re-renders an APPROXIMATE
- * `<memory>` block for what v3 selected, so the inspector can show the turn's
- * selection without re-running orchestration — which would be wrong anyway,
- * since the hot lane is frecency-stateful and can't be reproduced after the
- * fact.
+ * Read-side store for the inspector's Memory V3 panel. Reads the persisted
+ * `memory_v3_selections` rows for a turn (by the turn's message ids) and
+ * re-renders the `<memory>` block for what v3 selected, so the inspector can
+ * show the turn's selection without re-running orchestration — which would be
+ * wrong anyway, since the hot lane is frecency-stateful and can't be reproduced
+ * after the fact.
  *
- * The rendered text is inspector-only and NOT byte-identical to live
- * injection: the live injector freezes net-new compact CARDS into history
- * (`renderV3CardContent`) plus an ephemeral spotlight, while this store
- * re-renders the whole selection set as full/lead pages
- * (`renderV3SectionContent` with no persisted section identity — see the
- * inline note at `injectedText`).
+ * The rendered text is inspector-only and NOT byte-identical to live injection:
+ * the live injector freezes net-new compact CARDS into history
+ * (`renderV3CardContent`) plus an ephemeral spotlight. Here we re-render each
+ * selection's MATCHED SECTION — resolved from the persisted `(slug, ordinal)`
+ * against the current page — when one was recorded, falling back to the
+ * full/lead page otherwise. Section text is re-derived from the current page,
+ * so it reflects bounded page-drift if the page changed since the turn (the
+ * same approximation the v2 inspector accepts).
  */
 
 import type { MemoryV3SelectionLog } from "../../../api/responses/memory-v3-selection-log.js";
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
 import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
+import { readPage } from "../../../memory/v2/page-store.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
+import { capabilityOrDiskBody } from "./capabilities.js";
+import { sectionByOrdinal } from "./orchestrate.js";
 import { renderV3SectionContent } from "./page-content.js";
 import { renderMemoryBlock } from "./render-injection.js";
+import { buildSectionIndex } from "./sections.js";
 import {
   type Section,
   SELECTION_SOURCES,
@@ -31,16 +38,21 @@ const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
 const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 interface SelectionRow {
+  turn: number;
   slug: string;
   source: string;
   pinned: number;
+  section_ordinal: number | null;
+  section_title: string | null;
 }
 
+const SELECTION_COLUMNS = `turn, slug, source, pinned, section_ordinal, section_title`;
+
 function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
   return getSqliteFrom(getDb())
     .query(
       /*sql*/ `
-      SELECT slug, source, pinned FROM memory_v3_selections
+      SELECT ${SELECTION_COLUMNS} FROM memory_v3_selections
       WHERE conversation_id = ? AND turn = ?
       ORDER BY rowid
     `,
@@ -48,32 +60,59 @@ function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
     .all(conversationId, turn) as SelectionRow[];
 }
 
+function rowsForMessageIds(messageIds: string[]): SelectionRow[] {
+  if (messageIds.length === 0) return [];
+  const placeholders = messageIds.map(() => "?").join(", ");
+  return getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `
+      SELECT ${SELECTION_COLUMNS} FROM memory_v3_selections
+      WHERE message_id IN (${placeholders})
+      ORDER BY rowid
+    `,
+    )
+    .all(...messageIds) as SelectionRow[];
+}
+
 /**
- * Build the inspector's v3 selection log for one turn of a conversation.
- *
- * `turn` is the inspected message's turn (the v2-activation log's turn). The
- * selection is returned ONLY for that exact turn; when there are no v3 rows for
- * it — including when `turn` is null (the message has no v2-activation turn) —
- * this returns `null` rather than falling back to a different turn. A fallback
- * would attribute another turn's selection (e.g. a later turn's pages and
- * rendered block) to the inspected message, which corrupts shadow validation.
- *
- * Caveat: v3 rows are keyed by the orchestrator turn counter (`ctx.turnCount`)
- * while `turn` here is the v2 memory-tracker turn. They coincide for normal
- * turns, but if they diverge this simply yields `null` (no section) rather than
- * wrong data. Tying v3 rows to a message id for exact per-message attribution
- * regardless of counter drift is a documented follow-up.
- *
- * Selection rows are stored in selection order, so rendering them in row order
- * reproduces the block v3 would inject.
+ * Resolve each selection's persisted matched section `(slug, ordinal)` to the
+ * concrete `Section` in the CURRENT page, so the injected block renders the
+ * matched section rather than the full page. Only slugs with a recorded ordinal
+ * are resolved (core/hot/fresh/edge selections have none and render full-page).
+ * A page edited since the turn re-derives the current section at that ordinal,
+ * or falls back to full-page when the ordinal no longer exists.
  */
-export async function getMemoryV3SelectionForInspector(
-  conversationId: string,
-  turn: number | null | undefined,
-): Promise<MemoryV3SelectionLog | null> {
-  if (turn == null) return null;
+async function reconstructMatchedSections(
+  rows: SelectionRow[],
+): Promise<Map<Slug, Section>> {
+  const sectionSlugs = rows
+    .filter((r) => r.section_ordinal != null)
+    .map((r) => r.slug);
+  if (sectionSlugs.length === 0) return new Map();
+
+  const workspaceDir = getWorkspaceDir();
+  const pageBody = (slug: Slug): Promise<string> =>
+    capabilityOrDiskBody(slug, async (s) => {
+      try {
+        return (await readPage(workspaceDir, s))?.body ?? "";
+      } catch {
+        return "";
+      }
+    });
+  const index = await buildSectionIndex(sectionSlugs, pageBody);
+
+  const sectionBySlug = new Map<Slug, Section>();
+  for (const row of rows) {
+    if (row.section_ordinal == null) continue;
+    const section = sectionByOrdinal(index, row.slug, row.section_ordinal);
+    if (section) sectionBySlug.set(row.slug, section);
+  }
+  return sectionBySlug;
+}
 
-  const rows = rowsForTurn(conversationId, turn);
+async function buildSelectionLog(
+  rows: SelectionRow[],
+): Promise<MemoryV3SelectionLog | null> {
   if (rows.length === 0) return null;
 
   const config = getConfig();
@@ -81,25 +120,19 @@ export async function getMemoryV3SelectionForInspector(
     slug: r.slug,
     source: r.source,
     pinned: r.pinned === 1,
+    sectionOrdinal: r.section_ordinal,
+    sectionHeading: r.section_title,
   }));
   const slugs: Slug[] = selections.map((s) => s.slug);
-  // NOTE: `injectedText` is APPROXIMATE — it renders the full/lead page for
-  // every slug, not the exact matched section live injection used. The inspector
-  // re-renders from persisted rows without re-running orchestration, and the
-  // section identity is not persisted (`memory_v3_selections` stores
-  // slug/source/pinned, not the section ordinal), so the section map is empty
-  // and `renderV3SectionContent` falls back to the full page. Persisting the
-  // injected section (a schema migration) is deliberately deferred: the A/B's
-  // primary signal is slug-level recall via `summarizeSelections`, which is
-  // exact — only this debug-oriented injected text is an approximation.
+  const sectionBySlug = await reconstructMatchedSections(rows);
   const injectedText = await renderMemoryBlock(
     slugs,
-    new Map<Slug, Section>(),
+    sectionBySlug,
     renderV3SectionContent,
   );
 
   return {
-    turn,
+    turn: rows[0]!.turn,
     live: isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config),
     shadow: isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config),
     selections,
@@ -107,6 +140,38 @@ export async function getMemoryV3SelectionForInspector(
   };
 }
 
+/**
+ * Build the inspector's v3 selection log for the inspected message's turn,
+ * keyed by the turn's message ids. This is the durable join: `writeSelections`
+ * logs rows with `message_id = NULL` and the turn-end backfill stamps them with
+ * the assistant message id, so a per-message lookup is robust against the drift
+ * between v2's tracker turn and v3's orchestrator `turnCount`. Returns `null`
+ * when no v3 rows match (e.g. a turn predating the message-id backfill, or a
+ * conversation with no v3 data). Message ids are globally unique, so no
+ * conversation scope is needed.
+ *
+ * Selection rows are stored in selection order, so rendering them in row order
+ * reproduces the block v3 would inject.
+ */
+export async function getMemoryV3SelectionForInspectorByMessageIds(
+  messageIds: string[],
+): Promise<MemoryV3SelectionLog | null> {
+  return buildSelectionLog(rowsForMessageIds(messageIds));
+}
+
+/**
+ * Turn-keyed variant, retained for callers/tests that look up by an exact
+ * `(conversation, turn)`. Returns `null` when `turn` is null or there are no
+ * rows for it.
+ */
+export async function getMemoryV3SelectionForInspector(
+  conversationId: string,
+  turn: number | null | undefined,
+): Promise<MemoryV3SelectionLog | null> {
+  if (turn == null) return null;
+  return buildSelectionLog(rowsForTurn(conversationId, turn));
+}
+
 /**
  * Offline A/B aggregate over a conversation's logged v3 selections. Reads every
  * `memory_v3_selections` row for the conversation (all turns) and rolls them up

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

@@ -55,6 +55,7 @@ import { computeHotSet } from "./hot-set.js";
 import { computeLearnedEdgeGraph } from "./learned-edges.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
+import { MemoryV3RetrievalUnavailableError } from "./pool-select.js";
 import { ensureSectionCollection } from "./section-dense-store.js";
 import type { SectionNeedle } from "./section-needle.js";
 import { buildSectionNeedle } from "./section-needle.js";
@@ -418,6 +419,11 @@ interface SelectionRow {
   slug: Slug;
   source: SelectionSource;
   pinned: number;
+  /** Ordinal of the matched section a finder lane surfaced; null for
+   *  core/hot/fresh/edge selections with no matched section. */
+  sectionOrdinal: number | null;
+  /** Heading of the matched section; null when there is no matched section. */
+  sectionTitle: string | null;
 }
 
 /**
@@ -438,17 +444,24 @@ export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
   const finderLane = new Map(
     result.lanes.finder.map((c) => [c.slug, c.lane] as const),
   );
-  return result.selections.map((sel) => ({
-    slug: sel.slug,
-    source: core.has(sel.slug)
-      ? ("core" as const)
-      : hot.has(sel.slug)
-        ? ("hot" as const)
-        : fresh.has(sel.slug)
-          ? ("fresh" as const)
-          : (finderLane.get(sel.slug) ?? "needle"),
-    pinned: sel.pinned ? 1 : 0,
-  }));
+  return result.selections.map((sel) => {
+    // The matched section is populated only for finder-lane hits (including
+    // hits on core/hot pages); core/hot/fresh/edge-only selections have none.
+    const section = result.matchedSections.get(sel.slug);
+    return {
+      slug: sel.slug,
+      source: core.has(sel.slug)
+        ? ("core" as const)
+        : hot.has(sel.slug)
+          ? ("hot" as const)
+          : fresh.has(sel.slug)
+            ? ("fresh" as const)
+            : (finderLane.get(sel.slug) ?? "needle"),
+      pinned: sel.pinned ? 1 : 0,
+      sectionOrdinal: section?.ordinal ?? null,
+      sectionTitle: section?.title ?? null,
+    };
+  });
 }
 
 /** Write the attributed selection rows to `memory_v3_selections`. */
@@ -461,17 +474,51 @@ export function writeSelections(
   const raw = getSqliteFrom(getDb());
   // PK is (conversation_id, turn, slug); OR REPLACE keeps the write
   // idempotent if the same turn is observed twice (e.g. a retried turn).
+  // `message_id` is written NULL here (the assistant message does not exist at
+  // injection time) and stamped at turn end by
+  // `backfillMemoryV3SelectionMessageId`.
   const stmt = raw.query(/*sql*/ `
     INSERT OR REPLACE INTO memory_v3_selections (
-      conversation_id, turn, slug, source, pinned, created_at
-    ) VALUES (?, ?, ?, ?, ?, ?)
+      conversation_id, turn, slug, source, pinned, created_at,
+      message_id, section_ordinal, section_title
+    ) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?)
   `);
   const now = Date.now();
   for (const row of rows) {
-    stmt.run(conversationId, turn, row.slug, row.source, row.pinned, now);
+    stmt.run(
+      conversationId,
+      turn,
+      row.slug,
+      row.source,
+      row.pinned,
+      now,
+      row.sectionOrdinal,
+      row.sectionTitle,
+    );
   }
 }
 
+/**
+ * Stamp the turn's assistant message id onto the selection rows just written
+ * for it. Mirrors the v2 activation-log backfill: `writeSelections` writes
+ * `message_id = NULL` at injection time, and this runs at turn end once the
+ * assistant message exists. Relies on the single-threaded-per-conversation turn
+ * invariant — every NULL-`message_id` row for the conversation belongs to the
+ * turn that just finished. Lets the inspector look v3 selections up by the
+ * turn's message ids (robust against v2/v3 turn-counter drift).
+ */
+export function backfillMemoryV3SelectionMessageId(
+  conversationId: string,
+  assistantMessageId: string,
+): void {
+  getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `UPDATE memory_v3_selections SET message_id = ?
+               WHERE conversation_id = ? AND message_id IS NULL`,
+    )
+    .run(assistantMessageId, conversationId);
+}
+
 /**
  * Run v3 orchestration for one turn and log the selection set, returning the
  * orchestrate result so a live caller can render it. Never throws — all
@@ -530,6 +577,16 @@ export async function observeTurn(
     writeSelections(conversationId, turnIndex, rows);
     return result;
   } catch (err) {
+    // An INFRASTRUCTURE failure (the selector lost its provider — e.g. a
+    // transient CES credential blip) must NOT be silently swallowed: re-throw
+    // so the LIVE injector hard-fails the turn (a clean, retryable failure)
+    // rather than shipping it with no `<memory>` block. The shadow/observation
+    // callers (the injector in shadow mode, runShadowObservation) catch this
+    // and swallow it, so observation never fails a turn. Other (non-infra)
+    // errors stay non-fatal and degrade to no v3 block, as before.
+    if (err instanceof MemoryV3RetrievalUnavailableError) {
+      throw err;
+    }
     log.warn(
       { err: err instanceof Error ? err.message : String(err), conversationId },
       "memory-v3 orchestration failed (non-fatal)",
@@ -553,5 +610,11 @@ export async function runShadowObservation(
   const config = getConfig();
   if (config.memory.enabled === false) return;
   if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config)) return;
-  await observeTurn(conversationId, turnIndex);
+  try {
+    await observeTurn(conversationId, turnIndex);
+  } catch {
+    // Shadow observation is fire-and-forget and must NEVER fail a turn.
+    // `observeTurn` now re-throws infra failures so the LIVE injector can
+    // hard-fail on them; here (observation only) we swallow them.
+  }
 }

package/src/plugins/defaults/task-progress-nudge/hooks/post-tool-use.ts

@@ -0,0 +1,206 @@
+/**
+ * Default `post-tool-use` hook: when an interactive turn accumulates several
+ * tool-call rounds without the model having shown a `task_progress` card,
+ * surface a soft notice via `additionalContext` reminding it to show progress.
+ *
+ * Motivation: the system prompt and the `ui_show` tool description both ask
+ * the model to show a `task_progress` card on long multi-step turns, but
+ * weaker models (e.g. MiniMax M3) disregard the static instruction and run
+ * 30+ tool calls with no user-visible progress. A reminder injected mid-turn,
+ * right after a tool result, is far more salient than static prompt text.
+ *
+ * The nudge is strictly best-effort:
+ * - It fires at most once per turn (no nagging).
+ * - It is advisory — the model may decline if it is about to finish or judges
+ *   a card unnecessary.
+ * - A failed or ignored card never blocks the turn.
+ *
+ * It is scoped to weaker open models (Kimi, DeepSeek, MiniMax) that disregard
+ * the static progress-card instruction; capable models follow the prompt and
+ * never need the reminder. It also self-targets: a model that already showed a
+ * card this turn is never nudged.
+ *
+ * The turn state is derived from conversation history on every call (mirroring
+ * the tool-error and exploration-drift plugins) so the signal survives
+ * mid-turn compaction rewriting the array. The current turn is the trailing
+ * window bounded by the last genuine user message (a user row with no
+ * tool_result blocks). Within it we count tool-use rounds and detect whether a
+ * `ui_show` task_progress card was issued.
+ *
+ * Gating:
+ * - weaker open models only (Kimi, DeepSeek, MiniMax) — checked first on the
+ *   hot path so capable-model turns short-circuit immediately.
+ * - mainAgent call site only — background turns (wake, title-gen, memory) and
+ *   subagents have no live user watching, so a progress card is pointless.
+ * - the client must support dynamic UI — otherwise `ui_show` is blocked
+ *   client-side and the nudge would only provoke a wasted, erroring call.
+ *
+ * The call-site, capability, and subagent gates are resolved lazily on the
+ * would-nudge path; the model gate is a cheap regex test run up front.
+ *
+ * Dedup uses a per-conversation high-water mark of the round count at the last
+ * nudge: a non-zero mark means "already nudged this turn", which also dedupes
+ * the parallel tool results of one batch (they observe identical history and
+ * compute the same round count). The mark resets when the round count drops
+ * below it (a new turn restarts counting low).
+ */
+
+import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical nudge notice. Module-level constant so tests and wrapping plugins
+ * can match it without duplicating the string. Shown to the model as
+ * provider-only context, never to the user. Deliberately soft: coarse steps
+ * are fine and the model may skip it when wrapping up.
+ */
+export const TASK_PROGRESS_NUDGE_TEXT =
+  '<system_notice>You are several tool calls into this turn and have not shown the user a progress card. If you are doing multi-step work, call ui_show now with surface_type "card" and template "task_progress" (coarse steps are fine — a rough "Working on X" beats no signal) so the user can see what is happening, and keep it updated with ui_update as you go. Skip this if you are about to finish; never let it interrupt the actual work.</system_notice>';
+
+/**
+ * Number of tool-use rounds in a turn, with no task_progress card shown, that
+ * triggers the nudge. Tuned conservatively: a turn of one or two rounds (the
+ * common simple case) is never touched; only a clearly multi-step turn is
+ * nudged, and only once. Lower from telemetry if cards still arrive too late.
+ */
+export const TASK_PROGRESS_NUDGE_ROUND_THRESHOLD = 3;
+
+/**
+ * Weaker open models that disregard the static progress-card instruction and
+ * so get the mid-turn nudge: Kimi, DeepSeek, and MiniMax. Family-level matching
+ * spans provider naming conventions (OpenRouter `moonshotai/kimi-k2.6`,
+ * `deepseek/deepseek-chat`, `minimax/minimax-m3`; Fireworks
+ * `accounts/fireworks/models/minimax-m3`, `kimi-k2p6`). Extend as other models
+ * show the same gap. Capable models (Claude, GPT) follow the prompt and are
+ * intentionally excluded.
+ */
+const WEAK_MODEL_PATTERN = /kimi|deepseek|minimax/i;
+
+/**
+ * Round count at the last nudge, per conversation. A non-zero entry means the
+ * turn has already been nudged; it resets when the round count drops below the
+ * mark (a new turn). Mirrors the exploration-drift high-water mark so parallel
+ * results of one batch dedupe to a single notice.
+ */
+const lastNudgedRoundsByConversation = new Map<string, number>();
+
+/** Test-only: clear the per-conversation nudge high-water marks. */
+export function resetTaskProgressNudgeStateForTests(): void {
+  lastNudgedRoundsByConversation.clear();
+}
+
+/**
+ * True when a `ui_show` tool input shows a `task_progress` card — accepting the
+ * template either at the top level or nested under `data`, mirroring the
+ * server-side normalization tolerance.
+ */
+function isTaskProgressShowInput(input: unknown): boolean {
+  if (input === null || typeof input !== "object") return false;
+  const record = input as Record<string, unknown>;
+  if (record.template === "task_progress") return true;
+  const data = record.data;
+  return (
+    data !== null &&
+    typeof data === "object" &&
+    (data as Record<string, unknown>).template === "task_progress"
+  );
+}
+
+/**
+ * Scan the trailing turn (walking back to the last genuine user message) for
+ * the number of tool-use rounds and whether a task_progress card was shown.
+ * The current round's assistant tool_use is already in history; its result is
+ * not, so the count includes the current round.
+ */
+function scanTurn(messages: ReadonlyArray<Message>): {
+  rounds: number;
+  taskProgressShown: boolean;
+} {
+  let rounds = 0;
+  let taskProgressShown = false;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "user") {
+      const carriesToolResult = message.content.some(
+        (block: ContentBlock) =>
+          block.type === "tool_result" ||
+          block.type === "web_search_tool_result",
+      );
+      if (!carriesToolResult) break; // genuine user prompt — turn boundary
+      continue;
+    }
+    if (message.role !== "assistant") continue;
+    let hasToolUse = false;
+    for (const block of message.content) {
+      if (block.type !== "tool_use") continue;
+      hasToolUse = true;
+      if (block.name === "ui_show" && isTaskProgressShowInput(block.input)) {
+        taskProgressShown = true;
+      }
+    }
+    if (hasToolUse) rounds++;
+  }
+  return { rounds, taskProgressShown };
+}
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  if (!WEAK_MODEL_PATTERN.test(ctx.model)) return;
+
+  const { rounds, taskProgressShown } = scanTurn(ctx.messages);
+
+  let lastNudged = lastNudgedRoundsByConversation.get(ctx.conversationId) ?? 0;
+  if (rounds < lastNudged) {
+    // New turn (round count restarted low) — drop the stale mark.
+    lastNudgedRoundsByConversation.delete(ctx.conversationId);
+    lastNudged = 0;
+  }
+
+  // A card now exists this turn: clear any stale mark and never nudge.
+  if (taskProgressShown) {
+    if (lastNudged !== 0) {
+      lastNudgedRoundsByConversation.delete(ctx.conversationId);
+    }
+    return;
+  }
+
+  if (rounds < TASK_PROGRESS_NUDGE_ROUND_THRESHOLD) return;
+  if (lastNudged !== 0) return; // already nudged this turn
+
+  // Resolve gating lazily on the rare would-nudge path to keep the hot path
+  // free of the conversation-registry and subagent module graphs.
+  const { findConversation } =
+    await import("../../../../daemon/conversation-registry.js");
+  const conversation = findConversation(ctx.conversationId);
+  if (!conversation) return;
+
+  if (
+    conversation.currentCallSite &&
+    conversation.currentCallSite !== "mainAgent"
+  ) {
+    return; // background call site — no live user watching
+  }
+
+  const capabilities =
+    conversation.currentTurnChannelCapabilities ??
+    conversation.channelCapabilities;
+  if (capabilities && capabilities.supportsDynamicUi === false) {
+    return; // client cannot render surfaces — a nudge would only error
+  }
+
+  const { getSubagentManager } = await import("../../../../subagent/index.js");
+  if (getSubagentManager().getParentInfo(ctx.conversationId) !== undefined) {
+    return; // subagents have no live user
+  }
+
+  lastNudgedRoundsByConversation.set(ctx.conversationId, rounds);
+  ctx.logger.info(
+    { plugin: "task-progress-nudge", rounds },
+    "Multi-step turn with no task_progress card — nudging the model to show progress",
+  );
+  ctx.additionalContext = ctx.additionalContext
+    ? `${ctx.additionalContext}\n${TASK_PROGRESS_NUDGE_TEXT}`
+    : TASK_PROGRESS_NUDGE_TEXT;
+};
+
+export default postToolUse;

package/src/plugins/defaults/task-progress-nudge/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-task-progress-nudge",
+  "version": "1.0.0",
+  "description": "First-party default plugin contributing a post-tool-use hook that nudges the model to show a task_progress card when an interactive turn accumulates several tool-call rounds without one.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}