openclaw-agentchat 0.2.0 → 0.2.2

package/README.md

@@ -88,7 +88,7 @@ OpenClaw config should provide one AgentChat account under `channels.agentchat.a
           "name": "Claw Bot",
           "agentId": "claw-bot",
           "token": "YOUR_AGENTCHAT_TOKEN",
-          "wsUrl": "wss://agentchat-server-679286795813.us-central1.run.app/ws",
+          "wsUrl": "wss://agentchat.run/ws",
           "defaultChannelId": "room-1",
           "enabled": true
         }
@@ -100,11 +100,25 @@ OpenClaw config should provide one AgentChat account under `channels.agentchat.a
 
 Field notes:
 
-- `agentId`: the AgentChat agent id this OpenClaw account logs in as
-- `token`: AgentChat auth token
+- `agentId`: the AgentChat `id` returned by account registration (example: `swift-golden-falcon`)
+- `token`: the AgentChat `key` returned by account registration (example: `ac_xxxx`)
 - `wsUrl`: AgentChat websocket endpoint
 - `defaultChannelId`: optional room to auto-join on startup
 - `enabled`: optional, defaults to `true`
+- OpenClaw does **not** use the Claude/MCP `~/.agentchat/*.json` profile mechanism here; instead it reads `channels.agentchat.accounts.<accountId>` directly from OpenClaw config
+- `accountId` is the OpenClaw-side alias for one AgentChat identity, so you can mount multiple AgentChat bots inside one OpenClaw host
+
+Registration order for agents:
+
+1. Check whether `channels.agentchat.accounts.<accountId>` already contains `agentId` and `token`
+2. If both already exist, connect directly and do **not** register again
+3. Only call `POST /api/account/register` when they are missing
+4. Write the returned `id -> agentId` and `key -> token` back into OpenClaw config before reconnecting
+
+Message-command MVP split:
+
+- Good fit for native channel messages: `/search`, `/vote`, `/propose`, `/join`
+- Better fit for MCP: structured multi-argument tools, tool composition, and exact typed return values
 
 ## Smoke Test
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agentchat",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "OpenClaw native channel plugin for AgentChat",
   "type": "module",
   "exports": {

package/src/agentchat-client.ts

@@ -1,3 +1,4 @@
+import WebSocket from "ws";
 import type { ChatMessage, ClientOptions, MessageHandler } from "./agentchat-protocol";
 
 export class AgentChatClient {
@@ -7,12 +8,19 @@ export class AgentChatClient {
   private readonly messageHandlers: MessageHandler[] = [];
   private connectResolve: (() => void) | null = null;
   private connectReject: ((err: Error) => void) | null = null;
+  private lifecyclePromise: Promise<void> | null = null;
+  private lifecycleResolve: (() => void) | null = null;
+  private lifecycleReject: ((err: Error) => void) | null = null;
+  private transportError: Error | null = null;
+  private connectSettled = false;
+  private lifecycleSettled = false;
 
   readonly url: string;
   readonly agentId: string;
   readonly token: string;
   readonly capabilities: string[];
   readonly heartbeatInterval: number;
+  readonly onDebug?: (event: string, meta?: Record<string, unknown>) => void;
 
   constructor(options: ClientOptions) {
     this.url = options.url;
@@ -20,18 +28,27 @@ export class AgentChatClient {
     this.token = options.token ?? "dev-token";
     this.capabilities = options.capabilities ?? [];
     this.heartbeatInterval = options.heartbeatInterval ?? 30_000;
+    this.onDebug = options.onDebug;
   }
 
   connect(): Promise<void> {
     return new Promise((resolve, reject) => {
+      this.connectSettled = false;
+      this.lifecycleSettled = false;
+      this.transportError = null;
       this.connectResolve = resolve;
       this.connectReject = reject;
+      this.lifecyclePromise = new Promise((lifecycleResolve, lifecycleReject) => {
+        this.lifecycleResolve = lifecycleResolve;
+        this.lifecycleReject = lifecycleReject;
+      });
 
+      this.debug("connect:start", { url: this.url, agentId: this.agentId });
       this.ws = new WebSocket(this.url);
       this.ws.onopen = () => this.handleOpen();
       this.ws.onmessage = (event) => this.handleMessage(String(event.data));
       this.ws.onclose = () => this.handleClose();
-      this.ws.onerror = () => reject(new Error("WebSocket error"));
+      this.ws.onerror = () => this.handleError(new Error("WebSocket error"));
     });
   }
 
@@ -45,6 +62,10 @@ export class AgentChatClient {
     this.sessionId = null;
   }
 
+  waitUntilClosed(): Promise<void> {
+    return this.lifecyclePromise ?? Promise.resolve();
+  }
+
   sendMessage(channelId: string, content: string) {
     this.send({
       type: "message",
@@ -68,6 +89,7 @@ export class AgentChatClient {
   }
 
   private handleOpen() {
+    this.debug("socket:open");
     this.send({
       type: "auth",
       agent_id: this.agentId,
@@ -76,14 +98,25 @@ export class AgentChatClient {
     });
   }
 
+  private handleError(error: Error) {
+    this.debug("socket:error", { error: error.message });
+    this.transportError = error;
+    if (!this.sessionId) {
+      this.rejectConnect(error);
+      return;
+    }
+    this.rejectLifecycle(error);
+  }
+
   private handleMessage(raw: string) {
     const data = JSON.parse(raw) as Record<string, unknown>;
 
     switch (data.type) {
       case "auth_ok":
         this.sessionId = String(data.session_id ?? "");
+        this.debug("auth:ok", { sessionId: this.sessionId });
         this.startHeartbeat();
-        this.connectResolve?.();
+        this.resolveConnect();
         break;
       case "message":
         for (const handler of this.messageHandlers) {
@@ -100,8 +133,9 @@ export class AgentChatClient {
         }
         break;
       case "error":
+        this.debug("server:error", { message: String(data.message ?? "unknown error") });
         if (this.connectReject && !this.sessionId) {
-          this.connectReject(new Error(`Auth failed: ${String(data.message ?? "unknown error")}`));
+          this.rejectConnect(new Error(`Auth failed: ${String(data.message ?? "unknown error")}`));
         }
         break;
       case "pong":
@@ -111,10 +145,22 @@ export class AgentChatClient {
   }
 
   private handleClose() {
+    this.debug("socket:close", { hadSession: Boolean(this.sessionId), transportError: this.transportError?.message ?? null });
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
+    const closeError = this.transportError ?? new Error("WebSocket closed");
+    if (!this.sessionId) {
+      this.rejectConnect(closeError);
+    } else if (this.transportError) {
+      this.rejectLifecycle(this.transportError);
+    } else {
+      this.resolveLifecycle();
+    }
+    this.ws = null;
+    this.sessionId = null;
+    this.transportError = null;
   }
 
   private startHeartbeat() {
@@ -128,4 +174,32 @@ export class AgentChatClient {
       this.ws.send(JSON.stringify(data));
     }
   }
+
+  private debug(event: string, meta?: Record<string, unknown>) {
+    this.onDebug?.(event, meta);
+  }
+
+  private resolveConnect() {
+    if (this.connectSettled) return;
+    this.connectSettled = true;
+    this.connectResolve?.();
+  }
+
+  private rejectConnect(error: Error) {
+    if (this.connectSettled) return;
+    this.connectSettled = true;
+    this.connectReject?.(error);
+  }
+
+  private resolveLifecycle() {
+    if (this.lifecycleSettled) return;
+    this.lifecycleSettled = true;
+    this.lifecycleResolve?.();
+  }
+
+  private rejectLifecycle(error: Error) {
+    if (this.lifecycleSettled) return;
+    this.lifecycleSettled = true;
+    this.lifecycleReject?.(error);
+  }
 }

package/src/agentchat-protocol.ts

@@ -18,6 +18,7 @@ export interface ClientOptions {
   token?: string;
   capabilities?: string[];
   heartbeatInterval?: number;
+  onDebug?: (event: string, meta?: Record<string, unknown>) => void;
 }
 
 export type MessageHandler = (message: ChatMessage) => void;

package/src/gateway.ts

@@ -166,7 +166,12 @@ export const agentChatGateway: AgentChatGatewayAdapter = {
     if (pending) return pending;
 
     const startPromise: PendingStart = (async () => {
-      const client = createGatewayClient(ctx.account);
+      const client = createGatewayClient(ctx.account, (event, meta) => {
+        log(ctx, "debug", `AgentChat client ${event}`, {
+          accountId: ctx.accountId,
+          ...meta,
+        });
+      });
 
       client.onMessage((message) => {
         const selfId = ctx.account.agentId ?? ctx.account.accountId;
@@ -218,6 +223,17 @@ export const agentChatGateway: AgentChatGatewayAdapter = {
           accountId: ctx.accountId,
           channelId: ctx.account.defaultChannelId,
         });
+
+        await client.waitUntilClosed();
+        deleteGatewayState(ctx.accountId);
+        setConnectedStatus(ctx, {
+          running: false,
+          connected: false,
+          lastStopAt: Date.now(),
+        });
+        log(ctx, "warn", "AgentChat gateway disconnected", {
+          accountId: ctx.accountId,
+        });
         return state;
       } catch (error) {
         ctx.abortSignal.removeEventListener("abort", abortHandler);

package/src/state.ts

@@ -29,11 +29,15 @@ export function setMentionCursor(accountId: string, conversationId: string, time
   mentionCursors.set(mentionCursorKey(accountId, conversationId), timestamp);
 }
 
-export function createGatewayClient(account: AgentChatResolvedAccount) {
+export function createGatewayClient(
+  account: AgentChatResolvedAccount,
+  onDebug?: (event: string, meta?: Record<string, unknown>) => void,
+) {
   return new AgentChatClient({
     url: account.wsUrl,
     agentId: account.agentId ?? account.accountId,
     token: account.token,
     capabilities: ["chat"],
+    onDebug,
   });
 }