Skip to content

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

add OpenViking read tools to OpenClaw plugin (#2551)

marchpure2dbee8e33dc2
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index b20fb10dd..3e3b66a0c 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -42,6 +42,9 @@ Once installed, the plugin provides these agent tools:
| `add_resource` | Import documents, URLs, or Git repos |
| `add_skill` | Import agent skills |
| `ov_search` | Search imported resources and skills |
+| `ov_read` | Read the full original content of one exact OpenViking URI |
+| `ov_multi_read` | Read the full original content of multiple OpenViking URIs |
+| `ov_list` | List OpenViking directories after search to inspect sibling chunks and overview files |
| `openviking_tool_result_read` | Restore the full original content of an externalized tool result |
| `openviking_tool_result_search` | Search inside an externalized tool result by keyword |
| `openviking_tool_result_list` | List externalized tool results in the current session |
@@ -224,7 +227,7 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered async
## Tools and Expandability
-Beyond automatic behavior, the plugin exposes seven tools directly:
+Beyond automatic behavior, the plugin exposes these tools directly:
- `memory_recall`: explicit long-term memory search
- `memory_store`: write explicit long-term facts into an OpenViking session and trigger commit
@@ -233,6 +236,9 @@ Beyond automatic behavior, the plugin exposes seven tools directly:
- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource
- `add_skill`: import or register an OpenViking agent skill
- `ov_search`: search OpenViking resources and skills, especially after importing them
+- `ov_read`: read one exact `viking://` URI returned by `ov_search` or `ov_list`
+- `ov_multi_read`: read multiple exact `viking://` URIs, useful for an overview plus sibling chunks
+- `ov_list`: list a hit's parent directory after `ov_search` to recover sibling chunks, `.overview.md`, and related split-document context
They serve different roles:
@@ -243,6 +249,9 @@ They serve different roles:
- `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands
- `add_skill` imports skills into OpenViking, while `add_resource` imports resources
- `ov_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
+- `ov_read` turns a ranked hit into original evidence before answering precise documentation, codebase, configuration, or procedural questions
+- `ov_multi_read` reads overview and sibling chunks together when a split document needs more context than a single hit
+- `ov_list` complements `ov_search` when a ranked hit is only one chunk of a larger procedure or document
`ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md
index c51f091a2..2503d0007 100644
--- a/examples/openclaw-plugin/README_CN.md
+++ b/examples/openclaw-plugin/README_CN.md
@@ -42,6 +42,9 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A
| `add_resource` | 导入文档、URL 或 Git 仓库 |
| `add_skill` | 导入 agent 技能 |
| `ov_search` | 检索已导入的 resources 和 skills |
+| `ov_read` | 读取一个精确 OpenViking URI 的完整原文 |
+| `ov_multi_read` | 读取多个 OpenViking URI 的完整原文 |
+| `ov_list` | 在检索后列出 OpenViking 目录,补查同级切片和 overview 文件 |
| `openviking_tool_result_read` | 还原被 OpenViking 外置的工具结果的完整原始内容 |
| `openviking_tool_result_search` | 按关键词在外置的工具结果中检索 |
| `openviking_tool_result_list` | 列出当前会话中外置的工具结果 |
@@ -224,7 +227,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
## 工具层与可展开能力
-这套插件除了自动行为,还直接暴露了 7 个工具:
+这套插件除了自动行为,还直接暴露了以下工具:
- `memory_recall`:显式检索长期记忆
- `memory_store`:把明确的长期事实写入 OpenViking session 并立即触发 commit
@@ -233,6 +236,9 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
- `add_resource`:把文档、目录、URL 或 Git 仓库导入为 OpenViking resource
- `add_skill`:导入或注册 OpenViking agent skill
- `ov_search`:检索 OpenViking resources 和 skills,尤其用于导入后的确认和消费
+- `ov_read`:读取 `ov_search` 或 `ov_list` 返回的一个精确 `viking://` URI
+- `ov_multi_read`:读取多个精确 `viking://` URI,适合同时读取 overview 和同级切片
+- `ov_list`:在 `ov_search` 命中后列出父目录,用来补齐同级切片、`.overview.md` 和同源文档上下文
它们各自的作用不同:
@@ -243,6 +249,9 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
- `add_resource` 让 agent 在用户明确提出文档或仓库导入需求时直接完成操作,不要求用户记住 slash command。
- `add_skill` 把 skill 导入 OpenViking,`add_resource` 把文档、目录、URL 或 Git 仓库导入为 resource。
- `ov_search` 补齐导入后的使用闭环,让用户或 agent 可以确认并消费 resources 和 skills。
+- `ov_read` 把检索命中的 ranked hit 转成原文证据,适合精确文档、代码库、配置和操作步骤问答。
+- `ov_multi_read` 能一次读取 overview 和多个同级切片,适合拆分文档需要补上下文的场景。
+- `ov_list` 补齐 `ov_search` 的结构浏览能力,避免只拿到某个切片时遗漏同一目录下的连续步骤。
其中 `ov_archive_expand` 是 `assemble()` 的重要补充,因为 `assemble()` 默认给的是压缩后的索引和摘要,而不是完整历史正文。
diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.ts
index cc7c7237e..93c6f47b4 100644
--- a/examples/openclaw-plugin/client.ts
+++ b/examples/openclaw-plugin/client.ts
@@ -24,6 +24,10 @@ export type FindResult = {
total?: number;
};
+export type FsListEntry = string | Record<string, unknown>;
+
+export type FsListResult = FsListEntry[];
+
export type CaptureMode = "semantic" | "keyword";
export type RuntimeIdentity = {
userId: string;
@@ -508,6 +512,31 @@ export class OpenVikingClient {
);
}
+ async list(
+ uri: string,
+ options?: {
+ recursive?: boolean;
+ simple?: boolean;
+ output?: "agent" | "original";
+ absLimit?: number;
+ showAllHidden?: boolean;
+ nodeLimit?: number;
+ },
+ agentId?: string,
+ ): Promise<FsListResult> {
+ const normalizedUri = await this.normalizeTargetUri(uri, agentId);
+ const params = new URLSearchParams({
+ uri: normalizedUri,
+ recursive: String(options?.recursive ?? false),
+ simple: String(options?.simple ?? false),
+ output: options?.output ?? "agent",
+ abs_limit: String(options?.absLimit ?? 256),
+ show_all_hidden: String(options?.showAllHidden ?? false),
+ node_limit: String(options?.nodeLimit ?? 1000),
+ });
+ return this.request<FsListResult>(`/api/v1/fs/ls?${params.toString()}`, {}, agentId);
+ }
+
async readToolResult(
sessionId: string,
toolResultId: string,
diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.ts
index c65799eeb..2d721c961 100644
--- a/examples/openclaw-plugin/index.ts
+++ b/examples/openclaw-plugin/index.ts
@@ -162,6 +162,21 @@ type OVSearchInput = {
limit?: number;
};
+type OVListInput = {
+ uri: string;
+ recursive?: boolean;
+ simple?: boolean;
+ limit?: number;
+};
+
+type OVReadInput = {
+ uri: string;
+};
+
+type OVMultiReadInput = {
+ uris: string[];
+};
+
type ToolResultRef = {
sessionId: string;
toolResultId: string;
@@ -791,12 +806,6 @@ const contextEnginePlugin = {
}
return `${collapsed.slice(0, maxChars - 3)}...`;
};
- const truncateUri = (value: string, maxChars = 84): string => {
- if (value.length <= maxChars) {
- return value;
- }
- return `${value.slice(0, maxChars - 3)}...`;
- };
const items = [
...(result.memories ?? []).map((item) => ({ contextType: "memory", item })),
...(result.resources ?? []).map((item) => ({ contextType: "resource", item })),
@@ -808,7 +817,7 @@ const contextEnginePlugin = {
const numberHeader = "no";
const numberWidth = Math.max(numberHeader.length, String(items.length).length);
const typeWidth = Math.max("type".length, ...items.map(({ contextType }) => contextType.length));
- const uriWidth = Math.max("uri".length, ...items.map(({ item }) => truncateUri(item.uri).length));
+ const uriWidth = Math.max("uri".length, ...items.map(({ item }) => item.uri.length));
const levelWidth = Math.max("level".length, ...items.map(({ item }) => String(item.level ?? "").length));
const scoreWidth = Math.max(
"score".length,
@@ -819,7 +828,7 @@ const contextEnginePlugin = {
...items.map(({ contextType, item }, index) => {
const score = typeof item.score === "number" ? item.score.toFixed(2) : "";
const summary = truncateSummary(item.abstract || item.overview || "(no summary)");
- return `${String(index + 1).padEnd(numberWidth)} ${contextType.padEnd(typeWidth)} ${truncateUri(item.uri).padEnd(uriWidth)} ${String(item.level ?? "").padEnd(levelWidth)} ${score.padEnd(scoreWidth)} ${summary}`;
+ return `${String(index + 1).padEnd(numberWidth)} ${contextType.padEnd(typeWidth)} ${item.uri.padEnd(uriWidth)} ${String(item.level ?? "").padEnd(levelWidth)} ${score.padEnd(scoreWidth)} ${summary}`;
}),
];
};
@@ -832,12 +841,64 @@ const contextEnginePlugin = {
const scope = uri ? ` under ${uri}` : "";
const lines = [
`Found ${result.total ?? 0} OpenViking results for "${query}"${scope}`,
+ "Tip: search results are ranked snippets. Use ov_read on exact hit URIs before answering precise questions. Use ov_list on a hit's parent URI to inspect sibling chunks or overview files before answering procedural or multi-step questions.",
"",
...formatOVSearchRows(result),
].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));
return lines.join("\n");
};
+ const formatOVListEntry = (entry: unknown): string => {
+ if (typeof entry === "string") {
+ return entry;
+ }
+ if (!entry || typeof entry !== "object") {
+ return String(entry);
+ }
+ const item = entry as Record<string, unknown>;
+ const uri = typeof item.uri === "string" ? item.uri : "";
+ const name = typeof item.name === "string" ? item.name : "";
+ const isDir = item.isDir === true || item.type === "directory";
+ const marker = isDir ? "[dir]" : "[file]";
+ const summary =
+ typeof item.abstract === "string" && item.abstract.trim()
+ ? item.abstract.trim().replace(/\s+/g, " ")
+ : typeof item.overview === "string" && item.overview.trim()
+ ? item.overview.trim().replace(/\s+/g, " ")
+ : "";
+ const label = uri || name || JSON.stringify(item);
+ return summary ? `${marker} ${label} - ${summary}` : `${marker} ${label}`;
+ };
+
+ const formatOVListText = (uri: string, entries: unknown[]): string => {
+ if (entries.length === 0) {
+ return `No OpenViking entries found under ${uri}.`;
+ }
+ return [
+ `Listed ${entries.length} OpenViking entr${entries.length === 1 ? "y" : "ies"} under ${uri}`,
+ "",
+ ...entries.map((entry) => formatOVListEntry(entry)),
+ ].join("\n");
+ };
+
+ const formatOVReadText = (uri: string, content: string): string => {
+ const body = content || "(empty OpenViking content)";
+ return [`--- START OF ${uri} ---`, body, `--- END OF ${uri} ---`].join("\n");
+ };
+
+ const formatOVMultiReadText = (
+ results: Array<{ uri: string; content: string; success: boolean }>,
+ ): string => [
+ `Multi-read results for ${results.length} OpenViking resource${results.length === 1 ? "" : "s"}:`,
+ "",
+ ...results.flatMap((result) => [
+ `--- START OF ${result.uri} ---`,
+ result.success ? (result.content || "(empty OpenViking content)") : `ERROR: ${result.content}`,
+ `--- END OF ${result.uri} ---`,
+ "",
+ ]),
+ ].join("\n").trimEnd();
+
const searchOpenViking = async (
input: OVSearchInput,
agentId?: string,
@@ -896,17 +957,105 @@ const contextEnginePlugin = {
};
};
+ const readOpenViking = async (input: OVReadInput, agentId?: string) => {
+ const uri = input.uri.trim();
+ if (!uri) {
+ throw new Error("uri is required");
+ }
+ const client = await getClient();
+ const content = await client.read(uri, agentId);
+ return {
+ content: [{ type: "text" as const, text: formatOVReadText(uri, content) }],
+ details: {
+ action: "read",
+ uri,
+ chars: content.length,
+ },
+ };
+ };
+
+ const multiReadOpenViking = async (input: OVMultiReadInput, agentId?: string) => {
+ const uris = input.uris
+ .map((uri) => (typeof uri === "string" ? uri.trim() : ""))
+ .filter((uri) => uri.length > 0);
+ if (uris.length === 0) {
+ throw new Error("uris is required");
+ }
+ const client = await getClient();
+ const results = await Promise.all(
+ uris.map(async (uri) => {
+ try {
+ const content = await client.read(uri, agentId);
+ return {
+ uri,
+ content,
+ success: true,
+ chars: content.length,
+ };
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ return {
+ uri,
+ content: message,
+ success: false,
+ chars: 0,
+ };
+ }
+ }),
+ );
+ return {
+ content: [{ type: "text" as const, text: formatOVMultiReadText(results) }],
+ details: {
+ action: "multi_read",
+ count: results.length,
+ success_count: results.filter((result) => result.success).length,
+ results,
+ },
+ };
+ };
+
+ const listOpenViking = async (input: OVListInput, agentId?: string) => {
+ const uri = input.uri.trim();
+ if (!uri) {
+ throw new Error("uri is required");
+ }
+ const limit = Math.max(1, Math.floor(input.limit ?? 100));
+ const client = await getClient();
+ const entries = await client.list(
+ uri,
+ {
+ recursive: input.recursive ?? false,
+ simple: input.simple ?? false,
+ nodeLimit: limit,
+ },
+ agentId,
+ );
+ return {
+ content: [{ type: "text" as const, text: formatOVListText(uri, entries) }],
+ details: {
+ action: "listed",
+ uri,
+ recursive: input.recursive ?? false,
+ simple: input.simple ?? false,
+ count: entries.length,
+ entries,
+ },
+ };
+ };
+
api.registerTool(
(ctx: ToolContext) => ({
name: "add_resource",
label: "Add Resource (OpenViking)",
description:
"Use only when the user explicitly asks to import, add, upload, save, or index a document, directory, URL, Git repository, or OpenClaw media attachment into OpenViking resources. " +
- "For a '[media attached: /path ...]' document, set source to that exact local media path. Do not invent OpenViking upload REST endpoints.",
+ "For a '[media attached: /path ...]' document, set source to that exact local media path. " +
+ "Set either to for an exact target URI or parent for a parent directory, never both. " +
+ "Do not invent OpenViking upload REST endpoints.",
parameters: Type.Object({
source: Type.String({ description: "Local path, OpenClaw media attachment path, directory path, public URL, or Git URL" }),
- to: Type.Optional(Type.String({ description: "Exact target URI, e.g. viking://resources/project-docs" })),
- parent: Type.Optional(Type.String({ description: "Parent URI under viking://resources" })),
+ to: Type.Optional(Type.String({ description: "Exact target URI, e.g. viking://resources/project-docs. Mutually exclusive with parent." })),
+ parent: Type.Optional(Type.String({ description: "Parent URI under viking://resources. Mutually exclusive with to." })),
reason: Type.Optional(Type.String({ description: "Reason or note for adding this resource" })),
instruction: Type.Optional(Type.String({ description: "Processing instruction for semantic extraction" })),
wait: Type.Optional(Type.Boolean({ description: "Wait for processing to complete" })),
@@ -965,7 +1114,9 @@ const contextEnginePlugin = {
name: "ov_search",
label: "Search (OpenViking)",
description:
- "Search OpenViking resources and skills. Use after importing, or when the user asks to search OpenViking resources or skills.",
+ "Search OpenViking resources and skills. Use after importing, or when the user asks to search OpenViking resources or skills. " +
+ "Search only returns ranked snippets; call ov_read on exact hit URIs before answering precise questions. " +
+ "When a result is part of a split document or a multi-step procedure, call ov_list on the parent URI to inspect sibling chunks and overview files before answering.",
parameters: Type.Object({
query: Type.String({ description: "Search query" }),
uri: Type.Optional(Type.String({ description: "Optional search URI. Defaults to resources plus user skills." })),
@@ -987,6 +1138,84 @@ const contextEnginePlugin = {
{ name: "ov_search" },
);
+ api.registerTool(
+ (ctx: ToolContext) => ({
+ name: "ov_read",
+ label: "Read (OpenViking)",
+ description:
+ "Read the full original content of one exact OpenViking URI returned by ov_search or ov_list. " +
+ "Use after ov_search before answering precise documentation, codebase, configuration, or procedural questions. " +
+ "Do not use filesystem read/cat for viking:// URIs.",
+ parameters: Type.Object({
+ uri: Type.String({ description: "Exact OpenViking URI to read, e.g. viking://resources/project/docs/step-1.md" }),
+ }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (isBypassedSession(ctx)) {
+ return makeBypassedToolResult("ov_read");
+ }
+ const session = resolvePluginSessionRouting(ctx);
+ return readOpenViking({
+ uri: String((params as { uri?: unknown }).uri ?? ""),
+ }, session.agentId);
+ },
+ }),
+ { name: "ov_read" },
+ );
+
+ api.registerTool(
+ (ctx: ToolContext) => ({
+ name: "ov_multi_read",
+ label: "Multi Read (OpenViking)",
+ description:
+ "Read the full original content of multiple exact OpenViking URIs concurrently. " +
+ "Use after ov_search and ov_list to read an overview plus sibling chunks for split documents or multi-step procedures.",
+ parameters: Type.Object({
+ uris: Type.Array(Type.String({ description: "Exact OpenViking URI to read" }), {
+ description: "Exact OpenViking URIs to read",
+ }),
+ }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (isBypassedSession(ctx)) {
+ return makeBypassedToolResult("ov_multi_read");
+ }
+ const session = resolvePluginSessionRouting(ctx);
+ const uris = Array.isArray((params as { uris?: unknown }).uris)
+ ? (params as { uris: unknown[] }).uris.map((uri) => String(uri))
+ : [];
+ return multiReadOpenViking({ uris }, session.agentId);
+ },
+ }),
+ { name: "ov_multi_read" },
+ );
+
+ api.registerTool(
+ (ctx: ToolContext) => ({
+ name: "ov_list",
+ label: "List (OpenViking)",
+ description:
+ "List files and directories under an OpenViking URI. Use after ov_search to inspect a hit's parent directory, sibling chunks, or .overview.md files when search only returns ranked snippets.",
+ parameters: Type.Object({
+ uri: Type.String({ description: "OpenViking directory URI to list, e.g. viking://resources/project/docs" }),
+ recursive: Type.Optional(Type.Boolean({ description: "List nested entries recursively. Default: false" })),
+ simple: Type.Optional(Type.Boolean({ description: "Return only URI entries from OpenViking. Default: false" })),
+ limit: Type.Optional(Type.Number({ description: "Maximum entries to list. Default: 100" })),
+ }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (isBypassedSession(ctx)) {
+ return makeBypassedToolResult("ov_list");
+ }
+ const session = resolvePluginSessionRouting(ctx);
+ return listOpenViking({
+ uri: String((params as { uri?: unknown }).uri ?? ""),
+ recursive: typeof params.recursive === "boolean" ? params.recursive : undefined,
+ simple: typeof params.simple === "boolean" ? params.simple : undefined,
+ limit: typeof params.limit === "number" ? params.limit : undefined,
+ }, session.agentId);
+ },
+ }),
+ { name: "ov_list" },
+ );
+
api.registerCommand?.({
name: "add-resource",
description: "Add a resource into OpenViking.",
diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.json
index 8656d342f..fe3bcdcb7 100644
--- a/examples/openclaw-plugin/openclaw.plugin.json
+++ b/examples/openclaw-plugin/openclaw.plugin.json
@@ -15,6 +15,9 @@
"add_resource",
"add_skill",
"ov_search",
+ "ov_read",
+ "ov_multi_read",
+ "ov_list",
"memory_recall",
"memory_store",
"memory_forget",
diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.ts
index e1d9702e5..fa7528e13 100644
--- a/examples/openclaw-plugin/tests/ut/tools.test.ts
+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts
@@ -894,12 +894,16 @@ describe("Tool: add_resource, add_skill, and ov_search (registration)", () => {
expect(tool).toBeDefined();
expect(tool!.description).toContain("explicitly asks");
expect(tool!.description).toContain("[media attached: /path");
+ expect(tool!.description).toContain("Set either to");
+ expect(tool!.description).toContain("never both");
expect(tool!.description).toContain("Do not invent OpenViking upload REST endpoints");
const props = (tool!.parameters as any).properties;
expect(props).toHaveProperty("source");
expect(props.source.description).toContain("OpenClaw media attachment path");
expect(props).toHaveProperty("to");
+ expect(props.to.description).toContain("Mutually exclusive with parent");
expect(props).toHaveProperty("parent");
+ expect(props.parent.description).toContain("Mutually exclusive with to");
expect(props).toHaveProperty("reason");
expect(props).toHaveProperty("instruction");
expect(props).toHaveProperty("wait");
@@ -932,11 +936,46 @@ describe("Tool: add_resource, add_skill, and ov_search (registration)", () => {
expect(tools.get("memory_search")).toBeUndefined();
expect(tool!.description).toContain("Search OpenViking resources and skills");
expect(tool!.description).toContain("Use after importing");
+ expect(tool!.description).toContain("call ov_read");
+ expect(tool!.description).toContain("call ov_list on the parent URI");
const props = (tool!.parameters as any).properties;
expect(props).toHaveProperty("query");
expect(props).toHaveProperty("uri");
expect(props).toHaveProperty("limit");
});
+
+ it("registers ov_read and ov_multi_read tools for original evidence retrieval", () => {
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+
+ const read = tools.get("ov_read");
+ expect(read).toBeDefined();
+ expect(read!.description).toContain("Read the full original content");
+ expect(read!.description).toContain("after ov_search");
+ expect(read!.description).toContain("Do not use filesystem read/cat");
+ expect((read!.parameters as any).properties).toHaveProperty("uri");
+
+ const multiRead = tools.get("ov_multi_read");
+ expect(multiRead).toBeDefined();
+ expect(multiRead!.description).toContain("multiple exact OpenViking URIs");
+ expect(multiRead!.description).toContain("sibling chunks");
+ expect((multiRead!.parameters as any).properties).toHaveProperty("uris");
+ });
+
+ it("registers ov_list tool with directory browsing guidance", () => {
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const tool = tools.get("ov_list");
+ expect(tool).toBeDefined();
+ expect(tool!.description).toContain("List files and directories");
+ expect(tool!.description).toContain("after ov_search");
+ expect(tool!.description).toContain("sibling chunks");
+ const props = (tool!.parameters as any).properties;
+ expect(props).toHaveProperty("uri");
+ expect(props).toHaveProperty("recursive");
+ expect(props).toHaveProperty("simple");
+ expect(props).toHaveProperty("limit");
+ });
});
describe("Tool: ov_search (behavioral)", () => {
@@ -1000,6 +1039,8 @@ describe("Tool: ov_search (behavioral)", () => {
expect(result.content[0]!.text).toContain("no");
expect(result.content[0]!.text).toContain("type");
+ expect(result.content[0]!.text).toContain("Use ov_read on exact hit URIs");
+ expect(result.content[0]!.text).toContain("Use ov_list on a hit's parent URI");
expect(result.content[0]!.text).toContain("resource");
expect(result.content[0]!.text).toContain("skill");
expect(result.details.resources).toHaveLength(1);
@@ -1131,6 +1172,148 @@ describe("Tool: ov_search (behavioral)", () => {
});
});
+describe("Tool: ov_read and ov_multi_read (behavioral)", () => {
+ it("reads full content for one exact OpenViking URI", async () => {
+ const fetchMock = vi.fn(async (url: string) => {
+ const requestUrl = new URL(url);
+ if (requestUrl.pathname === "/api/v1/content/read") {
+ expect(requestUrl.searchParams.get("uri")).toBe("viking://resources/guide/step-1.md");
+ return okResponse("# Step 1\nDo the first thing.");
+ }
+ return okResponse({});
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const read = tools.get("ov_read")!;
+ const result = await read.execute("tc-ov-read", {
+ uri: "viking://resources/guide/step-1.md",
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("--- START OF viking://resources/guide/step-1.md ---");
+ expect(result.content[0]!.text).toContain("# Step 1");
+ expect(result.content[0]!.text).toContain("--- END OF viking://resources/guide/step-1.md ---");
+ expect(result.details).toMatchObject({
+ action: "read",
+ uri: "viking://resources/guide/step-1.md",
+ chars: 28,
+ });
+ });
+
+ it("reads multiple OpenViking URIs and preserves per-URI failures", async () => {
+ const fetchMock = vi.fn(async (url: string) => {
+ const requestUrl = new URL(url);
+ if (requestUrl.pathname === "/api/v1/content/read") {
+ const uri = requestUrl.searchParams.get("uri");
+ if (uri === "viking://resources/guide/missing.md") {
+ return new Response(JSON.stringify({ status: "error", message: "not found" }), {
+ status: 404,
+ headers: { "Content-Type": "application/json" },
+ });
+ }
+ return okResponse(`content for ${uri}`);
+ }
+ return okResponse({});
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const multiRead = tools.get("ov_multi_read")!;
+ const result = await multiRead.execute("tc-ov-multi-read", {
+ uris: [
+ "viking://resources/guide/.overview.md",
+ "viking://resources/guide/missing.md",
+ ],
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("Multi-read results for 2 OpenViking resources");
+ expect(result.content[0]!.text).toContain("--- START OF viking://resources/guide/.overview.md ---");
+ expect(result.content[0]!.text).toContain("content for viking://resources/guide/.overview.md");
+ expect(result.content[0]!.text).toContain("--- START OF viking://resources/guide/missing.md ---");
+ expect(result.content[0]!.text).toContain("ERROR:");
+ expect(result.details).toMatchObject({
+ action: "multi_read",
+ count: 2,
+ success_count: 1,
+ });
+ });
+});
+
+describe("Tool: ov_list (behavioral)", () => {
+ it("lists an OpenViking directory through the fs ls endpoint", async () => {
+ const fetchMock = vi.fn(async (url: string) => {
+ const requestUrl = new URL(url);
+ if (requestUrl.pathname === "/api/v1/fs/ls") {
+ expect(requestUrl.searchParams.get("uri")).toBe("viking://resources/guide");
+ expect(requestUrl.searchParams.get("recursive")).toBe("true");
+ expect(requestUrl.searchParams.get("simple")).toBe("false");
+ expect(requestUrl.searchParams.get("node_limit")).toBe("5");
+ return okResponse([
+ {
+ name: ".overview.md",
+ uri: "viking://resources/guide/.overview.md",
+ isDir: false,
+ abstract: "Guide overview",
+ },
+ {
+ name: "step-2.md",
+ uri: "viking://resources/guide/step-2.md",
+ isDir: false,
+ abstract: "Second step",
+ },
+ ]);
+ }
+ return okResponse({});
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const list = tools.get("ov_list")!;
+ const result = await list.execute("tc-ov-list", {
+ uri: "viking://resources/guide",
+ recursive: true,
+ limit: 5,
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("Listed 2 OpenViking entries");
+ expect(result.content[0]!.text).toContain("viking://resources/guide/.overview.md");
+ expect(result.content[0]!.text).toContain("Second step");
+ expect(result.details).toMatchObject({
+ action: "listed",
+ uri: "viking://resources/guide",
+ recursive: true,
+ simple: false,
+ count: 2,
+ });
+ });
+
+ it("passes simple list mode through to OpenViking", async () => {
+ const fetchMock = vi.fn(async (url: string) => {
+ const requestUrl = new URL(url);
+ if (requestUrl.pathname === "/api/v1/fs/ls") {
+ expect(requestUrl.searchParams.get("simple")).toBe("true");
+ return okResponse(["viking://resources/guide/step-1.md"]);
+ }
+ return okResponse({});
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const list = tools.get("ov_list")!;
+ const result = await list.execute("tc-ov-list-simple", {
+ uri: "viking://resources/guide",
+ simple: true,
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("viking://resources/guide/step-1.md");
+ expect(result.details.simple).toBe(true);
+ });
+});
+
describe("OpenViking import command parsing", () => {
it("tokenizes quoted args", () => {
expect(tokenizeCommandArgs(`./README.md --reason "project docs" --wait`)).toEqual([
@@ -1214,10 +1397,10 @@ describe("OpenViking ov_search command parsing", () => {
});
describe("Plugin registration", () => {
- it("registers all 11 tools", () => {
+ it("registers all 14 tools", () => {
const { api } = setupPlugin();
contextEnginePlugin.register(api as any);
- expect(api.registerTool).toHaveBeenCalledTimes(11);
+ expect(api.registerTool).toHaveBeenCalledTimes(14);
});
it("registers add and search commands", () => {