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

package/plugin/openviking-feature-gates.ts

@@ -0,0 +1,335 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Type, type Static } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+export const OPENVIKING_260610_FEATURE = "openviking.260610";
+export const OPENVIKING_FEATURE_GATES_RPC = "openviking.feature.gates";
+
+const versionPattern = String.raw`^\d+\.\d+\.\d+(?:-(?:\d+|beta(?:\.\d+)?))?$`;
+
+const FeatureGateSchema = Type.Object(
+  {
+    enable: Type.Boolean(),
+    minPluginVersion: Type.String({ pattern: versionPattern }),
+    minOpenclawVersion: Type.String({ minLength: 1 }),
+    editions: Type.Array(Type.String({ minLength: 1 }), {
+      minItems: 1,
+      uniqueItems: true,
+    }),
+  },
+  { additionalProperties: false },
+);
+
+const FeatureGatesConfigSchema = Type.Object(
+  {
+    features: Type.Record(Type.String({ minLength: 1 }), FeatureGateSchema),
+  },
+  { additionalProperties: false },
+);
+
+type FeatureGatesConfig = Static<typeof FeatureGatesConfigSchema>;
+
+interface ParsedVersion {
+  year: number;
+  month: number;
+  day: number;
+  channelRank: number;
+  sequence: number;
+}
+
+export interface OpenVikingFeatureGateServiceOptions {
+  configPath?: string;
+  getPluginVersion?: () => string;
+  getOpenClawVersion?: () => Promise<string>;
+  getOpenClawVersionSync?: () => string;
+}
+
+export interface OpenVikingFeatureGateService {
+  getEnabledFeatureGates(edition?: string): Promise<string[]>;
+  isFeatureGateEnabled(featureName: string, edition?: string): Promise<boolean>;
+  isFeatureGateEnabledSync(featureName: string, edition?: string): boolean;
+}
+
+export interface OpenVikingFeatureGatesGatewayApi {
+  registerGatewayMethod?: (
+    name: string,
+    handler: (input: {
+      params?: unknown;
+      respond: (success: boolean, data: unknown) => void;
+    }) => void | Promise<void>,
+  ) => void;
+}
+
+function parseVersion(version: string): ParsedVersion | null {
+  const stableMatch = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(\d+))?$/);
+  if (stableMatch) {
+    return {
+      year: Number(stableMatch[1]),
+      month: Number(stableMatch[2]),
+      day: Number(stableMatch[3]),
+      channelRank: 1,
+      sequence: stableMatch[4] ? Number(stableMatch[4]) : 0,
+    };
+  }
+
+  const betaMatch = version.match(/^(\d+)\.(\d+)\.(\d+)-beta(?:\.(\d+))?$/);
+  if (betaMatch) {
+    return {
+      year: Number(betaMatch[1]),
+      month: Number(betaMatch[2]),
+      day: Number(betaMatch[3]),
+      channelRank: 0,
+      sequence: betaMatch[4] ? Number(betaMatch[4]) : 0,
+    };
+  }
+
+  return null;
+}
+
+export function isPluginVersionAtLeast(currentVersion: string, minVersion: string): boolean {
+  const current = parseVersion(currentVersion);
+  const minimum = parseVersion(minVersion);
+  if (!current || !minimum) {
+    return false;
+  }
+
+  if (current.year !== minimum.year) return current.year > minimum.year;
+  if (current.month !== minimum.month) return current.month > minimum.month;
+  if (current.day !== minimum.day) return current.day > minimum.day;
+  if (current.channelRank !== minimum.channelRank) {
+    return current.channelRank > minimum.channelRank;
+  }
+  return current.sequence >= minimum.sequence;
+}
+
+export function isOpenClawVersionAtLeast(currentVersion: string, minVersion: string): boolean {
+  return isPluginVersionAtLeast(currentVersion, minVersion);
+}
+
+function formatSchemaError(path: string, message: string): string {
+  const normalizedPath = path ? path.replace(/\//g, ".").replace(/^\./, "") : "$";
+  return `${normalizedPath}: ${message}`;
+}
+
+function parseFeatureGatesConfig(raw: string): FeatureGatesConfig {
+  const parsed = JSON.parse(raw) as unknown;
+  if (Value.Check(FeatureGatesConfigSchema, parsed)) {
+    return parsed;
+  }
+
+  const validationError = Value.Errors(FeatureGatesConfigSchema, parsed).First();
+  const errorMessage = validationError
+    ? formatSchemaError(validationError.path, validationError.message)
+    : "unknown validation error";
+  throw new Error(`Invalid feature-gates.json: ${errorMessage}`);
+}
+
+function normalizeFeatures(
+  features: FeatureGatesConfig["features"],
+  pluginVersion: string,
+  openclawVersion: string,
+  edition?: string,
+): string[] {
+  const requestedEdition = edition?.trim();
+  const businessCarriers = (process.env.BUSINESS_CARRIER ?? "")
+    .split(",")
+    .map((carrier) => carrier.trim())
+    .filter(Boolean);
+  const effectiveEditions = requestedEdition ? [requestedEdition] : businessCarriers;
+
+  return Object.entries(features).flatMap(([featureName, featureConfig]) => {
+    const editionOk =
+      effectiveEditions.length > 0 &&
+      effectiveEditions.some((carrier) => featureConfig.editions.includes(carrier));
+
+    if (
+      featureConfig.enable &&
+      editionOk &&
+      isPluginVersionAtLeast(pluginVersion, featureConfig.minPluginVersion) &&
+      isOpenClawVersionAtLeast(openclawVersion, featureConfig.minOpenclawVersion)
+    ) {
+      return [featureName];
+    }
+    return [];
+  });
+}
+
+let cachedPackageRoot: string | undefined;
+let cachedDefaultPluginVersion: string | undefined;
+
+function findPackageRoot(startDir: string): string {
+  let current = startDir;
+  for (;;) {
+    if (existsSync(join(current, "package.json"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return startDir;
+    }
+    current = parent;
+  }
+}
+
+function getPackageRoot(): string {
+  cachedPackageRoot ??= findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+  return cachedPackageRoot;
+}
+
+function getDefaultFeatureGatesPath(): string {
+  return join(getPackageRoot(), "config", "feature-gates.json");
+}
+
+function getDefaultPluginVersion(): string {
+  if (cachedDefaultPluginVersion) {
+    return cachedDefaultPluginVersion;
+  }
+  try {
+    const raw = readFileSync(join(getPackageRoot(), "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    cachedDefaultPluginVersion = typeof parsed.version === "string" ? parsed.version : "0.0.0";
+  } catch {
+    cachedDefaultPluginVersion = "0.0.0";
+  }
+  return cachedDefaultPluginVersion;
+}
+
+function getDefaultOpenClawVersionSync(): string {
+  const envVersion = process.env.OPENCLAW_VERSION?.trim();
+  return envVersion || "2026.4.8";
+}
+
+export function createOpenVikingFeatureGateService(
+  options: OpenVikingFeatureGateServiceOptions = {},
+): OpenVikingFeatureGateService {
+  const configPath = options.configPath ?? getDefaultFeatureGatesPath();
+  const getPluginVersion = options.getPluginVersion ?? getDefaultPluginVersion;
+  const getOpenClawVersion = options.getOpenClawVersion ?? (async () => getDefaultOpenClawVersionSync());
+  const getOpenClawVersionSync = options.getOpenClawVersionSync ?? getDefaultOpenClawVersionSync;
+  let cachedConfig: FeatureGatesConfig | undefined;
+  let cachedConfigPromise: Promise<FeatureGatesConfig> | undefined;
+  let cachedOpenClawVersion: string | undefined;
+  let cachedOpenClawVersionPromise: Promise<string> | undefined;
+
+  async function loadFeatureGatesConfig(): Promise<FeatureGatesConfig> {
+    if (cachedConfig) {
+      return cachedConfig;
+    }
+    cachedConfigPromise ??= readFile(configPath, "utf8")
+      .then((raw) => {
+        cachedConfig = parseFeatureGatesConfig(raw);
+        return cachedConfig;
+      })
+      .catch((error: unknown) => {
+        cachedConfigPromise = undefined;
+        throw error;
+      });
+    return cachedConfigPromise;
+  }
+
+  function loadFeatureGatesConfigSync(): FeatureGatesConfig {
+    if (cachedConfig) {
+      return cachedConfig;
+    }
+    const raw = readFileSync(configPath, "utf8");
+    cachedConfig = parseFeatureGatesConfig(raw);
+    return cachedConfig;
+  }
+
+  async function loadOpenClawVersion(): Promise<string> {
+    if (cachedOpenClawVersion) {
+      return cachedOpenClawVersion;
+    }
+    cachedOpenClawVersionPromise ??= getOpenClawVersion()
+      .then((version) => {
+        cachedOpenClawVersion = version;
+        return version;
+      })
+      .catch((error: unknown) => {
+        cachedOpenClawVersionPromise = undefined;
+        throw error;
+      });
+    return cachedOpenClawVersionPromise;
+  }
+
+  function loadOpenClawVersionSync(): string {
+    cachedOpenClawVersion ??= getOpenClawVersionSync();
+    return cachedOpenClawVersion;
+  }
+
+  function loadAndNormalizeFeaturesSync(edition?: string): string[] {
+    const parsed = loadFeatureGatesConfigSync();
+    return normalizeFeatures(parsed.features, getPluginVersion(), loadOpenClawVersionSync(), edition);
+  }
+
+  async function loadAndNormalizeFeatures(edition?: string): Promise<string[]> {
+    const [parsed, openclawVersion] = await Promise.all([
+      loadFeatureGatesConfig(),
+      loadOpenClawVersion(),
+    ]);
+    return normalizeFeatures(parsed.features, getPluginVersion(), openclawVersion, edition);
+  }
+
+  return {
+    async getEnabledFeatureGates(edition?: string): Promise<string[]> {
+      return loadAndNormalizeFeatures(edition);
+    },
+
+    async isFeatureGateEnabled(featureName: string, edition?: string): Promise<boolean> {
+      try {
+        const features = await loadAndNormalizeFeatures(edition);
+        return features.includes(featureName);
+      } catch {
+        return false;
+      }
+    },
+
+    isFeatureGateEnabledSync(featureName: string, edition?: string): boolean {
+      try {
+        const features = loadAndNormalizeFeaturesSync(edition);
+        return features.includes(featureName);
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+function readEditionParam(params: unknown): string | undefined {
+  if (!params || typeof params !== "object") {
+    return undefined;
+  }
+  const value = (params as { edition?: unknown }).edition;
+  return typeof value === "string" ? value : undefined;
+}
+
+const defaultFeatureGateService = createOpenVikingFeatureGateService();
+
+export const getEnabledFeatureGates = (edition?: string): Promise<string[]> =>
+  defaultFeatureGateService.getEnabledFeatureGates(edition);
+export const isFeatureGateEnabled = (featureName: string, edition?: string): Promise<boolean> =>
+  defaultFeatureGateService.isFeatureGateEnabled(featureName, edition);
+export const isFeatureGateEnabledSync = (featureName: string, edition?: string): boolean =>
+  defaultFeatureGateService.isFeatureGateEnabledSync(featureName, edition);
+
+export function registerOpenVikingFeatureGatesMethod(
+  api: OpenVikingFeatureGatesGatewayApi,
+  service: OpenVikingFeatureGateService = defaultFeatureGateService,
+): void {
+  if (typeof api.registerGatewayMethod !== "function") {
+    return;
+  }
+
+  api.registerGatewayMethod(OPENVIKING_FEATURE_GATES_RPC, async ({ params, respond }) => {
+    try {
+      const edition = readEditionParam(params);
+      const features = await service.getEnabledFeatureGates(edition);
+      respond(true, { features });
+    } catch (error) {
+      respond(false, error instanceof Error ? error.message : String(error));
+    }
+  });
+}

package/plugin/openviking-import-runtime.ts

@@ -0,0 +1,105 @@
+import type {
+  AddResourceInput,
+  AddResourceResult,
+  AddSkillInput,
+  AddSkillResult,
+} from "../client.js";
+
+export type OpenVikingImportRuntimeResourceInput = {
+  source?: string;
+  to?: string;
+  parent?: string;
+  reason?: string;
+  instruction?: string;
+  wait?: boolean;
+  timeout?: number;
+};
+
+export type OpenVikingImportRuntimeSkillInput = {
+  source?: string;
+  data?: unknown;
+  wait?: boolean;
+  timeout?: number;
+};
+
+export type OpenVikingImportRuntimeToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  details?: Record<string, unknown>;
+};
+
+export type OpenVikingImportRuntimeClient = {
+  addResource: (input: AddResourceInput, agentId?: string) => Promise<AddResourceResult>;
+  addSkill: (input: AddSkillInput, agentId?: string) => Promise<AddSkillResult>;
+};
+
+export type OpenVikingImportRuntimeDeps = {
+  getClient: () => Promise<OpenVikingImportRuntimeClient>;
+};
+
+function formatResourceImportText(result: AddResourceResult): string {
+  const root = result.root_uri ? ` ${result.root_uri}` : "";
+  const warnings = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";
+  return `Imported OpenViking resource.${root}${warnings}`.trim();
+}
+
+function formatSkillImportText(result: AddSkillResult): string {
+  const uri = result.uri ? ` ${result.uri}` : "";
+  const name = result.name ? ` (${result.name})` : "";
+  return `Imported OpenViking skill${name}.${uri}`.trim();
+}
+
+export function createOpenVikingImportRuntime(deps: OpenVikingImportRuntimeDeps): {
+  addResourceOpenViking: (
+    input: OpenVikingImportRuntimeResourceInput,
+    agentId?: string,
+  ) => Promise<OpenVikingImportRuntimeToolResult>;
+  addSkillOpenViking: (
+    input: OpenVikingImportRuntimeSkillInput,
+    agentId?: string,
+  ) => Promise<OpenVikingImportRuntimeToolResult>;
+} {
+  const importResource = async (input: AddResourceInput, agentId?: string): Promise<OpenVikingImportRuntimeToolResult> => {
+    const client = await deps.getClient();
+    const result = await client.addResource(input, agentId);
+    return {
+      content: [{ type: "text", text: formatResourceImportText(result) }],
+      details: {
+        action: "resource_imported",
+        ...result,
+      },
+    };
+  };
+
+  const importSkill = async (input: AddSkillInput, agentId?: string): Promise<OpenVikingImportRuntimeToolResult> => {
+    const client = await deps.getClient();
+    const result = await client.addSkill(input, agentId);
+    return {
+      content: [{ type: "text", text: formatSkillImportText(result) }],
+      details: {
+        action: "skill_imported",
+        ...result,
+      },
+    };
+  };
+
+  const addResourceOpenViking = (input: OpenVikingImportRuntimeResourceInput, agentId?: string) =>
+    importResource({
+      pathOrUrl: input.source ?? "",
+      to: input.to,
+      parent: input.parent,
+      reason: input.reason,
+      instruction: input.instruction,
+      wait: input.wait,
+      timeout: input.timeout,
+    }, agentId);
+
+  const addSkillOpenViking = (input: OpenVikingImportRuntimeSkillInput, agentId?: string) =>
+    importSkill({
+      path: input.source,
+      data: input.data,
+      wait: input.wait,
+      timeout: input.timeout,
+    }, agentId);
+
+  return { addResourceOpenViking, addSkillOpenViking };
+}

package/plugin/openviking-import-tools.ts

@@ -0,0 +1,133 @@
+import { Type } from "@sinclair/typebox";
+
+import type {
+  AddResourceInput,
+  AddResourceResult,
+  AddSkillInput,
+  AddSkillResult,
+} from "../client.js";
+
+export type OpenVikingImportToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+};
+
+export type OpenVikingImportSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+export type OpenVikingImportClient = {
+  addResource: (input: AddResourceInput, agentId?: string) => Promise<AddResourceResult>;
+  addSkill: (input: AddSkillInput, agentId?: string) => Promise<AddSkillResult>;
+};
+
+export type OpenVikingImportToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingImportClient>;
+  resolvePluginSessionRouting: (ctx?: OpenVikingImportToolContext) => OpenVikingImportSession;
+  isBypassedSession: (ctx?: OpenVikingImportToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  enableAddResourceTool: boolean;
+};
+
+function formatResourceImportText(result: AddResourceResult): string {
+  const root = result.root_uri ? ` ${result.root_uri}` : "";
+  const warnings = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";
+  return `Imported OpenViking resource.${root}${warnings}`.trim();
+}
+
+function formatSkillImportText(result: AddSkillResult): string {
+  const uri = result.uri ? ` ${result.uri}` : "";
+  const name = result.name ? ` (${result.name})` : "";
+  return `Imported OpenViking skill${name}.${uri}`.trim();
+}
+
+export function registerOpenVikingImportTools(deps: OpenVikingImportToolsDeps): void {
+  if (deps.enableAddResourceTool) {
+    deps.registerTool(
+      (ctx: OpenVikingImportToolContext) => ({
+        name: "add_resource",
+        label: "Add Resource (OpenViking)",
+        description:
+          "Use only when the user explicitly asks to import, add, upload, save, or index a document, directory, URL, Git repository, or OpenClaw media attachment into OpenViking resources. " +
+          "Never use this during search, retrieval, URI reading, or search-result optimization; use ov_search and ov_read for those flows. " +
+          "For a '[media attached: /path ...]' document, set source to that exact local media path. Do not invent OpenViking upload REST endpoints.",
+        parameters: Type.Object({
+          source: Type.String({ description: "Local path, OpenClaw media attachment path, directory path, public URL, or Git URL" }),
+          to: Type.Optional(Type.String({ description: "Exact target URI, e.g. viking://resources/project-docs" })),
+          parent: Type.Optional(Type.String({ description: "Parent URI under viking://resources" })),
+          reason: Type.Optional(Type.String({ description: "Reason or note for adding this resource" })),
+          instruction: Type.Optional(Type.String({ description: "Processing instruction for semantic extraction" })),
+          wait: Type.Optional(Type.Boolean({ description: "Wait for processing to complete" })),
+          timeout: Type.Optional(Type.Number({ description: "Timeout in seconds when wait is true" })),
+        }),
+        async execute(_toolCallId: string, params: Record<string, unknown>) {
+          if (deps.isBypassedSession(ctx)) {
+            return deps.makeBypassedToolResult("add_resource");
+          }
+          const session = deps.resolvePluginSessionRouting(ctx);
+          const client = await deps.getClient();
+          const result = await client.addResource({
+            pathOrUrl: typeof params.source === "string" ? params.source : "",
+            to: typeof params.to === "string" ? params.to : undefined,
+            parent: typeof params.parent === "string" ? params.parent : undefined,
+            reason: typeof params.reason === "string" ? params.reason : undefined,
+            instruction: typeof params.instruction === "string" ? params.instruction : undefined,
+            wait: typeof params.wait === "boolean" ? params.wait : undefined,
+            timeout: typeof params.timeout === "number" ? params.timeout : undefined,
+          }, session.agentId);
+          return {
+            content: [{ type: "text" as const, text: formatResourceImportText(result) }],
+            details: {
+              action: "resource_imported",
+              ...result,
+            },
+          };
+        },
+      }),
+      { name: "add_resource" },
+    );
+  }
+
+  deps.registerTool(
+    (ctx: OpenVikingImportToolContext) => ({
+      name: "add_skill",
+      label: "Add Skill (OpenViking)",
+      description:
+        "Use only when the user explicitly asks to import, add, install, or register a skill into OpenViking. " +
+        "Set source to a local SKILL.md file or skill directory, or data to raw SKILL.md content or an MCP tool dict.",
+      parameters: Type.Object({
+        source: Type.Optional(Type.String({ description: "Local SKILL.md path or skill directory path" })),
+        data: Type.Optional(Type.Any({ description: "Raw SKILL.md content or MCP tool dict" })),
+        wait: Type.Optional(Type.Boolean({ description: "Wait for processing to complete" })),
+        timeout: Type.Optional(Type.Number({ description: "Timeout in seconds when wait is true" })),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("add_skill");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const result = await client.addSkill({
+          path: typeof params.source === "string" ? params.source : undefined,
+          data: params.data,
+          wait: typeof params.wait === "boolean" ? params.wait : undefined,
+          timeout: typeof params.timeout === "number" ? params.timeout : undefined,
+        }, session.agentId);
+        return {
+          content: [{ type: "text" as const, text: formatSkillImportText(result) }],
+          details: {
+            action: "skill_imported",
+            ...result,
+          },
+        };
+      },
+    }),
+    { name: "add_skill" },
+  );
+}

package/plugin/openviking-lifecycle-hooks.ts

@@ -0,0 +1,65 @@
+export type OpenVikingHookContext = {
+  agentId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+};
+
+export type ContextEngineCommitPort = {
+  commitOVSession: (ctx: { sessionId: string; sessionKey?: string }) => Promise<boolean>;
+};
+
+export type OpenVikingLifecycleHookApi = {
+  on: (
+    hookName: string,
+    handler: (event: unknown, ctx?: OpenVikingHookContext) => unknown,
+    opts?: { priority?: number },
+  ) => void;
+};
+
+export type OpenVikingLifecycleHooksDeps = {
+  api: OpenVikingLifecycleHookApi;
+  rememberSessionAgentId: (ctx: OpenVikingHookContext) => void;
+  isBypassedSession: (ctx?: OpenVikingHookContext) => boolean;
+  verboseRoutingInfo: (message: string) => void;
+  getContextEngine: () => ContextEngineCommitPort | null;
+  logger: {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+  };
+};
+
+export function registerOpenVikingLifecycleHooks(deps: OpenVikingLifecycleHooksDeps): void {
+  deps.api.on("session_start", async (_event: unknown, ctx?: OpenVikingHookContext) => {
+    deps.rememberSessionAgentId(ctx ?? {});
+  });
+  deps.api.on("session_end", async (_event: unknown, ctx?: OpenVikingHookContext) => {
+    deps.rememberSessionAgentId(ctx ?? {});
+  });
+  deps.api.on("before_reset", async (_event: unknown, ctx?: OpenVikingHookContext) => {
+    if (deps.isBypassedSession(ctx)) {
+      deps.verboseRoutingInfo(
+        `openviking: bypassing before_reset due to session pattern match (sessionKey=${ctx?.sessionKey ?? "none"}, sessionId=${ctx?.sessionId ?? "none"})`,
+      );
+      return;
+    }
+    const sessionId = ctx?.sessionId;
+    const contextEngine = deps.getContextEngine();
+    if (sessionId && contextEngine) {
+      try {
+        const ok = await contextEngine.commitOVSession({
+          sessionId,
+          sessionKey: ctx?.sessionKey,
+        });
+        if (ok) {
+          deps.logger.info(`openviking: committed OV session on reset for session=${sessionId}`);
+        }
+      } catch (err) {
+        deps.logger.warn(`openviking: failed to commit OV session on reset: ${String(err)}`);
+      }
+    }
+  });
+  deps.api.on("after_compaction", async (_event: unknown, _ctx?: OpenVikingHookContext) => {
+    // Reserved hook registration for future post-compaction memory integration.
+  });
+}