@yandy0725/pi-memory 1.4.0 → 2.1.0

package/src/fs-lock.ts

@@ -0,0 +1,251 @@
+import { link, open, readFile, rm, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+
+/**
+ * **跨进程**锁。只保护「毫秒级的物理写入」这一件事。
+ *
+ * 作用域分工（见 process-lock.ts 的说明）：进程内的**逻辑作用域**（单次调用、dream 整轮）由
+ * `process-lock.ts` 的 Promise 队列承担，因此这里永远只被持有一瞬间 —— 不存在「持有太久」，
+ * 也就不需要 TTL、续约心跳与存活探测。
+ *
+ * **永不自动回收**：另一个进程崩溃留下的锁没有任何人能释放它，但**也不会被自动删掉**。
+ * 原因是「移走别人的锁」无法用 POSIX 原语做到可证明安全：`link` 这个合法获取原语的条件正是
+ * 「锁路径不存在」，所以任何「先移走旧锁、再建立自己的」的接管都会产生一个空窗，其它等待者
+ * 可以合法地抢占它；一旦移走的其实是某个**活持有者**刚建立的记录，互斥就无法再恢复（把记录
+ * 挪回去又会顶掉抢占者，而路径只能容纳一条记录）。实测：把 `rm` 换成原子 `rename` 仍然会双持有，
+ * 加上「比字节 + 放回」则会把空窗拉长，同进程内可稳定复现双持有。
+ *
+ * 因此这里的策略是「安全优先」：崩溃遗留的锁**立刻**报一条可操作的错误（写明 pid / op /
+ * startedAt / 路径，并提示如何清除），由人（或 Plan B 的显式 `/memory unlock`）处理。
+ */
+export interface LockInfo {
+	pid: number;
+	hostname: string;
+	startedAt: string;
+	op: string;
+}
+
+export interface LockOptions {
+	timeoutMs: number;
+	pollMs?: number;
+	now?: () => number;
+}
+
+export class MemoryLockedError extends Error {
+	constructor(
+		readonly lockPath: string,
+		readonly holder: LockInfo | null,
+		readonly op: string,
+		/** 记录指向一个已死的本机进程，或本身无法解释 —— 没有任何人会释放它，只能人工清除。 */
+		readonly abandoned: boolean,
+	) {
+		const described = holder
+			? `${holder.op} (pid ${holder.pid}, started ${holder.startedAt})`
+			: "an unreadable record";
+		super(
+			abandoned
+				? `Memory lock at ${lockPath} is abandoned by ${described} — delete the file to clear it`
+				: `Memory is locked by ${described}`,
+		);
+		this.name = "MemoryLockedError";
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** 仅用于诊断（决定错误文案，不参与任何回收决策）。 */
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		// 只有 ESRCH（无此进程）才算死亡；EPERM 是「存在但无权限发信号」，其余意外 errno 一并按存活处理。
+		return (e as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function isLockInfo(value: unknown): value is LockInfo {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.pid === "number" &&
+		Number.isFinite(record.pid) &&
+		typeof record.hostname === "string" &&
+		typeof record.startedAt === "string" &&
+		typeof record.op === "string"
+	);
+}
+
+type LockRead =
+	/** 锁路径不存在 —— 这是「空闲」，不是「有问题」。 */
+	| { kind: "absent" }
+	/** 存在但无法解释（非 JSON、空文件、形状不对、读不到）：只有人工能清除它。 */
+	| { kind: "unreadable" }
+	| { kind: "held"; holder: LockInfo };
+
+/**
+ * 读锁的三种状态。**必须区分「不存在」与「存在但读不懂」** —— 把前者当成后者会让
+ * 「持有者刚释放、锁刚被删」被误报成「遗弃的锁」，从而在正常竞争下抛出误导性的错误。
+ */
+async function readLockState(lockPath: string): Promise<LockRead> {
+	let raw: string;
+	try {
+		raw = await readFile(lockPath, "utf8");
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+		// 权限之类的错误：无法判断内容，按「读不懂」处理（不接管、报可操作错误）
+		return { kind: "unreadable" };
+	}
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return isLockInfo(parsed) ? { kind: "held", holder: parsed } : { kind: "unreadable" };
+	} catch {
+		return { kind: "unreadable" };
+	}
+}
+
+/**
+ * 锁的诊断视图（spec §14 的 `/memory`）。
+ *
+ * **复用私有的 `readLockState`**，不另写一份读逻辑：三态必须与获取路径同源，
+ * 否则会出现「`/memory` 说 free，下一次写入却报 locked」这种无法诊断的矛盾。
+ * 它**不判断存活、也不删任何东西**（永不自动回收）；持有者是否已死由调用方自己看 pid。
+ */
+export async function readLockStatus(
+	lockPath: string,
+): Promise<{ kind: "absent" } | { kind: "unreadable" } | { kind: "held"; holder: LockInfo }> {
+	return readLockState(lockPath);
+}
+
+type AcquireOutcome =
+	| { acquired: true }
+	| { acquired: false; holder: LockInfo | null; abandoned: boolean };
+
+/**
+ * 尝试一次获取。路径为空时不当作失败 —— 那是「刚好被释放」，直接再试一次 link（CAS 会自然地
+ * 决出唯一赢家）；两次都撞上「刚好被释放」才交回给调用方重试。
+ */
+async function acquireOnce(lockPath: string, info: LockInfo): Promise<AcquireOutcome> {
+	for (let round = 0; round < 2; round++) {
+		if (await writeExclusive(lockPath, info)) return { acquired: true };
+		const state = await readLockState(lockPath);
+		if (state.kind === "absent") continue;
+		if (state.kind === "unreadable") return { acquired: false, holder: null, abandoned: true };
+		return { acquired: false, holder: state.holder, abandoned: isAbandoned(state.holder) };
+	}
+	return { acquired: false, holder: null, abandoned: false };
+}
+
+let tempCounter = 0;
+
+/**
+ * 原子获取：先把持有者信息写进同目录的唯一临时文件，再 `link` 到锁路径。
+ *
+ * 不能用 `open(lockPath, "wx")` 后紧接着单独写内容 —— 那会让锁路径出现「存在但 0 字节」的
+ * 中间态，等待者读到空文件会把它判为「无法解释」并据为己有。link 是原子的：锁路径要么不存在，
+ * 要么内容是完整的 JSON。
+ */
+async function writeExclusive(lockPath: string, info: LockInfo): Promise<boolean> {
+	tempCounter += 1;
+	const tempPath = `${lockPath}.${process.pid}.${tempCounter}.tmp`;
+	try {
+		const handle = await open(tempPath, "wx");
+		try {
+			await handle.writeFile(JSON.stringify(info), "utf8");
+		} finally {
+			await handle.close();
+		}
+		try {
+			await link(tempPath, lockPath);
+			return true;
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code === "EEXIST") return false;
+			throw e;
+		}
+	} finally {
+		await unlink(tempPath).catch(() => {});
+	}
+}
+
+function holderInfo(op: string, now: number): LockInfo {
+	return { pid: process.pid, hostname: hostname(), startedAt: new Date(now).toISOString(), op };
+}
+
+/**
+ * 这把锁是否「已被遗弃」（没有任何人会释放它）。
+ * - 记录无法解释：没有持有者能续约，也没人能释放 —— 遗弃。
+ * - 同 host 且进程已死：持有者永远不会再释放它 —— 遗弃（这是唯一能确定的遗弃情形）。
+ * - 跨 host：存活状况不可知 —— 一律按活持有者处理，绝不接管。
+ */
+function isAbandoned(holder: LockInfo | null): boolean {
+	if (holder === null) return true;
+	return holder.hostname === hostname() && !isProcessAlive(holder.pid);
+}
+
+/**
+ * 只在锁仍是自己持有的情况下删除；否则留给真正的持有者。
+ * 记录读不懂时也**不删** —— 那是别人的状态（或需要人工处理的状态），不该由我们清理。
+ */
+async function releaseLock(lockPath: string): Promise<void> {
+	const state = await readLockState(lockPath);
+	if (state.kind === "unreadable") return;
+	if (state.kind === "held" && !isOwnRecord(state.holder)) return;
+	await rm(lockPath, { force: true });
+}
+
+function isOwnRecord(holder: LockInfo): boolean {
+	return holder.pid === process.pid && holder.hostname === hostname();
+}
+
+/** 等待获取锁（轮询 pollMs，默认 50ms）；超时或被遗弃时抛 MemoryLockedError。 */
+export async function withLock<T>(
+	lockPath: string,
+	op: string,
+	options: LockOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	const clock = options.now ?? Date.now;
+	const info = holderInfo(op, clock());
+	const deadline = clock() + options.timeoutMs;
+
+	for (;;) {
+		const outcome = await acquireOnce(lockPath, info);
+		if (outcome.acquired) break;
+		// 没人能释放它 → 等下去毫无意义；立刻给出可操作的错误，而不是耗满 timeout
+		if (outcome.abandoned) throw new MemoryLockedError(lockPath, outcome.holder, op, true);
+		if (clock() >= deadline) throw new MemoryLockedError(lockPath, outcome.holder, op, false);
+		await sleep(options.pollMs ?? 50);
+	}
+
+	try {
+		return await fn();
+	} finally {
+		await releaseLock(lockPath);
+	}
+}
+
+/**
+ * 只尝试一次，不等待。
+ * 活持有者占用 → 返回 null（调用方跳过本轮）；被遗弃的锁 → **抛错而不是返回 null** ——
+ * 它不会自愈，静默跳过只会让 extract 之类的后台任务永远不再运行且毫无提示。
+ */
+export async function tryWithLock<T>(
+	lockPath: string,
+	op: string,
+	options: LockOptions,
+	fn: () => Promise<T>,
+): Promise<T | null> {
+	const clock = options.now ?? Date.now;
+	const outcome = await acquireOnce(lockPath, holderInfo(op, clock()));
+	if (!outcome.acquired) {
+		if (outcome.abandoned) throw new MemoryLockedError(lockPath, outcome.holder, op, true);
+		return null;
+	}
+	try {
+		return await fn();
+	} finally {
+		await releaseLock(lockPath);
+	}
+}

package/src/index-source.ts

@@ -0,0 +1,186 @@
+import * as sdk from "@earendil-works/pi-coding-agent";
+
+/**
+ * 索引 section 的名字（spec §9.1）。pi 要求 section 名匹配 `/^[a-z][a-z0-9_-]*$/`
+ * （0.99.2 `core/system-prompt.js`），渲染为 `<memory_index>…</memory_index>`。
+ */
+export const MEMORY_INDEX_SECTION = "memory_index";
+
+/**
+ * 重放录制值所需的最小 `SessionManager` 面（结构类型）。
+ *
+ * 本地类型是 pi-coding-agent **0.80.2**，它的 `ReadonlySessionManager` 没有
+ * `buildContextEntries`（0.99.2 才加），所以这里不 import SDK 的类型，而是按结构声明：
+ * 0.80.2 能过 `tsc`，0.99.2 的实例天然满足，测试也能直接塞假对象。
+ */
+export interface ReplayableSessionManager {
+	getEntries(): unknown[];
+	getLeafId(): string | null;
+	buildContextEntries?(entries: unknown[], leafId?: string | null): unknown[];
+	/**
+	 * 0.99.2 的实例方法（**无参**），返回 `{ entries, messages, thinkingLevel, model }`。
+	 * 宿主自己算 system 消息用的就是它（`session-manager.js:882`：
+	 * `getCurrentSystemMessage(this.buildSessionProjection().messages)`），所以它才是「模型当前
+	 * 看到哪些 system 消息」的权威来源。本地类型是 0.80.2（没有这个方法）—— 因此声明为可选 +
+	 * 运行时特性探测，不得 import SDK 的类型。
+	 */
+	buildSessionProjection?(): { messages?: unknown[] } | undefined;
+}
+
+/** 可注入的转换函数（测试用；生产路径从 SDK 包根动态取）。 */
+export interface ReplayOpts {
+	sessionEntryToContextMessages?: (entry: unknown) => unknown[];
+}
+
+/**
+ * 脱掉宿主为 section 值加的一层包裹（R42）。
+ *
+ * 0.99.2 `core/system-prompt.js` 把每个非 `preamble` section 渲染成
+ * `<${name}>\n${content}\n</${name}>` 之后才写进 transcript；`sessionEntryToContextMessages`
+ * 原样返回录制消息，所以重放拿到的是**带标签**的值。直接回写成 `options.sections[name]`
+ * 会被宿主二次包裹：`wrap(wrap(x)) !== wrap(x)` —— resume/fork/reload 第一轮就产生 patch
+ *（D13/D14 的头部字节恒等失效），内层闭合标签还会提前闭合外层标签。
+ *
+ * 只脱一层；不匹配（裸值、老 session、内容碰巧含标签）原样返回。
+ */
+export function unwrapSectionValue(value: string): string {
+	const prefix = `<${MEMORY_INDEX_SECTION}>\n`;
+	const suffix = `\n</${MEMORY_INDEX_SECTION}>`;
+	if (value.length >= prefix.length + suffix.length && value.startsWith(prefix) && value.endsWith(suffix)) {
+		return value.slice(prefix.length, value.length - suffix.length);
+	}
+	return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * 按 pi 的 patch 语义重放 transcript 里的 system 消息，得到「模型当前看到的 sections」。
+ *
+ * - `value === null` → **删除**该 section（pi 用 null 表示「不存在」，
+ *   `diffSystemPromptSections` 对「上一状态有、当前状态没有」正是生成 `patch[name] = null`）；
+ * - 字符串 → 覆盖值，并**保留首次插入位置**（`Map.set` 对已存在的键不改位置）——
+ *   折叠路径 `getCurrentSystemMessage` 按顺序重放，位置本身就是语义的一部分。
+ */
+export function replaySystemSections(messages: unknown[]): Map<string, string> {
+	const sections = new Map<string, string>();
+	for (const message of messages) {
+		if (!isRecord(message) || message.role !== "system") continue;
+		const patch = message.sections;
+		if (!isRecord(patch)) continue;
+		for (const [name, value] of Object.entries(patch)) {
+			if (value === null) sections.delete(name);
+			else if (typeof value === "string") sections.set(name, value);
+		}
+	}
+	return sections;
+}
+
+/**
+ * 动态取 SDK 包根的 `sessionEntryToContextMessages`。
+ *
+ * 不能写成 `import { sessionEntryToContextMessages } from "…"`：本地类型是 0.80.2，
+ * 具名导入会让 `tsc` 直接报 `has no exported member`，而这个包**不得**动 peerDependencies /
+ * lockfile。取不到就返回 null，调用方回退磁盘读（spec §19 的退路）。
+ */
+function resolveConverter(): ((entry: unknown) => unknown[]) | null {
+	const candidate = (sdk as unknown as Record<string, unknown>).sessionEntryToContextMessages;
+	return typeof candidate === "function" ? (candidate as (entry: unknown) => unknown[]) : null;
+}
+
+/**
+ * 宿主投影里的 messages（0.99.2 的 `buildSessionProjection()`）。
+ *
+ * 不可用（没有该方法 / 抛错 / 返回值形状不对）时返回 `null`，调用方回落到下面的自实现重放。
+ * 与宿主同源很重要：双重 compaction 的保留边界、`context_edit` 的应用都由宿主决定，我们自己
+ * 复刻一份就会在极端会话上漂移（Plan C 终审 #4）。
+ */
+function projectionMessages(sm: Partial<ReplayableSessionManager>): unknown[] | null {
+	try {
+		// 特征探测也放进 try：宿主把该方法做成抛错的 getter / proxy 时同样只能回退，
+		// 不能让异常逃到 session_start。
+		if (typeof sm.buildSessionProjection !== "function") return null;
+		const messages = sm.buildSessionProjection()?.messages;
+		return Array.isArray(messages) ? messages : null;
+	} catch {
+		// 投影抛错（更老的 session 形状 / 宿主内部不变量不成立）：回落自实现重放
+		return null;
+	}
+}
+
+/**
+ * 自实现的 entry 重放（旧 SDK / 老 session 的退路）：`getEntries` → `buildContextEntries`
+ * → 逐条转成 context messages。任何一步不可得都返回 `null`：转换函数缺失（SDK 太旧）、
+ * sessionManager 形状不认识、`getEntries` 抛错。
+ */
+function replayEntryMessages(sm: Partial<ReplayableSessionManager>, opts?: ReplayOpts): unknown[] | null {
+	const toMessages = opts?.sessionEntryToContextMessages ?? resolveConverter();
+	if (!toMessages) return null;
+	if (typeof sm.getEntries !== "function" || typeof sm.getLeafId !== "function") return null;
+
+	let entries: unknown[] = [];
+	try {
+		const raw = sm.getEntries();
+		if (Array.isArray(raw)) entries = raw;
+	} catch {
+		return null;
+	}
+
+	let leafId: string | null = null;
+	try {
+		leafId = sm.getLeafId();
+	} catch {
+		// Finding 2 / R43：这个函数在 index.ts 的 session_start 路径上被调用，抛错会让整个
+		// session_start 失败 → memory 工具整个会话不注册。拿不到 leaf 就退化成「没有 branch」：
+		// 用全部 entry 重放，多出来的 system patch 只会被后面的覆盖或删掉。
+	}
+	if (typeof sm.buildContextEntries === "function") {
+		try {
+			const built = sm.buildContextEntries(entries, leafId);
+			if (Array.isArray(built)) entries = built;
+		} catch {
+			// 解析不出当前分支就用全部 entry：多出来的 system patch 只会被后面的覆盖或删掉
+		}
+	}
+
+	const messages: unknown[] = [];
+	for (const e of entries) {
+		try {
+			const converted = toMessages(e);
+			if (Array.isArray(converted)) messages.push(...converted);
+		} catch {
+			// 单条 entry 的形状不认识：跳过它，别让整次重放失败
+		}
+	}
+
+	return messages;
+}
+
+/**
+ * 从 transcript 里取出**录制的**索引值（D14：resume / fork / reload 必须用它，
+ * 否则被恢复会话的 system prompt 头部会被改写，折叠路径下其后的整段对话全部失去缓存）。
+ *
+ * **优先用宿主的 `buildSessionProjection()`** —— 与宿主算 `getCurrentSystemMessage` 同源；
+ * 拿不到（0.80.2 / 更老的 session / 投影抛错）才回落到自实现的 entry 重放（Plan C 终审 #4）。
+ *
+ * 两条路径都不可得时返回 `null`，由调用方回退磁盘读：SDK 太旧（既无投影也无转换函数）、
+ * sessionManager 形状不认识（含 `buildSessionProjection()` 的返回值里没有 `messages` 数组，
+ * `projectionMessages` 对非数组返回 `null`）、`buildSessionProjection` / `getEntries` 抛错、重放后没有这个键、
+ * 或该键被 `null` patch 删除。**单条 entry 的形状不认识**不会让整次重放失败：那一条被跳过
+ *（见 `replayEntryMessages`），其余 entry 照常重放 —— 它不会变成 `null` 返回值。
+ * **绝不把 `null` 当录制值返回**（spec §9.1 的 null 陷阱）。
+ *
+ * 返回值是**裸值**：宿主把 section 渲染成 `<memory_index>…</memory_index>` 后才写进
+ * transcript，所以这里要脱掉那一层再回写（R42 / `unwrapSectionValue`）。
+ */
+export function readRecordedMemoryIndex(sessionManager: unknown, opts?: ReplayOpts): string | null {
+	if (!isRecord(sessionManager)) return null;
+	const sm = sessionManager as unknown as Partial<ReplayableSessionManager>;
+	const messages = projectionMessages(sm) ?? replayEntryMessages(sm, opts);
+	if (messages === null) return null;
+
+	const recorded = replaySystemSections(messages).get(MEMORY_INDEX_SECTION);
+	return typeof recorded === "string" ? unwrapSectionValue(recorded) : null;
+}