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

package/src/capture/guard.ts

@@ -0,0 +1,287 @@
+/**
+ * PayloadGuard: deferred comparison of the tool-declaration and message
+ * channels, and dispatch confirmation. Physical selections parse
+ * immediately after the payload copy; virtual selections keep the copy until
+ * dispatch supplies the model.
+ */
+import type { ModelIdentity } from "../model-identity.ts";
+import type { Dispatch, GuardFinding, GuardResult } from "../snapshot.ts";
+import {
+	type ConvertedRequest, type ConvertibleCapture, convertCapturedRequest, renderExpectedUnits,
+} from "./adjustments.ts";
+import { compareMessageUnits } from "./messages.ts";
+import {
+	copyPayload, type PayloadCopy, type PayloadDeclaration, parsePayloadMessages, parsePayloadTools,
+} from "./payload.ts";
+import { resolveForcedPrompt } from "./request.ts";
+import { compareToolDeclarations } from "./tools.ts";
+
+/** Model identity and the capabilities message normalization reads. */
+export interface GuardModel extends ModelIdentity {
+	/** Input modalities; without `image`, Pi replaces images with placeholders. */
+	readonly input: readonly string[];
+	/** API-specific compatibility settings; only top-level boolean flags are read. */
+	readonly compat?: object;
+}
+
+/** What the guard reads from a capture, before releasing the transcript. */
+export interface GuardCapture extends Omit<ConvertibleCapture, "forcedPrompt"> {
+	readonly id: number;
+	/** `ctx.getSystemPrompt()` at capture; the guard detects a forced prompt from it. */
+	readonly effectivePrompt: string;
+	readonly requestModel?: GuardModel;
+	/** Tools Pi left out of the request; their missing declarations are expected. */
+	readonly hiddenTools?: readonly string[];
+}
+
+/** Where guard results go; SnapshotBuilder in production. */
+export interface GuardPublisher {
+	/** Replace the earlier guard, including on a dispatch mismatch. */
+	settleGuard(id: number, guard: GuardResult): void;
+	/** Stop accepting updates after the final result. */
+	release(id: number): void;
+}
+
+/** Ports of the guard. */
+export interface PayloadGuardOptions {
+	readonly publisher: GuardPublisher;
+	/** Pi's `images.blockImages` setting, read at the payload hook. */
+	readonly blockImages: () => boolean;
+}
+
+/** Catalog lookup, as `ctx.modelRegistry.find()` does. */
+export type FindModel = (provider: string, modelId: string) => GuardModel | undefined;
+
+/** Minimal comparison data; no schemas, image data, or signatures. */
+interface ExpectedRequest {
+	readonly declarations: readonly PayloadDeclaration[];
+	/** Undefined when the captured request could not be converted. */
+	readonly transcript?: ConvertedRequest;
+}
+
+/**
+ * Result of comparing one channel:
+ *   compared      the channel was compared; `findings` may be empty
+ *   unsupported   the channel could not be compared, for `reason`
+ */
+type ChannelResult =
+	| { readonly status: "compared"; readonly findings: readonly GuardFinding[] }
+	| { readonly status: "unsupported"; readonly reason: string };
+
+/** State retained until comparison and dispatch confirmation have both ended. */
+interface PairedState {
+	readonly id: number;
+	readonly requestModel?: GuardModel;
+	readonly blockImages: boolean;
+	capture?: GuardCapture;
+	expected?: ExpectedRequest;
+	payload?: PayloadCopy;
+	scheduled?: NodeJS.Immediate;
+	/** The virtual route's catalog model, once known. */
+	dispatchedModel?: GuardModel;
+	dispatch?: Dispatch;
+	/** A failure that replaces even a comparison already published on the physical path. */
+	failure?: GuardResult;
+	finished: boolean;
+}
+
+/** Compare payloads and release raw copies before retaining the final snapshots. */
+export class PayloadGuard {
+	private readonly options: PayloadGuardOptions;
+	private readonly open = new Map<number, PairedState>();
+
+	public constructor(options: PayloadGuardOptions) {
+		this.options = options;
+	}
+
+	/** Copy synchronously in the payload hook; defer all comparison work. */
+	public accept(capture: GuardCapture, payload: unknown): void {
+		const state: PairedState = {
+			id: capture.id,
+			requestModel: capture.requestModel,
+			capture,
+			payload: copyPayload(payload),
+			blockImages: this.options.blockImages(),
+			finished: false,
+		};
+		this.open.set(state.id, state);
+		this.schedule(state);
+	}
+
+	/**
+	 * Read identity once, without parsing in the event handler. Physical identity
+	 * mismatches invalidate the result, never reparse. Virtual
+	 * requests use the dispatched model's API, not the payload shape.
+	 */
+	public confirm(id: number, dispatch: Dispatch, findModel: FindModel): void {
+		const state = this.open.get(id);
+		if (state === undefined || state.finished) return;
+		state.finished = true;
+		state.dispatch = dispatch;
+		const model = state.requestModel;
+		if (model?.api === "pi-virtual") {
+			state.dispatchedModel = findModel(dispatch.provider, dispatch.model);
+			if (state.dispatchedModel === undefined || !sameDispatch(toDispatch(state.dispatchedModel), dispatch)) {
+				state.failure = { status: "incomplete", reason: "The dispatched model is not registered.", dispatch };
+			}
+		} else if (model !== undefined && !sameDispatch(toDispatch(model), dispatch)) {
+			state.failure = {
+				status: "incomplete", reason: "The dispatched provider, API, or model differs from the captured selection.", dispatch,
+			};
+		}
+		this.schedule(state);
+	}
+
+	/** A paired request ended without dispatch metadata; discard any provisional result. */
+	public finishUnconfirmed(id: number): void {
+		const state = this.open.get(id);
+		if (state === undefined || state.finished) return;
+		state.finished = true;
+		state.failure = { status: "incomplete", reason: "No dispatch identity was observed for this request." };
+		this.schedule(state);
+	}
+
+	/** Cancel scheduled work and release payloads and comparison inputs at shutdown. */
+	public clear(): void {
+		for (const state of this.open.values()) {
+			if (state.scheduled !== undefined) clearImmediate(state.scheduled);
+		}
+		this.open.clear();
+	}
+
+	/** Schedule at most one job per request; failures never escape into the host. */
+	private schedule(state: PairedState): void {
+		if (state.scheduled !== undefined) return;
+		state.scheduled = setImmediate(() => {
+			state.scheduled = undefined;
+			try {
+				this.process(state);
+			} catch {
+				this.options.publisher.settleGuard(state.id, {
+					status: "incomplete", reason: "The payload could not be compared.",
+				});
+				state.capture = undefined;
+				state.expected = undefined;
+				state.payload = undefined;
+			}
+			if (state.finished) {
+				this.open.delete(state.id);
+				this.options.publisher.release(state.id);
+			}
+		});
+	}
+
+	/** Reduce the capture to comparison data first, even while a virtual request waits for dispatch. */
+	private process(state: PairedState): void {
+		if (state.failure !== undefined) {
+			this.options.publisher.settleGuard(state.id, state.failure);
+			return;
+		}
+		if (state.capture !== undefined) {
+			state.expected = reduceCapture(state.capture, state.blockImages);
+			state.capture = undefined;
+		}
+		const model = state.requestModel?.api === "pi-virtual" ? state.dispatchedModel : state.requestModel;
+		if (model === undefined && state.requestModel?.api === "pi-virtual") return;
+		const copy = state.payload;
+		const expected = state.expected;
+		state.payload = undefined;
+		state.expected = undefined;
+		if (copy === undefined || expected === undefined) return; // Already compared on the physical path
+		if (model === undefined) {
+			this.options.publisher.settleGuard(state.id, {
+				status: "incomplete", reason: "No model was selected for this request.",
+			});
+			return;
+		}
+		this.evaluate(state, copy, expected, model);
+	}
+
+	/**
+	 * Compare both channels and publish their findings. Only two compared
+	 * channels complete the guard; otherwise the compared one keeps its findings.
+	 */
+	private evaluate(state: PairedState, copy: PayloadCopy, expected: ExpectedRequest, model: GuardModel): void {
+		const dispatch = state.dispatch ?? toDispatch(model);
+		if (!copy.supported) {
+			this.options.publisher.settleGuard(state.id, { status: "incomplete", reason: copy.reason, dispatch });
+			return;
+		}
+		const tools = compareToolChannel(copy.payload, expected, model);
+		const messages = compareMessageChannel(copy.payload, expected.transcript, model);
+		const compared = [tools, messages].flatMap((channel) => channel.status === "compared" ? [channel.findings] : []);
+		const failure = tools.status === "unsupported" ? tools : messages.status === "unsupported" ? messages : undefined;
+		const guard: GuardResult = failure === undefined
+			? { status: "complete", dispatch, findings: compared.flat() }
+			: {
+				status: "incomplete", reason: failure.reason, dispatch,
+				...(compared.length === 0 ? {} : { findings: compared.flat() }),
+			};
+		this.options.publisher.settleGuard(state.id, guard);
+	}
+}
+
+/**
+ * The comparison data of a capture: the declarations Pi sends, without the
+ * tools it hid, and the converted transcript. A request that cannot be
+ * converted leaves only the message channel uncompared.
+ */
+function reduceCapture(capture: GuardCapture, blockImages: boolean): ExpectedRequest {
+	const hidden = new Set(capture.hiddenTools);
+	const tools = {
+		declarations: (capture.system?.toolsAdded ?? [])
+			.filter(({ name }) => !hidden.has(name))
+			.map(({ name, description }) => ({ name, description })),
+	};
+	try {
+		const forcedPrompt = resolveForcedPrompt(capture);
+		const convertible = forcedPrompt === undefined ? capture : { ...capture, forcedPrompt };
+		return { ...tools, transcript: convertCapturedRequest(convertible, { blockImages }) };
+	} catch {
+		return tools;
+	}
+}
+
+/** Compare the payload's tool declarations with the expected ones. */
+function compareToolChannel(payload: unknown, expected: ExpectedRequest, model: GuardModel): ChannelResult {
+	const parsed = parsePayloadTools(model.api, payload);
+	if (parsed.status !== "parsed") return parsed;
+	const findings = compareToolDeclarations({
+		expected: expected.declarations,
+		declarations: parsed.declarations,
+		ignoreNameCase: model.api === "anthropic-messages",
+	});
+	return { status: "compared", findings };
+}
+
+/** Compare the payload's text units with those Pi would send for the captured request. */
+function compareMessageChannel(
+	payload: unknown,
+	transcript: ConvertedRequest | undefined,
+	model: GuardModel,
+): ChannelResult {
+	if (transcript === undefined) {
+		return { status: "unsupported", reason: "The captured request could not be converted for comparison." };
+	}
+	const parsed = parsePayloadMessages(model.api, payload);
+	if (parsed.status !== "parsed") return parsed;
+	let expected;
+	try {
+		expected = renderExpectedUnits(transcript, model);
+	} catch {
+		// An unexpected message shape must not hide the tool channel's result
+		return { status: "unsupported", reason: "The captured request could not be normalized for this model." };
+	}
+	const findings = compareMessageUnits(expected, parsed.units, { ignoreNameCase: model.api === "anthropic-messages" });
+	return { status: "compared", findings };
+}
+
+/** Dispatch identity without mutable model metadata. */
+function toDispatch(model: GuardModel): Dispatch {
+	return { provider: model.provider, api: model.api, model: model.id };
+}
+
+/** Whether two identities name the same provider, API, and model. */
+function sameDispatch(a: Dispatch, b: Dispatch): boolean {
+	return a.provider === b.provider && a.api === b.api && a.model === b.model;
+}

package/src/capture/messages.ts

@@ -0,0 +1,246 @@
+/**
+ * PayloadGuard's message channel: compare the text units a payload sends
+ * with the units Pi would send for the captured request. Keys ignore
+ * whitespace; an LCS alignment matches them, and every unit left over is a
+ * payload change with its changed lines. Pure functions over process-local data.
+ */
+import type { GuardFinding, MessagePart, PayloadChangeLine } from "../snapshot.ts";
+import { alignSequences } from "./diff.ts";
+
+/** Unpaired UTF-16 surrogates; Pi removes them from text before sending it. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+const WHITESPACE = /\s+/gu;
+
+/** Parts that Pi omits when their text is empty; a tool call or result always counts. */
+const OMITTED_WHEN_EMPTY: ReadonlySet<MessagePart> = new Set(["system", "user", "assistant"]);
+
+/** One model-facing text unit: a run of one message part's text, a tool call, or a tool result. */
+export interface MessageUnit {
+	readonly part: MessagePart;
+	/** Text as sent; for a tool call, its arguments as canonical JSON or grammar input. */
+	readonly text: string;
+	/** Tool name of a tool call. */
+	readonly name?: string;
+}
+
+/** Options of one message-channel comparison. */
+export interface MessageComparisonOptions {
+	/** Match tool-call names without case, as for Claude Code names with an Anthropic OAuth token. */
+	readonly ignoreNameCase: boolean;
+}
+
+/**
+ * Collects units in message order. Text of one part merges with the previous
+ * unit until a message boundary or another part, so how a serializer splits a
+ * message into blocks does not matter.
+ */
+export class UnitCollector {
+	private readonly units: MessageUnit[] = [];
+	private open = false;
+
+	/** Start a new message: the next text never merges with earlier units. */
+	public boundary(): void {
+		this.open = false;
+	}
+
+	/** Add text of a system, user, or assistant part. */
+	public text(part: "system" | "user" | "assistant", text: string): void {
+		const previous = this.units.at(-1);
+		if (this.open && previous?.part === part) {
+			this.units[this.units.length - 1] = { part, text: `${previous.text}\n${text}` };
+			return;
+		}
+		this.units.push({ part, text });
+		this.open = true;
+	}
+
+	/** Add one tool call; it ends the current text run. */
+	public toolCall(name: string, text: string): void {
+		this.units.push({ part: "tool-call", name, text });
+		this.open = false;
+	}
+
+	/** Add one tool result; it ends the current text run. */
+	public toolResult(text: string): void {
+		this.units.push({ part: "tool-result", text });
+		this.open = false;
+	}
+
+	/** The collected units, in order. */
+	public result(): MessageUnit[] {
+		return this.units;
+	}
+}
+
+/**
+ * Compare the expected units with the payload's units:
+ *   only in the payload                        added
+ *   only in the expected units                 deleted
+ *   both with one part between the same matches   modified, with the differing lines
+ * Units whose text is only whitespace are skipped where Pi omits them too.
+ */
+export function compareMessageUnits(
+	expected: readonly MessageUnit[],
+	sent: readonly MessageUnit[],
+	options: MessageComparisonOptions,
+): GuardFinding[] {
+	const key = (unit: MessageUnit) => unitKey(unit, options.ignoreNameCase);
+	const [before, after] = trimMatchedEnds(expected, sent, key);
+	return findGaps(before.filter(isSent), after.filter(isSent), key).flatMap(classifyGap);
+}
+
+/**
+ * Lines that differ between two texts, ignoring whitespace and blank lines:
+ * removed lines of `before`, then added lines of `after`, for each gap.
+ */
+export function diffLines(before: string, after: string): PayloadChangeLine[] {
+	const beforeLines = splitLines(before);
+	const afterLines = splitLines(after);
+	return findGaps(beforeLines, afterLines, normalizeText)
+		.flatMap((gap) => [...gap.deleted.map(removedLine), ...gap.added.map(addedLine)]);
+}
+
+/** Text without whitespace and unpaired surrogates: what a unit key compares. */
+export function normalizeText(text: string): string {
+	return text.replace(LONE_SURROGATE, "").replace(WHITESPACE, "");
+}
+
+/**
+ * Drop the ends that the alignment would match anyway, so that only the middle
+ * builds keys: exactly equal units at the start, units with equal keys right
+ * after them, then exactly equal units at the end. The alignment extends the
+ * start by key before it trims the end, so the end stops where the start
+ * stopped; otherwise a key-equal unit could match on the other side.
+ */
+function trimMatchedEnds(
+	expected: readonly MessageUnit[],
+	sent: readonly MessageUnit[],
+	key: (unit: MessageUnit) => string,
+): [readonly MessageUnit[], readonly MessageUnit[]] {
+	let start = 0;
+	while (start < expected.length && start < sent.length && unitsEqual(expected[start], sent[start])) start++;
+	let expectedStart = start;
+	let sentStart = start;
+	for (;;) {
+		while (expectedStart < expected.length && !isSent(expected[expectedStart])) expectedStart++;
+		while (sentStart < sent.length && !isSent(sent[sentStart])) sentStart++;
+		if (expectedStart === expected.length || sentStart === sent.length) break;
+		if (key(expected[expectedStart]) !== key(sent[sentStart])) break;
+		expectedStart++;
+		sentStart++;
+	}
+	let end = 0;
+	while (end < expected.length - expectedStart && end < sent.length - sentStart
+		&& unitsEqual(expected[expected.length - 1 - end], sent[sent.length - 1 - end])) end++;
+	return [expected.slice(expectedStart, expected.length - end), sent.slice(sentStart, sent.length - end)];
+}
+
+/** Whether two units are exactly equal, which implies equal keys without building them. */
+function unitsEqual(a: MessageUnit, b: MessageUnit): boolean {
+	return a.part === b.part && a.name === b.name && a.text === b.text;
+}
+
+/** Items between two consecutive aligned matches. */
+interface Gap<Item> {
+	readonly deleted: readonly Item[];
+	readonly added: readonly Item[];
+}
+
+/** Align two sequences by key and return the unmatched items between matches, in order. */
+function findGaps<Item>(before: readonly Item[], after: readonly Item[], key: (item: Item) => string): Gap<Item>[] {
+	const ids = new Map<string, number>();
+	const intern = (item: Item) => {
+		const text = key(item);
+		let id = ids.get(text);
+		if (id === undefined) {
+			id = ids.size;
+			ids.set(text, id);
+		}
+		return id;
+	};
+	const matches = alignSequences(before.map(intern), after.map(intern));
+	const gaps: Gap<Item>[] = [];
+	let beforeIndex = 0;
+	let afterIndex = 0;
+	// A sentinel match after both ends closes the last gap
+	for (const match of [...matches, { before: before.length, after: after.length }]) {
+		const gap = { deleted: before.slice(beforeIndex, match.before), added: after.slice(afterIndex, match.after) };
+		if (gap.deleted.length > 0 || gap.added.length > 0) gaps.push(gap);
+		beforeIndex = match.before + 1;
+		afterIndex = match.after + 1;
+	}
+	return gaps;
+}
+
+/**
+ * Pair each deleted unit with the next unpaired added unit of the same part,
+ * keeping order. Deletions come first, then the gap's payload units in order.
+ */
+function classifyGap(gap: Gap<MessageUnit>): GuardFinding[] {
+	const pairs = new Map<number, MessageUnit>();
+	const unpaired: MessageUnit[] = [];
+	let searchFrom = 0;
+	for (const unit of gap.deleted) {
+		const position = gap.added.findIndex((candidate, index) => index >= searchFrom && candidate.part === unit.part);
+		if (position === -1) {
+			unpaired.push(unit);
+			continue;
+		}
+		pairs.set(position, unit);
+		searchFrom = position + 1;
+	}
+	const findings: GuardFinding[] = unpaired.map((unit) =>
+		payloadChange("deleted", unit, unitLines(unit).map(removedLine)));
+	for (const [index, unit] of gap.added.entries()) {
+		const original = pairs.get(index);
+		findings.push(original === undefined
+			? payloadChange("added", unit, unitLines(unit).map(addedLine))
+			: payloadChange("modified", unit, diffLines(displayText(original), displayText(unit))));
+	}
+	return findings;
+}
+
+/** A payload-change finding for one unit. */
+function payloadChange(
+	change: "added" | "modified" | "deleted",
+	unit: MessageUnit,
+	lines: readonly PayloadChangeLine[],
+): GuardFinding {
+	return { type: "payload-change", change, part: unit.part, lines };
+}
+
+/** Non-blank lines of a unit as findings show it. */
+function unitLines(unit: MessageUnit): string[] {
+	return splitLines(displayText(unit));
+}
+
+/** Whether a unit reaches the model: Pi drops system, user, and assistant text that is only whitespace. */
+function isSent(unit: MessageUnit): boolean {
+	return !OMITTED_WHEN_EMPTY.has(unit.part) || normalizeText(unit.text).length > 0;
+}
+
+/** Comparison key: part, tool name, and text without whitespace. */
+function unitKey(unit: MessageUnit, ignoreNameCase: boolean): string {
+	const name = unit.name === undefined ? "" : ignoreNameCase ? unit.name.toLowerCase() : unit.name;
+	return `${unit.part}\u0000${name}\u0000${normalizeText(unit.text)}`;
+}
+
+/** Text of a unit as findings show it; a tool call leads with its name. */
+function displayText(unit: MessageUnit): string {
+	return unit.name === undefined ? unit.text : `${unit.name} ${unit.text}`;
+}
+
+/** Lines of a text that hold more than whitespace. */
+function splitLines(text: string): string[] {
+	return text.split(/\r?\n/).filter((line) => normalizeText(line).length > 0);
+}
+
+/** A line only in the payload. */
+function addedLine(text: string): PayloadChangeLine {
+	return { type: "added", text };
+}
+
+/** A line only in the captured request. */
+function removedLine(text: string): PayloadChangeLine {
+	return { type: "removed", text };
+}