@vellumai/assistant 0.6.5 → 0.6.6

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

package/src/plugins/defaults/index.ts

@@ -0,0 +1,116 @@
+/**
+ * Aggregate export of the first-party default plugins.
+ *
+ * Each default wraps one of the assistant's built-in pipelines with a
+ * passthrough implementation so the pipeline shape is always explicit at boot
+ * and at test time, even when no third-party plugins are loaded.
+ *
+ * Consumers:
+ *
+ * - `daemon/external-plugins-bootstrap.ts` — production/registry boot path;
+ *   calls {@link registerDefaultPlugins} inside `bootstrapPlugins()`.
+ * - 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.
+ */
+
+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";
+
+/**
+ * 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).
+ *
+ * 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
+ * guaranteed initialized.
+ */
+export function getAllDefaultPlugins(): readonly Plugin[] {
+  return [
+    defaultLlmCallPlugin,
+    defaultToolExecutePlugin,
+    defaultToolResultTruncatePlugin,
+    defaultEmptyResponsePlugin,
+    defaultToolErrorPlugin,
+    defaultMemoryRetrievalPlugin,
+    defaultInjectorsPlugin,
+    defaultTokenEstimatePlugin,
+    defaultOverflowReducePlugin,
+    defaultHistoryRepairPlugin,
+    defaultCompactionPlugin,
+    defaultCircuitBreakerPlugin,
+    defaultPersistencePlugin,
+    defaultTitleGeneratePlugin,
+  ];
+}
+
+/**
+ * Register every first-party default plugin. Idempotent — duplicate-name
+ * registrations (which the registry surfaces as `PluginExecutionError` with
+ * 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()) {
+    try {
+      registerPlugin(plugin);
+    } catch (err) {
+      if (
+        err instanceof PluginExecutionError &&
+        err.message.includes("already registered")
+      ) {
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Test-only helper: clear the plugin registry and re-register every default
+ * so integration tests that exercise the full agent loop have a
+ * production-parity plugin stack. Use this in `beforeEach` of tests that
+ * dispatch through pipelines with a terminal that assumes the default
+ * plugin handles every op (e.g. persistence, overflowReduce).
+ *
+ * Tests that specifically need an empty registry (pipeline-unit tests, the
+ * plugin-registry tests themselves) should continue to call
+ * {@link resetPluginRegistryForTests} directly.
+ */
+export function resetPluginRegistryAndRegisterDefaults(): void {
+  resetPluginRegistryForTests();
+  registerDefaultPlugins();
+}