flowneer 0.9.0 → 0.9.2

package/dist/{FlowBuilder-B_BIRk3f.d.ts → FlowBuilder-G67AbbRt.d.ts}

@@ -62,7 +62,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;
 }
 /**
@@ -166,7 +166,35 @@ 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"]>[];
@@ -212,17 +240,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).
@@ -238,8 +279,8 @@ declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Recor
      * The base class prototype is never touched, so different `extend()`
      * calls are fully isolated from each other.
      *
-     * Plugins are applied in array order; later entries can override earlier
-     * ones for the same method name.
+     * Duplicate method names across plugins (or colliding with an existing
+     * prototype method) throw immediately to prevent silent overwrites.
      *
      * @example
      * const AppFlow = FlowBuilder.extend([withTiming, withRateLimit]);
@@ -354,4 +395,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 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 };

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-B_BIRk3f.js';
+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-G67AbbRt.js';
 export { Fragment, fragment } from './src/index.js';
 export { F as FlowError, I as InterruptError } from './errors-u-hq7p5N.js';

package/dist/index.js

@@ -23,15 +23,13 @@ var InterruptError = class extends Error {
 // src/core/utils.ts
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
-  if (meta.label === void 0) return false;
   const label = meta.label;
-  return filter.some((pattern) => {
-    if (!pattern.includes("*")) return pattern === label;
-    const re = new RegExp(
-      "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
-    );
-    return re.test(label);
-  });
+  if (label === void 0) return false;
+  return filter.some(
+    (p) => p.includes("*") ? new RegExp(
+      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+    ).test(label) : p === label
+  );
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -124,18 +122,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
@@ -166,8 +176,8 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
    * The base class prototype is never touched, so different `extend()`
    * calls are fully isolated from each other.
    *
-   * Plugins are applied in array order; later entries can override earlier
-   * ones for the same method name.
+   * Duplicate method names across plugins (or colliding with an existing
+   * prototype method) throw immediately to prevent silent overwrites.
    *
    * @example
    * const AppFlow = FlowBuilder.extend([withTiming, withRateLimit]);
@@ -179,11 +189,16 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   static extend(plugins) {
     const Extended = class extends this {
     };
+    const methods = {};
     for (const plugin of plugins) {
       for (const [name, fn] of Object.entries(plugin)) {
-        Extended.prototype[name] = fn;
+        if (name in methods || name in Extended.prototype) {
+          throw new Error(`Plugin method collision: "${name}"`);
+        }
+        methods[name] = fn;
       }
     }
+    Object.assign(Extended.prototype, methods);
     return Extended;
   }
   // -------------------------------------------------------------------------
@@ -260,6 +275,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,

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

@@ -1,4 +1,4 @@
-import { F as FlowBuilder, a as FlowneerPlugin } from '../../FlowBuilder-B_BIRk3f.js';
+import { F as FlowBuilder, a as FlowneerPlugin } from '../../FlowBuilder-G67AbbRt.js';
 
 interface HumanNodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     /**

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

@@ -1,5 +1,5 @@
-import { a as FnRegistry, b as ValidationResult } from '../../schema-DFNzcQP5.js';
-export { A as AnchorStepConfig, B as BatchStepConfig, c as BranchStepConfig, F as FlowConfig, d as FnStepConfig, L as LoopStepConfig, P as ParallelStepConfig, S as StepConfig, V as ValidationError } from '../../schema-DFNzcQP5.js';
+import { a as FnRegistry, b as ValidationResult } from '../../schema-CIqQAXqY.js';
+export { A as AnchorStepConfig, B as BatchStepConfig, c as BranchStepConfig, F as FlowConfig, d as FnStepConfig, L as LoopStepConfig, P as ParallelStepConfig, S as StepConfig, V as ValidationError } from '../../schema-CIqQAXqY.js';
 
 /**
  * Validate a raw config object + registry without building anything.

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-B_BIRk3f.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions, S as StepFilter } from '../../FlowBuilder-G67AbbRt.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
@@ -130,4 +130,39 @@ declare module "../../Flowneer" {
 }
 declare const withFlowAnalyzer: FlowneerPlugin;
 
-export { type PathMap, type PathNode, type TraceEvent, type TraceHandle, type TraceReport, withAtomicUpdates, withDryRun, withFlowAnalyzer, withMocks, withStepLimit };
+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;
+}
+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.
+         *
+         * @param filter  Limit to specific steps by label or predicate (optional).
+         * @param hooks   Which lifecycle points to pause at. Defaults to `{ beforeStep: true }`.
+         *
+         * @example
+         * // Pause before every step
+         * new AppFlow().withDebugger().then(myStep).run(shared);
+         *
+         * @example
+         * // Pause only on "llm:*" steps, before and after
+         * new AppFlow()
+         *   .withDebugger(["llm:*"], { beforeStep: true, afterStep: true })
+         *   .then(callLlm)
+         *   .run(shared);
+         */
+        withDebugger(filter?: StepFilter, hooks?: DebuggerHooks): this;
+    }
+}
+declare const withDebugger: FlowneerPlugin;
+
+export { type DebuggerHooks, type PathMap, type PathNode, type TraceEvent, type TraceHandle, type TraceReport, withAtomicUpdates, withDebugger, withDryRun, withFlowAnalyzer, withMocks, withStepLimit };

package/dist/plugins/dev/index.js

@@ -179,8 +179,40 @@ 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;
+      };
+    }
+    this._setHooks(registered, filter);
+    return this;
+  }
+};
 export {
   withAtomicUpdates,
+  withDebugger,
   withDryRun,
   withFlowAnalyzer,
   withMocks,

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

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