agent-relay 3.0.2 → 3.1.1

package/packages/openclaw/src/setup.ts

@@ -0,0 +1,336 @@
+import { mkdir, writeFile, readFile, copyFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn as spawnProcess, execFileSync } from 'node:child_process';
+
+import { detectOpenClaw, saveGatewayConfig } from './config.js';
+import type { GatewayConfig } from './types.js';
+
+export interface SetupOptions {
+  /** If provided, join this workspace. Otherwise create a new one. */
+  apiKey?: string;
+  /** Name for this claw (default: hostname). */
+  clawName?: string;
+  /** Channels to auto-join (default: ['general']). */
+  channels?: string[];
+  /** Relaycast API base URL. */
+  baseUrl?: string;
+}
+
+export interface SetupResult {
+  ok: boolean;
+  apiKey: string;
+  clawName: string;
+  skillDir: string;
+  message: string;
+}
+
+/**
+ * Install the Relaycast bridge into an OpenClaw workspace.
+ *
+ * 1. Detect OpenClaw installation
+ * 2. Create/join workspace via Relaycast API (if no key provided)
+ * 3. Install SKILL.md
+ * 4. Write .env config
+ * 5. Configure MCP server in openclaw.json
+ * 6. Print success summary
+ */
+export async function setup(options: SetupOptions): Promise<SetupResult> {
+  const detection = await detectOpenClaw();
+  const clawName = options.clawName ?? hostname() ?? 'my-claw';
+  const baseUrl = options.baseUrl ?? 'https://api.relaycast.dev';
+  const channels = options.channels ?? ['general'];
+
+  if (!detection.installed) {
+    // Auto-create ~/.openclaw/ if OpenClaw binary is available but the config dir
+    // doesn't exist yet (common in Docker images before onboarding).
+    try {
+      await mkdir(detection.homeDir, { recursive: true });
+      await mkdir(join(detection.homeDir, 'workspace'), { recursive: true });
+      // Write a minimal openclaw.json so MCP servers can be registered
+      const configPath = join(detection.homeDir, 'openclaw.json');
+      if (!existsSync(configPath)) {
+        await writeFile(configPath, JSON.stringify({ mcpServers: {} }, null, 2) + '\n', 'utf-8');
+      }
+      // Re-detect after creating
+      const redetection = await detectOpenClaw();
+      Object.assign(detection, redetection);
+    } catch {
+      return {
+        ok: false,
+        apiKey: '',
+        clawName,
+        skillDir: '',
+        message:
+          'OpenClaw not found. Please install OpenClaw first (expected ~/.openclaw/ directory).',
+      };
+    }
+  }
+
+  // Enable the OpenResponses HTTP API so the inbound gateway can inject
+  // messages via POST /v1/responses on the local OpenClaw gateway.
+  try {
+    execFileSync('openclaw', [
+      'config', 'set',
+      'gateway.http.endpoints.responses.enabled', 'true',
+    ], { stdio: 'pipe' });
+  } catch {
+    console.warn('Could not enable OpenResponses API (non-fatal). Enable manually:');
+    console.warn('  openclaw config set gateway.http.endpoints.responses.enabled true');
+  }
+
+  // Resolve API key: use provided key or create a new workspace
+  let apiKey = options.apiKey;
+
+  if (!apiKey) {
+    try {
+      const res = await fetch(`${baseUrl}/v1/workspaces`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: `${clawName}-workspace` }),
+      });
+
+      if (res.status === 409) {
+        // Workspace already exists — look up its API key
+        const lookupRes = await fetch(`${baseUrl}/v1/workspaces/by-name/${encodeURIComponent(`${clawName}-workspace`)}`, {
+          headers: { 'Content-Type': 'application/json' },
+        });
+        if (lookupRes.ok) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const lookupBody = (await lookupRes.json()) as any;
+          apiKey = lookupBody.apiKey ?? lookupBody.api_key ?? lookupBody.data?.apiKey ?? lookupBody.data?.api_key;
+        }
+        if (!apiKey) {
+          return {
+            ok: false,
+            apiKey: '',
+            clawName,
+            skillDir: '',
+            message: `Workspace "${clawName}-workspace" already exists. Pass the workspace key: @agent-relay/openclaw setup <key> --name ${clawName}`,
+          };
+        }
+      } else if (!res.ok) {
+        const body = await res.text();
+        return {
+          ok: false,
+          apiKey: '',
+          clawName,
+          skillDir: '',
+          message: `Failed to create workspace: ${res.status} ${body}`,
+        };
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const successBody = (await res.json()) as any;
+        apiKey = successBody.apiKey ?? successBody.api_key ?? successBody.data?.apiKey ?? successBody.data?.api_key;
+      }
+
+      if (!apiKey) {
+        return {
+          ok: false,
+          apiKey: '',
+          clawName,
+          skillDir: '',
+          message: 'Workspace created but no API key returned.',
+        };
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        apiKey: '',
+        clawName,
+        skillDir: '',
+        message: `Failed to create workspace: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  // Agent registration is done after mcporter is configured (see below),
+  // since the register tool is accessed via mcporter call relaycast.register.
+
+  // Install SKILL.md
+  const skillDir = join(detection.workspaceDir, 'relaycast');
+  await mkdir(skillDir, { recursive: true });
+
+  const skillSrc = resolveSkillPath();
+  if (existsSync(skillSrc)) {
+    await copyFile(skillSrc, join(skillDir, 'SKILL.md'));
+  } else {
+    // Write a minimal SKILL.md inline if the bundled one isn't found
+    await writeFile(
+      join(skillDir, 'SKILL.md'),
+      FALLBACK_SKILL_MD,
+      'utf-8',
+    );
+  }
+
+  // Save gateway config (.env)
+  const gatewayConfig: GatewayConfig = {
+    apiKey,
+    clawName,
+    baseUrl,
+    channels,
+  };
+  await saveGatewayConfig(gatewayConfig);
+
+  // Register MCP servers via mcporter
+  let mcpConfigured = false;
+  {
+    const envArgs = [
+      '--env', `RELAY_API_KEY=${apiKey}`,
+      ...(baseUrl !== 'https://api.relaycast.dev'
+        ? ['--env', `RELAY_BASE_URL=${baseUrl}`]
+        : []),
+    ];
+
+    try {
+      // Register relaycast messaging MCP server
+      execFileSync('mcporter', [
+        'config', 'add', 'relaycast',
+        '--command', 'npx',
+        '--arg', '@relaycast/mcp',
+        ...envArgs,
+        '--scope', 'home',
+        '--description', 'Relaycast messaging MCP server',
+      ], { stdio: 'pipe' });
+
+      // Register openclaw-spawner MCP server
+      execFileSync('mcporter', [
+        'config', 'add', 'openclaw-spawner',
+        '--command', 'npx',
+        '--arg', '@agent-relay/openclaw',
+        '--arg', 'mcp-server',
+        ...envArgs,
+        '--scope', 'home',
+        '--description', 'OpenClaw spawner MCP server',
+      ], { stdio: 'pipe' });
+
+      mcpConfigured = true;
+
+      // Register this claw as an agent via mcporter and persist the agent token
+      try {
+        const registerOutput = execFileSync('mcporter', [
+          'call', 'relaycast.register',
+          'name=' + clawName,
+          'type=agent',
+        ], { stdio: 'pipe', encoding: 'utf-8' });
+
+        // Parse the agent token from the register output
+        let agentToken: string | undefined;
+        try {
+          const parsed = JSON.parse(registerOutput);
+          agentToken = parsed.token ?? parsed.agentToken ?? parsed.agent_token;
+        } catch {
+          // Try to find token in raw output
+          const tokenMatch = registerOutput.match(/"token"\s*:\s*"([^"]+)"/);
+          if (tokenMatch) agentToken = tokenMatch[1];
+        }
+
+        if (agentToken) {
+          // Reconfigure mcporter with the agent token so subsequent calls are authenticated
+          try {
+            execFileSync('mcporter', ['config', 'remove', 'relaycast'], { stdio: 'pipe' });
+          } catch { /* may not exist */ }
+
+          execFileSync('mcporter', [
+            'config', 'add', 'relaycast',
+            '--command', 'npx',
+            '--arg', '@relaycast/mcp',
+            ...envArgs,
+            '--env', `RELAY_AGENT_TOKEN=${agentToken}`,
+            '--scope', 'home',
+            '--description', 'Relaycast messaging MCP server',
+          ], { stdio: 'pipe' });
+
+          console.log(`Agent "${clawName}" registered with token.`);
+        } else {
+          console.warn('Agent registered but no token found in response.');
+        }
+      } catch (regErr) {
+        console.warn(`Agent registration via mcporter failed (non-fatal): ${regErr instanceof Error ? regErr.message : String(regErr)}`);
+      }
+    } catch (err) {
+      // mcporter not installed — non-fatal, print manual instructions
+      console.warn('mcporter not found. Install MCP servers manually:');
+      console.warn(`  mcporter config add relaycast --command npx --arg @relaycast/mcp --env RELAY_API_KEY=${apiKey} --scope home`);
+      console.warn(`  mcporter config add openclaw-spawner --command npx --arg @agent-relay/openclaw --arg mcp-server --env RELAY_API_KEY=${apiKey} --scope home`);
+    }
+  }
+
+  // Auto-start the inbound gateway in the background
+  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();
+    gatewayStarted = true;
+  } catch {
+    // Non-fatal — user can start manually
+  }
+
+  const parts = [
+    `Relaycast bridge installed at ${skillDir}`,
+    mcpConfigured ? 'MCP server configured in openclaw.json.' : '',
+    `Claw name: ${clawName}`,
+    `Channels: ${channels.join(', ')}`,
+    gatewayStarted
+      ? 'Inbound gateway started in background.'
+      : 'Start the inbound gateway manually:\n  relay-openclaw gateway',
+  ].filter(Boolean);
+
+  return {
+    ok: true,
+    apiKey,
+    clawName,
+    skillDir,
+    message: parts.join('\n'),
+  };
+}
+
+/** Resolve the path to the bundled SKILL.md. */
+function resolveSkillPath(): string {
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return join(thisDir, '..', 'skill', 'SKILL.md');
+  } catch {
+    return join(process.cwd(), 'skill', 'SKILL.md');
+  }
+}
+
+const FALLBACK_SKILL_MD = `# Relaycast Bridge
+
+Structured messaging for multi-claw communication. Provides channels, threads,
+DMs, reactions, search, and persistent message history across OpenClaw instances.
+
+## Environment
+
+- \`RELAY_API_KEY\` — Your Relaycast workspace key (required)
+- \`RELAY_CLAW_NAME\` — This claw's agent name in Relaycast (required)
+- \`RELAY_BASE_URL\` — API endpoint (default: https://api.relaycast.dev)
+
+## Setup
+
+\`\`\`bash
+relay-openclaw setup [YOUR_WORKSPACE_KEY]
+\`\`\`
+
+## MCP Tools
+
+Once installed, use the Relaycast MCP tools:
+- \`post_message\` — Send to a channel
+- \`send_dm\` — Direct message another agent
+- \`reply_to_thread\` — Reply in a thread
+- \`check_inbox\` — See unread messages
+
+## Commands
+
+\`\`\`bash
+relay-openclaw setup [key]    # Install & configure
+relay-openclaw gateway        # Start inbound gateway
+relay-openclaw status         # Check connection
+\`\`\`
+`;

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

@@ -0,0 +1,261 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+import type { SpawnProvider, SpawnOptions, SpawnHandle } from './types.js';
+import { normalizeModelRef } from '../identity/model.js';
+import { buildIdentityTask } from '../identity/contract.js';
+import { buildAgentName } from '../identity/naming.js';
+import { convertCodexAuth } from '../auth/converter.js';
+
+async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function expandHomeDir(input: string): string {
+  if (input === '~') return homedir();
+  if (input.startsWith('~/')) return join(homedir(), input.slice(2));
+  return input;
+}
+
+function sanitizeContainerSegment(value: string): string {
+  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '-');
+  return normalized.replace(/^-+|-+$/g, '') || 'claw';
+}
+
+export interface DockerSpawnProviderOptions {
+  /** Docker image to use. Default: 'openclaw:local'. */
+  image?: string;
+  /** Fallback image if primary not found. Default: 'clawrunner-sandbox:latest'. */
+  imageFallback?: string;
+  /** Docker network mode. Default: 'bridge'. */
+  networkMode?: string;
+  /** Docker socket path. Default: '/var/run/docker.sock'. */
+  socketPath?: string;
+  /** Path to host codex auth.json. Default: ~/.codex/auth.json. */
+  codexAuthFile?: string;
+  /** Path to host codex config.toml. Default: ~/.codex/config.toml. */
+  codexConfigFile?: string;
+  /** Container home dir. Default: '/home/node'. */
+  containerHome?: string;
+  /**
+   * Custom container command. If set, overrides the default entrypoint.
+   * Use this for ClawRunner-managed images that have /opt/clawrunner/start-claw.sh.
+   * Default: uses @agent-relay/openclaw runtime-setup + openclaw gateway + agent-relay broker-spawn.
+   */
+  containerCmd?: string[];
+}
+
+/**
+ * Spawn OpenClaw instances as Docker containers.
+ * Requires `dockerode` as an optional peer dependency — dynamically imported at runtime.
+ *
+ * By default, the container runs:
+ *   1. `npx @agent-relay/openclaw runtime-setup` — auth conversion, config, identity files, dist patching
+ *   2. `openclaw gateway` in background
+ *   3. `agent-relay broker-spawn --from-env` as PID 1
+ *
+ * For ClawRunner-managed images, set containerCmd to ['/opt/clawrunner/start-claw.sh'].
+ */
+export class DockerSpawnProvider implements SpawnProvider {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private docker: any = null;
+  private readonly image: string;
+  private readonly imageFallback: string;
+  private readonly networkMode: string;
+  private readonly socketPath: string;
+  private readonly codexAuthFile: string;
+  private readonly codexConfigFile: string;
+  private readonly containerHome: string;
+  private readonly containerCmd: string[] | null;
+  private readonly handles = new Map<string, SpawnHandle>();
+
+  constructor(options: DockerSpawnProviderOptions = {}) {
+    this.image = options.image ?? process.env.CLAW_IMAGE ?? 'openclaw:local';
+    this.imageFallback = options.imageFallback ?? process.env.CLAW_IMAGE_FALLBACK ?? 'clawrunner-sandbox:latest';
+    this.networkMode = options.networkMode ?? process.env.CLAW_NETWORK ?? 'bridge';
+    this.socketPath = options.socketPath ?? process.env.DOCKER_SOCKET ?? '/var/run/docker.sock';
+    this.codexAuthFile = expandHomeDir(options.codexAuthFile ?? process.env.CLAW_CODEX_AUTH_FILE ?? '~/.codex/auth.json');
+    this.codexConfigFile = expandHomeDir(options.codexConfigFile ?? process.env.CLAW_CODEX_CONFIG_FILE ?? '~/.codex/config.toml');
+    this.containerHome = options.containerHome ?? process.env.CLAW_CONTAINER_HOME ?? '/home/node';
+    this.containerCmd = options.containerCmd ?? (process.env.CLAW_CONTAINER_CMD
+      ? process.env.CLAW_CONTAINER_CMD.split(' ')
+      : null);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async getDocker(): Promise<any> {
+    if (this.docker) return this.docker;
+    try {
+      // @ts-expect-error dockerode is an optional dependency
+      const mod = await import('dockerode');
+      const Docker = mod.default ?? mod;
+      this.docker = new Docker({ socketPath: this.socketPath });
+      return this.docker;
+    } catch {
+      throw new Error(
+        'dockerode is required for Docker spawning. Install it with: npm install dockerode',
+      );
+    }
+  }
+
+  /**
+   * Build the default container entrypoint script.
+   * This script works with any vanilla OpenClaw image that has `openclaw` and `node` on PATH.
+   * It runs runtime-setup via the package CLI, starts the gateway, then hands off to broker-spawn.
+   */
+  private buildEntrypointScript(gatewayPort: number): string[] {
+    // Shell script that runs setup, starts gateway, waits for health, then execs broker-spawn.
+    // Uses sh -c so it works in minimal alpine images.
+    // Runtime setup via package CLI, then gateway, then SDK's spawnFromEnv()
+    // which handles broker + agent lifecycle without needing the agent-relay CLI.
+    const script = [
+      'set -e',
+      // Runtime setup: auth conversion, openclaw.json, identity files, dist patching
+      'npx @agent-relay/openclaw runtime-setup',
+      // Resolve bridge.mjs from the installed package and symlink to the known AGENT_ARGS path.
+      // This handles any npm install location (global, local, npx cache).
+      'node -e "' +
+        "const p = require('path');" +
+        "const m = require('module');" +
+        "const r = m.createRequire(require.resolve('@agent-relay/openclaw/package.json'));" +
+        "const bp = p.join(p.dirname(require.resolve('@agent-relay/openclaw/package.json')), 'bridge', 'bridge.mjs');" +
+        "require('fs').symlinkSync(bp, '/tmp/openclaw-bridge.mjs');" +
+        "console.log('[entrypoint] Bridge resolved: ' + bp);" +
+      '"',
+      // Start gateway in background
+      `openclaw gateway --port ${gatewayPort} --bind loopback --allow-unconfigured --auth token &`,
+      // Wait for gateway health
+      `for i in $(seq 1 30); do`,
+      `  if openclaw health --port ${gatewayPort} 2>/dev/null; then break; fi`,
+      `  if [ "$i" -eq 30 ]; then echo "Gateway failed to start" >&2; exit 1; fi`,
+      `  sleep 1`,
+      `done`,
+      // Use SDK's spawnFromEnv() instead of shelling out to agent-relay CLI.
+      // This reads AGENT_NAME, AGENT_CLI, RELAY_API_KEY etc. from env,
+      // creates a broker internally, spawns the agent via PTY, and waits for exit.
+      `node -e "import('@agent-relay/sdk').then(m => m.spawnFromEnv())"`,
+    ].join('\n');
+
+    return ['sh', '-c', script];
+  }
+
+  async spawn(options: SpawnOptions): Promise<SpawnHandle> {
+    const docker = await this.getDocker();
+    const { preferredProvider } = await convertCodexAuth();
+    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 identityTask = buildIdentityTask(agentName, workspaceId, modelRef);
+    const channels = options.channels?.length ? options.channels : ['general'];
+    const gatewayToken = randomUUID().replace(/-/g, '').slice(0, 32);
+
+    const suffix = `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+    const containerName = `openclaw-${sanitizeContainerSegment(agentName)}-${suffix}`.slice(0, 63);
+
+    const binds: string[] = [];
+    if (options.workspacePath) {
+      binds.push(`${options.workspacePath}:/workspace:rw`);
+    }
+    if (await pathExists(this.codexAuthFile)) {
+      binds.push(`${this.codexAuthFile}:${this.containerHome}/.codex/auth.json:rw`);
+    }
+    if (await pathExists(this.codexConfigFile)) {
+      binds.push(`${this.codexConfigFile}:${this.containerHome}/.codex/config.toml:ro`);
+    }
+
+    const envVars: Record<string, string> = {
+      AGENT_NAME: agentName,
+      AGENT_CLI: 'node',
+      // Bridge path: resolved dynamically inside the container via the entrypoint script.
+      // The entrypoint writes the resolved path to /tmp/bridge-path.txt after runtime-setup.
+      AGENT_ARGS: '/tmp/openclaw-bridge.mjs',
+      RELAY_API_KEY: options.relayApiKey,
+      RELAY_BASE_URL: options.relayBaseUrl ?? '',
+      AGENT_TASK: options.systemPrompt
+        ? `${options.systemPrompt}\n\n${identityTask}`
+        : identityTask,
+      AGENT_CWD: '/workspace',
+      AGENT_CHANNELS: channels.join(','),
+      GATEWAY_PORT: String(gatewayPort),
+      OPENCLAW_GATEWAY_TOKEN: gatewayToken,
+      OPENCLAW_WORKSPACE_ID: workspaceId,
+      OPENCLAW_NAME: options.name,
+      OPENCLAW_ROLE: options.role ?? 'general',
+      OPENCLAW_MODEL: modelRef,
+      BROKER_NO_REMOTE_SPAWN: '1',
+    };
+
+    // Try to remove stale container with same name
+    try {
+      const stale = docker.getContainer(containerName);
+      await stale.stop({ t: 5 }).catch(() => {});
+      await stale.remove({ force: true }).catch(() => {});
+    } catch {
+      // No stale container
+    }
+
+    let imageToUse = this.image;
+    try {
+      await docker.getImage(this.image).inspect();
+    } catch {
+      imageToUse = this.imageFallback;
+    }
+
+    // Use custom cmd if provided, otherwise generate a vanilla-compatible entrypoint
+    const cmd = this.containerCmd ?? this.buildEntrypointScript(gatewayPort);
+
+    const container = await docker.createContainer({
+      Image: imageToUse,
+      name: containerName,
+      Env: Object.entries(envVars).map(([k, v]: [string, string]) => `${k}=${v}`),
+      Cmd: cmd,
+      WorkingDir: '/workspace',
+      Labels: {
+        '@agent-relay/openclaw.spawn': 'true',
+        '@agent-relay/openclaw.agent': agentName,
+      },
+      HostConfig: {
+        NetworkMode: this.networkMode,
+        Binds: binds,
+        AutoRemove: false,
+      },
+    });
+
+    await container.start();
+
+    const handle: SpawnHandle = {
+      id: container.id,
+      displayName: options.name,
+      agentName,
+      gatewayPort,
+      destroy: () => this.destroy(container.id),
+    };
+
+    this.handles.set(container.id, handle);
+    return handle;
+  }
+
+  async destroy(id: string): Promise<void> {
+    this.handles.delete(id);
+    try {
+      const docker = await this.getDocker();
+      const container = docker.getContainer(id);
+      await container.stop({ t: 5 }).catch(() => {});
+      await container.remove({ force: true }).catch(() => {});
+    } catch {
+      // Already gone
+    }
+  }
+
+  async list(): Promise<SpawnHandle[]> {
+    return Array.from(this.handles.values());
+  }
+}