@openclaw-cloud/agent-controller 0.1.0

package/src/connection.ts

@@ -0,0 +1,135 @@
+import { Centrifuge, Subscription } from 'centrifuge';
+import WebSocket from 'ws';
+import type { AgentCommand, AgentResponse } from './types.js';
+import { handleExec } from './handlers/exec.js';
+import { handleRestart } from './handlers/restart.js';
+import { handleDeploy } from './handlers/deploy.js';
+import { handleConfig } from './handlers/config.js';
+import { handlePair } from './handlers/pair.js';
+import { handleStop } from './handlers/stop.js';
+import { handleBackup } from './handlers/backup.js';
+
+export interface ConnectionOptions {
+  url: string;
+  token: string;
+  agentId: string;
+  backendUrl?: string;
+}
+
+const handlers: Record<string, (cmd: AgentCommand) => Promise<AgentResponse>> = {
+  exec: handleExec,
+  restart: handleRestart,
+  deploy: handleDeploy,
+  config: handleConfig,
+  pair: handlePair,
+  stop: handleStop,
+  backup: handleBackup,
+};
+
+async function fetchCentrifugoToken(backendUrl: string, agentToken: string, agentId: string): Promise<string> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch(`${backendUrl}/api/internal/centrifugo-token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${agentToken}`,
+      },
+      body: JSON.stringify({ agentId }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    }
+    const data = await res.json() as { token: string };
+    return data.token;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function createConnection(opts: ConnectionOptions): {
+  client: Centrifuge;
+  commandSub: Subscription;
+} {
+  const centrifugeOpts: Record<string, unknown> = {
+    websocket: WebSocket,
+    name: 'agent-controller',
+    minReconnectDelay: 1000,
+    maxReconnectDelay: 30000,
+  };
+
+  if (opts.backendUrl) {
+    // Dynamic JWT: fetch fresh token on every connect/reconnect
+    centrifugeOpts.getToken = async () => {
+      console.log('Fetching Centrifugo JWT from backend...');
+      try {
+        const token = await fetchCentrifugoToken(opts.backendUrl!, opts.token, opts.agentId);
+        console.log('Got Centrifugo JWT');
+        return token;
+      } catch (err) {
+        console.error('Failed to fetch Centrifugo JWT:', err instanceof Error ? err.message : err);
+        // Retry once
+        try {
+          const token = await fetchCentrifugoToken(opts.backendUrl!, opts.token, opts.agentId);
+          console.log('Got Centrifugo JWT (retry)');
+          return token;
+        } catch (retryErr) {
+          console.error('JWT fetch retry failed:', retryErr instanceof Error ? retryErr.message : retryErr);
+          throw retryErr;
+        }
+      }
+    };
+  } else {
+    // Fallback: use raw token (backward compat, won't work with Centrifugo JWT validation)
+    console.warn('BACKEND_INTERNAL_URL not set, using AGENT_TOKEN directly (may not work)');
+    centrifugeOpts.token = opts.token;
+  }
+
+  const client = new Centrifuge(opts.url, centrifugeOpts);
+
+  const commandChannel = `agent:${opts.agentId}`;
+  const commandSub = client.newSubscription(commandChannel);
+
+  commandSub.on('publication', async (ctx) => {
+    const command = ctx.data as AgentCommand;
+    if (!command || !command.type) return;
+
+    const handler = handlers[command.type];
+    if (!handler) {
+      console.error(`Unknown command type: ${command.type}`);
+      return;
+    }
+
+    try {
+      const response = await handler(command);
+      await client.publish(commandChannel, response);
+    } catch (err) {
+      const errorResponse: AgentResponse = {
+        id: command.id,
+        type: command.type,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+      await client.publish(commandChannel, errorResponse);
+    }
+  });
+
+  client.on('connected', (ctx) => {
+    console.log(`Connected to Centrifugo via ${ctx.transport}`);
+  });
+
+  client.on('disconnected', (ctx) => {
+    console.log(`Disconnected: ${ctx.reason} (code ${ctx.code})`);
+  });
+
+  client.on('connecting', (ctx) => {
+    console.log(`Connecting: ${ctx.reason} (code ${ctx.code})`);
+  });
+
+  commandSub.subscribe();
+  client.connect();
+
+  return { client, commandSub };
+}

package/src/handlers/backup.ts

@@ -0,0 +1,97 @@
+import { exec } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+const WORKSPACE_DIR = '/home/node/.openclaw/workspace';
+const BACKUP_DIR = '/tmp';
+const TAR_TIMEOUT = 120_000;
+const UPLOAD_TIMEOUT = 120_000;
+
+export function handleBackup(command: AgentCommand): Promise<AgentResponse> {
+  const uploadUrl = command.payload.uploadUrl as string;
+  if (!uploadUrl) {
+    return Promise.resolve({
+      id: command.id,
+      type: 'backup',
+      success: false,
+      error: 'Missing "uploadUrl" in payload',
+    });
+  }
+
+  const timestamp = Date.now();
+  const filename = `backup-${timestamp}.tar.gz`;
+  const archivePath = path.join(BACKUP_DIR, filename);
+
+  return createArchive(archivePath)
+    .then(() => uploadArchive(archivePath, uploadUrl))
+    .then(async (size) => {
+      await cleanup(archivePath);
+      return {
+        id: command.id,
+        type: 'backup' as const,
+        success: true,
+        data: { size, filename },
+      };
+    })
+    .catch(async (err) => {
+      await cleanup(archivePath);
+      return {
+        id: command.id,
+        type: 'backup' as const,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    });
+}
+
+function createArchive(archivePath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    exec(
+      `tar -czf ${archivePath} -C ${path.dirname(WORKSPACE_DIR)} ${path.basename(WORKSPACE_DIR)}`,
+      { timeout: TAR_TIMEOUT },
+      (error, _stdout, stderr) => {
+        if (error) {
+          reject(new Error(`tar failed: ${stderr.toString() || error.message}`));
+        } else {
+          resolve();
+        }
+      },
+    );
+  });
+}
+
+async function uploadArchive(archivePath: string, uploadUrl: string): Promise<number> {
+  const stat = await fs.stat(archivePath);
+  const fileBuffer = await fs.readFile(archivePath);
+
+  const boundary = `----backup-${Date.now()}`;
+  const filename = path.basename(archivePath);
+
+  const header = Buffer.from(
+    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename}"\r\nContent-Type: application/gzip\r\n\r\n`,
+  );
+  const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+  const body = Buffer.concat([header, fileBuffer, footer]);
+
+  const response = await fetch(uploadUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}` },
+    body,
+    signal: AbortSignal.timeout(UPLOAD_TIMEOUT),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
+  }
+
+  return stat.size;
+}
+
+async function cleanup(archivePath: string): Promise<void> {
+  try {
+    await fs.unlink(archivePath);
+  } catch {
+    // ignore cleanup errors
+  }
+}

package/src/handlers/config.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+const CONFIG_DIR = '/etc/openclaw';
+
+export function handleConfig(command: AgentCommand): Promise<AgentResponse> {
+  const filename = command.payload.filename as string;
+  const content = command.payload.content as string;
+
+  if (!filename || content === undefined) {
+    return Promise.resolve({
+      id: command.id,
+      type: 'config',
+      success: false,
+      error: 'Missing "filename" or "content" in payload',
+    });
+  }
+
+  const configPath = path.join(CONFIG_DIR, path.basename(filename));
+
+  return fs.mkdir(CONFIG_DIR, { recursive: true })
+    .then(() => fs.writeFile(configPath, content, 'utf-8'))
+    .then(() => {
+      return new Promise<AgentResponse>((resolve) => {
+        exec('openclaw gateway restart', { timeout: 30_000 }, (error, stdout, stderr) => {
+          resolve({
+            id: command.id,
+            type: 'config',
+            success: !error,
+            data: {
+              path: configPath,
+              stdout: stdout.toString(),
+              stderr: stderr.toString(),
+            },
+            ...(error ? { error: error.message } : {}),
+          });
+        });
+      });
+    })
+    .catch((err) => ({
+      id: command.id,
+      type: 'config',
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+}

package/src/handlers/deploy.ts

@@ -0,0 +1,32 @@
+import { exec } from 'node:child_process';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+export function handleDeploy(command: AgentCommand): Promise<AgentResponse> {
+  return new Promise((resolve) => {
+    exec('npm i -g openclaw', { timeout: 120_000 }, (installErr, installOut, installStderr) => {
+      if (installErr) {
+        resolve({
+          id: command.id,
+          type: 'deploy',
+          success: false,
+          data: { stdout: installOut.toString(), stderr: installStderr.toString() },
+          error: `Install failed: ${installErr.message}`,
+        });
+        return;
+      }
+
+      exec('openclaw gateway restart', { timeout: 30_000 }, (restartErr, restartOut, restartStderr) => {
+        resolve({
+          id: command.id,
+          type: 'deploy',
+          success: !restartErr,
+          data: {
+            install: { stdout: installOut.toString(), stderr: installStderr.toString() },
+            restart: { stdout: restartOut.toString(), stderr: restartStderr.toString() },
+          },
+          ...(restartErr ? { error: `Restart failed: ${restartErr.message}` } : {}),
+        });
+      });
+    });
+  });
+}

package/src/handlers/exec.ts

@@ -0,0 +1,32 @@
+import { exec } from 'node:child_process';
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+const EXEC_TIMEOUT = 60_000;
+
+export function handleExec(command: AgentCommand): Promise<AgentResponse> {
+  const cmd = command.payload.command as string;
+  if (!cmd) {
+    return Promise.resolve({
+      id: command.id,
+      type: 'exec',
+      success: false,
+      error: 'Missing "command" in payload',
+    });
+  }
+
+  return new Promise((resolve) => {
+    exec(cmd, { timeout: EXEC_TIMEOUT }, (error, stdout, stderr) => {
+      resolve({
+        id: command.id,
+        type: 'exec',
+        success: !error,
+        data: {
+          exitCode: error ? (error as NodeJS.ErrnoException & { code?: number }).code ?? 1 : 0,
+          stdout: stdout.toString(),
+          stderr: stderr.toString(),
+        },
+        ...(error ? { error: error.message } : {}),
+      });
+    });
+  });
+}

package/src/handlers/pair.ts

@@ -0,0 +1,26 @@
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+export function handlePair(command: AgentCommand): Promise<AgentResponse> {
+  const pairToken = command.payload.token as string;
+  const targetId = command.payload.targetId as string;
+
+  if (!pairToken || !targetId) {
+    return Promise.resolve({
+      id: command.id,
+      type: 'pair',
+      success: false,
+      error: 'Missing "token" or "targetId" in payload',
+    });
+  }
+
+  return Promise.resolve({
+    id: command.id,
+    type: 'pair',
+    success: true,
+    data: {
+      paired: true,
+      targetId,
+      agentId: process.env.AGENT_ID,
+    },
+  });
+}

package/src/handlers/restart.ts

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

package/src/handlers/stop.ts

@@ -0,0 +1,17 @@
+import type { AgentCommand, AgentResponse } from '../types.js';
+
+export function handleStop(command: AgentCommand): Promise<AgentResponse> {
+  const response: AgentResponse = {
+    id: command.id,
+    type: 'stop',
+    success: true,
+    data: { message: 'Shutting down gracefully' },
+  };
+
+  setTimeout(() => {
+    console.log('Agent stopping gracefully...');
+    process.exit(0);
+  }, 500);
+
+  return Promise.resolve(response);
+}

package/src/heartbeat.ts

@@ -0,0 +1,73 @@
+import os from 'node:os';
+import type { HeartbeatPayload } from './types.js';
+
+const HEARTBEAT_INTERVAL = 30_000;
+const HEARTBEAT_CHANNEL = 'heartbeat:data';
+
+export interface HeartbeatOptions {
+  centrifugoInternalUrl: string;
+  centrifugoApiKey: string;
+  agentId: string;
+}
+
+function getMetrics(): HeartbeatPayload['metrics'] {
+  const cpus = os.cpus();
+  const cpuUsage = cpus.reduce((acc, cpu) => {
+    const total = Object.values(cpu.times).reduce((a, b) => a + b, 0);
+    return acc + (1 - cpu.times.idle / total);
+  }, 0) / cpus.length;
+
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+
+  return {
+    cpu: Math.round(cpuUsage * 100) / 100,
+    mem: Math.round(((totalMem - freeMem) / totalMem) * 100) / 100,
+    uptime: os.uptime(),
+  };
+}
+
+async function publishHeartbeat(opts: HeartbeatOptions): Promise<void> {
+  const payload: HeartbeatPayload = {
+    type: 'heartbeat',
+    agentId: opts.agentId,
+    ts: Date.now(),
+    metrics: getMetrics(),
+  };
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+
+  try {
+    const res = await fetch(`${opts.centrifugoInternalUrl}/api/publish`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `apikey ${opts.centrifugoApiKey}`,
+      },
+      body: JSON.stringify({ channel: HEARTBEAT_CHANNEL, data: payload }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      console.error(`Heartbeat publish failed (HTTP ${res.status}): ${body}`);
+    }
+  } catch (err) {
+    if ((err as Error).name === 'AbortError') {
+      console.error('Heartbeat publish timed out');
+    } else {
+      console.error('Heartbeat publish failed:', err instanceof Error ? err.message : err);
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function startHeartbeat(opts: HeartbeatOptions): NodeJS.Timeout {
+  const send = () => { publishHeartbeat(opts).catch(() => {}); };
+  send();
+  return setInterval(send, HEARTBEAT_INTERVAL);
+}
+
+export { getMetrics };

package/src/index.ts

@@ -0,0 +1,47 @@
+import { createConnection } from './connection.js';
+import { startHeartbeat } from './heartbeat.js';
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Missing required environment variable: ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+export function main(): void {
+  const rawUrl = requireEnv('CENTRIFUGO_URL');
+  // Centrifuge client requires ws:// scheme
+  const url = rawUrl.replace(/^http:\/\//, 'ws://').replace(/^https:\/\//, 'wss://') + '/connection/websocket';
+  const token = requireEnv('AGENT_TOKEN');
+  const agentId = requireEnv('AGENT_ID');
+  const backendUrl = process.env.BACKEND_INTERNAL_URL || '';
+  const centrifugoInternalUrl = process.env.CENTRIFUGO_INTERNAL_URL || '';
+  const centrifugoApiKey = process.env.CENTRIFUGO_API_KEY || '';
+
+  console.log(`Starting agent-controller for agent: ${agentId}`);
+  if (backendUrl) {
+    console.log(`Backend URL: ${backendUrl} (JWT mode)`);
+  }
+
+  const { client } = createConnection({ url, token, agentId, backendUrl: backendUrl || undefined });
+
+  let heartbeatTimer: NodeJS.Timeout | undefined;
+  if (centrifugoInternalUrl && centrifugoApiKey) {
+    console.log(`Heartbeat via Centrifugo internal API: ${centrifugoInternalUrl}`);
+    heartbeatTimer = startHeartbeat({ centrifugoInternalUrl, centrifugoApiKey, agentId });
+  } else {
+    console.warn('CENTRIFUGO_INTERNAL_URL or CENTRIFUGO_API_KEY not set, heartbeat disabled');
+  }
+
+  const shutdown = () => {
+    console.log('Shutting down...');
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    client.disconnect();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Centrifugo channel layout:
+ *   agent:<agentId>     — commands from backend, responses from agent
+ *   heartbeat:<agentId> — heartbeat publications from agent
+ */
+
+export type CommandType = 'exec' | 'restart' | 'deploy' | 'config' | 'pair' | 'stop' | 'backup';
+
+export interface AgentCommand {
+  id: string;
+  type: CommandType;
+  payload: Record<string, unknown>;
+}
+
+export interface AgentResponse {
+  id: string;
+  type: CommandType;
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface HeartbeatPayload {
+  type: 'heartbeat';
+  agentId: string;
+  ts: number;
+  metrics: {
+    cpu: number;
+    mem: number;
+    uptime: number;
+  };
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}