@vellumai/assistant 0.8.6 → 0.8.7

package/src/plugins/defaults/tool-error/middlewares/toolError.ts

@@ -0,0 +1,21 @@
+import type {
+  Middleware,
+  ToolErrorArgs,
+  ToolErrorDecision,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `toolError` pipeline. Forwards to `next(args)`
+ * so later-registered user plugins still participate in the onion chain; the
+ * actual nudge-decision logic lives in the terminal handler (`../terminal.ts`),
+ * 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);
+  };
+
+export default defaultToolErrorMiddleware;

package/src/plugins/defaults/tool-error/package.json

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

@@ -0,0 +1,35 @@
+/**
+ * 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 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 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.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 19).
+ */
+
+import { type Plugin } from "../../types.js";
+import defaultToolErrorMiddleware from "./middlewares/toolError.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * 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: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    toolError: defaultToolErrorMiddleware,
+  },
+};

package/src/plugins/defaults/tool-error/terminal.ts

@@ -0,0 +1,47 @@
+/**
+ * Default `toolError` behavior: decides whether to nudge the LLM after a tool
+ * call fails.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * 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.
+ */
+
+import type { ToolErrorArgs, 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>";
+
+/**
+ * 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 the agent loop can call it directly and tests can verify the
+ * decision logic.
+ */
+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" };
+};

package/src/plugins/defaults/tool-execute/middlewares/toolExecute.ts

@@ -0,0 +1,23 @@
+import type {
+  Middleware,
+  ToolExecuteArgs,
+  ToolExecuteResult,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `toolExecute` pipeline. Forwards to
+ * `next(args)` and returns the downstream result unchanged. The original
+ * `ToolExecutor.execute` behavior runs in the terminal bound at the call site,
+ * so this default makes the pipeline shape explicit without introducing any
+ * behavior of its own: the chain `[defaultMiddleware] → terminal` composes
+ * identically to `[] → terminal`.
+ *
+ * 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);
+  };
+
+export default defaultToolExecute;

package/src/plugins/defaults/tool-execute/package.json

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

@@ -29,59 +29,21 @@
  *   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";
+import { type Plugin } from "../../types.js";
+import defaultToolExecute from "./middlewares/toolExecute.js";
+import pkg from "./package.json" with { type: "json" };
 
 /**
- * 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.
+ * The default `toolExecute` plugin. Exported as a module constant that the
+ * defaults aggregator registers centrally; tests may register it explicitly to
+ * cover the on-by-default execution path.
  */
 export const defaultToolExecutePlugin: Plugin = {
   manifest: {
-    name: "default-tool-execute",
-    version: "1.0.0",
+    name: pkg.name,
+    version: pkg.version,
   },
   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/middlewares/toolResultTruncate.ts

@@ -0,0 +1,23 @@
+import type { Middleware } from "../../../types.js";
+import type {
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+} from "../types.js";
+
+/**
+ * Passthrough middleware for the `toolResultTruncate` pipeline. Forwards to
+ * `next(args)` unchanged; the actual truncation 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 (including
+ * hot-reloaded ones). Routing through `next(args)` lets user middleware
+ * participate normally.
+ */
+const passthrough: Middleware<
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult
+> = async (args, next) => next(args);
+
+export default passthrough;

package/src/plugins/defaults/tool-result-truncate/package.json

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

@@ -0,0 +1,35 @@
+/**
+ * Default `toolResultTruncate` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual truncation 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 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 { type Plugin } from "../../types.js";
+import toolResultTruncate from "./middlewares/toolResultTruncate.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * 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: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    toolResultTruncate,
+  },
+};

package/src/plugins/defaults/tool-result-truncate/terminal.ts

@@ -0,0 +1,113 @@
+/**
+ * Default `toolResultTruncate` behavior: tail-drops oversized tool-result text
+ * down to a character budget, plus the truncation primitive it wraps.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ */
+
+import type {
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+} from "./types.js";
+
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+const LOW_SURROGATE_START = 0xdc00;
+const LOW_SURROGATE_END = 0xdfff;
+
+function isHighSurrogate(code: number): boolean {
+  return code >= HIGH_SURROGATE_START && code <= HIGH_SURROGATE_END;
+}
+
+function isLowSurrogate(code: number): boolean {
+  return code >= LOW_SURROGATE_START && code <= LOW_SURROGATE_END;
+}
+
+/**
+ * Slice a string by code-unit indices without splitting a surrogate pair, so
+ * the result never ends or begins mid-emoji. Indices are clamped to the
+ * string bounds; a cut that would land between a high/low surrogate is nudged
+ * inward to the nearest whole code point.
+ */
+function safeStringSlice(
+  str: string,
+  start = 0,
+  end: number = str.length,
+): string {
+  let safeStart = Math.max(0, Math.min(str.length, start));
+  let safeEnd = Math.max(safeStart, Math.min(str.length, end));
+
+  if (safeEnd < str.length && safeEnd > safeStart) {
+    const lastCode = str.charCodeAt(safeEnd - 1);
+    if (isHighSurrogate(lastCode)) {
+      safeEnd--;
+    }
+  }
+
+  if (safeStart > 0 && safeStart < str.length) {
+    const firstCode = str.charCodeAt(safeStart);
+    if (isLowSurrogate(firstCode)) {
+      safeStart++;
+      if (safeStart > safeEnd) safeEnd = safeStart;
+    }
+  }
+
+  return str.slice(safeStart, safeEnd);
+}
+
+/**
+ * Minimum number of characters to preserve when truncating.
+ */
+export const MIN_KEEP_CHARS = 2_000;
+
+/**
+ * Suffix appended to truncated tool results.
+ */
+export const TRUNCATION_SUFFIX =
+  "\n\n[Content truncated — original exceeded size limit. Use offset/limit parameters or request specific sections for large content.]";
+
+/**
+ * Truncate text with newline-boundary awareness.
+ *
+ * If `text.length <= maxChars`, the text is returned as-is.
+ * Otherwise we look for the last newline that falls within 80% of the budget
+ * so we get a clean cut. At least `MIN_KEEP_CHARS` characters are always
+ * preserved.
+ */
+export function truncateToolResultText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  const effectiveMax = Math.max(maxChars, MIN_KEEP_CHARS);
+  const cutPoint = effectiveMax - TRUNCATION_SUFFIX.length;
+
+  // Look for a newline within the last 20% of the budget for a clean break.
+  const threshold = Math.floor(cutPoint * 0.8);
+  const lastNewline = text.lastIndexOf("\n", cutPoint);
+
+  const sliceEnd = lastNewline >= threshold ? lastNewline : cutPoint;
+
+  // If sliceEnd covers the full text, nothing was actually removed — return
+  // the original text without appending the suffix.
+  if (sliceEnd >= text.length) {
+    return text;
+  }
+
+  return safeStringSlice(text, 0, sliceEnd) + TRUNCATION_SUFFIX;
+}
+
+/**
+ * Truncate a single tool-result block's content to `args.maxChars`. Exported
+ * so the agent loop can call it directly and tests can verify the default
+ * behavior.
+ */
+export function defaultToolResultTruncateTerminal(
+  args: ToolResultTruncateArgs,
+): ToolResultTruncateResult {
+  const truncated = truncateToolResultText(args.content, args.maxChars);
+  return {
+    content: truncated,
+    truncated: truncated !== args.content,
+  };
+}

package/src/plugins/defaults/tool-result-truncate/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Argument and result shapes for the default `toolResultTruncate` behavior.
+ */
+
+/**
+ * Input to tool-result truncation: the raw tool-result text and the character
+ * budget the caller computed from the context-window share.
+ */
+export type ToolResultTruncateArgs = {
+  readonly content: string;
+  readonly maxChars: number;
+};
+
+/**
+ * Output of tool-result truncation: the (possibly truncated) content and a
+ * boolean indicating whether the input was actually shortened. Callers use
+ * `truncated` for telemetry / warnings.
+ */
+export type ToolResultTruncateResult = {
+  readonly content: string;
+  readonly truncated: boolean;
+};

package/src/plugins/external-plugin-loader.ts

@@ -50,7 +50,7 @@ import { z } from "zod";
 
 import assistantPkg from "../../package.json" with { type: "json" };
 import { finalizeTool } from "../tools/tool-defaults.js";
-import type { LoadedTool, ToolDefinition } from "../tools/types.js";
+import type { Tool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -276,7 +276,7 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   const hooks = await loadHooks(pluginDir, name);
   if (hooks !== undefined) plugin.hooks = hooks;
 
-  const tools: LoadedTool[] = [];
+  const tools: Tool[] = [];
   for (const { name: toolName, path: toolPath } of listSurfaceDir(
     join(pluginDir, "tools"),
   )) {

package/src/plugins/pipeline.ts

@@ -36,17 +36,6 @@ import {
   type TurnContext,
 } from "./types.js";
 
-// Side-effect import: register every first-party default plugin at module
-// load so downstream consumers (production bootstrap AND tests that skip
-// `bootstrapPlugins()`) observe a fully-populated registry by default.
-// Every code path that calls `runPipeline` imports this module, so by the
-// time the first pipeline runs the defaults are already in place. User
-// plugins load via `loadUserPlugins()` inside `bootstrapPlugins()` (which
-// runs AFTER all static side-effect imports), so the onion ordering
-// (defaults inner, user middleware outer) across all 14 pipelines is
-// preserved in production.
-import "./defaults/index.js";
-
 const moduleLogger = getLogger("plugin-pipeline");
 
 // ─── Default timeouts ───────────────────────────────────────────────────────
@@ -67,7 +56,6 @@ export const DEFAULT_TIMEOUTS: Record<PipelineName, number | null> = {
   llmCall: null,
   toolExecute: null,
   memoryRetrieval: null,
-  historyRepair: null,
   tokenEstimate: null,
   compaction: null,
   overflowReduce: null,