agent-relay-server 0.4.38 → 0.5.0

package/src/routes.ts

@@ -46,12 +46,20 @@ import {
   createCallbackDelivery,
   finishCallbackDelivery,
   reapStaleAgents,
+  reapStaleOrchestrators,
   releaseExpiredClaims,
   validateAgentSession,
+  upsertOrchestrator,
+  getOrchestrator,
+  listOrchestrators,
+  orchestratorHeartbeat,
+  updateManagedAgents,
+  deleteOrchestrator,
   ValidationError,
 } from "./db";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
+import { listHostDirectories, spawnCodexAgent, type CodexSpawnApprovalMode } from "./agent-spawn";
 import {
   getIntegrationAuth,
   hasIntegrationScope,
@@ -66,6 +74,8 @@ import {
   emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
+  emitOrchestratorStatus,
+  emitOrchestratorRemoved,
 } from "./sse";
 
 type Handler = (
@@ -150,6 +160,9 @@ function parseQueryInt(
 }
 
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "offline"] as const;
+const VALID_AGENT_ACTIONS = ["restart", "shutdown"] as const;
+const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
+const VALID_CODEX_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
 const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
 const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "done", "failed", "canceled"] as const;
 const VALID_PAIR_STATUSES = ["pending", "active", "ended", "rejected", "expired"] as const;
@@ -738,6 +751,356 @@ const deleteAgentById: Handler = (_req, params) => {
   return json({ ok: true });
 };
 
+function agentCanReceiveControlAction(agent: AgentCard): boolean {
+  return agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.meta?.kind !== "channel" &&
+    !agent.tags.includes("channel");
+}
+
+const postAgentAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("action required");
+    const action = cleanEnum(parsed.body.action, "action", VALID_AGENT_ACTIONS);
+    if (!action) return error("action required");
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    if (!agentCanReceiveControlAction(agent)) return error("agent does not support dashboard control actions", 400);
+
+    const title = action === "restart" ? "Agent restart requested" : "Agent shutdown requested";
+    const msg = sendMessage({
+      from: "system",
+      to: agent.id,
+      type: "system",
+      subject: title,
+      body: action === "restart"
+        ? "Dashboard requested that this agent restart its relay-managed session now."
+        : "Dashboard requested that this agent shut down its relay-managed session now.",
+      meta: {
+        agentControl: {
+          action,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-agent-" + agent.id + "-action-" + action + "-" + msg.id,
+      kind: "state",
+      title,
+      body: action,
+      meta: agent.id,
+      icon: action === "restart" ? "ti-refresh" : "ti-power",
+      view: "agents",
+      messageId: msg.id,
+      agentId: agent.id,
+      metadata: { action },
+    });
+    return json({ ok: true, action, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postAgentSpawn: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("provider required");
+    const provider = cleanEnum(parsed.body.provider, "provider", [...VALID_AGENT_SPAWN_PROVIDERS, "claude"] as const);
+    if (!provider) return error("provider required");
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as CodexSpawnApprovalMode;
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+
+    // Check for an online orchestrator that supports this provider
+    const orchestrators = listOrchestrators().filter(
+      (o) => o.status === "online" && o.providers.includes(provider as SpawnProvider),
+    );
+    if (orchestrators.length > 0) {
+      // Route through the first available orchestrator
+      const orch = orchestrators[0]!;
+      const msg = sendMessage({
+        from: "system",
+        to: orch.agentId,
+        type: "system",
+        subject: "Spawn agent",
+        body: JSON.stringify({ action: "spawn", provider, cwd, label, approvalMode }),
+        meta: {
+          orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() },
+          delivery: "interrupt",
+          priority: "urgent",
+        },
+      });
+      emitNewMessage(msg);
+      auditEvent({
+        clientId: "server-agent-spawn-" + provider + "-" + Date.now(),
+        kind: "state",
+        title: `${provider} agent spawn requested (via ${orch.id})`,
+        body: cwd || orch.baseDir,
+        meta: orch.id,
+        icon: "ti-plus",
+        view: "agents",
+        metadata: { provider, orchestratorId: orch.id, approvalMode },
+      });
+      return json({ ok: true, orchestratorId: orch.id, provider, message: msg }, 202);
+    }
+
+    // Fallback: direct spawn for codex only (no orchestrator)
+    if (provider !== "codex") return error("no orchestrator available for provider: " + provider);
+    const relayUrl = process.env.AGENT_RELAY_SPAWN_RELAY_URL || process.env.AGENT_RELAY_URL || `http://127.0.0.1:${process.env.PORT || "4850"}`;
+    const token = req.headers.get("X-Agent-Relay-Token") ?? req.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
+    const result = spawnCodexAgent({
+      cwd,
+      approvalMode,
+      label,
+      relayUrl,
+      token: token || undefined,
+      dryRun: process.env.AGENT_RELAY_SPAWN_DRY_RUN === "1",
+    });
+    auditEvent({
+      clientId: "server-agent-spawn-codex-" + Date.now(),
+      kind: "state",
+      title: "Codex agent spawn requested (direct)",
+      body: result.cwd,
+      meta: result.pid ? `pid ${result.pid}` : "dry run",
+      icon: "ti-plus",
+      view: "agents",
+      metadata: {
+        provider: result.provider,
+        approvalMode: result.approvalMode,
+        pid: result.pid ?? null,
+        logPath: result.logPath,
+        dryRun: result.dryRun === true,
+      },
+    });
+    return json(result, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getHostDirectories: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const path = cleanString(url.searchParams.get("path") ?? undefined, "path", { max: 500 });
+    return json(listHostDirectories(path));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof Error) return error(e.message, 400);
+    throw e;
+  }
+};
+
+// --- Orchestrator routes ---
+
+const VALID_ORCHESTRATOR_PROVIDERS = ["claude", "codex"] as const;
+const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
+
+const postOrchestrator: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
+    const hostname = cleanString(parsed.body.hostname, "hostname", { required: true, max: 120 })!;
+    const baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
+    const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
+    if (providers) {
+      for (const p of providers) {
+        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
+          return error(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        }
+      }
+    }
+    const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys");
+    const meta = cleanMeta(parsed.body.meta);
+    const orch = upsertOrchestrator({ id, hostname, providers: providers ?? ["claude", "codex"], baseDir, envKeys, meta });
+    auditEvent({
+      clientId: "server-orchestrator-register-" + id + "-" + Date.now(),
+      kind: "state",
+      title: "Orchestrator registered",
+      body: hostname,
+      meta: id,
+      icon: "ti-server-2",
+      view: "orchestrators",
+      metadata: { orchestratorId: id, providers: orch.providers },
+    });
+    return json(orch, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getOrchestrators: Handler = () => {
+  return json(listOrchestrators());
+};
+
+const getOrchestratorById: Handler = (_req, params) => {
+  const orch = getOrchestrator(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json(orch);
+};
+
+const postOrchestratorHeartbeat: Handler = (_req, params) => {
+  const orch = orchestratorHeartbeat(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
+const patchOrchestratorAgents: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (!isRecord(parsed.body)) return error("body required");
+    const agents = parsed.body.agents;
+    if (!Array.isArray(agents)) return error("agents must be an array");
+    const cleaned: ManagedAgent[] = agents.map((a: any) => {
+      if (!isRecord(a)) throw new ValidationError("each agent must be an object");
+      return {
+        agentId: cleanString(a.agentId, "agentId", { required: true, max: 240 })!,
+        provider: cleanEnum(a.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider,
+        tmuxSession: cleanString(a.tmuxSession, "tmuxSession", { required: true, max: 240 })!,
+        cwd: cleanString(a.cwd, "cwd", { required: true, max: 500 })!,
+        label: cleanString(a.label, "label", { max: 120 }),
+        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") ?? "guarded") as SpawnApprovalMode,
+        pid: typeof a.pid === "number" && Number.isSafeInteger(a.pid) ? a.pid : undefined,
+        startedAt: typeof a.startedAt === "number" ? a.startedAt : Date.now(),
+      };
+    });
+    const updated = updateManagedAgents(params.id!, cleaned);
+    return json(updated);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postOrchestratorSpawn: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (orch.status !== "online") return error("orchestrator is offline", 409);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    if (!orch.providers.includes(provider)) {
+      return error(`orchestrator does not support provider: ${provider}`);
+    }
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    if (cwd && !cwd.startsWith(orch.baseDir)) {
+      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
+    }
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const prompt = cleanString(parsed.body.prompt, "prompt", { max: 4000 });
+
+    // Send control message to orchestrator's agent inbox
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      type: "system",
+      subject: "Spawn agent",
+      body: JSON.stringify({ action: "spawn", provider, cwd: cwd || orch.baseDir, label, approvalMode, prompt }),
+      meta: {
+        orchestratorControl: {
+          action: "spawn",
+          provider,
+          cwd: cwd || orch.baseDir,
+          label,
+          approvalMode,
+          prompt,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-spawn-" + orch.id + "-" + Date.now(),
+      kind: "state",
+      title: `Spawn ${provider} agent requested`,
+      body: cwd || orch.baseDir,
+      meta: orch.id,
+      icon: "ti-plus",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, provider, approvalMode, label },
+    });
+    return json({ ok: true, orchestratorId: orch.id, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postOrchestratorAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown"] as const);
+    if (!action) return error("action required");
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      type: "system",
+      subject: action === "restart" ? "Restart agent" : "Shutdown agent",
+      body: JSON.stringify({ action, agentId }),
+      meta: {
+        orchestratorControl: {
+          action,
+          agentId,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-action-" + orch.id + "-" + action + "-" + Date.now(),
+      kind: "state",
+      title: `Agent ${action} requested`,
+      body: agentId || "all",
+      meta: orch.id,
+      icon: action === "restart" ? "ti-refresh" : "ti-power",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, action, agentId },
+    });
+    return json({ ok: true, action, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteOrchestratorById: Handler = (_req, params) => {
+  const deleted = deleteOrchestrator(params.id!);
+  if (!deleted) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
 // --- Message routes ---
 
 const VALID_MSG_TYPES = ["message", "system"];
@@ -1369,20 +1732,23 @@ const getHealthRoute: Handler = () => json(getHealth());
 const postSystemReap: Handler = () => {
   const released = releaseExpiredClaims();
   const reapedAgentIds = reapStaleAgents();
+  const reapedOrchestratorIds = reapStaleOrchestrators();
   for (const id of released.messageIds) emitMessageClaimReleased(id);
   for (const task of released.tasks) emitTaskChanged(task, "task.updated");
   for (const id of reapedAgentIds) emitAgentStatus(id);
+  for (const id of reapedOrchestratorIds) emitOrchestratorStatus(id);
   auditEvent({
     clientId: "server-system-reap-" + Date.now(),
     kind: "state",
     title: "Maintenance reaper run",
-    body: `${reapedAgentIds.length} stale agent(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
+    body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
     icon: "ti-broom",
     view: "activity",
   });
   return json({
     ok: true,
     reapedAgentIds,
+    reapedOrchestratorIds,
     releasedMessageIds: released.messageIds,
     releasedTaskIds: released.tasks.map((task) => task.id),
   });
@@ -1412,16 +1778,28 @@ function route(method: string, path: string, handler: Handler): Route {
 
 const routes: Route[] = [
   route("POST", "/api/agents", postAgent),
+  route("POST", "/api/agents/spawn", postAgentSpawn),
   route("GET", "/api/agents", getAgents),
   route("GET", "/api/agents/find", findAgents),
+  route("GET", "/api/agents/spawn/directories", getHostDirectories),
   route("GET", "/api/agents/:id", getAgentById),
   route("PATCH", "/api/agents/:id/status", patchAgentStatus),
   route("PATCH", "/api/agents/:id/ready", patchAgentReady),
   route("PATCH", "/api/agents/:id/label", patchAgentLabel),
   route("PATCH", "/api/agents/:id/tags", patchAgentTags),
   route("POST", "/api/agents/:id/heartbeat", postHeartbeat),
+  route("POST", "/api/agents/:id/actions", postAgentAction),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
+  route("POST", "/api/orchestrators", postOrchestrator),
+  route("GET", "/api/orchestrators", getOrchestrators),
+  route("GET", "/api/orchestrators/:id", getOrchestratorById),
+  route("POST", "/api/orchestrators/:id/heartbeat", postOrchestratorHeartbeat),
+  route("PATCH", "/api/orchestrators/:id/agents", patchOrchestratorAgents),
+  route("POST", "/api/orchestrators/:id/spawn", postOrchestratorSpawn),
+  route("POST", "/api/orchestrators/:id/actions", postOrchestratorAction),
+  route("DELETE", "/api/orchestrators/:id", deleteOrchestratorById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("POST", "/api/messages", postMessage),
   route("GET", "/api/messages", getMessages),

package/src/sse.ts

@@ -1,4 +1,4 @@
-import { getAgent } from "./db";
+import { getAgent, getOrchestrator } from "./db";
 import type { Message, Task } from "./types";
 
 interface Connection {
@@ -135,3 +135,17 @@ function targetMatchesAgent(target: string, agentId: string): boolean {
   if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
   return false;
 }
+
+export function emitOrchestratorStatus(orchestratorId: string) {
+  const orch = getOrchestrator(orchestratorId);
+  const data = orch ?? { id: orchestratorId, status: "offline" };
+  for (const conn of connections.values()) {
+    send(conn, "orchestrator.status", data);
+  }
+}
+
+export function emitOrchestratorRemoved(orchestratorId: string) {
+  for (const conn of connections.values()) {
+    send(conn, "orchestrator.removed", { id: orchestratorId });
+  }
+}

package/src/types.ts

@@ -291,6 +291,66 @@ export interface ActivityEventInput {
   metadata?: Record<string, unknown>;
 }
 
+// --- Orchestrators ---
+
+export type OrchestratorStatus = "online" | "offline";
+export type SpawnProvider = "claude" | "codex";
+export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+
+export interface Orchestrator {
+  id: string;
+  hostname: string;
+  status: OrchestratorStatus;
+  agentId: string; // relay agent id for messaging
+  providers: SpawnProvider[];
+  baseDir: string;
+  envKeys: string[]; // names only, never values
+  meta: Record<string, unknown>;
+  managedAgents: ManagedAgent[];
+  lastSeen: number;
+  createdAt: number;
+}
+
+export interface ManagedAgent {
+  agentId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
+export interface RegisterOrchestratorInput {
+  id: string;
+  hostname: string;
+  providers: SpawnProvider[];
+  baseDir: string;
+  envKeys?: string[];
+  meta?: Record<string, unknown>;
+}
+
+export interface OrchestratorSpawnInput {
+  provider: SpawnProvider;
+  cwd?: string;
+  label?: string;
+  approvalMode?: SpawnApprovalMode;
+  prompt?: string;
+  env?: Record<string, string>;
+}
+
+export interface OrchestratorSpawnResult {
+  orchestratorId: string;
+  provider: SpawnProvider;
+  tmuxSession: string;
+  cwd: string;
+  label?: string;
+  approvalMode: SpawnApprovalMode;
+  pid?: number;
+  startedAt: number;
+}
+
 export interface HealthCheck {
   name: string;
   status: "ok" | "warn" | "error";