@danypops/pi-papyrus 0.38.5 → 0.40.0

package/extension/src/context-budget.ts

@@ -1,9 +1,19 @@
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
+import type { ContextSegmentItem } from "@danypops/jittor";
 import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_NODES, type Artifact, type TaskGraph } from "@danypops/papyrus";
 import { discoverSkillDirectories, scanSkillCatalogFootprint, type SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
 import { ruleInjectionPreview } from "./rules.ts";
 
+/**
+ * Papyrus's own real data for the Context Hub: Rules injection cost, the Task containment tree,
+ * and the Pi Skills catalog footprint -- contributed to Jittor's Context Hub as one segment
+ * (context-hub-contribution.ts) instead of rendering a whole breakdown locally. The Pi-generic
+ * segments (base prompt, message history, tool definitions) and the composer that reconciles
+ * every producer's segments against the real total now live in pi-jittor's own
+ * context-breakdown.ts.
+ */
+
 export interface RuleBudgetEntry {
 	id: string;
 	title: string;
@@ -59,295 +69,11 @@ export function computeContextBudget(
 	return { rules: ruleBudget, skills, totalEstimatedTokens: ruleBudget.totalEstimatedTokens + skills.totalEstimatedTokens };
 }
 
-/** Pi's own documented compaction-reserve default (docs/compaction.md): headroom kept free for the model's response. */
-export const DEFAULT_RESERVE_TOKENS = 16_384;
-
-export interface ContextSegmentItem {
-	label: string;
-	estimatedTokens: number;
-	/**
-	 * Recursive children, when this item has real hierarchy of its own -- conversation history
-	 * (Pi's session entries form a genuine tree via id/parentId, docs/session-format.md) and
-	 * Papyrus Tasks (containment via parentIds/childIds) both do; Rules and Skills don't, so
-	 * their items simply omit this field, degenerating to a flat one-level tree.
-	 */
-	children?: ContextSegmentItem[];
-}
-
-export interface ContextSegment {
-	key: "rules" | "tasks" | "skills" | "basePrompt" | "messageHistory" | "toolDefinitions" | "other";
-	label: string;
-	estimatedTokens: number;
-	/** Drill-down items, when this segment can be broken down further. Absent for "other" -- an opaque remainder, not a real category. */
-	items?: ContextSegmentItem[];
-	/**
-	 * True when this segment's size is genuinely unmeasured (not yet observed), as opposed to
-	 * measured-and-actually-zero. A display layer that hides zero-token rows to cut noise must
-	 * NOT hide an unknown segment just because its placeholder value happens to be zero --
-	 * that would silently misrepresent "we don't know" as "there is nothing here", the same
-	 * category of honesty problem overshootTokens exists to prevent for the unaccounted bucket.
-	 */
-	unknown?: boolean;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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):
- * a session file is external, mutable state, and this deliberately hardens past a confirmed
- * real gap in Pi's own getBranch() (no cycle guard at all) rather than assuming the tree can
- * never be malformed.
- *
- * `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. A real session with 3 compactions confirmed using getBranch() here
- * overcounts activeTokens by over 13x, since every pre-compaction message still reads as
- * "active". 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).
- */
-interface WalkFrame {
-	node: SessionTreeNodeLike;
-	parentIndex: number | null;
-}
-
-/**
- * Iterative (not recursive) two-pass walk: an explicit-stack pre-order discovery pass
- * followed by a reverse-order (children-before-parent) construction pass. A real, ordinary
- * (non-branching) long-running session is one long linear chain, so recursion depth would
- * equal entry count -- a session observed in production with 6,924 entries on its own active
- * branch confirmed this is not a hypothetical concern; a naive recursive walk risks a real
- * JavaScript call-stack overflow at that scale, independent of the CONTEXT_TREE_MAX_NODES
- * bound entirely.
- */
-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 };
-}
-
-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/estimated segments (rules+tasks+skills+basePrompt+messageHistory+
-	 * toolDefinitions) 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 this estimate's other segments already consumed the entire real budget on paper.
-	 * Hiding that distinction would make a genuinely nonzero cost look like zero.
-	 */
-	overshootTokens: number;
-	/** rules, tasks, skills, basePrompt, messageHistory, toolDefinitions, then "other" absorbing whatever real usage the rest don't account for. */
-	segments: ContextSegment[];
-}
-
-export interface BuildContextBreakdownInput {
-	totalTokens: number | null;
-	contextWindow: number | null;
-	reserveTokens?: number;
-	ruleBudget: ContextBudget["rules"];
-	/** Open tasks contributing to the injected task-context summary, nested by containment (parentIds/childIds) so the Tasks segment reflects the real Task tree, not a flat list. */
-	taskItems: ContextSegmentItem[];
-	skills: SkillCatalogFootprint;
-	/** Pi's own base system prompt size, cached from the last observed before_agent_start turn. Null before any turn has run yet. */
-	basePromptEstimatedTokens: number | null;
-	/** Structural sub-breakdown (tool snippets, Skills, context files, template remainder) from the same cached observation, built by buildBasePromptItems(). Empty when basePromptEstimatedTokens is null. */
-	basePromptItems?: ContextSegmentItem[];
-	/** From buildMessageHistoryTree() against the live session's real tree (ctx.sessionManager.getTree()). */
-	messageHistoryItems: ContextSegmentItem[];
-	/** buildMessageHistoryTree()'s activeTokens -- only entries on the current active path count toward the segment total; an abandoned /tree branch still appears in messageHistoryItems but contributes zero here. */
-	messageHistoryActiveTokens: number;
-	/** From buildToolDefinitionItems() against pi.getAllTools() filtered to pi.getActiveTools(). Defaults to empty when omitted. */
-	toolDefinitionItems?: ContextSegmentItem[];
-}
-
 /** Sums a possibly-nested item tree's tokens recursively -- every node's own contribution, not just top-level items. */
-function sumItemTree(items: ContextSegmentItem[]): number {
+export function sumItemTree(items: ContextSegmentItem[]): number {
 	return items.reduce((sum, item) => sum + item.estimatedTokens + sumItemTree(item.children ?? []), 0);
 }
 
-/** The subset of pi.getAllTools()'s ToolInfo this estimate actually reads -- kept minimal so this stays testable with plain object literals instead of importing Pi's own extension types. */
-export interface ActiveToolDefinitionLike {
-	name: string;
-	description: string;
-	parameters: unknown;
-	sourceInfo: { source: string };
-}
-
-/**
- * Tool definitions (name + description + JSON schema) are actually measurable, unlike genuine
- * wire-protocol framework overhead (message envelope/role wrapping, cache-control markers) which
- * really is invisible to any extension -- this is what lets "other" stop absorbing them as an
- * unmeasured guess. Grouped by extension/package source with each tool as a drill-down child
- * (mirrors the Tasks segment's own parent/child shape) rather than one flat list, since a real
- * session can have dozens of active tools spread across many extensions.
- */
-export function buildToolDefinitionItems(tools: ReadonlyArray<ActiveToolDefinitionLike>): ContextSegmentItem[] {
-	const bySource = new Map<string, ActiveToolDefinitionLike[]>();
-	for (const tool of tools) {
-		const list = bySource.get(tool.sourceInfo.source) ?? [];
-		list.push(tool);
-		bySource.set(tool.sourceInfo.source, list);
-	}
-	const items: ContextSegmentItem[] = [];
-	for (const [source, toolsForSource] of bySource) {
-		const children = toolsForSource
-			.map((tool) => {
-				const characters = tool.name.length + tool.description.length + JSON.stringify(tool.parameters ?? {}).length;
-				return { label: tool.name, estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) };
-			})
-			.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
-		items.push({
-			label: `${source} (${toolsForSource.length} tool${toolsForSource.length === 1 ? "" : "s"})`,
-			estimatedTokens: children.reduce((sum, child) => sum + child.estimatedTokens, 0),
-			children,
-		});
-	}
-	return items.sort((a, b) => b.estimatedTokens - a.estimatedTokens);
-}
-
 /**
  * Builds the Tasks segment's items from Papyrus's own real containment tree (parentIds/
  * childIds), not a flat list -- Tasks are a genuine DAG (a task may have more than one
@@ -365,7 +91,7 @@ interface TaskWalkFrame {
 	parentIndex: number | null;
 }
 
-/** Same iterative two-pass shape as buildMessageHistoryTree, for the same reason: don't assume containment depth stays small just because it usually does. */
+/** Bounded, iterative two-pass walk (an explicit-stack pre-order discovery pass, then a reverse-order construction pass) -- containment depth is not assumed to stay small just because it usually does. */
 export function buildTaskItemTree(graph: TaskGraph): ContextSegmentItem[] {
 	const byId = new Map(graph.nodes.map((node) => [node.task.id, node]));
 	const openIds = new Set(graph.nodes.filter((node) => node.task.status !== "done" && node.task.status !== "canceled").map((node) => node.task.id));
@@ -419,83 +145,3 @@ export function buildTaskItemTree(graph: TaskGraph): ContextSegmentItem[] {
 	}
 	return items;
 }
-
-/**
- * Composes every segment Papyrus can actually measure or estimate (rules, tasks, skills
- * catalog, cached base-prompt size, active tool definitions, and the live session's own
- * message history) 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 buildContextBreakdown(input: BuildContextBreakdownInput): ContextBreakdown {
-	const reserveTokens = input.reserveTokens ?? DEFAULT_RESERVE_TOKENS;
-	const rules: ContextSegment = {
-		key: "rules",
-		label: "Papyrus Rules",
-		estimatedTokens: input.ruleBudget.totalEstimatedTokens,
-		items: input.ruleBudget.entries.map((entry) => ({ label: entry.title, estimatedTokens: entry.estimatedTokens })),
-	};
-	const tasks: ContextSegment = {
-		key: "tasks",
-		label: "Papyrus Tasks",
-		estimatedTokens: sumItemTree(input.taskItems),
-		items: input.taskItems,
-	};
-	const skills: ContextSegment = {
-		key: "skills",
-		label: "Pi Skills catalog",
-		estimatedTokens: input.skills.totalEstimatedTokens,
-		items: input.skills.entries.map((entry) => ({ label: entry.name, estimatedTokens: entry.estimatedTokens })),
-	};
-	const basePrompt: ContextSegment = {
-		key: "basePrompt",
-		label: input.basePromptEstimatedTokens === null ? "Base system prompt (not observed yet)" : "Base system prompt (Pi + host instructions)",
-		estimatedTokens: input.basePromptEstimatedTokens ?? 0,
-		...(input.basePromptEstimatedTokens === null ? { unknown: true } : {}),
-		...(input.basePromptItems && input.basePromptItems.length > 0 ? { items: input.basePromptItems } : {}),
-	};
-	const messageHistory: ContextSegment = {
-		key: "messageHistory",
-		label: "Conversation message history",
-		estimatedTokens: input.messageHistoryActiveTokens,
-		items: input.messageHistoryItems,
-	};
-	const toolDefinitionItems = input.toolDefinitionItems ?? [];
-	const toolCount = toolDefinitionItems.reduce((sum, item) => sum + (item.children?.length ?? 1), 0);
-	const toolDefinitions: ContextSegment = {
-		key: "toolDefinitions",
-		label: `Active tool definitions (${toolCount} tool${toolCount === 1 ? "" : "s"})`,
-		// Top-level sum only, NOT sumItemTree: unlike Tasks/message-history, whose parent nodes
-		// carry their own independent content genuinely additive with their children, a
-		// buildToolDefinitionItems() group node's own estimatedTokens IS the sum of its children
-		// (by construction, for a meaningful collapsed-row total) -- summing the tree here would
-		// double-count every tool once as itself and once inside its group's total.
-		estimatedTokens: toolDefinitionItems.reduce((sum, item) => sum + item.estimatedTokens, 0),
-		...(toolDefinitionItems.length > 0 ? { items: toolDefinitionItems } : {}),
-	};
-	const knownTokens = rules.estimatedTokens + tasks.estimatedTokens + skills.estimatedTokens + basePrompt.estimatedTokens + messageHistory.estimatedTokens + toolDefinitions.estimatedTokens;
-	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),
-	};
-	return {
-		totalTokens: input.totalTokens,
-		contextWindow: input.contextWindow,
-		effectiveBudget: input.contextWindow === null ? null : Math.max(0, input.contextWindow - reserveTokens),
-		overshootTokens,
-		segments: [rules, tasks, skills, basePrompt, messageHistory, toolDefinitions, other],
-	};
-}
-
-

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

@@ -0,0 +1,42 @@
+import type { ContextSegment, ContextSegmentItem } from "@danypops/jittor";
+import { sumItemTree, type ContextBudget } from "./context-budget.ts";
+import type { SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
+
+/** Human-readable producer identity on Jittor's Context Hub bus -- distinct from PAPYRUS_CONTEXT_INJECTION_CHANNEL's own opaque per-process producerId, which identifies a specific injection stream rather than "which extension". */
+export const PAPYRUS_CONTEXT_HUB_PRODUCER_NAME = "papyrus";
+
+/**
+ * Bundles Rules + Tasks + Skills catalog into ONE contributed ContextSegment. Jittor's
+ * ContextHubCapability keeps only the latest segment per producer (a producer re-emits every
+ * turn, mirroring papyrus.context-injection.v1's own cadence), so contributing three separate
+ * top-level segments would need three fake producer identities instead of Papyrus's one real
+ * one -- nested as up to three drill-down item groups under a single "papyrus" segment instead,
+ * preserving the same per-category fidelity the original local /context breakdown had.
+ */
+export function papyrusContextSegment(ruleBudget: ContextBudget["rules"], taskItems: ContextSegmentItem[], skills: SkillCatalogFootprint): ContextSegment {
+	const items: ContextSegmentItem[] = [];
+	if (ruleBudget.entries.length > 0) {
+		items.push({
+			label: "Active Rules",
+			estimatedTokens: ruleBudget.totalEstimatedTokens,
+			children: ruleBudget.entries.map((entry) => ({ label: entry.title, estimatedTokens: entry.estimatedTokens })),
+		});
+	}
+	if (taskItems.length > 0) {
+		items.push({ label: "Open Tasks", estimatedTokens: sumItemTree(taskItems), children: taskItems });
+	}
+	if (skills.entries.length > 0) {
+		items.push({
+			label: "Pi Skills catalog",
+			estimatedTokens: skills.totalEstimatedTokens,
+			children: skills.entries.map((entry) => ({ label: entry.name, estimatedTokens: entry.estimatedTokens })),
+		});
+	}
+	return {
+		key: "papyrus",
+		label: "Papyrus (Rules, Tasks, Skills)",
+		estimatedTokens: items.reduce((sum, item) => sum + item.estimatedTokens, 0),
+		confidence: "exact-cooperative",
+		...(items.length > 0 ? { items } : {}),
+	};
+}

package/extension/src/domain-tools.ts

@@ -540,121 +540,9 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 	});
 }
 
-// notes.* is registered as a real Vehicle (see ../vehicle-notes-client.ts and index.ts),
-// not a hand-rolled pi.registerTool() -- the first domain migrated off the
-// action-dispatch mega-tool pattern this file's other tools still use.
-
-export function registerDocsTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "docs",
-		label: "Documents",
-		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project, update, remove, remove_subtree, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. update changes title/body/labels (at least one required) and is refused for a read-only external projection (e.g. web-spider-ingested Docs) -- capture a correction as a new linked Doc instead. remove moves a Doc to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline; remove_subtree extends this to a whole `contains` subtree in one call. PREFER `name` (the doc's exact title) over `id`, and `target_name` over `target_id` for link -- both are backend implementation details, resolved from name automatically (target_name searches across every kind, since a link target can be a doc, task, rule, or skill). Prefer this over low-level papyrus_* tools for document work.",
-		parameters: Type.Object({
-			action: Type.String(),
-			id: Type.Optional(Type.String()),
-			name: Type.Optional(Type.String()),
-			title: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()),
-			subtype: Type.Optional(Type.String()),
-			status: Type.Optional(Type.String()),
-			text: Type.Optional(Type.String()),
-			limit: Type.Optional(Type.Number()),
-			labels: Type.Optional(Type.Array(Type.String())),
-			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-			template_id: Type.Optional(Type.String()),
-			relation: Type.Optional(Type.String()),
-			target_id: Type.Optional(Type.String()),
-			target_name: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
-			reason: Type.Optional(Type.String()),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Documents", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				const scopeRequest = { project_root: params.project_root };
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "docs.list", baseRequest: scopeRequest },
-					// Kind-agnostic: a link target can be a doc, task, rule, or skill, so this searches every kind rather than only docs.
-					{ nameKey: "target_name", idKey: "target_id", listOperation: "artifact.query", baseRequest: scopeRequest },
-				]);
-				if (action === "create") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("docs.create", params);
-					return text(`Created document ${artifactLine(artifact)}`, createArtifactDetails("docs.create", artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("docs.list", params);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No documents found.", createArtifactListDetails("docs.list", rows));
-				}
-				if (action === "show") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("docs.show", params);
-					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("docs.show", artifact));
-				}
-				const trashResult = await handleArtifactRemoveRestore(action, params);
-				if (trashResult) return trashResult;
-				const operations = { activate: "docs.activate", archive: "docs.archive", reopen: "docs.reopen", link: "docs.link", assign_project: "docs.assign_project", update: "docs.update" } as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown docs action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
-				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`docs failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
-
-export function registerRulesTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "rules",
-		label: "Rules",
-		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project, update, remove, remove_subtree, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt. update changes title/body/labels (at least one required); body updates still enforce the same combined condition+action+body context-tax bound as creation, and are refused for a read-only external projection. remove moves a Rule to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline; remove_subtree extends this to a whole `contains` subtree in one call. PREFER `name` (the rule's exact title) over `id`, and `task_name` over `task_id` for gate -- both are backend implementation details, resolved from name automatically.",
-		parameters: Type.Object({
-			action: Type.String(), id: Type.Optional(Type.String()), name: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()), condition: Type.Optional(Type.String()), rule_action: Type.Optional(Type.String()),
-			severity: Type.Optional(Type.String()), labels: Type.Optional(Type.Array(Type.String())),
-			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
-			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), task_id: Type.Optional(Type.String()),
-			task_name: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Rules", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "rules.list", baseRequest: { project_root: params.project_root } },
-					{ nameKey: "task_name", idKey: "task_id", listOperation: "tasks.list", baseRequest: { project_root: params.project_root ?? ctx.cwd } },
-				]);
-				if (action === "create") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("rules.create", params);
-					return text(`Created rule ${artifactLine(artifact)}`, createArtifactDetails("rules.create", artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("rules.list", params);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No rules found.", createArtifactListDetails("rules.list", rows));
-				}
-				if (action === "preview") {
-					const preview = await callService<Record<string, unknown>, string>("rules.preview", params);
-					return text(preview, createPreviewDetails("rules.preview", "Rule preview", preview));
-				}
-				const trashResult = await handleArtifactRemoveRestore(action, params);
-				if (trashResult) return trashResult;
-				const operations = { show: "rules.show", enable: "rules.enable", disable: "rules.disable", gate: "rules.gate", assign_project: "rules.assign_project", update: "rules.update" } as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown rules action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
-				return text(`${artifactLine(artifact)}${action === "show" ? `\n\n${artifact.body}` : ""}`, createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`rules failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
+// notes.*, rules.*, docs.*, and the shared artifact.* are registered as Vehicles
+// (see ../vehicle-notes-client.ts and @danypops/papyrus's src/vehicle/papyrus-vehicle.ts),
+// not pi.registerTool()s in this file.
 
 export function registerPlaybooksTool(pi: ExtensionAPI): void {
 	pi.registerTool({
@@ -950,10 +838,12 @@ export function registerDiscussTool(pi: ExtensionAPI): void {
 }
 
 /** Thin orchestrator: each domain's tool is independently navigable/testable via its own registerXTool function. */
+// docs and rules are no longer registered here -- both migrated onto Vehicle
+// (registerNotesVehicle in vehicle-notes-client.ts, wired at session_start in
+// index.ts), replacing their own pi.registerTool() mega-tools. See
+// @danypops/papyrus's src/vehicle/papyrus-vehicle.ts for the server side.
 export function registerDomainTools(pi: ExtensionAPI): void {
 	registerTasksTool(pi);
-	registerDocsTool(pi);
-	registerRulesTool(pi);
 	registerPlaybooksTool(pi);
 	registerSkillsTool(pi);
 	registerDiscussTool(pi);

package/extension/src/index.ts

@@ -37,9 +37,9 @@ import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanI
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 import { buildContextInjection } from "./context-injection-telemetry.ts";
-import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, buildToolDefinitionItems, computeContextBudget, computeRuleBudget, DEFAULT_RESERVE_TOKENS, type ContextSegmentItem, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
-import { buildBasePromptItems } from "./base-prompt-breakdown.ts";
-import { showContextView } from "./context-view.ts";
+import { buildTaskItemTree, computeContextBudget } from "./context-budget.ts";
+import { PAPYRUS_CONTEXT_HUB_PRODUCER_NAME, papyrusContextSegment } from "./context-hub-contribution.ts";
+import { CONTEXT_DEFAULT_RESERVE_TOKENS, CONTEXT_HUB_CONTRIBUTION_CHANNEL, CONTEXT_HUB_CONTRIBUTION_SCHEMA } from "@danypops/jittor";
 import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
 import { cacheSessionSecret, forgetSessionSecret, sessionSecretField } from "./session-identity.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
@@ -327,15 +327,11 @@ export default async function (pi: ExtensionAPI) {
 	const contextInjectionProducerId = randomUUID();
 	let previousContextInjectionFingerprint: string | undefined;
 	let logTurnSequence = 0;
-	// 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.systemPrompt, so /context
-	// reuses the size buildContextInjection already computes every turn rather than going
-	// without it entirely. basePromptItems is the structural sub-breakdown built from the same
-	// event's systemPromptOptions field ("Extensions can inspect this to understand what Pi
-	// loaded without re-discovering resources", per Pi's own doc comment) -- no new hook, no new
-	// risk, just reading a field before_agent_start already hands over.
-	let lastObservedBasePromptTokens: number | null = null;
-	let lastObservedBasePromptItems: ContextSegmentItem[] = [];
+	// Papyrus's own Context Hub contribution (rules/tasks/skills, bundled into one segment --
+	// see context-hub-contribution.ts) re-emits every turn alongside the existing injection
+	// observation, its own independent monotonic sequence, same cadence and shape as
+	// contextInjectionSequence but on a different channel/schema.
+	let contextHubContributionSequence = 0;
 	const taskContinuation = new ActiveTaskContinuation({
 		maxTurns: TASK_DRIVER_MAX_TURNS,
 		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
@@ -388,7 +384,7 @@ export default async function (pi: ExtensionAPI) {
 			if (!usage || usage.tokens === null) return; // nothing real to report yet (e.g. before the first assistant turn, or right after compaction)
 			const totalTokens = usage.tokens;
 			const sessionId = ctx.sessionManager.getSessionId();
-			const effectiveBudget = Math.max(0, usage.contextWindow - DEFAULT_RESERVE_TOKENS);
+			const effectiveBudget = Math.max(0, usage.contextWindow - CONTEXT_DEFAULT_RESERVE_TOKENS);
 			const percentOfBudget = effectiveBudget > 0 ? Math.round((totalTokens / effectiveBudget) * 1000) / 10 : null;
 			await callService("logs.append", {
 				source_id: PI_SESSION_CONTEXT_LOG_SOURCE,
@@ -628,52 +624,6 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
 		handler: async (_args, ctx) => { await discussModule.showDiscussions(ctx); },
 	});
-	pi.registerCommand("context", {
-		description: "Structured, per-segment breakdown of the context window: real usage against the model's window, drilling into Papyrus Rules and the Pi-native skill catalog",
-		handler: async (_args, ctx) => {
-			try {
-				const sessionId = ctx.sessionManager.getSessionId();
-				const [rules, taskGraph] = await Promise.all([
-					callService<Record<string, unknown>, Array<Pick<Artifact, "id" | "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd, session_id: sessionId }),
-					callService<Record<string, unknown>, TaskGraph>("tasks.graph", { project_root: ctx.cwd, session_id: sessionId }),
-				]);
-				const { skills } = computeContextBudget(rules, ctx.cwd);
-				const ruleBudget = computeRuleBudget(rules);
-				const usage = ctx.getContextUsage?.();
-				// 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.
-				// A session with 3 real compactions confirmed this made "active" message-history
-				// tokens overcount the real total by over 13x -- getBranch()'s own docstring already
-				// says as much ("Use buildSessionContext() to get the resolved messages for the
-				// LLM"); buildContextEntries() is the compaction-aware entry list matching what the
-				// LLM actually sees (the latest compaction entry itself, plus kept entries from its
-				// firstKeptEntryId onward, plus everything after -- older summarized entries omitted).
-				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 activeToolNames = new Set(pi.getActiveTools());
-				const toolDefinitionItems = buildToolDefinitionItems(pi.getAllTools().filter((tool) => activeToolNames.has(tool.name)));
-				const breakdown = buildContextBreakdown({
-					totalTokens: usage?.tokens ?? null,
-					contextWindow: ctx.model?.contextWindow ?? null,
-					ruleBudget,
-					taskItems: buildTaskItemTree(taskGraph),
-					skills,
-					basePromptEstimatedTokens: lastObservedBasePromptTokens,
-					basePromptItems: lastObservedBasePromptItems,
-					toolDefinitionItems,
-					messageHistoryItems: messageHistory.items,
-					messageHistoryActiveTokens: messageHistory.activeTokens,
-				});
-				await showContextView(ctx, breakdown);
-			} catch (error) {
-				ctx.ui.notify(`Context breakdown failed: ${error instanceof Error ? error.message : error}`, "error");
-			}
-		},
-	});
 
 	// ── Task widget (TodoOverlay pattern: factory form, requestRender) ──
 
@@ -780,12 +730,14 @@ export default async function (pi: ExtensionAPI) {
 	// tasks, they're explicitly called out — the agent should address them.
 
 	pi.on("before_agent_start", async (event, ctx) => {
+		let result: { systemPrompt: string } | undefined;
 		try {
 			const sessionId = ctx.sessionManager.getSessionId();
-			const [rules, playbooks, summary] = await Promise.all([
-				callService<Record<string, unknown>, Array<Pick<Artifact, "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd, session_id: sessionId }),
+			const [rules, playbooks, summary, taskGraph] = await Promise.all([
+				callService<Record<string, unknown>, Array<Pick<Artifact, "id" | "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd, session_id: sessionId }),
 				callService<Record<string, unknown>, Array<Pick<Artifact, "title" | "extra">>>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS }),
 				callService<Record<string, unknown>, string | null>("tasks.context", { project_root: ctx.cwd, session_id: sessionId, verbosity: "summary" }),
+				callService<Record<string, unknown>, TaskGraph>("tasks.graph", { project_root: ctx.cwd, session_id: sessionId }),
 			]);
 			const injection = buildContextInjection({
 				basePrompt: event.systemPrompt ?? "",
@@ -798,12 +750,25 @@ export default async function (pi: ExtensionAPI) {
 				previousFingerprint: previousContextInjectionFingerprint,
 			});
 			previousContextInjectionFingerprint = injection.observation.fingerprint;
-			lastObservedBasePromptTokens = Math.ceil(injection.observation.before.characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
-			lastObservedBasePromptItems = buildBasePromptItems(event.systemPromptOptions, injection.observation.before.characters);
 			pi.events.emit(PAPYRUS_CONTEXT_INJECTION_CHANNEL, injection.observation);
-			if (injection.prompt !== (event.systemPrompt ?? "")) return { systemPrompt: injection.prompt };
+			if (injection.prompt !== (event.systemPrompt ?? "")) result = { systemPrompt: injection.prompt };
+			// Context Hub contribution is best-effort observability for /context -- its own failure
+			// must never block this turn's actual rules/tasks injection above.
+			try {
+				const { rules: ruleBudget, skills } = computeContextBudget(rules, ctx.cwd);
+				pi.events.emit(CONTEXT_HUB_CONTRIBUTION_CHANNEL, {
+					schema: CONTEXT_HUB_CONTRIBUTION_SCHEMA,
+					observedAt: Date.now(),
+					sequence: ++contextHubContributionSequence,
+					producerName: PAPYRUS_CONTEXT_HUB_PRODUCER_NAME,
+					segment: papyrusContextSegment(ruleBudget, buildTaskItemTree(taskGraph), skills),
+				});
+			} catch {
+				// Malformed/unreachable daemon data for this turn's contribution -- drop it silently.
+			}
 		} catch {
 			// DB not ready
 		}
+		return result;
 	});
 }

package/extension/src/vehicle-notes-client.ts

@@ -1,39 +1,29 @@
 /**
- * Registers notes.* as a real Vehicle instead of a hand-rolled `pi.registerTool()`
- * mega-tool -- see @danypops/papyrus's src/vehicle/notes-vehicle.ts for the
- * VehicleRegistry side. Same daemon, same handle file, same Bearer token every
- * other Papyrus RPC call already uses (resolveVehicleClientTarget mirrors
- * resolvePushChannelTarget's own resolution).
+ * Registers every Vehicle-projected domain (notes.*, rules.*, docs.*, artifact.*)
+ * as real Pi tools -- see @danypops/papyrus's src/vehicle/papyrus-vehicle.ts.
  *
- * Papyrus's daemon is expected to already be running as an installed service
- * (see `packed install-service`), not auto-spawned on first use -- so unlike
- * registerVehicleTools' README example, failure here (daemon not started yet,
- * stale handle) is tolerated the same silent-degrade way
- * subscribeTaskPushChannel already tolerates it, rather than letting a
- * daemon-not-running condition abort the rest of extension setup. There is
- * no retry-on-later-connect for a tool that was never registered at all --
- * Pi has no way to add one after the fact outside the initial registration
- * flow.
+ * Fails silently on a stale/unreachable daemon handle instead of aborting extension
+ * setup: Papyrus's daemon doesn't auto-spawn, and a tool that failed to register
+ * here has no later retry path.
  *
- * Resolves the target through service-client.ts's currentVehicleClientTarget()
- * (test-injectable, see setVehicleClientTargetResolverForTests), never
- * @danypops/papyrus's resolveVehicleClientTarget() directly -- this runs from
- * the bare extension entrypoint on every registerPapyrus(api) call, so an
- * un-injected default would resolve the real daemonStateDir() in any test
- * exercising the full entrypoint, not just ones about notes.
+ * Uses service-client.ts's currentVehicleClientTarget() (test-injectable) rather
+ * than resolveVehicleClientTarget() directly, so a test exercising the full
+ * extension entrypoint doesn't resolve a real daemonStateDir().
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
 import { registerVehicleTools } from "@danypops/vehicle-client-pi";
 import { currentVehicleClientTarget } from "./service-client.ts";
 
+const REGISTERED_PERMISSIONS = ["notes:read", "notes:write", "rules:read", "rules:write", "docs:read", "docs:write", "artifact:read", "artifact:write"];
+
 export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
 	const target = currentVehicleClientTarget();
 	if (!target) return;
 	try {
 		const client = new RemoteVehicleClient({ baseUrl: target.baseUrl, token: target.token });
 		await registerVehicleTools(pi, client, {
-			permissions: ["notes:read", "notes:write"],
+			permissions: REGISTERED_PERMISSIONS,
 			principal: { id: "pi-papyrus" },
 		});
 	} catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.38.5",
+  "version": "0.40.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -17,11 +17,12 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@danypops/papyrus": "^0.38.1",
-    "@danypops/vehicle-core": "^0.1.1",
+    "@danypops/jittor": "^0.14.0",
+    "@danypops/papyrus": "^0.39.0",
+    "@danypops/vehicle-core": "^0.2.0",
     "@danypops/vehicle-server": "^0.1.1",
     "@danypops/vehicle-client": "^0.1.1",
-    "@danypops/vehicle-client-pi": "^0.1.5",
+    "@danypops/vehicle-client-pi": "^0.2.0",
     "beautiful-mermaid": "1.1.3",
     "malevich-tui-components": "^0.5.0"
   },

package/extension/src/base-prompt-breakdown.ts

@@ -1,55 +0,0 @@
-import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
-import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "@danypops/papyrus";
-import type { ContextSegmentItem } from "./context-budget.ts";
-
-/**
- * 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 Papyrus can call, so reproducing their
- * exact template text here would be a real, silent drift risk if Pi ever changes it. 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 -- honesty
- * preserved even though individual sub-segment sizes are approximate, matching the same
- * known-segments-plus-honest-remainder pattern used everywhere else in this breakdown.
- */
-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;
-}
-
-function toCeilTokens(characters: number): number {
-	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
-}

package/extension/src/context-view.ts

@@ -1,222 +0,0 @@
-import type { ExtensionCommandContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
-import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
-import type { ContextBreakdown, ContextSegment, ContextSegmentItem } from "./context-budget.ts";
-
-const VISIBLE_ROWS = 24;
-
-const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
-	rules: "accent",
-	tasks: "success",
-	skills: "mdLink",
-	basePrompt: "warning",
-	messageHistory: "syntaxFunction",
-	toolDefinitions: "syntaxKeyword",
-	other: "muted",
-};
-
-/**
- * One row in the unified scrollable view. Every segment that has any real (nonzero) content
- * is fully expanded inline -- there is no separate "select a segment, then drill in" step.
- * `key` drives this row's color; `isHeader` distinguishes a segment's own summary line from
- * its item rows underneath it.
- */
-export interface ContextRow {
-	key: ContextSegment["key"];
-	isHeader: boolean;
-	text: string;
-	/** Nesting depth for indentation -- 0 for a segment header or a top-level item, deeper for real tree children (message history branches, Task containment). */
-	depth: number;
-}
-
-function formatTokenCount(tokens: number): string {
-	return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
-}
-
-function percentOf(part: number, whole: number): string {
-	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
-}
-
-/**
- * Flattens every segment with real content into one linear row list, filtering out anything
- * that is genuinely zero rather than displaying a misleading "0 tok  0.0%" row -- a segment or
- * item with literally nothing in it carries no information and is pure noise in a scrollable
- * view meant to show where tokens actually go. A segment whose OWN total is zero but whose
- * items are also all zero is dropped entirely; a segment with a nonzero total is always kept
- * even if all its items individually round to zero (the total itself is real signal).
- */
-/** Recursively flattens one item and its real tree children (message history branches, Task containment) into indented rows, sorted biggest-first at each level -- a parent always immediately precedes its own children, never scrambled by a global sort. */
-function flattenItem(item: ContextSegmentItem, key: ContextSegment["key"], depth: number, rows: ContextRow[]): void {
-	rows.push({ key, isHeader: false, depth, text: `${item.estimatedTokens.toString().padStart(6)} tok  ${item.label}` });
-	const children = (item.children ?? []).filter((child) => child.estimatedTokens > 0).sort((a, b) => b.estimatedTokens - a.estimatedTokens);
-	for (const child of children) flattenItem(child, key, depth + 1, rows);
-}
-
-export function buildContextRows(breakdown: ContextBreakdown): ContextRow[] {
-	const rows: ContextRow[] = [];
-	const denominator = breakdown.totalTokens ?? breakdown.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
-	for (const segment of breakdown.segments) {
-		const items = (segment.items ?? []).filter((item) => item.estimatedTokens > 0).sort((a, b) => b.estimatedTokens - a.estimatedTokens);
-		// A genuinely-unknown segment (basePrompt before the first observed turn) must stay
-		// visible even when its placeholder value is zero -- hiding it would misrepresent
-		// "not measured yet" as "measured and empty", the same honesty problem overshootTokens
-		// exists to prevent for the unaccounted bucket.
-		if (segment.estimatedTokens <= 0 && items.length === 0 && !segment.unknown) continue;
-		rows.push({
-			key: segment.key,
-			isHeader: true,
-			depth: 0,
-			text: `${segment.label} — ${segment.estimatedTokens} tok (${percentOf(segment.estimatedTokens, denominator)})`,
-		});
-		for (const item of items) flattenItem(item, segment.key, 1, rows);
-	}
-	return rows;
-}
-
-class ContextViewport {
-	private offsetY = 0;
-	private readonly rows: ContextRow[];
-
-	constructor(
-		private readonly tui: TUI,
-		private readonly theme: Theme,
-		private readonly breakdown: ContextBreakdown,
-		private readonly close: () => void,
-	) {
-		this.rows = buildContextRows(breakdown);
-	}
-
-	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, "")];
-
-		if (this.breakdown.totalTokens !== null && this.breakdown.effectiveBudget !== null) {
-			const percent = percentOf(this.breakdown.totalTokens, this.breakdown.effectiveBudget);
-			lines.push(truncateToWidth(
-				`${formatTokenCount(this.breakdown.totalTokens)} / ${formatTokenCount(this.breakdown.effectiveBudget)} tokens (${percent} of usable budget)`,
-				contentWidth,
-				"",
-			));
-		} else if (this.breakdown.totalTokens !== null) {
-			lines.push(truncateToWidth(`${formatTokenCount(this.breakdown.totalTokens)} tokens (model context window unknown)`, contentWidth, ""));
-		} else {
-			lines.push(theme.fg("dim", "No real usage reported yet — sizes below are Papyrus's own estimates only"));
-		}
-		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth, this.breakdown.effectiveBudget ?? undefined, this.breakdown.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("");
-
-		this.visibleWindow().forEach(({ row, index }) => {
-			const gutter = theme.fg(SEGMENT_COLORS[row.key], "▌");
-			const indent = "  ".repeat(row.depth);
-			const text = row.isHeader ? theme.bold(row.text) : `${indent}${row.text}`;
-			lines.push(truncateToWidth(`${gutter} ${text}`, contentWidth, ""));
-			void index;
-		});
-		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;
-	}
-
-	private visibleWindow(): Array<{ row: ContextRow; index: number }> {
-		const end = Math.min(this.offsetY + VISIBLE_ROWS, this.rows.length);
-		const result: Array<{ row: ContextRow; index: number }> = [];
-		for (let index = this.offsetY; index < end; index++) result.push({ row: this.rows[index]!, index });
-		return result;
-	}
-
-	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();
-	}
-}
-
-/**
- * Distributes `totalCells` proportionally across `weights` (parallel arrays), guaranteeing
- * every genuinely-positive weight gets at least one cell when there is room for all of them
- * to (totalCells >= weights.length) -- a real, nonzero segment must stay visible even when
- * dwarfed by a much larger one, not round away to nothing. The largest resulting cell count
- * absorbs whatever rounding leaves over or short, so the sum always equals totalCells exactly.
- */
-function distributeCells(weights: readonly number[], totalCells: number): number[] {
-	const sum = weights.reduce((a, b) => a + b, 0);
-	if (sum <= 0 || totalCells <= 0 || weights.length === 0) return weights.map(() => 0);
-	let cells = weights.map((weight) => Math.round((weight / sum) * totalCells));
-	if (totalCells >= weights.length) cells = cells.map((count) => (count === 0 ? 1 : count));
-	const diff = totalCells - cells.reduce((a, b) => a + b, 0);
-	if (diff !== 0) {
-		const maxIndex = cells.indexOf(Math.max(...cells));
-		cells[maxIndex] = (cells[maxIndex] ?? 0) + diff;
-	}
-	return cells;
-}
-
-/**
- * Renders the context window as one horizontal stacked bar: one colored run of block
- * characters per USED segment, followed by a gray/dim run of "░" cells for the remaining,
- * genuinely EMPTY context window -- this is the "total used vs. unused" graph. A zero-token
- * breakdown (nothing observed yet) renders an entirely gray/dim track rather than a
- * divide-by-zero, since 0 used really does mean the whole window is empty right now.
- *
- * `capacity` is the real denominator (Papyrus's own effectiveBudget, matching the percentage
- * already shown in the text line above this bar). `usedTokens` is the real, ground-truth used
- * amount (breakdown.totalTokens) the used-vs-unused split is measured against -- NOT the sum of
- * `segments`' own estimates. That distinction is load-bearing: a live-reported bug showed a
- * fully solid bar with zero gray even though the header read "55.9% of usable budget", because
- * the old code compared `capacity` against the SUM of estimated segments, which independently
- * overshot both the real total and the capacity itself (a session whose message-history
- * estimate alone summed to over 1.5M tokens against a real ~550k total) -- the exact estimate-
- * overshoot dishonesty `overshootTokens` exists to surface elsewhere was silently defeating the
- * bar's own gray/used split. `usedTokens` defaults to the segment sum only when omitted, for
- * callers with no real total available. Segments still split the USED portion proportionally to
- * their own estimated share of each other (via distributeCells, which also guarantees a tiny
- * nonzero segment stays visible rather than rounding to nothing next to a much larger one).
- */
-export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number, capacity?: number, usedTokens?: number): string {
-	const estimatedSum = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
-	if (estimatedSum <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
-	const realUsed = usedTokens ?? estimatedSum;
-	const usedWidth = capacity !== undefined ? Math.max(0, Math.min(width, Math.round((realUsed / capacity) * width))) : width;
-
-	const nonZero = segments.filter((segment) => segment.estimatedTokens > 0);
-	const cellCounts = distributeCells(nonZero.map((segment) => segment.estimatedTokens), usedWidth);
-	let output = "";
-	nonZero.forEach((segment, index) => {
-		const cells = cellCounts[index] ?? 0;
-		if (cells > 0) output += theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(cells));
-	});
-	const emptyWidth = width - usedWidth;
-	if (emptyWidth > 0) output += theme.fg("dim", "░".repeat(emptyWidth));
-	return output;
-}
-
-/** Non-interactive fallback (print mode, RPC, etc.): the same unified row list, as plain text lines. */
-function fallbackReport(breakdown: ContextBreakdown): string {
-	const totalLine = breakdown.totalTokens !== null
-		? `Real usage: ${breakdown.totalTokens} tokens${breakdown.effectiveBudget !== null ? ` / ${breakdown.effectiveBudget} usable budget (${percentOf(breakdown.totalTokens, breakdown.effectiveBudget)})` : ""}`
-		: "Real usage: not yet reported";
-	const overshootLine = breakdown.overshootTokens > 0 ? [`Estimates exceed real total by ~${breakdown.overshootTokens} tok -- sizes below are approximate, not exact`] : [];
-	const rows = buildContextRows(breakdown);
-	const rowLines = rows.length > 0 ? rows.map((row) => (row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`)) : ["(nothing observed yet)"];
-	return [totalLine, ...overshootLine, "", ...rowLines].join("\n");
-}
-
-export async function showContextView(ctx: ExtensionCommandContext, breakdown: ContextBreakdown): Promise<void> {
-	if (ctx.mode !== "tui") {
-		ctx.ui.notify(fallbackReport(breakdown), "info");
-		return;
-	}
-	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new ContextViewport(tui, theme, breakdown, done));
-}