open-plan-annotator 1.4.1 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.4.1"
+    "version": "1.5.0"
   },
   "plugins": [
     {
       "name": "open-plan-annotator",
       "source": "./",
       "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-      "version": "1.4.1",
+      "version": "1.5.0",
       "author": {
         "name": "ndom91"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "open-plan-annotator",
   "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "author": {
     "name": "ndom91"
   },

package/README.md

@@ -61,6 +61,16 @@ To update, refresh the plugin through OpenCode and restart the app so it reloads
 > [!NOTE]
 > The update mechanism changed significantly in `1.0.20+`: OpenCode now loads the npm package plus a platform runtime package instead of using the old in-place binary updater. If OpenCode appears to be stuck on an older plugin build, clear the cached `open-plan-annotator` entries under `~/.cache/opencode/node_modules/` and restart OpenCode.
 
+### Pi
+
+Install the dedicated Pi package:
+
+```sh
+pi install npm:@open-plan-annotator/pi-extension
+```
+
+The extension package registers a `submit_plan` tool and an `/annotate-plan` command, both of which open the same browser-based plan review UI.
+
 #### Implementation Handoff
 
 By default, after a plan is approved the plugin sends "Proceed with implementation." to a `build` agent. To customize or disable this, create `open-plan-annotator.json` in your project's `.opencode/` directory or globally in `~/.config/opencode/`:

package/opencode/bridge.js

@@ -1,201 +1,27 @@
-import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { existsSync, statSync } from "node:fs";
-import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectPackageManager } from "../shared/packageManager.mjs";
+import { runPlanReviewBinary } from "../shared/planReview.mjs";
 import { resolveRuntimeBinary } from "../shared/runtimeResolver.mjs";
 
-const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
-
-/**
- * @typedef {{
- *   hookSpecificOutput: {
- *     hookEventName: "PermissionRequest",
- *     decision: { behavior: "allow" } | { behavior: "deny", message: string }
- *   }
- * }} HookOutput
- */
-
-/**
- * @param {{ plan: string, sessionId?: string, cwd?: string }} options
- */
-function buildHookPayload(options) {
-  return {
-    session_id: options.sessionId ?? randomUUID(),
-    transcript_path: "",
-    cwd: options.cwd ?? process.cwd(),
-    permission_mode: "default",
-    hook_event_name: "PermissionRequest",
-    tool_name: "ExitPlanMode",
-    tool_use_id: randomUUID(),
-    tool_input: {
-      plan: options.plan,
-    },
-  };
-}
-
-/**
- * @param {string} stdoutText
- * @param {string} stderrText
- * @returns {HookOutput}
- */
-function parseHookOutput(stdoutText, stderrText) {
-  const trimmed = stdoutText.trim();
-  if (!trimmed) {
-    const stderr = stderrText.trim();
-    throw new Error(
-      stderr
-        ? `open-plan-annotator returned empty stdout; stderr: ${stderr}`
-        : "open-plan-annotator returned empty stdout",
-    );
-  }
-
-  try {
-    return validateHookOutput(JSON.parse(trimmed));
-  } catch {
-    const lines = trimmed
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .reverse();
-
-    for (const line of lines) {
-      try {
-        return validateHookOutput(JSON.parse(line));
-      } catch {
-        // ignore and keep searching
-      }
-    }
-
-    throw new Error("open-plan-annotator returned invalid hook JSON");
-  }
-}
-
-/**
- * @param {unknown} value
- * @returns {HookOutput}
- */
-function validateHookOutput(value) {
-  if (!value || typeof value !== "object") {
-    throw new Error("invalid hook output shape");
-  }
-
-  const output = /** @type {HookOutput} */ (value);
-  const decision = output?.hookSpecificOutput?.decision;
-
-  if (!decision || typeof decision !== "object" || typeof decision.behavior !== "string") {
-    throw new Error("missing decision in hook output");
-  }
-
-  if (decision.behavior === "allow") {
-    return output;
-  }
-
-  if (decision.behavior === "deny" && typeof decision.message === "string") {
-    return output;
-  }
-
-  throw new Error("unsupported decision payload");
-}
-
 /**
  * @param {{ plan: string, sessionId?: string, cwd?: string }} options
  */
 export async function runPlanReview(options) {
   const runtime = resolveRuntimeBinary({ parentUrl: import.meta.url });
 
-  const payload = buildHookPayload(options);
-
-  const output = await new Promise((resolve, reject) => {
-    let cwd = options.cwd ?? process.cwd();
-
-    // Guard: ensure cwd is a directory, not a file
-    try {
-      if (existsSync(cwd) && !statSync(cwd).isDirectory()) {
-        cwd = dirname(cwd);
-      }
-    } catch {
-      cwd = PKG_ROOT;
-    }
-
-    // Spawn detached so the binary can outlive this call — it keeps its
-    // HTTP server alive for ~10s after emitting the JSON hook response.
-    const child = spawn(runtime.binaryPath, [], {
-      cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-      env: {
-        ...process.env,
-        OPEN_PLAN_HOST: "opencode",
-        OPEN_PLAN_PKG_MANAGER:
-          process.env.OPEN_PLAN_PKG_MANAGER || detectPackageManager({ installPath: fileURLToPath(import.meta.url) }),
-      },
-      detached: true,
-    });
-
-    let stdout = "";
-    let stderr = "";
-    let resolved = false;
-
-    child.stdout.on("data", (chunk) => {
-      stdout += String(chunk);
-      if (resolved) return;
-
-      // Scan for a complete JSON hook-output line.  Once found, resolve
-      // immediately and let the binary keep running in the background.
-      const lines = stdout.split("\n");
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        try {
-          const parsed = validateHookOutput(JSON.parse(trimmed));
-          resolved = true;
-          child.unref();
-          resolve(parsed);
-          return;
-        } catch {
-          // Not valid hook JSON yet, keep buffering
-        }
-      }
-    });
-
-    child.stderr.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-
-    child.on("error", (error) => {
-      if (!resolved) reject(error);
-    });
-
-    child.on("close", (code, signal) => {
-      if (resolved) return;
-      // Binary exited without producing valid JSON
-      if (signal) {
-        reject(
-          new Error(
-            stderr.trim()
-              ? `open-plan-annotator was terminated by signal ${signal}: ${stderr.trim()}`
-              : `open-plan-annotator was terminated by signal ${signal}`,
-          ),
-        );
-      } else if (code !== 0) {
-        reject(
-          new Error(
-            stderr.trim()
-              ? `open-plan-annotator exited with code ${code}: ${stderr.trim()}`
-              : `open-plan-annotator exited with code ${code}`,
-          ),
-        );
-      } else {
-        reject(new Error("open-plan-annotator exited without producing hook output"));
-      }
-    });
-
-    child.stdin.write(`${JSON.stringify(payload)}\n`);
-    child.stdin.end();
+  const output = await runPlanReviewBinary({
+    binaryPath: runtime.binaryPath,
+    plan: options.plan,
+    sessionId: options.sessionId,
+    cwd: options.cwd,
+    env: {
+      OPEN_PLAN_HOST: "opencode",
+      OPEN_PLAN_PKG_MANAGER: process.env.OPEN_PLAN_PKG_MANAGER || detectPackageManager({ installPath: fileURLToPath(import.meta.url) }),
+    },
+    detached: true,
   });
 
-  const decision = /** @type {HookOutput} */ (output).hookSpecificOutput.decision;
+  const decision = output.hookSpecificOutput.decision;
 
   if (decision.behavior === "allow") {
     return { approved: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -34,6 +34,8 @@
     "shared/runtimeResolver.mjs",
     "shared/updateHints.mjs",
     "shared/versionInfo.mjs",
+    "shared/planReview.mjs",
+    "shared/piExtension.mjs",
     ".claude-plugin/",
     "opencode/bridge.js",
     "opencode/config.js",
@@ -62,19 +64,28 @@
     "postpack": "bun scripts/claude-pack-docs.mjs postpack"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
-    "@types/node": "^25.3.0",
-    "@types/bun": "^1.3.9",
-    "@typescript/native-preview": "^7.0.0-dev.20260224.1"
+    "@biomejs/biome": "^2.4.13",
+    "@types/node": "^25.6.0",
+    "@types/bun": "^1.3.13",
+    "@typescript/native-preview": "^7.0.0-dev.20260430.1",
+    "typebox": "^1.1.37"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.14"
+    "@opencode-ai/plugin": "^1.14.30"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "typebox": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.4.1",
-    "@open-plan-annotator/runtime-darwin-x64": "1.4.1",
-    "@open-plan-annotator/runtime-linux-arm64": "1.4.1",
-    "@open-plan-annotator/runtime-linux-x64": "1.4.1"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.5.0",
+    "@open-plan-annotator/runtime-darwin-x64": "1.5.0",
+    "@open-plan-annotator/runtime-linux-arm64": "1.5.0",
+    "@open-plan-annotator/runtime-linux-x64": "1.5.0"
   },
   "overrides": {
     "uuid": "^14.0.0"

package/shared/piExtension.mjs

@@ -0,0 +1,134 @@
+import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+import { detectPackageManager } from "./packageManager.mjs";
+import { runPlanReviewBinary } from "./planReview.mjs";
+import { resolveRuntimeBinary } from "./runtimeResolver.mjs";
+
+const TOOL_NAME = "submit_plan";
+
+function getSessionId(ctx) {
+  try {
+    return ctx.sessionManager.getSessionId();
+  } catch {
+    return undefined;
+  }
+}
+
+function getLastAssistantText(ctx) {
+  const branch = ctx.sessionManager.getBranch();
+
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (entry.type !== "message") continue;
+
+    const message = entry.message;
+    if (!message || message.role !== "assistant" || !Array.isArray(message.content)) continue;
+
+    const text = message.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("\n")
+      .trim();
+
+    if (text) return text;
+  }
+
+  return undefined;
+}
+
+async function reviewPlan(plan, ctx) {
+  const runtime = resolveRuntimeBinary({ parentUrl: import.meta.url });
+  const result = await runPlanReviewBinary({
+    binaryPath: runtime.binaryPath,
+    plan,
+    sessionId: getSessionId(ctx),
+    cwd: ctx.cwd,
+    env: {
+      OPEN_PLAN_HOST: "pi",
+      OPEN_PLAN_PKG_MANAGER:
+        process.env.OPEN_PLAN_PKG_MANAGER || detectPackageManager({ installPath: fileURLToPath(import.meta.url) }),
+    },
+    detached: true,
+  });
+
+  const decision = result.hookSpecificOutput.decision;
+  return {
+    approved: decision.behavior === "allow",
+    feedback: decision.behavior === "deny" ? decision.message : undefined,
+  };
+}
+
+export function registerPiExtension(pi) {
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: "Annotate Plan",
+    description: "Open the browser-based plan annotation UI and return approval or revision feedback.",
+    promptSnippet: "Use this tool after drafting a plan that needs human review before implementation.",
+    promptGuidelines: [
+      "Call submit_plan when you have a concrete plan in markdown form.",
+      "Include the full plan text, including numbered steps if available.",
+      "Wait for the review result before proceeding with implementation.",
+    ],
+    parameters: Type.Object({
+      plan: Type.String({ description: "The plan markdown to review" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const review = await reviewPlan(params.plan, ctx);
+
+      if (review.approved) {
+        return {
+          content: [{ type: "text", text: "Plan approved. Continue with implementation." }],
+          details: { approved: true },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Plan changes requested:\n\n${review.feedback ?? "No feedback provided."}`,
+          },
+        ],
+        details: { approved: false, feedback: review.feedback ?? null },
+      };
+    },
+  });
+
+  pi.registerCommand("annotate-plan", {
+    description: "Open the plan annotation UI for the latest plan or provided plan text.",
+    handler: async (args, ctx) => {
+      let plan = args.trim();
+
+      if (!plan) {
+        plan = getLastAssistantText(ctx) ?? "";
+      }
+
+      if (!plan && !ctx.hasUI) {
+        ctx.ui.notify("Usage: /annotate-plan <plan markdown> or run it after a plan message.", "warning");
+        return;
+      }
+
+      if (!plan) {
+        const edited = await ctx.ui.editor("Paste plan markdown", "# Plan\n\n1. ");
+        if (!edited?.trim()) {
+          ctx.ui.notify("Plan review cancelled", "info");
+          return;
+        }
+        plan = edited;
+      }
+
+      try {
+        const review = await reviewPlan(plan, ctx);
+        if (review.approved) {
+          ctx.ui.notify("Plan approved.", "success");
+          return;
+        }
+
+        ctx.ui.notify(`Changes requested:\n${review.feedback ?? "No feedback provided."}`, "warning");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Plan review failed: ${message}`, "error");
+      }
+    },
+  });
+}

package/shared/planReview.mjs

@@ -0,0 +1,203 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/**
+ * @typedef {{
+ *   hookSpecificOutput: {
+ *     hookEventName: "PermissionRequest",
+ *     decision: { behavior: "allow" } | { behavior: "deny", message: string }
+ *   }
+ * }} HookOutput
+ */
+
+/**
+ * @param {{ plan: string, sessionId?: string, cwd?: string }} options
+ */
+export function buildHookPayload(options) {
+  return {
+    session_id: options.sessionId ?? randomUUID(),
+    transcript_path: "",
+    cwd: options.cwd ?? process.cwd(),
+    permission_mode: "default",
+    hook_event_name: "PermissionRequest",
+    tool_name: "ExitPlanMode",
+    tool_use_id: randomUUID(),
+    tool_input: {
+      plan: options.plan,
+    },
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {HookOutput}
+ */
+export function validateHookOutput(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("invalid hook output shape");
+  }
+
+  const output = /** @type {HookOutput} */ (value);
+  const decision = output?.hookSpecificOutput?.decision;
+
+  if (!decision || typeof decision !== "object" || typeof decision.behavior !== "string") {
+    throw new Error("missing decision in hook output");
+  }
+
+  if (decision.behavior === "allow") {
+    return output;
+  }
+
+  if (decision.behavior === "deny" && typeof decision.message === "string") {
+    return output;
+  }
+
+  throw new Error("unsupported decision payload");
+}
+
+/**
+ * @param {string} stdoutText
+ * @param {string} stderrText
+ * @returns {HookOutput}
+ */
+export function parseHookOutput(stdoutText, stderrText) {
+  const trimmed = stdoutText.trim();
+  if (!trimmed) {
+    const stderr = stderrText.trim();
+    throw new Error(
+      stderr
+        ? `open-plan-annotator returned empty stdout; stderr: ${stderr}`
+        : "open-plan-annotator returned empty stdout",
+    );
+  }
+
+  try {
+    return validateHookOutput(JSON.parse(trimmed));
+  } catch {
+    const lines = trimmed
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .reverse();
+
+    for (const line of lines) {
+      try {
+        return validateHookOutput(JSON.parse(line));
+      } catch {
+        // keep searching
+      }
+    }
+
+    throw new Error("open-plan-annotator returned invalid hook JSON");
+  }
+}
+
+/**
+ * @param {string | undefined} cwd
+ */
+function resolveSpawnCwd(cwd) {
+  let resolvedCwd = cwd ?? process.cwd();
+
+  try {
+    if (existsSync(resolvedCwd) && !statSync(resolvedCwd).isDirectory()) {
+      resolvedCwd = dirname(resolvedCwd);
+    }
+  } catch {
+    resolvedCwd = PKG_ROOT;
+  }
+
+  return resolvedCwd;
+}
+
+/**
+ * @param {{
+ *   binaryPath: string,
+ *   plan: string,
+ *   sessionId?: string,
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   detached?: boolean,
+ * }} options
+ * @returns {Promise<HookOutput>}
+ */
+export async function runPlanReviewBinary(options) {
+  const payload = buildHookPayload({ plan: options.plan, sessionId: options.sessionId, cwd: options.cwd });
+  const cwd = resolveSpawnCwd(options.cwd);
+
+  return await new Promise((resolve, reject) => {
+    const child = spawn(options.binaryPath, [], {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        ...options.env,
+      },
+      detached: options.detached ?? true,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let resolved = false;
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+      if (resolved) return;
+
+      const lines = stdout.split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        try {
+          const parsed = validateHookOutput(JSON.parse(trimmed));
+          resolved = true;
+          child.unref();
+          resolve(parsed);
+          return;
+        } catch {
+          // Not JSON yet
+        }
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", (error) => {
+      if (!resolved) reject(error);
+    });
+
+    child.on("close", (code, signal) => {
+      if (resolved) return;
+
+      if (signal) {
+        reject(
+          new Error(
+            stderr.trim()
+              ? `open-plan-annotator was terminated by signal ${signal}: ${stderr.trim()}`
+              : `open-plan-annotator was terminated by signal ${signal}`,
+          ),
+        );
+      } else if (code !== 0) {
+        reject(
+          new Error(
+            stderr.trim()
+              ? `open-plan-annotator exited with code ${code}: ${stderr.trim()}`
+              : `open-plan-annotator exited with code ${code}`,
+          ),
+        );
+      } else {
+        reject(new Error("open-plan-annotator exited without producing hook output"));
+      }
+    });
+
+    child.stdin.write(`${JSON.stringify(payload)}\n`);
+    child.stdin.end();
+  });
+}

package/shared/updateMessage.mjs

@@ -7,7 +7,8 @@ export async function buildUpdateMessage(options = {}) {
   const host = options.host ?? process.env.OPEN_PLAN_HOST;
 
   try {
-    const latestVersion = await fetchLatestVersion();
+    const fetchVersion = options.fetchLatestVersion ?? fetchLatestVersion;
+    const latestVersion = await fetchVersion();
     if (currentVersion && isNewerVersion(currentVersion, latestVersion)) {
       return `latest v${latestVersion}; ${buildUpdateInstructions({ host, packageManager, version: latestVersion })}`;
     }