pi-note 0.4.0 → 0.5.0

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`.
@@ -55,8 +55,11 @@ standalone `settings/pi/extensions/pinote.ts` entry if installed; load only one
 
 ## Use
 
-`/pi-note` picks a task, starts it, and puts its full text and saved handoff fields
-in the editor. Existing drafts are preserved; nothing is submitted automatically.
+`/pi-note` picks a task, starts it, and adds a short task-ID prompt to the editor:
+“Read task #121 with pinote_get and work on it. Ask only if blocked. Save progress
+with pinote_update.” The agent fetches current task text and saved handoff fields
+when you submit; they are not copied into the draft. Existing drafts are preserved;
+nothing is submitted automatically.
 With a selected task it offers **Continue**, **Done**, and **Switch 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
@@ -66,7 +69,7 @@ The footer omits the task ID and state and shows only the first line, truncated
 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 load its current contents.
+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.
@@ -74,9 +77,20 @@ before/after agent activity, and after commands/tools.
 Agent tools:
 
 - `pinote_get`: read the selected task, or an explicit `id`, including its revision.
+  Omitting `id` returns null when this project 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
+  selects it for this project; 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

@@ -1,13 +1,18 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
 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 +63,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,17 +103,32 @@ export default function (pi: ExtensionAPI) {
     }
     return result.stdout;
   };
-  const run = async (argv: string[], signal?: AbortSignal, canRun = () => true) => {
+  const run = async (argv: string[], 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.");
     return invoke(argv, 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);
+    }
+  };
   const selected = async (ctx: ExtensionContext, signal?: AbortSignal) =>
     task(await run(["agent", "selected", "--cwd", ctx.cwd], signal));
 
@@ -261,9 +282,7 @@ export default function (pi: ExtensionAPI) {
         const chosen = requiredTask(await run(["agent", "select", String(id), "--cwd", ctx.cwd], undefined, canAct), id);
         if (!canAct()) return;
         const draft = ctx.ui.getEditorText();
-        const handoff = `Pinote task #${chosen.id} (revision ${chosen.updated_at}).\n` +
-          "Use pinote_get to read current task data and pinote_update to save agent handoff fields.\n" +
-          handoffGuidance + "\n\n" + chosen.markdown;
+        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);
         ctx.ui.notify(`Pinote #${chosen.id} is in progress. Task added to input.`, "info");
       } catch (error) {
@@ -278,22 +297,23 @@ 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 project'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);
-      return toolResult(result);
+      const raw = await run(argv, signal);
+      return toolResult(params.id === undefined ? task(raw) : requiredTask(raw, params.id));
     },
   });
   pi.registerTool({
     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 }),
@@ -304,21 +324,65 @@ 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.");
       }
-      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);
-      } finally {
-        if (pending === operation) pending = undefined;
-        if (alive && generation === epoch) await refresh(ctx);
+      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 selects it for this project. Omitting select leaves the current selection unchanged. Does not refresh the desktop notification.",
+    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.");
+      if (params.select === true && !isAbsolute(ctx.cwd)) throw new Error("Project directory must be absolute before selecting a task.");
+      const argv = ["agent", "add", `--text=${params.text}`];
+      if (params.tag !== undefined) argv.push(`--tag=${params.tag}`);
+      if (params.select === true) argv.push("--cwd", ctx.cwd);
+      return toolResult(await writeTask(ctx, signal, argv, undefined, "0.4.0"));
+    },
+  });
+  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.0",
+  "version": "0.5.0",
   "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);