@danypops/pi-papyrus 0.49.1 → 0.50.0

package/extension/src/tool-rendering/index.ts

@@ -55,6 +55,23 @@ function simpleDetailsText(details: Exclude<PapyrusToolDetails, { kind: "artifac
 			return `${details.title}\n${details.content}${details.completeness.truncated ? `\n[truncated ${details.completeness.omitted} characters]` : ""}`;
 		case "error":
 			return `${details.code}: ${details.message}`;
+		case "execution-plan":
+			return `${details.nodes.length} task(s) across ${details.layers.length} layer(s)${details.cycleIds.length ? `, ${details.cycleIds.length} in a cycle` : ""}`;
+		case "playbook-invocation":
+			return [
+				`✓ Run ${details.runId}`,
+				`${details.created.tasks.length} tasks · ${details.created.docs.length} docs · ${details.created.rules.length} rules`,
+			].join("\n");
+		case "playbook-missing-arguments":
+			return `Missing required argument(s): ${details.missingArguments.join(", ")}`;
+		case "discussion":
+			return `${details.discussion ? `${details.discussion.title}\n` : ""}${details.rounds.length} round(s)`;
+		case "task-completion":
+			return `${details.completed ? "✓" : "✗"} ${details.artifact.title}`;
+		case "no-focus":
+			return "No focused task.";
+		case "lease":
+			return `${details.taskName} — ${details.taskTitle}\nowner ${details.owner}, expires ${details.leaseExpiresAt}`;
 	}
 }
 

package/extension/src/tool-rendering/render-model.ts

@@ -127,6 +127,105 @@ export interface ErrorToolDetails extends ToolDetailsBase {
 	message: string;
 }
 
+export interface ExecutionPlanNode {
+	id: string;
+	title: string;
+	status: string;
+	active: boolean;
+	state: string;
+	layer: number | null;
+	prerequisiteIds: string[];
+	successorIds: string[];
+}
+
+export interface ExecutionPlanToolDetails extends ToolDetailsBase {
+	kind: "execution-plan";
+	nodes: ExecutionPlanNode[];
+	layers: string[][];
+	cycleIds: string[];
+	completeness: ResultCompleteness;
+}
+
+export interface PlaybookInvocationCreated {
+	docs: string[];
+	rules: string[];
+	tasks: string[];
+}
+
+export interface PlaybookInvocationToolDetails extends ToolDetailsBase {
+	kind: "playbook-invocation";
+	playbookId: string;
+	runId: string;
+	created: PlaybookInvocationCreated;
+	rootTaskIds: string[];
+	entryTaskId: string;
+	execution: { nodes: ExecutionPlanNode[]; layers: string[][]; cycleIds: string[] };
+	completeness: ResultCompleteness;
+}
+
+export interface PlaybookMissingArgumentsToolDetails extends ToolDetailsBase {
+	kind: "playbook-missing-arguments";
+	playbookId: string;
+	missingArguments: string[];
+}
+
+export interface DiscussionRoundSummary {
+	roundNumber: number;
+	actor: string;
+	content: string;
+}
+
+export interface DiscussionToolDetails extends ToolDetailsBase {
+	kind: "discussion";
+	/** Absent for discuss.rounds, which returns rounds with no parent discussion in its own output. */
+	discussion?: ToolArtifactSummary;
+	rounds: DiscussionRoundSummary[];
+	completeness: ResultCompleteness;
+}
+
+export interface TaskGateResultSummary {
+	passed: boolean;
+	output: string;
+}
+
+export interface TaskChecklistReviewSummary {
+	item: string;
+	accepted: boolean;
+	reason?: string;
+}
+
+export interface TaskBlockageSummary {
+	artifact: ToolArtifactSummary;
+	dependencyIds: string[];
+}
+
+export interface TaskCompletionToolDetails extends ToolDetailsBase {
+	kind: "task-completion";
+	artifact: ToolArtifactSummary;
+	gates: TaskGateResultSummary[];
+	checklist: TaskChecklistReviewSummary[];
+	completed: boolean;
+	focused?: ToolArtifactSummary;
+	blocked: TaskBlockageSummary[];
+	completeness: ResultCompleteness;
+}
+
+export interface NoFocusToolDetails extends ToolDetailsBase {
+	kind: "no-focus";
+}
+
+/** tasks.claim/heartbeat_lease/release_lease/lease's own name-first view -- deliberately never carries the raw lease token; the model channel (which needs the real token for a later heartbeat/release call) is a separate, independent channel from this persisted, human-facing one. */
+export interface LeaseToolDetails extends ToolDetailsBase {
+	kind: "lease";
+	taskName: string;
+	taskTitle: string;
+	owner: string;
+	claimedAt: string;
+	leaseExpiresAt: string;
+	heartbeatAt?: string;
+	note?: string;
+}
+
 export type PapyrusToolDetails =
 	| ArtifactToolDetails
 	| ArtifactListToolDetails
@@ -135,7 +234,14 @@ export type PapyrusToolDetails =
 	| GateRunToolDetails
 	| InvocationToolDetails
 	| PreviewToolDetails
-	| ErrorToolDetails;
+	| ErrorToolDetails
+	| ExecutionPlanToolDetails
+	| PlaybookInvocationToolDetails
+	| PlaybookMissingArgumentsToolDetails
+	| DiscussionToolDetails
+	| TaskCompletionToolDetails
+	| NoFocusToolDetails
+	| LeaseToolDetails;
 
 export interface ModelContent {
 	text: string;
@@ -153,7 +259,9 @@ function boundedText(value: string, maximum: number): { value: string; completen
 	return { value: clipped, completeness: completeness(value.length, clipped.length) };
 }
 
-function artifactSummary(artifact: Artifact): ToolArtifactSummary {
+type ArtifactSummarySource = Pick<Artifact, "id" | "kind" | "title" | "status" | "subtype" | "labels"> & { alias?: string };
+
+function artifactSummary(artifact: ArtifactSummarySource): ToolArtifactSummary {
 	return {
 		id: artifact.id,
 		alias: artifact.alias,
@@ -290,6 +398,171 @@ export function createErrorDetails(operation: string, code: string, message: str
 	};
 }
 
+function boundedStringArray(values: readonly string[]): string[] {
+	return values.slice(0, TOOL_DETAILS_MAX_ITEMS);
+}
+
+function boundedExecutionPlanNodes(nodes: readonly ExecutionPlanNode[]): ExecutionPlanNode[] {
+	return nodes.slice(0, TOOL_DETAILS_MAX_ITEMS).map((node) => ({
+		...node,
+		prerequisiteIds: boundedStringArray(node.prerequisiteIds),
+		successorIds: boundedStringArray(node.successorIds),
+	}));
+}
+
+function boundedLayers(layers: readonly (readonly string[])[]): string[][] {
+	return layers.slice(0, TOOL_DETAILS_MAX_ITEMS).map((layer) => boundedStringArray(layer));
+}
+
+export function createExecutionPlanDetails(
+	operation: string,
+	nodes: readonly ExecutionPlanNode[],
+	layers: readonly (readonly string[])[],
+	cycleIds: readonly string[],
+): ExecutionPlanToolDetails {
+	const boundedNodes = boundedExecutionPlanNodes(nodes);
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "execution-plan",
+		operation,
+		nodes: boundedNodes,
+		layers: boundedLayers(layers),
+		cycleIds: boundedStringArray(cycleIds),
+		completeness: completeness(nodes.length, boundedNodes.length),
+	};
+}
+
+export function createPlaybookInvocationDetails(
+	operation: string,
+	fields: {
+		playbookId: string;
+		runId: string;
+		created: PlaybookInvocationCreated;
+		rootTaskIds: readonly string[];
+		entryTaskId: string;
+		execution: { nodes: readonly ExecutionPlanNode[]; layers: readonly (readonly string[])[]; cycleIds: readonly string[] };
+	},
+): PlaybookInvocationToolDetails {
+	const boundedNodes = boundedExecutionPlanNodes(fields.execution.nodes);
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "playbook-invocation",
+		operation,
+		playbookId: fields.playbookId,
+		runId: fields.runId,
+		created: {
+			docs: boundedStringArray(fields.created.docs),
+			rules: boundedStringArray(fields.created.rules),
+			tasks: boundedStringArray(fields.created.tasks),
+		},
+		rootTaskIds: boundedStringArray(fields.rootTaskIds),
+		entryTaskId: fields.entryTaskId,
+		execution: {
+			nodes: boundedNodes,
+			layers: boundedLayers(fields.execution.layers),
+			cycleIds: boundedStringArray(fields.execution.cycleIds),
+		},
+		completeness: completeness(fields.execution.nodes.length, boundedNodes.length),
+	};
+}
+
+export function createPlaybookMissingArgumentsDetails(
+	operation: string,
+	playbookId: string,
+	missingArguments: readonly string[],
+): PlaybookMissingArgumentsToolDetails {
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "playbook-missing-arguments",
+		operation,
+		playbookId,
+		missingArguments: boundedStringArray(missingArguments),
+	};
+}
+
+export function createDiscussionDetails(
+	operation: string,
+	rounds: readonly DiscussionRoundSummary[],
+	discussion?: ArtifactSummarySource,
+): DiscussionToolDetails {
+	const boundedRounds = rounds.slice(0, TOOL_DETAILS_MAX_ITEMS).map((round) => ({
+		...round,
+		content: round.content.slice(0, TOOL_DETAILS_ROW_OUTPUT_MAX_CHARACTERS),
+	}));
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "discussion",
+		operation,
+		...(discussion ? { discussion: artifactSummary(discussion) } : {}),
+		rounds: boundedRounds,
+		completeness: completeness(rounds.length, boundedRounds.length),
+	};
+}
+
+export function createTaskCompletionDetails(
+	operation: string,
+	fields: {
+		artifact: Artifact;
+		gates: readonly TaskGateResultSummary[];
+		checklist: readonly TaskChecklistReviewSummary[];
+		completed: boolean;
+		focused: Artifact | null;
+		blocked: readonly { artifact: Artifact; dependencyIds: readonly string[] }[];
+	},
+): TaskCompletionToolDetails {
+	const boundedGates = fields.gates.slice(0, TOOL_DETAILS_MAX_ITEMS).map((gate) => ({
+		...gate,
+		output: gate.output.slice(0, TOOL_DETAILS_ROW_OUTPUT_MAX_CHARACTERS),
+	}));
+	const boundedChecklist = fields.checklist.slice(0, TOOL_DETAILS_MAX_ITEMS);
+	const boundedBlocked = fields.blocked.slice(0, TOOL_DETAILS_MAX_ITEMS).map((entry) => ({
+		artifact: artifactSummary(entry.artifact),
+		dependencyIds: boundedStringArray(entry.dependencyIds),
+	}));
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "task-completion",
+		operation,
+		artifact: artifactSummary(fields.artifact),
+		gates: boundedGates,
+		checklist: boundedChecklist,
+		completed: fields.completed,
+		...(fields.focused ? { focused: artifactSummary(fields.focused) } : {}),
+		blocked: boundedBlocked,
+		completeness: completeness(fields.blocked.length, boundedBlocked.length),
+	};
+}
+
+export function createNoFocusDetails(operation: string): NoFocusToolDetails {
+	return { schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA, kind: "no-focus", operation };
+}
+
+export function createLeaseDetails(
+	operation: string,
+	lease: {
+		taskName: string;
+		taskTitle: string;
+		owner: string;
+		claimedAt: string;
+		leaseExpiresAt: string;
+		heartbeatAt?: string;
+		note?: string;
+	},
+): LeaseToolDetails {
+	return {
+		schemaVersion: PAPYRUS_TOOL_DETAILS_SCHEMA,
+		kind: "lease",
+		operation,
+		taskName: lease.taskName,
+		taskTitle: lease.taskTitle,
+		owner: lease.owner,
+		claimedAt: lease.claimedAt,
+		leaseExpiresAt: lease.leaseExpiresAt,
+		...(lease.heartbeatAt ? { heartbeatAt: lease.heartbeatAt } : {}),
+		...(lease.note ? { note: lease.note.slice(0, TOOL_DETAILS_FIELD_MAX_CHARACTERS) } : {}),
+	};
+}
+
 export function createModelContent(value: string): ModelContent {
 	if (value.length <= TOOL_MODEL_CONTENT_MAX_CHARACTERS) {
 		return { text: value, truncated: false, omitted: 0 };
@@ -377,6 +650,54 @@ function isBoundedArray<T>(value: unknown, maximum: number, predicate: (entry: u
 	return Array.isArray(value) && value.length <= maximum && value.every(predicate);
 }
 
+function isExecutionPlanNode(value: unknown): value is ExecutionPlanNode {
+	return (
+		isRecord(value) &&
+		isBoundedString(value.id) &&
+		isBoundedString(value.title) &&
+		isBoundedString(value.status) &&
+		typeof value.active === "boolean" &&
+		isBoundedString(value.state) &&
+		(value.layer === null || Number.isSafeInteger(value.layer)) &&
+		isStringArray(value.prerequisiteIds) &&
+		isStringArray(value.successorIds)
+	);
+}
+
+function isLayers(value: unknown): value is string[][] {
+	return isBoundedArray(value, TOOL_DETAILS_MAX_ITEMS, (entry): entry is string[] => isStringArray(entry));
+}
+
+function isExecution(value: unknown): value is { nodes: ExecutionPlanNode[]; layers: string[][]; cycleIds: string[] } {
+	return (
+		isRecord(value) &&
+		isBoundedArray(value.nodes, TOOL_DETAILS_MAX_ITEMS, isExecutionPlanNode) &&
+		isLayers(value.layers) &&
+		isStringArray(value.cycleIds)
+	);
+}
+
+function isDiscussionRoundSummary(value: unknown): value is DiscussionRoundSummary {
+	return isRecord(value) && Number.isSafeInteger(value.roundNumber) && isBoundedString(value.actor) && isBoundedString(value.content);
+}
+
+function isTaskGateResultSummary(value: unknown): value is TaskGateResultSummary {
+	return isRecord(value) && typeof value.passed === "boolean" && isBoundedString(value.output, TOOL_DETAILS_ROW_OUTPUT_MAX_CHARACTERS);
+}
+
+function isTaskChecklistReviewSummary(value: unknown): value is TaskChecklistReviewSummary {
+	return (
+		isRecord(value) &&
+		isBoundedString(value.item) &&
+		typeof value.accepted === "boolean" &&
+		(value.reason === undefined || isBoundedString(value.reason))
+	);
+}
+
+function isTaskBlockageSummary(value: unknown): value is TaskBlockageSummary {
+	return isRecord(value) && isArtifactSummary(value.artifact) && isStringArray(value.dependencyIds);
+}
+
 /** Validate renderer details restored from session history before using them as typed presentation state. */
 export function parsePapyrusToolDetails(value: unknown): PapyrusToolDetails | undefined {
 	let serializedLength: number;
@@ -447,6 +768,59 @@ export function parsePapyrusToolDetails(value: unknown): PapyrusToolDetails | un
 			return isBoundedString(value.code) && isBoundedString(value.message, TOOL_DETAILS_BODY_MAX_CHARACTERS)
 				? (value as unknown as ErrorToolDetails)
 				: undefined;
+		case "execution-plan":
+			return isBoundedArray(value.nodes, TOOL_DETAILS_MAX_ITEMS, isExecutionPlanNode) &&
+				isLayers(value.layers) &&
+				isStringArray(value.cycleIds) &&
+				isCompleteness(value.completeness)
+				? (value as unknown as ExecutionPlanToolDetails)
+				: undefined;
+		case "playbook-invocation": {
+			if (!isRecord(value.created)) return undefined;
+			return isBoundedString(value.playbookId) &&
+				isBoundedString(value.runId) &&
+				isStringArray(value.created.docs) &&
+				isStringArray(value.created.rules) &&
+				isStringArray(value.created.tasks) &&
+				isStringArray(value.rootTaskIds) &&
+				isBoundedString(value.entryTaskId) &&
+				isExecution(value.execution) &&
+				isCompleteness(value.completeness)
+				? (value as unknown as PlaybookInvocationToolDetails)
+				: undefined;
+		}
+		case "playbook-missing-arguments":
+			return isBoundedString(value.playbookId) && isStringArray(value.missingArguments)
+				? (value as unknown as PlaybookMissingArgumentsToolDetails)
+				: undefined;
+		case "discussion":
+			return (value.discussion === undefined || isArtifactSummary(value.discussion)) &&
+				isBoundedArray(value.rounds, TOOL_DETAILS_MAX_ITEMS, isDiscussionRoundSummary) &&
+				isCompleteness(value.completeness)
+				? (value as unknown as DiscussionToolDetails)
+				: undefined;
+		case "task-completion":
+			return isArtifactSummary(value.artifact) &&
+				isBoundedArray(value.gates, TOOL_DETAILS_MAX_ITEMS, isTaskGateResultSummary) &&
+				isBoundedArray(value.checklist, TOOL_DETAILS_MAX_ITEMS, isTaskChecklistReviewSummary) &&
+				typeof value.completed === "boolean" &&
+				(value.focused === undefined || isArtifactSummary(value.focused)) &&
+				isBoundedArray(value.blocked, TOOL_DETAILS_MAX_ITEMS, isTaskBlockageSummary) &&
+				isCompleteness(value.completeness)
+				? (value as unknown as TaskCompletionToolDetails)
+				: undefined;
+		case "no-focus":
+			return value as unknown as NoFocusToolDetails;
+		case "lease":
+			return isBoundedString(value.taskName) &&
+				isBoundedString(value.taskTitle) &&
+				isBoundedString(value.owner) &&
+				isBoundedString(value.claimedAt) &&
+				isBoundedString(value.leaseExpiresAt) &&
+				(value.heartbeatAt === undefined || isBoundedString(value.heartbeatAt)) &&
+				(value.note === undefined || isBoundedString(value.note))
+				? (value as unknown as LeaseToolDetails)
+				: undefined;
 		default:
 			return undefined;
 	}

package/extension/src/tools/vehicle-artifact-renderers.ts

@@ -13,10 +13,10 @@
  */
 
 import type { Artifact } from "@danypops/papyrus";
-import { TOOL_COLLAPSED_ROW_LIMIT } from "@danypops/papyrus";
-import type { VehicleToolRenderers } from "@danypops/vehicle-client-pi";
+import { TOOL_COLLAPSED_ROW_LIMIT, TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS } from "@danypops/papyrus";
+import type { PiVehicleInvocationRequest, PiVehiclePresentationContract, VehicleToolRenderers } from "@danypops/vehicle-client-pi";
 import { renderVehicleCall, renderVehicleResult } from "@danypops/vehicle-client-pi/vehicle-render";
-import type { VehicleOperationDescriptor } from "@danypops/vehicle-core";
+import type { JsonValue, VehicleOperationDescriptor } from "@danypops/vehicle-core";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import {
@@ -30,7 +30,20 @@ import {
 } from "malevich-tui-components";
 import { ArtifactCard, detailViewTheme, expandHint, measure, statusColor, statusGlyph } from "../tool-rendering/artifact-card.ts";
 import { ArtifactListCard } from "../tool-rendering/artifact-list.ts";
-import { type ArtifactFocusAnnotation, createArtifactDetails, createArtifactListDetails } from "../tool-rendering/render-model.ts";
+import {
+	type ArtifactFocusAnnotation,
+	createArtifactDetails,
+	createArtifactListDetails,
+	createDiscussionDetails,
+	createExecutionPlanDetails,
+	createLeaseDetails,
+	createNoFocusDetails,
+	createPlaybookInvocationDetails,
+	createPlaybookMissingArgumentsDetails,
+	createPreviewDetails,
+	createTaskCompletionDetails,
+	parsePapyrusToolDetails,
+} from "../tool-rendering/render-model.ts";
 import { recordRenderDiagnostic, shapeFingerprint } from "./render-diagnostics.ts";
 
 function isArtifact(value: unknown): value is Artifact {
@@ -244,6 +257,12 @@ interface DiscussionAndRoundsOutput {
 	rounds: DiscussionRoundOutput[];
 }
 
+/** What renderDiscussionAndRounds actually reads -- satisfied by both a raw Artifact (the live duck-typed output path) and the leaner projected ToolArtifactSummary (the typed-DTO path), with no cast needed at either call site. */
+interface RenderableDiscussionParent {
+	title: string;
+	status: string;
+}
+
 function isDiscussionAndRounds(value: unknown): value is DiscussionAndRoundsOutput {
 	if (typeof value !== "object" || value === null) return false;
 	const row = value as Record<string, unknown>;
@@ -277,7 +296,11 @@ function roundsSection(rounds: readonly DiscussionRoundOutput[]): DetailSection
 	};
 }
 
-function renderDiscussionAndRounds(output: DiscussionAndRoundsOutput, theme: Theme, expanded: boolean): Component {
+function renderDiscussionAndRounds(
+	output: { discussion: RenderableDiscussionParent; rounds: readonly DiscussionRoundOutput[] },
+	theme: Theme,
+	expanded: boolean,
+): Component {
 	const discussion = output.discussion;
 	return statelessComponent((width) => {
 		const safeWidth = Math.max(1, width);
@@ -331,6 +354,16 @@ interface TaskCompletionOutput {
 	blocked: TaskBlockageOutput[];
 }
 
+/** What renderTaskCompletion actually reads -- satisfied by both the raw duck-typed TaskCompletionOutput and the leaner projected TaskCompletionToolDetails. */
+interface RenderableTaskCompletion {
+	artifact: RenderableDiscussionParent;
+	gates: readonly { passed: boolean; output: string }[];
+	checklist: readonly TaskChecklistReviewOutput[];
+	completed: boolean;
+	focused?: RenderableDiscussionParent | null;
+	blocked: readonly { artifact: RenderableDiscussionParent; dependencyIds: readonly string[] }[];
+}
+
 function isTaskCompletion(value: unknown): value is TaskCompletionOutput {
 	if (typeof value !== "object" || value === null) return false;
 	const row = value as Record<string, unknown>;
@@ -344,7 +377,7 @@ function isTaskCompletion(value: unknown): value is TaskCompletionOutput {
 	);
 }
 
-function renderTaskCompletion(result: TaskCompletionOutput, theme: Theme, expanded: boolean): Component {
+function renderTaskCompletion(result: RenderableTaskCompletion, theme: Theme, expanded: boolean): Component {
 	const task = result.artifact;
 	return statelessComponent((width) => {
 		const safeWidth = Math.max(1, width);
@@ -384,6 +417,69 @@ function renderTaskCompletion(result: TaskCompletionOutput, theme: Theme, expand
 	});
 }
 
+/** tasks.claim/heartbeat_lease/release_lease/lease's own name-first view. Detected the same
+ * name-independent, shape-based way as the others in this file. */
+interface TaskLeaseViewOutput {
+	taskName: string;
+	taskTitle: string;
+	owner: string;
+	token: string;
+	claimedAt: string;
+	leaseExpiresAt: string;
+	heartbeatAt?: string;
+	note?: string;
+}
+
+function isTaskLeaseView(value: unknown): value is TaskLeaseViewOutput {
+	if (typeof value !== "object" || value === null) return false;
+	const row = value as Record<string, unknown>;
+	return (
+		typeof row.taskName === "string" &&
+		typeof row.taskTitle === "string" &&
+		typeof row.owner === "string" &&
+		typeof row.token === "string" &&
+		typeof row.claimedAt === "string" &&
+		typeof row.leaseExpiresAt === "string" &&
+		(row.heartbeatAt === undefined || typeof row.heartbeatAt === "string") &&
+		(row.note === undefined || typeof row.note === "string")
+	);
+}
+
+/** Renders a lease's own safe fields -- never the raw token, which the model channel (not this persisted, human-facing one) carries for a later heartbeat/release call. */
+function renderLease(
+	lease: {
+		taskName: string;
+		taskTitle: string;
+		owner: string;
+		claimedAt: string;
+		leaseExpiresAt: string;
+		heartbeatAt?: string;
+		note?: string;
+	},
+	theme: Theme,
+): Component {
+	return statelessComponent((width) => {
+		const fields: DetailField[] = [
+			{ label: "Task", value: `${lease.taskName} \u2014 ${lease.taskTitle}` },
+			{ label: "Owner", value: lease.owner },
+			{ label: "Expires", value: lease.leaseExpiresAt },
+			...(lease.heartbeatAt ? [{ label: "Last heartbeat", value: lease.heartbeatAt }] : []),
+			...(lease.note ? [{ label: "Note", value: lease.note }] : []),
+		];
+		return buildDetailLines(Math.max(1, width), { fields, alignFields: true, theme: detailViewTheme(theme), measure });
+	});
+}
+
+/** Deliberately does not catch: a value JSON.stringify can't serialize (e.g. a circular
+ * reference) has no safe textual fallback, so this propagates and the projector's own caller
+ * (invokeVehicleOperation) fails the whole call closed rather than persisting a placeholder --
+ * the same "never silently substitute raw/unsafe output" contract every other projection
+ * failure already carries. */
+function boundedJsonPreview(value: unknown): string {
+	const text = JSON.stringify(value, null, 2);
+	return typeof text === "string" ? text : String(value);
+}
+
 export function papyrusVehicleRenderers(descriptor: VehicleOperationDescriptor): VehicleToolRenderers {
 	return {
 		// Pure pass-through to the generic renderer -- the only reason this exists at all is
@@ -455,3 +551,105 @@ export function papyrusVehicleRenderers(descriptor: VehicleOperationDescriptor):
 		},
 	};
 }
+
+/**
+ * Projects a raw Papyrus operation output into a bounded, versioned PapyrusToolDetails DTO
+ * before Pi ever persists it -- the seam papyrusVehicleRenderers' own renderResult never had
+ * (it only converts shape at render time, from whatever the legacy {vehicle, output} path
+ * already persisted verbatim, lease tokens and all). Every branch here mirrors the same
+ * shape-detection papyrusVehicleRenderers's own renderResult uses, so the two stay in lockstep;
+ * anything genuinely unmatched still becomes a real, bounded PreviewToolDetails rather than an
+ * unprojected raw passthrough -- the one requirement this whole seam exists to satisfy.
+ */
+function projectPapyrusPresentation(descriptor: VehicleOperationDescriptor, output: unknown): JsonValue {
+	if (isArtifactArray(output)) return createArtifactListDetails(descriptor.name, output) as unknown as JsonValue;
+	if (isArtifact(output)) return createArtifactDetails(descriptor.name, output) as unknown as JsonValue;
+	if (isTaskFocus(output)) return createArtifactDetails(descriptor.name, output.artifact, focusAnnotation(output)) as unknown as JsonValue;
+	if (output === null && descriptor.name === "tasks.focused") return createNoFocusDetails(descriptor.name) as unknown as JsonValue;
+	if (isTaskExecutionPlan(output))
+		return createExecutionPlanDetails(descriptor.name, output.nodes, output.layers, output.cycleIds) as unknown as JsonValue;
+	if (isPlaybookInvocationResult(output)) {
+		return createPlaybookInvocationDetails(descriptor.name, {
+			playbookId: output.playbookId,
+			runId: output.runId,
+			created: output.created,
+			rootTaskIds: output.rootTaskIds,
+			entryTaskId: output.entryTaskId,
+			execution: output.execution,
+		}) as unknown as JsonValue;
+	}
+	if (isPlaybookMissingArguments(output)) {
+		return createPlaybookMissingArgumentsDetails(descriptor.name, output.playbookId, output.missingArguments) as unknown as JsonValue;
+	}
+	if (isDiscussionAndRounds(output))
+		return createDiscussionDetails(descriptor.name, output.rounds, output.discussion) as unknown as JsonValue;
+	if (isDiscussionRoundsOnly(output)) return createDiscussionDetails(descriptor.name, output.rounds) as unknown as JsonValue;
+	if (isDiscussionListOutput(output)) return createArtifactListDetails(descriptor.name, output.discussions) as unknown as JsonValue;
+	if (isTaskCompletion(output)) return createTaskCompletionDetails(descriptor.name, output) as unknown as JsonValue;
+	if (isTaskLeaseView(output)) return createLeaseDetails(descriptor.name, output) as unknown as JsonValue;
+	return createPreviewDetails(descriptor.name, descriptor.name, boundedJsonPreview(output)) as unknown as JsonValue;
+}
+
+function renderFromPapyrusPresentation(
+	presentation: NonNullable<ReturnType<typeof parsePapyrusToolDetails>>,
+	theme: Theme,
+	expanded: boolean,
+): Component {
+	switch (presentation.kind) {
+		case "artifact-list":
+			return new ArtifactListCard(presentation, theme, expanded);
+		case "artifact":
+			return new ArtifactCard(presentation, theme, expanded);
+		case "no-focus":
+			return renderNoFocusedTask(theme);
+		case "execution-plan":
+			return renderTaskExecutionPlan(presentation, theme, expanded);
+		case "playbook-invocation":
+			return renderPlaybookInvocationResult(presentation, theme, expanded);
+		case "playbook-missing-arguments":
+			return renderPlaybookMissingArguments(presentation, theme);
+		case "discussion":
+			return presentation.discussion
+				? renderDiscussionAndRounds({ discussion: presentation.discussion, rounds: presentation.rounds }, theme, expanded)
+				: renderDiscussionRoundsOnly(presentation, theme);
+		case "task-completion":
+			return renderTaskCompletion(presentation, theme, expanded);
+		case "lease":
+			return renderLease(presentation, theme);
+		case "preview":
+			return new Text(theme.fg("toolOutput", presentation.content), 0, 0);
+		case "transition":
+		case "graph":
+		case "gate-run":
+		case "invocation":
+		case "error":
+			// Reachable only if a future caller starts producing these kinds through this seam
+			// (today's Papyrus Vehicle outputs never do) -- a bounded JSON preview is still a
+			// real, safe rendering rather than a crash.
+			return new Text(theme.fg("toolOutput", boundedJsonPreview(presentation)), 0, 0);
+	}
+}
+
+/**
+ * Pairs the projector above with a renderResult that reads the already-projected,
+ * already-bounded `details.presentation` DTO instead of raw `details.output` -- the seam
+ * pi-papyrus task "project typed bounded render details before Vehicle persists" exists for.
+ * Falls back to papyrusVehicleRenderers' own renderResult (which still reads `details.output`)
+ * for a partial/progress update, an error result, or a historical session row persisted before
+ * this seam existed -- both keep working exactly as before, unchanged.
+ */
+export function papyrusVehiclePresentations(descriptor: VehicleOperationDescriptor): PiVehiclePresentationContract {
+	return {
+		projector: {
+			maxBytes: TOOL_DETAILS_MAX_SERIALIZED_CHARACTERS,
+			project: (output: unknown, _request: PiVehicleInvocationRequest) => projectPapyrusPresentation(descriptor, output),
+		},
+		renderResult(result, options, theme, context) {
+			if (!options.isPartial && !context.isError) {
+				const presentation = parsePapyrusToolDetails((result.details as { presentation?: unknown } | undefined)?.presentation);
+				if (presentation) return renderFromPapyrusPresentation(presentation, theme, options.expanded);
+			}
+			return papyrusVehicleRenderers(descriptor).renderResult!(result, options, theme, context);
+		},
+	};
+}

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

@@ -32,7 +32,7 @@ import { currentVehicleClientTarget } from "../service-client.ts";
 import { sessionSecretField } from "../session-identity.ts";
 import { emitTaskFocusEvent } from "../task/task-focus-events.ts";
 import { recordRenderDiagnostic, shapeFingerprint } from "./render-diagnostics.ts";
-import { papyrusVehicleRenderers } from "./vehicle-artifact-renderers.ts";
+import { papyrusVehiclePresentations, papyrusVehicleRenderers } from "./vehicle-artifact-renderers.ts";
 
 const REGISTERED_PERMISSIONS = [
 	"notes:read",
@@ -135,6 +135,12 @@ export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehi
 		permissions: REGISTERED_PERMISSIONS,
 		principal: { id: "pi-papyrus" },
 		renderers: papyrusVehicleRenderers,
+		// papyrusVehiclePresentations projects a bounded, versioned PapyrusToolDetails DTO
+		// before Pi persists this call's details -- renderers above still supplies renderCall
+		// (createTool sources renderCall/renderResult independently; presentations' own
+		// renderResult takes priority over renderers' renderResult, and falls back to it for a
+		// partial/error result or a historical session row persisted before this seam existed).
+		presentations: papyrusVehiclePresentations,
 		shell: { coreOperations: CORE_OPERATIONS },
 		// playbooks.invoke's own module handler, and tasks.focus/pause/unpause/clear_focus's
 		// own module handlers, authorize an internal Task Focus write via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.49.1",
+  "version": "0.50.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"],
@@ -20,7 +20,7 @@
     "@danypops/jittor": "^0.14.0",
     "@danypops/papyrus": "^0.47.0",
     "@danypops/vehicle-client": "^0.7.0",
-    "@danypops/vehicle-client-pi": "^0.22.0",
+    "@danypops/vehicle-client-pi": "^0.22.1",
     "@danypops/vehicle-core": "^0.12.3",
     "@danypops/vehicle-server": "^0.18.1",
     "beautiful-mermaid": "1.1.3",
@@ -28,6 +28,7 @@
   },
   "devDependencies": {
     "@danypops/pi-tui-harness": "^0.0.2",
+    "@danypops/vehicle-conformance": "^0.3.0",
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "bun-types": "latest",
     "typebox": "^1.3.6",