@deepwhale/core 1.0.12 → 1.0.13

package/dist/session/jsonl.js

@@ -0,0 +1,226 @@
+/**
+ * Session JSONL — append-only 持久化 + crash recovery
+ *
+ * 协议（pi 借鉴）：
+ * - 每条消息 = 1 行 JSON
+ * - 行分隔符 = '\n'（不带 \r）
+ * - 写入：append + fsync（保证不丢消息）
+ * - 读取：行扫描，**自动截断不完整行**（crash recovery 关键）
+ *
+ * Sprint 0.2 范围：
+ * - SessionWriter（append + fsync + flush）
+ * - SessionReader（line-by-line + partial line truncation）
+ * - SessionEvent 联合类型（4 种核心：user/assistant/tool/system）
+ * - v2.0 升级到 Session DAG（DAG 与 Planner 同链路，arch §3.5）
+ *
+ * Sprint 1c-revive-2-D-5 已落地（产线代码 packages/core/src/session/compaction.ts）：
+ * - D-5-1 基础 compaction（shouldCompact + compact + 'compaction' event）
+ *   触发：promptTokens >= window * compactRatio (默认 0.8, Reasonix compact.go 拍板)
+ * - D-5-2 stuck latch（CompactionState + runCompactionWithLatch + 'compaction_paused' event）
+ *   连续 N 次失败 (默认 2) → latch 暂停, 防 death loop
+ * - D-5-3 tail token budget（resolveTail, tailMode='token_budget' 默认）
+ *   拍板 source: Reasonix compact.go:271-289 (tail 按 token budget 而非 message count)
+ *
+ * SessionEvent union 当前 7 kind：
+ *   user / assistant / tool / system / compaction / compaction_paused / verification
+ * SessionReader 读 'compaction' / 'compaction_paused' / 'verification' 不重放进 LLM context
+ * (compaction.ts 拍板: 这三种是 runtime/metadata, 不进 context).
+ *
+ * 'verification' event (Sprint 1c-revive-2-D-11-3, 2026-06-04): `deepwhale --verify`
+ * 或 REPL `/verify` 跑完生成的 VerificationReport 摘要写到 session JSONL.
+ *   - 跟 'compaction'/'compaction_paused' 同语义: metadata, 不重放进 LLM context.
+ *     用户 reload session 看不到 verification event 拼成 message (跟 paused event 一致).
+ *   - 字段: report (VerificationReport 形态) + status (passed / failed) — 给 viewer
+ *     / audit log 留口.
+ *   - Sprint 1c-revive-2-D-11-3 拍板: 旧 session 文件 (没有 verification event)
+ *     reload 不崩, 因为 SessionReader 走 kind discriminator union type,
+ *     旧 kind 解析流程不变. 新 kind 在旧 reader 读不到 (kind 不在 union),
+ *     但新 reader 读旧 JSONL 也不会试图 parse 缺失字段 — 严格 union 兜底.
+ *   - 拍板 (D-11, 2026-06-04): 不**不**新增 session event 子表 / 不**不**新建 verification.jsonl,
+ *     跟 user/assistant/tool 同 append-only 1 JSONL 走, 简单且对旧 loader 透明.
+ *
+ * Sprint 1+ 仍待落地（待拍板）：
+ * - 索引（按 messageId 加速查询）
+ * - 分片（>100MB 自动切文件）
+ * - 加密（at-rest AES-256-GCM）
+ * - 压缩（gzip content > N byte）
+ */
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * JSONL Writer — append + fsync。
+ *
+ * 使用方式：
+ *   const w = new SessionWriter('/path/to/session.jsonl');
+ *   await w.open();
+ *   await w.append({ kind: 'user', ts: Date.now(), content: 'hello' });
+ *   await w.close();
+ *
+ * 关键：每次 append 都 fsync（v1.0 = 单人本地，可接受开销；v2.0 引入 batch fsync）
+ */
+export class SessionWriter {
+    path;
+    handle = null;
+    writeQueue = Promise.resolve();
+    constructor(path) {
+        this.path = path;
+    }
+    async open() {
+        await fs.mkdir(dirname(this.path), { recursive: true });
+        this.handle = await fs.open(this.path, 'a');
+    }
+    /** 追加一条事件（fsync 后返回） */
+    async append(event) {
+        if (!this.handle) {
+            throw new Error('SessionWriter: must call open() before append()');
+        }
+        // 串行化写：避免并发 fsync 乱序
+        this.writeQueue = this.writeQueue.then(() => this.doAppend(event));
+        return this.writeQueue;
+    }
+    async doAppend(event) {
+        const handle = this.handle;
+        if (!handle)
+            throw new Error('SessionWriter: handle closed');
+        const line = JSON.stringify(event) + '\n';
+        await handle.write(line);
+        await handle.sync(); // fsync — 保证数据落盘
+    }
+    async close() {
+        // 关键：先 await writeQueue 排空，否则 doAppend 中的 handle.write/sync
+        // 会在 handle.close() 之后执行，触发 'EBADF' / 'file closed' 错误。
+        // 复现：append 后立刻 close（不 await）→ write 撞上 closed handle
+        await this.writeQueue;
+        if (this.handle) {
+            await this.handle.close();
+            this.handle = null;
+        }
+    }
+}
+/**
+ * JSONL Reader — line-by-line + 截断 partial line。
+ *
+ * Crash recovery 关键点：
+ * - 写入中途 crash → 最后一行可能是 partial JSON
+ * - read() 检测到不完整行 → 截断 + 警告 + 返回前面的完整行
+ * - 不抛错（让 agent 启动不卡死）
+ *
+ * 截断策略：把最后一行（无论完整与否）从文件删除
+ */
+export class SessionReader {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /** 读取所有完整事件（自动 truncate partial last line） */
+    async readAll() {
+        let text;
+        try {
+            text = await fs.readFile(this.path, 'utf8');
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === 'ENOENT')
+                return [];
+            throw e;
+        }
+        return this.parseLines(text);
+    }
+    parseLines(text) {
+        // Sprint 1c-revive-2-D-5+ (review P2, 2026-06-04): 入口清零 lastIncompleteLineIndex.
+        // 拍板: 同一个 SessionReader 实例先读过损坏文件 (有 partial line), truncate()
+        // 成功后, 再读修复后的文件, 旧 index 仍残留, 后续 truncate() 会按旧 index
+        // 截断, 可能删掉有效 events. 拍 parseLines 入口重置 = "本次读决定
+        // lastIncompleteLineIndex, 不会被前次污染".
+        this.lastIncompleteLineIndex = -1;
+        const events = [];
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                events.push(parsed);
+            }
+            catch {
+                // 不完整行 / 损坏行：截断掉（crash recovery）
+                // 后面 truncate() 会把这一行从文件删除
+                this.lastIncompleteLineIndex = i;
+                break;
+            }
+        }
+        return events;
+    }
+    lastIncompleteLineIndex = -1;
+    /** 截断文件到最后一个完整事件（crash recovery） */
+    async truncate() {
+        if (this.lastIncompleteLineIndex < 0) {
+            return { truncated: 0 };
+        }
+        const text = await fs.readFile(this.path, 'utf8');
+        const lines = text.split('\n');
+        const keep = lines.slice(0, this.lastIncompleteLineIndex).join('\n') + '\n';
+        const truncatedBytes = Buffer.byteLength(text, 'utf8') - Buffer.byteLength(keep, 'utf8');
+        // Sprint 1c.6: temp file + atomic rename (修 1c.5 'w' flag 漏洞)
+        //
+        // 1c.5 用 fs.open(this.path, 'w') — 'w' = O_TRUNC 立即截 0 字节.
+        // fsync 救不了"open → write"窗口: 进程在这段被杀, session 变 0 字节,
+        // 比不 truncate 更坏. 1c.5 test 只验了"成功路径 stat().size",
+        // 没覆盖最坏窗口, 是 R-G1 "test passed ≠ production works" 反例.
+        //
+        // 修法: write to temp + atomic rename. 关键不变量:
+        //   - 写 temp 阶段崩 → 原文件**完整保留** (没动), 可能有 .tmp 垃圾待清理
+        //   - rename 阶段崩 → POSIX 原子 (要么旧要么新, 没有中间态),
+        //                    Windows MoveFileEx 覆盖原子
+        //   - truncate 返回后, 文件系统状态 ∈ {原文件不变, 原文件 = keep}
+        //     — 绝不会有 0 字节第三态
+        //
+        // temp path 唯一性: pid + timestamp + 随机, 避免并发 truncate 同文件
+        // (v1.0 单人本地不并发, 但保险). 同 dir 保证 rename atomic.
+        const tempPath = `${this.path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+        const handle = await fs.open(tempPath, 'w');
+        try {
+            await handle.writeFile(keep, 'utf8');
+            await handle.sync();
+        }
+        catch (err) {
+            // 写 temp 失败: 清理垃圾, 原文件**不动**, 抛错给 caller.
+            // 拍板 (review P2, 2026-06-04): 失败**保留** lastIncompleteLineIndex,
+            // caller 之后重试 truncate 仍能清掉这个 partial line. 抹掉的话会
+            // "成功一次后忘记清" 反复 leak, 更难诊断.
+            await handle.close().catch(() => { });
+            await fs.unlink(tempPath).catch(() => { });
+            throw err;
+        }
+        await handle.close();
+        // atomic rename: 旧文件要么没被替换 (进程在 rename 前被杀, 原文件 = 旧 keep+partial),
+        // 要么被替换 (rename 完成, 原文件 = new keep). 不会有 0 字节.
+        try {
+            await fs.rename(tempPath, this.path);
+        }
+        catch (err) {
+            // rename 失败: 清理 temp, 原文件**不动** (rename 没成功), 抛错给 caller.
+            // 拍板: 同样**保留** lastIncompleteLineIndex, 跟写 temp 失败同语义.
+            await fs.unlink(tempPath).catch(() => { });
+            throw err;
+        }
+        // 成功: 清零 lastIncompleteLineIndex (拍板 review P2, 2026-06-04).
+        // 下次 parseLines 入口本来就会重置 (review P2 fix), 这里额外清零
+        // 是给 truncate 后的二次调用兜底 (虽然实际不会发生, 但防御编程).
+        this.lastIncompleteLineIndex = -1;
+        return { truncated: truncatedBytes };
+    }
+}
+/**
+ * 便捷工厂 — 组合 open + read + truncate + close
+ */
+export async function readSessionEvents(path) {
+    const reader = new SessionReader(path);
+    const events = await reader.readAll();
+    if (reader['lastIncompleteLineIndex'] >= 0) {
+        await reader.truncate();
+    }
+    return events;
+}
+//# sourceMappingURL=jsonl.js.map

package/dist/session/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/session/jsonl.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 跨包共享的原子类型 — Sprint 0 占位。
+ * Sprint 1+ 把 Task / Message / Context / Observation / Memory 移到这里（来自 AGENT_RUNTIME.md）。
+ */
+export type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};
+export type FilePath = Brand<string, 'FilePath'>;
+export type SessionId = Brand<string, 'SessionId'>;
+export type ToolName = Brand<string, 'ToolName'>;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACnD,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * 跨包共享的原子类型 — Sprint 0 占位。
+ * Sprint 1+ 把 Task / Message / Context / Observation / Memory 移到这里（来自 AGENT_RUNTIME.md）。
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepwhale/core",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Core primitives for DeepWhale: i18n, session JSONL, compaction, types",
   "license": "MIT",
   "type": "module",