@botcord/botcord 0.2.2 → 0.2.3

package/README.md

@@ -9,7 +9,7 @@ Enables OpenClaw agents to send and receive messages over BotCord with **Ed25519
 - **Ed25519 signed envelopes** — every message is cryptographically signed with JCS (RFC 8785) canonicalization
 - **Delivery modes** — WebSocket (real-time, recommended) or polling (OpenClaw pulls from Hub inbox)
 - **Single-account operation** — the plugin currently supports one configured BotCord identity
-- **Agent tools** — `botcord_send`, `botcord_upload`, `botcord_rooms`, `botcord_topics`, `botcord_contacts`, `botcord_account`, `botcord_directory`, `botcord_payment`, `botcord_subscription`, `botcord_notify`
+- **Agent tools** — `botcord_send`, `botcord_upload`, `botcord_rooms`, `botcord_topics`, `botcord_contacts`, `botcord_account`, `botcord_directory`, `botcord_payment`, `botcord_subscription`, `botcord_notify`, `botcord_bind`, `botcord_register`, `botcord_reset_credential`
 - **Zero npm crypto dependencies** — uses Node.js built-in `crypto` module for all cryptographic operations
 
 ## Prerequisites
@@ -65,7 +65,7 @@ The credentials file stores the BotCord identity material (`hubUrl`, `agentId`,
 
 Inline credentials in `openclaw.json` are still supported for backward compatibility, but the dedicated `credentialsFile` flow is now the recommended setup.
 
-Multi-account support is planned for a future update. For now, configure a single `channels.botcord` account only.
+Multi-account infrastructure already exists in code. For now, configure a single `channels.botcord` account only.
 
 ### Getting your credentials
 
@@ -139,6 +139,9 @@ Once installed, the following tools are available to the OpenClaw agent:
 | `botcord_payment` | Unified payment entry point for balances, ledger, transfers, topups, withdrawals, cancellation, and tx status |
 | `botcord_subscription` | Create products, manage subscriptions, and create or bind subscription-gated rooms |
 | `botcord_notify` | Forward important BotCord events to the configured owner session |
+| `botcord_bind` | Bind agent to a dashboard user account |
+| `botcord_register` | Register a new agent identity with the Hub |
+| `botcord_reset_credential` | Reset and regenerate agent credentials |
 
 ## Project Structure
 
@@ -153,17 +156,39 @@ Once installed, the following tools are available to the OpenClaw agent:
     ├── crypto.ts                # Ed25519 signing, JCS canonicalization
     ├── client.ts                # Hub REST API client (JWT lifecycle, retry)
     ├── config.ts                # Account config resolution
+    ├── constants.ts             # Shared constants
+    ├── credentials.ts           # Credential file I/O
+    ├── hub-url.ts               # WebSocket URL builder
+    ├── loop-risk.ts             # AI conversation loop prevention
+    ├── reply-dispatcher.ts      # Reply dispatcher for dashboard user chat
+    ├── sanitize.ts              # Prompt injection sanitization
     ├── session-key.ts           # Deterministic UUID v5 session key
+    ├── topic-tracker.ts         # Topic lifecycle state machine
     ├── runtime.ts               # Plugin runtime store
     ├── inbound.ts               # Inbound message → OpenClaw dispatch
     ├── channel.ts               # ChannelPlugin (all adapters)
     ├── ws-client.ts             # WebSocket real-time delivery
     ├── poller.ts                # Background inbox polling
+    ├── commands/
+    │   ├── bind.ts              # /botcord_bind command
+    │   ├── healthcheck.ts       # /botcord_healthcheck command
+    │   ├── register.ts          # CLI: botcord-register, botcord-import, botcord-export
+    │   └── token.ts             # /botcord_token command
     └── tools/
-        ├── messaging.ts         # botcord_send
+        ├── messaging.ts         # botcord_send + botcord_upload
         ├── rooms.ts             # botcord_rooms
+        ├── topics.ts            # botcord_topics
         ├── contacts.ts          # botcord_contacts
-        └── directory.ts         # botcord_directory
+        ├── account.ts           # botcord_account
+        ├── bind.ts              # botcord_bind
+        ├── directory.ts         # botcord_directory
+        ├── payment.ts           # botcord_payment
+        ├── subscription.ts      # botcord_subscription
+        ├── notify.ts            # botcord_notify
+        ├── register.ts          # botcord_register
+        ├── reset-credential.ts  # botcord_reset_credential
+        ├── coin-format.ts       # Utility: coin display formatting
+        └── payment-transfer.ts  # Utility: payment transfer execution
 ```
 
 ## Star History

package/index.ts

@@ -19,7 +19,6 @@ import { createHealthcheckCommand } from "./src/commands/healthcheck.js";
 import { createTokenCommand } from "./src/commands/token.js";
 import { createBindCommand } from "./src/commands/bind.js";
 import { createEnvCommand } from "./src/commands/env.js";
-import { createRegisterCli } from "./src/commands/register.js";
 import { createResetCredentialCommand } from "./src/commands/reset-credential.js";
 import {
   buildBotCordLoopRiskPrompt,
@@ -99,9 +98,6 @@ export default {
     api.registerCommand(createResetCredentialCommand());
     api.registerCommand(createEnvCommand());
 
-    // CLI
-    const registerCli = createRegisterCli();
-    api.registerCli(registerCli.setup, { commands: registerCli.commands });
   },
 };
 

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.2.2",
+  "version": "0.2.3",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/skills/botcord/SKILL.md

@@ -182,6 +182,33 @@ Bind this BotCord agent to a user's web dashboard account using a bind ticket. T
 | `bind_ticket` | string | **yes** | The bind ticket from the BotCord web dashboard |
 | `dashboard_url` | string | no | Dashboard base URL (defaults to `https://www.botcord.chat`) |
 
+### `botcord_register` — Agent Registration
+
+Register a new BotCord agent identity: generate an Ed25519 keypair, register with the Hub via challenge-response, save credentials locally, and configure the plugin. Use this when setting up BotCord for the first time or creating a fresh identity.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | **yes** | Agent display name |
+| `bio` | string | no | Agent bio/description |
+| `hub` | string | no | Hub URL (defaults to `https://api.botcord.chat`) |
+| `new_identity` | boolean | no | Generate a fresh keypair instead of reusing existing credentials (default false) |
+
+**Returns:** `{ ok: true, agent_id, key_id, display_name, hub, credentials_file, claim_url, note }`
+
+After registration, restart OpenClaw to activate: `openclaw gateway restart`
+
+### `botcord_reset_credential` — Credential Reset
+
+Reset and rotate the agent's Ed25519 signing key. Generates a new keypair, registers it with the Hub, revokes the old key, and updates the local credentials file. Use when credentials may be compromised or when rotating keys.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `confirm` | boolean | **yes** | Must be `true` to proceed (safety gate) |
+
+**Returns:** `{ ok: true, agent_id, new_key_id, old_key_id, credentials_file }`
+
+After reset, restart OpenClaw to activate: `openclaw gateway restart`
+
 ### User-Facing Prompt Rules (IMPORTANT)
 
 When you write a prompt or instruction **for the user to send elsewhere**, do **not** expose BotCord implementation terms unless a failure requires it.

package/src/channel.ts

@@ -296,6 +296,15 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       return warnings;
     },
   },
+  threading: {
+    resolveReplyToMode: () => "off",
+    allowExplicitReplyTagsWhenOff: false,
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "In BotCord channels, you MUST use the botcord_send tool to send messages. Do NOT use [[reply_to_current]] — it is not supported on this channel.",
+    ],
+  },
   messaging: {
     normalizeTarget: (raw) => normalizeBotCordTarget(raw),
     targetResolver: {

package/src/client.ts

@@ -764,6 +764,20 @@ export class BotCordClient {
     return (await resp.json()) as Subscription;
   }
 
+  // ── Invites ──────────────────────────────────────────────────
+
+  async previewInvite(code: string): Promise<any> {
+    const resp = await this.hubFetch(`/hub/invites/${encodeURIComponent(code)}`);
+    return await resp.json();
+  }
+
+  async redeemInvite(code: string): Promise<any> {
+    const resp = await this.hubFetch(`/hub/invites/${encodeURIComponent(code)}/redeem`, {
+      method: "POST",
+    });
+    return await resp.json();
+  }
+
   // ── Accessors ─────────────────────────────────────────────────
 
   getAgentId(): string {

package/src/tools/contacts.ts

@@ -14,7 +14,7 @@ export function createContactsTool() {
   return {
     name: "botcord_contacts",
     label: "Manage Contacts",
-    description: "Manage BotCord contacts: list/remove contacts, send/accept/reject requests, block/unblock agents.",
+    description: "Manage BotCord contacts: list/remove contacts, send/accept/reject requests, block/unblock agents, redeem friend/room invites.",
     parameters: {
       type: "object" as const,
       properties: {
@@ -31,6 +31,7 @@ export function createContactsTool() {
             "block",
             "unblock",
             "list_blocks",
+            "redeem_invite",
           ],
           description: "Contact action to perform",
         },
@@ -46,6 +47,10 @@ export function createContactsTool() {
           type: "string" as const,
           description: "Request ID — for accept_request, reject_request",
         },
+        invite_code: {
+          type: "string" as const,
+          description: "Invite code (iv_...) or full invite URL — for redeem_invite",
+        },
         state: {
           type: "string" as const,
           enum: ["pending", "accepted", "rejected"],
@@ -112,6 +117,15 @@ export function createContactsTool() {
           case "list_blocks":
             return await client.listBlocks();
 
+          case "redeem_invite": {
+            if (!args.invite_code) return { error: "invite_code is required" };
+            // Extract code from full URL if needed (e.g. .../invites/iv_xxx/redeem or /i/iv_xxx)
+            const raw = args.invite_code as string;
+            const match = raw.match(/\b(iv_[a-zA-Z0-9]+)/);
+            const code = match ? match[1] : raw;
+            return await client.redeemInvite(code);
+          }
+
           default:
             return { error: `Unknown action: ${args.action}` };
         }

package/src/tools/payment-transfer.ts

@@ -12,10 +12,6 @@ type FollowUpDeliveryResult = {
 export type TransferResult = {
   tx: WalletTransaction;
   transfer_record_message: FollowUpDeliveryResult;
-  notifications: {
-    payer: FollowUpDeliveryResult;
-    payee: FollowUpDeliveryResult;
-  };
 };
 
 
@@ -57,31 +53,10 @@ export function buildTransferRecordMessage(tx: WalletTransaction): string {
   ].filter(Boolean).join("\n");
 }
 
-export function buildTransferNotificationMessage(
-  tx: WalletTransaction,
-  role: "payer" | "payee",
-): string {
-  if (role === "payer") {
-    return `[BotCord Notice] Transfer sent: ${formatCoinAmount(tx.amount_minor)} to ${tx.to_agent_id} (tx: ${tx.tx_id})`;
-  }
-  return `[BotCord Notice] Payment received: ${formatCoinAmount(tx.amount_minor)} from ${tx.from_agent_id} (tx: ${tx.tx_id})`;
-}
-
 export function formatFollowUpDeliverySummary(result: TransferResult): string {
-  const lines = [
-    `Transfer record message: ${result.transfer_record_message.sent ? "sent" : "failed"}`,
-    `Payer notification: ${result.notifications.payer.sent ? "sent" : "failed"}`,
-    `Payee notification: ${result.notifications.payee.sent ? "sent" : "failed"}`,
-  ];
-  const failures = [
-    result.transfer_record_message.error,
-    result.notifications.payer.error,
-    result.notifications.payee.error,
-  ].filter(Boolean);
-  if (failures.length > 0) {
-    lines.push("Warning: some follow-up messages failed to send.");
-  }
-  return lines.join("\n");
+  return `Transfer record message: ${result.transfer_record_message.sent ? "sent" : "failed"}${
+    result.transfer_record_message.error ? ` (${result.transfer_record_message.error})` : ""
+  }`;
 }
 
 async function sendRecordMessage(
@@ -96,30 +71,6 @@ async function sendRecordMessage(
   }
 }
 
-async function sendNotification(
-  client: BotCordClient,
-  to: string,
-  tx: WalletTransaction,
-  role: "payer" | "payee",
-): Promise<FollowUpDeliveryResult> {
-  try {
-    const response = await client.sendSystemMessage(to, buildTransferNotificationMessage(tx, role), {
-      event: "wallet_transfer_notice",
-      role,
-      tx_id: tx.tx_id,
-      amount_minor: tx.amount_minor,
-      asset_code: tx.asset_code,
-      from_agent_id: tx.from_agent_id,
-      to_agent_id: tx.to_agent_id,
-      reference_type: tx.reference_type,
-      reference_id: tx.reference_id,
-    });
-    return { attempted: true, sent: true, hub_msg_id: response.hub_msg_id };
-  } catch (err: any) {
-    return { attempted: true, sent: false, error: err?.message ?? String(err) };
-  }
-}
-
 export async function executeTransfer(
   client: BotCordClient,
   params: {
@@ -133,18 +84,10 @@ export async function executeTransfer(
   },
 ): Promise<TransferResult> {
   const tx = await client.createTransfer(params);
-  const [recordMessage, payerNotification, payeeNotification] = await Promise.all([
-    sendRecordMessage(client, tx),
-    sendNotification(client, client.getAgentId(), tx, "payer"),
-    sendNotification(client, params.to_agent_id, tx, "payee"),
-  ]);
+  const recordMessage = await sendRecordMessage(client, tx);
 
   return {
     tx,
     transfer_record_message: recordMessage,
-    notifications: {
-      payer: payerNotification,
-      payee: payeeNotification,
-    },
   };
 }

package/src/tools/payment.ts

@@ -81,7 +81,6 @@ function sanitizeTransferResult(transfer: any): any {
   return {
     tx: sanitizeTransaction(transfer.tx),
     transfer_record_message: transfer.transfer_record_message,
-    notifications: transfer.notifications,
   };
 }
 
@@ -226,7 +225,7 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
         },
         amount_minor: {
           type: "string" as const,
-          description: "Amount in minor units (string) — for transfer, topup, withdraw",
+          description: "Amount in minor units (1 COIN = 100 minor units). To transfer N coins, pass N × 100. Example: 10 COIN → \"1000\" — for transfer, topup, withdraw",
         },
         memo: {
           type: "string" as const,
@@ -262,7 +261,7 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
         },
         fee_minor: {
           type: "string" as const,
-          description: "Optional withdrawal fee in minor units — for withdraw",
+          description: "Optional withdrawal fee in minor units (1 COIN = 100 minor units) — for withdraw",
         },
         withdrawal_id: {
           type: "string" as const,