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

package/src/system-prompt-rows.ts

@@ -0,0 +1,311 @@
+/**
+ * The `system prompt` rows of the Injections tree: the changes to pi's prompt
+ * text against pi's default prompt, split by available ownership signals. Each
+ * extension gets the diff of the lines measured as its own: its tools' prompt
+ * lines and the additions guessed to be its own. `unattributed` gets every
+ * other change to the System Prompt, instruction files, and skills. The rows
+ * repeat diffs that System Prompt and its siblings already count, so they
+ * carry no estimate of their own. The same split names the editors of each
+ * System Prompt part's diff. Pure; no pi access.
+ */
+import { charTokens, isPiPromptPart, SYSTEM_PROMPT_ITEM_ID } from "./measure.ts";
+import {
+	AGGREGATE_SOURCE,
+	AGGREGATE_SOURCE_ID,
+	type ChangeEditor,
+	type InjectionItem,
+	type InjectionSection,
+	type InjectionSource,
+	sumTokenDiffs,
+	type TokenDiff,
+} from "./model.ts";
+
+/** Label of every `system prompt` row; lower case, like the other rows under a source. */
+const SYSTEM_PROMPT_ROW_LABEL = "system prompt";
+
+/**
+ * One diff-only `system prompt` row per extension with lines in the System
+ * Prompt diff, in prompt order, then one `unattributed` row for every other
+ * prompt change. `items` are the request's prompt and tool items with their
+ * diffs; `session` holds the session's, which tell whether an extension's
+ * lines are only in this request. The extension rows and the unattributed row
+ * together add up to the diffs of System Prompt, Instruction Files, and
+ * Skills. No row is built without a diff.
+ */
+export function buildSystemPromptRows(
+	items: readonly InjectionItem[],
+	session: readonly InjectionItem[],
+): InjectionItem[] {
+	const owners = new Map<string, RowDraft>();
+	const unattributed = createRowDraft(AGGREGATE_SOURCE);
+	const sessionById = new Map(session.map((item) => [item.id, item]));
+	for (const item of items) {
+		if (item.id === SYSTEM_PROMPT_ITEM_ID) splitPromptDiff(item, owners, unattributed, sessionById.get(item.id));
+		else if (item.source.native && (item.kind === "context-file" || item.kind === "skills")) {
+			collectUnattributedDiffs(item, unattributed, sessionById.get(item.id));
+		}
+	}
+	const requestLines = extensionLines(items);
+	const sessionLines = extensionLines(session);
+	const rows = [...owners.values()].map((owner) => {
+		const id = owner.source.id;
+		// The session keeps the lines it has, whatever this request changed
+		owner.saved = sessionLines.has(id);
+		return createRow(owner, requestLines.get(id) !== sessionLines.get(id));
+	});
+	rows.push(createRow(unattributed, unattributed.sections.some((section) => section.requestOnly === true)));
+	return rows.filter((row) => row.diff !== undefined);
+}
+
+/**
+ * Who made a saved System Prompt part's diff, as the `system prompt` rows
+ * split it: extensions whose lines take a share of the added tokens, in
+ * prompt order, then `unknown` for any other addition and every removal.
+ * A request-only part's editor is always unknown. Undefined without a diff.
+ */
+export function partEditors(part: InjectionItem): ChangeEditor[] | undefined {
+	if (part.diff === undefined) return undefined;
+	// References name contributed lines, never who edited them in this request
+	if (part.requestOnly === true) return [{ type: "unknown" }];
+	const shares = ownerShares(part, part.diff.added);
+	const editors: ChangeEditor[] = shares.map(({ source, guess }) => ({
+		type: "extension",
+		source,
+		...(guess ? { attribution: "guess" as const } : {}),
+	}));
+	const known = shares.reduce((sum, share) => sum + share.added, 0);
+	if (known < part.diff.added || part.diff.removed > 0) editors.push({ type: "unknown" });
+	return editors;
+}
+
+/** Parts and diffs collected for one `system prompt` row before it is built. */
+interface RowDraft {
+	readonly source: InjectionSource;
+	/** One preview part per changed prompt part, in prompt order. */
+	readonly sections: InjectionSection[];
+	/** True when the session keeps some of the row's changes. */
+	saved: boolean;
+}
+
+/** An empty row draft for one source. */
+function createRowDraft(source: InjectionSource): RowDraft {
+	return { source, sections: [], saved: false };
+}
+
+/**
+ * Split the System Prompt diff part by part: each extension's lines go to its
+ * row, the rest of the part's diff to `unattributed`. A System Prompt without
+ * parts, such as a forced prompt without sections, has no extension lines.
+ */
+function splitPromptDiff(
+	prompt: InjectionItem,
+	owners: Map<string, RowDraft>,
+	unattributed: RowDraft,
+	session: InjectionItem | undefined,
+): void {
+	const parts = prompt.children ?? [];
+	if (parts.length === 0) {
+		if (prompt.diff !== undefined) addUnattributed(unattributed, prompt, prompt.diff, prompt.change === "forced");
+		return;
+	}
+	const sessionParts = new Map(session?.children?.map((part) => [part.id, part]));
+	for (const part of parts) {
+		if (part.diff === undefined) continue;
+		let added = part.diff.added;
+		for (const share of ownerShares(part, part.diff.added)) {
+			let owner = owners.get(share.source.id);
+			if (owner === undefined) {
+				owner = createRowDraft(share.source);
+				owners.set(share.source.id, owner);
+			}
+			owner.sections.push({
+				label: part.label,
+				text: share.text,
+				tokens: 0,
+				diffOnly: true,
+				diff: { added: share.added, removed: 0 },
+				...(share.guess ? { attribution: "guess" as const } : {}),
+			});
+			added -= share.added;
+		}
+		const rest = { added, removed: part.diff.removed };
+		if (rest.added > 0 || rest.removed > 0) {
+			addUnattributed(unattributed, part, rest, false, hasSavedUnattributed(part, sessionParts.get(part.id)));
+		}
+	}
+	collectResidual(prompt, parts, unattributed, session);
+}
+
+/**
+ * Changes to instruction files or skills, which `unattributed` holds whole:
+ * one part per changed child, or the item itself without children.
+ */
+function collectUnattributedDiffs(
+	item: InjectionItem,
+	unattributed: RowDraft,
+	session: InjectionItem | undefined,
+): void {
+	if (item.diff === undefined) return;
+	const children = item.children ?? [];
+	if (children.length === 0) {
+		addUnattributed(unattributed, item, item.diff, false);
+		return;
+	}
+	for (const child of children) {
+		if (child.diff !== undefined) addUnattributed(unattributed, child, child.diff, false);
+	}
+	collectResidual(item, children, unattributed, session);
+}
+
+/**
+ * The part of a parent's diff its children do not show: the removal of
+ * children only the session has. Preview their session text as one part. The
+ * request lacks them, so it is request-only.
+ */
+function collectResidual(
+	parent: InjectionItem,
+	children: readonly InjectionItem[],
+	row: RowDraft,
+	session: InjectionItem | undefined,
+): void {
+	const shown = sumTokenDiffs(children.map((child) => child.diff));
+	const residual = {
+		added: (parent.diff?.added ?? 0) - (shown?.added ?? 0),
+		removed: (parent.diff?.removed ?? 0) - (shown?.removed ?? 0),
+	};
+	if (residual.added <= 0 && residual.removed <= 0) return;
+	const sent = new Set(children.map((child) => child.id));
+	const missing = session?.children?.filter((child) => !sent.has(child.id)) ?? [];
+	const reference = missing.length === 1 ? missing[0] : {
+		...parent, text: missing.map((child) => child.text).join("\n"), injectedReferences: undefined,
+	};
+	// The request lacks these children, so their whole text is removed
+	if (reference !== undefined) {
+		addUnattributed(row, { ...reference, textDiff: { base: reference.text, request: "" } }, residual, true);
+	}
+}
+
+/**
+ * Whether the unattributed share includes saved changes: a saved custom
+ * section, or unowned extension lines the session has. Saved lines of known
+ * owners go to their own rows, not to the unknown request-only edits beside them.
+ */
+function hasSavedUnattributed(part: InjectionItem, session: InjectionItem | undefined): boolean {
+	if (part.requestOnly !== true) return true;
+	if (part.savedChange !== true || session === undefined) return false;
+	const references = session.injectedReferences ?? [];
+	if (references.length > 0) return references.some((reference) => isUnattributedSource(reference.source));
+	return !isPiPromptPart(part.id);
+}
+
+/** Add one changed part and its persistence state to the unattributed row. */
+function addUnattributed(
+	row: RowDraft,
+	part: InjectionItem,
+	diff: TokenDiff,
+	requestOnly: boolean,
+	saved = part.requestOnly !== true && !requestOnly,
+): void {
+	row.sections.push(diffSection(part, diff, requestOnly));
+	row.saved ||= saved;
+}
+
+/**
+ * One changed part as an unattributed preview part: its whole text, with the
+ * extension lines in it still annotated, or the session text of a deleted part.
+ * It keeps the part's text diff, so both previews show the same diff body.
+ */
+function diffSection(part: InjectionItem, diff: TokenDiff, requestOnly: boolean): InjectionSection {
+	return {
+		label: part.label,
+		text: part.text,
+		tokens: 0,
+		diffOnly: true,
+		diff,
+		...(part.requestOnly === true || requestOnly ? { requestOnly: true } : {}),
+		jsonSpan: part.jsonSpan,
+		injectedReferences: part.injectedReferences,
+		...(part.textDiff === undefined ? {} : { textDiff: part.textDiff }),
+	};
+}
+
+/** Tokens one extension's lines add to one part, and the lines themselves. */
+interface OwnerShare {
+	readonly source: InjectionSource;
+	readonly added: number;
+	/** The extension's lines in the part, in prompt order. */
+	readonly text: string;
+	/** True when any of the lines has a guessed owner. */
+	readonly guess: boolean;
+}
+
+/**
+ * Each extension's share of the tokens one part added, by the characters of
+ * its lines in prompt order. Shares round cumulatively, like section shares,
+ * so together they never exceed `added`; unattributed lines take no share.
+ */
+function ownerShares(part: InjectionItem, added: number): OwnerShare[] {
+	const references = (part.injectedReferences ?? [])
+		.filter((reference) => !isUnattributedSource(reference.source))
+		.sort((a, b) => a.start - b.start);
+	let chars = 0;
+	let allocated = 0;
+	const shares: OwnerShare[] = [];
+	for (const owned of Map.groupBy(references, (reference) => reference.source.id).values()) {
+		const text = owned.map((reference) => part.text.slice(reference.start, reference.end)).join("");
+		chars += text.length;
+		const tokens = Math.min(added, charTokens(chars)) - allocated;
+		allocated += tokens;
+		if (tokens > 0) {
+			const guess = owned.some((reference) => reference.attribution === "guess");
+			shares.push({ source: owned[0].source, added: tokens, text, guess });
+		}
+	}
+	return shares;
+}
+
+/**
+ * Every extension's lines in the System Prompt parts pi sent, keyed by source
+ * id, with the part each line is in. Equal keys in the request and the session
+ * mean the extension's lines are saved.
+ */
+function extensionLines(items: readonly InjectionItem[]): Map<string, string> {
+	const lines = new Map<string, string>();
+	const prompt = items.find((item) => item.id === SYSTEM_PROMPT_ITEM_ID);
+	for (const part of prompt?.children ?? []) {
+		if (part.dropped === true || part.change === "deleted") continue;
+		for (const reference of part.injectedReferences ?? []) {
+			if (isUnattributedSource(reference.source)) continue;
+			const line = `${part.id}\n${part.text.slice(reference.start, reference.end)}\n`;
+			lines.set(reference.source.id, (lines.get(reference.source.id) ?? "") + line);
+		}
+	}
+	return lines;
+}
+
+/**
+ * Whether a reference has no extension provenance, rather than a known or
+ * guessed owner, such as an unregistered recorded tool's snippet.
+ */
+function isUnattributedSource(source: InjectionSource): boolean {
+	return source.id === AGGREGATE_SOURCE_ID;
+}
+
+/** The diff-only row of one draft: no estimate, the sum of its parts' diffs. */
+function createRow(draft: RowDraft, requestOnly: boolean): InjectionItem {
+	const diff = sumTokenDiffs(draft.sections.map((section) => section.diff));
+	return {
+		id: `system-prompt:${draft.source.id}`,
+		kind: "prompt-addition",
+		source: draft.source,
+		label: SYSTEM_PROMPT_ROW_LABEL,
+		chars: 0,
+		tokens: 0,
+		text: draft.sections.map((section) => section.text).join(""),
+		sections: draft.sections,
+		diffOnly: true,
+		...(diff === undefined ? {} : { diff }),
+		...(requestOnly ? { requestOnly: true } : {}),
+		...(draft.saved ? { savedChange: true } : {}),
+	};
+}

package/src/text.ts

@@ -0,0 +1,46 @@
+/**
+ * Terminal sanitizers shared by command reporting and the views. Every string
+ * that reaches the terminal from outside this extension — captured content,
+ * configuration files, error messages — passes through here first.
+ */
+
+const TERMINAL_STRING_START = /\u001B[\]PX^_]|[\u0090\u0098\u009D\u009E\u009F]/g;
+const TERMINAL_STRING_END = /\u0007|\u001B\\|\u009C/g;
+const TERMINAL_CSI_SEQUENCE = /(?:\u001B\[|\u009B)[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]/g;
+const TERMINAL_ESCAPE_SEQUENCE = /\u001B[\u0020-\u002F]*[\u0030-\u007E]/g;
+const TERMINAL_CONTROL_CHARACTER = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+
+/** Normalize whitespace and remove terminal control sequences from raw preview text. */
+export function normalizePreviewText(text: string): string {
+	const normalized = text
+		.replaceAll("\r\n", "\n")
+		.replaceAll("\r", "\n")
+		.replaceAll("\t", "    ");
+	return stripTerminalStrings(normalized)
+		.replace(TERMINAL_CSI_SEQUENCE, "")
+		.replace(TERMINAL_ESCAPE_SEQUENCE, "")
+		.replace(TERMINAL_CONTROL_CHARACTER, "");
+}
+
+/** Remove complete terminal strings without rescanning an unterminated suffix for every start. */
+function stripTerminalStrings(text: string): string {
+	const parts: string[] = [];
+	let offset = 0;
+	TERMINAL_STRING_START.lastIndex = 0;
+	let start: RegExpExecArray | null;
+	while ((start = TERMINAL_STRING_START.exec(text)) !== null) {
+		TERMINAL_STRING_END.lastIndex = TERMINAL_STRING_START.lastIndex;
+		if (TERMINAL_STRING_END.exec(text) === null) break;
+		parts.push(text.slice(offset, start.index));
+		offset = TERMINAL_STRING_END.lastIndex;
+		TERMINAL_STRING_START.lastIndex = offset;
+	}
+	// Preserve an incomplete string for the existing escape/control sanitizers.
+	parts.push(text.slice(offset));
+	return parts.join("");
+}
+
+/** Sanitize dynamic text for one terminal line and collapse embedded whitespace. */
+export function normalizeInlineText(text: string): string {
+	return normalizePreviewText(text).replace(/\s+/g, " ").trim();
+}

package/src/token-diff.ts

@@ -0,0 +1,211 @@
+/**
+ * Word-level comparison of two texts and the token diff it implies. Pure
+ * string logic shared by the Injections composition; no pi access.
+ */
+import { charTokens } from "./measure.ts";
+import type { TokenDiff } from "./model.ts";
+
+/** A word, a whitespace run, or one other character; together they cover the whole text. */
+const WORD_PATTERN = /\s+|[\p{L}\p{N}_]+|[^\s\p{L}\p{N}_]/gu;
+
+/**
+ * Edit steps after which the comparison stops aligning and counts the rest as
+ * replaced. Unrelated texts, such as a forced prompt against pi's, would
+ * otherwise cost time proportional to their length times their edit distance.
+ */
+const MAX_EDIT_STEPS = 2_000;
+
+/** Characters a word-level comparison found only in one of two texts. */
+export interface WordChanges {
+	/** Characters only in the later text. */
+	readonly addedChars: number;
+	/** Characters only in the earlier text. */
+	readonly removedChars: number;
+}
+
+/** One contiguous run in a word comparison; joining each side reconstructs its exact text. */
+export interface WordDiffPart {
+	readonly type: "unchanged" | "added" | "removed";
+	readonly text: string;
+}
+
+/** Text and token estimate of one side of a comparison. */
+export interface DiffSide {
+	readonly text: string;
+	readonly tokens: number;
+}
+
+/**
+ * Tokens `request` gained and lost against `base`, or undefined when neither
+ * changed a token. No base means everything was added, and equal texts mean
+ * no change, even when a share of a larger estimate rounds differently.
+ * Otherwise a word-level comparison supplies the changed characters, rounded
+ * up to tokens, and any rounding difference goes to the side with changed
+ * characters, so that base tokens plus `added` minus `removed` equals the
+ * request tokens. An empty request with no tokens removes the whole base, and
+ * no diff removes more than the base or adds more than the request has.
+ */
+export function measureTokenDiff(base: DiffSide | undefined, request: DiffSide): TokenDiff | undefined {
+	if (base === undefined) return nonEmptyDiff({ added: request.tokens, removed: 0 });
+	if (base.text === request.text) return undefined;
+	const changes = countWordChanges(base.text, request.text);
+	return nonEmptyDiff(reconcileTokens(base.tokens, request.tokens, changes));
+}
+
+/**
+ * Characters only in `before` or only in `after`, aligning words with Myers'
+ * shortest edit script after matching the common ends. A difference too large
+ * to align within `MAX_EDIT_STEPS` counts its whole middle as replaced.
+ */
+export function countWordChanges(before: string, after: string): WordChanges {
+	if (before === after) return { addedChars: 0, removedChars: 0 };
+	const words = comparisonWords(before, after);
+	const matchedChars = words.prefix.length + words.suffix.length + matchedMiddleChars(words.before, words.after);
+	return { addedChars: after.length - matchedChars, removedChars: before.length - matchedChars };
+}
+
+/**
+ * Word runs on the same path used by token estimates, with a bounded Myers
+ * trace retained only for previews. An unalignable middle is a replacement.
+ */
+export function diffWords(before: string, after: string): WordDiffPart[] {
+	if (before === after) return before.length === 0 ? [] : [{ type: "unchanged", text: before }];
+	const words = comparisonWords(before, after);
+	const trace: Int32Array[] = [];
+	matchedMiddleChars(words.before, words.after, trace);
+	const middle = trace.length === 0
+		? [{ type: "removed" as const, text: words.before.join("") },
+			{ type: "added" as const, text: words.after.join("") }]
+		: traceParts(words.before, words.after, trace);
+	const parts: WordDiffPart[] = [];
+	for (const part of [{ type: "unchanged" as const, text: words.prefix }, ...middle,
+		{ type: "unchanged" as const, text: words.suffix }]) {
+		if (part.text.length === 0) continue;
+		const previous = parts.at(-1);
+		if (previous?.type === part.type) parts[parts.length - 1] = { type: part.type, text: previous.text + part.text };
+		else parts.push(part);
+	}
+	return parts;
+}
+
+/** Tokenized middle after stripping identical ends, shared by counts and previews. */
+interface ComparisonWords {
+	readonly before: readonly string[];
+	readonly after: readonly string[];
+	readonly prefix: string;
+	readonly suffix: string;
+}
+
+/** Strip common ends before running the bounded comparison. */
+function comparisonWords(before: string, after: string): ComparisonWords {
+	const beforeWords = before.match(WORD_PATTERN) ?? [];
+	const afterWords = after.match(WORD_PATTERN) ?? [];
+	let start = 0;
+	while (start < beforeWords.length && start < afterWords.length && beforeWords[start] === afterWords[start]) start++;
+	let beforeEnd = beforeWords.length;
+	let afterEnd = afterWords.length;
+	while (beforeEnd > start && afterEnd > start && beforeWords[beforeEnd - 1] === afterWords[afterEnd - 1]) {
+		beforeEnd--;
+		afterEnd--;
+	}
+	return {
+		before: beforeWords.slice(start, beforeEnd), after: afterWords.slice(start, afterEnd),
+		prefix: beforeWords.slice(0, start).join(""), suffix: beforeWords.slice(beforeEnd).join(""),
+	};
+}
+
+/**
+ * Characters of the words Myers' shortest edit script keeps in both
+ * sequences, or 0 when it needs more than `MAX_EDIT_STEPS`. Each diagonal
+ * remembers the kept characters of its furthest path. Only previews request
+ * a trace; counts keep linear working memory. A failed alignment clears it.
+ */
+function matchedMiddleChars(before: readonly string[], after: readonly string[], trace?: Int32Array[]): number {
+	const n = before.length;
+	const m = after.length;
+	if (n === 0 || m === 0) return 0;
+	const maxSteps = Math.min(n + m, MAX_EDIT_STEPS);
+	const offset = maxSteps + 1;
+	// furthest[offset + k]: the furthest x reached on diagonal k = x - y; kept[offset + k]: its kept characters
+	const furthest = new Int32Array(2 * offset + 1);
+	const kept = new Float64Array(2 * offset + 1);
+	for (let steps = 0; steps <= maxSteps; steps++) {
+		for (let k = -steps; k <= steps; k += 2) {
+			const insertion = k === -steps || (k !== steps && furthest[offset + k - 1] < furthest[offset + k + 1]);
+			const from = offset + (insertion ? k + 1 : k - 1);
+			let x = insertion ? furthest[from] : furthest[from] + 1;
+			let y = x - k;
+			let chars = kept[from];
+			while (x < n && y < m && before[x] === after[y]) {
+				chars += before[x].length;
+				x++;
+				y++;
+			}
+			furthest[offset + k] = x;
+			kept[offset + k] = chars;
+			if (x >= n && y >= m) {
+				trace?.push(furthest.slice(offset - steps, offset + steps + 1));
+				return chars;
+			}
+		}
+		trace?.push(furthest.slice(offset - steps, offset + steps + 1));
+	}
+	if (trace !== undefined) trace.length = 0;
+	return 0;
+}
+
+/** Walk a successful Myers trace backward, then restore word order. */
+function traceParts(before: readonly string[], after: readonly string[], trace: readonly Int32Array[]): WordDiffPart[] {
+	const parts: WordDiffPart[] = [];
+	let x = before.length;
+	let y = after.length;
+	for (let steps = trace.length - 1; steps > 0; steps--) {
+		const previous = trace[steps - 1];
+		const k = x - y;
+		const offset = steps - 1;
+		const insertion = k === -steps || (k !== steps && previous[offset + k - 1] < previous[offset + k + 1]);
+		const previousK = insertion ? k + 1 : k - 1;
+		const previousX = previous[offset + previousK];
+		const previousY = previousX - previousK;
+		while (x > previousX && y > previousY) {
+			parts.push({ type: "unchanged", text: before[--x] });
+			y--;
+		}
+		parts.push(insertion ? { type: "added", text: after[--y] } : { type: "removed", text: before[--x] });
+	}
+	while (x > 0 && y > 0) {
+		parts.push({ type: "unchanged", text: before[--x] });
+		y--;
+	}
+	return parts.reverse();
+}
+
+/**
+ * Round changed characters up to tokens, then give the difference to the base
+ * estimate to the side with changed characters, so the result reconciles
+ * exactly. An image, for example, changes the estimate far more than its text.
+ * Text the estimates leave out, such as the JSON around a message's content
+ * blocks, can count more changed characters than either side has tokens; the
+ * diff then replaces the whole base.
+ */
+function reconcileTokens(baseTokens: number, requestTokens: number, changes: WordChanges): TokenDiff {
+	let added = charTokens(changes.addedChars);
+	let removed = charTokens(changes.removedChars);
+	const error = requestTokens - baseTokens - (added - removed);
+	if (error > 0) {
+		const cut = changes.addedChars > 0 ? 0 : Math.min(error, removed);
+		removed -= cut;
+		added += error - cut;
+	} else if (error < 0) {
+		const cut = changes.removedChars > 0 ? 0 : Math.min(-error, added);
+		added -= cut;
+		removed += -error - cut;
+	}
+	if (added > requestTokens || removed > baseTokens) return { added: requestTokens, removed: baseTokens };
+	return { added, removed };
+}
+
+/** The diff, or undefined when it neither adds nor removes a token. */
+function nonEmptyDiff(diff: TokenDiff): TokenDiff | undefined {
+	return diff.added === 0 && diff.removed === 0 ? undefined : diff;
+}

package/src/transcript.ts

@@ -0,0 +1,19 @@
+/**
+ * Process-local helpers for Pi's transcript-backed system messages. Replay
+ * itself uses Pi's `getCurrentSystemMessage()`.
+ */
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+/** System-message shape supplied by Pi, with content and declaration patches. */
+export type SystemMessage = Extract<ContextEvent["messages"][number], { role: "system" }>;
+
+/** Content followed by non-deleted sections, matching Pi's complete-prompt rendering. */
+export function systemMessageText(message: Pick<SystemMessage, "content" | "sections">): string {
+	return [systemContentText(message), ...Object.values(message.sections ?? {})]
+		.filter((part): part is string => part !== null && part.length > 0).join("\n\n");
+}
+
+/** Extract plain text without copying opaque text-block signatures. */
+function systemContentText(message: Pick<SystemMessage, "content">): string {
+	return typeof message.content === "string" ? message.content : message.content.map((block) => block.text).join("\n");
+}

package/src/ui/color.ts

@@ -0,0 +1,52 @@
+/**
+ * Rendering of configured colors.
+ *
+ * A theme color key is painted by the active theme, so it keeps following
+ * theme changes. A literal hex value is painted through a pi `Theme` built
+ * over that single color, which reuses pi's own conversion: truecolor escapes
+ * where the terminal supports them, and the closest 256-color index otherwise.
+ */
+import { Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+
+import { type CategoryColor, type HexColor, isHexColor, THEME_COLOR_NAMES } from "../config.ts";
+
+/** Foreground slot read back from a literal theme, whose slots all hold one color. */
+const LITERAL_SLOT: ThemeColor = "text";
+
+/** Backgrounds a literal theme never paints; pi maps the empty value to its reset sequence. */
+const LITERAL_BACKGROUNDS = {
+	selectedBg: "",
+	userMessageBg: "",
+	customMessageBg: "",
+	toolPendingBg: "",
+	toolSuccessBg: "",
+	toolErrorBg: "",
+} as const;
+
+/**
+ * Literal themes, keyed by color and color mode. A map render paints hundreds
+ * of cells, so the themes are built once instead of per painted cell; a
+ * runtime configures at most one per category.
+ */
+const literalThemes = new Map<string, Theme>();
+
+/** Paint text with one configured color, whether it names a theme color or a literal value. */
+export function colorize(theme: Theme, color: CategoryColor, text: string): string {
+	if (!isHexColor(color)) return theme.fg(color, text);
+	return literalTheme(color, theme.getColorMode()).fg(LITERAL_SLOT, text);
+}
+
+/** Cached single-color theme converting one hex value for the active color mode. */
+function literalTheme(color: HexColor, mode: ReturnType<Theme["getColorMode"]>): Theme {
+	const key = `${mode} ${color}`;
+	const cached = literalThemes.get(key);
+	if (cached !== undefined) return cached;
+	const created = new Theme(uniformForeground(color), LITERAL_BACKGROUNDS, mode);
+	literalThemes.set(key, created);
+	return created;
+}
+
+/** Every foreground slot set to one color; the cast rests on the compile-checked key list. */
+function uniformForeground(color: HexColor): Record<ThemeColor, HexColor> {
+	return Object.fromEntries(THEME_COLOR_NAMES.map((name) => [name, color])) as Record<ThemeColor, HexColor>;
+}