flowneer 0.9.4 → 0.9.6

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

@@ -86,6 +86,11 @@ interface StepMeta {
  *   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.
+ * - **Negation** — prefix an entry with `!` to exclude matching steps.
+ *   Negation veto always wins over a positive match in the same array.
+ *   A negation-only array matches all labelled steps that are not excluded.
+ *   e.g. `["!human:*"]` fires on every step _except_ `human:*` steps.
+ *   e.g. `["!human:*", "llm:*"]` fires on `llm:*` steps only, never `human:*`.
  * - **Predicate** — full control; return `true` to match.
  *
  * Unmatched `wrapStep`/`wrapParallelFn` hooks still call `next()` automatically
@@ -98,6 +103,12 @@ interface StepMeta {
  * // Wildcard — any step whose label starts with "llm:"
  * flow.withRateLimit({ intervalMs: 1000 }, ["llm:*"]);
  *
+ * // Negation-only — apply everywhere except human-in-loop steps
+ * flow.withRateLimit({ intervalMs: 1000 }, ["!human:*"]);
+ *
+ * // Mixed — apply to llm steps, but never human steps
+ * flow.withRateLimit({ intervalMs: 1000 }, ["!human:*", "llm:*"]);
+ *
  * // Custom predicate
  * flow.addHooks({ beforeStep: log }, (meta) => meta.type === "fn");
  */
@@ -106,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.
@@ -113,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.
@@ -132,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.
@@ -143,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"]>[];
@@ -291,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.
@@ -421,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-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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-8kwREeyD.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

@@ -115,15 +115,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -250,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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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-8kwREeyD.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';
 
 /**
@@ -290,6 +290,172 @@ declare function selfConsistency<S = any, P extends Record<string, unknown> = Re
  */
 declare function critiqueAndRevise<S = any, P extends Record<string, unknown> = Record<string, unknown>>(generate: NodeFn<S, P>, critique: NodeFn<S, P>, revise: NodeFn<S, P>, rounds?: number): FlowBuilder<S, P>;
 
+/**
+ * A single message in the swarm conversation history.
+ * Agents write to `shared.messages` using this shape.
+ */
+interface SwarmMessage {
+    role: "user" | "assistant";
+    content: string;
+    /** Name of the agent that produced this message */
+    agent?: string;
+}
+/**
+ * Fields that `swarm()` reads and writes on shared state.
+ * Extend this with your own application fields via intersection:
+ *
+ * ```typescript
+ * type MyState = SwarmState & { topic: string; result?: string };
+ * ```
+ */
+interface SwarmState {
+    /** Name of the agent currently handling the request.
+     *  Defaults to `options.defaultAgent` on the first `.run()` call. */
+    currentAgent?: string;
+    /** Conversation history — manage this inside your agent fns. */
+    messages?: SwarmMessage[];
+    /** Number of handoffs that have occurred in the current `.run()` call. */
+    turnCount?: number;
+    /** @internal — loop exit sentinel; removed after each `.run()` */
+    __swarmDone?: boolean;
+    /** @internal — set by `handoffTo()`; consumed by the handoff checker */
+    __swarmHandoff?: {
+        target: string;
+        reason?: string;
+    };
+}
+/**
+ * A single agent in the swarm.
+ * Each agent is a `NodeFn` paired with a name and description.
+ */
+interface SwarmAgent<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique name used in `handoffTo()` calls and `SwarmState.currentAgent`. */
+    name: string;
+    /** Human-readable description (can be provided to an LLM for routing). */
+    description: string;
+    /** The agent's step function — same signature as any Flowneer `NodeFn`. */
+    fn: NodeFn<S, P>;
+}
+/**
+ * Options for `swarm()`.
+ */
+interface SwarmOptions<S = any> {
+    /**
+     * Name of the agent that handles the first turn.
+     * Must appear in the `agents` array.
+     */
+    defaultAgent: string;
+    /**
+     * Maximum number of handoffs per `.run()` call before the flow stops.
+     * Counts hops (not total agents); the original agent's first run is free.
+     * Defaults to `5`.
+     */
+    maxHandoffs?: number;
+    /**
+     * Called each time a handoff is accepted.
+     * `from` is the agent that handed off, `to` is the new agent.
+     */
+    onHandoff?: (from: string, to: string, reason: string | undefined, shared: S) => void | Promise<void>;
+    /**
+     * Called when `maxHandoffs` is exceeded instead of completing the handoff.
+     * The turn ends after this callback returns.
+     */
+    onMaxHandoffs?: (shared: S) => void | Promise<void>;
+    /**
+     * Optional LLM router that selects the starting agent on each `.run()` call.
+     * Runs once after state initialisation, before the handoff loop begins.
+     */
+    router?: SwarmRouter<S>;
+}
+/**
+ * Context object passed to a {@link SwarmRouter} prompt function.
+ */
+interface RouterContext<S = any> {
+    /** Full conversation history at the time of routing. */
+    messages: SwarmMessage[];
+    /** All agents registered in the swarm. */
+    agents: SwarmAgent<S, any>[];
+    /** Name of the agent that will be used if the router returns an unknown name. */
+    currentAgent: string;
+    /** Live shared state — mutations here are visible to the dispatched agent. */
+    shared: S;
+}
+/**
+ * An optional LLM-based router that selects the starting agent for each `.run()` call.
+ *
+ * @example
+ * const flow = swarm(agents, {
+ *   defaultAgent: "triage",
+ *   router: {
+ *     call: (prompt) => openai.chat.completions.create({ ... }).then(r => r.choices[0].message.content!),
+ *   },
+ * });
+ */
+interface SwarmRouter<S = any> {
+    /**
+     * Calls the LLM with the resolved prompt and returns the agent name to start with.
+     * The response is trimmed and matched case-insensitively against the agents array.
+     * An unrecognised response is silently ignored and `currentAgent` remains unchanged.
+     */
+    call: (prompt: string) => Promise<string>;
+    /**
+     * Static prompt string or async function that returns the prompt.
+     * When omitted, a default prompt listing all agents and the latest user message is used.
+     */
+    prompt?: string | ((context: RouterContext<S>) => string | Promise<string>);
+}
+/**
+ * Formats a `SwarmMessage[]` into a plain-text string suitable for use in LLM
+ * prompts. Each line is `[agentName] role: content`; the `[agentName]` prefix
+ * is omitted when `message.agent` is undefined.
+ *
+ * @example
+ * const prompt = `Conversation so far:\n${historyText(shared.messages ?? [])}`;
+ */
+declare function historyText(messages: SwarmMessage[]): string;
+/**
+ * Signal that control should pass to another agent in the swarm.
+ *
+ * Call this inside an agent's `fn` to hand off to `agentName`.
+ * If the target name is not found in the swarm the handoff is silently dropped
+ * and the current turn ends.
+ *
+ * @example
+ * const billingAgent: SwarmAgent<MyState> = {
+ *   name: "billing",
+ *   description: "Handles billing and payment queries",
+ *   fn: async (shared) => {
+ *     if (!isBillingQuery(shared.messages)) {
+ *       handoffTo(shared, "support", "not a billing question");
+ *       return;
+ *     }
+ *     shared.messages!.push({ role: "assistant", content: await billingLlm(shared) });
+ *   },
+ * };
+ */
+declare function handoffTo(shared: SwarmState, agentName: string, reason?: string): void;
+/**
+ * Creates a decentralized swarm of agents that hand off to each other
+ * dynamically at runtime.
+ *
+ * Each agent can call `handoffTo(shared, targetName, reason?)` inside its `fn`
+ * to yield control to another agent. The flow loops until either:
+ *  - An agent finishes without calling `handoffTo`, or
+ *  - `options.maxHandoffs` is exceeded (default 5) — `onMaxHandoffs` is called.
+ *
+ * `currentAgent` persists between `.run()` calls so the swarm remembers which
+ * agent was active. It is set to `defaultAgent` only on the first call.
+ *
+ * @example
+ * const flow = swarm(
+ *   [triageAgent, billingAgent, supportAgent],
+ *   { defaultAgent: "triage" },
+ * );
+ *
+ * await flow.run({ messages: [{ role: "user", content: "I need a refund" }] });
+ */
+declare function swarm<S extends SwarmState = SwarmState, P extends Record<string, unknown> = Record<string, unknown>>(agents: SwarmAgent<S, P>[], options: SwarmOptions<S>, FlowClass?: new () => FlowBuilder<S, P>): FlowBuilder<S, P>;
+
 /**
  * Minimal structural interface that matches a Zod ZodObject.
  * We duck-type against `.shape` so this plugin has zero Zod dependency —
@@ -438,4 +604,4 @@ interface CreateAgentOptions {
  */
 declare function createAgent(options: CreateAgentOptions): FlowBuilder<AgentState>;
 
-export { type AgentState, type ChatMessage, type CreateAgentOptions, type EvaluatorOptimizerOptions, type EvaluatorOptimizerResult, type LlmAdapter, type LlmResponse, type LlmToolDef, type PlanAndExecuteOptions, type ReActLoopOptions, type ReflexionOptions, type ThinkResult, type ToolConfig, type ToolConfigParams, type ToolConfigSchema, type ZodLikeObject, createAgent, critiqueAndRevise, evaluatorOptimizer, hierarchicalCrew, planAndExecute, reflexionAgent, roundRobinDebate, selfConsistency, sequentialCrew, supervisorCrew, tool, withReActLoop };
+export { type AgentState, type ChatMessage, type CreateAgentOptions, type EvaluatorOptimizerOptions, type EvaluatorOptimizerResult, type LlmAdapter, type LlmResponse, type LlmToolDef, type PlanAndExecuteOptions, type ReActLoopOptions, type ReflexionOptions, type RouterContext, type SwarmAgent, type SwarmMessage, type SwarmOptions, type SwarmRouter, type SwarmState, type ThinkResult, type ToolConfig, type ToolConfigParams, type ToolConfigSchema, type ZodLikeObject, createAgent, critiqueAndRevise, evaluatorOptimizer, handoffTo, hierarchicalCrew, historyText, planAndExecute, reflexionAgent, roundRobinDebate, selfConsistency, sequentialCrew, supervisorCrew, swarm, tool, withReActLoop };

package/dist/presets/agent/index.js

@@ -71,15 +71,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -206,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.
@@ -816,6 +843,120 @@ function critiqueAndRevise(generate, critique, revise, rounds = 1) {
   });
 }
 
+// presets/agent/swarm.ts
+function historyText(messages) {
+  return messages.map((m) => `${m.agent ? `[${m.agent}] ` : ""}${m.role}: ${m.content}`).join("\n");
+}
+function buildDefaultRouterPrompt(ctx) {
+  const agentList = ctx.agents.map((a) => `- ${a.name}: ${a.description}`).join("\n");
+  const history = historyText(ctx.messages);
+  const latest = [...ctx.messages].reverse().find((m) => m.role === "user");
+  return [
+    "You are a routing assistant. Choose the best agent to handle the user's request.",
+    "",
+    "Available agents:",
+    agentList,
+    "",
+    ...history ? ["Conversation history:", history, ""] : [],
+    ...latest ? [`Latest user message: ${latest.content}`, ""] : [],
+    "Respond with only the exact agent name, nothing else."
+  ].join("\n");
+}
+function handoffTo(shared, agentName, reason) {
+  shared.__swarmHandoff = { target: agentName, reason };
+}
+function swarm(agents, options, FlowClass = FlowBuilder) {
+  const agentMap = new Map(
+    agents.map((a) => [a.name, a])
+  );
+  if (!agentMap.has(options.defaultAgent)) {
+    throw new Error(
+      `swarm: defaultAgent "${options.defaultAgent}" not found in agents list. Available agents: ${agents.map((a) => a.name).join(", ")}`
+    );
+  }
+  const maxHandoffs = options.maxHandoffs ?? 5;
+  return new FlowClass().startWith(
+    (shared) => {
+      if (shared.currentAgent === void 0) {
+        shared.currentAgent = options.defaultAgent;
+      }
+      shared.turnCount = 0;
+      shared.__swarmDone = false;
+      delete shared.__swarmHandoff;
+    },
+    { label: "swarm:init" }
+  ).then(
+    async (shared) => {
+      if (!options.router) return;
+      const ctx = {
+        messages: shared.messages ?? [],
+        agents,
+        currentAgent: shared.currentAgent,
+        shared
+      };
+      const rawPrompt = typeof options.router.prompt === "function" ? await options.router.prompt(ctx) : options.router.prompt ?? buildDefaultRouterPrompt(ctx);
+      const response = await options.router.call(rawPrompt);
+      const raw = response.trim();
+      const match = agents.find(
+        (a) => a.name.toLowerCase() === raw.toLowerCase()
+      );
+      if (match) {
+        shared.currentAgent = match.name;
+      }
+    },
+    { label: "swarm:router" }
+  ).loop(
+    (shared) => !shared.__swarmDone,
+    (b) => {
+      b.startWith(
+        async (shared, params) => {
+          const agent = agentMap.get(shared.currentAgent);
+          if (!agent) {
+            shared.currentAgent = options.defaultAgent;
+            shared.__swarmDone = true;
+            return;
+          }
+          delete shared.__swarmHandoff;
+          await agent.fn(shared, params);
+        },
+        { label: "swarm:dispatch" }
+      ).then(
+        async (shared) => {
+          const handoff = shared.__swarmHandoff;
+          if (!handoff) {
+            shared.__swarmDone = true;
+            return;
+          }
+          if (!agentMap.has(handoff.target)) {
+            shared.__swarmDone = true;
+            return;
+          }
+          if ((shared.turnCount ?? 0) >= maxHandoffs) {
+            await options.onMaxHandoffs?.(shared);
+            shared.__swarmDone = true;
+            return;
+          }
+          await options.onHandoff?.(
+            shared.currentAgent,
+            handoff.target,
+            handoff.reason,
+            shared
+          );
+          shared.turnCount = (shared.turnCount ?? 0) + 1;
+          shared.currentAgent = handoff.target;
+        },
+        { label: "swarm:handoff" }
+      );
+    },
+    { label: "swarm:loop" }
+  ).then(
+    (shared) => {
+      delete shared.__swarmDone;
+    },
+    { label: "swarm:cleanup" }
+  );
+}
+
 // presets/agent/tool.ts
 function zodTypeToParamType(typeName) {
   switch (typeName) {
@@ -987,13 +1128,16 @@ export {
   createAgent,
   critiqueAndRevise,
   evaluatorOptimizer,
+  handoffTo,
   hierarchicalCrew,
+  historyText,
   planAndExecute,
   reflexionAgent,
   roundRobinDebate,
   selfConsistency,
   sequentialCrew,
   supervisorCrew,
+  swarm,
   tool,
   withReActLoop
 };

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-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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

@@ -1,7 +1,7 @@
-export { AgentState, ChatMessage, CreateAgentOptions, EvaluatorOptimizerOptions, EvaluatorOptimizerResult, LlmAdapter, LlmResponse, LlmToolDef, PlanAndExecuteOptions, ReActLoopOptions, ReflexionOptions, ThinkResult, ToolConfig, ToolConfigParams, ToolConfigSchema, ZodLikeObject, createAgent, critiqueAndRevise, evaluatorOptimizer, hierarchicalCrew, planAndExecute, reflexionAgent, roundRobinDebate, selfConsistency, sequentialCrew, supervisorCrew, tool, withReActLoop } from './agent/index.js';
+export { AgentState, ChatMessage, CreateAgentOptions, EvaluatorOptimizerOptions, EvaluatorOptimizerResult, LlmAdapter, LlmResponse, LlmToolDef, PlanAndExecuteOptions, ReActLoopOptions, ReflexionOptions, RouterContext, SwarmAgent, SwarmMessage, SwarmOptions, SwarmRouter, SwarmState, ThinkResult, ToolConfig, ToolConfigParams, ToolConfigSchema, ZodLikeObject, createAgent, critiqueAndRevise, evaluatorOptimizer, handoffTo, hierarchicalCrew, historyText, planAndExecute, reflexionAgent, roundRobinDebate, selfConsistency, sequentialCrew, supervisorCrew, swarm, tool, withReActLoop } from './agent/index.js';
 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-8kwREeyD.js';
+import '../FlowBuilder-CwBQDOEN.js';
 import '../plugins/tools/index.js';
 import '../schema-CIqQAXqY.js';

package/dist/presets/index.js

@@ -71,15 +71,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -206,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.
@@ -816,6 +843,120 @@ function critiqueAndRevise(generate, critique, revise, rounds = 1) {
   });
 }
 
+// presets/agent/swarm.ts
+function historyText(messages) {
+  return messages.map((m) => `${m.agent ? `[${m.agent}] ` : ""}${m.role}: ${m.content}`).join("\n");
+}
+function buildDefaultRouterPrompt(ctx) {
+  const agentList = ctx.agents.map((a) => `- ${a.name}: ${a.description}`).join("\n");
+  const history = historyText(ctx.messages);
+  const latest = [...ctx.messages].reverse().find((m) => m.role === "user");
+  return [
+    "You are a routing assistant. Choose the best agent to handle the user's request.",
+    "",
+    "Available agents:",
+    agentList,
+    "",
+    ...history ? ["Conversation history:", history, ""] : [],
+    ...latest ? [`Latest user message: ${latest.content}`, ""] : [],
+    "Respond with only the exact agent name, nothing else."
+  ].join("\n");
+}
+function handoffTo(shared, agentName, reason) {
+  shared.__swarmHandoff = { target: agentName, reason };
+}
+function swarm(agents, options, FlowClass = FlowBuilder) {
+  const agentMap = new Map(
+    agents.map((a) => [a.name, a])
+  );
+  if (!agentMap.has(options.defaultAgent)) {
+    throw new Error(
+      `swarm: defaultAgent "${options.defaultAgent}" not found in agents list. Available agents: ${agents.map((a) => a.name).join(", ")}`
+    );
+  }
+  const maxHandoffs = options.maxHandoffs ?? 5;
+  return new FlowClass().startWith(
+    (shared) => {
+      if (shared.currentAgent === void 0) {
+        shared.currentAgent = options.defaultAgent;
+      }
+      shared.turnCount = 0;
+      shared.__swarmDone = false;
+      delete shared.__swarmHandoff;
+    },
+    { label: "swarm:init" }
+  ).then(
+    async (shared) => {
+      if (!options.router) return;
+      const ctx = {
+        messages: shared.messages ?? [],
+        agents,
+        currentAgent: shared.currentAgent,
+        shared
+      };
+      const rawPrompt = typeof options.router.prompt === "function" ? await options.router.prompt(ctx) : options.router.prompt ?? buildDefaultRouterPrompt(ctx);
+      const response = await options.router.call(rawPrompt);
+      const raw = response.trim();
+      const match = agents.find(
+        (a) => a.name.toLowerCase() === raw.toLowerCase()
+      );
+      if (match) {
+        shared.currentAgent = match.name;
+      }
+    },
+    { label: "swarm:router" }
+  ).loop(
+    (shared) => !shared.__swarmDone,
+    (b) => {
+      b.startWith(
+        async (shared, params) => {
+          const agent = agentMap.get(shared.currentAgent);
+          if (!agent) {
+            shared.currentAgent = options.defaultAgent;
+            shared.__swarmDone = true;
+            return;
+          }
+          delete shared.__swarmHandoff;
+          await agent.fn(shared, params);
+        },
+        { label: "swarm:dispatch" }
+      ).then(
+        async (shared) => {
+          const handoff = shared.__swarmHandoff;
+          if (!handoff) {
+            shared.__swarmDone = true;
+            return;
+          }
+          if (!agentMap.has(handoff.target)) {
+            shared.__swarmDone = true;
+            return;
+          }
+          if ((shared.turnCount ?? 0) >= maxHandoffs) {
+            await options.onMaxHandoffs?.(shared);
+            shared.__swarmDone = true;
+            return;
+          }
+          await options.onHandoff?.(
+            shared.currentAgent,
+            handoff.target,
+            handoff.reason,
+            shared
+          );
+          shared.turnCount = (shared.turnCount ?? 0) + 1;
+          shared.currentAgent = handoff.target;
+        },
+        { label: "swarm:handoff" }
+      );
+    },
+    { label: "swarm:loop" }
+  ).then(
+    (shared) => {
+      delete shared.__swarmDone;
+    },
+    { label: "swarm:cleanup" }
+  );
+}
+
 // presets/agent/tool.ts
 function zodTypeToParamType(typeName) {
   switch (typeName) {
@@ -1391,7 +1532,9 @@ export {
   critiqueAndRevise,
   evaluatorOptimizer,
   generateUntilValid,
+  handoffTo,
   hierarchicalCrew,
+  historyText,
   iterativeRag,
   mapReduceLlm,
   planAndExecute,
@@ -1401,6 +1544,7 @@ export {
   selfConsistency,
   sequentialCrew,
   supervisorCrew,
+  swarm,
   tool,
   withReActLoop
 };

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

@@ -1,4 +1,4 @@
-import { N as NodeFn, F as FlowBuilder } from '../../FlowBuilder-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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-8kwREeyD.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-8kwREeyD.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

@@ -21,15 +21,21 @@ var InterruptError = class extends Error {
 };
 
 // src/core/utils.ts
+function matchesPattern(pattern, label) {
+  return pattern.includes("*") ? new RegExp(
+    "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
+  ).test(label) : pattern === label;
+}
 function matchesFilter(filter, meta) {
   if (!Array.isArray(filter)) return filter(meta);
+  const negations = filter.filter((p) => p.startsWith("!"));
+  const positives = filter.filter((p) => !p.startsWith("!"));
   const label = meta.label;
-  if (label === void 0) return false;
-  return filter.some(
-    (p) => p.includes("*") ? new RegExp(
-      "^" + p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$"
-    ).test(label) : p === label
-  );
+  if (label !== void 0 && negations.some((p) => matchesPattern(p.slice(1), label)))
+    return false;
+  if (positives.length > 0)
+    return label !== void 0 && positives.some((p) => matchesPattern(p, label));
+  return true;
 }
 function resolveNumber(val, fallback, shared, params) {
   if (val === void 0) return fallback;
@@ -156,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.4",
+  "version": "0.9.6",
   "description": "Zero-dependency fluent flow builder for AI agents",
   "license": "MIT",
   "type": "module",