@vellumai/assistant 0.6.5 → 0.7.0

package/src/plugins/defaults/token-estimate.ts

@@ -0,0 +1,103 @@
+/**
+ * Default `tokenEstimate` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual estimate lives in
+ * {@link defaultTokenEstimateTerminal}, 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. The
+ * passthrough lets user middleware that wraps the default (e.g. a doubler, a
+ * provider-native `countTokens` override) participate normally.
+ *
+ * The terminal delegates to
+ * {@link import("../../context/token-estimator.js").estimatePromptTokens estimatePromptTokens},
+ * which applies the EWMA calibration correction recorded from past provider
+ * responses. Preflight + mid-loop checks must use the calibrated estimate —
+ * the calibrated value keeps the overflow gate consistent with the
+ * convergence path in the reducer. The pre-send
+ * calibration capture in `agent/loop.ts` still uses `estimatePromptTokensRaw`
+ * on purpose — the calibrator must learn against the raw estimate so the EWMA
+ * converges against provider ground truth rather than chasing its own
+ * corrected output. Pipelines produce user-facing estimates; calibration
+ * capture stays outside the pipeline.
+ */
+
+import {
+  estimatePromptTokens,
+  estimateToolsTokens,
+} from "../../context/token-estimator.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type EstimateArgs,
+  type EstimateResult,
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+} from "../types.js";
+
+/**
+ * Terminal handler for the `tokenEstimate` pipeline. Computes the tool token
+ * budget from `args.tools` and delegates to {@link estimatePromptTokens} with
+ * the canonical provider key, applying the EWMA calibration correction.
+ * 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 const defaultTokenEstimateTerminal = async (
+  args: EstimateArgs,
+): Promise<EstimateResult> => {
+  const toolTokenBudget =
+    args.tools.length > 0 ? estimateToolsTokens(args.tools) : 0;
+  return estimatePromptTokens(args.history, args.systemPrompt, {
+    providerName: args.providerName,
+    toolTokenBudget,
+  });
+};
+
+const passthrough: Middleware<EstimateArgs, EstimateResult> = async (
+  args,
+  next,
+) => next(args);
+
+/**
+ * Default `tokenEstimate` plugin. Registered by
+ * {@link bootstrapPlugins} on daemon startup so the pipeline always has a
+ * terminal handler even when no other plugin contributes one.
+ */
+export const defaultTokenEstimatePlugin: Plugin = {
+  manifest: {
+    name: "default-token-estimate",
+    version: "1.0.0",
+    provides: { tokenEstimate: "v1" },
+    requires: { pluginRuntime: "v1", tokenEstimateApi: "v1" },
+  },
+  middleware: {
+    tokenEstimate: 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 `defaultTokenEstimatePlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultTokenEstimatePlugin);
+} 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/tool-error.ts

@@ -0,0 +1,126 @@
+/**
+ * Default `toolError` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual nudge-decision logic lives in
+ * {@link defaultToolErrorTerminal}, 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 via module-side-effect imports / `registerDefaultPlugins`),
+ * which puts it at the OUTERMOST position of the onion chain. If the default
+ * middleware invoked the decision logic directly without calling `next`, it
+ * would shadow every later-registered plugin. Routing through `next(args)`
+ * lets user middleware participate normally.
+ *
+ * The canonical nudge decision: when the current turn produced at least one
+ * failed tool result, append a system-notice block to the tool results that
+ * coaches the LLM to either retry with corrected parameters (for recoverable
+ * errors) or report the failure to the user (for unrecoverable ones). Once
+ * the consecutive-error-turn counter exceeds the caller-supplied cap, the
+ * nudge is skipped — the error is likely not something the LLM can fix on
+ * its own and continuing to nudge only burns tokens.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 19).
+ */
+
+import { registerPlugin } from "../registry.js";
+import {
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+  type ToolErrorArgs,
+  type ToolErrorDecision,
+} from "../types.js";
+
+/**
+ * Canonical nudge text. Kept as a module-level constant so tests and future
+ * plugins can match it without duplicating the string.
+ */
+export const DEFAULT_TOOL_ERROR_NUDGE_TEXT =
+  "<system_notice>One or more tool calls returned an error. If the error looks recoverable (e.g. missing or invalid parameters), fix the parameters and retry. If the error is clearly unrecoverable (e.g. a service is down, a resource does not exist, or a permission is permanently denied), report it to the user.</system_notice>";
+
+/**
+ * Terminal handler for the `toolError` pipeline. Nudge iff the current turn
+ * had an error AND the consecutive-error counter is within the cap. Once the
+ * cap is breached the caller should stop appending the nudge (the error is
+ * likely unrecoverable and the LLM already had multiple attempts to correct
+ * it).
+ *
+ * Exported so `agent/loop.ts` can pass it as the `terminal` argument to
+ * `runPipeline` (ensuring the nudge decision fires even when no plugin is
+ * registered — e.g. direct AgentLoop callers that skip `bootstrapPlugins()`)
+ * and so tests can verify the decision logic directly without going through
+ * the pipeline runner.
+ */
+export const defaultToolErrorTerminal = async (
+  args: ToolErrorArgs,
+): Promise<ToolErrorDecision> => {
+  if (
+    args.hasToolError &&
+    args.consecutiveErrorTurns <= args.maxConsecutiveErrorNudges
+  ) {
+    return {
+      action: "nudge",
+      nudgeText: DEFAULT_TOOL_ERROR_NUDGE_TEXT,
+    };
+  }
+  return { action: "skip" };
+};
+
+/**
+ * Default middleware for the `toolError` slot. Passthrough — calls `next(args)`
+ * so later-registered user plugins still participate in the onion chain. The
+ * actual decision logic lives in {@link defaultToolErrorTerminal}, wired in
+ * at the `runPipeline` call site in `agent/loop.ts`.
+ *
+ * Named explicitly so the pipeline's structured log record carries
+ * `"defaultToolErrorMiddleware"` in `chain` instead of an anonymous entry.
+ */
+const defaultToolErrorMiddleware: Middleware<ToolErrorArgs, ToolErrorDecision> =
+  async function defaultToolErrorMiddleware(args, next) {
+    return next(args);
+  };
+
+/**
+ * Plugin registration for the default `toolError` behavior. Registered by
+ * `daemon/external-plugins-bootstrap.ts` via a side-effect import so the
+ * middleware is available to the pipeline runner from daemon startup.
+ */
+export const defaultToolErrorPlugin: Plugin = {
+  manifest: {
+    name: "default-tool-error",
+    version: "1.0.0",
+    requires: {
+      pluginRuntime: "v1",
+      toolErrorApi: "v1",
+    },
+    provides: {
+      toolError: "v1",
+    },
+  },
+  middleware: {
+    toolError: defaultToolErrorMiddleware,
+  },
+};
+
+// 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 `defaultToolErrorPlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultToolErrorPlugin);
+} 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/tool-execute.ts

@@ -0,0 +1,89 @@
+/**
+ * Default `toolExecute` plugin — a no-argument passthrough that preserves
+ * the behavior `ToolExecutor.execute` had before the pipeline wrapper was
+ * introduced.
+ *
+ * Design
+ * ------
+ * The public {@link ToolExecutor.execute} method invokes
+ * {@link runPipeline} with the terminal bound to an internal
+ * `executeInternal` method (the original execute body, refactored to avoid
+ * recursion). Because the terminal IS the original behavior, the default
+ * plugin's `middleware.toolExecute` is a thin passthrough: it forwards to
+ * `next(args)` and returns the downstream result unchanged.
+ *
+ * This matches the convention set by PR 15 (`default-llm-call.ts`) for
+ * `llmCall` — the default plugin makes the pipeline shape explicit without
+ * introducing any behavior of its own. When no third-party plugins are
+ * registered the chain is `[defaultMiddleware] → terminal`, which composes
+ * identically to `[] → terminal`, so the shell-integration tests (which
+ * never register the default) stay unchanged-green.
+ *
+ * Why a dedicated plugin at all?
+ * ------------------------------
+ * - It signals publicly that `toolExecute` is a supported pipeline slot with
+ *   a concrete contract.
+ * - Registration order determines onion order. If a third-party plugin
+ *   wraps `toolExecute`, the runtime should boot with the default present
+ *   (as the innermost passthrough) so the chain visibly contains a
+ *   canonical terminator regardless of which third parties load.
+ */
+
+import { registerPlugin } from "../registry.js";
+import {
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+  type ToolExecuteArgs,
+  type ToolExecuteResult,
+} from "../types.js";
+
+/**
+ * Passthrough middleware — forwards the call to `next`. Named so the
+ * pipeline runner's `chain` log entry reads `defaultToolExecute` instead of
+ * `anonymous`.
+ */
+const defaultToolExecute: Middleware<ToolExecuteArgs, ToolExecuteResult> =
+  async function defaultToolExecute(args, next) {
+    return next(args);
+  };
+
+/**
+ * The default `toolExecute` plugin. Exported as a module constant so the
+ * daemon bootstrap can register it via a side-effect import. Tests may
+ * import and register it explicitly via `registerPlugin()` to cover the
+ * on-by-default execution path.
+ */
+export const defaultToolExecutePlugin: Plugin = {
+  manifest: {
+    name: "default-tool-execute",
+    version: "1.0.0",
+    provides: { toolExecuteApi: "v1" },
+    requires: { pluginRuntime: "v1", toolExecuteApi: "v1" },
+  },
+  middleware: {
+    toolExecute: defaultToolExecute,
+  },
+};
+
+// 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 `defaultToolExecutePlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultToolExecutePlugin);
+} 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/tool-result-truncate.ts

@@ -0,0 +1,88 @@
+/**
+ * Default `toolResultTruncate` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual truncation lives in
+ * {@link defaultToolResultTruncateTerminal}, 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 invoke the terminal directly without calling `next`, it
+ * would shadow every later-registered plugin (including hot-reloaded ones).
+ * Routing through `next(args)` lets user middleware participate normally.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 17).
+ */
+
+import { truncateToolResultText } from "../../context/tool-result-truncation.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+  type ToolResultTruncateArgs,
+  type ToolResultTruncateResult,
+} from "../types.js";
+
+/**
+ * Terminal handler for the `toolResultTruncate` 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 defaultToolResultTruncateTerminal(
+  args: ToolResultTruncateArgs,
+): ToolResultTruncateResult {
+  const truncated = truncateToolResultText(args.content, args.maxChars);
+  return {
+    content: truncated,
+    truncated: truncated !== args.content,
+  };
+}
+
+const passthrough: Middleware<
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult
+> = async (args, next) => next(args);
+
+/**
+ * Plugin descriptor for the default tool-result truncation middleware.
+ * Registered by `plugins/defaults/index.ts` so the registry always has at
+ * least one middleware for the `toolResultTruncate` pipeline.
+ */
+export const defaultToolResultTruncatePlugin: Plugin = {
+  manifest: {
+    name: "default-tool-result-truncate",
+    version: "1.0.0",
+    requires: {
+      pluginRuntime: "v1",
+      toolResultTruncateApi: "v1",
+    },
+  },
+  middleware: {
+    toolResultTruncate: 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 `defaultToolResultTruncatePlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultToolResultTruncatePlugin);
+} 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;
+  }
+}