repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

remove docs dir

d31087b18ca3bfd6be7671427109daa7a4c7026b

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/plans/2026-06-12-notes-extension-implementation.md

Deleted
deleted file mode 100644
1 -# Notes Extension Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Build `extensions/notes`, a TUI-only Pi slash-command extension for session-backed pending prompt notes.
7 -**Architecture:** Keep the extension standalone in one focused `index.ts` with pure state/replay/render helpers and a thin Pi registration layer.
8 -Session persistence uses append-only `notes-state` custom entries, replayed from `ctx.sessionManager.getBranch()` on `session_start`.
9 -UI state is process memory only: compact vs expanded resets to compact on session start.
11 -**Tech Stack:** TypeScript, Pi extension API, `@earendil-works/pi-tui` key IDs, `@marcfargas/pi-test-harness`, Vitest, npm workspaces, mise tasks.
13 -**Roadmap:** None
15 -**Phase:** Single-plan implementation
17 ----
19 -## File Structure
21 -- Create `extensions/notes/package.json`.
22 - Declares the standalone workspace package, Pi peer dependency, TUI peer dependency, harness dev dependency, and Vitest dev dependency.
23 -- Create `extensions/notes/index.ts`.
24 - Owns note state, session replay, command parsing, widget rendering, autocomplete, shortcut registration, and lifecycle hooks.
25 -- Create `extensions/notes/__tests__/harness.test.ts`.
26 - Loads the extension through the real Pi extension runtime and verifies command, persistence, widget, autocomplete, and send behavior.
27 -- Create `extensions/notes/README.md`.
28 - Documents commands, shortcut, persistence, and non-goals tersely.
29 -- Modify `README.md`.
30 - Adds `notes` to the root extension table.
31 -- Modify `package-lock.json`.
32 - Generated by `npm install` after adding the workspace package.
34 -## Existing Patterns To Follow
36 -- Use `extensions/model-info/package.json` for package metadata shape.
37 -- Use `extensions/neko/index.ts` for `registerCommand()` plus `registerShortcut()` shape.
38 -- Use `extensions/goal/__tests__/harness.test.ts` for harness helpers around commands and UI calls.
39 -- Use `extensions/diff-review/__tests__/harness.test.ts` for manual `session_start` emission after appending custom session entries.
40 -- Use `mise run test -- extensions/notes/__tests__/harness.test.ts` for targeted tests.
41 -- Use `mise run lint` and `mise run test` before completion.
43 -## Task 1: Package Skeleton And Runtime Registration
45 -**Files:**
47 -- Create: `extensions/notes/package.json`
48 -- Create: `extensions/notes/index.ts`
49 -- Create: `extensions/notes/__tests__/harness.test.ts`
50 -- Create: `extensions/notes/README.md`
51 -- Modify: `README.md`
52 -- Modify: `package-lock.json`
54 -- [ ] **Step 1: Write the failing harness load test**
56 -Create `extensions/notes/__tests__/harness.test.ts` with this content:
58 -```ts
59 -import { fileURLToPath } from "node:url";
60 -import { afterEach, describe, expect, it } from "vitest";
61 -import { createTestSession, type TestSession } from "../../../test/harness";
63 -let t: TestSession | undefined;
65 -function extensionPath(): string {
66 - return fileURLToPath(new URL("../index.ts", import.meta.url));
69 -afterEach(() => {
70 - t?.dispose();
71 - t = undefined;
72 -});
74 -describe("notes pi-test-harness", () => {
75 - it("loads in real Pi extension runtime and registers command plus shortcut", async () => {
76 - t = await createTestSession({ extensions: [extensionPath()] });
77 - const [extension] = t.session.extensionRunner.extensions;
79 - expect(extension.path).toBe(extensionPath());
80 - expect([...extension.commands.keys()]).toEqual(["note"]);
81 - expect([...extension.tools.keys()]).toEqual([]);
82 - expect(extension.shortcuts.has("alt+n")).toBe(true);
83 - });
84 -});
85 -```
87 -- [ ] **Step 2: Run test to verify it fails**
89 -Run:
91 -```bash
92 -mise run test -- extensions/notes/__tests__/harness.test.ts
93 -```
95 -Expected: FAIL because `extensions/notes/index.ts` does not exist.
97 -- [ ] **Step 3: Add package skeleton**
99 -Create `extensions/notes/package.json` with this content:
101 -```json
103 - "name": "@bugabinga/pi-ext-notes",
104 - "type": "module",
105 - "main": "index.ts",
106 - "scripts": {},
107 - "peerDependencies": {
108 - "@earendil-works/pi-coding-agent": "*",
109 - "@earendil-works/pi-tui": "*"
110 - },
111 - "license": "MIT",
112 - "description": "Session-backed pending prompt notes for Pi.",
113 - "keywords": [
114 - "pi",
115 - "pi-extension"
116 - ],
117 - "devDependencies": {
118 - "@marcfargas/pi-test-harness": "^0.6.1",
119 - "vitest": "^4.1.8"
120 - },
121 - "private": true
123 -```
125 -Create `extensions/notes/index.ts` with this content:
127 -```ts
128 -import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
130 -export default function notesExtension(pi: ExtensionAPI): void {
131 - pi.registerCommand("note", {
132 - description: "Park, inspect, edit, send, or clear pending prompt notes.",
133 - async handler(_args, ctx) {
134 - if (ctx.hasUI) ctx.ui.notify("No pending notes", "info");
135 - },
136 - });
138 - pi.registerShortcut("alt+n", {
139 - description: "Toggle notes widget",
140 - handler: async (ctx) => {
141 - if (ctx.hasUI) ctx.ui.notify("No pending notes", "info");
142 - },
143 - });
145 -```
147 -Create `extensions/notes/README.md` with this content:
149 -```md
150 -# notes
152 -Session-backed pending prompt notes for Pi.
154 -## Install / load
156 -Loaded through the root pi-ext package.
157 -See [root README](../../README.md).
159 -## Commands / tools / settings
161 -Commands:
163 -- `/note` — toggle the notes widget between compact and expanded mode.
164 -- `/note add <text>` — park a non-empty note.
165 -- `/note send <id>` — send one note as an exact user follow-up and remove it from pending notes.
166 -- `/note edit <id>` — edit one pending note.
167 -- `/note rm <id>` — remove one pending note.
168 -- `/note clear` — confirm and remove all pending notes.
170 -Shortcut:
172 -- `alt+n` — same as `/note`.
174 -Tools:
175 -none.
177 -Settings:
178 -none.
180 -## Behavior
182 -Pending notes are persisted as `notes-state` custom session entries.
183 -Custom entries are invisible to the model context.
184 -Notes are branch-local because state is reconstructed from the current session branch.
185 -The widget is compact on reload or resume.
186 -```
188 -- [ ] **Step 4: Add root README table row**
190 -Insert this row in `README.md` between `neko` and `nu-bang`:
192 -```md
193 -| `notes` | Session-backed pending prompt notes for Pi. | [README](extensions/notes/README.md) |
194 -```
196 -- [ ] **Step 5: Update workspace lockfile**
198 -Run:
200 -```bash
201 -npm install
202 -```
204 -Expected: `package-lock.json` includes `extensions/notes` and package metadata for `@bugabinga/pi-ext-notes`.
206 -- [ ] **Step 6: Run test to verify it passes**
208 -Run:
210 -```bash
211 -mise run test -- extensions/notes/__tests__/harness.test.ts
212 -```
214 -Expected: PASS for the load test.
216 -- [ ] **Step 7: Commit**
218 -Run:
220 -```bash
221 -git add README.md package-lock.json extensions/notes/package.json extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
222 -git commit -m "feat(notes): add extension package skeleton"
223 -```
225 -## Task 2: State Replay Core
227 -**Files:**
229 -- Modify: `extensions/notes/index.ts`
230 -- Modify: `extensions/notes/__tests__/harness.test.ts`
232 -- [ ] **Step 1: Add failing replay tests**
234 -Append these helpers below `extensionPath()` in `extensions/notes/__tests__/harness.test.ts`:
236 -```ts
237 -function customEntries(kind: string): Array<Record<string, unknown>> {
238 - return (
239 - t?.session.sessionManager.getEntries() as Array<{
240 - type: string;
241 - customType?: string;
242 - data?: Record<string, unknown>;
243 - }>
245 - .filter((entry) => entry.type === "custom" && entry.customType === kind)
246 - .map((entry) => entry.data ?? {});
248 -```
250 -Extend the import from `../index.ts` by changing no import yet.
251 -Add this import under the harness import:
253 -```ts
254 -import { __test } from "../index.ts";
255 -```
257 -Append these tests inside the `describe()` block:
259 -```ts
260 -it("replays add, edit, remove, and clear events in order", () => {
261 - const state = __test.replayNotes([
263 - type: "custom",
264 - customType: "notes-state",
265 - data: { op: "add", id: 1, text: "one", createdAt: 1 },
266 - },
268 - type: "custom",
269 - customType: "notes-state",
270 - data: { op: "add", id: 2, text: "two", createdAt: 2 },
271 - },
273 - type: "custom",
274 - customType: "notes-state",
275 - data: { op: "edit", id: 2, text: "two edited", updatedAt: 3 },
276 - },
278 - type: "custom",
279 - customType: "notes-state",
280 - data: { op: "remove", id: 1, removedAt: 4 },
281 - },
283 - type: "custom",
284 - customType: "notes-state",
285 - data: { op: "clear", clearedAt: 5 },
286 - },
288 - type: "custom",
289 - customType: "notes-state",
290 - data: { op: "add", id: 3, text: "three", createdAt: 6 },
291 - },
292 - ]);
294 - expect(__test.pendingNotes(state)).toEqual([{ id: 3, text: "three" }]);
295 - expect(state.nextId).toBe(4);
296 -});
298 -it("ignores malformed entries and invalid edits or removes", () => {
299 - const state = __test.replayNotes([
301 - type: "custom",
302 - customType: "notes-state",
303 - data: { op: "edit", id: 9, text: "missing", updatedAt: 1 },
304 - },
306 - type: "custom",
307 - customType: "notes-state",
308 - data: { op: "remove", id: 9, removedAt: 2 },
309 - },
311 - type: "custom",
312 - customType: "other",
313 - data: { op: "add", id: 1, text: "wrong", createdAt: 3 },
314 - },
316 - type: "custom",
317 - customType: "notes-state",
318 - data: { op: "add", id: 2, text: "ok", createdAt: 4 },
319 - },
321 - type: "custom",
322 - customType: "notes-state",
323 - data: { op: "add", id: "bad", text: "bad", createdAt: 5 },
324 - },
325 - ]);
327 - expect(__test.pendingNotes(state)).toEqual([{ id: 2, text: "ok" }]);
328 - expect(state.nextId).toBe(3);
329 -});
331 -it("appends notes-state entries through commands", async () => {
332 - t = await createTestSession({ extensions: [extensionPath()] });
333 - const command = t.session.extensionRunner.extensions[0].commands.get("note");
334 - await command.handler(
335 - "add remember parser tests",
336 - t.session.extensionRunner.createCommandContext(),
337 - );
339 - expect(customEntries("notes-state")).toEqual([
341 - op: "add",
342 - id: 1,
343 - text: "remember parser tests",
344 - createdAt: expect.any(Number),
345 - },
346 - ]);
347 -});
348 -```
350 -- [ ] **Step 2: Run test to verify it fails**
352 -Run:
354 -```bash
355 -mise run test -- extensions/notes/__tests__/harness.test.ts
356 -```
358 -Expected: FAIL because `__test`, replay helpers, and `/note add` are missing.
360 -- [ ] **Step 3: Replace `index.ts` with state core plus add command**
362 -Replace `extensions/notes/index.ts` with this content:
364 -```ts
365 -import type {
366 - ExtensionAPI,
367 - ExtensionContext,
368 -} from "@earendil-works/pi-coding-agent";
370 -const ENTRY_TYPE = "notes-state";
371 -const WIDGET_KEY = "notes";
373 -type Note = { id: number; text: string };
374 -type NotesEvent =
375 - | { op: "add"; id: number; text: string; createdAt: number }
376 - | { op: "edit"; id: number; text: string; updatedAt: number }
377 - | { op: "remove"; id: number; removedAt: number }
378 - | { op: "clear"; clearedAt: number };
380 -type SessionEntryLike = {
381 - type?: unknown;
382 - customType?: unknown;
383 - data?: unknown;
386 -type NotesState = {
387 - notes: Map<number, Note>;
388 - nextId: number;
391 -function createState(): NotesState {
392 - return { notes: new Map(), nextId: 1 };
395 -function isPositiveInteger(value: unknown): value is number {
396 - return Number.isInteger(value) && typeof value === "number" && value > 0;
399 -function isNonEmptyText(value: unknown): value is string {
400 - return typeof value === "string" && value.trim().length > 0;
403 -function parseEvent(data: unknown): NotesEvent | undefined {
404 - if (!data || typeof data !== "object") return undefined;
405 - const event = data as Record<string, unknown>;
406 - if (
407 - event.op === "add" && isPositiveInteger(event.id)
408 - && isNonEmptyText(event.text) && typeof event.createdAt === "number"
409 - ) {
410 - return {
411 - op: "add",
412 - id: event.id,
413 - text: event.text.trim(),
414 - createdAt: event.createdAt,
415 - };
417 - if (
418 - event.op === "edit" && isPositiveInteger(event.id)
419 - && isNonEmptyText(event.text) && typeof event.updatedAt === "number"
420 - ) {
421 - return {
422 - op: "edit",
423 - id: event.id,
424 - text: event.text.trim(),
425 - updatedAt: event.updatedAt,
426 - };
428 - if (
429 - event.op === "remove" && isPositiveInteger(event.id)
430 - && typeof event.removedAt === "number"
431 - ) {
432 - return { op: "remove", id: event.id, removedAt: event.removedAt };
434 - if (event.op === "clear" && typeof event.clearedAt === "number") {
435 - return { op: "clear", clearedAt: event.clearedAt };
437 - return undefined;
440 -function applyEvent(state: NotesState, event: NotesEvent): void {
441 - if (event.op === "add") {
442 - state.notes.set(event.id, { id: event.id, text: event.text });
443 - state.nextId = Math.max(state.nextId, event.id + 1);
444 - return;
446 - if (event.op === "edit") {
447 - const note = state.notes.get(event.id);
448 - if (!note) return;
449 - state.notes.set(event.id, { id: event.id, text: event.text });
450 - state.nextId = Math.max(state.nextId, event.id + 1);
451 - return;
453 - if (event.op === "remove") {
454 - if (!state.notes.has(event.id)) return;
455 - state.notes.delete(event.id);
456 - state.nextId = Math.max(state.nextId, event.id + 1);
457 - return;
459 - state.notes.clear();
462 -function replayNotes(entries: SessionEntryLike[]): NotesState {
463 - const state = createState();
464 - for (const entry of entries) {
465 - if (entry.type !== "custom" || entry.customType !== ENTRY_TYPE) continue;
466 - const event = parseEvent(entry.data);
467 - if (event) applyEvent(state, event);
469 - return state;
472 -function pendingNotes(state: NotesState): Note[] {
473 - return [...state.notes.values()].sort((a, b) => a.id - b.id);
476 -function replaceState(target: NotesState, source: NotesState): void {
477 - target.notes = source.notes;
478 - target.nextId = source.nextId;
481 -function appendEvent(
482 - pi: ExtensionAPI,
483 - state: NotesState,
484 - event: NotesEvent,
485 -): void {
486 - pi.appendEntry(ENTRY_TYPE, event);
487 - applyEvent(state, event);
490 -function notify(
491 - ctx: ExtensionContext,
492 - message: string,
493 - type: "info" | "warning" | "error" = "info",
494 -): void {
495 - if (ctx.hasUI) ctx.ui.notify(message, type);
498 -export default function notesExtension(pi: ExtensionAPI): void {
499 - const state = createState();
500 - let expanded = false;
502 - function refreshWidget(ctx: ExtensionContext): void {
503 - if (!ctx.hasUI) return;
504 - if (state.notes.size === 0) {
505 - ctx.ui.setWidget(WIDGET_KEY, undefined);
506 - return;
508 - ctx.ui.setWidget(WIDGET_KEY, [
509 - expanded
510 - ? `󰎚 notes · ${state.notes.size}`
511 - : `󰎚 ${state.notes.size} notes`,
512 - ]);
515 - pi.registerCommand("note", {
516 - description: "Park, inspect, edit, send, or clear pending prompt notes.",
517 - async handler(args, ctx) {
518 - const trimmed = args.trim();
519 - if (trimmed.startsWith("add ")) {
520 - const text = trimmed.slice(4).trim();
521 - if (!text) {
522 - notify(ctx, "Note text required", "warning");
523 - return;
525 - const wasEmpty = state.notes.size === 0;
526 - appendEvent(pi, state, {
527 - op: "add",
528 - id: state.nextId,
529 - text,
530 - createdAt: Date.now(),
531 - });
532 - if (wasEmpty) expanded = false;
533 - refreshWidget(ctx);
534 - return;
536 - notify(
537 - ctx,
538 - state.notes.size === 0
539 - ? "No pending notes"
540 - : "Usage: /note [add|send|edit|rm|clear]",
541 - "info",
542 - );
543 - refreshWidget(ctx);
544 - },
545 - });
547 - pi.registerShortcut("alt+n", {
548 - description: "Toggle notes widget",
549 - handler: async (ctx) => {
550 - notify(ctx, "No pending notes", "info");
551 - },
552 - });
554 - pi.on("session_start", async (_event, ctx) => {
555 - replaceState(
556 - state,
557 - replayNotes(ctx.sessionManager.getBranch() as SessionEntryLike[]),
558 - );
559 - expanded = false;
560 - refreshWidget(ctx);
561 - });
564 -export const __test = {
565 - ENTRY_TYPE,
566 - parseEvent,
567 - pendingNotes,
568 - replayNotes,
570 -```
572 -- [ ] **Step 4: Run test to verify it passes**
574 -Run:
576 -```bash
577 -mise run test -- extensions/notes/__tests__/harness.test.ts
578 -```
580 -Expected: PASS.
582 -- [ ] **Step 5: Commit**
584 -Run:
586 -```bash
587 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
588 -git commit -m "feat(notes): add session replay state"
589 -```
591 -## Task 3: Widget Rendering, Toggle, And Session Start Restore
593 -**Files:**
595 -- Modify: `extensions/notes/index.ts`
596 -- Modify: `extensions/notes/__tests__/harness.test.ts`
598 -- [ ] **Step 1: Add failing widget and toggle tests**
600 -Append these helpers below `customEntries()`:
602 -```ts
603 -function uiArgs(method: string): unknown[][] {
604 - return t?.events.ui.filter((call) => call.method === method).map((call) =>
605 - call.args
606 - ) ?? [];
609 -function latestWidget(): string[] | undefined {
610 - return uiArgs("setWidget")
611 - .filter((args) => args[0] === "notes")
612 - .map((args) => args[1] as string[] | undefined)
613 - .at(-1);
616 -async function noteCommand(args: string): Promise<void> {
617 - const command = t?.session.extensionRunner.extensions[0].commands.get("note");
618 - if (!command || !t) throw new Error("missing note command");
619 - await command.handler(args, t.session.extensionRunner.createCommandContext());
621 -```
623 -Append these tests inside the `describe()` block:
625 -```ts
626 -it("renders compact count and last note after add", async () => {
627 - t = await createTestSession({ extensions: [extensionPath()] });
628 - await noteCommand("add first note");
629 - await noteCommand("add second note");
631 - expect(latestWidget()).toEqual([
632 - "󰎚 2 notes · alt+n expand · last: second note",
633 - ]);
634 -});
636 -it("toggles expanded widget with slash command and shortcut", async () => {
637 - t = await createTestSession({ extensions: [extensionPath()] });
638 - await noteCommand("add first note");
639 - await noteCommand("add second note");
640 - await noteCommand("");
642 - expect(latestWidget()).toEqual([
643 - "󰎚 notes · 2",
644 - " 1 first note",
645 - " 2 second note",
646 - ]);
648 - const shortcut = t.session.extensionRunner.extensions[0].shortcuts.get(
649 - "alt+n",
650 - );
651 - await shortcut.handler(t.session.extensionRunner.createCommandContext());
653 - expect(latestWidget()).toEqual([
654 - "󰎚 2 notes · alt+n expand · last: second note",
655 - ]);
656 -});
658 -it("shows compact widget on session_start when current branch has pending notes", async () => {
659 - t = await createTestSession({ extensions: [extensionPath()] });
660 - (t.session.sessionManager as any).appendCustomEntry("notes-state", {
661 - op: "add",
662 - id: 7,
663 - text: "restored note",
664 - createdAt: 1,
665 - });
667 - await t.session.extensionRunner.emit({
668 - type: "session_start",
669 - reason: "resume",
670 - });
672 - expect(latestWidget()).toEqual([
673 - "󰎚 1 notes · alt+n expand · last: restored note",
674 - ]);
675 -});
677 -it("leaves widget hidden and notifies when toggling with no notes", async () => {
678 - t = await createTestSession({ extensions: [extensionPath()] });
679 - await noteCommand("");
681 - expect(uiArgs("notify").at(-1)).toEqual(["No pending notes", "info"]);
682 - expect(latestWidget()).toBeUndefined();
683 -});
684 -```
686 -- [ ] **Step 2: Run test to verify it fails**
688 -Run:
690 -```bash
691 -mise run test -- extensions/notes/__tests__/harness.test.ts
692 -```
694 -Expected: FAIL because widget lines are not fully rendered and toggle does not change expanded state.
696 -- [ ] **Step 3: Add render helpers and real toggle behavior**
698 -In `extensions/notes/index.ts`, add these helpers above `export default`:
700 -```ts
701 -function preview(text: string, max = 72): string {
702 - const oneLine = text.replace(/[\x00-\x1F\x7F]+/g, " ").replace(/ +/g, " ")
703 - .trim();
704 - return oneLine.length > max
705 - ? `${oneLine.slice(0, Math.max(0, max - 1))}…`
706 - : oneLine;
709 -function compactWidgetLine(state: NotesState): string {
710 - const notes = pendingNotes(state);
711 - const last = notes.at(-1);
712 - return `󰎚 ${notes.length} notes · alt+n expand · last: ${
713 - preview(last?.text ?? "")
714 - }`;
717 -function expandedWidgetLines(state: NotesState): string[] {
718 - const notes = pendingNotes(state);
719 - return [
720 - `󰎚 notes · ${notes.length}`,
721 - ...notes.map((note) => ` ${note.id} ${note.text}`),
722 - ];
725 -function widgetLines(
726 - state: NotesState,
727 - expanded: boolean,
728 -): string[] | undefined {
729 - if (state.notes.size === 0) return undefined;
730 - return expanded ? expandedWidgetLines(state) : [compactWidgetLine(state)];
732 -```
734 -Replace `refreshWidget()` and add `toggleWidget()` inside `notesExtension()`:
736 -```ts
737 -function refreshWidget(ctx: ExtensionContext): void {
738 - if (!ctx.hasUI) return;
739 - ctx.ui.setWidget(WIDGET_KEY, widgetLines(state, expanded));
742 -function toggleWidget(ctx: ExtensionContext): void {
743 - if (state.notes.size === 0) {
744 - notify(ctx, "No pending notes", "info");
745 - refreshWidget(ctx);
746 - return;
748 - expanded = !expanded;
749 - refreshWidget(ctx);
751 -```
753 -Replace the default command fallback in the command handler with:
755 -```ts
756 -if (!trimmed) {
757 - toggleWidget(ctx);
758 - return;
760 -notify(ctx, "Usage: /note [add|send|edit|rm|clear]", "warning");
761 -refreshWidget(ctx);
762 -```
764 -Replace the shortcut handler body with:
766 -```ts
767 -handler: async (ctx) => toggleWidget(ctx),
768 -```
770 -- [ ] **Step 4: Export render helpers for tests**
772 -Extend `__test` at the bottom of `index.ts` to this exact object:
774 -```ts
775 -export const __test = {
776 - ENTRY_TYPE,
777 - compactWidgetLine,
778 - expandedWidgetLines,
779 - parseEvent,
780 - pendingNotes,
781 - preview,
782 - replayNotes,
783 - widgetLines,
785 -```
787 -- [ ] **Step 5: Run test to verify it passes**
789 -Run:
791 -```bash
792 -mise run test -- extensions/notes/__tests__/harness.test.ts
793 -```
795 -Expected: PASS.
797 -- [ ] **Step 6: Commit**
799 -Run:
801 -```bash
802 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
803 -git commit -m "feat(notes): render and toggle notes widget"
804 -```
806 -## Task 4: Remove, Clear, And Edit Commands
808 -**Files:**
810 -- Modify: `extensions/notes/index.ts`
811 -- Modify: `extensions/notes/__tests__/harness.test.ts`
813 -- [ ] **Step 1: Add failing command mutation tests**
815 -Append these tests inside the `describe()` block:
817 -```ts
818 -it("removes one note and clears widget when none remain", async () => {
819 - t = await createTestSession({ extensions: [extensionPath()] });
820 - await noteCommand("add first note");
821 - await noteCommand("rm 1");
823 - expect(customEntries("notes-state").at(-1)).toEqual({
824 - op: "remove",
825 - id: 1,
826 - removedAt: expect.any(Number),
827 - });
828 - expect(latestWidget()).toBeUndefined();
829 -});
831 -it("confirms before clearing all pending notes", async () => {
832 - t = await createTestSession({
833 - extensions: [extensionPath()],
834 - mockUI: { confirm: true },
835 - });
836 - await noteCommand("add first note");
837 - await noteCommand("add second note");
838 - await noteCommand("clear");
840 - expect(uiArgs("confirm").at(-1)).toEqual([
841 - "Clear notes?",
842 - "Remove 2 pending notes?",
843 - ]);
844 - expect(customEntries("notes-state").at(-1)).toEqual({
845 - op: "clear",
846 - clearedAt: expect.any(Number),
847 - });
848 - expect(latestWidget()).toBeUndefined();
849 -});
851 -it("keeps notes when clear confirmation is rejected", async () => {
852 - t = await createTestSession({
853 - extensions: [extensionPath()],
854 - mockUI: { confirm: false },
855 - });
856 - await noteCommand("add first note");
857 - await noteCommand("clear");
859 - expect(customEntries("notes-state")).toHaveLength(1);
860 - expect(latestWidget()).toEqual([
861 - "󰎚 1 notes · alt+n expand · last: first note",
862 - ]);
863 -});
865 -it("edits note text and keeps old text on cancel or whitespace save", async () => {
866 - t = await createTestSession({
867 - extensions: [extensionPath()],
868 - mockUI: { editor: "edited note" },
869 - });
870 - await noteCommand("add old note");
871 - await noteCommand("edit 1");
873 - expect(uiArgs("editor").at(-1)).toEqual(["Edit note 1", "old note"]);
874 - expect(customEntries("notes-state").at(-1)).toEqual({
875 - op: "edit",
876 - id: 1,
877 - text: "edited note",
878 - updatedAt: expect.any(Number),
879 - });
880 - expect(latestWidget()).toEqual([
881 - "󰎚 1 notes · alt+n expand · last: edited note",
882 - ]);
884 - t.dispose();
885 - t = await createTestSession({
886 - extensions: [extensionPath()],
887 - mockUI: { editor: () => undefined },
888 - });
889 - await noteCommand("add stable note");
890 - await noteCommand("edit 1");
891 - expect(customEntries("notes-state")).toHaveLength(1);
893 - t.dispose();
894 - t = await createTestSession({
895 - extensions: [extensionPath()],
896 - mockUI: { editor: " " },
897 - });
898 - await noteCommand("add stable note");
899 - await noteCommand("edit 1");
900 - expect(customEntries("notes-state")).toHaveLength(1);
901 - expect(uiArgs("notify").at(-1)).toEqual(["Note text required", "warning"]);
902 -});
904 -it("unknown ids do not mutate state", async () => {
905 - t = await createTestSession({ extensions: [extensionPath()] });
906 - await noteCommand("add first note");
907 - await noteCommand("rm 99");
908 - await noteCommand("edit 99");
910 - expect(customEntries("notes-state")).toHaveLength(1);
911 - expect(uiArgs("notify").at(-1)).toEqual(["Unknown note id: 99", "error"]);
912 -});
913 -```
915 -- [ ] **Step 2: Run test to verify it fails**
917 -Run:
919 -```bash
920 -mise run test -- extensions/notes/__tests__/harness.test.ts
921 -```
923 -Expected: FAIL because `rm`, `clear`, and `edit` are not implemented.
925 -- [ ] **Step 3: Add command parsing helpers**
927 -Add these helpers above `export default` in `extensions/notes/index.ts`:
929 -```ts
930 -function splitCommand(args: string): { command: string; rest: string } {
931 - const trimmed = args.trim();
932 - const space = trimmed.indexOf(" ");
933 - if (space === -1) return { command: trimmed, rest: "" };
934 - return {
935 - command: trimmed.slice(0, space),
936 - rest: trimmed.slice(space + 1).trim(),
937 - };
940 -function parseId(text: string): number | undefined {
941 - const value = Number(text.trim());
942 - return isPositiveInteger(value) ? value : undefined;
945 -function requireNote(
946 - ctx: ExtensionContext,
947 - state: NotesState,
948 - idText: string,
949 -): Note | undefined {
950 - const id = parseId(idText);
951 - if (!id || !state.notes.has(id)) {
952 - notify(ctx, `Unknown note id: ${idText.trim() || "?"}`, "error");
953 - return undefined;
955 - return state.notes.get(id);
957 -```
959 -- [ ] **Step 4: Replace command handler branch body**
961 -Inside the `handler(args, ctx)` function, replace the current body with this code:
963 -```ts
964 -const trimmed = args.trim();
965 -const { command, rest } = splitCommand(trimmed);
967 -if (!trimmed) {
968 - toggleWidget(ctx);
969 - return;
972 -if (command === "add") {
973 - const text = rest.trim();
974 - if (!text) {
975 - notify(ctx, "Note text required", "warning");
976 - return;
978 - const wasEmpty = state.notes.size === 0;
979 - appendEvent(pi, state, {
980 - op: "add",
981 - id: state.nextId,
982 - text,
983 - createdAt: Date.now(),
984 - });
985 - if (wasEmpty) expanded = false;
986 - refreshWidget(ctx);
987 - return;
990 -if (command === "rm") {
991 - const note = requireNote(ctx, state, rest);
992 - if (!note) return;
993 - appendEvent(pi, state, { op: "remove", id: note.id, removedAt: Date.now() });
994 - refreshWidget(ctx);
995 - return;
998 -if (command === "clear") {
999 - if (state.notes.size === 0) {
1000 - notify(ctx, "No pending notes", "info");
1001 - refreshWidget(ctx);
1002 - return;
1004 - const confirmed = await ctx.ui.confirm(
1005 - "Clear notes?",
1006 - `Remove ${state.notes.size} pending notes?`,
1007 - );
1008 - if (!confirmed) return;
1009 - appendEvent(pi, state, { op: "clear", clearedAt: Date.now() });
1010 - refreshWidget(ctx);
1011 - return;
1014 -if (command === "edit") {
1015 - const note = requireNote(ctx, state, rest);
1016 - if (!note) return;
1017 - const edited = await ctx.ui.editor(`Edit note ${note.id}`, note.text);
1018 - if (edited === undefined) return;
1019 - const text = edited.trim();
1020 - if (!text) {
1021 - notify(ctx, "Note text required", "warning");
1022 - return;
1024 - appendEvent(pi, state, {
1025 - op: "edit",
1026 - id: note.id,
1027 - text,
1028 - updatedAt: Date.now(),
1029 - });
1030 - refreshWidget(ctx);
1031 - return;
1034 -notify(ctx, "Usage: /note [add|send|edit|rm|clear]", "warning");
1035 -refreshWidget(ctx);
1036 -```
1038 -- [ ] **Step 5: Run test to verify it passes**
1040 -Run:
1042 -```bash
1043 -mise run test -- extensions/notes/__tests__/harness.test.ts
1044 -```
1046 -Expected: PASS.
1048 -- [ ] **Step 6: Commit**
1050 -Run:
1052 -```bash
1053 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
1054 -git commit -m "feat(notes): add edit remove and clear commands"
1055 -```
1057 -## Task 5: Send Command And Autocomplete
1059 -**Files:**
1061 -- Modify: `extensions/notes/index.ts`
1062 -- Modify: `extensions/notes/__tests__/harness.test.ts`
1064 -- [ ] **Step 1: Add failing send and autocomplete tests**
1066 -Append these tests inside the `describe()` block:
1068 -```ts
1069 -it("sends exact note text when idle and removes it", async () => {
1070 - t = await createTestSession({ extensions: [extensionPath()] });
1071 - const sent: Array<{ content: unknown; options: unknown }> = [];
1072 - t.session.extensionRunner.runtime.sendUserMessage = (
1073 - content: unknown,
1074 - options: unknown,
1075 - ) => sent.push({ content, options });
1077 - await noteCommand("add exact text");
1078 - await noteCommand("send 1");
1080 - expect(sent).toEqual([{ content: "exact text", options: undefined }]);
1081 - expect(customEntries("notes-state").at(-1)).toEqual({
1082 - op: "remove",
1083 - id: 1,
1084 - removedAt: expect.any(Number),
1085 - });
1086 - expect(latestWidget()).toBeUndefined();
1087 -});
1089 -it("queues send as follow-up when busy", async () => {
1090 - t = await createTestSession({ extensions: [extensionPath()] });
1091 - const sent: Array<{ content: unknown; options: unknown }> = [];
1092 - t.session.extensionRunner.runtime.sendUserMessage = (
1093 - content: unknown,
1094 - options: unknown,
1095 - ) => sent.push({ content, options });
1097 - await noteCommand("add busy text");
1098 - const command = t.session.extensionRunner.extensions[0].commands.get("note");
1099 - const ctx = t.session.extensionRunner.createCommandContext();
1100 - ctx.isIdle = () => false;
1101 - await command.handler("send 1", ctx);
1103 - expect(sent).toEqual([{
1104 - content: "busy text",
1105 - options: { deliverAs: "followUp" },
1106 - }]);
1107 - expect(customEntries("notes-state").at(-1)).toEqual({
1108 - op: "remove",
1109 - id: 1,
1110 - removedAt: expect.any(Number),
1111 - });
1112 -});
1114 -it("unknown send id does not send or mutate", async () => {
1115 - t = await createTestSession({ extensions: [extensionPath()] });
1116 - const sent: Array<{ content: unknown; options: unknown }> = [];
1117 - t.session.extensionRunner.runtime.sendUserMessage = (
1118 - content: unknown,
1119 - options: unknown,
1120 - ) => sent.push({ content, options });
1121 - await noteCommand("add stable text");
1122 - await noteCommand("send 99");
1124 - expect(sent).toEqual([]);
1125 - expect(customEntries("notes-state")).toHaveLength(1);
1126 - expect(uiArgs("notify").at(-1)).toEqual(["Unknown note id: 99", "error"]);
1127 -});
1129 -it("autocompletes subcommands and pending note ids with previews", async () => {
1130 - t = await createTestSession({ extensions: [extensionPath()] });
1131 - const command = t.session.extensionRunner.extensions[0].commands.get("note");
1132 - await noteCommand("add consider split parser tests");
1133 - await noteCommand("add ask whether command should support autocomplete");
1135 - expect(command.getArgumentCompletions("")).toEqual([
1136 - { value: "add", label: "add" },
1137 - { value: "send", label: "send" },
1138 - { value: "edit", label: "edit" },
1139 - { value: "rm", label: "rm" },
1140 - { value: "clear", label: "clear" },
1141 - ]);
1142 - expect(command.getArgumentCompletions("send ")).toEqual([
1143 - { value: "send 1", label: "1 consider split parser tests" },
1145 - value: "send 2",
1146 - label: "2 ask whether command should support autocomplete",
1147 - },
1148 - ]);
1149 - expect(command.getArgumentCompletions("edit 2")).toEqual([
1151 - value: "edit 2",
1152 - label: "2 ask whether command should support autocomplete",
1153 - },
1154 - ]);
1155 - expect(command.getArgumentCompletions("rm ")).toEqual([
1156 - { value: "rm 1", label: "1 consider split parser tests" },
1158 - value: "rm 2",
1159 - label: "2 ask whether command should support autocomplete",
1160 - },
1161 - ]);
1162 -});
1163 -```
1165 -- [ ] **Step 2: Run test to verify it fails**
1167 -Run:
1169 -```bash
1170 -mise run test -- extensions/notes/__tests__/harness.test.ts
1171 -```
1173 -Expected: FAIL because send and autocomplete are not implemented.
1175 -- [ ] **Step 3: Add autocomplete helpers**
1177 -Add this import at the top of `extensions/notes/index.ts`:
1179 -```ts
1180 -import type { AutocompleteItem } from "@earendil-works/pi-tui";
1181 -```
1183 -Add these helpers above `export default`:
1185 -```ts
1186 -const SUBCOMMANDS = ["add", "send", "edit", "rm", "clear"] as const;
1188 -function argumentCompletions(
1189 - state: NotesState,
1190 - argumentPrefix: string,
1191 -): AutocompleteItem[] {
1192 - const { command, rest } = splitCommand(argumentPrefix);
1193 - if (!argumentPrefix.includes(" ")) {
1194 - return SUBCOMMANDS.filter((item) => item.startsWith(command)).map((
1195 - item,
1196 - ) => ({ value: item, label: item }));
1198 - if (command !== "send" && command !== "edit" && command !== "rm") return [];
1199 - return pendingNotes(state)
1200 - .filter((note) => String(note.id).startsWith(rest))
1201 - .map((note) => ({
1202 - value: `${command} ${note.id}`,
1203 - label: `${note.id} ${preview(note.text)}`,
1204 - }));
1206 -```
1208 -- [ ] **Step 4: Add send command branch**
1210 -Insert this branch in the command handler after the `edit` branch and before the usage fallback:
1212 -```ts
1213 -if (command === "send") {
1214 - const note = requireNote(ctx, state, rest);
1215 - if (!note) return;
1216 - if (ctx.isIdle()) pi.sendUserMessage(note.text);
1217 - else pi.sendUserMessage(note.text, { deliverAs: "followUp" });
1218 - appendEvent(pi, state, { op: "remove", id: note.id, removedAt: Date.now() });
1219 - refreshWidget(ctx);
1220 - return;
1222 -```
1224 -- [ ] **Step 5: Wire autocomplete into command registration**
1226 -Add this property to the `pi.registerCommand("note", { ... })` object before `handler`:
1228 -```ts
1229 -getArgumentCompletions: (argumentPrefix) => argumentCompletions(state, argumentPrefix),
1230 -```
1232 -Extend `__test` with `argumentCompletions`:
1234 -```ts
1235 -export const __test = {
1236 - ENTRY_TYPE,
1237 - argumentCompletions,
1238 - compactWidgetLine,
1239 - expandedWidgetLines,
1240 - parseEvent,
1241 - pendingNotes,
1242 - preview,
1243 - replayNotes,
1244 - widgetLines,
1246 -```
1248 -- [ ] **Step 6: Run test to verify it passes**
1250 -Run:
1252 -```bash
1253 -mise run test -- extensions/notes/__tests__/harness.test.ts
1254 -```
1256 -Expected: PASS.
1258 -- [ ] **Step 7: Commit**
1260 -Run:
1262 -```bash
1263 -git add extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts
1264 -git commit -m "feat(notes): send notes and autocomplete ids"
1265 -```
1267 -## Task 6: Branch-Local Replay Coverage And Final Docs Polish
1269 -**Files:**
1271 -- Modify: `extensions/notes/__tests__/harness.test.ts`
1272 -- Modify: `extensions/notes/README.md`
1274 -- [ ] **Step 1: Add branch-local replay assertion**
1276 -Append this test inside the `describe()` block:
1278 -```ts
1279 -it("replay uses only entries returned by the current branch", () => {
1280 - const state = __test.replayNotes([
1282 - type: "custom",
1283 - customType: "notes-state",
1284 - data: { op: "add", id: 2, text: "current branch", createdAt: 1 },
1285 - },
1286 - ]);
1288 - expect(__test.pendingNotes(state)).toEqual([{
1289 - id: 2,
1290 - text: "current branch",
1291 - }]);
1292 - expect(state.nextId).toBe(3);
1293 -});
1294 -```
1296 -- [ ] **Step 2: Run test to verify it passes**
1298 -Run:
1300 -```bash
1301 -mise run test -- extensions/notes/__tests__/harness.test.ts
1302 -```
1304 -Expected: PASS.
1306 -- [ ] **Step 3: Polish README with explicit invisibility and scope**
1308 -Replace the `## Behavior` section in `extensions/notes/README.md` with:
1310 -```md
1311 -## Behavior
1313 -Pending notes are persisted as `notes-state` custom session entries.
1314 -Custom entries are invisible to the model context.
1315 -Notes are branch-local because state is reconstructed from the current session branch.
1316 -The widget is compact on reload or resume.
1318 -No project-global storage exists.
1319 -No cross-session note list exists.
1320 -No system-prompt or model-context injection exists.
1321 -No steer mode exists.
1322 -```
1324 -- [ ] **Step 4: Run focused tests**
1326 -Run:
1328 -```bash
1329 -mise run test -- extensions/notes/__tests__/harness.test.ts
1330 -```
1332 -Expected: PASS.
1334 -- [ ] **Step 5: Commit**
1336 -Run:
1338 -```bash
1339 -git add extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
1340 -git commit -m "test(notes): cover branch-local replay"
1341 -```
1343 -## Task 7: Repository Verification
1345 -**Files:**
1347 -- Verify only.
1349 -- [ ] **Step 1: Run formatter**
1351 -Run:
1353 -```bash
1354 -mise run fmt
1355 -```
1357 -Expected: command exits 0.
1358 -Expected changed files are formatting-only in files touched by this plan.
1360 -- [ ] **Step 2: Run lint**
1362 -Run:
1364 -```bash
1365 -mise run lint
1366 -```
1368 -Expected: command exits 0.
1370 -- [ ] **Step 3: Run targeted test**
1372 -Run:
1374 -```bash
1375 -mise run test -- extensions/notes/__tests__/harness.test.ts
1376 -```
1378 -Expected: command exits 0.
1380 -- [ ] **Step 4: Run full test suite**
1382 -Run:
1384 -```bash
1385 -mise run test
1386 -```
1388 -Expected: command exits 0.
1390 -- [ ] **Step 5: Run static extension checks**
1392 -Run:
1394 -```bash
1395 -mise run check
1396 -```
1398 -Expected: command exits 0.
1400 -- [ ] **Step 6: Inspect final diff**
1402 -Run:
1404 -```bash
1405 -git diff --stat HEAD
1406 -```
1408 -Expected: diff includes only:
1410 -```text
1411 -README.md
1412 -package-lock.json
1413 -extensions/notes/package.json
1414 -extensions/notes/index.ts
1415 -extensions/notes/__tests__/harness.test.ts
1416 -extensions/notes/README.md
1417 -```
1419 -- [ ] **Step 7: Final commit if formatting changed files after last commit**
1421 -If Step 1 changed files after Task 6 commit, run:
1423 -```bash
1424 -git add README.md package-lock.json extensions/notes/package.json extensions/notes/index.ts extensions/notes/__tests__/harness.test.ts extensions/notes/README.md
1425 -git commit -m "chore(notes): format extension"
1426 -```
1428 -Expected: commit succeeds only when there are formatting changes.
1430 -## Spec Coverage Checklist
1432 -- Standalone package at `extensions/notes`: Task 1.
1433 -- One slash command namespace: Tasks 1, 2, 4, 5.
1434 -- Keyboard shortcut `alt+n`: Tasks 1 and 3.
1435 -- Compact and expanded widget: Task 3.
1436 -- Session-backed append-only persistence: Task 2.
1437 -- Autocomplete: Task 5.
1438 -- Tests through real Pi extension runtime: all test tasks.
1439 -- Terse README: Tasks 1 and 6.
1440 -- No state outside Pi session: implementation keeps only derived in-memory state and appends session entries.
1441 -- No prompt/model injection: implementation uses no `before_agent_start`, `custom_message`, or system prompt APIs.
1442 -- No project-global or cross-session notes: implementation writes no project files.
1443 -- Reload/resume/compaction reconstruction: Task 2 replay and Task 3 `session_start` restore.
1444 -- Branch-local replay: Task 6.
1445 -- Unknown ID errors: Task 4 and Task 5.
1446 -- Send exact text as user follow-up when busy: Task 5.
1447 -- Edit cancel and whitespace save behavior: Task 4.

docs/super/specs/2026-06-12-notes-extension-design.md

Deleted
deleted file mode 100644
1 -# Notes Extension Design
3 -## Purpose
5 -`extensions/notes` gives Pi users a manual side channel for prompt ideas that are relevant to the session or project but not useful as immediate steering.
6 -A user can park notes while watching the agent work, then later send one note as a normal follow-up prompt.
7 -Pending notes stay invisible to the agent until explicitly sent.
9 -## Scope
11 -Build a standalone Pi extension package at `extensions/notes`.
12 -The extension provides one slash command namespace, one keyboard shortcut, a compact/expanded widget, session-backed note persistence, autocomplete, tests, and a terse README.
13 -It does not store state outside the Pi session.
14 -It does not inject pending notes into the system prompt or model context.
15 -It does not provide project-global or cross-session notes.
17 -## User Experience
19 -Commands are TUI-only slash commands and are not reachable in print, JSON, or other non-interactive modes.
21 -```text
22 -/note
23 -/note add <text>
24 -/note send <id>
25 -/note edit <id>
26 -/note rm <id>
27 -/note clear
28 -```
30 -`/note add <text>` parks a note for later.
31 -Text must be non-empty after trimming.
32 -If this creates the first pending note, the widget appears above the editor in compact mode.
34 -`/note` toggles the widget between compact and expanded modes.
35 -`alt+n` performs the same toggle.
36 -If no notes are pending, `/note` shows a small informational notification and leaves the widget hidden.
38 -Compact widget shows the count and last note truncated to one line.
39 -Example:
41 -```text
42 -󰎚 3 notes · alt+n expand · last: consider split parser tests…
43 -```
45 -Expanded widget shows every pending note ID and full text.
46 -Example:
48 -```text
49 -󰎚 notes · 3
50 - 1 consider split parser tests
51 - 2 ask whether command should support autocomplete
52 - 3 revisit failure copy
53 -```
55 -`/note send <id>` sends the note text as a normal user follow-up message.
56 -The message body is exactly the note text.
57 -If the agent is busy, the message is delivered after current work finishes via follow-up delivery.
58 -Sending a note removes it immediately from pending notes.
59 -There is no steer mode.
61 -`/note edit <id>` opens the current UI editor with the existing note text.
62 -Saving non-empty text replaces the note.
63 -Cancel keeps the old note unchanged.
64 -Saving whitespace-only text is rejected and keeps the old note unchanged.
66 -`/note rm <id>` removes one note.
67 -`/note clear` asks for confirmation and removes all pending notes only when confirmed.
69 -Autocomplete:
71 -- `/note` suggests `add`, `send`, `edit`, `rm`, `clear`.
72 -- `/note send` suggests pending note IDs with truncated previews.
73 -- `/note edit` suggests pending note IDs with truncated previews.
74 -- `/note rm` suggests pending note IDs with truncated previews.
76 -## Pi Internals
78 -State is stored as append-only custom session entries through `pi.appendEntry()`.
79 -The extension uses one custom entry type, `notes-state`.
80 -Entries do not participate in LLM context, so pending notes remain invisible to the agent.
82 -Events use this shape:
84 -```ts
85 -type NotesEvent =
86 - | { op: "add"; id: number; text: string; createdAt: number }
87 - | { op: "edit"; id: number; text: string; updatedAt: number }
88 - | { op: "remove"; id: number; removedAt: number }
89 - | { op: "clear"; clearedAt: number };
90 -```
92 -On `session_start`, the extension scans `ctx.sessionManager.getBranch()` and replays `notes-state` entries in order.
93 -Only current-branch entries are replayed.
94 -This makes notes branch-local across `/tree`, forks, and resumed branch states.
95 -Invalid edits and removes are ignored.
96 -If pending notes exist after replay, the extension shows the compact widget.
98 -Note IDs are small monotonic integers per branch.
99 -The next ID is `max(replayed IDs) + 1`.
100 -IDs remain stable across reloads and resume.
101 -Removed IDs are not reused.
103 -Widget expanded or compact mode is memory-only UI state.
104 -Reload resets widget mode to compact.
105 -The widget is cleared when no pending notes remain.
107 -`/note send <id>` calls `pi.sendUserMessage(note.text)` when the agent is idle.
108 -If the agent is busy, it calls `pi.sendUserMessage(note.text, { deliverAs: "followUp" })`.
109 -It then appends a remove event and refreshes the widget.
110 -No `custom_message`, `before_agent_start`, or system-prompt injection is used.
112 -## Compaction
114 -No compaction-specific hook is required.
115 -Notes are persisted as custom session entries and are not part of LLM context.
116 -Pi compaction changes what model messages are summarized and kept, but it does not delete the session JSONL history.
117 -Replay from the current branch therefore reconstructs pending notes after reload or resume.
119 -## Error Handling
121 -Unknown note IDs produce an error notification and do not mutate state.
122 -`/note send <id>` with an unknown ID sends no message.
123 -`/note clear` with no notes is a no-op with an informational notification.
124 -`/note edit <id>` requires an interactive or RPC-capable UI.
125 -Widget updates are ignored when no UI exists.
126 -Malformed `notes-state` entries are ignored during replay.
128 -## Package Boundaries
130 -The extension is standalone.
131 -It must not import other `@bugabinga/pi-ext-*` packages.
132 -It may use Pi SDK APIs and TUI utilities from peer dependencies.
133 -It should follow the repository extension package template and include `@marcfargas/pi-test-harness` as a dev dependency.
135 -Files expected:
137 -```text
138 -extensions/notes/package.json
139 -extensions/notes/index.ts
140 -extensions/notes/__tests__/harness.test.ts
141 -extensions/notes/README.md
142 -```
144 -The root README extension table should list `notes`.
145 -Run `npm install` after adding the workspace package.
147 -## Testing
149 -Tests must load `extensions/notes/index.ts` through the real Pi extension runtime with `@marcfargas/pi-test-harness`.
151 -Coverage targets:
153 -- Extension registers `/note` and `alt+n`.
154 -- Autocomplete returns subcommands and note ID previews.
155 -- Replay reconstructs add, edit, remove, and clear events from `getBranch()`.
156 -- Replay is branch-local by using only current branch entries.
157 -- Compact widget includes note count and last note.
158 -- Expanded widget includes IDs and full text.
159 -- `/note send <id>` sends exact note text as follow-up and removes the note.
160 -- `/note edit <id>` keeps old text on cancel and whitespace-only save.
161 -- Unknown IDs do not mutate state or send messages.
163 -## Acceptance Criteria
165 -A user can park prompt ideas while the agent runs without steering the current work.
166 -Pending notes survive reload, resume, and compaction through session custom entries.
167 -Pending notes are invisible to the agent until `/note send <id>`.
168 -The widget is visible on session start when notes exist.
169 -Commands and autocomplete are enough to add, inspect, send, edit, remove, and clear notes.
170 -The implementation passes the extension harness test and repository checks for the notes package.