@danypops/pi-papyrus 0.46.4 → 0.46.5

package/extension/src/tools/render-diagnostics.ts

@@ -0,0 +1,59 @@
+/**
+ * Temporary diagnostic instrumentation for the still-open /reload rendering-fallback
+ * investigation (papyrus task 4930cd9b): a Vehicle tool call executes and returns real
+ * data but renders as raw JSON (call args and result both) instead of through its
+ * registered renderCall/renderResult. Leading theory: a timing race between
+ * registerVehicleToolsWhenReady's fire-and-forget registration attempt and Pi resolving
+ * a tool's ToolDefinition (session.getToolDefinition(name), read live from Pi's own
+ * _toolDefinitions Map at the moment a tool-call message streams in -- see
+ * @earendil-works/pi-coding-agent's agent-session.js/interactive-mode.ts).
+ *
+ * Opt-in (PAPYRUS_RENDER_DIAG=1) and best-effort (never throws, never blocks a real
+ * call) -- appends JSONL to PAPYRUS_RENDER_DIAG_PATH (default
+ * ~/.cache/papyrus/render-diag.log). Content-safe: never logs artifact body/title text,
+ * only lengths and a small allow-listed set of short categorical fields (id/kind/status/
+ * subtype/alias), matching the same discipline as every other diagnostic log in this
+ * ecosystem (e.g. pi-web-spider's own diag.log).
+ *
+ * Remove once the investigation concludes either way.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const SAFE_LITERAL_KEYS = new Set(["id", "kind", "status", "subtype", "alias"]);
+
+function isEnabled(): boolean {
+	return process.env.PAPYRUS_RENDER_DIAG === "1";
+}
+
+function diagPath(): string {
+	return process.env.PAPYRUS_RENDER_DIAG_PATH ?? join(homedir(), ".cache", "papyrus", "render-diag.log");
+}
+
+/** Redacts to shape + length, never content -- except a small allow-listed set of short, non-sensitive categorical fields. */
+export function shapeFingerprint(value: unknown, key?: string): unknown {
+	if (value === null || value === undefined) return value;
+	if (Array.isArray(value))
+		return { type: "array", length: value.length, sample: value.length > 0 ? shapeFingerprint(value[0]) : undefined };
+	if (typeof value === "string") return key && SAFE_LITERAL_KEYS.has(key) ? value : { type: "string", length: value.length };
+	if (typeof value === "boolean" || typeof value === "number") return value;
+	if (typeof value === "object") {
+		const row = value as Record<string, unknown>;
+		const fields: Record<string, unknown> = {};
+		for (const [fieldKey, fieldValue] of Object.entries(row)) fields[fieldKey] = shapeFingerprint(fieldValue, fieldKey);
+		return { type: "object", keys: Object.keys(row), fields };
+	}
+	return { type: typeof value };
+}
+
+export function recordRenderDiagnostic(entry: Record<string, unknown>): void {
+	if (!isEnabled()) return;
+	try {
+		const path = diagPath();
+		mkdirSync(dirname(path), { recursive: true });
+		appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`);
+	} catch {
+		/* best-effort -- a broken diagnostic log must never break a real render or invocation */
+	}
+}

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

@@ -15,7 +15,7 @@
 import type { Artifact } from "@danypops/papyrus";
 import { TOOL_COLLAPSED_ROW_LIMIT } from "@danypops/papyrus";
 import type { VehicleToolRenderers } from "@danypops/vehicle-client-pi";
-import { renderVehicleResult } from "@danypops/vehicle-client-pi/vehicle-render";
+import { renderVehicleCall, renderVehicleResult } from "@danypops/vehicle-client-pi/vehicle-render";
 import type { VehicleOperationDescriptor } from "@danypops/vehicle-core";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
@@ -31,6 +31,7 @@ import {
 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 { recordRenderDiagnostic, shapeFingerprint } from "./render-diagnostics.ts";
 
 function isArtifact(value: unknown): value is Artifact {
 	if (typeof value !== "object" || value === null) return false;
@@ -385,9 +386,29 @@ function renderTaskCompletion(result: TaskCompletionOutput, theme: Theme, expand
 
 export function papyrusVehicleRenderers(descriptor: VehicleOperationDescriptor): VehicleToolRenderers {
 	return {
+		// Pure pass-through to the generic renderer -- the only reason this exists at all is
+		// the /reload investigation (papyrus task 4930cd9b): its absence from the diagnostic
+		// log for a real invocation (see onInvoked in vehicle-notes-client.ts) is itself
+		// evidence Pi never found ANY renderer -- ours or vehicle-client-pi's generic default
+		// -- for that specific tool call, distinct from this renderer running and choosing
+		// the generic path internally (which DOES show up here).
+		renderCall(args, theme, context) {
+			recordRenderDiagnostic({ event: "render-call-invoked", operation: descriptor.name });
+			return renderVehicleCall(descriptor, args, theme, context);
+		},
 		renderResult(result, options, theme, context) {
 			if (!options.isPartial && !context.isError) {
 				const output = (result.details as { output?: unknown } | undefined)?.output;
+				// /reload rendering-fallback investigation (papyrus task 4930cd9b) -- correlates
+				// against vehicle-notes-client.ts's onInvoked/vehicle-ready diagnostics by
+				// descriptor.name and wall-clock time.
+				recordRenderDiagnostic({
+					event: "render-result-dispatch",
+					operation: descriptor.name,
+					isArtifact: isArtifact(output),
+					isArtifactArray: isArtifactArray(output),
+					output: shapeFingerprint(output),
+				});
 				if (isArtifactArray(output)) {
 					return new ArtifactListCard(createArtifactListDetails(descriptor.name, output), theme, options.expanded);
 				}
@@ -428,6 +449,7 @@ export function papyrusVehicleRenderers(descriptor: VehicleOperationDescriptor):
 				if (isTaskCompletion(output)) {
 					return renderTaskCompletion(output, theme, options.expanded);
 				}
+				recordRenderDiagnostic({ event: "render-result-fell-through-to-generic", operation: descriptor.name });
 			}
 			return renderVehicleResult(descriptor, result, options, theme, context);
 		},

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

@@ -31,6 +31,7 @@ import { discussLiveFollowUp } from "../discuss/discuss-live-follow-up.ts";
 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";
 
 const REGISTERED_PERMISSIONS = [
@@ -103,13 +104,21 @@ function notifyReadyEvent(event: VehicleReadyEvent): void {
  * awaiting it is optional and mainly useful for tests.
  */
 export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehicle | undefined> {
+	recordRenderDiagnostic({ event: "register-notes-vehicle-called" });
 	const client = createReconnectingVehicleClient(async () => {
 		const resolved = currentVehicleClientTarget();
 		if (!resolved) throw new Error("Papyrus daemon is not running");
 		return new RemoteVehicleClient({ baseUrl: resolved.baseUrl, token: resolved.token });
 	});
 	return registerVehicleToolsWhenReady(pi, () => Promise.resolve(currentVehicleClientTarget() ? client : undefined), {
-		log: notifyReadyEvent,
+		log: (event) => {
+			// Correlates against onInvoked's own timestamps below -- the /reload investigation's
+			// leading theory is a race between this fire-and-forget registration actually
+			// completing (this "registered" event) and Pi resolving a tool's ToolDefinition for
+			// rendering at the moment its tool-call message streams in.
+			recordRenderDiagnostic({ event: "vehicle-ready", kind: event.kind, ...("attempt" in event ? { attempt: event.attempt } : {}) });
+			notifyReadyEvent(event);
+		},
 		permissions: REGISTERED_PERMISSIONS,
 		principal: { id: "pi-papyrus" },
 		renderers: papyrusVehicleRenderers,
@@ -157,6 +166,9 @@ export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehi
 		// let those run before the human sees the prompt -- same reasoning here.
 		executionMode: (descriptor) => (descriptor.name === "discuss.open" || descriptor.name === "discuss.reply" ? "sequential" : undefined),
 		onInvoked: ({ descriptor }, output) => {
+			// See vehicle-notes-client.ts's log wiring above -- correlates a real invocation's
+			// timestamp against when registration actually completed.
+			recordRenderDiagnostic({ event: "invoked", operation: descriptor.name, output: shapeFingerprint(output) });
 			if (descriptor.name === "tasks.focus") {
 				const artifact = output as { id: string } | undefined;
 				if (artifact?.id) emitTaskFocusEvent({ taskId: artifact.id, status: "focused" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.46.4",
+  "version": "0.46.5",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],