@zhushanwen/pi-system-prompt-trace 0.1.8 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt-trace",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "System prompt trace extension: appends taiji:system-prompt entries to the session JSONL whenever the effective system prompt is established or changes",
   "type": "module",
   "main": "index.ts",

package/src/__tests__/baseline.a12.test.ts

@@ -72,6 +72,8 @@ function makeHarness(initialPrompt: string, opts?: { noSessionFile?: boolean }):
 
 	const env: TraceEnv = {
 		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
+		// F1b：A12 聚焦基线恢复，不涉回落事实（回落专测在 a11 / wiring）
+		getPresetFallback: () => undefined,
 	};
 
 	const ctx: TraceContext = {

package/src/__tests__/index-wiring.test.ts

@@ -20,7 +20,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
+import { isSystemPromptTraceEntryData, PRESET_FALLBACK_ENV_KEYS, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
 import type { SystemPromptTraceEntryData } from "../types.js";
 
 // trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
@@ -337,6 +337,61 @@ describe("index.ts wiring SDK 契约", () => {
 		});
 	});
 
+	it("F1b wiring：process.env 两键齐备 → entry 带 presetFallback（from/to）；既有字段不削弱", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		process.env[PRESET_FALLBACK_ENV_KEYS.FROM] = "custom:gone-uuid";
+		process.env[PRESET_FALLBACK_ENV_KEYS.TO] = "builtin:full";
+		try {
+			ext(h.pi);
+			const ctx = createCtx(() => P1, "sess-w-fb");
+			await emit(h, "session_start", { type: "session_start", reason: "startup" }, ctx);
+			await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+		} finally {
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		}
+		expect(h.entries).toHaveLength(1);
+		expect(entryData(h, 0).presetFallback).toEqual({ from: "custom:gone-uuid", to: "builtin:full" });
+		expect(entryData(h, 0)).toMatchObject({
+			version: 1,
+			reason: "initial",
+			fullText: P1,
+			charCount: P1.length,
+			hash: computePromptHash(P1),
+		});
+	});
+
+	it("F1b wiring：env 未注入 / 两键为空串（runtime 显式清除）→ entry 不含 presetFallback（无假披露）", async () => {
+		const ext = await loadExtension();
+		// 态 1：未注入
+		delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+		delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		const hAbsent = createWiringHarness();
+		ext(hAbsent.pi);
+		const ctxAbsent = createCtx(() => P1, "sess-w-fb-absent");
+		await emit(hAbsent, "session_start", { type: "session_start", reason: "startup" }, ctxAbsent);
+		await emit(hAbsent, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctxAbsent);
+		expect(hAbsent.entries).toHaveLength(1);
+		expect(Object.prototype.hasOwnProperty.call(entryData(hAbsent, 0), "presetFallback")).toBe(false);
+
+		// 态 2：空串（runtime 未回落时写空串显式清除继承值）——不得当回落事实
+		process.env[PRESET_FALLBACK_ENV_KEYS.FROM] = "";
+		process.env[PRESET_FALLBACK_ENV_KEYS.TO] = "";
+		const hEmpty = createWiringHarness();
+		try {
+			ext(hEmpty.pi);
+			const ctxEmpty = createCtx(() => P1, "sess-w-fb-empty");
+			await emit(hEmpty, "session_start", { type: "session_start", reason: "startup" }, ctxEmpty);
+			await emit(hEmpty, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctxEmpty);
+		} finally {
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.FROM];
+			delete process.env[PRESET_FALLBACK_ENV_KEYS.TO];
+		}
+		expect(hEmpty.entries).toHaveLength(1);
+		expect(Object.prototype.hasOwnProperty.call(entryData(hEmpty, 0), "presetFallback")).toBe(false);
+	});
+
 	it("getSystemPrompt 抛错 → handler 吞掉不写 entry（留痕是诊断旁路，不影响 agent 主流程）", async () => {
 		const ext = await loadExtension();
 		const h = createWiringHarness();

package/src/__tests__/trace.a11.test.ts

@@ -18,7 +18,7 @@ import { describe, expect, it } from "vitest";
 import { createSystemPromptTrace } from "../trace.js";
 import type { SystemPromptTrace, TraceContext, TraceEnv } from "../trace.js";
 import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
-import type { SystemPromptTraceEntryData, SwitchStash } from "../types.js";
+import type { PresetFallbackFact, SystemPromptTraceEntryData, SwitchStash } from "../types.js";
 
 // trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
 const computePromptHash = (text: string): string =>
@@ -37,13 +37,15 @@ interface Harness {
 	newLogic(): SystemPromptTrace;
 }
 
-function makeHarness(initialPrompt: string): Harness {
+function makeHarness(initialPrompt: string, presetFallback?: PresetFallbackFact): Harness {
 	const entries: SystemPromptTraceEntryData[] = [];
 	let prompt = initialPrompt;
 	const stash: SwitchStash = { pending: null };
 	// A11 不涉文件路径：三档基线全部 miss（直读 / fork prev 文件路径均不可读），隔离验证时机/去重/映射逻辑
 	const env: TraceEnv = {
 		readLastPromptFromFile: () => null,
+		// F1b：默认无回落事实；需要时经参数注入（进程 env 语义的 fake）
+		getPresetFallback: () => presetFallback,
 	};
 	const ctx: TraceContext = {
 		getSystemPrompt: () => prompt,
@@ -134,6 +136,34 @@ describe("A11 留痕时机与去重", () => {
 		expect(entry.parentVersionDiffSummary).toContain("+ [Available Models]");
 	});
 
+	it("F1b 模式回落事实：env 携带 from/to → 本进程每条 entry 均带 presetFallback（resume 快照与 change 一致），既有字段不削弱", () => {
+		const fact: PresetFallbackFact = { from: "custom:gone-uuid", to: "builtin:full" };
+		const h = makeHarness(P1, fact);
+		h.logic.onSessionStart("resume", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx); // v1 resume
+		h.setPrompt(P2);
+		h.logic.onTurnStart(h.ctx); // v2 change
+		expect(h.entries).toHaveLength(2);
+		expect(h.entries[0]?.presetFallback).toEqual(fact);
+		expect(h.entries[1]?.presetFallback).toEqual(fact);
+		// 既有形状与语义不受影响
+		expect(h.entries[0]).toMatchObject({
+			version: 1, reason: "resume", fullText: P1, charCount: P1.length, hash: computePromptHash(P1),
+		});
+		expect(h.entries[1]).toMatchObject({
+			version: 2, reason: "change", fullText: P2, charCount: P2.length, hash: computePromptHash(P2),
+		});
+	});
+
+	it("F1b 无回落（getPresetFallback → undefined）→ entry 无 presetFallback 字段（形状向后兼容）", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+		expect(h.entries[0]?.presetFallback).toBeUndefined();
+		expect(Object.prototype.hasOwnProperty.call(h.entries[0], "presetFallback")).toBe(false);
+	});
+
 	it("prompt 变回旧值再写 change v3（时间线保留真实历史，只对当前版本去重）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);

package/src/index.ts

@@ -19,6 +19,7 @@ import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 import { readLastPromptFromSessionFile } from "./baseline.js";
 import { createSystemPromptTrace } from "./trace.js";
 import type { TraceContext, TraceEnv } from "./trace.js";
+import { readPresetFallbackFromEnv } from "./types.js";
 import type { SwitchStash } from "./types.js";
 
 // 模块级单例：session_before_switch（旧 runtime）→ session_start（新 runtime）之间传递
@@ -45,6 +46,9 @@ export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
 
 	const env: TraceEnv = {
 		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
+		// F1b（E4 trace 披露面）：模式回落事实由 runtime 经 spawn 出站 env 携带。
+		// 工厂调用时读一次（进程 env 生命期内不变）；未回落 → 空串 → undefined。
+		getPresetFallback: () => readPresetFallbackFromEnv(),
 	};
 
 	const logic = createSystemPromptTrace(env, switchStash);

package/src/trace.ts

@@ -20,6 +20,7 @@ const logger = getLogger("pi-system-prompt-trace");
 import { summarizePromptDiff } from "./diff.js";
 import { mapReasonForFirstWrite, SYSTEM_PROMPT_CUSTOM_TYPE } from "./types.js";
 import type {
+	PresetFallbackFact,
 	PromptBaseline,
 	SwitchStash,
 	SystemPromptTraceEntryData,
@@ -38,6 +39,13 @@ export interface TraceContext {
 /** 文件系统侧依赖（wiring 用真实 fs；测试注入临时目录实现）。 */
 export interface TraceEnv {
 	readLastPromptFromFile(filePath: string): PromptBaseline | null;
+	/**
+	 * 本次 pi 进程启动时的模式回落事实（F1b，E4 trace 披露面）；未回落 / 未注入 → undefined。
+	 *
+	 * 进程 env 在生命期内不变，故工厂构造时读一次即可；为空字符串（runtime 的「显式
+	 * 清除」形态）时同样返回 undefined——不得把空串当回落事实。
+	 */
+	getPresetFallback(): PresetFallbackFact | undefined;
 }
 
 export interface SystemPromptTrace {
@@ -65,6 +73,10 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 	let sessionStartReason: SessionStartEvent["reason"] | null = null;
 	let baseline: PromptBaseline | null = null;
 	let current: CurrentPrompt | null = null;
+	// F1b（设计 `mode-system-composer-density` §7.5 E4 trace 披露面）：
+	// 本次 pi 进程的模式回落事实由 spawn 出站 env 携带，进程生命期内恒定，构造时读一次。
+	// 未回落 / 未注入 → undefined，entry 的 presetFallback 字段不出现（既有形状向后兼容）。
+	const presetFallback = env.getPresetFallback();
 
 	const write = (
 		ctx: TraceContext,
@@ -84,6 +96,11 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 		if (parentFullText !== undefined) {
 			data.parentVersionDiffSummary = summarizePromptDiff(parentFullText, text);
 		}
+		// 回落事实随本进程写出的每条 entry 携带：本次 pi 运行确实以回落档启动，
+		// resume 快照与后续 change 同属该运行，披露一致（事件语义 = 本次运行口径）。
+		if (presetFallback !== undefined) {
+			data.presetFallback = presetFallback;
+		}
 		ctx.appendEntry(SYSTEM_PROMPT_CUSTOM_TYPE, data);
 	};
 

package/src/types.ts

@@ -11,6 +11,53 @@ import type { SessionStartEvent } from "@earendil-works/pi-coding-agent";
 /** 留痕 entry 的 customType（taiji: 前缀 = taiji 自定义命名空间）。 */
 export const SYSTEM_PROMPT_CUSTOM_TYPE = "taiji:system-prompt";
 
+/**
+ * 模式回落事实 env 名（字面量镜像 `packages/shared/src/constants.ts` 的
+ * `PRESET_FALLBACK_ENV_KEYS`）。
+ *
+ * extension 独立发布体系不依赖 `@taiji/shared`，只能按字面量镜像——单侧改名即断链
+ * （消息见 write 产出的 `presetFallback` 字段消失）。一致性由机器守卫断言：
+ * `.githooks/check_env_whitelist_sync.py` 规则 3 A8（漂移即红）。写入方 =
+ * `packages/runtime/src/services/session/launch-params.ts` 的 `buildPresetFallbackEnv`。
+ */
+export const PRESET_FALLBACK_ENV_KEYS = {
+	FROM: "TAIJI_PRESET_FALLBACK_FROM",
+	TO: "TAIJI_PRESET_FALLBACK_TO",
+} as const;
+
+/**
+ * 模式回落事实（F1b，设计 `mode-system-composer-density` §7.5 E4
+ * 的 trace 披露面）。
+ *
+ * 语义 = 本次 pi 进程启动时，sidecar 里的模式定义已不可得，runtime 已回落
+ * `builtin:full` 启动（工具面从模式的受限面弹回全工具）——记录在 trace entry 里，
+ * 事后审计从 `taiji:system-prompt` 即可得知「提示词为何变了」。
+ */
+export interface PresetFallbackFact {
+	/** 原（悬空）模式 id。 */
+	from: string;
+	/** 回落目标模式 id（现行恒 `builtin:full`）。 */
+	to: string;
+}
+
+/**
+ * 从进程 env 读取模式回落事实（wiring 侧唯一 env 读取点；trace.ts 逻辑经 DI 消费）。
+ *
+ * - FROM 非空 → 返回 `{ from, to }`（TO 缺失时给空串——形状稳定，不抛错）；
+ * - FROM 缺失 / 空串 → undefined（未回落，或未注入；空串是 runtime 的「显式清除」
+ *   语义，见 `buildPresetFallbackEnv`）。
+ *
+ * 不抛错：env 是外部输入，任何形态异常都退化为「无回落事实」，不阻断留痕。
+ */
+export function readPresetFallbackFromEnv(
+	env: NodeJS.ProcessEnv = process.env,
+): PresetFallbackFact | undefined {
+	const from = env[PRESET_FALLBACK_ENV_KEYS.FROM];
+	if (typeof from !== "string" || from === "") return undefined;
+	const to = env[PRESET_FALLBACK_ENV_KEYS.TO];
+	return { from, to: typeof to === "string" ? to : "" };
+}
+
 /** 落盘 reason 枚举（initial/resume/change，对齐 DSH request/header 语义，设计 D2）。 */
 export type TraceReason = "initial" | "resume" | "change";
 
@@ -27,6 +74,12 @@ export interface SystemPromptTraceEntryData {
 	charCount: number;
 	/** 与上一版的行级 diff 摘要；首条留痕（无 parent）时缺省。 */
 	parentVersionDiffSummary?: string;
+	/**
+	 * 模式回落事实（F1b，E4 trace 披露面）：本次 pi 进程以「模式已删除 → 回落
+	 * builtin:full」启动时出现；未回落（正常启动）时**字段不出现**——既有 entry
+	 * 形状向后兼容。见 `PresetFallbackFact`。
+	 */
+	presetFallback?: PresetFallbackFact;
 }
 
 /** 跨重启恢复的 hash 基线（三档解析统一产自 session JSONL 留痕 entry 直读）。 */
@@ -55,6 +108,12 @@ export function isSystemPromptTraceEntryData(value: unknown): value is SystemPro
 	const reason = value["reason"];
 	const fullText = value["fullText"];
 	const charCount = value["charCount"];
+	// 可选字段（F1b）：存在时须为 { from: string, to: string }；缺失合法（向后兼容）
+	const presetFallback = value["presetFallback"];
+	if (presetFallback !== undefined) {
+		if (!isRecord(presetFallback)) return false;
+		if (typeof presetFallback["from"] !== "string" || typeof presetFallback["to"] !== "string") return false;
+	}
 	return (
 		typeof version === "number" &&
 		Number.isFinite(version) &&