flowneer 0.9.1 → 0.9.4

package/dist/{FlowBuilder-CqWK42bA.d.ts → FlowBuilder-8kwREeyD.d.ts}

@@ -1,3 +1,17 @@
+/**
+ * Extendable shared-state interface augmented by each plugin via declaration
+ * merging. Extend your state type with this to get all plugin-provided keys
+ * typed and documented automatically — no manual `__*` declarations needed.
+ *
+ * @example
+ * import type { AugmentedState } from "flowneer";
+ * interface MyState extends AugmentedState {
+ *   topic: string;
+ *   results: string[];
+ * }
+ */
+interface AugmentedState {
+}
 /**
  * Generic validator interface — structurally compatible with Zod, ArkType,
  * Valibot, or any custom implementation that exposes `.parse(input)`.
@@ -62,7 +76,7 @@ interface RunOptions {
 /** Metadata exposed to hooks — intentionally minimal to avoid coupling. */
 interface StepMeta {
     index: number;
-    type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor";
+    type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor" | "dag";
     label?: string;
 }
 /**
@@ -105,8 +119,18 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
      * `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;
+    onError?: (meta: StepMeta, error: unknown, shared: S, params: P) => void | Promise<void>;
     afterFlow?: (shared: S, params: P) => void | Promise<void>;
+    /**
+     * Fires after each loop iteration completes. `iteration` is zero-based.
+     * Only fires for `.loop()` steps, not `.batch()` or `.parallel()`.
+     */
+    onLoopIteration?: (meta: StepMeta, iteration: number, shared: S, params: P) => void | Promise<void>;
+    /**
+     * Fires when a goto jump resolves to an anchor (i.e. a step returned `"#anchorName"`).
+     * `anchorName` is the anchor label without the `#` prefix.
+     */
+    onAnchorHit?: (anchorName: string, shared: S, params: P) => void | Promise<void>;
 }
 /**
  * A plugin is an object whose keys become methods on a `FlowBuilder.extend()` subclass prototype.
@@ -120,6 +144,17 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
  * ```
  */
 type FlowneerPlugin = Record<string, (this: FlowBuilder<any, any>, ...args: any[]) => any>;
+type ResolvedHooks<S, P extends Record<string, unknown>> = {
+    beforeFlow: NonNullable<FlowHooks<S, P>["beforeFlow"]>[];
+    beforeStep: NonNullable<FlowHooks<S, P>["beforeStep"]>[];
+    wrapStep: NonNullable<FlowHooks<S, P>["wrapStep"]>[];
+    afterStep: NonNullable<FlowHooks<S, P>["afterStep"]>[];
+    wrapParallelFn: NonNullable<FlowHooks<S, P>["wrapParallelFn"]>[];
+    onError: NonNullable<FlowHooks<S, P>["onError"]>[];
+    afterFlow: NonNullable<FlowHooks<S, P>["afterFlow"]>[];
+    onLoopIteration: NonNullable<FlowHooks<S, P>["onLoopIteration"]>[];
+    onAnchorHit: NonNullable<FlowHooks<S, P>["onAnchorHit"]>[];
+};
 
 interface FnStep<S, P extends Record<string, unknown>> {
     type: "fn";
@@ -166,17 +201,36 @@ interface AnchorStep {
     /** Maximum number of times a goto may jump to this anchor per run. */
     maxVisits?: number;
 }
-type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P> | LoopStep<S, P> | BatchStep<S, P> | ParallelStep<S, P> | AnchorStep;
+/**
+ * A compiled DAG step. Produced by the graph plugin's `.compile()` and
+ * executed by the registered "dag" step handler, which traverses nodes
+ * in topological order and fires per-node lifecycle hooks natively.
+ */
+interface DagStep<S, P extends Record<string, unknown>> {
+    type: "dag";
+    nodes: Map<string, {
+        name: string;
+        fn: NodeFn<S, P>;
+        options?: NodeOptions<S, P>;
+    }>;
+    /** Topologically sorted node names. */
+    order: string[];
+    /** Conditional edges that point backwards (cycles). Always have a condition. */
+    backEdges: Array<{
+        from: string;
+        to: string;
+        condition: (shared: S, params: P) => boolean | Promise<boolean>;
+    }>;
+    /** Conditional edges that skip forward (not back-edges). Always have a condition. */
+    conditionalForward: Array<{
+        from: string;
+        to: string;
+        condition: (shared: S, params: P) => boolean | Promise<boolean>;
+    }>;
+    label?: 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 | DagStep<S, P>;
 
-type ResolvedHooks<S, P extends Record<string, unknown>> = {
-    beforeFlow: NonNullable<FlowHooks<S, P>["beforeFlow"]>[];
-    beforeStep: NonNullable<FlowHooks<S, P>["beforeStep"]>[];
-    wrapStep: NonNullable<FlowHooks<S, P>["wrapStep"]>[];
-    afterStep: NonNullable<FlowHooks<S, P>["afterStep"]>[];
-    wrapParallelFn: NonNullable<FlowHooks<S, P>["wrapParallelFn"]>[];
-    onError: NonNullable<FlowHooks<S, P>["onError"]>[];
-    afterFlow: NonNullable<FlowHooks<S, P>["afterFlow"]>[];
-};
 /**
  * Runtime context passed to every registered step handler.
  * Full access to the builder so handlers can run sub-flows etc.
@@ -212,17 +266,30 @@ declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Recor
     private _hooksList;
     private _hooksCache;
     private static _stepHandlers;
+    /**
+     * Step types registered with `{ transparent: true }` are invoked directly
+     * by `_execute` without wrapping in the outer beforeStep/wrapStep/afterStep
+     * lifecycle. Use this for step types that manage per-item lifecycle
+     * internally (e.g. a DAG handler that fires hooks once per graph node).
+     */
+    private static _transparentSteps;
     /**
      * Register a handler for a custom step type.
      * Called once at module load time from each step plugin.
      *
+     * Pass `{ transparent: true }` when the handler manages its own per-item
+     * lifecycle hooks internally and should not be wrapped by the outer
+     * beforeStep / wrapStep / afterStep guards.
+     *
      * @example
      * CoreFlowBuilder.registerStepType("myStep", async (step, ctx) => {
      *   await doWork(ctx.shared);
      *   return undefined;
      * });
      */
-    static registerStepType(type: string, handler: StepHandler): void;
+    static registerStepType(type: string, handler: StepHandler, options?: {
+        transparent?: boolean;
+    }): void;
     private _hooks;
     /**
      * Register lifecycle hooks (called by plugin methods, not by consumers).
@@ -354,4 +421,4 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
     private _addFn;
 }
 
-export { type AnchorStep as A, type BatchStep as B, CoreFlowBuilder as C, FlowBuilder as F, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type ResolvedHooks as R, type StepFilter as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type StepMeta as d, type BranchStep as e, type FnStep as f, type NumberOrFn as g, type RunOptions as h, type Step as i, type StepContext as j, type StepHandler as k, type StreamEvent as l };
+export { type AnchorStep as A, type BatchStep as B, CoreFlowBuilder as C, type DagStep as D, FlowBuilder as F, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type ResolvedHooks as R, type StepFilter as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type StepMeta as d, type AugmentedState as e, type BranchStep as f, type FnStep as g, type NumberOrFn as h, type RunOptions as i, type Step as j, type StepContext as k, type StepHandler as l, type StreamEvent as m };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, g as NumberOrFn, h as RunOptions, d as StepMeta, l as StreamEvent, V as Validator } from './FlowBuilder-CqWK42bA.js';
+export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, h as NumberOrFn, i as RunOptions, d as StepMeta, m as StreamEvent, V as Validator } from './FlowBuilder-8kwREeyD.js';
 export { Fragment, fragment } from './src/index.js';
 export { F as FlowError, I as InterruptError } from './errors-u-hq7p5N.js';

package/dist/index.js

@@ -97,6 +97,7 @@ function applyStepFilter(hooks, filter) {
   wrap("onError");
   wrap("wrapStep", (_m, next) => next());
   wrap("wrapParallelFn", (_m, _fi, next) => next());
+  wrap("onLoopIteration");
   return hooks;
 }
 function buildHookCache(list) {
@@ -108,7 +109,9 @@ function buildHookCache(list) {
     afterStep: pick("afterStep"),
     wrapParallelFn: pick("wrapParallelFn"),
     onError: pick("onError"),
-    afterFlow: pick("afterFlow")
+    afterFlow: pick("afterFlow"),
+    onLoopIteration: pick("onLoopIteration"),
+    onAnchorHit: pick("onAnchorHit")
   };
 }
 var CoreFlowBuilder = class _CoreFlowBuilder {
@@ -122,18 +125,30 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   // Step-type registry (static — shared across all instances)
   // -------------------------------------------------------------------------
   static _stepHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Step types registered with `{ transparent: true }` are invoked directly
+   * by `_execute` without wrapping in the outer beforeStep/wrapStep/afterStep
+   * lifecycle. Use this for step types that manage per-item lifecycle
+   * internally (e.g. a DAG handler that fires hooks once per graph node).
+   */
+  static _transparentSteps = /* @__PURE__ */ new Set();
   /**
    * Register a handler for a custom step type.
    * Called once at module load time from each step plugin.
    *
+   * Pass `{ transparent: true }` when the handler manages its own per-item
+   * lifecycle hooks internally and should not be wrapped by the outer
+   * beforeStep / wrapStep / afterStep guards.
+   *
    * @example
    * CoreFlowBuilder.registerStepType("myStep", async (step, ctx) => {
    *   await doWork(ctx.shared);
    *   return undefined;
    * });
    */
-  static registerStepType(type, handler) {
+  static registerStepType(type, handler, options) {
     _CoreFlowBuilder._stepHandlers.set(type, handler);
+    if (options?.transparent) _CoreFlowBuilder._transparentSteps.add(type);
   }
   // -------------------------------------------------------------------------
   // Hooks & plugins
@@ -263,6 +278,25 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
       signal?.throwIfAborted();
       const step = this.steps[i];
       if (step.type === "anchor") continue;
+      if (_CoreFlowBuilder._transparentSteps.has(step.type)) {
+        const handler = _CoreFlowBuilder._stepHandlers.get(step.type);
+        if (handler) {
+          const meta2 = {
+            index: i,
+            type: step.type,
+            label: step.label
+          };
+          await handler(step, {
+            shared,
+            params,
+            signal,
+            hooks,
+            meta: meta2,
+            builder: this
+          });
+        }
+        continue;
+      }
       const stepLabel = step.label;
       const meta = {
         index: i,
@@ -294,10 +328,12 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
               );
           }
           i = target;
+          for (const h of hooks.onAnchorHit)
+            await h(gotoTarget, shared, params);
         }
       } catch (err) {
         if (err instanceof InterruptError) throw err;
-        for (const h of hooks.onError) h(meta, err, shared, params);
+        for (const h of hooks.onError) await h(meta, err, shared, params);
         if (err instanceof FlowError) throw err;
         const labelPart = stepLabel ? `"${stepLabel}" ` : "";
         const label = step.type === "fn" ? `${labelPart}step ${i}` : `${labelPart}${step.type} (step ${i})`;
@@ -385,12 +421,16 @@ var branchHandler = async (step, { shared, params }) => {
 };
 
 // src/core/steps/loop.ts
-var loopHandler = async (step, { shared, params, signal, meta, builder }) => {
-  while (await step.condition(shared, params))
+var loopHandler = async (step, { shared, params, signal, meta, hooks, builder }) => {
+  let iteration = 0;
+  while (await step.condition(shared, params)) {
     await builder._runSub(
       `loop (step ${meta.index})`,
       () => step.body._execute(shared, params, signal)
     );
+    for (const h of hooks.onLoopIteration)
+      await h(meta, iteration++, shared, params);
+  }
   return void 0;
 };
 

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

@@ -1,4 +1,4 @@
-import { F as FlowBuilder, a as FlowneerPlugin } from '../../FlowBuilder-CqWK42bA.js';
+import { F as FlowBuilder, a as FlowneerPlugin } from '../../FlowBuilder-8kwREeyD.js';
 
 interface HumanNodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     /**
@@ -45,6 +45,12 @@ declare module "../../Flowneer" {
          */
         humanNode(options?: HumanNodeOptions<S, P>): this;
     }
+    interface AugmentedState {
+        /** Prompt/question for the human reviewer. Written by `.humanNode()` before interrupting. */
+        __humanPrompt?: string;
+        /** Human-provided response. Write this onto the saved shared state before calling `resumeFlow()`. */
+        __humanFeedback?: string;
+    }
 }
 declare const withHumanNode: FlowneerPlugin;
 /**

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions, S as StepFilter } from '../../FlowBuilder-CqWK42bA.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions, S as StepFilter } from '../../FlowBuilder-8kwREeyD.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
@@ -130,39 +130,118 @@ declare module "../../Flowneer" {
 }
 declare const withFlowAnalyzer: FlowneerPlugin;
 
-interface DebuggerHooks {
-    /** Pause before a step runs. Default: `true`. */
-    beforeStep?: boolean;
-    /** Pause after a step completes. Default: `false`. */
-    afterStep?: boolean;
-    /** Pause when a step throws. Default: `false`. */
-    onError?: boolean;
-    /** Pause once before the step body and once after (inside the wrapper). Default: `false`. */
-    wrapStep?: boolean;
+/** Per-step performance snapshot recorded by `.withPerfAnalyzer()`. */
+interface StepPerfStats {
+    /** Step index (0-based). */
+    index: number;
+    /** Step type: "fn" | "branch" | "loop" | "batch" | "parallel" | "dag". */
+    type: string;
+    /** Step label if set via `NodeOptions.label`. */
+    label?: string;
+    /** Wall-clock duration in ms (high-res via `performance.now()`). */
+    durationMs: number;
+    /** User-space CPU time consumed during this step (ms). 0 on non-Node runtimes. */
+    cpuUserMs: number;
+    /** Kernel CPU time consumed during this step (ms). 0 on non-Node runtimes. */
+    cpuSystemMs: number;
+    /** V8 heap used at step start (bytes). */
+    heapUsedBefore: number;
+    /** V8 heap used at step end (bytes). */
+    heapUsedAfter: number;
+    /**
+     * Net change in V8 heap usage (bytes, positive = allocated, negative = freed
+     * due to a GC cycle that completed during the step).
+     */
+    heapDeltaBytes: number;
+    /** Net change in Resident Set Size (bytes). */
+    rssDeltaBytes: number;
+    /** Net change in external (C++ / Buffer) memory bound to V8 (bytes). */
+    externalDeltaBytes: number;
+    /**
+     * Number of GC events accumulated since last step end. Best-effort; see
+     * module note regarding async PerformanceObserver delivery.
+     */
+    gcCount: number;
+    /** Total GC pause duration attributed to this step (ms). Best-effort. */
+    gcDurationMs: number;
+    /** `true` if the step threw an error (stats still recorded via finally). */
+    threw: boolean;
+}
+/** Flow-level performance summary written to `shared.__perfReport`. */
+interface PerfReport {
+    /** Sum of all step `durationMs` (includes parallel overlap). */
+    totalDurationMs: number;
+    /** Sum of all step `cpuUserMs`. */
+    totalCpuUserMs: number;
+    /** Sum of all step `cpuSystemMs`. */
+    totalCpuSystemMs: number;
+    /** Sum of all GC pause durations across the flow (ms). */
+    totalGcDurationMs: number;
+    /** Total GC event count during the flow. */
+    totalGcCount: number;
+    /** Highest `heapUsedAfter` seen across all steps (bytes). */
+    peakHeapUsedBytes: number;
+    /** All per-step stats in execution order. */
+    steps: StepPerfStats[];
+    /** The step with the longest wall-clock duration, or `null` if no steps ran. */
+    slowest: StepPerfStats | null;
+    /** The step with the largest heap delta, or `null` if no steps ran. */
+    heaviest: StepPerfStats | null;
+}
+interface PerfAnalyzerOptions {
+    /**
+     * Track GC pause events via `PerformanceObserver`. Requires Node.js.
+     * @default true
+     */
+    trackGc?: boolean;
+    /**
+     * Called with the final `PerfReport` in `afterFlow`.
+     * Use this to log, persist, or ship metrics — formatting is left to the caller.
+     */
+    onReport?: (report: PerfReport) => void;
 }
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
         /**
-         * Drops a `debugger` statement at the selected lifecycle points.
-         * Attach DevTools / `--inspect` breakpoints and step through live flow state.
+         * Profiles each step using Node.js built-in performance APIs — no external
+         * dependencies.
          *
-         * @param filter  Limit to specific steps by label or predicate (optional).
-         * @param hooks   Which lifecycle points to pause at. Defaults to `{ beforeStep: true }`.
+         * Per step, records:
+         * - Wall-clock duration (`performance.now()`)
+         * - CPU user + system time (`process.cpuUsage()`)
+         * - Heap used delta (`process.memoryUsage().heapUsed`)
+         * - RSS and external memory delta
+         * - GC pause count + duration (`PerformanceObserver`, best-effort)
+         *
+         * Results are written to `shared.__perfStats` (array, in execution order)
+         * and `shared.__perfReport` (flow summary) when the flow completes.
          *
          * @example
-         * // Pause before every step
-         * new AppFlow().withDebugger().then(myStep).run(shared);
+         * const flow = new AppFlow<State>()
+         *   .withPerfAnalyzer({
+         *     onReport: (r) => console.log(JSON.stringify(r, null, 2)),
+         *   })
+         *   .then(fetchData, { label: "fetch" })
+         *   .then(callLlm,   { label: "llm:generate" })
+         *   .then(save,      { label: "save" });
+         *
+         * await flow.run(shared);
+         * // shared.__perfReport.slowest → { label: "llm:generate", durationMs: ... }
+         * // shared.__perfStats[0]       → { heapDeltaBytes: 2621440, cpuUserMs: 12 … }
          *
          * @example
-         * // Pause only on "llm:*" steps, before and after
-         * new AppFlow()
-         *   .withDebugger(["llm:*"], { beforeStep: true, afterStep: true })
-         *   .then(callLlm)
-         *   .run(shared);
+         * // Profile only LLM steps
+         * flow.withPerfAnalyzer({}, ["llm:*"])
          */
-        withDebugger(filter?: StepFilter, hooks?: DebuggerHooks): this;
+        withPerfAnalyzer(options?: PerfAnalyzerOptions, filter?: StepFilter): this;
+    }
+    interface AugmentedState {
+        /** Per-step perf stats written by `.withPerfAnalyzer()`. In execution order. */
+        __perfStats?: StepPerfStats[];
+        /** Flow-level perf summary written by `.withPerfAnalyzer()` on flow completion. */
+        __perfReport?: PerfReport;
     }
 }
-declare const withDebugger: FlowneerPlugin;
+declare const withPerfAnalyzer: FlowneerPlugin;
 
-export { type DebuggerHooks, type PathMap, type PathNode, type TraceEvent, type TraceHandle, type TraceReport, withAtomicUpdates, withDebugger, withDryRun, withFlowAnalyzer, withMocks, withStepLimit };
+export { type PathMap, type PathNode, type PerfAnalyzerOptions, type PerfReport, type StepPerfStats, type TraceEvent, type TraceHandle, type TraceReport, withAtomicUpdates, withDryRun, withFlowAnalyzer, withMocks, withPerfAnalyzer, withStepLimit };

package/dist/plugins/dev/index.js

@@ -180,41 +180,131 @@ var withFlowAnalyzer = {
   }
 };
 
-// plugins/dev/withDebugger.ts
-var withDebugger = {
-  withDebugger(filter, hooks = { beforeStep: true }) {
-    const registered = {};
-    if (hooks.beforeStep) {
-      registered.beforeStep = (meta, shared, params) => {
-        debugger;
-      };
-    }
-    if (hooks.afterStep) {
-      registered.afterStep = (meta, shared, params) => {
-        debugger;
-      };
-    }
-    if (hooks.onError) {
-      registered.onError = (meta, error, shared, params) => {
-        debugger;
-      };
-    }
-    if (hooks.wrapStep) {
-      registered.wrapStep = async (meta, next, shared, params) => {
-        debugger;
-        await next();
-        debugger;
-      };
+// plugins/dev/withPerfAnalyzer.ts
+import { performance, PerformanceObserver } from "perf_hooks";
+function cpuUsage() {
+  return process.cpuUsage?.() ?? {
+    user: 0,
+    system: 0
+  };
+}
+function cpuUsageDelta(start) {
+  return process.cpuUsage?.(start) ?? { user: 0, system: 0 };
+}
+function memUsage() {
+  return process.memoryUsage?.() ?? {
+    rss: 0,
+    heapTotal: 0,
+    heapUsed: 0,
+    external: 0,
+    arrayBuffers: 0
+  };
+}
+var withPerfAnalyzer = {
+  withPerfAnalyzer(options = {}, filter) {
+    const { trackGc = true, onReport } = options;
+    const gcLog = [];
+    let gcObserver = null;
+    if (trackGc) {
+      try {
+        gcObserver = new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            gcLog.push({
+              startTime: entry.startTime,
+              duration: entry.duration
+            });
+          }
+        });
+        gcObserver.observe({ entryTypes: ["gc"] });
+      } catch {
+      }
     }
-    this._setHooks(registered, filter);
+    const snapshots = /* @__PURE__ */ new Map();
+    this._setHooks(
+      {
+        wrapStep: async (meta, next, shared) => {
+          const gcMsBefore = gcLog.reduce((a, e) => a + e.duration, 0);
+          const t0 = performance.now();
+          const cpu0 = cpuUsage();
+          const mem0 = memUsage();
+          snapshots.set(meta.index, {
+            t0,
+            cpu0,
+            mem0,
+            gcLenBefore: gcLog.length,
+            gcMsBefore
+          });
+          let threw = false;
+          try {
+            await next();
+          } catch (e) {
+            threw = true;
+            throw e;
+          } finally {
+            const durationMs = performance.now() - t0;
+            const cpuDelta = cpuUsageDelta(cpu0);
+            const mem1 = memUsage();
+            const snap = snapshots.get(meta.index);
+            snapshots.delete(meta.index);
+            const gcMsAfter = gcLog.reduce((a, e) => a + e.duration, 0);
+            const gcCountAfter = gcLog.length;
+            const gcLenBefore = snap?.gcLenBefore ?? gcLog.length;
+            const gcMsSnap = snap?.gcMsBefore ?? gcMsAfter;
+            const stat = {
+              index: meta.index,
+              type: meta.type,
+              label: meta.label,
+              durationMs,
+              cpuUserMs: cpuDelta.user / 1e3,
+              cpuSystemMs: cpuDelta.system / 1e3,
+              heapUsedBefore: mem0.heapUsed,
+              heapUsedAfter: mem1.heapUsed,
+              heapDeltaBytes: mem1.heapUsed - mem0.heapUsed,
+              rssDeltaBytes: mem1.rss - mem0.rss,
+              externalDeltaBytes: mem1.external - mem0.external,
+              gcCount: gcCountAfter - gcLenBefore,
+              gcDurationMs: gcMsAfter - gcMsSnap,
+              threw
+            };
+            if (!shared.__perfStats) shared.__perfStats = [];
+            shared.__perfStats.push(stat);
+          }
+        },
+        afterFlow: (shared) => {
+          gcObserver?.disconnect();
+          const stats = shared.__perfStats ?? [];
+          const totalGcDurationMs = gcLog.reduce((a, e) => a + e.duration, 0);
+          const totalGcCount = gcLog.length;
+          const report = {
+            totalDurationMs: stats.reduce((a, s) => a + s.durationMs, 0),
+            totalCpuUserMs: stats.reduce((a, s) => a + s.cpuUserMs, 0),
+            totalCpuSystemMs: stats.reduce((a, s) => a + s.cpuSystemMs, 0),
+            totalGcDurationMs,
+            totalGcCount,
+            peakHeapUsedBytes: stats.reduce(
+              (a, s) => Math.max(a, s.heapUsedAfter),
+              0
+            ),
+            steps: stats,
+            slowest: stats.length > 0 ? stats.reduce((a, s) => s.durationMs > a.durationMs ? s : a) : null,
+            heaviest: stats.length > 0 ? stats.reduce(
+              (a, s) => s.heapDeltaBytes > a.heapDeltaBytes ? s : a
+            ) : null
+          };
+          shared.__perfReport = report;
+          onReport?.(report);
+        }
+      },
+      filter
+    );
     return this;
   }
 };
 export {
   withAtomicUpdates,
-  withDebugger,
   withDryRun,
   withFlowAnalyzer,
   withMocks,
+  withPerfAnalyzer,
   withStepLimit
 };

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

@@ -1,4 +1,4 @@
-import { F as FlowBuilder } from '../../FlowBuilder-CqWK42bA.js';
+import { F as FlowBuilder } from '../../FlowBuilder-8kwREeyD.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,4 @@
-import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-CqWK42bA.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-8kwREeyD.js';
 
 /** A single node entry in the exported graph. */
 interface GraphNodeExport {