agent-relay 3.1.0 → 3.1.1

package/packages/openclaw/src/mcp/tools.ts

@@ -0,0 +1,174 @@
+import { InboundGateway } from '../gateway.js';
+
+/** Control API base URL — the gateway's spawn control server. */
+const CONTROL_URL = `http://127.0.0.1:${
+  Number(process.env.RELAYCAST_CONTROL_PORT) || InboundGateway.DEFAULT_CONTROL_PORT
+}`;
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export function getToolDefinitions(): McpToolDefinition[] {
+  return [
+    {
+      name: 'spawn_openclaw',
+      description:
+        'Spawn a new independent OpenClaw instance. The spawned instance gets its own gateway, ' +
+        'relay broker, and Relaycast messaging. It runs as an independent peer, not a child.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'Name for the new OpenClaw instance (e.g. "researcher", "coder").',
+          },
+          role: {
+            type: 'string',
+            description: 'Role description for the agent (e.g. "code review specialist").',
+          },
+          model: {
+            type: 'string',
+            description: 'Model reference (e.g. "openai-codex/gpt-5.3-codex"). Defaults to parent model.',
+          },
+          channels: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Relaycast channels to join (default: ["#general"]).',
+          },
+          system_prompt: {
+            type: 'string',
+            description: 'System prompt / task description for the spawned agent.',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'list_openclaws',
+      description: 'List all currently running OpenClaw instances spawned by this agent.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+    {
+      name: 'release_openclaw',
+      description: 'Stop and release a spawned OpenClaw instance by name or ID.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'Name of the OpenClaw to release (as provided during spawn).',
+          },
+          id: {
+            type: 'string',
+            description: 'ID of the OpenClaw to release (from list_openclaws).',
+          },
+        },
+      },
+    },
+  ];
+}
+
+export async function handleToolCall(
+  toolName: string,
+  args: Record<string, unknown>,
+): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  switch (toolName) {
+    case 'spawn_openclaw': {
+      const name = args.name as string;
+      if (!name) {
+        return text('Error: "name" is required.');
+      }
+
+      try {
+        const res = await fetch(`${CONTROL_URL}/spawn`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(args),
+        });
+        const body = await res.json() as Record<string, unknown>;
+        if (!body.ok) {
+          return text(`Failed to spawn "${name}": ${body.error ?? 'unknown error'}`);
+        }
+        return text(
+          `Spawned OpenClaw "${name}"\n` +
+          `  Agent name: ${body.agentName}\n` +
+          `  ID: ${body.id}\n` +
+          `  Gateway port: ${body.gatewayPort}\n` +
+          `  Total active: ${body.active}`,
+        );
+      } catch (err) {
+        return text(
+          `Failed to spawn "${name}": ${err instanceof Error ? err.message : String(err)}\n` +
+          'Is the gateway running? Start it with: relay-openclaw gateway',
+        );
+      }
+    }
+
+    case 'list_openclaws': {
+      try {
+        const res = await fetch(`${CONTROL_URL}/list`);
+        const body = await res.json() as Record<string, unknown>;
+        const claws = body.claws as Array<Record<string, unknown>>;
+        if (!claws || claws.length === 0) {
+          return text('No spawned OpenClaws currently running.');
+        }
+        const lines = claws.map(
+          (h) => `- ${h.name} → ${h.agentName} (id: ${h.id}, port: ${h.gatewayPort})`,
+        );
+        return text(`Active OpenClaws (${claws.length}):\n${lines.join('\n')}`);
+      } catch (err) {
+        return text(
+          `Failed to list claws: ${err instanceof Error ? err.message : String(err)}\n` +
+          'Is the gateway running? Start it with: relay-openclaw gateway',
+        );
+      }
+    }
+
+    case 'release_openclaw': {
+      const name = args.name as string | undefined;
+      const id = args.id as string | undefined;
+
+      if (!name && !id) {
+        return text('Error: provide either "name" or "id" to release.');
+      }
+
+      try {
+        const res = await fetch(`${CONTROL_URL}/release`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, id }),
+        });
+        const body = await res.json() as Record<string, unknown>;
+        if (body.ok) {
+          return text(`Released OpenClaw "${name ?? id}". Active: ${body.active}`);
+        }
+        return text(`OpenClaw "${name ?? id}" not found among active spawns.`);
+      } catch (err) {
+        return text(
+          `Failed to release: ${err instanceof Error ? err.message : String(err)}\n` +
+          'Is the gateway running? Start it with: relay-openclaw gateway',
+        );
+      }
+    }
+
+    default:
+      return text(`Unknown tool: ${toolName}`);
+  }
+}
+
+function text(message: string) {
+  return { content: [{ type: 'text' as const, text: message }] };
+}
+
+/**
+ * Cleanup: no-op since spawns are managed by the gateway process.
+ */
+export async function cleanup(): Promise<void> {
+  // Spawns live in the gateway — nothing to clean up here.
+}

package/packages/openclaw/src/runtime/openclaw-config.ts

@@ -0,0 +1,64 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface OpenClawConfigOptions {
+  /** Fully-qualified model ref, e.g. "openai-codex/gpt-5.3-codex". */
+  modelRef: string;
+  /** Path to ~/.openclaw/ (default: $HOME/.openclaw). */
+  openclawHome?: string;
+  /** Default workspace path (default: ~/.openclaw/workspace). */
+  workspacePath?: string;
+  /** MCP servers to include. Keys are server names, values are MCP server configs. */
+  mcpServers?: Record<string, { command: string; args: string[]; env?: Record<string, string> }>;
+}
+
+/**
+ * Write (or update) ~/.openclaw/openclaw.json with model, workspace, skipBootstrap,
+ * and MCP server configuration.
+ */
+export async function writeOpenClawConfig(options: OpenClawConfigOptions): Promise<void> {
+  const home = options.openclawHome ?? join(process.env.HOME ?? '/home/node', '.openclaw');
+  await mkdir(home, { recursive: true });
+
+  const configPath = join(home, 'openclaw.json');
+  let config: Record<string, unknown> = {};
+
+  try {
+    const raw = await readFile(configPath, 'utf8');
+    config = JSON.parse(raw);
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+    config = {};
+  }
+  if (!config || typeof config !== 'object') config = {};
+
+  // agents.defaults
+  if (!config.agents || typeof config.agents !== 'object') config.agents = {};
+  const agents = config.agents as Record<string, unknown>;
+  if (!agents.defaults || typeof agents.defaults !== 'object') agents.defaults = {};
+  const defaults = agents.defaults as Record<string, unknown>;
+
+  if (!defaults.workspace || typeof defaults.workspace !== 'string') {
+    defaults.workspace = options.workspacePath ?? '~/.openclaw/workspace';
+  }
+
+  // Model shape: { primary: "provider/model" }
+  if (typeof defaults.model === 'string') {
+    defaults.model = { primary: defaults.model };
+  } else if (!defaults.model || typeof defaults.model !== 'object') {
+    defaults.model = {};
+  }
+  (defaults.model as Record<string, string>).primary = options.modelRef;
+
+  defaults.skipBootstrap = true;
+
+  // MCP servers
+  if (options.mcpServers) {
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      config.mcpServers = {};
+    }
+    Object.assign(config.mcpServers as Record<string, unknown>, options.mcpServers);
+  }
+
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}

package/packages/openclaw/src/runtime/patch.ts

@@ -0,0 +1,103 @@
+import { readdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Patch OpenClaw's compiled dist JS files to replace hardcoded identity constants.
+ *
+ * FRAGILE: This is a best-effort operation. OpenClaw bakes Claude defaults into
+ * its compiled output. These patterns may change between OpenClaw versions.
+ * Prefer runtime identity enforcement (SOUL.md, runtime-identity.json, identity
+ * preamble in bridge) over relying on this patch.
+ *
+ * Known hardcoded constants (as of OpenClaw ~0.x):
+ *   - DEFAULT_MODEL = "claude-opus-4-6"
+ *   - KILOCODE_DEFAULT_MODEL_ID = "anthropic/claude-opus-4.6"
+ *   - KILOCODE_DEFAULT_MODEL_NAME = "Claude Opus 4.6"
+ *   - "Claude Code" branding
+ *
+ * @param distDir - Path to OpenClaw's dist directory (e.g. /usr/lib/node_modules/openclaw/dist)
+ * @param modelRef - Full model reference (e.g. "openai-codex/gpt-5.3-codex")
+ * @returns Number of files patched, or 0 if dist not found or patching skipped
+ */
+export async function patchOpenClawDist(distDir: string, modelRef: string): Promise<number> {
+  if (!existsSync(distDir)) {
+    process.stderr.write(`[patch] OpenClaw dist not found at ${distDir}, skipping\n`);
+    return 0;
+  }
+
+  // Extract bare model ID (e.g. "gpt-5.3-codex" from "openai-codex/gpt-5.3-codex")
+  const modelId = modelRef.includes('/') ? modelRef.split('/').pop()! : modelRef;
+
+  // Order matters: replace fully-qualified patterns before bare model IDs,
+  // otherwise the bare pattern destroys the substring the qualified pattern needs.
+  const replacements: [RegExp, string][] = [
+    [/anthropic\/claude-opus-4\.6/g, modelRef],
+    [/Claude Opus 4\.6/g, modelRef],
+    [/claude-opus-4\.6/g, modelId],
+    [/claude-opus-4-6/g, modelId],
+    [/Claude Code/g, 'OpenClaw Agent'],
+  ];
+
+  let patchedCount = 0;
+
+  try {
+    async function walkAndPatch(dir: string): Promise<void> {
+      const entries = await readdir(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walkAndPatch(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith('.js')) {
+          try {
+            let content = await readFile(fullPath, 'utf8');
+            let modified = false;
+
+            for (const [pattern, replacement] of replacements) {
+              const newContent = content.replace(pattern, replacement);
+              if (newContent !== content) {
+                content = newContent;
+                modified = true;
+              }
+            }
+
+            if (modified) {
+              await writeFile(fullPath, content, 'utf8');
+              patchedCount++;
+            }
+          } catch (err) {
+            // Individual file patch failure is non-fatal
+            process.stderr.write(
+              `[patch] Warning: could not patch ${fullPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+            );
+          }
+        }
+      }
+    }
+
+    await walkAndPatch(distDir);
+  } catch (err) {
+    // Entire patching failure is non-fatal — runtime identity enforcement is the primary defense
+    process.stderr.write(
+      `[patch] Warning: dist patching failed (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+
+  if (patchedCount > 0) {
+    process.stderr.write(`[patch] Patched ${patchedCount} file(s) in ${distDir}\n`);
+  }
+
+  return patchedCount;
+}
+
+/**
+ * Clear JIT cache (/tmp/jiti/) which may contain unpatched constants.
+ */
+export async function clearJitCache(): Promise<void> {
+  try {
+    await rm('/tmp/jiti', { recursive: true, force: true });
+  } catch {
+    // Ignore — cache may not exist
+  }
+}

package/packages/openclaw/src/runtime/setup.ts

@@ -0,0 +1,89 @@
+import { join } from 'node:path';
+import { unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import { normalizeModelRef } from '../identity/model.js';
+import { convertCodexAuth } from '../auth/converter.js';
+import { writeOpenClawConfig } from './openclaw-config.js';
+import { patchOpenClawDist, clearJitCache } from './patch.js';
+import {
+  generateSoulMd,
+  generateIdentityMd,
+  ensureWorkspace,
+} from '../identity/files.js';
+
+export interface RuntimeSetupOptions {
+  /** Raw model string (e.g. "gpt-5.3-codex"). Defaults to env OPENCLAW_MODEL. */
+  model?: string;
+  /** Agent name. Defaults to env OPENCLAW_NAME or AGENT_NAME. */
+  name?: string;
+  /** Workspace ID. Defaults to env OPENCLAW_WORKSPACE_ID. */
+  workspaceId?: string;
+  /** Agent role. Defaults to env OPENCLAW_ROLE. */
+  role?: string;
+  /** OpenClaw dist directory for patching. Defaults to /usr/lib/node_modules/openclaw/dist. */
+  openclawDistDir?: string;
+  /** Home directory. Defaults to $HOME. */
+  homeDir?: string;
+}
+
+/**
+ * Full runtime setup: auth conversion, config writing, identity files, dist patching, JIT cache clear.
+ *
+ * This replaces the inline node -e block + shell logic in start-claw.sh.
+ * Call this before starting the OpenClaw gateway.
+ */
+export async function runtimeSetup(options: RuntimeSetupOptions = {}): Promise<{
+  modelRef: string;
+  agentName: string;
+  workspaceId: string;
+}> {
+  const home = options.homeDir ?? process.env.HOME ?? '/home/node';
+  const model = options.model ?? process.env.OPENCLAW_MODEL ?? 'openai-codex/gpt-5.3-codex';
+  const name = options.name ?? process.env.OPENCLAW_NAME ?? process.env.AGENT_NAME ?? 'agent';
+  const workspaceId = options.workspaceId ?? process.env.OPENCLAW_WORKSPACE_ID ?? 'unknown';
+  const role = options.role ?? process.env.OPENCLAW_ROLE ?? 'general';
+  // Resolve OpenClaw dist dir: try explicit, then known install locations
+  const distDirCandidates = options.openclawDistDir
+    ? [options.openclawDistDir]
+    : [
+        '/usr/lib/node_modules/openclaw/dist',    // Global npm (ClawRunner sandbox)
+        '/app/dist',                                // Vanilla Docker image
+        '/usr/local/lib/node_modules/openclaw/dist', // Global npm (macOS/other)
+      ];
+  const distDir = distDirCandidates.find((d) => existsSync(d)) ?? distDirCandidates[0];
+
+  // 1. Convert codex auth
+  const { preferredProvider } = await convertCodexAuth();
+  const modelRef = normalizeModelRef(model, preferredProvider);
+
+  // 2. Write openclaw.json config
+  await writeOpenClawConfig({
+    modelRef,
+    openclawHome: join(home, '.openclaw'),
+  });
+
+  // 3. Write identity files in workspace
+  const wsDir = join(home, '.openclaw', 'workspace');
+  await ensureWorkspace({
+    workspacePath: wsDir,
+    workspaceId,
+    clawName: name,
+    role,
+    modelRef,
+  });
+
+  // Remove BOOTSTRAP.md if present (agent is pre-configured)
+  const bootstrapPath = join(wsDir, 'BOOTSTRAP.md');
+  if (existsSync(bootstrapPath)) {
+    await unlink(bootstrapPath);
+  }
+
+  // 4. Patch OpenClaw dist
+  await patchOpenClawDist(distDir, modelRef);
+
+  // 5. Clear JIT cache
+  await clearJitCache();
+
+  return { modelRef, agentName: name, workspaceId };
+}