@zhushanwen/pi-session-reader 0.1.0

package/src/core/family.ts

@@ -0,0 +1,240 @@
+import type { Entry } from './parser.js'
+
+/**
+ * 家族索引与解析（design §3.3 D-7）。
+ *
+ * M1 范围：纯逻辑层。buildFamilyIndex 接收已读入的 entry 数组（不做文件 IO），
+ * 文件扫描/首行读取归 M2 discovery 层（roots.ts/find.ts/subagents.ts）。
+ *
+ * M1 占位约定（M2 discovery 层补全真实值，逻辑不变）：
+ * - SessionRef.fileName：session header 推不出文件路径 → 占位空串
+ * - 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 通用
+ *
+ * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
+ */
+
+export interface SessionRef {
+  sessionId: string
+  fileName: string
+  mtime: number
+  sizeBytes: number
+  cwd: string
+  /** fork 文件指向来源的路径（来自 header 的 parentSession，原始文件路径字符串） */
+  parentSession?: string
+  name?: string
+}
+
+export interface SubagentRef extends SessionRef {
+  rootSessionId: string
+  slug: string
+  /** identity 在但文件已被 30 天 TTL GC（design §3.3 D-7 边界 / 失败路径 F3） */
+  cleanedUp?: boolean
+}
+
+export interface WorkflowRef {
+  runId: string
+  stateFile: string
+  calls: SessionRef[]
+}
+
+export interface Family {
+  root: SessionRef
+  /** fork 父链（root 往上，最近在前） */
+  parents: SessionRef[]
+  /** fork 直接子代 */
+  forks: SessionRef[]
+  /** 含隔代（design §3.3 D-7 Q1：对 fork 链每个节点查 subagentsByRoot 合并） */
+  subagents: SubagentRef[]
+  /** M1 恒返回 []，workflow 腿需读 workflow-state 文件（IO）归 M2 */
+  workflows: WorkflowRef[]
+}
+
+export interface FamilyIndex {
+  byId: Map<string, SessionRef>
+  /**
+   * 父 sessionId（经 parentSession 文件路径反查得到）→ 直接 fork 子代。
+   * 注意 key 是 sessionId 不是文件路径：parentSession 是文件路径，buildFamilyIndex
+   * 反查映射回父 sessionId 后建此表，供 resolveFamily 用 root.sessionId 直接查。
+   */
+  childrenOf: Map<string, SessionRef[]>
+  /** rootSessionId → 该 root 直接发起的 subagent（隔代合并在 resolveFamily 跨链节点做） */
+  subagentsByRoot: Map<string, SubagentRef[]>
+  /** 建索引时的文件元信息快照，供 cleanedUp 判断（subagent 文件 GC 检测，design §3.3 D-7） */
+  fileStats: Map<string, { mtime: number; size: number }>
+}
+
+// ---- 类型守卫：从 unknown 的 entry.data 提取 subagent identity 字段 ----
+
+interface SubagentIdentityData {
+  rootSessionId: string
+  slug: string
+}
+
+function isSubagentIdentityData(v: unknown): v is SubagentIdentityData {
+  if (typeof v !== 'object' || v === null) return false
+  const obj = v as Record<string, unknown>
+  return typeof obj.rootSessionId === 'string' && typeof obj.slug === 'string'
+}
+
+/**
+ * 把 parentSession（文件路径）反查回父 sessionId。
+ *
+ * parentSession 是 fork 文件首行 header 指向来源的**文件路径**（非 session id），
+ * 文件名格式 `<timestamp>_<sessionId>.jsonl`，故路径字符串含父 sessionId。
+ * 遍历已知 sessionId 做子串匹配反查。
+ *
+ * 兼容 parentSession 直接就是 sessionId 的简化场景（测试 fixture 常用）。
+ * 假设 sessionId 互不为子串（pi 用 UUID，满足）；M2 可优化为 fileName→sessionId
+ * 索引反查（O(1)），当前遍历 O(N)，家族索引文件数通常几十到几百，可接受。
+ */
+function resolveParentSessionId(
+  parentSession: string | undefined,
+  byId: Map<string, SessionRef>,
+): string | null {
+  if (!parentSession) return null
+  if (byId.has(parentSession)) return parentSession // 直接是 sessionId（简化场景）
+  for (const sid of byId.keys()) {
+    if (parentSession.includes(sid)) return sid
+  }
+  return null
+}
+
+/**
+ * 从已读入的 session headers + subagent identity entries 建家族索引（纯逻辑，无 IO）。
+ *
+ * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
+ * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
+ * - fileStats 原样存入 index，供 cleanedUp 判断
+ *
+ * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
+ * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
+ */
+export function buildFamilyIndex(
+  headers: Entry[],
+  subagentIdentities: Entry[],
+  fileStats: Map<string, { mtime: number; size: number }>,
+): FamilyIndex {
+  const byId = new Map<string, SessionRef>()
+
+  // 1. headers → byId
+  for (const h of headers) {
+    const stat = fileStats.get(h.id)
+    const ref: SessionRef = {
+      sessionId: h.id,
+      fileName: '', // M1 占位：M2 discovery 补真实文件路径
+      mtime: stat?.mtime ?? 0,
+      sizeBytes: stat?.size ?? 0,
+      cwd: h.cwd ?? '',
+    }
+    if (h.parentSession) ref.parentSession = h.parentSession
+    byId.set(h.id, ref)
+  }
+
+  // 2. childrenOf：parentSession（文件路径）→ 反查父 sessionId → key 用父 sessionId
+  const childrenOf = new Map<string, SessionRef[]>()
+  for (const h of headers) {
+    if (!h.parentSession) continue
+    const parentSid = resolveParentSessionId(h.parentSession, byId)
+    if (parentSid === null) continue // 反查不到父 → 无法建反查关系，跳过
+    const childRef = byId.get(h.id)
+    if (!childRef) continue
+    const list = childrenOf.get(parentSid) ?? []
+    list.push(childRef)
+    childrenOf.set(parentSid, list)
+  }
+
+  // 3. subagentIdentities → subagentsByRoot
+  const subagentsByRoot = new Map<string, SubagentRef[]>()
+  for (const ident of subagentIdentities) {
+    if (!isSubagentIdentityData(ident.data)) continue // 坏数据（缺 rootSessionId/slug）跳过
+    const stat = fileStats.get(ident.id)
+    const ref: SubagentRef = {
+      // M1 占位：identity entry 不含 subagent session 的 id，用 entry.id 顶替；
+      // M2 discovery 读 subagent 文件首行 header.id 得到真实 subagent sessionId
+      sessionId: ident.id,
+      rootSessionId: ident.data.rootSessionId,
+      slug: ident.data.slug,
+      fileName: '', // M1 占位
+      mtime: stat?.mtime ?? 0,
+      sizeBytes: stat?.size ?? 0,
+      cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
+      // M1: fileStats key=sessionId；M2 改用 subagent 真实文件路径（SubagentRef.fileName）查 fileStats
+      cleanedUp: !fileStats.has(ident.id),
+    }
+    const list = subagentsByRoot.get(ident.data.rootSessionId) ?? []
+    list.push(ref)
+    subagentsByRoot.set(ident.data.rootSessionId, list)
+  }
+
+  return { byId, childrenOf, subagentsByRoot, fileStats }
+}
+
+/**
+ * 解析某 session 的家族。
+ *
+ * 隔代关联规则（design §3.3 D-7 Q1，核心）：subagent 的 rootSessionId 指向其**直接
+ * 发起 session**，可能是 fork 链中间节点而非家族根。故不能只查 root 的 subagentsByRoot——
+ * 会漏隔代 subagent（从家族根出发会漏掉挂在 fork 子代下的 subagent）。
+ *
+ * 实现：建好 fork 链后，对链上**每个**节点 id（root + 所有 parents + 直接 forks）
+ * 查 subagentsByRoot，按 sessionId 去重合并。
+ *
+ * 范围限定：M1 的 chainIds 只含直接 forks（childrenOf[root]），不递归孙代——
+ * 多层 fork 后代上的 subagent 递归关联不在 M1 范围（Q1 真实场景为单层 fork）。
+ *
+ * @throws session 不在 index.byId 时抛 Error
+ */
+export function resolveFamily(sessionId: string, index: FamilyIndex): Family {
+  const root = index.byId.get(sessionId)
+  if (!root) {
+    throw new Error(
+      `session not found in family index: "${sessionId}". ` +
+        `Ensure buildFamilyIndex received this session's header entry (type=session, id="${sessionId}").`,
+    )
+  }
+
+  // 2. fork 父链 parents（root 沿 parentSession 往上，最近在前）
+  const parents: SessionRef[] = []
+  {
+    const seen = new Set<string>([root.sessionId]) // 环防御（坏数据 A→B→A）
+    let cur: SessionRef = root
+    while (cur.parentSession) {
+      const parentSid = resolveParentSessionId(cur.parentSession, index.byId)
+      if (parentSid === null) break // 反查不到父 → 链断
+      const parentRef = index.byId.get(parentSid)
+      if (!parentRef) break // 父不在 byId（未扫描到）→ 链断
+      if (seen.has(parentSid)) break // 环防御
+      seen.add(parentSid)
+      parents.push(parentRef)
+      cur = parentRef
+    }
+  }
+
+  // 3. fork 直接子代
+  const forks: SessionRef[] = index.childrenOf.get(root.sessionId) ?? []
+
+  // 4. 隔代 subagent：对 fork 链每个节点 id 查 subagentsByRoot，按 sessionId 去重合并
+  const chainIds = new Set<string>([root.sessionId])
+  for (const p of parents) chainIds.add(p.sessionId)
+  for (const f of forks) chainIds.add(f.sessionId)
+
+  const subagents: SubagentRef[] = []
+  const seenSubagent = new Set<string>()
+  for (const sid of chainIds) {
+    const subs = index.subagentsByRoot.get(sid)
+    if (!subs) continue
+    for (const s of subs) {
+      if (seenSubagent.has(s.sessionId)) continue
+      seenSubagent.add(s.sessionId)
+      subagents.push(s)
+    }
+  }
+
+  // 5. workflows：M1 恒 []，workflow 腿需读 workflow-state 文件（IO）归 M2
+  const workflows: WorkflowRef[] = []
+
+  return { root, parents, forks, subagents, workflows }
+}

package/src/core/parser.ts

@@ -0,0 +1,160 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * session JSONL 文件解析后的单行 entry（冻结接口，M2-M5 契约）。
+ *
+ * 字段对齐 pi session JSONL 各 type 的 payload：
+ * - type / id / parentId：树结构字段。root（session header）在文件里无 parentId，
+ *   归一化为 null（design §3.5 算法 2 的 root 判定依据）。
+ * - message：仅 type=message（role/content/toolCalls）。
+ *   toolName/toolCallId：仅 role=toolResult 的 message 透出（probe 实测 515/515 带，
+ *   O2/O3 据此精确关联同 turn 内 toolCall 取参数，替代 v1 脆弱的顺序关联）。
+ * - customType / data：仅 type=custom。
+ * - parentSession / cwd：仅 type=session；parentSession 是 fork 文件指向来源的路径指针。
+ * - summary：仅 type=compaction。
+ *
+ * 注：冻结接口未列的 per-type 附加字段（如 model_change.provider、
+ * compaction.firstKeptEntryId、session.version）不在此暴露——M2+ 若需消费，
+ * 扩展 Entry 接口并同步 design.md §3.4，不在 parser 层私自保留。
+ */
+export interface Entry {
+  type: string
+  id: string
+  parentId: string | null
+  timestamp?: string
+  message?: {
+    role: 'user' | 'assistant' | 'toolResult'
+    content: unknown
+    toolCalls?: unknown[]
+    /** toolResult 的工具名（probe 实测 515/515 带，仅 role=toolResult 时存在） */
+    toolName?: string
+    /** toolResult 关联的 toolCall.id（probe 实测 515/515 全部匹配 toolCall.id） */
+    toolCallId?: string
+  }
+  customType?: string
+  data?: unknown
+  parentSession?: string
+  cwd?: string
+  summary?: unknown
+}
+
+export interface ParseResult {
+  entries: Entry[]
+  /** JSON 解析失败（含缺必填结构字段）的行数 */
+  skippedLines: number
+  totalBytes: number
+  /** 最后一行疑似半行（活跃 session 写入中），区别于中间坏行 */
+  lastLinePartial: boolean
+}
+
+function isMessageRole(v: unknown): v is 'user' | 'assistant' | 'toolResult' {
+  return v === 'user' || v === 'assistant' || v === 'toolResult'
+}
+
+/**
+ * 把单个已 JSON.parse 成功的原始对象归一化为 Entry。
+ * 缺必填结构字段（type/id）返回 undefined，调用方计为坏行（skippedLines++）。
+ */
+function toEntry(raw: unknown): Entry | undefined {
+  if (typeof raw !== 'object' || raw === null) return 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
+    }
+  }
+  if (typeof id !== 'string') return undefined
+
+  const entry: Entry = {
+    type: obj.type,
+    id: id as string,
+    parentId: typeof obj.parentId === 'string' ? obj.parentId : null,
+  }
+  if (typeof obj.timestamp === 'string') entry.timestamp = obj.timestamp
+
+  // message：role 经值守卫收窄，缺/非法 role 时丢弃 message 字段（接口 role 必填）
+  if (obj.message !== null && typeof obj.message === 'object') {
+    const m = obj.message as Record<string, unknown>
+    if (isMessageRole(m.role)) {
+      const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
+      if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
+      // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
+      if (typeof m.toolName === 'string') message.toolName = m.toolName
+      if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
+      entry.message = message
+    }
+  }
+
+  if (typeof obj.customType === 'string') entry.customType = obj.customType
+  if (obj.data !== undefined) entry.data = obj.data
+  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
+  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
+  if (obj.summary !== undefined) entry.summary = obj.summary
+
+  return entry
+}
+
+/**
+ * 解析 session JSONL 文本为 entries。
+ *
+ * 逐行 JSON.parse，坏行（语法错误或缺必填结构字段）计入 skippedLines 并跳过，
+ * 不中断整体解析——pi 坏 session 容错（design §2 失败模式）。
+ *
+ * 末尾换行产生的空行忽略（不计 skipped、不计 partial）。最后一行 parse 失败时
+ * lastLinePartial=true（活跃 session 写到一半的半行），区别于中间坏行。
+ */
+export function parseSessionContent(content: string): ParseResult {
+  const entries: Entry[] = []
+  let skippedLines = 0
+  let lastLinePartial = false
+
+  const lines = content.split('\n')
+  // 移除末尾因 trailing newline 产生的空行（非真实行）
+  while (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop()
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const isLast = i === lines.length - 1
+
+    // 中间空行容错：pi 正常 jsonl 无空行，防御文件损坏；不计 skipped
+    if (line.trim() === '') continue
+
+    let raw: unknown
+    try {
+      raw = JSON.parse(line)
+    } catch {
+      skippedLines++
+      if (isLast) lastLinePartial = true
+      continue
+    }
+
+    const entry = toEntry(raw)
+    if (entry === undefined) {
+      skippedLines++
+      if (isLast) lastLinePartial = true
+      continue
+    }
+    entries.push(entry)
+  }
+
+  return {
+    entries,
+    skippedLines,
+    totalBytes: Buffer.byteLength(content, 'utf8'),
+    lastLinePartial,
+  }
+}
+
+/** 读取 session 文件并解析。文件不存在按 Node fs 原生错误抛出（ENOENT）。 */
+export async function parseSessionFile(filePath: string): Promise<ParseResult> {
+  const content = await readFile(filePath, 'utf8')
+  return parseSessionContent(content)
+}