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

package/src/plugins/defaults/index.ts

@@ -7,47 +7,37 @@
  *
  * Consumers:
  *
- * - `daemon/external-plugins-bootstrap.ts` — production/registry boot path;
- *   calls {@link registerDefaultPlugins} inside `bootstrapPlugins()`.
+ * - `daemon/external-plugins-bootstrap.ts` — the daemon's `initializePlugins()`
+ *   calls {@link registerDefaultPlugins} explicitly at startup, before
+ *   `loadUserPlugins()` closes the registration window, so the defaults compose
+ *   innermost (ahead of any user plugins). `bootstrapPlugins()` replays it;
+ *   idempotent, so already-registered defaults are skipped.
  * - integration tests that reset the registry and then need a
  *   production-parity state (e.g. `conversation-agent-loop.test.ts`); those
  *   call {@link resetPluginRegistryAndRegisterDefaults}.
  *
- * Each `defaults/<name>.ts` module self-registers at module load via a local
- * side effect. Importing this aggregator (or any individual default file)
- * populates the registry — the self-registration is idempotent, and so are
- * {@link registerDefaultPlugins} and {@link resetPluginRegistryAndRegisterDefaults}.
- * Per-file self-registration is what keeps registration attached to each
- * file's own already-initialized plugin identifier, so importing
- * `defaults/index.ts` mid-cycle (e.g. through the
- * `memory-retrieval.ts` → … → `pipeline.ts` → `defaults/index.ts`
- * chain) does not trip a TDZ.
+ * Each `defaults/<name>/register.ts` module only builds and exports its
+ * `Plugin` object; registration is centralized here. The plugin identifiers
+ * are dereferenced inside {@link registerDefaultPlugins} at call time, once
+ * every module has finished initializing, so importing this aggregator does no
+ * registration work.
  */
 
-import { memoryV3ShadowPlugin } from "../../memory/v3/shadow-middleware.js";
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
-import { defaultCircuitBreakerPlugin } from "./circuit-breaker.js";
-import { defaultCompactionPlugin } from "./compaction.js";
-import { defaultEmptyResponsePlugin } from "./empty-response.js";
-import { defaultHistoryRepairPlugin } from "./history-repair.js";
-import { defaultInjectorsPlugin } from "./injectors.js";
-import { defaultLlmCallPlugin } from "./llm-call.js";
-import { defaultMemoryRetrievalPlugin } from "./memory-retrieval.js";
-import { defaultOverflowReducePlugin } from "./overflow-reduce.js";
-import { defaultPersistencePlugin } from "./persistence.js";
-import { defaultTitleGeneratePlugin } from "./title-generate.js";
-import { defaultTokenEstimatePlugin } from "./token-estimate.js";
-import { defaultToolErrorPlugin } from "./tool-error.js";
-import { defaultToolExecutePlugin } from "./tool-execute.js";
-import { defaultToolResultTruncatePlugin } from "./tool-result-truncate.js";
+import { defaultCompactionPlugin } from "./compaction/register.js";
+import { defaultEmptyResponsePlugin } from "./empty-response/register.js";
+import { defaultHistoryRepairPlugin } from "./history-repair/register.js";
+import { memoryV3ShadowPlugin } from "./memory-v3-shadow/register.js";
+import { defaultTitleGeneratePlugin } from "./title-generate/register.js";
+import { defaultToolErrorPlugin } from "./tool-error/register.js";
+import { defaultToolResultTruncatePlugin } from "./tool-result-truncate/register.js";
 
 /**
  * Full set of first-party default plugins. Used by
- * {@link registerDefaultPlugins} to drive the idempotent re-registration
- * loop; actual registration-order in the registry is determined by the
- * module-load side effects in each per-file default (whichever loader
- * evaluates a file first wins, later attempts are swallowed as duplicates).
+ * {@link registerDefaultPlugins} to drive the registration loop; the array
+ * order is the registration order, which determines onion order for middleware
+ * composition (defaults innermost, user plugins outermost).
  *
  * Returned by a function rather than a top-level `const` so the array
  * contents are read at call time, after every imported plugin identifier is
@@ -55,25 +45,13 @@ import { defaultToolResultTruncatePlugin } from "./tool-result-truncate.js";
  */
 function getAllDefaultPlugins(): readonly Plugin[] {
   return [
-    defaultLlmCallPlugin,
-    defaultToolExecutePlugin,
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
-    defaultMemoryRetrievalPlugin,
-    // Live-shadow v3 retrieval. Always registered; inert unless both
-    // `memory.v3.enabled` and `memory.v3.shadow` are on (gated inside the
-    // middleware). Ordered after the default so the default terminal still
-    // produces the injected (v2) `MemoryResult`.
-    memoryV3ShadowPlugin,
-    defaultInjectorsPlugin,
-    defaultTokenEstimatePlugin,
-    defaultOverflowReducePlugin,
     defaultHistoryRepairPlugin,
     defaultCompactionPlugin,
-    defaultCircuitBreakerPlugin,
-    defaultPersistencePlugin,
     defaultTitleGeneratePlugin,
+    memoryV3ShadowPlugin,
   ];
 }
 
@@ -83,11 +61,6 @@ function getAllDefaultPlugins(): readonly Plugin[] {
  * an "already registered" message) are swallowed so repeat bootstrap or test
  * setup calls do not throw. Every other error (shape failure, version
  * mismatch) re-throws.
- *
- * In practice every call after the first is a no-op: each default's
- * module-load side effect registers itself the first time its file is
- * imported, which for production happens via `pipeline.ts`'s side-effect
- * import of this aggregator.
  */
 export function registerDefaultPlugins(): void {
   for (const plugin of getAllDefaultPlugins()) {
@@ -110,7 +83,7 @@ export function registerDefaultPlugins(): void {
  * so integration tests that exercise the full agent loop have a
  * production-parity plugin stack. Use this in `beforeEach` of tests that
  * dispatch through pipelines with a terminal that assumes the default
- * plugin handles every op (e.g. persistence, overflowReduce).
+ * plugin handles every op (e.g. compaction).
  *
  * Tests that specifically need an empty registry (pipeline-unit tests, the
  * plugin-registry tests themselves) should continue to call

package/src/plugins/defaults/memory-retrieval/hooks/post-compact.ts

@@ -0,0 +1,95 @@
+/**
+ * Default `memoryRetrieval` post-compaction hook.
+ *
+ * After the agent loop compacts a conversation mid-turn it must re-apply the
+ * runtime injections compaction stripped — the NOW.md scratchpad, PKB context,
+ * memory-v2 static block, workspace top-level context, and Slack chronological
+ * snapshot — onto the compacted history before the turn continues. This hook
+ * is the memory system's home for that transform: it receives the message
+ * history plus the resolved runtime-injection options and returns the edited
+ * history (and the blocks it captured), with no dependency on the agent loop's
+ * closure state.
+ *
+ * It re-applies the runtime injections via {@link applyRuntimeInjections},
+ * re-tracks the memory graph's cached nodes against the re-injected history,
+ * and converts now-historical `web_search_tool_result` blocks to text so their
+ * expired `encrypted_content` tokens are not replayed. The remaining
+ * orchestrator-side step (the post-injection bookkeeping the loop records) is
+ * expected to migrate here as the hook subsumes the loop's re-injection
+ * ceremony.
+ *
+ * The memory graph handle is sourced internally from the plugin's own
+ * conversation-keyed registry ({@link getLiveGraphMemory}) rather than being
+ * threaded in by the loop — it is memory-retrieval-specific state, not
+ * something the generic loop or the shared {@link TurnContext} should carry.
+ */
+
+import {
+  applyRuntimeInjections,
+  type RuntimeInjectionOptions,
+  type RuntimeInjectionResult,
+} from "../../../../daemon/conversation-runtime-assembly.js";
+import { resolveTrustClass } from "../../../../daemon/trust-context.js";
+import { stripHistoricalWebSearchResults } from "../../../../daemon/web-search-history.js";
+import { getLiveGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
+import type { PluginLogger } from "../../../../plugin-api/types.js";
+import type { Message } from "../../../../providers/types.js";
+import type { TurnContext } from "../../../types.js";
+
+/**
+ * The slice of the hook's context the agent loop supplies from its own working
+ * state. Re-injection inputs migrate loop-ward by growing this type; the loop
+ * hands the hook an object of this shape via
+ * {@link MidLoopCompaction.postCompactionHook}.
+ */
+export interface PostCompactionHookInput {
+  /** Compacted message history to re-inject onto. */
+  history: Message[];
+  /** Per-turn conversation context forwarded to the injector chain. */
+  turnContext?: TurnContext;
+}
+
+/**
+ * Everything the hook needs in a single context: the loop-supplied
+ * {@link PostCompactionHookInput}, the resolved {@link RuntimeInjectionOptions}
+ * (spread top-level so each field stays individually addressable), and a
+ * turn-scoped logger. The memory graph handle is not part of this context —
+ * the hook sources it internally via {@link getLiveGraphMemory} — and the
+ * actor's trust class is derived from {@link PostCompactionHookInput.turnContext}
+ * rather than threaded in.
+ */
+export interface PostCompactContext
+  extends RuntimeInjectionOptions, PostCompactionHookInput {
+  /** Turn-scoped logger for diagnostics emitted while re-injecting. */
+  logger: PluginLogger;
+}
+
+export default async function postCompactReinject(
+  ctx: PostCompactContext,
+): Promise<RuntimeInjectionResult> {
+  const { history, logger, ...options } = ctx;
+  const result = await applyRuntimeInjections(history, options);
+  // Re-track the nodes the memory graph last injected so they survive against
+  // the re-injected history. Untrusted actors and minimal-mode turns never
+  // received a memory-graph injection, so there is nothing to re-track. The
+  // actor's trust class is derived from the turn's own trust context (the same
+  // value the injector chain resolves), not threaded in from the loop. The
+  // live graph handle is looked up from the plugin's own registry by the
+  // turn's conversation id — the same instance the turn's retrieval mutated,
+  // so re-tracking sees the real cached-node state.
+  const isTrustedActor =
+    resolveTrustClass(options.turnContext?.trust) === "guardian";
+  if (isTrustedActor && options.mode !== "minimal") {
+    getLiveGraphMemory(
+      options.turnContext?.conversationId,
+    )?.retrackCachedNodes();
+  }
+  const strip = stripHistoricalWebSearchResults(result.messages);
+  if (strip.stats.blocksStripped > 0) {
+    logger.info(
+      { phase: "mid-loop-compact", ...strip.stats },
+      "Converted historical web_search_tool_result blocks to text summaries",
+    );
+  }
+  return { ...result, messages: strip.messages };
+}

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.ts

@@ -0,0 +1,216 @@
+/**
+ * Default `user-prompt-submit-temp` hook: runs the memory-graph retrieval the
+ * agent loop needs before building a turn's runtime-injection block.
+ *
+ * **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 hook also owns the retrieval's side effects — persisting the injected
+ * block onto the user message's metadata, writing the recall log, and emitting
+ * the `memory_recalled` event — so the loop only consumes the turn-scoped
+ * `latestMessages` written back onto the context. The PKB query-vector pair is
+ * recorded on the conversation's graph handle for the PKB-reminder injector to
+ * read back. PKB context and NOW.md are sourced directly by their injectors
+ * (gated on block presence), not produced here.
+ *
+ * This fires at the early "prompt submitted, before context assembly" moment,
+ * distinct from the canonical late `user-prompt-submit` hook (history repair,
+ * title): memory's outputs feed the injection and overflow-reduction transforms
+ * that run between the two moments. The `-temp` suffix marks this as a
+ * transitional staging point that folds into `user-prompt-submit` once
+ * compaction is cleared from the gap between the two call sites.
+ */
+
+import type { PluginHookFn } from "@vellumai/plugin-api";
+import type { Logger } from "pino";
+
+import type { AssistantConfig } from "../../../../config/schema.js";
+import type { ServerMessage } from "../../../../daemon/message-protocol.js";
+import type { MemoryRecalled } from "../../../../daemon/message-types/memory.js";
+import { updateMessageMetadata } from "../../../../memory/conversation-crud.js";
+import type { ConversationGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
+import { recordMemoryRecallLog } from "../../../../memory/memory-recall-log-store.js";
+import type { Message } from "../../../../providers/types.js";
+import type { GraphMemoryResult } from "../../../types.js";
+
+/**
+ * Context threaded through the `user-prompt-submit-temp` hook. The readonly
+ * fields carry the conversation-scoped state the retriever needs (graph
+ * handle, event sink, abort signal); the output fields are populated by the
+ * hook and read back by the agent loop. `latestMessages` straddles both: the
+ * loop seeds it with the pre-injection array and the hook overwrites it with
+ * the injected result.
+ */
+export interface MemoryRetrievalHookContext {
+  /** Per-conversation memory graph handle. */
+  readonly graphMemory: ConversationGraphMemory;
+  /** Assistant config snapshot. */
+  readonly config: AssistantConfig;
+  /** Event sink used by the graph retriever and `memory_recalled` emission. */
+  readonly onEvent: (msg: ServerMessage) => void;
+  /** True when the actor for this turn is trusted (guardian-class). */
+  readonly isTrustedActor: boolean;
+  /** Conversation the turn belongs to — keys the recall-log row. */
+  readonly conversationId: string;
+  /** User message the injected memory block is persisted onto. */
+  readonly userMessageId: string;
+  /** Turn-scoped logger for non-fatal persistence warnings. */
+  readonly logger: Logger;
+  /**
+   * Per-turn abort signal forwarded to `prepareMemory`. An external cancel
+   * aborts the underlying retrieval instead of letting it run to completion.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Working message list for the turn. Seeded by the loop with the
+   * pre-injection messages and consumed as the retrieval input; the hook
+   * overwrites it with the memory-graph block injected, or leaves it
+   * unchanged when no graph retrieval ran (untrusted actor, or a no-op
+   * retrieval). Read back by the loop.
+   */
+  latestMessages: Message[];
+}
+
+/**
+ * Persist and broadcast the retrieval's side effects: the injected block on
+ * the user message's metadata (so it survives reloads), a recall-log row, and
+ * the `memory_recalled` debug event. All three are best-effort — a failure to
+ * persist must not abort the turn.
+ */
+function recordRecallSideEffects(
+  graphResult: GraphMemoryResult,
+  ctx: MemoryRetrievalHookContext,
+): void {
+  // Persist the injected block text in message metadata so it survives
+  // conversation reloads (eviction, restart, fork). loadFromDb re-injects
+  // from metadata.
+  if (graphResult.injectedBlockText) {
+    try {
+      updateMessageMetadata(ctx.userMessageId, {
+        memoryInjectedBlock: graphResult.injectedBlockText,
+      });
+    } catch (err) {
+      ctx.logger.warn(
+        { err },
+        "Failed to persist memory injection to metadata (non-fatal)",
+      );
+    }
+  }
+
+  const m = graphResult.metrics;
+
+  try {
+    recordMemoryRecallLog({
+      conversationId: ctx.conversationId,
+      enabled: true,
+      degraded: false,
+      provider: m?.embeddingProvider ?? undefined,
+      model: m?.embeddingModel ?? undefined,
+      semanticHits: m?.semanticHits ?? 0,
+      mergedCount: m?.mergedCount ?? 0,
+      selectedCount: m?.selectedCount ?? 0,
+      tier1Count: m?.tier1Count ?? 0,
+      tier2Count: m?.tier2Count ?? 0,
+      hybridSearchLatencyMs: m?.hybridSearchLatencyMs ?? 0,
+      sparseVectorUsed: m?.sparseVectorUsed ?? false,
+      injectedTokens: graphResult.injectedTokens,
+      latencyMs: graphResult.latencyMs,
+      topCandidatesJson: (m?.topCandidates ?? []).map((c) => ({
+        key: c.nodeId,
+        type: c.type,
+        kind: "graph",
+        finalScore: c.score,
+        semantic: c.semanticSimilarity,
+        recency: c.recencyBoost,
+      })),
+      injectedText: graphResult.injectedBlockText ?? undefined,
+      reason: `graph:${graphResult.mode}`,
+      queryContext: m?.queryContext ?? undefined,
+    });
+  } catch (err) {
+    ctx.logger.warn({ err }, "Failed to persist memory recall log (non-fatal)");
+  }
+
+  if (m) {
+    const memoryRecalledEvent: MemoryRecalled = {
+      type: "memory_recalled",
+      provider: m.embeddingProvider ?? "unknown",
+      model: m.embeddingModel ?? "unknown",
+      semanticHits: m.semanticHits,
+      mergedCount: m.mergedCount,
+      selectedCount: m.selectedCount,
+      tier1Count: m.tier1Count,
+      tier2Count: m.tier2Count,
+      hybridSearchLatencyMs: m.hybridSearchLatencyMs,
+      sparseVectorUsed: m.sparseVectorUsed,
+      injectedTokens: graphResult.injectedTokens,
+      latencyMs: graphResult.latencyMs,
+      topCandidates: m.topCandidates.map((c) => ({
+        key: c.nodeId,
+        type: c.type,
+        kind: "graph",
+        finalScore: c.score,
+        semantic: c.semanticSimilarity,
+        recency: c.recencyBoost,
+      })),
+    };
+    ctx.onEvent(memoryRecalledEvent);
+  }
+}
+
+/**
+ * Run the default retrieval, writing `latestMessages` back onto the context and
+ * recording the PKB query-vector pair on the graph handle. Skips the
+ * memory-graph call entirely (leaving `latestMessages` as the seeded input
+ * messages and no query pair recorded) when the actor is not trusted.
+ *
+ * Memory retrieval blocks the turn — there is no soft timeout here. Memory is
+ * critical context, and silently dropping it produces a worse outcome than a
+ * slower turn. Cancellation still works via `ctx.signal`, which is threaded
+ * into `prepareMemory`.
+ */
+const userPromptSubmitMemoryRetrieval: PluginHookFn<
+  MemoryRetrievalHookContext
+> = async (ctx) => {
+  if (!ctx.isTrustedActor) {
+    // Untrusted actors skip memory-graph retrieval entirely.
+    return;
+  }
+
+  const graphResult = await ctx.graphMemory.prepareMemory(
+    ctx.latestMessages,
+    ctx.config,
+    ctx.signal,
+    ctx.onEvent,
+  );
+
+  recordRecallSideEffects(graphResult, ctx);
+
+  ctx.latestMessages = graphResult.runMessages;
+  // Select dense+sparse as a matched pair so RRF fusion combines two signals
+  // aligned to the same query text:
+  //   1. Context-load with a user query: user-query dense + user-query sparse
+  //      — the cleanest pairing.
+  //   2. Otherwise (context-load without a user query, or per-turn): whatever
+  //      `queryVector` / `sparseVector` the retriever produced, which are
+  //      themselves co-aligned (both summary-derived in context-load, both
+  //      user-last-message-derived in per-turn).
+  // Never pair a user-query dense with a summary-aligned sparse.
+  // The PKB-reminder injector reads this pair back off the same graph handle
+  // (looked up by conversation id) rather than receiving it threaded through
+  // the agent loop.
+  if (graphResult.userQueryVector) {
+    ctx.graphMemory.recordPkbQueryVectors(
+      graphResult.userQueryVector,
+      graphResult.userQuerySparseVector,
+    );
+  } else {
+    ctx.graphMemory.recordPkbQueryVectors(
+      graphResult.queryVector,
+      graphResult.sparseVector,
+    );
+  }
+};
+
+export default userPromptSubmitMemoryRetrieval;

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

@@ -0,0 +1,35 @@
+/**
+ * The assembled runtime injector chain.
+ *
+ * Injection is not a plugin contribution: the first-party injectors are
+ * imported directly and sorted once, by ascending `order`, into the single
+ * sequence `applyRuntimeInjections` walks each turn. This co-locates the
+ * chain with the memory-retrieval domain it serves, rather than aggregating
+ * injectors out of the plugin registry.
+ *
+ * The chain combines the default injectors ({@link defaultInjectors}) with the
+ * memory-v3 injector ({@link memoryV3Injector}). The sort mirrors the previous
+ * registry aggregation (`Array.prototype.sort` is stable, so injectors sharing
+ * an `order` keep their listed order), so the produced sequence — and therefore
+ * the injected content — is identical.
+ *
+ * The chain is assembled lazily on first access and memoized, so the sort runs
+ * once per process rather than per turn and module evaluation stays free of any
+ * ordering assumptions about when `defaultInjectors` finishes initializing.
+ */
+
+import type { Injector } from "../../types.js";
+import { memoryV3Injector } from "../memory-v3-shadow/injector.js";
+import { defaultInjectors } from "./injectors.js";
+
+let cachedChain: Injector[] | null = null;
+
+/** The order-sorted runtime injector chain, assembled once and memoized. */
+export function getInjectorChain(): Injector[] {
+  if (cachedChain === null) {
+    cachedChain = [...defaultInjectors, memoryV3Injector].sort(
+      (a, b) => a.order - b.order,
+    );
+  }
+  return cachedChain;
+}