@vellumai/assistant 0.8.5 → 0.8.7

package/src/plugins/defaults/circuit-breaker/middlewares/circuitBreaker.ts

@@ -0,0 +1,93 @@
+import type {
+  CircuitBreakerArgs,
+  CircuitBreakerResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Consecutive failures required to trip the breaker. Matches the legacy
+ * `COMPACTION_CIRCUIT_FAILURE_THRESHOLD` in `conversation-agent-loop.ts`.
+ */
+export const COMPACTION_CIRCUIT_FAILURE_THRESHOLD = 3;
+
+/**
+ * Cooldown window after the breaker trips, during which auto-compaction is
+ * suspended. Matches the legacy `COMPACTION_CIRCUIT_COOLDOWN_MS`.
+ */
+export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
+
+/**
+ * Default middleware for the `circuitBreaker` pipeline. A thin wrapper over the
+ * state container passed in `CircuitBreakerArgs.state`:
+ *
+ * - `{ key }` — query. Defers to `next` for the current
+ *   `{ open, cooldownRemainingMs? }`.
+ * - `{ key, outcome }` — update state based on outcome, then defer to `next`
+ *   for the post-update decision. A run of three failures trips the breaker;
+ *   any non-failure outcome resets both the counter and the cooldown timestamp.
+ *
+ * Event emission preserves the existing `trackCompactionOutcome` behavior:
+ * `compaction_circuit_open` fires once when the counter first reaches the
+ * threshold while the circuit is dormant; `compaction_circuit_closed` fires
+ * only on the open→closed transition.
+ */
+const circuitBreaker: Middleware<CircuitBreakerArgs, CircuitBreakerResult> =
+  async function circuitBreaker(args, next) {
+    const { outcome, state, onEvent } = args;
+
+    // Update branch — mutate state first, then defer to the downstream
+    // chain (or terminal) for the decision so outer observers still see
+    // the fully-processed outcome. Separating state mutation from
+    // decision computation also keeps this middleware composable: an
+    // outer plugin may wrap the invocation to observe both the pre-update
+    // args and the post-update result.
+    if (outcome !== undefined) {
+      if (outcome === "failure") {
+        state.consecutiveCompactionFailures += 1;
+        // Treat a stale/expired open-until timestamp the same as null so
+        // a new 3-strike window can re-open the circuit after the prior
+        // cooldown elapses. Without this, subsequent trips would no-op
+        // because `compactionCircuitOpenUntil` remains set to a past
+        // timestamp even though the breaker is effectively closed.
+        const circuitDormant =
+          state.compactionCircuitOpenUntil === null ||
+          Date.now() >= state.compactionCircuitOpenUntil;
+        if (
+          state.consecutiveCompactionFailures >=
+            COMPACTION_CIRCUIT_FAILURE_THRESHOLD &&
+          circuitDormant
+        ) {
+          const openUntil = Date.now() + COMPACTION_CIRCUIT_COOLDOWN_MS;
+          state.compactionCircuitOpenUntil = openUntil;
+          if (onEvent) {
+            onEvent({
+              type: "compaction_circuit_open",
+              conversationId: state.conversationId,
+              reason: "3_consecutive_failures",
+              openUntil,
+            });
+          }
+        }
+      } else {
+        // Emit only on the open→closed transition; firing on the common
+        // closed→closed case would be noise.
+        const wasOpen = state.compactionCircuitOpenUntil !== null;
+        state.consecutiveCompactionFailures = 0;
+        state.compactionCircuitOpenUntil = null;
+        if (wasOpen && onEvent) {
+          onEvent({
+            type: "compaction_circuit_closed",
+            conversationId: state.conversationId,
+          });
+        }
+      }
+    }
+
+    // Defer to downstream (the terminal, in the default registration, but
+    // potentially another plugin in a customized chain) for the final
+    // decision. The terminal's implementation is the canonical read of
+    // the (now-updated) state container.
+    return next(args);
+  };
+
+export default circuitBreaker;

package/src/plugins/defaults/circuit-breaker/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-circuit-breaker",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in circuit-breaker pipeline with a passthrough implementation.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/circuit-breaker/register.ts

@@ -0,0 +1,39 @@
+/**
+ * Default `circuitBreaker` plugin.
+ *
+ * Replicates the inline compaction circuit-breaker logic that previously
+ * lived in `daemon/conversation-agent-loop.ts`: three consecutive summary-LLM
+ * failures open the circuit for a one-hour cooldown, and any successful
+ * compaction resets the counter.
+ *
+ * The plugin is a thin wrapper over the state container passed in
+ * `CircuitBreakerArgs.state`. The {@link Conversation} owns the underlying
+ * fields (`consecutiveCompactionFailures`, `compactionCircuitOpenUntil`)
+ * because dev-only playground routes (`POST /playground/reset-compaction-circuit`,
+ * `POST /playground/inject-compaction-failures`) read and mutate them
+ * directly. Keeping ownership on the conversation lets this plugin stay a
+ * pure wrapper while preserving those hatches.
+ *
+ * The `key` parameter is carried through for multi-circuit futures but the
+ * default plugin currently bundles all circuit state into the `state`
+ * container; the key is attached to the log record via the pipeline runner.
+ */
+
+import { type Plugin } from "../../types.js";
+import circuitBreaker from "./middlewares/circuitBreaker.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Default plugin registered at daemon startup. Consumers negotiate against
+ * `circuitBreakerApi@v1` via the registry's capability table.
+ */
+export const defaultCircuitBreakerPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+
+  middleware: {
+    circuitBreaker,
+  },
+};

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

@@ -0,0 +1,25 @@
+import type {
+  CompactionArgs,
+  CompactionResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `compaction` pipeline. Forwards to
+ * `next(args)` so any custom plugins layered outside still run; when this is
+ * the only middleware, `next` is the terminal handler (`../terminal.ts`) and
+ * returns the real compaction output.
+ *
+ * Defaults register at the OUTERMOST onion position, so deciding here without
+ * calling `next` would shadow every later-registered plugin. Routing through
+ * `next(args)` lets user middleware participate normally.
+ */
+const defaultCompactionMiddleware: Middleware<
+  CompactionArgs,
+  CompactionResult
+> = async function defaultCompaction(args, next, ctx) {
+  void ctx;
+  return next(args);
+};
+
+export default defaultCompactionMiddleware;

package/src/plugins/defaults/compaction/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-compaction",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in compaction pipeline with a passthrough implementation.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Default `compaction` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual compaction lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * the `runPipeline` call site in `daemon/conversation-agent-loop.ts`. This
+ * separation matters: the default plugin is registered before any user plugin
+ * (defaults load first in `bootstrapPlugins()`), which puts it at the
+ * OUTERMOST position of the onion chain. If the default middleware were to
+ * invoke the terminal directly without calling `next`, it would shadow every
+ * later-registered plugin. Routing through `next(args)` lets user middleware
+ * participate normally.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
+ */
+
+import { type Plugin } from "../../types.js";
+import defaultCompactionMiddleware from "./middlewares/compaction.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Manifest + middleware wiring for the default compaction plugin. The
+ * registration happens in `daemon/external-plugins-bootstrap.ts` before
+ * {@link bootstrapPlugins} fires plugin `init()` hooks.
+ */
+export const defaultCompactionPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    compaction: defaultCompactionMiddleware,
+  },
+};

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

@@ -0,0 +1,73 @@
+/**
+ * Default `compaction` behavior: summarizes conversation history when the
+ * context window fills up.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to the orchestrator's existing {@link ContextWindowManager}
+ * instance, read from `ctx.contextWindowManager` on the {@link TurnContext} as
+ * a typed optional field. The orchestrator is responsible for attaching that
+ * handle to the per-turn context. If the handle is missing, this throws a
+ * {@link PluginExecutionError} so the bug surfaces with clear attribution
+ * instead of a late `undefined.maybeCompact is not a function`.
+ */
+
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../../../context/window-manager.js";
+import type { Message } from "../../../providers/types.js";
+import {
+  type CompactionArgs,
+  type CompactionResult,
+  PluginExecutionError,
+  type TurnContext,
+} from "../../types.js";
+
+/**
+ * Name under which the default plugin registers. Exposed so tests and later
+ * plugins can assert registration order or override the default via
+ * composition.
+ */
+export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
+
+/**
+ * Read `contextWindowManager` off the turn context. Throws
+ * {@link PluginExecutionError} when absent so the failure attributes cleanly
+ * to the default plugin instead of manifesting as a later NPE.
+ */
+function extractManager(ctx: TurnContext): ContextWindowManager {
+  const manager = ctx.contextWindowManager;
+  if (
+    manager == null ||
+    typeof manager !== "object" ||
+    typeof (manager as { maybeCompact?: unknown }).maybeCompact !== "function"
+  ) {
+    throw new PluginExecutionError(
+      "default-compaction: ctx.contextWindowManager is missing — orchestrator must attach it before invoking compaction",
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
+  return manager;
+}
+
+/**
+ * Run compaction for the turn: reads the context window manager off the turn
+ * context and returns the (possibly summarized) message history from
+ * `maybeCompact`.
+ */
+export async function defaultCompactionTerminal(
+  args: CompactionArgs,
+  ctx: TurnContext,
+): Promise<CompactionResult> {
+  const manager = extractManager(ctx);
+  const messages = args.messages as Message[];
+  const options = args.options as ContextWindowCompactOptions | undefined;
+  const result: ContextWindowResult = await manager.maybeCompact(
+    messages,
+    args.signal,
+    options,
+  );
+  return result;
+}

package/src/plugins/defaults/empty-response/middlewares/emptyResponse.ts

@@ -0,0 +1,22 @@
+import type {
+  EmptyResponseArgs,
+  EmptyResponseResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `emptyResponse` pipeline. Forwards to
+ * `next(args)` unchanged; the actual empty-response decision lives in the
+ * terminal handler (`../terminal.ts`), wired in at the `runPipeline` call site
+ * in `agent/loop.ts`.
+ *
+ * Defaults register at the OUTERMOST onion position, so deciding here without
+ * calling `next` would shadow every later-registered plugin. Routing through
+ * `next(args)` lets user middleware participate normally.
+ */
+const passthrough: Middleware<EmptyResponseArgs, EmptyResponseResult> = async (
+  args,
+  next,
+) => next(args);
+
+export default passthrough;

package/src/plugins/defaults/empty-response/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-empty-response",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in empty-response pipeline with a passthrough implementation.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/empty-response/register.ts

@@ -0,0 +1,28 @@
+/**
+ * Default `emptyResponse` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual decision lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * the `runPipeline` call site in `agent/loop.ts`. This separation matters: the
+ * default plugin is registered before any user plugin (defaults load first in
+ * `bootstrapPlugins()`), which puts it at the OUTERMOST position of the onion
+ * chain. If the default middleware were to decide directly without calling
+ * `next`, it would shadow every later-registered plugin. Routing through
+ * `next(args)` lets user middleware participate normally.
+ */
+
+import { type Plugin } from "../../types.js";
+import emptyResponse from "./middlewares/emptyResponse.js";
+import pkg from "./package.json" with { type: "json" };
+
+/** Singleton plugin — the registry rejects duplicate registrations by name. */
+export const defaultEmptyResponsePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    emptyResponse,
+  },
+};

package/src/plugins/defaults/empty-response/terminal.ts

@@ -0,0 +1,106 @@
+/**
+ * Default `emptyResponse` behavior: decides whether an empty assistant turn
+ * should be nudged (re-queried) or accepted.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * The handler inspects the turn snapshot and returns one of:
+ *
+ * 1. `"nudge"`  — fired in two distinct shapes:
+ *                 (a) **Post-tool empty.** The turn produced no visible text,
+ *                     no tool calls, follows at least one prior tool-use turn,
+ *                     no earlier turn in this run() has already delivered
+ *                     visible text, AND the retry counter is below
+ *                     `maxEmptyResponseRetries`. Uses `NUDGE_TEXT`.
+ *                 (b) **Refusal stop.** The provider returned
+ *                     `stopReason === "refusal"` with no visible text and no
+ *                     tool calls (Anthropic's safety classifier). Nudges even
+ *                     on turn 0 / before any tool use, because a refusal on
+ *                     the first model call of the run is a hard guarantee
+ *                     that no organic text exists yet — without intervening
+ *                     we'd persist an empty assistant bubble to the user.
+ *                     Uses the refusal-specific `REFUSAL_NUDGE_TEXT`. The
+ *                     retry cap still applies; after `maxEmptyResponseRetries`
+ *                     refusals in a row the terminal falls through to accept.
+ *                 The loop appends the chosen `nudgeText` as a `user` turn
+ *                 and re-queries the model.
+ * 2. `"accept"` — every other case. The turn either legitimately ended
+ *                 (model said its piece earlier), is still in progress
+ *                 (tool calls pending), or exhausted its retry budget. The
+ *                 loop pushes the assistant message and continues normally.
+ *
+ * The default never returns `"error"` — that action is an escape hatch for
+ * downstream plugins (e.g. a circuit breaker) that want to surface an
+ * explicit error instead of silently absorbing an empty turn.
+ *
+ * `MAX_EMPTY_RESPONSE_RETRIES` lives in `agent/loop.ts` and is passed in via
+ * `EmptyResponseArgs.maxEmptyResponseRetries` so the cap is declared in one
+ * place only.
+ */
+
+import type { EmptyResponseArgs, EmptyResponseResult } from "../../types.js";
+
+/**
+ * Canonical nudge text. Must stay verbatim so a plugin that wraps the
+ * default cannot accidentally see a different string.
+ *
+ * Wire-compat note: this is shown to the LLM, not the user. Edits here
+ * affect model behavior but not end-user UX directly.
+ */
+const NUDGE_TEXT =
+  "<system_notice>Your previous response was empty. You must respond to the user with a summary of what you found or did. Do not use any tools — just respond with text.</system_notice>";
+
+/**
+ * Refusal-specific nudge. Used when the provider stops with `"refusal"`
+ * before any tool use — i.e. the safety classifier zeroed the response.
+ * Kept distinct from `NUDGE_TEXT` so the model gets context-appropriate
+ * guidance (no "summary of what you found or did" — there is no tool
+ * trail to summarize on a turn-0 refusal).
+ *
+ * Wire-compat note: this is shown to the LLM, not the user. Edits here
+ * affect retry behavior but not end-user UX directly.
+ */
+export const REFUSAL_NUDGE_TEXT =
+  '<system_notice>Your previous response was empty because the upstream provider returned stop_reason="refusal". Please answer the user\'s last message directly with a plain-text response. Do not use any tools — just respond with text.</system_notice>';
+
+/**
+ * Decide whether an empty turn should be nudged or accepted. Exported so the
+ * agent loop can call it directly and tests can verify the decision logic.
+ */
+export function defaultEmptyResponseTerminal(
+  args: EmptyResponseArgs,
+): EmptyResponseResult {
+  const hasVisibleText = args.responseContent.some(
+    (block) =>
+      block.type === "text" &&
+      typeof (block as { text?: unknown }).text === "string" &&
+      (block as { text: string }).text.trim().length > 0,
+  );
+
+  // Refusal stop with zero usable content — the provider's safety
+  // classifier zeroed the response. Nudge regardless of toolUseTurns or
+  // priorAssistantHadVisibleText: a `"refusal"` stop with no visible
+  // text and no tool calls IS the failure mode this branch exists to
+  // catch (otherwise we persist an empty assistant bubble to the user).
+  // Still respect the retry cap so a persistent classifier doesn't
+  // burn turns indefinitely.
+  const isRefusal =
+    args.stopReason === "refusal" &&
+    !hasVisibleText &&
+    args.toolUseBlocksLength === 0;
+
+  if (isRefusal && args.emptyResponseRetries < args.maxEmptyResponseRetries) {
+    return { action: "nudge", nudgeText: REFUSAL_NUDGE_TEXT };
+  }
+
+  const isEmptyTurn =
+    !hasVisibleText &&
+    args.toolUseBlocksLength === 0 &&
+    args.toolUseTurns > 0 &&
+    !args.priorAssistantHadVisibleText;
+
+  if (isEmptyTurn && args.emptyResponseRetries < args.maxEmptyResponseRetries) {
+    return { action: "nudge", nudgeText: NUDGE_TEXT };
+  }
+  return { action: "accept" };
+}

package/src/plugins/defaults/history-repair/hooks/user-prompt-submit.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `user-prompt-submit` hook: normalizes the working message history so
+ * it satisfies the provider's tool-use/tool-result pairing and role-alternation
+ * rules before the agent loop hands it to the provider.
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `user-prompt-submit` chain — every later hook sees an already-normalized
+ * history. The hook mutates `latestMessages` in place by reassigning it to the
+ * repaired list.
+ */
+
+import type {
+  PluginHookFn,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import { repairHistory } from "../terminal.js";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+  const { messages, stats } = repairHistory(ctx.latestMessages);
+  ctx.latestMessages = messages;
+  if (
+    stats.assistantToolResultsMigrated > 0 ||
+    stats.missingToolResultsInserted > 0 ||
+    stats.orphanToolResultsDowngraded > 0 ||
+    stats.consecutiveSameRoleMerged > 0
+  ) {
+    ctx.logger.warn(
+      { plugin: "history-repair", phase: "pre_run", ...stats },
+      "Repaired runtime history before provider call",
+    );
+  }
+};
+
+export default userPromptSubmit;

package/src/plugins/defaults/history-repair/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-history-repair",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in history-repair pipeline with a passthrough implementation.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Default `history-repair` plugin.
+ *
+ * Contributes 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. The repair implementation lives in
+ * `./terminal.ts`; the hook in `./hooks/user-prompt-submit.ts` wires it into
+ * the lifecycle. Defaults register before user plugins, so this normalization
+ * runs at the front of the hook chain.
+ */
+
+import { type Plugin } from "../../types.js";
+import userPromptSubmit from "./hooks/user-prompt-submit.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const defaultHistoryRepairPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": userPromptSubmit,
+  },
+};

package/src/{daemon/history-repair.ts → plugins/defaults/history-repair/terminal.ts}

@@ -1,19 +1,32 @@
+/**
+ * Default `history-repair` behavior: the implementation that normalizes a
+ * message history so it satisfies the provider's tool-use/tool-result pairing
+ * and role-alternation rules.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ * `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.
+ */
+
 import type {
   ContentBlock,
   Message,
   ServerToolUseContent,
   ToolResultContent,
   ToolUseContent,
-} from "../providers/types.js";
+} from "../../../providers/types.js";
 
-export interface RepairStats {
+interface RepairStats {
   assistantToolResultsMigrated: number;
   missingToolResultsInserted: number;
   orphanToolResultsDowngraded: number;
   consecutiveSameRoleMerged: number;
 }
 
-export interface RepairResult {
+interface RepairResult {
   messages: Message[];
   stats: RepairStats;
 }
@@ -280,38 +293,6 @@ function buildResultMessage(
   };
 }
 
-/**
- * Aggressive repair pass that handles edge cases beyond repairHistory:
- * - Removes empty messages
- * - Ensures the first message is from the user
- * - Merges consecutive same-role messages (before tool-use/result repair)
- * Then applies the standard repairHistory on top (which also merges any
- * consecutive same-role messages introduced by tool-use/result repair).
- */
-export function deepRepairHistory(messages: Message[]): RepairResult {
-  // 1. Remove messages with no content blocks
-  let cleaned = messages.filter((m) => m.content.length > 0);
-
-  // 2. Strip leading assistant messages (provider requires user-first)
-  while (cleaned.length > 0 && cleaned[0].role === "assistant") {
-    cleaned = cleaned.slice(1);
-  }
-
-  // 3. Merge consecutive same-role messages
-  const merged: Message[] = [];
-  for (const msg of cleaned) {
-    const prev = merged[merged.length - 1];
-    if (prev && prev.role === msg.role) {
-      prev.content = [...prev.content, ...msg.content];
-    } else {
-      merged.push({ role: msg.role, content: [...msg.content] });
-    }
-  }
-
-  // 4. Apply standard tool-use/tool-result repair on top
-  return repairHistory(merged);
-}
-
 function downgradeResult(tr: {
   type: string;
   tool_use_id: string;
@@ -351,3 +332,35 @@ function formatWebSearchContent(content: unknown): string {
   }
   return "results unavailable";
 }
+
+/**
+ * Aggressive repair pass that handles edge cases beyond repairHistory:
+ * - Removes empty messages
+ * - Ensures the first message is from the user
+ * - Merges consecutive same-role messages (before tool-use/result repair)
+ * Then applies the standard repairHistory on top (which also merges any
+ * consecutive same-role messages introduced by tool-use/result repair).
+ */
+export function deepRepairHistory(messages: Message[]): RepairResult {
+  // 1. Remove messages with no content blocks
+  let cleaned = messages.filter((m) => m.content.length > 0);
+
+  // 2. Strip leading assistant messages (provider requires user-first)
+  while (cleaned.length > 0 && cleaned[0].role === "assistant") {
+    cleaned = cleaned.slice(1);
+  }
+
+  // 3. Merge consecutive same-role messages
+  const merged: Message[] = [];
+  for (const msg of cleaned) {
+    const prev = merged[merged.length - 1];
+    if (prev && prev.role === msg.role) {
+      prev.content = [...prev.content, ...msg.content];
+    } else {
+      merged.push({ role: msg.role, content: [...msg.content] });
+    }
+  }
+
+  // 4. Apply standard tool-use/tool-result repair on top
+  return repairHistory(merged);
+}