@zhushanwen/pi-session-reader 0.1.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from './src/index.js'

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zhushanwen/pi-session-reader",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": []
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "vitest.config.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/family.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest'
+import { buildFamilyIndex, resolveFamily } from '../core/family.js'
+import type { Entry } from '../core/parser.js'
+
+// ---- fixture 常量（映射 design §3.3 D-7 Q1 真实场景）----
+const ROOT = '019fe620' // 家族根（无 parentSession）
+const FORK = '019fe632' // fork 子代（parentSession 指向 ROOT 的文件）
+const SUB = '019fe635' // subagent（rootSessionId=FORK，挂在 fork 子代下，非家族根）
+
+// ---- fixture helpers ----
+
+/** 构造 session header entry（type=session，含 id/cwd，可选 parentSession） */
+function header(id: string, opts?: { parentSession?: string; cwd?: string }): Entry {
+  const e: Entry = { type: 'session', id, parentId: null, cwd: opts?.cwd ?? '/proj' }
+  if (opts?.parentSession) e.parentSession = opts.parentSession
+  return e
+}
+
+/** 模拟真实文件路径：含 sessionId 的 jsonl 路径（resolveParentSessionId 靠 includes 反查） */
+function sessionFile(id: string): string {
+  return `/sessions/2026-08-09T10-45-20Z_${id}.jsonl`
+}
+
+/** 构造 subagent-identity custom entry（data.rootSessionId/slug） */
+function subagentIdentity(id: string, rootSessionId: string, slug: string): Entry {
+  return {
+    type: 'custom',
+    id,
+    parentId: null,
+    customType: 'subagent-identity',
+    data: { rootSessionId, slug },
+  }
+}
+
+/** 构造 fileStats Map（M1 key=sessionId） */
+function makeStats(
+  keys: string[],
+  opts: { mtime?: number; size?: number } = {},
+): Map<string, { mtime: number; size: number }> {
+  const { mtime = 1000, size = 5000 } = opts
+  const m = new Map<string, { mtime: number; size: number }>()
+  for (const k of keys) m.set(k, { mtime, size })
+  return m
+}
+
+/** Q1 核心 fixture：ROOT ← fork ← FORK；subagent SUB 挂在 fork 子代 FORK 下 */
+function q1Fixture(aliveKeys: string[] = [ROOT, FORK, SUB]) {
+  return {
+    headers: [header(ROOT), header(FORK, { parentSession: sessionFile(ROOT) })],
+    identities: [subagentIdentity(SUB, FORK, 'deep-survey')],
+    fileStats: makeStats(aliveKeys),
+  }
+}
+
+describe('buildFamilyIndex', () => {
+  it('byId / childrenOf / subagentsByRoot 结构正确', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    expect(index.byId.has(ROOT)).toBe(true)
+    expect(index.byId.has(FORK)).toBe(true)
+    expect(index.byId.get(ROOT)?.cwd).toBe('/proj')
+
+    // childrenOf key 是父 sessionId（经 parentSession 文件路径反查）
+    expect(index.childrenOf.get(ROOT)).toHaveLength(1)
+    expect(index.childrenOf.get(ROOT)?.[0].sessionId).toBe(FORK)
+
+    // subagentsByRoot key 是 rootSessionId
+    expect(index.subagentsByRoot.get(FORK)).toHaveLength(1)
+    expect(index.subagentsByRoot.get(FORK)?.[0].sessionId).toBe(SUB)
+    expect(index.subagentsByRoot.get(FORK)?.[0].slug).toBe('deep-survey')
+  })
+
+  it('parentSession 是文件路径：经 sessionId 子串反查建 childrenOf', () => {
+    const headers = [
+      header('aaa'),
+      header('bbb', { parentSession: '/some/dir/2026-01-01T00-00-00Z_aaa.jsonl' }),
+    ]
+    const index = buildFamilyIndex(headers, [], new Map())
+
+    expect(index.childrenOf.get('aaa')?.[0].sessionId).toBe('bbb')
+  })
+
+  it('parentSession 直接是 sessionId 也兼容（简化 fixture）', () => {
+    const headers = [header('aaa'), header('bbb', { parentSession: 'aaa' })]
+    const index = buildFamilyIndex(headers, [], new Map())
+
+    expect(index.childrenOf.get('aaa')?.[0].sessionId).toBe('bbb')
+  })
+
+  it('parentSession 反查不到父 → 该 entry 不进 childrenOf（不报错）', () => {
+    const headers = [header('bbb', { parentSession: '/missing.jsonl' })]
+    const index = buildFamilyIndex(headers, [], new Map())
+
+    expect(index.childrenOf.size).toBe(0)
+  })
+
+  it('identity 缺 rootSessionId/slug → 跳过（坏数据容错）', () => {
+    const bad: Entry = {
+      type: 'custom',
+      id: 'x',
+      parentId: null,
+      customType: 'subagent-identity',
+      data: { slug: 'no-root' },
+    }
+    const index = buildFamilyIndex([], [bad], new Map())
+
+    expect(index.subagentsByRoot.size).toBe(0)
+  })
+
+  it('fileStats 原样存入 index（供 cleanedUp 判断用）', () => {
+    const fileStats = makeStats(['s1'])
+    const index = buildFamilyIndex([], [], fileStats)
+
+    expect(index.fileStats).toBe(fileStats)
+  })
+})
+
+describe('resolveFamily - 隔代关联（design §3.3 D-7 Q1 核心断言）', () => {
+  it('从家族根 resolve 能关联到挂在 fork 子代下的隔代 subagent', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    const family = resolveFamily(ROOT, index)
+
+    // Q1 核心：subagent SUB 的 rootSessionId 是 fork 子代 FORK，不是 root ROOT。
+    // 只查 root 的 subagentsByRoot 会漏；必须对 fork 链每个节点（含 forks）查。
+    expect(family.subagents.some((s) => s.sessionId === SUB)).toBe(true)
+    expect(family.subagents.find((s) => s.sessionId === SUB)?.slug).toBe('deep-survey')
+  })
+
+  it('从 fork 子代 resolve 也能关联到直接挂在其下的 subagent', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    const family = resolveFamily(FORK, index)
+    expect(family.subagents.some((s) => s.sessionId === SUB)).toBe(true)
+  })
+})
+
+describe('resolveFamily - fork 链', () => {
+  it('fork 子代的 parents 含 root；root 的 forks 含 fork 子代', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    expect(resolveFamily(FORK, index).parents.some((p) => p.sessionId === ROOT)).toBe(true)
+    expect(resolveFamily(ROOT, index).forks.some((f) => f.sessionId === FORK)).toBe(true)
+  })
+
+  it('root 无 parentSession → parents 空、forks 取 childrenOf', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    const family = resolveFamily(ROOT, index)
+    expect(family.parents).toEqual([])
+    expect(family.forks.map((f) => f.sessionId)).toEqual([FORK])
+  })
+
+  it('线性多级 fork 链：C←B←A，resolveFamily(C).parents=[B,A]', () => {
+    const headers = [
+      header('A'),
+      header('B', { parentSession: sessionFile('A') }),
+      header('C', { parentSession: sessionFile('B') }),
+    ]
+    const index = buildFamilyIndex(headers, [], new Map())
+
+    const family = resolveFamily('C', index)
+    expect(family.parents.map((p) => p.sessionId)).toEqual(['B', 'A'])
+    // forks 只含直接子代（孙代 C 是 B 的子代，不是 A 的直接子代）
+    expect(resolveFamily('A', index).forks.map((f) => f.sessionId)).toEqual(['B'])
+    expect(resolveFamily('B', index).forks.map((f) => f.sessionId)).toEqual(['C'])
+  })
+
+  it('workflows 恒为空数组（M1，接口字段保留供 M2）', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    expect(resolveFamily(ROOT, index).workflows).toEqual([])
+  })
+})
+
+describe('resolveFamily - cleanedUp（subagent 文件被 GC）', () => {
+  it('identity 在但 fileStats 不含其 sessionId → cleanedUp=true', () => {
+    const { headers, identities, fileStats } = q1Fixture([ROOT, FORK]) // SUB 不在 fileStats（已 GC）
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === SUB)
+    expect(sub?.cleanedUp).toBe(true)
+  })
+
+  it('identity 在且 fileStats 含其 sessionId → cleanedUp=false', () => {
+    const { headers, identities, fileStats } = q1Fixture() // 默认 [ROOT,FORK,SUB]，SUB 存活
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === SUB)
+    expect(sub?.cleanedUp).toBe(false)
+  })
+})
+
+describe('resolveFamily - 错误', () => {
+  it('sessionId 不在 index → 抛 Error', () => {
+    const { headers, identities, fileStats } = q1Fixture()
+    const index = buildFamilyIndex(headers, identities, fileStats)
+
+    expect(() => resolveFamily('unknown-session', index)).toThrow(/not found in family index/)
+  })
+})

package/src/__tests__/find.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises'
+import { join } from 'node:path'
+import { findSessions } from '../discovery/find.js'
+import { REAL_AGENT_DIR, HAS_E6 } from './real-data.js'
+
+/**
+ * 建一个假 session 文件：首行 header（type=session，含 id/cwd/parentSession），
+ * 可选第二条 user message（用于名称关键词匹配 + firstMessagePreview）。返回绝对路径。
+ */
+async function makeSession(
+  dir: string,
+  opts: {
+    name: string
+    id: string
+    cwd?: string
+    parentSession?: string
+    firstUserText?: string
+  },
+): Promise<string> {
+  const header: Record<string, unknown> = {
+    type: 'session',
+    id: opts.id,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  }
+  if (opts.cwd) header.cwd = opts.cwd
+  if (opts.parentSession) header.parentSession = opts.parentSession
+  const lines = [JSON.stringify(header)]
+  if (opts.firstUserText) {
+    lines.push(
+      JSON.stringify({
+        type: 'message',
+        id: opts.id + '-m1',
+        message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
+      }),
+    )
+  }
+  await mkdir(dir, { recursive: true })
+  const path = join(dir, opts.name)
+  await writeFile(path, lines.join('\n') + '\n')
+  return path
+}
+
+describe('findSessions', () => {
+  let agentDir: string
+  let slugDir: string
+
+  beforeEach(async () => {
+    agentDir = await mkdtemp(join(tmpdir(), 'find-test-'))
+    slugDir = join(agentDir, 'sessions', '--Users-demo--')
+  })
+  afterEach(async () => {
+    await rm(agentDir, { recursive: true, force: true })
+  })
+
+  it('uuid 片段匹配正确的 session（sessionId 含 query）', async () => {
+    await makeSession(slugDir, { name: 'a.jsonl', id: '019e6c96-aaaa-bbbb', cwd: '/demo' })
+    await makeSession(slugDir, { name: 'b.jsonl', id: '019fffff-cccc-dddd', cwd: '/demo' })
+
+    const { matches } = await findSessions('e6c96', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('019e6c96-aaaa-bbbb')
+  })
+
+  it('uuid 片段匹配：文件路径含 query（query 出现在文件名）', async () => {
+    // sessionId 不含 query，但文件名含 → path.includes(query) 命中
+    await makeSession(slugDir, { name: '2026-special-name.jsonl', id: 'sid-no-query', cwd: '/demo' })
+    const { matches } = await findSessions('special', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('sid-no-query')
+  })
+
+  it('fileName 填完整绝对路径，mtime/sizeBytes/cwd 为真实值', async () => {
+    const path = await makeSession(slugDir, { name: 'a.jsonl', id: 'sid-fullpath', cwd: '/demo' })
+    const { matches } = await findSessions('sid-fullpath', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].fileName).toBe(path)
+    expect(matches[0].mtime).toBeGreaterThan(0)
+    expect(matches[0].sizeBytes).toBeGreaterThan(0)
+    expect(matches[0].cwd).toBe('/demo')
+  })
+
+  it('cwd 过滤：只留 header.cwd === opts.cwd 的', async () => {
+    await makeSession(slugDir, { name: 'a.jsonl', id: 'aaa-shared', cwd: '/proj-a' })
+    await makeSession(slugDir, { name: 'b.jsonl', id: 'bbb-shared', cwd: '/proj-b' })
+
+    // query 'shared' 同时命中两个 id，cwd 过滤后只留 /proj-a
+    const { matches } = await findSessions('shared', agentDir, { cwd: '/proj-a' })
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('aaa-shared')
+    expect(matches[0].cwd).toBe('/proj-a')
+  })
+
+  it('limit 截断：truncated 标记正确', async () => {
+    // 5 个文件 id 都含 "common"，uuid 片段 "common" 全匹配
+    for (let i = 0; i < 5; i++) {
+      await makeSession(slugDir, { name: `f${i}.jsonl`, id: `common-${i}`, cwd: '/demo' })
+    }
+    const { matches, truncated } = await findSessions('common', agentDir, { limit: 2 })
+    expect(matches).toHaveLength(2)
+    expect(truncated).toBe(true)
+
+    // limit >= 总数时 truncated=false
+    const all = await findSessions('common', agentDir, { limit: 10 })
+    expect(all.matches).toHaveLength(5)
+    expect(all.truncated).toBe(false)
+  })
+
+  it("query='recent' 按 mtime 倒序", async () => {
+    const paths: string[] = []
+    for (let i = 0; i < 3; i++) {
+      paths.push(await makeSession(slugDir, { name: `r${i}.jsonl`, id: `recent-${i}`, cwd: '/demo' }))
+    }
+    // 设递增 mtime：r0 最旧，r2 最新
+    const base = Math.floor(Date.now() / 1000)
+    await utimes(paths[0], base, base)
+    await utimes(paths[1], base + 100, base + 100)
+    await utimes(paths[2], base + 200, base + 200)
+
+    const { matches } = await findSessions('recent', agentDir)
+    expect(matches).toHaveLength(3)
+    expect(matches[0].sessionId).toBe('recent-2') // mtime 最大排前
+    expect(matches[1].sessionId).toBe('recent-1')
+    expect(matches[2].sessionId).toBe('recent-0')
+  })
+
+  it("recent 也尊重 cwd 过滤", async () => {
+    await makeSession(slugDir, { name: 'a.jsonl', id: 'r-a', cwd: '/proj-a' })
+    await makeSession(slugDir, { name: 'b.jsonl', id: 'r-b', cwd: '/proj-b' })
+
+    const { matches } = await findSessions('recent', agentDir, { cwd: '/proj-a' })
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('r-a')
+  })
+
+  it('名称关键词匹配：uuid 无匹配时读首消息预览含 query', async () => {
+    // query 'plugin' 含 p/l/u/g/i/n（p/l/u 非十六进制）→ 非 uuid 特征，走首消息 fallback
+    await makeSession(slugDir, {
+      name: 'a.jsonl',
+      id: 'kw-aaaa',
+      cwd: '/demo',
+      firstUserText: '重构插件架构 plugin architecture review',
+    })
+    await makeSession(slugDir, {
+      name: 'b.jsonl',
+      id: 'kw-bbbb',
+      cwd: '/demo',
+      firstUserText: '完全无关的内容 unrelated content',
+    })
+
+    const { matches } = await findSessions('plugin', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('kw-aaaa')
+    expect(matches[0].firstMessagePreview).toContain('plugin')
+  })
+
+  it('无匹配返回 { matches: [], truncated: false }', async () => {
+    await makeSession(slugDir, { name: 'a.jsonl', id: '019abcd', cwd: '/demo' })
+    // query 非 uuid 特征（z 非十六进制），走首消息 fallback 仍无匹配
+    const result = await findSessions('zzznotexist', agentDir)
+    expect(result).toEqual({ matches: [], truncated: false })
+  })
+
+  it('firstMessagePreview 截断到 80 字符', async () => {
+    const longText = 'X'.repeat(200)
+    await makeSession(slugDir, {
+      name: 'a.jsonl',
+      id: 'prev-len',
+      cwd: '/demo',
+      firstUserText: longText,
+    })
+    const { matches } = await findSessions('prev-len', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].firstMessagePreview).toBeDefined()
+    expect(matches[0].firstMessagePreview!.length).toBeLessThanOrEqual(80)
+  })
+
+  it('纯十六进制 query 无 uuid 匹配时不走首消息 fallback（uuid 特征短路）', async () => {
+    // 'deadbeef' 全十六进制 → uuid 特征；sessionId 不含、首消息也不会含 → matched=[]
+    await makeSession(slugDir, {
+      name: 'a.jsonl',
+      id: '019aaaa',
+      cwd: '/demo',
+      firstUserText: 'deadbeef 出现在首消息里也不该匹配',
+    })
+    const result = await findSessions('deadbeef', agentDir)
+    expect(result.matches).toEqual([])
+    expect(result.truncated).toBe(false)
+  })
+
+  it.skipIf(!HAS_E6)('真实数据：e6c96 匹配 019e6c96 开头的 session', async () => {
+    const { matches } = await findSessions('e6c96', REAL_AGENT_DIR)
+    expect(matches.length).toBeGreaterThan(0)
+    expect(matches.some((m) => m.sessionId.startsWith('019e6c96'))).toBe(true)
+    // 真实值校验
+    const hit = matches.find((m) => m.sessionId.startsWith('019e6c96'))!
+    expect(hit.fileName).toContain('019e6c96')
+    expect(hit.mtime).toBeGreaterThan(0)
+    expect(hit.sizeBytes).toBeGreaterThan(0)
+  }, 30000)
+
+  it.skipIf(!HAS_E6)("真实数据：recent 返回最近 N 个，mtime 倒序，truncated=true", async () => {
+    const { matches, truncated } = await findSessions('recent', REAL_AGENT_DIR, { limit: 5 })
+    expect(matches.length).toBeGreaterThan(0)
+    expect(matches.length).toBeLessThanOrEqual(5)
+    // mtime 倒序
+    for (let i = 1; i < matches.length; i++) {
+      expect(matches[i - 1].mtime).toBeGreaterThanOrEqual(matches[i].mtime)
+    }
+    // 真实 session 文件远多于 5 → 截断
+    expect(truncated).toBe(true)
+  }, 30000)
+})