@vellumai/assistant 0.6.4 → 0.6.6

package/src/plugins/defaults/memory-retrieval.ts

@@ -0,0 +1,226 @@
+/**
+ * Default `memoryRetrieval` plugin.
+ *
+ * Encapsulates the three retrievals the agent loop performs before building
+ * the runtime-injection block for a turn:
+ *
+ * 1. **PKB context** via {@link readPkbContext} — always-loaded workspace
+ *    notes (INDEX.md, essentials.md, …) that precede the user's message.
+ * 2. **NOW.md scratchpad** via {@link readNowScratchpad} — the short
+ *    user-maintained note the assistant keeps up to date.
+ * 3. **Memory graph** via {@link ConversationGraphMemory.prepareMemory} —
+ *    dispatches to context-load or per-turn retrieval depending on
+ *    initialization state; gated on the actor being trusted (guardian).
+ *
+ * The default plugin registers a pass-through middleware so the pipeline
+ * runner always has at least one entry and downstream telemetry observes a
+ * deterministic chain. The actual retrieval runs in the terminal supplied
+ * by the agent loop; centralizing the helper here (as
+ * {@link runDefaultMemoryRetrieval}) makes it trivial for a plugin to
+ * fall back to the default behavior by calling this helper from its own
+ * middleware.
+ *
+ * See `.private/plans/agent-plugin-system.md` PR 20 for the containing
+ * milestone.
+ */
+
+import type { AssistantConfig } from "../../config/schema.js";
+import {
+  readNowScratchpad,
+  readPkbContext,
+} from "../../daemon/conversation-runtime-assembly.js";
+import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { ConversationGraphMemory } from "../../memory/graph/conversation-graph-memory.js";
+import type { Message } from "../../providers/types.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type MemoryArgs,
+  type MemoryResult,
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+} from "../types.js";
+
+/**
+ * Discriminator the agent loop uses to narrow `MemoryResult.memoryGraphBlocks`
+ * back into the full {@link GraphMemoryPayload} shape. Plugins that substitute
+ * their own memory blocks without setting this marker will fall through the
+ * agent loop's graph-result consumption path — which is the intended escape
+ * hatch for custom retrievers.
+ */
+export const DEFAULT_MEMORY_GRAPH_KIND = "default.graph" as const;
+
+/**
+ * Shape of the single block the default memory-graph retriever emits.
+ *
+ * Mirrors the object returned by
+ * {@link ConversationGraphMemory.prepareMemory} — the agent loop consumes
+ * every field downstream (PKB query vectors, metrics persistence, memory
+ * event emission). Kept as a concrete type here so both the terminal and the
+ * agent loop can share one import.
+ */
+export interface GraphMemoryPayload {
+  readonly kind: typeof DEFAULT_MEMORY_GRAPH_KIND;
+  readonly result: Awaited<
+    ReturnType<ConversationGraphMemory["prepareMemory"]>
+  >;
+}
+
+/**
+ * External state the default retriever needs but the pipeline args cannot
+ * carry (conversation-scoped graph handle, event sink, live message list).
+ * Passed as a second argument to {@link runDefaultMemoryRetrieval} rather
+ * than threaded through {@link MemoryArgs} to keep the plugin-facing
+ * pipeline surface minimal.
+ *
+ * The per-turn abort signal lives on {@link MemoryArgs.signal} instead of
+ * here so the pipeline runner's `linkAbortSignal` can swap it for an
+ * internally-linked signal — that way a plugin timeout actually cancels
+ * the underlying `prepareMemory` work instead of letting it run after
+ * `Promise.race` has already rejected.
+ */
+export interface DefaultMemoryRetrievalDeps {
+  /** Live message list for this turn (pre-injection). */
+  readonly messages: Message[];
+  /** Per-conversation memory graph handle. */
+  readonly graphMemory: ConversationGraphMemory;
+  /** Assistant config snapshot. */
+  readonly config: AssistantConfig;
+  /** Event sink used by the graph retriever (memory_status events). */
+  readonly onEvent: (msg: ServerMessage) => void;
+  /** True when the actor for this turn is trusted (guardian-class). */
+  readonly isTrustedActor: boolean;
+}
+
+/**
+ * Run the default retrieval. Always returns a {@link MemoryResult}; skips
+ * the memory-graph call entirely when the actor is not trusted (matches the
+ * prior agent-loop gate).
+ *
+ * The returned `memoryGraphBlocks` is either empty (when the actor is not
+ * trusted) or a single {@link GraphMemoryPayload} wrapping the graph
+ * retriever's full output. The agent loop narrows via
+ * {@link DEFAULT_MEMORY_GRAPH_KIND} to consume it.
+ */
+export async function runDefaultMemoryRetrieval(
+  args: MemoryArgs,
+  deps: DefaultMemoryRetrievalDeps,
+): Promise<MemoryResult> {
+  // NOW.md and PKB are read unconditionally — the agent loop decides
+  // whether to inject them based on first-turn / post-compaction gating.
+  const pkbContent = readPkbContext();
+  const nowContent = readNowScratchpad();
+
+  if (!deps.isTrustedActor) {
+    // Untrusted actors skip memory-graph retrieval entirely — preserves the
+    // pre-plugin gate that lived inline in `conversation-agent-loop.ts`.
+    return {
+      pkbContent,
+      nowContent,
+      memoryGraphBlocks: [],
+    };
+  }
+
+  // `prepareMemory` requires a non-optional signal. In production the agent
+  // loop always threads one via `args.signal`; the fallback `AbortController`
+  // keeps direct callers (e.g. tests that skip the pipeline) working without
+  // forcing every call site to synthesize a dummy signal.
+  const abortSignal = args.signal ?? new AbortController().signal;
+  const graphResult = await deps.graphMemory.prepareMemory(
+    deps.messages,
+    deps.config,
+    abortSignal,
+    deps.onEvent,
+  );
+
+  const payload: GraphMemoryPayload = {
+    kind: DEFAULT_MEMORY_GRAPH_KIND,
+    result: graphResult,
+  };
+
+  return {
+    pkbContent,
+    nowContent,
+    memoryGraphBlocks: [payload],
+  };
+}
+
+/**
+ * Narrow a {@link MemoryResult} memory-graph block back into the full
+ * {@link GraphMemoryPayload} the default retriever emits. Returns `null` when
+ * the pipeline output came from a custom retriever (no blocks, or a block
+ * without the {@link DEFAULT_MEMORY_GRAPH_KIND} discriminator).
+ *
+ * The agent loop uses this helper to decide whether to run its downstream
+ * graph-result consumption path (query-vector propagation, metric
+ * persistence, memory-event emission). Custom retrievers that skip that
+ * path are expected to handle their own side effects inside their
+ * middleware.
+ */
+export function asDefaultGraphPayload(
+  blocks: ReadonlyArray<unknown>,
+): GraphMemoryPayload | null {
+  const first = blocks[0];
+  if (
+    first != null &&
+    typeof first === "object" &&
+    "kind" in first &&
+    (first as { kind?: unknown }).kind === DEFAULT_MEMORY_GRAPH_KIND
+  ) {
+    return first as GraphMemoryPayload;
+  }
+  return null;
+}
+
+/**
+ * Default `memoryRetrieval` middleware — a pure pass-through.
+ *
+ * Keeping a real middleware registered (rather than an empty list) makes
+ * the pipeline observable in `plugin.pipeline` logs with a non-empty
+ * `chain` field and lets third-party plugins rely on the default slot
+ * being present even when nothing is overriding it. The work happens in
+ * the terminal supplied by the agent loop, which calls
+ * {@link runDefaultMemoryRetrieval}.
+ */
+const defaultMemoryRetrievalMiddleware: Middleware<MemoryArgs, MemoryResult> =
+  async function defaultMemoryRetrieval(args, next) {
+    return next(args);
+  };
+
+/**
+ * Default plugin exposing the `memoryRetrieval` pipeline slot. Registered
+ * by {@link registerDefaultMemoryRetrievalPlugin} from the plugin
+ * bootstrap wiring so ordering is deterministic across boots.
+ */
+export const defaultMemoryRetrievalPlugin: Plugin = {
+  manifest: {
+    name: "default-memory-retrieval",
+    version: "0.0.1",
+    requires: { pluginRuntime: "v1", memoryApi: "v1" },
+  },
+  middleware: {
+    memoryRetrieval: defaultMemoryRetrievalMiddleware,
+  },
+};
+
+// 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 `defaultMemoryRetrievalPlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultMemoryRetrievalPlugin);
+} 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/overflow-reduce.ts

@@ -0,0 +1,181 @@
+/**
+ * Default `overflowReduce` plugin — extracted verbatim from the inline
+ * preflight reducer loop that previously lived in
+ * `daemon/conversation-agent-loop.ts` (the `while (preflightAttempts < …)`
+ * block around lines 1045–1156 before PR 23).
+ *
+ * The plugin owns the reducer tier-loop (forced compaction, tool-result
+ * truncation, media stubbing, injection downgrade) and the post-step
+ * re-injection / re-estimation dance. Orchestrator-specific coupling
+ * (activity emission, circuit-breaker tracking, compaction-result
+ * application, runtime injection reassembly) is threaded in through the
+ * callbacks carried on {@link OverflowReduceArgs}; the plugin itself has no
+ * access to the agent-loop context object.
+ *
+ * Internal calls to `ContextWindowManager` remain direct — pipeline layering
+ * ends at the top of the reducer, not within the forced-compaction tier.
+ * The supplied `compactFn` delegates straight into the context window
+ * manager, so only the tier-loop orchestration goes through the pipeline
+ * runner.
+ */
+
+import type { ContextWindowCompactOptions } from "../../context/window-manager.js";
+import {
+  createInitialReducerState,
+  reduceContextOverflow,
+  type ReducerState,
+} from "../../daemon/context-overflow-reducer.js";
+import { registerPlugin } from "../registry.js";
+import {
+  type Middleware,
+  type OverflowReduceArgs,
+  type OverflowReduceResult,
+  type Plugin,
+  PluginExecutionError,
+} from "../types.js";
+
+/**
+ * Default middleware — implements the historical tier-loop semantics.
+ *
+ * The middleware intentionally ignores `next`. Overflow reduction is a
+ * *terminal* behavior: there is no downstream implementation to defer to
+ * when a user-supplied middleware short-circuits. Later plugins may still
+ * wrap this one (outer middleware can observe each reduction iteration via
+ * their own `next` callback) but the default never delegates to a
+ * hypothetical base handler — the inline loop was the base.
+ */
+export const defaultOverflowReduceMiddleware: Middleware<
+  OverflowReduceArgs,
+  OverflowReduceResult
+> = async function defaultOverflowReduceMiddleware(args, _next, _ctx) {
+  let messages = args.messages;
+  let runMessages = args.runMessages;
+  let injectionMode: "full" | "minimal" = "full";
+  let reducerState: ReducerState = createInitialReducerState();
+  let reducerCompacted = false;
+  let attempts = 0;
+
+  while (attempts < args.maxAttempts && !reducerState.exhausted) {
+    // Abort check at the top of every iteration. When the pipeline runner
+    // arms a timeout (or the caller aborts externally), `args.abortSignal`
+    // is linked to that trigger via `linkAbortSignal`, so this check lets
+    // us bail out BETWEEN iterations rather than letting another round of
+    // compaction / re-injection mutate `ctx.messages` after the turn has
+    // already failed. Individual `reduceContextOverflow` calls also honor
+    // the signal, but without this gate a fresh iteration could still
+    // start after the signal fires, since the previous one returned
+    // normally before the abort propagated.
+    args.abortSignal?.throwIfAborted();
+
+    attempts++;
+    args.emitActivityState();
+
+    const step = await reduceContextOverflow(
+      messages,
+      {
+        providerName: args.providerName,
+        systemPrompt: args.systemPrompt,
+        contextWindow: args.contextWindow,
+        targetTokens: args.preflightBudget,
+        toolTokenBudget: args.toolTokenBudget,
+      },
+      reducerState,
+      (msgs, signal, opts: ContextWindowCompactOptions) =>
+        args.compactFn(msgs, signal, opts),
+      args.abortSignal,
+    );
+
+    reducerState = step.state;
+    messages = step.messages;
+    injectionMode = step.state.injectionMode;
+
+    // Per-iteration compaction flag: whether THIS step just produced a
+    // fresh compaction. PKB / NOW re-injection is gated on this — see the
+    // reinjectForMode JSDoc for why the two signals differ.
+    const stepCompacted = step.compactionResult?.compacted === true;
+
+    // Let the orchestrator apply compaction side effects (circuit-breaker
+    // tracking, event emission, ctx mutation) before we re-inject.
+    if (step.compactionResult) {
+      await args.onCompactionResult(step.compactionResult);
+      if (stepCompacted) {
+        reducerCompacted = true;
+      }
+    }
+
+    // Second abort gate — if the side effects or the step itself took us
+    // past the deadline, don't rebuild runMessages or iterate again.
+    args.abortSignal?.throwIfAborted();
+
+    // Rebuild runMessages via the orchestrator-supplied helper (which
+    // re-runs `applyRuntimeInjections` with potentially downgraded mode
+    // and freshly re-hydrated PKB/NOW blocks after compaction). We pass
+    // the current reduced `messages` explicitly so the orchestrator never
+    // has to read from mutable shared state to rebuild runMessages — a
+    // tier that doesn't trigger compaction (tool-result truncation, media
+    // stubbing) won't update `ctx.messages` on its own.
+    //
+    // `stepCompacted` and `reducerCompacted` are both passed so the
+    // orchestrator can gate PKB / NOW re-injection per-iteration while
+    // keeping `slackChronologicalMessages` suppressed once any iteration
+    // has compacted.
+    runMessages = await args.reinjectForMode(
+      messages,
+      injectionMode,
+      stepCompacted,
+      reducerCompacted,
+    );
+
+    // Re-estimate with injections included — `step.estimatedTokens` was
+    // computed on bare history and doesn't account for tokens added by
+    // runtime injections.
+    const postInjectionTokens = args.estimatePostInjection(runMessages);
+    if (postInjectionTokens <= args.preflightBudget) break;
+  }
+
+  return {
+    messages,
+    runMessages,
+    injectionMode,
+    reducerState,
+    reducerCompacted,
+    attempts,
+  };
+};
+
+/**
+ * The default plugin registered at bootstrap. No `init`/`onShutdown` —
+ * registering the middleware is the only behavior.
+ */
+export const defaultOverflowReducePlugin: Plugin = {
+  manifest: {
+    name: "default-overflow-reduce",
+    version: "1.0.0",
+    requires: { pluginRuntime: "v1", overflowReduceApi: "v1" },
+  },
+  middleware: {
+    overflowReduce: defaultOverflowReduceMiddleware,
+  },
+};
+
+// 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 `defaultOverflowReducePlugin` identifier —
+// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
+// other default plugin and directly import this file.
+try {
+  registerPlugin(defaultOverflowReducePlugin);
+} 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

@@ -0,0 +1,129 @@
+/**
+ * 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",
+    provides: { persistence: "v1" },
+    requires: { pluginRuntime: "v1" },
+  },
+  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

@@ -0,0 +1,95 @@
+/**
+ * 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",
+    provides: { titleGenerate: "v1" },
+    requires: {
+      pluginRuntime: "v1",
+      titleGenerateApi: "v1",
+    },
+  },
+};
+
+// 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;
+  }
+}