flowneer 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img src="https://raw.githubusercontent.com/Fanna1119/flowneer/feature/extras/docs/images/flowneer_logo.png" width="500" height="auto" alt="Flowneer"/>
+    <img src="https://github.com/Fanna1119/flowneer/blob/main/docs/public/flowneer_logo.png" width="500" height="auto" alt="Flowneer"/>
 </div>
 
 <p>
@@ -8,10 +8,14 @@
   <a href="https://www.npmjs.com/package/flowneer"><img src="https://img.shields.io/npm/l/flowneer" /></a>
   <a href="https://www.npmjs.com/package/flowneer"><img src="https://img.shields.io/npm/d18m/flowneer" /></a>
   <a href="https://deepwiki.com/Fanna1119/flowneer"><img src="https://deepwiki.com/badge.svg" /></a>
+  <a href="https://github.com/Fanna1119/flowneer"><img src="https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)" /></a>
+ <a href="https://context7.com/fanna1119/flowneer"><img src="https://img.shields.io/badge/-Context7-black?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHZpZXdCb3g9IjAgMCAyOCAyOCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjI4IiBoZWlnaHQ9IjI4IiByeD0iNCIgZmlsbD0iIzA1OTY2OSIvPgo8cGF0aCBkPSJNMTAuNTcyNCAxNS4yNTY1QzEwLjU3MjQgMTcuNTAyNSA5LjY2MTMgMTkuMzc3OCA4LjE3ODA1IDIxLjEwNDdIMTEuNjMxOUwxMS42MzE5IDIyLjc3ODZINi4zMzQ1OVYyMS4xODk1QzcuOTU1NTcgMTkuMzU2NiA4LjU4MDY1IDE3Ljg2MjggOC41ODA2NSAxNS4yNTY1TDEwLjU3MjQgMTUuMjU2NVoiIGZpbGw9IndoaXRlIi8%2BCjxwYXRoIGQ9Ik0xNy40Mjc2IDE1LjI1NjVDMTcuNDI3NiAxNy41MDI1IDE4LjMzODcgMTkuMzc3OCAxOS44MjIgMjEuMTA0N0gxNi4zNjgxVjIyLjc3ODZIMjEuNjY1NFYyMS4xODk1QzIwLjA0NDQgMTkuMzU2NiAxOS40MTk0IDE3Ljg2MjggMTkuNDE5NCAxNS4yNTY1SDE3LjQyNzZaIiBmaWxsPSJ3aGl0ZSIvPgo8cGF0aCBkPSJNMTAuNTcyNCAxMi43NDM1QzEwLjU3MjQgMTAuNDk3NSA5LjY2MTMxIDguNjIyMjQgOC4xNzgwNyA2Ljg5NTMyTDExLjYzMTkgNi44OTUzMlY1LjIyMTM3TDYuMzM0NjEgNS4yMjEzN1Y2LjgxMDU2QzcuOTU1NTggOC42NDM0MyA4LjU4MDY2IDEwLjEzNzMgOC41ODA2NiAxMi43NDM1TDEwLjU3MjQgMTIuNzQzNVoiIGZpbGw9IndoaXRlIi8%2BCjxwYXRoIGQ9Ik0xNy40Mjc2IDEyLjc0MzVDMTcuNDI3NiAxMC40OTc1IDE4LjMzODcgOC42MjIyNCAxOS44MjIgNi44OTUzMkwxNi4zNjgxIDYuODk1MzJMMTYuMzY4MSA1LjIyMTM4TDIxLjY2NTQgNS4yMjEzOFY2LjgxMDU2QzIwLjA0NDQgOC42NDM0MyAxOS40MTk0IDEwLjEzNzMgMTkuNDE5NCAxMi43NDM1SDE3LjQyNzZaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K" alt="Badge"></a>
 </p>
 
 A tiny, zero-dependency fluent flow builder for TypeScript. Chain steps, branch on conditions, loop, batch-process, and run tasks in parallel — all through a single `FlowBuilder` class. Extend it with plugins for tool calling, ReAct agent loops, human-in-the-loop, memory, structured output, streaming, graph-based flow composition, eval, and more.
 
+> Flowneer is currently under heavy development with ongoing pattern exploration and architectural refinement. Breaking changes are expected frequently, potentially on a daily basis, as the core design is actively evolving.
+
 ## Install
 
 ```bash

package/dist/FlowBuilder-Dqppgla9.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Generic validator interface — structurally compatible with Zod, ArkType,
+ * Valibot, or any custom implementation that exposes `.parse(input)`.
+ * Used by `withStructuredOutput` and output parsers.
+ */
+interface Validator<T = unknown> {
+    parse(input: unknown): T;
+}
+/**
+ * Events yielded by `FlowBuilder.stream()`.
+ */
+type StreamEvent<S = any> = {
+    type: "step:before";
+    meta: StepMeta;
+} | {
+    type: "step:after";
+    meta: StepMeta;
+    shared: S;
+} | {
+    type: "chunk";
+    data: unknown;
+} | {
+    type: "error";
+    error: unknown;
+} | {
+    type: "done";
+};
+/**
+ * Function signature for all step logic.
+ * Return an action string to route, or undefined/void to continue.
+ *
+ * Steps may also be declared as `async function*` generators — each `yield`
+ * forwards its value to the active stream consumer as a `chunk` event.
+ * The generator's final `return` value is still routed normally, so
+ * `return "#anchorName"` works exactly as it does in plain steps.
+ *
+ * @example
+ * .then(async function* (s) {
+ *   for await (const token of llmStream(s.prompt)) {
+ *     s.response += token;
+ *     yield token;           // → chunk event on flow.stream()
+ *   }
+ * })
+ */
+type NodeFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = (shared: S, params: P) => Promise<string | undefined | void> | string | undefined | void | AsyncGenerator<unknown, string | undefined | void, unknown>;
+/**
+ * A numeric value or a function that computes it from the current shared state
+ * and params. Use functions for dynamic per-item behaviour, e.g.
+ * `retries: (s) => (s.__batchItem % 3 === 0 ? 3 : 1)`.
+ */
+type NumberOrFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = number | ((shared: S, params: P) => number);
+interface NodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    retries?: NumberOrFn<S, P>;
+    delaySec?: NumberOrFn<S, P>;
+    timeoutMs?: NumberOrFn<S, P>;
+}
+interface RunOptions {
+    signal?: AbortSignal;
+}
+/** Metadata exposed to hooks — intentionally minimal to avoid coupling. */
+interface StepMeta {
+    index: number;
+    type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor";
+    label?: string;
+}
+/** Lifecycle hooks that plugins can register. */
+interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Fires once before the first step runs. */
+    beforeFlow?: (shared: S, params: P) => void | Promise<void>;
+    beforeStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
+    /**
+     * Wraps step execution — call `next()` to invoke the step body.
+     * Omitting `next()` skips execution (dry-run, mock, etc.).
+     * Multiple `wrapStep` registrations are composed innermost-first.
+     */
+    wrapStep?: (meta: StepMeta, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
+    afterStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
+    /**
+     * Wraps individual functions within a `.parallel()` step.
+     * `fnIndex` is the position within the fns array.
+     */
+    wrapParallelFn?: (meta: StepMeta, fnIndex: number, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
+    onError?: (meta: StepMeta, error: unknown, shared: S, params: P) => void;
+    afterFlow?: (shared: S, params: P) => void | Promise<void>;
+}
+/**
+ * A plugin is an object whose keys become methods on `FlowBuilder.prototype`.
+ * Each method receives the builder as `this` and should return `this` for chaining.
+ *
+ * Use declaration merging to get type-safe access:
+ * ```ts
+ * declare module "flowneer" {
+ *   interface FlowBuilder<S, P> { withTracing(fn: TraceCallback): this; }
+ * }
+ * ```
+ */
+type FlowneerPlugin = Record<string, (this: FlowBuilder<any, any>, ...args: any[]) => any>;
+
+interface FnStep<S, P extends Record<string, unknown>> {
+    type: "fn";
+    fn: NodeFn<S, P>;
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+}
+interface BranchStep<S, P extends Record<string, unknown>> {
+    type: "branch";
+    router: NodeFn<S, P>;
+    branches: Record<string, NodeFn<S, P>>;
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+}
+interface LoopStep<S, P extends Record<string, unknown>> {
+    type: "loop";
+    condition: (shared: S, params: P) => Promise<boolean> | boolean;
+    body: FlowBuilder<S, P>;
+}
+interface BatchStep<S, P extends Record<string, unknown>> {
+    type: "batch";
+    itemsExtractor: (shared: S, params: P) => Promise<any[]> | any[];
+    processor: FlowBuilder<S, P>;
+    key: string;
+}
+interface ParallelStep<S, P extends Record<string, unknown>> {
+    type: "parallel";
+    fns: NodeFn<S, P>[];
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+    reducer?: (shared: S, drafts: S[]) => void;
+}
+interface AnchorStep {
+    type: "anchor";
+    name: string;
+}
+type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P> | LoopStep<S, P> | BatchStep<S, P> | ParallelStep<S, P> | AnchorStep;
+
+/**
+ * Fluent builder for composable flows.
+ *
+ * Steps execute sequentially in the order added. Call `.run(shared)` to execute.
+ *
+ * **Shared-state safety**: all steps operate on the same shared object.
+ * Mutate it directly; avoid spreading/replacing the entire object.
+ */
+declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    protected steps: Step<S, P>[];
+    private _hooksList;
+    /** Cached flat arrays of present hooks — invalidated whenever a hook is added. */
+    private _cachedHooks;
+    private _getHooks;
+    /** Register a plugin — copies its methods onto `FlowBuilder.prototype`. */
+    static use(plugin: FlowneerPlugin): void;
+    /** Register lifecycle hooks (called by plugin methods, not by consumers). */
+    protected _setHooks(hooks: Partial<FlowHooks<S, P>>): void;
+    /** Set the first step, resetting any prior chain. */
+    startWith(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
+    /** Append a sequential step. */
+    then(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
+    /**
+     * Splice all steps from a `Fragment` into this flow at the current position.
+     *
+     * Fragments are reusable partial flows created with the `fragment()` factory.
+     * Steps are copied by reference (same semantics as `loop` / `batch` inners).
+     *
+     * @example
+     * ```ts
+     * const enrich = fragment<S>()
+     *   .then(fetchUser)
+     *   .then(enrichProfile);
+     *
+     * new FlowBuilder<S>()
+     *   .then(init)
+     *   .add(enrich)
+     *   .then(finalize)
+     *   .run(shared);
+     * ```
+     */
+    add(frag: FlowBuilder<S, P>): this;
+    /**
+     * Append a routing step.
+     * `router` returns a key; the matching branch flow executes, then the chain continues.
+     */
+    branch(router: NodeFn<S, P>, branches: Record<string, NodeFn<S, P>>, options?: NodeOptions<S, P>): this;
+    /**
+     * Append a looping step.
+     * Repeatedly runs `body` while `condition` returns true.
+     */
+    loop(condition: (shared: S, params: P) => Promise<boolean> | boolean, body: (b: FlowBuilder<S, P>) => void): this;
+    /**
+     * Append a batch step.
+     * Runs `processor` once per item extracted by `items`, setting
+     * `shared[key]` each time (defaults to `"__batchItem"`).
+     *
+     * Use a unique `key` when nesting batches so each level has its own
+     * namespace:
+     * ```ts
+     * .batch(s => s.users, b => b
+     *   .startWith(s => { console.log(s.__batch_user); })
+     *   .batch(s => s.__batch_user.posts, p => p
+     *     .startWith(s => { console.log(s.__batch_post); })
+     *   , { key: '__batch_post' })
+     * , { key: '__batch_user' })
+     * ```
+     */
+    batch(items: (shared: S, params: P) => Promise<any[]> | any[], processor: (b: FlowBuilder<S, P>) => void, options?: {
+        key?: string;
+    }): this;
+    /**
+     * Append a parallel step.
+     * Runs all `fns` concurrently against the same shared state.
+     *
+     * When `reducer` is provided each fn receives its own shallow clone of
+     * `shared`; after all fns complete the reducer merges the drafts back
+     * into the original shared object — preventing concurrent mutation races.
+     */
+    parallel(fns: NodeFn<S, P>[], options?: NodeOptions<S, P>, reducer?: (shared: S, drafts: S[]) => void): this;
+    /**
+     * Insert a named anchor. Anchors are no-op markers that can be jumped to
+     * from any `NodeFn` by returning `"#anchorName"`.
+     */
+    anchor(name: string): this;
+    /** Execute the flow. */
+    run(shared: S, params?: P, options?: RunOptions): Promise<void>;
+    /**
+     * Execute the flow and yield `StreamEvent`s as an async generator.
+     *
+     * Events include `step:before`, `step:after`, `chunk` (from `emit()`),
+     * `error`, and `done`. This is an additive API — `.run()` is unchanged.
+     *
+     * @example
+     * for await (const event of flow.stream(shared)) {
+     *   if (event.type === "chunk") process.stdout.write(event.data);
+     * }
+     */
+    stream(shared: S, params?: P, options?: RunOptions): AsyncGenerator<StreamEvent<S>>;
+    protected _execute(shared: S, params: P, signal?: AbortSignal): Promise<void>;
+    private _addFn;
+    /** Resolve a NumberOrFn value against the current shared state and params. */
+    private _res;
+    private _runSub;
+    private _retry;
+    private _withTimeout;
+}
+
+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 };

package/dist/index.d.ts

@@ -1,226 +1,2 @@
-/**
- * Generic validator interface — structurally compatible with Zod, ArkType,
- * Valibot, or any custom implementation that exposes `.parse(input)`.
- * Used by `withStructuredOutput` and output parsers.
- */
-interface Validator<T = unknown> {
-    parse(input: unknown): T;
-}
-/**
- * Events yielded by `FlowBuilder.stream()`.
- */
-type StreamEvent<S = any> = {
-    type: "step:before";
-    meta: StepMeta;
-} | {
-    type: "step:after";
-    meta: StepMeta;
-    shared: S;
-} | {
-    type: "chunk";
-    data: unknown;
-} | {
-    type: "error";
-    error: unknown;
-} | {
-    type: "done";
-};
-/**
- * Function signature for all step logic.
- * Return an action string to route, or undefined/void to continue.
- */
-type NodeFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = (shared: S, params: P) => Promise<string | undefined | void> | string | undefined | void;
-/**
- * A numeric value or a function that computes it from the current shared state
- * and params. Use functions for dynamic per-item behaviour, e.g.
- * `retries: (s) => (s.__batchItem % 3 === 0 ? 3 : 1)`.
- */
-type NumberOrFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = number | ((shared: S, params: P) => number);
-interface NodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
-    retries?: NumberOrFn<S, P>;
-    delaySec?: NumberOrFn<S, P>;
-    timeoutMs?: NumberOrFn<S, P>;
-}
-interface RunOptions {
-    signal?: AbortSignal;
-}
-interface FnStep<S, P extends Record<string, unknown>> {
-    type: "fn";
-    fn: NodeFn<S, P>;
-    retries: NumberOrFn<S, P>;
-    delaySec: NumberOrFn<S, P>;
-    timeoutMs: NumberOrFn<S, P>;
-}
-interface BranchStep<S, P extends Record<string, unknown>> {
-    type: "branch";
-    router: NodeFn<S, P>;
-    branches: Record<string, NodeFn<S, P>>;
-    retries: NumberOrFn<S, P>;
-    delaySec: NumberOrFn<S, P>;
-    timeoutMs: NumberOrFn<S, P>;
-}
-interface LoopStep<S, P extends Record<string, unknown>> {
-    type: "loop";
-    condition: (shared: S, params: P) => Promise<boolean> | boolean;
-    body: FlowBuilder<S, P>;
-}
-interface BatchStep<S, P extends Record<string, unknown>> {
-    type: "batch";
-    itemsExtractor: (shared: S, params: P) => Promise<any[]> | any[];
-    processor: FlowBuilder<S, P>;
-    key: string;
-}
-interface ParallelStep<S, P extends Record<string, unknown>> {
-    type: "parallel";
-    fns: NodeFn<S, P>[];
-    retries: NumberOrFn<S, P>;
-    delaySec: NumberOrFn<S, P>;
-    timeoutMs: NumberOrFn<S, P>;
-    reducer?: (shared: S, drafts: S[]) => void;
-}
-interface AnchorStep {
-    type: "anchor";
-    name: string;
-}
-type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P> | LoopStep<S, P> | BatchStep<S, P> | ParallelStep<S, P> | AnchorStep;
-/** Metadata exposed to hooks — intentionally minimal to avoid coupling. */
-interface StepMeta {
-    index: number;
-    type: Step<any, any>["type"];
-    label?: string;
-}
-/** Lifecycle hooks that plugins can register. */
-interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
-    /** Fires once before the first step runs. */
-    beforeFlow?: (shared: S, params: P) => void | Promise<void>;
-    beforeStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
-    /**
-     * Wraps step execution — call `next()` to invoke the step body.
-     * Omitting `next()` skips execution (dry-run, mock, etc.).
-     * Multiple `wrapStep` registrations are composed innermost-first.
-     */
-    wrapStep?: (meta: StepMeta, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
-    afterStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
-    /**
-     * Wraps individual functions within a `.parallel()` step.
-     * `fnIndex` is the position within the fns array.
-     */
-    wrapParallelFn?: (meta: StepMeta, fnIndex: number, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
-    onError?: (meta: StepMeta, error: unknown, shared: S, params: P) => void;
-    afterFlow?: (shared: S, params: P) => void | Promise<void>;
-}
-/**
- * A plugin is an object whose keys become methods on `FlowBuilder.prototype`.
- * Each method receives the builder as `this` and should return `this` for chaining.
- *
- * Use declaration merging to get type-safe access:
- * ```ts
- * declare module "flowneer" {
- *   interface FlowBuilder<S, P> { withTracing(fn: TraceCallback): this; }
- * }
- * ```
- */
-type FlowneerPlugin = Record<string, (this: FlowBuilder<any, any>, ...args: any[]) => any>;
-/** Wraps step failures with context about which step failed. */
-declare class FlowError extends Error {
-    readonly step: string;
-    readonly cause: unknown;
-    constructor(step: string, cause: unknown);
-}
-/**
- * Thrown by `interruptIf` to pause a flow.
- * Catch this in your runner to save `savedShared` and resume later.
- */
-declare class InterruptError extends Error {
-    readonly savedShared: unknown;
-    constructor(shared: unknown);
-}
-/**
- * Fluent builder for composable flows.
- *
- * Steps execute sequentially in the order added. Call `.run(shared)` to execute.
- *
- * **Shared-state safety**: all steps operate on the same shared object.
- * Mutate it directly; avoid spreading/replacing the entire object.
- */
-declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
-    private steps;
-    private _hooksList;
-    /** Cached flat arrays of present hooks — invalidated whenever a hook is added. */
-    private _cachedHooks;
-    private _getHooks;
-    /** Register a plugin — copies its methods onto `FlowBuilder.prototype`. */
-    static use(plugin: FlowneerPlugin): void;
-    /** Register lifecycle hooks (called by plugin methods, not by consumers). */
-    protected _setHooks(hooks: Partial<FlowHooks<S, P>>): void;
-    /** Set the first step, resetting any prior chain. */
-    startWith(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
-    /** Append a sequential step. */
-    then(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
-    /**
-     * Append a routing step.
-     * `router` returns a key; the matching branch flow executes, then the chain continues.
-     */
-    branch(router: NodeFn<S, P>, branches: Record<string, NodeFn<S, P>>, options?: NodeOptions<S, P>): this;
-    /**
-     * Append a looping step.
-     * Repeatedly runs `body` while `condition` returns true.
-     */
-    loop(condition: (shared: S, params: P) => Promise<boolean> | boolean, body: (b: FlowBuilder<S, P>) => void): this;
-    /**
-     * Append a batch step.
-     * Runs `processor` once per item extracted by `items`, setting
-     * `shared[key]` each time (defaults to `"__batchItem"`).
-     *
-     * Use a unique `key` when nesting batches so each level has its own
-     * namespace:
-     * ```ts
-     * .batch(s => s.users, b => b
-     *   .startWith(s => { console.log(s.__batch_user); })
-     *   .batch(s => s.__batch_user.posts, p => p
-     *     .startWith(s => { console.log(s.__batch_post); })
-     *   , { key: '__batch_post' })
-     * , { key: '__batch_user' })
-     * ```
-     */
-    batch(items: (shared: S, params: P) => Promise<any[]> | any[], processor: (b: FlowBuilder<S, P>) => void, options?: {
-        key?: string;
-    }): this;
-    /**
-     * Append a parallel step.
-     * Runs all `fns` concurrently against the same shared state.
-     *
-     * When `reducer` is provided each fn receives its own shallow clone of
-     * `shared`; after all fns complete the reducer merges the drafts back
-     * into the original shared object — preventing concurrent mutation races.
-     */
-    parallel(fns: NodeFn<S, P>[], options?: NodeOptions<S, P>, reducer?: (shared: S, drafts: S[]) => void): this;
-    /**
-     * Insert a named anchor. Anchors are no-op markers that can be jumped to
-     * from any `NodeFn` by returning `"#anchorName"`.
-     */
-    anchor(name: string): this;
-    /** Execute the flow. */
-    run(shared: S, params?: P, options?: RunOptions): Promise<void>;
-    /**
-     * Execute the flow and yield `StreamEvent`s as an async generator.
-     *
-     * Events include `step:before`, `step:after`, `chunk` (from `emit()`),
-     * `error`, and `done`. This is an additive API — `.run()` is unchanged.
-     *
-     * @example
-     * for await (const event of flow.stream(shared)) {
-     *   if (event.type === "chunk") process.stdout.write(event.data);
-     * }
-     */
-    stream(shared: S, params?: P, options?: RunOptions): AsyncGenerator<StreamEvent<S>>;
-    protected _execute(shared: S, params: P, signal?: AbortSignal): Promise<void>;
-    private _addFn;
-    /** Resolve a NumberOrFn value against the current shared state and params. */
-    private _res;
-    private _runSub;
-    private _retry;
-    private _withTimeout;
-}
-
-export { FlowBuilder, FlowError, type FlowHooks, type FlowneerPlugin, InterruptError, type NodeFn, type NodeOptions, type NumberOrFn, type RunOptions, type StepMeta, type StreamEvent, type Validator };
+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-Dqppgla9.js';
+export { FlowError, Fragment, InterruptError, fragment } from './src/index.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-// Flowneer.ts
+// src/errors.ts
 var FlowError = class extends Error {
   step;
   cause;
@@ -19,6 +19,8 @@ var InterruptError = class extends Error {
     this.savedShared = shared;
   }
 };
+
+// src/FlowBuilder.ts
 var FlowBuilder = class _FlowBuilder {
   steps = [];
   _hooksList = [];
@@ -64,6 +66,29 @@ var FlowBuilder = class _FlowBuilder {
   then(fn, options) {
     return this._addFn(fn, options);
   }
+  /**
+   * Splice all steps from a `Fragment` into this flow at the current position.
+   *
+   * Fragments are reusable partial flows created with the `fragment()` factory.
+   * Steps are copied by reference (same semantics as `loop` / `batch` inners).
+   *
+   * @example
+   * ```ts
+   * const enrich = fragment<S>()
+   *   .then(fetchUser)
+   *   .then(enrichProfile);
+   *
+   * new FlowBuilder<S>()
+   *   .then(init)
+   *   .add(enrich)
+   *   .then(finalize)
+   *   .run(shared);
+   * ```
+   */
+  add(frag) {
+    for (const step of frag.steps) this.steps.push(step);
+    return this;
+  }
   /**
    * Append a routing step.
    * `router` returns a key; the matching branch flow executes, then the chain continues.
@@ -192,7 +217,7 @@ var FlowBuilder = class _FlowBuilder {
       push({ type: "chunk", data: chunk });
       if (typeof prevStream === "function") prevStream(chunk);
     };
-    const flowDone = this.run(shared, params, options).catch((err) => push({ type: "error", error: err })).then(() => push(null));
+    this.run(shared, params, options).catch((err) => push({ type: "error", error: err })).then(() => push(null));
     while (true) {
       await pull();
       while (queue.length > 0) {
@@ -233,8 +258,18 @@ var FlowBuilder = class _FlowBuilder {
                 this._res(step.delaySec, 0, shared, params),
                 () => step.fn(shared, params)
               );
-              if (typeof result === "string" && result[0] === "#")
+              if (result != null && typeof result[Symbol.asyncIterator] === "function") {
+                const gen = result;
+                let genResult = await gen.next();
+                while (!genResult.done) {
+                  shared.__stream?.(genResult.value);
+                  genResult = await gen.next();
+                }
+                if (typeof genResult.value === "string" && genResult.value[0] === "#")
+                  gotoTarget = genResult.value.slice(1);
+              } else if (typeof result === "string" && result[0] === "#") {
                 gotoTarget = result.slice(1);
+              }
               break;
             }
             case "branch": {
@@ -392,8 +427,29 @@ var FlowBuilder = class _FlowBuilder {
     ]);
   }
 };
+
+// src/Fragment.ts
+var Fragment = class extends FlowBuilder {
+  /** @internal Fragments cannot be run — embed them via `.add()`. */
+  async run(_shared, _params) {
+    throw new Error(
+      "Fragment cannot be run directly \u2014 use .add() to embed it in a FlowBuilder"
+    );
+  }
+  /** @internal Fragments cannot be streamed — embed them via `.add()`. */
+  async *stream(_shared, _params) {
+    throw new Error(
+      "Fragment cannot be streamed directly \u2014 use .add() to embed it in a FlowBuilder"
+    );
+  }
+};
+function fragment() {
+  return new Fragment();
+}
 export {
   FlowBuilder,
   FlowError,
-  InterruptError
+  Fragment,
+  InterruptError,
+  fragment
 };

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

@@ -1,4 +1,4 @@
-import { FlowneerPlugin, FlowBuilder, NodeFn } from '../../index.js';
+import { b as FlowneerPlugin, F as FlowBuilder, N as NodeFn } from '../../FlowBuilder-Dqppgla9.js';
 import { ToolCall, ToolResult } from '../tools/index.js';
 
 /**

package/dist/plugins/agent/index.js

@@ -80,7 +80,7 @@ var withReActLoop = {
   }
 };
 
-// Flowneer.ts
+// src/errors.ts
 var FlowError = class extends Error {
   step;
   cause;
@@ -101,6 +101,8 @@ var InterruptError = class extends Error {
     this.savedShared = shared;
   }
 };
+
+// src/FlowBuilder.ts
 var FlowBuilder = class _FlowBuilder {
   steps = [];
   _hooksList = [];
@@ -146,6 +148,29 @@ var FlowBuilder = class _FlowBuilder {
   then(fn, options) {
     return this._addFn(fn, options);
   }
+  /**
+   * Splice all steps from a `Fragment` into this flow at the current position.
+   *
+   * Fragments are reusable partial flows created with the `fragment()` factory.
+   * Steps are copied by reference (same semantics as `loop` / `batch` inners).
+   *
+   * @example
+   * ```ts
+   * const enrich = fragment<S>()
+   *   .then(fetchUser)
+   *   .then(enrichProfile);
+   *
+   * new FlowBuilder<S>()
+   *   .then(init)
+   *   .add(enrich)
+   *   .then(finalize)
+   *   .run(shared);
+   * ```
+   */
+  add(frag) {
+    for (const step of frag.steps) this.steps.push(step);
+    return this;
+  }
   /**
    * Append a routing step.
    * `router` returns a key; the matching branch flow executes, then the chain continues.
@@ -274,7 +299,7 @@ var FlowBuilder = class _FlowBuilder {
       push({ type: "chunk", data: chunk });
       if (typeof prevStream === "function") prevStream(chunk);
     };
-    const flowDone = this.run(shared, params, options).catch((err) => push({ type: "error", error: err })).then(() => push(null));
+    this.run(shared, params, options).catch((err) => push({ type: "error", error: err })).then(() => push(null));
     while (true) {
       await pull();
       while (queue.length > 0) {
@@ -315,8 +340,18 @@ var FlowBuilder = class _FlowBuilder {
                 this._res(step.delaySec, 0, shared, params),
                 () => step.fn(shared, params)
               );
-              if (typeof result === "string" && result[0] === "#")
+              if (result != null && typeof result[Symbol.asyncIterator] === "function") {
+                const gen = result;
+                let genResult = await gen.next();
+                while (!genResult.done) {
+                  shared.__stream?.(genResult.value);
+                  genResult = await gen.next();
+                }
+                if (typeof genResult.value === "string" && genResult.value[0] === "#")
+                  gotoTarget = genResult.value.slice(1);
+              } else if (typeof result === "string" && result[0] === "#") {
                 gotoTarget = result.slice(1);
+              }
               break;
             }
             case "branch": {