flowneer 0.7.1 → 0.8.0

package/dist/{FlowBuilder-DJkzGH5l.d.ts → FlowBuilder-B0SMJ4um.d.ts}

@@ -65,6 +65,29 @@ interface StepMeta {
     type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor";
     label?: string;
 }
+/**
+ * Narrows which steps a hook fires for.
+ *
+ * - **String array** — only steps whose `label` matches are affected.
+ *   Entries are exact matches unless they contain `*`, which acts as a
+ *   wildcard matching any substring (glob-style).
+ *   e.g. `["llm:*"]` matches `"llm:summarise"`, `"llm:embed"`, etc.
+ * - **Predicate** — full control; return `true` to match.
+ *
+ * Unmatched `wrapStep`/`wrapParallelFn` hooks still call `next()` automatically
+ * so the middleware chain is never broken.
+ *
+ * @example
+ * // Exact labels
+ * flow.withRateLimit({ intervalMs: 1000 }, ["callLlm", "callEmbeddings"]);
+ *
+ * // Wildcard — any step whose label starts with "llm:"
+ * flow.withRateLimit({ intervalMs: 1000 }, ["llm:*"]);
+ *
+ * // Custom predicate
+ * flow.addHooks({ beforeStep: log }, (meta) => meta.type === "fn");
+ */
+type StepFilter = string[] | ((meta: StepMeta) => boolean);
 /** 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. */
@@ -230,7 +253,7 @@ declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Recor
      * Register lifecycle hooks (called by plugin methods, not by consumers).
      * Returns a dispose function that removes these hooks when called.
      */
-    protected _setHooks(hooks: Partial<FlowHooks<S, P>>): () => void;
+    protected _setHooks(hooks: Partial<FlowHooks<S, P>>, filter?: StepFilter): () => void;
     /**
      * Register a plugin — copies its methods onto `FlowBuilder.prototype`.
      */
@@ -250,7 +273,7 @@ declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Recor
      * Register lifecycle hooks directly on this instance.
      * Returns a dispose function that removes these hooks when called.
      */
-    addHooks(hooks: Partial<FlowHooks<S, P>>): () => void;
+    addHooks(hooks: Partial<FlowHooks<S, P>>, filter?: StepFilter): () => void;
     /** Execute the flow. */
     run(shared: S, params?: P, options?: RunOptions): Promise<void>;
     /**
@@ -364,4 +387,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 InstancePlugin as I, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type ResolvedHooks 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 RunOptions as g, type Step as h, type StepContext as i, type StepHandler as j, type StreamEvent as k };
+export { type AnchorStep as A, type BatchStep as B, CoreFlowBuilder as C, FlowBuilder as F, type InstancePlugin as I, 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/errors-u-hq7p5N.d.ts

@@ -0,0 +1,16 @@
+/** 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);
+}
+
+export { FlowError as F, InterruptError as I };

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, f as NumberOrFn, g as RunOptions, S as StepMeta, k as StreamEvent, V as Validator } from './FlowBuilder-DJkzGH5l.js';
-export { FlowError, Fragment, InterruptError, fragment } from './src/index.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-B0SMJ4um.js';
+export { Fragment, fragment } from './src/index.js';
+export { F as FlowError, I as InterruptError } from './errors-u-hq7p5N.js';

package/dist/index.js

@@ -74,6 +74,35 @@ function buildAnchorMap(steps) {
 }
 
 // src/core/CoreFlowBuilder.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);
+  });
+}
+function applyStepFilter(hooks, filter) {
+  const match = (meta) => matchesFilter(filter, meta);
+  const wrap = (key, fallback = () => {
+  }) => {
+    const orig = hooks[key];
+    if (!orig) return;
+    hooks[key] = ((...args) => match(args[0]) ? orig(...args) : fallback(
+      ...args
+    ));
+  };
+  wrap("beforeStep");
+  wrap("afterStep");
+  wrap("onError");
+  wrap("wrapStep", (_m, next) => next());
+  wrap("wrapParallelFn", (_m, _fi, next) => next());
+  return hooks;
+}
 function buildHookCache(list) {
   const pick = (key) => list.map((h) => h[key]).filter(Boolean);
   return {
@@ -120,11 +149,12 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.
    */
-  _setHooks(hooks) {
-    this._hooksList.push(hooks);
+  _setHooks(hooks, filter) {
+    const resolved = filter ? applyStepFilter(hooks, filter) : hooks;
+    this._hooksList.push(resolved);
     this._hooksCache = null;
     return () => {
-      const idx = this._hooksList.indexOf(hooks);
+      const idx = this._hooksList.indexOf(resolved);
       if (idx !== -1) this._hooksList.splice(idx, 1);
       this._hooksCache = null;
     };
@@ -156,8 +186,8 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
    * Register lifecycle hooks directly on this instance.
    * Returns a dispose function that removes these hooks when called.
    */
-  addHooks(hooks) {
-    return this._setHooks(hooks);
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
   }
   // -------------------------------------------------------------------------
   // Execution API

package/dist/{patterns-CCtG27Gv.d.ts → patterns-1gFxWo6a.d.ts}

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

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

@@ -1,5 +1,5 @@
-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-CCtG27Gv.js';
-import { F as FlowBuilder } from '../../FlowBuilder-DJkzGH5l.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-1gFxWo6a.js';
+import { F as FlowBuilder } from '../../FlowBuilder-B0SMJ4um.js';
 import { ToolRegistry, ToolResult, Tool, ToolCall, ToolParam } from '../tools/index.js';
 
 /**

package/dist/plugins/agent/index.js

@@ -157,6 +157,35 @@ function buildAnchorMap(steps) {
 }
 
 // src/core/CoreFlowBuilder.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);
+  });
+}
+function applyStepFilter(hooks, filter) {
+  const match = (meta) => matchesFilter(filter, meta);
+  const wrap = (key, fallback = () => {
+  }) => {
+    const orig = hooks[key];
+    if (!orig) return;
+    hooks[key] = ((...args) => match(args[0]) ? orig(...args) : fallback(
+      ...args
+    ));
+  };
+  wrap("beforeStep");
+  wrap("afterStep");
+  wrap("onError");
+  wrap("wrapStep", (_m, next) => next());
+  wrap("wrapParallelFn", (_m, _fi, next) => next());
+  return hooks;
+}
 function buildHookCache(list) {
   const pick = (key) => list.map((h) => h[key]).filter(Boolean);
   return {
@@ -203,11 +232,12 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.
    */
-  _setHooks(hooks) {
-    this._hooksList.push(hooks);
+  _setHooks(hooks, filter) {
+    const resolved = filter ? applyStepFilter(hooks, filter) : hooks;
+    this._hooksList.push(resolved);
     this._hooksCache = null;
     return () => {
-      const idx = this._hooksList.indexOf(hooks);
+      const idx = this._hooksList.indexOf(resolved);
       if (idx !== -1) this._hooksList.splice(idx, 1);
       this._hooksCache = null;
     };
@@ -239,8 +269,8 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
    * Register lifecycle hooks directly on this instance.
    * Returns a dispose function that removes these hooks when called.
    */
-  addHooks(hooks) {
-    return this._setHooks(hooks);
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
   }
   // -------------------------------------------------------------------------
   // Execution API

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-DJkzGH5l.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions } from '../../FlowBuilder-B0SMJ4um.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {
@@ -45,4 +45,89 @@ declare module "../../Flowneer" {
  */
 declare const withAtomicUpdates: FlowneerPlugin;
 
-export { withAtomicUpdates, withDryRun, withMocks, withStepLimit };
+/**
+ * A single node in the static path tree.
+ */
+interface PathNode {
+    /** Stable id: `"fn_0"`, `"branch_2"`, `"anchor:refine"`, etc. */
+    id: string;
+    type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor";
+    label?: string;
+    /** Branch arms — keys are the branch names, values are the arm subtrees. */
+    branches?: Record<string, PathNode[]>;
+    /** Inline body steps (loop / batch). */
+    body?: PathNode[];
+    /** One lane per parallel fn. */
+    parallel?: PathNode[][];
+}
+/**
+ * The result of `.analyzeFlow()`.
+ */
+interface PathMap {
+    nodes: PathNode[];
+    /** All anchor names declared in this flow (and nested sub-flows). */
+    anchors: string[];
+    /**
+     * True if any `fn` step exists — those can dynamically return goto targets
+     * (`"#anchorName"`) that cannot be resolved without running the flow.
+     * Static analysis is therefore necessarily conservative for those edges.
+     */
+    hasDynamicGotos: boolean;
+}
+interface TraceEvent {
+    stepIndex: number;
+    type: string;
+    label?: string;
+    durationMs: number;
+}
+interface TraceReport {
+    events: TraceEvent[];
+    totalDurationMs: number;
+    /** Human-readable ordered list of visited step labels (unlabelled steps are skipped). */
+    pathSummary: string[];
+}
+interface TraceHandle {
+    /** Returns the trace collected so far. Safe to call mid-run. */
+    getTrace(): TraceReport;
+    /** Removes the installed hooks. */
+    dispose(): void;
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Statically analyze this flow and return a `PathMap` describing all
+         * possible nodes and anchors without executing anything.
+         *
+         * `hasDynamicGotos` is true whenever `fn` steps are present — those may
+         * return goto targets at runtime that cannot be resolved statically.
+         *
+         * @example
+         * const map = flow.analyzeFlow();
+         * console.log("anchors:", map.anchors);
+         * console.log("has dynamic gotos:", map.hasDynamicGotos);
+         */
+        analyzeFlow(): PathMap;
+        /**
+         * Install execution-trace hooks on this flow.
+         *
+         * Records every step's index, type, label, and wall-clock duration.
+         * Call `getTrace()` after (or during) the run to inspect results.
+         * Call `dispose()` to remove the hooks when no longer needed.
+         *
+         * Composable with `withDryRun` — trace structure without side effects:
+         * ```ts
+         * flow.withDryRun().withTrace()
+         * ```
+         *
+         * @example
+         * const trace = flow.withTrace();
+         * await flow.run(shared);
+         * console.log(trace.getTrace().pathSummary);
+         * trace.dispose();
+         */
+        withTrace(): TraceHandle;
+    }
+}
+declare const withFlowAnalyzer: FlowneerPlugin;
+
+export { type PathMap, type PathNode, type TraceEvent, type TraceHandle, type TraceReport, withAtomicUpdates, withDryRun, withFlowAnalyzer, withMocks, withStepLimit };

package/dist/plugins/dev/index.js

@@ -49,9 +49,140 @@ var withAtomicUpdates = {
     return this.parallel(fns, options, reducer);
   }
 };
+
+// plugins/dev/withFlowAnalyzer.ts
+function walkSteps(steps, prefix = "") {
+  const nodes = [];
+  const anchors = [];
+  let hasDynamicGotos = false;
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const rawId = step.type === "anchor" ? `anchor:${step.name}` : `${step.type}_${i}`;
+    const id = prefix ? `${prefix}:${rawId}` : rawId;
+    switch (step.type) {
+      case "fn": {
+        hasDynamicGotos = true;
+        nodes.push({
+          id,
+          type: "fn",
+          label: step.label ?? step.fn?.name
+        });
+        break;
+      }
+      case "anchor": {
+        anchors.push(step.name);
+        nodes.push({ id, type: "anchor", label: step.name });
+        break;
+      }
+      case "branch": {
+        const branchMap = {};
+        for (const [key, fn] of Object.entries(step.branches ?? {})) {
+          branchMap[key] = [
+            {
+              id: `${id}:arm:${key}`,
+              type: "fn",
+              label: fn?.name ?? key
+            }
+          ];
+          hasDynamicGotos = true;
+        }
+        nodes.push({
+          id,
+          type: "branch",
+          label: step.label ?? step.router?.name,
+          branches: branchMap
+        });
+        break;
+      }
+      case "loop": {
+        const bodySteps = step.body?.steps ?? [];
+        const inner = walkSteps(bodySteps, `${id}:body`);
+        anchors.push(...inner.anchors);
+        hasDynamicGotos = hasDynamicGotos || inner.hasDynamicGotos;
+        nodes.push({
+          id,
+          type: "loop",
+          label: step.label,
+          body: inner.nodes
+        });
+        break;
+      }
+      case "batch": {
+        const procSteps = step.processor?.steps ?? [];
+        const inner = walkSteps(procSteps, `${id}:each`);
+        anchors.push(...inner.anchors);
+        hasDynamicGotos = hasDynamicGotos || inner.hasDynamicGotos;
+        nodes.push({
+          id,
+          type: "batch",
+          label: step.label,
+          body: inner.nodes
+        });
+        break;
+      }
+      case "parallel": {
+        const fns = step.fns ?? [];
+        const lanes = fns.map((fn, fi) => [
+          {
+            id: `${id}:fn_${fi}`,
+            type: "fn",
+            label: fn?.name ?? `fn_${fi}`
+          }
+        ]);
+        hasDynamicGotos = hasDynamicGotos || fns.length > 0;
+        nodes.push({
+          id,
+          type: "parallel",
+          label: step.label,
+          parallel: lanes
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return { nodes, anchors, hasDynamicGotos };
+}
+var withFlowAnalyzer = {
+  analyzeFlow() {
+    const steps = this.steps ?? [];
+    const { nodes, anchors, hasDynamicGotos } = walkSteps(steps);
+    return { nodes, anchors, hasDynamicGotos };
+  },
+  withTrace() {
+    const events = [];
+    const starts = /* @__PURE__ */ new Map();
+    const dispose = this.addHooks({
+      beforeStep: (meta) => {
+        starts.set(meta.index, Date.now());
+      },
+      afterStep: (meta) => {
+        const start = starts.get(meta.index) ?? Date.now();
+        const durationMs = Date.now() - start;
+        starts.delete(meta.index);
+        events.push({
+          stepIndex: meta.index,
+          type: meta.type,
+          label: meta.label,
+          durationMs
+        });
+      }
+    });
+    return {
+      getTrace() {
+        const totalDurationMs = events.reduce((s, e) => s + e.durationMs, 0);
+        const pathSummary = events.filter((e) => e.label !== void 0).map((e) => e.label);
+        return { events: [...events], totalDurationMs, pathSummary };
+      },
+      dispose
+    };
+  }
+};
 export {
   withAtomicUpdates,
   withDryRun,
+  withFlowAnalyzer,
   withMocks,
   withStepLimit
 };

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

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