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

package/dist/plugin/openviking-tool-result-tools.js

@@ -0,0 +1,268 @@
+import { Type } from "@sinclair/typebox";
+export function parseToolResultRef(value) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    if (!raw) {
+        return null;
+    }
+    const match = raw.match(/^viking:\/\/session\/([^/]+)\/tool-results\/([^/?#]+)(?:[?#].*)?$/);
+    if (!match) {
+        return null;
+    }
+    const sessionId = decodeURIComponent(match[1]);
+    const toolResultId = decodeURIComponent(match[2]);
+    if (!sessionId || !toolResultId) {
+        return null;
+    }
+    return {
+        sessionId,
+        toolResultId,
+        ref: `viking://session/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}`,
+    };
+}
+function getOptionalInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function getPositiveInteger(value, fallback) {
+    return Math.max(1, getOptionalInteger(value, fallback));
+}
+export function registerOpenVikingToolResultTools({ registerTool, getClient, resolvePluginSessionRouting, isBypassedSession, makeBypassedToolResult, logger, }) {
+    registerTool((ctx) => ({
+        name: "openviking_tool_result_read",
+        label: "Tool Result Read (OpenViking)",
+        description: "Restore the full original content of a tool result that was externalized by OpenViking. " +
+            "Use when a previous tool result was externalized and only a preview is visible — " +
+            "the preview contains a [tool-result-ref] or viking://session/.../tool-results/... URI. " +
+            "\"Read\" tool returns the same truncated preview; this tool returns the complete content. " +
+            "To read all content: pass offset=0 and a limit large enough to cover the whole result " +
+            "(e.g. limit=100000). Use offset/limit for paging only when you need a specific section.",
+        parameters: Type.Object({
+            tool_output_ref: Type.String({
+                description: "Exact OV URI from the preview, e.g. viking://session/<session_id>/tool-results/<tool_result_id>",
+            }),
+            offset: Type.Optional(Type.Number({ description: "Unicode character offset. Default: 0" })),
+            limit: Type.Optional(Type.Number({ description: "Maximum Unicode characters to read. Default: 20000" })),
+        }),
+        async execute(_toolCallId, params) {
+            if (isBypassedSession(ctx)) {
+                return makeBypassedToolResult("openviking_tool_result_read");
+            }
+            const session = resolvePluginSessionRouting(ctx);
+            if (!session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: no active session." }],
+                    details: { error: "no_session" },
+                };
+            }
+            const parsed = parseToolResultRef(params.tool_output_ref ?? params.ref ?? params.uri);
+            if (!parsed) {
+                return {
+                    content: [{ type: "text", text: "Error: tool_output_ref must be a viking://session/.../tool-results/... URI." }],
+                    details: { error: "invalid_tool_output_ref" },
+                };
+            }
+            if (parsed.sessionId !== session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: refusing to read a tool result from another session." }],
+                    details: {
+                        error: "session_mismatch",
+                        requestedSessionId: parsed.sessionId,
+                        currentSessionId: session.ovSessionId,
+                    },
+                };
+            }
+            const offset = Math.max(0, getOptionalInteger(params.offset, 0));
+            const limit = getOptionalInteger(params.limit, 20_000);
+            if (limit < -1) {
+                return {
+                    content: [{ type: "text", text: "Error: limit must be -1 or greater than or equal to 0." }],
+                    details: { error: "invalid_limit", limit },
+                };
+            }
+            try {
+                const client = await getClient();
+                const result = await client.readToolResult(session.ovSessionId, parsed.toolResultId, { offset, limit, includeMetadata: true }, session.agentId);
+                const returnedChars = result.content.length;
+                const nextOffset = result.offset + returnedChars;
+                const text = result.content || "(empty tool result chunk)";
+                return {
+                    content: [{ type: "text", text }],
+                    details: {
+                        action: "read",
+                        tool_output_ref: parsed.ref,
+                        tool_result_id: result.tool_result_id,
+                        offset: result.offset,
+                        limit: result.limit,
+                        returned_chars: returnedChars,
+                        total_chars: result.total_chars,
+                        has_more: result.has_more,
+                        next_offset: result.has_more ? nextOffset : null,
+                        metadata: result.metadata ?? null,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger?.warn?.(`openviking: openviking_tool_result_read failed: ${msg}`);
+                return {
+                    content: [{ type: "text", text: `Failed to read tool result: ${msg}` }],
+                    details: { error: msg, tool_output_ref: parsed.ref },
+                };
+            }
+        },
+    }), { name: "openviking_tool_result_read" });
+    registerTool((ctx) => ({
+        name: "openviking_tool_result_search",
+        label: "Tool Result Search (OpenViking)",
+        description: "Search inside an externalized tool result for a keyword. " +
+            "Use when you need to find specific content in a large externalized result, " +
+            "before reading it with openviking_tool_result_read. " +
+            "Returns matching snippets with their character offsets.",
+        parameters: Type.Object({
+            tool_output_ref: Type.String({
+                description: "Exact OV URI from the preview, e.g. viking://session/<session_id>/tool-results/<tool_result_id>",
+            }),
+            query: Type.String({ description: "Keyword or exact text to search for" }),
+            limit: Type.Optional(Type.Number({ description: "Maximum matches. Default: 20" })),
+            context_chars: Type.Optional(Type.Number({ description: "Characters around each match. Default: 300" })),
+        }),
+        async execute(_toolCallId, params) {
+            if (isBypassedSession(ctx)) {
+                return makeBypassedToolResult("openviking_tool_result_search");
+            }
+            const session = resolvePluginSessionRouting(ctx);
+            if (!session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: no active session." }],
+                    details: { error: "no_session" },
+                };
+            }
+            const parsed = parseToolResultRef(params.tool_output_ref ?? params.ref ?? params.uri);
+            if (!parsed) {
+                return {
+                    content: [{ type: "text", text: "Error: tool_output_ref must be a viking://session/.../tool-results/... URI." }],
+                    details: { error: "invalid_tool_output_ref" },
+                };
+            }
+            if (parsed.sessionId !== session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: refusing to search a tool result from another session." }],
+                    details: {
+                        error: "session_mismatch",
+                        requestedSessionId: parsed.sessionId,
+                        currentSessionId: session.ovSessionId,
+                    },
+                };
+            }
+            const query = String(params.query ?? "").trim();
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "Error: query is required." }],
+                    details: { error: "missing_param", param: "query" },
+                };
+            }
+            const limit = getPositiveInteger(params.limit, 20);
+            const contextChars = Math.max(0, getOptionalInteger(params.context_chars ?? params.contextChars, 300));
+            try {
+                const client = await getClient();
+                const result = await client.searchToolResult(session.ovSessionId, parsed.toolResultId, query, { limit, contextChars }, session.agentId);
+                const matches = result.matches ?? [];
+                const text = matches.length
+                    ? [
+                        `Found ${matches.length} match(es) for "${query}" in ${parsed.ref}:`,
+                        "",
+                        ...matches.map((match, index) => `## Match ${index + 1} (offset ${match.offset})\n${match.snippet}`),
+                    ].join("\n")
+                    : `No matches found for "${query}" in ${parsed.ref}.`;
+                return {
+                    content: [{ type: "text", text }],
+                    details: {
+                        action: "searched",
+                        tool_output_ref: parsed.ref,
+                        tool_result_id: result.tool_result_id,
+                        query,
+                        match_count: matches.length,
+                        matches,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger?.warn?.(`openviking: openviking_tool_result_search failed: ${msg}`);
+                return {
+                    content: [{ type: "text", text: `Failed to search tool result: ${msg}` }],
+                    details: { error: msg, tool_output_ref: parsed.ref, query },
+                };
+            }
+        },
+    }), { name: "openviking_tool_result_search" });
+    registerTool((ctx) => ({
+        name: "openviking_tool_result_list",
+        label: "Tool Result List (OpenViking)",
+        description: "List externalized tool results for the current session. " +
+            "Use to discover available refs before calling openviking_tool_result_read. " +
+            "Optionally filter by tool_name to narrow down results.",
+        parameters: Type.Object({
+            tool_name: Type.Optional(Type.String({ description: "Optional exact tool name filter" })),
+            limit: Type.Optional(Type.Number({ description: "Maximum results. Default: 50" })),
+        }),
+        async execute(_toolCallId, params) {
+            if (isBypassedSession(ctx)) {
+                return makeBypassedToolResult("openviking_tool_result_list");
+            }
+            const session = resolvePluginSessionRouting(ctx);
+            if (!session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: no active session." }],
+                    details: { error: "no_session" },
+                };
+            }
+            const toolName = typeof params.tool_name === "string" && params.tool_name.trim()
+                ? params.tool_name.trim()
+                : typeof params.toolName === "string" && params.toolName.trim()
+                    ? params.toolName.trim()
+                    : undefined;
+            const limit = getPositiveInteger(params.limit, 50);
+            try {
+                const client = await getClient();
+                const result = await client.listToolResults(session.ovSessionId, { toolName, limit }, session.agentId);
+                const items = result.tool_results ?? [];
+                const text = items.length
+                    ? [
+                        `Found ${items.length} externalized tool result(s) in current session:`,
+                        "",
+                        ...items.map((item, index) => {
+                            const ref = typeof item.storage_uri === "string" ? item.storage_uri : "(missing ref)";
+                            const name = typeof item.tool_name === "string" ? item.tool_name : "tool";
+                            const chars = typeof item.original_chars === "number" ? item.original_chars : "unknown";
+                            const created = typeof item.created_at === "string" ? ` created_at=${item.created_at}` : "";
+                            return `${index + 1}. ${name} original_chars=${chars}${created}\nref: ${ref}`;
+                        }),
+                    ].join("\n")
+                    : toolName
+                        ? `No externalized tool results found for tool "${toolName}" in current session.`
+                        : "No externalized tool results found in current session.";
+                return {
+                    content: [{ type: "text", text }],
+                    details: {
+                        action: "listed",
+                        session_id: session.ovSessionId,
+                        tool_name: toolName ?? null,
+                        count: items.length,
+                        tool_results: items,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger?.warn?.(`openviking: openviking_tool_result_list failed: ${msg}`);
+                return {
+                    content: [{ type: "text", text: `Failed to list tool results: ${msg}` }],
+                    details: { error: msg, session_id: session.ovSessionId, tool_name: toolName ?? null },
+                };
+            }
+        },
+    }), { name: "openviking_tool_result_list" });
+}

package/dist/plugin/recall-trace-routes.js

@@ -0,0 +1,77 @@
+export const RECALL_TRACE_ROUTE_PATHS = [
+    "/api/openviking/recall-traces",
+    "/api/openviking/uri-detail",
+    "/api/openviking/recall-traces/latest-ov-search-list",
+    "/api/openviking/recall-traces/:traceId",
+];
+export function registerRecallTraceRoutes(ctx, handlers) {
+    const routeAdapter = ctx;
+    const canRegisterLegacyRoute = typeof routeAdapter?.registerRoute === "function";
+    const canRegisterHttpRoute = typeof routeAdapter?.registerHttpRoute === "function";
+    if (!canRegisterLegacyRoute && !canRegisterHttpRoute) {
+        return false;
+    }
+    const handle = handlers.handleRecallTraces;
+    const routes = [
+        { method: "GET", path: RECALL_TRACE_ROUTE_PATHS[0], handler: handle },
+        { method: "GET", path: RECALL_TRACE_ROUTE_PATHS[1], handler: handlers.handleUriDetail },
+        { method: "GET", path: RECALL_TRACE_ROUTE_PATHS[2], handler: handlers.handleLatestOvSearchList },
+        {
+            method: "GET",
+            path: RECALL_TRACE_ROUTE_PATHS[3],
+            handler: (request) => handle({
+                ...request,
+                query: {
+                    ...(request?.query ?? {}),
+                    traceId: typeof request?.params?.traceId === "string" ? request.params.traceId : undefined,
+                },
+            }),
+        },
+    ];
+    for (const route of routes) {
+        routeAdapter?.registerRoute?.(route);
+    }
+    if (canRegisterHttpRoute) {
+        const sendJson = (res, status, body) => {
+            res.statusCode = status;
+            res.setHeader?.("Cache-Control", "no-store");
+            res.setHeader?.("Content-Type", "application/json; charset=utf-8");
+            res.end?.(JSON.stringify(body));
+        };
+        const makeHttpHandler = (route, getParams) => async (req, res) => {
+            if ((req.method ?? "GET").toUpperCase() !== route.method) {
+                sendJson(res, 405, { ok: false, error: { code: "method_not_allowed", message: `${route.method} is required` } });
+                return true;
+            }
+            const url = req.url ?? route.path;
+            const result = await route.handler({ url, params: getParams?.(url) });
+            const response = result;
+            sendJson(res, typeof response.status === "number" ? response.status : 200, response.body ?? response);
+            return true;
+        };
+        for (const route of routes) {
+            if (route.path === RECALL_TRACE_ROUTE_PATHS[3]) {
+                const prefix = "/api/openviking/recall-traces/";
+                routeAdapter?.registerHttpRoute?.({
+                    path: "/api/openviking/recall-traces",
+                    auth: "plugin",
+                    match: "prefix",
+                    handler: makeHttpHandler(route, (url) => {
+                        const pathname = new URL(url, "http://openclaw.local").pathname;
+                        const traceId = pathname.startsWith(prefix) ? decodeURIComponent(pathname.slice(prefix.length)) : "";
+                        return traceId ? { traceId } : {};
+                    }),
+                });
+            }
+            else {
+                routeAdapter?.registerHttpRoute?.({
+                    path: route.path,
+                    auth: "plugin",
+                    match: "exact",
+                    handler: makeHttpHandler(route),
+                });
+            }
+        }
+    }
+    return true;
+}

package/dist/plugin/tool-registration.js

@@ -0,0 +1,23 @@
+export function createOpenVikingToolRegistrar({ api, enabledToolNames, logger, }) {
+    return (toolOrFactory, opts) => {
+        if (!enabledToolNames.has(opts.name)) {
+            logger?.debug?.(`openviking: tool ${opts.name} disabled by config`);
+            return;
+        }
+        api.registerTool(toolOrFactory, opts);
+    };
+}
+export function createOpenVikingToolRegistrationRuntime(options) {
+    const enabledTools = Array.isArray(options.cfg.enabledTools)
+        ? options.cfg.enabledTools
+        : [options.cfg.enabledTools];
+    const enabledToolNames = new Set(enabledTools);
+    const registerOpenVikingTool = createOpenVikingToolRegistrar({
+        api: options.api,
+        enabledToolNames,
+        logger: options.logger,
+    });
+    return {
+        registerOpenVikingTool,
+    };
+}

package/dist/process-manager.js

@@ -12,7 +12,7 @@ export function withTimeout(promise, timeoutMs, timeoutMessage) {
 }
 export async function quickHealthCheck(client, agentId, timeoutMs) {
     try {
-        await client.healthCheck(agentId, timeoutMs);
+        await client.healthCheck(timeoutMs, agentId);
         return true;
     }
     catch {