agent-relay-server 0.32.1 → 0.32.3

package/src/routes/insights.ts

@@ -0,0 +1,81 @@
+// Auto-split from routes.ts (#299). Domain: insights.
+import { ValidationError } from "../db";
+import { cleanString } from "../validation";
+import { emitConfigChanged } from "../sse";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getInsightsConfigEntry, setInsightsConfig } from "../config-store";
+import { getObservationStats, listObservationProjects, listObservations, recordObservation } from "../insights-db";
+import { isRecord } from "agent-relay-sdk";
+
+export const getInsightsConfigRoute: Handler = () => json(getInsightsConfigEntry());
+
+export const putInsightsConfigRoute: Handler = async (req) => {
+  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 = setInsightsConfig(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;
+  }
+};
+
+export const getInsightsObservationsRoute: Handler = (req) => {
+  const url = new URL(req.url);
+  const project = url.searchParams.get("project") ?? undefined;
+  const signal = url.searchParams.get("signal") ?? undefined;
+  const sessionId = url.searchParams.get("session") ?? undefined;
+  const limitRaw = url.searchParams.get("limit");
+  const limit = limitRaw ? Number(limitRaw) : undefined;
+  const observations = listObservations({ project, signal, sessionId, limit: Number.isFinite(limit) ? limit : undefined });
+  return json({
+    observations,
+    stats: getObservationStats(signal),
+    projects: listObservationProjects(),
+  });
+};
+
+function sanitizeObservationOccurredAt(occurredAt: unknown): number | undefined {
+  if (typeof occurredAt !== "number" || !Number.isFinite(occurredAt)) return undefined;
+  if (occurredAt <= 0 || occurredAt > Date.now() + 60_000) return undefined;
+  return Math.floor(occurredAt);
+}
+
+export const postInsightsObservationRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("JSON object body required", 400);
+  // Master switch + per-signal toggle gate ingestion, so flipping a feature off in the
+  // dashboard actually stops data landing — not just hides it.
+  const config = getInsightsConfigEntry().value;
+  if (!config.enabled) return error("insights disabled", 409);
+  const body = parsed.body;
+  const signal = typeof body.signal === "string" ? body.signal.trim() : "";
+  if (signal === "introspection" && !config.introspection.enabled) return error("introspection disabled", 409);
+  if (signal === "context_ratio" && !config.contextRatio.enabled) return error("contextRatio disabled", 409);
+  try {
+    const observation = recordObservation({
+      sessionId: typeof body.sessionId === "string" ? body.sessionId : "",
+      agentId: typeof body.agentId === "string" ? body.agentId : undefined,
+      project: typeof body.project === "string" ? body.project : undefined,
+      signal,
+      value: isRecord(body.value) ? body.value : {},
+      outcome: isRecord(body.outcome) ? body.outcome : undefined,
+      source: body.source === "server" ? "server" : "agent",
+      // For insights the event time IS the record time (end-of-session). When the Runner
+      // backfilled this through its durable outbox (#196), occurredAt preserves the real
+      // moment rather than the later server-receive time.
+      createdAt: sanitizeObservationOccurredAt(body.occurredAt),
+    });
+    return json(observation, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routes/integrations.ts

@@ -0,0 +1,592 @@
+// Auto-split from routes.ts (#299). Domain: integrations.
+import { INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES, getIntegrationTokens, type IntegrationTokenConfig } from "../config";
+import { VALID_ARTIFACT_KINDS, VALID_ARTIFACT_ROLES, VALID_TASK_STATUSES, agentSessionStatus, authorizeRoute, cleanAttachmentRefs, dispatchTaskCallbacks, error, json, normalizeAgentSessionGuard, parseBody, reactionEmoji, sendReactionNotificationToAuthor, validateChannelAttachmentSourceRef, withPayloadAttachments, type Handler } from "./_shared";
+import { ValidationError, evaluatePoolBindings, findMessageByTelegramSource, getAgent, getChannel, getMessage, ingestIntegrationEvent, isIntegrationRegistryEnabled, listChannelBindings, listChannels, listIntegrationRegistry, listIntegrationTaskStats, resolveChannelRoutes, sendMessageWithResult, setMessageReaction, upsertChannelBinding, upsertIntegrationRegistry, validateAgentSession } from "../db";
+import { cleanMeta, cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { emitChannelActivity, emitMessageQueued, emitMessageReactionUpdated, emitNewMessage, emitTaskChanged } from "../sse";
+import { getComponentAuth, getIntegrationAuth, hasIntegrationScope, isRequestAuthorizedFor } from "../security";
+import { isRecord } from "agent-relay-sdk";
+import { type ChannelBinding, type ChannelBindingMode, type ChannelRouteTarget, type ChannelSummary, type IntegrationEventInput, type IntegrationSummary } from "../types";
+
+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_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
+
+const integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
+
+function normalizeChannelBindingInput(body: unknown): {
+  channelId: string;
+  conversationId?: string;
+  target: ChannelRouteTarget;
+  mode?: ChannelBindingMode;
+  priority?: number;
+} {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const channelId = cleanString(body.channelId, "channelId", { required: true, max: 200 })!;
+  const conversationId = cleanString(body.conversationId, "conversationId", { max: 300 });
+  const mode = optionalEnum(body.mode, "mode", VALID_CHANNEL_BINDING_MODES, "exclusive") as ChannelBindingMode | undefined;
+  const priority = typeof body.priority === "number" && Number.isSafeInteger(body.priority) ? body.priority : undefined;
+
+  let target: ChannelRouteTarget | undefined;
+  if (typeof body.target === "string") {
+    target = routeTargetFromAddress(body.target);
+  } else if (isRecord(body.target)) {
+    const type = optionalEnum(body.target.type, "target.type", VALID_CHANNEL_BINDING_TARGET_TYPES)!;
+    const id = type === "broadcast" ? undefined : cleanString(body.target.id, "target.id", { required: true, max: 240 })!;
+    if (type === "orchestrator") throw new ValidationError("orchestrator channel targets are not supported yet");
+    target = type === "broadcast" ? { type: "broadcast" } : { type, id } as ChannelRouteTarget;
+  }
+  if (!target) throw new ValidationError("target required");
+
+  return { channelId, conversationId, target, mode, priority };
+}
+
+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) };
+  if (target === "broadcast") return { type: "broadcast" };
+  if (target.startsWith("orchestrator:")) throw new ValidationError("orchestrator channel targets are not supported yet");
+  return { type: "agent", id: target };
+}
+
+function messageTargetForChannelTarget(target: ChannelRouteTarget, binding?: ChannelBinding): string {
+  if (target.type === "orchestrator") throw new ValidationError("orchestrator channel targets are not supported yet");
+  if (target.type === "pool") {
+    if (!binding?.poolAgentId) throw new ValidationError("pool slot is unclaimed — no eligible agent available");
+    return binding.poolAgentId;
+  }
+  if (target.type === "label") return `label:${target.id}`;
+  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;
+}
+
+function payloadConversationId(payload: Record<string, unknown>): string | undefined {
+  const conversation = payload.conversation;
+  if (isRecord(conversation)) return cleanString(conversation.id, "payload.conversation.id", { max: 300 });
+  return undefined;
+}
+
+function payloadDedupeKey(payload: Record<string, unknown>): string | undefined {
+  const dedupe = payload.dedupe;
+  if (isRecord(dedupe)) return cleanString(dedupe.key, "payload.dedupe.key", { max: 240 });
+  return undefined;
+}
+
+const EPHEMERAL_CHANNEL_EVENT_TYPES = new Set([
+  "typing.started",
+  "typing.stopped",
+  "message.read",
+  "message.delivered",
+  "presence.updated",
+]);
+
+function channelPayloadEventType(payload: Record<string, unknown>): string {
+  const event = payload.event;
+  if (!isRecord(event)) throw new ValidationError("payload.event must be an object");
+  return cleanString(event.type, "payload.event.type", { required: true, max: 80 })!;
+}
+
+function validateChannelEnvelope(payload: Record<string, unknown>, channel: ChannelSummary): void {
+  const schema = cleanString(payload.schema, "payload.schema", { required: true, max: 80 });
+  if (schema !== "agent-relay.channel.v1") throw new ValidationError("payload.schema must be agent-relay.channel.v1");
+
+  const payloadChannel = payload.channel;
+  if (!isRecord(payloadChannel)) throw new ValidationError("payload.channel must be an object");
+  const provider = cleanString(payloadChannel.provider, "payload.channel.provider", { required: true, max: 80 });
+  const accountId = cleanString(payloadChannel.accountId, "payload.channel.accountId", { required: true, max: 200 });
+  const agentId = cleanString(payloadChannel.agentId, "payload.channel.agentId", { required: true, max: 200 });
+  if (provider !== channel.type || accountId !== channel.accountId || agentId !== channel.agentId) {
+    throw new ValidationError("payload.channel does not match channel identity");
+  }
+
+  const direction = cleanString(payload.direction, "payload.direction", { required: true, max: 20 });
+  if (direction !== "inbound" && direction !== "outbound") throw new ValidationError("payload.direction must be inbound or outbound");
+
+  const conversation = payload.conversation;
+  if (!isRecord(conversation)) throw new ValidationError("payload.conversation must be an object");
+  cleanString(conversation.id, "payload.conversation.id", { required: true, max: 300 });
+  cleanString(conversation.type, "payload.conversation.type", { required: true, max: 80 });
+
+  const actor = payload.actor;
+  if (!isRecord(actor)) throw new ValidationError("payload.actor must be an object");
+  cleanString(actor.id, "payload.actor.id", { required: true, max: 240 });
+  cleanString(actor.kind, "payload.actor.kind", { required: true, max: 80 });
+
+  channelPayloadEventType(payload);
+  validateChannelAttachmentRefs(payload);
+}
+
+function validateChannelPayloadContent(payload: Record<string, unknown>, allowActivity: boolean): void {
+  const hasMessage = isRecord(payload.message);
+  const hasAttachments = Array.isArray(payload.attachments);
+  const hasReaction = isRecord(payload.reaction);
+  const hasInteraction = isRecord(payload.interaction);
+  const hasActivity = isRecord(payload.activity);
+  if (!hasMessage && !hasAttachments && !hasReaction && !hasInteraction && !hasActivity) {
+    throw new ValidationError("channel payload must include message, attachments, reaction, interaction, or activity");
+  }
+  if (!allowActivity && hasActivity) throw new ValidationError("channel activity must use /api/channels/:id/activities");
+}
+
+function validateChannelAttachmentItem(item: unknown, field: string): void {
+  if (!isRecord(item)) throw new ValidationError(`${field} must be an object`);
+  const artifactId = cleanString(item.artifactId, `${field}.artifactId`, { max: 120 });
+  if (artifactId) {
+    optionalEnum(item.kind, `${field}.kind`, VALID_ARTIFACT_KINDS);
+    optionalEnum(item.role, `${field}.role`, VALID_ARTIFACT_ROLES);
+    cleanString(item.title, `${field}.title`, { max: 240 });
+    if (item.ref !== undefined) validateChannelAttachmentSourceRef(item.ref, `${field}.ref`);
+    return;
+  }
+  validateChannelAttachmentSourceRef(item.ref, `${field}.ref`);
+}
+
+function validateChannelAttachmentRefs(payload: Record<string, unknown>): void {
+  if (payload.attachments === undefined) return;
+  if (!Array.isArray(payload.attachments)) throw new ValidationError("payload.attachments must be an array");
+  for (const [index, item] of payload.attachments.entries()) {
+    validateChannelAttachmentItem(item, `payload.attachments[${index}]`);
+  }
+}
+
+function cleanChannelAttachmentRefs(value: unknown, field = "attachments"): Array<Record<string, unknown>> | 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) => {
+    validateChannelAttachmentItem(item, `${field}[${index}]`);
+    return { ...(item as Record<string, unknown>) };
+  });
+}
+
+function normalizeChannelEventBody(body: unknown): {
+  body: string;
+  payload: Record<string, unknown>;
+  conversationId?: string;
+  idempotencyKey?: string;
+} {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const embeddedPayload = cleanMeta(body.payload);
+  const topLevelAttachmentInput = embeddedPayload || body.artifacts !== undefined ? body.attachments ?? body.artifacts : undefined;
+  const topLevelAttachments = cleanChannelAttachmentRefs(topLevelAttachmentInput, "attachments");
+  const payload = withPayloadAttachments(embeddedPayload ?? body, topLevelAttachments);
+  const fallbackBody = cleanString(body.body, "body", { max: MAX_BODY_BYTES });
+  const text = isRecord(payload.message) ? cleanString(payload.message.text, "payload.message.text", { max: MAX_BODY_BYTES }) : undefined;
+  const conversationId = cleanString(body.conversationId, "conversationId", { max: 300 }) ?? payloadConversationId(payload);
+  return {
+    body: fallbackBody ?? text ?? "Channel event",
+    payload,
+    conversationId,
+    idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }) ?? payloadDedupeKey(payload),
+  };
+}
+
+function requireChannelSession(req: Request, body: unknown, channel: ChannelSummary): Response | undefined {
+  const guard = normalizeAgentSessionGuard(req, body);
+  if (!guard || (!guard.instanceId && guard.epoch === undefined)) return error("channel session guard required", 400);
+  const session = validateAgentSession(channel.agentId, guard);
+  if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
+  return undefined;
+}
+
+function normalizeIntegrationEvent(body: unknown): IntegrationEventInput {
+  if (!isRecord(body)) throw new ValidationError("JSON object body required");
+  const status = optionalEnum(body.status, "status", [...VALID_TASK_STATUSES, "resolved"] as const);
+  return {
+    source: cleanString(body.source, "source", { max: 120 }),
+    type: cleanString(body.type, "type", { max: 80 }) ?? "event",
+    severity: optionalEnum(body.severity, "severity", VALID_TASK_SEVERITIES, "info"),
+    status,
+    title: cleanString(body.title, "title", { required: true, max: 240 })!,
+    body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+    target: cleanString(body.target, "target", { required: true, max: 200 })!,
+    channel: cleanString(body.channel, "channel", { max: 120 }),
+    dedupeKey: cleanString(body.dedupeKey, "dedupeKey", { max: 240 }),
+    externalUrl: cleanString(body.externalUrl, "externalUrl", { max: 1000 }),
+    attachments: cleanAttachmentRefs(body.attachments),
+    metadata: cleanMeta(body.metadata),
+  };
+}
+
+function normalizeIntegrationRegistryInput(name: string, body: unknown): {
+  name: string;
+  displayName?: string;
+  description?: string;
+  enabled?: boolean;
+  scopes?: string[];
+  targets?: string[];
+  channels?: string[];
+  type?: string;
+  icon?: string;
+  accentColor?: string;
+  tags?: string[];
+  homepageUrl?: string;
+  repositoryUrl?: string;
+  docsUrl?: string;
+  manifest?: Record<string, unknown>;
+  source: "api";
+} {
+  if (!isRecord(body)) throw new ValidationError("body must be an object");
+  if (body.enabled !== undefined && typeof body.enabled !== "boolean") throw new ValidationError("enabled must be a boolean");
+  return {
+    name,
+    displayName: cleanString(body.displayName, "displayName", { max: 120 }),
+    description: cleanString(body.description, "description", { max: 1000 }),
+    enabled: body.enabled as boolean | undefined,
+    scopes: cleanStringArray(body.scopes, "scopes", { itemMax: 80, maxItems: 50 }),
+    targets: cleanStringArray(body.targets, "targets", { itemMax: 80, maxItems: 50 }),
+    channels: cleanStringArray(body.channels, "channels", { itemMax: 80, maxItems: 50 }),
+    type: cleanString(body.type, "type", { max: 80 }),
+    icon: cleanString(body.icon, "icon", { max: 80 }),
+    accentColor: cleanString(body.accentColor, "accentColor", { max: 32 }),
+    tags: cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 }),
+    homepageUrl: cleanString(body.homepageUrl, "homepageUrl", { max: 500 }),
+    repositoryUrl: cleanString(body.repositoryUrl, "repositoryUrl", { max: 500 }),
+    docsUrl: cleanString(body.docsUrl, "docsUrl", { max: 500 }),
+    manifest: cleanMeta(body.manifest),
+    source: "api",
+  };
+}
+
+function channelIdFromIntegrationTarget(target: string): string | undefined {
+  if (!target.startsWith("channel:")) return undefined;
+  const channelId = target.slice("channel:".length).trim();
+  if (!channelId) throw new ValidationError("channel target id required");
+  return channelId;
+}
+
+function metadataWithResolvedChannelTarget(
+  metadata: Record<string, unknown> | undefined,
+  originalTarget: string,
+  channelId: string,
+  binding: ChannelBinding,
+): Record<string, unknown> {
+  return {
+    ...(metadata ?? {}),
+    relayRequestedTarget: originalTarget,
+    relayResolvedChannelId: channelId,
+    relayResolvedChannelBindingId: binding.id,
+  };
+}
+
+function resolveIntegrationEventTarget(input: IntegrationEventInput): IntegrationEventInput {
+  const channelId = channelIdFromIntegrationTarget(input.target);
+  if (!channelId) return input;
+
+  evaluatePoolBindings();
+  const channel = getChannel(channelId);
+  if (!channel) throw new ValidationError(`channel ${channelId} not found`);
+
+  const bindings = resolveChannelRoutes(channelId);
+  if (bindings.length === 0) throw new ValidationError(`channel ${channelId} has no binding`);
+  if (bindings.length > 1) throw new ValidationError(`channel ${channelId} has multiple bindings; integration channel targets must resolve to one backend agent`);
+
+  const binding = bindings[0]!;
+  const resolvedTarget = messageTargetForChannelTarget(binding.target, binding);
+  if (!resolvedTarget.startsWith("policy:") && !getAgent(resolvedTarget)) {
+    throw new ValidationError(`channel ${channelId} binding resolves to ${resolvedTarget}; integration channel targets must resolve to one backend agent`);
+  }
+
+  return {
+    ...input,
+    target: resolvedTarget,
+    channel: input.channel ?? channelId,
+    metadata: metadataWithResolvedChannelTarget(input.metadata, input.target, channelId, binding),
+  };
+}
+
+function checkIntegrationRateLimit(name: string): boolean {
+  const now = Date.now();
+  const windowMs = 60_000;
+  const bucket = integrationRateBuckets.get(name);
+  if (!bucket || now - bucket.windowStart >= windowMs) {
+    integrationRateBuckets.set(name, { windowStart: now, count: 1 });
+    return true;
+  }
+  bucket.count += 1;
+  return bucket.count <= INTEGRATION_RATE_LIMIT_PER_MINUTE;
+}
+
+function safeCallbackHost(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  try {
+    return new URL(url).host;
+  } catch {
+    return undefined;
+  }
+}
+
+function reconcileIntegrationRegistry(configured: Map<string, IntegrationTokenConfig>, observedStats: Map<string, ReturnType<typeof listIntegrationTaskStats>[number]>): Map<string, ReturnType<typeof listIntegrationRegistry>[number]> {
+  for (const config of configured.values()) {
+    upsertIntegrationRegistry({
+      name: config.name,
+      displayName: config.displayName,
+      description: config.description,
+      scopes: config.scopes,
+      targets: config.targets,
+      channels: config.channels,
+      type: config.type,
+      icon: config.icon,
+      accentColor: config.accentColor,
+      tags: config.tags,
+      homepageUrl: config.homepageUrl,
+      repositoryUrl: config.repositoryUrl,
+      docsUrl: config.docsUrl,
+      manifest: config.manifest,
+      source: "env",
+    });
+  }
+  for (const stats of observedStats.values()) {
+    upsertIntegrationRegistry({
+      name: stats.source,
+      enabled: true,
+      source: "observed",
+    });
+  }
+  return new Map(listIntegrationRegistry().map((integration) => [integration.name, integration]));
+}
+
+export const getIntegrations: Handler = () => {
+  const configured = new Map(getIntegrationTokens().map((integration) => [integration.name, integration]));
+  const observedStats = new Map(listIntegrationTaskStats().map((stats) => [stats.source, stats]));
+  const registry = reconcileIntegrationRegistry(configured, observedStats);
+  const names = [...new Set([...configured.keys(), ...observedStats.keys(), ...registry.keys()])].sort((a, b) => a.localeCompare(b));
+  const now = Date.now();
+
+  const integrations: IntegrationSummary[] = names.map((name) => {
+    const config = configured.get(name);
+    const registered = registry.get(name);
+    const taskStats = observedStats.get(name) ?? {
+      source: name,
+      tasks: 0,
+      openTasks: 0,
+      waitingTasks: 0,
+      failedTasks: 0,
+    };
+    const bucket = integrationRateBuckets.get(name);
+    const bucketCurrent = Boolean(bucket && now - bucket.windowStart < 60_000);
+
+    return {
+      name,
+      displayName: registered?.displayName,
+      description: registered?.description,
+      enabled: registered?.enabled ?? true,
+      configured: Boolean(config),
+      observed: observedStats.has(name),
+      type: registered?.type,
+      icon: registered?.icon,
+      accentColor: registered?.accentColor,
+      tags: registered?.tags ?? [],
+      homepageUrl: registered?.homepageUrl,
+      repositoryUrl: registered?.repositoryUrl,
+      docsUrl: registered?.docsUrl,
+      manifest: registered?.manifest,
+      scopes: registered?.scopes?.length ? registered.scopes : config?.scopes ?? [],
+      targets: registered?.targets?.length ? registered.targets : config?.targets ?? [],
+      channels: registered?.channels?.length ? registered.channels : config?.channels ?? [],
+      callbackHost: safeCallbackHost(config?.callbackUrl),
+      callbackConfigured: Boolean(config?.callbackUrl),
+      rateLimit: {
+        limitPerMinute: INTEGRATION_RATE_LIMIT_PER_MINUTE,
+        currentWindowCount: bucketCurrent ? bucket!.count : 0,
+        windowStartedAt: bucketCurrent ? bucket!.windowStart : undefined,
+      },
+      taskStats,
+    };
+  });
+
+  return json(integrations);
+};
+
+export const putIntegrationRegistryRoute: Handler = async (req, params) => {
+  const name = cleanString(params.name, "name", { required: true, max: 200 })!;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(upsertIntegrationRegistry(normalizeIntegrationRegistryInput(name, parsed.body)));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getChannels: Handler = () => {
+  return json(listChannels());
+};
+
+export const getChannelBindings: Handler = (req) => {
+  const url = new URL(req.url);
+  const channelId = cleanString(url.searchParams.get("channelId") ?? undefined, "channelId", { max: 200 });
+  return json(listChannelBindings(channelId));
+};
+
+export const postChannelBinding: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = normalizeChannelBindingInput(parsed.body);
+    const channel = getChannel(input.channelId);
+    if (!channel) return error("channel not found", 404);
+    const sessionError = requireChannelSession(req, parsed.body, channel);
+    if (sessionError) return sessionError;
+    const binding = upsertChannelBinding(input);
+    return json(binding, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function scopedChannelIdempotencyKey(key: string | undefined, binding: ChannelBinding): string | undefined {
+  return key ? `${key}:${binding.id}` : undefined;
+}
+
+function applyInboundChannelReaction(payload: Record<string, unknown>): void {
+  const eventType = channelPayloadEventType(payload);
+  if (eventType !== "message.reaction") return;
+  const reaction = isRecord(payload.reaction) ? payload.reaction : undefined;
+  if (!reaction) return;
+  const target = isRecord(reaction.target) ? reaction.target : undefined;
+  const relayMessageId = target && typeof target.relayMessageId === "number" && Number.isSafeInteger(target.relayMessageId)
+    ? target.relayMessageId
+    : undefined;
+  const source = target && isRecord(target.source) ? target.source : undefined;
+  const telegram = source && isRecord(source.telegram) ? source.telegram : undefined;
+  if (!telegram && relayMessageId === undefined) return;
+
+  let parent = relayMessageId !== undefined ? getMessage(relayMessageId) : null;
+  if (!parent && telegram) {
+    const chatId = cleanString(telegram.chatId, "payload.reaction.target.source.telegram.chatId", { max: 120 });
+    const messageId = cleanString(telegram.messageId, "payload.reaction.target.source.telegram.messageId", { max: 120 });
+    if (!chatId || !messageId) return;
+    const channel = isRecord(payload.channel) ? payload.channel : undefined;
+    const accountId = channel ? cleanString(channel.accountId, "payload.channel.accountId", { max: 200 }) : undefined;
+    parent = findMessageByTelegramSource({ accountId, chatId, messageId });
+  }
+  if (!parent) return;
+
+  const actor = isRecord(payload.actor) ? payload.actor : {};
+  const actorId = cleanString(actor.id, "payload.actor.id", { max: 240 }) ?? "telegram";
+  const emoji = reactionEmoji(reaction.emoji ?? reaction.value ?? reaction.name, "payload.reaction.emoji");
+  const action = cleanString(reaction.action, "payload.reaction.action", { max: 20 }) === "remove" ? "remove" : "add";
+  const result = setMessageReaction({ messageId: parent.id, actorId, emoji, action });
+  if (result.ok) {
+    emitMessageReactionUpdated(result.message);
+    sendReactionNotificationToAuthor(result.message, actorId, emoji, action);
+  }
+}
+
+export const postChannelEvent: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const channel = getChannel(params.id!);
+    if (!channel) return error("channel not found", 404);
+    const sessionError = requireChannelSession(req, parsed.body, channel);
+    if (sessionError) return sessionError;
+    const denied = authorizeRoute(req, { scope: "channel:write", resource: { channel: channel.id } });
+    if (denied) return denied;
+    const input = normalizeChannelEventBody(parsed.body);
+    validateChannelEnvelope(input.payload, channel);
+    validateChannelPayloadContent(input.payload, false);
+    const eventType = channelPayloadEventType(input.payload);
+    if (EPHEMERAL_CHANNEL_EVENT_TYPES.has(eventType)) {
+      return error("ephemeral channel activity must use /api/channels/:id/activities", 400);
+    }
+    applyInboundChannelReaction(input.payload);
+    const bindings = resolveChannelRoutes(channel.id, input.conversationId);
+    if (!bindings.length) return error("channel has no binding", 409);
+    const results = bindings.map((binding) => sendMessageWithResult({
+      from: channel.agentId,
+      to: messageTargetForChannelTarget(binding.target, binding),
+      kind: "channel.event",
+      channel: channel.id,
+      body: input.body,
+      payload: input.payload,
+      idempotencyKey: scopedChannelIdempotencyKey(input.idempotencyKey, binding),
+      claimable: false,
+    }));
+    for (const result of results) {
+      if (!result.created) continue;
+      if (result.message.deliveryStatus === "queued") emitMessageQueued(result.message);
+      else emitNewMessage(result.message);
+    }
+    return json({
+      messages: results.map((result) => result.message),
+      bindings,
+      created: results.some((result) => result.created),
+    }, results.some((result) => result.created) ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postChannelActivity: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const channel = getChannel(params.id!);
+    if (!channel) return error("channel not found", 404);
+    const sessionError = requireChannelSession(req, parsed.body, channel);
+    if (sessionError) return sessionError;
+    const input = normalizeChannelEventBody(parsed.body);
+    validateChannelEnvelope(input.payload, channel);
+    validateChannelPayloadContent(input.payload, true);
+    const eventType = channelPayloadEventType(input.payload);
+    if (!EPHEMERAL_CHANNEL_EVENT_TYPES.has(eventType) && !input.payload.activity) {
+      return error("channel activity payload must include an ephemeral event type or activity object", 400);
+    }
+    const activity = {
+      channelId: channel.id,
+      conversationId: input.conversationId,
+      payload: input.payload,
+      createdAt: Date.now(),
+    };
+    emitChannelActivity(activity);
+    return json({ ok: true, activity }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postIntegrationEvent: Handler = async (req) => {
+  const auth = getIntegrationAuth(req);
+  const component = getComponentAuth(req);
+  const componentIntegration = component?.role === "integration" ? component : null;
+  const integrationName = auth?.name ?? componentIntegration?.sub;
+  if (!integrationName) return error("integration token required", 401);
+  if (!isIntegrationRegistryEnabled(integrationName)) return error("integration disabled", 403);
+  if (!checkIntegrationRateLimit(integrationName)) return error("integration rate limit exceeded", 429);
+  if (auth && !hasIntegrationScope(auth, "tasks:create") && !hasIntegrationScope(auth, "events:create")) {
+    return error("integration token missing tasks:create scope", 403);
+  }
+
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const normalized = { ...normalizeIntegrationEvent(parsed.body), source: integrationName };
+    const requestedChannelId = channelIdFromIntegrationTarget(normalized.target);
+    const integrationScope = auth && !hasIntegrationScope(auth, "events:create") ? "task:write" : "integration:write";
+    if (!isRequestAuthorizedFor(req, { scope: integrationScope, resource: { integrationName, target: normalized.target, channel: normalized.channel ?? requestedChannelId } })) {
+      return error("integration token cannot target this task", 403);
+    }
+    const input = resolveIntegrationEventTarget(normalized);
+    const result = ingestIntegrationEvent(input, integrationName);
+    if (result.message) emitNewMessage(result.message);
+    emitTaskChanged(result.task, result.created ? "task.created" : "task.updated");
+    void dispatchTaskCallbacks(result.task.id, result.created ? "task.created" : "task.updated");
+    return json(result, result.created ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};