@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/session/request-policy.ts

@@ -0,0 +1,192 @@
+/**
+ * Per-session request policy: provider / model / reasoning-effort overrides.
+ *
+ * Cordis waterfalls run the earliest listener as the outermost wrapper, so the
+ * channel policy registers with `prepend: true`: preset/model-selection
+ * listeners may be standing registrations that predate this Agent, and they
+ * rewrite the request after `next()` resolves. The outer channel wrapper
+ * therefore writes last.
+ *
+ * Session overrides are recovered from successful command lifecycles
+ * (`/effort`, `/model`). Reusing Harness' durable `command/run` /
+ * `command/done` pair avoids inventing an out-of-repo Session event that
+ * persistence could not safely recognize on restore.
+ *
+ * @module dsh-channels/session/request-policy
+ */
+
+import type { AgentContext, CommandId, SessionEvent } from '../dsh-types.ts'
+
+/** A model selection override: a bare model keeps the composed provider. */
+export interface ModelOverride {
+  /** Provider route; absent keeps the route composed by earlier listeners. */
+  readonly provider?: string
+  readonly model: string
+}
+
+/** Channel-configured defaults for sessions this plugin creates. */
+export interface RequestPolicyConfig {
+  /** Configured reasoning effort (optional → adapter/provider default). */
+  effort?: string
+  /** Configured provider pin (optional → deployment default). */
+  provider?: string
+  /** Configured model pin (optional → deployment default). */
+  model?: string
+}
+
+export interface RequestPolicyState {
+  readonly configuredEffort: string | undefined
+  readonly configuredModel: ModelOverride | undefined
+  /** Session-level `/effort` override. */
+  readonly effortOverride: string | undefined
+  /** Session-level `/model` override. */
+  readonly modelOverride: ModelOverride | undefined
+  /** Effort this channel writes into the next request, when defined. */
+  readonly effectiveEffort: string | undefined
+  /** Model this channel writes into the next request, when defined. */
+  readonly effectiveModel: ModelOverride | undefined
+  readonly effortSource: 'session' | 'config' | 'model-default'
+  readonly modelSource: 'session' | 'config' | 'deployment-default'
+}
+
+export interface RequestPolicyController {
+  readonly state: RequestPolicyState
+  /** Re-fold the durable log after resume or a settled command lifecycle. */
+  sync(events: readonly SessionEvent[]): void
+  /** Remove only this controller's Agent-scoped request wrapper. */
+  dispose(): void
+}
+
+type PendingSelection =
+  | { readonly kind: 'effort'; readonly value: string | undefined }
+  | { readonly kind: 'model'; readonly value: ModelOverride | undefined }
+
+/** Parse `/effort` input; only values the handler can accept. */
+function effortSelection(args: string | undefined): string | undefined | 'invalid' {
+  if (args === undefined) return 'invalid'
+  const value = args.trim()
+  if (value === '' || /\s/u.test(value)) return 'invalid'
+  return value === 'reset' ? undefined : value
+}
+
+/**
+ * Parse `/model` input: `reset`, `<model>` (keeps the composed provider), or
+ * `<provider>/<model>`.
+ */
+function modelSelection(args: string | undefined): ModelOverride | undefined | 'invalid' {
+  if (args === undefined) return 'invalid'
+  const value = args.trim()
+  if (value === '' || /\s/u.test(value)) return 'invalid'
+  if (value === 'reset') return undefined
+  const slash = value.indexOf('/')
+  if (slash === -1) return { model: value }
+  const provider = value.slice(0, slash)
+  const model = value.slice(slash + 1)
+  if (provider === '' || model === '' || model.includes('/')) return 'invalid'
+  return { provider, model }
+}
+
+/** One folded policy: the last successful Session-level selections. */
+export interface FoldedRequestPolicy {
+  effort: string | undefined
+  model: ModelOverride | undefined
+}
+
+/**
+ * Fold the durable log into the Session-level policy.
+ *
+ * A run changes nothing until its matching `command/done` succeeds. Failed,
+ * incomplete, query-only, and malformed commands are therefore inert.
+ */
+export function foldRequestPolicy(events: readonly SessionEvent[]): FoldedRequestPolicy {
+  const pending = new Map<CommandId, PendingSelection>()
+  let effort: string | undefined
+  let model: ModelOverride | undefined
+  for (const event of events) {
+    if (event.type === 'command/run') {
+      if (event.data.name === 'effort') {
+        const selection = effortSelection(event.data.args)
+        if (selection !== 'invalid') pending.set(event.data.commandId, { kind: 'effort', value: selection })
+      } else if (event.data.name === 'model') {
+        const selection = modelSelection(event.data.args)
+        if (selection !== 'invalid') pending.set(event.data.commandId, { kind: 'model', value: selection })
+      }
+      continue
+    }
+    if (event.type !== 'command/done') continue
+    const selection = pending.get(event.data.commandId)
+    if (selection === undefined) continue
+    pending.delete(event.data.commandId)
+    if (event.data.kind !== 'success') continue
+    if (selection.kind === 'effort') effort = selection.value
+    else model = selection.value
+  }
+  return { effort, model }
+}
+
+/** Fold only the last successful Session-level `/effort` selection. */
+export function foldEffortOverride(events: readonly SessionEvent[]): string | undefined {
+  return foldRequestPolicy(events).effort
+}
+
+/** Fold only the last successful Session-level `/model` selection. */
+export function foldModelOverride(events: readonly SessionEvent[]): ModelOverride | undefined {
+  return foldRequestPolicy(events).model
+}
+
+/** Install the mutable request policy outside every other request wrapper. */
+export function installRequestPolicy(
+  agentCtx: AgentContext,
+  config: RequestPolicyConfig = {},
+): RequestPolicyController {
+  let effortOverride: string | undefined
+  let modelOverride: ModelOverride | undefined
+  let disposed = false
+  const configuredModel: ModelOverride | undefined = config.provider !== undefined && config.model !== undefined
+    ? { provider: config.provider, model: config.model }
+    : undefined
+
+  const disposeListener = agentCtx.on('agent/request', async (_payload, next) => {
+    const request = await next()
+    const effort = effortOverride ?? config.effort
+    const model = modelOverride ?? configuredModel
+    if (effort === undefined && model === undefined) return request
+    return {
+      ...request,
+      ...(effort === undefined ? {} : { reasoningEffort: effort }),
+      ...(model === undefined ? {} : { model: model.model }),
+      ...(model?.provider === undefined ? {} : { provider: model.provider }),
+    }
+  }, { prepend: true })
+
+  return {
+    get state(): RequestPolicyState {
+      const effectiveEffort = effortOverride ?? config.effort
+      const effectiveModel = modelOverride ?? configuredModel
+      return {
+        configuredEffort: config.effort,
+        configuredModel,
+        effortOverride,
+        modelOverride,
+        effectiveEffort,
+        effectiveModel,
+        effortSource: effortOverride !== undefined
+          ? 'session'
+          : config.effort !== undefined ? 'config' : 'model-default',
+        modelSource: modelOverride !== undefined
+          ? 'session'
+          : configuredModel !== undefined ? 'config' : 'deployment-default',
+      }
+    },
+    sync(events) {
+      const folded = foldRequestPolicy(events)
+      effortOverride = folded.effort
+      modelOverride = folded.model
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      disposeListener()
+    },
+  }
+}

package/src/session/routes.ts

@@ -0,0 +1,165 @@
+/**
+ * Durable route store: thread/chat keys → bound DSH session records.
+ *
+ * Owns the hot cache over the `channels_routes` domain tables, the TTL
+ * retirement that leaves a persistent tombstone, and session → route lookup.
+ * The domain handle is late-bound (`domain()`), because the service opens it
+ * during `start()` while the store is constructed earlier.
+ *
+ * @module dsh-channels/session/routes
+ */
+
+import type { ExpiredRouteRecord, FeishuDomainHandle, RouteRecord } from '../domain.ts'
+import { normalizeRouteRecord } from '../domain.ts'
+
+export interface RouteStoreDeps {
+  /** The opened domain handle, or undefined before `start()` / after shutdown. */
+  domain(): FeishuDomainHandle | undefined
+  /** Route retirement TTL in milliseconds; `0` disables retirement. */
+  ttlMs(): number
+  /** Structured warning sink (never throws). */
+  warn(message: string, ...args: unknown[]): void
+}
+
+export class RouteStore {
+  /** Active route records, hydrated once and kept in sync with writes. */
+  private readonly active = new Map<string, RouteRecord>()
+  /** Thread ids retired by TTL; retained so later messages cannot fork context. */
+  private readonly expired = new Map<string, ExpiredRouteRecord>()
+
+  constructor(private readonly deps: RouteStoreDeps) {}
+
+  /**
+   * Hydrate the caches from the opened domain. A tombstone wins over an active
+   * row left behind by an interrupted or failed delete: expired Sessions must
+   * not remain approval-routable.
+   */
+  load(): void {
+    const domain = this.deps.domain()
+    if (domain === undefined) return
+    for (const [key, record] of domain.routes.entries()) {
+      this.active.set(key, normalizeRouteRecord(record))
+    }
+    for (const [key, record] of domain.expiredRoutes.entries()) {
+      this.expired.set(key, record)
+      this.active.delete(key)
+    }
+  }
+
+  /** One active route by key (cache-first, normalized). */
+  get(key: string): RouteRecord | undefined {
+    const cached = this.active.get(key)
+    if (cached !== undefined) return cached
+    const stored = this.deps.domain()?.routes.get(key)
+    if (stored === undefined) return undefined
+    const normalized = normalizeRouteRecord(stored)
+    this.active.set(key, normalized)
+    return normalized
+  }
+
+  /** One durable tombstone by expired thread id. */
+  expiredRoute(key: string): ExpiredRouteRecord | undefined {
+    const cached = this.expired.get(key)
+    if (cached !== undefined) return cached
+    const stored = this.deps.domain()?.expiredRoutes.get(key)
+    if (stored === undefined) return undefined
+    this.expired.set(key, stored)
+    return stored
+  }
+
+  /** Persist one active route and refresh the cache. */
+  async put(key: string, record: RouteRecord): Promise<void> {
+    await this.deps.domain()?.routes.put(key, record)
+    this.active.set(key, normalizeRouteRecord(record))
+  }
+
+  /** Delete one active route from the medium and the cache. */
+  async remove(key: string): Promise<void> {
+    await this.deps.domain()?.routes.delete(key)
+    this.active.delete(key)
+  }
+
+  /** Drop one key from the cache only (used when a tombstone takes over). */
+  forget(key: string): void {
+    this.active.delete(key)
+  }
+
+  /** Find the route record owning a session (a thread route wins). */
+  findBySession(sessionId: string): RouteRecord | undefined {
+    let fallback: RouteRecord | undefined
+    for (const record of this.active.values()) {
+      if (record.sessionId !== sessionId) continue
+      if (record.kind === 'thread') return record
+      fallback ??= record
+    }
+    return fallback
+  }
+
+  size(): number {
+    return this.active.size
+  }
+
+  clear(): void {
+    this.active.clear()
+    this.expired.clear()
+  }
+
+  /** Whether one active route has crossed the configured inactivity deadline. */
+  private hasExpired(record: RouteRecord, now: number): boolean {
+    const ttlMs = this.deps.ttlMs()
+    return ttlMs > 0 && record.lastActivityAt < now - ttlMs
+  }
+
+  /**
+   * Resolve or create the persistent tombstone for a thread whose active route
+   * has crossed TTL. Tombstone publication comes first and wins even if the
+   * best-effort active-route delete fails.
+   */
+  async expireThread(key: string, now = Date.now()): Promise<ExpiredRouteRecord | undefined> {
+    const existing = this.expiredRoute(key)
+    if (existing !== undefined) {
+      this.active.delete(key)
+      if (this.deps.domain()?.routes.get(key) !== undefined) {
+        try {
+          await this.deps.domain()?.routes.delete(key)
+        } catch (error) {
+          this.deps.warn('dsh-channels: deleting tombstoned route %s failed: %s', key, String(error))
+        }
+      }
+      return existing
+    }
+    const record = this.get(key)
+    if (record === undefined || record.kind !== 'thread' || !this.hasExpired(record, now)) return undefined
+    return await this.retire(key, now)
+  }
+
+  /**
+   * Retire one active thread route into a persistent tombstone regardless of
+   * the configured TTL. Used by the workspace-retention cleanup, which may
+   * close topics earlier than the route TTL.
+   */
+  async retire(key: string, now = Date.now()): Promise<ExpiredRouteRecord | undefined> {
+    const record = this.get(key)
+    if (record === undefined) return this.expiredRoute(key)
+    const tombstone: ExpiredRouteRecord = {
+      key,
+      chatId: record.chatId,
+      chatType: record.chatType,
+      senderOpenId: record.senderOpenId,
+      expiredAt: now,
+      workspacePath: record.workspacePath,
+      lastActivityAt: record.lastActivityAt,
+    }
+    await this.deps.domain()?.expiredRoutes.put(key, tombstone)
+    this.expired.set(key, tombstone)
+    this.active.delete(key)
+    try {
+      await this.deps.domain()?.routes.delete(key)
+    } catch (error) {
+      // The durable tombstone already makes expiry fail-closed. Keep serving
+      // the explicit rejection and let a later sweep retry the stale delete.
+      this.deps.warn('dsh-channels: deleting retired route %s failed: %s', key, String(error))
+    }
+    return tombstone
+  }
+}

package/src/session-commands.ts

@@ -0,0 +1,310 @@
+/**
+ * Pure result rendering and validation for Session-scoped slash commands.
+ *
+ * @module dsh-channels/session-commands
+ */
+
+import path from 'node:path'
+import { standaloneCard } from './cards/primitives.ts'
+import type { RouteRecord, SessionHistoryEntry } from './domain.ts'
+import { normalizeSessionHistory } from './domain.ts'
+import type { ContextMeasurement, StatsFold, ToolEventSample } from './stats.ts'
+import {
+  averageDecodeTokensPerSecond, averageTtftMs, cacheHitPct,
+} from './stats.ts'
+
+function fmtCount(value: number): string {
+  return value.toLocaleString('en-US')
+}
+
+function fmtDuration(value: number | undefined): string {
+  if (value === undefined || !Number.isFinite(value)) return '暂无数据'
+  if (value < 1000) return `${Math.round(value)} ms`
+  return `${(value / 1000).toFixed(2)} s`
+}
+
+function fmtPercent(value: number | undefined): string {
+  return value === undefined || !Number.isFinite(value) ? '暂无数据' : `${(value * 100).toFixed(1)}%`
+}
+
+function fmtRate(value: number | undefined): string {
+  return value === undefined || !Number.isFinite(value) ? '暂无数据' : `${value.toFixed(1)} tokens/s`
+}
+
+function contextLine(measurement: ContextMeasurement): string {
+  const tokens = measurement.contextTokens
+  const window = measurement.contextWindow
+  if (tokens === undefined) return '暂无数据'
+  if (window === undefined) return `${fmtCount(tokens)} tokens`
+  return `${fmtCount(tokens)} / ${fmtCount(window)} (${(tokens / window * 100).toFixed(1)}%)`
+}
+
+function escapeInlineCode(value: string): string {
+  return value.replaceAll('`', '\\`')
+}
+
+function toolLine(sample: ToolEventSample): string {
+  const status = sample.status === 'running' ? '运行中' : sample.status === 'success' ? '成功' : '失败'
+  const duration = sample.status === 'running' ? '尚未完成' : fmtDuration(sample.durationMs)
+  return `- \`${escapeInlineCode(sample.name)}\` · ${status} · ${duration}`
+}
+
+export interface SessionStatusCardInput {
+  sessionId: string
+  stats: StatsFold
+  context: ContextMeasurement
+  /** Optional operational extras (permission preset, workspace, uptime, …). */
+  extras?: SessionStatusExtras
+}
+
+/** Operational extras appended to the `/status` card when available. */
+export interface SessionStatusExtras {
+  /** Effective permission preset of this Session (`ctx.permissionPresets`). */
+  permissionPreset?: string
+  /** Workspace directory bound to this route. */
+  workspacePath?: string
+  /** Plugin uptime in milliseconds. */
+  uptimeMs?: number
+  /** Live agent entries this channel owns/borrows. */
+  liveAgents?: number
+  /** Persisted route records. */
+  routeCount?: number
+}
+
+/** Render the complete `/status` snapshot without exposing tool arguments or results. */
+export function buildSessionStatusCard(input: SessionStatusCardInput): object {
+  const { stats } = input
+  const model = stats.lastHeader === undefined
+    ? '尚未产生模型请求'
+    : `${stats.lastHeader.provider}/${stats.lastHeader.model}`
+  const effort = stats.lastHeader?.effort ?? '暂无数据'
+  const tools = stats.recentTools.length === 0
+    ? '暂无工具事件'
+    : [...stats.recentTools].reverse().map(toolLine).join('\n')
+  const pendingNames = [...stats.pendingTools.values()].slice(-5).map(tool => `\`${escapeInlineCode(tool.name)}\``)
+  const hiddenPending = stats.pendingTools.size - pendingNames.length
+  const pending = pendingNames.length === 0
+    ? '无'
+    : `${pendingNames.join('、')}${hiddenPending > 0 ? `，另有 ${hiddenPending} 个` : ''}`
+  const tokenSummary = stats.usageSamples === 0
+    ? '暂无数据'
+    : `输入 ${fmtCount(stats.totals.inputTokens)} · 输出 ${fmtCount(stats.totals.outputTokens)} · 推理 ${fmtCount(stats.totals.reasoningTokens)}`
+  const cacheSummary = stats.usageSamples === 0
+    ? '暂无数据'
+    : `读取 ${fmtCount(stats.totals.cacheReadTokens)} · 写入 ${fmtCount(stats.totals.cacheWriteTokens)} · 最近命中率 ${fmtPercent(cacheHitPct(stats.lastUsage))}`
+
+  return standaloneCard('**📊 Session 状态**', [
+    { tag: 'markdown', content: `**模型**：${model}\n**推理强度**：${effort}` },
+    {
+      tag: 'markdown',
+      content: `**Token 累计**：${tokenSummary}\n`
+        + `**缓存**：${cacheSummary}\n`
+        + `**上下文**：${contextLine(input.context)}`,
+    },
+    {
+      tag: 'markdown',
+      content: `**LLM 时间**：${fmtDuration(stats.llmSteps === 0 ? undefined : stats.llmMs)}\n`
+        + `**工具时间**：${fmtDuration(stats.toolTimedCalls === 0 ? undefined : stats.toolMs)}\n`
+        + `**平均首 token**：${fmtDuration(averageTtftMs(stats))}\n`
+        + `**平均生成速度**：${fmtRate(averageDecodeTokensPerSecond(stats))}`,
+    },
+    {
+      tag: 'markdown',
+      content: `**工具调用**：累计 ${fmtCount(stats.toolCalls)} · 未完成 ${fmtCount(stats.pendingTools.size)}（${pending}）\n`
+        + `**最近工具事件（最多 5 条）**\n${tools}`,
+    },
+    ...statusExtrasElements(input.extras),
+    { tag: 'markdown', content: input.sessionId, text_size: 'notation' },
+  ])
+}
+
+/** Render the optional operational lines, omitting unavailable ones. */
+function statusExtrasElements(extras: SessionStatusExtras | undefined): object[] {
+  if (extras === undefined) return []
+  const lines: string[] = []
+  if (extras.permissionPreset !== undefined) lines.push(`**权限预设**：\`${escapeInlineCode(extras.permissionPreset)}\``)
+  if (extras.workspacePath !== undefined) lines.push(`**工作区**：\`${escapeInlineCode(extras.workspacePath)}\``)
+  if (extras.uptimeMs !== undefined) lines.push(`**插件运行时长**：${fmtUptime(extras.uptimeMs)}`)
+  if (extras.liveAgents !== undefined || extras.routeCount !== undefined) {
+    const parts: string[] = []
+    if (extras.liveAgents !== undefined) parts.push(`live Agent ${fmtCount(extras.liveAgents)}`)
+    if (extras.routeCount !== undefined) parts.push(`持久化路由 ${fmtCount(extras.routeCount)}`)
+    lines.push(`**通道**：${parts.join(' · ')}`)
+  }
+  return lines.length === 0 ? [] : [{ tag: 'markdown', content: lines.join('\n') }]
+}
+
+/** `2 小时 5 分` / `45 秒` — coarse human uptime. */
+function fmtUptime(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000))
+  if (totalSeconds < 60) return `${totalSeconds} 秒`
+  const minutes = Math.floor(totalSeconds / 60) % 60
+  const hours = Math.floor(totalSeconds / 3600)
+  return hours === 0 ? `${minutes} 分` : `${hours} 小时 ${minutes} 分`
+}
+
+export type WorkDirResolution =
+  | { kind: 'success'; path: string }
+  | { kind: 'missing'; text: string }
+  | { kind: 'mismatch'; text: string }
+
+/** Validate the Session header cwd against the plugin's durable route. */
+export function resolveWorkDir(headerCwd: string | undefined, routeWorkspacePath: string): WorkDirResolution {
+  if (headerCwd === undefined || headerCwd === '' || !path.isAbsolute(headerCwd)) {
+    return {
+      kind: 'missing',
+      text: '当前 Session header 未记录可用的绝对工作目录；请检查 Session 创建或恢复配置。',
+    }
+  }
+  if (!path.isAbsolute(routeWorkspacePath)) {
+    return {
+      kind: 'missing',
+      text: '当前飞书路由未记录可用的绝对工作目录；请检查路由持久化状态。',
+    }
+  }
+  if (headerCwd !== routeWorkspacePath) {
+    return {
+      kind: 'mismatch',
+      text: 'Session header 与飞书路由记录的工作目录不一致；为避免返回错误目录，已拒绝显示。',
+    }
+  }
+  return { kind: 'success', path: headerCwd }
+}
+
+/** Render one verified absolute workspace path. */
+export function buildWorkDirCard(sessionId: string, workspacePath: string): object {
+  return standaloneCard('**📁 当前工作目录**', [
+    { tag: 'markdown', content: `\`${escapeInlineCode(workspacePath)}\`` },
+    { tag: 'markdown', content: sessionId, text_size: 'notation' },
+  ])
+}
+
+export interface RenewCardInput {
+  previousSessionId: string
+  currentSessionId: string
+  workspacePath: string
+}
+
+/** Render the committed route switch without implying that the old log was deleted. */
+export function buildRenewCard(input: RenewCardInput): object {
+  return standaloneCard('**🔄 Session 已续建**', [
+    {
+      tag: 'markdown',
+      content: `**旧 Session**：${input.previousSessionId}\n`
+        + `**新 Session**：${input.currentSessionId}\n`
+        + `**复用工作区**：\`${escapeInlineCode(input.workspacePath)}\``,
+    },
+    { tag: 'markdown', content: '旧 Session 及其日志仍由 Harness 保留。', text_size: 'notation' },
+  ])
+}
+
+export const SESSION_HISTORY_DISPLAY_LIMIT = 20
+
+export interface SessionHistoryItem extends SessionHistoryEntry {
+  current: boolean
+}
+
+export interface SessionHistoryView {
+  total: number
+  items: SessionHistoryItem[]
+  hidden: number
+}
+
+/** Read one route's normalized history without consulting the Session repository. */
+export function querySessionHistory(record: RouteRecord): SessionHistoryView {
+  const history = normalizeSessionHistory(record)
+  const items = history
+    .slice(-SESSION_HISTORY_DISPLAY_LIMIT)
+    .reverse()
+    .map(entry => ({ ...entry, current: entry.sessionId === record.sessionId }))
+  return {
+    total: history.length,
+    items,
+    hidden: Math.max(0, history.length - items.length),
+  }
+}
+
+/** Optional per-session facts folded from the host session query. */
+export interface SessionHistoryAnnotation {
+  /** Latest log-backed session title, when one exists. */
+  title?: string
+  /** Whether the session is currently live (held by any owner). */
+  live?: boolean
+}
+
+function historyLine(
+  item: SessionHistoryItem,
+  index: number,
+  annotation: SessionHistoryAnnotation | undefined,
+): string {
+  const markers = [
+    ...(item.current ? ['**当前**'] : []),
+    ...(annotation?.live === true && !item.current ? ['live'] : []),
+  ]
+  const marker = markers.length === 0 ? '' : ` · ${markers.join(' · ')}`
+  const title = annotation?.title === undefined || annotation.title === ''
+    ? ''
+    : `\n   标题：${escapeInlineCode(annotation.title)}`
+  return `${index + 1}. \`${escapeInlineCode(item.sessionId)}\`${marker}${title}\n`
+    + `   创建时间：${new Date(item.createdAt).toISOString()}`
+}
+
+/** Render the newest route-local Session history with host-query annotations. */
+export function buildSessionHistoryCard(
+  record: RouteRecord,
+  annotations: Readonly<Record<string, SessionHistoryAnnotation>> = {},
+): object {
+  const view = querySessionHistory(record)
+  const elements: object[] = [
+    { tag: 'markdown', content: `**总数**：${fmtCount(view.total)}\n**当前 Session**：\`${escapeInlineCode(record.sessionId)}\`` },
+    { tag: 'markdown', content: view.items.map((item, index) => historyLine(item, index, annotations[item.sessionId])).join('\n') },
+  ]
+  if (view.hidden > 0) {
+    elements.push({ tag: 'markdown', content: `另有 ${fmtCount(view.hidden)} 条未展示。`, text_size: 'notation' })
+  }
+  return standaloneCard('**🕘 Session 历史**', elements)
+}
+
+function comparisonLine(label: string, tokens: number | undefined, window: number | undefined): string {
+  if (tokens === undefined) return `${label}  暂无数据`
+  if (window === undefined) return `${label}  ${fmtCount(tokens)} tokens`
+  const ratio = tokens / window
+  const filled = Math.min(10, Math.max(0, Math.round(ratio * 10)))
+  return `${label}  ${'█'.repeat(filled)}${'░'.repeat(10 - filled)}  ${(ratio * 100).toFixed(0)}%  ${fmtCount(tokens)} / ${fmtCount(window)}`
+}
+
+export interface CompactComparisonInput {
+  sessionId: string
+  resultText: string
+  before: ContextMeasurement
+  after: ContextMeasurement
+}
+
+/** Render successful and no-op compaction outcomes with one shared 10-cell scale. */
+export function buildCompactComparisonCard(input: CompactComparisonInput): object {
+  const window = input.after.contextWindow ?? input.before.contextWindow
+  const beforeTokens = input.before.contextTokens
+  const afterTokens = input.after.contextTokens
+  const released = beforeTokens === undefined || afterTokens === undefined
+    ? undefined
+    : Math.max(0, beforeTokens - afterTokens)
+  return standaloneCard('**🗜️ 上下文压缩完成**', [
+    { tag: 'markdown', content: input.resultText },
+    {
+      tag: 'markdown',
+      content: `${comparisonLine('压缩前', beforeTokens, window)}\n`
+        + `${comparisonLine('压缩后', afterTokens, window)}\n`
+        + `释放    ${released === undefined ? '暂无数据' : `${fmtCount(released)} tokens`}`,
+    },
+    { tag: 'markdown', content: input.sessionId, text_size: 'notation' },
+  ])
+}
+
+/** Describe whether a failed compaction left the measured surface unchanged. */
+export function compactFailureContext(before: ContextMeasurement, after: ContextMeasurement): string {
+  if (before.contextTokens === undefined || after.contextTokens === undefined) return '上下文状态：暂无可用测量数据。'
+  if (before.contextTokens === after.contextTokens) {
+    return `上下文保持不变：${fmtCount(before.contextTokens)} tokens。`
+  }
+  return `上下文状态可能已变化：执行前 ${fmtCount(before.contextTokens)} tokens，当前 ${fmtCount(after.contextTokens)} tokens；请检查 Session 后再重试。`
+}