Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import { describe, expect, it, vi } from "vitest";
import {
createOpenVikingCommandDefinitions,
} from "../../plugin/openviking-command-definitions.js";
import { registerOpenVikingContextEngine } from "../../plugin/openviking-context-engine-registration.js";
import { createOpenVikingQueryConfigCommandHandler } from "../../plugin/openviking-query-config-command.js";
import { createOpenVikingQueryRuntime } from "../../plugin/openviking-query-runtime.js";
import { createOpenVikingRecallTraceRuntime } from "../../plugin/openviking-recall-trace-runtime.js";
import {
createOpenVikingToolRegistrar,
} from "../../plugin/tool-registration.js";
import {
registerOpenVikingCommands,
} from "../../plugin/command-registration.js";
import {
RECALL_TRACE_ROUTE_PATHS,
registerRecallTraceRoutes,
} from "../../plugin/recall-trace-routes.js";
import { createOpenVikingService } from "../../plugin/openviking-services.js";
import { registerOpenVikingArchiveTools } from "../../plugin/openviking-archive-tools.js";
import { registerOpenVikingImportTools } from "../../plugin/openviking-import-tools.js";
import { createOpenVikingImportRuntime } from "../../plugin/openviking-import-runtime.js";
import { registerOpenVikingLifecycleHooks } from "../../plugin/openviking-lifecycle-hooks.js";
import { registerOpenVikingMemoryTools } from "../../plugin/openviking-memory-tools.js";
import { registerOpenVikingMemoryRecallTools } from "../../plugin/openviking-memory-recall-tools.js";
import { registerOpenVikingQueryTools } from "../../plugin/openviking-query-tools.js";
import { createOpenVikingSessionRoutingRuntime } from "../../plugin/openviking-session-routing-runtime.js";
import { registerOpenVikingRecallTraceTools } from "../../plugin/openviking-recall-trace-tools.js";
import { registerOpenVikingToolResultTools } from "../../plugin/openviking-tool-result-tools.js";
describe("plugin module seams", () => {
it("routes tools without a sender-scoped peer under peer_role=sender when the sender is missing", () => {
const logger = { info: vi.fn(), warn: vi.fn() };
const { resolvePluginSessionRouting } = createOpenVikingSessionRoutingRuntime({
peerRole: "sender",
peerPrefix: "default",
logFindRequests: false,
logger,
});
expect(resolvePluginSessionRouting({ sessionId: "session-1" }).actorPeerId).toBeUndefined();
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("no sender identity"));
logger.warn.mockClear();
expect(resolvePluginSessionRouting({ sessionId: "session-1", requesterSenderId: "ou_01:abc" }).actorPeerId).toBe("ou_01_abc");
expect(logger.warn).not.toHaveBeenCalled();
});
it("registers only enabled OpenViking tools through the tool-registration seam", () => {
const api = { registerTool: vi.fn() };
const logger = { debug: vi.fn() };
const registrar = createOpenVikingToolRegistrar({
api,
enabledToolNames: new Set(["ov_search"]),
logger,
});
const toolFactory = () => ({ name: "ov_search" });
const disabledFactory = () => ({ name: "memory_store" });
registrar(toolFactory, { name: "ov_search" });
registrar(disabledFactory, { name: "memory_store" });
expect(api.registerTool).toHaveBeenCalledTimes(1);
expect(api.registerTool).toHaveBeenCalledWith(toolFactory, { name: "ov_search" });
expect(logger.debug).toHaveBeenCalledWith("openviking: tool memory_store disabled by config");
});
it("registers command definitions without changing names or handlers", async () => {
const command = {
name: "ov-search",
description: "Search OpenViking resources and skills.",
acceptsArgs: true,
handler: vi.fn().mockResolvedValue({ text: "ok" }),
};
const api = { registerCommand: vi.fn() };
registerOpenVikingCommands(api, [command]);
expect(api.registerCommand).toHaveBeenCalledWith(command);
const registered = api.registerCommand.mock.calls[0]?.[0];
await expect(registered.handler({ args: "query" })).resolves.toEqual({ text: "ok" });
expect(command.handler).toHaveBeenCalledWith({ args: "query" });
});
it("builds OpenViking command definitions through a dedicated plugin module", async () => {
const addResourceOpenViking = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "resource imported" }],
details: { action: "resource_imported" },
});
const addSkillOpenViking = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "skill imported" }],
details: { action: "skill_imported" },
});
const searchOpenViking = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "search result" }],
details: { action: "searched" },
});
const handleQueryConfigCommand = vi.fn().mockResolvedValue({ text: "query config", details: { action: "query_config" } });
const queryRecallTraces = vi.fn().mockResolvedValue({ entries: [{ traceId: "trace-1" }], lookupLayer: "memory", warnings: [] });
const formatRecallTraceText = vi.fn().mockReturnValue("trace text");
const deps = {
resolvePluginSessionRouting: () => ({ agentId: "agent-main", actorPeerId: "agent-main", sessionId: "session-1", ovSessionId: "ov-session-1" }),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
parseAddResourceCommandArgs: vi.fn().mockReturnValue({ source: "https://example.com/doc", wait: true }),
parseAddSkillCommandArgs: vi.fn().mockReturnValue({ source: "skill.md" }),
parseOVSearchCommandArgs: vi.fn().mockReturnValue({ query: "docs", uri: "viking://resources", limit: 3 }),
addResourceOpenViking,
addSkillOpenViking,
searchOpenViking,
handleQueryConfigCommand,
queryRecallTraces,
formatRecallTraceText,
};
const commands = createOpenVikingCommandDefinitions(deps);
expect(commands.map((command) => command.name)).toEqual([
"add-resource",
"add-skill",
"ov-search",
"ov-query-config",
"ov-recall-trace",
]);
await expect(commands[0]!.handler({ args: "https://example.com/doc", sessionId: "session-1" })).resolves.toEqual({
text: "resource imported",
details: { action: "resource_imported" },
});
expect(addResourceOpenViking).toHaveBeenCalledWith({ source: "https://example.com/doc", wait: true }, "agent-main");
await commands[1]!.handler({ args: "skill.md" });
expect(addSkillOpenViking).toHaveBeenCalledWith({ source: "skill.md" }, "agent-main");
await commands[2]!.handler({ args: "docs --uri viking://resources --limit 3" });
expect(searchOpenViking).toHaveBeenCalledWith({ query: "docs", uri: "viking://resources", limit: 3 }, "agent-main", {
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
});
await expect(commands[3]!.handler({ args: "get" })).resolves.toEqual({ text: "query config", details: { action: "query_config" } });
expect(handleQueryConfigCommand).toHaveBeenCalledWith({ args: "get" });
await expect(commands[4]!.handler({ args: "--source ov_search --limit 5" })).resolves.toEqual({
text: "trace text",
details: { count: 1, lookupLayer: "memory", warnings: [], entries: [{ traceId: "trace-1" }] },
});
expect(queryRecallTraces).toHaveBeenCalledWith(expect.objectContaining({ source: "ov_search", limit: 5, includeContent: false }), {
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
});
expect(formatRecallTraceText).toHaveBeenCalledWith({ entries: [{ traceId: "trace-1" }], lookupLayer: "memory", warnings: [] });
});
it("keeps recall trace route paths stable across legacy and HTTP adapters", () => {
expect(RECALL_TRACE_ROUTE_PATHS).toEqual([
"/api/openviking/recall-traces",
"/api/openviking/uri-detail",
"/api/openviking/recall-traces/latest-ov-search-list",
"/api/openviking/recall-traces/:traceId",
]);
const adapter = {
registerRoute: vi.fn(),
registerHttpRoute: vi.fn(),
};
const handlers = {
handleRecallTraces: vi.fn().mockResolvedValue({ status: 200, body: { ok: true } }),
handleUriDetail: vi.fn().mockResolvedValue({ status: 200, body: { ok: true } }),
handleLatestOvSearchList: vi.fn().mockResolvedValue({ status: 200, body: { ok: true } }),
};
const registered = registerRecallTraceRoutes(adapter, handlers);
expect(registered).toBe(true);
expect(adapter.registerRoute.mock.calls.map(([route]) => route.path)).toEqual(RECALL_TRACE_ROUTE_PATHS);
expect(adapter.registerHttpRoute.mock.calls.map(([route]) => route.path)).toEqual([
"/api/openviking/recall-traces",
"/api/openviking/uri-detail",
"/api/openviking/recall-traces/latest-ov-search-list",
"/api/openviking/recall-traces",
]);
});
it("creates recall trace route handlers through a dedicated runtime module", async () => {
const entry = {
schemaVersion: "1.0" as const,
traceId: "trace-1",
ts: Date.UTC(2026, 0, 1),
sessionId: "session-1",
sessionKey: "session-key-1",
ovSessionId: "ov-session-1",
agentId: "agent-main",
source: "ov_search" as const,
operationType: "semantic_find" as const,
resourceTypes: ["resource" as const],
trigger: { query: "project spec" },
searches: [{
resourceType: "resource" as const,
targetUriResolved: "viking://resources",
limit: 5,
durationMs: 1,
total: 2,
results: [
{ uri: "viking://resources/project/spec.md", resourceType: "resource" as const, category: "doc", score: 0.91, abstractPreview: "Search abstract", resultType: "resource" as const },
{ uri: "viking://user/skills/debugger", resourceType: "agent" as const, category: "skill", score: 0.8, abstractPreview: "Skill abstract", resultType: "skill" as const },
],
}],
selected: [{ uri: "viking://resources/project/spec.md", resourceType: "resource" as const, category: "selected-doc", score: 0.95, abstractPreview: "Selected abstract" }],
stats: { candidateCount: 2, selectedCount: 1, injectedCount: 0 },
};
const traceRecorder = {
queryWithFallback: vi.fn().mockResolvedValue({ entries: [entry], lookupLayer: "memory", warnings: [] }),
};
const read = vi.fn().mockResolvedValue("0123456789abcdefghijklmnopqrstuvwxyz");
const runtime = createOpenVikingRecallTraceRuntime({
getClient: async () => ({ read }),
resolvePluginSessionRouting: () => ({ agentId: "agent-main", actorPeerId: "agent-main", sessionId: "session-1", sessionKey: "session-key-1", ovSessionId: "ov-session-1" }),
traceRecorder,
registerRecallTraceRoutes: vi.fn().mockReturnValue(true),
normalizeResourceTypes: (value) => Array.isArray(value) ? value : [String(value)],
clampScore: (value) => value,
previewText: (value, maxChars) => typeof value === "string" ? value.slice(0, maxChars) : undefined,
cfg: { traceRecallIncludeContentByDefault: true, traceRecallPreviewChars: 80, recallMaxContentChars: 100 },
});
const list = await runtime.routeHandlers.handleLatestOvSearchList({ query: { sessionkey: "session-key-1", includeSkills: "false", limit: "5" } }) as { status: number; body: any };
expect(list.status).toBe(200);
expect(list.body.items).toHaveLength(1);
expect(list.body.items[0]).toMatchObject({
uri: "viking://resources/project/spec.md",
abstractPreview: "Selected abstract",
source: "selected",
targetUri: "viking://resources",
});
const detail = await runtime.routeHandlers.handleUriDetail({ query: { uri: "viking://resources/project/spec.md", traceId: "trace-1", offset: "10", contentLimit: "5" } }) as { status: number; body: any };
expect(detail.status).toBe(200);
expect(detail.body.uriType).toBe("resource");
expect(detail.body.metadata).toMatchObject({ category: "selected-doc", sourceTraceId: "trace-1", source: "ov_search" });
expect(detail.body.content).toMatchObject({ text: "abcde", offset: 10, limit: 5, hasMore: true });
read.mockClear();
const kebabDetail = await runtime.routeHandlers.handleUriDetail({ query: { uri: "viking://resources/project/spec.md", "trace-id": "trace-1", offset: "10", "content-limit": "5", "include-content": "false" } }) as { status: number; body: any };
expect(kebabDetail.status).toBe(200);
expect(kebabDetail.body.metadata).toMatchObject({ category: "selected-doc", sourceTraceId: "trace-1", source: "ov_search" });
expect(kebabDetail.body).not.toHaveProperty("content");
expect(read).not.toHaveBeenCalled();
traceRecorder.queryWithFallback.mockClear();
read.mockClear();
const traces = await runtime.routeHandlers.handleRecallTraces({ query: { "trace-id": "trace-1", "session-key": "session-key-1", "include-content": "false", limit: "1" } }) as { status: number; body: any };
expect(traces.status).toBe(200);
expect(traceRecorder.queryWithFallback).toHaveBeenCalledWith(expect.objectContaining({
traceId: "trace-1",
sessionKey: "session-key-1",
limit: 1,
}));
expect(read).not.toHaveBeenCalled();
});
it("creates OpenViking query runtime for search/read behavior", async () => {
const find = vi.fn(async (_query: string, options: { targetUri?: string }) => {
if (options.targetUri === "viking://resources") {
return {
memories: [],
resources: [{ uri: "viking://resources/spec.md", abstract: "Spec abstract", score: 0.91, category: "doc" }],
skills: [],
total: 1,
};
}
return {
memories: [],
resources: [],
skills: [{ uri: "viking://user/skills/debugger", overview: "Debugger overview", score: 0.8, category: "skill" }],
total: 1,
};
});
const read = vi.fn().mockResolvedValue({ text: "full content" });
const recordAndFlush = vi.fn();
const runtime = createOpenVikingQueryRuntime({
getClient: async () => ({ find, read, list: vi.fn().mockResolvedValue([]) }),
queryConfigStore: { getEffective: vi.fn().mockResolvedValue({ ovSearchLimit: 2 }) },
toQueryConfigContext: (session) => session,
traceRecorder: { recordAndFlush },
inferRecallResourceType: (uri) => uri.includes("skills") ? "agent" : "resource",
createTraceId: () => "trace-query-1",
boundTraceQuery: (query) => ({ query }),
previewText: (value) => typeof value === "string" ? value : undefined,
logger: { warn: vi.fn() },
cfg: { traceRecallMaxResultsPerSearch: 5, traceRecallPreviewChars: 80, traceRecallQueryMaxChars: 120 },
});
const search = await runtime.searchOpenViking({ query: "spec" }, "agent-main", { agentId: "agent-main", sessionId: "session-1" }) as any;
expect(find.mock.calls.map(([, options]) => options.targetUri)).toEqual(["viking://resources", "viking://~/skills"]);
expect(search.content[0].text).toContain("Found 2 OpenViking results for \"spec\"");
expect(search.details).toMatchObject({ action: "searched", total: 2 });
expect(recordAndFlush).toHaveBeenCalledWith(expect.objectContaining({
traceId: "trace-query-1",
source: "ov_search",
agentId: "agent-main",
stats: { candidateCount: 2, selectedCount: 2, injectedCount: 0 },
}));
const readResult = await runtime.readOpenVikingContent({ uri: "viking://resources/spec.md" }, "agent-main") as any;
expect(read).toHaveBeenCalledWith("viking://resources/spec.md", "agent-main");
expect(readResult.content[0].text).toContain("--- START OF viking://resources/spec.md ---");
});
it("handles OpenViking query config commands through a dedicated module", async () => {
const session = { agentId: "agent-main", sessionId: "session-1", sessionKey: "key-1", ovSessionId: "ov-session-1" };
const queryCtx = { agentId: "agent-main", sessionId: "session-1", sessionKey: "key-1", ovSessionId: "ov-session-1" };
const effective = { ovSearchLimit: 7, targetUri: "viking://resources", warnings: [] };
const queryConfigStore = {
getEffective: vi.fn().mockResolvedValue(effective),
set: vi.fn().mockResolvedValue(undefined),
unset: vi.fn().mockResolvedValue(undefined),
reset: vi.fn().mockResolvedValue(undefined),
};
const normalizeRuntimeQueryParams = vi.fn().mockReturnValue({ params: { ovSearchLimit: 3 }, warnings: ["normalized"] });
const handler = createOpenVikingQueryConfigCommandHandler({
resolvePluginSessionRouting: vi.fn().mockReturnValue(session),
toQueryConfigContext: vi.fn().mockReturnValue(queryCtx),
queryConfigStore,
normalizeRuntimeQueryParams,
});
await expect(handler({ args: "get --scope claw" })).resolves.toEqual({
text: JSON.stringify({ scope: "claw", effective }, null, 2),
details: { scope: "claw", effective },
});
await expect(handler({ args: "set --ovSearchLimit 3 --scope session" })).resolves.toMatchObject({
text: "Updated OpenViking query config (session). Warnings: normalized",
details: { scope: "session", params: { ovSearchLimit: 3 }, warnings: ["normalized"], effective },
});
expect(normalizeRuntimeQueryParams).toHaveBeenCalledWith({ ovSearchLimit: 3 });
expect(queryConfigStore.set).toHaveBeenCalledWith("session", queryCtx, { ovSearchLimit: 3 });
await expect(handler({ args: "unset ovSearchLimit targetUri --scope claw" })).resolves.toMatchObject({
text: "Unset OpenViking query config fields (claw): ovSearchLimit, targetUri",
details: { scope: "claw", fields: ["ovSearchLimit", "targetUri"], effective },
});
expect(queryConfigStore.unset).toHaveBeenCalledWith("claw", queryCtx, ["ovSearchLimit", "targetUri"]);
await expect(handler({ args: "reset" })).resolves.toMatchObject({
text: "Reset OpenViking query config (session).",
details: { scope: "session", effective },
});
expect(queryConfigStore.reset).toHaveBeenCalledWith("session", queryCtx);
});
it("creates OpenViking import runtime for command import behavior", async () => {
const addResource = vi.fn().mockResolvedValue({
root_uri: "viking://resources/project-docs",
warnings: ["kept existing metadata"],
task_id: "task-resource-1",
});
const addSkill = vi.fn().mockResolvedValue({
uri: "viking://user/skills/debugger",
name: "debugger",
task_id: "task-skill-1",
});
const runtime = createOpenVikingImportRuntime({
getClient: async () => ({ addResource, addSkill }),
});
await expect(runtime.addResourceOpenViking({
source: "./docs",
to: "viking://resources/project-docs",
parent: "viking://resources",
reason: "project docs",
instruction: "extract API notes",
wait: true,
}, "agent-main")).resolves.toEqual({
content: [{ type: "text", text: "Imported OpenViking resource. viking://resources/project-docs Warnings: kept existing metadata" }],
details: {
action: "resource_imported",
root_uri: "viking://resources/project-docs",
warnings: ["kept existing metadata"],
task_id: "task-resource-1",
},
});
expect(addResource).toHaveBeenCalledWith({
pathOrUrl: "./docs",
to: "viking://resources/project-docs",
parent: "viking://resources",
reason: "project docs",
instruction: "extract API notes",
wait: true,
}, "agent-main");
await expect(runtime.addSkillOpenViking({
source: "./skills/debugger/SKILL.md",
data: "skill body",
wait: false,
}, "agent-main")).resolves.toEqual({
content: [{ type: "text", text: "Imported OpenViking skill (debugger). viking://user/skills/debugger" }],
details: {
action: "skill_imported",
uri: "viking://user/skills/debugger",
name: "debugger",
task_id: "task-skill-1",
},
});
expect(addSkill).toHaveBeenCalledWith({
path: "./skills/debugger/SKILL.md",
data: "skill body",
wait: false,
}, "agent-main");
});
it("creates the OpenViking lifecycle service without changing start/stop behavior", async () => {
const healthCheck = vi.fn().mockResolvedValue({ ok: true });
const logger = { info: vi.fn(), warn: vi.fn() };
const registerRecallTraceRoutes = vi.fn().mockReturnValue(true);
const service = createOpenVikingService({
cfg: { baseUrl: "http://127.0.0.1:1933", targetUri: "viking://resources" },
getClient: async () => ({ healthCheck }),
logger,
recallTraceHttpRoutesRegistered: false,
registerRecallTraceRoutes,
});
expect(service.id).toBe("openviking");
await service.start({ registerRoute: vi.fn() });
service.stop();
expect(registerRecallTraceRoutes).toHaveBeenCalled();
expect(healthCheck).toHaveBeenCalled();
expect(logger.info).toHaveBeenCalledWith(expect.stringContaining("openviking: initialized"));
expect(logger.info).toHaveBeenCalledWith("openviking: registered recall trace Gateway routes");
expect(logger.info).toHaveBeenCalledWith("openviking: stopped");
});
it("registers lifecycle hooks through a dedicated plugin module", async () => {
const handlers = new Map<string, Function>();
const api = {
on: vi.fn((hookName: string, handler: Function) => {
handlers.set(hookName, handler);
}),
};
const rememberSessionAgentId = vi.fn();
const verboseRoutingInfo = vi.fn();
const commitOVSession = vi.fn().mockResolvedValue(true);
const logger = { info: vi.fn(), warn: vi.fn() };
registerOpenVikingLifecycleHooks({
api,
rememberSessionAgentId,
isBypassedSession: (ctx) => ctx?.sessionKey === "bypass",
verboseRoutingInfo,
getContextEngine: () => ({ commitOVSession }),
logger,
});
expect(api.on.mock.calls.map(([hookName]) => hookName)).toEqual([
"session_start",
"session_end",
"before_reset",
"after_compaction",
]);
await handlers.get("session_start")?.({}, { sessionId: "session-1", agentId: "agent-main" });
await handlers.get("session_end")?.({}, { sessionId: "session-2", agentId: "agent-main" });
expect(rememberSessionAgentId).toHaveBeenCalledWith({ sessionId: "session-1", agentId: "agent-main" });
expect(rememberSessionAgentId).toHaveBeenCalledWith({ sessionId: "session-2", agentId: "agent-main" });
await handlers.get("before_reset")?.({}, { sessionId: "session-3", sessionKey: "key-3" });
expect(commitOVSession).toHaveBeenCalledWith({ sessionId: "session-3", sessionKey: "key-3" });
expect(logger.info).toHaveBeenCalledWith("openviking: committed OV session on reset for session=session-3");
await handlers.get("before_reset")?.({}, { sessionId: "session-4", sessionKey: "bypass" });
expect(verboseRoutingInfo).toHaveBeenCalledWith(expect.stringContaining("bypassing before_reset"));
expect(commitOVSession).toHaveBeenCalledTimes(1);
});
it("registers the context engine through a dedicated plugin module", () => {
const engine = { id: "openviking", commitOVSession: vi.fn() };
const api = { runtime: { version: "2026.9.3" }, registerContextEngine: vi.fn() };
const logger = { info: vi.fn(), warn: vi.fn() };
const getClient = vi.fn();
const resolveAgentId = vi.fn();
const rememberSessionAgentId = vi.fn();
const queryConfigStore = { get: vi.fn() };
const traceRecorder = { record: vi.fn() };
const createContextEngine = vi.fn().mockReturnValue(engine);
const setContextEngineRef = vi.fn();
registerOpenVikingContextEngine({
api,
plugin: { id: "openviking", name: "OpenViking" },
version: "0.1.0",
cfg: { baseUrl: "http://127.0.0.1:1933" },
logger,
getClient,
resolveAgentId,
rememberSessionAgentId,
queryConfigStore,
traceRecorder,
createContextEngine,
setContextEngineRef,
});
expect(api.registerContextEngine).toHaveBeenCalledWith("openviking", expect.any(Function));
expect(createContextEngine).not.toHaveBeenCalled();
const registeredFactory = api.registerContextEngine.mock.calls[0]?.[1];
expect(registeredFactory()).toBe(engine);
expect(createContextEngine).toHaveBeenCalledWith({
id: "openviking",
name: "OpenViking",
version: "0.1.0",
hostVersion: "2026.9.3",
cfg: { baseUrl: "http://127.0.0.1:1933" },
logger,
getClient,
resolveAgentId,
rememberSessionAgentId,
queryConfigStore,
traceRecorder,
});
expect(setContextEngineRef).toHaveBeenCalledWith(engine);
expect(logger.info).toHaveBeenCalledWith(expect.stringContaining("registered context-engine"));
});
it("warns when the context-engine registration API is unavailable", () => {
const logger = { info: vi.fn(), warn: vi.fn() };
registerOpenVikingContextEngine({
api: {},
plugin: { id: "openviking", name: "OpenViking" },
version: "0.1.0",
cfg: {},
logger,
getClient: vi.fn(),
resolveAgentId: vi.fn(),
rememberSessionAgentId: vi.fn(),
queryConfigStore: {},
traceRecorder: {},
createContextEngine: vi.fn(),
setContextEngineRef: vi.fn(),
});
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("registerContextEngine is unavailable"));
expect(logger.info).not.toHaveBeenCalled();
});
it("registers externalized tool-result tools through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const readToolResult = vi.fn().mockResolvedValue({
content: "full tool result",
offset: 0,
limit: 20_000,
total_chars: 16,
has_more: false,
tool_result_id: "tr_1",
metadata: { tool_name: "ov_search" },
});
const deps = {
registerTool,
getClient: async () => ({ readToolResult }),
resolvePluginSessionRouting: () => ({ agentId: "agent-main", ovSessionId: "ov-session-1" }),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
logger: { warn: vi.fn() },
};
registerOpenVikingToolResultTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual([
"openviking_tool_result_read",
"openviking_tool_result_search",
"openviking_tool_result_list",
]);
const readFactory = registerTool.mock.calls[0]?.[0];
const readTool = readFactory({ sessionId: "session-1" });
const result = await readTool.execute("call-1", {
tool_output_ref: "viking://user/default/sessions/ov-session-1/tool-results/tr_1",
});
expect(readToolResult).toHaveBeenCalledWith(
"ov-session-1",
"tr_1",
{ offset: 0, limit: 20_000, includeMetadata: true },
);
expect(result.content[0].text).toBe("full tool result");
expect(result.details).toMatchObject({ action: "read", tool_result_id: "tr_1" });
});
it("registers archive search and expansion through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const recordAndFlush = vi.fn().mockResolvedValue(undefined);
const grepSessionArchives = vi.fn().mockResolvedValue({
count: 1,
matches: [{
uri: "viking://user/default/sessions/ov-session-1/history/archive_001#L12",
line: 12,
content: "important command output",
}],
});
const getSessionArchive = vi.fn().mockResolvedValue({
archive_id: "archive_001",
abstract: "Compressed summary",
messages: [{ id: "m1", role: "user", parts: [{ type: "text", text: "hello" }], created_at: "2026-06-10T00:00:00Z" }],
});
const deps = {
registerTool,
getClient: async () => ({ grepSessionArchives, getSessionArchive }),
rememberSessionAgentId: vi.fn(),
toOvSessionId: () => "ov-session-1",
resolveAgentId: () => "agent-main",
resolvePluginSessionRouting: () => ({
agentId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
}),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
formatMessage: (message: { role: string; parts: Array<{ text?: string }> }) => `${message.role}: ${message.parts[0]?.text ?? ""}`,
traceRecorder: { recordAndFlush },
traceRecallMaxResultsPerSearch: 10,
traceRecallPreviewChars: 20,
createTraceId: () => "trace-archive-search",
logger: { info: vi.fn(), warn: vi.fn() },
};
registerOpenVikingArchiveTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual([
"ov_archive_search",
"ov_archive_expand",
]);
const searchFactory = registerTool.mock.calls[0]?.[0];
const searchTool = searchFactory({ sessionId: "session-1", sessionKey: "session-key" });
const searchResult = await searchTool.execute("call-1", { query: "command" });
expect(grepSessionArchives).toHaveBeenCalledWith("ov-session-1", "command", {
archiveId: undefined,
caseInsensitive: true,
});
expect(searchResult.content[0].text).toContain("Found 1 match(es)");
expect(searchResult.content[0].text).toContain("important command output");
expect(searchResult.details).toMatchObject({ query: "command", matchCount: 1 });
expect(recordAndFlush).toHaveBeenCalledWith(expect.objectContaining({
traceId: "trace-archive-search",
source: "ov_archive_search",
operationType: "archive_grep",
}));
const expandFactory = registerTool.mock.calls[1]?.[0];
const expandTool = expandFactory({ sessionId: "session-1" });
const result = await expandTool.execute("call-2", { archiveId: "archive_001" });
expect(getSessionArchive).toHaveBeenCalledWith("ov-session-1", "archive_001");
expect(result.content[0].text).toContain("## archive_001");
expect(result.content[0].text).toContain("user: hello");
expect(result.details).toMatchObject({
action: "expanded",
archiveId: "archive_001",
messageCount: 1,
sessionId: "session-1",
ovSessionId: "ov-session-1",
});
});
it("registers import tools through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const addResource = vi.fn().mockResolvedValue({ root_uri: "viking://resources/docs", warnings: ["warn"] });
const addSkill = vi.fn().mockResolvedValue({ uri: "viking://user/skills/demo", name: "demo" });
const deps = {
registerTool,
getClient: async () => ({ addResource, addSkill }),
resolvePluginSessionRouting: () => ({ agentId: "agent-main", actorPeerId: "agent-main" }),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
enableAddResourceTool: true,
};
registerOpenVikingImportTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["add_resource", "add_skill"]);
const addResourceFactory = registerTool.mock.calls[0]?.[0];
const addResourceTool = addResourceFactory({ sessionId: "session-1" });
const resourceResult = await addResourceTool.execute("call-1", {
source: "https://example.com/docs",
to: "viking://resources/docs",
wait: true,
});
expect(addResource).toHaveBeenCalledWith({
pathOrUrl: "https://example.com/docs",
to: "viking://resources/docs",
parent: undefined,
reason: undefined,
instruction: undefined,
wait: true,
}, "agent-main");
expect(resourceResult.content[0].text).toBe("Imported OpenViking resource. viking://resources/docs Warnings: warn");
expect(resourceResult.details).toMatchObject({ action: "resource_imported", root_uri: "viking://resources/docs" });
const addSkillFactory = registerTool.mock.calls[1]?.[0];
const addSkillTool = addSkillFactory({ sessionId: "session-1" });
const skillResult = await addSkillTool.execute("call-2", { data: "name: demo\n" });
expect(addSkill).toHaveBeenCalledWith({
path: undefined,
data: "name: demo\n",
wait: undefined,
}, "agent-main");
expect(skillResult.content[0].text).toBe("Imported OpenViking skill (demo). viking://user/skills/demo");
expect(skillResult.details).toMatchObject({ action: "skill_imported", uri: "viking://user/skills/demo" });
});
it("keeps add_resource import tool behind explicit opt-in", () => {
const registerTool = vi.fn();
registerOpenVikingImportTools({
registerTool,
getClient: async () => ({ addResource: vi.fn(), addSkill: vi.fn() }),
resolvePluginSessionRouting: () => ({ agentId: "agent-main", actorPeerId: "agent-main" }),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
enableAddResourceTool: false,
});
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["add_skill"]);
});
it("registers query tools through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const searchOpenViking = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "search result" }],
details: { action: "searched", total: 1 },
});
const readOpenVikingContent = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "read result" }],
details: { action: "read", uri: "viking://resources/doc" },
});
const multiReadOpenVikingContent = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "multi read result" }],
details: { action: "multi_read", count: 2 },
});
const listOpenVikingDirectory = vi.fn().mockResolvedValue({
content: [{ type: "text" as const, text: "list result" }],
details: { action: "listed", count: 2 },
});
const deps = {
registerTool,
searchOpenViking,
readOpenVikingContent,
multiReadOpenVikingContent,
listOpenVikingDirectory,
resolvePluginSessionRouting: () => ({
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
}),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
};
registerOpenVikingQueryTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["ov_search", "ov_read", "ov_multi_read", "ov_list"]);
const searchFactory = registerTool.mock.calls[0]?.[0];
const searchTool = searchFactory({ sessionId: "session-1" });
const searched = await searchTool.execute("call-1", { query: "docs", uri: "viking://resources", limit: 3 });
expect(searchOpenViking).toHaveBeenCalledWith({
query: "docs",
uri: "viking://resources",
limit: 3,
}, "agent-main", {
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
});
expect(searched.details).toMatchObject({ action: "searched", total: 1 });
const readFactory = registerTool.mock.calls[1]?.[0];
const readTool = readFactory({ sessionId: "session-1" });
const read = await readTool.execute("call-2", { uri: "viking://resources/doc" });
expect(readOpenVikingContent).toHaveBeenCalledWith({ uri: "viking://resources/doc" }, "agent-main");
expect(read.content[0].text).toBe("read result");
const multiReadFactory = registerTool.mock.calls[2]?.[0];
const multiReadTool = multiReadFactory({ sessionId: "session-1" });
const multiRead = await multiReadTool.execute("call-3", { uris: ["viking://resources/a.md", "viking://resources/b.md"] });
expect(multiReadOpenVikingContent).toHaveBeenCalledWith({
uris: ["viking://resources/a.md", "viking://resources/b.md"],
}, "agent-main");
expect(multiRead.content[0].text).toBe("multi read result");
const listFactory = registerTool.mock.calls[3]?.[0];
const listTool = listFactory({ sessionId: "session-1" });
const list = await listTool.execute("call-4", {
uri: "viking://resources/doc",
recursive: true,
simple: true,
limit: 5,
});
expect(listOpenVikingDirectory).toHaveBeenCalledWith({
uri: "viking://resources/doc",
recursive: true,
simple: true,
limit: 5,
}, "agent-main");
expect(list.content[0].text).toBe("list result");
});
it("registers memory store and forget through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const addSessionMessage = vi.fn().mockResolvedValue(undefined);
const commitSession = vi.fn().mockResolvedValue({
session_id: "memory-store-temp",
status: "completed",
archived: false,
memories_extracted: { core: 2 },
});
const deleteUri = vi.fn().mockResolvedValue(undefined);
const find = vi.fn().mockResolvedValue({ memories: [], total: 0 });
const deps = {
registerTool,
getClient: async () => ({ addSessionMessage, commitSession, deleteUri, find }),
normalizeSessionId: (sessionId: string) => `normalized:${sessionId}`,
createTempSessionId: () => "memory-store-temp",
peerRole: "sender" as const,
resolvePluginSessionRouting: () => ({ agentId: "agent-main", actorPeerId: "ou_01_abc" }),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
defaultTargetUri: "viking://user/default",
defaultRecallScoreThreshold: 0.25,
logFindRequests: true,
logger: { info: vi.fn(), warn: vi.fn() },
};
registerOpenVikingMemoryTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["memory_store", "memory_forget"]);
const storeFactory = registerTool.mock.calls[0]?.[0];
const storeTool = storeFactory({ sessionId: "session-1", requesterSenderId: "ou_01@abc" });
const stored = await storeTool.execute("call-1", { text: "remember this" });
expect(addSessionMessage).toHaveBeenCalledWith(
"memory-store-temp",
"user",
[{ type: "text", text: "remember this" }],
undefined,
undefined,
"ou_01_abc",
);
expect(commitSession).toHaveBeenCalledWith("memory-store-temp", {
wait: true,
keepRecentCount: 0,
});
expect(stored.details).toMatchObject({ action: "stored", memoriesCount: 2, usedTempSession: true });
const forgetFactory = registerTool.mock.calls[1]?.[0];
const forgetTool = forgetFactory({ sessionId: "session-1" });
const rejected = await forgetTool.execute("call-2", { uri: "viking://resources/r1" });
expect(rejected.details).toMatchObject({ action: "rejected", uri: "viking://resources/r1" });
expect(deleteUri).not.toHaveBeenCalled();
const memoryUri = "viking://user/default/memories/m1";
const deleted = await forgetTool.execute("call-3", { uri: memoryUri });
expect(deleteUri).toHaveBeenCalledWith(memoryUri, "ou_01_abc");
expect(deleted.content[0].text).toBe(`Forgotten: ${memoryUri}`);
expect(deleted.details).toMatchObject({ action: "deleted", uri: memoryUri });
});
it("registers recall trace tool through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const traceResult = {
entries: [{ traceId: "trace-1", source: "ov_search" }],
lookupLayer: "memory",
warnings: ["warn"],
};
const queryRecallTraces = vi.fn().mockResolvedValue(traceResult);
const formatRecallTraceText = vi.fn().mockReturnValue("formatted trace");
const deps = {
registerTool,
queryRecallTraces,
formatRecallTraceText,
resolvePluginSessionRouting: () => ({
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
}),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
};
registerOpenVikingRecallTraceTools(deps);
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["ov_recall_trace"]);
const traceFactory = registerTool.mock.calls[0]?.[0];
const traceTool = traceFactory({ sessionId: "session-1" });
const result = await traceTool.execute("call-1", { source: "ov_search", limit: 5 });
expect(queryRecallTraces).toHaveBeenCalledWith({ source: "ov_search", limit: 5 }, {
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
ovSessionId: "ov-session-1",
});
expect(formatRecallTraceText).toHaveBeenCalledWith(traceResult);
expect(result.content[0].text).toBe("formatted trace");
expect(result.details).toMatchObject({
action: "queried",
count: 1,
lookupLayer: "memory",
warnings: ["warn"],
entries: traceResult.entries,
});
});
it("registers memory recall tool through a dedicated plugin module", async () => {
const registerTool = vi.fn();
const memory = {
uri: "viking://user/default/memories/m1",
category: "preferences",
abstract: "User prefers TDD.",
score: 0.93,
level: 2,
};
const find = vi.fn().mockResolvedValue({ memories: [memory], total: 1 });
const read = vi.fn().mockResolvedValue("User prefers TDD.");
const getDefaultAgentId = vi.fn().mockReturnValue("default-agent");
const recordAndFlush = vi.fn().mockResolvedValue(undefined);
const getEffective = vi.fn().mockResolvedValue({
recallLimit: 1,
scoreThreshold: 0.5,
targetUri: "viking://user/default",
resourceTypes: ["user"],
candidateLimit: 4,
maxInjectedChars: 500,
rankingWeights: {},
categoryWeights: {},
resourceTypeWeights: {},
});
registerOpenVikingMemoryRecallTools({
registerTool,
getClient: async () => ({ find, read, getDefaultAgentId }),
queryConfigStore: { getEffective },
toQueryConfigContext: (session) => ({ agentId: session.agentId, sessionId: session.sessionId, sessionKey: session.sessionKey, ovSessionId: session.ovSessionId }),
resolvePluginSessionRouting: () => ({
agentId: "agent-main",
actorPeerId: "agent-main",
sessionId: "session-1",
sessionKey: "agent:agent-main:session-1",
ovSessionId: "ov-session-1",
}),
isBypassedSession: () => false,
makeBypassedToolResult: (toolName: string) => ({ content: [{ type: "text" as const, text: `bypassed ${toolName}` }], details: { toolName } }),
resolveRecallSearchPlan: vi.fn(),
postProcessMemories: (items) => items,
pickMemoriesForInjection: (items) => items.slice(0, 1),
buildMemoryLinesWithBudget: vi.fn(async (items, readFn) => {
await readFn(items[0].uri);
return { lines: ["1. [preferences] User prefers TDD. (93%)"], estimatedTokens: 8 };
}),
inferRecallResourceType: (uri) => uri.startsWith("viking://user/") ? "user" : "resource",
createTraceId: () => "memory_recall-trace-1",
boundTraceQuery: (query) => ({ query }),
previewText: (value) => typeof value === "string" ? value : undefined,
traceRecorder: { recordAndFlush },
cfg: {
recallTargetTypes: ["user"],
traceRecallMaxResultsPerSearch: 5,
traceRecallPreviewChars: 120,
traceRecallQueryMaxChars: 200,
logFindRequests: true,
},
logger: { info: vi.fn() },
});
expect(registerTool.mock.calls.map(([, opts]) => opts.name)).toEqual(["memory_recall"]);
const recallFactory = registerTool.mock.calls[0]?.[0];
const recallTool = recallFactory({ sessionId: "session-1" });
const result = await recallTool.execute("call-1", { query: "TDD preference", limit: 2, scoreThreshold: 0.5 });
expect(getEffective).toHaveBeenCalledWith({
agentId: "agent-main",
sessionId: "session-1",
sessionKey: "agent:agent-main:session-1",
ovSessionId: "ov-session-1",
}, {
recallLimit: 2,
scoreThreshold: 0.5,
targetUri: undefined,
resourceTypes: undefined,
});
expect(find).toHaveBeenCalledWith("TDD preference", {
targetUri: "viking://user/default",
limit: 4,
scoreThreshold: 0,
actorPeerId: "agent-main",
});
expect(read).toHaveBeenCalledWith("viking://user/default/memories/m1", "agent-main");
expect(recordAndFlush).toHaveBeenCalledWith(expect.objectContaining({
traceId: "memory_recall-trace-1",
sessionId: "session-1",
sessionKey: "agent:agent-main:session-1",
ovSessionId: "ov-session-1",
agentId: "agent-main",
source: "memory_recall",
resourceTypes: ["user"],
stats: { candidateCount: 1, selectedCount: 1, injectedCount: 1 },
}));
expect(result.content[0].text).toContain("Found 1 memories");
expect(result.details).toMatchObject({
count: 1,
total: 1,
scoreThreshold: 0.5,
requestLimit: 4,
recallMaxInjectedChars: 500,
});
});
});