agent-relay 3.0.2 → 3.1.1

package/packages/openclaw/dist/setup.js

@@ -0,0 +1,300 @@
+import { mkdir, writeFile, 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';
+/**
+ * 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) {
+    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());
+                    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());
+                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 = {
+        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;
+                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() {
+    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
+\`\`\`
+`;
+//# sourceMappingURL=setup.js.map

package/packages/openclaw/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/packages/openclaw/dist/spawn/docker.d.ts

@@ -0,0 +1,58 @@
+import type { SpawnProvider, SpawnOptions, SpawnHandle } from './types.js';
+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 declare class DockerSpawnProvider implements SpawnProvider {
+    private docker;
+    private readonly image;
+    private readonly imageFallback;
+    private readonly networkMode;
+    private readonly socketPath;
+    private readonly codexAuthFile;
+    private readonly codexConfigFile;
+    private readonly containerHome;
+    private readonly containerCmd;
+    private readonly handles;
+    constructor(options?: DockerSpawnProviderOptions);
+    private getDocker;
+    /**
+     * 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;
+    spawn(options: SpawnOptions): Promise<SpawnHandle>;
+    destroy(id: string): Promise<void>;
+    list(): Promise<SpawnHandle[]>;
+}
+//# sourceMappingURL=docker.d.ts.map

package/packages/openclaw/dist/spawn/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/spawn/docker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0B3E,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAEvD,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAE9C,OAAO,GAAE,0BAA+B;YActC,SAAS;IAevB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAiGlD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlC,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAGrC"}

package/packages/openclaw/dist/spawn/docker.js

@@ -0,0 +1,222 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+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) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function expandHomeDir(input) {
+    if (input === '~')
+        return homedir();
+    if (input.startsWith('~/'))
+        return join(homedir(), input.slice(2));
+    return input;
+}
+function sanitizeContainerSegment(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '-');
+    return normalized.replace(/^-+|-+$/g, '') || 'claw';
+}
+/**
+ * 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 {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    docker = null;
+    image;
+    imageFallback;
+    networkMode;
+    socketPath;
+    codexAuthFile;
+    codexConfigFile;
+    containerHome;
+    containerCmd;
+    handles = new Map();
+    constructor(options = {}) {
+        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
+    async getDocker() {
+        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.
+     */
+    buildEntrypointScript(gatewayPort) {
+        // 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) {
+        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 = [];
+        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 = {
+            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]) => `${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 = {
+            id: container.id,
+            displayName: options.name,
+            agentName,
+            gatewayPort,
+            destroy: () => this.destroy(container.id),
+        };
+        this.handles.set(container.id, handle);
+        return handle;
+    }
+    async destroy(id) {
+        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() {
+        return Array.from(this.handles.values());
+    }
+}
+//# sourceMappingURL=docker.js.map

package/packages/openclaw/dist/spawn/docker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.js","sourceRoot":"","sources":["../../src/spawn/docker.ts"],"names":[],"mappings":"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"}

package/packages/openclaw/dist/spawn/manager.d.ts

@@ -0,0 +1,45 @@
+import type { SpawnOptions, SpawnHandle } from './types.js';
+export type SpawnMode = 'process' | 'docker';
+interface PersistedSpawn {
+    id: string;
+    displayName: string;
+    agentName: string;
+    gatewayPort: number;
+    spawnedAt: string;
+}
+/**
+ * SpawnManager — tracks active spawns and provides a unified interface
+ * for spawning, listing, and releasing OpenClaw instances.
+ *
+ * Security controls:
+ *   - maxSpawns: Maximum concurrent spawns (default: 10)
+ *   - maxDepth: Maximum spawn depth to prevent recursive chains (default: 3)
+ *   - Persistent state in spawns.json for recovery on restart
+ */
+export declare class SpawnManager {
+    private readonly provider;
+    private readonly handles;
+    private readonly maxSpawns;
+    private readonly maxDepth;
+    private readonly stateFile;
+    private currentDepth;
+    constructor(options?: {
+        mode?: SpawnMode;
+        maxSpawns?: number;
+        maxDepth?: number;
+        spawnDepth?: number;
+    });
+    spawn(options: SpawnOptions): Promise<SpawnHandle>;
+    release(id: string): Promise<boolean>;
+    releaseByName(name: string): Promise<boolean>;
+    releaseAll(): Promise<void>;
+    list(): SpawnHandle[];
+    get(id: string): SpawnHandle | undefined;
+    get size(): number;
+    /** Persist spawn state to disk for recovery. */
+    private persistState;
+    /** Load persisted state (for display/diagnostics only — processes can't be recovered). */
+    loadPersistedState(): Promise<PersistedSpawn[]>;
+}
+export {};
+//# sourceMappingURL=manager.d.ts.map

package/packages/openclaw/dist/spawn/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/spawn/manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI3E,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAQ7C,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAeD;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,YAAY,CAAS;gBAEjB,OAAO,CAAC,EAAE;QACpB,IAAI,CAAC,EAAE,SAAS,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAkBK,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA8BlD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa7C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,IAAI,WAAW,EAAE;IAIrB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gDAAgD;YAClC,YAAY;IAqB1B,0FAA0F;IACpF,kBAAkB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;CAUtD"}