@desplega.ai/agent-swarm 1.49.0 → 1.52.0

package/src/be/db.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { configureDbResolver } from "../prompts/resolver";
 import type {
   ActiveSession,
   Agent,
@@ -7,6 +8,7 @@ import type {
   AgentMemory,
   AgentMemoryScope,
   AgentMemorySource,
+  AgentSkill,
   AgentStatus,
   AgentTask,
   AgentTaskSource,
@@ -24,11 +26,17 @@ import type {
   InboxMessage,
   InboxMessageStatus,
   InputValue,
+  PromptTemplate,
+  PromptTemplateHistory,
   ScheduledTask,
   Service,
   ServiceStatus,
   SessionCost,
   SessionLog,
+  Skill,
+  SkillScope,
+  SkillType,
+  SkillWithInstallInfo,
   SwarmConfig,
   SwarmRepo,
   TriggerConfig,
@@ -44,6 +52,7 @@ import type {
   WorkflowVersion,
 } from "../types";
 import { runMigrations } from "./migrations/runner";
+import { seedDefaultTemplates } from "./seed";
 
 let db: Database | null = null;
 
@@ -55,9 +64,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   db = new Database(dbPath, { create: true });
   console.log(`Database initialized at ${dbPath}`);
 
-  // Capture in local const for TypeScript (db is guaranteed non-null here)
   const database = db;
-
   database.run("PRAGMA journal_mode = WAL;");
   database.run("PRAGMA foreign_keys = ON;");
 
@@ -187,6 +194,12 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   // Backfill: Seed v1 for existing agents that don't have any context versions yet
   seedContextVersions();
 
+  // Inject DB resolver into the prompt template resolver (DI to avoid worker/API boundary violation)
+  configureDbResolver(resolvePromptTemplate);
+
+  // Seed default prompt templates from the in-memory code registry
+  seedDefaultTemplates();
+
   return db;
 }
 
@@ -2153,6 +2166,16 @@ export function getUnassignedTasksCount(): number {
   return result?.count ?? 0;
 }
 
+/** Get unassigned task IDs, ordered by priority (highest first) then creation time */
+export function getUnassignedTaskIds(limit = 10): string[] {
+  const rows = getDb()
+    .prepare<{ id: string }, [number]>(
+      "SELECT id FROM agent_tasks WHERE status = 'unassigned' ORDER BY priority DESC, createdAt ASC LIMIT ?",
+    )
+    .all(limit);
+  return rows.map((r) => r.id);
+}
+
 // ============================================================================
 // Dependency Checking
 // ============================================================================
@@ -5430,6 +5453,7 @@ export function insertActiveSession(session: {
   triggerType: string;
   inboxMessageId?: string;
   taskDescription?: string;
+  runnerSessionId?: string;
 }): ActiveSession {
   const id = crypto.randomUUID();
   const now = new Date().toISOString();
@@ -5437,10 +5461,20 @@ export function insertActiveSession(session: {
   const row = getDb()
     .prepare<
       ActiveSession,
-      [string, string, string | null, string, string | null, string | null, string, string]
+      [
+        string,
+        string,
+        string | null,
+        string,
+        string | null,
+        string | null,
+        string | null,
+        string,
+        string,
+      ]
     >(
-      `INSERT INTO active_sessions (id, agentId, taskId, triggerType, inboxMessageId, taskDescription, startedAt, lastHeartbeatAt)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `INSERT INTO active_sessions (id, agentId, taskId, triggerType, inboxMessageId, taskDescription, runnerSessionId, startedAt, lastHeartbeatAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        RETURNING *`,
     )
     .get(
@@ -5450,6 +5484,7 @@ export function insertActiveSession(session: {
       session.triggerType,
       session.inboxMessageId ?? null,
       session.taskDescription ?? null,
+      session.runnerSessionId ?? null,
       now,
       now,
     );
@@ -5502,6 +5537,30 @@ export function cleanupAgentSessions(agentId: string): number {
   return result.changes;
 }
 
+/** Update providerSessionId on an active session identified by taskId */
+export function updateActiveSessionProviderSessionId(
+  taskId: string,
+  providerSessionId: string,
+): boolean {
+  const result = getDb()
+    .prepare("UPDATE active_sessions SET providerSessionId = ? WHERE taskId = ?")
+    .run(providerSessionId, taskId);
+  return result.changes > 0;
+}
+
+/**
+ * Reassociate session logs from a runner session to a real task ID.
+ * Used when a pool task is claimed — logs were stored under a random UUID,
+ * this updates them to use the real task ID.
+ * Idempotent — safe to call multiple times.
+ */
+export function reassociateSessionLogs(runnerSessionId: string, realTaskId: string): number {
+  const result = getDb()
+    .prepare("UPDATE session_logs SET taskId = ? WHERE sessionId = ? AND taskId != ?")
+    .run(realTaskId, runnerSessionId, realTaskId);
+  return result.changes;
+}
+
 // ============================================================================
 // Heartbeat / Triage Query Functions
 // ============================================================================
@@ -5571,6 +5630,8 @@ type WorkflowRow = {
   cooldown: string | null;
   input: string | null;
   triggerSchema: string | null;
+  dir: string | null;
+  vcs_repo: string | null;
   createdByAgentId: string | null;
   createdAt: string;
   lastUpdatedAt: string;
@@ -5589,6 +5650,8 @@ function rowToWorkflow(row: WorkflowRow): Workflow {
     triggerSchema: row.triggerSchema
       ? (JSON.parse(row.triggerSchema) as Record<string, unknown>)
       : undefined,
+    dir: row.dir ?? undefined,
+    vcsRepo: row.vcs_repo ?? undefined,
     createdByAgentId: row.createdByAgentId ?? undefined,
     createdAt: row.createdAt,
     lastUpdatedAt: row.lastUpdatedAt,
@@ -5603,6 +5666,8 @@ export function createWorkflow(data: {
   cooldown?: CooldownConfig;
   input?: Record<string, InputValue>;
   triggerSchema?: Record<string, unknown>;
+  dir?: string;
+  vcsRepo?: string;
   createdByAgentId?: string;
 }): Workflow {
   const id = crypto.randomUUID();
@@ -5619,10 +5684,12 @@ export function createWorkflow(data: {
         string | null,
         string | null,
         string | null,
+        string | null,
+        string | null,
       ]
     >(
-      `INSERT INTO workflows (id, name, description, definition, triggers, cooldown, input, triggerSchema, createdByAgentId)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+      `INSERT INTO workflows (id, name, description, definition, triggers, cooldown, input, triggerSchema, dir, vcs_repo, createdByAgentId)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     )
     .get(
       id,
@@ -5633,6 +5700,8 @@ export function createWorkflow(data: {
       data.cooldown ? JSON.stringify(data.cooldown) : null,
       data.input ? JSON.stringify(data.input) : null,
       data.triggerSchema ? JSON.stringify(data.triggerSchema) : null,
+      data.dir ?? null,
+      data.vcsRepo ?? null,
       data.createdByAgentId ?? null,
     );
   if (!row) throw new Error("Failed to create workflow");
@@ -5671,6 +5740,8 @@ export function updateWorkflow(
     cooldown?: CooldownConfig | null;
     input?: Record<string, InputValue> | null;
     triggerSchema?: Record<string, unknown> | null;
+    dir?: string | null;
+    vcsRepo?: string | null;
   },
 ): Workflow | null {
   const updates: string[] = [];
@@ -5707,6 +5778,14 @@ export function updateWorkflow(
     updates.push("triggerSchema = ?");
     params.push(data.triggerSchema ? JSON.stringify(data.triggerSchema) : null);
   }
+  if (data.dir !== undefined) {
+    updates.push("dir = ?");
+    params.push(data.dir ?? null);
+  }
+  if (data.vcsRepo !== undefined) {
+    updates.push("vcs_repo = ?");
+    params.push(data.vcsRepo ?? null);
+  }
   if (updates.length === 0) return getWorkflow(id);
   updates.push("lastUpdatedAt = ?");
   params.push(new Date().toISOString());
@@ -5739,6 +5818,22 @@ export function deleteWorkflow(id: string): boolean {
   return result.changes > 0;
 }
 
+/**
+ * Find enabled workflows that have a schedule trigger matching the given scheduleId.
+ * Uses SQLite JSON functions to query into the triggers JSON array.
+ */
+export function getWorkflowsByScheduleId(scheduleId: string): Workflow[] {
+  const rows = getDb()
+    .prepare<WorkflowRow, [string]>(
+      `SELECT w.* FROM workflows w, json_each(w.triggers) AS t
+       WHERE w.enabled = 1
+         AND json_extract(t.value, '$.type') = 'schedule'
+         AND json_extract(t.value, '$.scheduleId') = ?`,
+    )
+    .all(scheduleId);
+  return rows.map(rowToWorkflow);
+}
+
 // ============================================================================
 // Workflow Run CRUD
 // ============================================================================
@@ -6138,3 +6233,1134 @@ export function getWorkflowVersion(workflowId: string, version: number): Workflo
     .get(workflowId, version);
   return row ? rowToWorkflowVersion(row) : null;
 }
+
+// ============================================================================
+// Prompt Template Operations
+// ============================================================================
+
+type PromptTemplateRow = {
+  id: string;
+  eventType: string;
+  scope: string;
+  scopeId: string | null;
+  state: string;
+  body: string;
+  isDefault: number; // SQLite boolean
+  version: number;
+  createdBy: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type PromptTemplateHistoryRow = {
+  id: string;
+  templateId: string;
+  version: number;
+  body: string;
+  state: string;
+  changedBy: string | null;
+  changedAt: string;
+  changeReason: string | null;
+};
+
+function rowToPromptTemplate(row: PromptTemplateRow): PromptTemplate {
+  return {
+    id: row.id,
+    eventType: row.eventType,
+    scope: row.scope as "global" | "agent" | "repo",
+    scopeId: row.scopeId ?? null,
+    state: row.state as "enabled" | "default_prompt_fallback" | "skip_event",
+    body: row.body,
+    isDefault: row.isDefault === 1,
+    version: row.version,
+    createdBy: row.createdBy ?? null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function rowToPromptTemplateHistory(row: PromptTemplateHistoryRow): PromptTemplateHistory {
+  return {
+    id: row.id,
+    templateId: row.templateId,
+    version: row.version,
+    body: row.body,
+    state: row.state,
+    changedBy: row.changedBy ?? null,
+    changedAt: row.changedAt,
+    changeReason: row.changeReason ?? null,
+  };
+}
+
+/**
+ * List prompt templates with optional filters.
+ */
+export function getPromptTemplates(filters?: {
+  eventType?: string;
+  scope?: string;
+  scopeId?: string;
+  isDefault?: boolean;
+}): PromptTemplate[] {
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filters?.eventType) {
+    conditions.push("eventType = ?");
+    params.push(filters.eventType);
+  }
+  if (filters?.scope) {
+    conditions.push("scope = ?");
+    params.push(filters.scope);
+  }
+  if (filters?.scopeId) {
+    conditions.push("scopeId = ?");
+    params.push(filters.scopeId);
+  }
+  if (filters?.isDefault !== undefined) {
+    conditions.push("isDefault = ?");
+    params.push(filters.isDefault ? 1 : 0);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const query = `SELECT * FROM prompt_templates ${whereClause} ORDER BY eventType ASC`;
+
+  return getDb()
+    .prepare<PromptTemplateRow, (string | number)[]>(query)
+    .all(...params)
+    .map(rowToPromptTemplate);
+}
+
+/**
+ * Get a single prompt template by ID.
+ */
+export function getPromptTemplateById(id: string): PromptTemplate | null {
+  const row = getDb()
+    .prepare<PromptTemplateRow, [string]>("SELECT * FROM prompt_templates WHERE id = ?")
+    .get(id);
+  return row ? rowToPromptTemplate(row) : null;
+}
+
+/**
+ * Upsert a prompt template. Inserts or updates by (eventType, scope, scopeId) unique constraint.
+ * Creates a history entry on both insert and update.
+ */
+export function upsertPromptTemplate(data: {
+  eventType: string;
+  scope: "global" | "agent" | "repo";
+  scopeId?: string | null;
+  state?: "enabled" | "default_prompt_fallback" | "skip_event";
+  body: string;
+  createdBy?: string | null;
+  changedBy?: string | null;
+  changeReason?: string | null;
+  isDefault?: boolean;
+}): PromptTemplate {
+  const now = new Date().toISOString();
+  const scopeId = data.scope === "global" ? null : (data.scopeId ?? null);
+  const state = data.state ?? "enabled";
+  const createdBy = data.createdBy ?? data.changedBy ?? null;
+  const changedBy = data.changedBy ?? data.createdBy ?? null;
+  const changeReason = data.changeReason ?? null;
+
+  // Manual check for existing entry because SQLite's UNIQUE constraint
+  // treats NULL != NULL, so ON CONFLICT never fires when scopeId is NULL (global scope).
+  const existing =
+    scopeId === null
+      ? getDb()
+          .prepare<PromptTemplateRow, [string, string]>(
+            "SELECT * FROM prompt_templates WHERE eventType = ? AND scope = ? AND scopeId IS NULL",
+          )
+          .get(data.eventType, data.scope)
+      : getDb()
+          .prepare<PromptTemplateRow, [string, string, string]>(
+            "SELECT * FROM prompt_templates WHERE eventType = ? AND scope = ? AND scopeId = ?",
+          )
+          .get(data.eventType, data.scope, scopeId);
+
+  let row: PromptTemplateRow | null;
+
+  if (existing) {
+    // If upserting at global scope and existing record has isDefault=true, flip it to false
+    const newIsDefault =
+      data.scope === "global" && existing.isDefault === 1 ? 0 : existing.isDefault;
+    const newVersion = existing.version + 1;
+
+    row = getDb()
+      .prepare<PromptTemplateRow, [string, string, number, number, string, string]>(
+        `UPDATE prompt_templates SET body = ?, state = ?, isDefault = ?, version = ?, updatedAt = ?
+         WHERE id = ? RETURNING *`,
+      )
+      .get(data.body, state, newIsDefault, newVersion, now, existing.id);
+
+    // Create history entry for the update
+    getDb()
+      .prepare(
+        `INSERT INTO prompt_template_history (id, templateId, version, body, state, changedBy, changedAt, changeReason)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        crypto.randomUUID(),
+        existing.id,
+        newVersion,
+        data.body,
+        state,
+        changedBy,
+        now,
+        changeReason,
+      );
+  } else {
+    const id = crypto.randomUUID();
+    row = getDb()
+      .prepare<
+        PromptTemplateRow,
+        [
+          string,
+          string,
+          string,
+          string | null,
+          string,
+          string,
+          number,
+          number,
+          string | null,
+          string,
+          string,
+        ]
+      >(
+        `INSERT INTO prompt_templates (id, eventType, scope, scopeId, state, body, isDefault, version, createdBy, createdAt, updatedAt)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+      )
+      .get(
+        id,
+        data.eventType,
+        data.scope,
+        scopeId,
+        state,
+        data.body,
+        data.isDefault ? 1 : 0,
+        1,
+        createdBy,
+        now,
+        now,
+      );
+
+    // Create history entry for the insert
+    getDb()
+      .prepare(
+        `INSERT INTO prompt_template_history (id, templateId, version, body, state, changedBy, changedAt, changeReason)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        crypto.randomUUID(),
+        id,
+        1,
+        data.body,
+        state,
+        changedBy,
+        now,
+        changeReason ?? "Initial creation",
+      );
+  }
+
+  if (!row) throw new Error("Failed to upsert prompt template");
+  return rowToPromptTemplate(row);
+}
+
+/**
+ * Delete a prompt template by ID. Guards against deleting default templates.
+ * Does NOT delete history rows (intentional for audit trail).
+ */
+export function deletePromptTemplate(id: string): boolean {
+  const existing = getDb()
+    .prepare<PromptTemplateRow, [string]>("SELECT * FROM prompt_templates WHERE id = ?")
+    .get(id);
+
+  if (!existing) return false;
+  if (existing.isDefault === 1) {
+    throw new Error(
+      "Cannot delete a default prompt template. Use resetPromptTemplateToDefault instead.",
+    );
+  }
+
+  const result = getDb().run("DELETE FROM prompt_templates WHERE id = ?", [id]);
+  return result.changes > 0;
+}
+
+/**
+ * Reset a prompt template to its default state.
+ * Sets body to defaultBody, isDefault=true, state='enabled', bumps version.
+ */
+export function resetPromptTemplateToDefault(id: string, defaultBody: string): PromptTemplate {
+  const now = new Date().toISOString();
+  const existing = getDb()
+    .prepare<PromptTemplateRow, [string]>("SELECT * FROM prompt_templates WHERE id = ?")
+    .get(id);
+
+  if (!existing) throw new Error(`Prompt template ${id} not found`);
+
+  const newVersion = existing.version + 1;
+
+  const row = getDb()
+    .prepare<PromptTemplateRow, [string, number, string, string]>(
+      `UPDATE prompt_templates SET body = ?, state = 'enabled', isDefault = 1, version = ?, updatedAt = ?
+       WHERE id = ? RETURNING *`,
+    )
+    .get(defaultBody, newVersion, now, id);
+
+  if (!row) throw new Error("Failed to reset prompt template to default");
+
+  // Create history entry
+  getDb()
+    .prepare(
+      `INSERT INTO prompt_template_history (id, templateId, version, body, state, changedBy, changedAt, changeReason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      crypto.randomUUID(),
+      id,
+      newVersion,
+      defaultBody,
+      "enabled",
+      null,
+      now,
+      "Reset to default",
+    );
+
+  return rowToPromptTemplate(row);
+}
+
+/**
+ * Get version history for a prompt template, ordered by version DESC.
+ */
+export function getPromptTemplateHistory(templateId: string): PromptTemplateHistory[] {
+  return getDb()
+    .prepare<PromptTemplateHistoryRow, [string]>(
+      "SELECT * FROM prompt_template_history WHERE templateId = ? ORDER BY version DESC",
+    )
+    .all(templateId)
+    .map(rowToPromptTemplateHistory);
+}
+
+/**
+ * Resolve the best prompt template for a given eventType using scope precedence.
+ *
+ * Two-pass resolution:
+ *   Pass 1 (exact match): Try exact eventType at agent → repo → global scope.
+ *   Pass 2 (wildcard): Generate wildcards from eventType (e.g. "github.pull_request.*", "github.*")
+ *     and try each at agent → repo → global scope.
+ *
+ * Exact match at ANY scope always beats wildcard at ANY scope.
+ *
+ * State behavior:
+ *   - 'enabled': return the template
+ *   - 'skip_event': return { skip: true }
+ *   - 'default_prompt_fallback': continue to next scope level
+ */
+export function resolvePromptTemplate(
+  eventType: string,
+  agentId?: string,
+  repoId?: string,
+): { template: PromptTemplate } | { skip: true } | null {
+  // Helper to look up a template at a specific scope
+  const lookupAtScope = (
+    et: string,
+    scope: "global" | "agent" | "repo",
+    scopeId: string | null,
+  ): PromptTemplateRow | undefined => {
+    if (scopeId === null) {
+      return (
+        getDb()
+          .prepare<PromptTemplateRow, [string, string]>(
+            "SELECT * FROM prompt_templates WHERE eventType = ? AND scope = ? AND scopeId IS NULL",
+          )
+          .get(et, scope) ?? undefined
+      );
+    }
+    return (
+      getDb()
+        .prepare<PromptTemplateRow, [string, string, string]>(
+          "SELECT * FROM prompt_templates WHERE eventType = ? AND scope = ? AND scopeId = ?",
+        )
+        .get(et, scope, scopeId) ?? undefined
+    );
+  };
+
+  // Try resolution at the scope chain for a given eventType string
+  const tryResolve = (et: string): { template: PromptTemplate } | { skip: true } | "continue" => {
+    // Build scope chain: agent → repo → global
+    const scopeChain: Array<{ scope: "global" | "agent" | "repo"; scopeId: string | null }> = [];
+    if (agentId) scopeChain.push({ scope: "agent", scopeId: agentId });
+    if (repoId) scopeChain.push({ scope: "repo", scopeId: repoId });
+    scopeChain.push({ scope: "global", scopeId: null });
+
+    for (const { scope, scopeId } of scopeChain) {
+      const row = lookupAtScope(et, scope, scopeId);
+      if (!row) continue;
+
+      if (row.state === "enabled") {
+        return { template: rowToPromptTemplate(row) };
+      }
+      if (row.state === "skip_event") {
+        return { skip: true };
+      }
+      // default_prompt_fallback: continue to next scope
+    }
+
+    return "continue";
+  };
+
+  // Pass 1: exact match
+  const exactResult = tryResolve(eventType);
+  if (exactResult !== "continue") return exactResult;
+
+  // Pass 2: wildcard matching
+  // e.g. "github.pull_request.review_submitted" → ["github.pull_request.*", "github.*"]
+  const parts = eventType.split(".");
+  const wildcards: string[] = [];
+  for (let i = parts.length - 1; i >= 1; i--) {
+    wildcards.push(`${parts.slice(0, i).join(".")}.*`);
+  }
+
+  for (const wildcard of wildcards) {
+    const wildcardResult = tryResolve(wildcard);
+    if (wildcardResult !== "continue") return wildcardResult;
+  }
+
+  return null;
+}
+
+/**
+ * Checkout a prompt template to a specific version from history.
+ * Copies body and state from the history entry into the live record, bumps version.
+ */
+export function checkoutPromptTemplate(id: string, targetVersion: number): PromptTemplate {
+  const now = new Date().toISOString();
+
+  const existing = getDb()
+    .prepare<PromptTemplateRow, [string]>("SELECT * FROM prompt_templates WHERE id = ?")
+    .get(id);
+  if (!existing) throw new Error(`Prompt template ${id} not found`);
+
+  const historyEntry = getDb()
+    .prepare<PromptTemplateHistoryRow, [string, number]>(
+      "SELECT * FROM prompt_template_history WHERE templateId = ? AND version = ?",
+    )
+    .get(id, targetVersion);
+  if (!historyEntry)
+    throw new Error(`No history entry at version ${targetVersion} for template ${id}`);
+
+  const newVersion = existing.version + 1;
+
+  const row = getDb()
+    .prepare<PromptTemplateRow, [string, string, number, string, string]>(
+      `UPDATE prompt_templates SET body = ?, state = ?, version = ?, updatedAt = ?
+       WHERE id = ? RETURNING *`,
+    )
+    .get(historyEntry.body, historyEntry.state, newVersion, now, id);
+
+  if (!row) throw new Error("Failed to checkout prompt template");
+
+  // Create history entry for the checkout
+  getDb()
+    .prepare(
+      `INSERT INTO prompt_template_history (id, templateId, version, body, state, changedBy, changedAt, changeReason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      crypto.randomUUID(),
+      id,
+      newVersion,
+      historyEntry.body,
+      historyEntry.state,
+      null,
+      now,
+      `Checked out from version ${targetVersion}`,
+    );
+
+  return rowToPromptTemplate(row);
+}
+
+// ─── Channel Activity Cursors ─────────────────────────────────────────────────
+
+type ChannelActivityCursorRow = {
+  channelId: string;
+  lastSeenTs: string;
+  updatedAt: string;
+};
+
+export interface ChannelActivityCursor {
+  channelId: string;
+  lastSeenTs: string;
+  updatedAt: string;
+}
+
+function rowToChannelActivityCursor(row: ChannelActivityCursorRow): ChannelActivityCursor {
+  return {
+    channelId: row.channelId,
+    lastSeenTs: row.lastSeenTs,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function getAllChannelActivityCursors(): ChannelActivityCursor[] {
+  return getDb()
+    .prepare<ChannelActivityCursorRow, []>("SELECT * FROM channel_activity_cursors")
+    .all()
+    .map(rowToChannelActivityCursor);
+}
+
+export function getChannelActivityCursor(channelId: string): ChannelActivityCursor | null {
+  const row = getDb()
+    .prepare<ChannelActivityCursorRow, [string]>(
+      "SELECT * FROM channel_activity_cursors WHERE channelId = ?",
+    )
+    .get(channelId);
+  return row ? rowToChannelActivityCursor(row) : null;
+}
+
+export function upsertChannelActivityCursor(channelId: string, lastSeenTs: string): void {
+  getDb()
+    .prepare(
+      `INSERT INTO channel_activity_cursors (channelId, lastSeenTs, updatedAt)
+       VALUES (?, ?, datetime('now'))
+       ON CONFLICT(channelId) DO UPDATE SET lastSeenTs = excluded.lastSeenTs, updatedAt = excluded.updatedAt`,
+    )
+    .run(channelId, lastSeenTs);
+}
+
+// ============================================================================
+// Approval Requests
+// ============================================================================
+
+export interface ApprovalRequest {
+  id: string;
+  title: string;
+  questions: unknown[];
+  workflowRunId: string | null;
+  workflowRunStepId: string | null;
+  sourceTaskId: string | null;
+  approvers: unknown;
+  status: "pending" | "approved" | "rejected" | "timeout";
+  responses: unknown | null;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  timeoutSeconds: number | null;
+  expiresAt: string | null;
+  notificationChannels: unknown[] | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ApprovalRequestRow {
+  id: string;
+  title: string;
+  questions: string;
+  workflowRunId: string | null;
+  workflowRunStepId: string | null;
+  sourceTaskId: string | null;
+  approvers: string;
+  status: string;
+  responses: string | null;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  timeoutSeconds: number | null;
+  expiresAt: string | null;
+  notificationChannels: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function rowToApprovalRequest(row: ApprovalRequestRow): ApprovalRequest {
+  return {
+    id: row.id,
+    title: row.title,
+    questions: JSON.parse(row.questions),
+    workflowRunId: row.workflowRunId,
+    workflowRunStepId: row.workflowRunStepId,
+    sourceTaskId: row.sourceTaskId,
+    approvers: JSON.parse(row.approvers),
+    status: row.status as ApprovalRequest["status"],
+    responses: row.responses ? JSON.parse(row.responses) : null,
+    resolvedBy: row.resolvedBy,
+    resolvedAt: row.resolvedAt,
+    timeoutSeconds: row.timeoutSeconds,
+    expiresAt: row.expiresAt,
+    notificationChannels: row.notificationChannels ? JSON.parse(row.notificationChannels) : null,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function createApprovalRequest(data: {
+  id: string;
+  title: string;
+  questions: unknown[];
+  approvers: unknown;
+  workflowRunId?: string;
+  workflowRunStepId?: string;
+  sourceTaskId?: string;
+  timeoutSeconds?: number;
+  notificationChannels?: unknown[];
+}): ApprovalRequest {
+  const now = new Date().toISOString();
+  const expiresAt = data.timeoutSeconds
+    ? new Date(Date.now() + data.timeoutSeconds * 1000).toISOString()
+    : null;
+
+  const row = getDb()
+    .prepare<
+      ApprovalRequestRow,
+      [
+        string,
+        string,
+        string,
+        string | null,
+        string | null,
+        string | null,
+        string,
+        number | null,
+        string | null,
+        string | null,
+        string,
+        string,
+      ]
+    >(
+      `INSERT INTO approval_requests (id, title, questions, workflowRunId, workflowRunStepId, sourceTaskId, approvers, timeoutSeconds, expiresAt, notificationChannels, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`,
+    )
+    .get(
+      data.id,
+      data.title,
+      JSON.stringify(data.questions),
+      data.workflowRunId ?? null,
+      data.workflowRunStepId ?? null,
+      data.sourceTaskId ?? null,
+      JSON.stringify(data.approvers),
+      data.timeoutSeconds ?? null,
+      expiresAt,
+      data.notificationChannels ? JSON.stringify(data.notificationChannels) : null,
+      now,
+      now,
+    );
+
+  return rowToApprovalRequest(row!);
+}
+
+export function getApprovalRequestById(id: string): ApprovalRequest | null {
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string]>("SELECT * FROM approval_requests WHERE id = ?")
+    .get(id);
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+export function resolveApprovalRequest(
+  id: string,
+  data: {
+    status: "approved" | "rejected" | "timeout";
+    responses?: unknown;
+    resolvedBy?: string;
+  },
+): ApprovalRequest | null {
+  const now = new Date().toISOString();
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string, string | null, string | null, string, string, string]>(
+      `UPDATE approval_requests
+       SET status = ?, responses = ?, resolvedBy = ?, resolvedAt = ?, updatedAt = ?
+       WHERE id = ? AND status = 'pending'
+       RETURNING *`,
+    )
+    .get(
+      data.status,
+      data.responses ? JSON.stringify(data.responses) : null,
+      data.resolvedBy ?? null,
+      now,
+      now,
+      id,
+    );
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+export function listApprovalRequests(filters?: {
+  status?: string;
+  workflowRunId?: string;
+  limit?: number;
+}): ApprovalRequest[] {
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filters?.status) {
+    conditions.push("status = ?");
+    params.push(filters.status);
+  }
+  if (filters?.workflowRunId) {
+    conditions.push("workflowRunId = ?");
+    params.push(filters.workflowRunId);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = filters?.limit ?? 100;
+  params.push(limit);
+
+  const stmt = getDb().prepare(
+    `SELECT * FROM approval_requests ${where} ORDER BY createdAt DESC LIMIT ?`,
+  );
+  const rows = stmt.all(...params) as ApprovalRequestRow[];
+
+  return rows.map(rowToApprovalRequest);
+}
+
+export interface StuckApprovalRun {
+  runId: string;
+  stepId: string;
+  nodeId: string;
+  workflowId: string;
+  approvalId: string;
+  approvalStatus: string;
+  approvalResponses: string | null;
+  expiresAt: string | null;
+}
+
+export function getStuckApprovalRuns(): StuckApprovalRun[] {
+  return getDb()
+    .prepare<StuckApprovalRun, []>(
+      `SELECT
+        wr.id as runId,
+        wrs.id as stepId,
+        wrs.nodeId,
+        wr.workflowId,
+        ar.id as approvalId,
+        ar.status as approvalStatus,
+        ar.responses as approvalResponses,
+        ar.expiresAt
+      FROM workflow_runs wr
+      JOIN workflow_run_steps wrs ON wrs.runId = wr.id AND wrs.status = 'waiting'
+      JOIN approval_requests ar ON ar.workflowRunStepId = wrs.id
+      WHERE wr.status = 'waiting'
+        AND (ar.status IN ('approved', 'rejected', 'timeout')
+             OR (ar.status = 'pending' AND ar.expiresAt IS NOT NULL AND ar.expiresAt < datetime('now')))`,
+    )
+    .all();
+}
+
+export function getApprovalRequestByStepId(stepId: string): ApprovalRequest | null {
+  const row = getDb()
+    .prepare<ApprovalRequestRow, [string]>(
+      "SELECT * FROM approval_requests WHERE workflowRunStepId = ?",
+    )
+    .get(stepId);
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+// TODO: Wire into a periodic cron/sweep to auto-timeout expired approval requests (Phase 2)
+export function getExpiredPendingApprovals(): ApprovalRequest[] {
+  const rows = getDb()
+    .prepare<ApprovalRequestRow, []>(
+      `SELECT * FROM approval_requests
+       WHERE status = 'pending'
+         AND expiresAt IS NOT NULL
+         AND expiresAt < datetime('now')`,
+    )
+    .all();
+  return rows.map(rowToApprovalRequest);
+}
+
+// ============================================================================
+// Skills
+// ============================================================================
+
+type SkillRow = {
+  id: string;
+  name: string;
+  description: string;
+  content: string;
+  type: string;
+  scope: string;
+  ownerAgentId: string | null;
+  sourceUrl: string | null;
+  sourceRepo: string | null;
+  sourcePath: string | null;
+  sourceBranch: string;
+  sourceHash: string | null;
+  isComplex: number;
+  allowedTools: string | null;
+  model: string | null;
+  effort: string | null;
+  context: string | null;
+  agent: string | null;
+  disableModelInvocation: number;
+  userInvocable: number;
+  version: number;
+  isEnabled: number;
+  createdAt: string;
+  lastUpdatedAt: string;
+  lastFetchedAt: string | null;
+};
+
+function rowToSkill(row: SkillRow): Skill {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    content: row.content,
+    type: row.type as SkillType,
+    scope: row.scope as SkillScope,
+    ownerAgentId: row.ownerAgentId,
+    sourceUrl: row.sourceUrl,
+    sourceRepo: row.sourceRepo,
+    sourcePath: row.sourcePath,
+    sourceBranch: row.sourceBranch,
+    sourceHash: row.sourceHash,
+    isComplex: row.isComplex === 1,
+    allowedTools: row.allowedTools,
+    model: row.model,
+    effort: row.effort,
+    context: row.context,
+    agent: row.agent,
+    disableModelInvocation: row.disableModelInvocation === 1,
+    userInvocable: row.userInvocable === 1,
+    version: row.version,
+    isEnabled: row.isEnabled === 1,
+    createdAt: row.createdAt,
+    lastUpdatedAt: row.lastUpdatedAt,
+    lastFetchedAt: row.lastFetchedAt,
+  };
+}
+
+type AgentSkillRow = {
+  id: string;
+  agentId: string;
+  skillId: string;
+  isActive: number;
+  installedAt: string;
+};
+
+function rowToAgentSkill(row: AgentSkillRow): AgentSkill {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    skillId: row.skillId,
+    isActive: row.isActive === 1,
+    installedAt: row.installedAt,
+  };
+}
+
+type SkillWithInstallRow = SkillRow & { isActive: number; installedAt: string };
+
+function rowToSkillWithInstall(row: SkillWithInstallRow): SkillWithInstallInfo {
+  return {
+    ...rowToSkill(row),
+    isActive: row.isActive === 1,
+    installedAt: row.installedAt,
+  };
+}
+
+export interface SkillInsert {
+  name: string;
+  description: string;
+  content: string;
+  type?: SkillType;
+  scope?: SkillScope;
+  ownerAgentId?: string;
+  sourceUrl?: string;
+  sourceRepo?: string;
+  sourcePath?: string;
+  sourceBranch?: string;
+  sourceHash?: string;
+  isComplex?: boolean;
+  allowedTools?: string;
+  model?: string;
+  effort?: string;
+  context?: string;
+  agent?: string;
+  disableModelInvocation?: boolean;
+  userInvocable?: boolean;
+}
+
+export function createSkill(data: SkillInsert): Skill {
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+
+  const row = getDb()
+    .prepare<SkillRow, (string | number | null)[]>(
+      `INSERT INTO skills (
+        id, name, description, content, type, scope, ownerAgentId,
+        sourceUrl, sourceRepo, sourcePath, sourceBranch, sourceHash, isComplex,
+        allowedTools, model, effort, context, agent, disableModelInvocation, userInvocable,
+        version, isEnabled, createdAt, lastUpdatedAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 1, ?, ?) RETURNING *`,
+    )
+    .get(
+      id,
+      data.name,
+      data.description,
+      data.content,
+      data.type ?? "personal",
+      data.scope ?? "agent",
+      data.ownerAgentId ?? null,
+      data.sourceUrl ?? null,
+      data.sourceRepo ?? null,
+      data.sourcePath ?? null,
+      data.sourceBranch ?? "main",
+      data.sourceHash ?? null,
+      data.isComplex ? 1 : 0,
+      data.allowedTools ?? null,
+      data.model ?? null,
+      data.effort ?? null,
+      data.context ?? null,
+      data.agent ?? null,
+      data.disableModelInvocation ? 1 : 0,
+      data.userInvocable === false ? 0 : 1,
+      now,
+      now,
+    );
+
+  if (!row) throw new Error("Failed to create skill");
+  return rowToSkill(row);
+}
+
+export function updateSkill(
+  id: string,
+  updates: Partial<SkillInsert> & { isEnabled?: boolean; lastFetchedAt?: string },
+): Skill | null {
+  const existing = getSkillById(id);
+  if (!existing) return null;
+
+  const now = new Date().toISOString();
+  const sets: string[] = ["lastUpdatedAt = ?"];
+  const params: (string | number | null)[] = [now];
+
+  if (updates.name !== undefined) {
+    sets.push("name = ?");
+    params.push(updates.name);
+  }
+  if (updates.description !== undefined) {
+    sets.push("description = ?");
+    params.push(updates.description);
+  }
+  if (updates.content !== undefined) {
+    sets.push("content = ?");
+    params.push(updates.content);
+  }
+  if (updates.scope !== undefined) {
+    sets.push("scope = ?");
+    params.push(updates.scope);
+  }
+  if (updates.isEnabled !== undefined) {
+    sets.push("isEnabled = ?");
+    params.push(updates.isEnabled ? 1 : 0);
+  }
+  if (updates.allowedTools !== undefined) {
+    sets.push("allowedTools = ?");
+    params.push(updates.allowedTools ?? null);
+  }
+  if (updates.model !== undefined) {
+    sets.push("model = ?");
+    params.push(updates.model ?? null);
+  }
+  if (updates.effort !== undefined) {
+    sets.push("effort = ?");
+    params.push(updates.effort ?? null);
+  }
+  if (updates.context !== undefined) {
+    sets.push("context = ?");
+    params.push(updates.context ?? null);
+  }
+  if (updates.agent !== undefined) {
+    sets.push("agent = ?");
+    params.push(updates.agent ?? null);
+  }
+  if (updates.disableModelInvocation !== undefined) {
+    sets.push("disableModelInvocation = ?");
+    params.push(updates.disableModelInvocation ? 1 : 0);
+  }
+  if (updates.userInvocable !== undefined) {
+    sets.push("userInvocable = ?");
+    params.push(updates.userInvocable ? 1 : 0);
+  }
+  if (updates.sourceUrl !== undefined) {
+    sets.push("sourceUrl = ?");
+    params.push(updates.sourceUrl ?? null);
+  }
+  if (updates.sourceRepo !== undefined) {
+    sets.push("sourceRepo = ?");
+    params.push(updates.sourceRepo ?? null);
+  }
+  if (updates.sourcePath !== undefined) {
+    sets.push("sourcePath = ?");
+    params.push(updates.sourcePath ?? null);
+  }
+  if (updates.sourceBranch !== undefined) {
+    sets.push("sourceBranch = ?");
+    params.push(updates.sourceBranch ?? "main");
+  }
+  if (updates.sourceHash !== undefined) {
+    sets.push("sourceHash = ?");
+    params.push(updates.sourceHash ?? null);
+  }
+  if (updates.isComplex !== undefined) {
+    sets.push("isComplex = ?");
+    params.push(updates.isComplex ? 1 : 0);
+  }
+  if (updates.lastFetchedAt !== undefined) {
+    sets.push("lastFetchedAt = ?");
+    params.push(updates.lastFetchedAt);
+  }
+
+  // Bump version when content changes
+  if (updates.content !== undefined) {
+    sets.push("version = version + 1");
+  }
+
+  params.push(id);
+  const row = getDb()
+    .prepare<SkillRow, (string | number | null)[]>(
+      `UPDATE skills SET ${sets.join(", ")} WHERE id = ? RETURNING *`,
+    )
+    .get(...params);
+
+  return row ? rowToSkill(row) : null;
+}
+
+export function deleteSkill(id: string): boolean {
+  const result = getDb().prepare("DELETE FROM skills WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function getSkillById(id: string): Skill | null {
+  const row = getDb().prepare<SkillRow, [string]>("SELECT * FROM skills WHERE id = ?").get(id);
+  return row ? rowToSkill(row) : null;
+}
+
+export function getSkillByName(
+  name: string,
+  scope: SkillScope,
+  ownerAgentId?: string,
+): Skill | null {
+  const row = getDb()
+    .prepare<SkillRow, [string, string, string]>(
+      "SELECT * FROM skills WHERE name = ? AND scope = ? AND COALESCE(ownerAgentId, '') = ?",
+    )
+    .get(name, scope, ownerAgentId ?? "");
+  return row ? rowToSkill(row) : null;
+}
+
+export interface SkillFilters {
+  type?: SkillType;
+  scope?: SkillScope;
+  ownerAgentId?: string;
+  isEnabled?: boolean;
+  search?: string;
+  limit?: number;
+  includeContent?: boolean;
+}
+
+export function listSkills(filters?: SkillFilters): Skill[] {
+  const columns =
+    filters?.includeContent === false
+      ? "id, name, description, type, scope, ownerAgentId, sourceUrl, sourceRepo, sourcePath, sourceBranch, sourceHash, isComplex, allowedTools, model, effort, context, agent, disableModelInvocation, userInvocable, version, isEnabled, createdAt, lastUpdatedAt, lastFetchedAt, '' as content"
+      : "*";
+  let query = `SELECT ${columns} FROM skills WHERE 1=1`;
+  const params: (string | number)[] = [];
+
+  if (filters?.type) {
+    query += " AND type = ?";
+    params.push(filters.type);
+  }
+  if (filters?.scope) {
+    query += " AND scope = ?";
+    params.push(filters.scope);
+  }
+  if (filters?.ownerAgentId) {
+    query += " AND ownerAgentId = ?";
+    params.push(filters.ownerAgentId);
+  }
+  if (filters?.isEnabled !== undefined) {
+    query += " AND isEnabled = ?";
+    params.push(filters.isEnabled ? 1 : 0);
+  }
+  if (filters?.search) {
+    query += " AND (name LIKE ? OR description LIKE ?)";
+    const term = `%${filters.search}%`;
+    params.push(term, term);
+  }
+
+  query += " ORDER BY name ASC";
+
+  if (filters?.limit) {
+    query += " LIMIT ?";
+    params.push(filters.limit);
+  }
+
+  return getDb()
+    .prepare<SkillRow, (string | number)[]>(query)
+    .all(...params)
+    .map(rowToSkill);
+}
+
+export function searchSkills(query: string, limit = 20): Skill[] {
+  const term = `%${query}%`;
+  return getDb()
+    .prepare<SkillRow, [string, string, number]>(
+      "SELECT * FROM skills WHERE (name LIKE ? OR description LIKE ?) AND isEnabled = 1 ORDER BY name ASC LIMIT ?",
+    )
+    .all(term, term, limit)
+    .map(rowToSkill);
+}
+
+export function installSkill(agentId: string, skillId: string): AgentSkill {
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+
+  const row = getDb()
+    .prepare<AgentSkillRow, [string, string, string, string]>(
+      `INSERT INTO agent_skills (id, agentId, skillId, isActive, installedAt)
+       VALUES (?, ?, ?, 1, ?)
+       ON CONFLICT(agentId, skillId) DO UPDATE SET isActive = 1
+       RETURNING *`,
+    )
+    .get(id, agentId, skillId, now);
+
+  if (!row) throw new Error("Failed to install skill");
+  return rowToAgentSkill(row);
+}
+
+export function uninstallSkill(agentId: string, skillId: string): boolean {
+  const result = getDb()
+    .prepare("DELETE FROM agent_skills WHERE agentId = ? AND skillId = ?")
+    .run(agentId, skillId);
+  return result.changes > 0;
+}
+
+export function getAgentSkills(agentId: string, activeOnly = true): SkillWithInstallInfo[] {
+  const query = `
+    SELECT s.*, as2.isActive, as2.installedAt
+    FROM skills s
+    JOIN agent_skills as2 ON s.id = as2.skillId
+    WHERE as2.agentId = ?
+      ${activeOnly ? "AND as2.isActive = 1" : ""}
+      AND s.isEnabled = 1
+    ORDER BY
+      CASE WHEN s.type = 'personal' THEN 0 ELSE 1 END,
+      s.name
+  `;
+
+  const rows = getDb().prepare<SkillWithInstallRow, [string]>(query).all(agentId);
+
+  // Deduplicate by name — personal skills take precedence (already sorted first)
+  const seen = new Set<string>();
+  return rows
+    .filter((r) => {
+      if (seen.has(r.name)) return false;
+      seen.add(r.name);
+      return true;
+    })
+    .map(rowToSkillWithInstall);
+}
+
+export function toggleAgentSkill(agentId: string, skillId: string, isActive: boolean): boolean {
+  const result = getDb()
+    .prepare("UPDATE agent_skills SET isActive = ? WHERE agentId = ? AND skillId = ?")
+    .run(isActive ? 1 : 0, agentId, skillId);
+  return result.changes > 0;
+}