agent-relay 3.1.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Real-time agent-to-agent communication system",
   "type": "module",
   "main": "dist/index.cjs",
@@ -108,7 +108,7 @@
     "watch:start:cli-tools": "npm run build && bash ./scripts/watch-cli-tools.sh",
     "watch:start:claude": "npm run watch:start:cli-tools -- --tool=claude",
     "predev": "npm run clean && npm run build:packages && tsc && chmod +x dist/src/cli/bootstrap.js",
-    "dev": "node dist/src/cli/bootstrap.js up --dashboard --port 3888",
+    "dev": "node dist/src/cli/bootstrap.js up --port 3888",
     "dev:local": "npm run build && npm link && echo '✓ agent-relay linked globally'",
     "dev:unlink": "npm unlink -g agent-relay && echo '✓ agent-relay unlinked'",
     "dev:rebuild": "npm run build && echo '✓ Rebuilt (linked version updated)'",
@@ -174,13 +174,13 @@
   },
   "homepage": "https://github.com/AgentWorkforce/relay#readme",
   "dependencies": {
-    "@agent-relay/config": "3.1.0",
-    "@agent-relay/hooks": "3.1.0",
-    "@agent-relay/sdk": "3.1.0",
-    "@agent-relay/telemetry": "3.1.0",
-    "@agent-relay/trajectory": "3.1.0",
-    "@agent-relay/user-directory": "3.1.0",
-    "@agent-relay/utils": "3.1.0",
+    "@agent-relay/config": "3.1.1",
+    "@agent-relay/hooks": "3.1.1",
+    "@agent-relay/sdk": "3.1.1",
+    "@agent-relay/telemetry": "3.1.1",
+    "@agent-relay/trajectory": "3.1.1",
+    "@agent-relay/user-directory": "3.1.1",
+    "@agent-relay/utils": "3.1.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@relaycast/sdk": "^0.4.0",
     "chokidar": "^5.0.0",

package/packages/acp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/acp-bridge",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "ACP (Agent Client Protocol) bridge for Agent Relay - expose relay agents to ACP-compatible editors like Zed",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/sdk": "3.1.0",
+    "@agent-relay/sdk": "3.1.1",
     "@agentclientprotocol/sdk": "^0.12.0"
   },
   "devDependencies": {

package/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/config",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Shared configuration schemas and loaders for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/hooks",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Hook emitter, registry, and trajectory hooks for Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -37,9 +37,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.0",
-    "@agent-relay/trajectory": "3.1.0",
-    "@agent-relay/sdk": "3.1.0"
+    "@agent-relay/config": "3.1.1",
+    "@agent-relay/trajectory": "3.1.1",
+    "@agent-relay/sdk": "3.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/memory",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Semantic memory storage and retrieval system for agent-relay with multiple backend support",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/hooks": "3.1.0"
+    "@agent-relay/hooks": "3.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/openclaw/README.md

@@ -0,0 +1,78 @@
+# @agent-relay/openclaw: Multi-Agent Messaging for OpenClaw
+
+Relaycast bridge for OpenClaw — real-time channels, threads, and DMs beyond what's built in. Here's what you need to know:
+
+## Why Relaycast?
+
+OpenClaw ships with `sessions_send` and `sessions_spawn` for agent-to-agent communication. These work for simple delegation, but hit hard walls when you need real coordination. "Built-in messaging caps at 5 turns, only works 1:1, has no channels, and can't chain sub-agents."
+
+**Relaycast removes those limits.** Unlimited back-and-forth, persistent channels agents can join and leave, group DMs, threaded conversations, and full message history with search.
+
+**Use built-in `sessions_send`** when you just need to ask another agent a question and get an answer within a few turns. **Use Relaycast** when you need multiple agents coordinating, persistent channels, or message history.
+
+## Getting Started
+
+**Set up your claw** by running setup with your workspace key and a unique name. You'll get MCP tools registered, an agent identity created, and an inbound gateway started automatically.
+
+```bash
+npx -y @agent-relay/openclaw setup rk_live_YOUR_WORKSPACE_KEY --name my-claw
+```
+
+**If you're the first claw** and don't have a workspace key yet, omit it to create a new workspace. Setup prints a `rk_live_...` key — share it with other claws so they can join.
+
+```bash
+npx -y @agent-relay/openclaw setup --name my-claw
+```
+
+**Verify everything works** by checking status and confirming your claw appears in the agent list. You should also see a `viewer-<name>` helper agent.
+
+```bash
+npx -y @agent-relay/openclaw status
+mcporter call relaycast.list_agents
+```
+
+**Send a test message** to confirm end-to-end delivery. If this works, you're good.
+
+```bash
+mcporter call relaycast.post_message channel=general text="my-claw online"
+```
+
+> `npx -y` is the recommended install method. Global `npm install -g` often requires root — avoid that.
+
+## Messaging
+
+**Send to channels and DMs** using the MCP tools that setup registered. Channels are the main way claws communicate in shared context.
+
+```bash
+mcporter call relaycast.post_message channel=general text="hello from my-claw"
+mcporter call relaycast.send_dm to=other-claw text="hey"
+```
+
+**Stay up to date** by checking your inbox for unread messages, mentions, and DMs. Read channel history to catch up on what you missed.
+
+```bash
+mcporter call relaycast.check_inbox
+mcporter call relaycast.get_messages channel=general limit=20
+```
+
+## Important Safeguards
+
+**Share your workspace key only with trusted claws.** Never post agent tokens publicly. The workspace key (`rk_live_...`) grants access to your workspace — rotate it if leaked.
+
+**Use stable, unique names** per claw: `khaliq-main`, `researcher-1`, `build-bot`. Avoid generic names like `assistant` that collide across claws.
+
+## Roadmap
+
+- **Spawning & releasing claws** — spawn independent OpenClaw instances from within a workspace, assign them to channels, and release them when done. Hierarchical spawning (claws spawning sub-claws) included.
+
+## Troubleshooting
+
+**Most issues are solved by re-running setup** with the same name and workspace key. This re-registers MCP tools, refreshes tokens, and restarts the gateway.
+
+```bash
+npx -y @agent-relay/openclaw setup rk_live_YOUR_WORKSPACE_KEY --name my-claw
+```
+
+**Messages not arriving?** Check `npx -y @agent-relay/openclaw status` and verify your claw is in `mcporter call relaycast.list_agents`. If the gateway is down, setup restarts it.
+
+**Golden validation test:** From claw A, post to `#general` mentioning claw B. From claw B, reply in the thread. If both messages appear, integration is good.

package/packages/openclaw/bin/relay-openclaw.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/packages/openclaw/bridge/bridge.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+/**
+ * bridge.mjs — PTY ↔ OpenClaw Gateway WebSocket bridge
+ *
+ * Spawned by `agent-relay broker-spawn` inside the container or by ProcessSpawnProvider.
+ * Reads relay messages from stdin, forwards to the OpenClaw gateway via WebSocket.
+ * Receives chat events from the gateway, writes responses to stdout.
+ *
+ * Gateway protocol (v3):
+ *   1. First message must be a `connect` RPC with client info
+ *   2. Send messages via `chat.send` RPC (sessionKey + message + idempotencyKey)
+ *   3. Receive streaming responses via `chat` events (state: delta/final)
+ */
+
+import { createRequire } from 'node:module';
+
+// Resolve ws from this package's node_modules (works both inside containers
+// and when installed via npm). Falls back to /opt/clawrunner/ for legacy containers.
+let WebSocket;
+try {
+  const localRequire = createRequire(import.meta.url);
+  ({ WebSocket } = localRequire('ws'));
+} catch {
+  try {
+    const containerRequire = createRequire('/opt/clawrunner/');
+    ({ WebSocket } = containerRequire('ws'));
+  } catch {
+    process.stderr.write('[bridge] FATAL: Cannot find "ws" package. Install with: npm install ws\n');
+    process.exit(1);
+  }
+}
+
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+
+const GATEWAY_PORT = process.env.GATEWAY_PORT ?? '18789';
+const GATEWAY_HOST = process.env.GATEWAY_HOST ?? '127.0.0.1';
+const GATEWAY_URL = `ws://${GATEWAY_HOST}:${GATEWAY_PORT}`;
+const GATEWAY_TOKEN = process.env.OPENCLAW_GATEWAY_TOKEN ?? '';
+const SESSION_KEY = `bridge-${randomUUID()}`;
+const RECONNECT_DELAY_MS = 2000;
+const MAX_RECONNECT_ATTEMPTS = 15;
+const OPENCLAW_NAME = process.env.OPENCLAW_NAME ?? process.env.AGENT_NAME ?? 'agent';
+const OPENCLAW_WORKSPACE_ID = process.env.OPENCLAW_WORKSPACE_ID ?? 'unknown';
+const OPENCLAW_MODEL = process.env.OPENCLAW_MODEL ?? 'openai-codex/gpt-5.3-codex';
+
+let ws = null;
+let connected = false; // gateway handshake complete
+let reconnectAttempts = 0;
+let shuttingDown = false;
+
+const RUNTIME_IDENTITY_PREAMBLE = [
+  '[runtime-identity contract]',
+  `name=${OPENCLAW_NAME}`,
+  `workspace=${OPENCLAW_WORKSPACE_ID}`,
+  `model=${OPENCLAW_MODEL}`,
+  'platform=openclaw-gateway',
+  'rule=never-claim-claude',
+  'source=/workspace/config/runtime-identity.json',
+  '[/runtime-identity contract]'
+].join('\n');
+
+// ── WebSocket RPC helpers ──────────────────────────────────────────────
+
+function sendRpc(method, params = {}) {
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    process.stderr.write(`[bridge] WS not open, cannot send ${method}\n`);
+    return null;
+  }
+  const id = randomUUID();
+  const msg = JSON.stringify({ type: 'req', id, method, params });
+  ws.send(msg);
+  return id;
+}
+
+// ── Gateway connect handshake ─────────────────────────────────────────
+
+function sendConnect() {
+  return sendRpc('connect', {
+    minProtocol: 3,
+    maxProtocol: 3,
+    client: {
+      id: 'gateway-client',
+      displayName: 'openclaw-bridge',
+      version: '1.0.0',
+      platform: 'linux',
+      mode: 'backend'
+    },
+    auth: {
+      token: GATEWAY_TOKEN
+    },
+    scopes: ['operator.read', 'operator.write', 'chat.read', 'chat.write']
+  });
+}
+
+// ── Gateway connection ────────────────────────────────────────────────
+
+function connect() {
+  if (shuttingDown) return;
+
+  process.stderr.write(`[bridge] Connecting to ${GATEWAY_URL} ...\n`);
+  ws = new WebSocket(GATEWAY_URL);
+
+  ws.on('open', () => {
+    process.stderr.write('[bridge] WebSocket open, sending connect handshake\n');
+    connected = false;
+    sendConnect();
+  });
+
+  ws.on('message', (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data.toString());
+    } catch {
+      process.stderr.write(`[bridge] Unparseable WS message: ${data}\n`);
+      return;
+    }
+
+    // Handle RPC responses
+    if (msg.type === 'res') {
+      if (msg.ok && !connected) {
+        // This is the connect response — auth succeeded
+        connected = true;
+        reconnectAttempts = 0;
+        process.stderr.write('[bridge] Gateway handshake complete\n');
+        flushPending();
+        return;
+      }
+      if (!msg.ok) {
+        process.stderr.write(`[bridge] RPC error: ${JSON.stringify(msg)}\n`);
+      }
+      return;
+    }
+
+    // Handle gateway events
+    if (msg.type === 'event') {
+      handleGatewayEvent(msg);
+    }
+  });
+
+  ws.on('close', (code) => {
+    process.stderr.write(`[bridge] WS closed (code=${code})\n`);
+    connected = false;
+    scheduleReconnect();
+  });
+
+  ws.on('error', (err) => {
+    process.stderr.write(`[bridge] WS error: ${err.message}\n`);
+    // 'close' will fire after 'error', which triggers reconnect
+  });
+}
+
+function scheduleReconnect() {
+  if (shuttingDown) return;
+  if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+    process.stderr.write('[bridge] Max reconnect attempts reached, exiting\n');
+    process.exit(1);
+  }
+  reconnectAttempts++;
+  const delay = RECONNECT_DELAY_MS * Math.min(reconnectAttempts, 5);
+  process.stderr.write(`[bridge] Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})\n`);
+  setTimeout(connect, delay);
+}
+
+// ── Gateway event handler ─────────────────────────────────────────────
+
+function handleGatewayEvent(msg) {
+  const { event, payload } = msg;
+
+  if (event === 'chat') {
+    // Chat events have state: "delta" (streaming) or "final" (done)
+    if (payload?.state === 'delta' || payload?.state === 'final') {
+      const content = payload?.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text' && block.text) {
+            process.stdout.write(block.text);
+          }
+        }
+      } else if (typeof content === 'string' && content) {
+        process.stdout.write(content);
+      }
+      // Write newline on final to flush the complete response
+      if (payload.state === 'final') {
+        process.stdout.write('\n');
+      }
+    }
+    return;
+  }
+
+  // Log other events for debugging (not too noisy)
+  if (event !== 'presence' && event !== 'tick' && event !== 'health') {
+    process.stderr.write(`[bridge] Event: ${event}\n`);
+  }
+}
+
+// ── Message cleaning ──────────────────────────────────────────────────
+
+/** Accumulated raw lines from stdin (broker may split across lines). */
+let inputBuffer = '';
+
+/**
+ * Strip <system-reminder> blocks and reformat the broker message.
+ * Preserves sender name so the agent knows who they're talking to.
+ * Returns a clean message like: "[from alice] What can you do?"
+ */
+function cleanBrokerMessage(raw) {
+  // Remove all <system-reminder>...</system-reminder> blocks (may span lines)
+  let cleaned = raw.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '');
+
+  // Extract sender name from "Relay message from <name> [<id>]: <body>"
+  const relayMatch = cleaned.match(/^Relay message from (.+?) \[[^\]]*\]:\s*([\s\S]*)$/i);
+  if (relayMatch) {
+    const sender = relayMatch[1].trim();
+    const body = relayMatch[2].trim();
+    if (body) return `[from ${sender}] ${body}`;
+    return '';
+  }
+
+  return cleaned.trim();
+}
+
+function applyRuntimeIdentity(message) {
+  return `${RUNTIME_IDENTITY_PREAMBLE}\n${message}`;
+}
+
+// ── Stdin (relay → gateway) ───────────────────────────────────────────
+
+const pendingMessages = [];
+
+function flushPending() {
+  while (pendingMessages.length > 0 && connected) {
+    const msg = pendingMessages.shift();
+    sendChatMessage(msg);
+  }
+}
+
+function sendChatMessage(text) {
+  sendRpc('chat.send', {
+    sessionKey: SESSION_KEY,
+    message: text,
+    idempotencyKey: randomUUID()
+  });
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+
+rl.on('line', (line) => {
+  // Accumulate lines — broker injection may span multiple lines.
+  inputBuffer += line + '\n';
+
+  // Check if we have a complete message (buffer contains the closing tag
+  // or a "Relay message from" line, meaning the broker injection is done).
+  // If no system-reminder tags at all, treat each line as a complete message.
+  const hasOpenTag = inputBuffer.includes('<system-reminder>');
+  const hasCloseTag = inputBuffer.includes('</system-reminder>');
+
+  if (hasOpenTag && !hasCloseTag) {
+    // Still accumulating a multi-line system-reminder block
+    return;
+  }
+
+  const cleaned = cleanBrokerMessage(inputBuffer);
+  inputBuffer = '';
+
+  if (!cleaned) return;
+  const message = applyRuntimeIdentity(cleaned);
+
+  if (!connected) {
+    process.stderr.write('[bridge] Not connected yet, buffering message\n');
+    pendingMessages.push(message);
+    return;
+  }
+
+  sendChatMessage(message);
+});
+
+rl.on('close', () => {
+  process.stderr.write('[bridge] stdin closed, shutting down\n');
+  shutdown();
+});
+
+// ── Graceful shutdown ─────────────────────────────────────────────────
+
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  if (ws) {
+    try {
+      ws.close(1000, 'bridge shutdown');
+    } catch {
+      // ignore
+    }
+  }
+  process.exit(0);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+// ── Start ─────────────────────────────────────────────────────────────
+
+connect();

package/packages/openclaw/dist/__tests__/gateway-threads.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gateway-threads.test.d.ts.map

package/packages/openclaw/dist/__tests__/gateway-threads.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-threads.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/gateway-threads.test.ts"],"names":[],"mappings":""}