@danypops/papyrus 0.34.1 → 0.34.3

package/extension/src/artifact-detail-format.ts

@@ -10,19 +10,26 @@ export interface ArtifactDetailContent {
 	relationships: string[];
 }
 
-export function artifactDetailContent(artifact: Artifact): ArtifactDetailContent {
+export function artifactDetailContent(artifact: Artifact, relationshipLines: string[] = []): ArtifactDetailContent {
 	return {
 		title: artifact.title,
 		identity: `${artifact.id} [${artifact.kind}|${artifact.status}]${artifact.subtype ? ` · ${artifact.subtype}` : ""}`,
 		body: artifact.body || "(no body)",
 		labels: [...artifact.labels],
 		metadata: Object.keys(artifact.extra).length > 0 ? formatMetadata(artifact.extra) : [],
-		relationships: (artifact.edges ?? []).map((edge) => `${edge.from} --${edge.relation}--> ${edge.to}`),
+		relationships: relationshipLines,
 	};
 }
 
-export function artifactDetailsText(artifact: Artifact): string {
-	const content = artifactDetailContent(artifact);
+/**
+ * Deliberately plain, unlike ArtifactDetailViewport's TUI body (renderMarkdownBody): this path
+ * feeds ctx.ui.notify(), used outside interactive mode (RPC, piped/non-terminal callers) where
+ * ANSI escape codes are noise or corruption, not formatting. Raw Markdown source stays readable
+ * as plain text either way. relationshipLines is still upgraded (a real graph or a resolved
+ * arrow list, never raw ids) since that needs no color to read.
+ */
+export function artifactDetailsText(artifact: Artifact, relationshipLines: string[] = []): string {
+	const content = artifactDetailContent(artifact, relationshipLines);
 	let output = `${content.title}\n${content.identity}\n\n${content.body}`;
 	if (content.labels.length > 0) output += `\n\nLabels: ${content.labels.join(", ")}`;
 	if (content.metadata.length > 0) output += `\n\nMetadata:\n${content.metadata.map((line) => `  ${line}`).join("\n")}`;

package/extension/src/artifact-detail-view.ts

@@ -7,7 +7,10 @@ import {
 	ARTIFACT_DETAIL_RESERVED_ROWS,
 } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
+import type { GraphRenderer } from "../../src/ports/graph-renderer.ts";
 import { artifactDetailContent, artifactDetailsText, type ArtifactDetailContent } from "./artifact-detail-format.ts";
+import { buildArtifactRelationshipLines } from "./artifact-relationship-lines.ts";
+import { BeautifulMermaidRenderer } from "./beautiful-mermaid-renderer.ts";
 import { renderMarkdownBody, type ActiveTheme } from "./markdown.ts";
 
 interface ArtifactDetailLine {
@@ -27,13 +30,14 @@ class ArtifactDetailViewport {
 		private readonly tui: TUI,
 		private readonly activeTheme: ActiveTheme,
 		artifact: Artifact,
+		relationshipLines: string[],
 		private readonly close: () => void,
 	) {
 		this.visibleLines = Math.max(
 			ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
 			Math.min(ARTIFACT_DETAIL_MAX_VISIBLE_LINES, tui.terminal.rows - ARTIFACT_DETAIL_RESERVED_ROWS),
 		);
-		this.content = artifactDetailContent(artifact);
+		this.content = artifactDetailContent(artifact, relationshipLines);
 	}
 
 	invalidate(): void { this.renderedWidth = 0; }
@@ -104,9 +108,14 @@ class ArtifactDetailViewport {
 	}
 }
 
-export async function showArtifactDetailView(ctx: ExtensionCommandContext, artifact: Artifact): Promise<void> {
-	const output = artifactDetailsText(artifact);
+export async function showArtifactDetailView(
+	ctx: ExtensionCommandContext,
+	artifact: Artifact,
+	renderer: GraphRenderer = new BeautifulMermaidRenderer(),
+): Promise<void> {
+	const relationshipLines = buildArtifactRelationshipLines(artifact, renderer);
+	const output = artifactDetailsText(artifact, relationshipLines);
 	if (ctx.mode !== "tui") { ctx.ui.notify(output, "info"); return; }
 	await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>
-		new ArtifactDetailViewport(tui, () => ctx.ui.theme ?? theme, artifact, done));
+		new ArtifactDetailViewport(tui, () => ctx.ui.theme ?? theme, artifact, relationshipLines, done));
 }

package/extension/src/artifact-relationship-lines.ts

@@ -0,0 +1,24 @@
+import { GRAPH_RENDER_MAX_ROUTED_EDGES, GRAPH_RENDER_MAX_ROUTED_NODES } from "../../src/constants.ts";
+import { projectArtifactRelationships } from "../../src/artifact-relationship-view.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import type { GraphRenderer } from "../../src/ports/graph-renderer.ts";
+
+/**
+ * Renders an artifact's direct relationships as a small graph when the neighbor set is real
+ * (more than one node) and within the same bound Task graph rendering already enforces;
+ * otherwise falls back to a plain, still name-resolved arrow list -- never the renderer's own
+ * separate box-style fallback, so this view has exactly two shapes, not three.
+ */
+export function buildArtifactRelationshipLines(artifact: Artifact, renderer: GraphRenderer): string[] {
+	const graph = projectArtifactRelationships(artifact);
+	if (graph.edges.length === 0) return [];
+	const withinBounds = graph.nodes.length > 1
+		&& graph.nodes.length <= GRAPH_RENDER_MAX_ROUTED_NODES
+		&& graph.edges.length <= GRAPH_RENDER_MAX_ROUTED_EDGES;
+	if (withinBounds) {
+		const rendered = renderer.render(graph);
+		if (rendered.lines.length > 0) return rendered.lines;
+	}
+	const labelById = new Map(graph.nodes.map((node) => [node.id, node.label]));
+	return graph.edges.map((edge) => `${labelById.get(edge.from) ?? edge.from} --${edge.label}--> ${labelById.get(edge.to) ?? edge.to}`);
+}

package/extension/src/context-budget.ts

@@ -77,7 +77,7 @@ export interface ContextSegmentItem {
 }
 
 export interface ContextSegment {
-	key: "rules" | "tasks" | "skills" | "basePrompt" | "messageHistory" | "other";
+	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. */
@@ -273,15 +273,15 @@ export interface ContextBreakdown {
 	/** 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)
-	 * 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 tool definitions and framework overhead are 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.
+	 * 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, then "other" absorbing whatever real usage the rest don't account for. */
+	/** rules, tasks, skills, basePrompt, messageHistory, toolDefinitions, then "other" absorbing whatever real usage the rest don't account for. */
 	segments: ContextSegment[];
 }
 
@@ -301,6 +301,8 @@ export interface BuildContextBreakdownInput {
 	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. */
@@ -308,6 +310,46 @@ 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
@@ -382,9 +424,10 @@ export function buildTaskItemTree(graph: TaskGraph): ContextSegmentItem[] {
 
 /**
  * Composes every segment Papyrus can actually measure or estimate (rules, tasks, skills
- * catalog, cached base-prompt size, and the live session's own message history) against the
- * real total Pi reports, deriving "unaccounted" (tool definitions and framework overhead --
- * genuinely invisible to any extension) as the remainder. The remainder is clamped to zero
+ * 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
@@ -426,13 +469,26 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 		estimatedTokens: input.messageHistoryActiveTokens,
 		items: input.messageHistoryItems,
 	};
-	const knownTokens = rules.estimatedTokens + tasks.estimatedTokens + skills.estimatedTokens + basePrompt.estimatedTokens + messageHistory.estimatedTokens;
+	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 (tool definitions, framework overhead) -- estimate overshoot: other segments' estimates already exceed the real total by ~${overshootTokens} tokens, so this is a floor, not a real zero`
-			: "Unaccounted (tool definitions, framework overhead)",
+			? `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 {
@@ -440,7 +496,7 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 		contextWindow: input.contextWindow,
 		effectiveBudget: input.contextWindow === null ? null : Math.max(0, input.contextWindow - reserveTokens),
 		overshootTokens,
-		segments: [rules, tasks, skills, basePrompt, messageHistory, other],
+		segments: [rules, tasks, skills, basePrompt, messageHistory, toolDefinitions, other],
 	};
 }
 

package/extension/src/context-view.ts

@@ -10,6 +10,7 @@ const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
 	skills: "mdLink",
 	basePrompt: "warning",
 	messageHistory: "syntaxFunction",
+	toolDefinitions: "syntaxKeyword",
 	other: "muted",
 };
 

package/extension/src/index.ts

@@ -34,7 +34,7 @@ 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 ContextSegmentItem, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.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 { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
@@ -635,6 +635,8 @@ export default async function (pi: ExtensionAPI) {
 				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,
@@ -643,6 +645,7 @@ export default async function (pi: ExtensionAPI) {
 					skills,
 					basePromptEstimatedTokens: lastObservedBasePromptTokens,
 					basePromptItems: lastObservedBasePromptItems,
+					toolDefinitionItems,
 					messageHistoryItems: messageHistory.items,
 					messageHistoryActiveTokens: messageHistory.activeTokens,
 				});

package/package.json

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

package/src/artifact-relationship-view.ts

@@ -0,0 +1,23 @@
+import type { Artifact } from "./domain/artifact.ts";
+import type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode } from "./domain/display-graph.ts";
+import { fallbackLabel } from "./task-relationship-view.ts";
+
+/**
+ * The generic-artifact counterpart to projectTaskRelationships: unlike a Task, which already
+ * has its containing TaskGraph's real titles in memory, a generic Doc/Rule/Skill/Playbook only
+ * has raw edge id pairs (artifact.show's tree fetch never resolves neighbor titles -- see
+ * ops.ts getArtifact). Reuses the same fallbackLabel heuristic rather than adding a network
+ * round-trip per neighbor, which would turn a rendering concern into a new daemon-adjacent one.
+ */
+export function projectArtifactRelationships(artifact: Artifact): DisplayGraph {
+	const edges: DisplayGraphEdge[] = (artifact.edges ?? []).map((edge) => ({ from: edge.from, to: edge.to, label: edge.relation }));
+	const nodeIds = new Set<string>();
+	for (const edge of edges) {
+		nodeIds.add(edge.from);
+		nodeIds.add(edge.to);
+	}
+	const nodes: DisplayGraphNode[] = [...nodeIds].map((id) => id === artifact.id
+		? { id, label: artifact.title, status: artifact.status }
+		: { id, label: fallbackLabel(id) });
+	return { direction: "LR", nodes, edges };
+}

package/src/task-relationship-view.ts

@@ -9,7 +9,8 @@ function normalizeEdge(edge: ArtifactEdge): DisplayGraphEdge {
 	return { from: edge.from, to: edge.to, label: edge.relation };
 }
 
-function fallbackLabel(id: string): string {
+/** Best-effort readable label from a bare id when no real title is known -- shared with artifact-relationship-view.ts's generic version of this same problem. */
+export function fallbackLabel(id: string): string {
 	return id.replace(/-[a-z0-9]{4}$/i, "").replaceAll("-", " ");
 }