agent-relay-server 0.6.0 → 0.7.0

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,
@@ -11,12 +11,14 @@ import type {
   ChannelBindingMode,
   ChannelRouteTarget,
   ChannelSummary,
+  ChannelTargetHealth,
   CreatePairInput,
   HealthCheck,
   HealthReport,
   ManagedAgent,
   Message,
   Orchestrator,
+  OrchestratorHealth,
   OrchestratorStatus,
   PairActionInput,
   PairMessageInput,
@@ -628,6 +630,94 @@ function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
   return "";
 }
 
+function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
+  const candidates = listAgents().filter((agent) => (
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.kind !== "channel" &&
+    agent.meta?.kind !== "channel"
+  ));
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = getAgent(target.id);
+    return agent ? [agent] : [];
+  }
+  if (target.type === "label") return candidates.filter((agent) => agent.label === target.id);
+  if (target.type === "tag") return candidates.filter((agent) => agent.tags.includes(target.id));
+  if (target.type === "capability") return candidates.filter((agent) => agent.capabilities.includes(target.id));
+  if (target.type === "broadcast") return candidates;
+  return [];
+}
+
+function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
+  return {
+    id: agent.id,
+    name: agent.name,
+    status: agent.status,
+    ready: agent.ready,
+    lastSeen: agent.lastSeen,
+    label: agent.label,
+    tags: agent.tags,
+    capabilities: agent.capabilities,
+  };
+}
+
+function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
+  return isDeliveryAgent(agent) && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+function describeTarget(target: ChannelRouteTarget): string {
+  return bindingTargetToLegacyTarget(target);
+}
+
+function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
+  const target = binding.target;
+  const targetLabel = describeTarget(target);
+  const matches = channelTargetMatches(target);
+  const snapshots = matches.map(channelTargetMatchSnapshot);
+
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = matches[0];
+    if (!agent) {
+      return { status: "error", detail: `Target ${targetLabel} is not registered`, target, matches: [] };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && (agent.kind === "channel" || agent.meta?.kind === "channel")) {
+      return { status: "error", detail: `Target ${targetLabel} is a channel, not a delivery agent`, target, matches: snapshots };
+    }
+    if (agent.status === "offline") {
+      return { status: "error", detail: `Target ${targetLabel} is offline`, target, matches: snapshots };
+    }
+    if (!agent.ready) {
+      return { status: "warning", detail: `Target ${targetLabel} is online but not ready`, target, matches: snapshots };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && agent.lastSeen <= now - STALE_TTL_MS) {
+      return { status: "warning", detail: `Target ${targetLabel} heartbeat is stale`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Target ${targetLabel} is online and ready`, target, matches: snapshots };
+  }
+
+  const healthyMatches = matches.filter((agent) => isHealthyChannelTarget(agent, now));
+  if (matches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no matching agents`, target, matches: [] };
+  }
+  if (healthyMatches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no online ready agents`, target, matches: snapshots };
+  }
+  if (binding.mode === "exclusive" && healthyMatches.length > 1) {
+    return {
+      status: "warning",
+      detail: `Target ${targetLabel} matches ${healthyMatches.length} online ready agents for an exclusive binding`,
+      target,
+      matches: snapshots,
+    };
+  }
+  return {
+    status: "ok",
+    detail: `Target ${targetLabel} has ${healthyMatches.length} online ready agent${healthyMatches.length === 1 ? "" : "s"}`,
+    target,
+    matches: snapshots,
+  };
+}
+
 function rowToChannelSummary(row: any): ChannelSummary {
   const binding = row.binding_id ? rowToChannelBinding({
     id: row.binding_id,
@@ -653,6 +743,7 @@ function rowToChannelSummary(row: any): ChannelSummary {
     direction: row.direction,
     target: binding ? bindingTargetToLegacyTarget(binding.target) : undefined,
     binding,
+    targetHealth: binding ? channelTargetHealth(binding) : undefined,
     topicChannels: parseStringArray(row.topic_channels),
     capabilities: parseStringArray(row.channel_capabilities),
     tags: parseStringArray(row.agent_tags),
@@ -965,25 +1056,31 @@ export function upsertChannelBinding(input: {
   const targetId = input.target.type === "broadcast" ? "" : input.target.id;
   const targetKey = input.target.type === "broadcast" ? "broadcast" : `${input.target.type}:${targetId}`;
   const id = `${input.channelId}:${conversationKey || "default"}:${targetKey}`;
+  const mode = input.mode ?? "exclusive";
   const now = Date.now();
-  db.prepare(`
-    INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
-    VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
-    ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
-      mode = $mode,
-      priority = $priority,
-      updated_at = $now
-  `).run({
-    $id: id,
-    $channelId: input.channelId,
-    $conversationKey: conversationKey,
-    $conversationId: input.conversationId ?? null,
-    $targetType: input.target.type,
-    $targetId: targetId,
-    $mode: input.mode ?? "exclusive",
-    $priority: input.priority ?? 0,
-    $now: now,
-  });
+  db.transaction(() => {
+    if (mode === "exclusive") {
+      db.prepare("DELETE FROM channel_bindings WHERE channel_id = ? AND conversation_key = ?").run(input.channelId, conversationKey);
+    }
+    db.prepare(`
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
+      ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
+        mode = $mode,
+        priority = $priority,
+        updated_at = $now
+    `).run({
+      $id: id,
+      $channelId: input.channelId,
+      $conversationKey: conversationKey,
+      $conversationId: input.conversationId ?? null,
+      $targetType: input.target.type,
+      $targetId: targetId,
+      $mode: mode,
+      $priority: input.priority ?? 0,
+      $now: now,
+    });
+  })();
 
   const row = db.prepare("SELECT * FROM channel_bindings WHERE id = ?").get(id) as any;
   return rowToChannelBinding(row);
@@ -1733,6 +1830,21 @@ function isChannelAgentId(agentId: string): boolean {
   ));
 }
 
+function legacyChannelTargets(agent: AgentCard | null | undefined): string[] {
+  if (!agent || !isChannelAgentId(agent.id)) return [];
+  const aliases = new Set<string>();
+  const provider = channelProviderForAgent(agent);
+  if (provider && provider !== "custom") aliases.add(provider);
+  const channelType = stringValue(agent.meta?.channelType);
+  if (channelType) aliases.add(channelType);
+  const transport = stringValue(agent.meta?.transport);
+  if (transport) aliases.add(transport);
+  const providerTag = agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length);
+  if (providerTag) aliases.add(providerTag);
+  aliases.delete(agent.id);
+  return [...aliases];
+}
+
 function matchingDeliveryAgents(target: string): AgentCard[] {
   if (!target) return [];
   const candidates = listAgents().filter(isDeliveryAgent);
@@ -1963,11 +2075,15 @@ export function pollMessages(query: PollQuery): Message[] {
   const agentTags = agent?.tags ?? [];
   const agentCaps = agent?.capabilities ?? [];
   const agentLabel = agent?.label;
+  const agentLegacyChannelTargets = legacyChannelTargets(agent);
 
   const conditions: string[] = [];
   const params: any[] = [];
 
-  // Build target matching: direct + broadcast + tag + capability + label
+  // Build target matching: direct + broadcast + tag + capability + label.
+  // Channel agents also accept legacy bare provider targets (for example
+  // "telegram") so older clients keep working after canonical IDs became
+  // provider:account ("telegram:default").
   const targetClauses = ["to_target = ?", "to_target = 'broadcast'"];
   params.push(query.for);
 
@@ -1983,6 +2099,10 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push("to_target = ?");
     params.push(`label:${agentLabel}`);
   }
+  for (const target of agentLegacyChannelTargets) {
+    targetClauses.push("to_target = ?");
+    params.push(target);
+  }
   conditions.push(`(${targetClauses.join(" OR ")})`);
 
   // Hide active claims held by someone else, but let expired claims surface so
@@ -2267,6 +2387,21 @@ export function getHealth(now: number = Date.now()): HealthReport {
     detail: offlineClaimedTasks > 0 ? `${offlineClaimedTasks} active task(s) are claimed by offline agents` : undefined,
   });
 
+  const unhealthyChannelTargets = listChannels().filter((channel) => channel.targetHealth && channel.targetHealth.status !== "ok");
+  const channelTargetErrors = unhealthyChannelTargets.filter((channel) => channel.targetHealth?.status === "error");
+  const channelTargetDetail = unhealthyChannelTargets
+    .slice(0, 3)
+    .map((channel) => `${channel.name}: ${channel.targetHealth?.detail}`)
+    .join("; ");
+  checks.push({
+    name: "channel-delivery-targets",
+    status: channelTargetErrors.length > 0 ? "error" : unhealthyChannelTargets.length > 0 ? "warn" : "ok",
+    count: unhealthyChannelTargets.length,
+    detail: unhealthyChannelTargets.length > 0
+      ? `${unhealthyChannelTargets.length} channel delivery target issue(s): ${channelTargetDetail}${unhealthyChannelTargets.length > 3 ? "; ..." : ""}`
+      : undefined,
+  });
+
   const status = checks.some((check) => check.status === "error")
     ? "error"
     : checks.some((check) => check.status === "warn")
@@ -2278,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,
@@ -2286,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}`;
@@ -2315,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,
   });
 
@@ -2327,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)!;

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

@@ -290,6 +290,22 @@ export interface ChannelBinding {
   updatedAt: number;
 }
 
+export interface ChannelTargetHealth {
+  status: "ok" | "warning" | "error";
+  detail: string;
+  target: ChannelRouteTarget;
+  matches: Array<{
+    id: string;
+    name: string;
+    status: AgentCard["status"];
+    ready: boolean;
+    lastSeen: number;
+    label?: string;
+    tags: string[];
+    capabilities: string[];
+  }>;
+}
+
 export interface ChannelSummary {
   id: string;
   name: string;
@@ -302,6 +318,7 @@ export interface ChannelSummary {
   direction: ChannelDirection;
   target?: string;
   binding?: ChannelBinding;
+  targetHealth?: ChannelTargetHealth;
   topicChannels: string[];
   capabilities: string[];
   tags: string[];
@@ -394,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;
@@ -417,6 +447,9 @@ export interface RegisterOrchestratorInput {
   providers: SpawnProvider[];
   baseDir: string;
   envKeys?: string[];
+  version?: string;
+  protocolVersion?: number;
+  gitSha?: string;
   meta?: Record<string, unknown>;
 }