openclaw-bridge 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# openclaw-bridge
+
+Cross-gateway communication plugin for [OpenClaw](https://github.com/nicepkg/openclaw). Enables independent gateway instances to discover each other, exchange files, relay messages, and hand off conversations.
+
+## Features
+
+- **Agent Discovery** — Auto-register and discover online agents via heartbeat
+- **File Transfer** — Send files between agents (local or cross-machine via Hub)
+- **Message Relay** — Send messages to any agent through the Hub and get replies
+- **Session Handoff** — Transfer active conversations between agents seamlessly
+- **Superuser Tools** — Read/write files and restart remote gateways
+- **Auto-Config** — Automatically patches `openclaw.json` with recommended settings on first run
+
+## Prerequisites
+
+You need [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) (v0.2.4+) running on a reachable server first:
+
+```bash
+# On your server:
+npm install -g openclaw-bridge-hub
+openclaw-bridge-hub init          # generates API key — save it!
+openclaw-bridge-hub start         # starts on port 3080
+openclaw-bridge-hub install-service  # auto-start on boot (Linux)
+```
+
+Save the generated API key — you'll need it for the plugin config below.
+
+## Installation
+
+```bash
+openclaw plugins install openclaw-bridge
+```
+
+Or manually: place this plugin in a directory listed in `plugins.load.paths` of your `openclaw.json`.
+
+## Configuration
+
+Add to `openclaw.json` under `plugins.entries` (replace the API key and server URL with your own):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-bridge": {
+        "config": {
+          "role": "normal",
+          "agentId": "my-agent",
+          "agentName": "My Agent",
+          "registry": {
+            "baseUrl": "http://69.5.7.190:3080",
+            "apiKey": "your-hub-api-key"
+          },
+          "fileRelay": {
+            "baseUrl": "http://69.5.7.190:3080",
+            "apiKey": "your-hub-api-key"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Auto-configured settings
+
+On first startup, the plugin automatically adds these if missing:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `messageRelay.url` | Derived from `fileRelay.baseUrl` | WebSocket connection to Hub |
+| `messageRelay.apiKey` | Same as `fileRelay.apiKey` | Hub authentication |
+| `gateway.http.endpoints.chatCompletions.enabled` | `true` | Required for message relay processing |
+| `channels.discord.accounts.*.dmHistoryLimit` | `0` | Fast DM responses (OpenViking handles memory) |
+
+### Roles
+
+| Role | Capabilities |
+|------|-------------|
+| `normal` | discover, whois, send_file, send_message, handoff |
+| `superuser` | All of normal + read_file, write_file, restart |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `bridge_discover` | List all online agents |
+| `bridge_whois` | Get details for a specific agent |
+| `bridge_send_file` | Send a file to another agent's inbox |
+| `bridge_send_message` | Send a message and wait for reply (relay mode) |
+| `bridge_handoff` | Hand off conversation to another agent |
+| `bridge_handoff_end` | End handoff and return to original agent |
+| `bridge_handoff_switch` | Switch handoff to a different agent |
+| `bridge_read_file` | Read a file from any agent's workspace (superuser) |
+| `bridge_write_file` | Write a file to any agent's workspace (superuser) |
+| `bridge_restart` | Restart another gateway (superuser) |
+
+## Architecture
+
+```
+User ←→ Discord DM ←→ Main Gateway
+                            ↕ (WebSocket)
+                      openclaw-bridge-hub (port 3080)
+                            ↕ (WebSocket)
+                       PM Gateway / Bot1-4
+```
+
+- Each gateway runs one agent with this shared plugin
+- Plugin auto-registers to Hub, heartbeats every 30 seconds
+- Messages and handoffs route through Hub WebSocket (`/ws`)
+- File transfers use local filesystem (same machine) or Hub relay (cross-machine)
+
+## Requirements
+
+- [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) v0.2.4+ running on a reachable server
+- OpenClaw gateway 2026.3.24+
+
+## License
+
+MIT

package/_inbox/main/bridge-test.md

@@ -0,0 +1 @@
+Hello from main! This is a test file sent via bridge_send_file.

package/_inbox/pm/bridge-test.md

@@ -0,0 +1 @@
+Hello from main! This is a test file sent via bridge_send_file.

package/openclaw.plugin.json

@@ -0,0 +1,71 @@
+{
+  "id": "openclaw-bridge",
+  "kind": "extension",
+  "uiHints": {
+    "role": {
+      "label": "Role",
+      "help": "normal = isolated workspace access only; superuser = cross-gateway access"
+    },
+    "agentId": {
+      "label": "Agent ID",
+      "help": "Unique identifier for this agent (e.g., pm, bot1, main)"
+    },
+    "agentName": {
+      "label": "Agent Display Name",
+      "help": "Human-readable name (e.g., PM Bot, Director Ma)"
+    },
+    "registry.baseUrl": {
+      "label": "OpenViking URL",
+      "placeholder": "http://69.5.7.190:1933",
+      "help": "OpenViking server for gateway registry"
+    },
+    "registry.apiKey": {
+      "label": "OpenViking API Key",
+      "sensitive": true
+    },
+    "fileRelay.baseUrl": {
+      "label": "FileRelay URL",
+      "placeholder": "http://69.5.7.190:3080",
+      "help": "FileRelay server for cross-machine file transfer"
+    },
+    "fileRelay.apiKey": {
+      "label": "FileRelay API Key",
+      "sensitive": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["role", "agentId", "agentName", "registry"],
+    "properties": {
+      "role": { "type": "string", "enum": ["normal", "superuser"] },
+      "agentId": { "type": "string" },
+      "agentName": { "type": "string" },
+      "registry": {
+        "type": "object",
+        "required": ["baseUrl"],
+        "properties": {
+          "provider": { "type": "string" },
+          "baseUrl": { "type": "string" },
+          "apiKey": { "type": "string" }
+        }
+      },
+      "fileRelay": {
+        "type": "object",
+        "properties": {
+          "baseUrl": { "type": "string" },
+          "apiKey": { "type": "string" }
+        }
+      },
+      "messageRelay": {
+        "type": "object",
+        "properties": {
+          "url": { "type": "string" },
+          "apiKey": { "type": "string" }
+        }
+      },
+      "heartbeatIntervalMs": { "type": "number" },
+      "offlineThresholdMs": { "type": "number" }
+    }
+  }
+}

package/output/bridge-test.md

@@ -0,0 +1 @@
+Hello from main! This is a test file sent via bridge_send_file.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "openclaw-bridge",
+  "version": "0.1.0",
+  "description": "Cross-gateway communication plugin for OpenClaw — agent discovery, file transfer, real-time messaging, and session handoff",
+  "type": "module",
+  "main": "src/index.ts",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "openclaw",
+    "bridge",
+    "multi-agent",
+    "gateway",
+    "communication",
+    "handoff"
+  ],
+  "license": "MIT"
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+import { hostname } from "node:os";
+import type { BridgeConfig } from "./types.js";
+
+const DEFAULTS = {
+  heartbeatIntervalMs: 30_000,
+  offlineThresholdMs: 120_000,
+} as const;
+
+export function parseConfig(raw: unknown): BridgeConfig {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("openclaw-bridge: missing plugin config");
+  }
+  const obj = raw as Record<string, unknown>;
+
+  if (!obj.role || (obj.role !== "normal" && obj.role !== "superuser")) {
+    throw new Error('openclaw-bridge: config.role must be "normal" or "superuser"');
+  }
+  if (!obj.agentId || typeof obj.agentId !== "string") {
+    throw new Error("openclaw-bridge: config.agentId is required");
+  }
+  if (!obj.agentName || typeof obj.agentName !== "string") {
+    throw new Error("openclaw-bridge: config.agentName is required");
+  }
+  const registry = obj.registry as Record<string, unknown> | undefined;
+  if (!registry || !registry.baseUrl || typeof registry.baseUrl !== "string") {
+    throw new Error("openclaw-bridge: config.registry.baseUrl is required");
+  }
+
+  return {
+    role: obj.role as "normal" | "superuser",
+    agentId: obj.agentId as string,
+    agentName: obj.agentName as string,
+    registry: {
+      provider: (registry.provider as string) ?? "openviking",
+      baseUrl: registry.baseUrl as string,
+      apiKey: registry.apiKey as string | undefined,
+    },
+    fileRelay: obj.fileRelay
+      ? {
+          baseUrl: (obj.fileRelay as Record<string, unknown>).baseUrl as string,
+          apiKey: (obj.fileRelay as Record<string, unknown>).apiKey as string | undefined,
+        }
+      : undefined,
+    messageRelay: obj.messageRelay
+      ? {
+          url: (obj.messageRelay as Record<string, unknown>).url as string,
+          apiKey: (obj.messageRelay as Record<string, unknown>).apiKey as string,
+        }
+      : undefined,
+    heartbeatIntervalMs:
+      typeof obj.heartbeatIntervalMs === "number"
+        ? obj.heartbeatIntervalMs
+        : DEFAULTS.heartbeatIntervalMs,
+    offlineThresholdMs:
+      typeof obj.offlineThresholdMs === "number"
+        ? obj.offlineThresholdMs
+        : DEFAULTS.offlineThresholdMs,
+  };
+}
+
+export function getMachineId(): string {
+  return hostname();
+}

package/src/discovery.ts

@@ -0,0 +1,17 @@
+import type { RegistryEntry } from "./types.js";
+import type { BridgeRegistry } from "./registry.js";
+
+export async function discoverAll(
+  registry: BridgeRegistry,
+  offlineThresholdMs: number,
+): Promise<RegistryEntry[]> {
+  return registry.discover(offlineThresholdMs);
+}
+
+export async function whois(
+  registry: BridgeRegistry,
+  agentId: string,
+  offlineThresholdMs: number,
+): Promise<RegistryEntry | null> {
+  return registry.findAgent(agentId, offlineThresholdMs);
+}

package/src/file-ops.ts

@@ -0,0 +1,320 @@
+import { readFile, writeFile, copyFile, mkdir, access } from "node:fs/promises";
+import { join, resolve, dirname, basename, extname } from "node:path";
+import type { BridgeConfig, RegistryEntry, PluginLogger } from "./types.js";
+
+/** If dest exists, append _1, _2, etc. before the extension */
+async function deduplicatePath(destPath: string): Promise<string> {
+  let candidate = destPath;
+  let counter = 0;
+  const ext = extname(destPath);
+  const base = destPath.slice(0, destPath.length - ext.length);
+  while (true) {
+    try {
+      await access(candidate);
+      counter++;
+      candidate = `${base}_${counter}${ext}`;
+    } catch {
+      return candidate; // File doesn't exist, use this path
+    }
+  }
+}
+
+export class BridgeFileOps {
+  private config: BridgeConfig;
+  private machineId: string;
+  private workspacePath: string;
+  private logger: PluginLogger;
+
+  constructor(
+    config: BridgeConfig,
+    machineId: string,
+    workspacePath: string,
+    logger: PluginLogger,
+  ) {
+    this.config = config;
+    this.machineId = machineId;
+    this.workspacePath = workspacePath;
+    this.logger = logger;
+  }
+
+  private isSameMachine(target: RegistryEntry): boolean {
+    return target.machineId === this.machineId;
+  }
+
+  private validatePathWithinWorkspace(filePath: string, workspace: string): string {
+    const resolved = resolve(workspace, filePath);
+    if (!resolved.startsWith(resolve(workspace))) {
+      throw new Error(`openclaw-bridge: path escapes workspace: ${filePath}`);
+    }
+    return resolved;
+  }
+
+  private fileRelayHeaders(): Record<string, string> {
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.config.fileRelay?.apiKey) h["X-API-Key"] = this.config.fileRelay.apiKey;
+    return h;
+  }
+
+  private fileRelayUrl(path: string): string {
+    if (!this.config.fileRelay?.baseUrl) {
+      throw new Error("openclaw-bridge: fileRelay.baseUrl not configured");
+    }
+    return `${this.config.fileRelay.baseUrl.replace(/\/+$/, "")}${path}`;
+  }
+
+  async sendFile(
+    target: RegistryEntry,
+    localRelativePath: string,
+  ): Promise<{ delivered: boolean; message: string }> {
+    const sourcePath = this.validatePathWithinWorkspace(localRelativePath, this.workspacePath);
+
+    if (this.isSameMachine(target)) {
+      const destDir = join(target.workspacePath, "_inbox", this.config.agentId);
+      await mkdir(destDir, { recursive: true });
+      const originalFilename = localRelativePath.split(/[\\/]/).pop()!;
+      const rawDestPath = join(destDir, originalFilename);
+      const destPath = await deduplicatePath(rawDestPath);
+      await copyFile(sourcePath, destPath);
+      const actualFilename = basename(destPath);
+      const renamed = actualFilename !== originalFilename;
+      this.logger.info(
+        `openclaw-bridge: sent ${localRelativePath} to ${target.agentId} (local)${renamed ? ` (renamed to ${actualFilename})` : ""}`,
+      );
+      return {
+        delivered: true,
+        message: renamed
+          ? `File copied to ${target.agentId}/_inbox/ (renamed to ${actualFilename} because a file with the same name already existed)`
+          : `File copied to ${target.agentId}/_inbox/`,
+        filename: actualFilename,
+        renamed,
+      };
+    }
+
+    const content = await readFile(sourcePath);
+    const res = await fetch(this.fileRelayUrl("/api/v1/files/upload"), {
+      method: "POST",
+      headers: this.fileRelayHeaders(),
+      body: JSON.stringify({
+        fromAgent: this.config.agentId,
+        toAgent: target.agentId,
+        filename: localRelativePath.split(/[\\/]/).pop()!,
+        content: content.toString("base64"),
+        metadata: {},
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`openclaw-bridge: FileRelay upload failed: ${res.status}`);
+    }
+
+    this.logger.info(
+      `openclaw-bridge: sent ${localRelativePath} to ${target.agentId} (FileRelay)`,
+    );
+    return { delivered: false, message: `File uploaded to FileRelay for ${target.agentId}` };
+  }
+
+  async readRemoteFile(
+    target: RegistryEntry,
+    relativePath: string,
+  ): Promise<string> {
+    if (this.isSameMachine(target)) {
+      const fullPath = this.validatePathWithinWorkspace(relativePath, target.workspacePath);
+      return await readFile(fullPath, "utf-8");
+    }
+
+    const enqueueRes = await fetch(this.fileRelayUrl("/api/v1/commands/enqueue"), {
+      method: "POST",
+      headers: this.fileRelayHeaders(),
+      body: JSON.stringify({
+        fromAgent: this.config.agentId,
+        toAgent: target.agentId,
+        type: "read_file",
+        payload: { path: relativePath },
+      }),
+    });
+
+    if (!enqueueRes.ok) {
+      throw new Error(`openclaw-bridge: command enqueue failed: ${enqueueRes.status}`);
+    }
+
+    const { id: cmdId } = (await enqueueRes.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(this.fileRelayUrl(`/api/v1/commands/result/${cmdId}`), {
+        headers: this.fileRelayHeaders(),
+      });
+      if (!resultRes.ok) continue;
+      const result = (await resultRes.json()) as {
+        status: string;
+        payload?: { content?: string };
+      };
+      if (result.status === "ok" && result.payload?.content) {
+        return Buffer.from(result.payload.content, "base64").toString("utf-8");
+      }
+      if (result.status === "error") {
+        throw new Error(`openclaw-bridge: remote read failed`);
+      }
+    }
+    throw new Error("openclaw-bridge: remote read timed out (90s)");
+  }
+
+  async writeRemoteFile(
+    target: RegistryEntry,
+    relativePath: string,
+    content: string,
+  ): Promise<void> {
+    if (this.isSameMachine(target)) {
+      const fullPath = this.validatePathWithinWorkspace(relativePath, target.workspacePath);
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFile(fullPath, content, "utf-8");
+      this.logger.info(
+        `openclaw-bridge: wrote ${relativePath} to ${target.agentId} workspace`,
+      );
+      return;
+    }
+
+    const res = await fetch(this.fileRelayUrl("/api/v1/files/upload"), {
+      method: "POST",
+      headers: this.fileRelayHeaders(),
+      body: JSON.stringify({
+        fromAgent: this.config.agentId,
+        toAgent: target.agentId,
+        filename: relativePath.split(/[\\/]/).pop()!,
+        content: Buffer.from(content).toString("base64"),
+        metadata: { writeToPath: relativePath },
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`openclaw-bridge: FileRelay write-upload failed: ${res.status}`);
+    }
+  }
+
+  async processPendingFiles(): Promise<number> {
+    if (!this.config.fileRelay?.baseUrl) return 0;
+
+    try {
+      const res = await fetch(
+        this.fileRelayUrl(`/api/v1/files/pending?agent=${this.config.agentId}`),
+        { headers: this.fileRelayHeaders() },
+      );
+      if (!res.ok) return 0;
+
+      const data = (await res.json()) as {
+        files: Array<{
+          id: string;
+          fromAgent: string;
+          filename: string;
+          metadata?: { writeToPath?: string };
+        }>;
+      };
+
+      let count = 0;
+      for (const file of data.files) {
+        const dlRes = await fetch(this.fileRelayUrl(`/api/v1/files/download/${file.id}`), {
+          headers: this.fileRelayHeaders(),
+        });
+        if (!dlRes.ok) continue;
+
+        const dlData = (await dlRes.json()) as { content: string };
+        const fileContent = Buffer.from(dlData.content, "base64");
+
+        let destPath: string;
+        if (file.metadata?.writeToPath) {
+          destPath = this.validatePathWithinWorkspace(file.metadata.writeToPath, this.workspacePath);
+        } else {
+          const inboxDir = join(this.workspacePath, "_inbox", file.fromAgent);
+          await mkdir(inboxDir, { recursive: true });
+          destPath = await deduplicatePath(join(inboxDir, file.filename));
+        }
+
+        await mkdir(dirname(destPath), { recursive: true });
+        await writeFile(destPath, fileContent);
+
+        await fetch(this.fileRelayUrl(`/api/v1/files/ack/${file.id}`), {
+          method: "POST",
+          headers: this.fileRelayHeaders(),
+        });
+
+        count++;
+      }
+
+      if (count > 0) {
+        this.logger.info(`openclaw-bridge: processed ${count} pending file(s) from FileRelay`);
+      }
+      return count;
+    } catch (err) {
+      this.logger.warn(`openclaw-bridge: FileRelay file poll failed: ${String(err)}`);
+      return 0;
+    }
+  }
+
+  async processPendingCommands(): Promise<number> {
+    if (!this.config.fileRelay?.baseUrl) return 0;
+
+    try {
+      const res = await fetch(
+        this.fileRelayUrl(`/api/v1/commands/pending?agent=${this.config.agentId}`),
+        { headers: this.fileRelayHeaders() },
+      );
+      if (!res.ok) return 0;
+
+      const data = (await res.json()) as {
+        commands: Array<{
+          id: string;
+          fromAgent: string;
+          type: string;
+          payload: Record<string, unknown>;
+        }>;
+      };
+
+      let count = 0;
+      for (const cmd of data.commands) {
+        try {
+          if (cmd.type === "read_file") {
+            const path = cmd.payload.path as string;
+            const fullPath = this.validatePathWithinWorkspace(path, this.workspacePath);
+            const content = await readFile(fullPath);
+            await fetch(this.fileRelayUrl(`/api/v1/commands/respond/${cmd.id}`), {
+              method: "POST",
+              headers: this.fileRelayHeaders(),
+              body: JSON.stringify({
+                status: "ok",
+                payload: { content: content.toString("base64") },
+              }),
+            });
+          } else if (cmd.type === "restart") {
+            // Acknowledge the command first
+            await fetch(this.fileRelayUrl(`/api/v1/commands/respond/${cmd.id}`), {
+              method: "POST",
+              headers: this.fileRelayHeaders(),
+              body: JSON.stringify({ status: "ok", payload: {} }),
+            });
+            // Schedule self-restart after responding
+            setTimeout(() => {
+              this.logger.info("openclaw-bridge: executing remote restart command");
+              process.exit(0); // PM2 or run.ps1 will restart the process
+            }, 1_000);
+          }
+          count++;
+        } catch (err) {
+          await fetch(this.fileRelayUrl(`/api/v1/commands/respond/${cmd.id}`), {
+            method: "POST",
+            headers: this.fileRelayHeaders(),
+            body: JSON.stringify({ status: "error", payload: { error: String(err) } }),
+          });
+        }
+      }
+
+      if (count > 0) {
+        this.logger.info(`openclaw-bridge: processed ${count} pending command(s) from FileRelay`);
+      }
+      return count;
+    } catch (err) {
+      this.logger.warn(`openclaw-bridge: FileRelay command poll failed: ${String(err)}`);
+      return 0;
+    }
+  }
+}