@danypops/papyrus 0.13.3 → 0.13.5

package/extension/src/context-budget.ts

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
-import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_DEPTH, CONTEXT_TREE_MAX_NODES } from "../../src/constants.ts";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_NODES } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
 import { discoverSkillDirectories, scanSkillCatalogFootprint, type SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
@@ -162,7 +162,7 @@ export interface MessageHistoryTree {
 	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_DEPTH or CONTEXT_TREE_MAX_NODES, or found a cycle -- the tree shown is a bounded prefix, not necessarily the complete session. */
+	/** 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;
 }
 
@@ -171,24 +171,49 @@ export interface MessageHistoryTree {
  * 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_DEPTH /
- * CONTEXT_TREE_MAX_NODES): a session file is external, mutable state, and this deliberately
+ * 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.
  */
+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>): MessageHistoryTree {
 	const visited = new Set<string>();
 	let truncated = false;
 	let activeTokens = 0;
-	let nodesVisited = 0;
 
-	function visit(node: SessionTreeNodeLike, depth: number): ContextSegmentItem | null {
-		if (nodesVisited >= CONTEXT_TREE_MAX_NODES || depth > CONTEXT_TREE_MAX_DEPTH) { truncated = true; return null; }
-		if (visited.has(node.entry.id)) { truncated = true; return null; } // cycle guard
-		visited.add(node.entry.id);
-		nodesVisited++;
+	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 entry = node.entry;
+	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"
@@ -198,19 +223,29 @@ export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike
 		const isActive = activeEntryIds.has(entry.id);
 		if (isActive) activeTokens += tokens;
 
-		const children = node.children
-			.map((child) => visit(child, depth + 1))
-			.filter((item): item is ContextSegmentItem => item !== null);
-		if (tokens === 0 && children.length === 0) return null; // no content, no descendants with content -- nothing to show
+		const children = childItemsByParent.get(index) ?? [];
+		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
 
-		return {
+		const item: ContextSegmentItem = {
 			label: isActive ? entryLabel(entry) : `${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 = roots.map((root) => visit(root, 0)).filter((item): item is ContextSegmentItem => item !== null);
+	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 };
 }
 
@@ -267,30 +302,64 @@ function sumItemTree(items: ContextSegmentItem[]): number {
  * (extension/src/task-widget.ts) for the identical multi-parent-DAG-in-a-bounded-view
  * problem, not a new inconsistency.
  */
+interface TaskWalkFrame {
+	taskId: string;
+	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. */
 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));
 	const visited = new Set<string>();
 
-	function visit(id: string, depth: number): ContextSegmentItem | null {
-		if (depth > CONTEXT_TREE_MAX_DEPTH || visited.size >= CONTEXT_TREE_MAX_NODES || visited.has(id) || !openIds.has(id)) return null;
-		visited.add(id);
-		const node = byId.get(id);
-		if (!node) return null;
-		const characters = node.task.title.length + node.task.body.length;
-		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
-		const children = node.childIds
-			.filter((childId) => openIds.has(childId))
-			.map((childId) => visit(childId, depth + 1))
-			.filter((item): item is ContextSegmentItem => item !== null);
-		return { label: node.task.title, estimatedTokens: tokens, ...(children.length > 0 ? { children } : {}) };
-	}
-
 	const rootIds = [...openIds].filter((id) => {
 		const node = byId.get(id)!;
 		return node.parentIds.length === 0 || !node.parentIds.some((parentId) => openIds.has(parentId));
 	});
-	return rootIds.map((id) => visit(id, 0)).filter((item): item is ContextSegmentItem => item !== null);
+
+	const order: TaskWalkFrame[] = [];
+	const stack: TaskWalkFrame[] = [...rootIds].reverse().map((taskId) => ({ taskId, parentIndex: null }));
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (order.length >= CONTEXT_TREE_MAX_NODES) break;
+		if (visited.has(frame.taskId) || !openIds.has(frame.taskId)) continue; // cycle guard + open-only filter
+		visited.add(frame.taskId);
+		const index = order.length;
+		order.push(frame);
+		const node = byId.get(frame.taskId);
+		const children = [...(node?.childIds ?? [])].reverse()
+			.filter((childId) => openIds.has(childId))
+			.map((childId) => ({ taskId: childId, parentIndex: index }));
+		stack.push(...children);
+	}
+
+	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 node = byId.get(frame.taskId);
+		if (!node) continue;
+		const characters = node.task.title.length + node.task.body.length;
+		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		const children = childItemsByParent.get(index) ?? [];
+		const item: ContextSegmentItem = { label: node.task.title, estimatedTokens: tokens, ...(children.length > 0 ? { children } : {}) };
+		itemByIndex.set(index, item);
+		if (frame.parentIndex !== null) {
+			const siblings = childItemsByParent.get(frame.parentIndex) ?? [];
+			siblings.unshift(item);
+			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;
 }
 
 /**

package/extension/src/context-view.ts

@@ -13,6 +13,19 @@ const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
 	other: "muted",
 };
 
+/** Short, fixed-width column labels for the vertical deep-dive graph -- must match VERTICAL_BAR_WIDTH exactly so each label sits centered under its own bar. */
+const SEGMENT_SHORT_LABELS: Record<ContextSegment["key"], string> = {
+	rules: "Rul",
+	tasks: "Tsk",
+	skills: "Skl",
+	basePrompt: "Bse",
+	messageHistory: "Msg",
+	other: "Oth",
+};
+
+const VERTICAL_BAR_HEIGHT = 6;
+const VERTICAL_BAR_WIDTH = 3;
+
 /**
  * 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.
@@ -104,10 +117,16 @@ class ContextViewport {
 		} 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));
+		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth, this.breakdown.effectiveBudget ?? 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, ""));
 		}
+		const verticalBars = renderContextVerticalBars(theme, this.breakdown.segments);
+		if (verticalBars.length > 0) {
+			lines.push("");
+			lines.push(theme.fg("dim", "Composition of used tokens:"));
+			for (const barLine of verticalBars) lines.push(truncateToWidth(barLine, contentWidth, ""));
+		}
 		lines.push("");
 
 		this.visibleWindow().forEach(({ row, index }) => {
@@ -143,27 +162,67 @@ class ContextViewport {
 }
 
 /**
- * Renders the context window as one proportional stacked bar, one colored run of block
- * characters per segment, matching each row's own gutter color above/below it. A zero-token
- * breakdown (nothing observed yet) renders an empty dim track rather than a divide-by-zero.
- * Zero-token segments contribute no cells and are effectively invisible in the bar, matching
- * their exclusion from the row list below it.
+ * 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) that used-vs-unused is measured against. When
+ * omitted, or when usage has already exceeded it (overshoot / near-compaction), the bar falls
+ * back to filling 100% of its width proportionally among segments -- there is no "unused" left
+ * to show gray for once real usage has met or passed the real budget.
  */
-export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number): string {
+export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number, capacity?: number): string {
 	const total = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
 	if (total <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
 	const nonZero = segments.filter((segment) => segment.estimatedTokens > 0);
+	const usedWidth = capacity !== undefined && capacity > total ? Math.min(width, Math.round((total / capacity) * width)) : width;
+
 	let used = 0;
 	let output = "";
 	nonZero.forEach((segment, index) => {
 		const isLast = index === nonZero.length - 1;
-		const cells = isLast ? width - used : Math.round((segment.estimatedTokens / total) * width);
+		const cells = isLast ? usedWidth - used : Math.round((segment.estimatedTokens / total) * usedWidth);
 		used += cells;
 		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;
 }
 
+/**
+ * Renders the "used" portion's own composition as a small vertical bar chart, one column per
+ * segment with real content, scaled so the largest segment fills the full height -- the
+ * "deep dive" graph, complementing the horizontal used-vs-unused bar above it. Any segment
+ * with real (nonzero) tokens gets at least one filled row so it stays visible even next to a
+ * much larger segment. Returns an empty array (nothing to render) when no segment has any
+ * tokens yet, matching the same zero-noise principle as the row list below it.
+ */
+export function renderContextVerticalBars(theme: Theme, segments: ReadonlyArray<ContextSegment>): string[] {
+	const visible = segments.filter((segment) => segment.estimatedTokens > 0);
+	if (visible.length === 0) return [];
+	const max = Math.max(...visible.map((segment) => segment.estimatedTokens));
+	const filledRows = new Map(visible.map((segment) => [segment.key, Math.max(1, Math.round((segment.estimatedTokens / max) * VERTICAL_BAR_HEIGHT))]));
+
+	const lines: string[] = [];
+	for (let row = 0; row < VERTICAL_BAR_HEIGHT; row++) {
+		const rowsFromBottom = VERTICAL_BAR_HEIGHT - row;
+		let line = "";
+		for (const segment of visible) {
+			const filled = (filledRows.get(segment.key) ?? 0) >= rowsFromBottom;
+			line += `${filled ? theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(VERTICAL_BAR_WIDTH)) : " ".repeat(VERTICAL_BAR_WIDTH)} `;
+		}
+		lines.push(line);
+	}
+	let legend = "";
+	for (const segment of visible) legend += `${theme.fg(SEGMENT_COLORS[segment.key], SEGMENT_SHORT_LABELS[segment.key])} `;
+	lines.push(legend);
+	return lines;
+}
+
 /** 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -24,6 +24,7 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.10",
     "bun-types": "latest",
     "typescript": "^5.7.3"
   },

package/src/constants.ts

@@ -33,14 +33,19 @@ export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
 /**
  * Bounds for walking Pi's real session tree (getTree()) and Papyrus's own Task containment
  * tree when estimating /context's message-history and task segments. Both are genuine trees
- * built from external, mutable state (a session file; the live Task graph) -- depth and
- * total-node bounds are a defensive measure against a corrupted/adversarial parentId chain
- * forming an accidental cycle, matching the same cycle-safety discipline already applied to
- * ConversationJournal traversal and deliberately hardening past a real, confirmed gap in
- * Pi's own getBranch() (no cycle guard at all).
+ * built from external, mutable state (a session file; the live Task graph) -- the node bound
+ * is a defensive measure against a corrupted/adversarial parentId chain forming an accidental
+ * cycle, matching the same cycle-safety discipline already applied to ConversationJournal
+ * traversal and deliberately hardening past a real, confirmed gap in Pi's own getBranch() (no
+ * cycle guard at all). Set generously: a real, ordinary (non-branching) long-running session
+ * is one long linear chain, so a naively small bound truncates the walk after counting only a
+ * small fraction of the real conversation -- a session observed in production with 6,924
+ * entries on its own active branch confirmed an earlier, much smaller bound did exactly that,
+ * making the derived "unaccounted" remainder balloon to absorb almost the entire real total.
+ * The walk itself is iterative (an explicit stack), not recursive, specifically so a chain
+ * this long cannot also risk a real JavaScript call-stack overflow independent of this bound.
  */
-export const CONTEXT_TREE_MAX_DEPTH = 200;
-export const CONTEXT_TREE_MAX_NODES = 2000;
+export const CONTEXT_TREE_MAX_NODES = 50_000;
 
 /**
  * A Papyrus Rule's condition+action+body is injected into EVERY relevant turn's system