@agent-plan/pi-adapter 0.2.5 → 0.2.7

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AA+xBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA8vF9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AA00BtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAqxF9D"}

package/dist/index.js

@@ -165,6 +165,24 @@ async function maybeHealStatuses(st) {
 function normalizeLanguagePref(value) {
     return value?.trim() ?? "";
 }
+// Safety net: ctx.ui.input() can hang forever when the extension is loaded from
+// an NPM-installed package (the prompt never renders, the await never resolves,
+// and Pi freezes). Race the prompt against a timeout; on timeout, fall back to the
+// empty answer (treated as "no / this session only" by the gating logic) and notify
+// the user how to enable manually. This preserves the interactive prompt for the
+// working case while guaranteeing session_start can never block Pi permanently.
+const PROMPT_TIMEOUT_MS = 20000;
+async function safeInput(ctx, prompt) {
+    try {
+        return await Promise.race([
+            ctx.ui.input(prompt),
+            new Promise((resolve) => setTimeout(() => resolve("__PLANNER_PROMPT_TIMEOUT__"), PROMPT_TIMEOUT_MS)),
+        ]);
+    }
+    catch {
+        return "";
+    }
+}
 async function ensureProjectLanguagePreferences(st) {
     const project = await st.loadProject();
     const contentLanguage = normalizeLanguagePref(project.contentLanguage);
@@ -429,6 +447,24 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         : inferredRecentChanges.length > 0
             ? inferredRecentChanges.map((entry) => `- ${entry}`)
             : ["- No recent activity recorded"];
+    // Auto-derived: all task statuses for the current phase, so a resuming agent
+    // sees the full picture (not just the single in-progress task).
+    const currentPhaseTaskLines = currentPhase && currentPhase.tasks.length > 0
+        ? [...currentPhase.tasks]
+            .sort((a, b) => a.number - b.number || a.createdAt.localeCompare(b.createdAt))
+            .map((task) => `- ${statusIcon(task.status)} \`${task.id}\` — ${task.title} (${task.status})`)
+        : [];
+    // Caller-supplied rich context sections (locked design decisions,
+    // architecture, mode/state flows, plugin/API contracts, data mappings,
+    // known gaps, ...) injected between "What was being done" and "How to resume".
+    const extraSectionLines = (overrides?.extraSections ?? []).flatMap((section) => [
+        "",
+        `## ${section.heading}`,
+        section.body,
+    ]);
+    const autoCurrentTaskSection = currentPhaseTaskLines.length > 0
+        ? ["", `## Current Task Statuses (phase ${currentPhase.id})`, ...currentPhaseTaskLines]
+        : [];
     return [
         "# Handoff",
         "",
@@ -448,6 +484,8 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         "",
         "## What was being done",
         whatWasBeingDone || "No additional execution notes were captured.",
+        ...extraSectionLines,
+        ...autoCurrentTaskSection,
         "",
         "## How to resume",
         howToResume,
@@ -791,7 +829,7 @@ export default function planPiExtension(pi) {
                 }
                 else {
                     try {
-                        const ans = await ctx.ui.input("Planner detected in this project. Enable the planner extension? (y)es / (n)o / (a)lways / n(e)ver)");
+                        const ans = await safeInput(ctx, "Planner detected in this project. Enable the planner extension? (y)es / (n)o / (a)lways / n(e)ver)");
                         const normalized = ans?.trim().toLowerCase() ?? "";
                         if (["a", "always", "sempre"].includes(normalized)) {
                             enablePlanner = true;
@@ -865,7 +903,9 @@ export default function planPiExtension(pi) {
                 await st.ensureStructureOrdering().catch(() => { });
                 // Reconcile derived statuses once on startup: backfills any drift from
                 // manual edits, pre-fix data, or tools that bypassed the rollup.
-                await st.syncStatuses().catch(() => { });
+                // Uses maybeHealStatuses (idempotent via healedStatusRoots guard) so the
+                // later call below and before_agent_start don't re-run it (startup dedup).
+                await maybeHealStatuses(st).catch(() => { });
                 // Decide whether to start the web UI based on persisted prefs or prompt.
                 let startWeb = false;
                 if (project?.plannerAutoStartWeb) {
@@ -876,7 +916,7 @@ export default function planPiExtension(pi) {
                 }
                 else if (server === null) {
                     try {
-                        const ans = await ctx.ui.input("Start the planner web UI? (y)es / (n)o / (a)lways / n(e)ver)");
+                        const ans = await safeInput(ctx, "Start the planner web UI? (y)es / (n)o / (a)lways / n(e)ver)");
                         const normalized = ans?.trim().toLowerCase() ?? "";
                         if (["a", "always", "sempre"].includes(normalized)) {
                             startWeb = true;
@@ -917,13 +957,19 @@ export default function planPiExtension(pi) {
                 const url = server?.url ?? "Starting server...";
                 ctx.ui.notify(`Planner enabled. Dashboard: ${url}\nAnalyzing project state and preparing resume summary...`, "info");
                 await ensureProjectLanguagePreferences(st).catch(() => null);
-                await maybeHealStatuses(st).catch(() => { });
+                // (maybeHealStatuses already ran above — skipped here thanks to the guard.)
                 // Background cleanup of orphan .bak/.tmp.* files (non-blocking)
                 st.cleanupOrphanBackups().catch(() => { });
                 const handoff = await st.loadHandoff().catch(() => null);
                 if (handoff?.content) {
                     ctx.ui.notify(`Handoff detected at .planner/HANDOFF.md (updated ${handoff.updatedAt}). It will be loaded automatically when the agent starts.`, "info");
                 }
+                // Mark heavy init done so before_agent_start doesn't re-run migration,
+                // status healing, and language prefs on the first turn (startup dedup:
+                // all of these already ran in this session_start block). refreshResume is
+                // safe to skip here because the per-turn context builder falls back to
+                // loadResume() ?? refreshResume() when building the system prompt.
+                plannerHeavyInitDone = true;
                 pi.sendMessage({
                     customType: "planner-resume-trigger",
                     content: "Emit the mandatory planner startup resume summary now.",
@@ -2748,11 +2794,15 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_write_handoff",
         label: "Plan Write Handoff",
-        description: "Write or refresh the canonical .planner/HANDOFF.md document.",
+        description: "Write or refresh the canonical .planner/HANDOFF.md document. Capture full design context, not just operational resume steps: pass extraSections with locked decisions, architecture (with file:line refs), mode/state flows, plugin/API contracts, data mappings, files touched, and known gaps so a resuming agent doesn't re-discover decisions already made.",
         parameters: Type.Object({
             reason: Type.Optional(Type.String({ description: "Why the handoff is being written" })),
             whatWasBeingDone: Type.Optional(Type.String({ description: "Optional override for the current work summary" })),
             howToResume: Type.Optional(Type.String({ description: "Optional override for resume instructions" })),
+            extraSections: Type.Optional(Type.Array(Type.Object({
+                heading: Type.String({ description: "Section heading (without the leading ## markers)" }),
+                body: Type.String({ description: "Markdown body of the section. Use file:line refs, IDs, and concrete mappings." }),
+            }), { description: "Rich context sections injected between 'What was being done' and 'How to resume'. Use for: Locked Design Decisions ({id,title,decision,rationale}), Architecture (new modules with file:line), Mode/State Flow (textual diagrams), Plugin/API Contracts, Data Mappings, Files Touched (new/modified/planner), Known Gaps. Maximize the design context a resuming agent needs." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2761,6 +2811,13 @@ export default function planPiExtension(pi) {
             await writeProjectHandoff(st, params.reason?.trim() || "manual tool handoff", {
                 ...(params.whatWasBeingDone?.trim() ? { whatWasBeingDone: params.whatWasBeingDone.trim() } : {}),
                 ...(params.howToResume?.trim() ? { howToResume: params.howToResume.trim() } : {}),
+                ...(params.extraSections && params.extraSections.length > 0
+                    ? {
+                        extraSections: params.extraSections
+                            .map((section) => ({ heading: section.heading?.trim() ?? "", body: section.body ?? "" }))
+                            .filter((section) => section.heading),
+                    }
+                    : {}),
             });
             const handoff = await st.loadHandoff();
             return { content: [{ type: "text", text: "Wrote .planner/HANDOFF.md" }], details: handoff ?? {} };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/pi-adapter",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "private": false,
   "description": "Pi agent extension for Agent Plan — structured project planning in .planner/",
   "keywords": [
@@ -25,11 +25,6 @@
       "."
     ]
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && rm -f dist/.tsbuildinfo",
-    "build:full": "pnpm build && ../../scripts/copy-web-ui.sh",
-    "check": "tsc -p tsconfig.json --noEmit"
-  },
   "dependencies": {
     "@agent-plan/core": "^0.2.0",
     "@agent-plan/server": "^0.2.0",
@@ -39,5 +34,10 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",
     "@earendil-works/pi-ai": "^0.74.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && rm -f dist/.tsbuildinfo",
+    "build:full": "pnpm build && ../../scripts/copy-web-ui.sh",
+    "check": "tsc -p tsconfig.json --noEmit"
   }
-}
+}