agentworkshop 0.7.44 → 0.7.46

package/server/services/workshop/db/outbox.repo.ts

@@ -0,0 +1,127 @@
+/**
+ * Outbox 仓储 —— v17 事务内待发布事件(outbox_events)。
+ *
+ * 语义(主计划 §3.6):
+ * - 消息事实落库与 delivery/outbox 写入必须同一 SQLite 事务;
+ * - 广播失败**不能回滚已落库消息**;重试必须幂等(attempts 计数 + status)。
+ * - status: pending | published | failed
+ *
+ * 用途:WS 广播是不可靠副作用(peer 可能断开、进程可能崩溃)。落库成功即事实,
+ * 发布失败只影响实时提示,由 listPending 的补偿扫描(或客户端游标补拉)收敛。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { OutboxEventRow } from './database'
+
+const COLS = 'id, aggregate_type AS aggregateType, aggregate_id AS aggregateId, event_type AS eventType, payload_json AS payloadJson, status, attempts, last_error AS lastError, created_at AS createdAt, published_at AS publishedAt'
+
+export type OutboxStatus = 'pending' | 'published' | 'failed'
+
+export interface OutboxEnqueueInput {
+  aggregateType: string
+  aggregateId: string
+  eventType: string
+  payload?: Record<string, unknown>
+  /** 幂等键(缺省 = `${aggregateType}:${aggregateId}:${eventType}`;同键唯一) */
+  eventId?: string
+  id?: string
+}
+
+export type OutboxRepo = ReturnType<typeof createOutboxRepo>
+
+export function createOutboxRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO outbox_events (id, aggregate_type, aggregate_id, event_type, payload_json, status, attempts, last_error, created_at, published_at)
+     VALUES (?, ?, ?, ?, ?, 'pending', 0, '', ?, NULL)`,
+  )
+  const selectById = db.prepare(`SELECT ${COLS} FROM outbox_events WHERE id = ?`)
+  const selectPending = db.prepare(`SELECT ${COLS} FROM outbox_events WHERE status = 'pending' ORDER BY created_at ASC LIMIT ?`)
+  const selectAll = db.prepare(`SELECT ${COLS} FROM outbox_events ORDER BY created_at ASC LIMIT ?`)
+  const markPublished = db.prepare(`UPDATE outbox_events SET status = 'published', published_at = ?, attempts = attempts + 1, last_error = '' WHERE id = ?`)
+  /** 条件发布(幂等;不改动非 pending 行) */
+  const markPublishedIfPending = db.prepare(`UPDATE outbox_events SET status = 'published', published_at = ?, attempts = attempts + 1, last_error = '' WHERE id = ? AND status = 'pending'`)
+  const markFailed = db.prepare(`UPDATE outbox_events SET status = 'failed', attempts = attempts + 1, last_error = ? WHERE id = ?`)
+  const reschedule = db.prepare(`UPDATE outbox_events SET status = 'pending', attempts = attempts + 1, last_error = ? WHERE id = ?`)
+  const countByStatus = db.prepare(`SELECT status, COUNT(*) AS n FROM outbox_events GROUP BY status`)
+  /** 保留期清理:删除已发布且 published_at 早于给定时刻的行 */
+  const sweepPublishedStmt = db.prepare(`DELETE FROM outbox_events WHERE status = 'published' AND published_at IS NOT NULL AND published_at < ?`)
+  /** 死信保留期清理:failed 行超过保留期后回收(否则毒事件永久占表,§11 需要容量有界) */
+  const sweepFailedStmt = db.prepare(`DELETE FROM outbox_events WHERE status = 'failed' AND created_at < ?`)
+
+  return {
+    /**
+     * 事务内登记一条待发布事件(幂等:同 id 已存在时不重复插入)。
+     * 返回 id 与是否新插入。
+     */
+    enqueue(input: OutboxEnqueueInput): { id: string, inserted: boolean } {
+      const id = input.id ?? input.eventId ?? `${input.aggregateType}:${input.aggregateId}:${input.eventType}:${randomUUID()}`
+      const res = insert.run(
+        id, input.aggregateType, input.aggregateId, input.eventType,
+        JSON.stringify(input.payload ?? {}), new Date().toISOString(),
+      )
+      return { id, inserted: Number(res.changes ?? 0) > 0 }
+    },
+
+    findById(id: string): OutboxEventRow | undefined {
+      return (selectById.get(id) as unknown as OutboxEventRow | undefined) ?? undefined
+    },
+
+    /** 待发布清单(补偿扫描;升序保序) */
+    listPending(limit = 200): OutboxEventRow[] {
+      return selectPending.all(limit) as unknown as OutboxEventRow[]
+    },
+
+    listAll(limit = 500): OutboxEventRow[] {
+      return selectAll.all(limit) as unknown as OutboxEventRow[]
+    },
+
+    markPublished(id: string): void {
+      markPublished.run(new Date().toISOString(), id)
+    },
+
+    /**
+     * 幂等收敛:pending → published(仅当仍为 pending)。
+     *
+     * 与 `markPublished` 的差别:这是**条件更新**,重复调用不会把 attempts 越加越大,
+     * 也不会覆盖已 failed 的行(发布阶段的"已成功"不应该抹掉失败留痕)。
+     * 返回是否真的发生了状态迁移 —— 调用方据此判断"本次发布是否首次成功"。
+     */
+    markPublishedIfPending(id: string): boolean {
+      return Number(markPublishedIfPending.run(new Date().toISOString(), id).changes ?? 0) > 0
+    },
+
+    markFailed(id: string, error: string): void {
+      markFailed.run(error.slice(0, 500), id)
+    },
+
+    /** 重试:failed → pending(attempts+1) */
+    reschedule(id: string, reason = ''): void {
+      reschedule.run(reason.slice(0, 500), id)
+    },
+
+    counts(): Record<string, number> {
+      const rows = countByStatus.all() as unknown as Array<{ status: string, n: number }>
+      const out: Record<string, number> = { pending: 0, published: 0, failed: 0 }
+      for (const r of rows) out[r.status] = Number(r.n)
+      return out
+    },
+
+    /**
+     * 保留期清理:删除 `published_at < beforeIso` 的已发布行,返回清理行数。
+     *
+     * 每次群聊发言都会登记 outbox 行(chat.message + 每条投递),不清理则表随会话线性增长。
+     * **只删 published**:pending 是"尚未发布"的欠账,failed 是失败留痕,都不能回收。
+     */
+    sweepPublished(beforeIso: string): number {
+      return Number(sweepPublishedStmt.run(beforeIso).changes ?? 0)
+    },
+
+    /**
+     * 死信保留期清理:删除 `created_at < beforeIso` 的 failed 行,返回清理行数。
+     * pending(**尚未发布**的欠账)永不回收 —— 那是必须收敛的事实源。
+     */
+    sweepFailed(beforeIso: string): number {
+      return Number(sweepFailedStmt.run(beforeIso).changes ?? 0)
+    },
+  }
+}

package/server/services/workshop/db/scheduled-task.repo.ts

@@ -0,0 +1,235 @@
+/**
+ * ScheduledTask 仓储:scheduled_tasks / scheduled_task_runs 两表 CRUD(v16 定时任务)。
+ * 工厂接收 DatabaseSync(依赖注入),不持有任何单例;触发决策(next_run_at 计算)在 runtime 层。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { ScheduledTaskRow, ScheduledTaskRunRow } from './database'
+
+const COLS = `id, channel_id AS channelId, name, title, description, mode, interval_ms AS intervalMs,
+  daily_time AS dailyTime, enabled, state, last_run_at AS lastRunAt, next_run_at AS nextRunAt,
+  last_task_id AS lastTaskId, run_count AS runCount, fail_count AS failCount,
+  consecutive_failures AS consecutiveFailures, max_consecutive_failures AS maxConsecutiveFailures,
+  owner_user_id AS ownerUserId, created_at AS createdAt, updated_at AS updatedAt`
+
+const RUN_COLS = `id, schedule_id AS scheduleId, trigger_kind AS triggerKind, task_id AS taskId,
+  state, error, started_at AS startedAt, ended_at AS endedAt`
+
+/** 每计划保留的运行历史上限(超出裁剪最旧;GC 在每次触发时顺带执行) */
+const RUNS_RETAIN_PER_SCHEDULE = 50
+
+export interface ScheduledTaskCreateInput {
+  channelId: string
+  name: string
+  title: string
+  description?: string
+  mode: 'interval' | 'daily'
+  intervalMs?: number
+  dailyTime?: string
+  maxConsecutiveFailures?: number
+  ownerUserId?: string | null
+  /** 首次触发时刻(ISO;由 manager/runtime 计算后传入持久化) */
+  nextRunAt?: string | null
+}
+
+export interface ScheduledTaskPatch {
+  name?: string
+  title?: string
+  description?: string
+  mode?: 'interval' | 'daily'
+  intervalMs?: number
+  dailyTime?: string
+  enabled?: number
+  maxConsecutiveFailures?: number
+}
+
+export type ScheduledTaskRepo = ReturnType<typeof createScheduledTaskRepo>
+
+export function createScheduledTaskRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO scheduled_tasks (id, channel_id, name, title, description, mode, interval_ms, daily_time,
+       enabled, state, next_run_at, max_consecutive_failures, owner_user_id, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const selectById = db.prepare(`SELECT ${COLS} FROM scheduled_tasks WHERE id = ?`)
+  const selectAll = db.prepare(`SELECT ${COLS} FROM scheduled_tasks ORDER BY createdAt DESC`)
+  const selectEnabled = db.prepare(`SELECT ${COLS} FROM scheduled_tasks WHERE enabled = 1 ORDER BY next_run_at ASC`)
+  const selectByChannel = db.prepare(`SELECT ${COLS} FROM scheduled_tasks WHERE channel_id = ? ORDER BY createdAt DESC`)
+  const countEnabledByChannel = db.prepare(`SELECT COUNT(*) AS n FROM scheduled_tasks WHERE channel_id = ? AND enabled = 1`)
+  const updateStmt = db.prepare(
+    `UPDATE scheduled_tasks SET name = ?, title = ?, description = ?, mode = ?, interval_ms = ?, daily_time = ?,
+       enabled = ?, state = ?, last_run_at = ?, next_run_at = ?, last_task_id = ?, run_count = ?, fail_count = ?,
+       consecutive_failures = ?, max_consecutive_failures = ?, updated_at = ?
+     WHERE id = ?`,
+  )
+  const removeStmt = db.prepare(`DELETE FROM scheduled_tasks WHERE id = ?`)
+  const removeByChannelStmt = db.prepare(`DELETE FROM scheduled_tasks WHERE channel_id = ?`)
+
+  const insertRun = db.prepare(
+    `INSERT INTO scheduled_task_runs (id, schedule_id, trigger_kind, task_id, state, error, started_at, ended_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const selectRunsBySchedule = db.prepare(
+    `SELECT ${RUN_COLS} FROM scheduled_task_runs WHERE schedule_id = ? ORDER BY started_at DESC LIMIT ?`,
+  )
+  const findRunById = db.prepare(`SELECT ${RUN_COLS} FROM scheduled_task_runs WHERE id = ?`)
+  const updateRunStmt = db.prepare(
+    `UPDATE scheduled_task_runs SET task_id = ?, state = ?, error = ?, ended_at = ? WHERE id = ?`,
+  )
+  const listRunningRuns = db.prepare(`SELECT ${RUN_COLS} FROM scheduled_task_runs WHERE state = 'RUNNING'`)
+  const pruneRunsStmt = db.prepare(
+    `DELETE FROM scheduled_task_runs WHERE schedule_id = ? AND id NOT IN (
+       SELECT id FROM scheduled_task_runs WHERE schedule_id = ? ORDER BY started_at DESC LIMIT ${RUNS_RETAIN_PER_SCHEDULE})`,
+  )
+
+  return {
+    create(input: ScheduledTaskCreateInput): ScheduledTaskRow {
+      const now = new Date().toISOString()
+      const row: ScheduledTaskRow = {
+        id: randomUUID(),
+        channelId: input.channelId,
+        name: input.name,
+        title: input.title,
+        description: input.description ?? '',
+        mode: input.mode,
+        intervalMs: input.intervalMs ?? 0,
+        dailyTime: input.dailyTime ?? '',
+        enabled: 1,
+        state: 'idle',
+        lastRunAt: null,
+        nextRunAt: input.nextRunAt ?? null,
+        lastTaskId: null,
+        runCount: 0,
+        failCount: 0,
+        consecutiveFailures: 0,
+        maxConsecutiveFailures: input.maxConsecutiveFailures ?? 0,
+        ownerUserId: input.ownerUserId ?? null,
+        createdAt: now,
+        updatedAt: now,
+      }
+      insert.run(row.id, row.channelId, row.name, row.title, row.description, row.mode, row.intervalMs,
+        row.dailyTime, row.enabled, row.state, row.nextRunAt, row.maxConsecutiveFailures,
+        row.ownerUserId, row.createdAt, row.updatedAt)
+      return row
+    },
+
+    list(): ScheduledTaskRow[] {
+      return selectAll.all() as unknown as ScheduledTaskRow[]
+    },
+
+    listEnabled(): ScheduledTaskRow[] {
+      return selectEnabled.all() as unknown as ScheduledTaskRow[]
+    },
+
+    listByChannel(channelId: string): ScheduledTaskRow[] {
+      return selectByChannel.all(channelId) as unknown as ScheduledTaskRow[]
+    },
+
+    findById(id: string): ScheduledTaskRow | undefined {
+      return selectById.get(id) as unknown as ScheduledTaskRow | undefined
+    },
+
+    /** 该 channel 当前启用的定时任务数(Channel「定时」标志的单一事实源) */
+    countEnabledByChannel(channelId: string): number {
+      return (countEnabledByChannel.get(channelId) as unknown as { n: number }).n
+    },
+
+    /** 全量计数(按 channel 分组):channels 列表批量附标志用,一次查询替代 N 次 count */
+    countEnabledByChannelAll(): Map<string, number> {
+      const rows = db.prepare(
+        `SELECT channel_id AS channelId, COUNT(*) AS n FROM scheduled_tasks WHERE enabled = 1 GROUP BY channel_id`,
+      ).all() as unknown as Array<{ channelId: string, n: number }>
+      return new Map(rows.map(r => [r.channelId, r.n]))
+    },
+
+    /** 全量更新(runtime 触发/收敛的主写路径;patch 未给字段沿用现值) */
+    update(id: string, patch: ScheduledTaskPatch & {
+      state?: string
+      lastRunAt?: string | null
+      nextRunAt?: string | null
+      lastTaskId?: string | null
+      runCount?: number
+      failCount?: number
+      consecutiveFailures?: number
+    }): ScheduledTaskRow | undefined {
+      const current = selectById.get(id) as unknown as ScheduledTaskRow | undefined
+      if (!current) return undefined
+      const next: ScheduledTaskRow = {
+        ...current,
+        name: patch.name ?? current.name,
+        title: patch.title ?? current.title,
+        description: patch.description ?? current.description,
+        mode: patch.mode ?? current.mode,
+        intervalMs: patch.intervalMs ?? current.intervalMs,
+        dailyTime: patch.dailyTime ?? current.dailyTime,
+        enabled: patch.enabled ?? current.enabled,
+        state: patch.state ?? current.state,
+        lastRunAt: patch.lastRunAt !== undefined ? patch.lastRunAt : current.lastRunAt,
+        nextRunAt: patch.nextRunAt !== undefined ? patch.nextRunAt : current.nextRunAt,
+        lastTaskId: patch.lastTaskId !== undefined ? patch.lastTaskId : current.lastTaskId,
+        runCount: patch.runCount ?? current.runCount,
+        failCount: patch.failCount ?? current.failCount,
+        consecutiveFailures: patch.consecutiveFailures ?? current.consecutiveFailures,
+        maxConsecutiveFailures: patch.maxConsecutiveFailures ?? current.maxConsecutiveFailures,
+        updatedAt: new Date().toISOString(),
+      }
+      updateStmt.run(next.name, next.title, next.description, next.mode, next.intervalMs, next.dailyTime,
+        next.enabled, next.state, next.lastRunAt, next.nextRunAt, next.lastTaskId, next.runCount,
+        next.failCount, next.consecutiveFailures, next.maxConsecutiveFailures, next.updatedAt, id)
+      return next
+    },
+
+    remove(id: string): void {
+      removeStmt.run(id)
+    },
+
+    /** channel 级联清理(FK CASCADE 兜底;removeChannel 显式调用以保证旧库无 FK 时也收敛) */
+    removeByChannel(channelId: string): void {
+      removeByChannelStmt.run(channelId)
+    },
+
+    // ===== 运行历史 =====
+
+    createRun(input: { scheduleId: string, triggerKind: 'timer' | 'manual' }): ScheduledTaskRunRow {
+      const row: ScheduledTaskRunRow = {
+        id: randomUUID(),
+        scheduleId: input.scheduleId,
+        triggerKind: input.triggerKind,
+        taskId: null,
+        state: 'RUNNING',
+        error: '',
+        startedAt: new Date().toISOString(),
+        endedAt: null,
+      }
+      insertRun.run(row.id, row.scheduleId, row.triggerKind, row.taskId, row.state, row.error, row.startedAt, row.endedAt)
+      return row
+    },
+
+    findRun(runId: string): ScheduledTaskRunRow | undefined {
+      return findRunById.get(runId) as unknown as ScheduledTaskRunRow | undefined
+    },
+
+    listRuns(scheduleId: string, limit = RUNS_RETAIN_PER_SCHEDULE): ScheduledTaskRunRow[] {
+      return selectRunsBySchedule.all(scheduleId, limit) as unknown as ScheduledTaskRunRow[]
+    },
+
+    /** 在途运行(重启恢复/对账用) */
+    listRunningRuns(): ScheduledTaskRunRow[] {
+      return listRunningRuns.all() as unknown as ScheduledTaskRunRow[]
+    },
+
+    finishRun(runId: string, patch: { taskId?: string | null, state: 'COMPLETED' | 'FAILED', error?: string }): void {
+      updateRunStmt.run(patch.taskId ?? null, patch.state, patch.error ?? '', new Date().toISOString(), runId)
+    },
+
+    /** 在途 run 回填 taskId(保持 RUNNING;ended_at 不动——收口统一走 finishRun) */
+    attachTask(runId: string, taskId: string): void {
+      db.prepare(`UPDATE scheduled_task_runs SET task_id = ? WHERE id = ?`).run(taskId, runId)
+    },
+
+    /** 保留策略:每计划只留最近 RUNS_RETAIN_PER_SCHEDULE 条(触发时顺带 GC) */
+    pruneRuns(scheduleId: string): void {
+      pruneRunsStmt.run(scheduleId, scheduleId)
+    },
+  }
+}

package/server/services/workshop/db/schema.sql

@@ -67,6 +67,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   id             TEXT PRIMARY KEY,
   channel_id     TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
   parent_id      TEXT,
+  root_queue_seq INTEGER,              -- root FIFO sequence; NULL for children
   assignee_id    TEXT NOT NULL,               -- 实例身份 id
   creator_id     TEXT,
   title          TEXT NOT NULL,
@@ -76,6 +77,15 @@ CREATE TABLE IF NOT EXISTS tasks (
   retry_count    INTEGER NOT NULL DEFAULT 0,  -- 重派次数(SchedulerLoop reassign 时 +1,>=3 停止重派)
   artifacts_json TEXT NOT NULL DEFAULT '[]',
   history_json   TEXT NOT NULL DEFAULT '[]',
+  source_chat_message_id  TEXT,
+  source_chat_delivery_id TEXT,
+  close_reason   TEXT,
+  deadline_at    TEXT,
+  assignment_generation      INTEGER NOT NULL DEFAULT 0,  -- 执行交接代次(重分配 +1)
+  execution_lease_id         TEXT,                         -- 当前执行租约 id(旧 worker 迟到事件据此丢弃)
+  execution_lease_agent_id   TEXT,                         -- 租约持有者
+  execution_lease_started_at TEXT,
+  execution_lease_revoked_at TEXT,
   created_at     TEXT NOT NULL,
   updated_at     TEXT NOT NULL
 );
@@ -141,3 +151,178 @@ CREATE TRIGGER IF NOT EXISTS trg_agent_memories_au AFTER UPDATE ON agent_memorie
   INSERT INTO agent_memories_fts(title, content, agent_id, memory_rowid)
   VALUES (new.title_fts, new.content, new.agent_id, new.rowid);
 END;
+
+-- v16:定时任务(绑定 Channel 的周期任务编排;权威 DDL 在 database.ts SCHEMA_SQL)
+-- mode='interval' 固定间隔 / mode='daily' 每日定点(HH:MM 本地时区);
+-- state: idle|waiting|running|disabled|failed(runtime 视图状态)。
+CREATE TABLE IF NOT EXISTS scheduled_tasks (
+  id              TEXT PRIMARY KEY,
+  channel_id      TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+  name            TEXT NOT NULL,
+  title           TEXT NOT NULL,
+  description     TEXT NOT NULL DEFAULT '',
+  mode            TEXT NOT NULL DEFAULT 'interval',
+  interval_ms     INTEGER NOT NULL DEFAULT 0,
+  daily_time      TEXT NOT NULL DEFAULT '',
+  enabled         INTEGER NOT NULL DEFAULT 1,
+  state           TEXT NOT NULL DEFAULT 'idle',
+  last_run_at     TEXT,
+  next_run_at     TEXT,
+  last_task_id    TEXT,
+  run_count       INTEGER NOT NULL DEFAULT 0,
+  fail_count      INTEGER NOT NULL DEFAULT 0,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  max_consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  owner_user_id   TEXT,
+  created_at      TEXT NOT NULL,
+  updated_at      TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_channel ON scheduled_tasks(channel_id);
+CREATE INDEX IF NOT EXISTS idx_scheduled_tasks_enabled ON scheduled_tasks(enabled, next_run_at);
+
+-- v16:定时任务运行历史(每次触发留痕;repo 层按 schedule 裁剪至最近 50 条)
+CREATE TABLE IF NOT EXISTS scheduled_task_runs (
+  id            TEXT PRIMARY KEY,
+  schedule_id   TEXT NOT NULL REFERENCES scheduled_tasks(id) ON DELETE CASCADE,
+  trigger_kind  TEXT NOT NULL DEFAULT 'timer',   -- 'timer' | 'manual'
+  task_id       TEXT,
+  state         TEXT NOT NULL DEFAULT 'RUNNING', -- RUNNING|COMPLETED|FAILED
+  error         TEXT NOT NULL DEFAULT '',
+  started_at    TEXT NOT NULL,
+  ended_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_scheduled_task_runs_schedule ON scheduled_task_runs(schedule_id, started_at DESC);
+
+-- ============================================================================
+-- v17:人类群聊 / 成员权限 / 用户级通知 / 可靠投递 / HITL 持久化
+-- 权威 DDL 在 database.ts 的 SCHEMA_SQL(内联字符串);本文件为源码文档,两处必须同步。
+-- 约定:user_id 一律为「全局用户系统」的 id,不是本库遗留 users 表;跨库不加外键。
+-- ============================================================================
+
+-- channel_members:登录用户作为 Channel 群成员(owner 亦有一条 active 记录)。
+-- status: active | left | removed | pending(owner_approve 待批准)
+-- generation: 反复加入/退出时递增;旧审批资格不因重新加入而恢复。
+CREATE TABLE IF NOT EXISTS channel_members (
+  channel_id  TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+  user_id     TEXT NOT NULL,
+  role        TEXT NOT NULL DEFAULT 'member',   -- owner | member
+  status      TEXT NOT NULL DEFAULT 'active',   -- active | left | removed | pending
+  generation  INTEGER NOT NULL DEFAULT 1,
+  joined_at   TEXT NOT NULL,
+  left_at     TEXT,
+  PRIMARY KEY (channel_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_channel_members_user ON channel_members(user_id, status);
+CREATE INDEX IF NOT EXISTS idx_channel_members_channel ON channel_members(channel_id, status);
+
+-- chat_messages:群聊事实表(与 Agent mailbox 双轨,共享关联 ID)。
+CREATE TABLE IF NOT EXISTS chat_messages (
+  id                     TEXT PRIMARY KEY,
+  channel_id             TEXT NOT NULL REFERENCES channels(id) ON DELETE CASCADE,
+  sender_type            TEXT NOT NULL,          -- user | agent | system
+  sender_id              TEXT NOT NULL,
+  sender_name            TEXT NOT NULL DEFAULT '',
+  text                   TEXT NOT NULL,
+  mentions_json          TEXT NOT NULL DEFAULT '[]',
+  reply_to_id            TEXT,
+  requester_user_id      TEXT,
+  source_chat_message_id TEXT,
+  client_message_id      TEXT NOT NULL,
+  created_at             TEXT NOT NULL,
+  UNIQUE(channel_id, client_message_id)
+);
+CREATE INDEX IF NOT EXISTS idx_chat_messages_channel ON chat_messages(channel_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_chat_messages_source ON chat_messages(source_chat_message_id);
+
+-- chat_deliveries:群聊 → Agent mailbox 投递台账(同消息同 Agent 唯一)。
+CREATE TABLE IF NOT EXISTS chat_deliveries (
+  id                  TEXT PRIMARY KEY,
+  chat_message_id     TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,
+  channel_id          TEXT NOT NULL,
+  target_agent_id     TEXT NOT NULL,
+  mailbox_message_id  TEXT,
+  status              TEXT NOT NULL DEFAULT 'pending', -- pending|delivered|consumed|failed|cancelled
+  error               TEXT NOT NULL DEFAULT '',
+  created_at          TEXT NOT NULL,
+  updated_at          TEXT NOT NULL,
+  UNIQUE(chat_message_id, target_agent_id)
+);
+CREATE INDEX IF NOT EXISTS idx_chat_deliveries_message ON chat_deliveries(chat_message_id);
+CREATE INDEX IF NOT EXISTS idx_chat_deliveries_agent ON chat_deliveries(target_agent_id, status);
+-- Agent 回复关联链热路径:按 mailboxMessageId 反查群聊来源
+CREATE INDEX IF NOT EXISTS idx_chat_deliveries_mailbox ON chat_deliveries(mailbox_message_id);
+-- 成员撤权:按 (channel, agent) 批量取消 pending 投递
+CREATE INDEX IF NOT EXISTS idx_chat_deliveries_channel_agent ON chat_deliveries(channel_id, target_agent_id, status);
+
+-- user_notifications:按 recipientUserId 定向的用户通知事实源(游标补发)。
+CREATE TABLE IF NOT EXISTS user_notifications (
+  id                 TEXT PRIMARY KEY,
+  recipient_user_id  TEXT NOT NULL,
+  channel_id         TEXT REFERENCES channels(id) ON DELETE CASCADE,
+  chat_message_id    TEXT,
+  hitl_kind          TEXT,
+  hitl_id            TEXT,
+  event_id           TEXT NOT NULL,
+  type               TEXT NOT NULL,             -- mention | agent_reply | hitl_request | hitl_resolved | member
+  title              TEXT NOT NULL DEFAULT '',
+  body               TEXT NOT NULL DEFAULT '',
+  payload_json       TEXT NOT NULL DEFAULT '{}',
+  created_at         TEXT NOT NULL,
+  read_at            TEXT,
+  UNIQUE(recipient_user_id, event_id)
+);
+CREATE INDEX IF NOT EXISTS idx_user_notifications_recipient ON user_notifications(recipient_user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_user_notifications_unread ON user_notifications(recipient_user_id, read_at);
+-- 发布路径按 eventId 反查刚写入的通知;撤权时按 (channel, recipient) 清理
+CREATE INDEX IF NOT EXISTS idx_user_notifications_event ON user_notifications(event_id);
+CREATE INDEX IF NOT EXISTS idx_user_notifications_channel ON user_notifications(channel_id, recipient_user_id);
+
+-- outbox_events:事务内待发布事件(消息落库与投递同事务;广播失败不回滚消息)。
+CREATE TABLE IF NOT EXISTS outbox_events (
+  id              TEXT PRIMARY KEY,
+  aggregate_type  TEXT NOT NULL,
+  aggregate_id    TEXT NOT NULL,
+  event_type      TEXT NOT NULL,
+  payload_json    TEXT NOT NULL DEFAULT '{}',
+  status          TEXT NOT NULL DEFAULT 'pending', -- pending | published | failed
+  attempts        INTEGER NOT NULL DEFAULT 0,
+  last_error      TEXT NOT NULL DEFAULT '',
+  created_at      TEXT NOT NULL,
+  published_at    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_outbox_status ON outbox_events(status, created_at);
+
+-- hitl_requests:HITL 持久化事实源(registry 降级为缓存门面)。
+CREATE TABLE IF NOT EXISTS hitl_requests (
+  id                     TEXT PRIMARY KEY,
+  kind                   TEXT NOT NULL,
+  request_type           TEXT NOT NULL DEFAULT 'approval', -- question | approval
+  native_request_id      TEXT NOT NULL DEFAULT '',
+  channel_id             TEXT NOT NULL,
+  agent_id               TEXT NOT NULL,
+  agent_name             TEXT NOT NULL DEFAULT '',
+  session_id             TEXT NOT NULL DEFAULT '',
+  harness                TEXT NOT NULL DEFAULT '',
+  mode                   TEXT NOT NULL DEFAULT 'approval',
+  title                  TEXT NOT NULL DEFAULT '',
+  detail                 TEXT NOT NULL DEFAULT '',
+  options_json           TEXT NOT NULL DEFAULT '[]',
+  questions_json         TEXT NOT NULL DEFAULT '[]',
+  schema_json            TEXT NOT NULL DEFAULT '{}',
+  status                 TEXT NOT NULL DEFAULT 'pending',
+  policy                 TEXT NOT NULL DEFAULT 'owner_only',
+  policy_snapshot_json   TEXT NOT NULL DEFAULT '{}',
+  policy_version         INTEGER NOT NULL DEFAULT 0,
+  decision_id            TEXT,
+  responder_user_id      TEXT,
+  decision_json          TEXT NOT NULL DEFAULT '{}',
+  native_confirmed       INTEGER NOT NULL DEFAULT 0,
+  error                  TEXT NOT NULL DEFAULT '',
+  created_at             TEXT NOT NULL,
+  updated_at             TEXT NOT NULL,
+  resolved_at            TEXT,
+  expires_at             TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_hitl_requests_status ON hitl_requests(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_hitl_requests_channel ON hitl_requests(channel_id, status);
+CREATE INDEX IF NOT EXISTS idx_hitl_requests_agent ON hitl_requests(agent_id, status);