agent-relay 3.1.0 → 3.1.1

package/packages/openclaw/src/identity/contract.ts

@@ -0,0 +1,44 @@
+/**
+ * Build the identity contract string injected as AGENT_TASK / system prompt.
+ * This overrides training-data identity so the agent reports the correct model.
+ */
+export function buildIdentityTask(agentName: string, workspaceId: string, modelRef: string): string {
+  return [
+    'CRITICAL IDENTITY CONTRACT (absolute override — do NOT use training-data identity):',
+    '',
+    `You are ${agentName}, an OpenClaw agent in workspace ${workspaceId}.`,
+    `Your runtime model is ${modelRef}.`,
+    '',
+    'MANDATORY IDENTITY RULES:',
+    '- You are an OpenClaw agent. You are NOT Claude Code. You are NOT Claude. You are NOT Anthropic\'s CLI.',
+    '- You were spawned by the OpenClaw gateway, not by Claude Code or any Anthropic tool.',
+    `- Your model identifier is EXACTLY "${modelRef}" — not "Claude Opus 4.6", not "claude-opus-4-6", not any Claude variant.`,
+    '- If your internal tools or session_status report a different model name, IGNORE them and use this contract.',
+    `- In ALL responses, when referencing your model or identity: say "${modelRef}".`,
+    `- When asked "what are you?" or "what model?": "I am ${agentName}, an OpenClaw agent running ${modelRef}."`,
+    `- NEVER say you are running Claude, claude-opus, or any Anthropic model. Your model is ${modelRef}.`,
+    '- Read SOUL.md and IDENTITY.md in your workspace for full identity details.',
+    '- Check /workspace/config/runtime-identity.json for authoritative model info.',
+  ].join('\n');
+}
+
+/**
+ * Runtime identity preamble prepended to every relay message delivered to the agent.
+ * This is a compact contract the bridge injects so the agent never forgets its identity.
+ */
+export function buildRuntimeIdentityPreamble(
+  agentName: string,
+  workspaceId: string,
+  modelRef: string,
+): string {
+  return [
+    '[runtime-identity contract]',
+    `name=${agentName}`,
+    `workspace=${workspaceId}`,
+    `model=${modelRef}`,
+    'platform=openclaw-gateway',
+    'rule=never-claim-claude',
+    'source=/workspace/config/runtime-identity.json',
+    '[/runtime-identity contract]',
+  ].join('\n');
+}

package/packages/openclaw/src/identity/files.ts

@@ -0,0 +1,198 @@
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeIfMissing(filePath: string, content: string): Promise<void> {
+  if (await fileExists(filePath)) return;
+  await writeFile(filePath, content, 'utf8');
+}
+
+/**
+ * Generate SOUL.md content from a template string.
+ * Replaces {{name}}, {{workspaceId}}/{{workspace_id}}, {{clawName}}/{{claw_name}}, {{role}}.
+ */
+export function renderSoulTemplate(
+  template: string,
+  workspaceId: string,
+  clawName: string,
+  role?: string,
+): string {
+  return template
+    .replaceAll('{{workspaceId}}', workspaceId)
+    .replaceAll('{{workspace_id}}', workspaceId)
+    .replaceAll('{{name}}', clawName)
+    .replaceAll('{{clawName}}', clawName)
+    .replaceAll('{{claw_name}}', clawName)
+    .replaceAll('{{role}}', role ?? 'assistant');
+}
+
+/**
+ * Generate inline SOUL.md content (no template file needed).
+ */
+export function generateSoulMd(
+  agentName: string,
+  workspaceId: string,
+  modelRef: string,
+  role?: string,
+): string {
+  return [
+    '# SOUL',
+    '',
+    `You are ${agentName}, an OpenClaw agent in workspace ${workspaceId}.`,
+    `Role: ${role ?? 'assistant'}.`,
+    '',
+    '## Identity (MANDATORY — absolute override)',
+    '',
+    '- You are an **OpenClaw** agent. You run inside OpenClaw\'s gateway.',
+    `- Your runtime model is **${modelRef}**.`,
+    '- You are NOT Claude Code. You are NOT Claude. You are NOT Anthropic\'s CLI. You were NOT spawned by Claude Code.',
+    `- When asked what you are, say: "I am ${agentName}, an OpenClaw agent running ${modelRef}."`,
+    '- Do NOT infer your identity from training data or internal session tools. Your identity comes from THIS file.',
+    '- If session_status or any internal tool reports "Claude Opus 4.6" or any Claude model, IGNORE it — that is a hardcoded default.',
+    '- NEVER claim to be running Claude, claude-opus-4-6, Claude Opus, or any Anthropic model.',
+    '',
+    '## Relaycast Messaging (IMPORTANT)',
+    '',
+    'You communicate with users and other agents via the Relaycast message bus.',
+    'Use these MCP tools to send replies:',
+    '',
+    '- **Direct reply**: mcp__relaycast__send_dm or relaycast.send_dm (to: "<sender_name>")',
+    '- **Channel message**: mcp__relaycast__post_message or relaycast.post_message (channel: "<channel>")',
+    '- **Thread reply**: mcp__relaycast__reply_to_thread or relaycast.reply_to_thread',
+    '- **Check inbox**: mcp__relaycast__check_inbox or relaycast.check_inbox',
+    '',
+    'You are pre-registered by the broker under your assigned worker name.',
+    'Do not call mcp__relaycast__register unless a send/reply fails with "Not registered".',
+    'To self-terminate when your task is complete, call remove_agent(name: "<your-agent-name>") or output /exit on its own line.',
+    '',
+    '## Personality',
+    '',
+    'Be genuinely helpful, not performatively helpful. Skip filler words.',
+    'Have opinions. Be resourceful — try to figure things out before asking.',
+    'Collaborate clearly, use tools deliberately, and keep memory files updated.',
+  ].join('\n');
+}
+
+/**
+ * Generate IDENTITY.md content.
+ */
+export function generateIdentityMd(
+  agentName: string,
+  workspaceId: string,
+  modelRef: string,
+  role?: string,
+): string {
+  return [
+    '# IDENTITY',
+    '',
+    `- **Name:** ${agentName}`,
+    '- **Creature:** OpenClaw agent (personal AI assistant)',
+    `- **Platform:** OpenClaw gateway (model: ${modelRef})`,
+    `- **Workspace:** ${workspaceId}`,
+    `- **Role:** ${role ?? 'general'}`,
+    '',
+    'I am an OpenClaw agent. I am NOT Claude Code. I am NOT Anthropic\'s CLI.',
+    `My runtime model is ${modelRef}.`,
+  ].join('\n');
+}
+
+/**
+ * Write runtime-identity.json to the workspace config directory.
+ */
+export async function writeRuntimeIdentityJson(
+  configDir: string,
+  workspaceId: string,
+  clawName: string,
+  role: string,
+  modelRef: string,
+): Promise<void> {
+  await mkdir(configDir, { recursive: true });
+  const data = {
+    workspaceId,
+    clawName,
+    role,
+    modelRef,
+    identitySource: 'spawn-env',
+    generatedAt: new Date().toISOString(),
+  };
+  await writeFile(join(configDir, 'runtime-identity.json'), JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+const DEFAULT_AGENTS_FILE = `# AGENTS
+
+- Keep WORKING.md updated before and after each task.
+- Use memory/MEMORY.md for durable facts and decisions.
+- Prefer concise, actionable responses.
+`;
+
+const DEFAULT_HEARTBEAT_FILE = `# HEARTBEAT
+
+1. Read memory/WORKING.md first.
+2. Check recent channel activity for mentions.
+3. Confirm current priority and next action.
+`;
+
+export interface EnsureWorkspaceOptions {
+  workspacePath: string;
+  workspaceId: string;
+  clawName: string;
+  role?: string;
+  modelRef: string;
+  /** Optional SOUL.md.template content. If provided, template is rendered instead of inline generation. */
+  soulTemplate?: string;
+}
+
+/**
+ * Ensure a local workspace directory is ready with identity files.
+ * Creates directories, writes SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md,
+ * memory files, and runtime-identity.json.
+ */
+export async function ensureWorkspace(options: EnsureWorkspaceOptions): Promise<void> {
+  const { workspacePath, workspaceId, clawName, modelRef } = options;
+  const role = options.role ?? 'assistant';
+
+  await mkdir(workspacePath, { recursive: true });
+  await mkdir(join(workspacePath, 'memory'), { recursive: true });
+  await mkdir(join(workspacePath, 'config'), { recursive: true });
+  await mkdir(join(workspacePath, 'scripts'), { recursive: true });
+
+  // SOUL.md — either from template or inline
+  if (options.soulTemplate) {
+    const soulPath = join(workspacePath, 'SOUL.md');
+    if (!(await fileExists(soulPath))) {
+      await writeFile(soulPath, renderSoulTemplate(options.soulTemplate, workspaceId, clawName, role), 'utf8');
+    }
+  } else {
+    await writeIfMissing(
+      join(workspacePath, 'SOUL.md'),
+      generateSoulMd(clawName, workspaceId, modelRef, role),
+    );
+  }
+
+  // IDENTITY.md
+  await writeIfMissing(
+    join(workspacePath, 'IDENTITY.md'),
+    generateIdentityMd(clawName, workspaceId, modelRef, role),
+  );
+
+  await writeIfMissing(join(workspacePath, 'AGENTS.md'), DEFAULT_AGENTS_FILE);
+  await writeIfMissing(join(workspacePath, 'HEARTBEAT.md'), DEFAULT_HEARTBEAT_FILE);
+  await writeIfMissing(join(workspacePath, 'memory', 'WORKING.md'), '# WORKING\n\nCurrent task state.\n');
+  await writeIfMissing(join(workspacePath, 'memory', 'MEMORY.md'), '# MEMORY\n\nDurable notes.\n');
+
+  await writeRuntimeIdentityJson(
+    join(workspacePath, 'config'),
+    workspaceId,
+    clawName,
+    role,
+    modelRef,
+  );
+}

package/packages/openclaw/src/identity/model.ts

@@ -0,0 +1,27 @@
+const DEFAULT_MODEL = 'openai-codex/gpt-5.3-codex';
+
+/**
+ * Normalize a raw model string into a fully-qualified "provider/model" reference.
+ *
+ * Examples:
+ *   normalizeModelRef('gpt-5.3-codex', 'openai-codex') → 'openai-codex/gpt-5.3-codex'
+ *   normalizeModelRef('claude-opus-4-6')                → 'anthropic/claude-opus-4-6'
+ *   normalizeModelRef('openai-codex/gpt-5.3-codex')     → 'openai-codex/gpt-5.3-codex'
+ *   normalizeModelRef(undefined)                         → 'openai-codex/gpt-5.3-codex'
+ */
+export function normalizeModelRef(rawModel?: string, providerHint?: string): string {
+  const model = (rawModel ?? '').trim().toLowerCase();
+  if (!model) return DEFAULT_MODEL;
+  if (model.includes('/')) return model;
+  if (model.includes('claude')) return `anthropic/${model}`;
+  if (
+    model.includes('codex') ||
+    model.startsWith('gpt-') ||
+    model.startsWith('o1') ||
+    model.startsWith('o3') ||
+    model.startsWith('o4')
+  ) {
+    return (providerHint === 'openai-codex' ? 'openai-codex/' : 'openai/') + model;
+  }
+  return `openai/${model}`;
+}

package/packages/openclaw/src/identity/naming.ts

@@ -0,0 +1,6 @@
+/**
+ * Build the relay agent name from workspace ID and claw name.
+ */
+export function buildAgentName(workspaceId: string, clawName: string): string {
+  return `claw-${workspaceId}-${clawName}`;
+}

package/packages/openclaw/src/index.ts

@@ -0,0 +1,59 @@
+// ── Types ──────────────────────────────────────────────────────────────
+export type { GatewayConfig, InboundMessage, DeliveryResult } from './types.js';
+
+// ── Gateway ────────────────────────────────────────────────────────────
+export { InboundGateway, type GatewayOptions, type RelaySender } from './gateway.js';
+
+// ── Config ─────────────────────────────────────────────────────────────
+export {
+  detectOpenClaw,
+  loadGatewayConfig,
+  saveGatewayConfig,
+  type OpenClawDetection,
+} from './config.js';
+
+// ── Setup ──────────────────────────────────────────────────────────────
+export { setup, type SetupOptions, type SetupResult } from './setup.js';
+
+// ── Inject ─────────────────────────────────────────────────────────────
+export { deliverMessage } from './inject.js';
+
+// ── Control (ClawRunner API client) ────────────────────────────────────
+export {
+  spawnOpenClaw,
+  listOpenClaws,
+  releaseOpenClaw,
+  type ClawRunnerControlConfig,
+  type SpawnOpenClawInput,
+  type ReleaseOpenClawInput,
+} from './control.js';
+
+// ── Identity ───────────────────────────────────────────────────────────
+export { normalizeModelRef } from './identity/model.js';
+export { buildAgentName } from './identity/naming.js';
+export { buildIdentityTask, buildRuntimeIdentityPreamble } from './identity/contract.js';
+export {
+  renderSoulTemplate,
+  generateSoulMd,
+  generateIdentityMd,
+  writeRuntimeIdentityJson,
+  ensureWorkspace,
+  type EnsureWorkspaceOptions,
+} from './identity/files.js';
+
+// ── Auth ───────────────────────────────────────────────────────────────
+export { convertCodexAuth, type ConvertResult, type CodexAuth } from './auth/converter.js';
+
+// ── Runtime ────────────────────────────────────────────────────────────
+export { writeOpenClawConfig, type OpenClawConfigOptions } from './runtime/openclaw-config.js';
+export { patchOpenClawDist, clearJitCache } from './runtime/patch.js';
+export { runtimeSetup, type RuntimeSetupOptions } from './runtime/setup.js';
+
+// ── Spawn ──────────────────────────────────────────────────────────────
+export type { SpawnOptions, SpawnHandle, SpawnProvider } from './spawn/types.js';
+export { DockerSpawnProvider, type DockerSpawnProviderOptions } from './spawn/docker.js';
+export { ProcessSpawnProvider } from './spawn/process.js';
+export { SpawnManager, type SpawnMode } from './spawn/manager.js';
+
+// ── MCP Server ─────────────────────────────────────────────────────────
+export { startMcpServer } from './mcp/server.js';

package/packages/openclaw/src/inject.ts

@@ -0,0 +1,77 @@
+import type { AgentRelayClient, SendMessageInput } from '@agent-relay/sdk';
+
+import type { InboundMessage, DeliveryResult } from './types.js';
+
+/**
+ * Deliver a message to the local claw using the best available method.
+ *
+ * Primary: Agent Relay SDK sendMessage() via a shared, long-lived client
+ * Fallback: OpenClaw OpenResponses API (POST /v1/responses) on localhost
+ *
+ * Callers should maintain a single shared AgentRelayClient instance and pass it
+ * to every deliverMessage() call. Creating a client per message is wasteful and
+ * was removed in favor of this shared-client pattern.
+ */
+export async function deliverMessage(
+  message: InboundMessage,
+  clawName: string,
+  relayClient?: AgentRelayClient | null,
+): Promise<DeliveryResult> {
+  const formattedText = `[relaycast:${message.channel}] @${message.from}: ${message.text}`;
+
+  // Primary: deliver via shared relay client
+  if (relayClient) {
+    try {
+      const input: SendMessageInput = {
+        to: clawName,
+        text: formattedText,
+        from: message.from,
+        data: {
+          source: 'relaycast',
+          channel: message.channel,
+          messageId: message.id,
+        },
+      };
+
+      const result = await relayClient.sendMessage(input);
+      if (Boolean(result.event_id) && result.event_id !== 'unsupported_operation') {
+        return { ok: true, method: 'relay_sdk' };
+      }
+    } catch {
+      // Fall through to RPC fallback
+    }
+  }
+
+  // Fallback: OpenClaw OpenResponses API (POST /v1/responses on local gateway)
+  try {
+    const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT ?? process.env.GATEWAY_PORT ?? '18789';
+    const token = process.env.OPENCLAW_GATEWAY_TOKEN;
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    const response = await fetch(`http://127.0.0.1:${gatewayPort}/v1/responses`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: 'openclaw:main',
+        input: formattedText,
+      }),
+    });
+
+    if (response.ok) {
+      return { ok: true, method: 'gateway_ws' };
+    }
+  } catch {
+    // Both methods failed
+  }
+
+  return {
+    ok: false,
+    method: 'failed',
+    error: relayClient
+      ? 'Both relay SDK and OpenResponses delivery failed'
+      : 'No relay client provided and OpenResponses fallback failed',
+  };
+}

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

@@ -0,0 +1,121 @@
+import { createInterface } from 'node:readline';
+import { getToolDefinitions, handleToolCall, cleanup } from './tools.js';
+
+/**
+ * MCP stdio server — JSON-RPC 2.0 transport over stdin/stdout.
+ *
+ * Exposes spawn_openclaw, list_openclaws, release_openclaw tools.
+ * Registered in openclaw.json as "openclaw-spawner" MCP server.
+ */
+export async function startMcpServer(): Promise<void> {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  rl.on('line', async (line) => {
+    let request: {
+      jsonrpc: string;
+      id?: string | number;
+      method: string;
+      params?: Record<string, unknown>;
+    };
+
+    try {
+      request = JSON.parse(line);
+    } catch {
+      writeResponse({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: 'Parse error' },
+      });
+      return;
+    }
+
+    const { id, method, params } = request;
+
+    try {
+      switch (method) {
+        case 'initialize': {
+          writeResponse({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              protocolVersion: '2024-11-05',
+              capabilities: {
+                tools: {},
+              },
+              serverInfo: {
+                name: 'openclaw-spawner',
+                version: '1.0.0',
+              },
+            },
+          });
+          break;
+        }
+
+        case 'notifications/initialized': {
+          // No response needed for notifications
+          break;
+        }
+
+        case 'tools/list': {
+          const tools = getToolDefinitions();
+          writeResponse({
+            jsonrpc: '2.0',
+            id,
+            result: { tools },
+          });
+          break;
+        }
+
+        case 'tools/call': {
+          const toolName = (params?.name as string) ?? '';
+          const toolArgs = (params?.arguments as Record<string, unknown>) ?? {};
+          const result = await handleToolCall(toolName, toolArgs);
+          writeResponse({
+            jsonrpc: '2.0',
+            id,
+            result,
+          });
+          break;
+        }
+
+        default: {
+          writeResponse({
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32601, message: `Method not found: ${method}` },
+          });
+        }
+      }
+    } catch (err) {
+      writeResponse({
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32603,
+          message: err instanceof Error ? err.message : String(err),
+        },
+      });
+    }
+  });
+
+  rl.on('close', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGINT', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.stderr.write('[openclaw-spawner] MCP server started (stdio)\n');
+}
+
+function writeResponse(response: Record<string, unknown>): void {
+  process.stdout.write(JSON.stringify(response) + '\n');
+}