@oisin-ee/pi-todo 0.3.0 → 0.5.0

package/README.md

@@ -42,6 +42,36 @@ Expansion stays open through task updates. Session changes and `/tree` navigatio
 When no task is active, a short status and the shortcut hint remain visible.
 Outside the terminal UI, `/todos` prints the list instead.
 
+## Shared work display
+
+When a compatible pi-wrangle extension is active, its `WORK` strip replaces the standalone todo widget.
+Tasks remain on the current Pi session branch. Wrangle receives read-only snapshots through `pi.events`.
+`/todos` and Alt+T request the shared Todos view. `/todos list` still prints the full list.
+When shared presentation ends, the standalone widget returns without changing task state.
+
+The [version 1 display contract](https://github.com/oisin-ee/wrangle/blob/main/docs/pi-work.md)
+defines the snapshot request, acknowledgement, release, and read-only view events.
+
+## Plannotator plans
+
+With Plannotator external execution, pi-todo continues approved plans in the same session.
+Add this setting to `~/.pi/agent/plannotator.json`:
+
+```json
+{
+  "executionMode": "external"
+}
+```
+
+After approval, the agent reads the current todo list and adds the remaining approved work before implementation.
+It preserves unrelated tasks and completed progress. Free-form plans do not need a special checklist format.
+The todo tool owns progress, persistence, reminders, and the shared work display.
+Plannotator returns to idle and does not maintain a second checklist or require `[DONE:n]` markers.
+
+This integration uses the supported `plannotator:plan-approved` event, verified with Plannotator `0.28.19`.
+It does not import Plannotator internals or change its code.
+Malformed events, a different working directory, or another owner of the `todo` tool stop the handoff with an error.
+
 ## Reminder
 
 When the agent stops with open tasks, pi-todo adds a hidden reminder that lists them and continues the turn.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A todo tool for pi with a Rust core: one active task, state on the session branch.",
   "keywords": [
     "pi-extension",

package/src/index.ts

@@ -1,17 +1,26 @@
-import { ownsTodo, settle, show } from "./lifecycle.ts";
+import { ownsTodo, settle } from "./lifecycle.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PlannotatorHandoff } from "./plannotator.ts";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { TODO_SHORTCUT } from "./widget.ts";
 import { TodoPresentation } from "./presentation.ts";
+import { TodoWork } from "./work.ts";
 import { Type } from "typebox";
+import type { WorkHost } from "./work.ts";
 import { runTodo } from "./tool.ts";
 
-type TodoAPI = Readonly<
-  Pick<
-    ExtensionAPI,
-    "appendEntry" | "getAllTools" | "on" | "registerCommand" | "registerShortcut" | "registerTool"
-  >
->;
+type TodoAPI = WorkHost &
+  Readonly<
+    Pick<
+      ExtensionAPI,
+      | "appendEntry"
+      | "getAllTools"
+      | "on"
+      | "registerCommand"
+      | "registerShortcut"
+      | "registerTool"
+      | "sendMessage"
+    >
+  >;
 
 const items = Type.Immutable(
     Type.Array(Type.String(), { description: "For init or append: tasks, in order." }),
@@ -32,13 +41,10 @@ const items = Type.Immutable(
  * @param {TodoAPI} pi The extension API methods used here.
  */
 export default function piTodo(pi: TodoAPI): void {
-  const presentation = new TodoPresentation();
-  pi.registerShortcut(TODO_SHORTCUT, {
-    description: "Expand or collapse upcoming and done todos.",
-    handler(ctx) {
-      presentation.toggle(pi, ctx);
-    },
-  });
+  const handoff = new PlannotatorHandoff(pi),
+    presentation = new TodoPresentation(),
+    work = new TodoWork(pi, presentation);
+  work.register(pi);
   pi.registerTool({
     description:
       "Keep the session todo list. Tasks are addressed by their exact content. One task is active; the next open task starts when it closes.",
@@ -49,6 +55,7 @@ export default function piTodo(pi: TodoAPI): void {
         },
         branch: () => ctx.sessionManager.getBranch(),
       });
+      work.publish(ctx);
       presentation.refresh(ctx);
       return result;
     },
@@ -59,23 +66,18 @@ export default function piTodo(pi: TodoAPI): void {
   });
   pi.on("session_start", (_event, ctx) => {
     presentation.start(pi, ctx);
+    work.start(ctx);
+    handoff.start(ctx);
+  });
+  pi.on("session_shutdown", () => {
+    handoff.stop();
+    work.stop();
   });
   pi.on("session_tree", (_event, ctx) => {
     if (ownsTodo(pi)) {
+      work.publish(ctx);
       presentation.reset(ctx);
     }
   });
   pi.on("agent_before_settle", (event, ctx) => settle(pi, event, ctx));
-  pi.registerCommand("todos", {
-    description: "Toggle todo details; /todos list prints the full branch list.",
-    async handler(args, ctx) {
-      if (ownsTodo(pi)) {
-        if (args.trim() === "list" || ctx.mode !== "tui") {
-          show(ctx);
-        } else {
-          presentation.toggle(pi, ctx);
-        }
-      }
-    },
-  });
 }

package/src/plannotator.ts

@@ -0,0 +1,107 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TodoContext } from "./lifecycle.ts";
+import type { WorkHost } from "./work.ts";
+import { ownsTodo } from "./lifecycle.ts";
+
+/** The supported Plannotator external-execution event. */
+interface ApprovedPlan {
+  readonly cwd: string;
+  readonly planFilePath: string;
+  readonly planContent: string;
+  readonly feedback?: string;
+}
+
+type PlanHost = WorkHost & Readonly<Pick<ExtensionAPI, "sendMessage">>;
+type PlanContext = TodoContext & { readonly cwd: string };
+
+/**
+ * Validates the event before it enters the model context.
+ * @param {unknown} value The shared event payload.
+ * @returns {boolean} Whether the required handoff fields are present.
+ */
+const isApprovedPlan = (value: unknown): value is ApprovedPlan =>
+    typeof value === "object" &&
+    value !== null &&
+    "cwd" in value &&
+    typeof value.cwd === "string" &&
+    "planFilePath" in value &&
+    typeof value.planFilePath === "string" &&
+    value.planFilePath.trim() !== "" &&
+    "planContent" in value &&
+    typeof value.planContent === "string" &&
+    value.planContent.trim() !== "" &&
+    (!("feedback" in value) || value.feedback === undefined || typeof value.feedback === "string"),
+  /**
+   * Continues the approved plan through the existing todo tool, not a second parser or store.
+   * @param {ApprovedPlan} plan The approved document and reviewer feedback.
+   * @returns {string} Instructions followed by the exact handoff data.
+   */
+  continuation = (plan: ApprovedPlan): string =>
+    [
+      "The user approved this plan in Plannotator. Continue execution in this session.",
+      "Use the todo tool as the only task tracker. Do not maintain Plannotator [DONE:n] markers.",
+      "First call todo with op=view to inspect the current branch list.",
+      "Before implementation, represent the approved plan's remaining work in that list.",
+      "If the list is empty, call todo with op=init and the remaining approved tasks in order.",
+      "Otherwise, reuse matching tasks and append missing tasks. Preserve unrelated work and completed progress.",
+      "If approved work remains, select its next open task with op=start. Never restart a completed task just because the plan was approved again.",
+      "If no approved work remains, report completion without changing tasks. Otherwise, update tasks with op=done or op=drop as work proceeds.",
+      "Resolve a relative planFilePath against cwd. The approved document and reviewer feedback follow as JSON:",
+      JSON.stringify({
+        cwd: plan.cwd,
+        feedback: plan.feedback,
+        planContent: plan.planContent,
+        planFilePath: plan.planFilePath,
+      }),
+    ].join("\n");
+
+/** Owns the approval subscription, never the todo list or execution progress. */
+class PlannotatorHandoff {
+  readonly #host: PlanHost;
+  #unsubscribe: (() => void) | undefined;
+
+  /**
+   * Keeps the supported event bus and conversation API.
+   * @param {PlanHost} host The Pi methods used by the handoff.
+   */
+  public constructor(host: PlanHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Subscribes with the current session context after startup or replacement.
+   * @param {PlanContext} ctx The current branch and working directory.
+   */
+  public start(ctx: PlanContext): void {
+    this.stop();
+    this.#unsubscribe = this.#host.events.on(
+      "plannotator:plan-approved",
+      (value: unknown): void => {
+        if (!isApprovedPlan(value)) {
+          ctx.ui.notify("pi-todo: Invalid Plannotator approval. No execution started.", "error");
+        } else if (value.cwd !== ctx.cwd) {
+          ctx.ui.notify(
+            "pi-todo: The approved plan belongs to another working directory. No execution started.",
+            "error",
+          );
+        } else if (ownsTodo(this.#host)) {
+          this.#host.sendMessage(
+            { content: continuation(value), customType: "todo-plan-approved", display: true },
+            { deliverAs: "followUp", triggerTurn: true },
+          );
+        } else {
+          ctx.ui.notify("pi-todo: Another extension owns todo. No execution started.", "error");
+        }
+      },
+    );
+  }
+
+  /** Removes the previous session's listener before replacement or shutdown. */
+  public stop(): void {
+    this.#unsubscribe?.();
+    this.#unsubscribe = undefined;
+  }
+}
+
+export { PlannotatorHandoff };
+export type { PlanContext, PlanHost };

package/src/presentation.ts

@@ -4,13 +4,16 @@ import { ownsTodo, replay, start } from "./lifecycle.ts";
 /** Owns transient expansion for one extension instance, never task state. */
 class TodoPresentation {
   #expanded = false;
+  #external = false;
 
   /**
    * Replays current branch tasks without changing expansion.
    * @param {TodoContext} ctx Current branch and UI.
    */
   public refresh(ctx: TodoContext): void {
-    replay(ctx, this.#expanded);
+    if (!this.#external) {
+      replay(ctx, this.#expanded);
+    }
   }
 
   /**
@@ -29,9 +32,28 @@ class TodoPresentation {
    */
   public start(pi: TodoHost, ctx: TodoContext): void {
     this.#expanded = false;
+    this.#external = false;
     start(pi, ctx);
   }
 
+  /**
+   * Yields only this extension's widget to an acknowledged work presenter.
+   * @param {TodoContext} ctx Current terminal UI.
+   */
+  public claim(ctx: TodoContext): void {
+    this.#external = true;
+    ctx.ui.setWidget("pi-todo", undefined);
+  }
+
+  /**
+   * Restores the standalone view without changing task state.
+   * @param {TodoContext} ctx Current terminal UI.
+   */
+  public release(ctx: TodoContext): void {
+    this.#external = false;
+    this.refresh(ctx);
+  }
+
   /**
    * Reveals or hides secondary groups without writing session state.
    * @param {TodoHost} pi Registered tool metadata.

package/src/work.ts

@@ -0,0 +1,230 @@
+import type { TodoContext, TodoHost } from "./lifecycle.ts";
+import { ownsTodo, show } from "./lifecycle.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { TODO_SHORTCUT } from "./widget.ts";
+import type { TodoPresentation } from "./presentation.ts";
+import { latestSnapshot } from "./state.ts";
+import { parse } from "./wasm.ts";
+
+interface WorkHost extends TodoHost {
+  readonly events: Readonly<ExtensionAPI["events"]>;
+}
+
+type WorkCommands = Readonly<Pick<ExtensionAPI, "registerCommand" | "registerShortcut">>;
+const protocolVersion = 1,
+  initialRevision = 0;
+
+interface WorkContext extends TodoContext {
+  readonly sessionManager: TodoContext["sessionManager"] & {
+    readonly getSessionId: () => string;
+    readonly getLeafId: () => string | null;
+  };
+}
+
+/** The identity of one work presenter requesting this provider's snapshot. */
+interface Presenter {
+  readonly presenter: string;
+  readonly request: string;
+  readonly version: typeof protocolVersion;
+}
+
+/**
+ * Checks a presentation request without trusting an extension's event payload.
+ * @param {unknown} value Event payload.
+ * @returns {boolean} Whether the envelope uses the supported protocol.
+ */
+const isPresenter = (value: unknown): value is Presenter =>
+  typeof value === "object" &&
+  value !== null &&
+  "version" in value &&
+  value.version === protocolVersion &&
+  "presenter" in value &&
+  typeof value.presenter === "string" &&
+  "request" in value &&
+  typeof value.request === "string";
+
+/** Publishes validated branch data; presentation claims never write task state. */
+class TodoWork {
+  readonly #host: WorkHost;
+  readonly #presentation: Readonly<TodoPresentation>;
+  #context: WorkContext | undefined;
+  #publisher = "";
+  #revision = initialRevision;
+  #presenter: Presenter | undefined;
+  #claimed = false;
+  #subscriptions: (() => void)[] = [];
+
+  /**
+   * Keeps the event bus and the existing standalone presentation owner.
+   * @param {WorkHost} host Pi event bus and tool ownership.
+   * @param {Readonly<TodoPresentation>} presentation Standalone display owner.
+   */
+  public constructor(host: WorkHost, presentation: Readonly<TodoPresentation>) {
+    this.#host = host;
+    this.#presentation = presentation;
+  }
+
+  /**
+   * Registers view entrypoints with a shared or standalone presentation target.
+   * @param {WorkCommands} commands Pi command registration.
+   */
+  public register(commands: WorkCommands): void {
+    commands.registerShortcut(TODO_SHORTCUT, {
+      description: "Show todo details.",
+      handler: (ctx): void => {
+        this.#toggle(ctx);
+      },
+    });
+    commands.registerCommand("todos", {
+      description: "Show todo details; /todos list prints the full branch list.",
+      handler: async (args, ctx): Promise<void> => {
+        if (ownsTodo(this.#host)) {
+          if (args.trim() === "list" || ctx.mode !== "tui") {
+            show(ctx);
+          } else {
+            this.#toggle(ctx);
+          }
+        }
+      },
+    });
+  }
+
+  /**
+   * Opens the shared view or toggles the existing standalone view.
+   * @param {TodoContext} ctx Current UI and branch.
+   */
+  #toggle(ctx: TodoContext): void {
+    if (!this.open()) {
+      this.#presentation.toggle(this.#host, ctx);
+    }
+  }
+
+  /**
+   * Subscribes only when this extension owns the terminal todo tool.
+   * @param {WorkContext} ctx Current Pi session.
+   */
+  public start(ctx: WorkContext): void {
+    this.stop();
+    if (ctx.mode !== "tui" || !ownsTodo(this.#host)) {
+      return;
+    }
+    this.#context = ctx;
+    this.#publisher = crypto.randomUUID();
+    this.#revision = initialRevision;
+    this.#subscriptions = [
+      this.#host.events.on("oisin.work.request", (value: unknown): void => {
+        if (isPresenter(value)) {
+          this.#presenter = value;
+          if (this.#context !== undefined) {
+            this.publish(this.#context);
+          }
+        }
+      }),
+      this.#host.events.on("oisin.work.claim", (value: unknown): void => {
+        this.#claim(value);
+      }),
+      this.#host.events.on("oisin.work.release", (value: unknown): void => {
+        if (this.#matches(value)) {
+          this.#release();
+        }
+      }),
+    ];
+    this.#host.events.emit("oisin.todo.ready", { publisher: this.#publisher, version: 1 });
+  }
+
+  /**
+   * Publishes the actual branch snapshot after tool or branch changes.
+   * @param {WorkContext} ctx Current Pi session, never a stored file's last entry.
+   */
+  public publish(ctx: WorkContext): void {
+    if (this.#context === undefined || this.#presenter === undefined) {
+      return;
+    }
+    this.#context = ctx;
+    this.#revision += 1;
+    const list = parse(latestSnapshot(ctx.sessionManager.getBranch()));
+    this.#host.events.emit("oisin.todo.snapshot", {
+      branch: ctx.sessionManager.getLeafId(),
+      presenter: this.#presenter.presenter,
+      publisher: this.#publisher,
+      request: this.#presenter.request,
+      revision: this.#revision,
+      session: ctx.sessionManager.getSessionId(),
+      tasks: list.tasks,
+      version: 1,
+    });
+  }
+
+  /**
+   * Requests the read-only Todos view without changing expansion or task state.
+   * @returns {boolean} Whether a shared presenter owns the view.
+   */
+  public open(): boolean {
+    if (!this.#claimed || this.#presenter === undefined) {
+      return false;
+    }
+    this.#host.events.emit("oisin.work.open", {
+      presenter: this.#presenter.presenter,
+      request: this.#presenter.request,
+      version: 1,
+      view: "todos",
+    });
+    return true;
+  }
+
+  /** Releases subscriptions and tells the presenter to discard this provider. */
+  public stop(): void {
+    for (const unsubscribe of this.#subscriptions) {
+      unsubscribe();
+    }
+    this.#subscriptions = [];
+    if (this.#context !== undefined) {
+      this.#host.events.emit("oisin.todo.stop", { publisher: this.#publisher, version: 1 });
+    }
+    this.#release();
+    this.#context = undefined;
+  }
+
+  /**
+   * Accepts only an acknowledgement of the latest published snapshot.
+   * @param {unknown} value Claim envelope.
+   */
+  #claim(value: unknown): void {
+    if (
+      this.#matches(value) &&
+      "publisher" in value &&
+      value.publisher === this.#publisher &&
+      "revision" in value &&
+      value.revision === this.#revision &&
+      this.#context !== undefined
+    ) {
+      this.#claimed = true;
+      this.#presentation.claim(this.#context);
+    }
+  }
+
+  /**
+   * Matches a live presenter, excluding delayed messages from replaced sessions.
+   * @param {unknown} value Event envelope.
+   * @returns {boolean} Whether the envelope belongs to the current presenter.
+   */
+  #matches(value: unknown): value is Presenter {
+    return (
+      isPresenter(value) &&
+      value.presenter === this.#presenter?.presenter &&
+      value.request === this.#presenter.request
+    );
+  }
+
+  /** Restores the standalone display when shared presentation ends. */
+  #release(): void {
+    this.#claimed = false;
+    this.#presenter = undefined;
+    if (this.#context !== undefined) {
+      this.#presentation.release(this.#context);
+    }
+  }
+}
+
+export { TodoWork };
+export type { WorkContext, WorkHost };