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

package/package.json

@@ -1,76 +1,86 @@
-{
-  "name": "@openviking/openclaw-plugin",
-  "version": "2026.5.26",
-  "displayName": "OpenViking",
-  "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
-  "type": "module",
-  "keywords": [
-    "openclaw",
-    "openviking",
-    "plugin",
-    "context-engine",
-    "memory",
-    "remote-memory",
-    "RAG",
-    "semantic-retrieval",
-    "context-database",
-    "long-term-memory",
-    "auto-recall",
-    "auto-capture"
-  ],
-  "files": [
-    "dist/",
-    "*.ts",
-    "commands/setup.ts",
-    "!vitest.config.ts",
-    "install-manifest.json",
-    "openclaw.plugin.json",
-    "package.json",
-    "README.md",
-    "INSTALL.md",
-    "INSTALL-ZH.md",
-    "INSTALL-AGENT.md",
-    "images/",
-    "skills/"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json",
-    "test:watch": "vitest"
-  },
-  "engines": {
-    "openclaw": ">=2026.4.8"
-  },
-  "dependencies": {
-    "@sinclair/typebox": "0.34.48",
-    "fflate": "^0.8.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/volcengine/OpenViking"
-  },
-  "homepage": "https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin",
-  "license": "MIT",
-  "author": "OpenViking Contributors",
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "setupEntry": "./commands/setup.ts",
-    "compat": {
-      "pluginApi": ">=2026.4.8",
-      "minGatewayVersion": "2026.4.8"
-    },
-    "build": {
-      "openclawVersion": "2026.4.8",
-      "pluginSdkVersion": "2026.4.8"
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.5",
-    "typescript": "^5.8.0",
-    "vitest": "^4.1.0"
-  }
-}
+{
+  "name": "@openviking/openclaw-plugin",
+  "version": "2026.6.17-dev.1",
+  "displayName": "OpenViking",
+  "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
+  "type": "module",
+  "keywords": [
+    "openclaw",
+    "openviking",
+    "plugin",
+    "context-engine",
+    "memory",
+    "remote-memory",
+    "RAG",
+    "semantic-retrieval",
+    "context-database",
+    "long-term-memory",
+    "auto-recall",
+    "auto-capture"
+  ],
+  "files": [
+    "dist/",
+    "*.ts",
+    "adapters/",
+    "commands/setup.ts",
+    "config/feature-gates.json",
+    "registries/",
+    "routing/",
+    "plugin/",
+    "services/",
+    "!vitest.config.ts",
+    "install-manifest.json",
+    "openclaw.plugin.json",
+    "package.json",
+    "README.md",
+    "INSTALL.md",
+    "INSTALL-ZH.md",
+    "INSTALL-AGENT.md",
+    "images/",
+    "skills/"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "openclaw": ">=2026.4.8"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "fflate": "^0.8.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/volcengine/OpenViking"
+  },
+  "overrides": {
+    "axios": "^1.16.1"
+  },
+  "homepage": "https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin",
+  "license": "MIT",
+  "author": "OpenViking Contributors",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "setupEntry": "./dist/commands/setup.js",
+    "compat": {
+      "pluginApi": ">=2026.4.8",
+      "minGatewayVersion": "2026.4.8"
+    },
+    "build": {
+      "openclawVersion": "2026.4.8",
+      "pluginSdkVersion": "2026.4.8"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "@volcengine/tos-sdk": "^2.9.1",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.0"
+  }
+}

package/plugin/command-registration.ts

@@ -0,0 +1,34 @@
+export type PluginCommandContext = {
+  args?: string;
+  commandBody?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  ovSessionId?: string;
+};
+
+export type CommandResult = {
+  text: string;
+  details?: Record<string, unknown>;
+};
+
+export type CommandDefinition = {
+  name: string;
+  description: string;
+  acceptsArgs?: boolean;
+  requireAuth?: boolean;
+  handler: (ctx: PluginCommandContext) => CommandResult | Promise<CommandResult>;
+};
+
+export type OpenVikingCommandRegistrationApi = {
+  registerCommand?: (command: CommandDefinition) => void;
+};
+
+export function registerOpenVikingCommands(
+  api: OpenVikingCommandRegistrationApi,
+  commands: CommandDefinition[],
+): void {
+  for (const command of commands) {
+    api.registerCommand?.(command);
+  }
+}

package/plugin/openviking-archive-tools.ts

@@ -0,0 +1,301 @@
+import { Type } from "@sinclair/typebox";
+import type { OVMessage } from "../client.js";
+import type { RecallTraceEntry, RecallTraceResult } from "../recall-trace.js";
+
+export type OpenVikingArchiveToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+};
+
+export type OpenVikingArchiveSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+type OpenVikingArchiveMatch = {
+  uri: string;
+  line: number;
+  content: string;
+};
+
+export type OpenVikingArchiveClient = {
+  grepSessionArchives: (
+    sessionId: string,
+    pattern: string,
+    options: { archiveId?: string; caseInsensitive: boolean; agentId?: string },
+  ) => Promise<{
+    count?: number;
+    matches?: OpenVikingArchiveMatch[];
+  }>;
+  getSessionArchive: (
+    sessionId: string,
+    archiveId: string,
+    agentId?: string,
+  ) => Promise<{
+    archive_id: string;
+    abstract?: string;
+    messages: OVMessage[];
+  }>;
+};
+
+export type OpenVikingArchiveToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingArchiveClient>;
+  rememberSessionAgentId: (ctx: OpenVikingArchiveToolContext) => void;
+  toOvSessionId: (sessionId?: string, sessionKey?: string) => string;
+  resolveAgentId: (sessionId?: string, sessionKey?: string, ovSessionId?: string) => string;
+  resolvePluginSessionRouting: (ctx?: OpenVikingArchiveToolContext) => OpenVikingArchiveSession;
+  isBypassedSession: (ctx?: OpenVikingArchiveToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  formatMessage: (message: OVMessage) => string;
+  traceRecorder?: { recordAndFlush: (trace: RecallTraceEntry) => Promise<unknown> | unknown };
+  traceRecallMaxResultsPerSearch: number;
+  traceRecallPreviewChars: number;
+  createTraceId: (source: string) => string;
+  logger?: {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+  };
+};
+
+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 registerOpenVikingArchiveTools(deps: OpenVikingArchiveToolsDeps): void {
+  deps.registerTool(
+    (ctx: OpenVikingArchiveToolContext) => ({
+      name: "ov_archive_search",
+      label: "Archive Search (OpenViking)",
+      description:
+        "Keyword-grep across all archived original conversation messages of the current session. " +
+        "Use this whenever the [Session History Summary] does not contain the specific detail " +
+        "the user is asking about. Extract 2-3 concrete entity words from the question " +
+        "(names, places, objects, dates) and search each separately. " +
+        "Only conclude information is unavailable after trying at least 2 different keyword variations.",
+      parameters: Type.Object({
+        query: Type.String({
+          description:
+            "A single keyword or short phrase to grep. Use concrete nouns, names, dates, " +
+            "or distinctive phrases. Case-insensitive. Prefer entity words over full sentences.",
+        }),
+        archiveId: Type.Optional(
+          Type.String({
+            description: 'Optional: limit search to one archive (e.g. "archive_005")',
+          }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("ov_archive_search");
+        }
+        deps.rememberSessionAgentId(ctx);
+        const sessionId = ctx.sessionId ?? "";
+        const sessionKey = ctx.sessionKey ?? "";
+        if (!sessionId && !sessionKey) {
+          return {
+            content: [{ type: "text", text: "Error: no active session." }],
+            details: { error: "no_session" },
+          };
+        }
+        const ovSessionId = deps.toOvSessionId(ctx.sessionId, ctx.sessionKey);
+        const query = String((params as { query?: string }).query ?? "").trim();
+        const archiveId = (params as { archiveId?: string }).archiveId;
+
+        if (!query) {
+          return {
+            content: [{ type: "text", text: "Error: query is required." }],
+            details: { error: "missing_param", param: "query" },
+          };
+        }
+
+        const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        deps.logger?.info?.(`openviking: ov_archive_search query="${query}" escaped="${escapedQuery}" archive=${archiveId ?? "all"} session=${ovSessionId}`);
+
+        try {
+          const client = await deps.getClient();
+          const agentId = deps.resolveAgentId(ctx.sessionId, ctx.sessionKey);
+          const started = Date.now();
+          const result = await client.grepSessionArchives(ovSessionId, escapedQuery, {
+            archiveId,
+            caseInsensitive: true,
+            agentId,
+          });
+          const traceResults: RecallTraceResult[] = (result.matches ?? []).slice(0, deps.traceRecallMaxResultsPerSearch).map((match) => ({
+            uri: match.uri,
+            resourceType: "archive",
+            abstractPreview: previewText(match.content, deps.traceRecallPreviewChars),
+            resultType: "archive_match",
+          }));
+
+          const recordArchiveTrace = async (displayed: OpenVikingArchiveMatch[]) => {
+            await deps.traceRecorder?.recordAndFlush({
+              schemaVersion: "1.0",
+              traceId: deps.createTraceId("ov_archive_search"),
+              ts: Date.now(),
+              sessionId: ctx.sessionId,
+              sessionKey: ctx.sessionKey,
+              ovSessionId,
+              agentId,
+              source: "ov_archive_search",
+              operationType: "archive_grep",
+              resourceTypes: ["session"],
+              trigger: { query, derivedKeywords: [query] },
+              searches: [{
+                resourceType: "archive",
+                targetUriResolved: archiveId ? `viking://session/${ovSessionId}/history/${archiveId}` : `viking://session/${ovSessionId}/history`,
+                limit: deps.traceRecallMaxResultsPerSearch,
+                durationMs: Date.now() - started,
+                total: result.matches?.length ?? result.count ?? 0,
+                results: traceResults,
+                archiveId,
+                caseInsensitive: true,
+              }],
+              selected: displayed.map((match) => ({
+                uri: match.uri,
+                resourceType: "archive",
+                line: match.line,
+                abstractPreview: previewText(match.content, deps.traceRecallPreviewChars),
+                displayed: true,
+              })),
+              stats: {
+                candidateCount: result.matches?.length ?? result.count ?? 0,
+                selectedCount: displayed.length,
+                injectedCount: 0,
+              },
+            });
+          };
+
+          if (!result.matches || result.matches.length === 0) {
+            await recordArchiveTrace([]);
+            return {
+              content: [{
+                type: "text",
+                text: `No matches found for "${query}". Try a different keyword — ` +
+                  "the original conversation may use different wording than the question. " +
+                  "Try synonyms, related terms, or shorter fragments.",
+              }],
+              details: { query, matchCount: 0 },
+            };
+          }
+
+          const MAX_MATCHES = 12;
+          const MAX_LINE_LEN = 1500;
+          const shown = result.matches.slice(0, MAX_MATCHES);
+          await recordArchiveTrace(shown);
+          const blocks = shown.map((m, i) => {
+            const archiveTag = m.uri.match(/archive_\d+/)?.[0] ?? "unknown";
+            const truncated = m.content.length > MAX_LINE_LEN
+              ? m.content.slice(0, MAX_LINE_LEN) + "…(truncated)"
+              : m.content;
+            return `## Match ${i + 1}: ${archiveTag} (line ${m.line})\n${truncated}`;
+          });
+
+          const header = `Found ${result.matches.length} match(es) for "${query}"` +
+            (result.matches.length > MAX_MATCHES ? ` (showing first ${MAX_MATCHES})` : "") + ":";
+
+          return {
+            content: [{ type: "text", text: header + "\n\n" + blocks.join("\n\n") }],
+            details: { query, matchCount: result.matches.length },
+          };
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : String(err);
+          deps.logger?.error?.(`openviking: ov_archive_search error: ${msg}`);
+          return {
+            content: [{ type: "text", text: `Archive search failed: ${msg}` }],
+            details: { error: msg },
+          };
+        }
+      },
+    }),
+    { name: "ov_archive_search" },
+  );
+
+  deps.registerTool((ctx: OpenVikingArchiveToolContext) => ({
+    name: "ov_archive_expand",
+    label: "Archive Expand (OpenViking)",
+    description:
+      "Retrieve original messages from a compressed session archive. " +
+      "Use when a session summary lacks specific details " +
+      "such as exact commands, file paths, code snippets, or config values. " +
+      "Check [Archive Index] to find the right archive ID.",
+    parameters: Type.Object({
+      archiveId: Type.String({
+        description:
+          'Archive ID from [Archive Index] (e.g. "archive_002")',
+      }),
+    }),
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      if (deps.isBypassedSession(ctx)) {
+        return deps.makeBypassedToolResult("ov_archive_expand");
+      }
+      const session = deps.resolvePluginSessionRouting(ctx);
+      const archiveId = String((params as { archiveId?: string }).archiveId ?? "").trim();
+      const sessionId = session.sessionId ?? "";
+      deps.logger?.info?.(`openviking: ov_archive_expand invoked (archiveId=${archiveId || "(empty)"}, sessionId=${sessionId || "(empty)"})`);
+
+      if (!archiveId) {
+        deps.logger?.warn?.("openviking: ov_archive_expand missing archiveId");
+        return {
+          content: [{ type: "text", text: "Error: archiveId is required." }],
+          details: { error: "missing_param", param: "archiveId" },
+        };
+      }
+
+      if (!session.ovSessionId) {
+        return {
+          content: [{ type: "text", text: "Error: no active session." }],
+          details: { error: "no_session" },
+        };
+      }
+
+      try {
+        const client = await deps.getClient();
+        const detail = await client.getSessionArchive(
+          session.ovSessionId,
+          archiveId,
+          session.agentId,
+        );
+
+        const header = [
+          `## ${detail.archive_id}`,
+          detail.abstract ? `**Summary**: ${detail.abstract}` : "",
+          `**Messages**: ${detail.messages.length}`,
+          "",
+        ].filter(Boolean).join("\n");
+
+        const body = detail.messages
+          .map((message) => deps.formatMessage(message))
+          .join("\n\n");
+
+        deps.logger?.info?.(`openviking: ov_archive_expand expanded ${detail.archive_id}, messages=${detail.messages.length}, chars=${body.length}, sessionId=${sessionId}`);
+        return {
+          content: [{ type: "text", text: `${header}\n${body}` }],
+          details: {
+            action: "expanded",
+            archiveId: detail.archive_id,
+            messageCount: detail.messages.length,
+            sessionId,
+            ovSessionId: session.ovSessionId,
+          },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        deps.logger?.warn?.(`openviking: ov_archive_expand failed (archiveId=${archiveId}, sessionId=${sessionId}): ${msg}`);
+        return {
+          content: [{ type: "text", text: `Failed to expand ${archiveId}: ${msg}` }],
+          details: { error: msg, archiveId, sessionId, ovSessionId: session.ovSessionId },
+        };
+      }
+    },
+  }), { name: "ov_archive_expand" });
+}

package/plugin/openviking-bypass-runtime.ts

@@ -0,0 +1,26 @@
+import {
+  compileSessionPatterns,
+  shouldBypassSession,
+} from "../text-utils.js";
+
+type BypassRuntimeConfig = {
+  bypassSessionPatterns: string[];
+};
+
+type SessionBypassContext = {
+  sessionId?: string;
+  sessionKey?: string;
+};
+
+export function createOpenVikingBypassRuntime<TConfig extends BypassRuntimeConfig>(options: {
+  cfg: TConfig;
+}) {
+  const bypassSessionPatterns = compileSessionPatterns(options.cfg.bypassSessionPatterns);
+
+  const isBypassedSession = (ctx?: SessionBypassContext): boolean =>
+    shouldBypassSession(ctx ?? {}, bypassSessionPatterns);
+
+  return {
+    isBypassedSession,
+  };
+}

package/plugin/openviking-client-runtime.ts

@@ -0,0 +1,74 @@
+import { OpenVikingClient } from "../client.js";
+import type { HttpTransport } from "../adapters/http-transport.js";
+
+type Logger = {
+  info: (message: string) => void;
+};
+
+type ClientRuntimeConfig = {
+  baseUrl: string;
+  apiKey: string;
+  peer_role: "none" | "assistant" | "person";
+  peer_prefix: string;
+  timeoutMs: number;
+  accountId?: string;
+  userId?: string;
+  logFindRequests: boolean;
+};
+
+export function createOpenVikingClientRuntime(options: {
+  cfg: ClientRuntimeConfig;
+  rawPeerPrefix: unknown;
+  logger: Logger;
+  transport?: HttpTransport;
+}) {
+  const { cfg, logger } = options;
+
+  if (cfg.logFindRequests) {
+    logger.info(
+      "openviking: routing debug logging enabled (config logFindRequests, or env OPENVIKING_LOG_ROUTING=1 / OPENVIKING_DEBUG=1)",
+    );
+  }
+
+  const verboseRoutingInfo = (message: string) => {
+    if (cfg.logFindRequests) {
+      logger.info(message);
+    }
+  };
+
+  verboseRoutingInfo(
+    `openviking: loaded plugin config peer_role="${cfg.peer_role}" peer_prefix="${cfg.peer_prefix}" ` +
+      `(raw peer_prefix=${JSON.stringify(options.rawPeerPrefix ?? "(missing)")}; ` +
+      `${
+        cfg.peer_prefix
+          ? 'non-empty → assistant peer_id is <peer_prefix>_<ctx.agentId> when peer_role="assistant", or <peer_prefix>_main when ctx.agentId is unknown'
+          : 'empty → assistant peer_id follows OpenClaw ctx.agentId when peer_role="assistant", or "main" when ctx.agentId is unknown'
+      })`,
+  );
+
+  const routingDebugLog = cfg.logFindRequests
+    ? (msg: string) => {
+        logger.info(msg);
+      }
+    : undefined;
+
+  const clientPromise = Promise.resolve(
+    new OpenVikingClient(
+      cfg.baseUrl,
+      cfg.apiKey,
+      cfg.peer_prefix,
+      cfg.timeoutMs,
+      cfg.accountId,
+      cfg.userId,
+      routingDebugLog,
+      { transport: options.transport },
+    ),
+  );
+
+  const getClient = (): Promise<OpenVikingClient> => clientPromise;
+
+  return {
+    getClient,
+    verboseRoutingInfo,
+  };
+}