@danypops/pi-papyrus 0.57.10 → 0.58.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

@@ -35,7 +35,7 @@ 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";
 
@@ -210,14 +210,18 @@ export function registerNotesVehicle(pi: ExtensionAPI): Promise<RegisteredPiVehi
 			// 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.58.0",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "license": "MIT",
   "type": "module",