diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 59e6842ad8..f9527fe9f6 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -375,6 +375,7 @@ Environment variables take precedence over the config file. They are useful for | `BILI_UPSTREAM_PROXY` | Upstream proxy for the proxy's own outbound connections — highest priority, above per-URL/per-provider config. See the README *Upstream proxy* section. | | `BILI_PERSIST` | Set `0` to disable session persistence (in-memory only, lost on restart). | | `BILI_PERSIST_DEBOUNCE_MS` | Debounce window for persistence writes to disk, in ms (default `500`). | +| `BILI_PERSIST_TAIL_TOKENS` | Token budget for the persisted conversation snapshot (#401). The disk record stores the **folded view** (block summaries in place of compressed ranges) truncated to the newest messages within this budget — never the raw full history. Default `16384`; `0` disables message persistence entirely (block summaries and compressed originals still persist; `bili export` falls back to block-only rendering). Live in-memory sessions are unaffected — `bili export` of a live session is always complete. | | `BILI_PERSIST_EPERM_ALERT_THRESHOLD` | N consecutive persist write failures (`EPERM`/`EBUSY`/`EACCES`) on one session before the one-time "add this dir to antivirus exclusions" alert fires (default `5`). Windows only. See [Windows: exclude the sessions dir](#windows-exclude-the-sessions-dir-from-antivirus-362). | | `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | Re-alert window for the persist EPERM alert, in ms. `0` (default) = alert once then stay silent; `>0` = re-alert at most every that many ms while the failures continue. | | `BILI_TUNNEL_ALLOWED_HOSTS` | `/bili/` tunnel admission for **remote clients** (#409): comma-separated `host` or `host:port` entries that unlock loopback/private destinations (e.g. a LAN relay or the machine's own sglang) for non-loopback clients. The proxy itself and link-local/metadata addresses are always denied; local (loopback) clients always pass. | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index a8d959867b..66745bf0d2 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -373,6 +373,7 @@ | `BILI_UPSTREAM_PROXY` | 代理自身出站连接的上游代理 —— 优先级最高,高于 per-URL/per-provider 配置。见 README「上游代理」一节。 | | `BILI_PERSIST` | 设 `0` 关闭会话持久化(仅内存,重启即丢)。 | | `BILI_PERSIST_DEBOUNCE_MS` | 持久化写盘的防抖窗口(毫秒,默认 `500`)。 | +| `BILI_PERSIST_TAIL_TOKENS` | 持久化会话快照的 token 预算(#401)。盘上记录的是**折叠视图**(压缩范围以块摘要替代)并截断到该预算内的最新消息 —— 不再存全量原始历史。默认 `16384`;设 `0` 彻底不持久化消息(块摘要与压缩原件仍会持久化,`bili export` 退回块级渲染)。活会话内存不受影响 —— 活会话的 `bili export` 始终完整。 | | `BILI_PERSIST_EPERM_ALERT_THRESHOLD` | 同一会话连续 N 次持久化写失败(`EPERM`/`EBUSY`/`EACCES`)后触发一次性「把该目录加入杀软排除项」告警的阈值(默认 `5`)。仅 Windows。见下文「Windows:把会话目录加入杀软排除项」章节。 | | `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | persist EPERM 告警的重复窗口(毫秒)。`0`(默认)= 只告警一次后静默;`>0` = 失败持续期间最多每这么久重复告警一次。 | | `BILI_MAX_SESSIONS` | 内存中最多保留的会话数(默认 `256`;LRU 淘汰 —— 磁盘是事实源)。 | diff --git a/README.md b/README.md index 2954dea914..609a48a9c2 100644 --- a/README.md +++ b/README.md @@ -418,7 +418,12 @@ pass an explicit `x-acp-session` header per conversation to avoid collisions. The proxy persists each session's compression state to the sessions dir (`%USERPROFILE%\.local\share\billion-context\` by default) and rewrites the -file every turn of a long session. On Windows, real-time antivirus (Windows +file every turn of a long session. Persisted per session: the compression +state (block summaries), the compressed originals cache (`blockContents`, +what `bili export --full` recovers), and a bounded folded-view snapshot of +the recent conversation (newest `BILI_PERSIST_TAIL_TOKENS` tokens, default +16k) — the raw full history is never duplicated on disk (#401). On +Windows, real-time antivirus (Windows Defender), the search indexer, or a sync tool (OneDrive) can lock that directory mid-write, so the rename fails with `EPERM` and every persist for that session fails until the lock clears. diff --git a/src/export.ts b/src/export.ts index 22bf3ac0b1..26d9c42ef5 100644 --- a/src/export.ts +++ b/src/export.ts @@ -63,13 +63,24 @@ export function renderHandoff(s: Session, full: boolean): string { const messages = s.lastMessages; if (messages && messages.length > 0) { - // Full-conversation snapshot (v3 files): render exactly what the model + // Conversation snapshot (v3 files): render exactly what the model // saw. Default = folded view via the kernel's own renderer (summaries // in place of compressed ranges); --full = every original message. - lines.push(full ? `## Full conversation (${messages.length} messages)` : `## Conversation (folded view as the model saw it, ${messages.length} client messages)`); + // A restored #401 snapshot is ALREADY pruned (and truncated) — its + // message ids no longer align with the state ranges, so re-running + // prune() would resurrect dropped summaries at index 0. Render it + // as-is; --full recovers folded originals from blockContents below. + const folded = s.lastMessagesFolded === true; + const view = full || folded ? messages : prune(messages, s.state); + lines.push( + full && !folded + ? `## Full conversation (${messages.length} messages)` + : folded + ? `## Conversation (persisted folded snapshot, ${messages.length} messages)` + : `## Conversation (folded view as the model saw it, ${messages.length} client messages)`, + ); lines.push(""); let lastRole = ""; - const view = full ? messages : prune(messages, s.state); for (const m of view) { if (m.role !== lastRole) { lines.push(`### ${m.role}`); @@ -79,6 +90,21 @@ export function renderHandoff(s: Session, full: boolean): string { lines.push(renderMessage(m)); } lines.push(""); + // A folded snapshot has no originals of the folded ranges — --full + // recovers them from the blockContents cache (same source the v2 + // fallback uses). + if (full && folded) { + for (const b of s.state.blocks.filter((x) => x.active)) { + const content = s.blockContents.get(b.blockId); + if (!content) continue; + lines.push(`## Block ${b.blockId}${b.topic ? ` — ${b.topic}` : ""}`); + lines.push(""); + lines.push(`### Original messages (${content.full.count})`); + lines.push(""); + lines.push(content.full.text.trim()); + lines.push(""); + } + } return lines.join("\n"); } @@ -148,7 +174,7 @@ export async function exportSession(selector: string | undefined, opts: ExportOp const store = new SessionStore({ dir: opts.dir, enabled: true }); const all = [...(await store.loadAll()).values()]; if (all.length === 0) { - return "No persisted sessions found. Sessions are written under the sessions directory once the proxy has served a request (compression state and compressed originals only — uncompressed conversation text is not persisted)."; + return "No persisted sessions found. Sessions are written under the sessions directory once the proxy has served a request (compression state, compressed originals, and a bounded folded-view snapshot of the recent conversation)."; } if (!selector) { const list = await listSessions(opts); diff --git a/src/persist.ts b/src/persist.ts index 84210ae05c..db7441591c 100644 --- a/src/persist.ts +++ b/src/persist.ts @@ -6,7 +6,7 @@ import { StateStore, flatFileNameFor, type PersistedEnvelope } from "acp-kernel/ import { sessionsDir } from "./paths.js"; import { log as loggerLog } from "./logger.js"; import { PersistEpermAlert } from "./persist-eperm.js"; -import { createInitialState, type CompressionState, type CoreMessage } from "acp-kernel"; +import { createInitialState, defaultCountTokens, prune, type CompressionState, type CoreMessage } from "acp-kernel"; import type { Session, BlockContent, BlockView } from "./session.js"; /** @@ -108,10 +108,18 @@ interface PersistedSession { state: CompressionState; /** blockContents serialized as a plain record (Maps do not survive JSON). */ blockContents: Record; - /** Latest full-conversation snapshot (v3+): the client's raw messages - * from its most recent request, overwritten every turn. Absent on v2 - * files — export falls back to block-only rendering. */ + /** Latest folded-view conversation snapshot (v3+): prune() rendered + * summaries in place of folded ranges, then truncated to the newest + * BILI_PERSIST_TAIL_TOKENS tokens (#401) — the raw full history is NOT + * persisted (it duplicated 63% of the corpus; originals of folded + * ranges remain available offline via blockContents). Absent on v2 + * files and when the tail budget is 0 — export falls back to + * block-only rendering. */ messages?: CoreMessage[]; + /** True when `messages` is an already-pruned folded snapshot (see above); + * absent on records written before #401, whose `messages` held the raw + * history and must still be pruned at export time. */ + messagesFolded?: boolean; } type Logger = (level: "info" | "warn" | "error", msg: string) => void; @@ -398,13 +406,15 @@ export class SessionStore { } function buildRecord(session: Session): PersistedSession { + const snapshot = boundedFoldedSnapshot(session); return { version: PERSIST_VERSION, savedAt: Date.now(), id: session.id, meta: { ...session.meta }, stats: { ...session.stats }, - messages: session.lastMessages, + messages: snapshot, + messagesFolded: snapshot ? true : undefined, metadata: { ...session.metadata }, state: session.state, blockContents: Object.fromEntries(session.blockContents), @@ -466,6 +476,7 @@ function buildSession(parsed: PersistedSession): Session { restored: true, blockContents, lastMessages: Array.isArray(parsed.messages) ? parsed.messages : undefined, + lastMessagesFolded: parsed.messagesFolded === true, inFlight: 0, persisted: true, }; @@ -496,6 +507,47 @@ function persistEnabled(): boolean { return true; } +/** Token budget for the persisted folded-view snapshot (#401). The raw full + * history is never persisted — prune() first replaces folded ranges with + * their summaries (exactly what `bili export` renders by default), then the + * OLDEST messages are dropped until the view fits. 0 disables message + * persistence entirely (block summaries + blockContents survive). */ +function persistTailTokens(): number { + const env = process.env.BILI_PERSIST_TAIL_TOKENS; + if (env) { + const n = Number.parseInt(env, 10); + if (Number.isFinite(n) && n >= 0) return n; + } + return 16384; +} + +/** Bounded folded-view snapshot for the on-disk record (#401). See + * PersistedSession.messages. Truncation keeps whole messages from the NEWEST + * end; at least one message always survives (even if it alone exceeds the + * budget — a handoff doc with an empty tail is useless). */ +function boundedFoldedSnapshot(session: Session): CoreMessage[] | undefined { + const msgs = session.lastMessages; + if (!msgs || msgs.length === 0) return undefined; + const budget = persistTailTokens(); + if (budget === 0) return undefined; + let view = prune(msgs, session.state); + let total = 0; + for (const m of view) total += defaultCountTokens(m.text ?? ""); + if (total > budget) { + let acc = 0; + let start = 0; + for (let i = view.length - 1; i >= 0; i--) { + acc += defaultCountTokens(view[i]!.text ?? ""); + if (acc > budget) { + start = Math.min(i + 1, view.length - 1); + break; + } + } + if (start > 0) view = view.slice(start); + } + return view; +} + function epermAlertThreshold(): number { const env = process.env.BILI_PERSIST_EPERM_ALERT_THRESHOLD; if (env) { diff --git a/src/session.ts b/src/session.ts index f9d6144f2d..ba470cb985 100644 --- a/src/session.ts +++ b/src/session.ts @@ -114,6 +114,13 @@ export type Session = { * request keeps a bounded, up-to-date copy — that is what makes offline * export complete. Bounded by MAX_SESSIONS, same as blockContents. */ lastMessages?: CoreMessage[]; + /** True when lastMessages holds an already-pruned folded-view snapshot + * (restored from disk — #401: the persisted record stores the bounded + * folded view, not the raw history). Export must render it as-is instead + * of re-running prune() (the snapshot's message ids no longer align with + * the state ranges). Cleared by snapshotMessages on the next live + * request — the client re-sends full raw history, restoring the invariant. */ + lastMessagesFolded?: boolean; /** Number of in-flight requests using this session. A session with * inFlight > 0 must NOT be LRU-evicted: evicting it mid-stream flushes a * half-mutated snapshot and then a miss reloads a SECOND Session object, @@ -268,7 +275,10 @@ export function peekSession(id: string): Session | undefined { * session, replaced every request — bounded, always the newest state. Empty * arrays (parse failures) never clobber a good snapshot. */ export function snapshotMessages(session: Session, messages: CoreMessage[]): void { - if (messages.length > 0) session.lastMessages = messages; + if (messages.length > 0) { + session.lastMessages = messages; + session.lastMessagesFolded = false; + } } /** Mark a session's state as changed so it is persisted on the next debounce. diff --git a/tests/persist-tail.test.ts b/tests/persist-tail.test.ts new file mode 100644 index 0000000000..1afb2dc35e --- /dev/null +++ b/tests/persist-tail.test.ts @@ -0,0 +1,199 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { SessionStore } from "../src/persist.ts"; +import { Session, cacheBlockContent, snapshotMessages } from "../src/session.ts"; +import { renderHandoff } from "../src/export.ts"; +import { createInitialState, defaultCountTokens } from "acp-kernel"; + +// #401: the persisted record stores a BOUNDED FOLDED-VIEW snapshot — +// prune() renders summaries in place of folded ranges, then the oldest +// messages are dropped until the view fits BILI_PERSIST_TAIL_TOKENS. The raw +// full history (63.2% of the 258MB corpus) is no longer duplicated on disk. + +function makeSession(id: string): Session { + return { + id, + meta: { protocol: "openai", upstreamOrigin: "http://up:1", title: "tail test" }, + stats: { requests: 3, tokensSaved: 0, inputTokens: 10, cachedTokens: 0, outputTokens: 5, cacheSamples: 0, lastInputTokens: 10, contextTokens: 1000 }, + metadata: {}, + createdAt: Date.now() - 1000, + lastSeen: Date.now(), + state: createInitialState(), + blockContents: new Map(), + inFlight: 0, + persisted: false, + }; +} + +function withBlock(s: Session): void { + s.state.blocks.push({ + blockId: "b0", runId: "r0", tier: 1, topic: "old work", + summary: "SUMMARY-MARKER: covered early messages about the old work.", + directMessageIds: ["m1", "m2"], effectiveMessageIds: ["m1", "m2"], directBlockIds: [], + compressedTokens: 500, createdAt: Date.now(), survivedCount: 2, generation: 1, active: true, + }); + cacheBlockContent(s, "b0", { + one: null, + full: { text: "user: OLD-ORIGINAL-one\nassistant: OLD-ORIGINAL-two", count: 2 }, + }); +} + +function readRecord(dir: string): Record { + const proto = readdirSync(dir).find((d) => d !== ".bili-migration-286.done"); + assert.ok(proto, "no protocol dir written"); + const file = readdirSync(path.join(dir, proto!)).find((f) => f.endsWith(".json")); + assert.ok(file, "no session file written"); + const envelope = JSON.parse(readFileSync(path.join(dir, proto!, file!), "utf8")) as { payload: Record }; + return envelope.payload; +} + +async function withTailEnv(value: string | undefined, fn: () => Promise): Promise { + const prev = process.env.BILI_PERSIST_TAIL_TOKENS; + if (value === undefined) delete process.env.BILI_PERSIST_TAIL_TOKENS; + else process.env.BILI_PERSIST_TAIL_TOKENS = value; + try { + return await fn(); + } finally { + if (prev === undefined) delete process.env.BILI_PERSIST_TAIL_TOKENS; + else process.env.BILI_PERSIST_TAIL_TOKENS = prev; + } +} + +test("#401 persisted messages are a folded snapshot: covered originals dropped, summary + tail kept", async () => { + await withTailEnv(undefined, async () => { + const dir = mkdtempSync(path.join(tmpdir(), "bili-tail-")); + try { + const s = makeSession("tail-folded"); + withBlock(s); + s.lastMessages = [ + { id: "m1", role: "user", contentType: "text", text: "OLD-ORIGINAL-one" }, + { id: "m2", role: "assistant", contentType: "text", text: "OLD-ORIGINAL-two" }, + { id: "m3", role: "user", contentType: "text", text: "TAIL-QUESTION still here" }, + { id: "m4", role: "assistant", contentType: "text", text: "TAIL-ANSWER also here" }, + ]; + const store = new SessionStore({ dir, enabled: true, debounceMs: 0 }); + await store.writeNow(s); + + const rec = readRecord(dir); + assert.equal(rec.messagesFolded, true, "record must mark the snapshot as pre-folded"); + const msgs = rec.messages as { id: string; text?: string }[]; + assert.ok(msgs.some((m) => m.text?.includes("SUMMARY-MARKER")), "summary missing from persisted snapshot"); + assert.ok(!msgs.some((m) => m.id === "m2"), "covered non-first messages must be dropped"); + // Kernel design: prune() always keeps the FIRST user message even + // when covered (conversation anchor) — assert that invariant too. + assert.ok(msgs.some((m) => m.id === "m1"), "first user message must survive as the anchor"); + assert.ok(!msgs.some((m) => m.text?.includes("OLD-ORIGINAL-two")), "covered original text leaked"); + assert.ok(msgs.some((m) => m.text?.includes("TAIL-QUESTION")), "tail dropped"); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); + +test("#401 budget truncation keeps the newest whole messages and at least one survivor", async () => { + await withTailEnv("50", async () => { + const dir = mkdtempSync(path.join(tmpdir(), "bili-tail-")); + try { + const s = makeSession("tail-trunc"); + const filler = "x".repeat(100); // defaultCountTokens heuristic: ~25-35 tokens per 100 chars + s.lastMessages = [ + { id: "m1", role: "user", contentType: "text", text: `oldest ${filler}` }, + { id: "m2", role: "assistant", contentType: "text", text: `middle ${filler}` }, + { id: "m3", role: "user", contentType: "text", text: `newest ${filler}` }, + ]; + const store = new SessionStore({ dir, enabled: true, debounceMs: 0 }); + await store.writeNow(s); + + const rec = readRecord(dir); + const msgs = rec.messages as { id: string; text?: string }[]; + assert.equal(rec.messagesFolded, true); + assert.ok(msgs.length >= 1, "at least one message must survive truncation"); + assert.ok(msgs.length < 3, `expected truncation (budget=50 tokens), kept ${msgs.length}`); + assert.ok(!msgs.some((m) => m.id === "m1"), "oldest message should be dropped first"); + assert.equal(msgs[msgs.length - 1]!.id, "m3", "newest message must be kept"); + const total = msgs.reduce((acc, m) => acc + defaultCountTokens(m.text ?? ""), 0); + assert.ok(total <= defaultCountTokens(`newest ${filler}`) + 1, `kept total ${total} exceeds the single-newest bound`); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); + +test("#401 BILI_PERSIST_TAIL_TOKENS=0 disables message persistence entirely (v2-style record)", async () => { + await withTailEnv("0", async () => { + const dir = mkdtempSync(path.join(tmpdir(), "bili-tail-")); + try { + const s = makeSession("tail-off"); + withBlock(s); + s.lastMessages = [{ id: "m1", role: "user", contentType: "text", text: "hello" }]; + const store = new SessionStore({ dir, enabled: true, debounceMs: 0 }); + await store.writeNow(s); + + const rec = readRecord(dir); + assert.equal(rec.messages, undefined, "messages must be absent with budget 0"); + assert.equal(rec.messagesFolded, undefined); + + // A restored session then has no snapshot — export falls back to + // the v2 block-only rendering. (The LIVE in-memory session still + // exports its full snapshot — that is unaffected by the budget.) + const restored = (await store.loadAll()).get("tail-off"); + assert.ok(restored, "session not restored"); + assert.equal(restored!.lastMessages, undefined); + const md = renderHandoff(restored!, false); + assert.match(md, /SUMMARY-MARKER/); + assert.doesNotMatch(md, /hello/); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); + +test("#401 restore + export: folded snapshot renders as-is (--full recovers originals from blockContents)", async () => { + await withTailEnv(undefined, async () => { + const dir = mkdtempSync(path.join(tmpdir(), "bili-tail-")); + try { + const s = makeSession("tail-roundtrip"); + withBlock(s); + s.lastMessages = [ + { id: "m1", role: "user", contentType: "text", text: "OLD-ORIGINAL-one" }, + { id: "m2", role: "assistant", contentType: "text", text: "OLD-ORIGINAL-two" }, + { id: "m3", role: "user", contentType: "text", text: "TAIL-QUESTION" }, + ]; + const store = new SessionStore({ dir, enabled: true, debounceMs: 0 }); + await store.writeNow(s); + + const restored = (await store.loadAll()).get("tail-roundtrip"); + assert.ok(restored, "session not restored"); + assert.equal(restored!.lastMessagesFolded, true); + + const md = renderHandoff(restored!, false); + assert.match(md, /persisted folded snapshot/); + assert.match(md, /SUMMARY-MARKER/); + assert.match(md, /TAIL-QUESTION/); + assert.doesNotMatch(md, /OLD-ORIGINAL-two/, "covered non-first original leaked (first-user anchor is kept by design)"); + assert.equal(md.match(/SUMMARY-MARKER/g)?.length, 1, "summary must not be duplicated (prune re-run leaked)"); + + const full = renderHandoff(restored!, true); + assert.match(full, /SUMMARY-MARKER/); + assert.match(full, /TAIL-QUESTION/); + assert.match(full, /OLD-ORIGINAL-two/, "--full must recover folded originals via blockContents"); + assert.match(full, /Original messages \(2\)/); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); + +test("#401 a live request clears lastMessagesFolded (client re-sends full raw history)", async () => { + const s = makeSession("tail-live"); + s.lastMessagesFolded = true; + s.lastMessages = [{ id: "acp_summary_b0", role: "system", contentType: "text", text: "[Compressed conversation section]\nSUMMARY-MARKER" }]; + snapshotMessages(s, [ + { id: "m1", role: "user", contentType: "text", text: "fresh raw history" }, + ]); + assert.equal(s.lastMessagesFolded, false, "snapshotMessages must clear the folded flag"); + assert.equal(s.lastMessages[0]!.text, "fresh raw history"); +});