@hedeqiang/dsh-nl2sql 0.0.0-stage → 0.11.1

package/service/bots.js

@@ -0,0 +1,665 @@
+/**
+ * Nl2SqlService methods: inbound IM bots (see docs/CHANNELS.md).
+ * Mixed into the service prototype by index.js; `this` is the service.
+ *
+ * Every channel whose kind has `capabilities.bot` may carry
+ * `channel.bot = { enabled, allowP2p, sessionScope: 'chat'|'user' }`. Enabled
+ * bots run their adapter's `createBot(channel, secrets, { onMessage, onAction })`.
+ * This module owns lifecycle, conversations (`state.botConversations`, keyed
+ * `<channelId>:<chatId>#<scopeHash>` per chat or `<channelId>:<chatId>:<userId>`
+ * per user), the per-conversation queue, the agent turn, actor resolution,
+ * interactive actions (opaque tokens, rate limit, re-authorization), delivery
+ * log and audit.
+ *
+ * Buttons carry only an opaque token ({ a: <action>, t: <token> }); the token
+ * maps server-side to { resultId, sessionId, channelId, platform, chatId,
+ * replyTo, depth, ownerRole }. Every click re-resolves the clicking operator and
+ * re-checks data source scope, row-level rules and role before anything runs.
+ */
+import { randomBytes } from 'node:crypto'
+import { parseSelect } from '../analysis.js'
+import { getAdapter, kindOf, loadAdapters } from '../channels/index.js'
+import { toInboundAction, toInboundMessage } from '../channels/lark.js'
+import { PLATFORM_LABEL } from './access.js'
+import { PRESET_ID, UserError, hashText, oneOf, toUserError } from './shared.js'
+
+export const ACTION_TOKEN_TTL_MS = 7 * 24 * 3600 * 1000
+const ACTION_TOKEN_MAX = 5000
+export const ACTION_RATE_MS = 2000
+/** Messages produced by actions get buttons up to this depth (0 = answer message). */
+export const ACTION_MAX_DEPTH = 2
+const ACTIONS = new Set(['drill', 'why', 'detail', 'pin'])
+const CONVERSATIONS_MAX = 500
+
+const toast = (type, content) => ({ toast: { type, content } })
+const label = (platform) => PLATFORM_LABEL[platform] ?? platform ?? 'IM'
+const SOURCE = (platform) => `${platform ?? 'im'}bot`
+
+function hasAggregate(r, dialect) {
+  const parsed = parseSelect(r.baseSql ?? r.sql, { dialect })
+  return Boolean(parsed?.select?.some(i => i.isAggregate))
+}
+
+export const methods = {
+  // ------------------------------------------------------------- config
+
+  normalizeBotConfig(input = {}, prev = {}) {
+    const conf = { enabled: false, allowP2p: true, sessionScope: 'chat', ...(prev ?? {}) }
+    if (input.enabled !== undefined) conf.enabled = Boolean(input.enabled)
+    if (input.allowP2p !== undefined) conf.allowP2p = Boolean(input.allowP2p)
+    if (input.sessionScope !== undefined) conf.sessionScope = oneOf(input.sessionScope, ['chat', 'user'], 'sessionScope')
+    return { enabled: conf.enabled, allowP2p: conf.allowP2p, sessionScope: conf.sessionScope }
+  },
+
+  /** Channels whose kind can run a bot. */
+  botChannels() {
+    return this.state.channels.filter(c => kindOf(c.type)?.kind.capabilities?.bot)
+  },
+
+  /** Bot settings of a channel (or the legacy / default settings for unknown ids). */
+  botConfigFor(channelId) {
+    const c = channelId ? this.state.channels.find(x => x.id === channelId) : undefined
+    if (c?.bot) return this.normalizeBotConfig({}, c.bot)
+    if (this.state.larkBot) return this.normalizeBotConfig({}, this.state.larkBot)
+    return this.normalizeBotConfig({}, {})
+  },
+
+  /**
+   * One-time migration (idempotent): legacy `state.larkBot` → `channel.bot` on
+   * the referenced channel, `state.larkSessions` → `state.botConversations`.
+   */
+  migrateLegacyBot() {
+    let changed = false
+    const legacy = this.state.larkBot
+    let legacyChannelId = legacy?.channelId ?? null
+    if (legacy && typeof legacy === 'object') {
+      const c = legacyChannelId ? this.state.channels.find(x => x.id === legacyChannelId) : undefined
+      if (c && c.type === 'lark_app' && !c.bot) c.bot = this.normalizeBotConfig(legacy, {})
+      changed = true
+    }
+    if ('larkBot' in this.state) { delete this.state.larkBot; changed = true }
+    const old = Object.getOwnPropertyDescriptor(this.state, 'larkSessions')
+    if (old && 'value' in old) {
+      legacyChannelId ??= this.state.channels.find(c => c.type === 'lark_app' && c.bot)?.id ?? 'lark'
+      this.state.botConversations ??= {}
+      for (const conv of Object.values(old.value ?? {})) {
+        if (!conv || typeof conv !== 'object') continue
+        const key = `${legacyChannelId}:${conv.key ?? conv.chatId}`
+        if (!this.state.botConversations[key]) this.state.botConversations[key] = { ...conv, key, channelId: legacyChannelId, platform: 'lark' }
+      }
+      delete this.state.larkSessions
+      changed = true
+    }
+    this.state.botConversations ??= {}
+    // `state.larkSessions` stays readable (not persisted) for older callers.
+    if (!Object.getOwnPropertyDescriptor(this.state, 'larkSessions')) {
+      Object.defineProperty(this.state, 'larkSessions', { get: () => this.state.botConversations, enumerable: false, configurable: true })
+    }
+    return changed
+  },
+
+  // ------------------------------------------------------------- lifecycle
+
+  botRuntimeStatus(c) {
+    const running = this.bots?.get(c.id)
+    if (running) return running.bot.status()
+    return { state: c.bot?.enabled ? 'stopped' : 'idle', since: Date.now() }
+  },
+
+  conversationsFor(channelId, limit = 50) {
+    return Object.values(this.state.botConversations ?? {}).filter(v => !channelId || v.channelId === channelId).sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0)).slice(0, limit)
+  },
+
+  /** Status of every bot-capable channel. */
+  async botStatus() {
+    await loadAdapters()
+    return this.botChannels().map(c => this.botStatusFor(c))
+  },
+
+  botStatusFor(c) {
+    const conf = this.normalizeBotConfig({}, c.bot)
+    return {
+      channelId: c.id, channelName: c.name, platform: c.platform ?? kindOf(c.type)?.adapter.id, type: c.type,
+      ...conf,
+      status: this.botRuntimeStatus(c),
+      info: this.bots?.get(c.id)?.bot.info?.() ?? null,
+      conversations: this.conversationsFor(c.id),
+    }
+  },
+
+  async saveBot({ channelId, ...input } = {}) {
+    await loadAdapters()
+    const c = this.state.channels.find(x => x.id === channelId)
+    if (!c) throw new UserError('nl2sql/unknown-channel', '推送渠道不存在')
+    if (!kindOf(c.type)?.kind.capabilities?.bot) throw new UserError('nl2sql/invalid', `渠道「${c.name}」不支持机器人`)
+    c.bot = this.normalizeBotConfig(input, c.bot)
+    this.auditAdmin('bot.save', `${c.name} · ${c.bot.enabled ? '启用' : '停用'}`)
+    await this.save()
+    await this.restartBot({ channelId: c.id })
+    return this.botStatusFor(c)
+  },
+
+  async stopBot(channelId) {
+    const running = this.bots?.get(channelId)
+    if (!running) return
+    this.bots.delete(channelId)
+    try { await running.bot.stop() } catch {}
+  },
+
+  async stopAllBots() {
+    await Promise.allSettled([...(this.bots?.keys() ?? [])].map(id => this.stopBot(id)))
+  },
+
+  /** (Re)start the bot of one channel; stops it when disabled. Returns its status. */
+  async restartBot({ channelId } = {}) {
+    await loadAdapters()
+    this.bots ??= new Map()
+    await this.stopBot(channelId)
+    const c = this.state.channels.find(x => x.id === channelId)
+    if (!c) return undefined
+    const found = kindOf(c.type)
+    const adapter = found ? getAdapter(found.adapter.id) : undefined
+    if (!c.bot?.enabled || this.disposed || !found?.kind.capabilities?.bot || !adapter?.createBot || c.needsSecret) return this.botStatusFor(c)
+    const secrets = await this.channelSecrets(c)
+    const bot = adapter.createBot(this.adapterChannel(c), secrets, {
+      onMessage: (m) => this.handleBotMessage({ ...m, channelId: c.id, platform: m.platform ?? adapter.id }),
+      onAction: (a) => this.handleBotAction({ ...a, channelId: c.id, platform: a.platform ?? adapter.id }),
+    }, { logger: { debug() {}, info() {}, warn: (...a) => console.warn(`nl2sql ${adapter.id}:`, ...a), error: (...a) => console.warn(`nl2sql ${adapter.id}:`, ...a) } })
+    this.bots.set(c.id, { bot, platform: adapter.id })
+    if (adapter.id === 'lark' && bot.creds && this.larkBotChannel()?.id === c.id) this.larkCreds = bot.creds
+    try { await bot.start() } catch (error) { console.warn('nl2sql bot: %s start failed: %s', c.name, error.message) }
+    return this.botStatusFor(c)
+  },
+
+  /** Start every enabled bot (on apply). */
+  async startBots() {
+    await loadAdapters()
+    for (const c of this.botChannels()) {
+      if (!c.bot?.enabled) continue
+      await this.restartBot({ channelId: c.id }).catch(error => console.warn('nl2sql bot: %s: %s', c.name, error.message))
+    }
+  },
+
+  // ------------------------------------------------------------- legacy Lark RPCs
+
+  /** The Lark app channel the legacy single-bot RPCs operate on. */
+  larkBotChannel() {
+    const apps = this.state.channels.filter(c => c.type === 'lark_app')
+    return apps.find(c => c.bot?.enabled) ?? apps.find(c => c.bot) ?? undefined
+  },
+
+  larkBotConfig() {
+    if (this.state.larkBot) return { enabled: false, channelId: null, allowP2p: true, sessionScope: 'chat', ...this.state.larkBot }
+    const c = this.larkBotChannel()
+    return { ...this.normalizeBotConfig({}, c?.bot), channelId: c?.id ?? null }
+  },
+
+  larkBotStatus() {
+    const conf = this.larkBotConfig()
+    const c = conf.channelId ? this.state.channels.find(x => x.id === conf.channelId) : undefined
+    const info = c ? this.bots?.get(c.id)?.bot.info?.() : null
+    return {
+      ...conf,
+      status: c ? this.botRuntimeStatus(c) : { state: conf.enabled ? 'stopped' : 'idle', since: Date.now() },
+      bot: info ? { openId: info.id, name: info.name } : null,
+      conversations: this.conversationsFor(undefined).filter(v => (v.platform ?? 'lark') === 'lark'),
+    }
+  },
+
+  async saveLarkBot(input = {}) {
+    const conf = this.larkBotConfig()
+    let target = conf.channelId
+    if (input.channelId !== undefined) {
+      const ch = this.state.channels.find(c => c.id === input.channelId)
+      if (input.channelId && (!ch || ch.type !== 'lark_app')) throw new UserError('nl2sql/invalid', '飞书机器人需要选择一个「应用机器人」类型的推送渠道（提供 App ID / Secret）')
+      target = input.channelId || null
+    }
+    const next = this.normalizeBotConfig(input, conf)
+    if (next.enabled && !target) throw new UserError('nl2sql/invalid', '请先选择应用机器人渠道')
+    delete this.state.larkBot
+    // One legacy Lark bot: moving it disables it on the previous channel.
+    const restart = new Set()
+    for (const c of this.state.channels) {
+      if (c.type !== 'lark_app') continue
+      if (c.id === target) { c.bot = next; restart.add(c.id) } else if (c.bot && conf.channelId === c.id) { c.bot = { ...c.bot, enabled: false }; restart.add(c.id) }
+    }
+    this.auditAdmin('larkbot.save', `${next.enabled ? '启用' : '停用'} · ${target ?? ''}`)
+    await this.save()
+    for (const id of restart) await this.restartBot({ channelId: id })
+    return this.larkBotStatus()
+  },
+
+  async restartLarkBot() {
+    const c = this.larkBotChannel()
+    if (c) await this.restartBot({ channelId: c.id })
+  },
+
+  /** Legacy entry: a normalized Lark message (lark-bot.js shape) handled with `this.larkCreds`. */
+  async handleLarkMessage(m) {
+    const creds = this.larkCreds
+    if (!creds) return
+    if (m.chatType === 'group' && !m.mentionedBot) return
+    const inbound = await toInboundMessage(m, creds, { channelId: this.larkBotChannel()?.id })
+    return this.handleBotMessage(inbound)
+  },
+
+  /** Legacy signature (m: normalized Lark message, creds: Lark credentials). */
+  async handleLarkMessageInner(m, text, conf, creds, reply) {
+    const inbound = await toInboundMessage(m, creds, { channelId: this.larkBotChannel()?.id })
+    return this.handleBotMessageInner(inbound, text, conf, reply)
+  },
+
+  /** Legacy entry: a normalized Lark card callback handled with `this.larkCreds`. */
+  async handleLarkCardAction(evt) {
+    const creds = this.larkCreds
+    if (!creds || !evt?.operator?.openId) return undefined
+    return this.handleBotAction(await toInboundAction(evt, creds, { channelId: this.larkBotChannel()?.id }))
+  },
+
+  // ------------------------------------------------------------- messages
+
+  /** One inbound message → permission check → session prompt → reply. */
+  async handleBotMessage(m) {
+    const conf = this.botConfigFor(m.channelId)
+    if (m.chatType === 'group' && !m.mentionedBot) return
+    if (m.chatType === 'p2p' && !conf.allowP2p) return
+    const text = String(m.text ?? '').trim()
+    if (!text) return
+    const reply = (t) => Promise.resolve(m.replyText?.(t)).catch(() => {})
+    try {
+      await this.handleBotMessageInner(m, text, conf, reply)
+    } catch (error) {
+      console.warn('nl2sql bot: %s', error.message)
+      await reply(`处理失败：${toUserError(error).message}`)
+    }
+  },
+
+  async handleBotMessageInner(m, text, conf, reply) {
+    const platform = m.platform ?? 'lark'
+    const name = label(platform)
+    const userId = m.sender?.id != null ? String(m.sender.id) : undefined
+    const resolved = this.resolveActor({ platform, userId, email: m.sender?.email, name: m.sender?.name, chatId: m.chatId != null ? String(m.chatId) : m.chatId, chatType: m.chatType })
+    if (resolved.refused) { await reply(resolved.refused); return }
+    const actor = resolved.actor
+    // Commands: 帮助 / 数据源 / 切换 <名称> / 新对话
+    const cmd = text.match(/^\/?(帮助|help|数据源|切换数据源|切换|新对话|reset|start)\s*(.*)$/i)
+    // Members with different scopes must not share a conversation: per-user sessions
+    // whenever the sender's effective scope or rules differ from the chat's.
+    const scopeSig = JSON.stringify([actor.datasourceIds, actor.role, actor.rowRules ?? []])
+    const shared = conf.sessionScope !== 'user'
+    const prefix = m.channelId ?? platform
+    const key = shared ? `${prefix}:${m.chatId}#${hashText(scopeSig)}` : `${prefix}:${m.chatId}:${userId}`
+    this.state.botConversations ??= {}
+    const convs = this.state.botConversations
+    const conv = convs[key] ?? { key, channelId: m.channelId ?? null, platform, chatId: m.chatId, chatType: m.chatType, sessionId: null, datasourceId: actor.defaultDatasourceId, createdAt: Date.now() }
+    const allowedDs = this.state.datasources.filter(d => !Array.isArray(actor.datasourceIds) || actor.datasourceIds.includes(d.id))
+    if (conv.datasourceId && !allowedDs.some(d => d.id === conv.datasourceId)) conv.datasourceId = allowedDs[0]?.id ?? null
+    if (cmd) {
+      const verb = cmd[1].toLowerCase()
+      if (verb === '帮助' || verb === 'help' || verb === 'start') { await reply(`直接${m.chatType === 'group' ? ' @我 ' : ''}提问即可，例如「上周每天的订单量」。\n命令：数据源（查看可用数据源）、切换 <名称>、新对话。\n当前数据源：${this.findDatasource(conv.datasourceId)?.name ?? '未选择'}${actor.role === 'viewer' ? '\n你是只读成员：可以查询指标库中的指标、已验证的常见问题和看板。' : ''}`); return }
+      if (verb === '数据源') { await reply(`可用数据源：${allowedDs.map(d => d.name).join('、') || '无'}\n当前：${this.findDatasource(conv.datasourceId)?.name ?? '未选择'}`); return }
+      if (verb === '新对话' || verb === 'reset') { conv.sessionId = null; convs[key] = conv; await this.save(); await reply('已开始新对话。'); return }
+      const target = allowedDs.find(d => d.name === cmd[2].trim() || d.id === cmd[2].trim())
+      if (!target) { await reply(`找不到可用的数据源「${cmd[2]}」。可用：${allowedDs.map(d => d.name).join('、')}`); return }
+      conv.datasourceId = target.id
+      if (conv.sessionId) { this.state.sessions[conv.sessionId] = target.id }
+      convs[key] = conv
+      await this.save()
+      await reply(`已切换到数据源「${target.name}」。`)
+      return
+    }
+    const ds = this.findDatasource(conv.datasourceId) ?? allowedDs[0]
+    if (!ds) { await reply('没有可访问的数据源，请联系管理员。'); return }
+    this.assertAccess(actor, ds)
+    if (!this.ctx.get('sessionController')) { await reply('当前 Harness 不支持创建会话（缺少 sessionController）。'); return }
+    void Promise.resolve(m.react?.('working')).catch(() => {})
+    if (!conv.chatName && m.chatType === 'group') {
+      try { conv.chatName = typeof m.chatName === 'function' ? await m.chatName() : m.chatName ?? undefined } catch {}
+      if (!conv.chatName) delete conv.chatName
+    }
+    const channel = m.channelId ? this.state.channels.find(c => c.id === m.channelId) : undefined
+    const buttons = channel ? Boolean(kindOf(channel.type)?.kind.capabilities?.buttons) : platform === 'lark'
+    // One prompt at a time per conversation, so each question gets its own answer.
+    await this.serialize(`bot:${key}`, async () => {
+      const started = Date.now()
+      // Another message of this conversation may have created the session meanwhile.
+      const latest = convs[key]
+      if (latest?.sessionId && !conv.sessionId) conv.sessionId = latest.sessionId
+      const prepare = async (sessionId) => {
+        conv.sessionId = sessionId
+        conv.datasourceId = ds.id
+        conv.lastAt = started
+        conv.lastQuestion = text.slice(0, 200)
+        conv.lastActor = actor.name
+        convs[key] = conv
+        this.state.sessions[sessionId] = ds.id
+        this.state.sessionActors ??= {}
+        this.state.sessionActors[sessionId] = { id: actor.id, name: actor.name, kind: platform, platform, datasourceIds: actor.datasourceIds, role: actor.role, rowRules: actor.rowRules ?? [] }
+        await this.save()
+      }
+      const where = m.chatType === 'group' ? `群「${conv.chatName ?? m.chatId}」` : '私聊'
+      const prompt = `[${name}${where} · ${actor.name}${actor.role === 'viewer' ? ' · 只读成员' : ''}] ${text}\n\n（回答会以${name}消息发回该聊天：请用简洁的中文 Markdown 写结论，必要时附上查询结果；不要调用 nl2sql_send，也不要向用户提问——有歧义时说明你的假设后直接回答。${actor.role === 'viewer' ? '该成员是只读角色：只能用 nl2sql_metric 查询指标库，或复用 nl2sql_knowledge 中已验证的样例 SQL；不能自由编写 SQL。' : ''}）`
+      const requestId = platform === 'lark' ? `lark-${m.messageId}` : `${platform}-${m.chatId}-${m.messageId}`
+      const turn = await this.runAgentTurn({ sessionId: conv.sessionId, title: `${name} · ${conv.chatName ?? actor.name}`, requestId, text: prompt, prepare, timeoutMs: 600000 })
+      let body = turn.text
+      if (turn.reason === 'timeout') body = `${body ? `${body}\n\n` : ''}<font color='grey'>（查询超过 10 分钟仍未完成，已停止。请缩小范围后重试。）</font>`
+      if (turn.reason === 'input-required') body = `${body ? `${body}\n\n` : ''}<font color='grey'>（需要在 Harness 中确认后才能继续，已取消本次回答。）</font>`
+      const results = turn.resultIds.map(id => this.lookupResult(id)).filter(Boolean).filter(r => { try { this.assertResultAccess(r, { ...actor, kind: platform }); return true } catch { return false } }).slice(-4)
+      // Buttons (拆分 / 为什么变化 / 明细 / 固定到看板) carry opaque tokens only.
+      const shown = buttons ? await this.withResultActions(results, { actor, sessionId: conv.sessionId, channelId: m.channelId, platform, chatId: m.chatId, chatType: m.chatType, replyTo: m.messageId, depth: 0 }) : results
+      let status = turn.reason === 'idle' ? 'ok' : 'error'
+      let error = turn.reason === 'idle' ? undefined : turn.reason
+      try {
+        await m.reply({ title: text.length > 40 ? `${text.slice(0, 40)}…` : text, text: body || '（没有生成文字回答）', results: shown, footer: `数据问答 · ${ds.name} · ${actor.name}` })
+      } catch (e) {
+        status = 'error'
+        error = e.message
+        await reply(String(body || e.message).slice(0, 3000))
+      }
+      void Promise.resolve(m.react?.(status === 'ok' ? 'done' : 'failed')).catch(() => {})
+      this.recordDelivery({ channel: { id: m.channelId ?? SOURCE(platform), name: `${name}机器人 · ${conv.chatName ?? actor.name}`, platform }, title: text.slice(0, 60), status, ...(error ? { error } : {}), results: results.length, source: SOURCE(platform), sessionId: conv.sessionId, elapsedMs: Date.now() - started })
+      await this.save()
+    })
+  },
+
+  /** Run tasks with the same key one after another. */
+  serialize(key, task) {
+    this.queues ??= new Map()
+    const prev = this.queues.get(key) ?? Promise.resolve()
+    const next = prev.catch(() => {}).then(task)
+    this.queues.set(key, next)
+    next.finally(() => { if (this.queues.get(key) === next) this.queues.delete(key) }).catch(() => {})
+    return next
+  },
+
+  /** Bound the conversation map (most recent first). */
+  pruneBotConversations() {
+    const convs = Object.values(this.state.botConversations ?? {}).sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0))
+    if (convs.length > CONVERSATIONS_MAX) for (const c of convs.slice(CONVERSATIONS_MAX)) delete this.state.botConversations[c.key]
+  },
+
+  /**
+   * Prompt an nl2sql session and collect exactly the answer of that prompt's
+   * turn. Creates (or recreates, if archived / missing) the session, handles
+   * timeouts and pending questions by cancelling the turn.
+   * @returns {{ sessionId, text, resultIds, reason: 'idle'|'timeout'|'input-required' }}
+   */
+  async runAgentTurn({ sessionId, title, requestId, text, prepare, timeoutMs = 300000 }) {
+    const controller = this.ctx.get('sessionController')
+    const registry = this.ctx.get('workspaceRegistry')
+    const create = async () => {
+      const created = await controller.create({ agentPreset: PRESET_ID, ...(this.state.settings.botCwd ? { cwd: this.state.settings.botCwd } : {}) })
+      try { await controller.rename?.({ sessionId: created.sessionId, title }) } catch {}
+      return created.sessionId
+    }
+    let sid = sessionId
+    if (sid && (registry?.archivedSessionIds?.includes?.(sid))) sid = null
+    if (!sid) sid = await create()
+    await prepare?.(sid)
+    const send = (id) => controller.prompt({ requestId, sessionId: id, mode: 'queue', content: [{ type: 'text', text }] }, new AbortController().signal)
+    try {
+      await send(sid)
+    } catch (error) {
+      const code = error?.code ?? ''
+      if (!/not-found|archived|writer-held/.test(code) && !/not found|archived/i.test(error?.message ?? '')) throw error
+      sid = await create()
+      await prepare?.(sid)
+      await send(sid)
+    }
+    const waited = await controller.wait({ sessionId: sid, timeoutMs, maxMessages: 1 }, new AbortController().signal)
+    const reason = waited?.reason ?? 'idle'
+    if (reason !== 'idle') { try { controller.cancel({ sessionId: sid }) } catch {} }
+    const answer = await this.collectTurnByRequest(sid, requestId)
+    return { sessionId: sid, reason, ...answer }
+  },
+
+  /** Session events (live or persisted). */
+  async sessionEvents(sessionId) {
+    const live = this.ctx.get('agents')?.get(sessionId)?.session
+    const read = (session) => session.snapshotEvents()
+    if (live) return read(live)
+    const q = this.ctx.get('sessionQuery')
+    return q ? q.inspectSession(sessionId, read) : []
+  },
+
+  /**
+   * Answer of the turn started by the user message carrying `requestId`:
+   * the last assistant text of that turn and the nl2sql resultIds it produced.
+   */
+  async collectTurnByRequest(sessionId, requestId) {
+    const events = await this.sessionEvents(sessionId)
+    const at = events.findIndex(e => e.type === 'user/message' && (e.data?.source?.rpcId === requestId || e.data?.source?.requestId === requestId))
+    if (at < 0) return { text: '', resultIds: [] }
+    let turn
+    for (let i = at + 1; i < events.length; i++) {
+      const e = events[i]
+      if (e.type === 'turn/start') { turn = e.data.turn; break }
+      if (e.data?.turn !== undefined) { turn = e.data.turn; break }
+    }
+    if (turn === undefined) return { text: '', resultIds: [] }
+    let text = ''
+    const resultIds = []
+    for (const e of events.slice(at + 1)) {
+      if (e.data?.turn !== undefined && e.data.turn !== turn) { if (e.data.turn > turn) break; continue }
+      if (e.type === 'assistant/message') {
+        const t = (e.data.message?.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n\n').trim()
+        if (t) text = t
+      }
+      if (e.type === 'tool/result') {
+        const meta = e.data.meta
+        if (meta?.resultId) resultIds.push(meta.resultId)
+        for (const r of meta?.results ?? []) if (r.resultId) resultIds.push(r.resultId)
+      }
+      if (e.type === 'turn/end' && e.data.turn === turn) break
+    }
+    return { text, resultIds: [...new Set(resultIds)] }
+  },
+
+  /** Back-compat for callers that only have the live session and a seq anchor. */
+  collectTurnAnswer(sessionId, afterSeq) {
+    const session = this.ctx.get('agents')?.get(sessionId)?.session
+    if (!session) return { text: '', resultIds: [] }
+    let text = ''
+    const resultIds = []
+    for (const e of session.snapshotEvents().filter(x => x.seq > afterSeq)) {
+      if (e.type === 'assistant/message') { const t = (e.data.message?.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n\n').trim(); if (t) text = t }
+      if (e.type === 'tool/result') { const meta = e.data.meta; if (meta?.resultId) resultIds.push(meta.resultId); for (const r of meta?.results ?? []) if (r.resultId) resultIds.push(r.resultId) }
+    }
+    return { text, resultIds: [...new Set(resultIds)] }
+  },
+
+  // ------------------------------------------------------------- action tokens
+
+  /** In-memory token cache (legacy name kept for callers/tests). */
+  get larkActionTokens() {
+    return this.actionTokens
+  },
+
+  /** Store context for a message's buttons; returns the opaque token. */
+  createActionToken(ctx) {
+    const token = randomBytes(9).toString('base64url')
+    const now = Date.now()
+    const body = { resultId: ctx.resultId, sessionId: ctx.sessionId ?? null, channelId: ctx.channelId ?? null, platform: ctx.platform ?? 'lark', chatId: ctx.chatId ?? null, chatType: ctx.chatType === 'p2p' ? 'p2p' : 'group', replyTo: ctx.replyTo ?? null, depth: ctx.depth ?? 0, ownerRole: ctx.ownerRole ?? null }
+    this.actionTokens ??= new Map()
+    this.actionTokens.set(token, { ...body, created: now })
+    while (this.actionTokens.size > ACTION_TOKEN_MAX) this.actionTokens.delete(this.actionTokens.keys().next().value)
+    try {
+      this.store?.putActionToken(token, body, now)
+      if ((this.actionTokenWrites = (this.actionTokenWrites ?? 0) + 1) % 200 === 0) this.store?.pruneActionTokens(ACTION_TOKEN_TTL_MS, ACTION_TOKEN_MAX)
+    } catch {}
+    return token
+  },
+
+  /** Context for a token, or undefined when unknown / expired. */
+  lookupActionToken(token, now = Date.now()) {
+    if (typeof token !== 'string' || !/^[\w-]{8,32}$/.test(token)) return undefined
+    let ctx = this.actionTokens?.get(token)
+    if (!ctx) { try { ctx = this.store?.getActionToken(token) } catch {} }
+    if (!ctx || now - ctx.created > ACTION_TOKEN_TTL_MS) return undefined
+    return ctx
+  },
+
+  createLarkActionToken(ctx) { return this.createActionToken({ platform: 'lark', ...ctx }) },
+  lookupLarkActionToken(token, now) { return this.lookupActionToken(token, now) },
+
+  // ------------------------------------------------------------- building actions
+
+  /**
+   * ActionSpec for one result shown to `actor` in a chat, or undefined when
+   * nothing applies. Never throws.
+   */
+  async resultActions(result, { actor, sessionId, channelId, platform, chatId, chatType, replyTo, depth = 0 } = {}) {
+    try {
+      if (!result?.resultId || result.error || depth >= ACTION_MAX_DEPTH) return undefined
+      const ds = this.findDatasource(result.datasourceId)
+      if (!ds) return undefined
+      const dialect = ds.type ?? 'mysql'
+      const role = actor?.role ?? 'analyst'
+      const token = this.createActionToken({ resultId: result.resultId, sessionId, channelId, platform, chatId, chatType, replyTo, depth, ownerRole: role })
+      const aggregate = hasAggregate(result, dialect)
+      const buttons = []
+      let select
+      if (aggregate) {
+        let dims = []
+        try { dims = (await this.drillDimensions(result.resultId)).dimensions } catch {}
+        const xName = result.chart?.x
+        dims = dims.filter(d => d.column !== xName && d.column.split('.').pop() !== xName).slice(0, 6)
+        if (dims.length) select = { placeholder: '按维度拆分', value: { a: 'drill', t: token }, options: dims.map(d => ({ text: d.label && d.label !== d.column ? `${d.label}（${d.column}）` : d.column, value: d.column })) }
+      }
+      const xi = result.chart?.x ? result.columns.findIndex(c => c.name === result.chart.x) : -1
+      const points = xi >= 0 ? result.rows.filter(r => r[xi] !== null && r[xi] !== undefined).length : 0
+      const timeLike = xi >= 0 && (result.columns[xi].kind === 'time' || ['line', 'area'].includes(result.chart?.type))
+      if (aggregate && timeLike && points >= 2) buttons.push({ text: '为什么变化', value: { a: 'why', t: token } })
+      if (xi >= 0 && points >= 1 && role !== 'viewer') buttons.push({ text: '明细', value: { a: 'detail', t: token } })
+      if (role === 'admin' || role === 'analyst') buttons.push({ text: '固定到看板', value: { a: 'pin', t: token } })
+      if (!select && !buttons.length) return undefined
+      return { ...(select ? { select } : {}), buttons }
+    } catch (error) {
+      console.warn('nl2sql bot: cannot build actions: %s', error.message)
+      return undefined
+    }
+  },
+
+  /** Results with their ActionSpec attached as `actions`. */
+  async withResultActions(results, ctx) {
+    const out = []
+    for (const r of results) {
+      const actions = await this.resultActions(r, ctx)
+      out.push(actions ? { ...r, actions } : r)
+    }
+    return out
+  },
+
+  larkCardActions(result, ctx) { return this.resultActions(result, { platform: 'lark', ...ctx }) },
+  withLarkCardActions(results, ctx) { return this.withResultActions(results, { platform: 'lark', ...ctx }) },
+
+  // ------------------------------------------------------------- clicks
+
+  /**
+   * An InboundAction. Authorizes synchronously and returns a toast quickly
+   * (Lark waits at most 3 s); the analysis runs in the background and replies
+   * in the chat with a new message.
+   */
+  async handleBotAction(a) {
+    if (!a?.operator?.id) return undefined
+    const platform = a.platform ?? 'lark'
+    const operatorId = String(a.operator.id)
+    const verb = a.value?.a
+    const ctx = this.lookupActionToken(a.value?.t)
+    const deny = (msg, detail) => { this.auditAdmin(`${SOURCE(platform)}.action.denied`, `${operatorId} · ${verb ?? '?'} · ${detail ?? msg}`); return toast('error', msg) }
+    // Per-operator rate limit.
+    this.actionRate ??= new Map()
+    const now = Date.now()
+    const rateKey = `${platform}:${operatorId}`
+    const last = this.actionRate.get(rateKey) ?? 0
+    if (now - last < ACTION_RATE_MS) return toast('warning', '操作太频繁，请稍后再试。')
+    this.actionRate.set(rateKey, now)
+    if (this.actionRate.size > 2000) for (const [k, t] of this.actionRate) if (now - t > ACTION_RATE_MS) this.actionRate.delete(k)
+
+    if (!ACTIONS.has(verb) || !ctx) return deny('该按钮已过期或无效，请重新提问。', 'unknown/expired token')
+    if ((ctx.platform ?? 'lark') !== platform || (ctx.channelId && a.channelId && ctx.channelId !== a.channelId)) return deny('该按钮不属于当前机器人。', 'channel mismatch')
+    if (ctx.chatId && a.chatId && String(ctx.chatId) !== String(a.chatId)) return deny('该按钮不属于当前聊天。', 'chat mismatch')
+    // Who clicked: resolved from our member list, never from the callback value.
+    const chatId = ctx.chatId ?? a.chatId
+    const resolved = this.resolveActor({ platform, userId: operatorId, email: a.operator.email, name: a.operator.name, chatId: chatId != null ? String(chatId) : chatId, chatType: ctx.chatType ?? 'group' })
+    if (resolved.refused) return deny(resolved.refused, 'actor refused')
+    const actor = { ...resolved.actor, kind: platform }
+    const r = this.lookupResult(ctx.resultId)
+    if (!r) return deny('结果已过期，请重新提问。', 'result expired')
+    try { this.assertResultAccess(r, actor) } catch (error) { return deny(toUserError(error).message, `${actor.name}: ${error.message}`) }
+    if (actor.role === 'viewer') {
+      // Viewers may only act on governed results (produced under viewer rules, or a verified example / dashboard SQL).
+      const ds = this.findDatasource(r.datasourceId)
+      const governed = ctx.ownerRole === 'viewer' || (ds && this.isVerifiedExample(ds, r.baseSql ?? r.sql))
+      if (!governed || verb === 'detail' || verb === 'pin') return deny(verb === 'pin' ? '只读成员不能固定到看板。' : verb === 'detail' ? '只读成员不能查看明细数据。' : '只读成员只能分析指标库或已验证问答的结果。', `${actor.name}: viewer`)
+    }
+    if (verb === 'pin' && actor.role !== 'admin' && actor.role !== 'analyst') return deny('只有管理员或分析师可以固定到看板。', `${actor.name}: role ${actor.role}`)
+    let dimension
+    if (verb === 'drill') {
+      dimension = typeof a.option === 'string' ? a.option : undefined
+      let allowed = []
+      try { allowed = (await this.drillDimensions(r.resultId)).dimensions.map(d => d.column) } catch {}
+      if (!dimension || !allowed.includes(dimension)) return deny('请选择一个有效的拆分维度。', `invalid dimension ${String(dimension).slice(0, 40)}`)
+    }
+    const deliveryChannel = { id: a.channelId ?? SOURCE(platform), name: `${label(platform)}机器人 · ${actor.name}`, platform }
+
+    if (verb === 'pin') {
+      try {
+        const widget = await this.pinWidget({ title: r.title || `${label(platform)}结果`, sql: r.baseSql ?? r.sql, datasourceId: r.datasourceId, chart: r.chart })
+        const board = this.currentDashboardObj()
+        this.auditAdmin(`${SOURCE(platform)}.pin`, `${actor.name} · ${widget.title} → ${board.name}`, actor)
+        this.recordDelivery({ channel: deliveryChannel, title: `固定：${widget.title}`.slice(0, 60), status: 'ok', results: 0, source: SOURCE(platform), sessionId: ctx.sessionId, elapsedMs: Date.now() - now })
+        await this.save()
+        return toast('success', `已固定到看板「${board.name}」`)
+      } catch (error) {
+        return toast('error', `固定失败：${toUserError(error).message}`.slice(0, 200))
+      }
+    }
+
+    const job = this.runBotAction({ verb, ctx, r, actor, dimension, a, deliveryChannel })
+    this.botActionJobs ??= new Set()
+    this.botActionJobs.add(job)
+    job.finally(() => this.botActionJobs.delete(job)).catch(() => {})
+    return toast('info', '正在分析…')
+  },
+
+  async runBotAction({ verb, ctx, r, actor, dimension, a, deliveryChannel }) {
+    const platform = a.platform ?? 'lark'
+    const started = Date.now()
+    const replyTo = ctx.replyTo ?? a.messageId
+    const what = verb === 'drill' ? `拆分：${dimension}` : verb === 'why' ? '为什么变化' : `明细：${r.chart?.x ?? ''}`
+    const footer = `数据问答 · ${r.datasourceName ?? ''} · ${actor.name}`
+    let status = 'ok'
+    let error
+    let resultsCount = 0
+    try {
+      let message
+      if (verb === 'drill' || verb === 'detail') {
+        let xValue
+        if (verb === 'detail') {
+          const xi = r.columns.findIndex(c => c.name === r.chart?.x)
+          xValue = r.rows.map(row => row[xi]).filter(v => v !== null && v !== undefined).at(-1)
+        }
+        const out = await this.drill({ resultId: r.resultId, mode: verb === 'drill' ? 'breakdown' : 'detail', dimension, xValue, sessionId: ctx.sessionId ?? undefined, actor, source: SOURCE(platform) })
+        const results = await this.withResultActions([out], { actor, sessionId: ctx.sessionId, channelId: ctx.channelId ?? a.channelId, platform, chatId: ctx.chatId ?? a.chatId, chatType: ctx.chatType, replyTo, depth: (ctx.depth ?? 0) + 1 })
+        resultsCount = 1
+        message = { title: out.title || what, text: verb === 'detail' ? `「${r.title || '结果'}」在 ${r.chart?.x}=${xValue} 的明细（最多 200 行）。` : `「${r.title || '结果'}」按 ${dimension} 拆分。`, results, footer }
+      } else {
+        const out = await this.explainChange({ resultId: r.resultId, sessionId: ctx.sessionId ?? undefined, actor })
+        const top = out.dimensions.find(d => d.attribution)
+        const rows = (top?.attribution.items ?? []).slice(0, 8)
+        const table = rows.length ? `\n\n| ${top.dimension} | ${out.baseline} | ${out.current} | 变化 |\n|---|---|---|---|\n${rows.map(i => `| ${i.value ?? 'NULL'} | ${i.baseline} | ${i.current} | ${i.delta >= 0 ? '+' : ''}${i.delta} |`).join('\n')}` : ''
+        message = { title: `为什么变化 · ${r.title || ''}`.slice(0, 80), text: `${out.summary}${table}`, results: [], footer }
+      }
+      await a.reply(message, { replyTo })
+    } catch (e) {
+      status = 'error'
+      error = toUserError(e).message
+      const text = `${what} 失败：${error}`.slice(0, 1000)
+      try { if (a.replyText) await a.replyText(text, { replyTo }); else await a.reply({ title: what, text }, { replyTo }) } catch {}
+    }
+    this.auditAdmin(`${SOURCE(platform)}.action`, `${actor.name} · ${what} · ${r.resultId}${error ? ` · ${error}` : ''}`, actor)
+    this.recordDelivery({ channel: deliveryChannel, title: what.slice(0, 60), status, ...(error ? { error } : {}), results: resultsCount, source: SOURCE(platform), sessionId: ctx.sessionId, elapsedMs: Date.now() - started })
+    await this.save()
+  },
+}