@openclaw-cloud/agent-controller 0.1.3 → 0.1.5

package/src/commands/self-update.ts

@@ -0,0 +1,43 @@
+import { exec } from 'node:child_process';
+
+const PACKAGE_NAME = '@openclaw-cloud/agent-controller';
+
+function execAsync(cmd: string, timeout: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec(cmd, { timeout }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout.toString().trim());
+    });
+  });
+}
+
+export async function selfUpdate(currentVersion: string): Promise<void> {
+  console.log(`Current version: ${currentVersion}`);
+
+  let latestVersion: string;
+  try {
+    latestVersion = await execAsync(`npm view ${PACKAGE_NAME} version`, 10_000);
+  } catch (err) {
+    console.error('Failed to fetch latest version:', err instanceof Error ? err.message : err);
+    process.exit(1);
+    return; // unreachable in production; guards test flow when process.exit is mocked
+  }
+
+  console.log(`Latest version: ${latestVersion}`);
+
+  if (currentVersion === latestVersion) {
+    console.log('Already up to date.');
+    return;
+  }
+
+  console.log(`Updating from ${currentVersion} to ${latestVersion}...`);
+  try {
+    await execAsync(`npm install -g ${PACKAGE_NAME}@latest`, 120_000);
+    console.log(`Successfully updated to ${latestVersion}. Restarting...`);
+    process.exit(0);
+    return; // unreachable in production; guards test flow when process.exit is mocked
+  } catch (err) {
+    console.error('Update failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}

package/src/connection.ts

@@ -8,6 +8,10 @@ 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';
+import { handlePackageInstall } from './handlers/package-install.js';
+import { handleFileWrite } from './handlers/file-write.js';
+import { handleOnboardingComplete } from './handlers/onboarding.js';
 
 export interface ConnectionOptions {
   url: string;
@@ -24,6 +28,9 @@ const handlers: Record<string, (cmd: AgentCommand) => Promise<AgentResponse>> =
   pair: handlePair,
   stop: handleStop,
   backup: handleBackup,
+  package_install: handlePackageInstall,
+  file_write: handleFileWrite,
+  onboarding_complete: handleOnboardingComplete,
 };
 
 async function fetchCentrifugoToken(backendUrl: string, agentToken: string, agentId: string): Promise<string> {
@@ -100,6 +107,24 @@ export function createConnection(opts: ConnectionOptions): {
       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(`[WS] Unknown command type: ${command.type}`);

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/handlers/file-write.ts

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR ?? '/etc/openclaw/workspace';
+
+export async function handleFileWrite(command: AgentCommand): Promise<AgentResponse> {
+  const filePath = command.payload.path as string;
+  const content = command.payload.content;
+  const overwrite = (command.payload.overwrite as boolean | undefined) ?? true;
+
+  if (!filePath || content === undefined) {
+    return {
+      id: command.id,
+      type: 'file_write',
+      success: false,
+      error: 'Missing "path" or "content" in payload',
+    };
+  }
+
+  if (filePath.includes('..') || filePath.startsWith('/')) {
+    return {
+      id: command.id,
+      type: 'file_write',
+      success: false,
+      error: 'Invalid path: must not contain ".." or start with "/"',
+    };
+  }
+
+  const resolvedPath = path.join(WORKSPACE_DIR, filePath);
+
+  try {
+    if (!overwrite) {
+      try {
+        await fs.access(resolvedPath);
+        // File exists — skip
+        return {
+          id: command.id,
+          type: 'file_write',
+          success: true,
+          data: { path: resolvedPath, written: false, skipped: true },
+        };
+      } catch {
+        // File does not exist — proceed with write
+      }
+    }
+
+    await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+    await fs.writeFile(resolvedPath, content as string, 'utf-8');
+
+    return {
+      id: command.id,
+      type: 'file_write',
+      success: true,
+      data: { path: resolvedPath, written: true },
+    };
+  } catch (err) {
+    return {
+      id: command.id,
+      type: 'file_write',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/handlers/onboarding.ts

@@ -0,0 +1,19 @@
+import { exec } from 'node:child_process';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+export function handleOnboardingComplete(command: AgentCommand): Promise<AgentResponse> {
+  return new Promise((resolve) => {
+    exec('openclaw gateway restart', { timeout: 30_000 }, (error, stdout, stderr) => {
+      resolve({
+        id: command.id,
+        type: 'onboarding_complete',
+        success: !error,
+        data: {
+          stdout: stdout.toString(),
+          stderr: stderr.toString(),
+        },
+        ...(error ? { error: error.message } : {}),
+      });
+    });
+  });
+}

package/src/handlers/package-install.ts

@@ -0,0 +1,69 @@
+import { exec } from 'node:child_process';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+const INSTALL_TIMEOUT_MS = 300_000; // 5 minutes total
+
+function execPackage(cmd: string, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    exec(cmd, { timeout: timeoutMs }, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+export async function handlePackageInstall(command: AgentCommand): Promise<AgentResponse> {
+  const packages = command.payload.packages as {
+    apt?: string[];
+    npm?: string[];
+    pip?: string[];
+  } | undefined;
+
+  const apt = packages?.apt ?? [];
+  const npm = packages?.npm ?? [];
+  const pip = packages?.pip ?? [];
+
+  if (apt.length === 0 && npm.length === 0 && pip.length === 0) {
+    return {
+      id: command.id,
+      type: 'package_install',
+      success: true,
+      data: { installed: { apt: [], npm: [], pip: [] }, errors: [] },
+    };
+  }
+
+  const installed: { apt: string[]; npm: string[]; pip: string[] } = { apt: [], npm: [], pip: [] };
+  const errors: Array<{ name: string; error: string }> = [];
+  const deadline = Date.now() + INSTALL_TIMEOUT_MS;
+
+  async function tryInstall(pkg: string, cmd: string, type: 'apt' | 'npm' | 'pip'): Promise<void> {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      errors.push({ name: pkg, error: 'Install timeout exceeded' });
+      return;
+    }
+    try {
+      await execPackage(cmd, remaining);
+      installed[type].push(pkg);
+    } catch (err) {
+      errors.push({ name: pkg, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  for (const pkg of apt) {
+    await tryInstall(pkg, `apt-get install -y ${pkg}`, 'apt');
+  }
+  for (const pkg of npm) {
+    await tryInstall(pkg, `npm install -g ${pkg}`, 'npm');
+  }
+  for (const pkg of pip) {
+    await tryInstall(pkg, `pip install ${pkg}`, 'pip');
+  }
+
+  return {
+    id: command.id,
+    type: 'package_install',
+    success: errors.length === 0,
+    data: { installed, errors },
+  };
+}

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