@vellumai/assistant 0.8.4 → 0.8.5

package/src/memory/v3/validate.ts

@@ -0,0 +1,300 @@
+/**
+ * Memory v3 — Tree structure validator.
+ *
+ * The v3 tree is hand-authored by a data-migration during the v2 → v3 rollout
+ * (nodes reference pages and sub-nodes by `page:`/`node:` refs). Because the
+ * structure is authored, not derived, it can drift: a ref can dangle, a page
+ * can be left unwired, two nodes can reference each other into a cycle, a
+ * parent node's compositional summary can fall behind a freshly-edited child,
+ * or a page `edges:` entry can point at a slug with no page.
+ *
+ * `validateTree` is the read-only report the migration (and any later
+ * structure-health probe) runs to surface those defects. It is deliberately
+ * **non-throwing**: the migration is in progress, so an incomplete tree is
+ * expected — the report is informational, and the caller decides what (if
+ * anything) is fatal. It builds the three indices it needs (tree, page, edge),
+ * walks the DAG, and returns counts plus the offending ids for each category.
+ *
+ * Categories:
+ *   - `danglingChildRefs` — a node `children` entry (`node:`/`page:`) whose
+ *     target node/page does not exist on disk.
+ *   - `orphanPages` — concept pages present in the page index but not reachable
+ *     from the tree root by descending every `node:` child. Informational while
+ *     the migration is mid-flight (not every page is wired in yet). Synthetic
+ *     page-index entries (skills, CLI commands) are excluded — they are never
+ *     tree members.
+ *   - `cycles` — back-edges found during a full DFS over `node:` adjacency
+ *     (A → B → A). A cycle would make a naive descent loop forever.
+ *   - `staleIndex` — a node whose own file mtime predates one of its `node:`
+ *     children's mtime, hinting its compositional index/summary may be out of
+ *     date relative to the child it composes.
+ *   - `unknownEdgeTargets` — page `edges:` targets with no corresponding page
+ *     index slug, reusing v2's `validateEdgeTargets`.
+ */
+
+import { CLI_COMMAND_SLUG_PREFIX } from "../v2/cli-command-store.js";
+import { getEdgeIndex, validateEdgeTargets } from "../v2/edge-index.js";
+import { getPageIndex } from "../v2/page-index.js";
+import { SKILL_SLUG_PREFIX } from "../v2/skill-store.js";
+import { getTreeIndex, type TreeIndex } from "./tree-index.js";
+import { getNodeMtimeMs } from "./tree-store.js";
+
+/**
+ * A `node:` child whose mtime is newer than the parent node that composes it.
+ * `node` is the parent, `child` the fresher child, and the two `*MtimeMs`
+ * fields are their epoch-ms mtimes (parent < child triggers the report).
+ */
+export interface StaleIndexEntry {
+  node: string;
+  child: string;
+  nodeMtimeMs: number;
+  childMtimeMs: number;
+}
+
+/**
+ * Read-only health report over the v3 tree + its referenced pages/edges.
+ * Every list is sorted for deterministic output; `*Count` fields mirror the
+ * corresponding list length so callers can summarize without re-counting.
+ */
+export interface TreeValidationReport {
+  /** `node:`/`page:` children whose target does not exist. */
+  danglingChildRefs: Array<{
+    node: string;
+    ref: string;
+    kind: "node" | "page";
+  }>;
+  danglingChildRefCount: number;
+  /** Concept pages not reachable from the root by descending all node children. */
+  orphanPages: string[];
+  orphanPageCount: number;
+  /** Back-edges (`from → to`) closing a cycle during the full DFS descent. */
+  cycles: Array<{ from: string; to: string }>;
+  cycleCount: number;
+  /** Nodes whose mtime predates a child node's mtime. */
+  staleIndex: StaleIndexEntry[];
+  staleIndexCount: number;
+  /** Page `edges:` targets with no corresponding page-index slug. */
+  unknownEdgeTargets: Array<{ from: string; to: string }>;
+  unknownEdgeTargetCount: number;
+}
+
+/** True when a page-index slug is a synthetic (non-concept-page) entry. */
+function isSyntheticSlug(slug: string): boolean {
+  return (
+    slug.startsWith(SKILL_SLUG_PREFIX) ||
+    slug.startsWith(CLI_COMMAND_SLUG_PREFIX)
+  );
+}
+
+/**
+ * Collect dangling `node:`/`page:` child refs: every node child whose target
+ * node id is absent from `tree.nodes`, and every page child whose slug is
+ * absent from `knownPageSlugs`. Sorted by `(node, kind, ref)`.
+ */
+function collectDanglingChildRefs(
+  tree: TreeIndex,
+  knownPageSlugs: ReadonlySet<string>,
+): Array<{ node: string; ref: string; kind: "node" | "page" }> {
+  const dangling: Array<{ node: string; ref: string; kind: "node" | "page" }> =
+    [];
+  for (const [nodeId, children] of tree.childrenByNode) {
+    for (const child of children) {
+      const exists =
+        child.kind === "node"
+          ? tree.nodes.has(child.ref)
+          : knownPageSlugs.has(child.ref);
+      if (!exists) {
+        dangling.push({ node: nodeId, ref: child.ref, kind: child.kind });
+      }
+    }
+  }
+  dangling.sort(
+    (a, b) =>
+      a.node.localeCompare(b.node) ||
+      a.kind.localeCompare(b.kind) ||
+      a.ref.localeCompare(b.ref),
+  );
+  return dangling;
+}
+
+/**
+ * Resolve the existing `node:` children of `nodeId`, in `children` order. Refs
+ * to absent nodes are skipped (those are reported separately as dangling) so
+ * the descent never recurses into a node that isn't on disk.
+ */
+function nodeChildrenOf(tree: TreeIndex, nodeId: string): string[] {
+  const children = tree.childrenByNode.get(nodeId) ?? [];
+  const out: string[] = [];
+  for (const child of children) {
+    if (child.kind === "node" && tree.nodes.has(child.ref)) {
+      out.push(child.ref);
+    }
+  }
+  return out;
+}
+
+/**
+ * Full DFS over `node:` adjacency from `tree.root`. Returns the set of
+ * reachable node ids (for orphan-page reachability) and the back-edges that
+ * close a cycle. A back-edge is an edge into a node still on the active
+ * recursion stack (classic gray-node cycle detection); `visited` (black)
+ * prevents re-walking shared DAG sub-nodes.
+ */
+function descend(tree: TreeIndex): {
+  reachableNodes: Set<string>;
+  cycles: Array<{ from: string; to: string }>;
+} {
+  const reachableNodes = new Set<string>();
+  const onStack = new Set<string>();
+  const cycles: Array<{ from: string; to: string }> = [];
+
+  // Iterative DFS with an explicit stack so deep trees don't blow the call
+  // stack. Each frame tracks its child cursor; we push a child frame, and on
+  // exhaustion pop the parent off the recursion stack (`onStack`).
+  type Frame = { node: string; children: string[]; cursor: number };
+  const stack: Frame[] = [];
+
+  function enter(nodeId: string): void {
+    reachableNodes.add(nodeId);
+    onStack.add(nodeId);
+    stack.push({
+      node: nodeId,
+      children: nodeChildrenOf(tree, nodeId),
+      cursor: 0,
+    });
+  }
+
+  if (tree.nodes.has(tree.root)) {
+    enter(tree.root);
+  }
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame.cursor >= frame.children.length) {
+      onStack.delete(frame.node);
+      stack.pop();
+      continue;
+    }
+    const child = frame.children[frame.cursor++];
+    if (onStack.has(child)) {
+      // Edge into an ancestor still on the stack → cycle-closing back-edge.
+      cycles.push({ from: frame.node, to: child });
+      continue;
+    }
+    if (reachableNodes.has(child)) {
+      // Already fully explored via another parent (shared DAG sub-node).
+      continue;
+    }
+    enter(child);
+  }
+
+  cycles.sort(
+    (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to),
+  );
+  return { reachableNodes, cycles };
+}
+
+/**
+ * Concept pages reachable from the tree: every `page:` child of a reachable
+ * node. Pages hanging off unreachable nodes are *not* counted reachable — they
+ * only become reachable once their parent chain links back to the root.
+ */
+function reachablePages(
+  tree: TreeIndex,
+  reachableNodes: ReadonlySet<string>,
+): Set<string> {
+  const pages = new Set<string>();
+  for (const nodeId of reachableNodes) {
+    for (const child of tree.childrenByNode.get(nodeId) ?? []) {
+      if (child.kind === "page") pages.add(child.ref);
+    }
+  }
+  return pages;
+}
+
+/**
+ * Nodes whose own mtime predates one of their `node:` children's mtime. A
+ * missing node file reads as mtime 0 (oldest), so the check never flags a
+ * parent against an absent child. Sorted by `(node, child)`.
+ */
+async function collectStaleIndex(
+  workspaceDir: string,
+  tree: TreeIndex,
+): Promise<StaleIndexEntry[]> {
+  const ids = [...tree.nodes.keys()];
+  const mtimes = new Map<string, number>();
+  await Promise.all(
+    ids.map(async (id) => {
+      mtimes.set(id, await getNodeMtimeMs(workspaceDir, id));
+    }),
+  );
+
+  const stale: StaleIndexEntry[] = [];
+  for (const node of ids) {
+    const nodeMtimeMs = mtimes.get(node) ?? 0;
+    for (const child of nodeChildrenOf(tree, node)) {
+      const childMtimeMs = mtimes.get(child) ?? 0;
+      if (nodeMtimeMs < childMtimeMs) {
+        stale.push({ node, child, nodeMtimeMs, childMtimeMs });
+      }
+    }
+  }
+  stale.sort(
+    (a, b) => a.node.localeCompare(b.node) || a.child.localeCompare(b.child),
+  );
+  return stale;
+}
+
+/**
+ * Validate the hand-authored v3 tree structure for `workspaceDir` and return a
+ * {@link TreeValidationReport}. Builds the tree, page, and edge indices, walks
+ * the DAG from the root, and reports the five defect categories. Never throws —
+ * it is a report, not an assertion.
+ */
+export async function validateTree(
+  workspaceDir: string,
+): Promise<TreeValidationReport> {
+  const [tree, pageIndex, edgeIndex] = await Promise.all([
+    getTreeIndex(workspaceDir),
+    getPageIndex(workspaceDir),
+    getEdgeIndex(workspaceDir),
+  ]);
+
+  const knownPageSlugs = new Set(pageIndex.bySlug.keys());
+
+  // Kick off the stale-index mtime stats up front — it only depends on the
+  // tree, not on the DAG walk below — so its filesystem reads overlap the
+  // (synchronous) descent rather than running strictly after it.
+  const staleIndexPromise = collectStaleIndex(workspaceDir, tree);
+
+  const danglingChildRefs = collectDanglingChildRefs(tree, knownPageSlugs);
+
+  const { reachableNodes, cycles } = descend(tree);
+
+  const reached = reachablePages(tree, reachableNodes);
+  const orphanPages = [...knownPageSlugs]
+    .filter((slug) => !isSyntheticSlug(slug) && !reached.has(slug))
+    .sort();
+
+  const staleIndex = await staleIndexPromise;
+
+  // Edge graph is page-only; knownSlugs is the full page-index slug set so an
+  // edge pointing at a skill/CLI entry is not spuriously flagged unknown.
+  const unknownEdgeTargets = validateEdgeTargets(
+    edgeIndex,
+    knownPageSlugs,
+  ).missing;
+
+  return {
+    danglingChildRefs,
+    danglingChildRefCount: danglingChildRefs.length,
+    orphanPages,
+    orphanPageCount: orphanPages.length,
+    cycles,
+    cycleCount: cycles.length,
+    staleIndex,
+    staleIndexCount: staleIndex.length,
+    unknownEdgeTargets,
+    unknownEdgeTargetCount: unknownEdgeTargets.length,
+  };
+}

package/src/notifications/adapters/macos.ts

@@ -18,6 +18,7 @@
  * does not match their own identity.
  */
 
+import type { InterfaceId } from "../../channels/types.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import { getLogger } from "../../util/logger.js";
 import type {
@@ -30,7 +31,23 @@ import type {
 
 const log = getLogger("notif-adapter-vellum");
 
-export type BroadcastFn = (msg: ServerMessage) => void;
+/**
+ * Optional targeting/filtering applied at the hub when a broadcast is
+ * emitted. Mirrors the third argument of
+ * `broadcastMessage()` in `runtime/assistant-event-hub.ts`. Callers can
+ * use `targetInterfaceId` to scope a legacy message to a single client
+ * surface (e.g. macOS) during a migration window.
+ */
+export interface BroadcastFnOptions {
+  targetClientId?: string;
+  targetInterfaceId?: InterfaceId;
+}
+
+export type BroadcastFn = (
+  msg: ServerMessage,
+  conversationId?: string,
+  options?: BroadcastFnOptions,
+) => void;
 
 /**
  * Event name prefixes that carry guardian-sensitive content (approval

package/src/notifications/adapters/platform.ts

@@ -5,7 +5,7 @@
  * POSTs a `notification_intent` payload to
  * `/v1/assistants/{id}/push/dispatch/`. The platform endpoint fans the
  * notification out to all registered device tokens for the bound user and
- * gates on the `ios-remote-push-enabled` LD flag server-side (returning 202
+ * gates on the `ios-remote-push-enabled` feature flag server-side (returning 202
  * with `{ skipped: "flag_off" }` when the flag is OFF — no action needed
  * from the daemon).
  *

package/src/notifications/decision-engine.ts

@@ -13,7 +13,6 @@ import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
 import { listGuardianChannels } from "../contacts/contact-store.js";
-import { resolveGuardianPersona } from "../prompts/persona-resolver.js";
 import { buildCoreIdentityContext } from "../prompts/system-prompt.js";
 import {
   createTimeout,
@@ -921,9 +920,7 @@ async function classifyWithLLM(
   const candidateContext = candidateSet
     ? (serializeCandidatesForPrompt(candidateSet) ?? undefined)
     : undefined;
-  const rawIdentityContext = buildCoreIdentityContext({
-    userPersona: resolveGuardianPersona(),
-  });
+  const rawIdentityContext = buildCoreIdentityContext();
   const identityContext = rawIdentityContext
     ? truncate(rawIdentityContext, MAX_IDENTITY_CONTEXT_CHARS, "\n…[truncated]")
     : undefined;

package/src/notifications/emit-signal.ts

@@ -14,8 +14,9 @@ import { v4 as uuid } from "uuid";
 import { getDeliverableChannels } from "../channels/config.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
 import type { ConversationCreateType } from "../memory/conversation-crud.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
-import { type BroadcastFn, VellumAdapter } from "./adapters/macos.js";
+import { VellumAdapter } from "./adapters/macos.js";
 import { PlatformPushAdapter } from "./adapters/platform.js";
 import { SlackAdapter } from "./adapters/slack.js";
 import { TelegramAdapter } from "./adapters/telegram.js";
@@ -49,56 +50,38 @@ const log = getLogger("emit-signal");
 // ── Broadcaster singleton ──────────────────────────────────────────────
 
 let broadcasterInstance: NotificationBroadcaster | null = null;
-let registeredBroadcastFn: BroadcastFn | null = null;
-
-/**
- * Register the broadcast function so the vellum adapter can deliver
- * notifications to connected clients. Must be called once during
- * daemon startup (before any signals are emitted).
- */
-export function registerBroadcastFn(fn: BroadcastFn): void {
-  registeredBroadcastFn = fn;
-  // Reset the broadcaster so it picks up the new broadcast function
-  broadcasterInstance = null;
-}
 
 function getBroadcaster(): NotificationBroadcaster {
   if (!broadcasterInstance) {
-    const adapters = [
+    broadcasterInstance = new NotificationBroadcaster([
+      new VellumAdapter(broadcastMessage),
       new TelegramAdapter(),
       new SlackAdapter(),
       new PlatformPushAdapter(),
-    ];
-    if (registeredBroadcastFn) {
-      adapters.unshift(new VellumAdapter(registeredBroadcastFn));
-    }
-    broadcasterInstance = new NotificationBroadcaster(adapters);
+    ]);
 
     // Wire the conversation-created callback so the macOS client is notified
     // immediately when a vellum notification conversation is paired — before
     // slower channel deliveries (e.g. Telegram) delay the push.
-    if (registeredBroadcastFn) {
-      const broadcastFn = registeredBroadcastFn;
-      broadcasterInstance.setOnConversationCreated((info) => {
-        broadcastFn({
-          type: "notification_conversation_created",
-          conversationId: info.conversationId,
-          title: info.title,
-          sourceEventName: info.sourceEventName,
-          targetGuardianPrincipalId: info.targetGuardianPrincipalId,
-          groupId: info.groupId,
-          source: info.source,
-          silent: info.silent,
-        });
-        log.info(
-          {
-            conversationId: info.conversationId,
-            guardianScoped: info.targetGuardianPrincipalId != null,
-          },
-          "Emitted notification_conversation_created push event",
-        );
+    broadcasterInstance.setOnConversationCreated((info) => {
+      broadcastMessage({
+        type: "notification_conversation_created",
+        conversationId: info.conversationId,
+        title: info.title,
+        sourceEventName: info.sourceEventName,
+        targetGuardianPrincipalId: info.targetGuardianPrincipalId,
+        groupId: info.groupId,
+        source: info.source,
+        silent: info.silent,
       });
-    }
+      log.info(
+        {
+          conversationId: info.conversationId,
+          guardianScoped: info.targetGuardianPrincipalId != null,
+        },
+        "Emitted notification_conversation_created push event",
+      );
+    });
   }
   return broadcasterInstance;
 }
@@ -115,18 +98,15 @@ function getConnectedChannels(): NotificationChannel[] {
     switch (channel) {
       case "vellum":
         // Vellum is always considered connected (the local transport is
-        // always available when the daemon is running).
+        // always available when the assistant is running).
         channels.push(channel);
         break;
       case "platform":
-        // Platform push is connected when the daemon has a registered
-        // broadcast function — i.e., full daemon mode where platform
-        // credentials are also available. Mirrors the vellum gate so
-        // the decision engine doesn't route to platform in standalone
-        // CLI contexts where VellumPlatformClient.create() returns null.
-        if (registeredBroadcastFn) {
-          channels.push(channel);
-        }
+        // Platform push is treated as connected at the decision-engine
+        // layer; the actual delivery path lazily resolves
+        // `VellumPlatformClient.create()` in `PlatformPushAdapter.send()`
+        // and reports a delivery failure when credentials are absent.
+        channels.push(channel);
         break;
       case "telegram": {
         // A binding-based channel is connected when the guardian has an

package/src/permissions/prompter.ts

@@ -79,7 +79,7 @@ export class PermissionPrompter {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
 
       const timer = setTimeout(() => {
-        const interaction = pendingInteractions.resolve(requestId);
+        const interaction = pendingInteractions.resolve(requestId, "cancelled");
         this.ownedIds.delete(requestId);
         log.warn(
           { requestId, toolName },
@@ -130,7 +130,7 @@ export class PermissionPrompter {
       if (signal) {
         const onAbort = () => {
           if (this.ownedIds.has(requestId)) {
-            pendingInteractions.resolve(requestId);
+            pendingInteractions.resolve(requestId, "cancelled");
             this.ownedIds.delete(requestId);
             resolve({ decision: "deny", wasAbort: true });
           }
@@ -232,7 +232,7 @@ export class PermissionPrompter {
 
   dispose(): void {
     for (const requestId of [...this.ownedIds]) {
-      const interaction = pendingInteractions.resolve(requestId);
+      const interaction = pendingInteractions.resolve(requestId, "cancelled");
       this.ownedIds.delete(requestId);
       interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),

package/src/permissions/question-prompter.ts

@@ -223,8 +223,11 @@ export class QuestionPrompter {
           signal.removeEventListener("abort", onAbort);
         }
         // Idempotent: a no-op if the entry was already removed (e.g. by
-        // `removeByConversation`) or by an earlier path.
-        pendingInteractions.resolve(requestId);
+        // `removeByConversation`) or by an earlier path. The route's
+        // success path resolves with "answered" before invoking rpcResolve,
+        // so this fallback only fires for timeout / abort / removeByConversation —
+        // all cancellation-shaped outcomes.
+        pendingInteractions.resolve(requestId, "cancelled");
         fn();
       };
 

package/src/permissions/secret-prompter.ts

@@ -71,7 +71,7 @@ export class SecretPrompter {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
 
       const timer = setTimeout(() => {
-        pendingInteractions.resolve(requestId);
+        pendingInteractions.resolve(requestId, "cancelled");
         this.ownedIds.delete(requestId);
         log.warn({ requestId, service, field }, "Secret prompt timed out");
         resolve({ value: null, delivery: "store" });
@@ -142,7 +142,7 @@ export class SecretPrompter {
 
   dispose(): void {
     for (const requestId of [...this.ownedIds]) {
-      const interaction = pendingInteractions.resolve(requestId);
+      const interaction = pendingInteractions.resolve(requestId, "cancelled");
       this.ownedIds.delete(requestId);
       interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),

package/src/plugin-api/index.ts

@@ -25,6 +25,8 @@
  * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
  *   fired immediately before the agent loop receives a user's prompt
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
+ * - {@link ToolDefinition} — author-facing tool spec (default-export shape
+ *   for both plugin tool files and workspace tool files)
  * - {@link ToolContext} — passed to a plugin tool's `execute` method
  * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
  *
@@ -41,6 +43,8 @@ export type {
   PluginLogger,
   PluginShutdownContext,
   ToolContext,
+  ToolDefinition,
   ToolExecutionResult,
   UserPromptSubmitContext,
 } from "./types.js";
+export { RiskLevel } from "./types.js";

package/src/plugin-api/types.ts

@@ -1,43 +1,17 @@
 /**
- * Public plugin-API types.
- *
- * This module is the entry point plugin authors land on when they import
- * from `@vellumai/plugin-api`. The shapes here are the canonical public
- * contract — anything exported is part of the surface that semver gates.
- *
- * ## Tool-execution types
- *
- * `ToolContext` and `ToolExecutionResult` are re-exports of the narrow,
- * stable bases defined alongside their daemon-internal counterparts in
- * `assistant/src/tools/types.ts`. The daemon-internal `ToolContext` /
- * `ToolExecutionResult` (with CES, trust classification, lifecycle
- * events, sensitive-output bindings, risk metadata, etc.) `extends`
- * the public bases, so the runtime can hand plugins the full value
- * without a manual cast and tsc enforces the structural relationship.
- * Plugin tools see the narrow surface only — they MUST NOT set fields
- * that belong to the daemon-internal extension.
- *
- * ## Hook contexts
- *
- * The init / shutdown hook contexts are owned by this module directly.
- * They have no daemon-internal extension today (the daemon constructs
- * and hands them straight through), so there's nothing to inherit from.
- *
- * ## Compatibility
- *
- * Adding fields to any public shape is non-breaking. Renaming or
- * removing fields is breaking and gated on a major bump of
- * `@vellumai/plugin-api`.
+ * Public plugin-API types — the canonical contract for
+ * `@vellumai/plugin-api`. Adding fields is non-breaking; renaming /
+ * removing is breaking and gated on a major bump.
  */
 
 import type { Message } from "../providers/types.js";
 
-// ─── Tool-execution types (re-exported from daemon source-of-truth) ──────────
-
 export type {
-  PluginToolContext as ToolContext,
-  PluginToolExecutionResult as ToolExecutionResult,
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
 } from "../tools/types.js";
+export { RiskLevel } from "../tools/types.js";
 
 // ─── Logger ──────────────────────────────────────────────────────────────────
 

package/src/plugins/defaults/index.ts

@@ -24,6 +24,7 @@
  * chain) does not trip a TDZ.
  */
 
+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";
@@ -60,6 +61,11 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     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,