@osolmaz/pi-workflows 0.11.2 → 0.12.0

package/dist/extension/index.js

@@ -14,6 +14,8 @@ import { appendProgressHistory, progressRecordsFromTrace } from "../workflows/pr
 import { createRunId, listRunBundles, readLastTraceEvent, readRunBundle, WorkflowRunStore, createDefinitionSnapshot, } from "../workflows/store.js";
 import { PiControllerHost, parseControllerArgs, } from "./controller-host.js";
 import { PiDecisionChannel, TelegramDecisionChannel, audienceChannels, createTelegramChannels, loadDecisionChannelConfig, verifyTelegramTokenFile, writeDecisionChannelProfile, } from "./decision-channels.js";
+import { DeferredTurnCoordinator, } from "./deferred-turn-coordinator.js";
+import { buildDeferredTurnContent, createDeferredTurnDescriptor, DEFERRED_TURN_MESSAGE_TYPE, deferredTurnMessageDetails, deferredTurnMessageId, deferredTurnSourceEventId, } from "./deferred-turn.js";
 import { ConversationStepExecutor } from "./executor.js";
 import { HerdrWorkflowViewer, parseViewerPlacement, PIW_SHORTCUT, PIW_SHORTCUT_HINT, VIEWER_PLACEMENTS, } from "./herdr-viewer.js";
 import { SessionRecorder } from "./recorder.js";
@@ -25,8 +27,10 @@ const RUN_CLAIM_LEASE_MS = 30_000;
 const RUN_CLAIM_RENEW_MS = 10_000;
 const RUN_SYNC_POLL_MS = 3_000;
 const NOTIFICATION_DELIVERY_LEASE_MS = 30_000;
+const TURN_INTENT_DELIVERY_LEASE_MS = 30_000;
 const WIDGET_KEY = "pi-workflows";
 const PRESENTATION_MESSAGE_TYPE = "pi-workflows-presentation";
+const PRESENTATION_MESSAGE_SCHEMA = "pi-workflows.presentation-message.v1";
 const FINAL_WIDGET_TTL_MS = 60_000;
 const WIDGET_SCROLL_STEP = 3;
 const MAX_PRESENTATION_RESULT_CHARS = 50_000;
@@ -220,6 +224,7 @@ export default function piWorkflows(pi) {
     let activationRecovery;
     let decisionRecoveryTimer = null;
     let decisionRecoveryActive = false;
+    let turnCoordinator;
     const recordRunEvent = (event) => {
         try {
             runQueueStore?.recordRunEvent({ ...event, runnerId });
@@ -266,9 +271,7 @@ export default function piWorkflows(pi) {
                             runId: notification.runId,
                             kind: notification.kind,
                         },
-                    }, notification.kind === "launch_failure"
-                        ? { triggerTurn: true, deliverAs: "followUp" }
-                        : { triggerTurn: false });
+                    }, { triggerTurn: false });
                     alreadyDelivered.add(notification.notificationId);
                 }
                 runQueueStore.markWorkflowNotificationDelivered({
@@ -277,6 +280,19 @@ export default function piWorkflows(pi) {
                     claimToken,
                 });
             }
+            const idle = ctx.isIdle() && systemTurnAbort === null && !sessionClosed && !runHeld();
+            turnCoordinator.flushNatural(idle);
+            turnCoordinator.deliverFallbacks({
+                targetSessionId: sessionId,
+                send: (intent) => {
+                    pi.sendMessage({
+                        customType: DEFERRED_TURN_MESSAGE_TYPE,
+                        content: buildDeferredTurnContent(intent),
+                        display: true,
+                        details: deferredTurnMessageDetails(intent),
+                    }, { triggerTurn: true, deliverAs: "followUp" });
+                },
+            }, idle);
         }
         catch {
             // Delivery retries on the next poll. It never affects workflow execution.
@@ -312,6 +328,35 @@ export default function piWorkflows(pi) {
     let presentationPending = null;
     let controllerHost;
     let controllerContext = null;
+    const branchIntentResolution = (intentId) => {
+        if (controllerContext === null)
+            return null;
+        for (const entry of controllerContext.sessionManager.getBranch()) {
+            if (entry.type !== "custom_message")
+                continue;
+            const details = entry.details;
+            if (details === null || typeof details !== "object" || Array.isArray(details))
+                continue;
+            if (details.turnIntentId !== intentId)
+                continue;
+            let resolution = null;
+            if (entry.customType === WORKFLOW_AGENT_STEP_MESSAGE_TYPE)
+                resolution = "workflowPrompt";
+            if (entry.customType === PRESENTATION_MESSAGE_TYPE)
+                resolution = "presentation";
+            if (entry.customType === DEFERRED_TURN_MESSAGE_TYPE)
+                resolution = "fallback";
+            if (resolution !== null) {
+                return { resolution, messageId: deferredTurnMessageId(intentId, resolution) };
+            }
+        }
+        return null;
+    };
+    turnCoordinator = new DeferredTurnCoordinator({
+        store: () => runQueueStore,
+        branchResolution: branchIntentResolution,
+        leaseMs: TURN_INTENT_DELIVERY_LEASE_MS,
+    });
     // UI updates are best-effort: a captured ctx becomes stale after session
     // replacement or shutdown, and pi throws on any access (even `ctx.hasUI`).
     // A workflow finishing right as the session goes away must not crash pi.
@@ -352,6 +397,115 @@ export default function piWorkflows(pi) {
     };
     /** True when the run is held for the user (escape or /workflow pause). */
     const runHeld = () => activeRun !== null && (activeRun.engine.pauseRequested || activeRun.executor.held);
+    const originSessionId = (ctx, runId) => ensureRunQueueStore(ctx.cwd).getWorkflowRun(runId)?.originSessionId ??
+        ctx.sessionManager.getSessionId();
+    const storeTurnDescriptor = (ctx, descriptor, eligible) => {
+        ensureRunQueueStore(ctx.cwd).ensureWorkflowTurnIntent({ ...descriptor, eligible });
+    };
+    const ensureAbortTurnIntent = (ctx, run, cause, contract, reason) => {
+        if (run.abortProvenance?.descriptor !== undefined) {
+            return run.abortProvenance.descriptor;
+        }
+        const descriptor = createDeferredTurnDescriptor({
+            runId: run.runId,
+            workflowName: run.workflowName,
+            targetSessionId: originSessionId(ctx, run.runId),
+            cause,
+            sourceEventId: deferredTurnSourceEventId({
+                runId: run.runId,
+                cause,
+                nodeId: contract.nodeId,
+                attemptId: contract.attemptId,
+                source: "agent-step-abort",
+            }),
+            observedState: cause === "claimLost" ? "handedOff" : "interrupted",
+            nodeId: contract.nodeId,
+            attemptId: contract.attemptId,
+            reason: errorMessage(reason),
+            handoff: cause === "claimLost",
+        });
+        run.abortProvenance = { cause, descriptor };
+        try {
+            storeTurnDescriptor(ctx, descriptor, false);
+        }
+        catch (error) {
+            run.abortProvenance.storageError = errorMessage(error);
+        }
+        return descriptor;
+    };
+    const makeRunTurnIntentEligible = (ctx, run, observedState, reason) => {
+        if (sessionClosed ||
+            run.suppressTurnIntent === true ||
+            run.abortProvenance?.cause === "claimLost") {
+            return;
+        }
+        const targetSessionId = originSessionId(ctx, run.runId);
+        const pending = ensureRunQueueStore(ctx.cwd).findPendingWorkflowTurnIntent({
+            runId: run.runId,
+            targetSessionId,
+        });
+        if (run.childKey !== undefined &&
+            run.abortProvenance === undefined &&
+            pending?.cause !== "claimLost") {
+            return;
+        }
+        const cause = pending?.cause ??
+            run.abortProvenance?.cause ??
+            (observedState === "timed_out" ? "timedOut" : "failed");
+        if (observedState === "cancelled" &&
+            run.abortProvenance === undefined &&
+            pending === undefined) {
+            return;
+        }
+        const previous = run.abortProvenance?.descriptor;
+        const sourceEventId = pending?.sourceEventId ??
+            previous?.sourceEventId ??
+            deferredTurnSourceEventId({
+                runId: run.runId,
+                cause,
+                nodeId: "$terminal",
+                source: "terminal",
+            });
+        const descriptor = createDeferredTurnDescriptor({
+            runId: run.runId,
+            workflowName: pending?.workflowRef ?? run.workflowName,
+            targetSessionId,
+            cause,
+            sourceEventId,
+            observedState,
+            nodeId: pending?.nodeId ?? previous?.nodeId ?? "$terminal",
+            attemptId: pending?.attemptId ?? previous?.attemptId ?? null,
+            reason: reason ?? null,
+            handoff: false,
+        });
+        run.abortProvenance = {
+            cause,
+            descriptor,
+            ...(run.abortProvenance?.storageError === undefined
+                ? {}
+                : { storageError: run.abortProvenance.storageError }),
+        };
+        try {
+            storeTurnDescriptor(ctx, descriptor, false);
+            ensureRunQueueStore(ctx.cwd).makeWorkflowTurnIntentEligible({
+                intentId: descriptor.intentId,
+                fallbackFacts: descriptor.fallbackFacts,
+            });
+            delete run.abortProvenance.storageError;
+            syncArmed = true;
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            run.abortProvenance.storageError = message;
+            recordRunEvent({
+                runId: run.runId,
+                workflowRef: run.workflowName,
+                type: "turn_intent_failed",
+                payload: { error: message },
+            });
+            notify(ctx, `Workflow ${run.workflowName} ended, but Pi Workflows could not preserve its successor turn: ${message}`, "warning");
+        }
+    };
     const footerStatus = (state) => {
         const label = runHeld() || state.paused ? "paused" : state.status;
         const node = state.currentNode ?? state.waitingOn;
@@ -512,20 +666,36 @@ export default function piWorkflows(pi) {
             const instructions = typeof run.presentationPrompt === "function"
                 ? await resolvePresentationPrompt(run.presentationPrompt, state, abort.signal)
                 : run.presentationPrompt;
-            if (sessionClosed ||
-                run.generation !== runGeneration ||
-                abort.signal.aborted ||
-                instructions === undefined ||
-                instructions.trim().length === 0) {
+            if (sessionClosed || run.generation !== runGeneration || abort.signal.aborted) {
                 return;
             }
-            presentationPending = run.generation;
-            suppressWorkflowAssistantTail = false;
-            pi.sendMessage({
-                customType: PRESENTATION_MESSAGE_TYPE,
-                content: buildPresentationMessage(instructions, state),
-                display: false,
-            }, { deliverAs: "steer", triggerTurn: true });
+            if (instructions === undefined || instructions.trim().length === 0) {
+                if (run.abortProvenance !== undefined) {
+                    makeRunTurnIntentEligible(ctx, run, state.status, "No result presentation was available");
+                }
+                return;
+            }
+            turnCoordinator.sendNatural({
+                runId: run.runId,
+                targetSessionId: originSessionId(ctx, run.runId),
+                resolution: "presentation",
+                send: (turnIntentId) => {
+                    presentationPending = run.generation;
+                    suppressWorkflowAssistantTail = false;
+                    pi.sendMessage({
+                        customType: PRESENTATION_MESSAGE_TYPE,
+                        content: buildPresentationMessage(instructions, state),
+                        display: false,
+                        details: {
+                            schema: PRESENTATION_MESSAGE_SCHEMA,
+                            ...(turnIntentId === undefined ? {} : { turnIntentId }),
+                        },
+                    }, {
+                        deliverAs: turnIntentId === undefined ? "steer" : "followUp",
+                        triggerTurn: true,
+                    });
+                },
+            }, ctx.isIdle() && systemTurnAbort === null);
         }
         catch (error) {
             if (presentationPending === run.generation) {
@@ -540,6 +710,9 @@ export default function piWorkflows(pi) {
                 ? `timed out after ${PRESENTATION_TIMEOUT_MS}ms`
                 : errorMessage(error);
             notify(ctx, `Could not present workflow result: ${message}`, "warning");
+            if (run.abortProvenance !== undefined) {
+                makeRunTurnIntentEligible(ctx, run, state.status, message);
+            }
         }
         finally {
             clearTimeout(timer);
@@ -590,6 +763,19 @@ export default function piWorkflows(pi) {
             clearWidget(ctx);
             return;
         }
+        if (run.abortProvenance?.cause === "claimLost") {
+            await run.recorder?.stop().catch(() => undefined);
+            releaseClaim(run, "lost");
+            recordRunEvent({
+                runId: run.runId,
+                workflowRef: run.workflowName,
+                type: "claim_lost",
+            });
+            stopWidgetTicker();
+            clearWidget(ctx);
+            notify(ctx, `Workflow ${run.workflowName} continues under another runner (run ${run.runId}).`);
+            return;
+        }
         releaseClaim(run, "done");
         recordRunEvent({
             runId: run.runId,
@@ -638,6 +824,14 @@ export default function piWorkflows(pi) {
         catch (error) {
             notify(ctx, `Could not record child workflow completion: ${errorMessage(error)}`, "warning");
         }
+        if (state.status === "failed" || state.status === "timed_out" || state.status === "cancelled") {
+            makeRunTurnIntentEligible(ctx, run, state.status, state.error);
+        }
+        else if (run.abortProvenance !== undefined &&
+            run.presentationPrompt === undefined &&
+            (state.status === "completed" || state.status === "waiting")) {
+            makeRunTurnIntentEligible(ctx, run, state.status, state.error);
+        }
         void presentRun(ctx, run, state);
         if (pendingDecision !== null && state.status === "waiting") {
             const channels = audienceChannels(decisionChannelConfig, pendingDecision.audience);
@@ -744,21 +938,29 @@ export default function piWorkflows(pi) {
         }
         const executor = new ConversationStepExecutor({
             sendPrompt: ({ prompt, contract, presentation, kind, streaming }) => {
-                const details = {
-                    schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
-                    kind,
-                    contract,
-                    ...(presentation !== undefined ? { presentation } : {}),
-                };
-                pi.sendMessage({
-                    customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
-                    content: prompt,
-                    display: true,
-                    details,
-                }, {
-                    triggerTurn: true,
-                    deliverAs: streaming ? "steer" : "followUp",
-                });
+                turnCoordinator.sendNatural({
+                    runId,
+                    targetSessionId: originSessionId(ctx, runId),
+                    resolution: "workflowPrompt",
+                    send: (turnIntentId) => {
+                        const details = {
+                            schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
+                            kind,
+                            contract,
+                            ...(presentation !== undefined ? { presentation } : {}),
+                            ...(turnIntentId === undefined ? {} : { turnIntentId }),
+                        };
+                        pi.sendMessage({
+                            customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
+                            content: prompt,
+                            display: true,
+                            details,
+                        }, {
+                            triggerTurn: true,
+                            deliverAs: streaming ? "steer" : "followUp",
+                        });
+                    },
+                }, ctx.isIdle() && systemTurnAbort === null);
             },
             onAbort: (contract, reason) => {
                 lastExpiredAttempt = {
@@ -766,7 +968,15 @@ export default function piWorkflows(pi) {
                     reason: reason instanceof TimeoutError ? "timed out" : `ended: ${errorMessage(reason)}`,
                 };
                 if (!executor.held && !ctx.isIdle()) {
-                    systemTurnAbort = contract;
+                    const cause = reason instanceof TimeoutError ? "timedOut" : run.pendingAbortCause;
+                    const descriptor = cause === undefined
+                        ? undefined
+                        : ensureAbortTurnIntent(ctx, run, cause, contract, reason);
+                    run.pendingAbortCause = undefined;
+                    systemTurnAbort = {
+                        contract,
+                        ...(descriptor === undefined ? {} : { intentId: descriptor.intentId }),
+                    };
                     ctx.abort();
                 }
             },
@@ -859,6 +1069,7 @@ export default function piWorkflows(pi) {
             run.renewTimer = setInterval(() => {
                 try {
                     if (!store.renewWorkflowRunClaim({ runId, claimToken: token, leaseMs: RUN_CLAIM_LEASE_MS })) {
+                        run.pendingAbortCause = "claimLost";
                         run.engine.cancel();
                     }
                 }
@@ -952,6 +1163,11 @@ export default function piWorkflows(pi) {
             }
             if (terminalStatus !== undefined) {
                 recordRunEvent({ runId, workflowRef: workflow.name, type: terminalStatus, payload: {} });
+                if (terminalStatus === "failed" ||
+                    terminalStatus === "timed_out" ||
+                    terminalStatus === "cancelled") {
+                    makeRunTurnIntentEligible(ctx, run, terminalStatus, message);
+                }
                 notify(ctx, `Workflow ${workflow.name} ${terminalStatus} (run ${runId}).`);
                 return;
             }
@@ -961,6 +1177,7 @@ export default function piWorkflows(pi) {
                 type: "failed",
                 payload: { error: message },
             });
+            makeRunTurnIntentEligible(ctx, run, "failed", message);
             try {
                 run.onFinish?.({ state: "failed", runId, error: message });
             }
@@ -1155,10 +1372,12 @@ export default function piWorkflows(pi) {
         }
         return null;
     };
-    const cancelWorkflowControl = async (ctx, requestedRunId) => {
+    const cancelWorkflowControl = async (ctx, origin, requestedRunId) => {
         if (activeRun && (requestedRunId === undefined || requestedRunId === activeRun.runId)) {
             const workflowName = activeRun.workflowName;
             const runId = activeRun.runId;
+            activeRun.pendingAbortCause = origin === "agent" ? "agentCancelled" : undefined;
+            activeRun.suppressTurnIntent = origin === "user";
             activeRun.engine.cancel();
             return {
                 message: `Cancelling workflow ${workflowName}…`,
@@ -1250,6 +1469,7 @@ export default function piWorkflows(pi) {
                 },
             };
         }
+        activeRun.suppressTurnIntent = true;
         activeRun.engine.pause();
         renderWidget(ctx);
         return {
@@ -1282,6 +1502,7 @@ export default function piWorkflows(pi) {
                 level: "warning",
             };
         }
+        activeRun.suppressTurnIntent = false;
         activeRun.engine.resume();
         activeRun.executor.release();
         renderWidget(ctx);
@@ -1758,20 +1979,28 @@ export default function piWorkflows(pi) {
                 payload: { errorCode: safe.code, error: safe.message },
             });
             const content = `Workflow ${claimed.workflowName} failed to start (run ${claimed.runId}): ${safe.message}. Inspect the error and call workflow start again only after you correct the cause.`;
-            try {
-                queue.enqueueWorkflowNotification({
+            const cause = "launchFailed";
+            const descriptor = createDeferredTurnDescriptor({
+                runId: claimed.runId,
+                workflowName: claimed.workflowName,
+                targetSessionId: claimed.originSessionId ?? ctx.sessionManager.getSessionId(),
+                cause,
+                sourceEventId: deferredTurnSourceEventId({
                     runId: claimed.runId,
+                    cause,
                     nodeId: "$launch",
-                    attemptId: claimed.runId,
-                    notificationIndex: 1,
-                    targetSessionId: claimed.originSessionId ?? ctx.sessionManager.getSessionId(),
-                    kind: "launch_failure",
-                    content,
-                    notificationId: `launch-failure:${claimed.runId}`,
-                });
+                    source: "queued-launch",
+                }),
+                observedState: "failedToStart",
+                nodeId: "$launch",
+                reason: safe.message,
+            });
+            try {
+                storeTurnDescriptor(ctx, descriptor, true);
+                syncArmed = true;
             }
-            catch {
-                // A deterministic notification id makes duplicate insertion harmless.
+            catch (intentError) {
+                notify(ctx, `Workflow ${claimed.workflowName} failed to start, but Pi Workflows could not preserve its successor turn: ${errorMessage(intentError)}`, "warning");
             }
             notify(ctx, content, "error");
             runSyncPass(ctx);
@@ -1830,7 +2059,7 @@ export default function piWorkflows(pi) {
                 return;
             }
             if (parsed.kind === "cancel") {
-                const result = await cancelWorkflowControl(ctx);
+                const result = await cancelWorkflowControl(ctx, "user");
                 notify(ctx, result.message, result.level);
                 return;
             }
@@ -1990,6 +2219,7 @@ export default function piWorkflows(pi) {
                     case "stop":
                         if (activeRun?.childKey !== undefined) {
                             activeRun.interruptionRequested = true;
+                            activeRun.pendingAbortCause = "controllerInterrupted";
                             activeRun.engine.cancel();
                         }
                         await host.stop();
@@ -2006,7 +2236,7 @@ export default function piWorkflows(pi) {
         name: "workflow",
         label: "Workflow",
         description: [
-            "List, start, inspect, pause, resume, cancel, answer, update, or complete Pi Workflows runs.",
+            "List, start, inspect, pause, resume, cancel, answer, update, or complete pi-workflows runs.",
             "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, everyMinutes, stopWhen, and optional maxChecks.",
             "Use update or submit only when a workflow step contract asks for it, and pass the exact step and attempt ids.",
             "Do not start repeated work without the user's request, and keep monitoring observation-only unless the user authorizes mutations.",
@@ -2032,7 +2262,7 @@ export default function piWorkflows(pi) {
                     control = resumeWorkflowControl(ctx);
                     break;
                 case "cancel":
-                    control = await cancelWorkflowControl(ctx, params.runId);
+                    control = await cancelWorkflowControl(ctx, "agent", params.runId);
                     break;
                 case "answer": {
                     const waiting = await resolveWaitingWorkflow(ctx, params.runId);
@@ -2190,6 +2420,7 @@ export default function piWorkflows(pi) {
         if (!aborted || runHeld()) {
             return;
         }
+        run.suppressTurnIntent = true;
         run.engine.pause();
         run.executor.hold();
         renderWidget(ctx);
@@ -2228,6 +2459,7 @@ export default function piWorkflows(pi) {
         activeRun?.recorder?.handleToolEnd(event);
     });
     pi.on("agent_settled", async (_event, ctx) => {
+        systemTurnAbort = null;
         if (activeRun === null) {
             try {
                 const prepared = ensureRunQueueStore(ctx.cwd).findSessionReservation(ctx.sessionManager.getSessionId());
@@ -2241,23 +2473,30 @@ export default function piWorkflows(pi) {
                 return;
             }
         }
+        const flushedNatural = turnCoordinator.flushNatural(ctx.isIdle() && !sessionClosed && !runHeld());
         const run = activeRun;
         if (!run) {
             presentationPending = null;
+            runSyncPass(ctx);
             return;
         }
         await run.recorder?.synchronize(ctx).catch(() => undefined);
         run.recorder?.settleAttempt();
         run.executor.setStreaming(false);
-        run.executor.handleAgentSettled();
+        if (flushedNatural === 0)
+            run.executor.handleAgentSettled();
+        runSyncPass(ctx);
     });
     pi.on("session_shutdown", async () => {
         sessionClosed = true;
         herdrProbeGeneration += 1;
         systemTurnAbort = null;
         suppressWorkflowAssistantTail = false;
+        turnCoordinator.clearDeferred();
         supersedePresentation();
         const run = activeRun;
+        if (run !== null)
+            run.suppressTurnIntent = true;
         if (run !== null && run.claimToken !== undefined) {
             // Queued interactive runs park: no terminal event, no recorded partial
             // attempt, and the claim releases so another runner can resume.