@agent-plan/mcp 0.4.6 → 0.4.8

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA4BA,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA2LrI;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAUzE;AAi4FD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA4BA,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA2LrI;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAUzE;AAk5FD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -5,7 +5,7 @@ import * as z from "zod/v4";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
-import { PlanStore, PlanStoreError, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, createStaleProcessCheck, runtimeCapabilities, runtimePackagesDiagnostic, markCanonicalFullReadForSessionId, contextReadEligibilityForSession, requirementReadEligibilityForSession, hasValidSessionAttestation, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, taskStartGateState, taskStartGateStateLine, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, HANDOFF_COLD_START_INVENTORY_VERSION, HANDOFF_COLD_START_INVENTORY_CATEGORIES, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, buildPlannerLoadReply, buildScopedDecisionContext, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildMutationReply, longTextFieldLimitNotice, buildRecommendationReply, buildTaskOrderContext, taskOrderContextLine, taskCreatedPriorityFragment, findHigherPriorityOpenPhase, higherPriorityOpenPhaseAdvisory, listOpenPhaseWork, openPhaseWorkLines, boundedOpenPhaseWork, deleteFeatureCascade, evaluateTaskCompletionGate, taskCompletionChecklistRefusal, taskCompletionForceMotivationRequired, taskCompletionOverrideNote, taskCompletionMismatchLine, boundedPage, nowISO, resolveFeatureRefStrict, resolveAcceptedDecisionTarget, applyTaskLifecycleDates, handoffContractFailureReply, derivedStatusReadOnlyReply, acceptedDecisionMutationFailureReply, legacyContextMigrationSummary, moveTasks, buildTaskMoveReply } from "@agent-plan/core";
+import { PlanStore, PlanStoreError, taskOwnershipConflict, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, createStaleProcessCheck, runtimeCapabilities, runtimePackagesDiagnostic, markCanonicalFullReadForSessionId, contextReadEligibilityForSession, requirementReadEligibilityForSession, hasValidSessionAttestation, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, taskStartGateState, taskStartGateStateLine, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, HANDOFF_COLD_START_INVENTORY_VERSION, HANDOFF_COLD_START_INVENTORY_CATEGORIES, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, buildPlannerLoadReply, buildScopedDecisionContext, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildMutationReply, longTextFieldLimitNotice, buildRecommendationReply, buildTaskOrderContext, taskOrderContextLine, taskCreatedPriorityFragment, findHigherPriorityOpenPhase, higherPriorityOpenPhaseAdvisory, listOpenPhaseWork, openPhaseWorkLines, boundedOpenPhaseWork, deleteFeatureCascade, evaluateTaskCompletionGate, taskCompletionChecklistRefusal, taskCompletionForceMotivationRequired, taskCompletionOverrideNote, taskCompletionMismatchLine, boundedPage, nowISO, resolveFeatureRefStrict, resolveAcceptedDecisionTarget, applyTaskLifecycleDates, handoffContractFailureReply, derivedStatusReadOnlyReply, acceptedDecisionMutationFailureReply, legacyContextMigrationSummary, moveTasks, buildTaskMoveReply } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createRequirementId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, formatIdeaRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
@@ -201,10 +201,38 @@ function withStaleServerNotice(result) {
     return { ...result, content: [...result.content, { type: "text", text: notice }] };
 }
 {
+    const sessionOperations = new Set(["planner-load", "planner-task-start", "planner-task-switch", "planner-task-pause", "planner-task-complete", "planner-task-reopen", "planner-task-update", "planner-task-deviation", "planner-session-recover"]);
+    const registeredSessions = new Set();
     const registerToolUnwrapped = server.registerTool.bind(server);
     server.registerTool = (...args) => {
         const handler = args[args.length - 1];
-        const wrapped = async (...handlerArgs) => foldTextIntoStructured(withStaleServerNotice(await handler(...handlerArgs)));
+        const wrapped = async (...handlerArgs) => {
+            const invoke = async () => foldTextIntoStructured(withStaleServerNotice(await handler(...handlerArgs)));
+            if (!sessionOperations.has(args[0]))
+                return invoke();
+            const st = store();
+            if (!(await st.exists()))
+                return invoke();
+            const sessionId = plannerSessionIdFor(handlerArgs[1]);
+            const prepare = async () => {
+                if (!registeredSessions.has(sessionId)) {
+                    await st.registerSession(sessionId);
+                    registeredSessions.add(sessionId);
+                }
+            };
+            // Server/watchers must be created outside a write transaction's async context.
+            if (args[0] === "planner-load") {
+                await st.runBatch(prepare);
+                return invoke();
+            }
+            return st.runBatch(async () => {
+                await prepare();
+                const result = await invoke();
+                if (!result.isError)
+                    await st.refreshResume(undefined, undefined, sessionId);
+                return result;
+            });
+        };
         return registerToolUnwrapped(...args.slice(0, -1), wrapped);
     };
 }
@@ -2120,6 +2148,10 @@ server.registerTool("planner-task-switch", {
         return text(`Task not found: ${to_task}`);
     if (source.task.id === target.task.id)
         return text("Source and temporary task must differ.");
+    const allDeviations = await st.listAllWorkDeviations();
+    if ([source.task, target.task].some((task) => taskOwnershipConflict(task, allDeviations, plannerSessionId))) {
+        return { ...text("Task switch denied: source or target belongs to another session.", { started: false, errorCode: "TASK_OWNED_BY_ANOTHER_SESSION" }), isError: true };
+    }
     if (source.task.status !== "in-progress" && !source.task.pauseSnapshot) {
         return text(`Task switch denied: source is ${source.task.status}; only in-progress or checkpointed work can be switched.`);
     }
@@ -2202,27 +2234,7 @@ server.registerTool("planner-task-switch", {
                 });
             }
             sourceCheckpointed = true;
-            if (target.task.pauseSnapshot) {
-                await st.resumeTask(target.phase.id, target.task.id, timestamp, plannerSessionId);
-            }
-            else {
-                await st.updatePhase(target.phase.id, (phase) => {
-                    const task = phase.tasks.find((entry) => entry.id === target.task.id);
-                    if (!task)
-                        throw new Error(`Temporary task disappeared: ${to_task}`);
-                    const previousStatus = task.status;
-                    applyTaskLifecycleDates(task, "in-progress", timestamp);
-                    task.activeOwnerSession = plannerSessionId;
-                    task.statusLog = [...task.statusLog, {
-                            id: createChecklistItemId(task.id, task.statusLog.length + 1, `${previousStatus}-in-progress`),
-                            date: timestamp, fromStatus: previousStatus, toStatus: "in-progress",
-                            title: `${previousStatus} → in-progress`, description: `Temporary switch from ${source.task.title}.`,
-                        }];
-                    task.updatedAt = timestamp;
-                    phase.updatedAt = timestamp;
-                    return phase;
-                });
-            }
+            await st.claimTask(target.phase.id, target.task.id, plannerSessionId, timestamp);
             targetStarted = true;
             await st.addWorkDeviation(record, plannerSessionId);
             if (target.task.pauseSnapshot) {
@@ -2284,6 +2296,22 @@ server.registerTool("planner-task-reopen", {
         return { ...text(`Task reopen denied: ${error instanceof Error ? error.message : "unknown error"}`, { reopened: false, errorCode: details?.errorCode ?? "TASK_REOPEN_FAILED" }), isError: true };
     }
 });
+server.registerTool("planner-session-recover", {
+    description: "Explicitly recover a stopped caller's task ownership, complete return stack and resume focus into this fresh connection. Identify the old session by an active task or a pending return task, without client-side session-ID mapping. Requires confirmed=true after confirming the previous caller has stopped; refuses a registered live process and a caller that already owns work. Task statuses, checkpoints and context-read gates are preserved. Then read the task context and use planner-task-start normally.",
+    inputSchema: { task: z.string().min(1), confirmed: z.boolean() },
+}, async ({ task: ref, confirmed }, extra) => {
+    const st = await requireStore();
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
+    if (!found)
+        return { ...text(`Task not found: ${ref}`, { recovered: false, errorCode: "TASK_NOT_FOUND" }), isError: true };
+    try {
+        const result = await st.recoverSessionForTask(found.phase.id, found.task.id, plannerSessionIdFor(extra), confirmed);
+        return text("Session recovered. Existing tasks, checkpoints and return stack are preserved; read the task context before continuing.", { recovered: true, ...result });
+    }
+    catch (error) {
+        return { ...text(`Session recovery denied: ${error instanceof Error ? error.message : String(error)}`, { recovered: false, errorCode: error instanceof PlanStoreError ? error.details?.errorCode ?? "SESSION_RECOVERY_FAILED" : "SESSION_RECOVERY_FAILED" }), isError: true };
+    }
+});
 server.registerTool("planner-task-start", {
     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, then retry. Reads may be performed in any order within the current session. If nextActions includes planner-project-guidelines-show, read that section and keep it in working memory while doing task work. 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) },
@@ -2347,10 +2375,19 @@ server.registerTool("planner-task-start", {
             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") {
+            let claimed;
+            try {
+                claimed = await st.claimTask(found.phase.id, found.task.id, plannerSessionId);
+            }
+            catch (error) {
+                if (!(error instanceof PlanStoreError))
+                    throw error;
+                return taskStartError(taskStartDenied(error.details?.errorCode, error.message, ["Continue with the owning caller, or use planner-session-recover after confirming it has stopped."], { taskId: found.task.id }));
+            }
             const outcome = taskStartSucceeded(found.task.id, true);
             const higherPriorityPhase = findHigherPriorityOpenPhase(initialPhases, features, found.phase.id, found.phase.priority ?? found.phase.number);
             const phaseOrderAdvisory = higherPriorityOpenPhaseAdvisory(higherPriorityPhase);
-            return text(`✅ Task already started: ${taskRef} — ${found.task.title} (in-progress)\nstarted: true${projectContextAdvisory}${phaseOrderAdvisory}`, { ...outcome, task: found.task, projectContextStale: projectContextReadState === "stale", higherPriorityOpenPhase: higherPriorityPhase });
+            return text(`✅ Task already started: ${taskRef} — ${found.task.title} (in-progress)\nstarted: true${projectContextAdvisory}${phaseOrderAdvisory}`, { ...outcome, task: claimed.task, projectContextStale: projectContextReadState === "stale", higherPriorityOpenPhase: higherPriorityPhase });
         }
         const [phases, focus] = await Promise.all([st.loadAllPhases(), st.loadResume(plannerSessionId)]);
         const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
@@ -2405,31 +2442,13 @@ server.registerTool("planner-task-start", {
             : "";
         const timestamp = nowISO();
         let updatedTask;
-        if (found.task.pauseSnapshot) {
-            updatedTask = await st.resumeTask(found.phase.id, found.task.id, timestamp, plannerSessionId);
+        try {
+            updatedTask = (await st.claimTask(found.phase.id, found.task.id, plannerSessionId, timestamp)).task;
         }
-        else {
-            await st.updatePhase(found.phase.id, (phase) => {
-                const task = phase.tasks.find((entry) => entry.id === found.task.id);
-                if (!task)
-                    return phase;
-                const previousStatus = task.status;
-                applyTaskLifecycleDates(task, "in-progress", timestamp);
-                const entry = {
-                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${previousStatus}-in-progress`),
-                    date: timestamp,
-                    fromStatus: previousStatus,
-                    toStatus: "in-progress",
-                    title: `${previousStatus} → in-progress`,
-                    description: "",
-                };
-                task.activeOwnerSession = plannerSessionId;
-                task.statusLog = [...(task.statusLog ?? []), entry];
-                task.updatedAt = timestamp;
-                phase.updatedAt = timestamp;
-                updatedTask = task;
-                return phase;
-            });
+        catch (error) {
+            if (!(error instanceof PlanStoreError))
+                throw error;
+            return taskStartError(taskStartDenied(error.details?.errorCode, error.message, ["Re-read the task and reconcile its owner before retrying."], { taskId: found.task.id }));
         }
         await st.syncTaskStatusRollup(found.phase.id);
         const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === found.task.id && deviation.state === "approved");
@@ -2443,7 +2462,7 @@ server.registerTool("planner-task-start", {
             await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
         await st.writeGenerated();
         const persistedTask = (await st.loadPhase(found.phase.id)).tasks.find((candidate) => candidate.id === found.task.id);
-        if (!updatedTask || persistedTask?.status !== "in-progress") {
+        if (!updatedTask || persistedTask?.status !== "in-progress" || persistedTask.activeOwnerSession !== plannerSessionId) {
             return taskStartError(taskStartDenied("PERSISTENCE_VERIFICATION_FAILED", `The lifecycle write could not be verified as in-progress for ${taskRef}.`, ["Inspect planner-task-show for the persisted state and retry only after resolving the persistence failure."], { taskId: found.task.id }));
         }
         const outcome = taskStartSucceeded(persistedTask.id);
@@ -3164,6 +3183,7 @@ server.registerTool("planner-load", {
         return text(`Planner load aborted: ${error instanceof Error ? error.message : String(error)}`, { errorCode: "PLANNER_SESSION_PREPARATION_FAILED", loaded: false });
     }
     const project = preparation.project;
+    await st.runBatch(() => st.refreshResume(undefined, undefined, plannerSessionId));
     if (project.projectGuidelines.content.trim()) {
         await st.recordProjectGuidelinesRead({ sessionId: plannerSessionId });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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.4.6",
-    "@agent-plan/server": "0.4.6"
+    "@agent-plan/server": "0.4.8",
+    "@agent-plan/core": "0.4.8"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",