@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

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

@@ -46,6 +46,14 @@ export interface TurnContext {
   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/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

@@ -1,7 +1,7 @@
 {
   "name": "default-title-generate",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in title-generate pipeline with a passthrough implementation.",
+  "description": "First-party default plugin that triggers conversation-title generation from the user-prompt-submit hook.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/plugins/defaults/title-generate/register.ts

@@ -1,11 +1,17 @@
 /**
- * Default `titleGenerate` pipeline plugin.
+ * Default `title-generate` plugin.
  *
- * Declares no middleware — the terminal handler in `./terminal.ts` is wired in
- * as the pipeline's `terminal` argument by the `runPipeline` call site in
- * `daemon/conversation-agent-loop.ts`. This plugin exists purely to negotiate
- * the `titleGenerateApi` capability so bootstrap has a record that the
- * assistant runtime exposes this pipeline.
+ * 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
@@ -13,23 +19,17 @@
  */
 
 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" };
 
-/**
- * Default titleGenerate plugin. Declares no middleware — it exists purely
- * to negotiate the `titleGenerateApi` capability so bootstrap has a record
- * that the assistant runtime exposes this pipeline.
- *
- * The terminal handler (`./terminal.ts`) is supplied at the call site in
- * `conversation-agent-loop.ts` rather than through `middleware.titleGenerate`,
- * because a default middleware would short-circuit user-registered middleware
- * by always running first in onion order. Keeping the terminal outside the
- * middleware chain lets user plugins observe/transform/short-circuit the
- * call without competing with an assistant-owned default middleware.
- */
 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

@@ -1,7 +1,7 @@
 {
   "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.",
+  "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",

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/external-api.ts

@@ -31,8 +31,8 @@
  * absolute paths or workspace-local copies — the TypeScript compiler erases
  * them and they have no module-identity effect at runtime.
  *
- * See `assistant/docs/plugins.md` for the full authoring contract and
- * `assistant/examples/plugins/echo/register.ts` for a worked example.
+ * See `experimental/plugins/README.md` for the full authoring contract and
+ * `assistant/examples/plugins/echo/` for a worked example.
  */
 
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";