@agent-plan/mcp 0.2.17 → 0.2.19-next.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA21BA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA+5BA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -3,11 +3,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { PlanStore, ExportService, withFeatureLock, needsMotivation } from "@agent-plan/core";
+import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
-import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug } from "@agent-plan/core/naming";
+import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
 const PHASE_STATUS_VALUES = ["draft", "discovery", ...STATUS_VALUES];
 function text(textValue, structuredContent) {
@@ -28,8 +27,14 @@ async function requireStore() {
     const st = store();
     if (!(await st.exists()))
         throw new Error(`No .planner/ found at ${st.root}. Use planner-init first.`);
+    // One-time idempotent backfill of shortId + priority (safe, best-effort).
+    if (!planBackfillDone) {
+        planBackfillDone = true;
+        await st.ensureShortIdsAndPriority().catch(() => { });
+    }
     return st;
 }
+let planBackfillDone = false;
 // In-process web server handle, managed by the planner-web tool and planner-load.
 // Lives as long as this MCP stdio process (i.e. the host session). Null when not running.
 let webHandle = null;
@@ -53,7 +58,7 @@ async function ensureWebStarted() {
 /** Build a consolidated planner recap (project state + active work + pending
  *  handoff + web URL). Harness-agnostic equivalent of Pi's buildStartupResumeSummary. */
 async function buildRecapText(st, web) {
-    const [plan, resume, handoff] = await Promise.all([st.loadAll(), st.loadResume(), st.loadHandoff()]);
+    const [plan, resume, handoffs] = await Promise.all([st.loadAll(), st.loadResume(), st.listHandoffs()]);
     const allTasks = plan.phases.flatMap((p) => p.tasks.map((t) => ({ phase: p, task: t })));
     const totalF = plan.features.features.length;
     const doneF = plan.features.features.filter((f) => f.status === "done").length;
@@ -80,11 +85,13 @@ async function buildRecapText(st, web) {
     }
     if (resume?.nextSteps?.length)
         lines.push(`Next step: ${resume.nextSteps[0]}`);
-    if (handoff) {
-        lines.push("", "## Pending handoff (read me first)", handoff.content || "(empty handoff)", "", "→ After processing the handoff above, call planner-handoff-clear to remove it.");
+    if (handoffs.length > 0) {
+        lines.push("", `## Pending phase handoffs (${handoffs.length})`);
+        handoffs.forEach((h, i) => lines.push(`[${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`));
+        lines.push("", "→ Read the relevant one with planner-handoff-show <ref> (validate against current state), then call planner-handoff-clear <ref> once consumed (delete-on-resume).");
     }
     else if (activeT === 0) {
-        lines.push("", "No handoff pending and no task in-progress. Use planner-task-add / planner-task-start to begin work.");
+        lines.push("", "No phase handoff pending and no task in-progress. Use planner-task-add / planner-task-start to begin work.");
     }
     if (web.localUrl) {
         lines.push("", "## Web UI", `🌐 ${web.localUrl}${web.lanUrl ? " (LAN: " + web.lanUrl + ")" : ""}`);
@@ -97,12 +104,6 @@ function findFeatureByRef(features, ref) {
         ?? features.find((feature) => feature.name.toLowerCase() === normalized)
         ?? features.find((feature) => feature.name.toLowerCase().includes(normalized));
 }
-function findPhaseByRef(phases, ref) {
-    const normalized = ref.trim().toLowerCase();
-    return phases.find((phase) => phase.id.toLowerCase() === normalized)
-        ?? phases.find((phase) => phase.title.toLowerCase() === normalized)
-        ?? phases.find((phase) => phase.title.toLowerCase().includes(normalized));
-}
 function findTaskByRef(phases, ref) {
     const normalized = ref.trim().toLowerCase();
     for (const phase of phases) {
@@ -136,6 +137,28 @@ const server = new McpServer({
     name: "agent-plan-planner",
     version: "0.1.0",
 });
+async function resolvePhaseForHandoff(st, ref) {
+    const phases = await st.loadAllPhases();
+    const features = (await st.loadFeatures()).features;
+    let phase;
+    if (ref && ref.trim()) {
+        phase = findPhaseByRef(phases, features, ref.trim());
+    }
+    else {
+        phase = phases.find((p) => p.status === "in-progress")
+            ?? phases.find((p) => p.tasks.some((t) => t.status === "in-progress"));
+    }
+    if (!phase) {
+        return {
+            ok: false,
+            error: ref && ref.trim()
+                ? `Phase not found: "${ref.trim()}". Use P00x, P00x(F00x), UUID, or title.`
+                : "No in-progress phase. Specify a phaseRef (P00x or P00x(F00x)).",
+        };
+    }
+    const feat = phase.featureId ? features.find((f) => f.id === phase.featureId) : undefined;
+    return { ok: true, phase, compositeRef: formatPhaseRef(phase.number, feat?.number) };
+}
 server.registerTool("planner-export", {
     description: "Export the project plan as a Markdown report. Supports a concise summary or full hierarchical detail.",
     inputSchema: {
@@ -282,9 +305,13 @@ server.registerTool("planner-feature-add", {
     const timestamp = nowISO();
     const effectiveStatus = status ?? "planned";
     const existingFeatures = (await st.loadFeatures()).features;
+    const shortId = createShortId(await st.assignedShortIds());
+    const priority = await st.nextPriority("feature");
     const feature = {
         id: createFeatureId(),
         number: existingFeatures.length + 1,
+        shortId,
+        priority,
         name: name.trim(),
         description: description?.trim() ?? "",
         status: effectiveStatus,
@@ -330,6 +357,7 @@ server.registerTool("planner-feature-update", {
         workRemaining: z.string().optional(),
         startDate: z.string().optional(),
         endDate: z.string().optional(),
+        priority: z.number().int().nonnegative().optional().describe("Display order within the project (lower = higher). Tiebreak by number then createdAt."),
     },
 }, async ({ feature: ref, ...updates }) => {
     const st = await requireStore();
@@ -355,6 +383,8 @@ server.registerTool("planner-feature-update", {
             target.startDate = updates.startDate.trim();
         if (updates.endDate !== undefined)
             target.endDate = updates.endDate.trim();
+        if (updates.priority !== undefined)
+            target.priority = updates.priority;
         target.updatedAt = nowISO();
         return doc;
     });
@@ -410,9 +440,13 @@ server.registerTool("planner-phase-add", {
         const phases = await st.loadAllPhases();
         const featurePhases = feature ? phases.filter((phase) => phase.featureId === feature.id) : phases;
         const timestamp = nowISO();
+        const shortId = createShortId(await st.assignedShortIds());
+        const priority = await st.nextPriority("phase", feature?.id);
         phase = {
             id: createPhaseId(),
             number: featurePhases.reduce((max, entry) => Math.max(max, entry.number), 0) + 1,
+            shortId,
+            priority,
             slug: normalizeSlug(title),
             title: title.trim(),
             featureId: feature?.id,
@@ -436,6 +470,8 @@ server.registerTool("planner-phase-add", {
             tasks: [],
             createdAt: timestamp,
             updatedAt: timestamp,
+            handoff: "",
+            handoffUpdatedAt: "",
         };
         await st.savePhase(phase);
         if (feature) {
@@ -457,7 +493,7 @@ server.registerTool("planner-phase-show", {
     inputSchema: { phase: z.string().min(1).describe("Phase id or name") },
 }, async ({ phase: ref }) => {
     const st = await requireStore();
-    const phase = findPhaseByRef(await st.loadAllPhases(), ref);
+    const phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
     return text(`${phase.title} (${phase.id}) — ${phase.status}; ${phase.tasks.length} tasks`, { phase });
@@ -476,7 +512,7 @@ server.registerTool("planner-phase-discuss", {
     },
 }, async ({ phase: ref, ...updates }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), ref);
+    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
     const phase = await st.updatePhase(found.id, (entry) => {
@@ -511,10 +547,11 @@ server.registerTool("planner-phase-update", {
         status: z.enum(PHASE_STATUS_VALUES).optional(),
         summary: z.string().optional(),
         description: z.string().optional(),
+        priority: z.number().int().nonnegative().optional().describe("Display order within the feature (lower = higher)."),
     },
 }, async ({ phase: ref, ...updates }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), ref);
+    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
     const phase = await st.updatePhase(found.id, (entry) => {
@@ -526,6 +563,8 @@ server.registerTool("planner-phase-update", {
             entry.summary = updates.summary.trim();
         if (updates.description !== undefined)
             entry.description = updates.description.trim();
+        if (updates.priority !== undefined)
+            entry.priority = updates.priority;
         entry.updatedAt = nowISO();
         return entry;
     });
@@ -536,7 +575,7 @@ server.registerTool("planner-phase-delete", {
     inputSchema: { phase: z.string().min(1) },
 }, async ({ phase: ref }) => {
     const st = await requireStore();
-    const phase = findPhaseByRef(await st.loadAllPhases(), ref);
+    const phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
     await st.deletePhase(phase.id);
@@ -557,15 +596,19 @@ server.registerTool("planner-task-add", {
     },
 }, async ({ phase: ref, title, description, checklist }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), ref);
+    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
     const timestamp = nowISO();
     const taskId = createTaskId();
+    const shortId = createShortId(await st.assignedShortIds());
+    const priority = await st.nextPriority("task", found.id);
     const task = {
         id: taskId,
         phaseId: found.id,
         number: found.tasks.length + 1,
+        shortId,
+        priority,
         shortName: clampSlug(title, 30, `task-${Date.now().toString(36)}`),
         title: title.trim(),
         status: "planned",
@@ -636,8 +679,9 @@ server.registerTool("planner-task-update", {
         status: z.enum(STATUS_VALUES).optional(),
         description: z.string().optional(),
         motivation: z.string().optional(),
+        priority: z.number().int().nonnegative().optional().describe("Display order within the phase (lower = higher)."),
     },
-}, async ({ task: ref, title, status, description, motivation }) => {
+}, async ({ task: ref, title, status, description, motivation, priority }) => {
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), ref);
     if (!found)
@@ -657,6 +701,8 @@ server.registerTool("planner-task-update", {
             return phase;
         if (title !== undefined)
             task.title = title.trim();
+        if (priority !== undefined)
+            task.priority = priority;
         if (description !== undefined)
             task.description = description.trim();
         if (status !== undefined && status !== task.status) {
@@ -706,8 +752,8 @@ server.registerTool("planner-task-start", {
     // task_start — the handoff is a captured-context artifact, not a lock (e.g. a
     // small modification after writing a handoff should start without forcing
     // deletion, which would lose context).
-    const handoffNotice = existsSync(join(st.root, "HANDOFF.md"))
-        ? "ℹ️  A handoff exists at .planner/HANDOFF.md — read it for context, then delete it with planner-handoff-delete when no longer needed. Proceeding with task start.\n"
+    const handoffNotice = (await st.listHandoffs()).length > 0
+        ? "ℹ️  One or more phases have a pending handoff — if relevant to the task you're starting, read it with planner-handoff-show <ref>, then clear with planner-handoff-clear. Proceeding with task start.\n"
         : "";
     const found = findTaskByRef(await st.loadAllPhases(), ref);
     if (!found)
@@ -780,41 +826,63 @@ server.registerTool("planner-task-complete", {
         updatedTask = task;
         return phase;
     });
-    await st.syncTaskStatusRollup(found.phase.id);
-    return writeAndSummarize(st, `✅ Task completed: ${found.task.id}`, { task: updatedTask ?? found.task });
+    const clearedRef = await st.syncTaskStatusRollup(found.phase.id);
+    return writeAndSummarize(st, `✅ Task completed: ${found.task.id}${clearedRef ? ` — phase handoff auto-cleared (${clearedRef})` : ""}`, { task: updatedTask ?? found.task });
 });
-server.registerTool("planner-handoff-show", {
-    description: "Show .planner/HANDOFF.md if present.",
+server.registerTool("planner-handoff-list", {
+    description: "List all phases with a non-empty entity-scoped handoff (phase.handoff field). Returns composite refs (P00x / P00x(F00x)) with the first line and last-updated time.",
 }, async () => {
     const st = await requireStore();
-    const handoff = await st.loadHandoff();
-    return text(handoff?.content ?? "No .planner/HANDOFF.md present.", { handoff: handoff ?? null });
+    const list = await st.listHandoffs();
+    if (list.length === 0)
+        return text("No phase handoffs set.");
+    const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
+    return text(`Phase handoffs (${list.length}):\n${lines.join("\n")}`, { count: list.length, handoffs: list });
+});
+server.registerTool("planner-handoff-show", {
+    description: "Read the entity-scoped handoff of a phase. phaseRef accepts P00x, P00x(F00x), UUID, or title. Omit to target the current in-progress phase.",
+    inputSchema: { phaseRef: z.string().optional().describe("Phase ref: P00x | P00x(F00x) | UUID | title. Default: current in-progress phase.") },
+}, async ({ phaseRef }) => {
+    const st = await requireStore();
+    const r = await resolvePhaseForHandoff(st, phaseRef);
+    if (!r.ok)
+        return text(`❌ ${r.error}`);
+    const content = await st.getPhaseHandoff(r.phase.id);
+    if (!content.trim())
+        return text(`No handoff set on ${r.compositeRef}.`, { phaseRef: r.compositeRef, empty: true });
+    return text(`Handoff for ${r.compositeRef}:\n\n${content}`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-handoff-write", {
-    description: "Write .planner/HANDOFF.md content.",
+    description: "Write/refresh the entity-scoped handoff on a phase. Pass content (markdown). phaseRef optional (default: current in-progress phase). Captures design context for a resuming agent on that phase.",
     inputSchema: {
-        content: z.string().min(1),
-        reason: z.string().optional(),
+        phaseRef: z.string().optional().describe("Phase ref. Default: current in-progress phase."),
+        content: z.string().min(1).describe("Handoff text (markdown)."),
     },
-}, async ({ content, reason }) => {
+}, async ({ phaseRef, content }) => {
     const st = await requireStore();
-    const finalContent = reason && !content.includes("Reason:") ? `Reason: ${reason}\n\n${content}` : content;
-    await st.saveHandoff(finalContent);
-    return text("Wrote .planner/HANDOFF.md");
+    const r = await resolvePhaseForHandoff(st, phaseRef);
+    if (!r.ok)
+        return text(`❌ ${r.error}`);
+    await st.setPhaseHandoff(r.phase.id, content);
+    return text(`✅ Wrote handoff on ${r.compositeRef}.`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-handoff-prepare", {
-    description: "Return instructions for the agent to prepare a canonical handoff, then call planner-handoff-write.",
+    description: "Return instructions for the agent to prepare a canonical handoff, then call planner-handoff-write (entity-scoped, phase.handoff).",
 }, async () => text([
-    "Prepare the canonical session handoff and write it with planner-handoff-write.",
+    "Prepare the canonical session handoff and write it on the current in-progress phase with planner-handoff-write (omit phaseRef to target the in-progress phase).",
     "Required sections: Created at, Updated at, Reason, Current focus, What was being done, How to resume, Files touched, Blockers, Next steps, Recent decisions, Reminder.",
-    "Canonical path: .planner/HANDOFF.md.",
+    "Stored on the phase.handoff field (entity-scoped). .planner/HANDOFF.md is deprecated.",
 ].join("\n")));
 server.registerTool("planner-handoff-clear", {
-    description: "Delete .planner/HANDOFF.md.",
-}, async () => {
+    description: "Clear the entity-scoped handoff of a phase (sets handoff to empty, keeps handoffUpdatedAt as an audit trail). phaseRef optional (default: current in-progress phase).",
+    inputSchema: { phaseRef: z.string().optional().describe("Phase ref. Default: current in-progress phase.") },
+}, async ({ phaseRef }) => {
     const st = await requireStore();
-    await st.deleteHandoff();
-    return text("Deleted .planner/HANDOFF.md");
+    const r = await resolvePhaseForHandoff(st, phaseRef);
+    if (!r.ok)
+        return text(`❌ ${r.error}`);
+    await st.clearPhaseHandoff(r.phase.id);
+    return text(`✅ Cleared handoff on ${r.compositeRef}. (handoffUpdatedAt preserved as audit)`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-web", {
     description: "Manage the planner web dashboard (start/status/stop) from MCP stdio. Runs an in-process HTTP+WS server bound to LAN; it lives as long as this MCP process. plan-root comes from AGENT_PLAN_ROOT or cwd()/.planner.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.2.17",
+  "version": "0.2.19-next.0",
   "private": false,
   "description": "MCP server for Agent Plan, exposing planner-* tools over stdio.",
   "license": "MIT",
@@ -41,8 +41,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.2.17",
-    "@agent-plan/server": "0.2.17"
+    "@agent-plan/core": "0.2.19-next.0",
+    "@agent-plan/server": "0.2.19-next.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",