@danypops/papyrus 0.33.2 → 0.33.4

package/extension/src/bounded-poll.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared idempotent start/stop wrapper over setInterval, extracted once TaskOverlay and
+ * NoteOverlay both needed the identical "fallback refresh for a mutation no event announces"
+ * behavior -- a second start() is a no-op rather than a competing timer, and stop() is safe
+ * to call even if never started.
+ */
+export class BoundedPoll {
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	start(intervalMs: number, tick: () => void): void {
+		if (this.timer) return;
+		this.timer = setInterval(tick, intervalMs);
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}

package/extension/src/domain-tools.ts

@@ -164,7 +164,7 @@ export function normalizeJsonEncodedField(params: Record<string, unknown>, key:
 }
 
 /** Resolves every {nameKey -> idKey} pair present and not already satisfied by an explicit id, in place. */
-async function resolveNameFields(
+export async function resolveNameFields(
 	params: Record<string, unknown>,
 	fields: ReadonlyArray<{ nameKey: string; idKey: string; listOperation: OperationName; baseRequest: Record<string, unknown> }>,
 ): Promise<void> {
@@ -474,7 +474,7 @@ export function registerNotesTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "notes",
 		label: "Notes",
-		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, 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. Archive requires an explicit disposition. PREFER `name` (the note's exact title) over `id` for show/consume/promote/archive -- id is a backend implementation detail, resolved from name automatically.",
+		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, 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. PREFER `name` (the note's exact title) over `id` for show/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()),
@@ -485,6 +485,7 @@ export function registerNotesTool(pi: ExtensionAPI): void {
 			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()),
@@ -497,7 +498,11 @@ export function registerNotesTool(pi: ExtensionAPI): void {
 				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 }]);
+				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);

package/extension/src/index.ts

@@ -17,12 +17,16 @@ import {
 	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
 	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
 	TASK_WIDGET_POLL_INTERVAL_MS,
+	NOTE_WIDGET_POLL_INTERVAL_MS,
+	NOTE_LIST_MAX_LIMIT,
 } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
 import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
-import { registerDomainTools } from "./domain-tools.ts";
+import { registerDomainTools, resolveNameFields } from "./domain-tools.ts";
+import { BoundedPoll } from "./bounded-poll.ts";
+import { renderNoteWidgetLines } from "./note-widget.ts";
 import { ensureTypingCourtesyTracking, isLiveAskPending } from "./discuss-ask-view.ts";
 import { PLAYBOOK_BRIDGE_MAX_PLAYBOOKS, registerPlaybookBridge } from "./playbook-bridge.ts";
 import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
@@ -103,7 +107,7 @@ export class TaskOverlay {
 	private snapshot: TaskGraph = { nodes: [], rootIds: [] };
 	private projectRoot: string | undefined;
 	private sessionId: string | undefined;
-	private pollTimer: ReturnType<typeof setInterval> | undefined;
+	private readonly poll = new BoundedPoll();
 
 	setUI(ctx: ExtensionUIContext): void {
 		if (ctx !== this.uiCtx) {
@@ -179,18 +183,14 @@ export class TaskOverlay {
 
 	/**
 	 * Fallback for a Task mutation no event announces -- the CLI run directly from a shell, or
-	 * a second concurrent Pi session against the same daemon. Idempotent: a second call is a
-	 * no-op rather than starting a competing timer.
+	 * a second concurrent Pi session against the same daemon.
 	 */
 	startPolling(intervalMs: number = TASK_WIDGET_POLL_INTERVAL_MS): void {
-		if (this.pollTimer) return;
-		this.pollTimer = setInterval(() => { void this.refresh(); }, intervalMs);
+		this.poll.start(intervalMs, () => { void this.refresh(); });
 	}
 
 	stopPolling(): void {
-		if (!this.pollTimer) return;
-		clearInterval(this.pollTimer);
-		this.pollTimer = undefined;
+		this.poll.stop();
 	}
 
 	dispose(): void {
@@ -204,6 +204,98 @@ export class TaskOverlay {
 	}
 }
 
+const NOTE_WIDGET_KEY = "pi-papyrus-notes";
+
+/**
+ * Deliberately simple, unlike TaskOverlay's tree: just an open-note count for this session's own
+ * CWD -- notes.list already scopes to project_root exactly (a note's projectRoot is fixed at
+ * capture time), so passing this overlay's projectRoot is what makes the count CWD-aware by
+ * default.
+ */
+export class NoteOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private registered = false;
+	private tui: any | undefined;
+	private openCount = 0;
+	private projectRoot: string | undefined;
+	private readonly poll = new BoundedPoll();
+
+	setUI(ctx: ExtensionUIContext): void {
+		if (ctx !== this.uiCtx) {
+			this.uiCtx = ctx;
+			this.registered = false;
+			this.tui = undefined;
+		}
+	}
+
+	setProjectRoot(projectRoot: string): void { this.projectRoot = projectRoot; }
+
+	async refresh(): Promise<void> {
+		if (!this.projectRoot) return;
+		try {
+			const rows = await callService<Record<string, unknown>, Artifact[]>("notes.list", { project_root: this.projectRoot, limit: NOTE_LIST_MAX_LIMIT });
+			this.openCount = rows.length;
+		} catch {
+			this.openCount = 0;
+		}
+		try {
+			this.render();
+		} catch {
+			// A rendering bug must not crash the extension host over a best-effort status widget.
+		}
+	}
+
+	private render(): void {
+		if (!this.uiCtx) return;
+
+		if (this.openCount === 0) {
+			if (this.registered) {
+				this.uiCtx.setWidget(NOTE_WIDGET_KEY, undefined);
+				this.registered = false;
+				this.tui = undefined;
+			}
+			return;
+		}
+
+		if (!this.registered) {
+			this.uiCtx.setWidget(
+				NOTE_WIDGET_KEY,
+				(tui: any, theme: Theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => renderNoteWidgetLines(theme, this.openCount, width),
+						invalidate: () => {
+							this.registered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.registered = true;
+		} else {
+			this.tui?.requestRender?.();
+		}
+	}
+
+	startPolling(intervalMs: number = NOTE_WIDGET_POLL_INTERVAL_MS): void {
+		this.poll.start(intervalMs, () => { void this.refresh(); });
+	}
+
+	stopPolling(): void {
+		this.poll.stop();
+	}
+
+	dispose(): void {
+		this.stopPolling();
+		this.uiCtx?.setWidget(NOTE_WIDGET_KEY, undefined);
+		this.registered = false;
+		this.tui = undefined;
+		this.uiCtx = undefined;
+		this.projectRoot = undefined;
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
@@ -331,12 +423,15 @@ export default async function (pi: ExtensionAPI) {
 			"ACTIONS: link (from+relation+to), unlink (from+relation+to — idempotent, no error if already absent; for Task depends_on/contains prefer the tasks tool's undepend/uncontain), " +
 			"tree (id → bounded BFS subgraph), " +
 			"history (who did what, when — requires id, actor, or session_id). " +
-			"status (id+status) exists at the protocol level but is refused for every kind with its own lifecycle (Doc/Rule/Skill/Playbook/Task/Note all reject it) -- use that kind's own domain tool for status changes (docs.activate, rules.enable, tasks.start, etc), never this.",
+			"status (id+status) exists at the protocol level but is refused for every kind with its own lifecycle (Doc/Rule/Skill/Playbook/Task/Note all reject it) -- use that kind's own domain tool for status changes (docs.activate, rules.enable, tasks.start, etc), never this. " +
+			"PREFER `from_name`/`to_name` over `from`/`to` for link/unlink -- both are backend implementation details, resolved from name automatically, searching across every kind since either end of an edge can be any artifact.",
 		parameters: Type.Object({
 			action: Type.String({ description: "link | unlink | tree | status | history" }),
 			from: Type.Optional(Type.String()),
+			from_name: Type.Optional(Type.String()),
 			relation: Type.Optional(Type.String()),
 			to: Type.Optional(Type.String()),
+			to_name: Type.Optional(Type.String()),
 			id: Type.Optional(Type.String()),
 			status: Type.Optional(Type.String()),
 			depth: Type.Optional(Type.Number({ description: "tree traversal depth; bounded by a hard ceiling" })),
@@ -348,18 +443,26 @@ export default async function (pi: ExtensionAPI) {
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Artifact graph", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, params, _signal, _onUpdate, _ctx) {
+		async execute(_id, rawParams, _signal, _onUpdate, _ctx) {
 			try {
+				const params: Record<string, unknown> = { ...rawParams };
+				if (params.action === "link" || params.action === "unlink") {
+					// Kind-agnostic: either end of an edge can be a task, doc, rule, skill, or playbook.
+					await resolveNameFields(params, [
+						{ nameKey: "from_name", idKey: "from", listOperation: "artifact.query", baseRequest: {} },
+						{ nameKey: "to_name", idKey: "to", listOperation: "artifact.query", baseRequest: {} },
+					]);
+				}
 				if (params.action === "link") {
-					await callService("graph.link", { from: params.from!, relation: params.relation!, to: params.to! });
-					const names = await artifactNamesById([params.from!, params.to!]);
-					const output = `Linked "${names.get(params.from!) ?? "unknown artifact"}" --${params.relation}--> "${names.get(params.to!) ?? "unknown artifact"}"`;
+					await callService("graph.link", { from: params.from as string, relation: params.relation as string, to: params.to as string });
+					const names = await artifactNamesById([params.from as string, params.to as string]);
+					const output = `Linked "${names.get(params.from as string) ?? "unknown artifact"}" --${params.relation}--> "${names.get(params.to as string) ?? "unknown artifact"}"`;
 					return text(output, createPreviewDetails("graph.link", "Artifact relationship", output));
 				}
 				if (params.action === "unlink") {
-					const result = await callService<Record<string, unknown>, { removed: boolean }>("graph.unlink", { from: params.from!, relation: params.relation!, to: params.to! });
-					const names = await artifactNamesById([params.from!, params.to!]);
-					const relationship = `"${names.get(params.from!) ?? "unknown artifact"}" --${params.relation}--> "${names.get(params.to!) ?? "unknown artifact"}"`;
+					const result = await callService<Record<string, unknown>, { removed: boolean }>("graph.unlink", { from: params.from as string, relation: params.relation as string, to: params.to as string });
+					const names = await artifactNamesById([params.from as string, params.to as string]);
+					const relationship = `"${names.get(params.from as string) ?? "unknown artifact"}" --${params.relation}--> "${names.get(params.to as string) ?? "unknown artifact"}"`;
 					const output = result.removed ? `Unlinked ${relationship}` : `No such relationship: ${relationship}`;
 					return text(output, createPreviewDetails("graph.unlink", "Artifact relationship", output));
 				}
@@ -455,6 +558,7 @@ export default async function (pi: ExtensionAPI) {
 		import("./discuss.ts"),
 	]);
 	let overlay: TaskOverlay | undefined;
+	let noteOverlay: NoteOverlay | undefined;
 
 	pi.registerCommand("tasks", {
 		description: "Browse and manage Papyrus tasks (interactive)",
@@ -471,11 +575,18 @@ export default async function (pi: ExtensionAPI) {
 	});
 	pi.registerCommand("note", {
 		description: "Capture a deferred request directly in Papyrus",
-		handler: async (args, ctx) => { await notesModule.captureNote(args, ctx); },
+		handler: async (args, ctx) => {
+			await notesModule.captureNote(args, ctx);
+			await noteOverlay?.refresh();
+		},
 	});
 	pi.registerCommand("notes", {
 		description: "Browse and triage the project Notes inbox",
-		handler: async (_args, ctx) => { await notesModule.showNotes(ctx); },
+		handler: async (_args, ctx) => {
+			noteOverlay?.setProjectRoot(ctx.cwd);
+			await notesModule.showNotes(ctx);
+			await noteOverlay?.refresh();
+		},
 	});
 	pi.registerCommand("rules", {
 		description: "Browse, preview, and toggle Papyrus rules (interactive)",
@@ -569,14 +680,22 @@ export default async function (pi: ExtensionAPI) {
 		overlay.setSessionId(ctx.sessionManager.getSessionId());
 		await overlay.refresh();
 		overlay.startPolling(TASK_WIDGET_POLL_INTERVAL_MS);
+
+		noteOverlay ??= new NoteOverlay();
+		noteOverlay.setUI(ctx.ui);
+		noteOverlay.setProjectRoot(ctx.cwd);
+		await noteOverlay.refresh();
+		noteOverlay.startPolling(NOTE_WIDGET_POLL_INTERVAL_MS);
 	});
 
 	pi.on("session_before_compact", () => { taskContinuation.onCompaction(); });
-	pi.on("session_compact", async () => { await overlay?.refresh(); });
-	pi.on("session_tree", async () => { await overlay?.refresh(); });
+	pi.on("session_compact", async () => { await Promise.all([overlay?.refresh(), noteOverlay?.refresh()]); });
+	pi.on("session_tree", async () => { await Promise.all([overlay?.refresh(), noteOverlay?.refresh()]); });
 	pi.on("session_shutdown", async (_event, ctx) => {
 		overlay?.dispose();
 		overlay = undefined;
+		noteOverlay?.dispose();
+		noteOverlay = undefined;
 		try {
 			const sessionId = ctx.sessionManager.getSessionId();
 			await callService("session.release", { session_id: sessionId, ...sessionSecretField(sessionId) });
@@ -586,11 +705,14 @@ export default async function (pi: ExtensionAPI) {
 		}
 	});
 
-	// Update widget after any papyrus tool call
+	// Update widgets after any papyrus tool call
 	pi.on("tool_execution_end", async (event) => {
 		if (event.toolName.startsWith("papyrus_") || event.toolName === "tasks") {
 			await overlay?.refresh();
 		}
+		if (event.toolName === "notes") {
+			await noteOverlay?.refresh();
+		}
 	});
 
 	// ── Keep driving active work after Pi has exhausted built-in continuations ──

package/extension/src/note-widget.ts

@@ -0,0 +1,8 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+/** Hidden at 0, matching TaskOverlay's own "nothing open" hiding rule. */
+export function renderNoteWidgetLines(theme: Theme, openCount: number, width: number): string[] {
+	if (openCount === 0) return [];
+	return [truncateToWidth(`${theme.fg("muted", "Notes")} ${theme.fg("accent", String(openCount))}`, width, "…")];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.33.2",
+  "version": "0.33.4",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/constants.ts

@@ -71,6 +71,8 @@ export const TASK_DETAIL_MIN_VISIBLE_LINES = 8;
  * directly from a shell. This bounded poll is the fallback for exactly that gap.
  */
 export const TASK_WIDGET_POLL_INTERVAL_MS = 20_000;
+/** Same fallback purpose as TASK_WIDGET_POLL_INTERVAL_MS, for the Notes widget's own count. */
+export const NOTE_WIDGET_POLL_INTERVAL_MS = 20_000;
 export const TASK_DETAIL_MAX_VISIBLE_LINES = 24;
 export const TASK_DETAIL_RESERVED_ROWS = 8;
 export const TASK_DETAIL_HORIZONTAL_PAN_COLUMNS = 4;