agent-relay 3.1.4 → 3.1.5

package/packages/openclaw/src/gateway.ts

@@ -14,7 +14,7 @@ import type {
 } from '@relaycast/sdk';
 import WebSocket from 'ws';
 
-import type { GatewayConfig, InboundMessage, DeliveryResult } from './types.js';
+import { DEFAULT_OPENCLAW_GATEWAY_PORT, type GatewayConfig, type InboundMessage, type DeliveryResult } from './types.js';
 import { SpawnManager } from './spawn/manager.js';
 import type { SpawnOptions } from './spawn/types.js';
 
@@ -129,9 +129,14 @@ export class OpenClawGatewayClient {
   private connectResolve: (() => void) | null = null;
   private connectReject: ((error: Error) => void) | null = null;
   private connectTimeout: ReturnType<typeof setTimeout> | null = null;
+  private pairingRejected = false;
+  private consecutiveFailures = 0;
 
   /** Default timeout for initial connection (30 seconds). */
   private static readonly CONNECT_TIMEOUT_MS = 30_000;
+  private static readonly MAX_CONSECUTIVE_FAILURES = 5;
+  private static readonly BASE_RECONNECT_MS = 3_000;
+  private static readonly MAX_RECONNECT_MS = 30_000;
 
   constructor(token: string, port: number) {
     this.token = token;
@@ -143,6 +148,10 @@ export class OpenClawGatewayClient {
   async connect(): Promise<void> {
     if (this.authenticated && this.ws?.readyState === WebSocket.OPEN) return;
 
+    // Explicit connect() clears pairing rejection so users can retry after fixing their token
+    this.pairingRejected = false;
+    this.stopped = false;
+
     // Cancel any pending reconnect timer to prevent orphaned WebSocket connections
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -196,9 +205,18 @@ export class OpenClawGatewayClient {
     });
 
     this.ws.on('close', (code, reason) => {
-      console.warn(`[openclaw-ws] Disconnected: ${code} ${reason.toString()}`);
+      const reasonStr = reason.toString();
+      console.warn(`[openclaw-ws] Disconnected: ${code} ${reasonStr}`);
       const wasAuthenticated = this.authenticated;
       this.authenticated = false;
+
+      // Detect pairing rejection via close code 1008 (Policy Violation)
+      if (code === 1008 || /pairing|not.paired/i.test(reasonStr)) {
+        console.error('[openclaw-ws] Connection closed due to pairing policy. Device is not paired.');
+        console.error('[openclaw-ws] Ensure OPENCLAW_GATEWAY_TOKEN matches ~/.openclaw/openclaw.json gateway.auth.token');
+        this.pairingRejected = true;
+      }
+
       // Reject all pending RPCs
       for (const [id, pending] of this.pendingRpcs) {
         clearTimeout(pending.timer);
@@ -213,7 +231,7 @@ export class OpenClawGatewayClient {
         this.connectReject = null;
         this.connectResolve = null;
       }
-      if (!this.stopped) {
+      if (!this.stopped && !this.pairingRejected) {
         this.scheduleReconnect();
       }
     });
@@ -307,14 +325,23 @@ export class OpenClawGatewayClient {
       if (msg.ok) {
         console.log('[openclaw-ws] Authenticated successfully');
         this.authenticated = true;
+        this.consecutiveFailures = 0;
         this.connectResolve?.();
         this.connectResolve = null;
         this.connectReject = null;
       } else {
-        console.warn(`[openclaw-ws] Auth rejected: ${JSON.stringify(msg.error ?? msg)}`);
-        // Reject the connect promise on auth failure
-        const errMsg = msg.error ? JSON.stringify(msg.error) : 'Authentication rejected';
-        this.connectReject?.(new Error(`OpenClaw gateway auth failed: ${errMsg}`));
+        const errStr = msg.error ? JSON.stringify(msg.error) : 'Authentication rejected';
+        const isPairing = /pairing.required|not.paired/i.test(errStr);
+
+        if (isPairing) {
+          console.error('[openclaw-ws] Pairing rejected — device is not paired with the OpenClaw gateway.');
+          console.error('[openclaw-ws] Ensure OPENCLAW_GATEWAY_TOKEN matches ~/.openclaw/openclaw.json gateway.auth.token');
+          this.pairingRejected = true;
+        } else {
+          console.warn(`[openclaw-ws] Auth rejected: ${errStr}`);
+        }
+
+        this.connectReject?.(new Error(`OpenClaw gateway auth failed: ${errStr}`));
         this.connectReject = null;
         this.connectResolve = null;
       }
@@ -388,12 +415,25 @@ export class OpenClawGatewayClient {
   }
 
   private scheduleReconnect(): void {
-    if (this.stopped || this.reconnectTimer) return;
-    console.log('[openclaw-ws] Reconnecting in 3s...');
+    if (this.stopped || this.pairingRejected || this.reconnectTimer) return;
+
+    this.consecutiveFailures++;
+
+    if (this.consecutiveFailures >= OpenClawGatewayClient.MAX_CONSECUTIVE_FAILURES) {
+      console.warn(`[openclaw-ws] ${this.consecutiveFailures} consecutive connection failures — stopping reconnect.`);
+      console.warn('[openclaw-ws] Check that the OpenClaw gateway is running and OPENCLAW_GATEWAY_TOKEN is correct.');
+      return;
+    }
+
+    const delay = Math.min(
+      OpenClawGatewayClient.BASE_RECONNECT_MS * Math.pow(2, this.consecutiveFailures - 1),
+      OpenClawGatewayClient.MAX_RECONNECT_MS,
+    );
+    console.log(`[openclaw-ws] Reconnecting in ${delay / 1000}s (attempt ${this.consecutiveFailures})...`);
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       this.doConnect();
-    }, 3_000);
+    }, delay);
   }
 
   async disconnect(): Promise<void> {
@@ -475,7 +515,7 @@ export class InboundGateway {
 
     // Connect to the local OpenClaw gateway WebSocket (persistent connection)
     const token = this.config.openclawGatewayToken ?? process.env.OPENCLAW_GATEWAY_TOKEN;
-    const port = this.config.openclawGatewayPort ?? 18789;
+    const port = this.config.openclawGatewayPort ?? DEFAULT_OPENCLAW_GATEWAY_PORT;
 
     if (token) {
       this.openclawClient = new OpenClawGatewayClient(token, port);

package/packages/openclaw/src/inject.ts

@@ -1,6 +1,6 @@
 import type { AgentRelayClient, SendMessageInput } from '@agent-relay/sdk';
 
-import type { InboundMessage, DeliveryResult } from './types.js';
+import { DEFAULT_OPENCLAW_GATEWAY_PORT, type InboundMessage, type DeliveryResult } from './types.js';
 
 /**
  * Deliver a message to the local claw using the best available method.
@@ -44,7 +44,7 @@ export async function deliverMessage(
 
   // Fallback: OpenClaw OpenResponses API (POST /v1/responses on local gateway)
   try {
-    const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT ?? process.env.GATEWAY_PORT ?? '18789';
+    const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT ?? process.env.GATEWAY_PORT ?? String(DEFAULT_OPENCLAW_GATEWAY_PORT);
     const token = process.env.OPENCLAW_GATEWAY_TOKEN;
     const headers: Record<string, string> = { 'Content-Type': 'application/json' };
     if (token) {

package/packages/openclaw/src/setup.ts

@@ -1,4 +1,5 @@
 import { mkdir, writeFile, readFile, copyFile } from 'node:fs/promises';
+import { createConnection } from 'node:net';
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { hostname } from 'node:os';
@@ -8,7 +9,21 @@ import { spawn as spawnProcess, execFileSync } from 'node:child_process';
 import { RelayCast } from '@relaycast/sdk';
 
 import { detectOpenClaw, saveGatewayConfig } from './config.js';
-import type { GatewayConfig } from './types.js';
+import { InboundGateway } from './gateway.js';
+import { DEFAULT_OPENCLAW_GATEWAY_PORT, type GatewayConfig } from './types.js';
+
+/**
+ * Safely traverse a nested object by dot-separated path.
+ * Returns undefined if any segment is missing.
+ */
+function extractNestedValue(obj: unknown, path: string): unknown {
+  let current: unknown = obj;
+  for (const key of path.split('.')) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
 
 /**
  * Resolve how to invoke mcporter. Prefers a global binary, falls back to npx.
@@ -28,6 +43,26 @@ function resolveMcporter(): { cmd: string; prefix: string[] } {
   }
 }
 
+/** Check if a port is already in use by attempting a TCP connection. */
+function isPortInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host: '127.0.0.1' });
+    socket.setTimeout(2000);
+    socket.once('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once('timeout', () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once('error', () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
 export interface SetupOptions {
   /** If provided, join this workspace. Otherwise create a new one. */
   apiKey?: string;
@@ -185,12 +220,29 @@ export async function setup(options: SetupOptions): Promise<SetupResult> {
     );
   }
 
+  // Extract gateway auth from openclaw.json (if available)
+  const openclawGatewayToken =
+    process.env.OPENCLAW_GATEWAY_TOKEN ??
+    (extractNestedValue(detection.config, 'gateway.auth.token') as string | undefined);
+  const openclawGatewayPortRaw =
+    process.env.OPENCLAW_GATEWAY_PORT ??
+    (extractNestedValue(detection.config, 'gateway.port') as number | string | undefined);
+  const openclawGatewayPort = openclawGatewayPortRaw ? Number(openclawGatewayPortRaw) : undefined;
+
+  if (!openclawGatewayToken) {
+    console.warn('[setup] No gateway token found in openclaw.json or OPENCLAW_GATEWAY_TOKEN env.');
+    console.warn('[setup] Inbound gateway may fail to pair. Set it manually:');
+    console.warn('[setup]   export OPENCLAW_GATEWAY_TOKEN=$(cat ~/.openclaw/openclaw.json | jq -r .gateway.auth.token)');
+  }
+
   // Save gateway config (.env)
   const gatewayConfig: GatewayConfig = {
     apiKey,
     clawName,
     baseUrl,
     channels,
+    openclawGatewayToken,
+    openclawGatewayPort: Number.isFinite(openclawGatewayPort) ? openclawGatewayPort : undefined,
   };
   await saveGatewayConfig(gatewayConfig);
 
@@ -281,18 +333,41 @@ export async function setup(options: SetupOptions): Promise<SetupResult> {
     }
   }
 
-  // Auto-start the inbound gateway in the background
+  // Auto-start the inbound gateway in the background, but only if one isn't
+  // already running. Re-running setup without this check spawns duplicates
+  // that fight over the control port.
   let gatewayStarted = false;
-  try {
-    const child = spawnProcess('npx', ['@agent-relay/openclaw', 'gateway'], {
-      stdio: 'ignore',
-      detached: true,
-      env: { ...process.env, RELAY_API_KEY: apiKey, RELAY_CLAW_NAME: clawName, RELAY_BASE_URL: baseUrl },
-    });
-    child.unref();
+  // Check the inbound gateway's control port (18790), NOT the OpenClaw
+  // gateway WS port (18789) — they are different processes.
+  const controlPort = Number(process.env.RELAYCAST_CONTROL_PORT) || InboundGateway.DEFAULT_CONTROL_PORT;
+  const gatewayAlreadyRunning = await isPortInUse(controlPort);
+  if (gatewayAlreadyRunning) {
+    console.log('[setup] Inbound gateway already running — skipping spawn.');
     gatewayStarted = true;
-  } catch {
-    // Non-fatal — user can start manually
+  } else {
+    try {
+      const gatewayEnv: Record<string, string> = {
+        ...process.env as Record<string, string>,
+        RELAY_API_KEY: apiKey,
+        RELAY_CLAW_NAME: clawName,
+        RELAY_BASE_URL: baseUrl,
+      };
+      if (openclawGatewayToken) {
+        gatewayEnv.OPENCLAW_GATEWAY_TOKEN = openclawGatewayToken;
+      }
+      if (openclawGatewayPort && Number.isFinite(openclawGatewayPort)) {
+        gatewayEnv.OPENCLAW_GATEWAY_PORT = String(openclawGatewayPort);
+      }
+      const child = spawnProcess('npx', ['@agent-relay/openclaw', 'gateway'], {
+        stdio: 'ignore',
+        detached: true,
+        env: gatewayEnv,
+      });
+      child.unref();
+      gatewayStarted = true;
+    } catch {
+      // Non-fatal — user can start manually
+    }
   }
 
   const parts = [

package/packages/openclaw/src/spawn/docker.ts

@@ -8,6 +8,7 @@ import { normalizeModelRef } from '../identity/model.js';
 import { buildIdentityTask } from '../identity/contract.js';
 import { buildAgentName } from '../identity/naming.js';
 import { convertCodexAuth } from '../auth/converter.js';
+import { DEFAULT_OPENCLAW_GATEWAY_PORT } from '../types.js';
 
 async function pathExists(targetPath: string): Promise<boolean> {
   try {
@@ -152,7 +153,7 @@ export class DockerSpawnProvider implements SpawnProvider {
     const modelRef = normalizeModelRef(options.model, preferredProvider);
     const workspaceId = options.workspaceId ?? `local-${Date.now().toString(36)}`;
     const agentName = buildAgentName(workspaceId, options.name);
-    const gatewayPort = 18789; // Internal to container — each container is isolated
+    const gatewayPort = DEFAULT_OPENCLAW_GATEWAY_PORT; // Internal to container — each container is isolated
     const identityTask = buildIdentityTask(agentName, workspaceId, modelRef);
     const channels = options.channels?.length ? options.channels : ['general'];
     const gatewayToken = randomUUID().replace(/-/g, '').slice(0, 32);

package/packages/openclaw/src/types.ts

@@ -1,3 +1,6 @@
+/** Default port for the local OpenClaw gateway WebSocket API. */
+export const DEFAULT_OPENCLAW_GATEWAY_PORT = 18789;
+
 export interface GatewayConfig {
   /** Relaycast workspace API key (rk_live_*). */
   apiKey: string;

package/packages/policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/policy",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.4"
+    "@agent-relay/config": "3.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -81,7 +81,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.4",
+    "@agent-relay/config": "3.1.5",
     "@relaycast/sdk": "^0.4.0",
     "yaml": "^2.7.0"
   }

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.1.4"
+version = "3.1.5"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.4"
+    "@agent-relay/config": "3.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "3.1.4"
+    "@agent-relay/utils": "3.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.4",
+    "@agent-relay/config": "3.1.5",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {