@zhushanwen/session-core 0.11.0

package/README.md

@@ -0,0 +1,24 @@
+# @zhushanwen/session-core
+
+Coding-agent session 的 canonical 模型与纯 JSONL 原语基座。**零运行时依赖**（import 图不可达任何驱动/外部包），可被 node 侧 tsup 与 extension 侧 esbuild 安全内联，可独立 npm 发布。
+
+## 包定位
+
+「把某个 coding-agent 的 session 读成统一结构」的唯一落点：session-reader（pi 会话读取）、runtime 导入、未来的 coding-agent source 包共用本基座，取代各自为政的字节层副本（首行读取、entry 解析、id 归一化）。
+
+## 导出面
+
+| 导出 | 说明 |
+|------|------|
+| `Entry` / `ParseResult` / `SessionHeader` / `NormalizedSession` | canonical 模型（D1）：严格 Entry 树，坏行丢弃不占位 |
+| `parseSessionContent(content)` | JSONL 文本 → `ParseResult`（坏行计 `skippedLines`，末行半行记 `lastLinePartial`） |
+| `parseSessionFile(path)` | `parseSessionContent` 的 async 文件版（ENOENT 等按 fs 原生错误抛出） |
+| `serializeSession(entries)` | `Entry[]` → JSONL，与 pi 产物逐字节兼容（`JSON.stringify(entry) + '\n'`） |
+| `readFirstJsonlLine(path)` / `readFirstJsonlLineSync(path)` | 首行字节原语（async/sync 双形态）：只读首行、处理 CRLF/LF、跨块多字节安全；空文件/纯空白 → `undefined`；IO 错误上抛由消费方分流 |
+| `sessionIdFromFileName(fileName)` | 文件名不变量：剥 `.jsonl` 后最后一个 `_` 之后的尾段；提取不出 → `undefined` |
+| `normalizeZcodeRowId(rowId)` | zcode 行 id → 8 位零填充小写十六进制（canonical entry id 域） |
+
+## 显式不进基座
+
+- **header 合法性谓词**：reader 仅要求 `id`、runtime 要求 `id`+`cwd` 非空——语义差异是不可统一的行为契约，各消费侧保留薄包装（≤5 行，共享本基座的 `readFirstJsonlLine`）。
+- **形式化 source SPI**：source 契约 = 「产出 `NormalizedSession`」的约定，形式接口在第二个 source 落地时才抽取。

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+/**
+ * canonical session 模型（设计 D1）：「与 pi 结构一致」的严格定义。
+ *
+ * 数据语义（冻结接口，消费方 session-reader / runtime 导入 / zcode source 共享）：
+ * - type / id / parentId：树结构字段。root（session header）在文件里无 parentId，
+ *   归一化为 null。
+ * - message：仅 type=message（role/content/toolCalls）。toolName/toolCallId：仅
+ *   role=toolResult 的 message 透出（probe 实测 515/515 带，用于精确关联同 turn 内
+ *   toolCall 取参数）。
+ * - customType / data：仅 type=custom。
+ * - parentSession / cwd：仅 type=session；parentSession 是 fork 文件指向来源的路径指针。
+ * - summary：仅 type=compaction。
+ *
+ * 冻结接口未列的 per-type 附加字段不在此暴露；消费方需要时先扩展本接口——解析层
+ * 不私自保留未知字段，保证「读到的就是模型声明的」。
+ */
+/** pi message entry 的 role 域（窄联合：解析时值守卫收窄，非法 role 计坏行）。 */
+type SessionMessageRole = 'user' | 'assistant' | 'toolResult';
+interface Entry {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp?: string;
+    message?: {
+        role: SessionMessageRole;
+        content: unknown;
+        toolCalls?: unknown[];
+        /** toolResult 的工具名（仅 role=toolResult 时存在） */
+        toolName?: string;
+        /** toolResult 关联的 toolCall.id（仅 role=toolResult 时存在） */
+        toolCallId?: string;
+    };
+    customType?: string;
+    data?: unknown;
+    parentSession?: string;
+    cwd?: string;
+    summary?: unknown;
+}
+interface ParseResult {
+    entries: Entry[];
+    /** JSON 解析失败（含缺必填结构字段）的行数 */
+    skippedLines: number;
+    totalBytes: number;
+    /** 最后一行疑似半行（活跃 session 写入中），区别于中间坏行 */
+    lastLinePartial: boolean;
+}
+/**
+ * session header（首行 type='session' entry 的模型）。
+ *
+ * runtime / reader 两版消费形态的并集：reader 侧仅消费 id（cwd 可缺），
+ * runtime 侧要求 id+cwd 非空（乐观约定 timestamp 必有）。「缺 cwd 的 header 算不算
+ * 合法」是两侧不同的行为契约，由各消费侧谓词裁决（基座不导出 header 谓词），
+ * 本接口只声明字段形状：除 id 外全部可选。
+ */
+interface SessionHeader {
+    id: string;
+    cwd?: string;
+    timestamp?: string;
+    /** 父 session 血缘键（fork 出的 session header 指回源文件/源 sessionId）。 */
+    parentSession?: string;
+    /** fork 锚点 entry id（截断点）。 */
+    forkEntryId?: string;
+}
+/**
+ * 转换降级记录（zcode→canonical 转换的信息损失按性质分档）。
+ *
+ * 与 `@taiji/shared` 的 wire 契约类型 `ImportDegradation` 为结构等价声明：基座是零
+ * 依赖包（设计负面清单），不 import shared——两处定义字段逐一同步（code 五值闭集 /
+ * kind / source / count / sample / zcodeSchemaVersion），漂移由消费侧（runtime 导入
+ * 薄包装把本类型赋给 wire 契约类型）的类型检查拦截。档位语义：
+ * - `dropped_redundant`（L1）：内容已由 tool 通道保留的运行时注入丢弃，无损
+ * - `dropped_transient`（L2）：无对话语义的瞬态/注入形态丢弃 + part 级诊断登记
+ * - `truncated_output` / `compaction_unlinked`（L3）：保真损失
+ * - `unclassified`（L4）：超出闭集无法分类，丢弃 + 独立告警
+ */
+interface ImportDegradation {
+    /** 降级码（五值闭集） */
+    code: 'dropped_redundant' | 'dropped_transient' | 'truncated_output' | 'compaction_unlinked' | 'unclassified';
+    /** zcode semantics.kind 原值（按可得性携带的聚合维度） */
+    kind?: string;
+    /** metadata.source / source 原值（按可得性携带的聚合维度） */
+    source?: string;
+    /** 该 (code, kind, source) 维度的聚合计数 */
+    count: number;
+    /** 定位样本（unclassified 必带；part 级诊断可携带便于日志定位） */
+    sample?: {
+        messageId: string;
+        preview: string;
+    };
+    /** zcode schema_migration.app_version（回归定位锚，按可得性携带） */
+    zcodeSchemaVersion?: string;
+}
+/**
+ * source 包读取链的统一返回类型：`readZcodeSession(dbPath, sessionId)` 等具体读取
+ * 函数产出本形状。
+ * - header：canonical 化后的会话头（pi 侧 = 直读 JSONL 首行的 SessionHeader；zcode 侧
+ *   由 converter 从库内 session 行构造——zcode 无 cwd 概念，缺省留空不伪造）。
+ * - entries：严格 Entry 树（parentId 链完整，坏行/未知 part 不占位）。
+ * - degradations：结构化降级明细（pi 恒为 []——JSONL 直读无转换损失；zcode 侧由
+ *   converter 在降级点登记，不静默丢弃）。
+ */
+interface NormalizedSession {
+    header: SessionHeader;
+    entries: Entry[];
+    degradations: ImportDegradation[];
+}
+
+/**
+ * JSONL 解析原语：session JSONL 文本/文件 → canonical entries。
+ *
+ * 坏行语义（严格模型，设计 D1）：逐行 JSON.parse，语法错误或缺必填结构字段计入
+ * skippedLines 并丢弃，不占位、不中断整体解析。宽松「坏行保留占位」形态是
+ * core/session-trace 的私有语义（设计 D1 被否项），不进本基座。
+ */
+
+/**
+ * 解析 session JSONL 文本为 entries。
+ *
+ * 末尾换行产生的空行忽略（不计 skipped、不计 partial）；中间空行容错跳过
+ * （正常 JSONL 无空行，防御文件损坏）。最后一行 parse 失败时 lastLinePartial=true
+ * （活跃 session 写到一半的半行），区别于中间坏行。
+ */
+declare function parseSessionContent(content: string): ParseResult;
+/** 读取 session 文件并解析。文件不存在按 Node fs 原生错误抛出（ENOENT）。 */
+declare function parseSessionFile(filePath: string): Promise<ParseResult>;
+
+/**
+ * JSONL 序列化原语：canonical entries → session JSONL 文本。
+ *
+ * 字节契约（P-serializer，与 pi 产物逐字节兼容）：每行 = `JSON.stringify(entry) + '\n'`
+ * （pi session-manager `_persist` 同款）；键序责任在 Entry 对象构造方——pi appendMessage
+ * 与 converter emitEntry 均按 `{type, id, parentId, timestamp, ...payload}` 顺序构造，
+ * 本函数不重排键、不丢接口外字段。空值处理由 JSON.stringify 原生承担：undefined 值
+ * 字段不落盘，`parentId: null` 落盘为 `"parentId":null`（root entry 语义，pi 同款）。
+ */
+
+declare function serializeSession(entries: readonly Entry[]): string;
+
+/**
+ * 首行字节原语（设计 G2 的 SSOT）：只读 session JSONL 首行，收敛仓内 4 份漂移副本
+ * （runtime sync session-file-utils / runtime async session-file-external-scan /
+ * runtime async import-source-external-file / session-reader session-header）。
+ *
+ * 语义裁决：
+ * - 超长首行：块续读直至换行或 EOF（等价「回退全量读首行」，超长首行可解析）；
+ *   块大小只影响 syscall 次数不影响结果。
+ * - 跨块解码：换行先在原始 Buffer 上定位，命中前内容以 Buffer 累积、最终整体
+ *   toString——逐块 toString 会把跨块多字节 UTF-8 字符（CJK）拆出 U+FFFD。
+ * - 行尾 CRLF 剥 `\r`（副本既有实现不处理，Windows 侧编辑过的文件首行会带裸 CR
+ *   致 JSON.parse 失败；本原语统一处理）。
+ * - 空文件 / 首行剥 CR 后纯空白 → undefined。
+ * - IO 错误（不存在/权限等）上抛：错误分类信息不丢失（STANDARDS §11.2 把 IO 故障
+ *   伪装成 not-found 会误导排障）；「任何失败都视为无 header」的分流归消费侧薄包装。
+ */
+/** 首行读取（async 形态）。文件不存在/打开失败按 fs 原生错误抛出。 */
+declare function readFirstJsonlLine(filePath: string): Promise<string | undefined>;
+/** 首行读取（sync 形态）。文件不存在/打开失败按 fs 原生错误抛出。 */
+declare function readFirstJsonlLineSync(filePath: string): string | undefined;
+
+/**
+ * session 文件名不变量原语：全仓约定「session 文件名（剥 .jsonl 后）最后一个 `_`
+ * 之后的尾段 == header.id」——image-cache 孤儿判定/删除级联、session-reader 文件名
+ * 提取、parent-session 兜底匹配、短名展示等消费点共享该不变量。
+ *
+ * 无 `_` 时返回剥后缀全串（对齐 session-reader extractSessionIdFromFilename 既有
+ * 行为——uuid 直接作文件名无时间戳前缀的形态仍可提取）。uuid 特征校验是 reader 侧
+ * 策略（非 uuid 特征按无 id 处理），不进基座：基座只承诺命名不变量本身。
+ */
+declare function sessionIdFromFileName(fileName: string): string | undefined;
+
+/**
+ * zcode 行 id 值域归一化：非负安全整数 → 8 位小写十六进制（10 → '0000000a'；与
+ * pi 自身 id 形态 randomUUID().slice(0,8) 同为 8-hex，pi 侧对 entry id 仅作
+ * opaque map key 消费、无 parseInt/形态校验）。
+ *
+ * canonical entry id 由 source 包 converter 的产序计数器经本函数格式化生成，与
+ * zcode 库行 id 无对应关系；parentId 顺序链（每条 entry 指向前一条）同样由
+ * converter 维护，本函数只负责单点 id 值域归一化。
+ */
+/** 归一化产物的固定十六进制位数（8-hex，'00000001' 起）。 */
+declare const ZCODE_ROW_ID_WIDTH = 8;
+declare function normalizeZcodeRowId(rowId: number): string;
+
+export { type Entry, type ImportDegradation, type NormalizedSession, type ParseResult, type SessionHeader, type SessionMessageRole, ZCODE_ROW_ID_WIDTH, normalizeZcodeRowId, parseSessionContent, parseSessionFile, readFirstJsonlLine, readFirstJsonlLineSync, serializeSession, sessionIdFromFileName };

package/dist/index.js

@@ -0,0 +1,181 @@
+// src/parse.ts
+import { readFile } from "fs/promises";
+function isMessageRole(v) {
+  return v === "user" || v === "assistant" || v === "toolResult";
+}
+function parseEntryMessage(raw) {
+  if (raw === null || typeof raw !== "object") return void 0;
+  const m = raw;
+  if (!isMessageRole(m.role)) return void 0;
+  const message = { role: m.role, content: m.content };
+  if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls;
+  if (typeof m.toolName === "string") message.toolName = m.toolName;
+  if (typeof m.toolCallId === "string") message.toolCallId = m.toolCallId;
+  return message;
+}
+function assignOptionalFields(obj, entry) {
+  if (typeof obj.customType === "string") entry.customType = obj.customType;
+  if (obj.data !== void 0) 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 !== void 0) entry.summary = obj.summary;
+}
+function toEntry(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const obj = raw;
+  if (typeof obj.type !== "string") return void 0;
+  const id = obj.id;
+  if (typeof id !== "string") return void 0;
+  const entry = {
+    type: obj.type,
+    id,
+    parentId: typeof obj.parentId === "string" ? obj.parentId : null
+  };
+  if (typeof obj.timestamp === "string") entry.timestamp = obj.timestamp;
+  const message = parseEntryMessage(obj.message);
+  if (message !== void 0) entry.message = message;
+  assignOptionalFields(obj, entry);
+  return entry;
+}
+function parseSessionContent(content) {
+  const entries = [];
+  let skippedLines = 0;
+  let lastLinePartial = false;
+  const lines = content.split("\n");
+  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;
+    if (line.trim() === "") continue;
+    let raw;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      skippedLines++;
+      if (isLast) lastLinePartial = true;
+      continue;
+    }
+    const entry = toEntry(raw);
+    if (entry === void 0) {
+      skippedLines++;
+      if (isLast) lastLinePartial = true;
+      continue;
+    }
+    entries.push(entry);
+  }
+  return {
+    entries,
+    skippedLines,
+    totalBytes: Buffer.byteLength(content, "utf8"),
+    lastLinePartial
+  };
+}
+async function parseSessionFile(filePath) {
+  const content = await readFile(filePath, "utf8");
+  return parseSessionContent(content);
+}
+
+// src/serialize.ts
+function serializeSession(entries) {
+  let out = "";
+  for (const entry of entries) {
+    out += `${JSON.stringify(entry)}
+`;
+  }
+  return out;
+}
+
+// src/first-line.ts
+import { open } from "fs/promises";
+import { closeSync, openSync, readSync } from "fs";
+var NEWLINE_BYTE = 10;
+var CHUNK_BYTES = 8192;
+function decodeLineBytes(chunks) {
+  if (chunks.length === 0) return void 0;
+  const line = Buffer.concat(chunks).toString("utf8");
+  const withoutCr = line.endsWith("\r") ? line.slice(0, -1) : line;
+  return withoutCr.trim() === "" ? void 0 : withoutCr;
+}
+async function readFirstLineViaHandle(fh) {
+  const buffer = Buffer.alloc(CHUNK_BYTES);
+  const chunks = [];
+  for (; ; ) {
+    const { bytesRead } = await fh.read(buffer, 0, CHUNK_BYTES, null);
+    if (bytesRead === 0) {
+      return decodeLineBytes(chunks);
+    }
+    const nl = buffer.subarray(0, bytesRead).indexOf(NEWLINE_BYTE);
+    if (nl >= 0) {
+      chunks.push(Buffer.from(buffer.subarray(0, nl)));
+      return decodeLineBytes(chunks);
+    }
+    chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+  }
+}
+async function readFirstJsonlLine(filePath) {
+  const fh = await open(filePath, "r");
+  try {
+    return await readFirstLineViaHandle(fh);
+  } finally {
+    try {
+      await fh.close();
+    } catch (err) {
+      console.debug("first-line read: close failed after successful read (best-effort)", err);
+    }
+  }
+}
+function readFirstJsonlLineSync(filePath) {
+  const fd = openSync(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(CHUNK_BYTES);
+    const chunks = [];
+    for (; ; ) {
+      const bytesRead = readSync(fd, buffer, 0, CHUNK_BYTES, null);
+      if (bytesRead === 0) {
+        return decodeLineBytes(chunks);
+      }
+      const nl = buffer.subarray(0, bytesRead).indexOf(NEWLINE_BYTE);
+      if (nl >= 0) {
+        chunks.push(Buffer.from(buffer.subarray(0, nl)));
+        return decodeLineBytes(chunks);
+      }
+      chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+    }
+  } finally {
+    try {
+      closeSync(fd);
+    } catch (err) {
+      console.debug("first-line read: closeSync failed after successful read (best-effort)", err);
+    }
+  }
+}
+
+// src/session-id.ts
+function sessionIdFromFileName(fileName) {
+  const noExt = fileName.replace(/\.jsonl.*$/, "");
+  const idx = noExt.lastIndexOf("_");
+  const candidate = idx >= 0 ? noExt.slice(idx + 1) : noExt;
+  return candidate.length > 0 ? candidate : void 0;
+}
+
+// src/zcode-id.ts
+var ZCODE_ROW_ID_WIDTH = 8;
+var HEX_RADIX = 16;
+function normalizeZcodeRowId(rowId) {
+  if (!Number.isSafeInteger(rowId) || rowId < 0) {
+    throw new RangeError(`zcode row id must be a non-negative safe integer, got: ${rowId}`);
+  }
+  return rowId.toString(HEX_RADIX).padStart(ZCODE_ROW_ID_WIDTH, "0");
+}
+export {
+  ZCODE_ROW_ID_WIDTH,
+  normalizeZcodeRowId,
+  parseSessionContent,
+  parseSessionFile,
+  readFirstJsonlLine,
+  readFirstJsonlLineSync,
+  serializeSession,
+  sessionIdFromFileName
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@zhushanwen/session-core",
+  "version": "0.11.0",
+  "type": "module",
+  "description": "Canonical session model and pure JSONL primitives shared by session readers and importers: Entry/ParseResult/SessionHeader/NormalizedSession, parse/serialize, first-line byte primitive, session id invariants. Zero runtime dependencies.",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}