@positronic/core 0.0.55 → 0.0.57

package/dist/types/dsl/signal-validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Machine state definition structure.
+ * This matches the structure returned by robot3 createMachine.
+ */
+export interface MachineStateDefinition {
+    states: Record<string, {
+        transitions: Map<string, unknown>;
+    }>;
+}
+/**
+ * Result of signal validation.
+ */
+export interface SignalValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * 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 declare function isSignalValid(machineDefinition: MachineStateDefinition, brainStatus: string, signalType: string): SignalValidationResult;
+/**
+ * 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 declare function getValidSignals(machineDefinition: MachineStateDefinition, brainStatus: string): string[];
+//# sourceMappingURL=signal-validation.d.ts.map

package/dist/types/dsl/signal-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-validation.d.ts","sourceRoot":"","sources":["../../../src/dsl/signal-validation.ts"],"names":[],"mappings":"AA8BA;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,sBAAsB,EACzC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,sBAAsB,CAyBxB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,iBAAiB,EAAE,sBAAsB,EACzC,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CAmBV"}

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

@@ -53,6 +53,39 @@ export type JsonPatch = {
 export interface AgentToolWaitFor {
     waitFor: WebhookRegistration<z.ZodSchema> | WebhookRegistration<z.ZodSchema>[];
 }
+/**
+ * Context passed to step actions, agent config functions, and tool execute functions.
+ * This is the same context available throughout brain execution.
+ *
+ * Generic parameters allow type-safe access to state, options, response, and page.
+ * For tools (which are defined statically), use the non-generic defaults.
+ */
+export interface StepContext<TState = object, TOptions = JsonObject, TResponse = JsonObject | undefined, TPage = import('./definitions/brain-types.js').GeneratedPage | undefined> {
+    /** Current brain state */
+    state: TState;
+    /** Brain options */
+    options: TOptions;
+    /** The LLM client for making AI calls */
+    client: import('../clients/types.js').ObjectGenerator;
+    /** Resource loader for accessing brain resources */
+    resources: import('../resources/resources.js').Resources;
+    /** Webhook response data (when resuming after a webhook) */
+    response: TResponse;
+    /** Generated page from a previous UI step */
+    page: TPage;
+    /** Page service for creating UI pages */
+    pages?: import('./pages.js').PagesService;
+    /** Runtime environment (origin, secrets) */
+    env: RuntimeEnv;
+    /** UI components available for generateUI */
+    components?: Record<string, import('../ui/types.js').UIComponent<any>>;
+    /** Current brain run ID (for creating unique webhook identifiers) */
+    brainRunId: string;
+    /** Current step ID (for creating unique webhook identifiers) */
+    stepId: string;
+    /** Scoped memory for storing and retrieving long-term memories */
+    memory?: import('../memory/types.js').ScopedMemory;
+}
 /**
  * A tool definition for use in agent steps.
  * Compatible with Vercel AI SDK tool format, extended with Positronic-specific properties.
@@ -66,18 +99,31 @@ export interface AgentTool<TInput extends z.ZodSchema = z.ZodSchema> {
      * Execute function for the tool.
      * Can return a result directly, or { waitFor: webhook(...) } to suspend execution.
      * Not required for terminal tools.
+     * @param input - The validated input from the LLM
+     * @param context - Runtime context with access to client, pages, state, etc.
      */
-    execute?: (input: z.infer<TInput>) => Promise<unknown | AgentToolWaitFor> | unknown | AgentToolWaitFor;
+    execute?: (input: z.infer<TInput>, context: StepContext) => Promise<unknown | AgentToolWaitFor> | unknown | AgentToolWaitFor;
     /**
      * If true, calling this tool ends the agent.
      * The tool's input becomes the agent result (merged into state).
      */
     terminal?: boolean;
 }
+/**
+ * Configuration for agent output schema.
+ * When provided, generates a terminal tool from the schema and
+ * namespaces the result in state under the specified key.
+ */
+export interface AgentOutputSchema<TSchema extends z.ZodObject<any> = z.ZodObject<any>, TName extends string = string> {
+    /** Zod schema defining the agent's output structure */
+    schema: TSchema;
+    /** Key name to store the result under in state (use `as const` for type inference) */
+    name: TName;
+}
 /**
  * Configuration for an agent step.
  */
-export interface AgentConfig<TTools extends Record<string, AgentTool> = Record<string, AgentTool>> {
+export interface AgentConfig<TTools extends Record<string, AgentTool> = Record<string, AgentTool>, TOutputSchema extends AgentOutputSchema | undefined = undefined> {
     /** System prompt for the LLM */
     system?: string;
     /** Initial user prompt to start the conversation. If omitted, uses "Begin." */
@@ -86,6 +132,14 @@ export interface AgentConfig<TTools extends Record<string, AgentTool> = Record<s
     tools?: TTools;
     /** Safety valve - exit if cumulative tokens exceed this limit */
     maxTokens?: number;
+    /** Maximum number of agent loop iterations. Default: 100 */
+    maxIterations?: number;
+    /**
+     * Output schema for structured agent output.
+     * When provided, generates a terminal tool that validates output against the schema
+     * and stores the result under state[outputSchema.name].
+     */
+    outputSchema?: TOutputSchema;
 }
 /**
  * Represents a single message in the agent conversation.
@@ -122,4 +176,39 @@ export interface RetryConfig {
     /** Maximum delay in ms between retries. Default: 30000 */
     maxDelay?: number;
 }
+/**
+ * Signal types that can be sent to a running brain.
+ * Signals are processed in priority order: KILL > PAUSE > WEBHOOK_RESPONSE > RESUME > USER_MESSAGE
+ */
+export type SignalType = 'KILL' | 'PAUSE' | 'USER_MESSAGE' | 'RESUME' | 'WEBHOOK_RESPONSE';
+/**
+ * A signal that can be injected into a running brain's execution.
+ */
+export type BrainSignal = {
+    type: 'KILL';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'USER_MESSAGE';
+    content: string;
+} | {
+    type: 'RESUME';
+} | {
+    type: 'WEBHOOK_RESPONSE';
+    response: JsonObject;
+};
+/**
+ * Interface for providing signals to a running brain.
+ * Implementations are backend-specific (in-memory, database, KV store, etc.)
+ */
+export interface SignalProvider {
+    /**
+     * Get pending signals for the current brain run.
+     * Signals should be consumed (deleted) when returned.
+     *
+     * @param filter - 'CONTROL' returns only KILL/PAUSE, 'WEBHOOK' returns only WEBHOOK_RESPONSE, 'ALL' includes all signal types
+     * @returns Array of signals in priority order (KILL first, then PAUSE, then WEBHOOK_RESPONSE, then RESUME, then USER_MESSAGE)
+     */
+    getSignals(filter: 'CONTROL' | 'WEBHOOK' | 'ALL'): Promise<BrainSignal[]>;
+}
 //# 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":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/dsl/types.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -4,9 +4,9 @@ export { createBrain } from './dsl/create-brain.js';
 export type { CreateBrainConfig } from './dsl/create-brain.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, BrainConfig, GeneratedPage, } from './dsl/brain.js';
-export type { ObjectGenerator, Message, ToolMessage } from './clients/types.js';
-export type { State, RuntimeEnv, Secrets, AgentTool, AgentConfig, AgentMessage, AgentToolWaitFor, ExtractTerminalInput, RetryConfig, } from './dsl/types.js';
+export type { BrainEvent, SerializedStep, InitialRunParams, ResumeRunParams, ResumeContext, BrainStartEvent, BrainCompleteEvent, BrainErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent, StepRetryEvent, BrainStructure, BrainConfig, GeneratedPage, } from './dsl/brain.js';
+export type { ObjectGenerator, Message, ToolMessage, ToolCall, ResponseMessage } from './clients/types.js';
+export type { State, RuntimeEnv, Secrets, AgentTool, AgentConfig, AgentOutputSchema, AgentMessage, AgentToolWaitFor, StepContext, ExtractTerminalInput, RetryConfig, SignalType, BrainSignal, SignalProvider, } from './dsl/types.js';
 export { applyPatches } from './dsl/json-patch.js';
 export { z } from 'zod';
 export type { ResourceLoader } from './resources/resource-loader.js';
@@ -16,9 +16,14 @@ 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 { AgentStartEvent, AgentIterationEvent, AgentToolCallEvent, AgentToolResultEvent, AgentAssistantMessageEvent, AgentCompleteEvent, AgentTokenLimitEvent, AgentWebhookEvent, WebhookResponseEvent, } from './dsl/definitions/events.js';
-export { createTool, defaultTools, generateUI, consoleLog, done } from './tools/index.js';
+export type { AgentStartEvent, AgentIterationEvent, AgentToolCallEvent, AgentToolResultEvent, AgentAssistantMessageEvent, AgentCompleteEvent, AgentTokenLimitEvent, AgentIterationLimitEvent, AgentWebhookEvent, AgentRawResponseMessageEvent, AgentUserMessageEvent, WebhookResponseEvent, BrainPausedEvent, } from './dsl/definitions/events.js';
+export { createTool, defaultTools, defaultDoneSchema, generateUI, waitForWebhook, print, consoleLog } from './tools/index.js';
+export type { Memory, MemoryMessage, MemoryScope, MemorySearchOptions, MemoryAddOptions, MemoryProvider, ScopedMemory, } from './memory/types.js';
+export { createScopedMemory } from './memory/scoped-memory.js';
 export type { UIComponent } from './ui/types.js';
-export { createBrainExecutionMachine, createBrainMachine, sendEvent, getDepth, isTopLevel, getCurrentStep, getBrainStack, getBrainRunId, getExecutionState, getPendingWebhooks, getError, getCompletedSteps, } from './dsl/brain-state-machine.js';
-export type { BrainStateMachine, BrainExecutionContext, BrainStackEntry, RunningBrain, StepInfo, ExecutionState, CreateMachineOptions, } from './dsl/brain-state-machine.js';
+export { createBrainExecutionMachine, createBrainMachine, sendEvent, reconstructBrainTree, brainMachineDefinition, } from './dsl/brain-state-machine.js';
+export { isSignalValid, getValidSignals, } from './dsl/signal-validation.js';
+export type { MachineStateDefinition, SignalValidationResult, } from './dsl/signal-validation.js';
+export type { BrainStateMachine, BrainExecutionContext, BrainStackEntry, BrainEntry, ExecutionStackEntry, RunningBrain, StepInfo, ExecutionState, CreateMachineOptions, AgentContext, ExecutionNode, } from './dsl/brain-state-machine.js';
+export type { AgentResumeContext } from './dsl/agent-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,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,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,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,SAAS,EACT,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,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,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAG1F,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,oBAAoB,GACrB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,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,eAAe,EACf,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3G,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,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,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9H,YAAY,EACV,MAAM,EACN,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,aAAa,EACb,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/types/memory/scoped-memory.d.ts

@@ -0,0 +1,22 @@
+import type { MemoryProvider, ScopedMemory } from './types.js';
+/**
+ * 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 declare function createScopedMemory(provider: MemoryProvider, agentId: string): ScopedMemory;
+//# sourceMappingURL=scoped-memory.d.ts.map

package/dist/types/memory/scoped-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/scoped-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAKb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,GACd,YAAY,CAwBd"}

package/dist/types/memory/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+export interface Memory {
+    /** Unique identifier for this memory */
+    id: string;
+    /** The memory content */
+    content: string;
+    /** Relevance score from 0-1 (optional, provider-dependent) */
+    score?: number;
+    /** Additional metadata about the memory */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Message format for adding memories.
+ * Compatible with common conversation formats.
+ */
+export interface MemoryMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/**
+ * Scope parameters for memory operations.
+ * Used to namespace memories by agent and optionally by user.
+ */
+export interface MemoryScope {
+    /** The agent/brain ID this memory belongs to */
+    agentId: string;
+    /** Optional user ID for user-specific memories */
+    userId?: string;
+}
+/**
+ * Search options for memory retrieval.
+ */
+export interface MemorySearchOptions {
+    /** Optional user ID to scope the search */
+    userId?: string;
+    /** Maximum number of memories to return */
+    limit?: number;
+}
+/**
+ * Options for adding memories.
+ */
+export interface MemoryAddOptions {
+    /** Optional user ID to scope the memory */
+    userId?: string;
+    /** Additional metadata to store with the memory */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Raw memory provider interface.
+ * Implementations handle the actual storage and retrieval of memories.
+ * All methods take the full scope (agentId + optional userId).
+ */
+export interface MemoryProvider {
+    /**
+     * Search for relevant memories.
+     *
+     * @param query - The search query
+     * @param scope - The scope including agentId and optional userId
+     * @param options - Additional search options
+     * @returns Array of matching memories
+     */
+    search(query: string, scope: MemoryScope, options?: {
+        limit?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Add memories from a conversation.
+     *
+     * @param messages - Array of messages to extract memories from
+     * @param scope - The scope including agentId and optional userId
+     * @param options - Additional options like metadata
+     */
+    add(messages: MemoryMessage[], scope: MemoryScope, options?: {
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+}
+/**
+ * Scoped memory interface with agentId pre-bound.
+ * This is what brain steps receive - they don't need to pass agentId.
+ */
+export interface ScopedMemory {
+    /**
+     * Search for relevant memories.
+     *
+     * @param query - The search query
+     * @param options - Optional search options (userId, limit)
+     * @returns Array of matching memories
+     */
+    search(query: string, options?: MemorySearchOptions): Promise<Memory[]>;
+    /**
+     * Add memories from messages.
+     *
+     * @param messages - Array of messages to extract memories from
+     * @param options - Optional options (userId, metadata)
+     */
+    add(messages: MemoryMessage[], options?: MemoryAddOptions): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAErB;;;;;;OAMG;IACH,GAAG,CACD,QAAQ,EAAE,aAAa,EAAE,EACzB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC/C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAExE;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E"}

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { AgentTool, AgentToolWaitFor } from '../dsl/types.js';
+import type { AgentTool, AgentToolWaitFor, StepContext } from '../dsl/types.js';
 /**
  * Helper function to create tools with proper type inference.
  *
@@ -14,7 +14,7 @@ import type { AgentTool, AgentToolWaitFor } from '../dsl/types.js';
  *     message: z.string().describe('The notification message'),
  *     clickUrl: z.string().optional().describe('URL to open on click'),
  *   }),
- *   execute: async ({ message, clickUrl }) => {  // Types inferred!
+ *   execute: async ({ message, clickUrl }, context) => {
  *     await ntfy.send(message, clickUrl);
  *     return { sent: true };
  *   },
@@ -24,28 +24,76 @@ import type { AgentTool, AgentToolWaitFor } from '../dsl/types.js';
 export declare function createTool<T extends z.ZodSchema>(config: {
     description: string;
     inputSchema: T;
-    execute?: (input: z.infer<T>) => unknown | Promise<unknown> | AgentToolWaitFor | Promise<AgentToolWaitFor>;
+    execute?: (input: z.infer<T>, context: StepContext) => unknown | Promise<unknown> | AgentToolWaitFor | Promise<AgentToolWaitFor>;
     terminal?: boolean;
 }): AgentTool<T>;
+declare const generateUIInputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    hasForm: z.ZodOptional<z.ZodBoolean>;
+    persist: z.ZodOptional<z.ZodBoolean>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    data?: Record<string, unknown> | undefined;
+    hasForm?: boolean | undefined;
+    persist?: boolean | undefined;
+}, {
+    prompt: string;
+    data?: Record<string, unknown> | undefined;
+    hasForm?: boolean | undefined;
+    persist?: boolean | undefined;
+}>;
 /**
- * Default generateUI tool - gets enriched with component metadata at runtime.
+ * 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. 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.
  *
- * This tool allows the LLM to generate a UI and wait for user response.
- * The actual component list and descriptions are injected at runtime
- * based on the components registered with .withComponents().
+ * Requires components and pages to be configured via createBrain or withComponents().
+ *
+ * The description is enriched at runtime with available component information.
  */
-export declare const generateUI: AgentTool<z.ZodObject<{
-    component: z.ZodString;
-    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const generateUI: AgentTool<typeof generateUIInputSchema>;
+declare const waitForWebhookInputSchema: z.ZodObject<{
+    slug: z.ZodString;
+    identifier: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    component: string;
-    props: Record<string, unknown>;
+    slug: string;
+    identifier: string;
+}, {
+    slug: string;
+    identifier: string;
+}>;
+/**
+ * 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 declare const waitForWebhook: AgentTool<typeof waitForWebhookInputSchema>;
+/**
+ * Print tool - the simplest way for agents to communicate with users.
+ * Like PRINT in BASIC - outputs a message that users can see.
+ */
+export declare const print: AgentTool<z.ZodObject<{
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
 }, {
-    component: string;
-    props: Record<string, unknown>;
+    message: string;
 }>>;
 /**
- * Console log tool - useful for debugging and logging information during agent execution.
+ * Console log tool - for internal server-side debugging and logging.
+ * NOT for user communication - use print for that.
  */
 export declare const consoleLog: AgentTool<z.ZodObject<{
     message: z.ZodString;
@@ -58,16 +106,16 @@ export declare const consoleLog: AgentTool<z.ZodObject<{
     level?: "error" | "info" | "warn" | undefined;
 }>>;
 /**
- * Done tool - a simple terminal tool for completing agent execution.
- * The result becomes part of the brain state.
+ * Default schema for the auto-generated 'done' tool when no outputSchema is provided.
+ * Used internally by the framework.
  */
-export declare const done: AgentTool<z.ZodObject<{
+export declare const defaultDoneSchema: z.ZodObject<{
     result: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     result: string;
 }, {
     result: string;
-}>>;
+}>;
 /**
  * Default tools bundle.
  *
@@ -75,6 +123,10 @@ export declare const done: AgentTool<z.ZodObject<{
  * 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';
@@ -96,14 +148,37 @@ export declare const done: AgentTool<z.ZodObject<{
  */
 export declare const defaultTools: {
     generateUI: AgentTool<z.ZodObject<{
-        component: z.ZodString;
-        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        prompt: z.ZodString;
+        hasForm: z.ZodOptional<z.ZodBoolean>;
+        persist: z.ZodOptional<z.ZodBoolean>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        data?: Record<string, unknown> | undefined;
+        hasForm?: boolean | undefined;
+        persist?: boolean | undefined;
+    }, {
+        prompt: string;
+        data?: Record<string, unknown> | undefined;
+        hasForm?: boolean | undefined;
+        persist?: boolean | undefined;
+    }>>;
+    waitForWebhook: AgentTool<z.ZodObject<{
+        slug: z.ZodString;
+        identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        component: string;
-        props: Record<string, unknown>;
+        slug: string;
+        identifier: string;
     }, {
-        component: string;
-        props: Record<string, unknown>;
+        slug: string;
+        identifier: string;
+    }>>;
+    print: AgentTool<z.ZodObject<{
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+    }, {
+        message: string;
     }>>;
     consoleLog: AgentTool<z.ZodObject<{
         message: z.ZodString;
@@ -115,12 +190,6 @@ export declare const defaultTools: {
         message: string;
         level?: "error" | "info" | "warn" | undefined;
     }>>;
-    done: AgentTool<z.ZodObject<{
-        result: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        result: string;
-    }, {
-        result: string;
-    }>>;
 };
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3G,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,SAAS,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;;;;;;;GAwBrB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;GAWrB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;GAMf,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIxB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC;IACf,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,WAAW,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,SAAS,CAAC,CAAC,CAAC,CAEf;AAED,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;EAwBzB,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,CAAC,OAAO,qBAAqB,CAqF9D,CAAC;AAEF,QAAA,MAAM,yBAAyB;;;;;;;;;EAW7B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,OAAO,yBAAyB,CAuCtE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,KAAK;;;;;;GAWhB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;GAWrB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKxB,CAAC"}

package/dist/types/ui/generate-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-ui.d.ts","sourceRoot":"","sources":["../../../src/ui/generate-ui.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0DrE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAgUD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqD5B"}
+{"version":3,"file":"generate-ui.d.ts","sourceRoot":"","sources":["../../../src/ui/generate-ui.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAkErE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAuUD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqD5B"}

package/dist/types/yaml/data-validator.d.ts

@@ -4,7 +4,7 @@
  * Validates that template bindings (like {{email.subject}}) reference
  * valid paths in the provided data structure.
  */
-import type { ComponentNode, DataType, ValidationResult } from './types.js';
+import type { ComponentNode, DataType, ResolvedBinding, ValidationResult } from './types.js';
 /**
  * Loop context tracks variables introduced by List/Each components.
  * Maps variable name to the element type of the array being iterated.
@@ -31,5 +31,31 @@ export declare function resolvePathType(path: string, rootType: DataType, loopCo
  * @returns ValidationResult with any errors found
  */
 export declare function validateDataBindings(root: ComponentNode, dataType: DataType): ValidationResult;
+/**
+ * Loop data context maps loop variable names to their sample values.
+ */
+type LoopDataContext = Map<string, unknown>;
+/**
+ * Resolve a binding path against actual data, considering loop context.
+ *
+ * @param path - The binding path like "email.subject"
+ * @param rootData - The root data object
+ * @param loopDataContext - Map of loop variable names to sample values
+ * @returns The resolved value, or undefined if the path doesn't resolve
+ */
+export declare function resolvePathValue(path: string, rootData: Record<string, unknown>, loopDataContext: LoopDataContext): unknown;
+/**
+ * Summarize a value for LLM consumption.
+ * Keeps output compact — no full data dumps.
+ */
+export declare function summarizeValue(value: unknown): string;
+/**
+ * Walk the ComponentNode tree and resolve every binding against real data.
+ *
+ * @param root - The root ComponentNode
+ * @param data - The actual data object
+ * @returns Array of ResolvedBinding entries
+ */
+export declare function resolveBindings(root: ComponentNode, data: Record<string, unknown>): ResolvedBinding[];
 export {};
 //# sourceMappingURL=data-validator.d.ts.map

package/dist/types/yaml/data-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-validator.d.ts","sourceRoot":"","sources":["../../../src/yaml/data-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EAER,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzC;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAkCtD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,GACvB,QAAQ,GAAG,IAAI,CA+BjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAyDlB"}
+{"version":3,"file":"data-validator.d.ts","sourceRoot":"","sources":["../../../src/yaml/data-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,eAAe,EAEf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzC;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAkCtD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,GACvB,QAAQ,GAAG,IAAI,CA+BjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAyDlB;AAED;;GAEG;AACH,KAAK,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,eAAe,EAAE,eAAe,GAC/B,OAAO,CA0BT;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2BrD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,eAAe,EAAE,CA4DnB"}

package/dist/types/yaml/types.d.ts

@@ -71,6 +71,16 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
 }
+/**
+ * Result of resolving a binding against actual data at dry-run time.
+ */
+export interface ResolvedBinding {
+    path: string;
+    component: string;
+    prop: string;
+    value: string;
+    resolved: boolean;
+}
 /**
  * Data type inference for validating bindings.
  */