agent-relay-orchestrator 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -0,0 +1,90 @@
+import { readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { OrchestratorConfig } from "./config";
+
+interface DirectoryEntry {
+  name: string;
+  path: string;
+}
+
+interface DirectoryListing {
+  path: string;
+  parent?: string;
+  baseDir: string;
+  entries: DirectoryEntry[];
+}
+
+function listDirectories(requestedPath: string | undefined, baseDir: string): DirectoryListing {
+  const target = resolve(requestedPath || baseDir);
+
+  if (!target.startsWith(baseDir) && target !== baseDir) {
+    throw new Error(`Path must be within baseDir: ${baseDir}`);
+  }
+
+  let stat;
+  try { stat = statSync(target); } catch { throw new Error(`Path does not exist: ${target}`); }
+  if (!stat.isDirectory()) throw new Error(`Not a directory: ${target}`);
+
+  const entries = readdirSync(target, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => ({ name: e.name, path: join(target, e.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const parent = dirname(target);
+  return {
+    path: target,
+    parent: parent.startsWith(baseDir) && parent !== target ? parent : undefined,
+    baseDir,
+    entries,
+  };
+}
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+  });
+}
+
+function error(message: string, status = 400): Response {
+  return json({ error: message }, status);
+}
+
+export function startApiServer(config: OrchestratorConfig): { stop(): void; url: string } {
+  const server = Bun.serve({
+    port: config.apiPort,
+    hostname: "0.0.0.0",
+    fetch(req) {
+      const url = new URL(req.url);
+
+      if (req.method === "OPTIONS") {
+        return new Response(null, {
+          headers: {
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, X-Agent-Relay-Token",
+          },
+        });
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/directories") {
+        try {
+          const listing = listDirectories(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(listing);
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/health") {
+        return json({ ok: true, id: config.id, hostname: config.hostname });
+      }
+
+      return error("Not found", 404);
+    },
+  });
+
+  const url = `http://${config.hostname}:${config.apiPort}`;
+  console.error(`[orchestrator] API server listening on :${config.apiPort}`);
+  return { stop: () => server.stop(), url };
+}

package/src/config.ts

@@ -12,6 +12,7 @@ export interface OrchestratorConfig {
   env: Record<string, string>;
   heartbeatIntervalMs: number;
   tmuxPrefix: string;
+  apiPort: number;
 }
 
 const DEFAULT_CONFIG_PATH = join(homedir(), ".agent-relay", "orchestrator.json");
@@ -26,6 +27,7 @@ interface RawConfig {
   env?: Record<string, string>;
   heartbeatIntervalMs?: number;
   tmuxPrefix?: string;
+  apiPort?: number;
 }
 
 export function loadConfig(path?: string): OrchestratorConfig {
@@ -45,8 +47,9 @@ export function loadConfig(path?: string): OrchestratorConfig {
   const env = raw.env || {};
   const heartbeatIntervalMs = raw.heartbeatIntervalMs || 30_000;
   const tmuxPrefix = raw.tmuxPrefix || "ar";
+  const apiPort = raw.apiPort || Number(process.env.AGENT_RELAY_ORCHESTRATOR_API_PORT) || 4860;
 
-  return { id, hostname, relayUrl, token, providers, baseDir, env, heartbeatIntervalMs, tmuxPrefix };
+  return { id, hostname, relayUrl, token, providers, baseDir, env, heartbeatIntervalMs, tmuxPrefix, apiPort };
 }
 
 export function initConfigFile(config: Partial<RawConfig>): string {
@@ -58,6 +61,7 @@ export function initConfigFile(config: Partial<RawConfig>): string {
     relayUrl: "http://localhost:4850",
     providers: ["claude", "codex"],
     baseDir: join(homedir(), "projects"),
+    apiPort: 4860,
     env: {},
   };
   const merged = { ...defaults, ...config };

package/src/control.ts

@@ -1,9 +1,9 @@
 import type { OrchestratorConfig } from "./config";
-import type { ControlMessage, ManagedAgentReport, RelayAgentSummary, RelayClient } from "./relay";
-import { hasSession, killSession, spawnAgent, type SpawnOptions } from "./tmux";
+import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
+import { spawnAgent, type SpawnOptions } from "./tmux";
 
-export interface ControlHandler {
-  handle(message: ControlMessage): Promise<boolean>;
+interface ControlHandler {
+  handleCommand(command: RelayCommand): Promise<boolean>;
   getManagedAgents(): ManagedAgentReport[];
   setManagedAgents(agents: ManagedAgentReport[]): void;
 }
@@ -14,30 +14,6 @@ export function createControlHandler(
 ): ControlHandler {
   let managedAgents: ManagedAgentReport[] = [];
 
-  async function handle(message: ControlMessage): Promise<boolean> {
-    const ctrl = message.payload?.orchestratorControl;
-    if (!ctrl) return false;
-
-    let handled = false;
-    switch (ctrl.action) {
-      case "spawn":
-        handled = await handleSpawn(ctrl);
-        break;
-      case "restart":
-        handled = await handleRestart(ctrl);
-        break;
-      case "shutdown":
-        handled = await handleShutdown(ctrl);
-        break;
-      default:
-        console.error(`[orchestrator] Unknown control action: ${ctrl.action}`);
-        return false;
-    }
-
-    await relay.updateManagedAgents(managedAgents);
-    return handled;
-  }
-
   async function handleSpawn(ctrl: Record<string, any>): Promise<boolean> {
     const opts: SpawnOptions = {
       provider: ctrl.provider || "claude",
@@ -58,108 +34,22 @@ export function createControlHandler(
     }
   }
 
-  async function handleRestart(ctrl: Record<string, any>): Promise<boolean> {
-    const targetId = ctrl.agentId;
-    if (!targetId) {
-      // Restart all managed agents
-      let ok = true;
-      for (const agent of [...managedAgents]) {
-        ok = await restartSingle(agent) && ok;
-      }
-      return ok;
-    }
-
-    const agent = managedAgents.find(
-      (a) => a.agentId === targetId || a.tmuxSession === targetId || a.label === targetId,
-    );
-    if (!agent) {
-      console.error(`[orchestrator] Restart: agent not found: ${targetId}`);
-      return false;
-    }
-    return restartSingle(agent);
-  }
-
-  async function restartSingle(agent: ManagedAgentReport): Promise<boolean> {
-    console.error(`[orchestrator] Restarting: ${agent.tmuxSession}`);
-    await killSession(agent.tmuxSession);
-
-    // Remove from managed list
-    managedAgents = managedAgents.filter((a) => a.tmuxSession !== agent.tmuxSession);
-    await deleteRelayAgentsForManaged(agent);
-
-    // Re-spawn with same options
+  async function handleCommand(command: RelayCommand): Promise<boolean> {
+    await relay.updateCommand(command.id, "accepted");
+    await relay.updateCommand(command.id, "running");
     try {
-      const newAgent = await spawnAgent({
-        provider: agent.provider,
-        cwd: agent.cwd,
-        label: agent.label,
-        approvalMode: agent.approvalMode,
-      }, config);
-      managedAgents.push(newAgent);
-      console.error(`[orchestrator] Restarted: ${newAgent.tmuxSession}`);
+      if (command.type !== "agent.spawn") throw new Error(`unsupported orchestrator command: ${command.type}`);
+      const handled = await handleSpawn(command.params);
+      if (!handled) throw new Error("spawn failed");
+      await relay.updateCommand(command.id, "succeeded", { managedAgents });
+      await relay.updateManagedAgents(managedAgents);
       return true;
-    } catch (err) {
-      console.error(`[orchestrator] Restart spawn failed: ${err}`);
+    } catch (error) {
+      await relay.updateCommand(command.id, "failed", undefined, error instanceof Error ? error.message : String(error));
       return false;
     }
   }
 
-  async function handleShutdown(ctrl: Record<string, any>): Promise<boolean> {
-    const targetId = ctrl.agentId;
-    if (!targetId) {
-      // Shutdown all managed agents
-      let ok = true;
-      for (const agent of [...managedAgents]) {
-        ok = await shutdownSingle(agent) && ok;
-      }
-      return ok;
-    }
-
-    const agent = managedAgents.find(
-      (a) => a.agentId === targetId || a.tmuxSession === targetId || a.label === targetId,
-    );
-    if (!agent) {
-      console.error(`[orchestrator] Shutdown: agent not found: ${targetId}`);
-      return false;
-    }
-    return shutdownSingle(agent);
-  }
-
-  async function shutdownSingle(agent: ManagedAgentReport): Promise<boolean> {
-    console.error(`[orchestrator] Shutting down: ${agent.tmuxSession}`);
-    const alive = await hasSession(agent.tmuxSession);
-    const killed = alive ? await killSession(agent.tmuxSession) : true;
-    if (killed) {
-      managedAgents = managedAgents.filter((a) => a.tmuxSession !== agent.tmuxSession);
-      await deleteRelayAgentsForManaged(agent);
-    }
-    return killed;
-  }
-
-  async function deleteRelayAgentsForManaged(agent: ManagedAgentReport): Promise<void> {
-    const agents = await relay.listAgents();
-    const matches = agents.filter((candidate) => relayAgentMatchesManaged(candidate, agent));
-    for (const candidate of matches) {
-      const deleted = await relay.deleteAgent(candidate.id);
-      if (deleted) {
-        console.error(`[orchestrator] Removed relay agent record: ${candidate.id}`);
-      } else {
-        console.error(`[orchestrator] Failed to remove relay agent record: ${candidate.id}`);
-      }
-    }
-  }
-
-  function relayAgentMatchesManaged(candidate: RelayAgentSummary, managed: ManagedAgentReport): boolean {
-    if (managed.agentId && candidate.id === managed.agentId) return true;
-
-    const tags = candidate.tags || [];
-    const sameLabel = Boolean(managed.label && candidate.label === managed.label);
-    const sameProvider = tags.includes(managed.provider) || candidate.meta?.provider === managed.provider;
-    const sameCwd = candidate.meta?.cwd === managed.cwd;
-    const orchestratorOwned = tags.includes("dashboard-spawned");
-    return sameLabel && sameProvider && sameCwd && orchestratorOwned;
-  }
-
   function getManagedAgents(): ManagedAgentReport[] {
     return managedAgents;
   }
@@ -168,5 +58,5 @@ export function createControlHandler(
     managedAgents = agents;
   }
 
-  return { handle, getManagedAgents, setManagedAgents };
+  return { handleCommand, getManagedAgents, setManagedAgents };
 }

package/src/index.ts

@@ -3,6 +3,7 @@ import { loadConfig, initConfigFile } from "./config";
 import { createRelayClient } from "./relay";
 import { createControlHandler } from "./control";
 import { recoverExistingSessions, hasSession } from "./tmux";
+import { startApiServer } from "./api";
 
 const args = process.argv.slice(2);
 
@@ -25,6 +26,7 @@ Environment:
   AGENT_RELAY_TOKEN                 Authentication token
   AGENT_RELAY_ORCHESTRATOR_ID       Orchestrator ID (default: hostname)
   AGENT_RELAY_ORCHESTRATOR_BASE_DIR Base directory for agent CWDs
+  AGENT_RELAY_ORCHESTRATOR_API_PORT API server port (default: 4860)
   AGENT_RELAY_ORCHESTRATOR_CONFIG   Path to config file
 
 Config file: ~/.agent-relay/orchestrator.json
@@ -40,6 +42,7 @@ const POLL_INTERVAL_MS = 3_000;
 const REGISTER_RETRY_MS = 5_000;
 let pollTimer: Timer | null = null;
 let healthCheckTimer: Timer | null = null;
+let apiServer: { stop(): void; url: string } | null = null;
 
 async function startup(): Promise<void> {
   console.error(`[orchestrator] Starting orchestrator: ${config.id}`);
@@ -48,8 +51,13 @@ async function startup(): Promise<void> {
   console.error(`[orchestrator]   providers: ${config.providers.join(", ")}`);
   console.error(`[orchestrator]   env keys: ${Object.keys(config.env).length}`);
 
+  // Start API server before registration so we can advertise the URL
+  apiServer = startApiServer(config);
+  console.error(`[orchestrator]   apiUrl: ${apiServer.url}`);
+
   // Register with relay. The server and orchestrator are often restarted
   // together, so startup must tolerate the server not listening yet.
+  relay.setApiUrl(apiServer.url);
   await registerUntilConnected();
   relay.startHeartbeatLoop();
 
@@ -61,31 +69,26 @@ async function startup(): Promise<void> {
     await relay.updateManagedAgents(recovered);
   }
 
-  // Start polling for control messages
+  // Start polling for command requests
   startPolling();
 
   // Periodic health check — remove dead sessions
   healthCheckTimer = setInterval(healthCheck, 60_000);
 
-  console.error("[orchestrator] Ready. Polling for control messages...");
+  console.error("[orchestrator] Ready. Polling for command requests...");
 }
 
 function startPolling(): void {
   pollTimer = setInterval(async () => {
     if (!relay.connected) return;
     try {
-      const messages = await relay.pollControlMessages();
-      if (messages.length > 0) {
-        console.error(`[orchestrator] Received ${messages.length} control message(s)`);
+      const commands = await relay.pollCommands();
+      if (commands.length > 0) {
+        console.error(`[orchestrator] Received ${commands.length} command(s)`);
       }
-      for (const msg of messages) {
-        console.error(`[orchestrator] Handling: ${JSON.stringify(msg.payload?.orchestratorControl)}`);
-        const handled = await control.handle(msg);
-        if (handled) {
-          await relay.ackMessage(msg.id);
-        } else {
-          console.error(`[orchestrator] Control message ${msg.id} was not handled; leaving it unread for retry`);
-        }
+      for (const command of commands) {
+        console.error(`[orchestrator] Handling command: ${command.type} ${command.id}`);
+        await control.handleCommand(command);
       }
     } catch (err) {
       console.error(`[orchestrator] Poll error: ${err}`);
@@ -126,6 +129,7 @@ async function shutdown(): Promise<void> {
   console.error("[orchestrator] Shutting down...");
   if (pollTimer) clearInterval(pollTimer);
   if (healthCheckTimer) clearInterval(healthCheckTimer);
+  if (apiServer) apiServer.stop();
   relay.stopHeartbeatLoop();
   process.exit(0);
 }

package/src/relay.ts

@@ -5,10 +5,9 @@ export interface RelayClient {
   register(): Promise<void>;
   heartbeat(): Promise<void>;
   updateManagedAgents(agents: ManagedAgentReport[]): Promise<void>;
-  pollControlMessages(since?: number): Promise<ControlMessage[]>;
-  ackMessage(messageId: number): Promise<boolean>;
-  listAgents(): Promise<RelayAgentSummary[]>;
-  deleteAgent(agentId: string): Promise<boolean>;
+  pollCommands(): Promise<RelayCommand[]>;
+  updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<boolean>;
+  setApiUrl(url: string): void;
   startHeartbeatLoop(): void;
   stopHeartbeatLoop(): void;
   connected: boolean;
@@ -25,40 +24,12 @@ export interface ManagedAgentReport {
   startedAt: number;
 }
 
-export interface RelayAgentSummary {
+export interface RelayCommand {
   id: string;
-  label?: string;
-  status?: string;
-  ready?: boolean;
-  tags?: string[];
-  meta?: { cwd?: string; provider?: string; [key: string]: unknown };
-}
-
-export interface OrchestratorControlPayload {
-  action: string;
-  provider?: string;
-  cwd?: string;
-  label?: string;
-  approvalMode?: string;
-  prompt?: string;
-  agentId?: string;
-  requestedBy?: string;
-  requestedAt?: number;
-}
-
-export interface ControlMessage {
-  id: number;
-  body: string;
-  kind: string;
-  payload: {
-    orchestratorControl?: OrchestratorControlPayload;
-    [key: string]: unknown;
-  };
-  meta: {
-    orchestratorControl?: OrchestratorControlPayload;
-    [key: string]: unknown;
-  };
-  createdAt: number;
+  type: string;
+  target: string;
+  params: Record<string, unknown>;
+  status: string;
 }
 
 const BACKOFF_SCHEDULE_MS = [
@@ -72,6 +43,7 @@ export function createRelayClient(config: OrchestratorConfig): RelayClient {
   let connected = false;
   let backoffIndex = 0;
   let cursorFloor = 0;
+  let apiUrl: string | undefined;
 
   function headers(): Record<string, string> {
     const h: Record<string, string> = { "Content-Type": "application/json" };
@@ -95,6 +67,7 @@ export function createRelayClient(config: OrchestratorConfig): RelayClient {
       hostname: config.hostname,
       providers: config.providers,
       baseDir: config.baseDir,
+      apiUrl,
       envKeys: Object.keys(config.env),
       version: VERSION,
       protocolVersion: ORCHESTRATOR_PROTOCOL_VERSION,
@@ -127,7 +100,11 @@ export function createRelayClient(config: OrchestratorConfig): RelayClient {
 
   async function heartbeat(): Promise<void> {
     try {
-      const res = await apiCall("POST", `/orchestrators/${config.id}/heartbeat`);
+      const res = await apiCall("POST", `/orchestrators/${config.id}/heartbeat`, {
+        version: VERSION,
+        protocolVersion: ORCHESTRATOR_PROTOCOL_VERSION,
+        gitSha: GIT_SHA,
+      });
       if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
       if (!connected) {
         console.error("[orchestrator] Reconnected to relay");
@@ -161,45 +138,22 @@ export function createRelayClient(config: OrchestratorConfig): RelayClient {
     await apiCall("PATCH", `/orchestrators/${config.id}/agents`, { agents });
   }
 
-  async function pollControlMessages(since?: number): Promise<ControlMessage[]> {
-    const sinceId = since ?? cursorFloor;
-    const res = await apiCall(
-      "GET",
-      `/messages?for=${agentId}&sinceId=${sinceId}&unread=true`,
-    );
+  async function pollCommands(): Promise<RelayCommand[]> {
+    const url = `/commands?target=${encodeURIComponent(agentId)}&status=pending&limit=50`;
+    const res = await apiCall("GET", url);
     if (!res.ok) return [];
-    const messages = await res.json() as ControlMessage[];
-    if (messages.length > 0) {
-      console.error(`[orchestrator] Polled ${messages.length} message(s) (sinceId=${sinceId}), ids: ${messages.map(m => m.id).join(",")}`);
-    }
-    const controlMessages = messages
-      .filter((m) => m.kind === "control" && (m.payload?.orchestratorControl != null || m.meta?.orchestratorControl != null))
-      .map((m) => ({
-        ...m,
-        payload: {
-          ...m.payload,
-          orchestratorControl: m.payload?.orchestratorControl ?? m.meta?.orchestratorControl,
-        },
-      }));
-    return controlMessages;
+    return await res.json() as RelayCommand[];
   }
 
-  async function ackMessage(messageId: number): Promise<boolean> {
-    const res = await apiCall("PATCH", `/messages/${messageId}`, { readBy: agentId });
+  async function updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<boolean> {
+    const res = await apiCall("PATCH", `/commands/${encodeURIComponent(commandId)}`, {
+      status,
+      ...(result ? { result } : {}),
+      ...(error ? { error } : {}),
+    });
     return res.ok;
   }
 
-  async function listAgents(): Promise<RelayAgentSummary[]> {
-    const res = await apiCall("GET", "/agents");
-    if (!res.ok) return [];
-    return await res.json() as RelayAgentSummary[];
-  }
-
-  async function deleteAgent(agentId: string): Promise<boolean> {
-    const res = await apiCall("DELETE", `/agents/${encodeURIComponent(agentId)}`);
-    return res.ok || res.status === 404;
-  }
-
   function startHeartbeatLoop(): void {
     if (heartbeatTimer) return;
     heartbeatTimer = setInterval(heartbeat, config.heartbeatIntervalMs);
@@ -216,10 +170,9 @@ export function createRelayClient(config: OrchestratorConfig): RelayClient {
     register,
     heartbeat,
     updateManagedAgents,
-    pollControlMessages,
-    ackMessage,
-    listAgents,
-    deleteAgent,
+    pollCommands,
+    updateCommand,
+    setApiUrl(url: string) { apiUrl = url; },
     startHeartbeatLoop,
     stopHeartbeatLoop,
     get connected() { return connected; },

package/src/tmux.ts

@@ -8,12 +8,13 @@ export interface SpawnOptions {
   provider: "claude" | "codex";
   cwd: string;
   label?: string;
+  agentId?: string;
   approvalMode: string;
   prompt?: string;
   env?: Record<string, string>;
 }
 
-export interface TmuxSession {
+interface TmuxSession {
   name: string;
   pid: number;
   attached: boolean;
@@ -24,7 +25,7 @@ export function sessionName(config: OrchestratorConfig, provider: string, label:
   return `${config.tmuxPrefix}-${provider}-${clean}`;
 }
 
-export async function listTmuxSessions(prefix: string): Promise<TmuxSession[]> {
+async function listTmuxSessions(prefix: string): Promise<TmuxSession[]> {
   try {
     const proc = Bun.spawn(["tmux", "list-sessions", "-F", "#{session_name}\t#{pid}\t#{session_attached}"], {
       stdout: "pipe",
@@ -51,34 +52,23 @@ export async function hasSession(name: string): Promise<boolean> {
   return (await proc.exited) === 0;
 }
 
-export async function killSession(name: string): Promise<boolean> {
-  const proc = Bun.spawn(["tmux", "kill-session", "-t", name], {
-    stdout: "ignore",
-    stderr: "ignore",
-  });
-  return (await proc.exited) === 0;
-}
-
-function buildClaudeCommand(opts: SpawnOptions, config: OrchestratorConfig): string[] {
-  const args = ["claude"];
-  if (opts.prompt) {
-    args.push(opts.prompt);
-  } else {
-    args.push("You are a headless relay agent spawned by the orchestrator. Await and respond to incoming relay messages.");
-  }
-  args.push("--dangerously-skip-permissions");
-  return args;
-}
-
-export function buildCodexCommand(opts: SpawnOptions, config: OrchestratorConfig): string[] {
-  const repoLauncher = resolve(import.meta.dir, "../../codex/bin/agent-relay-codex.ts");
+export function buildRunnerCommand(opts: SpawnOptions, config: OrchestratorConfig): string[] {
+  const repoLauncher = resolve(import.meta.dir, "../../runner/src/index.ts");
   const launcher = existsSync(repoLauncher)
-    ? ["bun", "run", repoLauncher, "start"]
-    : ["codex-relay"];
-  return [
+    ? ["bun", "run", repoLauncher, opts.provider]
+    : [`${opts.provider}-relay`];
+  const args = [
     ...launcher,
     "--headless",
+    "--cwd", opts.cwd,
     "--relay-url", config.relayUrl,
+    "--approval", opts.approvalMode || "guarded",
+  ];
+  if (opts.label) args.push("--label", opts.label);
+  if (opts.agentId) args.push("--agent-id", opts.agentId);
+  if (opts.prompt) args.push("--prompt", opts.prompt);
+  return [
+    ...args,
   ];
 }
 
@@ -101,7 +91,7 @@ function buildEnv(opts: SpawnOptions, config: OrchestratorConfig): Record<string
     AGENT_RELAY_URL: config.relayUrl,
     AGENT_RELAY_APPROVAL: opts.approvalMode || "guarded",
     AGENT_RELAY_TAGS: ["headless", "dashboard-spawned", config.hostname].join(","),
-    ...(opts.provider === "codex" ? { AGENT_RELAY_CODEX_HEADLESS: "1" } : {}),
+    AGENT_RELAY_HEADLESS: "1",
     ...(opts.label ? { AGENT_RELAY_LABEL: opts.label } : {}),
     ...(config.token ? { AGENT_RELAY_TOKEN: config.token } : {}),
   };
@@ -112,7 +102,8 @@ export async function spawnAgent(
   config: OrchestratorConfig,
 ): Promise<ManagedAgentReport> {
   const label = opts.label || `${opts.provider}-${Date.now()}`;
-  const spawnOpts: SpawnOptions = { ...opts, label };
+  const agentId = opts.agentId || managedAgentId(config, opts.provider, label);
+  const spawnOpts: SpawnOptions = { ...opts, label, agentId };
   const name = sessionName(config, opts.provider, label);
 
   if (!existsSync(opts.cwd)) {
@@ -122,9 +113,7 @@ export async function spawnAgent(
     throw new Error(`cwd must be within base directory: ${config.baseDir}`);
   }
 
-  const command = spawnOpts.provider === "claude"
-    ? buildClaudeCommand(spawnOpts, config)
-    : buildCodexCommand(spawnOpts, config);
+  const command = buildRunnerCommand(spawnOpts, config);
 
   const env = buildEnv(spawnOpts, config);
 
@@ -160,22 +149,11 @@ export async function spawnAgent(
     throw new Error(`tmux spawn failed (exit ${exitCode}): ${stderr.trim()}`);
   }
 
-  // Wait for Claude to show the trust prompt, then accept it
-  if (spawnOpts.provider === "claude") {
-    await new Promise((resolve) => setTimeout(resolve, 4000));
-    const accept = Bun.spawn(["tmux", "send-keys", "-t", name, "Enter"], {
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    await accept.exited;
-    console.error(`[orchestrator] Sent trust-accept Enter to ${name}`);
-  }
-
   // Get the PID from tmux
   const pid = await getSessionPid(name);
 
   return {
-    agentId: "", // will be filled when the agent self-registers on the relay
+    agentId,
     provider: spawnOpts.provider,
     tmuxSession: name,
     cwd: spawnOpts.cwd,
@@ -186,6 +164,12 @@ export async function spawnAgent(
   };
 }
 
+function managedAgentId(config: OrchestratorConfig, provider: string, label: string): string {
+  const cleanHost = config.hostname.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  const cleanLabel = label.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  return `${cleanHost}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
 async function getSessionPid(name: string): Promise<number | null> {
   try {
     const proc = Bun.spawn(["tmux", "display-message", "-p", "-t", name, "#{pane_pid}"], {
@@ -219,7 +203,7 @@ export async function recoverExistingSessions(
     const cwd = await getSessionCwd(session.name);
 
     managed.push({
-      agentId: "",
+      agentId: managedAgentId(config, provider, label || session.name),
       provider,
       tmuxSession: session.name,
       cwd: cwd || config.baseDir,

package/src/version.ts

@@ -6,5 +6,5 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { version?: string };
 
 export const VERSION = pkg.version || "0.0.0";
-export const ORCHESTRATOR_PROTOCOL_VERSION = 2;
+export const ORCHESTRATOR_PROTOCOL_VERSION = 3;
 export const GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;