agent-relay-server 0.6.1 → 0.7.1

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">
@@ -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>
@@ -1817,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()">
@@ -2567,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 {

package/src/db.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { VERSION } from "./config.ts";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "./config.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -18,6 +18,7 @@ import type {
   ManagedAgent,
   Message,
   Orchestrator,
+  OrchestratorHealth,
   OrchestratorStatus,
   PairActionInput,
   PairMessageInput,
@@ -2412,6 +2413,15 @@ export function getHealth(now: number = Date.now()): HealthReport {
 // --- Orchestrators ---
 
 function rowToOrchestrator(row: any): Orchestrator {
+  const meta = parseJson<Record<string, unknown>>(row.meta, {});
+  const version = stringValue(meta.version);
+  const gitSha = stringValue(meta.gitSha);
+  const protocolRaw = meta.protocolVersion;
+  const protocolVersion = typeof protocolRaw === "number"
+    ? protocolRaw
+    : typeof protocolRaw === "string" && protocolRaw.trim() !== ""
+      ? Number(protocolRaw)
+      : undefined;
   return {
     id: row.id,
     hostname: row.hostname,
@@ -2420,13 +2430,40 @@ function rowToOrchestrator(row: any): Orchestrator {
     providers: parseJson<SpawnProvider[]>(row.providers, []),
     baseDir: row.base_dir,
     envKeys: parseJson<string[]>(row.env_keys, []),
-    meta: parseJson(row.meta, {}),
+    ...(version ? { version } : {}),
+    ...(Number.isFinite(protocolVersion) ? { protocolVersion } : {}),
+    ...(gitSha ? { gitSha } : {}),
+    health: orchestratorHealth(version, Number.isFinite(protocolVersion) ? protocolVersion : undefined),
+    meta,
     managedAgents: parseJson<ManagedAgent[]>(row.managed_agents, []),
     lastSeen: row.last_seen,
     createdAt: row.created_at,
   };
 }
 
+function orchestratorHealth(version: string | undefined, protocolVersion: number | undefined): OrchestratorHealth {
+  const issues: OrchestratorHealth["issues"] = [];
+  if (!version) {
+    issues.push({ code: "missing-version", detail: "Orchestrator did not report a version; restart or upgrade it." });
+  } else if (version !== VERSION) {
+    issues.push({ code: "outdated", detail: `Orchestrator ${version} does not match server ${VERSION}.` });
+  }
+  if (protocolVersion !== ORCHESTRATOR_PROTOCOL_VERSION) {
+    issues.push({
+      code: "protocol-mismatch",
+      detail: `Orchestrator protocol ${protocolVersion ?? "unknown"} does not match server protocol ${ORCHESTRATOR_PROTOCOL_VERSION}.`,
+    });
+  }
+  if (issues.length > 0) {
+    issues.push({ code: "restart-required", detail: "Restart the orchestrator after upgrading Agent Relay." });
+  }
+  return {
+    status: issues.some((issue) => issue.code === "protocol-mismatch") ? "error" : issues.length > 0 ? "warn" : "ok",
+    restartRequired: issues.length > 0,
+    issues,
+  };
+}
+
 export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrator {
   const now = Date.now();
   const agentId = `orchestrator-${input.id}`;
@@ -2449,7 +2486,12 @@ export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrat
     $providers: JSON.stringify(input.providers),
     $baseDir: input.baseDir,
     $envKeys: JSON.stringify(input.envKeys ?? []),
-    $meta: JSON.stringify(input.meta ?? {}),
+    $meta: JSON.stringify({
+      ...(input.meta ?? {}),
+      ...(input.version ? { version: input.version } : {}),
+      ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
+      ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+    }),
     $now: now,
   });
 
@@ -2461,7 +2503,13 @@ export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrat
     machine: input.hostname,
     capabilities: ["orchestrator", "spawn"],
     status: "online",
-    meta: { orchestratorId: input.id, builtin: true },
+    meta: {
+      orchestratorId: input.id,
+      builtin: true,
+      ...(input.version ? { version: input.version } : {}),
+      ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
+      ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+    },
   });
 
   return getOrchestrator(input.id)!;