agent-relay-server 0.32.4 → 0.33.1

package/src/db/delivery.ts

@@ -0,0 +1,395 @@
+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 {
+  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 } from "./agents.ts";
+import { channelProviderForAgent } from "./channels.ts";
+import { getDb } from "./connection.ts";
+import { MSG_SELECT, rowToMessage, rowToMessageDeliveryAttempt } from "./mappers.ts";
+import { getMessage } 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 queueDepthLimit(target: string): number {
+  const row = getDb().query("SELECT value FROM config WHERE namespace = 'system' AND key = 'message-queue'").get() as { value?: string } | undefined;
+  const parsed = row?.value ? parseJson<Record<string, unknown>>(row.value, {}) : {};
+  const perTarget = parsed?.maxDepthPerTarget;
+  if (typeof perTarget === "number" && Number.isSafeInteger(perTarget) && perTarget > 0) return perTarget;
+  const targetLimits = parsed?.targetLimits;
+  if (targetLimits && typeof targetLimits === "object" && !Array.isArray(targetLimits)) {
+    const value = (targetLimits as Record<string, unknown>)[target];
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return value;
+  }
+  return 100;
+}
+
+export function enforceQueueLimit(target: string): void {
+  const limit = queueDepthLimit(target);
+  const rows = getDb().query(`
+      SELECT id FROM messages
+      WHERE to_target = ? AND delivery_status = 'queued'
+      ORDER BY queued_at DESC, id DESC
+      LIMIT -1 OFFSET ?
+  `).all(target, limit) as Array<{ id: number }>;
+  if (rows.length === 0) return;
+  const now = Date.now();
+  getDb().transaction(() => {
+    for (const row of rows) {
+      insertMessageDeliveryAttempt(row.id, {
+        action: "mark-dead",
+        status: "dead",
+        error: "queue depth limit exceeded",
+        poisonReason: "queue depth limit exceeded",
+      }, now);
+      setMessageDeliveryState(row.id, {
+        status: "dead",
+        error: "queue depth limit exceeded",
+        poisonReason: "queue depth limit exceeded",
+        nextRetryAt: null,
+      }, now);
+    }
+  })();
+}
+
+export function isDeliveryAgent(agent: AgentCard): boolean {
+  return agent.status !== "offline" &&
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.kind !== "channel" &&
+    agent.meta?.kind !== "channel";
+}
+
+export 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")
+  ));
+}
+
+export 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];
+}
+
+export function matchingDeliveryAgents(target: string): AgentCard[] {
+  if (!target) return [];
+  const candidates = listAgents().filter(isDeliveryAgent);
+  if (target === "broadcast") return candidates;
+  const direct = getAgent(target);
+  if (direct) return isDeliveryAgent(direct) ? [direct] : [];
+  if (target.startsWith("tag:")) {
+    const tag = target.slice(4);
+    return candidates.filter((agent) => agent.tags.includes(tag));
+  }
+  if (target.startsWith("cap:")) {
+    const cap = target.slice(4);
+    return candidates.filter((agent) => agent.capabilities.includes(cap));
+  }
+  if (target.startsWith("label:")) {
+    const label = target.slice(6);
+    return candidates.filter((agent) => agent.label === label);
+  }
+  return [];
+}
+
+
+export function getMessageDeliveryAttempts(messageId: number, limit = 50): MessageDeliveryAttempt[] {
+  const safeLimit = Math.min(Math.max(limit, 1), 200);
+  return (getDb().query(`
+    SELECT * FROM message_delivery_attempts
+    WHERE message_id = ?
+    ORDER BY created_at DESC, id DESC
+    LIMIT ?
+  `).all(messageId, safeLimit) as any[]).map(rowToMessageDeliveryAttempt);
+}
+
+export function insertMessageDeliveryAttempt(
+  messageId: number,
+  input: {
+    agentId?: string;
+    action?: MessageDeliveryAttempt["action"];
+    status: MessageDeliveryStatus;
+    error?: string;
+    nextRetryAt?: number;
+    poisonReason?: string;
+  },
+  now: number,
+): void {
+  getDb().query(`
+    INSERT INTO message_delivery_attempts (message_id, agent_id, action, status, error, next_retry_at, poison_reason, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    messageId,
+    input.agentId ?? null,
+    input.action ?? "attempt",
+    input.status,
+    input.error ?? null,
+    input.nextRetryAt ?? null,
+    input.poisonReason ?? null,
+    now,
+  );
+}
+
+export function setMessageDeliveryState(
+  messageId: number,
+  input: {
+    status: MessageDeliveryStatus;
+    error?: string | null;
+    nextRetryAt?: number | null;
+    poisonReason?: string | null;
+    incrementAttempts?: boolean;
+  },
+  now: number,
+): boolean {
+  return getDb().query(`
+    UPDATE messages
+    SET delivery_status = ?,
+        delivery_attempts = delivery_attempts + ?,
+        delivery_last_error = ?,
+        delivery_next_retry_at = ?,
+        delivery_poison_reason = ?,
+        delivery_updated_at = ?
+    WHERE id = ?
+  `).run(
+    input.status,
+    input.incrementAttempts ? 1 : 0,
+    input.error ?? null,
+    input.nextRetryAt ?? null,
+    input.poisonReason ?? null,
+    now,
+    messageId,
+  ).changes > 0;
+}
+
+export function recordMessageDeliveryAttempt(messageId: number, input: {
+  agentId?: string;
+  status: MessageDeliveryStatus;
+  error?: string;
+  nextRetryAt?: number;
+  poisonReason?: string;
+}): { ok: boolean; error?: string; message?: Message; attempts?: MessageDeliveryAttempt[] } {
+  if (!getMessage(messageId)) return { ok: false, error: "message not found" };
+  const now = Date.now();
+  getDb().transaction(() => {
+    insertMessageDeliveryAttempt(messageId, { ...input, action: "attempt" }, now);
+    setMessageDeliveryState(messageId, {
+      status: input.status,
+      error: input.status === "delivered" ? null : input.error ?? null,
+      nextRetryAt: input.status === "delivered" ? null : input.nextRetryAt ?? null,
+      poisonReason: input.status === "dead" ? input.poisonReason ?? input.error ?? null : null,
+      incrementAttempts: true,
+    }, now);
+  })();
+  return { ok: true, message: getMessage(messageId)!, attempts: getMessageDeliveryAttempts(messageId) };
+}
+
+export function applyMessageDeliveryAction(messageId: number, input: {
+  action: "retry-now" | "mark-dead" | "clear";
+  reason?: string;
+  agentId?: string;
+}): { ok: boolean; error?: string; message?: Message; attempts?: MessageDeliveryAttempt[] } {
+  if (!getMessage(messageId)) return { ok: false, error: "message not found" };
+  const now = Date.now();
+  const status: MessageDeliveryStatus =
+    input.action === "retry-now" ? "pending" :
+    input.action === "mark-dead" ? "dead" :
+    "delivered";
+  const reason = input.reason?.trim() || undefined;
+  getDb().transaction(() => {
+    insertMessageDeliveryAttempt(messageId, {
+      agentId: input.agentId,
+      action: input.action,
+      status,
+      error: input.action === "mark-dead" ? reason : undefined,
+      poisonReason: input.action === "mark-dead" ? reason : undefined,
+    }, now);
+    setMessageDeliveryState(messageId, {
+      status,
+      error: input.action === "mark-dead" ? reason ?? "marked dead" : null,
+      nextRetryAt: null,
+      poisonReason: input.action === "mark-dead" ? reason ?? "marked dead" : null,
+      incrementAttempts: false,
+    }, now);
+  })();
+  return { ok: true, message: getMessage(messageId)!, attempts: getMessageDeliveryAttempts(messageId) };
+}
+
+export function getMessageDeliveryStatus(id: number): Pick<Message, "id" | "to" | "deliveryStatus" | "deliveryAttempts" | "deliveryLastError" | "deliveryNextRetryAt" | "deliveryPoisonReason" | "deliveryUpdatedAt" | "queuedAt" | "maxAgeSeconds" | "resolvedToAgent"> & { attempts: MessageDeliveryAttempt[] } | null {
+  const message = getMessage(id);
+  if (!message) return null;
+  return {
+    id: message.id,
+    to: message.to,
+    deliveryStatus: message.deliveryStatus,
+    deliveryAttempts: message.deliveryAttempts,
+    deliveryLastError: message.deliveryLastError,
+    deliveryNextRetryAt: message.deliveryNextRetryAt,
+    deliveryPoisonReason: message.deliveryPoisonReason,
+    deliveryUpdatedAt: message.deliveryUpdatedAt,
+    queuedAt: message.queuedAt,
+    maxAgeSeconds: message.maxAgeSeconds,
+    resolvedToAgent: message.resolvedToAgent,
+    attempts: getMessageDeliveryAttempts(id),
+  };
+}
+
+export function listQueuedMessages(target: string, limit = 100): Message[] {
+  const safeLimit = Math.min(Math.max(limit, 1), 500);
+  return (getDb().query(`
+    ${MSG_SELECT}
+    WHERE m.to_target = ? AND m.delivery_status = 'queued'
+    ORDER BY m.queued_at ASC, m.id ASC
+    LIMIT ?
+  `).all(target, safeLimit) as any[]).map(rowToMessage);
+}
+
+export function resolveQueuedPolicyMessages(policyName: string, agentId: string): Message[] {
+  const target = `policy:${policyName}`;
+  const rows = getDb().query(`
+    SELECT m.id
+    FROM messages m
+    WHERE m.to_target = ?
+      AND m.delivery_status IN ('queued', 'pending')
+      AND NOT EXISTS (SELECT 1 FROM message_reads mr WHERE mr.message_id = m.id)
+      AND (
+        m.delivery_status = 'queued'
+        OR m.resolved_to_agent IS NULL
+        OR m.resolved_to_agent != ?
+      )
+    ORDER BY COALESCE(m.queued_at, m.created_at) ASC, m.id ASC
+  `).all(target, agentId) as Array<{ id: number }>;
+  if (rows.length === 0) return [];
+  const ids = rows.map((row) => row.id);
+  const placeholders = ids.map(() => "?").join(",");
+  getDb().query(`
+    UPDATE messages
+    SET delivery_status = 'pending',
+        resolved_to_agent = ?,
+        delivery_attempts = delivery_attempts + 1,
+        delivery_last_error = NULL,
+        delivery_next_retry_at = NULL,
+        delivery_poison_reason = NULL,
+        delivery_updated_at = ?
+    WHERE id IN (${placeholders})
+  `).run(agentId, Date.now(), ...ids);
+  const now = Date.now();
+  for (const id of ids) {
+    insertMessageDeliveryAttempt(id, { agentId, status: "pending" }, now);
+  }
+  return ids.map((id) => getMessage(id)).filter((message): message is Message => Boolean(message));
+}
+
+export function expireQueuedMessages(now: number = Date.now()): Message[] {
+  const rows = getDb().query(`
+    SELECT id FROM messages
+    WHERE delivery_status = 'queued'
+      AND queued_at IS NOT NULL
+      AND coalesce(max_age_seconds, 86400) >= 0
+      AND queued_at + (coalesce(max_age_seconds, 86400) * 1000) <= ?
+  `).all(now) as Array<{ id: number }>;
+  if (rows.length === 0) return [];
+  const ids = rows.map((row) => row.id);
+  getDb().transaction(() => {
+    for (const id of ids) {
+      insertMessageDeliveryAttempt(id, {
+        action: "mark-dead",
+        status: "dead",
+        error: "queued message expired",
+        poisonReason: "queued message expired",
+      }, now);
+      setMessageDeliveryState(id, {
+        status: "dead",
+        error: "queued message expired",
+        poisonReason: "queued message expired",
+        nextRetryAt: null,
+      }, now);
+    }
+  })();
+  return ids.map((id) => getMessage(id)).filter((message): message is Message => Boolean(message));
+}
+

package/src/db/inbox.ts

@@ -0,0 +1,249 @@
+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 {
+  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 { ValidationError, getDb } from "./connection.ts";
+import { rowToChatHistoryImport, rowToChatHistoryImportEntry, rowToInboxDraft, rowToInboxThreadState } from "./mappers.ts";
+import { getMessage } 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 getInboxState(operatorId: string): InboxState {
+  const threads = (getDb().query(
+    "SELECT * FROM inbox_thread_state WHERE operator_id = ? ORDER BY updated_at DESC",
+  ).all(operatorId) as any[]).map(rowToInboxThreadState);
+  const drafts = (getDb().query(
+    "SELECT * FROM inbox_drafts WHERE operator_id = ? ORDER BY updated_at DESC",
+  ).all(operatorId) as any[]).map(rowToInboxDraft);
+  return { operatorId, threads, drafts };
+}
+
+export function setInboxThreadState(input: {
+  operatorId: string;
+  peerId: string;
+  readCursorMessageId?: number | null;
+  archivedAtMessageId?: number | null;
+}): InboxThreadState {
+  const now = Date.now();
+  const current = getDb().query(
+    "SELECT * FROM inbox_thread_state WHERE operator_id = ? AND peer_id = ?",
+  ).get(input.operatorId, input.peerId) as any | undefined;
+
+  const readCursorMessageId = Object.prototype.hasOwnProperty.call(input, "readCursorMessageId")
+    ? input.readCursorMessageId ?? null
+    : current?.read_cursor_message_id ?? null;
+  const archivedAtMessageId = Object.prototype.hasOwnProperty.call(input, "archivedAtMessageId")
+    ? input.archivedAtMessageId ?? null
+    : current?.archived_at_message_id ?? null;
+
+  getDb().query(`
+    INSERT INTO inbox_thread_state (operator_id, peer_id, read_cursor_message_id, archived_at_message_id, updated_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(operator_id, peer_id) DO UPDATE SET
+      read_cursor_message_id = excluded.read_cursor_message_id,
+      archived_at_message_id = excluded.archived_at_message_id,
+      updated_at = excluded.updated_at
+  `).run(input.operatorId, input.peerId, readCursorMessageId, archivedAtMessageId, now);
+
+  return rowToInboxThreadState(getDb().query(
+    "SELECT * FROM inbox_thread_state WHERE operator_id = ? AND peer_id = ?",
+  ).get(input.operatorId, input.peerId));
+}
+
+export function setInboxDraft(input: {
+  operatorId: string;
+  peerId: string;
+  body: string;
+  subject?: string | null;
+  channel?: string | null;
+}): InboxDraft {
+  const now = Date.now();
+  getDb().query(`
+    INSERT INTO inbox_drafts (operator_id, peer_id, body, subject, channel, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(operator_id, peer_id) DO UPDATE SET
+      body = excluded.body,
+      subject = excluded.subject,
+      channel = excluded.channel,
+      updated_at = excluded.updated_at
+  `).run(input.operatorId, input.peerId, input.body, input.subject ?? null, input.channel ?? null, now);
+
+  return rowToInboxDraft(getDb().query(
+    "SELECT * FROM inbox_drafts WHERE operator_id = ? AND peer_id = ?",
+  ).get(input.operatorId, input.peerId));
+}
+
+export function deleteInboxDraft(operatorId: string, peerId: string): boolean {
+  return getDb().query("DELETE FROM inbox_drafts WHERE operator_id = ? AND peer_id = ?").run(operatorId, peerId).changes > 0;
+}
+
+export function createChatHistoryImport(input: {
+  targetAgentId?: string;
+  targetSpawnRequestId?: string;
+  sourcePeerId: string;
+  sourceAgentId?: string;
+  sourceThreadId?: string;
+  sourceAgentLabel?: string;
+  importedBy?: string;
+  messageIds: number[];
+}): ChatHistoryImport {
+  if (!input.targetAgentId && !input.targetSpawnRequestId) {
+    throw new ValidationError("targetAgentId or targetSpawnRequestId required");
+  }
+  if (!input.sourcePeerId.trim()) throw new ValidationError("sourcePeerId required");
+  const uniqueMessageIds = [...new Set(input.messageIds.map((id) => Number(id)).filter((id) => Number.isInteger(id) && id > 0))];
+  if (uniqueMessageIds.length === 0) throw new ValidationError("messageIds required");
+  if (uniqueMessageIds.length > 500) throw new ValidationError("messageIds max 500");
+
+  const messages = uniqueMessageIds.map((id) => getMessage(id));
+  if (messages.some((message) => !message)) throw new ValidationError("message not found");
+  const orderedMessages = (messages as Message[]).sort((a, b) => a.id - b.id);
+
+  const id = randomUUID();
+  const now = Date.now();
+  getDb().transaction(() => {
+    getDb().query(`
+      INSERT INTO chat_history_imports (
+        id, target_agent_id, target_spawn_request_id, source_peer_id, source_agent_id,
+        source_thread_id, source_agent_label, imported_by, imported_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id,
+      input.targetAgentId ?? null,
+      input.targetSpawnRequestId ?? null,
+      input.sourcePeerId,
+      input.sourceAgentId ?? null,
+      input.sourceThreadId ?? null,
+      input.sourceAgentLabel ?? null,
+      input.importedBy ?? "user",
+      now,
+    );
+
+    const insertEntry = getDb().query(`
+      INSERT INTO chat_history_import_entries (
+        import_id, position, original_message_id, original_from, original_to, original_created_at, message_snapshot
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    orderedMessages.forEach((message, index) => {
+      insertEntry.run(
+        id,
+        index,
+        message.id,
+        message.from,
+        message.to,
+        Number(message.createdAt),
+        JSON.stringify(message),
+      );
+    });
+  })();
+
+  return getChatHistoryImport(id)!;
+}
+
+export function getChatHistoryImport(id: string): ChatHistoryImport | null {
+  const row = getDb().query("SELECT * FROM chat_history_imports WHERE id = ?").get(id) as any | undefined;
+  if (!row) return null;
+  const entries = (getDb().query(
+    "SELECT * FROM chat_history_import_entries WHERE import_id = ? ORDER BY position ASC",
+  ).all(id) as any[]).map(rowToChatHistoryImportEntry);
+  return rowToChatHistoryImport(row, entries);
+}
+
+export function listChatHistoryImports(input: {
+  targetAgentId?: string;
+  targetSpawnRequestId?: string;
+  limit?: number;
+} = {}): ChatHistoryImport[] {
+  const conditions: string[] = [];
+  const params: any[] = [];
+  if (input.targetAgentId) {
+    conditions.push("target_agent_id = ?");
+    params.push(input.targetAgentId);
+  }
+  if (input.targetSpawnRequestId) {
+    conditions.push("target_spawn_request_id = ?");
+    params.push(input.targetSpawnRequestId);
+  }
+  const limit = Math.max(1, Math.min(input.limit ?? 100, 500));
+  const where = conditions.length ? `WHERE ${conditions.join(" OR ")}` : "";
+  const rows = getDb().query(`SELECT * FROM chat_history_imports ${where} ORDER BY imported_at ASC LIMIT ?`).all(...params, limit) as any[];
+  return rows.map((row) => {
+    const entries = (getDb().query(
+      "SELECT * FROM chat_history_import_entries WHERE import_id = ? ORDER BY position ASC",
+    ).all(row.id) as any[]).map(rowToChatHistoryImportEntry);
+    return rowToChatHistoryImport(row, entries);
+  });
+}
+

package/src/db/index.ts

@@ -0,0 +1,23 @@
+// Barrel for the db/ package. src/db.ts re-exports this, preserving the
+// historical `import { ... } from "./db"` surface while the implementation
+// lives in per-domain modules. See docs/architecture.md (DB schema) and #298.
+export * from "./connection.ts";
+export * from "./schema.ts";
+export * from "./migrations.ts";
+export * from "./mappers.ts";
+export * from "./channels.ts";
+export * from "./agents.ts";
+export * from "./agent-search.ts";
+export * from "./tasks.ts";
+export * from "./integrations.ts";
+export * from "./pairs.ts";
+export * from "./artifacts.ts";
+export * from "./messages.ts";
+export * from "./delivery.ts";
+export * from "./message-reads.ts";
+export * from "./inbox.ts";
+export * from "./activity.ts";
+export * from "./stats.ts";
+export * from "./orchestrators.ts";
+export * from "./workspaces.ts";
+export * from "./merge-lease.ts";