@nextclaw/openclaw-compat 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -59,10 +59,58 @@ type OpenClawProviderPlugin = {
     models?: Record<string, unknown>;
     auth?: Array<Record<string, unknown>>;
 };
+type OpenClawChannelConfigSchema = {
+    schema: Record<string, unknown>;
+    uiHints?: Record<string, PluginConfigUiHint>;
+};
+type OpenClawChannelSetup = {
+    validateInput?: (params: {
+        cfg: Record<string, unknown>;
+        input: unknown;
+        accountId?: string | null;
+    }) => string | null;
+    applyAccountConfig?: (params: {
+        cfg: Record<string, unknown>;
+        input: unknown;
+        accountId?: string | null;
+    }) => Record<string, unknown>;
+};
+type OpenClawChannelGatewayStartContext = {
+    accountId?: string | null;
+    log?: {
+        debug?: (message: string) => void;
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+};
+type OpenClawChannelGateway = {
+    startAccount?: (ctx: OpenClawChannelGatewayStartContext) => Promise<void | {
+        stop?: () => void | Promise<void>;
+    }> | void | {
+        stop?: () => void | Promise<void>;
+    };
+};
+type OpenClawChannelConfigAdapter = {
+    listAccountIds?: (cfg?: Record<string, unknown>) => string[];
+    defaultAccountId?: (cfg?: Record<string, unknown>) => string;
+};
+type OpenClawChannelAgentPrompt = {
+    messageToolHints?: (params: {
+        cfg: Config;
+        accountId?: string | null;
+    }) => string[];
+};
 type OpenClawChannelPlugin = {
     id: string;
     meta?: Record<string, unknown>;
     capabilities?: Record<string, unknown>;
+    configSchema?: OpenClawChannelConfigSchema;
+    config?: OpenClawChannelConfigAdapter;
+    setup?: OpenClawChannelSetup;
+    gateway?: OpenClawChannelGateway;
+    agentTools?: OpenClawPluginTool[] | (() => OpenClawPluginTool | OpenClawPluginTool[] | null | undefined);
+    agentPrompt?: OpenClawChannelAgentPrompt;
     outbound?: {
         sendText?: (ctx: {
             cfg: Config;
@@ -141,8 +189,38 @@ type PluginProviderRegistration = {
     provider: OpenClawProviderPlugin;
     source: string;
 };
+type PluginReplyDispatchParams = {
+    ctx: {
+        Body?: string;
+        BodyForAgent?: string;
+        BodyForCommands?: string;
+        ChatType?: string;
+        SenderId?: string;
+        SenderName?: string;
+        SessionKey?: string;
+        AccountId?: string;
+        OriginatingChannel?: string;
+        OriginatingTo?: string;
+        Provider?: string;
+        Surface?: string;
+        [key: string]: unknown;
+    };
+    cfg?: unknown;
+    dispatcherOptions: {
+        deliver: (replyPayload: {
+            text?: string;
+        }, info: {
+            kind: string;
+        }) => Promise<void> | void;
+        onError?: (error: unknown) => void;
+    };
+};
 type PluginRuntime = {
     version: string;
+    config: {
+        loadConfig: () => Record<string, unknown>;
+        writeConfigFile: (next: Record<string, unknown>) => Promise<void>;
+    };
     tools: {
         createMemorySearchTool: (params: {
             config?: Config;
@@ -153,6 +231,11 @@ type PluginRuntime = {
             agentSessionKey?: string;
         }) => OpenClawPluginTool | null;
     };
+    channel: {
+        reply: {
+            dispatchReplyWithBufferedBlockDispatcher: (params: PluginReplyDispatchParams) => Promise<void>;
+        };
+    };
 };
 type OpenClawPluginApi = {
     id: string;
@@ -254,6 +337,34 @@ declare function enablePluginInConfig(config: Config, pluginId: string): Config;
 declare function disablePluginInConfig(config: Config, pluginId: string): Config;
 declare function addPluginLoadPath(config: Config, loadPath: string): Config;
 
+type PluginChannelBinding = {
+    pluginId: string;
+    channelId: string;
+    channel: OpenClawChannelPlugin;
+};
+type PluginChannelGatewayHandle = {
+    pluginId: string;
+    channelId: string;
+    accountId: string;
+    stop?: () => void | Promise<void>;
+};
+declare function getPluginChannelBindings(registry: PluginRegistry): PluginChannelBinding[];
+declare function resolvePluginChannelMessageToolHints(params: {
+    registry: PluginRegistry;
+    channel?: string | null;
+    cfg?: Config;
+    accountId?: string | null;
+}): string[];
+declare function getPluginUiMetadataFromRegistry(registry: PluginRegistry): PluginUiMetadata[];
+declare function startPluginChannelGateways(params: {
+    registry: PluginRegistry;
+    logger?: PluginLogger;
+}): Promise<{
+    handles: PluginChannelGatewayHandle[];
+    diagnostics: PluginDiagnostic[];
+}>;
+declare function stopPluginChannelGateways(handles: PluginChannelGatewayHandle[]): Promise<void>;
+
 type PluginCandidate = {
     idHint: string;
     source: string;
@@ -396,6 +507,12 @@ type PackageManifest = {
 };
 declare function getPackageManifestMetadata(manifest: PackageManifest | undefined): OpenClawPackageManifest | undefined;
 
+type PluginRuntimeBridge = {
+    loadConfig?: () => Record<string, unknown>;
+    writeConfigFile?: (next: Record<string, unknown>) => Promise<void>;
+    dispatchReplyWithBufferedBlockDispatcher?: (params: PluginReplyDispatchParams) => Promise<void>;
+};
+declare function setPluginRuntimeBridge(next: PluginRuntimeBridge | null): void;
 declare function createPluginRuntime(params: {
     workspace: string;
     config?: Config;
@@ -459,4 +576,4 @@ declare function uninstallPlugin(params: {
     extensionsDir?: string;
 }): Promise<UninstallPluginResult>;
 
-export { DEFAULT_ACCOUNT_ID, type InstallPluginResult, type NormalizedPluginsConfig, type OpenClawChannelPlugin, type OpenClawPluginApi, type OpenClawPluginChannelRegistration, type OpenClawPluginConfigSchema, type OpenClawPluginDefinition, type OpenClawPluginModule, type OpenClawPluginTool, type OpenClawPluginToolContext, type OpenClawPluginToolFactory, type OpenClawPluginToolOptions, type OpenClawProviderPlugin, PLUGIN_MANIFEST_FILENAME, PLUGIN_MANIFEST_FILENAMES, type PackageManifest, type PluginCandidate, type PluginChannelRegistration, type PluginConfigUiHint, type PluginDiagnostic, type PluginDiscoveryResult, type PluginInstallLogger, type PluginInstallSource, type PluginInstallUpdate, type PluginKind, type PluginLoadOptions, type PluginLogger, type PluginManifest, type PluginManifestLoadResult, type PluginManifestRecord, type PluginManifestRegistry, type PluginOrigin, type PluginProviderRegistration, type PluginRecord, type PluginRegistry, type PluginRuntime, type PluginStatusReport, type PluginToolRegistration, type PluginUiMetadata, type UninstallActions, type UninstallPluginResult, type _CompatOnly, __nextclawPluginSdkCompat, addPluginLoadPath, buildChannelConfigSchema, buildOauthProviderAuthResult, buildPluginStatusReport, createPluginRuntime, disablePluginInConfig, discoverOpenClawPlugins, emptyPluginConfigSchema, enablePluginInConfig, getPackageManifestMetadata, installPluginFromArchive, installPluginFromDir, installPluginFromFile, installPluginFromNpmSpec, installPluginFromPath, loadOpenClawPlugins, loadPluginManifest, loadPluginManifestRegistry, loadPluginUiMetadata, normalizeAccountId, normalizePluginHttpPath, normalizePluginsConfig, recordPluginInstall, removePluginFromConfig, resolveEnableState, resolvePluginInstallDir, resolvePluginManifestPath, resolveUninstallDirectoryTarget, sleep, toPluginUiMetadata, uninstallPlugin, validateJsonSchemaValue };
+export { DEFAULT_ACCOUNT_ID, type InstallPluginResult, type NormalizedPluginsConfig, type OpenClawChannelAgentPrompt, type OpenClawChannelConfigAdapter, type OpenClawChannelConfigSchema, type OpenClawChannelGateway, type OpenClawChannelGatewayStartContext, type OpenClawChannelPlugin, type OpenClawChannelSetup, type OpenClawPluginApi, type OpenClawPluginChannelRegistration, type OpenClawPluginConfigSchema, type OpenClawPluginDefinition, type OpenClawPluginModule, type OpenClawPluginTool, type OpenClawPluginToolContext, type OpenClawPluginToolFactory, type OpenClawPluginToolOptions, type OpenClawProviderPlugin, PLUGIN_MANIFEST_FILENAME, PLUGIN_MANIFEST_FILENAMES, type PackageManifest, type PluginCandidate, type PluginChannelBinding, type PluginChannelGatewayHandle, type PluginChannelRegistration, type PluginConfigUiHint, type PluginDiagnostic, type PluginDiscoveryResult, type PluginInstallLogger, type PluginInstallSource, type PluginInstallUpdate, type PluginKind, type PluginLoadOptions, type PluginLogger, type PluginManifest, type PluginManifestLoadResult, type PluginManifestRecord, type PluginManifestRegistry, type PluginOrigin, type PluginProviderRegistration, type PluginRecord, type PluginRegistry, type PluginReplyDispatchParams, type PluginRuntime, type PluginRuntimeBridge, type PluginStatusReport, type PluginToolRegistration, type PluginUiMetadata, type UninstallActions, type UninstallPluginResult, type _CompatOnly, __nextclawPluginSdkCompat, addPluginLoadPath, buildChannelConfigSchema, buildOauthProviderAuthResult, buildPluginStatusReport, createPluginRuntime, disablePluginInConfig, discoverOpenClawPlugins, emptyPluginConfigSchema, enablePluginInConfig, getPackageManifestMetadata, getPluginChannelBindings, getPluginUiMetadataFromRegistry, installPluginFromArchive, installPluginFromDir, installPluginFromFile, installPluginFromNpmSpec, installPluginFromPath, loadOpenClawPlugins, loadPluginManifest, loadPluginManifestRegistry, loadPluginUiMetadata, normalizeAccountId, normalizePluginHttpPath, normalizePluginsConfig, recordPluginInstall, removePluginFromConfig, resolveEnableState, resolvePluginChannelMessageToolHints, resolvePluginInstallDir, resolvePluginManifestPath, resolveUninstallDirectoryTarget, setPluginRuntimeBridge, sleep, startPluginChannelGateways, stopPluginChannelGateways, toPluginUiMetadata, uninstallPlugin, validateJsonSchemaValue };

package/dist/index.js

@@ -169,6 +169,125 @@ function addPluginLoadPath(config, loadPath) {
   };
 }
 
+// src/plugins/channel-runtime.ts
+function normalizeChannelId(channel) {
+  return (channel ?? "").trim().toLowerCase();
+}
+function toBinding(registration) {
+  const channelId = registration.channel.id?.trim();
+  if (!channelId) {
+    return null;
+  }
+  return {
+    pluginId: registration.pluginId,
+    channelId,
+    channel: registration.channel
+  };
+}
+function getPluginChannelBindings(registry) {
+  const bindings = [];
+  for (const entry of registry.channels) {
+    const binding = toBinding(entry);
+    if (!binding) {
+      continue;
+    }
+    bindings.push(binding);
+  }
+  return bindings;
+}
+function resolvePluginChannelMessageToolHints(params) {
+  const channelId = normalizeChannelId(params.channel);
+  if (!channelId) {
+    return [];
+  }
+  const binding = getPluginChannelBindings(params.registry).find(
+    (entry) => normalizeChannelId(entry.channelId) === channelId
+  );
+  if (!binding) {
+    return [];
+  }
+  const resolveHints = binding.channel.agentPrompt?.messageToolHints;
+  if (typeof resolveHints !== "function") {
+    return [];
+  }
+  try {
+    const hinted = resolveHints({
+      cfg: params.cfg ?? {},
+      accountId: params.accountId
+    });
+    if (!Array.isArray(hinted)) {
+      return [];
+    }
+    return hinted.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function getPluginUiMetadataFromRegistry(registry) {
+  return registry.plugins.map((plugin) => ({
+    id: plugin.id,
+    configSchema: plugin.configJsonSchema,
+    configUiHints: plugin.configUiHints
+  }));
+}
+async function startPluginChannelGateways(params) {
+  const logger = params.logger;
+  const diagnostics = [];
+  const handles = [];
+  for (const binding of getPluginChannelBindings(params.registry)) {
+    const gateway = binding.channel.gateway;
+    if (!gateway?.startAccount) {
+      continue;
+    }
+    const accountIdsRaw = binding.channel.config?.listAccountIds?.() ?? [binding.channel.config?.defaultAccountId?.() ?? "default"];
+    const accountIds = Array.from(
+      new Set(accountIdsRaw.map((id) => typeof id === "string" ? id.trim() : "").filter(Boolean))
+    );
+    const finalAccountIds = accountIds.length > 0 ? accountIds : ["default"];
+    for (const accountId of finalAccountIds) {
+      try {
+        const started = await gateway.startAccount({
+          accountId,
+          log: logger
+        });
+        handles.push({
+          pluginId: binding.pluginId,
+          channelId: binding.channelId,
+          accountId,
+          stop: started && typeof started === "object" && "stop" in started && typeof started.stop === "function" ? started.stop : void 0
+        });
+      } catch (error) {
+        const raw = String(error);
+        const lower = raw.toLowerCase();
+        const level = lower.includes("required") || lower.includes("not configured") || lower.includes("missing") ? "warn" : "error";
+        const message = `failed to start channel gateway for ${binding.channelId}/${accountId}: ${raw}`;
+        diagnostics.push({
+          level,
+          pluginId: binding.pluginId,
+          message
+        });
+        if (level === "error") {
+          logger?.error(message);
+        } else {
+          logger?.warn(message);
+        }
+      }
+    }
+  }
+  return { handles, diagnostics };
+}
+async function stopPluginChannelGateways(handles) {
+  for (const handle of handles) {
+    if (!handle.stop) {
+      continue;
+    }
+    try {
+      await handle.stop();
+    } catch {
+    }
+  }
+}
+
 // src/plugins/discovery.ts
 import fs2 from "fs";
 import path2 from "path";
@@ -736,19 +855,23 @@ async function installPluginFromPackageDir(params) {
   }
   logger.info?.(`Installing to ${targetDir}...`);
   await fs3.cp(packageDir, targetDir, { recursive: true, force: true });
-  for (const extensionPath of extensions) {
-    const resolved = path3.resolve(targetDir, extensionPath);
-    if (!resolved.startsWith(path3.resolve(targetDir) + path3.sep) && resolved !== path3.resolve(targetDir)) {
-      return { ok: false, error: `extension entry escapes plugin directory: ${extensionPath}` };
-    }
-    if (!await exists(resolved)) {
-      logger.warn?.(`extension entry not found: ${extensionPath}`);
-    }
-  }
   try {
+    for (const extensionPath of extensions) {
+      const resolved = path3.resolve(targetDir, extensionPath);
+      if (!resolved.startsWith(path3.resolve(targetDir) + path3.sep) && resolved !== path3.resolve(targetDir)) {
+        throw new Error(`extension entry escapes plugin directory: ${extensionPath}`);
+      }
+      if (!await exists(resolved)) {
+        throw new Error(`extension entry not found after install: ${extensionPath}`);
+      }
+    }
     await installDependenciesIfNeeded(targetDir, packageManifest, logger);
   } catch (err) {
-    return { ok: false, error: `failed to install dependencies: ${String(err)}` };
+    await fs3.rm(targetDir, { recursive: true, force: true }).catch(() => void 0);
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : `failed to install dependencies: ${String(err)}`
+    };
   }
   return {
     ok: true,
@@ -785,7 +908,7 @@ async function installPluginFromArchive(params) {
     } catch (err) {
       return { ok: false, error: String(err) };
     }
-    return installPluginFromPackageDir({
+    return await installPluginFromPackageDir({
       packageDir,
       extensionsDir: params.extensionsDir,
       logger,
@@ -892,7 +1015,7 @@ async function installPluginFromNpmSpec(params) {
       return { ok: false, error: "npm pack produced no archive" };
     }
     const archivePath = path3.join(tempDir, archiveName);
-    return installPluginFromArchive({
+    return await installPluginFromArchive({
       archivePath,
       extensionsDir: params.extensionsDir,
       logger,
@@ -1096,6 +1219,10 @@ function loadPluginUiMetadata(params) {
 // src/plugins/runtime.ts
 import { getPackageVersion } from "@nextclaw/core";
 import { MemoryGetTool, MemorySearchTool } from "@nextclaw/core";
+var bridge = {};
+function setPluginRuntimeBridge(next) {
+  bridge = next ?? {};
+}
 function toPluginTool(tool) {
   return {
     name: tool.name,
@@ -1104,12 +1231,39 @@ function toPluginTool(tool) {
     execute: (params) => tool.execute(params)
   };
 }
+function loadConfigWithFallback(config) {
+  if (bridge.loadConfig) {
+    return bridge.loadConfig();
+  }
+  return config ?? {};
+}
+async function writeConfigWithFallback(next) {
+  if (!bridge.writeConfigFile) {
+    throw new Error("plugin runtime config.writeConfigFile is unavailable outside gateway runtime");
+  }
+  await bridge.writeConfigFile(next);
+}
+async function dispatchReplyWithFallback(params) {
+  if (!bridge.dispatchReplyWithBufferedBlockDispatcher) {
+    throw new Error("plugin runtime channel.reply dispatcher is unavailable outside gateway runtime");
+  }
+  await bridge.dispatchReplyWithBufferedBlockDispatcher(params);
+}
 function createPluginRuntime(params) {
   return {
     version: getPackageVersion(),
+    config: {
+      loadConfig: () => loadConfigWithFallback(params.config),
+      writeConfigFile: async (next) => writeConfigWithFallback(next)
+    },
     tools: {
       createMemorySearchTool: () => toPluginTool(new MemorySearchTool(params.workspace)),
       createMemoryGetTool: () => toPluginTool(new MemoryGetTool(params.workspace))
+    },
+    channel: {
+      reply: {
+        dispatchReplyWithBufferedBlockDispatcher: async (dispatchParams) => dispatchReplyWithFallback(dispatchParams)
+      }
     }
   };
 }
@@ -1272,8 +1426,21 @@ function ensureUniqueNames(params) {
   }
   return accepted;
 }
+function isPlaceholderConfigSchema(schema) {
+  if (!schema || typeof schema !== "object") {
+    return false;
+  }
+  const type = schema.type;
+  const isObjectType = type === "object" || Array.isArray(type) && type.includes("object");
+  if (!isObjectType) {
+    return false;
+  }
+  const properties = schema.properties;
+  const noProperties = !properties || typeof properties === "object" && !Array.isArray(properties) && Object.keys(properties).length === 0;
+  return noProperties && schema.additionalProperties === false;
+}
 function validatePluginConfig(params) {
-  if (!params.schema) {
+  if (!params.schema || isPlaceholderConfigSchema(params.schema)) {
     return { ok: true, value: params.value };
   }
   const cacheKey = params.cacheKey ?? JSON.stringify(params.schema);
@@ -1567,12 +1734,95 @@ function loadOpenClawPlugins(options) {
         if (accepted.length === 0) {
           return;
         }
+        const channelPlugin = normalizedChannel;
         registry.channels.push({
           pluginId,
-          channel: normalizedChannel,
+          channel: channelPlugin,
           source: candidate.source
         });
-        record.channelIds.push(accepted[0]);
+        const channelId = accepted[0];
+        record.channelIds.push(channelId);
+        const configSchema = channelPlugin.configSchema;
+        if (configSchema && typeof configSchema === "object") {
+          const schema = configSchema.schema;
+          if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+            record.configJsonSchema = schema;
+            record.configSchema = true;
+          }
+          const uiHints = configSchema.uiHints;
+          if (uiHints && typeof uiHints === "object" && !Array.isArray(uiHints)) {
+            record.configUiHints = {
+              ...record.configUiHints ?? {},
+              ...uiHints
+            };
+          }
+        }
+        const pushChannelTools = (value, optional, sourceLabel, resolveValue) => {
+          const previewTools = normalizeToolList(value);
+          if (previewTools.length === 0) {
+            return;
+          }
+          const declaredNames = previewTools.map((tool) => tool.name);
+          const acceptedNames = ensureUniqueNames({
+            names: declaredNames,
+            pluginId,
+            diagnostics: registry.diagnostics,
+            source: candidate.source,
+            owners: toolNameOwners,
+            reserved: reservedToolNames,
+            kind: "tool"
+          });
+          if (acceptedNames.length === 0) {
+            return;
+          }
+          const factory = (ctx) => {
+            const tools = normalizeToolList(resolveValue(ctx));
+            if (tools.length === 0) {
+              return [];
+            }
+            const byName = new Map(tools.map((tool) => [tool.name, tool]));
+            return acceptedNames.map((name) => byName.get(name)).filter(Boolean);
+          };
+          registry.tools.push({
+            pluginId,
+            factory,
+            names: acceptedNames,
+            optional,
+            source: candidate.source
+          });
+          record.toolNames.push(...acceptedNames);
+          const previewByName = new Map(previewTools.map((tool) => [tool.name, tool]));
+          for (const name of acceptedNames) {
+            const resolvedTool = previewByName.get(name);
+            if (!resolvedTool || resolvedToolNames.has(resolvedTool.name)) {
+              continue;
+            }
+            resolvedToolNames.add(resolvedTool.name);
+            registry.resolvedTools.push(resolvedTool);
+          }
+          registry.diagnostics.push({
+            level: "warn",
+            pluginId,
+            source: candidate.source,
+            message: `${sourceLabel} registered channel-owned tools: ${acceptedNames.join(", ")}`
+          });
+        };
+        const agentTools = channelPlugin.agentTools;
+        if (typeof agentTools === "function") {
+          pushChannelTools(
+            normalizeToolList(agentTools()),
+            false,
+            `channel "${channelId}"`,
+            () => agentTools()
+          );
+        } else if (agentTools) {
+          pushChannelTools(
+            normalizeToolList(agentTools),
+            false,
+            `channel "${channelId}"`,
+            () => agentTools
+          );
+        }
       },
       registerProvider: (provider) => {
         const accepted = ensureUniqueNames({
@@ -1810,6 +2060,8 @@ export {
   emptyPluginConfigSchema,
   enablePluginInConfig,
   getPackageManifestMetadata,
+  getPluginChannelBindings,
+  getPluginUiMetadataFromRegistry,
   installPluginFromArchive,
   installPluginFromDir,
   installPluginFromFile,
@@ -1825,10 +2077,14 @@ export {
   recordPluginInstall,
   removePluginFromConfig,
   resolveEnableState,
+  resolvePluginChannelMessageToolHints,
   resolvePluginInstallDir,
   resolvePluginManifestPath,
   resolveUninstallDirectoryTarget,
+  setPluginRuntimeBridge,
   sleep,
+  startPluginChannelGateways,
+  stopPluginChannelGateways,
   toPluginUiMetadata,
   uninstallPlugin,
   validateJsonSchemaValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/openclaw-compat",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "OpenClaw plugin compatibility layer for NextClaw.",
   "type": "module",
@@ -18,7 +18,7 @@
     "jiti": "^1.21.7",
     "jszip": "^3.10.1",
     "tar": "^7.4.3",
-    "@nextclaw/core": "^0.4.8"
+    "@nextclaw/core": "^0.4.9"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",