@botcord/openclaw-plugin 0.0.2

package/src/tools/rooms.ts

@@ -0,0 +1,177 @@
+/**
+ * botcord_rooms — Room lifecycle and membership management.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createRoomsTool() {
+  return {
+    name: "botcord_rooms",
+    description:
+      "Manage BotCord rooms: create, list, join, leave, update, invite/remove members, " +
+      "set permissions, promote/transfer/dissolve, discover public rooms.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: [
+            "create", "list", "info", "update", "discover",
+            "join", "leave", "dissolve",
+            "members", "invite", "remove_member",
+            "promote", "transfer", "permissions",
+          ],
+          description: "Room action to perform",
+        },
+        room_id: {
+          type: "string" as const,
+          description: "Room ID (rm_...)",
+        },
+        name: {
+          type: "string" as const,
+          description: "Room name — for create, update, discover",
+        },
+        description: {
+          type: "string" as const,
+          description: "Room description — for create, update",
+        },
+        visibility: {
+          type: "string" as const,
+          enum: ["private", "public"],
+          description: "Room visibility — for create, update",
+        },
+        join_policy: {
+          type: "string" as const,
+          enum: ["invite_only", "open"],
+          description: "Join policy — for create, update",
+        },
+        default_send: {
+          type: "boolean" as const,
+          description: "Whether all members can post — for create, update",
+        },
+        agent_id: {
+          type: "string" as const,
+          description: "Agent ID — for invite, remove_member, promote, transfer, permissions",
+        },
+        role: {
+          type: "string" as const,
+          enum: ["admin", "member"],
+          description: "Target role — for promote",
+        },
+        can_send: {
+          type: "boolean" as const,
+          description: "Send permission override — for permissions",
+        },
+        can_invite: {
+          type: "boolean" as const,
+          description: "Invite permission override — for permissions",
+        },
+      },
+      required: ["action"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) return { error: singleAccountError };
+
+      const acct = resolveAccountConfig(cfg);
+      if (!isAccountConfigured(acct)) {
+        return { error: "BotCord is not configured." };
+      }
+
+      const client = new BotCordClient(acct);
+
+      try {
+        switch (args.action) {
+          case "create":
+            if (!args.name) return { error: "name is required" };
+            return await client.createRoom({
+              name: args.name,
+              description: args.description,
+              visibility: args.visibility || "private",
+              join_policy: args.join_policy,
+              default_send: args.default_send,
+            });
+
+          case "list":
+            return await client.listMyRooms();
+
+          case "info":
+            if (!args.room_id) return { error: "room_id is required" };
+            return await client.getRoomInfo(args.room_id);
+
+          case "update":
+            if (!args.room_id) return { error: "room_id is required" };
+            return await client.updateRoom(args.room_id, {
+              name: args.name,
+              description: args.description,
+              visibility: args.visibility,
+              join_policy: args.join_policy,
+              default_send: args.default_send,
+            });
+
+          case "discover":
+            return await client.discoverRooms(args.name);
+
+          case "join":
+            if (!args.room_id) return { error: "room_id is required" };
+            await client.joinRoom(args.room_id);
+            return { ok: true, joined: args.room_id };
+
+          case "leave":
+            if (!args.room_id) return { error: "room_id is required" };
+            await client.leaveRoom(args.room_id);
+            return { ok: true, left: args.room_id };
+
+          case "dissolve":
+            if (!args.room_id) return { error: "room_id is required" };
+            await client.dissolveRoom(args.room_id);
+            return { ok: true, dissolved: args.room_id };
+
+          case "members":
+            if (!args.room_id) return { error: "room_id is required" };
+            return await client.getRoomMembers(args.room_id);
+
+          case "invite":
+            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            await client.inviteToRoom(args.room_id, args.agent_id);
+            return { ok: true, invited: args.agent_id, room: args.room_id };
+
+          case "remove_member":
+            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            await client.removeMember(args.room_id, args.agent_id);
+            return { ok: true, removed: args.agent_id, room: args.room_id };
+
+          case "promote":
+            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            await client.promoteMember(args.room_id, args.agent_id, args.role || "admin");
+            return { ok: true, promoted: args.agent_id, role: args.role || "admin", room: args.room_id };
+
+          case "transfer":
+            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            await client.transferOwnership(args.room_id, args.agent_id);
+            return { ok: true, new_owner: args.agent_id, room: args.room_id };
+
+          case "permissions":
+            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            await client.setMemberPermissions(args.room_id, args.agent_id, {
+              can_send: args.can_send,
+              can_invite: args.can_invite,
+            });
+            return { ok: true, agent: args.agent_id, room: args.room_id };
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Room action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/topics.ts

@@ -0,0 +1,106 @@
+/**
+ * botcord_topics — Topic lifecycle management within rooms.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createTopicsTool() {
+  return {
+    name: "botcord_topics",
+    description:
+      "Manage topics within BotCord rooms. Topics are goal-driven conversation units " +
+      "with lifecycle states: open → completed/failed/expired.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: ["create", "list", "get", "update", "delete"],
+          description: "Topic action to perform",
+        },
+        room_id: {
+          type: "string" as const,
+          description: "Room ID (rm_...) — required for all actions",
+        },
+        topic_id: {
+          type: "string" as const,
+          description: "Topic ID (tp_...) — for get, update, delete",
+        },
+        title: {
+          type: "string" as const,
+          description: "Topic title — for create, update",
+        },
+        description: {
+          type: "string" as const,
+          description: "Topic description — for create, update",
+        },
+        goal: {
+          type: "string" as const,
+          description: "Topic goal — declares the conversation's purpose. Required to reactivate a closed topic",
+        },
+        status: {
+          type: "string" as const,
+          enum: ["open", "completed", "failed", "expired"],
+          description: "Topic status — for list (filter) or update (transition)",
+        },
+      },
+      required: ["action", "room_id"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) return { error: singleAccountError };
+
+      const acct = resolveAccountConfig(cfg);
+      if (!isAccountConfigured(acct)) {
+        return { error: "BotCord is not configured." };
+      }
+
+      const client = new BotCordClient(acct);
+
+      try {
+        switch (args.action) {
+          case "create":
+            if (!args.title) return { error: "title is required" };
+            return await client.createTopic(args.room_id, {
+              title: args.title,
+              description: args.description,
+              goal: args.goal,
+            });
+
+          case "list":
+            return await client.listTopics(args.room_id, args.status);
+
+          case "get":
+            if (!args.topic_id) return { error: "topic_id is required" };
+            return await client.getTopic(args.room_id, args.topic_id);
+
+          case "update":
+            if (!args.topic_id) return { error: "topic_id is required" };
+            return await client.updateTopic(args.room_id, args.topic_id, {
+              title: args.title,
+              description: args.description,
+              status: args.status,
+              goal: args.goal,
+            });
+
+          case "delete":
+            if (!args.topic_id) return { error: "topic_id is required" };
+            await client.deleteTopic(args.room_id, args.topic_id);
+            return { ok: true, deleted: args.topic_id, room: args.room_id };
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Topic action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/wallet.ts

@@ -0,0 +1,208 @@
+/**
+ * botcord_wallet — Manage the agent's coin wallet: balance, ledger, transfers, topups, withdrawals.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+function formatBalance(summary: any): string {
+  const available = summary.available_balance_minor ?? "0";
+  const locked = summary.locked_balance_minor ?? "0";
+  const total = summary.total_balance_minor ?? "0";
+  return [
+    `Asset: ${summary.asset_code}`,
+    `Available: ${available} minor units`,
+    `Locked:    ${locked} minor units`,
+    `Total:     ${total} minor units`,
+    `Updated:   ${summary.updated_at}`,
+  ].join("\n");
+}
+
+function extractMemo(tx: any): string | null {
+  if (!tx.metadata_json) return null;
+  try {
+    const meta = typeof tx.metadata_json === "string"
+      ? JSON.parse(tx.metadata_json)
+      : tx.metadata_json;
+    return meta?.memo ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function formatTransaction(tx: any): string {
+  const lines = [
+    `Transaction: ${tx.tx_id}`,
+    `Type:   ${tx.type}`,
+    `Status: ${tx.status}`,
+    `Amount: ${tx.amount_minor} minor units`,
+    `Fee:    ${tx.fee_minor} minor units`,
+  ];
+  if (tx.from_agent_id) lines.push(`From: ${tx.from_agent_id}`);
+  if (tx.to_agent_id) lines.push(`To:   ${tx.to_agent_id}`);
+  const memo = extractMemo(tx);
+  if (memo) lines.push(`Memo: ${memo}`);
+  lines.push(`Created: ${tx.created_at}`);
+  if (tx.completed_at) lines.push(`Completed: ${tx.completed_at}`);
+  return lines.join("\n");
+}
+
+function formatLedger(data: any): string {
+  const entries = data.entries ?? [];
+  if (entries.length === 0) return "No ledger entries found.";
+
+  const lines = entries.map((e: any) => {
+    const dir = e.direction === "credit" ? "+" : "-";
+    return `${e.created_at} | ${dir}${e.amount_minor} | bal=${e.balance_after_minor} | tx=${e.tx_id}`;
+  });
+
+  if (data.has_more) {
+    lines.push(`\n(More entries available — use cursor: "${data.next_cursor}")`);
+  }
+  return lines.join("\n");
+}
+
+export function createWalletTool() {
+  return {
+    name: "botcord_wallet",
+    description:
+      "Manage your BotCord coin wallet: check balance, view ledger, transfer coins, request topup/withdrawal, check transaction status.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: ["balance", "ledger", "transfer", "topup", "withdraw", "tx_status"],
+          description: "Wallet action to perform",
+        },
+        to_agent_id: {
+          type: "string" as const,
+          description: "Recipient agent ID (ag_...) — for transfer",
+        },
+        amount_minor: {
+          type: "string" as const,
+          description: "Amount in minor units (string) — for transfer, topup, withdraw",
+        },
+        memo: {
+          type: "string" as const,
+          description: "Optional memo — for transfer",
+        },
+        idempotency_key: {
+          type: "string" as const,
+          description: "Optional idempotency key (UUID) — for transfer, withdraw",
+        },
+        channel: {
+          type: "string" as const,
+          description: "Topup channel (e.g. 'mock') — for topup",
+        },
+        destination_type: {
+          type: "string" as const,
+          description: "Withdrawal destination type — for withdraw",
+        },
+        destination: {
+          type: "object" as const,
+          description: "Withdrawal destination details — for withdraw",
+        },
+        tx_id: {
+          type: "string" as const,
+          description: "Transaction ID — for tx_status",
+        },
+        cursor: {
+          type: "string" as const,
+          description: "Pagination cursor — for ledger",
+        },
+        limit: {
+          type: "number" as const,
+          description: "Max entries to return — for ledger",
+        },
+        type: {
+          type: "string" as const,
+          description: "Filter by transaction type — for ledger",
+        },
+      },
+      required: ["action"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) return { error: singleAccountError };
+
+      const acct = resolveAccountConfig(cfg);
+      if (!isAccountConfigured(acct)) {
+        return { error: "BotCord is not configured." };
+      }
+
+      const client = new BotCordClient(acct);
+
+      try {
+        switch (args.action) {
+          case "balance": {
+            const summary = await client.getWallet();
+            return { result: formatBalance(summary), data: summary };
+          }
+
+          case "ledger": {
+            const opts: { cursor?: string; limit?: number; type?: string } = {};
+            if (args.cursor) opts.cursor = args.cursor;
+            if (args.limit) opts.limit = args.limit;
+            if (args.type) opts.type = args.type;
+            const ledger = await client.getWalletLedger(opts);
+            return { result: formatLedger(ledger), data: ledger };
+          }
+
+          case "transfer": {
+            if (!args.to_agent_id) return { error: "to_agent_id is required" };
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const tx = await client.createTransfer({
+              to_agent_id: args.to_agent_id,
+              amount_minor: args.amount_minor,
+              memo: args.memo,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatTransaction(tx), data: tx };
+          }
+
+          case "topup": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const topup = await client.createTopup({
+              amount_minor: args.amount_minor,
+              channel: args.channel,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: `Topup request created: ${JSON.stringify(topup)}`, data: topup };
+          }
+
+          case "withdraw": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const withdrawal = await client.createWithdrawal({
+              amount_minor: args.amount_minor,
+              destination_type: args.destination_type,
+              destination: args.destination,
+              idempotency_key: args.idempotency_key,
+            });
+            return {
+              result: `Withdrawal request created: ${JSON.stringify(withdrawal)}`,
+              data: withdrawal,
+            };
+          }
+
+          case "tx_status": {
+            if (!args.tx_id) return { error: "tx_id is required" };
+            const tx = await client.getWalletTransaction(args.tx_id);
+            return { result: formatTransaction(tx), data: tx };
+          }
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Wallet action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/topic-tracker.ts

@@ -0,0 +1,204 @@
+/**
+ * TopicTracker — Agent-side Topic lifecycle state management.
+ *
+ * Implements the decision tree from the Topic lifecycle design doc:
+ * - No topic → one-way notification, don't auto-reply
+ * - Has topic + open → auto-reply OK
+ * - Has topic + terminated + has goal → reactivate to open, auto-reply OK
+ * - Has topic + terminated + no goal → don't auto-reply
+ * - type: result → mark completed
+ * - type: error → mark failed
+ * - TTL expiration → mark expired
+ */
+
+export type TopicState = "open" | "completed" | "failed" | "expired";
+
+export interface TopicInfo {
+  state: TopicState;
+  goal?: string;
+  lastActivityAt: number; // timestamp ms
+  ttlMs: number;
+}
+
+export interface HandleIncomingParams {
+  topic?: string | null;
+  goal?: string | null;
+  type: string; // message type: "message", "ack", "result", "error", etc.
+}
+
+export interface HandleIncomingResult {
+  shouldReply: boolean;
+  reason: string;
+}
+
+export class TopicTracker {
+  private topics = new Map<string, TopicInfo>();
+  private defaultTtlMs: number;
+
+  constructor(options?: { defaultTtlMs?: number }) {
+    this.defaultTtlMs = options?.defaultTtlMs ?? 3_600_000; // 1 hour default
+  }
+
+  /**
+   * Process an incoming message and return whether the agent should auto-reply.
+   *
+   * Decision tree:
+   *   - No topic → one-way notification, don't auto-reply
+   *   - type: "result" → mark completed, don't auto-reply (termination signal)
+   *   - type: "error" → mark failed, don't auto-reply (termination signal)
+   *   - Topic unseen → create as open, auto-reply
+   *   - Topic open → update activity, auto-reply
+   *   - Topic terminated (completed/failed/expired):
+   *       - Message has goal → reactivate to open, auto-reply
+   *       - Message has no goal → don't auto-reply
+   */
+  handleIncoming(params: HandleIncomingParams): HandleIncomingResult {
+    const { topic, goal, type } = params;
+
+    // No topic → one-way notification
+    if (!topic) {
+      return { shouldReply: false, reason: "no topic — treated as one-way notification" };
+    }
+
+    const now = Date.now();
+    const existing = this.topics.get(topic);
+
+    // Check if existing topic has expired by TTL
+    if (existing && existing.state === "open") {
+      if (now - existing.lastActivityAt > existing.ttlMs) {
+        existing.state = "expired";
+      }
+    }
+
+    // Termination signals: result or error
+    if (type === "result") {
+      this.upsertTopic(topic, "completed", goal ?? existing?.goal, now);
+      return { shouldReply: false, reason: "type is result — topic marked completed" };
+    }
+
+    if (type === "error") {
+      this.upsertTopic(topic, "failed", goal ?? existing?.goal, now);
+      return { shouldReply: false, reason: "type is error — topic marked failed" };
+    }
+
+    // Topic not seen before → create as open
+    if (!existing) {
+      this.upsertTopic(topic, "open", goal ?? undefined, now);
+      return { shouldReply: true, reason: "new topic created as open" };
+    }
+
+    // Topic is open → update activity, auto-reply OK
+    if (existing.state === "open") {
+      existing.lastActivityAt = now;
+      if (goal) existing.goal = goal;
+      return { shouldReply: true, reason: "topic is open — auto-reply allowed" };
+    }
+
+    // Topic is terminated (completed / failed / expired)
+    if (goal) {
+      // Reactivate with new goal
+      existing.state = "open";
+      existing.goal = goal;
+      existing.lastActivityAt = now;
+      return { shouldReply: true, reason: "terminated topic reactivated with new goal" };
+    }
+
+    // Terminated + no goal → don't auto-reply
+    return {
+      shouldReply: false,
+      reason: `topic is ${existing.state} and message has no goal — not auto-replying`,
+    };
+  }
+
+  /** Get current state of a topic, checking TTL expiration. */
+  getState(topicKey: string): TopicState | undefined {
+    const info = this.topics.get(topicKey);
+    if (!info) return undefined;
+
+    // Check TTL expiration for open topics
+    if (info.state === "open" && Date.now() - info.lastActivityAt > info.ttlMs) {
+      info.state = "expired";
+    }
+
+    return info.state;
+  }
+
+  /** Get full topic info. */
+  getTopicInfo(topicKey: string): TopicInfo | undefined {
+    const info = this.topics.get(topicKey);
+    if (!info) return undefined;
+
+    // Check TTL expiration for open topics
+    if (info.state === "open" && Date.now() - info.lastActivityAt > info.ttlMs) {
+      info.state = "expired";
+    }
+
+    return { ...info };
+  }
+
+  /** Mark a topic as completed (e.g., when sending a result message). */
+  markCompleted(topicKey: string): void {
+    const info = this.topics.get(topicKey);
+    if (info) {
+      info.state = "completed";
+      info.lastActivityAt = Date.now();
+    }
+  }
+
+  /** Mark a topic as failed (e.g., when sending an error message). */
+  markFailed(topicKey: string): void {
+    const info = this.topics.get(topicKey);
+    if (info) {
+      info.state = "failed";
+      info.lastActivityAt = Date.now();
+    }
+  }
+
+  /** Clean up expired topics. Returns the count of topics removed. */
+  sweepExpired(): number {
+    const now = Date.now();
+    let count = 0;
+
+    for (const [key, info] of this.topics) {
+      // Check TTL expiration for open topics
+      if (info.state === "open" && now - info.lastActivityAt > info.ttlMs) {
+        info.state = "expired";
+      }
+
+      if (info.state === "expired") {
+        this.topics.delete(key);
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  /** Return the number of tracked topics. */
+  get size(): number {
+    return this.topics.size;
+  }
+
+  // ── Internal helpers ────────────────────────────────────────────
+
+  private upsertTopic(
+    key: string,
+    state: TopicState,
+    goal: string | undefined,
+    now: number,
+  ): void {
+    const existing = this.topics.get(key);
+    if (existing) {
+      existing.state = state;
+      existing.lastActivityAt = now;
+      if (goal !== undefined) existing.goal = goal;
+    } else {
+      this.topics.set(key, {
+        state,
+        goal,
+        lastActivityAt: now,
+        ttlMs: this.defaultTtlMs,
+      });
+    }
+  }
+}