agent-relay-server 0.5.0 → 0.6.0

package/src/index.ts

@@ -117,12 +117,36 @@ export function createFetchHandler(
       return Response.json({ error: "not found" }, { status: 404 });
     }
     const file = Bun.file(resolved);
-    if (await file.exists()) return new Response(file);
+    if (await file.exists()) {
+      const headers = staticHeaders(requested);
+      return new Response(file, { headers });
+    }
 
     return Response.json({ error: "not found" }, { status: 404 });
   };
 }
 
+function staticHeaders(pathname: string): Headers {
+  const headers = new Headers();
+  const contentType = staticContentType(pathname);
+  if (contentType) headers.set("Content-Type", contentType);
+  if (pathname === "/sw.js") {
+    headers.set("Cache-Control", "no-cache");
+  } else if (pathname === "/manifest.webmanifest") {
+    headers.set("Cache-Control", "no-cache");
+  }
+  return headers;
+}
+
+function staticContentType(pathname: string): string | undefined {
+  if (pathname.endsWith(".webmanifest")) return "application/manifest+json; charset=utf-8";
+  if (pathname.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (pathname.endsWith(".html")) return "text/html; charset=utf-8";
+  if (pathname.endsWith(".svg")) return "image/svg+xml";
+  if (pathname.endsWith(".png")) return "image/png";
+  return undefined;
+}
+
 if (import.meta.main) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/src/routes.ts

@@ -42,6 +42,11 @@ import {
   setInboxDraft,
   deleteInboxDraft,
   listActivityEvents,
+  listChannels,
+  listChannelBindings,
+  getChannel,
+  resolveChannelRoutes,
+  upsertChannelBinding,
   createActivityEvent,
   createCallbackDelivery,
   finishCallbackDelivery,
@@ -57,7 +62,15 @@ import {
   deleteOrchestrator,
   ValidationError,
 } from "./db";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
+import {
+  getConnector,
+  listConnectors,
+  readConnectorConfig,
+  registerConnectorManifest,
+  runConnectorAction,
+  writeConnectorConfig,
+} from "./connectors";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentSessionGuard, ChannelBinding, ChannelBindingMode, ChannelDirection, ChannelRouteTarget, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnProvider, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
 import { listHostDirectories, spawnCodexAgent, type CodexSpawnApprovalMode } from "./agent-spawn";
 import {
@@ -74,6 +87,7 @@ import {
   emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
+  emitChannelActivity,
   emitOrchestratorStatus,
   emitOrchestratorRemoved,
 } from "./sse";
@@ -160,9 +174,13 @@ function parseQueryInt(
 }
 
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "offline"] as const;
+const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
+const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator"] as const;
+const VALID_CHANNEL_BINDING_MODES = ["exclusive", "claimable", "broadcast"] as const;
 const VALID_AGENT_ACTIONS = ["restart", "shutdown"] as const;
 const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
 const VALID_CODEX_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
+const VALID_CONNECTOR_ACTIONS = ["install", "uninstall", "enable", "disable", "start", "stop", "restart", "status", "doctor"] as const;
 const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
 const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "done", "failed", "canceled"] as const;
 const VALID_PAIR_STATUSES = ["pending", "active", "ended", "rejected", "expired"] as const;
@@ -282,6 +300,7 @@ function normalizeAgentInput(body: unknown): RegisterAgentInput {
   const input: RegisterAgentInput = {
     id: cleanString(body.id, "id", { required: true, max: 200 })!,
     name: cleanString(body.name, "name", { required: true, max: 200 })!,
+    kind: cleanEnum(body.kind, "kind", VALID_AGENT_KINDS) as AgentKind | undefined,
     status: status as RegisterAgentInput["status"] | undefined,
     ready: body.ready as boolean | undefined,
   };
@@ -306,9 +325,9 @@ function normalizeAgentInput(body: unknown): RegisterAgentInput {
 
 function normalizeMessageInput(body: unknown): SendMessageInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
-  const type = cleanString(body.type, "type", { max: 20 });
-  if (type && !VALID_MSG_TYPES.includes(type)) {
-    throw new ValidationError(`type must be one of: ${VALID_MSG_TYPES.join(", ")}`);
+  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");
@@ -318,7 +337,7 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     from: cleanString(body.from, "from", { required: true, max: 200 })!,
     to: cleanString(body.to, "to", { required: true, max: 200 })!,
     body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
-    type: type as SendMessageInput["type"] | undefined,
+    kind: kind as SendMessageInput["kind"] | undefined,
     replyTo: cleanPositiveId(body.replyTo, "replyTo"),
     claimable: body.claimable as boolean | undefined,
     idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }),
@@ -330,10 +349,168 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
   if (subject) input.subject = subject;
   const meta = cleanMeta(body.meta);
   if (meta) input.meta = meta;
+  const payload = cleanMeta(body.payload);
+  if (payload) input.payload = payload;
 
   return input;
 }
 
+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 = cleanEnum(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 = cleanEnum(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("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): string {
+  if (target.type === "orchestrator") throw new ValidationError("orchestrator channel targets are not supported yet");
+  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";
+  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 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()) {
+    if (!isRecord(item)) throw new ValidationError(`payload.attachments[${index}] must be an object`);
+    const ref = item.ref;
+    if (!isRecord(ref)) throw new ValidationError(`payload.attachments[${index}].ref must be an object`);
+    const type = cleanString(ref.type, `payload.attachments[${index}].ref.type`, { required: true, max: 40 });
+    if (type !== "relay-blob" && type !== "external-url" && type !== "channel-file") {
+      throw new ValidationError(`payload.attachments[${index}].ref.type must be relay-blob, external-url, or channel-file`);
+    }
+    if (type === "external-url") cleanString(ref.url, `payload.attachments[${index}].ref.url`, { required: true, max: 2048 });
+    if (type === "relay-blob" || type === "channel-file") cleanString(ref.id, `payload.attachments[${index}].ref.id`, { required: true, max: 400 });
+  }
+}
+
+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 payload = cleanMeta(body.payload) ?? body;
+  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 = cleanEnum(body.status, "status", [...VALID_TASK_STATUSES, "resolved"] as const);
@@ -521,7 +698,8 @@ function metaDirection(meta: Record<string, unknown> | undefined): ChannelDirect
 
 function isChannelAgent(agent: AgentCard): boolean {
   const kind = metaString(agent.meta, "kind");
-  return kind === "channel" ||
+  return agent.kind === "channel" ||
+    kind === "channel" ||
     kind === "communication-channel" ||
     agent.tags.includes("channel") ||
     agent.capabilities.includes("channel");
@@ -531,6 +709,7 @@ function agentToChannel(agent: AgentCard): ChannelSummary {
   const type = metaString(agent.meta, "channelType") ?? metaString(agent.meta, "type") ?? agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ?? "custom";
   const transport = metaString(agent.meta, "transport") ?? type;
   const topicChannels = metaStringArray(agent.meta, "topicChannels");
+  const accountId = metaString(agent.meta, "accountId") ?? (agent.id.startsWith(`${type}:`) ? agent.id.slice(type.length + 1) : agent.id);
 
   return {
     id: metaString(agent.meta, "channelId") ?? agent.id,
@@ -538,6 +717,7 @@ function agentToChannel(agent: AgentCard): ChannelSummary {
     type,
     transport,
     agentId: agent.id,
+    accountId,
     status: agent.status,
     ready: agent.ready,
     direction: metaDirection(agent.meta),
@@ -773,17 +953,19 @@ const postAgentAction: Handler = async (req, params) => {
     const msg = sendMessage({
       from: "system",
       to: agent.id,
-      type: "system",
+      kind: "control",
       subject: title,
       body: action === "restart"
         ? "Dashboard requested that this agent restart its relay-managed session now."
         : "Dashboard requested that this agent shut down its relay-managed session now.",
-      meta: {
+      payload: {
         agentControl: {
           action,
           requestedBy: "dashboard",
           requestedAt: Date.now(),
         },
+      },
+      meta: {
         delivery: "interrupt",
         priority: "urgent",
       },
@@ -829,11 +1011,11 @@ const postAgentSpawn: Handler = async (req) => {
       const msg = sendMessage({
         from: "system",
         to: orch.agentId,
-        type: "system",
+        kind: "control",
         subject: "Spawn agent",
-        body: JSON.stringify({ action: "spawn", provider, cwd, label, approvalMode }),
+        body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
+        payload: { orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() } },
         meta: {
-          orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() },
           delivery: "interrupt",
           priority: "urgent",
         },
@@ -969,7 +1151,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
     const cleaned: ManagedAgent[] = agents.map((a: any) => {
       if (!isRecord(a)) throw new ValidationError("each agent must be an object");
       return {
-        agentId: cleanString(a.agentId, "agentId", { required: true, max: 240 })!,
+        agentId: cleanString(a.agentId, "agentId", { max: 240 }) || "",
         provider: cleanEnum(a.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider,
         tmuxSession: cleanString(a.tmuxSession, "tmuxSession", { required: true, max: 240 })!,
         cwd: cleanString(a.cwd, "cwd", { required: true, max: 500 })!,
@@ -980,6 +1162,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
       };
     });
     const updated = updateManagedAgents(params.id!, cleaned);
+    if (updated) emitOrchestratorStatus(params.id!);
     return json(updated);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -1012,10 +1195,10 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
     const msg = sendMessage({
       from: "system",
       to: orch.agentId,
-      type: "system",
+      kind: "control",
       subject: "Spawn agent",
-      body: JSON.stringify({ action: "spawn", provider, cwd: cwd || orch.baseDir, label, approvalMode, prompt }),
-      meta: {
+      body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
+      payload: {
         orchestratorControl: {
           action: "spawn",
           provider,
@@ -1026,6 +1209,8 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
           requestedBy: "dashboard",
           requestedAt: Date.now(),
         },
+      },
+      meta: {
         delivery: "interrupt",
         priority: "urgent",
       },
@@ -1063,16 +1248,18 @@ const postOrchestratorAction: Handler = async (req, params) => {
     const msg = sendMessage({
       from: "system",
       to: orch.agentId,
-      type: "system",
+      kind: "control",
       subject: action === "restart" ? "Restart agent" : "Shutdown agent",
-      body: JSON.stringify({ action, agentId }),
-      meta: {
+      body: agentId ? `${action} ${agentId}` : `${action} all managed agents`,
+      payload: {
         orchestratorControl: {
           action,
           agentId,
           requestedBy: "dashboard",
           requestedAt: Date.now(),
         },
+      },
+      meta: {
         delivery: "interrupt",
         priority: "urgent",
       },
@@ -1103,7 +1290,7 @@ const deleteOrchestratorById: Handler = (_req, params) => {
 
 // --- Message routes ---
 
-const VALID_MSG_TYPES = ["message", "system"];
+const VALID_MSG_KINDS = ["chat", "channel.event", "task", "pair", "control", "system"];
 
 const postMessage: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
@@ -1116,13 +1303,14 @@ const postMessage: Handler = async (req) => {
     const result = sendMessageWithResult(input);
     if (result.created) {
       emitNewMessage(result.message);
+      const isWork = result.message.kind === "task";
       auditEvent({
         clientId: "server-message-" + result.message.id,
-        kind: result.message.claimable ? "task" : "message",
-        title: result.message.claimable ? "Claimable message sent" : "Message sent",
+        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: result.message.claimable ? "ti-hand-grab" : "ti-send",
+        icon: isWork ? "ti-hand-grab" : "ti-send",
         view: "messages",
         messageId: result.message.id,
         agentId: result.message.from,
@@ -1144,7 +1332,7 @@ const postSystemBroadcast: Handler = async (req) => {
     const msg = sendMessage({
       from: "system",
       to: "broadcast",
-      type: "system",
+      kind: "system",
       subject: body.subject ?? undefined,
       body: body.body,
     });
@@ -1373,6 +1561,67 @@ const postActivityEvent: Handler = async (req) => {
   }
 };
 
+// --- Connectors ---
+
+const getConnectors: Handler = () => json(listConnectors());
+
+const getConnectorById: Handler = (_req, params) => {
+  const connector = getConnector(params.id!);
+  return connector ? json(connector) : error("connector not found", 404);
+};
+
+const postConnectorRegister: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("JSON object body required");
+    const manifest = isRecord(parsed.body.manifest) ? parsed.body.manifest : parsed.body;
+    const config = isRecord(parsed.body.config) ? parsed.body.config : undefined;
+    const state = isRecord(parsed.body.state) ? parsed.body.state : undefined;
+    return json(registerConnectorManifest(manifest as any, { config, state }), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postConnectorAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("JSON object body required");
+    const action = cleanEnum(parsed.body.action, "action", VALID_CONNECTOR_ACTIONS)!;
+    const result = runConnectorAction(params.id!, action);
+    return json(result, result.ok ? 200 : 502);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, e.message.includes("not found") ? 404 : 400);
+    throw e;
+  }
+};
+
+const getConnectorConfig: Handler = (_req, params) => {
+  try {
+    if (!getConnector(params.id!)) return error("connector not found", 404);
+    return json(readConnectorConfig(params.id!));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const putConnectorConfig: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!getConnector(params.id!)) return error("connector not found", 404);
+    if (!isRecord(parsed.body)) throw new ValidationError("connector config must be an object");
+    return json(writeConnectorConfig(params.id!, parsed.body));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- Tasks and integrations ---
 
 const getIntegrations: Handler = () => {
@@ -1415,16 +1664,104 @@ const getIntegrations: Handler = () => {
 };
 
 const getChannels: Handler = () => {
-  const channels = listAgents()
-    .filter(isChannelAgent)
-    .map(agentToChannel)
-    .sort((a, b) => {
-      const readyDiff = Number(b.ready) - Number(a.ready);
-      if (readyDiff !== 0) return readyDiff;
-      return a.name.localeCompare(b.name);
-    });
+  return json(listChannels());
+};
+
+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));
+};
+
+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;
+}
 
-  return json(channels);
+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 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);
+    }
+    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),
+      kind: "channel.event",
+      channel: channel.id,
+      body: input.body,
+      payload: input.payload,
+      idempotencyKey: scopedChannelIdempotencyKey(input.idempotencyKey, binding),
+      claimable: binding.mode === "claimable",
+    }));
+    for (const result of results) {
+      if (result.created) 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;
+  }
+};
+
+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;
+  }
 };
 
 const postIntegrationEvent: Handler = async (req) => {
@@ -1819,7 +2156,18 @@ const routes: Route[] = [
   route("GET", "/api/activity", getActivityEvents),
   route("POST", "/api/activity", postActivityEvent),
 
+  route("GET", "/api/connectors", getConnectors),
+  route("POST", "/api/connectors", postConnectorRegister),
+  route("GET", "/api/connectors/:id", getConnectorById),
+  route("POST", "/api/connectors/:id/actions", postConnectorAction),
+  route("GET", "/api/connectors/:id/config", getConnectorConfig),
+  route("PUT", "/api/connectors/:id/config", putConnectorConfig),
+
   route("GET", "/api/channels", getChannels),
+  route("POST", "/api/channels/:id/events", postChannelEvent),
+  route("POST", "/api/channels/:id/activities", postChannelActivity),
+  route("GET", "/api/channel-bindings", getChannelBindings),
+  route("POST", "/api/channel-bindings", postChannelBinding),
   route("GET", "/api/integrations", getIntegrations),
   route("POST", "/api/integrations/events", postIntegrationEvent),
   route("GET", "/api/tasks", getTasks),

package/src/security.ts

@@ -95,7 +95,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/stats") return "stats:read";
   if (pathname === "/api/health") return "health:read";
   if (pathname === "/api/events") return "events:read";
-  if (pathname === "/api/channels") return "channels:read";
+  if (pathname === "/api/connectors" || pathname.startsWith("/api/connectors/")) return method === "GET" ? "connectors:read" : "system:write";
+  if (pathname.startsWith("/api/channels") || pathname.startsWith("/api/channel-bindings")) return method === "GET" ? "channels:read" : "channels:write";
   if (pathname === "/api/integrations" || pathname.startsWith("/api/integrations/")) return method === "GET" ? "integrations:read" : "integrations:write";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agents:read" : "agents:write";
   if (pathname.startsWith("/api/activity")) return method === "GET" ? "activity:read" : "activity:write";

package/src/sse.ts

@@ -122,6 +122,12 @@ export function emitTaskChanged(task: Task, eventType = "task.updated") {
   }
 }
 
+export function emitChannelActivity(activity: Record<string, unknown>) {
+  for (const conn of connections.values()) {
+    send(conn, "channel.activity", activity);
+  }
+}
+
 export function getConnectionCount(): number {
   return connections.size;
 }