@danypops/pi-papyrus 0.46.3 → 0.46.5

package/extension/src/index.ts

@@ -694,21 +694,17 @@ export default async function (pi: ExtensionAPI) {
 		},
 	});
 
+	// registerNotesVehicle defers the actual registerVehicleTools() call to session_start
+	// internally (via registerVehicleToolsWhenReady), since Pi's extension runtime only
+	// finishes initializing (pi.getAllTools()/etc. becoming callable) after every
+	// extension's top-level factory has resolved. Calling it here, at factory time, is
+	// therefore safe -- and deliberately not awaited, so a slow-starting daemon's bounded
+	// retries never block this factory or session_start itself.
+	void registerNotesVehicle(pi);
+
 	// ── Task widget (TodoOverlay pattern: factory form, requestRender) ──
 
 	pi.on("session_start", async (_event, ctx) => {
-		// registerVehicleTools() (which registerNotesVehicle wraps) needs
-		// pi.getAllTools()/getActiveTools()/setActiveTools() -- Pi's extension
-		// runtime only finishes initializing after every extension's top-level
-		// factory (this one included) has resolved, so calling it directly from
-		// there throws "Extension runtime not initialized" (previously silently
-		// swallowed by registerNotesVehicle's own daemon-unreachable try/catch,
-		// making every projected notes.* tool invisible to the model with zero
-		// visible sign why -- confirmed live in the identical pi-tickets bug).
-		// session_start fires only after that initialization completes, and Pi
-		// awaits every session_start handler before the model's first turn, so
-		// registering here is both safe and still visible on turn one.
-		await registerNotesVehicle(pi);
 		// Registers this session's identity with the daemon as early as possible -- before any
 		// Focus-mutating call could plausibly happen -- shrinking (not eliminating; see
 		// domain/session-identity.ts) the first-touch race window. Best-effort: the daemon may be

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

@@ -4,30 +4,34 @@
  * src/handlers/registry.ts. discuss.* is the last of the six domains to
  * migrate off pi-papyrus's own retired hand-rolled pi.registerTool() mega-tool.
  *
- * Fails silently on a stale/unreachable daemon handle instead of aborting extension
- * setup: Papyrus's daemon doesn't auto-spawn, and a tool that failed to register
- * here has no later retry path.
+ * Deferred to registerVehicleToolsWhenReady's own internal session_start handler
+ * (bounded retry/backoff, matching pi-tickets' registerTicketsVehicle) rather than
+ * a single unretried attempt: a daemon that's merely slow to start, or transiently
+ * unreachable right when session_start fires (including on /reload, which re-runs
+ * this extension's factory and this call), no longer permanently drops every
+ * notes/rules/docs/playbooks/tasks/discuss/artifact tool for the rest of the
+ * session. Every outcome logs through ctx.ui.notify instead of vanishing.
  *
  * Uses service-client.ts's currentVehicleClientTarget() (test-injectable) rather
  * than resolveVehicleClientTarget() directly, so a test exercising the full
  * extension entrypoint doesn't resolve a real daemonStateDir().
  *
- * The client itself is wrapped in createReconnectingVehicleClient(), re-resolving
+ * The client itself is wrapped in createReconnectingVehicleClient() once, re-resolving
  * currentVehicleClientTarget() on every reconnect attempt rather than closing over
- * one target captured here at session_start -- confirmed live: the daemon rebinds
- * a new random port on every restart, and a bare RemoteVehicleClient built once had
- * no way to notice its baseUrl had died, breaking every Vehicle tool call for the
- * rest of the Pi session until a full extension reload.
+ * one target captured here -- the daemon rebinds a new random port on every restart,
+ * so a bare RemoteVehicleClient built once would have no way to notice its baseUrl
+ * had died.
  */
 
 import { createReconnectingVehicleClient } from "@danypops/vehicle-client/daemon-client";
 import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
-import { registerVehicleTools } from "@danypops/vehicle-client-pi";
+import { type RegisteredPiVehicle, registerVehicleToolsWhenReady, type VehicleReadyEvent } from "@danypops/vehicle-client-pi";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 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 = [
@@ -59,82 +63,127 @@ const FOCUS_MUTATION_OPERATIONS = new Set(["tasks.focus", "tasks.pause", "tasks.
  */
 const CORE_OPERATIONS = ["tasks.list", "tasks.create", "tasks.start", "tasks.submit", "tasks.complete", "tasks.context"];
 
-export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
-	const target = currentVehicleClientTarget();
-	if (!target) return;
-	try {
-		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 });
-		});
-		await registerVehicleTools(pi, client, {
-			permissions: REGISTERED_PERMISSIONS,
-			principal: { id: "pi-papyrus" },
-			renderers: papyrusVehicleRenderers,
-			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
-			// sessionIdentity.assertAuthorized(session_id, session_secret) -- see
-			// @danypops/papyrus's src/handlers/playbooks.ts and tasks.ts. That
-			// secret must never be a model-visible input field (the model has no business
-			// knowing or supplying it), so it travels here instead, in principal.claims, from
-			// this extension's own already-cached secret (registered at session_start -- see
-			// index.ts) -- the same value sessionSecretField() used to thread through as a raw
-			// RPC input field before these operations moved onto Vehicle.
-			resolveInvocation: ({ descriptor, input, context }) => {
-				if (descriptor.name !== "playbooks.invoke" && !FOCUS_MUTATION_OPERATIONS.has(descriptor.name)) return {};
-				// tasks.* defaults session_id to this Pi session's own id, same as the removed
-				// hand-rolled tool -- but the secret cache is keyed by whichever session_id is
-				// actually being authorized, not blindly this session's, so a model that
-				// explicitly overrides session_id to a DIFFERENT session never gets this
-				// session's secret smuggled in on its behalf.
-				const requestedSessionId = (input as { session_id?: unknown } | undefined)?.session_id;
-				const sessionId =
-					typeof requestedSessionId === "string" && requestedSessionId.length > 0
-						? requestedSessionId
-						: context.sessionManager.getSessionId();
-				const { session_secret: sessionSecret } = sessionSecretField(sessionId);
-				// Omit sessionSecret entirely when nothing is cached (unregistered session) --
-				// {sessionSecret: null} would fail the module's own optionalString(input,
-				// "session_secret") check (undefined-or-string, not null), a real regression from
-				// sessionSecretField()'s own {} (key omitted) return for the same case.
-				const claims: Record<string, string> = sessionSecret ? { sessionId, sessionSecret } : { sessionId };
-				return { principal: { id: "pi-papyrus", claims } };
-			},
-			// papyrus.task-focus.v1 is a same-process Pi extension event bus broadcast (e.g. a
-			// token-cost router correlating its own telemetry with the currently focused task)
-			// -- has no Vehicle-transport equivalent, so it's emitted here, client-side, rather
-			// than from the operation's own output.
-			// discuss.open/discuss.reply's own live:true synchronous human round-trip --
-			// see discuss/discuss-live-follow-up.ts. Every other operation's resolver call
-			// returns undefined, meaning zero behavior change for the other 5 domains.
-			interactiveFollowUps: (descriptor) =>
-				descriptor.name === "discuss.open" || descriptor.name === "discuss.reply" ? discussLiveFollowUp : undefined,
-			// The retired discuss tool declared executionMode: "sequential" so the model
-			// couldn't batch a live ask alongside other tool calls in the same turn and
-			// 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) => {
-				if (descriptor.name === "tasks.focus") {
-					const artifact = output as { id: string } | undefined;
-					if (artifact?.id) emitTaskFocusEvent({ taskId: artifact.id, status: "focused" });
-					return;
-				}
-				if (descriptor.name === "tasks.pause" || descriptor.name === "tasks.unpause") {
-					const focus = output as { artifact: { id: string } } | undefined;
-					if (focus?.artifact?.id)
-						emitTaskFocusEvent({ taskId: focus.artifact.id, status: descriptor.name === "tasks.pause" ? "paused" : "unpaused" });
-					return;
-				}
-				if (descriptor.name === "tasks.clear_focus") {
-					const result = output as { cleared: boolean } | undefined;
-					if (result?.cleared) emitTaskFocusEvent({ taskId: null, status: "cleared" });
-				}
-			},
-		});
-	} catch {
-		// Daemon state is stale/unreachable -- degrade silently, matching
-		// subscribeTaskPushChannel's own tolerance for the same condition.
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Surfaces a real resolution/registration error and the terminal exhausted state (the
+ * case that used to leave every notes/rules/docs/playbooks/tasks/discuss/artifact tool
+ * unregistered for the whole session with no visible sign why) -- a daemon merely still
+ * starting up (repeated client-unavailable before the last attempt) stays quiet, matching
+ * pi-tickets' own notifyReadyEvent.
+ */
+function notifyReadyEvent(event: VehicleReadyEvent): void {
+	switch (event.kind) {
+		case "client-resolution-failed":
+			event.ctx.ui.notify(`papyrus daemon target resolution failed: ${errorMessage(event.error)}`, "warning");
+			return;
+		case "registration-failed":
+			event.ctx.ui.notify(`papyrus tool registration failed: ${errorMessage(event.error)}`, "warning");
+			return;
+		case "exhausted":
+			event.ctx.ui.notify(
+				`papyrus tools unavailable this session -- the daemon never became reachable after ${event.attempts} attempts`,
+				"warning",
+			);
+			return;
+		case "client-unavailable":
+		case "registered":
+			return;
 	}
 }
+
+/**
+ * Fire-and-forget from the extension's top-level factory: registerVehicleToolsWhenReady
+ * registers its own session_start handler internally and defers the actual
+ * pi.getAllTools()/getActiveTools()/setActiveTools() calls to it (Pi's extension runtime
+ * only finishes initializing after every extension's factory has resolved, so calling
+ * registerVehicleTools directly from here throws "Extension runtime not initialized").
+ * The returned promise settles once that sequence succeeds or exhausts its attempts --
+ * 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: (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,
+		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
+		// sessionIdentity.assertAuthorized(session_id, session_secret) -- see
+		// @danypops/papyrus's src/handlers/playbooks.ts and tasks.ts. That
+		// secret must never be a model-visible input field (the model has no business
+		// knowing or supplying it), so it travels here instead, in principal.claims, from
+		// this extension's own already-cached secret (registered at session_start -- see
+		// index.ts) -- the same value sessionSecretField() used to thread through as a raw
+		// RPC input field before these operations moved onto Vehicle.
+		resolveInvocation: ({ descriptor, input, context }) => {
+			if (descriptor.name !== "playbooks.invoke" && !FOCUS_MUTATION_OPERATIONS.has(descriptor.name)) return {};
+			// tasks.* defaults session_id to this Pi session's own id, same as the removed
+			// hand-rolled tool -- but the secret cache is keyed by whichever session_id is
+			// actually being authorized, not blindly this session's, so a model that
+			// explicitly overrides session_id to a DIFFERENT session never gets this
+			// session's secret smuggled in on its behalf.
+			const requestedSessionId = (input as { session_id?: unknown } | undefined)?.session_id;
+			const sessionId =
+				typeof requestedSessionId === "string" && requestedSessionId.length > 0
+					? requestedSessionId
+					: context.sessionManager.getSessionId();
+			const { session_secret: sessionSecret } = sessionSecretField(sessionId);
+			// Omit sessionSecret entirely when nothing is cached (unregistered session) --
+			// {sessionSecret: null} would fail the module's own optionalString(input,
+			// "session_secret") check (undefined-or-string, not null), a real regression from
+			// sessionSecretField()'s own {} (key omitted) return for the same case.
+			const claims: Record<string, string> = sessionSecret ? { sessionId, sessionSecret } : { sessionId };
+			return { principal: { id: "pi-papyrus", claims } };
+		},
+		// papyrus.task-focus.v1 is a same-process Pi extension event bus broadcast (e.g. a
+		// token-cost router correlating its own telemetry with the currently focused task)
+		// -- has no Vehicle-transport equivalent, so it's emitted here, client-side, rather
+		// than from the operation's own output.
+		// discuss.open/discuss.reply's own live:true synchronous human round-trip --
+		// see discuss/discuss-live-follow-up.ts. Every other operation's resolver call
+		// returns undefined, meaning zero behavior change for the other 5 domains.
+		interactiveFollowUps: (descriptor) =>
+			descriptor.name === "discuss.open" || descriptor.name === "discuss.reply" ? discussLiveFollowUp : undefined,
+		// The retired discuss tool declared executionMode: "sequential" so the model
+		// couldn't batch a live ask alongside other tool calls in the same turn and
+		// 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" });
+				return;
+			}
+			if (descriptor.name === "tasks.pause" || descriptor.name === "tasks.unpause") {
+				const focus = output as { artifact: { id: string } } | undefined;
+				if (focus?.artifact?.id)
+					emitTaskFocusEvent({ taskId: focus.artifact.id, status: descriptor.name === "tasks.pause" ? "paused" : "unpaused" });
+				return;
+			}
+			if (descriptor.name === "tasks.clear_focus") {
+				const result = output as { cleared: boolean } | undefined;
+				if (result?.cleared) emitTaskFocusEvent({ taskId: null, status: "cleared" });
+			}
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.46.3",
+  "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"],