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

package/dist/index.js

@@ -42,7 +42,7 @@ var init_compile_observe = __esm({
 
 // src/components/Agent.tsx
 function Agent(props) {
-  const { id, input, output, description, tags, loopValidator, loopConfig, tools, children } = props;
+  const { id, input, output, description, tags, loopValidator, loopConfig, tools: propsTools, children } = props;
   if (!id) {
     throw new Error("Agent: id is required");
   }
@@ -55,9 +55,11 @@ function Agent(props) {
   if (!children || children.length === 0) {
     throw new Error("Agent: must have at least Prompt and Result children");
   }
-  const [prompt, ...rest] = children;
+  const toolsNode = children.find((child) => child?.type === "Tools");
+  const nonToolsChildren = children.filter((child) => child?.type !== "Tools");
+  const [prompt, ...rest] = nonToolsChildren;
   if (!prompt || prompt.type !== "Prompt") {
-    throw new Error("Agent: first child must be a Prompt component");
+    throw new Error("Agent: first non-Tools child must be a Prompt component");
   }
   const result = rest.find((child) => child?.type === "Result");
   if (!result) {
@@ -66,6 +68,7 @@ function Agent(props) {
   const observe = rest.find((child) => child?.type === "Observe");
   const validate = rest.find((child) => child?.type === "Validate");
   const retry = rest.find((child) => child?.type === "Retry");
+  const mergedTools = mergeTools(propsTools, toolsNode);
   const orderedChildren = [
     prompt
   ];
@@ -73,6 +76,7 @@ function Agent(props) {
   orderedChildren.push(result);
   if (validate) orderedChildren.push(validate);
   if (retry) orderedChildren.push(retry);
+  if (toolsNode) orderedChildren.push(toolsNode);
   return {
     type: "Agent",
     props: {
@@ -83,11 +87,24 @@ function Agent(props) {
       tags,
       loopValidator,
       loopConfig,
-      tools
+      tools: mergedTools
     },
     children: orderedChildren
   };
 }
+function mergeTools(propsTools, toolsNode) {
+  if (!propsTools && !toolsNode) {
+    return void 0;
+  }
+  const staticToolsFromNode = toolsNode ? (toolsNode.children || []).filter((child) => child?.type === "Tools:Def" && child.props?.tool).map((child) => child.props.tool) : [];
+  if (!toolsNode) {
+    return propsTools;
+  }
+  if (!propsTools) {
+    return staticToolsFromNode.length > 0 ? staticToolsFromNode : void 0;
+  }
+  return [...propsTools, ...staticToolsFromNode];
+}
 
 // src/components/Prompt.tsx
 function Prompt(props) {
@@ -135,6 +152,40 @@ function System(props) {
       if (children.length === 0) {
         throw new Error("System: children array is empty");
       }
+      const hasToolRef = children.some(
+        (child) => typeof child === "object" && child !== null && "type" in child && child.type === "ToolRef"
+      );
+      if (hasToolRef) {
+        const parts = [];
+        for (const child of children) {
+          if (typeof child === "object" && child !== null && "type" in child) {
+            const node = child;
+            if (node.type === "Text" && node.props?.content) {
+              parts.push({ kind: "text", value: node.props.content });
+            } else if (node.type === "ComputedText" && node.props?.compute) {
+              parts.push({ kind: "computed", compute: node.props.compute });
+            } else if (node.type === "ToolRef" && node.props?.toolName) {
+              parts.push({ kind: "toolref", toolName: node.props.toolName });
+            } else {
+              throw new Error(`System: invalid child type in template mode: ${node.type}`);
+            }
+          } else if (typeof child === "string") {
+            parts.push({ kind: "text", value: child });
+          } else if (typeof child === "function") {
+            parts.push({ kind: "computed", compute: child });
+          } else {
+            throw new Error("System: invalid child in template mode");
+          }
+        }
+        return {
+          type: "System",
+          props: {
+            source,
+            required,
+            templateParts: parts
+          }
+        };
+      }
       if (children.length > 1) {
         throw new Error("System: can only have one child");
       }
@@ -191,6 +242,38 @@ function User(props) {
       if (children.length === 0) {
         throw new Error("User: children array is empty");
       }
+      const hasToolRef = children.some(
+        (child) => typeof child === "object" && child !== null && "type" in child && child.type === "ToolRef"
+      );
+      if (hasToolRef) {
+        const parts = [];
+        for (const child of children) {
+          if (typeof child === "object" && child !== null && "type" in child) {
+            const node = child;
+            if (node.type === "Text" && node.props?.content) {
+              parts.push({ kind: "text", value: node.props.content });
+            } else if (node.type === "ComputedText" && node.props?.compute) {
+              parts.push({ kind: "computed", compute: node.props.compute });
+            } else if (node.type === "ToolRef" && node.props?.toolName) {
+              parts.push({ kind: "toolref", toolName: node.props.toolName });
+            } else {
+              throw new Error(`User: invalid child type in template mode: ${node.type}`);
+            }
+          } else if (typeof child === "string") {
+            parts.push({ kind: "text", value: child });
+          } else if (typeof child === "function") {
+            parts.push({ kind: "computed", compute: child });
+          } else {
+            throw new Error("User: invalid child in template mode");
+          }
+        }
+        return {
+          type: "User",
+          props: {
+            templateParts: parts
+          }
+        };
+      }
       if (children.length > 1) {
         throw new Error("User: can only have one child");
       }
@@ -374,6 +457,241 @@ function Retry(props = {}) {
     }
   };
 }
+
+// src/components/Tools.tsx
+function Tools(props) {
+  const { children } = props;
+  const toolDefs = (children || []).filter(
+    (child) => child?.type === "Tools:Def"
+  );
+  return {
+    type: "Tools",
+    props: {},
+    children: toolDefs
+  };
+}
+function ToolDef(props) {
+  return {
+    type: "Tools:Def",
+    props: { tool: props.tool }
+  };
+}
+function Tool(props) {
+  const { name, description, input, execute, children } = props;
+  if (!name) {
+    throw new Error("Tool: name is required");
+  }
+  if (!description) {
+    throw new Error("Tool: description is required");
+  }
+  if (!input) {
+    throw new Error("Tool: input schema is required");
+  }
+  let executeFn;
+  if (children) {
+    if (execute) {
+      throw new Error("Tool: cannot use both children and execute prop");
+    }
+    let actualChild = children;
+    if (Array.isArray(children)) {
+      if (children.length === 0) {
+        throw new Error("Tool: children array is empty");
+      }
+      if (children.length > 1) {
+        throw new Error("Tool: can only have one child (the execute function)");
+      }
+      actualChild = children[0];
+    }
+    if (typeof actualChild === "object" && actualChild !== null && "type" in actualChild) {
+      const node = actualChild;
+      if (node.type === "ComputedText" && node.props?.compute) {
+        executeFn = node.props.compute;
+      } else {
+        throw new Error("Tool: invalid child node type (expected ComputedText with execute function)");
+      }
+    } else if (typeof actualChild === "function") {
+      executeFn = actualChild;
+    } else {
+      throw new Error("Tool: children must be a function");
+    }
+  } else if (execute) {
+    executeFn = execute;
+  } else {
+    throw new Error("Tool: must provide children (execute function) or execute prop");
+  }
+  const toolSpec = {
+    name,
+    description,
+    inputSchema: input,
+    execute: executeFn
+  };
+  return {
+    type: "Tools:Def",
+    props: { tool: toolSpec }
+  };
+}
+
+// src/components/ToolRef.tsx
+function ToolRef(props) {
+  const { tool } = props;
+  let toolName;
+  if (tool === null || tool === void 0) {
+    throw new Error(
+      "ToolRef: `tool` prop must be a tool component with .toolName, a ToolSpec with .name, or a string tool ID"
+    );
+  }
+  if (typeof tool === "string") {
+    toolName = tool;
+  } else if (typeof tool === "function" && "toolName" in tool && typeof tool.toolName === "string") {
+    toolName = tool.toolName;
+  } else if (typeof tool === "object" && "toolName" in tool && typeof tool.toolName === "string") {
+    toolName = tool.toolName;
+  } else if (typeof tool === "object" && "name" in tool && typeof tool.name === "string") {
+    toolName = tool.name;
+  } else {
+    throw new Error(
+      "ToolRef: `tool` prop must be a tool component with .toolName, a ToolSpec with .name, or a string tool ID"
+    );
+  }
+  return {
+    type: "ToolRef",
+    props: { toolName }
+  };
+}
+
+// src/components/Sequence.tsx
+function Sequence(props) {
+  const { children } = props;
+  if (!children || children.length === 0) {
+    throw new Error("Sequence: must have at least one child");
+  }
+  return {
+    type: "WorkflowSequence",
+    children
+  };
+}
+
+// src/components/Parallel.tsx
+function Parallel(props) {
+  const { children } = props;
+  if (!children || children.length === 0) {
+    throw new Error("Parallel: must have at least one child");
+  }
+  return {
+    type: "WorkflowParallel",
+    children
+  };
+}
+
+// src/components/Conditional.tsx
+function Conditional(props) {
+  const { condition, children } = props;
+  if (!condition) {
+    throw new Error("Conditional: condition prop is required");
+  }
+  if (!children) {
+    throw new Error("Conditional: must have at least one child (true branch)");
+  }
+  if (children.length < 1 || children.length > 2) {
+    throw new Error("Conditional: must have 1-2 children (true branch required, false branch optional)");
+  }
+  return {
+    type: "WorkflowConditional",
+    props: {
+      condition
+    },
+    children
+  };
+}
+
+// src/components/Loop.tsx
+function Loop(props) {
+  const { iterations, children } = props;
+  if (!iterations || iterations < 1) {
+    throw new Error("Loop: iterations must be >= 1");
+  }
+  if (!children) {
+    throw new Error("Loop: must have exactly one child");
+  }
+  const childArray = Array.isArray(children) ? children : [children];
+  if (childArray.length !== 1) {
+    throw new Error("Loop: must have exactly one child");
+  }
+  return {
+    type: "WorkflowLoop",
+    props: {
+      iterations
+    },
+    children: [childArray[0]]
+  };
+}
+
+// src/components/ForEach.tsx
+function ForEach(props) {
+  const {
+    items,
+    itemMode = "property",
+    itemKey = "currentItem",
+    errorMode = "stop",
+    collectResults = true,
+    children
+  } = props;
+  if (!items) {
+    throw new Error("ForEach: items prop is required");
+  }
+  if (!children) {
+    throw new Error("ForEach: must have exactly one child");
+  }
+  const childArray = Array.isArray(children) ? children : [children];
+  if (childArray.length !== 1) {
+    throw new Error("ForEach: must have exactly one child");
+  }
+  const validModes = ["merge", "replace", "property"];
+  if (!validModes.includes(itemMode)) {
+    throw new Error(`ForEach: itemMode must be one of: ${validModes.join(", ")}`);
+  }
+  const validErrorModes = ["stop", "continue", "skip"];
+  if (!validErrorModes.includes(errorMode)) {
+    throw new Error(`ForEach: errorMode must be one of: ${validErrorModes.join(", ")}`);
+  }
+  return {
+    type: "WorkflowForEach",
+    props: {
+      items,
+      itemMode,
+      itemKey,
+      errorMode,
+      collectResults
+    },
+    children: [childArray[0]]
+  };
+}
+
+// src/components/Workflow.tsx
+function Workflow(props) {
+  const { name, description, defaultModel, state, enhancements, children } = props;
+  if (!name) {
+    throw new Error("Workflow: name is required");
+  }
+  if (!children) {
+    throw new Error("Workflow: must have exactly one child (workflow graph)");
+  }
+  const childArray = Array.isArray(children) ? children : [children];
+  if (childArray.length !== 1) {
+    throw new Error("Workflow: must have exactly one child (workflow graph)");
+  }
+  return {
+    type: "Workflow",
+    props: {
+      name,
+      description,
+      defaultModel,
+      state,
+      enhancements
+    },
+    children: [childArray[0]]
+  };
+}
 var PromptResourceLoader = class {
   cache = /* @__PURE__ */ new Map();
   options;
@@ -583,7 +901,25 @@ function compilePrompt(promptNode) {
   };
 }
 async function resolveSystemContent(node, ctx) {
-  const { source, content, compute, required = false } = node.props;
+  const { source, content, compute, required = false, templateParts } = node.props;
+  if (templateParts) {
+    const resolved = await Promise.all(
+      templateParts.map(async (part) => {
+        switch (part.kind) {
+          case "text":
+            return part.value;
+          case "computed":
+            return await Promise.resolve(part.compute(ctx));
+          case "toolref":
+            return part.toolName;
+          default:
+            const _exhaustive = part;
+            throw new Error(`Unknown template part kind: ${_exhaustive.kind}`);
+        }
+      })
+    );
+    return resolved.join("");
+  }
   if (source) {
     if (!source.startsWith("file:")) {
       throw new Error(`Invalid source format: ${source} (must start with "file:")`);
@@ -604,17 +940,35 @@ async function resolveSystemContent(node, ctx) {
   if (compute) {
     return await Promise.resolve(compute(ctx));
   }
-  throw new Error("System node must have source, content, or compute");
+  throw new Error("System node must have source, content, compute, or templateParts");
 }
 async function resolveUserContent(node, ctx) {
-  const { content, compute } = node.props;
+  const { content, compute, templateParts } = node.props;
+  if (templateParts) {
+    const resolved = await Promise.all(
+      templateParts.map(async (part) => {
+        switch (part.kind) {
+          case "text":
+            return part.value;
+          case "computed":
+            return await Promise.resolve(part.compute(ctx));
+          case "toolref":
+            return part.toolName;
+          default:
+            const _exhaustive = part;
+            throw new Error(`Unknown template part kind: ${_exhaustive.kind}`);
+        }
+      })
+    );
+    return resolved.join("");
+  }
   if (content !== void 0) {
     return content;
   }
   if (compute) {
     return await Promise.resolve(compute(ctx));
   }
-  throw new Error("User node must have content or compute");
+  throw new Error("User node must have content, compute, or templateParts");
 }
 
 // src/compiler/compile-agent.ts
@@ -744,6 +1098,184 @@ function compileAgent(ast) {
 // src/compiler/index.ts
 init_compile_observe();
 
+// src/compiler/compile-workflow-node.ts
+function compileWorkflowNode(node) {
+  switch (node.type) {
+    case "Agent":
+      return compileAgentNode(node);
+    case "WorkflowSequence":
+      return compileSequenceNode(node);
+    case "WorkflowParallel":
+      return compileParallelNode(node);
+    case "WorkflowConditional":
+      return compileConditionalNode(node);
+    case "WorkflowLoop":
+      return compileLoopNode(node);
+    case "WorkflowForEach":
+      return compileForEachNode(node);
+    default:
+      throw new Error(`Unknown workflow node type: ${node.type}`);
+  }
+}
+function compileAgentNode(node) {
+  const lazyComponent = createLazyAgentComponent(node);
+  return {
+    type: "step",
+    component: lazyComponent
+  };
+}
+function compileSequenceNode(node) {
+  if (!node.children || node.children.length === 0) {
+    throw new Error("Sequence node must have children");
+  }
+  const children = node.children.map((child) => compileWorkflowNode(child));
+  return {
+    type: "sequence",
+    children
+  };
+}
+function compileParallelNode(node) {
+  if (!node.children || node.children.length === 0) {
+    throw new Error("Parallel node must have children");
+  }
+  const children = node.children.map((child) => compileWorkflowNode(child));
+  return {
+    type: "parallel",
+    children
+  };
+}
+function compileConditionalNode(node) {
+  if (!node.props?.condition) {
+    throw new Error("Conditional node must have a condition function");
+  }
+  if (!node.children || node.children.length < 1 || node.children.length > 2) {
+    throw new Error("Conditional node must have 1-2 children (true branch required, false branch optional)");
+  }
+  const children = node.children.map((child) => compileWorkflowNode(child));
+  return {
+    type: "conditional",
+    condition: node.props.condition,
+    children
+  };
+}
+function compileLoopNode(node) {
+  if (!node.props?.iterations || node.props.iterations < 1) {
+    throw new Error("Loop node must have iterations >= 1");
+  }
+  if (!node.children || node.children.length !== 1) {
+    throw new Error("Loop node must have exactly one child");
+  }
+  const child = compileWorkflowNode(node.children[0]);
+  return {
+    type: "loop",
+    maxIterations: node.props.iterations,
+    children: [child]
+  };
+}
+function compileForEachNode(node) {
+  if (!node.props?.items) {
+    throw new Error("ForEach node must have items prop");
+  }
+  if (!node.children || node.children.length !== 1) {
+    throw new Error("ForEach node must have exactly one child");
+  }
+  const child = compileWorkflowNode(node.children[0]);
+  return {
+    type: "foreach",
+    itemsAccessor: node.props.items,
+    itemMode: node.props.itemMode,
+    itemKey: node.props.itemKey,
+    errorMode: node.props.errorMode,
+    collectResults: node.props.collectResults,
+    children: [child]
+  };
+}
+function createLazyAgentComponent(astNode) {
+  let compiled = null;
+  const ensureCompiled = () => {
+    if (!compiled) {
+      compiled = compileAgent(astNode);
+    }
+    return compiled;
+  };
+  const proxy = {
+    get id() {
+      return astNode.props.id;
+    },
+    get inputSchema() {
+      return astNode.props.input;
+    },
+    get outputSchema() {
+      return astNode.props.output;
+    },
+    get tools() {
+      return astNode.props.tools;
+    },
+    get loopValidator() {
+      return astNode.props.loopValidator;
+    },
+    get loopConfig() {
+      return astNode.props.loopConfig;
+    },
+    // Lazy methods - compile on first call
+    buildPrompt(ctx) {
+      return ensureCompiled().buildPrompt(ctx);
+    },
+    get retry() {
+      return ensureCompiled().retry;
+    },
+    get model() {
+      return ensureCompiled().model;
+    }
+  };
+  const hasResultNode = astNode.children.some((child) => child.type === "Result");
+  if (hasResultNode) {
+    proxy.extractOutput = (ctx, llmResult) => {
+      return ensureCompiled().extractOutput(ctx, llmResult);
+    };
+  }
+  const hasValidateNode = astNode.children.some((child) => child.type === "Validate");
+  if (hasValidateNode) {
+    proxy.validateOutput = (output, ctx) => {
+      const comp = ensureCompiled();
+      return comp.validateOutput(output, ctx);
+    };
+  }
+  return proxy;
+}
+
+// src/compiler/compile-workflow.ts
+function compileWorkflow(ast) {
+  if (ast.type !== "Workflow") {
+    throw new Error(`Expected Workflow node, got ${ast.type}`);
+  }
+  if (!ast.children || ast.children.length !== 1) {
+    throw new Error("Workflow must have exactly one child (workflow graph)");
+  }
+  const { name, description, defaultModel, state, enhancements } = ast.props;
+  if (!name) {
+    throw new Error("Workflow must have a name");
+  }
+  const graph = compileWorkflowNode(ast.children[0]);
+  const config = {
+    name,
+    graph
+  };
+  if (description) {
+    config.description = description;
+  }
+  if (defaultModel) {
+    config.defaultModel = defaultModel;
+  }
+  if (state) {
+    config.state = state;
+  }
+  if (enhancements) {
+    config.enhancements = enhancements;
+  }
+  return config;
+}
+
 // src/ast/types.ts
 function isAgentNode(node) {
   return node.type === "Agent";
@@ -769,6 +1301,33 @@ function isValidateNode(node) {
 function isRetryNode(node) {
   return node.type === "Retry";
 }
+function isToolsNode(node) {
+  return node.type === "Tools";
+}
+function isToolDefNode(node) {
+  return node.type === "Tools:Def";
+}
+function isToolRefNode(node) {
+  return node.type === "ToolRef";
+}
+function isWorkflowSequenceNode(node) {
+  return node.type === "WorkflowSequence";
+}
+function isWorkflowParallelNode(node) {
+  return node.type === "WorkflowParallel";
+}
+function isWorkflowConditionalNode(node) {
+  return node.type === "WorkflowConditional";
+}
+function isWorkflowLoopNode(node) {
+  return node.type === "WorkflowLoop";
+}
+function isWorkflowForEachNode(node) {
+  return node.type === "WorkflowForEach";
+}
+function isWorkflowNode(node) {
+  return node.type === "Workflow";
+}
 
 // src/utilities/observe-utils.ts
 var ObserveUtils = class {
@@ -1964,6 +2523,20 @@ var RetryUtils = class {
   }
 };
 
+// src/utilities/jsx-helpers.ts
+function toWorkflow(element) {
+  if (element.type !== "Workflow") {
+    throw new Error(`Expected Workflow element, got ${element.type}`);
+  }
+  return element;
+}
+function toAgent(element) {
+  if (element.type !== "Agent") {
+    throw new Error(`Expected Agent element, got ${element.type}`);
+  }
+  return element;
+}
+
 // src/utilities/preflight.ts
 var PreflightChecker = class {
   options;
@@ -2391,6 +2964,7 @@ async function executeLLMLoop(adapter, initialMessages, tools, config, ctx, loop
         });
       }
     }
+    const allPreExecuted = response.toolCalls.every((tc) => tc._alreadyExecuted);
     if (validator) {
       const loopState = {
         rounds,
@@ -2410,6 +2984,9 @@ async function executeLLMLoop(adapter, initialMessages, tools, config, ctx, loop
         });
       }
     }
+    if (allPreExecuted) {
+      break;
+    }
   }
   return {
     response,
@@ -2749,10 +3326,11 @@ async function executeComponent(component, ctx, adapter, config) {
       ctx.ui?.stepProgress(component.id, 50, "Executing LLM...");
       const promptMessages = await Promise.resolve(component.buildPrompt(ctx));
       const messages = feedbackMessages ? [...promptMessages, ...feedbackMessages] : promptMessages;
+      const resolvedTools = component.tools;
       const llmResult = await executeLLMLoop(
         adapter,
         messages,
-        component.tools,
+        resolvedTools,
         config,
         ctx,
         component.loopConfig,
@@ -2862,6 +3440,8 @@ var ExecutionContext = class _ExecutionContext {
   ui;
   /** Session store (optional) */
   session;
+  /** Application state store (optional, isolated from AI memory) */
+  appState;
   /** Current stage ID (for UI updates) */
   currentStageId;
   // ========== Constructor ==========
@@ -2874,6 +3454,7 @@ var ExecutionContext = class _ExecutionContext {
     this.conversation = params.conversation;
     this.memory = params.memory;
     this.session = params.session;
+    this.appState = params.appState;
     this.ui = params.ui;
     this.currentStageId = params.currentStageId;
     this.iteration = params.iteration;
@@ -2922,6 +3503,7 @@ var ExecutionContext = class _ExecutionContext {
       conversation: this.conversation,
       memory: this.memory,
       session: this.session,
+      appState: this.appState,
       ui: this.ui,
       currentStageId: updates.currentStageId ?? this.currentStageId,
       iteration: updates.iteration ?? this.iteration,
@@ -2950,6 +3532,27 @@ var ExecutionContext = class _ExecutionContext {
       iterationHistory: this.iterationHistory
     });
   }
+  /**
+   * Update inputs (for ForEach iterations)
+   */
+  withInputs(inputs) {
+    return new _ExecutionContext({
+      inputs,
+      previousOutputs: this.previousOutputs,
+      store: this.store,
+      trace: this.trace,
+      stats: this.stats,
+      conversation: this.conversation,
+      memory: this.memory,
+      session: this.session,
+      appState: this.appState,
+      ui: this.ui,
+      currentStageId: this.currentStageId,
+      iteration: this.iteration,
+      maxIterations: this.maxIterations,
+      iterationHistory: this.iterationHistory
+    });
+  }
   /**
    * Add to iteration history
    */
@@ -2983,6 +3586,12 @@ var ExecutionContext = class _ExecutionContext {
   hasUI() {
     return this.ui !== void 0;
   }
+  /**
+   * Check if appState is enabled
+   */
+  hasAppState() {
+    return this.appState !== void 0;
+  }
   /**
    * Get conversation manager (throws if not available)
    */
@@ -3019,6 +3628,15 @@ var ExecutionContext = class _ExecutionContext {
     }
     return this.ui;
   }
+  /**
+   * Get application state store (throws if not available)
+   */
+  requireAppState() {
+    if (!this.appState) {
+      throw new Error("Application state store not available in this context");
+    }
+    return this.appState;
+  }
   // ========== Debugging ==========
   /**
    * Get context summary for debugging
@@ -3033,7 +3651,8 @@ var ExecutionContext = class _ExecutionContext {
         conversation: this.hasConversation(),
         memory: this.hasMemory(),
         session: this.hasSession(),
-        ui: this.hasUI()
+        ui: this.hasUI(),
+        appState: this.hasAppState()
       },
       stats: this.stats
     };
@@ -3469,6 +4088,81 @@ var LimoMemoryManager = class {
   getDetailedMemories() {
     return Array.from(this.detailedMemories.values());
   }
+  /**
+   * Get all memory keys (core + detailed)
+   *
+   * @returns Array of all memory keys
+   */
+  getAllKeys() {
+    const keys = /* @__PURE__ */ new Set();
+    for (const key of this.coreMemories.keys()) keys.add(key);
+    for (const key of this.detailedMemories.keys()) keys.add(key);
+    return Array.from(keys);
+  }
+  /**
+   * Get all Memory objects (core + detailed)
+   *
+   * @returns Array of all Memory entries
+   */
+  getAllMemories() {
+    return [
+      ...Array.from(this.coreMemories.values()),
+      ...Array.from(this.detailedMemories.values())
+    ];
+  }
+  /**
+   * Get raw Memory object by key (without triggering access metadata update)
+   *
+   * @param key - Memory key
+   * @returns Memory object or undefined
+   */
+  getMemory(key) {
+    return this.coreMemories.get(key) || this.detailedMemories.get(key);
+  }
+  /**
+   * Update an existing memory entry
+   *
+   * @param key - Memory key to update
+   * @param updates - Partial updates (content, importance, category, tags)
+   * @returns true if updated, false if key not found
+   */
+  async update(key, updates) {
+    const memory = this.coreMemories.get(key) || this.detailedMemories.get(key);
+    if (!memory) return false;
+    if (updates.content !== void 0) memory.content = updates.content;
+    if (updates.importance !== void 0) memory.importance = updates.importance;
+    if (updates.category !== void 0) memory.category = updates.category;
+    if (updates.tags !== void 0) memory.tags = updates.tags;
+    return true;
+  }
+  /**
+   * Promote a memory to core by key
+   *
+   * @param key - Memory key to promote
+   * @returns true if promoted, false if key not found or already in core
+   */
+  promoteToCoreByKey(key) {
+    const memory = this.detailedMemories.get(key);
+    if (!memory) {
+      return this.coreMemories.has(key) ? false : false;
+    }
+    this.promoteToCore(memory);
+    return true;
+  }
+  /**
+   * Demote a memory from core to detailed by key
+   *
+   * @param key - Memory key to demote
+   * @returns true if demoted, false if key not found in core
+   */
+  demoteFromCore(key) {
+    const memory = this.coreMemories.get(key);
+    if (!memory) return false;
+    memory.is_core = false;
+    this.detailedMemories.set(memory.id, memory);
+    this.coreMemories.delete(memory.id);
+    return true;
+  }
   /**
    * Get memory statistics
    */
@@ -3600,8 +4294,6 @@ var LimoMemoryManager = class {
     return diffMs / (1e3 * 60 * 60 * 24);
   }
 };
-
-// src/session/types.ts
 var DEFAULT_SESSION_CONFIG = {
   directory: ".deity/sessions",
   autoSaveInterval: 3e4,
@@ -3610,6 +4302,32 @@ var DEFAULT_SESSION_CONFIG = {
   maxBackups: 5,
   compress: false
 };
+var PauseReasonSchema = z.enum(["manual", "timeout", "error"]);
+var ExecutionStatsSchema = z.object({
+  totalToolCalls: z.number().int().min(0),
+  totalRetries: z.number().int().min(0)
+}).passthrough();
+var PausedSessionStateSchema = z.object({
+  inputs: z.unknown(),
+  outputs: z.record(z.string(), z.unknown()),
+  conversation: z.string().optional(),
+  memory: z.string().optional(),
+  appState: z.string().optional(),
+  stats: ExecutionStatsSchema
+});
+var PausedSessionMetadataSchema = z.object({
+  pauseReason: PauseReasonSchema,
+  resumable: z.boolean(),
+  notes: z.string().optional()
+});
+z.object({
+  sessionId: z.string().min(1, "Session ID cannot be empty"),
+  workflowName: z.string().min(1, "Workflow name cannot be empty"),
+  pausedAt: z.string().datetime("Must be ISO 8601 datetime"),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Must be semver format (e.g., 4.0.0)"),
+  state: PausedSessionStateSchema,
+  metadata: PausedSessionMetadataSchema
+});
 
 // src/session/serializer.ts
 var TYPE_MARKERS = {
@@ -4038,6 +4756,58 @@ var FileSystemSessionStore = class {
   }
 };
 
+// src/engine/stores.ts
+var InMemoryStore = class {
+  data = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.data.get(key);
+  }
+  async set(key, value) {
+    this.data.set(key, value);
+  }
+  async has(key) {
+    return this.data.has(key);
+  }
+  async delete(key) {
+    this.data.delete(key);
+  }
+  async clear() {
+    this.data.clear();
+  }
+  // Extra methods beyond StateStore interface
+  size() {
+    return this.data.size;
+  }
+  keys() {
+    return Array.from(this.data.keys());
+  }
+  entries() {
+    return Array.from(this.data.entries());
+  }
+  values() {
+    return Array.from(this.data.values());
+  }
+};
+var InMemoryTrace = class {
+  entries = [];
+  async log(entry) {
+    this.entries.push(entry);
+  }
+  async getEntries() {
+    return [...this.entries];
+  }
+  // Extra methods for testing
+  clear() {
+    this.entries = [];
+  }
+  count() {
+    return this.entries.length;
+  }
+  getEntriesByType(type) {
+    return this.entries.filter((e) => e.type === type);
+  }
+};
+
 // src/engine/stats.ts
 var StatsManager = class {
   stats;
@@ -4166,6 +4936,14 @@ async function createEnhancedContext(config) {
     session = new FileSystemSessionStore(sessionConfig);
     await session.init();
   }
+  let appState;
+  if (config.enableAppState) {
+    if (typeof config.enableAppState === "boolean") {
+      appState = new InMemoryStore();
+    } else {
+      appState = config.enableAppState;
+    }
+  }
   return new ExecutionContext({
     inputs: config.inputs,
     previousOutputs: config.previousOutputs ?? {},
@@ -4175,6 +4953,7 @@ async function createEnhancedContext(config) {
     conversation,
     memory,
     session,
+    appState,
     ui: config.ui,
     currentStageId: config.currentStageId,
     iteration: config.loop?.iteration,
@@ -4183,52 +4962,6 @@ async function createEnhancedContext(config) {
   });
 }
 
-// src/engine/stores.ts
-var InMemoryStore = class {
-  data = /* @__PURE__ */ new Map();
-  async get(key) {
-    return this.data.get(key);
-  }
-  async set(key, value) {
-    this.data.set(key, value);
-  }
-  async has(key) {
-    return this.data.has(key);
-  }
-  async delete(key) {
-    this.data.delete(key);
-  }
-  async clear() {
-    this.data.clear();
-  }
-  // Extra methods for testing
-  size() {
-    return this.data.size;
-  }
-  keys() {
-    return Array.from(this.data.keys());
-  }
-};
-var InMemoryTrace = class {
-  entries = [];
-  async log(entry) {
-    this.entries.push(entry);
-  }
-  async getEntries() {
-    return [...this.entries];
-  }
-  // Extra methods for testing
-  clear() {
-    this.entries = [];
-  }
-  count() {
-    return this.entries.length;
-  }
-  getEntriesByType(type) {
-    return this.entries.filter((e) => e.type === type);
-  }
-};
-
 // src/engine/workflow.ts
 async function runWorkflow(config, inputs) {
   const store = config.state?.store ?? new InMemoryStore();
@@ -4240,6 +4973,7 @@ async function runWorkflow(config, inputs) {
     enableConversation: config.enhancements?.conversation !== void 0,
     enableMemory: config.enhancements?.memory !== void 0,
     enableSession: config.enhancements?.session !== void 0,
+    enableAppState: config.enhancements?.appState,
     ui: config.enhancements?.ui
   });
   const result = await executeNode(
@@ -4250,6 +4984,10 @@ async function runWorkflow(config, inputs) {
   );
   return result;
 }
+async function runTSXWorkflow(workflowAST, inputs) {
+  const config = compileWorkflow(workflowAST);
+  return runWorkflow(config, inputs);
+}
 async function executeNode(node, ctx, adapter, config) {
   switch (node.type) {
     case "step":
@@ -4262,6 +5000,8 @@ async function executeNode(node, ctx, adapter, config) {
       return executeConditionalNode(node, ctx, adapter, config);
     case "loop":
       return executeLoopNode(node, ctx, adapter, config);
+    case "foreach":
+      return executeForEachNode(node, ctx, adapter, config);
     default:
       throw new Error(`Unknown node type: ${node.type}`);
   }
@@ -4347,6 +5087,116 @@ async function executeLoopNode(node, ctx, adapter, config) {
   }
   return results;
 }
+async function executeForEachNode(node, ctx, adapter, config) {
+  if (!node.children || node.children.length === 0) {
+    throw new Error("ForEach node has no children");
+  }
+  if (!node.itemsAccessor) {
+    throw new Error("ForEach node missing itemsAccessor");
+  }
+  let items;
+  if (typeof node.itemsAccessor === "function") {
+    items = await Promise.resolve(node.itemsAccessor(ctx));
+  } else {
+    items = node.itemsAccessor;
+  }
+  if (!Array.isArray(items)) {
+    throw new Error("ForEach items must be an array");
+  }
+  const itemMode = node.itemMode ?? "property";
+  const itemKey = node.itemKey ?? "currentItem";
+  const errorMode = node.errorMode ?? "stop";
+  const collectResults = node.collectResults ?? true;
+  const results = [];
+  const errors = [];
+  let successCount = 0;
+  let failureCount = 0;
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    try {
+      const iterationCtx = createIterationContext(
+        ctx,
+        item,
+        i,
+        items.length,
+        itemMode,
+        itemKey
+      );
+      const result = await executeNode(node.children[0], iterationCtx, adapter, config);
+      if (collectResults) {
+        results.push(result);
+      }
+      successCount++;
+    } catch (error) {
+      failureCount++;
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (errorMode === "stop") {
+        throw err;
+      } else if (errorMode === "continue") {
+        errors.push({ index: i, item, error: err });
+      } else ;
+    }
+  }
+  if (errorMode === "continue" && (errors.length > 0 || failureCount > 0)) {
+    return {
+      results,
+      errors,
+      totalItems: items.length,
+      successCount,
+      failureCount
+    };
+  }
+  return results;
+}
+function createIterationContext(baseCtx, currentItem, index, totalItems, itemMode, itemKey) {
+  let newInputs;
+  if (itemMode === "property") {
+    newInputs = {
+      ...baseCtx.inputs,
+      [itemKey]: currentItem,
+      __forEachIndex: index,
+      __forEachTotal: totalItems,
+      __forEachIsLast: index === totalItems - 1
+    };
+  } else if (itemMode === "merge") {
+    if (typeof currentItem === "object" && currentItem !== null) {
+      newInputs = {
+        ...baseCtx.inputs,
+        ...currentItem,
+        __forEachIndex: index,
+        __forEachTotal: totalItems,
+        __forEachIsLast: index === totalItems - 1
+      };
+    } else {
+      throw new Error(
+        `ForEach itemMode='merge' requires object items, got ${typeof currentItem}`
+      );
+    }
+  } else if (itemMode === "replace") {
+    if (typeof currentItem === "object" && currentItem !== null) {
+      newInputs = {
+        ...currentItem,
+        __forEachIndex: index,
+        __forEachTotal: totalItems,
+        __forEachIsLast: index === totalItems - 1
+      };
+    } else {
+      newInputs = currentItem;
+    }
+  } else {
+    throw new Error(`Unknown itemMode: ${itemMode}`);
+  }
+  if (baseCtx instanceof ExecutionContext) {
+    return baseCtx.withInputs(newInputs).withIteration(index, totalItems);
+  }
+  return {
+    ...baseCtx,
+    inputs: newInputs,
+    iteration: index,
+    maxIterations: totalItems,
+    isLastIteration: index === totalItems - 1
+  };
+}
 function createStepNode(component) {
   return {
     type: "step",
@@ -4380,250 +5230,6 @@ function createLoopNode(child, maxIterations) {
   };
 }
 
-// src/engine/tool-result-extractor.ts
-function extractLastToolResult(llmResult, toolName, options = {}) {
-  const { unwrap = true, required = true } = options;
-  if (llmResult.response?.toolCalls && llmResult.response.toolCalls.length > 0) {
-    const toolCalls = llmResult.response.toolCalls.filter(
-      (tc) => tc.name === toolName
-    );
-    if (toolCalls.length > 0) {
-      const lastCall = toolCalls[toolCalls.length - 1];
-      return parseToolCall(lastCall, unwrap);
-    }
-  }
-  const toolMessages = llmResult.messages.filter(
-    (msg) => msg.role === "tool" && msg.name === toolName
-  );
-  if (toolMessages.length === 0) {
-    if (required) {
-      throw new Error(`Tool '${toolName}' was not called`);
-    }
-    return null;
-  }
-  const lastMessage = toolMessages[toolMessages.length - 1];
-  return parseToolResult(lastMessage.content, unwrap);
-}
-function extractAllToolResults(llmResult, toolName, options = {}) {
-  const { unwrap = true, filterSuccess = false } = options;
-  if (llmResult.response?.toolCalls && llmResult.response.toolCalls.length > 0) {
-    const toolCalls = llmResult.response.toolCalls.filter(
-      (tc) => tc.name === toolName
-    );
-    if (toolCalls.length > 0) {
-      let results2 = toolCalls.map((tc) => {
-        try {
-          return parseToolCall(tc, unwrap);
-        } catch {
-          return null;
-        }
-      }).filter((r) => r !== null);
-      if (filterSuccess && unwrap) {
-        results2 = results2.filter((result) => {
-          if (result && typeof result === "object" && "success" in result) {
-            return result.success === true;
-          }
-          return true;
-        });
-      }
-      return results2;
-    }
-  }
-  const toolMessages = llmResult.messages.filter(
-    (msg) => msg.role === "tool" && msg.name === toolName
-  );
-  let results = toolMessages.map((msg) => {
-    try {
-      return parseToolResult(msg.content, unwrap);
-    } catch {
-      return null;
-    }
-  }).filter((r) => r !== null);
-  if (filterSuccess && unwrap) {
-    results = results.filter((result) => {
-      if (result && typeof result === "object" && "success" in result) {
-        return result.success === true;
-      }
-      return true;
-    });
-  }
-  return results;
-}
-function countToolCalls(llmResult, toolName, filter) {
-  if (llmResult.response?.toolCalls && llmResult.response.toolCalls.length > 0) {
-    const toolCalls = llmResult.response.toolCalls.filter(
-      (tc) => tc.name === toolName
-    );
-    if (toolCalls.length > 0) {
-      if (!filter) {
-        return toolCalls.length;
-      }
-      return toolCalls.filter((tc) => {
-        try {
-          const parsed = parseToolCall(tc, true);
-          return filter(parsed);
-        } catch {
-          return false;
-        }
-      }).length;
-    }
-  }
-  const toolMessages = llmResult.messages.filter(
-    (msg) => msg.role === "tool" && msg.name === toolName
-  );
-  if (!filter) {
-    return toolMessages.length;
-  }
-  return toolMessages.filter((msg) => {
-    try {
-      const result = JSON.parse(msg.content);
-      return filter(result);
-    } catch {
-      return false;
-    }
-  }).length;
-}
-function parseToolCall(toolCall, unwrap) {
-  try {
-    if (toolCall._executionResult) {
-      const result = JSON.parse(toolCall._executionResult);
-      if (unwrap && result && typeof result === "object") {
-        if ("success" in result) {
-          if (result.success === false && result.error) {
-            throw new Error(`Tool execution failed: ${result.error}`);
-          }
-          return result.data !== void 0 ? result.data : result;
-        }
-      }
-      return result;
-    }
-    return toolCall.arguments;
-  } catch (error) {
-    throw new Error(`Failed to parse tool call: ${error.message}`);
-  }
-}
-function parseToolResult(content, unwrap) {
-  try {
-    const parsed = JSON.parse(content);
-    if (unwrap && parsed && typeof parsed === "object") {
-      if ("success" in parsed) {
-        if (parsed.success === false && parsed.error) {
-          throw new Error(`Tool execution failed: ${parsed.error}`);
-        }
-        return parsed.data !== void 0 ? parsed.data : parsed;
-      }
-    }
-    return parsed;
-  } catch (error) {
-    throw new Error(`Failed to parse tool result: ${error.message}`);
-  }
-}
-var MemoryStoreInputSchema = z.object({
-  key: z.string().describe("Unique identifier for this memory entry"),
-  content: z.string().min(20).describe("Content to store (minimum 20 characters for meaningful data)"),
-  importance: z.number().min(0).max(10).optional().default(5).describe("Importance level (0-10, higher = more important, default: 5)"),
-  category: z.string().optional().describe('Category for filtering and organization (e.g., "architecture", "planning")'),
-  tags: z.array(z.string()).optional().default([]).describe("Tags for relevance matching and retrieval")
-});
-var MemoryRecallInputSchema = z.object({
-  query: z.string().describe("Search query or keywords to find relevant memories"),
-  category: z.string().optional().describe("Filter results by category"),
-  limit: z.number().min(1).max(20).optional().default(5).describe("Maximum number of memories to return (default: 5, max: 20)")
-});
-function createMemoryTools(ctx) {
-  if (!ctx.memory) {
-    throw new Error(
-      "Cannot create memory tools: Memory is not enabled in ExecutionContext. Use createEnhancedContext({ enableMemory: true }) to enable memory."
-    );
-  }
-  const memory = ctx.memory;
-  return [
-    // ========================================================================
-    // memory_store
-    // ========================================================================
-    {
-      name: "memory_store",
-      description: "Store important findings, insights, or context for later retrieval. Use this to remember key information that will be useful in subsequent analysis phases.",
-      inputSchema: MemoryStoreInputSchema,
-      execute: async (params) => {
-        try {
-          const memoryData = {
-            content: params.content,
-            importance: params.importance,
-            category: params.category,
-            tags: params.tags,
-            stored_at: (/* @__PURE__ */ new Date()).toISOString()
-          };
-          await memory.set(params.key, memoryData);
-          return {
-            success: true,
-            key: params.key,
-            stored_at: memoryData.stored_at,
-            message: `Memory '${params.key}' stored successfully`
-          };
-        } catch (error) {
-          const errorMsg = error instanceof Error ? error.message : String(error);
-          return {
-            success: false,
-            error: `Failed to store memory: ${errorMsg}`
-          };
-        }
-      }
-    },
-    // ========================================================================
-    // memory_recall
-    // ========================================================================
-    {
-      name: "memory_recall",
-      description: "Recall previously stored memories by searching with keywords or queries. Returns the most relevant memories based on content similarity, category, tags, and importance.",
-      inputSchema: MemoryRecallInputSchema,
-      execute: async (params) => {
-        try {
-          const keywords = params.query.toLowerCase().split(/\s+/).filter((word) => word.length > 3);
-          const memories = await memory.loadWorkingMemory({
-            currentTask: params.query,
-            keywords,
-            categories: params.category ? [params.category] : void 0
-          });
-          const limit = params.limit ?? 5;
-          const results = memories.slice(0, limit);
-          const formattedMemories = results.map((m) => {
-            let content = m.content;
-            try {
-              const parsed = JSON.parse(m.content);
-              content = parsed.content || m.content;
-            } catch {
-            }
-            return {
-              key: m.id,
-              content,
-              importance: m.importance,
-              category: m.category,
-              tags: m.tags,
-              stored_at: m.stored_at,
-              access_count: m.access_count
-            };
-          });
-          return {
-            success: true,
-            count: formattedMemories.length,
-            total_available: memories.length,
-            memories: formattedMemories,
-            message: `Found ${formattedMemories.length} relevant memories`
-          };
-        } catch (error) {
-          const errorMsg = error instanceof Error ? error.message : String(error);
-          return {
-            success: false,
-            error: `Failed to recall memories: ${errorMsg}`,
-            memories: []
-          };
-        }
-      }
-    }
-  ];
-}
-
-export { Agent, DEBUG_ENABLED, DebugLogger, InMemoryStore, InMemoryTrace, Observe, ObserveUtils, PreflightChecker, Prompt, PromptResourceLoader, Result, ResultUtils, Retry, RetryUtils, System, User, Validate, ValidateUtils, compileAgent, countToolCalls, createConditionalNode, createEnhancedContext, createLoopNode, createMemoryTools, createParallelNode, createSequenceNode, createStepNode, executeComponent, executeLLMLoop, extractAllToolResults, extractLastToolResult, getResourceLoader, isAgentNode, isObserveNode, isPromptNode, isResultNode, isRetryNode, isSystemNode, isUserNode, isValidateNode, logger, preflight, runWorkflow, setResourceLoader, testFullAgent };
+export { Agent, Conditional, DEBUG_ENABLED, DebugLogger, ForEach, InMemoryStore, InMemoryTrace, Loop, Observe, ObserveUtils, Parallel, PreflightChecker, Prompt, PromptResourceLoader, Result, ResultUtils, Retry, RetryUtils, Sequence, System, Tool, ToolDef, ToolRef, Tools, User, Validate, ValidateUtils, Workflow, compileAgent, compileWorkflow, compileWorkflowNode, createConditionalNode, createEnhancedContext, createLoopNode, createParallelNode, createSequenceNode, createStepNode, executeComponent, executeLLMLoop, getResourceLoader, isAgentNode, isObserveNode, isPromptNode, isResultNode, isRetryNode, isSystemNode, isToolDefNode, isToolRefNode, isToolsNode, isUserNode, isValidateNode, isWorkflowConditionalNode, isWorkflowForEachNode, isWorkflowLoopNode, isWorkflowNode, isWorkflowParallelNode, isWorkflowSequenceNode, logger, preflight, runTSXWorkflow, runWorkflow, setResourceLoader, testFullAgent, toAgent, toWorkflow };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map