@osolmaz/pi-workflows 0.14.0 → 0.15.1

package/dist/workflows/engine.js

@@ -5,7 +5,7 @@ import { StaleResourceError } from "../state/mutation.js";
 import { compileWorkflowDefinition, compositionMetadata, isCompiledWorkflow, } from "./composition.js";
 import { CancelledError, errorMessage, isAbortLikeError, isClaimLostError, isRunParkedError, RunParkedError, TimeoutError, WorkflowSourceChangedError, } from "./errors.js";
 import { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
-import { HumanDecisionStore, createHumanDecisionRequest, validateHumanDecisionResponse, } from "./human-decision.js";
+import { createHumanDecisionRequest, validateHumanDecisionResponse } from "./human-decision.js";
 import { extractJsonValue } from "./json.js";
 import { parseWorkflowSettingsValue, resolveInitialWorkflowSettings, } from "./settings.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
@@ -173,6 +173,8 @@ export class WorkflowEngine {
             await this.executeGraph(workflow, state, runId);
         }
         catch (error) {
+            if (isClaimLostError(error))
+                throw error;
             if (isRunParkedError(error) || this.parked) {
                 return { runId, state };
             }
@@ -208,24 +210,29 @@ export class WorkflowEngine {
             state.currentAttemptId !== undefined &&
             state.currentNodeStartedAt !== undefined &&
             interruptedNode?.nodeType === "agent" &&
-            assistantMessageConfig(interruptedNode) !== undefined) {
-            const resumedSettings = this.persistedSettingsBinding(state);
+            (assistantMessageConfig(interruptedNode) !== undefined ||
+                options.resumeInteractionAttemptId === state.currentAttemptId)) {
+            const resumedSettings = await this.persistedSettingsBinding(state);
             resumedAttempt = {
                 nodeId: state.currentNode,
                 attemptId: state.currentAttemptId,
                 startedAt: state.currentNodeStartedAt,
+                ...(state.currentNodeDeadlineAt === undefined
+                    ? {}
+                    : { deadlineAt: state.currentNodeDeadlineAt }),
                 ...(resumedSettings !== undefined ? { settings: resumedSettings } : {}),
             };
         }
-        // A resumed run starts unpaused. Submitted and non-agent nodes discard
-        // stale in-flight markers and start a new attempt. Assistant-message
-        // nodes keep their attempt id so the origin session can adopt an already
-        // visible response without showing it twice.
+        // A resumed run starts unpaused. Submitted and non-agent nodes normally
+        // discard stale in-flight markers and start a new attempt. A submitted
+        // interaction and an assistant-message node keep their exact attempt id
+        // so durable origin-session work is never detached from its contract.
         delete state.paused;
         if (resumedAttempt === undefined) {
             delete state.currentNode;
             delete state.currentAttemptId;
             delete state.currentNodeStartedAt;
+            delete state.currentNodeDeadlineAt;
             delete state.currentSettingsScopeId;
             delete state.currentSettingsChangeNumber;
             delete state.currentSettingsHash;
@@ -267,6 +274,8 @@ export class WorkflowEngine {
             await this.executeGraph(workflow, state, runId, point.nodeId, countExecutableSteps(workflow, state.steps), point.lastOutput, resumedAttempt);
         }
         catch (error) {
+            if (isClaimLostError(error))
+                throw error;
             if (isRunParkedError(error) || this.parked) {
                 return { runId, state };
             }
@@ -287,7 +296,7 @@ export class WorkflowEngine {
         this.cancelled = false;
         this.paused = false;
         this.parked = false;
-        const parent = this.store.readRun(parentRunId);
+        const parent = await this.store.readRun(parentRunId);
         if (parent === null) {
             throw new Error(`Cannot continue from unreadable workflow run: ${parentRunId}`);
         }
@@ -314,9 +323,7 @@ export class WorkflowEngine {
                 request.requestDigest !== options.humanDecision.requestDigest) {
                 throw new Error("Accepted human decision does not match the waiting request");
             }
-            const durableDecision = await new HumanDecisionStore(this.store.databasePath, {
-                state: this.store.state,
-            }).readResolved(request.decisionId);
+            const durableDecision = await this.store.readResolvedHumanDecision(request.decisionId);
             if (durableDecision === null || !isDeepStrictEqual(durableDecision, options.humanDecision)) {
                 throw new Error("Accepted human decision does not match the durable decision record");
             }
@@ -393,6 +400,8 @@ export class WorkflowEngine {
             await this.executeGraph(workflow, state, runId, point.nodeId, countExecutableSteps(workflow, state.steps), point.lastOutput);
         }
         catch (error) {
+            if (isClaimLostError(error))
+                throw error;
             if (isRunParkedError(error) || this.parked) {
                 return { runId, state };
             }
@@ -741,6 +750,7 @@ export class WorkflowEngine {
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
+        delete state.currentNodeDeadlineAt;
         delete state.currentSettingsScopeId;
         delete state.currentSettingsChangeNumber;
         delete state.currentSettingsHash;
@@ -786,7 +796,7 @@ export class WorkflowEngine {
         }
         const meta = { promptText: null };
         try {
-            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings);
+            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, resumedAttempt?.deadlineAt);
             return {
                 result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
                 execution,
@@ -794,6 +804,8 @@ export class WorkflowEngine {
             };
         }
         catch (error) {
+            if (isRunParkedError(error) || isClaimLostError(error))
+                throw error;
             const outcome = this.outcomeForError(error);
             return {
                 result: {
@@ -834,7 +846,7 @@ export class WorkflowEngine {
             ...(output !== undefined ? { output } : {}),
         };
     }
-    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings) {
+    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, persistedDeadlineAt) {
         const abort = new AbortController();
         const context = this.createNodeContext(state, abort.signal, settings);
         let timer;
@@ -849,13 +861,54 @@ export class WorkflowEngine {
             if (this.cancelled) {
                 throw new CancelledError();
             }
-            const timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+            let timeoutMs;
+            let timeoutErrorMs;
+            if (persistedDeadlineAt === undefined) {
+                timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+                timeoutErrorMs = timeoutMs;
+                if (node.nodeType === "agent" && this.executor.preservesDeadlineWhileParked === true) {
+                    state.currentNodeDeadlineAt =
+                        timeoutMs === null ? null : new Date(Date.now() + timeoutMs).toISOString();
+                    await this.persist(runId, state, {
+                        scope: "node",
+                        type: "node_deadline_set",
+                        nodeId,
+                        attemptId,
+                        payload: { deadlineAt: state.currentNodeDeadlineAt },
+                    });
+                    if (state.currentNodeDeadlineAt !== null && timeoutErrorMs !== null) {
+                        timeoutMs = Date.parse(state.currentNodeDeadlineAt) - Date.now();
+                        if (timeoutMs <= 0)
+                            throw new TimeoutError(timeoutErrorMs);
+                    }
+                }
+                else {
+                    delete state.currentNodeDeadlineAt;
+                }
+            }
+            else if (persistedDeadlineAt === null) {
+                state.currentNodeDeadlineAt = null;
+                timeoutMs = null;
+                timeoutErrorMs = null;
+            }
+            else {
+                const deadline = Date.parse(persistedDeadlineAt);
+                const started = Date.parse(state.currentNodeStartedAt ?? persistedDeadlineAt);
+                if (!Number.isFinite(deadline) || !Number.isFinite(started)) {
+                    throw new Error("Persisted node deadline is invalid");
+                }
+                state.currentNodeDeadlineAt = persistedDeadlineAt;
+                timeoutMs = deadline - Date.now();
+                timeoutErrorMs = Math.max(1, deadline - started);
+                if (timeoutMs <= 0)
+                    throw new TimeoutError(timeoutErrorMs);
+            }
             if (abort.signal.aborted) {
                 throw abortError(abort.signal);
             }
-            if (timeoutMs !== null) {
+            if (timeoutMs !== null && timeoutErrorMs !== null) {
                 timer = setTimeout(() => {
-                    abort.abort(new TimeoutError(timeoutMs));
+                    abort.abort(new TimeoutError(timeoutErrorMs));
                 }, timeoutMs);
             }
             this.activeAttempt = {
@@ -988,7 +1041,7 @@ export class WorkflowEngine {
         if (definition === undefined)
             return undefined;
         const invocation = mountPath === "" ? 1 : currentMountInvocation(state, mountPath);
-        const existing = this.store.findSettingsScope(state.runId, mountPath, invocation);
+        const existing = await this.store.findSettingsScope(state.runId, mountPath, invocation);
         if (existing !== undefined)
             return existing;
         const input = mountPath === "" ? state.input : currentMountInput(state, mountPath);
@@ -996,21 +1049,21 @@ export class WorkflowEngine {
         const initial = mappedSettings.present
             ? await parseWorkflowSettingsValue(definition, mappedSettings.value)
             : await resolveInitialWorkflowSettings(definition, input);
-        return this.store.ensureSettingsScope({
+        return await this.store.ensureSettingsScope({
             runId: state.runId,
             mountPath,
             invocation,
             settings: initial.json,
         });
     }
-    persistedSettingsBinding(state) {
+    async persistedSettingsBinding(state) {
         if (state.currentSettingsScopeId === undefined)
             return undefined;
         if (state.currentSettingsChangeNumber === undefined ||
             state.currentSettingsHash === undefined) {
             throw new Error("Saved workflow settings binding is incomplete");
         }
-        const scope = this.store.getSettingsScopeAtChange(state.currentSettingsScopeId, state.currentSettingsChangeNumber);
+        const scope = await this.store.getSettingsScopeAtChange(state.currentSettingsScopeId, state.currentSettingsChangeNumber);
         if (scope === undefined) {
             throw new Error(`Saved workflow settings scope is missing: ${state.currentSettingsScopeId}`);
         }
@@ -1125,16 +1178,79 @@ export class WorkflowEngine {
         }
     }
     async runActionNode(node, context, nodeId, attemptId, signal, meta) {
+        /* istanbul ignore if -- graph validation rejects action nodes without managed effects */
+        if (node.effect === undefined) {
+            throw new Error(`Action node ${nodeId} must declare a managed effect with an explicit recovery policy`);
+        }
+        const effectType = node.effect.type.trim();
+        const idempotencyKey = typeof node.effect.idempotencyKey === "function"
+            ? await node.effect.idempotencyKey(context)
+            : node.effect.idempotencyKey;
+        const request = typeof node.effect.request === "function"
+            ? await node.effect.request(context)
+            : node.effect.request;
+        /* istanbul ignore if -- definition validation and effect helpers reject empty fields */
+        if (effectType.length === 0 || idempotencyKey.trim().length === 0) {
+            throw new Error("Managed effect type and idempotency key must be nonempty text");
+        }
+        canonicalJson(request);
+        const reservation = await this.store.reserveEffect({
+            runId: context.state.runId,
+            attemptId,
+            effectType,
+            idempotencyKey,
+            request: request,
+            recovery: node.effect.recovery,
+        });
+        if (reservation.disposition === "ambiguous")
+            throw new RunParkedError();
+        if (reservation.disposition === "adopted") {
+            const adopted = reservation.result;
+            if (adopted === null || typeof adopted !== "object" || Array.isArray(adopted)) {
+                throw new Error("Managed effect receipt is invalid");
+            }
+            const execution = adopted;
+            if (execution.action !== undefined)
+                meta.action = execution.action;
+            return execution;
+        }
         const actionContext = {
             ...context,
+            effect: { type: effectType, idempotencyKey, recovery: node.effect.recovery },
             publishUpdate: async (update) => await this.publishUpdate(nodeId, attemptId, update),
         };
-        if ("exec" in node) {
-            return await runShellActionNode(node, context, actionContext, signal, meta);
+        try {
+            let execution;
+            if ("exec" in node) {
+                execution = await runShellActionNode(node, actionContext, signal, meta);
+            }
+            else {
+                meta.action = { actionType: "function" };
+                const output = await node.run(actionContext);
+                execution = { output, promptText: null, action: { actionType: "function" } };
+            }
+            canonicalJson(execution);
+            await this.store.settleEffect({
+                runId: context.state.runId,
+                effectId: reservation.effectId,
+                attemptNumber: reservation.attemptNumber,
+                outcome: "applied",
+                result: execution,
+            });
+            return execution;
+        }
+        catch (error) {
+            if (isRunParkedError(error) || isClaimLostError(error))
+                throw error;
+            await this.store.settleEffect({
+                runId: context.state.runId,
+                effectId: reservation.effectId,
+                attemptNumber: reservation.attemptNumber,
+                outcome: "rejected",
+                error: errorMessage(error),
+            });
+            throw error;
         }
-        meta.action = { actionType: "function" };
-        const output = await node.run(actionContext);
-        return { output, promptText: null, action: { actionType: "function" } };
     }
     async persist(runId, state, event) {
         const traceEvent = await this.store.writeSnapshot(runId, state, event);
@@ -1145,19 +1261,12 @@ export class WorkflowEngine {
             // Observers (UI updates, loggers) must never determine workflow
             // correctness; a throwing observer would otherwise fail the run.
         }
+        await new Promise((resolve) => setImmediate(resolve));
     }
     async finishRun(runId, state, status, fields) {
         if (status === "failed" && state.status === "timed_out") {
             status = "timed_out";
         }
-        // Let observers (e.g. the session recorder) stop and drain before the
-        // terminal event exists, so the terminal fact is immutable from that point on.
-        try {
-            await this.onRunFinishing?.(runId, state);
-        }
-        catch {
-            // Finishing the run wins over observer failures.
-        }
         state.status = status;
         state.finishedAt = new Date().toISOString();
         if (fields.error !== undefined) {
@@ -1172,9 +1281,18 @@ export class WorkflowEngine {
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
+        delete state.currentNodeDeadlineAt;
         delete state.currentSettingsScopeId;
         delete state.currentSettingsChangeNumber;
         delete state.currentSettingsHash;
+        // Let observers stop, drain, and prepare terminal delivery from the final
+        // in-memory state before the immutable terminal event is committed.
+        try {
+            await this.onRunFinishing?.(runId, state);
+        }
+        catch {
+            // Finishing the run wins over observer failures.
+        }
         await this.persist(runId, state, {
             scope: "run",
             type: `run_${status}`,
@@ -1206,9 +1324,7 @@ async function runCheckpointNode(node, context, execution) {
             prompt,
             ...(timeout !== undefined ? { timeout } : {}),
         });
-        await new HumanDecisionStore(execution.store.databasePath, {
-            state: execution.store.state,
-        }).createRequest(request);
+        await execution.store.createHumanDecisionRequest(request);
         return { output: request, promptText: null };
     }
     const output = node.run ? await node.run(context) : { summary: node.summary ?? "checkpoint" };
@@ -1225,8 +1341,8 @@ function shellReceipt(result) {
         durationMs: result.durationMs,
     };
 }
-async function runShellActionNode(node, context, actionContext, signal, meta) {
-    const spec = await node.exec(context);
+async function runShellActionNode(node, actionContext, signal, meta) {
+    const spec = await node.exec(actionContext);
     const streams = new Set(node.updates?.streams ?? ["stdout"]);
     let result;
     try {
@@ -1251,7 +1367,7 @@ async function runShellActionNode(node, context, actionContext, signal, meta) {
         throw error;
     }
     meta.action = shellReceipt(result);
-    const output = node.parse ? await node.parse(result, context) : result;
+    const output = node.parse ? await node.parse(result, actionContext) : result;
     return { output, promptText: null, action: shellReceipt(result) };
 }
 function assertValidTimeout(value) {
@@ -1427,7 +1543,7 @@ function assistantMessageConfig(node) {
     return assistantMessageOutput(node.expectedOutput);
 }
 function appendLiveControlInstructions(prompt, workflow, nodeId, context) {
-    const lines = [prompt.trimEnd(), "", "Workflow changes during this run:"];
+    const lines = [prompt.trimEnd(), "", "Workflow context for this run:"];
     if (context.settingsScopeId !== undefined &&
         context.settingsChangeNumber !== undefined &&
         context.settings !== undefined) {
@@ -1441,12 +1557,11 @@ function appendLiveControlInstructions(prompt, workflow, nodeId, context) {
             .join(", ");
         lines.push(`- Active settings scope: ${context.settingsScopeId}`, `- Current settings change number: ${context.settingsChangeNumber}`, ...(definition?.description !== undefined
             ? [`- Settings purpose: ${definition.description}`]
-            : []), `- Current settings: ${summary}`, `- Changes allowed from this model step: ${allowed || "none"}`, "- Treat the current settings as authoritative for future behavior in this workflow scope.", "- To change future workflow settings, use the workflow tool with action change-settings, this scopeId, an RFC 6902 patch, and optionally expectedChangeNumber.");
+            : []), `- Current settings: ${summary}`, `- Settings permissions: ${allowed || "none"}`, "- Treat the current settings as authoritative for this workflow scope.");
     }
     else {
         lines.push("- This workflow scope has no editable settings.");
     }
-    lines.push("- To save normal user work for after successful completion, use workflow action queue-follow-up once for each prompt.", "- To remove an unsent prompt that this model queued, use workflow action remove-follow-up with its followUpId.", "- Setting changes affect only future node attempts and future settings routes. They do not change this running attempt or completed work.");
     return lines.join("\n");
 }
 function settingsDefinitionForNode(workflow, nodeId) {