agent-relay-server 0.8.1 → 0.10.0

package/src/db.ts

@@ -19,6 +19,7 @@ import type {
   Message,
   Orchestrator,
   OrchestratorHealth,
+  OrchestratorRuntimeInput,
   OrchestratorStatus,
   PairActionInput,
   PairMessageInput,
@@ -41,7 +42,7 @@ import type {
   InboxThreadState,
   TaskStatusInput,
 } from "./types";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS } from "./config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS } from "./config";
 
 let db: Database;
 
@@ -120,6 +121,49 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_tasks_target ON tasks(target);
     CREATE INDEX IF NOT EXISTS idx_tasks_updated ON tasks(updated_at);
 
+    CREATE TABLE IF NOT EXISTS automations (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      schedule TEXT NOT NULL,
+      timezone TEXT NOT NULL,
+      next_run_at INTEGER,
+      catch_up_policy TEXT NOT NULL,
+      concurrency_policy TEXT NOT NULL,
+      orchestrator_id TEXT NOT NULL,
+      target_policy TEXT NOT NULL,
+      task_template TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_automations_enabled_next_run ON automations(enabled, next_run_at);
+
+    CREATE TABLE IF NOT EXISTS automation_runs (
+      id TEXT PRIMARY KEY,
+      automation_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      scheduled_for INTEGER NOT NULL,
+      started_at INTEGER,
+      finished_at INTEGER,
+      orchestrator_id TEXT NOT NULL,
+      target_agent_id TEXT,
+      spawned_agent_id TEXT,
+      task_id INTEGER,
+      message_id INTEGER,
+      control_message_id INTEGER,
+      error TEXT,
+      result TEXT,
+      meta TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      shutdown_requested_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_automation ON automation_runs(automation_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_status ON automation_runs(status);
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_task ON automation_runs(task_id);
+
     CREATE TABLE IF NOT EXISTS task_events (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
@@ -252,6 +296,70 @@ export function initDb(path: string = "agent-relay.db"): Database {
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS bus_outbox (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      source TEXT NOT NULL,
+      subject TEXT,
+      data TEXT NOT NULL,
+      timestamp INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_outbox_type ON bus_outbox(event_type);
+    CREATE INDEX IF NOT EXISTS idx_outbox_timestamp ON bus_outbox(timestamp);
+
+    CREATE TABLE IF NOT EXISTS commands (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      source TEXT NOT NULL,
+      target TEXT NOT NULL,
+      params TEXT NOT NULL DEFAULT '{}',
+      status TEXT NOT NULL DEFAULT 'pending',
+      result TEXT,
+      error TEXT,
+      correlation_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_commands_target ON commands(target);
+    CREATE INDEX IF NOT EXISTS idx_commands_status ON commands(status);
+    CREATE INDEX IF NOT EXISTS idx_commands_created ON commands(created_at);
+    CREATE INDEX IF NOT EXISTS idx_commands_correlation ON commands(correlation_id);
+
+    CREATE TABLE IF NOT EXISTS recipe_instances (
+      id TEXT PRIMARY KEY,
+      recipe_name TEXT NOT NULL,
+      recipe_source TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      orchestrator_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      started_by TEXT NOT NULL,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      stopped_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS recipe_agent_instances (
+      instance_id TEXT NOT NULL REFERENCES recipe_instances(id) ON DELETE CASCADE,
+      role TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      status TEXT NOT NULL,
+      idx INTEGER,
+      PRIMARY KEY (instance_id, role, agent_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_recipe_instances_status ON recipe_instances(status);
+
+    CREATE TABLE IF NOT EXISTS tokens (
+      jti TEXT PRIMARY KEY,
+      sub TEXT NOT NULL,
+      role TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      issued_at INTEGER NOT NULL,
+      expires_at INTEGER,
+      revoked_at INTEGER,
+      created_by TEXT
+    );
   `);
 
   // Migrations
@@ -307,6 +415,14 @@ export function initDb(path: string = "agent-relay.db"): Database {
   db.run("CREATE INDEX IF NOT EXISTS idx_channel_bindings_channel ON channel_bindings(channel_id, priority)");
   db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_target ON channel_bindings(channel_id, conversation_key, target_type, target_id)");
 
+  const bindingColNames = (db.prepare("PRAGMA table_info(channel_bindings)").all() as any[]).map((c: any) => c.name);
+  if (!bindingColNames.includes("pool_selector")) {
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_selector TEXT");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_id TEXT");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_agent_epoch INTEGER");
+    db.run("ALTER TABLE channel_bindings ADD COLUMN pool_claim_expires_at INTEGER");
+  }
+
   if (!colNames.includes("kind")) {
     db.run("ALTER TABLE messages ADD COLUMN kind TEXT NOT NULL DEFAULT 'chat'");
   }
@@ -327,6 +443,13 @@ export function initDb(path: string = "agent-relay.db"): Database {
     "UPDATE tasks SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
   ).run(Date.now(), CLAIM_LEASE_MS);
 
+  // Migration: orchestrators.api_url
+  const orchCols = db.prepare("PRAGMA table_info(orchestrators)").all() as any[];
+  const orchColNames = orchCols.map((c: any) => c.name);
+  if (!orchColNames.includes("api_url")) {
+    db.run("ALTER TABLE orchestrators ADD COLUMN api_url TEXT");
+  }
+
   // message_reads: relational replacement for the read_by JSON array.
   db.run(`
     CREATE TABLE IF NOT EXISTS message_reads (
@@ -395,6 +518,11 @@ export function initDb(path: string = "agent-relay.db"): Database {
   return db;
 }
 
+export function getDb(): Database {
+  if (!db) throw new Error("database not initialized");
+  return db;
+}
+
 export class ValidationError extends Error {}
 class ClaimError extends Error {}
 
@@ -608,7 +736,7 @@ function rowToChannelBinding(row: any): ChannelBinding {
   const target = row.target_type === "broadcast"
     ? { type: "broadcast" } as ChannelRouteTarget
     : { type: row.target_type, id: row.target_id } as ChannelRouteTarget;
-  return {
+  const binding: ChannelBinding = {
     id: row.id,
     channelId: row.channel_id,
     conversationId: row.conversation_id ?? undefined,
@@ -618,6 +746,13 @@ function rowToChannelBinding(row: any): ChannelBinding {
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
+  if (row.pool_selector) {
+    binding.poolSelector = row.pool_selector;
+    binding.poolAgentId = row.pool_agent_id ?? undefined;
+    binding.poolAgentEpoch = row.pool_agent_epoch ?? undefined;
+    binding.poolClaimExpiresAt = row.pool_claim_expires_at ?? undefined;
+  }
+  return binding;
 }
 
 function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
@@ -627,10 +762,35 @@ function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
   if (target.type === "capability") return `cap:${target.id}`;
   if (target.type === "broadcast") return "broadcast";
   if (target.type === "orchestrator") return `orchestrator:${target.id}`;
+  if (target.type === "pool") return `pool:${target.id}`;
   return "";
 }
 
-function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
+function configuredChannelsForAgent(agent: AgentCard): string[] {
+  const channels = agent.meta?.channels;
+  if (!Array.isArray(channels)) return [];
+  return channels
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function channelEntryMatches(channelId: string, entry: string): boolean {
+  const normalized = entry.trim();
+  if (!normalized) return false;
+  if (normalized === channelId) return true;
+  if (normalized.endsWith(":*")) return channelId.startsWith(normalized.slice(0, -1));
+  return channelId.startsWith(`${normalized}:`);
+}
+
+function agentCanServeChannel(agent: AgentCard, channelId?: string): boolean {
+  if (!channelId) return true;
+  const channels = configuredChannelsForAgent(agent);
+  if (channels.length === 0) return true;
+  return channels.some((entry) => channelEntryMatches(channelId, entry));
+}
+
+function channelTargetMatches(target: ChannelRouteTarget, channelId?: string): AgentCard[] {
   const candidates = listAgents().filter((agent) => (
     agent.id !== "user" &&
     agent.id !== "system" &&
@@ -641,13 +801,23 @@ function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
     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;
+  const channelCandidates = candidates.filter((agent) => agentCanServeChannel(agent, channelId));
+  if (target.type === "pool") return poolSelectorMatches(target.id, channelCandidates);
+  if (target.type === "label") return channelCandidates.filter((agent) => agent.label === target.id);
+  if (target.type === "tag") return channelCandidates.filter((agent) => agent.tags.includes(target.id));
+  if (target.type === "capability") return channelCandidates.filter((agent) => agent.capabilities.includes(target.id));
+  if (target.type === "broadcast") return channelCandidates;
   return [];
 }
 
+function poolSelectorMatches(selector: string, candidates: AgentCard[]): AgentCard[] {
+  if (selector.startsWith("label:")) return candidates.filter((a) => a.label === selector.slice("label:".length));
+  if (selector.startsWith("tag:")) return candidates.filter((a) => a.tags.includes(selector.slice("tag:".length)));
+  if (selector.startsWith("cap:")) return candidates.filter((a) => a.capabilities.includes(selector.slice("cap:".length)));
+  const agent = getAgent(selector);
+  return agent ? [agent] : [];
+}
+
 function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
   return {
     id: agent.id,
@@ -672,9 +842,31 @@ function describeTarget(target: ChannelRouteTarget): string {
 function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
   const target = binding.target;
   const targetLabel = describeTarget(target);
-  const matches = channelTargetMatches(target);
+  const matches = channelTargetMatches(target, binding.channelId);
   const snapshots = matches.map(channelTargetMatchSnapshot);
 
+  if (target.type === "pool") {
+    const healthyEligibles = matches.filter((a) => isHealthyChannelTarget(a, now));
+    if (!binding.poolAgentId) {
+      if (matches.length === 0) return { status: "error", detail: `Pool ${targetLabel}: no eligible agents`, target, matches: [] };
+      return { status: "error", detail: `Pool ${targetLabel}: ${healthyEligibles.length} eligible but slot unclaimed`, target, matches: snapshots };
+    }
+    const holder = getAgent(binding.poolAgentId);
+    if (!holder || holder.status === "offline") {
+      return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is offline`, target, matches: snapshots };
+    }
+    if (!agentCanServeChannel(holder, binding.channelId)) {
+      return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is not configured for ${binding.channelId}`, target, matches: snapshots };
+    }
+    if (!holder.ready) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} online but not ready`, target, matches: snapshots };
+    }
+    if (binding.poolAgentEpoch !== undefined && holder.epoch !== binding.poolAgentEpoch) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder epoch changed (stale claim)`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Pool ${targetLabel}: claimed by ${binding.poolAgentId}`, target, matches: snapshots };
+  }
+
   if (target.type === "agent" || target.type === "orchestrator") {
     const agent = matches[0];
     if (!agent) {
@@ -686,6 +878,9 @@ function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()):
     if (agent.status === "offline") {
       return { status: "error", detail: `Target ${targetLabel} is offline`, target, matches: snapshots };
     }
+    if (!agentCanServeChannel(agent, binding.channelId)) {
+      return { status: "error", detail: `Target ${targetLabel} is not configured for ${binding.channelId}`, target, matches: snapshots };
+    }
     if (!agent.ready) {
       return { status: "warning", detail: `Target ${targetLabel} is online but not ready`, target, matches: snapshots };
     }
@@ -729,6 +924,10 @@ function rowToChannelSummary(row: any): ChannelSummary {
     priority: row.binding_priority,
     created_at: row.binding_created_at,
     updated_at: row.binding_updated_at,
+    pool_selector: row.binding_pool_selector,
+    pool_agent_id: row.binding_pool_agent_id,
+    pool_agent_epoch: row.binding_pool_agent_epoch,
+    pool_claim_expires_at: row.binding_pool_claim_expires_at,
   }) : undefined;
 
   return {
@@ -817,6 +1016,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
 
   const agent = getAgent(input.id)!;
   if (agent.kind === "channel") upsertChannelForAgent(agent);
+  evaluatePoolBindings();
   return agent;
 }
 
@@ -949,6 +1149,7 @@ function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"]
 
 function routeTargetFromLegacyTarget(target: string | undefined): ChannelRouteTarget | undefined {
   if (!target) return undefined;
+  if (target.startsWith("pool:")) return { type: "pool", id: target.slice("pool:".length) };
   if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
   if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
   if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
@@ -1002,7 +1203,7 @@ function upsertChannelForAgent(agent: AgentCard): void {
     upsertChannelBinding({
       channelId,
       target: defaultTarget,
-      mode: defaultTarget.type === "agent" ? "exclusive" : defaultTarget.type === "broadcast" ? "broadcast" : "claimable",
+      mode: defaultTarget.type === "broadcast" ? "broadcast" : "exclusive",
     });
   }
 }
@@ -1024,7 +1225,11 @@ export function listChannels(): ChannelSummary[] {
       b.mode AS binding_mode,
       b.priority AS binding_priority,
       b.created_at AS binding_created_at,
-      b.updated_at AS binding_updated_at
+      b.updated_at AS binding_updated_at,
+      b.pool_selector AS binding_pool_selector,
+      b.pool_agent_id AS binding_pool_agent_id,
+      b.pool_agent_epoch AS binding_pool_agent_epoch,
+      b.pool_claim_expires_at AS binding_pool_claim_expires_at
     FROM channels c
     JOIN agents a ON a.id = c.agent_id
     LEFT JOIN channel_bindings b ON b.channel_id = c.id AND b.conversation_key = ''
@@ -1057,17 +1262,20 @@ export function upsertChannelBinding(input: {
   const targetKey = input.target.type === "broadcast" ? "broadcast" : `${input.target.type}:${targetId}`;
   const id = `${input.channelId}:${conversationKey || "default"}:${targetKey}`;
   const mode = input.mode ?? "exclusive";
+  const isPool = input.target.type === "pool";
+  const poolSelector = isPool ? targetId : null;
   const now = Date.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)
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, pool_selector, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $poolSelector, $now, $now)
       ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
         mode = $mode,
         priority = $priority,
+        pool_selector = $poolSelector,
         updated_at = $now
     `).run({
       $id: id,
@@ -1078,14 +1286,78 @@ export function upsertChannelBinding(input: {
       $targetId: targetId,
       $mode: mode,
       $priority: input.priority ?? 0,
+      $poolSelector: poolSelector,
       $now: now,
     });
   })();
 
+  evaluatePoolBindings(now);
   const row = db.prepare("SELECT * FROM channel_bindings WHERE id = ?").get(id) as any;
   return rowToChannelBinding(row);
 }
 
+interface PoolBindingChange {
+  bindingId: string;
+  channelId: string;
+  previousAgentId: string | null;
+  newAgentId: string | null;
+}
+
+export function evaluatePoolBindings(now: number = Date.now()): PoolBindingChange[] {
+  const rows = db.prepare("SELECT * FROM channel_bindings WHERE target_type = 'pool'").all() as any[];
+  const changes: PoolBindingChange[] = [];
+
+  for (const row of rows) {
+    const bindingId = row.id as string;
+    const channelId = row.channel_id as string;
+    const selector = row.pool_selector ?? row.target_id;
+    const currentAgentId: string | null = row.pool_agent_id;
+    const currentEpoch: number | null = row.pool_agent_epoch;
+
+    let holderValid = false;
+    if (currentAgentId) {
+      const holder = getAgent(currentAgentId);
+      if (holder && holder.status !== "offline" && holder.ready && holder.lastSeen > now - STALE_TTL_MS && agentCanServeChannel(holder, channelId)) {
+        if (currentEpoch === null || holder.epoch === currentEpoch) {
+          db.prepare("UPDATE channel_bindings SET pool_claim_expires_at = ? WHERE id = ?")
+            .run(now + POOL_CLAIM_LEASE_MS, bindingId);
+          holderValid = true;
+        }
+      }
+    }
+
+    if (!holderValid && currentAgentId) {
+      db.prepare("UPDATE channel_bindings SET pool_agent_id = NULL, pool_agent_epoch = NULL, pool_claim_expires_at = NULL WHERE id = ?")
+        .run(bindingId);
+      changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: null });
+    }
+
+    if (!holderValid) {
+      const candidates = listAgents().filter((a) =>
+        a.id !== "user" && a.id !== "system" && a.kind !== "channel" && a.meta?.kind !== "channel"
+      );
+      const eligible = poolSelectorMatches(selector, candidates)
+        .filter((a) => agentCanServeChannel(a, channelId))
+        .filter((a) => a.status !== "offline" && a.ready && a.lastSeen > now - STALE_TTL_MS)
+        .sort((a, b) => b.lastSeen - a.lastSeen);
+
+      if (eligible.length > 0) {
+        const picked = eligible[0]!;
+        db.prepare("UPDATE channel_bindings SET pool_agent_id = ?, pool_agent_epoch = ?, pool_claim_expires_at = ? WHERE id = ?")
+          .run(picked.id, picked.epoch, now + POOL_CLAIM_LEASE_MS, bindingId);
+        const lastChange = changes[changes.length - 1];
+        if (lastChange && lastChange.bindingId === bindingId && lastChange.newAgentId === null) {
+          lastChange.newAgentId = picked.id;
+        } else {
+          changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: picked.id });
+        }
+      }
+    }
+  }
+
+  return changes;
+}
+
 export function resolveChannelRoutes(channelId: string, conversationId?: string): ChannelBinding[] {
   const rows = conversationId
     ? db.prepare(`
@@ -1103,17 +1375,13 @@ export function resolveChannelRoutes(channelId: string, conversationId?: string)
   return (exact.length ? exact : rows.filter((row) => row.conversation_key === "")).map(rowToChannelBinding);
 }
 
-export function resolveChannelRoute(channelId: string, conversationId?: string): ChannelBinding | null {
-  return resolveChannelRoutes(channelId, conversationId)[0] ?? null;
-}
-
 export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   const now = Date.now();
   const cutoff = now - ttlMs;
   db.prepare("UPDATE agents SET last_seen = ? WHERE id IN ('user', 'system')").run(now);
   const rows = db
     .prepare(
-      "UPDATE agents SET status = 'offline', ready = 0 WHERE status != 'offline' AND last_seen < ? AND id NOT IN ('user', 'system') RETURNING id"
+      "UPDATE agents SET status = 'offline', ready = 0 WHERE status NOT IN ('offline', 'stale') AND last_seen < ? AND id NOT IN ('user', 'system') RETURNING id"
     )
     .all(cutoff) as any[];
   for (const row of rows) closeOpenPairsForAgent(row.id, now);
@@ -1411,6 +1679,63 @@ export function releaseExpiredClaims(now: number = Date.now()): { messageIds: nu
   })();
 }
 
+export function orphanTasksForAgent(agentId: string, now: number = Date.now()): Task[] {
+  return db.transaction(() => {
+    const rows = db
+      .prepare(`${TASK_SELECT} WHERE claimed_by = ? AND status IN ('claimed', 'in_progress')`)
+      .all(agentId) as any[];
+    if (rows.length === 0) return [];
+
+    db.prepare(`
+      UPDATE tasks
+      SET status = 'orphaned', updated_at = ?, last_seen_at = ?
+      WHERE claimed_by = ? AND status IN ('claimed', 'in_progress')
+    `).run(now, now, agentId);
+
+    for (const row of rows) {
+      insertTaskEvent(row.id, {
+        source: "agent-relay",
+        type: "task.orphaned",
+        severity: row.severity,
+        title: "Task orphaned",
+        body: `Claimed agent ${agentId} went offline`,
+        metadata: { agentId },
+      }, now);
+    }
+
+    return rows.map((row: any) => getTask(row.id)!);
+  })();
+}
+
+export function releaseOrphanedTasks(graceMs = 120_000, now: number = Date.now()): Task[] {
+  return db.transaction(() => {
+    const cutoff = now - graceMs;
+    const rows = db
+      .prepare(`${TASK_SELECT} WHERE status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?`)
+      .all(cutoff) as any[];
+    if (rows.length === 0) return [];
+
+    db.prepare(`
+      UPDATE tasks
+      SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ?
+      WHERE status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?
+    `).run(now, cutoff);
+
+    for (const row of rows) {
+      insertTaskEvent(row.id, {
+        source: "agent-relay",
+        type: "orphan.released",
+        severity: row.severity,
+        title: "Orphaned task released",
+        body: "Task is available for claim again",
+        metadata: { previousAgentId: row.claimed_by },
+      }, now);
+    }
+
+    return rows.map((row: any) => getTask(row.id)!);
+  })();
+}
+
 export function claimTask(taskId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
   releaseExpiredClaims();
   const session = validateAgentSession(agentId, guard);
@@ -2429,6 +2754,7 @@ function rowToOrchestrator(row: any): Orchestrator {
     agentId: row.agent_id,
     providers: parseJson<SpawnProvider[]>(row.providers, []),
     baseDir: row.base_dir,
+    ...(row.api_url ? { apiUrl: row.api_url } : {}),
     envKeys: parseJson<string[]>(row.env_keys, []),
     ...(version ? { version } : {}),
     ...(Number.isFinite(protocolVersion) ? { protocolVersion } : {}),
@@ -2464,17 +2790,27 @@ function orchestratorHealth(version: string | undefined, protocolVersion: number
   };
 }
 
+function mergeOrchestratorRuntimeMeta(meta: Record<string, unknown>, input: OrchestratorRuntimeInput): Record<string, unknown> {
+  return {
+    ...meta,
+    ...(input.version ? { version: input.version } : {}),
+    ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
+    ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+  };
+}
+
 export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrator {
   const now = Date.now();
   const agentId = `orchestrator-${input.id}`;
   const stmt = db.prepare(`
-    INSERT INTO orchestrators (id, hostname, status, agent_id, providers, base_dir, env_keys, meta, last_seen, created_at)
-    VALUES ($id, $hostname, 'online', $agentId, $providers, $baseDir, $envKeys, $meta, $now, $now)
+    INSERT INTO orchestrators (id, hostname, status, agent_id, providers, base_dir, api_url, env_keys, meta, last_seen, created_at)
+    VALUES ($id, $hostname, 'online', $agentId, $providers, $baseDir, $apiUrl, $envKeys, $meta, $now, $now)
     ON CONFLICT(id) DO UPDATE SET
       hostname = $hostname,
       status = 'online',
       providers = $providers,
       base_dir = $baseDir,
+      api_url = $apiUrl,
       env_keys = $envKeys,
       meta = $meta,
       last_seen = $now
@@ -2485,13 +2821,9 @@ export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrat
     $agentId: agentId,
     $providers: JSON.stringify(input.providers),
     $baseDir: input.baseDir,
+    $apiUrl: input.apiUrl ?? null,
     $envKeys: JSON.stringify(input.envKeys ?? []),
-    $meta: JSON.stringify({
-      ...(input.meta ?? {}),
-      ...(input.version ? { version: input.version } : {}),
-      ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
-      ...(input.gitSha ? { gitSha: input.gitSha } : {}),
-    }),
+    $meta: JSON.stringify(mergeOrchestratorRuntimeMeta(input.meta ?? {}, input)),
     $now: now,
   });
 
@@ -2503,6 +2835,7 @@ export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrat
     machine: input.hostname,
     capabilities: ["orchestrator", "spawn"],
     status: "online",
+    ready: true,
     meta: {
       orchestratorId: input.id,
       builtin: true,
@@ -2524,9 +2857,12 @@ export function listOrchestrators(): Orchestrator[] {
   return (db.prepare("SELECT * FROM orchestrators ORDER BY hostname").all() as any[]).map(rowToOrchestrator);
 }
 
-export function orchestratorHeartbeat(id: string): Orchestrator | null {
+export function orchestratorHeartbeat(id: string, runtime: OrchestratorRuntimeInput = {}): Orchestrator | null {
   const now = Date.now();
-  db.prepare("UPDATE orchestrators SET last_seen = ?, status = 'online' WHERE id = ?").run(now, id);
+  const row = db.prepare("SELECT meta FROM orchestrators WHERE id = ?").get(id) as { meta?: string } | undefined;
+  if (!row) return null;
+  const meta = mergeOrchestratorRuntimeMeta(parseJson<Record<string, unknown>>(row.meta ?? "{}", {}), runtime);
+  db.prepare("UPDATE orchestrators SET last_seen = ?, status = 'online', meta = ? WHERE id = ?").run(now, JSON.stringify(meta), id);
   // Also heartbeat the agent
   const orch = getOrchestrator(id);
   if (orch) {
@@ -2535,15 +2871,6 @@ export function orchestratorHeartbeat(id: string): Orchestrator | null {
   return orch;
 }
 
-export function setOrchestratorStatus(id: string, status: OrchestratorStatus): Orchestrator | null {
-  db.prepare("UPDATE orchestrators SET status = ?, last_seen = ? WHERE id = ?").run(status, Date.now(), id);
-  const orch = getOrchestrator(id);
-  if (orch) {
-    setStatus(orch.agentId, status === "online" ? "online" : "offline");
-  }
-  return orch;
-}
-
 export function updateManagedAgents(id: string, agents: ManagedAgent[]): Orchestrator | null {
   db.prepare("UPDATE orchestrators SET managed_agents = ?, last_seen = ? WHERE id = ?")
     .run(JSON.stringify(agents), Date.now(), id);

package/src/events.ts

@@ -0,0 +1,33 @@
+import { appendEvent } from "./bus-outbox";
+
+export interface RelayEvent {
+  seq: number;
+  type: string;
+  source: string;
+  subject?: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+type Listener = (event: RelayEvent) => void;
+
+const listeners = new Set<Listener>();
+
+export function emitRelayEvent(input: Omit<RelayEvent, "seq" | "timestamp">): RelayEvent {
+  const timestamp = Date.now();
+  const seq = appendEvent(input.type, input.source, input.data, input.subject);
+  const event: RelayEvent = { ...input, seq, timestamp };
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch {
+      // Event projections are isolated so one transport cannot block another.
+    }
+  }
+  return event;
+}
+
+export function subscribeRelayEvents(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}