@limo-labs/deity 0.2.0-alpha.0 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ZodSchema, z } from 'zod';
-import { V as Validator, T as Tool, A as AgentNode, P as PromptNode, E as ExecutionContext$1, S as SystemNode, U as UserNode, L as LLMLoopResult$1, O as ObserveNode, R as ResultNode, a as ValidationRules, b as ValidateNode, c as RetryNode, d as AgentComponent, M as Message, e as ValidationResult$1, f as LLMAdapter, G as GenerationConfig, g as ExecutionNode, W as WorkflowConfig, h as StateStore, i as TraceLogger, j as TraceEntry, k as ExecutionStats, C as ConversationManager, l as LimoMemoryManager, m as UIUpdateBridge, n as SessionStore, o as ConversationConfig, p as MemoryConfig, q as SessionConfig } from './jsx-dev-runtime-CKrGWO-8.js';
-export { r as ASTNode, J as JSXComponent, s as JSXElementType, t as JSXProps, u as LLMLoopState, v as LLMResponse, w as MessageRole, x as ToolCall, y as ToolResult, z as ValidationRule, B as isAgentNode, D as isObserveNode, F as isPromptNode, H as isResultNode, I as isRetryNode, K as isSystemNode, N as isUserNode, Q as isValidateNode } from './jsx-dev-runtime-CKrGWO-8.js';
+import { V as Validator, T as ToolSpec, A as AgentNode, P as PromptNode, E as ExecutionContext$1, S as SystemNode, U as UserNode, L as LLMLoopResult, O as ObserveNode, R as ResultNode, a as ValidationRules, b as ValidateNode, c as RetryNode, d as ToolDefNode, e as ToolsNode, f as ToolRefNode, W as WorkflowChildNode, g as WorkflowSequenceNode, h as WorkflowParallelNode, i as WorkflowConditionalNode, j as WorkflowLoopNode, k as WorkflowForEachNode, l as WorkflowNode, m as AgentComponent, n as WorkflowConfig, o as ExecutionNode, p as ASTNode, M as Message, q as ValidationResult$1, r as LLMAdapter$1, G as GenerationConfig$1, s as StateStore$1, t as TraceLogger, u as TraceEntry, v as ExecutionStats, C as ConversationManager, w as LimoMemoryManager, x as UIUpdateBridge, y as SessionStore, z as ConversationConfig, B as MemoryConfig, D as SessionConfig } from './jsx-dev-runtime-Dg782FK5.js';
+export { J as JSXComponent, F as JSXElementType, H as JSXProps, I as LLMLoopState, K as LLMResponse, N as MessageRole, Q as TemplatePart, X as ToolCall, Y as ToolResult, Z as ValidationRule, _ as isAgentNode, $ as isObserveNode, a0 as isPromptNode, a1 as isResultNode, a2 as isRetryNode, a3 as isSystemNode, a4 as isToolDefNode, a5 as isToolRefNode, a6 as isToolsNode, a7 as isUserNode, a8 as isValidateNode, a9 as isWorkflowConditionalNode, aa as isWorkflowForEachNode, ab as isWorkflowLoopNode, ac as isWorkflowNode, ad as isWorkflowParallelNode, ae as isWorkflowSequenceNode } from './jsx-dev-runtime-Dg782FK5.js';
 
 /**
  * Deity TSX - Agent Component
@@ -35,9 +35,9 @@ interface AgentProps<I = unknown, O = unknown> {
     loopValidator?: Validator;
     /** Optional LLM loop configuration */
     loopConfig?: LLMLoopConfig$1;
-    /** Optional tool definitions */
-    tools?: Tool[];
-    /** Child components (Prompt, Observe, Result, Validate, Retry) */
+    /** Optional tool definitions (backward compatible - can also use <Tools> child) */
+    tools?: ToolSpec[];
+    /** Child components (Tools, Prompt, Observe, Result, Validate, Retry) */
     children?: any[];
 }
 /**
@@ -47,11 +47,19 @@ interface AgentProps<I = unknown, O = unknown> {
  * - Identity (id, description, tags)
  * - IO schemas (input/output)
  * - Behavior specification (Prompt, Observe, Result, Validate, Retry)
+ * - Tool definitions (via props.tools or <Tools> child)
  *
  * @example
  * ```tsx
  * export const MyAgent = (
  *   <Agent id="my-agent" input={InputSchema} output={OutputSchema}>
+ *     <Tools>
+ *       <MemoryStore />
+ *       <MemoryRecall />
+ *       <Tool name="my_tool" description="..." input={Schema}>
+ *         {async (params) => ({ ... })}
+ *       </Tool>
+ *     </Tools>
  *     <Prompt>
  *       <System source="file:./prompt.md" />
  *       <User>{(ctx) => `Task: ${ctx.inputs.task}`}</User>
@@ -241,7 +249,7 @@ interface ObserveProps {
     /**
      * Alternative to children (same as children)
      */
-    compute?: (llmResult: LLMLoopResult$1) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    compute?: (llmResult: LLMLoopResult) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
 /**
  * Observe Component
@@ -303,7 +311,7 @@ interface ResultProps<O = unknown> {
     /**
      * Alternative to children (same as children)
      */
-    extract?: (ctx: ExecutionContext$1, llmResult: LLMLoopResult$1, observed: Record<string, unknown>) => O | Promise<O>;
+    extract?: (ctx: ExecutionContext$1, llmResult: LLMLoopResult, observed: Record<string, unknown>) => O | Promise<O>;
 }
 /**
  * Result Component
@@ -446,6 +454,511 @@ interface RetryProps {
  */
 declare function Retry(props?: RetryProps): RetryNode;
 
+/**
+ * Deity TSX - Tools Components
+ *
+ * Container and definition components for declaring tools in JSX.
+ *
+ * @example
+ * ```tsx
+ * <Agent id="my-agent" input={InputSchema} output={OutputSchema}>
+ *   <Tools>
+ *     <MemoryStore />
+ *     <MemoryRecall />
+ *     <Tool name="greet" description="Greet user" input={GreetSchema}>
+ *       {async (params) => ({ success: true, data: { message: `Hello ${params.name}` } })}
+ *     </Tool>
+ *   </Tools>
+ *   <Prompt>...</Prompt>
+ *   <Result>...</Result>
+ * </Agent>
+ * ```
+ */
+
+/**
+ * Tools Component Props
+ */
+interface ToolsProps {
+    /** Child ToolDef/Tool components */
+    children?: any[];
+}
+/**
+ * Tools Component
+ *
+ * Container for tool definitions within an Agent.
+ * All tools (including memory tools) are declared as children.
+ */
+declare function Tools(props: ToolsProps): ToolsNode;
+/**
+ * ToolDef Component Props
+ */
+interface ToolDefProps {
+    /** The tool object to register */
+    tool: ToolSpec;
+    /** Children (not used, but accepted for JSX compatibility) */
+    children?: any[];
+}
+/**
+ * ToolDef Component
+ *
+ * Wraps a single Tool object as a JSX element.
+ * Must be used inside a <Tools> container.
+ *
+ * Low-level escape hatch for pre-built ToolSpec objects.
+ * Prefer using the declarative <Tool> component for new tools.
+ */
+declare function ToolDef(props: ToolDefProps): ToolDefNode;
+/**
+ * Tool Component Props
+ *
+ * Declarative tool definition using TSX syntax.
+ *
+ * @example
+ * ```tsx
+ * <Tool name="file_list" description="List files" input={FileListInputSchema}>
+ *   {async (params) => {
+ *     const files = await glob(params.pattern);
+ *     return { success: true, data: { files } };
+ *   }}
+ * </Tool>
+ *
+ * // Or using the execute prop instead of children:
+ * <Tool
+ *   name="file_list"
+ *   description="List files"
+ *   input={FileListInputSchema}
+ *   execute={async (params) => ({ success: true, data: { files: [] } })}
+ * />
+ * ```
+ */
+interface ToolProps<TInput = unknown> {
+    /** Tool name (unique identifier used by LLM) */
+    name: string;
+    /** Description (LLM uses this to decide when to invoke the tool) */
+    description: string;
+    /** Input validation schema (Zod) */
+    input: ZodSchema<TInput>;
+    /**
+     * Execute function (alternative to children).
+     * Use either `execute` prop or a function child, not both.
+     */
+    execute?: (input: TInput, ctx?: ExecutionContext$1) => any;
+    /** Function child that implements tool execution */
+    children?: any[];
+}
+/**
+ * Tool Component
+ *
+ * Declarative tool definition as a first-class TSX component.
+ * Produces a `ToolDefNode` (same as `<ToolDef>`), so the
+ * compiler and executor require zero changes.
+ *
+ * @example
+ * ```tsx
+ * <Tool name="file_list" description="List files" input={FileListInputSchema}>
+ *   {async (params: FileListInput) => {
+ *     const files = await glob(params.pattern, { cwd: rootPath });
+ *     return { success: true, data: { files, total: files.length } };
+ *   }}
+ * </Tool>
+ * ```
+ */
+declare function Tool<TInput = unknown>(props: ToolProps<TInput>): ToolDefNode;
+
+/**
+ * Deity TSX - ToolRef Component
+ *
+ * Allows referencing tool names in prompt text in a type-safe, refactoring-friendly way.
+ */
+
+/**
+ * ToolRef target type
+ *
+ * Can be:
+ * - A tool component function with .toolName static property
+ * - A ToolSpec object with .name property
+ * - A plain string tool ID
+ */
+type ToolRefTarget = {
+    toolName: string;
+} | {
+    (): ToolDefNode;
+    toolName: string;
+} | ToolSpec | string;
+/**
+ * ToolRef Component Props
+ */
+interface ToolRefProps {
+    /**
+     * Tool reference
+     *
+     * Can be:
+     * - Tool component with .toolName: `<ToolRef tool={MemoryStore} />`
+     * - ToolSpec object: `<ToolRef tool={myToolSpec} />`
+     * - String ID: `<ToolRef tool="memory_store" />`
+     */
+    tool: ToolRefTarget;
+}
+/**
+ * ToolRef Component
+ *
+ * Inserts a tool name reference into prompt text. The reference is resolved
+ * at compile time to the tool's runtime ID.
+ *
+ * This provides type-safe, refactor-friendly tool references that stay in sync
+ * with the <Tools> tree, unlike hard-coded string IDs.
+ *
+ * @example
+ * ```tsx
+ * import { MemoryStore } from '@limo-labs/deity-tools';
+ *
+ * <User>
+ *   Use <ToolRef tool={MemoryStore} /> to save your findings.
+ * </User>
+ * // Compiles to: "Use memory_store to save your findings."
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With a custom tool
+ * const myTool = createTool({ name: 'my_tool', ... });
+ *
+ * <User>
+ *   Call <ToolRef tool={myTool} /> when ready.
+ * </User>
+ * // Compiles to: "Call my_tool when ready."
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Direct string (for backwards compatibility)
+ * <User>
+ *   Use <ToolRef tool="memory_store" /> for persistence.
+ * </User>
+ * ```
+ */
+declare function ToolRef(props: ToolRefProps): ToolRefNode;
+
+/**
+ * Deity TSX - Sequence Component
+ *
+ * Execute child nodes in sequential order.
+ */
+
+/**
+ * Sequence Component Props
+ */
+interface SequenceProps {
+    /** Child workflow nodes (Agents or other workflow structures) */
+    children?: WorkflowChildNode[] | any[];
+}
+/**
+ * Sequence Component
+ *
+ * Executes child nodes in sequential order.
+ * Each child completes before the next one starts.
+ *
+ * @example
+ * ```tsx
+ * <Sequence>
+ *   <Agent1 />
+ *   <Agent2 />
+ *   <Agent3 />
+ * </Sequence>
+ * ```
+ */
+declare function Sequence(props: SequenceProps): WorkflowSequenceNode;
+
+/**
+ * Deity TSX - Parallel Component
+ *
+ * Execute child nodes concurrently.
+ */
+
+/**
+ * Parallel Component Props
+ */
+interface ParallelProps {
+    /** Child workflow nodes (Agents or other workflow structures) */
+    children?: WorkflowChildNode[] | any[];
+}
+/**
+ * Parallel Component
+ *
+ * Executes child nodes concurrently (in parallel).
+ * All children start simultaneously and the node completes when all children complete.
+ *
+ * @example
+ * ```tsx
+ * <Parallel>
+ *   <SecurityScanAgent />
+ *   <PerformanceAnalysisAgent />
+ *   <CodeQualityAgent />
+ * </Parallel>
+ * ```
+ */
+declare function Parallel(props: ParallelProps): WorkflowParallelNode;
+
+/**
+ * Deity TSX - Conditional Component
+ *
+ * Execute child nodes based on a condition.
+ */
+
+/**
+ * Conditional Component Props
+ */
+interface ConditionalProps {
+    /** Condition function (true = first child, false = second child) */
+    condition: (ctx: ExecutionContext$1) => boolean | Promise<boolean>;
+    /** Child workflow nodes (1-2 children: true branch required, false branch optional) */
+    children?: [WorkflowChildNode] | [WorkflowChildNode, WorkflowChildNode] | any[];
+}
+/**
+ * Conditional Component
+ *
+ * Executes child nodes based on a condition function.
+ * - First child: executed when condition returns true
+ * - Second child (optional): executed when condition returns false
+ *
+ * @example
+ * ```tsx
+ * <Conditional condition={(ctx) => ctx.getOutput('check').needsAnalysis}>
+ *   <DeepAnalysisAgent />
+ *   <QuickSummaryAgent />
+ * </Conditional>
+ * ```
+ *
+ * @example With only true branch
+ * ```tsx
+ * <Conditional condition={(ctx) => ctx.getOutput('check').isValid}>
+ *   <ProcessAgent />
+ * </Conditional>
+ * ```
+ */
+declare function Conditional(props: ConditionalProps): WorkflowConditionalNode;
+
+/**
+ * Deity TSX - Loop Component
+ *
+ * Execute a child node N times.
+ */
+
+/**
+ * Loop Component Props
+ */
+interface LoopProps {
+    /** Number of iterations */
+    iterations: number;
+    /** Single child workflow node (Agent or workflow structure) */
+    children?: WorkflowChildNode | any;
+}
+/**
+ * Loop Component
+ *
+ * Executes a single child node N times.
+ * The child has access to iteration context via ctx.iteration.
+ *
+ * @example
+ * ```tsx
+ * <Loop iterations={3}>
+ *   <RefineAgent />
+ * </Loop>
+ * ```
+ */
+declare function Loop(props: LoopProps): WorkflowLoopNode;
+
+/**
+ * Deity TSX - ForEach Component
+ *
+ * Execute a child node for each item in a dynamic array.
+ */
+
+/**
+ * Item injection modes for ForEach
+ */
+type ItemMode = 'merge' | 'replace' | 'property';
+/**
+ * Error handling modes for ForEach
+ */
+type ErrorMode = 'stop' | 'continue' | 'skip';
+/**
+ * ForEach Component Props
+ */
+interface ForEachProps<TItem = unknown> {
+    /**
+     * Array of items to iterate over, or function to dynamically resolve items
+     * Function can be sync or async
+     */
+    items: TItem[] | ((ctx: ExecutionContext$1) => TItem[] | Promise<TItem[]>);
+    /**
+     * How to inject the current item into context inputs
+     * - 'property' (default): Inject as ctx.inputs[itemKey]
+     * - 'merge': Spread item properties into ctx.inputs (for object items)
+     * - 'replace': Replace entire ctx.inputs with item
+     */
+    itemMode?: ItemMode;
+    /**
+     * Key name for 'property' mode (default: 'currentItem')
+     */
+    itemKey?: string;
+    /**
+     * Error handling mode
+     * - 'stop' (default): Fail-fast, throw on first error
+     * - 'continue': Collect errors, don't stop loop
+     * - 'skip': Silent failure, increment failure count only
+     */
+    errorMode?: ErrorMode;
+    /**
+     * Whether to collect results from each iteration (default: true)
+     * Set to false for side-effect-only operations to optimize memory
+     */
+    collectResults?: boolean;
+    /** Single child workflow node (Agent or workflow structure) */
+    children?: WorkflowChildNode | any;
+}
+/**
+ * ForEach Component
+ *
+ * Executes a single child node for each item in an array.
+ * The child has access to iteration context via ctx.iteration and the current item
+ * via the injection mode specified.
+ *
+ * @example
+ * ```tsx
+ * // Static array with property injection
+ * <ForEach items={['task1', 'task2', 'task3']} itemKey="task">
+ *   <ProcessAgent />
+ * </ForEach>
+ *
+ * // Dynamic array with merge injection
+ * <ForEach
+ *   items={(ctx) => ctx.getOutput('planner').tasks}
+ *   itemMode="merge"
+ *   errorMode="continue"
+ *   collectResults={false}
+ * >
+ *   <AnalystAgent />
+ * </ForEach>
+ * ```
+ */
+declare function ForEach<TItem = unknown>(props: ForEachProps<TItem>): WorkflowForEachNode;
+
+/**
+ * Deity TSX - Workflow Component
+ *
+ * Top-level container for defining a complete workflow.
+ */
+
+/**
+ * LLM Adapter interface (minimal definition for type safety)
+ */
+interface LLMAdapter {
+    generate(messages: any[], config?: any): Promise<any>;
+}
+/**
+ * Generation Config (minimal definition)
+ */
+interface GenerationConfig {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+}
+/**
+ * State Store interface (minimal definition)
+ */
+interface StateStore {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+}
+/**
+ * Workflow Enhancement Options
+ */
+interface WorkflowEnhancements {
+    /** Conversation management */
+    conversation?: {
+        maxTokens: number;
+        pruneThreshold: number;
+        messageRetentionPolicy?: unknown;
+    };
+    /** Memory management */
+    memory?: {
+        coreBudget: {
+            maxItems: number;
+            maxTotalSize: number;
+        };
+        detailedBudget?: {
+            maxItems: number;
+            maxTotalSize: number;
+        };
+    };
+    /** Session persistence */
+    session?: {
+        directory: string;
+        autoSave?: boolean;
+    };
+    /** UI updates */
+    ui?: any;
+    /** Application state store (isolated from AI memory) */
+    appState?: any;
+}
+/**
+ * Workflow Component Props
+ */
+interface WorkflowProps {
+    /** Workflow name (required) */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Default LLM model configuration */
+    defaultModel?: {
+        adapter: LLMAdapter;
+        config?: GenerationConfig;
+    };
+    /** Optional state storage */
+    state?: {
+        store: StateStore;
+    };
+    /** Optional enhancements (conversation, memory, session, UI) */
+    enhancements?: WorkflowEnhancements;
+    /** Single child representing the workflow graph */
+    children?: WorkflowChildNode | any;
+}
+/**
+ * Workflow Component
+ *
+ * Top-level container for defining a complete workflow.
+ * Must contain exactly one child representing the workflow execution graph.
+ *
+ * @example
+ * ```tsx
+ * const workflow = Workflow({
+ *   name: 'my-workflow',
+ *   defaultModel: { adapter: llmAdapter },
+ *   children: Sequence({
+ *     children: [Agent1, Agent2, Agent3]
+ *   })
+ * });
+ * ```
+ *
+ * @example With enhancements
+ * ```tsx
+ * const workflow = Workflow({
+ *   name: 'enhanced-workflow',
+ *   defaultModel: { adapter: llmAdapter },
+ *   enhancements: {
+ *     conversation: { maxTokens: 8000, pruneThreshold: 6000 },
+ *     memory: {
+ *       coreBudget: { maxItems: 10, maxTotalSize: 8192 }
+ *     }
+ *   },
+ *   children: MyAgent
+ * });
+ * ```
+ */
+declare function Workflow(props: WorkflowProps): WorkflowNode;
+
 /**
  * Deity TSX - AST Compiler
  *
@@ -492,7 +1005,53 @@ declare function compileAgent<I = unknown, O = unknown>(ast: AgentNode<I, O>): A
  *
  * Extracts observations from LLM loop result.
  */
-type ObserveFunction = (llmResult: LLMLoopResult$1) => Promise<Record<string, unknown>>;
+type ObserveFunction = (llmResult: LLMLoopResult) => Promise<Record<string, unknown>>;
+
+/**
+ * Deity TSX - Workflow Compiler
+ *
+ * Compiles WorkflowNode AST into executable WorkflowConfig.
+ */
+
+/**
+ * Compile Workflow AST to WorkflowConfig
+ *
+ * This is the main entry point for compiling a complete workflow.
+ *
+ * @param ast - Workflow AST node
+ * @returns Executable WorkflowConfig that can be passed to runWorkflow()
+ *
+ * @example
+ * ```typescript
+ * const MyWorkflow = Workflow({
+ *   name: 'my-workflow',
+ *   defaultModel: { adapter: llmAdapter },
+ *   children: Sequence({
+ *     children: [Agent1, Agent2, Agent3]
+ *   })
+ * });
+ *
+ * const config = compileWorkflow(MyWorkflow);
+ * const result = await runWorkflow(config, inputs);
+ * ```
+ */
+declare function compileWorkflow(ast: WorkflowNode): WorkflowConfig;
+
+/**
+ * Deity TSX - Workflow Node Compiler
+ *
+ * Compiles workflow structure AST nodes into ExecutionNode instances.
+ */
+
+/**
+ * Compile a workflow child node (Agent or workflow structure) to ExecutionNode
+ *
+ * This is the main dispatcher that routes to the appropriate compiler.
+ *
+ * @param node - Workflow child node (Agent, Sequence, Parallel, Conditional, Loop, ForEach)
+ * @returns ExecutionNode that can be executed by the runtime
+ */
+declare function compileWorkflowNode(node: WorkflowChildNode): ExecutionNode;
 
 /**
  * Deity TSX - Observe Utilities
@@ -531,7 +1090,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static countToolCalls(llmResult: LLMLoopResult$1): number;
+    static countToolCalls(llmResult: LLMLoopResult): number;
     /**
      * Count tool calls by name
      *
@@ -547,7 +1106,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static countToolCallsByName(llmResult: LLMLoopResult$1, name: string): number;
+    static countToolCallsByName(llmResult: LLMLoopResult, name: string): number;
     /**
      * Count tool calls matching filter
      *
@@ -563,7 +1122,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static countToolCallsWhere(llmResult: LLMLoopResult$1, filter: ToolCallFilter): number;
+    static countToolCallsWhere(llmResult: LLMLoopResult, filter: ToolCallFilter): number;
     /**
      * Get list of unique tool names called
      *
@@ -576,7 +1135,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static getToolNames(llmResult: LLMLoopResult$1): string[];
+    static getToolNames(llmResult: LLMLoopResult): string[];
     /**
      * Count occurrences of each tool
      *
@@ -590,7 +1149,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static getToolFrequency(llmResult: LLMLoopResult$1): Record<string, number>;
+    static getToolFrequency(llmResult: LLMLoopResult): Record<string, number>;
     /**
      * Check if specific tool was called
      *
@@ -603,7 +1162,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static hasToolCall(llmResult: LLMLoopResult$1, name: string): boolean;
+    static hasToolCall(llmResult: LLMLoopResult, name: string): boolean;
     /**
      * Check if any tool matching filter was called
      *
@@ -619,7 +1178,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static hasToolCallWhere(llmResult: LLMLoopResult$1, filter: ToolCallFilter): boolean;
+    static hasToolCallWhere(llmResult: LLMLoopResult, filter: ToolCallFilter): boolean;
     /**
      * Get content length
      *
@@ -632,7 +1191,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static getContentLength(llmResult: LLMLoopResult$1): number;
+    static getContentLength(llmResult: LLMLoopResult): number;
     /**
      * Count successful tool calls
      *
@@ -649,7 +1208,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static countSuccessfulCalls(llmResult: LLMLoopResult$1): number;
+    static countSuccessfulCalls(llmResult: LLMLoopResult): number;
     /**
      * Count failed tool calls
      *
@@ -666,7 +1225,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static countFailedCalls(_llmResult: LLMLoopResult$1): number;
+    static countFailedCalls(_llmResult: LLMLoopResult): number;
     /**
      * Get tool call arguments
      *
@@ -685,7 +1244,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static getToolArguments(llmResult: LLMLoopResult$1, name: string): any[];
+    static getToolArguments(llmResult: LLMLoopResult, name: string): any[];
     /**
      * Get first tool call matching name
      *
@@ -704,7 +1263,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static findToolCall(llmResult: LLMLoopResult$1, name: string): any | null;
+    static findToolCall(llmResult: LLMLoopResult, name: string): any | null;
     /**
      * Get all tool calls matching filter
      *
@@ -723,7 +1282,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static filterToolCalls(llmResult: LLMLoopResult$1, filter: ToolCallFilter): any[];
+    static filterToolCalls(llmResult: LLMLoopResult, filter: ToolCallFilter): any[];
     /**
      * Check if content contains text
      *
@@ -736,7 +1295,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static contentContains(llmResult: LLMLoopResult$1, text: string): boolean;
+    static contentContains(llmResult: LLMLoopResult, text: string): boolean;
     /**
      * Check if content matches regex
      *
@@ -749,7 +1308,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static contentMatches(llmResult: LLMLoopResult$1, regex: RegExp): boolean;
+    static contentMatches(llmResult: LLMLoopResult, regex: RegExp): boolean;
     /**
      * Calculate success rate
      *
@@ -762,7 +1321,7 @@ declare class ObserveUtils {
      * </Observe>
      * ```
      */
-    static getSuccessRate(llmResult: LLMLoopResult$1): number;
+    static getSuccessRate(llmResult: LLMLoopResult): number;
 }
 
 /**
@@ -799,7 +1358,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractJSON<T = any>(llmResult: LLMLoopResult$1): T;
+    static extractJSON<T = any>(llmResult: LLMLoopResult): T;
     /**
      * Extract JSON with Zod schema validation
      *
@@ -818,7 +1377,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractWithSchema<T extends z.ZodType>(llmResult: LLMLoopResult$1, schema: T): z.infer<T>;
+    static extractWithSchema<T extends z.ZodType>(llmResult: LLMLoopResult, schema: T): z.infer<T>;
     /**
      * Extract from specific tool call result
      *
@@ -835,7 +1394,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractFromToolCall(llmResult: LLMLoopResult$1, toolName: string): any;
+    static extractFromToolCall(llmResult: LLMLoopResult, toolName: string): any;
     /**
      * Extract text content (no JSON parsing)
      *
@@ -848,7 +1407,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractText(llmResult: LLMLoopResult$1): string;
+    static extractText(llmResult: LLMLoopResult): string;
     /**
      * Extract code block by language
      *
@@ -861,7 +1420,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractCodeBlock(llmResult: LLMLoopResult$1, language?: string): string;
+    static extractCodeBlock(llmResult: LLMLoopResult, language?: string): string;
     /**
      * Extract all code blocks
      *
@@ -874,7 +1433,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractAllCodeBlocks(llmResult: LLMLoopResult$1): Array<{
+    static extractAllCodeBlocks(llmResult: LLMLoopResult): Array<{
         language: string | null;
         code: string;
     }>;
@@ -894,7 +1453,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static tryExtract<T = any>(llmResult: LLMLoopResult$1, extractors: Array<(result: LLMLoopResult$1) => T>): T;
+    static tryExtract<T = any>(llmResult: LLMLoopResult, extractors: Array<(result: LLMLoopResult) => T>): T;
     /**
      * Normalize partial data with defaults
      *
@@ -952,7 +1511,7 @@ declare class ResultUtils {
      * </Result>
      * ```
      */
-    static extractAndValidate<T>(llmResult: LLMLoopResult$1, extractor: (result: LLMLoopResult$1) => T, validator: (data: T) => T): T;
+    static extractAndValidate<T>(llmResult: LLMLoopResult, extractor: (result: LLMLoopResult) => T, validator: (data: T) => T): T;
     /**
      * Merge observed data with extracted output
      *
@@ -1382,6 +1941,48 @@ declare class RetryUtils {
     };
 }
 
+/**
+ * JSX Type Helpers
+ *
+ * Helper functions to convert JSX elements to their specific AST node types.
+ * This avoids the need for manual type assertions in user code.
+ */
+
+/**
+ * Convert a JSX Workflow element to WorkflowNode type
+ *
+ * This is a type-safe helper that avoids manual type assertions.
+ *
+ * @example
+ * ```tsx
+ * const workflow = toWorkflow(
+ *   <Workflow name="my-workflow">
+ *     <Sequence>
+ *       <Agent1 />
+ *       <Agent2 />
+ *     </Sequence>
+ *   </Workflow>
+ * );
+ *
+ * // No need for: as unknown as WorkflowNode
+ * await runTSXWorkflow(workflow, inputs);
+ * ```
+ */
+declare function toWorkflow(element: ASTNode): WorkflowNode;
+/**
+ * Convert a JSX Agent element to AgentNode type
+ *
+ * @example
+ * ```tsx
+ * const agent = toAgent(
+ *   <Agent id="test" input={schema} output={schema}>
+ *     <Prompt>...</Prompt>
+ *   </Agent>
+ * );
+ * ```
+ */
+declare function toAgent<I = unknown, O = unknown>(element: ASTNode): AgentNode<I, O>;
+
 /**
  * Deity TSX - Preflight Checker
  *
@@ -1633,7 +2234,7 @@ interface FullAgentTestOptions<I = unknown> {
     /** Inputs for the agent */
     inputs: I;
     /** Mock LLM loop result */
-    llmResult: Partial<LLMLoopResult$1>;
+    llmResult: Partial<LLMLoopResult>;
 }
 /**
  * Full Agent Test Result
@@ -1798,7 +2399,7 @@ interface ComponentExecutionResult<O> {
     /** Total attempts made */
     attempts: number;
     /** LLM loop results from all attempts */
-    llmResults: LLMLoopResult$1[];
+    llmResults: LLMLoopResult[];
     /** Retry execution result */
     retryResult: RetryExecutionResult<O>;
     /** Execution duration (ms) */
@@ -1815,7 +2416,7 @@ interface ComponentExecutionResult<O> {
  * 5. Retry if needed
  * 6. UI updates (if bridge available)
  */
-declare function executeComponent<I, O>(component: AgentComponent<I, O>, ctx: ExecutionContext$1<I>, adapter: LLMAdapter, config?: GenerationConfig): Promise<ComponentExecutionResult<O>>;
+declare function executeComponent<I, O>(component: AgentComponent<I, O>, ctx: ExecutionContext$1<I>, adapter: LLMAdapter$1, config?: GenerationConfig$1): Promise<ComponentExecutionResult<O>>;
 
 /**
  * Deity 4.0 - LLM Execution Loop
@@ -1875,7 +2476,7 @@ interface LLMLoopConfig {
  * @param loopConfig - Loop configuration
  * @param validator - Optional validator for loop convergence
  */
-declare function executeLLMLoop(adapter: LLMAdapter, initialMessages: Message[], tools: Tool[] | undefined, config: GenerationConfig | undefined, ctx: ExecutionContext$1, loopConfig?: LLMLoopConfig, validator?: Validator): Promise<LLMLoopResult$1>;
+declare function executeLLMLoop(adapter: LLMAdapter$1, initialMessages: Message[], tools: ToolSpec[] | undefined, config: GenerationConfig$1 | undefined, ctx: ExecutionContext$1, loopConfig?: LLMLoopConfig, validator?: Validator): Promise<LLMLoopResult>;
 
 /**
  * Deity 4.0 - Workflow Runner
@@ -1887,6 +2488,64 @@ declare function executeLLMLoop(adapter: LLMAdapter, initialMessages: Message[],
  * Execute a workflow
  */
 declare function runWorkflow<I, O>(config: WorkflowConfig, inputs: I): Promise<O>;
+/**
+ * Execute a TSX workflow
+ *
+ * Convenience function that compiles a WorkflowNode AST and executes it.
+ * This is the recommended way to run TSX-defined workflows.
+ *
+ * @param workflowAST - Workflow AST node (created by Workflow component)
+ * @param inputs - Workflow inputs
+ * @returns Workflow output
+ *
+ * @example
+ * ```typescript
+ * const workflow = Workflow({
+ *   name: 'my-workflow',
+ *   defaultModel: { adapter: llmAdapter },
+ *   children: Sequence({
+ *     children: [Agent1, Agent2, Agent3]
+ *   })
+ * });
+ *
+ * const result = await runTSXWorkflow(workflow, { input: 'data' });
+ * ```
+ *
+ * @example With enhancements
+ * ```typescript
+ * const workflow = Workflow({
+ *   name: 'enhanced-workflow',
+ *   defaultModel: { adapter: llmAdapter },
+ *   enhancements: {
+ *     conversation: { maxTokens: 8000, pruneThreshold: 6000 },
+ *     memory: { coreBudget: { maxItems: 10, maxTotalSize: 8192 } }
+ *   },
+ *   children: MyAgent
+ * });
+ *
+ * const result = await runTSXWorkflow(workflow, inputs);
+ * ```
+ */
+declare function runTSXWorkflow<I, O>(workflowAST: WorkflowNode, inputs: I): Promise<O>;
+/**
+ * Result from ForEach execution with error tracking
+ */
+interface ForEachResult {
+    /** Results from successful iterations */
+    results: unknown[];
+    /** Errors from failed iterations (when errorMode='continue' or 'skip') */
+    errors: Array<{
+        index: number;
+        item: unknown;
+        error: Error;
+    }>;
+    /** Total items processed */
+    totalItems: number;
+    /** Successfully processed count */
+    successCount: number;
+    /** Failed iterations count */
+    failureCount: number;
+}
 /**
  * Create a simple step node
  */
@@ -1917,7 +2576,7 @@ declare function createLoopNode(child: ExecutionNode, maxIterations: number): Ex
 /**
  * Simple in-memory state store
  */
-declare class InMemoryStore implements StateStore {
+declare class InMemoryStore implements StateStore$1 {
     private data;
     get(key: string): Promise<unknown>;
     set(key: string, value: unknown): Promise<void>;
@@ -1926,6 +2585,8 @@ declare class InMemoryStore implements StateStore {
     clear(): Promise<void>;
     size(): number;
     keys(): string[];
+    entries(): [string, unknown][];
+    values(): unknown[];
 }
 /**
  * Simple in-memory trace logger
@@ -1939,103 +2600,6 @@ declare class InMemoryTrace implements TraceLogger {
     getEntriesByType(type: TraceEntry['type']): TraceEntry[];
 }
 
-/**
- * Tool Result Extractor
- *
- * Utilities for extracting tool call results from LLM loop results.
- * Simplifies common patterns in Agent extractOutput implementations.
- */
-
-/**
- * LLM Loop Result (subset needed for extraction)
- */
-interface LLMLoopResult {
-    messages: Message[];
-    response: {
-        content: string;
-        toolCalls?: any[];
-    };
-    [key: string]: any;
-}
-/**
- * Extract options
- */
-interface ExtractOptions {
-    /** Auto unwrap { success, data } format (default: true) */
-    unwrap?: boolean;
-    /** Throw error if tool not called (default: true) */
-    required?: boolean;
-    /** Only return successful calls (for { success: boolean } format) */
-    filterSuccess?: boolean;
-}
-/**
- * Extract last tool call result
- *
- * Uses a two-tier extraction strategy:
- * 1. First checks llmResult.response.toolCalls array (priority 1)
- * 2. Falls back to messages array filtering (priority 2)
- *
- * This supports adapters that track tool calls via hooks (e.g., Copilot SDK)
- * while maintaining backward compatibility with message-based extraction.
- *
- * @param llmResult - LLM loop result
- * @param toolName - Target tool name
- * @param options - Extraction options
- * @returns Parsed tool result or null if not found
- * @throws Error if tool not called and required=true
- *
- * @example
- * // Extract from toolCalls array
- * const plan = extractLastToolResult<Plan>(llmResult, 'planning_create');
- *
- * @example
- * // Extract with fallback to messages
- * const result = extractLastToolResult<Result>(llmResult, 'analyze', {
- *   unwrap: false,
- *   required: false
- * });
- */
-declare function extractLastToolResult<T = unknown>(llmResult: LLMLoopResult, toolName: string, options?: ExtractOptions): T | null;
-/**
- * Extract all tool call results
- *
- * Uses a two-tier extraction strategy:
- * 1. First checks llmResult.response.toolCalls array (priority 1)
- * 2. Falls back to messages array filtering (priority 2)
- *
- * This supports adapters that track tool calls via hooks (e.g., Copilot SDK)
- * while maintaining backward compatibility with message-based extraction.
- *
- * @param llmResult - LLM loop result
- * @param toolName - Target tool name
- * @param options - Extraction options
- * @returns Array of parsed results
- *
- * @example
- * // Extract all analyze_file calls
- * const results = extractAllToolResults<FileAnalysis>(llmResult, 'analyze_file');
- *
- * @example
- * // Filter only successful results
- * const successful = extractAllToolResults<Result>(llmResult, 'process', {
- *   filterSuccess: true
- * });
- */
-declare function extractAllToolResults<T = unknown>(llmResult: LLMLoopResult, toolName: string, options?: ExtractOptions): T[];
-/**
- * Count tool calls
- *
- * Uses a two-tier counting strategy:
- * 1. First checks llmResult.response.toolCalls array (priority 1)
- * 2. Falls back to messages array filtering (priority 2)
- *
- * @param llmResult - LLM loop result
- * @param toolName - Target tool name
- * @param filter - Optional filter function
- * @returns Number of tool calls
- */
-declare function countToolCalls(llmResult: LLMLoopResult, toolName: string, filter?: (result: any) => boolean): number;
-
 /**
  * Deity 4.0 - Enhanced Execution Context
  *
@@ -2063,7 +2627,7 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
     /** Outputs from previous stages */
     readonly previousOutputs: Record<string, unknown>;
     /** State store for persistence */
-    readonly store: StateStore;
+    readonly store: StateStore$1;
     /** Trace logger for observability */
     readonly trace: TraceLogger;
     /** Execution statistics */
@@ -2084,17 +2648,20 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
     readonly ui?: UIUpdateBridge;
     /** Session store (optional) */
     readonly session?: SessionStore;
+    /** Application state store (optional, isolated from AI memory) */
+    readonly appState?: StateStore$1;
     /** Current stage ID (for UI updates) */
     currentStageId?: string;
     constructor(params: {
         inputs: I;
         previousOutputs?: Record<string, unknown>;
-        store: StateStore;
+        store: StateStore$1;
         trace: TraceLogger;
         stats: ExecutionStats;
         conversation?: ConversationManager;
         memory?: LimoMemoryManager;
         session?: SessionStore;
+        appState?: StateStore$1;
         ui?: UIUpdateBridge;
         currentStageId?: string;
         iteration?: number;
@@ -2133,6 +2700,10 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
      * Update iteration info (for loops)
      */
     withIteration(iteration: number, maxIterations: number): ExecutionContext<I>;
+    /**
+     * Update inputs (for ForEach iterations)
+     */
+    withInputs<NewI = I>(inputs: NewI): ExecutionContext<NewI>;
     /**
      * Add to iteration history
      */
@@ -2153,6 +2724,10 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
      * Check if UI is enabled
      */
     hasUI(): boolean;
+    /**
+     * Check if appState is enabled
+     */
+    hasAppState(): boolean;
     /**
      * Get conversation manager (throws if not available)
      */
@@ -2169,6 +2744,10 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
      * Get UI bridge (throws if not available)
      */
     requireUI(): UIUpdateBridge;
+    /**
+     * Get application state store (throws if not available)
+     */
+    requireAppState(): StateStore$1;
     /**
      * Get context summary for debugging
      */
@@ -2182,6 +2761,7 @@ declare class ExecutionContext<I = unknown> implements ExecutionContext$1<I> {
             memory: boolean;
             session: boolean;
             ui: boolean;
+            appState: boolean;
         };
         stats: ExecutionStats;
     };
@@ -2206,7 +2786,7 @@ interface ContextConfig<I = unknown> {
     /** Previous stage outputs */
     previousOutputs?: Record<string, unknown>;
     /** State store (required) */
-    store: StateStore;
+    store: StateStore$1;
     /** Trace logger (required) */
     trace: TraceLogger;
     /** Execution stats (optional, will create if not provided) */
@@ -2217,6 +2797,8 @@ interface ContextConfig<I = unknown> {
     enableMemory?: boolean | MemoryConfig;
     /** Enable session store */
     enableSession?: boolean | SessionConfig;
+    /** Enable application state store (isolated from AI memory) */
+    enableAppState?: boolean | StateStore$1;
     /** UI update bridge */
     ui?: UIUpdateBridge;
     /** Current stage ID */
@@ -2233,35 +2815,4 @@ interface ContextConfig<I = unknown> {
  */
 declare function createEnhancedContext<I = unknown>(config: ContextConfig<I>): Promise<ExecutionContext<I>>;
 
-/**
- * Deity Built-in Memory Tools
- *
- * Provides out-of-the-box memory management tools that applications can use
- * without implementing their own memory storage/retrieval logic.
- */
-
-/**
- * Create built-in memory management tools
- *
- * These tools integrate with Deity's LimoMemoryManager to provide:
- * - Automatic tiered storage (core vs detailed)
- * - Relevance-based retrieval
- * - Automatic promotion/demotion of memories
- *
- * @param ctx ExecutionContext with memory enabled
- * @returns Array of memory tools (memory_store, memory_recall)
- *
- * @example
- * ```typescript
- * const ctx = await createEnhancedContext({
- *   inputs: { task: "..." },
- *   enableMemory: true
- * });
- *
- * const memoryTools = createMemoryTools(ctx);
- * const allTools = [...memoryTools, ...myCustomTools];
- * ```
- */
-declare function createMemoryTools(ctx: ExecutionContext): Tool[];
-
-export { Agent, AgentComponent, AgentNode, type AgentProps, DEBUG_ENABLED, DebugLogger, ExecutionContext$1 as ExecutionContext, type FullAgentTestOptions, type FullAgentTestResult, GenerationConfig, InMemoryStore, InMemoryTrace, LLMAdapter, type LLMLoopConfig, LLMLoopResult$1 as LLMLoopResult, type LogLevel, Message, Observe, type ObserveFunction, ObserveNode, type ObserveProps, ObserveUtils, PreflightChecker, type PreflightResult, Prompt, PromptNode, type PromptProps, PromptResourceLoader, Result, ResultNode, type ResultProps, ResultUtils, Retry, type RetryContext, RetryNode, type RetryProps, RetryUtils, StateStore, System, SystemNode, type SystemProps, Tool, TraceLogger, User, UserNode, type UserProps, Validate, ValidateNode, type ValidateProps, ValidateUtils, type ValidationResult, ValidationRules, Validator, compileAgent, countToolCalls, createConditionalNode, createEnhancedContext, createLoopNode, createMemoryTools, createParallelNode, createSequenceNode, createStepNode, executeComponent, executeLLMLoop, extractAllToolResults, extractLastToolResult, getResourceLoader, logger, preflight, runWorkflow, setResourceLoader, testFullAgent };
+export { ASTNode, Agent, AgentComponent, AgentNode, type AgentProps, Conditional, type ConditionalProps, DEBUG_ENABLED, DebugLogger, type ErrorMode, ExecutionContext$1 as ExecutionContext, ForEach, type ForEachProps, type ForEachResult, type FullAgentTestOptions, type FullAgentTestResult, GenerationConfig$1 as GenerationConfig, InMemoryStore, InMemoryTrace, type ItemMode, LLMAdapter$1 as LLMAdapter, type LLMLoopConfig, LLMLoopResult, type LogLevel, Loop, type LoopProps, Message, Observe, type ObserveFunction, ObserveNode, type ObserveProps, ObserveUtils, Parallel, type ParallelProps, PreflightChecker, type PreflightResult, Prompt, PromptNode, type PromptProps, PromptResourceLoader, Result, ResultNode, type ResultProps, ResultUtils, Retry, type RetryContext, RetryNode, type RetryProps, RetryUtils, Sequence, type SequenceProps, StateStore$1 as StateStore, System, SystemNode, type SystemProps, Tool, ToolDef, ToolDefNode, type ToolDefProps, type ToolProps, ToolRef, ToolRefNode, type ToolRefProps, type ToolRefTarget, ToolSpec, Tools, ToolsNode, type ToolsProps, TraceLogger, User, UserNode, type UserProps, Validate, ValidateNode, type ValidateProps, ValidateUtils, type ValidationResult, ValidationRules, Validator, Workflow, WorkflowChildNode, WorkflowConditionalNode, type WorkflowEnhancements, WorkflowForEachNode, type GenerationConfig as WorkflowGenerationConfig, type LLMAdapter as WorkflowLLMAdapter, WorkflowLoopNode, WorkflowNode, WorkflowParallelNode, type WorkflowProps, WorkflowSequenceNode, type StateStore as WorkflowStateStore, compileAgent, compileWorkflow, compileWorkflowNode, createConditionalNode, createEnhancedContext, createLoopNode, createParallelNode, createSequenceNode, createStepNode, executeComponent, executeLLMLoop, getResourceLoader, logger, preflight, runTSXWorkflow, runWorkflow, setResourceLoader, testFullAgent, toAgent, toWorkflow };