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

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/__tests__/shadow-plugin.test.ts

@@ -22,8 +22,8 @@ import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
-import { migrateAddMemoryV3Selections } from "../../migrations/268-add-memory-v3-selections.js";
-import * as schema from "../../schema.js";
+import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
+import * as schema from "../../../../memory/schema.js";
 import type { LeafTree, SelectionSource } from "../types.js";
 
 // `mock.module` is process-global and, in Bun, neither `mock.restore()` nor a
@@ -41,10 +41,10 @@ const realTree = { ...(await import("../tree.js")) };
 const realCore = { ...(await import("../core.js")) };
 const realNeedle = { ...(await import("../needle.js")) };
 const realOrchestrate = { ...(await import("../orchestrate.js")) };
-const realPlatform = { ...(await import("../../../util/platform.js")) };
-const realPageStore = { ...(await import("../../v2/page-store.js")) };
+const realPlatform = { ...(await import("../../../../util/platform.js")) };
+const realPageStore = { ...(await import("../../../../memory/v2/page-store.js")) };
 const realConversationCrud = {
-  ...(await import("../../conversation-crud.js")),
+  ...(await import("../../../../memory/conversation-crud.js")),
 };
 
 let shadowMockActive = false;
@@ -68,6 +68,7 @@ const orchestrateSpy = mock(async () => ({
 let treeLoads = 0;
 let coreLoads = 0;
 let needleBuilds = 0;
+let configL2Concurrency = 16;
 
 // Shared in-memory DB so writes are observable from the test. We hold the raw
 // sqlite handle alongside the drizzle wrapper so the test can both read rows
@@ -94,7 +95,7 @@ const FAKE_TREE = {
 
 // ─── module mocks (installed before the plugin import) ──────────────────────
 
-mock.module("../../../config/assistant-feature-flags.js", () => ({
+mock.module("../../../../config/assistant-feature-flags.js", () => ({
   isAssistantFeatureFlagEnabled: (key: string) =>
     key === "memory-v3-live"
       ? liveEnabled
@@ -103,9 +104,14 @@ mock.module("../../../config/assistant-feature-flags.js", () => ({
         : false,
 }));
 
-mock.module("../../../config/loader.js", () => ({
+mock.module("../../../../config/loader.js", () => ({
   getConfig: () => ({
-    memory: { v3: { workingSet: { maxPages: 150, evictWindow: 5 } } },
+    memory: {
+      v3: {
+        workingSet: { maxPages: 150, evictWindow: 5 },
+        l2Concurrency: configL2Concurrency,
+      },
+    },
   }),
 }));
 
@@ -113,12 +119,12 @@ mock.module("../../../config/loader.js", () => ({
 // (e.g. `getMessageById` via page-content.ts) stays present — replacing the
 // whole module with a bare `{ getMessages }` made those consumers fail to load.
 // Only `getMessages` is overridden, since that's the one the plugin reads.
-mock.module("../../conversation-crud.js", () => ({
+mock.module("../../../../memory/conversation-crud.js", () => ({
   ...realConversationCrud,
   getMessages: () => messages.map((m, i) => ({ ...m, id: `m${i}` })),
 }));
 
-mock.module("../../db-connection.js", () => ({
+mock.module("../../../../memory/db-connection.js", () => ({
   getDb: () => testDb,
   getSqliteFrom: () => testSqlite,
 }));
@@ -130,7 +136,7 @@ mock.module("../v2/page-index.js", () => ({
 // `pageContent` (live mode) reads the full page via `readPage`/`renderPageContent`.
 // Stub them to return a deterministic body per slug so the rendered `<memory>`
 // block is assertable without touching the filesystem.
-mock.module("../../v2/page-store.js", () => ({
+mock.module("../../../../memory/v2/page-store.js", () => ({
   ...realPageStore,
   readPage: async (workspaceDir: string, slug: string) =>
     shadowMockActive
@@ -144,7 +150,7 @@ mock.module("../../v2/page-store.js", () => ({
         ),
 }));
 
-mock.module("../../../util/platform.js", () => ({
+mock.module("../../../../util/platform.js", () => ({
   ...realPlatform,
   getWorkspaceDir: () =>
     shadowMockActive
@@ -203,8 +209,8 @@ const {
   runShadowObservation,
   resetShadowLanesForTests,
   invalidateLanes,
-  memoryV3ShadowPlugin,
 } = await import("../shadow-plugin.js");
+const { memoryV3Injector } = await import("../injector.js");
 
 // The module stubs above stay installed for the rest of the process (Bun can't
 // reliably uninstall them), but `shadowMockActive` gates their fake behavior to
@@ -235,14 +241,14 @@ beforeEach(() => {
   treeLoads = 0;
   coreLoads = 0;
   needleBuilds = 0;
+  configL2Concurrency = 16;
   testDb = makeDb();
   resetShadowLanesForTests();
 });
 
-/** Invoke the plugin's single injector's `produce()` for a turn. */
+/** Invoke the memory-v3 injector's `produce()` for a turn. */
 function produce(conversationId: string, turnIndex: number) {
-  const injector = memoryV3ShadowPlugin.injectors![0]!;
-  return injector.produce({
+  return memoryV3Injector.produce({
     requestId: "r1",
     conversationId,
     turnIndex,
@@ -289,6 +295,18 @@ describe("memory-v3 shadow plugin", () => {
     expect(turn.currentMessage).toBe("hello world");
   });
 
+  test("orchestrate receives the configured L2 concurrency", async () => {
+    shadowEnabled = true;
+    configL2Concurrency = 9;
+    await runShadowObservation("conv-1", 0);
+    const deps = (
+      orchestrateSpy.mock.calls as unknown as unknown[][]
+    )[0]![1] as {
+      l2Concurrency?: number;
+    };
+    expect(deps.l2Concurrency).toBe(9);
+  });
+
   test("both flags OFF → produce returns null, no orchestrate, no writes", async () => {
     liveEnabled = false;
     shadowEnabled = false;

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/assign.ts

@@ -18,15 +18,15 @@
  * omitted, resolves the `memoryV3RouteL1` callsite provider.
  */
 
+import { listPages, readPage, writePage } from "../../../memory/v2/page-store.js";
+import type { ConceptPage } from "../../../memory/v2/types.js";
 import {
   extractToolUse,
   getConfiguredProvider,
   userMessage,
-} from "../../providers/provider-send-message.js";
-import type { Provider, ToolDefinition } from "../../providers/types.js";
-import { getLogger } from "../../util/logger.js";
-import { listPages, readPage, writePage } from "../v2/page-store.js";
-import type { ConceptPage } from "../v2/types.js";
+} from "../../../providers/provider-send-message.js";
+import type { Provider, ToolDefinition } from "../../../providers/types.js";
+import { getLogger } from "../../../util/logger.js";
 import type { LeafPath, LeafTree, Slug } from "./types.js";
 
 const log = getLogger("memory-v3-assign");

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/capabilities.ts

@@ -28,8 +28,8 @@
 import {
   getCliCommandCapability,
   isCliCommandSlug,
-} from "../v2/cli-command-store.js";
-import { getSkillCapability, isSkillSlug } from "../v2/skill-store.js";
+} from "../../../memory/v2/cli-command-store.js";
+import { getSkillCapability, isSkillSlug } from "../../../memory/v2/skill-store.js";
 import type { LeafNode, LeafPath, LeafTree, Slug } from "./types.js";
 
 /** Path of the always-on synthetic leaf that owns skill + CLI capability rows. */

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

@@ -0,0 +1,14 @@
+/**
+ * No-op `post-compact` scaffolding for the memory-v3-shadow plugin.
+ *
+ * v3 re-injection after mid-turn compaction is not yet owned by this plugin —
+ * the active injector still runs through the static chain. Once the
+ * post-compaction hook API stabilizes we will import `memoryV3Injector` from
+ * `../injector.js` and re-apply it here. Until then this hook does nothing.
+ */
+
+import type { PluginHookFn } from "@vellumai/plugin-api";
+
+const postCompact: PluginHookFn = async () => {};
+
+export default postCompact;

package/src/plugins/defaults/memory-v3-shadow/hooks/user-prompt-submit.ts

@@ -0,0 +1,19 @@
+/**
+ * No-op `user-prompt-submit` scaffolding for the memory-v3-shadow plugin.
+ *
+ * The v3 injector currently runs through the static injector chain
+ * (`memory-retrieval/injector-chain.ts`), not through this hook. Once the
+ * prompt-submit hook API stabilizes we will import `memoryV3Injector` from
+ * `../injector.js` and run it here, so v3 injection is owned by the plugin's
+ * own lifecycle rather than the loop-driven chain. Until then this hook
+ * intentionally does nothing.
+ */
+
+import type {
+  PluginHookFn,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async () => {};
+
+export default userPromptSubmit;

package/src/plugins/defaults/memory-v3-shadow/injector.ts

@@ -0,0 +1,75 @@
+/**
+ * The memory-v3 {@link Injector}. Reads both v3 flags:
+ *   - `memory-v3-live` on → orchestrate, log, render the working-set selection
+ *     into a `<memory>` block, and return it at v2's dynamic-memory placement.
+ *   - `memory-v3-shadow` on (live off) → orchestrate + log only, return `null`.
+ *   - both off → return `null` (no orchestration).
+ *
+ * Empty selection and any failure return `null` (no v3 injection). v2
+ * suppression keys off BOTH the flag AND this return value, so a `null` here
+ * (failure or empty selection) falls back to v2 memory rather than dropping all
+ * memory.
+ *
+ * Orchestration and telemetry live in {@link observeTurn}; this module is the
+ * thin injector wrapper that renders the result for live injection.
+ */
+
+import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
+import { getConfig } from "../../../config/loader.js";
+import { getLogger } from "../../../util/logger.js";
+import {
+  type InjectionBlock,
+  type Injector,
+  type TurnContext as PluginTurnContext,
+} from "../../types.js";
+import { renderV3PageContent } from "./page-content.js";
+import { renderMemoryBlock } from "./render-injection.js";
+import {
+  MEMORY_V3_LIVE,
+  MEMORY_V3_SHADOW,
+  observeTurn,
+} from "./shadow-plugin.js";
+import { MEMORY_V3_BLOCK_ID } from "./types.js";
+
+const log = getLogger("memory-v3-shadow");
+
+export const memoryV3Injector: Injector = {
+  name: "memory-v3-shadow",
+  // High order so it sorts last; the live `<memory>` block uses the
+  // after-memory-prefix placement so it lands at the memory boundary regardless
+  // of this sort key, which only orders content-producing injectors.
+  order: 1000,
+  async produce(ctx: PluginTurnContext): Promise<InjectionBlock | null> {
+    const config = getConfig();
+    const live = isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
+    const shadow = isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config);
+    if (!live && !shadow) return null;
+
+    const result = await observeTurn(ctx.conversationId, ctx.turnIndex);
+    if (!live || !result) return null;
+
+    try {
+      // `renderMemoryBlock` returns "" for an empty selection; inject nothing.
+      const text = await renderMemoryBlock(
+        result.finalInjection,
+        renderV3PageContent,
+      );
+      if (text.length === 0) return null;
+      return {
+        id: MEMORY_V3_BLOCK_ID,
+        text,
+        // Mirror v2's dynamic `<memory>` block placement.
+        placement: "after-memory-prefix",
+      };
+    } catch (err) {
+      log.warn(
+        {
+          err: err instanceof Error ? err.message : String(err),
+          conversationId: ctx.conversationId,
+        },
+        "memory-v3 live render failed (non-fatal) — falling back to v2",
+      );
+      return null;
+    }
+  },
+};

package/src/plugins/defaults/memory-v3-shadow/llm-retry.ts

@@ -0,0 +1,32 @@
+/**
+ * Memory v3 — shared retry helper for the L1 router and L2 selector model calls.
+ *
+ * The configured provider is already wrapped in `RetryProvider`
+ * (`../../providers/retry.ts`), which retries transient transport failures
+ * (network errors, 429s, 5xx, stream aborts) with exponential backoff before it
+ * ever throws. This helper therefore adds NO backoff of its own; it exists to:
+ *   (a) re-prompt on a malformed-but-successful response — a 200 whose body has
+ *       no usable forced `tool_use`, or whose tool input fails schema validation
+ *       (the provider's retry never re-runs these, since nothing threw); and
+ *   (b) cheaply re-attempt a call that threw after the provider exhausted its
+ *       own retries, before the lane degrades to its deterministic fallback.
+ *
+ * `attempt` signals "unusable, retry me" by returning `null` (or throwing). The
+ * first non-null result wins; `null` after `maxAttempts` tells the caller to
+ * degrade to the deterministic recall lanes.
+ */
+export async function retryForResult<T>(
+  attempt: () => Promise<T | null>,
+  maxAttempts = 3,
+): Promise<T | null> {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const result = await attempt();
+      if (result !== null) return result;
+    } catch {
+      // Treat a throw like an unusable result and retry. The provider layer has
+      // already backed off transient errors, so there is nothing to wait for.
+    }
+  }
+  return null;
+}

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/maintain-job.ts

@@ -25,14 +25,14 @@
  * `assignPages`, and `invalidateLanes` without process-global module mocks.
  */
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import type { AssistantConfig } from "../../config/types.js";
-import { getLogger } from "../../util/logger.js";
-import { getWorkspaceDir } from "../../util/platform.js";
-import { getMemoryCheckpoint, setMemoryCheckpoint } from "../checkpoints.js";
-import type { MemoryJob } from "../jobs-store.js";
-import { getPageIndex } from "../v2/page-index.js";
-import { listPages, readPage, writePage } from "../v2/page-store.js";
+import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../../../config/types.js";
+import { getMemoryCheckpoint, setMemoryCheckpoint } from "../../../memory/checkpoints.js";
+import type { MemoryJob } from "../../../memory/jobs-store.js";
+import { getPageIndex } from "../../../memory/v2/page-index.js";
+import { listPages, readPage, writePage } from "../../../memory/v2/page-store.js";
+import { getLogger } from "../../../util/logger.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
 import { assignPages as realAssignPages } from "./assign.js";
 import { invalidateLanes as realInvalidateLanes } from "./shadow-plugin.js";
 import { loadLeafTree as realLoadLeafTree, resolveDataDir } from "./tree.js";

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/orchestrate.ts

@@ -13,11 +13,16 @@
  *      then dedup by slug (a page assigned to multiple opened leaves comes back
  *      once per leaf) ORing the pinned flag so a page pinned anywhere stays
  *      pinned.
- *   4. Record each deduped selection into the carry-forward working set and
- *      evict (core slugs, stale non-pinned entries, then the cap).
- *   5. Final injection = unique union of this turn's selected slugs and the
- *      working-set union, so pages selected on earlier turns carry forward even
- *      when this turn does not re-select them.
+ *   4. Age the carry-forward working set to this turn (evict core slugs, stale
+ *      non-pinned entries, then the cap) and snapshot it — the pages carried in
+ *      from EARLIER turns.
+ *   5. Final injection = unique union of this turn's selected slugs and that
+ *      carried-forward set, so pages selected on earlier turns carry forward
+ *      even when this turn does not re-select them.
+ *   6. Record this turn's selections into the working set for LATER turns. This
+ *      runs AFTER the snapshot so the cap is spent on genuinely carried pages,
+ *      not on this turn's selections (which are injected directly) — otherwise a
+ *      turn selecting more pages than the cap would evict the entire carry.
  */
 
 import type { NeedleIndex } from "./needle.js";
@@ -48,7 +53,8 @@ export interface OrchestrateResult {
   openedLeaves: LeafPath[];
   /** This turn's L2 selections, deduped by slug (pinned flags ORed). */
   currentSelections: SelectedPage[];
-  /** Snapshot of the working-set union after record + evict. */
+  /** The carried-forward set: selections from EARLIER turns, aged to this turn
+   *  (snapshotted before this turn's selections are recorded). */
   workingSetUnion: Set<Slug>;
   /** Slugs to inject: this turn's selections ∪ the carried-forward working set. */
   finalInjection: Slug[];
@@ -95,20 +101,26 @@ export async function orchestrate(
   }
   const currentSelections = [...bySlug.values()];
 
-  // Step 4: record this turn's selections into the carry-forward working set.
-  for (const sel of currentSelections) {
-    deps.workingSet.recordSelection(sel.slug, turn.turnNumber, sel.pinned);
-  }
-
-  // Step 5: evict. Core slugs are owned by core, not the working set.
+  // Step 4: age the carry-forward set to this turn (drop core slugs, stale
+  // non-pinned entries, then the cap) and snapshot it. This is the set carried
+  // in from EARLIER turns; recording this turn happens afterward (step 6) so the
+  // cap is spent on genuinely carried pages, not on this turn's selections
+  // (which are injected directly anyway).
   deps.workingSet.evict(turn.turnNumber, coreSlugs(deps.tree, deps.core));
-
-  // Step 6: final injection = this turn's selections ∪ carried-forward set.
   const workingSetUnion = deps.workingSet.union();
+
+  // Step 5: final injection = this turn's selections ∪ the carried-forward set,
+  // so pages selected on earlier turns carry forward even when this turn does
+  // not re-select them.
   const finalInjection = unique<Slug>([
     ...currentSelections.map((s) => s.slug),
     ...workingSetUnion,
   ]);
 
+  // Step 6: record this turn's selections so they carry forward to LATER turns.
+  for (const sel of currentSelections) {
+    deps.workingSet.recordSelection(sel.slug, turn.turnNumber, sel.pinned);
+  }
+
   return { openedLeaves, currentSelections, workingSetUnion, finalInjection };
 }

package/src/plugins/defaults/{llm-call → memory-v3-shadow}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "default-llm-call",
+  "name": "default-memory-v3-shadow",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in llm-call pipeline with a passthrough implementation.",
+  "description": "First-party default plugin housing the memory-v3 shadow/live orchestration engine and its injector.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/page-content.ts

@@ -1,5 +1,5 @@
-import { getWorkspaceDir } from "../../util/platform.js";
-import { readPage, renderPageContent } from "../v2/page-store.js";
+import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
 import { renderCapabilityContent } from "./capabilities.js";
 import type { Slug } from "./types.js";
 

package/src/plugins/defaults/memory-v3-shadow/provider-blocks.ts

@@ -0,0 +1,26 @@
+import type { ContentBlock } from "../../../providers/types.js";
+
+/**
+ * Text content block carrying a `cache_control` breakpoint with a 1-hour TTL.
+ * Shared by the v3 router (the static leaf-tree block) and selector (each
+ * leaf's static `<pages>` block): these prefixes are stable across turns — the
+ * leaf tree is byte-identical every turn, and a leaf's pages block changes only
+ * when its pages/summaries do — while v3 turns are frequently more than the
+ * default 5-minute cache window apart. A 1h TTL keeps the prefix warm across
+ * those gaps so it is read from cache rather than re-created every turn; the
+ * volatile current-message block is rendered after this one and left un-cached.
+ * Haiku does not support the extended-cache-ttl beta, so the Anthropic provider
+ * strips this `ttl` for Haiku models.
+ *
+ * Our internal `TextContent` type omits `cache_control` (only the Anthropic
+ * provider transforms it onto the wire), so we reach through a `Record` cast to
+ * keep the core types provider-agnostic.
+ */
+export function cachedTextBlock(text: string): ContentBlock {
+  const block: ContentBlock = { type: "text", text };
+  (block as unknown as Record<string, unknown>).cache_control = {
+    type: "ephemeral",
+    ttl: "1h",
+  };
+  return block;
+}

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/reconcile.ts

@@ -38,9 +38,9 @@ import { join, relative, sep } from "node:path";
 
 import { parse as parseYaml } from "yaml";
 
-import type { Provider } from "../../providers/types.js";
-import { getLogger } from "../../util/logger.js";
-import { listPages, readPage, writePage } from "../v2/page-store.js";
+import { listPages, readPage, writePage } from "../../../memory/v2/page-store.js";
+import type { Provider } from "../../../providers/types.js";
+import { getLogger } from "../../../util/logger.js";
 import { assignPages } from "./assign.js";
 import { loadCore } from "./core.js";
 import { invalidateLanes } from "./shadow-plugin.js";

package/src/plugins/defaults/memory-v3-shadow/register.ts

@@ -0,0 +1,26 @@
+/**
+ * Default `memory-v3-shadow` plugin.
+ *
+ * Houses the memory-v3 shadow/live orchestration engine (this directory) and
+ * its injector (`./injector.ts`). The injector is still consumed by the static
+ * chain in `memory-retrieval/injector-chain.ts`; the `user-prompt-submit` /
+ * `post-compact` hooks below are no-op scaffolding for the eventual
+ * convergence, when v3 injection moves off the loop-driven chain and into these
+ * lifecycle hooks. See each hook file for the convergence note.
+ */
+
+import { type Plugin } from "../../types.js";
+import postCompact from "./hooks/post-compact.js";
+import userPromptSubmit from "./hooks/user-prompt-submit.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const memoryV3ShadowPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": userPromptSubmit,
+    "post-compact": postCompact,
+  },
+};

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/render-injection.ts

@@ -1,4 +1,4 @@
-import { wrapMemoryBlock } from "../memory-marker.js";
+import { wrapMemoryBlock } from "../../../memory/memory-marker.js";
 import { Slug } from "./types.js";
 
 /**