@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/access/store.ts

@@ -0,0 +1,220 @@
+/**
+ * Durable access-control store.
+ *
+ * Reads come from in-memory maps (seeded once from the plugin's
+ * `storageDomain` tables) so admission decisions stay synchronous and cheap;
+ * every mutation writes through to the domain first and then updates memory,
+ * matching the store patterns used for routes and inflight snapshots.
+ *
+ * The tables (`access_groups`, `access_users`, `access_requests`) were added
+ * without bumping the domain version on purpose: the JSON backend's `single`
+ * layout refuses a stored-version mismatch, while unknown/missing tables are
+ * simply empty on load (see `docs/access-control-design.md` §4.2).
+ *
+ * @module dsh-channels/access/store
+ */
+
+import type {
+  AccessGroupRecord,
+  AccessRequestRecord,
+  AccessUserRecord,
+  FeishuDomainHandle,
+} from '../domain.ts'
+
+export interface AccessStoreDeps {
+  /** The open domain handle, or undefined before start / after shutdown. */
+  domain(): FeishuDomainHandle | undefined
+  warn(message: string, ...args: unknown[]): void
+}
+
+/** Read-only whitespace snapshot handed to the pure policy. */
+export interface AccessStoreSnapshot {
+  groups: ReadonlySet<string>
+  users: ReadonlySet<string>
+}
+
+/** One settled authorization request (audit trail). */
+export type AccessRequestStatus = AccessRequestRecord['status']
+
+export class AccessStore {
+  private readonly groups = new Map<string, AccessGroupRecord>()
+  private readonly users = new Map<string, AccessUserRecord>()
+  private readonly requests = new Map<string, AccessRequestRecord>()
+  /** Cached key sets so `snapshot()` can stay allocation-free per message. */
+  private readonly groupKeys = new Set<string>()
+  private readonly userKeys = new Set<string>()
+
+  constructor(private readonly deps: AccessStoreDeps) {}
+
+  /** Seed memory from the durable tables (called once after the domain opens). */
+  load(): void {
+    this.clear()
+    const domain = this.deps.domain()
+    if (domain === undefined) {
+      this.deps.warn('dsh-channels: access tables unavailable; starting with an empty whitelist')
+      return
+    }
+    for (const [key, record] of domain.accessGroups.entries()) {
+      this.groups.set(key, record)
+      this.groupKeys.add(key)
+    }
+    for (const [key, record] of domain.accessUsers.entries()) {
+      this.users.set(key, record)
+      this.userKeys.add(key)
+    }
+    for (const [key, record] of domain.accessRequests.entries()) {
+      this.requests.set(key, record)
+    }
+  }
+
+  /** Drop every in-memory record (shutdown). The domain owns durability. */
+  clear(): void {
+    this.groups.clear()
+    this.users.clear()
+    this.requests.clear()
+    this.groupKeys.clear()
+    this.userKeys.clear()
+  }
+
+  snapshot(): AccessStoreSnapshot {
+    return { groups: this.groupKeys, users: this.userKeys }
+  }
+
+  hasGroup(chatId: string): boolean {
+    return this.groupKeys.has(chatId)
+  }
+
+  hasUser(openId: string): boolean {
+    return this.userKeys.has(openId)
+  }
+
+  getGroup(chatId: string): AccessGroupRecord | undefined {
+    return this.groups.get(chatId)
+  }
+
+  getUser(openId: string): AccessUserRecord | undefined {
+    return this.users.get(openId)
+  }
+
+  /** Every authorized group, oldest first. */
+  groupRecords(): AccessGroupRecord[] {
+    return [...this.groups.values()].sort((left, right) => left.addedAt - right.addedAt)
+  }
+
+  /** Every authorized user, oldest first. */
+  userRecords(): AccessUserRecord[] {
+    return [...this.users.values()].sort((left, right) => left.addedAt - right.addedAt)
+  }
+
+  async addGroup(record: AccessGroupRecord): Promise<AccessGroupRecord> {
+    await this.requireDomain('add access group').accessGroups.put(record.chatId, record)
+    this.groups.set(record.chatId, record)
+    this.groupKeys.add(record.chatId)
+    return record
+  }
+
+  async removeGroup(chatId: string): Promise<boolean> {
+    if (!this.groups.has(chatId)) return false
+    await this.requireDomain('remove access group').accessGroups.delete(chatId)
+    this.groups.delete(chatId)
+    this.groupKeys.delete(chatId)
+    return true
+  }
+
+  async addUser(record: AccessUserRecord): Promise<AccessUserRecord> {
+    await this.requireDomain('add access user').accessUsers.put(record.openId, record)
+    this.users.set(record.openId, record)
+    this.userKeys.add(record.openId)
+    return record
+  }
+
+  async removeUser(openId: string): Promise<boolean> {
+    if (!this.users.has(openId)) return false
+    await this.requireDomain('remove access user').accessUsers.delete(openId)
+    this.users.delete(openId)
+    this.userKeys.delete(openId)
+    return true
+  }
+
+  /** Every authorization request, including settled ones (audit). */
+  requestRecords(): AccessRequestRecord[] {
+    return [...this.requests.values()].sort((left, right) => left.createdAt - right.createdAt)
+  }
+
+  /**
+   * Pending, not-yet-expired requests. Expired-but-unsettled records are
+   * excluded here; `expireRequests()` is the sweep that persists the terminal
+   * state (and lets the card surface patch the DM card).
+   */
+  pendingRequests(now = Date.now()): AccessRequestRecord[] {
+    return this.requestRecords().filter(
+      record => record.status === 'pending' && record.expiresAt > now,
+    )
+  }
+
+  getRequest(token: string): AccessRequestRecord | undefined {
+    return this.requests.get(token)
+  }
+
+  /** The current pending request for one target, if any. */
+  pendingRequestFor(kind: AccessRequestRecord['kind'], targetId: string): AccessRequestRecord | undefined {
+    for (const record of this.requests.values()) {
+      if (record.kind === kind && record.targetId === targetId && record.status === 'pending') {
+        return record
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * True when the same target was denied recently — used to keep a rejected
+   * request from immediately re-notifying the administrator.
+   */
+  recentlyDenied(
+    kind: AccessRequestRecord['kind'],
+    targetId: string,
+    windowMs: number,
+    now = Date.now(),
+  ): boolean {
+    const cutoff = now - windowMs
+    for (const record of this.requests.values()) {
+      if (record.kind === kind && record.targetId === targetId
+        && record.status === 'denied' && record.createdAt >= cutoff) {
+        return true
+      }
+    }
+    return false
+  }
+
+  async putRequest(record: AccessRequestRecord): Promise<AccessRequestRecord> {
+    await this.requireDomain('put access request').accessRequests.put(record.token, record)
+    this.requests.set(record.token, record)
+    return record
+  }
+
+  /**
+   * Mark every pending request past its deadline as expired. Returns the
+   * settled records so the caller can patch stale DM cards.
+   */
+  async expireRequests(now = Date.now()): Promise<AccessRequestRecord[]> {
+    const expired: AccessRequestRecord[] = []
+    for (const record of [...this.requests.values()]) {
+      if (record.status !== 'pending' || record.expiresAt > now) continue
+      const next: AccessRequestRecord = { ...record, status: 'expired' }
+      try {
+        await this.requireDomain('expire access request').accessRequests.put(next.token, next)
+      } catch (error) {
+        this.deps.warn('dsh-channels: persisting expired access request %s failed: %s', next.token, String(error))
+      }
+      this.requests.set(next.token, next)
+      expired.push(next)
+    }
+    return expired
+  }
+
+  private requireDomain(action: string): FeishuDomainHandle {
+    const domain = this.deps.domain()
+    if (domain === undefined) throw new Error(`dsh-channels: access domain not open (${action})`)
+    return domain
+  }
+}

package/src/approvals.ts

@@ -0,0 +1,8 @@
+/**
+ * Public barrel for the HITL approval answerer (implementation lives in
+ * `src/interactions/approvals.ts`).
+ *
+ * @module dsh-channels/approvals
+ */
+
+export * from './interactions/approvals.ts'

package/src/cards/approval.ts

@@ -0,0 +1,114 @@
+/**
+ * HITL approval decision cards (`approval/request`).
+ *
+ * @module dsh-channels/cards/approval
+ */
+
+import { columnSet, divider, markdown, note, standaloneCard, textButton } from './primitives.ts'
+
+// ---- HITL approval decision cards ----------------------------------------
+
+/** Terminal states an approval decision card can settle into. */
+export type ApprovalCardState = 'allowed' | 'denied' | 'expired' | 'cancelled'
+
+/** The question one approval decision card presents. */
+export interface ApprovalQuestion {
+  /** Opaque token binding the card to one pending approval (button value). */
+  token: string
+  /** Model-facing tool name asking for approval (e.g. `bash`). */
+  toolName: string
+  /** The asker's human-readable justification; clipped to a safe length. */
+  reason?: string
+  /** Timeout window shown on the card (milliseconds). */
+  timeoutMs: number
+  /** Session id trace line (omitted when absent). */
+  sessionId?: string
+}
+
+/** Approval card rendering options. */
+export interface ApprovalCardOptions {
+  /** Add the owner-only notice (a non-owner clicked and was ignored). */
+  unauthorizedNote?: boolean
+}
+
+/** Cap on the rendered reason so the card can never approach the size budget. */
+const APPROVAL_REASON_MAX_CHARS = 1_000
+
+/** `⏱ 5 分钟内有效…` — human timeout label (whole minutes, min 1). */
+function approvalTimeoutLabel(timeoutMs: number): string {
+  return `${Math.max(1, Math.round(timeoutMs / 60_000))} 分钟`
+}
+
+/** One approval decision button with its callback payload. */
+function approvalButton(question: ApprovalQuestion, decision: 'allow' | 'deny'): object {
+  const allow = decision === 'allow'
+  return textButton({
+    label: allow ? '✅ 允许' : '❌ 拒绝',
+    type: allow ? 'primary' : 'danger',
+    width: 'fill',
+    margin: '0px',
+    value: { decision, token: question.token },
+  })
+}
+
+/** Two-column row that keeps both decisions side by side. */
+function approvalActions(question: ApprovalQuestion): object {
+  return columnSet((['allow', 'deny'] as const).map(decision => approvalButton(question, decision)))
+}
+
+/** The question summary shared by the pending and settled variants. */
+function approvalQuestionElements(question: ApprovalQuestion): object[] {
+  const elements: object[] = [
+    markdown(`工具 \`${question.toolName}\` 请求执行一个需要授权的操作。`),
+  ]
+  if (question.reason !== undefined && question.reason !== '') {
+    const clipped = question.reason.length > APPROVAL_REASON_MAX_CHARS
+      ? `${question.reason.slice(0, APPROVAL_REASON_MAX_CHARS)}…`
+      : question.reason
+    elements.push(markdown(`> ${clipped.replace(/\s+/gu, ' ')}`))
+  }
+  return elements
+}
+
+/**
+ * The pending approval decision card: question summary, timeout note, and the
+ * enabled allow/deny buttons. Sent as a NEW standalone message anchored to
+ * the session's latest streaming card (never embedded into the streamed
+ * card, whose full-replacement patches would clobber the buttons).
+ */
+export function buildApprovalCard(question: ApprovalQuestion, options: ApprovalCardOptions = {}): object {
+  const elements: object[] = [
+    ...approvalQuestionElements(question),
+    divider(),
+    note(`⏱ ${approvalTimeoutLabel(question.timeoutMs)}内有效，超时自动拒绝 · 允许仅对本次动作生效`),
+  ]
+  if (options.unauthorizedNote === true) {
+    elements.push(note('ℹ️ 仅发起该会话的用户可操作此卡片'))
+  }
+  if (question.sessionId !== undefined) {
+    elements.push(note(`🔑 ${question.sessionId}`))
+  }
+  elements.push(approvalActions(question))
+  return standaloneCard('**⚠️ 需要你的审批**', elements)
+}
+
+/** Settled-card status lines, one per terminal state. */
+const APPROVAL_SETTLED_LINES: Record<ApprovalCardState, string> = {
+  allowed: '✅ 已允许执行',
+  denied: '❌ 已拒绝',
+  expired: '⏱ 已超时未处理，自动拒绝',
+  cancelled: '↩️ 请求已取消',
+}
+
+/**
+ * The terminal replacement for a decision card after the question settles
+ * (decision, timeout, or withdrawal). Keeps the question summary for context
+ * and removes the decision controls entirely.
+ */
+export function buildApprovalSettledCard(question: ApprovalQuestion, state: ApprovalCardState): object {
+  return standaloneCard(`**${APPROVAL_SETTLED_LINES[state]}**`, [
+    ...approvalQuestionElements(question),
+    divider(),
+  ])
+}
+

package/src/cards/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Card rendering barrel: one import specifier for every card this plugin
+ * builds, while the implementations stay grouped by surface.
+ *
+ * @module dsh-channels/cards
+ */
+
+export * from './primitives.ts'
+export * from './streaming.ts'
+export * from './approval.ts'
+export * from './question.ts'

package/src/cards/primitives.ts

@@ -0,0 +1,82 @@
+/**
+ * Card JSON 2.0 primitives shared by every card this plugin renders.
+ *
+ * One envelope + one element vocabulary keeps the byte budget, the width
+ * mode and the callback shape in a single place; card modules only describe
+ * their content.
+ *
+ * @module dsh-channels/cards/primitives
+ */
+
+/** Feishu card JSON schema version this plugin targets. */
+export const CARD_SCHEMA = '2.0'
+
+/** Default card config: full-width cards in the chat pane. */
+export const CARD_CONFIG: Record<string, unknown> = { width_mode: 'fill' }
+
+/** Wrap elements in a card 2.0 envelope. */
+export function card(elements: object[], config: Record<string, unknown> = CARD_CONFIG): object {
+  return { schema: CARD_SCHEMA, config, body: { elements } }
+}
+
+/** Markdown element with optional presentation fields (`text_size`, …). */
+export function markdown(content: string, extra: Record<string, unknown> = {}): object {
+  return { tag: 'markdown', content, ...extra }
+}
+
+/** Small notation-size markdown, used for hints and footers. */
+export function note(content: string): object {
+  return markdown(content, { text_size: 'notation' })
+}
+
+/** Horizontal divider. */
+export function divider(): object {
+  return { tag: 'hr' }
+}
+
+export interface TextButtonOptions {
+  label: string
+  /** Callback payload carried back by `card.action.trigger`. */
+  value: unknown
+  type?: 'default' | 'primary' | 'danger'
+  disabled?: boolean
+  width?: 'fill' | 'default'
+  margin?: string
+}
+
+/** One callback button (`behaviors[0].value` is the plugin's action object). */
+export function textButton(options: TextButtonOptions): object {
+  return {
+    tag: 'button',
+    type: options.type ?? 'default',
+    width: options.width ?? 'fill',
+    margin: options.margin ?? '4px 0 0 0',
+    ...(options.disabled === true ? { disabled: true } : {}),
+    text: { tag: 'plain_text', content: options.label },
+    behaviors: [{ type: 'callback', value: options.value }],
+  }
+}
+
+/** A row of equal-width columns, each holding one element. */
+export function columnSet(
+  columns: object[],
+  options: { flexMode?: string; spacing?: string; margin?: string } = {},
+): object {
+  return {
+    tag: 'column_set',
+    flex_mode: options.flexMode ?? 'bisect',
+    horizontal_spacing: options.spacing ?? 'medium',
+    margin: options.margin ?? '4px 0 0 0',
+    columns: columns.map(element => ({ tag: 'column', width: 'weighted', weight: 1, elements: [element] })),
+  }
+}
+
+/** Titled standalone card: bold title element followed by the body elements. */
+export function standaloneCard(title: string, elements: object[], config?: Record<string, unknown>): object {
+  return card([markdown(title), ...elements], config)
+}
+
+/** Titled card whose body is one markdown element per supplied line. */
+export function standaloneInfoCard(title: string, lines: readonly string[]): object {
+  return standaloneCard(title, lines.map(line => markdown(line)))
+}

package/src/cards/question.ts

@@ -0,0 +1,141 @@
+/**
+ * Structured user-question cards (`user-questions/request`).
+ *
+ * @module dsh-channels/cards/question
+ */
+
+import { card, divider, markdown, note, standaloneCard, textButton } from './primitives.ts'
+
+// ---- structured user-question cards --------------------------------------
+
+/** Terminal states a user-question card can settle into. */
+export type QuestionCardState = 'answered' | 'expired' | 'cancelled'
+
+/** One question as rendered (options are always present after normalization). */
+export interface QuestionCardItem {
+  id: string
+  question: string
+  detail?: string
+  header?: string
+  options: Array<{ label: string; description?: string }>
+  multiSelect: boolean
+  /** `plan-review` intent's approve label (presentation only). */
+  intentApproved?: string
+}
+
+/** One pending question card's render input. */
+export interface QuestionCardInput {
+  /** Opaque token binding the card to one pending question set. */
+  token: string
+  questions: QuestionCardItem[]
+  timeoutMs: number
+  sessionId?: string
+  /** Multi-select toggles accumulated so far, by question id. */
+  selected?: Record<string, string[]>
+  /** Question ids already answered (single-select picks). */
+  answered?: readonly string[]
+  /** Add the owner-only notice (a non-owner clicked and was ignored). */
+  unauthorizedNote?: boolean
+}
+
+/** Cap on rendered strings so one question cannot approach the card budget. */
+const QUESTION_TEXT_MAX_CHARS = 500
+/** Cap on rendered options per question (excess is reported, not dropped silently). */
+export const MAX_QUESTION_OPTIONS = 8
+
+function clipQuestionText(text: string, max = QUESTION_TEXT_MAX_CHARS): string {
+  return text.length <= max ? text : `${text.slice(0, max)}…`
+}
+
+function questionAnswered(input: QuestionCardInput, id: string): boolean {
+  return (input.answered ?? []).includes(id)
+}
+
+function questionOptionButton(
+  input: QuestionCardInput,
+  question: QuestionCardItem,
+  option: { label: string; description?: string },
+): object {
+  const isMulti = question.multiSelect
+  const selected = (input.selected?.[question.id] ?? []).includes(option.label)
+  const approved = question.intentApproved === option.label
+  const answered = questionAnswered(input, question.id)
+  const type = isMulti
+    ? (selected ? 'primary' : 'default')
+    : (approved ? 'primary' : 'default')
+  const label = isMulti && selected ? `✅ ${option.label}` : option.label
+  return textButton({
+    label: clipQuestionText(label, 80),
+    type: answered ? 'default' : type,
+    width: 'fill',
+    disabled: answered,
+    value: {
+      decision: isMulti ? 'question-toggle' : 'question-answer',
+      token: input.token,
+      id: question.id,
+      value: option.label,
+    },
+  })
+}
+
+function questionElements(input: QuestionCardInput): object[] {
+  const elements: object[] = [markdown('**❓ 需要你的回答**')]
+  input.questions.forEach((question, index) => {
+    const heading = question.header === undefined || question.header === ''
+      ? `**问题 ${index + 1}**`
+      : `**问题 ${index + 1} · ${clipQuestionText(question.header, 80)}**`
+    elements.push(markdown(`${heading}\n${clipQuestionText(question.question)}`))
+    if (question.detail !== undefined && question.detail !== '') {
+      elements.push(markdown(`> ${clipQuestionText(question.detail, 1_200).replace(/\s+/gu, ' ')}`))
+    }
+    const options = question.options.slice(0, MAX_QUESTION_OPTIONS)
+    for (const option of options) {
+      elements.push(questionOptionButton(input, question, option))
+    }
+    if (question.options.length === 0) {
+      elements.push(note('本题没有预设选项，请直接回复文字作答。'))
+    } else if (question.options.length > options.length) {
+      elements.push(note(`另有 ${question.options.length - options.length} 个选项未展示，请在 Web 端回答。`))
+    }
+    if (question.multiSelect) {
+      const selected = input.selected?.[question.id] ?? []
+      if (selected.length > 0 && !questionAnswered(input, question.id)) {
+        elements.push(textButton({
+          label: '提交本题选择',
+          type: 'primary',
+          value: { decision: 'question-submit', token: input.token, id: question.id },
+        }))
+      }
+      elements.push(note(`本题为多选：点选后请点“提交本题选择”（已选 ${selected.length} 项）。`))
+    }
+  })
+  elements.push(divider())
+  elements.push(note(`⏱ ${Math.max(1, Math.round(input.timeoutMs / 60_000))} 分钟内有效，超时后本轮提问失败 · 仅发起该会话的用户可操作 · 也可直接回复文字作答`))
+  if (input.sessionId !== undefined) elements.push(note(`🔑 ${input.sessionId}`))
+  if (input.unauthorizedNote === true) elements.push(note('ℹ️ 仅发起该会话的用户可操作此卡片'))
+  return elements
+}
+
+/** The pending structured-question card (one card carries every question). */
+export function buildQuestionCard(input: QuestionCardInput): object {
+  return card(questionElements(input))
+}
+
+const QUESTION_SETTLED_LINES: Record<QuestionCardState, string> = {
+  answered: '✅ 已回答',
+  expired: '⏱ 已超时未处理，本轮提问已失败',
+  cancelled: '↩️ 提问已取消',
+}
+
+/** The terminal replacement after the question set settles; controls removed. */
+export function buildQuestionSettledCard(input: QuestionCardInput, state: QuestionCardState): object {
+  const elements: object[] = [
+    ...input.questions.slice(0, 4).map((question, index) =>
+      markdown(`**问题 ${index + 1}**：${clipQuestionText(question.question, 200)}`)),
+    divider(),
+  ]
+  if (state === 'expired') {
+    elements.push(note('提问窗口已关闭。可在下一条消息中要求模型重新提问。'))
+  }
+  return standaloneCard(`**${QUESTION_SETTLED_LINES[state]}**`, elements)
+}