@strands-agents/sdk 0.6.0 → 1.0.0-rc.0

package/dist/src/multiagent/multiagent.d.ts

@@ -0,0 +1,41 @@
+import type { InvokeArgs } from '../types/agent.js';
+import type { Message, MessageData } from '../types/messages.js';
+import type { HookableEvent } from '../hooks/events.js';
+import type { HookCallback, HookableEventConstructor, HookCleanup } from '../hooks/types.js';
+import type { MultiAgentStreamEvent } from './events.js';
+import type { MultiAgentResult } from './state.js';
+/**
+ * Input type for multi-agent orchestrators. Excludes `Message[]` and `MessageData[]`
+ * from {@link InvokeArgs} since orchestrators route content blocks between nodes.
+ */
+export type MultiAgentInput = Exclude<InvokeArgs, Message[] | MessageData[]>;
+/**
+ * Interface for any multi-agent orchestrator that can stream execution.
+ * Implement this interface to create custom orchestration patterns that can be
+ * composed as nodes within other orchestrators via {@link MultiAgentNode}.
+ */
+export interface MultiAgent {
+    /** Unique identifier for this orchestrator. */
+    readonly id: string;
+    /**
+     * Execute the orchestrator and return the final result.
+     * @param input - Input to pass to the orchestrator
+     * @returns The aggregate result from all executed nodes
+     */
+    invoke(input: MultiAgentInput): Promise<MultiAgentResult>;
+    /**
+     * Execute the orchestrator and stream events as they occur.
+     * @param input - Input to pass to the orchestrator
+     * @returns Async generator yielding events and returning the final result
+     */
+    stream(input: MultiAgentInput): AsyncGenerator<MultiAgentStreamEvent, MultiAgentResult, undefined>;
+    /**
+     * Register a hook callback for a specific orchestrator event type.
+     *
+     * @param eventType - The event class constructor to register the callback for
+     * @param callback - The callback function to invoke when the event occurs
+     * @returns Cleanup function that removes the callback when invoked
+     */
+    addHook<T extends HookableEvent>(eventType: HookableEventConstructor<T>, callback: HookCallback<T>): HookCleanup;
+}
+//# sourceMappingURL=multiagent.d.ts.map

package/dist/src/multiagent/multiagent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiagent.d.ts","sourceRoot":"","sources":["../../../src/multiagent/multiagent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAEzD;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAAC,qBAAqB,EAAE,gBAAgB,EAAE,SAAS,CAAC,CAAA;IAElG;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,SAAS,aAAa,EAAE,SAAS,EAAE,wBAAwB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAA;CACjH"}

package/dist/src/multiagent/multiagent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=multiagent.js.map

package/dist/src/multiagent/multiagent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiagent.js","sourceRoot":"","sources":["../../../src/multiagent/multiagent.ts"],"names":[],"mappings":""}

package/dist/src/multiagent/nodes.d.ts

@@ -1,8 +1,10 @@
-import type { Agent, InvokeArgs } from '../agent/agent.js';
+import type { InvokableAgent } from '../types/agent.js';
+import type { MultiAgentInput } from './multiagent.js';
 import type { MultiAgentStreamEvent } from './events.js';
 import { NodeResult } from './state.js';
 import type { MultiAgentState, NodeResultUpdate } from './state.js';
-import type { MultiAgentBase } from './base.js';
+import type { MultiAgent } from './multiagent.js';
+import type { z } from 'zod';
 /**
  * Known node type identifiers with extensibility for custom nodes.
  */
@@ -16,6 +18,15 @@ export interface NodeConfig {
      */
     description?: string;
 }
+/**
+ * Per-invocation options passed from the orchestrator to a node.
+ */
+export interface NodeInputOptions {
+    /**
+     * Structured output schema for this node invocation.
+     */
+    structuredOutputSchema?: z.ZodSchema;
+}
 /**
  * Abstract base class for all multi-agent orchestration nodes.
  *
@@ -38,54 +49,57 @@ export declare abstract class Node {
      * Execute the node. Handles duration measurement, error capture,
      * and delegates to handle() for node-specific logic.
      *
-     * @param args - Input to pass to the node (string, content blocks, or messages)
+     * @param input - Input to pass to the node (string or content blocks)
      * @param state - The current multi-agent state
+     * @param options - Per-invocation options from the orchestrator
      * @returns Async generator yielding streaming events and returning a NodeResult
      */
-    stream(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResult, undefined>;
+    stream(input: MultiAgentInput, state: MultiAgentState, options?: NodeInputOptions): AsyncGenerator<MultiAgentStreamEvent, NodeResult, undefined>;
     /**
      * Node-specific execution logic implemented by subclasses.
      *
-     * @param args - Input to process (string, content blocks, or messages)
+     * @param input - Input to process (string or content blocks)
      * @param state - The current multi-agent state
+     * @param options - Per-invocation options from the orchestrator
      * @returns Async generator yielding streaming events and returning a partial result
      */
-    abstract handle(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+    abstract handle(input: MultiAgentInput, state: MultiAgentState, options?: NodeInputOptions): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
 }
 /**
  * Options for creating an {@link AgentNode}.
  */
 export interface AgentNodeOptions {
     /** The agent to wrap as a node. */
-    agent: Agent;
+    agent: InvokableAgent;
 }
 /**
- * Node that wraps an Agent instance for multi-agent orchestration.
+ * Node that wraps an {@link InvokableAgent} instance for multi-agent orchestration.
  *
- * Each execution is isolated — the wrapped agent's internal state
- * is unchanged after the node completes.
+ * Each execution is isolated. When the wrapped agent is an {@link Agent} instance,
+ * its internal state is snapshot/restored so it remains unchanged after the node completes.
  */
 export declare class AgentNode extends Node {
     readonly type: "agentNode";
     private readonly _agent;
     constructor(options: AgentNodeOptions);
-    get agent(): Agent;
+    get agent(): InvokableAgent;
     /**
      * Executes the wrapped agent, yielding each agent streaming event
      * wrapped in a {@link NodeStreamUpdateEvent}.
      *
-     * @param args - Input to pass to the agent
+     * @param input - Input to pass to the agent
      * @param state - The current multi-agent state
+     * @param options - Per-invocation options from the orchestrator
      * @returns Async generator yielding streaming events and returning the agent's content blocks
      */
-    handle(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+    handle(input: MultiAgentInput, state: MultiAgentState, options?: NodeInputOptions): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
 }
 /**
  * Options for creating a {@link MultiAgentNode}.
  */
 export interface MultiAgentNodeOptions extends NodeConfig {
     /** The orchestrator to wrap as a node. */
-    orchestrator: MultiAgentBase;
+    orchestrator: MultiAgent;
 }
 /**
  * Node that wraps a multi-agent orchestrator (e.g. Graph) for nested composition.
@@ -98,28 +112,25 @@ export declare class MultiAgentNode extends Node {
     readonly type: "multiAgentNode";
     private readonly _orchestrator;
     constructor(options: MultiAgentNodeOptions);
-    get orchestrator(): MultiAgentBase;
+    get orchestrator(): MultiAgent;
     /**
      * Executes the wrapped orchestrator. Inner {@link NodeStreamUpdateEvent}s
      * pass through as-is; all other events are wrapped in a new
      * {@link NodeStreamUpdateEvent} tagged with this node's identity.
      *
-     * @param args - Input to pass to the orchestrator
-     * @param _state - The current multi-agent state (unused)
+     * @param input - Input to pass to the orchestrator
+     * @param state - The current multi-agent state
+     * @param _options - Per-invocation options (unused by orchestrator nodes)
      * @returns Async generator yielding streaming events and returning the orchestrator's content
      */
-    handle(args: InvokeArgs, _state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+    handle(input: MultiAgentInput, state: MultiAgentState, _options?: NodeInputOptions): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
 }
 /**
  * A node definition accepted by orchestration constructors.
  *
- * Pass an {@link Agent} or {@link MultiAgentBase} directly for the simple case,
+ * Pass an {@link InvokableAgent} or {@link MultiAgent} directly for the simple case,
  * use typed options objects for per-node configuration, or provide pre-built
  * {@link Node} instances for full control.
  */
-export type NodeDefinition = Agent | MultiAgentBase | Node | (AgentNodeOptions & {
-    type: 'agent';
-}) | (MultiAgentNodeOptions & {
-    type: 'multiAgent';
-});
+export type NodeDefinition = InvokableAgent | MultiAgent | Node | AgentNodeOptions | MultiAgentNodeOptions;
 //# sourceMappingURL=nodes.d.ts.map

package/dist/src/multiagent/nodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../../src/multiagent/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAiB,MAAM,mBAAmB,CAAA;AAEzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,EAAE,UAAU,EAAU,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAG/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAErE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,8BAAsB,IAAI;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAS;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAE3B;;;OAGG;gBACS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IAK1C;;;;;;;OAOG;IACI,MAAM,CACX,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,eAAe,GACrB,cAAc,CAAC,qBAAqB,EAAE,UAAU,EAAE,SAAS,CAAC;IAgC/D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CACb,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,eAAe,GACrB,cAAc,CAAC,qBAAqB,EAAE,gBAAgB,EAAE,SAAS,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,KAAK,CAAA;CACb;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,IAAI;IACjC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAO;gBAElB,OAAO,EAAE,gBAAgB;IAWrC,IAAI,KAAK,IAAI,KAAK,CAEjB;IAED;;;;;;;OAOG;IACI,MAAM,CACX,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,eAAe,GACrB,cAAc,CAAC,qBAAqB,EAAE,gBAAgB,EAAE,SAAS,CAAC;CAsBtE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACvD,0CAA0C;IAC1C,YAAY,EAAE,cAAc,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,IAAI;IACtC,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAElC,OAAO,EAAE,qBAAqB;IAM1C,IAAI,YAAY,IAAI,cAAc,CAEjC;IAED;;;;;;;;OAQG;IACI,MAAM,CACX,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,eAAe,GACtB,cAAc,CAAC,qBAAqB,EAAE,gBAAgB,EAAE,SAAS,CAAC;CActE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,cAAc,GACd,IAAI,GACJ,CAAC,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,GACtC,CAAC,qBAAqB,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAA"}
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../../src/multiagent/nodes.ts"],"names":[],"mappings":"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"}

package/dist/src/multiagent/nodes.js

@@ -1,7 +1,9 @@
+import { Agent } from '../agent/agent.js';
 import { takeSnapshot, loadSnapshot } from '../agent/snapshot.js';
 import { NodeStreamUpdateEvent, NodeResultEvent } from './events.js';
 import { NodeResult, Status } from './state.js';
 import { logger } from '../logging/logger.js';
+import { normalizeError } from '../errors.js';
 /**
  * Abstract base class for all multi-agent orchestration nodes.
  *
@@ -27,17 +29,18 @@ export class Node {
      * Execute the node. Handles duration measurement, error capture,
      * and delegates to handle() for node-specific logic.
      *
-     * @param args - Input to pass to the node (string, content blocks, or messages)
+     * @param input - Input to pass to the node (string or content blocks)
      * @param state - The current multi-agent state
+     * @param options - Per-invocation options from the orchestrator
      * @returns Async generator yielding streaming events and returning a NodeResult
      */
-    async *stream(args, state) {
+    async *stream(input, state, options) {
         const nodeState = state.node(this.id);
         nodeState.status = Status.EXECUTING;
         nodeState.startTime = Date.now();
         let result;
         try {
-            const update = yield* this.handle(args, state);
+            const update = yield* this.handle(input, state, options);
             result = new NodeResult({
                 nodeId: this.id,
                 status: Status.COMPLETED,
@@ -51,7 +54,7 @@ export class Node {
                 nodeId: this.id,
                 status: Status.FAILED,
                 duration: Date.now() - nodeState.startTime,
-                error: error instanceof Error ? error : new Error(String(error)),
+                error: normalizeError(error),
             });
             logger.warn(`node_id=<${this.id}>, error=<${result.error?.message}> | node execution failed`);
         }
@@ -59,22 +62,22 @@ export class Node {
             nodeState.status = result.status;
             nodeState.results.push(result);
         }
-        yield new NodeResultEvent({ nodeId: this.id, nodeType: this.type, result });
+        yield new NodeResultEvent({ nodeId: this.id, nodeType: this.type, state, result });
         return result;
     }
 }
 /**
- * Node that wraps an Agent instance for multi-agent orchestration.
+ * Node that wraps an {@link InvokableAgent} instance for multi-agent orchestration.
  *
- * Each execution is isolated — the wrapped agent's internal state
- * is unchanged after the node completes.
+ * Each execution is isolated. When the wrapped agent is an {@link Agent} instance,
+ * its internal state is snapshot/restored so it remains unchanged after the node completes.
  */
 export class AgentNode extends Node {
     type = 'agentNode';
     _agent;
     constructor(options) {
         const { agent, ...config } = options;
-        super(agent.agentId, {
+        super(agent.id, {
             ...config,
             ...(agent.description !== undefined && { description: agent.description }),
         });
@@ -87,29 +90,41 @@ export class AgentNode extends Node {
      * Executes the wrapped agent, yielding each agent streaming event
      * wrapped in a {@link NodeStreamUpdateEvent}.
      *
-     * @param args - Input to pass to the agent
+     * @param input - Input to pass to the agent
      * @param state - The current multi-agent state
+     * @param options - Per-invocation options from the orchestrator
      * @returns Async generator yielding streaming events and returning the agent's content blocks
      */
-    async *handle(args, state) {
-        const snapshot = takeSnapshot(this._agent, { include: ['messages', 'state'] });
+    async *handle(input, state, options) {
+        // Only Agent instances support snapshot/restore for state isolation
+        const snapshot = this._agent instanceof Agent ? takeSnapshot(this._agent, { include: ['messages', 'state'] }) : undefined;
         try {
-            const options = {
-                ...(state.structuredOutputSchema && { structuredOutputSchema: state.structuredOutputSchema }),
+            const invokeOptions = {
+                ...(options?.structuredOutputSchema && { structuredOutputSchema: options.structuredOutputSchema }),
             };
-            const gen = this._agent.stream(args, options);
+            const gen = this._agent.stream(input, invokeOptions);
             let next = await gen.next();
             while (!next.done) {
-                yield new NodeStreamUpdateEvent({ nodeId: this.id, nodeType: this.type, event: next.value });
+                yield new NodeStreamUpdateEvent({
+                    nodeId: this.id,
+                    nodeType: this.type,
+                    state,
+                    inner: this._agent instanceof Agent
+                        ? { source: 'agent', event: next.value }
+                        : { source: 'custom', event: next.value },
+                });
                 next = await gen.next();
             }
             return {
                 content: next.value.lastMessage.content,
                 ...('structuredOutput' in next.value && { structuredOutput: next.value.structuredOutput }),
+                ...(next.value.metrics?.accumulatedUsage && { usage: next.value.metrics.accumulatedUsage }),
             };
         }
         finally {
-            loadSnapshot(this._agent, snapshot);
+            if (snapshot) {
+                loadSnapshot(this._agent, snapshot);
+            }
         }
     }
 }
@@ -136,12 +151,13 @@ export class MultiAgentNode extends Node {
      * pass through as-is; all other events are wrapped in a new
      * {@link NodeStreamUpdateEvent} tagged with this node's identity.
      *
-     * @param args - Input to pass to the orchestrator
-     * @param _state - The current multi-agent state (unused)
+     * @param input - Input to pass to the orchestrator
+     * @param state - The current multi-agent state
+     * @param _options - Per-invocation options (unused by orchestrator nodes)
      * @returns Async generator yielding streaming events and returning the orchestrator's content
      */
-    async *handle(args, _state) {
-        const gen = this._orchestrator.stream(args);
+    async *handle(input, state, _options) {
+        const gen = this._orchestrator.stream(input);
         let next = await gen.next();
         while (!next.done) {
             const event = next.value;
@@ -149,11 +165,22 @@ export class MultiAgentNode extends Node {
                 yield event;
             }
             else {
-                yield new NodeStreamUpdateEvent({ nodeId: this.id, nodeType: this.type, event });
+                yield new NodeStreamUpdateEvent({
+                    nodeId: this.id,
+                    nodeType: this.type,
+                    state,
+                    inner: { source: 'multiAgent', event },
+                });
             }
             next = await gen.next();
         }
-        return { content: next.value.content };
+        const innerResult = next.value;
+        return {
+            content: innerResult.content,
+            usage: innerResult.usage,
+            ...(innerResult.status !== Status.COMPLETED && { status: innerResult.status }),
+            ...(innerResult.error && { error: innerResult.error }),
+        };
     }
 }
 //# sourceMappingURL=nodes.js.map

package/dist/src/multiagent/nodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../../src/multiagent/nodes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../../src/multiagent/nodes.ts"],"names":[],"mappings":"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"}

package/dist/src/multiagent/plugins.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Plugin interface and registry for extending multi-agent orchestrator functionality.
+ *
+ * This module defines the MultiAgentPlugin abstract class and MultiAgentPluginRegistry,
+ * which provide a composable way to add behavior to multi-agent orchestrators (e.g. Swarm, Graph)
+ * through hook registration and custom initialization.
+ */
+import type { MultiAgent } from './multiagent.js';
+/**
+ * Abstract base class for plugins that extend multi-agent orchestrator functionality.
+ *
+ * MultiAgentPlugins provide a composable way to add behavior to orchestrators
+ * by registering hook callbacks in their `initMultiAgent` method.
+ *
+ * @example
+ * ```typescript
+ * class LoggingPlugin extends MultiAgentPlugin {
+ *   get name(): string {
+ *     return 'logging-plugin'
+ *   }
+ *
+ *   override initMultiAgent(orchestrator: MultiAgent): void {
+ *     orchestrator.addHook(BeforeNodeCallEvent, (event) => {
+ *       console.log(`Node ${event.nodeId} starting`)
+ *     })
+ *   }
+ * }
+ *
+ * const swarm = new Swarm({
+ *   nodes: [agentA, agentB],
+ *   start: 'agentA',
+ *   plugins: [new LoggingPlugin()],
+ * })
+ * ```
+ */
+export declare abstract class MultiAgentPlugin {
+    /**
+     * A stable string identifier for the plugin.
+     * Used for logging, duplicate detection, and plugin management.
+     */
+    abstract readonly name: string;
+    /**
+     * Initialize the plugin with the orchestrator instance.
+     *
+     * Override this method to register hooks and perform custom initialization.
+     *
+     * @param orchestrator - The orchestrator this plugin is being attached to
+     */
+    abstract initMultiAgent(orchestrator: MultiAgent): void | Promise<void>;
+}
+/**
+ * Registry for managing plugins attached to a multi-agent orchestrator.
+ *
+ * Holds pending plugins and initializes them on first use.
+ * Handles duplicate detection and calls each plugin's initMultiAgent method.
+ */
+export declare class MultiAgentPluginRegistry {
+    private readonly _plugins;
+    private readonly _pending;
+    constructor(plugins?: MultiAgentPlugin[]);
+    /**
+     * Initialize all pending plugins with the orchestrator.
+     * Safe to call multiple times — only runs once.
+     *
+     * @param orchestrator - The orchestrator instance to initialize plugins with
+     */
+    initialize(orchestrator: MultiAgent): Promise<void>;
+    private _addAndInit;
+}
+//# sourceMappingURL=plugins.d.ts.map

package/dist/src/multiagent/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../src/multiagent/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BAAsB,gBAAgB;IACpC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,YAAY,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CACxE;AAED;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;gBAEjC,OAAO,GAAE,gBAAgB,EAAO;IAK5C;;;;;OAKG;IACG,UAAU,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAO3C,WAAW;CAO1B"}

package/dist/src/multiagent/plugins.js

@@ -0,0 +1,70 @@
+/**
+ * Plugin interface and registry for extending multi-agent orchestrator functionality.
+ *
+ * This module defines the MultiAgentPlugin abstract class and MultiAgentPluginRegistry,
+ * which provide a composable way to add behavior to multi-agent orchestrators (e.g. Swarm, Graph)
+ * through hook registration and custom initialization.
+ */
+/**
+ * Abstract base class for plugins that extend multi-agent orchestrator functionality.
+ *
+ * MultiAgentPlugins provide a composable way to add behavior to orchestrators
+ * by registering hook callbacks in their `initMultiAgent` method.
+ *
+ * @example
+ * ```typescript
+ * class LoggingPlugin extends MultiAgentPlugin {
+ *   get name(): string {
+ *     return 'logging-plugin'
+ *   }
+ *
+ *   override initMultiAgent(orchestrator: MultiAgent): void {
+ *     orchestrator.addHook(BeforeNodeCallEvent, (event) => {
+ *       console.log(`Node ${event.nodeId} starting`)
+ *     })
+ *   }
+ * }
+ *
+ * const swarm = new Swarm({
+ *   nodes: [agentA, agentB],
+ *   start: 'agentA',
+ *   plugins: [new LoggingPlugin()],
+ * })
+ * ```
+ */
+export class MultiAgentPlugin {
+}
+/**
+ * Registry for managing plugins attached to a multi-agent orchestrator.
+ *
+ * Holds pending plugins and initializes them on first use.
+ * Handles duplicate detection and calls each plugin's initMultiAgent method.
+ */
+export class MultiAgentPluginRegistry {
+    _plugins;
+    _pending;
+    constructor(plugins = []) {
+        this._plugins = new Map();
+        this._pending = [...plugins];
+    }
+    /**
+     * Initialize all pending plugins with the orchestrator.
+     * Safe to call multiple times — only runs once.
+     *
+     * @param orchestrator - The orchestrator instance to initialize plugins with
+     */
+    async initialize(orchestrator) {
+        while (this._pending.length > 0) {
+            const plugin = this._pending.shift();
+            await this._addAndInit(plugin, orchestrator);
+        }
+    }
+    async _addAndInit(plugin, orchestrator) {
+        if (this._plugins.has(plugin.name)) {
+            throw new Error(`plugin_name=<${plugin.name}> | plugin already registered`);
+        }
+        this._plugins.set(plugin.name, plugin);
+        await plugin.initMultiAgent(orchestrator);
+    }
+}
+//# sourceMappingURL=plugins.js.map

package/dist/src/multiagent/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../../src/multiagent/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAgB,gBAAgB;CAerC;AAED;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAClB,QAAQ,CAA+B;IACvC,QAAQ,CAAoB;IAE7C,YAAY,UAA8B,EAAE;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,YAAwB;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAG,CAAA;YACrC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,MAAwB,EAAE,YAAwB;QAC1E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,gBAAgB,MAAM,CAAC,IAAI,+BAA+B,CAAC,CAAA;QAC7E,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACtC,MAAM,MAAM,CAAC,cAAc,CAAC,YAAY,CAAC,CAAA;IAC3C,CAAC;CACF"}

package/dist/src/multiagent/state.d.ts

@@ -1,5 +1,6 @@
-import { AppState } from '../app-state.js';
+import { StateStore } from '../state-store.js';
 import type { ContentBlock } from '../types/messages.js';
+import type { Usage } from '../models/streaming.js';
 import type { z } from 'zod';
 /**
  * Execution lifecycle status shared across all multi-agent patterns.
@@ -37,6 +38,8 @@ export declare class NodeResult {
     readonly error?: Error;
     /** Validated structured output, if a schema was provided. */
     readonly structuredOutput?: z.output<z.ZodType>;
+    /** Token usage from the node execution. */
+    readonly usage?: Usage;
     constructor(data: {
         nodeId: string;
         status: ResultStatus;
@@ -44,6 +47,7 @@ export declare class NodeResult {
         content?: ContentBlock[];
         error?: Error;
         structuredOutput?: z.output<z.ZodType>;
+        usage?: Usage;
     });
 }
 /**
@@ -80,6 +84,8 @@ export declare class MultiAgentResult {
     readonly content: ContentBlock[];
     readonly duration: number;
     readonly error?: Error;
+    /** Aggregated token usage across all node results. */
+    readonly usage: Usage;
     constructor(data: {
         status?: ResultStatus;
         results: NodeResult[];
@@ -89,6 +95,8 @@ export declare class MultiAgentResult {
     });
     /** Derives the aggregate status from individual node results. */
     private _resolveStatus;
+    /** Sums token usage across all node results. */
+    private _aggregateNodeUsage;
 }
 /**
  * Shared state for multi-agent orchestration patterns.
@@ -101,13 +109,10 @@ export declare class MultiAgentState {
     /** All node results in completion order. */
     readonly results: NodeResult[];
     /** App-level key-value state accessible from hooks, edge handlers, and custom nodes. */
-    readonly app: AppState;
-    /** Structured output schema to apply to node invocations. */
-    readonly structuredOutputSchema?: z.ZodSchema;
+    readonly app: StateStore;
     private readonly _nodes;
     constructor(data?: {
         nodeIds?: string[];
-        structuredOutputSchema?: z.ZodSchema;
     });
     /**
      * Get the state of a specific node by ID.

package/dist/src/multiagent/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/multiagent/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/multiagent/state.ts"],"names":[],"mappings":"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"}