openclaw-bridge 0.1.0

package/src/message-relay.ts

@@ -0,0 +1,155 @@
+import WebSocket from 'ws';
+import type { PluginLogger, MessageRelayConfig } from './types.js';
+
+type MessageHandler = (msg: any) => void;
+
+export class MessageRelayClient {
+  private ws: WebSocket | null = null;
+  private agentId: string;
+  private config: MessageRelayConfig;
+  private logger: PluginLogger;
+  private handlers = new Map<string, MessageHandler[]>();
+  private reconnectDelay = 1000;
+  private maxReconnectDelay = 30000;
+  private shouldReconnect = true;
+  private pendingCallbacks = new Map<string, {
+    resolve: (msg: any) => void;
+    reject: (err: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+  }>();
+
+  constructor(agentId: string, config: MessageRelayConfig, logger: PluginLogger) {
+    this.agentId = agentId;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.config.url);
+
+        this.ws.on('open', () => {
+          this.logger.info('Connected to Message Relay Hub');
+          this.reconnectDelay = 1000;
+
+          this.ws!.send(JSON.stringify({
+            type: 'auth',
+            agentId: this.agentId,
+            apiKey: this.config.apiKey,
+          }));
+        });
+
+        this.ws.on('message', (data) => {
+          let msg: any;
+          try {
+            msg = JSON.parse(data.toString());
+          } catch {
+            return;
+          }
+
+          if (msg.type === 'auth_ok') {
+            this.logger.info('Authenticated with Message Relay Hub');
+            resolve();
+            return;
+          }
+
+          if (msg.type === 'auth_error') {
+            this.logger.error(`Auth failed: ${msg.reason}`);
+            reject(new Error(msg.reason));
+            return;
+          }
+
+          // Check for pending request callbacks
+          if (msg.replyTo && this.pendingCallbacks.has(msg.replyTo)) {
+            const cb = this.pendingCallbacks.get(msg.replyTo)!;
+            clearTimeout(cb.timer);
+            this.pendingCallbacks.delete(msg.replyTo);
+            cb.resolve(msg);
+            return;
+          }
+
+          // Also check sessionId for handoff ack
+          if (msg.sessionId && this.pendingCallbacks.has(msg.sessionId)) {
+            const cb = this.pendingCallbacks.get(msg.sessionId)!;
+            clearTimeout(cb.timer);
+            this.pendingCallbacks.delete(msg.sessionId);
+            cb.resolve(msg);
+            return;
+          }
+
+          // Dispatch to type-based handlers
+          const handlers = this.handlers.get(msg.type) || [];
+          for (const handler of handlers) {
+            handler(msg);
+          }
+        });
+
+        this.ws.on('close', () => {
+          this.logger.info('Disconnected from Message Relay Hub');
+          if (this.shouldReconnect) {
+            this.scheduleReconnect();
+          }
+        });
+
+        this.ws.on('error', (err) => {
+          this.logger.error(`WebSocket error: ${err.message}`);
+        });
+      } catch (err: any) {
+        reject(err);
+      }
+    });
+  }
+
+  private scheduleReconnect(): void {
+    this.logger.info(`Reconnecting in ${this.reconnectDelay}ms...`);
+    setTimeout(() => {
+      this.connect().catch(() => {
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+      });
+    }, this.reconnectDelay);
+  }
+
+  on(type: string, handler: MessageHandler): void {
+    const existing = this.handlers.get(type) || [];
+    existing.push(handler);
+    this.handlers.set(type, existing);
+  }
+
+  send(msg: any): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  async sendAndWait(msg: any, timeoutMs = 60_000): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const id = msg.id || msg.sessionId;
+      const timer = setTimeout(() => {
+        this.pendingCallbacks.delete(id);
+        reject(new Error(`Timeout waiting for reply to ${id}`));
+      }, timeoutMs);
+
+      this.pendingCallbacks.set(id, { resolve, reject, timer });
+      this.send(msg);
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    this.shouldReconnect = false;
+    for (const [id, cb] of this.pendingCallbacks.entries()) {
+      clearTimeout(cb.timer);
+      cb.reject(new Error('Disconnecting'));
+    }
+    this.pendingCallbacks.clear();
+
+    if (this.ws) {
+      this.ws.close(1000, 'plugin deactivated');
+      this.ws = null;
+    }
+  }
+
+  get isConnected(): boolean {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+}

package/src/permissions.ts

@@ -0,0 +1,18 @@
+import type { BridgeConfig } from "./types.js";
+
+const PUBLIC_ACTIONS = new Set(["discover", "whois", "send_file"]);
+const SUPERUSER_ACTIONS = new Set(["read_file", "write_file", "restart"]);
+
+export function checkPermission(action: string, config: BridgeConfig): boolean {
+  if (PUBLIC_ACTIONS.has(action)) return true;
+  if (SUPERUSER_ACTIONS.has(action)) return config.role === "superuser";
+  return false;
+}
+
+export function assertPermission(action: string, config: BridgeConfig): void {
+  if (!checkPermission(action, config)) {
+    throw new Error(
+      `openclaw-bridge: permission denied — "${action}" requires superuser role, current role is "${config.role}"`,
+    );
+  }
+}

package/src/registry.ts

@@ -0,0 +1,107 @@
+import type { BridgeConfig, RegistryEntry, PluginLogger } from "./types.js";
+
+export class BridgeRegistry {
+  private baseUrl: string;
+  private apiKey: string | undefined;
+  private logger: PluginLogger;
+
+  constructor(config: BridgeConfig, logger: PluginLogger) {
+    // Use fileRelay URL for registry (not OpenViking)
+    if (!config.fileRelay?.baseUrl) {
+      throw new Error("openclaw-bridge: fileRelay.baseUrl is required for registry");
+    }
+    this.baseUrl = config.fileRelay.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.fileRelay.apiKey;
+    this.logger = logger;
+  }
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.apiKey) h["X-API-Key"] = this.apiKey;
+    return h;
+  }
+
+  async register(entry: RegistryEntry): Promise<void> {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/registry/register`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(entry),
+      });
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      this.logger.info(`openclaw-bridge: registered ${entry.agentId} to registry`);
+    } catch (err) {
+      this.logger.error(`openclaw-bridge: registration failed: ${String(err)}`);
+      throw err;
+    }
+  }
+
+  async update(entry: RegistryEntry): Promise<void> {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/registry/heartbeat`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(entry),
+      });
+      if (!res.ok) {
+        // Re-register if heartbeat fails
+        await this.register(entry);
+      }
+    } catch (err) {
+      this.logger.warn(`openclaw-bridge: heartbeat failed, re-registering: ${String(err)}`);
+      await this.register(entry);
+    }
+  }
+
+  async deregister(agentId: string): Promise<void> {
+    try {
+      await fetch(`${this.baseUrl}/api/v1/registry/${agentId}`, {
+        method: "DELETE",
+        headers: this.headers(),
+      });
+      this.logger.info(`openclaw-bridge: deregistered ${agentId}`);
+    } catch (err) {
+      this.logger.warn(`openclaw-bridge: deregistration failed: ${String(err)}`);
+    }
+  }
+
+  async discover(offlineThresholdMs: number): Promise<RegistryEntry[]> {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/registry/discover`, {
+        headers: this.headers(),
+      });
+      if (!res.ok) return [];
+
+      const data = (await res.json()) as { agents?: RegistryEntry[] };
+      const now = Date.now();
+
+      return (data.agents ?? []).map((entry) => {
+        const lastBeat = new Date(entry.lastHeartbeat).getTime();
+        entry.status = (now - lastBeat > offlineThresholdMs) ? "offline" : "online";
+        return entry;
+      });
+    } catch (err) {
+      this.logger.error(`openclaw-bridge: discover failed: ${String(err)}`);
+      return [];
+    }
+  }
+
+  async findAgent(agentId: string, offlineThresholdMs: number): Promise<RegistryEntry | null> {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/registry/whois/${agentId}`, {
+        headers: this.headers(),
+      });
+      if (!res.ok) return null;
+
+      const entry = (await res.json()) as RegistryEntry;
+      const now = Date.now();
+      const lastBeat = new Date(entry.lastHeartbeat).getTime();
+      entry.status = (now - lastBeat > offlineThresholdMs) ? "offline" : "online";
+      return entry;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/restart.ts

@@ -0,0 +1,137 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { BridgeConfig, RegistryEntry, PluginLogger } from "./types.js";
+import type { BridgeRegistry } from "./registry.js";
+
+const execAsync = promisify(exec);
+const IS_WIN = process.platform === "win32";
+
+export class BridgeRestart {
+  private config: BridgeConfig;
+  private machineId: string;
+  private registry: BridgeRegistry;
+  private logger: PluginLogger;
+
+  constructor(
+    config: BridgeConfig,
+    machineId: string,
+    registry: BridgeRegistry,
+    logger: PluginLogger,
+  ) {
+    this.config = config;
+    this.machineId = machineId;
+    this.registry = registry;
+    this.logger = logger;
+  }
+
+  async restart(target: RegistryEntry): Promise<{ success: boolean; message: string }> {
+    if (target.machineId !== this.machineId) {
+      return this.restartRemote(target);
+    }
+    return this.restartLocal(target);
+  }
+
+  private async restartLocal(
+    target: RegistryEntry,
+  ): Promise<{ success: boolean; message: string }> {
+    this.logger.info(`openclaw-bridge: restarting ${target.agentId} on local machine`);
+
+    try {
+      if (IS_WIN) {
+        const { stdout } = await execAsync(
+          `netstat -ano | findstr :${target.port} | findstr LISTENING`,
+        );
+        const lines = stdout.trim().split("\n");
+        for (const line of lines) {
+          const pid = line.trim().split(/\s+/).pop();
+          if (pid && /^\d+$/.test(pid)) {
+            await execAsync(`taskkill /F /PID ${pid}`).catch(() => {});
+          }
+        }
+      } else {
+        await execAsync(`lsof -ti:${target.port} | xargs kill -9`).catch(() => {});
+      }
+
+      const instanceDir = target.workspacePath.replace(/[\\/]workspace[\\/]?$/, "");
+      const runScript = IS_WIN
+        ? `${instanceDir}\\run.ps1`
+        : `${instanceDir}/run.sh`;
+
+      if (IS_WIN) {
+        await execAsync(
+          `powershell -Command "Start-Process powershell -ArgumentList '-File','${runScript}' -WindowStyle Hidden"`,
+        );
+      } else {
+        await execAsync(`nohup bash "${runScript}" > /dev/null 2>&1 &`);
+      }
+
+      const deadline = Date.now() + 60_000;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 3_000));
+        const found = await this.registry.findAgent(
+          target.agentId,
+          this.config.offlineThresholdMs ?? 120_000,
+        );
+        if (found && found.status === "online") {
+          this.logger.info(`openclaw-bridge: ${target.agentId} restarted successfully`);
+          return { success: true, message: `${target.agentId} restarted and back online` };
+        }
+      }
+
+      return {
+        success: false,
+        message: `${target.agentId} process started but did not re-register within 60s`,
+      };
+    } catch (err) {
+      return { success: false, message: `Restart failed: ${String(err)}` };
+    }
+  }
+
+  private async restartRemote(
+    target: RegistryEntry,
+  ): Promise<{ success: boolean; message: string }> {
+    if (!this.config.fileRelay?.baseUrl) {
+      return {
+        success: false,
+        message: "Cannot restart remote gateway: fileRelay not configured",
+      };
+    }
+
+    const baseUrl = this.config.fileRelay.baseUrl.replace(/\/+$/, "");
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.config.fileRelay.apiKey) headers["X-API-Key"] = this.config.fileRelay.apiKey;
+
+    const res = await fetch(`${baseUrl}/api/v1/commands/enqueue`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        fromAgent: this.config.agentId,
+        toAgent: target.agentId,
+        type: "restart",
+        payload: {},
+      }),
+    });
+
+    if (!res.ok) {
+      return { success: false, message: `FileRelay command enqueue failed: ${res.status}` };
+    }
+
+    const { id: cmdId } = (await res.json()) as { id: string };
+
+    const deadline = Date.now() + 90_000;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5_000));
+      const resultRes = await fetch(`${baseUrl}/api/v1/commands/result/${cmdId}`, { headers });
+      if (!resultRes.ok) continue;
+      const result = (await resultRes.json()) as { status: string };
+      if (result.status === "ok") {
+        return { success: true, message: `Restart command acknowledged by ${target.agentId}` };
+      }
+      if (result.status === "error") {
+        return { success: false, message: `Remote restart failed` };
+      }
+    }
+
+    return { success: false, message: "Restart command timed out (90s)" };
+  }
+}

package/src/router.ts

@@ -0,0 +1,40 @@
+import type { RegistryEntry, ChannelInfo } from './types.js';
+
+export interface MessageContext {
+  channel: ChannelInfo;
+  isGroupChannel: boolean;
+}
+
+export interface RouteDecision {
+  method: 'channel_direct' | 'hub_relay';
+  channel?: ChannelInfo;
+  fallback: 'hub_relay';
+}
+
+export function decideRoute(
+  currentContext: MessageContext,
+  targetAgentId: string,
+  registry: RegistryEntry[]
+): RouteDecision {
+  const target = registry.find(a => a.agentId === targetAgentId);
+  if (!target || target.status !== 'online') {
+    return { method: 'hub_relay', fallback: 'hub_relay' };
+  }
+
+  if (currentContext.isGroupChannel && target.channels) {
+    const targetInSameChannel = target.channels.some(
+      ch => ch.type === currentContext.channel.type
+        && ch.channelId === currentContext.channel.channelId
+    );
+
+    if (targetInSameChannel) {
+      return {
+        method: 'channel_direct',
+        channel: currentContext.channel,
+        fallback: 'hub_relay',
+      };
+    }
+  }
+
+  return { method: 'hub_relay', fallback: 'hub_relay' };
+}

package/src/session.ts

@@ -0,0 +1,33 @@
+export interface ProxySession {
+  sessionId: string;
+  originAgent: string;
+  currentAgent: string;
+  currentAgentName: string;
+}
+
+let activeSession: ProxySession | null = null;
+
+export function setSession(session: ProxySession): void {
+  activeSession = session;
+  console.log(`[session] SET handoff: sessionId=${session.sessionId} target=${session.currentAgent}`);
+}
+
+export function getSession(): ProxySession | null {
+  return activeSession;
+}
+
+export function clearSession(): void {
+  console.log(`[session] CLEAR handoff (was: ${activeSession?.sessionId || 'none'})`);
+  activeSession = null;
+}
+
+export function updateCurrentAgent(agentId: string, agentName: string): void {
+  if (activeSession) {
+    activeSession.currentAgent = agentId;
+    activeSession.currentAgentName = agentName;
+  }
+}
+
+export function isInHandoff(): boolean {
+  return activeSession !== null;
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+export interface MessageRelayConfig {
+  url: string;       // ws://host:3080/ws
+  apiKey: string;
+}
+
+export interface BridgeConfig {
+  role: "normal" | "superuser";
+  agentId: string;
+  agentName: string;
+  registry: {
+    provider?: string;
+    baseUrl: string;
+    apiKey?: string;
+  };
+  fileRelay?: {
+    baseUrl: string;
+    apiKey?: string;
+  };
+  messageRelay?: MessageRelayConfig;
+  heartbeatIntervalMs?: number;
+  offlineThresholdMs?: number;
+}
+
+export interface ChannelInfo {
+  type: string;       // "discord", "slack", "web", etc.
+  channelId: string;  // platform-specific channel identifier
+  name: string;       // human-readable name, e.g. "#creators", "DM-user1"
+}
+
+export interface RegistryEntry {
+  type: "gateway-registry";
+  agentId: string;
+  agentName: string;
+  machineId: string;
+  host: string;
+  port: number;
+  workspacePath: string;
+  discordId: string | null;
+  role: "normal" | "superuser";
+  capabilities: string[];
+  channels: ChannelInfo[];
+  registeredAt: string;
+  lastHeartbeat: string;
+  status: "online" | "offline";
+}
+
+export interface DiscoverResult {
+  agents: RegistryEntry[];
+}
+
+export type PluginLogger = {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+export type HookAgentContext = {
+  agentId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+};
+
+export type OpenClawPluginApi = {
+  pluginConfig?: unknown;
+  logger: PluginLogger;
+  registerTool: (
+    tool: {
+      name: string;
+      label: string;
+      description: string;
+      parameters: unknown;
+      execute: (_toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
+    },
+    opts?: { name?: string; names?: string[] },
+  ) => void;
+  registerService: (service: {
+    id: string;
+    start: (ctx?: unknown) => void | Promise<void>;
+    stop?: (ctx?: unknown) => void | Promise<void>;
+  }) => void;
+  on: (
+    hookName: string,
+    handler: (event: unknown, ctx?: HookAgentContext) => unknown,
+    opts?: { priority?: number },
+  ) => void;
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}