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

package/services/setup/probe-service.ts

@@ -0,0 +1,143 @@
+export type SetupNetworkTransport = (url: string, init: RequestInit) => Promise<Response>;
+
+export type SetupVersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
+
+export type SetupHealthResult = {
+  ok: boolean;
+  version: string;
+  error: string;
+  compatibility: SetupVersionCompatibility;
+  pluginVersion: string;
+  compatRange: string;
+};
+
+export type SetupApiKeyProbeResult = {
+  keyType: "user_key" | "root_key" | "no_key" | "unknown";
+  needsAccountId: boolean;
+  needsUserId: boolean;
+  detail: string;
+};
+
+export type SetupNetworkProbeOptions = {
+  pluginVersion: string;
+  compatRange: string;
+  checkVersionCompatibility: (serverVersion: string) => SetupVersionCompatibility;
+  transport?: SetupNetworkTransport;
+  timeoutMs?: number;
+};
+
+export type SetupNetworkProbes = {
+  probeApiKeyType: (baseUrl: string, apiKey?: string) => Promise<SetupApiKeyProbeResult>;
+  checkServiceHealth: (baseUrl: string, apiKey?: string) => Promise<SetupHealthResult>;
+};
+
+export const defaultSetupNetworkTransport: SetupNetworkTransport = (url, init) => fetch(url, init);
+
+export function createSetupNetworkProbes({
+  pluginVersion,
+  compatRange,
+  checkVersionCompatibility,
+  transport = defaultSetupNetworkTransport,
+  timeoutMs = 10_000,
+}: SetupNetworkProbeOptions): SetupNetworkProbes {
+  return {
+    async probeApiKeyType(baseUrl: string, apiKey?: string): Promise<SetupApiKeyProbeResult> {
+      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 headers: Record<string, string> = { "X-API-Key": apiKey };
+        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: Record<string, string> = {
+              "X-API-Key": apiKey,
+              "X-OpenViking-Account": "__probe__",
+              "X-OpenViking-User": "__probe__",
+            };
+            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: string, apiKey?: string): Promise<SetupHealthResult> {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const headers: Record<string, string> = {};
+        if (apiKey) headers["X-API-Key"] = apiKey;
+        const response = await transport(`${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, 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/services/setup/setup-flow.ts

@@ -0,0 +1,306 @@
+import {
+  activateContextEngineSlot,
+  getExistingPluginConfig,
+  isContextEngineSlotActive,
+  writeOpenVikingConfig,
+  type SetupIO,
+  type SlotActivationResult,
+} from "./config-writer.js";
+
+export type { SetupIO, SlotActivationResult };
+
+export type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
+
+export type HealthResult = {
+  ok: boolean;
+  version: string;
+  error: string;
+  compatibility: VersionCompatibility;
+  pluginVersion: string;
+  compatRange: string;
+};
+
+export type ApiKeyProbeResult = {
+  keyType: "user_key" | "root_key" | "no_key" | "unknown";
+  needsAccountId: boolean;
+  needsUserId: boolean;
+  detail: string;
+};
+
+export type SetupResult = {
+  success: boolean;
+  action: "configured" | "existing" | "error" | "slot_blocked";
+  config?: {
+    mode: string;
+    baseUrl: string;
+    apiKey?: string;
+    peer_role?: "none" | "assistant" | "person";
+    peer_prefix?: string;
+    accountId?: string;
+    userId?: string;
+    recallTargetTypes?: string[];
+  };
+  health?: HealthResult;
+  keyProbe?: ApiKeyProbeResult;
+  slot: SlotActivationResult;
+  error?: string;
+};
+
+export type StatusResult = {
+  configured: boolean;
+  config?: {
+    mode: string;
+    baseUrl: string;
+    hasApiKey: boolean;
+    peer_role?: "none" | "assistant" | "person";
+    peer_prefix?: string;
+    hasAccountId: boolean;
+    hasUserId: boolean;
+  };
+  health?: HealthResult;
+  keyProbe?: ApiKeyProbeResult;
+  slotActive: boolean;
+};
+
+export type SetupParams = {
+  baseUrl: string;
+  apiKey?: string;
+  peerRole?: "none" | "assistant" | "person";
+  peerPrefix?: string;
+  accountId?: string;
+  userId?: string;
+  recallTargetTypes?: string[];
+  allowOffline?: boolean;
+  forceSlot?: boolean;
+};
+
+export type InteractiveRemoteConfigParams = {
+  existing?: Record<string, unknown> | null;
+  baseUrl: string;
+  apiKey?: string;
+  peerRole?: "none" | "assistant" | "person";
+  peerPrefix?: string;
+  accountId?: string;
+  userId?: string;
+  forceSlot?: boolean;
+};
+
+export type InteractiveRemoteConfigResult = {
+  config: Record<string, unknown>;
+  slot: SlotActivationResult;
+};
+
+export type OpenVikingSetupService = {
+  setupNonInteractive: (configPath: string, params: SetupParams) => Promise<SetupResult>;
+  saveInteractiveRemoteConfig: (configPath: string, params: InteractiveRemoteConfigParams) => Promise<InteractiveRemoteConfigResult>;
+  useExistingRemoteConfig: (configPath: string, existing: Record<string, unknown>) => Promise<SetupResult>;
+  getStatus: (configPath: string) => Promise<StatusResult>;
+};
+
+export type OpenVikingSetupServiceDependencies = {
+  io: SetupIO;
+  defaultRemoteUrl?: string;
+  checkServiceHealth: (baseUrl: string, apiKey?: string) => Promise<HealthResult>;
+  probeApiKeyType: (baseUrl: string, apiKey?: string) => Promise<ApiKeyProbeResult>;
+};
+
+export function maskKey(key: string): string {
+  if (key.length <= 8) return "****";
+  return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+
+export function isLegacyLocalMode(existing: Record<string, unknown>): boolean {
+  const mode = existing.mode;
+  return mode !== "remote";
+}
+
+export function buildInteractiveRemotePluginConfig({
+  existing,
+  baseUrl,
+  apiKey,
+  peerRole,
+  peerPrefix,
+  accountId,
+  userId,
+}: InteractiveRemoteConfigParams): Record<string, unknown> {
+  const pluginCfg: Record<string, unknown> = {
+    ...(existing ?? {}),
+    mode: "remote",
+    baseUrl,
+  };
+  if (apiKey) pluginCfg.apiKey = apiKey;
+  else delete pluginCfg.apiKey;
+  if (peerRole) pluginCfg.peer_role = peerRole;
+  else delete pluginCfg.peer_role;
+  if (peerPrefix) pluginCfg.peer_prefix = peerPrefix;
+  else delete pluginCfg.peer_prefix;
+  if (accountId) pluginCfg.accountId = accountId;
+  else delete pluginCfg.accountId;
+  if (userId) pluginCfg.userId = userId;
+  else delete pluginCfg.userId;
+  delete pluginCfg.configPath;
+  delete pluginCfg.port;
+  return pluginCfg;
+}
+
+export function createOpenVikingSetupService({
+  io,
+  defaultRemoteUrl = "http://127.0.0.1:1933",
+  checkServiceHealth,
+  probeApiKeyType,
+}: OpenVikingSetupServiceDependencies): OpenVikingSetupService {
+  return {
+    async setupNonInteractive(configPath: string, params: SetupParams): Promise<SetupResult> {
+      try {
+        const { baseUrl, apiKey, peerRole, peerPrefix, accountId, userId, recallTargetTypes, allowOffline, forceSlot } = params;
+
+        const health = await checkServiceHealth(baseUrl, apiKey);
+
+        if (!health.ok && !allowOffline) {
+          return {
+            success: false,
+            action: "error",
+            config: { mode: "remote", baseUrl },
+            health,
+            slot: { activated: false, replaced: false },
+            error: `Server unreachable: ${health.error}. Use --allow-offline to save config anyway.`,
+          };
+        }
+
+        const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+
+        if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
+          const missing: string[] = [];
+          if (!accountId) missing.push("--account-id");
+          if (!userId) missing.push("--user-id");
+          return {
+            success: false,
+            action: "error",
+            config: {
+              mode: "remote",
+              baseUrl,
+              ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
+            },
+            health,
+            keyProbe,
+            slot: { activated: false, replaced: false },
+            error: `Root API key detected. Missing: ${missing.join(", ")}. Re-run with: ${missing.map(f => `${f} <value>`).join(" ")}`,
+          };
+        }
+
+        const pluginCfg: Record<string, unknown> = { mode: "remote", baseUrl };
+        if (apiKey) pluginCfg.apiKey = apiKey;
+        if (peerRole) pluginCfg.peer_role = peerRole;
+        if (peerPrefix) pluginCfg.peer_prefix = peerPrefix;
+        if (accountId) pluginCfg.accountId = accountId;
+        if (userId) pluginCfg.userId = userId;
+        if (recallTargetTypes && recallTargetTypes.length > 0) pluginCfg.recallTargetTypes = recallTargetTypes;
+
+        writeOpenVikingConfig(configPath, pluginCfg, io);
+        const slot = activateContextEngineSlot(configPath, !!forceSlot, io);
+
+        const resultConfig = {
+          mode: "remote",
+          baseUrl,
+          ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
+          ...(peerRole ? { peer_role: peerRole } : {}),
+          ...(peerPrefix ? { peer_prefix: peerPrefix } : {}),
+          ...(accountId ? { accountId } : {}),
+          ...(userId ? { userId } : {}),
+          ...(recallTargetTypes && recallTargetTypes.length > 0 ? { recallTargetTypes } : {}),
+        };
+
+        if (!slot.activated && slot.previousOwner) {
+          return {
+            success: false,
+            action: "slot_blocked",
+            config: resultConfig,
+            health,
+            keyProbe,
+            slot,
+            error: `contextEngine slot is owned by "${slot.previousOwner}". Config was saved but slot was NOT changed. Use --force-slot to replace.`,
+          };
+        }
+
+        return {
+          success: true,
+          action: "configured",
+          config: resultConfig,
+          health,
+          keyProbe,
+          slot,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          action: "error",
+          slot: { activated: false, replaced: false },
+          error: String(err instanceof Error ? err.message : err),
+        };
+      }
+    },
+
+    async saveInteractiveRemoteConfig(
+      configPath: string,
+      params: InteractiveRemoteConfigParams,
+    ): Promise<InteractiveRemoteConfigResult> {
+      const pluginCfg = buildInteractiveRemotePluginConfig(params);
+      writeOpenVikingConfig(configPath, pluginCfg, io);
+      const slot = activateContextEngineSlot(configPath, !!params.forceSlot, io);
+      return { config: pluginCfg, slot };
+    },
+
+    async useExistingRemoteConfig(configPath: string, existing: Record<string, unknown>): Promise<SetupResult> {
+      const baseUrl = String(existing.baseUrl ?? defaultRemoteUrl);
+      const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
+      const health = await checkServiceHealth(baseUrl, apiKey);
+      const slot = activateContextEngineSlot(configPath, false, io);
+      return {
+        success: true,
+        action: "existing",
+        config: {
+          mode: String(existing.mode ?? "remote"),
+          baseUrl,
+          ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
+          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as "none" | "assistant" | "person" } : {}),
+          ...(existing.peer_prefix ? { peer_prefix: String(existing.peer_prefix) } : {}),
+          ...(existing.accountId ? { accountId: String(existing.accountId) } : {}),
+          ...(existing.userId ? { userId: String(existing.userId) } : {}),
+        },
+        health,
+        slot,
+      };
+    },
+
+    async getStatus(configPath: string): Promise<StatusResult> {
+      const config = io.readConfig(configPath);
+      const existing = getExistingPluginConfig(config);
+      const slotActive = isContextEngineSlotActive(configPath, io);
+
+      if (!existing) {
+        return { configured: false, slotActive };
+      }
+
+      const baseUrl = String(existing.baseUrl ?? defaultRemoteUrl);
+      const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
+      const health = await checkServiceHealth(baseUrl, apiKey);
+      const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+
+      return {
+        configured: true,
+        config: {
+          mode: String(existing.mode ?? "remote"),
+          baseUrl,
+          hasApiKey: !!existing.apiKey,
+          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as "none" | "assistant" | "person" } : {}),
+          ...(existing.peer_prefix ? { peer_prefix: String(existing.peer_prefix) } : {}),
+          hasAccountId: !!existing.accountId,
+          hasUserId: !!existing.userId,
+        },
+        health,
+        keyProbe,
+        slotActive,
+      };
+    },
+  };
+}

package/services/setup/version-compatibility.ts

@@ -0,0 +1,41 @@
+export type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
+
+export type VersionCompatibilityRange = {
+  min?: string;
+  max?: string;
+};
+
+export function parseVersionTuple(v: string): number[] | null {
+  const cleaned = v.replace(/^v/i, "").split("-")[0];
+  const parts = cleaned.split(".").map(Number);
+  if (parts.some(isNaN)) return null;
+  return parts;
+}
+
+export function compareVersions(a: number[], b: number[]): number {
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+export function checkVersionCompatibility(
+  serverVersion: string,
+  { min, max }: VersionCompatibilityRange,
+): VersionCompatibility {
+  if (!serverVersion) return "unknown";
+  const sv = parseVersionTuple(serverVersion);
+  if (!sv) return "unknown";
+
+  if (min) {
+    const minV = parseVersionTuple(min);
+    if (minV && compareVersions(sv, minV) < 0) return "server_too_old";
+  }
+  if (max) {
+    const maxV = parseVersionTuple(max);
+    if (maxV && compareVersions(sv, maxV) > 0) return "server_too_new";
+  }
+  return "compatible";
+}

package/session-transcript-repair.ts

@@ -191,8 +191,6 @@ function normalizeToolResultName(
   return message;
 }
 
-export { makeMissingToolResult };
-
 export type ToolCallInputRepairReport = {
   messages: AgentMessage[];
   droppedToolCalls: number;