@osolmaz/pi-workflows 0.13.2 → 0.13.4

package/dist/workflows/engine.js

@@ -1,11 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { canonicalJson } from "../state/json.js";
+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 { extractJsonValue } from "./json.js";
+import { parseWorkflowSettingsValue, resolveInitialWorkflowSettings, } from "./settings.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
 import { RUN_STATE_SCHEMA, WorkflowRunStore, createDefinitionSnapshot, createRunId, } from "./store.js";
 import { UpdateRateLimiter, updateReceipt, validateWorkflowUpdate } from "./updates.js";
@@ -15,6 +17,7 @@ const TITLE_TIMEOUT_MS = 30_000;
 const TIMEOUT_RESOLUTION_TIMEOUT_MS = 30_000;
 // Covers the shell SIGTERM → SIGKILL escalation (1s) plus stdio close.
 const ABORT_CLEANUP_GRACE_MS = 2_000;
+const MAX_SETTINGS_ROUTE_RETRIES = 16;
 /**
  * Executes a workflow graph step by step. Agent steps are delegated to the
  * configured executor; compute/action/checkpoint nodes run inline. Every
@@ -37,6 +40,7 @@ export class WorkflowEngine {
     cancelled = false;
     parked = false;
     paused = false;
+    presentationRequired = false;
     wakePause = null;
     constructor(options) {
         this.executor = options.executor;
@@ -123,9 +127,13 @@ export class WorkflowEngine {
     get pauseRequested() {
         return this.paused;
     }
+    get activeSettingsScopeId() {
+        return this.activeAttempt?.settingsScopeId;
+    }
     async run(workflow, input, options = {}) {
         workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
         validateWorkflowDefinition(workflow);
+        this.presentationRequired = workflow.presentationPrompt !== undefined;
         // Fail before any run row exists so bad input cannot leave partial state.
         const suppliedInput = input === undefined ? null : input;
         const normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
@@ -137,7 +145,17 @@ export class WorkflowEngine {
         this.paused = false;
         this.parked = false;
         const state = await this.createRunState(workflow, normalizedInput, options.workflowSource, options.runId);
-        const runId = await this.store.initializeRun(workflow, state);
+        const initialSettings = workflow.settings === undefined
+            ? []
+            : [
+                {
+                    mountPath: "",
+                    invocation: 1,
+                    settings: (await resolveInitialWorkflowSettings(workflow.settings, normalizedInput))
+                        .json,
+                },
+            ];
+        const runId = await this.store.initializeRun(workflow, state, { initialSettings });
         await this.persist(runId, state, {
             scope: "run",
             type: "run_started",
@@ -171,6 +189,7 @@ export class WorkflowEngine {
     async resumeRun(workflow, runId, options = {}) {
         workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
         validateWorkflowDefinition(workflow);
+        this.presentationRequired = workflow.presentationPrompt !== undefined;
         // Reset before any await: a park or cancel landing during preparation
         // must survive, or a host drain would hang while the run executes.
         this.cancelled = false;
@@ -184,17 +203,20 @@ export class WorkflowEngine {
         }
         const point = this.resumePointFor(workflow, state, "wait");
         const interruptedNode = state.currentNode !== undefined ? workflow.nodes[state.currentNode] : undefined;
-        const resumedAttempt = state.currentNode !== undefined &&
+        let resumedAttempt;
+        if (state.currentNode !== undefined &&
             state.currentAttemptId !== undefined &&
             state.currentNodeStartedAt !== undefined &&
             interruptedNode?.nodeType === "agent" &&
-            assistantMessageConfig(interruptedNode) !== undefined
-            ? {
+            assistantMessageConfig(interruptedNode) !== undefined) {
+            const resumedSettings = this.persistedSettingsBinding(state);
+            resumedAttempt = {
                 nodeId: state.currentNode,
                 attemptId: state.currentAttemptId,
                 startedAt: state.currentNodeStartedAt,
-            }
-            : undefined;
+                ...(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
@@ -204,6 +226,9 @@ export class WorkflowEngine {
             delete state.currentNode;
             delete state.currentAttemptId;
             delete state.currentNodeStartedAt;
+            delete state.currentSettingsScopeId;
+            delete state.currentSettingsChangeNumber;
+            delete state.currentSettingsHash;
             delete state.statusDetail;
         }
         await this.persist(runId, state, {
@@ -258,6 +283,7 @@ export class WorkflowEngine {
     async continueRun(workflow, parentRunId, input, options = {}) {
         workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
         validateWorkflowDefinition(workflow);
+        this.presentationRequired = workflow.presentationPrompt !== undefined;
         this.cancelled = false;
         this.paused = false;
         this.parked = false;
@@ -481,6 +507,7 @@ export class WorkflowEngine {
         let currentNodeId = startNodeId;
         let executedSteps = executedStepsBase;
         let lastOutput = initialLastOutput;
+        const settingsRouteRetries = new Map();
         while (currentNodeId !== null) {
             await this.holdWhilePaused(state, runId);
             const isTransition = composition?.entries[currentNodeId] !== undefined ||
@@ -504,28 +531,81 @@ export class WorkflowEngine {
                 // as in-flight, and resume reruns it with a fresh attempt.
                 throw new RunParkedError();
             }
+            const beforeRecord = structuredClone(state);
             this.recordAttempt(workflow, state, attempt);
-            // The durable step row owns the output. The trace keeps the terminal fact
-            // and compact execution metadata without copying the output value.
-            await this.persist(runId, state, {
-                scope: "node",
-                type: attempt.result.outcome === "ok" ? "node_finished" : "node_failed",
-                nodeId: attempt.result.nodeId,
-                attemptId: attempt.result.attemptId,
-                payload: {
-                    outcome: attempt.result.outcome,
-                    durationMs: attempt.result.durationMs,
-                    ...(attempt.result.outcome === "ok" ? { output: attempt.result.output ?? null } : {}),
-                    ...(attempt.result.error !== undefined ? { error: attempt.result.error } : {}),
-                    ...(attempt.execution?.action !== undefined ? { action: attempt.execution.action } : {}),
-                    ...(attempt.execution?.assistantMessage !== undefined
-                        ? { assistantMessage: attempt.execution.assistantMessage }
-                        : {}),
-                    ...(attempt.execution?.conversation !== undefined
-                        ? { conversation: attempt.execution.conversation }
-                        : {}),
-                },
-            });
+            // The durable step row owns the output. The trace keeps the terminal fact,
+            // settings binding, and compact execution metadata.
+            try {
+                await this.persist(runId, state, {
+                    scope: "node",
+                    type: attempt.result.outcome === "ok" ? "node_finished" : "node_failed",
+                    nodeId: attempt.result.nodeId,
+                    attemptId: attempt.result.attemptId,
+                    payload: {
+                        outcome: attempt.result.outcome,
+                        durationMs: attempt.result.durationMs,
+                        ...(attempt.result.outcome === "ok" ? { output: attempt.result.output ?? null } : {}),
+                        ...(attempt.result.error !== undefined ? { error: attempt.result.error } : {}),
+                        ...(attempt.execution?.action !== undefined
+                            ? { action: attempt.execution.action }
+                            : {}),
+                        ...(attempt.execution?.assistantMessage !== undefined
+                            ? { assistantMessage: attempt.execution.assistantMessage }
+                            : {}),
+                        ...(attempt.execution?.conversation !== undefined
+                            ? { conversation: attempt.execution.conversation }
+                            : {}),
+                        ...(attempt.settings !== undefined
+                            ? {
+                                settingsScopeId: attempt.settings.scopeId,
+                                settingsChangeNumber: attempt.settings.changeNumber,
+                                settingsHash: attempt.settings.settingsHash,
+                            }
+                            : {}),
+                    },
+                });
+            }
+            catch (error) {
+                if (!(error instanceof StaleResourceError) ||
+                    node.nodeType !== "compute" ||
+                    node.settingsRoute !== true ||
+                    attempt.settings === undefined) {
+                    throw error;
+                }
+                restoreRunState(state, beforeRecord);
+                const retryCount = (settingsRouteRetries.get(currentNodeId) ?? 0) + 1;
+                if (retryCount > MAX_SETTINGS_ROUTE_RETRIES) {
+                    throw new Error(`Settings route ${currentNodeId} changed more than ${MAX_SETTINGS_ROUTE_RETRIES} times before settlement`);
+                }
+                settingsRouteRetries.set(currentNodeId, retryCount);
+                const latest = await this.captureSettingsBinding(workflow, state, currentNodeId);
+                if (latest === undefined) {
+                    throw new Error(`Settings route ${currentNodeId} lost its settings scope`);
+                }
+                state.currentSettingsScopeId = latest.scopeId;
+                state.currentSettingsChangeNumber = latest.changeNumber;
+                state.currentSettingsHash = latest.settingsHash;
+                await this.persist(runId, state, {
+                    scope: "run",
+                    type: "settings_route_retried",
+                    nodeId: currentNodeId,
+                    attemptId: attempt.result.attemptId,
+                    payload: {
+                        scopeId: latest.scopeId,
+                        previousChangeNumber: attempt.settings.changeNumber,
+                        changeNumber: latest.changeNumber,
+                    },
+                });
+                resumedAttempt = {
+                    nodeId: currentNodeId,
+                    attemptId: attempt.result.attemptId,
+                    startedAt: attempt.result.startedAt,
+                    settings: latest,
+                };
+                executedSteps -= 1;
+                continue;
+            }
+            settingsRouteRetries.delete(currentNodeId);
             if (attempt.result.outcome !== "ok") {
                 currentNodeId = this.routeAfterFailure(workflow, state, attempt);
                 continue;
@@ -649,19 +729,40 @@ export class WorkflowEngine {
             ...(attempt.execution?.conversation !== undefined
                 ? { conversation: attempt.execution.conversation }
                 : {}),
+            ...(attempt.settings !== undefined
+                ? {
+                    settingsScopeId: attempt.settings.scopeId,
+                    settingsChangeNumber: attempt.settings.changeNumber,
+                    settingsHash: attempt.settings.settingsHash,
+                }
+                : {}),
         };
         state.steps.push(step);
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
+        delete state.currentSettingsScopeId;
+        delete state.currentSettingsChangeNumber;
+        delete state.currentSettingsHash;
         delete state.statusDetail;
     }
     async executeNode(workflow, state, runId, nodeId, node, resumedAttempt) {
         const attemptId = resumedAttempt?.attemptId ?? randomUUID();
         const startedAt = resumedAttempt?.startedAt ?? new Date().toISOString();
+        const settings = resumedAttempt?.settings ?? (await this.captureSettingsBinding(workflow, state, nodeId));
         state.currentNode = nodeId;
         state.currentAttemptId = attemptId;
         state.currentNodeStartedAt = startedAt;
+        if (settings !== undefined) {
+            state.currentSettingsScopeId = settings.scopeId;
+            state.currentSettingsChangeNumber = settings.changeNumber;
+            state.currentSettingsHash = settings.settingsHash;
+        }
+        else {
+            delete state.currentSettingsScopeId;
+            delete state.currentSettingsChangeNumber;
+            delete state.currentSettingsHash;
+        }
         if (node.statusDetail !== undefined) {
             state.statusDetail = node.statusDetail;
         }
@@ -671,15 +772,25 @@ export class WorkflowEngine {
                 type: "node_started",
                 nodeId,
                 attemptId,
-                payload: { nodeType: node.nodeType },
+                payload: {
+                    nodeType: node.nodeType,
+                    ...(settings !== undefined
+                        ? {
+                            settingsScopeId: settings.scopeId,
+                            settingsChangeNumber: settings.changeNumber,
+                            settingsHash: settings.settingsHash,
+                        }
+                        : {}),
+                },
             });
         }
         const meta = { promptText: null };
         try {
-            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta);
+            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings);
             return {
                 result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
                 execution,
+                ...(settings !== undefined ? { settings } : {}),
             };
         }
         catch (error) {
@@ -696,6 +807,7 @@ export class WorkflowEngine {
                     promptText: meta.promptText,
                     ...(meta.action !== undefined ? { action: meta.action } : {}),
                 },
+                ...(settings !== undefined ? { settings } : {}),
                 error,
             };
         }
@@ -722,9 +834,9 @@ export class WorkflowEngine {
             ...(output !== undefined ? { output } : {}),
         };
     }
-    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta) {
+    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings) {
         const abort = new AbortController();
-        const context = this.createNodeContext(state, abort.signal);
+        const context = this.createNodeContext(state, abort.signal, settings);
         let timer;
         let dispatchSettled;
         this.activeAbort = abort;
@@ -746,7 +858,14 @@ export class WorkflowEngine {
                     abort.abort(new TimeoutError(timeoutMs));
                 }, timeoutMs);
             }
-            this.activeAttempt = { runId, state, nodeId, attemptId, signal: abort.signal };
+            this.activeAttempt = {
+                runId,
+                state,
+                nodeId,
+                attemptId,
+                ...(settings !== undefined ? { settingsScopeId: settings.scopeId } : {}),
+                signal: abort.signal,
+            };
             const dispatched = this.dispatchNode(workflow, state, runId, nodeId, attemptId, node, context, abort.signal, meta);
             dispatchSettled = dispatched.then(() => undefined, () => undefined);
             // Race the dispatch against the abort signal so timeouts and cancel
@@ -848,12 +967,71 @@ export class WorkflowEngine {
                 });
         }
     }
-    createNodeContext(state, signal) {
+    async captureSettingsBinding(workflow, state, nodeId) {
+        const metadata = compositionMetadata(workflow);
+        let mountPath = "";
+        let definition = workflow.settings;
+        if (metadata !== undefined) {
+            const entry = metadata.entries[nodeId];
+            const exit = metadata.exits[nodeId];
+            const scope = entry !== undefined
+                ? metadata.scopes[entry.parentPath]
+                : exit !== undefined
+                    ? metadata.scopes[exit.mountPath]
+                    : Object.values(metadata.scopes).find((candidate) => Object.values(candidate.authoredNodes).includes(nodeId));
+            if (scope === undefined) {
+                throw new Error(`Workflow settings scope is missing for node ${nodeId}`);
+            }
+            mountPath = scope.path;
+            definition = scope.settings;
+        }
+        if (definition === undefined)
+            return undefined;
+        const invocation = mountPath === "" ? 1 : currentMountInvocation(state, mountPath);
+        const existing = this.store.findSettingsScope(state.runId, mountPath, invocation);
+        if (existing !== undefined)
+            return existing;
+        const input = mountPath === "" ? state.input : currentMountInput(state, mountPath);
+        const mappedSettings = mountPath === "" ? { present: false } : currentMountSettings(state, mountPath);
+        const initial = mappedSettings.present
+            ? await parseWorkflowSettingsValue(definition, mappedSettings.value)
+            : await resolveInitialWorkflowSettings(definition, input);
+        return this.store.ensureSettingsScope({
+            runId: state.runId,
+            mountPath,
+            invocation,
+            settings: initial.json,
+        });
+    }
+    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);
+        if (scope === undefined) {
+            throw new Error(`Saved workflow settings scope is missing: ${state.currentSettingsScopeId}`);
+        }
+        if (scope.settingsHash !== state.currentSettingsHash) {
+            throw new Error("Saved workflow settings binding does not match its saved change");
+        }
+        return scope;
+    }
+    createNodeContext(state, signal, settings) {
         return {
             input: state.input,
             outputs: state.outputs,
             results: state.results,
             state,
+            ...(settings !== undefined
+                ? {
+                    settings: deepFreezeJson(structuredClone(settings.settings)),
+                    settingsScopeId: settings.scopeId,
+                    settingsChangeNumber: settings.changeNumber,
+                }
+                : {}),
             signal,
         };
     }
@@ -876,7 +1054,8 @@ export class WorkflowEngine {
                 throw new Error("Assistant completion requires an origin Pi session");
             }
         }
-        const basePrompt = await node.prompt(context);
+        const authoredPrompt = await node.prompt(context);
+        const basePrompt = appendLiveControlInstructions(authoredPrompt, workflow, nodeId, context);
         if (signal.aborted) {
             // The node timed out or the run was cancelled while the async prompt
             // builder ran; a late continuation must not write into a run that
@@ -993,6 +1172,9 @@ export class WorkflowEngine {
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
+        delete state.currentSettingsScopeId;
+        delete state.currentSettingsChangeNumber;
+        delete state.currentSettingsHash;
         await this.persist(runId, state, {
             scope: "run",
             type: `run_${status}`,
@@ -1001,6 +1183,7 @@ export class WorkflowEngine {
                 ...(fields.error !== undefined ? { error: fields.error } : {}),
                 ...(fields.waitingOn !== undefined ? { waitingOn: fields.waitingOn } : {}),
                 ...(fields.finalOutput !== undefined ? { finalOutput: fields.finalOutput } : {}),
+                presentationRequired: status === "completed" && this.presentationRequired,
             },
         });
     }
@@ -1094,6 +1277,54 @@ function abortRejection(signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
+function restoreRunState(target, saved) {
+    for (const key of Object.keys(target)) {
+        delete target[key];
+    }
+    Object.assign(target, saved);
+}
+function currentMountInvocation(state, mountPath) {
+    for (let index = state.steps.length - 1; index >= 0; index -= 1) {
+        const step = state.steps[index];
+        if (step?.nodeId !== mountPath || step.outcome !== "ok")
+            continue;
+        const output = step.output;
+        if (typeof output.invocation === "number" && Number.isInteger(output.invocation)) {
+            return output.invocation;
+        }
+    }
+    throw new Error(`Workflow include entry is missing for settings scope ${mountPath}`);
+}
+function currentMountInput(state, mountPath) {
+    for (let index = state.steps.length - 1; index >= 0; index -= 1) {
+        const step = state.steps[index];
+        if (step?.nodeId !== mountPath || step.outcome !== "ok")
+            continue;
+        const output = step.output;
+        return output.input ?? null;
+    }
+    throw new Error(`Workflow include input is missing for settings scope ${mountPath}`);
+}
+function currentMountSettings(state, mountPath) {
+    for (let index = state.steps.length - 1; index >= 0; index -= 1) {
+        const step = state.steps[index];
+        if (step?.nodeId !== mountPath || step.outcome !== "ok")
+            continue;
+        const output = step.output;
+        return Object.hasOwn(output, "settings")
+            ? { present: true, value: output.settings }
+            : { present: false };
+    }
+    throw new Error(`Workflow include entry is missing for settings scope ${mountPath}`);
+}
+function deepFreezeJson(value) {
+    if (value !== null && typeof value === "object") {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreezeJson(item);
+    }
+    return value;
+}
 function countExecutableSteps(workflow, steps) {
     const metadata = compositionMetadata(workflow);
     if (metadata === undefined)
@@ -1144,7 +1375,7 @@ function workflowSourceMismatch(state, source) {
     return (state.workflowHash !== undefined &&
         (source.kind !== "file" || state.workflowHash !== source.hash));
 }
-function workflowIdentityMismatch(state, workflow, source) {
+export function workflowIdentityMismatch(state, workflow, source) {
     if (workflowSourceMismatch(state, source))
         return true;
     const metadata = compositionMetadata(workflow);
@@ -1195,6 +1426,41 @@ function assistantMessageOutput(expectedOutput) {
 function assistantMessageConfig(node) {
     return assistantMessageOutput(node.expectedOutput);
 }
+function appendLiveControlInstructions(prompt, workflow, nodeId, context) {
+    const lines = [prompt.trimEnd(), "", "Workflow changes during this run:"];
+    if (context.settingsScopeId !== undefined &&
+        context.settingsChangeNumber !== undefined &&
+        context.settings !== undefined) {
+        const definition = settingsDefinitionForNode(workflow, nodeId);
+        const value = canonicalJson(context.settings);
+        const summary = value.length <= 8_192 ? value : `${value.slice(0, 8_192)}… [settings truncated]`;
+        const allowed = (definition?.paths ?? [])
+            .flatMap((rule) => Object.entries(rule.permissions)
+            .filter(([, actors]) => actors?.includes("session") === true)
+            .map(([permission]) => `${permission} ${rule.path || "/"}`))
+            .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.");
+    }
+    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) {
+    const metadata = compositionMetadata(workflow);
+    if (metadata === undefined)
+        return workflow.settings;
+    const entry = metadata.entries[nodeId];
+    if (entry !== undefined)
+        return metadata.scopes[entry.parentPath]?.settings;
+    const exit = metadata.exits[nodeId];
+    if (exit !== undefined)
+        return metadata.scopes[exit.mountPath]?.settings;
+    return Object.values(metadata.scopes).find((scope) => Object.values(scope.authoredNodes).includes(nodeId))?.settings;
+}
 /**
  * The step contract appended to every agent-node prompt. This is the
  * documented standard for how the model completes a workflow step.