@openviking/openclaw-plugin 2026.9.5 → 2026.9.8-2

package/client.ts

@@ -1,12 +1,3 @@
-import { randomUUID } from "node:crypto";
-import { once } from "node:events";
-import { createWriteStream } from "node:fs";
-import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
-
-import { Zip, ZipDeflate } from "fflate";
-
 import { defaultHttpTransport, type HttpTransport } from "./adapters/http-transport.js";
 import {
   defaultResourcePackager,
@@ -255,23 +246,6 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-const MEMORY_URI_PATTERNS = [
-  /^viking:\/\/user\/(?:[^/]+\/)?memories(?:\/|$)/,
-];
-const REMOTE_RESOURCE_PREFIXES = ["http://", "https://", "git@", "ssh://", "git://"];
-
-export function isMemoryUri(uri: string): boolean {
-  return MEMORY_URI_PATTERNS.some((pattern) => pattern.test(uri));
-}
-
-function isRemoteResourceSource(source: string): boolean {
-  return REMOTE_RESOURCE_PREFIXES.some((prefix) => source.startsWith(prefix));
-}
-
-function toBlobPart(value: Buffer): ArrayBuffer {
-  return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
-}
-
 function resolveWaitRequestTimeoutMs(defaultTimeoutMs: number, waitTimeoutSeconds?: number): number {
   const requestedMs =
     typeof waitTimeoutSeconds === "number" && Number.isFinite(waitTimeoutSeconds) && waitTimeoutSeconds > 0
@@ -280,14 +254,6 @@ function resolveWaitRequestTimeoutMs(defaultTimeoutMs: number, waitTimeoutSecond
   return Math.max(defaultTimeoutMs, requestedMs);
 }
 
-async function cleanupUploadTempPath(path?: string): Promise<void> {
-  if (!path) {
-    return;
-  }
-  await rm(path, { force: true }).catch(() => undefined);
-  await rm(dirname(path), { recursive: true, force: true }).catch(() => undefined);
-}
-
 export class OpenVikingClient {
   private readonly transport: HttpTransport;
   private readonly configuredHeaders: Record<string, string>;
@@ -685,63 +651,6 @@ export class OpenVikingClient {
     return result.temp_file_id;
   }
 
-  async zipDirectoryForUpload(dirPath: string): Promise<string> {
-    const rootStats = await stat(dirPath);
-    if (!rootStats.isDirectory()) {
-      throw new Error(`Not a directory: ${dirPath}`);
-    }
-
-    const zipDir = await mkdtemp(join(tmpdir(), "openviking-openclaw-upload-"));
-    const zipPath = join(zipDir, `${basename(dirPath).replace(/[^a-zA-Z0-9._-]/g, "_")}-${randomUUID()}.zip`);
-    const output = createWriteStream(zipPath);
-    const outputClosed = once(output, "close");
-    const outputErrored = once(output, "error").then(([err]) => Promise.reject(err));
-    const zip = new Zip((err, chunk, final) => {
-      if (err) {
-        output.destroy(err);
-        return;
-      }
-      if (chunk?.length) {
-        output.write(Buffer.from(chunk));
-      }
-      if (final) {
-        output.end();
-      }
-    });
-
-    const walk = async (currentDir: string) => {
-      const entries = await readdir(currentDir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = join(currentDir, entry.name);
-        if (entry.isDirectory()) {
-          await walk(fullPath);
-          continue;
-        }
-        if (!entry.isFile()) {
-          continue;
-        }
-        const relPath = relative(dirPath, fullPath).replace(/\\/g, "/");
-        if (!relPath || relPath.startsWith("../") || relPath.includes("/../")) {
-          throw new Error(`Unsafe relative path while zipping: ${relPath}`);
-        }
-        const file = new ZipDeflate(relPath);
-        zip.add(file);
-        file.push(new Uint8Array(await readFile(fullPath)), true);
-      }
-    };
-    try {
-      await walk(dirPath);
-      zip.end();
-      await Promise.race([outputClosed, outputErrored]);
-    } catch (err) {
-      zip.terminate();
-      output.destroy(err as Error);
-      await cleanupUploadTempPath(zipPath);
-      throw err;
-    }
-    return zipPath;
-  }
-
   async addResource(input: AddResourceInput, actorPeerId?: string): Promise<AddResourceResult> {
     const pathOrUrl = input.pathOrUrl.trim();
     if (!pathOrUrl) {

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/client.js

@@ -1,10 +1,3 @@
-import { randomUUID } from "node:crypto";
-import { once } from "node:events";
-import { createWriteStream } from "node:fs";
-import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
-import { Zip, ZipDeflate } from "fflate";
 import { defaultHttpTransport } from "./adapters/http-transport.js";
 import { defaultResourcePackager, } from "./adapters/resource-packager.js";
 import { buildContextSearchBody, contextRequestTimeoutMs, normalizeContextEntry, } from "./shared/recall-core.mjs";
@@ -17,32 +10,12 @@ const WAIT_REQUEST_TIMEOUT_BUFFER_MS = 5_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const MEMORY_URI_PATTERNS = [
-    /^viking:\/\/user\/(?:[^/]+\/)?memories(?:\/|$)/,
-];
-const REMOTE_RESOURCE_PREFIXES = ["http://", "https://", "git@", "ssh://", "git://"];
-export function isMemoryUri(uri) {
-    return MEMORY_URI_PATTERNS.some((pattern) => pattern.test(uri));
-}
-function isRemoteResourceSource(source) {
-    return REMOTE_RESOURCE_PREFIXES.some((prefix) => source.startsWith(prefix));
-}
-function toBlobPart(value) {
-    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
-}
 function resolveWaitRequestTimeoutMs(defaultTimeoutMs, waitTimeoutSeconds) {
     const requestedMs = typeof waitTimeoutSeconds === "number" && Number.isFinite(waitTimeoutSeconds) && waitTimeoutSeconds > 0
         ? Math.ceil(waitTimeoutSeconds * 1000) + WAIT_REQUEST_TIMEOUT_BUFFER_MS
         : DEFAULT_WAIT_REQUEST_TIMEOUT_MS;
     return Math.max(defaultTimeoutMs, requestedMs);
 }
-async function cleanupUploadTempPath(path) {
-    if (!path) {
-        return;
-    }
-    await rm(path, { force: true }).catch(() => undefined);
-    await rm(dirname(path), { recursive: true, force: true }).catch(() => undefined);
-}
 export class OpenVikingClient {
     baseUrl;
     apiKey;
@@ -323,61 +296,6 @@ export class OpenVikingClient {
         }
         return result.temp_file_id;
     }
-    async zipDirectoryForUpload(dirPath) {
-        const rootStats = await stat(dirPath);
-        if (!rootStats.isDirectory()) {
-            throw new Error(`Not a directory: ${dirPath}`);
-        }
-        const zipDir = await mkdtemp(join(tmpdir(), "openviking-openclaw-upload-"));
-        const zipPath = join(zipDir, `${basename(dirPath).replace(/[^a-zA-Z0-9._-]/g, "_")}-${randomUUID()}.zip`);
-        const output = createWriteStream(zipPath);
-        const outputClosed = once(output, "close");
-        const outputErrored = once(output, "error").then(([err]) => Promise.reject(err));
-        const zip = new Zip((err, chunk, final) => {
-            if (err) {
-                output.destroy(err);
-                return;
-            }
-            if (chunk?.length) {
-                output.write(Buffer.from(chunk));
-            }
-            if (final) {
-                output.end();
-            }
-        });
-        const walk = async (currentDir) => {
-            const entries = await readdir(currentDir, { withFileTypes: true });
-            for (const entry of entries) {
-                const fullPath = join(currentDir, entry.name);
-                if (entry.isDirectory()) {
-                    await walk(fullPath);
-                    continue;
-                }
-                if (!entry.isFile()) {
-                    continue;
-                }
-                const relPath = relative(dirPath, fullPath).replace(/\\/g, "/");
-                if (!relPath || relPath.startsWith("../") || relPath.includes("/../")) {
-                    throw new Error(`Unsafe relative path while zipping: ${relPath}`);
-                }
-                const file = new ZipDeflate(relPath);
-                zip.add(file);
-                file.push(new Uint8Array(await readFile(fullPath)), true);
-            }
-        };
-        try {
-            await walk(dirPath);
-            zip.end();
-            await Promise.race([outputClosed, outputErrored]);
-        }
-        catch (err) {
-            zip.terminate();
-            output.destroy(err);
-            await cleanupUploadTempPath(zipPath);
-            throw err;
-        }
-        return zipPath;
-    }
     async addResource(input, actorPeerId) {
         const pathOrUrl = input.pathOrUrl.trim();
         if (!pathOrUrl) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.9.5",
+  "version": "2026.9.8-2",
   "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