@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

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

@@ -1,35 +1,24 @@
 /**
  * Default `compaction` plugin.
  *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual compaction lives in the terminal handler in
- * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
- * the `runPipeline` call site 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.
- *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
+ * Compaction is implemented in `./compact.ts` as {@link defaultCompact}, which
+ * the agent loop calls directly with a {@link CompactionContext}. The plugin
+ * stays registered as a placeholder so it keeps a presence in the defaults
+ * list while we decide how plugins should surface compaction; it contributes
+ * no contract slot today.
  */
 
 import { type Plugin } from "../../types.js";
-import defaultCompactionMiddleware from "./middlewares/compaction.js";
 import pkg from "./package.json" with { type: "json" };
 
 /**
- * Manifest + middleware wiring for the default compaction plugin. The
- * registration happens in `daemon/external-plugins-bootstrap.ts` before
- * {@link bootstrapPlugins} fires plugin `init()` hooks.
+ * Manifest 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: pkg.name,
     version: pkg.version,
   },
-  middleware: {
-    compaction: defaultCompactionMiddleware,
-  },
 };

package/src/plugins/defaults/empty-response/hooks/stop.ts

@@ -0,0 +1,126 @@
+/**
+ * Default `stop` hook: when the model yields a turn with no tool calls, decide
+ * whether to let the turn end or re-query the model with a nudge.
+ *
+ * Two cases warrant a nudge:
+ *
+ * 1. **Refusal stop.** The provider returned `stopReason === "refusal"` with no
+ *    visible text (Anthropic's safety classifier zeroed the response). Nudged
+ *    even on the first model call of the run — a refusal there guarantees no
+ *    organic text exists yet, so without intervening the loop would persist an
+ *    empty assistant bubble to the user. Uses `REFUSAL_NUDGE_TEXT`.
+ * 2. **Empty turn after tool use.** The turn produced no visible text, follows
+ *    at least one prior assistant turn this run, and no earlier turn this run
+ *    already delivered visible text. Uses `NUDGE_TEXT`.
+ *
+ * Every other case leaves the decision at `"stop"` (the model said its piece,
+ * or there is nothing to nudge about). The retry cap is owned by the agent
+ * loop: this hook always asks to continue when a nudge is warranted, and the
+ * loop stops anyway once the run's nudge budget is spent.
+ *
+ * Both prior-turn signals are derived from the current response cycle — the
+ * messages after the last genuine user prompt (a user turn that isn't purely
+ * tool results). Scoping this way keeps prior conversation turns from polluting
+ * the signals, and deriving the boundary from history content rather than an
+ * index means mid-run compaction (which rewrites the array in place) can't
+ * invalidate it. A prior assistant turn this cycle implies a completed tool-use
+ * iteration (an empty turn nudges-and-continues without pushing an assistant
+ * message), so "a prior assistant turn exists" is the equivalent of "this is
+ * not the first model call".
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `stop` chain — later hooks see (and may override) its decision.
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+
+/**
+ * Canonical nudge text for an empty turn after tool use. Must stay verbatim so
+ * a plugin that wraps the default sees a stable string.
+ *
+ * Wire-compat note: this is shown to the LLM, not the user. Edits here affect
+ * model behavior but not end-user UX directly.
+ */
+export 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>";
+
+/**
+ * Refusal-specific nudge. Used when the provider stops with `"refusal"` and no
+ * visible text — i.e. the safety classifier zeroed the response. Kept distinct
+ * from `NUDGE_TEXT` so the model gets context-appropriate guidance (no "summary
+ * of what you found or did" — there is no tool trail to summarize on a refusal).
+ *
+ * Wire-compat note: this is shown to the LLM, not the user. Edits here affect
+ * retry behavior but not end-user UX directly.
+ */
+export const REFUSAL_NUDGE_TEXT =
+  '<system_notice>Your previous response was empty because the upstream provider returned stop_reason="refusal". Please answer the user\'s last message directly with a plain-text response. Do not use any tools — just respond with text.</system_notice>';
+
+function hasVisibleText(content: ReadonlyArray<ContentBlock>): boolean {
+  return content.some(
+    (block) => block.type === "text" && block.text.trim().length > 0,
+  );
+}
+
+function isAssistantTurn(message: Message): boolean {
+  return message.role === "assistant";
+}
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/**
+ * Messages belonging to the current response cycle: everything after the last
+ * genuine user prompt. Falls back to the whole history when none is found.
+ */
+function currentCycleMessages(
+  messages: ReadonlyArray<Message>,
+): ReadonlyArray<Message> {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "user" && !isToolResultMessage(message)) {
+      return messages.slice(i + 1);
+    }
+  }
+  return messages;
+}
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  const turnHasVisibleText = hasVisibleText(ctx.responseContent);
+
+  const appendNudge = (text: string): void => {
+    ctx.messages.push({ role: "user", content: [{ type: "text", text }] });
+    ctx.decision = "continue";
+  };
+
+  if (ctx.stopReason === "refusal" && !turnHasVisibleText) {
+    appendNudge(REFUSAL_NUDGE_TEXT);
+    return;
+  }
+
+  const cycleMessages = currentCycleMessages(ctx.messages);
+  const priorAssistantTurns = cycleMessages.filter(isAssistantTurn);
+  const hadPriorAssistantTurn = priorAssistantTurns.length > 0;
+  const priorAssistantHadVisibleText = priorAssistantTurns.some((message) =>
+    hasVisibleText(message.content),
+  );
+
+  const isEmptyTurnAfterTools =
+    !turnHasVisibleText &&
+    hadPriorAssistantTurn &&
+    !priorAssistantHadVisibleText;
+
+  if (isEmptyTurnAfterTools) {
+    appendNudge(NUDGE_TEXT);
+  }
+};
+
+export default stop;

package/src/plugins/defaults/empty-response/register.ts

@@ -1,19 +1,14 @@
 /**
- * Default `emptyResponse` plugin.
+ * Default `empty-response` plugin.
  *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual decision lives in the terminal handler in
- * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
- * the `runPipeline` call site in `agent/loop.ts`. This separation matters: the
- * default plugin is registered before any user plugin (defaults load first in
- * `bootstrapPlugins()`), which puts it at the OUTERMOST position of the onion
- * chain. If the default middleware were to decide directly without calling
- * `next`, it would shadow every later-registered plugin. Routing through
- * `next(args)` lets user middleware participate normally.
+ * Contributes a `stop` hook that re-queries the model when a turn yields with
+ * no tool calls but came back empty (or as a provider refusal). The decision
+ * logic lives in `./hooks/stop.ts`. Defaults register before user plugins, so
+ * this runs at the front of the `stop` hook chain.
  */
 
 import { type Plugin } from "../../types.js";
-import emptyResponse from "./middlewares/emptyResponse.js";
+import stop from "./hooks/stop.js";
 import pkg from "./package.json" with { type: "json" };
 
 /** Singleton plugin — the registry rejects duplicate registrations by name. */
@@ -22,7 +17,7 @@ export const defaultEmptyResponsePlugin: Plugin = {
     name: pkg.name,
     version: pkg.version,
   },
-  middleware: {
-    emptyResponse,
+  hooks: {
+    stop,
   },
 };

package/src/plugins/defaults/index.ts

@@ -23,22 +23,14 @@
  * registration work.
  */
 
-import { memoryV3ShadowPlugin } from "../../memory/v3/shadow-plugin.js";
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
-import { defaultCircuitBreakerPlugin } from "./circuit-breaker/register.js";
 import { defaultCompactionPlugin } from "./compaction/register.js";
 import { defaultEmptyResponsePlugin } from "./empty-response/register.js";
 import { defaultHistoryRepairPlugin } from "./history-repair/register.js";
-import { defaultInjectorsPlugin } from "./injectors/register.js";
-import { defaultLlmCallPlugin } from "./llm-call/register.js";
-import { defaultMemoryRetrievalPlugin } from "./memory-retrieval/register.js";
-import { defaultOverflowReducePlugin } from "./overflow-reduce/register.js";
-import { defaultPersistencePlugin } from "./persistence/register.js";
+import { memoryV3ShadowPlugin } from "./memory-v3-shadow/register.js";
 import { defaultTitleGeneratePlugin } from "./title-generate/register.js";
-import { defaultTokenEstimatePlugin } from "./token-estimate/register.js";
 import { defaultToolErrorPlugin } from "./tool-error/register.js";
-import { defaultToolExecutePlugin } from "./tool-execute/register.js";
 import { defaultToolResultTruncatePlugin } from "./tool-result-truncate/register.js";
 
 /**
@@ -53,19 +45,11 @@ import { defaultToolResultTruncatePlugin } from "./tool-result-truncate/register
  */
 function getAllDefaultPlugins(): readonly Plugin[] {
   return [
-    defaultLlmCallPlugin,
-    defaultToolExecutePlugin,
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
-    defaultMemoryRetrievalPlugin,
-    defaultInjectorsPlugin,
-    defaultTokenEstimatePlugin,
-    defaultOverflowReducePlugin,
     defaultHistoryRepairPlugin,
     defaultCompactionPlugin,
-    defaultCircuitBreakerPlugin,
-    defaultPersistencePlugin,
     defaultTitleGeneratePlugin,
     memoryV3ShadowPlugin,
   ];
@@ -99,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;
+}