@xprnvd/pi-context-view 0.0.0-stage → 0.8.0

package/src/replay.ts

@@ -0,0 +1,234 @@
+/**
+ * Measurement inputs from recorded system state, plus the live prompt/tool
+ * fallback when no state was recorded. Usage and Injections share these helpers.
+ */
+import type { BuildSystemPromptOptions, ToolInfo } from "@earendil-works/pi-coding-agent";
+import { getCurrentSystemMessage, type Tool } from "@earendil-works/pi-ai";
+
+import {
+	analyzeSystemPrompt,
+	type DeletedSection,
+	type PromptChanges,
+	type PromptOptionsSlice,
+	SYSTEM_PROMPT_ITEM_ID,
+	type ToolSlice,
+	UNREGISTERED_TOOL_SOURCE,
+} from "./measure.ts";
+import { buildSnapshot, type InjectionItem, type InjectionSnapshot, type RequestChange } from "./model.ts";
+import type { PromptSourceSlice } from "./prompt-additions.ts";
+import type { RequestMessage, SystemChange } from "./snapshot.ts";
+import { type SystemMessage, systemMessageText } from "./transcript.ts";
+
+/** Inputs for an on-demand pi-native prompt/tool fallback without recorded system state. */
+export interface NativeSnapshotInput {
+	systemPrompt: string;
+	/** Prompt options; `hiddenTools` names the tools Pi leaves out of requests. */
+	options: BuildSystemPromptOptions;
+	allTools: readonly ToolInfo[];
+	activeToolNames: readonly string[];
+	/** Loaded extension provenance: labels path extensions and guesses who appended prompt text. */
+	promptSources?: readonly PromptSourceSlice[];
+	/** Forced prompt of the request, measured instead of the prompt; tool changes still apply. */
+	forcedPrompt?: string;
+}
+
+/** Inputs for Usage's branch-local prompt/tool estimate. */
+export interface UsageSnapshotInput extends NativeSnapshotInput {
+	/** Current branch messages; their system messages supply the recorded state. */
+	messages: readonly RequestMessage[];
+	/** Request-only system changes of the latest request, applied after the replayed state. */
+	systemChanges?: readonly SystemChange[];
+}
+
+/** System state a request carried, with what its changes touched. */
+export interface RequestSystemState {
+	readonly state: Pick<SystemMessage, "content" | "sections">;
+	readonly declarations: readonly Tool[];
+	readonly prompt: PromptChanges;
+	readonly tools: ReadonlyMap<string, Exclude<RequestChange, "deleted" | "forced">>;
+	readonly deletedTools: readonly Tool[];
+}
+
+/** Build a view-local pi-native fallback without starting a capture; the tools Pi hides are left out and counted. */
+export function buildNativeSnapshot(input: NativeSnapshotInput): InjectionSnapshot {
+	const options = copyPromptOptions(input.options);
+	const tools = splitHiddenTools(captureActiveTools(input.allTools, input.activeToolNames, input.options),
+		input.options.hiddenTools);
+	const prompt = input.forcedPrompt ?? input.systemPrompt;
+	const items = analyzeSystemPrompt(prompt, options, tools.declared, { sources: input.promptSources });
+	return { ...buildSnapshot(markForcedPrompt(items, input.forcedPrompt)), hiddenTools: tools.hiddenNames };
+}
+
+/**
+ * Measure the branch's replayed prompt and tools instead of today's loader
+ * prompt/tools, with the latest request's system changes applied once. A forced
+ * prompt replaces every section, so only tool changes reach it. The tools Pi
+ * currently hides from the model are left out. Only a branch with no recorded
+ * system message yet uses the live fallback.
+ */
+export function buildUsageSnapshot(input: UsageSnapshotInput): InjectionSnapshot {
+	const forced = input.forcedPrompt;
+	const base = getCurrentSystemMessage(input.messages);
+	// Undefined means a branch with no recorded system message yet, not an explicitly empty state
+	if (base === undefined) return buildNativeSnapshot(input);
+	const request = applySystemChanges(base, input.systemChanges ?? []);
+	const declarations = splitHiddenTools(request.declarations, input.options.hiddenTools);
+	const tools = replayedToolSlices(request.state, declarations.declared, input.allTools);
+	const options = copyPromptOptions(input.options);
+	const items = analyzeSystemPrompt(forced ?? systemMessageText(request.state), {
+		...options,
+		// Current loader overrides are not evidence of what this branch recorded.
+		customPrompt: undefined, sections: undefined,
+		// The replayed layout locates inline or unwrapped request sections; Usage marks no section changes
+	}, tools, { sources: input.promptSources }, forced === undefined ? { replayed: request.prompt.replayed } : {});
+	return { ...buildSnapshot(markForcedPrompt(items, forced)), hiddenTools: declarations.hiddenNames };
+}
+
+/**
+ * The tools Pi declares to the model, and the names of `tools` it hid from it:
+ * they stay active and callable through another tool, such as codemode.
+ * `hiddenTools` names the hidden ones, as Pi's prompt options report them.
+ */
+export function splitHiddenTools<T extends { readonly name: string }>(
+	tools: readonly T[],
+	hiddenTools: readonly string[] | undefined,
+): { readonly declared: T[]; readonly hiddenNames: string[] } {
+	const hidden = new Set(hiddenTools);
+	const declared: T[] = [];
+	const hiddenNames: string[] = [];
+	for (const tool of tools) {
+		if (hidden.has(tool.name)) hiddenNames.push(tool.name);
+		else declared.push(tool);
+	}
+	return { declared, hiddenNames };
+}
+
+/** Items with the System Prompt marked `forced` when the request carried a forced prompt. */
+export function markForcedPrompt(items: InjectionItem[], forced: string | undefined): InjectionItem[] {
+	if (forced === undefined) return items;
+	return items.map((item) => item.id === SYSTEM_PROMPT_ITEM_ID ? { ...item, change: "forced" } : item);
+}
+
+/** Apply content, section, and tool changes in capture order to a replayed system state. */
+export function applySystemChanges(base: SystemMessage, changes: readonly SystemChange[]): RequestSystemState {
+	let content = contentText(base.content);
+	const sections: Record<string, string | null> = { ...base.sections };
+	const sectionChanges = new Map<string, Exclude<RequestChange, "deleted" | "forced">>();
+	const deletedSections: DeletedSection[] = [];
+	const declarations = [...(base.toolsAdded ?? [])];
+	const toolChanges = new Map<string, Exclude<RequestChange, "deleted" | "forced">>();
+	const deletedTools: Tool[] = [];
+	for (const change of changes) {
+		switch (change.type) {
+			case "content":
+				content = change.text;
+				// Pi renders plain content before the first section, inside the measured Preamble
+				sectionChanges.set("preamble", "modified");
+				break;
+			case "section": {
+				const previous = sections[change.name];
+				if (change.text === null) {
+					if (typeof previous === "string") deletedSections.push({ name: change.name, text: previous });
+					delete sections[change.name];
+					break;
+				}
+				sectionChanges.set(change.name, typeof previous === "string" ? "modified" : "added");
+				sections[change.name] = change.text;
+				break;
+			}
+			case "tool": {
+				const index = declarations.findIndex((tool) => tool.name === change.name);
+				if (change.declaration === null) {
+					if (index !== -1) deletedTools.push(...declarations.splice(index, 1));
+				} else if (index === -1) {
+					declarations.push(change.declaration);
+					toolChanges.set(change.name, "added");
+				} else {
+					declarations[index] = change.declaration;
+					toolChanges.set(change.name, "modified");
+				}
+				break;
+			}
+		}
+	}
+	return {
+		state: { content, sections },
+		declarations,
+		prompt: { sections: sectionChanges, deleted: deletedSections, replayed: { content, sections } },
+		tools: toolChanges,
+		deletedTools,
+	};
+}
+
+/** Copy the prompt-options slice used by measurement, without shared nested references. */
+export function copyPromptOptions(options: BuildSystemPromptOptions): PromptOptionsSlice {
+	return {
+		homeDir: process.env.HOME,
+		customPrompt: options.customPrompt,
+		sections: options.sections === undefined ? undefined : { ...options.sections },
+	};
+}
+
+/**
+ * Snapshot the final active tool set with provenance and payload definitions.
+ * Keep pi's active-tool order: it decides which tool owns a guideline bullet
+ * that several tools declare.
+ */
+export function captureActiveTools(
+	allTools: readonly ToolInfo[],
+	activeToolNames: readonly string[],
+	options: { readonly toolSnippets?: Readonly<Record<string, string>> },
+): ToolSlice[] {
+	const byName = new Map(allTools.map((tool) => [tool.name, tool]));
+	return [...new Set(activeToolNames)]
+		.map((name) => byName.get(name))
+		.filter((tool) => tool !== undefined)
+		.map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			parametersJson: JSON.stringify(tool.parameters ?? {}),
+			snippet: options.toolSnippets?.[tool.name],
+			guidelines: normalizeGuidelines(tool.promptGuidelines),
+			source: tool.sourceInfo.source,
+			sourcePath: tool.sourceInfo.path,
+		}));
+}
+
+/**
+ * Tool slices for recorded declarations. The declaration supplies name,
+ * description, and schema; the prompt snippet comes from the recorded `tools`
+ * section. Current registration metadata supplies only guidelines and
+ * provenance; an unregistered tool stays unattributed.
+ */
+export function replayedToolSlices(
+	state: Pick<SystemMessage, "sections">,
+	declarations: readonly Tool[],
+	allTools: readonly ToolInfo[],
+): ToolSlice[] {
+	const registered = new Map(allTools.map((tool) => [tool.name, tool]));
+	const snippetLines = state.sections?.tools?.split("\n") ?? [];
+	return declarations.map((tool) => {
+		const metadata = registered.get(tool.name);
+		const snippetLine = snippetLines.find((line) => line.startsWith(`- ${tool.name}: `));
+		return {
+			name: tool.name,
+			description: tool.description,
+			parametersJson: JSON.stringify(tool.parameters),
+			snippet: snippetLine?.slice(`- ${tool.name}: `.length),
+			guidelines: normalizeGuidelines(metadata?.promptGuidelines),
+			source: metadata?.sourceInfo.source ?? UNREGISTERED_TOOL_SOURCE,
+			sourcePath: metadata?.sourceInfo.path,
+		};
+	});
+}
+
+/** Plain text of system content; text blocks join with a newline, as Pi renders them. */
+function contentText(content: SystemMessage["content"]): string {
+	return typeof content === "string" ? content : content.map((block) => block.text).join("\n");
+}
+
+/** Normalize the string-or-array promptGuidelines field to an owned array. */
+function normalizeGuidelines(guidelines: string | string[] | undefined): string[] {
+	if (guidelines === undefined) return [];
+	return Array.isArray(guidelines) ? [...guidelines] : [guidelines];
+}

package/src/settings.ts

@@ -0,0 +1,62 @@
+/**
+ * Read Pi's settings for the probe preconditions and the Usage map's
+ * auto-compaction reserve.
+ */
+import { type CacheWarmingMode, type ExtensionAPI, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** Identifies the `compaction.modelOverrides` entry pi would apply to a request. */
+export interface CompactionModel {
+	readonly provider: string;
+	readonly id: string;
+}
+
+/**
+ * Wrap Pi's live merged settings, including unsaved runtime changes, so both
+ * the probe preconditions and the Usage map read the same source.
+ */
+export function readLiveSettings(pi: ExtensionAPI): SettingsManager {
+	return SettingsManager.inMemory(pi.getSettings());
+}
+
+/**
+ * Read the global-only warming mode; a project override must not hide idle warming.
+ * Extensions cannot see an SDK host's custom agent directory, so this reads Pi's
+ * default one, which honors `PI_CODING_AGENT_DIR`.
+ */
+export function readGlobalCacheWarmingMode(cwd: string): CacheWarmingMode {
+	const settings = SettingsManager.create(cwd, undefined, { projectTrusted: false });
+	if (settings.drainErrors().length > 0) throw new Error("Pi settings could not be read.");
+	return settings.getCacheWarmingMode();
+}
+
+/**
+ * Read the auto-compaction reserve from Pi's live settings, or undefined when
+ * auto-compaction is disabled. Read at view-open time because `enabled` and the
+ * model can change at runtime.
+ */
+export function readAutoCompactReserveTokens(pi: ExtensionAPI, model?: CompactionModel): number | undefined {
+	try {
+		return resolveAutoCompactReserveTokens(readLiveSettings(pi), model);
+	} catch {
+		// Unreadable settings degrade to a map without the buffer, not a failed view.
+		return undefined;
+	}
+}
+
+/**
+ * Resolve the reserve pi would apply to `model`: its `compaction.modelOverrides`
+ * entry, else the ordinary `compaction.reserveTokens`, else pi's default.
+ * Returns undefined when auto-compaction is disabled or a setting is invalid.
+ */
+export function resolveAutoCompactReserveTokens(
+	settings: SettingsManager,
+	model?: CompactionModel,
+): number | undefined {
+	try {
+		if (!settings.getCompactionEnabled()) return undefined;
+		return settings.getCompactionReserveTokens(model);
+	} catch {
+		// Pi rejects invalid reserve values; show no buffer rather than a wrong one.
+		return undefined;
+	}
+}

package/src/snapshot.ts

@@ -0,0 +1,188 @@
+/**
+ * Request snapshots and the SnapshotStore that decouples capture from its
+ * consumers (doc/architecture/capture.md). Capture publishes; views read.
+ * Imports Pi types only, so the store runs and is tested without a Pi runtime.
+ */
+import type { Tool } from "@earendil-works/pi-ai";
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+/** What produced the captured request: a real agent run or the silent probe. */
+export type CaptureOrigin = "real-turn" | "synthetic-probe";
+
+/** One message as Pi passes it to context handlers. */
+export type RequestMessage = ContextEvent["messages"][number];
+
+/**
+ * Best-effort source of a conversation change. Neither field proves
+ * ownership: any extension can reuse them. Both absent means unattributed.
+ * For a modification or deletion they describe the affected message, which
+ * names its owner, not the extension that edited it.
+ */
+export interface ChangeAttribution {
+	/** `customType` of a custom message. */
+	readonly customType?: string;
+	/** Cooperative provenance from a custom message's `details`, which is never sent to the model. */
+	readonly provenance?: { readonly source: string; readonly reason?: string };
+}
+
+/**
+ * A request-only conversation edit. Modifications and deletions reference the
+ * source entry of their baseline message, so consumers can apply them to a later
+ * projection and drop them once the entry is gone. Retained messages are
+ * redacted: image data holds only a size marker, `textSignature` is removed, and
+ * thinking and tool-call signatures keep only their length.
+ */
+export type ConversationChange =
+	| { readonly type: "added"; readonly message: RequestMessage; readonly attribution: ChangeAttribution }
+	| {
+		readonly type: "modified";
+		readonly entryId: string;
+		readonly message: RequestMessage;
+		readonly attribution: ChangeAttribution;
+	}
+	| { readonly type: "deleted"; readonly entryId: string; readonly attribution: ChangeAttribution };
+
+/**
+ * A request-only change of the replayed system state:
+ *   content   the replayed plain content differs; `text` is the request's whole content
+ *   section   a section was added or changed; `null` text removes it
+ *   tool      a declaration was added or redefined; `null` removes it
+ */
+export type SystemChange =
+	| { readonly type: "content"; readonly text: string }
+	| { readonly type: "section"; readonly name: string; readonly text: string | null }
+	| { readonly type: "tool"; readonly name: string; readonly declaration: Tool | null };
+
+/** Structured request-only edits between the session projection and the captured request. */
+export interface StructuredChanges {
+	readonly conversation: readonly ConversationChange[];
+	readonly system: readonly SystemChange[];
+}
+
+/** Provider, API, and model that a paired request was dispatched to. */
+export interface Dispatch {
+	readonly provider: string;
+	readonly api: string;
+	readonly model: string;
+}
+
+/**
+ * Part of a provider message that the payload guard compares as one text unit:
+ *   system        system prompt or later system message text
+ *   user          user text, including converted custom messages and summaries
+ *   assistant     assistant text
+ *   tool-call     one tool call: its name and arguments
+ *   tool-result   one tool result's text
+ */
+export type MessagePart = "system" | "user" | "assistant" | "tool-call" | "tool-result";
+
+/** One changed line of a payload change: only in the payload (`added`) or only in the captured request (`removed`). */
+export interface PayloadChangeLine {
+	readonly type: "added" | "removed";
+	readonly text: string;
+}
+
+/**
+ * A payload difference the structured capture cannot explain:
+ *   payload-change        message text added, changed, or removed after the monitor,
+ *                         without structure or attribution
+ *   payload-tool-change   a declaration the payload adds, removes, or describes differently
+ *                         after the monitor; tools Pi hid are not removals
+ */
+export type GuardFinding =
+	| {
+		readonly type: "payload-change";
+		readonly change: "added" | "modified" | "deleted";
+		readonly part: MessagePart;
+		/** Changed lines; a modification lists only the lines that differ, ignoring whitespace. */
+		readonly lines: readonly PayloadChangeLine[];
+	}
+	| {
+		readonly type: "payload-tool-change";
+		readonly change: "added" | "modified" | "deleted";
+		readonly name: string;
+		/**
+		 * Changed description lines: every line the payload declares for an addition,
+		 * every captured line for a deletion, and only the lines that differ for a
+		 * modification, ignoring whitespace.
+		 */
+		readonly lines: readonly PayloadChangeLine[];
+	};
+
+/**
+ * Payload comparison state. Pending and incomplete mean the comparison is
+ * unavailable, never that the request had no payload changes. An incomplete result
+ * with `findings` compared only some channels: the findings hold, and `reason`
+ * names what was not compared.
+ */
+export type GuardResult =
+	| { readonly status: "pending" }
+	| { readonly status: "complete"; readonly dispatch: Dispatch; readonly findings: readonly GuardFinding[] }
+	| {
+		readonly status: "incomplete";
+		readonly reason: string;
+		readonly dispatch?: Dispatch;
+		readonly findings?: readonly GuardFinding[];
+	};
+
+/** One captured request. Raw message content is process-local; never log or persist it. */
+export interface RequestSnapshot {
+	/** Local capture number; later captures have larger IDs. A guard update keeps its ID. */
+	readonly id: number;
+	readonly origin: CaptureOrigin;
+	/** Session leaf at capture; `buildSessionProjection(entries, leafId)` rebuilds the baseline. */
+	readonly leafId: string | null;
+	readonly changes: StructuredChanges;
+	/** Effective forced prompt text, present only when it differs from the replayed prompt. */
+	readonly forcedPrompt?: string;
+	readonly guard: GuardResult;
+	/**
+	 * Active tools Pi left out of the request for a tool's `prepareLoadout()`, as
+	 * the run's `before_agent_start` reported them; absent when Pi hid none.
+	 */
+	readonly hiddenTools?: readonly string[];
+}
+
+/** Read access for consumers. */
+export interface SnapshotReader {
+	/** The kept snapshot: the one with the highest ID published so far, of either origin. */
+	latest(): RequestSnapshot | undefined;
+	/** Report every publication, including guard updates; returns the unsubscribe function. */
+	subscribe(listener: (snapshot: RequestSnapshot) => void): () => void;
+}
+
+/**
+ * Keeps one snapshot: the latest by ID. A publication with the same or a
+ * higher ID replaces it, so a guard update replaces its own snapshot and the
+ * first real request's snapshot releases a probe snapshot. A publication with
+ * an older ID only notifies subscribers.
+ */
+export class SnapshotStore implements SnapshotReader {
+	private kept: RequestSnapshot | undefined;
+	private readonly listeners = new Set<(snapshot: RequestSnapshot) => void>();
+
+	/** Read the kept snapshot without transferring ownership. */
+	public latest(): RequestSnapshot | undefined {
+		return this.kept;
+	}
+
+	/** Observe every publication, even when a newer snapshot is already kept. */
+	public subscribe(listener: (snapshot: RequestSnapshot) => void): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	/** Keep a snapshot unless the kept one is newer, then notify subscribers. */
+	public publish(snapshot: RequestSnapshot): void {
+		if (this.kept === undefined || this.kept.id <= snapshot.id) this.kept = snapshot;
+		// Copy: a listener may unsubscribe while being notified
+		for (const listener of [...this.listeners]) listener(snapshot);
+	}
+
+	/** Drop the kept snapshot at session shutdown; subscriptions stay. */
+	public clear(): void {
+		this.kept = undefined;
+	}
+}