agent-relay-server 0.32.2 → 0.32.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.32.2",
+  "version": "0.32.3",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/src/ratchet-files.ts

@@ -0,0 +1,37 @@
+// Shared file enumeration for the ratchet tests (duplication + file-size).
+//
+// Kept in ONE place so the two ratchets can never drift on *which* files they
+// scan — a file-size ratchet that duplicated its own harness would be the very
+// thing it exists to prevent (see issue #300). Both `duplication-ratchet.test.ts`
+// and `file-size-ratchet.test.ts` import from here.
+
+import { Glob } from "bun";
+
+// Source roots scanned by the ratchets. Mirror real package layout; generated
+// and bundled output (public/, dist/, node_modules/) is excluded below.
+export const RATCHET_ROOTS = [
+  "src",
+  "sdk/src",
+  "client",
+  "orchestrator/src",
+  "runner/src",
+  "connectors",
+  "dashboard/src",
+  "scripts",
+  "examples",
+];
+
+// All tracked first-party .ts/.tsx source files, excluding tests, type
+// declarations, and build output. Paths are returned relative to repo root.
+export function ratchetSourceFiles(): string[] {
+  const files: string[] = [];
+  for (const root of RATCHET_ROOTS) {
+    const glob = new Glob("**/*.{ts,tsx}");
+    for (const rel of glob.scanSync({ cwd: root, onlyFiles: true })) {
+      if (rel.includes("node_modules") || rel.includes("dist/")) continue;
+      if (rel.endsWith(".test.ts") || rel.endsWith(".test.tsx") || rel.endsWith(".d.ts")) continue;
+      files.push(`${root}/${rel}`);
+    }
+  }
+  return files;
+}

package/src/routes/_shared.ts

@@ -0,0 +1,376 @@
+// Auto-split from routes.ts (#299). Domain: _shared.
+import { MAX_BODY_BYTES, getIntegrationTokens } from "../config";
+import { MemoryBrokerContractError } from "../memory-broker-contract";
+import { ValidationError, createActivityEvent, createCallbackDelivery, finishCallbackDelivery, getAgent, getTask, normalizeReactionEmoji, sendMessageWithResult } from "../db";
+import { cleanEpoch, cleanString, optionalEnum } from "../validation";
+import { emitActivityEvent, emitMessageQueued, emitNewMessage } from "../sse";
+import { emitRelayEvent } from "../events";
+import { errMessage, isRecord } from "agent-relay-sdk";
+import { generateSpawnRequestId } from "../spawn-command";
+import { getComponentAuth, getIntegrationAuth, isAuthorized, isRequestAuthorizedFor } from "../security";
+import { readBodyBytes } from "../http-body";
+import { type ActivityEventInput, type AgentSessionGuard, type ArtifactKind, type AttachmentRef, type Command, type MemoryBrokerContext, type Message } from "../types";
+
+export type Handler = (
+  req: Request,
+  params: Record<string, string>
+) => Response | Promise<Response>;
+
+export const json = (data: unknown, status = 200) =>
+  Response.json(data, { status });
+
+export const error = (msg: string, status = 400) =>
+  json({ error: msg }, status);
+
+export function authorizeRoute(req: Request, check: Parameters<typeof isRequestAuthorizedFor>[1]): Response | null {
+  if (!hasPresentedCredential(req)) return null;
+  return isRequestAuthorizedFor(req, check) ? null : error("forbidden", 403);
+}
+
+function hasPresentedCredential(req: Request): boolean {
+  return Boolean(req.headers.get("authorization") || req.headers.get("x-agent-relay-token") || new URL(req.url).searchParams.get("token"));
+}
+
+export function authAuditMetadata(req: Request): Record<string, unknown> {
+  const component = getComponentAuth(req);
+  if (component) {
+    return {
+      auth: {
+        type: "component",
+        sub: component.sub,
+        role: component.role,
+        jti: component.jti,
+        scope: component.scope,
+        constraints: component.constraints,
+      },
+    };
+  }
+  const integration = getIntegrationAuth(req);
+  if (integration) {
+    return {
+      auth: {
+        type: "integration",
+        name: integration.name,
+        scopes: integration.scopes,
+        targets: integration.targets,
+        channels: integration.channels,
+      },
+    };
+  }
+  return hasPresentedCredential(req) ? { auth: { type: "root" } } : {};
+}
+
+export function isRootCredentialRequest(req: Request): boolean {
+  return hasPresentedCredential(req) && isAuthorized(req) && !getComponentAuth(req) && !getIntegrationAuth(req);
+}
+
+function sanitizeAttribution(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined;
+  // eslint-disable-next-line no-control-regex
+  const cleaned = raw.replace(/[\x00-\x1f\x7f]/g, "").trim();
+  if (!cleaned) return undefined;
+  return cleaned.length > 120 ? cleaned.slice(0, 120) : cleaned;
+}
+
+export function dashboardAttribution(req: Request, surface?: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const client = sanitizeAttribution(req.headers.get("x-dashboard-client-id"));
+  const session = sanitizeAttribution(req.headers.get("x-dashboard-session-id"));
+  const view = sanitizeAttribution(req.headers.get("x-dashboard-view"));
+  const component = isRecord(surface) ? sanitizeAttribution(surface.component) : undefined;
+  if (client) out.client = client;
+  if (session) out.session = session;
+  if (view) out.view = view;
+  if (component) out.component = component;
+  if (Object.keys(out).length === 0) return {};
+  out.route = `${req.method} ${new URL(req.url).pathname}`;
+  return { surface: out };
+}
+
+type ParseBodyResult<T> =
+  | { ok: true; body: T | null }
+  | { ok: false; status: number; error: string };
+
+export async function parseBody<T>(req: Request): Promise<ParseBodyResult<T>> {
+  if (!req.body) return { ok: true, body: null };
+  const read = await readBodyBytes(req.body, MAX_BODY_BYTES);
+  if (!read.ok) return { ok: false, status: read.status, error: read.error };
+  if (read.bytes.byteLength === 0) return { ok: true, body: null };
+  try {
+    const decoded = new TextDecoder().decode(read.bytes);
+    return { ok: true, body: JSON.parse(decoded) as T };
+  } catch {
+    return { ok: false, status: 400, error: "invalid JSON body" };
+  }
+}
+
+export function parseId(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0 || n > Number.MAX_SAFE_INTEGER) return null;
+  return n;
+}
+
+export function parseQueryInt(
+  raw: string | null,
+  opts: { min: number; max: number }
+): number | null {
+  if (raw === null) return null;
+  if (!/^-?\d+$/.test(raw)) return Number.NaN;
+
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n)) return Number.NaN;
+  if (n < opts.min || n > opts.max) return Number.NaN;
+  return n;
+}
+
+export const VALID_AGENT_STATUSES = ["online", "idle", "busy", "stale", "offline"] as const;
+
+export const VALID_AGENT_ACTIONS = ["restart", "shutdown", "reconnect", "compact", "clearContext", "resume", "interrupt"] as const;
+
+export const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "orphaned", "done", "failed", "canceled"] as const;
+
+export const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
+
+export const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
+
+export function normalizeAgentSessionGuard(req: Request, body: unknown): AgentSessionGuard | undefined {
+  const record = isRecord(body) ? body : {};
+  const headerInstance = req.headers.get("x-agent-relay-instance-id") ?? undefined;
+  const headerEpoch = req.headers.get("x-agent-relay-epoch") ?? undefined;
+  const instanceId = cleanString(headerInstance ?? record.instanceId, "instanceId", { max: 200 });
+  const rawEpoch = headerEpoch === undefined ? record.epoch : Number(headerEpoch);
+  const epoch = cleanEpoch(rawEpoch, "epoch");
+
+  if (!instanceId && epoch === undefined) return undefined;
+  if (!instanceId) throw new ValidationError("instanceId required when epoch is provided");
+  return { instanceId, epoch };
+}
+
+export function agentSessionStatus(errorMessage: string | undefined): number {
+  if (errorMessage === "agent not found") return 404;
+  if (errorMessage === "stale agent instance") return 409;
+  return 400;
+}
+
+export function withPayloadAttachments(
+  payload: Record<string, unknown>,
+  attachments: Array<Record<string, unknown>> | undefined,
+): Record<string, unknown> {
+  if (!attachments) return payload;
+  if (payload.attachments !== undefined) {
+    throw new ValidationError("attachments must be provided either top-level or in payload.attachments, not both");
+  }
+  return { ...payload, attachments };
+}
+
+export function validateChannelAttachmentSourceRef(ref: unknown, field: string): void {
+  if (!isRecord(ref)) throw new ValidationError(`${field} must be an object`);
+  const type = cleanString(ref.type, `${field}.type`, { required: true, max: 40 });
+  if (type !== "relay-blob" && type !== "external-url" && type !== "channel-file") {
+    throw new ValidationError(`${field}.type must be relay-blob, external-url, or channel-file`);
+  }
+  if (type === "external-url") cleanString(ref.url, `${field}.url`, { required: true, max: 2048 });
+  if (type === "relay-blob" || type === "channel-file") cleanString(ref.id, `${field}.id`, { required: true, max: 400 });
+  if (type === "channel-file") {
+    cleanString(ref.provider, `${field}.provider`, { max: 80 });
+    cleanString(ref.uniqueId, `${field}.uniqueId`, { max: 400 });
+  }
+}
+
+export function cleanAttachmentRefs(value: unknown, field = "attachments"): AttachmentRef[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
+  return value.map((item, index) => {
+    if (!isRecord(item)) throw new ValidationError(`${field}[${index}] must be an object`);
+    const ref = item.ref;
+    if (ref !== undefined) validateChannelAttachmentSourceRef(ref, `${field}[${index}].ref`);
+    const normalizedRef = isRecord(ref) ? { ref: { ...ref } as AttachmentRef["ref"] } : {};
+    return {
+      artifactId: cleanString(item.artifactId, `${field}[${index}].artifactId`, { required: true, max: 120 })!,
+      kind: optionalEnum(item.kind, `${field}[${index}].kind`, VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
+      role: optionalEnum(item.role, `${field}[${index}].role`, VALID_ARTIFACT_ROLES) as "media" | "patch" | "report" | "log" | "output" | "input" | undefined,
+      title: cleanString(item.title, `${field}[${index}].title`, { max: 240 }),
+      ...normalizedRef,
+      ...(isRecord(item.metadata) ? { metadata: item.metadata } : {}),
+    };
+  });
+}
+
+export function metaString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = meta?.[key];
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+export async function dispatchTaskCallbacks(taskId: number, eventType: string): Promise<void> {
+  const task = getTask(taskId);
+  if (!task) return;
+  const requestedTarget = typeof task.metadata?.relayRequestedTarget === "string" ? task.metadata.relayRequestedTarget : undefined;
+  const integrations = getIntegrationTokens()
+    .filter((integration) => integration.name === task.source)
+    .filter((integration) => integration.callbackUrl)
+    .filter((integration) => !integration.targets?.length || integration.targets.includes(task.target) || Boolean(requestedTarget && integration.targets.includes(requestedTarget)))
+    .filter((integration) => !integration.channels?.length || !task.channel || integration.channels.includes(task.channel));
+
+  for (const integration of integrations) {
+    const payload = { event: eventType, task };
+    const deliveryId = createCallbackDelivery(task.id, integration.callbackUrl!, eventType, payload);
+    void postCallback(deliveryId, integration.callbackUrl!, payload);
+  }
+}
+
+async function postCallback(deliveryId: number, url: string, payload: unknown): Promise<void> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    finishCallbackDelivery(deliveryId, response.ok, response.ok ? undefined : `${response.status} ${response.statusText}`);
+  } catch (e) {
+    finishCallbackDelivery(deliveryId, false, errMessage(e));
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function auditEvent(input: ActivityEventInput): void {
+  try {
+    const event = createActivityEvent({
+      ...input,
+      metadata: { source: "server", ...(input.metadata ?? {}) },
+    });
+    emitActivityEvent(event);
+  } catch {
+    // Audit trail writes must never block relay behavior.
+  }
+}
+
+export function memoryContext(req: Request): MemoryBrokerContext {
+  const component = getComponentAuth(req);
+  if (component) {
+    return { now: Date.now(), actor: component.sub, scopes: component.scope, relayUrl: new URL(req.url).origin };
+  }
+  const integration = getIntegrationAuth(req);
+  if (integration) {
+    return { now: Date.now(), actor: integration.name, scopes: integration.scopes, relayUrl: new URL(req.url).origin };
+  }
+  return { now: Date.now(), actor: "server", scopes: ["*"], relayUrl: new URL(req.url).origin };
+}
+
+export function memoryErrorResponse(e: unknown): Response {
+  if (e instanceof ValidationError || e instanceof MemoryBrokerContractError) return error(e.message, 400);
+  throw e;
+}
+
+export type AgentControlAction = (typeof VALID_AGENT_ACTIONS)[number];
+
+export function agentControlActionIcon(action: AgentControlAction): string {
+  if (action === "shutdown") return "ti-power";
+  if (action === "compact") return "ti-compress";
+  if (action === "clearContext") return "ti-eraser";
+  if (action === "resume") return "ti-player-play";
+  if (action === "interrupt") return "ti-player-stop";
+  return "ti-refresh";
+}
+
+export function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
+  if (JSON.stringify(value).length > 65_536) throw new ValidationError(`${field} is too large`);
+  return value;
+}
+
+export function cleanSafeNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function commandEventType(command: Command): string {
+  if (command.status === "pending") return "command.requested";
+  return `command.${command.status}`;
+}
+
+export function emitCommand(command: Command): void {
+  emitRelayEvent({
+    type: commandEventType(command),
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
+export function normalizeConfigPathParam(raw: string | undefined, field: string): string {
+  return cleanString(raw, field, { required: true, max: 240 })!;
+}
+
+export function spawnRequestId(): string {
+  return generateSpawnRequestId();
+}
+
+export function reactionEmoji(value: unknown, field = "emoji"): string {
+  const emoji = cleanString(value, field, { required: true, max: 64 })!;
+  const normalized = normalizeReactionEmoji(emoji);
+  if (!normalized.trim()) throw new ValidationError(`${field} required`);
+  return normalized;
+}
+
+function reactionActorView(actorId: string): Record<string, unknown> {
+  const agent = getAgent(actorId);
+  return {
+    id: actorId,
+    kind: actorId === "user" ? "human" : agent?.kind === "channel" ? "channel" : "agent",
+    displayName: agent?.label ?? agent?.name ?? actorId,
+  };
+}
+
+function reactionNotificationSender(parent: Message, actorId: string): string {
+  if (getAgent(actorId)) return actorId;
+  return parent.channel && getAgent(parent.channel) ? parent.channel : "user";
+}
+
+export function sendReactionNotificationToAuthor(parent: Message, actorId: string, emoji: string, action: "add" | "remove"): void {
+  if (parent.from === "user" || parent.from === "system") return;
+  const targetAgent = getAgent(parent.from);
+  if (!targetAgent || targetAgent.kind === "channel") return;
+  const from = reactionNotificationSender(parent, actorId);
+  if (from === parent.from) return;
+  const now = Date.now();
+  const actor = reactionActorView(actorId);
+  const verb = action === "remove" ? "removed reaction" : "reacted";
+  const result = sendMessageWithResult({
+    from,
+    to: parent.from,
+    kind: "system",
+    body: `${String(actor.displayName ?? actorId)} ${verb} ${emoji} to message #${parent.id}.`,
+    replyTo: parent.id,
+    idempotencyKey: `reaction-notify:${parent.id}:${actorId}:${emoji}:${action}:${now}`,
+    payload: {
+      schema: "agent-relay.reaction.v1",
+      reactionNotification: true,
+      event: {
+        id: `relay:${parent.id}:reaction-notify:${actorId}:${emoji}:${action}:${now}`,
+        type: "message.reaction",
+        ts: new Date(now).toISOString(),
+      },
+      reaction: {
+        emoji,
+        action,
+        actor,
+        target: {
+          relayMessageId: parent.id,
+          from: parent.from,
+          to: parent.to,
+          kind: parent.kind,
+          bodyPreview: parent.body.length > 240 ? `${parent.body.slice(0, 240)}\n[truncated]` : parent.body,
+        },
+      },
+    },
+  });
+  if (result.created) {
+    if (result.message.deliveryStatus === "queued") emitMessageQueued(result.message);
+    else emitNewMessage(result.message);
+  }
+}

package/src/routes/activity.ts

@@ -0,0 +1,61 @@
+// Auto-split from routes.ts (#299). Domain: activity.
+import { ValidationError, createActivityEvent, listActivityEvents } from "../db";
+import { cleanMeta, cleanOperatorId, cleanPositiveId, cleanString, optionalEnum } from "../validation";
+import { emitActivityEvent } from "../sse";
+import { error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import { isRecord } from "agent-relay-sdk";
+import { type ActivityEventInput, type ActivityKind } from "../types";
+
+const VALID_ACTIVITY_KINDS = ["message", "reply", "question", "operator", "pair", "task", "state"] as const;
+
+function normalizeActivityInput(body: unknown): ActivityEventInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  return {
+    operatorId: cleanOperatorId(body.operatorId),
+    clientId: cleanString(body.clientId, "clientId", { max: 240 }),
+    kind: optionalEnum(body.kind, "kind", VALID_ACTIVITY_KINDS, "operator") as ActivityKind,
+    title: cleanString(body.title, "title", { required: true, max: 200 })!,
+    body: cleanString(body.body, "body", { max: 1000 }),
+    meta: cleanString(body.meta, "meta", { max: 500 }),
+    icon: cleanString(body.icon, "icon", { max: 80 }),
+    view: cleanString(body.view, "view", { max: 80 }),
+    peer: cleanString(body.peer, "peer", { max: 200 }),
+    messageId: cleanPositiveId(body.messageId, "messageId"),
+    pairId: cleanString(body.pairId, "pairId", { max: 120 }),
+    taskId: cleanPositiveId(body.taskId, "taskId"),
+    agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+
+export const getActivityEvents: Handler = (req) => {
+  const url = new URL(req.url);
+  try {
+    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 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");
+    return json(listActivityEvents({
+      operatorId: cleanString(url.searchParams.get("operatorId") ?? undefined, "operatorId", { max: 200 }),
+      agentId: cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 200 }),
+      limit: limitRaw ?? 200,
+      since: sinceRaw ?? undefined,
+    }));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postActivityEvent: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const event = createActivityEvent(normalizeActivityInput(parsed.body));
+    emitActivityEvent(event);
+    return json(event, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

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;
+  }
+};