agent-relay-server 0.5.0 → 0.6.1

package/src/db.ts

@@ -5,13 +5,18 @@ import type {
   AgentCard,
   ActivityEvent,
   ActivityEventInput,
+  AgentKind,
   AgentSessionGuard,
+  ChannelBinding,
+  ChannelBindingMode,
+  ChannelRouteTarget,
+  ChannelSummary,
+  ChannelTargetHealth,
   CreatePairInput,
   HealthCheck,
   HealthReport,
   ManagedAgent,
   Message,
-  MessageType,
   Orchestrator,
   OrchestratorStatus,
   PairActionInput,
@@ -48,6 +53,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE TABLE IF NOT EXISTS agents (
       id TEXT PRIMARY KEY,
       name TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'provider',
       tags TEXT NOT NULL DEFAULT '[]',
       machine TEXT,
       rig TEXT,
@@ -64,7 +70,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       from_agent TEXT NOT NULL,
       to_target TEXT NOT NULL,
-      type TEXT NOT NULL DEFAULT 'message',
+      kind TEXT NOT NULL DEFAULT 'chat',
       channel TEXT,
       subject TEXT,
       body TEXT NOT NULL,
@@ -75,6 +81,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       claimed_at INTEGER,
       claim_expires_at INTEGER,
       idempotency_key TEXT,
+      payload TEXT NOT NULL DEFAULT '{}',
       meta TEXT NOT NULL DEFAULT '{}',
       read_by TEXT NOT NULL DEFAULT '[]',
       created_at INTEGER NOT NULL
@@ -199,6 +206,38 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_activity_operator ON activity_events(operator_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_activity_created ON activity_events(created_at);
 
+    CREATE TABLE IF NOT EXISTS channels (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      account_id TEXT NOT NULL,
+      display_name TEXT NOT NULL,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      transport TEXT NOT NULL,
+      direction TEXT NOT NULL DEFAULT 'bidirectional',
+      topic_channels TEXT NOT NULL DEFAULT '[]',
+      capabilities TEXT NOT NULL DEFAULT '[]',
+      meta TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_channels_agent ON channels(agent_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_channels_provider_account ON channels(provider, account_id);
+
+    CREATE TABLE IF NOT EXISTS channel_bindings (
+      id TEXT PRIMARY KEY,
+      channel_id TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+      conversation_key TEXT NOT NULL DEFAULT '',
+      conversation_id TEXT,
+      target_type TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      mode TEXT NOT NULL DEFAULT 'exclusive',
+      priority INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_channel_bindings_channel ON channel_bindings(channel_id, priority);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_target ON channel_bindings(channel_id, conversation_key, target_type, target_id);
+
     CREATE TABLE IF NOT EXISTS orchestrators (
       id TEXT PRIMARY KEY,
       hostname TEXT NOT NULL,
@@ -238,9 +277,42 @@ export function initDb(path: string = "agent-relay.db"): Database {
   db.run("CREATE INDEX IF NOT EXISTS idx_msg_thread ON messages(thread_id)");
   db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_idempotency ON messages(from_agent, idempotency_key) WHERE idempotency_key IS NOT NULL");
 
-  if (!colNames.includes("type")) {
-    db.run("ALTER TABLE messages ADD COLUMN type TEXT NOT NULL DEFAULT 'message'");
+  const channelBindingsSql = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'channel_bindings'").get() as { sql?: string } | undefined;
+  if (channelBindingsSql?.sql?.includes("UNIQUE(channel_id, conversation_key)")) {
+    db.transaction(() => {
+      db.run("ALTER TABLE channel_bindings RENAME TO channel_bindings_old");
+      db.run(`
+        CREATE TABLE channel_bindings (
+          id TEXT PRIMARY KEY,
+          channel_id TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+          conversation_key TEXT NOT NULL DEFAULT '',
+          conversation_id TEXT,
+          target_type TEXT NOT NULL,
+          target_id TEXT NOT NULL,
+          mode TEXT NOT NULL DEFAULT 'exclusive',
+          priority INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+      db.run(`
+        INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
+        SELECT id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at
+        FROM channel_bindings_old
+      `);
+      db.run("DROP TABLE channel_bindings_old");
+    })();
+  }
+  db.run("CREATE INDEX IF NOT EXISTS idx_channel_bindings_channel ON channel_bindings(channel_id, priority)");
+  db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_target ON channel_bindings(channel_id, conversation_key, target_type, target_id)");
+
+  if (!colNames.includes("kind")) {
+    db.run("ALTER TABLE messages ADD COLUMN kind TEXT NOT NULL DEFAULT 'chat'");
+  }
+  if (!colNames.includes("payload")) {
+    db.run("ALTER TABLE messages ADD COLUMN payload TEXT NOT NULL DEFAULT '{}'");
   }
+  db.run("CREATE INDEX IF NOT EXISTS idx_msg_kind ON messages(kind)");
 
   // Backfill thread_id for pre-migration rows (self-threaded).
   db.run("UPDATE messages SET thread_id = id WHERE thread_id IS NULL");
@@ -280,19 +352,33 @@ export function initDb(path: string = "agent-relay.db"): Database {
   if (!agentColNames.includes("epoch")) {
     db.run("ALTER TABLE agents ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0");
   }
+  if (!agentColNames.includes("kind")) {
+    db.run("ALTER TABLE agents ADD COLUMN kind TEXT NOT NULL DEFAULT 'provider'");
+    db.run(`
+      UPDATE agents
+      SET kind = CASE
+        WHEN id = 'user' THEN 'user'
+        WHEN id = 'system' THEN 'system'
+        WHEN json_extract(meta, '$.kind') = 'channel' THEN 'channel'
+        WHEN EXISTS (SELECT 1 FROM json_each(tags) WHERE value = 'channel') THEN 'channel'
+        ELSE 'provider'
+      END
+    `);
+  }
   db.run("CREATE INDEX IF NOT EXISTS idx_agents_label ON agents(label)");
+  db.run("CREATE INDEX IF NOT EXISTS idx_agents_kind ON agents(kind)");
 
   // Built-in agents — registered unconditionally so sends from these ids
   // pass the sendMessage validation. The reaper exempts these by checking
   // meta.builtin (or by id for "user").
   const now = Date.now();
   const builtinStmt = db.prepare(`
-    INSERT INTO agents (id, name, tags, machine, rig, capabilities, ready, status, meta, last_seen, created_at)
-    VALUES (?, ?, ?, NULL, NULL, '[]', 1, 'online', '{"builtin":true}', ?, ?)
+    INSERT INTO agents (id, name, kind, tags, machine, rig, capabilities, ready, status, meta, last_seen, created_at)
+    VALUES (?, ?, ?, ?, NULL, NULL, '[]', 1, 'online', '{"builtin":true}', ?, ?)
     ON CONFLICT(id) DO UPDATE SET status = 'online', ready = 1, last_seen = excluded.last_seen
   `);
-  builtinStmt.run("user", "User", '["human"]', now, now);
-  builtinStmt.run("system", "System", '["system"]', now, now);
+  builtinStmt.run("user", "User", "user", '["human"]', now, now);
+  builtinStmt.run("system", "System", "system", '["system"]', now, now);
 
   // One-shot migration: backfill message_reads from legacy read_by JSON
   // if that column still carries data. Safe to run repeatedly (INSERT OR IGNORE).
@@ -333,7 +419,19 @@ function stringValue(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
+function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
+  if (input.kind) return input.kind;
+  if (input.id === "user") return "user";
+  if (input.id === "system") return "system";
+  const metaKind = stringValue(input.meta?.kind);
+  if (metaKind === "channel" || metaKind === "communication-channel") return "channel";
+  if (metaKind === "orchestrator") return "orchestrator";
+  if ((input.tags ?? []).includes("channel") || (input.capabilities ?? []).includes("channel")) return "channel";
+  return "provider";
+}
+
 function inferProviderTag(input: RegisterAgentInput): "claude" | "codex" | undefined {
+  if (inferAgentKind(input) !== "provider") return undefined;
   const meta = input.meta ?? {};
   const values = [
     input.id,
@@ -367,6 +465,7 @@ function rowToAgent(row: any): AgentCard {
   return {
     id: row.id,
     name: row.name,
+    kind: row.kind ?? "provider",
     label: row.label ?? undefined,
     tags: parseStringArray(row.tags),
     machine: row.machine ?? undefined,
@@ -387,7 +486,7 @@ function rowToMessage(row: any): Message {
     id: row.id,
     from: row.from_agent,
     to: row.to_target,
-    type: (row.type ?? "message") as MessageType,
+    kind: row.kind ?? "chat",
     channel: row.channel ?? undefined,
     subject: row.subject ?? undefined,
     body: row.body,
@@ -398,6 +497,7 @@ function rowToMessage(row: any): Message {
     claimedAt: row.claimed_at ?? undefined,
     claimExpiresAt: row.claim_expires_at ?? undefined,
     idempotencyKey: row.idempotency_key ?? undefined,
+    payload: parseJson(row.payload ?? "{}", {}),
     meta: parseJson(row.meta, {}),
     readBy: parseJson(row.read_by_agents ?? "[]", []),
     createdAt: row.created_at,
@@ -503,6 +603,154 @@ function rowToActivityEvent(row: any): ActivityEvent {
   };
 }
 
+function rowToChannelBinding(row: any): ChannelBinding {
+  const target = row.target_type === "broadcast"
+    ? { type: "broadcast" } as ChannelRouteTarget
+    : { type: row.target_type, id: row.target_id } as ChannelRouteTarget;
+  return {
+    id: row.id,
+    channelId: row.channel_id,
+    conversationId: row.conversation_id ?? undefined,
+    target,
+    mode: row.mode as ChannelBindingMode,
+    priority: row.priority,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
+  if (target.type === "agent") return target.id;
+  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 === "orchestrator") return `orchestrator:${target.id}`;
+  return "";
+}
+
+function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
+  const candidates = listAgents().filter((agent) => (
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.kind !== "channel" &&
+    agent.meta?.kind !== "channel"
+  ));
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = getAgent(target.id);
+    return agent ? [agent] : [];
+  }
+  if (target.type === "label") return candidates.filter((agent) => agent.label === target.id);
+  if (target.type === "tag") return candidates.filter((agent) => agent.tags.includes(target.id));
+  if (target.type === "capability") return candidates.filter((agent) => agent.capabilities.includes(target.id));
+  if (target.type === "broadcast") return candidates;
+  return [];
+}
+
+function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
+  return {
+    id: agent.id,
+    name: agent.name,
+    status: agent.status,
+    ready: agent.ready,
+    lastSeen: agent.lastSeen,
+    label: agent.label,
+    tags: agent.tags,
+    capabilities: agent.capabilities,
+  };
+}
+
+function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
+  return isDeliveryAgent(agent) && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+function describeTarget(target: ChannelRouteTarget): string {
+  return bindingTargetToLegacyTarget(target);
+}
+
+function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
+  const target = binding.target;
+  const targetLabel = describeTarget(target);
+  const matches = channelTargetMatches(target);
+  const snapshots = matches.map(channelTargetMatchSnapshot);
+
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = matches[0];
+    if (!agent) {
+      return { status: "error", detail: `Target ${targetLabel} is not registered`, target, matches: [] };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && (agent.kind === "channel" || agent.meta?.kind === "channel")) {
+      return { status: "error", detail: `Target ${targetLabel} is a channel, not a delivery agent`, target, matches: snapshots };
+    }
+    if (agent.status === "offline") {
+      return { status: "error", detail: `Target ${targetLabel} is offline`, target, matches: snapshots };
+    }
+    if (!agent.ready) {
+      return { status: "warning", detail: `Target ${targetLabel} is online but not ready`, target, matches: snapshots };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && agent.lastSeen <= now - STALE_TTL_MS) {
+      return { status: "warning", detail: `Target ${targetLabel} heartbeat is stale`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Target ${targetLabel} is online and ready`, target, matches: snapshots };
+  }
+
+  const healthyMatches = matches.filter((agent) => isHealthyChannelTarget(agent, now));
+  if (matches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no matching agents`, target, matches: [] };
+  }
+  if (healthyMatches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no online ready agents`, target, matches: snapshots };
+  }
+  if (binding.mode === "exclusive" && healthyMatches.length > 1) {
+    return {
+      status: "warning",
+      detail: `Target ${targetLabel} matches ${healthyMatches.length} online ready agents for an exclusive binding`,
+      target,
+      matches: snapshots,
+    };
+  }
+  return {
+    status: "ok",
+    detail: `Target ${targetLabel} has ${healthyMatches.length} online ready agent${healthyMatches.length === 1 ? "" : "s"}`,
+    target,
+    matches: snapshots,
+  };
+}
+
+function rowToChannelSummary(row: any): ChannelSummary {
+  const binding = row.binding_id ? rowToChannelBinding({
+    id: row.binding_id,
+    channel_id: row.id,
+    conversation_id: row.binding_conversation_id,
+    target_type: row.binding_target_type,
+    target_id: row.binding_target_id,
+    mode: row.binding_mode,
+    priority: row.binding_priority,
+    created_at: row.binding_created_at,
+    updated_at: row.binding_updated_at,
+  }) : undefined;
+
+  return {
+    id: row.id,
+    name: row.display_name,
+    type: row.provider,
+    transport: row.transport,
+    agentId: row.agent_id,
+    accountId: row.account_id,
+    status: row.agent_status,
+    ready: row.agent_ready === 1,
+    direction: row.direction,
+    target: binding ? bindingTargetToLegacyTarget(binding.target) : undefined,
+    binding,
+    targetHealth: binding ? channelTargetHealth(binding) : undefined,
+    topicChannels: parseStringArray(row.topic_channels),
+    capabilities: parseStringArray(row.channel_capabilities),
+    tags: parseStringArray(row.agent_tags),
+    lastSeen: row.agent_last_seen,
+    meta: parseJson(row.channel_meta, {}),
+  };
+}
+
 const MSG_SELECT = `SELECT m.*, (
   SELECT json_group_array(agent_id) FROM message_reads WHERE message_id = m.id
 ) AS read_by_agents FROM messages m`;
@@ -511,6 +759,13 @@ const MSG_SELECT = `SELECT m.*, (
 
 export function upsertAgent(input: RegisterAgentInput): AgentCard {
   const now = Date.now();
+  const kind = inferAgentKind(input);
+  if (kind === "channel") {
+    const expectedId = expectedChannelAgentId(input);
+    if (input.id !== expectedId) {
+      throw new ValidationError(`channel agent id must be canonical: ${expectedId}`);
+    }
+  }
   const tags = tagsWithProvider(input);
   // Preserve the existing label across re-registrations unless the caller
   // explicitly sends one (including null to clear).
@@ -518,10 +773,11 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
   const instanceProvided = Boolean(input.instanceId);
   const stmt = db.prepare(`
-    INSERT INTO agents (id, name, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, meta, last_seen, created_at)
-    VALUES ($id, $name, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $meta, $now, $now)
+    INSERT INTO agents (id, name, kind, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, meta, last_seen, created_at)
+    VALUES ($id, $name, $kind, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $meta, $now, $now)
     ON CONFLICT(id) DO UPDATE SET
       name = $name,
+      kind = $kind,
       label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
       tags = $tags,
       machine = coalesce($machine, agents.machine),
@@ -541,6 +797,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   stmt.run({
     $id: input.id,
     $name: input.name,
+    $kind: kind,
     $label: input.label ?? null,
     $labelProvided: labelProvided ? 1 : 0,
     $tags: JSON.stringify(tags),
@@ -557,7 +814,9 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
     $now: now,
   });
 
-  return getAgent(input.id)!;
+  const agent = getAgent(input.id)!;
+  if (agent.kind === "channel") upsertChannelForAgent(agent);
+  return agent;
 }
 
 export function validateAgentSession(id: string, guard?: AgentSessionGuard): { ok: boolean; error?: string } {
@@ -646,6 +905,207 @@ export function heartbeat(id: string, guard?: AgentSessionGuard): boolean {
   return result.changes > 0;
 }
 
+function channelProviderForAgent(agent: AgentCard): string {
+  return stringValue(agent.meta?.provider) ??
+    stringValue(agent.meta?.channelType) ??
+    stringValue(agent.meta?.transport) ??
+    agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+function channelProviderForInput(input: Pick<RegisterAgentInput, "tags" | "meta">): string {
+  return stringValue(input.meta?.provider) ??
+    stringValue(input.meta?.channelType) ??
+    stringValue(input.meta?.transport) ??
+    (input.tags ?? []).find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+function channelAccountIdForAgent(agent: AgentCard, provider: string): string {
+  const accountId = stringValue(agent.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return agent.id.startsWith(prefix) ? agent.id.slice(prefix.length) : agent.id;
+}
+
+function channelAccountIdForInput(input: Pick<RegisterAgentInput, "id" | "meta">, provider: string): string {
+  const accountId = stringValue(input.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return input.id.startsWith(prefix) ? input.id.slice(prefix.length) : input.id;
+}
+
+function expectedChannelAgentId(input: Pick<RegisterAgentInput, "id" | "tags" | "meta">): string {
+  const provider = channelProviderForInput(input);
+  const accountId = channelAccountIdForInput(input, provider);
+  return `${provider}:${accountId}`;
+}
+
+function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"] {
+  const direction = stringValue(agent.meta?.direction);
+  return direction === "inbound" || direction === "outbound" || direction === "bidirectional" ? direction : "bidirectional";
+}
+
+function routeTargetFromLegacyTarget(target: string | undefined): ChannelRouteTarget | undefined {
+  if (!target) return undefined;
+  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:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
+  return { type: "agent", id: target };
+}
+
+function upsertChannelForAgent(agent: AgentCard): void {
+  const now = Date.now();
+  const provider = channelProviderForAgent(agent);
+  const accountId = channelAccountIdForAgent(agent, provider);
+  const channelId = `${provider}:${accountId}`;
+  const transport = stringValue(agent.meta?.transport) ?? provider;
+  const displayName = stringValue(agent.meta?.displayName) ?? agent.name;
+  const topicChannels = Array.isArray(agent.meta?.topicChannels)
+    ? (agent.meta.topicChannels as unknown[]).filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+    : [];
+
+  db.prepare(`
+    INSERT INTO channels (id, provider, account_id, display_name, agent_id, transport, direction, topic_channels, capabilities, meta, created_at, updated_at)
+    VALUES ($id, $provider, $accountId, $displayName, $agentId, $transport, $direction, $topicChannels, $capabilities, $meta, $now, $now)
+    ON CONFLICT(provider, account_id) DO UPDATE SET
+      id = $id,
+      provider = $provider,
+      account_id = $accountId,
+      display_name = $displayName,
+      agent_id = $agentId,
+      transport = $transport,
+      direction = $direction,
+      topic_channels = $topicChannels,
+      capabilities = $capabilities,
+      meta = $meta,
+      updated_at = $now
+  `).run({
+    $id: channelId,
+    $provider: provider,
+    $accountId: accountId,
+    $displayName: displayName,
+    $agentId: agent.id,
+    $transport: transport,
+    $direction: channelDirectionForAgent(agent),
+    $topicChannels: JSON.stringify(topicChannels),
+    $capabilities: JSON.stringify(agent.capabilities),
+    $meta: JSON.stringify(agent.meta ?? {}),
+    $now: now,
+  });
+
+  const defaultTarget = routeTargetFromLegacyTarget(stringValue(agent.meta?.target));
+  if (defaultTarget) {
+    upsertChannelBinding({
+      channelId,
+      target: defaultTarget,
+      mode: defaultTarget.type === "agent" ? "exclusive" : defaultTarget.type === "broadcast" ? "broadcast" : "claimable",
+    });
+  }
+}
+
+export function listChannels(): ChannelSummary[] {
+  const rows = db.prepare(`
+    SELECT
+      c.*,
+      c.capabilities AS channel_capabilities,
+      c.meta AS channel_meta,
+      a.status AS agent_status,
+      a.ready AS agent_ready,
+      a.tags AS agent_tags,
+      a.last_seen AS agent_last_seen,
+      b.id AS binding_id,
+      b.conversation_id AS binding_conversation_id,
+      b.target_type AS binding_target_type,
+      b.target_id AS binding_target_id,
+      b.mode AS binding_mode,
+      b.priority AS binding_priority,
+      b.created_at AS binding_created_at,
+      b.updated_at AS binding_updated_at
+    FROM channels c
+    JOIN agents a ON a.id = c.agent_id
+    LEFT JOIN channel_bindings b ON b.channel_id = c.id AND b.conversation_key = ''
+    ORDER BY a.ready DESC, c.display_name COLLATE NOCASE
+  `).all() as any[];
+  return rows.map(rowToChannelSummary);
+}
+
+export function getChannel(channelId: string): ChannelSummary | null {
+  return listChannels().find((channel) => channel.id === channelId) ?? null;
+}
+
+export function listChannelBindings(channelId?: string): ChannelBinding[] {
+  const rows = channelId
+    ? db.prepare("SELECT * FROM channel_bindings WHERE channel_id = ? ORDER BY priority DESC, updated_at DESC").all(channelId) as any[]
+    : db.prepare("SELECT * FROM channel_bindings ORDER BY channel_id, priority DESC, updated_at DESC").all() as any[];
+  return rows.map(rowToChannelBinding);
+}
+
+export function upsertChannelBinding(input: {
+  channelId: string;
+  conversationId?: string;
+  target: ChannelRouteTarget;
+  mode?: ChannelBindingMode;
+  priority?: number;
+}): ChannelBinding {
+  if (!getChannel(input.channelId)) throw new ValidationError(`channel ${input.channelId} not found`);
+  const conversationKey = input.conversationId ?? "";
+  const targetId = input.target.type === "broadcast" ? "" : input.target.id;
+  const targetKey = input.target.type === "broadcast" ? "broadcast" : `${input.target.type}:${targetId}`;
+  const id = `${input.channelId}:${conversationKey || "default"}:${targetKey}`;
+  const mode = input.mode ?? "exclusive";
+  const now = Date.now();
+  db.transaction(() => {
+    if (mode === "exclusive") {
+      db.prepare("DELETE FROM channel_bindings WHERE channel_id = ? AND conversation_key = ?").run(input.channelId, conversationKey);
+    }
+    db.prepare(`
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
+      ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
+        mode = $mode,
+        priority = $priority,
+        updated_at = $now
+    `).run({
+      $id: id,
+      $channelId: input.channelId,
+      $conversationKey: conversationKey,
+      $conversationId: input.conversationId ?? null,
+      $targetType: input.target.type,
+      $targetId: targetId,
+      $mode: mode,
+      $priority: input.priority ?? 0,
+      $now: now,
+    });
+  })();
+
+  const row = db.prepare("SELECT * FROM channel_bindings WHERE id = ?").get(id) as any;
+  return rowToChannelBinding(row);
+}
+
+export function resolveChannelRoutes(channelId: string, conversationId?: string): ChannelBinding[] {
+  const rows = conversationId
+    ? db.prepare(`
+      SELECT * FROM channel_bindings
+      WHERE channel_id = ? AND conversation_key IN (?, '')
+      ORDER BY CASE WHEN conversation_key = ? THEN 1 ELSE 0 END DESC, priority DESC, updated_at DESC
+    `).all(channelId, conversationId, conversationId) as any[]
+    : db.prepare(`
+      SELECT * FROM channel_bindings
+      WHERE channel_id = ? AND conversation_key = ''
+      ORDER BY priority DESC, updated_at DESC
+    `).all(channelId) as any[];
+  if (!conversationId) return rows.map(rowToChannelBinding);
+  const exact = rows.filter((row) => row.conversation_key === conversationId);
+  return (exact.length ? exact : rows.filter((row) => row.conversation_key === "")).map(rowToChannelBinding);
+}
+
+export function resolveChannelRoute(channelId: string, conversationId?: string): ChannelBinding | null {
+  return resolveChannelRoutes(channelId, conversationId)[0] ?? null;
+}
+
 export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   const now = Date.now();
   const cutoff = now - ttlMs;
@@ -833,14 +1293,16 @@ export function ingestIntegrationEvent(input: IntegrationEventInput, integration
       message = sendMessage({
         from: "system",
         to: task.target,
-        type: "system",
+        kind: "task",
         channel: task.channel,
         subject: `[${task.severity}] ${task.title}`,
         body: taskMessageBody(task),
         claimable: true,
-        meta: {
+        payload: {
           taskId: task.id,
           source: task.source,
+          title: task.title,
+          status: task.status,
           severity: task.severity,
           dedupeKey: task.dedupeKey ?? null,
           externalUrl: task.externalUrl ?? null,
@@ -1175,10 +1637,10 @@ function pairSystemMessage(pair: PairSession, to: string, event: string, subject
   return sendMessage({
     from: "system",
     to,
-    type: "system",
+    kind: "pair",
     subject,
     body,
-    meta: {
+    payload: {
       pairId: pair.id,
       pairEvent: event,
       requesterId: pair.requesterId,
@@ -1326,9 +1788,10 @@ export function sendPairMessage(id: string, input: PairMessageInput): { ok: true
   const message = sendMessage({
     from: input.from,
     to,
+    kind: "pair",
     subject: input.subject ?? `Pair ${pair.id}`,
     body: input.body,
-    meta: {
+    payload: {
       pairId: pair.id,
       pairEvent: "message",
       requesterId: pair.requesterId,
@@ -1352,9 +1815,35 @@ function isDeliveryAgent(agent: AgentCard): boolean {
   return agent.status !== "offline" &&
     agent.id !== "user" &&
     agent.id !== "system" &&
+    agent.kind !== "channel" &&
     agent.meta?.kind !== "channel";
 }
 
+function isChannelAgentId(agentId: string): boolean {
+  const agent = getAgent(agentId);
+  return Boolean(agent && (
+    agent.kind === "channel" ||
+    agent.meta?.kind === "channel" ||
+    agent.tags.includes("channel") ||
+    agent.capabilities.includes("channel")
+  ));
+}
+
+function legacyChannelTargets(agent: AgentCard | null | undefined): string[] {
+  if (!agent || !isChannelAgentId(agent.id)) return [];
+  const aliases = new Set<string>();
+  const provider = channelProviderForAgent(agent);
+  if (provider && provider !== "custom") aliases.add(provider);
+  const channelType = stringValue(agent.meta?.channelType);
+  if (channelType) aliases.add(channelType);
+  const transport = stringValue(agent.meta?.transport);
+  if (transport) aliases.add(transport);
+  const providerTag = agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length);
+  if (providerTag) aliases.add(providerTag);
+  aliases.delete(agent.id);
+  return [...aliases];
+}
+
 function matchingDeliveryAgents(target: string): AgentCard[] {
   if (!target) return [];
   const candidates = listAgents().filter(isDeliveryAgent);
@@ -1382,10 +1871,18 @@ function claimableAllowedForTarget(target: string): boolean {
 
 function shouldStoreClaimable(input: SendMessageInput): boolean {
   if (!input.claimable) return false;
-  if (input.type === "system" || typeof input.meta?.taskId === "number") return true;
+  if (input.kind === "task" || input.kind === "system") return true;
+  if (input.kind === "channel.event") return true;
   return claimableAllowedForTarget(input.to);
 }
 
+function inferMessageKind(input: SendMessageInput): Message["kind"] {
+  if (input.kind) return input.kind;
+  if (input.claimable) return "task";
+  if (isChannelAgentId(input.from) || isChannelAgentId(input.to)) return "channel.event";
+  return "chat";
+}
+
 export function sendMessageWithResult(input: SendMessageInput): { message: Message; created: boolean } {
   const now = Date.now();
 
@@ -1408,17 +1905,18 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
   }
 
   const insert = db.prepare(`
-    INSERT INTO messages (from_agent, to_target, type, channel, subject, body, thread_id, reply_to, claimable, idempotency_key, meta, created_at)
-    VALUES ($from, $to, $type, $channel, $subject, $body, $threadId, $replyTo, $claimable, $idempotencyKey, $meta, $now)
+    INSERT INTO messages (from_agent, to_target, kind, channel, subject, body, thread_id, reply_to, claimable, idempotency_key, payload, meta, created_at)
+    VALUES ($from, $to, $kind, $channel, $subject, $body, $threadId, $replyTo, $claimable, $idempotencyKey, $payload, $meta, $now)
   `);
   const setSelfThread = db.prepare("UPDATE messages SET thread_id = ? WHERE id = ?");
   const claimable = shouldStoreClaimable(input);
+  const kind = inferMessageKind(input);
 
   const id = db.transaction(() => {
     const result = insert.run({
       $from: input.from,
       $to: input.to,
-      $type: input.type ?? "message",
+      $kind: kind,
       $channel: input.channel ?? null,
       $subject: input.subject ?? null,
       $body: input.body,
@@ -1426,6 +1924,7 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
       $replyTo: input.replyTo ?? null,
       $claimable: claimable ? 1 : 0,
       $idempotencyKey: input.idempotencyKey ?? null,
+      $payload: JSON.stringify(input.payload ?? {}),
       $meta: JSON.stringify(input.meta ?? {}),
       $now: now,
     });
@@ -1483,8 +1982,8 @@ export function claimMessage(messageId: number, agentId: string, guard?: AgentSe
       const messageClaim = claimMessageRow(messageId, agentId, now);
       if (!messageClaim.ok) return messageClaim;
 
-      const taskId = typeof msg.meta?.taskId === "number" && Number.isSafeInteger(msg.meta.taskId)
-        ? msg.meta.taskId
+      const taskId = typeof msg.payload?.taskId === "number" && Number.isSafeInteger(msg.payload.taskId)
+        ? msg.payload.taskId
         : null;
       if (!taskId) return { ok: true };
 
@@ -1534,8 +2033,8 @@ export function renewMessageClaim(messageId: number, agentId: string, guard?: Ag
   let task: Task | undefined;
   db.transaction(() => {
     db.prepare("UPDATE messages SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, messageId, agentId);
-    const taskId = typeof msg.meta?.taskId === "number" && Number.isSafeInteger(msg.meta.taskId)
-      ? msg.meta.taskId
+    const taskId = typeof msg.payload?.taskId === "number" && Number.isSafeInteger(msg.payload.taskId)
+      ? msg.payload.taskId
       : null;
     if (taskId) {
       db.prepare("UPDATE tasks SET claim_expires_at = ?, updated_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, now, taskId, agentId);
@@ -1575,11 +2074,15 @@ export function pollMessages(query: PollQuery): Message[] {
   const agentTags = agent?.tags ?? [];
   const agentCaps = agent?.capabilities ?? [];
   const agentLabel = agent?.label;
+  const agentLegacyChannelTargets = legacyChannelTargets(agent);
 
   const conditions: string[] = [];
   const params: any[] = [];
 
-  // Build target matching: direct + broadcast + tag + capability + label
+  // Build target matching: direct + broadcast + tag + capability + label.
+  // Channel agents also accept legacy bare provider targets (for example
+  // "telegram") so older clients keep working after canonical IDs became
+  // provider:account ("telegram:default").
   const targetClauses = ["to_target = ?", "to_target = 'broadcast'"];
   params.push(query.for);
 
@@ -1595,6 +2098,10 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push("to_target = ?");
     params.push(`label:${agentLabel}`);
   }
+  for (const target of agentLegacyChannelTargets) {
+    targetClauses.push("to_target = ?");
+    params.push(target);
+  }
   conditions.push(`(${targetClauses.join(" OR ")})`);
 
   // Hide active claims held by someone else, but let expired claims surface so
@@ -1879,6 +2386,21 @@ export function getHealth(now: number = Date.now()): HealthReport {
     detail: offlineClaimedTasks > 0 ? `${offlineClaimedTasks} active task(s) are claimed by offline agents` : undefined,
   });
 
+  const unhealthyChannelTargets = listChannels().filter((channel) => channel.targetHealth && channel.targetHealth.status !== "ok");
+  const channelTargetErrors = unhealthyChannelTargets.filter((channel) => channel.targetHealth?.status === "error");
+  const channelTargetDetail = unhealthyChannelTargets
+    .slice(0, 3)
+    .map((channel) => `${channel.name}: ${channel.targetHealth?.detail}`)
+    .join("; ");
+  checks.push({
+    name: "channel-delivery-targets",
+    status: channelTargetErrors.length > 0 ? "error" : unhealthyChannelTargets.length > 0 ? "warn" : "ok",
+    count: unhealthyChannelTargets.length,
+    detail: unhealthyChannelTargets.length > 0
+      ? `${unhealthyChannelTargets.length} channel delivery target issue(s): ${channelTargetDetail}${unhealthyChannelTargets.length > 3 ? "; ..." : ""}`
+      : undefined,
+  });
+
   const status = checks.some((check) => check.status === "error")
     ? "error"
     : checks.some((check) => check.status === "warn")