@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/workflow/machine-builder.js

@@ -0,0 +1,678 @@
+import { setup, assign, fromPromise } from 'xstate';
+import { guardImplementations } from './guards.js';
+import { stripStatusBlock } from './status-parser.js';
+import { isAgentInvocationError } from './errors.js';
+import { laneScopeEvolveCurrentPath, templateLaneCommand } from './lane-template.js';
+// ---------------------------------------------------------------------------
+// Extraction helpers (used by guards and actions inside the machine)
+// ---------------------------------------------------------------------------
+/**
+ * Extracts the invoke result from an xstate.done.actor.* event.
+ * XState wraps the promise resolution in `event.output`.
+ */
+function extractInvokeResult(event) {
+    const output = event.output;
+    if (output && typeof output === 'object' && 'output' in output && 'outputHash' in output) {
+        return output;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Agent output truncation
+// ---------------------------------------------------------------------------
+const MAX_AGENT_OUTPUT_BYTES = 32_768;
+const TRUNCATION_NOTICE = '\n\n[Output truncated. Read the artifact directories for full details.]';
+/**
+ * Sanitizes agent response text for reuse in subsequent prompts: escapes any
+ * literal NUL bytes and truncates to stay within the 32KB limit.
+ *
+ * NUL escaping is load-bearing, not cosmetic. Agent output flows back into
+ * later prompts via `previousAgentOutput` / `previousAgentNotes`, which the
+ * Docker adapter passes as an argv element to `child_process.spawn`. Node
+ * refuses argv strings containing `\0` (`ERR_INVALID_ARG_VALUE`) and throws
+ * synchronously before the container even starts — aborting the workflow. A
+ * security-research agent describing a binary file format ("APP1 'Exif\\0\\0'")
+ * is the natural way this happens. We escape rather than strip so the textual
+ * description survives intact for downstream readers.
+ *
+ * Exported for testing.
+ */
+export function truncateAgentOutput(text) {
+    const sanitized = text.includes('\0') ? text.replaceAll('\0', '\\x00') : text;
+    if (Buffer.byteLength(sanitized, 'utf-8') <= MAX_AGENT_OUTPUT_BYTES) {
+        return sanitized;
+    }
+    const budget = MAX_AGENT_OUTPUT_BYTES - Buffer.byteLength(TRUNCATION_NOTICE, 'utf-8');
+    let truncated = sanitized;
+    while (Buffer.byteLength(truncated, 'utf-8') > budget) {
+        truncated = truncated.slice(0, Math.floor(truncated.length * 0.9));
+    }
+    return truncated + TRUNCATION_NOTICE;
+}
+// ---------------------------------------------------------------------------
+// Initial context factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates the initial WorkflowContext for a given definition.
+ * Exported for testing.
+ */
+export function createInitialContext(definition) {
+    return {
+        artifacts: {},
+        round: 0,
+        maxRounds: definition.settings?.maxRounds ?? 4,
+        previousOutputHashes: {},
+        previousTestCount: null,
+        humanPrompt: null,
+        reviewHistory: [],
+        totalTokens: 0,
+        lastError: null,
+        agentConversationsByState: {},
+        previousAgentOutput: null,
+        previousAgentNotes: null,
+        previousStateName: null,
+        visitCounts: {},
+    };
+}
+// ---------------------------------------------------------------------------
+// State builders
+// ---------------------------------------------------------------------------
+/**
+ * Finds an appropriate error target for a state. Looks for a human_gate
+ * in the definition's transitions, then falls back to any terminal state.
+ */
+function findErrorTarget(stateDef, definition) {
+    // Check if any transition leads to a human gate (good for error review)
+    for (const t of stateDef.transitions) {
+        const targetState = definition.states[t.to];
+        if (targetState.type === 'human_gate')
+            return t.to;
+    }
+    // Fall back: prefer terminal states named 'aborted' or 'failed'
+    for (const [id, state] of Object.entries(definition.states)) {
+        if (state.type === 'terminal' && (id === 'aborted' || id === 'failed'))
+            return id;
+    }
+    // Then any terminal
+    for (const [id, state] of Object.entries(definition.states)) {
+        if (state.type === 'terminal')
+            return id;
+    }
+    // Last resort: first transition target (machine will at least not crash)
+    if (stateDef.transitions.length > 0) {
+        return stateDef.transitions[0].to;
+    }
+    // Should not happen in a validated definition
+    throw new Error('No valid error target found');
+}
+/**
+ * Collects all transition actions for a given transition definition into
+ * XState action entries, preserving order:
+ *   1. the default context-update action (caller-provided),
+ *   2. each entry from `actions[]` translated to XState form.
+ */
+function collectTransitionActions(t, defaultContextAction) {
+    const entries = [defaultContextAction];
+    for (const action of t.actions ?? []) {
+        entries.push(compileAction(action));
+    }
+    return entries;
+}
+// Adding a new variant to WorkflowTransitionAction will make
+// `action.stateIds` a compile error, forcing a switch here.
+function compileAction(action) {
+    return { type: 'resetVisitCounts', params: { stateIds: action.stateIds } };
+}
+// Shared onDone-transition builder for agent and deterministic states: both map a
+// `when:` clause to the __matchesWhen guard, else a bare `guard:`, and run a
+// per-state-type context-update action. Only the update action differs.
+function buildOnDoneTransitions(transitions, updateAction, mapTarget = (transition) => transition.to) {
+    return transitions.map((t) => {
+        let guard;
+        if (t.when) {
+            guard = { type: '__matchesWhen', params: { when: t.when } };
+        }
+        else if (t.guard) {
+            guard = t.guard;
+        }
+        return {
+            target: mapTarget(t),
+            ...(guard ? { guard } : {}),
+            actions: collectTransitionActions(t, updateAction),
+        };
+    });
+}
+function buildAgentState(stateId, config, definition, options = {}) {
+    return {
+        entry: [{ type: 'incrementVisitCount', params: { stateId } }],
+        invoke: {
+            id: stateId,
+            src: 'agentService',
+            input: ({ context }) => ({
+                stateId,
+                stateConfig: config,
+                context,
+            }),
+            onDone: buildOnDoneTransitions(config.transitions, 'updateContextFromAgentResult', options.mapTransitionTarget),
+            onError: {
+                target: options.onErrorTarget ?? findErrorTarget(config, definition),
+                actions: ['storeError', 'updateContextFromAgentInvocationError'],
+            },
+        },
+    };
+}
+function buildDeterministicState(stateId, config, definition, options = {}) {
+    const onDoneTransitions = buildOnDoneTransitions(config.transitions, 'updateContextFromDeterministicResult', options.mapTransitionTarget);
+    return {
+        invoke: {
+            id: stateId,
+            src: 'deterministicService',
+            input: ({ context }) => ({
+                stateId,
+                commands: config.run.map((command) => templateLaneCommand(command, context)),
+                context,
+                container: config.container ?? false,
+                containerScope: config.containerScope,
+                timeoutMs: config.timeoutMs,
+                resultFile: config.resultFile ? laneScopeEvolveCurrentPath(config.resultFile, context) : undefined,
+            }),
+            onDone: onDoneTransitions,
+            onError: {
+                target: options.onErrorTarget ?? findErrorTarget(config, definition),
+                actions: ['storeError'],
+            },
+        },
+    };
+}
+/**
+ * Builds the parent `workers` state: a single XState invoke of `fanOutService`
+ * (the orchestrator's `runFanOutSegment`). From the parent FSM's vantage the
+ * whole batch is ONE invoke — the N child round actors live inside the invoke
+ * body, not in the parent's state value, so the parent's `snapshot.value` stays
+ * the string `"workers"` (single-active-state spine, §6.4). `onDone` runs
+ * `updateContextFromFanOutResult` (promote the joined context) then follows the
+ * verdict-matched edge; `onError` routes to the definition's error target.
+ */
+function buildFanOutState(stateId, config, definition) {
+    return {
+        invoke: {
+            id: stateId,
+            src: 'fanOutService',
+            input: ({ context }) => ({
+                stateId,
+                stateConfig: config,
+                context,
+            }),
+            onDone: buildOnDoneTransitions(config.transitions, 'updateContextFromFanOutResult'),
+            onError: {
+                target: findErrorTarget(config, definition),
+                actions: ['storeError'],
+            },
+        },
+    };
+}
+function buildHumanGateState(_stateId, config) {
+    const on = {};
+    for (const t of config.transitions) {
+        const eventName = `HUMAN_${t.event}`;
+        // Order: the hardcoded gate actions (storeHumanPrompt, clearError) run
+        // first so they set up context (prompt, error state) before any
+        // user-declared actions observe or modify it. User-declared actions
+        // (e.g., resetVisitCounts) run afterward.
+        const actions = ['storeHumanPrompt', 'clearError'];
+        for (const action of t.actions ?? []) {
+            actions.push(compileAction(action));
+        }
+        on[eventName] = {
+            target: t.to,
+            actions,
+        };
+    }
+    return { on };
+}
+/** The three synthetic terminal state names every child round machine carries. */
+const ROUND_CHILD_RECORDED = 'recorded';
+const ROUND_CHILD_BLOCKED = 'blocked';
+const ROUND_CHILD_ERRORED = 'errored';
+/**
+ * Factors a fan-out segment (the round sub-chain
+ * `sample -> researcher -> evaluate -> analysis_record`) into a standalone
+ * child machine definition. Each member is copied verbatim except for two
+ * rewrites: its out-of-segment transition targets are remapped to one of
+ * three synthetic terminals via {@link mapRoundChildTarget}, and the
+ * `fanOut`/`segment` markers are stripped so the recursive
+ * `buildWorkflowMachine` does not try to re-factor the member into yet
+ * another child.
+ *
+ * The three synthetic terminals (`recorded`, `blocked`, `errored`) are the
+ * lane verdict surface — every lane finishes in exactly one, and the parent
+ * barrier reads it to decide the batch verdict (§6.1). `initial: segment[0]`
+ * starts the child at the first segment member. `settings` are inherited from
+ * the parent so the child's per-lane `maxVisits` guard fires natively from the
+ * member's own declared limits (§6.1).
+ */
+function buildRoundChildDefinition(definition, fanOutStateId, segment) {
+    const segmentSet = new Set(segment);
+    const states = {};
+    for (const memberId of segment) {
+        const member = definition.states[memberId];
+        if (member.type !== 'agent' && member.type !== 'deterministic') {
+            throw new Error(`fan-out state "${fanOutStateId}" segment member "${memberId}" is not executable`);
+        }
+        const transitions = member.transitions.map((transition) => ({
+            ...transition,
+            to: mapRoundChildTarget(definition, transition, segmentSet),
+        }));
+        // The agent and deterministic arms produce byte-identical state objects
+        // (strip the fan-out markers, override transitions); the only difference
+        // is the discriminated-union narrowing of `member`, so one block covers
+        // both once the `type` guard above has run. `_fanOut`/`_segment` are
+        // destructured only to omit them from `rest`; `void` marks them used.
+        const { fanOut: _fanOut, segment: _segment, ...rest } = member;
+        void _fanOut;
+        void _segment;
+        states[memberId] = { ...rest, transitions };
+    }
+    states[ROUND_CHILD_RECORDED] = {
+        type: 'terminal',
+        description: `Fan-out segment "${fanOutStateId}" recorded successfully.`,
+    };
+    states[ROUND_CHILD_BLOCKED] = {
+        type: 'terminal',
+        description: `Fan-out segment "${fanOutStateId}" needs human review.`,
+    };
+    states[ROUND_CHILD_ERRORED] = {
+        type: 'terminal',
+        description: `Fan-out segment "${fanOutStateId}" failed.`,
+    };
+    return {
+        name: `${definition.name}-${fanOutStateId}-round`,
+        description: `Child round machine for ${definition.name}.${fanOutStateId}`,
+        initial: segment[0],
+        settings: definition.settings,
+        states,
+    };
+}
+/**
+ * Maps a segment member's transition target onto a child round-machine
+ * target. In-segment edges pass through unchanged; everything that would
+ * leave the segment is collapsed onto one of the three synthetic terminals.
+ *
+ * The mapping table:
+ *   - target is another segment member  -> passthrough (the target name)
+ *   - `when.verdict === 'recorded'`      -> `recorded`  (round committed a node)
+ *   - `when.verdict === 'evaluator_blocked'` -> `blocked` (needs human review)
+ *   - any other named verdict            -> `errored`   (unexpected verdict)
+ *   - target is a human_gate state       -> `blocked`   (escalation edge)
+ *   - else (bare fallthrough / failed)   -> `errored`
+ */
+function mapRoundChildTarget(definition, transition, segment) {
+    if (segment.has(transition.to))
+        return transition.to;
+    const verdict = transition.when?.verdict;
+    if (verdict === 'recorded')
+        return ROUND_CHILD_RECORDED;
+    if (verdict === 'evaluator_blocked')
+        return ROUND_CHILD_BLOCKED;
+    if (typeof verdict === 'string')
+        return ROUND_CHILD_ERRORED;
+    const targetState = definition.states[transition.to];
+    if (targetState.type === 'human_gate')
+        return ROUND_CHILD_BLOCKED;
+    return ROUND_CHILD_ERRORED;
+}
+/**
+ * Builds an XState v5 machine from a validated WorkflowDefinition.
+ *
+ * The returned machine has placeholder actors (`agentService`,
+ * `deterministicService`) that throw if invoked directly. Callers
+ * must call `.provide({ actors: { ... } })` to inject real
+ * implementations before passing to `createActor()`.
+ *
+ * Guards are registered with concrete implementations from the guards
+ * module. Actions for context updates are defined inline via `assign`.
+ */
+export function buildWorkflowMachine(definition, taskDescription, options = {}) {
+    const states = {};
+    const roundMachinesByState = new Map();
+    const gateStateNames = new Set();
+    const terminalStateNames = new Set();
+    // Per-state maxVisits map, built at machine-construction time and
+    // closed over by the `isStateVisitLimitReached` guard below. Only
+    // agent states can declare `maxVisits`; states without it are absent
+    // from the map and the guard returns false for them.
+    const maxVisitsByState = new Map();
+    // For child round machines, every executable member's error path is forced
+    // to the synthetic `errored` terminal (see `onErrorTarget` doc above); the
+    // parent machine leaves it undefined and falls back to `findErrorTarget`.
+    const executableOptions = { onErrorTarget: options.onErrorTarget };
+    for (const [stateId, stateDef] of Object.entries(definition.states)) {
+        switch (stateDef.type) {
+            case 'agent':
+                states[stateId] =
+                    stateDef.fanOut !== undefined
+                        ? buildFanOutState(stateId, stateDef, definition)
+                        : buildAgentState(stateId, stateDef, definition, executableOptions);
+                if (typeof stateDef.maxVisits === 'number') {
+                    maxVisitsByState.set(stateId, stateDef.maxVisits);
+                }
+                break;
+            case 'deterministic':
+                states[stateId] =
+                    stateDef.fanOut !== undefined
+                        ? buildFanOutState(stateId, stateDef, definition)
+                        : buildDeterministicState(stateId, stateDef, definition, executableOptions);
+                break;
+            case 'human_gate':
+                states[stateId] = buildHumanGateState(stateId, stateDef);
+                gateStateNames.add(stateId);
+                break;
+            case 'terminal':
+                states[stateId] = { type: 'final' };
+                terminalStateNames.add(stateId);
+                break;
+        }
+    }
+    if (options.buildRoundMachines !== false) {
+        for (const [stateId, stateDef] of Object.entries(definition.states)) {
+            if ((stateDef.type !== 'agent' && stateDef.type !== 'deterministic') || stateDef.fanOut === undefined) {
+                continue;
+            }
+            const segment = stateDef.segment ?? [];
+            if (segment.length === 0)
+                continue;
+            const childDefinition = buildRoundChildDefinition(definition, stateId, segment);
+            const child = buildWorkflowMachine(childDefinition, taskDescription, {
+                contextFromInput: true,
+                buildRoundMachines: false,
+                // A segment member's service rejection must land in the child's
+                // `errored` terminal, not fall through `findErrorTarget` to the
+                // first terminal (`recorded`). See `onErrorTarget` above.
+                onErrorTarget: ROUND_CHILD_ERRORED,
+            });
+            roundMachinesByState.set(stateId, child.machine);
+        }
+    }
+    // Build XState guard implementations compatible with XState's guard API.
+    // XState v5 guards receive ({ context, event }) but the event type
+    // during onDone is the xstate done event, not our WorkflowEvent.
+    // We need to adapt our guards to work with the done event's output.
+    // The second `params` argument is used by parameterized guards like __matchesWhen.
+    const xstateGuards = {};
+    for (const [name, guardFn] of Object.entries(guardImplementations)) {
+        xstateGuards[name] = ({ context, event }) => {
+            // For xstate.done.actor.* events, extract the output and create
+            // a synthetic WorkflowEvent for the guard
+            const doneEvent = event;
+            let workflowEvent;
+            if (doneEvent.type.startsWith('xstate.done.actor.')) {
+                const result = extractInvokeResult(doneEvent);
+                if (result) {
+                    // Special case: isStalled needs access to outputHash and stateId
+                    // which are not part of AgentOutput/WorkflowEvent.
+                    if (name === 'isStalled') {
+                        const stateId = doneEvent.type.replace('xstate.done.actor.', '');
+                        const prevHash = context.previousOutputHashes[stateId];
+                        return !!prevHash && result.outputHash === prevHash;
+                    }
+                    // Special case: isStateVisitLimitReached consults the per-state
+                    // maxVisits map (closed over from the definition) and compares it
+                    // to the visit count for the state that just completed.
+                    if (name === 'isStateVisitLimitReached') {
+                        const stateId = doneEvent.type.replace('xstate.done.actor.', '');
+                        const cap = maxVisitsByState.get(stateId);
+                        if (cap === undefined)
+                            return false;
+                        const visits = context.visitCounts[stateId] ?? 0;
+                        return visits >= cap;
+                    }
+                    // Agent service result -> AGENT_COMPLETED event
+                    workflowEvent = { type: 'AGENT_COMPLETED', output: result.output };
+                }
+                else {
+                    // Deterministic service result -> map to VALIDATION_PASSED/FAILED
+                    const detResult = doneEvent.output;
+                    if (detResult?.passed) {
+                        workflowEvent = { type: 'VALIDATION_PASSED', testCount: detResult.testCount ?? 0 };
+                    }
+                    else {
+                        workflowEvent = { type: 'VALIDATION_FAILED', errors: detResult?.errors ?? 'unknown' };
+                    }
+                }
+            }
+            else {
+                // For human gate events, pass through directly
+                workflowEvent = event;
+            }
+            return guardFn({ context, event: workflowEvent });
+        };
+    }
+    // Register the __matchesWhen parameterized guard. This intentionally
+    // bypasses the guard adapter loop above because it operates on AgentOutput
+    // directly (via extractInvokeResult inline) rather than on WorkflowEvent.
+    xstateGuards['__matchesWhen'] = ({ event }, params) => {
+        const doneEvent = event;
+        let matchSource;
+        if (doneEvent.type.startsWith('xstate.done.actor.')) {
+            const result = extractInvokeResult(doneEvent);
+            if (result) {
+                matchSource = result.output;
+            }
+            else {
+                const detResult = doneEvent.output;
+                if (typeof detResult?.verdict === 'string') {
+                    matchSource = { verdict: detResult.verdict };
+                }
+            }
+        }
+        if (!matchSource)
+            return false;
+        // Defensive: fail closed if params are missing or when is empty/missing.
+        // Validation prevents these cases, but we don't want a silent unconditional
+        // match if validation is bypassed.
+        if (!params || typeof params !== 'object')
+            return false;
+        const whenMap = params.when;
+        if (!whenMap || typeof whenMap !== 'object' || Object.keys(whenMap).length === 0) {
+            return false;
+        }
+        const when = whenMap;
+        for (const [key, expected] of Object.entries(when)) {
+            const actual = matchSource[key];
+            if (actual !== expected)
+                return false;
+        }
+        return true;
+    };
+    const machine = setup({
+        types: {
+            context: {},
+            events: {},
+            input: {},
+        },
+        actors: {
+            agentService: fromPromise(() => {
+                return Promise.reject(new Error('agentService must be provided via machine.provide()'));
+            }),
+            deterministicService: fromPromise(() => {
+                return Promise.reject(new Error('deterministicService must be provided via machine.provide()'));
+            }),
+            fanOutService: fromPromise(() => {
+                return Promise.reject(new Error('fanOutService must be provided via machine.provide()'));
+            }),
+        },
+        guards: xstateGuards,
+        actions: {
+            updateContextFromAgentResult: assign(({ context, event }) => {
+                const doneEvent = event;
+                const result = extractInvokeResult(doneEvent);
+                if (!result)
+                    return {};
+                const output = result.output;
+                // Derive stateId from the event type: xstate.done.actor.<stateId>
+                const stateId = event.type.replace('xstate.done.actor.', '');
+                return {
+                    artifacts: { ...context.artifacts, ...result.artifacts },
+                    previousOutputHashes: {
+                        ...context.previousOutputHashes,
+                        [stateId]: result.outputHash,
+                    },
+                    round: context.round + 1,
+                    reviewHistory: output.verdict === 'rejected' ? [...context.reviewHistory, output.notes ?? ''] : context.reviewHistory,
+                    agentConversationsByState: {
+                        ...context.agentConversationsByState,
+                        [stateId]: result.agentConversationId,
+                    },
+                    // Sourced from `instance.outputTokens` in the orchestrator,
+                    // which subscribes to the token-stream bus and accumulates
+                    // `message_end.outputTokens` across every session this workflow
+                    // has spawned. The orchestrator always supplies a numeric
+                    // cumulative value — the field is required on AgentInvokeResult.
+                    totalTokens: result.totalTokens,
+                    previousAgentOutput: truncateAgentOutput(stripStatusBlock(result.responseText)),
+                    previousAgentNotes: output.notes ? truncateAgentOutput(output.notes) : null,
+                    previousStateName: stateId,
+                    humanPrompt: null,
+                };
+            }),
+            updateContextFromDeterministicResult: assign(({ context, event }) => {
+                const doneEvent = event;
+                const result = doneEvent.output;
+                if (!result)
+                    return {};
+                // Only attach lastDeterministicResult when the state actually produced a
+                // verdict/payload (a result-file state). Guard-only deterministic states
+                // leave context byte-identical to the legacy path (the field stays absent).
+                const verdictUpdate = result.verdict !== undefined || result.payload !== undefined
+                    ? {
+                        lastDeterministicResult: {
+                            ...(result.verdict !== undefined ? { verdict: result.verdict } : {}),
+                            ...(result.payload !== undefined ? { payload: result.payload } : {}),
+                        },
+                    }
+                    : {};
+                const baseUpdate = {
+                    previousTestCount: result.testCount ?? context.previousTestCount,
+                    ...verdictUpdate,
+                };
+                if (result.passed)
+                    return baseUpdate;
+                // Set previousStateName to the deterministic state's id (not the prior agent)
+                // so prompt-builder's cross-state framing (buildScopingSection) renders the
+                // failure as "Output from <det-state>" for the next agent.
+                const stateId = event.type.replace('xstate.done.actor.', '');
+                return {
+                    ...baseUpdate,
+                    previousAgentOutput: truncateAgentOutput(result.errors ?? ''),
+                    previousAgentNotes: null,
+                    previousStateName: stateId,
+                };
+            }),
+            // Promotes the batch's joined context onto the parent FSM after a
+            // fan-out invoke resolves (the parent was frozen at `workers` for the
+            // whole batch — see runFanOutSegment). The result already carries the
+            // chosen lane's full WorkflowContext, so this replaces context wholesale.
+            // `if (!result) return {}` keeps the existing context unchanged when the
+            // invoke produced no output — never blanks the parent context on a
+            // malformed/empty result.
+            updateContextFromFanOutResult: assign(({ event }) => {
+                const doneEvent = event;
+                const result = doneEvent.output;
+                if (!result)
+                    return {};
+                return result.context;
+            }),
+            storeHumanPrompt: assign(({ event }) => ({
+                humanPrompt: event.prompt ?? null,
+            })),
+            clearError: assign(() => ({
+                lastError: null,
+            })),
+            storeError: assign(({ event }) => {
+                const errorEvent = event;
+                const err = errorEvent.error;
+                let message;
+                if (err instanceof Error) {
+                    message = err.message;
+                }
+                else if (typeof err === 'object' && err !== null && 'message' in err) {
+                    message = String(err.message);
+                }
+                else if (typeof err === 'string') {
+                    message = err;
+                }
+                else {
+                    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                    message = err != null ? String(err) : 'Unknown error';
+                }
+                // Write directly to stderr to bypass any console hijacking
+                // (logger.setup() redirects console.error to a log file).
+                process.stderr.write(`[workflow] storeError action: ${message}\n`);
+                return { lastError: message };
+            }),
+            /**
+             * Mirrors `updateContextFromAgentResult` for the error path: when
+             * the agent service rejects, recover the `agentConversationId` that
+             * was minted for the invocation (wrapped in `AgentInvocationError`)
+             * and persist it into `context.agentConversationsByState[stateId]`.
+             *
+             * Without this, `onError` drops the conversation id on the floor —
+             * `onDone` stamps the id into context, but `onError` used to record
+             * only `lastError`, which silently broke `freshSession: false`
+             * resume on the next visit to an errored state.
+             */
+            updateContextFromAgentInvocationError: assign(({ context, event }) => {
+                const errorEvent = event;
+                const err = errorEvent.error;
+                if (!isAgentInvocationError(err))
+                    return {};
+                return {
+                    agentConversationsByState: {
+                        ...context.agentConversationsByState,
+                        [err.stateId]: err.agentConversationId,
+                    },
+                };
+            }),
+            incrementVisitCount: assign(({ context }, params) => ({
+                visitCounts: {
+                    ...context.visitCounts,
+                    [params.stateId]: (context.visitCounts[params.stateId] ?? 0) + 1,
+                },
+            })),
+            resetVisitCounts: assign(({ context }, params) => {
+                // Clear only the named keys; leave all other visit counts intact.
+                // Used on transitions that re-enter a bounded loop (e.g., when the
+                // orchestrator sends a fresh hypothesis) to reset the cap without
+                // losing counts for unrelated states.
+                const next = { ...context.visitCounts };
+                for (const stateId of params.stateIds) {
+                    next[stateId] = 0;
+                }
+                return { visitCounts: next };
+            }),
+        },
+    }).createMachine({
+        id: definition.name,
+        initial: definition.initial,
+        context: ({ input }) => {
+            if (options.contextFromInput) {
+                if (!input?.context) {
+                    throw new Error(`machine "${definition.name}" requires input.context`);
+                }
+                return input.context;
+            }
+            return {
+                ...createInitialContext(definition),
+                taskDescription,
+            };
+        },
+        states,
+    });
+    return {
+        machine,
+        roundMachinesByState,
+        gateStateNames,
+        terminalStateNames,
+    };
+}
+//# sourceMappingURL=machine-builder.js.map