@openviking/openclaw-plugin 2026.9.8 → 2026.9.9

package/commands/setup.ts

@@ -6,9 +6,13 @@ import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
 import {
   cleanOpenVikingRequestHeaders,
-  resolveOpenVikingRequestHeaders,
   type OpenVikingRequestHeaders,
 } from "../request-headers.js";
+import {
+  createSetupNetworkProbes,
+  type SetupApiKeyProbeResult,
+  type SetupHealthResult,
+} from "../services/setup/probe-service.js";
 
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
@@ -269,14 +273,7 @@ function ask(rl: readline.Interface, prompt: string, defaultValue = ""): Promise
 
 type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
 
-type HealthResult = {
-  ok: boolean;
-  version: string;
-  error: string;
-  compatibility: VersionCompatibility;
-  pluginVersion: string;
-  compatRange: string;
-};
+type HealthResult = SetupHealthResult;
 
 function parseVersionTuple(v: string): number[] | null {
   const cleaned = v.replace(/^v/i, "").split("-")[0];
@@ -317,132 +314,13 @@ function formatCompatRange(): string {
   return "any";
 }
 
-type ApiKeyProbeResult = {
-  keyType: "user_key" | "root_key" | "no_key" | "unknown";
-  needsAccountId: boolean;
-  needsUserId: boolean;
-  detail: string;
-};
-
-async function probeApiKeyType(
-  baseUrl: string,
-  apiKey?: string,
-  configuredHeaders?: OpenVikingRequestHeaders,
-): Promise<ApiKeyProbeResult> {
-  if (!apiKey) return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
-
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 10_000);
-  const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
-  try {
-    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-    const headers: Record<string, string> = {};
-    headers["X-API-Key"] = apiKey;
-    Object.assign(headers, configuredRequestHeaders);
-    const response = await fetch(sessionsUrl, {
-      headers,
-      signal: controller.signal,
-    });
-
-    if (response.ok) {
-      return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
-    }
-
-    // Server raises InvalidArgumentError (-> HTTP 400) when a ROOT key calls
-    // tenant-scoped endpoints without X-OpenViking-Account / X-OpenViking-User.
-    // 401/403 may also be returned by older versions, FastAPI validation can
-    // surface as 422. Treat all four as candidates for tenant-context errors.
-    if ([400, 401, 403, 422].includes(response.status)) {
-      let body = "";
-      try {
-        body = await response.text();
-      } catch { /* ignore parse errors */ }
-      const lower = body.toLowerCase();
-      const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
-      const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
-      if (needsAccount || needsUser) {
-        return {
-          keyType: "root_key",
-          needsAccountId: needsAccount,
-          needsUserId: needsUser,
-          detail: body.slice(0, 200),
-        };
-      }
-
-      // Body did not name account/user/tenant explicitly (custom auth middleware,
-      // localized message, etc.). Re-probe with placeholder tenant headers; if
-      // the failure was due to missing tenant headers the response will change.
-      try {
-        const probeHeaders: Record<string, string> = {
-          "X-API-Key": apiKey,
-          "X-OpenViking-Account": "__probe__",
-          "X-OpenViking-User": "__probe__",
-          ...configuredRequestHeaders,
-        };
-        const probe2 = await fetch(sessionsUrl, {
-          headers: probeHeaders,
-          signal: controller.signal,
-        });
-        if (probe2.status !== response.status) {
-          return {
-            keyType: "root_key",
-            needsAccountId: true,
-            needsUserId: true,
-            detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
-          };
-        }
-      } catch { /* ignore probe errors, fall through to unknown */ }
-
-      if (response.status === 401 || response.status === 403) {
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
-      }
-      return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
-    }
-
-    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
-  } catch (err) {
-    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
+type ApiKeyProbeResult = SetupApiKeyProbeResult;
 
-async function checkServiceHealth(
-  baseUrl: string,
-  apiKey?: string,
-  configuredHeaders?: OpenVikingRequestHeaders,
-): Promise<HealthResult> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 10_000);
-  try {
-    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-    const headers: Record<string, string> = {};
-    if (apiKey) {
-      headers["X-API-Key"] = apiKey;
-    }
-    Object.assign(headers, configuredRequestHeaders);
-    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
-      headers,
-      signal: controller.signal,
-    });
-    if (response.ok) {
-      try {
-        const data = await response.json() as Record<string, unknown>;
-        const result = (data.result ?? data) as Record<string, unknown>;
-        const version = String(result.version ?? data.version ?? "");
-        const compatibility = checkVersionCompatibility(version);
-        return { ok: true, version, error: "", compatibility, pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-      } catch {
-        return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-      }
-    }
-    return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-  } catch (err) {
-    return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
+const setupProbes = createSetupNetworkProbes({
+  pluginVersion: PLUGIN_VERSION,
+  compatRange: formatCompatRange(),
+  checkVersionCompatibility,
+});
 
 function readOpenClawConfig(configPath: string): Record<string, unknown> {
   if (!fs.existsSync(configPath)) return {};
@@ -813,7 +691,7 @@ async function runRemoteCheck(
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
   const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey, headers);
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -847,7 +725,7 @@ async function setupNonInteractive(
     }
 
     // Phase 1: validate connectivity and key type BEFORE writing config
-    const health = await checkServiceHealth(baseUrl, apiKey);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);
 
     if (!health.ok && !allowOffline) {
       return {
@@ -860,7 +738,7 @@ async function setupNonInteractive(
       };
     }
 
-    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+    const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;
 
     if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
       const missing: string[] = [];
@@ -996,8 +874,8 @@ async function getStatus(configPath: string): Promise<StatusResult> {
   const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
   const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
-  const health = await checkServiceHealth(baseUrl, apiKey, headers);
-  const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
+  const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;
 
   const peerPrefix = resolveExistingPeerPrefix(existing);
   return {
@@ -1119,7 +997,7 @@ async function setupRemote(
 
   if (apiKey) {
     console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-    const probe = await probeApiKeyType(baseUrl, apiKey, headers);
+    const probe = await setupProbes.probeApiKeyType(baseUrl, apiKey, headers);
     if (probe.keyType === "root_key") {
       console.log(tr(zh,
         "  ⚠ Root API key detected. accountId and userId are required.",
@@ -1140,7 +1018,7 @@ async function setupRemote(
   console.log("");
 
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -1204,7 +1082,6 @@ export const __test__ = {
   checkVersionCompatibility,
   parseVersionTuple,
   compareVersions,
-  probeApiKeyType,
   ensureInstallRecord,
   findPluginPackageRoot,
   readCompatRangeFromManifest,

package/dist/commands/setup.js

@@ -4,7 +4,8 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
-import { cleanOpenVikingRequestHeaders, resolveOpenVikingRequestHeaders, } from "../request-headers.js";
+import { cleanOpenVikingRequestHeaders, } from "../request-headers.js";
+import { createSetupNetworkProbes, } from "../services/setup/probe-service.js";
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
 const DEFAULT_REMOTE_URL = "http://127.0.0.1:1933";
@@ -247,118 +248,11 @@ function formatCompatRange() {
         return `<= ${COMPATIBLE_SERVER_MAX}`;
     return "any";
 }
-async function probeApiKeyType(baseUrl, apiKey, configuredHeaders) {
-    if (!apiKey)
-        return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 10_000);
-    const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
-    try {
-        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-        const headers = {};
-        headers["X-API-Key"] = apiKey;
-        Object.assign(headers, configuredRequestHeaders);
-        const response = await fetch(sessionsUrl, {
-            headers,
-            signal: controller.signal,
-        });
-        if (response.ok) {
-            return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
-        }
-        // Server raises InvalidArgumentError (-> HTTP 400) when a ROOT key calls
-        // tenant-scoped endpoints without X-OpenViking-Account / X-OpenViking-User.
-        // 401/403 may also be returned by older versions, FastAPI validation can
-        // surface as 422. Treat all four as candidates for tenant-context errors.
-        if ([400, 401, 403, 422].includes(response.status)) {
-            let body = "";
-            try {
-                body = await response.text();
-            }
-            catch { /* ignore parse errors */ }
-            const lower = body.toLowerCase();
-            const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
-            const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
-            if (needsAccount || needsUser) {
-                return {
-                    keyType: "root_key",
-                    needsAccountId: needsAccount,
-                    needsUserId: needsUser,
-                    detail: body.slice(0, 200),
-                };
-            }
-            // Body did not name account/user/tenant explicitly (custom auth middleware,
-            // localized message, etc.). Re-probe with placeholder tenant headers; if
-            // the failure was due to missing tenant headers the response will change.
-            try {
-                const probeHeaders = {
-                    "X-API-Key": apiKey,
-                    "X-OpenViking-Account": "__probe__",
-                    "X-OpenViking-User": "__probe__",
-                    ...configuredRequestHeaders,
-                };
-                const probe2 = await fetch(sessionsUrl, {
-                    headers: probeHeaders,
-                    signal: controller.signal,
-                });
-                if (probe2.status !== response.status) {
-                    return {
-                        keyType: "root_key",
-                        needsAccountId: true,
-                        needsUserId: true,
-                        detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
-                    };
-                }
-            }
-            catch { /* ignore probe errors, fall through to unknown */ }
-            if (response.status === 401 || response.status === 403) {
-                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
-            }
-            return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
-        }
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
-    }
-    catch (err) {
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-async function checkServiceHealth(baseUrl, apiKey, configuredHeaders) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 10_000);
-    try {
-        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-        const headers = {};
-        if (apiKey) {
-            headers["X-API-Key"] = apiKey;
-        }
-        Object.assign(headers, configuredRequestHeaders);
-        const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
-            headers,
-            signal: controller.signal,
-        });
-        if (response.ok) {
-            try {
-                const data = await response.json();
-                const result = (data.result ?? data);
-                const version = String(result.version ?? data.version ?? "");
-                const compatibility = checkVersionCompatibility(version);
-                return { ok: true, version, error: "", compatibility, pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-            }
-            catch {
-                return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-            }
-        }
-        return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-    }
-    catch (err) {
-        return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
+const setupProbes = createSetupNetworkProbes({
+    pluginVersion: PLUGIN_VERSION,
+    compatRange: formatCompatRange(),
+    checkVersionCompatibility,
+});
 function readOpenClawConfig(configPath) {
     if (!fs.existsSync(configPath))
         return {};
@@ -624,7 +518,7 @@ async function runRemoteCheck(zh, existing) {
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
     const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey, headers);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -644,7 +538,7 @@ async function setupNonInteractive(configPath, params) {
             throw new Error("peer_prefix may only contain letters, digits, underscores, and hyphens, or be empty");
         }
         // Phase 1: validate connectivity and key type BEFORE writing config
-        const health = await checkServiceHealth(baseUrl, apiKey);
+        const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);
         if (!health.ok && !allowOffline) {
             return {
                 success: false,
@@ -655,7 +549,7 @@ async function setupNonInteractive(configPath, params) {
                 error: `Server unreachable: ${health.error}. Use --allow-offline to save config anyway.`,
             };
         }
-        const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+        const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;
         if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
             const missing = [];
             if (!accountId)
@@ -793,8 +687,8 @@ async function getStatus(configPath) {
     const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
     const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
-    const health = await checkServiceHealth(baseUrl, apiKey, headers);
-    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
+    const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;
     const peerPrefix = resolveExistingPeerPrefix(existing);
     return {
         configured: true,
@@ -887,7 +781,7 @@ async function setupRemote(zh, configPath, existing, q) {
     let userId = existing?.userId ? String(existing.userId) : "";
     if (apiKey) {
         console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-        const probe = await probeApiKeyType(baseUrl, apiKey, headers);
+        const probe = await setupProbes.probeApiKeyType(baseUrl, apiKey, headers);
         if (probe.keyType === "root_key") {
             console.log(tr(zh, "  ⚠ Root API key detected. accountId and userId are required.", "  ⚠ 检测到 Root API Key，需要提供 accountId 和 userId。"));
             accountId = await q(tr(zh, "Account ID (required for root key)", "Account ID（root key 必填）"), accountId);
@@ -903,7 +797,7 @@ async function setupRemote(zh, configPath, existing, q) {
         : "";
     console.log("");
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -969,7 +863,6 @@ export const __test__ = {
     checkVersionCompatibility,
     parseVersionTuple,
     compareVersions,
-    probeApiKeyType,
     ensureInstallRecord,
     findPluginPackageRoot,
     readCompatRangeFromManifest,

package/dist/recall-trace.js

@@ -1,63 +1,5 @@
 import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
-const ALLOWED_RESOURCE_TYPES = ["resource", "user", "agent"];
-const DEFAULT_RESOURCE_TYPES = ["user", "agent"];
-function toResourceTypeEntries(value) {
-    if (Array.isArray(value)) {
-        return value
-            .filter((entry) => typeof entry === "string")
-            .map((entry) => entry.trim())
-            .filter(Boolean);
-    }
-    if (typeof value === "string") {
-        return value
-            .split(/[,\n]/)
-            .map((entry) => entry.trim())
-            .filter(Boolean);
-    }
-    return [];
-}
-export function normalizeResourceTypes(value) {
-    const entries = toResourceTypeEntries(value);
-    if (entries.length === 0) {
-        return [...DEFAULT_RESOURCE_TYPES];
-    }
-    const seen = new Set();
-    const normalized = [];
-    const invalid = [];
-    for (const entry of entries) {
-        if (ALLOWED_RESOURCE_TYPES.includes(entry)) {
-            const typed = entry;
-            if (!seen.has(typed)) {
-                seen.add(typed);
-                normalized.push(typed);
-            }
-        }
-        else {
-            invalid.push(entry);
-        }
-    }
-    if (invalid.length > 0) {
-        throw new Error(`invalid resourceTypes: ${invalid.join(", ")}`);
-    }
-    return normalized.length > 0 ? normalized : [...DEFAULT_RESOURCE_TYPES];
-}
-export function resolveRecallSearchPlan(resourceTypes, _ctx) {
-    const normalized = normalizeResourceTypes(resourceTypes);
-    const searches = [];
-    const skipped = [];
-    let addedMemorySearch = false;
-    for (const resourceType of normalized) {
-        if (resourceType === "resource") {
-            searches.push({ resourceType, contextType: "resource" });
-        }
-        else if ((resourceType === "user" || resourceType === "agent") && !addedMemorySearch) {
-            searches.push({ resourceType: "user", contextType: "memory" });
-            addedMemorySearch = true;
-        }
-    }
-    return { resourceTypes: normalized, searches, skipped };
-}
 export class RecallTraceMemoryStore {
     maxEntries;
     entries = [];

package/dist/services/setup/probe-service.js

@@ -0,0 +1,112 @@
+import { resolveOpenVikingRequestHeaders, } from "../../request-headers.js";
+export const defaultSetupNetworkTransport = (url, init) => fetch(url, init);
+export function createSetupNetworkProbes({ pluginVersion, compatRange, checkVersionCompatibility, transport = defaultSetupNetworkTransport, timeoutMs = 10_000, }) {
+    return {
+        async probeApiKeyType(baseUrl, apiKey, configuredHeaders) {
+            if (!apiKey) {
+                return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
+            }
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
+            try {
+                const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+                const headers = {};
+                headers["X-API-Key"] = apiKey;
+                Object.assign(headers, configuredRequestHeaders);
+                const response = await transport(sessionsUrl, {
+                    headers,
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
+                }
+                if ([400, 401, 403, 422].includes(response.status)) {
+                    let body = "";
+                    try {
+                        body = await response.text();
+                    }
+                    catch { /* ignore parse errors */ }
+                    const lower = body.toLowerCase();
+                    const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
+                    const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
+                    if (needsAccount || needsUser) {
+                        return {
+                            keyType: "root_key",
+                            needsAccountId: needsAccount,
+                            needsUserId: needsUser,
+                            detail: body.slice(0, 200),
+                        };
+                    }
+                    try {
+                        const probeHeaders = {
+                            "X-API-Key": apiKey,
+                            "X-OpenViking-Account": "__probe__",
+                            "X-OpenViking-User": "__probe__",
+                            ...configuredRequestHeaders,
+                        };
+                        const probe2 = await transport(sessionsUrl, {
+                            headers: probeHeaders,
+                            signal: controller.signal,
+                        });
+                        if (probe2.status !== response.status) {
+                            return {
+                                keyType: "root_key",
+                                needsAccountId: true,
+                                needsUserId: true,
+                                detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
+                            };
+                        }
+                    }
+                    catch { /* ignore probe errors, fall through to unknown */ }
+                    if (response.status === 401 || response.status === 403) {
+                        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
+                    }
+                    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
+                }
+                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
+            }
+            catch (err) {
+                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        },
+        async checkServiceHealth(baseUrl, apiKey, configuredHeaders) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+                const headers = {};
+                if (apiKey) {
+                    headers["X-API-Key"] = apiKey;
+                }
+                Object.assign(headers, configuredRequestHeaders);
+                const response = await transport(`${baseUrl.replace(/\/+$/, "")}/health`, {
+                    headers,
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    try {
+                        const data = await response.json();
+                        const result = (data.result ?? data);
+                        const version = String(result.version ?? data.version ?? "");
+                        const compatibility = checkVersionCompatibility(version);
+                        return { ok: true, version, error: "", compatibility, pluginVersion, compatRange };
+                    }
+                    catch {
+                        return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion, compatRange };
+                    }
+                }
+                return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion, compatRange };
+            }
+            catch (err) {
+                return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion, compatRange };
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        },
+    };
+}

package/dist/shared/recall-compress-core.mjs

@@ -83,11 +83,21 @@ export function repairDigestUris(digest, validUris = []) {
             lines.push(line);
             continue;
         }
+        let tokenized = line;
+        for (const uri of [...valid].sort((a, b) => b.length - a.length)) {
+            if (/\s/.test(uri))
+                tokenized = tokenized.split(uri).join(encodeURI(uri));
+        }
         let dropped = false;
-        const repaired = line.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
-            if (validSet.has(uri))
-                return uri;
-            const nearest = nearestUri(uri, valid);
+        const repaired = tokenized.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
+            let decoded = uri;
+            try {
+                decoded = decodeURI(uri);
+            }
+            catch { /* keep the original candidate */ }
+            if (validSet.has(decoded))
+                return decoded;
+            const nearest = nearestUri(decoded, valid);
             if (nearest)
                 return nearest;
             dropped = true;
@@ -146,13 +156,14 @@ async function writeCache(path, value) {
     }
     catch { /* best effort */ }
 }
-export async function compressRecallContext({ query, rendered, entries = [], cfg = {}, runCompressor, cachePath = "", now = 0, }) {
+export async function compressRecallContext({ query, rendered, shortContext = rendered, entries = [], cfg = {}, runCompressor, cachePath = "", now = 0, }) {
     const input = String(rendered || "").trim();
     if (!input)
         return { status: COMPRESS_EMPTY, context: "" };
     const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));
-    if (input.length < minChars)
-        return { status: COMPRESS_OK, context: input };
+    if (input.length < minChars) {
+        return { status: COMPRESS_OK, context: String(shortContext ?? input).trim() };
+    }
     const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
     const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));
     const key = recallDigestCacheKey({
@@ -164,7 +175,9 @@ export async function compressRecallContext({ query, rendered, entries = [], cfg
     });
     const cached = await readCache(cachePath);
     if (cached?.key === key && typeof cached.digest === "string") {
-        return { status: COMPRESS_OK, context: cached.digest };
+        const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);
+        if (digest)
+            return { status: COMPRESS_OK, context: digest };
     }
     const prompt = buildRecallCompressionPrompt({
         query,
@@ -178,9 +191,10 @@ export async function compressRecallContext({ query, rendered, entries = [], cfg
     if (!normalized)
         return { status: COMPRESS_EMPTY, context: "" };
     const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
-    const digest = repairDigestUris(normalized, validUris.length
+    const repaired = repairDigestUris(normalized, validUris.length
         ? validUris
         : (input.match(/viking:\/\/[^\s<>"']+/g) || []));
+    const digest = normalizeCompressedContext(repaired, 4000, maxBullets);
     if (!digest)
         return { status: COMPRESS_FAILED, context: "" };
     await writeCache(cachePath, { key, digest, updatedAt: now || 0 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.9.8",
+  "version": "2026.9.9",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",

package/recall-trace.ts

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
 
-export type RecallResourceType = "resource" | "session" | "user" | "agent";
+import type { RecallResourceType } from "./registries/recall-resource-types.js";
 
 export type RecallTraceSource = "auto_recall" | "memory_recall" | "ov_search" | "ov_archive_search";
 
@@ -27,7 +27,9 @@ export type RecallTraceEntry = {
   agentId?: string;
   source: RecallTraceSource;
   operationType: RecallTraceOperationType;
-  resourceTypes: RecallResourceType[];
+  // "session" labels archive-grep traces over session history; recall targets
+  // stay in the registry's narrower union and never include it.
+  resourceTypes: Array<RecallResourceType | "session">;
   trigger: {
     rawUserTextPreview?: string;
     query: string;
@@ -92,78 +94,6 @@ export type RecallTraceFlushResult = {
   warnings: string[];
 };
 
-const ALLOWED_RESOURCE_TYPES: RecallResourceType[] = ["resource", "user", "agent"];
-const DEFAULT_RESOURCE_TYPES: RecallResourceType[] = ["user", "agent"];
-
-function toResourceTypeEntries(value: unknown): string[] {
-  if (Array.isArray(value)) {
-    return value
-      .filter((entry): entry is string => typeof entry === "string")
-      .map((entry) => entry.trim())
-      .filter(Boolean);
-  }
-  if (typeof value === "string") {
-    return value
-      .split(/[,\n]/)
-      .map((entry) => entry.trim())
-      .filter(Boolean);
-  }
-  return [];
-}
-
-export function normalizeResourceTypes(value: unknown): RecallResourceType[] {
-  const entries = toResourceTypeEntries(value);
-  if (entries.length === 0) {
-    return [...DEFAULT_RESOURCE_TYPES];
-  }
-
-  const seen = new Set<RecallResourceType>();
-  const normalized: RecallResourceType[] = [];
-  const invalid: string[] = [];
-  for (const entry of entries) {
-    if ((ALLOWED_RESOURCE_TYPES as string[]).includes(entry)) {
-      const typed = entry as RecallResourceType;
-      if (!seen.has(typed)) {
-        seen.add(typed);
-        normalized.push(typed);
-      }
-    } else {
-      invalid.push(entry);
-    }
-  }
-
-  if (invalid.length > 0) {
-    throw new Error(`invalid resourceTypes: ${invalid.join(", ")}`);
-  }
-
-  return normalized.length > 0 ? normalized : [...DEFAULT_RESOURCE_TYPES];
-}
-
-export function resolveRecallSearchPlan(
-  resourceTypes: unknown,
-  _ctx: { ovSessionId?: string; agentId?: string },
-): {
-  resourceTypes: RecallResourceType[];
-  searches: Array<{ resourceType: RecallResourceType; targetUri?: string; contextType: "memory" | "resource" }>;
-  skipped: Array<{ resourceType: RecallResourceType; reason: "missing_session" }>;
-} {
-  const normalized = normalizeResourceTypes(resourceTypes);
-  const searches: Array<{ resourceType: RecallResourceType; targetUri?: string; contextType: "memory" | "resource" }> = [];
-  const skipped: Array<{ resourceType: RecallResourceType; reason: "missing_session" }> = [];
-  let addedMemorySearch = false;
-
-  for (const resourceType of normalized) {
-    if (resourceType === "resource") {
-      searches.push({ resourceType, contextType: "resource" });
-    } else if ((resourceType === "user" || resourceType === "agent") && !addedMemorySearch) {
-      searches.push({ resourceType: "user", contextType: "memory" });
-      addedMemorySearch = true;
-    }
-  }
-
-  return { resourceTypes: normalized, searches, skipped };
-}
-
 export class RecallTraceMemoryStore {
   private readonly maxEntries: number;
   private readonly entries: RecallTraceEntry[] = [];
@@ -183,7 +113,7 @@ export class RecallTraceMemoryStore {
     const limit = Math.max(1, Math.floor(query.limit ?? 20));
     const turn = query.turn ?? "latest";
     const resourceTypes = query.resourceTypes && query.resourceTypes.length > 0
-      ? new Set(query.resourceTypes)
+      ? new Set<string>(query.resourceTypes)
       : undefined;
 
     const filtered = this.entries

package/shared/recall-compress-core.mjs

@@ -86,10 +86,16 @@ export function repairDigestUris(digest, validUris = []) {
       lines.push(line);
       continue;
     }
+    let tokenized = line;
+    for (const uri of [...valid].sort((a, b) => b.length - a.length)) {
+      if (/\s/.test(uri)) tokenized = tokenized.split(uri).join(encodeURI(uri));
+    }
     let dropped = false;
-    const repaired = line.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
-      if (validSet.has(uri)) return uri;
-      const nearest = nearestUri(uri, valid);
+    const repaired = tokenized.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
+      let decoded = uri;
+      try { decoded = decodeURI(uri); } catch { /* keep the original candidate */ }
+      if (validSet.has(decoded)) return decoded;
+      const nearest = nearestUri(decoded, valid);
       if (nearest) return nearest;
       dropped = true;
       return uri;
@@ -149,6 +155,7 @@ async function writeCache(path, value) {
 export async function compressRecallContext({
   query,
   rendered,
+  shortContext = rendered,
   entries = [],
   cfg = {},
   runCompressor,
@@ -158,7 +165,9 @@ export async function compressRecallContext({
   const input = String(rendered || "").trim();
   if (!input) return { status: COMPRESS_EMPTY, context: "" };
   const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));
-  if (input.length < minChars) return { status: COMPRESS_OK, context: input };
+  if (input.length < minChars) {
+    return { status: COMPRESS_OK, context: String(shortContext ?? input).trim() };
+  }
 
   const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
   const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));
@@ -171,7 +180,8 @@ export async function compressRecallContext({
   });
   const cached = await readCache(cachePath);
   if (cached?.key === key && typeof cached.digest === "string") {
-    return { status: COMPRESS_OK, context: cached.digest };
+    const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);
+    if (digest) return { status: COMPRESS_OK, context: digest };
   }
 
   const prompt = buildRecallCompressionPrompt({
@@ -185,9 +195,10 @@ export async function compressRecallContext({
   if (!normalized) return { status: COMPRESS_EMPTY, context: "" };
 
   const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
-  const digest = repairDigestUris(normalized, validUris.length
+  const repaired = repairDigestUris(normalized, validUris.length
     ? validUris
     : (input.match(/viking:\/\/[^\s<>"']+/g) || []));
+  const digest = normalizeCompressedContext(repaired, 4000, maxBullets);
   if (!digest) return { status: COMPRESS_FAILED, context: "" };
 
   await writeCache(cachePath, { key, digest, updatedAt: now || 0 });

package/skills/ov-experience-memory/SKILL.md

@@ -55,7 +55,8 @@ context or deeper intent analysis is useful.
 
    For tools using MCP-style parameters, set `target_uri` to this root. For
    OpenClaw `ov_search`, set `uri` to this root. Never hardcode `default`,
-   `test`, or another user ID.
+   `test`, or another user ID. If the server rejects the URI, resolve the root
+   as described in *Servers Without the Home Alias* and retry once.
 4. Start with `limit=5` and the tool's normal score threshold. Judge results by
    task, environment, preconditions, and likely effect; title similarity alone
    is insufficient. If no result is relevant, continue without Experience and
@@ -73,6 +74,26 @@ context or deeper intent analysis is useful.
    follow-up search using the failure evidence, then read only newly relevant
    Experience files.
 
+## Servers Without the Home Alias
+
+`viking://~` is the home alias for the caller's own space. A server released
+before the alias (OpenViking v0.4.16) does not resolve it and rejects the
+request with `INVALID_URI` (HTTP 400) instead of searching. Retry once against
+the caller's explicit root, resolved from evidence rather than guessed:
+
+- If a canonical `viking://user/<user_id>/...` URI is already visible in this
+  session — injected memory context, or an earlier OpenViking tool result —
+  reuse that `<user_id>` and search
+  `viking://user/<user_id>/memories/experiences`.
+- Otherwise repeat the same query with no target scope, narrowed to memories
+  with `context_type` when the tool accepts it, and keep only hits whose URI
+  contains `/memories/experiences/`. Those hits carry the canonical user ID;
+  reuse it for the reads and for any later Experience search in this task.
+
+Do not fall back to the uid-less `viking://user/memories/experiences`: only
+some older servers and roles expand it, and current servers reject it. If no
+explicit root can be resolved, continue without Experience.
+
 ## Applying Retrieved Experience
 
 - Treat Experience as reusable procedure, not as a user profile, user intent,