@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -1,35 +1,23 @@
 /**
- * Default `toolError` plugin.
+ * Default `tool-error` 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).
+ * Contributes a `post-tool-use` hook that coaches the model to retry or report
+ * a failed tool call, bounded per tool so an unrecoverable error doesn't churn.
+ * The coaching is surfaced via `additionalContext` (a separate provider-only
+ * block), leaving the tool result's own content untouched. The decision logic
+ * lives in `./hooks/post-tool-use.ts`.
  */
 
 import { type Plugin } from "../../types.js";
-import defaultToolErrorMiddleware from "./middlewares/toolError.js";
+import postToolUse from "./hooks/post-tool-use.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,
+  hooks: {
+    "post-tool-use": postToolUse,
   },
 };

package/src/plugins/defaults/tool-result-truncate/hooks/post-tool-use.ts

@@ -0,0 +1,32 @@
+/**
+ * Default `post-tool-use` hook: tail-drops an oversized tool result down to a
+ * character budget derived from the model's context window, keeping a single
+ * result from blowing the provider's context.
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `post-tool-use` chain — every later hook sees an already-bounded result.
+ * The hook mutates `toolResponse.content` in place.
+ */
+
+import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+
+import { truncateToolResult } from "../terminal.js";
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  const { content, truncated } = truncateToolResult(
+    ctx.toolResponse.content,
+    ctx.maxInputTokens,
+  );
+  if (truncated) {
+    ctx.toolResponse.content = content;
+    ctx.logger.warn(
+      {
+        plugin: "tool-result-truncate",
+        toolUseId: ctx.toolResponse.tool_use_id,
+      },
+      "Truncated oversized tool result to prevent context overflow",
+    );
+  }
+};
+
+export default postToolUse;

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

@@ -1,35 +1,24 @@
 /**
- * Default `toolResultTruncate` plugin.
+ * Default `tool-result-truncate` 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).
+ * Contributes a `post-tool-use` hook that tail-drops an oversized tool result
+ * down to a character budget derived from the model's context window before
+ * the result is sent to the provider. The truncation implementation lives in
+ * `./terminal.ts`; the hook in `./hooks/post-tool-use.ts` wires it into the
+ * lifecycle. Defaults register before user plugins, so this runs at the front
+ * of the hook chain.
  */
 
 import { type Plugin } from "../../types.js";
-import toolResultTruncate from "./middlewares/toolResultTruncate.js";
+import postToolUse from "./hooks/post-tool-use.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,
+  hooks: {
+    "post-tool-use": postToolUse,
   },
 };

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

@@ -1,15 +1,11 @@
 /**
- * Default `toolResultTruncate` behavior: tail-drops oversized tool-result text
- * down to a character budget, plus the truncation primitive it wraps.
+ * Tool-result truncation: tail-drops oversized tool-result text down to a
+ * character budget derived from the model's context window, plus the
+ * primitives 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;
@@ -98,16 +94,39 @@ export function truncateToolResultText(text: string, maxChars: number): string {
 }
 
 /**
- * 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.
+ * Maximum share of the context window that a single tool result may occupy.
+ */
+const MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3;
+
+/**
+ * Absolute cap on tool-result characters (~100K tokens).
+ */
+export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
+
+/**
+ * Calculate the maximum allowed characters for a tool result based on the
+ * context window size. Uses ~4 chars per token as a rough heuristic.
+ */
+export function calculateMaxToolResultChars(
+  contextWindowTokens: number,
+): number {
+  return Math.min(
+    HARD_MAX_TOOL_RESULT_CHARS,
+    Math.floor(contextWindowTokens * MAX_TOOL_RESULT_CONTEXT_SHARE * 4),
+  );
+}
+
+/**
+ * Truncate a tool result's content to fit the model's context window. Derives
+ * the character budget from `maxInputTokens` and tail-drops anything beyond it.
+ * Returns the (possibly truncated) content alongside a `truncated` flag the
+ * caller can use for telemetry.
  */
-export function defaultToolResultTruncateTerminal(
-  args: ToolResultTruncateArgs,
-): ToolResultTruncateResult {
-  const truncated = truncateToolResultText(args.content, args.maxChars);
-  return {
-    content: truncated,
-    truncated: truncated !== args.content,
-  };
+export function truncateToolResult(
+  content: string,
+  maxInputTokens: number,
+): { content: string; truncated: boolean } {
+  const maxChars = calculateMaxToolResultChars(maxInputTokens);
+  const next = truncateToolResultText(content, maxChars);
+  return { content: next, truncated: next !== content };
 }

package/src/plugins/pipeline.ts

@@ -20,8 +20,7 @@
  *   timer. A timeout rejection is a `PluginTimeoutError` carrying the
  *   pipeline name, the best-known offending plugin (from `ctx.pluginName`),
  *   and elapsed ms. When `timeoutMs` is `null`/`undefined`, no timer is
- *   armed — pipelines like `llmCall` and `toolExecute` rely on downstream
- *   timeouts instead.
+ *   armed — pipelines like `compaction` rely on downstream timeouts instead.
  */
 
 import type { Logger } from "pino";
@@ -43,27 +42,16 @@ const moduleLogger = getLogger("plugin-pipeline");
 /**
  * Default per-pipeline timeout budgets in milliseconds. A value of `null`
  * means the runner does NOT arm a timer — the pipeline relies on its
- * downstream for budgeting (e.g. `llmCall` defers to provider-level HTTP
- * timeouts; `toolExecute` defers to the per-tool timeout already enforced
- * by `ToolExecutor`).
+ * downstream for budgeting (e.g. `compaction` defers to the provider-level
+ * HTTP timeouts of the summary call it wraps).
  *
  * Callers pass the appropriate entry as `runPipeline`'s `timeoutMs` argument.
  * The design doc locks these numbers in; do not tweak without coordinating
  * a design update.
  */
 export const DEFAULT_TIMEOUTS: Record<PipelineName, number | null> = {
-  turn: null,
-  llmCall: null,
-  toolExecute: null,
-  memoryRetrieval: null,
-  tokenEstimate: null,
   compaction: null,
   overflowReduce: null,
-  persistence: null,
-  titleGenerate: null,
-  toolResultTruncate: null,
-  emptyResponse: null,
-  toolError: null,
   circuitBreaker: null,
 };
 
@@ -114,7 +102,7 @@ export function composeMiddleware<A, R>(
  *
  * When `args` carries no `AbortSignal` property, the original object is
  * returned unchanged — pipelines whose terminals don't consume a signal
- * (e.g. `persistence`, `tokenEstimate`) see identical behavior to before.
+ * (e.g. `circuitBreaker`) see identical behavior to before.
  * The return value's `cleanup()` tears down any `addEventListener("abort",
  * ...)` handlers attached to the caller's signal so a pipeline that
  * completes successfully doesn't leak listeners on the caller's controller.
@@ -316,9 +304,9 @@ export async function runPipeline<A, R>(
  *
  * `runHook` is the hook-side counterpart to {@link runPipeline}:
  * `runPipeline` composes middleware around a terminal handler for stateful
- * request/response pipelines (memory retrieval, history repair, etc.);
+ * request/response pipelines (compaction, overflow reduction, etc.);
  * `runHook` walks ordered hook functions for declarative chain-style
- * context transformations (`user-prompt-submit` today).
+ * context transformations (`user-prompt-submit`, `post-tool-use`).
  *
  * @param name        The hook identifier — pick one from {@link HOOKS}.
  * @param initialCtx  Context the first hook receives.

package/src/plugins/registry.ts

@@ -9,10 +9,10 @@
  * closed-registration latch that protects `bootstrapPlugins()` from
  * late-arriving registrations.
  *
- * Registration is order-preserving: {@link getRegisteredPlugins},
- * {@link getMiddlewaresFor}, and (secondarily) {@link getInjectors} all reflect
- * the order in which {@link registerPlugin} was called, which in turn
- * determines onion order for middleware composition in the pipeline runner.
+ * Registration is order-preserving: {@link getRegisteredPlugins} and
+ * {@link getMiddlewaresFor} reflect the order in which {@link registerPlugin}
+ * was called, which in turn determines onion order for middleware composition
+ * in the pipeline runner.
  *
  * This module does not call `Plugin.init()` — that is the job of the
  * bootstrap (see PR 14). It also does not wire the registry into the daemon;
@@ -22,7 +22,6 @@
  */
 
 import {
-  type Injector,
   type PipelineMiddlewareMap,
   type PipelineName,
   type Plugin,
@@ -47,7 +46,7 @@ const registeredPlugins = new Map<string, Plugin>();
  * top-level `await` later resolves and still tries to call
  * {@link registerPlugin}. Without the latch such a late arrival would land in
  * the registry after `bootstrapPlugins()` has already walked it, leaving the
- * plugin visible to `getMiddlewaresFor()` / `getInjectors()` with its
+ * plugin visible to `getMiddlewaresFor()` with its
  * `init()` hook never invoked.
  */
 let registrationClosed = false;
@@ -190,22 +189,6 @@ export function getHooksFor<TCtx = unknown>(
   return out;
 }
 
-/**
- * Flatten every registered plugin's `injectors` array and sort the result by
- * `order` ascending. Two injectors with the same `order` retain their relative
- * registration order (stable sort via `Array.prototype.sort`).
- */
-export function getInjectors(): Injector[] {
-  const out: Injector[] = [];
-  for (const plugin of registeredPlugins.values()) {
-    if (plugin.injectors && plugin.injectors.length > 0) {
-      out.push(...plugin.injectors);
-    }
-  }
-  out.sort((a, b) => a.order - b.order);
-  return out;
-}
-
 /**
  * Close the per-boot registration window. After this call, any attempt to
  * register a genuinely new plugin throws a {@link PluginExecutionError}.
@@ -226,9 +209,9 @@ export function closeRegistration(): void {
 /**
  * Remove a plugin from the registry. Invoked from the bootstrap's failure path
  * after {@link Plugin.onShutdown} and contribution teardown have run, so
- * {@link getMiddlewaresFor} and {@link getInjectors} no longer expose a
- * plugin whose `init()` aborted mid-bootstrap. Without this, every subsequent
- * pipeline invocation would re-enter the uninitialized plugin's middleware.
+ * {@link getMiddlewaresFor} no longer exposes a plugin whose `init()` aborted
+ * mid-bootstrap. Without this, every subsequent pipeline invocation would
+ * re-enter the uninitialized plugin's middleware.
  * Safe to call on an already-absent name (no-op).
  */
 export function unregisterPlugin(name: string): void {