@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/dist/plugin/openviking-query-runtime.js

@@ -0,0 +1,367 @@
+function mergeFindResults(results) {
+    const deduplicate = (items) => {
+        const seen = new Map();
+        for (const item of items) {
+            if (!seen.has(item.uri)) {
+                seen.set(item.uri, item);
+            }
+        }
+        return Array.from(seen.values());
+    };
+    const memories = deduplicate(results.flatMap((result) => result.memories ?? []));
+    const resources = deduplicate(results.flatMap((result) => result.resources ?? []));
+    const skills = deduplicate(results.flatMap((result) => result.skills ?? []));
+    return {
+        memories,
+        resources,
+        skills,
+        total: memories.length + resources.length + skills.length,
+    };
+}
+function formatOVSearchRows(result) {
+    const truncateSummary = (value, maxChars = 220) => {
+        const collapsed = value.replace(/\s+/g, " ").trim();
+        if (collapsed.length <= maxChars) {
+            return collapsed;
+        }
+        return `${collapsed.slice(0, maxChars - 3)}...`;
+    };
+    const items = [
+        ...(result.memories ?? []).map((item) => ({ contextType: "memory", item })),
+        ...(result.resources ?? []).map((item) => ({ contextType: "resource", item })),
+        ...(result.skills ?? []).map((item) => ({ contextType: "skill", item })),
+    ];
+    if (items.length === 0) {
+        return [];
+    }
+    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 }) => item.uri.length));
+    const levelWidth = Math.max("level".length, ...items.map(({ item }) => String(item.level ?? "").length));
+    const scoreWidth = Math.max("score".length, ...items.map(({ item }) => (typeof item.score === "number" ? item.score.toFixed(2).length : 0)));
+    return [
+        `${numberHeader.padEnd(numberWidth)}  ${"type".padEnd(typeWidth)}  ${"uri".padEnd(uriWidth)}  ${"level".padEnd(levelWidth)}  ${"score".padEnd(scoreWidth)}  abstract`,
+        ...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)}  ${item.uri.padEnd(uriWidth)}  ${String(item.level ?? "").padEnd(levelWidth)}  ${score.padEnd(scoreWidth)}  ${summary}`;
+        }),
+    ];
+}
+function formatOVSearchText(query, uri, result) {
+    if ((result.total ?? 0) <= 0) {
+        const scope = uri ? ` under ${uri}` : "";
+        return `No OpenViking resource or skill results found for "${query}"${scope}.`;
+    }
+    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),
+        "",
+        "Note: result URIs are OpenViking virtual URIs, not local file paths. Use the ov_read tool with the exact viking:// URI to read full content; do not use filesystem read tools for these URIs.",
+    ].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));
+    return lines.join("\n");
+}
+function validateOpenVikingUri(toolName, uri) {
+    if (!uri) {
+        throw new Error("uri is required");
+    }
+    if (!uri.startsWith("viking://")) {
+        throw new Error(`${toolName} only accepts OpenViking viking:// URIs, not local file paths or openviking:// display aliases`);
+    }
+    if (uri.endsWith("...") || uri.includes("…")) {
+        throw new Error(`${toolName} received a truncated display URI. Use the exact full viking:// URI from ov_search details/results; do not shorten it with ... or ….`);
+    }
+}
+function formatOVListEntry(entry) {
+    if (typeof entry === "string") {
+        return entry;
+    }
+    if (!entry || typeof entry !== "object") {
+        return String(entry);
+    }
+    const item = entry;
+    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}`;
+}
+function formatOVListText(uri, entries) {
+    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");
+}
+function formatOVReadText(uri, content) {
+    const body = content || "(empty OpenViking content)";
+    return [`--- START OF ${uri} ---`, body, `--- END OF ${uri} ---`].join("\n");
+}
+function formatOVMultiReadText(results) {
+    return [
+        `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();
+}
+export function createOpenVikingQueryRuntime(deps) {
+    const toTraceResult = (item, resultType) => ({
+        uri: item.uri,
+        resourceType: deps.inferRecallResourceType(item.uri),
+        category: item.category,
+        score: item.score,
+        level: item.level,
+        abstractPreview: deps.previewText(item.abstract || item.overview, deps.cfg.traceRecallPreviewChars),
+        resultType,
+    });
+    const readOpenVikingContent = async (input, agentId) => {
+        const uri = input.uri.trim();
+        validateOpenVikingUri("ov_read", uri);
+        const client = await deps.getClient();
+        const content = await client.read(uri, agentId);
+        const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+        return {
+            content: [{ type: "text", text: formatOVReadText(uri, text) }],
+            details: {
+                action: "read",
+                uri,
+                chars: text.length,
+            },
+        };
+    };
+    const multiReadOpenVikingContent = async (input, agentId) => {
+        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");
+        }
+        for (const uri of uris) {
+            validateOpenVikingUri("ov_multi_read", uri);
+        }
+        const client = await deps.getClient();
+        const results = await Promise.all(uris.map(async (uri) => {
+            try {
+                const content = await client.read(uri, agentId);
+                const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+                return {
+                    uri,
+                    content: text,
+                    success: true,
+                    chars: text.length,
+                };
+            }
+            catch (err) {
+                return {
+                    uri,
+                    content: err instanceof Error ? err.message : String(err),
+                    success: false,
+                    chars: 0,
+                };
+            }
+        }));
+        return {
+            content: [{ type: "text", text: formatOVMultiReadText(results) }],
+            details: {
+                action: "multi_read",
+                count: results.length,
+                success_count: results.filter((result) => result.success).length,
+                results,
+            },
+        };
+    };
+    const listOpenVikingDirectory = async (input, agentId) => {
+        const uri = input.uri.trim();
+        validateOpenVikingUri("ov_list", uri);
+        const limit = Math.max(1, Math.floor(input.limit ?? 100));
+        const client = await deps.getClient();
+        const entries = await client.list(uri, {
+            recursive: input.recursive ?? false,
+            simple: input.simple ?? false,
+            nodeLimit: limit,
+        }, agentId);
+        return {
+            content: [{ type: "text", text: formatOVListText(uri, entries) }],
+            details: {
+                action: "listed",
+                uri,
+                recursive: input.recursive ?? false,
+                simple: input.simple ?? false,
+                count: entries.length,
+                entries,
+            },
+        };
+    };
+    const searchOpenViking = async (input, agentId, traceCtx) => {
+        const query = input.query.trim();
+        if (!query) {
+            throw new Error("query is required");
+        }
+        const queryConfig = traceCtx
+            ? await deps.queryConfigStore.getEffective(deps.toQueryConfigContext(traceCtx), {
+                ovSearchLimit: typeof input.limit === "number" ? input.limit : undefined,
+                targetUri: input.uri,
+            })
+            : undefined;
+        const limit = Math.max(1, Math.floor(input.limit ?? queryConfig?.ovSearchLimit ?? 10));
+        const searchUri = input.uri ?? queryConfig?.targetUri;
+        const client = await deps.getClient();
+        let result;
+        const searches = [];
+        if (searchUri) {
+            const started = Date.now();
+            result = await client.find(query, { targetUri: searchUri, limit }, agentId);
+            const items = [
+                ...(result.memories ?? []).map((item) => toTraceResult(item, "memory")),
+                ...(result.resources ?? []).map((item) => toTraceResult(item, "resource")),
+                ...(result.skills ?? []).map((item) => toTraceResult(item, "skill")),
+            ].slice(0, deps.cfg.traceRecallMaxResultsPerSearch);
+            searches.push({
+                resourceType: deps.inferRecallResourceType(searchUri) ?? "resource",
+                targetUriInput: searchUri,
+                targetUriResolved: searchUri,
+                limit,
+                durationMs: Date.now() - started,
+                total: result.total ?? items.length,
+                results: items,
+            });
+        }
+        else {
+            const runSearch = async (targetUri) => {
+                const started = Date.now();
+                try {
+                    const found = await client.find(query, { targetUri, limit }, agentId);
+                    const items = [
+                        ...(found.memories ?? []).map((item) => toTraceResult(item, "memory")),
+                        ...(found.resources ?? []).map((item) => toTraceResult(item, "resource")),
+                        ...(found.skills ?? []).map((item) => toTraceResult(item, "skill")),
+                    ].slice(0, deps.cfg.traceRecallMaxResultsPerSearch);
+                    searches.push({
+                        resourceType: deps.inferRecallResourceType(targetUri) ?? "resource",
+                        targetUriResolved: targetUri,
+                        limit,
+                        durationMs: Date.now() - started,
+                        total: found.total ?? items.length,
+                        results: items,
+                    });
+                    return found;
+                }
+                catch (err) {
+                    searches.push({
+                        resourceType: deps.inferRecallResourceType(targetUri) ?? "resource",
+                        targetUriResolved: targetUri,
+                        limit,
+                        durationMs: Date.now() - started,
+                        total: 0,
+                        results: [],
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    throw err;
+                }
+            };
+            const [resourcesSettled, skillsSettled] = await Promise.allSettled([
+                runSearch("viking://resources"),
+                runSearch("viking://user/skills"),
+            ]);
+            const successful = [];
+            if (resourcesSettled.status === "fulfilled") {
+                successful.push(resourcesSettled.value);
+            }
+            if (skillsSettled.status === "fulfilled") {
+                successful.push(skillsSettled.value);
+            }
+            if (successful.length === 0) {
+                const firstError = resourcesSettled.status === "rejected"
+                    ? resourcesSettled.reason
+                    : skillsSettled.status === "rejected"
+                        ? skillsSettled.reason
+                        : "Both searches failed";
+                throw firstError instanceof Error ? firstError : new Error(String(firstError));
+            }
+            if (resourcesSettled.status === "rejected") {
+                deps.logger.warn?.(`openviking: resource search failed: ${String(resourcesSettled.reason)}`);
+            }
+            if (skillsSettled.status === "rejected") {
+                deps.logger.warn?.(`openviking: skill search failed: ${String(skillsSettled.reason)}`);
+            }
+            result = mergeFindResults(successful);
+        }
+        const selected = [
+            ...(result.memories ?? []).map((item) => ({
+                uri: item.uri,
+                resourceType: deps.inferRecallResourceType(item.uri),
+                category: item.category,
+                score: item.score,
+                abstractPreview: deps.previewText(item.abstract || item.overview, deps.cfg.traceRecallPreviewChars),
+                displayed: true,
+            })),
+            ...(result.resources ?? []).map((item) => ({
+                uri: item.uri,
+                resourceType: deps.inferRecallResourceType(item.uri),
+                category: item.category,
+                score: item.score,
+                abstractPreview: deps.previewText(item.abstract || item.overview, deps.cfg.traceRecallPreviewChars),
+                displayed: true,
+            })),
+            ...(result.skills ?? []).map((item) => ({
+                uri: item.uri,
+                resourceType: deps.inferRecallResourceType(item.uri),
+                category: item.category,
+                score: item.score,
+                abstractPreview: deps.previewText(item.abstract || item.overview, deps.cfg.traceRecallPreviewChars),
+                displayed: true,
+            })),
+        ];
+        await deps.traceRecorder?.recordAndFlush?.({
+            schemaVersion: "1.0",
+            traceId: deps.createTraceId("ov_search"),
+            ts: Date.now(),
+            sessionId: traceCtx?.sessionId,
+            sessionKey: traceCtx?.sessionKey,
+            ovSessionId: traceCtx?.ovSessionId,
+            agentId,
+            source: "ov_search",
+            operationType: "semantic_find",
+            resourceTypes: [...new Set(searches.map((search) => search.resourceType).filter((resourceType) => resourceType !== "archive"))],
+            trigger: deps.boundTraceQuery(query, deps.cfg.traceRecallQueryMaxChars),
+            searches,
+            selected,
+            stats: {
+                candidateCount: searches.reduce((sum, search) => sum + search.results.length, 0),
+                selectedCount: selected.length,
+                injectedCount: 0,
+            },
+        });
+        return {
+            content: [{ type: "text", text: formatOVSearchText(query, searchUri, result) }],
+            details: {
+                action: "searched",
+                query,
+                uri: searchUri,
+                memories: result.memories ?? [],
+                resources: result.resources ?? [],
+                skills: result.skills ?? [],
+                total: result.total ?? 0,
+            },
+        };
+    };
+    return { readOpenVikingContent, multiReadOpenVikingContent, listOpenVikingDirectory, searchOpenViking };
+}

package/dist/plugin/openviking-query-tools.js

@@ -0,0 +1,91 @@
+import { Type } from "@sinclair/typebox";
+export function registerOpenVikingQueryTools(deps) {
+    deps.registerTool((ctx) => ({
+        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 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. " +
+            "Returned viking:// URIs are OpenViking virtual URIs, not local file paths.",
+        parameters: Type.Object({
+            query: Type.String({ description: "Search query" }),
+            uri: Type.Optional(Type.String({ description: "Optional search URI. Defaults to resources plus agent skills." })),
+            limit: Type.Optional(Type.Number({ description: "Max results per search scope. Default: 10" })),
+        }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_search");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            return deps.searchOpenViking({
+                query: String(params.query ?? ""),
+                uri: typeof params.uri === "string" ? params.uri : undefined,
+                limit: typeof params.limit === "number" ? params.limit : undefined,
+            }, session.agentId, session);
+        },
+    }), { name: "ov_search" });
+    deps.registerTool((ctx) => ({
+        name: "ov_read",
+        label: "Read (OpenViking)",
+        description: "Read the full original content of one exact OpenViking viking:// URI returned by ov_search, ov_list, or recall traces. " +
+            "Use after ov_search before answering precise documentation, codebase, configuration, or procedural questions. " +
+            "OpenViking URIs are virtual context-database identifiers, not local file paths; do not use filesystem read tools for them. " +
+            "Never pass shortened or display-truncated URIs ending with ... or containing …. Use the exact full URI.",
+        parameters: Type.Object({
+            uri: Type.String({ description: "Exact viking:// URI returned by ov_search; pass the full URI, e.g. viking://resources/project-docs/api.md#chunk-3; do not use shortened display text with ... or …." }),
+        }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_read");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            return deps.readOpenVikingContent({
+                uri: String(params.uri ?? ""),
+            }, session.agentId);
+        },
+    }), { name: "ov_read" });
+    deps.registerTool((ctx) => ({
+        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 viking:// URI to read" }), {
+                description: "Exact OpenViking viking:// URIs to read",
+            }),
+        }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_multi_read");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            const uris = Array.isArray(params.uris)
+                ? params.uris.map((uri) => String(uri))
+                : [];
+            return deps.multiReadOpenVikingContent({ uris }, session.agentId);
+        },
+    }), { name: "ov_multi_read" });
+    deps.registerTool((ctx) => ({
+        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, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_list");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            return deps.listOpenVikingDirectory({
+                uri: String(params.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" });
+}