flowneer 0.9.5 → 0.9.6

package/dist/{FlowBuilder-Bvf_nDeb.d.ts → FlowBuilder-CwBQDOEN.d.ts}

@@ -117,6 +117,7 @@ type StepFilter = string[] | ((meta: StepMeta) => boolean);
 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>;
+    /** Fires before each step body executes. Respects `StepFilter` when registered via `_setHooks`. */
     beforeStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
     /**
      * Wraps step execution — call `next()` to invoke the step body.
@@ -124,13 +125,21 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
      * Multiple `wrapStep` registrations are composed innermost-first.
      */
     wrapStep?: (meta: StepMeta, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
+    /** Fires after each step body completes successfully. Respects `StepFilter` when registered via `_setHooks`. */
     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>;
+    /**
+     * Fires when a step throws, before the error is re-thrown.
+     * Use for logging or writing error details to `shared` — do not suppress the error here;
+     * use `wrapStep` with a try/catch for recovery instead.
+     * Respects `StepFilter` when registered via `_setHooks`.
+     */
     onError?: (meta: StepMeta, error: unknown, shared: S, params: P) => void | Promise<void>;
+    /** Fires once after the last step completes (or after a flow error). Not affected by `StepFilter`. */
     afterFlow?: (shared: S, params: P) => void | Promise<void>;
     /**
      * Fires after each loop iteration completes. `iteration` is zero-based.
@@ -143,6 +152,14 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
      */
     onAnchorHit?: (anchorName: string, shared: S, params: P) => void | Promise<void>;
 }
+/**
+ * The `this` type inside every plugin method. Extends the public `FlowBuilder`
+ * with `_setHooks` so plugins can register lifecycle hooks without casting to
+ * `any`.
+ */
+type PluginContext = FlowBuilder<any, any> & {
+    _setHooks(hooks: Partial<FlowHooks<any, any>>, filter?: StepFilter): () => void;
+};
 /**
  * A plugin is an object whose keys become methods on a `FlowBuilder.extend()` subclass prototype.
  * Each method receives the builder as `this` and should return `this` for chaining.
@@ -154,7 +171,7 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
  * }
  * ```
  */
-type FlowneerPlugin = Record<string, (this: FlowBuilder<any, any>, ...args: any[]) => any>;
+type FlowneerPlugin = Record<string, (this: PluginContext, ...args: any[]) => any>;
 type ResolvedHooks<S, P extends Record<string, unknown>> = {
     beforeFlow: NonNullable<FlowHooks<S, P>["beforeFlow"]>[];
     beforeStep: NonNullable<FlowHooks<S, P>["beforeStep"]>[];
@@ -302,6 +319,25 @@ declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Recor
         transparent?: boolean;
     }): void;
     private _hooks;
+    /**
+     * Register lifecycle hooks on this flow instance at runtime.
+     *
+     * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+     * intended for consumers — app code, tests, or request-scoped instrumentation
+     * that needs to observe or modify a specific flow instance without defining a
+     * plugin.
+     *
+     * Returns a `dispose` function that removes the registered hooks when called.
+     *
+     * @example
+     * const dispose = flow.addHooks(
+     *   { beforeStep: (meta) => console.log("->", meta.label) },
+     *   ["llm:*"],
+     * );
+     * await flow.run(shared);
+     * dispose(); // removes the hooks
+     */
+    addHooks(hooks: Partial<FlowHooks<S, P>>, filter?: StepFilter): () => void;
     /**
      * Register lifecycle hooks (called by plugin methods, not by consumers).
      * Returns a dispose function that removes these hooks when called.
@@ -432,4 +468,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, 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 };
+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 PluginContext as i, type RunOptions as j, type Step as k, type StepContext as l, type StepHandler as m, type StreamEvent as n };

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, h as NumberOrFn, i as RunOptions, d as StepMeta, m as StreamEvent, V as Validator } from './FlowBuilder-Bvf_nDeb.js';
+export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, h as NumberOrFn, j as RunOptions, d as StepMeta, n as StreamEvent, V as Validator } from './FlowBuilder-CwBQDOEN.js';
 export { Fragment, fragment } from './src/index.js';
 export { F as FlowError, I as InterruptError } from './errors-u-hq7p5N.js';

package/dist/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

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

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

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-Bvf_nDeb.js';
+import { a as FlowneerPlugin, N as NodeFn, b as NodeOptions, S as StepFilter } from '../../FlowBuilder-CwBQDOEN.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

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

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

package/dist/plugins/graph/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/dist/plugins/index.d.ts

@@ -11,7 +11,7 @@ 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-Bvf_nDeb.js';
+import { S as StepFilter, a as FlowneerPlugin, d as StepMeta, F as FlowBuilder } from '../FlowBuilder-CwBQDOEN.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-CIqQAXqY.js';

package/dist/plugins/index.js

@@ -256,6 +256,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

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

@@ -1,4 +1,4 @@
-import { S as StepFilter, a as FlowneerPlugin, V as Validator } from '../../FlowBuilder-Bvf_nDeb.js';
+import { S as StepFilter, a as FlowneerPlugin, V as Validator } from '../../FlowBuilder-CwBQDOEN.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 /** A single message in conversational memory. */
 interface MemoryMessage {

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 /** Send a message to a named channel on `shared.__channels`. */
 declare function sendTo<S extends Record<string, any>>(shared: S, channel: string, message: unknown): void;

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

@@ -1,4 +1,4 @@
-import { S as StepFilter, a as FlowneerPlugin, d as StepMeta } from '../../FlowBuilder-Bvf_nDeb.js';
+import { S as StepFilter, a as FlowneerPlugin, d as StepMeta } from '../../FlowBuilder-CwBQDOEN.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

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

@@ -1,4 +1,4 @@
-import { V as Validator } from '../../FlowBuilder-Bvf_nDeb.js';
+import { V as Validator } from '../../FlowBuilder-CwBQDOEN.js';
 
 /**
  * Extract and parse JSON from a (possibly noisy) LLM response.

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

@@ -1,4 +1,4 @@
-import { d as StepMeta, S as StepFilter, a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { d as StepMeta, S as StepFilter, a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 /**
  * Events that can trigger a checkpoint save.

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

@@ -1,4 +1,4 @@
-import { N as NodeFn, S as StepFilter, a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { N as NodeFn, S as StepFilter, a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 declare module "../../Flowneer" {
     interface FlowBuilder<S, P> {

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

@@ -1,4 +1,4 @@
-import { c as FlowHooks, a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { c as FlowHooks, a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 interface Span {
     traceId: string;

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

@@ -1,4 +1,4 @@
-import { a as FlowneerPlugin } from '../../FlowBuilder-Bvf_nDeb.js';
+import { a as FlowneerPlugin } from '../../FlowBuilder-CwBQDOEN.js';
 
 /** Describes a single parameter for a tool. */
 interface ToolParam {

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

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

package/dist/presets/agent/index.js

@@ -212,6 +212,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

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

@@ -1,5 +1,5 @@
 import { S as StepConfig, a as FnRegistry, b as ValidationResult, F as FlowConfig } from '../../schema-CIqQAXqY.js';
-import { F as FlowBuilder } from '../../FlowBuilder-Bvf_nDeb.js';
+import { F as FlowBuilder } from '../../FlowBuilder-CwBQDOEN.js';
 
 /** Recursive applicator passed to nested step builders (loop body, batch processor). */
 type ApplyFn = (steps: StepConfig[], flow: FlowBuilder<any, any>, registry: FnRegistry) => void;

package/dist/presets/config/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/dist/presets/index.d.ts

@@ -2,6 +2,6 @@ export { AgentState, ChatMessage, CreateAgentOptions, EvaluatorOptimizerOptions,
 export { ApplyFn, ConfigValidationError, CustomStepBuilder, JsonFlowBuilder, StepConfigBuilder } from './config/index.js';
 export { IterativeRagOptions, RagOptions, iterativeRag, ragPipeline } from './rag/index.js';
 export { ApprovalGateOptions, ClarifyLoopOptions, GenerateUntilValidOptions, MapReduceOptions, approvalGate, clarifyLoop, generateUntilValid, mapReduceLlm } from './pipeline/index.js';
-import '../FlowBuilder-Bvf_nDeb.js';
+import '../FlowBuilder-CwBQDOEN.js';
 import '../plugins/tools/index.js';
 import '../schema-CIqQAXqY.js';

package/dist/presets/index.js

@@ -212,6 +212,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/dist/presets/pipeline/index.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeFn, F as FlowBuilder } from '../../FlowBuilder-Bvf_nDeb.js';
+import { N as NodeFn, F as FlowBuilder } from '../../FlowBuilder-CwBQDOEN.js';
 
 interface GenerateUntilValidOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     /**

package/dist/presets/pipeline/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/dist/presets/rag/index.d.ts

@@ -1,4 +1,4 @@
-import { N as NodeFn, F as FlowBuilder } from '../../FlowBuilder-Bvf_nDeb.js';
+import { N as NodeFn, F as FlowBuilder } from '../../FlowBuilder-CwBQDOEN.js';
 
 interface RagOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     /** Retrieves relevant documents/chunks and writes them to shared state. */

package/dist/presets/rag/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FlowBuilder } from '../FlowBuilder-Bvf_nDeb.js';
-export { A as AnchorStep, e as AugmentedState, B as BatchStep, f as BranchStep, C as CoreFlowBuilder, D as DagStep, c as FlowHooks, a as FlowneerPlugin, g as FnStep, L as LoopStep, N as NodeFn, b as NodeOptions, h as NumberOrFn, P as ParallelStep, R as ResolvedHooks, i as RunOptions, j as Step, k as StepContext, S as StepFilter, l as StepHandler, d as StepMeta, m as StreamEvent, V as Validator } from '../FlowBuilder-Bvf_nDeb.js';
+import { F as FlowBuilder } from '../FlowBuilder-CwBQDOEN.js';
+export { A as AnchorStep, e as AugmentedState, B as BatchStep, f as BranchStep, C as CoreFlowBuilder, D as DagStep, c as FlowHooks, a as FlowneerPlugin, g as FnStep, L as LoopStep, N as NodeFn, b as NodeOptions, h as NumberOrFn, P as ParallelStep, i as PluginContext, R as ResolvedHooks, j as RunOptions, k as Step, l as StepContext, S as StepFilter, m as StepHandler, d as StepMeta, n as StreamEvent, V as Validator } from '../FlowBuilder-CwBQDOEN.js';
 export { F as FlowError, I as InterruptError } from '../errors-u-hq7p5N.js';
 
 /**

package/dist/src/index.js

@@ -162,6 +162,27 @@ var CoreFlowBuilder = class _CoreFlowBuilder {
   _hooks() {
     return this._hooksCache ??= buildHookCache(this._hooksList);
   }
+  /**
+   * Register lifecycle hooks on this flow instance at runtime.
+   *
+   * Unlike plugin methods (which use `_setHooks` internally), `addHooks` is
+   * intended for consumers — app code, tests, or request-scoped instrumentation
+   * that needs to observe or modify a specific flow instance without defining a
+   * plugin.
+   *
+   * Returns a `dispose` function that removes the registered hooks when called.
+   *
+   * @example
+   * const dispose = flow.addHooks(
+   *   { beforeStep: (meta) => console.log("->", meta.label) },
+   *   ["llm:*"],
+   * );
+   * await flow.run(shared);
+   * dispose(); // removes the hooks
+   */
+  addHooks(hooks, filter) {
+    return this._setHooks(hooks, filter);
+  }
   /**
    * Register lifecycle hooks (called by plugin methods, not by consumers).
    * Returns a dispose function that removes these hooks when called.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowneer",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Zero-dependency fluent flow builder for AI agents",
   "license": "MIT",
   "type": "module",