@danypops/pi-papyrus 0.57.10 → 0.59.0

package/extension/src/index.ts

@@ -50,7 +50,7 @@ import {
 	automaticPauseReason,
 	shouldResumeFocusOnHumanInput,
 } from "./task/active-task-continuation.ts";
-import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task/task-focus-events.ts";
+import { emitTaskFocusEvent, extractDeclaredEffort, setTaskFocusEventBus } from "./task/task-focus-events.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task/task-presentation.ts";
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task/task-widget.ts";
 import { measure as artifactCardMeasure } from "./tool-rendering/artifact-card.ts";
@@ -492,7 +492,7 @@ export default async function (pi: ExtensionAPI) {
 					session_id: sessionId,
 					...sessionSecretField(sessionId),
 				});
-				emitTaskFocusEvent({ taskId: paused.artifact.id, sessionId, status: "paused" });
+				emitTaskFocusEvent({ taskId: paused.artifact.id, sessionId, status: "paused", effort: extractDeclaredEffort(paused.artifact.extra) });
 				if (ctx.hasUI) ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Human input resumes it automatically.`, "warning");
 			}
 		} catch {
@@ -896,7 +896,12 @@ export default async function (pi: ExtensionAPI) {
 					session_id: sessionId,
 					...sessionSecretField(sessionId),
 				});
-				emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId, status: "unpaused" });
+				emitTaskFocusEvent({
+					taskId: focus.artifact.id,
+					sessionId,
+					status: "unpaused",
+					effort: extractDeclaredEffort(focus.artifact.extra),
+				});
 			}
 		} catch {
 			// The daemon may be unavailable during startup, reload, or shutdown.

package/extension/src/task/task-focus-events.ts

@@ -3,12 +3,31 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export type TaskFocusStatus = "focused" | "paused" | "unpaused" | "cleared";
 
+/**
+ * A Task's own declared effort convention (`extra.effort`) -- Papyrus's core schema and
+ * validation know nothing about this value; it is genuine free-form `extra` JSON, the same
+ * mechanism `gates`/`checklist` already use. This module only reads it, opaquely, to relay it
+ * on the task-focus broadcast when present; Papyrus never assigns or requires it.
+ */
+export const TASK_DECLARED_EFFORT_LEVELS = ["low", "medium", "high"] as const;
+export type TaskDeclaredEffort = (typeof TASK_DECLARED_EFFORT_LEVELS)[number];
+
+/** Returns the task's own declared `extra.effort` when it is one of the recognized values, or undefined otherwise -- an absent or malformed value is silently omitted, never guessed or defaulted. */
+export function extractDeclaredEffort(extra: Record<string, unknown> | undefined): TaskDeclaredEffort | undefined {
+	const value = extra?.effort;
+	return typeof value === "string" && (TASK_DECLARED_EFFORT_LEVELS as readonly string[]).includes(value)
+		? (value as TaskDeclaredEffort)
+		: undefined;
+}
+
 export interface TaskFocusEvent {
 	schema: typeof PAPYRUS_TASK_FOCUS_SCHEMA;
 	taskId: string | null;
 	sessionId?: string;
 	status: TaskFocusStatus;
 	observedAt: number;
+	/** The focused task's own declared `extra.effort`, when it has one -- omitted (never null) otherwise, matching this payload's existing minimalism. */
+	effort?: TaskDeclaredEffort;
 }
 
 export interface TaskFocusEventInput {
@@ -16,14 +35,16 @@ export interface TaskFocusEventInput {
 	sessionId?: string;
 	status: TaskFocusStatus;
 	observedAt?: number;
+	effort?: TaskDeclaredEffort;
 }
 
 /**
  * Pure event builder, mirroring buildContextInjection's shape: no task title, body, or any other
- * artifact content -- only the id, session, lifecycle status, and timestamp, which are already
- * public metadata a caller with the id could look up directly. This is the payload emitted on
- * papyrus.task-focus.v1, the analogue of papyrus.context-injection.v1, so extensions such as a
- * token-cost router can correlate their own telemetry with the currently focused task without
+ * artifact content -- only the id, session, lifecycle status, timestamp, and (when the task
+ * declares one) its own bounded effort enum, which are already public metadata a caller with the
+ * id could look up directly. This is the payload emitted on papyrus.task-focus.v1, the analogue
+ * of papyrus.context-injection.v1, so extensions such as a token-cost router can correlate their
+ * own telemetry with the currently focused task -- and now its declared effort -- without
  * Papyrus depending on them.
  */
 export function buildTaskFocusEvent(input: TaskFocusEventInput): TaskFocusEvent {
@@ -35,6 +56,7 @@ export function buildTaskFocusEvent(input: TaskFocusEventInput): TaskFocusEvent
 		status: input.status,
 		observedAt: input.observedAt ?? Date.now(),
 		...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+		...(input.effort === undefined ? {} : { effort: input.effort }),
 	};
 }
 

package/extension/src/task/tasks.ts

@@ -25,7 +25,7 @@ import {
 import { callService } from "../service-client.ts";
 import { sessionSecretField } from "../session-identity.ts";
 import { showTaskDetails } from "./task-detail-view.ts";
-import { emitTaskFocusEvent } from "./task-focus-events.ts";
+import { emitTaskFocusEvent, extractDeclaredEffort } from "./task-focus-events.ts";
 import { showTaskGraph } from "./task-graph.ts";
 
 export { taskDetailsText } from "./task-detail-format.ts";
@@ -313,7 +313,7 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 					session_id: sessionId,
 					...sessionSecretField(sessionId),
 				});
-				emitTaskFocusEvent({ taskId: focused.id, sessionId, status: "focused" });
+				emitTaskFocusEvent({ taskId: focused.id, sessionId, status: "focused", effort: extractDeclaredEffort(focused.extra) });
 				ctx.ui.notify(`Active: ${action.row.title}`, "info");
 			} catch (error) {
 				ctx.ui.notify(`Focus failed: ${error instanceof Error ? error.message : error}`, "error");
@@ -336,7 +336,12 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 						session_id: sessionId,
 						...sessionSecretField(sessionId),
 					});
-					emitTaskFocusEvent({ taskId: result.artifact.id, sessionId, status: choice === "Pause focus" ? "paused" : "unpaused" });
+					emitTaskFocusEvent({
+						taskId: result.artifact.id,
+						sessionId,
+						status: choice === "Pause focus" ? "paused" : "unpaused",
+						effort: extractDeclaredEffort(result.artifact.extra),
+					});
 				}
 				ctx.ui.notify(choice === "Clear focus" ? "Task focus cleared" : choice, "info");
 			} catch (error) {

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

@@ -23,6 +23,7 @@
  * had died.
  */
 
+import { createAgentNotifier } from "@danypops/vehicle-client-pi/agent-poll-ticker";
 import { createReconnectingVehicleClient, daemonInstanceIdentity } from "@danypops/vehicle-client/daemon-client";
 import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
 import {
@@ -31,11 +32,12 @@ import {
 	registerVehicleToolsWhenReady,
 	type VehicleReadyEvent,
 } from "@danypops/vehicle-client-pi";
+import { VehicleApprovalOutcomePoll } from "@danypops/vehicle-client-pi/vehicle-approval-outcome-poll";
 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 { emitTaskFocusEvent, extractDeclaredEffort } from "../task/task-focus-events.ts";
 import { recordRenderDiagnostic, shapeFingerprint } from "./render-diagnostics.ts";
 import { papyrusVehiclePresentations, papyrusVehicleRenderers } from "./vehicle-artifact-renderers.ts";
 
@@ -61,6 +63,13 @@ export const PAPYRUS_VEHICLE_PERMISSIONS = [
 /** Task Focus's own internal write needs a real, per-session secret -- see below. Every other tasks.* operation reads session_id purely for read-scoping and needs no secret. */
 const FOCUS_MUTATION_OPERATIONS = new Set(["tasks.focus", "tasks.pause", "tasks.unpause", "tasks.clear_focus"]);
 
+/** Matches pi-tickets' own watch-events poll cadence -- no established Papyrus-specific reason
+ * to differ, and this Vehicle doesn't call configureApprovals() on anything today, so nothing yet
+ * actually exercises this path; it exists so a future gated operation (e.g. a genuinely
+ * destructive artifact mutation) gets outcome-visibility for free rather than needing this same
+ * wiring added later. */
+const APPROVAL_OUTCOME_POLL_INTERVAL_MS = 30_000;
+
 /**
  * Vehicle Shell's core set (see @danypops/vehicle-client-pi's registerVehicleTools `shell`
  * option): the handful of operations used in nearly every session, active from turn one with no
@@ -134,6 +143,22 @@ export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehi
 			connectRetry: true,
 		},
 	);
+	// Push half of the Approval Gate's outcome-visibility story -- see
+	// @danypops/vehicle-client-pi's own vehicle-approval-outcome-poll.ts doc comment (the Papyrus
+	// Discussion parallel this mirrors) and pi-tickets' identical wiring in vehicle-client.ts.
+	const approvalOutcomePoll = new VehicleApprovalOutcomePoll(client, createAgentNotifier(pi));
+	let approvalOutcomePollTimer: ReturnType<typeof setInterval> | undefined;
+	pi.on("session_start", (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		if (approvalOutcomePollTimer) return;
+		approvalOutcomePollTimer = setInterval(() => void approvalOutcomePoll.poll(), APPROVAL_OUTCOME_POLL_INTERVAL_MS);
+		void approvalOutcomePoll.poll(); // an outcome may already be resolved before this session ever started polling
+	});
+	pi.on("session_shutdown", () => {
+		if (!approvalOutcomePollTimer) return;
+		clearInterval(approvalOutcomePollTimer);
+		approvalOutcomePollTimer = undefined;
+	});
 	return registerVehicleToolsWhenReady(pi, () => Promise.resolve(currentVehicleClientTarget() ? client : undefined), {
 		// registerVehicleMetricsOperations(..., "papyrus") in @danypops/papyrus's own daemon.ts uses
 		// the default "metrics" prefix -- without this, its metrics.query/metrics.recordClientEvent
@@ -205,19 +230,24 @@ export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehi
 		// 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),
+		onApprovalPending: (requestId, descriptor) => approvalOutcomePoll.record(requestId, descriptor.name),
 		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" });
+				const artifact = output as { id: string; extra?: Record<string, unknown> } | undefined;
+				if (artifact?.id) emitTaskFocusEvent({ taskId: artifact.id, status: "focused", effort: extractDeclaredEffort(artifact.extra) });
 				return;
 			}
 			if (descriptor.name === "tasks.pause" || descriptor.name === "tasks.unpause") {
-				const focus = output as { artifact: { id: string } } | undefined;
+				const focus = output as { artifact: { id: string; extra?: Record<string, unknown> } } | undefined;
 				if (focus?.artifact?.id)
-					emitTaskFocusEvent({ taskId: focus.artifact.id, status: descriptor.name === "tasks.pause" ? "paused" : "unpaused" });
+					emitTaskFocusEvent({
+						taskId: focus.artifact.id,
+						status: descriptor.name === "tasks.pause" ? "paused" : "unpaused",
+						effort: extractDeclaredEffort(focus.artifact.extra),
+					});
 				return;
 			}
 			if (descriptor.name === "tasks.clear_focus") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.57.10",
+  "version": "0.59.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "peerDependencies": {
-    "@danypops/vehicle-client-pi": "^0.45.1",
+    "@danypops/vehicle-client-pi": "^0.46.0",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@danypops/pi-tui-harness": "^0.0.2",
-    "@danypops/vehicle-client-pi": "^0.45.1",
+    "@danypops/vehicle-client-pi": "^0.46.0",
     "@danypops/vehicle-conformance": "^0.3.0",
     "@earendil-works/pi-coding-agent": "^0.80.10",
     "bun-types": "latest",