agent-relay-server 0.6.1 → 0.7.0

package/src/routes.ts

@@ -775,6 +775,44 @@ function auditEvent(input: ActivityEventInput): void {
   }
 }
 
+type AgentActivityState = {
+  key: "available" | "busy" | "not-ready" | "offline";
+  title: string;
+  icon: string;
+};
+
+function agentActivityState(agent?: Pick<AgentCard, "ready" | "status"> | null): AgentActivityState | null {
+  if (!agent) return null;
+  if (agent.status === "offline") return { key: "offline", title: "Agent offline", icon: "ti-plug-off" };
+  if (!agent.ready) return { key: "not-ready", title: "Agent not ready", icon: "ti-loader" };
+  if (agent.status === "busy") return { key: "busy", title: "Agent busy", icon: "ti-activity" };
+  return { key: "available", title: "Agent available", icon: "ti-circle-check" };
+}
+
+function auditAgentStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): void {
+  const previous = agentActivityState(before);
+  const next = agentActivityState(after);
+  if (!next || previous?.key === next.key) return;
+  auditEvent({
+    clientId: "server-agent-" + agentId + "-state-" + next.key + "-" + Date.now(),
+    kind: "state",
+    title: next.title,
+    meta: agentId,
+    icon: next.icon,
+    view: "agents",
+    agentId,
+  });
+}
+
+function orchestratorControlMeta(control: Record<string, unknown>): Record<string, unknown> {
+  return {
+    delivery: "interrupt",
+    priority: "urgent",
+    // Legacy orchestrators read control details from message meta.
+    orchestratorControl: control,
+  };
+}
+
 // --- Agent routes ---
 
 const postAgent: Handler = async (req) => {
@@ -836,21 +874,14 @@ const patchAgentStatus: Handler = async (req, params) => {
     const guard = normalizeAgentSessionGuard(req, body);
     const session = validateAgentSession(params.id!, guard);
     if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    const before = getAgent(params.id!);
     if (!setStatus(params.id!, body.status as any, guard)) return error("agent not found", 404);
+    auditAgentStateTransition(params.id!, before, getAgent(params.id!));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
   }
   emitAgentStatus(params.id!);
-  auditEvent({
-    clientId: "server-agent-" + params.id! + "-status-" + body.status + "-" + Date.now(),
-    kind: "state",
-    title: "Agent " + body.status,
-    meta: params.id!,
-    icon: body.status === "offline" ? "ti-plug-off" : "ti-activity",
-    view: "agents",
-    agentId: params.id!,
-  });
   return json({ ok: true });
 };
 
@@ -903,21 +934,14 @@ const patchAgentReady: Handler = async (req, params) => {
     const guard = normalizeAgentSessionGuard(req, body);
     const session = validateAgentSession(params.id!, guard);
     if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+    const before = getAgent(params.id!);
     if (!markReady(params.id!, body.ready, guard)) return error("agent not found", 404);
+    auditAgentStateTransition(params.id!, before, getAgent(params.id!));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
   }
   emitAgentStatus(params.id!);
-  auditEvent({
-    clientId: "server-agent-" + params.id! + "-ready-" + body.ready + "-" + Date.now(),
-    kind: "state",
-    title: body.ready ? "Agent ready" : "Agent not ready",
-    meta: params.id!,
-    icon: body.ready ? "ti-circle-check" : "ti-loader",
-    view: "agents",
-    agentId: params.id!,
-  });
   return json({ ok: true });
 };
 
@@ -1008,17 +1032,15 @@ const postAgentSpawn: Handler = async (req) => {
     if (orchestrators.length > 0) {
       // Route through the first available orchestrator
       const orch = orchestrators[0]!;
+      const control = { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() };
       const msg = sendMessage({
         from: "system",
         to: orch.agentId,
         kind: "control",
         subject: "Spawn agent",
         body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
-        payload: { orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() } },
-        meta: {
-          delivery: "interrupt",
-          priority: "urgent",
-        },
+        payload: { orchestratorControl: control },
+        meta: orchestratorControlMeta(control),
       });
       emitNewMessage(msg);
       auditEvent({
@@ -1104,8 +1126,16 @@ const postOrchestrator: Handler = async (req) => {
       }
     }
     const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys");
+    const version = cleanString(parsed.body.version, "version", { max: 80 });
+    const gitSha = cleanString(parsed.body.gitSha, "gitSha", { max: 80 });
+    const protocolVersionRaw = parsed.body.protocolVersion;
+    const protocolVersion = protocolVersionRaw === undefined
+      ? undefined
+      : typeof protocolVersionRaw === "number" && Number.isInteger(protocolVersionRaw) && protocolVersionRaw > 0
+        ? protocolVersionRaw
+        : (() => { throw new ValidationError("protocolVersion must be a positive integer"); })();
     const meta = cleanMeta(parsed.body.meta);
-    const orch = upsertOrchestrator({ id, hostname, providers: providers ?? ["claude", "codex"], baseDir, envKeys, meta });
+    const orch = upsertOrchestrator({ id, hostname, providers: providers ?? ["claude", "codex"], baseDir, envKeys, version, protocolVersion, gitSha, meta });
     auditEvent({
       clientId: "server-orchestrator-register-" + id + "-" + Date.now(),
       kind: "state",
@@ -1192,6 +1222,16 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
     const prompt = cleanString(parsed.body.prompt, "prompt", { max: 4000 });
 
     // Send control message to orchestrator's agent inbox
+    const control = {
+      action: "spawn",
+      provider,
+      cwd: cwd || orch.baseDir,
+      label,
+      approvalMode,
+      prompt,
+      requestedBy: "dashboard",
+      requestedAt: Date.now(),
+    };
     const msg = sendMessage({
       from: "system",
       to: orch.agentId,
@@ -1199,21 +1239,9 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
       subject: "Spawn agent",
       body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
       payload: {
-        orchestratorControl: {
-          action: "spawn",
-          provider,
-          cwd: cwd || orch.baseDir,
-          label,
-          approvalMode,
-          prompt,
-          requestedBy: "dashboard",
-          requestedAt: Date.now(),
-        },
-      },
-      meta: {
-        delivery: "interrupt",
-        priority: "urgent",
+        orchestratorControl: control,
       },
+      meta: orchestratorControlMeta(control),
     });
     emitNewMessage(msg);
     auditEvent({
@@ -1245,6 +1273,12 @@ const postOrchestratorAction: Handler = async (req, params) => {
     if (!action) return error("action required");
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
 
+    const control = {
+      action,
+      agentId,
+      requestedBy: "dashboard",
+      requestedAt: Date.now(),
+    };
     const msg = sendMessage({
       from: "system",
       to: orch.agentId,
@@ -1252,17 +1286,9 @@ const postOrchestratorAction: Handler = async (req, params) => {
       subject: action === "restart" ? "Restart agent" : "Shutdown agent",
       body: agentId ? `${action} ${agentId}` : `${action} all managed agents`,
       payload: {
-        orchestratorControl: {
-          action,
-          agentId,
-          requestedBy: "dashboard",
-          requestedAt: Date.now(),
-        },
-      },
-      meta: {
-        delivery: "interrupt",
-        priority: "urgent",
+        orchestratorControl: control,
       },
+      meta: orchestratorControlMeta(control),
     });
     emitNewMessage(msg);
     auditEvent({

package/src/types.ts

@@ -411,12 +411,25 @@ export interface Orchestrator {
   providers: SpawnProvider[];
   baseDir: string;
   envKeys: string[]; // names only, never values
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
+  health?: OrchestratorHealth;
   meta: Record<string, unknown>;
   managedAgents: ManagedAgent[];
   lastSeen: number;
   createdAt: number;
 }
 
+export interface OrchestratorHealth {
+  status: "ok" | "warn" | "error";
+  restartRequired: boolean;
+  issues: Array<{
+    code: "missing-version" | "outdated" | "protocol-mismatch" | "restart-required";
+    detail: string;
+  }>;
+}
+
 export interface ManagedAgent {
   agentId: string;
   provider: SpawnProvider;
@@ -434,6 +447,9 @@ export interface RegisterOrchestratorInput {
   providers: SpawnProvider[];
   baseDir: string;
   envKeys?: string[];
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
   meta?: Record<string, unknown>;
 }
 

package/src/upgrade.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { VERSION } from "./config";
 
-export type UpgradeProvider = "auto" | "all" | "codex" | "claude";
+export type UpgradeProvider = "auto" | "all" | "codex" | "claude" | "orchestrator";
 
 type UpgradeOptions = {
   targetVersion?: string;
@@ -28,12 +28,16 @@ export type UpgradeSnapshot = {
   targetVersion: string;
   serverPackage?: InstalledPackage;
   codexPackage?: InstalledPackage;
+  orchestratorPackage?: InstalledPackage;
   codexCopiedPackage?: InstalledPackage;
   claudePluginInstalls: ClaudePluginInstall[];
   hasCodexCommand: boolean;
+  hasOrchestratorCommand: boolean;
   hasClaudeCommand: boolean;
   hasSystemdUserService: boolean;
+  hasSystemdUserOrchestratorService: boolean;
   runningServerVersion?: string;
+  runningOrchestrators?: Array<{ id: string; version?: string; protocolVersion?: number; health?: { status?: string; restartRequired?: boolean } }>;
   packageManager: "bun" | "npm" | "none";
 };
 
@@ -46,7 +50,7 @@ type UpgradeAction = {
 
 type UpgradePlan = {
   targetVersion: string;
-  providers: { codex: boolean; claude: boolean };
+  providers: { codex: boolean; claude: boolean; orchestrator: boolean };
   snapshot: UpgradeSnapshot;
   actions: UpgradeAction[];
   warnings: string[];
@@ -67,9 +71,9 @@ export async function detectUpgradeSnapshot(options: UpgradeOptions = {}): Promi
   const codexCopiedPackage = readPackageVersion(join(homeDir(), ".agent-relay", "codex", "package", "package.json"));
   const claudePluginInstalls = readClaudePluginInstalls(join(homeDir(), ".claude", "plugins", "installed_plugins.json"));
 
-  const packageManager = bunPackages.has("agent-relay-server") || bunPackages.has("agent-relay-codex")
+  const packageManager = bunPackages.has("agent-relay-server") || bunPackages.has("agent-relay-codex") || bunPackages.has("agent-relay-orchestrator")
     ? "bun"
-    : npmPackages.has("agent-relay-server") || npmPackages.has("agent-relay-codex")
+    : npmPackages.has("agent-relay-server") || npmPackages.has("agent-relay-codex") || npmPackages.has("agent-relay-orchestrator")
       ? "npm"
       : commandExists("bun")
         ? "bun"
@@ -81,14 +85,18 @@ export async function detectUpgradeSnapshot(options: UpgradeOptions = {}): Promi
     targetVersion,
     serverPackage: installedPackage("agent-relay-server", bunPackages, npmPackages),
     codexPackage: installedPackage("agent-relay-codex", bunPackages, npmPackages),
+    orchestratorPackage: installedPackage("agent-relay-orchestrator", bunPackages, npmPackages),
     codexCopiedPackage: codexCopiedPackage
       ? { version: codexCopiedPackage, source: "copied", path: join(homeDir(), ".agent-relay", "codex", "package") }
       : undefined,
     claudePluginInstalls,
     hasCodexCommand: commandExists("agent-relay-codex") || commandExists("codex-relay") || existsSync(join(homeDir(), ".agent-relay", "codex", "package")),
+    hasOrchestratorCommand: commandExists("agent-relay-orchestrator"),
     hasClaudeCommand: commandExists("claude"),
     hasSystemdUserService: hasSystemdUserService("agent-relay.service"),
+    hasSystemdUserOrchestratorService: hasSystemdUserService("agent-relay-orchestrator.service"),
     runningServerVersion: await runningServerVersion(),
+    runningOrchestrators: await runningOrchestrators(),
     packageManager,
   };
 }
@@ -99,6 +107,7 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   const providerSet = new Set(requestedProviders);
   const codexRequested = providerSet.has("all") || providerSet.has("codex") || (providerSet.has("auto") && isCodexDetected(snapshot));
   const claudeRequested = providerSet.has("all") || providerSet.has("claude") || (providerSet.has("auto") && isClaudeRelayDetected(snapshot));
+  const orchestratorRequested = providerSet.has("all") || providerSet.has("orchestrator") || (providerSet.has("auto") && isOrchestratorDetected(snapshot));
   const actions: UpgradeAction[] = [];
   const warnings: string[] = [];
 
@@ -107,13 +116,14 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   } else {
     const packages = [`agent-relay-server@${targetVersion}`];
     if (codexRequested) packages.push(`agent-relay-codex@${targetVersion}`);
+    if (orchestratorRequested) packages.push(`agent-relay-orchestrator@${targetVersion}`);
     const command = snapshot.packageManager === "bun"
       ? ["bun", "add", "-g", ...packages]
       : ["npm", "install", "-g", ...packages];
     actions.push({
       label: "Upgrade global packages",
       command,
-      reason: `Update server${codexRequested ? " and Codex integration" : ""} packages to ${targetVersion}.`,
+      reason: `Update server${codexRequested ? ", Codex integration" : ""}${orchestratorRequested ? ", and orchestrator" : ""} packages to ${targetVersion}.`,
       mutates: true,
     });
   }
@@ -148,6 +158,10 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
     warnings.push("Claude Agent Relay plugin not detected; skipping Claude plugin upgrade.");
   }
 
+  if (!orchestratorRequested && providerSet.has("auto") && !isOrchestratorDetected(snapshot)) {
+    warnings.push("Agent Relay orchestrator not detected; skipping orchestrator package upgrade.");
+  }
+
   if (snapshot.hasSystemdUserService) {
     if (options.noRestart) {
       warnings.push("agent-relay.service detected but --no-restart was set; restart manually to run the upgraded server.");
@@ -163,9 +177,24 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
     warnings.push("No systemd user service detected; restart any manually running Agent Relay server yourself.");
   }
 
+  if (snapshot.hasSystemdUserOrchestratorService) {
+    if (options.noRestart) {
+      warnings.push("agent-relay-orchestrator.service detected but --no-restart was set; restart manually to run the upgraded orchestrator.");
+    } else {
+      actions.push({
+        label: "Restart Agent Relay orchestrator service",
+        command: ["systemctl", "--user", "restart", "agent-relay-orchestrator.service"],
+        reason: "Restart orchestrator daemon so host lifecycle control uses the upgraded protocol.",
+        mutates: true,
+      });
+    }
+  } else if (orchestratorRequested) {
+    warnings.push("No agent-relay-orchestrator.service detected; restart any manually running orchestrator yourself.");
+  }
+
   return {
     targetVersion,
-    providers: { codex: codexRequested, claude: claudeRequested },
+    providers: { codex: codexRequested, claude: claudeRequested, orchestrator: orchestratorRequested },
     snapshot: { ...snapshot, targetVersion },
     actions,
     warnings,
@@ -194,6 +223,15 @@ export async function executeUpgradePlan(plan: UpgradePlan, options: { dryRun?:
     }
     if (serverVersion) lines.push(`Running server: ${serverVersion}`);
   }
+  if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay-orchestrator.service")) {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    const orchestrators = await runningOrchestrators() ?? [];
+    const mismatched = orchestrators.filter((orch) => orch.version && orch.version !== plan.targetVersion);
+    if (mismatched.length > 0) {
+      throw new Error(`agent-relay-orchestrator.service restarted but ${mismatched.map((orch) => `${orch.id} reports ${orch.version}`).join(", ")}, expected ${plan.targetVersion}`);
+    }
+    if (orchestrators.length > 0) lines.push(`Running orchestrator(s): ${orchestrators.map((orch) => `${orch.id}${orch.version ? ` ${orch.version}` : ""}`).join(", ")}`);
+  }
   lines.push("\nUpgrade commands completed.");
   if (plan.warnings.length > 0) {
     lines.push("\nWarnings:");
@@ -211,11 +249,14 @@ export function formatUpgradePlan(plan: UpgradePlan, options: { dryRun?: boolean
     `- running server: ${plan.snapshot.runningServerVersion ?? "unknown"}`,
     `- codex package: ${formatPackage(plan.snapshot.codexPackage)}`,
     `- codex copied package: ${formatPackage(plan.snapshot.codexCopiedPackage)}`,
+    `- orchestrator package: ${formatPackage(plan.snapshot.orchestratorPackage)}`,
+    `- running orchestrators: ${formatRunningOrchestrators(plan.snapshot.runningOrchestrators)}`,
     `- claude command: ${plan.snapshot.hasClaudeCommand ? "yes" : "no"}`,
     `- claude agent-relay plugin: ${formatClaudePlugins(plan.snapshot.claudePluginInstalls)}`,
     `- systemd user service: ${plan.snapshot.hasSystemdUserService ? "yes" : "no"}`,
+    `- orchestrator systemd user service: ${plan.snapshot.hasSystemdUserOrchestratorService ? "yes" : "no"}`,
     "",
-    `Providers: codex=${plan.providers.codex ? "yes" : "no"}, claude=${plan.providers.claude ? "yes" : "no"}`,
+    `Providers: codex=${plan.providers.codex ? "yes" : "no"}, claude=${plan.providers.claude ? "yes" : "no"}, orchestrator=${plan.providers.orchestrator ? "yes" : "no"}`,
     "",
     "Actions:",
   ];
@@ -239,6 +280,10 @@ function isClaudeRelayDetected(snapshot: UpgradeSnapshot): boolean {
   return snapshot.claudePluginInstalls.length > 0;
 }
 
+function isOrchestratorDetected(snapshot: UpgradeSnapshot): boolean {
+  return Boolean(snapshot.orchestratorPackage || snapshot.hasOrchestratorCommand || snapshot.hasSystemdUserOrchestratorService || (snapshot.runningOrchestrators?.length ?? 0) > 0);
+}
+
 function installedPackage(name: string, bunPackages: Map<string, string>, npmPackages: Map<string, string>): InstalledPackage | undefined {
   const bunVersion = bunPackages.get(name);
   if (bunVersion) return { version: bunVersion, source: "bun" };
@@ -292,6 +337,27 @@ async function runningServerVersion(): Promise<string | undefined> {
   }
 }
 
+async function runningOrchestrators(): Promise<UpgradeSnapshot["runningOrchestrators"]> {
+  try {
+    const headers: Record<string, string> = {};
+    if (process.env.AGENT_RELAY_TOKEN) headers["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+    const relayUrl = (process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850").replace(/\/+$/, "");
+    const response = await fetch(`${relayUrl}/api/orchestrators`, { headers });
+    if (!response.ok) return [];
+    const payload = await response.json() as Array<{ id?: string; version?: string; protocolVersion?: number; health?: { status?: string; restartRequired?: boolean } }>;
+    return payload
+      .filter((orch) => typeof orch.id === "string")
+      .map((orch) => ({
+        id: orch.id!,
+        version: orch.version,
+        protocolVersion: orch.protocolVersion,
+        health: orch.health,
+      }));
+  } catch {
+    return [];
+  }
+}
+
 function hasSystemdUserService(name: string): boolean {
   if (!commandExists("systemctl")) return false;
   const result = runCommand(["systemctl", "--user", "status", name, "--no-pager"]);
@@ -372,6 +438,13 @@ function formatClaudePlugins(installs: ClaudePluginInstall[]): string {
   return installs.map((install) => `${install.version ?? "unknown"} (${install.scope ?? "user"})`).join(", ");
 }
 
+function formatRunningOrchestrators(orchestrators: UpgradeSnapshot["runningOrchestrators"]): string {
+  if (!orchestrators?.length) return "not detected";
+  return orchestrators
+    .map((orch) => `${orch.id}: ${orch.version ?? "unknown"}${orch.health?.restartRequired ? " (restart required)" : ""}`)
+    .join(", ");
+}
+
 function shellQuote(value: string): string {
   if (/^[a-zA-Z0-9_@%+=:,./-]+$/.test(value)) return value;
   return `'${value.replaceAll("'", "'\\''")}'`;