agent-relay-server 0.33.0 → 0.34.0

package/src/db/schema.ts

@@ -0,0 +1,758 @@
+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 { applyConnectionPragmas, getDb, setDb } from "./connection.ts";
+import { applyMigrations } from "./migrations.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";
+
+// Schema bootstrap. initDb opens the handle, applies connection pragmas, creates
+// the full table/index catalog (the inline DDL below — kept in one place so the
+// schema reads top-to-bottom), then hands off to applyMigrations() for the
+// incremental ALTER/backfill history. The DDL block is declarative and large by
+// nature; that is why this file carries a file-size-ratchet baseline.
+export function initDb(path: string = "agent-relay.db"): Database {
+  const conn = new Database(path, { create: true });
+  applyConnectionPragmas(conn);
+  setDb(conn);
+
+  getDb().run(`
+    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,
+      capabilities TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'idle',
+      instance_id TEXT,
+      epoch INTEGER NOT NULL DEFAULT 0,
+      provider_capabilities TEXT,
+      context_state TEXT,
+      meta TEXT NOT NULL DEFAULT '{}',
+      spawned_by TEXT,
+      last_seen INTEGER NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      from_agent TEXT NOT NULL,
+      to_target TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'chat',
+      channel TEXT,
+      subject TEXT,
+      body TEXT NOT NULL,
+      thread_id INTEGER,
+      reply_to INTEGER REFERENCES messages(id),
+      reply_expected INTEGER NOT NULL DEFAULT 1,
+      claimable INTEGER NOT NULL DEFAULT 0,
+      claimed_by TEXT,
+      claimed_at INTEGER,
+      claim_expires_at INTEGER,
+      idempotency_key TEXT,
+      delivery_status TEXT NOT NULL DEFAULT 'pending',
+      delivery_attempts INTEGER NOT NULL DEFAULT 0,
+      delivery_last_error TEXT,
+      delivery_next_retry_at INTEGER,
+      delivery_poison_reason TEXT,
+      delivery_updated_at INTEGER,
+      queued_at INTEGER,
+      max_age_seconds INTEGER,
+      resolved_to_agent TEXT,
+      payload TEXT NOT NULL DEFAULT '{}',
+      meta TEXT NOT NULL DEFAULT '{}',
+      read_by TEXT NOT NULL DEFAULT '[]',
+      created_at INTEGER NOT NULL,
+      occurred_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_msg_to ON messages(to_target);
+    CREATE INDEX IF NOT EXISTS idx_msg_created ON messages(created_at);
+    CREATE INDEX IF NOT EXISTS idx_msg_channel ON messages(channel);
+    -- (reply_to, from_agent) powers the reply-obligation NOT EXISTS subquery in
+    -- listPendingReplyObligations. Without it that subquery full-scans messages
+    -- per candidate row (O(n^2)): ~8.6s at 4k rows, which blew the 5s Stop-hook
+    -- timeout and wedged turns in "busy" (#199).
+    CREATE INDEX IF NOT EXISTS idx_msg_reply_to ON messages(reply_to, from_agent);
+
+    CREATE TABLE IF NOT EXISTS message_reactions (
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      actor_id TEXT NOT NULL,
+      emoji TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (message_id, actor_id, emoji)
+    );
+    CREATE INDEX IF NOT EXISTS idx_message_reactions_message ON message_reactions(message_id);
+
+    CREATE TABLE IF NOT EXISTS context_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      utilization REAL NOT NULL,
+      lifecycle_state TEXT NOT NULL,
+      tokens_used INTEGER,
+      tokens_max INTEGER,
+      source TEXT NOT NULL,
+      confidence TEXT NOT NULL,
+      context_state TEXT NOT NULL,
+      captured_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_context_snapshots_agent_time ON context_snapshots(agent_id, captured_at DESC);
+
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '[]',
+      visibility TEXT NOT NULL DEFAULT 'project',
+      sensitivity TEXT NOT NULL DEFAULT 'normal',
+      confidence TEXT NOT NULL DEFAULT 'reported',
+      redaction_state TEXT NOT NULL DEFAULT 'raw',
+      relevance_score REAL DEFAULT 1.0,
+      source_agent TEXT,
+      source_task INTEGER REFERENCES tasks(id) ON DELETE SET NULL,
+      created_by TEXT,
+      content_hash TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      access_count INTEGER DEFAULT 0,
+      last_accessed_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+    CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope);
+    CREATE INDEX IF NOT EXISTS idx_memories_tags ON memories(tags);
+    CREATE INDEX IF NOT EXISTS idx_memories_relevance ON memories(relevance_score);
+    CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at);
+
+    CREATE TABLE IF NOT EXISTS agent_active_memories (
+      agent_id TEXT NOT NULL,
+      memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+      loaded_at INTEGER NOT NULL,
+      PRIMARY KEY (agent_id, memory_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_active_memories_agent ON agent_active_memories(agent_id);
+
+    CREATE TABLE IF NOT EXISTS artifact_blobs (
+      digest TEXT PRIMARY KEY,
+      storage_uri TEXT NOT NULL,
+      media_type TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS artifacts (
+      id TEXT PRIMARY KEY,
+      blob_digest TEXT NOT NULL REFERENCES artifact_blobs(digest),
+      media_type TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'other',
+      filename TEXT,
+      size INTEGER NOT NULL,
+      visibility TEXT NOT NULL DEFAULT 'project',
+      sensitivity TEXT NOT NULL DEFAULT 'normal',
+      created_by TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER,
+      metadata TEXT NOT NULL DEFAULT '{}'
+    );
+    CREATE INDEX IF NOT EXISTS idx_artifacts_blob ON artifacts(blob_digest);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_created ON artifacts(created_at);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_expires ON artifacts(expires_at);
+    CREATE INDEX IF NOT EXISTS idx_artifacts_created_by ON artifacts(created_by);
+
+    CREATE TABLE IF NOT EXISTS artifact_links (
+      id TEXT PRIMARY KEY,
+      artifact_id TEXT NOT NULL REFERENCES artifacts(id) ON DELETE CASCADE,
+      entity_type TEXT NOT NULL,
+      entity_id TEXT NOT NULL,
+      role TEXT,
+      title TEXT,
+      created_by TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      UNIQUE (artifact_id, entity_type, entity_id, role)
+    );
+    CREATE INDEX IF NOT EXISTS idx_artifact_links_entity ON artifact_links(entity_type, entity_id);
+    CREATE INDEX IF NOT EXISTS idx_artifact_links_artifact ON artifact_links(artifact_id);
+
+    CREATE TABLE IF NOT EXISTS message_delivery_attempts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      agent_id TEXT,
+      action TEXT NOT NULL DEFAULT 'attempt',
+      status TEXT NOT NULL,
+      error TEXT,
+      next_retry_at INTEGER,
+      poison_reason TEXT,
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_mda_message ON message_delivery_attempts(message_id, created_at DESC);
+
+    CREATE TABLE IF NOT EXISTS config (
+      namespace TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_by TEXT,
+      PRIMARY KEY (namespace, key)
+    );
+
+    CREATE TABLE IF NOT EXISTS config_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      namespace TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+      changed_by TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_config_history_key ON config_history(namespace, key, version);
+
+    CREATE TABLE IF NOT EXISTS managed_agent_state (
+      policy_name TEXT PRIMARY KEY,
+      status TEXT NOT NULL,
+      agent_id TEXT,
+      orchestrator_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      tmux_session TEXT,
+      spawn_request_id TEXT,
+      workspace_id TEXT,
+      workspace_path TEXT,
+      workspace_branch TEXT,
+      last_spawn_at INTEGER,
+      last_stop_at INTEGER,
+      healthy_since INTEGER,
+      restart_count INTEGER NOT NULL DEFAULT 0,
+      consecutive_failures INTEGER NOT NULL DEFAULT 0,
+      backoff_until INTEGER,
+      last_error TEXT,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_managed_agent_state_status ON managed_agent_state(status);
+    CREATE INDEX IF NOT EXISTS idx_managed_agent_state_agent ON managed_agent_state(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_managed_agent_state_spawn_request ON managed_agent_state(policy_name, spawn_request_id);
+
+    CREATE TABLE IF NOT EXISTS workspaces (
+      id TEXT PRIMARY KEY,
+      repo_root TEXT NOT NULL,
+      source_cwd TEXT NOT NULL,
+      worktree_path TEXT NOT NULL,
+      branch TEXT,
+      base_ref TEXT,
+      base_sha TEXT,
+      mode TEXT NOT NULL,
+      requested_mode TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      owner_agent_id TEXT,
+      owner_policy_name TEXT,
+      owner_automation_run_id TEXT,
+      steward_agent_id TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      ready_at INTEGER,
+      cleaned_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_workspaces_repo_status ON workspaces(repo_root, status);
+    CREATE INDEX IF NOT EXISTS idx_workspaces_owner_agent ON workspaces(owner_agent_id);
+    CREATE INDEX IF NOT EXISTS idx_workspaces_policy ON workspaces(owner_policy_name);
+
+    -- Persistent per-repo steward record. Keyed to the repo, not a live agent, so
+    -- it survives a full all-agents-offline gap: steward_agent_id goes NULL
+    -- (dormant) while last_steward_agent_id preserves continuity, and the row is
+    -- re-filled when an agent rejoins the repo. This is the durable backing store
+    -- the steward column on workspace rows mirrors for display/maintenance.
+    CREATE TABLE IF NOT EXISTS repo_stewards (
+      repo_root TEXT PRIMARY KEY,
+      steward_agent_id TEXT,
+      last_steward_agent_id TEXT,
+      elected_at INTEGER,
+      updated_at INTEGER NOT NULL
+    );
+
+    -- Per-repo merge serialization lease. Exactly one base merge may be in flight
+    -- per repo; a second merge request is rejected until the holder settles or the
+    -- lease expires. Atomicity comes from the repo_root PRIMARY KEY + expiry guard.
+    CREATE TABLE IF NOT EXISTS workspace_merge_leases (
+      repo_root TEXT PRIMARY KEY,
+      workspace_id TEXT NOT NULL,
+      command_id TEXT,
+      holder TEXT,
+      acquired_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      status TEXT NOT NULL,
+      target TEXT NOT NULL,
+      channel TEXT,
+      dedupe_key TEXT,
+      external_url TEXT,
+      occurrence_count INTEGER NOT NULL DEFAULT 1,
+      claimed_by TEXT,
+      claimed_at INTEGER,
+      claim_expires_at INTEGER,
+      message_id INTEGER REFERENCES messages(id) ON DELETE SET NULL,
+      result TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      last_seen_at INTEGER NOT NULL
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_source_dedupe ON tasks(source, dedupe_key) WHERE dedupe_key IS NOT NULL AND status NOT IN ('done', 'failed', 'canceled');
+    CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_target ON tasks(target);
+    CREATE INDEX IF NOT EXISTS idx_tasks_updated ON tasks(updated_at);
+
+    CREATE TABLE IF NOT EXISTS automations (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      schedule TEXT NOT NULL,
+      timezone TEXT NOT NULL,
+      next_run_at INTEGER,
+      catch_up_policy TEXT NOT NULL,
+      concurrency_policy TEXT NOT NULL,
+      orchestrator_id TEXT NOT NULL,
+      target_policy TEXT NOT NULL,
+      task_template TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_automations_enabled_next_run ON automations(enabled, next_run_at);
+
+    CREATE TABLE IF NOT EXISTS automation_runs (
+      id TEXT PRIMARY KEY,
+      automation_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      scheduled_for INTEGER NOT NULL,
+      started_at INTEGER,
+      finished_at INTEGER,
+      orchestrator_id TEXT NOT NULL,
+      target_agent_id TEXT,
+      spawned_agent_id TEXT,
+      task_id INTEGER,
+      message_id INTEGER,
+      control_message_id INTEGER,
+      error TEXT,
+      result TEXT,
+      meta TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      shutdown_requested_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_automation ON automation_runs(automation_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_status ON automation_runs(status);
+    CREATE INDEX IF NOT EXISTS idx_automation_runs_task ON automation_runs(task_id);
+
+    CREATE TABLE IF NOT EXISTS task_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      source TEXT NOT NULL,
+      type TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS task_callback_deliveries (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      url TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      status TEXT NOT NULL,
+      attempts INTEGER NOT NULL DEFAULT 0,
+      last_error TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS pairs (
+      id TEXT PRIMARY KEY,
+      requester_id TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      objective TEXT,
+      meta TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      accepted_at INTEGER,
+      ended_at INTEGER,
+      ended_by TEXT,
+      last_message_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_pairs_requester ON pairs(requester_id);
+    CREATE INDEX IF NOT EXISTS idx_pairs_target ON pairs(target_id);
+    CREATE INDEX IF NOT EXISTS idx_pairs_status ON pairs(status);
+
+    CREATE TABLE IF NOT EXISTS inbox_thread_state (
+      operator_id TEXT NOT NULL,
+      peer_id TEXT NOT NULL,
+      read_cursor_message_id INTEGER,
+      archived_at_message_id INTEGER,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (operator_id, peer_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_inbox_thread_operator ON inbox_thread_state(operator_id);
+
+    CREATE TABLE IF NOT EXISTS inbox_drafts (
+      operator_id TEXT NOT NULL,
+      peer_id TEXT NOT NULL,
+      body TEXT NOT NULL,
+      subject TEXT,
+      channel TEXT,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (operator_id, peer_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_inbox_drafts_operator ON inbox_drafts(operator_id);
+
+    CREATE TABLE IF NOT EXISTS chat_history_imports (
+      id TEXT PRIMARY KEY,
+      target_agent_id TEXT,
+      target_spawn_request_id TEXT,
+      source_peer_id TEXT NOT NULL,
+      source_agent_id TEXT,
+      source_thread_id TEXT,
+      source_agent_label TEXT,
+      imported_by TEXT NOT NULL,
+      imported_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_chat_history_imports_target_agent ON chat_history_imports(target_agent_id, imported_at);
+    CREATE INDEX IF NOT EXISTS idx_chat_history_imports_target_spawn ON chat_history_imports(target_spawn_request_id, imported_at);
+
+    CREATE TABLE IF NOT EXISTS chat_history_import_entries (
+      import_id TEXT NOT NULL REFERENCES chat_history_imports(id) ON DELETE CASCADE,
+      position INTEGER NOT NULL,
+      original_message_id INTEGER NOT NULL,
+      original_from TEXT NOT NULL,
+      original_to TEXT NOT NULL,
+      original_created_at INTEGER NOT NULL,
+      message_snapshot TEXT NOT NULL,
+      PRIMARY KEY (import_id, position)
+    );
+    CREATE INDEX IF NOT EXISTS idx_chat_history_import_entries_import ON chat_history_import_entries(import_id, position);
+
+    CREATE TABLE IF NOT EXISTS activity_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      operator_id TEXT,
+      client_id TEXT UNIQUE,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      meta_text TEXT,
+      icon TEXT,
+      view TEXT,
+      peer_id TEXT,
+      message_id INTEGER,
+      pair_id TEXT,
+      task_id INTEGER,
+      agent_id TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL
+    );
+    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 INDEX IF NOT EXISTS idx_activity_agent ON activity_events(agent_id, 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,
+      status TEXT NOT NULL DEFAULT 'online',
+      agent_id TEXT NOT NULL,
+      providers TEXT NOT NULL DEFAULT '[]',
+      base_dir TEXT NOT NULL,
+      env_keys TEXT NOT NULL DEFAULT '[]',
+      meta TEXT NOT NULL DEFAULT '{}',
+      managed_agents TEXT NOT NULL DEFAULT '[]',
+      last_seen INTEGER NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS bus_outbox (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      source TEXT NOT NULL,
+      subject TEXT,
+      data TEXT NOT NULL,
+      timestamp INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_outbox_type ON bus_outbox(event_type);
+    CREATE INDEX IF NOT EXISTS idx_outbox_timestamp ON bus_outbox(timestamp);
+
+    CREATE TABLE IF NOT EXISTS commands (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      source TEXT NOT NULL,
+      target TEXT NOT NULL,
+      params TEXT NOT NULL DEFAULT '{}',
+      status TEXT NOT NULL DEFAULT 'pending',
+      result TEXT,
+      error TEXT,
+      correlation_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_commands_target ON commands(target);
+    CREATE INDEX IF NOT EXISTS idx_commands_status ON commands(status);
+    CREATE INDEX IF NOT EXISTS idx_commands_created ON commands(created_at);
+    CREATE INDEX IF NOT EXISTS idx_commands_correlation ON commands(correlation_id);
+
+    CREATE TABLE IF NOT EXISTS recipe_instances (
+      id TEXT PRIMARY KEY,
+      recipe_name TEXT NOT NULL,
+      recipe_source TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      orchestrator_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      started_by TEXT NOT NULL,
+      error TEXT,
+      started_at INTEGER NOT NULL,
+      stopped_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS recipe_agent_instances (
+      instance_id TEXT NOT NULL REFERENCES recipe_instances(id) ON DELETE CASCADE,
+      role TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      status TEXT NOT NULL,
+      idx INTEGER,
+      PRIMARY KEY (instance_id, role, agent_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_recipe_instances_status ON recipe_instances(status);
+
+    CREATE TABLE IF NOT EXISTS tokens (
+      jti TEXT PRIMARY KEY,
+      sub TEXT NOT NULL,
+      role TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      profile_id TEXT,
+      issued_at INTEGER NOT NULL,
+      expires_at INTEGER,
+      revoked_at INTEGER,
+      created_by TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS token_profiles (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      role TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      constraints TEXT,
+      ttl_seconds INTEGER,
+      built_in INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      created_by TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS maintenance_jobs (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      description TEXT,
+      interval_ms INTEGER NOT NULL,
+      timeout_ms INTEGER NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      run_on_start INTEGER NOT NULL DEFAULT 0,
+      last_run_at INTEGER,
+      next_run_at INTEGER,
+      last_duration_ms INTEGER,
+      last_status TEXT NOT NULL DEFAULT 'idle',
+      last_error TEXT,
+      last_result TEXT,
+      consecutive_failures INTEGER NOT NULL DEFAULT 0,
+      lease_owner TEXT,
+      lease_until INTEGER,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_maintenance_jobs_next_run ON maintenance_jobs(enabled, next_run_at);
+
+    CREATE TABLE IF NOT EXISTS provider_model_overrides (
+      provider TEXT NOT NULL,
+      alias TEXT NOT NULL,
+      entry TEXT NOT NULL DEFAULT '{}',
+      deleted INTEGER NOT NULL DEFAULT 0,
+      updated_at INTEGER NOT NULL,
+      updated_by TEXT,
+      PRIMARY KEY (provider, alias)
+    );
+    CREATE INDEX IF NOT EXISTS idx_provider_model_overrides_provider ON provider_model_overrides(provider);
+
+    CREATE TABLE IF NOT EXISTS integration_registry (
+      name TEXT PRIMARY KEY,
+      display_name TEXT,
+      description TEXT,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      targets TEXT NOT NULL DEFAULT '[]',
+      channels TEXT NOT NULL DEFAULT '[]',
+      type TEXT,
+      icon TEXT,
+      accent_color TEXT,
+      tags TEXT NOT NULL DEFAULT '[]',
+      homepage_url TEXT,
+      repository_url TEXT,
+      docs_url TEXT,
+      manifest TEXT NOT NULL DEFAULT '{}',
+      source TEXT NOT NULL DEFAULT 'api',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      last_event_at INTEGER,
+      last_task_at INTEGER,
+      last_auth_success_at INTEGER,
+      last_auth_failure_at INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS insights_observations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      agent_id TEXT,
+      project TEXT NOT NULL DEFAULT 'unknown',
+      signal TEXT NOT NULL,
+      value TEXT NOT NULL DEFAULT '{}',
+      outcome TEXT,
+      source TEXT NOT NULL DEFAULT 'server',
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_insights_obs_project_signal ON insights_observations(project, signal, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_insights_obs_signal ON insights_observations(signal, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_insights_obs_session ON insights_observations(session_id);
+  `);
+
+  applyMigrations();
+
+  // Bootstrap planner statistics on first run (sqlite_stat1 absent means ANALYZE
+  // has never run — the planner would otherwise rely on heuristics only), then
+  // let PRAGMA optimize apply/refresh them cheaply on every startup.
+  const hasStats = getDb()
+    .query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'sqlite_stat1'")
+    .get();
+  if (!hasStats) getDb().run("ANALYZE");
+  getDb().run("PRAGMA optimize");
+
+  return conn;
+}