pi-note 0.11.1 → 0.12.0

package/README.md

@@ -7,7 +7,7 @@ The extension and Python app share a repository but install separately.
 
 ## Install
 
-Requires Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
+Requires Pi 0.99.1+, Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
 From this checkout, install the extension with `pi install ./pi`, then run
 `/reload` in interactive Pi. Use `/pi-note-setup` if the CLI is missing, or the
 suggested `/pi-note-upgrade` if it is older than the bundled CLI. The planned npm package name is
@@ -68,9 +68,41 @@ task, so existing values can be configured without creating another task.
 Type in the task picker to filter by text, ID, tag, or state (all words must match).
 Use ↑/↓ and Enter to select, or Esc to cancel. Rows show **●** for in progress or
 **○** for active, followed by the tag (`[Untagged]` when absent).
-The normal Pi status area shows `📌 [tag] Task title` without replacing other footers.
-The footer omits the task ID and state and shows only the first line, truncated to the configured width (default 60 terminal columns including the pin and tag). Overflow ends with `...`.
-The pin glyph is bundled in `icons/note.txt`; it uses the terminal's emoji font, not a Nerd Font or icon theme.
+The normal Pi status area shows `👁 📌 [tag] Task title` without replacing other footers.
+The footer omits the task ID and state and shows only the first line, truncated to the configured width (default 60 terminal columns including the eye, pin and tag). Overflow ends with `...`.
+The glyphs are bundled in `icons/eye.txt` and `icons/note.txt`; they use terminal fonts, not a Nerd Font or icon theme.
+
+### Display-only preview
+
+Run `/pi-note-preview` to print the selected task's full Markdown text and saved
+agent fields in the transcript. The preview is labeled **display only · not sent
+to model**: it is a local custom session entry, excluded from subsequent model
+requests, compaction and branch summaries. It survives session resume but does not
+modify the note, editor draft or task selection, and never starts a model call.
+The agent can still read the task separately with `pinote_get_current`.
+Previewing requires Pi to be idle with no other Pinote operation open.
+
+On Linux, the eye is a clickable OSC 8 link to a private per-session Unix socket.
+The package ships [a Kitty configuration example](kitty/open-actions.conf).
+Append its block to `~/.config/kitty/open-actions.conf`, preserving existing
+actions. Replace `/absolute/path/to/pi-note` with the installed package directory
+containing `preview-click.cjs`; for this checkout, that directory is `pi/`.
+Keep `${URL}` literal: Kitty substitutes the clicked eye's link.
+
+```conf
+protocol pi-note-preview
+action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs ${URL}
+```
+
+Do not replace or symlink your entire Kitty configuration to the example: it
+contains only Pinote's handler. Package installation does not edit Kitty files.
+
+Reload Kitty with **Ctrl+Shift+F5**. In Pi's regular mode, click the eye; in
+fullscreen mode, use **Ctrl+Shift+click** so Kitty handles the link instead of
+Pi's system URL opener. The helper sends only an authenticated selection
+identifier, never note content or a model prompt. Stale links after task switching, tree navigation, reload or session exit
+are rejected. Other terminals can use `/pi-note-preview`; if the socket cannot
+start, the eye is omitted and that command remains available.
 
 Each Pi session remembers its own task, including several sessions in one folder.
 Resume restores that session's task; a new session starts unselected and does not import
@@ -198,7 +230,7 @@ Add `footer` to `~/.pi/agent/pi-note.json` (or `pi-note.json` under
 }
 ```
 
-Widths are terminal columns, including icons/tags or field labels, and must be
+Widths are terminal columns, including the eye, pin, tags or field labels, and must be
 integers from 3 to 1000. Defaults: `titleWidth: 60`, `fieldWidth: 60`,
 `maxFields: 4` (allowed 0–64). Each field can override `fieldWidth` with `width`.
 `fields` selects task field names in order, regardless of a task's `Bar`.

package/icons/eye.txt

@@ -0,0 +1 @@
+👁

package/index.ts

@@ -1,5 +1,5 @@
-import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Editor, truncateToWidth, type Keybinding } from "@earendil-works/pi-tui";
+import { getAgentDir, getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Editor, Markdown, Text, truncateToWidth, visibleWidth, type Keybinding } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -9,6 +9,7 @@ import { defaultFooterConfig, defaultHandoffPrompt, effectiveFooterFields, loadF
 import { FooterSettings, TaskMenu, withSettingsTab } from "./footer-settings.ts";
 import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
 import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
+import { createPreviewBridge } from "./preview-bridge.ts";
 
 const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep a GitHub pull request in the PR field. Read pinote_fields to learn the user's globally configured footer field names and presentation. Populate those fields with meaningful task values when relevant using pinote_update_current; fields without values stay hidden. Footer fields and widths are chosen by the user's pi-note.json config. Set configured fields with Markdown values; links are clickable. When footer.fields is unset, Bar selects labels, one per line. Do not list PR in Bar. Remove a field to hide it. Do not modify config without user approval.";
 const offerGuidance = {
@@ -30,6 +31,8 @@ type Task = {
 type Summary = Pick<Task, "id" | "text" | "state" | "tag">;
 // The standard Pi footer accepts text, so ship a portable terminal glyph, not a theme icon.
 const noteIcon = readFileSync(new URL("./icons/note.txt", import.meta.url), "utf8").trim();
+const eyeIcon = readFileSync(new URL("./icons/eye.txt", import.meta.url), "utf8").trim();
+const previewType = "pinote-preview";
 const compatible = "Incompatible note CLI response. Install pinote 0.3.0+ and check note on PATH.";
 const validId = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) > 0;
 const record = (value: unknown): value is Record<string, unknown> =>
@@ -115,6 +118,14 @@ function toolResult(value: Task | null) {
 
 export default function (pi: ExtensionAPI) {
   const { guidelines: createGuidance, error: offerConfigError } = creationGuidance();
+  pi.registerEntryRenderer<{ id: number; markdown: string }>(previewType, (entry, _options, theme) => {
+    if (!record(entry.data) || !validId(entry.data.id) || typeof entry.data.markdown !== "string") return;
+    const view = new Container();
+    view.addChild(new Text(theme.fg("muted", `Pinote #${entry.data.id} · display only · not sent to model`), 0, 0));
+    view.addChild(new Markdown(clean(entry.data.markdown), 0, 0, getMarkdownTheme()));
+    return view;
+  });
+  let previewBridge: ReturnType<typeof createPreviewBridge> | undefined;
   let alive = true;
   let epoch = 0;
   let refreshSerial = 0;
@@ -184,6 +195,7 @@ export default function (pi: ExtensionAPI) {
   let branchEpoch = 0;
   const remember = (id: number | null, branch = branchEpoch) => {
     if (!alive || branch !== branchEpoch || selectedId === id) return;
+    previewBridge?.invalidate();
     selectedId = id;
     pi.appendEntry(selectionType, { id });
   };
@@ -238,11 +250,20 @@ export default function (pi: ExtensionAPI) {
     try {
       const current = await selected(ctx);
       if (alive && generation === epoch && serial === refreshSerial) {
-        ctx.ui.setStatus("pinote", current ? truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, footerConfig.titleWidth, "...") : undefined);
+        const previewId = current?.id ?? null;
+        const previewBranch = branchEpoch;
+        previewBridge?.setTask(previewId, (signal) => alive && generation === epoch && previewBranch === branchEpoch &&
+          selectedId === previewId ? preview(ctx, signal) : Promise.resolve(false));
+        const url = previewBridge?.url();
+        // Keep the eye outside title truncation, including the minimum title width.
+        const eye = url ? `\x1b]8;;${url}\x07${eyeIcon}\x1b]8;;\x07 ` : "";
+        const width = Math.max(0, footerConfig.titleWidth - (eye ? visibleWidth(eyeIcon) + 1 : 0));
+        ctx.ui.setStatus("pinote", current ? eye + truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, width, "...") : undefined);
         watcher.update(ctx, current);
       }
     } catch {
       if (alive && generation === epoch && serial === refreshSerial) {
+        previewBridge?.invalidate();
         ctx.ui.setStatus("pinote", `${noteIcon} Pinote unavailable · ${cliState === "upgrade" ? "/pi-note-upgrade" : cliState === "setup" ? "/pi-note-setup" : "/pi-note"}`);
       }
     }
@@ -265,14 +286,57 @@ export default function (pi: ExtensionAPI) {
     },
     refresh,
   });
+  const preview = async (ctx: ExtensionContext, requestSignal?: AbortSignal): Promise<boolean> => {
+    if (!ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || !validId(selectedId)) return false;
+    const generation = epoch;
+    const branch = branchEpoch;
+    const id = selectedId;
+    const operation = Symbol();
+    pending = operation;
+    // Complete before the bridge's 5s and helper's 6s deadlines; disconnection cancels reads too.
+    const controller = new AbortController();
+    const deadline = Date.now() + 4000;
+    const timer = setTimeout(() => controller.abort(), 4000);
+    const signal = requestSignal ? AbortSignal.any([requestSignal, controller.signal]) : controller.signal;
+    const canUse = () => alive && generation === epoch && branch === branchEpoch && selectedId === id && ctx.isIdle() &&
+      !signal.aborted && Date.now() < deadline;
+    try {
+      const current = await currentTask(signal, canUse);
+      if (!current || !canUse()) return false;
+      // Custom entries are rendered locally, never conversation messages or compaction input.
+      pi.appendEntry(previewType, { id: current.id, markdown: current.markdown });
+      return true;
+    } catch (error) {
+      if (canUse()) ctx.ui.notify(`Pinote preview: ${clean(String(error))}`, "error");
+      return false;
+    } finally {
+      clearTimeout(timer);
+      if (pending === operation) pending = undefined;
+    }
+  };
+  pi.registerCommand("pi-note-preview", {
+    description: "Display the selected task locally without sending it to the model",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim()) { ctx.ui.notify("Usage: /pi-note-preview", "warning"); return; }
+      if (!await preview(ctx)) ctx.ui.notify("Select a task with /pi-note and wait until Pi is idle before previewing.", "warning");
+    },
+  });
   pi.on("session_start", async (_event, ctx) => {
     setupAbort?.abort();
-    alive = true;
-    activeContext = ctx;
+    // Retire old polling before bridge teardown/startup yields to its scheduled callbacks.
+    watcher.stop();
+    alive = false;
     epoch++;
     branchEpoch++;
-    selectedId = readSelection(ctx);
     const generation = epoch;
+    const previousBridge = previewBridge;
+    previewBridge = undefined;
+    if (previousBridge) await previousBridge.stop();
+    if (generation !== epoch) return;
+    alive = true;
+    activeContext = ctx;
+    selectedId = readSelection(ctx);
     footerConfig = loadFooterConfig((message) => {
       if (ctx.hasUI) ctx.ui.notify(message, "warning");
     });
@@ -281,6 +345,18 @@ export default function (pi: ExtensionAPI) {
       if (offerConfigError) ctx.ui.notify(`Pinote task offers disabled: ${clean(offerConfigError)} Fix the configuration and /reload.`, "warning");
       ctx.ui.addAutocompleteProvider((current) => cliMenu(current, () => setupAbort ? undefined : cliState));
     }
+    if (ctx.hasUI && ctx.mode === "tui") {
+      const bridge = createPreviewBridge();
+      previewBridge = bridge;
+      try {
+        await bridge.start();
+      } catch {
+        await bridge.stop();
+        if (previewBridge === bridge) previewBridge = undefined;
+        ctx.ui.notify("Pinote eye link unavailable; use /pi-note-preview.", "warning");
+      }
+    }
+    if (!alive || generation !== epoch) return;
     // Keep the setup lock until its aborted subprocess has actually settled.
     if (!setupAbort) pending = undefined;
     await checkCLI(ctx, true);
@@ -291,6 +367,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_tree", async (_event, ctx) => {
     if (!alive) return;
     branchEpoch++;
+    previewBridge?.invalidate();
     const generation = branchEpoch;
     const id = readSelection(ctx);
     if (!alive || generation !== branchEpoch) return;
@@ -300,7 +377,7 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("before_agent_start", async (_event, ctx) => { await refresh(ctx); });
   pi.on("agent_end", async (_event, ctx) => { await refresh(ctx); });
-  pi.on("session_shutdown", (_event, ctx) => {
+  pi.on("session_shutdown", async (_event, ctx) => {
     setupAbort?.abort();
     alive = false;
     activeContext = undefined;
@@ -310,6 +387,9 @@ export default function (pi: ExtensionAPI) {
     refreshSerial++;
     watcher.stop();
     if (ctx.hasUI && ctx.mode === "tui") ctx.ui.setStatus("pinote", undefined);
+    const bridge = previewBridge;
+    previewBridge = undefined;
+    if (bridge) await bridge.stop();
   });
 
   const registerInstallCommand = (name: "pi-note-setup" | "pi-note-upgrade") => pi.registerCommand(name, {

package/kitty/open-actions.conf

@@ -0,0 +1,5 @@
+# Append this block to ~/.config/kitty/open-actions.conf; preserve existing actions.
+# Replace /absolute/path/to/pi-note with the directory containing preview-click.cjs.
+# Keep ${URL} literal: Kitty substitutes the clicked eye's link.
+protocol pi-note-preview
+action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs ${URL}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "homepage": "https://github.com/kvidzibo/pinote/tree/main/pi#readme",
   "bugs": { "url": "https://github.com/kvidzibo/pinote/issues" },
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "files": ["index.ts", "pr-watch.ts", "footer-links.ts", "footer-config.ts", "footer-settings.ts", "task-picker.ts", "setup.ts", "icons", "README.md", "LICENSE"],
+  "files": ["index.ts", "pr-watch.ts", "footer-links.ts", "footer-config.ts", "footer-settings.ts", "task-picker.ts", "setup.ts", "preview-bridge.ts", "preview-click.cjs", "icons", "kitty", "README.md", "LICENSE"],
   "pi": { "extensions": ["./index.ts"] },
   "scripts": {
     "check": "tsc --noEmit",

package/preview-bridge.ts

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { basename, join } from "node:path";
+
+// No note data travels through the socket or hyperlink; both identify a local selection.
+export function createPreviewBridge() {
+  const uid = process.getuid?.();
+  const capability = randomBytes(16).toString("hex");
+  let server: Server | undefined;
+  let socketPath: string | undefined;
+  let starting: Promise<void> | undefined;
+  let stopping: Promise<void> | undefined;
+  let closed = false;
+  let ready = false;
+  let taskId: number | null = null;
+  let callback: ((signal: AbortSignal) => Promise<boolean>) | undefined;
+  let nonce: string | undefined;
+  const clients = new Set<Socket>();
+  const invalidate = () => { taskId = null; callback = undefined; nonce = undefined; };
+  const cleanup = async () => {
+    ready = false;
+    for (const client of clients) client.destroy();
+    const instance = server;
+    server = undefined;
+    if (instance) await new Promise<void>((resolve) => instance.close(() => resolve()));
+    const file = socketPath;
+    socketPath = undefined;
+    if (file) {
+      try {
+        const st = await fs.lstat(file);
+        if (st.isSocket() && st.uid === uid) await fs.unlink(file);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+    }
+  };
+  const api = {
+    async start(): Promise<void> {
+      if (closed || uid === undefined) throw new Error("Preview bridge unavailable");
+      if (starting) return starting;
+      starting = (async () => {
+        const dir = `/tmp/pi-note-preview-${uid}`;
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const st = await fs.lstat(dir);
+        if (!st.isDirectory() || st.uid !== uid || (st.mode & 0o777) !== 0o700 || closed) {
+          throw new Error("Preview bridge unavailable");
+        }
+        socketPath = join(dir, `${process.pid}-${randomBytes(4).toString("hex")}.sock`);
+        const instance = createServer((client) => {
+          clients.add(client);
+          const request = new AbortController();
+          client.on("error", () => client.destroy());
+          client.on("close", () => { request.abort(); clients.delete(client); });
+          client.setTimeout(5000, () => { request.abort(); client.destroy(); });
+          let data = Buffer.alloc(0);
+          let dispatched = false;
+          client.on("data", (chunk) => {
+            if (dispatched || closed) return;
+            data = Buffer.concat([data, chunk]);
+            if (data.length > 128) { client.destroy(); return; }
+            if (!data.includes(10)) return;
+            dispatched = true;
+            const input = data.toString("utf8");
+            const match = /^preview ([0-9a-f]{32}) ([1-9][0-9]*) ([0-9a-f]{32})\n$/u.exec(input);
+            const id = match ? Number(match[2]) : NaN;
+            if (!match || match[0] !== input || match[1] !== capability || !Number.isSafeInteger(id) ||
+                id !== taskId || match[3] !== nonce || !callback) { client.end("rejected\n"); return; }
+            const invoke = callback;
+            Promise.resolve().then(() => !closed && !request.signal.aborted && taskId === id && nonce === match[3] ? invoke(request.signal) : false)
+              .then((accepted) => { if (!client.destroyed) client.end(accepted === true ? "accepted\n" : "rejected\n"); },
+                () => { if (!client.destroyed) client.end("rejected\n"); });
+          });
+        });
+        server = instance;
+        try {
+          await new Promise<void>((resolve, reject) => {
+            instance.once("error", reject);
+            instance.listen(socketPath!, resolve);
+          });
+          await fs.chmod(socketPath, 0o600);
+          if (closed) throw new Error("Preview bridge unavailable");
+          instance.on("error", () => { void api.stop().catch(() => {}); });
+          instance.unref();
+          ready = true;
+        } catch {
+          await cleanup();
+          throw new Error("Preview bridge unavailable");
+        }
+      })();
+      return starting;
+    },
+    setTask(id: number | null, preview: (signal: AbortSignal) => Promise<boolean>): void {
+      if (closed) return;
+      if (id !== null && (!Number.isSafeInteger(id) || id <= 0)) throw new Error("Invalid preview task");
+      if (id !== taskId) nonce = id === null ? undefined : randomBytes(16).toString("hex");
+      taskId = id;
+      callback = id === null ? undefined : preview;
+    },
+    invalidate,
+    url(): string | undefined {
+      if (!ready || closed || !socketPath || taskId === null || !nonce) return;
+      return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/${taskId}/${nonce}`;
+    },
+    async stop(): Promise<void> {
+      closed = true;
+      invalidate();
+      if (!stopping) stopping = (async () => { await starting?.catch(() => {}); await cleanup(); })();
+      return stopping;
+    },
+  };
+  return api;
+}

package/preview-click.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+const net = require('node:net');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const urlPattern = /^pi-note-preview:\/\/([1-9][0-9]*)-([0-9a-f]{8})\/([0-9a-f]{32})\/([1-9][0-9]*)\/([0-9a-f]{32})$/;
+
+function parse(value) {
+  if (typeof value !== 'string' || value.length > 160) throw new Error('Preview unavailable');
+  const m = urlPattern.exec(value);
+  if (!m || m[0] !== value) throw new Error('Preview unavailable');
+  const pid = Number(m[1]), id = Number(m[4]);
+  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(id) || pid <= 0 || id <= 0) throw new Error('Preview unavailable');
+  return { pid, tag: m[2], capability: m[3], id, nonce: m[5] };
+}
+function socketPathFor(value) {
+  const p = parse(value);
+  return path.join(`/tmp/pi-note-preview-${typeof process.getuid === 'function' ? process.getuid() : -1}`, `${p.pid}-${p.tag}.sock`);
+}
+function verify(file) {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
+  if (uid < 0) throw new Error('Preview unavailable');
+  const dir = `/tmp/pi-note-preview-${uid}`;
+  const ds = fs.lstatSync(dir);
+  if (!ds.isDirectory() || ds.isSymbolicLink() || ds.uid !== uid || (ds.mode & 0o777) !== 0o700) throw new Error('Preview unavailable');
+  const ss = fs.lstatSync(file);
+  if (!ss.isSocket() || ss.isSymbolicLink() || ss.uid !== uid || (ss.mode & 0o777) !== 0o600) throw new Error('Preview unavailable');
+}
+function preview(value) {
+  let p, file;
+  try { p = parse(value); file = socketPathFor(value); verify(file); }
+  catch { return Promise.reject(new Error('Preview unavailable')); }
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(file);
+    let response = Buffer.alloc(0), done = false;
+    const finish = (err, result) => {
+      if (done) return;
+      done = true; clearTimeout(timer); client.destroy();
+      err ? reject(new Error('Preview unavailable')) : resolve(result);
+    };
+    const timer = setTimeout(() => finish(new Error()), 6000);
+    client.on('connect', () => client.write(`preview ${p.capability} ${p.id} ${p.nonce}\n`));
+    client.on('data', chunk => {
+      response = Buffer.concat([response, chunk]);
+      if (response.length > 64) return finish(new Error());
+      const text = response.toString('utf8');
+      if (text.includes('\n')) finish(text === 'accepted\n' ? null : new Error(), text === 'accepted\n');
+    });
+    client.on('error', () => finish(new Error()));
+    client.on('end', () => { if (!done) finish(new Error()); });
+  });
+}
+if (require.main === module) {
+  if (process.argv.length !== 3) {
+    console.error('Usage: preview-click.cjs <preview URL>');
+    process.exitCode = 2;
+  } else {
+    preview(process.argv[2]).catch(() => {
+      console.error('Pinote preview unavailable; select a task and wait until Pi is idle.');
+      process.exitCode = 1;
+    });
+  }
+}
+module.exports = { preview, socketPathFor };