agent-relay-orchestrator 0.9.0

package/README.md

@@ -0,0 +1,8 @@
+# agent-relay-orchestrator
+
+Host daemon for Agent Relay. It registers host capabilities, receives lifecycle control messages, and spawns managed Claude/Codex agents in tmux sessions.
+
+```bash
+agent-relay-orchestrator init
+agent-relay-orchestrator
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "agent-relay-orchestrator",
+  "version": "0.9.0",
+  "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
+  "type": "module",
+  "bin": {
+    "agent-relay-orchestrator": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "test": "bun test"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/config.ts

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir, hostname as osHostname } from "node:os";
+import { join, dirname } from "node:path";
+
+export interface OrchestratorConfig {
+  id: string;
+  hostname: string;
+  relayUrl: string;
+  token?: string;
+  providers: ("claude" | "codex")[];
+  baseDir: string;
+  env: Record<string, string>;
+  heartbeatIntervalMs: number;
+  tmuxPrefix: string;
+}
+
+const DEFAULT_CONFIG_PATH = join(homedir(), ".agent-relay", "orchestrator.json");
+
+interface RawConfig {
+  id?: string;
+  hostname?: string;
+  relayUrl?: string;
+  token?: string;
+  providers?: string[];
+  baseDir?: string;
+  env?: Record<string, string>;
+  heartbeatIntervalMs?: number;
+  tmuxPrefix?: string;
+}
+
+export function loadConfig(path?: string): OrchestratorConfig {
+  const configPath = path || process.env.AGENT_RELAY_ORCHESTRATOR_CONFIG || DEFAULT_CONFIG_PATH;
+
+  let raw: RawConfig = {};
+  if (existsSync(configPath)) {
+    raw = JSON.parse(readFileSync(configPath, "utf8"));
+  }
+
+  const id = raw.id || process.env.AGENT_RELAY_ORCHESTRATOR_ID || osHostname().replace(/\./g, "-");
+  const hostname = raw.hostname || process.env.AGENT_RELAY_ORCHESTRATOR_HOSTNAME || osHostname();
+  const relayUrl = raw.relayUrl || process.env.AGENT_RELAY_URL || "http://localhost:4850";
+  const token = raw.token || process.env.AGENT_RELAY_TOKEN || undefined;
+  const providers = (raw.providers || process.env.AGENT_RELAY_ORCHESTRATOR_PROVIDERS?.split(",") || ["claude", "codex"]) as ("claude" | "codex")[];
+  const baseDir = raw.baseDir || process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR || join(homedir(), "projects");
+  const env = raw.env || {};
+  const heartbeatIntervalMs = raw.heartbeatIntervalMs || 30_000;
+  const tmuxPrefix = raw.tmuxPrefix || "ar";
+
+  return { id, hostname, relayUrl, token, providers, baseDir, env, heartbeatIntervalMs, tmuxPrefix };
+}
+
+export function initConfigFile(config: Partial<RawConfig>): string {
+  const configPath = DEFAULT_CONFIG_PATH;
+  mkdirSync(dirname(configPath), { recursive: true });
+  const defaults: RawConfig = {
+    id: osHostname().replace(/\./g, "-"),
+    hostname: osHostname(),
+    relayUrl: "http://localhost:4850",
+    providers: ["claude", "codex"],
+    baseDir: join(homedir(), "projects"),
+    env: {},
+  };
+  const merged = { ...defaults, ...config };
+  writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n");
+  return configPath;
+}

package/src/control.ts

@@ -0,0 +1,172 @@
+import type { OrchestratorConfig } from "./config";
+import type { ControlMessage, ManagedAgentReport, RelayAgentSummary, RelayClient } from "./relay";
+import { hasSession, killSession, spawnAgent, type SpawnOptions } from "./tmux";
+
+export interface ControlHandler {
+  handle(message: ControlMessage): Promise<boolean>;
+  getManagedAgents(): ManagedAgentReport[];
+  setManagedAgents(agents: ManagedAgentReport[]): void;
+}
+
+export function createControlHandler(
+  config: OrchestratorConfig,
+  relay: RelayClient,
+): 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",
+      cwd: ctrl.cwd || config.baseDir,
+      label: ctrl.label,
+      approvalMode: ctrl.approvalMode || "guarded",
+      prompt: ctrl.prompt,
+    };
+
+    try {
+      const agent = await spawnAgent(opts, config);
+      managedAgents.push(agent);
+      console.error(`[orchestrator] Spawned ${opts.provider} agent: ${agent.tmuxSession}`);
+      return true;
+    } catch (err) {
+      console.error(`[orchestrator] Spawn failed: ${err}`);
+      return false;
+    }
+  }
+
+  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
+    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}`);
+      return true;
+    } catch (err) {
+      console.error(`[orchestrator] Restart spawn failed: ${err}`);
+      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;
+  }
+
+  function setManagedAgents(agents: ManagedAgentReport[]): void {
+    managedAgents = agents;
+  }
+
+  return { handle, getManagedAgents, setManagedAgents };
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env bun
+import { loadConfig, initConfigFile } from "./config";
+import { createRelayClient } from "./relay";
+import { createControlHandler } from "./control";
+import { recoverExistingSessions, hasSession } from "./tmux";
+
+const args = process.argv.slice(2);
+
+if (args[0] === "init") {
+  const path = initConfigFile({});
+  console.error(`[orchestrator] Config initialized at ${path}`);
+  console.error("[orchestrator] Edit it to set your relay URL, base directory, and secrets.");
+  process.exit(0);
+}
+
+if (args[0] === "--help" || args[0] === "-h") {
+  console.log(`agent-relay-orchestrator — manage agent lifecycle across hosts
+
+Usage:
+  agent-relay-orchestrator          Start the orchestrator daemon
+  agent-relay-orchestrator init     Create default config file
+
+Environment:
+  AGENT_RELAY_URL                   Relay server URL (default: http://localhost:4850)
+  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_CONFIG   Path to config file
+
+Config file: ~/.agent-relay/orchestrator.json
+`);
+  process.exit(0);
+}
+
+const config = loadConfig();
+const relay = createRelayClient(config);
+const control = createControlHandler(config, relay);
+
+const POLL_INTERVAL_MS = 3_000;
+const REGISTER_RETRY_MS = 5_000;
+let pollTimer: Timer | null = null;
+let healthCheckTimer: Timer | null = null;
+
+async function startup(): Promise<void> {
+  console.error(`[orchestrator] Starting orchestrator: ${config.id}`);
+  console.error(`[orchestrator]   relay: ${config.relayUrl}`);
+  console.error(`[orchestrator]   baseDir: ${config.baseDir}`);
+  console.error(`[orchestrator]   providers: ${config.providers.join(", ")}`);
+  console.error(`[orchestrator]   env keys: ${Object.keys(config.env).length}`);
+
+  // Register with relay. The server and orchestrator are often restarted
+  // together, so startup must tolerate the server not listening yet.
+  await registerUntilConnected();
+  relay.startHeartbeatLoop();
+
+  // Recover existing tmux sessions
+  const recovered = await recoverExistingSessions(config);
+  if (recovered.length > 0) {
+    console.error(`[orchestrator] Recovered ${recovered.length} existing session(s)`);
+    control.setManagedAgents(recovered);
+    await relay.updateManagedAgents(recovered);
+  }
+
+  // Start polling for control messages
+  startPolling();
+
+  // Periodic health check — remove dead sessions
+  healthCheckTimer = setInterval(healthCheck, 60_000);
+
+  console.error("[orchestrator] Ready. Polling for control messages...");
+}
+
+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)`);
+      }
+      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`);
+        }
+      }
+    } catch (err) {
+      console.error(`[orchestrator] Poll error: ${err}`);
+    }
+  }, POLL_INTERVAL_MS);
+}
+
+async function registerUntilConnected(): Promise<void> {
+  for (;;) {
+    try {
+      await relay.register();
+      return;
+    } catch (err) {
+      console.error(`[orchestrator] Register failed: ${err}`);
+      console.error(`[orchestrator] Retrying registration in ${Math.round(REGISTER_RETRY_MS / 1000)}s...`);
+      await new Promise((resolve) => setTimeout(resolve, REGISTER_RETRY_MS));
+    }
+  }
+}
+
+async function healthCheck(): Promise<void> {
+  const agents = control.getManagedAgents();
+  let changed = false;
+  for (const agent of agents) {
+    const alive = await hasSession(agent.tmuxSession);
+    if (!alive) {
+      console.error(`[orchestrator] Session dead: ${agent.tmuxSession} — removing from managed list`);
+      control.setManagedAgents(agents.filter((a) => a.tmuxSession !== agent.tmuxSession));
+      changed = true;
+    }
+  }
+  if (changed) {
+    await relay.updateManagedAgents(control.getManagedAgents());
+  }
+}
+
+async function shutdown(): Promise<void> {
+  console.error("[orchestrator] Shutting down...");
+  if (pollTimer) clearInterval(pollTimer);
+  if (healthCheckTimer) clearInterval(healthCheckTimer);
+  relay.stopHeartbeatLoop();
+  process.exit(0);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+startup().catch((err) => {
+  console.error(`[orchestrator] Fatal: ${err}`);
+  process.exit(1);
+});

package/src/relay.ts

@@ -0,0 +1,227 @@
+import type { OrchestratorConfig } from "./config";
+import { GIT_SHA, ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "./version";
+
+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>;
+  startHeartbeatLoop(): void;
+  stopHeartbeatLoop(): void;
+  connected: boolean;
+}
+
+export interface ManagedAgentReport {
+  agentId: string;
+  provider: "claude" | "codex";
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: string;
+  pid?: number;
+  startedAt: number;
+}
+
+export interface RelayAgentSummary {
+  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;
+}
+
+const BACKOFF_SCHEDULE_MS = [
+  30_000, 60_000, 120_000, 240_000, 480_000, 960_000,
+];
+const MAX_BACKOFF_MS = 3_600_000; // 1 hour
+
+export function createRelayClient(config: OrchestratorConfig): RelayClient {
+  const agentId = `orchestrator-${config.id}`;
+  let heartbeatTimer: Timer | null = null;
+  let connected = false;
+  let backoffIndex = 0;
+  let cursorFloor = 0;
+
+  function headers(): Record<string, string> {
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (config.token) h["X-Agent-Relay-Token"] = config.token;
+    return h;
+  }
+
+  async function apiCall(method: string, path: string, body?: unknown): Promise<Response> {
+    const url = `${config.relayUrl}/api${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: headers(),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    return res;
+  }
+
+  async function register(): Promise<void> {
+    const res = await apiCall("POST", "/orchestrators", {
+      id: config.id,
+      hostname: config.hostname,
+      providers: config.providers,
+      baseDir: config.baseDir,
+      envKeys: Object.keys(config.env),
+      version: VERSION,
+      protocolVersion: ORCHESTRATOR_PROTOCOL_VERSION,
+      gitSha: GIT_SHA,
+      meta: {
+        pid: process.pid,
+        tmuxPrefix: config.tmuxPrefix,
+        startedAt: Date.now(),
+        version: VERSION,
+        protocolVersion: ORCHESTRATOR_PROTOCOL_VERSION,
+        gitSha: GIT_SHA,
+      },
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to register orchestrator: ${res.status} ${err}`);
+    }
+    connected = true;
+    backoffIndex = 0;
+
+    // Bootstrap message cursor
+    const cursor = await apiCall("GET", "/messages/cursor");
+    if (cursor.ok) {
+      const data = await cursor.json() as { latestId: number };
+      cursorFloor = data.latestId;
+    }
+
+    console.error(`[orchestrator] Registered as ${config.id} (agent: ${agentId})`);
+  }
+
+  async function heartbeat(): Promise<void> {
+    try {
+      const res = await apiCall("POST", `/orchestrators/${config.id}/heartbeat`);
+      if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
+      if (!connected) {
+        console.error("[orchestrator] Reconnected to relay");
+        connected = true;
+        backoffIndex = 0;
+      }
+    } catch (err) {
+      if (connected) {
+        console.error(`[orchestrator] Lost connection to relay: ${err}`);
+        connected = false;
+      }
+      await reconnect();
+    }
+  }
+
+  async function reconnect(): Promise<void> {
+    const delay = backoffIndex < BACKOFF_SCHEDULE_MS.length
+      ? BACKOFF_SCHEDULE_MS[backoffIndex]!
+      : MAX_BACKOFF_MS;
+    backoffIndex = Math.min(backoffIndex + 1, BACKOFF_SCHEDULE_MS.length);
+    console.error(`[orchestrator] Reconnecting in ${Math.round(delay / 1000)}s...`);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    try {
+      await register();
+    } catch {
+      // Will retry on next heartbeat
+    }
+  }
+
+  async function updateManagedAgents(agents: ManagedAgentReport[]): Promise<void> {
+    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`,
+    );
+    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;
+  }
+
+  async function ackMessage(messageId: number): Promise<boolean> {
+    const res = await apiCall("PATCH", `/messages/${messageId}`, { readBy: agentId });
+    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);
+  }
+
+  function stopHeartbeatLoop(): void {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  return {
+    register,
+    heartbeat,
+    updateManagedAgents,
+    pollControlMessages,
+    ackMessage,
+    listAgents,
+    deleteAgent,
+    startHeartbeatLoop,
+    stopHeartbeatLoop,
+    get connected() { return connected; },
+  };
+}

package/src/tmux.ts

@@ -0,0 +1,255 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { OrchestratorConfig } from "./config";
+import type { ManagedAgentReport } from "./relay";
+
+export interface SpawnOptions {
+  provider: "claude" | "codex";
+  cwd: string;
+  label?: string;
+  approvalMode: string;
+  prompt?: string;
+  env?: Record<string, string>;
+}
+
+export interface TmuxSession {
+  name: string;
+  pid: number;
+  attached: boolean;
+}
+
+export function sessionName(config: OrchestratorConfig, provider: string, label: string): string {
+  const clean = label.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  return `${config.tmuxPrefix}-${provider}-${clean}`;
+}
+
+export 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",
+      stderr: "pipe",
+    });
+    const out = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    if (code !== 0) return [];
+
+    return out.trim().split("\n").filter(Boolean).map((line) => {
+      const [name, pid, attached] = line.split("\t");
+      return { name: name!, pid: parseInt(pid!, 10), attached: attached === "1" };
+    }).filter((s) => s.name.startsWith(`${prefix}-`));
+  } catch {
+    return [];
+  }
+}
+
+export async function hasSession(name: string): Promise<boolean> {
+  const proc = Bun.spawn(["tmux", "has-session", "-t", name], {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  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");
+  const launcher = existsSync(repoLauncher)
+    ? ["bun", "run", repoLauncher, "start"]
+    : ["codex-relay"];
+  return [
+    ...launcher,
+    "--headless",
+    "--relay-url", config.relayUrl,
+  ];
+}
+
+function buildEnv(opts: SpawnOptions, config: OrchestratorConfig): Record<string, string> {
+  const currentPath = process.env.PATH || "";
+  const extraPaths = [
+    join(homedir(), ".local", "bin"),
+    join(homedir(), ".bun", "bin"),
+    join(homedir(), ".npm-global", "bin"),
+  ];
+  const fullPath = [...extraPaths, ...currentPath.split(":").filter(Boolean)]
+    .filter((v, i, a) => a.indexOf(v) === i)
+    .join(":");
+
+  return {
+    ...process.env as Record<string, string>,
+    ...config.env,
+    ...(opts.env || {}),
+    PATH: fullPath,
+    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" } : {}),
+    ...(opts.label ? { AGENT_RELAY_LABEL: opts.label } : {}),
+    ...(config.token ? { AGENT_RELAY_TOKEN: config.token } : {}),
+  };
+}
+
+export async function spawnAgent(
+  opts: SpawnOptions,
+  config: OrchestratorConfig,
+): Promise<ManagedAgentReport> {
+  const label = opts.label || `${opts.provider}-${Date.now()}`;
+  const spawnOpts: SpawnOptions = { ...opts, label };
+  const name = sessionName(config, opts.provider, label);
+
+  if (!existsSync(opts.cwd)) {
+    throw new Error(`cwd does not exist: ${opts.cwd}`);
+  }
+  if (!opts.cwd.startsWith(config.baseDir)) {
+    throw new Error(`cwd must be within base directory: ${config.baseDir}`);
+  }
+
+  const command = spawnOpts.provider === "claude"
+    ? buildClaudeCommand(spawnOpts, config)
+    : buildCodexCommand(spawnOpts, config);
+
+  const env = buildEnv(spawnOpts, config);
+
+  // Build the env export string for tmux
+  const envExports = Object.entries(env)
+    .filter(([k]) => k === "PATH" || k.startsWith("AGENT_RELAY_") || k.startsWith("CLAUDE_") || k.startsWith("ANTHROPIC_") || k === "GITHUB_TOKEN" || k === "NPM_TOKEN" || k === "HOME" || k === "USER" || k === "SHELL")
+    .map(([k, v]) => `${k}=${shellEscape(v)}`)
+    .join(" ");
+
+  const fullCommand = envExports
+    ? `env ${envExports} ${command.map(shellEscape).join(" ")}`
+    : command.map(shellEscape).join(" ");
+
+  const tmuxArgs = [
+    "tmux", "new-session", "-d",
+    "-s", name,
+    "-c", opts.cwd,
+    fullCommand,
+  ];
+
+  console.error(`[orchestrator] Spawning ${opts.provider} agent: ${name}`);
+  console.error(`[orchestrator]   cwd: ${opts.cwd}`);
+  console.error(`[orchestrator]   command: ${fullCommand}`);
+
+  const proc = Bun.spawn(tmuxArgs, {
+    stdout: "pipe",
+    stderr: "pipe",
+    env,
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    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
+    provider: spawnOpts.provider,
+    tmuxSession: name,
+    cwd: spawnOpts.cwd,
+    label,
+    approvalMode: spawnOpts.approvalMode || "guarded",
+    pid: pid ?? undefined,
+    startedAt: Date.now(),
+  };
+}
+
+async function getSessionPid(name: string): Promise<number | null> {
+  try {
+    const proc = Bun.spawn(["tmux", "display-message", "-p", "-t", name, "#{pane_pid}"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const out = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    if (code !== 0) return null;
+    const pid = parseInt(out.trim(), 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export async function recoverExistingSessions(
+  config: OrchestratorConfig,
+): Promise<ManagedAgentReport[]> {
+  const sessions = await listTmuxSessions(config.tmuxPrefix);
+  const managed: ManagedAgentReport[] = [];
+
+  for (const session of sessions) {
+    // Parse provider and label from session name: "ar-claude-backend" → provider=claude, label=backend
+    const parts = session.name.slice(config.tmuxPrefix.length + 1).split("-");
+    const provider = parts[0] as "claude" | "codex";
+    if (provider !== "claude" && provider !== "codex") continue;
+    const label = parts.slice(1).join("-") || undefined;
+
+    // Get cwd from tmux
+    const cwd = await getSessionCwd(session.name);
+
+    managed.push({
+      agentId: "",
+      provider,
+      tmuxSession: session.name,
+      cwd: cwd || config.baseDir,
+      label,
+      approvalMode: "guarded",
+      pid: session.pid || undefined,
+      startedAt: Date.now(),
+    });
+
+    console.error(`[orchestrator] Recovered existing session: ${session.name} (${provider}, pid ${session.pid})`);
+  }
+
+  return managed;
+}
+
+async function getSessionCwd(name: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["tmux", "display-message", "-p", "-t", name, "#{pane_current_path}"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const out = await new Response(proc.stdout).text();
+    const code = await proc.exited;
+    return code === 0 ? out.trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+
+function shellEscape(s: string): string {
+  if (/^[a-zA-Z0-9._\-/:=@]+$/.test(s)) return s;
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/version.ts

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+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 GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;