flowneer 0.6.1 → 0.7.0

package/dist/{FlowBuilder-DssSGM7v.d.ts → FlowBuilder-C3B91Fzo.d.ts}

@@ -250,4 +250,4 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
     private _runSub;
 }
 
-export { FlowBuilder as F, type NodeFn as N, type RunOptions as R, type StepMeta as S, type Validator as V, type NodeOptions as a, type FlowneerPlugin as b, type FlowHooks as c, type NumberOrFn as d, type StreamEvent as e };
+export { type AnchorStep as A, type BatchStep as B, FlowBuilder as F, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type RunOptions as R, type StepMeta as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type BranchStep as d, type FnStep as e, type NumberOrFn as f, type Step as g, type StreamEvent as h };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { F as FlowBuilder, c as FlowHooks, b as FlowneerPlugin, N as NodeFn, a as NodeOptions, d as NumberOrFn, R as RunOptions, S as StepMeta, e as StreamEvent, V as Validator } from './FlowBuilder-DssSGM7v.js';
+export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, f as NumberOrFn, R as RunOptions, S as StepMeta, h as StreamEvent, V as Validator } from './FlowBuilder-C3B91Fzo.js';
 export { FlowError, Fragment, InterruptError, fragment } from './src/index.js';

package/dist/index.js

@@ -453,6 +453,8 @@ var Fragment = class extends FlowBuilder {
     );
   }
   /** @internal Fragments cannot be streamed — embed them via `.add()`. */
+  // v8 ignore next 5 — async generator has an implicit "resume after yield"
+  // branch that is unreachable here because we always throw before yielding.
   async *stream(_shared, _params) {
     throw new Error(
       "Fragment cannot be streamed directly \u2014 use .add() to embed it in a FlowBuilder"

package/dist/patterns-C3oKxgYZ.d.ts

@@ -0,0 +1,195 @@
+import { a as FlowneerPlugin, F as FlowBuilder, N as NodeFn } from './FlowBuilder-C3B91Fzo.js';
+import { ToolCall, ToolResult } from './plugins/tools/index.js';
+
+/**
+ * The result of a `think` function.
+ *
+ * - Return `{ action: "finish", output }` to end the loop.
+ * - Return `{ action: "tool", calls }` to invoke tools, the results of
+ *   which will be available in `shared.__toolResults` on the next iteration.
+ */
+type ThinkResult = {
+    action: "finish";
+    output?: unknown;
+} | {
+    action: "tool";
+    calls: ToolCall[];
+};
+interface ReActLoopOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * The "think" step — receives shared state (which includes tool results
+     * from the previous iteration) and returns the next action.
+     */
+    think: (shared: S, params: P) => ThinkResult | Promise<ThinkResult>;
+    /**
+     * Maximum number of think → act iterations. Defaults to 10.
+     * When exceeded the loop breaks and `shared.__reactExhausted = true`.
+     */
+    maxIterations?: number;
+    /**
+     * Optional callback invoked after each tool execution round.
+     * Useful for logging, appending to conversation history, etc.
+     */
+    onObservation?: (results: ToolResult[], shared: S, params: P) => void | Promise<void>;
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Inserts a ReAct agent loop into the flow.
+         *
+         * The loop runs `think → [tool calls] → observation → repeat` until
+         * the think step returns `{ action: "finish" }` or `maxIterations`
+         * is reached.
+         *
+         * Requires `.withTools(tools)` to have been called first so that
+         * `shared.__tools` is available.
+         *
+         * @example
+         * flow
+         *   .withTools([calculatorTool, searchTool])
+         *   .withReActLoop({
+         *     think: async (s) => {
+         *       const response = await callLlm(buildPrompt(s));
+         *       if (response.toolCalls.length) {
+         *         return { action: "tool", calls: response.toolCalls };
+         *       }
+         *       return { action: "finish", output: response.text };
+         *     },
+         *     maxIterations: 5,
+         *   })
+         */
+        withReActLoop(options: ReActLoopOptions<S, P>): this;
+    }
+}
+declare const withReActLoop: FlowneerPlugin;
+
+interface HumanNodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Key on `shared` where the prompt / question for the human is stored.
+     * The step will set `shared[promptKey]` before interrupting so the
+     * caller knows what input is expected.
+     * Defaults to `"__humanPrompt"`.
+     */
+    promptKey?: string;
+    /**
+     * Optional condition — when provided, the node only interrupts when
+     * the condition returns `true`. Defaults to always interrupt.
+     */
+    condition?: (shared: S, params: P) => boolean | Promise<boolean>;
+    /**
+     * Optional prompt message to store on `shared[promptKey]` before
+     * interrupting. If omitted, step uses whatever is already on shared.
+     */
+    prompt?: string | ((shared: S, params: P) => string | Promise<string>);
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Insert a human-in-the-loop pause point.
+         *
+         * When this step executes it throws an `InterruptError` carrying a
+         * deep clone of `shared`. The caller catches the interrupt, obtains
+         * human input, and calls `resumeFlow()` to continue.
+         *
+         * @example
+         * const flow = new FlowBuilder<MyState>()
+         *   .startWith(generateDraft)
+         *   .humanNode({ prompt: "Please review the draft above." })
+         *   .then(applyFeedback);
+         *
+         * try {
+         *   await flow.run(shared);
+         * } catch (e) {
+         *   if (e instanceof InterruptError) {
+         *     const userInput = await getUserInput(e.savedShared.__humanPrompt);
+         *     await resumeFlow(flow, e.savedShared, { feedback: userInput }, 2);
+         *   }
+         * }
+         */
+        humanNode(options?: HumanNodeOptions<S, P>): this;
+    }
+}
+declare const withHumanNode: FlowneerPlugin;
+/**
+ * Resume a flow from an `InterruptError`.
+ *
+ * Merges `edits` into the saved shared state, then re-runs the flow
+ * starting from step `fromStep` (defaults to 0, which replays from
+ * the beginning — combine with `withReplay(fromStep)` to skip already-
+ * completed steps).
+ *
+ * @param flow   The same FlowBuilder instance that was interrupted.
+ * @param saved  The `savedShared` captured by `InterruptError`.
+ * @param edits  Partial state to merge (human's input / corrections).
+ * @param fromStep  Step index to effectively resume from (uses `withReplay`).
+ */
+declare function resumeFlow<S extends Record<string, any>>(flow: FlowBuilder<S, any>, saved: S, edits?: Partial<S>, fromStep?: number): Promise<void>;
+
+/**
+ * Creates a supervisor → workers pattern.
+ *
+ * 1. `supervisor` runs first to set up context / assign tasks.
+ * 2. All `workers` run in parallel (with an optional reducer).
+ * 3. `supervisor` runs again (post step) to aggregate results.
+ *
+ * @example
+ * const flow = supervisorCrew<MyState>(
+ *   async (s) => { s.tasks = splitIntoChunks(s.input); },
+ *   [
+ *     async (s) => { s.results ??= []; s.results.push(await doWork(s)); },
+ *     async (s) => { s.results ??= []; s.results.push(await doWork(s)); },
+ *   ],
+ *   { post: async (s) => { s.summary = combine(s.results); } },
+ * );
+ */
+declare function supervisorCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(supervisor: NodeFn<S, P>, workers: NodeFn<S, P>[], options?: {
+    /** Optional post-parallel supervisor step for aggregation. */
+    post?: NodeFn<S, P>;
+    /** Optional reducer for parallel isolation. */
+    reducer?: (shared: S, drafts: S[]) => void;
+}): FlowBuilder<S, P>;
+/**
+ * Creates a strict sequential pipeline: each step runs in order,
+ * reading/writing to shared state as a baton pass.
+ *
+ * @example
+ * const flow = sequentialCrew<MyState>([
+ *   async (s) => { s.research = await research(s.query); },
+ *   async (s) => { s.draft = await writeDraft(s.research); },
+ *   async (s) => { s.final = await editDraft(s.draft); },
+ * ]);
+ */
+declare function sequentialCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(steps: NodeFn<S, P>[]): FlowBuilder<S, P>;
+/**
+ * Creates a hierarchical pattern: a top-level manager delegates to
+ * sub-team flows (each is its own `FlowBuilder` or supervisor crew).
+ *
+ * The manager runs first, then each team runs sequentially (for safety;
+ * use `parallel` within each team if needed), and a final aggregation
+ * step runs at the end.
+ *
+ * @example
+ * const flow = hierarchicalCrew<MyState>(
+ *   async (s) => { s.plan = planTasks(s.input); },
+ *   [researchTeamFlow, writingTeamFlow],
+ *   async (s) => { s.output = mergeTeamResults(s); },
+ * );
+ */
+declare function hierarchicalCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(manager: NodeFn<S, P>, teams: FlowBuilder<S, P>[], aggregate?: NodeFn<S, P>): FlowBuilder<S, P>;
+/**
+ * Creates a round-robin debate: each agent step runs in sequence,
+ * repeated `rounds` times, appending perspectives to shared state.
+ *
+ * @example
+ * const flow = roundRobinDebate<MyState>(
+ *   [
+ *     async (s) => { s.debate.push({ agent: "optimist", text: await optimist(s) }); },
+ *     async (s) => { s.debate.push({ agent: "critic", text: await critic(s) }); },
+ *     async (s) => { s.debate.push({ agent: "synthesiser", text: await synth(s) }); },
+ *   ],
+ *   3, // 3 rounds
+ * );
+ */
+declare function roundRobinDebate<S = any, P extends Record<string, unknown> = Record<string, unknown>>(agents: NodeFn<S, P>[], rounds: number): FlowBuilder<S, P>;
+
+export { type HumanNodeOptions as H, type ReActLoopOptions as R, type ThinkResult as T, roundRobinDebate as a, supervisorCrew as b, withReActLoop as c, hierarchicalCrew as h, resumeFlow as r, sequentialCrew as s, withHumanNode as w };

package/dist/plugins/agent/index.d.ts

@@ -1,195 +1,152 @@
-import { b as FlowneerPlugin, F as FlowBuilder, N as NodeFn } from '../../FlowBuilder-DssSGM7v.js';
-import { ToolCall, ToolResult } from '../tools/index.js';
+export { H as HumanNodeOptions, R as ReActLoopOptions, T as ThinkResult, h as hierarchicalCrew, r as resumeFlow, a as roundRobinDebate, s as sequentialCrew, b as supervisorCrew, w as withHumanNode, c as withReActLoop } from '../../patterns-C3oKxgYZ.js';
+import { F as FlowBuilder } from '../../FlowBuilder-C3B91Fzo.js';
+import { ToolRegistry, ToolResult, Tool, ToolCall, ToolParam } from '../tools/index.js';
 
 /**
- * The result of a `think` function.
- *
- * - Return `{ action: "finish", output }` to end the loop.
- * - Return `{ action: "tool", calls }` to invoke tools, the results of
- *   which will be available in `shared.__toolResults` on the next iteration.
+ * Minimal structural interface that matches a Zod ZodObject.
+ * We duck-type against `.shape` so this plugin has zero Zod dependency —
+ * pass a real `z.object(...)` and it just works.
  */
-type ThinkResult = {
-    action: "finish";
-    output?: unknown;
-} | {
-    action: "tool";
-    calls: ToolCall[];
-};
-interface ReActLoopOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
-    /**
-     * The "think" step — receives shared state (which includes tool results
-     * from the previous iteration) and returns the next action.
-     */
-    think: (shared: S, params: P) => ThinkResult | Promise<ThinkResult>;
-    /**
-     * Maximum number of think → act iterations. Defaults to 10.
-     * When exceeded the loop breaks and `shared.__reactExhausted = true`.
-     */
-    maxIterations?: number;
-    /**
-     * Optional callback invoked after each tool execution round.
-     * Useful for logging, appending to conversation history, etc.
-     */
-    onObservation?: (results: ToolResult[], shared: S, params: P) => void | Promise<void>;
-}
-declare module "../../Flowneer" {
-    interface FlowBuilder<S, P> {
-        /**
-         * Inserts a ReAct agent loop into the flow.
-         *
-         * The loop runs `think → [tool calls] → observation → repeat` until
-         * the think step returns `{ action: "finish" }` or `maxIterations`
-         * is reached.
-         *
-         * Requires `.withTools(tools)` to have been called first so that
-         * `shared.__tools` is available.
-         *
-         * @example
-         * flow
-         *   .withTools([calculatorTool, searchTool])
-         *   .withReActLoop({
-         *     think: async (s) => {
-         *       const response = await callLlm(buildPrompt(s));
-         *       if (response.toolCalls.length) {
-         *         return { action: "tool", calls: response.toolCalls };
-         *       }
-         *       return { action: "finish", output: response.text };
-         *     },
-         *     maxIterations: 5,
-         *   })
-         */
-        withReActLoop(options: ReActLoopOptions<S, P>): this;
-    }
+interface ZodLikeObject {
+    shape: Record<string, {
+        _def: {
+            typeName: string;
+            description?: string;
+        };
+        isOptional?(): boolean;
+    }>;
 }
-declare const withReActLoop: FlowneerPlugin;
-
-interface HumanNodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
-    /**
-     * Key on `shared` where the prompt / question for the human is stored.
-     * The step will set `shared[promptKey]` before interrupting so the
-     * caller knows what input is expected.
-     * Defaults to `"__humanPrompt"`.
-     */
-    promptKey?: string;
-    /**
-     * Optional condition — when provided, the node only interrupts when
-     * the condition returns `true`. Defaults to always interrupt.
-     */
-    condition?: (shared: S, params: P) => boolean | Promise<boolean>;
-    /**
-     * Optional prompt message to store on `shared[promptKey]` before
-     * interrupting. If omitted, step uses whatever is already on shared.
-     */
-    prompt?: string | ((shared: S, params: P) => string | Promise<string>);
+/** Config when using a Zod-compatible schema. */
+interface ToolConfigSchema<TArgs> {
+    name: string;
+    description: string;
+    schema: ZodLikeObject;
+    execute?: (args: TArgs) => unknown | Promise<unknown>;
 }
-declare module "../../Flowneer" {
-    interface FlowBuilder<S, P> {
-        /**
-         * Insert a human-in-the-loop pause point.
-         *
-         * When this step executes it throws an `InterruptError` carrying a
-         * deep clone of `shared`. The caller catches the interrupt, obtains
-         * human input, and calls `resumeFlow()` to continue.
-         *
-         * @example
-         * const flow = new FlowBuilder<MyState>()
-         *   .startWith(generateDraft)
-         *   .humanNode({ prompt: "Please review the draft above." })
-         *   .then(applyFeedback);
-         *
-         * try {
-         *   await flow.run(shared);
-         * } catch (e) {
-         *   if (e instanceof InterruptError) {
-         *     const userInput = await getUserInput(e.savedShared.__humanPrompt);
-         *     await resumeFlow(flow, e.savedShared, { feedback: userInput }, 2);
-         *   }
-         * }
-         */
-        humanNode(options?: HumanNodeOptions<S, P>): this;
-    }
+/** Config when using plain Flowneer ToolParam definitions. */
+interface ToolConfigParams<TArgs> {
+    name: string;
+    description: string;
+    params: Record<string, ToolParam>;
+    execute?: (args: TArgs) => unknown | Promise<unknown>;
 }
-declare const withHumanNode: FlowneerPlugin;
-/**
- * Resume a flow from an `InterruptError`.
- *
- * Merges `edits` into the saved shared state, then re-runs the flow
- * starting from step `fromStep` (defaults to 0, which replays from
- * the beginning — combine with `withReplay(fromStep)` to skip already-
- * completed steps).
- *
- * @param flow   The same FlowBuilder instance that was interrupted.
- * @param saved  The `savedShared` captured by `InterruptError`.
- * @param edits  Partial state to merge (human's input / corrections).
- * @param fromStep  Step index to effectively resume from (uses `withReplay`).
- */
-declare function resumeFlow<S extends Record<string, any>>(flow: FlowBuilder<S, any>, saved: S, edits?: Partial<S>, fromStep?: number): Promise<void>;
-
+type ToolConfig<TArgs> = ToolConfigSchema<TArgs> | ToolConfigParams<TArgs>;
 /**
- * Creates a supervisor → workers pattern.
+ * Create a Flowneer `Tool` from an execute function + config.
  *
- * 1. `supervisor` runs first to set up context / assign tasks.
- * 2. All `workers` run in parallel (with an optional reducer).
- * 3. `supervisor` runs again (post step) to aggregate results.
+ * Mirrors LangChain's `tool()` factory. Accepts either:
+ * - `schema: z.object(...)` — a Zod-compatible schema (duck-typed, no import needed)
+ * - `params: Record<string, ToolParam>` — plain Flowneer param definitions
  *
  * @example
- * const flow = supervisorCrew<MyState>(
- *   async (s) => { s.tasks = splitIntoChunks(s.input); },
- *   [
- *     async (s) => { s.results ??= []; s.results.push(await doWork(s)); },
- *     async (s) => { s.results ??= []; s.results.push(await doWork(s)); },
- *   ],
- *   { post: async (s) => { s.summary = combine(s.results); } },
+ * // With Zod schema:
+ * const getWeather = tool(
+ *   ({ city }) => `Always sunny in ${city}!`,
+ *   {
+ *     name: "get_weather",
+ *     description: "Get the weather for a given city",
+ *     schema: z.object({ city: z.string().describe("The city name") }),
+ *   },
  * );
- */
-declare function supervisorCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(supervisor: NodeFn<S, P>, workers: NodeFn<S, P>[], options?: {
-    /** Optional post-parallel supervisor step for aggregation. */
-    post?: NodeFn<S, P>;
-    /** Optional reducer for parallel isolation. */
-    reducer?: (shared: S, drafts: S[]) => void;
-}): FlowBuilder<S, P>;
-/**
- * Creates a strict sequential pipeline: each step runs in order,
- * reading/writing to shared state as a baton pass.
  *
- * @example
- * const flow = sequentialCrew<MyState>([
- *   async (s) => { s.research = await research(s.query); },
- *   async (s) => { s.draft = await writeDraft(s.research); },
- *   async (s) => { s.final = await editDraft(s.draft); },
- * ]);
+ * // With plain params:
+ * const getTime = tool(
+ *   () => new Date().toISOString(),
+ *   {
+ *     name: "get_time",
+ *     description: "Get the current UTC time",
+ *     params: {},
+ *   },
+ * );
  */
-declare function sequentialCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(steps: NodeFn<S, P>[]): FlowBuilder<S, P>;
+declare function tool<TArgs = Record<string, unknown>>(execute: (args: TArgs) => unknown | Promise<unknown>, config: ToolConfig<TArgs>): Tool<TArgs>;
+/** Minimal chat message shape understood by `createAgent`. */
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** Present on assistant messages when the LLM wants to call tools. */
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    /** Present on tool result messages. */
+    tool_call_id?: string;
+}
+/** Tool definition shape forwarded to the LLM. */
+interface LlmToolDef {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description: string;
+        }>;
+        required: string[];
+    };
+}
+/** Response returned by an `LlmAdapter`. */
+interface LlmResponse {
+    /** Plain-text reply — present when the model is done. */
+    text?: string;
+    /** Tool calls — present when the model wants to invoke tools. */
+    toolCalls?: ToolCall[];
+}
 /**
- * Creates a hierarchical pattern: a top-level manager delegates to
- * sub-team flows (each is its own `FlowBuilder` or supervisor crew).
+ * A vendor-agnostic LLM adapter.
  *
- * The manager runs first, then each team runs sequentially (for safety;
- * use `parallel` within each team if needed), and a final aggregation
- * step runs at the end.
+ * Receives the current conversation history and available tool definitions,
+ * returns either a final answer or a list of tool calls.
  *
  * @example
- * const flow = hierarchicalCrew<MyState>(
- *   async (s) => { s.plan = planTasks(s.input); },
- *   [researchTeamFlow, writingTeamFlow],
- *   async (s) => { s.output = mergeTeamResults(s); },
- * );
+ * // OpenAI adapter (see examples/agentExample.ts for a full implementation)
+ * const callLlm: LlmAdapter = async (messages, tools) => { ... };
  */
-declare function hierarchicalCrew<S = any, P extends Record<string, unknown> = Record<string, unknown>>(manager: NodeFn<S, P>, teams: FlowBuilder<S, P>[], aggregate?: NodeFn<S, P>): FlowBuilder<S, P>;
+type LlmAdapter = (messages: ChatMessage[], tools: LlmToolDef[]) => Promise<LlmResponse>;
+interface AgentState {
+    /** The user's input prompt. */
+    input: string;
+    /** The agent's final answer — set after the flow completes. */
+    output?: string;
+    /** Conversation history accumulated during the run. */
+    messages: ChatMessage[];
+    /** Optional system prompt (can also be passed to `createAgent`). */
+    systemPrompt?: string;
+    __tools?: ToolRegistry;
+    __reactOutput?: unknown;
+    __toolResults?: ToolResult[];
+    __reactExhausted?: boolean;
+}
+interface CreateAgentOptions {
+    /** Tools the agent can invoke. */
+    tools: Tool[];
+    /** LLM adapter — call your preferred provider here. */
+    callLlm: LlmAdapter;
+    /** System prompt inserted before the conversation. */
+    systemPrompt?: string;
+    /** Maximum think → act iterations. Defaults to 10. */
+    maxIterations?: number;
+}
 /**
- * Creates a round-robin debate: each agent step runs in sequence,
- * repeated `rounds` times, appending perspectives to shared state.
+ * Create a reusable agent flow.
+ *
+ * Returns a `FlowBuilder<AgentState>`. Call `.run(state)` to execute.
  *
  * @example
- * const flow = roundRobinDebate<MyState>(
- *   [
- *     async (s) => { s.debate.push({ agent: "optimist", text: await optimist(s) }); },
- *     async (s) => { s.debate.push({ agent: "critic", text: await critic(s) }); },
- *     async (s) => { s.debate.push({ agent: "synthesiser", text: await synth(s) }); },
- *   ],
- *   3, // 3 rounds
- * );
+ * const agent = createAgent({
+ *   tools: [getWeather, getTime],
+ *   callLlm: openAiAdapter,
+ *   systemPrompt: "You are a helpful assistant.",
+ * });
+ *
+ * const state: AgentState = { input: "What's the weather in Paris?", messages: [] };
+ * await agent.run(state);
+ * console.log(state.output);
  */
-declare function roundRobinDebate<S = any, P extends Record<string, unknown> = Record<string, unknown>>(agents: NodeFn<S, P>[], rounds: number): FlowBuilder<S, P>;
+declare function createAgent(options: CreateAgentOptions): FlowBuilder<AgentState>;
 
-export { type HumanNodeOptions, type ReActLoopOptions, type ThinkResult, hierarchicalCrew, resumeFlow, roundRobinDebate, sequentialCrew, supervisorCrew, withHumanNode, withReActLoop };
+export { type AgentState, type ChatMessage, type CreateAgentOptions, type LlmAdapter, type LlmResponse, type LlmToolDef, type ToolConfig, type ToolConfigParams, type ToolConfigSchema, type ZodLikeObject, createAgent, tool };

package/dist/plugins/agent/index.js

@@ -601,12 +601,181 @@ function roundRobinDebate(agents, rounds) {
   );
   return flow;
 }
+
+// plugins/tools/withTools.ts
+var ToolRegistry = class {
+  _tools = /* @__PURE__ */ new Map();
+  constructor(tools) {
+    for (const t of tools) this._tools.set(t.name, t);
+  }
+  /** Get a registered tool by name. */
+  get(name) {
+    return this._tools.get(name);
+  }
+  /** Check if a tool is registered. */
+  has(name) {
+    return this._tools.has(name);
+  }
+  /** List all registered tool names. */
+  names() {
+    return [...this._tools.keys()];
+  }
+  /** Return tool definitions as plain objects (suitable for LLM schemas). */
+  definitions() {
+    return [...this._tools.values()].map((t) => {
+      const required = Object.entries(t.params).filter(([, p]) => p.required !== false).map(([k]) => k);
+      return {
+        name: t.name,
+        description: t.description,
+        parameters: {
+          type: "object",
+          properties: Object.fromEntries(
+            Object.entries(t.params).map(([k, p]) => [
+              k,
+              { type: p.type, description: p.description }
+            ])
+          ),
+          required
+        }
+      };
+    });
+  }
+  /**
+   * Execute a single tool call. Returns a `ToolResult`.
+   * Catches tool errors and returns them as `{ error }` rather than throwing.
+   */
+  async execute(call) {
+    const tool2 = this._tools.get(call.name);
+    if (!tool2) {
+      return {
+        callId: call.id,
+        name: call.name,
+        error: `unknown tool: ${call.name}`
+      };
+    }
+    try {
+      const result = await tool2.execute(call.args);
+      return { callId: call.id, name: call.name, result };
+    } catch (err) {
+      return {
+        callId: call.id,
+        name: call.name,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  /**
+   * Execute multiple tool calls concurrently.
+   * Returns results in the same order as the input calls.
+   */
+  async executeAll(calls) {
+    return Promise.all(calls.map((c) => this.execute(c)));
+  }
+};
+var withTools = {
+  withTools(tools) {
+    const registry = new ToolRegistry(tools);
+    this._setHooks({
+      beforeFlow: (shared) => {
+        shared.__tools = registry;
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/agent/createAgent.ts
+FlowBuilder.use(withTools);
+FlowBuilder.use(withReActLoop);
+function zodTypeToParamType(typeName) {
+  switch (typeName) {
+    case "ZodNumber":
+      return "number";
+    case "ZodBoolean":
+      return "boolean";
+    case "ZodObject":
+      return "object";
+    case "ZodArray":
+      return "array";
+    default:
+      return "string";
+  }
+}
+function zodSchemaToParams(schema) {
+  const params = {};
+  for (const [key, field] of Object.entries(schema.shape)) {
+    params[key] = {
+      type: zodTypeToParamType(field._def.typeName),
+      description: field._def.description ?? key,
+      required: field.isOptional ? !field.isOptional() : true
+    };
+  }
+  return params;
+}
+function isSchemaConfig(cfg) {
+  return "schema" in cfg && cfg.schema != null;
+}
+function tool(execute, config) {
+  const params = isSchemaConfig(config) ? zodSchemaToParams(config.schema) : config.params;
+  return {
+    name: config.name,
+    description: config.description,
+    params,
+    execute
+  };
+}
+function createAgent(options) {
+  const { tools, callLlm, systemPrompt, maxIterations = 10 } = options;
+  return new FlowBuilder().withTools(tools).startWith((s) => {
+    s.messages = [];
+    const sys = systemPrompt ?? s.systemPrompt;
+    if (sys) s.messages.push({ role: "system", content: sys });
+    s.messages.push({ role: "user", content: s.input });
+  }).withReActLoop({
+    maxIterations,
+    think: async (s) => {
+      const toolDefs = s.__tools.definitions();
+      const response = await callLlm(s.messages, toolDefs);
+      if (response.toolCalls && response.toolCalls.length > 0) {
+        s.messages.push({
+          role: "assistant",
+          content: "",
+          tool_calls: response.toolCalls.map((tc) => ({
+            id: tc.id ?? `call_${tc.name}_${Date.now()}`,
+            type: "function",
+            function: {
+              name: tc.name,
+              arguments: JSON.stringify(tc.args)
+            }
+          }))
+        });
+        return { action: "tool", calls: response.toolCalls };
+      }
+      s.messages.push({ role: "assistant", content: response.text ?? "" });
+      return { action: "finish", output: response.text };
+    },
+    // After each tool round, append results so the next think step has context.
+    onObservation: (results, s) => {
+      for (const r of results) {
+        s.messages.push({
+          role: "tool",
+          tool_call_id: r.callId ?? r.name,
+          content: r.error != null ? `Error: ${r.error}` : JSON.stringify(r.result)
+        });
+      }
+    }
+  }).then((s) => {
+    s.output = typeof s.__reactOutput === "string" ? s.__reactOutput : JSON.stringify(s.__reactOutput ?? "");
+  });
+}
 export {
+  createAgent,
   hierarchicalCrew,
   resumeFlow,
   roundRobinDebate,
   sequentialCrew,
   supervisorCrew,
+  tool,
   withHumanNode,
   withReActLoop
 };

package/dist/plugins/dev/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin, N as NodeFn, a as NodeOptions } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-C3B91Fzo.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

package/dist/plugins/eval/index.d.ts

@@ -1,4 +1,4 @@
-import { F as FlowBuilder } from '../../FlowBuilder-DssSGM7v.js';
+import { F as FlowBuilder } from '../../FlowBuilder-C3B91Fzo.js';
 
 /** Case-insensitive exact match. Returns 1.0 or 0.0. */
 declare function exactMatch(predicted: string, expected: string): number;

package/dist/plugins/graph/index.d.ts

@@ -1,4 +1,49 @@
-import { N as NodeFn, a as NodeOptions, b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-C3B91Fzo.js';
+
+/** A single node entry in the exported graph. */
+interface GraphNodeExport {
+    name: string;
+    /** Numeric options that were supplied at `.addNode()` time. */
+    options?: {
+        retries?: number | string;
+        delaySec?: number | string;
+        timeoutMs?: number | string;
+    };
+}
+/** A single edge entry in the exported graph. */
+interface GraphEdgeExport {
+    from: string;
+    to: string;
+    /** `true` when the edge has a runtime condition (back-edge / skip-ahead). */
+    conditional: boolean;
+}
+/** The root object returned by `.exportGraph("json")`. */
+interface GraphExport {
+    format: "json";
+    nodes: GraphNodeExport[];
+    edges: GraphEdgeExport[];
+}
+/**
+ * Supported export formats.
+ * - `"json"` — JSON-serialisable structure (implemented).
+ * - `"mermaid"` — Mermaid flowchart string (reserved for future use).
+ */
+type ExportFormat = "json" | "mermaid";
+type FormatResult<F extends ExportFormat> = F extends "json" ? GraphExport : F extends "mermaid" ? string : never;
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Export the graph (nodes + edges) in the given format.
+         *
+         * When only `withExportGraph` is loaded this returns `GraphExport`.
+         * Load `withExportFlow` to get the unified `FlowExport` shape instead.
+         *
+         * Non-JSON formats are reserved for future implementation.
+         */
+        exportGraph<F extends ExportFormat>(format: F): FormatResult<F>;
+    }
+}
+declare const withExportGraph: FlowneerPlugin;
 
 interface GraphNode<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
@@ -42,6 +87,7 @@ declare module "../../Flowneer" {
         compile(): this;
     }
 }
+
 declare const withGraph: FlowneerPlugin;
 
-export { type GraphEdge, type GraphNode, withGraph };
+export { type ExportFormat, type GraphEdge, type GraphEdgeExport, type GraphExport, type GraphNode, type GraphNodeExport, withExportGraph, withGraph };

package/dist/plugins/graph/index.js

@@ -1,3 +1,58 @@
+// plugins/graph/withExportGraph.ts
+function serializeOption(val) {
+  if (val === void 0 || val === null) return void 0;
+  if (typeof val === "number") return val === 0 ? void 0 : val;
+  if (typeof val === "function") return "<dynamic>";
+  return void 0;
+}
+function toJson(nodes, edges) {
+  const nodeExports = [];
+  for (const node of nodes.values()) {
+    const opts = node.options;
+    const optExport = opts ? {
+      retries: serializeOption(opts.retries),
+      delaySec: serializeOption(opts.delaySec),
+      timeoutMs: serializeOption(opts.timeoutMs)
+    } : void 0;
+    const hasOpts = optExport && (optExport.retries !== void 0 || optExport.delaySec !== void 0 || optExport.timeoutMs !== void 0);
+    nodeExports.push({
+      name: node.name,
+      ...hasOpts ? { options: optExport } : {}
+    });
+  }
+  const edgeExports = edges.map((e) => ({
+    from: e.from,
+    to: e.to,
+    conditional: !!e.condition
+  }));
+  return { format: "json", nodes: nodeExports, edges: edgeExports };
+}
+function dispatch(format, nodes, edges) {
+  switch (format) {
+    case "json":
+      return toJson(nodes, edges);
+    case "mermaid":
+      throw new Error(
+        'exportGraph: "mermaid" format is not yet implemented. Use "json" for now.'
+      );
+    default: {
+      const _exhaustive = format;
+      throw new Error(`exportGraph: unknown format "${_exhaustive}"`);
+    }
+  }
+}
+var withExportGraph = {
+  exportGraph(format = "json") {
+    const store = this.__graphStore;
+    if (!store || store.nodes.size === 0) {
+      throw new Error(
+        "exportGraph: no graph nodes found. Call .addNode() / .addEdge() before .exportGraph()."
+      );
+    }
+    return dispatch(format, store.nodes, store.edges);
+  }
+};
+
 // plugins/graph/index.ts
 function compileGraph(nodes, edges) {
   const unconditional = edges.filter((e) => !e.condition);
@@ -132,5 +187,6 @@ function _getGraphStore(builder) {
   return builder.__graphStore;
 }
 export {
+  withExportGraph,
   withGraph
 };

package/dist/plugins/index.d.ts

@@ -5,10 +5,10 @@ export { RateLimitOptions, withCostTracker, withRateLimit, withTokenBudget } fro
 export { withAtomicUpdates, withDryRun, withMocks, withStepLimit } from './dev/index.js';
 export { StreamSubscriber, emit, peekChannel, receiveFrom, sendTo, withChannels, withStream } from './messaging/index.js';
 export { Tool, ToolCall, ToolParam, ToolRegistry, ToolResult, executeTool, executeTools, getTools, withTools } from './tools/index.js';
-export { HumanNodeOptions, ReActLoopOptions, ThinkResult, hierarchicalCrew, resumeFlow, roundRobinDebate, sequentialCrew, supervisorCrew, withHumanNode, withReActLoop } from './agent/index.js';
+export { H as HumanNodeOptions, R as ReActLoopOptions, T as ThinkResult, h as hierarchicalCrew, r as resumeFlow, a as roundRobinDebate, s as sequentialCrew, b as supervisorCrew, w as withHumanNode, c as withReActLoop } from '../patterns-C3oKxgYZ.js';
 export { BufferWindowMemory, BufferWindowOptions, KVMemory, Memory, MemoryMessage, SummaryMemory, SummaryMemoryOptions, withMemory } from './memory/index.js';
 export { parseJsonOutput, parseListOutput, parseMarkdownTable, parseRegexOutput } from './output/index.js';
 export { Span, TelemetryDaemon, TelemetryExporter, TelemetryOptions, consoleExporter, otlpExporter, withTelemetry } from './telemetry/index.js';
 export { EvalResult, EvalSummary, ScoreFn, answerRelevance, containsMatch, exactMatch, f1Score, retrievalPrecision, retrievalRecall, runEvalSuite } from './eval/index.js';
 export { GraphEdge, GraphNode, withGraph } from './graph/index.js';
-import '../FlowBuilder-DssSGM7v.js';
+import '../FlowBuilder-C3B91Fzo.js';

package/dist/plugins/llm/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin, V as Validator } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin, V as Validator } from '../../FlowBuilder-C3B91Fzo.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

package/dist/plugins/memory/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 /** A single message in conversational memory. */
 interface MemoryMessage {

package/dist/plugins/messaging/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 /** Send a message to a named channel on `shared.__channels`. */
 declare function sendTo<S extends Record<string, any>>(shared: S, channel: string, message: unknown): void;

package/dist/plugins/observability/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin, S as StepMeta } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin, S as StepMeta } from '../../FlowBuilder-C3B91Fzo.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

package/dist/plugins/output/index.d.ts

@@ -1,4 +1,4 @@
-import { V as Validator } from '../../FlowBuilder-DssSGM7v.js';
+import { V as Validator } from '../../FlowBuilder-C3B91Fzo.js';
 
 /**
  * Extract and parse JSON from a (possibly noisy) LLM response.

package/dist/plugins/persistence/index.d.ts

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 interface CheckpointStore<S = any> {
     /** Called after each successful step with the step index and current shared state. */

package/dist/plugins/resilience/index.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeFn, b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { N as NodeFn, a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
@@ -58,4 +58,56 @@ declare module "../../Flowneer" {
 }
 declare const withCycles: FlowneerPlugin;
 
-export { type CircuitBreakerOptions, withCircuitBreaker, withCycles, withFallback, withTimeout };
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Begin a try / catch / finally block.
+         *
+         * Executes all steps in `tryFrag`. If any step throws:
+         *  - the `.catch()` fragment runs (if registered), with the caught error
+         *    available as `shared.__tryError`;
+         *  - if no `.catch()` fragment is registered the error propagates.
+         *
+         * The `.finally()` fragment (if registered) always runs last, regardless
+         * of success or failure.
+         *
+         * @example
+         * flow
+         *   .try(
+         *     fragment().then(risky).then(another)
+         *   )
+         *   .catch(
+         *     fragment()
+         *       .then((s) => { s.recovery = true; })
+         *       .anchor("recover")
+         *       .then(recoveryStep)
+         *   )
+         *   .finally(
+         *     fragment().then(cleanup)
+         *   );
+         */
+        try(tryFrag: FlowBuilder<S, P>): this;
+        /**
+         * Register the catch handler for the immediately preceding `.try()` block.
+         *
+         * The caught error is stored on `shared.__tryError` before the fragment
+         * runs and removed once it completes (or throws). Access the original
+         * error and its `.cause` inside the catch fragment:
+         *
+         * ```ts
+         * .catch(fragment().then((s) => console.error(s.__tryError)))
+         * ```
+         */
+        catch(catchFrag: FlowBuilder<S, P>): this;
+        /**
+         * Register a finally handler that always runs after the preceding `.try()`
+         * (and optional `.catch()`) block — whether or not an error was thrown.
+         *
+         * Clears the pending try/catch state from the builder.
+         */
+        finally(finallyFrag: FlowBuilder<S, P>): this;
+    }
+}
+declare const withTryCatch: FlowneerPlugin;
+
+export { type CircuitBreakerOptions, withCircuitBreaker, withCycles, withFallback, withTimeout, withTryCatch };

package/dist/plugins/resilience/index.js

@@ -116,9 +116,85 @@ var withCycles = {
     return this;
   }
 };
+
+// src/errors.ts
+var FlowError = class extends Error {
+  step;
+  cause;
+  constructor(step, cause) {
+    super(
+      `Flow failed at ${step}: ${cause instanceof Error ? cause.message : String(cause)}`
+    );
+    this.name = "FlowError";
+    this.step = step;
+    this.cause = cause;
+  }
+};
+
+// plugins/resilience/withTryCatch.ts
+var PENDING_KEY = "__flowneerPendingTryCatch";
+var withTryCatch = {
+  try(tryFrag) {
+    const block = {
+      tryFrag,
+      catchFrag: null,
+      finallyFrag: null
+    };
+    this[PENDING_KEY] = block;
+    this._addFn(async (shared, params) => {
+      let thrownError;
+      let didThrow = false;
+      try {
+        await block.tryFrag._execute(shared, params, void 0);
+      } catch (tryErr) {
+        if (block.catchFrag) {
+          shared.__tryError = tryErr instanceof FlowError ? tryErr.cause : tryErr;
+          try {
+            await block.catchFrag._execute(shared, params, void 0);
+          } catch (catchErr) {
+            thrownError = catchErr;
+            didThrow = true;
+          } finally {
+            delete shared.__tryError;
+          }
+        } else {
+          thrownError = tryErr;
+          didThrow = true;
+        }
+      }
+      if (block.finallyFrag) {
+        await block.finallyFrag._execute(shared, params, void 0);
+      }
+      if (didThrow) throw thrownError;
+    });
+    return this;
+  },
+  catch(catchFrag) {
+    const block = this[PENDING_KEY];
+    if (!block) {
+      throw new Error(
+        "withTryCatch: .catch() must be called immediately after .try()"
+      );
+    }
+    block.catchFrag = catchFrag;
+    return this;
+  },
+  finally(finallyFrag) {
+    const block = this[PENDING_KEY];
+    if (!block) {
+      throw new Error(
+        "withTryCatch: .finally() must be called after .try() or .try().catch()"
+      );
+    }
+    block.finallyFrag = finallyFrag;
+    delete this[PENDING_KEY];
+    return this;
+  }
+};
 export {
   withCircuitBreaker,
   withCycles,
   withFallback,
-  withTimeout
+  withTimeout,
+  withTryCatch
 };

package/dist/plugins/telemetry/index.d.ts

@@ -1,4 +1,4 @@
-import { c as FlowHooks, b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { c as FlowHooks, a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 interface Span {
     traceId: string;

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

@@ -1,4 +1,4 @@
-import { b as FlowneerPlugin } from '../../FlowBuilder-DssSGM7v.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-C3B91Fzo.js';
 
 /** Describes a single parameter for a tool. */
 interface ToolParam {

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FlowBuilder } from '../FlowBuilder-DssSGM7v.js';
-export { c as FlowHooks, b as FlowneerPlugin, N as NodeFn, a as NodeOptions, d as NumberOrFn, R as RunOptions, S as StepMeta, e as StreamEvent, V as Validator } from '../FlowBuilder-DssSGM7v.js';
+import { F as FlowBuilder } from '../FlowBuilder-C3B91Fzo.js';
+export { A as AnchorStep, B as BatchStep, d as BranchStep, c as FlowHooks, a as FlowneerPlugin, e as FnStep, L as LoopStep, N as NodeFn, b as NodeOptions, f as NumberOrFn, P as ParallelStep, R as RunOptions, g as Step, S as StepMeta, h as StreamEvent, V as Validator } from '../FlowBuilder-C3B91Fzo.js';
 
 /**
  * A reusable, composable partial flow — the Flowneer equivalent of a Zod

package/dist/src/index.js

@@ -453,6 +453,8 @@ var Fragment = class extends FlowBuilder {
     );
   }
   /** @internal Fragments cannot be streamed — embed them via `.add()`. */
+  // v8 ignore next 5 — async generator has an implicit "resume after yield"
+  // branch that is unreachable here because we always throw before yielding.
   async *stream(_shared, _params) {
     throw new Error(
       "Fragment cannot be streamed directly \u2014 use .add() to embed it in a FlowBuilder"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowneer",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Zero-dependency fluent flow builder for AI agents",
   "license": "MIT",
   "type": "module",
@@ -47,7 +47,8 @@
     "dotenv": "17.3.1",
     "openai": "6.22.0",
     "tsup": "^8.5.1",
-    "vitepress": "^2.0.0-alpha.16"
+    "vitepress": "^2.0.0-alpha.16",
+    "vitepress-plugin-llms": "^1.11.0"
   },
   "peerDependencies": {
     "typescript": "^5"