agent-relay-server 0.10.7 → 0.10.8

package/src/routes.ts

@@ -11,9 +11,11 @@ import {
   deleteAgent,
   sendMessage,
   sendMessageWithResult,
+  getMessageDeliveryStatus,
   getMessage,
   getThread,
   claimMessage,
+  listQueuedMessages,
   listRecentMessages,
   pollMessages,
   markRead,
@@ -53,6 +55,8 @@ import {
   reapStaleAgents,
   reapStaleOrchestrators,
   releaseExpiredClaims,
+  expireQueuedMessages,
+  resolveQueuedPolicyMessages,
   releaseOrphanedTasks,
   validateAgentSession,
   upsertOrchestrator,
@@ -64,6 +68,18 @@ import {
   evaluatePoolBindings,
   ValidationError,
 } from "./db";
+import {
+  deleteConfig,
+  getConfig,
+  getConfigHistory,
+  getManagedAgentState,
+  getSpawnPolicy,
+  listSpawnPolicies,
+  listConfig,
+  setConfig,
+  upsertManagedAgentState,
+  updateManagedAgentState,
+} from "./config-store";
 import { createCommand, deleteCommand, expireCommands, getCommand, listCommands, updateCommand } from "./commands-db";
 import { getRecipe, listRecipes } from "./recipe-loader";
 import { applyCommandToRecipe, getRecipeInstance, listRecipeInstances, startRecipe, stopRecipe } from "./recipe-runner";
@@ -86,7 +102,7 @@ import {
   updateAutomation,
   type AutomationDispatchResult,
 } from "./automations";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentSessionGuard, ChannelBinding, ChannelBindingMode, ChannelDirection, ChannelRouteTarget, ChannelSummary, Command, CommandStatus, CreateCommandInput, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, OrchestratorRuntimeInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentSessionGuard, ChannelBinding, ChannelBindingMode, ChannelDirection, ChannelRouteTarget, ChannelSummary, Command, CommandStatus, CreateCommandInput, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, OrchestratorRuntimeInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnPolicy, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
 import { listHostDirectories } from "./agent-spawn";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
@@ -104,13 +120,19 @@ import {
   emitMessageClaimed,
   emitMessageClaimReleased,
   emitMessageDeleted,
+  emitMessageQueued,
+  emitMessageAvailable,
+  emitMessageExpired,
   emitTaskChanged,
   emitChannelActivity,
   emitOrchestratorStatus,
   emitOrchestratorRemoved,
   emitPoolBindingChanged,
+  emitConfigChanged,
+  emitManagedAgentStateChanged,
 } from "./sse";
 import { emitRelayEvent } from "./events";
+import { isAbsolute, relative, resolve } from "node:path";
 
 type Handler = (
   req: Request,
@@ -195,7 +217,7 @@ function parseQueryInt(
 
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "stale", "offline"] as const;
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
-const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool"] as const;
+const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool", "policy"] as const;
 const VALID_CHANNEL_BINDING_MODES = ["exclusive", "broadcast"] as const;
 const VALID_AGENT_ACTIONS = ["restart", "shutdown"] as const;
 const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
@@ -212,6 +234,13 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function pathWithinBase(path: string, baseDir: string): boolean {
+  const base = resolve(baseDir);
+  const target = resolve(path);
+  const rel = relative(base, target);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
 function cleanString(
   value: unknown,
   field: string,
@@ -370,6 +399,12 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     claimable: body.claimable as boolean | undefined,
     idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }),
   };
+  if (body.maxAgeSeconds !== undefined) {
+    if (typeof body.maxAgeSeconds !== "number" || !Number.isSafeInteger(body.maxAgeSeconds) || body.maxAgeSeconds < 0 || body.maxAgeSeconds > 2_592_000) {
+      throw new ValidationError("maxAgeSeconds must be an integer between 0 and 2592000");
+    }
+    input.maxAgeSeconds = body.maxAgeSeconds;
+  }
 
   const channel = cleanString(body.channel, "channel", { max: 120 });
   if (channel) input.channel = channel;
@@ -438,6 +473,7 @@ function normalizeChannelBindingInput(body: unknown): {
 
 function routeTargetFromAddress(target: string): ChannelRouteTarget {
   if (target.startsWith("pool:")) return { type: "pool", id: target.slice("pool:".length) };
+  if (target.startsWith("policy:")) return { type: "policy", id: target.slice("policy:".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) };
@@ -456,6 +492,7 @@ function messageTargetForChannelTarget(target: ChannelRouteTarget, binding?: Cha
   if (target.type === "tag") return `tag:${target.id}`;
   if (target.type === "capability") return `cap:${target.id}`;
   if (target.type === "broadcast") return "broadcast";
+  if (target.type === "policy") return `policy:${target.id}`;
   return target.id;
 }
 
@@ -623,7 +660,7 @@ function resolveIntegrationEventTarget(input: IntegrationEventInput): Integratio
 
   const binding = bindings[0]!;
   const resolvedTarget = messageTargetForChannelTarget(binding.target, binding);
-  if (!getAgent(resolvedTarget)) {
+  if (!resolvedTarget.startsWith("policy:") && !getAgent(resolvedTarget)) {
     throw new ValidationError(`channel ${channelId} binding resolves to ${resolvedTarget}; integration channel targets must resolve to one backend agent`);
   }
 
@@ -920,6 +957,25 @@ const postAgent: Handler = async (req) => {
     const input = normalizeAgentInput(parsed.body);
     const existing = getAgent(input.id);
     const agent = upsertAgent(input);
+    const policyName = metaString(agent.meta, "policyName");
+    const spawnRequestId = metaString(agent.meta, "spawnRequestId");
+    if (policyName && spawnRequestId) {
+      const state = getManagedAgentState(policyName);
+      if (state?.spawnRequestId === spawnRequestId) {
+        const updatedState = updateManagedAgentState(policyName, {
+          status: "running",
+          agentId: agent.id,
+          healthySince: Date.now(),
+          lastError: undefined,
+        });
+        if (updatedState) emitManagedAgentStateChanged(policyName, updatedState as unknown as Record<string, unknown>);
+        const available = resolveQueuedPolicyMessages(policyName, agent.id);
+        if (available.length) {
+          emitMessageAvailable(policyName, agent.id, available);
+          for (const message of available) emitNewMessage(message);
+        }
+      }
+    }
     emitAgentStatus(agent.id);
     if (!existing) {
       auditEvent({
@@ -1424,24 +1480,36 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
       return error(`orchestrator does not support provider: ${provider}`);
     }
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
-    if (cwd && !cwd.startsWith(orch.baseDir)) {
+    if (cwd && !pathWithinBase(cwd, 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 });
+    const tags = cleanStringArray(parsed.body.tags, "tags") ?? [];
+    const capabilities = cleanStringArray(parsed.body.capabilities, "capabilities") ?? [];
+    const providerArgs = cleanStringArray(parsed.body.providerArgs, "providerArgs") ?? [];
+    const policyName = cleanString(parsed.body.policyName, "policyName", { max: 120 });
+    const spawnRequestId = cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 });
 
     const command = createCommand({
       type: "agent.spawn",
       source: "system",
       target: orch.agentId,
+      correlationId: spawnRequestId,
       params: {
         action: "spawn",
         provider,
         cwd: cwd || orch.baseDir,
         label,
+        tags,
+        capabilities,
         approvalMode,
+        permissionMode: approvalMode,
+        providerArgs,
         prompt,
+        policyName,
+        spawnRequestId,
         requestedBy: "dashboard",
         requestedAt: Date.now(),
       },
@@ -1475,12 +1543,17 @@ const postOrchestratorAction: Handler = async (req, params) => {
     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 policyName = cleanString(parsed.body.policyName, "policyName", { max: 120 });
+    const spawnRequestId = cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 });
+    const tmuxSession = cleanString(parsed.body.tmuxSession, "tmuxSession", { max: 200 });
+    const reason = cleanString(parsed.body.reason, "reason", { max: 200 }) ?? "manual";
 
     const command = createCommand({
       type: action === "restart" ? "agent.restart" : "agent.shutdown",
       source: "system",
       target: agentId || orch.agentId,
-      params: { action, agentId, requestedBy: "dashboard", requestedAt: Date.now(), orchestratorId: orch.id },
+      correlationId: spawnRequestId,
+      params: { action, agentId, policyName, spawnRequestId, tmuxSession, reason, requestedBy: "dashboard", requestedAt: Date.now(), orchestratorId: orch.id },
     });
     emitCommand(command);
     auditEvent({
@@ -1517,6 +1590,34 @@ const getOrchestratorDirectories: Handler = async (req, params) => {
   }
 };
 
+async function proxyOrchestratorGet(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["X-Agent-Relay-Token"] = relayToken;
+  try {
+    const res = await fetch(proxyUrl, { headers, signal: AbortSignal.timeout(10_000) });
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      return new Response(res.body, { status: res.status, headers: { "Content-Type": contentType } });
+    }
+    const body = await res.text();
+    return new Response(body, { status: res.status, headers: { "Content-Type": contentType || "application/json" } });
+  } catch (e) {
+    return error(`Failed to reach orchestrator API: ${(e as Error).message}`, 502);
+  }
+}
+
+const getOrchestratorProviders: Handler = (req, params) => proxyOrchestratorGet(req, params.id!, "/api/providers");
+const getOrchestratorSessions: Handler = (req, params) => proxyOrchestratorGet(req, params.id!, "/api/sessions");
+const getOrchestratorVersion: Handler = (req, params) => proxyOrchestratorGet(req, params.id!, "/api/version");
+const getOrchestratorLogs: Handler = (req, params) => proxyOrchestratorGet(req, params.id!, `/api/logs/${encodeURIComponent(params.session!)}`);
+
 const deleteOrchestratorById: Handler = (_req, params) => {
   const deleted = deleteOrchestrator(params.id!);
   if (!deleted) return error("orchestrator not found", 404);
@@ -1612,6 +1713,262 @@ const patchCommand: Handler = async (req, params) => {
   }
 };
 
+// --- Config routes ---
+
+function normalizeConfigPathParam(raw: string | undefined, field: string): string {
+  return cleanString(raw, field, { required: true, max: 240 })!;
+}
+
+const getConfigNamespace: Handler = (_req, params) => {
+  const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+  return json(listConfig(namespace));
+};
+
+const getConfigKey: Handler = (_req, params) => {
+  const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+  const key = normalizeConfigPathParam(params.key, "key");
+  const entry = getConfig(namespace, key);
+  return entry ? json(entry) : error("config not found", 404);
+};
+
+const putConfigKey: 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("JSON object body required");
+    if (!Object.prototype.hasOwnProperty.call(parsed.body, "value")) throw new ValidationError("value required");
+    const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+    const key = normalizeConfigPathParam(params.key, "key");
+    const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
+    const entry = setConfig(namespace, key, parsed.body.value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteConfigKey: Handler = (req, params) => {
+  try {
+    const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+    const key = normalizeConfigPathParam(params.key, "key");
+    const updatedBy = cleanString(new URL(req.url).searchParams.get("updatedBy") ?? undefined, "updatedBy", { max: 200 });
+    const existing = getConfig(namespace, key);
+    if (!existing) return error("config not found", 404);
+    deleteConfig(namespace, key, updatedBy);
+    emitConfigChanged(namespace, key, existing.version + 1);
+    return json({ ok: true });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getConfigKeyHistory: Handler = (req, params) => {
+  try {
+    const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+    const key = normalizeConfigPathParam(params.key, "key");
+    const limitRaw = parseQueryInt(new URL(req.url).searchParams.get("limit"), { min: 1, max: 500 });
+    if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+    return json(getConfigHistory(namespace, key, limitRaw ?? undefined));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+// --- Spawn policy routes ---
+
+function spawnRequestId(): string {
+  return `sp_${crypto.randomUUID()}`;
+}
+
+function policyStatusPayload(policy: SpawnPolicy) {
+  return {
+    policy,
+    state: getManagedAgentState(policy.name) ?? {
+      policyName: policy.name,
+      status: "stopped",
+      orchestratorId: policy.orchestratorId,
+      provider: policy.provider,
+      restartCount: 0,
+      consecutiveFailures: 0,
+      updatedAt: 0,
+    },
+  };
+}
+
+function managedSpawnParams(policy: SpawnPolicy, requestId: string): Record<string, unknown> {
+  return {
+    action: "spawn",
+    provider: policy.provider,
+    cwd: policy.cwd,
+    label: policy.label,
+    tags: policy.tags,
+    capabilities: policy.capabilities,
+    approvalMode: policy.permissionMode,
+    permissionMode: policy.permissionMode,
+    providerArgs: policy.providerArgs,
+    prompt: policy.prompt,
+    headless: true,
+    policyName: policy.name,
+    spawnRequestId: requestId,
+    requestedBy: "managed-agent",
+    requestedAt: Date.now(),
+  };
+}
+
+function requirePolicyAndOrchestrator(name: string): { policy: SpawnPolicy; orch: NonNullable<ReturnType<typeof getOrchestrator>> } | Response {
+  const entry = getSpawnPolicy(name);
+  if (!entry) return error("spawn policy not found", 404);
+  const policy = entry.value;
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  return { policy, orch };
+}
+
+function enqueuePolicyStart(policy: SpawnPolicy, reason: string): Command | Response {
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  if (orch.status !== "online") return error("orchestrator is offline", 409);
+  const requestId = spawnRequestId();
+  const state = upsertManagedAgentState({
+    policyName: policy.name,
+    status: "starting",
+    orchestratorId: policy.orchestratorId,
+    provider: policy.provider,
+    spawnRequestId: requestId,
+    lastSpawnAt: Date.now(),
+  });
+  emitManagedAgentStateChanged(policy.name, state as unknown as Record<string, unknown>);
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "system",
+    target: orch.agentId,
+    correlationId: requestId,
+    params: {
+      ...managedSpawnParams(policy, requestId),
+      reason,
+      orchestratorId: orch.id,
+    },
+  });
+  emitCommand(command);
+  return command;
+}
+
+function enqueuePolicyStop(policy: SpawnPolicy, action: "shutdown" | "restart", reason: string): Command | Response {
+  const orch = getOrchestrator(policy.orchestratorId);
+  if (!orch) return error("orchestrator not found", 404);
+  const state = getManagedAgentState(policy.name);
+  const nextState = upsertManagedAgentState({
+    policyName: policy.name,
+    status: action === "restart" ? "starting" : "stopping",
+    agentId: state?.agentId,
+    orchestratorId: policy.orchestratorId,
+    provider: policy.provider,
+    tmuxSession: state?.tmuxSession,
+    spawnRequestId: state?.spawnRequestId,
+    lastSpawnAt: state?.lastSpawnAt,
+    lastStopAt: Date.now(),
+    restartCount: state?.restartCount ?? 0,
+    consecutiveFailures: state?.consecutiveFailures ?? 0,
+  });
+  emitManagedAgentStateChanged(policy.name, nextState as unknown as Record<string, unknown>);
+  const command = createCommand({
+    type: action === "restart" ? "agent.restart" : "agent.shutdown",
+    source: "system",
+    target: orch.agentId,
+    correlationId: state?.spawnRequestId,
+    params: {
+      action,
+      policyName: policy.name,
+      spawnRequestId: state?.spawnRequestId,
+      agentId: state?.agentId,
+      tmuxSession: state?.tmuxSession,
+      graceful: true,
+      timeoutMs: 10_000,
+      reason,
+      orchestratorId: orch.id,
+      requestedBy: "managed-agent",
+      requestedAt: Date.now(),
+    },
+  });
+  emitCommand(command);
+  return command;
+}
+
+const getSpawnPoliciesRoute: Handler = () => {
+  return json(listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)));
+};
+
+const getSpawnPolicyRoute: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(entry) : error("spawn policy not found", 404);
+};
+
+const putSpawnPolicyRoute: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const value = isRecord(parsed.body) && Object.prototype.hasOwnProperty.call(parsed.body, "value")
+      ? parsed.body.value
+      : parsed.body;
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const entry = setConfig("spawn-policy", params.name!, value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteSpawnPolicyRoute: Handler = (req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  if (!entry) return error("spawn policy not found", 404);
+  const stop = enqueuePolicyStop(entry.value, "shutdown", "policy-deleted");
+  if (stop instanceof Response) return stop;
+  deleteConfig("spawn-policy", params.name!, new URL(req.url).searchParams.get("updatedBy") ?? undefined);
+  emitConfigChanged("spawn-policy", params.name!, entry.version + 1);
+  return json({ ok: true, command: stop }, 202);
+};
+
+const postSpawnPolicyStart: Handler = (_req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const command = enqueuePolicyStart(resolved.policy, "manual-start");
+  return command instanceof Response ? command : json({ ok: true, command }, 202);
+};
+
+const postSpawnPolicyStop: Handler = (_req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const command = enqueuePolicyStop(resolved.policy, "shutdown", "manual-stop");
+  return command instanceof Response ? command : json({ ok: true, command }, 202);
+};
+
+const postSpawnPolicyRestart: Handler = (_req, params) => {
+  const resolved = requirePolicyAndOrchestrator(params.name!);
+  if (resolved instanceof Response) return resolved;
+  const command = enqueuePolicyStop(resolved.policy, "restart", "manual-restart");
+  return command instanceof Response ? command : json({ ok: true, command }, 202);
+};
+
+const getSpawnPolicyStatus: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(policyStatusPayload(entry.value)) : error("spawn policy not found", 404);
+};
+
+const getSpawnPoliciesHealth: Handler = () => {
+  return json(listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)));
+};
+
+const getSpawnPolicyHealth: Handler = (_req, params) => {
+  const entry = getSpawnPolicy(params.name!);
+  return entry ? json(policyStatusPayload(entry.value)) : error("spawn policy not found", 404);
+};
+
 // --- Provider config routes ---
 
 const VALID_PROVIDER_CONFIGS = ["claude", "codex"] as const;
@@ -1705,6 +2062,21 @@ const deleteCommandById: Handler = (_req, params) => {
 
 const VALID_MSG_KINDS = ["chat", "channel.event", "task", "pair", "control", "system"];
 
+const getQueuedMessagesRoute: Handler = (req) => {
+  const url = new URL(req.url);
+  const target = cleanString(url.searchParams.get("for") ?? undefined, "for", { required: true, max: 240 })!;
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  return json(listQueuedMessages(target, limitRaw ?? undefined));
+};
+
+const getMessageStatusRoute: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const status = getMessageDeliveryStatus(id);
+  return status ? json(status) : error("message not found", 404);
+};
+
 const postMessage: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -1724,7 +2096,8 @@ const postMessage: Handler = async (req) => {
     }
     const result = sendMessageWithResult(input);
     if (result.created) {
-      emitNewMessage(result.message);
+      if (result.message.deliveryStatus === "queued") emitMessageQueued(result.message);
+      else emitNewMessage(result.message);
       const isWork = result.message.kind === "task";
       auditEvent({
         clientId: "server-message-" + result.message.id,
@@ -2221,7 +2594,9 @@ const postChannelEvent: Handler = async (req, params) => {
       claimable: false,
     }));
     for (const result of results) {
-      if (result.created) emitNewMessage(result.message);
+      if (!result.created) continue;
+      if (result.message.deliveryStatus === "queued") emitMessageQueued(result.message);
+      else emitNewMessage(result.message);
     }
     return json({
       messages: results.map((result) => result.message),
@@ -2570,12 +2945,14 @@ const getHealthRoute: Handler = () => json(getHealth());
 const postSystemReap: Handler = () => {
   const released = releaseExpiredClaims();
   const releasedOrphans = releaseOrphanedTasks();
+  const expiredQueuedMessages = expireQueuedMessages();
   const expiredCommands = expireCommands();
   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 task of releasedOrphans) emitTaskChanged(task, "task.updated");
+  for (const message of expiredQueuedMessages) emitMessageExpired(message);
   for (const command of expiredCommands) {
     applyCommandToRecipe(command);
     emitCommand(command);
@@ -2600,7 +2977,7 @@ const postSystemReap: Handler = () => {
     clientId: "server-system-reap-" + Date.now(),
     kind: "state",
     title: "Maintenance reaper run",
-    body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s), ${expiredCommands.length} command(s)`,
+    body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s), ${expiredQueuedMessages.length} queued message(s), ${expiredCommands.length} command(s)`,
     icon: "ti-broom",
     view: "activity",
   });
@@ -2611,6 +2988,7 @@ const postSystemReap: Handler = () => {
     releasedMessageIds: released.messageIds,
     releasedTaskIds: released.tasks.map((task) => task.id),
     releasedOrphanedTaskIds: releasedOrphans.map((task) => task.id),
+    expiredQueuedMessageIds: expiredQueuedMessages.map((message) => message.id),
     expiredCommandIds: expiredCommands.map((command) => command.id),
   });
 };
@@ -2660,6 +3038,10 @@ const routes: Route[] = [
   route("POST", "/api/orchestrators/:id/spawn", postOrchestratorSpawn),
   route("POST", "/api/orchestrators/:id/actions", postOrchestratorAction),
   route("GET", "/api/orchestrators/:id/directories", getOrchestratorDirectories),
+  route("GET", "/api/orchestrators/:id/providers", getOrchestratorProviders),
+  route("GET", "/api/orchestrators/:id/sessions", getOrchestratorSessions),
+  route("GET", "/api/orchestrators/:id/version", getOrchestratorVersion),
+  route("GET", "/api/orchestrators/:id/logs/:session", getOrchestratorLogs),
   route("DELETE", "/api/orchestrators/:id", deleteOrchestratorById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
@@ -2678,6 +3060,21 @@ const routes: Route[] = [
   route("GET", "/api/commands/:id", getCommandById),
   route("PATCH", "/api/commands/:id", patchCommand),
   route("DELETE", "/api/commands/:id", deleteCommandById),
+  route("GET", "/api/config/:namespace", getConfigNamespace),
+  route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
+  route("GET", "/api/config/:namespace/:key", getConfigKey),
+  route("PUT", "/api/config/:namespace/:key", putConfigKey),
+  route("DELETE", "/api/config/:namespace/:key", deleteConfigKey),
+  route("GET", "/api/spawn-policies", getSpawnPoliciesRoute),
+  route("GET", "/api/spawn-policy/:name", getSpawnPolicyRoute),
+  route("PUT", "/api/spawn-policy/:name", putSpawnPolicyRoute),
+  route("DELETE", "/api/spawn-policy/:name", deleteSpawnPolicyRoute),
+  route("POST", "/api/spawn-policy/:name/start", postSpawnPolicyStart),
+  route("POST", "/api/spawn-policy/:name/stop", postSpawnPolicyStop),
+  route("POST", "/api/spawn-policy/:name/restart", postSpawnPolicyRestart),
+  route("GET", "/api/spawn-policies/health", getSpawnPoliciesHealth),
+  route("GET", "/api/spawn-policy/:name/status", getSpawnPolicyStatus),
+  route("GET", "/api/spawn-policy/:name/health", getSpawnPolicyHealth),
   route("GET", "/api/providers/config", getProviderConfigsRoute),
   route("GET", "/api/providers/:provider/config", getProviderConfigRoute),
   route("PUT", "/api/providers/:provider/config", putProviderConfigRoute),
@@ -2685,7 +3082,9 @@ const routes: Route[] = [
 
   route("POST", "/api/messages", postMessage),
   route("GET", "/api/messages", getMessages),
+  route("GET", "/api/messages/queued", getQueuedMessagesRoute),
   route("GET", "/api/messages/cursor", getCursorRoute),
+  route("GET", "/api/messages/:id/status", getMessageStatusRoute),
   route("GET", "/api/messages/:id", getMessageById),
   route("GET", "/api/messages/:id/thread", getMessageThread),
   route("POST", "/api/messages/:id/claim", postClaimMessage),

package/src/sse.ts

@@ -70,6 +70,7 @@ function send(conn: Connection, event: string, data: unknown) {
 function messageMatchesAgent(msg: Message, agentId: string): boolean {
   const agent = getAgent(agentId);
   if (!agent) return false;
+  if (msg.resolvedToAgent === agentId) return true;
   if (msg.to === agentId || msg.from === agentId) return true;
   if (msg.to === "broadcast") return true;
   if (msg.to.startsWith("tag:") && agent.tags.includes(msg.to.slice(4))) return true;
@@ -130,6 +131,23 @@ export function emitMessageDeleted(messageId: number) {
   emitRelayEvent({ type: "message.deleted", source: "server", subject: String(messageId), data: { messageId } });
 }
 
+export function emitMessageQueued(msg: Message) {
+  emitRelayEvent({ type: "message.queued", source: msg.from, subject: String(msg.id), data: msg as unknown as Record<string, unknown> });
+}
+
+export function emitMessageAvailable(policyName: string, agentId: string, messages: Message[]) {
+  emitRelayEvent({
+    type: "message.available",
+    source: "server",
+    subject: `policy:${policyName}`,
+    data: { policyName, agentId, messageIds: messages.map((message) => message.id), count: messages.length },
+  });
+}
+
+export function emitMessageExpired(msg: Message) {
+  emitRelayEvent({ type: "message.expired", source: "server", subject: String(msg.id), data: msg as unknown as Record<string, unknown> });
+}
+
 function sendTaskChanged(task: Task, eventType = "task.updated"): void {
   for (const conn of connections.values()) {
     if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId)) continue;
@@ -145,6 +163,14 @@ export function emitChannelActivity(activity: Record<string, unknown>) {
   emitRelayEvent({ type: "channel.activity", source: "server", data: activity });
 }
 
+export function emitConfigChanged(namespace: string, key: string, version: number) {
+  emitRelayEvent({ type: "config.changed", source: "server", subject: `${namespace}:${key}`, data: { namespace, key, version } });
+}
+
+export function emitManagedAgentStateChanged(policyName: string, data: Record<string, unknown>) {
+  emitRelayEvent({ type: "policy.state.changed", source: "server", subject: policyName, data });
+}
+
 export function getConnectionCount(): number {
   return connections.size;
 }