@danypops/pi-jittor 0.1.1 → 0.2.1

package/extension/src/benchmark-tui.ts

@@ -1,5 +1,3 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	BENCHMARK_TUI_MAX_CANDIDATES,
 	BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE,
@@ -15,6 +13,8 @@ import {
 	type RankedModel,
 	type UtilityComponentName,
 } from "@danypops/jittor";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { sessionSecretField } from "./session-identity.ts";
 
 export interface BenchmarkPanelClient {
@@ -31,13 +31,18 @@ type BenchmarkPanelAction = "refresh" | "close";
 const COMPONENT_LABELS: Record<UtilityComponentName, string> = { quality: "Q", cost: "$", latency: "L", context: "C", reliability: "R" };
 
 function componentText(item: RankedModel): string {
-	return item.components.map((component) => `${COMPONENT_LABELS[component.name]} ${component.score === null ? "?" : component.score.toFixed(3)}`).join(" · ");
+	return item.components
+		.map((component) => `${COMPONENT_LABELS[component.name]} ${component.score === null ? "?" : component.score.toFixed(3)}`)
+		.join(" · ");
 }
 
 function candidateLines(item: RankedModel, index: number, currentIdentity: string): string[] {
 	const current = item.identity.startsWith(`${currentIdentity}:`);
 	const localSamples = item.components.find((component) => component.name === "reliability")?.evidenceCount ?? 0;
-	const provenance = item.provenance.slice(0, BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE).map((source) => `${source.sourceId}@${source.revision} ${source.freshness}`).join(" · ");
+	const provenance = item.provenance
+		.slice(0, BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE)
+		.map((source) => `${source.sourceId}@${source.revision} ${source.freshness}`)
+		.join(" · ");
 	return [
 		` ${index + 1}. ${item.identity}${index === 0 ? "  recommended" : ""}${current ? "  current" : ""}`,
 		`    utility ${item.utility === null ? "?" : item.utility.toFixed(3)} · confidence ${(item.confidence * 100).toFixed(0)}% · ${componentText(item)}`,
@@ -50,13 +55,18 @@ export function renderBenchmarkView(result: ModelRankingResult, currentIdentity:
 	const shown = result.ranked.slice(0, BENCHMARK_TUI_MAX_CANDIDATES);
 	const currentIndex = result.ranked.findIndex((item) => item.identity.startsWith(`${currentIdentity}:`));
 	const recommended = result.ranked[0];
-	const reason = recommended && currentIndex > 0
-		? `Recommendation differs from current: ${recommended.identity} ranks #1; current ranks #${currentIndex + 1}.`
-		: recommended && currentIndex === 0 ? "Current model is the top recommendation." : "Current model is outside the ranked candidates.";
+	const reason =
+		recommended && currentIndex > 0
+			? `Recommendation differs from current: ${recommended.identity} ranks #1; current ranks #${currentIndex + 1}.`
+			: recommended && currentIndex === 0
+				? "Current model is the top recommendation."
+				: "Current model is outside the ranked candidates.";
 	const lines = [
 		theme.fg("borderMuted", "─".repeat(safeWidth)),
 		theme.bold("Jittor Benchmark Recommendations"),
-		result.scopeAuthority === "exact-session" ? "Scope: exact session" : "Scope: available models · ADVISORY (exact session scope unavailable)",
+		result.scopeAuthority === "exact-session"
+			? "Scope: exact session"
+			: "Scope: available models · ADVISORY (exact session scope unavailable)",
 		`Domain: ${result.domain} · Type: ${result.type} · evidence ${result.completeness}`,
 		reason,
 		...shown.flatMap((item, index) => candidateLines(item, index, currentIdentity)),
@@ -78,7 +88,7 @@ export async function showBenchmarkPanel(
 ): Promise<void> {
 	for (;;) {
 		const session_id = ctx.sessionManager.getSessionId();
-		const result = await client.call("models.rank", {
+		const result = (await client.call("models.rank", {
 			candidates,
 			session_id,
 			...sessionSecretField(session_id),
@@ -94,14 +104,19 @@ export async function showBenchmarkPanel(
 				reliability: MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
 			},
 			sourceIds: ["openrouter-models", "lmarena-hf", "artificial-analysis-direct", "openrouter-design-arena"],
-		}) as ModelRankingResult;
+		})) as ModelRankingResult;
 		if (ctx.mode !== "tui") {
-			ctx.ui.notify(renderBenchmarkView(result, currentIdentity, 100, { fg: (_color, text) => text, bold: (text) => text }).join("\n"), "info");
+			ctx.ui.notify(
+				renderBenchmarkView(result, currentIdentity, 100, { fg: (_color, text) => text, bold: (text) => text }).join("\n"),
+				"info",
+			);
 			return;
 		}
 		const action = await ctx.ui.custom<BenchmarkPanelAction>((_tui, theme, _keybindings, done) => ({
 			invalidate() {},
-			render(width: number): string[] { return renderBenchmarkView(result, currentIdentity, width, theme); },
+			render(width: number): string[] {
+				return renderBenchmarkView(result, currentIdentity, width, theme);
+			},
 			handleInput(data: string): void {
 				if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) done("close");
 				else if (data === "r") done("refresh");

package/extension/src/capabilities/codex-recovery.ts

@@ -1,17 +1,17 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
 	CODEX_RECOVERY_BASE_DELAY_MS,
 	CODEX_RECOVERY_JITTER_RATIO,
 	CODEX_RECOVERY_MAX_ATTEMPTS,
 	CODEX_RECOVERY_MAX_DELAY_MS,
-	MILLISECONDS_PER_MINUTE,
-	MILLISECONDS_PER_SECOND,
-	CodexRecoveryPolicy,
-	classifyCodexFailure,
 	type CodexFailureKind,
 	type CodexFailureMetadata,
+	CodexRecoveryPolicy,
+	classifyCodexFailure,
+	MILLISECONDS_PER_MINUTE,
+	MILLISECONDS_PER_SECOND,
 } from "@danypops/jittor";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { CodexRecoveryControl } from "../settings.ts";
 import { headerValue } from "./http-headers.ts";
 
@@ -25,8 +25,14 @@ export interface CodexRecoveryRuntime {
 export const SYSTEM_RECOVERY_RUNTIME: CodexRecoveryRuntime = {
 	now: Date.now,
 	random: Math.random,
-	setTimeout(callback, delayMs) { return setTimeout(() => { void callback(); }, delayMs); },
-	clearTimeout(handle) { clearTimeout(handle as ReturnType<typeof setTimeout>); },
+	setTimeout(callback, delayMs) {
+		return setTimeout(() => {
+			void callback();
+		}, delayMs);
+	},
+	clearTimeout(handle) {
+		clearTimeout(handle as ReturnType<typeof setTimeout>);
+	},
 };
 
 /**
@@ -47,13 +53,16 @@ export class CodexRecoveryCapability {
 		private readonly control: CodexRecoveryControl,
 		private readonly runtime: CodexRecoveryRuntime,
 	) {
-		this.policy = new CodexRecoveryPolicy({
-			baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
-			maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
-			maxAttempts: CODEX_RECOVERY_MAX_ATTEMPTS,
-			attemptWindowMs: CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
-			jitterRatio: CODEX_RECOVERY_JITTER_RATIO,
-		}, runtime.random);
+		this.policy = new CodexRecoveryPolicy(
+			{
+				baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
+				maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
+				maxAttempts: CODEX_RECOVERY_MAX_ATTEMPTS,
+				attemptWindowMs: CODEX_RECOVERY_ATTEMPT_WINDOW_MS,
+				jitterRatio: CODEX_RECOVERY_JITTER_RATIO,
+			},
+			runtime.random,
+		);
 	}
 
 	/** Clears the tracked response at the start of every new turn, before any Codex response for it has arrived. */
@@ -90,9 +99,13 @@ export class CodexRecoveryCapability {
 		const attempt = this.cooldown?.attempt ?? (state.pending ? state.attempts + 1 : state.attempts);
 		const phase = this.cooldown
 			? `cooldown ${Math.ceil(Math.max(0, this.cooldown.until - now) / MILLISECONDS_PER_SECOND)}s`
-			: state.pending ? "pending"
-				: state.attempts >= CODEX_RECOVERY_MAX_ATTEMPTS ? "exhausted"
-					: state.attempts > 0 ? "waiting" : "idle";
+			: state.pending
+				? "pending"
+				: state.attempts >= CODEX_RECOVERY_MAX_ATTEMPTS
+					? "exhausted"
+					: state.attempts > 0
+						? "waiting"
+						: "idle";
 		const failureKind = this.cooldown?.failureKind ?? state.lastFailureKind;
 		return [
 			`Codex recovery: ${enabled ? "on" : "off"}`,
@@ -119,12 +132,15 @@ export class CodexRecoveryCapability {
 			if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
 			const attempt = this.policy.recordAttempt(this.runtime.now());
 			if (!attempt) return;
-			this.pi.sendMessage({
-				customType: "jittor-codex-recovery",
-				content: `Retry the previous Codex request after a transient ${attempt.failureKind} failure. Automatic recovery attempt ${attempt.attempt} of ${CODEX_RECOVERY_MAX_ATTEMPTS}.`,
-				display: false,
-				details: { attempt: attempt.attempt, failureKind: attempt.failureKind },
-			}, { triggerTurn: true, deliverAs: "followUp" });
+			this.pi.sendMessage(
+				{
+					customType: "jittor-codex-recovery",
+					content: `Retry the previous Codex request after a transient ${attempt.failureKind} failure. Automatic recovery attempt ${attempt.attempt} of ${CODEX_RECOVERY_MAX_ATTEMPTS}.`,
+					display: false,
+					details: { attempt: attempt.attempt, failureKind: attempt.failureKind },
+				},
+				{ triggerTurn: true, deliverAs: "followUp" },
+			);
 		}, plan.delayMs);
 	}
 }

package/extension/src/capabilities/context-hub.ts

@@ -1,8 +1,4 @@
-import {
-	CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT,
-	validateContextContribution,
-	type ContextSegment,
-} from "@danypops/jittor";
+import { CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT, type ContextSegment, validateContextContribution } from "@danypops/jittor";
 
 /**
  * Merges Jittor's own directly-computed segments (tool ledger, real usage) with whatever

package/extension/src/capabilities/local-run-telemetry.ts

@@ -1,4 +1,4 @@
-import { classifyTaskFromTools, modelRunMetrics, type MetricObservation, type ModelRunObservation } from "@danypops/jittor";
+import { classifyTaskFromTools, type MetricObservation, type ModelRunObservation, modelRunMetrics } from "@danypops/jittor";
 
 export interface ActiveLocalModelRun {
 	runId: string;
@@ -59,18 +59,22 @@ export class LocalRunTelemetry {
 		this.active = undefined;
 		if (!active || typeof message !== "object" || message === null || Array.isArray(message)) return [];
 		const value = message as Record<string, unknown>;
-		if (value["role"] !== "assistant" || typeof value["provider"] !== "string" || typeof value["model"] !== "string") return [];
-		const usage = typeof value["usage"] === "object" && value["usage"] !== null ? value["usage"] as Record<string, unknown> : {};
-		const amount = (name: string): number => typeof usage[name] === "number" && Number.isFinite(usage[name]) ? usage[name] as number : 0;
-		const cost = typeof usage["cost"] === "object" && usage["cost"] !== null && typeof (usage["cost"] as Record<string, unknown>)["total"] === "number"
-			? (usage["cost"] as Record<string, number>)["total"] ?? 0 : 0;
-		const stopReason = ["stop", "length", "toolUse", "error", "aborted"].includes(String(value["stopReason"]))
-			? value["stopReason"] as ModelRunObservation["stopReason"] : "unknown";
+		if (value.role !== "assistant" || typeof value.provider !== "string" || typeof value.model !== "string") return [];
+		const usage = typeof value.usage === "object" && value.usage !== null ? (value.usage as Record<string, unknown>) : {};
+		const amount = (name: string): number =>
+			typeof usage[name] === "number" && Number.isFinite(usage[name]) ? (usage[name] as number) : 0;
+		const cost =
+			typeof usage.cost === "object" && usage.cost !== null && typeof (usage.cost as Record<string, unknown>).total === "number"
+				? ((usage.cost as Record<string, number>).total ?? 0)
+				: 0;
+		const stopReason = ["stop", "length", "toolUse", "error", "aborted"].includes(String(value.stopReason))
+			? (value.stopReason as ModelRunObservation["stopReason"])
+			: "unknown";
 		const completedAt = Math.max(Date.now(), active.firstTokenAt ?? active.startedAt, active.startedAt);
 		this.lastCompleted = {
 			runId: active.runId,
-			provider: value["provider"],
-			model: value["model"],
+			provider: value.provider,
+			model: value.model,
 			thinking: thinkingLevel,
 			...classifyTaskFromTools(active.toolNames),
 			startedAt: active.startedAt,

package/extension/src/capabilities/provider-response-telemetry.ts

@@ -1,11 +1,11 @@
 import {
 	classifyGoogleVertexFailure,
+	type GoogleVertexFailureMetadata,
 	googleVertexFailureMetrics,
 	hasAnthropicRateLimitHeaders,
+	type MetricObservation,
 	parseAnthropicRateLimitHeaders,
 	parseCodexRateLimitHeaders,
-	type GoogleVertexFailureMetadata,
-	type MetricObservation,
 } from "@danypops/jittor";
 import { headerValue } from "./http-headers.ts";
 
@@ -67,22 +67,36 @@ export class ProviderResponseTelemetry {
 			}
 			// Well-evidenced regardless of headers: GCP's own quota system fronts this transport, so the
 			// same failure classification as google-vertex applies below.
-			this.lastAnthropicVertexResponse = { status, ...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}) };
+			this.lastAnthropicVertexResponse = {
+				status,
+				...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}),
+			};
 		}
 		if (provider === "google-vertex") {
-			this.lastGoogleVertexResponse = { status, ...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}) };
+			this.lastGoogleVertexResponse = {
+				status,
+				...(headerValue(headers, "retry-after") ? { retryAfter: headerValue(headers, "retry-after") } : {}),
+			};
 		}
 		if (Object.keys(headers).some((name) => name.toLowerCase().startsWith("x-codex-"))) {
 			try {
 				const updates = parseCodexRateLimitHeaders(new Headers(headers), Date.now());
-				await recordMetrics(client, updates.flatMap((update) => update.metrics));
+				await recordMetrics(
+					client,
+					updates.flatMap((update) => update.metrics),
+				);
 			} catch {
 				notifySchemaDrift("Codex telemetry schema drift");
 			}
 		}
 	}
 
-	async handleMessageEnd(client: ProviderTelemetryClient, provider: string | undefined, stopReason: string | undefined, errorMessage: string | undefined): Promise<void> {
+	async handleMessageEnd(
+		client: ProviderTelemetryClient,
+		provider: string | undefined,
+		stopReason: string | undefined,
+		errorMessage: string | undefined,
+	): Promise<void> {
 		if (provider === "google-vertex") {
 			if (stopReason === "error") {
 				const failure = classifyGoogleVertexFailure(errorMessage, this.lastGoogleVertexResponse);

package/extension/src/context-breakdown.ts

@@ -0,0 +1,347 @@
+import {
+	CONTEXT_DEFAULT_RESERVE_TOKENS,
+	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
+	CONTEXT_TREE_MAX_NODES,
+	type ContextSegment,
+	type ContextSegmentItem,
+} from "@danypops/jittor";
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Ported from pi-papyrus's context-budget.ts: the Pi-generic half (session message-history tree
+ * walk, base-prompt structural breakdown, and the known-segments-vs-real-total composer) that
+ * has nothing to do with Papyrus's own artifacts. Papyrus's rules/tasks segments stay in
+ * pi-papyrus, contributed to this same breakdown over CONTEXT_HUB_CONTRIBUTION_CHANNEL instead
+ * of being computed here.
+ */
+
+/**
+ * Session entries and tree nodes as SessionManager exposes them (docs/session-format.md,
+ * SessionTreeNode from @earendil-works/pi-coding-agent): a subset covering only the fields
+ * this estimate reads, so this stays testable with plain object literals instead of
+ * importing pi's own session types.
+ */
+export interface SessionEntryLike {
+	id: string;
+	type: string;
+	message?: unknown;
+	summary?: string;
+}
+export interface SessionTreeNodeLike {
+	entry: SessionEntryLike;
+	children: SessionTreeNodeLike[];
+}
+
+function messageContentCharacters(message: unknown): number {
+	if (typeof message !== "object" || message === null) return 0;
+	const record = message as Record<string, unknown>;
+	if (record.role === "bashExecution") {
+		// Pi's own context builder excludes "!!"-prefixed bash output from context; match that.
+		if (record.excludeFromContext === true) return 0;
+		return String(record.command ?? "").length + String(record.output ?? "").length;
+	}
+	const content = record.content;
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	let characters = 0;
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		const b = block as Record<string, unknown>;
+		if (b.type === "text") characters += String(b.text ?? "").length;
+		else if (b.type === "thinking") characters += String(b.thinking ?? "").length;
+		else if (b.type === "toolCall") characters += JSON.stringify(b.arguments ?? {}).length;
+		// "image" blocks are deliberately not counted here -- image tokens follow a different,
+		// non-character-based cost model this char/4 estimate cannot represent; this is a real,
+		// documented undercount for image-heavy sessions, not a silent approximation.
+	}
+	return characters;
+}
+
+function messageSnippet(message: unknown, maxLength = 48): string {
+	if (typeof message !== "object" || message === null) return "";
+	const record = message as Record<string, unknown>;
+	if (record.role === "bashExecution") return String(record.command ?? "");
+	const content = record.content;
+	const text =
+		typeof content === "string"
+			? content
+			: Array.isArray(content)
+				? content
+						.map((block) =>
+							typeof block === "object" && block !== null && (block as Record<string, unknown>).type === "text"
+								? String((block as Record<string, unknown>).text ?? "")
+								: "",
+						)
+						.join(" ")
+				: "";
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1)}…` : collapsed;
+}
+
+function entryLabel(entry: SessionEntryLike): string {
+	if (entry.type === "compaction") return "compaction summary";
+	if (entry.type === "branch_summary") return "branch summary";
+	const role = typeof entry.message === "object" && entry.message !== null ? (entry.message as Record<string, unknown>).role : undefined;
+	const prefix = typeof role === "string" ? role : entry.type;
+	const snippet = messageSnippet(entry.message);
+	return snippet ? `${prefix}: ${snippet}` : prefix;
+}
+
+export interface MessageHistoryTree {
+	/** One item per real tree root (ordinarily one, the session's first entry). */
+	items: ContextSegmentItem[];
+	/** Sum of tokens for entries on the CURRENT active path only -- what actually feeds the LLM's context right now, unlike content sitting in an abandoned /tree branch. */
+	activeTokens: number;
+	/** True if the walk hit CONTEXT_TREE_MAX_NODES or found a cycle -- the tree shown is a bounded prefix, not necessarily the complete session. */
+	truncated: boolean;
+}
+
+interface WalkFrame {
+	node: SessionTreeNodeLike;
+	parentIndex: number | null;
+}
+
+/**
+ * Walks Pi's own real session tree (ctx.sessionManager.getTree(), docs/session-format.md --
+ * entries form a genuine tree via id/parentId, not just the linear current-branch path) to
+ * estimate the conversation's context contribution AND surface branches explored via /tree
+ * that are no longer on the active path -- content that cost real tokens to generate but is
+ * NOT currently part of the context window. Bounded and cycle-safe (CONTEXT_TREE_MAX_NODES).
+ *
+ * `activeEntryIds` MUST come from ctx.sessionManager.buildContextEntries(), not getBranch().
+ * getBranch()'s own docstring says it "[i]ncludes all entry types... Use buildSessionContext()
+ * to get the resolved messages for the LLM" -- it does not skip entries a real compaction has
+ * already summarized away; using it here would overcount activeTokens for any session that has
+ * been compacted at all. buildContextEntries() is Pi's own compaction-aware entry list: the
+ * latest compaction entry, its kept entries from firstKeptEntryId onward, and everything after.
+ *
+ * `branchEntryIds` (optional) is the full raw current-path id set (getBranch()'s own output).
+ * When given, an entry on the branch path but excluded from activeEntryIds is labeled
+ * "(compacted)" rather than the less accurate "(inactive branch)", which is reserved for
+ * entries not on the current path at all (a genuinely abandoned /tree branch). Omitting it
+ * preserves the simpler binary active/inactive-branch labeling for callers that only have one
+ * set to give (e.g. tests).
+ *
+ * Iterative (not recursive) two-pass walk: an explicit-stack pre-order discovery pass followed
+ * by a reverse-order (children-before-parent) construction pass -- an ordinary long-running
+ * session is one long linear chain, so recursion depth would equal entry count.
+ */
+export function buildMessageHistoryTree(
+	roots: ReadonlyArray<SessionTreeNodeLike>,
+	activeEntryIds: ReadonlySet<string>,
+	branchEntryIds?: ReadonlySet<string>,
+): MessageHistoryTree {
+	const visited = new Set<string>();
+	let truncated = false;
+	let activeTokens = 0;
+
+	const order: WalkFrame[] = [];
+	const stack: WalkFrame[] = [...roots].reverse().map((root) => ({ node: root, parentIndex: null }));
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (order.length >= CONTEXT_TREE_MAX_NODES) {
+			truncated = true;
+			break;
+		}
+		if (visited.has(frame.node.entry.id)) {
+			truncated = true;
+			continue;
+		} // cycle guard
+		visited.add(frame.node.entry.id);
+		const index = order.length;
+		order.push(frame);
+		const children = [...frame.node.children].reverse().map((child) => ({ node: child, parentIndex: index }));
+		stack.push(...children);
+	}
+	if (stack.length > 0) truncated = true; // node bound hit with more work still queued
+
+	const childItemsByParent = new Map<number, ContextSegmentItem[]>();
+	const itemByIndex = new Map<number, ContextSegmentItem>();
+	for (let index = order.length - 1; index >= 0; index--) {
+		const frame = order[index]!;
+		const entry = frame.node.entry;
+		const characters =
+			entry.type === "message"
+				? messageContentCharacters(entry.message)
+				: entry.type === "compaction" || entry.type === "branch_summary"
+					? (entry.summary ?? "").length
+					: 0;
+		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		const isActive = activeEntryIds.has(entry.id);
+		if (isActive) activeTokens += tokens;
+		const isOnBranch = branchEntryIds ? branchEntryIds.has(entry.id) : isActive; // no branch set given -- fall back to the old binary active/inactive-branch label
+
+		const children = childItemsByParent.get(index) ?? [];
+		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
+
+		const item: ContextSegmentItem = {
+			label: isActive ? entryLabel(entry) : isOnBranch ? `${entryLabel(entry)} (compacted)` : `${entryLabel(entry)} (inactive branch)`,
+			estimatedTokens: tokens,
+			...(children.length > 0 ? { children } : {}),
+		};
+		itemByIndex.set(index, item);
+		if (frame.parentIndex !== null) {
+			const siblings = childItemsByParent.get(frame.parentIndex) ?? [];
+			siblings.unshift(item); // reverse-order processing -- unshift restores original document order
+			childItemsByParent.set(frame.parentIndex, siblings);
+		}
+	}
+
+	const items: ContextSegmentItem[] = [];
+	for (let index = 0; index < order.length; index++) {
+		if (order[index]!.parentIndex === null) {
+			const item = itemByIndex.get(index);
+			if (item) items.push(item);
+		}
+	}
+	return { items, activeTokens, truncated };
+}
+
+function toCeilTokens(characters: number): number {
+	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+}
+
+/**
+ * Splits Pi's base system prompt into real structural sub-segments instead of one opaque
+ * number, using BeforeAgentStartEvent's own systemPromptOptions field -- Pi's own doc comment
+ * on it: "Extensions can inspect this to understand what Pi loaded without re-discovering
+ * resources." No new hook, no new risk: before_agent_start is already wired.
+ *
+ * Deliberately measures each INPUT's raw content size (tool snippet text, skill metadata,
+ * context file content) rather than attempting to byte-for-byte reproduce Pi's internal
+ * wrapping/tag format -- buildSystemPrompt() and formatSkillsForPrompt() are Pi-internal
+ * functions, not part of the public extension API. The remainder item absorbs whatever
+ * wrapping/template text this doesn't attribute, so the segment's total always still matches
+ * the real observed prompt length exactly.
+ *
+ * Measured as of THIS extension's own before_agent_start handler, which runs at whatever point
+ * Pi's own extension-load order places it in the before_agent_start chain -- an earlier
+ * extension's own systemPrompt mutation (e.g. an injected Rules/Tasks block) is already baked
+ * into event.systemPrompt by the time a later handler sees it. There is no per-handler identity
+ * in Pi's event payload to detect this, so this measurement is only as "pure Pi base prompt" as
+ * this extension's actual position in the load order happens to make it -- a real, documented
+ * limitation, not a promise.
+ */
+export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCharacters: number): ContextSegmentItem[] {
+	const items: ContextSegmentItem[] = [];
+
+	const toolSnippetEntries = Object.entries(options.toolSnippets ?? {});
+	// Mirrors buildSystemPrompt()'s own "- name: snippet\n" line shape closely enough to be a
+	// fair estimate without importing Pi-internal formatting code.
+	const toolSnippetsCharacters = toolSnippetEntries.reduce((sum, [name, snippet]) => sum + name.length + snippet.length + 4, 0);
+	if (toolSnippetsCharacters > 0) {
+		items.push({ label: `Tool snippets (${toolSnippetEntries.length} tools)`, estimatedTokens: toCeilTokens(toolSnippetsCharacters) });
+	}
+
+	const visibleSkills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
+	const skillsCharacters = visibleSkills.reduce(
+		(sum, skill) => sum + skill.name.length + skill.description.length + skill.filePath.length + 20,
+		0,
+	);
+	if (skillsCharacters > 0) {
+		items.push({ label: `Skills catalog (${visibleSkills.length} skills)`, estimatedTokens: toCeilTokens(skillsCharacters) });
+	}
+
+	const contextFiles = options.contextFiles ?? [];
+	const contextFilesCharacters = contextFiles.reduce((sum, file) => sum + file.path.length + file.content.length + 40, 0);
+	if (contextFilesCharacters > 0) {
+		items.push({
+			label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`,
+			estimatedTokens: toCeilTokens(contextFilesCharacters),
+		});
+	}
+
+	const knownCharacters = toolSnippetsCharacters + skillsCharacters + contextFilesCharacters;
+	const remainderCharacters = Math.max(0, totalCharacters - knownCharacters);
+	if (remainderCharacters > 0 || items.length === 0) {
+		items.push({ label: "Base template, guidelines, and formatting", estimatedTokens: toCeilTokens(remainderCharacters) });
+	}
+
+	return items;
+}
+
+/** Wraps a cached before_agent_start observation into the basePrompt ContextSegment -- `unknown` before any turn has run yet, so a display layer never mistakes "not observed yet" for "measured and empty". */
+export function basePromptSegment(estimatedTokens: number | null, items: ContextSegmentItem[]): ContextSegment {
+	return {
+		key: "basePrompt",
+		label: estimatedTokens === null ? "Base system prompt (not observed yet)" : "Base system prompt (Pi + host instructions)",
+		estimatedTokens: estimatedTokens ?? 0,
+		confidence: "exact-structural",
+		...(estimatedTokens === null ? { unknown: true } : {}),
+		...(items.length > 0 ? { items } : {}),
+	};
+}
+
+/** Wraps a buildMessageHistoryTree() result into the messageHistory ContextSegment -- only the active-path token sum counts toward the segment total; an abandoned /tree branch still appears in items but contributes zero. */
+export function messageHistorySegment(tree: MessageHistoryTree): ContextSegment {
+	return {
+		key: "messageHistory",
+		label: "Conversation message history",
+		estimatedTokens: tree.activeTokens,
+		confidence: "exact-structural",
+		...(tree.items.length > 0 ? { items: tree.items } : {}),
+	};
+}
+
+export interface ContextBreakdown {
+	/** Real usage from ctx.getContextUsage() -- ground truth, not estimated. Null only when Pi has no usage yet (e.g. before the first turn). */
+	totalTokens: number | null;
+	/** From ctx.model.contextWindow. Null when the active model's context window is unknown. */
+	contextWindow: number | null;
+	/** contextWindow - reserveTokens, mirroring Pi's own compaction-trigger formula. Null when contextWindow is unknown. */
+	effectiveBudget: number | null;
+	/**
+	 * How much the known segments (Jittor's own plus whatever else was contributed) exceed the
+	 * real total, when they do. Zero means no overshoot. This must stay visible rather than only
+	 * being absorbed into "unaccounted" clamping to zero -- a clamped-to-zero unaccounted segment
+	 * does NOT mean wire-protocol overhead is actually free; it means the other segments already
+	 * consumed the entire real budget on paper. Hiding that distinction would make a genuinely
+	 * nonzero cost look like zero.
+	 */
+	overshootTokens: number;
+	/** Every input segment, in the order given, plus "other" absorbing whatever real usage the rest don't account for. */
+	segments: ContextSegment[];
+}
+
+export interface ComposeContextBreakdownInput {
+	totalTokens: number | null;
+	contextWindow: number | null;
+	reserveTokens?: number;
+	/** Every segment currently known: Jittor's own directly-computed ones (basePrompt, messageHistory, toolDefinitions) plus whatever else was contributed on CONTEXT_HUB_CONTRIBUTION_CHANNEL (e.g. Papyrus's rules/tasks). Order is preserved for rendering. */
+	segments: ContextSegment[];
+}
+
+/**
+ * Composes every segment currently known (Jittor's own, plus whatever any extension
+ * contributed) against the real total Pi reports, deriving "unaccounted" (genuine
+ * wire-protocol overhead -- message envelope/role wrapping, cache-control markers -- which
+ * really is invisible to any extension) as the remainder. The remainder is clamped to zero
+ * rather than shown negative -- char/4 token estimation is approximate, and a small overshoot
+ * in the known segments must not display as a nonsensical negative bucket -- but the clamp
+ * amount itself is preserved as overshootTokens rather than silently discarded, so a consumer
+ * can tell "genuinely zero" apart from "our other estimates already exceeded the real total".
+ * When the real total is unavailable, unaccounted is reported as zero and totalTokens surfaces
+ * as null so callers can label the whole breakdown as estimate-only rather than silently
+ * treating a partial sum as ground truth.
+ */
+export function composeContextBreakdown(input: ComposeContextBreakdownInput): ContextBreakdown {
+	const reserveTokens = input.reserveTokens ?? CONTEXT_DEFAULT_RESERVE_TOKENS;
+	const knownTokens = input.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	const overshootTokens = input.totalTokens === null ? 0 : Math.max(0, knownTokens - input.totalTokens);
+	const other: ContextSegment = {
+		key: "other",
+		label:
+			overshootTokens > 0
+				? `Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead) -- estimate overshoot: other segments' estimates already exceed the real total by ~${overshootTokens} tokens, so this is a floor, not a real zero`
+				: "Unaccounted (message envelope, cache-control markers, and other wire-protocol overhead)",
+		estimatedTokens: input.totalTokens === null ? 0 : Math.max(0, input.totalTokens - knownTokens),
+		confidence: "correlated",
+	};
+	return {
+		totalTokens: input.totalTokens,
+		contextWindow: input.contextWindow,
+		effectiveBudget: input.contextWindow === null ? null : Math.max(0, input.contextWindow - reserveTokens),
+		overshootTokens,
+		segments: [...input.segments, other],
+	};
+}