@botcord/botcord 0.1.1

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,
+      });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,273 @@
+// BotCord protocol types (mirrors hub/schemas.py)
+
+export type BotCordSignature = {
+  alg: "ed25519";
+  key_id: string;
+  value: string; // base64
+};
+
+export type MessageType =
+  | "message"
+  | "ack"
+  | "result"
+  | "error"
+  | "contact_request"
+  | "contact_request_response"
+  | "contact_removed"
+  | "system";
+
+export type BotCordMessageEnvelope = {
+  v: string;
+  msg_id: string;
+  ts: number;
+  from: string;
+  to: string;
+  type: MessageType;
+  reply_to: string | null;
+  ttl_sec: number;
+  topic?: string | null;
+  goal?: string | null;
+  payload: Record<string, unknown>;
+  payload_hash: string;
+  sig: BotCordSignature;
+  mentions?: string[] | null;
+};
+
+// Account config in openclaw.json channels.botcord
+export type BotCordAccountConfig = {
+  enabled?: boolean;
+  credentialsFile?: string;
+  hubUrl?: string;
+  agentId?: string;
+  keyId?: string;
+  privateKey?: string;
+  publicKey?: string;
+  deliveryMode?: "polling" | "websocket";
+  pollIntervalMs?: number;
+  allowFrom?: string[];
+  notifySession?: string;
+  accounts?: Record<string, BotCordAccountConfig>;
+};
+
+export type BotCordChannelConfig = BotCordAccountConfig;
+
+// Inbox poll response
+export type SourceType = "agent" | "dashboard_user_chat";
+
+export type InboxMessage = {
+  hub_msg_id: string;
+  envelope: BotCordMessageEnvelope;
+  text?: string;
+  room_id?: string;
+  room_name?: string;
+  room_rule?: string | null;
+  room_member_count?: number;
+  room_member_names?: string[];
+  my_role?: string;
+  my_can_send?: boolean;
+  topic?: string;
+  topic_id?: string;
+  goal?: string;
+  mentioned?: boolean;
+  source_type?: SourceType;
+  source_user_id?: string | null;
+  source_session_kind?: string | null;
+};
+
+export type InboxPollResponse = {
+  messages: InboxMessage[];
+  count: number;
+  has_more: boolean;
+};
+
+// Hub API response types
+export type SendResponse = {
+  queued: boolean;
+  hub_msg_id: string;
+  status: string;
+  topic_id?: string;
+};
+
+export type RoomInfo = {
+  room_id: string;
+  name: string;
+  description?: string;
+  rule?: string | null;
+  visibility: "private" | "public";
+  join_policy: "invite_only" | "open";
+  required_subscription_product_id?: string | null;
+  max_members?: number | null;
+  default_send: boolean;
+  default_invite?: boolean;
+  slow_mode_seconds?: number | null;
+  member_count: number;
+  created_at: string;
+};
+
+export type AgentInfo = {
+  agent_id: string;
+  display_name?: string;
+  bio?: string;
+  message_policy: string;
+  endpoints: Array<{ url: string; state: string }>;
+};
+
+export type ContactInfo = {
+  contact_agent_id: string;
+  display_name?: string;
+  created_at: string;
+};
+
+export type ContactRequestInfo = {
+  request_id: string;
+  from_agent_id: string;
+  to_agent_id: string;
+  state: "pending" | "accepted" | "rejected";
+  created_at: string;
+};
+
+// File upload response (mirrors hub/schemas.py FileUploadResponse)
+export type FileUploadResponse = {
+  file_id: string;
+  url: string;
+  original_filename: string;
+  content_type: string;
+  size_bytes: number;
+  expires_at: string; // ISO 8601
+};
+
+// Attachment metadata included in message payloads
+export type MessageAttachment = {
+  filename: string;
+  url: string;
+  content_type?: string;
+  size_bytes?: number;
+};
+
+// Wallet types (mirrors hub wallet schemas)
+
+export type WalletSummary = {
+  agent_id: string;
+  asset_code: string;
+  available_balance_minor: string;
+  locked_balance_minor: string;
+  total_balance_minor: string;
+  updated_at: string;
+};
+
+export type WalletTransaction = {
+  tx_id: string;
+  type: "topup" | "withdrawal" | "transfer";
+  status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+  asset_code: string;
+  amount_minor: string;
+  fee_minor: string;
+  from_agent_id: string | null;
+  to_agent_id: string | null;
+  reference_type: string | null;
+  reference_id: string | null;
+  idempotency_key: string | null;
+  metadata_json: string | null;
+  created_at: string;
+  updated_at: string;
+  completed_at: string | null;
+};
+
+export type WalletLedgerEntry = {
+  entry_id: string;
+  tx_id: string;
+  agent_id: string;
+  asset_code: string;
+  direction: "debit" | "credit";
+  amount_minor: string;
+  balance_after_minor: string;
+  created_at: string;
+};
+
+export type WalletLedgerResponse = {
+  entries: WalletLedgerEntry[];
+  next_cursor: string | null;
+  has_more: boolean;
+};
+
+export type TopupResponse = {
+  topup_id: string;
+  tx_id: string | null;
+  agent_id: string;
+  asset_code: string;
+  amount_minor: string;
+  status: string;
+  channel: string;
+  created_at: string;
+  completed_at: string | null;
+};
+
+export type WithdrawalResponse = {
+  withdrawal_id: string;
+  tx_id: string | null;
+  agent_id: string;
+  asset_code: string;
+  amount_minor: string;
+  fee_minor: string;
+  status: string;
+  destination_type: string | null;
+  review_note: string | null;
+  created_at: string;
+  reviewed_at: string | null;
+  completed_at: string | null;
+};
+
+export type BillingInterval = "week" | "month";
+
+export type SubscriptionProductStatus = "active" | "archived";
+
+export type SubscriptionStatus = "active" | "past_due" | "cancelled";
+
+export type SubscriptionChargeAttemptStatus = "pending" | "succeeded" | "failed";
+
+export type SubscriptionProduct = {
+  product_id: string;
+  owner_agent_id: string;
+  name: string;
+  description: string;
+  asset_code: string;
+  amount_minor: string;
+  billing_interval: BillingInterval;
+  status: SubscriptionProductStatus;
+  created_at: string;
+  updated_at: string;
+  archived_at: string | null;
+};
+
+export type Subscription = {
+  subscription_id: string;
+  product_id: string;
+  subscriber_agent_id: string;
+  provider_agent_id: string;
+  asset_code: string;
+  amount_minor: string;
+  billing_interval: BillingInterval;
+  status: SubscriptionStatus;
+  current_period_start: string;
+  current_period_end: string;
+  next_charge_at: string;
+  cancel_at_period_end: boolean;
+  cancelled_at: string | null;
+  last_charged_at: string | null;
+  last_charge_tx_id: string | null;
+  consecutive_failed_attempts: number;
+  created_at: string;
+  updated_at: string;
+};
+
+export type SubscriptionChargeAttempt = {
+  attempt_id: string;
+  subscription_id: string;
+  billing_cycle_key: string;
+  status: SubscriptionChargeAttemptStatus;
+  scheduled_at: string;
+  attempted_at: string | null;
+  tx_id: string | null;
+  failure_reason: string | null;
+  created_at: string;
+};

package/src/ws-client.ts

@@ -0,0 +1,187 @@
+/**
+ * WebSocket client for real-time BotCord Hub inbox notifications.
+ *
+ * Protocol:
+ *   1. Connect to ws(s)://<hubUrl>/hub/ws
+ *   2. Send {"type": "auth", "token": "<JWT>"}
+ *   3. Receive {"type": "auth_ok", "agent_id": "ag_xxx"}
+ *   4. Receive {"type": "inbox_update"} when new messages arrive
+ *   5. On inbox_update → poll /hub/inbox to fetch messages
+ *   6. Receive {"type": "heartbeat"} every 30s (keepalive)
+ */
+import WebSocket from "ws";
+import { BotCordClient } from "./client.js";
+import { handleInboxMessage } from "./inbound.js";
+import { displayPrefix } from "./config.js";
+import { buildHubWebSocketUrl } from "./hub-url.js";
+
+interface WsClientOptions {
+  client: BotCordClient;
+  accountId: string;
+  cfg: any;
+  abortSignal?: AbortSignal;
+  log?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+const activeWsClients = new Map<string, { stop: () => void }>();
+
+// Reconnect backoff: 1s, 2s, 4s, 8s, 16s, 30s max
+const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
+
+export function startWsClient(opts: WsClientOptions): { stop: () => void } {
+  // Stop any existing client for this account before creating a new one
+  const existing = activeWsClients.get(opts.accountId);
+  if (existing) existing.stop();
+
+  const { client, accountId, cfg, abortSignal, log } = opts;
+  const dp = displayPrefix(accountId, cfg);
+  let running = true;
+  let ws: WebSocket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempt = 0;
+  let processing = false;
+  let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
+  const KEEPALIVE_INTERVAL = 20_000; // 20s — well under Caddy/proxy 30s timeout
+
+  async function fetchAndDispatch() {
+    if (processing) return;
+    processing = true;
+    try {
+      const resp = await client.pollInbox({ limit: 20, ack: true });
+      const messages = resp.messages || [];
+      for (const msg of messages) {
+        try {
+          await handleInboxMessage(msg, accountId, cfg);
+        } catch (err: any) {
+          log?.error(`[${dp}] ws dispatch error for ${msg.hub_msg_id}: ${err.message}`);
+        }
+      }
+    } catch (err: any) {
+      log?.error(`[${dp}] ws poll error: ${err.message}`);
+    } finally {
+      processing = false;
+    }
+  }
+
+  async function connect() {
+    if (!running || abortSignal?.aborted) return;
+
+    try {
+      // Get a fresh JWT token
+      const token = await client.ensureToken();
+      const hubUrl = client.getHubUrl();
+      const wsUrl = buildHubWebSocketUrl(hubUrl);
+
+      log?.info(`[${dp}] WebSocket connecting to ${wsUrl}`);
+      ws = new WebSocket(wsUrl);
+
+      ws.on("open", () => {
+        // Send auth message
+        ws!.send(JSON.stringify({ type: "auth", token }));
+      });
+
+      ws.on("message", async (data: WebSocket.Data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          switch (msg.type) {
+            case "auth_ok":
+              log?.info(`[${dp}] WebSocket authenticated as ${msg.agent_id}`);
+              reconnectAttempt = 0; // Reset backoff on successful auth
+              // Start client-side keepalive to survive proxies/Caddy timeouts
+              if (keepaliveTimer) clearInterval(keepaliveTimer);
+              keepaliveTimer = setInterval(() => {
+                if (ws?.readyState === WebSocket.OPEN) {
+                  ws.send(JSON.stringify({ type: "ping" }));
+                }
+              }, KEEPALIVE_INTERVAL);
+              break;
+
+            case "inbox_update":
+              // New messages available — fetch them
+              await fetchAndDispatch();
+              break;
+
+            case "heartbeat":
+              // Respond with ping to keep alive
+              ws?.send(JSON.stringify({ type: "ping" }));
+              break;
+
+            case "pong":
+              // Server responded to our ping
+              break;
+
+            default:
+              log?.warn(`[${dp}] unknown ws message type: ${msg.type}`);
+          }
+        } catch (err: any) {
+          log?.error(`[${dp}] ws message parse error: ${err.message}`);
+        }
+      });
+
+      ws.on("close", (code: number, reason: Buffer) => {
+        const reasonStr = reason.toString();
+        log?.info(`[${dp}] WebSocket closed: code=${code} reason=${reasonStr}`);
+        ws = null;
+        if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
+
+        if (code === 4001) {
+          // Auth failure — don't reconnect immediately, token may need refresh
+          log?.warn(`[${dp}] WebSocket auth failed, will retry with fresh token`);
+        }
+
+        scheduleReconnect();
+      });
+
+      ws.on("error", (err: Error) => {
+        log?.error(`[${dp}] WebSocket error: ${err.message}`);
+        // 'close' event will fire after this, triggering reconnect
+      });
+    } catch (err: any) {
+      log?.error(`[${dp}] WebSocket connect failed: ${err.message}`);
+      scheduleReconnect();
+    }
+  }
+
+  function scheduleReconnect() {
+    if (!running || abortSignal?.aborted) return;
+    const delay =
+      RECONNECT_BACKOFF[Math.min(reconnectAttempt, RECONNECT_BACKOFF.length - 1)];
+    reconnectAttempt++;
+    log?.info(`[${dp}] WebSocket reconnecting in ${delay}ms (attempt ${reconnectAttempt})`);
+    reconnectTimer = setTimeout(connect, delay);
+  }
+
+  function stop() {
+    running = false;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
+    if (ws) {
+      try {
+        ws.close(1000, "client shutdown");
+      } catch {
+        // ignore
+      }
+      ws = null;
+    }
+    activeWsClients.delete(accountId);
+  }
+
+  // Start connection
+  connect();
+
+  const entry = { stop };
+  activeWsClients.set(accountId, entry);
+
+  abortSignal?.addEventListener("abort", stop, { once: true });
+
+  return entry;
+}
+
+export function stopWsClient(accountId: string): void {
+  const entry = activeWsClients.get(accountId);
+  if (entry) entry.stop();
+}