@positronic/core 0.0.75 → 0.0.77

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

@@ -281,7 +281,7 @@ import { DEFAULT_ENV } from './brain.js';
  * Adds agent context to the deepest level.
  * Webhook response is no longer passed here - it comes from signals during execution.
  * This is internal to BrainRunner - external consumers don't need to know about ResumeContext.
- */ function executionStackToResumeContext(stack, agentContext, batchContext) {
+ */ function executionStackToResumeContext(stack, agentContext, iterateContext, currentPage) {
     if (stack.length === 0) {
         throw new Error('Cannot convert empty execution stack to ResumeContext');
     }
@@ -290,12 +290,13 @@ import { DEFAULT_ENV } from './brain.js';
     for(var i = stack.length - 1; i >= 0; i--){
         var entry = stack[i];
         if (i === stack.length - 1) {
-            // Deepest level - add agent context and batch progress (webhook response comes from signals now)
+            // Deepest level - add agent context, iterate progress, and page context
             context = {
                 stepIndex: entry.stepIndex,
                 state: entry.state,
                 agentContext: agentContext !== null && agentContext !== void 0 ? agentContext : undefined,
-                batchProgress: batchContext !== null && batchContext !== void 0 ? batchContext : undefined
+                iterateProgress: iterateContext !== null && iterateContext !== void 0 ? iterateContext : undefined,
+                currentPage: currentPage !== null && currentPage !== void 0 ? currentPage : undefined
             };
         } else {
             // Outer level - wrap inner context
@@ -427,13 +428,13 @@ export var BrainRunner = /*#__PURE__*/ function() {
    * Webhook response data comes from signals, not as a parameter.
    */ function resume(brain, options) {
                 return _async_to_generator(function() {
-                    var machine, brainRunId, brainOptions, endAfter, signal, currentUser, _machine_context, executionStack, agentContext, batchContext, resumeContext;
+                    var machine, brainRunId, brainOptions, endAfter, signal, currentUser, _machine_context, executionStack, agentContext, iterateContext, currentPage, resumeContext;
                     return _ts_generator(this, function(_state) {
                         machine = options.machine, brainRunId = options.brainRunId, brainOptions = options.options, endAfter = options.endAfter, signal = options.signal, currentUser = options.currentUser;
                         // Build ResumeContext from machine's execution stack
                         // Webhook response comes from signals during execution, not from resume parameters
-                        _machine_context = machine.context, executionStack = _machine_context.executionStack, agentContext = _machine_context.agentContext, batchContext = _machine_context.batchContext;
-                        resumeContext = executionStackToResumeContext(executionStack, agentContext, batchContext);
+                        _machine_context = machine.context, executionStack = _machine_context.executionStack, agentContext = _machine_context.agentContext, iterateContext = _machine_context.iterateContext, currentPage = _machine_context.currentPage;
+                        resumeContext = executionStackToResumeContext(executionStack, agentContext, iterateContext, currentPage);
                         return [
                             2,
                             this.execute(brain, {

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

@@ -101,6 +101,7 @@ import { applyPatches } from './json-patch.js';
             brainRunId: entry.brainRunId,
             brainTitle: entry.brainTitle,
             brainDescription: entry.brainDescription,
+            options: entry.options,
             parentStepId: entry.parentStepId,
             steps: entry.steps,
             innerBrain: innerBrain,
@@ -125,7 +126,8 @@ var createInitialContext = function(opts) {
         currentState: (_opts_initialState = opts === null || opts === void 0 ? void 0 : opts.initialState) !== null && _opts_initialState !== void 0 ? _opts_initialState : {},
         options: (_opts_options = opts === null || opts === void 0 ? void 0 : opts.options) !== null && _opts_options !== void 0 ? _opts_options : {},
         agentContext: null,
-        batchContext: null,
+        iterateContext: null,
+        currentPage: null,
         status: STATUS.PENDING,
         isTopLevel: false,
         isRunning: false,
@@ -190,7 +192,7 @@ var updateDerivedState = function(ctx, executionState) {
 // 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 brainRunId = param.brainRunId, brainTitle = param.brainTitle, brainDescription = param.brainDescription, options = param.options, initialState = param.initialState;
     var currentStepId = ctx.currentStepId, depth = ctx.depth, existingBrainRunId = ctx.brainRunId, currentState = ctx.currentState, brains = ctx.brains, brainIdStack = ctx.brainIdStack, executionStack = ctx.executionStack;
     var newDepth = depth + 1;
     var brainInitialState = initialState !== null && initialState !== void 0 ? initialState : currentState;
@@ -200,6 +202,7 @@ var startBrain = reduce(function(ctx, param) {
         brainRunId: brainRunId,
         brainTitle: brainTitle,
         brainDescription: brainDescription,
+        options: options,
         parentStepId: currentStepId,
         parentBrainId: parentBrainId,
         steps: [],
@@ -276,6 +279,19 @@ var errorBrain = reduce(function(ctx, param) {
     });
     return updateDerivedState(newCtx, 'error');
 });
+var completeInnerBrainError = reduce(function(ctx, param) {
+    var error = param.error;
+    var depth = ctx.depth, brainIdStack = ctx.brainIdStack, executionStack = ctx.executionStack;
+    if (brainIdStack.length === 0) return ctx;
+    var newCtx = _object_spread_props(_object_spread({}, ctx), {
+        brainIdStack: brainIdStack.slice(0, -1),
+        executionStack: executionStack.slice(0, -1),
+        depth: depth - 1,
+        error: error,
+        agentContext: null
+    });
+    return updateDerivedState(newCtx, 'running');
+});
 var cancelBrain = reduce(function(ctx) {
     return updateDerivedState(ctx, 'cancelled');
 });
@@ -319,7 +335,8 @@ var startStep = reduce(function(ctx, param) {
     });
 });
 var completeStep = reduce(function(ctx, param) {
-    var stepId = param.stepId, stepTitle = param.stepTitle, patch = param.patch, halted = param.halted;
+    var stepId = param.stepId, stepTitle = param.stepTitle, patch = param.patch, halted = param.halted, pageContext = param.pageContext;
+    var _ctx_iterateContext;
     var brains = ctx.brains, brainIdStack = ctx.brainIdStack, executionStack = ctx.executionStack, depth = ctx.depth, currentState = ctx.currentState, topLevelStepCount = ctx.topLevelStepCount;
     if (brainIdStack.length === 0) return ctx;
     // === NEW: Update flat structures ===
@@ -374,12 +391,19 @@ var completeStep = reduce(function(ctx, param) {
         ]);
         newStepCount = topLevelStepCount + 1;
     }
+    // Only clear iterateContext when the iterate step itself completes,
+    // not when inner brain steps complete during iteration
+    var newIterateContext = ((_ctx_iterateContext = ctx.iterateContext) === null || _ctx_iterateContext === void 0 ? void 0 : _ctx_iterateContext.stepId) === stepId ? null : ctx.iterateContext;
+    // Track page context: set when UI step completes (has pageContext),
+    // clear when the next step completes (page is ephemeral)
+    var newCurrentPage = pageContext !== null && pageContext !== void 0 ? pageContext : null;
     return _object_spread_props(_object_spread({}, ctx), {
         brains: newBrains,
         executionStack: newExecutionStack,
         currentState: newState1,
         topLevelStepCount: newStepCount,
-        batchContext: null
+        iterateContext: newIterateContext,
+        currentPage: newCurrentPage
     });
 });
 var webhookPause = reduce(function(ctx, param) {
@@ -442,15 +466,17 @@ var passthrough = function() {
         return ctx;
     });
 };
-// Reducer for BATCH_CHUNK_COMPLETE - merges chunk results into batchContext
-var batchChunkComplete = reduce(function(ctx, payload) {
-    var existing = ctx.batchContext;
+// Reducer for ITERATE_ITEM_COMPLETE - appends a single item result into iterateContext
+var iterateItemComplete = reduce(function(ctx, payload) {
+    var existing = ctx.iterateContext;
     var newResults = (existing === null || existing === void 0 ? void 0 : existing.accumulatedResults) ? _to_consumable_array(existing.accumulatedResults) : [];
-    for(var i = 0; i < payload.chunkResults.length; i++){
-        newResults[payload.chunkStartIndex + i] = payload.chunkResults[i];
-    }
+    newResults[payload.itemIndex] = payload.result != null ? [
+        payload.item,
+        payload.result
+    ] : undefined;
     return _object_spread_props(_object_spread({}, ctx), {
-        batchContext: {
+        iterateContext: {
+            stepId: payload.stepId,
             accumulatedResults: newResults,
             processedCount: payload.processedCount,
             totalItems: payload.totalItems,
@@ -559,13 +585,14 @@ var makeBrainMachine = function(initialContext) {
         transition(BRAIN_EVENTS.START, 'running', startBrain), // Outer brain complete -> terminal
         transition(BRAIN_EVENTS.COMPLETE, 'complete', isOuterBrain, completeBrain), // Inner brain complete -> stay running
         transition(BRAIN_EVENTS.COMPLETE, 'running', isInnerBrain, completeBrain), // Error (only outer brain errors are terminal)
-        transition(BRAIN_EVENTS.ERROR, 'error', isOuterBrain, errorBrain), // Cancelled
+        transition(BRAIN_EVENTS.ERROR, 'error', isOuterBrain, errorBrain), // Inner brain error -> stay running (pop the inner brain off the stack)
+        transition(BRAIN_EVENTS.ERROR, 'running', isInnerBrain, completeInnerBrainError), // Cancelled
         transition(BRAIN_EVENTS.CANCELLED, 'cancelled', cancelBrain), // Paused (by signal)
         transition(BRAIN_EVENTS.PAUSED, 'paused', pauseBrain), // Webhook -> waiting (for non-agent webhooks)
         transition(BRAIN_EVENTS.WEBHOOK, 'waiting', webhookPause), // Webhook response (for resume from non-agent webhook)
         transition(BRAIN_EVENTS.WEBHOOK_RESPONSE, 'running', webhookResponse), // Step events
-        transition(BRAIN_EVENTS.STEP_START, 'running', startStep), transition(BRAIN_EVENTS.STEP_COMPLETE, 'running', completeStep), transition(BRAIN_EVENTS.STEP_STATUS, 'running', stepStatus), // Batch chunk complete - stays in running, accumulates results
-        transition(BRAIN_EVENTS.BATCH_CHUNK_COMPLETE, 'running', batchChunkComplete), // AGENT_START transitions to the agentLoop state
+        transition(BRAIN_EVENTS.STEP_START, 'running', startStep), transition(BRAIN_EVENTS.STEP_COMPLETE, 'running', completeStep), transition(BRAIN_EVENTS.STEP_STATUS, 'running', stepStatus), // Iterate item complete - stays in running, accumulates results
+        transition(BRAIN_EVENTS.ITERATE_ITEM_COMPLETE, 'running', iterateItemComplete), // AGENT_START transitions to the agentLoop state
         transition(BRAIN_EVENTS.AGENT_START, 'agentLoop', agentStart)),
         // Explicit agent loop state - isolates agent execution logic
         agentLoop: state.apply(void 0, // Spread agent micro-transitions
@@ -579,6 +606,8 @@ var makeBrainMachine = function(initialContext) {
             transition(BRAIN_EVENTS.WEBHOOK, 'waiting', webhookPause),
             // Error handling
             transition(BRAIN_EVENTS.ERROR, 'error', isOuterBrain, errorBrain),
+            // Inner brain error -> back to running (pop inner brain, clear agentContext)
+            transition(BRAIN_EVENTS.ERROR, 'running', isInnerBrain, completeInnerBrainError),
             transition(BRAIN_EVENTS.CANCELLED, 'cancelled', cancelBrain)
         ])),
         paused: state(transition(BRAIN_EVENTS.CANCELLED, 'cancelled', cancelBrain), // RESUMED transitions out of paused state without creating a new brain

package/dist/src/dsl/builder/brain.js

@@ -388,6 +388,7 @@ export var Brain = /*#__PURE__*/ function() {
         _define_property(this, "optionsSchema", void 0);
         _define_property(this, "components", void 0);
         _define_property(this, "defaultTools", void 0);
+        _define_property(this, "extraTools", void 0);
         _define_property(this, "memoryProvider", void 0);
         _define_property(this, "storeSchema", void 0);
         this.title = title;
@@ -447,6 +448,7 @@ export var Brain = /*#__PURE__*/ function() {
                 nextBrain.optionsSchema = this.optionsSchema;
                 nextBrain.components = this.components;
                 nextBrain.defaultTools = this.defaultTools;
+                nextBrain.extraTools = this.extraTools;
                 nextBrain.memoryProvider = this.memoryProvider;
                 nextBrain.storeSchema = this.storeSchema;
                 return nextBrain;
@@ -460,6 +462,7 @@ export var Brain = /*#__PURE__*/ function() {
                 nextBrain.services = this.services;
                 nextBrain.components = this.components;
                 nextBrain.defaultTools = this.defaultTools;
+                nextBrain.extraTools = this.extraTools;
                 nextBrain.memoryProvider = this.memoryProvider;
                 nextBrain.storeSchema = this.storeSchema;
                 return nextBrain;
@@ -486,6 +489,7 @@ export var Brain = /*#__PURE__*/ function() {
                 nextBrain.services = this.services;
                 nextBrain.components = components;
                 nextBrain.defaultTools = this.defaultTools;
+                nextBrain.extraTools = this.extraTools;
                 nextBrain.memoryProvider = this.memoryProvider;
                 nextBrain.storeSchema = this.storeSchema;
                 return nextBrain;
@@ -520,6 +524,31 @@ export var Brain = /*#__PURE__*/ function() {
         },
         {
             /**
+   * Add extra tools on top of whatever default tools are already configured.
+   * Unlike `withTools()` which replaces defaults, this merges additively.
+   *
+   * @param tools - Record of additional tool definitions
+   *
+   * @example
+   * ```typescript
+   * const myBrain = createBrain({ defaultTools })
+   *   ('my-brain')
+   *   .withExtraTools({ myCustomTool })
+   *   .brain('agent', ({ tools }) => ({
+   *     system: 'You are helpful',
+   *     prompt: 'Do something',
+   *     tools  // includes both defaults and myCustomTool
+   *   }));
+   * ```
+   */ key: "withExtraTools",
+            value: function withExtraTools(tools) {
+                var next = this.nextBrain();
+                next.extraTools = tools;
+                return next;
+            }
+        },
+        {
+            /**
    * Configure a memory provider for this brain.
    * When configured, steps receive a scoped memory instance in their context.
    *
@@ -573,6 +602,7 @@ export var Brain = /*#__PURE__*/ function() {
                 nextBrain.services = this.services;
                 nextBrain.components = this.components;
                 nextBrain.defaultTools = this.defaultTools;
+                nextBrain.extraTools = this.extraTools;
                 nextBrain.memoryProvider = this.memoryProvider;
                 nextBrain.storeSchema = storeSchema;
                 return nextBrain;
@@ -619,10 +649,32 @@ export var Brain = /*#__PURE__*/ function() {
         {
             // Implementation
             key: "brain",
-            value: function brain(title, innerBrainOrConfig, action, initialState) {
+            value: function brain(title, innerBrainOrConfig, actionOrIterateConfig, initialState) {
+                // Detect iterate config: 3rd arg is an object with `over` property
+                var isIterateConfig = actionOrIterateConfig && (typeof actionOrIterateConfig === "undefined" ? "undefined" : _type_of(actionOrIterateConfig)) === 'object' && 'over' in actionOrIterateConfig;
                 // Case 1: Nested brain instance
                 if (innerBrainOrConfig && (typeof innerBrainOrConfig === "undefined" ? "undefined" : _type_of(innerBrainOrConfig)) === 'object' && 'type' in innerBrainOrConfig && innerBrainOrConfig.type === 'brain') {
-                    var nestedBlock = {
+                    if (isIterateConfig) {
+                        // Case 1b: Nested brain with iterate
+                        var iterateConfig = actionOrIterateConfig;
+                        var nestedBlock = {
+                            type: 'brain',
+                            title: title,
+                            innerBrain: innerBrainOrConfig,
+                            initialState: function() {
+                                return {};
+                            },
+                            action: function() {
+                                return {};
+                            },
+                            iterateConfig: iterateConfig
+                        };
+                        this.blocks.push(nestedBlock);
+                        return this.nextBrain();
+                    }
+                    // Case 1a: Single nested brain (existing behavior)
+                    var action = actionOrIterateConfig;
+                    var nestedBlock1 = {
                         type: 'brain',
                         title: title,
                         innerBrain: innerBrainOrConfig,
@@ -637,26 +689,39 @@ export var Brain = /*#__PURE__*/ function() {
                             });
                         }
                     };
-                    this.blocks.push(nestedBlock);
+                    this.blocks.push(nestedBlock1);
                     return this.nextBrain();
                 }
                 // Case 2 & 3: Agent config (object or function)
-                var configFn = typeof innerBrainOrConfig === 'function' ? innerBrainOrConfig : function() {
+                if (isIterateConfig) {
+                    // Agent config with iterate — configFn receives (item, params)
+                    var iterateConfig1 = actionOrIterateConfig;
+                    var configFn = innerBrainOrConfig;
+                    var agentBlock = {
+                        type: 'agent',
+                        title: title,
+                        configFn: configFn,
+                        iterateConfig: iterateConfig1
+                    };
+                    this.blocks.push(agentBlock);
+                    return this.nextBrain();
+                }
+                var configFn1 = typeof innerBrainOrConfig === 'function' ? innerBrainOrConfig : function() {
                     return innerBrainOrConfig;
                 };
-                var agentBlock = {
+                var agentBlock1 = {
                     type: 'agent',
                     title: title,
-                    configFn: configFn
+                    configFn: configFn1
                 };
-                this.blocks.push(agentBlock);
+                this.blocks.push(agentBlock1);
                 return this.nextBrain();
             }
         },
         {
             // Implementation
             key: "prompt",
-            value: function prompt(title, config, batchConfig) {
+            value: function prompt(title, config, iterateConfig) {
                 // Schema-less prompt - returns text response for next step
                 if (!config.outputSchema) {
                     var textSchema = z.object({
@@ -667,7 +732,7 @@ export var Brain = /*#__PURE__*/ function() {
                         title: title,
                         client: config.client,
                         action: function(param) {
-                            var state = param.state, client = param.client, resources = param.resources;
+                            var state = param.state, options = param.options, client = param.client, resources = param.resources;
                             return _async_to_generator(function() {
                                 var prompt, result;
                                 return _ts_generator(this, function(_state) {
@@ -675,7 +740,11 @@ export var Brain = /*#__PURE__*/ function() {
                                         case 0:
                                             return [
                                                 4,
-                                                config.template(state, resources)
+                                                config.template({
+                                                    state: state,
+                                                    options: options,
+                                                    resources: resources
+                                                })
                                             ];
                                         case 1:
                                             prompt = _state.sent();
@@ -706,8 +775,8 @@ export var Brain = /*#__PURE__*/ function() {
                 }
                 // At this point, outputSchema is guaranteed to exist (schema-less case returned early)
                 var outputSchema = config.outputSchema;
-                if (batchConfig) {
-                    // Batch mode - store config on block for event-stream to execute with per-item events
+                if (iterateConfig) {
+                    // Iterate mode - store config on block for event-stream to execute with per-item events
                     var promptBlock1 = {
                         type: 'step',
                         title: title,
@@ -722,14 +791,13 @@ export var Brain = /*#__PURE__*/ function() {
                                 });
                             })();
                         },
-                        batchConfig: {
-                            over: batchConfig.over,
-                            error: batchConfig.error,
+                        iterateConfig: {
+                            over: iterateConfig.over,
+                            error: iterateConfig.error,
                             template: config.template,
                             schema: outputSchema.schema,
                             schemaName: outputSchema.name,
-                            client: config.client,
-                            concurrency: batchConfig.concurrency
+                            client: config.client
                         }
                     };
                     this.blocks.push(promptBlock1);
@@ -741,7 +809,7 @@ export var Brain = /*#__PURE__*/ function() {
                         title: title,
                         client: config.client,
                         action: function(param) {
-                            var state = param.state, client = param.client, resources = param.resources;
+                            var state = param.state, options = param.options, client = param.client, resources = param.resources;
                             return _async_to_generator(function() {
                                 var schema, schemaName, prompt, result;
                                 return _ts_generator(this, function(_state) {
@@ -750,7 +818,11 @@ export var Brain = /*#__PURE__*/ function() {
                                             schema = outputSchema.schema, schemaName = outputSchema.name;
                                             return [
                                                 4,
-                                                config.template(state, resources)
+                                                config.template({
+                                                    state: state,
+                                                    options: options,
+                                                    resources: resources
+                                                })
                                             ];
                                         case 1:
                                             prompt = _state.sent();
@@ -801,7 +873,7 @@ export var Brain = /*#__PURE__*/ function() {
    * brain('feedback-form')
    *   .step('Initialize', () => ({ userName: 'John' }))
    *   .ui('Create Form', {
-   *     template: (state) => `Create a feedback form for ${state.userName}`,
+   *     template: ({ state }) => `Create a feedback form for ${state.userName}`,
    *     responseSchema: z.object({
    *       rating: z.number().min(1).max(5),
    *       comments: z.string(),
@@ -849,21 +921,11 @@ export var Brain = /*#__PURE__*/ function() {
             value: // Implementation signature
             function run(params) {
                 return _wrap_async_generator(function() {
-                    var _this, title, description, blocks, validatedOptions, store, stream;
+                    var _this, title, description, blocks, store, stream;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 _this = this, title = _this.title, description = _this.description, blocks = _this.blocks;
-                                if (this.optionsSchema) {
-                                    // Just call parse - Zod handles defaults automatically
-                                    validatedOptions = this.optionsSchema.parse(params.options || {});
-                                } else {
-                                    // If no schema is defined but options are provided, throw error
-                                    if (params.options && Object.keys(params.options).length > 0) {
-                                        throw new Error("Brain '".concat(this.title, "' received options but no schema was defined. Use withOptionsSchema() to define a schema for options."));
-                                    }
-                                    validatedOptions = {};
-                                }
                                 // Build store if withStore() was called and a store provider is given
                                 store = this.storeSchema && params.storeProvider ? params.storeProvider({
                                     schema: this.storeSchema,
@@ -875,10 +937,12 @@ export var Brain = /*#__PURE__*/ function() {
                                     description: description,
                                     blocks: blocks
                                 }, params), {
-                                    options: validatedOptions,
+                                    options: params.options || {},
+                                    optionsSchema: this.optionsSchema,
                                     services: this.services,
                                     components: this.components,
                                     defaultTools: this.defaultTools,
+                                    extraTools: this.extraTools,
                                     memoryProvider: this.memoryProvider,
                                     store: store
                                 }));
@@ -916,6 +980,8 @@ export var Brain = /*#__PURE__*/ function() {
                 nextBrain.components = this.components;
                 // Copy defaultTools to the next brain
                 nextBrain.defaultTools = this.defaultTools;
+                // Copy extraTools to the next brain
+                nextBrain.extraTools = this.extraTools;
                 // Copy memoryProvider to the next brain
                 nextBrain.memoryProvider = this.memoryProvider;
                 // Copy store schema to the next brain

package/dist/src/dsl/constants.js

@@ -25,8 +25,8 @@ export var BRAIN_EVENTS = {
     AGENT_WEBHOOK: 'agent:webhook',
     AGENT_RAW_RESPONSE_MESSAGE: 'agent:raw_response_message',
     AGENT_USER_MESSAGE: 'agent:user_message',
-    // Batch prompt events (prompt with `over`)
-    BATCH_CHUNK_COMPLETE: 'batch:chunk_complete'
+    // Iterate events (prompt/brain with `over`)
+    ITERATE_ITEM_COMPLETE: 'iterate:item_complete'
 };
 export var STATUS = {
     PENDING: 'pending',