pi-note 0.4.1 → 0.5.1

package/README.md

@@ -1,12 +1,12 @@
 # pi-note
 
 Persistent [pinote](https://github.com/kvidzibo/pinote) tasks and Markdown handoffs
-in Pi: selected-task footer status, `/pi-note`, and agent read/update tools.
+in Pi: selected-task footer status, `/pi-note`, and agent read/update/add/tag tools.
 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).
+Requires Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag 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
@@ -17,7 +17,7 @@ It is not published yet. npm installation does not run Python installers.
 
 Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first and
 restart Pi with `uv` on PATH. At startup the extension checks `note --version`
-against its bundled CLI version (currently 0.3.0), without network requests:
+against its bundled CLI version (currently 0.4.0), without network requests:
 
 - Missing/unrecognized CLI: show `/pi-note-setup` in the slash-command menu.
 - Older CLI: show and suggest `/pi-note-upgrade`.
@@ -68,18 +68,35 @@ The normal Pi status area shows `📌 [tag] Task title` without replacing other
 The footer omits the task ID and state and shows only the first line, truncated to 60 terminal columns including the pin and tag.
 The pin glyph is bundled in `icons/note.txt`; it uses the terminal's emoji font, not a Nerd Font or icon theme.
 
-Selection is stored per canonical working directory in pinote's database. A new
-Pi session shows that selection; use **Continue** to insert its task-ID prompt.
-Completing, removing, or scheduling a task clears its selections. Switching does
-not complete or reset the previous task. Task status refreshes at session start,
-before/after agent activity, and after commands/tools.
+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
+an older per-folder selection. Pi saves the session after the first submitted message;
+quitting before that leaves the next launch unselected, while the task stays in progress.
+Use **Continue**
+to insert its task-ID prompt. Completing, removing, or scheduling a task clears it
+from sessions that refresh it. Switching does not complete or reset the previous task.
+Task fields such as `Worktree` and `PR` stay on the task, so sessions can use separate
+worktrees and pull requests. Task status refreshes at session start, before/after
+agent activity, and after commands/tools. The CLI's per-directory `agent selected`
+command is not this session memory.
 
 Agent tools:
 
-- `pinote_get`: read the selected task, or an explicit `id`, including its revision.
+- `pinote_get`: read this session's selected task, or an explicit `id`, including its revision.
+  Omitting `id` returns null when this session has no selected task.
 - `pinote_update`: supply `id`, `expected_updated_at` from that read, and arbitrary
   `set` label/value pairs or `remove` labels. Updates merge fields, never replace
-  the task text. If another process changed the task, read again before retrying.
+  the task text or tag. If another process changed the task, read again before retrying.
+- `pinote_tags`: list saved tag names.
+- `pinote_add`: create an active task. Optional `tag`. `select: true` starts and
+  remembers it for this session only; use that only after the user agrees.
+- `pinote_tag`: set or clear a tag on an active or in-progress task. Read first and
+  pass `expected_updated_at`.
+
+When the user gives work and no task is selected, the agent proposes one note as
+`[tag] text` and asks before creating it. No continues without a note. Yes calls
+`pinote_add` with `select: true`. An existing selection is not replaced unless the
+user asks to switch. Reuse a saved tag name when it fits.
 
 Agents are guided to keep notes to three short bullets total: relevant outcome,
 blocker, and next action. Replace stale notes; omit narration, repeated task text,

package/index.ts

@@ -5,9 +5,13 @@ import { stripVTControlCharacters } from "node:util";
 import { Type } from "typebox";
 import { createPRWatcher } from "./pr-watch.ts";
 import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
-import { bundledCLIVersion, cliMenu, detectCLI, compatibleVersion, setupCLI, setupHint, type CLIAction } from "./setup.ts";
+import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.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 PR links in the separate PR field.";
+const createGuidance = [
+  "When the user gives work and no pinote task is selected, propose one note as `[tag] text` and ask before creating it. On no, continue without a note. On yes, call pinote_add with select true so it becomes this session's active task. Never add or select without a yes. If a task is already selected, do not replace it unless the user asks to switch.",
+  "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. pinote_tag changes an existing active or in-progress task after pinote_get; pass updated_at. Do not use pinote_update for tags or task text.",
+];
 type Task = {
   id: number;
   text: string;
@@ -58,7 +62,8 @@ function taskList(raw: string): Summary[] {
   return value.sort((a, b) => b.id - a.id);
 }
 
-function toolResult(value: Task) {
+function toolResult(value: Task | null) {
+  if (!value) return { content: [{ type: "text" as const, text: "null" }], details: null };
   // Keep the model payload under 50 KiB at the CLI's limits; don't send the same fields twice.
   const { markdown: _markdown, ...data } = value;
   return { content: [{ type: "text" as const, text: JSON.stringify(data) }], details: value };
@@ -97,19 +102,86 @@ export default function (pi: ExtensionAPI) {
     }
     return result.stdout;
   };
-  const run = async (argv: string[], signal?: AbortSignal, canRun = () => true) => {
+  const ensureCLI = async (signal?: AbortSignal, canRun = () => true, minimum = "0.3.0") => {
     if (setupAbort) throw new Error("Pinote CLI setup is still running. Retry after it finishes.");
     // Old pinote treats unknown commands as note text. Probe safely before every call,
     // including tools in headless sessions, and do not cache across CLI upgrades/downgrades.
     const version = (await invoke(["--version"], signal)).trim();
-    if (!compatibleVersion(version)) {
-      throw new Error(`pi-note requires pinote 0.3.0+; found ${clean(version) || "an unknown CLI"}. ${setupHint}`);
+    if (!versionAtLeast(version, minimum)) {
+      throw new Error(`pi-note requires pinote ${minimum}+; found ${clean(version) || "an unknown CLI"}. ${setupHint}`);
     }
     if (!canRun()) throw new Error("Pinote operation cancelled: the session changed.");
+  };
+  const run = async (argv: string[], signal?: AbortSignal, canRun = () => true, minimum = "0.3.0") => {
+    await ensureCLI(signal, canRun, minimum);
     return invoke(argv, signal);
   };
-  const selected = async (ctx: ExtensionContext, signal?: AbortSignal) =>
-    task(await run(["agent", "selected", "--cwd", ctx.cwd], signal));
+  const writeTask = async (
+    ctx: ExtensionContext, signal: AbortSignal | undefined, argv: string[], id?: number, minimum = "0.3.0",
+  ) => {
+    if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
+    const operation = Symbol();
+    pending = operation;
+    const generation = epoch;
+    refreshSerial++;
+    try {
+      return requiredTask(await run(argv, signal, () => alive && generation === epoch, minimum), id);
+    } finally {
+      if (pending === operation) pending = undefined;
+      if (alive && generation === epoch) await refresh(ctx);
+    }
+  };
+  // One folder can host several sessions. Remember the task in the Pi session, not by cwd.
+  const selectionType = "pinote-selection";
+  let selectedId: number | null = null;
+  let branchEpoch = 0;
+  const remember = (id: number | null, branch = branchEpoch) => {
+    if (!alive || branch !== branchEpoch || selectedId === id) return;
+    selectedId = id;
+    pi.appendEntry(selectionType, { id });
+  };
+  const readSelection = (ctx: ExtensionContext) => {
+    let id: number | null = null;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom" || entry.customType !== selectionType) continue;
+      const data = entry.data as { id?: unknown } | null;
+      id = data && validId(data.id) ? data.id : null;
+    }
+    return id;
+  };
+  const currentTask = async (signal?: AbortSignal, canUse = () => alive) => {
+    const id = selectedId;
+    if (!validId(id) || !canUse()) return null;
+    const current = task(await run(["agent", "get", String(id)], signal, canUse));
+    if (!canUse() || selectedId !== id) return null;
+    if (!current || current.id !== id || !["active", "in_progress"].includes(current.state)) {
+      if (canUse() && selectedId === id) remember(null);
+      return null;
+    }
+    return current;
+  };
+  const selected = async (_ctx: ExtensionContext, signal?: AbortSignal) => {
+    const generation = epoch;
+    const canUse = () => alive && generation === epoch;
+    await ensureCLI(signal, canUse);
+    return currentTask(signal, canUse);
+  };
+  const startTask = async (id: number, canAct: () => boolean, signal?: AbortSignal) => {
+    const branch = branchEpoch;
+    const still = () => canAct() && branch === branchEpoch;
+    const before = requiredTask(await run(["agent", "get", String(id)], signal, still), id);
+    if (!still()) return;
+    if (!["active", "in_progress"].includes(before.state)) {
+      throw new Error(`Note ${id} is ${before.state}; restore it first.`);
+    }
+    // Start without the shared cwd selection so another session can keep a different task.
+    if (before.state === "active") await run(["--no-notify", "start", String(id)], signal, still);
+    const chosen = requiredTask(await run(["agent", "get", String(id)], signal, still), id);
+    if (chosen.state !== "in_progress") throw new Error(compatible);
+    if (!still()) return;
+    remember(chosen.id, branch);
+    return chosen;
+  };
 
   const refresh = async (ctx: ExtensionContext) => {
     if (!alive || setupAbort || !ctx.hasUI || ctx.mode !== "tui") return;
@@ -149,6 +221,8 @@ export default function (pi: ExtensionAPI) {
     alive = true;
     activeContext = ctx;
     epoch++;
+    branchEpoch++;
+    selectedId = readSelection(ctx);
     const generation = epoch;
     cliState = undefined;
     if (ctx.hasUI && ctx.mode === "tui") {
@@ -161,13 +235,25 @@ export default function (pi: ExtensionAPI) {
     if (!setupAbort) watcher.start(ctx);
     await refresh(ctx);
   });
+  pi.on("session_tree", async (_event, ctx) => {
+    if (!alive) return;
+    branchEpoch++;
+    const generation = branchEpoch;
+    const id = readSelection(ctx);
+    if (!alive || generation !== branchEpoch) return;
+    selectedId = id;
+    if (setupAbort) return;
+    await refresh(ctx);
+  });
   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) => {
     setupAbort?.abort();
     alive = false;
     activeContext = undefined;
+    selectedId = null;
     epoch++;
+    branchEpoch++;
     refreshSerial++;
     watcher.stop();
     if (ctx.hasUI && ctx.mode === "tui") ctx.ui.setStatus("pinote", undefined);
@@ -226,8 +312,9 @@ export default function (pi: ExtensionAPI) {
       const operation = Symbol();
       pending = operation;
       const generation = epoch;
+      const branch = branchEpoch;
       const currentSession = () => alive && generation === epoch;
-      const canAct = () => currentSession() && ctx.isIdle();
+      const canAct = () => currentSession() && ctx.isIdle() && branch === branchEpoch;
       try {
         const current = await selected(ctx);
         if (!canAct()) return;
@@ -241,6 +328,7 @@ export default function (pi: ExtensionAPI) {
             "agent", "done", String(current.id), "--expected-updated-at", current.updated_at,
           ], undefined, canAct), current.id);
           if (completed.state !== "done") throw new Error(compatible);
+          if (currentSession() && branch === branchEpoch) remember(null, branch);
           if (currentSession()) ctx.ui.notify(`Pinote #${current.id} completed.`, "info");
           return;
         }
@@ -256,10 +344,9 @@ export default function (pi: ExtensionAPI) {
           if (choice === undefined || !canAct()) return;
           id = choice;
         } else return;
-        // Validate/start the explicit task and return its latest handoff in one transaction.
         refreshSerial++;
-        const chosen = requiredTask(await run(["agent", "select", String(id), "--cwd", ctx.cwd], undefined, canAct), id);
-        if (!canAct()) return;
+        const chosen = await startTask(id, canAct);
+        if (!chosen || !canAct()) return;
         const draft = ctx.ui.getEditorText();
         const handoff = `Read task #${chosen.id} with pinote_get and work on it. Ask only if blocked. Save progress with pinote_update.`;
         ctx.ui.setEditorText(draft ? `${draft}\n\n${handoff}` : handoff);
@@ -276,14 +363,14 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "pinote_get",
     label: "Pinote get",
-    description: "Read a pinote task and its Markdown agent fields/revision. Omit id to read this project's selected task; supply id to read another task. Use the returned updated_at for pinote_update.",
+    promptGuidelines: createGuidance,
+    description: "Read a pinote task and its Markdown agent fields/revision. Omit id to read this session's selected task; returns null when none is selected. Supply id to read another task. Use the returned updated_at for pinote_update and pinote_tag.",
     parameters: Type.Object({ id: Type.Optional(idSchema) }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       if (params.id !== undefined && !validId(params.id)) throw new Error("id must be a positive safe integer.");
-      const argv = params.id === undefined
-        ? ["agent", "selected", "--cwd", ctx.cwd]
-        : ["agent", "get", String(params.id)];
-      const result = requiredTask(await run(argv, signal), params.id);
+      const result = params.id === undefined
+        ? await selected(ctx, signal)
+        : requiredTask(await run(["agent", "get", String(params.id)], signal), params.id);
       return toolResult(result);
     },
   });
@@ -291,7 +378,7 @@ export default function (pi: ExtensionAPI) {
     name: "pinote_update",
     label: "Pinote update",
     promptGuidelines: [handoffGuidance],
-    description: "Patch arbitrary agent handoff fields on an explicit pinote task. Read first with pinote_get; pass its updated_at as expected_updated_at. set merges label/value pairs without replacing other fields or task text; values are Markdown, e.g. PR: [Fix #42](https://github.com/org/repo/pull/42). Set PR to one GitHub pull-request URL or Markdown link to show it in the footer and watch for merge confirmation in interactive Pi. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task.",
+    description: "Patch arbitrary agent handoff fields on an explicit pinote task. Read first with pinote_get; pass its updated_at as expected_updated_at. set merges label/value pairs without replacing other fields or task text; values are Markdown, e.g. PR: [Fix #42](https://github.com/org/repo/pull/42). Set PR to one GitHub pull-request URL or Markdown link to show it in the footer and watch for merge confirmation in interactive Pi. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task or change its tag.",
     parameters: Type.Object({
       id: idSchema,
       expected_updated_at: Type.String({ minLength: 1 }),
@@ -302,21 +389,80 @@ export default function (pi: ExtensionAPI) {
       if (!validId(params.id) || !text(params.expected_updated_at) || !params.expected_updated_at.trim()) {
         throw new Error("id and expected_updated_at are required; read the task first.");
       }
+      const argv = ["agent", "update", String(params.id), "--expected-updated-at", params.expected_updated_at,
+        "--set-json", JSON.stringify(params.set ?? {})];
+      for (const label of params.remove ?? []) argv.push(`--remove=${label}`);
+      return toolResult(await writeTask(ctx, signal, argv, params.id));
+    },
+  });
+  pi.registerTool({
+    name: "pinote_tags",
+    label: "Pinote tags",
+    description: "List saved pinote tag names so a new or retagged task can reuse one.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, signal) {
+      const value = parse(await run(["agent", "tags"], signal, () => true, "0.4.0"));
+      if (!Array.isArray(value) || !value.every((item) => text(item))) throw new Error(compatible);
+      return { content: [{ type: "text" as const, text: JSON.stringify(value) }], details: value };
+    },
+  });
+  pi.registerTool({
+    name: "pinote_add",
+    label: "Pinote add",
+    promptGuidelines: createGuidance,
+    description: "Create an active pinote task. Optional tag is registered if new. Set select true only after the user agrees to make it this session's active task; that starts it and remembers it for this session only. Omitting select leaves the current selection unchanged. Does not refresh the desktop notification or bind the project directory.",
+    parameters: Type.Object({
+      text: Type.String({ minLength: 1 }),
+      tag: Type.Optional(Type.String({ minLength: 1 })),
+      select: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!text(params.text) || !params.text.trim()) throw new Error("text must be a non-empty note.");
+      if (params.tag !== undefined && (!text(params.tag) || !params.tag.trim())) {
+        throw new Error("tag must be a non-empty name, or omit it.");
+      }
+      if (params.select !== undefined && typeof params.select !== "boolean") throw new Error("select must be a boolean.");
+      const argv = ["agent", "add", `--text=${params.text}`];
+      if (params.tag !== undefined) argv.push(`--tag=${params.tag}`);
+      const generation = epoch;
+      const branch = branchEpoch;
+      const created = await writeTask(ctx, signal, argv, undefined, "0.4.0");
+      if (params.select !== true) return toolResult(created);
+      if (!alive || generation !== epoch || branch !== branchEpoch) throw new Error("Pinote operation cancelled: the session changed.");
       if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
       const operation = Symbol();
       pending = operation;
-      const generation = epoch;
-      refreshSerial++;
       try {
-        const argv = ["agent", "update", String(params.id), "--expected-updated-at", params.expected_updated_at,
-          "--set-json", JSON.stringify(params.set ?? {})];
-        for (const label of params.remove ?? []) argv.push(`--remove=${label}`);
-        const result = requiredTask(await run(argv, signal, () => alive && generation === epoch), params.id);
-        return toolResult(result);
+        const chosen = await startTask(
+          created.id, () => alive && generation === epoch && branch === branchEpoch && pending === operation, signal,
+        );
+        if (!chosen) throw new Error("Pinote operation cancelled: the session changed.");
+        return toolResult(chosen);
       } finally {
         if (pending === operation) pending = undefined;
         if (alive && generation === epoch) await refresh(ctx);
       }
     },
   });
+  pi.registerTool({
+    name: "pinote_tag",
+    label: "Pinote tag",
+    description: "Set or clear the tag on an active or in-progress pinote task. Read first with pinote_get and pass updated_at as expected_updated_at. Provide tag or clear true, not both. A stale revision fails without writing. Does not change task text.",
+    parameters: Type.Object({
+      id: idSchema,
+      expected_updated_at: Type.String({ minLength: 1 }),
+      tag: Type.Optional(Type.String({ minLength: 1 })),
+      clear: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!validId(params.id) || !text(params.expected_updated_at) || !params.expected_updated_at.trim()) {
+        throw new Error("id and expected_updated_at are required; read the task first.");
+      }
+      if ((params.tag !== undefined) === (params.clear === true)) throw new Error("Provide tag or clear true, not both.");
+      if (params.tag !== undefined && (!text(params.tag) || !params.tag.trim())) throw new Error("tag must be a non-empty name.");
+      const argv = ["agent", "tag", String(params.id), "--expected-updated-at", params.expected_updated_at];
+      argv.push(params.clear === true ? "--clear" : `--tag=${params.tag}`);
+      return toolResult(await writeTask(ctx, signal, argv, params.id, "0.4.0"));
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",

package/setup.ts

@@ -3,8 +3,8 @@ import { stripVTControlCharacters } from "node:util";
 import type { AutocompleteProvider } from "@earendil-works/pi-tui";
 
 // Immutable source: the Python app is not yet published to PyPI.
-export const cliSource = "https://github.com/kvidzibo/pinote/archive/9c6795f655e6b9d2c51c735fc84b6485fb663bb1.tar.gz";
-export const bundledCLIVersion = "0.3.0";
+export const cliSource = "https://github.com/kvidzibo/pinote/archive/1597baf60bff8bc96893be40781f152a001623d1.tar.gz";
+export const bundledCLIVersion = "0.4.0";
 export const setupHint = "Use /pi-note-setup for a missing CLI or /pi-note-upgrade for an older CLI; note must be on PATH.";
 export type CLIAction = "setup" | "upgrade" | "ready";
 
@@ -44,9 +44,19 @@ export function cliMenu(current: AutocompleteProvider, action: () => CLIAction |
     shouldTriggerFileCompletion: (...args) => current.shouldTriggerFileCompletion?.(...args) ?? true,
   };
 }
-export function compatibleVersion(version: string): boolean {
+export function versionAtLeast(version: string, minimum: string): boolean {
   const match = /^pinote (\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
-  return !!match && (Number(match[1]) > 0 || Number(match[2]) >= 3);
+  if (!match) return false;
+  const installed = match.slice(1).map(Number);
+  const required = minimum.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (installed[i] > required[i]) return true;
+    if (installed[i] < required[i]) return false;
+  }
+  return true;
+}
+export function compatibleVersion(version: string): boolean {
+  return versionAtLeast(version, "0.3.0");
 }
 const clean = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/gu, " ").slice(0, 1500);