@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/plugins/defaults/memory-v3-shadow/tree.ts

@@ -0,0 +1,174 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parse as parseYaml } from "yaml";
+
+import { getWorkspaceDir } from "../../../util/platform.js";
+import type {
+  LeafFrontmatter,
+  LeafNode,
+  LeafPath,
+  LeafTree,
+  Slug,
+} from "./types.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Bundled stub data shipped alongside the loader. */
+const BUNDLED_DATA_DIR = join(HERE, "data");
+
+/**
+ * Resolve the directory the loaders should read leaf-tree artifacts from.
+ *
+ * Prefers a maintainer's per-instance workspace override
+ * (`<workspace>/memory/v3/data/`) when present, otherwise falls back to the
+ * generic bundled stub shipped in this package.
+ *
+ * The public {@link loadLeafTree} API still takes an explicit `dataDir` for
+ * testability; orchestrators that want the runtime default call this helper.
+ */
+export function resolveDataDir(): string {
+  const workspaceData = join(getWorkspaceDir(), "memory", "v3", "data");
+  if (existsSync(workspaceData)) return workspaceData;
+  return BUNDLED_DATA_DIR;
+}
+
+/** Recursively collect every `*.md` file under `dir`. */
+async function collectMarkdownFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectMarkdownFiles(full)));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Split a leaf `.md` file into its YAML frontmatter and body.
+ *
+ * Frontmatter is the `---`-delimited block at the top of the file; everything
+ * after the closing delimiter is the description body.
+ */
+function splitFrontmatter(raw: string): { frontmatter: string; body: string } {
+  const normalized = raw.replace(/^/, "");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(normalized);
+  if (!match) {
+    throw new Error("leaf markdown is missing YAML frontmatter");
+  }
+  return { frontmatter: match[1], body: match[2] };
+}
+
+function parseLeafFrontmatter(yaml: string, file: string): LeafFrontmatter {
+  const parsed = parseYaml(yaml) as unknown;
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error(`leaf ${file} frontmatter is not a mapping`);
+  }
+  const record = parsed as Record<string, unknown>;
+  if (typeof record.path !== "string") {
+    throw new Error(`leaf ${file} frontmatter is missing a string \`path\``);
+  }
+  if (typeof record.in_core !== "boolean") {
+    throw new Error(
+      `leaf ${file} frontmatter is missing a boolean \`in_core\``,
+    );
+  }
+  return {
+    path: record.path,
+    in_core: record.in_core,
+    ...(typeof record.id === "string" ? { id: record.id } : {}),
+  };
+}
+
+/** Derive the canonical leaf path from a file's location under `leaves/`. */
+function pathFromLocation(leavesDir: string, file: string): LeafPath {
+  return relative(leavesDir, file).replace(/\.md$/, "").split(sep).join("/");
+}
+
+/**
+ * Load the leaf tree from `dataDir`. READ-ONLY: walks `leaves/**\/*.md` and
+ * reads `assignments.json` without mutating anything on disk.
+ *
+ * Builds:
+ * - `leaves`: leaf path → {@link LeafNode} (frontmatter, description, domain,
+ *   and the slugs assigned to it).
+ * - `byPage`: slug → the leaf paths it is assigned to (inverted assignments).
+ *
+ * Page→leaf membership precedence is per-page: when `pageLeaves` supplies a
+ * non-empty array for a slug, those frontmatter-derived leaves win for that
+ * page; slugs absent from `pageLeaves` (or mapped to an empty array) fall back
+ * to `assignments.json`. Omitting `pageLeaves` reproduces the legacy
+ * assignments.json-only behavior exactly (used by the bundled stub and tests);
+ * orchestrators supply `pageLeaves` from the page index.
+ */
+export async function loadLeafTree(
+  dataDir: string,
+  pageLeaves?: Map<Slug, LeafPath[]>,
+): Promise<LeafTree> {
+  const leavesDir = join(dataDir, "leaves");
+  const files = await collectMarkdownFiles(leavesDir);
+
+  const nodes = await Promise.all(
+    files.map(async (file): Promise<LeafNode> => {
+      const raw = await readFile(file, "utf8");
+      const { frontmatter, body } = splitFrontmatter(raw);
+      const path = pathFromLocation(leavesDir, file);
+      return {
+        path,
+        frontmatter: parseLeafFrontmatter(frontmatter, file),
+        description: body.trim(),
+        members: [],
+        domain: path.split("/")[0],
+      };
+    }),
+  );
+
+  const leaves = new Map<LeafPath, LeafNode>(
+    nodes.map((node) => [node.path, node]),
+  );
+
+  const assignmentsRaw = await readFile(
+    join(dataDir, "assignments.json"),
+    "utf8",
+  );
+  const assignments = JSON.parse(assignmentsRaw) as Record<Slug, LeafPath[]>;
+
+  const slugs = new Set<Slug>(Object.keys(assignments));
+  if (pageLeaves) for (const slug of pageLeaves.keys()) slugs.add(slug);
+
+  const byPage = new Map<Slug, LeafPath[]>();
+  for (const slug of slugs) {
+    const fromFrontmatter = pageLeaves?.get(slug);
+    const leafPaths =
+      fromFrontmatter && fromFrontmatter.length > 0
+        ? fromFrontmatter
+        : (assignments[slug] ?? []);
+    byPage.set(slug, [...leafPaths]);
+    for (const leafPath of leafPaths) {
+      leaves.get(leafPath)?.members.push(slug);
+    }
+  }
+
+  return { leaves, byPage };
+}
+
+/** The slugs assigned to a leaf. */
+export function membersOf(tree: LeafTree, leaf: LeafPath): Slug[] {
+  return tree.leaves.get(leaf)?.members ?? [];
+}
+
+/** The leaf paths a slug is assigned to. */
+export function leavesOf(tree: LeafTree, slug: Slug): LeafPath[] {
+  return tree.byPage.get(slug) ?? [];
+}
+
+/** The unique slugs owned by every leaf in `core` (expand leaf-paths → slugs). */
+export function coreSlugs(tree: LeafTree, core: Set<LeafPath>): Set<Slug> {
+  return new Set([...core].flatMap((leaf) => membersOf(tree, leaf)));
+}

package/src/plugins/defaults/memory-v3-shadow/types.ts

@@ -0,0 +1,59 @@
+export type LeafPath = string; // dot- or slash-pathed taxonomy node
+export type Slug = string;
+
+/**
+ * Injection-block id for the v3 live `<memory>` block. Shared between the
+ * producer (the v3 injector in `shadow-plugin.ts`) and the v2-suppression
+ * consumer (`conversation-runtime-assembly.ts`), which keys off this id to
+ * detect that v3 actually produced a block this turn. Keeping it in one place
+ * makes a rename a compile error on both sides instead of a silent
+ * suppression bypass.
+ */
+export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
+
+export interface LeafFrontmatter {
+  path: LeafPath;
+  in_core: boolean;
+  /**
+   * Optional stable identifier for the leaf, independent of its taxonomy path.
+   * Older leaves predate this field and omit it, so it is optional.
+   */
+  id?: string;
+}
+
+export interface LeafNode {
+  path: LeafPath;
+  frontmatter: LeafFrontmatter;
+  description: string;
+  members: Slug[];
+  domain: string;
+}
+
+export interface LeafTree {
+  leaves: Map<LeafPath, LeafNode>;
+  byPage: Map<Slug, LeafPath[]>;
+}
+
+export interface WorkingSetEntry {
+  slug: Slug;
+  selectedAtTurn: number;
+  pinned: boolean;
+  lastSeenTurn: number;
+}
+
+export interface TurnContext {
+  conversationId: string;
+  turnNumber: number;
+  currentMessage: string;
+  recentContext: string;
+  /**
+   * Optional situational signal — the current date plus the live NOW.md
+   * scratchpad — so a leaf or page can be routed/selected on a date or
+   * live-state cue the message itself never names (e.g. a person whose
+   * anniversary is today). Omitted when unavailable; the router and selector
+   * render nothing for an undefined value.
+   */
+  situationalContext?: string;
+}
+
+export type SelectionSource = "l1+l2" | "core+l2" | "needle" | "carry-forward";

package/src/plugins/defaults/memory-v3-shadow/working-set.ts

@@ -0,0 +1,88 @@
+import { Slug, WorkingSetEntry } from "./types.js";
+
+/**
+ * Scores a working-set entry for cap eviction. Lower score = more evictable.
+ * This is the pluggable seam for a future salience-weighted policy; the
+ * default is plain LRU on `lastSeenTurn`.
+ */
+export type ScoreFn = (entry: WorkingSetEntry) => number;
+
+/** Default eviction score: least-recently-seen entries evict first. */
+function lruScore(entry: WorkingSetEntry): number {
+  return entry.lastSeenTurn;
+}
+
+export class WorkingSet {
+  private entries = new Map<Slug, WorkingSetEntry>();
+
+  constructor(
+    private readonly maxPages = 150,
+    private readonly evictWindow = 5,
+    private readonly scoreFn: ScoreFn = lruScore,
+  ) {}
+
+  recordSelection(slug: Slug, turn: number, pinned: boolean): void {
+    const existing = this.entries.get(slug);
+    this.entries.set(slug, {
+      slug,
+      selectedAtTurn: existing?.selectedAtTurn ?? turn,
+      pinned: existing?.pinned || pinned,
+      lastSeenTurn: turn,
+    });
+  }
+
+  union(): Set<Slug> {
+    return new Set(this.entries.keys());
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * Prune the working set, in order:
+   *   1. Core slugs never belong here — drop any entry whose slug is core.
+   *   2. Pinned entries never evict.
+   *   3. Window eviction: drop a non-pinned entry unseen for more than
+   *      `evictWindow` turns.
+   *   4. Cap eviction: while over `maxPages`, evict the lowest-scoring
+   *      non-pinned entry first (ties broken deterministically).
+   */
+  evict(currentTurn: number, coreSlugs: Set<Slug>): void {
+    // 1. Core slugs are owned by core, not the working set.
+    for (const slug of this.entries.keys()) {
+      if (coreSlugs.has(slug)) {
+        this.entries.delete(slug);
+      }
+    }
+
+    // 2 + 3. Window eviction for stale non-pinned entries.
+    for (const [slug, entry] of this.entries) {
+      if (
+        !entry.pinned &&
+        currentTurn - entry.lastSeenTurn > this.evictWindow
+      ) {
+        this.entries.delete(slug);
+      }
+    }
+
+    // 4. Cap eviction: evict the lowest-scoring non-pinned entry until the
+    // set fits. Sort once (ascending score, then slug for determinism) and
+    // walk the candidates.
+    if (this.entries.size <= this.maxPages) {
+      return;
+    }
+    const evictable = [...this.entries.values()]
+      .filter((entry) => !entry.pinned)
+      .sort(
+        (a, b) =>
+          this.scoreFn(a) - this.scoreFn(b) || (a.slug < b.slug ? -1 : 1),
+      );
+    for (const entry of evictable) {
+      if (this.entries.size <= this.maxPages) {
+        break;
+      }
+      this.entries.delete(entry.slug);
+    }
+  }
+}

package/src/plugins/defaults/title-generate/hooks/stop.ts

@@ -0,0 +1,75 @@
+/**
+ * Default `stop` hook: triggers the second-pass conversation-title
+ * regeneration once a conversation has accumulated enough context.
+ *
+ * The first title is generated from the opening prompt alone (see
+ * `./user-prompt-submit.ts`). After a few exchanges the conversation's real
+ * topic is usually clearer, so a single second pass re-titles using the most
+ * recent messages. This hook is the trigger — it fires the regeneration when
+ * the conversation reaches its third user turn — and delegates the title
+ * itself to the service (`memory/conversation-title-service.ts`), which
+ * re-checks that the title is still auto-generated, resolves the title
+ * provider, persists, and broadcasts the `conversation_title_updated` /
+ * `sync_changed` events.
+ *
+ * Turn count is read from history rather than an external counter: the number
+ * of genuine user prompts — user-role messages that aren't purely tool results
+ * — is the conversation's turn number. Deriving it from history keeps the hook
+ * stateless and means a mid-run array rewrite (compaction) can't invalidate it.
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { getConfig } from "../../../../config/loader.js";
+import { queueRegenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
+import type { Message } from "../../../../providers/types.js";
+
+/**
+ * User turn at which the second title pass fires. Matches the
+ * `conversations.skipAutoRetitling` opt-out, documented as skipping the
+ * regeneration "that fires after the third user turn".
+ */
+const SECOND_PASS_USER_TURN = 3;
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/** Count of genuine user prompts in history — the conversation's turn number. */
+function countUserTurns(messages: ReadonlyArray<Message>): number {
+  let turns = 0;
+  for (const message of messages) {
+    if (message.role === "user" && !isToolResultMessage(message)) turns++;
+  }
+  return turns;
+}
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  // Only re-title at a genuine turn end. A `"continue"` decision means an
+  // earlier hook is re-querying the model (e.g. an empty-response nudge), so
+  // defer to the eventual terminal stop.
+  if (ctx.decision !== "stop") return;
+
+  if (getConfig().conversations.skipAutoRetitling) return;
+
+  if (countUserTurns(ctx.messages) !== SECOND_PASS_USER_TURN) return;
+
+  const { conversationId } = ctx;
+  // Deferred to a later macrotask so the just-completed turn lands first. The
+  // hook fires at the stop boundary, before the loop appends the turn's
+  // assistant reply to history and emits `message_complete` (which persists
+  // it). The service regenerates from the most recent stored messages, so it
+  // must run after the reply is persisted to reflect it. The service is itself
+  // fire-and-forget and re-checks replaceability, owning provider resolution,
+  // persistence, and the resulting broadcast.
+  setTimeout(() => {
+    queueRegenerateConversationTitle({ conversationId });
+  }, 0);
+};
+
+export default stop;

package/src/plugins/defaults/title-generate/hooks/user-prompt-submit.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `user-prompt-submit` hook: kicks off conversation-title generation
+ * from the submitted prompt.
+ *
+ * Title generation is a self-contained side effect that only needs the user's
+ * prompt as context, so it belongs at the prompt-submit boundary rather than
+ * threaded through the agent loop. The hook is a pure trigger — it schedules
+ * the work and returns; persistence and the resulting
+ * `conversation_title_updated` / `sync_changed` broadcast are owned by the
+ * title service (see `memory/conversation-title-service.ts`).
+ */
+
+import type {
+  PluginHookFn,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import { queueGenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+  // Deferred to a later macrotask so the main agent-loop LLM request is
+  // issued first; on strict single-slot provider configs this keeps the
+  // background title call from claiming the rate-limit slot ahead of the
+  // user-visible response. The title service is itself fire-and-forget and
+  // re-checks title replaceability before making any LLM call, so an
+  // already-titled conversation incurs no generation.
+  setTimeout(() => {
+    queueGenerateConversationTitle({
+      conversationId: ctx.conversationId,
+      userMessage: ctx.prompt,
+    });
+  }, 0);
+};
+
+export default userPromptSubmit;

package/src/plugins/defaults/title-generate/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-title-generate",
+  "version": "1.0.0",
+  "description": "First-party default plugin that triggers conversation-title generation from the user-prompt-submit hook.",
+  "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/title-generate/register.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `title-generate` plugin.
+ *
+ * Contributes two hooks, both pure triggers that delegate the title work to
+ * the service (`memory/conversation-title-service.ts`):
+ *
+ * - `user-prompt-submit` (`./hooks/user-prompt-submit.ts`) — first-pass title
+ *   generation from the submitted prompt.
+ * - `stop` (`./hooks/stop.ts`) — second-pass regeneration once the
+ *   conversation reaches its third user turn, for a title that reflects the
+ *   established topic.
+ *
+ * Persistence and the resulting `conversation_title_updated` / `sync_changed`
+ * broadcast are owned by the title service.
+ *
+ * Registered via a side-effect import from
+ * `daemon/external-plugins-bootstrap.ts` so it is present in the registry
+ * by the time {@link bootstrapPlugins} runs.
+ */
+
+import { type Plugin } from "../../types.js";
+import stop from "./hooks/stop.js";
+import userPromptSubmit from "./hooks/user-prompt-submit.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const defaultTitleGeneratePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": userPromptSubmit,
+    stop,
+  },
+};

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

@@ -0,0 +1,118 @@
+/**
+ * Default `post-tool-use` hook: when a tool result carries `is_error`, set
+ * `additionalContext` with a system-notice that coaches the model to either
+ * retry with corrected parameters (for recoverable errors) or report the
+ * failure to the user (for unrecoverable ones).
+ *
+ * The coaching is delivered via `additionalContext`, not by mutating the tool
+ * result's `content`. The loop appends it to the provider-bound history as a
+ * separate block after the tool_result event is emitted, so the model sees the
+ * guidance while the client-facing and persisted tool output stay the tool's
+ * actual result. This mirrors how Claude Code (`additionalContext`) and Codex
+ * (`additional_contexts`) surface PostToolUse feedback as separate context
+ * rather than rewriting the tool response.
+ *
+ * The coaching is bounded per tool: once a single tool has failed
+ * `MAX_CONSECUTIVE_ERROR_NUDGES` times in a row the notice is dropped — the
+ * error is likely not something the model can fix on its own, and continuing
+ * to coach a retry only burns tokens. The consecutive-failure count is derived
+ * from the conversation history (the trailing run of error results for this
+ * tool name, plus the current one) rather than a loop-held counter, so the
+ * guard survives mid-run compaction rewriting the history array. A successful
+ * result for the tool resets its streak.
+ */
+
+import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+
+import type { Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical tool-error coaching text. Kept as a module-level constant so tests
+ * and plugins that wrap the default can match it without duplicating the
+ * string.
+ *
+ * This is shown to the model as provider-only context, not the user. Edits
+ * here affect retry behavior but not end-user UX directly.
+ */
+export const TOOL_ERROR_NUDGE_TEXT =
+  "<system_notice>This tool call 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>";
+
+/**
+ * Number of back-to-back failures of a single tool to coach before giving up.
+ * Coaching fires on the 1st through Nth consecutive failure and is dropped from
+ * the (N+1)th onward.
+ */
+const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
+
+/** Map every `tool_use` block id in history to the tool name it invoked. */
+function toolNamesById(messages: ReadonlyArray<Message>): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    for (const block of message.content) {
+      if (block.type === "tool_use") names.set(block.id, block.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Trailing run of consecutive error results for `toolName` already in history.
+ * Walks the tool's results in chronological order and counts back from the most
+ * recent until a successful result breaks the streak. The current result is not
+ * yet in history, so callers add it themselves.
+ */
+function priorConsecutiveErrors(
+  messages: ReadonlyArray<Message>,
+  toolName: string,
+  namesById: ReadonlyMap<string, string>,
+): number {
+  const isErrorByOrder: boolean[] = [];
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    for (const block of message.content) {
+      if (block.type !== "tool_result") continue;
+      if (namesById.get(block.tool_use_id) !== toolName) continue;
+      isErrorByOrder.push(block.is_error === true);
+    }
+  }
+
+  let streak = 0;
+  for (let i = isErrorByOrder.length - 1; i >= 0; i--) {
+    if (!isErrorByOrder[i]) break;
+    streak++;
+  }
+  return streak;
+}
+
+const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+  if (ctx.toolResponse.is_error !== true) return;
+
+  const namesById = toolNamesById(ctx.messages);
+  const toolName = namesById.get(ctx.toolResponse.tool_use_id);
+
+  // Prior failures of this tool plus the current one. An unresolved name (the
+  // current turn's tool_use is always in history, so this is defensive) falls
+  // back to coaching this lone failure.
+  const consecutiveErrors =
+    (toolName === undefined
+      ? 0
+      : priorConsecutiveErrors(ctx.messages, toolName, namesById)) + 1;
+
+  if (consecutiveErrors > MAX_CONSECUTIVE_ERROR_NUDGES) {
+    ctx.logger.info(
+      {
+        plugin: "tool-error",
+        toolName,
+        toolUseId: ctx.toolResponse.tool_use_id,
+        consecutiveErrors,
+      },
+      "Skipping tool-error coaching after repeated consecutive failures",
+    );
+    return;
+  }
+
+  ctx.additionalContext = TOOL_ERROR_NUDGE_TEXT;
+};
+
+export default postToolUse;

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 contributing a post-tool-use hook that coaches the model to retry or report a failed tool call.",
+  "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,23 @@
+/**
+ * Default `tool-error` plugin.
+ *
+ * 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 postToolUse from "./hooks/post-tool-use.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const defaultToolErrorPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  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;