@openviking/openclaw-plugin 2026.5.26 → 2026.6.17-dev.1

package/plugin/openviking-runtime-utils.ts

@@ -0,0 +1,67 @@
+import type { RecallResourceType } from "../registries/recall-resource-types.js";
+
+export function previewText(value: unknown, maxChars: number): string | undefined {
+  const text = typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  if (!text) {
+    return undefined;
+  }
+  return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+export function inferRecallResourceType(uri: string): RecallResourceType | undefined {
+  if (uri.startsWith("viking://resources")) return "resource";
+  if (uri.startsWith("viking://user/skills") || uri.startsWith("viking://skills")) return "agent";
+  if (uri.startsWith("viking://user/")) return "user";
+  return undefined;
+}
+
+export function createTraceId(source: string): string {
+  return `${source}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function createMemoryStoreTempSessionId(): string {
+  return `memory-store-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function boundTraceQuery(query: string, maxChars: number): { query: string; queryTruncated?: boolean } {
+  if (query.length <= maxChars) {
+    return { query };
+  }
+  return { query: query.slice(0, maxChars), queryTruncated: true };
+}
+
+export function extractToolSenderId(ctx: unknown): string | undefined {
+  if (!ctx || typeof ctx !== "object") {
+    return undefined;
+  }
+  const toolCtx = ctx as Record<string, unknown>;
+  if (typeof toolCtx.requesterSenderId === "string") {
+    const trimmed = toolCtx.requesterSenderId.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  if (typeof toolCtx.senderId === "string") {
+    const trimmed = toolCtx.senderId.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return undefined;
+}
+
+export function makeBypassedToolResult(toolName: string) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `OpenViking is bypassed for this session by bypassSessionPatterns; ${toolName} was skipped.`,
+      },
+    ],
+    details: {
+      action: "bypassed",
+      reason: "session_bypassed",
+      toolName,
+    },
+  };
+}

package/plugin/openviking-services.ts

@@ -0,0 +1,49 @@
+export type OpenVikingServiceLogger = {
+  info: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+export type OpenVikingServiceConfig = {
+  baseUrl: string;
+  targetUri: string;
+};
+
+export type OpenVikingServiceClient = {
+  healthCheck: () => Promise<unknown>;
+};
+
+export type OpenVikingServiceOptions = {
+  cfg: OpenVikingServiceConfig;
+  getClient: () => Promise<OpenVikingServiceClient>;
+  logger: OpenVikingServiceLogger;
+  recallTraceHttpRoutesRegistered: boolean;
+  registerRecallTraceRoutes: (ctx?: unknown) => boolean;
+};
+
+export function createOpenVikingService({
+  cfg,
+  getClient,
+  logger,
+  recallTraceHttpRoutesRegistered,
+  registerRecallTraceRoutes,
+}: OpenVikingServiceOptions) {
+  return {
+    id: "openviking",
+    start: async (ctx?: unknown) => {
+      const runtimeRouteRegistered = registerRecallTraceRoutes(ctx);
+      const routeRegistered = recallTraceHttpRoutesRegistered || runtimeRouteRegistered;
+      await (await getClient()).healthCheck().catch(() => {});
+      logger.info(
+        `openviking: initialized (url: ${cfg.baseUrl}, targetUri: ${cfg.targetUri}, search: hybrid endpoint)`,
+      );
+      if (routeRegistered) {
+        logger.info("openviking: registered recall trace Gateway routes");
+      } else {
+        logger.warn?.("openviking: recall trace Gateway route adapter unavailable; use ov_recall_trace tool or /ov-recall-trace command");
+      }
+    },
+    stop: () => {
+      logger.info("openviking: stopped");
+    },
+  };
+}

package/plugin/openviking-session-routing-runtime.ts

@@ -0,0 +1,105 @@
+import type { QueryConfigContext } from "../query-config.js";
+import {
+  createSessionAgentResolver,
+  openClawSessionToOvStorageId,
+} from "../routing/identity-routing.js";
+
+type Logger = {
+  info: (message: string) => void;
+};
+
+export type SessionAgentLookup = {
+  agentId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+};
+
+export type PluginSessionRouting = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+export function createOpenVikingSessionRoutingRuntime(options: {
+  peerPrefix: string;
+  logFindRequests: boolean;
+  logger: Logger;
+}) {
+  const sessionAgentResolver = createSessionAgentResolver(options.peerPrefix);
+
+  const rememberSessionAgentId = (ctx: SessionAgentLookup) => {
+    sessionAgentResolver.remember(ctx);
+  };
+
+  const resolveAgentId = (
+    sessionId?: string,
+    sessionKey?: string,
+    ovSessionId?: string,
+  ): string => {
+    const sid = typeof sessionId === "string" ? sessionId.trim() : "";
+    const sk = typeof sessionKey === "string" ? sessionKey.trim() : "";
+    const ovSid = typeof ovSessionId === "string" ? ovSessionId.trim() : "";
+    const result = sessionAgentResolver.resolve(sid, sk, ovSid);
+    if (options.logFindRequests) {
+      options.logger.info(
+        `openviking: resolveAgentId ${JSON.stringify({
+          sessionId: sid || "(empty)",
+          sessionKey: sk || "(empty)",
+          ovSessionId: ovSid || "(empty)",
+          parsedConfigPeerPrefix: options.peerPrefix,
+          mappedResolvedAgentId: result.mappedResolvedAgentId,
+          resolvedBeforeSanitize: result.resolvedBeforeSanitize,
+          resolved: result.resolved,
+          branch: result.branch,
+          aliases: result.aliases,
+          fromExplicitBinding: result.fromExplicitBinding,
+        })}`,
+      );
+    }
+    return result.resolved;
+  };
+
+  const resolvePluginSessionRouting = (ctx?: SessionAgentLookup): PluginSessionRouting => {
+    const sessionId = typeof ctx?.sessionId === "string" ? ctx.sessionId.trim() : "";
+    const sessionKey = typeof ctx?.sessionKey === "string" ? ctx.sessionKey.trim() : "";
+    let ovSessionId = typeof ctx?.ovSessionId === "string" ? ctx.ovSessionId.trim() : "";
+
+    if (!ovSessionId && (sessionId || sessionKey)) {
+      ovSessionId = openClawSessionToOvStorageId(
+        sessionId || undefined,
+        sessionKey || undefined,
+      );
+    }
+
+    const session = {
+      agentId: ctx?.agentId,
+      sessionId: sessionId || undefined,
+      sessionKey: sessionKey || undefined,
+      ovSessionId: ovSessionId || undefined,
+    };
+    rememberSessionAgentId(session);
+
+    return {
+      sessionId: session.sessionId,
+      sessionKey: session.sessionKey,
+      ovSessionId: session.ovSessionId,
+      agentId: resolveAgentId(session.sessionId, session.sessionKey, session.ovSessionId),
+    };
+  };
+
+  const toQueryConfigContext = (session: PluginSessionRouting): QueryConfigContext => ({
+    peerId: session.agentId,
+    sessionId: session.sessionId,
+    sessionKey: session.sessionKey,
+    ovSessionId: session.ovSessionId,
+  });
+
+  return {
+    rememberSessionAgentId,
+    resolveAgentId,
+    resolvePluginSessionRouting,
+    toQueryConfigContext,
+  };
+}

package/plugin/openviking-tool-result-tools.ts

@@ -0,0 +1,397 @@
+import { Type } from "@sinclair/typebox";
+
+export type OpenVikingToolResultToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+};
+
+export type OpenVikingToolResultSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+export type OpenVikingToolResultToolDefinition = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (_toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
+};
+
+export type OpenVikingToolResultClient = {
+  readToolResult: (
+    sessionId: string,
+    toolResultId: string,
+    options: { offset: number; limit: number; includeMetadata: boolean },
+    agentId?: string,
+  ) => Promise<{
+    content: string;
+    offset: number;
+    limit: number;
+    total_chars: number;
+    has_more: boolean;
+    tool_result_id: string;
+    metadata?: unknown;
+  }>;
+  searchToolResult: (
+    sessionId: string,
+    toolResultId: string,
+    query: string,
+    options: { limit: number; contextChars: number },
+    agentId?: string,
+  ) => Promise<{
+    tool_result_id: string;
+    matches?: Array<{ offset: number; snippet: string }>;
+  }>;
+  listToolResults: (
+    sessionId: string,
+    options: { toolName?: string; limit: number },
+    agentId?: string,
+  ) => Promise<{
+    tool_results?: Array<{
+      storage_uri?: string;
+      tool_name?: string;
+      original_chars?: number;
+      created_at?: string;
+    }>;
+  }>;
+};
+
+export type OpenVikingToolResultToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingToolResultClient>;
+  resolvePluginSessionRouting: (ctx?: OpenVikingToolResultToolContext) => OpenVikingToolResultSession;
+  isBypassedSession: (ctx?: OpenVikingToolResultToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  logger?: { warn?: (message: string) => void };
+};
+
+type ToolResultRef = {
+  sessionId: string;
+  toolResultId: string;
+  ref: string;
+};
+
+export function parseToolResultRef(value: unknown): ToolResultRef | null {
+  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: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+function getPositiveInteger(value: unknown, fallback: number): number {
+  return Math.max(1, getOptionalInteger(value, fallback));
+}
+
+export function registerOpenVikingToolResultTools({
+  registerTool,
+  getClient,
+  resolvePluginSessionRouting,
+  isBypassedSession,
+  makeBypassedToolResult,
+  logger,
+}: OpenVikingToolResultToolsDeps): void {
+  registerTool(
+    (ctx: OpenVikingToolResultToolContext): OpenVikingToolResultToolDefinition => ({
+      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: string, params: Record<string, unknown>) {
+        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: OpenVikingToolResultToolContext): OpenVikingToolResultToolDefinition => ({
+      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: string, params: Record<string, unknown>) {
+        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: OpenVikingToolResultToolContext): OpenVikingToolResultToolDefinition => ({
+      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: string, params: Record<string, unknown>) {
+        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" },
+  );
+}