@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/host/services.ts

@@ -0,0 +1,320 @@
+/**
+ * Host bridge, service surface: workspaces, storage domains, credentials,
+ * token meter, LLM catalog, session projections, Cordis diagnostics, and the
+ * `HostContext` slice this plugin consumes.
+ *
+ * @module dsh-channels/host/services
+ */
+
+import type { AgentRegistry } from './agent.ts'
+import type { CommandRuntime } from './commands.ts'
+import type { AssistantStreamPayload, Session, SessionEvent, SessionId } from './core.ts'
+import type { ApprovalAnswererListener, UserQuestionAnswererListener } from './interaction.ts'
+
+// ---- Workspace surface --------------------------------------------------
+
+export interface Workspace {
+  readonly id: string
+  readonly path: string
+  readonly title: string
+  attachSession(id: SessionId): Promise<void> | void
+  detachSession(id: SessionId): Promise<void> | void
+}
+
+export interface WorkspaceRegistry {
+  create(path: string, title?: string): Promise<Workspace>
+  /** Every workspace currently registered with the host. */
+  list(): Workspace[]
+  /** Unregister one workspace record (the directory itself is the caller's concern). */
+  delete(id: string): Promise<boolean>
+}
+
+// ---- Storage / token-meter / llm / credentials surface ------------------
+
+/** The host's storage-domain facility (narrowly typed at the call site). */
+export interface StorageDomainFacility {
+  open(spec: unknown): Promise<unknown>
+}
+
+/** One resolved credential value and the source layer that supplied it. */
+export interface ResolvedCredential {
+  value: string
+  source: string
+}
+
+/** Presence/writability facts for one credential reference (never the value). */
+export interface CredentialInfo {
+  configured: boolean
+  writable?: boolean
+  source?: string
+}
+
+/**
+ * The host credentials seam (`@deepseek-ai/dsh-credentials`): resolves a
+ * reference per call with the provider's layer precedence
+ * (env > $DSH_HOME/.credentials.yaml > .env fallbacks), and can store a value
+ * for a reference through the same seam (the Web panel's credential editor).
+ * Every member beyond the read path is optional so embedded/test hosts can
+ * supply only what they support.
+ */
+export interface CredentialProvider {
+  resolve(ref: string): Promise<ResolvedCredential | undefined>
+  /** Presence check without revealing the value (the host's `credentials.describe`). */
+  describe?(ref: string): Promise<CredentialInfo | undefined>
+  /** Store a value for the reference; stored values outrank environment fallbacks. */
+  set?(ref: string, value: string): Promise<void>
+  /** Remove the stored value (environment fallbacks then apply again). */
+  unset?(ref: string): Promise<void>
+}
+
+export interface TokenMeasurement {
+  readonly totalTokens: number
+}
+
+export interface TokenMeter {
+  measure(session: Session, requestHeader?: unknown): TokenMeasurement
+}
+
+/** One registered provider route, as advertised by the LLM service. */
+export interface LlmProviderInfo {
+  id: string
+  name: string
+}
+
+/** One adapter-owned reasoning effort advertised for an exact model route. */
+export interface LlmReasoningEffortInfo {
+  /** Opaque stable id accepted by model requests. */
+  id: string
+  /** Human-readable effort name for selectors. */
+  name: string
+  description?: string
+}
+
+/** Selectable reasoning efforts for one exact provider/model route. */
+export interface LlmModelReasoningInfo {
+  /** Supported efforts from least to greatest. */
+  efforts: readonly LlmReasoningEffortInfo[]
+  /** Adapter-configured default effort; absent means the provider default. */
+  defaultEffort?: string
+}
+
+export interface LlmModelInfo {
+  /** Provider route that owns this entry. */
+  provider?: string
+  /** Model id passed to request generation. */
+  id?: string
+  /** Human-readable model name for selectors. */
+  name?: string
+  description?: string
+  context?: { contextWindow: number }
+  /** Adapter-owned reasoning levels, when `resolveModelInfo` reports them. */
+  reasoning?: LlmModelReasoningInfo
+}
+
+export interface LlmService {
+  resolveModelInfo(provider: string, model: string): Promise<LlmModelInfo>
+  /** Registered provider routes, when the deployment exposes them. */
+  listProviders?(): readonly LlmProviderInfo[]
+  /** Models advertised for one provider route. */
+  listModels?(provider: string): Promise<readonly LlmModelInfo[]>
+}
+
+/**
+ * Deployment default model selection (`@deepseek-ai/dsh-agent-default-model`).
+ * Web UI and headless entry points read it before creating an Agent; the
+ * settings panel only reads it to label the "inherit" choice.
+ */
+export interface AgentDefaultModel {
+  currentSelection(): { provider: string; model: string; reasoningEffort?: string }
+}
+
+// ---- Session projections -------------------------------------------------
+
+/**
+ * Whole-log figures maintained by the host's `sessionStats` projection
+ * (`@deepseek-ai/dsh-session-stats`, mounted by the web-app bundle). Reading
+ * these replaces re-folding the event log for wall times and TTFT.
+ */
+export interface SessionStatsView {
+  turns: number
+  steps: number
+  llmMs: number
+  toolMs: number
+  ttftMs: number
+  ttftSteps: number
+  decodeMs: number
+  decodeTokens: number
+}
+
+/** Provider-reported token buckets maintained by the `tokenUsage` projection. */
+export interface TokenUsageBuckets {
+  uncachedInputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+}
+
+export interface TokenUsageView {
+  totals: TokenUsageBuckets
+  last: { turn: number; step: number; buckets: TokenUsageBuckets } | null
+}
+
+/** Route capacity and prompt pressure maintained by the `contextPressure` projection. */
+export interface ContextPressureView {
+  pressureTokens?: number
+  projectedTokens?: number
+  contextWindow?: number
+}
+
+/**
+ * The host projection registry (`ctx.sessionProjections`). Read through
+ * `ctx.get` so deployments without the registry keep working: `stateOf`
+ * returns `undefined` for an unregistered key.
+ */
+export interface SessionProjections {
+  stateOf(session: Session, key: string): unknown
+}
+
+
+// ---- Session query -------------------------------------------------------
+
+/** Latest log-backed title of one session. */
+export interface SessionTitleSnapshot {
+  title: string
+  updatedAt: number
+}
+
+export interface SessionTitleObservation {
+  /** Absent when the observed log has no title event. */
+  title?: SessionTitleSnapshot
+}
+
+/** One ordered result from a batch title observation. */
+export type SessionTitleObservationResult =
+  | { sessionId: SessionId; status: 'fulfilled'; value: SessionTitleObservation }
+  | { sessionId: SessionId; status: 'rejected'; reason: unknown }
+
+/**
+ * The narrow read side of `ctx.sessionQuery` this plugin consumes: live-first
+ * title folding for the sessions a Feishu topic has bound.
+ */
+export interface SessionQuery {
+  readTitleSnapshots(sessionIds: readonly SessionId[]): Promise<readonly SessionTitleObservationResult[]>
+}
+
+// ---- Permission presets --------------------------------------------------
+
+/** One selectable sandbox+approval preset offered to clients. */
+export interface PermissionPresetOption {
+  value: string
+  name: string
+  description?: string
+}
+
+/** The process-level preset catalog exposed to current-session controls. */
+export interface PermissionCatalog {
+  options: PermissionPresetOption[]
+  defaultOptions: PermissionPresetOption[]
+  defaultPreset: string
+}
+
+/**
+ * The host permission-preset service (`ctx.permissionPresets`): reads the
+ * current Session's effective preset and records a switched one.
+ */
+export interface PermissionPresets {
+  catalog(): PermissionCatalog
+  current(session: Session): string
+  optionOf(name: string): PermissionPresetOption
+  set(session: Session, name: string): void
+}
+
+// ---- Cordis diagnostic surface -----------------------------------------
+
+/** Numeric values mirror Cordis 4's public `FiberState` enum. */
+export const CordisFiberState = {
+  PENDING: 0,
+  LOADING: 1,
+  ACTIVE: 2,
+  FAILED: 3,
+  DISPOSED: 4,
+  UNLOADING: 5,
+} as const
+
+export type CordisFiberState = typeof CordisFiberState[keyof typeof CordisFiberState]
+
+export interface CordisFiber {
+  readonly state: CordisFiberState
+  /** Best-effort plugin display name (`fiber.name`), used only for health diagnostics. */
+  readonly name?: string
+}
+
+export interface CordisPluginRuntime {
+  readonly fibers: Iterable<CordisFiber>
+}
+
+export interface CordisRegistry {
+  readonly size: number
+  values(): IterableIterator<CordisPluginRuntime>
+}
+
+// ---- Host context surface ----------------------------------------------
+
+/**
+ * The host (Cordis) context slice the plugin consumes. Declared locally and
+ * structurally: the host injects every capability through `ctx`, and the
+ * plugin never imports cordis at runtime, so there is no dependency on the
+ * npm-published cordis typings (whose `.ts`-specifier augmentations do not
+ * resolve under bundler module resolution).
+ */
+export interface HostLogger {
+  debug?(...args: unknown[]): void
+  info?(...args: unknown[]): void
+  warn?(...args: unknown[]): void
+  error?(...args: unknown[]): void
+}
+
+export interface HostContext {
+  agents: AgentRegistry
+  commands: CommandRuntime
+  workspaceRegistry: WorkspaceRegistry
+  storageDomain: StorageDomainFacility
+  /** Resolved through the injected `credentials` seam (env > .credentials.yaml > .env). */
+  credentials: CredentialProvider
+  tokenMeter: TokenMeter
+  llm: LlmService
+  /** Built-in Cordis plugin registry used for aggregate health diagnostics. */
+  registry: CordisRegistry
+  logger?: HostLogger
+  /** Safe service lookup (returns undefined for absent services). */
+  get?(name: string): unknown
+  /** Host events this plugin subscribes to (overloads per event). */
+  on(name: 'session/event', listener: (session: Session, event: SessionEvent) => void): () => boolean
+  /** Live (transient) model stream for every agent; replaces the removed `assistant/chunk` events. */
+  on(name: 'agent/assistant-stream', listener: (payload: AssistantStreamPayload) => void): () => boolean
+  /**
+   * The host's structured-question waterfall (`ask_user_question`). Same
+   * shape as `approval/request`: return an answer to claim, or delegate with
+   * `next()`. Untagged plugin contexts receive requests for every agent, so
+   * ownership filtering is mandatory.
+   */
+  on(
+    name: 'user-questions/request',
+    listener: UserQuestionAnswererListener,
+    options?: { prepend?: boolean },
+  ): () => boolean
+  /**
+   * The host's HITL answerer waterfall. Registered with `prepend: true` so
+   * this channel claims its own sessions before generic answerers (the web
+   * gateway); non-owned requests delegate through `next()`. Untagged plugin
+   * contexts receive requests for EVERY agent, so ownership filtering is
+   * mandatory. Safe to register without the approval service mounted — the
+   * event simply never fires.
+   */
+  on(
+    name: 'approval/request',
+    listener: ApprovalAnswererListener,
+    options?: { prepend?: boolean },
+  ): () => boolean
+  effect(callback: () => (() => void | Promise<void>) | void, label?: string): void
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * dsh-channels — DeepSeek Harness 飞书渠道插件。
+ *
+ * 一个 dsh 实例对应一个飞书机器人；用户通过私聊、群聊 @、话题群 @ 三种方式
+ * 发起会话。每条触发消息：立即加 “Typing” 表情 → 以话题形式回复（创建话题）
+ * → 绑定 DSH session → 卡片 2.0 流式回复（推理折叠面板 + 富文本正文 + 两行
+ * session 信息，默认 500ms 刷新）→ 流式结束移除 Typing，成功更新为
+ * “DONE”，失败显示结构化错误并更新为 “No”。
+ *
+ * 工作区归属：私聊一人一工作区；群聊中每个用户在该群拥有独立工作区
+ * （目录即工作区，会话以 cwd 落盘）。
+ *
+ * @module dsh-channels
+ */
+
+import type { HostContext } from './dsh-types.ts'
+import { FeishuService } from './service.ts'
+import { configSchema, resolveConfig } from './config.ts'
+import type { FeishuConfig } from './config.ts'
+import { defaultChannelFactory } from './feishu-channel.ts'
+import type { ChannelFactory } from './feishu-channel.ts'
+import { OverlayStore, defaultOverlayPath } from './settings/overlay.ts'
+import { mountSettingsRoutes } from './settings/routes.ts'
+import { SettingsSurface } from './settings/surface.ts'
+import { createHostCatalog } from './settings/catalog.ts'
+
+export type * from './config.ts'
+export type * from './cards.ts'
+export type * from './domain.ts'
+export type * from './feishu-channel.ts'
+export type * from './approvals.ts'
+export type * from './commands.ts'
+export type * from './health.ts'
+export type * from './session-commands.ts'
+export type * from './session-export.ts'
+export type * from './stats.ts'
+export type * from './questions.ts'
+export type * from './settings/contract.ts'
+export * from './access/index.ts'
+export type { AccessGroupRecord, AccessRequestRecord, AccessUserRecord } from './domain.ts'
+export { CATALOG_ROUTE, CLEANUP_ROUTE, CONFIG_ROUTE, CREDENTIALS_ROUTE, EDITABLE_KEYS, PANEL_COPY, PANEL_ROUTE, RECONNECT_ROUTE, RESTART_KEYS, STATUS_ROUTE } from './settings/contract.ts'
+export { defaultOverlayPath, mergeOverlay, normalizeOverlay, OverlayStore, parseOverlay, pickEditable, resolveDshHome } from './settings/overlay.ts'
+export { applyCatalog, emptyCatalog, FIELD_DESCRIPTORS, normalizeCredentialValue, readOnlyFields, SettingsSurface } from './settings/surface.ts'
+export type { SettingsTarget } from './settings/surface.ts'
+export { createHostCatalog } from './settings/catalog.ts'
+export type { CatalogWarn, SettingsCatalog } from './settings/catalog.ts'
+export { isSameOriginRequest, mountSettingsRoutes, registerSettingsRoutes } from './settings/routes.ts'
+export type { HostWebServer } from './settings/routes.ts'
+export type { ApprovalOutcome, ApprovalRequest, ApprovalAnswererListener, AssistantStreamFrame, AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequestEvent, UserQuestionAnswererListener, AgentCancelCause, SessionStatsView, TokenUsageView, ContextPressureView, SessionProjections } from './dsh-types.ts'
+export { buildCard, buildInterruptionCard, cardJsonBytes, CARD_MAX_BYTES, CARD_TARGET_BYTES, CARD_PANEL_RESERVE_BYTES, REASONING_MAX_BYTES, INTERRUPTION_NOTICE, MAX_TABLES_PER_CARD, PANEL_TITLES, PANEL_CHEVRON_TOKEN, segmentCardContent, splitBodyForCard, stripTables, tableBlocks, TRUNCATION_SUFFIX, buildApprovalCard, buildApprovalSettledCard, buildQuestionCard, buildQuestionSettledCard, MAX_QUESTION_OPTIONS } from './cards.ts'
+export { ApprovalAnswerer } from './approvals.ts'
+export { QuestionAnswerer } from './questions.ts'
+export { armModelCommand, buildCommandResultCard, CHANNEL_COMMAND_NAMES, commandResultCardKind, isSupportedCommand, parseSlashCommand, registerChannelCommands, registerModelCommand, RouteOperationQueue, SUPPORTED_COMMAND_NAMES, supportedCommandHelp, supportedCommandList } from './commands.ts'
+export { buildHealthCard, countFiberStates, foldHealthSnapshot, HEALTH_DEPENDENCY_NAMES, maskOpenIdTail } from './health.ts'
+export { buildCompactComparisonCard, buildRenewCard, buildSessionHistoryCard, buildSessionStatusCard, buildWorkDirCard, compactFailureContext, querySessionHistory, resolveWorkDir, SESSION_HISTORY_DISPLAY_LIMIT } from './session-commands.ts'
+export { createLogicalSessionExport, DSH_CHANNELS_VERSION, LOGICAL_EXPORT_FORMAT, LOGICAL_EXPORT_FORMAT_VERSION, serializeLogicalSession } from './session-export.ts'
+export { addUsage, applyProjectionViews, averageDecodeTokensPerSecond, averageTtftMs, cacheHitPct, EMPTY_TOTALS, foldAll, foldEvent, foldSessionStats, measureSessionContext, readProjectionViews, usageFromBuckets } from './stats.ts'
+export { FeishuService } from './service.ts'
+export { TurnStreamer } from './streamer.ts'
+export { ensureWorkspace, stagingPathFor, topicTokenFor, workspacePathFor, workspaceTitleFor } from './workspaces.ts'
+export { accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, appendSessionHistory, chatRouteKey, expiredRouteRecordSchema, feishuDomain, normalizeRouteRecord, normalizeSessionHistory, routeRecordSchema, sessionHistoryEntrySchema, inflightSnapshotSchema, processedRecordSchema } from './domain.ts'
+
+/** Cordis function-plugin name. */
+export const name = 'channels'
+
+/** Host services this plugin consumes (all resolved through ctx).
+ *
+ * `credentials` is listed even though the plugin could fall back to the
+ * process environment: at boot the credentials provider may not be visible
+ * yet (a race observed in real profiles), and inject makes the loader wait
+ * for it. `llm` / `tokenMeter` feed the card's context line and ship with
+ * every dsh-base profile.
+ */
+export const inject = ['agents', 'commands', 'workspaceRegistry', 'storageDomain', 'credentials', 'llm', 'tokenMeter'] as const
+
+/**
+ * Cordis Standard Schema declaration for the plugin config.
+ *
+ * The loader validates (and default-fills) the raw composition config through
+ * `Config['~standard'].validate()` *before* `apply()` runs, so a malformed
+ * `cordis.patch.yml` entry fails at load time with a cordis `ValidationError`
+ * instead of surfacing from inside the async service start. `apply()` keeps
+ * its `resolveConfig()` fallback for direct invocation (unit tests, embedded
+ * hosts) where config has not been pre-validated.
+ */
+export const Config = configSchema
+
+export interface FeishuPluginOptions extends FeishuConfig {
+  /** Test seam: substitute a channel implementation. */
+  channelFactory?: ChannelFactory
+}
+
+/**
+ * Install the bridge. Credentials stay references here — the actual secrets
+ * resolve through `ctx.credentials` (env > `$DSH_HOME/.credentials.yaml`
+ * > `.env`) when `FeishuService.start()` builds the channel.
+ */
+export function apply(ctx: HostContext, config?: unknown): void {
+  const resolved = resolveConfig(config)
+  const factory: ChannelFactory = (config as FeishuPluginOptions | undefined)?.channelFactory
+    ?? defaultChannelFactory
+  // Web settings overlay (optional file; degrades to "no overrides").
+  const overlay = new OverlayStore(
+    resolved.settingsFile ?? defaultOverlayPath(),
+    { warn: (message, ...args) => ctx.logger?.warn?.(message, ...args) },
+  )
+  const service = new FeishuService(ctx, resolved, factory, undefined, overlay)
+  // Settings routes ride the host's web server when this deployment has one.
+  // The catalog resolves the panel's model selectors from live host services.
+  const warn = (message: string, ...args: unknown[]): void => { ctx.logger?.warn?.(message, ...args) }
+  mountSettingsRoutes(ctx, new SettingsSurface(service, overlay, { warn }, createHostCatalog(ctx, warn)))
+  ctx.effect(() => {
+    void service.boot().catch((error: unknown) => {
+      ctx.logger?.error?.('dsh-channels failed to start: %s', String(error))
+      // Critical lifecycle line duplicated to the console: cordis logger
+      // messages emitted before a web exporter attaches are buffered and may
+      // never reach stdout, which makes real-device debugging guesswork.
+      console.error('[dsh-channels] failed to start:', error)
+    })
+    return () => service.shutdown()
+  }, 'dsh-channels')
+}

package/src/interactions/approvals.ts

@@ -0,0 +1,154 @@
+/**
+ * HITL approval answerer: turns the host's `approval/request` waterfall
+ * events into standalone Feishu decision cards.
+ *
+ * The answerer is registered with `prepend: true` on the plugin context so it
+ * runs BEFORE generic answerers: a request for a session this channel routes
+ * is claimed here, and the decision card becomes the only way to answer.
+ * Requests for sessions the channel does NOT route delegate through `next()`.
+ *
+ * Rendering lives in `cards/approval.ts`; the shared pending-card lifecycle
+ * (delivery, owner gating, timeout, settle-once, withdrawal) lives in
+ * `interactions/pending.ts`.
+ *
+ * @module dsh-channels/interactions/approvals
+ */
+
+import { randomUUID } from 'node:crypto'
+import { buildApprovalCard, buildApprovalSettledCard } from '../cards/approval.ts'
+import type { ApprovalCardState, ApprovalQuestion } from '../cards/approval.ts'
+import type { ApprovalOutcome, ApprovalRequest } from '../dsh-types.ts'
+import type { CardActionEvent, FeishuChannel } from '../feishu-channel.ts'
+import { PendingCardTable } from './pending.ts'
+import type { InteractionRoute, PendingCardEntry } from './pending.ts'
+
+/** Feishu placement of one session's approval cards. */
+export type ApprovalRoute = InteractionRoute
+
+export interface ApprovalHooks {
+  /**
+   * Resolve the Feishu placement for a session. `undefined` means the session
+   * is not owned by this channel — the answerer delegates through `next()`.
+   */
+  routeFor(sessionId: string): ApprovalRoute | undefined
+  /** Log a non-fatal error (delivery/update failures). */
+  onError(sessionId: string, error: unknown): void
+}
+
+/** One in-flight approval question: its card content and its resolver. */
+interface Pending extends PendingCardEntry {
+  question: ApprovalQuestion
+  resolve(outcome: ApprovalOutcome): void
+}
+
+export class ApprovalAnswerer {
+  private readonly table: PendingCardTable<Pending>
+
+  constructor(
+    channel: FeishuChannel,
+    private readonly hooks: ApprovalHooks,
+    private readonly timeoutMs: number,
+  ) {
+    this.table = new PendingCardTable(channel, hooks.onError)
+  }
+
+  /** In-flight question count (diagnostics/tests). */
+  pendingCount(): number {
+    return this.table.count()
+  }
+
+  /**
+   * The `approval/request` waterfall listener. Never rejects: the host service
+   * already contains answerer failures to the fail-closed `'unavailable'`.
+   */
+  onRequest(req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome> {
+    const route = this.hooks.routeFor(req.agent.session.id)
+    if (route === undefined) return next()
+    // The abort window between the service's own signal check and this
+    // listener is closed by settling synchronously: an aborted ask never
+    // opens a question.
+    if (req.signal?.aborted === true) return Promise.resolve('cancelled')
+
+    const token = randomUUID()
+    // `displayReason` (DSH 0.2.0) is presentation-only and locale-aware;
+    // `reason` remains the audit-trail fallback.
+    const displayReason = req.displayReason?.zh ?? req.displayReason?.en ?? req.reason
+    const question: ApprovalQuestion = {
+      token,
+      toolName: req.toolName,
+      ...(displayReason === undefined ? {} : { reason: displayReason }),
+      timeoutMs: this.timeoutMs,
+      sessionId: req.agent.session.id,
+    }
+    return new Promise<ApprovalOutcome>((resolve) => {
+      const entry: Pending = {
+        token,
+        sessionId: req.agent.session.id,
+        route,
+        messageId: undefined,
+        settled: false,
+        timer: undefined,
+        signal: req.signal,
+        onAbort: undefined,
+        unauthorizedNoted: false,
+        question,
+        resolve,
+      }
+      const onAbort = (): void => {
+        this.settle(entry, 'cancelled', 'cancelled')
+      }
+      entry.onAbort = onAbort
+      // Registered synchronously at promise creation so no abort can slip
+      // between the ownership check and the card delivery; a residual abort
+      // in the tiny window before addEventListener is still covered because
+      // the host's decide() races the signal against this promise and
+      // discards a late resolution (worst case: the card times out).
+      req.signal?.addEventListener('abort', onAbort, { once: true })
+      this.table.add(entry)
+      void this.table.deliver(entry, {
+        card: buildApprovalCard(question),
+        onWithdrawn: e => this.table.patch(e, buildApprovalSettledCard(e.question, 'cancelled')),
+        onDelivered: e => this.table.armTimeout(e, this.timeoutMs, () => {
+          this.settle(e, 'rejected', 'expired')
+        }),
+        // No card → no human answerer → fail closed.
+        onFailure: e => {
+          this.table.close(e, () => {})
+          e.resolve('unavailable')
+        },
+      })
+    })
+  }
+
+  /**
+   * Route one card button-callback event to its pending question. Unknown
+   * cards and non-owner operators are ignored (a non-owner click adds the
+   * owner-only notice to the card once); owner decisions settle the question.
+   */
+  onCardAction(event: CardActionEvent): void {
+    const entry = this.table.resolveAction(event, candidate => {
+      if (candidate.unauthorizedNoted) return
+      candidate.unauthorizedNoted = true
+      this.table.patch(candidate, buildApprovalCard(candidate.question, { unauthorizedNote: true }))
+    })
+    if (entry === undefined) return
+    const decision = (event.action.value as { decision?: unknown } | undefined)?.decision
+    if (decision === 'allow') this.settle(entry, 'allowed-once', 'allowed')
+    else if (decision === 'deny') this.settle(entry, 'rejected', 'denied')
+  }
+
+  /** Withdraw every in-flight question (plugin shutdown). */
+  dispose(): void {
+    this.table.withdrawAll(entry => this.settle(entry, 'cancelled'))
+  }
+
+  /** Settle once, then patch the card to its terminal state. */
+  private settle(entry: Pending, outcome: ApprovalOutcome, cardState?: ApprovalCardState): void {
+    const closed = this.table.close(entry, () => {
+      if (cardState !== undefined) {
+        this.table.patch(entry, buildApprovalSettledCard(entry.question, cardState))
+      }
+    })
+    if (closed) entry.resolve(outcome)
+  }
+}