@vellumai/assistant 0.8.6 → 0.8.7

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

package/src/plugins/defaults/index.ts

@@ -7,47 +7,45 @@
  *
  * Consumers:
  *
- * - `daemon/external-plugins-bootstrap.ts` — production/registry boot path;
- *   calls {@link registerDefaultPlugins} inside `bootstrapPlugins()`.
+ * - `daemon/external-plugins-bootstrap.ts` — the daemon's `initializePlugins()`
+ *   calls {@link registerDefaultPlugins} explicitly at startup, before
+ *   `loadUserPlugins()` closes the registration window, so the defaults compose
+ *   innermost (ahead of any user plugins). `bootstrapPlugins()` replays it;
+ *   idempotent, so already-registered defaults are skipped.
  * - integration tests that reset the registry and then need a
  *   production-parity state (e.g. `conversation-agent-loop.test.ts`); those
  *   call {@link resetPluginRegistryAndRegisterDefaults}.
  *
- * Each `defaults/<name>.ts` module self-registers at module load via a local
- * side effect. Importing this aggregator (or any individual default file)
- * populates the registry — the self-registration is idempotent, and so are
- * {@link registerDefaultPlugins} and {@link resetPluginRegistryAndRegisterDefaults}.
- * Per-file self-registration is what keeps registration attached to each
- * file's own already-initialized plugin identifier, so importing
- * `defaults/index.ts` mid-cycle (e.g. through the
- * `memory-retrieval.ts` → … → `pipeline.ts` → `defaults/index.ts`
- * chain) does not trip a TDZ.
+ * Each `defaults/<name>/register.ts` module only builds and exports its
+ * `Plugin` object; registration is centralized here. The plugin identifiers
+ * are dereferenced inside {@link registerDefaultPlugins} at call time, once
+ * every module has finished initializing, so importing this aggregator does no
+ * registration work.
  */
 
-import { memoryV3ShadowPlugin } from "../../memory/v3/shadow-middleware.js";
+import { memoryV3ShadowPlugin } from "../../memory/v3/shadow-plugin.js";
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
-import { defaultCircuitBreakerPlugin } from "./circuit-breaker.js";
-import { defaultCompactionPlugin } from "./compaction.js";
-import { defaultEmptyResponsePlugin } from "./empty-response.js";
-import { defaultHistoryRepairPlugin } from "./history-repair.js";
-import { defaultInjectorsPlugin } from "./injectors.js";
-import { defaultLlmCallPlugin } from "./llm-call.js";
-import { defaultMemoryRetrievalPlugin } from "./memory-retrieval.js";
-import { defaultOverflowReducePlugin } from "./overflow-reduce.js";
-import { defaultPersistencePlugin } from "./persistence.js";
-import { defaultTitleGeneratePlugin } from "./title-generate.js";
-import { defaultTokenEstimatePlugin } from "./token-estimate.js";
-import { defaultToolErrorPlugin } from "./tool-error.js";
-import { defaultToolExecutePlugin } from "./tool-execute.js";
-import { defaultToolResultTruncatePlugin } from "./tool-result-truncate.js";
+import { defaultCircuitBreakerPlugin } from "./circuit-breaker/register.js";
+import { defaultCompactionPlugin } from "./compaction/register.js";
+import { defaultEmptyResponsePlugin } from "./empty-response/register.js";
+import { defaultHistoryRepairPlugin } from "./history-repair/register.js";
+import { defaultInjectorsPlugin } from "./injectors/register.js";
+import { defaultLlmCallPlugin } from "./llm-call/register.js";
+import { defaultMemoryRetrievalPlugin } from "./memory-retrieval/register.js";
+import { defaultOverflowReducePlugin } from "./overflow-reduce/register.js";
+import { defaultPersistencePlugin } from "./persistence/register.js";
+import { defaultTitleGeneratePlugin } from "./title-generate/register.js";
+import { defaultTokenEstimatePlugin } from "./token-estimate/register.js";
+import { defaultToolErrorPlugin } from "./tool-error/register.js";
+import { defaultToolExecutePlugin } from "./tool-execute/register.js";
+import { defaultToolResultTruncatePlugin } from "./tool-result-truncate/register.js";
 
 /**
  * Full set of first-party default plugins. Used by
- * {@link registerDefaultPlugins} to drive the idempotent re-registration
- * loop; actual registration-order in the registry is determined by the
- * module-load side effects in each per-file default (whichever loader
- * evaluates a file first wins, later attempts are swallowed as duplicates).
+ * {@link registerDefaultPlugins} to drive the registration loop; the array
+ * order is the registration order, which determines onion order for middleware
+ * composition (defaults innermost, user plugins outermost).
  *
  * Returned by a function rather than a top-level `const` so the array
  * contents are read at call time, after every imported plugin identifier is
@@ -61,11 +59,6 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
     defaultMemoryRetrievalPlugin,
-    // Live-shadow v3 retrieval. Always registered; inert unless both
-    // `memory.v3.enabled` and `memory.v3.shadow` are on (gated inside the
-    // middleware). Ordered after the default so the default terminal still
-    // produces the injected (v2) `MemoryResult`.
-    memoryV3ShadowPlugin,
     defaultInjectorsPlugin,
     defaultTokenEstimatePlugin,
     defaultOverflowReducePlugin,
@@ -74,6 +67,7 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultCircuitBreakerPlugin,
     defaultPersistencePlugin,
     defaultTitleGeneratePlugin,
+    memoryV3ShadowPlugin,
   ];
 }
 
@@ -83,11 +77,6 @@ function getAllDefaultPlugins(): readonly Plugin[] {
  * an "already registered" message) are swallowed so repeat bootstrap or test
  * setup calls do not throw. Every other error (shape failure, version
  * mismatch) re-throws.
- *
- * In practice every call after the first is a no-op: each default's
- * module-load side effect registers itself the first time its file is
- * imported, which for production happens via `pipeline.ts`'s side-effect
- * import of this aggregator.
  */
 export function registerDefaultPlugins(): void {
   for (const plugin of getAllDefaultPlugins()) {

package/src/plugins/defaults/injectors/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-injectors",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in injectors 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/{injectors.ts → injectors/register.ts}

@@ -39,30 +39,28 @@
  * sorted ascending, so a plugin-registered injector at `order: 25`
  * reliably slots between `unified-turn-context` (20) and `pkb` (30).
  *
- * Registration happens via a module-load side effect at the bottom of this
- * file — importing the module is enough to populate the registry. The
- * explicit `registerDefaultPlugins()` call in `plugins/defaults/index.ts`
- * (invoked from `daemon/external-plugins-bootstrap.ts`) re-registers the
- * same plugin idempotently, so either entry point alone is sufficient.
+ * This module only builds and exports the `Plugin` object; the defaults
+ * aggregator in `plugins/defaults/index.ts` registers it centrally, either
+ * explicitly from `daemon/external-plugins-bootstrap.ts` or lazily via the
+ * registry's default registrar the first time a query reads the registry.
  */
 
 import { resolve } from "node:path";
 
-import { getConfig } from "../../config/loader.js";
-import { getInContextPkbPaths } from "../../daemon/pkb-context-tracker.js";
-import { buildPkbReminder } from "../../daemon/pkb-reminder-builder.js";
-import { listComments } from "../../documents/document-comments-store.js";
-import { searchPkbFiles } from "../../memory/pkb/pkb-search.js";
-import { getLogger } from "../../util/logger.js";
-import { registerPlugin } from "../registry.js";
+import { getConfig } from "../../../config/loader.js";
+import { getInContextPkbPaths } from "../../../daemon/pkb-context-tracker.js";
+import { buildPkbReminder } from "../../../daemon/pkb-reminder-builder.js";
+import { listComments } from "../../../documents/document-comments-store.js";
+import { searchPkbFiles } from "../../../memory/pkb/pkb-search.js";
+import { getLogger } from "../../../util/logger.js";
 import {
   type InjectionBlock,
   type Injector,
   type Plugin,
-  PluginExecutionError,
   type TurnContext,
   type TurnInjectionInputs,
-} from "../types.js";
+} from "../../types.js";
+import pkg from "./package.json" with { type: "json" };
 
 const pkbReminderLog = getLogger("pkb-reminder");
 
@@ -686,8 +684,8 @@ const threadFocusInjector: Injector = {
  */
 export const defaultInjectorsPlugin: Plugin = {
   manifest: {
-    name: "default-injectors",
-    version: "1.0.0",
+    name: pkg.name,
+    version: pkg.version,
   },
   injectors: [
     diskPressureWarningInjector,
@@ -705,25 +703,3 @@ export const defaultInjectorsPlugin: Plugin = {
     threadFocusInjector,
   ],
 };
-
-// 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 `defaultInjectorsPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultInjectorsPlugin);
-} 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/llm-call/middlewares/llmCall.ts

@@ -0,0 +1,17 @@
+import type { LLMCallArgs, LLMCallResult, Middleware } from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `llmCall` pipeline. Forwards to `next(args)`
+ * unchanged so any user-registered middleware (registered later, inner in the
+ * onion) still runs and the terminal at the call site (`agent/loop.ts`)
+ * performs the actual `provider.sendMessage(...)` call.
+ *
+ * Defaults register at the OUTERMOST onion position; forwarding
+ * unconditionally keeps user-registered middleware reachable.
+ */
+const defaultLlmCall: Middleware<LLMCallArgs, LLMCallResult> =
+  async function defaultLlmCall(args, next, _ctx) {
+    return next(args);
+  };
+
+export default defaultLlmCall;

package/src/plugins/defaults/llm-call/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-llm-call",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in llm-call 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/{llm-call.ts → llm-call/register.ts}

@@ -20,13 +20,9 @@
  * Design doc: `.private/plans/agent-plugin-system.md` (PR 15).
  */
 
-import { registerPlugin } from "../registry.js";
-import {
-  type LLMCallArgs,
-  type LLMCallResult,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
+import { type Plugin } from "../../types.js";
+import llmCall from "./middlewares/llmCall.js";
+import pkg from "./package.json" with { type: "json" };
 
 /**
  * The default LLM-call plugin. Its `llmCall` middleware is a passthrough that
@@ -40,38 +36,10 @@ import {
  */
 export const defaultLlmCallPlugin: Plugin = {
   manifest: {
-    name: "default-llm-call",
-    version: "1.0.0",
+    name: pkg.name,
+    version: pkg.version,
   },
   middleware: {
-    llmCall: async function defaultLlmCall(
-      args: LLMCallArgs,
-      next,
-      _ctx,
-    ): Promise<LLMCallResult> {
-      return next(args);
-    },
+    llmCall,
   },
 };
-
-// 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 `defaultLlmCallPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultLlmCallPlugin);
-} 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;
-  }
-}