@botcord/botcord 0.1.2 → 0.1.3-beta.1

package/api.ts

@@ -0,0 +1,3 @@
+// api.ts — setup-only public surface (no runtime deps)
+export { botCordPlugin } from "./src/channel.js";
+export type { BotCordChannelConfig, BotCordAccountConfig } from "./src/types.js";

package/index.ts

@@ -1,14 +1,7 @@
 /**
  * @botcord/botcord — OpenClaw plugin for BotCord A2A messaging protocol.
- *
- * Registers:
- * - Channel plugin (botcord) with WebSocket + polling gateway
- * - Agent tools: botcord_send, botcord_upload, botcord_rooms, botcord_topics, botcord_contacts, botcord_account, botcord_directory, botcord_payment, botcord_subscription, botcord_bind
- * - Commands: /botcord_healthcheck, /botcord_token, /botcord_bind
- * - CLI: openclaw botcord-register, openclaw botcord-import, openclaw botcord-export
  */
-import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
 import { botCordPlugin } from "./src/channel.js";
 import { setBotCordRuntime, setConfigGetter } from "./src/runtime.js";
 import { createMessagingTool, createUploadTool } from "./src/tools/messaging.js";
@@ -33,33 +26,34 @@ import {
   shouldRunBotCordLoopRiskCheck,
 } from "./src/loop-risk.js";
 
-const plugin = {
+export default defineChannelPluginEntry({
   id: "botcord",
   name: "BotCord",
   description: "BotCord A2A messaging protocol — secure agent-to-agent communication with Ed25519 signing",
-  configSchema: emptyPluginConfigSchema(),
+  plugin: botCordPlugin,
 
-  register(api: OpenClawPluginApi) {
-    // Store runtime reference and config getter
-    setBotCordRuntime(api.runtime);
-    setConfigGetter(() => api.config);
+  setRuntime(runtime) {
+    setBotCordRuntime(runtime);
+  },
 
-    // Register channel plugin
-    api.registerChannel({ plugin: botCordPlugin as ChannelPlugin });
+  registerFull(api) {
+    setConfigGetter(() => api.config);
 
-    // Register agent tools
+    // Agent tools — `as any` needed until tool execute() return types are
+    // migrated to the AgentToolResult<T> shape (P2 task).
     api.registerTool(createMessagingTool() as any);
+    api.registerTool(createUploadTool() as any);
     api.registerTool(createRoomsTool() as any);
     api.registerTool(createTopicsTool() as any);
     api.registerTool(createContactsTool() as any);
     api.registerTool(createAccountTool() as any);
     api.registerTool(createDirectoryTool() as any);
-    api.registerTool(createUploadTool() as any);
     api.registerTool(createPaymentTool() as any);
     api.registerTool(createSubscriptionTool() as any);
     api.registerTool(createNotifyTool() as any);
     api.registerTool(createBindTool() as any);
 
+    // Hooks
     api.on("after_tool_call", async (event, ctx) => {
       if (ctx.toolName !== "botcord_send") return;
       if (!didBotCordSendSucceed(event.result, event.error)) return;
@@ -92,18 +86,16 @@ const plugin = {
       clearBotCordLoopRiskSession(ctx.sessionKey);
     });
 
-    // Register commands
-    api.registerCommand(createHealthcheckCommand() as any);
-    api.registerCommand(createTokenCommand() as any);
-    api.registerCommand(createBindCommand() as any);
+    // Commands
+    api.registerCommand(createHealthcheckCommand());
+    api.registerCommand(createTokenCommand());
+    api.registerCommand(createBindCommand());
 
-    // Register CLI command
+    // CLI
     const registerCli = createRegisterCli();
     api.registerCli(registerCli.setup, { commands: registerCli.commands });
   },
-};
+});
 
 export { TopicTracker } from "./src/topic-tracker.js";
 export type { TopicState, TopicInfo } from "./src/topic-tracker.js";
-
-export default plugin;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.1.2",
+  "version": "0.1.3-beta.1",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.1.2",
+  "version": "0.1.3-beta.1",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",
   "license": "MIT",
   "files": [
     "index.ts",
+    "setup-entry.ts",
+    "api.ts",
+    "runtime-api.ts",
     "src/",
     "!src/__tests__/",
     "skills/",
@@ -35,11 +38,11 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.0"
+    "openclaw": ">=2026.3.22"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0",
-    "openclaw": ">=2026.1.0",
+    "openclaw": "^2026.3.23",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
@@ -47,6 +50,12 @@
     "extensions": [
       "./index.ts"
     ],
+    "setupEntry": "./setup-entry.ts",
+    "install": {
+      "npmSpec": "@botcord/botcord",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.22"
+    },
     "channel": {
       "id": "botcord",
       "label": "BotCord",

package/runtime-api.ts

@@ -0,0 +1,7 @@
+// runtime-api.ts — full runtime surface
+export { botCordPlugin } from "./src/channel.js";
+export { BotCordClient } from "./src/client.js";
+export { getBotCordRuntime } from "./src/runtime.js";
+export { TopicTracker } from "./src/topic-tracker.js";
+export type { TopicState, TopicInfo } from "./src/topic-tracker.js";
+export type { BotCordChannelConfig, BotCordAccountConfig, MessageAttachment } from "./src/types.js";

package/setup-entry.ts

@@ -0,0 +1,5 @@
+// setup-entry.ts — lightweight entry for onboarding/config (no heavy deps like ws)
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+import { botCordPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(botCordPlugin);

package/src/channel.ts

@@ -3,28 +3,32 @@
  * outbound (send via signed envelopes), gateway (start websocket/polling),
  * security, messaging, and status adapters.
  */
-import type { ChannelPlugin, ClawdbotConfig } from "openclaw/plugin-sdk";
+import type { ChannelPlugin, OpenClawConfig as ClawdbotConfig } from "openclaw/plugin-sdk/core";
 import {
   buildBaseChannelStatusSummary,
   createDefaultChannelRuntimeState,
-  DEFAULT_ACCOUNT_ID,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/status-helpers";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
 import {
   resolveChannelConfig,
   resolveAccounts,
   isAccountConfigured,
   displayPrefix,
 } from "./config.js";
-import { BotCordClient } from "./client.js";
-import { getBotCordRuntime } from "./runtime.js";
-import { startPoller, stopPoller } from "./poller.js";
-import { startWsClient, stopWsClient } from "./ws-client.js";
 import type {
   BotCordAccountConfig,
   BotCordChannelConfig,
   MessageAttachment,
 } from "./types.js";
 
+// runtime.js is lightweight (no ws/network deps) — safe for static import.
+// Heavy deps (client, poller, ws-client) are lazy-loaded so that setup-entry.ts
+// can import botCordPlugin without pulling in ws at module level.
+import { getBotCordRuntime } from "./runtime.js";
+const lazyClient = () => import("./client.js").then((m) => m.BotCordClient);
+const lazyPoller = () => import("./poller.js");
+const lazyWsClient = () => import("./ws-client.js");
+
 // ── Types ────────────────────────────────────────────────────────
 
 export interface ResolvedBotCordAccount {
@@ -291,7 +295,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId });
       if (!account.configured || !account.agentId) return null;
       try {
-        const client = new BotCordClient(account.config);
+        const Client = await lazyClient();
+        const client = new Client(account.config);
         const info = await client.resolve(account.agentId);
         return { kind: "user", id: info.agent_id, name: info.display_name || info.agent_id };
       } catch {
@@ -302,7 +307,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId });
       if (!account.configured) return [];
       try {
-        const client = new BotCordClient(account.config);
+        const Client = await lazyClient();
+        const client = new Client(account.config);
         const contacts = await client.listContacts();
         const q = query?.trim().toLowerCase() ?? "";
         return contacts
@@ -326,7 +332,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId });
       if (!account.configured) return [];
       try {
-        const client = new BotCordClient(account.config);
+        const Client = await lazyClient();
+        const client = new Client(account.config);
         const rooms = await client.listMyRooms();
         const q = query?.trim().toLowerCase() ?? "";
         return rooms
@@ -345,7 +352,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
     textChunkLimit: 4000,
     sendText: async ({ cfg, to, text, accountId }) => {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId: accountId ?? undefined });
-      const client = new BotCordClient(account.config);
+      const Client = await lazyClient();
+      const client = new Client(account.config);
       const result = await client.sendMessage(to, text);
       return {
         channel: "botcord",
@@ -355,7 +363,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
     },
     sendMedia: async ({ cfg, to, text, mediaUrl, accountId }) => {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId: accountId ?? undefined });
-      const client = new BotCordClient(account.config);
+      const Client = await lazyClient();
+      const client = new Client(account.config);
       const attachments: MessageAttachment[] = [];
       if (mediaUrl) {
         const filename = mediaUrl.split("/").pop() || "attachment";
@@ -402,11 +411,13 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const dp = displayPrefix(account.accountId, ctx.cfg);
       ctx.log?.info(`[${dp}] starting BotCord gateway (${account.deliveryMode} mode)`);
 
-      const client = new BotCordClient(account.config);
+      const Client = await lazyClient();
+      const client = new Client(account.config);
       const mode = account.deliveryMode || "websocket";
 
       if (mode === "websocket") {
         ctx.log?.info(`[${dp}] starting WebSocket connection to Hub`);
+        const { startWsClient } = await lazyWsClient();
         startWsClient({
           client,
           accountId: account.accountId,
@@ -415,6 +426,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
           log: ctx.log,
         });
       } else {
+        const { startPoller } = await lazyPoller();
         startPoller({
           client,
           accountId: account.accountId,
@@ -438,6 +450,8 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
         ctx.abortSignal?.addEventListener("abort", () => resolve(), { once: true });
       });
 
+      const { stopWsClient } = await lazyWsClient();
+      const { stopPoller } = await lazyPoller();
       stopWsClient(account.accountId);
       stopPoller(account.accountId);
       ctx.setStatus({ accountId: ctx.accountId, running: false, lastStopAt: Date.now() });

package/src/commands/bind.ts

@@ -10,8 +10,8 @@ export function createBindCommand() {
       "Bind this agent to a BotCord web dashboard account using a bind ticket.",
     acceptsArgs: true,
     requireAuth: true,
-    handler: async (args?: string) => {
-      const bindTicket = (args || "").trim();
+    handler: async (ctx: any) => {
+      const bindTicket = (ctx.args || "").trim();
       if (!bindTicket) {
         return { text: "[FAIL] Usage: /botcord_bind <bind_ticket>" };
       }

package/src/commands/healthcheck.ts

@@ -18,7 +18,7 @@ export function createHealthcheckCommand() {
     description: "Check BotCord integration health: config, Hub connectivity, token, delivery mode.",
     acceptsArgs: false,
     requireAuth: true,
-    handler: async () => {
+    handler: async (_ctx: any) => {
       const lines: string[] = [];
       let pass = 0;
       let warn = 0;

package/src/commands/register.ts

@@ -25,8 +25,7 @@ import {
 } from "../config.js";
 import { normalizeAndValidateHubUrl } from "../hub-url.js";
 import { getBotCordRuntime } from "../runtime.js";
-
-const DEFAULT_HUB = "https://api.botcord.chat";
+import { DEFAULT_HUB } from "../constants.js";
 
 interface RegisterResult {
   agentId: string;

package/src/commands/token.ts

@@ -15,7 +15,7 @@ export function createTokenCommand() {
     description: "Fetch and display the current BotCord JWT token.",
     acceptsArgs: false,
     requireAuth: true,
-    handler: async () => {
+    handler: async (_ctx: any) => {
       const cfg = getAppConfig();
       if (!cfg) {
         return { text: "[FAIL] No OpenClaw configuration available" };

package/src/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * Release channel and environment-dependent defaults.
+ *
+ * In the stable (production) build this file ships as-is.
+ * The CI pipeline replaces the RELEASE_CHANNEL value with "beta"
+ * before publishing to the `beta` npm dist-tag, so that beta
+ * installations automatically point at the test hub.
+ */
+
+export type ReleaseChannel = "stable" | "beta";
+
+export const RELEASE_CHANNEL: ReleaseChannel = "beta";
+
+const HUB_URLS: Record<ReleaseChannel, string> = {
+  stable: "https://api.botcord.chat",
+  beta: "https://test.botcord.chat",
+};
+
+export const DEFAULT_HUB = HUB_URLS[RELEASE_CHANNEL];

package/src/inbound.ts

@@ -227,7 +227,7 @@ async function handleA2AMessage(
   // Prompt the agent to notify its owner when receiving contact requests
   const notifyOwnerHint =
     envelope.type === "contact_request"
-      ? `\n\n[You received a contact request from ${senderId}. Use the botcord_notify tool to inform your owner about this request so they can decide whether to accept or reject it. Include the sender's agent ID and any message they attached.]`
+      ? `\n\n[You received a contact request from ${sanitizedSender}. Use the botcord_notify tool to inform your owner about this request so they can decide whether to accept or reject it. Include the sender's agent ID and any message they attached.]`
       : "";
 
   const sanitizedContent = sanitizeUntrustedContent(rawContent);

package/src/runtime.ts

@@ -2,7 +2,7 @@
  * Plugin runtime store — holds a reference to OpenClaw's PluginRuntime
  * and a config getter for tools/hooks that need the full app config.
  */
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 
 let runtime: PluginRuntime | null = null;
 let configGetter: (() => any) | null = null;

package/src/sanitize.ts

@@ -33,11 +33,14 @@ export function sanitizeUntrustedContent(text: string): string {
 }
 
 /**
- * Sanitize sender name — must not contain newlines or structural markers.
+ * Sanitize sender name — must not contain newlines, structural markers,
+ * or characters that could break XML attribute boundaries.
  */
 export function sanitizeSenderName(name: string): string {
   return name
     .replace(/[\n\r]/g, " ")
     .replace(/\[/g, "⟦").replace(/\]/g, "⟧")
+    .replace(/"/g, "'")
+    .replace(/</g, "＜").replace(/>/g, "＞")
     .slice(0, 100);
 }

package/src/tools/account.ts

@@ -12,6 +12,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 export function createAccountTool() {
   return {
     name: "botcord_account",
+    label: "Manage Account",
     description:
       "Manage your own BotCord agent: view identity, update profile, get/set message policy, check message delivery status.",
     parameters: {

package/src/tools/bind.ts

@@ -70,6 +70,7 @@ export async function executeBind(
 export function createBindTool() {
   return {
     name: "botcord_bind",
+    label: "Bind Dashboard",
     description:
       "Bind this BotCord agent to a user's web dashboard account using a bind ticket.",
     parameters: {

package/src/tools/contacts.ts

@@ -12,6 +12,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 export function createContactsTool() {
   return {
     name: "botcord_contacts",
+    label: "Manage Contacts",
     description: "Manage BotCord contacts: list/remove contacts, send/accept/reject requests, block/unblock agents.",
     parameters: {
       type: "object" as const,

package/src/tools/directory.ts

@@ -12,6 +12,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 export function createDirectoryTool() {
   return {
     name: "botcord_directory",
+    label: "Search Directory",
     description: "Look up agents, discover public rooms, and query message history on BotCord.",
     parameters: {
       type: "object" as const,

package/src/tools/messaging.ts

@@ -77,6 +77,7 @@ async function uploadLocalFiles(
 export function createMessagingTool() {
   return {
     name: "botcord_send",
+    label: "Send Message",
     description:
       "Send a message to another agent or room via BotCord. " +
       "Use ag_* for direct messages, rm_* for rooms. " +
@@ -192,6 +193,7 @@ export function createMessagingTool() {
 export function createUploadTool() {
   return {
     name: "botcord_upload",
+    label: "Upload Files",
     description:
       "Upload one or more local files to BotCord Hub. " +
       "Returns file URLs that can be used later in botcord_send's file_urls parameter. " +

package/src/tools/notify.ts

@@ -11,6 +11,7 @@ import { deliverNotification } from "../inbound.js";
 export function createNotifyTool() {
   return {
     name: "botcord_notify",
+    label: "Send Notification",
     description:
       "Send a notification to the owner's configured channel (e.g. Telegram, Discord). " +
       "Use this when you receive an important BotCord message that the owner should know about — " +

package/src/tools/payment.ts

@@ -194,6 +194,7 @@ function sanitizeLedger(data: any): any {
 export function createPaymentTool(opts?: { name?: string; description?: string }) {
   return {
     name: opts?.name || "botcord_payment",
+    label: "Manage Payments",
     description:
       opts?.description ||
       "Manage BotCord coin payments and transactions: verify recipients, check balance, view ledger, transfer coins, create topups and withdrawals, cancel withdrawals, and query transaction status.",

package/src/tools/rooms.ts

@@ -12,6 +12,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 export function createRoomsTool() {
   return {
     name: "botcord_rooms",
+    label: "Manage Rooms",
     description:
       "Manage BotCord rooms: create, list, join, leave, update, invite/remove members, " +
       "set permissions, promote/transfer/dissolve, discover public rooms.",

package/src/tools/subscription.ts

@@ -47,6 +47,7 @@ function formatSubscriptionList(subscriptions: any[]): string {
 export function createSubscriptionTool() {
   return {
     name: "botcord_subscription",
+    label: "Manage Subscriptions",
     description:
       "Create subscription products priced in BotCord coin, subscribe to products, list active subscriptions, and manage cancellation or product archiving.",
     parameters: {

package/src/tools/topics.ts

@@ -12,6 +12,7 @@ import { getConfig as getAppConfig } from "../runtime.js";
 export function createTopicsTool() {
   return {
     name: "botcord_topics",
+    label: "Manage Topics",
     description:
       "Manage topics within BotCord rooms. Topics are goal-driven conversation units " +
       "with lifecycle states: open → completed/failed/expired.",