@zhushanwen/pi-session-reader 0.3.1 → 0.4.0

package/src/result-action.ts

@@ -0,0 +1,244 @@
+/**
+ * result action（subagent-sync-collect U6：design subagent-sync-collect.md §3.1.3）。
+ *
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮）：纯移动零行为变更。tool-handler 的
+ * 定位/解析 helper（err/stripHash/requireStr/resolveSessionId/disambiguate/safeParse）
+ * 为文件私有且被其余 9 个 action 共用，不便搬移——经 {@link ResultActionDeps} 注入，
+ * tool-handler.ts 构造 RESULT_ACTION_DEPS 常量传入（构造期绑定，运行时零查找开销）。
+ *
+ * 设计来源：docs/design/subagent-sync-collect.md §3.1.3 ——
+ *   session_read {"action":"result","session":"sa-aaa"}              // 单个
+ *   session_read {"action":"result","session":"sa-aaa,sa-bbb,sa-ccc"} // 批量（≤10）
+ *   → 每条返回该 subagent session 的最终 assistant 正文（与通知 record.result 同源），
+ *     可选 limit 参数（默认 8000 字符/条，超出截断 + 提示读原文件）。
+ * 定位复用既有发现机制（sa-xxx manifest 反查 / uuid 片段 / 路径），不新造目录或文件。
+ */
+import type { Entry, ParseResult } from './core/parser.js'
+import type { MatchedSession } from './discovery/find.js'
+import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
+import type { ResolveResult, SessionReadAction, SessionReadParams, ToolResult } from './tool-handler.js'
+
+/** result 批量上限（design subagent-sync-collect §3.1.3：一次最多 10 个）。 */
+const RESULT_MAX_BATCH = 10
+
+/** result 单条默认字符上限（design §3.1.3：默认 8000 字符/条）。 */
+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 的注入面（构造期常量绑定）。 */
+export interface ResultActionDeps {
+  err(message: string): Error
+  stripHash(s: string): string
+  requireStr(val: string | undefined, name: string, action: SessionReadAction): string
+  resolveSessionId(
+    rawSession: string | undefined,
+    action: SessionReadAction,
+    agentDir: string,
+    source?: 'main' | 'subagent',
+    /** S3：批量预取的 manifest 列表（避免逐 id 重复全量扫描）；单 id 不传。 */
+    prefetchedManifests?: RecordManifest[],
+  ): Promise<ResolveResult>
+  disambiguate(query: string, candidates: MatchedSession[]): ToolResult
+  safeParse(fileName: string): Promise<ParseResult>
+  /** 批量头行短 id 截断宽度（tool-handler SESSION_ID_PREFIX_LEN 同源）。 */
+  sessionIdPrefixLen: number
+}
+
+/**
+ * 从 assistant message content 提取纯 text（text 块顺序拼接）。
+ *
+ * 与 record 侧 text_delta 直累积同构：同一 message 内多个 text 块无分隔拼接
+ *（流式 delta 逐段 append），thinking/toolCall 块不入 record.text，此处同样排除。
+ *
+ * [S7 code-simplify 登记] 本包内第 4 个同構「text 块提取」变体（其余三处均在
+ * tool-handler.ts / discovery/find.ts）：messageReadableText（'' join + 占位符）、
+ * extractContentText（'\n' join）、extractTextFromContent（' ' join + 空返 undefined）。
+ * 本变体的 '' 无分隔拼接是 A4 取回逐字节一致锁定的硬理由（对齐 record.result 的
+ * 流式 delta 无分隔累积），不可与带分隔符的变体合并——差异是行为敏感点，勿「顺手统一」。
+ */
+function assistantMessageText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  let out = ''
+  for (const block of content) {
+    if (block !== null && typeof block === 'object') {
+      const o = block as Record<string, unknown>
+      if (o.type === 'text' && typeof o.text === 'string') out += o.text
+    }
+  }
+  return out
+}
+
+/**
+ * 从 session entries 提取最终结果正文（与完成通知 record.result 同源，A4 逐字节一致的前置）。
+ *
+ * 同源语义（packages/subagent-core/src/execution/execution-record.ts getFullText，只读参考）：
+ * record.result = AgentResult.text = getFullText(record) = 全部 assistant turn 文本
+ * filter(非空，空白串按非空) join("\\n\\n")；pi 每 turn_end 对应一条 assistant message
+ *（agent-session.js turn_end 携带 message），故文件侧重建 = 每条 assistant message 的
+ * text 块顺序拼接 → 跨 message 非空过滤 join("\\n\\n")。
+ *
+ * 取「最后一条 user message 之后」的 assistant 文本：one-shot（单 user prompt，
+ * collect:sync 的目标形态）与 join-all 逐字节一致；多轮 chatMode session 对齐
+ * 「最终一轮输出」语义。
+ *
+ * 导出供单测白盒锁定同源重建规则（message 内 '' join / 跨 message '\n\n' join /
+ * thinking 与 toolCall 排除 / 空 text 过滤 / 末 user 边界）。
+ */
+export function extractFinalAssistantText(entries: Entry[]): string {
+  let lastUserIdx = -1
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]?.message?.role === 'user') {
+      lastUserIdx = i
+      break
+    }
+  }
+  const texts: string[] = []
+  for (let i = lastUserIdx + 1; i < entries.length; i++) {
+    const e = entries[i]
+    if (e?.message?.role !== 'assistant') continue
+    const text = assistantMessageText(e.message.content)
+    if (text.length > 0) texts.push(text)
+  }
+  return texts.join('\n\n')
+}
+
+/** result 单条取回结果（单条 details 与批量 details.items 共用形状）。 */
+interface ResultItem {
+  /** 调用方原始输入（sa-id / uuid 片段 / 路径） */
+  session: string
+  /** 反查到的真实 session id（header id，非 sa- 占位） */
+  sessionId: string
+  /** session .jsonl 绝对路径（截断提示读原文件用） */
+  sessionFile: string
+  /** 全量正文字符数（截断前口径） */
+  totalChars: number
+  truncated: boolean
+  /** 实际展示正文（截断后含尾提示；未截断时 = 全量正文） */
+  text: string
+}
+
+/** result 截断尾提示（design §3.1.3：超出截断 + 提示读原文件）。 */
+/** result 条目截断提示行。
+ *
+ * [S8 code-simplify 口径注] 本函数的 X = **保留**字符数（limit）；而 subagent-core
+ * notifier.ts buildTruncationPointer 同模板的 X = **丢弃**字符数（total - kept）。
+ * 两处措辞同构但口径相反（主 agent 会先后消费两种通知），统一字符串 = 行为变更，
+ * 勿顺手改口径——读本行时先确认在消费哪一侧。
+ * [C6] 英文去 emoji（对齐 notifier 指针行的纯英文形态，adversarial-review-fixes §3.4）。 */
+function formatResultTruncation(
+  raw: string,
+  sessionFile: string,
+  limit: number,
+  totalChars: number,
+): string {
+  return (
+    `\n\n[truncated ${limit} of ${totalChars} chars — ` +
+    `full text: read ${sessionFile}, or session_read { action:"detail", session:"${raw}" }]`
+  )
+}
+
+/**
+ * result 的 limit 解析：缺省 8000；非有限数/非正数报错（schema 已限 Number，此处防御
+ * + 可单测绕过 schema）。向下取整防小数 slice 语义模糊。
+ */
+function resolveResultLimit(raw: number | undefined): number {
+  if (raw === undefined) return RESULT_DEFAULT_LIMIT
+  if (!Number.isFinite(raw) || raw <= 0) {
+    throw new Error(
+      `limit "${String(raw)}" 无效，需为正数。👉 传正整数重试（缺省 ${RESULT_DEFAULT_LIMIT} 字符/条）。`,
+    )
+  }
+  return Math.floor(raw)
+}
+
+/**
+ * result 的 session 列表解析：单 id 或逗号批量（≤10）。
+ * 空条目（如 "sa-a," 或连续逗号）与超限均明确报错（含上限数字与 👉）。
+ */
+function parseResultSessionList(raw: string | undefined, deps: ResultActionDeps): string[] {
+  const trimmed = deps.requireStr(raw, 'session', 'result')
+  const ids = trimmed.split(',').map((s) => deps.stripHash(s.trim()))
+  if (ids.some((id) => id === '')) {
+    throw deps.err(
+      `session 列表含空条目："${trimmed}"。👉 检查逗号分隔格式（如 "sa-aaa,sa-bbb"）重试。`,
+    )
+  }
+  if (ids.length > RESULT_MAX_BATCH) {
+    throw deps.err(
+      `批量取回 ${ids.length} 个 session 超上限：一次最多 ${RESULT_MAX_BATCH} 个。` +
+        `\n👉 分批取回（每批 ≤${RESULT_MAX_BATCH} 个 id）。`,
+    )
+  }
+  return ids
+}
+
+/**
+ * result：取回 subagent session 的最终结果正文（design subagent-sync-collect §3.1.3）。
+ *
+ * 流程：逐 id 走 resolveSessionId 三形态反查（sa-xxx manifest 精确反查 / uuid 片段 /
+ * 绝对路径，multi 走既有 disambiguate）→ safeParse → extractFinalAssistantText
+ *（与通知 record.result 同源）→ limit 截断。定位零新机制，不新造目录或文件。
+ *
+ * content 形态：单 id = 纯正文（无包装，未截断时与 record.result 逐字节一致，A4 取回门）；
+ * 批量 = 每条目 `[i/n] <原始id> (session <短id>)` 头行 + 正文，'\\n\\n---\\n\\n' join。
+ *
+ * 错误路径（明确报错不返空串）：id 无匹配（ES2/F1 风格）、manifest 有但文件不存在
+ *（ES1：GC 或 pi session 延迟写入尚未 flush）、无 assistant 输出（运行中/未写正文）、
+ * 批量超限 / 空条目 / limit 非法。
+ */
+export async function doResult(
+  params: SessionReadParams,
+  agentDir: string,
+  deps: ResultActionDeps,
+): Promise<ToolResult> {
+  const ids = parseResultSessionList(params.session, deps)
+  const limit = resolveResultLimit(params.limit)
+  // S3（code-simplify）：sa- 形态走 manifest 反查，逐 id 调用会重复全量扫 subagents/ 树
+  //（N+1）——批量入口预取一次注入。uuid 片段/路径形态不经 manifest，不预取。
+  const prefetchedManifests = ids.some((id) => id.startsWith('sa-'))
+    ? await listRecordManifests(agentDir)
+    : undefined
+  const items: ResultItem[] = []
+  for (const id of ids) {
+    const resolved = await deps.resolveSessionId(id, 'result', agentDir, params.source, prefetchedManifests)
+    if (resolved.kind === 'multi') return deps.disambiguate(resolved.query, resolved.candidates)
+    const { entries } = await deps.safeParse(resolved.fileName)
+    const text = extractFinalAssistantText(entries)
+    if (text.length === 0) {
+      throw deps.err(
+        `session "${id}" 尚无 assistant 输出（运行中或文件尚未 flush 完整）。` +
+          `\n👉 稍后重试，或用 session_read { action:"outline", session:"${id}" } 看当前进度。`,
+      )
+    }
+    const totalChars = text.length
+    const truncated = totalChars > limit
+    items.push({
+      session: id,
+      sessionId: resolved.sessionId,
+      sessionFile: resolved.fileName,
+      totalChars,
+      truncated,
+      text: truncated
+        ? text.slice(0, limit) + formatResultTruncation(id, resolved.fileName, limit, totalChars)
+        : text,
+    })
+  }
+  if (items.length === 1) {
+    const only = items[0]
+    return {
+      content: [{ type: 'text', text: only.text }],
+      details: { ...only },
+    }
+  }
+  const blocks = items.map(
+    (it, i) =>
+      `[${i + 1}/${items.length}] ${it.session} (session ${it.sessionId.slice(0, deps.sessionIdPrefixLen)}…)\n${it.text}`,
+  )
+  return {
+    content: [{ type: 'text', text: blocks.join(RESULT_BATCH_SEPARATOR) }],
+    details: { count: items.length, items },
+  }
+}

package/src/tool-handler.ts

@@ -4,7 +4,7 @@
  * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
- * 按 action 分发到 9 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
+ * 按 action 分发到 10 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
@@ -35,6 +35,10 @@ import {
   type ToolResultSummaryEntry,
 } from './core/render.js'
 import type { Family, SessionRef, WorkflowRef } from './core/family.js'
+import { doResult, extractFinalAssistantText, type ResultActionDeps } from './result-action.js'
+
+// result action 主体在 result-action.ts（max-lines 拆分轮机械提取，零行为变更）；
+// 导出面保持不变：extractFinalAssistantText 仍从本模块导出（包内测试白盒导入路径不变）。
 import {
   buildExecutionTree,
   formatExecutionTreeText,
@@ -55,6 +59,7 @@ export type SessionReadAction =
   | 'export'
   | 'extract'
   | 'workflow'
+  | 'result'
 
 export interface SessionReadParams {
   action: SessionReadAction
@@ -185,7 +190,7 @@ function rangeLabel(r: { start: number; end: number }): string {
 // resolveSessionId：片段 → 完整 id（design §3.4 resolveSessionId 辅助）
 // ---------------------------------------------------------------------------
 
-type ResolveResult =
+export type ResolveResult =
   | { kind: 'ok'; sessionId: string; fileName: string }
   | { kind: 'multi'; query: string; candidates: MatchedSession[] }
 
@@ -246,73 +251,87 @@ function expandHome(p: string): string {
 }
 
 /**
- * 把 session 参数解析到唯一完整 id（design §6.1 M0 + U2/U3）。
- *
- * 三形态：
- * - ① 绝对路径 / ~ 前缀 → 展开后读首行 header，sessionId=header 真实 id（文件名仅定位）
- * - ② sa-id 前缀 → listRecordManifests 精确反查，sessionId=sessionFile header id
- *   （禁止降级 record.id——sa- 形态不可当 sessionId，CQ3 决策）
- * - ③ 其余 → findSessions 透传 source 沿用 F1/F2
- *
- * 错误契约（U3）：① 文件不存在/非 .jsonl/header 读不出 → F6 风格；
- * ② sessionFile GC → ES1（manifest 元数据 + 👉）；sa-id 0/>1 命中 → ES2（👉 family）。
- *
- * 仅用于 family/outline/expand/detail/search/export/extract（find action 自行调 findSessions，
- * 零匹配时返回空 + 提示，不抛错）。
+ * 把 session 参数解析到唯一完整 id（design §6.1 M0 + U2/U3）。三形态各拆独立解析器：
+ * resolveBySessionPath（① 绝对路径/~）→ resolveByRecordId（② sa- 前缀）→ resolveByFragment（③ 片段）。
+ * 错误契约（U3）：① 文件不存在/非 .jsonl/header 读不出 → F6 风格；② sessionFile GC → ES1（manifest 元数据 + 👉）；
+ * sa-id 0/>1 命中 → ES2（👉 family）。仅用于 family/outline/expand/detail/search/export/extract/result
+ *（find action 自行调 findSessions，零匹配时返回空 + 提示，不抛错）。
  */
 async function resolveSessionId(
   rawSession: string | undefined,
   action: SessionReadAction,
   agentDir: string,
   source?: 'main' | 'subagent',
+  /** S3（code-simplify）：批量调用方（doResult）预取的 manifest 列表——省去逐 id
+   *  重复全量扫 subagents/ 树（N+1）。单 id 调用点不传，行为零变化。 */
+  prefetchedManifests?: RecordManifest[],
 ): Promise<ResolveResult> {
   const session = stripHash(requireStr(rawSession, 'session', action))
 
   // ① 绝对路径或 ~ 前缀（Windows 盘符由 isAbsolute 处理）
   if (isAbsolute(session) || session === '~' || session.startsWith('~/')) {
-    const expanded = expandHome(session)
-    if (!expanded.endsWith('.jsonl')) {
-      throw err(
-        `读取失败：${session}（非 .jsonl session 文件）。👉 检查文件或换 session。`,
-      )
-    }
-    if (!existsSync(expanded)) {
-      throw err(`读取失败：${session}（文件不存在）。👉 检查文件或换 session。`)
-    }
-    const headerId = readSessionHeaderId(expanded)
-    if (headerId === undefined) {
-      throw err(
-        `读取失败：${session}（首行非合法 session header）。👉 检查文件或换 session。`,
-      )
-    }
-    return { kind: 'ok', sessionId: headerId, fileName: expanded }
+    return resolveBySessionPath(session)
   }
 
   // ② sa-id 前缀 → record manifest 精确反查
   if (session.startsWith('sa-')) {
-    const manifests = await listRecordManifests(agentDir)
-    const hits = manifests.filter((m) => m.id === session)
-    if (hits.length === 0) {
-      throw err(formatSaIdNotFound(session))
-    }
-    if (hits.length > 1) {
-      throw err(formatSaIdAmbiguous(session, hits))
-    }
-    const record = hits[0]
-    if (!existsSync(record.sessionFile)) {
-      throw err(formatSessionGc(record))
-    }
-    const headerId = readSessionHeaderId(record.sessionFile)
-    if (headerId === undefined) {
-      // header 读不出不降级 record.id（sa- 形态不可当 sessionId，CQ3）
-      throw err(
-        `读取失败：${record.sessionFile}（首行非合法 session header）。👉 检查文件或换 session。`,
-      )
-    }
-    return { kind: 'ok', sessionId: headerId, fileName: record.sessionFile }
+    return resolveByRecordId(session, agentDir, prefetchedManifests)
   }
 
   // ③ 其余：findSessions 透传 source 沿用 F1/F2
+  return resolveByFragment(session, agentDir, source)
+}
+
+/** 形态①：绝对路径 / ~ 前缀 → 展开后读首行 header，sessionId=header 真实 id（文件名仅定位）。 */
+function resolveBySessionPath(session: string): ResolveResult {
+  const expanded = expandHome(session)
+  if (!expanded.endsWith('.jsonl')) {
+    throw err(
+      `读取失败：${session}（非 .jsonl session 文件）。👉 检查文件或换 session。`,
+    )
+  }
+  if (!existsSync(expanded)) {
+    throw err(`读取失败：${session}（文件不存在）。👉 检查文件或换 session。`)
+  }
+  const headerId = readSessionHeaderId(expanded)
+  if (headerId === undefined) {
+    throw err(
+      `读取失败：${session}（首行非合法 session header）。👉 检查文件或换 session。`,
+    )
+  }
+  return { kind: 'ok', sessionId: headerId, fileName: expanded }
+}
+
+/**
+ * 形态②：sa-id 前缀 → record manifest 精确反查，sessionId=sessionFile header id
+ *（禁止降级 record.id——sa- 形态不可当 sessionId，CQ3 决策）。批量调用方传预取列表
+ *（S3：避免逐 id 全量重扫）；单 id 调用点现场扫一次。
+ */
+async function resolveByRecordId(session: string, agentDir: string, prefetchedManifests: RecordManifest[] | undefined): Promise<ResolveResult> {
+  const manifests = prefetchedManifests ?? (await listRecordManifests(agentDir))
+  const hits = manifests.filter((m) => m.id === session)
+  if (hits.length === 0) {
+    throw err(formatSaIdNotFound(session))
+  }
+  if (hits.length > 1) {
+    throw err(formatSaIdAmbiguous(session, hits))
+  }
+  const record = hits[0]
+  if (!existsSync(record.sessionFile)) {
+    throw err(formatSessionGc(record))
+  }
+  const headerId = readSessionHeaderId(record.sessionFile)
+  if (headerId === undefined) {
+    // header 读不出不降级 record.id（sa- 形态不可当 sessionId，CQ3）
+    throw err(
+      `读取失败：${record.sessionFile}（首行非合法 session header）。👉 检查文件或换 session。`,
+    )
+  }
+  return { kind: 'ok', sessionId: headerId, fileName: record.sessionFile }
+}
+
+/** 形态③：其余片段 → findSessions 透传 source 沿用 F1（零匹配）/ F2（多匹配消歧）。 */
+async function resolveByFragment(session: string, agentDir: string, source?: 'main' | 'subagent'): Promise<ResolveResult> {
   const opts = { limit: 10, ...(source ? { source } : {}) }
   const { matches } = await findSessions(session, agentDir, opts)
   if (matches.length === 0) {
@@ -1529,6 +1548,19 @@ async function doWorkflow(params: SessionReadParams, agentDir: string): Promise<
   return { content: [{ type: 'text', text }], details }
 }
 
+/** result action 的注入依赖（构造期绑定本文件私有 helper，运行时零查找开销）。 */
+const RESULT_ACTION_DEPS: ResultActionDeps = {
+  err,
+  stripHash,
+  requireStr,
+  resolveSessionId,
+  disambiguate,
+  safeParse,
+  sessionIdPrefixLen: SESSION_ID_PREFIX_LEN,
+}
+
+export { extractFinalAssistantText }
+
 // ===========================================================================
 // 入口：按 action 分发
 // ===========================================================================
@@ -1565,12 +1597,14 @@ export async function handleSessionRead(
       return doExtract(params, agentDir)
     case 'workflow':
       return doWorkflow(params, agentDir)
+    case 'result':
+      return doResult(params, agentDir, RESULT_ACTION_DEPS)
     default: {
-      // exhaustive guard：switch 覆盖全部 9 action，此处 params.action 收窄为 never；
+      // exhaustive guard：switch 覆盖全部 10 action，此处 params.action 收窄为 never；
       // 仅防御运行时非法 action（schema 正常校验下不可达）
       const exhaustive: never = params.action
       throw err(
-        `未知 action "${JSON.stringify(exhaustive)}"。👉 合法 action: find/family/outline/expand/detail/search/export/extract/workflow。`,
+        `未知 action "${JSON.stringify(exhaustive)}"。👉 合法 action: find/family/outline/expand/detail/search/export/extract/workflow/result。`,
       )
     }
   }

package/vitest.config.ts

@@ -1,3 +1,5 @@
+import path from 'node:path'
+
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
@@ -6,4 +8,17 @@ export default defineConfig({
     outputFile: { junit: './test-results/vitest-junit.xml' },
     include: ['src/__tests__/**/*.test.ts'],
   },
+  resolve: {
+    // 数组形态按序匹配（vite 文档）。跨包集成测试（cross-package-subagent-core.test.ts）
+    // 消费 @zhushanwen/subagent-core 未进 barrel 的内部符号（D3 判定不进），按
+    // subagent-workflow vitest.config 同款正则把带 .ts 后缀的包名深路径重写到 core src
+    // 物理路径——不依赖 package exports 的 `./*` 通配（u-2c 已删）；barrel（包根无路径段）
+    // 不命中，走 workspace node 解析（exports "." → src/index.ts）。
+    alias: [
+      {
+        find: /^@zhushanwen\/subagent-core\/(.+\.ts)$/,
+        replacement: `${path.resolve(__dirname, '../../../packages/subagent-core/src')}/$1`,
+      },
+    ],
+  },
 })