agent-relay-server 0.4.39 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.4.39",
+  "version": "0.5.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/public/dashboard.js

@@ -54,6 +54,7 @@
 
       agents: [],
       agentsById: {},
+      orchestrators: [],
       pairs: [],
       messages: [],
       tasks: [],
@@ -85,6 +86,14 @@
       replyTo: null,
       composeOpen: false,
       agentSpawnOpen: false,
+      orchestratorSpawnOpen: false,
+      spawnOrchId: "",
+      spawnProvider: "claude",
+      spawnCwd: "",
+      spawnLabel: "",
+      spawnApproval: "guarded",
+      spawnPrompt: "",
+      spawnDirListing: null,
       agentDirectoryBrowser: { open: false, loading: false, path: "", parent: "", home: "", cwd: "", entries: [], error: "" },
       pairInviteOpen: false,
       pairMessageOpen: false,
@@ -281,6 +290,8 @@
     es.addEventListener("message.claimed", (event) => handleMessageClaimed(this, parseEventData(event)));
     es.addEventListener("message.claim_released", (event) => handleMessageClaimReleased(this, parseEventData(event)));
     es.addEventListener("message.deleted", (event) => handleMessageDeleted(this, parseEventData(event)));
+    es.addEventListener("orchestrator.status", (event) => handleOrchestratorStatus(this, parseEventData(event)));
+    es.addEventListener("orchestrator.removed", (event) => handleOrchestratorRemoved(this, parseEventData(event)));
     registerTaskEvents(this, es);
   }
 
@@ -320,6 +331,14 @@
     refreshChartsIfVisible(vm);
   }
 
+  function handleOrchestratorStatus(vm, orch) {
+    upsertById(vm.orchestrators, orch);
+  }
+
+  function handleOrchestratorRemoved(vm, data) {
+    vm.orchestrators = vm.orchestrators.filter((o) => o.id !== data.id);
+  }
+
   function handleMessageClaimed(vm, data) {
     const msg = vm.messages.find((item) => item.id === data.messageId);
     if (!msg) return;
@@ -374,7 +393,7 @@
       },
 
       async refresh() {
-        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchChannels(), this.fetchIntegrations(), this.fetchInboxState(), this.fetchActivityEvents()]);
+        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchOrchestrators(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchChannels(), this.fetchIntegrations(), this.fetchInboxState(), this.fetchActivityEvents()]);
       },
 
       async refreshLiveData() {
@@ -407,6 +426,12 @@
         } catch {}
       },
 
+      async fetchOrchestrators() {
+        try {
+          this.orchestrators = await this.api("GET", "/orchestrators");
+        } catch {}
+      },
+
       async fetchPairs() {
         try {
           let pairs;
@@ -535,9 +560,15 @@
       healthIssues: { get: getHealthIssues },
       healthDiagnostics: { get: getHealthDiagnostics },
       commandPaletteItems: { get: getCommandPaletteItems },
+      spawnAvailableProviders: { get: getSpawnAvailableProviders },
     };
   }
 
+  function getSpawnAvailableProviders() {
+    const orch = this.orchestrators.find((o) => o.id === this.spawnOrchId);
+    return orch ? orch.providers : ["claude", "codex"];
+  }
+
   function getOnlineCount() {
     return visibleAgents(this).filter((agent) => agent.status !== "offline").length;
   }
@@ -1667,6 +1698,12 @@
       openAgentDirectoryBrowser,
       browseAgentDirectory,
       selectAgentDirectory,
+      openOrchestratorSpawn,
+      openOrchestratorSpawnFor,
+      browseOrchestratorDirs,
+      submitOrchestratorSpawn,
+      orchestratorAction,
+      deleteOrchestrator,
       doSendPairMessage,
       doAcceptPair,
       doRejectPair,
@@ -2478,6 +2515,96 @@
     }
   }
 
+  // --- Orchestrator methods ---
+
+  function openOrchestratorSpawn() {
+    const online = this.orchestrators.filter((o) => o.status === "online");
+    if (online.length === 0) return alert("No orchestrators online");
+    this.spawnOrchId = online[0].id;
+    this.spawnProvider = "claude";
+    this.spawnCwd = "";
+    this.spawnLabel = "";
+    this.spawnApproval = "guarded";
+    this.spawnPrompt = "";
+    this.spawnDirListing = null;
+    this.orchestratorSpawnOpen = true;
+  }
+
+  function openOrchestratorSpawnFor(orchId) {
+    this.spawnOrchId = orchId;
+    this.spawnProvider = "claude";
+    this.spawnCwd = "";
+    this.spawnLabel = "";
+    this.spawnApproval = "guarded";
+    this.spawnPrompt = "";
+    this.spawnDirListing = null;
+    this.orchestratorSpawnOpen = true;
+  }
+
+  async function browseOrchestratorDirs() {
+    try {
+      const query = this.spawnCwd ? "?path=" + encodeURIComponent(this.spawnCwd) : "";
+      this.spawnDirListing = await this.api("GET", "/agents/spawn/directories" + query);
+    } catch (e) {
+      alert("Directory browse failed: " + e.message);
+    }
+  }
+
+  async function submitOrchestratorSpawn() {
+    if (!this.spawnOrchId) return alert("Select an orchestrator");
+    try {
+      const payload = {
+        provider: this.spawnProvider,
+        approvalMode: this.spawnApproval,
+      };
+      if (this.spawnCwd) payload.cwd = this.spawnCwd;
+      if (this.spawnLabel) payload.label = this.spawnLabel;
+      if (this.spawnPrompt) payload.prompt = this.spawnPrompt;
+      await this.api("POST", "/orchestrators/" + encodeURIComponent(this.spawnOrchId) + "/spawn", payload);
+      this.orchestratorSpawnOpen = false;
+      this.recordOperatorActivity({
+        title: `${this.spawnProvider} agent spawn requested`,
+        body: this.spawnCwd || "",
+        meta: this.spawnOrchId,
+        icon: "ti-plus",
+        kind: "state",
+        view: "orchestrators",
+      });
+      await Promise.all([this.fetchOrchestrators(), this.fetchActivityEvents()]);
+    } catch (e) {
+      alert("Spawn failed: " + e.message);
+    }
+  }
+
+  async function orchestratorAction(orchId, action, agentId) {
+    const label = action === "restart" ? "Restart" : "Shutdown";
+    if (!confirm(`${label} agent "${agentId || "all"}" on orchestrator "${orchId}"?`)) return;
+    try {
+      await this.api("POST", "/orchestrators/" + encodeURIComponent(orchId) + "/actions", { action, agentId });
+      this.recordOperatorActivity({
+        title: `Agent ${action} requested`,
+        body: agentId || "all agents",
+        meta: orchId,
+        icon: action === "restart" ? "ti-refresh" : "ti-power",
+        kind: "state",
+        view: "orchestrators",
+      });
+      await Promise.all([this.fetchOrchestrators(), this.fetchActivityEvents()]);
+    } catch (e) {
+      alert(`${label} failed: ` + e.message);
+    }
+  }
+
+  async function deleteOrchestrator(orchId) {
+    if (!confirm(`Remove orchestrator "${orchId}"? This will NOT stop its managed agents.`)) return;
+    try {
+      await this.api("DELETE", "/orchestrators/" + encodeURIComponent(orchId));
+      await this.fetchOrchestrators();
+    } catch (e) {
+      alert("Delete failed: " + e.message);
+    }
+  }
+
   function closePairMessage() {
     this.pairMessageOpen = false;
     this.pairMessage = { ...DEFAULT_PAIR_MESSAGE };

package/public/index.html

@@ -210,6 +210,12 @@
           <span class="badge bg-success text-white" x-show="onlineCount > 0" x-text="onlineCount"></span>
         </span>
       </a>
+      <a href="#" class="nav-link" :class="{ active: view === 'orchestrators' }" @click.prevent="switchView('orchestrators')">
+        <i class="ti ti-server-2"></i>Orchestrators
+        <span class="ms-auto d-inline-flex gap-1 align-items-center">
+          <span class="badge bg-success text-white" x-show="orchestrators.filter(o => o.status === 'online').length > 0" x-text="orchestrators.filter(o => o.status === 'online').length"></span>
+        </span>
+      </a>
       <a href="#" class="nav-link" :class="{ active: view === 'channels' }" @click.prevent="switchView('channels')">
         <i class="ti ti-messages"></i>Channels
         <span class="badge bg-success text-white ms-auto" x-show="channelCards.filter((item) => item.ready).length > 0" x-text="channelCards.filter((item) => item.ready).length"></span>
@@ -658,6 +664,185 @@
         </template>
       </div>
 
+      <!-- ==================== ORCHESTRATORS ==================== -->
+      <div x-show="view === 'orchestrators'" x-cloak class="fade-in">
+        <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">
+          <h2 class="page-title mb-0">Orchestrators</h2>
+          <span class="badge bg-success-lt" x-show="orchestrators.filter(o => o.status === 'online').length > 0"
+                x-text="orchestrators.filter(o => o.status === 'online').length + ' online'"></span>
+          <div class="ms-auto">
+            <button class="btn btn-sm btn-primary" @click="openOrchestratorSpawn()" :disabled="orchestrators.filter(o => o.status === 'online').length === 0">
+              <i class="ti ti-plus me-1"></i>Spawn Agent
+            </button>
+          </div>
+        </div>
+
+        <template x-if="orchestrators.length > 0">
+          <div class="row g-3">
+            <template x-for="orch in orchestrators" :key="orch.id">
+              <div class="col-12 col-lg-6">
+                <div class="card">
+                  <div class="card-body">
+                    <div class="d-flex align-items-center mb-3">
+                      <i class="ti ti-server-2 me-2" style="font-size: 24px"></i>
+                      <div>
+                        <h3 class="mb-0" x-text="orch.hostname"></h3>
+                        <small class="text-secondary" x-text="orch.id"></small>
+                      </div>
+                      <span class="ms-auto badge" :class="orch.status === 'online' ? 'bg-success' : 'bg-secondary'" x-text="orch.status"></span>
+                    </div>
+
+                    <div class="d-flex gap-3 mb-3 text-secondary" style="font-size: 13px">
+                      <span><i class="ti ti-folder me-1"></i><span x-text="orch.baseDir"></span></span>
+                      <span><i class="ti ti-key me-1"></i><span x-text="(orch.envKeys?.length || 0) + ' env vars'"></span></span>
+                    </div>
+
+                    <div class="d-flex gap-1 mb-3">
+                      <template x-for="provider in orch.providers" :key="provider">
+                        <span class="badge" :class="provider === 'claude' ? 'bg-orange-lt' : 'bg-blue-lt'" x-text="provider"></span>
+                      </template>
+                    </div>
+
+                    <template x-if="orch.managedAgents?.length > 0">
+                      <div>
+                        <h4 class="mb-2" style="font-size: 13px; text-transform: uppercase; letter-spacing: 0.5px; color: var(--tblr-secondary)">
+                          Managed Agents (<span x-text="orch.managedAgents.length"></span>)
+                        </h4>
+                        <div class="list-group list-group-flush">
+                          <template x-for="agent in orch.managedAgents" :key="agent.tmuxSession">
+                            <div class="list-group-item px-0 py-2 d-flex align-items-center gap-2">
+                              <span class="badge" :class="agent.provider === 'claude' ? 'bg-orange-lt' : 'bg-blue-lt'" x-text="agent.provider" style="font-size: 10px"></span>
+                              <span x-text="agent.label || agent.tmuxSession" style="font-size: 13px"></span>
+                              <small class="text-secondary" x-text="agent.cwd" style="font-size: 11px"></small>
+                              <div class="ms-auto d-flex gap-1">
+                                <button class="btn btn-sm btn-ghost-warning p-1" title="Restart"
+                                        @click="orchestratorAction(orch.id, 'restart', agent.agentId || agent.tmuxSession)">
+                                  <i class="ti ti-refresh" style="font-size: 14px"></i>
+                                </button>
+                                <button class="btn btn-sm btn-ghost-danger p-1" title="Shutdown"
+                                        @click="orchestratorAction(orch.id, 'shutdown', agent.agentId || agent.tmuxSession)">
+                                  <i class="ti ti-power" style="font-size: 14px"></i>
+                                </button>
+                              </div>
+                            </div>
+                          </template>
+                        </div>
+                      </div>
+                    </template>
+                    <template x-if="!orch.managedAgents?.length">
+                      <p class="text-secondary mb-0" style="font-size: 13px">No managed agents</p>
+                    </template>
+
+                    <div class="d-flex gap-1 mt-3">
+                      <button class="btn btn-sm btn-primary" @click="openOrchestratorSpawnFor(orch.id)" :disabled="orch.status !== 'online'">
+                        <i class="ti ti-plus me-1"></i>Spawn
+                      </button>
+                      <button class="btn btn-sm btn-ghost-danger" @click="deleteOrchestrator(orch.id)">
+                        <i class="ti ti-trash me-1"></i>Remove
+                      </button>
+                    </div>
+                  </div>
+                  <div class="card-footer text-secondary" style="font-size: 12px">
+                    Last seen: <span x-text="timeAgo(orch.lastSeen)"></span>
+                  </div>
+                </div>
+              </div>
+            </template>
+          </div>
+        </template>
+
+        <template x-if="orchestrators.length === 0">
+          <div class="card">
+            <div class="card-body text-center py-5">
+              <i class="ti ti-server-2 mb-3" style="font-size: 48px; color: var(--tblr-secondary)"></i>
+              <h3>No orchestrators registered</h3>
+              <p class="text-secondary">Install and start <code>agent-relay-orchestrator</code> on each host to enable remote agent spawning.</p>
+              <pre class="text-start mx-auto" style="max-width: 500px; font-size: 12px">npm install -g agent-relay-orchestrator
+agent-relay-orchestrator init
+agent-relay-orchestrator</pre>
+            </div>
+          </div>
+        </template>
+      </div>
+
+      <!-- Orchestrator Spawn Modal -->
+      <div class="modal" :class="{ show: orchestratorSpawnOpen }" tabindex="-1" :style="orchestratorSpawnOpen ? 'display:block' : 'display:none'" @click.self="orchestratorSpawnOpen = false">
+        <div class="modal-dialog modal-dialog-centered">
+          <div class="modal-content">
+            <div class="modal-header">
+              <h5 class="modal-title">Spawn Agent</h5>
+              <button type="button" class="btn-close" @click="orchestratorSpawnOpen = false"></button>
+            </div>
+            <div class="modal-body">
+              <div class="mb-3">
+                <label class="form-label">Orchestrator</label>
+                <select class="form-select" x-model="spawnOrchId">
+                  <template x-for="orch in orchestrators.filter(o => o.status === 'online')" :key="orch.id">
+                    <option :value="orch.id" x-text="orch.hostname + ' (' + orch.providers.join(', ') + ')'"></option>
+                  </template>
+                </select>
+              </div>
+              <div class="mb-3">
+                <label class="form-label">Provider</label>
+                <select class="form-select" x-model="spawnProvider">
+                  <template x-for="p in spawnAvailableProviders" :key="p">
+                    <option :value="p" x-text="p"></option>
+                  </template>
+                </select>
+              </div>
+              <div class="mb-3">
+                <label class="form-label">Working Directory</label>
+                <div class="input-group">
+                  <input type="text" class="form-control" x-model="spawnCwd" placeholder="Leave empty for base directory">
+                  <button class="btn btn-outline-secondary" @click="browseOrchestratorDirs()" type="button">
+                    <i class="ti ti-folder"></i>
+                  </button>
+                </div>
+                <template x-if="spawnDirListing">
+                  <div class="border rounded mt-2 p-2" style="max-height: 200px; overflow-y: auto; font-size: 13px">
+                    <template x-if="spawnDirListing.parent">
+                      <a href="#" class="d-block py-1 text-secondary" @click.prevent="spawnCwd = spawnDirListing.parent; browseOrchestratorDirs()">
+                        <i class="ti ti-arrow-up me-1"></i>..
+                      </a>
+                    </template>
+                    <template x-for="entry in spawnDirListing.entries" :key="entry.path">
+                      <a href="#" class="d-block py-1" @click.prevent="spawnCwd = entry.path; browseOrchestratorDirs()">
+                        <i class="ti ti-folder me-1"></i><span x-text="entry.name"></span>
+                      </a>
+                    </template>
+                  </div>
+                </template>
+              </div>
+              <div class="mb-3">
+                <label class="form-label">Label</label>
+                <input type="text" class="form-control" x-model="spawnLabel" placeholder="e.g. backend, reviewer">
+              </div>
+              <div class="mb-3">
+                <label class="form-label">Approval Mode</label>
+                <select class="form-select" x-model="spawnApproval">
+                  <option value="guarded">Guarded (block destructive ops)</option>
+                  <option value="open">Open (no restrictions)</option>
+                  <option value="read-only">Read-only (observe only)</option>
+                </select>
+              </div>
+              <template x-if="spawnProvider === 'claude'">
+                <div class="mb-3">
+                  <label class="form-label">Initial Prompt</label>
+                  <textarea class="form-control" x-model="spawnPrompt" rows="3" placeholder="You are a headless relay agent..."></textarea>
+                </div>
+              </template>
+            </div>
+            <div class="modal-footer">
+              <button class="btn btn-secondary" @click="orchestratorSpawnOpen = false">Cancel</button>
+              <button class="btn btn-primary" @click="submitOrchestratorSpawn()">
+                <i class="ti ti-rocket me-1"></i>Spawn
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="modal-backdrop fade show" x-show="orchestratorSpawnOpen" x-cloak></div>
+
       <!-- ==================== CHANNELS ==================== -->
       <div x-show="view === 'channels'" x-cloak class="fade-in">
         <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">

package/src/db.ts

@@ -9,15 +9,21 @@ import type {
   CreatePairInput,
   HealthCheck,
   HealthReport,
+  ManagedAgent,
   Message,
   MessageType,
+  Orchestrator,
+  OrchestratorStatus,
   PairActionInput,
   PairMessageInput,
   PairSession,
   PairStatus,
   RegisterAgentInput,
+  RegisterOrchestratorInput,
   SendMessageInput,
   PollQuery,
+  SpawnApprovalMode,
+  SpawnProvider,
   Task,
   TaskEvent,
   TaskSeverity,
@@ -192,6 +198,20 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_activity_operator ON activity_events(operator_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_activity_created ON activity_events(created_at);
+
+    CREATE TABLE IF NOT EXISTS orchestrators (
+      id TEXT PRIMARY KEY,
+      hostname TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'online',
+      agent_id TEXT NOT NULL,
+      providers TEXT NOT NULL DEFAULT '[]',
+      base_dir TEXT NOT NULL,
+      env_keys TEXT NOT NULL DEFAULT '[]',
+      meta TEXT NOT NULL DEFAULT '{}',
+      managed_agents TEXT NOT NULL DEFAULT '[]',
+      last_seen INTEGER NOT NULL,
+      created_at INTEGER NOT NULL
+    );
   `);
 
   // Migrations
@@ -1866,3 +1886,114 @@ export function getHealth(now: number = Date.now()): HealthReport {
       : "ok";
   return { status, version: VERSION, generatedAt: now, checks };
 }
+
+// --- Orchestrators ---
+
+function rowToOrchestrator(row: any): Orchestrator {
+  return {
+    id: row.id,
+    hostname: row.hostname,
+    status: row.status as OrchestratorStatus,
+    agentId: row.agent_id,
+    providers: parseJson<SpawnProvider[]>(row.providers, []),
+    baseDir: row.base_dir,
+    envKeys: parseJson<string[]>(row.env_keys, []),
+    meta: parseJson(row.meta, {}),
+    managedAgents: parseJson<ManagedAgent[]>(row.managed_agents, []),
+    lastSeen: row.last_seen,
+    createdAt: row.created_at,
+  };
+}
+
+export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrator {
+  const now = Date.now();
+  const agentId = `orchestrator-${input.id}`;
+  const stmt = db.prepare(`
+    INSERT INTO orchestrators (id, hostname, status, agent_id, providers, base_dir, env_keys, meta, last_seen, created_at)
+    VALUES ($id, $hostname, 'online', $agentId, $providers, $baseDir, $envKeys, $meta, $now, $now)
+    ON CONFLICT(id) DO UPDATE SET
+      hostname = $hostname,
+      status = 'online',
+      providers = $providers,
+      base_dir = $baseDir,
+      env_keys = $envKeys,
+      meta = $meta,
+      last_seen = $now
+  `);
+  stmt.run({
+    $id: input.id,
+    $hostname: input.hostname,
+    $agentId: agentId,
+    $providers: JSON.stringify(input.providers),
+    $baseDir: input.baseDir,
+    $envKeys: JSON.stringify(input.envKeys ?? []),
+    $meta: JSON.stringify(input.meta ?? {}),
+    $now: now,
+  });
+
+  // Also register as an agent so the orchestrator can receive messages
+  upsertAgent({
+    id: agentId,
+    name: `Orchestrator (${input.hostname})`,
+    tags: ["orchestrator", input.hostname],
+    machine: input.hostname,
+    capabilities: ["orchestrator", "spawn"],
+    status: "online",
+    meta: { orchestratorId: input.id, builtin: true },
+  });
+
+  return getOrchestrator(input.id)!;
+}
+
+export function getOrchestrator(id: string): Orchestrator | null {
+  const row = db.prepare("SELECT * FROM orchestrators WHERE id = ?").get(id) as any;
+  return row ? rowToOrchestrator(row) : null;
+}
+
+export function listOrchestrators(): Orchestrator[] {
+  return (db.prepare("SELECT * FROM orchestrators ORDER BY hostname").all() as any[]).map(rowToOrchestrator);
+}
+
+export function orchestratorHeartbeat(id: string): Orchestrator | null {
+  const now = Date.now();
+  db.prepare("UPDATE orchestrators SET last_seen = ?, status = 'online' WHERE id = ?").run(now, id);
+  // Also heartbeat the agent
+  const orch = getOrchestrator(id);
+  if (orch) {
+    heartbeat(orch.agentId);
+  }
+  return orch;
+}
+
+export function setOrchestratorStatus(id: string, status: OrchestratorStatus): Orchestrator | null {
+  db.prepare("UPDATE orchestrators SET status = ?, last_seen = ? WHERE id = ?").run(status, Date.now(), id);
+  const orch = getOrchestrator(id);
+  if (orch) {
+    setStatus(orch.agentId, status === "online" ? "online" : "offline");
+  }
+  return orch;
+}
+
+export function updateManagedAgents(id: string, agents: ManagedAgent[]): Orchestrator | null {
+  db.prepare("UPDATE orchestrators SET managed_agents = ?, last_seen = ? WHERE id = ?")
+    .run(JSON.stringify(agents), Date.now(), id);
+  return getOrchestrator(id);
+}
+
+export function deleteOrchestrator(id: string): boolean {
+  const orch = getOrchestrator(id);
+  if (!orch) return false;
+  db.prepare("DELETE FROM orchestrators WHERE id = ?").run(id);
+  deleteAgent(orch.agentId);
+  return true;
+}
+
+export function reapStaleOrchestrators(): string[] {
+  const cutoff = Date.now() - STALE_TTL_MS;
+  const stale = db.prepare("SELECT id, agent_id FROM orchestrators WHERE last_seen < ? AND status = 'online'").all(cutoff) as any[];
+  for (const row of stale) {
+    db.prepare("UPDATE orchestrators SET status = 'offline' WHERE id = ?").run(row.id);
+    setStatus(row.agent_id, "offline");
+  }
+  return stale.map((row: any) => row.id);
+}

package/src/routes.ts

@@ -46,11 +46,18 @@ import {
   createCallbackDelivery,
   finishCallbackDelivery,
   reapStaleAgents,
+  reapStaleOrchestrators,
   releaseExpiredClaims,
   validateAgentSession,
+  upsertOrchestrator,
+  getOrchestrator,
+  listOrchestrators,
+  orchestratorHeartbeat,
+  updateManagedAgents,
+  deleteOrchestrator,
   ValidationError,
 } from "./db";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
 import { listHostDirectories, spawnCodexAgent, type CodexSpawnApprovalMode } from "./agent-spawn";
 import {
@@ -67,6 +74,8 @@ import {
   emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
+  emitOrchestratorStatus,
+  emitOrchestratorRemoved,
 } from "./sse";
 
 type Handler = (
@@ -804,11 +813,47 @@ const postAgentSpawn: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_AGENT_SPAWN_PROVIDERS);
-    if (provider !== "codex") return error("provider must be codex");
+    const provider = cleanEnum(parsed.body.provider, "provider", [...VALID_AGENT_SPAWN_PROVIDERS, "claude"] as const);
+    if (!provider) return error("provider required");
     const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as CodexSpawnApprovalMode;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
     const label = cleanString(parsed.body.label, "label", { max: 120 });
+
+    // Check for an online orchestrator that supports this provider
+    const orchestrators = listOrchestrators().filter(
+      (o) => o.status === "online" && o.providers.includes(provider as SpawnProvider),
+    );
+    if (orchestrators.length > 0) {
+      // Route through the first available orchestrator
+      const orch = orchestrators[0]!;
+      const msg = sendMessage({
+        from: "system",
+        to: orch.agentId,
+        type: "system",
+        subject: "Spawn agent",
+        body: JSON.stringify({ action: "spawn", provider, cwd, label, approvalMode }),
+        meta: {
+          orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() },
+          delivery: "interrupt",
+          priority: "urgent",
+        },
+      });
+      emitNewMessage(msg);
+      auditEvent({
+        clientId: "server-agent-spawn-" + provider + "-" + Date.now(),
+        kind: "state",
+        title: `${provider} agent spawn requested (via ${orch.id})`,
+        body: cwd || orch.baseDir,
+        meta: orch.id,
+        icon: "ti-plus",
+        view: "agents",
+        metadata: { provider, orchestratorId: orch.id, approvalMode },
+      });
+      return json({ ok: true, orchestratorId: orch.id, provider, message: msg }, 202);
+    }
+
+    // Fallback: direct spawn for codex only (no orchestrator)
+    if (provider !== "codex") return error("no orchestrator available for provider: " + provider);
     const relayUrl = process.env.AGENT_RELAY_SPAWN_RELAY_URL || process.env.AGENT_RELAY_URL || `http://127.0.0.1:${process.env.PORT || "4850"}`;
     const token = req.headers.get("X-Agent-Relay-Token") ?? req.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
     const result = spawnCodexAgent({
@@ -822,7 +867,7 @@ const postAgentSpawn: Handler = async (req) => {
     auditEvent({
       clientId: "server-agent-spawn-codex-" + Date.now(),
       kind: "state",
-      title: "Codex agent spawn requested",
+      title: "Codex agent spawn requested (direct)",
       body: result.cwd,
       meta: result.pid ? `pid ${result.pid}` : "dry run",
       icon: "ti-plus",
@@ -855,6 +900,207 @@ const getHostDirectories: Handler = (req) => {
   }
 };
 
+// --- Orchestrator routes ---
+
+const VALID_ORCHESTRATOR_PROVIDERS = ["claude", "codex"] as const;
+const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
+
+const postOrchestrator: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
+    const hostname = cleanString(parsed.body.hostname, "hostname", { required: true, max: 120 })!;
+    const baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
+    const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
+    if (providers) {
+      for (const p of providers) {
+        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
+          return error(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        }
+      }
+    }
+    const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys");
+    const meta = cleanMeta(parsed.body.meta);
+    const orch = upsertOrchestrator({ id, hostname, providers: providers ?? ["claude", "codex"], baseDir, envKeys, meta });
+    auditEvent({
+      clientId: "server-orchestrator-register-" + id + "-" + Date.now(),
+      kind: "state",
+      title: "Orchestrator registered",
+      body: hostname,
+      meta: id,
+      icon: "ti-server-2",
+      view: "orchestrators",
+      metadata: { orchestratorId: id, providers: orch.providers },
+    });
+    return json(orch, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getOrchestrators: Handler = () => {
+  return json(listOrchestrators());
+};
+
+const getOrchestratorById: Handler = (_req, params) => {
+  const orch = getOrchestrator(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json(orch);
+};
+
+const postOrchestratorHeartbeat: Handler = (_req, params) => {
+  const orch = orchestratorHeartbeat(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
+const patchOrchestratorAgents: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (!isRecord(parsed.body)) return error("body required");
+    const agents = parsed.body.agents;
+    if (!Array.isArray(agents)) return error("agents must be an array");
+    const cleaned: ManagedAgent[] = agents.map((a: any) => {
+      if (!isRecord(a)) throw new ValidationError("each agent must be an object");
+      return {
+        agentId: cleanString(a.agentId, "agentId", { required: true, max: 240 })!,
+        provider: cleanEnum(a.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider,
+        tmuxSession: cleanString(a.tmuxSession, "tmuxSession", { required: true, max: 240 })!,
+        cwd: cleanString(a.cwd, "cwd", { required: true, max: 500 })!,
+        label: cleanString(a.label, "label", { max: 120 }),
+        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") ?? "guarded") as SpawnApprovalMode,
+        pid: typeof a.pid === "number" && Number.isSafeInteger(a.pid) ? a.pid : undefined,
+        startedAt: typeof a.startedAt === "number" ? a.startedAt : Date.now(),
+      };
+    });
+    const updated = updateManagedAgents(params.id!, cleaned);
+    return json(updated);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postOrchestratorSpawn: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (orch.status !== "online") return error("orchestrator is offline", 409);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    if (!orch.providers.includes(provider)) {
+      return error(`orchestrator does not support provider: ${provider}`);
+    }
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    if (cwd && !cwd.startsWith(orch.baseDir)) {
+      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
+    }
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const prompt = cleanString(parsed.body.prompt, "prompt", { max: 4000 });
+
+    // Send control message to orchestrator's agent inbox
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      type: "system",
+      subject: "Spawn agent",
+      body: JSON.stringify({ action: "spawn", provider, cwd: cwd || orch.baseDir, label, approvalMode, prompt }),
+      meta: {
+        orchestratorControl: {
+          action: "spawn",
+          provider,
+          cwd: cwd || orch.baseDir,
+          label,
+          approvalMode,
+          prompt,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-spawn-" + orch.id + "-" + Date.now(),
+      kind: "state",
+      title: `Spawn ${provider} agent requested`,
+      body: cwd || orch.baseDir,
+      meta: orch.id,
+      icon: "ti-plus",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, provider, approvalMode, label },
+    });
+    return json({ ok: true, orchestratorId: orch.id, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postOrchestratorAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown"] as const);
+    if (!action) return error("action required");
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      type: "system",
+      subject: action === "restart" ? "Restart agent" : "Shutdown agent",
+      body: JSON.stringify({ action, agentId }),
+      meta: {
+        orchestratorControl: {
+          action,
+          agentId,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-action-" + orch.id + "-" + action + "-" + Date.now(),
+      kind: "state",
+      title: `Agent ${action} requested`,
+      body: agentId || "all",
+      meta: orch.id,
+      icon: action === "restart" ? "ti-refresh" : "ti-power",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, action, agentId },
+    });
+    return json({ ok: true, action, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteOrchestratorById: Handler = (_req, params) => {
+  const deleted = deleteOrchestrator(params.id!);
+  if (!deleted) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
 // --- Message routes ---
 
 const VALID_MSG_TYPES = ["message", "system"];
@@ -1486,20 +1732,23 @@ const getHealthRoute: Handler = () => json(getHealth());
 const postSystemReap: Handler = () => {
   const released = releaseExpiredClaims();
   const reapedAgentIds = reapStaleAgents();
+  const reapedOrchestratorIds = reapStaleOrchestrators();
   for (const id of released.messageIds) emitMessageClaimReleased(id);
   for (const task of released.tasks) emitTaskChanged(task, "task.updated");
   for (const id of reapedAgentIds) emitAgentStatus(id);
+  for (const id of reapedOrchestratorIds) emitOrchestratorStatus(id);
   auditEvent({
     clientId: "server-system-reap-" + Date.now(),
     kind: "state",
     title: "Maintenance reaper run",
-    body: `${reapedAgentIds.length} stale agent(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
+    body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
     icon: "ti-broom",
     view: "activity",
   });
   return json({
     ok: true,
     reapedAgentIds,
+    reapedOrchestratorIds,
     releasedMessageIds: released.messageIds,
     releasedTaskIds: released.tasks.map((task) => task.id),
   });
@@ -1542,6 +1791,15 @@ const routes: Route[] = [
   route("POST", "/api/agents/:id/actions", postAgentAction),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
+  route("POST", "/api/orchestrators", postOrchestrator),
+  route("GET", "/api/orchestrators", getOrchestrators),
+  route("GET", "/api/orchestrators/:id", getOrchestratorById),
+  route("POST", "/api/orchestrators/:id/heartbeat", postOrchestratorHeartbeat),
+  route("PATCH", "/api/orchestrators/:id/agents", patchOrchestratorAgents),
+  route("POST", "/api/orchestrators/:id/spawn", postOrchestratorSpawn),
+  route("POST", "/api/orchestrators/:id/actions", postOrchestratorAction),
+  route("DELETE", "/api/orchestrators/:id", deleteOrchestratorById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("POST", "/api/messages", postMessage),
   route("GET", "/api/messages", getMessages),

package/src/sse.ts

@@ -1,4 +1,4 @@
-import { getAgent } from "./db";
+import { getAgent, getOrchestrator } from "./db";
 import type { Message, Task } from "./types";
 
 interface Connection {
@@ -135,3 +135,17 @@ function targetMatchesAgent(target: string, agentId: string): boolean {
   if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
   return false;
 }
+
+export function emitOrchestratorStatus(orchestratorId: string) {
+  const orch = getOrchestrator(orchestratorId);
+  const data = orch ?? { id: orchestratorId, status: "offline" };
+  for (const conn of connections.values()) {
+    send(conn, "orchestrator.status", data);
+  }
+}
+
+export function emitOrchestratorRemoved(orchestratorId: string) {
+  for (const conn of connections.values()) {
+    send(conn, "orchestrator.removed", { id: orchestratorId });
+  }
+}

package/src/types.ts

@@ -291,6 +291,66 @@ export interface ActivityEventInput {
   metadata?: Record<string, unknown>;
 }
 
+// --- Orchestrators ---
+
+export type OrchestratorStatus = "online" | "offline";
+export type SpawnProvider = "claude" | "codex";
+export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+
+export interface Orchestrator {
+  id: string;
+  hostname: string;
+  status: OrchestratorStatus;
+  agentId: string; // relay agent id for messaging
+  providers: SpawnProvider[];
+  baseDir: string;
+  envKeys: string[]; // names only, never values
+  meta: Record<string, unknown>;
+  managedAgents: ManagedAgent[];
+  lastSeen: number;
+  createdAt: number;
+}
+
+export interface ManagedAgent {
+  agentId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
+export interface RegisterOrchestratorInput {
+  id: string;
+  hostname: string;
+  providers: SpawnProvider[];
+  baseDir: string;
+  envKeys?: string[];
+  meta?: Record<string, unknown>;
+}
+
+export interface OrchestratorSpawnInput {
+  provider: SpawnProvider;
+  cwd?: string;
+  label?: string;
+  approvalMode?: SpawnApprovalMode;
+  prompt?: string;
+  env?: Record<string, string>;
+}
+
+export interface OrchestratorSpawnResult {
+  orchestratorId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
 export interface HealthCheck {
   name: string;
   status: "ok" | "warn" | "error";