@zhushanwen/pi-session-reader 0.2.1 → 0.2.3

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "index.ts",
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -13,6 +16,7 @@
     "pi-package"
   ],
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "files": [
@@ -21,9 +25,9 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/src/__tests__/index.test.ts

@@ -6,7 +6,8 @@ import { Check } from 'typebox/value'
  * M3 pi 边界层（src/index.ts）单测（MF-6：此前该层零测试）。
  *
  * mock pi/ctx（as unknown as ExtensionAPI），测：
- * 1. execute catch → isError:true 文本返回（「execute 不向 pi 抛」契约守护）
+ * 1. execute 错误路径 throw（W4：pi 只对 execute throw 置 isError:true——agent-loop
+ *    丢弃返回值里的 isError 字段，「错误轮被标成功」契约守护）
  * 2. session_start handler 的 ctx.mode!=='tui' 守卫
  * 3. registeredPis WeakSet 去重：同 pi 二次 session_start 不重复注册；不同 pi 可注册
  * 4. typeof ctx.ui.addAutocompleteProvider 运行时守卫（ui 缺方法 → 跳过，不崩）
@@ -78,7 +79,7 @@ describe('sessionReaderExtension - execute 契约', () => {
     sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
   })
 
-  it('handler 抛错 → execute 返回 isError:true + 👉 文本，不向 pi 抛', async () => {
+  it('handler 抛错 → execute 向 pi throw（W4：throw 才置 isError:true，返回值 isError 被 agent-loop 丢弃）', async () => {
     const toolDef = fake.registerTool.mock.calls[0][0] as {
       name: string
       execute: (
@@ -87,18 +88,14 @@ describe('sessionReaderExtension - execute 契约', () => {
         signal: AbortSignal | undefined,
         onUpdate: unknown,
         ctx: unknown,
-      ) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>
+      ) => Promise<{ content: Array<{ type: string; text: string }> }>
     }
     expect(toolDef.name).toBe('session_read')
-    // action=find 缺 query → F5 requireStr 抛错 → execute catch 转换
-    const result = await toolDef.execute('tc-1', { action: 'find' }, undefined, undefined, undefined)
-    expect(result.isError).toBe(true)
-    expect(result.content[0].type).toBe('text')
-    expect(result.content[0].text).toContain('👉')
-    // 非 Error 抛错（string）也能转文本
-    const result2 = await toolDef.execute('tc-2', { action: 123 }, undefined, undefined, undefined)
-    expect(result2.isError).toBe(true)
-    expect(typeof result2.content[0].text).toBe('string')
+    // action=find 缺 query → F5 requireStr 抛错 → execute 原样传播（pi catch 后
+    // isError:true + message 成为 toolResult content[0].text）
+    await expect(
+      toolDef.execute('tc-1', { action: 'find' }, undefined, undefined, undefined),
+    ).rejects.toThrow(/👉/)
   })
 })
 

package/src/__tests__/parser.test.ts

@@ -117,18 +117,22 @@ describe('parseSessionContent', () => {
     expect(result.lastLinePartial).toBe(true)
   })
 
-  it('custom entry 无顶层 id 时 fallback 到 data.id（pi subagent-identity 等格式）', () => {
-    const content = line({
-      type: 'custom',
-      customType: 'subagent-identity',
-      data: { id: 'sa-abc123', rootSessionId: 'sess-1', slug: 'fix' },
-    })
+  it('custom entry 无顶层 id → 坏行跳过（W4：data.id fallback 死分支已删，pi appendCustomEntry 恒写顶层 id）', () => {
+    // pi appendCustomEntry 恒写顶层 id（session-manager.js:820-828）；data.id 是扩展
+    // 业务字段而非 entry id。无顶层 id 的行按坏行跳过（skippedLines++）。
+    const content = [
+      line({ type: 'custom', customType: 'ok-entry', id: 'top-level-id', data: {} }),
+      line({
+        type: 'custom',
+        customType: 'subagent-identity',
+        data: { id: 'sa-abc123', rootSessionId: 'sess-1', slug: 'fix' },
+      }),
+    ].join('\n')
     const result = parseSessionContent(content)
 
     expect(result.entries).toHaveLength(1)
-    expect(result.entries[0].id).toBe('sa-abc123')
-    expect(result.entries[0].customType).toBe('subagent-identity')
-    expect(result.skippedLines).toBe(0)
+    expect(result.entries[0].id).toBe('top-level-id')
+    expect(result.skippedLines).toBe(1)
   })
 
   it('session header 无 parentId → 归一化为 null（root 判定）', () => {

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

@@ -372,6 +372,48 @@ describe('F2 多匹配消歧（fixture，MF-9）', () => {
   })
 })
 
+describe('outline skippedLines 报告（fixture，D8d 有检测必有报告）', () => {
+  let dir: string
+  const SID = '019e6c96-bbbb-cccc-dddd-00000000000b'
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tool-handler-skipped-'))
+  })
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('坏行计入 stats.skippedLines 且文本尾部可见（不静默跳过）', async () => {
+    // 中间注入 1 行坏 JSON（半截对象）：parser 计 skippedLines=1，outline 必须报告
+    const slug = '--demo-cwd--'
+    await mkdir(join(dir, 'sessions', slug), { recursive: true })
+    const lines = [
+      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
+      JSON.stringify({
+        type: 'message',
+        id: SID + '-m1',
+        parentId: SID,
+        message: { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      }),
+      '{"broken json line',
+    ]
+    await writeFile(join(dir, 'sessions', slug, SID + '.jsonl'), lines.join('\n') + '\n')
+
+    const r = await handleSessionRead({ action: 'outline', session: SID }, dir)
+    const d = r.details as { stats: { skippedLines: number } }
+    expect(d.stats.skippedLines).toBe(1)
+    expect(r.content[0].text).toContain('1 skipped lines')
+  })
+
+  it('无坏行时不输出 skipped 片段（正常 session 零噪音）', async () => {
+    await makeFixtureSession(dir, SID, 'clean session')
+    const r = await handleSessionRead({ action: 'outline', session: SID }, dir)
+    const d = r.details as { stats: { skippedLines: number } }
+    expect(d.stats.skippedLines).toBe(0)
+    expect(r.content[0].text).not.toContain('skipped lines')
+  })
+})
+
 describe('search 灾难性正则降级 + abort（fixture，MF-5 回归）', () => {
   let dir: string
   const SID = '019e6c96-bbbb-cccc-dddd-00000000000a'

package/src/core/parser.ts

@@ -60,15 +60,11 @@ function toEntry(raw: unknown): Entry | undefined {
   const obj = raw as Record<string, unknown>
   if (typeof obj.type !== 'string') return undefined
 
-  // id 解析：顶层 id 优先；custom entry 无顶层 id 时 fallback 到 data.id
-  //（pi 的 subagent-identity 等 custom entry 把 id 放在 data.id，非顶层——真实样本确认）
-  let id: unknown = obj.id
-  if (typeof id !== 'string' && obj.type === 'custom') {
-    const data = obj.data
-    if (typeof data === 'object' && data !== null && typeof (data as Record<string, unknown>).id === 'string') {
-      id = (data as Record<string, unknown>).id
-    }
-  }
+  // id 解析：pi appendCustomEntry 恒写顶层 id（session-manager.js:820-828）——
+  // 无需 fallback。data.id 是扩展业务字段（如 subagent-identity payload），不是 entry id。
+  // [W4 删除] 原 data.id fallback 分支对 pi 写出的 entry 是死分支（对历史/异构文件
+  // 也无必要——entry id 语义以顶层为准）。
+  const id: unknown = obj.id
   if (typeof id !== 'string') return undefined
 
   const entry: Entry = {

package/src/core/render.ts

@@ -26,7 +26,8 @@ export interface TurnBrief {
 
 export interface OutlineResult {
   turns: TurnBrief[]
-  stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number }
+  /** skippedLines：JSON 解析失败/缺结构字段的行数（parser 检测，工具层覆盖精确值；render 层无 ParseResult 恒 0） */
+  stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number; skippedLines: number }
   /** chars / 4 近似（与 design P-outline 口径一致） */
   tokenEstimate: number
   /** 被总预算截断的 turn 数（从尾部丢弃） */
@@ -319,6 +320,7 @@ export function renderOutline(
     totalEntries: totalEntriesAll,
     totalBytes: parsedBytes,
     parsedBytes,
+    skippedLines: 0,
   }
 
   if (turns.length === 0) {

package/src/index.ts

@@ -12,7 +12,9 @@ import { createSessionCommand } from './tui/session-command.js'
  * 分层（同 scheduler/cw-tool）：
  * - tool-handler.ts：纯逻辑 handler，agentDir 注入，零 pi 依赖，可单测
  * - index.ts（本文件）：pi 依赖层，registerTool + getAgentDir() 调用 + execute 闭包
- *   （catch handler 抛的 Error 转 isError:true，execute 不向 pi 抛——pi 工具契约）
+ *   （错误直接 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' 时）。
  */
@@ -164,17 +166,12 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
       _onUpdate: unknown,
       _ctx: ExtensionContext,
     ) {
-      try {
-        // signal 仅 search 消费（MF-5：长扫描可中断，Esc 不再挂死）；其余 action 有界不接
-        return await handleSessionRead(params, getAgentDir(), signal)
-      } catch (e) {
-        const msg = e instanceof Error ? e.message : String(e)
-        return {
-          content: [{ type: 'text' as const, text: msg }],
-          details: {},
-          isError: true,
-        }
-      }
+      // 错误路径直接 throw：pi 契约只有 throw 才置 isError:true（tool_execution_end /
+      // ToolResultMessage），handler 抛的 Error 文案（含 👉 恢复提示）原样成为
+      // toolResult content，模型仍可读到。曾用 return {isError:true}——被 agent-loop
+      // 丢弃，错误轮被标成功（W4 修复）。
+      // signal 仅 search 消费（MF-5：长扫描可中断，Esc 不再挂死）；其余 action 有界不接
+      return handleSessionRead(params, getAgentDir(), signal)
     },
   })
 

package/src/tool-handler.ts

@@ -7,8 +7,9 @@
  * 按 action 分发到 8 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
- * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），由 index.ts 的 execute
- * 闭包 catch 转 isError:true 文本返回——handler 可抛（纯逻辑可测），execute 不抛（pi 契约）。
+ * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
+ * 原样传播给 pi——pi-agent-core 只对 execute throw 置 isError:true（返回值里的 isError
+ * 字段被丢弃，agent-loop.js:453-483）。handler 可抛（纯逻辑可测）。
  * 例外：F2 多匹配与 F1 find 零匹配「不视为错误」，返回消歧/提示结果而非抛错。
  */
 import { existsSync, openSync, readSync, closeSync } from 'node:fs'
@@ -425,7 +426,9 @@ function formatOutlineText(r: OutlineResult): string {
   })
   const tail = [
     '',
-    `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens`,
+    `${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]` : '',
   ]
     .filter(Boolean)
@@ -677,7 +680,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
 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)
-  const { entries, totalBytes } = await safeParse(resolved.fileName)
+  const { entries, totalBytes, skippedLines } = await safeParse(resolved.fileName)
   const tree = buildTreeView(entries)
   const turns = segmentTurns(entries, new Set(tree.leafPath))
   const opts: OutlineOptions = {
@@ -689,6 +692,9 @@ async function doOutline(params: SessionReadParams, agentDir: string): Promise<T
   // 覆盖 stats.totalBytes：render 用 parsedBytes（leaf entry JSON 字节和）近似，
   // 此处用 ParseResult.totalBytes（原始文件字节数，design §3.4 stats.totalBytes 语义）
   result.stats.totalBytes = totalBytes
+  // [D8d] skippedLines 同模式覆盖：parser 已检测坏行计数（render 签名不含 ParseResult 恒 0），
+  // 有检测必有报告——静默跳过行对调用方不可见 = 数据完整性缺口
+  result.stats.skippedLines = skippedLines
   return { content: [{ type: 'text', text: formatOutlineText(result) }], details: result }
 }