agent-relay-server 0.33.0 → 0.34.0

package/src/db/channels.ts

@@ -0,0 +1,576 @@
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { parseJson } from "../utils";
+import { isLiveIsolatedWorkspace } from "../workspace-phase";
+import { parseChannelRouteTarget } from "../channel-target.ts";
+import {
+  CONTRACT_REQUIREMENTS,
+  contractCompatibility,
+  parseRuntimeCapabilities,
+  parseRuntimeContracts,
+  parseRuntimePackage,
+  type RuntimeContracts,
+} from "../contracts";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { matchAgents } from "../agent-ref";
+import { getAgent, listAgents, parseStringArray } from "./agents.ts";
+import { ValidationError, getDb } from "./connection.ts";
+import { isDeliveryAgent } from "./delivery.ts";
+import { runningAgentForPolicy } from "./messages.ts";
+import type {
+  AgentCard,
+  ActivityEvent,
+  ActivityEventInput,
+  AgentKind,
+  AgentSessionGuard,
+  Artifact,
+  ArtifactBlob,
+  ArtifactKind,
+  ArtifactLink,
+  ArtifactSensitivity,
+  ArtifactVisibility,
+  AttachmentRef,
+  ChannelBinding,
+  ChannelBindingMode,
+  ChannelRouteTarget,
+  ChatHistoryImport,
+  ChatHistoryImportEntry,
+  ChannelSummary,
+  ChannelTargetHealth,
+  CreatePairInput,
+  HealthCheck,
+  HealthReport,
+  ManagedAgent,
+  ManagedSessionExitDiagnostics,
+  Message,
+  MessageDeliveryAttempt,
+  MessageDeliveryStatus,
+  Orchestrator,
+  OrchestratorHealth,
+  OrchestratorRuntimeInput,
+  OrchestratorStatus,
+  OrchestratorUpgradeState,
+  PairActionInput,
+  PairMessageInput,
+  PairSession,
+  PairStatus,
+  RegisterAgentInput,
+  ReplyObligation,
+  RegisterOrchestratorInput,
+  SendMessageInput,
+  PollQuery,
+  SpawnApprovalMode,
+  SpawnProvider,
+  Task,
+  TaskEvent,
+  TaskSeverity,
+  TaskStatus,
+  IntegrationEventInput,
+  IntegrationSummary,
+  IntegrationTaskStats,
+  InboxDraft,
+  InboxState,
+  InboxThreadState,
+  ContextSnapshot,
+  ContextState,
+  ProviderCapabilities,
+  TaskStatusInput,
+  WorkspaceMetadata,
+  WorkspaceRecord,
+  WorkspaceStatus,
+} from "../types";
+
+export 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;
+  const binding: ChannelBinding = {
+    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,
+  };
+  if (row.pool_selector) {
+    binding.poolSelector = row.pool_selector;
+    binding.poolAgentId = row.pool_agent_id ?? undefined;
+    binding.poolAgentEpoch = row.pool_agent_epoch ?? undefined;
+    binding.poolClaimExpiresAt = row.pool_claim_expires_at ?? undefined;
+  }
+  return binding;
+}
+
+export 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}`;
+  if (target.type === "pool") return `pool:${target.id}`;
+  if (target.type === "policy") return `policy:${target.id}`;
+  return "";
+}
+
+export function configuredChannelsForAgent(agent: AgentCard): string[] {
+  const channels = agent.meta?.channels;
+  if (!Array.isArray(channels)) return [];
+  return channels
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+export function channelEntryMatches(channelId: string, entry: string): boolean {
+  const normalized = entry.trim();
+  if (!normalized) return false;
+  if (normalized === channelId) return true;
+  if (normalized.endsWith(":*")) return channelId.startsWith(normalized.slice(0, -1));
+  return channelId.startsWith(`${normalized}:`);
+}
+
+export function agentCanServeChannel(agent: AgentCard, channelId?: string): boolean {
+  if (!channelId) return true;
+  const channels = configuredChannelsForAgent(agent);
+  if (channels.length === 0) return true;
+  return channels.some((entry) => channelEntryMatches(channelId, entry));
+}
+
+export function channelTargetMatches(target: ChannelRouteTarget, channelId?: string): 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 === "policy") {
+    const agentId = runningAgentForPolicy(target.id);
+    const agent = agentId ? getAgent(agentId) : null;
+    return agent ? [agent] : [];
+  }
+  const channelCandidates = candidates.filter((agent) => agentCanServeChannel(agent, channelId));
+  if (target.type === "pool") return poolSelectorMatches(target.id, channelCandidates);
+  if (target.type === "label") return channelCandidates.filter((agent) => agent.label === target.id);
+  if (target.type === "tag") return channelCandidates.filter((agent) => agent.tags.includes(target.id));
+  if (target.type === "capability") return channelCandidates.filter((agent) => agent.capabilities.includes(target.id));
+  if (target.type === "broadcast") return channelCandidates;
+  return [];
+}
+
+export function poolSelectorMatches(selector: string, candidates: AgentCard[]): AgentCard[] {
+  if (selector.startsWith("label:")) return candidates.filter((a) => a.label === selector.slice("label:".length));
+  if (selector.startsWith("tag:")) return candidates.filter((a) => a.tags.includes(selector.slice("tag:".length)));
+  if (selector.startsWith("cap:")) return candidates.filter((a) => a.capabilities.includes(selector.slice("cap:".length)));
+  const agent = getAgent(selector);
+  return agent ? [agent] : [];
+}
+
+export 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,
+  };
+}
+
+export function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
+  return isDeliveryAgent(agent) && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+export function describeTarget(target: ChannelRouteTarget): string {
+  return bindingTargetToLegacyTarget(target);
+}
+
+export function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
+  const target = binding.target;
+  const targetLabel = describeTarget(target);
+  const matches = channelTargetMatches(target, binding.channelId);
+  const snapshots = matches.map(channelTargetMatchSnapshot);
+
+  if (target.type === "pool") {
+    const healthyEligibles = matches.filter((a) => isHealthyChannelTarget(a, now));
+    if (!binding.poolAgentId) {
+      if (matches.length === 0) return { status: "error", detail: `Pool ${targetLabel}: no eligible agents`, target, matches: [] };
+      return { status: "error", detail: `Pool ${targetLabel}: ${healthyEligibles.length} eligible but slot unclaimed`, target, matches: snapshots };
+    }
+    const holder = getAgent(binding.poolAgentId);
+    if (!holder || holder.status === "offline") {
+      return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is offline`, target, matches: snapshots };
+    }
+    if (!agentCanServeChannel(holder, binding.channelId)) {
+      return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is not configured for ${binding.channelId}`, target, matches: snapshots };
+    }
+    if (!holder.ready) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} online but not ready`, target, matches: snapshots };
+    }
+    if (binding.poolAgentEpoch !== undefined && holder.epoch !== binding.poolAgentEpoch) {
+      return { status: "warning", detail: `Pool ${targetLabel}: holder epoch changed (stale claim)`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Pool ${targetLabel}: claimed by ${binding.poolAgentId}`, target, matches: snapshots };
+  }
+
+  if (target.type === "agent" || target.type === "orchestrator" || target.type === "policy") {
+    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 (!agentCanServeChannel(agent, binding.channelId)) {
+      return { status: "error", detail: `Target ${targetLabel} is not configured for ${binding.channelId}`, 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,
+  };
+}
+
+export 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,
+    pool_selector: row.binding_pool_selector,
+    pool_agent_id: row.binding_pool_agent_id,
+    pool_agent_epoch: row.binding_pool_agent_epoch,
+    pool_claim_expires_at: row.binding_pool_claim_expires_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, {}),
+  };
+}
+
+
+export 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";
+}
+
+export 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";
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export function expectedChannelAgentId(input: Pick<RegisterAgentInput, "id" | "tags" | "meta">): string {
+  const provider = channelProviderForInput(input);
+  const accountId = channelAccountIdForInput(input, provider);
+  return `${provider}:${accountId}`;
+}
+
+export function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"] {
+  const direction = stringValue(agent.meta?.direction);
+  return direction === "inbound" || direction === "outbound" || direction === "bidirectional" ? direction : "bidirectional";
+}
+
+// Parse an agent's configured channel target (meta.target / meta.configuredTarget).
+// Delegates to the canonical parser — the previous inline copy dropped `policy:`
+// and routed it as a literal agent id (#298). undefined target → no channel.
+export function routeTargetFromLegacyTarget(target: string | undefined): ChannelRouteTarget | undefined {
+  if (!target) return undefined;
+  return parseChannelRouteTarget(target);
+}
+
+export 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)
+    : [];
+
+  getDb().query(`
+    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) ?? stringValue(agent.meta?.configuredTarget));
+  if (defaultTarget) {
+    upsertChannelBinding({
+      channelId,
+      target: defaultTarget,
+      mode: defaultTarget.type === "broadcast" ? "broadcast" : "exclusive",
+    });
+  }
+}
+
+export function listChannels(): ChannelSummary[] {
+  const rows = getDb().query(`
+    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,
+      b.pool_selector AS binding_pool_selector,
+      b.pool_agent_id AS binding_pool_agent_id,
+      b.pool_agent_epoch AS binding_pool_agent_epoch,
+      b.pool_claim_expires_at AS binding_pool_claim_expires_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
+    ? getDb().query("SELECT * FROM channel_bindings WHERE channel_id = ? ORDER BY priority DESC, updated_at DESC").all(channelId) as any[]
+    : getDb().query("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 isPool = input.target.type === "pool";
+  const poolSelector = isPool ? targetId : null;
+  const now = Date.now();
+  getDb().transaction(() => {
+    if (mode === "exclusive") {
+      getDb().query("DELETE FROM channel_bindings WHERE channel_id = ? AND conversation_key = ?").run(input.channelId, conversationKey);
+    }
+    getDb().query(`
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, pool_selector, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $poolSelector, $now, $now)
+      ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
+        mode = $mode,
+        priority = $priority,
+        pool_selector = $poolSelector,
+        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,
+      $poolSelector: poolSelector,
+      $now: now,
+    });
+  })();
+
+  evaluatePoolBindings(now);
+  const row = getDb().query("SELECT * FROM channel_bindings WHERE id = ?").get(id) as any;
+  return rowToChannelBinding(row);
+}
+
+export interface PoolBindingChange {
+  bindingId: string;
+  channelId: string;
+  previousAgentId: string | null;
+  newAgentId: string | null;
+}
+
+export function evaluatePoolBindings(now: number = Date.now()): PoolBindingChange[] {
+  const rows = getDb().query("SELECT * FROM channel_bindings WHERE target_type = 'pool'").all() as any[];
+  const changes: PoolBindingChange[] = [];
+
+  for (const row of rows) {
+    const bindingId = row.id as string;
+    const channelId = row.channel_id as string;
+    const selector = row.pool_selector ?? row.target_id;
+    const currentAgentId: string | null = row.pool_agent_id;
+    const currentEpoch: number | null = row.pool_agent_epoch;
+
+    let holderValid = false;
+    if (currentAgentId) {
+      const holder = getAgent(currentAgentId);
+      if (holder && holder.status !== "offline" && holder.ready && holder.lastSeen > now - STALE_TTL_MS && agentCanServeChannel(holder, channelId)) {
+        if (currentEpoch === null || holder.epoch === currentEpoch) {
+          getDb().query("UPDATE channel_bindings SET pool_claim_expires_at = ? WHERE id = ?")
+            .run(now + POOL_CLAIM_LEASE_MS, bindingId);
+          holderValid = true;
+        }
+      }
+    }
+
+    if (!holderValid && currentAgentId) {
+      getDb().query("UPDATE channel_bindings SET pool_agent_id = NULL, pool_agent_epoch = NULL, pool_claim_expires_at = NULL WHERE id = ?")
+        .run(bindingId);
+      changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: null });
+    }
+
+    if (!holderValid) {
+      const candidates = listAgents().filter((a) =>
+        a.id !== "user" && a.id !== "system" && a.kind !== "channel" && a.meta?.kind !== "channel"
+      );
+      const eligible = poolSelectorMatches(selector, candidates)
+        .filter((a) => agentCanServeChannel(a, channelId))
+        .filter((a) => a.status !== "offline" && a.ready && a.lastSeen > now - STALE_TTL_MS)
+        .sort((a, b) => b.lastSeen - a.lastSeen);
+
+      if (eligible.length > 0) {
+        const picked = eligible[0]!;
+        getDb().query("UPDATE channel_bindings SET pool_agent_id = ?, pool_agent_epoch = ?, pool_claim_expires_at = ? WHERE id = ?")
+          .run(picked.id, picked.epoch, now + POOL_CLAIM_LEASE_MS, bindingId);
+        const lastChange = changes[changes.length - 1];
+        if (lastChange && lastChange.bindingId === bindingId && lastChange.newAgentId === null) {
+          lastChange.newAgentId = picked.id;
+        } else {
+          changes.push({ bindingId, channelId, previousAgentId: currentAgentId, newAgentId: picked.id });
+        }
+      }
+    }
+  }
+
+  return changes;
+}
+
+export function resolveChannelRoutes(channelId: string, conversationId?: string): ChannelBinding[] {
+  const rows = conversationId
+    ? getDb().query(`
+      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[]
+    : getDb().query(`
+      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);
+}
+

package/src/db/connection.ts

@@ -0,0 +1,71 @@
+import { Database } from "bun:sqlite";
+
+// The shared SQLite handle. Set once by initDb() (schema.ts) and read everywhere
+// else through getDb(). Kept module-private so the only mutation path is setDb().
+let db: Database;
+
+export function setDb(conn: Database): void {
+  db = conn;
+}
+
+export function getDb(): Database {
+  if (!db) throw new Error("database not initialized");
+  return db;
+}
+
+// Connection-scoped pragmas. journal_mode and auto_vacuum persist in the file;
+// the rest reset per connection, so they must be re-applied on every open.
+export function applyConnectionPragmas(conn: Database): void {
+  conn.run("PRAGMA journal_mode = WAL");
+  // Wait up to 5s for a held lock instead of failing instantly with SQLITE_BUSY.
+  // Matters with many agents polling/writing concurrently.
+  conn.run("PRAGMA busy_timeout = 5000");
+  // NORMAL is the recommended durability level under WAL: as safe as FULL except
+  // for a power loss mid-checkpoint, and meaningfully faster on writes.
+  conn.run("PRAGMA synchronous = NORMAL");
+  conn.run("PRAGMA foreign_keys = ON");
+  // ~8MB page cache (negative = KiB) and 256MB mmap window for the read-heavy
+  // poll workload. Both are best-effort; SQLite ignores them if unsupported.
+  conn.run("PRAGMA cache_size = -8000");
+  conn.run("PRAGMA mmap_size = 268435456");
+}
+
+// Slow-query log. Off unless AGENT_RELAY_DB_SLOW_MS is set (>0). Wraps the
+// execution of the heavy dynamic queries so the next slow query surfaces before
+// it wedges something (see issue #197 — the 8.6s reply-obligation query).
+const SLOW_QUERY_MS = Number(process.env.AGENT_RELAY_DB_SLOW_MS) || 0;
+export function timedQuery<T>(label: string, run: () => T): T {
+  if (SLOW_QUERY_MS <= 0) return run();
+  const start = performance.now();
+  try {
+    return run();
+  } finally {
+    const ms = performance.now() - start;
+    if (ms >= SLOW_QUERY_MS) {
+      console.warn(`[db.slow] ${label} took ${ms.toFixed(1)}ms (threshold ${SLOW_QUERY_MS}ms)`);
+    }
+  }
+}
+
+// Periodic DB upkeep, invoked by the maintenance scheduler. ANALYZE refreshes
+// planner statistics, PRAGMA optimize applies them, wal_checkpoint(TRUNCATE)
+// bounds WAL growth, and VACUUM (opt-in) reclaims space since auto_vacuum is off.
+export function runDbMaintenance(options: { vacuum?: boolean } = {}): {
+  analyzed: boolean;
+  checkpointed: boolean;
+  vacuumed: boolean;
+} {
+  db.run("ANALYZE");
+  db.run("PRAGMA optimize");
+  db.run("PRAGMA wal_checkpoint(TRUNCATE)");
+  let vacuumed = false;
+  if (options.vacuum) {
+    db.run("VACUUM");
+    vacuumed = true;
+  }
+  return { analyzed: true, checkpointed: true, vacuumed };
+}
+
+// Shared error types thrown across query domains and unwrapped at call sites.
+export class ValidationError extends Error {}
+export class ClaimError extends Error {}