@positronic/core 0.0.46 → 0.0.47

package/dist/src/dsl/brain-runner.js

@@ -273,9 +273,10 @@ function _ts_values(o) {
     };
     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
 }
-import { BRAIN_EVENTS, STATUS } from './constants.js';
+import { BRAIN_EVENTS } from './constants.js';
 import { applyPatches } from './json-patch.js';
 import { reconstructLoopContext } from './loop-messages.js';
+import { createBrainExecutionMachine, sendEvent, sendAction, BRAIN_ACTIONS } from './brain-state-machine.js';
 import { DEFAULT_ENV } from './brain.js';
 export var BrainRunner = /*#__PURE__*/ function() {
     "use strict";
@@ -330,7 +331,7 @@ export var BrainRunner = /*#__PURE__*/ function() {
             key: "run",
             value: function run(_0) {
                 return _async_to_generator(function(brain) {
-                    var _ref, _ref_initialState, initialState, options, initialCompletedSteps, brainRunId, endAfter, signal, response, loopEvents, _this_options, adapters, client, resources, pages, env, resolvedEnv, currentState, stepNumber, brainDepth, loopResumeContext, brainRun, _iteratorAbruptCompletion, _didIteratorError, _iteratorError, _loop, _iterator, _step, _ret, err, error, cancelledEvent;
+                    var _ref, _ref_initialState, initialState, options, initialCompletedSteps, brainRunId, endAfter, signal, response, loopEvents, _this_options, adapters, client, resources, pages, env, resolvedEnv, machineInitialState, initialStepCount, machine, loopResumeContext, brainRun, _iteratorAbruptCompletion, _didIteratorError, _iteratorError, _loop, _iterator, _step, _ret, err, error, cancelledEvent;
                     var _arguments = arguments;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
@@ -338,25 +339,23 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                 _ref = _arguments.length > 1 && _arguments[1] !== void 0 ? _arguments[1] : {}, _ref_initialState = _ref.initialState, initialState = _ref_initialState === void 0 ? {} : _ref_initialState, options = _ref.options, initialCompletedSteps = _ref.initialCompletedSteps, brainRunId = _ref.brainRunId, endAfter = _ref.endAfter, signal = _ref.signal, response = _ref.response, loopEvents = _ref.loopEvents;
                                 _this_options = this.options, adapters = _this_options.adapters, client = _this_options.client, resources = _this_options.resources, pages = _this_options.pages, env = _this_options.env;
                                 resolvedEnv = env !== null && env !== void 0 ? env : DEFAULT_ENV;
-                                currentState = initialState !== null && initialState !== void 0 ? initialState : {};
-                                stepNumber = 1;
-                                // Apply any patches from completed steps
-                                // to the initial state so that the brain
-                                // starts with a state that reflects all of the completed steps.
-                                // Need to do this when a brain is restarted with completed steps.
-                                // Note: Only apply top-level step patches, not innerSteps patches
-                                // (inner brain patches are applied to inner brain state, not outer brain state)
+                                // Apply any patches from completed steps to get the initial state
+                                // for the state machine. The machine will then track all subsequent state changes.
+                                machineInitialState = initialState !== null && initialState !== void 0 ? initialState : {};
+                                initialStepCount = 0;
                                 initialCompletedSteps === null || initialCompletedSteps === void 0 ? void 0 : initialCompletedSteps.forEach(function(step) {
                                     if (step.patch) {
-                                        currentState = applyPatches(currentState, [
+                                        machineInitialState = applyPatches(machineInitialState, [
                                             step.patch
                                         ]);
-                                        stepNumber++;
+                                        initialStepCount++;
                                     }
                                 });
-                                // Track brain nesting depth to know which STEP_COMPLETE events
-                                // belong to the top-level brain vs inner brains
-                                brainDepth = 0;
+                                // Create state machine with pre-populated state
+                                // The machine tracks: currentState, isTopLevel, topLevelStepCount, etc.
+                                machine = createBrainExecutionMachine({
+                                    initialState: machineInitialState
+                                });
                                 // If loopEvents and response are provided, reconstruct loop context
                                 loopResumeContext = loopEvents && response ? reconstructLoopContext(loopEvents, response) : null;
                                 brainRun = brainRunId && initialCompletedSteps ? brain.run({
@@ -397,7 +396,7 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                     14
                                 ]);
                                 _loop = function() {
-                                    var _value, event, cancelledEvent;
+                                    var _value, event, cancelledEvent, totalSteps;
                                     return _ts_generator(this, function(_state) {
                                         switch(_state.label){
                                             case 0:
@@ -407,15 +406,9 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                                     3,
                                                     2
                                                 ];
-                                                // Emit a cancelled event
-                                                cancelledEvent = {
-                                                    type: BRAIN_EVENTS.CANCELLED,
-                                                    status: STATUS.CANCELLED,
-                                                    brainTitle: brain.title,
-                                                    brainDescription: brain.structure.description,
-                                                    brainRunId: brainRunId || event.brainRunId,
-                                                    options: event.options
-                                                };
+                                                // Use state machine to create cancelled event
+                                                sendAction(machine, BRAIN_ACTIONS.CANCEL_BRAIN, {});
+                                                cancelledEvent = machine.context.currentEvent;
                                                 return [
                                                     4,
                                                     Promise.all(adapters.map(function(adapter) {
@@ -424,17 +417,16 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                                 ];
                                             case 1:
                                                 _state.sent();
+                                                // Cast is safe: state started as TState and patches maintain the structure
                                                 return [
                                                     2,
                                                     {
-                                                        v: currentState
+                                                        v: machine.context.currentState
                                                     }
                                                 ];
                                             case 2:
-                                                // Track brain nesting depth - START/RESTART increases, COMPLETE decreases
-                                                if (event.type === BRAIN_EVENTS.START || event.type === BRAIN_EVENTS.RESTART) {
-                                                    brainDepth++;
-                                                }
+                                                // Feed event to state machine - this updates currentState, isTopLevel, stepCount, etc.
+                                                sendEvent(machine, event);
                                                 // Dispatch event to all adapters
                                                 return [
                                                     4,
@@ -444,38 +436,28 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                                 ];
                                             case 3:
                                                 _state.sent();
-                                                // Update current state when steps complete
-                                                // Only apply patches from top-level brain (depth === 1)
-                                                // Inner brain patches are applied to inner brain state within brain.ts
-                                                if (event.type === BRAIN_EVENTS.STEP_COMPLETE) {
-                                                    if (event.patch && brainDepth === 1) {
-                                                        currentState = applyPatches(currentState, [
-                                                            event.patch
-                                                        ]);
-                                                    }
-                                                    // Check if we should stop after this step (only for top-level steps)
-                                                    if (brainDepth === 1 && endAfter && stepNumber >= endAfter) {
+                                                // Check if we should stop after this step (only for top-level steps)
+                                                // The machine's topLevelStepCount tracks steps since this run started,
+                                                // so we add initialStepCount to get the total step count.
+                                                if (event.type === BRAIN_EVENTS.STEP_COMPLETE && machine.context.isTopLevel) {
+                                                    totalSteps = machine.context.topLevelStepCount + initialStepCount;
+                                                    if (endAfter && totalSteps >= endAfter) {
+                                                        // Cast is safe: state started as TState and patches maintain the structure
                                                         return [
                                                             2,
                                                             {
-                                                                v: currentState
+                                                                v: machine.context.currentState
                                                             }
                                                         ];
                                                     }
-                                                    if (brainDepth === 1) {
-                                                        stepNumber++;
-                                                    }
-                                                }
-                                                // Track brain completion - decreases nesting depth
-                                                if (event.type === BRAIN_EVENTS.COMPLETE) {
-                                                    brainDepth--;
                                                 }
-                                                // Stop execution when webhook event is encountered
-                                                if (event.type === BRAIN_EVENTS.WEBHOOK) {
+                                                // Stop execution when machine enters paused state (webhook)
+                                                if (machine.context.isPaused) {
+                                                    // Cast is safe: state started as TState and patches maintain the structure
                                                     return [
                                                         2,
                                                         {
-                                                            v: currentState
+                                                            v: machine.context.currentState
                                                         }
                                                     ];
                                                 }
@@ -572,14 +554,8 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                     3,
                                     17
                                 ];
-                                cancelledEvent = {
-                                    type: BRAIN_EVENTS.CANCELLED,
-                                    status: STATUS.CANCELLED,
-                                    brainTitle: brain.title,
-                                    brainDescription: brain.structure.description,
-                                    brainRunId: brainRunId || '',
-                                    options: options || {}
-                                };
+                                sendAction(machine, BRAIN_ACTIONS.CANCEL_BRAIN, {});
+                                cancelledEvent = machine.context.currentEvent;
                                 return [
                                     4,
                                     Promise.all(adapters.map(function(adapter) {
@@ -588,16 +564,18 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                 ];
                             case 16:
                                 _state.sent();
+                                // Cast is safe: state started as TState and patches maintain the structure
                                 return [
                                     2,
-                                    currentState
+                                    machine.context.currentState
                                 ];
                             case 17:
                                 throw error;
                             case 18:
+                                // Cast is safe: state started as TState and patches maintain the structure
                                 return [
                                     2,
-                                    currentState
+                                    machine.context.currentState
                                 ];
                         }
                     });

package/dist/src/dsl/brain-state-machine.js

@@ -0,0 +1,663 @@
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _object_without_properties(source, excluded) {
+    if (source == null) return {};
+    var target = _object_without_properties_loose(source, excluded);
+    var key, i;
+    if (Object.getOwnPropertySymbols) {
+        var sourceSymbolKeys = Object.getOwnPropertySymbols(source);
+        for(i = 0; i < sourceSymbolKeys.length; i++){
+            key = sourceSymbolKeys[i];
+            if (excluded.indexOf(key) >= 0) continue;
+            if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue;
+            target[key] = source[key];
+        }
+    }
+    return target;
+}
+function _object_without_properties_loose(source, excluded) {
+    if (source == null) return {};
+    var target = {};
+    var sourceKeys = Object.keys(source);
+    var key, i;
+    for(i = 0; i < sourceKeys.length; i++){
+        key = sourceKeys[i];
+        if (excluded.indexOf(key) >= 0) continue;
+        target[key] = source[key];
+    }
+    return target;
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+import { createMachine, state, transition, reduce, guard, interpret } from 'robot3';
+import { BRAIN_EVENTS, STATUS } from './constants.js';
+import { applyPatches } from './json-patch.js';
+var createInitialContext = function(opts) {
+    var _opts_initialState, _opts_options;
+    return {
+        brainStack: [],
+        depth: 0,
+        brainRunId: null,
+        currentStepId: null,
+        currentStepTitle: null,
+        error: null,
+        pendingWebhooks: null,
+        currentState: (_opts_initialState = opts === null || opts === void 0 ? void 0 : opts.initialState) !== null && _opts_initialState !== void 0 ? _opts_initialState : {},
+        currentEvent: null,
+        options: (_opts_options = opts === null || opts === void 0 ? void 0 : opts.options) !== null && _opts_options !== void 0 ? _opts_options : {},
+        isTopLevel: false,
+        isRunning: false,
+        isComplete: false,
+        isPaused: false,
+        isError: false,
+        isCancelled: false,
+        topLevelStepCount: 0
+    };
+};
+// ============================================================================
+// Helper to update derived state
+// ============================================================================
+var updateDerivedState = function(ctx, executionState) {
+    return _object_spread_props(_object_spread({}, ctx), {
+        isTopLevel: ctx.depth === 1,
+        isRunning: executionState === 'running',
+        isComplete: executionState === 'complete',
+        isPaused: executionState === 'paused',
+        isError: executionState === 'error',
+        isCancelled: executionState === 'cancelled'
+    });
+};
+// ============================================================================
+// Reducers - Update context on transitions
+// ============================================================================
+var startBrain = reduce(function(ctx, param) {
+    var brainRunId = param.brainRunId, brainTitle = param.brainTitle, brainDescription = param.brainDescription, initialState = param.initialState;
+    var currentStepId = ctx.currentStepId, brainStack = ctx.brainStack, depth = ctx.depth, existingBrainRunId = ctx.brainRunId, currentState = ctx.currentState, options = ctx.options;
+    var newEntry = {
+        brainRunId: brainRunId,
+        brainTitle: brainTitle,
+        brainDescription: brainDescription,
+        parentStepId: currentStepId,
+        steps: []
+    };
+    var newDepth = depth + 1;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        brainStack: _to_consumable_array(brainStack).concat([
+            newEntry
+        ]),
+        depth: newDepth,
+        brainRunId: existingBrainRunId !== null && existingBrainRunId !== void 0 ? existingBrainRunId : brainRunId,
+        currentState: newDepth === 1 ? initialState !== null && initialState !== void 0 ? initialState : currentState : currentState,
+        currentEvent: {
+            type: BRAIN_EVENTS.START,
+            brainTitle: brainTitle,
+            brainDescription: brainDescription,
+            brainRunId: brainRunId,
+            initialState: initialState !== null && initialState !== void 0 ? initialState : {},
+            status: STATUS.RUNNING,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'running');
+});
+var restartBrain = reduce(function(ctx, param) {
+    var brainRunId = param.brainRunId, brainTitle = param.brainTitle, brainDescription = param.brainDescription, initialState = param.initialState;
+    var currentStepId = ctx.currentStepId, brainStack = ctx.brainStack, depth = ctx.depth, existingBrainRunId = ctx.brainRunId, options = ctx.options;
+    var newEntry = {
+        brainRunId: brainRunId,
+        brainTitle: brainTitle,
+        brainDescription: brainDescription,
+        parentStepId: currentStepId,
+        steps: []
+    };
+    var newDepth = depth + 1;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        brainStack: _to_consumable_array(brainStack).concat([
+            newEntry
+        ]),
+        depth: newDepth,
+        brainRunId: existingBrainRunId !== null && existingBrainRunId !== void 0 ? existingBrainRunId : brainRunId,
+        currentEvent: {
+            type: BRAIN_EVENTS.RESTART,
+            brainTitle: brainTitle,
+            brainDescription: brainDescription,
+            brainRunId: brainRunId,
+            initialState: initialState !== null && initialState !== void 0 ? initialState : {},
+            status: STATUS.RUNNING,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'running');
+});
+var completeBrain = reduce(function(ctx) {
+    var brainStack = ctx.brainStack, depth = ctx.depth, brainRunId = ctx.brainRunId, options = ctx.options;
+    if (brainStack.length === 0) return ctx;
+    var completedBrain = brainStack[brainStack.length - 1];
+    var newStack = brainStack.slice(0, -1);
+    // Attach completed brain's steps to parent step if nested
+    if (newStack.length > 0 && completedBrain.parentStepId) {
+        var parentBrain = newStack[newStack.length - 1];
+        var parentStep = parentBrain.steps.find(function(s) {
+            return s.id === completedBrain.parentStepId;
+        });
+        if (parentStep) {
+            parentStep.innerSteps = completedBrain.steps;
+            parentStep.status = STATUS.COMPLETE;
+        }
+    }
+    var newDepth = depth - 1;
+    var isNowComplete = newDepth === 0;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        brainStack: newStack,
+        depth: newDepth,
+        currentEvent: {
+            type: BRAIN_EVENTS.COMPLETE,
+            brainTitle: completedBrain.brainTitle,
+            brainDescription: completedBrain.brainDescription,
+            brainRunId: brainRunId,
+            status: STATUS.COMPLETE,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, isNowComplete ? 'complete' : 'running');
+});
+var errorBrain = reduce(function(ctx, param) {
+    var error = param.error;
+    var brainStack = ctx.brainStack, brainRunId = ctx.brainRunId, options = ctx.options;
+    var currentBrain = brainStack[brainStack.length - 1];
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        error: error,
+        currentEvent: {
+            type: BRAIN_EVENTS.ERROR,
+            brainTitle: currentBrain === null || currentBrain === void 0 ? void 0 : currentBrain.brainTitle,
+            brainDescription: currentBrain === null || currentBrain === void 0 ? void 0 : currentBrain.brainDescription,
+            brainRunId: brainRunId,
+            error: error,
+            status: STATUS.ERROR,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'error');
+});
+var cancelBrain = reduce(function(ctx) {
+    var brainStack = ctx.brainStack, brainRunId = ctx.brainRunId, options = ctx.options;
+    var currentBrain = brainStack[brainStack.length - 1];
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        currentEvent: {
+            type: BRAIN_EVENTS.CANCELLED,
+            brainTitle: currentBrain === null || currentBrain === void 0 ? void 0 : currentBrain.brainTitle,
+            brainDescription: currentBrain === null || currentBrain === void 0 ? void 0 : currentBrain.brainDescription,
+            brainRunId: brainRunId,
+            status: STATUS.CANCELLED,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'cancelled');
+});
+var startStep = reduce(function(ctx, param) {
+    var stepId = param.stepId, stepTitle = param.stepTitle;
+    var brainStack = ctx.brainStack, brainRunId = ctx.brainRunId, options = ctx.options;
+    // Add step to current brain's steps if not already there
+    if (brainStack.length > 0) {
+        var currentBrain = brainStack[brainStack.length - 1];
+        var existingStep = currentBrain.steps.find(function(s) {
+            return s.id === stepId;
+        });
+        if (!existingStep) {
+            currentBrain.steps.push({
+                id: stepId,
+                title: stepTitle,
+                status: STATUS.RUNNING
+            });
+        } else {
+            existingStep.status = STATUS.RUNNING;
+        }
+    }
+    return _object_spread_props(_object_spread({}, ctx), {
+        currentStepId: stepId,
+        currentStepTitle: stepTitle,
+        currentEvent: {
+            type: BRAIN_EVENTS.STEP_START,
+            brainRunId: brainRunId,
+            stepId: stepId,
+            stepTitle: stepTitle,
+            status: STATUS.RUNNING,
+            options: options
+        }
+    });
+});
+var completeStep = reduce(function(ctx, param) {
+    var stepId = param.stepId, stepTitle = param.stepTitle, patch = param.patch;
+    var brainStack = ctx.brainStack, depth = ctx.depth, currentState = ctx.currentState, topLevelStepCount = ctx.topLevelStepCount, brainRunId = ctx.brainRunId, options = ctx.options;
+    if (brainStack.length > 0) {
+        var currentBrain = brainStack[brainStack.length - 1];
+        var step = currentBrain.steps.find(function(s) {
+            return s.id === stepId;
+        });
+        if (step) {
+            step.status = STATUS.COMPLETE;
+            step.patch = patch;
+        }
+    }
+    // Apply patch to currentState only for top-level brain
+    var newState = currentState;
+    var newStepCount = topLevelStepCount;
+    if (depth === 1 && patch) {
+        newState = applyPatches(currentState, [
+            patch
+        ]);
+        newStepCount = topLevelStepCount + 1;
+    }
+    return _object_spread_props(_object_spread({}, ctx), {
+        currentState: newState,
+        topLevelStepCount: newStepCount,
+        currentEvent: {
+            type: BRAIN_EVENTS.STEP_COMPLETE,
+            brainRunId: brainRunId,
+            stepId: stepId,
+            stepTitle: stepTitle,
+            patch: patch,
+            status: STATUS.RUNNING,
+            options: options
+        }
+    });
+});
+var webhookPause = reduce(function(ctx, param) {
+    var waitFor = param.waitFor, state = param.state;
+    var brainRunId = ctx.brainRunId, currentState = ctx.currentState, options = ctx.options;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        pendingWebhooks: waitFor,
+        currentEvent: {
+            type: BRAIN_EVENTS.WEBHOOK,
+            brainRunId: brainRunId,
+            waitFor: waitFor,
+            state: state !== null && state !== void 0 ? state : currentState,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'paused');
+});
+var webhookResponse = reduce(function(ctx, param) {
+    var response = param.response;
+    var brainRunId = ctx.brainRunId, options = ctx.options;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        pendingWebhooks: null,
+        currentEvent: {
+            type: BRAIN_EVENTS.WEBHOOK_RESPONSE,
+            brainRunId: brainRunId,
+            response: response,
+            options: options
+        }
+    });
+    return updateDerivedState(newCtx, 'running');
+});
+var stepStatus = reduce(function(ctx, param) {
+    var eventBrainRunId = param.brainRunId, steps = param.steps;
+    var brainRunId = ctx.brainRunId, brainStack = ctx.brainStack, options = ctx.options;
+    if (brainStack.length === 0) return ctx;
+    // Only update the current (deepest) brain on the stack.
+    // STEP_STATUS is emitted by the currently executing brain, which is always
+    // the deepest one. We can't match by brainRunId because nested brains share
+    // the same brainRunId, which would incorrectly update all nested brains.
+    var updatedStack = brainStack.map(function(brain, index) {
+        if (index === brainStack.length - 1) {
+            // Create a map of existing steps to preserve their patches
+            var existingStepsById = new Map(brain.steps.map(function(s) {
+                return [
+                    s.id,
+                    s
+                ];
+            }));
+            return _object_spread_props(_object_spread({}, brain), {
+                steps: steps.map(function(s) {
+                    var existing = existingStepsById.get(s.id);
+                    return _object_spread({
+                        id: s.id,
+                        title: s.title,
+                        status: s.status
+                    }, (existing === null || existing === void 0 ? void 0 : existing.patch) ? {
+                        patch: existing.patch
+                    } : {});
+                })
+            });
+        }
+        return brain;
+    });
+    return _object_spread_props(_object_spread({}, ctx), {
+        brainStack: updatedStack,
+        currentEvent: {
+            type: BRAIN_EVENTS.STEP_STATUS,
+            brainRunId: brainRunId,
+            steps: steps,
+            options: options
+        }
+    });
+});
+var stepRetry = reduce(function(ctx, param) {
+    var stepId = param.stepId, stepTitle = param.stepTitle, error = param.error, attempt = param.attempt;
+    var brainRunId = ctx.brainRunId, options = ctx.options;
+    return _object_spread_props(_object_spread({}, ctx), {
+        currentEvent: {
+            type: BRAIN_EVENTS.STEP_RETRY,
+            brainRunId: brainRunId,
+            stepId: stepId,
+            stepTitle: stepTitle,
+            error: error,
+            attempt: attempt,
+            options: options
+        }
+    });
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+var passthrough = function(eventType) {
+    return reduce(function(ctx, ev) {
+        var brainRunId = ctx.brainRunId, options = ctx.options;
+        // Destructure to exclude 'type' (the action name) from being spread into currentEvent
+        var _actionType = ev.type, eventData = _object_without_properties(ev, [
+            "type"
+        ]);
+        return _object_spread_props(_object_spread({}, ctx), {
+            currentEvent: _object_spread({
+                type: eventType,
+                brainRunId: brainRunId,
+                options: options
+            }, eventData)
+        });
+    });
+};
+// ============================================================================
+// Guards - Conditional transitions
+// ============================================================================
+var isOuterBrain = guard(function(ctx) {
+    return ctx.depth === 1;
+});
+var isInnerBrain = guard(function(ctx) {
+    return ctx.depth > 1;
+});
+// ============================================================================
+// State Machine Definition
+// ============================================================================
+// Action names for transitions
+var ACTIONS = {
+    START_BRAIN: 'startBrain',
+    RESTART_BRAIN: 'restartBrain',
+    COMPLETE_BRAIN: 'completeBrain',
+    ERROR_BRAIN: 'errorBrain',
+    CANCEL_BRAIN: 'cancelBrain',
+    WEBHOOK: 'webhook',
+    WEBHOOK_RESPONSE: 'webhookResponse',
+    START_STEP: 'startStep',
+    COMPLETE_STEP: 'completeStep',
+    STEP_STATUS: 'stepStatus',
+    STEP_RETRY: 'stepRetry',
+    LOOP_START: 'loopStart',
+    LOOP_ITERATION: 'loopIteration',
+    LOOP_TOOL_CALL: 'loopToolCall',
+    LOOP_TOOL_RESULT: 'loopToolResult',
+    LOOP_ASSISTANT_MESSAGE: 'loopAssistantMessage',
+    LOOP_COMPLETE: 'loopComplete',
+    LOOP_TOKEN_LIMIT: 'loopTokenLimit',
+    LOOP_WEBHOOK: 'loopWebhook',
+    HEARTBEAT: 'heartbeat'
+};
+export { ACTIONS as BRAIN_ACTIONS };
+// Create machine factory - needs to be called with initial context
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+var createBrainMachine = function(initialContext) {
+    return createMachine('idle', {
+        idle: state(transition(ACTIONS.START_BRAIN, 'running', startBrain), transition(ACTIONS.RESTART_BRAIN, 'running', restartBrain)),
+        running: state(// Nested brain lifecycle
+        transition(ACTIONS.START_BRAIN, 'running', startBrain), transition(ACTIONS.RESTART_BRAIN, 'running', restartBrain), // Outer brain complete -> terminal
+        transition(ACTIONS.COMPLETE_BRAIN, 'complete', isOuterBrain, completeBrain), // Inner brain complete -> stay running
+        transition(ACTIONS.COMPLETE_BRAIN, 'running', isInnerBrain, completeBrain), // Error (only outer brain errors are terminal)
+        transition(ACTIONS.ERROR_BRAIN, 'error', isOuterBrain, errorBrain), // Cancelled
+        transition(ACTIONS.CANCEL_BRAIN, 'cancelled', cancelBrain), // Webhook -> paused
+        transition(ACTIONS.WEBHOOK, 'paused', webhookPause), // Webhook response (for resume from webhook - machine is already running)
+        transition(ACTIONS.WEBHOOK_RESPONSE, 'running', webhookResponse), // Step events
+        transition(ACTIONS.START_STEP, 'running', startStep), transition(ACTIONS.COMPLETE_STEP, 'running', completeStep), transition(ACTIONS.STEP_STATUS, 'running', stepStatus), transition(ACTIONS.STEP_RETRY, 'running', stepRetry), // Loop events (pass-through with event data)
+        transition(ACTIONS.LOOP_START, 'running', passthrough(BRAIN_EVENTS.LOOP_START)), transition(ACTIONS.LOOP_ITERATION, 'running', passthrough(BRAIN_EVENTS.LOOP_ITERATION)), transition(ACTIONS.LOOP_TOOL_CALL, 'running', passthrough(BRAIN_EVENTS.LOOP_TOOL_CALL)), transition(ACTIONS.LOOP_TOOL_RESULT, 'running', passthrough(BRAIN_EVENTS.LOOP_TOOL_RESULT)), transition(ACTIONS.LOOP_ASSISTANT_MESSAGE, 'running', passthrough(BRAIN_EVENTS.LOOP_ASSISTANT_MESSAGE)), transition(ACTIONS.LOOP_COMPLETE, 'running', passthrough(BRAIN_EVENTS.LOOP_COMPLETE)), transition(ACTIONS.LOOP_TOKEN_LIMIT, 'running', passthrough(BRAIN_EVENTS.LOOP_TOKEN_LIMIT)), transition(ACTIONS.LOOP_WEBHOOK, 'running', passthrough(BRAIN_EVENTS.LOOP_WEBHOOK)), transition(ACTIONS.HEARTBEAT, 'running', passthrough(BRAIN_EVENTS.HEARTBEAT))),
+        paused: state(transition(ACTIONS.WEBHOOK_RESPONSE, 'running', webhookResponse), transition(ACTIONS.CANCEL_BRAIN, 'cancelled', cancelBrain), // RESTART happens when resuming from webhook
+        transition(ACTIONS.RESTART_BRAIN, 'running', restartBrain)),
+        // Terminal states - limited outgoing transitions
+        complete: state(),
+        error: state(// Allow STEP_STATUS after error so we can emit the final step statuses
+        transition(ACTIONS.STEP_STATUS, 'error', stepStatus)),
+        cancelled: state()
+    }, function() {
+        return initialContext;
+    });
+};
+/**
+ * Create a new brain execution state machine.
+ */ export function createBrainExecutionMachine(options) {
+    var initialContext = createInitialContext(options);
+    var machine = createBrainMachine(initialContext);
+    return interpret(machine, function() {});
+}
+/**
+ * Send a transition action to the machine.
+ * After calling this, read machine.context.currentEvent to get the event to yield.
+ */ export function sendAction(machine, action, payload) {
+    machine.send(_object_spread({
+        type: action
+    }, payload));
+}
+/**
+ * Feed an incoming event into the machine to update state (observer mode).
+ * Maps brain event types to machine actions.
+ */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function sendEvent(machine, event) {
+    var _obj;
+    var eventToAction = (_obj = {}, _define_property(_obj, BRAIN_EVENTS.START, ACTIONS.START_BRAIN), _define_property(_obj, BRAIN_EVENTS.RESTART, ACTIONS.RESTART_BRAIN), _define_property(_obj, BRAIN_EVENTS.COMPLETE, ACTIONS.COMPLETE_BRAIN), _define_property(_obj, BRAIN_EVENTS.ERROR, ACTIONS.ERROR_BRAIN), _define_property(_obj, BRAIN_EVENTS.CANCELLED, ACTIONS.CANCEL_BRAIN), _define_property(_obj, BRAIN_EVENTS.WEBHOOK, ACTIONS.WEBHOOK), _define_property(_obj, BRAIN_EVENTS.WEBHOOK_RESPONSE, ACTIONS.WEBHOOK_RESPONSE), _define_property(_obj, BRAIN_EVENTS.STEP_START, ACTIONS.START_STEP), _define_property(_obj, BRAIN_EVENTS.STEP_COMPLETE, ACTIONS.COMPLETE_STEP), _define_property(_obj, BRAIN_EVENTS.STEP_STATUS, ACTIONS.STEP_STATUS), _define_property(_obj, BRAIN_EVENTS.STEP_RETRY, ACTIONS.STEP_RETRY), _define_property(_obj, BRAIN_EVENTS.LOOP_START, ACTIONS.LOOP_START), _define_property(_obj, BRAIN_EVENTS.LOOP_ITERATION, ACTIONS.LOOP_ITERATION), _define_property(_obj, BRAIN_EVENTS.LOOP_TOOL_CALL, ACTIONS.LOOP_TOOL_CALL), _define_property(_obj, BRAIN_EVENTS.LOOP_TOOL_RESULT, ACTIONS.LOOP_TOOL_RESULT), _define_property(_obj, BRAIN_EVENTS.LOOP_ASSISTANT_MESSAGE, ACTIONS.LOOP_ASSISTANT_MESSAGE), _define_property(_obj, BRAIN_EVENTS.LOOP_COMPLETE, ACTIONS.LOOP_COMPLETE), _define_property(_obj, BRAIN_EVENTS.LOOP_TOKEN_LIMIT, ACTIONS.LOOP_TOKEN_LIMIT), _define_property(_obj, BRAIN_EVENTS.LOOP_WEBHOOK, ACTIONS.LOOP_WEBHOOK), _define_property(_obj, BRAIN_EVENTS.HEARTBEAT, ACTIONS.HEARTBEAT), _obj);
+    var action = eventToAction[event.type];
+    if (action) {
+        var payload = extractPayloadFromEvent(event);
+        machine.send(_object_spread({
+            type: action
+        }, payload));
+    }
+}
+/**
+ * Extract relevant payload fields from a brain event for the state machine.
+ */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractPayloadFromEvent(event) {
+    switch(event.type){
+        case BRAIN_EVENTS.START:
+        case BRAIN_EVENTS.RESTART:
+            return {
+                brainRunId: event.brainRunId,
+                brainTitle: event.brainTitle,
+                brainDescription: event.brainDescription,
+                initialState: event.initialState
+            };
+        case BRAIN_EVENTS.STEP_START:
+            return {
+                stepId: event.stepId,
+                stepTitle: event.stepTitle
+            };
+        case BRAIN_EVENTS.STEP_COMPLETE:
+            return {
+                stepId: event.stepId,
+                stepTitle: event.stepTitle,
+                patch: event.patch
+            };
+        case BRAIN_EVENTS.ERROR:
+            return {
+                error: event.error
+            };
+        case BRAIN_EVENTS.WEBHOOK:
+            return {
+                waitFor: event.waitFor,
+                state: event.state
+            };
+        case BRAIN_EVENTS.WEBHOOK_RESPONSE:
+            return {
+                response: event.response
+            };
+        case BRAIN_EVENTS.STEP_STATUS:
+            return {
+                brainRunId: event.brainRunId,
+                steps: event.steps
+            };
+        case BRAIN_EVENTS.STEP_RETRY:
+            return {
+                stepId: event.stepId,
+                stepTitle: event.stepTitle,
+                error: event.error,
+                attempt: event.attempt
+            };
+        default:
+            // For pass-through events, pass all properties except type
+            var type = event.type, rest = _object_without_properties(event, [
+                "type"
+            ]);
+            return rest;
+    }
+}
+// ============================================================================
+// Query Helpers (kept for backwards compatibility, but context is now preferred)
+// ============================================================================
+export function getDepth(machine) {
+    return machine.context.depth;
+}
+export function isTopLevel(machine) {
+    return machine.context.isTopLevel;
+}
+export function getCurrentStep(machine) {
+    var _machine_context = machine.context, brainStack = _machine_context.brainStack, currentStepId = _machine_context.currentStepId;
+    if (brainStack.length === 0 || !currentStepId) return null;
+    var currentBrain = brainStack[brainStack.length - 1];
+    var _currentBrain_steps_find;
+    return (_currentBrain_steps_find = currentBrain.steps.find(function(s) {
+        return s.id === currentStepId;
+    })) !== null && _currentBrain_steps_find !== void 0 ? _currentBrain_steps_find : null;
+}
+export function getBrainStack(machine) {
+    return machine.context.brainStack;
+}
+export function getBrainRunId(machine) {
+    return machine.context.brainRunId;
+}
+export function getExecutionState(machine) {
+    return machine.machine.current;
+}
+export function getPendingWebhooks(machine) {
+    return machine.context.pendingWebhooks;
+}
+export function getError(machine) {
+    return machine.context.error;
+}
+/**
+ * Get the completed steps from the state machine in the format needed for resume.
+ * This reconstructs the nested step hierarchy from the brain stack.
+ * Returns a deep copy to avoid mutating the state machine's context.
+ */ export function getCompletedSteps(machine) {
+    var brainStack = machine.context.brainStack;
+    if (brainStack.length === 0) {
+        return [];
+    }
+    // Deep copy the steps to avoid mutating state machine context
+    var copyStep = function(step) {
+        var _step_innerSteps;
+        return _object_spread_props(_object_spread({}, step), {
+            innerSteps: (_step_innerSteps = step.innerSteps) === null || _step_innerSteps === void 0 ? void 0 : _step_innerSteps.map(copyStep)
+        });
+    };
+    var copyBrainStack = brainStack.map(function(brain) {
+        return _object_spread_props(_object_spread({}, brain), {
+            steps: brain.steps.map(copyStep)
+        });
+    });
+    // The outer brain's steps, with inner brain steps nested
+    var outerBrain = copyBrainStack[0];
+    // If there are nested brains still on the stack (paused mid-execution),
+    // attach their steps to the parent step as innerSteps
+    if (copyBrainStack.length > 1) {
+        var _loop = function(i) {
+            var innerBrain = copyBrainStack[i];
+            var parentBrain = copyBrainStack[i - 1];
+            // Find the parent step (the one that started this inner brain)
+            var parentStep = parentBrain.steps.find(function(s) {
+                return s.id === innerBrain.parentStepId;
+            });
+            if (parentStep) {
+                parentStep.innerSteps = innerBrain.steps;
+            }
+        };
+        for(var i = copyBrainStack.length - 1; i > 0; i--)_loop(i);
+    }
+    return outerBrain.steps;
+}

package/dist/src/index.js

@@ -11,3 +11,5 @@ export { createResources } from './resources/resources.js';
 export { createWebhook } from './dsl/webhook.js';
 export { RESOURCE_TYPES } from './resources/resources.js';
 export { reconstructLoopContext } from './dsl/loop-messages.js';
+// Brain state machine
+export { createBrainExecutionMachine, sendAction, sendEvent, getDepth, isTopLevel, getCurrentStep, getBrainStack, getBrainRunId, getExecutionState, getPendingWebhooks, getError, getCompletedSteps, BRAIN_ACTIONS } from './dsl/brain-state-machine.js';

package/dist/types/dsl/brain-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain-runner.d.ts","sourceRoot":"","sources":["../../../src/dsl/brain-runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAe,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,qBAAa,WAAW;IAEpB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE;QACf,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,EAAE,eAAe,CAAC;QACxB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,GAAG,CAAC,EAAE,UAAU,CAAC;KAClB;IAGH,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW;IAQ9C,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,WAAW;IAOhD,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW;IAOhD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW;IAO3C,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW;IAO/B,GAAG,CAAC,QAAQ,SAAS,UAAU,GAAG,EAAE,EAAE,MAAM,SAAS,KAAK,GAAG,EAAE,EACnE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EACnC,EACE,YAA2B,EAC3B,OAAO,EACP,qBAAqB,EACrB,UAAU,EACV,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,UAAU,GACX,GAAE;QACD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,QAAQ,CAAC;QACnB,qBAAqB,CAAC,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;QACjD,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,QAAQ,CAAC,EAAE,UAAU,CAAC;QACtB,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;KACtB,GACL,OAAO,CAAC,MAAM,CAAC;CA8HnB"}
+{"version":3,"file":"brain-runner.d.ts","sourceRoot":"","sources":["../../../src/dsl/brain-runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAe,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,qBAAa,WAAW;IAEpB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE;QACf,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,EAAE,eAAe,CAAC;QACxB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,GAAG,CAAC,EAAE,UAAU,CAAC;KAClB;IAGH,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW;IAQ9C,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,WAAW;IAOhD,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW;IAOhD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW;IAO3C,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW;IAO/B,GAAG,CAAC,QAAQ,SAAS,UAAU,GAAG,EAAE,EAAE,MAAM,SAAS,KAAK,GAAG,EAAE,EACnE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EACnC,EACE,YAA2B,EAC3B,OAAO,EACP,qBAAqB,EACrB,UAAU,EACV,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,UAAU,GACX,GAAE;QACD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,QAAQ,CAAC;QACnB,qBAAqB,CAAC,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;QACjD,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,QAAQ,CAAC,EAAE,UAAU,CAAC;QACtB,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;KACtB,GACL,OAAO,CAAC,MAAM,CAAC;CAmGnB"}

package/dist/types/dsl/brain-state-machine.d.ts

@@ -0,0 +1,156 @@
+import { STATUS } from './constants.js';
+import type { JsonPatch, JsonObject } from './types.js';
+export interface BrainStackEntry {
+    brainRunId: string;
+    brainTitle: string;
+    brainDescription?: string;
+    parentStepId: string | null;
+    steps: StepInfo[];
+}
+export interface StepInfo {
+    id: string;
+    title: string;
+    status: (typeof STATUS)[keyof typeof STATUS];
+    patch?: JsonPatch;
+    innerSteps?: StepInfo[];
+}
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export interface WebhookRegistration {
+    name: string;
+    identifier: string;
+}
+export interface BrainEvent {
+    type: string;
+    brainRunId: string;
+    options: JsonObject;
+    [key: string]: unknown;
+}
+export interface BrainExecutionContext {
+    brainStack: BrainStackEntry[];
+    depth: number;
+    brainRunId: string | null;
+    currentStepId: string | null;
+    currentStepTitle: string | null;
+    error: SerializedError | null;
+    pendingWebhooks: WebhookRegistration[] | null;
+    currentState: JsonObject;
+    currentEvent: BrainEvent | null;
+    options: JsonObject;
+    isTopLevel: boolean;
+    isRunning: boolean;
+    isComplete: boolean;
+    isPaused: boolean;
+    isError: boolean;
+    isCancelled: boolean;
+    topLevelStepCount: number;
+}
+export type ExecutionState = 'idle' | 'running' | 'paused' | 'complete' | 'error' | 'cancelled';
+export interface StartBrainPayload {
+    brainRunId: string;
+    brainTitle: string;
+    brainDescription?: string;
+    initialState?: JsonObject;
+}
+export interface StartStepPayload {
+    stepId: string;
+    stepTitle: string;
+}
+export interface CompleteStepPayload {
+    stepId: string;
+    stepTitle: string;
+    patch?: JsonPatch;
+}
+export interface WebhookPayload {
+    waitFor: WebhookRegistration[];
+    state?: JsonObject;
+}
+export interface ErrorPayload {
+    error: SerializedError;
+}
+export interface StepStatusPayload {
+    brainRunId: string;
+    steps: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+}
+export interface StepRetryPayload {
+    stepId: string;
+    stepTitle: string;
+    error: SerializedError;
+    attempt: number;
+}
+export interface CreateMachineOptions {
+    initialState?: JsonObject;
+    options?: JsonObject;
+}
+declare const ACTIONS: {
+    readonly START_BRAIN: "startBrain";
+    readonly RESTART_BRAIN: "restartBrain";
+    readonly COMPLETE_BRAIN: "completeBrain";
+    readonly ERROR_BRAIN: "errorBrain";
+    readonly CANCEL_BRAIN: "cancelBrain";
+    readonly WEBHOOK: "webhook";
+    readonly WEBHOOK_RESPONSE: "webhookResponse";
+    readonly START_STEP: "startStep";
+    readonly COMPLETE_STEP: "completeStep";
+    readonly STEP_STATUS: "stepStatus";
+    readonly STEP_RETRY: "stepRetry";
+    readonly LOOP_START: "loopStart";
+    readonly LOOP_ITERATION: "loopIteration";
+    readonly LOOP_TOOL_CALL: "loopToolCall";
+    readonly LOOP_TOOL_RESULT: "loopToolResult";
+    readonly LOOP_ASSISTANT_MESSAGE: "loopAssistantMessage";
+    readonly LOOP_COMPLETE: "loopComplete";
+    readonly LOOP_TOKEN_LIMIT: "loopTokenLimit";
+    readonly LOOP_WEBHOOK: "loopWebhook";
+    readonly HEARTBEAT: "heartbeat";
+};
+export { ACTIONS as BRAIN_ACTIONS };
+export interface BrainStateMachine {
+    machine: {
+        current: string;
+        context: BrainExecutionContext;
+    };
+    context: BrainExecutionContext;
+    send: (event: {
+        type: string;
+        [key: string]: unknown;
+    }) => void;
+}
+/**
+ * Create a new brain execution state machine.
+ */
+export declare function createBrainExecutionMachine(options?: CreateMachineOptions): BrainStateMachine;
+/**
+ * Send a transition action to the machine.
+ * After calling this, read machine.context.currentEvent to get the event to yield.
+ */
+export declare function sendAction(machine: BrainStateMachine, action: string, payload?: object): void;
+/**
+ * Feed an incoming event into the machine to update state (observer mode).
+ * Maps brain event types to machine actions.
+ */
+export declare function sendEvent(machine: BrainStateMachine, event: {
+    type: string;
+} & Record<string, any>): void;
+export declare function getDepth(machine: BrainStateMachine): number;
+export declare function isTopLevel(machine: BrainStateMachine): boolean;
+export declare function getCurrentStep(machine: BrainStateMachine): StepInfo | null;
+export declare function getBrainStack(machine: BrainStateMachine): BrainStackEntry[];
+export declare function getBrainRunId(machine: BrainStateMachine): string | null;
+export declare function getExecutionState(machine: BrainStateMachine): ExecutionState;
+export declare function getPendingWebhooks(machine: BrainStateMachine): WebhookRegistration[] | null;
+export declare function getError(machine: BrainStateMachine): SerializedError | null;
+/**
+ * Get the completed steps from the state machine in the format needed for resume.
+ * This reconstructs the nested step hierarchy from the brain stack.
+ * Returns a deep copy to avoid mutating the state machine's context.
+ */
+export declare function getCompletedSteps(machine: BrainStateMachine): StepInfo[];
+//# sourceMappingURL=brain-state-machine.d.ts.map

package/dist/types/dsl/brain-state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-state-machine.d.ts","sourceRoot":"","sources":["../../../src/dsl/brain-state-machine.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -17,4 +17,6 @@ export { RESOURCE_TYPES } from './resources/resources.js';
 export type { LoopStartEvent, LoopIterationEvent, LoopToolCallEvent, LoopToolResultEvent, LoopAssistantMessageEvent, LoopCompleteEvent, LoopTokenLimitEvent, LoopWebhookEvent, WebhookResponseEvent, HeartbeatEvent, } from './dsl/brain.js';
 export type { LoopResumeContext } from './dsl/loop-messages.js';
 export { reconstructLoopContext } from './dsl/loop-messages.js';
+export { createBrainExecutionMachine, sendAction, sendEvent, getDepth, isTopLevel, getCurrentStep, getBrainStack, getBrainRunId, getExecutionState, getPendingWebhooks, getError, getCompletedSteps, BRAIN_ACTIONS, } from './dsl/brain-state-machine.js';
+export type { BrainStateMachine, BrainExecutionContext, BrainStackEntry, StepInfo, ExecutionState, CreateMachineOptions, } from './dsl/brain-state-machine.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMhE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,KAAK,IAAI,aAAa,EACtB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMhE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,KAAK,IAAI,aAAa,EACtB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,EACR,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,aAAa,GACd,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,oBAAoB,GACrB,MAAM,8BAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/core",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "publishConfig": {
     "access": "public"
   },
@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "fast-json-patch": "^3.1.1",
+    "robot3": "^1.2.0",
     "uuid": "^11.0.5"
   },
   "devDependencies": {