@modesto_ma/dsh-channels 0.5.0-beta.1 → 0.5.0-beta.3

package/src/feishu/wiki/base-tools.ts

@@ -0,0 +1,423 @@
+/**
+ * Wiki Base (多维表格) tools: `feishu_wiki_base_read` (switch
+ * `feishuTools.wikiRead`) and `feishu_wiki_base_edit` (switch
+ * `feishuTools.wikiWrite`).
+ *
+ * Both run through the same gates as the docx tools (whitelist, `wikiRoots`
+ * containment, consent cards). Reading shares the docx read grant per Session
+ * and document. Editing changes records only (no table or field structure):
+ * on a base the app owns it may create, update, and delete records; on any
+ * other base it may only create records, so existing data written by people
+ * is never changed. Every edit asks on a consent card. Feishu offers no
+ * revision precondition for record writes, and applies them asynchronously.
+ *
+ * @module dsh-channels/feishu/wiki/base-tools
+ */
+
+import { z } from 'zod'
+import type { WikiNode } from './api.ts'
+import { BASE_BATCH_MAX_RECORDS } from './base-api.ts'
+import type { BaseApi, BaseField, BaseRecordFields, BaseTable } from './base-api.ts'
+import { parseWikiRef } from './links.ts'
+import { display, failure, failureOf, guarded, nodeUrl, ownedByApp, parseArgs, preview } from './shared.ts'
+import type { WikiCallContext, WikiFailure, WikiToolKit, WikiToolSpec } from './shared.ts'
+
+/** Model-facing tool names; stable across releases (session history references them). */
+export const WIKI_BASE_READ_TOOL_NAME = 'feishu_wiki_base_read'
+export const WIKI_BASE_EDIT_TOOL_NAME = 'feishu_wiki_base_edit'
+
+/** Most operations one `feishu_wiki_base_edit` call may apply. */
+export const WIKI_BASE_EDIT_MAX_OPERATIONS = 10
+
+/** Record page size bounds of `feishu_wiki_base_read`. */
+const READ_DEFAULT_LIMIT = 50
+const READ_MAX_LIMIT = 200
+
+/** Records of each operation shown on a consent card. */
+const CARD_PREVIEW_RECORDS = 3
+
+// ---- Arguments ----------------------------------------------------------
+
+const refSchema = z.string().trim().min(1).max(2048)
+const nameSchema = z.string().trim().min(1).max(200)
+const recordIdSchema = z.string().trim().min(1).max(64)
+const fieldMapSchema = z.record(z.string().min(1).max(200), z.unknown())
+  .refine(map => Object.keys(map).length > 0, '至少包含一个字段')
+
+export const wikiBaseReadArgsSchema = z.object({
+  doc: refSchema,
+  table: nameSchema.optional(),
+  filter: z.object({
+    logic: z.enum(['and', 'or']).optional(),
+    conditions: z.array(z.array(z.unknown()).min(2).max(3)).min(1).max(50),
+  }).strict().optional(),
+  sort: z.array(z.object({ field: nameSchema, desc: z.boolean().optional() }).strict()).min(1).max(10).optional(),
+  keyword: z.string().trim().min(1).max(200).optional(),
+  search_fields: z.array(nameSchema).min(1).max(20).optional(),
+  fields: z.array(nameSchema).min(1).max(100).optional(),
+  view_id: nameSchema.optional(),
+  offset: z.number().int().min(0).optional(),
+  limit: z.number().int().min(1).max(READ_MAX_LIMIT).optional(),
+}).strict()
+
+const baseOperationSchema = z.discriminatedUnion('command', [
+  z.object({ command: z.literal('create'), records: z.array(fieldMapSchema).min(1).max(BASE_BATCH_MAX_RECORDS) }).strict(),
+  z.object({
+    command: z.literal('update'),
+    records: z.array(z.object({ record_id: recordIdSchema, fields: fieldMapSchema }).strict()).min(1).max(BASE_BATCH_MAX_RECORDS),
+  }).strict(),
+  z.object({ command: z.literal('delete'), record_ids: z.array(recordIdSchema).min(1).max(BASE_BATCH_MAX_RECORDS) }).strict(),
+])
+
+export type WikiBaseOperation = z.infer<typeof baseOperationSchema>
+
+export const wikiBaseEditArgsSchema = z.object({
+  doc: refSchema,
+  table: nameSchema,
+  operations: z.array(baseOperationSchema).min(1).max(WIKI_BASE_EDIT_MAX_OPERATIONS),
+}).strict()
+
+// ---- Results ------------------------------------------------------------
+
+/** One field as the tools report it: id, name, type, and Feishu's remaining properties. */
+export type WikiBaseFieldView = Readonly<Record<string, unknown>> & {
+  readonly field_id: string
+  readonly name: string
+  readonly type: string
+}
+
+/** Successful `feishu_wiki_base_read`. */
+export interface WikiBaseReadValue {
+  readonly ok: true
+  readonly title: string
+  readonly node_token: string
+  readonly url: string
+  readonly tables: ReadonlyArray<{ readonly table_id: string; readonly name: string }>
+  /** The table read; absent when the call only listed the tables. */
+  readonly table_id?: string
+  readonly fields?: readonly WikiBaseFieldView[]
+  readonly records?: ReadonlyArray<{ readonly record_id: string; readonly fields: Readonly<Record<string, unknown>> }>
+  readonly has_more?: boolean
+  /** Offset of the next page when `has_more`. */
+  readonly next_offset?: number
+  readonly timezone?: string
+  readonly ignored_fields?: readonly string[]
+  /** What `feishu_wiki_base_edit` may do here: `all` (owned by the app), `create` (add records only), or `none`. */
+  readonly writable: 'all' | 'create' | 'none'
+  readonly warning?: string
+}
+
+/** Successful `feishu_wiki_base_edit`. */
+export interface WikiBaseEditValue {
+  readonly ok: true
+  readonly title: string
+  readonly node_token: string
+  readonly url: string
+  readonly table_id: string
+  readonly applied: number
+  readonly created_record_ids: readonly string[]
+  readonly updated: number
+  readonly deleted: number
+  readonly ignored_fields: readonly string[]
+}
+
+// ---- Descriptions -------------------------------------------------------
+
+const VALUE_NOTE = '单元格取值：文本为字符串；数字为数字；单选/多选为选项名数组（如 ["进行中"]，单选也是数组）；日期为 "2026-03-24 10:00" 或毫秒时间戳；'
+  + '复选框为布尔；人员为 [{"id":"ou_xxx"}]；关联为 [{"id":"rec_xxx"}]；null 清空。公式、查找引用、创建时间等字段只读。'
+
+const READ_DESCRIPTION =
+  '读取知识库中的飞书多维表格（bitable）。doc 传知识库节点链接或 node_token。'
+  + '第一次读取某个多维表格会在话题里弹出授权卡，由话题发起人确认，确认后本话题内再次读取不再询问；等待期间不要重复调用。'
+  + '不传 table 时只返回数据表列表；传 table（table_id 或表名）时返回字段列表和记录。'
+  + 'filter 形如 {"logic":"and","conditions":[["状态","intersects",["进行中"]],["金额",">=",100],["备注","non_empty"]]}，'
+  + '运算符有 == != > >= < <= intersects（包含）disjoint（不包含）empty non_empty；日期条件用 "ExactDate(2026-08-07)"，日期不支持 >=。'
+  + 'sort 形如 [{"field":"更新时间","desc":true}]；keyword 为关键词搜索，search_fields 指定搜索的字段（默认主字段）；fields 只返回指定字段。'
+  + `分页用 offset/limit（limit 默认 ${READ_DEFAULT_LIMIT}，最多 ${READ_MAX_LIMIT}），has_more 为 true 时用 next_offset 继续。`
+  + 'writable 说明能做哪些修改：all 表示可增改删记录（本应用创建的表），create 表示只能新增记录，none 表示不能修改。'
+
+const EDIT_DESCRIPTION =
+  '修改知识库中飞书多维表格（bitable）某个数据表的记录。先用 feishu_wiki_base_read 读取字段列表，按字段名写入。'
+  + `operations 按顺序执行（最多 ${WIKI_BASE_EDIT_MAX_OPERATIONS} 个，每个最多 ${BASE_BATCH_MAX_RECORDS} 条记录）：`
+  + 'create（records 为字段名→值的对象数组）、update（records 为 {record_id, fields} 数组，只改给出的字段）、delete（record_ids）。'
+  + '本应用创建的多维表格可以增改删；其他多维表格只能新增记录，不能修改或删除已有记录。不会修改数据表和字段结构。'
+  + VALUE_NOTE
+  + '写入是异步生效的，立刻读取可能还看不到。每次修改都会在话题里弹出授权卡，由话题发起人确认后才执行；等待期间不要重复调用。'
+
+// ---- Parameters ---------------------------------------------------------
+
+const REF_DESCRIPTION = '知识库节点链接 https://<租户>.feishu.cn/wiki/<node_token> 或 node_token'
+const TABLE_PROPERTY = { type: 'string', description: '数据表 table_id 或表名' }
+const FIELD_MAP_PROPERTY = { type: 'object', description: '字段名（或字段 id）→ 值', additionalProperties: true }
+
+const READ_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    doc: { type: 'string', description: REF_DESCRIPTION },
+    table: { ...TABLE_PROPERTY, description: '数据表 table_id 或表名；不传只列出数据表' },
+    filter: {
+      type: 'object',
+      properties: {
+        logic: { type: 'string', enum: ['and', 'or'] },
+        conditions: { type: 'array', items: { type: 'array', description: '[字段, 运算符, 值]；empty / non_empty 不带值' } },
+      },
+      required: ['conditions'],
+      additionalProperties: false,
+    },
+    sort: {
+      type: 'array',
+      items: { type: 'object', properties: { field: { type: 'string' }, desc: { type: 'boolean' } }, required: ['field'], additionalProperties: false },
+    },
+    keyword: { type: 'string', description: '关键词搜索' },
+    search_fields: { type: 'array', items: { type: 'string' }, description: 'keyword 搜索的字段，默认主字段' },
+    fields: { type: 'array', items: { type: 'string' }, description: '只返回这些字段' },
+    view_id: { type: 'string', description: '按视图读取（应用视图的筛选与排序）' },
+    offset: { type: 'integer', minimum: 0 },
+    limit: { type: 'integer', minimum: 1, maximum: READ_MAX_LIMIT },
+  },
+  required: ['doc'],
+  additionalProperties: false,
+}
+
+const EDIT_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    doc: { type: 'string', description: REF_DESCRIPTION },
+    table: TABLE_PROPERTY,
+    operations: {
+      type: 'array',
+      minItems: 1,
+      maxItems: WIKI_BASE_EDIT_MAX_OPERATIONS,
+      items: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', enum: ['create', 'update', 'delete'] },
+          records: {
+            type: 'array',
+            maxItems: BASE_BATCH_MAX_RECORDS,
+            description: 'create：字段映射数组；update：{record_id, fields} 数组',
+            items: {
+              type: 'object',
+              properties: { record_id: { type: 'string' }, fields: FIELD_MAP_PROPERTY },
+              additionalProperties: true,
+            },
+          },
+          record_ids: { type: 'array', maxItems: BASE_BATCH_MAX_RECORDS, items: { type: 'string' }, description: 'delete 的记录 id' },
+        },
+        required: ['command'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['doc', 'table', 'operations'],
+  additionalProperties: false,
+}
+
+// ---- Shared steps -------------------------------------------------------
+
+interface BaseTarget {
+  readonly context: WikiCallContext
+  readonly bases: BaseApi
+  readonly node: WikiNode
+  readonly url: string
+}
+
+async function baseTarget(kit: WikiToolKit, context: WikiCallContext, doc: string): Promise<BaseTarget | WikiFailure> {
+  const bases = context.bases
+  if (bases === undefined) return failure('CHANNEL_UNAVAILABLE')
+  const ref = parseWikiRef(doc)
+  if (ref === undefined) return failure('INVALID_REFERENCE')
+  const node = await kit.containedNode(context, ref)
+  if ('ok' in node) return node
+  if (node.objType !== 'bitable') return failure('UNSUPPORTED_TYPE', `${failure('UNSUPPORTED_TYPE').reason}（该节点类型：${node.objType}）`)
+  return { context, bases, node, url: nodeUrl(context.roots, node) }
+}
+
+function writableOf(kit: WikiToolKit, target: BaseTarget): 'all' | 'create' | 'none' {
+  if (!kit.writeEnabled()) return 'none'
+  return ownedByApp(target.node, target.context.botOpenId) ? 'all' : 'create'
+}
+
+function pickTable(tables: readonly BaseTable[], wanted: string): BaseTable | string {
+  const match = tables.find(table => table.tableId === wanted) ?? tables.find(table => table.name === wanted)
+  if (match !== undefined) return match
+  const list = tables.map(table => `${table.name}（${table.tableId}）`).join('、') || '无'
+  return `找不到数据表「${wanted}」；可用数据表：${list}`
+}
+
+function fieldView(field: BaseField): WikiBaseFieldView {
+  return { ...field.properties, field_id: field.fieldId, name: field.name, type: field.type }
+}
+
+// ---- feishu_wiki_base_read ---------------------------------------------
+
+async function read(kit: WikiToolKit, sessionId: string, rawArgs: Record<string, unknown>, signal: AbortSignal): Promise<object> {
+  const args = parseArgs(WIKI_BASE_READ_TOOL_NAME, wikiBaseReadArgsSchema, rawArgs)
+  const gate = kit.gate(sessionId, WIKI_BASE_READ_TOOL_NAME)
+  if (!gate.ok) return gate
+  return await guarded<WikiBaseReadValue>(kit, WIKI_BASE_READ_TOOL_NAME, async () => {
+    const target = await baseTarget(kit, gate.context, args.doc)
+    if ('ok' in target) return target
+    const denied = await kit.readConsent(sessionId, target.context, target.node, signal)
+    if (denied !== undefined) return denied
+    if (signal.aborted) return failure('ABORTED')
+    const token = target.node.objToken
+    const tables = await target.bases.listTables(token)
+    const base = {
+      ok: true as const,
+      title: target.node.title,
+      node_token: target.node.nodeToken,
+      url: target.url,
+      tables: tables.map(table => ({ table_id: table.tableId, name: table.name })),
+      writable: writableOf(kit, target),
+    }
+    if (args.table === undefined) return base
+    const table = pickTable(tables, args.table)
+    if (typeof table === 'string') return failure('INVALID_OPERATION', table)
+    const fields = await target.bases.listFields(token, table.tableId)
+    const offset = args.offset ?? 0
+    const query = {
+      ...(args.filter === undefined ? {} : { filter: args.filter }),
+      ...(args.sort === undefined ? {} : { sort: args.sort }),
+      ...(args.fields === undefined ? {} : { fields: args.fields }),
+      ...(args.view_id === undefined ? {} : { viewId: args.view_id }),
+      offset,
+      limit: args.limit ?? READ_DEFAULT_LIMIT,
+    }
+    let page
+    if (args.keyword === undefined) {
+      page = await target.bases.listRecords(token, table.tableId, query)
+    } else {
+      const primary = fields[0]?.name
+      const searchFields = args.search_fields ?? (primary === undefined ? [] : [primary])
+      if (searchFields.length === 0) return failure('INVALID_OPERATION', 'keyword 搜索需要 search_fields')
+      page = await target.bases.searchRecords(token, table.tableId, { ...query, keyword: args.keyword, searchFields })
+    }
+    return {
+      ...base,
+      table_id: table.tableId,
+      fields: fields.map(fieldView),
+      records: page.records.map(record => ({ record_id: record.recordId, fields: record.fields })),
+      has_more: page.hasMore,
+      ...(page.hasMore ? { next_offset: offset + page.records.length } : {}),
+      ...(page.timezone === undefined ? {} : { timezone: page.timezone }),
+      ...(page.ignoredFields.length === 0 ? {} : { ignored_fields: page.ignoredFields }),
+    }
+  })
+}
+
+// ---- feishu_wiki_base_edit ---------------------------------------------
+
+function json(value: unknown): string {
+  return preview(JSON.stringify(value) ?? 'null', 120)
+}
+
+function cardLines(operations: readonly WikiBaseOperation[], tableName: string): string[] {
+  const lines = operations.map((operation, index) => {
+    const n = `${index + 1}.`
+    switch (operation.command) {
+      case 'create': {
+        const sample = operation.records.slice(0, CARD_PREVIEW_RECORDS).map(record => `　${json(record)}`)
+        const more = operation.records.length > CARD_PREVIEW_RECORDS ? [`　…（共 ${operation.records.length} 条）`] : []
+        return [`${n} 新增 ${operation.records.length} 条记录`, ...sample, ...more].join('\n')
+      }
+      case 'update': {
+        const sample = operation.records.slice(0, CARD_PREVIEW_RECORDS).map(record => `　${preview(record.record_id, 40)}：${json(record.fields)}`)
+        const more = operation.records.length > CARD_PREVIEW_RECORDS ? [`　…（共 ${operation.records.length} 条）`] : []
+        return [`${n} 修改 ${operation.records.length} 条记录`, ...sample, ...more].join('\n')
+      }
+      case 'delete':
+        return `${n} ⚠️ 删除 ${operation.record_ids.length} 条记录：${preview(operation.record_ids.join('、'), 160)}`
+    }
+  })
+  return [`**数据表**：${preview(tableName, 60)}`, `**将执行 ${operations.length} 个操作**`, ...lines]
+}
+
+async function edit(kit: WikiToolKit, sessionId: string, rawArgs: Record<string, unknown>, signal: AbortSignal): Promise<object> {
+  const args = parseArgs(WIKI_BASE_EDIT_TOOL_NAME, wikiBaseEditArgsSchema, rawArgs)
+  const gate = kit.gate(sessionId, WIKI_BASE_EDIT_TOOL_NAME)
+  if (!gate.ok) return gate
+  return await guarded<WikiBaseEditValue>(kit, WIKI_BASE_EDIT_TOOL_NAME, async () => {
+    const target = await baseTarget(kit, gate.context, args.doc)
+    if ('ok' in target) return target
+    const { node, bases } = target
+    if (writableOf(kit, target) !== 'all') {
+      const changing = args.operations.find(operation => operation.command !== 'create')
+      if (changing !== undefined) {
+        return failure('NOT_OWNED', `这个多维表格不是本应用创建的，只能新增记录，不能${changing.command === 'update' ? '修改' : '删除'}已有记录（所有者：${node.owner ?? '未知'}）`)
+      }
+    }
+    const table = pickTable(await bases.listTables(node.objToken), args.table)
+    if (typeof table === 'string') return failure('INVALID_OPERATION', table)
+    const denied = await kit.consent(sessionId, target.context, 'edit', {
+      title: node.title,
+      url: target.url,
+      location: await kit.locationOf(target.context.api, node),
+      details: cardLines(args.operations, table.name),
+    }, signal)
+    if (denied !== undefined) return denied
+    const created: string[] = []
+    const ignored: string[] = []
+    let updated = 0
+    let deleted = 0
+    for (const [index, operation] of args.operations.entries()) {
+      if (signal.aborted) return { ...failure('ABORTED', `已取消；前 ${index} 个操作已执行`), applied: index }
+      try {
+        switch (operation.command) {
+          case 'create':
+            created.push(...await bases.createRecords(node.objToken, table.tableId, operation.records as BaseRecordFields[]))
+            break
+          case 'update':
+            ignored.push(...await bases.updateRecords(
+              node.objToken,
+              table.tableId,
+              Object.fromEntries(operation.records.map(record => [record.record_id, record.fields as BaseRecordFields])),
+            ))
+            updated += operation.records.length
+            break
+          case 'delete':
+            await bases.deleteRecords(node.objToken, table.tableId, operation.record_ids)
+            deleted += operation.record_ids.length
+            break
+        }
+      } catch (error) {
+        const reason = failureOf(error).reason
+        return { ...failure('EDIT_FAILED', `第 ${index + 1} 个操作失败：${reason}；前 ${index} 个操作已执行`), applied: index }
+      }
+    }
+    return {
+      ok: true,
+      title: node.title,
+      node_token: node.nodeToken,
+      url: target.url,
+      table_id: table.tableId,
+      applied: args.operations.length,
+      created_record_ids: created,
+      updated,
+      deleted,
+      ignored_fields: [...new Set(ignored)],
+    }
+  })
+}
+
+// ---- Specs --------------------------------------------------------------
+
+/** The Base tool family. */
+export const BASE_TOOL_SPECS: readonly WikiToolSpec[] = [
+  {
+    name: WIKI_BASE_READ_TOOL_NAME,
+    access: 'read',
+    description: READ_DESCRIPTION,
+    parameters: READ_PARAMETERS,
+    execute: read,
+    presentCall: args => `读取知识库多维表格：${display(args.doc)}`,
+  },
+  {
+    name: WIKI_BASE_EDIT_TOOL_NAME,
+    access: 'write',
+    description: EDIT_DESCRIPTION,
+    parameters: EDIT_PARAMETERS,
+    execute: edit,
+    presentCall: args => `修改知识库多维表格：${display(args.doc)}`,
+  },
+]

package/src/feishu/wiki/consent.ts

@@ -0,0 +1,183 @@
+/**
+ * Topic-owner consent for wiki tool calls.
+ *
+ * A wiki tool that opens, creates, or edits a document asks the topic owner
+ * on a consent card in the topic and waits for the answer. Only the topic
+ * owner (`route.senderUserId`) can decide; a click by anyone else adds the
+ * owner-only notice once. An unanswered card is denied after the configured
+ * window (`approvalTimeoutMs`). A read consent is remembered per Session and
+ * document, in memory only: it ends with the Session (`/renew`) or the
+ * process. Create and edit consents are never remembered.
+ *
+ * @module dsh-channels/feishu/wiki/consent
+ */
+
+import { randomUUID } from 'node:crypto'
+import { buildWikiConsentCard, buildWikiConsentSettledCard } from '../../cards/wiki.ts'
+import type { WikiConsentAction, WikiConsentCardState, WikiConsentQuestion } from '../../cards/wiki.ts'
+import type { CardActionEvent, FeishuChannel } from '../../feishu-channel.ts'
+import { PendingCardTable } from '../../interactions/pending.ts'
+import type { InteractionRoute, PendingCardEntry } from '../../interactions/pending.ts'
+
+/** How one consent request ended. */
+export type WikiConsentOutcome = 'allowed' | 'denied' | 'expired' | 'cancelled' | 'unavailable'
+
+/** One consent to ask for. */
+export interface WikiConsentRequest {
+  readonly sessionId: string
+  readonly route: InteractionRoute
+  readonly action: WikiConsentAction
+  readonly title: string
+  readonly url?: string
+  readonly location: string
+  readonly details: readonly string[]
+  /** The tool call's abort signal; aborting withdraws the card. */
+  readonly signal: AbortSignal
+}
+
+interface Pending extends PendingCardEntry {
+  readonly question: WikiConsentQuestion
+  resolve(outcome: WikiConsentOutcome): void
+}
+
+export interface WikiConsentDeps {
+  /** Live Feishu channel; undefined while disconnected. */
+  channel(): FeishuChannel | undefined
+  /** Decision window per card, read per request (`approvalTimeoutMs`). */
+  timeoutMs(): number
+  /** Log a non-fatal delivery/update failure. */
+  onError(sessionId: string, error: unknown): void
+}
+
+/** Consent cards for the wiki tools. */
+export class WikiConsent {
+  /** One table per channel instance (cards are patched through their channel). */
+  private table: { channel: FeishuChannel; entries: PendingCardTable<Pending> } | undefined
+  /** sessionId → document ids with a standing read consent. */
+  private readonly readGrants = new Map<string, Set<string>>()
+
+  constructor(private readonly deps: WikiConsentDeps) {}
+
+  /**
+   * Whether the Session already holds a read consent for one document.
+   * @param sessionId The Session.
+   * @param documentId Docx document id.
+   * @returns True when reading needs no new card.
+   */
+  hasReadGrant(sessionId: string, documentId: string): boolean {
+    return this.readGrants.get(sessionId)?.has(documentId) === true
+  }
+
+  /**
+   * Record a standing read consent (after an allowed read, or for a document
+   * the topic owner just approved creating).
+   * @param sessionId The Session.
+   * @param documentId Docx document id.
+   */
+  grantRead(sessionId: string, documentId: string): void {
+    let grants = this.readGrants.get(sessionId)
+    if (grants === undefined) {
+      grants = new Set()
+      this.readGrants.set(sessionId, grants)
+    }
+    grants.add(documentId)
+  }
+
+  /**
+   * Ask the topic owner and wait for the decision. Never rejects.
+   * @param request What to ask.
+   * @returns The outcome; `unavailable` when no card could be delivered.
+   */
+  request(request: WikiConsentRequest): Promise<WikiConsentOutcome> {
+    if (request.signal.aborted) return Promise.resolve('cancelled')
+    const channel = this.deps.channel()
+    if (channel === undefined) return Promise.resolve('unavailable')
+    const table = this.tableFor(channel)
+    const timeoutMs = this.deps.timeoutMs()
+    const question: WikiConsentQuestion = {
+      token: randomUUID(),
+      action: request.action,
+      title: request.title,
+      ...(request.url === undefined ? {} : { url: request.url }),
+      location: request.location,
+      details: request.details,
+      timeoutMs,
+    }
+    return new Promise<WikiConsentOutcome>((resolve) => {
+      const entry: Pending = {
+        token: question.token,
+        sessionId: request.sessionId,
+        route: request.route,
+        messageId: undefined,
+        settled: false,
+        timer: undefined,
+        signal: request.signal,
+        onAbort: undefined,
+        unauthorizedNoted: false,
+        question,
+        resolve,
+      }
+      const onAbort = (): void => this.settle(table, entry, 'cancelled', 'cancelled')
+      entry.onAbort = onAbort
+      request.signal.addEventListener('abort', onAbort, { once: true })
+      table.add(entry)
+      void table.deliver(entry, {
+        card: buildWikiConsentCard(question),
+        onWithdrawn: e => table.patch(e, buildWikiConsentSettledCard(e.question, 'cancelled')),
+        onDelivered: e => table.armTimeout(e, timeoutMs, () => this.settle(table, e, 'expired', 'expired')),
+        onFailure: e => this.settle(table, e, 'unavailable'),
+      })
+    })
+  }
+
+  /**
+   * Route one card button callback to its pending consent; unknown cards are
+   * ignored.
+   * @param event The card action.
+   */
+  onCardAction(event: CardActionEvent): void {
+    const table = this.table?.entries
+    if (table === undefined) return
+    const entry = table.resolveAction(event, (candidate) => {
+      if (candidate.unauthorizedNoted) return
+      candidate.unauthorizedNoted = true
+      table.patch(candidate, buildWikiConsentCard(candidate.question, { unauthorizedNote: true }))
+    })
+    if (entry === undefined) return
+    const decision = (event.action.value as { decision?: unknown } | undefined)?.decision
+    if (decision === 'allow') this.settle(table, entry, 'allowed', 'allowed')
+    else if (decision === 'deny') this.settle(table, entry, 'denied', 'denied')
+  }
+
+  /** Withdraw every pending card and forget every read consent (shutdown). */
+  dispose(): void {
+    const table = this.table?.entries
+    table?.withdrawAll(entry => this.settle(table, entry, 'cancelled', 'cancelled'))
+    this.table = undefined
+    this.readGrants.clear()
+  }
+
+  /** Pending consent count (diagnostics/tests). */
+  pendingCount(): number {
+    return this.table?.entries.count() ?? 0
+  }
+
+  private tableFor(channel: FeishuChannel): PendingCardTable<Pending> {
+    if (this.table?.channel !== channel) {
+      this.table = { channel, entries: new PendingCardTable<Pending>(channel, this.deps.onError) }
+    }
+    return this.table.entries
+  }
+
+  private settle(
+    table: PendingCardTable<Pending>,
+    entry: Pending,
+    outcome: WikiConsentOutcome,
+    cardState?: WikiConsentCardState,
+  ): void {
+    const closed = table.close(entry, () => {
+      if (cardState !== undefined) table.patch(entry, buildWikiConsentSettledCard(entry.question, cardState))
+    })
+    if (closed) entry.resolve(outcome)
+  }
+}