@agent-plan/pi-adapter 0.4.7 → 0.4.9

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;AAw0BtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA20K9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AAw0BtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAy2K9D"}

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 import { Type } from "typebox";
 import { paginatedSelect, paginatedNotify } from "./ui/paginate.js";
-import { ExportService, PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, classifyGuardedTool, loadNoTaskGuardState, noTaskWarning, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, 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_SOURCE_REVIEWS, HANDOFF_COLD_START_INVENTORY_CATEGORIES, handoffContentHash, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, buildPlannerLoadReply, buildScopedDecisionContext, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, ACCEPTED_DECISION_OWNERSHIP_RULE, ACCEPTED_DECISION_RAW_REPLACEMENT_DISABLED_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED_ERROR_CODE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildDecisionRecordRedirectReply, 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, statusIcon, moveTasks, buildTaskMoveReply } from "@agent-plan/core";
+import { ExportService, PlanStore, PlanStoreError, taskOwnershipConflict, setWriteBusyHook, setWriteNotifyHook, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, classifyGuardedTool, loadNoTaskGuardState, noTaskWarning, addChecklistItem, removeChecklistItem, toggleChecklistItem, replaceChecklist, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, isStartableTaskStatus, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, 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_SOURCE_REVIEWS, HANDOFF_COLD_START_INVENTORY_CATEGORIES, handoffContentHash, HandoffContractError, buildHandoffShowReply, buildHandoffPrepareReply, buildProjectContextLoadReply, buildPlannerLoadReply, buildScopedDecisionContext, DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS, projectContextStaleAdvisory, ACCEPTED_DECISION_OWNERSHIP_RULE, ACCEPTED_DECISION_RAW_REPLACEMENT_DISABLED_MESSAGE, LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE, ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED_ERROR_CODE, LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE, buildDecisionRecordRedirectReply, 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, statusIcon, moveTasks, buildTaskMoveReply } from "@agent-plan/core";
 import { createChecklistItemId, createFeatureId, createPhaseId, createRequirementId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, formatIdeaRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 /** Stated on every long-prose input so a caller learns the limit before the
  * call rather than from the rejection. The number lives in the core
@@ -775,6 +775,37 @@ async function stopServer() {
 // ─── Extension factory ──────────────────────────────────────────────────
 export default function planPiExtension(pi) {
     capturedPi = pi;
+    const registerSessionTool = pi.registerTool.bind(pi);
+    const sessionTools = new Set(["planner-load", "task_start", "task_switch", "task_pause", "task_complete", "task_reopen", "task_update", "task_deviation", "session_recover"]);
+    const registeredSessions = new Set();
+    pi.registerTool = (definition) => {
+        if (!sessionTools.has(definition.name))
+            return registerSessionTool(definition);
+        const execute = definition.execute;
+        registerSessionTool({ ...definition, async execute(id, params, signal, onUpdate, ctx) {
+                const st = await requirePlan(ctx);
+                if (!st)
+                    return execute(id, params, signal, onUpdate, ctx);
+                const sessionId = piSessionIdOf(ctx);
+                const prepare = async () => {
+                    if (!registeredSessions.has(sessionId)) {
+                        await st.registerSession(sessionId);
+                        registeredSessions.add(sessionId);
+                    }
+                };
+                if (definition.name === "planner-load") {
+                    await st.runBatch(prepare);
+                    return execute(id, params, signal, onUpdate, ctx);
+                }
+                return st.runBatch(async () => {
+                    await prepare();
+                    const result = await execute(id, params, signal, onUpdate, ctx);
+                    if (!result.isError)
+                        await st.refreshResume(undefined, undefined, sessionId);
+                    return result;
+                });
+            } });
+    };
     // ── Restore on session start/reload ─────────────────────────────────
     pi.on("session_start", async (_event, ctx) => {
         plannerSessionId = piSessionIdOf(ctx);
@@ -5468,7 +5499,7 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: `No resume task is available. Provide resume_task explicitly. ${selected.reason}` }], details: selected };
             if (temporary.task.id === resume.task.id)
                 return { content: [{ type: "text", text: "A temporary task must differ from its resume target." }], details: {} };
-            if (temporary.task.status !== "planned")
+            if (!isStartableTaskStatus(temporary.task.status))
                 return { content: [{ type: "text", text: `Temporary task is not startable: ${temporary.task.status}.` }], details: {} };
             const timestamp = nowISO();
             const record = {
@@ -5570,6 +5601,10 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: `Task not found: ${params.to_task}` }], details: {} };
             if (source.task.id === target.task.id)
                 return { content: [{ type: "text", text: "Source and temporary task must differ." }], details: {} };
+            const allDeviations = await st.listAllWorkDeviations();
+            if ([source.task, target.task].some((task) => taskOwnershipConflict(task, allDeviations, plannerSessionId))) {
+                return { content: [{ type: "text", text: "Task switch denied: source or target belongs to another session." }], details: { started: false, errorCode: "TASK_OWNED_BY_ANOTHER_SESSION" }, isError: true };
+            }
             if (source.task.status !== "in-progress" && !source.task.pauseSnapshot) {
                 return { content: [{ type: "text", text: `Task switch denied: source is ${source.task.status}; only in-progress or checkpointed work can be switched.` }], details: {} };
             }
@@ -5655,27 +5690,7 @@ export default function planPiExtension(pi) {
                         });
                     }
                     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: ${params.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) {
@@ -5749,6 +5764,27 @@ export default function planPiExtension(pi) {
             }
         },
     });
+    pi.registerTool({
+        name: "session_recover",
+        label: "Session Recover",
+        description: "Explicitly recover a stopped caller's complete task ownership, return stack and focus into this fresh session. Confirm that the previous caller has stopped. Registered live processes and callers that already own work are refused. Then read context and use task_start normally.",
+        parameters: Type.Object({ taskId: Type.String(), confirmed: Type.Boolean() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No planner found." }], details: { recovered: false, errorCode: "PLAN_NOT_FOUND" }, isError: true };
+            const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, params.taskId);
+            if (!found)
+                return { content: [{ type: "text", text: "Task not found." }], details: { recovered: false, errorCode: "TASK_NOT_FOUND" }, isError: true };
+            try {
+                const recovered = await st.recoverSessionForTask(found.phase.id, found.task.id, piSessionIdOf(ctx), params.confirmed);
+                return { content: [{ type: "text", text: "Session recovered; tasks, checkpoints and return stack are preserved. Read task context before continuing." }], details: { recovered: true, ...recovered } };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Session recovery denied: ${error instanceof Error ? error.message : String(error)}` }], details: { recovered: false, errorCode: error instanceof PlanStoreError ? error.details?.errorCode ?? "SESSION_RECOVERY_FAILED" : "SESSION_RECOVERY_FAILED" }, isError: true };
+            }
+        },
+    });
     pi.registerTool({
         name: "task_start",
         label: "Task Start",
@@ -5822,10 +5858,20 @@ export default function planPiExtension(pi) {
                     });
                 }
                 if (task.status === "in-progress") {
+                    let claimed;
+                    try {
+                        claimed = await st.claimTask(found.phase.id, task.id, plannerSessionId);
+                    }
+                    catch (error) {
+                        if (!(error instanceof PlanStoreError))
+                            throw error;
+                        return taskStartFailure(taskStartDenied(error.details?.errorCode, error.message, ["Continue with the owning caller, or explicitly recover its session after it has stopped."], { taskId: task.id }));
+                    }
+                    await st.refreshResume(undefined, undefined, plannerSessionId);
                     const outcome = taskStartSucceeded(task.id, true);
                     const higherPriorityPhase = findHigherPriorityOpenPhase(initialPhases, features, found.phase.id, found.phase.priority ?? found.phase.number);
                     const phaseOrderAdvisory = higherPriorityOpenPhaseAdvisory(higherPriorityPhase);
-                    return { content: [{ type: "text", text: `✅ Task already started: ${taskRef} — ${task.title} (in-progress)\nstarted: true${projectContextAdvisory}${phaseOrderAdvisory}` }], details: { ...task, ...outcome, task, projectContextStale: projectContextReadState === "stale", higherPriorityOpenPhase: higherPriorityPhase } };
+                    return { content: [{ type: "text", text: `✅ Task already started: ${taskRef} — ${task.title} (in-progress)\nstarted: true${projectContextAdvisory}${phaseOrderAdvisory}` }], details: { ...claimed.task, ...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, task.id, project.workDeviations);
@@ -5876,27 +5922,13 @@ export default function planPiExtension(pi) {
                     : "";
                 const now = nowISO();
                 let startedTask;
-                if (task.pauseSnapshot) {
-                    startedTask = await st.resumeTask(found.phase.id, found.task.id, now, plannerSessionId);
+                try {
+                    startedTask = (await st.claimTask(found.phase.id, found.task.id, plannerSessionId, now)).task;
                 }
-                else {
-                    await st.updatePhase(found.phase.id, (phase) => {
-                        const t = phase.tasks.find((x) => x.id === found.task.id);
-                        if (!t)
-                            return phase;
-                        const previousStatus = t.status;
-                        applyTaskLifecycleDates(t, "in-progress", now);
-                        t.activeOwnerSession = plannerSessionId;
-                        t.statusLog = [...t.statusLog, {
-                                id: createChecklistItemId(t.id, t.statusLog.length + 1, `${previousStatus}-in-progress`),
-                                date: now, fromStatus: previousStatus, toStatus: "in-progress",
-                                title: `${previousStatus} → in-progress`, description: "",
-                            }];
-                        t.updatedAt = now;
-                        phase.updatedAt = now;
-                        startedTask = t;
-                        return phase;
-                    });
+                catch (error) {
+                    if (!(error instanceof PlanStoreError))
+                        throw error;
+                    return taskStartFailure(taskStartDenied(error.details?.errorCode, error.message, ["Re-read the task and reconcile its owner before retrying."], { taskId: task.id }));
                 }
                 await st.syncTaskStatusRollup(found.phase.id);
                 const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === task.id && deviation.state === "approved");
@@ -5910,10 +5942,11 @@ export default function planPiExtension(pi) {
                     await st.setWorkDeviationState(resumedDeviation.id, "resumed", now);
                 await st.writeGenerated();
                 const persistedTask = (await st.loadPhase(found.phase.id)).tasks.find((candidate) => candidate.id === task.id);
-                if (!startedTask || persistedTask?.status !== "in-progress") {
+                if (!startedTask || persistedTask?.status !== "in-progress" || persistedTask.activeOwnerSession !== plannerSessionId) {
                     return taskStartFailure(taskStartDenied("PERSISTENCE_VERIFICATION_FAILED", `The lifecycle write could not be verified as in-progress for ${taskRef}.`, ["Inspect task_get for the persisted state and retry task_start only after resolving the persistence failure."], { taskId: task.id }));
                 }
                 const outcome = taskStartSucceeded(persistedTask.id);
+                await st.refreshResume(undefined, undefined, plannerSessionId);
                 const higherPriorityPhase = findHigherPriorityOpenPhase(phases, features, found.phase.id, found.phase.priority ?? found.phase.number);
                 const phaseOrderAdvisory = higherPriorityOpenPhaseAdvisory(higherPriorityPhase);
                 return {
@@ -6199,6 +6232,7 @@ export default function planPiExtension(pi) {
             catch (error) {
                 return { content: [{ type: "text", text: `Planner load aborted: ${error instanceof Error ? error.message : String(error)}` }], details: { errorCode: "PLANNER_SESSION_PREPARATION_FAILED", enabled: false, running: false } };
             }
+            await st.runBatch(() => st.refreshResume(undefined, undefined, piSessionIdOf(ctx)));
             enablePlannerSession();
             if (!server) {
                 await startServer(ctx, undefined, "lan").catch(() => { });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/pi-adapter",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "private": false,
   "description": "Pi agent extension for Agent Plan — structured project planning in .planner/",
   "keywords": [
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "zod": "^3.24.0",
-    "@agent-plan/server": "0.4.7",
-    "@agent-plan/core": "0.4.7"
+    "@agent-plan/core": "0.4.9",
+    "@agent-plan/server": "0.4.9"
   },
   "peerDependencies": {
     "typebox": "*"