@agent-plan/mcp 0.2.24 → 0.2.25

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -10,11 +10,48 @@ import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, validateResolvedTarget } 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];
-const plannerSessionId = randomUUID();
-startReadSession(plannerSessionId);
+const fallbackPlannerSessionId = `mcp-process:${randomUUID()}`;
+startReadSession(fallbackPlannerSessionId);
+function plannerSessionIdFor(extra) {
+    const transportSessionId = extra?.sessionId?.trim();
+    const sessionId = transportSessionId ? `mcp:${transportSessionId}` : fallbackPlannerSessionId;
+    startReadSession(sessionId);
+    return sessionId;
+}
 function text(textValue, structuredContent) {
     return structuredContent ? { content: [{ type: "text", text: textValue }], structuredContent } : { content: [{ type: "text", text: textValue }] };
 }
+function derivedStatusReadOnlyResult(entity, ref, attemptedStatus, effectiveStatus) {
+    const childKind = entity === "feature" ? "phases" : "tasks";
+    const retryAction = entity === "feature"
+        ? `Retry planner-feature-update ${ref} without the status field if you need to update metadata.`
+        : `Retry planner-phase-update ${ref} without the status field if you need to update metadata.`;
+    const nextActions = [
+        `${entity[0].toUpperCase()}${entity.slice(1)} status is derived from child ${childKind}; update the child ${childKind} instead of setting ${entity}.status.`,
+        retryAction,
+    ];
+    return {
+        isError: true,
+        content: [{ type: "text", text: [
+                    `❌ ${entity.toUpperCase()} UPDATE FAILED [DERIVED_STATUS_READ_ONLY]`,
+                    `${entity[0].toUpperCase()}${entity.slice(1)} status is derived from child ${childKind} and cannot be set directly.`,
+                    `Attempted status: ${attemptedStatus}`,
+                    `Effective derived status: ${effectiveStatus}`,
+                    "No planner data was changed.",
+                    "Next required actions:",
+                    ...nextActions.map((action, index) => `${index + 1}. ${action}`),
+                ].join("\n") }],
+        structuredContent: {
+            updated: false,
+            errorCode: "DERIVED_STATUS_READ_ONLY",
+            entity,
+            ref,
+            attemptedStatus,
+            effectiveStatus,
+            nextActions,
+        },
+    };
+}
 function taskStartError(outcome, structuredContent = {}) {
     return {
         isError: true,
@@ -29,6 +66,19 @@ function taskStartError(outcome, structuredContent = {}) {
         structuredContent: { ...outcome, ...structuredContent },
     };
 }
+function mcpContextReadActions(eligibility, refs, requirementReadRequired, retryAction) {
+    const actions = (eligibility.requiredReads ?? []).flatMap((read) => {
+        if (read.kind === "task")
+            return [`planner-task-show ${refs.task} with full=true`];
+        if (read.kind === "phase")
+            return [`planner-phase-show ${refs.phase} with full=true`];
+        return refs.feature ? [`planner-feature-show ${refs.feature} with full=true`] : [];
+    });
+    if (requirementReadRequired)
+        actions.push("planner-requirement-list");
+    actions.push(retryAction);
+    return actions;
+}
 const MCP_PACKAGE = packageVersionFromModule(import.meta.url, "@agent-plan/mcp");
 const CORE_PACKAGE = resolvedPackageVersion("@agent-plan/core", import.meta.url);
 function nowISO() {
@@ -461,7 +511,8 @@ server.registerTool("planner-feature-add", {
 server.registerTool("planner-feature-show", {
     description: "Show a feature by id or name.",
     inputSchema: { feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the feature description. Default: compact identity only (saves tokens).") },
-}, async ({ feature: ref, full }) => {
+}, async ({ feature: ref, full }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const resolvedFeature = resolveFeatureRefStrict(features, ref);
@@ -531,6 +582,9 @@ server.registerTool("planner-feature-update", {
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
+    if (updates.status !== undefined) {
+        return derivedStatusReadOnlyResult("feature", formatFeatureRef(feature.number), updates.status, feature.status);
+    }
     const updated = await st.updateFeatures((doc) => {
         const target = doc.features.find((entry) => entry.id === feature.id);
         if (!target)
@@ -539,8 +593,6 @@ server.registerTool("planner-feature-update", {
             target.name = updates.name.trim();
         if (updates.description !== undefined)
             target.description = updates.description.trim();
-        if (updates.status !== undefined)
-            target.status = updates.status;
         if (updates.workDone !== undefined)
             target.workDone = updates.workDone.trim();
         if (updates.workRemaining !== undefined)
@@ -672,7 +724,8 @@ server.registerTool("planner-phase-add", {
 server.registerTool("planner-phase-show", {
     description: "Show a phase by id or name, including derived linked requirements in the full view.",
     inputSchema: { phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the phase description. Default: compact identity only (saves tokens).") },
-}, async ({ phase: ref, full }) => {
+}, async ({ phase: ref, full }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const phase = findPhaseByRef(await st.loadAllPhases(), features, ref);
@@ -757,11 +810,12 @@ server.registerTool("planner-phase-update", {
     const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
+    if (updates.status !== undefined) {
+        return derivedStatusReadOnlyResult("phase", formatPhaseRef(found.number, featureNumberOfPhase(found, features)), updates.status, found.status);
+    }
     const phase = await st.updatePhase(found.id, (entry) => {
         if (updates.title !== undefined)
             entry.title = updates.title.trim();
-        if (updates.status !== undefined)
-            entry.status = updates.status;
         if (updates.summary !== undefined)
             entry.summary = updates.summary.trim();
         if (updates.description !== undefined)
@@ -866,7 +920,8 @@ server.registerTool("planner-task-add", {
 server.registerTool("planner-task-show", {
     description: "Show a task by id or name.",
     inputSchema: { task: z.string().min(1).describe("Task ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the task description, resume checkpoint/advisory, and statusLog. Default: compact identity only (saves tokens).") },
-}, async ({ task: ref, full }) => {
+}, async ({ task: ref, full }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
@@ -1186,7 +1241,8 @@ server.registerTool("planner-task-pause", {
         how_to_resume: z.string().min(1),
         paused_by: z.string().optional(),
     },
-}, async ({ task: ref, reason, what_was_being_done, resume_location, how_to_resume, paused_by }) => {
+}, async ({ task: ref, reason, what_was_being_done, resume_location, how_to_resume, paused_by }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const found = findTaskByRef(await st.loadAllPhases(), features, ref);
@@ -1223,7 +1279,7 @@ server.registerTool("planner-task-pause", {
     ].join("\n"), { task: checkpointed, snapshot, ...(resume ? { resumeRequired: { taskId: resume.task.id } } : {}) });
 });
 server.registerTool("planner-task-switch", {
-    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Reuse the target's valid sessionInfo context or require the exact full tree when missing or stale. Pause the source with a mandatory snapshot, start the target, and push a durable LIFO return target.",
+    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Call this tool first so valid sessionInfo context can be reused; on denial, perform only the missing/stale reads listed in nextActions and retry. Pause the source with a mandatory snapshot, start the target, and push a durable LIFO return target.",
     inputSchema: {
         from_task: z.string().min(1),
         to_task: z.string().min(1),
@@ -1233,7 +1289,8 @@ server.registerTool("planner-task-switch", {
         how_to_resume: z.string().min(1),
         switched_by: z.string().optional(),
     },
-}, async ({ from_task, to_task, reason, what_was_being_done, resume_location, how_to_resume, switched_by }) => {
+}, async ({ from_task, to_task, reason, what_was_being_done, resume_location, how_to_resume, switched_by }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const [featuresDoc, phases, project, focus] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject(), st.loadResume()]);
     const features = featuresDoc.features;
@@ -1266,10 +1323,16 @@ server.registerTool("planner-task-switch", {
         requirementIds: linkedRequirementIds,
     };
     const contextEligibility = contextReadEligibilityForSession(contextInput);
-    if (!contextEligibility.eligible)
-        return text(`Task switch denied: context reads required. ${contextEligibility.reason}`, contextEligibility);
-    if (!hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements)) {
-        return text("Task switch denied: read the requirements linked to the target phase and feature before switching.", { requirementIds: linkedRequirementIds });
+    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
+    const targetTaskRef = taskCompositeRef(target.task, target.phase, features);
+    const targetPhaseRef = formatPhaseRef(target.phase.number, featureNumberOfPhase(target.phase, features));
+    const targetFeatureRef = targetFeature ? formatFeatureRef(targetFeature.number) : "";
+    if (!contextEligibility.eligible) {
+        const nextActions = mcpContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, !requirementsReady, `Retry planner-task-switch to ${targetTaskRef}`);
+        return text(`Task switch denied: context reads required. ${contextEligibility.reason}`, { ...contextEligibility, nextActions });
+    }
+    if (!requirementsReady) {
+        return text("Task switch denied: read the requirements linked to the target phase and feature before switching.", { requirementIds: linkedRequirementIds, nextActions: ["planner-requirement-list", `Retry planner-task-switch to ${targetTaskRef}`] });
     }
     if (!hasValidSessionAttestation(contextInput)) {
         await st.recordContextRead({ sessionId: plannerSessionId, phaseId: target.phase.id, taskId: target.task.id, ...(target.phase.featureId ? { featureId: target.phase.featureId } : {}), requirementIds: linkedRequirementIds });
@@ -1371,9 +1434,10 @@ server.registerTool("planner-task-switch", {
     ].join("\n"), { deviation: record, snapshot, resumeTaskId: source.task.id, temporaryTaskId: target.task.id });
 });
 server.registerTool("planner-task-start", {
-    description: "Set a task to in-progress or resume checkpointed work. Read the exact full task → phase → feature tree and linked requirements once per harness session; subsequent starts reuse persisted sessionInfo while entity updatedAt values remain unchanged. Every stale or denied start is an MCP isError result with started=false and exact retry actions; NEVER claim work started unless structuredContent.started is true. Success is returned only after persisted in-progress state is verified.",
+    description: "Set a task to in-progress or resume checkpointed work. Call this tool before reading context so it can reuse valid sessionInfo attestations; if denied, perform only the missing/stale reads listed in nextActions, in order, and retry. Every denied start is an MCP isError result with started=false; NEVER claim work started unless structuredContent.started is true. Success is returned only after persisted in-progress state is verified.",
     inputSchema: { task: z.string().min(1) },
-}, async ({ task: ref }) => {
+}, async ({ task: ref }, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     let st;
     try {
         st = await requireStore();
@@ -1389,10 +1453,6 @@ server.registerTool("planner-task-start", {
     const phaseRef = formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features));
     const parentFeature = found.phase.featureId ? features.find((candidate) => candidate.id === found.phase.featureId) : undefined;
     const featureRef = parentFeature ? formatFeatureRef(parentFeature.number) : "";
-    if (found.task.status === "in-progress") {
-        const outcome = taskStartSucceeded(found.task.id, true);
-        return text(`✅ Task already started: ${taskRef} — ${found.task.title} (in-progress)\nstarted: true`, { ...outcome, task: found.task });
-    }
     if (found.task.status === "done")
         return taskStartError(taskStartDenied("TASK_DONE", `Task ${taskRef} is done and was not reopened.`, [`Use planner-task-update with status=planned and a motivation to reopen ${taskRef}.`, `Repeat the required full context reads, then retry planner-task-start ${taskRef}.`], { taskId: found.task.id }));
     const linkedRequirements = [
@@ -1412,20 +1472,19 @@ server.registerTool("planner-task-start", {
         requirementIds: linkedRequirementIds,
     };
     const contextEligibility = contextReadEligibilityForSession(contextInput);
+    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
     if (!contextEligibility.eligible)
-        return taskStartError(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, [
-            `planner-task-show ${taskRef} with full=true`,
-            `planner-phase-show ${phaseRef} with full=true`,
-            ...(featureRef ? [`planner-feature-show ${featureRef} with full=true`] : []),
-            ...(linkedRequirementIds.length > 0 ? ["planner-requirement-list"] : []),
-            `Retry planner-task-start ${taskRef}`,
-        ], { taskId: found.task.id }), { contextEligibility });
-    if (!hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements)) {
+        return taskStartError(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, mcpContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, !requirementsReady, `Retry planner-task-start ${taskRef}`), { taskId: found.task.id }), { contextEligibility });
+    if (!requirementsReady) {
         return taskStartError(taskStartDenied("REQUIREMENTS_READ_REQUIRED", "Linked requirements were not read; the task remains unchanged.", ["planner-requirement-list", `Retry planner-task-start ${taskRef}`], { taskId: found.task.id, requirementIds: linkedRequirementIds }));
     }
     if (!hasValidSessionAttestation(contextInput)) {
         await st.recordContextRead({ sessionId: plannerSessionId, phaseId: found.phase.id, taskId: found.task.id, ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}), requirementIds: linkedRequirementIds });
     }
+    if (found.task.status === "in-progress") {
+        const outcome = taskStartSucceeded(found.task.id, true);
+        return text(`✅ Task already started: ${taskRef} — ${found.task.title} (in-progress)\nstarted: true`, { ...outcome, task: found.task });
+    }
     const [project, phases, focus] = await Promise.all([st.loadProject(), st.loadAllPhases(), st.loadResume()]);
     const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
     if (!eligibility.eligible)
@@ -1624,7 +1683,8 @@ server.registerTool("planner-handoff-show", {
 server.registerTool("planner-requirement-list", {
     description: "List all top-level requirements in requirements.json. Reading this list records the requirements as read for the start/resume read-enforcement (explicit requirement read, required alongside feature/phase reads).",
     inputSchema: {},
-}, async () => {
+}, async (_args, extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
     const st = await requireStore();
     const requirements = await st.loadRequirements();
     requirements.requirements.forEach((req) => markRequirementReadForSessionId(plannerSessionId, req.id));

package/package.json

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