flowneer 0.9.4 → 0.9.5

package/dist/{FlowBuilder-8kwREeyD.d.ts → FlowBuilder-Bvf_nDeb.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");
  */

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, i as RunOptions, d as StepMeta, m as StreamEvent, V as Validator } from './FlowBuilder-Bvf_nDeb.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;

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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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;

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-Bvf_nDeb.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;

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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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-Bvf_nDeb.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;
@@ -816,6 +822,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 +1107,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-Bvf_nDeb.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;

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-Bvf_nDeb.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;
@@ -816,6 +822,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 +1511,9 @@ export {
   critiqueAndRevise,
   evaluatorOptimizer,
   generateUntilValid,
+  handoffTo,
   hierarchicalCrew,
+  historyText,
   iterativeRag,
   mapReduceLlm,
   planAndExecute,
@@ -1401,6 +1523,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-Bvf_nDeb.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;

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-Bvf_nDeb.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;

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-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';
 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;

package/package.json

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