@positronic/core 0.0.37 → 0.0.38

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

@@ -275,6 +275,7 @@ function _ts_values(o) {
 }
 import { BRAIN_EVENTS, STATUS } from './constants.js';
 import { applyPatches } from './json-patch.js';
+import { reconstructLoopContext } from './loop-messages.js';
 import { DEFAULT_ENV } from './brain.js';
 export var BrainRunner = /*#__PURE__*/ function() {
     "use strict";
@@ -329,12 +330,12 @@ 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, _this_options, adapters, client, resources, pages, env, resolvedEnv, currentState, stepNumber, 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, currentState, stepNumber, loopResumeContext, brainRun, _iteratorAbruptCompletion, _didIteratorError, _iteratorError, _loop, _iterator, _step, _ret, err, error, cancelledEvent;
                     var _arguments = arguments;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
-                                _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;
+                                _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 : {};
@@ -351,6 +352,8 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                         stepNumber++;
                                     }
                                 });
+                                // If loopEvents and response are provided, reconstruct loop context
+                                loopResumeContext = loopEvents && response ? reconstructLoopContext(loopEvents, response) : null;
                                 brainRun = brainRunId && initialCompletedSteps ? brain.run({
                                     initialState: initialState,
                                     initialCompletedSteps: initialCompletedSteps,
@@ -360,7 +363,8 @@ export var BrainRunner = /*#__PURE__*/ function() {
                                     resources: resources !== null && resources !== void 0 ? resources : {},
                                     pages: pages,
                                     env: resolvedEnv,
-                                    response: response
+                                    response: response,
+                                    loopResumeContext: loopResumeContext
                                 }) : brain.run({
                                     initialState: initialState,
                                     options: options,

package/dist/src/dsl/brain.js

@@ -1,3 +1,11 @@
+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_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
 function _async_generator(gen) {
     var front, back;
     function send(key, arg) {
@@ -219,6 +227,33 @@ function _define_property(obj, key, value) {
     }
     return obj;
 }
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure 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] : {};
@@ -289,10 +324,21 @@ function _overload_yield(value, kind) {
     this.v = value;
     this.k = kind;
 }
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
 function _type_of(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
+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);
+}
 function _wrap_async_generator(fn) {
     return function() {
         return new _async_generator(fn.apply(this, arguments));
@@ -442,6 +488,11 @@ export var Brain = /*#__PURE__*/ function() {
                                 type: 'step',
                                 title: block.title
                             };
+                        } else if (block.type === 'loop') {
+                            return {
+                                type: 'loop',
+                                title: block.title
+                            };
                         } else {
                             // block.type === 'brain'
                             return {
@@ -513,6 +564,25 @@ export var Brain = /*#__PURE__*/ function() {
                 return this.nextBrain();
             }
         },
+        {
+            /**
+   * Add an agentic loop step that runs an LLM with tools.
+   * The loop continues until a terminal tool is called, no tool calls are returned,
+   * or maxTokens is exceeded.
+   */ key: "loop",
+            value: function loop(title, configFn) {
+                var loopBlock = {
+                    type: 'loop',
+                    title: title,
+                    configFn: configFn
+                };
+                this.blocks.push(loopBlock);
+                var nextBrain = new Brain(this.title, this.description).withBlocks(this.blocks);
+                nextBrain.services = this.services;
+                nextBrain.optionsSchema = this.optionsSchema;
+                return nextBrain;
+            }
+        },
         {
             // TResponseKey:
             // The response key must be a string literal, so if defining a response model
@@ -699,7 +769,8 @@ var BrainEventStream = /*#__PURE__*/ function() {
         _define_property(this, "pages", void 0);
         _define_property(this, "env", void 0);
         _define_property(this, "currentResponse", undefined);
-        var _params_initialState = params.initialState, initialState = _params_initialState === void 0 ? {} : _params_initialState, initialCompletedSteps = params.initialCompletedSteps, blocks = params.blocks, title = params.title, description = params.description, providedBrainRunId = params.brainRunId, _params_options = params.options, options = _params_options === void 0 ? {} : _params_options, client = params.client, services = params.services, _params_resources = params.resources, resources = _params_resources === void 0 ? {} : _params_resources, pages = params.pages, env = params.env, response = params.response;
+        _define_property(this, "loopResumeContext", undefined);
+        var _params_initialState = params.initialState, initialState = _params_initialState === void 0 ? {} : _params_initialState, initialCompletedSteps = params.initialCompletedSteps, blocks = params.blocks, title = params.title, description = params.description, providedBrainRunId = params.brainRunId, _params_options = params.options, options = _params_options === void 0 ? {} : _params_options, client = params.client, services = params.services, _params_resources = params.resources, resources = _params_resources === void 0 ? {} : _params_resources, pages = params.pages, env = params.env, response = params.response, loopResumeContext = params.loopResumeContext;
         this.initialState = initialState;
         this.title = title;
         this.description = description;
@@ -748,6 +819,10 @@ var BrainEventStream = /*#__PURE__*/ function() {
         if (response) {
             this.currentResponse = response;
         }
+        // Set loop resume context if provided (for loop webhook restarts)
+        if (loopResumeContext) {
+            this.loopResumeContext = loopResumeContext;
+        }
     }
     _create_class(BrainEventStream, [
         {
@@ -1076,27 +1151,42 @@ var BrainEventStream = /*#__PURE__*/ function() {
                                 _state.sent();
                                 return [
                                     3,
-                                    28
+                                    30
                                 ];
                             case 16:
+                                if (!(block.type === 'loop')) return [
+                                    3,
+                                    18
+                                ];
+                                return [
+                                    5,
+                                    _ts_values(_async_generator_delegate(_async_iterator(this.executeLoop(step))))
+                                ];
+                            case 17:
+                                _state.sent();
+                                return [
+                                    3,
+                                    30
+                                ];
+                            case 18:
                                 // Get previous state before action
                                 prevState1 = this.currentState;
                                 stepBlock = block;
                                 // Execute step with automatic retry on failure
                                 retries = 0;
-                                _state.label = 17;
-                            case 17:
+                                _state.label = 19;
+                            case 19:
                                 if (!true) return [
                                     3,
-                                    25
+                                    27
                                 ];
-                                _state.label = 18;
-                            case 18:
+                                _state.label = 20;
+                            case 20:
                                 _state.trys.push([
-                                    18,
                                     20,
+                                    22,
                                     ,
-                                    24
+                                    26
                                 ]);
                                 actionPromise = Promise.resolve(stepBlock.action(_object_spread({
                                     state: this.currentState,
@@ -1111,17 +1201,17 @@ var BrainEventStream = /*#__PURE__*/ function() {
                                     4,
                                     _await_async_generator(actionPromise)
                                 ];
-                            case 19:
+                            case 21:
                                 result = _state.sent();
                                 return [
                                     3,
-                                    25
+                                    27
                                 ]; // Success
-                            case 20:
+                            case 22:
                                 error = _state.sent();
                                 if (!(retries < MAX_RETRIES)) return [
                                     3,
-                                    22
+                                    24
                                 ];
                                 retries++;
                                 return [
@@ -1140,35 +1230,35 @@ var BrainEventStream = /*#__PURE__*/ function() {
                                         brainRunId: this.brainRunId
                                     }
                                 ];
-                            case 21:
+                            case 23:
                                 _state.sent();
                                 return [
                                     3,
-                                    23
+                                    25
                                 ];
-                            case 22:
+                            case 24:
                                 throw error;
-                            case 23:
+                            case 25:
                                 return [
                                     3,
-                                    24
+                                    26
                                 ];
-                            case 24:
+                            case 26:
                                 return [
                                     3,
-                                    17
+                                    19
                                 ];
-                            case 25:
+                            case 27:
                                 this.currentState = result && (typeof result === "undefined" ? "undefined" : _type_of(result)) === 'object' && 'waitFor' in result ? result.state : result;
                                 return [
                                     5,
                                     _ts_values(_async_generator_delegate(_async_iterator(this.completeStep(step, prevState1))))
                                 ];
-                            case 26:
+                            case 28:
                                 _state.sent();
                                 if (!(result && (typeof result === "undefined" ? "undefined" : _type_of(result)) === 'object' && 'waitFor' in result)) return [
                                     3,
-                                    28
+                                    30
                                 ];
                                 // Serialize webhook registrations (remove Zod schemas for event serializability)
                                 serializedWaitFor = result.waitFor.map(function(registration) {
@@ -1187,10 +1277,420 @@ var BrainEventStream = /*#__PURE__*/ function() {
                                         brainRunId: this.brainRunId
                                     }
                                 ];
+                            case 29:
+                                _state.sent();
+                                _state.label = 30;
+                            case 30:
+                                return [
+                                    2
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
+        {
+            key: "executeLoop",
+            value: function executeLoop(step) {
+                return _wrap_async_generator(function() {
+                    var block, prevState, _this_options, config, messages, resumeContext, _this_options1, _this_options2, _this_options3, totalTokens, iteration, _this_options4, toolsForClient, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, name, toolDef, tool, response, _this_options5, _this_options6, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, toolCall, _this_options7, tool1, _this_options8, toolResult, waitForResult, _this_options9, _this_options10, _this_options11, err;
+                    return _ts_generator(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                block = step.block;
+                                prevState = this.currentState;
+                                return [
+                                    4,
+                                    _await_async_generator(block.configFn(_object_spread({
+                                        state: this.currentState,
+                                        options: (_this_options = this.options) !== null && _this_options !== void 0 ? _this_options : {},
+                                        client: this.client,
+                                        resources: this.resources,
+                                        response: this.currentResponse,
+                                        pages: this.pages,
+                                        env: this.env
+                                    }, this.services)))
+                                ];
+                            case 1:
+                                config = _state.sent();
+                                if (!this.loopResumeContext) return [
+                                    3,
+                                    4
+                                ];
+                                resumeContext = this.loopResumeContext;
+                                // Emit WEBHOOK_RESPONSE event to record the response
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.WEBHOOK_RESPONSE,
+                                        response: this.currentResponse,
+                                        options: (_this_options1 = this.options) !== null && _this_options1 !== void 0 ? _this_options1 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 2:
+                                _state.sent();
+                                // Emit LOOP_TOOL_RESULT for the pending tool (webhook response injected as tool result)
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_TOOL_RESULT,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        toolCallId: resumeContext.pendingToolCallId,
+                                        toolName: resumeContext.pendingToolName,
+                                        result: this.currentResponse,
+                                        options: (_this_options2 = this.options) !== null && _this_options2 !== void 0 ? _this_options2 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 3:
+                                _state.sent();
+                                // Use restored messages from the resume context
+                                messages = resumeContext.messages;
+                                // Clear the context so it's only used once
+                                this.loopResumeContext = undefined;
+                                return [
+                                    3,
+                                    6
+                                ];
+                            case 4:
+                                // Emit loop start event (only for fresh starts)
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_START,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        prompt: config.prompt,
+                                        system: config.system,
+                                        options: (_this_options3 = this.options) !== null && _this_options3 !== void 0 ? _this_options3 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 5:
+                                _state.sent();
+                                // Initialize messages for fresh start
+                                messages = [
+                                    {
+                                        role: 'user',
+                                        content: config.prompt
+                                    }
+                                ];
+                                _state.label = 6;
+                            case 6:
+                                // Initialize token tracking
+                                totalTokens = 0;
+                                iteration = 0;
+                                _state.label = 7;
+                            case 7:
+                                if (!true) return [
+                                    3,
+                                    33
+                                ];
+                                iteration++;
+                                // Emit iteration event
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_ITERATION,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        iteration: iteration,
+                                        options: (_this_options4 = this.options) !== null && _this_options4 !== void 0 ? _this_options4 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 8:
+                                _state.sent();
+                                // Check if client supports generateText
+                                if (!this.client.generateText) {
+                                    throw new Error('Client does not support generateText. Use a client that implements generateText for loop steps.');
+                                }
+                                // Build tools object for the client (description and inputSchema only)
+                                toolsForClient = {};
+                                _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                                try {
+                                    for(_iterator = Object.entries(config.tools)[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                                        _step_value = _sliced_to_array(_step.value, 2), name = _step_value[0], toolDef = _step_value[1];
+                                        tool = toolDef;
+                                        toolsForClient[name] = {
+                                            description: tool.description,
+                                            inputSchema: tool.inputSchema
+                                        };
+                                    }
+                                } catch (err) {
+                                    _didIteratorError = true;
+                                    _iteratorError = err;
+                                } finally{
+                                    try {
+                                        if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                            _iterator.return();
+                                        }
+                                    } finally{
+                                        if (_didIteratorError) {
+                                            throw _iteratorError;
+                                        }
+                                    }
+                                }
+                                return [
+                                    4,
+                                    _await_async_generator(this.client.generateText({
+                                        system: config.system,
+                                        messages: messages,
+                                        tools: toolsForClient
+                                    }))
+                                ];
+                            case 9:
+                                response = _state.sent();
+                                // Track tokens
+                                totalTokens += response.usage.totalTokens;
+                                if (!(config.maxTokens && totalTokens > config.maxTokens)) return [
+                                    3,
+                                    12
+                                ];
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_TOKEN_LIMIT,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        totalTokens: totalTokens,
+                                        maxTokens: config.maxTokens,
+                                        options: (_this_options5 = this.options) !== null && _this_options5 !== void 0 ? _this_options5 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 10:
+                                _state.sent();
+                                return [
+                                    5,
+                                    _ts_values(_async_generator_delegate(_async_iterator(this.completeStep(step, prevState))))
+                                ];
+                            case 11:
+                                _state.sent();
+                                return [
+                                    2
+                                ];
+                            case 12:
+                                if (!response.text) return [
+                                    3,
+                                    14
+                                ];
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_ASSISTANT_MESSAGE,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        content: response.text,
+                                        options: (_this_options6 = this.options) !== null && _this_options6 !== void 0 ? _this_options6 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 13:
+                                _state.sent();
+                                messages.push({
+                                    role: 'assistant',
+                                    content: response.text
+                                });
+                                _state.label = 14;
+                            case 14:
+                                if (!(!response.toolCalls || response.toolCalls.length === 0)) return [
+                                    3,
+                                    16
+                                ];
+                                return [
+                                    5,
+                                    _ts_values(_async_generator_delegate(_async_iterator(this.completeStep(step, prevState))))
+                                ];
+                            case 15:
+                                _state.sent();
+                                return [
+                                    2
+                                ];
+                            case 16:
+                                _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                                _state.label = 17;
+                            case 17:
+                                _state.trys.push([
+                                    17,
+                                    30,
+                                    31,
+                                    32
+                                ]);
+                                _iterator1 = response.toolCalls[Symbol.iterator]();
+                                _state.label = 18;
+                            case 18:
+                                if (!!(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done)) return [
+                                    3,
+                                    29
+                                ];
+                                toolCall = _step1.value;
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_TOOL_CALL,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        toolName: toolCall.toolName,
+                                        toolCallId: toolCall.toolCallId,
+                                        input: toolCall.args,
+                                        options: (_this_options7 = this.options) !== null && _this_options7 !== void 0 ? _this_options7 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 19:
+                                _state.sent();
+                                tool1 = config.tools[toolCall.toolName];
+                                if (!tool1) {
+                                    throw new Error("Unknown tool: ".concat(toolCall.toolName));
+                                }
+                                if (!tool1.terminal) return [
+                                    3,
+                                    22
+                                ];
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_COMPLETE,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        terminalToolName: toolCall.toolName,
+                                        result: toolCall.args,
+                                        totalIterations: iteration,
+                                        options: (_this_options8 = this.options) !== null && _this_options8 !== void 0 ? _this_options8 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 20:
+                                _state.sent();
+                                // Merge terminal result into state
+                                this.currentState = _object_spread({}, this.currentState, toolCall.args);
+                                return [
+                                    5,
+                                    _ts_values(_async_generator_delegate(_async_iterator(this.completeStep(step, prevState))))
+                                ];
+                            case 21:
+                                _state.sent();
+                                return [
+                                    2
+                                ];
+                            case 22:
+                                if (!tool1.execute) return [
+                                    3,
+                                    28
+                                ];
+                                return [
+                                    4,
+                                    _await_async_generator(Promise.resolve(tool1.execute(toolCall.args)))
+                                ];
+                            case 23:
+                                toolResult = _state.sent();
+                                if (!(toolResult && (typeof toolResult === "undefined" ? "undefined" : _type_of(toolResult)) === 'object' && 'waitFor' in toolResult)) return [
+                                    3,
+                                    26
+                                ];
+                                waitForResult = toolResult;
+                                // Emit loop webhook event first (captures pending tool context)
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_WEBHOOK,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        toolCallId: toolCall.toolCallId,
+                                        toolName: toolCall.toolName,
+                                        input: toolCall.args,
+                                        options: (_this_options9 = this.options) !== null && _this_options9 !== void 0 ? _this_options9 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 24:
+                                _state.sent();
+                                // Then emit webhook event
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.WEBHOOK,
+                                        waitFor: [
+                                            {
+                                                slug: waitForResult.waitFor.slug,
+                                                identifier: waitForResult.waitFor.identifier
+                                            }
+                                        ],
+                                        state: this.currentState,
+                                        options: (_this_options10 = this.options) !== null && _this_options10 !== void 0 ? _this_options10 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
+                            case 25:
+                                _state.sent();
+                                return [
+                                    2
+                                ];
+                            case 26:
+                                // Normal tool result
+                                return [
+                                    4,
+                                    {
+                                        type: BRAIN_EVENTS.LOOP_TOOL_RESULT,
+                                        stepTitle: step.block.title,
+                                        stepId: step.id,
+                                        toolName: toolCall.toolName,
+                                        toolCallId: toolCall.toolCallId,
+                                        result: toolResult,
+                                        options: (_this_options11 = this.options) !== null && _this_options11 !== void 0 ? _this_options11 : {},
+                                        brainRunId: this.brainRunId
+                                    }
+                                ];
                             case 27:
                                 _state.sent();
+                                messages.push({
+                                    role: 'tool',
+                                    content: JSON.stringify(toolResult),
+                                    toolCallId: toolCall.toolCallId,
+                                    toolName: toolCall.toolName
+                                });
                                 _state.label = 28;
                             case 28:
+                                _iteratorNormalCompletion1 = true;
+                                return [
+                                    3,
+                                    18
+                                ];
+                            case 29:
+                                return [
+                                    3,
+                                    32
+                                ];
+                            case 30:
+                                err = _state.sent();
+                                _didIteratorError1 = true;
+                                _iteratorError1 = err;
+                                return [
+                                    3,
+                                    32
+                                ];
+                            case 31:
+                                try {
+                                    if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                                        _iterator1.return();
+                                    }
+                                } finally{
+                                    if (_didIteratorError1) {
+                                        throw _iteratorError1;
+                                    }
+                                }
+                                return [
+                                    7
+                                ];
+                            case 32:
+                                return [
+                                    3,
+                                    7
+                                ];
+                            case 33:
                                 return [
                                     2
                                 ];

package/dist/src/dsl/constants.js

@@ -8,7 +8,17 @@ export var BRAIN_EVENTS = {
     ERROR: 'brain:error',
     COMPLETE: 'brain:complete',
     CANCELLED: 'brain:cancelled',
-    WEBHOOK: 'brain:webhook'
+    WEBHOOK: 'brain:webhook',
+    WEBHOOK_RESPONSE: 'brain:webhook_response',
+    // Loop step events
+    LOOP_START: 'loop:start',
+    LOOP_ITERATION: 'loop:iteration',
+    LOOP_TOOL_CALL: 'loop:tool_call',
+    LOOP_TOOL_RESULT: 'loop:tool_result',
+    LOOP_ASSISTANT_MESSAGE: 'loop:assistant_message',
+    LOOP_COMPLETE: 'loop:complete',
+    LOOP_TOKEN_LIMIT: 'loop:token_limit',
+    LOOP_WEBHOOK: 'loop:webhook'
 };
 export var STATUS = {
     PENDING: 'pending',

package/dist/src/dsl/loop-messages.js

@@ -0,0 +1,75 @@
+import { BRAIN_EVENTS } from './constants.js';
+/**
+ * Reconstructs the loop context from stored events and a webhook response.
+ * Returns null if this is not a loop resume (no LOOP_WEBHOOK event found).
+ */ export function reconstructLoopContext(events, webhookResponse) {
+    // Find LOOP_WEBHOOK event - if not present, this is not a loop resume
+    var loopWebhookEvent = events.find(function(e) {
+        return e.type === BRAIN_EVENTS.LOOP_WEBHOOK;
+    });
+    if (!loopWebhookEvent) {
+        return null;
+    }
+    // Find LOOP_START to get the initial prompt and system
+    var loopStartEvent = events.find(function(e) {
+        return e.type === BRAIN_EVENTS.LOOP_START;
+    });
+    if (!loopStartEvent) {
+        throw new Error('LOOP_START event not found but LOOP_WEBHOOK exists - invalid event sequence');
+    }
+    var messages = [];
+    // Add initial user message from the prompt
+    messages.push({
+        role: 'user',
+        content: loopStartEvent.prompt
+    });
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        // Process events in order to rebuild conversation
+        for(var _iterator = events[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var event = _step.value;
+            if (event.type === BRAIN_EVENTS.LOOP_ASSISTANT_MESSAGE) {
+                var assistantEvent = event;
+                messages.push({
+                    role: 'assistant',
+                    content: assistantEvent.content
+                });
+            } else if (event.type === BRAIN_EVENTS.LOOP_TOOL_RESULT) {
+                var toolResultEvent = event;
+                messages.push({
+                    role: 'tool',
+                    content: JSON.stringify(toolResultEvent.result),
+                    toolCallId: toolResultEvent.toolCallId,
+                    toolName: toolResultEvent.toolName
+                });
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    // Add the webhook response as the pending tool's result
+    messages.push({
+        role: 'tool',
+        content: JSON.stringify(webhookResponse),
+        toolCallId: loopWebhookEvent.toolCallId,
+        toolName: loopWebhookEvent.toolName
+    });
+    return {
+        messages: messages,
+        pendingToolCallId: loopWebhookEvent.toolCallId,
+        pendingToolName: loopWebhookEvent.toolName,
+        prompt: loopStartEvent.prompt,
+        system: loopStartEvent.system
+    };
+}

package/dist/src/dsl/types.js

@@ -1 +1,4 @@
-export { };
+/**
+ * Helper type to extract the terminal tool's input type from a tools object.
+ * Used for typing the result that gets merged into state.
+ */ export { };

package/dist/src/index.js

@@ -10,3 +10,4 @@ export { z } from 'zod';
 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';

package/dist/types/clients/types.d.ts

@@ -6,6 +6,16 @@ export type Message = {
     role: 'user' | 'assistant' | 'system';
     content: string;
 };
+/**
+ * Represents a message in a tool-calling conversation.
+ * Extends Message to include tool messages.
+ */
+export type ToolMessage = {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolName?: string;
+};
 /**
  * Interface for AI model interactions, focused on generating structured objects
  * and potentially other types of content in the future.
@@ -46,5 +56,33 @@ export interface ObjectGenerator {
          */
         system?: string;
     }): Promise<z.infer<T>>;
+    /**
+     * Generates text with optional tool calling support.
+     * Used by loop steps for agentic workflows.
+     */
+    generateText?(params: {
+        /** System prompt for the LLM */
+        system?: string;
+        /** Conversation messages (including tool messages) */
+        messages: ToolMessage[];
+        /** Available tools for the LLM to call */
+        tools: Record<string, {
+            description: string;
+            inputSchema: z.ZodSchema;
+        }>;
+    }): Promise<{
+        /** Text response from the LLM */
+        text?: string;
+        /** Tool calls made by the LLM */
+        toolCalls?: Array<{
+            toolCallId: string;
+            toolName: string;
+            args: unknown;
+        }>;
+        /** Token usage information */
+        usage: {
+            totalTokens: number;
+        };
+    }>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/clients/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE;QAC/C;;;WAGG;QACH,MAAM,EAAE,CAAC,CAAC;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;QAErB;;;;WAIG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/clients/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE;QAC/C;;;WAGG;QACH,MAAM,EAAE,CAAC,CAAC;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;QAErB;;;;WAIG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,CAAC,MAAM,EAAE;QACpB,gCAAgC;QAChC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,QAAQ,EAAE,WAAW,EAAE,CAAC;QACxB,0CAA0C;QAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAA;SAAE,CAAC,CAAC;KAC1E,GAAG,OAAO,CAAC;QACV,iCAAiC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,iCAAiC;QACjC,SAAS,CAAC,EAAE,KAAK,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;YACnB,QAAQ,EAAE,MAAM,CAAC;YACjB,IAAI,EAAE,OAAO,CAAC;SACf,CAAC,CAAC;QACH,8BAA8B;QAC9B,KAAK,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC,CAAC,CAAC;CACJ"}

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

@@ -1,5 +1,5 @@
 import type { Adapter } from '../adapters/types.js';
-import { type SerializedStep, type Brain } from './brain.js';
+import { type SerializedStep, type Brain, type BrainEvent } from './brain.js';
 import type { State, JsonObject, RuntimeEnv } from './types.js';
 import type { ObjectGenerator } from '../clients/types.js';
 import type { Resources } from '../resources/resources.js';
@@ -18,7 +18,7 @@ export declare class BrainRunner {
     withResources(resources: Resources): BrainRunner;
     withPages(pages: PagesService): BrainRunner;
     withEnv(env: RuntimeEnv): BrainRunner;
-    run<TOptions extends JsonObject = {}, TState extends State = {}>(brain: Brain<TOptions, TState, any>, { initialState, options, initialCompletedSteps, brainRunId, endAfter, signal, response, }?: {
+    run<TOptions extends JsonObject = {}, TState extends State = {}>(brain: Brain<TOptions, TState, any>, { initialState, options, initialCompletedSteps, brainRunId, endAfter, signal, response, loopEvents, }?: {
         initialState?: TState;
         options?: TOptions;
         initialCompletedSteps?: SerializedStep[] | never;
@@ -26,6 +26,7 @@ export declare class BrainRunner {
         endAfter?: number;
         signal?: AbortSignal;
         response?: JsonObject;
+        loopEvents?: BrainEvent[];
     }): Promise<TState>;
 }
 //# sourceMappingURL=brain-runner.d.ts.map

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":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAe,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC1E,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,GACT,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;KAClB,GACL,OAAO,CAAC,MAAM,CAAC;CAmGnB"}
+{"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;CA0GnB"}

package/dist/types/dsl/brain.d.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import type { ObjectGenerator } from '../clients/types.js';
-import type { State, JsonPatch, JsonObject, RuntimeEnv } from './types.js';
+import type { State, JsonPatch, JsonObject, RuntimeEnv, LoopTool, LoopConfig } from './types.js';
 import { STATUS, BRAIN_EVENTS } from './constants.js';
 import type { Resources } from '../resources/resources.js';
 import type { ExtractWebhookResponses, SerializedWebhookRegistration } from './webhook.js';
 import type { PagesService } from './pages.js';
+import type { LoopResumeContext } from './loop-messages.js';
 export type SerializedError = {
     name: string;
     message: string;
@@ -86,7 +87,69 @@ export interface WebhookEvent<TOptions extends JsonObject = JsonObject> extends
     waitFor: SerializedWebhookRegistration[];
     state: State;
 }
-export type BrainEvent<TOptions extends JsonObject = JsonObject> = BrainStartEvent<TOptions> | BrainCompleteEvent<TOptions> | BrainErrorEvent<TOptions> | BrainCancelledEvent<TOptions> | StepStatusEvent<TOptions> | StepStartedEvent<TOptions> | StepCompletedEvent<TOptions> | StepRetryEvent<TOptions> | WebhookEvent<TOptions>;
+export interface LoopStartEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_START;
+    stepTitle: string;
+    stepId: string;
+    prompt: string;
+    system?: string;
+}
+export interface LoopIterationEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_ITERATION;
+    stepTitle: string;
+    stepId: string;
+    iteration: number;
+}
+export interface LoopToolCallEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_TOOL_CALL;
+    stepTitle: string;
+    stepId: string;
+    toolName: string;
+    toolCallId: string;
+    input: JsonObject;
+}
+export interface LoopToolResultEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_TOOL_RESULT;
+    stepTitle: string;
+    stepId: string;
+    toolName: string;
+    toolCallId: string;
+    result: unknown;
+}
+export interface LoopAssistantMessageEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_ASSISTANT_MESSAGE;
+    stepTitle: string;
+    stepId: string;
+    content: string;
+}
+export interface LoopCompleteEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_COMPLETE;
+    stepTitle: string;
+    stepId: string;
+    terminalToolName: string;
+    result: JsonObject;
+    totalIterations: number;
+}
+export interface LoopTokenLimitEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_TOKEN_LIMIT;
+    stepTitle: string;
+    stepId: string;
+    totalTokens: number;
+    maxTokens: number;
+}
+export interface LoopWebhookEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.LOOP_WEBHOOK;
+    stepTitle: string;
+    stepId: string;
+    toolCallId: string;
+    toolName: string;
+    input: JsonObject;
+}
+export interface WebhookResponseEvent<TOptions extends JsonObject = JsonObject> extends BaseEvent<TOptions> {
+    type: typeof BRAIN_EVENTS.WEBHOOK_RESPONSE;
+    response: JsonObject;
+}
+export type BrainEvent<TOptions extends JsonObject = JsonObject> = BrainStartEvent<TOptions> | BrainCompleteEvent<TOptions> | BrainErrorEvent<TOptions> | BrainCancelledEvent<TOptions> | StepStatusEvent<TOptions> | StepStartedEvent<TOptions> | StepCompletedEvent<TOptions> | StepRetryEvent<TOptions> | WebhookEvent<TOptions> | WebhookResponseEvent<TOptions> | LoopStartEvent<TOptions> | LoopIterationEvent<TOptions> | LoopToolCallEvent<TOptions> | LoopToolResultEvent<TOptions> | LoopAssistantMessageEvent<TOptions> | LoopCompleteEvent<TOptions> | LoopTokenLimitEvent<TOptions> | LoopWebhookEvent<TOptions>;
 export interface SerializedStep {
     title: string;
     status: (typeof STATUS)[keyof typeof STATUS];
@@ -98,7 +161,7 @@ export interface BrainStructure {
     title: string;
     description?: string;
     steps: Array<{
-        type: 'step' | 'brain';
+        type: 'step' | 'brain' | 'loop';
         title: string;
         innerBrain?: BrainStructure;
     }>;
@@ -126,6 +189,7 @@ export interface RerunParams<TOptions extends JsonObject = JsonObject> extends B
     initialCompletedSteps: SerializedStep[];
     brainRunId: string;
     response?: JsonObject;
+    loopResumeContext?: LoopResumeContext | null;
 }
 export declare class Brain<TOptions extends JsonObject = JsonObject, TState extends State = object, TServices extends object = object, TResponse extends JsonObject | undefined = undefined> {
     readonly title: string;
@@ -158,6 +222,20 @@ export declare class Brain<TOptions extends JsonObject = JsonObject, TState exte
         brainState: TInnerState;
         services: TServices;
     }) => TNewState, initialState?: State | ((state: TState) => State)): Brain<TOptions, TNewState, TServices, undefined>;
+    /**
+     * Add an agentic loop step that runs an LLM with tools.
+     * The loop continues until a terminal tool is called, no tool calls are returned,
+     * or maxTokens is exceeded.
+     */
+    loop<TTools extends Record<string, LoopTool> = Record<string, LoopTool>, TNewState extends State = TState>(title: string, configFn: (params: {
+        state: TState;
+        options: TOptions;
+        client: ObjectGenerator;
+        resources: Resources;
+        response: TResponse;
+        pages?: PagesService;
+        env: RuntimeEnv;
+    } & TServices) => LoopConfig<TTools> | Promise<LoopConfig<TTools>>): Brain<TOptions, TNewState, TServices, TResponse>;
     prompt<TResponseKey extends string & {
         readonly brand?: unique symbol;
     }, TSchema extends z.ZodObject<any>, TNewState extends State = TState & {

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

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

package/dist/types/dsl/constants.d.ts

@@ -9,6 +9,15 @@ export declare const BRAIN_EVENTS: {
     readonly COMPLETE: "brain:complete";
     readonly CANCELLED: "brain:cancelled";
     readonly WEBHOOK: "brain:webhook";
+    readonly WEBHOOK_RESPONSE: "brain:webhook_response";
+    readonly LOOP_START: "loop:start";
+    readonly LOOP_ITERATION: "loop:iteration";
+    readonly LOOP_TOOL_CALL: "loop:tool_call";
+    readonly LOOP_TOOL_RESULT: "loop:tool_result";
+    readonly LOOP_ASSISTANT_MESSAGE: "loop:assistant_message";
+    readonly LOOP_COMPLETE: "loop:complete";
+    readonly LOOP_TOKEN_LIMIT: "loop:token_limit";
+    readonly LOOP_WEBHOOK: "loop:webhook";
 };
 export declare const STATUS: {
     readonly PENDING: "pending";

package/dist/types/dsl/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;;;;;;CAWf,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;CAqBf,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC"}

package/dist/types/dsl/loop-messages.d.ts

@@ -0,0 +1,16 @@
+import type { BrainEvent } from './brain.js';
+import type { ToolMessage } from '../clients/types.js';
+import type { JsonObject } from './types.js';
+export interface LoopResumeContext {
+    messages: ToolMessage[];
+    pendingToolCallId: string;
+    pendingToolName: string;
+    prompt: string;
+    system?: string;
+}
+/**
+ * Reconstructs the loop context from stored events and a webhook response.
+ * Returns null if this is not a loop resume (no LOOP_WEBHOOK event found).
+ */
+export declare function reconstructLoopContext(events: BrainEvent[], webhookResponse: JsonObject): LoopResumeContext | null;
+//# sourceMappingURL=loop-messages.d.ts.map

package/dist/types/dsl/loop-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-messages.d.ts","sourceRoot":"","sources":["../../../src/dsl/loop-messages.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAKX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAAE,EACpB,eAAe,EAAE,UAAU,GAC1B,iBAAiB,GAAG,IAAI,CA0D1B"}

package/dist/types/dsl/types.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+import type { WebhookRegistration } from './webhook.js';
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonArray = JsonValue[];
 export type JsonObject = {
@@ -37,4 +39,65 @@ export type JsonPatch = {
     value?: JsonValue;
     from?: string;
 }[];
+/**
+ * Return type for tools that need to suspend execution and wait for an external event.
+ */
+export interface LoopToolWaitFor {
+    waitFor: WebhookRegistration<z.ZodSchema>;
+}
+/**
+ * A tool definition for use in loop steps.
+ * Compatible with Vercel AI SDK tool format, extended with Positronic-specific properties.
+ */
+export interface LoopTool<TInput extends z.ZodSchema = z.ZodSchema> {
+    /** Description of what this tool does, helps the LLM understand when to use it */
+    description: string;
+    /** Zod schema defining the input parameters for this tool */
+    inputSchema: TInput;
+    /**
+     * Execute function for the tool.
+     * Can return a result directly, or { waitFor: webhook(...) } to suspend execution.
+     * Not required for terminal tools.
+     */
+    execute?: (input: z.infer<TInput>) => Promise<unknown | LoopToolWaitFor> | unknown | LoopToolWaitFor;
+    /**
+     * If true, calling this tool ends the loop.
+     * The tool's input becomes the loop result (merged into state).
+     */
+    terminal?: boolean;
+}
+/**
+ * Configuration for a loop step.
+ */
+export interface LoopConfig<TTools extends Record<string, LoopTool> = Record<string, LoopTool>> {
+    /** System prompt for the LLM */
+    system?: string;
+    /** Initial user prompt to start the conversation */
+    prompt: string;
+    /** Tools available to the LLM */
+    tools: TTools;
+    /** Safety valve - exit if cumulative tokens exceed this limit */
+    maxTokens?: number;
+}
+/**
+ * Represents a single message in the loop conversation.
+ */
+export interface LoopMessage {
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    /** For tool messages, the ID of the tool call this is responding to */
+    toolCallId?: string;
+    /** For tool messages, the name of the tool */
+    toolName?: string;
+}
+/**
+ * Helper type to extract the terminal tool's input type from a tools object.
+ * Used for typing the result that gets merged into state.
+ */
+export type ExtractTerminalInput<TTools extends Record<string, LoopTool>> = {
+    [K in keyof TTools]: TTools[K] extends {
+        terminal: true;
+        inputSchema: infer S;
+    } ? S extends z.ZodSchema ? z.infer<S> : never : never;
+}[keyof TTools];
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/dsl/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AACpC,MAAM,MAAM,UAAU,GAAG;KAAG,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;CAEvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/dsl/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AACpC,MAAM,MAAM,UAAU,GAAG;KAAG,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;CAEvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,EAAE,CAAC;AAIJ;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS;IAChE,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KACnB,OAAO,CAAC,OAAO,GAAG,eAAe,CAAC,GAAG,OAAO,GAAG,eAAe,CAAC;IACpE;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CACzB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IAElE,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;KACzE,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC,CAAA;KAAE,GAC3E,CAAC,SAAS,CAAC,CAAC,SAAS,GACnB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GACV,KAAK,GACP,KAAK;CACV,CAAC,MAAM,MAAM,CAAC,CAAC"}

package/dist/types/index.d.ts

@@ -3,8 +3,8 @@ export { BrainRunner } from './dsl/brain-runner.js';
 export { STATUS, BRAIN_EVENTS } from './dsl/constants.js';
 export type { Adapter } from './adapters/types.js';
 export type { BrainEvent, SerializedStep, InitialRunParams, RerunParams, BrainStartEvent, BrainCompleteEvent, BrainErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent, StepRetryEvent, BrainStructure, BrainFactory, } from './dsl/brain.js';
-export type { ObjectGenerator, Message } from './clients/types.js';
-export type { State, RuntimeEnv, Secrets } from './dsl/types.js';
+export type { ObjectGenerator, Message, ToolMessage } from './clients/types.js';
+export type { State, RuntimeEnv, Secrets, LoopTool, LoopConfig, LoopMessage, LoopToolWaitFor, ExtractTerminalInput, } from './dsl/types.js';
 export { createPatch, applyPatches } from './dsl/json-patch.js';
 export { z } from 'zod';
 export type { ResourceLoader } from './resources/resource-loader.js';
@@ -14,4 +14,7 @@ export type { WebhookFunction, WebhookRegistration } from './dsl/webhook.js';
 export type { PagesService, Page, PageCreateOptions } from './dsl/pages.js';
 export type { Manifest as ResourceManifest, Entry as ResourceEntry, ResourceType, } from './resources/resources.js';
 export { RESOURCE_TYPES } from './resources/resources.js';
+export type { LoopStartEvent, LoopIterationEvent, LoopToolCallEvent, LoopToolResultEvent, LoopAssistantMessageEvent, LoopCompleteEvent, LoopTokenLimitEvent, LoopWebhookEvent, WebhookResponseEvent, } from './dsl/brain.js';
+export type { LoopResumeContext } from './dsl/loop-messages.js';
+export { reconstructLoopContext } from './dsl/loop-messages.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,MAAM,oBAAoB,CAAC;AACnE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACjE,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"}
+{"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,GACrB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/core",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "publishConfig": {
     "access": "public"
   },