@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/plugin-api/types.ts

@@ -4,7 +4,11 @@
  * removing is breaking and gated on a major bump.
  */
 
-import type { Message } from "../providers/types.js";
+import type {
+  ContentBlock,
+  Message,
+  ToolResultContent,
+} from "../providers/types.js";
 
 export type {
   ToolContext,
@@ -34,6 +38,24 @@ export interface PluginLogger {
   debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
+// ─── Hook function ───────────────────────────────────────────────────────────
+
+/**
+ * A plugin lifecycle hook. Receives a per-lifecycle context shape and
+ * may return either a transformed context or `void`. Today's runtime
+ * consumes only the resolved-or-rejected nature of the promise; the
+ * `TCtx` return is reserved for hooks that fan a transformed context out
+ * to downstream plugins (e.g. `user-prompt-submit`).
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link PluginInitContext}
+ *   - `shutdown` — {@link PluginShutdownContext}
+ *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `post-tool-use` — {@link PostToolUseContext}
+ *   - `stop` — {@link StopContext}
+ */
+export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
+
 // ─── Init context ────────────────────────────────────────────────────────────
 
 /**
@@ -83,9 +105,9 @@ export interface PluginShutdownContext {
 /**
  * Context passed to the `user-prompt-submit` hook. Fires once per user
  * turn, after the agent loop has prepared the message list (PKB / NOW /
- * memory-graph injections, history repair, overflow reduction all already
- * applied) and immediately before the messages are handed to the agent
- * loop's tool/LLM iteration.
+ * memory-graph injections, overflow reduction all already applied) and
+ * immediately before the messages are handed to the agent loop's tool/LLM
+ * iteration.
  *
  * The hook may transform `latestMessages` either by mutating it in place
  * (`push` / `splice` / `length = 0`) or by returning a new context with
@@ -105,6 +127,16 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * The text of the user prompt that triggered this turn — the resolved
+   * user message (after slash-command expansion), independent of any
+   * internal rewriting applied to the message that flows into the model.
+   * Mirrors the `prompt` field Claude Code / Codex pass to their
+   * `UserPromptSubmit` hooks, so hooks that key off the submitted text
+   * (e.g. title generation) read it directly rather than reconstructing
+   * it from the message arrays.
+   */
+  readonly prompt: string;
   /**
    * The user's original message list, immutable for the hook. Plugins
    * may snapshot or compare against this but MUST NOT mutate it.
@@ -115,4 +147,144 @@ export interface UserPromptSubmitContext {
    * may mutate this in place or replace it by returning a new context.
    */
   latestMessages: Message[];
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}
+
+// ─── Post-tool-use hook context ──────────────────────────────────────────────
+
+/**
+ * Context passed to the `post-tool-use` hook. Fires once per tool result —
+ * after the tool returns and before the result is appended to the message
+ * history sent to the provider. With several tools dispatched in a single
+ * turn, the hook fires once per result, in tool-use order.
+ *
+ * The hook may transform the result either by mutating `toolResponse` in
+ * place (e.g. reassigning `toolResponse.content`) or by returning a new
+ * context with a fresh `toolResponse` — see {@link PluginHookFn}'s
+ * polymorphic return shape. The daemon threads the final `toolResponse`
+ * into the provider-bound history.
+ *
+ * Multiple plugins' hooks chain in registration order — each plugin's hook
+ * sees the previous plugin's mutations. The default tool-result-truncate
+ * plugin contributes a hook here that tail-drops oversized output to fit the
+ * model's context window; the default tool-error plugin sets
+ * {@link additionalContext} with retry coaching for failed results. User hooks
+ * can swap in a smarter strategy (e.g. a summarizer) or observe results for
+ * side effects.
+ */
+export interface PostToolUseContext {
+  /** Conversation ID the tool ran on. */
+  readonly conversationId: string;
+  /**
+   * The tool result block. Plugins may mutate its `content` in place or
+   * replace the block by returning a new context.
+   */
+  toolResponse: ToolResultContent;
+  /**
+   * Conversation history up to and including the assistant turn that issued
+   * this tool call. The current result is not in it yet — it lives in
+   * {@link toolResponse}. A hook reasoning about prior tool outcomes (e.g.
+   * how many times a tool has failed in a row) derives that from the history
+   * content rather than a precomputed counter, so the signal survives mid-run
+   * compaction rewriting the array. Read-only: hooks transform the result via
+   * {@link toolResponse}, not by mutating history.
+   */
+  readonly messages: ReadonlyArray<Message>;
+  /**
+   * Extra guidance for the model that is not part of the tool's output. A hook
+   * sets this to surface provider-only context — e.g. retry coaching for a
+   * failed result — and the daemon appends it to the provider-bound history as
+   * a separate block *after* emitting the tool_result, so it reaches the model
+   * without polluting the client-facing or persisted tool output. Mirrors
+   * Claude Code's PostToolUse `hookSpecificOutput.additionalContext` and the
+   * singular of Codex's `additional_contexts`. Unset means no extra context.
+   */
+  additionalContext?: string;
+  /**
+   * 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
+   * receiving a precomputed limit.
+   */
+  readonly maxInputTokens: number;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}
+
+// ─── Stop hook context ───────────────────────────────────────────────────────
+
+/**
+ * Binary outcome of the `stop` hook. The agent loop seeds it to `"stop"`
+ * and acts on the value the chain settles on:
+ *
+ * - `"stop"`     — let the turn end; the loop yields the assistant response
+ *                  to the user. This is the default.
+ * - `"continue"` — re-query the model. The hook is responsible for appending
+ *                  the follow-up turn it wants the model to see to
+ *                  {@link StopContext.messages} before returning.
+ *
+ * To abort with an error a hook should throw — the loop's error handler
+ * surfaces it. There is intentionally no error decision value.
+ */
+export type StopDecision = "continue" | "stop";
+
+/**
+ * Context passed to the `stop` hook. Fires when the model yields a response
+ * with no tool calls — the run's stop boundary, where the loop is about to
+ * hand the turn back to the user. The default empty-response plugin uses it
+ * to re-query the model when a turn came back empty or as a provider refusal.
+ *
+ * The hook decides the outcome by setting {@link decision}. When it sets
+ * `"continue"` it must also append the follow-up turn (e.g. a nudge `user`
+ * message) to {@link messages}; the loop threads those messages into the next
+ * iteration. {@link messages} is the full conversation history, carried back
+ * verbatim. A hook that needs to reason about just the current response cycle
+ * (e.g. whether an earlier turn already delivered visible text) derives that
+ * boundary from the history itself — the messages after the last genuine user
+ * prompt — rather than an index, since mid-run compaction can rewrite the
+ * array.
+ *
+ * Multiple plugins' hooks chain in registration order — each sees the
+ * previous hook's `decision` and `messages` mutations.
+ */
+export interface StopContext {
+  /** Conversation ID the run belongs to. */
+  readonly conversationId: string;
+  /**
+   * Full conversation history: the inbound conversation followed by every
+   * message produced this run. A hook that sets `decision` to `"continue"`
+   * appends its follow-up turn here; the loop carries the result into the
+   * next iteration.
+   */
+  messages: Message[];
+  /**
+   * Content blocks of the assistant turn that triggered the stop. Guaranteed
+   * to contain no `tool_use` blocks — the hook only fires at the boundary
+   * where the model stopped requesting tools.
+   */
+  readonly responseContent: ReadonlyArray<ContentBlock>;
+  /**
+   * Provider-reported stop reason for the assistant turn (e.g. `"refusal"`,
+   * `"end_turn"`). `null`/`undefined` when the provider didn't report one.
+   */
+  readonly stopReason: string | null | undefined;
+  /**
+   * Seeded to `"stop"`. A hook sets it to `"continue"` to force another loop
+   * iteration; later hooks in the chain may override it.
+   */
+  decision: StopDecision;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
 }

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

@@ -0,0 +1,59 @@
+/**
+ * Default compaction implementation.
+ *
+ * Summarizes conversation history when the context window fills up by
+ * delegating to a {@link ContextWindowManager}. The agent loop calls
+ * {@link defaultCompact} directly with a {@link CompactionContext}; the request
+ * carries the conversational inputs while the manager performs the work.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ */
+
+import type {
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../../../context/window-manager.js";
+import type { Message } from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+
+/**
+ * Name under which the default compaction plugin registers. Exposed so call
+ * sites can attribute compaction failures to the default plugin.
+ */
+export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
+
+/**
+ * Self-describing compaction request handed to {@link defaultCompact}. Carries
+ * the conversational inputs plus the {@link ContextWindowManager} that runs the
+ * summary, so the request is the part that can grow toward a model-facing
+ * compaction-method shape without coupling callers to the manager's option bag.
+ */
+export interface CompactionContext {
+  /** Context window manager that performs the compaction. */
+  manager: ContextWindowManager;
+  /** Message history to consider for compaction. */
+  messages: Message[];
+  /** Abort signal forwarded to the compaction summary call. */
+  signal?: AbortSignal;
+  /** Skip the auto-threshold check (forced/overflow/emergency compaction). */
+  force?: boolean;
+  /** Per-conversation inference-profile override for the summary call. */
+  overrideProfile?: string | null;
+  /** Pre-computed token estimate from a prior `shouldCompact()` call. */
+  precomputedEstimate?: number;
+  /** Legacy keep-boundary hint forwarded to the compactor. */
+  minKeepRecentUserTurns?: number;
+  /** Trust class of the actor whose turn triggered compaction. */
+  actorTrustClass?: TrustClass;
+}
+
+/**
+ * Run compaction for the turn: delegates to the request's context window
+ * manager and returns the (possibly summarized) message history.
+ */
+export async function defaultCompact(
+  context: CompactionContext,
+): Promise<ContextWindowResult> {
+  const { manager, messages, signal, ...options } = context;
+  return manager.maybeCompact(messages, signal, options);
+}

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

@@ -0,0 +1,15 @@
+{
+  "name": "default-compaction",
+  "version": "1.0.0",
+  "description": "First-party default plugin providing the assistant's built-in conversation-history compaction.",
+  "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,24 @@
+/**
+ * Default `compaction` plugin.
+ *
+ * Compaction is implemented in `./compact.ts` as {@link defaultCompact}, which
+ * the agent loop calls directly with a {@link CompactionContext}. The plugin
+ * stays registered as a placeholder so it keeps a presence in the defaults
+ * list while we decide how plugins should surface compaction; it contributes
+ * no contract slot today.
+ */
+
+import { type Plugin } from "../../types.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Manifest 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,
+  },
+};

package/src/plugins/defaults/empty-response/hooks/stop.ts

@@ -0,0 +1,126 @@
+/**
+ * Default `stop` hook: when the model yields a turn with no tool calls, decide
+ * whether to let the turn end or re-query the model with a nudge.
+ *
+ * Two cases warrant a nudge:
+ *
+ * 1. **Refusal stop.** The provider returned `stopReason === "refusal"` with no
+ *    visible text (Anthropic's safety classifier zeroed the response). Nudged
+ *    even on the first model call of the run — a refusal there guarantees no
+ *    organic text exists yet, so without intervening the loop would persist an
+ *    empty assistant bubble to the user. Uses `REFUSAL_NUDGE_TEXT`.
+ * 2. **Empty turn after tool use.** The turn produced no visible text, follows
+ *    at least one prior assistant turn this run, and no earlier turn this run
+ *    already delivered visible text. Uses `NUDGE_TEXT`.
+ *
+ * Every other case leaves the decision at `"stop"` (the model said its piece,
+ * or there is nothing to nudge about). The retry cap is owned by the agent
+ * loop: this hook always asks to continue when a nudge is warranted, and the
+ * loop stops anyway once the run's nudge budget is spent.
+ *
+ * Both prior-turn signals are derived from the current response cycle — the
+ * messages after the last genuine user prompt (a user turn that isn't purely
+ * tool results). Scoping this way keeps prior conversation turns from polluting
+ * the signals, and deriving the boundary from history content rather than an
+ * index means mid-run compaction (which rewrites the array in place) can't
+ * invalidate it. A prior assistant turn this cycle implies a completed tool-use
+ * iteration (an empty turn nudges-and-continues without pushing an assistant
+ * message), so "a prior assistant turn exists" is the equivalent of "this is
+ * not the first model call".
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `stop` chain — later hooks see (and may override) its decision.
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical nudge text for an empty turn after tool use. Must stay verbatim so
+ * a plugin that wraps the default sees a stable string.
+ *
+ * Wire-compat note: this is shown to the LLM, not the user. Edits here affect
+ * model behavior but not end-user UX directly.
+ */
+export 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"` and no
+ * visible text — 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 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>';
+
+function hasVisibleText(content: ReadonlyArray<ContentBlock>): boolean {
+  return content.some(
+    (block) => block.type === "text" && block.text.trim().length > 0,
+  );
+}
+
+function isAssistantTurn(message: Message): boolean {
+  return message.role === "assistant";
+}
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/**
+ * Messages belonging to the current response cycle: everything after the last
+ * genuine user prompt. Falls back to the whole history when none is found.
+ */
+function currentCycleMessages(
+  messages: ReadonlyArray<Message>,
+): ReadonlyArray<Message> {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "user" && !isToolResultMessage(message)) {
+      return messages.slice(i + 1);
+    }
+  }
+  return messages;
+}
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  const turnHasVisibleText = hasVisibleText(ctx.responseContent);
+
+  const appendNudge = (text: string): void => {
+    ctx.messages.push({ role: "user", content: [{ type: "text", text }] });
+    ctx.decision = "continue";
+  };
+
+  if (ctx.stopReason === "refusal" && !turnHasVisibleText) {
+    appendNudge(REFUSAL_NUDGE_TEXT);
+    return;
+  }
+
+  const cycleMessages = currentCycleMessages(ctx.messages);
+  const priorAssistantTurns = cycleMessages.filter(isAssistantTurn);
+  const hadPriorAssistantTurn = priorAssistantTurns.length > 0;
+  const priorAssistantHadVisibleText = priorAssistantTurns.some((message) =>
+    hasVisibleText(message.content),
+  );
+
+  const isEmptyTurnAfterTools =
+    !turnHasVisibleText &&
+    hadPriorAssistantTurn &&
+    !priorAssistantHadVisibleText;
+
+  if (isEmptyTurnAfterTools) {
+    appendNudge(NUDGE_TEXT);
+  }
+};
+
+export default stop;

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,23 @@
+/**
+ * Default `empty-response` plugin.
+ *
+ * Contributes 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). The decision
+ * logic lives in `./hooks/stop.ts`. Defaults register before user plugins, so
+ * this runs at the front of the `stop` hook chain.
+ */
+
+import { type Plugin } from "../../types.js";
+import stop from "./hooks/stop.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,
+  },
+  hooks: {
+    stop,
+  },
+};

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