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

package/src/plugins/defaults/persistence.ts

@@ -1,127 +0,0 @@
-/**
- * Default `persistence` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual dispatch lives in
- * {@link defaultPersistenceTerminal}, 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.
- *
- * The terminal dispatches on the discriminated {@link PersistArgs.op} field:
- *
- * - `add`    → {@link addMessage}, optionally followed by
- *              {@link syncMessageToDisk} when `args.syncToDisk` is true.
- * - `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).
- *
- * 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 {
-  addMessage,
-  deleteMessageById,
-  updateMessageMetadata,
-} from "../../memory/conversation-crud.js";
-import { syncMessageToDisk } from "../../memory/conversation-disk-view.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type Middleware,
-  type PersistArgs,
-  type PersistResult,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
-
-/**
- * Terminal handler for the `persistence` pipeline. Exported so tests can
- * verify default behavior directly without going through `runPipeline`, and
- * so the `daemon/conversation-agent-loop*.ts` call sites can pass it as the
- * `terminal` argument to `runPipeline`.
- */
-export async function defaultPersistenceTerminal(
-  args: PersistArgs,
-): Promise<PersistResult> {
-  switch (args.op) {
-    case "add": {
-      const message = await addMessage(
-        args.conversationId,
-        args.role,
-        args.content,
-        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 "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,
-      };
-    }
-  }
-}
-
-const passthrough: Middleware<PersistArgs, PersistResult> = async (
-  args,
-  next,
-) => next(args);
-
-export const defaultPersistencePlugin: Plugin = {
-  manifest: {
-    name: "default-persistence",
-    version: "1.0.0",
-  },
-  middleware: {
-    persistence: passthrough,
-  },
-};
-
-// 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 `defaultPersistencePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultPersistencePlugin);
-} 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/title-generate.ts

@@ -1,90 +0,0 @@
-/**
- * Default `titleGenerate` pipeline plugin.
- *
- * The terminal for the `titleGenerate` pipeline. Delegates to
- * {@link queueGenerateConversationTitle}, which schedules title generation
- * as fire-and-forget background work and falls back to a deterministic
- * placeholder on failure.
- *
- * Custom plugins may install middleware that short-circuits this terminal
- * (e.g. a deterministic generator for tests, or an alternative LLM routing
- * policy). When no middleware is installed the pipeline calls this
- * terminal directly and behavior is bit-identical to the pre-plugin code
- * path.
- *
- * 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 { queueGenerateConversationTitle } from "../../memory/conversation-title-service.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type Plugin,
-  PluginExecutionError,
-  type TitleArgs,
-  type TitleResult,
-} from "../types.js";
-
-/**
- * Invoke the title-generation service with the provided arguments. Used as
- * the terminal handler for the `titleGenerate` pipeline in
- * `conversation-agent-loop.ts`, and re-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 {};
-}
-
-/**
- * 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 is supplied at the call site in
- * `conversation-agent-loop.ts` (see {@link defaultTitleGenerateTerminal})
- * 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: "default-title-generate",
-    version: "1.0.0",
-  },
-};
-
-// 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 `defaultTitleGeneratePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultTitleGeneratePlugin);
-} 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/token-estimate.ts

@@ -1,101 +0,0 @@
-/**
- * Default `tokenEstimate` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual estimate lives in
- * {@link defaultTokenEstimateTerminal}, 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.
- *
- * The terminal delegates to
- * {@link import("../../context/token-estimator.js").estimatePromptTokens 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. Pipelines produce user-facing estimates; calibration
- * capture stays outside the pipeline.
- */
-
-import {
-  estimatePromptTokens,
-  estimateToolsTokens,
-} from "../../context/token-estimator.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type EstimateArgs,
-  type EstimateResult,
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
-
-/**
- * Terminal handler for the `tokenEstimate` pipeline. Computes the tool token
- * budget from `args.tools` and delegates to {@link estimatePromptTokens} with
- * the canonical provider key, applying the EWMA calibration correction.
- * Exported so tests can verify default behavior directly without going through
- * `runPipeline`, and so `daemon/conversation-agent-loop.ts` can pass it as the
- * `terminal` argument to `runPipeline`.
- */
-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,
-  });
-};
-
-const passthrough: Middleware<EstimateArgs, EstimateResult> = async (
-  args,
-  next,
-) => next(args);
-
-/**
- * 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: "default-token-estimate",
-    version: "1.0.0",
-  },
-  middleware: {
-    tokenEstimate: passthrough,
-  },
-};
-
-// 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 `defaultTokenEstimatePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultTokenEstimatePlugin);
-} 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-error.ts

@@ -1,119 +0,0 @@
-/**
- * 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
- * {@link defaultToolErrorTerminal}, 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.
- *
- * 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.
- *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 19).
- */
-
-import { registerPlugin } from "../registry.js";
-import {
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-  type ToolErrorArgs,
-  type 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>";
-
-/**
- * Terminal handler for the `toolError` pipeline. 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 `agent/loop.ts` can pass it as the `terminal` argument to
- * `runPipeline` (ensuring the nudge decision fires even when no plugin is
- * registered — e.g. direct AgentLoop callers that skip `bootstrapPlugins()`)
- * and so tests can verify the decision logic directly without going through
- * the pipeline runner.
- */
-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" };
-};
-
-/**
- * Default middleware for the `toolError` slot. Passthrough — calls `next(args)`
- * so later-registered user plugins still participate in the onion chain. The
- * actual decision logic lives in {@link defaultToolErrorTerminal}, 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);
-  };
-
-/**
- * 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: "default-tool-error",
-    version: "1.0.0",
-  },
-  middleware: {
-    toolError: defaultToolErrorMiddleware,
-  },
-};
-
-// 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 `defaultToolErrorPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultToolErrorPlugin);
-} 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-execute.ts

@@ -1,87 +0,0 @@
-/**
- * Default `toolExecute` plugin — a no-argument passthrough that preserves
- * the behavior `ToolExecutor.execute` had before the pipeline wrapper was
- * introduced.
- *
- * Design
- * ------
- * The public {@link ToolExecutor.execute} method invokes
- * {@link runPipeline} with the terminal bound to an internal
- * `executeInternal` method (the original execute body, refactored to avoid
- * recursion). Because the terminal IS the original behavior, the default
- * plugin's `middleware.toolExecute` is a thin passthrough: it forwards to
- * `next(args)` and returns the downstream result unchanged.
- *
- * This matches the convention set by PR 15 (`default-llm-call.ts`) for
- * `llmCall` — the default plugin makes the pipeline shape explicit without
- * introducing any behavior of its own. When no third-party plugins are
- * registered the chain is `[defaultMiddleware] → terminal`, which composes
- * identically to `[] → terminal`, so the shell-integration tests (which
- * never register the default) stay unchanged-green.
- *
- * Why a dedicated plugin at all?
- * ------------------------------
- * - It signals publicly that `toolExecute` is a supported pipeline slot with
- *   a concrete contract.
- * - Registration order determines onion order. If a third-party plugin
- *   wraps `toolExecute`, the runtime should boot with the default present
- *   (as the innermost passthrough) so the chain visibly contains a
- *   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";
-
-/**
- * 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.
- */
-export const defaultToolExecutePlugin: Plugin = {
-  manifest: {
-    name: "default-tool-execute",
-    version: "1.0.0",
-  },
-  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.ts

@@ -1,84 +0,0 @@
-/**
- * Default `toolResultTruncate` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual truncation lives in
- * {@link defaultToolResultTruncateTerminal}, 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 { truncateToolResultText } from "../../context/tool-result-truncation.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-  type ToolResultTruncateArgs,
-  type ToolResultTruncateResult,
-} from "../types.js";
-
-/**
- * Terminal handler for the `toolResultTruncate` pipeline. Exported so tests
- * can verify default behavior directly without going through `runPipeline`,
- * and so `agent/loop.ts` can pass it as the `terminal` argument to
- * `runPipeline`.
- */
-export function defaultToolResultTruncateTerminal(
-  args: ToolResultTruncateArgs,
-): ToolResultTruncateResult {
-  const truncated = truncateToolResultText(args.content, args.maxChars);
-  return {
-    content: truncated,
-    truncated: truncated !== args.content,
-  };
-}
-
-const passthrough: Middleware<
-  ToolResultTruncateArgs,
-  ToolResultTruncateResult
-> = async (args, next) => next(args);
-
-/**
- * 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: "default-tool-result-truncate",
-    version: "1.0.0",
-  },
-  middleware: {
-    toolResultTruncate: passthrough,
-  },
-};
-
-// 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 `defaultToolResultTruncatePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultToolResultTruncatePlugin);
-} 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;
-  }
-}