Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

44.7 KB
Raw Blame
import { describe, expect, it, vi } from "vitest";

import type { OpenVikingClient } from "../../client.js";
import { memoryOpenVikingConfigSchema } from "../../config.js";
import { createMemoryOpenVikingContextEngine } from "../../context-engine.js";
import { RuntimeQueryConfigStore } from "../../query-config.js";
import { RecallTraceMemoryStore } from "../../recall-trace.js";

const cfg = memoryOpenVikingConfigSchema.parse({
  contextManagementMode: "openviking",
  mode: "remote",
  baseUrl: "http://127.0.0.1:1933",
  autoCapture: false,
  autoRecall: false,
});

function roughEstimate(messages: unknown[]): number {
  return Math.ceil(JSON.stringify(messages).length / 4);
}

function systemPromptTokens(text?: string): number {
  return text ? Math.ceil(text.length / 4) : 0;
}

function makeLogger() {
  return {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
  };
}

function makeStats() {
  return {
    totalArchives: 0,
    includedArchives: 0,
    droppedArchives: 0,
    failedArchives: 0,
    activeTokens: 0,
    archiveTokens: 0,
  };
}

function makeEngine(
  contextResult: unknown,
  opts?: {
    cfgOverrides?: Record<string, unknown>;
    traceRecorder?: RecallTraceMemoryStore;
    queryConfigStore?: RuntimeQueryConfigStore;
  },
) {
  const logger = makeLogger();
  const client = {
    healthCheck: vi.fn().mockResolvedValue(undefined),
    getSessionContext: vi.fn().mockResolvedValue(contextResult),
    searchContext: vi.fn().mockResolvedValue({ entries: [], rendered: "", stats: {} }),
    find: vi.fn().mockResolvedValue({ memories: [], resources: [], total: 0 }),
    read: vi.fn().mockResolvedValue(""),
  } as unknown as OpenVikingClient;
  const getClient = vi.fn().mockResolvedValue(client);
  const resolveAgentId = vi.fn((sessionId: string) => `agent:${sessionId}`);
  const localCfg = opts?.cfgOverrides
    ? memoryOpenVikingConfigSchema.parse({
        ...cfg,
        ...opts.cfgOverrides,
      })
    : cfg;

  const engine = createMemoryOpenVikingContextEngine({
    id: "openviking",
    name: "Context Engine (OpenViking)",
    version: "test",
    cfg: localCfg,
    logger,
    getClient,
    resolveAgentId,
    traceRecorder: opts?.traceRecorder,
    queryConfigStore: opts?.queryConfigStore,
  });

  return {
    engine,
    client: client as unknown as {
      getSessionContext: ReturnType<typeof vi.fn>;
      healthCheck: ReturnType<typeof vi.fn>;
      searchContext: ReturnType<typeof vi.fn>;
      find: ReturnType<typeof vi.fn>;
      read: ReturnType<typeof vi.fn>;
    },
    getClient,
    logger,
    resolveAgentId,
  };
}

describe("context-engine assemble()", () => {
  describe("recall from the separately supplied prompt", () => {
    const prompt = "what backend language should we use?";
    const memory = "User prefers Rust for backend tasks.";
    function mockRecall(client: ReturnType<typeof makeEngine>["client"]) {
      client.searchContext.mockResolvedValue({
        entries: [{ uri: "viking://user/default/memories/rust-pref", category: "preferences", text: memory, score: 0.93 }],
        rendered: `<memory>${memory}</memory>`,
        stats: { candidates: 1, used_tokens: 18 },
      });
    }

    it.each([false, true])("recalls on a fresh session (missing session: %s) without manufacturing a user turn", async (missing) => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      if (missing) client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
      mockRecall(client);
      const messages: [] = [];
      const result = await engine.assemble({ sessionId: "new-session", messages, prompt, availableTools: new Set() });
      expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.objectContaining({ sessionId: "new-session" }));
      expect(result.messages).toBe(messages);
      expect(result.systemPromptAddition).toContain(memory);
      expect(result.systemPromptAddition).not.toContain(prompt);
      expect(result.estimatedTokens).toBeGreaterThan(systemPromptTokens(result.systemPromptAddition));
    });

    it("still recalls under peer_role=sender when the host supplies no sender", async () => {
      const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, peer_role: "sender" } });
      mockRecall(client);
      const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.objectContaining({ actorPeerId: undefined }));
      expect(result.systemPromptAddition).toContain(memory);
      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("no sender identity"));

      logger.warn.mockClear();
      await engine.assemble({ sessionId: "session", messages: [], prompt, runtimeContext: { senderId: "telegram:12345" } });
      expect(client.searchContext).toHaveBeenLastCalledWith(prompt, expect.objectContaining({ actorPeerId: "telegram_12345" }));
      expect(logger.warn).not.toHaveBeenCalled();
    });

    it("recalls another detail from the same memory on a follow-up turn", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      const savedMemory = "Use Rust; deploy in eu-west.";
      let messageCount = 2;
      let lastServedAt: number | undefined;
      client.searchContext.mockImplementation(async (_query, options) => {
        const cooled = lastServedAt !== undefined && messageCount - lastServedAt < (options.dedupTurns ?? 0);
        if (cooled) return { entries: [], rendered: "", stats: {} };
        lastServedAt = messageCount;
        return {
          entries: [{ uri: "viking://user/default/memories/development", category: "preferences", text: savedMemory, score: 0.95 }],
          rendered: `<memory>${savedMemory}</memory>`, stats: {},
        };
      });
      const common = { sessionId: "existing-session", availableTools: new Set<string>() };
      const messages = [{ role: "user", content: "Hello" }, { role: "assistant", content: "Hello" }];
      const first = await engine.assemble({ ...common, messages, prompt: "What language should I use?" });
      expect(first.systemPromptAddition).toContain(savedMemory);

      const followupMessages = [...messages,
        { role: "user", content: "What language should I use?" },
        { role: "assistant", content: "Rust." },
      ];
      messageCount = followupMessages.length;
      const second = await engine.assemble({ ...common, messages: followupMessages, prompt: "What region should I deploy in?" });
      expect(second.systemPromptAddition).toContain("eu-west");
      expect(second.messages).toBe(followupMessages);
      expect(JSON.stringify(second.messages)).not.toContain("eu-west");
      expect(client.searchContext).toHaveBeenLastCalledWith("What region should I deploy in?", expect.objectContaining({ dedupTurns: 0 }));
    });

    it("keeps archive guidance and recalls the current prompt rather than the history tail", async () => {
      const { engine, client } = makeEngine({
        latest_archive_overview: "Previously discussed repository setup.",
        pre_archive_abstracts: [], messages: [], estimatedTokens: 10, stats: makeStats(),
      }, { cfgOverrides: { autoRecall: true } });
      mockRecall(client);
      const messages = [{ role: "user", content: "an unrelated old question" }];
      const result = await engine.assemble({ sessionId: "archived-session", messages, prompt });
      expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.anything());
      expect(result.systemPromptAddition).toContain("Session Context Guide");
      expect(result.systemPromptAddition).toContain(memory);
      expect(JSON.stringify(result.messages)).not.toContain(memory);
      expect(messages).toEqual([{ role: "user", content: "an unrelated old question" }]);
    });

    it.each([
      { autoRecall: false, prompt, bypassSessionPatterns: [] },
      { autoRecall: true, prompt: "", bypassSessionPatterns: [] },
      { autoRecall: true, prompt: "hi", bypassSessionPatterns: [] },
      { autoRecall: true, prompt, bypassSessionPatterns: ["agent:*:cron:**"] },
    ])("respects disabled, empty and bypassed recall: %j", async ({ prompt: currentPrompt, ...cfgOverrides }) => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides });
      const result = await engine.assemble({ sessionId: "session", sessionKey: "agent:main:cron:task", messages: [], prompt: currentPrompt });
      expect(client.searchContext).not.toHaveBeenCalled();
      expect(result.systemPromptAddition).toBeUndefined();
    });

    it.each(["no hits", "search failure", "budget exhausted"])("preserves history on %s", async (scenario) => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      if (scenario === "search failure") client.searchContext.mockRejectedValue(new Error("unavailable"));
      if (scenario === "budget exhausted") mockRecall(client);
      const messages = [{ role: "assistant", content: "previous answer" }];
      const result = await engine.assemble({ sessionId: "session", messages, prompt, tokenBudget: scenario === "budget exhausted" ? 1 : 128_000 });
      expect(result.messages).toBe(messages);
      expect(result.systemPromptAddition).toBeUndefined();
    });
  });

  describe("user profile injection", () => {
    const prompt = "what are my project alias and theme color?";
    const userProfileUri = "viking://~/memories/profile.md";
    const profile = "# User\n- Project alias: Basalt-x\n- Preferred theme color: marigold";
    const memory = "User prefers Rust for backend tasks.";

    function mockProfile(client: ReturnType<typeof makeEngine>["client"], profiles: Record<string, string> = { [userProfileUri]: profile }) {
      client.read.mockImplementation(async (uri: string) => {
        if (uri in profiles) return profiles[uri];
        throw new Error("[NOT_FOUND] File not found");
      });
    }

    function mockRecall(client: ReturnType<typeof makeEngine>["client"], text = memory) {
      client.searchContext.mockResolvedValue({
        entries: [{ uri: "viking://user/default/memories/preferences/rust", category: "preferences", text, score: 0.93 }],
        rendered: `<memory>${text}</memory>`,
        stats: {},
      });
    }

    it.each([false, true])("injects profile.md when recall finds nothing (missing session: %s)", async (missing) => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      if (missing) client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
      mockProfile(client);
      const messages: [] = [];
      const result = await engine.assemble({ sessionId: "new-session", messages, prompt });
      expect(client.read).toHaveBeenCalledWith(userProfileUri, undefined, 3000);
      expect(result.messages).toBe(messages);
      expect(result.systemPromptAddition).toContain(`<user-profile uri="${userProfileUri}">`);
      expect(result.systemPromptAddition).toContain("Basalt-x");
      expect(result.estimatedTokens).toBeGreaterThanOrEqual(systemPromptTokens(result.systemPromptAddition));
    });

    it("places the profile between the archive guide and recalled memories on every main turn", async () => {
      const { engine, client } = makeEngine({
        latest_archive_overview: "Previously discussed repository setup.",
        pre_archive_abstracts: [], messages: [], estimatedTokens: 10, stats: makeStats(),
      }, { cfgOverrides: { autoRecall: true } });
      mockProfile(client);
      mockRecall(client);
      for (const turnPrompt of [prompt, "and which backend language?"]) {
        const result = await engine.assemble({ sessionId: "archived-session", messages: [], prompt: turnPrompt });
        const addition = result.systemPromptAddition ?? "";
        const guideAt = addition.indexOf("Session Context Guide");
        const profileAt = addition.indexOf("<user-profile");
        const recallAt = addition.indexOf(memory);
        expect(guideAt).toBeGreaterThanOrEqual(0);
        expect(profileAt).toBeGreaterThan(guideAt);
        expect(recallAt).toBeGreaterThan(profileAt);
      }
    });

    it("injects the profile for prompts too short to recall", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client);
      const result = await engine.assemble({ sessionId: "session", messages: [], prompt: "hi" });
      expect(client.searchContext).not.toHaveBeenCalled();
      expect(result.systemPromptAddition).toContain("Basalt-x");
    });

    it("keeps recall when the profile is missing, and the profile when recall fails", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client, {});
      mockRecall(client);
      const recallOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(recallOnly.systemPromptAddition).toContain(memory);
      expect(recallOnly.systemPromptAddition).not.toContain("<user-profile");

      mockProfile(client);
      client.searchContext.mockRejectedValue(new Error("unavailable"));
      const profileOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(profileOnly.systemPromptAddition).toContain("Basalt-x");
      expect(profileOnly.systemPromptAddition).not.toContain(memory);
    });

    it("reads the actor peer's profile too under peer_role=sender", async () => {
      const peerProfileUri = "viking://~/peers/telegram_12345/memories/profile.md";
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, peer_role: "sender" } });
      mockProfile(client, { [userProfileUri]: profile, [peerProfileUri]: "# Peer\n- Timezone: UTC+8" });
      const result = await engine.assemble({
        sessionId: "session", messages: [], prompt, runtimeContext: { senderId: "telegram:12345" },
      });
      expect(client.read).toHaveBeenCalledWith(userProfileUri, "telegram_12345", 3000);
      expect(client.read).toHaveBeenCalledWith(peerProfileUri, "telegram_12345", 3000);
      expect(result.systemPromptAddition).toContain("Basalt-x");
      expect(result.systemPromptAddition).toContain(`<user-profile uri="${peerProfileUri}">`);
      expect(result.systemPromptAddition).toContain("Timezone: UTC+8");
    });

    it("bounds the profile read by the auto-recall timeout", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, autoRecallTimeoutMs: 1000 } });
      mockProfile(client);
      await engine.assemble({ sessionId: "session", messages: [], prompt: "hi" });
      expect(client.read).toHaveBeenCalledWith(userProfileUri, undefined, 1000);
    });

    it("warns when the profile read fails for a reason other than a missing file", async () => {
      const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockRecall(client);
      client.read.mockRejectedValue(new Error("OpenViking request failed [PERMISSION_DENIED]: forbidden"));
      const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(result.systemPromptAddition).toContain(memory);
      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining(`profile read failed (uri=${userProfileUri})`));
      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("PERMISSION_DENIED"));

      logger.warn.mockClear();
      mockProfile(client, {});
      await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining("profile read failed"));
    });

    it("caps a long profile", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client, { [userProfileUri]: `${"x".repeat(9000)}TAIL` });
      const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
      expect(result.systemPromptAddition).toContain("[profile truncated]");
      expect(result.systemPromptAddition).not.toContain("TAIL");
    });

    it("drops recall before the profile when the budget is tight", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client);
      const profileOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
      mockRecall(client, "long recalled memory ".repeat(200));
      const tight = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: profileOnly.estimatedTokens });
      expect(tight.systemPromptAddition).toBe(profileOnly.systemPromptAddition);
      const tighter = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: profileOnly.estimatedTokens - 1 });
      expect(tighter.systemPromptAddition).toBeUndefined();
    });

    it("keeps recall when the profile alone does not fit the budget", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client, {});
      mockRecall(client);
      const recallOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
      mockProfile(client, { [userProfileUri]: "画像".repeat(3950) });
      const result = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: recallOnly.estimatedTokens });
      expect(result.systemPromptAddition).toBe(recallOnly.systemPromptAddition);
      expect(result.systemPromptAddition).not.toContain("<user-profile");
    });

    it.each([
      { name: "autoRecall off", cfgOverrides: { autoRecall: false }, sessionKey: undefined },
      { name: "bypassed session", cfgOverrides: { autoRecall: true, bypassSessionPatterns: ["agent:*:cron:**"] }, sessionKey: "agent:main:cron:task" },
    ])("does not read the profile when $name", async ({ cfgOverrides, sessionKey }) => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides });
      mockProfile(client);
      const result = await engine.assemble({ sessionId: "session", sessionKey, messages: [], prompt });
      expect(client.read).not.toHaveBeenCalled();
      expect(result.systemPromptAddition).toBeUndefined();
    });

    it("does not inject the profile during transformContext", async () => {
      const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      mockProfile(client);
      const result = await engine.assemble({ sessionId: "session", messages: [{ role: "user", content: prompt }] });
      expect(client.read.mock.calls.some(([uri]) => uri === userProfileUri)).toBe(false);
      expect(JSON.stringify(result)).not.toContain("Basalt-x");
    });

    it("logs a missing OV session as skipped history, not a skipped assemble", async () => {
      const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
      client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
      await engine.assemble({ sessionId: "new-session", messages: [], prompt });
      const logged = logger.info.mock.calls.map(([line]) => String(line));
      expect(logged.some((line) => line.includes("session history not assembled because OV session does not exist"))).toBe(true);
      expect(logged.some((line) => line.includes("assemble skipped"))).toBe(false);
    });
  });

  it("prepends auto-recall to the latest user message during transformContext", async () => {
      const { engine, client } = makeEngine(
        {
          latest_archive_overview: "This OV context must not be rebuilt during transformContext.",
          pre_archive_abstracts: [],
          messages: [
            {
              id: "stored-current-user",
              role: "user",
              created_at: "2026-04-30T00:00:00Z",
              parts: [{ type: "text", text: "stale stored prompt" }],
            },
          ],
          estimatedTokens: 12,
          stats: makeStats(),
        },
        {
          cfgOverrides: {
            autoRecall: true,
            recallPreferAbstract: true,
          },
        },
      );
      client.searchContext.mockResolvedValueOnce({
        entries: [{
          uri: "viking://user/default/memories/rust-pref",
          category: "preferences",
          text: "User prefers Rust for backend tasks.",
          score: 0.93,
        }],
        rendered: '<memory uri="viking://user/default/memories/rust-pref">User prefers Rust for backend tasks.</memory>',
        stats: { candidates: 1, used_tokens: 18 },
      });

      const sourceMessages = [
        { role: "user", content: "[Session History Summary]\nOlder archive summary." },
        { role: "assistant", content: [{ type: "text", text: "Previous answer." }] },
        { role: "user", content: "what backend language should we use?" },
      ];

      const result = await engine.assemble({
        sessionId: "session-transform",
        messages: sourceMessages,
      });

      expect(client.getSessionContext).not.toHaveBeenCalled();
      expect(result.messages).toHaveLength(sourceMessages.length);
      expect(result.messages[0]).toBe(sourceMessages[0]);
      expect(result.messages[1]).toBe(sourceMessages[1]);
      expect(result.messages[2]?.role).toBe("user");
      expect(result.messages[2]?.content).toMatch(/^<relevant-memories>/);
      expect(result.messages[2]?.content).toContain("Source: openviking-auto-recall");
      expect(result.messages[2]?.content).toContain("User prefers Rust for backend tasks.");
      expect(result.messages[2]?.content).toContain("what backend language should we use?");
      expect(result.systemPromptAddition).toBeUndefined();
  });

  it("passes session metadata into auto-recall trace recording during transformContext", async () => {
      const traces = new RecallTraceMemoryStore(10);
      const { engine, client } = makeEngine(
        {
          latest_archive_overview: "unused",
          pre_archive_abstracts: [],
          messages: [],
          estimatedTokens: 0,
          stats: makeStats(),
        },
        {
          traceRecorder: traces,
          cfgOverrides: {
            autoRecall: true,
            recallPreferAbstract: true,
            recallTargetTypes: ["user"],
          },
        },
      );
      client.searchContext.mockResolvedValueOnce({
        entries: [{
          uri: "viking://user/default/memories/typescript-pref",
          category: "preferences",
          text: "Use TypeScript for gateway plugins.",
          score: 0.9,
        }],
        rendered: '<memory uri="viking://user/default/memories/typescript-pref">Use TypeScript for gateway plugins.</memory>',
        stats: { candidates: 1, used_tokens: 16 },
      });

      await engine.assemble({
        sessionId: "session-transform-trace",
        messages: [{ role: "user", content: "which language should the gateway plugin use?" }],
      });

      const recorded = traces.query({ turn: "latest", sessionId: "session-transform-trace", limit: 10 }).entries[0]!;
      expect(recorded.sessionId).toBe("session-transform-trace");
      expect(recorded.ovSessionId).toBe("session-transform-trace");
      expect(recorded.agentId).toBe("agent:session-transform-trace");
      expect(recorded.trigger.query).toBe("which language should the gateway plugin use?");
      expect(recorded.resourceTypes).toEqual(["user"]);
  });

  it("uses backward-compatible user and agent auto-recall by default during transformContext", async () => {
      const traces = new RecallTraceMemoryStore(10);
      const { engine, client } = makeEngine(
        {
          latest_archive_overview: "unused",
          pre_archive_abstracts: [],
          messages: [],
          estimatedTokens: 0,
          stats: makeStats(),
        },
        {
          traceRecorder: traces,
          cfgOverrides: {
            autoRecall: true,
            recallPreferAbstract: true,
          },
        },
      );
      client.searchContext.mockResolvedValue({
        entries: [{
          uri: "viking://user/memories/project-docs",
          category: "memory",
          text: "Memory docs for the gateway plugin.",
          score: 0.9,
        }],
        rendered: '<memory uri="viking://user/memories/project-docs">Memory docs for the gateway plugin.</memory>',
        stats: { candidates: 1, used_tokens: 14 },
      });

      await engine.assemble({
        sessionId: "session-transform-resource-default",
        messages: [{ role: "user", content: "where are the gateway plugin docs?" }],
      });

      expect(client.searchContext).toHaveBeenCalledTimes(1);
      expect(client.searchContext.mock.calls[0]?.[1]).toMatchObject({
        sessionId: "session-transform-resource-default",
        contextType: "memory",
        queryExpansion: "auto",
        dedupTurns: 5,
      });
      const recorded = traces.query({ turn: "latest", sessionId: "session-transform-resource-default", limit: 10 }).entries[0]!;
      expect(recorded.resourceTypes).toEqual(["user", "agent"]);
  });

  it("applies session effective query config to transformContext auto-recall", async () => {
      const localCfg = memoryOpenVikingConfigSchema.parse({
        ...cfg,
        autoRecall: true,
        recallPreferAbstract: true,
      });
      const queryConfigStore = RuntimeQueryConfigStore.createInMemory(localCfg);
      await queryConfigStore.set(
        "session",
        { agentId: "agent:session-dynamic-query", sessionId: "session-dynamic-query" },
        {
          recallLimit: 1,
          candidateLimit: 3,
          scoreThreshold: 0.5,
          resourceTypes: ["user"],
          maxInjectedChars: 1000,
        },
      );
      const { engine, client } = makeEngine(
        {
          latest_archive_overview: "unused",
          pre_archive_abstracts: [],
          messages: [],
          estimatedTokens: 0,
          stats: makeStats(),
        },
        {
          cfgOverrides: {
            autoRecall: true,
            recallPreferAbstract: true,
          },
          queryConfigStore,
        },
      );
      client.searchContext.mockResolvedValueOnce({
        entries: [{
          uri: "viking://user/default/memories/high",
          category: "preferences",
          text: "High-confidence dynamic query memory.",
          score: 0.9,
        }],
        rendered: '<memory uri="viking://user/default/memories/high">High-confidence dynamic query memory.</memory>',
        stats: { candidates: 1, used_tokens: 12 },
      });

      const result = await engine.assemble({
        sessionId: "session-dynamic-query",
        messages: [{ role: "user", content: "which dynamic query memory applies?" }],
      });

      expect(client.searchContext).toHaveBeenCalledTimes(1);
      expect(client.searchContext.mock.calls[0]?.[1]).toMatchObject({
        contextType: "memory",
        limit: 1,
        scoreThreshold: 0.5,
        maxTokens: 250,
      });
      expect(String(result.messages[0]?.content)).toContain("High-confidence dynamic query memory.");
      expect(String(result.messages[0]?.content)).not.toContain("Low-confidence memory should be filtered.");
  });

  it("passes through transformContext messages when the latest message is not user", async () => {
    const { engine, getClient } = makeEngine(
      {
        latest_archive_overview: "unused",
        pre_archive_abstracts: [],
        messages: [],
        estimatedTokens: 0,
        stats: makeStats(),
      },
      {
        cfgOverrides: {
          autoRecall: true,
        },
      },
    );
    const sourceMessages = [
      { role: "user", content: "run the tool" },
      {
        role: "assistant",
        content: [{ type: "toolCall", id: "tool_1", name: "bash", arguments: {} }],
      },
    ];

    const result = await engine.assemble({
      sessionId: "session-tool-loop",
      messages: sourceMessages,
    });

    expect(getClient).not.toHaveBeenCalled();
    expect(result.messages).toBe(sourceMessages);
    expect(result.estimatedTokens).toBe(0);
  });

  it("passes through transformContext latest user messages when auto-recall is disabled", async () => {
    const { engine, getClient } = makeEngine({
      latest_archive_overview: "unused",
      pre_archive_abstracts: [],
      messages: [],
      estimatedTokens: 0,
      stats: makeStats(),
    });
    const sourceMessages = [
      { role: "assistant", content: [{ type: "text", text: "Previous answer." }] },
      { role: "user", content: "what backend language should we use?" },
    ];

    const result = await engine.assemble({
      sessionId: "session-auto-recall-disabled",
      messages: sourceMessages,
    });

    expect(getClient).not.toHaveBeenCalled();
    expect(result.messages).toBe(sourceMessages);
    expect(result.estimatedTokens).toBe(roughEstimate(sourceMessages));
  });

  it("treats prompt-less assemble with availableTools as main assemble", async () => {
    const { engine, client, resolveAgentId } = makeEngine({
      latest_archive_overview: "# Session Summary\nPreviously discussed repository setup.",
      pre_archive_abstracts: [
        {
          archive_id: "archive_001",
          abstract: "Previously discussed repository setup.",
        },
      ],
      messages: [
        {
          id: "msg_main_no_prompt",
          role: "assistant",
          created_at: "2026-03-24T00:00:00Z",
          parts: [{ type: "text", text: "Stored answer from OpenViking." }],
        },
      ],
      estimatedTokens: 120,
      stats: {
        ...makeStats(),
        totalArchives: 1,
        includedArchives: 1,
        archiveTokens: 40,
        activeTokens: 80,
      },
    });

    const liveMessages = [{ role: "user", content: "fallback live message" }];
    const result = await engine.assemble({
      sessionId: "session-main-no-prompt",
      messages: liveMessages,
      tokenBudget: 4096,
      availableTools: new Set(),
    });

    expect(client.getSessionContext).toHaveBeenCalledWith(
      "session-main-no-prompt",
      4096,
    );
    expect(client.searchContext).not.toHaveBeenCalled();
    expect(result.messages[0]).toEqual({
      role: "user",
      content: "[Session History Summary]\n# Session Summary\nPreviously discussed repository setup.",
    });
    expect(result.messages[1]).toEqual({
      role: "assistant",
      content: [{ type: "text", text: "Stored answer from OpenViking." }],
    });
    expect(result.systemPromptAddition).toContain("Session Context Guide");
  });

  it("assembles summary archive and completed tool parts into agent messages", async () => {
    const { engine, client, resolveAgentId } = makeEngine({
      latest_archive_overview: "# Session Summary\nPreviously discussed repository setup.",
      pre_archive_abstracts: [
        {
          archive_id: "archive_001",
          abstract: "Previously discussed repository setup.",
        },
      ],
      messages: [
        {
          id: "msg_1",
          role: "assistant",
          created_at: "2026-03-24T00:00:00Z",
          parts: [
            { type: "text", text: "I checked the latest context." },
            { type: "context", abstract: "User prefers concise answers." },
            {
              type: "tool",
              tool_id: "tool_123",
              tool_name: "read_file",
              tool_input: { path: "src/app.ts" },
              tool_output: "export const value = 1;",
              tool_status: "completed",
            },
          ],
        },
      ],
      estimatedTokens: 321,
      stats: {
        ...makeStats(),
        totalArchives: 1,
        includedArchives: 1,
        archiveTokens: 40,
        activeTokens: 281,
      },
    });

    const liveMessages = [{ role: "user", content: "fallback live message" }];
    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-1",
      messages: liveMessages,
      tokenBudget: 4096,
    });

    expect(client.getSessionContext).toHaveBeenCalledWith("session-1", 4096);
    expect(result.estimatedTokens).toBe(
      roughEstimate(result.messages) + systemPromptTokens(result.systemPromptAddition),
    );
    expect(result.systemPromptAddition).toContain("Session Context Guide");
    expect(result.messages[0]).toEqual({
      role: "user",
      content: "[Session History Summary]\n# Session Summary\nPreviously discussed repository setup.",
    });
    expect(result.messages[1]).toEqual({
      role: "assistant",
      content: [
        { type: "text", text: "I checked the latest context." },
        { type: "text", text: "User prefers concise answers." },
        {
          type: "toolCall",
          id: "tool_123",
          name: "read_file",
          arguments: { path: "src/app.ts" },
        },
      ],
    });
    expect(result.messages[2]).toEqual({
      role: "toolResult",
      toolCallId: "tool_123",
      toolName: "read_file",
      content: [{ type: "text", text: "export const value = 1;" }],
      isError: false,
    });
  });

  it("passes through live messages when the session matches bypassSessionPatterns", async () => {
    const { engine, client, getClient } = makeEngine(
      {
        latest_archive_overview: "unused",
        pre_archive_abstracts: [],
        messages: [],
        estimatedTokens: 123,
        stats: makeStats(),
      },
      {
        cfgOverrides: {
          bypassSessionPatterns: ["agent:*:cron:**"],
        },
      },
    );

    const liveMessages = [{ role: "user", content: "fallback live message" }];
    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "runtime-session",
      sessionKey: "agent:main:cron:nightly:run:1",
      messages: liveMessages,
      tokenBudget: 4096,
    });

    expect(getClient).not.toHaveBeenCalled();
    expect(client.getSessionContext).not.toHaveBeenCalled();
    expect(result).toEqual({
      messages: liveMessages,
      estimatedTokens: roughEstimate(liveMessages),
    });
  });

  it("emits a non-error toolResult for a running tool (not a synthetic error)", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_2",
          role: "assistant",
          created_at: "2026-03-24T00:00:00Z",
          parts: [
            {
              type: "tool",
              tool_id: "tool_running",
              tool_name: "bash",
              tool_input: { command: "npm test" },
              tool_output: "",
              tool_status: "running",
            },
          ],
        },
      ],
      estimatedTokens: 88,
      stats: {
        ...makeStats(),
        activeTokens: 88,
      },
    });

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-running",
      messages: [],
    });

    expect(result.systemPromptAddition).toBeUndefined();
    expect(result.messages).toHaveLength(2);
    expect(result.messages[0]).toEqual({
      role: "assistant",
      content: [
        {
          type: "toolCall",
          id: "tool_running",
          name: "bash",
          arguments: { command: "npm test" },
        },
      ],
    });
    expect(result.messages[1]).toMatchObject({
      role: "toolResult",
      toolCallId: "tool_running",
      toolName: "bash",
      isError: false,
    });
    const text = (result.messages[1] as any).content?.[0]?.text ?? "";
    expect(text).toContain("interrupted");
    expect((result.messages[1] as { content: Array<{ text: string }> }).content[0]?.text).toContain(
      "interrupted",
    );
  });

  it("degrades tool parts without tool_id into assistant text blocks", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_3",
          role: "assistant",
          created_at: "2026-03-24T00:00:00Z",
          parts: [
            { type: "text", text: "Tool state snapshot:" },
            {
              type: "tool",
              tool_id: "",
              tool_name: "grep",
              tool_input: { pattern: "TODO" },
              tool_output: "src/app.ts:17 TODO refine this",
              tool_status: "completed",
            },
          ],
        },
      ],
      estimatedTokens: 71,
      stats: {
        ...makeStats(),
        activeTokens: 71,
      },
    });

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-missing-id",
      messages: [],
    });

    expect(result.messages).toEqual([
      {
        role: "assistant",
        content: [
          { type: "text", text: "Tool state snapshot:" },
          {
            type: "text",
            text: "[grep] (completed)\nInput: {\"pattern\":\"TODO\"}\nOutput: src/app.ts:17 TODO refine this",
          },
        ],
      },
    ]);
  });

  it("falls back to live messages when assembled active messages look truncated", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_4",
          role: "user",
          created_at: "2026-03-24T00:00:00Z",
          parts: [{ type: "text", text: "Only one stored message" }],
        },
      ],
      estimatedTokens: 12,
      stats: {
        ...makeStats(),
        activeTokens: 12,
      },
    });

    const liveMessages = [
      { role: "user", content: "message one" },
      { role: "assistant", content: [{ type: "text", text: "message two" }] },
    ];

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-fallback",
      messages: liveMessages,
      tokenBudget: 1024,
    });

    expect(result).toEqual({
      messages: liveMessages,
      estimatedTokens: roughEstimate(liveMessages),
    });
  });

  it("passes through when OV has no archives and no active messages (new user)", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "",
      latest_archive_id: "",
      pre_archive_abstracts: [],
      messages: [],
      estimatedTokens: 0,
      stats: makeStats(),
    });

    const liveMessages = [
      { role: "user", content: "hello, first message" },
    ];

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-new-user",
      messages: liveMessages,
    });

    expect(result.messages).toBe(liveMessages);
    expect(result.estimatedTokens).toBe(roughEstimate(liveMessages));
    expect(result.systemPromptAddition).toBeUndefined();
  });

  it("still produces non-empty output when OV messages have empty parts (overview fills it)", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "Some overview of previous sessions",
      latest_archive_id: "archive_001",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_empty",
          role: "assistant",
          created_at: "2026-03-29T00:00:00Z",
          parts: [],
        },
      ],
      estimatedTokens: 10,
      stats: {
        ...makeStats(),
        totalArchives: 1,
        includedArchives: 1,
      },
    });

    const liveMessages = [
      { role: "user", content: "what was that thing?" },
    ];

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-empty-parts",
      messages: liveMessages,
    });

    // Even with empty parts, the overview and archive index still produce messages
    // so sanitized.length > 0 and we get the assembled result (not fallback)
    expect(result.messages.length).toBeGreaterThanOrEqual(2);
    expect(result.messages[0]).toMatchObject({
      role: "user",
      content: expect.stringContaining("Session History Summary"),
    });
    expect(result.systemPromptAddition).toContain("Session Context Guide");
  });

  it("keeps assembled output within the requested token budget", async () => {
    const longText = "A".repeat(2500);
    const { engine } = makeEngine({
      latest_archive_overview: "# Session Summary\nA short overview",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_long_1",
          role: "user",
          created_at: "2026-03-24T00:00:00Z",
          parts: [{ type: "text", text: longText }],
        },
        {
          id: "msg_long_2",
          role: "assistant",
          created_at: "2026-03-24T00:00:01Z",
          parts: [{ type: "text", text: longText }],
        },
      ],
      estimatedTokens: 2000,
      stats: {
        ...makeStats(),
        totalArchives: 1,
        includedArchives: 1,
        activeTokens: 2000,
        archiveTokens: 10,
      },
    });

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-budgeted",
      messages: [],
      tokenBudget: 1024,
    });

    expect(result.estimatedTokens).toBeLessThanOrEqual(1024);
    expect(result.messages.length).toBeGreaterThan(0);
    expect(result.systemPromptAddition).toContain("Session Context Guide");
  });

  it("falls back to original messages when getClient throws", async () => {
    const logger = makeLogger();
    const getClient = vi.fn().mockRejectedValue(new Error("OV connection refused"));
    const resolveAgentId = vi.fn((_s: string) => "agent");

    const engine = createMemoryOpenVikingContextEngine({
      id: "openviking",
      name: "Test",
      version: "test",
      cfg,
      logger,
      getClient,
      resolveAgentId,
    });

    const liveMessages = [
      { role: "user", content: "hello" },
    ];

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-error",
      messages: liveMessages,
    });

    expect(result.messages).toBe(liveMessages);
    expect(result.estimatedTokens).toBe(roughEstimate(liveMessages));
    expect(result.systemPromptAddition).toBeUndefined();
  });

  it("drops tool-only user messages instead of emitting empty content (issue #1485)", async () => {
    const { engine } = makeEngine({
      latest_archive_overview: "",
      pre_archive_abstracts: [],
      messages: [
        {
          id: "msg_tool_only_user",
          role: "user",
          created_at: "2026-04-17T00:00:00Z",
          parts: [
            {
              type: "tool",
              tool_id: "tool_abc",
              tool_name: "bash",
              tool_input: { command: "ls" },
              tool_output: "file.txt",
              tool_status: "completed",
            },
          ],
        },
      ],
      estimatedTokens: 50,
      stats: { ...makeStats(), activeTokens: 50 },
    });

    const result = await engine.assemble({
      prompt: "current user prompt",
      sessionId: "session-tool-only",
      messages: [],
    });

    const emptyContentMsg = result.messages.find(
      (m) => typeof m.content === "string" && m.content === "",
    );
    expect(emptyContentMsg).toBeUndefined();
  });
});


describe("cloud recall digest injection", () => {
  it.each([false, true])("honors server no_relevant=%s", async (noRelevant) => {
    const { engine, client } = makeEngine({}, { cfgOverrides: { autoRecall: true, recallCompress: "server" } });
    client.searchContext.mockResolvedValueOnce({
      entries: [], rendered: "RAW SHOULD NOT APPEAR", digest: "Prefer Rust for backend tasks.",
      stats: { rewrite: noRelevant ? "no_relevant" : "rewritten" },
    });
    const result = await engine.assemble({ sessionId: "cloud-digest", messages: [{ role: "user", content: "what backend language should we use?" }] });
    expect(client.searchContext).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ recallCompress: "server" }));
    expect(JSON.stringify(result.messages)).not.toContain("RAW SHOULD NOT APPEAR");
    expect(JSON.stringify(result.messages).includes("Prefer Rust")).toBe(!noRelevant);
  });
});


it("native mode preserves host history and recall without reading OV history", async () => {
  const { engine, client } = makeEngine({ latest_archive_overview: "obsolete OV summary" }, { cfgOverrides: { contextManagementMode: "native", autoRecall: true } });
  client.searchContext.mockResolvedValue({ entries: [], rendered: "Remember Rust.", stats: {} });
  const messages = [{ role: "user", content: "earlier host constraint" }, { role: "assistant", content: "native summary" }];
  const result = await engine.assemble({ sessionId: "native", messages, prompt: "next question" });
  expect(result.messages).toBe(messages);
  expect(result.systemPromptAddition).toContain("Remember Rust.");
  expect(client.getSessionContext).not.toHaveBeenCalled();
  expect(client.searchContext).toHaveBeenCalledOnce();
});

it("keeps native history when a completed archive has no summary", async () => {
  const { engine, logger } = makeEngine({
    latest_archive_overview: "", pre_archive_abstracts: [],
    messages: [{ role: "assistant", parts: [{ type: "text", text: "retained tail" }] }],
    stats: { ...makeStats(), totalArchives: 1 },
  });
  const messages = [{ role: "user", content: "earlier constraint" }];
  const result = await engine.assemble({ sessionId: "no-wm", messages, prompt: "Continue" });
  expect(result.messages).toBe(messages);
  expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("no summary"));
});