@danypops/pi-jittor 0.1.0 → 0.2.0

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

@@ -0,0 +1,40 @@
+import {
+	CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT,
+	validateContextContribution,
+	type ContextSegment,
+} from "@danypops/jittor";
+
+/**
+ * Merges Jittor's own directly-computed segments (tool ledger, real usage) with whatever
+ * segments other extensions contributed on CONTEXT_HUB_CONTRIBUTION_CHANNEL for the current
+ * session. Keeps only the latest contribution per producer -- a producer re-emits every turn
+ * (mirroring Papyrus's own context-injection.v1 cadence), so an older segment from the same
+ * producer is stale, not a second real contributor.
+ */
+export class ContextHubCapability {
+	private readonly latestByProducer = new Map<string, ContextSegment>();
+	private readonly seen = new Set<string>();
+
+	/** Validates and records one contribution; silently drops a malformed, stale, or duplicate one without retaining its payload or crashing the caller. */
+	observe(payload: unknown, now = Date.now()): void {
+		try {
+			const contribution = validateContextContribution(payload, now);
+			const key = `${contribution.producerName}:${contribution.sequence}`;
+			if (this.seen.has(key)) return;
+			this.seen.add(key);
+			if (this.seen.size > CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT) this.seen.delete(this.seen.values().next().value!);
+			this.latestByProducer.set(contribution.producerName, contribution.segment);
+		} catch {
+			// Reject malformed or stale cross-extension contributions without retaining payloads.
+		}
+	}
+
+	contributedSegments(): ContextSegment[] {
+		return [...this.latestByProducer.values()];
+	}
+
+	reset(): void {
+		this.latestByProducer.clear();
+		this.seen.clear();
+	}
+}

package/extension/src/context-breakdown.ts

@@ -0,0 +1,316 @@
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_DEFAULT_RESERVE_TOKENS, CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_NODES, type ContextSegment, type ContextSegmentItem } from "@danypops/jittor";
+
+/**
+ * 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],
+	};
+}

package/extension/src/context-report.ts

@@ -0,0 +1,49 @@
+import { buildContextRows, type ContextSegment as MalevichContextSegment } from "malevich-tui-components";
+import type { ContextBreakdown } from "./context-breakdown.ts";
+import type { ContextSegment } from "@danypops/jittor";
+
+/** Bounds how many items render per segment in the plain-text fallback -- a notify-mode report is a scan-at-a-glance summary, not a full dump (the interactive TUI view has no such cap, since it scrolls). */
+const MAX_ITEMS_PER_SEGMENT_LINE = 5;
+
+function formatTokens(tokens: number): string {
+	return tokens >= 1_000 ? `${(tokens / 1_000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+/** Malevich's row builder is confidence-unaware (it's a generic segment/item shape); folding the tier into the label is how it survives into the rendered row text, e.g. "Active Rules [exact-cooperative]". */
+function withConfidenceLabel(segment: ContextSegment): MalevichContextSegment {
+	const items = [...(segment.items ?? [])].sort((left, right) => right.estimatedTokens - left.estimatedTokens).slice(0, MAX_ITEMS_PER_SEGMENT_LINE);
+	return { key: segment.key, label: `${segment.label} [${segment.confidence}]`, estimatedTokens: segment.estimatedTokens, items, unknown: segment.unknown };
+}
+
+/**
+ * Plain-text Context Hub report (non-TUI fallback): real usage against the model's effective
+ * (reserve-adjusted) budget first -- matching Papyrus's own real-vs-estimate honesty accounting
+ * -- an explicit overshoot warning when the known segments' estimates exceed the real total, then
+ * every segment heaviest-first. Malevich's buildContextRows renders segments in the order given,
+ * so sorting by weight is this function's own policy, not Malevich's.
+ */
+export function buildContextReport(breakdown: ContextBreakdown): string {
+	const lines: string[] = [];
+	if (breakdown.totalTokens !== null && breakdown.effectiveBudget !== null) {
+		lines.push(`Real usage: ${formatTokens(breakdown.totalTokens)} / ${formatTokens(breakdown.effectiveBudget)} tokens (${percentOf(breakdown.totalTokens, breakdown.effectiveBudget)} of usable budget)`);
+	} else if (breakdown.totalTokens !== null) {
+		lines.push(`Real usage: ${formatTokens(breakdown.totalTokens)} tokens (model context window unknown)`);
+	} else {
+		lines.push("Real usage: not yet reported -- sizes below are estimates only");
+	}
+	if (breakdown.overshootTokens > 0) lines.push(`Estimates exceed real total by ~${breakdown.overshootTokens} tok -- sizes below are approximate, not exact`);
+
+	const sorted = [...breakdown.segments].sort((left, right) => right.estimatedTokens - left.estimatedTokens).map(withConfidenceLabel);
+	const rows = buildContextRows(sorted, breakdown.totalTokens ?? undefined);
+	if (rows.length === 0) {
+		lines.push("", "(no segments observed yet)");
+		return lines.join("\n");
+	}
+	lines.push("");
+	for (const row of rows) lines.push(row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`);
+	return lines.join("\n");
+}

package/extension/src/context-view.ts

@@ -0,0 +1,108 @@
+import type { ExtensionCommandContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { buildContextRows, renderContextRowLines, renderContextUsageBar, type ContextBarTheme, type ContextRow, type ContextRowsTheme, type ContextSegment as MalevichContextSegment } from "malevich-tui-components";
+import type { ContextSegment } from "@danypops/jittor";
+import type { ContextBreakdown } from "./context-breakdown.ts";
+import { buildContextReport } from "./context-report.ts";
+
+const VISIBLE_ROWS = 24;
+
+/**
+ * A dynamically-contributed segment set (any string key from any extension, not a fixed enum)
+ * can't use a hardcoded per-key color map the way Papyrus's own ContextViewport did for its
+ * fixed seven segments -- this cycles a small categorical palette keyed by a stable hash of the
+ * segment key, so the same key always renders the same color within one process without needing
+ * every possible contributor's key to be known in advance.
+ */
+const PALETTE: ThemeColor[] = ["accent", "success", "syntaxFunction", "warning", "syntaxKeyword", "syntaxType", "muted"];
+
+function paletteColor(key: string): ThemeColor {
+	let hash = 0;
+	for (let index = 0; index < key.length; index += 1) hash = (hash * 31 + key.charCodeAt(index)) >>> 0;
+	return PALETTE[hash % PALETTE.length]!;
+}
+
+function formatTokenCount(tokens: number): string {
+	return tokens >= 1_000 ? `${(tokens / 1_000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+/** Folds each segment's confidence tier into its label so it survives Malevich's confidence-unaware row builder. */
+function withConfidenceLabel(segment: ContextSegment): MalevichContextSegment {
+	return { key: segment.key, label: `${segment.label} [${segment.confidence}]`, estimatedTokens: segment.estimatedTokens, items: segment.items, unknown: segment.unknown };
+}
+
+class ContextViewport {
+	private offsetY = 0;
+	private readonly rows: ContextRow[];
+	private readonly segments: readonly MalevichContextSegment[];
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly breakdown: ContextBreakdown,
+		private readonly close: () => void,
+	) {
+		// Heaviest-first: Malevich renders segments in the order given, so sorting by weight for a
+		// merged multi-producer view is this viewport's own policy, matching context-report.ts.
+		this.segments = [...breakdown.segments].sort((left, right) => right.estimatedTokens - left.estimatedTokens).map(withConfidenceLabel);
+		this.rows = buildContextRows(this.segments, breakdown.totalTokens ?? undefined);
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const theme = this.theme;
+		const contentWidth = Math.max(1, width);
+		const border = theme.fg("borderMuted", "─".repeat(contentWidth));
+		const lines: string[] = [border, truncateToWidth(theme.fg("accent", theme.bold("Context")), contentWidth, "")];
+
+		const { totalTokens, effectiveBudget } = this.breakdown;
+		if (totalTokens !== null && effectiveBudget !== null) {
+			lines.push(truncateToWidth(`${formatTokenCount(totalTokens)} / ${formatTokenCount(effectiveBudget)} tokens (${percentOf(totalTokens, effectiveBudget)} of usable budget)`, contentWidth, ""));
+		} else if (totalTokens !== null) {
+			lines.push(truncateToWidth(`${formatTokenCount(totalTokens)} tokens (model context window unknown)`, contentWidth, ""));
+		} else {
+			lines.push(theme.fg("dim", "No real usage reported yet — sizes below are estimates only"));
+		}
+
+		const colorFor = (key: string) => (s: string) => theme.fg(paletteColor(key), s);
+		const barTheme: ContextBarTheme = { colorFor, empty: (s) => theme.fg("dim", s) };
+		lines.push(renderContextUsageBar(barTheme, this.segments, contentWidth, effectiveBudget ?? undefined, totalTokens ?? undefined));
+		if (this.breakdown.overshootTokens > 0) {
+			lines.push(truncateToWidth(theme.fg("warning", `Estimates exceed real total by ~${this.breakdown.overshootTokens} tok — sizes below are approximate, not exact`), contentWidth, ""));
+		}
+		lines.push("");
+
+		const rowsTheme: ContextRowsTheme = { colorFor, header: (s) => theme.bold(s) };
+		const visible = this.rows.slice(this.offsetY, this.offsetY + VISIBLE_ROWS);
+		lines.push(...renderContextRowLines(visible, contentWidth, rowsTheme));
+		if (this.rows.length === 0) lines.push(theme.fg("dim", "  (nothing observed yet)"));
+		else lines.push(theme.fg("muted", `  ${Math.min(this.offsetY + VISIBLE_ROWS, this.rows.length)}/${this.rows.length}`));
+
+		lines.push("");
+		lines.push(theme.fg("dim", "↑↓ scroll · esc close"));
+		lines.push(border);
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) { this.close(); return; }
+		if (matchesKey(data, "up")) this.offsetY = Math.max(0, this.offsetY - 1);
+		else if (matchesKey(data, "down")) this.offsetY = Math.min(Math.max(0, this.rows.length - VISIBLE_ROWS), this.offsetY + 1);
+		else return;
+		this.tui.requestRender();
+	}
+}
+
+/** Interactive scrollable Context Hub view in TUI mode; the same plain-text report as /context's non-interactive path otherwise. */
+export async function showContextView(ctx: ExtensionCommandContext, breakdown: ContextBreakdown): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(buildContextReport(breakdown), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new ContextViewport(tui, theme, breakdown, done));
+}

package/extension/src/footer.ts

@@ -1,6 +1,7 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { ProgressBar } from "malevich-tui-components";
 import {
 	FOOTER_BAR_MAX_WIDTH,
 	FOOTER_BAR_MIN_WIDTH,
@@ -119,11 +120,11 @@ function barWidth(width: number): number {
 	return width >= FOOTER_WIDE_TERMINAL_WIDTH ? FOOTER_BAR_MAX_WIDTH : FOOTER_BAR_MIN_WIDTH;
 }
 
+// Thin wrapper over Malevich's ProgressBar.format() -- keeps this file's own call sites
+// (fraction-first, width-second, tolerant of null/non-finite) unchanged.
 function progressBar(fraction: number | null, width: number): string {
-	if (fraction === null || !Number.isFinite(fraction)) return "░".repeat(width);
-	const clamped = Math.min(1, Math.max(0, fraction));
-	const filled = Math.round(width * clamped);
-	return "█".repeat(filled) + "░".repeat(width - filled);
+	const value = fraction === null || !Number.isFinite(fraction) ? 0 : fraction;
+	return new ProgressBar({ value, max: 1, width }).format(width);
 }
 
 function fillColor(fraction: number | null): FooterColor {

package/extension/src/index.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
+	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
+	CONTEXT_HUB_CONTRIBUTION_CHANNEL,
 	FOOTER_COMPACTION_RENDER_INTERVAL_MS,
 	MAX_DYNAMIC_ROUTES,
 	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
@@ -10,6 +12,7 @@ import {
 	validatePapyrusContextInjection,
 	applyTaskFocusEvent,
 	validateTaskFocusEvent,
+	toolLedgerSegment,
 	TASK_DOMAINS,
 	TASK_TYPES,
 	USAGE_PERIODS,
@@ -35,6 +38,10 @@ import { showUsagePanel } from "./usage.ts";
 import { CodexRecoveryCapability, SYSTEM_RECOVERY_RUNTIME, type CodexRecoveryRuntime } from "./capabilities/codex-recovery.ts";
 import { ProviderResponseTelemetry } from "./capabilities/provider-response-telemetry.ts";
 import { LocalRunTelemetry } from "./capabilities/local-run-telemetry.ts";
+import { ContextHubCapability } from "./capabilities/context-hub.ts";
+import { basePromptSegment, buildBasePromptItems, buildMessageHistoryTree, composeContextBreakdown, messageHistorySegment, type SessionEntryLike, type SessionTreeNodeLike } from "./context-breakdown.ts";
+import { showContextView } from "./context-view.ts";
+import type { ContextSegmentItem } from "@danypops/jittor";
 
 export { formatFooterStatus } from "./tui.ts";
 export type { CodexRecoveryRuntime } from "./capabilities/codex-recovery.ts";
@@ -253,6 +260,14 @@ export function registerJittorExtension(
 	const localRunTelemetry = new LocalRunTelemetry();
 	const providerResponseTelemetry = new ProviderResponseTelemetry();
 	const codexRecoveryCapability = new CodexRecoveryCapability(pi, codexRecovery, recoveryRuntime);
+	const contextHub = new ContextHubCapability();
+	const stopContextHub = pi.events?.on?.(CONTEXT_HUB_CONTRIBUTION_CHANNEL, (payload) => contextHub.observe(payload));
+	// Cached from the most recent before_agent_start observation: Pi's own base system prompt is
+	// only ever visible transiently inside that hook's event, so /context reuses this rather than
+	// going without it entirely. Measured as of THIS extension's own place in the before_agent_start
+	// chain -- see buildBasePromptItems' own doc comment for the load-order caveat this implies.
+	let lastObservedBasePromptTokens: number | null = null;
+	let lastObservedBasePromptItems: ContextSegmentItem[] = [];
 	const contextObservations = new Set<string>();
 	const stopPapyrusContext = pi.events?.on?.(PAPYRUS_CONTEXT_INJECTION_CHANNEL, (payload) => {
 		try {
@@ -458,6 +473,30 @@ export function registerJittorExtension(
 		},
 	});
 
+	pi.registerCommand("context", {
+		description: "Context Hub: real usage plus every segment's estimated size (base prompt, message history, tool schemas by owning extension, and whatever other extensions contributed), each tagged with how it was attributed",
+		handler: async (_args, ctx) => {
+			const activeToolNames = new Set(pi.getActiveTools());
+			const toolSegment = toolLedgerSegment(pi.getAllTools().filter((tool) => activeToolNames.has(tool.name)));
+			// Real tree (not just the linear current-branch path): surfaces content sitting in an
+			// abandoned /tree branch, which cost real tokens to generate but isn't in context now.
+			const tree = ctx.sessionManager.getTree() as SessionTreeNodeLike[];
+			// buildContextEntries(), NOT getBranch(): getBranch() returns every raw entry on the current
+			// path including everything a real compaction has already summarized away.
+			const activeEntryIds = new Set((ctx.sessionManager.buildContextEntries() as SessionEntryLike[]).map((entry) => entry.id));
+			const branchEntryIds = new Set((ctx.sessionManager.getBranch() as SessionEntryLike[]).map((entry) => entry.id));
+			const messageHistory = buildMessageHistoryTree(tree, activeEntryIds, branchEntryIds);
+			const usage = ctx.getContextUsage();
+			const ownSegments = [basePromptSegment(lastObservedBasePromptTokens, lastObservedBasePromptItems), messageHistorySegment(messageHistory), toolSegment];
+			const breakdown = composeContextBreakdown({
+				totalTokens: usage?.tokens ?? null,
+				contextWindow: ctx.model?.contextWindow ?? null,
+				segments: [...ownSegments, ...contextHub.contributedSegments()],
+			});
+			await showContextView(ctx, breakdown);
+		},
+	});
+
 	pi.registerCommand("usage", {
 		description: "Cumulative token/cost usage graph with hourly/daily/weekly/monthly/quarterly views",
 		handler: async (args, ctx) => {
@@ -502,6 +541,7 @@ export function registerJittorExtension(
 		finishCompactionUi();
 		compactionTelemetry = new CompactionTelemetry();
 		localRunTelemetry.reset();
+		contextHub.reset();
 		cancelRecovery(true);
 		providerResponseTelemetry.resetTurn();
 		ctx.ui.setStatus("jittor", undefined);
@@ -526,6 +566,15 @@ export function registerJittorExtension(
 		}
 	});
 
+	pi.on("before_agent_start", async (event) => {
+		// No new hook, no new risk: measures event.systemPrompt's length and structural
+		// event.systemPromptOptions as-of this handler's own place in the before_agent_start chain --
+		// see buildBasePromptItems' own doc comment for the resulting load-order caveat.
+		const characters = (event.systemPrompt ?? "").length;
+		lastObservedBasePromptTokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		lastObservedBasePromptItems = buildBasePromptItems(event.systemPromptOptions, characters);
+	});
+
 	pi.on("session_before_compact", async (event, ctx) => {
 		beginCompactionUi(ctx, event.signal);
 		const usage = ctx.getContextUsage();
@@ -642,6 +691,7 @@ export function registerJittorExtension(
 		if (compactionTelemetry.hasOpenCompaction()) await recordMetrics(client, [compactionTelemetry.abort(Date.now(), "session-shutdown")]).catch(() => undefined);
 		stopPapyrusContext?.();
 		stopPapyrusTaskFocus?.();
+		stopContextHub?.();
 		cancelRecovery(true);
 		localRunTelemetry.reset();
 		const session_id = ctx.sessionManager.getSessionId();

package/extension/src/service-client.ts

@@ -1,4 +1,4 @@
-import { createRetryingClient, type RetryingClient } from "@danypops/daemon-kit/pi-client";
+import { createRetryingClient, type RetryingClient } from "@danypops/vehicle-client/daemon-client";
 import { connectJittorClient, type JittorClient, type OperationInputs, type OperationName, type OperationOutputs } from "@danypops/jittor";
 
 type JittorConnector = () => Promise<JittorClient>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-jittor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension for Jittor: native routing enforcement, footer, settings, usage graphs, and benchmark panels backed by the @danypops/jittor daemon",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
@@ -12,8 +12,9 @@
     "extensions": ["extension/src/index.ts"]
   },
   "dependencies": {
-    "@danypops/daemon-kit": "^0.4.0",
-    "@danypops/jittor": "^0.12.0"
+    "@danypops/vehicle-client": "^0.1.1",
+    "@danypops/jittor": "^0.14.0",
+    "malevich-tui-components": "^0.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",