@zhushanwen/pi-session-reader 0.3.1 → 0.5.0

package/src/extract.ts

@@ -0,0 +1,422 @@
+/**
+ * extract 预设管线（v2 O4：跨 turn 按类型提取素材）。
+ *
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）。
+ * design §3.3 D3 的 5 个预设 + F8/F9 规格；F7（what 校验）与 doExtract 编排
+ *（resolveSessionId/safeParse/turns 范围限定依赖 tool-handler 私有定位层）留守
+ * tool-handler，经本模块导出的 5 预设函数分发。renderExtractItems 导出面不变：
+ * tool-handler re-export（单测 F9 白盒 import 路径不变）。纯提取，不调 LLM。
+ */
+import { extractToolCalls, formatToolCallSummary, basename } from './core/toolcall.js'
+import type { Turn } from './core/turns.js'
+import { pad } from './handler-utils.js'
+import type { ToolResult } from './tool-handler.js'
+
+/** extract 的 5 个合法 what（design §3.3 D3）。 */
+export type ExtractWhat = 'user-messages' | 'commands' | 'files' | 'commits' | 'tool-results'
+
+/** extract 结果预算（design §3.3 F9）：8000 字节 ≈ 2000 token。 */
+const EXTRACT_BUDGET_BYTES = 8000
+
+/** 含 path 参数的文件类工具（design §3.3 D3 files scope）。 */
+const FILE_TOOLS = new Set(['read', 'edit', 'write', 'head'])
+
+/** git 命令关键词（commits 预设判定 bash 结果是否来自 git 命令）。 */
+const GIT_CMD_RE = /\bgit\s+(log|show|commit|push|merge|cherry-pick|revert|reset|rebase|diff)\b/
+/** git short hash（commits 预设，保守限定 7-8 位避免 uuid 全量误报）。 */
+const SHORT_HASH_RE = /\b[0-9a-f]{7,8}\b/g
+/** commit 上下文消歧关键词（commits 次路径：hash 附近出现才纳入）。 */
+const COMMIT_CTX_RE = /feat:|fix:|refactor:|chore:|docs:|\b(commit|commits|merged|pushed|merge)\b/i
+
+/**
+ * 从 message.content 提取纯 text（string 直取；数组拼接 text 块）。
+ *
+ * 与 render.ts 内部 extractText 同语义，但那未导出；extract 仅需纯 text
+ *（user-messages / tool-results 的正文），不要 thinking/toolCall 占位，本地实现。
+ * content 是 unknown 做类型守卫。
+ */
+function extractContentText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const b of content) {
+      if (b !== null && typeof b === 'object') {
+        const o = b as Record<string, unknown>
+        if (o.type === 'text' && typeof o.text === 'string') parts.push(o.text)
+      }
+    }
+    return parts.join('\n')
+  }
+  return ''
+}
+
+/** 截断到 max 字符，超出加省略号（防爆；tool-results 正文用）。 */
+function truncateText(s: string, max: number): string {
+  return s.length <= max ? s : s.slice(0, max) + '…'
+}
+
+/** turnsLabel 展示的 turn 数上限（超出折叠为 +N）。 */
+const TURNS_LABEL_HEAD_COUNT = 5
+
+/** turns 数组紧凑标签（前 5 个 + +N，避免一行过长撑爆预算）。 */
+function turnsLabel(turns: number[]): string {
+  const head = turns.slice(0, TURNS_LABEL_HEAD_COUNT).map((n) => `T${pad(n)}`)
+  const suffix = turns.length > TURNS_LABEL_HEAD_COUNT ? `+${turns.length - TURNS_LABEL_HEAD_COUNT}` : ''
+  return head.join(',') + suffix
+}
+
+/**
+ * 计算工具分布（按出现次数降序），用于 F8 提示 + details.toolDistribution。
+ * 遍历 assistant entry 的 toolCall，复用 extractToolCalls。
+ */
+function computeToolDistribution(
+  turns: Turn[],
+): Array<{ name: string; count: number }> {
+  const counts = new Map<string, number>()
+  for (const t of turns) {
+    for (const e of t.entries) {
+      if (e.message?.role !== 'assistant') continue
+      for (const tc of extractToolCalls(e)) {
+        counts.set(tc.name, (counts.get(tc.name) ?? 0) + 1)
+      }
+    }
+  }
+  return Array.from(counts.entries())
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count)
+}
+
+/** F8 提示展示的工具分布条数上限。 */
+const TOOL_DISTRIBUTION_LIMIT = 10
+
+/** F8：commands/tool-results 的 tool 过滤零匹配 → 返回工具分布 + 👉（不抛错，design §3.3 F8）。 */
+function f8ToolNoMatch(what: ExtractWhat, tool: string, turns: Turn[]): ToolResult {
+  const dist = computeToolDistribution(turns).slice(0, TOOL_DISTRIBUTION_LIMIT)
+  const distStr = dist.map((d) => `${d.name}×${d.count}`).join(', ')
+  const text = `what=${what} tool="${tool}" 无匹配。该 session 工具：${distStr}。👉 用存在的工具名重试。`
+  return { content: [{ type: 'text', text }], details: { what, tool, toolDistribution: dist } }
+}
+
+/**
+ * 通用预算渲染：逐项累加字节，超 EXTRACT_BUDGET_BYTES 截断（design §3.3 F9）。
+ *
+ * details.items 放实际展示的子集（截断后），count 放全集长度，测试可断言 shown/count/truncated。
+ * emptyHint 仅 items 为空时用（files/commits 无匹配不报错，返空 + 提示）。
+ *
+ * 预算控制：按 item 累计字节达预算即截断。**首项超大也内部截断**（对单行 slice 到剩余字节预算，
+ * 字节→字符 ×3 近似防 UTF8 多字节被切半），保证 body 不超预算——而非放行首项致 body 远超预算。
+ * 导出供 tool-handler.test 单测 F9 截断逻辑（首项截断 + 文案含 turn 范围 + 实际 token）。
+ *
+ * getTurns：从 item 提取 turn 列表（files 是 turns 数组，其余单值包数组），供 F9 文案报 turn 范围。
+ */
+
+/** UTF8 单字符最大字节数（预算字节→字符的保守换算基数，防多字节字符被切半）。 */
+const UTF8_MAX_BYTES_PER_CHAR = 3
+/** token 估算换算基数（bytes/4 口径，与 render 层 chars/4 同近似）。 */
+const CHARS_PER_TOKEN = 4
+
+export function renderExtractItems<I>(
+  what: ExtractWhat,
+  items: I[],
+  renderLine: (item: I) => string,
+  getTurns: (item: I) => number[],
+  emptyHint?: string,
+): ToolResult {
+  if (items.length === 0) {
+    const text = emptyHint ?? `what=${what} 无匹配。`
+    return {
+      content: [{ type: 'text', text }],
+      details: { what, count: 0, shown: 0, truncated: false, items: [] },
+    }
+  }
+  const shown: I[] = []
+  const shownLines: string[] = []
+  let bytes = 0
+  let cut = false
+  for (const item of items) {
+    const line = renderLine(item)
+    const lineBytes = Buffer.byteLength(line, 'utf8') + 1 // +\n
+    if (bytes + lineBytes > EXTRACT_BUDGET_BYTES) {
+      // 超预算：对当前 line 内部截断到剩余预算（首项超大也截断，但保留截断后的内容）
+      const remainingBytes = EXTRACT_BUDGET_BYTES - bytes
+      const charBudget = Math.floor(remainingBytes / UTF8_MAX_BYTES_PER_CHAR) // 字节→字符 ×3 近似防 UTF8 切半
+      if (charBudget > 0) {
+        const sliced = line.slice(0, charBudget) + '…'
+        shown.push(item)
+        shownLines.push(sliced)
+      }
+      cut = true
+      break
+    }
+    shown.push(item)
+    shownLines.push(line)
+    bytes += lineBytes
+  }
+  const body = shownLines.join('\n')
+  if (!cut) {
+    return {
+      content: [{ type: 'text', text: body }],
+      details: {
+        what,
+        count: items.length,
+        shown: shown.length,
+        truncated: false,
+        items: shown,
+      },
+    }
+  }
+  // F9：超预算截断。tokens 反映 body 实际体积（非固定 2000）；文案报 shown/count + turn 范围 + 实际 token
+  const shownTurns = shown.flatMap(getTurns)
+  const turnRange =
+    shownTurns.length > 0
+      ? `（T${pad(Math.min(...shownTurns))}-T${pad(Math.max(...shownTurns))}）`
+      : ''
+  const actualTokens = Math.round(Buffer.byteLength(body, 'utf8') / CHARS_PER_TOKEN)
+  const text =
+    body +
+    `\n[what=${what} 已显示 ${shown.length}/${items.length} 项${turnRange}，约 ${actualTokens} token 达预算上限。👉 用较小 turns 范围（如 T000-T005）缩小，或换 what 重试。]`
+  return {
+    content: [{ type: 'text', text }],
+    details: {
+      what,
+      count: items.length,
+      shown: shown.length,
+      truncated: true,
+      items: shown,
+    },
+  }
+}
+
+/** 预设 1：user-messages——收集 role==='user' 的全文（按 turn 排列，design §3.3 D3）。 */
+export function extractUserMessages(turns: Turn[]): ToolResult {
+  const items: Array<{ turn: number; text: string }> = []
+  for (const t of turns) {
+    for (const e of t.entries) {
+      if (e.message?.role !== 'user') continue
+      items.push({ turn: t.index, text: extractContentText(e.message.content) })
+    }
+  }
+  return renderExtractItems(
+    'user-messages',
+    items,
+    (it) => `T${pad(it.turn)}: ${it.text}`,
+    (it) => [it.turn],
+  )
+}
+
+/**
+ * 预设 2：commands——assistant 的 toolCall，带 name + D1 摘要（design §3.3 D3）。
+ * 可选 tool 过滤；过滤后零匹配 → F8（工具分布 + 👉，不抛错）。
+ * index = entry 在 turn.entries 内的位置，与 expand 的 [N] 对齐便于定位。
+ */
+export function extractCommands(turns: Turn[], tool: string | undefined): ToolResult {
+  const items: Array<{ turn: number; index: number; name: string; summary: string }> = []
+  for (const t of turns) {
+    for (let ei = 0; ei < t.entries.length; ei++) {
+      const e = t.entries[ei]
+      if (e.message?.role !== 'assistant') continue
+      for (const tc of extractToolCalls(e)) {
+        if (tool !== undefined && tc.name !== tool) continue
+        items.push({
+          turn: t.index,
+          index: ei,
+          name: tc.name,
+          summary: formatToolCallSummary(tc),
+        })
+      }
+    }
+  }
+  if (tool !== undefined && items.length === 0) return f8ToolNoMatch('commands', tool, turns)
+  return renderExtractItems(
+    'commands',
+    items,
+    (it) => `T${pad(it.turn)} #${it.index} ${it.summary}`,
+    (it) => [it.turn],
+  )
+}
+
+/**
+ * 预设 3：files——read/edit/write/head 的 path 去重（design §3.3 D3）。
+ * 同 path 多次操作合并，op 聚合成 `read+edit` 形式，turns 记录出现过的轮次。
+ * todo/subagent/cw 无 path 不纳入。无匹配不报错（返空 + 提示）。
+ */
+export function extractFiles(turns: Turn[]): ToolResult {
+  const map = new Map<string, { ops: Set<string>; turns: Set<number> }>()
+  for (const t of turns) {
+    for (const e of t.entries) {
+      if (e.message?.role !== 'assistant') continue
+      for (const tc of extractToolCalls(e)) {
+        if (!FILE_TOOLS.has(tc.name)) continue
+        const p = tc.arguments.path
+        if (typeof p !== 'string') continue
+        let rec = map.get(p)
+        if (rec === undefined) {
+          rec = { ops: new Set(), turns: new Set() }
+          map.set(p, rec)
+        }
+        rec.ops.add(tc.name)
+        rec.turns.add(t.index)
+      }
+    }
+  }
+  const items = Array.from(map.entries()).map(([path, rec]) => ({
+    path,
+    basename: basename(path),
+    op: Array.from(rec.ops).sort().join('+'),
+    turns: Array.from(rec.turns).sort((a, b) => a - b),
+  }))
+  return renderExtractItems(
+    'files',
+    items,
+    (it) => `${it.op}: ${it.path} (${turnsLabel(it.turns)})`,
+    (it) => it.turns,
+    `what=files 无匹配（该 session 无 read/edit/write/head 文件操作）。`,
+  )
+}
+
+/**
+ * 预设 4：commits——git 命令 toolResult 的 hash（design §3.3 D3 + D6 误匹配处理）。
+ *
+ * 保守策略（宁可少召回不要乱报 uuid）：
+ * ① 主路径（高置信）：只从 bash 且关联 command 含 git (log|show|commit|push|merge|...) 的
+ *    toolResult 文本提取 7-8 位 hex；
+ * ② 次路径（中置信）：扫所有 toolResult 文本，hash 前后各 30 字符内含
+ *    feat:/fix:/commit/merge 等关键词的才纳入；
+ * ③ 去重，git-cmd 置信度优先；不扫 user/assistant 自由文本（uuid/session-id 误报太多）。
+ *
+ * 已知局限：7-8 位 hex 与 uuid v7 片段形似，靠 git 命令上下文过滤；仍可能漏报
+ *（git 操作未被 toolResult 捕获）或误报（git log 输出里的其他 hex）。每条标注来源 turn
+ * + source + context，agent 可快速辨认。完全语义判断需 LLM，本工具零 LLM 依赖。
+ */
+/** commits 提取的 hash 前后上下文字符数（次路径关键词判定窗口）。 */
+const COMMIT_CONTEXT_CHARS = 30
+
+/** commits 预设的单条提取结果（hash + 来源 turn + 置信来源 + 上下文片段）。 */
+interface CommitItem {
+  hash: string
+  turn: number
+  source: 'git-cmd' | 'commit-context'
+  context: string
+}
+
+/** 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）。 */
+function collectBashCommands(turns: Turn[]): Map<string, string> {
+  const bashCmds = new Map<string, string>()
+  for (const t of turns) {
+    for (const e of t.entries) {
+      if (e.message?.role !== 'assistant') continue
+      for (const tc of extractToolCalls(e)) {
+        if (tc.name === 'bash') {
+          const cmd = tc.arguments.command
+          if (typeof cmd === 'string') bashCmds.set(tc.id, cmd)
+        }
+      }
+    }
+  }
+  return bashCmds
+}
+
+/** 单条 toolResult 文本的 hash 提取：git-cmd 全收（高置信），否则按上下文关键词过滤（次路径）。 */
+function matchCommitsInResult(
+  text: string,
+  turnIndex: number,
+  isGitBash: boolean,
+  high: CommitItem[],
+  low: CommitItem[],
+): void {
+  for (const m of text.matchAll(SHORT_HASH_RE)) {
+    const hash = m[0]
+    const idx = m.index ?? 0
+    const ctx = text
+      .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
+      .replace(/\s+/g, ' ')
+      .trim()
+    if (isGitBash) {
+      high.push({ hash, turn: turnIndex, source: 'git-cmd', context: ctx })
+    } else if (COMMIT_CTX_RE.test(ctx)) {
+      low.push({ hash, turn: turnIndex, source: 'commit-context', context: ctx })
+    }
+  }
+}
+
+/** 主扫描阶段：遍历 toolResult entry，分类收集高/低置信 commit 候选。 */
+function collectCommitCandidates(
+  turns: Turn[],
+  bashCmds: Map<string, string>,
+): { high: CommitItem[]; low: CommitItem[] } {
+  const high: CommitItem[] = []
+  const low: CommitItem[] = []
+  for (const t of turns) {
+    for (const e of t.entries) {
+      if (e.message?.role !== 'toolResult') continue
+      const msg = e.message
+      const text = extractContentText(msg.content)
+      if (text === '') continue
+      const cmd = msg.toolCallId !== undefined ? bashCmds.get(msg.toolCallId) : undefined
+      const isGitBash = msg.toolName === 'bash' && cmd !== undefined && GIT_CMD_RE.test(cmd)
+      matchCommitsInResult(text, t.index, isGitBash, high, low)
+    }
+  }
+  return { high, low }
+}
+
+/** 收口阶段：去重，高置信优先，同 hash 保留首次。 */
+function dedupeCommits(high: CommitItem[], low: CommitItem[]): CommitItem[] {
+  const seen = new Set<string>()
+  const items: CommitItem[] = []
+  for (const c of high) {
+    if (seen.has(c.hash)) continue
+    seen.add(c.hash)
+    items.push(c)
+  }
+  for (const c of low) {
+    if (seen.has(c.hash)) continue
+    seen.add(c.hash)
+    items.push(c)
+  }
+  return items
+}
+
+export function extractCommits(turns: Turn[]): ToolResult {
+  // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
+  const bashCmds = collectBashCommands(turns)
+  const { high, low } = collectCommitCandidates(turns, bashCmds)
+  const items = dedupeCommits(high, low)
+
+  return renderExtractItems(
+    'commits',
+    items,
+    (it) => `T${pad(it.turn)} ${it.hash} [${it.source}] ${it.context}`,
+    (it) => [it.turn],
+    `what=commits 无匹配（该 session 无 git commit hash，或未在 toolResult 中出现）。`,
+  )
+}
+
+/** tool-results 正文截断上限（防爆）。 */
+const TOOL_RESULT_TEXT_MAX_CHARS = 500
+
+/**
+ * 预设 5：tool-results——role==='toolResult' 文本（design §3.3 D3）。
+ * text 截断到 500 字防爆；可选 tool 过滤（msg.toolName）；过滤零匹配 → F8。
+ */
+export function extractToolResults(turns: Turn[], tool: string | undefined): ToolResult {
+  const items: Array<{ turn: number; index: number; toolName: string; text: string }> = []
+  for (const t of turns) {
+    for (let ei = 0; ei < t.entries.length; ei++) {
+      const e = t.entries[ei]
+      if (e.message?.role !== 'toolResult') continue
+      const tn = e.message.toolName ?? '?'
+      if (tool !== undefined && tn !== tool) continue
+      const text = truncateText(extractContentText(e.message.content), TOOL_RESULT_TEXT_MAX_CHARS)
+      items.push({ turn: t.index, index: ei, toolName: tn, text })
+    }
+  }
+  if (tool !== undefined && items.length === 0)
+    return f8ToolNoMatch('tool-results', tool, turns)
+  return renderExtractItems(
+    'tool-results',
+    items,
+    (it) => `T${pad(it.turn)} #${it.index} ${it.toolName}: ${it.text}`,
+    (it) => [it.turn],
+  )
+}

package/src/handler-utils.ts

@@ -0,0 +1,63 @@
+/**
+ * tool-handler 共享小工具（max-lines 拆分轮机械提取，零行为变更）。
+ *
+ * 从 tool-handler.ts「小工具」与「turn/turns 索引解析」段搬出：pad/err/turn 索引解析
+ * 被留守的 tool-handler 与拆出的 search-across.ts / extract.ts 共同消费——放独立低层
+ * 模块保持单向依赖（handler-utils ← 各域模块 ← tool-handler），不引入循环 import
+ *（result-action.ts 的 Deps 注入先例解决不了纯函数跨模块复用，低层模块更直接）。
+ * stripHash/formatDate/shortCwd/requireStr 仅 tool-handler 留守部分使用，不在此列。
+ */
+
+/** turn 索引显示宽度（T013 三位补零）。 */
+const TURN_INDEX_WIDTH = 3
+
+export const pad = (n: number): string => String(n).padStart(TURN_INDEX_WIDTH, '0')
+
+/** 构造带 👉 恢复指引的 Error。契约：handler 直接 throw，execute 不 catch、原样传播给 pi；
+ * pi 外层（pi-agent-core agent-loop.js executePreparedToolCall catch，:466-471）统一转
+ * isError:true 的 error tool result——返回值上的 isError 字段会被丢弃（错误被标成功）。 */
+export function err(message: string): Error {
+  return new Error(message)
+}
+
+// ---------------------------------------------------------------------------
+// turn / turns 索引解析
+// ---------------------------------------------------------------------------
+
+const TURN_RE = /^T?(\d+)$/i
+
+export function parseTurnIndex(raw: string): number {
+  const m = raw.trim().match(TURN_RE)
+  if (!m) {
+    throw err(
+      `turn "${raw}" 格式无效（应为 T013 或 013）。👉 用合法 turn 索引重试，或 outline 重看有效范围。`,
+    )
+  }
+  return parseInt(m[1], 10)
+}
+
+/** turns 范围 "T013-T015" 的段数。 */
+const TURNS_RANGE_PARTS = 2
+
+export function parseTurnsRange(raw: string): { start: number; end: number } {
+  const parts = raw.split('-').map((s) => s.trim())
+  if (parts.length === 1) {
+    const i = parseTurnIndex(parts[0])
+    return { start: i, end: i }
+  }
+  if (parts.length === TURNS_RANGE_PARTS) {
+    const start = parseTurnIndex(parts[0])
+    const end = parseTurnIndex(parts[1])
+    if (end < start) {
+      throw err(
+        `turns 范围 "${raw}" 起始大于结束。👉 检查范围格式（如 T013-T015）重试。`,
+      )
+    }
+    return { start, end }
+  }
+  throw err(`turns "${raw}" 格式无效（应为 T013 或 T013-T015）。👉 用合法范围重试。`)
+}
+
+export function rangeLabel(r: { start: number; end: number }): string {
+  return r.start === r.end ? `T${pad(r.start)}` : `T${pad(r.start)}-T${pad(r.end)}`
+}

package/src/index.ts

@@ -1,8 +1,9 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-import { getAgentDir } 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 { handleSessionRead, type SessionReadParams } from './tool-handler.js'
+import type { SessionMetadataProvider } from './discovery/find.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'
 
@@ -21,16 +22,28 @@ import { createSessionCommand } from './tui/session-command.js'
 
 const SessionReadSchema = Type.Object({
   action: StringEnum(
-    ['find', 'family', 'outline', 'expand', 'detail', 'search', 'export', 'extract', 'workflow'],
+    [
+      'find',
+      'family',
+      'outline',
+      'expand',
+      'detail',
+      'search',
+      'export',
+      'extract',
+      'workflow',
+      'result',
+      'doctor',
+    ],
     {
       description:
-        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail).',
+        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep, single session or cross-session over a comma-separated id list), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail), result (fetch a subagent session final result text — same content as its completion notice; session = single id or comma-separated batch of at most 10, optional limit caps chars per item), doctor (show detected host environment and session-root diagnostics).',
     },
   ),
   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/extract/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/result. result also accepts a comma-separated list of up to 10 ids. search also accepts a comma-separated list of up to 10 full ids (from find output) for cross-session search. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -91,7 +104,14 @@ const SessionReadSchema = Type.Object({
     }),
   ),
   limit: Type.Optional(
-    Type.Number({ description: 'find/search: max results. Default 20.' }),
+    Type.Number({
+      // minimum:1 在 schema 校验层拒绝 limit:0 等退化输入（不落入 find F1 的
+      // 「无匹配 session」措辞面）；result 消费侧的 resolveResultLimit 防御保留
+      //（可单测绕过 schema 的调用形态）。
+      minimum: 1,
+      description:
+        'find/search: max results. Default 20. result: max chars per item, default 8000 (overlong text truncated with a pointer to the full file).',
+    }),
   ),
   what: Type.Optional(
     StringEnum(
@@ -118,6 +138,12 @@ const SessionReadSchema = Type.Object({
         'family action: return nested execution tree (arbitrary-depth subagent↔workflow-call nesting, precise parentRecordId chain with flat-fallback for legacy records). Default false (flat family).',
     }),
   ),
+  includeSubagents: Type.Optional(
+    Type.Boolean({
+      description:
+        'doctor action: also scan the subagent session root (adds its file count). Default false (path and existence only).',
+    }),
+  ),
 })
 
 // ---- guidelines（注入 LLM，design §3.4）----
@@ -129,12 +155,14 @@ const guidelines = [
   '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).',
   "workflow action to see workflow run overviews (status/budget/steps). Each step's call sessionId can jump to outline/detail for deep reading.",
+  "result action to fetch a subagent's final result text (same content as its completion notice): session takes a single sa-id/uuid/path or a comma-separated batch of at most 10; optional limit caps chars per item (default 8000, truncated items carry a pointer to the full file).",
   'Errors carry a 👉 recovery hint—follow it to retry in one step.',
+  'Unsure about the host environment (pure pi vs xyz-agent) or where session roots live? Run action:"doctor" first—it prints the detected environment and every candidate session root.',
 ]
 
 // ---- 工具 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, ~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).`
+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. Eleven 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, or cross-session over a comma-separated id list ≤10 from find output), 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), result (fetch a subagent session final result text, same content as its completion notice; single id or comma-separated batch ≤10, optional limit chars per item default 8000), doctor (show detected host environment and session-root diagnostics). 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 实例集合。
@@ -153,6 +181,13 @@ const registeredPis = new WeakSet<ExtensionAPI>()
 let currentCwdSessionDir: string | null = null
 
 export default function sessionReaderExtension(pi: ExtensionAPI): void {
+  // u11（design 2026-09-10 §6.6）：标题元数据走 pi 的 SessionManager.listAll(dir)——
+  // session_info name 提取、首消息采集与并发解析由 pi 维护。注入范式同 §6.2 信号包：
+  // pi 类型只在本层出现（SessionInfo 对发现层 SessionMetadataEntry 结构兼容，直接透传），
+  // 发现层只见注入函数，零 pi 依赖。调用成本由三条调用策略约束（惰性/窄化/缓存，
+  // 缓存在 tool-handler 注入边界包装），listAll 实装语义「扫一层平铺目录 + 每文件
+  // 全量解析」决定了不得对含子目录根调用（hash-provider.ts:158 空参灾难同源教训）。
+  const metadataProvider: SessionMetadataProvider = async (dir) => SessionManager.listAll(dir)
   pi.registerTool({
     name: 'session_read',
     label: 'Session Reader',
@@ -164,14 +199,33 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
       params: SessionReadParams,
       signal: AbortSignal | undefined,
       _onUpdate: unknown,
-      _ctx: ExtensionContext,
+      ctx: ExtensionContext | undefined,
     ) {
       // 错误路径直接 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)
+      // 信号包采集（design §7B）：可选链逐层降级——ctx===undefined（存量单测五参形态）、
+      // sessionManager 缺字段、getSessionDir 方法缺失，任一层不成立即 liveSessionDir=undefined
+      //（发现层走 [default]+[legacy]+[subagent] 三根降级）；方法调用抛错可选链兜不住，try/catch
+      // 同样降级——宿主异常不得变成工具内部 TypeError。env/bundleUrl 由 u8 补采（doctor
+      // 环境判定/发行形态需要，design §6.2/§6.4）。
+      let liveSessionDir: string | undefined
+      try {
+        liveSessionDir = ctx?.sessionManager?.getSessionDir?.()
+      } catch {
+        liveSessionDir = undefined
+      }
+      const signals: SessionReadSignals = {
+        agentDir: getAgentDir(),
+        liveSessionDir,
+        env: process.env,
+        bundleUrl: import.meta.url,
+      }
+      // u11：标题元数据 provider 随信号包注入（provider 抛错由发现层单目录降级，
+      // 不会变成工具错误——宿主 listAll 异常不得打断 find 的「能找到 session」底线）。
+      return handleSessionRead(params, signals, signal, metadataProvider)
     },
   })