@agent-plan/pi-adapter 0.2.12 → 0.2.15

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;AA8yBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAkrF9D"}
+{"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+yBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAgyF9D"}

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 import { Type } from "typebox";
 import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation } from "@agent-plan/core";
-import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, normalizeSlug } from "@agent-plan/core/naming";
+import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -72,6 +72,7 @@ let startupResumePromptPending = false;
 let startupResumeSummaryPending = false;
 let plannerHeavyInitDone = false; // runs migrate/heal/refreshResume once per session, not every turn
 let startupResumeSummaryText = "";
+let startupResumeSummaryTimer = null;
 let contextBlockCache = ""; // cached before_agent_start context; rebuilt only when plan changes
 let contextBlockDirty = true; // build on first turn; invalidated by write notify hook
 let editedThisTurn = false; // tracks edit/write activity for the task_complete reminder
@@ -861,18 +862,31 @@ export default function planPiExtension(pi) {
             return;
         if (event.message.role !== "assistant")
             return;
-        const hasVisibleText = event.message.content.some((item) => item.type === "text" && Boolean(item.text?.trim()));
-        if (!hasVisibleText)
+        const visibleText = event.message.content
+            .filter((item) => item.type === "text")
+            .map((item) => item.text ?? "")
+            .join("");
+        if (!visibleText.trim())
             return;
-        startupResumeSummaryPending = false;
-        const summaryText = startupResumeSummaryText.trim();
-        startupResumeSummaryText = "";
-        if (!summaryText)
+        // Dedupe: if the agent already printed the address, don't double-append.
+        if (visibleText.includes("🌐 Web UI:"))
             return;
+        // Append the web address to EVERY assistant text message during the recap
+        // turn (template: "{agent_summary}\n\n{web_address}"). We intentionally do
+        // NOT consume the flag here: the recap turn can span several assistant
+        // messages (tool calls + final summary), and we must guarantee the address
+        // lands on the final summary the user actually reads. The flag is cleared
+        // at the start of the next turn (before_agent_start) plus a safety timeout.
+        const webServer = server;
+        const localUrl = webServer?.localUrl ?? webServer?.url ?? "";
+        if (!localUrl)
+            return;
+        const lanUrl = webServer?.lanUrl ?? "";
+        const urlLine = `\n\n🌐 Web UI: ${localUrl}${lanUrl ? ` — LAN: ${lanUrl}` : ""}`;
         return {
             message: {
                 ...event.message,
-                content: [{ type: "text", text: summaryText }],
+                content: [...event.message.content, { type: "text", text: urlLine }],
             },
         };
     });
@@ -906,6 +920,12 @@ export default function planPiExtension(pi) {
         // git pull, build, test, ls, etc. always work.
         if (event.toolName !== "edit" && event.toolName !== "write")
             return;
+        // Planner-internal writes (.planner/HANDOFF.md, resume.json, generated plan
+        // files, etc.) are planner operations, NOT code edits. They never require a
+        // task in-progress — skip the guard so the handoff can always be written.
+        const targetPath = String(event.input?.path ?? event.input?.filePath ?? "");
+        if (targetPath && (targetPath.includes("/.planner/") || targetPath.includes("\\.planner\\") || targetPath.startsWith(".planner/")))
+            return;
         const st = loadStore(ctx);
         if (!(await st.exists().catch(() => false)))
             return;
@@ -1802,8 +1822,7 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Aborted", "warning");
                     return;
                 }
-                const shortName = title.trim().toLowerCase()
-                    .replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
+                const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
                 const taskNum = phase.tasks.length + 1;
                 const taskId = createTaskId();
                 const now = nowISO();
@@ -1976,8 +1995,7 @@ export default function planPiExtension(pi) {
                         return;
                     }
                     if (normalizedStatus === "in-progress" && existsSync(join(st.root, "HANDOFF.md"))) {
-                        ctx.ui.notify("🚨 HYGIENE VIOLATION: A pending handoff file exists at .planner/HANDOFF.md. You MUST read and delete it before you can move a task to in-progress.", "error");
-                        return;
+                        ctx.ui.notify("ℹ️  A handoff exists at .planner/HANDOFF.md — read it for context, then delete it with /planner handoff clear (or plan_delete_handoff) when no longer needed. Proceeding with the status change.", "info");
                     }
                     applyTaskLifecycleDates(task, normalizedStatus, now);
                 }
@@ -2018,10 +2036,12 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
                 }
-                // Hygiene Gate: block starting work if a pending handoff exists.
+                // Hygiene notice (non-blocking): surface an existing handoff but never
+                // block task_start — the handoff is a captured-context artifact, not a
+                // lock (a small modification after writing a handoff should start without
+                // forcing deletion, which would lose context).
                 if (existsSync(join(st.root, "HANDOFF.md"))) {
-                    ctx.ui.notify("🚨 HYGIENE VIOLATION: A pending handoff file exists at .planner/HANDOFF.md. You MUST read and delete it before you can officially start a task.", "error");
-                    return;
+                    ctx.ui.notify("ℹ️  A handoff exists at .planner/HANDOFF.md — read it for context, then delete it with /planner handoff clear (or plan_delete_handoff) when no longer needed. Proceeding with task start.", "info");
                 }
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
@@ -2263,6 +2283,16 @@ export default function planPiExtension(pi) {
             // at the END of that summary (not in a notify here) so it stays visible.
             startupResumePromptPending = true;
             startupResumeSummaryPending = true;
+            // Force the recap turn to rebuild the context (slow path) so the resume
+            // protocol is injected fresh. The protocol is appended per-turn and is
+            // never baked into the cache, so later turns won't see it.
+            contextBlockDirty = true;
+            if (startupResumeSummaryTimer)
+                clearTimeout(startupResumeSummaryTimer);
+            startupResumeSummaryTimer = setTimeout(() => {
+                startupResumeSummaryPending = false;
+                startupResumeSummaryTimer = null;
+            }, 60000);
             pi.sendMessage({
                 customType: "planner-resume-trigger",
                 content: "planner recap",
@@ -3153,8 +3183,7 @@ export default function planPiExtension(pi) {
             catch {
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
             }
-            const rawShort = params.shortName ?? normalizeSlug(params.title).slice(0, 30);
-            const shortName = rawShort.trim() || `task-${Date.now().toString(36)}`; // never empty (fixes regex invalid_string)
+            const shortName = clampSlug(params.shortName ?? params.title, 30, `task-${Date.now().toString(36)}`); // clamp+strip trailing dash; never empty
             const taskId = createTaskId();
             const now = nowISO();
             const initialStatus = params.status ?? "planned";
@@ -3384,6 +3413,90 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)` }], details: completedTask };
         },
     });
+    // ── Web lifecycle tools (agent-callable; parity with @agent-plan/mcp planner-web) ──
+    // These let the agent manage the web dashboard directly, without relying
+    // on the /planner slash command (which is not intercepted when the planner
+    // is disabled by default). Planner operations are NOT code edits.
+    pi.registerTool({
+        name: "planner-web",
+        label: "Planner Web",
+        description: "Manage the planner web dashboard (start/status/stop). The dashboard is LAN-bound (0.0.0.0) with a dynamic OS-assigned port by default. Planner operations are NOT code edits and need no active task. The web does NOT auto-start; call action=start explicitly.",
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal("start"), Type.Literal("stop"), Type.Literal("status")], { description: "start | stop | status. Default: status" }),
+            port: Type.Optional(Type.Number({ description: "Optional requested port for start. Omit/0 → OS assigns a free port." })),
+            visibility: Type.Optional(Type.Union([Type.Literal("local"), Type.Literal("lan")], { description: "Bind scope for start. Default: lan (0.0.0.0, reachable from other devices)." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const action = params.action ?? "status";
+            if (action === "start") {
+                const st = await requirePlan(ctx);
+                if (!st)
+                    return { content: [{ type: "text", text: "No .planner/ found. Run plan_init first." }], details: { running: false } };
+                const visibility = params.visibility ?? "lan";
+                if (server) {
+                    const srv = server;
+                    return { content: [{ type: "text", text: `Web UI already running. Local: ${srv.localUrl}${srv.lanUrl ? ` — LAN: ${srv.lanUrl}` : ""} (mode: ${srv.mode}, port: ${lastKnownWebPort ?? "?"})` }], details: { running: true, localUrl: srv.localUrl, lanUrl: srv.lanUrl, port: lastKnownWebPort, mode: srv.mode } };
+                }
+                await startServer(ctx, params.port && params.port > 0 ? params.port : undefined, visibility);
+                const srv = server;
+                if (!srv)
+                    return { content: [{ type: "text", text: "Failed to start web server." }], details: { running: false } };
+                return { content: [{ type: "text", text: `Web UI started. Local: ${srv.localUrl}${srv.lanUrl ? ` — LAN: ${srv.lanUrl}` : ""} (mode: ${srv.mode}, port: ${lastKnownWebPort ?? "?"})` }], details: { running: true, localUrl: srv.localUrl, lanUrl: srv.lanUrl, port: lastKnownWebPort, mode: srv.mode } };
+            }
+            if (action === "stop") {
+                if (!server)
+                    return { content: [{ type: "text", text: "Web UI not running." }], details: { running: false } };
+                const stoppedUrl = server.localUrl;
+                await stopServer();
+                return { content: [{ type: "text", text: `Web UI stopped (was ${stoppedUrl}).` }], details: { running: false } };
+            }
+            // status
+            const srv = server;
+            if (!srv)
+                return { content: [{ type: "text", text: "Web UI not running. Use planner-web with action=start to start the dashboard." }], details: { running: false } };
+            return { content: [{ type: "text", text: `Web UI running. Local: ${srv.localUrl}${srv.lanUrl ? ` — LAN: ${srv.lanUrl}` : ""} (mode: ${srv.mode}, port: ${lastKnownWebPort ?? "?"})` }], details: { running: true, localUrl: srv.localUrl, lanUrl: srv.lanUrl, port: lastKnownWebPort, mode: srv.mode } };
+        },
+    });
+    pi.registerTool({
+        name: "planner-load",
+        label: "Planner Load",
+        description: "Enable the planner for this project and start the web dashboard (LAN), then return a resume recap (project status + handoff if present + Web UI address). This is the explicit way to enable the planner — it does NOT auto-start. Planner operations are NOT code edits.",
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found. Run plan_init first." }], details: { enabled: false, running: false } };
+            plannerSessionEnabled = true;
+            if (!server) {
+                await startServer(ctx, undefined, "lan").catch(() => { });
+            }
+            let recap = "";
+            try {
+                recap = await buildStartupResumeSummary(st);
+            }
+            catch (e) {
+                recap = `(recap unavailable: ${e instanceof Error ? e.message : String(e)})`;
+            }
+            const srv = server;
+            const webLine = srv ? `\n🌐 Web UI: ${srv.localUrl}${lastKnownWebPort ? ` (port ${lastKnownWebPort})` : ""}${srv.lanUrl ? ` — LAN: ${srv.lanUrl}` : ""}` : "\n🌐 Web UI: not running";
+            return { content: [{ type: "text", text: `${recap}${webLine}` }], details: { enabled: true, running: Boolean(srv), localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort } };
+        },
+    });
+    pi.registerTool({
+        name: "planner-stop",
+        label: "Planner Stop",
+        description: "Disable the planner for this project and stop the web dashboard. Alias: planner-disable. Planner operations are NOT code edits.",
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, _ctx) {
+            plannerSessionEnabled = false;
+            await stopServer().catch(() => { });
+            try {
+                capturedPi?.appendEntry("plan-web-state", { running: false });
+            }
+            catch { }
+            return { content: [{ type: "text", text: "Planner disabled. Web UI shut down. Run /planner load or planner-load to re-enable." }], details: { disabled: true, webRunning: false } };
+        },
+    });
     // ── Context injection ─────────────────────────────────────────────
     pi.on("before_agent_start", async (event, ctx) => {
         if (!plannerSessionEnabled)
@@ -3402,6 +3515,18 @@ export default function planPiExtension(pi) {
                 await st.refreshResume();
                 plannerHeavyInitDone = true;
             }
+            // Resume-flag lifecycle — MUST run every turn, including cache hits.
+            // /planner load sets both flags and dirties the cache so the recap turn
+            // rebuilds (slow path) and injects the resume protocol. We consume
+            // startupResumePromptPending here (it marks the recap turn only), and we
+            // stop appending the web UI address on every later turn. Doing this
+            // BEFORE the cache fast-path is what prevents the URL from leaking onto
+            // every assistant message after /planner load.
+            const isRecapTurn = startupResumePromptPending;
+            startupResumePromptPending = false;
+            if (startupResumeSummaryPending && !isRecapTurn) {
+                startupResumeSummaryPending = false;
+            }
             // Fast path: on steady turns (no plan changes since last build) reuse
             // the cached context block and skip all the per-turn I/O + string build.
             // The cache is invalidated by the write-notify hook whenever the plan
@@ -3499,10 +3624,7 @@ export default function planPiExtension(pi) {
             const ambientSummary = ambient
                 ? `node=${ambient.nodeVersion || "?"} pm=${ambient.packageManager || "?"} lockfile=${ambient.lockfile || "none"} scripts=${Object.entries(ambient.scripts).map(([k, v]) => `${k}="${v}"`).join(", ") || "none"}`
                 : "(not scanned)";
-            if (startupResumeSummaryPending) {
-                startupResumeSummaryText = await buildStartupResumeSummary(st).catch(() => "");
-            }
-            const startupResumeProtocol = startupResumePromptPending ? [
+            const startupResumeProtocol = isRecapTurn ? [
                 "",
                 "STARTUP RESUME PROTOCOL (first reply of the session — mandatory):",
                 "- You are resuming a planner-backed project session.",
@@ -3517,7 +3639,7 @@ export default function planPiExtension(pi) {
                 `- Mention the next suggested activity: ${nextActivity}`,
                 "- THEN ask the user explicitly whether they want to resume that activity now.",
                 "- Do NOT assume yes. Wait for the user's answer before continuing implementation work.",
-                "- If the user says yes and no task is currently in-progress, your NEXT action must be task_start before any bash/edit/write.",
+                "- If the user says yes and no task is currently in-progress, your NEXT action must be task_start before any CODE edit/write (bash for git/build/test is fine; planner operations like plan_write_handoff are NOT code edits and never require a task).",
             ].filter(Boolean).join("\n") : "";
             // Build/refresh the context block (slow path: cache miss).
             const contextBlock = [
@@ -3531,7 +3653,7 @@ export default function planPiExtension(pi) {
                 "MANDATORY OPERATIONAL PROTOCOL (violation = execution failure):",
                 "═══════════════════════════════════════════════════════════════",
                 "1. HANDOFF HYGIENE: If .planner/HANDOFF.md exists, READ and DELETE it IMMEDIATELY using the handoff delete tool. Do NOT summarize first. Do NOT ask for confirmation. Do NOT defer cleanup. DELETE \u2192 THEN work.",
-                "2. TASK LIFECYCLE: BEFORE coding ANY file: call task_start. AFTER finishing work on ANY task: call task_complete. No exceptions. No 'I'll do it later'.",
+                "2. TASK LIFECYCLE: BEFORE coding ANY file: call task_start. AFTER finishing work on ANY task: call task_complete. No exceptions. No 'I'll do it later'. NOTE: Planner operations (plan_write_handoff / /planner handoff, task_start, task_complete, task_update, status reads) are NOT code edits. They are ALWAYS allowed regardless of task state — you may write/refresh the handoff even when no task is in-progress (e.g., all tasks done, or capturing state mid-flight). Never refuse to write a handoff because 'no task is open'; that is incorrect.",
                 "3. IMMEDIATE SYNC: Update task status AT THE EXACT MOMENT of transition. Start = task_start NOW. Done = task_complete NOW. Blocked = task_update with motivation NOW. Never batch status updates.",
                 "4. BLOCKED MOTIVATION: Transitions to blocked/canceled/rejected/deferred/waiting/planned(from non-planned) MUST include a detailed 'motivation' parameter. Write it as if the next person has zero context.",
                 "5. NO SHORTCUTS: If a tool blocks you, follow the protocol. Bypasses are for emergencies only, not for convenience.",
@@ -3609,14 +3731,14 @@ export default function planPiExtension(pi) {
                 handoff?.content ? "If planner state shows no task/phase in-progress, do NOT present the handoff target as the current focus; present it only as a candidate to validate." : "",
                 handoff?.content ? "When the handoff has been fully consumed and work is safely resumed, delete `.planner/HANDOFF.md` using the dedicated handoff delete command/tool." : "",
                 handoff?.content ? handoff.content : "",
-                startupResumeProtocol,
                 "Plan tools available: project_set_language_preferences, plan_init, project_update, requirement_list, requirement_create, requirement_update, requirement_delete, plan_get, feature_list, feature_get, feature_create, feature_update, feature_delete, phase_list, phase_get, phase_create, phase_update, phase_delete, task_list, task_get, task_create, task_update, task_delete, task_start, task_complete, plan_render, plan_get_handoff, plan_write_handoff, plan_delete_handoff, plan_authorize_bypass, plan_clear_bypass",
             ].filter(Boolean).join("\n");
             contextBlockCache = contextBlock;
             contextBlockDirty = false;
-            startupResumePromptPending = false;
+            // The resume protocol is per-turn only (the recap turn) — never bake it
+            // into the cached context block, or it would persist on every later turn.
             return {
-                systemPrompt: `${event.systemPrompt}\n\n---\n${contextBlockCache}`,
+                systemPrompt: `${event.systemPrompt}\n\n---\n${contextBlockCache}${startupResumeProtocol ? `\n\n${startupResumeProtocol}` : ""}`,
             };
         }
         catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/pi-adapter",
-  "version": "0.2.12",
+  "version": "0.2.15",
   "private": false,
   "description": "Pi agent extension for Agent Plan — structured project planning in .planner/",
   "keywords": [
@@ -26,10 +26,10 @@
     ]
   },
   "dependencies": {
-    "@agent-plan/core": "^0.2.0",
-    "@agent-plan/server": "^0.2.0",
     "typebox": "^1.1.24",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@agent-plan/core": "0.2.11",
+    "@agent-plan/server": "0.2.11"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",