agent-relay-server 0.6.0 → 0.7.0

package/public/dashboard/utils.js

@@ -0,0 +1,207 @@
+import { HUMAN_AGENT_ID, AGENT_TYPE_ICONS, AGENT_TYPE_TITLES, WAITING_TASK_STATUSES } from "./constants.js";
+
+export function indexAgents(agents) {
+  const byId = {};
+  for (const agent of agents) byId[agent.id] = agent;
+  return byId;
+}
+
+export function upsertById(list, item) {
+  const idx = list.findIndex((existing) => existing.id === item.id);
+  if (idx >= 0) list.splice(idx, 1, item);
+  else list.push(item);
+}
+
+export function toTimestamp(value) {
+  const ts = typeof value === "number" ? value : new Date(value || 0).getTime();
+  return Number.isFinite(ts) ? ts : 0;
+}
+
+export function isBuiltInAgent(agent) {
+  return agent?.meta?.builtin === true || agent?.id === HUMAN_AGENT_ID || agent?.id === "system";
+}
+
+export function isChannelAgent(agent) {
+  return agent?.kind === "channel" || agent?.meta?.kind === "channel" || agent?.tags?.includes("channel");
+}
+
+export function agentType(agent) {
+  if (agent?.id === HUMAN_AGENT_ID) return "user";
+  if (agent?.id === "system") return "system";
+  if (isChannelAgent(agent)) return "channel";
+
+  const values = [
+    ...(agent?.tags || []),
+    agent?.meta?.provider,
+    agent?.meta?.client,
+    agent?.meta?.runtime,
+    agent?.meta?.agentType,
+    agent?.id,
+    agent?.name,
+  ]
+    .filter((value) => typeof value === "string")
+    .map((value) => value.toLowerCase());
+
+  if (values.some((value) => value.includes("codex"))) return "codex";
+  if (values.some((value) => value.includes("claude"))) return "claude";
+  return "agent";
+}
+
+export function agentTypeIcon(agent) {
+  return AGENT_TYPE_ICONS[agentType(agent)] || AGENT_TYPE_ICONS.agent;
+}
+
+export function agentTypeTitle(agent) {
+  return AGENT_TYPE_TITLES[agentType(agent)] || AGENT_TYPE_TITLES.agent;
+}
+
+export function isAgentStale(vm, agent) {
+  if (!agent?.lastSeen || agent.status === "offline") return false;
+  if (agent.id === "user" || agent.id === "system") return false;
+  const lastSeenMs = new Date(agent.lastSeen).getTime();
+  if (!Number.isFinite(lastSeenMs)) return false;
+  return (vm.now || Date.now()) - lastSeenMs > 60_000;
+}
+
+export function agentSupportsControlActions(agent) {
+  return Boolean(agent && !isBuiltInAgent(agent) && !isChannelAgent(agent));
+}
+
+export function visibleAgents(vm) {
+  const nonChannelAgents = vm.agents.filter((agent) => !isChannelAgent(agent));
+  return vm.showBuiltIns ? nonChannelAgents : nonChannelAgents.filter((agent) => !isBuiltInAgent(agent));
+}
+
+export function messageBody(msg) {
+  if (!msg) return "";
+  const payload = msg.payload || {};
+  const channelMessage = payload.message;
+  if (channelMessage && typeof channelMessage === "object" && typeof channelMessage.text === "string" && channelMessage.text.trim()) {
+    return channelMessage.text;
+  }
+  const interaction = payload.interaction;
+  if (interaction && typeof interaction === "object") {
+    const title = typeof interaction.title === "string" ? interaction.title.trim() : "";
+    const description = typeof interaction.description === "string" ? interaction.description.trim() : "";
+    if (title && description) return title + "\n" + description;
+    if (title) return title;
+    if (description) return description;
+  }
+  const reaction = payload.reaction;
+  if (reaction && typeof reaction === "object") {
+    const name = typeof reaction.name === "string" ? reaction.name : "";
+    const emoji = typeof reaction.emoji === "string" ? reaction.emoji : "";
+    const value = typeof reaction.value === "string" ? reaction.value : "";
+    return ["Reaction", emoji || name || value].filter(Boolean).join(": ");
+  }
+  const activity = payload.activity;
+  if (activity && typeof activity === "object") {
+    const kind = typeof activity.kind === "string" ? activity.kind : "activity";
+    const state = typeof activity.state === "string" ? activity.state : "";
+    return [kind, state].filter(Boolean).join(" ");
+  }
+  if (typeof payload.text === "string" && payload.text.trim()) return payload.text;
+  if (typeof payload.message === "string" && payload.message.trim()) return payload.message;
+  return msg.body || "";
+}
+
+export function messageLooksLikeQuestion(msg) {
+  return /\?/.test(`${msg.subject || ""}\n${messageBody(msg)}`);
+}
+
+export function inboxPeer(msg) {
+  if (msg.from === HUMAN_AGENT_ID && msg.to) return msg.to;
+  if (msg.to === HUMAN_AGENT_ID && msg.from) return msg.from;
+  return "";
+}
+
+export function isHumanInboundMessage(msg) {
+  return msg.to === HUMAN_AGENT_ID && msg.from !== HUMAN_AGENT_ID;
+}
+
+export function isUnreadHumanMessage(vm, peer, msg) {
+  if (!isHumanInboundMessage(msg)) return false;
+  if ((msg.readBy || []).includes(HUMAN_AGENT_ID)) return false;
+  return msg.id > readCursorForPeer(vm, peer);
+}
+
+export function maxMessageId(messages, predicate) {
+  let max = 0;
+  for (const msg of messages) {
+    if (predicate(msg) && msg.id > max) max = msg.id;
+  }
+  return max;
+}
+
+export function readCursorForPeer(vm, peer) {
+  const value = Number(vm.inboxReadCursors?.[peer] || 0);
+  return Number.isFinite(value) ? value : 0;
+}
+
+export function draftForPeer(vm, peer) {
+  return typeof vm.inboxDrafts?.[peer] === "string" ? vm.inboxDrafts[peer] : "";
+}
+
+export function isClaimableTaskWaiting(task) {
+  return WAITING_TASK_STATUSES.has(task.status) && !task.claimedBy;
+}
+
+export function isClaimableMessageWaiting(msg) {
+  return Boolean(msg.claimable && !msg.claimedBy && !(msg.kind === "task" && Number.isSafeInteger(msg.payload?.taskId)));
+}
+
+export function targetMatchesAgent(target, agent) {
+  if (!target || !agent) return false;
+  if (target === "broadcast" || target === agent.id) return true;
+  if (target.startsWith("tag:")) return (agent.tags || []).includes(target.slice(4));
+  if (target.startsWith("cap:")) return (agent.capabilities || []).includes(target.slice(4));
+  if (target.startsWith("label:")) return agent.label === target.slice(6);
+  return false;
+}
+
+export function messageMatchesChannel(message, channel) {
+  if (!message || !channel) return false;
+  const channelKeys = [channel.id, channel.type, ...(channel.topicChannels || [])].filter(Boolean);
+  if (message.channel && channelKeys.includes(message.channel)) return true;
+  const payloadChannel = message.payload?.channel;
+  if (payloadChannel && typeof payloadChannel === "object") {
+    const payloadKeys = [payloadChannel.agentId, payloadChannel.provider, payloadChannel.accountId].filter(Boolean);
+    if (payloadKeys.includes(channel.id) || payloadKeys.includes(channel.type) || payloadKeys.includes(channel.accountId)) return true;
+  }
+  if (channel.agentId && (message.from === channel.agentId || message.to === channel.agentId)) return true;
+  return false;
+}
+
+export function activityItem(input) {
+  return {
+    id: input.id,
+    kind: input.kind || "state",
+    ts: Number(input.ts) || 0,
+    icon: input.icon || "ti-activity",
+    title: input.title || "Activity",
+    body: input.body || "",
+    meta: input.meta || "",
+    view: input.view || "",
+    peer: input.peer || "",
+    clientId: input.clientId || "",
+    messageId: input.messageId,
+    pairId: input.pairId,
+    taskId: input.taskId,
+    agentId: input.agentId,
+  };
+}
+
+export function emptyAttention() {
+  return {
+    unread: 0,
+    agentQuestion: false,
+    pendingPairInvite: false,
+    claimableTasks: 0,
+    total: 0,
+    score: 0,
+  };
+}
+
+export function safeFilename(value) {
+  return String(value || "export").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "export";
+}

package/public/index.html

@@ -34,8 +34,6 @@
 
   .ar-main { height: 100vh; }
 
-  .view-fit { display: flex; flex-direction: column; height: calc(100vh - 2rem); }
-
   .status-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; flex-shrink: 0; }
   .status-dot.online { background: var(--tblr-success); box-shadow: 0 0 6px var(--tblr-success); }
   .status-dot.online.not-ready { animation: pulse-dot 1.5s ease-in-out infinite; }
@@ -183,7 +181,7 @@
   .fade-in { animation: fadeIn 0.2s ease-in; }
   @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
 
-  .stat-card .ti { font-size: 32px; opacity: 0.3; }
+  i.stat-card { font-size: 32px; opacity: 0.3; }
 
   @media (max-width: 768px) {
     .ar-sidebar { display: none; }
@@ -219,13 +217,11 @@
       </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>
+        <span class="badge bg-success text-white ms-auto" x-show="onlineOrchestratorCount > 0" x-text="onlineOrchestratorCount"></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>
+        <span class="badge bg-success text-white ms-auto" x-show="readyChannelCount > 0" x-text="readyChannelCount"></span>
       </a>
       <a href="#" class="nav-link" :class="{ active: view === 'connectors' }" @click.prevent="switchView('connectors')">
         <i class="ti ti-plug"></i>Connectors
@@ -297,34 +293,34 @@
           <span class="form-check-label small">Auto refresh</span>
         </label>
       </div>
-	    <div class="text-muted small" x-show="stats.version" x-text="'v' + stats.version"></div>
-	  </div>
-	</aside>
+      <div class="text-muted small" x-show="stats.version" x-text="'v' + stats.version"></div>
+    </div>
+  </aside>
 
   <!-- Mobile nav -->
   <div class="mobile-nav d-none border-bottom p-2 gap-1 position-fixed top-0 w-100 bg-dark" style="z-index:50">
-    <template x-for="v in ['overview','agents','channels','connectors','integrations','inbox','activity','pairs','messages','work','tasks','analytics']">
+    <template x-for="v in ['overview','agents','orchestrators','channels','connectors','integrations','inbox','activity','pairs','messages','work','tasks','analytics']">
       <button class="btn btn-sm" :class="view === v ? 'btn-primary' : 'btn-ghost-secondary'" @click="switchView(v)" x-text="v.charAt(0).toUpperCase() + v.slice(1)"></button>
     </template>
   </div>
 
   <!-- Main content -->
-	  <main class="ar-main flex-grow-1 overflow-auto">
-	    <div class="container-xl py-3">
-	      <template x-if="authNeeded">
-	        <div class="alert alert-warning d-flex align-items-center gap-2 mb-3">
-	          <i class="ti ti-lock"></i>
-	          <input
-	            type="password"
-	            class="form-control form-control-sm"
-	            style="max-width: 320px"
-	            placeholder="Agent Relay token"
-	            x-model="authToken"
-	            @keydown.enter="saveTokenAndRefresh()"
-	          >
-	          <button class="btn btn-sm btn-warning" @click="saveTokenAndRefresh()">Unlock</button>
-	        </div>
-	      </template>
+  <main class="ar-main flex-grow-1 overflow-auto">
+    <div class="container-xl py-3">
+      <template x-if="authNeeded">
+        <div class="alert alert-warning d-flex align-items-center gap-2 mb-3">
+          <i class="ti ti-lock"></i>
+          <input
+            type="password"
+            class="form-control form-control-sm"
+            style="max-width: 320px"
+            placeholder="Agent Relay token"
+            x-model="authToken"
+            @keydown.enter="saveTokenAndRefresh()"
+          >
+          <button class="btn btn-sm btn-warning" @click="saveTokenAndRefresh()">Unlock</button>
+        </div>
+      </template>
 
       <!-- ==================== OVERVIEW ==================== -->
       <div x-show="view === 'overview'" x-cloak class="fade-in">
@@ -339,8 +335,8 @@
               <div class="card-body">
                 <div class="d-flex align-items-center">
                   <div>
-                    <div class="text-secondary small">Total Agents</div>
-                    <div class="h1 mb-0" x-text="stats.agents ?? 0"></div>
+                    <div class="text-secondary small">Agents</div>
+                    <div class="h1 mb-0" x-text="onlineCount"></div>
                   </div>
                   <i class="ti ti-robot ms-auto stat-card"></i>
                 </div>
@@ -352,10 +348,10 @@
               <div class="card-body">
                 <div class="d-flex align-items-center">
                   <div>
-                    <div class="text-secondary small">Active</div>
-                    <div class="h1 mb-0 text-success" x-text="onlineCount"></div>
+                    <div class="text-secondary small">Busy</div>
+                    <div class="h1 mb-0 text-warning" x-text="busyAgentCount"></div>
                   </div>
-                  <i class="ti ti-circle-check ms-auto stat-card"></i>
+                  <i class="ti ti-activity ms-auto stat-card"></i>
                 </div>
               </div>
             </div>
@@ -366,7 +362,7 @@
                 <div class="d-flex align-items-center">
                   <div>
                     <div class="text-secondary small">Messages (24h)</div>
-	                    <div class="h1 mb-0 text-info" x-text="stats.messagesLast24h ?? 0"></div>
+                    <div class="h1 mb-0 text-info" x-text="stats.messagesLast24h ?? 0"></div>
                   </div>
                   <i class="ti ti-mail ms-auto stat-card"></i>
                 </div>
@@ -679,10 +675,10 @@
       <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>
+          <span class="badge bg-success-lt" x-show="onlineOrchestratorCount > 0"
+                x-text="onlineOrchestratorCount + ' online'"></span>
           <div class="ms-auto">
-            <button class="btn btn-sm btn-primary" @click="openOrchestratorSpawn()" :disabled="orchestrators.filter(o => o.status === 'online').length === 0">
+            <button class="btn btn-sm btn-primary" @click="openOrchestratorSpawn()" :disabled="onlineOrchestratorCount === 0">
               <i class="ti ti-plus me-1"></i>Spawn Agent
             </button>
           </div>
@@ -700,14 +696,30 @@
                         <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 class="ms-auto d-flex align-items-center gap-1">
+                        <span class="badge" :class="orchestratorHealthClass(orch)" x-text="orchestratorHealthLabel(orch)"></span>
+                        <span class="badge" :class="orch.status === 'online' ? 'bg-success' : 'bg-secondary'" x-text="orch.status"></span>
+                      </div>
                     </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>
+                    <div class="d-flex gap-3 mb-3 text-secondary flex-wrap min-width-0" style="font-size: 13px">
+                      <span class="text-truncate"><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>
+                      <span><i class="ti ti-package me-1"></i><span x-text="orch.version || 'unknown'"></span></span>
                     </div>
 
+                    <template x-if="orch.health?.issues?.length">
+                      <div class="alert alert-warning py-2 px-3 mb-3" :class="orch.health.status === 'error' ? 'alert-danger' : 'alert-warning'">
+                        <div class="d-flex align-items-start gap-2">
+                          <i class="ti ti-alert-triangle mt-1"></i>
+                          <div>
+                            <div x-text="orch.health.issues[0].detail"></div>
+                            <small x-show="orch.health.restartRequired">Restart required after upgrade.</small>
+                          </div>
+                        </div>
+                      </div>
+                    </template>
+
                     <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>
@@ -859,6 +871,8 @@ agent-relay-orchestrator</pre>
         <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">
           <h2 class="page-title mb-0">Channels</h2>
           <span class="badge bg-success-lt" x-show="channelCards.filter((item) => item.ready).length > 0" x-text="channelCards.filter((item) => item.ready).length + ' ready'"></span>
+          <span class="badge bg-danger-lt" x-show="channelCards.filter((item) => item.targetHealth?.status === 'error').length > 0" x-text="channelCards.filter((item) => item.targetHealth?.status === 'error').length + ' target issue' + (channelCards.filter((item) => item.targetHealth?.status === 'error').length === 1 ? '' : 's')"></span>
+          <span class="badge bg-warning-lt" x-show="channelCards.filter((item) => item.targetHealth?.status === 'warning').length > 0" x-text="channelCards.filter((item) => item.targetHealth?.status === 'warning').length + ' target warning' + (channelCards.filter((item) => item.targetHealth?.status === 'warning').length === 1 ? '' : 's')"></span>
           <div class="ms-auto d-flex gap-2 align-items-center">
             <button class="btn btn-sm btn-ghost-secondary" @click="fetchChannels()">
               <i class="ti ti-refresh"></i>
@@ -887,6 +901,12 @@ agent-relay-orchestrator</pre>
                         <span class="badge bg-cyan-lt" x-text="channel.direction"></span>
                         <span class="badge bg-secondary-lt" x-text="displayTarget(channel.target || channel.agentId)"></span>
                       </div>
+                      <div class="alert py-2 px-2 mt-2 mb-0"
+                           :class="channel.targetHealth?.status === 'error' ? 'alert-danger' : 'alert-warning'"
+                           x-show="channel.targetHealth && channel.targetHealth.status !== 'ok'">
+                        <i class="ti me-1" :class="channel.targetHealth?.status === 'error' ? 'ti-alert-triangle' : 'ti-alert-circle'"></i>
+                        <span x-text="channel.targetHealth?.detail"></span>
+                      </div>
                       <div class="d-flex gap-1 mt-2 flex-wrap" x-show="channel.capabilities?.length">
                         <template x-for="capability in (channel.capabilities || [])" :key="capability">
                           <span class="badge bg-secondary-lt" x-text="capability"></span>
@@ -1809,7 +1829,7 @@ agent-relay-orchestrator</pre>
       </div>
 
     </div>
-	  </main>
+  </main>
 
   <!-- ==================== COMMAND PALETTE ==================== -->
   <div class="command-palette" x-show="commandPaletteOpen" x-cloak @click.self="closeCommandPalette()">
@@ -2559,8 +2579,8 @@ agent-relay-orchestrator</pre>
 
 <script src="https://cdn.jsdelivr.net/npm/@tabler/core@latest/dist/js/tabler.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/apexcharts@latest/dist/apexcharts.min.js"></script>
+<script type="module" src="dashboard/app.js"></script>
 <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
-<script src="dashboard.js"></script>
 <script>
   if ("serviceWorker" in navigator) {
     window.addEventListener("load", () => {

package/scripts/orchestrator-spawn-smoke.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+type Orchestrator = {
+  id: string;
+  status: string;
+  providers: string[];
+  baseDir: string;
+  managedAgents?: Array<{ label?: string; tmuxSession: string }>;
+};
+
+type Agent = {
+  id: string;
+  label?: string;
+  status: string;
+  ready: boolean;
+  tags?: string[];
+  meta?: { cwd?: string; provider?: string };
+  createdAt?: number;
+};
+
+const args = process.argv.slice(2);
+let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+let orchestratorId = process.env.AGENT_RELAY_SMOKE_ORCHESTRATOR || "";
+let cwd = process.env.AGENT_RELAY_SMOKE_CWD || process.cwd();
+let timeoutMs = Number(process.env.AGENT_RELAY_SMOKE_TIMEOUT_MS || 90_000);
+let providers = (process.env.AGENT_RELAY_SMOKE_PROVIDERS || "codex,claude").split(",").filter(Boolean);
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === "--relay-url" && args[i + 1]) relayUrl = args[++i]!;
+  else if (arg === "--orchestrator" && args[i + 1]) orchestratorId = args[++i]!;
+  else if (arg === "--cwd" && args[i + 1]) cwd = args[++i]!;
+  else if (arg === "--timeout" && args[i + 1]) timeoutMs = Number(args[++i]);
+  else if (arg === "--providers" && args[i + 1]) providers = args[++i]!.split(",").map((p) => p.trim()).filter(Boolean);
+  else throw new Error(`Unknown option: ${arg}`);
+}
+
+relayUrl = relayUrl.replace(/\/+$/, "");
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (process.env.AGENT_RELAY_TOKEN) h["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+  return h;
+}
+
+async function api<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const res = await fetch(`${relayUrl}/api${path}`, {
+    method,
+    headers: headers(),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`${method} ${path} failed: ${res.status} ${await res.text()}`);
+  return await res.json() as T;
+}
+
+async function apiOptional<T>(method: string, path: string, body?: unknown): Promise<T | null> {
+  const res = await fetch(`${relayUrl}/api${path}`, {
+    method,
+    headers: headers(),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`${method} ${path} failed: ${res.status} ${await res.text()}`);
+  if (res.status === 204) return null;
+  return await res.json() as T;
+}
+
+async function waitFor<T>(label: string, fn: () => Promise<T | null>): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await fn();
+    if (result) return result;
+    await new Promise((resolve) => setTimeout(resolve, 2_000));
+  }
+  throw new Error(`${label} timed out after ${timeoutMs}ms`);
+}
+
+function findSpawnedAgent(agents: Agent[], provider: string, label: string, startedAt: number): Agent | null {
+  return agents
+    .filter((agent) => agent.ready && agent.status !== "offline")
+    .filter((agent) => agent.label === label)
+    .filter((agent) => agent.meta?.cwd === cwd)
+    .filter((agent) => (agent.tags || []).includes(provider))
+    .filter((agent) => (agent.tags || []).includes("dashboard-spawned"))
+    .filter((agent) => !agent.createdAt || agent.createdAt >= startedAt - 5_000)
+    .sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0))[0] || null;
+}
+
+const orchestrators = await api<Orchestrator[]>("GET", "/orchestrators");
+const orchestrator = orchestratorId
+  ? orchestrators.find((orch) => orch.id === orchestratorId)
+  : orchestrators.find((orch) => orch.status === "online");
+if (!orchestrator) throw new Error(orchestratorId ? `orchestrator not found: ${orchestratorId}` : "no online orchestrator found");
+if (orchestrator.status !== "online") throw new Error(`orchestrator ${orchestrator.id} is ${orchestrator.status}`);
+
+for (const provider of providers) {
+  if (!orchestrator.providers.includes(provider)) {
+    console.log(`skip ${provider}: orchestrator ${orchestrator.id} does not support it`);
+    continue;
+  }
+
+  const label = `smoke-${provider}-${Date.now()}`;
+  const startedAt = Date.now();
+  console.log(`spawn ${provider} via ${orchestrator.id}`);
+  await api("POST", `/orchestrators/${encodeURIComponent(orchestrator.id)}/spawn`, {
+    provider,
+    cwd,
+    label,
+    approvalMode: "guarded",
+    ...(provider === "claude" ? { prompt: "Agent Relay spawn smoke. Register with relay and wait for shutdown." } : {}),
+  });
+
+  const agent = await waitFor(`waiting for ${provider} agent registration`, async () => {
+    const agents = await api<Agent[]>("GET", "/agents");
+    return findSpawnedAgent(agents, provider, label, startedAt);
+  });
+  console.log(`registered ${provider}: ${agent.id}`);
+
+  const managed = await waitFor(`waiting for ${provider} managed session`, async () => {
+    const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
+    return latest?.managedAgents?.find((entry) => entry.label === label || entry.tmuxSession.includes(label)) || null;
+  });
+
+  await api("POST", `/orchestrators/${encodeURIComponent(orchestrator.id)}/actions`, {
+    action: "shutdown",
+    agentId: managed.tmuxSession,
+  });
+
+  await waitFor(`waiting for ${provider} managed session shutdown`, async () => {
+    const latest = (await api<Orchestrator[]>("GET", "/orchestrators")).find((orch) => orch.id === orchestrator.id);
+    const stillManaged = latest?.managedAgents?.some((managed) => managed.label === label || managed.tmuxSession.includes(label));
+    return stillManaged ? null : true;
+  });
+  await waitFor(`waiting for ${provider} agent cleanup`, async () => {
+    const current = await apiOptional<Agent>("GET", `/agents/${encodeURIComponent(agent.id)}`);
+    return current ? null : true;
+  });
+  console.log(`shutdown ${provider}: ${label}`);
+}
+
+console.log("spawn smoke passed");

package/src/cli.ts

@@ -31,7 +31,7 @@ agent-relay ${VERSION}
 Usage:
   agent-relay [start]
   agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
-  agent-relay upgrade [--dry-run] [--version VERSION] [--providers auto|all|codex|claude] [--no-restart] [--yes]
+  agent-relay upgrade [--dry-run] [--version VERSION] [--providers auto|all|codex|claude|orchestrator] [--no-restart] [--yes]
   agent-relay setup upgrade [same options as upgrade]
   agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
@@ -74,7 +74,7 @@ Daemon options:
 
 Upgrade options:
   --version VERSION Target version (default: latest published server version)
-  --providers LIST  Provider integrations to upgrade: auto, all, codex, claude
+  --providers LIST  Provider integrations to upgrade: auto, all, codex, claude, orchestrator
   --no-restart      Do not restart agent-relay.service
   --dry-run         Print detected state and planned commands
   --yes             Skip confirmation prompts
@@ -158,6 +158,7 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
     } else if (arg === "--provider" && i + 1 < args.length) providers.push(parseUpgradeProvider(args[++i]!));
     else if (arg === "--codex") providers.push("codex");
     else if (arg === "--claude") providers.push("claude");
+    else if (arg === "--orchestrator") providers.push("orchestrator");
     else if (arg === "--all") providers.push("all");
     else if (arg === "--dry-run") dryRun = true;
     else if (arg === "--no-restart") noRestart = true;
@@ -200,8 +201,8 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
 }
 
 function parseUpgradeProvider(value: string): UpgradeProvider {
-  if (value === "auto" || value === "all" || value === "codex" || value === "claude") return value;
-  throw new Error(`Unknown upgrade provider "${value}". Expected auto, all, codex, or claude.`);
+  if (value === "auto" || value === "all" || value === "codex" || value === "claude" || value === "orchestrator") return value;
+  throw new Error(`Unknown upgrade provider "${value}". Expected auto, all, codex, claude, or orchestrator.`);
 }
 
 async function handleSlashOrPairCommand(command: string, args: string[]): Promise<void> {

package/src/config.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
 export const VERSION: string = pkg.version;
+export const ORCHESTRATOR_PROTOCOL_VERSION = 2;
 
 export const DAY_MS = 86_400_000;
 function envPositiveInt(name: string, fallback: number): number {