agent-relay-server 0.4.39 → 0.6.0

package/src/routes.ts

@@ -42,15 +42,35 @@ import {
   setInboxDraft,
   deleteInboxDraft,
   listActivityEvents,
+  listChannels,
+  listChannelBindings,
+  getChannel,
+  resolveChannelRoutes,
+  upsertChannelBinding,
   createActivityEvent,
   createCallbackDelivery,
   finishCallbackDelivery,
   reapStaleAgents,
+  reapStaleOrchestrators,
   releaseExpiredClaims,
   validateAgentSession,
+  upsertOrchestrator,
+  getOrchestrator,
+  listOrchestrators,
+  orchestratorHeartbeat,
+  updateManagedAgents,
+  deleteOrchestrator,
   ValidationError,
 } from "./db";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, 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 {
@@ -67,6 +87,9 @@ import {
   emitMessageClaimReleased,
   emitMessageDeleted,
   emitTaskChanged,
+  emitChannelActivity,
+  emitOrchestratorStatus,
+  emitOrchestratorRemoved,
 } from "./sse";
 
 type Handler = (
@@ -151,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;
@@ -273,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,
   };
@@ -297,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");
@@ -309,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 }),
@@ -321,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);
@@ -512,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");
@@ -522,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,
@@ -529,6 +717,7 @@ function agentToChannel(agent: AgentCard): ChannelSummary {
     type,
     transport,
     agentId: agent.id,
+    accountId,
     status: agent.status,
     ready: agent.ready,
     direction: metaDirection(agent.meta),
@@ -764,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",
       },
@@ -804,11 +995,47 @@ const postAgentSpawn: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_AGENT_SPAWN_PROVIDERS);
-    if (provider !== "codex") return error("provider must be codex");
+    const provider = cleanEnum(parsed.body.provider, "provider", [...VALID_AGENT_SPAWN_PROVIDERS, "claude"] as const);
+    if (!provider) return error("provider required");
     const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as CodexSpawnApprovalMode;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
     const label = cleanString(parsed.body.label, "label", { max: 120 });
+
+    // Check for an online orchestrator that supports this provider
+    const orchestrators = listOrchestrators().filter(
+      (o) => o.status === "online" && o.providers.includes(provider as SpawnProvider),
+    );
+    if (orchestrators.length > 0) {
+      // Route through the first available orchestrator
+      const orch = orchestrators[0]!;
+      const msg = sendMessage({
+        from: "system",
+        to: orch.agentId,
+        kind: "control",
+        subject: "Spawn agent",
+        body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
+        payload: { orchestratorControl: { action: "spawn", provider, cwd, label, approvalMode, requestedBy: "dashboard", requestedAt: Date.now() } },
+        meta: {
+          delivery: "interrupt",
+          priority: "urgent",
+        },
+      });
+      emitNewMessage(msg);
+      auditEvent({
+        clientId: "server-agent-spawn-" + provider + "-" + Date.now(),
+        kind: "state",
+        title: `${provider} agent spawn requested (via ${orch.id})`,
+        body: cwd || orch.baseDir,
+        meta: orch.id,
+        icon: "ti-plus",
+        view: "agents",
+        metadata: { provider, orchestratorId: orch.id, approvalMode },
+      });
+      return json({ ok: true, orchestratorId: orch.id, provider, message: msg }, 202);
+    }
+
+    // Fallback: direct spawn for codex only (no orchestrator)
+    if (provider !== "codex") return error("no orchestrator available for provider: " + provider);
     const relayUrl = process.env.AGENT_RELAY_SPAWN_RELAY_URL || process.env.AGENT_RELAY_URL || `http://127.0.0.1:${process.env.PORT || "4850"}`;
     const token = req.headers.get("X-Agent-Relay-Token") ?? req.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
     const result = spawnCodexAgent({
@@ -822,7 +1049,7 @@ const postAgentSpawn: Handler = async (req) => {
     auditEvent({
       clientId: "server-agent-spawn-codex-" + Date.now(),
       kind: "state",
-      title: "Codex agent spawn requested",
+      title: "Codex agent spawn requested (direct)",
       body: result.cwd,
       meta: result.pid ? `pid ${result.pid}` : "dry run",
       icon: "ti-plus",
@@ -855,9 +1082,215 @@ const getHostDirectories: Handler = (req) => {
   }
 };
 
+// --- Orchestrator routes ---
+
+const VALID_ORCHESTRATOR_PROVIDERS = ["claude", "codex"] as const;
+const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
+
+const postOrchestrator: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
+    const hostname = cleanString(parsed.body.hostname, "hostname", { required: true, max: 120 })!;
+    const baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
+    const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
+    if (providers) {
+      for (const p of providers) {
+        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
+          return error(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        }
+      }
+    }
+    const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys");
+    const meta = cleanMeta(parsed.body.meta);
+    const orch = upsertOrchestrator({ id, hostname, providers: providers ?? ["claude", "codex"], baseDir, envKeys, meta });
+    auditEvent({
+      clientId: "server-orchestrator-register-" + id + "-" + Date.now(),
+      kind: "state",
+      title: "Orchestrator registered",
+      body: hostname,
+      meta: id,
+      icon: "ti-server-2",
+      view: "orchestrators",
+      metadata: { orchestratorId: id, providers: orch.providers },
+    });
+    return json(orch, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const getOrchestrators: Handler = () => {
+  return json(listOrchestrators());
+};
+
+const getOrchestratorById: Handler = (_req, params) => {
+  const orch = getOrchestrator(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json(orch);
+};
+
+const postOrchestratorHeartbeat: Handler = (_req, params) => {
+  const orch = orchestratorHeartbeat(params.id!);
+  if (!orch) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
+const patchOrchestratorAgents: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (!isRecord(parsed.body)) return error("body required");
+    const agents = parsed.body.agents;
+    if (!Array.isArray(agents)) return error("agents must be an array");
+    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", { 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 })!,
+        label: cleanString(a.label, "label", { max: 120 }),
+        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") ?? "guarded") as SpawnApprovalMode,
+        pid: typeof a.pid === "number" && Number.isSafeInteger(a.pid) ? a.pid : undefined,
+        startedAt: typeof a.startedAt === "number" ? a.startedAt : Date.now(),
+      };
+    });
+    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);
+    throw e;
+  }
+};
+
+const postOrchestratorSpawn: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+    if (orch.status !== "online") return error("orchestrator is offline", 409);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    if (!orch.providers.includes(provider)) {
+      return error(`orchestrator does not support provider: ${provider}`);
+    }
+    const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
+    if (cwd && !cwd.startsWith(orch.baseDir)) {
+      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
+    }
+    const label = cleanString(parsed.body.label, "label", { max: 120 });
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const prompt = cleanString(parsed.body.prompt, "prompt", { max: 4000 });
+
+    // Send control message to orchestrator's agent inbox
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      kind: "control",
+      subject: "Spawn agent",
+      body: `Spawn ${provider} agent${label ? ` (${label})` : ""}`,
+      payload: {
+        orchestratorControl: {
+          action: "spawn",
+          provider,
+          cwd: cwd || orch.baseDir,
+          label,
+          approvalMode,
+          prompt,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+      },
+      meta: {
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-spawn-" + orch.id + "-" + Date.now(),
+      kind: "state",
+      title: `Spawn ${provider} agent requested`,
+      body: cwd || orch.baseDir,
+      meta: orch.id,
+      icon: "ti-plus",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, provider, approvalMode, label },
+    });
+    return json({ ok: true, orchestratorId: orch.id, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const postOrchestratorAction: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const orch = getOrchestrator(params.id!);
+    if (!orch) return error("orchestrator not found", 404);
+
+    if (!isRecord(parsed.body)) return error("body required");
+    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown"] as const);
+    if (!action) return error("action required");
+    const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
+
+    const msg = sendMessage({
+      from: "system",
+      to: orch.agentId,
+      kind: "control",
+      subject: action === "restart" ? "Restart agent" : "Shutdown agent",
+      body: agentId ? `${action} ${agentId}` : `${action} all managed agents`,
+      payload: {
+        orchestratorControl: {
+          action,
+          agentId,
+          requestedBy: "dashboard",
+          requestedAt: Date.now(),
+        },
+      },
+      meta: {
+        delivery: "interrupt",
+        priority: "urgent",
+      },
+    });
+    emitNewMessage(msg);
+    auditEvent({
+      clientId: "server-orchestrator-action-" + orch.id + "-" + action + "-" + Date.now(),
+      kind: "state",
+      title: `Agent ${action} requested`,
+      body: agentId || "all",
+      meta: orch.id,
+      icon: action === "restart" ? "ti-refresh" : "ti-power",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, action, agentId },
+    });
+    return json({ ok: true, action, message: msg }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+const deleteOrchestratorById: Handler = (_req, params) => {
+  const deleted = deleteOrchestrator(params.id!);
+  if (!deleted) return error("orchestrator not found", 404);
+  return json({ ok: true });
+};
+
 // --- 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);
@@ -870,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,
@@ -898,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,
     });
@@ -1127,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 = () => {
@@ -1169,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;
+}
+
+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;
+  }
+};
 
-  return json(channels);
+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) => {
@@ -1486,20 +2069,23 @@ const getHealthRoute: Handler = () => json(getHealth());
 const postSystemReap: Handler = () => {
   const released = releaseExpiredClaims();
   const reapedAgentIds = reapStaleAgents();
+  const reapedOrchestratorIds = reapStaleOrchestrators();
   for (const id of released.messageIds) emitMessageClaimReleased(id);
   for (const task of released.tasks) emitTaskChanged(task, "task.updated");
   for (const id of reapedAgentIds) emitAgentStatus(id);
+  for (const id of reapedOrchestratorIds) emitOrchestratorStatus(id);
   auditEvent({
     clientId: "server-system-reap-" + Date.now(),
     kind: "state",
     title: "Maintenance reaper run",
-    body: `${reapedAgentIds.length} stale agent(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
+    body: `${reapedAgentIds.length} stale agent(s), ${reapedOrchestratorIds.length} stale orchestrator(s), ${released.messageIds.length} message claim(s), ${released.tasks.length} task claim(s)`,
     icon: "ti-broom",
     view: "activity",
   });
   return json({
     ok: true,
     reapedAgentIds,
+    reapedOrchestratorIds,
     releasedMessageIds: released.messageIds,
     releasedTaskIds: released.tasks.map((task) => task.id),
   });
@@ -1542,6 +2128,15 @@ const routes: Route[] = [
   route("POST", "/api/agents/:id/actions", postAgentAction),
   route("DELETE", "/api/agents/:id", deleteAgentById),
 
+  route("POST", "/api/orchestrators", postOrchestrator),
+  route("GET", "/api/orchestrators", getOrchestrators),
+  route("GET", "/api/orchestrators/:id", getOrchestratorById),
+  route("POST", "/api/orchestrators/:id/heartbeat", postOrchestratorHeartbeat),
+  route("PATCH", "/api/orchestrators/:id/agents", patchOrchestratorAgents),
+  route("POST", "/api/orchestrators/:id/spawn", postOrchestratorSpawn),
+  route("POST", "/api/orchestrators/:id/actions", postOrchestratorAction),
+  route("DELETE", "/api/orchestrators/:id", deleteOrchestratorById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("POST", "/api/messages", postMessage),
   route("GET", "/api/messages", getMessages),
@@ -1561,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),