flowneer 0.9.0 → 0.9.1

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

@@ -238,8 +238,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]);

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-CqWK42bA.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;
@@ -166,8 +164,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 +177,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;
   }
   // -------------------------------------------------------------------------

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-CqWK42bA.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-CqWK42bA.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-CqWK42bA.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-CqWK42bA.js';
 
 /** A single node entry in the exported graph. */
 interface GraphNodeExport {

package/dist/plugins/index.d.ts

@@ -11,10 +11,10 @@ export { parseJsonOutput, parseListOutput, parseMarkdownTable, parseRegexOutput
 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 { S as StepFilter, a as FlowneerPlugin, d as StepMeta, F as FlowBuilder } from '../FlowBuilder-B_BIRk3f.js';
+import { S as StepFilter, a as FlowneerPlugin, d as StepMeta, F as FlowBuilder } from '../FlowBuilder-CqWK42bA.js';
 import { F as FlowError } from '../errors-u-hq7p5N.js';
 export { validate } from './config/index.js';
-export { F as FlowConfig, a as FnRegistry, S as StepConfig, V as ValidationError, b as ValidationResult } from '../schema-DFNzcQP5.js';
+export { F as FlowConfig, a as FnRegistry, S as StepConfig, V as ValidationError, b as ValidationResult } from '../schema-CIqQAXqY.js';
 
 /**
  * Behaviour when a compliance violation is detected.

package/dist/plugins/index.js

@@ -33,52 +33,61 @@ var init_withReplay = __esm({
 
 // plugins/observability/withTiming.ts
 var withTiming = {
-  withTiming() {
+  withTiming(filter) {
     const starts = /* @__PURE__ */ new Map();
-    this._setHooks({
-      beforeStep: (meta) => {
-        starts.set(meta.index, Date.now());
+    this._setHooks(
+      {
+        beforeStep: (meta) => {
+          starts.set(meta.index, Date.now());
+        },
+        afterStep: (meta, shared) => {
+          const start = starts.get(meta.index) ?? Date.now();
+          if (!shared.__timings) shared.__timings = {};
+          shared.__timings[meta.index] = Date.now() - start;
+          starts.delete(meta.index);
+        }
       },
-      afterStep: (meta, shared) => {
-        const start = starts.get(meta.index) ?? Date.now();
-        if (!shared.__timings) shared.__timings = {};
-        shared.__timings[meta.index] = Date.now() - start;
-        starts.delete(meta.index);
-      }
-    });
+      filter
+    );
     return this;
   }
 };
 
 // plugins/observability/withHistory.ts
 var withHistory = {
-  withHistory() {
-    this._setHooks({
-      afterStep: (meta, shared) => {
-        if (!Array.isArray(shared.__history)) shared.__history = [];
-        const { __history: _h, ...rest } = shared;
-        shared.__history.push({
-          index: meta.index,
-          type: meta.type,
-          snapshot: { ...rest }
-        });
-      }
-    });
+  withHistory(filter) {
+    this._setHooks(
+      {
+        afterStep: (meta, shared) => {
+          if (!Array.isArray(shared.__history)) shared.__history = [];
+          const { __history: _h, ...rest } = shared;
+          shared.__history.push({
+            index: meta.index,
+            type: meta.type,
+            snapshot: { ...rest }
+          });
+        }
+      },
+      filter
+    );
     return this;
   }
 };
 
 // plugins/observability/withVerbose.ts
 var withVerbose = {
-  withVerbose() {
-    this._setHooks({
-      afterStep: (meta, shared) => {
-        console.log(
-          `[flowneer] step ${meta.index} (${meta.type}):`,
-          JSON.stringify(shared, null, 2)
-        );
-      }
-    });
+  withVerbose(filter) {
+    this._setHooks(
+      {
+        afterStep: (meta, shared) => {
+          console.log(
+            `[flowneer] step ${meta.index} (${meta.type}):`,
+            JSON.stringify(shared, null, 2)
+          );
+        }
+      },
+      filter
+    );
     return this;
   }
 };
@@ -120,23 +129,26 @@ var withInterrupts = {
 
 // plugins/resilience/withFallback.ts
 var withFallback = {
-  withFallback(fn) {
-    this._setHooks({
-      wrapStep: async (meta, next, shared, params) => {
-        try {
-          await next();
-        } catch (e) {
-          if (e instanceof InterruptError) throw e;
-          shared.__fallbackError = {
-            stepIndex: meta.index,
-            stepType: meta.type,
-            message: e instanceof Error ? e.message : String(e),
-            stack: e instanceof Error ? e.stack : void 0
-          };
-          await fn(shared, params);
+  withFallback(fn, filter) {
+    this._setHooks(
+      {
+        wrapStep: async (meta, next, shared, params) => {
+          try {
+            await next();
+          } catch (e) {
+            if (e instanceof InterruptError) throw e;
+            shared.__fallbackError = {
+              stepIndex: meta.index,
+              stepType: meta.type,
+              message: e instanceof Error ? e.message : String(e),
+              stack: e instanceof Error ? e.stack : void 0
+            };
+            await fn(shared, params);
+          }
         }
-      }
-    });
+      },
+      filter
+    );
     return this;
   }
 };
@@ -176,23 +188,26 @@ var withCircuitBreaker = {
 
 // plugins/resilience/withTimeout.ts
 var withTimeout = {
-  withTimeout(ms) {
-    this._setHooks({
-      wrapStep: (meta, next) => {
-        let handle;
-        return Promise.race([
-          next().finally(() => clearTimeout(handle)),
-          new Promise(
-            (_, reject) => handle = setTimeout(
-              () => reject(
-                new Error(`step ${meta.index} timed out after ${ms}ms`)
-              ),
-              ms
+  withTimeout(ms, filter) {
+    this._setHooks(
+      {
+        wrapStep: (meta, next) => {
+          let handle;
+          return Promise.race([
+            next().finally(() => clearTimeout(handle)),
+            new Promise(
+              (_, reject) => handle = setTimeout(
+                () => reject(
+                  new Error(`step ${meta.index} timed out after ${ms}ms`)
+                ),
+                ms
+              )
             )
-          )
-        ]);
-      }
-    });
+          ]);
+        }
+      },
+      filter
+    );
     return this;
   }
 };
@@ -240,39 +255,45 @@ var withCycles = {
 
 // plugins/persistence/withCheckpoint.ts
 var withCheckpoint = {
-  withCheckpoint(store) {
-    this._setHooks({
-      afterStep: async (meta, shared) => {
-        await store.save(meta.index, shared);
-      }
-    });
+  withCheckpoint(store, filter) {
+    this._setHooks(
+      {
+        afterStep: async (meta, shared) => {
+          await store.save(meta.index, shared);
+        }
+      },
+      filter
+    );
     return this;
   }
 };
 
 // plugins/persistence/withAuditLog.ts
 var withAuditLog = {
-  withAuditLog(store) {
+  withAuditLog(store, filter) {
     const clone = (v) => JSON.parse(JSON.stringify(v));
-    this._setHooks({
-      afterStep: async (meta, shared) => {
-        await store.append({
-          stepIndex: meta.index,
-          type: meta.type,
-          timestamp: Date.now(),
-          shared: clone(shared)
-        });
+    this._setHooks(
+      {
+        afterStep: async (meta, shared) => {
+          await store.append({
+            stepIndex: meta.index,
+            type: meta.type,
+            timestamp: Date.now(),
+            shared: clone(shared)
+          });
+        },
+        onError: (meta, err2, shared) => {
+          store.append({
+            stepIndex: meta.index,
+            type: meta.type,
+            timestamp: Date.now(),
+            shared: clone(shared),
+            error: err2 instanceof Error ? err2.message : String(err2)
+          });
+        }
       },
-      onError: (meta, err2, shared) => {
-        store.append({
-          stepIndex: meta.index,
-          type: meta.type,
-          timestamp: Date.now(),
-          shared: clone(shared),
-          error: err2 instanceof Error ? err2.message : String(err2)
-        });
-      }
-    });
+      filter
+    );
     return this;
   }
 };
@@ -297,31 +318,34 @@ function diffObjects(prev, curr) {
 }
 var versionCounter = 0;
 var withVersionedCheckpoint = {
-  withVersionedCheckpoint(store) {
+  withVersionedCheckpoint(store, filter) {
     let prevSnapshot = {};
     let lastVersion = null;
-    this._setHooks({
-      beforeFlow: (shared) => {
-        prevSnapshot = JSON.parse(JSON.stringify(shared));
-        lastVersion = null;
+    this._setHooks(
+      {
+        beforeFlow: (shared) => {
+          prevSnapshot = JSON.parse(JSON.stringify(shared));
+          lastVersion = null;
+        },
+        afterStep: async (meta, shared) => {
+          const curr = JSON.parse(JSON.stringify(shared));
+          const diff = diffObjects(prevSnapshot, curr);
+          if (Object.keys(diff).length === 0) return;
+          const version = `v${++versionCounter}`;
+          const entry = {
+            version,
+            stepIndex: meta.index,
+            diff,
+            parentVersion: lastVersion,
+            timestamp: Date.now()
+          };
+          await store.save(entry);
+          lastVersion = version;
+          prevSnapshot = curr;
+        }
       },
-      afterStep: async (meta, shared) => {
-        const curr = JSON.parse(JSON.stringify(shared));
-        const diff = diffObjects(prevSnapshot, curr);
-        if (Object.keys(diff).length === 0) return;
-        const version = `v${++versionCounter}`;
-        const entry = {
-          version,
-          stepIndex: meta.index,
-          diff,
-          parentVersion: lastVersion,
-          timestamp: Date.now()
-        };
-        await store.save(entry);
-        lastVersion = version;
-        prevSnapshot = curr;
-      }
-    });
+      filter
+    );
     return this;
   },
   resumeFrom(version, store) {
@@ -344,29 +368,35 @@ var withVersionedCheckpoint = {
 
 // plugins/llm/withTokenBudget.ts
 var withTokenBudget = {
-  withTokenBudget(limit) {
-    this._setHooks({
-      beforeStep: (_meta, shared) => {
-        const used = shared.tokensUsed ?? 0;
-        if (used >= limit) {
-          throw new Error(`token budget exceeded: ${used} >= ${limit}`);
+  withTokenBudget(limit, filter) {
+    this._setHooks(
+      {
+        beforeStep: (_meta, shared) => {
+          const used = shared.tokensUsed ?? 0;
+          if (used >= limit) {
+            throw new Error(`token budget exceeded: ${used} >= ${limit}`);
+          }
         }
-      }
-    });
+      },
+      filter
+    );
     return this;
   }
 };
 
 // plugins/llm/withCostTracker.ts
 var withCostTracker = {
-  withCostTracker() {
-    this._setHooks({
-      afterStep: (_meta, shared) => {
-        const stepCost = shared.__stepCost ?? 0;
-        shared.__cost = (shared.__cost ?? 0) + stepCost;
-        delete shared.__stepCost;
-      }
-    });
+  withCostTracker(filter) {
+    this._setHooks(
+      {
+        afterStep: (_meta, shared) => {
+          const stepCost = shared.__stepCost ?? 0;
+          shared.__cost = (shared.__cost ?? 0) + stepCost;
+          delete shared.__stepCost;
+        }
+      },
+      filter
+    );
     return this;
   }
 };

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin, S as StepFilter, V as Validator } from '../../FlowBuilder-B_BIRk3f.js';
+import { S as StepFilter, a as FlowneerPlugin, V as Validator } from '../../FlowBuilder-CqWK42bA.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
@@ -6,7 +6,7 @@ declare module "../../Flowneer" {
          * Aborts the flow before any step if `shared.tokensUsed >= limit`.
          * Steps are responsible for incrementing `shared.tokensUsed`.
          */
-        withTokenBudget(limit: number): this;
+        withTokenBudget(limit: number, filter?: StepFilter): this;
     }
 }
 declare const withTokenBudget: FlowneerPlugin;
@@ -17,7 +17,7 @@ declare module "../../Flowneer" {
          * Accumulates `shared.__stepCost` (set by each step) into `shared.__cost`.
          * Clears `__stepCost` after each step so it is never double-counted.
          */
-        withCostTracker(): this;
+        withCostTracker(filter?: StepFilter): this;
     }
 }
 declare const withCostTracker: FlowneerPlugin;
@@ -102,7 +102,7 @@ declare module "../../Flowneer" {
          *   .startWith(async (s) => { s.__llmOutput = await callLlm("..."); })
          *   .then((s) => { console.log(s.__structuredOutput); });
          */
-        withStructuredOutput<T = unknown>(validator: Validator<T>, options?: StructuredOutputOptions): this;
+        withStructuredOutput<T = unknown>(validator: Validator<T>, options?: StructuredOutputOptions, filter?: StepFilter): this;
     }
 }
 declare const withStructuredOutput: FlowneerPlugin;