@danypops/pi-papyrus 0.38.0 → 0.38.2

package/extension/src/domain-tools.ts

@@ -1,14 +1,12 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
-	NOTE_DISPOSITIONS,
 	PROOF_TYPES,
 	readDiscussionExtra,
 	type Artifact,
 	type DiscussionAndRounds,
 	type DiscussionRound,
 	type GateResult,
-	type NoteHistoryPage,
 	type OperationName,
 	type WorkflowRunResult,
 	type TaskCompletion,
@@ -250,7 +248,7 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, context, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, cancel_subtree, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, remove_subtree, restore, claim, heartbeat_lease, release_lease, lease, event_feed. Lifecycle: todo → in-progress → review → done; review failure → rejected → retry → in-progress; canceled is terminal. Focus and lease are independent of lifecycle and of each other -- multiple sessions can focus the same task while only one holds its lease (claim throws if a different owner already holds one; release/heartbeat need the exact token claim returned; owner defaults to this session's id). context returns the full plan (the system prompt itself only carries a one-line pointer) -- call it explicitly after a compaction or before reconciling. complete runs gates + checklist-proof review, then focuses one ready successor. cancel_subtree cancels a task and its whole containment subtree in one call, skipping tasks already done/canceled. remove/restore use a time-gated trash (refuses the live Focus); remove_subtree trashes a whole `contains` subtree in one call; undepend/uncontain are idempotent no-ops when the edge is already absent. update recovers an accidentally-terminal task via status=todo + reason, without rewriting real history. Prefer `name` (exact title) over `id` -- id is a backend detail, resolved automatically, needed only to disambiguate a shared title; `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the same pattern for their `_id` counterparts.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, context, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, cancel_subtree, run_gates, set_checklist, set_gates, depend, undepend, contain, uncontain, remove, remove_subtree, restore, claim, heartbeat_lease, release_lease, lease, event_feed. Lifecycle: todo → in-progress → review → done; review failure → rejected → retry → in-progress; canceled is terminal. Focus and lease are independent of lifecycle and of each other -- multiple sessions can focus the same task while only one holds its lease (claim throws if a different owner already holds one; release/heartbeat need the exact token claim returned; owner defaults to this session's id). context returns the full plan (the system prompt itself only carries a one-line pointer) -- call it explicitly after a compaction or before reconciling. complete runs gates + checklist-proof review, then focuses one ready successor. cancel_subtree cancels a task and its whole containment subtree in one call, skipping tasks already done/canceled. remove/restore use a time-gated trash (refuses the live Focus); remove_subtree trashes a whole `contains` subtree in one call; undepend/uncontain are idempotent no-ops when the edge is already absent. update recovers an accidentally-terminal task via status=todo + reason, without rewriting real history; update never touches gates (title/body/labels/status only) -- use set_gates to replace a task's gate commands after creation. Prefer `name` (exact title) over `id` -- id is a backend detail, resolved automatically, needed only to disambiguate a shared title; `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the same pattern for their `_id` counterparts.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -411,6 +409,10 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_checklist", params);
 					return text(`Updated checklist: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
 				}
+				if (action === "set_gates") {
+					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_gates", params);
+					return text(`Updated gates: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_gates", artifact));
+				}
 				if (action === "complete") {
 					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", request);
 					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
@@ -487,69 +489,9 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 	});
 }
 
-export function registerNotesTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "notes",
-		label: "Notes",
-		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, history, consume, promote, archive. Capture stores a request without creating work. Consume marks it considered. To promote, first create the resulting Task, Doc, Rule, or Skill through its domain tool, then link it with target_id (or target_name). Archive requires an explicit disposition. history returns this note's own real append-only event log (captured/consumed/promoted/archived), not the generic cross-kind graph.history. PREFER `name` (the note's exact title) over `id` for show/history/consume/promote/archive, and `target_name` over `target_id` for promote -- all are backend implementation details, resolved from name automatically (target_name searches across every kind, since a promotion target can be a task, doc, rule, or skill).",
-		parameters: Type.Object({
-			action: Type.String(),
-			id: Type.Optional(Type.String()),
-			name: Type.Optional(Type.String()),
-			body: Type.Optional(Type.String()),
-			title: Type.Optional(Type.String()),
-			status: Type.Optional(Type.Union([Type.Literal("draft"), Type.Literal("active"), Type.Literal("archived")])),
-			text: Type.Optional(Type.String()),
-			limit: Type.Optional(Type.Number()),
-			target_id: Type.Optional(Type.String()),
-			target_name: Type.Optional(Type.String()),
-			disposition: Type.Optional(Type.Union(NOTE_DISPOSITIONS.map((value) => Type.Literal(value)))),
-			reason: Type.Optional(Type.String()),
-			session_id: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
-		}),
-		renderCall(args, theme) { return renderPapyrusToolCall("Notes", args, theme); },
-		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
-			try {
-				const params: Record<string, unknown> = { ...rawParams };
-				const action = params.action;
-				const baseRequest = { project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "notes-tool" };
-				await resolveNameFields(params, [
-					{ nameKey: "name", idKey: "id", listOperation: "notes.list", baseRequest },
-					// Kind-agnostic: a promotion target can be a task, doc, rule, or skill, so this searches every kind rather than only notes.
-					{ nameKey: "target_name", idKey: "target_id", listOperation: "artifact.query", baseRequest },
-				]);
-				const request = { ...params, ...baseRequest };
-				if (action === "capture") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("notes.capture", request);
-					return text(`Captured note ${artifactLine(artifact)}`, createArtifactDetails("notes.capture", artifact));
-				}
-				if (action === "list") {
-					const rows = await callService<Record<string, unknown>, Artifact[]>("notes.list", request);
-					return text(rows.length ? artifactLines(rows).join("\n") : "No open notes.", createArtifactListDetails("notes.list", rows));
-				}
-				if (action === "show") {
-					const artifact = await callService<Record<string, unknown>, Artifact>("notes.show", request);
-					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("notes.show", artifact));
-				}
-				if (action === "history") {
-					const page = await callService<Record<string, unknown>, NoteHistoryPage>("notes.history", request);
-					const lines = page.events.map((event) => `${event.occurredAt} ${event.type} · ${event.actor}/${event.source}${event.relatedId ? ` · ${event.relatedId}` : ""}${event.disposition ? ` · ${event.disposition}` : ""}${event.reason ? ` · ${event.reason}` : ""}`);
-					const output = lines.join("\n") || "No recorded history for this note.";
-					return text(output, createPreviewDetails("notes.history", "Note history", output));
-				}
-				const operations = { consume: "notes.consume", promote: "notes.promote", archive: "notes.archive" } as const;
-				const operation = operations[action as keyof typeof operations];
-				if (!operation) throw new Error(`unknown notes action: ${action}`);
-				const artifact = await callService<Record<string, unknown>, Artifact>(operation, request);
-				return text(`${action}: ${artifactLine(artifact)}`, createArtifactDetails(operation, artifact));
-			} catch (error) {
-				throw new Error(`notes failed: ${error instanceof Error ? error.message : error}`);
-			}
-		},
-	});
-}
+// notes.* is registered as a real Vehicle (see ../vehicle-notes-client.ts and index.ts),
+// not a hand-rolled pi.registerTool() -- the first domain migrated off the
+// action-dispatch mega-tool pattern this file's other tools still use.
 
 export function registerDocsTool(pi: ExtensionAPI): void {
 	pi.registerTool({
@@ -939,7 +881,6 @@ export function registerDiscussTool(pi: ExtensionAPI): void {
 /** Thin orchestrator: each domain's tool is independently navigable/testable via its own registerXTool function. */
 export function registerDomainTools(pi: ExtensionAPI): void {
 	registerTasksTool(pi);
-	registerNotesTool(pi);
 	registerDocsTool(pi);
 	registerRulesTool(pi);
 	registerPlaybooksTool(pi);

package/extension/src/index.ts

@@ -28,6 +28,7 @@ import { formatMetadata } from "./artifact-format.ts";
 import { callService, subscribeTaskPushChannel } from "./service-client.ts";
 import type { PushChannelClient } from "@danypops/daemon-kit/pi-client";
 import { registerDomainTools, resolveNameFields } from "./domain-tools.ts";
+import { registerNotesVehicle } from "./vehicle-notes-client.ts";
 import { BoundedPoll } from "./bounded-poll.ts";
 import { renderNoteWidgetLines } from "./note-widget.ts";
 import { ensureTypingCourtesyTracking, isLiveAskPending } from "./discuss-ask-view.ts";
@@ -677,6 +678,18 @@ export default async function (pi: ExtensionAPI) {
 	// ── 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
@@ -731,7 +744,9 @@ export default async function (pi: ExtensionAPI) {
 		if (event.toolName.startsWith("papyrus_") || event.toolName === "tasks") {
 			await overlay?.refresh();
 		}
-		if (event.toolName === "notes") {
+		// notes.* projects to notes_capture/notes_list/notes_show/... (see
+		// registerNotesVehicle) -- not a single "notes" tool name anymore.
+		if (event.toolName.startsWith("notes_")) {
 			await noteOverlay?.refresh();
 		}
 	});

package/extension/src/service-client.ts

@@ -1,5 +1,5 @@
 import { connectPushChannel, createRetryingClient, type PushChannelClient, type PushChannelState, type RetryingClient } from "@danypops/daemon-kit/pi-client";
-import { connectPapyrusClient, resolvePushChannelTarget, type OperationName, type PapyrusClient } from "@danypops/papyrus";
+import { connectPapyrusClient, resolvePushChannelTarget, resolveVehicleClientTarget, type OperationName, type PapyrusClient, type VehicleClientTarget } from "@danypops/papyrus";
 
 type ClientConnector = () => Promise<PapyrusClient>;
 
@@ -37,6 +37,27 @@ export function resetPushChannelTargetResolverForTests(): void {
 	pushChannelTargetResolver = resolvePushChannelTarget;
 }
 
+let vehicleClientTargetResolver: typeof resolveVehicleClientTarget = resolveVehicleClientTarget;
+
+/**
+ * Defaults to the real daemonStateDir() -- every test that exercises the full extension
+ * entrypoint (registerPapyrus(api)), not just registerDomainTools, must override this
+ * first, the same way mockService already overrides setPapyrusClientConnectorForTests,
+ * or a hermetic unit test can silently start depending on whatever real Papyrus daemon
+ * handle happens to exist on the machine running it.
+ */
+export function setVehicleClientTargetResolverForTests(value: () => VehicleClientTarget | undefined): void {
+	vehicleClientTargetResolver = value;
+}
+
+export function resetVehicleClientTargetResolverForTests(): void {
+	vehicleClientTargetResolver = resolveVehicleClientTarget;
+}
+
+export function currentVehicleClientTarget(): VehicleClientTarget | undefined {
+	return vehicleClientTargetResolver();
+}
+
 /**
  * Subscribes to the daemon's "tasks" push topic so a widget can refresh the moment
  * a mutation happens, instead of waiting for its next poll tick. Returns undefined

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

@@ -0,0 +1,43 @@
+/**
+ * Registers notes.* as a real Vehicle instead of a hand-rolled `pi.registerTool()`
+ * mega-tool -- see @danypops/papyrus's src/vehicle/notes-vehicle.ts for the
+ * VehicleRegistry side. Same daemon, same handle file, same Bearer token every
+ * other Papyrus RPC call already uses (resolveVehicleClientTarget mirrors
+ * resolvePushChannelTarget's own resolution).
+ *
+ * Papyrus's daemon is expected to already be running as an installed service
+ * (see `packed install-service`), not auto-spawned on first use -- so unlike
+ * registerVehicleTools' README example, failure here (daemon not started yet,
+ * stale handle) is tolerated the same silent-degrade way
+ * subscribeTaskPushChannel already tolerates it, rather than letting a
+ * daemon-not-running condition abort the rest of extension setup. There is
+ * no retry-on-later-connect for a tool that was never registered at all --
+ * Pi has no way to add one after the fact outside the initial registration
+ * flow.
+ *
+ * Resolves the target through service-client.ts's currentVehicleClientTarget()
+ * (test-injectable, see setVehicleClientTargetResolverForTests), never
+ * @danypops/papyrus's resolveVehicleClientTarget() directly -- this runs from
+ * the bare extension entrypoint on every registerPapyrus(api) call, so an
+ * un-injected default would resolve the real daemonStateDir() in any test
+ * exercising the full entrypoint, not just ones about notes.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
+import { registerVehicleTools } from "@danypops/vehicle-client-pi";
+import { currentVehicleClientTarget } from "./service-client.ts";
+
+export async function registerNotesVehicle(pi: ExtensionAPI): Promise<void> {
+	const target = currentVehicleClientTarget();
+	if (!target) return;
+	try {
+		const client = new RemoteVehicleClient({ baseUrl: target.baseUrl, token: target.token });
+		await registerVehicleTools(pi, client, {
+			permissions: ["notes:read", "notes:write"],
+			principal: { id: "pi-papyrus" },
+		});
+	} catch {
+		// Daemon state is stale/unreachable -- degrade silently, matching
+		// subscribeTaskPushChannel's own tolerance for the same condition.
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "type": "module",
   "keywords": ["pi-package"],
@@ -19,6 +19,9 @@
   "dependencies": {
     "@danypops/daemon-kit": "^0.10.0",
     "@danypops/papyrus": "^0.38.0",
+    "@danypops/vehicle-core": "^0.1.0",
+    "@danypops/vehicle-client": "^0.1.1",
+    "@danypops/vehicle-client-pi": "^0.1.5",
     "beautiful-mermaid": "1.1.3"
   },
   "devDependencies": {