@vellumai/assistant 0.8.5 → 0.8.7

package/src/plugins/defaults/circuit-breaker.ts

@@ -1,141 +0,0 @@
-/**
- * Default `circuitBreaker` plugin.
- *
- * Replicates the inline compaction circuit-breaker logic that previously
- * lived in `daemon/conversation-agent-loop.ts`: three consecutive summary-LLM
- * failures open the circuit for a one-hour cooldown, and any successful
- * compaction resets the counter.
- *
- * The plugin is a thin wrapper over the state container passed in
- * `CircuitBreakerArgs.state`. The {@link Conversation} owns the underlying
- * fields (`consecutiveCompactionFailures`, `compactionCircuitOpenUntil`)
- * because dev-only playground routes (`POST /playground/reset-compaction-circuit`,
- * `POST /playground/inject-compaction-failures`) read and mutate them
- * directly. Keeping ownership on the conversation lets this plugin stay a
- * pure wrapper while preserving those hatches.
- *
- * Semantics — query vs update:
- * - `{ key }` — query. Returns the current `{ open, cooldownRemainingMs? }`.
- * - `{ key, outcome }` — update state based on outcome, then return the
- *   post-update decision. A run of three failures trips the breaker; any
- *   non-failure outcome resets both the counter and the cooldown timestamp.
- *
- * Event emission — preserves the existing `trackCompactionOutcome` behavior:
- * - Emits `compaction_circuit_open` exactly once when the counter first
- *   reaches the threshold and the circuit is dormant (null or expired).
- * - Emits `compaction_circuit_closed` only on the open→closed transition.
- *   Successive successful outcomes while the circuit is already closed emit
- *   nothing (would otherwise spam the client).
- *
- * The `key` parameter is carried through for multi-circuit futures but the
- * default plugin currently bundles all circuit state into the `state`
- * container; the key is attached to the log record via the pipeline runner.
- */
-
-import { registerPlugin } from "../registry.js";
-import { type Plugin, PluginExecutionError } from "../types.js";
-
-/**
- * Consecutive failures required to trip the breaker. Matches the legacy
- * `COMPACTION_CIRCUIT_FAILURE_THRESHOLD` in `conversation-agent-loop.ts`.
- */
-export const COMPACTION_CIRCUIT_FAILURE_THRESHOLD = 3;
-
-/**
- * Cooldown window after the breaker trips, during which auto-compaction is
- * suspended. Matches the legacy `COMPACTION_CIRCUIT_COOLDOWN_MS`.
- */
-export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
-
-/**
- * Default plugin registered at daemon startup. Consumers negotiate against
- * `circuitBreakerApi@v1` via the registry's capability table.
- */
-export const defaultCircuitBreakerPlugin: Plugin = {
-  manifest: {
-    name: "default-circuit-breaker",
-    version: "1.0.0",
-  },
-
-  middleware: {
-    circuitBreaker: async (args, next) => {
-      const { outcome, state, onEvent } = args;
-
-      // Update branch — mutate state first, then defer to the downstream
-      // chain (or terminal) for the decision so outer observers still see
-      // the fully-processed outcome. Separating state mutation from
-      // decision computation also keeps this middleware composable: an
-      // outer plugin may wrap the invocation to observe both the pre-update
-      // args and the post-update result.
-      if (outcome !== undefined) {
-        if (outcome === "failure") {
-          state.consecutiveCompactionFailures += 1;
-          // Treat a stale/expired open-until timestamp the same as null so
-          // a new 3-strike window can re-open the circuit after the prior
-          // cooldown elapses. Without this, subsequent trips would no-op
-          // because `compactionCircuitOpenUntil` remains set to a past
-          // timestamp even though the breaker is effectively closed.
-          const circuitDormant =
-            state.compactionCircuitOpenUntil === null ||
-            Date.now() >= state.compactionCircuitOpenUntil;
-          if (
-            state.consecutiveCompactionFailures >=
-              COMPACTION_CIRCUIT_FAILURE_THRESHOLD &&
-            circuitDormant
-          ) {
-            const openUntil = Date.now() + COMPACTION_CIRCUIT_COOLDOWN_MS;
-            state.compactionCircuitOpenUntil = openUntil;
-            if (onEvent) {
-              onEvent({
-                type: "compaction_circuit_open",
-                conversationId: state.conversationId,
-                reason: "3_consecutive_failures",
-                openUntil,
-              });
-            }
-          }
-        } else {
-          // Emit only on the open→closed transition; firing on the common
-          // closed→closed case would be noise.
-          const wasOpen = state.compactionCircuitOpenUntil !== null;
-          state.consecutiveCompactionFailures = 0;
-          state.compactionCircuitOpenUntil = null;
-          if (wasOpen && onEvent) {
-            onEvent({
-              type: "compaction_circuit_closed",
-              conversationId: state.conversationId,
-            });
-          }
-        }
-      }
-
-      // Defer to downstream (the terminal, in the default registration, but
-      // potentially another plugin in a customized chain) for the final
-      // decision. The terminal's implementation is the canonical read of
-      // the (now-updated) state container.
-      return next(args);
-    },
-  },
-};
-
-// 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 `defaultCircuitBreakerPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultCircuitBreakerPlugin);
-} 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/compaction.ts

@@ -1,141 +0,0 @@
-/**
- * Default `compaction` plugin.
- *
- * Delegates to the orchestrator's existing
- * {@link import("../../context/window-manager.js").ContextWindowManager}
- * instance. No behavior change relative to the pre-plugin call site — the
- * plugin only exists so custom plugins registered in later PRs can observe
- * arguments, short-circuit to a different summary, or post-process the
- * {@link import("../../context/window-manager.js").ContextWindowResult}
- * before the orchestrator consumes it.
- *
- * Lookup: the default middleware reads `ctx.contextWindowManager` from the
- * {@link TurnContext} as a typed optional field. The orchestrator is
- * responsible for attaching that handle to the per-turn context it hands to
- * {@link runPipeline}. If the handle is missing, the middleware throws a
- * {@link PluginExecutionError} so the bug surfaces with clear attribution
- * instead of a late `undefined.maybeCompact is not a function`.
- *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
- */
-
-import type {
-  ContextWindowCompactOptions,
-  ContextWindowManager,
-  ContextWindowResult,
-} from "../../context/window-manager.js";
-import type { Message } from "../../providers/types.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type CompactionArgs,
-  type CompactionResult,
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-  type TurnContext,
-} from "../types.js";
-
-/**
- * Name under which the default plugin registers. Exposed so tests and later
- * plugins can assert registration order or override the default via
- * composition.
- */
-export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
-
-/**
- * Read `contextWindowManager` off the turn context. Throws
- * {@link PluginExecutionError} when absent so the failure attributes cleanly
- * to the default plugin instead of manifesting as a later NPE.
- */
-function extractManager(ctx: TurnContext): ContextWindowManager {
-  const manager = ctx.contextWindowManager;
-  if (
-    manager == null ||
-    typeof manager !== "object" ||
-    typeof (manager as { maybeCompact?: unknown }).maybeCompact !== "function"
-  ) {
-    throw new PluginExecutionError(
-      "default-compaction: ctx.contextWindowManager is missing — orchestrator must attach it before invoking the compaction pipeline",
-      DEFAULT_COMPACTION_PLUGIN_NAME,
-    );
-  }
-  return manager;
-}
-
-/**
- * Default terminal behavior. Exposed as a standalone function (rather than
- * inlined in the plugin object) so the orchestrator can pass it directly to
- * {@link runPipeline} as the terminal handler. Keeping terminal-vs-middleware
- * separate avoids a wasted `next → terminal` hop when no custom plugin
- * observes the slot.
- */
-export async function defaultCompactionTerminal(
-  args: CompactionArgs,
-  ctx: TurnContext,
-): Promise<CompactionResult> {
-  const manager = extractManager(ctx);
-  const messages = args.messages as Message[];
-  const options = args.options as ContextWindowCompactOptions | undefined;
-  const result: ContextWindowResult = await manager.maybeCompact(
-    messages,
-    args.signal,
-    options,
-  );
-  return result;
-}
-
-/**
- * Middleware wrapper around {@link defaultCompactionTerminal}. Registered via
- * {@link defaultCompactionPlugin} so tests that compose middleware through the
- * registry (rather than passing a terminal to `runPipeline` directly) see a
- * working no-op default. In production the orchestrator passes
- * {@link defaultCompactionTerminal} as the terminal and this middleware is
- * never hit.
- */
-const defaultCompactionMiddleware: Middleware<
-  CompactionArgs,
-  CompactionResult
-> = async function defaultCompaction(args, next, ctx) {
-  // Invoke `next` so any custom plugins layered outside us still run; when
-  // we're the only middleware, `next` is the terminal and returns the real
-  // compaction output.
-  void ctx;
-  return next(args);
-};
-
-/**
- * Manifest + middleware wiring for the default compaction plugin. The
- * registration happens in `daemon/external-plugins-bootstrap.ts` before
- * {@link bootstrapPlugins} fires plugin `init()` hooks.
- */
-export const defaultCompactionPlugin: Plugin = {
-  manifest: {
-    name: DEFAULT_COMPACTION_PLUGIN_NAME,
-    version: "1.0.0",
-  },
-  middleware: {
-    compaction: defaultCompactionMiddleware,
-  },
-};
-
-// 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 `defaultCompactionPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultCompactionPlugin);
-} 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/empty-response.ts

@@ -1,124 +0,0 @@
-/**
- * Default `emptyResponse` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual decision lives in
- * {@link defaultEmptyResponseTerminal}, 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
- * decide directly without calling `next`, it would shadow every
- * later-registered plugin. Routing through `next(args)` lets user middleware
- * participate normally.
- *
- * Wiring the terminal at the call site (rather than relying on the plugin to
- * be registered) also means the loop's nudge/accept/error behavior survives
- * configurations that boot without the default plugin — e.g. unit tests that
- * skip `bootstrapPlugins()`.
- *
- * The terminal inspects the turn snapshot and returns one of:
- *
- * 1. `"nudge"`  — the turn produced no visible text, no tool calls, follows
- *                 at least one prior tool-use turn, no earlier turn in this
- *                 run() has already delivered visible text, AND the retry
- *                 counter is below `maxEmptyResponseRetries`. The loop
- *                 appends `nudgeText` (the `<system_notice>…` message below)
- *                 as a `user` turn and re-queries the model.
- * 2. `"accept"` — every other case. The turn either legitimately ended
- *                 (model said its piece earlier), is still in progress
- *                 (tool calls pending), or exhausted its retry budget. The
- *                 loop pushes the assistant message and continues normally.
- *
- * The default never returns `"error"` — that action is an escape hatch for
- * downstream plugins (e.g. a circuit breaker) that want to surface an
- * explicit error instead of silently absorbing an empty turn.
- *
- * `MAX_EMPTY_RESPONSE_RETRIES` lives in `agent/loop.ts` and is threaded into
- * the pipeline via `EmptyResponseArgs.maxEmptyResponseRetries` so the cap is
- * declared in one place only.
- */
-
-import { registerPlugin } from "../registry.js";
-import {
-  type EmptyResponseArgs,
-  type EmptyResponseResult,
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
-
-/**
- * Canonical nudge text. Must stay verbatim so a plugin that wraps the
- * default cannot accidentally see a different string.
- *
- * Wire-compat note: this is shown to the LLM, not the user. Edits here
- * affect model behavior but not end-user UX directly.
- */
-const NUDGE_TEXT =
-  "<system_notice>Your previous response was empty. You must respond to the user with a summary of what you found or did. Do not use any tools — just respond with text.</system_notice>";
-
-/**
- * Terminal handler for the `emptyResponse` 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 defaultEmptyResponseTerminal(
-  args: EmptyResponseArgs,
-): EmptyResponseResult {
-  const hasVisibleText = args.responseContent.some(
-    (block) =>
-      block.type === "text" &&
-      typeof (block as { text?: unknown }).text === "string" &&
-      (block as { text: string }).text.trim().length > 0,
-  );
-
-  const isEmptyTurn =
-    !hasVisibleText &&
-    args.toolUseBlocksLength === 0 &&
-    args.toolUseTurns > 0 &&
-    !args.priorAssistantHadVisibleText;
-
-  if (isEmptyTurn && args.emptyResponseRetries < args.maxEmptyResponseRetries) {
-    return { action: "nudge", nudgeText: NUDGE_TEXT };
-  }
-  return { action: "accept" };
-}
-
-const passthrough: Middleware<EmptyResponseArgs, EmptyResponseResult> = async (
-  args,
-  next,
-) => next(args);
-
-/** Singleton plugin — the registry rejects duplicate registrations by name. */
-export const defaultEmptyResponsePlugin: Plugin = {
-  manifest: {
-    name: "default-empty-response",
-    version: "1.0.0",
-  },
-  middleware: {
-    emptyResponse: 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 `defaultEmptyResponsePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultEmptyResponsePlugin);
-} 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/history-repair.ts

@@ -1,83 +0,0 @@
-/**
- * Default `historyRepair` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual repair lives in
- * {@link defaultHistoryRepairTerminal}, 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.
- * Routing through `next(args)` lets user middleware participate normally.
- *
- * Plugins that override this middleware receive both `history` and `provider`
- * so they can route behavior per provider (e.g. strip blocks a specific
- * provider can't handle) without reaching into ambient state.
- *
- * Scope: this pipeline wraps only the standard pre-run repair (`repairHistory`).
- * The orchestrator's one-shot deep-repair fallback (`deepRepairHistory`),
- * invoked only after a provider ordering error, intentionally bypasses the
- * pipeline today — see the design note at the `deepRepairHistory` call site
- * in `daemon/conversation-agent-loop.ts`.
- */
-
-import { repairHistory } from "../../daemon/history-repair.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type HistoryRepairArgs,
-  type HistoryRepairResult,
-  type Middleware,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
-
-/**
- * Terminal handler for the `historyRepair` pipeline. 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 function defaultHistoryRepairTerminal(
-  args: HistoryRepairArgs,
-): HistoryRepairResult {
-  return repairHistory(args.history);
-}
-
-const passthrough: Middleware<HistoryRepairArgs, HistoryRepairResult> = async (
-  args,
-  next,
-) => next(args);
-
-export const defaultHistoryRepairPlugin: Plugin = {
-  manifest: {
-    name: "default-history-repair",
-    version: "1.0.0",
-  },
-  middleware: {
-    historyRepair: 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 `defaultHistoryRepairPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultHistoryRepairPlugin);
-} 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/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;
-  }
-}