@zhushanwen/pi-session-reader 0.10.4 → 0.12.0

package/src/discovery/subagents.ts

@@ -1,11 +1,11 @@
 import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
-import { join, basename } from 'node:path'
+import { join } from 'node:path'
 import type { Entry } from '@zhushanwen/session-core'
 import type { Family, SessionRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
 import { listZcodeManifests } from './zcode-manifest.js'
-import { resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { resolveSessionRoots, resolveSessionStoreRoot, resolveStoreSubagentRecordsDir, listSessionStorePartitions, type SessionFileMeta } from './roots.js'
 import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
 
@@ -186,7 +186,8 @@ async function collectSubagentIdentities(
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
   // A3（ext-simplify-04）：直调 resolveSessionRoots（原 listSubagentSessions 薄包装已删除）
-  //——agentDir 信号包下 [subagent] 根 = <agentDir>/subagents（常量推导，恒唯一）
+  //——[subagent] 根 = session 存储树（[session-store-layout-inversion] 单新根，常量
+  // 推导，恒唯一；扫描定向探各 sid 分区的 subagents/sessions/）。
   const subMetas =
     (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
   for (const meta of subMetas) {
@@ -418,31 +419,37 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
 }
 
 /**
- * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 由终态 finalize 或 sync 批落标出口写入（创建时不写），持久存在即使
+ * 扫描 records/*.json —— subagent 注册清单（读侧单新根，[session-store-layout-inversion]
+ * D6 裁决：旧布局存量原位保留、不再读写——旧 record 从 agent 面 result/find 消失是该
+ * 裁决取舍清单明示项，不做旧根兼容扫描）。
+ * 每个 manifest 由终态 finalize 或 rebuildIndexes 投影写入（创建时不写），持久存在即使
  * .jsonl 被 GC。坏 manifest（缺必填字段/JSON 损坏）跳过，不中断扫描。
+ *
+ * 单新根：`<dataDir>/ext-sessions`（dataDir = dirname(agentDir)，布局 B agentDir =
+ * `<dataDir>/agent`；树根段镜像 shared SESSION_STORE_DIR_SEGMENT，对拍机检锚点 =
+ * scripts/check-artifact-dir-formula-sync.mjs 域 9）。新布局 records 在
+ * `<root>/<sid>/subagents/records/`（分区键 = rootSessionId，嵌套派发全层同值——
+ * 嵌套 subagent 的 manifest 同落根会话分区，固定位置扫描完整覆盖）。扫描剪枝：
+ * `<root>/` 一级只进 isPiSessionId 形态目录（不进 logs/attachments 等大目录），每个
+ * sid 分区内只探 subagents/records/ 固定位置，不整树递归。根不存在时静默空读。
  */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
-  const root = join(agentDir, 'subagents')
+  const storeRoot = resolveSessionStoreRoot(agentDir)
   const out: RecordManifest[] = []
-  async function walk(dir: string): Promise<void> {
+  for (const sid of await listSessionStorePartitions(storeRoot)) {
+    const recordsDir = resolveStoreSubagentRecordsDir(agentDir, sid)
     let entries
     try {
-      entries = await readdir(dir, { withFileTypes: true })
+      entries = await readdir(recordsDir, { withFileTypes: true })
     } catch {
-      return // 目录不存在/无权限 → 静默返回
+      continue // 该分区无 records/（无 subagent 的会话）→ 静默跳过
     }
     for (const e of entries) {
-      const full = join(dir, e.name)
-      if (e.isDirectory()) {
-        await walk(full)
-      } else if (e.isFile() && e.name.endsWith('.json') && basename(dir) === 'records') {
-        const m = await tryReadManifest(full)
-        if (m) out.push(m)
-      }
+      if (!e.isFile() || !e.name.endsWith('.json')) continue
+      const m = await tryReadManifest(join(recordsDir, e.name))
+      if (m) out.push(m)
     }
   }
-  await walk(root)
   return out
 }
 

package/src/discovery/whitelist.ts

@@ -16,8 +16,8 @@ import { zcodeImportDbAllowlist } from '@zhushanwen/zcode-session-source'
  *
  * **检查顺序铁律（§3.4 三段递进，实现与测试双锚定）**：存在性先于路径——
  * `existsSync` 为 false 报 `zcode_db_unreadable`（库文件不存在）而非
- * `zcode_db_path_forbidden`，避免把「只是还没落库」误报成安全事件（forbidden 是
- * 安全面错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
+ * `zcode_db_path_forbidden`，避免把「只是还没写入仓库」误报成安全事件（forbidden 是
+ * 安全侧错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
  * 开库（第 3 段）由调用方在本闸通过后进行。
  *
  * **TOCTOU 残留（设计 §3.4 显式登记，不在本梯队硬化）**：realpath 之后仍按原
@@ -72,10 +72,10 @@ export function formatZcodeDbPathForbidden(dbPath: string): string {
  * 白名单闸（第 1 段存在性 → 第 2 段路径；通过才允许开库）。
  *
  * @throws Error（消费侧映射为 zcode_db_unreadable / zcode_db_path_forbidden，
- *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误面）
+ *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误范围）
  */
 export function assertZcodeDbPathAllowed(dbPath: string, agentDir: string): void {
-  // 第 1 段 存在性（先于路径——「还没落库」不是安全事件）
+	// 第 1 段 存在性（先于路径——「还没写入仓库」不是安全事件）
   if (!existsSync(dbPath)) {
     throw new Error(formatZcodeDbUnreadable(dirname(agentDir), `（库文件不存在：${dbPath}）`))
   }

package/src/discovery/workflows.ts

@@ -17,7 +17,7 @@ import { extractSessionIdFromFilename } from './subagents.js'
 //   ——家族链数据源同 record 流，无第二承载位）；旧后缀锚点（.events.jsonl 形态）=
 //   历史实体（[D1] 历史数据处置：旧两件不读）→ calls=[] 仅 run 存在性兜底。
 //   历史格式条目（v1 全量快照 / workflow-state-link 指针）不识别、静默从发现链消失
-//   （不拒读、不报错）——run 侧 v1 读面已删除（ADR-0095，同 record 侧裁决：项目未
+//   （不拒读、不报错）——run 侧 v1 读侧已删除（ADR-0095，同 record 侧裁决：项目未
 //   上线无历史数据，不迁移不兼容）。
 // - readRunSnapshot：读 wf-state 文件尾向找首个可解析行，返回原始对象（unknown，格式
 //   收窄交 core 层）。唯一消费方 = tool-handler workflow 概览的快照链分支。
@@ -82,16 +82,16 @@ function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): S
 }
 
 // ============================================================
-// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试守卫漂移）
+// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试检查漂移）
 // ============================================================
 
 /**
  * `workflow-record` custom entry 的 customType 值。
  *
  * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core
- * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖面不引
+ * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖范围不引
  * subagent-core（同 entry-anchor.ts 的协议字面量模式），两侧漂移由 workflow.test.ts
- * 的跨包断言守卫。
+ * 的跨包断言检查。
  */
 const WORKFLOW_RECORD_CUSTOM_TYPE = 'workflow-record'
 
@@ -102,7 +102,7 @@ const WORKFLOW_RECORD_ENTRY_V2 = 2
  * run record 流文件名尾段（`<runId>.record.jsonl`）。写侧 subagent-core
  * RUN_EVENTS_SUFFIX 同值（[D1] record 单源后缀）——v2 注册条目的
  * recordPath 锚点后缀判定用（新锚点直读 record 流；旧 `.events.jsonl` 锚点 =
- * 历史实体分流），本地持有 + 测试守卫漂移。
+ * 历史实体分流），本地持有 + 测试检查漂移。
  */
 export const RUN_RECORD_STREAM_SUFFIX = '.record.jsonl'
 
@@ -142,7 +142,7 @@ function collectRegisteredRecordPaths(entries: readonly Entry[]): RegisteredReco
 /**
  * [D16③] recordPath 后缀分流：`.record.jsonl` 锚点 = 新形态（record 流直读）；
  * 其余（含旧 `.events.jsonl` 锚点）= 历史实体（[D1] 历史数据处置——旧两件不读
- * 不写，历史 run 从发现链数据面退空即预期行为）。
+ * 不写，历史 run 从发现链的数据中退空即预期行为）。
  */
 function isNewRecordStreamAnchor(recordPath: string): boolean {
   return recordPath.endsWith(RUN_RECORD_STREAM_SUFFIX)
@@ -155,7 +155,7 @@ interface AgentSettledSessionFileView {
   result: { sessionFile: string }
 }
 
-/** [extractRecordStreamSessionFiles 守卫] 单帧是否为携带非空 result.sessionFile
+/** [extractRecordStreamSessionFiles 检查] 单帧是否为携带非空 result.sessionFile
  *  的 agent-settled 帧：逐字段 typeof 校验（type → taskIndex → result →
  *  sessionFile），不过关 = 宽容跳过（与 readRunSnapshot 同容忍度）。 */
 function isAgentSettledSessionFileFrame(v: unknown): v is AgentSettledSessionFileView {
@@ -194,7 +194,7 @@ export function extractRecordStreamSessionFiles(content: string): string[] {
 /**
  * 读目标 session 文件全文，从 workflow-record v2 注册条目构造 WorkflowRef[]
  * （单档发现链——v1 快照条目与 workflow-state-link 指针条目不再识别，历史 run
- * 从发现链数据面退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
+ * 从发现链的数据中退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
  * （条目顺序 = 时间顺序，取最新锚点）。
  *
  * **签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）不变**

package/src/discovery/zcode-manifest.ts

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises'
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { resolveSessionStoreRoot, listSessionStorePartitions } from './roots.js'
 import type { ZcodeAnchor } from './entry-anchor.js'
 import type { ZcodeFamilyNode } from '../core/family.js'
 
@@ -9,9 +10,9 @@ import type { ZcodeFamilyNode } from '../core/family.js'
  * zcode manifest 直读与枚举（design session-reader-shared-core §3.1 第①步 / D5 / D5-1）。
  *
  * 背景（F21）：pi 路径的 `isRecordManifest` 三必填含 `sessionFile`，而 zcode manifest
- * 落盘时该键被 JSON.stringify 丢弃（subagent-core record-store-rebuild.ts:665/725 投影
+ * 落盘时该键被 JSON.stringify 丢弃（subagent-core record-store-rebuild.ts:665/725 派生视图
  * 照写 `sessionFile: undefined`）→ `listRecordManifests` 对 zcode manifest 恒返回 []。
- * 本单元另开一条**不经过该守卫**的独立路径：
+ * 本单元另开一条**不经过该检查**的独立路径：
  * - **定点直读**（`readZcodeManifest`）：manifest 文件名由 sa-id 完全确定（写侧
  *   `path.join(recordsDir, \`${record.id}.json\`)`，manifest-store.ts:141/153），按确定性
  *   文件名 `<sa-id>.json` 在 `<agentDir>/subagents/<cwd>/records/` 下**窄 walk（命中即止，
@@ -24,7 +25,7 @@ import type { ZcodeFamilyNode } from '../core/family.js'
  * `listRecordManifests`（subagents.ts）一行不改——pi manifest 仍走原扫描路径，本单元
  * 的谓词**不走** isRecordManifest。判别规则与 runtime `transcriptAnchorOf` 同构
  * （F8：`engine === 'zcode'` 第一判据 + sessionRef 双键齐）。用 `engine` 判别而非
- * 「engineHandle 存在性」的理由见 D5 被否项 ②（pi record 提升后 engineHandle 仍持久化，
+ * 「engineHandle 存在性」的理由见 D5 不采用项 ②（pi record 提升后 engineHandle 仍持久化，
  * 存在性判别会误路由）。
  */
 
@@ -43,7 +44,7 @@ export interface ZcodeManifestRecord extends ZcodeFamilyNode {
 /**
  * anchor-missing 的缺失键归因（§3.4：缺失键名进结构化日志——engineHandle 整体缺席 /
  * 缺 sessionRef / 缺 sessionId / 缺 dbPath 归因不同：整体缺席多为旧版本产物，缺
- * sessionId 多为引擎未回调 onHandleReady，缺 dbPath 多为写入面截断）。entry 兜底侧
+ * sessionId 多为引擎未回调 onHandleReady，缺 dbPath 多为写侧截断）。entry 兜底侧
  * 的同构分类（tool-handler classifyIncompleteEntryAnchor）复用本类型单源。
  */
 export type ZcodeAnchorMissingReason =
@@ -67,7 +68,7 @@ export type ZcodeManifestLookup =
   | { kind: 'not-zcode' }
   | { kind: 'anchor-missing'; reason: ZcodeAnchorMissingReason }
 
-/** manifest 顶层 JSON 的读取视图（守卫输入） */
+/** manifest 顶层 JSON 的读取视图（检查输入） */
 type ManifestJson = Record<string, unknown>
 
 function asObject(v: unknown): ManifestJson | undefined {
@@ -125,7 +126,7 @@ function richFieldsOf(m: ManifestJson): ManifestRichFields {
   return out
 }
 
-/** stat 存在性（任意路径无安全面——D5-1 只查「文件在不在」，不开库） */
+/** stat 存在性（任意路径无安全侧——D5-1 只查「文件在不在」，不开库） */
 function fileExists(p: string): boolean {
   try {
     statSync(p)
@@ -161,7 +162,13 @@ function toZcodeManifestRecord(m: ManifestJson): ZcodeManifestRecord | undefined
   }
 }
 
-/** `<agentDir>/subagents` 布局常量（与写侧 path-encoding/manifest-store 布局对齐） */
+/**
+ * [session-store-layout-inversion D6/单新根] zcode manifest 读侧 = session 存储树分区
+ * 固定位置 `<root>/<rootSessionId>/subagents/records/`（根推导与分区枚举复用 roots.ts
+ * 的 resolveSessionStoreRoot / listSessionStorePartitions——同包单源防漂移）。旧布局
+ * `<agentDir>/subagents/<cwdSlug>/records/` 不再读写（D6 存量不迁移不读取——旧 zcode
+ * record 从 agent 面消失是 D6 取舍清单明示项）。
+ */
 const SUBAGENTS_DIR = 'subagents'
 const RECORDS_DIR = 'records'
 
@@ -196,22 +203,16 @@ export async function readZcodeManifest(
   agentDir: string,
   saId: string,
 ): Promise<ZcodeManifestLookup> {
-  const root = join(agentDir, SUBAGENTS_DIR)
-  let slugs: DirentLike[]
-  try {
-    slugs = await readdir(root, { withFileTypes: true })
-  } catch {
-    return { kind: 'not-zcode' } // subagents 根不存在/不可读 → 无 manifest
-  }
-  for (const e of slugs) {
-    if (!e.isDirectory()) continue
-    const file = join(root, e.name, RECORDS_DIR, `${saId}.json`)
+  const root = resolveSessionStoreRoot(agentDir)
+  const partitions = await listSessionStorePartitions(root)
+  for (const part of partitions) {
+    const file = join(root, part, SUBAGENTS_DIR, RECORDS_DIR, `${saId}.json`)
     let raw: string
     try {
       // 命中即止：只读这一个文件（文件名由 sa-id 确定），坏内容同样终止（见 parseManifestLookup）
       raw = await readFile(file, 'utf8')
     } catch {
-      continue // 该 cwd 目录下无此 manifest → 下一候选目录
+      continue // 该分区无此 manifest → 下一候选分区
     }
     return parseManifestLookup(raw)
   }
@@ -236,17 +237,11 @@ interface DirentLike {
  * family 是列表视图，单节点不可达不炸整屏（D5-1 GC 语义）。
  */
 export async function listZcodeManifests(agentDir: string): Promise<ZcodeManifestRecord[]> {
-  const root = join(agentDir, SUBAGENTS_DIR)
+  const root = resolveSessionStoreRoot(agentDir)
   const out: ZcodeManifestRecord[] = []
-  let slugs: DirentLike[]
-  try {
-    slugs = await readdir(root, { withFileTypes: true })
-  } catch {
-    return out // 根不存在/不可读 → 空（无 zcode 节点，不报错）
-  }
+  const slugs = await listSessionStorePartitions(root)
   for (const slug of slugs) {
-    if (!slug.isDirectory()) continue
-    const recordsDir = join(root, slug.name, RECORDS_DIR)
+    const recordsDir = join(root, slug, SUBAGENTS_DIR, RECORDS_DIR)
     let files: DirentLike[]
     try {
       files = await readdir(recordsDir, { withFileTypes: true })

package/src/extract.ts

@@ -347,7 +347,7 @@ function collectCommitCandidates(
   return { high, low }
 }
 
-/** 收口阶段：去重，高置信优先，同 hash 保留首次。 */
+/** 收尾阶段：去重，高置信优先，同 hash 保留首次。 */
 function dedupeCommits(high: CommitItem[], low: CommitItem[]): CommitItem[] {
   const seen = new Set<string>()
   const items: CommitItem[] = []

package/src/index.ts

@@ -1,12 +1,14 @@
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext, Theme } from '@earendil-works/pi-coding-agent'
 import { getAgentDir, SessionManager } from '@earendil-works/pi-coding-agent'
 import { StringEnum } from '@earendil-works/pi-ai'
 import { Type } from 'typebox'
 import { setPiHandle } from '@zhushanwen/pi-extension-logger'
 import type { SessionMetadataProvider } from './discovery/find.js'
+import { withResultSummary } from './summary.js'
 import { handleSessionRead, type SessionReadParams, type SessionReadSignals } from './tool-handler.js'
 import { createHashAutocompleteProvider } from './tui/hash-provider.js'
 import { createSessionCommand } from './tui/session-command.js'
+import { renderSessionReadResult } from './tui/tool-render.js'
 
 /**
  * pi-session-reader extension 入口（M3 工具适配层）。
@@ -154,7 +156,7 @@ const guidelines = [
   // 工具内指向本工具的交叉引用，非本清单的锚）。
   'Progressive reading: outline (~1500 tokens) → expand (one turn) → detail; defaults omit toolResult/thinking noise.',
   'find first (uuid fragment / name); TUI #references are full uuids. Never read raw .jsonl—use this tool.',
-  // zcode 路由（U9）对 LLM 的唯一可见面：sa-id 输入自动路由，无需任何参数；首遇
+  // zcode 路由（U9）对 LLM 的唯一可见部分：sa-id 输入自动路由，无需任何参数；首遇
   // zcode_* 错误码前先有背景预告。
   'sa- ids route transparently to pi or zcode engine sessions; sess_ prefixed ids are not accepted—use the completion-notice sa- id.',
   'Errors carry a 👉 recovery hint—follow it to retry.',
@@ -232,7 +234,13 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
       }
       // u11：标题元数据 provider 随信号包注入（provider 抛错由发现层单目录降级，
       // 不会变成工具错误——宿主 listAll 异常不得打断 find 的「能找到 session」底线）。
-      return handleSessionRead(params, signals, signal, metadataProvider)
+      const result = await handleSessionRead(params, signals, signal, metadataProvider)
+      // 收起态一行摘要：details 追加 summary（现有字段保留），GUI 收起态与 TUI 折叠态共用
+      return withResultSummary(params, result)
+    },
+
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderSessionReadResult(result, options, theme)
     },
   })
 
@@ -242,7 +250,7 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
   //
   // addAutocompleteProvider 挂在 ctx.ui（非 ExtensionAPI），setup 入口无 ctx，
   // 只能在 event handler 里拿——session_start 是最早且每 session 触发的 event。
-  // once-guard + ctx.mode 守卫 + typeof 运行时守卫三重防护。
+	// once-guard + ctx.mode 检查 + typeof 运行时检查三重防护。
   //
   // 2026-08-10 重构：数据源从全盘 findSessions(agentDir) 换为 SessionManager.listAll(ctx.sessionManager.getSessionDir())。
   // getSessionDir() 返回当前 session 的目录（encoded cwd），listAll 只扫该目录 →

package/src/no-match.ts

@@ -147,7 +147,7 @@ function guidanceLines(): string[] {
  * ③「正确做法」四条：标题/keyword、绝对路径 outline、更短前缀、doctor。
  * ④ 最后一行封死 shell 绕行：find/ls/rg 搜 session 目录、cat/read 原始 .jsonl 均禁止。
  *
- * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 被否项）。
+ * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 不采用项）。
  */
 export function formatNoMatch(query: string, roots: SessionRoot[]): string {
   return [

package/src/result-action.ts

@@ -31,7 +31,7 @@ const RESULT_DEFAULT_LIMIT = 8000
 /** result 批量条目分隔符（与 notifier 批通知 "\n\n---\n\n" join 同款）。 */
 const RESULT_BATCH_SEPARATOR = '\n\n---\n\n'
 
-/** result action 对 tool-handler 文件私有 helper 的注入面（入口分发处 per-call 构造）。 */
+/** result action 对 tool-handler 文件私有 helper 的注入点（入口分发处 per-call 构造）。 */
 export interface ResultActionDeps {
   resolveSessionId(
     rawSession: string | undefined,

package/src/search-across.ts

@@ -137,7 +137,7 @@ export function collectSearchHits(
   return hits
 }
 
-/** search 收口阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
+/** search 收尾阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
 export function formatSearchText(
   pattern: string,
   degraded: boolean,
@@ -196,7 +196,7 @@ interface CrossSearchSkipped {
   sizeBytes?: number
 }
 
-/** 跨会话检索 details（程序化消费/测试断言面）。 */
+/** 跨会话检索 details（程序化消费/测试断言范围）。 */
 export interface CrossSearchDetails {
   pattern: string
   scope: NonNullable<SessionReadParams['scope']>
@@ -355,7 +355,7 @@ interface CrossSearchOptions {
   byteBudget?: number
 }
 
-/** 缺省值收口后的检索参数（各缺省值与旧内联 `opts?.** ?? 常量` 逐一对应）。 */
+/** 缺省值收尾后的检索参数（各缺省值与旧内联 `opts?.** ?? 常量` 逐一对应）。 */
 interface CrossSearchResolvedOptions {
   scope: NonNullable<SessionReadParams['scope']>
   limit: number

package/src/summary.ts

@@ -0,0 +1,178 @@
+/**
+ * session_read 工具的收起态一行摘要（GUI details.summary + TUI renderResult 共用）。
+ *
+ * 纯函数：按 params.action 经分发表派发到各 action 的 summarizer 小函数，从
+ * result.details 容错取数（details 形态随 action 与历史 entry 版本漂移，逐字段
+ * typeof/Array.isArray 守卫，取不到的后缀省略）。文案与 content 正文风格一致
+ * （动作 + 数量/目标），一行英文，不带逐条详情。
+ * 每个 action 独立函数（圈复杂度门禁：单函数 ≤15；曾以单函数全内联 11-action
+ * switch 达 44 被门禁拦截后拆分）。
+ */
+
+import type { SessionReadAction, SessionReadParams, ToolResult } from './tool-handler.js'
+import { pad } from './handler-utils.js'
+
+// ---- details 容错取数原语（details 是 unknown，逐字段守卫替代裸断言）----
+
+function asRecord(v: unknown): Record<string, unknown> {
+  return typeof v === 'object' && v !== null ? (v as Record<string, unknown>) : {}
+}
+
+function numOf(v: unknown): number | undefined {
+  return typeof v === 'number' ? v : undefined
+}
+
+function strOf(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined
+}
+
+function arrOf(v: unknown): unknown[] | undefined {
+  return Array.isArray(v) ? v : undefined
+}
+
+function countOf(details: Record<string, unknown>, key: string): number {
+  return arrOf(details[key])?.length ?? 0
+}
+
+/** 截断标注（find/search/result 的 truncated 字段在场且为真时追加） */
+function truncatedSuffix(details: Record<string, unknown>): string {
+  return details.truncated === true ? ' (truncated)' : ''
+}
+
+/** session 未解析出显式值时的占位（params.session 可选字段缺省 → 空串） */
+function sessionLabel(params: SessionReadParams): string {
+  return params.session ?? ''
+}
+
+// ---- 各 action 的 summarizer（签名统一，经 ACTION_SUMMARIZERS 分发）----
+
+function summarizeFind(params: SessionReadParams, details: Record<string, unknown>): string {
+  const query = params.query ?? ''
+  const matches = countOf(details, 'matches')
+  if (matches === 0) return `No sessions matching "${query}"`
+  return `Found ${matches} sessions matching "${query}"${truncatedSuffix(details)}`
+}
+
+function summarizeFamily(params: SessionReadParams, details: Record<string, unknown>): string {
+  // recursive=true 的 details 是 { tree }；flat 的 details 是 Family（root/parents/forks/subagents/workflows）
+  if (details.tree !== undefined) return `Execution tree of session ${sessionLabel(params)}`
+  const relations =
+    countOf(details, 'parents') + countOf(details, 'forks') + countOf(details, 'subagents') + countOf(details, 'workflows')
+  return `Family of session ${sessionLabel(params)}: ${relations} relations`
+}
+
+function summarizeOutline(params: SessionReadParams, details: Record<string, unknown>): string {
+  const turns = numOf(asRecord(details.stats).totalTurns)
+  return turns === undefined
+    ? `Outline of session ${sessionLabel(params)}`
+    : `Outline of session ${sessionLabel(params)} · ${turns} turns`
+}
+
+function summarizeExpand(params: SessionReadParams, details: Record<string, unknown>): string {
+  const turn = numOf(asRecord(details.turn).index)
+  const entries = countOf(details, 'entries')
+  return `Expanded turn ${turn !== undefined ? `T${pad(turn)}` : (params.turn ?? '')} · ${entries} entries`
+}
+
+function summarizeDetail(params: SessionReadParams, details: Record<string, unknown>): string {
+  const label = strOf(details.turns) ?? params.turns ?? ''
+  return `Read turns ${label} · ${countOf(details, 'entries')} entries`
+}
+
+function summarizeSearch(params: SessionReadParams, details: Record<string, unknown>): string {
+  const pattern = params.pattern ?? ''
+  const hits = countOf(details, 'hits')
+  if (hits === 0) return `No hits for "${pattern}"`
+  return `Found ${hits} hits for "${pattern}"${truncatedSuffix(details)}`
+}
+
+function summarizeExport(params: SessionReadParams, details: Record<string, unknown>): string {
+  const format = params.format ?? 'outline'
+  const sizeBytes = numOf(details.sizeBytes)
+  return sizeBytes === undefined
+    ? `Exported ${format} view`
+    : `Exported ${format} view · ${sizeBytes} bytes`
+}
+
+function summarizeExtract(params: SessionReadParams, details: Record<string, unknown>): string {
+  const what = strOf(details.what) ?? params.what ?? ''
+  const count = numOf(details.count) ?? 0
+  if (count === 0) return `No ${what} found`
+  const shown = numOf(details.shown)
+  const clipped = details.truncated === true && shown !== undefined ? ` (showing ${shown})` : ''
+  return `Extracted ${count} ${what}${clipped}`
+}
+
+function summarizeWorkflow(_params: SessionReadParams, details: Record<string, unknown>): string {
+  const runs = countOf(details, 'runs')
+  if (runs === 0) return 'No workflow runs'
+  const skipped = countOf(details, 'skippedRuns')
+  return `Found ${runs} workflow runs${skipped > 0 ? ` · ${skipped} skipped` : ''}`
+}
+
+function summarizeResult(params: SessionReadParams, details: Record<string, unknown>): string {
+  // 批量 details = { count, items }；单条 details = ResultItem 本体（session/totalChars/truncated）
+  const count = numOf(details.count)
+  if (count !== undefined && details.items !== undefined) {
+    return `Read ${count} final results`
+  }
+  const session = strOf(details.session) ?? sessionLabel(params)
+  const totalChars = numOf(details.totalChars)
+  return `Read final result of ${session} · ${totalChars !== undefined ? `${totalChars} chars` : 'done'}${truncatedSuffix(details)}`
+}
+
+function summarizeDoctor(_params: SessionReadParams, details: Record<string, unknown>): string {
+  const roots = arrOf(details.roots)
+  return roots !== undefined ? `Doctor: ${roots.length} roots checked` : 'Doctor check completed'
+}
+
+/** 消歧结果（任意 action 的 session 解析多匹配共用此 details 形态），优先于 action 分发 */
+function summarizeAmbiguous(params: SessionReadParams, details: Record<string, unknown>): string {
+  const candidates = countOf(details, 'candidates')
+  return `Ambiguous session "${params.session ?? ''}": ${candidates} candidates`
+}
+
+/** 未知/缺省 action 的兜底（历史 entry 漂移面，展示面不抛错） */
+function summarizeDone(): string {
+  return 'Done'
+}
+
+/** action → summarizer 分发表（Partial：运行时未知 action 落 summarizeDone 兜底） */
+const ACTION_SUMMARIZERS: Partial<Record<SessionReadAction, (params: SessionReadParams, details: Record<string, unknown>) => string>> = {
+  find: summarizeFind,
+  family: summarizeFamily,
+  outline: summarizeOutline,
+  expand: summarizeExpand,
+  detail: summarizeDetail,
+  search: summarizeSearch,
+  export: summarizeExport,
+  extract: summarizeExtract,
+  workflow: summarizeWorkflow,
+  result: summarizeResult,
+  doctor: summarizeDoctor,
+}
+
+/**
+ * 按 action 产出一行摘要。action 与 details 不匹配（历史 entry / 异常形态）时
+ * 落到该 action 的兜底文案，不抛错——summary 是展示面，失败不追究。
+ */
+export function buildSessionReadSummary(params: SessionReadParams, result: ToolResult): string {
+  const details = asRecord(result.details)
+  if (details.ambiguous === true) return summarizeAmbiguous(params, details)
+  const summarize = ACTION_SUMMARIZERS[params.action] ?? summarizeDone
+  return summarize(params, details)
+}
+
+/**
+ * 给 tool result 的 details 追加 summary（现有字段一律保留）。details 非对象
+ * （防御形态）时整体替换为 { summary }——生产路径 details 恒为对象，此分支只为
+ * 类型完备。
+ */
+export function withResultSummary(params: SessionReadParams, result: ToolResult): ToolResult {
+  const summary = buildSessionReadSummary(params, result)
+  const details = result.details
+  if (details === null || typeof details !== 'object' || Array.isArray(details)) {
+    return { ...result, details: { summary } }
+  }
+  return { ...result, details: { ...details, summary } }
+}

package/src/tool-format.ts

@@ -1,11 +1,11 @@
 /**
  * session_read 各 action 的输出文本渲染（max-lines 拆分轮从 tool-handler.ts 机械
- * 提取，零行为变更）：错误面 message（ES1/ES2 + zcode 七码 + 开库/查询期错误映射）+
+ * 提取，零行为变更）：错误范围 message（ES1/ES2 + zcode 七码 + 开库/查询期错误映射）+
  * content 文本（find/outline/expand/detail/family）+ entry 可读文本 + F2 消歧与
  * find 零匹配的 ToolResult 包装。纯字符串/纯渲染函数，不触 fs（findNoMatch 的
  * roots 由调用方传入）。
  *
- * 导出面：SQLITE_DRIVER_UNSUPPORTED_MARK / ZCODE_DB_MISSING_MARK /
+ * 导出清单：SQLITE_DRIVER_UNSUPPORTED_MARK / ZCODE_DB_MISSING_MARK /
  * zcodeReadErrorMessage（测试契约锚消费方直接 import 本模块）。logger 用同名
  * getLogger('session-reader')——按名缓存单例，与 tool-handler 侧同一实例，
  * warn/error 落同一 appendEntry/文件日志通道。ToolResult 等公共类型留
@@ -84,7 +84,7 @@ export function formatSaIdNotFound(saId: string): string {
 }
 
 // ---------------------------------------------------------------------------
-// zcode 错误面（U9，design §3.4 七码 + 👉 逐行；错误码标识入 message 供机器识别，
+// zcode 错误范围（U9，design §3.4 七码 + 👉 逐行；错误码标识入 message 供机器识别，
 // 形态对齐 §3.1 失败路径示例 `[zcode_db_path_forbidden] …`）
 // ---------------------------------------------------------------------------
 
@@ -131,7 +131,7 @@ function formatZcodeSchemaDrift(observed: string | undefined): string {
 
 /**
  * bun 驱动探测失败（§3.4 表第 8 行理论态）的 message：宿主既无 bun:sqlite 也无
- * node:sqlite——zcode action 整体降级为本错误面（fail-fast + 日志），pi 链路不受影响。
+ * node:sqlite——zcode action 整体降级为本错误范围（fail-fast + 日志），pi 链路不受影响。
  * 错误码字面量为实施期命名（设计该行未定码名，形态对齐七码 `[zcode_*]` 惯例）。
  */
 function formatZcodeHostUnsupported(detail: string): string {
@@ -145,8 +145,8 @@ function formatZcodeHostUnsupported(detail: string): string {
 /**
  * sqlite 驱动探测失败的消息特征（zcode-session-source sqlite-driver.ts 探测失败的
  * 错误消息契约；该包不导出专用错误子类，reader 侧按消息特征单列识别——跨包漂移
- * 由 zcode-routing.test.ts 的源文本契约测试守卫：sqlite-driver 源文不再含本子串即红）。
- * 导出面仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
+ * 由 zcode-routing.test.ts 的源文本契约测试检查：sqlite-driver 源文不再含本子串即红）。
+ * 导出范围仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
  */
 export const SQLITE_DRIVER_UNSUPPORTED_MARK = '不支持 node:sqlite'
 
@@ -154,17 +154,17 @@ export const SQLITE_DRIVER_UNSUPPORTED_MARK = '不支持 node:sqlite'
  * 库文件缺失的消息特征（zcode-session-source sqlite-access.ts `openZcodeSessionDb`
  * 开头 existsSync 失败抛普通 Error「db 文件不存在：<dbPath>」的消息契约锚点）。该包
  * 不导出专用错误子类，reader 侧按消息特征单列识别——落 §3.4 第 4 行
- * `zcode_db_unreadable`（不误标 schema_drift）。生产路径上白名单闸
+ * `zcode_db_unreadable`（不误标 schema_drift）。生产路径上白名单门禁
  * （assertZcodeDbPathAllowed 第 1 段）已先行拦掉绝大多数缺失，此处命中的是两段
- * existsSync 之间的 TOCTOU 理论窗口（闸通过后开库前文件被删）。跨包漂移由
- * zcode-routing.test.ts 的源文本契约测试守卫（SQLITE_DRIVER_UNSUPPORTED_MARK 同范式）。
- * 导出面仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
+ * existsSync 之间的 TOCTOU 理论窗口（门禁通过后开库前文件被删）。跨包漂移由
+ * zcode-routing.test.ts 的源文本契约测试检查（SQLITE_DRIVER_UNSUPPORTED_MARK 同范式）。
+ * 导出范围仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
  */
 export const ZCODE_DB_MISSING_MARK = 'db 文件不存在'
 
 /**
- * 开库/查询期错误 → §3.4 错误面映射（SqliteUnreadableError / schema drift / 驱动探测失败 / 库缺失 / 其余）。
- * 导出面仅测试消费（L4 包装形态的映射契约直测，zcode-routing.test.ts）。
+ * 开库/查询期错误 → §3.4 错误范围映射（SqliteUnreadableError / schema drift / 驱动探测失败 / 库缺失 / 其余）。
+ * 导出范围仅测试消费（L4 包装形态的映射契约直测，zcode-routing.test.ts）。
  */
 export function zcodeReadErrorMessage(e: unknown, agentDir: string): string {
   if (e instanceof SqliteUnreadableError) {