@openclaw-cloud/agent-controller 0.1.2 → 0.1.4

package/CLAUDE.md

@@ -1,5 +1,64 @@
 # CLAUDE.md — Agent Controller Context
 
+Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.
+
+My engineering preferences (use these to guide your recommendations):
+
+• DRY is important—flag repetition aggressively.
+• Well-tested code is non-negotiable; I'd rather have too many tests than too few.
+• I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
+• I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
+• Bias toward explicit over clever.
+
+1. Architecture review
+   Evaluate:
+
+• Overall system design and component boundaries.
+• Dependency graph and coupling concerns.
+• Data flow patterns and potential bottlenecks.
+• Scaling characteristics and single points of failure.
+• Security architecture (auth, data access, API boundaries).
+2. Code quality review
+   Evaluate:
+
+• Code organization and module structure.
+• DRY violations—be aggressive here.
+• Error handling patterns and missing edge cases (call these out explicitly).
+• Technical debt hotspots.
+• Areas that are over-engineered or under-engineered relative to my preferences.
+3. Test review
+   Evaluate:
+
+• Test coverage gaps (unit, integration, e2e).
+• Test quality and assertion strength.
+• Missing edge case coverage—be thorough.
+• Untested failure modes and error paths.
+4. Performance review
+   Evaluate:
+
+• N+1 queries and database access patterns.
+• Memory-usage concerns.
+• Caching opportunities.
+• Slow or high-complexity code paths.
+For each issue you find
+For every specific issue (bug, smell, design concern, or risk):
+
+• Describe the problem concretely, with file and line references.
+• Present 2–3 options, including "do nothing" where that's reasonable.
+• For each option, specify: implementation effort, risk, impact on other code, and maintenance burden.
+• Give me your recommended option and why, mapped to my preferences above.
+• Then explicitly ask whether I agree or want to choose a different direction before proceeding.
+Workflow and interaction
+
+• Do not assume my priorities on timeline or scale.
+• After each section, pause and ask for my feedback before moving on.
+BEFORE YOU START:
+Ask if I want one of two options:
+1/ BIG CHANGE: Work through this interactively, one section at a time (Architecture → Code Quality → Tests → Performance) with at most 4 top issues in each section.
+2/ SMALL CHANGE: Work through interactively ONE question per review section
+
+FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion. Also NUMBER issues and then give LETTERS for options and when using AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. Make the recommended option always the 1st option.
+
 ## Quick Reference
 
 ```bash

package/__tests__/board-handler.test.ts

@@ -16,12 +16,14 @@ function mockApi(overrides: Partial<AgentApi> = {}): AgentApi {
 
 function makeBoardInfo(opts: Partial<{
   boardId: string;
+  workspaceId: string;
   myColumnIds: string[];
   columns: BoardInfo['board']['columns'];
 }> = {}): BoardInfo {
   return {
     board: {
       id: opts.boardId ?? 'board-1',
+      workspaceId: opts.workspaceId ?? 'ws-1',
       myColumnIds: opts.myColumnIds ?? ['col-1'],
       columns: opts.columns ?? [{
         id: 'col-1',
@@ -70,13 +72,14 @@ describe('BoardHandler', () => {
   });
 
   describe('initialize', () => {
-    it('sets boardId and myColumnIds from API response', async () => {
-      const info = makeBoardInfo({ boardId: 'b-42', myColumnIds: ['c-1', 'c-2'] });
+    it('sets boardId, workspaceId and myColumnIds from API response', async () => {
+      const info = makeBoardInfo({ boardId: 'b-42', workspaceId: 'ws-99', myColumnIds: ['c-1', 'c-2'] });
       (api.get as jest.Mock).mockResolvedValue(info);
 
       const result = await handler.initialize();
 
-      expect(result).toBe('b-42');
+      // initialize() returns workspaceId for channel subscription
+      expect(result).toBe('ws-99');
       expect(handler.getBoardId()).toBe('b-42');
       expect(api.get).toHaveBeenCalledWith('/api/agent/board');
     });

package/dist/connection.js

@@ -79,14 +79,18 @@ export function createConnection(opts) {
     const commandChannel = `agent:${opts.agentId}`;
     const commandSub = client.newSubscription(commandChannel);
     commandSub.on('publication', async (ctx) => {
+        console.log(`[WS] Received message on ${commandChannel}:`, JSON.stringify(ctx.data));
         const command = ctx.data;
-        if (!command || !command.type)
+        if (!command || !command.type) {
+            console.warn('[WS] Ignoring message without type:', JSON.stringify(ctx.data));
             return;
+        }
         const handler = handlers[command.type];
         if (!handler) {
-            console.error(`Unknown command type: ${command.type}`);
+            console.error(`[WS] Unknown command type: ${command.type}`);
             return;
         }
+        console.log(`[WS] Handling command: type=${command.type} id=${command.id}`);
         try {
             const response = await handler(command);
             await client.publish(commandChannel, response);
@@ -110,6 +114,18 @@ export function createConnection(opts) {
     client.on('connecting', (ctx) => {
         console.log(`Connecting: ${ctx.reason} (code ${ctx.code})`);
     });
+    commandSub.on('subscribed', (ctx) => {
+        console.log(`[WS] Subscribed to ${commandChannel} (recovered=${ctx.wasRecovering})`);
+    });
+    commandSub.on('subscribing', (ctx) => {
+        console.log(`[WS] Subscribing to ${commandChannel}: ${ctx.reason} (code ${ctx.code})`);
+    });
+    commandSub.on('error', (ctx) => {
+        console.error(`[WS] Subscription error on ${commandChannel}:`, ctx.error);
+    });
+    commandSub.on('unsubscribed', (ctx) => {
+        console.log(`[WS] Unsubscribed from ${commandChannel}: ${ctx.reason} (code ${ctx.code})`);
+    });
     commandSub.subscribe();
     client.connect();
     return { client, commandSub };

package/dist/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-cloud/agent-controller",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/connection.ts

@@ -8,6 +8,7 @@ import { handleConfig } from './handlers/config.js';
 import { handlePair } from './handlers/pair.js';
 import { handleStop } from './handlers/stop.js';
 import { handleBackup } from './handlers/backup.js';
+import { handleChatListSessions, handleChatHistory, handleChatSend } from './handlers/chat.js';
 
 export interface ConnectionOptions {
   url: string;
@@ -93,14 +94,37 @@ export function createConnection(opts: ConnectionOptions): {
   const commandSub = client.newSubscription(commandChannel);
 
   commandSub.on('publication', async (ctx) => {
+    console.log(`[WS] Received message on ${commandChannel}:`, JSON.stringify(ctx.data));
     const command = ctx.data as AgentCommand;
-    if (!command || !command.type) return;
+    if (!command || !command.type) {
+      console.warn('[WS] Ignoring message without type:', JSON.stringify(ctx.data));
+      return;
+    }
+
+    // Chat commands — handle before generic dispatch
+    if (command.type === 'chat_list_sessions' || command.type === 'chat_history' || command.type === 'chat_send') {
+      const publishFn = async (data: unknown): Promise<void> => { await client.publish(commandChannel, data); };
+      console.log(`[WS] Handling chat command: type=${command.type} id=${command.id}`);
+      switch (command.type) {
+        case 'chat_list_sessions':
+          handleChatListSessions(command, publishFn).catch(console.error);
+          break;
+        case 'chat_history':
+          handleChatHistory(command, publishFn).catch(console.error);
+          break;
+        case 'chat_send':
+          handleChatSend(command, publishFn, opts.agentId).catch(console.error);
+          break;
+      }
+      return;
+    }
 
     const handler = handlers[command.type];
     if (!handler) {
-      console.error(`Unknown command type: ${command.type}`);
+      console.error(`[WS] Unknown command type: ${command.type}`);
       return;
     }
+    console.log(`[WS] Handling command: type=${command.type} id=${command.id}`);
 
     try {
       const response = await handler(command);
@@ -128,6 +152,22 @@ export function createConnection(opts: ConnectionOptions): {
     console.log(`Connecting: ${ctx.reason} (code ${ctx.code})`);
   });
 
+  commandSub.on('subscribed', (ctx) => {
+    console.log(`[WS] Subscribed to ${commandChannel} (recovered=${ctx.wasRecovering})`);
+  });
+
+  commandSub.on('subscribing', (ctx) => {
+    console.log(`[WS] Subscribing to ${commandChannel}: ${ctx.reason} (code ${ctx.code})`);
+  });
+
+  commandSub.on('error', (ctx) => {
+    console.error(`[WS] Subscription error on ${commandChannel}:`, ctx.error);
+  });
+
+  commandSub.on('unsubscribed', (ctx) => {
+    console.log(`[WS] Unsubscribed from ${commandChannel}: ${ctx.reason} (code ${ctx.code})`);
+  });
+
   commandSub.subscribe();
   client.connect();
 

package/src/handlers/board-handler.ts

@@ -8,6 +8,7 @@ export class BoardHandler {
   private boardState: BoardState = { state: 'idle', cardId: null };
   private myColumnIds: string[] = [];
   private boardId: string | null = null;
+  private workspaceId: string | null = null;
   private api: AgentApi;
 
   constructor(api: AgentApi) {
@@ -18,12 +19,14 @@ export class BoardHandler {
     try {
       const data = await this.api.get('/api/agent/board') as BoardInfo;
       this.boardId = data.board.id;
+      this.workspaceId = data.board.workspaceId;
       this.myColumnIds = data.board.myColumnIds;
-      console.log(`Board initialized: ${this.boardId}, watching ${this.myColumnIds.length} column(s)`);
+      console.log(`Board initialized: ${this.boardId} (workspace: ${this.workspaceId}), watching ${this.myColumnIds.length} column(s)`);
 
       // Backfill: check for existing unassigned cards in my columns
       await this.checkQueue(data);
-      return this.boardId;
+      // Return workspaceId for channel subscription (board:<workspaceId>)
+      return this.workspaceId;
     } catch (err) {
       console.error('Board initialization failed:', err instanceof Error ? err.message : err);
       return null;

package/src/handlers/chat.ts

@@ -0,0 +1,79 @@
+import type { AgentCommand } from '../types.js';
+import { getChatProvider } from '../openclaw/index.js';
+
+export async function handleChatListSessions(
+  command: AgentCommand,
+  publish: (data: unknown) => Promise<void>,
+): Promise<void> {
+  const provider = getChatProvider();
+  if (!provider) {
+    await publish({ type: 'chat_sessions_response', correlationId: command.id, sessions: [], error: 'Chat provider not initialized' });
+    return;
+  }
+  try {
+    const sessions = await provider.listSessions();
+    await publish({ type: 'chat_sessions_response', correlationId: command.id, sessions });
+  } catch (err) {
+    await publish({ type: 'chat_sessions_response', correlationId: command.id, sessions: [], error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+export async function handleChatHistory(
+  command: AgentCommand,
+  publish: (data: unknown) => Promise<void>,
+): Promise<void> {
+  const { sessionKey, limit } = command.payload as { sessionKey: string; limit?: number };
+  const provider = getChatProvider();
+  if (!provider) {
+    await publish({ type: 'chat_history_response', correlationId: command.id, messages: [], error: 'Chat provider not initialized' });
+    return;
+  }
+  try {
+    const messages = await provider.getHistory(sessionKey, limit ?? 200);
+    await publish({ type: 'chat_history_response', correlationId: command.id, messages });
+  } catch (err) {
+    await publish({ type: 'chat_history_response', correlationId: command.id, messages: [], error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+export async function handleChatSend(
+  command: AgentCommand,
+  publish: (data: unknown) => Promise<void>,
+  agentId: string,
+): Promise<void> {
+  const { sessionKey, text, attachments } = command.payload as {
+    sessionKey: string;
+    text: string;
+    attachments?: Array<{ type: 'image'; mimeType: string; content: string }>;
+  };
+  const correlationId = command.id;
+
+  // Typing indicator
+  await publish({ type: 'chat_typing', agentId, state: true }).catch(() => {});
+
+  const provider = getChatProvider();
+  if (!provider) {
+    await publish({ type: 'chat_response', correlationId, sessionKey, text: '', error: 'Chat provider not initialized' });
+    return;
+  }
+
+  try {
+    await provider.sendMessage({
+      sessionKey,
+      text,
+      idempotencyKey: correlationId,
+      attachments, // base64 inline — Centrifugo limit raised to 10MB
+      onDelta: async (accumulated) => {
+        await publish({ type: 'chat_delta', correlationId, sessionKey, text: accumulated }).catch(() => {});
+      },
+      onDone: async (finalText) => {
+        await publish({ type: 'chat_response', correlationId, sessionKey, text: finalText }).catch(() => {});
+      },
+      onError: async (error) => {
+        await publish({ type: 'chat_response', correlationId, sessionKey, text: '', error }).catch(() => {});
+      },
+    });
+  } catch (err) {
+    await publish({ type: 'chat_response', correlationId, sessionKey, text: '', error: err instanceof Error ? err.message : String(err) }).catch(() => {});
+  }
+}

package/src/index.ts

@@ -2,6 +2,7 @@ import { createConnection } from './connection.js';
 import { startHeartbeat } from './heartbeat.js';
 import { createAgentApi } from './api.js';
 import { BoardHandler } from './handlers/board-handler.js';
+import { createChatProvider } from './openclaw/index.js';
 import type { BoardEvent } from './types.js';
 
 function requireEnv(name: string): string {
@@ -30,6 +31,21 @@ export function main(): void {
 
   const { client } = createConnection({ url, token, agentId, backendUrl: backendUrl || undefined });
 
+  // Chat provider via OpenClaw Gateway WS
+  const gatewayWsUrl = process.env.OPENCLAW_GATEWAY_WS || 'ws://localhost:18789';
+  const gatewayToken = process.env.OPENCLAW_GATEWAY_TOKEN || '';
+
+  if (gatewayToken) {
+    const chatProvider = createChatProvider(gatewayWsUrl, gatewayToken);
+    chatProvider.connect().then(() => {
+      console.log('OpenClaw Gateway WS connected (chat provider ready)');
+    }).catch((e) => {
+      console.warn('Chat provider connect failed:', e instanceof Error ? e.message : e);
+    });
+  } else {
+    console.warn('OPENCLAW_GATEWAY_TOKEN not set, chat provider disabled');
+  }
+
   // Board handler (optional — requires BACKEND_URL and AGENT_TOKEN)
   let boardHandler: BoardHandler | null = null;
   const apiBaseUrl = process.env.BACKEND_URL || backendUrl;
@@ -38,13 +54,13 @@ export function main(): void {
     boardHandler = new BoardHandler(api);
 
     // Initialize board handler after connection is established
-    boardHandler.initialize().then((boardId) => {
-      if (!boardId) {
+    boardHandler.initialize().then((workspaceId) => {
+      if (!workspaceId) {
         console.log('No board found for this agent, board handler dormant');
         return;
       }
 
-      const boardChannel = `board:${boardId}`;
+      const boardChannel = `board:${workspaceId}`;
       const boardSub = client.newSubscription(boardChannel);
 
       boardSub.on('publication', (ctx) => {

package/src/openclaw/gateway-adapter.ts

@@ -0,0 +1,129 @@
+import { GatewayClient } from './gateway-client.js';
+import type { IChatProvider, ChatSession, ChatMessage, ChatAttachment } from './types.js';
+
+export class OpenclawGatewayAdapter implements IChatProvider {
+  private client: GatewayClient;
+  private streamCallbacks = new Map<string, {
+    onDelta?: (text: string) => void;
+    onDone?: (text: string) => void;
+    onError?: (error: string) => void;
+    lastText: string;
+  }>();
+
+  constructor(url: string, token: string) {
+    this.client = new GatewayClient(url, token);
+    this.client.setEventHandler(this.handleEvent.bind(this));
+  }
+
+  async connect(): Promise<void> {
+    await this.client.connect();
+  }
+
+  disconnect(): void {
+    this.client.disconnect();
+  }
+
+  isConnected(): boolean {
+    return this.client.isConnected();
+  }
+
+  async listSessions(): Promise<ChatSession[]> {
+    const result = await this.client.request('sessions.list', {});
+    return (result?.sessions ?? []).map((s: any) => ({
+      key: s.key,
+      sessionId: s.sessionId ?? '',
+      kind: s.kind ?? 'direct',
+      updatedAt: s.updatedAt ?? 0,
+      model: s.model,
+    }));
+  }
+
+  async getHistory(sessionKey: string, limit = 200): Promise<ChatMessage[]> {
+    const result = await this.client.request('chat.history', { sessionKey, limit });
+    return (result?.messages ?? [])
+      .filter((m: any) => m.role === 'user' || m.role === 'assistant')
+      .map((m: any) => {
+        const content = Array.isArray(m.content)
+          ? m.content.filter((c: any) => c.type === 'text').map((c: any) => c.text).join('')
+          : String(m.content ?? '');
+        return {
+          role: m.role,
+          content,
+          timestamp: typeof m.timestamp === 'number'
+            ? new Date(m.timestamp).toISOString()
+            : m.timestamp ?? new Date().toISOString(),
+        };
+      });
+  }
+
+  async sendMessage(params: {
+    sessionKey: string;
+    text: string;
+    idempotencyKey: string;
+    attachments?: ChatAttachment[];
+    onDelta?: (text: string) => void;
+    onDone?: (text: string) => void;
+    onError?: (error: string) => void;
+  }): Promise<void> {
+    // Register stream callbacks BEFORE sending
+    this.streamCallbacks.set(params.idempotencyKey, {
+      onDelta: params.onDelta,
+      onDone: params.onDone,
+      onError: params.onError,
+      lastText: '',
+    });
+
+    const payload: any = {
+      sessionKey: params.sessionKey,
+      message: params.text,
+      deliver: false,
+      idempotencyKey: params.idempotencyKey,
+    };
+    if (params.attachments?.length) {
+      payload.attachments = params.attachments;
+    }
+
+    try {
+      await this.client.request('chat.send', payload);
+      // Request accepted — response comes via events
+    } catch (err) {
+      this.streamCallbacks.delete(params.idempotencyKey);
+      params.onError?.(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async abort(sessionKey: string, runId?: string): Promise<void> {
+    await this.client.request('chat.abort', { sessionKey, runId }).catch(() => {});
+  }
+
+  private handleEvent(event: { event: string; payload: any }): void {
+    const data = event.payload;
+    if (!data || !data.sessionKey) return;
+
+    // Stream events have runId matching idempotencyKey
+    const runId = data.runId;
+    const cb = runId ? this.streamCallbacks.get(runId) : null;
+    if (!cb) return;
+
+    if (data.state === 'delta' && data.message != null) {
+      // message is accumulated text
+      const text = typeof data.message === 'string'
+        ? data.message
+        : Array.isArray(data.message)
+          ? data.message.filter((c: any) => c.type === 'text').map((c: any) => c.text).join('')
+          : '';
+      cb.lastText = text;
+      cb.onDelta?.(text);
+    } else if (data.state === 'final') {
+      this.streamCallbacks.delete(runId!);
+      cb.onDone?.(cb.lastText);
+    } else if (data.state === 'aborted') {
+      this.streamCallbacks.delete(runId!);
+      cb.onDone?.(cb.lastText); // still send whatever we have
+    } else if (data.state === 'error') {
+      this.streamCallbacks.delete(runId!);
+      const errMsg = typeof data.error === 'string' ? data.error : data.error?.message ?? 'Unknown error';
+      cb.onError?.(errMsg);
+    }
+  }
+}

package/src/openclaw/gateway-client.ts

@@ -0,0 +1,131 @@
+import WebSocket from 'ws';
+import { randomUUID } from 'crypto';
+
+interface PendingRequest {
+  resolve: (payload: any) => void;
+  reject: (err: Error) => void;
+}
+
+export type EventHandler = (event: { event: string; payload: any; seq?: number }) => void;
+
+export class GatewayClient {
+  private ws: WebSocket | null = null;
+  private pending = new Map<string, PendingRequest>();
+  private onEvent: EventHandler | null = null;
+  private connected = false;
+  private token: string;
+  private url: string;
+
+  constructor(url: string, token: string) {
+    this.url = url;
+    this.token = token;
+  }
+
+  setEventHandler(handler: EventHandler): void {
+    this.onEvent = handler;
+  }
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.url);
+
+      this.ws.on('open', () => {
+        // Wait for connect.challenge event, then authenticate
+      });
+
+      this.ws.on('message', (raw) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          this.handleMessage(msg);
+        } catch {}
+      });
+
+      this.ws.on('error', (e) => {
+        if (!this.connected) reject(e);
+      });
+
+      this.ws.on('close', () => {
+        this.connected = false;
+        this.flushPending(new Error('Connection closed'));
+      });
+
+      // Wait for connect.challenge → authenticate → resolve
+      const origHandler = this.onEvent;
+      this.onEvent = async (ev) => {
+        if (ev.event === 'connect.challenge') {
+          try {
+            await this.request('connect', {
+              auth: { token: this.token },
+              scopes: ['operator.admin'],
+              caps: [],
+            });
+            this.connected = true;
+            this.onEvent = origHandler;
+            resolve();
+          } catch (e) {
+            reject(e);
+          }
+        }
+      };
+
+      setTimeout(() => {
+        if (!this.connected) reject(new Error('Connect timeout'));
+      }, 10_000);
+    });
+  }
+
+  disconnect(): void {
+    this.ws?.close();
+    this.ws = null;
+    this.connected = false;
+    this.flushPending(new Error('Disconnected'));
+  }
+
+  isConnected(): boolean {
+    return this.connected && this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  request(method: string, params: any): Promise<any> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error('Not connected'));
+      }
+
+      const id = randomUUID();
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ type: 'req', id, method, params }));
+
+      // Timeout per request
+      setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`Request timeout: ${method}`));
+        }
+      }, 120_000);
+    });
+  }
+
+  private handleMessage(msg: any): void {
+    if (msg.type === 'event') {
+      this.onEvent?.(msg);
+      return;
+    }
+    if (msg.type === 'res') {
+      const req = this.pending.get(msg.id);
+      if (!req) return;
+      this.pending.delete(msg.id);
+      if (msg.ok) {
+        req.resolve(msg.payload);
+      } else {
+        req.reject(new Error(msg.error?.message ?? 'Request failed'));
+      }
+    }
+  }
+
+  private flushPending(err: Error): void {
+    for (const [, req] of this.pending) {
+      req.reject(err);
+    }
+    this.pending.clear();
+  }
+}

package/src/openclaw/index.ts

@@ -0,0 +1,17 @@
+export { OpenclawGatewayAdapter } from './gateway-adapter.js';
+export type { IChatProvider, ChatSession, ChatMessage, ChatAttachment } from './types.js';
+
+import { OpenclawGatewayAdapter } from './gateway-adapter.js';
+import type { IChatProvider } from './types.js';
+
+let _provider: IChatProvider | null = null;
+
+export function createChatProvider(url: string, token: string): IChatProvider & { connect(): Promise<void>; disconnect(): void } {
+  const adapter = new OpenclawGatewayAdapter(url, token);
+  _provider = adapter;
+  return adapter;
+}
+
+export function getChatProvider(): IChatProvider | null {
+  return _provider;
+}

package/src/openclaw/types.ts

@@ -0,0 +1,41 @@
+export interface ChatSession {
+  key: string;
+  sessionId: string;
+  kind: string;
+  updatedAt: number;
+  model?: string;
+}
+
+export interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;        // normalized to plain text
+  timestamp: string;      // ISO 8601
+}
+
+export interface ChatAttachment {
+  type: 'image';
+  mimeType: string;
+  content: string;        // base64
+}
+
+export interface IChatProvider {
+  listSessions(): Promise<ChatSession[]>;
+  getHistory(sessionKey: string, limit?: number): Promise<ChatMessage[]>;
+
+  /**
+   * Send message. Returns after the agent finishes (full response).
+   * Calls onDelta with accumulated text during streaming.
+   * Calls onDone when agent response is complete.
+   */
+  sendMessage(params: {
+    sessionKey: string;
+    text: string;
+    idempotencyKey: string;
+    attachments?: ChatAttachment[];
+    onDelta?: (accumulatedText: string) => void;
+    onDone?: (finalText: string) => void;
+    onError?: (error: string) => void;
+  }): Promise<void>;
+
+  abort(sessionKey: string, runId?: string): Promise<void>;
+}

package/src/types.ts

@@ -4,7 +4,9 @@
  *   heartbeat:<agentId> — heartbeat publications from agent
  */
 
-export type CommandType = 'exec' | 'restart' | 'deploy' | 'config' | 'pair' | 'stop' | 'backup';
+export type CommandType =
+  | 'exec' | 'restart' | 'deploy' | 'config' | 'pair' | 'stop' | 'backup'
+  | 'chat_list_sessions' | 'chat_history' | 'chat_send';
 
 export interface AgentCommand {
   id: string;
@@ -56,6 +58,7 @@ export interface BoardEvent {
 export interface BoardInfo {
   board: {
     id: string;
+    workspaceId: string;
     columns: Array<{
       id: string;
       name: string;