@strands-agents/sdk 0.5.0 → 0.7.0

package/README.md

@@ -47,6 +47,7 @@ Strands Agents is a simple yet powerful SDK that takes a model-driven approach t
 - **⚡ Streaming Support**: Real-time response streaming for better user experience
 - **🎣 Extensible Hooks**: Lifecycle hooks for monitoring and customizing agent behavior
 - **💬 Conversation Management**: Flexible strategies for managing conversation history and context windows
+- **🤝 Multi-Agent Orchestration**: Graph and Swarm patterns for coordinating multiple agents
 
 ---
 
@@ -235,6 +236,69 @@ await agent.invoke("Use a random tool from the MCP server.");
 await documentationTools.disconnect();
 ```
 
+### Multi-Agent Orchestration
+
+Coordinate multiple agents using built-in orchestration patterns.
+
+**Graph** — You define a deterministic execution plan. Agents run as nodes in a directed graph, with edges controlling execution order. Parallel execution is supported, and downstream nodes run once all dependencies complete.
+
+```typescript
+import { Agent, BedrockModel, Graph } from '@strands-agents/sdk'
+
+const model = new BedrockModel({ maxTokens: 1024 })
+
+const researcher = new Agent({
+  model,
+  id: 'researcher',
+  systemPrompt: 'Research the topic and provide key facts.',
+})
+
+const writer = new Agent({
+  model,
+  id: 'writer',
+  systemPrompt: 'Rewrite the research into a polished paragraph.',
+})
+
+const graph = new Graph({
+  nodes: [researcher, writer],
+  edges: [['researcher', 'writer']],
+})
+
+const result = await graph.invoke('What is the largest ocean?')
+```
+
+**Swarm** — The agents decide the routing. Each agent chooses whether to hand off to another agent or produce a final response, making the execution path dynamic and model-driven.
+
+```typescript
+import { Agent, BedrockModel, Swarm } from '@strands-agents/sdk'
+
+const model = new BedrockModel({ maxTokens: 1024 })
+
+const researcher = new Agent({
+  model,
+  id: 'researcher',
+  description: 'Researches a topic and gathers key facts.',
+  systemPrompt: 'Research the answer, then hand off to the writer.',
+})
+
+const writer = new Agent({
+  model,
+  id: 'writer',
+  description: 'Writes a polished final answer.',
+  systemPrompt: 'Write the final answer. Do not hand off.',
+})
+
+const swarm = new Swarm({
+  nodes: [researcher, writer],
+  start: 'researcher',
+  maxSteps: 4,
+})
+
+const result = await swarm.invoke('What is the largest ocean?')
+```
+
+Both patterns support streaming via `.stream()` for real-time access to handoff and node execution events. See the [examples](./examples/) directory for complete working samples.
+
 ---
 
 ## Documentation

package/dist/src/__fixtures__/agent-helpers.d.ts

@@ -6,6 +6,16 @@ import type { Agent } from '../agent/agent.js';
 import { Message } from '../types/messages.js';
 import type { Role } from '../types/messages.js';
 import type { JSONValue } from '../types/json.js';
+import { ToolRegistry } from '../registry/tool-registry.js';
+import type { HookableEvent } from '../hooks/events.js';
+import type { HookableEventConstructor, HookCallback } from '../hooks/types.js';
+/**
+ * A hook registration captured by the mock agent's addHook.
+ */
+export type TrackedHook = {
+    eventType: HookableEventConstructor<HookableEvent>;
+    callback: HookCallback<HookableEvent>;
+};
 /**
  * Data for creating a mock Agent.
  */
@@ -17,16 +27,31 @@ export interface MockAgentData {
     /**
      * Initial state for the agent.
      */
-    state?: Record<string, JSONValue>;
+    appState?: Record<string, JSONValue>;
+    /**
+     * Optional tool registry for the agent.
+     */
+    toolRegistry?: ToolRegistry;
+    /**
+     * Additional properties to spread onto the mock agent.
+     */
+    extra?: Partial<Agent>;
 }
+/**
+ * A mock Agent with a `trackedHooks` array populated by `addHook` calls.
+ */
+export type MockAgent = Agent & {
+    trackedHooks: TrackedHook[];
+};
 /**
  * Helper to create a mock Agent for testing.
- * Provides minimal Agent interface with messages and state.
+ * Provides minimal Agent interface with messages, appState, and tool registry.
+ * `addHook` captures registrations into `trackedHooks` for test inspection.
  *
  * @param data - Optional mock agent data
- * @returns Mock Agent object
+ * @returns Mock Agent with trackedHooks
  */
-export declare function createMockAgent(data?: MockAgentData): Agent;
+export declare function createMockAgent(data?: MockAgentData): MockAgent;
 /**
  * Creates a Message with the given role containing a single TextBlock.
  *
@@ -35,4 +60,12 @@ export declare function createMockAgent(data?: MockAgentData): Agent;
  * @returns A Message with the specified role
  */
 export declare function textMessage(role: Role, text: string): Message;
+/**
+ * Finds the tracked hook for the given event type and invokes it with the provided event.
+ * Throws if no hook is registered for that event type.
+ *
+ * @param agent - The mock agent with tracked hooks
+ * @param event - The event instance to dispatch
+ */
+export declare function invokeTrackedHook<T extends HookableEvent>(agent: MockAgent, event: T): Promise<void>;
 //# sourceMappingURL=agent-helpers.d.ts.map

package/dist/src/__fixtures__/agent-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-helpers.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/agent-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAa,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,KAAK,CAK3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"agent-helpers.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/agent-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAa,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE/E;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,wBAAwB,CAAC,aAAa,CAAC,CAAA;IAClD,QAAQ,EAAE,YAAY,CAAC,aAAa,CAAC,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACpC;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG;IAAE,YAAY,EAAE,WAAW,EAAE,CAAA;CAAE,CAAA;AAE/D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAgB/D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAM1G"}

package/dist/src/__fixtures__/agent-helpers.js

@@ -3,18 +3,31 @@
  * This module provides utilities for testing Agent-related implementations.
  */
 import { Message, TextBlock } from '../types/messages.js';
-import { AppState } from '../app-state.js';
+import { StateStore } from '../state-store.js';
+import { ToolRegistry } from '../registry/tool-registry.js';
 /**
  * Helper to create a mock Agent for testing.
- * Provides minimal Agent interface with messages and state.
+ * Provides minimal Agent interface with messages, appState, and tool registry.
+ * `addHook` captures registrations into `trackedHooks` for test inspection.
  *
  * @param data - Optional mock agent data
- * @returns Mock Agent object
+ * @returns Mock Agent with trackedHooks
  */
 export function createMockAgent(data) {
+    const trackedHooks = [];
     return {
         messages: data?.messages ?? [],
-        state: new AppState(data?.state ?? {}),
+        appState: new StateStore(data?.appState ?? {}),
+        toolRegistry: data?.toolRegistry ?? new ToolRegistry(),
+        addHook: (eventType, callback) => {
+            trackedHooks.push({
+                eventType: eventType,
+                callback: callback,
+            });
+            return () => { };
+        },
+        ...data?.extra,
+        trackedHooks,
     };
 }
 /**
@@ -27,4 +40,18 @@ export function createMockAgent(data) {
 export function textMessage(role, text) {
     return new Message({ role, content: [new TextBlock(text)] });
 }
+/**
+ * Finds the tracked hook for the given event type and invokes it with the provided event.
+ * Throws if no hook is registered for that event type.
+ *
+ * @param agent - The mock agent with tracked hooks
+ * @param event - The event instance to dispatch
+ */
+export async function invokeTrackedHook(agent, event) {
+    const hook = agent.trackedHooks.find((h) => h.eventType === event.constructor);
+    if (!hook) {
+        throw new Error(`No hook registered for event type: ${event.constructor.name}`);
+    }
+    await hook.callback(event);
+}
 //# sourceMappingURL=agent-helpers.js.map

package/dist/src/__fixtures__/agent-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-helpers.js","sourceRoot":"","sources":["../../../src/__fixtures__/agent-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAiB1C;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,OAAO;QACL,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE;QAC9B,KAAK,EAAE,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;KACnB,CAAA;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,IAAY;IAClD,OAAO,IAAI,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AAC9D,CAAC"}
+{"version":3,"file":"agent-helpers.js","sourceRoot":"","sources":["../../../src/__fixtures__/agent-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAuC3D;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,MAAM,YAAY,GAAkB,EAAE,CAAA;IACtC,OAAO;QACL,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE;QAC9B,QAAQ,EAAE,IAAI,UAAU,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC;QAC9C,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,IAAI,YAAY,EAAE;QACtD,OAAO,EAAE,CAA0B,SAAsC,EAAE,QAAyB,EAAE,EAAE;YACtG,YAAY,CAAC,IAAI,CAAC;gBAChB,SAAS,EAAE,SAAoD;gBAC/D,QAAQ,EAAE,QAAuC;aAClD,CAAC,CAAA;YACF,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;QACjB,CAAC;QACD,GAAG,IAAI,EAAE,KAAK;QACd,YAAY;KACW,CAAA;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,IAAY;IAClD,OAAO,IAAI,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAA0B,KAAgB,EAAE,KAAQ;IACzF,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,KAAK,CAAC,WAAW,CAAC,CAAA;IAC9E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,sCAAsC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;IACjF,CAAC;IACD,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC5B,CAAC"}

package/dist/src/__fixtures__/metrics-helpers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Test helpers for asserting on AgentMetrics in agent tests.
+ */
+import type { Usage } from '../models/streaming.js';
+import { AgentMetrics } from '../telemetry/meter.js';
+/**
+ * Options for building an AgentMetrics matcher.
+ */
+export interface LoopMetricsMatcher {
+    /**
+     * Expected number of agent loop cycles.
+     */
+    cycleCount: number;
+    /**
+     * Expected tool names that were invoked.
+     */
+    toolNames?: string[];
+    /**
+     * Expected accumulated token usage. When provided, asserts exact values.
+     * When omitted, asserts the shape with expect.any(Number).
+     */
+    usage?: Usage;
+}
+/**
+ * Creates an asymmetric matcher that validates AgentMetrics structure and values.
+ *
+ * @param options - Expected metric values
+ * @returns An asymmetric matcher suitable for use in expect().toEqual()
+ */
+export declare function expectLoopMetrics(options: LoopMetricsMatcher): AgentMetrics;
+/**
+ * Finds the latest data point value for a named metric from OTEL ResourceMetrics.
+ *
+ * Flattens the ResourceMetrics → ScopeMetrics → MetricData hierarchy and
+ * returns the value of the last data point for the matching metric name.
+ * For counters this is a number; for histograms it is an object with
+ * sum, count, min, max, etc.
+ *
+ * @param resourceMetrics - Array of ResourceMetrics from an InMemoryMetricExporter
+ * @param metricName - The metric descriptor name to search for
+ * @returns The value of the last data point, or undefined if not found
+ */
+export declare function findMetricValue(resourceMetrics: {
+    scopeMetrics: {
+        metrics: {
+            descriptor: {
+                name: string;
+            };
+            dataPoints: {
+                value: unknown;
+            }[];
+        }[];
+    }[];
+}[], metricName: string): unknown;
+//# sourceMappingURL=metrics-helpers.d.ts.map

package/dist/src/__fixtures__/metrics-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-helpers.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/metrics-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CA2B3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE;IACf,YAAY,EAAE;QAAE,OAAO,EAAE;YAAE,UAAU,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,UAAU,EAAE;gBAAE,KAAK,EAAE,OAAO,CAAA;aAAE,EAAE,CAAA;SAAE,EAAE,CAAA;KAAE,EAAE,CAAA;CAClG,EAAE,EACH,UAAU,EAAE,MAAM,GACjB,OAAO,CAQT"}

package/dist/src/__fixtures__/metrics-helpers.js

@@ -0,0 +1,57 @@
+/**
+ * Test helpers for asserting on AgentMetrics in agent tests.
+ */
+import { expect } from 'vitest';
+import { AgentMetrics } from '../telemetry/meter.js';
+/**
+ * Creates an asymmetric matcher that validates AgentMetrics structure and values.
+ *
+ * @param options - Expected metric values
+ * @returns An asymmetric matcher suitable for use in expect().toEqual()
+ */
+export function expectLoopMetrics(options) {
+    const { cycleCount, toolNames = [], usage } = options;
+    const expectedToolMetrics = {};
+    for (const name of toolNames) {
+        expectedToolMetrics[name] = {
+            callCount: expect.any(Number),
+            successCount: expect.any(Number),
+            errorCount: expect.any(Number),
+            totalTime: expect.any(Number),
+        };
+    }
+    const expectedUsage = usage ??
+        expect.objectContaining({
+            inputTokens: expect.any(Number),
+            outputTokens: expect.any(Number),
+            totalTokens: expect.any(Number),
+        });
+    return expect.objectContaining({
+        cycleCount,
+        toolMetrics: toolNames.length > 0 ? expect.objectContaining(expectedToolMetrics) : {},
+        accumulatedUsage: expectedUsage,
+        accumulatedMetrics: { latencyMs: expect.any(Number) },
+    });
+}
+/**
+ * Finds the latest data point value for a named metric from OTEL ResourceMetrics.
+ *
+ * Flattens the ResourceMetrics → ScopeMetrics → MetricData hierarchy and
+ * returns the value of the last data point for the matching metric name.
+ * For counters this is a number; for histograms it is an object with
+ * sum, count, min, max, etc.
+ *
+ * @param resourceMetrics - Array of ResourceMetrics from an InMemoryMetricExporter
+ * @param metricName - The metric descriptor name to search for
+ * @returns The value of the last data point, or undefined if not found
+ */
+export function findMetricValue(resourceMetrics, metricName) {
+    const dp = resourceMetrics
+        .flatMap((rm) => rm.scopeMetrics)
+        .flatMap((sm) => sm.metrics)
+        .filter((m) => m.descriptor.name === metricName)
+        .flatMap((m) => m.dataPoints)
+        .at(-1);
+    return dp?.value;
+}
+//# sourceMappingURL=metrics-helpers.js.map

package/dist/src/__fixtures__/metrics-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-helpers.js","sourceRoot":"","sources":["../../../src/__fixtures__/metrics-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAuBpD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,EAAE,UAAU,EAAE,SAAS,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAErD,MAAM,mBAAmB,GAA4B,EAAE,CAAA;IACvD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,mBAAmB,CAAC,IAAI,CAAC,GAAG;YAC1B,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC7B,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAChC,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC9B,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;SAC9B,CAAA;IACH,CAAC;IAED,MAAM,aAAa,GACjB,KAAK;QACL,MAAM,CAAC,gBAAgB,CAAC;YACtB,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC/B,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAChC,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;SAChC,CAAC,CAAA;IAEJ,OAAO,MAAM,CAAC,gBAAgB,CAAC;QAC7B,UAAU;QACV,WAAW,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE;QACrF,gBAAgB,EAAE,aAAa;QAC/B,kBAAkB,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;KACtD,CAAiB,CAAA;AACpB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,eAEG,EACH,UAAkB;IAElB,MAAM,EAAE,GAAG,eAAe;SACvB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC;SAChC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC;SAC/C,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;SAC5B,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACT,OAAO,EAAE,EAAE,KAAK,CAAA;AAClB,CAAC"}

package/dist/src/__fixtures__/mock-message-model.d.ts

@@ -6,7 +6,7 @@
  */
 import { Model } from '../models/model.js';
 import type { Message, StopReason } from '../types/messages.js';
-import type { ModelStreamEvent } from '../models/streaming.js';
+import type { ModelStreamEvent, Usage } from '../models/streaming.js';
 import type { BaseModelConfig, StreamOptions } from '../models/model.js';
 import type { PlainContentBlock } from './slim-types.js';
 /**
@@ -35,7 +35,7 @@ export declare class MockMessageModel extends Model<BaseModelConfig> {
      * Returns this for method chaining.
      *
      * @param turn - ContentBlock, ContentBlock[], or Error to add
-     * @param stopReason - Optional explicit stopReason (overrides auto-derivation)
+     * @param options - Optional stop reason and token usage
      * @returns This provider for chaining
      *
      * @example
@@ -43,11 +43,15 @@ export declare class MockMessageModel extends Model<BaseModelConfig> {
      * provider
      *   .addTurn({ type: 'textBlock', text: 'Hello' })  // Single block
      *   .addTurn([{ type: 'toolUseBlock', ... }])  // Array of blocks
-     *   .addTurn({ type: 'textBlock', text: 'Done' }, 'maxTokens')  // Explicit stopReason
+     *   .addTurn({ type: 'textBlock', text: 'Done' }, { stopReason: 'maxTokens' })  // Explicit stopReason
+     *   .addTurn({ type: 'textBlock', text: 'Hi' }, { usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } })
      *   .addTurn(new Error('Failed'))  // Error turn
      * ```
      */
-    addTurn(turn: ContentBlockInput, stopReason?: StopReason): this;
+    addTurn(turn: ContentBlockInput, options?: {
+        stopReason?: StopReason;
+        usage?: Usage;
+    }): this;
     /**
      * Updates the model configuration.
      *

package/dist/src/__fixtures__/mock-message-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-message-model.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/mock-message-model.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;GAEG;AACH,KAAK,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,KAAK,CAAA;AAQxE;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK,CAAC,eAAe,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,OAAO,CAAiB;IAEhC;;OAEG;;IAQH;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAK/D;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,eAAe,GAAG,IAAI;IAIhD;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;;;;;;;OAUG;IACI,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC,gBAAgB,CAAC;IA4B/F;;;OAGG;YACY,yBAAyB;IAiBxC;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;OAEG;YACY,yBAAyB;IAcxC;;OAEG;YACY,uBAAuB;CAiFvC"}
+{"version":3,"file":"mock-message-model.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/mock-message-model.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;GAEG;AACH,KAAK,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,KAAK,CAAA;AAUxE;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK,CAAC,eAAe,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,OAAO,CAAiB;IAEhC;;OAEG;;IAQH;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI;IAK5F;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,eAAe,GAAG,IAAI;IAIhD;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;;;;;;;OAUG;IACI,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC,gBAAgB,CAAC;IA4B/F;;;OAGG;YACY,yBAAyB;IAuBxC;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;OAEG;YACY,yBAAyB;IAcxC;;OAEG;YACY,uBAAuB;CA8FvC"}

package/dist/src/__fixtures__/mock-message-model.js

@@ -34,7 +34,7 @@ export class MockMessageModel extends Model {
      * Returns this for method chaining.
      *
      * @param turn - ContentBlock, ContentBlock[], or Error to add
-     * @param stopReason - Optional explicit stopReason (overrides auto-derivation)
+     * @param options - Optional stop reason and token usage
      * @returns This provider for chaining
      *
      * @example
@@ -42,12 +42,13 @@ export class MockMessageModel extends Model {
      * provider
      *   .addTurn({ type: 'textBlock', text: 'Hello' })  // Single block
      *   .addTurn([{ type: 'toolUseBlock', ... }])  // Array of blocks
-     *   .addTurn({ type: 'textBlock', text: 'Done' }, 'maxTokens')  // Explicit stopReason
+     *   .addTurn({ type: 'textBlock', text: 'Done' }, { stopReason: 'maxTokens' })  // Explicit stopReason
+     *   .addTurn({ type: 'textBlock', text: 'Hi' }, { usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } })
      *   .addTurn(new Error('Failed'))  // Error turn
      * ```
      */
-    addTurn(turn, stopReason) {
-        this._turns.push(this._createTurn(turn, stopReason));
+    addTurn(turn, options) {
+        this._turns.push(this._createTurn(turn, options?.stopReason, options?.usage));
         return this;
     }
     /**
@@ -97,13 +98,13 @@ export class MockMessageModel extends Model {
             throw turn.error;
         }
         // Generate events for content turn
-        yield* this._generateEventsForContent(turn.content, turn.stopReason);
+        yield* this._generateEventsForContent(turn.content, turn.stopReason, turn.usage);
     }
     /**
      * Generates appropriate ModelStreamEvents for content blocks.
      * All messages have role 'assistant' since this is for testing model responses.
      */
-    async *_generateEventsForContent(content, stopReason) {
+    async *_generateEventsForContent(content, stopReason, usage) {
         // Yield message start event (always assistant role)
         yield { type: 'modelMessageStartEvent', role: 'assistant' };
         // Yield events for each content block
@@ -113,11 +114,15 @@ export class MockMessageModel extends Model {
         }
         // Yield message stop event
         yield { type: 'modelMessageStopEvent', stopReason };
+        // Yield metadata event with token usage when provided
+        if (usage) {
+            yield { type: 'modelMetadataEvent', usage };
+        }
     }
     /**
      * Creates a Turn object from ContentBlock(s) or Error.
      */
-    _createTurn(turn, explicitStopReason) {
+    _createTurn(turn, explicitStopReason, usage) {
         if (turn instanceof Error) {
             return { type: 'error', error: turn };
         }
@@ -127,6 +132,7 @@ export class MockMessageModel extends Model {
             type: 'content',
             content,
             stopReason: explicitStopReason ?? this._deriveStopReason(content),
+            ...(usage !== undefined && { usage }),
         };
     }
     /**
@@ -210,6 +216,18 @@ export class MockMessageModel extends Model {
                 // GuardContentBlock is handled by guardrails and doesn't generate model events
                 // This is typically used in system prompts or message content for guardrail evaluation
                 break;
+            case 'citationsBlock':
+                yield { type: 'modelContentBlockStartEvent' };
+                yield {
+                    type: 'modelContentBlockDeltaEvent',
+                    delta: {
+                        type: 'citationsDelta',
+                        citations: block.citations,
+                        content: block.content,
+                    },
+                };
+                yield { type: 'modelContentBlockStopEvent' };
+                break;
             case 'imageBlock':
             case 'videoBlock':
             case 'documentBlock':

package/dist/src/__fixtures__/mock-message-model.js.map

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

package/dist/src/__fixtures__/mock-meter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mock OpenTelemetry Meter for testing metric instrument emission.
+ * Records all counter and histogram data points for assertion.
+ */
+import type { Attributes } from '@opentelemetry/api';
+export interface MockDataPoint {
+    value: number;
+    attributes: Attributes | undefined;
+}
+export declare class MockCounter {
+    readonly dataPoints: MockDataPoint[];
+    add(value: number, attributes?: Attributes): void;
+    get sum(): number;
+}
+export declare class MockHistogram {
+    readonly dataPoints: MockDataPoint[];
+    record(value: number, attributes?: Attributes): void;
+    get sum(): number;
+}
+/**
+ * Mock OTEL Meter that tracks created instruments by name.
+ * Cast to `Meter` when passing to `vi.spyOn(otelMetrics, 'getMeter')`.
+ */
+export declare class MockMeter {
+    private readonly _counters;
+    private readonly _histograms;
+    createCounter(name: string): MockCounter;
+    createHistogram(name: string): MockHistogram;
+    getCounter(name: string): MockCounter | undefined;
+    getHistogram(name: string): MockHistogram | undefined;
+}
+//# sourceMappingURL=mock-meter.d.ts.map

package/dist/src/__fixtures__/mock-meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-meter.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/mock-meter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,UAAU,GAAG,SAAS,CAAA;CACnC;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,CAAK;IAEzC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,IAAI,GAAG,IAAI,MAAM,CAEhB;CACF;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,CAAK;IAEzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAIpD,IAAI,GAAG,IAAI,MAAM,CAEhB;CACF;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAE/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAMxC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAM5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIjD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGtD"}

package/dist/src/__fixtures__/mock-meter.js

@@ -0,0 +1,47 @@
+/**
+ * Mock OpenTelemetry Meter for testing metric instrument emission.
+ * Records all counter and histogram data points for assertion.
+ */
+export class MockCounter {
+    dataPoints = [];
+    add(value, attributes) {
+        this.dataPoints.push({ value, attributes });
+    }
+    get sum() {
+        return this.dataPoints.reduce((acc, dp) => acc + dp.value, 0);
+    }
+}
+export class MockHistogram {
+    dataPoints = [];
+    record(value, attributes) {
+        this.dataPoints.push({ value, attributes });
+    }
+    get sum() {
+        return this.dataPoints.reduce((acc, dp) => acc + dp.value, 0);
+    }
+}
+/**
+ * Mock OTEL Meter that tracks created instruments by name.
+ * Cast to `Meter` when passing to `vi.spyOn(otelMetrics, 'getMeter')`.
+ */
+export class MockMeter {
+    _counters = new Map();
+    _histograms = new Map();
+    createCounter(name) {
+        const counter = new MockCounter();
+        this._counters.set(name, counter);
+        return counter;
+    }
+    createHistogram(name) {
+        const histogram = new MockHistogram();
+        this._histograms.set(name, histogram);
+        return histogram;
+    }
+    getCounter(name) {
+        return this._counters.get(name);
+    }
+    getHistogram(name) {
+        return this._histograms.get(name);
+    }
+}
+//# sourceMappingURL=mock-meter.js.map

package/dist/src/__fixtures__/mock-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-meter.js","sourceRoot":"","sources":["../../../src/__fixtures__/mock-meter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,MAAM,OAAO,WAAW;IACb,UAAU,GAAoB,EAAE,CAAA;IAEzC,GAAG,CAAC,KAAa,EAAE,UAAuB;QACxC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAA;IAC7C,CAAC;IAED,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAC/D,CAAC;CACF;AAED,MAAM,OAAO,aAAa;IACf,UAAU,GAAoB,EAAE,CAAA;IAEzC,MAAM,CAAC,KAAa,EAAE,UAAuB;QAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAA;IAC7C,CAAC;IAED,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAC/D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,SAAS;IACH,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC1C,WAAW,GAAG,IAAI,GAAG,EAAyB,CAAA;IAE/D,aAAa,CAAC,IAAY;QACxB,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACjC,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,eAAe,CAAC,IAAY;QAC1B,MAAM,SAAS,GAAG,IAAI,aAAa,EAAE,CAAA;QACrC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;QACrC,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACnC,CAAC;CACF"}

package/dist/src/__fixtures__/mock-plugin.d.ts

@@ -0,0 +1,13 @@
+import type { HookableEvent } from '../hooks/index.js';
+import type { Plugin } from '../plugins/plugin.js';
+import type { LocalAgent } from '../types/agent.js';
+/**
+ * Mock plugin that records all hookable event invocations for testing.
+ */
+export declare class MockPlugin implements Plugin {
+    invocations: HookableEvent[];
+    get name(): string;
+    initAgent(agent: LocalAgent): void;
+    reset(): void;
+}
+//# sourceMappingURL=mock-plugin.d.ts.map

package/dist/src/__fixtures__/mock-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-plugin.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/mock-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAanD;;GAEG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,WAAW,EAAE,aAAa,EAAE,CAAK;IAEjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAmBlC,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/__fixtures__/{mock-hook-provider.js → mock-plugin.js}

@@ -1,10 +1,13 @@
 import { InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, MessageAddedEvent, BeforeToolCallEvent, AfterToolCallEvent, BeforeModelCallEvent, AfterModelCallEvent, } from '../hooks/index.js';
 /**
- * Mock hook provider that records all hookable event invocations for testing.
+ * Mock plugin that records all hookable event invocations for testing.
  */
-export class MockHookProvider {
+export class MockPlugin {
     invocations = [];
-    registerCallbacks(registry) {
+    get name() {
+        return 'mock-plugin';
+    }
+    initAgent(agent) {
         const eventTypes = [
             InitializedEvent,
             BeforeInvocationEvent,
@@ -16,7 +19,7 @@ export class MockHookProvider {
             AfterModelCallEvent,
         ];
         for (const eventType of eventTypes) {
-            registry.addCallback(eventType, (e) => {
+            agent.addHook(eventType, (e) => {
                 this.invocations.push(e);
             });
         }
@@ -25,4 +28,4 @@ export class MockHookProvider {
         this.invocations = [];
     }
 }
-//# sourceMappingURL=mock-hook-provider.js.map
+//# sourceMappingURL=mock-plugin.js.map

package/dist/src/__fixtures__/mock-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-plugin.js","sourceRoot":"","sources":["../../../src/__fixtures__/mock-plugin.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAG1B;;GAEG;AACH,MAAM,OAAO,UAAU;IACrB,WAAW,GAAoB,EAAE,CAAA;IAEjC,IAAI,IAAI;QACN,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,SAAS,CAAC,KAAiB;QACzB,MAAM,UAAU,GAA+B;YAC7C,gBAAgB;YAChB,qBAAqB;YACrB,oBAAoB;YACpB,iBAAiB;YACjB,mBAAmB;YACnB,kBAAkB;YAClB,oBAAoB;YACpB,mBAAmB;SACpB,CAAA;QAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;gBAC7B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1B,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,WAAW,GAAG,EAAE,CAAA;IACvB,CAAC;CACF"}