@xprnvd/pi-context-view 0.7.2 → 0.8.0

package/README.md

@@ -35,28 +35,28 @@ injected by other extensions.
   defaults, useful for
   [customization](https://github.com/dimk90/pi-context-view#customization).
 
-## Demo
-
-
-### `/context`
+## Demo: `/context`
 
 See what fills your context, for example, what survives compaction:
 
-![Context usage view showing estimated context composition](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/context-usage.gif)
+![Context usage view showing estimated context composition](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/context-usage.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
 
 
-### `/context injections`
+## Demo: `/context injections`
 
 Inspect hidden parts of the context, such as tool definitions:
 
-![Context injections view and item preview](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/context-injections.gif)
+![Context injections view and item preview](https://media.githubusercontent.com/media/dimk90/pi-context-view/0ee9a806e9c23bea642edabacfd6830755f3122d/doc/images/context-injections.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
 
-### Zoom
+## Demo: Zoom
 
 Zoom in for a more detailed breakdown of large context windows, such as
 1M-token windows:
 
-![Zoom feature](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/zoom.gif)
+![Zoom feature](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/zoom.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
 
 ## Install
 
@@ -73,7 +73,7 @@ To get started, create a configuration file populated with the current defaults:
 ```text
 /context config
 ```
-> This creates `~/.pi/agent/extensions/pi-context-view.json`.
+➥ This creates `~/.pi/agent/extensions/pi-context-view.json`.
 
 See the [configuration reference](https://github.com/dimk90/pi-context-view/blob/master/doc/CONFIG.md)
 for each parameter's meaning and default value.
@@ -85,7 +85,8 @@ colors that stay the same across themes. Here are examples of custom
 [terrain](https://github.com/dimk90/pi-context-view/blob/master/doc/palettes/terrain.json) and
 [rainbow](https://github.com/dimk90/pi-context-view/blob/master/doc/palettes/rainbow.json) palettes:
 
-![Terrain and rainbow palettes](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/palettes.png)
+![Terrain and rainbow palettes](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/palettes.png)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
 
 See the [theme color reference](https://github.com/dimk90/pi-context-view/blob/develop/doc/PI-THEME-COLORS.md)
 for color names that follow the current theme.
@@ -94,7 +95,8 @@ for color names that follow the current theme.
 
 You can configure the number of rows and columns in the `Context Usage` map:
 
-![Map size demo](https://media.githubusercontent.com/media/dimk90/pi-context-view/2bc280f758d88fc0ac6396e921c7e697c9016086/doc/images/map-sizes.png)
+![Map size demo](https://media.githubusercontent.com/media/dimk90/pi-context-view/2bc280f758d88fc0ac6396e921c7e697c9016086/doc/images/map-sizes.png)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
 
 
 ## Context Footprint

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xprnvd/pi-context-view",
-	"version": "0.7.2",
+	"version": "0.8.0",
 	"description": "Pi extension to visualize context usage and inspect the hidden parts: base prompt, tools defs, and extension injections",
 	"type": "module",
 	"license": "MIT",
@@ -9,9 +9,9 @@
 		"type": "git",
 		"url": "git+https://github.com/xprnvd/pi-context-view.git"
 	},
-	"homepage": "https://github.com/dimk90/pi-context-view#readme",
+	"homepage": "https://github.com/xprnvd/pi-context-view",
 	"bugs": {
-		"url": "https://github.com/dimk90/pi-context-view/issues"
+		"url": "https://github.com/xprnvd/pi-context-view/issues"
 	},
 	"keywords": [
 		"pi",

package/src/capture/diff.ts

@@ -100,10 +100,23 @@ export function messageKey(message: RequestMessage): string {
  */
 export function sameMessage(a: RequestMessage, b: RequestMessage): boolean {
 	if (a.role !== b.role || customTypeKey(a) !== customTypeKey(b)) return false;
-	const result = compareJson(modelFacingPart(a), modelFacingPart(b), 0);
+	const result = compareJson(modelFacingPart(a), modelFacingPart(b), 0, "any");
 	return result === "unknown" ? messageKey(a) === messageKey(b) : result === "equal";
 }
 
+/**
+ * Whether two tools declare the same interface, as Pi's `declarationsEqual()`
+ * decides, without serializing plain JSON declarations. Only the fields Pi
+ * keeps in a declaration are compared; anything outside plain JSON data falls
+ * back to `declarationsEqual()`.
+ */
+export function sameDeclaration(a: Tool, b: Tool): boolean {
+	if (a === b) return true;
+	// Pi compares declarations as plain JSON, so schema key order matters
+	const result = compareJson(declarationPart(a), declarationPart(b), 0, "same");
+	return result === "unknown" ? declarationsEqual(a, b) : result === "equal";
+}
+
 /**
  * Remove the non-system messages that both sides share at the start and at
  * the end. Alignment matches these ends first, so `diffConversation()` over
@@ -158,7 +171,7 @@ function diffTools(before: readonly Tool[], after: readonly Tool[]): SystemChang
 	const changes: SystemChange[] = [];
 	for (const tool of after) {
 		const previous = beforeByName.get(tool.name);
-		if (previous === undefined || !declarationsEqual(previous, tool)) {
+		if (previous === undefined || !sameDeclaration(previous, tool)) {
 			changes.push({ type: "tool", name: tool.name, declaration: tool });
 		}
 	}
@@ -168,6 +181,16 @@ function diffTools(before: readonly Tool[], after: readonly Tool[]): SystemChang
 	return changes;
 }
 
+/** The fields of a tool that Pi's `toToolDeclaration()` keeps; executable and display fields are left out. */
+function declarationPart(tool: Tool): Tool {
+	return {
+		name: tool.name,
+		description: tool.description,
+		parameters: tool.parameters,
+		constrainedSampling: tool.constrainedSampling,
+	};
+}
+
 /** 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");
@@ -302,18 +325,25 @@ export function canonicalJson(value: unknown): string {
 
 /**
  * Result of comparing two values as JSON:
- *   equal       both encode to the same canonical JSON
- *   different   their canonical JSON differs
- *   unknown     a value is outside plain JSON data; compare the encoded keys
+ *   equal       both encode to the same JSON
+ *   different   their JSON differs
+ *   unknown     a value is outside plain JSON data; compare the encoded values
  */
 type JsonComparison = "equal" | "different" | "unknown";
 
+/**
+ * Which JSON encoding a comparison agrees with:
+ *   any    `canonicalJson()`: object key order does not matter
+ *   same   `JSON.stringify()`: object keys must come in the same order
+ */
+type KeyOrder = "any" | "same";
+
 /**
  * Compare plain JSON data (strings, booleans, null, finite numbers, arrays,
- * and plain objects) as `canonicalJson()` would, without encoding it. Object
- * key order and `undefined` properties do not matter, as in the keys.
+ * and plain objects) as its JSON encoding would, without encoding it.
+ * `undefined` properties do not matter, as in JSON.
  */
-function compareJson(a: unknown, b: unknown, depth: number): JsonComparison {
+function compareJson(a: unknown, b: unknown, depth: number, keyOrder: KeyOrder): JsonComparison {
 	if (typeof a === "string" || typeof a === "boolean") {
 		if (typeof b !== typeof a) return "unknown";
 		return a === b ? "equal" : "different";
@@ -325,17 +355,23 @@ function compareJson(a: unknown, b: unknown, depth: number): JsonComparison {
 	if (a === null) return b === null ? "equal" : "unknown";
 	if (typeof a !== "object" || typeof b !== "object" || b === null || depth >= MAX_COMPARE_DEPTH) return "unknown";
 	if (Array.isArray(a) || Array.isArray(b)) {
-		return Array.isArray(a) && Array.isArray(b) ? compareJsonArrays(a, b, depth) : "unknown";
+		return Array.isArray(a) && Array.isArray(b) ? compareJsonArrays(a, b, depth, keyOrder) : "unknown";
 	}
 	if (!isPlainObject(a) || !isPlainObject(b)) return "unknown";
-	return compareJsonObjects(a as Record<string, unknown>, b as Record<string, unknown>, depth);
+	const compareObjects = keyOrder === "any" ? compareJsonObjects : compareOrderedJsonObjects;
+	return compareObjects(a as Record<string, unknown>, b as Record<string, unknown>, depth);
 }
 
 /** Compare two arrays element by element; JSON keeps their order. */
-function compareJsonArrays(a: readonly unknown[], b: readonly unknown[], depth: number): JsonComparison {
+function compareJsonArrays(
+	a: readonly unknown[],
+	b: readonly unknown[],
+	depth: number,
+	keyOrder: KeyOrder,
+): JsonComparison {
 	if (a.length !== b.length) return "different";
 	for (let index = 0; index < a.length; index++) {
-		const result = compareJson(a[index], b[index], depth + 1);
+		const result = compareJson(a[index], b[index], depth + 1, keyOrder);
 		if (result !== "equal") return result;
 	}
 	return "equal";
@@ -351,7 +387,7 @@ function compareJsonObjects(
 	for (const key in a) {
 		if (a[key] === undefined) continue;
 		unpaired++;
-		const result = compareJson(a[key], b[key], depth + 1);
+		const result = compareJson(a[key], b[key], depth + 1, "any");
 		if (result !== "equal") return result;
 	}
 	for (const key in b) {
@@ -364,6 +400,29 @@ function compareJsonObjects(
 	return unpaired === 0 ? "equal" : "different";
 }
 
+/** Compare two plain objects by their defined properties, which must come in the same order. */
+function compareOrderedJsonObjects(
+	a: Readonly<Record<string, unknown>>,
+	b: Readonly<Record<string, unknown>>,
+	depth: number,
+): JsonComparison {
+	const aKeys = Object.keys(a).filter((key) => a[key] !== undefined);
+	const bKeys = Object.keys(b).filter((key) => b[key] !== undefined);
+	// JSON omits these, so the key lists alone cannot decide
+	if (aKeys.some((key) => isOmittedByJson(a[key])) || bKeys.some((key) => isOmittedByJson(b[key]))) return "unknown";
+	if (aKeys.length !== bKeys.length || aKeys.some((key, index) => key !== bKeys[index])) return "different";
+	for (const key of aKeys) {
+		const result = compareJson(a[key], b[key], depth + 1, "same");
+		if (result !== "equal") return result;
+	}
+	return "equal";
+}
+
+/** Whether JSON leaves out an object property with this value. */
+function isOmittedByJson(value: unknown): boolean {
+	return typeof value === "function" || typeof value === "symbol";
+}
+
 /** Whether a value is an object literal, not a class instance whose JSON may differ. */
 function isPlainObject(value: object): boolean {
 	const prototype: unknown = Object.getPrototypeOf(value);

package/src/capture/request.ts

@@ -10,7 +10,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { ProbeView } from "../probe/view.ts";
 import type { CaptureOrigin, RequestMessage } from "../snapshot.ts";
-import { trimMatchedEnds, type UnmatchedMessages } from "./diff.ts";
+import { sameDeclaration, trimMatchedEnds, type UnmatchedMessages } from "./diff.ts";
 import type { GuardModel } from "./guard.ts";
 
 /**
@@ -47,7 +47,9 @@ export interface SystemText {
 
 /**
  * The parts of a request the deferred diff and the payload guard need, as this
- * extension's handler saw them. Request-side values are owned copies.
+ * extension's handler saw them. Request-side objects are owned copies, except
+ * declarations equal to the baseline's: those are the baseline's own objects,
+ * which are only read. Strings are kept by reference.
  */
 export interface RequestCopy {
 	/** The request's replayed system state; undefined when it has none. */
@@ -105,8 +107,8 @@ export interface CaptureInput {
 
 /**
  * Read the baseline, copy what differs from it, and keep the effective prompt
- * for deferred forced-prompt detection. Throws when a differing message cannot
- * be cloned, for example when a handler added a function value to it.
+ * for deferred forced-prompt detection. Throws when a differing message or tool
+ * cannot be cloned, for example when a handler added a function value to it.
  */
 export function captureRequest(input: CaptureInput): CapturedRequest {
 	const baseline = readBaseline(input.sessionManager, input.probe);
@@ -125,21 +127,22 @@ export function captureRequest(input: CaptureInput): CapturedRequest {
 
 /**
  * Copy the request's replayed system state and the messages that differ from
- * the baseline. Messages equal to the baseline at both ends are compared in
- * place and never copied. System text positions and historical declarations
- * also belong to the copy: serializers may keep them instead of collapsing.
+ * the baseline. Messages equal to the baseline at both ends, and declarations
+ * equal to the baseline's of the same name, are compared in place and never
+ * copied. System text positions and historical declarations also belong to
+ * the copy: serializers may keep them instead of collapsing.
  */
 export function copyRequest(baseline: readonly BaselineMessage[], messages: readonly RequestMessage[]): RequestCopy {
 	const unmatched = trimMatchedEnds(baseline, messages);
-	// Later handlers share these objects, tool schemas included, and may edit them in place
-	const copy = structuredClone({
-		system: getCurrentSystemMessage(messages), declarations: getDeclaredTools(messages), request: unmatched.request,
-	});
+	// Later handlers share these objects and may edit them in place
+	const request = structuredClone(unmatched.request);
+	const copyTool = createToolCopier(baseline);
+	const system = getCurrentSystemMessage(messages);
 	return {
-		...(copy.system === undefined ? {} : { system: copy.system }),
+		...(system === undefined ? {} : { system: copySystemState(system, copyTool) }),
 		systemTexts: copySystemTexts(messages),
-		declarations: copy.declarations,
-		conversation: { prefix: unmatched.prefix, baseline: unmatched.baseline, request: copy.request },
+		declarations: getDeclaredTools(messages).map(copyTool),
+		conversation: { prefix: unmatched.prefix, baseline: unmatched.baseline, request },
 	};
 }
 
@@ -181,6 +184,36 @@ export function detectForcedPrompt(effectivePrompt: string, baseline: readonly B
 	return effectivePrompt === replayed ? undefined : effectivePrompt;
 }
 
+/**
+ * A function that returns, for each request tool, the baseline's declaration
+ * of the same name when it is equal, else an owned copy. Each request object
+ * is compared and copied once, so the current and historical declarations
+ * keep sharing objects. Throws when a differing tool cannot be cloned.
+ */
+function createToolCopier(baseline: readonly BaselineMessage[]): (tool: Tool) => Tool {
+	const baselineTools = new Map(getDeclaredTools(baseline.map(({ message }) => message))
+		.map((tool) => [tool.name, tool]));
+	const copies = new Map<Tool, Tool>();
+	return (tool) => {
+		let copy = copies.get(tool);
+		if (copy === undefined) {
+			const previous = baselineTools.get(tool.name);
+			// Later handlers share request tools, schemas included, and may edit them in place
+			copy = previous !== undefined && sameDeclaration(previous, tool) ? previous : structuredClone(tool);
+			copies.set(tool, copy);
+		}
+		return copy;
+	};
+}
+
+/**
+ * The replayed system state with copied tools. Replay builds new containers
+ * and strings are immutable, so content and sections need no copy.
+ */
+function copySystemState(system: SystemMessage, copyTool: (tool: Tool) => Tool): SystemMessage {
+	return system.toolsAdded === undefined ? system : { ...system, toolsAdded: system.toolsAdded.map(copyTool) };
+}
+
 /**
  * Copy the text of every system message with its position. Strings are
  * immutable, so a shallow copy of the sections suffices; tool changes are

package/src/ui/injections-model.ts

@@ -6,6 +6,7 @@
 import {
 	type ChangeEditor,
 	type ForcedEdit,
+	type InjectionGroup,
 	type InjectionItem,
 	type InjectionSnapshot,
 	type RequestChange,
@@ -40,6 +41,30 @@ export type ChangeScope =
 	| "request-new"
 	| "payload";
 
+/** What a list filter compares the query against. */
+export type InjectionFilterMode = "name" | "content";
+
+/** A non-blank list filter; the view owns how text is normalized and compared. */
+export interface InjectionFilter {
+	readonly mode: InjectionFilterMode;
+	/** Whether a group or item label contains the query. */
+	readonly nameMatches: (label: string) => boolean;
+	/** Whether an item's content contains the query. */
+	readonly contentMatches: (item: InjectionItem) => boolean;
+}
+
+/**
+ * Rows a filter leaves, by item id and `source:<id>` group key. The snapshot
+ * itself stays whole, so estimates, diffs, and change scopes never depend on
+ * which rows a filter hides.
+ */
+export interface InjectionFilterResult {
+	/** Rows to show: matches and the ancestors kept as their context. */
+	readonly kept: ReadonlySet<string>;
+	/** Rows that matched directly, not as context. */
+	readonly matched: ReadonlySet<string>;
+}
+
 /** One flattened list row derived from the snapshot hierarchy. */
 export type InjectionRow =
 	| {
@@ -51,6 +76,8 @@ export type InjectionRow =
 		readonly diff?: TokenDiff;
 		/** Where the changes of the rows it counts live; absent when none changed. */
 		readonly scope?: ChangeScope;
+		/** Whether an active filter matched this row itself rather than keeping it as context. */
+		readonly matched?: boolean;
 	}
 	| {
 		readonly kind: "item";
@@ -84,6 +111,8 @@ export type InjectionRow =
 		readonly editors?: readonly ChangeEditor[];
 		/** Stable preview target id from the snapshot. */
 		readonly itemId: string;
+		/** Whether an active filter matched this row itself rather than keeping it as context. */
+		readonly matched?: boolean;
 	}
 	| {
 		readonly kind: "separator";
@@ -110,10 +139,80 @@ export function collectItemsById(snapshot: InjectionSnapshot): Map<string, Injec
 	return items;
 }
 
-/** Flatten snapshot groups into rows separated from the non-selectable snapshot total. */
-export function buildInjectionRows(snapshot: InjectionSnapshot): InjectionRow[] {
+/**
+ * Rows the filter matches, plus each match's ancestors as context. In name
+ * mode a matching group or item keeps its whole subtree, since naming a
+ * container asks for its contents. In content mode an item with children
+ * matches through them: its own text concatenates theirs, so it stands alone
+ * only when no child matches.
+ */
+export function filterInjections(snapshot: InjectionSnapshot, filter: InjectionFilter): InjectionFilterResult {
+	const kept = new Set<string>();
+	const matched = new Set<string>();
+	const matches = (item: InjectionItem): boolean => filter.mode === "name"
+		? filter.nameMatches(item.label)
+		: filter.contentMatches(item);
+	for (const group of snapshot.groups) {
+		const wholeGroup = filter.mode === "name" && filter.nameMatches(group.source.label);
+		if (wholeGroup) matched.add(groupKey(group));
+		let groupKept = wholeGroup;
+		for (const item of group.items) {
+			if (filterItem(item, filter.mode, matches, wholeGroup, kept, matched)) groupKept = true;
+		}
+		if (groupKept) kept.add(groupKey(group));
+	}
+	return { kept, matched };
+}
+
+/**
+ * Record which rows of one item the filter keeps and matches; true when any
+ * is kept. `whole` keeps the full subtree, as inside a matching group.
+ */
+function filterItem(
+	item: InjectionItem,
+	mode: InjectionFilterMode,
+	matches: (item: InjectionItem) => boolean,
+	whole: boolean,
+	kept: Set<string>,
+	matched: Set<string>,
+): boolean {
+	const children = item.children ?? [];
+	const matchedChildren = children.filter(matches);
+	for (const child of matchedChildren) matched.add(child.id);
+	const itemMatched = matches(item);
+	if (whole || (mode === "name" && itemMatched)) {
+		if (itemMatched) matched.add(item.id);
+		for (const entry of [item, ...children]) kept.add(entry.id);
+		return true;
+	}
+	if (matchedChildren.length > 0) {
+		for (const entry of [item, ...matchedChildren]) kept.add(entry.id);
+		return true;
+	}
+	if (mode === "content" && itemMatched) {
+		matched.add(item.id);
+		kept.add(item.id);
+		return true;
+	}
+	return false;
+}
+
+/** Match key of a group row, kept apart from item ids. */
+function groupKey(group: InjectionGroup): string {
+	return `source:${group.source.id}`;
+}
+
+/**
+ * Flatten snapshot groups into rows separated from the non-selectable snapshot
+ * total. A filter result hides the rows it does not keep and flags the rows it
+ * matched; every shown row keeps the values and status of the whole snapshot.
+ */
+export function buildInjectionRows(snapshot: InjectionSnapshot, filter?: InjectionFilterResult): InjectionRow[] {
+	const shown = (key: string): boolean => filter === undefined || filter.kept.has(key);
+	const matched = (key: string): boolean | undefined => filter?.matched.has(key);
 	const rows: InjectionRow[] = [];
 	for (const group of snapshot.groups) {
+		if (!shown(groupKey(group))) continue;
 		rows.push({
 			kind: "group",
 			label: group.source.label,
@@ -121,9 +220,11 @@ export function buildInjectionRows(snapshot: InjectionSnapshot): InjectionRow[]
 			depth: 0,
 			diff: group.diff,
 			scope: combineScopes(group.items.filter((item) => item.diffOnly !== true).map(itemScope)),
+			matched: matched(groupKey(group)),
 		});
-		group.items.forEach((item, itemIndex) => {
-			const isLastItem = itemIndex === group.items.length - 1;
+		const items = group.items.filter((item) => shown(item.id));
+		items.forEach((item, itemIndex) => {
+			const isLastItem = itemIndex === items.length - 1;
 			rows.push({
 				kind: "item",
 				label: item.label,
@@ -141,8 +242,9 @@ export function buildInjectionRows(snapshot: InjectionSnapshot): InjectionRow[]
 				diffOnly: item.diffOnly,
 				...rowStatus(item),
 				itemId: item.id,
+				matched: matched(item.id),
 			});
-			const children = item.children ?? [];
+			const children = (item.children ?? []).filter((child) => shown(child.id));
 			children.forEach((child, childIndex) => {
 				rows.push({
 					kind: "item",
@@ -159,6 +261,7 @@ export function buildInjectionRows(snapshot: InjectionSnapshot): InjectionRow[]
 					requestOnly: child.requestOnly,
 					...rowStatus(child),
 					itemId: child.id,
+					matched: matched(child.id),
 				});
 			});
 		});
@@ -372,6 +475,12 @@ export class PreviewScroller {
 		return this.scrollBy(direction * Math.max(1, this.visibleCount - 1));
 	}
 
+	/** Leave a visible line in place; otherwise scroll it near the top, below `context` lines. */
+	public reveal(line: number, context: number): boolean {
+		if (line >= this.offsetValue && line < this.offsetValue + this.visibleCount) return false;
+		return this.scrollTo(line - context);
+	}
+
 	public reset(): void {
 		this.offsetValue = 0;
 	}