@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/plugins/defaults/empty-response/nudge-state-store.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-conversation empty-response nudge state for the default empty-response
+ * module.
+ *
+ * The `post-model-call` hook recovers from an empty turn after tool use by
+ * appending a nudge and asking the loop to re-query. That recovery is bounded
+ * to one pass per run: a second empty turn means the nudge could not coax a
+ * real answer, so the hook lets the turn end rather than looping.
+ *
+ * The two hooks split this state's lifecycle: `post-model-call` marks a
+ * conversation when it issues a nudge-retry, and the sibling `stop` hook clears
+ * the mark when the turn terminates. A conversation therefore only holds an
+ * entry while a nudge is in flight, and the next run always nudges afresh.
+ *
+ * This module is side-effect free: importing it only initializes an empty store
+ * and registers no plugin.
+ */
+
+/** Conversations with an empty-response nudge in flight for the current run. */
+const nudgeInFlight = new Set<string>();
+
+/** Whether the conversation already issued its one nudge this run. */
+export function isEmptyResponseNudged(conversationId: string): boolean {
+  return nudgeInFlight.has(conversationId);
+}
+
+/** Record that the conversation issued its one nudge-retry this run. */
+export function markEmptyResponseNudged(conversationId: string): void {
+  nudgeInFlight.add(conversationId);
+}
+
+/**
+ * Clear the conversation's nudge mark so the next run nudges afresh. The
+ * sibling `stop` hook calls this when the turn terminates.
+ */
+export function clearEmptyResponseNudged(conversationId: string): void {
+  nudgeInFlight.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's nudge state so a suite that drives the
+ * hook directly starts each case from an empty store.
+ */
+export function resetEmptyResponseNudgeStoreForTests(): void {
+  nudgeInFlight.clear();
+}

package/src/plugins/defaults/history-repair/hooks/post-model-call.ts

@@ -0,0 +1,50 @@
+/**
+ * Default `post-model-call` hook: recovers from a provider ordering rejection.
+ *
+ * A provider rejects the call when the history violates tool-use/tool-result
+ * pairing or role-alternation rules (orphan `tool_use`, orphan
+ * `web_search_tool_result`, leading assistant turn, consecutive same-role
+ * turns). That rejection is a model-call outcome — the loop runs the
+ * `post-model-call` chain with the rejection attached. This hook recognizes the
+ * ordering class and runs {@link deepRepairHistory} directly — deliberately not
+ * through the `user-prompt-submit` hook chain, whose user/plugin hooks may have
+ * caused the drift — to re-normalize the history, then asks the loop to retry
+ * the call.
+ *
+ * Bounded to one pass per turn via the per-conversation repair state: a second
+ * consecutive ordering rejection means the repair could not recover the
+ * history, so the hook leaves the error to surface rather than looping. The
+ * loop's per-run backstop caps these retries globally; this one-shot mark keeps
+ * a single recovery attempt per turn. This hook only ever marks the
+ * conversation; the sibling `stop` hook (see `./stop.ts`) clears the mark when
+ * the turn terminates, so the next turn always repairs afresh.
+ *
+ * A finalized reply (the model returned content) is left untouched for the
+ * empty-response hook; only a provider rejection is this hook's to act on.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import {
+  isOrderingRepairAttempted,
+  markOrderingRepairAttempted,
+} from "../repair-state-store.js";
+import { deepRepairHistory, isRepairableOrderingError } from "../terminal.js";
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  if (
+    ctx.error &&
+    isRepairableOrderingError(ctx.error.message) &&
+    !isOrderingRepairAttempted(ctx.conversationId)
+  ) {
+    markOrderingRepairAttempted(ctx.conversationId);
+    ctx.messages = deepRepairHistory(ctx.messages).messages;
+    ctx.decision = "continue";
+    ctx.logger.warn(
+      { plugin: "history-repair", messageCount: ctx.messages.length },
+      "Provider ordering error — recovering via history deep-repair",
+    );
+  }
+};
+
+export default postModelCall;

package/src/plugins/defaults/history-repair/hooks/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `stop` hook: clears the per-conversation ordering-repair bound when a
+ * turn terminates.
+ *
+ * The `post-model-call` hook (see `./post-model-call.ts`) marks the bound when
+ * it deep-repairs the history and asks the loop to retry. `stop` is the
+ * definitive terminal hook — it fires exactly once when the turn is truly
+ * ending, after every retry decision has been made — so clearing the bound here
+ * unconditionally guarantees the next turn always repairs afresh, no matter how
+ * the turn ended (a finalized reply, an unrecovered rejection, an abort, or a
+ * retry the loop's per-run backstop refused).
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { clearOrderingRepairAttempted } from "../repair-state-store.js";
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  clearOrderingRepairAttempted(ctx.conversationId);
+};
+
+export default stop;

package/src/plugins/defaults/history-repair/repair-state-store.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-conversation ordering-repair state for the default history-repair module.
+ *
+ * The `post-model-call` hook recovers from a provider ordering rejection by
+ * running a deep repair and asking the loop to retry. That recovery is bounded
+ * to one pass per turn: a second consecutive ordering rejection means the
+ * repair could not recover the history, so the hook lets the error surface
+ * rather than looping.
+ *
+ * The `post-model-call` hook marks a conversation when it issues a repair-retry
+ * and clears the mark on any outcome it resolves — a finalized reply, a
+ * non-ordering rejection, or an exhausted second ordering rejection. The
+ * `stop` hook clears it on the one terminal that hook does not resolve: a retry
+ * the loop's per-run backstop overrides, surfacing the rejection without
+ * re-running `post-model-call`. A conversation therefore only holds an entry
+ * while a repair is in flight, so the store stays bounded without a separate
+ * teardown step.
+ *
+ * This module is side-effect free: importing it only initializes an empty store
+ * and registers no plugin.
+ */
+
+/** Conversations with a deep-repair pass in flight for the current turn. */
+const repairInFlight = new Set<string>();
+
+/** Whether the conversation already attempted a deep repair this turn. */
+export function isOrderingRepairAttempted(conversationId: string): boolean {
+  return repairInFlight.has(conversationId);
+}
+
+/** Record that the conversation issued its one deep-repair retry this turn. */
+export function markOrderingRepairAttempted(conversationId: string): void {
+  repairInFlight.add(conversationId);
+}
+
+/**
+ * Clear the conversation's repair mark so the next turn (or run) repairs afresh.
+ * The `post-model-call` hook calls this on the outcomes it resolves; the `stop`
+ * hook calls it on a terminal stop to cover a backstop-overridden retry.
+ */
+export function clearOrderingRepairAttempted(conversationId: string): void {
+  repairInFlight.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's repair state so a suite that drives the
+ * hook directly starts each case from an empty store.
+ */
+export function resetRepairStateStoreForTests(): void {
+  repairInFlight.clear();
+}

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

@@ -7,8 +7,9 @@
  * `repairHistory` is the canonical repair pass, run per turn via the plugin's
  * `user-prompt-submit` hook (`./hooks/user-prompt-submit.ts`) and exported so
  * daemon call sites and tests can reach it directly. `deepRepairHistory` is an
- * aggressive one-shot fallback the orchestrator invokes only after a provider
- * ordering error.
+ * aggressive one-shot fallback applied after a provider ordering rejection, and
+ * `isRepairableOrderingError` recognizes the rejections it can recover — so
+ * detection and repair of ordering drift live together as one unit.
  */
 
 import type {
@@ -333,6 +334,42 @@ function formatWebSearchContent(content: unknown): string {
   return "results unavailable";
 }
 
+/**
+ * Provider rejection messages indicating a tool_use/tool_result pairing or
+ * message-ordering violation — the structural drift `deepRepairHistory`
+ * re-normalizes.
+ */
+export const ORDERING_ERROR_PATTERNS: readonly RegExp[] = [
+  /tool_result.*not immediately after.*tool_use/i,
+  /tool_use.*must have.*tool_result/i,
+  /tool_use_id.*without.*tool_result/i,
+  /tool_result.*tool_use_id.*not found/i,
+  /messages.*invalid.*order/i,
+];
+
+/**
+ * Provider rejection messages for the server-side web-search tool's own
+ * tool_use/result pairing violations, which `repairHistory` resolves by
+ * downgrading the orphaned block to text.
+ */
+export const WEB_SEARCH_ORDERING_PATTERNS: readonly RegExp[] = [
+  /web_search.*tool_use.*without/i,
+  /web_search.*tool_result/i,
+];
+
+/**
+ * Whether a provider error message denotes an ordering/pairing violation that
+ * `deepRepairHistory` can recover by re-normalizing the history. Detection and
+ * repair are co-located so callers recognize and fix ordering drift through a
+ * single source of truth.
+ */
+export function isRepairableOrderingError(message: string): boolean {
+  return (
+    ORDERING_ERROR_PATTERNS.some((pattern) => pattern.test(message)) ||
+    WEB_SEARCH_ORDERING_PATTERNS.some((pattern) => pattern.test(message))
+  );
+}
+
 /**
  * Aggressive repair pass that handles edge cases beyond repairHistory:
  * - Removes empty messages

package/src/plugins/defaults/image-recovery/detect.ts

@@ -0,0 +1,25 @@
+/**
+ * Detection for the image-too-large recovery path.
+ *
+ * Anthropic returns a 400 with one of these messages when an image block
+ * violates a hard limit. The first matches the per-side pixel cap ("image
+ * dimensions exceed max allowed size"); the second matches the base64 payload
+ * cap ("image exceeds 5 MB maximum: 7465044 bytes > 5242880 bytes"). Distinct
+ * classification matters because retrying with the same oversized image is
+ * futile — the recovery path must downscale or note it instead.
+ *
+ * Exported as the single source of truth: the image-recovery `stop` hook reads
+ * it to recognize the rejection it can recover, and `daemon/conversation-error`
+ * imports it so the user-facing classification stays in lockstep with what the
+ * hook actually recovers.
+ */
+
+export const IMAGE_DIMENSIONS_TOO_LARGE_PATTERNS: readonly RegExp[] = [
+  /image dimensions? exceeds? max allowed size/i,
+  /image exceeds \d+\s*MB maximum/i,
+];
+
+/** Whether an error message indicates an image-input dimension/payload failure. */
+export function isImageDimensionsTooLargeError(message: string): boolean {
+  return IMAGE_DIMENSIONS_TOO_LARGE_PATTERNS.some((p) => p.test(message));
+}

package/src/plugins/defaults/image-recovery/hooks/post-model-call.ts

@@ -0,0 +1,73 @@
+/**
+ * Default `post-model-call` hook: recovers from a provider image-too-large
+ * rejection.
+ *
+ * A provider rejects the call when an attached image violates a hard limit —
+ * its longest side exceeds the per-side pixel cap, or its base64 payload
+ * exceeds the size cap. That rejection is a model-call outcome — the loop runs
+ * the `post-model-call` chain with the rejection attached. This hook recognizes
+ * the image-too-large class, downscales the oversized image blocks in the
+ * working history via {@link recoverOversizedImages}, and asks the loop to
+ * retry the call. It also persists the same downgrade durably via {@link
+ * persistUnsendableImageDowngrades} so the rejected image cannot rehydrate from
+ * the stored row and re-reject on every later turn.
+ *
+ * Bounded to one pass per turn via the per-conversation recovery state: a
+ * second consecutive image-too-large rejection means the downscale could not
+ * bring the image under the cap, so the hook leaves the error to surface rather
+ * than looping. The loop's per-run backstop caps these retries globally; this
+ * one-shot mark keeps a single recovery attempt per turn. This hook only ever
+ * marks the conversation; the sibling `stop` hook (see `./stop.ts`) clears the
+ * mark when the turn terminates, so the next turn recovers afresh.
+ *
+ * A finalized reply (the model returned content) is left untouched for the
+ * empty-response hook; only a provider rejection is this hook's to act on.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import { isImageDimensionsTooLargeError } from "../detect.js";
+import {
+  isImageRecoveryAttempted,
+  markImageRecoveryAttempted,
+} from "../image-recovery-state-store.js";
+import {
+  persistUnsendableImageDowngrades,
+  recoverOversizedImages,
+} from "../recover.js";
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  if (
+    ctx.error &&
+    isImageDimensionsTooLargeError(ctx.error.message) &&
+    !isImageRecoveryAttempted(ctx.conversationId)
+  ) {
+    markImageRecoveryAttempted(ctx.conversationId);
+    ctx.messages = recoverOversizedImages(ctx.messages);
+    // Make the downgrade durable so the rejected image can't rehydrate from the
+    // stored row and re-reject on later turns. This is cleanup for future
+    // turns, so a persistence failure must never abort the retry that is about
+    // to run — log it and continue with the in-memory recovery.
+    try {
+      const rewritten = persistUnsendableImageDowngrades(ctx.conversationId);
+      if (rewritten > 0) {
+        ctx.logger.info(
+          { plugin: "image-recovery", rewritten },
+          "Persisted unsendable-image downgrades so they cannot resurface",
+        );
+      }
+    } catch (err) {
+      ctx.logger.warn(
+        { plugin: "image-recovery", err },
+        "Failed to persist unsendable-image downgrade; continuing with in-memory recovery",
+      );
+    }
+    ctx.decision = "continue";
+    ctx.logger.warn(
+      { plugin: "image-recovery", messageCount: ctx.messages.length },
+      "Provider image-too-large error — recovering oversized image blocks and retrying",
+    );
+  }
+};
+
+export default postModelCall;

package/src/plugins/defaults/image-recovery/hooks/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `stop` hook: clears the per-conversation image-recovery bound when a
+ * turn terminates.
+ *
+ * The `post-model-call` hook (see `./post-model-call.ts`) marks the bound when
+ * it downscales an oversized image and asks the loop to retry. `stop` is the
+ * definitive terminal hook — it fires exactly once when the turn is truly
+ * ending, after every retry decision has been made — so clearing the bound here
+ * unconditionally guarantees the next turn always recovers afresh, no matter how
+ * the turn ended (a finalized reply, an unrecovered rejection, an abort, or a
+ * retry the loop's per-run backstop refused).
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { clearImageRecoveryAttempted } from "../image-recovery-state-store.js";
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  clearImageRecoveryAttempted(ctx.conversationId);
+};
+
+export default stop;

package/src/plugins/defaults/image-recovery/image-recovery-state-store.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-conversation image-recovery state for the default image-recovery module.
+ *
+ * The `stop` hook recovers from a provider image-too-large rejection by
+ * downscaling the oversized image blocks and asking the loop to retry. That
+ * recovery is bounded to one pass per turn: a second consecutive image-too-large
+ * rejection means the downscale could not get the image under the provider's
+ * cap, so the hook lets the error surface rather than looping.
+ *
+ * The `stop` hook owns this state end-to-end. It marks a conversation when it
+ * issues a recovery-retry and clears the mark on any terminal stop — a
+ * successful response, a non-image rejection, or an exhausted second
+ * image-too-large rejection — i.e. whenever the loop is leaving rather than
+ * retrying. A conversation therefore only holds an entry while a recovery is in
+ * flight, so the store stays bounded without a separate teardown step.
+ *
+ * This module is side-effect free: importing it only initializes an empty store
+ * and registers no plugin.
+ */
+
+/** Conversations with an image-recovery pass in flight for the current turn. */
+const recoveryInFlight = new Set<string>();
+
+/** Whether the conversation already attempted an image recovery this turn. */
+export function isImageRecoveryAttempted(conversationId: string): boolean {
+  return recoveryInFlight.has(conversationId);
+}
+
+/** Record that the conversation issued its one image-recovery retry this turn. */
+export function markImageRecoveryAttempted(conversationId: string): void {
+  recoveryInFlight.add(conversationId);
+}
+
+/**
+ * Clear the conversation's recovery mark so the next turn (or run) recovers
+ * afresh. The `stop` hook calls this on every terminal stop.
+ */
+export function clearImageRecoveryAttempted(conversationId: string): void {
+  recoveryInFlight.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's recovery state so a suite that drives the
+ * hook directly starts each case from an empty store.
+ */
+export function resetImageRecoveryStoreForTests(): void {
+  recoveryInFlight.clear();
+}

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

@@ -0,0 +1,14 @@
+{
+  "name": "default-image-recovery",
+  "version": "1.0.0",
+  "description": "First-party default plugin that recovers from provider image-too-large rejections by downscaling oversized image blocks and retrying.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/{daemon/persist-unsendable-image.ts → plugins/defaults/image-recovery/recover.ts}

@@ -1,26 +1,28 @@
 /**
- * Persistence for the image-too-large recovery path.
+ * Image-too-large recovery transforms for the image-recovery plugin.
  *
  * When the provider rejects a turn because an attached image exceeds its
- * limits, the agent loop downgrades the offending image blocks in memory and
- * retries. That transformation is transient — the stored message row keeps the
- * full-size image block, so the rejected image is rehydrated on every later
- * turn and keeps re-entering the model's context. This module makes the
- * downgrade durable: the oversized block is rewritten to its downscaled form,
- * or to a text note when it cannot be shrunk on this host, so a rejected image
- * cannot resurface and re-reject on every later turn.
+ * limits, the `stop` hook downgrades the offending image blocks in the working
+ * history and asks the loop to retry. {@link recoverOversizedImages} performs
+ * that in-memory transform for the immediate retry; {@link
+ * persistUnsendableImageDowngrades} makes the same downgrade durable, because
+ * the stored message row otherwise keeps the full-size image block and the
+ * rejected image rehydrates on every later turn and keeps re-entering the
+ * model's context. The durable rewrite replaces the oversized block with its
+ * downscaled form, or with a text note when it cannot be shrunk on this host,
+ * so a rejected image cannot resurface and re-reject on every later turn.
  */
 
-import { optimizeImageForTransport } from "../agent/image-optimize.js";
-import { parseImageDimensions } from "../context/image-dimensions.js";
+import { optimizeImageForTransport } from "../../../agent/image-optimize.js";
+import { parseImageDimensions } from "../../../context/image-dimensions.js";
 import {
   getMessages,
   updateMessageContent,
-} from "../memory/conversation-crud.js";
-import type { ContentBlock } from "../providers/types.js";
-import { getLogger } from "../util/logger.js";
+} from "../../../memory/conversation-crud.js";
+import type { ContentBlock, Message } from "../../../providers/types.js";
+import { getLogger } from "../../../util/logger.js";
 
-const log = getLogger("persist-unsendable-image");
+const log = getLogger("image-recovery");
 
 // Anthropic rejects any image whose longest side exceeds this many pixels,
 // regardless of payload size. Mirrors the user-facing message surfaced by
@@ -152,3 +154,54 @@ export function persistUnsendableImageDowngrades(
   }
   return rewritten;
 }
+
+/**
+ * True when a message's content holds an image the provider may have rejected
+ * for being oversized — either a top-level image block (user upload) or one
+ * nested inside a tool_result's contentBlocks (e.g. a browser screenshot).
+ */
+function messageHasImageBlock(content: ReadonlyArray<ContentBlock>): boolean {
+  return content.some(
+    (b) =>
+      b.type === "image" ||
+      (b.type === "tool_result" &&
+        (b.contentBlocks?.some((cb) => cb.type === "image") ?? false)),
+  );
+}
+
+/**
+ * Downscale every oversized image in the working history for an immediate
+ * retry, leaving still-sendable images untouched. Recovers both top-level image
+ * blocks (user uploads) and images nested inside a tool_result's contentBlocks
+ * (e.g. a browser screenshot) in place, so the tool_use/tool_result pairing
+ * stays intact rather than dropping the whole tool_result. Applies the same
+ * provider-cap gate as {@link persistUnsendableImageDowngrades} so the in-memory
+ * retry and the durable rewrite agree on which images are unsendable.
+ */
+export function recoverOversizedImages(
+  messages: ReadonlyArray<Message>,
+): Message[] {
+  return messages.map((msg) => {
+    if (!Array.isArray(msg.content)) return msg;
+    if (!messageHasImageBlock(msg.content)) return msg;
+    return {
+      ...msg,
+      content: msg.content.flatMap((b): ContentBlock[] => {
+        if (b.type === "image") {
+          return [oversizedImageReplacement(b) ?? b];
+        }
+        if (b.type === "tool_result" && b.contentBlocks?.length) {
+          return [
+            {
+              ...b,
+              contentBlocks: b.contentBlocks.map((cb) =>
+                cb.type === "image" ? (oversizedImageReplacement(cb) ?? cb) : cb,
+              ),
+            },
+          ];
+        }
+        return [b];
+      }),
+    };
+  });
+}

package/src/plugins/defaults/index.ts

@@ -27,10 +27,22 @@
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
 import compactionPkg from "./compaction/package.json" with { type: "json" };
+import emptyResponsePostModelCall from "./empty-response/hooks/post-model-call.js";
 import emptyResponseStop from "./empty-response/hooks/stop.js";
+import { resetEmptyResponseNudgeStoreForTests } from "./empty-response/nudge-state-store.js";
 import emptyResponsePkg from "./empty-response/package.json" with { type: "json" };
+import historyRepairPostModelCall from "./history-repair/hooks/post-model-call.js";
+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 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";
+import imageRecoveryPkg from "./image-recovery/package.json" with { type: "json" };
+import memoryRetrievalPostCompact from "./memory-retrieval/hooks/post-compact.js";
+import memoryRetrievalUserPromptSubmit from "./memory-retrieval/hooks/user-prompt-submit.js";
+import memoryRetrievalPkg from "./memory-retrieval/package.json" with { type: "json" };
 import memoryV3PostCompact from "./memory-v3-shadow/hooks/post-compact.js";
 import memoryV3UserPromptSubmit from "./memory-v3-shadow/hooks/user-prompt-submit.js";
 import memoryV3Pkg from "./memory-v3-shadow/package.json" with { type: "json" };
@@ -57,8 +69,10 @@ export const defaultCompactionPlugin: Plugin = {
 };
 
 /**
- * `empty-response` — a `stop` hook that re-queries the model when a turn
- * yields with no tool calls but came back empty (or as a provider refusal).
+ * `empty-response` — a `post-model-call` hook that re-queries the model when a
+ * turn yields with no tool calls but came back empty (or as a provider
+ * refusal); the `stop` hook clears the one-shot nudge bound on a terminal stop
+ * so the next run nudges afresh.
  */
 export const defaultEmptyResponsePlugin: Plugin = {
   manifest: {
@@ -66,14 +80,39 @@ export const defaultEmptyResponsePlugin: Plugin = {
     version: emptyResponsePkg.version,
   },
   hooks: {
+    "post-model-call": emptyResponsePostModelCall,
     stop: emptyResponseStop,
   },
 };
 
 /**
- * `history-repair` — a `user-prompt-submit` hook that normalizes the working
- * message history (tool-use/tool-result pairing, role alternation) before the
- * agent loop hands it to the provider.
+ * `memory-retrieval` — assembles the turn's runtime injections (the unified
+ * `<turn_context>` block, Slack chronological transcript, NOW.md / PKB /
+ * memory-v2 / workspace blocks) via two hooks: `user-prompt-submit` runs
+ * memory-graph retrieval and the initial injection, and `post-compact`
+ * re-applies the injections onto the compacted history after a mid-turn
+ * compaction. Registered first in the chain so later `user-prompt-submit`
+ * hooks (history repair, title) see the fully memory-injected history.
+ */
+export const defaultMemoryRetrievalPlugin: Plugin = {
+  manifest: {
+    name: memoryRetrievalPkg.name,
+    version: memoryRetrievalPkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": memoryRetrievalUserPromptSubmit,
+    "post-compact": memoryRetrievalPostCompact,
+  },
+};
+
+/**
+ * `history-repair` — normalizes the working message history (tool-use/tool-result
+ * pairing, role alternation). The `user-prompt-submit` hook normalizes the
+ * history before each provider call; the `post-model-call` hook handles the
+ * provider rejection where the call failed on an ordering violation,
+ * deep-repairing the history and asking the loop to retry; the `stop` hook
+ * clears the one-shot repair bound on a terminal stop so the next turn repairs
+ * afresh.
  */
 export const defaultHistoryRepairPlugin: Plugin = {
   manifest: {
@@ -82,6 +121,28 @@ export const defaultHistoryRepairPlugin: Plugin = {
   },
   hooks: {
     "user-prompt-submit": historyRepairUserPromptSubmit,
+    "post-model-call": historyRepairPostModelCall,
+    stop: historyRepairStop,
+  },
+};
+
+/**
+ * `image-recovery` — recovers from a provider image-too-large rejection. The
+ * `post-model-call` hook handles the rejection, downscaling the oversized image
+ * blocks in the working history and asking the loop to retry, and persisting
+ * the same downgrade durably so the rejected image cannot rehydrate from the
+ * stored row and re-reject on later turns; the `stop` hook clears the one-shot
+ * recovery bound on a terminal stop so the next turn recovers afresh. Bounded
+ * to one pass per turn.
+ */
+export const defaultImageRecoveryPlugin: Plugin = {
+  manifest: {
+    name: imageRecoveryPkg.name,
+    version: imageRecoveryPkg.version,
+  },
+  hooks: {
+    "post-model-call": imageRecoveryPostModelCall,
+    stop: imageRecoveryStop,
   },
 };
 
@@ -156,10 +217,12 @@ export const defaultToolResultTruncatePlugin: Plugin = {
  */
 function getAllDefaultPlugins(): readonly Plugin[] {
   return [
+    defaultMemoryRetrievalPlugin,
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
     defaultHistoryRepairPlugin,
+    defaultImageRecoveryPlugin,
     defaultCompactionPlugin,
     defaultTitleGeneratePlugin,
     memoryV3ShadowPlugin,
@@ -202,5 +265,8 @@ export function registerDefaultPlugins(): void {
  */
 export function resetPluginRegistryAndRegisterDefaults(): void {
   resetPluginRegistryForTests();
+  resetEmptyResponseNudgeStoreForTests();
+  resetRepairStateStoreForTests();
+  resetImageRecoveryStoreForTests();
   registerDefaultPlugins();
 }