@botcord/botcord 0.2.3-beta.20260326095543 → 0.2.3

package/src/poller.ts

@@ -27,16 +27,26 @@ export function startPoller(opts: PollerOptions): { stop: () => void } {
     if (!running || abortSignal?.aborted) return;
 
     try {
-      const resp = await client.pollInbox({ limit: 20, ack: true });
+      const resp = await client.pollInbox({ limit: 20, ack: false });
       const messages = resp.messages || [];
+      const ackedIds: string[] = [];
 
       for (const msg of messages) {
         try {
           await handleInboxMessage(msg, accountId, cfg);
+          ackedIds.push(msg.hub_msg_id);
         } catch (err: any) {
           log?.error(`[${dp}] failed to dispatch message ${msg.hub_msg_id}: ${err.message}`);
         }
       }
+
+      if (ackedIds.length > 0) {
+        try {
+          await client.ackMessages(ackedIds);
+        } catch (err: any) {
+          log?.error(`[${dp}] ack error: ${err.message}`);
+        }
+      }
     } catch (err: any) {
       if (!running) return;
       log?.error(`[${dp}] poll error: ${err.message}`);

package/src/reset-credential.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared BotCord credential reset flow for commands and tools.
+ * Generates a new local keypair, redeems a one-time reset code/ticket, and
+ * persists the replacement credentials through OpenClaw's config writer.
+ */
+import { defaultCredentialsFile, type StoredBotCordCredentials, writeCredentialsFile } from "./credentials.js";
+import { generateKeypair } from "./crypto.js";
+import { getSingleAccountModeError, resolveAccountConfig } from "./config.js";
+import { normalizeAndValidateHubUrl } from "./hub-url.js";
+import { getBotCordRuntime } from "./runtime.js";
+
+export interface ResetCredentialResult {
+  agentId: string;
+  displayName: string;
+  keyId: string;
+  hubUrl: string;
+  credentialsFile: string;
+}
+
+type ResetCredentialApiResponse = {
+  agent_id: string;
+  display_name: string;
+  key_id: string;
+  agent_token: string;
+  expires_at: number;
+  hub_url?: string | null;
+};
+
+function stripInlineCredentials(botcordCfg: Record<string, any>): Record<string, any> {
+  const next = { ...botcordCfg };
+  delete next.hubUrl;
+  delete next.agentId;
+  delete next.keyId;
+  delete next.privateKey;
+  delete next.publicKey;
+  return next;
+}
+
+function buildNextConfig(config: Record<string, any>, credentialsFile: string): Record<string, any> {
+  const currentBotcord = ((config.channels as Record<string, any>)?.botcord ?? {}) as Record<string, any>;
+  return {
+    ...config,
+    channels: {
+      ...(config.channels as Record<string, any>),
+      botcord: {
+        ...stripInlineCredentials(currentBotcord),
+        enabled: true,
+        credentialsFile,
+        deliveryMode: currentBotcord.deliveryMode === "polling" ? "polling" : "websocket",
+        notifySession: currentBotcord.notifySession || "botcord:owner:main",
+      },
+    },
+    session: {
+      ...(config.session as Record<string, any>),
+      dmScope: (config.session as Record<string, any>)?.dmScope || "per-channel-peer",
+    },
+  };
+}
+
+export async function resetCredential(opts: {
+  config: Record<string, any>;
+  agentId: string;
+  resetCodeOrTicket: string;
+  hubUrl?: string;
+}): Promise<ResetCredentialResult> {
+  const { config, agentId, resetCodeOrTicket } = opts;
+  const singleAccountError = getSingleAccountModeError(config);
+  if (singleAccountError) {
+    throw new Error(singleAccountError);
+  }
+  if (!agentId.startsWith("ag_")) {
+    throw new Error("agent_id must start with 'ag_'");
+  }
+  if (!resetCodeOrTicket.trim()) {
+    throw new Error("reset code or reset ticket is required");
+  }
+
+  const existingAccount = resolveAccountConfig(config);
+  const resolvedHubUrl = normalizeAndValidateHubUrl(
+    opts.hubUrl || existingAccount.hubUrl || "",
+  );
+
+  const keypair = generateKeypair();
+  const payload: Record<string, unknown> = {
+    agent_id: agentId,
+    pubkey: keypair.pubkeyFormatted,
+  };
+  if (resetCodeOrTicket.startsWith("rc_")) {
+    payload.reset_code = resetCodeOrTicket;
+  } else {
+    payload.reset_ticket = resetCodeOrTicket;
+  }
+
+  const resp = await fetch(`${resolvedHubUrl}/api/users/me/agents/reset-credential`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(15000),
+  });
+
+  const body = (await resp.json().catch(() => null)) as ResetCredentialApiResponse | { detail?: string; error?: string } | null;
+  if (!resp.ok) {
+    const message = (body as any)?.detail || (body as any)?.error || resp.statusText;
+    throw new Error(`Credential reset failed (${resp.status}): ${message}`);
+  }
+
+  const result = body as ResetCredentialApiResponse;
+  const finalHubUrl = normalizeAndValidateHubUrl(result.hub_url || resolvedHubUrl);
+  const credentials: StoredBotCordCredentials = {
+    version: 1,
+    hubUrl: finalHubUrl,
+    agentId: result.agent_id,
+    keyId: result.key_id,
+    privateKey: keypair.privateKey,
+    publicKey: keypair.publicKey,
+    displayName: result.display_name,
+    savedAt: new Date().toISOString(),
+    token: result.agent_token,
+    tokenExpiresAt: result.expires_at,
+  };
+
+  const runtime = getBotCordRuntime();
+  const credentialsFile = writeCredentialsFile(
+    existingAccount.credentialsFile || defaultCredentialsFile(result.agent_id),
+    credentials,
+  );
+  await runtime.config.writeConfigFile(buildNextConfig(config, credentialsFile));
+
+  return {
+    agentId: result.agent_id,
+    displayName: result.display_name,
+    keyId: result.key_id,
+    hubUrl: finalHubUrl,
+    credentialsFile,
+  };
+}

package/src/tools/account.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createAccountTool() {
@@ -55,6 +56,7 @@ export function createAccountTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/bind.ts

@@ -10,6 +10,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
@@ -32,6 +33,7 @@ export async function executeBind(
   }
 
   const client = new BotCordClient(acct);
+  attachTokenPersistence(client, acct);
 
   try {
     const agentToken = await client.ensureToken();

package/src/tools/contacts.ts

@@ -7,13 +7,14 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 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.",
+    description: "Manage BotCord contacts: list/remove contacts, send/accept/reject requests, block/unblock agents, redeem friend/room invites.",
     parameters: {
       type: "object" as const,
       properties: {
@@ -30,6 +31,7 @@ export function createContactsTool() {
             "block",
             "unblock",
             "list_blocks",
+            "redeem_invite",
           ],
           description: "Contact action to perform",
         },
@@ -45,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"],
@@ -65,6 +71,7 @@ export function createContactsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {
@@ -110,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/directory.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createDirectoryTool() {
@@ -73,6 +74,7 @@ export function createDirectoryTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/messaging.ts

@@ -10,6 +10,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import type { MessageAttachment } from "../types.js";
 
@@ -142,6 +143,7 @@ export function createMessagingTool() {
 
       try {
         const client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
         const msgType = args.type || "message";
 
         // Collect attachments from both file_paths (upload first) and file_urls
@@ -226,6 +228,7 @@ export function createUploadTool() {
 
       try {
         const client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
         const uploaded = await uploadLocalFiles(client, args.file_paths);
         return { ok: true, files: uploaded };
       } catch (err: any) {

package/src/tools/notify.ts

@@ -6,7 +6,7 @@
 import { getBotCordRuntime } from "../runtime.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
-import { deliverNotification } from "../inbound.js";
+import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
 
 export function createNotifyTool() {
   return {
@@ -34,8 +34,8 @@ export function createNotifyTool() {
       if (singleAccountError) return { error: singleAccountError };
 
       const acct = resolveAccountConfig(cfg);
-      const notifySession = acct.notifySession;
-      if (!notifySession) {
+      const sessions = normalizeNotifySessions(acct.notifySession);
+      if (sessions.length === 0) {
         return { error: "notifySession is not configured in channels.botcord" };
       }
 
@@ -45,12 +45,23 @@ export function createNotifyTool() {
         return { error: "text is required" };
       }
 
-      try {
-        await deliverNotification(core, cfg, notifySession, text);
-        return { ok: true, notifySession };
-      } catch (err: any) {
-        return { error: `notify failed: ${err?.message ?? err}` };
+      const errors: string[] = [];
+      for (const ns of sessions) {
+        try {
+          await deliverNotification(core, cfg, ns, text);
+        } catch (err: any) {
+          errors.push(`${ns}: ${err?.message ?? err}`);
+        }
       }
+
+      if (errors.length > 0) {
+        return {
+          ok: errors.length < sessions.length,
+          notifySessions: sessions,
+          errors,
+        };
+      }
+      return { ok: true, notifySessions: sessions };
     },
   };
 }

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

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { formatCoinAmount } from "./coin-format.js";
 import { executeTransfer, isPeerContact, formatFollowUpDeliverySummary } from "./payment-transfer.js";
@@ -80,7 +81,6 @@ function sanitizeTransferResult(transfer: any): any {
   return {
     tx: sanitizeTransaction(transfer.tx),
     transfer_record_message: transfer.transfer_record_message,
-    notifications: transfer.notifications,
   };
 }
 
@@ -225,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,
@@ -261,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,
@@ -302,6 +302,7 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/reset-credential.ts

@@ -0,0 +1,58 @@
+/**
+ * botcord_reset_credential — tool wrapper for the credential reset flow.
+ */
+import { getConfig as getAppConfig } from "../runtime.js";
+import { resetCredential } from "../reset-credential.js";
+
+export function createResetCredentialTool() {
+  return {
+    name: "botcord_reset_credential",
+    label: "Reset Credential",
+    description:
+      "Generate a fresh BotCord credential for an existing agent using a one-time reset code or reset ticket.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        agent_id: {
+          type: "string" as const,
+          description: "Existing BotCord agent ID (ag_...)",
+        },
+        reset_code: {
+          type: "string" as const,
+          description: "One-time reset code or raw reset ticket from the dashboard",
+        },
+        hub_url: {
+          type: "string" as const,
+          description: "Hub URL; defaults to the configured BotCord hub if available",
+        },
+      },
+      required: ["agent_id", "reset_code"],
+    },
+    execute: async (_toolCallId: any, args: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      if (!args.agent_id) return { error: "agent_id is required" };
+      if (!args.reset_code) return { error: "reset_code is required" };
+
+      try {
+        const result = await resetCredential({
+          config: cfg,
+          agentId: args.agent_id,
+          resetCodeOrTicket: args.reset_code,
+          hubUrl: args.hub_url,
+        });
+        return {
+          ok: true,
+          agent_id: result.agentId,
+          display_name: result.displayName,
+          key_id: result.keyId,
+          hub_url: result.hubUrl,
+          credentials_file: result.credentialsFile,
+          note: "Restart OpenClaw to activate: openclaw gateway restart",
+        };
+      } catch (err: any) {
+        return { error: err.message };
+      }
+    },
+  };
+}

package/src/tools/rooms.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createRoomsTool() {
@@ -116,6 +117,7 @@ export function createRoomsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/subscription.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { formatCoinAmount } from "./coin-format.js";
 
@@ -141,6 +142,7 @@ export function createSubscriptionTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {
@@ -181,8 +183,8 @@ export function createSubscriptionTool() {
               name: args.name,
               description: args.description,
               rule: args.rule,
-              visibility: "private",
-              join_policy: "invite_only",
+              visibility: "public",
+              join_policy: "open",
               required_subscription_product_id: args.product_id,
               max_members: args.max_members,
               default_send: args.default_send,
@@ -202,8 +204,8 @@ export function createSubscriptionTool() {
               name: args.name,
               description: args.description,
               rule: args.rule,
-              visibility: "private",
-              join_policy: "invite_only",
+              visibility: "public",
+              join_policy: "open",
               required_subscription_product_id: args.product_id,
               max_members: args.max_members,
               default_send: args.default_send,

package/src/tools/topics.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createTopicsTool() {
@@ -64,6 +65,7 @@ export function createTopicsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/types.ts

@@ -42,10 +42,12 @@ export type BotCordAccountConfig = {
   keyId?: string;
   privateKey?: string;
   publicKey?: string;
+  token?: string;
+  tokenExpiresAt?: number;
   deliveryMode?: "polling" | "websocket";
   pollIntervalMs?: number;
   allowFrom?: string[];
-  notifySession?: string;
+  notifySession?: string | string[];
   accounts?: Record<string, BotCordAccountConfig>;
 };
 
@@ -71,6 +73,7 @@ export type InboxMessage = {
   mentioned?: boolean;
   source_type?: SourceType;
   source_user_id?: string | null;
+  source_user_name?: string | null;
   source_session_kind?: string | null;
 };