@vellumai/assistant 0.6.4 → 0.6.6

package/src/permissions/web-risk-classifier.ts

@@ -0,0 +1,89 @@
+/**
+ * Web risk classifier — domain and method-based risk classification.
+ *
+ * Implements RiskClassifier<WebClassifierInput> for web-related tools:
+ * web_search, web_fetch, and network_request.
+ *
+ * - web_search: always Low (read-only)
+ * - web_fetch: High if allowPrivateNetwork, Low otherwise
+ * - network_request: always Medium (proxied credentials)
+ */
+
+import type { RiskAssessment, RiskClassifier } from "./risk-types.js";
+
+// ── Input type ───────────────────────────────────────────────────────────────
+
+/** Input to the web risk classifier. */
+export interface WebClassifierInput {
+  /** Which web tool is being invoked. */
+  toolName: "web_fetch" | "network_request" | "web_search";
+  /** The target URL (informational, not used for classification yet). */
+  url?: string;
+  /** Whether the fetch is allowed to reach private/internal networks. */
+  allowPrivateNetwork?: boolean;
+}
+
+// ── Classifier ───────────────────────────────────────────────────────────────
+
+/**
+ * Web risk classifier implementation.
+ *
+ * Classifies web tool invocations by tool type and flags. This is the
+ * simplest classifier — no registry lookups, no subcommand resolution,
+ * just direct conditional logic matching the original checker.ts behavior.
+ */
+export class WebRiskClassifier implements RiskClassifier<WebClassifierInput> {
+  async classify(input: WebClassifierInput): Promise<RiskAssessment> {
+    const { toolName, allowPrivateNetwork } = input;
+
+    // NOTE: We intentionally do NOT produce allowlistOptions here.
+    // The canonical URL normalization logic (normalizeWebFetchUrl in
+    // checker.ts) handles edge cases (path-only inputs, host:port
+    // shorthand, non-http schemes) that our simplified normalizeUrl()
+    // does not. Importing the canonical version would create a circular
+    // dependency. By omitting allowlistOptions, we let the fallback
+    // urlAllowlistStrategy in generateAllowlistOptions() handle scope
+    // option generation using the canonical normalization.
+
+    switch (toolName) {
+      case "web_search":
+        return {
+          riskLevel: "low",
+          reason: "Web search (read-only)",
+          scopeOptions: [],
+          matchType: "registry",
+        };
+
+      case "web_fetch":
+        // Private-network fetches are High risk so that blanket allow rules
+        // (including the starter bundle) cannot silently bypass the prompt.
+        if (allowPrivateNetwork === true) {
+          return {
+            riskLevel: "high",
+            reason: "Private network fetch",
+            scopeOptions: [],
+            matchType: "registry",
+          };
+        }
+        return {
+          riskLevel: "low",
+          reason: "Web fetch (default)",
+          scopeOptions: [],
+          matchType: "registry",
+        };
+
+      case "network_request":
+        // Proxy-authenticated network requests are Medium risk — they carry
+        // injected credentials and the user should approve the target host/origin.
+        return {
+          riskLevel: "medium",
+          reason: "Network request (proxied credentials)",
+          scopeOptions: [],
+          matchType: "registry",
+        };
+    }
+  }
+}
+
+/** Singleton classifier instance. */
+export const webRiskClassifier = new WebRiskClassifier();

package/src/permissions/workspace-policy.ts

@@ -1,6 +1,8 @@
 import { realpathSync } from "node:fs";
 import { basename, dirname, normalize, resolve } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
+
 /**
  * Resolve a path to its canonical form. When the target itself doesn't
  * exist (e.g. a new file being written), walk up to the nearest existing
@@ -54,22 +56,7 @@ export function isPathWithinWorkspaceRoot(
 const PATH_SCOPED_TOOLS = new Set(["file_read", "file_write", "file_edit"]);
 
 /** Network-accessing tools — never workspace-scoped. */
-const NETWORK_TOOLS = new Set([
-  "web_search",
-  "web_fetch",
-  "browser_navigate",
-  "browser_click",
-  "browser_type",
-  "browser_scroll",
-  "browser_select_option",
-  "browser_hover",
-  "browser_screenshot",
-  "browser_close",
-  "browser_attach",
-  "browser_detach",
-  "browser_status",
-  "network_request",
-]);
+const NETWORK_TOOLS = new Set(["web_search", "web_fetch", "network_request"]);
 
 /** Host-level tools — operate outside the sandbox, never workspace-scoped. */
 const HOST_TOOLS = new Set([
@@ -127,9 +114,12 @@ export function isWorkspaceScopedInvocation(
     );
   }
 
-  // Bash is generally workspace-scoped when sandbox isolation is active —
-  // the caller handles network mode checks separately.
-  if (toolName === "bash") return true;
+  // Bash workspace scope depends on the environment: containerized bash has the
+  // entire filesystem as workspace, so it's always workspace-scoped. Non-containerized
+  // bash is NOT workspace-scoped here — path resolution for allowlisted commands is
+  // handled upstream in the checker's hasSandboxAutoApprove computation, which validates
+  // all path arguments against the workspace root for non-containerized environments.
+  if (toolName === "bash") return getIsContainerized();
 
   // Unknown tool — conservative default.
   return false;

package/src/platform/client.ts

@@ -9,6 +9,11 @@ import { getPlatformAssistantId } from "../config/env.js";
 import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("platform-client");
+
+let _missingPrereqsWarned = false;
 
 export class VellumPlatformClient {
   private readonly platformBaseUrl: string;
@@ -66,7 +71,20 @@ export class VellumPlatformClient {
         )?.trim() ?? "";
     }
 
-    if (!baseUrl || !apiKey) return null;
+    if (!baseUrl || !apiKey) {
+      const level = _missingPrereqsWarned ? "debug" : "warn";
+      _missingPrereqsWarned = true;
+      log[level](
+        {
+          hasBaseUrl: !!baseUrl,
+          hasApiKey: !!apiKey,
+          hasAssistantId: !!assistantId,
+          managedProxyEnabled: ctx.enabled,
+        },
+        "Platform client prerequisites missing — returning null",
+      );
+      return null;
+    }
 
     return new VellumPlatformClient(baseUrl, apiKey, assistantId);
   }

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

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ *
+ * Semantics — query vs update:
+ * - `{ key }` — query. Returns the current `{ open, cooldownRemainingMs? }`.
+ * - `{ key, outcome }` — update state based on outcome, then return 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:
+ * - Emits `compaction_circuit_open` exactly once when the counter first
+ *   reaches the threshold and the circuit is dormant (null or expired).
+ * - Emits `compaction_circuit_closed` only on the open→closed transition.
+ *   Successive successful outcomes while the circuit is already closed emit
+ *   nothing (would otherwise spam the client).
+ *
+ * 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 { registerPlugin } from "../registry.js";
+import { type Plugin, PluginExecutionError } 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 plugin registered at daemon startup. Consumers negotiate against
+ * `circuitBreakerApi@v1` via the registry's capability table.
+ */
+export const defaultCircuitBreakerPlugin: Plugin = {
+  manifest: {
+    name: "default-circuit-breaker",
+    version: "1.0.0",
+    provides: { circuitBreakerApi: "v1" },
+    requires: {
+      pluginRuntime: "v1",
+      circuitBreakerApi: "v1",
+    },
+  },
+
+  middleware: {
+    circuitBreaker: async (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);
+    },
+  },
+};
+
+// Module-load side effect: register this default at import time so
+// downstream consumers (including tests that skip `bootstrapPlugins()`)
+// observe a populated registry by default. Idempotent via the swallowed
+// duplicate-name check. Kept local to this module (rather than iterating
+// an array in `defaults/index.ts`) so the registration only references
+// the already-initialized `defaultCircuitBreakerPlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultCircuitBreakerPlugin);
+} catch (err) {
+  if (
+    err instanceof PluginExecutionError &&
+    err.message.includes("already registered")
+  ) {
+    // already registered — expected when both index.ts and the direct
+    // file are imported in the same process
+  } else {
+    throw err;
+  }
+}

package/src/plugins/defaults/compaction.ts

@@ -0,0 +1,145 @@
+/**
+ * Default `compaction` plugin.
+ *
+ * Delegates to the orchestrator's existing
+ * {@link import("../../context/window-manager.js").ContextWindowManager}
+ * instance. No behavior change relative to the pre-plugin call site — the
+ * plugin only exists so custom plugins registered in later PRs can observe
+ * arguments, short-circuit to a different summary, or post-process the
+ * {@link import("../../context/window-manager.js").ContextWindowResult}
+ * before the orchestrator consumes it.
+ *
+ * Lookup: the default middleware reads `ctx.contextWindowManager` from the
+ * {@link TurnContext} as a typed optional field. The orchestrator is
+ * responsible for attaching that handle to the per-turn context it hands to
+ * {@link runPipeline}. If the handle is missing, the middleware throws a
+ * {@link PluginExecutionError} so the bug surfaces with clear attribution
+ * instead of a late `undefined.maybeCompact is not a function`.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
+ */
+
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../../context/window-manager.js";
+import type { Message } from "../../providers/types.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type CompactionArgs,
+  type CompactionResult,
+  type Middleware,
+  type Plugin,
+  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 the compaction pipeline",
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
+  return manager;
+}
+
+/**
+ * Default terminal behavior. Exposed as a standalone function (rather than
+ * inlined in the plugin object) so the orchestrator can pass it directly to
+ * {@link runPipeline} as the terminal handler. Keeping terminal-vs-middleware
+ * separate avoids a wasted `next → terminal` hop when no custom plugin
+ * observes the slot.
+ */
+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;
+}
+
+/**
+ * Middleware wrapper around {@link defaultCompactionTerminal}. Registered via
+ * {@link defaultCompactionPlugin} so tests that compose middleware through the
+ * registry (rather than passing a terminal to `runPipeline` directly) see a
+ * working no-op default. In production the orchestrator passes
+ * {@link defaultCompactionTerminal} as the terminal and this middleware is
+ * never hit.
+ */
+const defaultCompactionMiddleware: Middleware<
+  CompactionArgs,
+  CompactionResult
+> = async function defaultCompaction(args, next, ctx) {
+  // Invoke `next` so any custom plugins layered outside us still run; when
+  // we're the only middleware, `next` is the terminal and returns the real
+  // compaction output.
+  void ctx;
+  return next(args);
+};
+
+/**
+ * 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: DEFAULT_COMPACTION_PLUGIN_NAME,
+    version: "1.0.0",
+    requires: {
+      pluginRuntime: "v1",
+      compactionApi: "v1",
+    },
+  },
+  middleware: {
+    compaction: defaultCompactionMiddleware,
+  },
+};
+
+// Module-load side effect: register this default at import time so
+// downstream consumers (including tests that skip `bootstrapPlugins()`)
+// observe a populated registry by default. Idempotent via the swallowed
+// duplicate-name check. Kept local to this module (rather than iterating
+// an array in `defaults/index.ts`) so the registration only references
+// the already-initialized `defaultCompactionPlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultCompactionPlugin);
+} catch (err) {
+  if (
+    err instanceof PluginExecutionError &&
+    err.message.includes("already registered")
+  ) {
+    // already registered — expected when both index.ts and the direct
+    // file are imported in the same process
+  } else {
+    throw err;
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Default `emptyResponse` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual decision lives in
+ * {@link defaultEmptyResponseTerminal}, 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.
+ *
+ * Wiring the terminal at the call site (rather than relying on the plugin to
+ * be registered) also means the loop's nudge/accept/error behavior survives
+ * configurations that boot without the default plugin — e.g. unit tests that
+ * skip `bootstrapPlugins()`.
+ *
+ * The terminal inspects the turn snapshot and returns one of:
+ *
+ * 1. `"nudge"`  — 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`. The loop
+ *                 appends `nudgeText` (the `<system_notice>…` message below)
+ *                 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 threaded into
+ * the pipeline via `EmptyResponseArgs.maxEmptyResponseRetries` so the cap is
+ * declared in one place only.
+ */
+
+import { registerPlugin } from "../registry.js";
+import {
+  type EmptyResponseArgs,
+  type EmptyResponseResult,
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+} 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>";
+
+/**
+ * Terminal handler for the `emptyResponse` pipeline. Exported so tests can
+ * verify default behavior directly without going through `runPipeline`, and
+ * so `agent/loop.ts` can pass it as the `terminal` argument to `runPipeline`.
+ */
+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,
+  );
+
+  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" };
+}
+
+const passthrough: Middleware<EmptyResponseArgs, EmptyResponseResult> = async (
+  args,
+  next,
+) => next(args);
+
+/** Singleton plugin — the registry rejects duplicate registrations by name. */
+export const defaultEmptyResponsePlugin: Plugin = {
+  manifest: {
+    name: "default-empty-response",
+    version: "1.0.0",
+    provides: { emptyResponseApi: "v1" },
+    requires: { pluginRuntime: "v1", emptyResponseApi: "v1" },
+  },
+  middleware: {
+    emptyResponse: passthrough,
+  },
+};
+
+// Module-load side effect: register this default at import time so
+// downstream consumers (including tests that skip `bootstrapPlugins()`)
+// observe a populated registry by default. Idempotent via the swallowed
+// duplicate-name check. Kept local to this module (rather than iterating
+// an array in `defaults/index.ts`) so the registration only references
+// the already-initialized `defaultEmptyResponsePlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultEmptyResponsePlugin);
+} catch (err) {
+  if (
+    err instanceof PluginExecutionError &&
+    err.message.includes("already registered")
+  ) {
+    // already registered — expected when both index.ts and the direct
+    // file are imported in the same process
+  } else {
+    throw err;
+  }
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Default `historyRepair` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual repair lives in
+ * {@link defaultHistoryRepairTerminal}, which is wired in as the pipeline's
+ * `terminal` argument by `runPipeline` call sites 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.
+ *
+ * Plugins that override this middleware receive both `history` and `provider`
+ * so they can route behavior per provider (e.g. strip blocks a specific
+ * provider can't handle) without reaching into ambient state.
+ *
+ * Scope: this pipeline wraps only the standard pre-run repair (`repairHistory`).
+ * The orchestrator's one-shot deep-repair fallback (`deepRepairHistory`),
+ * invoked only after a provider ordering error, intentionally bypasses the
+ * pipeline today — see the design note at the `deepRepairHistory` call site
+ * in `daemon/conversation-agent-loop.ts`.
+ */
+
+import { repairHistory } from "../../daemon/history-repair.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type HistoryRepairArgs,
+  type HistoryRepairResult,
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+} from "../types.js";
+
+/**
+ * Terminal handler for the `historyRepair` pipeline. Exported so tests can
+ * verify default behavior directly without going through `runPipeline`, and
+ * so `daemon/conversation-agent-loop.ts` can pass it as the `terminal`
+ * argument to `runPipeline`.
+ */
+export function defaultHistoryRepairTerminal(
+  args: HistoryRepairArgs,
+): HistoryRepairResult {
+  return repairHistory(args.history);
+}
+
+const passthrough: Middleware<HistoryRepairArgs, HistoryRepairResult> = async (
+  args,
+  next,
+) => next(args);
+
+export const defaultHistoryRepairPlugin: Plugin = {
+  manifest: {
+    name: "default-history-repair",
+    version: "1.0.0",
+    provides: { historyRepair: "v1" },
+    requires: { pluginRuntime: "v1", historyRepairApi: "v1" },
+  },
+  middleware: {
+    historyRepair: passthrough,
+  },
+};
+
+// Module-load side effect: register this default at import time so
+// downstream consumers (including tests that skip `bootstrapPlugins()`)
+// observe a populated registry by default. Idempotent via the swallowed
+// duplicate-name check. Kept local to this module (rather than iterating
+// an array in `defaults/index.ts`) so the registration only references
+// the already-initialized `defaultHistoryRepairPlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultHistoryRepairPlugin);
+} catch (err) {
+  if (
+    err instanceof PluginExecutionError &&
+    err.message.includes("already registered")
+  ) {
+    // already registered — expected when both index.ts and the direct
+    // file are imported in the same process
+  } else {
+    throw err;
+  }
+}