@vellumai/assistant 0.8.5 → 0.8.7

package/src/plugins/defaults/persistence/register.ts

@@ -0,0 +1,38 @@
+/**
+ * Default `persistence` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual dispatch lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * `runPipeline` call sites in `daemon/conversation-agent-loop.ts` and
+ * `daemon/conversation-agent-loop-handlers.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.
+ * Routing through `next(args)` lets user middleware participate normally.
+ *
+ * Manifest declares `provides.persistence: "v1"` so other plugins can
+ * negotiate against the pipeline surface and `requires.pluginRuntime: "v1"`
+ * to satisfy the registry's mandatory capability check.
+ *
+ * Registered from `daemon/external-plugins-bootstrap.ts` via a side-effect
+ * import so the plugin is present in the registry before
+ * {@link bootstrapPlugins} walks it.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 27).
+ */
+
+import { type Plugin } from "../../types.js";
+import persistence from "./middlewares/persistence.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const defaultPersistencePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    persistence,
+  },
+};

package/src/plugins/defaults/persistence/terminal.ts

@@ -0,0 +1,83 @@
+/**
+ * Default `persistence` behavior: writes conversation messages to the database
+ * (and optionally the JSONL disk view).
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * The handler dispatches on the discriminated {@link PersistArgs.op} field:
+ *
+ * - `add`           → {@link addMessage}, optionally followed by
+ *                     {@link syncMessageToDisk} when `args.syncToDisk` is true.
+ * - `reserve`       → {@link reserveMessage} — pre-allocates an empty row
+ *                     for assistant anchor stamping.
+ * - `updateContent` → {@link updateMessageContent} — overwrites an existing
+ *                     row's content (returns `void`, wrapped as
+ *                     `{ op: "updateContent" }`).
+ * - `update`        → {@link updateMessageMetadata} (returns `void`, wrapped
+ *                     as `{ op: "update" }`).
+ * - `delete`        → {@link deleteMessageById} (returns the segment/summary
+ *                     IDs the caller must clean up out-of-band).
+ */
+
+import {
+  addMessage,
+  deleteMessageById,
+  reserveMessage,
+  updateMessageContent,
+  updateMessageMetadata,
+} from "../../../memory/conversation-crud.js";
+import { syncMessageToDisk } from "../../../memory/conversation-disk-view.js";
+import type { PersistArgs, PersistResult } from "../../types.js";
+
+/**
+ * Persist a message according to `args.op`. Exported so the agent-loop call
+ * sites can invoke it directly and tests can verify each op in isolation.
+ */
+export async function defaultPersistenceTerminal(
+  args: PersistArgs,
+): Promise<PersistResult> {
+  switch (args.op) {
+    case "add": {
+      const message = await addMessage(
+        args.conversationId,
+        args.role,
+        args.content,
+        {
+          metadata: args.metadata,
+          ...args.addOptions,
+        },
+      );
+      // Sync the just-persisted row to the JSONL disk view when the caller
+      // opted in. The handler that emits tool-result rows sets
+      // `syncToDisk: true` so the disk view stays in lockstep with the DB.
+      if (args.syncToDisk && args.createdAtMs !== undefined) {
+        syncMessageToDisk(args.conversationId, message.id, args.createdAtMs);
+      }
+      return { op: "add", message };
+    }
+    case "reserve": {
+      const message = await reserveMessage(
+        args.conversationId,
+        args.role,
+        args.metadata,
+      );
+      return { op: "reserve", message };
+    }
+    case "updateContent": {
+      updateMessageContent(args.messageId, args.content);
+      return { op: "updateContent" };
+    }
+    case "update": {
+      updateMessageMetadata(args.messageId, args.updates);
+      return { op: "update" };
+    }
+    case "delete": {
+      const deleted = deleteMessageById(args.messageId);
+      return {
+        op: "delete",
+        segmentIds: deleted.segmentIds,
+        deletedSummaryIds: deleted.deletedSummaryIds,
+      };
+    }
+  }
+}

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 wrapping the assistant's built-in title-generate 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/title-generate/register.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `titleGenerate` pipeline 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.
+ *
+ * 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 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,
+  },
+};

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

@@ -0,0 +1,31 @@
+/**
+ * Default `titleGenerate` behavior: kicks off conversation-title generation.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to {@link queueGenerateConversationTitle}, which schedules title
+ * generation as fire-and-forget background work and falls back to a
+ * deterministic placeholder on failure.
+ */
+
+import { queueGenerateConversationTitle } from "../../../memory/conversation-title-service.js";
+import type { TitleArgs, TitleResult } from "../../types.js";
+
+/**
+ * Invoke the title-generation service with the provided arguments. Exported
+ * for tests that want to exercise the default directly.
+ *
+ * Returns an empty result — the service is fire-and-forget and surfaces its
+ * output through `onTitleUpdated`.
+ */
+export async function defaultTitleGenerateTerminal(
+  args: TitleArgs,
+): Promise<TitleResult> {
+  queueGenerateConversationTitle({
+    conversationId: args.conversationId,
+    provider: args.provider,
+    userMessage: args.userMessage,
+    onTitleUpdated: args.onTitleUpdated,
+  });
+  return {};
+}

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

@@ -0,0 +1,23 @@
+import type {
+  EstimateArgs,
+  EstimateResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `tokenEstimate` pipeline. Forwards to
+ * `next(args)` unchanged; the actual estimate lives in the terminal handler
+ * (`../terminal.ts`), wired in at the `runPipeline` call sites in
+ * `daemon/conversation-agent-loop.ts`.
+ *
+ * Defaults register at the OUTERMOST onion position, so deciding here without
+ * calling `next` 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.
+ */
+const passthrough: Middleware<EstimateArgs, EstimateResult> = async (
+  args,
+  next,
+) => next(args);
+
+export default passthrough;

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

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * Default `tokenEstimate` behavior: estimates the prompt token count used by
+ * the overflow gate.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to
+ * {@link 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. This path produces the user-facing estimate; calibration
+ * capture stays separate.
+ */
+
+import {
+  estimatePromptTokens,
+  estimateToolsTokens,
+} from "../../../context/token-estimator.js";
+import type { EstimateArgs, EstimateResult } from "../../types.js";
+
+/**
+ * Compute the tool token budget from `args.tools` and delegate to
+ * {@link estimatePromptTokens} with the canonical provider key, applying the
+ * EWMA calibration correction. Exported so the agent loop can call it directly
+ * and tests can verify the default behavior.
+ */
+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,
+  });
+};

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,
+  },
+};