@strands-agents/sdk 0.3.0 → 0.5.0

package/dist/src/multiagent/events.js

@@ -0,0 +1,140 @@
+import { HookableEvent } from '../hooks/events.js';
+/**
+ * Event triggered when a multi-agent orchestrator has finished initialization.
+ */
+export class MultiAgentInitializedEvent extends HookableEvent {
+    type = 'multiAgentInitializedEvent';
+    orchestrator;
+    constructor(data) {
+        super();
+        this.orchestrator = data.orchestrator;
+    }
+}
+/**
+ * Event triggered before orchestrator execution starts.
+ */
+export class BeforeMultiAgentInvocationEvent extends HookableEvent {
+    type = 'beforeMultiAgentInvocationEvent';
+    orchestrator;
+    state;
+    constructor(data) {
+        super();
+        this.orchestrator = data.orchestrator;
+        this.state = data.state;
+    }
+}
+/**
+ * Event triggered after orchestrator execution completes.
+ */
+export class AfterMultiAgentInvocationEvent extends HookableEvent {
+    type = 'afterMultiAgentInvocationEvent';
+    orchestrator;
+    state;
+    constructor(data) {
+        super();
+        this.orchestrator = data.orchestrator;
+        this.state = data.state;
+    }
+    _shouldReverseCallbacks() {
+        return true;
+    }
+}
+/**
+ * Event triggered before a node begins execution.
+ * Hook callbacks can set {@link cancel} to prevent the node from executing.
+ */
+export class BeforeNodeCallEvent extends HookableEvent {
+    type = 'beforeNodeCallEvent';
+    orchestrator;
+    state;
+    nodeId;
+    /**
+     * Set by hook callbacks to cancel node execution.
+     * When set to `true`, a default cancel message is used.
+     * When set to a string, that string is used as the cancel message.
+     */
+    cancel = false;
+    constructor(data) {
+        super();
+        this.orchestrator = data.orchestrator;
+        this.state = data.state;
+        this.nodeId = data.nodeId;
+    }
+}
+/**
+ * Event triggered after a node completes execution.
+ */
+export class AfterNodeCallEvent extends HookableEvent {
+    type = 'afterNodeCallEvent';
+    orchestrator;
+    state;
+    nodeId;
+    constructor(data) {
+        super();
+        this.orchestrator = data.orchestrator;
+        this.state = data.state;
+        this.nodeId = data.nodeId;
+    }
+    _shouldReverseCallbacks() {
+        return true;
+    }
+}
+/**
+ * Wraps an inner streaming event from a node with the node's identity.
+ * Emitted during node execution to propagate agent-level or nested
+ * multi-agent events up to the orchestration layer.
+ */
+export class NodeStreamUpdateEvent extends HookableEvent {
+    type = 'nodeStreamUpdateEvent';
+    nodeId;
+    nodeType;
+    event;
+    constructor(data) {
+        super();
+        this.nodeId = data.nodeId;
+        this.nodeType = data.nodeType;
+        this.event = data.event;
+    }
+}
+/**
+ * Event triggered when a node finishes execution.
+ * Wraps the {@link NodeResult} for the completed node.
+ */
+export class NodeResultEvent extends HookableEvent {
+    type = 'nodeResultEvent';
+    nodeId;
+    nodeType;
+    result;
+    constructor(data) {
+        super();
+        this.nodeId = data.nodeId;
+        this.nodeType = data.nodeType;
+        this.result = data.result;
+    }
+}
+/**
+ * Event triggered when execution transitions between nodes.
+ */
+export class MultiAgentHandoffEvent extends HookableEvent {
+    type = 'multiAgentHandoffEvent';
+    source;
+    targets;
+    constructor(data) {
+        super();
+        this.source = data.source;
+        this.targets = data.targets;
+    }
+}
+/**
+ * Event triggered as the final event in the multi-agent stream.
+ * Wraps the {@link MultiAgentResult} containing the aggregate outcome.
+ */
+export class MultiAgentResultEvent extends HookableEvent {
+    type = 'multiAgentResultEvent';
+    result;
+    constructor(data) {
+        super();
+        this.result = data.result;
+    }
+}
+//# sourceMappingURL=events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/multiagent/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAMlD;;GAEG;AACH,MAAM,OAAO,0BAA2B,SAAQ,aAAa;IAClD,IAAI,GAAG,4BAAqC,CAAA;IAC5C,YAAY,CAAgB;IAErC,YAAY,IAAsC;QAChD,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;IACvC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,+BAAgC,SAAQ,aAAa;IACvD,IAAI,GAAG,iCAA0C,CAAA;IACjD,YAAY,CAAgB;IAC5B,KAAK,CAAiB;IAE/B,YAAY,IAA8D;QACxE,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,8BAA+B,SAAQ,aAAa;IACtD,IAAI,GAAG,gCAAyC,CAAA;IAChD,YAAY,CAAgB;IAC5B,KAAK,CAAiB;IAE/B,YAAY,IAA8D;QACxE,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;IAEQ,uBAAuB;QAC9B,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAC3C,IAAI,GAAG,qBAA8B,CAAA;IACrC,YAAY,CAAgB;IAC5B,KAAK,CAAiB;IACtB,MAAM,CAAQ;IAEvB;;;;OAIG;IACH,MAAM,GAAqB,KAAK,CAAA;IAEhC,YAAY,IAA8E;QACxF,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC1C,IAAI,GAAG,oBAA6B,CAAA;IACpC,YAAY,CAAgB;IAC5B,KAAK,CAAiB;IACtB,MAAM,CAAQ;IAEvB,YAAY,IAA8E;QACxF,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC3B,CAAC;IAEQ,uBAAuB;QAC9B,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,IAAI,GAAG,uBAAgC,CAAA;IACvC,MAAM,CAAQ;IACd,QAAQ,CAAU;IAClB,KAAK,CAA0E;IAExF,YAAY,IAIX;QACC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IACvC,IAAI,GAAG,iBAA0B,CAAA;IACjC,MAAM,CAAQ;IACd,QAAQ,CAAU;IAClB,MAAM,CAAY;IAE3B,YAAY,IAAgE;QAC1E,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IAC9C,IAAI,GAAG,wBAAiC,CAAA;IACxC,MAAM,CAAQ;IACd,OAAO,CAAU;IAE1B,YAAY,IAA2C;QACrD,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,IAAI,GAAG,uBAAgC,CAAA;IACvC,MAAM,CAAkB;IAEjC,YAAY,IAAkC;QAC5C,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC3B,CAAC;CACF"}

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

@@ -0,0 +1,13 @@
+/**
+ * Multi-agent orchestration module.
+ */
+export { MultiAgentState, NodeState, Status, NodeResult, MultiAgentResult } from './state.js';
+export type { NodeResultUpdate, ResultStatus } from './state.js';
+export { Node, AgentNode, MultiAgentNode } from './nodes.js';
+export type { NodeConfig, AgentNodeOptions, MultiAgentNodeOptions, NodeDefinition, NodeType } from './nodes.js';
+export type { MultiAgentBase } from './base.js';
+export { MultiAgentInitializedEvent, BeforeMultiAgentInvocationEvent, AfterMultiAgentInvocationEvent, BeforeNodeCallEvent, AfterNodeCallEvent, NodeStreamUpdateEvent, NodeResultEvent, MultiAgentHandoffEvent, MultiAgentResultEvent, } from './events.js';
+export type { MultiAgentStreamEvent } from './events.js';
+export { Edge } from './edge.js';
+export type { EdgeHandler, EdgeDefinition } from './edge.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/multiagent/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7F,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC5D,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE/G,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE/C,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,EAC9B,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA"}

package/dist/src/multiagent/index.js

@@ -0,0 +1,8 @@
+/**
+ * Multi-agent orchestration module.
+ */
+export { MultiAgentState, NodeState, Status, NodeResult, MultiAgentResult } from './state.js';
+export { Node, AgentNode, MultiAgentNode } from './nodes.js';
+export { MultiAgentInitializedEvent, BeforeMultiAgentInvocationEvent, AfterMultiAgentInvocationEvent, BeforeNodeCallEvent, AfterNodeCallEvent, NodeStreamUpdateEvent, NodeResultEvent, MultiAgentHandoffEvent, MultiAgentResultEvent, } from './events.js';
+export { Edge } from './edge.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/multiagent/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG7F,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAK5D,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,EAC9B,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

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

@@ -0,0 +1,123 @@
+import type { Agent, InvokeArgs } from '../agent/agent.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';
+/**
+ * Known node type identifiers with extensibility for custom nodes.
+ */
+export type NodeType = 'agentNode' | 'multiAgentNode' | (string & {});
+/**
+ * Configuration for a node execution.
+ */
+export interface NodeConfig {
+    /**
+     * Maximum execution time for this node in milliseconds.
+     */
+    timeout?: number;
+}
+/**
+ * Abstract base class for all multi-agent orchestration nodes.
+ *
+ * Uses the template method pattern: {@link stream} handles orchestration
+ * boilerplate (duration measurement, status tracking, error capture) and
+ * delegates to {@link handle} for node-specific execution logic.
+ */
+export declare abstract class Node {
+    readonly type: string;
+    /** Unique identifier for this node within the orchestration. */
+    readonly id: string;
+    /** Per-node configuration. */
+    readonly config: NodeConfig;
+    /**
+     * @param id - Unique identifier for this node within the orchestration
+     * @param config - Per-node configuration
+     */
+    constructor(id: string, config: NodeConfig);
+    /**
+     * 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 state - The current multi-agent state
+     * @returns Async generator yielding streaming events and returning a NodeResult
+     */
+    stream(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResult, undefined>;
+    /**
+     * Node-specific execution logic implemented by subclasses.
+     *
+     * @param args - Input to process (string, content blocks, or messages)
+     * @param state - The current multi-agent state
+     * @returns Async generator yielding streaming events and returning a partial result
+     */
+    abstract handle(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+}
+/**
+ * Options for creating an {@link AgentNode}.
+ */
+export interface AgentNodeOptions extends NodeConfig {
+    /** Unique node identifier. */
+    id: string;
+    /** The agent to wrap as a node. */
+    agent: Agent;
+}
+/**
+ * Node that wraps an Agent instance for multi-agent orchestration.
+ *
+ * Each execution is isolated — the wrapped agent's internal state
+ * is unchanged after the node completes.
+ */
+export declare class AgentNode extends Node {
+    readonly type: "agentNode";
+    private readonly _agent;
+    constructor(options: AgentNodeOptions);
+    get agent(): Agent;
+    /**
+     * Executes the wrapped agent, yielding each agent streaming event
+     * wrapped in a {@link NodeStreamUpdateEvent}.
+     *
+     * @param args - Input to pass to the agent
+     * @param state - The current multi-agent state
+     * @returns Async generator yielding streaming events and returning the agent's content blocks
+     */
+    handle(args: InvokeArgs, state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+}
+/**
+ * Options for creating a {@link MultiAgentNode}.
+ */
+export interface MultiAgentNodeOptions extends NodeConfig {
+    /** The orchestrator to wrap as a node. */
+    orchestrator: MultiAgentBase;
+}
+/**
+ * Node that wraps a multi-agent orchestrator (e.g. Graph) for nested composition.
+ *
+ * Inner {@link NodeStreamUpdateEvent}s pass through to preserve the original
+ * node's identity. All other events are wrapped in a new {@link NodeStreamUpdateEvent}
+ * tagged with this node's identity.
+ */
+export declare class MultiAgentNode extends Node {
+    readonly type: "multiAgentNode";
+    private readonly _orchestrator;
+    constructor(options: MultiAgentNodeOptions);
+    get orchestrator(): MultiAgentBase;
+    /**
+     * 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)
+     * @returns Async generator yielding streaming events and returning the orchestrator's content
+     */
+    handle(args: InvokeArgs, _state: MultiAgentState): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined>;
+}
+/**
+ * A node definition accepted by orchestration constructors.
+ */
+export type NodeDefinition = Node | (AgentNodeOptions & {
+    type: 'agent';
+}) | (MultiAgentNodeOptions & {
+    type: 'multiAgent';
+});
+//# sourceMappingURL=nodes.d.ts.map

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

@@ -0,0 +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;AAE/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,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;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;IA0B/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,gBAAiB,SAAQ,UAAU;IAClD,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,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;IAMrC,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;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,IAAI,GACJ,CAAC,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,GACtC,CAAC,qBAAqB,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAA"}

package/dist/src/multiagent/nodes.js

@@ -0,0 +1,148 @@
+import { takeSnapshot, loadSnapshot } from '../agent/snapshot.js';
+import { NodeStreamUpdateEvent, NodeResultEvent } from './events.js';
+import { NodeResult, Status } from './state.js';
+/**
+ * Abstract base class for all multi-agent orchestration nodes.
+ *
+ * Uses the template method pattern: {@link stream} handles orchestration
+ * boilerplate (duration measurement, status tracking, error capture) and
+ * delegates to {@link handle} for node-specific execution logic.
+ */
+export class Node {
+    type = 'node';
+    /** Unique identifier for this node within the orchestration. */
+    id;
+    /** Per-node configuration. */
+    config;
+    /**
+     * @param id - Unique identifier for this node within the orchestration
+     * @param config - Per-node configuration
+     */
+    constructor(id, config) {
+        this.id = id;
+        this.config = config;
+    }
+    /**
+     * 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 state - The current multi-agent state
+     * @returns Async generator yielding streaming events and returning a NodeResult
+     */
+    async *stream(args, state) {
+        const startTime = Date.now();
+        let result;
+        try {
+            const update = yield* this.handle(args, state);
+            result = new NodeResult({
+                nodeId: this.id,
+                status: Status.COMPLETED,
+                duration: Date.now() - startTime,
+                content: [],
+                ...update,
+            });
+        }
+        catch (error) {
+            result = new NodeResult({
+                nodeId: this.id,
+                status: Status.FAILED,
+                duration: Date.now() - startTime,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+        yield new NodeResultEvent({ nodeId: this.id, nodeType: this.type, result });
+        return result;
+    }
+}
+/**
+ * Node that wraps an Agent instance for multi-agent orchestration.
+ *
+ * Each execution is isolated — the wrapped agent's internal state
+ * is unchanged after the node completes.
+ */
+export class AgentNode extends Node {
+    type = 'agentNode';
+    _agent;
+    constructor(options) {
+        const { id, agent, ...config } = options;
+        super(id, config);
+        this._agent = agent;
+    }
+    get agent() {
+        return this._agent;
+    }
+    /**
+     * Executes the wrapped agent, yielding each agent streaming event
+     * wrapped in a {@link NodeStreamUpdateEvent}.
+     *
+     * @param args - Input to pass to the agent
+     * @param state - The current multi-agent state
+     * @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'] });
+        try {
+            const options = {
+                ...(state.structuredOutputSchema && { structuredOutputSchema: state.structuredOutputSchema }),
+            };
+            const gen = this._agent.stream(args, options);
+            let next = await gen.next();
+            while (!next.done) {
+                yield new NodeStreamUpdateEvent({ nodeId: this.id, nodeType: this.type, event: next.value });
+                next = await gen.next();
+            }
+            return {
+                content: next.value.lastMessage.content,
+                ...('structuredOutput' in next.value && { structuredOutput: next.value.structuredOutput }),
+            };
+        }
+        finally {
+            loadSnapshot(this._agent, snapshot);
+        }
+    }
+}
+/**
+ * Node that wraps a multi-agent orchestrator (e.g. Graph) for nested composition.
+ *
+ * Inner {@link NodeStreamUpdateEvent}s pass through to preserve the original
+ * node's identity. All other events are wrapped in a new {@link NodeStreamUpdateEvent}
+ * tagged with this node's identity.
+ */
+export class MultiAgentNode extends Node {
+    type = 'multiAgentNode';
+    _orchestrator;
+    constructor(options) {
+        const { orchestrator, ...config } = options;
+        super(orchestrator.id, config);
+        this._orchestrator = orchestrator;
+    }
+    get orchestrator() {
+        return this._orchestrator;
+    }
+    /**
+     * 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)
+     * @returns Async generator yielding streaming events and returning the orchestrator's content
+     */
+    async *handle(args, _state) {
+        const gen = this._orchestrator.stream(args);
+        let next = await gen.next();
+        while (!next.done) {
+            const event = next.value;
+            if (event.type === 'nodeStreamUpdateEvent') {
+                yield event;
+            }
+            else {
+                yield new NodeStreamUpdateEvent({ nodeId: this.id, nodeType: this.type, event });
+            }
+            next = await gen.next();
+        }
+        return { content: next.value.content };
+    }
+}
+//# sourceMappingURL=nodes.js.map

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

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

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

@@ -0,0 +1,67 @@
+import type { Node } from './nodes.js';
+import type { MultiAgentStreamEvent } from './events.js';
+import type { NodeResult } from './state.js';
+/**
+ * Data produced by a running node: a streaming event, a completion signal, or an error.
+ */
+export type QueueData = {
+    type: 'event';
+    node: Node;
+    event: MultiAgentStreamEvent;
+} | {
+    type: 'result';
+    node: Node;
+    result: NodeResult;
+} | {
+    type: 'error';
+    node: Node;
+    error: Error;
+};
+/**
+ * Queue data paired with an acknowledgement callback.
+ * The consumer must call {@link ack} after fully processing the data
+ * to unblock any producer waiting via {@link Queue.send}.
+ */
+export interface QueueEntry {
+    data: QueueData;
+    ack: () => void;
+}
+/**
+ * Async queue with promise-based notification and optional back-pressure.
+ *
+ * Producers use {@link push} for fire-and-forget or {@link send} to
+ * block until the consumer has fully processed the data. The consumer calls
+ * {@link shift} to dequeue, then {@link QueueEntry.ack} after
+ * processing to unblock the producer.
+ */
+export declare class Queue {
+    private readonly _entries;
+    /** Resolve function for the pending wait() promise, if any. */
+    private _notify?;
+    /**
+     * Push data to the queue, waking any waiting consumer.
+     */
+    push(data: QueueData): void;
+    /**
+     * Push data and wait until the consumer has fully processed it.
+     * Provides back-pressure so the producer pauses until the event
+     * has been yielded and hook callbacks have been invoked.
+     *
+     * @param data - The queue data to push
+     * @returns Promise that resolves when the consumer calls {@link QueueEntry.ack}
+     */
+    send(data: QueueData): Promise<void>;
+    /**
+     * Wait until at least one entry is available.
+     */
+    wait(): Promise<void>;
+    /**
+     * Remove and return the next entry, or undefined if empty.
+     */
+    shift(): QueueEntry | undefined;
+    /**
+     * Number of entries in the queue.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/multiagent/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAA;IACf,GAAG,EAAE,MAAM,IAAI,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,+DAA+D;IAC/D,OAAO,CAAC,OAAO,CAAC,CAA0B;IAE1C;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAM3B;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrB;;OAEG;IACH,KAAK,IAAI,UAAU,GAAG,SAAS;IAI/B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/src/multiagent/queue.js

@@ -0,0 +1,59 @@
+/**
+ * Async queue with promise-based notification and optional back-pressure.
+ *
+ * Producers use {@link push} for fire-and-forget or {@link send} to
+ * block until the consumer has fully processed the data. The consumer calls
+ * {@link shift} to dequeue, then {@link QueueEntry.ack} after
+ * processing to unblock the producer.
+ */
+export class Queue {
+    _entries = [];
+    /** Resolve function for the pending wait() promise, if any. */
+    _notify;
+    /**
+     * Push data to the queue, waking any waiting consumer.
+     */
+    push(data) {
+        this._entries.push({ data, ack: () => { } });
+        this._notify?.();
+        this._notify = undefined;
+    }
+    /**
+     * Push data and wait until the consumer has fully processed it.
+     * Provides back-pressure so the producer pauses until the event
+     * has been yielded and hook callbacks have been invoked.
+     *
+     * @param data - The queue data to push
+     * @returns Promise that resolves when the consumer calls {@link QueueEntry.ack}
+     */
+    send(data) {
+        return new Promise((resolve) => {
+            this._entries.push({ data, ack: resolve });
+            this._notify?.();
+            this._notify = undefined;
+        });
+    }
+    /**
+     * Wait until at least one entry is available.
+     */
+    wait() {
+        if (this._entries.length > 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this._notify = resolve;
+        });
+    }
+    /**
+     * Remove and return the next entry, or undefined if empty.
+     */
+    shift() {
+        return this._entries.shift();
+    }
+    /**
+     * Number of entries in the queue.
+     */
+    get size() {
+        return this._entries.length;
+    }
+}
+//# sourceMappingURL=queue.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../../src/multiagent/queue.ts"],"names":[],"mappings":"AAsBA;;;;;;;GAOG;AACH,MAAM,OAAO,KAAK;IACC,QAAQ,GAAiB,EAAE,CAAA;IAC5C,+DAA+D;IACvD,OAAO,CAA2B;IAE1C;;OAEG;IACH,IAAI,CAAC,IAAe;QAClB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC,CAAA;QAC3C,IAAI,CAAC,OAAO,EAAE,EAAE,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,IAAe;QAClB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;YAC1C,IAAI,CAAC,OAAO,EAAE,EAAE,CAAA;YAChB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;QAC1B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QACtD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACxB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAA;IAC7B,CAAC;CACF"}