agent-relay-server 0.32.2 → 0.32.3

package/src/routes/messages.ts

@@ -0,0 +1,529 @@
+// Auto-split from routes.ts (#299). Domain: messages.
+import { MAX_BODY_BYTES } from "../config";
+import { ValidationError, applyMessageDeliveryAction, claimMessage, deleteMessage, getAgent, getLatestMessageId, getMessage, getMessageDeliveryStatus, getThread, listAgents, listQueuedMessages, listRecentMessages, markRead, pollMessages, recordMessageDeliveryAttempt, renewMessageClaim, sendMessage, sendMessageWithResult, setMessageReaction } from "../db";
+import { auditEvent, authorizeRoute, cleanAttachmentRefs, dispatchTaskCallbacks, emitCommand, error, json, memoryContext, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, reactionEmoji, sendReactionNotificationToAuthor, withPayloadAttachments, type Handler } from "./_shared";
+import { cleanMeta, cleanPositiveId, cleanString, optionalEnum } from "../validation";
+import { emitMessageClaimed, emitMessageDeleted, emitMessageDeliveryUpdated, emitMessageQueued, emitMessageReactionUpdated, emitNewMessage, emitTaskChanged } from "../sse";
+import { errMessage, isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
+import { getLifecycleManager } from "../lifecycle-manager";
+import { injectMemoryForMessageDelivery } from "../memory-service";
+import { planSend } from "../agent-ref";
+import { type AgentSessionGuard, type Message, type SendMessageInput } from "../types";
+
+const VALID_DELIVERY_STATUSES = ["pending", "delivered", "queued", "failed", "dead"] as const;
+
+const VALID_DELIVERY_ACTIONS = ["retry-now", "mark-dead", "clear"] as const;
+
+function normalizeMessageInput(body: unknown): SendMessageInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const kind = cleanString(body.kind, "kind", { max: 40 });
+  if (kind && !VALID_MSG_KINDS.includes(kind)) {
+    throw new ValidationError(`kind must be one of: ${VALID_MSG_KINDS.join(", ")}`);
+  }
+  if (body.claimable !== undefined && typeof body.claimable !== "boolean") {
+    throw new ValidationError("claimable must be a boolean");
+  }
+  if (body.replyExpected !== undefined && typeof body.replyExpected !== "boolean") {
+    throw new ValidationError("replyExpected must be a boolean");
+  }
+
+  const input: SendMessageInput = {
+    from: cleanString(body.from, "from", { required: true, max: 200 })!,
+    to: cleanString(body.to, "to", { max: 200 }) ?? "",
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    kind: kind as SendMessageInput["kind"] | undefined,
+    replyTo: cleanPositiveId(body.replyTo, "replyTo"),
+    replyExpected: body.replyExpected as boolean | undefined,
+    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;
+  }
+  if (body.occurredAt !== undefined) {
+    if (typeof body.occurredAt !== "number" || !Number.isFinite(body.occurredAt) || body.occurredAt <= 0) {
+      throw new ValidationError("occurredAt must be a positive epoch-ms number");
+    }
+    input.occurredAt = body.occurredAt;
+  }
+
+  const channel = cleanString(body.channel, "channel", { max: 120 });
+  if (channel) input.channel = channel;
+  const subject = cleanString(body.subject, "subject", { max: 200 });
+  if (subject) input.subject = subject;
+  const meta = cleanMeta(body.meta);
+  if (meta) input.meta = meta;
+  const payload = cleanMeta(body.payload);
+  const attachments = cleanAttachmentRefs(body.attachments ?? body.artifacts, "attachments");
+  if (payload || attachments) {
+    input.payload = withPayloadAttachments(payload ?? {}, attachments as Array<Record<string, unknown>> | undefined);
+  }
+
+  return input;
+}
+
+const FANOUT_PREFIXES = ["tag:", "cap:", "label:"];
+
+function isDirectTarget(to: string): boolean {
+  return to !== "broadcast" && !FANOUT_PREFIXES.some((p) => to.startsWith(p));
+}
+
+function applyReplyRouting(input: SendMessageInput): void {
+  if (input.to || !input.replyTo) return;
+  const parent = getMessage(input.replyTo);
+  if (!parent) return;
+  input.to = parent.from;
+  if (!input.channel && parent.channel) input.channel = parent.channel;
+  const parentPayload = parent.payload ?? {};
+  if (parentPayload.schema === "agent-relay.channel.v1" || parentPayload.conversation) {
+    const replyContext: Record<string, unknown> = {};
+    if (parent.channel) replyContext.channelId = parent.channel;
+    if (parentPayload.conversation && typeof parentPayload.conversation === "object") {
+      replyContext.conversationId = (parentPayload.conversation as Record<string, unknown>).id;
+    }
+    if (parentPayload.event && typeof parentPayload.event === "object") {
+      replyContext.parentEventId = (parentPayload.event as Record<string, unknown>).id;
+    }
+    if (parentPayload.source) replyContext.source = parentPayload.source;
+    input.payload = { ...input.payload, replyContext };
+  }
+}
+
+const VALID_MSG_KINDS = ["chat", "channel.event", "task", "pair", "control", "system", "session"];
+
+export 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));
+};
+
+export 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);
+};
+
+export const getMessageDeliveryRoute: 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);
+};
+
+export const postMessageDeliveryAttempt: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("body must be an object");
+    const status = optionalEnum(parsed.body.status, "status", VALID_DELIVERY_STATUSES);
+    if (!status) throw new ValidationError("status required");
+    const nextRetryAt = cleanPositiveId(parsed.body.nextRetryAt, "nextRetryAt");
+    const result = recordMessageDeliveryAttempt(id, {
+      agentId: cleanString(parsed.body.agentId, "agentId", { max: 200 }),
+      status,
+      error: cleanString(parsed.body.error, "error", { max: 2000 }),
+      nextRetryAt,
+      poisonReason: cleanString(parsed.body.poisonReason, "poisonReason", { max: 2000 }),
+    });
+    if (!result.ok) return error(result.error ?? "message not found", 404);
+    emitMessageDeliveryUpdated(result.message!);
+    return json(getMessageDeliveryStatus(id), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMessageDeliveryAction: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("body must be an object");
+    const action = optionalEnum(parsed.body.action, "action", VALID_DELIVERY_ACTIONS);
+    if (!action) throw new ValidationError("action required");
+    const result = applyMessageDeliveryAction(id, {
+      action,
+      reason: cleanString(parsed.body.reason, "reason", { max: 2000 }),
+      agentId: cleanString(parsed.body.agentId, "agentId", { max: 200 }),
+    });
+    if (!result.ok) return error(result.error ?? "message not found", 404);
+    emitMessageDeliveryUpdated(result.message!);
+    return json(getMessageDeliveryStatus(id));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMessage: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = normalizeMessageInput(parsed.body);
+    if (!input.idempotencyKey) {
+      input.idempotencyKey = cleanString(req.headers.get("Idempotency-Key") ?? undefined, "idempotencyKey", { max: 240 });
+    }
+    applyReplyRouting(input);
+    if (!input.to) return error("to is required (or provide replyTo to auto-route)");
+    // Mechanical lifecycle/observability posts (system/control/session) addressed to a
+    // reserved sink ("user"/"system") are the relay's own lane, not agent-directed
+    // messaging. A managed token's recipient constraints (targets/policies/agents) gate
+    // which *agents* it may message — they must NOT gate a session-mirror capture to the
+    // reserved sink, or constrained tokens (telegram policy, codex steward) 403 → the
+    // runner's outbox retries 12× and poisons the record → the dashboard silently loses
+    // the turn (#284, same outbox-poison failure mode as #184). The message:send scope
+    // and any channel constraint still apply; we only drop the target/agentId predicate.
+    const reservedSinkPost = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
+    const denied = authorizeRoute(req, {
+      scope: "message:send",
+      resource: reservedSinkPost
+        ? { channel: input.channel }
+        : { target: input.to, channel: input.channel, agentId: input.from },
+    });
+    if (denied) return denied;
+    // Resolve the target through the shared planner — the SAME matcher the MCP send tool
+    // uses (planSend → matchAgents) — so a bare label / name / id-segment that matches an
+    // existing agent is rewritten to its canonical id. Poll-time matching is exact, so
+    // without this a bare label is stored verbatim and reaches no one (#234). An ambiguous
+    // direct ref can't be delivered, so reject it up front. Unknown targets are left
+    // untouched on purpose: sending to an id that isn't registered yet is a supported
+    // "store-ahead" pattern (delivered once that agent registers and polls). Fan-out and
+    // reserved/policy targets carry through unchanged (and may legitimately match zero now).
+    //
+    // "session" = observed assistant turn (Phase 1 live-session lane). It is captured
+    // from the provider transcript and stored for the dashboard chat; it must persist
+    // regardless of target liveness and never be re-delivered into a session.
+    if (!isMechanicalMessageKind(input.kind)) {
+      // excludeId: a bare ref must never resolve back to its own author — that self-loop
+      // silently swallows the message (the reddit-briefing → telegram bridge break, #290).
+      const plan = planSend(input.to, listAgents(), { excludeId: input.from });
+      if (plan.kind === "ambiguous") return error(plan.message, 409);
+      if (plan.kind !== "not_found") input.to = plan.to;
+      // Long-standing guard: refuse a direct send to a known-offline agent (now also
+      // catches a ref that resolved to an offline agent by label/segment).
+      const target = getAgent(input.to);
+      if (target && target.status === "offline") {
+        return error(`agent "${input.to}" is offline`, 422);
+      }
+    }
+    const result = sendMessageWithResult(input);
+    if (result.created) {
+      const autoMemoryTarget = automaticMemoryTarget(result.message);
+      if (autoMemoryTarget) {
+        try {
+          const memoryInjection = await injectMemoryForMessageDelivery(result.message, autoMemoryTarget, memoryContext(req));
+          if (memoryInjection) emitCommand(memoryInjection.command);
+        } catch (e) {
+          console.warn(`[memory] automatic message context assembly failed: ${errMessage(e)}`);
+        }
+      }
+      if (result.message.deliveryStatus === "queued") {
+        emitMessageQueued(result.message);
+        // Wake an on-demand managed policy that has no live agent attached yet.
+        if (result.message.to?.startsWith("policy:")) {
+          getLifecycleManager().onMessageForPolicy(result.message.to.slice("policy:".length));
+        }
+      } else emitNewMessage(result.message);
+      const isWork = result.message.kind === "task";
+      auditEvent({
+        clientId: "server-message-" + result.message.id,
+        kind: isWork ? "task" : "message",
+        title: isWork ? "Task message sent" : "Message sent",
+        body: result.message.subject || result.message.body,
+        meta: `${result.message.from} -> ${result.message.to}`,
+        icon: isWork ? "ti-hand-grab" : "ti-send",
+        view: "messages",
+        messageId: result.message.id,
+        agentId: result.message.from,
+      });
+    }
+    return json(result.message, result.created ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function automaticMemoryTarget(message: { to: string; resolvedToAgent?: string; kind: string }): string | null {
+  if (isMechanicalMessageKind(message.kind)) return null;
+  const target = message.resolvedToAgent ?? message.to;
+  if (!isDirectTarget(target)) return null;
+  const agent = getAgent(target);
+  if (!agent || agent.kind !== "provider" || agent.status === "offline") return null;
+  return agent.id;
+}
+
+export const postSystemBroadcast: Handler = async (req) => {
+  const parsed = await parseBody<{ body: string; subject?: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.body) return error("body required");
+  try {
+    const msg = sendMessage({
+      from: "system",
+      to: "broadcast",
+      kind: "system",
+      subject: body.subject ?? undefined,
+      body: body.body,
+    });
+    emitNewMessage(msg);
+    return json(msg, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getMessages: Handler = (req) => {
+  const url = new URL(req.url);
+  const forAgent = url.searchParams.get("for");
+  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");
+  const limit = limitRaw ?? undefined;
+
+  const sinceRaw = parseQueryInt(url.searchParams.get("since"), {
+    min: 0,
+    max: Number.MAX_SAFE_INTEGER,
+  });
+  if (Number.isNaN(sinceRaw)) return error("since must be a non-negative integer");
+  const since = sinceRaw ?? undefined;
+
+  const sinceIdRaw = parseQueryInt(url.searchParams.get("sinceId"), {
+    min: 0,
+    max: Number.MAX_SAFE_INTEGER,
+  });
+  if (Number.isNaN(sinceIdRaw)) return error("sinceId must be a non-negative integer");
+  const sinceId = sinceIdRaw ?? undefined;
+
+  const channel = url.searchParams.get("channel") ?? undefined;
+
+  // No agent filter — return all recent messages
+  if (!forAgent) {
+    return json(listRecentMessages(limit ?? 100, since, channel));
+  }
+
+  return json(pollMessages({
+    for: forAgent,
+    since,
+    sinceId,
+    unread: url.searchParams.get("unread") === "true",
+    channel,
+    limit,
+  }));
+};
+
+export const getMessageById: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const msg = getMessage(id);
+  return msg ? json(msg) : error("message not found", 404);
+};
+
+export const getMessageThread: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const thread = getThread(id);
+  if (!thread.length) return error("message not found", 404);
+  return json(thread);
+};
+
+export const postClaimMessage: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.agentId) return error("agentId required");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = claimMessage(id, body.agentId, guard);
+  if (result.ok) {
+    emitMessageClaimed(id, body.agentId, getMessage(id)?.claimExpiresAt);
+    auditEvent({
+      clientId: "server-message-" + id + "-claimed-" + body.agentId,
+      kind: "task",
+      title: "Message claimed",
+      body: "Message #" + id,
+      meta: "by " + body.agentId,
+      icon: "ti-user-check",
+      view: "work",
+      messageId: id,
+      agentId: body.agentId,
+    });
+    if (result.task) {
+      emitTaskChanged(result.task, "task.claimed");
+      void dispatchTaskCallbacks(result.task.id, "task.claimed");
+    }
+    return json({ ok: true, task: result.task, claimExpiresAt: getMessage(id)?.claimExpiresAt });
+  }
+  const status =
+    result.error === "message not found" ? 404 :
+    result.error === "claiming agent not found" ? 400 :
+    result.error === "message is not claimable" ? 400 :
+    409;
+  return error(result.error!, status);
+};
+
+export const postRenewMessageClaim: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<{ agentId: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const agentId = parsed.body?.agentId;
+  if (!agentId) return error("agentId required");
+  let guard: AgentSessionGuard | undefined;
+  try {
+    guard = normalizeAgentSessionGuard(req, parsed.body);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+  const result = renewMessageClaim(id, agentId, guard);
+  if (!result.ok) {
+    const status =
+      result.error === "message not found" ? 404 :
+      result.error === "claiming agent not found" ? 400 :
+      result.error === "message is not claimable" ? 400 :
+      409;
+    return error(result.error!, status);
+  }
+  emitMessageClaimed(id, agentId, getMessage(id)?.claimExpiresAt);
+  if (result.task) emitTaskChanged(result.task, "task.updated");
+  return json({ ok: true, claimExpiresAt: getMessage(id)?.claimExpiresAt });
+};
+
+export const patchMessage: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<{ readBy: string }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!body?.readBy) return error("readBy required");
+  if (!markRead(id, body.readBy)) return error("message not found", 404);
+  const msg = getMessage(id);
+  if (msg) emitMessageDeliveryUpdated(msg);
+  return json({ ok: true });
+};
+
+function telegramTargetFromMessage(msg: Message): { chatId: string; messageId: string; accountId?: string } | null {
+  const source = msg.payload?.source;
+  const sourceTelegram = isRecord(source) && isRecord(source.telegram) ? source.telegram : undefined;
+  const replyContext = msg.payload?.replyContext;
+  const replySource = isRecord(replyContext) && isRecord(replyContext.source) ? replyContext.source : undefined;
+  const replyTelegram = replySource && isRecord(replySource.telegram) ? replySource.telegram : undefined;
+  const telegram = sourceTelegram ?? replyTelegram;
+  if (!telegram) return null;
+  const chatId = cleanString(telegram.chatId, "telegram.chatId", { max: 120 });
+  const messageId = cleanString(telegram.messageId, "telegram.messageId", { max: 120 });
+  if (!chatId || !messageId) return null;
+  const channel = isRecord(msg.payload?.channel) ? msg.payload.channel : undefined;
+  const accountId = channel ? cleanString(channel.accountId, "payload.channel.accountId", { max: 200 }) : undefined;
+  return { chatId, messageId, accountId };
+}
+
+function channelReactionActor(actorId: string): Record<string, unknown> {
+  const agent = getAgent(actorId);
+  return {
+    id: actorId,
+    kind: actorId === "user" ? "human" : "agent",
+    displayName: agent?.label ?? agent?.name ?? actorId,
+  };
+}
+
+function sendOutboundChannelReaction(parent: Message, actorId: string, emoji: string): void {
+  if (!parent.channel) return;
+  const target = telegramTargetFromMessage(parent);
+  if (!target) return;
+  const payloadChannel = isRecord(parent.payload?.channel) ? parent.payload.channel : {};
+  const accountId = target.accountId ?? cleanString(payloadChannel.accountId, "payload.channel.accountId", { max: 200 }) ?? "default";
+  const conversation = isRecord(parent.payload?.conversation) ? parent.payload.conversation : undefined;
+  const now = Date.now();
+  const result = sendMessageWithResult({
+    from: actorId,
+    to: parent.channel,
+    kind: "channel.event",
+    channel: parent.channel,
+    body: `Reaction: ${emoji}`,
+    idempotencyKey: `reaction:${parent.id}:${actorId}:${emoji}:${now}`,
+    payload: {
+      schema: "agent-relay.channel.v1",
+      channel: {
+        provider: cleanString(payloadChannel.provider, "payload.channel.provider", { max: 80 }) ?? "telegram",
+        accountId,
+        agentId: parent.channel,
+      },
+      direction: "outbound",
+      conversation: conversation ?? { id: `telegram:${accountId}:dm:${target.chatId}`, type: "dm" },
+      actor: channelReactionActor(actorId),
+      event: {
+        id: `relay:${parent.id}:reaction:${actorId}:${now}`,
+        type: "message.reaction",
+        ts: new Date(now).toISOString(),
+      },
+      reaction: {
+        emoji,
+        action: "add",
+        target: {
+          source: {
+            telegram: {
+              chatId: target.chatId,
+              messageId: target.messageId,
+            },
+          },
+        },
+      },
+    },
+  });
+  if (result.created) {
+    if (result.message.deliveryStatus === "queued") emitMessageQueued(result.message);
+    else emitNewMessage(result.message);
+  }
+}
+
+export const postMessageReaction: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("reaction body must be an object");
+    const actorId = cleanString(parsed.body.actorId, "actorId", { max: 200 }) ?? "user";
+    const emoji = reactionEmoji(parsed.body.emoji);
+    const action = cleanString(parsed.body.action, "action", { max: 20 }) ?? "add";
+    if (action !== "add" && action !== "remove") throw new ValidationError("action must be add or remove");
+    const result = setMessageReaction({ messageId: id, actorId, emoji, action });
+    if (!result.ok) return error(result.error, result.error === "message not found" ? 404 : 400);
+    emitMessageReactionUpdated(result.message);
+    if (action === "add") sendOutboundChannelReaction(result.message, actorId, emoji);
+    sendReactionNotificationToAuthor(result.message, actorId, emoji, action);
+    return json(result.message);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteMessageById: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid message id");
+  if (!deleteMessage(id)) return error("message not found", 404);
+  emitMessageDeleted(id);
+  return json({ ok: true });
+};
+
+export const getCursorRoute: Handler = () => json({ latestId: getLatestMessageId() });

package/src/routes/orchestrator-bootstrap.ts

@@ -0,0 +1,100 @@
+// Auto-split from routes.ts (#299). Domain: orchestrator-bootstrap.
+import { SPAWN_PROVIDERS, isRecord } from "agent-relay-sdk";
+import { VERSION } from "../config";
+import { ValidationError } from "../db";
+import { authorizeRoute, cleanSafeNumber, error, json, parseBody, type Handler } from "./_shared";
+import { cleanString, cleanStringArray } from "../validation";
+import { createToken, revokeToken } from "../token-db";
+import { getComponentAuth } from "../security";
+import { issueOrchestratorRuntimeToken } from "../runtime-tokens";
+import { type SpawnProvider } from "../types";
+
+export const postOrchestratorBootstrap: 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 baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
+    const providers = cleanStringArray(parsed.body.providers, "providers", { itemMax: 80, maxItems: 50 }) as SpawnProvider[] | undefined;
+    const apiPort = cleanSafeNumber(parsed.body.apiPort) ?? 4860;
+    if (!Number.isInteger(apiPort) || apiPort < 1 || apiPort > 65535) throw new ValidationError("apiPort must be an integer from 1 to 65535");
+    const relayUrl = cleanString(parsed.body.relayUrl, "relayUrl", { max: 500 }) ?? new URL(req.url).origin;
+    const version = cleanString(parsed.body.version, "version", { max: 80 }) ?? VERSION;
+    const pathPrefix = cleanStringArray(parsed.body.pathPrefix, "pathPrefix", { itemMax: 80, maxItems: 50 });
+    const providerList = providers?.length ? providers : ["claude", "codex"];
+    for (const p of providerList) {
+      if (!SPAWN_PROVIDERS.includes(p as any)) {
+        throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+      }
+    }
+    const bootstrapToken = createToken({
+      sub: `orchestrator:${id}`,
+      role: "orchestrator-bootstrap",
+      scope: ["token:write"],
+      constraints: {
+        orchestrators: [id],
+      },
+      ttlSeconds: 15 * 60,
+      createdBy: "dashboard-bootstrap",
+    });
+    const args = [
+      "orchestrator", "install",
+      "--relay-url", relayUrl,
+      "--bootstrap-token", bootstrapToken.token,
+      "--id", id,
+      "--base-dir", baseDir,
+      "--providers", providerList.join(","),
+      "--api-port", String(apiPort),
+      "--version", version,
+      "--yes",
+    ];
+    for (const entry of pathPrefix ?? []) args.push("--path-prefix", entry);
+    const command = ["bunx", `agent-relay-server@${version}`, ...args].map(quoteInstallCommandArg).join(" ");
+    return json({
+      command,
+      relayUrl,
+      id,
+      baseDir,
+      providers: providerList,
+      apiPort,
+      version,
+      pathPrefix: pathPrefix ?? [],
+      token: bootstrapToken.record,
+      expiresAt: bootstrapToken.record.expiresAt,
+    }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postOrchestratorBootstrapExchange: 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 baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
+    const denied = authorizeRoute(req, { scope: "token:write", resource: { orchestratorId: id } });
+    if (denied) return denied;
+    const auth = getComponentAuth(req);
+    if (!auth || auth.role !== "orchestrator-bootstrap") return error("bootstrap token required", 403);
+    const runtimeToken = issueOrchestratorRuntimeToken({
+      orchestratorId: id,
+      baseDir,
+      createdBy: auth.jti ? `bootstrap:${auth.jti}` : "bootstrap",
+    });
+    if (auth.jti) revokeToken(auth.jti);
+    return json(runtimeToken, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function quoteInstallCommandArg(value: string): string {
+  if (/^[A-Za-z0-9_./:=,@+-]+$/.test(value)) return value;
+  if (value.startsWith("$HOME/") && !value.includes("\"") && !value.includes("`") && !value.includes("\\")) return `"${value}"`;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}