@zhushanwen/pi-session-reader 0.2.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {

package/src/__tests__/render.test.ts

@@ -93,7 +93,7 @@ describe('renderOutline', () => {
   })
 
   it('2a. 降级：单行 toolSummary 过长超 perTurnBudget → 砍 toolSummary，保 userBrief 骨架', () => {
-    // L1 行不含 assistantBrief（design §3.5 算法1 step2）；budget=40, 3 turns → perTurnCharBudget≈53
+    // 预算紧张降级后 L1 行不含 assistantBrief（预算充足 level 0 行含）；budget=40, 3 turns → perTurnCharBudget≈53
     // 行 = head + userBrief(10) + toolSummary(20 个工具名≈63 chars) → ~80 > 53 → 砍 toolSummary
     const toolCalls = Array.from({ length: 20 }, (_, k) => ({ name: `t${String(k).padStart(2, '0')}` }))
     const turns = [0, 1, 2].map((i) =>
@@ -183,7 +183,7 @@ describe('renderOutline', () => {
     // stats 完整性
     expect(result.stats.totalTurns).toBe(32)
     // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）；
-    // 准确值由 M2 工具层用 ParseResult.totalEntries 覆盖。M1 验量级。
+    // 工具层仅覆盖 stats.totalBytes 与 skippedLines（ParseResult 无 totalEntries 字段）。M1 验量级。
     expect(result.stats.totalEntries).toBeGreaterThan(1000)
     // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
   }, 60000)

package/src/__tests__/tool-handler.test.ts

@@ -22,7 +22,7 @@ import {
  * 测试框架 vitest（禁止 node:test/tsx）。直接调 handleSessionRead（纯逻辑，agentDir 注入），
  * 传真实 `/Users/zhushanwen/.pi/agent` 作 agentDir——用本机真实历史 session 数据，无需 mock。
  *
- * 覆盖 7 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
+ * 覆盖 9 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
  *
  * 真实数据用例全部带 skipIf 守卫（CI 无本机 ~/.pi/agent → skip，不硬失败）；
  * renderExtractItems F9 截断是纯 fixture，无条件跑。
@@ -782,7 +782,7 @@ describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
       await handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, dir)
     } catch (e) {
       const msg = (e as Error).message
-      expect(msg).toContain('可能仍在运行')
+      expect(msg).toContain('可能尚未落盘')
       expect(msg).toContain('action:"family"')
       expect(msg).toContain('👉')
     }

package/src/core/execution-tree.ts

@@ -173,7 +173,6 @@ function collectRelatedRecords(
 // buildExecutionTree（IF3 核心）
 // ============================================================
 
-/** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 /** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 interface BuildContext {
   rootSessionId: string

package/src/core/family.ts

@@ -11,7 +11,7 @@ import type { Entry } from './parser.js'
  * - SessionRef.mtime/sizeBytes：从 fileStats 取（M1 key=sessionId），取不到为 0
  * - SubagentRef.sessionId：identity entry 不含 subagent session 的 id → 占位用 entry.id
  * - SubagentRef.cwd：identity entry（custom 类型）无 cwd → 占位空串
- * - fileStats 的 key：M1 用 sessionId（M2 改用真实文件路径），cleanedUp 逻辑 M1/M2 通用
+ * - fileStats 的 key：sessionId（M2 实现沿用此 key，cleanedUp 按 sessionId 命中），逻辑通用
  *
  * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
  */
@@ -24,7 +24,6 @@ export interface SessionRef {
   cwd: string
   /** fork 文件指向来源的路径（来自 header 的 parentSession，原始文件路径字符串） */
   parentSession?: string
-  name?: string
 }
 
 export interface SubagentRef extends SessionRef {
@@ -194,7 +193,7 @@ export function buildFamilyIndex(
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
       cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
-      // M1: fileStats key=sessionId；M2 改用 subagent 真实文件路径（SubagentRef.fileName）查 fileStats
+      // fileStats key=sessionId（buildFamilyFromFs 以 header.id 写入），cleanedUp 按 sessionId 命中
       cleanedUp: !fileStats.has(ident.id),
       // U4 富字段：从 identity data 读（manifest 主/P-fallback 由 buildFamilyFromFs 组装时决定）
       task: ident.data.task,

package/src/core/render.ts

@@ -285,7 +285,7 @@ function formatHHMM(timestamp?: string): string {
   return m ? `${m[1]}:${m[2]}` : ''
 }
 
-function formatBytesMarker(bytes: number): string {
+export function formatBytesMarker(bytes: number): string {
   if (bytes <= 0) return ''
   if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
   return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`

package/src/discovery/subagents.ts

@@ -23,7 +23,8 @@ import { resolveWorkflows } from './workflows.js'
  *   是 records/<sa-id>.json manifest（subagent 创建时写入，持久存在）。故 manifest 是孤儿/
  *   cleanedUp 的来源（design §3.3 D-7 "records/*.json manifest 作孤儿补充"）。
  * - workflows：M1 resolveFamily 恒返回 []。M2 在此单独读目标 session 的 workflow-state-link
- *   custom entry → link.data.path（wf-state 文件绝对路径）→ 读该文件最后一行（最新快照）取 calls。
+ *   custom entry → link.data.path（wf-state 文件绝对路径）→ 从文件尾向头找首个非空且
+ *   JSON.parse 成功的行（最新快照，容错尾半截 JSON）取 calls。
  *
  * @throws sessionId 不在任意 main session header → Error（M3 tool-adapter 层转 F1 恢复指引）
  */
@@ -87,7 +88,7 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       // manifest 主（TC-u4-manifest-enrich）：透 task/slug/model/status/sessionFile 全字段
       data = {
         rootSessionId: manifest.rootSessionId,
-        slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兑底，m0 契约）
+        slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兜底，m0 契约）
         task: manifest.task,
         agent: manifest.agentName, // 同语义异名：manifest.agentName ↔ identity.data.agent
         model: manifest.model,
@@ -163,7 +164,7 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   const family = resolveFamily(sessionId, index)
 
   // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
-  enrichRefs(family, sessionIdToPath, pathToRef)
+  enrichRefs(family, pathToRef)
   family.workflows = await resolveWorkflows(sessionId, sessionIdToPath, pathToRef)
 
   return family
@@ -330,11 +331,6 @@ function isRecordManifest(v: unknown): v is RecordManifest {
   )
 }
 
-/**
- * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
- * /JSON 损坏）跳过，不中断扫描。
- */
 /** 读单个 manifest 文件并校验；坏 manifest（JSON 损坏/缺必填字段）返回 undefined。 */
 async function tryReadManifest(path: string): Promise<RecordManifest | undefined> {
   try {
@@ -345,6 +341,11 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
   }
 }
 
+/**
+ * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
+ * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
+ * /JSON 损坏）跳过，不中断扫描。
+ */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
   const root = join(agentDir, 'subagents')
   const out: RecordManifest[] = []
@@ -395,11 +396,7 @@ export function extractSessionIdFromFilename(name: string): string {
  *（identity 无 cwd）。此处用已扫描的真实文件信息补全：alive 的 ref 补 fileName + cwd；
  * cleanedUp 孤儿（无文件）保持占位。
  */
-function enrichRefs(
-  family: Family,
-  sessionIdToPath: Map<string, string>,
-  pathToRef: Map<string, SessionRef>,
-): void {
+function enrichRefs(family: Family, pathToRef: Map<string, SessionRef>): void {
   // sessionId → 完整 ref（含真实 fileName/cwd），由 pathToRef 反建
   const bySid = new Map<string, SessionRef>()
   for (const ref of pathToRef.values()) bySid.set(ref.sessionId, ref)
@@ -426,6 +423,4 @@ function enrichRefs(
       cwd: full.cwd || s.cwd,
     } as SubagentRef
   })
-  // sessionIdToPath 仅用于类型完整性占位引用，避免未用警告（实际路径信息已在 pathToRef）
-  void sessionIdToPath
 }

package/src/index.ts

@@ -15,8 +15,6 @@ import { createSessionCommand } from './tui/session-command.js'
  *   （错误直接 throw 给 pi——pi-agent-core agent-loop 只对 execute throw 置
  *   isError:true，返回值里的 isError 字段被丢弃；W4 修复，锚点
  *   agent-loop.js:453-483/525-547，pi 自带 bash 工具同范式）
- *
- * M4 将在此 addAutocompleteProvider（TUI # 补全，ctx.mode === 'tui' 时）。
  */
 
 // ---- TypeBox 参数 schema（design §3.4 14 字段）----
@@ -32,7 +30,7 @@ const SessionReadSchema = Type.Object({
   session: Type.Optional(
     Type.String({
       description:
-        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/workflow. # prefix auto-stripped.',
+        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -43,7 +41,7 @@ const SessionReadSchema = Type.Object({
   ),
   turns: Type.Optional(
     Type.String({
-      description: 'detail action: turn range, "T013-T015" or "T013".',
+      description: 'detail/extract action: turn range, "T013-T015" or "T013".',
     }),
   ),
   turn: Type.Optional(
@@ -74,7 +72,8 @@ const SessionReadSchema = Type.Object({
   ),
   allBranches: Type.Optional(
     Type.Boolean({
-      description: 'outline/family: include abandoned side-branches. Default false.',
+      description:
+        "outline (and export's outline section): include abandoned side-branches. Not supported by family. Default false.",
     }),
   ),
   granularity: Type.Optional(
@@ -87,7 +86,8 @@ const SessionReadSchema = Type.Object({
   ),
   source: Type.Optional(
     StringEnum(['main', 'subagent'], {
-      description: 'find action: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
+      description:
+        'find and session-resolving actions: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
     }),
   ),
   limit: Type.Optional(
@@ -123,8 +123,8 @@ const SessionReadSchema = Type.Object({
 // ---- guidelines（注入 LLM，design §3.4）----
 
 const guidelines = [
-  'Progressive reading: outline (~500 token overview) → expand (one turn) → detail (full text). Default omits toolResult/thinking noise.',
-  'find first to locate a session by uuid fragment or name. TUI #references are uuid fragments.',
+  'Progressive reading: outline (~1500 token overview) → expand (one turn) → detail (full text). Default omits toolResult/thinking noise.',
+  'find first to locate a session by uuid fragment or name. TUI #references are full uuids.',
   'outline before detail. Never read raw .jsonl files—use this tool.',
   'family traces fork parents/children, subagent sessions, and workflow runs.',
   'extract what=<type> to pull user messages / commands / files / commits / tool results across turns (optional tool= filter for commands/tool-results).',
@@ -134,7 +134,7 @@ const guidelines = [
 
 // ---- 工具 description（design §3.4，照搬措辞）----
 
-const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (use get_messages) or to edit sessions (pi has /resume /fork).`
+const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。

package/src/tool-handler.ts

@@ -4,7 +4,7 @@
  * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
- * 按 action 分发到 8 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
+ * 按 action 分发到 9 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
@@ -28,6 +28,7 @@ import {
   renderOutline,
   renderExpand,
   renderDetail,
+  formatBytesMarker,
   type OutlineOptions,
   type OutlineResult,
   type EntryBrief,
@@ -126,15 +127,6 @@ function shortCwd(cwd: string): string {
   return parts.slice(-SHORT_CWD_SEGMENTS).join('/')
 }
 
-/** bytes→KB 换算基数（formatOmitted 的 KB 显示）。 */
-const BYTES_PER_KB = 1024
-
-function formatOmitted(bytes: number): string {
-  if (bytes <= 0) return ''
-  if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`
-}
-
 /** F5 必填参数校验。 */
 function requireStr(
   val: string | undefined,
@@ -347,7 +339,7 @@ function formatSessionGc(record: RecordManifest): string {
 /** ES2（SA_ID_NO_MATCH）：sa-id 无精确匹配（可能仍在运行 / 片段输入）。 */
 function formatSaIdNotFound(saId: string): string {
   return (
-    `subagent "${saId}" 无匹配 record（可能仍在运行——终态 record 在 completed/failed 后才写）。` +
+    `subagent "${saId}" 无匹配 record（若刚启动，record 可能尚未落盘）。` +
     `\n👉 用 session_read { action:"family" } 查活跃/已完成的 subagent；` +
     `若是片段输入，请用完整 sa- id 或 action:"find" 重试。`
   )
@@ -439,7 +431,7 @@ function formatOutlineText(r: OutlineResult): string {
     if (b.toolSummary) parts.push(b.toolSummary)
     // v2 O1：补 assistant 结论行（→ ）让 outline 单独可决策
     if (b.assistantBrief) parts.push('→ ' + b.assistantBrief)
-    const om = formatOmitted(b.omittedBytes)
+    const om = formatBytesMarker(b.omittedBytes)
     if (om) parts.push(om)
     if (b.branch) parts.push('[旁支]')
     return parts.join(' · ')
@@ -449,7 +441,7 @@ function formatOutlineText(r: OutlineResult): string {
     `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens${
       r.stats.skippedLines > 0 ? ` · ${r.stats.skippedLines} skipped lines` : ''
     }`,
-    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 或调大 budget]` : '',
+    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 的 turns 参数看指定 turn 范围]` : '',
   ]
     .filter(Boolean)
     .join('\n')
@@ -460,7 +452,7 @@ function formatExpandText(turn: string, entries: EntryBrief[]): string {
   const lines = entries.map(
     (e) =>
       `  [${e.index}] ${e.type}${e.role ? '/' + e.role : ''} ${e.brief}${
-        e.omittedBytes > 0 ? ' ' + formatOmitted(e.omittedBytes) : ''
+        e.omittedBytes > 0 ? ' ' + formatBytesMarker(e.omittedBytes) : ''
       }`,
   )
   return `${turn}\n${lines.join('\n')}`
@@ -681,7 +673,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
       tree = await buildExecutionTree(resolved.sessionId, agentDir, resolved.fileName)
     } catch (e) {
       throw err(
-        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兑底。`,
+        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兜底。`,
       )
     }
     return {
@@ -702,7 +694,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
   return { content: [{ type: 'text', text: formatFamilyText(family) }], details: family }
 }
 
-/** outline：turn 级全貌 TOC（design §3.4 outline，~500 token）。 */
+/** outline：turn 级全貌 TOC（design §3.4 outline，~1500 token；render budget 硬编码 2000）。 */
 async function doOutline(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const resolved = await resolveSessionId(params.session, 'outline', agentDir, params.source)
   if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
@@ -1385,8 +1377,9 @@ interface SkippedRun {
  * session 会抛「session not found in family index」）——resolveSessionId 已把 session 解析到
  * 真实文件（kind==='ok' 保证文件存在，三形态：绝对路径/sa-id 均 existsSync 校验，片段匹配
  * 来自实际 fs 扫描），直接用 resolved.fileName 构造单条目 sessionIdToPath 调 resolveWorkflows
- *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 仅含目标 session，call 引用
- * 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，足够 LLM 跳 outline/detail 深读）。
+ *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 传空 Map（单条目链路无其他
+ * 文件可反查），call 引用 100% 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，
+ * 足够 LLM 跳 outline/detail 深读）。
  *
  * 错误契约（C2）：workflow 概览探索语义，三类错误均返回 ToolResult 不抛错。
  * step 的 call sessionId/sessionFile 是 LLM 跳 outline/detail 的入口（m0 resolveSessionId
@@ -1468,7 +1461,7 @@ async function doWorkflow(params: SessionReadParams, agentDir: string): Promise<
   if (requestedRunId !== undefined) details.requestedRunId = requestedRunId
   if (skippedRuns.length > 0) details.skippedRuns = skippedRuns
 
-  // 全部 run 都跳过的兑底提示（ES-wf-snapshot-read-fail 末段）
+  // 全部 run 都跳过的兜底提示（ES-wf-snapshot-read-fail 末段）
   let text: string
   if (runs.length === 0) {
     text =

package/src/tui/hash-provider.ts

@@ -47,8 +47,6 @@ const AGE_NUM_DIGITS = 2
 export interface AutocompleteCandidate {
   /** 显示文本（满宽 label）。`${age} ${预览/name}`，如 "01m 看看 pi-session-reader..." */
   label: string
-  /** 副信息（次列）。本 provider 不设（undefined）——触发 SelectList 满宽 label 分支 */
-  description?: string
   /** 插入编辑器，如 "#019e6c96-aaaa-bbbb-cccc-dddddddddddd"（design D-3：完整 uuid，非名称；不显示给用户看） */
   insertText: string
 }
@@ -203,7 +201,6 @@ export function createHashAutocompleteProvider(
       const items: AutocompleteItem[] = candidates.map((c) => ({
         value: c.insertText,
         label: c.label,
-        description: c.description,
       }))
       // prefix = 光标前匹配到的整段（# 及片段），applyCompletion 据此定位替换区间
       return { items, prefix: `#${fragment}` }

package/src/tui/session-command.ts

@@ -36,7 +36,7 @@ export function createSessionCommand(
   handler(args: string, ctx: ExtensionCommandContext): Promise<void>
 } {
   return {
-    description: 'Pick a session and insert a #uuid-fragment reference into the editor.',
+    description: 'Pick a session and insert a #uuid reference into the editor.',
     async getArgumentCompletions(argumentPrefix) {
       const trimmed = argumentPrefix.trim()
       const all = await SessionManager.listAll(getCwdSessionDir())