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

package/src/__tests__/injector-disk-pressure.test.ts

@@ -1,23 +1,28 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 
+import {
+  clearConversations,
+  setConversation,
+} from "../daemon/conversation-registry.js";
+import type { ChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
 import {
   applyRuntimeInjections,
   stripInjectionsForCompaction,
 } from "../daemon/conversation-runtime-assembly.js";
 import {
   DEFAULT_INJECTOR_ORDER,
-  defaultInjectorsPlugin,
+  defaultInjectors,
   DISK_PRESSURE_WARNING_PROMPT,
-} from "../plugins/defaults/injectors/register.js";
-import {
-  registerPlugin,
-  resetPluginRegistryForTests,
-} from "../plugins/registry.js";
+} from "../plugins/defaults/memory-retrieval/injectors.js";
 import type { Injector, TurnContext } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";
 
+// `makeContext` and the workspace registry seed share this id so the
+// `workspace-context` injector resolves the seeded block for the turn.
+const TEST_CONVERSATION_ID = "conv-test";
+
 function findInjector(name: string): Injector {
-  const injector = defaultInjectorsPlugin.injectors?.find(
+  const injector = defaultInjectors.find(
     (candidate) => candidate.name === name,
   );
   if (!injector) {
@@ -29,7 +34,7 @@ function findInjector(name: string): Injector {
 function makeContext(overrides: Partial<TurnContext> = {}): TurnContext {
   return {
     requestId: "req-test",
-    conversationId: "conv-test",
+    conversationId: TEST_CONVERSATION_ID,
     turnIndex: 0,
     trust: { sourceChannel: "vellum", trustClass: "guardian" },
     ...overrides,
@@ -47,20 +52,58 @@ function tailTexts(messages: Message[]): string[] {
 }
 
 const diskPressureInjector = findInjector("disk-pressure-warning");
-const cleanupContext = { cleanupModeActive: true };
+
+// The disk-pressure-warning and workspace-context injectors both read their
+// per-conversation state off the live `Conversation` looked up by
+// `conversationId`. Seed a single fake instance under the id `makeContext()`
+// uses, carrying the disk-pressure flag and the workspace top-level cache, so a
+// turn can exercise both; the seed helpers mutate and re-register the same
+// instance. An empty (non-dirty) workspace cache resolves to no block, so
+// disk-pressure-only tests don't trigger a directory scan.
+let liveConversation: {
+  conversationId: string;
+  workingDir: string;
+  workspaceTopLevelContext: string | null;
+  workspaceTopLevelDirty: boolean;
+  diskPressureCleanupModeActive: boolean;
+  channelCapabilities?: ChannelCapabilities;
+};
+
+function resetLiveConversation(): void {
+  liveConversation = {
+    conversationId: TEST_CONVERSATION_ID,
+    workingDir: "/workspace",
+    workspaceTopLevelContext: "",
+    workspaceTopLevelDirty: false,
+    diskPressureCleanupModeActive: false,
+  };
+}
+
+function seedChannelCapabilities(caps: ChannelCapabilities): void {
+  liveConversation.channelCapabilities = caps;
+  setConversation(TEST_CONVERSATION_ID, liveConversation as never);
+}
+
+function seedDiskPressure(cleanupModeActive: boolean): void {
+  liveConversation.diskPressureCleanupModeActive = cleanupModeActive;
+  setConversation(TEST_CONVERSATION_ID, liveConversation as never);
+}
+
+function seedWorkspaceContext(text: string): void {
+  liveConversation.workspaceTopLevelContext = text;
+  liveConversation.workspaceTopLevelDirty = false;
+  setConversation(TEST_CONVERSATION_ID, liveConversation as never);
+}
 
 describe("disk-pressure-warning injector", () => {
   beforeEach(() => {
-    resetPluginRegistryForTests();
-    registerPlugin(defaultInjectorsPlugin);
+    clearConversations();
+    resetLiveConversation();
   });
 
   test("emits the exact cleanup prompt during disk pressure cleanup mode", async () => {
-    const block = await diskPressureInjector.produce(
-      makeContext({
-        injectionInputs: { diskPressureContext: cleanupContext },
-      }),
-    );
+    seedDiskPressure(true);
+    const block = await diskPressureInjector.produce(makeContext());
 
     expect(block).toEqual({
       id: "disk-pressure-warning",
@@ -81,21 +124,14 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
 </disk_pressure_warning>`);
   });
 
-  test("omits the prompt when cleanup context is null or inactive", async () => {
+  test("omits the prompt when no cleanup context is registered or it is inactive", async () => {
     await expect(
-      diskPressureInjector.produce(
-        makeContext({ injectionInputs: { diskPressureContext: null } }),
-      ),
+      diskPressureInjector.produce(makeContext()),
     ).resolves.toBeNull();
 
+    seedDiskPressure(false);
     await expect(
-      diskPressureInjector.produce(
-        makeContext({
-          injectionInputs: {
-            diskPressureContext: { cleanupModeActive: false },
-          },
-        }),
-      ),
+      diskPressureInjector.produce(makeContext()),
     ).resolves.toBeNull();
   });
 
@@ -106,10 +142,10 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
     const workspace = "<workspace>\nRoot: /workspace\n</workspace>";
     const turnContext = "<turn_context>\ninterface: macos\n</turn_context>";
 
+    seedWorkspaceContext(workspace);
+    seedDiskPressure(true);
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeContext(),
-      diskPressureContext: cleanupContext,
-      workspaceTopLevelContext: workspace,
       unifiedTurnContext: turnContext,
     });
 
@@ -127,13 +163,12 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
   });
 
   test("survives minimal mode as safety-critical context", async () => {
+    seedDiskPressure(true);
     const result = await applyRuntimeInjections(
       [{ role: "user", content: [{ type: "text", text: "status" }] }],
       {
         turnContext: makeContext(),
         mode: "minimal",
-        diskPressureContext: cleanupContext,
-        workspaceTopLevelContext: "<workspace>...</workspace>",
         unifiedTurnContext: "<turn_context>...</turn_context>",
       },
     );
@@ -163,16 +198,16 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
       },
     ];
 
+    seedDiskPressure(true);
+    seedChannelCapabilities({
+      channel: "slack",
+      dashboardCapable: false,
+      supportsDynamicUi: false,
+      supportsVoiceInput: false,
+      chatType: "channel",
+    });
     const result = await applyRuntimeInjections(originalRun, {
       turnContext: makeContext(),
-      diskPressureContext: cleanupContext,
-      channelCapabilities: {
-        channel: "slack",
-        dashboardCapable: false,
-        supportsDynamicUi: false,
-        supportsVoiceInput: false,
-        chatType: "channel",
-      },
       slackChronologicalMessages: slackTranscript,
     });
 
@@ -190,16 +225,15 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
       { role: "user", content: [{ type: "text", text: "find large files" }] },
     ];
 
+    seedDiskPressure(true);
     const first = await applyRuntimeInjections(runMessages, {
       turnContext: makeContext(),
-      diskPressureContext: cleanupContext,
     });
     const stripped = stripInjectionsForCompaction(first.messages);
     expect(tailTexts(stripped)).toEqual(["find large files"]);
 
     const second = await applyRuntimeInjections(stripped, {
       turnContext: makeContext(),
-      diskPressureContext: cleanupContext,
     });
     expect(
       tailTexts(second.messages).filter(

package/src/__tests__/injector-document-comments.test.ts

@@ -8,12 +8,12 @@ mock.module("../documents/document-comments-store.js", () => ({
   listComments: (...args: unknown[]) => listCommentsMock(...args),
 }));
 
-const { DEFAULT_INJECTOR_ORDER, defaultInjectorsPlugin } =
-  await import("../plugins/defaults/injectors/register.js");
+const { DEFAULT_INJECTOR_ORDER, defaultInjectors } =
+  await import("../plugins/defaults/memory-retrieval/injectors.js");
 import type { Injector, TurnContext } from "../plugins/types.js";
 
 function findInjector(name: string): Injector {
-  const injector = defaultInjectorsPlugin.injectors?.find(
+  const injector = defaultInjectors.find(
     (candidate) => candidate.name === name,
   );
   if (!injector) {

package/src/__tests__/injector-pkb-v2-silenced.test.ts

@@ -12,7 +12,9 @@
  * search so the reminder-with-hints branch can resolve deterministically
  * when called.
  */
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 let v2Active = false;
 
@@ -20,7 +22,12 @@ const realLoader = await import("../config/loader.js");
 
 mock.module("../config/loader.js", () => ({
   ...realLoader,
-  getConfig: () => ({ memory: { v2: { enabled: v2Active } } }),
+  getConfig: () => ({
+    memory: {
+      v2: { enabled: v2Active },
+      retrieval: { scratchpadInjection: { enabled: true } },
+    },
+  }),
 }));
 
 mock.module("../memory/pkb/pkb-search.js", () => ({
@@ -29,12 +36,10 @@ mock.module("../memory/pkb/pkb-search.js", () => ({
 
 const { applyRuntimeInjections } =
   await import("../daemon/conversation-runtime-assembly.js");
-const { defaultInjectorsPlugin } =
-  await import("../plugins/defaults/injectors/register.js");
-const { registerPlugin, resetPluginRegistryForTests } =
-  await import("../plugins/registry.js");
+import { getPkbRoot } from "../memory/pkb/types.js";
 import type { TurnContext } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";
+import { getWorkspacePromptPath } from "../util/platform.js";
 
 function makeTurnContext(): TurnContext {
   return {
@@ -55,28 +60,37 @@ function tailTexts(messages: Message[]): string[] {
     .map((b) => b.text);
 }
 
-const PKB_CONTEXT = "essentials of the project";
-const NOW_CONTENT = "Current focus: shipping G2.1";
 const RUN_MESSAGES: Message[] = [
   { role: "user", content: [{ type: "text", text: "What next?" }] },
 ];
 
 describe("PKB injector v2 cutover behavior", () => {
+  // The pkb-reminder gate derives PKB-active state from the workspace
+  // (`readPkbContext()` returning content) behind the guardian trust on
+  // `makeTurnContext()`, so seed a default auto-injected PKB file rather than
+  // passing a flag.
   beforeEach(() => {
-    resetPluginRegistryForTests();
-    registerPlugin(defaultInjectorsPlugin);
     v2Active = false;
+    mkdirSync(getPkbRoot(), { recursive: true });
+    writeFileSync(
+      join(getPkbRoot(), "INDEX.md"),
+      "workspace knowledge index",
+      "utf-8",
+    );
+    // now-md sources NOW.md from the workspace behind the same guardian trust,
+    // so seed the file rather than passing a flag.
+    const nowPath = getWorkspacePromptPath("NOW.md");
+    mkdirSync(dirname(nowPath), { recursive: true });
+    writeFileSync(nowPath, "Current focus: shipping G2.1", "utf-8");
+  });
+  afterEach(() => {
+    rmSync(getPkbRoot(), { recursive: true, force: true });
+    rmSync(getWorkspacePromptPath("NOW.md"), { force: true });
   });
 
   test("v2 inactive → pkb-context, pkb-reminder, and now-md all produce blocks", async () => {
     const result = await applyRuntimeInjections(RUN_MESSAGES, {
       turnContext: makeTurnContext(),
-      pkbContext: PKB_CONTEXT,
-      pkbActive: true,
-      pkbScopeId: "scope-default",
-      pkbRoot: "/tmp/pkb",
-      pkbConversation: { messages: [] },
-      nowScratchpad: NOW_CONTENT,
     });
 
     const texts = tailTexts(result.messages);
@@ -89,12 +103,6 @@ describe("PKB injector v2 cutover behavior", () => {
     v2Active = true;
     const result = await applyRuntimeInjections(RUN_MESSAGES, {
       turnContext: makeTurnContext(),
-      pkbContext: PKB_CONTEXT,
-      pkbActive: true,
-      pkbScopeId: "scope-default",
-      pkbRoot: "/tmp/pkb",
-      pkbConversation: { messages: [] },
-      nowScratchpad: NOW_CONTENT,
     });
 
     const texts = tailTexts(result.messages);

package/src/__tests__/injector-v3-suppression.test.ts

@@ -1,34 +1,38 @@
 /**
  * Tests for the memory-v3-live v2-suppression branch in
- * `applyRuntimeInjections` (PR L6 of the memory-v3-live plan).
+ * `applyRuntimeInjections`.
  *
- * When `suppressV2MemoryForV3` is on AND the v3 injector (id `memory-v3`,
+ * When the `memory-v3-live` flag is on AND the v3 injector (id `memory-v3`,
  * placement `after-memory-prefix`) actually produces a block, runtime
  * assembly strips the v2 `<memory>` prefix from EVERY user message before
  * splicing the v3 block — so v3 becomes the sole `<memory>` source and history
  * is byte-stable for prompt caching.
  *
- * Keyed off whether v3 produced a block, NOT off the option alone: a v3
+ * Keyed off whether v3 produced a block, NOT off the flag alone: a v3
  * failure (`produce()` → null) leaves v2's block intact (fallback-to-v2).
  *
  * The flag-off path must be byte-for-byte identical to today — that is the
- * load-bearing regression guard.
+ * load-bearing regression guard. `applyRuntimeInjections` reads the flag
+ * itself, so these tests drive it through the override cache.
  */
 
-import { beforeEach, describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
-import {
-  getInjectors,
-  registerPlugin,
-  resetPluginRegistryForTests,
-} from "../plugins/registry.js";
 import type {
   InjectionBlock,
   Injector,
-  Plugin,
   TurnContext,
 } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";
+import { setOverridesForTesting } from "./feature-flag-test-helpers.js";
+
+// Drive the suppression branch by controlling the static injector chain that
+// `applyRuntimeInjections` walks. The slot is mutated per-test to stand in for
+// the memory-v3 injector producing (or not producing) a block.
+const injectorChainSlot: Injector[] = [];
+mock.module("../plugins/defaults/memory-retrieval/injector-chain.js", () => ({
+  getInjectorChain: () => injectorChainSlot,
+}));
 
 const { applyRuntimeInjections } =
   await import("../daemon/conversation-runtime-assembly.js");
@@ -42,10 +46,6 @@ function makeTurnContext(): TurnContext {
   };
 }
 
-function wrapInPlugin(name: string, injectors: Injector[]): Plugin {
-  return { manifest: { name, version: "0.0.1" }, injectors };
-}
-
 /**
  * A fake v3 injector that mirrors the real one's id + placement. The real
  * injector's `renderMemoryBlock` already wraps its content in
@@ -88,11 +88,15 @@ function tailTexts(messages: Message[]): string[] {
 
 describe("memory-v3-live v2 suppression", () => {
   beforeEach(() => {
-    resetPluginRegistryForTests();
+    injectorChainSlot.length = 0;
+    // Clean baseline: no overrides → `memory-v3-live` resolves to its registry
+    // default (off). Each test seeds the flag it needs.
+    setOverridesForTesting({});
   });
 
   test("flag ON + v3 produced a block → v2 stripped from all turns, exactly one <memory> (the v3 block)", async () => {
-    registerPlugin(wrapInPlugin("v3", [v3Injector("v3 working set")]));
+    setOverridesForTesting({ "memory-v3-live": true });
+    injectorChainSlot.push(v3Injector("v3 working set"));
 
     // History: a prior user turn that still carries a v2 block (rehydrated),
     // plus the current tail user turn with its own v2 block.
@@ -107,7 +111,6 @@ describe("memory-v3-live v2 suppression", () => {
 
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeTurnContext(),
-      suppressV2MemoryForV3: true,
     });
 
     // Exactly one <memory> source across the WHOLE assembled context.
@@ -138,7 +141,8 @@ describe("memory-v3-live v2 suppression", () => {
   });
 
   test("flag ON but v3 produced NOTHING → v2 block left intact (fallback-to-v2)", async () => {
-    registerPlugin(wrapInPlugin("v3", [v3Injector(null)]));
+    setOverridesForTesting({ "memory-v3-live": true });
+    injectorChainSlot.push(v3Injector(null));
 
     const runMessages: Message[] = [
       userMsgWithV2Memory("fresh recalled fact", "current question"),
@@ -146,7 +150,6 @@ describe("memory-v3-live v2 suppression", () => {
 
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeTurnContext(),
-      suppressV2MemoryForV3: true,
     });
 
     // v2's block survives — the turn still ships memory.
@@ -158,7 +161,7 @@ describe("memory-v3-live v2 suppression", () => {
   });
 
   test("flag OFF → byte-for-byte identical to today even when v3 would have produced a block", async () => {
-    registerPlugin(wrapInPlugin("v3", [v3Injector("v3 working set")]));
+    injectorChainSlot.push(v3Injector("v3 working set"));
 
     const runMessages: Message[] = [
       userMsgWithV2Memory("old recalled fact", "earlier question"),
@@ -169,16 +172,16 @@ describe("memory-v3-live v2 suppression", () => {
       userMsgWithV2Memory("fresh recalled fact", "current question"),
     ];
 
-    // With suppression off, the v3 injector still runs through the chain
-    // (after-memory-prefix), but NO v2 stripping happens. This captures the
-    // exact pre-flag assembly behavior: v2 prefix stays, v3 splices after it.
+    // With the flag off (registry default), the v3 injector still runs through
+    // the chain (after-memory-prefix), but NO v2 stripping happens. This
+    // captures the exact pre-flag assembly behavior: v2 prefix stays, v3
+    // splices after it.
     const offResult = await applyRuntimeInjections(runMessages, {
       turnContext: makeTurnContext(),
-      suppressV2MemoryForV3: false,
     });
 
     // The tail keeps v2's block AND gains v3's (the historical double-injection
-    // the suppression PR exists to prevent) — proving suppression is the ONLY
+    // the suppression exists to prevent) — proving suppression is the ONLY
     // behavior change and it is fully gated off here.
     const texts = tailTexts(offResult.messages);
     expect(texts[0]).toBe("<memory>\nfresh recalled fact\n</memory>");
@@ -190,21 +193,13 @@ describe("memory-v3-live v2 suppression", () => {
       .filter((b): b is { type: "text"; text: string } => b.type === "text")
       .map((b) => b.text);
     expect(firstUserTexts[0]).toBe("<memory>\nold recalled fact\n</memory>");
-
-    // Strongest guard: omitting the option entirely yields the SAME result as
-    // passing it false — the default path is untouched by this PR.
-    resetPluginRegistryForTests();
-    registerPlugin(wrapInPlugin("v3", [v3Injector("v3 working set")]));
-    const defaultResult = await applyRuntimeInjections(runMessages, {
-      turnContext: makeTurnContext(),
-    });
-    expect(defaultResult.messages).toEqual(offResult.messages);
   });
 
   test("no v3 injector registered + flag ON → no stripping, messages untouched", async () => {
     // No injector named memory-v3 at all (e.g. plugin not loaded): the
     // suppression branch keys off the produced block, so nothing is stripped.
-    expect(getInjectors()).toHaveLength(0);
+    setOverridesForTesting({ "memory-v3-live": true });
+    expect(injectorChainSlot).toHaveLength(0);
 
     const runMessages: Message[] = [
       userMsgWithV2Memory("fresh recalled fact", "current question"),
@@ -212,7 +207,6 @@ describe("memory-v3-live v2 suppression", () => {
 
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeTurnContext(),
-      suppressV2MemoryForV3: true,
     });
 
     expect(result.messages).toEqual(runMessages);

package/src/__tests__/internal-telemetry-routes.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// Toggle for the collectUsageData opt-out the real store consults. The store
+// module is intentionally NOT mocked here — it has its own DB-backed tests, and
+// Bun's `mock.module` is process-global, so mocking it would leak into those
+// tests when files share an invocation. Exercising the real store keeps every
+// auth-fallback test order-independent.
+let collectUsageData = true;
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+    secretDetection: { enabled: false },
+    collectUsageData,
+  }),
+}));
+
+import { queryUnreportedAuthFallbackEvents } from "../memory/auth-fallback-events-store.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import { authFallbackEvents } from "../memory/schema.js";
+import { GATEWAY_PRINCIPALS } from "../runtime/auth/route-policy.js";
+import { RouteError } from "../runtime/routes/errors.js";
+import { ROUTES } from "../runtime/routes/internal-telemetry-routes.js";
+import type { RouteHandlerArgs } from "../runtime/routes/types.js";
+
+initializeDb();
+
+const route = ROUTES.find(
+  (r) => r.operationId === "internal_telemetry_auth_fallback",
+);
+
+function call(body: unknown) {
+  if (!route) throw new Error("route not found");
+  return route.handler({ body } as RouteHandlerArgs);
+}
+
+const VALID_BODY = {
+  window_start: 1000,
+  window_end: 2000,
+  counts: [
+    {
+      guard: "edge",
+      path: "/v1/messages",
+      failure_kind: "missing_authorization",
+      count: 5,
+    },
+  ],
+};
+
+describe("internal-telemetry-routes: auth-fallback", () => {
+  beforeEach(() => {
+    collectUsageData = true;
+    getDb().delete(authFallbackEvents).run();
+  });
+
+  test("route is locked to service-token callers (GATEWAY_PRINCIPALS + internal.write)", () => {
+    expect(route).toBeDefined();
+    expect(route?.endpoint).toBe("internal/telemetry/auth-fallback");
+    expect(route?.method).toBe("POST");
+    expect(route?.policy?.allowedPrincipalTypes).toEqual(GATEWAY_PRINCIPALS);
+    expect(route?.policy?.requiredScopes).toEqual(["internal.write"]);
+  });
+
+  test("valid batch is persisted with snake_case → camelCase mapping", () => {
+    const result = call(VALID_BODY);
+    expect(result).toEqual({ recorded: 1 });
+
+    const rows = queryUnreportedAuthFallbackEvents(0, undefined, 100);
+    expect(rows.length).toBe(1);
+    expect(rows[0]).toMatchObject({
+      guard: "edge",
+      path: "/v1/messages",
+      failureKind: "missing_authorization",
+      count: 5,
+      windowStart: 1000,
+      windowEnd: 2000,
+    });
+  });
+
+  test("returns skipped and persists nothing under the opt-out", () => {
+    collectUsageData = false;
+    expect(call(VALID_BODY)).toEqual({ skipped: true });
+    expect(queryUnreportedAuthFallbackEvents(0, undefined, 100).length).toBe(0);
+  });
+
+  test("rejects a malformed body without persisting", () => {
+    expect(() => call({ window_start: 1000 })).toThrow(RouteError);
+    expect(() => call({ ...VALID_BODY, counts: [] })).toThrow(RouteError);
+    expect(() =>
+      call({
+        ...VALID_BODY,
+        counts: [{ guard: "edge", path: "/x", failure_kind: "y", count: 0 }],
+      }),
+    ).toThrow(RouteError);
+    expect(queryUnreportedAuthFallbackEvents(0, undefined, 100).length).toBe(0);
+  });
+});

package/src/__tests__/list-messages-hidden-metadata.test.ts

@@ -96,6 +96,44 @@ describe("handleListMessages metadata.hidden filtering", () => {
     expect(llmRows[1].metadata).toContain('"hidden":true');
   });
 
+  test("UI serializer omits system rows but LLM-side getMessages includes them", async () => {
+    // GIVEN a conversation with a system row sandwiched between two
+    // renderable turns (e.g. a skill-authored context message)
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "first visible" }]),
+    );
+    await addMessage(
+      conv.id,
+      "system",
+      JSON.stringify([{ type: "text", text: "system scaffolding" }]),
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "second visible" }]),
+    );
+
+    // WHEN the UI history list is serialized
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    });
+    const body = response as { messages: MessagePayload[] };
+
+    // THEN only the user/assistant turns are returned, never the system row
+    expect(body.messages.map((m) => m.role)).toEqual(["user", "assistant"]);
+    expect(
+      body.messages.some((m) => plainText(m).includes("system scaffolding")),
+    ).toBe(false);
+
+    // AND the LLM-side loader still includes the system row for agent context
+    const llmRows = getMessages(conv.id);
+    expect(llmRows).toHaveLength(3);
+    expect(llmRows[1].role).toBe("system");
+  });
+
   test("messages without metadata or with hidden=false are returned", async () => {
     const conv = createConversation();
     await addMessage(