@danypops/papyrus 0.15.2 → 0.16.0

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

@@ -0,0 +1,55 @@
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+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-budget.ts

@@ -295,6 +295,8 @@ export interface BuildContextBreakdownInput {
 	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. */
@@ -416,6 +418,7 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 		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",

package/extension/src/index.ts

@@ -27,7 +27,8 @@ 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, computeContextBudget, computeRuleBudget, DEFAULT_RESERVE_TOKENS, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
+import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, 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 { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
@@ -164,8 +165,12 @@ export default async function (pi: ExtensionAPI) {
 	// 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.
+	// 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[] = [];
 	const taskContinuation = new ActiveTaskContinuation({
 		maxTurns: TASK_DRIVER_MAX_TURNS,
 		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
@@ -480,6 +485,7 @@ export default async function (pi: ExtensionAPI) {
 					taskItems: buildTaskItemTree(taskGraph),
 					skills,
 					basePromptEstimatedTokens: lastObservedBasePromptTokens,
+					basePromptItems: lastObservedBasePromptItems,
 					messageHistoryItems: messageHistory.items,
 					messageHistoryActiveTokens: messageHistory.activeTokens,
 				});
@@ -559,6 +565,7 @@ export default async function (pi: ExtensionAPI) {
 			});
 			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 };
 		} catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],