pi-note 0.6.0 → 0.7.1

package/README.md

@@ -1,12 +1,13 @@
 # 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/add/tag tools.
+in Pi: selected-task footer status, `/pi-note`, and agent current-task read/update,
+add, and tag-listing 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). Add and tag need **pinote 0.4.0+**.
+Requires 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
@@ -55,11 +56,11 @@ standalone `settings/pi/extensions/pinote.ts` entry if installed; load only one
 
 ## Use
 
-`/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.
+`/pi-note` picks a task, marks it in progress, and adds this prompt to the editor:
+“Read the current Pinote task. Summarize your understanding, but don’t start work yet.”
+The agent fetches current task text and saved handoff fields when you submit;
+they are not copied into the draft. The prompt asks for a summary, not implementation.
+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
@@ -73,7 +74,7 @@ Resume restores that session's task; a new session starts unselected and does no
 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
+to insert the same read-and-summarize 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
@@ -82,16 +83,20 @@ command is not this session memory.
 
 Agent tools:
 
-- `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 or tag. If another process changed the task, read again before retrying.
+- `pinote_get_current`: read this session's selected task, including its revision.
+  Takes no arguments; returns null when this session has no selected task.
+- `pinote_update_current`: supply `expected_updated_at` from that read and arbitrary
+  `set` label/value pairs or `remove` labels. Updates the selected task only, with no
+  ID argument. Updates merge fields, never replace the task text or tag. Fails if
+  no task is selected or the selection changes during the operation. 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`.
+
+Version 0.7.0 replaces `pinote_get`/`pinote_update` with these current-task tools
+and removes `pinote_tag`, without aliases. Agents cannot read/update tasks by ID
+or retag existing tasks; use `/pi-note` to select an existing task.
 
 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
@@ -142,7 +147,7 @@ off the footer unless named in `Bar`.
 
 ### PR merge watcher
 
-Set `PR` with `pinote_update` to one `https://github.com/owner/repo/pull/123` URL
+Set `PR` with `pinote_update_current` to one `https://github.com/owner/repo/pull/123` URL
 or Markdown link. The footer adds a clickable, link-coloured **PR #123**, without
 status text. Other hosts, multiple links, and prose are not watched.
 

package/index.ts

@@ -10,7 +10,7 @@ import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLe
 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. To show another footer field, set its Markdown value and append its label to Bar, one label per line. Links in that text are clickable. Do not list PR in Bar. Remove the field and its Bar line to drop it. Notes stay off the footer unless named in Bar.";
 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.",
+  "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. Tags are set when creating tasks with pinote_add; agent tools cannot retag existing tasks. Do not use pinote_update_current for tags or task text.",
 ];
 type Task = {
   id: number;
@@ -24,7 +24,6 @@ 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 idSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
 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> =>
@@ -118,6 +117,7 @@ export default function (pi: ExtensionAPI) {
   };
   const writeTask = async (
     ctx: ExtensionContext, signal: AbortSignal | undefined, argv: string[], id?: number, minimum = "0.3.0",
+    canRun = () => true,
   ) => {
     if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
     const operation = Symbol();
@@ -125,7 +125,7 @@ export default function (pi: ExtensionAPI) {
     const generation = epoch;
     refreshSerial++;
     try {
-      return requiredTask(await run(argv, signal, () => alive && generation === epoch, minimum), id);
+      return requiredTask(await run(argv, signal, () => alive && generation === epoch && canRun(), minimum), id);
     } finally {
       if (pending === operation) pending = undefined;
       if (alive && generation === epoch) await refresh(ctx);
@@ -162,7 +162,8 @@ export default function (pi: ExtensionAPI) {
   };
   const selected = async (_ctx: ExtensionContext, signal?: AbortSignal) => {
     const generation = epoch;
-    const canUse = () => alive && generation === epoch;
+    const branch = branchEpoch;
+    const canUse = () => alive && generation === epoch && branch === branchEpoch;
     await ensureCLI(signal, canUse);
     return currentTask(signal, canUse);
   };
@@ -348,7 +349,7 @@ export default function (pi: ExtensionAPI) {
         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.`;
+        const handoff = "Read the current Pinote task. Summarize your understanding, but don’t start work yet.";
         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) {
@@ -361,38 +362,44 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "pinote_get",
-    label: "Pinote get",
+    name: "pinote_get_current",
+    label: "Pinote get current",
     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 result = params.id === undefined
-        ? await selected(ctx, signal)
-        : requiredTask(await run(["agent", "get", String(params.id)], signal), params.id);
-      return toolResult(result);
+    description: "Read this session's current pinote task and its Markdown agent fields/revision. Returns null when none is selected. No ID argument. Use the returned updated_at for pinote_update_current.",
+    parameters: Type.Object({}, { additionalProperties: false }),
+    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      return toolResult(await selected(ctx, signal));
     },
   });
   pi.registerTool({
-    name: "pinote_update",
-    label: "Pinote update",
+    name: "pinote_update_current",
+    label: "Pinote update current",
     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 PR #N in the footer and watch for merge confirmation in interactive Pi. Set Bar to newline-separated field labels to show those Markdown fields in the footer; links in the text are clickable. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task or change its tag.",
+    description: "Patch arbitrary agent handoff fields on this session's current pinote task. No ID argument. Read first with pinote_get_current; pass its updated_at as expected_updated_at. Fails when no task is selected or the selection changes during the operation. 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 PR #N in the footer and watch for merge confirmation in interactive Pi. Set Bar to newline-separated field labels to show those Markdown fields in the footer; links in the text are clickable. 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 }),
       set: Type.Optional(Type.Record(Type.String(), Type.String())),
       remove: Type.Optional(Type.Array(Type.String())),
-    }),
+    }, { additionalProperties: false }),
     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 (!text(params.expected_updated_at) || !params.expected_updated_at.trim()) {
+        throw new Error("expected_updated_at is required; read the current task first.");
       }
-      const argv = ["agent", "update", String(params.id), "--expected-updated-at", params.expected_updated_at,
+      const generation = epoch;
+      const branch = branchEpoch;
+      const id = selectedId;
+      const canRun = () => alive && generation === epoch && branch === branchEpoch && selectedId === id;
+      const current = await selected(ctx, signal);
+      if (!canRun()) throw new Error("Pinote operation cancelled: the session or selected task changed.");
+      if (!current) throw new Error("No selected pinote task. Select one with /pi-note first.");
+      const argv = ["agent", "update", String(current.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));
+      const updated = await writeTask(ctx, signal, argv, current.id, "0.3.0", canRun);
+      if (!canRun()) {
+        throw new Error("Pinote operation cancelled: the session or selected task changed. The write may have committed; read the current task before retrying.");
+      }
+      return toolResult(updated);
     },
   });
   pi.registerTool({
@@ -444,25 +451,4 @@ export default function (pi: ExtensionAPI) {
       }
     },
   });
-  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.6.0",
+  "version": "0.7.1",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",