agent-relay-server 0.32.2 → 0.32.4

package/src/routes/agent-profiles.ts

@@ -0,0 +1,47 @@
+// Auto-split from routes.ts (#299). Domain: agent-profiles.
+import { ValidationError } from "../db";
+import { cleanString } from "../validation";
+import { deleteAgentProfile, getAgentProfile, listAgentProfiles, setAgentProfile } from "../config-store";
+import { emitConfigChanged } from "../sse";
+import { error, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
+import { isRecord } from "agent-relay-sdk";
+import { type AgentProfile } from "../types";
+
+export const getAgentProfilesRoute: Handler = () => json(listAgentProfiles());
+
+export const getAgentProfileRoute: Handler = (_req, params) => {
+  const name = normalizeConfigPathParam(params.name, "name");
+  const profile = getAgentProfile(name);
+  return profile ? json(profile) : error("agent profile not found", 404);
+};
+
+export const putAgentProfileRoute: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("agent profile body required");
+    const name = normalizeConfigPathParam(params.name, "name");
+    const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
+    const profile = setAgentProfile({ ...parsed.body, name } as AgentProfile, updatedBy);
+    emitConfigChanged(profile.namespace, profile.key, profile.version);
+    return json(profile, profile.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteAgentProfileRoute: Handler = (req, params) => {
+  try {
+    const name = normalizeConfigPathParam(params.name, "name");
+    const existing = getAgentProfile(name);
+    if (!existing || existing.value.builtIn) return error(existing ? "built-in agent profiles are managed by Relay" : "agent profile not found", existing ? 400 : 404);
+    const updatedBy = cleanString(new URL(req.url).searchParams.get("updatedBy") ?? undefined, "updatedBy", { max: 200 });
+    deleteAgentProfile(name, updatedBy);
+    emitConfigChanged(existing.namespace, existing.key, existing.version + 1);
+    return json({ ok: true });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routes/agent-sessions.ts

@@ -0,0 +1,488 @@
+// Auto-split from routes.ts (#299). Domain: agent-sessions.
+import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage } from "../db";
+import { buildManagedSpawnParams } from "../managed-policy";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
+import { cleanString, optionalEnum } from "../validation";
+import { createCommand } from "../commands-db";
+import { emitAgentStatus, emitNewMessage } from "../sse";
+import { getAgentProfile, getSpawnPolicy } from "../config-store";
+import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { type AgentCard, type SpawnApprovalMode } from "../types";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+
+const CLAUDE_RESUME_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function metaStringArray(meta: Record<string, unknown> | undefined, key: string): string[] {
+  const value = meta?.[key];
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : [];
+}
+
+function agentControlActionCommandType(action: AgentControlAction): "agent.restart" | "agent.shutdown" | "agent.reconnect" | "agent.compact" | "agent.clearContext" | "agent.interrupt" {
+  if (action === "restart" || action === "resume") return "agent.restart";
+  if (action === "shutdown") return "agent.shutdown";
+  if (action === "compact") return "agent.compact";
+  if (action === "clearContext") return "agent.clearContext";
+  if (action === "interrupt") return "agent.interrupt";
+  return "agent.reconnect";
+}
+
+function agentControlActionRequestedTitle(action: AgentControlAction): string {
+  if (action === "restart") return "Agent restart requested";
+  if (action === "resume") return "Agent resume requested";
+  if (action === "shutdown") return "Agent shutdown requested";
+  if (action === "compact") return "Agent compaction requested";
+  if (action === "clearContext") return "Agent context clear requested";
+  if (action === "interrupt") return "Agent interrupt requested";
+  return "Agent reconnect requested";
+}
+
+function agentIsControlEligible(agent: AgentCard): boolean {
+  return agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.meta?.kind !== "channel" &&
+    !agent.tags.includes("channel");
+}
+
+function agentCanReceiveControlAction(agent: AgentCard, action: AgentControlAction): boolean {
+  if (!agentIsControlEligible(agent)) return false;
+  if (action === "resume") return agentRuntimeProvider(agent) === "claude" && (agent.status === "offline" || agent.status === "stale");
+  // Interrupt only makes sense while the provider is mid-turn, and only if the
+  // provider advertises it can be interrupted from the dashboard.
+  if (action === "interrupt") return agent.providerCapabilities?.liveSession?.interrupt === true && agent.status === "busy";
+  const lifecycle = agent.providerCapabilities?.lifecycle;
+  if (lifecycle) {
+    if (action === "restart") return lifecycle.restartHard === true;
+    if (action === "shutdown") return lifecycle.shutdownHard === true;
+    if (action === "reconnect") return lifecycle.reconnect === true;
+  }
+  if (action === "compact") return agent.providerCapabilities?.context?.compact === true;
+  if (action === "clearContext") return agent.providerCapabilities?.context?.clear === true;
+  return agent.meta?.runnerManaged === true && (action === "restart" || action === "shutdown");
+}
+
+function agentRuntimeProvider(agent: AgentCard): string | undefined {
+  return metaString(agent.meta, "provider") ?? agent.providerCapabilities?.model?.provider;
+}
+
+function managedControlOrchestrator(agent: AgentCard): NonNullable<ReturnType<typeof getOrchestrator>> | null {
+  if (agent.meta?.runnerManaged !== true) return null;
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  const candidates = [
+    ...listManagedOrchestratorsForAgent({
+      agentId: agent.id,
+      sessionName: str(agent.meta.sessionName),
+      tmuxSession: str(agent.meta.tmuxSession),
+      policyName: str(agent.meta.policyName),
+      spawnRequestId: str(agent.meta.spawnRequestId),
+    }),
+    ...(agent.machine ? [getOrchestrator(agent.machine)].filter((orch): orch is NonNullable<ReturnType<typeof getOrchestrator>> => Boolean(orch)) : []),
+  ];
+  return candidates.find((orch) => orch.status === "online") ?? null;
+}
+
+function restartSpawnParamsForAgent(
+  agent: AgentCard,
+  orchestrator: NonNullable<ReturnType<typeof getOrchestrator>> | null,
+  policyName?: string,
+  spawnRequestId?: string,
+  opts: { resumeId?: string } = {},
+): Record<string, unknown> | undefined {
+  if (!orchestrator) return undefined;
+  const requestId = spawnRequestId ?? spawnRequestIdForRestart();
+  const policy = policyName ? getSpawnPolicy(policyName) : null;
+  const requestedBy = opts.resumeId ? "dashboard-resume" : "dashboard-restart";
+  if (policy) {
+    const params = { ...buildManagedSpawnParams(policy.value, requestId, { createdBy: "managed-agent" }), agentId: agent.id, requestedBy };
+    return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
+  }
+
+  const provider = metaString(agent.meta, "provider");
+  if (provider !== "claude" && provider !== "codex") return undefined;
+  const cwd = metaString(agent.meta, "cwd") ?? orchestrator.baseDir;
+  const label = metaString(agent.meta, "label") ?? agent.label;
+  const approvalMode = metaString(agent.meta, "approvalMode") as SpawnApprovalMode | undefined;
+  const model = metaString(agent.meta, "model");
+  const effort = metaString(agent.meta, "effort") as ProviderEffort | undefined;
+  const providerArgs = metaStringArray(agent.meta, "providerArgs");
+  const profileName = metaString(agent.meta, "profile");
+  const agentProfile = profileName ? getAgentProfile(profileName)?.value : undefined;
+  const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
+  const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
+  const params = buildSpawnCommand({
+    provider,
+    modelParams: resolvedModel,
+    cwd,
+    workspaceMode,
+    profile: profileName || undefined,
+    agentProfile,
+    label: label || undefined,
+    agentId: agent.id,
+    tags: agent.tags,
+    capabilities: agent.capabilities,
+    approvalMode: approvalMode ?? "guarded",
+    permissionMode: approvalMode ?? "guarded",
+    providerArgs: providerArgs.length ? providerArgs : undefined,
+    policyName: policyName || undefined,
+    headless: true,
+    spawnRequestId: requestId,
+    env: runnerRuntimeTokenEnv({
+      orchestratorId: orchestrator.id,
+      cwd,
+      provider,
+      label,
+      policyName,
+      spawnRequestId: requestId,
+      createdBy: requestedBy,
+      profile: profileName || undefined,
+    }),
+    requestedBy,
+    requestedAt: Date.now(),
+  });
+  return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
+}
+
+function spawnRequestIdForRestart(): string {
+  return generateSpawnRequestId();
+}
+
+function withClaudeResumeParams(params: Record<string, unknown>, resumeId: string, agentId: string): Record<string, unknown> {
+  return {
+    ...params,
+    providerArgs: providerArgsWithClaudeResume(recordStringArray(params.providerArgs), resumeId),
+    resumeOfAgentId: agentId,
+    claudeResumeId: resumeId,
+  };
+}
+
+function providerArgsWithClaudeResume(args: string[], resumeId: string): string[] {
+  const cleaned: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg === "--resume") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--resume=")) continue;
+    cleaned.push(arg);
+  }
+  return [...cleaned, "--resume", resumeId];
+}
+
+function recordStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : [];
+}
+
+function latestClaudeResumeIdForAgent(agent: AgentCard): string | undefined {
+  for (const entry of getAgentTimeline(agent.id, { limit: 50 })) {
+    const metadata = entry.metadata;
+    if (!metadata) continue;
+    const provider = metaString(metadata, "provider");
+    const resumeId = metaString(metadata, "claudeResumeId");
+    if (provider === "claude" && resumeId && CLAUDE_RESUME_ID_RE.test(resumeId)) return resumeId;
+  }
+  return undefined;
+}
+
+function compactMemoryParams(agent: AgentCard): Record<string, unknown> {
+  const alwaysReload = agent.tags
+    .filter((tag) => tag.startsWith("memory-reload:"))
+    .map((tag) => tag.slice("memory-reload:".length).trim())
+    .filter(Boolean);
+  if (!alwaysReload.length) return {};
+  return { memory: { alwaysReload } };
+}
+
+export 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 = optionalEnum(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, action)) return error(`agent does not support ${action}`, 400);
+
+    const orchestrator = (action === "restart" || action === "shutdown" || action === "resume") ? managedControlOrchestrator(agent) : null;
+    const metaSessionName = typeof agent.meta?.sessionName === "string" ? agent.meta.sessionName : undefined;
+    const metaTmuxSession = typeof agent.meta?.tmuxSession === "string" ? agent.meta.tmuxSession : undefined;
+    const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
+    const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
+    const resumeId = action === "resume" ? latestClaudeResumeIdForAgent(agent) : undefined;
+    if (action === "resume" && !orchestrator) return error("no online orchestrator available to resume agent", 409);
+    if (action === "resume" && !resumeId) return error("no Claude resume id recorded for agent", 422);
+    const denied = authorizeRoute(req, {
+      scope: "agent:write",
+      resource: { agentId: agent.id, orchestratorId: orchestrator?.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId },
+    });
+    if (denied) return denied;
+    const command = createCommand({
+      type: agentControlActionCommandType(action),
+      source: "system",
+      target: orchestrator?.agentId ?? agent.id,
+      correlationId: metaSpawnRequestId,
+      params: {
+        action,
+        agentId: agent.id,
+        ...(orchestrator ? { orchestratorId: orchestrator.id } : {}),
+        ...(metaSessionName ? { sessionName: metaSessionName } : {}),
+        ...(metaTmuxSession ? { tmuxSession: metaTmuxSession } : {}),
+        ...(metaPolicyName ? { policyName: metaPolicyName } : {}),
+        ...(metaSpawnRequestId ? { spawnRequestId: metaSpawnRequestId } : {}),
+        ...(action === "restart" || action === "resume" ? { restartSpawn: restartSpawnParamsForAgent(agent, orchestrator, metaPolicyName, metaSpawnRequestId, { resumeId }) } : {}),
+        ...(action === "compact" ? compactMemoryParams(agent) : {}),
+        ...(resumeId ? { claudeResumeId: resumeId } : {}),
+        requestedBy: "dashboard",
+        requestedAt: Date.now(),
+      },
+    });
+    if (action === "shutdown" || action === "restart" || action === "resume") {
+      const lifecycleAction = action === "shutdown" ? "shutting-down" : action === "resume" ? "resuming" : "restarting";
+      markReady(agent.id, false);
+      mergeAgentMeta(agent.id, { lifecycleAction, lifecycleActionAt: Date.now(), lifecycleCommandId: command.id });
+      emitAgentStatus(agent.id);
+    }
+    emitCommand(command);
+    auditEvent({
+      clientId: "server-agent-" + agent.id + "-action-" + action + "-" + command.id,
+      kind: "state",
+      title: agentControlActionRequestedTitle(action),
+      body: action,
+      meta: agent.id,
+      icon: agentControlActionIcon(action),
+      view: "agents",
+      agentId: agent.id,
+      metadata: { action, commandId: command.id, ...(orchestrator ? { orchestratorId: orchestrator.id } : {}), ...authAuditMetadata(req), ...dashboardAttribution(req, parsed.body.surface) },
+    });
+    return json({ ok: true, action, command }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postAgentPrompt: 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("body required");
+    const body = cleanString(parsed.body.body, "body", { required: true, max: 100_000 })!;
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    if (agent.status === "offline") return error("agent is offline", 422);
+    const denied = authorizeRoute(req, {
+      scope: "message:send",
+      resource: { target: agent.id, agentId: "user" },
+    });
+    if (denied) return denied;
+    const message = sendMessage({
+      from: "user",
+      to: agent.id,
+      kind: "session",
+      body,
+    });
+    const command = createCommand({
+      type: "prompt.inject",
+      source: "dashboard",
+      target: agent.id,
+      params: { body, messageId: message.id },
+    });
+    emitCommand(command);
+    emitNewMessage(message);
+    auditEvent({
+      clientId: "server-prompt-inject-" + message.id,
+      kind: "message",
+      title: "Prompt injected",
+      body,
+      meta: `user -> ${agent.id}`,
+      icon: "ti-message-bolt",
+      view: "messages",
+      messageId: message.id,
+      agentId: agent.id,
+    });
+    return json({ ok: true, messageId: message.id, commandId: command.id }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postAgentPermissionDecision: 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("permission decision required");
+    const approvalId = cleanString(parsed.body.approvalId, "approvalId", { required: true, max: 240 })!;
+    const decision = optionalEnum(parsed.body.decision, "decision", ["approve", "approve-session", "deny", "abort", "answer"] as const);
+    if (!decision) return error("decision required");
+    const reason = cleanString(parsed.body.reason, "reason", { max: 500 });
+    // AskUserQuestion answers: { "<question text>": "<chosen label(s)>" }
+    const answers = decision === "answer" && isRecord(parsed.body.answers)
+      ? Object.fromEntries(
+          Object.entries(parsed.body.answers)
+            .filter(([, v]) => typeof v === "string")
+            .map(([k, v]) => [k.slice(0, 2000), (v as string).slice(0, 4000)]),
+        )
+      : undefined;
+    if (decision === "answer" && (!answers || Object.keys(answers).length === 0)) {
+      return error("answers required for answer decision");
+    }
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    if (!agentIsControlEligible(agent)) return error("agent cannot receive permission decisions", 400);
+    const pendingApproval = isRecord(agent.meta?.providerState) && isRecord(agent.meta.providerState.pendingApproval)
+      ? agent.meta.providerState.pendingApproval
+      : null;
+    const pendingId = typeof pendingApproval?.id === "string" ? pendingApproval.id : "";
+    if (pendingId && pendingId !== approvalId) return error("approval request is no longer current", 409);
+    const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
+    const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
+    const denied = authorizeRoute(req, {
+      scope: "agent:write",
+      resource: { agentId: agent.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId },
+    });
+    if (denied) return denied;
+    const command = createCommand({
+      type: "agent.permissionDecision",
+      source: "system",
+      target: agent.id,
+      correlationId: approvalId,
+      ttlMs: 15 * 60 * 1000,
+      params: {
+        agentId: agent.id,
+        approvalId,
+        decision,
+        ...(reason ? { reason } : {}),
+        ...(answers ? { answers } : {}),
+        requestedBy: "dashboard",
+        requestedAt: Date.now(),
+      },
+    });
+    emitCommand(command);
+    auditEvent({
+      clientId: "server-agent-" + agent.id + "-permission-" + approvalId + "-" + command.id,
+      kind: "state",
+      title: "Agent permission decision sent",
+      body: decision,
+      meta: agent.id,
+      icon: decision === "deny" || decision === "abort" ? "ti-circle-x" : "ti-circle-check",
+      view: "chat",
+      agentId: agent.id,
+      metadata: { decision, approvalId, commandId: command.id, ...authAuditMetadata(req) },
+    });
+    return json({ ok: true, decision, command }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postAgentTerminalSession: Handler = async (req, params) => {
+  try {
+    const agent = getAgent(params.id!);
+    if (!agent) return error("agent not found", 404);
+    const orchestrator = managedControlOrchestrator(agent);
+    if (!orchestrator) return error("agent does not have an online orchestrator", 422);
+    const metaTmuxSession = typeof agent.meta?.tmuxSession === "string" ? agent.meta.tmuxSession : undefined;
+    const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
+    const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
+    const denied = authorizeRoute(req, {
+      scope: "terminal:attach",
+      resource: { agentId: agent.id, orchestratorId: orchestrator.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId, terminalAttach: true },
+    });
+    if (denied) return denied;
+    if (agent.providerCapabilities?.terminal?.live?.read && metaTmuxSession) {
+      return json({
+        mode: "live",
+        orchestratorId: orchestrator.id,
+        session: metaTmuxSession,
+        interactive: agent.providerCapabilities.terminal.live.write === true,
+      });
+    }
+    if (agent.providerCapabilities?.terminal?.attach?.create !== true) return error("agent does not support terminal attach", 422);
+    if (!orchestrator.apiUrl) return error("orchestrator does not expose an API", 422);
+
+    const body = {
+      agentId: agent.id,
+      ...(metaTmuxSession ? { tmuxSession: metaTmuxSession } : {}),
+      ...(metaPolicyName ? { policyName: metaPolicyName } : {}),
+      ...(metaSpawnRequestId ? { spawnRequestId: metaSpawnRequestId } : {}),
+    };
+    const res = await proxyOrchestratorJson(orchestrator.id, "/api/terminal-guests", "POST", body);
+    if (res instanceof Response) return res;
+    return json({ ...res, orchestratorId: orchestrator.id });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteAgentTerminalSession: Handler = async (req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  const orchestrator = managedControlOrchestrator(agent);
+  if (!orchestrator) return error("agent does not have an online orchestrator", 422);
+  const denied = authorizeRoute(req, {
+    scope: "terminal:attach",
+    resource: {
+      agentId: agent.id,
+      orchestratorId: orchestrator.id,
+      policyName: typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined,
+      spawnRequestId: typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined,
+      terminalAttach: true,
+    },
+  });
+  if (denied) return denied;
+  const session = params.session!;
+  return proxyOrchestratorDelete(req, orchestrator.id, `/api/terminal-guests/${encodeURIComponent(session)}`);
+};
+
+async function proxyOrchestratorDelete(req: Request, orchestratorId: string, path: string): Promise<Response> {
+  const orch = getOrchestrator(orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
+  if (orch.status !== "online") return error("orchestrator is offline", 422);
+  const incoming = new URL(req.url);
+  const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(proxyUrl, {
+      method: "DELETE",
+      headers,
+      signal: AbortSignal.timeout(10_000),
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    return new Response(await res.text(), { status: res.status, headers: { "Content-Type": contentType || "application/json" } });
+  } catch (e) {
+    return error(`Failed to reach orchestrator API: ${(e as Error).message}`, 502);
+  }
+}
+
+async function proxyOrchestratorJson(orchestratorId: string, path: string, method: "POST", body: unknown): Promise<Record<string, unknown> | Response> {
+  const orch = getOrchestrator(orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
+  if (orch.status !== "online") return error("orchestrator is offline", 422);
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}${path}`, {
+      method,
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+    const payload = await res.json().catch(() => null) as unknown;
+    if (!res.ok) return json(payload ?? { error: `orchestrator returned ${res.status}` }, res.status);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload as Record<string, unknown> : {};
+  } catch (e) {
+    return error(`Failed to reach orchestrator API: ${(e as Error).message}`, 502);
+  }
+}