agent-relay-server 0.32.2 → 0.32.4

package/src/branch-landed.ts

@@ -1,9 +1,9 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
 import { notifySystemMessage } from "./notify";
-import { listAgents } from "./db";
+import { createActivityEvent, listAgents, updateWorkspaceStatus } from "./db";
 import { isAgentOnline } from "./agent-ref";
-import type { AgentCard, WorkspaceRecord } from "./types";
+import type { AgentCard, WorkspaceMergePreview, WorkspaceRecord } from "./types";
 
 export interface BranchLandedInput {
   /**
@@ -113,6 +113,42 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
   }
 }
 
+/**
+ * Finalize a workspace whose work landed in base out-of-band — a pr-strategy land whose
+ * PR merged (by anyone, incl. `gh pr merge`), or a squash/cherry-pick already in base
+ * (#304). Marks it terminal `merged`, records the merge SHA, and fires the same
+ * branch.landed push the local land path emits — a pr land never runs through the
+ * workspace.merge result handler, so without this the author never learns it shipped.
+ * Lives here (not maintenance.ts) so the giant doesn't grow and land-notify has one home.
+ */
+export function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: WorkspaceMergePreview): void {
+  const sha = typeof preview.prMergeSha === "string" ? preview.prMergeSha : undefined;
+  const via = preview.prMerged === true ? "pr" : "git";
+  updateWorkspaceStatus(ws.id, "merged", {
+    autoMerged: true,
+    mergedFromStatus: ws.status,
+    landedDetectedAt: Date.now(),
+    landedVia: via,
+    ...(sha ? { landedSha: sha } : {}),
+    autoConflict: false,
+  });
+  createActivityEvent({
+    clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
+    kind: "state",
+    title: "Workspace work landed in base",
+    body: `${ws.branch ?? ws.id} is ${via === "pr" ? "merged on the remote (PR)" : "already merged into base"} ${preview.baseRef ? `(${preview.baseRef})` : ""} — marking merged`,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-git-merge",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status, ...(sha ? { landedSha: sha } : {}) },
+  });
+  try {
+    notifyBranchLanded({ workspace: ws, mergedSha: sha, pushed: true });
+  } catch {
+    // Notification is best-effort; the merged status + activity event still stand.
+  }
+}
+
 // An agent is "on `main`" when its registered cwd equals the repo's main checkout — i.e. it
 // works in the base, not an isolated worktree. Excludes the author, pseudo agents (system/
 // user), channels, and offline sessions.

package/src/cli.ts

@@ -1617,7 +1617,7 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     throw new Error(WORKSPACE_USAGE);
   }
 
-  let id = currentWorkspaceId();
+  let id = currentWorkspaceId(), idExplicit = false; // idExplicit: --id was passed, not the ambient default (#307)
   let strategy: string | undefined;
   let purpose: string | undefined;
   let repo: string | undefined;
@@ -1628,7 +1628,7 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   let timeoutSeconds: number | undefined;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "--id" && i + 1 < args.length) id = args[++i];
+    if (arg === "--id" && i + 1 < args.length) { id = args[++i]; idExplicit = true; }
     else if (arg === "--strategy" && i + 1 < args.length) strategy = args[++i];
     else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
     else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
@@ -1651,7 +1651,7 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   }
 
   if (action === "cleanup-stale") {
-    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute });
+    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, ...(idExplicit && id ? { workspaceId: id } : {}) });
     console.log(JSON.stringify(result, null, 2));
     return;
   }

package/src/maintenance.ts

@@ -33,6 +33,7 @@ import {
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { reconcileLandedWorkspace } from "./branch-landed";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
 import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
@@ -434,8 +435,11 @@ function workspacePathWithinBase(path: string | undefined, baseDir: string | und
   return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
 }
 
-async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord): Promise<WorkspaceMergePreview | { available: false } | null> {
-  const query = new URLSearchParams({ path: workspace.worktreePath, checkPr: "1" });
+async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord, opts: { checkPr?: boolean } = {}): Promise<WorkspaceMergePreview | { available: false } | null> {
+  // `checkPr` costs a `gh` round-trip, so the caller opts in only where PR-merge ground
+  // truth is actionable (reconcile/land candidates), not for every badge-probe (#304).
+  const checkPr = opts.checkPr !== false;
+  const query = new URLSearchParams({ path: workspace.worktreePath, ...(checkPr ? { checkPr: "1" } : {}) });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
@@ -577,10 +581,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
-    const preview = await fetchHostMergePreview(orch.apiUrl, ws);
+    // Spend the `gh` PR-state round-trip only on reconcile-eligible rows; active/ready
+    // are excluded from reconcile, so their scan stays git-only (#304).
+    const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: LANDED_RECONCILE_STATUSES.has(ws.status) });
     if (!preview || (preview as { available?: false }).available === false) continue;
     const p = preview as WorkspaceMergePreview;
-    if (p.error || p.missing || p.conflict === undefined) continue;
+    if (p.error || p.missing) continue;
 
     const meta = ws.metadata as Record<string, unknown>;
 
@@ -605,29 +611,23 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     // merge_planned forever otherwise, and the conflict scan can even pin a
     // landed branch to `conflict`). Reconcile to the terminal `merged` status so
     // the dashboard stops showing it as unmerged and GC prunes it on schedule.
+    // This runs BEFORE the conflict-undefined skip below: a PR merged via a regular
+    // merge commit makes the branch an ancestor (ahead=0 → no-op → conflict comes
+    // back undefined), which the skip would otherwise drop, stranding the row at
+    // merge_planned — the exact #304 stall.
+    // Reconcile + finalize (record SHA, fire branch.landed) in branch-landed.ts so the
+    // giant doesn't grow (#291) and land-notify stays single-homed (#304).
     const landed = p.landed === true || p.prMerged === true;
     if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
-      updateWorkspaceStatus(ws.id, "merged", {
-        autoMerged: true,
-        mergedFromStatus: ws.status,
-        landedDetectedAt: Date.now(),
-        landedVia: p.prMerged === true ? "pr" : "git",
-        autoConflict: false,
-      });
+      reconcileLandedWorkspace(ws, p);
       merged.push(ws.id);
-      createActivityEvent({
-        clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
-        kind: "state",
-        title: "Workspace work landed in base",
-        body: `${ws.branch ?? ws.id} is ${p.prMerged === true ? "merged on the remote (PR)" : "already merged into base"} ${p.baseRef ? `(${p.baseRef})` : ""} — marking merged`,
-        meta: ws.branch ?? ws.id,
-        icon: "ti-git-merge",
-        view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status },
-      });
       continue;
     }
 
+    // Past here we act on the conflict signal — skip when the host couldn't assess it
+    // (undefined): never flag/clear a conflict on incomplete data.
+    if (p.conflict === undefined) continue;
+
     if (p.conflict === true && ws.status !== "conflict") {
       updateWorkspaceStatus(ws.id, "conflict", {
         autoConflict: true,

package/src/mcp.ts

@@ -45,7 +45,7 @@ import {
   isIntegrationAllowed,
 } from "./security";
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
-import { applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
+import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
@@ -1011,7 +1011,7 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
     action,
     agentId: callerAgentId(auth) ?? auth.actor,
     detail: optionalString(args.detail, "detail", 4000),
-    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const) as WorkspaceMergeStrategy | undefined) : undefined,
+    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", LAND_STRATEGIES) as WorkspaceMergeStrategy | undefined) : undefined,
     deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
     prTitle: optionalString(args.prTitle, "prTitle", 240),
     prBody: optionalString(args.prBody, "prBody", 8000),

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