@positronic/core 0.0.56 → 0.0.57

package/dist/src/dsl/signal-validation.js

@@ -0,0 +1,157 @@
+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 _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _iterable_to_array_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 _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 _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+import { BRAIN_EVENTS, STATUS } from './constants.js';
+/**
+ * Map signal types to the events they would emit.
+ * These events must have valid transitions from the current state.
+ */ var signalToEvent = {
+    'KILL': BRAIN_EVENTS.CANCELLED,
+    'PAUSE': BRAIN_EVENTS.PAUSED,
+    'RESUME': BRAIN_EVENTS.RESUMED,
+    'USER_MESSAGE': BRAIN_EVENTS.AGENT_USER_MESSAGE,
+    'WEBHOOK_RESPONSE': BRAIN_EVENTS.WEBHOOK_RESPONSE
+};
+var _obj;
+/**
+ * Map brain status (from MonitorDO) to state machine state names.
+ * The state machine uses different internal names than the public status values.
+ */ var statusToState = (_obj = {}, _define_property(_obj, STATUS.PENDING, 'idle'), _define_property(_obj, STATUS.RUNNING, 'running'), _define_property(_obj, STATUS.PAUSED, 'paused'), _define_property(_obj, STATUS.WAITING, 'waiting'), _define_property(_obj, STATUS.COMPLETE, 'complete'), _define_property(_obj, STATUS.ERROR, 'error'), _define_property(_obj, STATUS.CANCELLED, 'cancelled'), _obj);
+/**
+ * Check if a signal is valid for the current brain state.
+ * Uses the state machine definition as the source of truth.
+ *
+ * @param machineDefinition - The state machine definition with states and transitions
+ * @param brainStatus - The current brain status (e.g., 'running', 'paused', 'complete')
+ * @param signalType - The signal type to validate (e.g., 'PAUSE', 'KILL', 'RESUME')
+ * @returns Validation result with valid flag and optional reason for rejection
+ */ export function isSignalValid(machineDefinition, brainStatus, signalType) {
+    var eventName = signalToEvent[signalType];
+    if (!eventName) {
+        return {
+            valid: false,
+            reason: "Unknown signal type: ".concat(signalType)
+        };
+    }
+    var stateName = statusToState[brainStatus];
+    if (!stateName) {
+        return {
+            valid: false,
+            reason: "Unknown brain status: ".concat(brainStatus)
+        };
+    }
+    var stateObj = machineDefinition.states[stateName];
+    if (!stateObj) {
+        return {
+            valid: false,
+            reason: "State '".concat(stateName, "' not found in machine")
+        };
+    }
+    var hasTransition = stateObj.transitions.has(eventName);
+    if (!hasTransition) {
+        return {
+            valid: false,
+            reason: "Cannot ".concat(signalType, " brain in '").concat(brainStatus, "' state")
+        };
+    }
+    return {
+        valid: true
+    };
+}
+/**
+ * Get the list of valid signals for a given brain status.
+ * Useful for debugging and for providing user feedback.
+ *
+ * @param machineDefinition - The state machine definition with states and transitions
+ * @param brainStatus - The current brain status
+ * @returns Array of valid signal types
+ */ export function getValidSignals(machineDefinition, brainStatus) {
+    var stateName = statusToState[brainStatus];
+    if (!stateName) {
+        return [];
+    }
+    var stateObj = machineDefinition.states[stateName];
+    if (!stateObj) {
+        return [];
+    }
+    var validSignals = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = Object.entries(signalToEvent)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array(_step.value, 2), signalType = _step_value[0], eventName = _step_value[1];
+            if (stateObj.transitions.has(eventName)) {
+                validSignals.push(signalType);
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return validSignals;
+}

package/dist/src/dsl/types.js

@@ -1,4 +1,4 @@
 /**
- * Configuration for retry behavior with exponential backoff.
- * Used by batch prompt execution.
+ * Interface for providing signals to a running brain.
+ * Implementations are backend-specific (in-memory, database, KV store, etc.)
  */ export { };

package/dist/src/index.js

@@ -12,6 +12,9 @@ export { createResources } from './resources/resources.js';
 export { createWebhook } from './dsl/webhook.js';
 export { RESOURCE_TYPES } from './resources/resources.js';
 // Default tools
-export { createTool, defaultTools, generateUI, consoleLog, done } from './tools/index.js';
+export { createTool, defaultTools, defaultDoneSchema, generateUI, waitForWebhook, print, consoleLog } from './tools/index.js';
+export { createScopedMemory } from './memory/scoped-memory.js';
 // Brain state machine
-export { createBrainExecutionMachine, createBrainMachine, sendEvent, getDepth, isTopLevel, getCurrentStep, getBrainStack, getBrainRunId, getExecutionState, getPendingWebhooks, getError, getCompletedSteps } from './dsl/brain-state-machine.js';
+export { createBrainExecutionMachine, createBrainMachine, sendEvent, reconstructBrainTree, brainMachineDefinition } from './dsl/brain-state-machine.js';
+// Signal validation
+export { isSignalValid, getValidSignals } from './dsl/signal-validation.js';

package/dist/src/memory/scoped-memory.js

@@ -0,0 +1,176 @@
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() {
+        return this;
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Creates a scoped memory instance with the agentId pre-bound.
+ *
+ * This wraps a MemoryProvider and automatically includes the agentId
+ * in all calls, so brain steps don't need to pass it explicitly.
+ *
+ * @param provider - The underlying memory provider
+ * @param agentId - The agent/brain ID to scope memories to
+ * @returns A ScopedMemory instance
+ *
+ * @example
+ * ```typescript
+ * const provider = createMem0Provider({ apiKey: '...' });
+ * const scopedMemory = createScopedMemory(provider, 'my-brain');
+ *
+ * // Now search without passing agentId
+ * const memories = await scopedMemory.search('user preferences');
+ * ```
+ */ export function createScopedMemory(provider, agentId) {
+    return {
+        search: function search(query, options) {
+            return _async_to_generator(function() {
+                var scope;
+                return _ts_generator(this, function(_state) {
+                    scope = {
+                        agentId: agentId,
+                        userId: options === null || options === void 0 ? void 0 : options.userId
+                    };
+                    return [
+                        2,
+                        provider.search(query, scope, {
+                            limit: options === null || options === void 0 ? void 0 : options.limit
+                        })
+                    ];
+                });
+            })();
+        },
+        add: function add(messages, options) {
+            return _async_to_generator(function() {
+                var scope;
+                return _ts_generator(this, function(_state) {
+                    scope = {
+                        agentId: agentId,
+                        userId: options === null || options === void 0 ? void 0 : options.userId
+                    };
+                    return [
+                        2,
+                        provider.add(messages, scope, {
+                            metadata: options === null || options === void 0 ? void 0 : options.metadata
+                        })
+                    ];
+                });
+            })();
+        }
+    };
+}

package/dist/src/memory/types.js

@@ -0,0 +1,12 @@
+/**
+ * Memory types for the Positronic memory system.
+ *
+ * The memory system provides a provider-agnostic interface for storing and
+ * retrieving long-term memories. Memory providers implement the raw interface,
+ * and brain steps receive a scoped memory instance with the agent ID pre-bound.
+ */ /**
+ * A single memory entry returned from search operations.
+ */ /**
+ * Scoped memory interface with agentId pre-bound.
+ * This is what brain steps receive - they don't need to pass agentId.
+ */ export { };

package/dist/src/tools/index.js

@@ -145,30 +145,37 @@ import { generatePageHtml } from '../ui/generate-page-html.js';
     return config;
 }
 var generateUIInputSchema = z.object({
-    prompt: z.string().describe('Instructions for what UI to generate. Describe the form fields, layout, and purpose. ' + 'Be specific about what data you want to collect from the user.')
+    prompt: z.string().describe('Natural language instructions describing the UI to generate. ' + 'Include: (1) the purpose of the page, (2) what information to display from the data parameter, ' + '(3) what input fields are needed if collecting data, (4) labels and placeholders for fields, ' + '(5) any specific layout preferences. Example: "Create a form to collect user feedback with ' + 'fields for rating (1-5 scale), comments (text area), and email. Show the product name at the top."'),
+    hasForm: z.boolean().optional().describe('Whether to include a form that can be submitted. Defaults to true. ' + 'Set to true when: collecting user input, approval workflows, any interactive data entry. ' + 'Set to false when: displaying read-only information, confirmation pages, dashboards. ' + 'When true, the tool returns webhook info that must be used with waitForWebhook to receive the submission.'),
+    persist: z.boolean().optional().describe('Whether to keep the page after the brain run completes. Defaults to false. ' + 'Set to false (default): Page is automatically cleaned up when the brain run finishes. Use for one-time forms, approvals, or temporary displays. ' + 'Set to true: Page survives brain completion and remains accessible. Use for shared dashboards, permanent reference pages, or pages that need to outlive the workflow.'),
+    data: z.record(z.unknown()).optional().describe('Structured data for template bindings ({{path.to.value}} syntax). ' + 'Pass the objects/arrays you want to display. The UI generator infers the shape ' + 'and creates bindings to render all items. Example: { articles: [...], user: { name: "..." } }')
 });
 /**
- * Generate UI tool - creates an interactive UI page and waits for user response.
+ * Generate UI tool - creates an interactive UI page.
  *
  * This tool:
  * 1. Uses an LLM to generate a UI page based on your prompt
  * 2. Creates an HTML page with the generated components
- * 3. Pauses agent execution until the user submits the form
- * 4. Returns the form data as the tool result when resumed
+ * 3. Returns the page URL and webhook info (if hasForm is true)
+ *
+ * IMPORTANT: This tool does NOT pause execution. After generating a page with a form,
+ * you must call waitForWebhook to pause and wait for the form submission.
+ * Before calling waitForWebhook, ensure the user knows the page URL.
  *
  * Requires components and pages to be configured via createBrain or withComponents().
  *
  * The description is enriched at runtime with available component information.
  */ export var generateUI = {
-    description: 'Generate a UI page to display to the user and wait for their response. ' + 'Available components will be listed in the system prompt. ' + 'After the page is created, execution pauses until the user submits the form.',
+    description: "Generate a web page for displaying rich content or collecting user input.\n\nSometimes you need more than simple notifications to communicate with users. This tool creates web pages that can display formatted content, dashboards, or forms to collect information.\n\nPass structured data via the 'data' parameter to populate the page with dynamic content. The UI generator uses {{path.to.value}} template bindings to render your data.\n\nRETURNS: { url: string, webhook: { slug: string, identifier: string } | null }\n- url: The page URL\n- webhook: For forms (hasForm=true), contains slug and identifier that can be passed to waitForWebhook to pause execution until the user submits the form\n\nIMPORTANT: Users have no way to discover the page URL on their own. After generating a page, you must tell them the URL using whatever communication tools are available.",
     inputSchema: generateUIInputSchema,
     execute: function execute(input, context) {
         return _async_to_generator(function() {
-            var components, pages, client, state, env, brainRunId, stepId, uiResult, placementCount, webhookIdentifier, formAction, html, page, webhook;
+            var components, pages, client, state, env, brainRunId, stepId, _input_hasForm, hasForm, _input_data, uiResult, placementCount, webhookInfo, formAction, webhookIdentifier, _input_data1, html, page;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
                         components = context.components, pages = context.pages, client = context.client, state = context.state, env = context.env, brainRunId = context.brainRunId, stepId = context.stepId;
+                        hasForm = (_input_hasForm = input.hasForm) !== null && _input_hasForm !== void 0 ? _input_hasForm : true;
                         if (!components || Object.keys(components).length === 0) {
                             throw new Error('generateUI requires components to be configured. ' + 'Use createBrain({ components }) or brain.withComponents() to register UI components.');
                         }
@@ -181,7 +188,7 @@ var generateUIInputSchema = z.object({
                                 client: client,
                                 prompt: input.prompt,
                                 components: components,
-                                data: state
+                                data: (_input_data = input.data) !== null && _input_data !== void 0 ? _input_data : {}
                             })
                         ];
                     case 1:
@@ -194,36 +201,38 @@ var generateUIInputSchema = z.object({
                                 throw new Error("UI generation failed - no root component found. " + "".concat(placementCount, " component(s) were placed but all have a parentId."));
                             }
                         }
-                        // Create unique identifier for the webhook
-                        webhookIdentifier = "".concat(brainRunId, "-").concat(stepId, "-generateui-").concat(Date.now());
-                        // Build form action URL
-                        formAction = "".concat(env.origin, "/webhooks/system/ui-form?identifier=").concat(encodeURIComponent(webhookIdentifier));
+                        // Create webhook info only if hasForm is true
+                        webhookInfo = null;
+                        if (hasForm) {
+                            webhookIdentifier = "".concat(brainRunId, "-").concat(stepId, "-generateui-").concat(Date.now());
+                            formAction = "".concat(env.origin, "/webhooks/system/ui-form?identifier=").concat(encodeURIComponent(webhookIdentifier));
+                            webhookInfo = {
+                                slug: 'ui-form',
+                                identifier: webhookIdentifier
+                            };
+                        }
                         // Generate HTML page
                         html = generatePageHtml({
                             placements: uiResult.placements,
                             rootId: uiResult.rootId,
-                            data: state,
-                            title: 'Generated Form',
+                            data: (_input_data1 = input.data) !== null && _input_data1 !== void 0 ? _input_data1 : {},
+                            title: hasForm ? 'Generated Form' : 'Generated Page',
                             formAction: formAction
                         });
                         return [
                             4,
-                            pages.create(html)
+                            pages.create(html, {
+                                persist: input.persist
+                            })
                         ];
                     case 2:
                         page = _state.sent();
-                        // Create webhook registration for form submission
-                        webhook = {
-                            slug: 'ui-form',
-                            identifier: webhookIdentifier,
-                            schema: z.record(z.unknown())
-                        };
-                        // Return URL and waitFor - the URL is included so it can be logged/emitted
+                        // Return URL and webhook info (no waitFor - does not pause)
                         return [
                             2,
                             {
                                 url: page.url,
-                                waitFor: webhook
+                                webhook: webhookInfo
                             }
                         ];
                 }
@@ -231,36 +240,75 @@ var generateUIInputSchema = z.object({
         })();
     }
 };
+var waitForWebhookInputSchema = z.object({
+    slug: z.string().describe('The webhook slug that identifies the type of webhook. ' + 'For generateUI forms, this is always "ui-form". ' + 'Use the exact slug value returned by the tool that created the webhook.'),
+    identifier: z.string().describe('The unique identifier for this specific webhook instance. ' + 'This is returned by generateUI in webhook.identifier. ' + 'Each generateUI call creates a unique identifier - use the one from the specific page you want to wait for.')
+});
+/**
+ * Wait for webhook tool - pauses execution until a webhook receives a response.
+ *
+ * Use this after generating a UI page with a form to wait for the user's submission.
+ * The form data will be returned as the tool result when the webhook fires.
+ *
+ * IMPORTANT: Before calling this tool, ensure the user knows the page URL
+ * so they can access and submit the form.
+ */ export var waitForWebhook = {
+    description: 'Pause agent execution and wait for an external event (webhook response).\n\nPURPOSE: Suspend the agent until a user action occurs, such as submitting a form generated by generateUI.\n\n⚠️ CRITICAL - BEFORE CALLING THIS TOOL:\nYou MUST have already communicated the page URL to the user in your response. The user has no other way to discover the URL. If you call this tool without first telling the user where to go, the job will freeze indefinitely with no easy recovery.\n\nCORRECT SEQUENCE:\n1. Call generateUI to create the page\n2. In your response text, tell the user the URL (e.g., "Please complete the form at: {url}")\n3. THEN call waitForWebhook\n\nBEHAVIOR:\n- Calling this tool immediately pauses execution\n- The agent will NOT continue until the webhook receives data\n- This pause is indefinite - there is no timeout\n- When the webhook fires, execution resumes with the webhook payload as this tool\'s result\n- The form data will be available as key-value pairs (e.g., { name: "John", email: "john@example.com" })\n\nWHEN TO USE:\n- After generateUI with hasForm=true, to wait for form submission\n- Any workflow requiring human input or approval before continuing\n\nFAILURE MODE: If the user doesn\'t know the URL, they cannot submit the form, and the agent waits forever. The only recovery is to kill the job or manually inspect the event stream for the URL.\n\nRETURNS: The webhook payload when triggered. For UI forms, this contains all form field values as an object.',
+    inputSchema: waitForWebhookInputSchema,
+    execute: function execute(input) {
+        var webhook = {
+            slug: input.slug,
+            identifier: input.identifier,
+            schema: z.record(z.unknown())
+        };
+        return {
+            waitFor: webhook
+        };
+    }
+};
 /**
- * Console log tool - useful for debugging and logging information during agent execution.
+ * Print tool - the simplest way for agents to communicate with users.
+ * Like PRINT in BASIC - outputs a message that users can see.
+ */ export var print = createTool({
+    description: "Display a message to the user. This is the simplest way to communicate with users.\n\nUse this tool whenever you need to tell the user something - status updates, instructions, results, or any information they should see. The message will be displayed to users watching this workflow.",
+    inputSchema: z.object({
+        message: z.string().describe('The message to display to the user')
+    }),
+    execute: function(param) {
+        var message = param.message;
+        console.log("[Print] ".concat(message));
+        return {
+            printed: true
+        };
+    }
+});
+/**
+ * Console log tool - for internal server-side debugging and logging.
+ * NOT for user communication - use print for that.
  */ export var consoleLog = createTool({
-    description: 'Log a message to the console for debugging or informational purposes',
+    description: "Write a debug log message to the server console. For internal debugging only - users do not see these messages. Use 'print' to communicate with users.",
     inputSchema: z.object({
-        message: z.string().describe('The message to log'),
+        message: z.string().describe('The debug message to log'),
         level: z.enum([
             'info',
             'warn',
             'error'
-        ]).optional().describe('Log level (defaults to info)')
+        ]).optional().describe('Log level: info (default), warn, or error')
     }),
     execute: function(param) {
         var message = param.message, _param_level = param.level, level = _param_level === void 0 ? 'info' : _param_level;
         var logFn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
-        logFn("[Agent] ".concat(message));
+        logFn("[Debug] ".concat(message));
         return {
             logged: true
         };
     }
 });
 /**
- * Done tool - a simple terminal tool for completing agent execution.
- * The result becomes part of the brain state.
- */ export var done = createTool({
-    description: 'Complete the task and return a result',
-    inputSchema: z.object({
-        result: z.string().describe('The final result or summary of the completed task')
-    }),
-    terminal: true
+ * Default schema for the auto-generated 'done' tool when no outputSchema is provided.
+ * Used internally by the framework.
+ */ export var defaultDoneSchema = z.object({
+    result: z.string().describe('A clear summary of what was accomplished. ' + 'Include: key outcomes, any important values or findings, and confirmation that the task is complete. ' + 'Be specific but concise. Example: "Successfully processed 15 orders totaling $1,234.56. All items shipped."')
 });
 /**
  * Default tools bundle.
@@ -269,6 +317,10 @@ var generateUIInputSchema = z.object({
  * standard tools in your brain. Tools can be extended or overridden in
  * individual agent steps.
  *
+ * Note: A 'done' terminal tool is automatically generated for every agent.
+ * If you provide an outputSchema, 'done' will use that schema. Otherwise,
+ * it uses a default schema expecting { result: string }.
+ *
  * @example
  * ```typescript
  * import { createBrain, defaultTools } from '@positronic/core';
@@ -289,6 +341,7 @@ var generateUIInputSchema = z.object({
  * ```
  */ export var defaultTools = {
     generateUI: generateUI,
-    consoleLog: consoleLog,
-    done: done
+    waitForWebhook: waitForWebhook,
+    print: print,
+    consoleLog: consoleLog
 };

package/dist/src/ui/generate-ui.js

@@ -186,7 +186,7 @@ function _ts_generator(thisArg, body) {
 import { v4 as uuidv4 } from 'uuid';
 import { z } from 'zod';
 import { parseTemplate } from '../yaml/parser.js';
-import { inferDataType, validateDataBindings } from '../yaml/data-validator.js';
+import { inferDataType, resolveBindings, validateDataBindings } from '../yaml/data-validator.js';
 import { extractFormSchema, validateAgainstZod } from '../yaml/schema-extractor.js';
 import { describeDataShape } from '../yaml/type-inference.js';
 /**
@@ -319,7 +319,7 @@ import { describeDataShape } from '../yaml/type-inference.js';
  */ function createValidateTemplateTool(components, schema, data) {
     var dataType = inferDataType(data);
     return {
-        description: "Validate a YAML template. Checks that:\n1. The YAML is valid and can be parsed\n2. All component names are valid\n3. All data bindings (like {{email.subject}}) reference valid paths in the provided data\n4. Form components have a Button for submission\n5. The form fields will produce data matching the expected schema (if schema provided)\n\nCall this after generating your YAML template to verify it's correct before finalizing.",
+        description: "Validate a YAML template. Checks that:\n1. The YAML is valid and can be parsed\n2. All component names are valid\n3. All data bindings (like {{email.subject}}) reference valid paths in the provided data\n4. Form components have a Button for submission\n5. The form fields will produce data matching the expected schema (if schema provided)\n\nReturns resolvedBindings showing what each binding resolves to in the actual data. Use this to verify bindings point to the right values.\n\nCall this after generating your YAML template to verify it's correct before finalizing.",
         inputSchema: z.object({
             yaml: z.string().describe('The complete YAML template to validate')
         }),
@@ -390,6 +390,8 @@ import { describeDataShape } from '../yaml/type-inference.js';
                 var schemaErrors = validateAgainstZod(extracted, schema);
                 (_errors2 = errors).push.apply(_errors2, _to_consumable_array(schemaErrors));
             }
+            // 6. Resolve bindings against actual data
+            var resolved = resolveBindings(root, data);
             return {
                 valid: errors.length === 0,
                 errors: errors.map(function(e) {
@@ -398,7 +400,8 @@ import { describeDataShape } from '../yaml/type-inference.js';
                         message: e.message
                     };
                 }),
-                extractedFields: extractedFields
+                extractedFields: extractedFields,
+                resolvedBindings: resolved
             };
         }
     };