@danypops/pi-papyrus 0.46.3 → 0.46.4

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/vehicle-notes-client.ts

@@ -4,25 +4,28 @@
  * 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";
@@ -59,82 +62,116 @@ 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> {
+	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,
+		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" });
+			}
+		},
+	});
+}

package/package.json

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