@strands-agents/sdk 0.3.0 → 0.5.0

package/dist/src/__fixtures__/slim-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slim-types.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/slim-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,SAAS,EACV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AAEzC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,CAAC,SAAS,CAAC,GACjB,MAAM,CAAC,YAAY,CAAC,GACpB,MAAM,CAAC,eAAe,CAAC,GACvB,MAAM,CAAC,cAAc,CAAC,GACtB,MAAM,CAAC,eAAe,CAAC,GACvB,MAAM,CAAC,iBAAiB,CAAC,GACzB,MAAM,CAAC,SAAS,CAAC,GACjB,MAAM,CAAC,UAAU,CAAC,GAClB,MAAM,CAAC,UAAU,CAAC,GAClB,MAAM,CAAC,aAAa,CAAC,CAAA;AAEzB;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAA;AAE7G;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,eAAe,CAAC,CAAA;AAE1D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAAA;AAE7E;;;;;;;;;;GAUG;AACH,YAAY,EAAE,OAAO,EAAE,CAAA"}

package/dist/src/__fixtures__/slim-types.js

@@ -0,0 +1,6 @@
+/**
+ * Utility types for testing that strip methods from classes.
+ * Allows tests to use plain objects without needing to construct class instances.
+ */
+export {};
+//# sourceMappingURL=slim-types.js.map

package/dist/src/__fixtures__/slim-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slim-types.js","sourceRoot":"","sources":["../../../src/__fixtures__/slim-types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -3,28 +3,32 @@
  * This module provides utilities for testing Tool implementations.
  */
 import type { Tool, ToolContext } from '../tools/tool.js';
-import { ToolResultBlock } from '../types/messages.js';
 import type { JSONValue } from '../types/json.js';
+import type { PlainToolResultBlock } from './slim-types.js';
 /**
  * Helper to create a mock ToolContext for testing.
  *
  * @param toolUse - The tool use request
- * @param agentState - Optional initial agent state
+ * @param appState - Optional initial app state
  * @returns Mock ToolContext object
  */
 export declare function createMockContext(toolUse: {
     name: string;
     toolUseId: string;
     input: JSONValue;
-}, agentState?: Record<string, JSONValue>): ToolContext;
+}, appState?: Record<string, JSONValue>): ToolContext;
+/**
+ * Result function type for createMockTool - accepts plain objects or class instances.
+ */
+type ToolResultFn = () => PlainToolResultBlock | AsyncGenerator<never, PlainToolResultBlock, never>;
 /**
  * Helper to create a mock tool for testing.
  *
  * @param name - The name of the mock tool
- * @param resultFn - Function that returns a ToolResultBlock or an AsyncGenerator that yields nothing and returns a ToolResultBlock
+ * @param resultFn - Function that returns a ToolResultBlock (plain object or class instance) or an AsyncGenerator
  * @returns Mock Tool object
  */
-export declare function createMockTool(name: string, resultFn: () => ToolResultBlock | AsyncGenerator<never, ToolResultBlock, never>): Tool;
+export declare function createMockTool(name: string, resultFn: ToolResultFn): Tool;
 /**
  * Helper to create a simple mock tool with minimal configuration for testing.
  * This is a lighter-weight version of createMockTool for scenarios where the tool's
@@ -34,4 +38,5 @@ export declare function createMockTool(name: string, resultFn: () => ToolResultB
  * @returns Mock Tool object
  */
 export declare function createRandomTool(name?: string): Tool;
+export {};
 //# sourceMappingURL=tool-helpers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAGjD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,EAC9D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GACrC,WAAW,CAQb;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,CAAC,GAC9E,IAAI,CA8BN;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAWpD"}
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,EAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAQb;AAED;;GAEG;AACH,KAAK,YAAY,GAAG,MAAM,oBAAoB,GAAG,cAAc,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,CAAC,CAAA;AAEnG;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CA8BzE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAWpD"}

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

@@ -3,19 +3,19 @@
  * This module provides utilities for testing Tool implementations.
  */
 import { ToolResultBlock } from '../types/messages.js';
-import { AgentState } from '../agent/state.js';
+import { AppState } from '../app-state.js';
 /**
  * Helper to create a mock ToolContext for testing.
  *
  * @param toolUse - The tool use request
- * @param agentState - Optional initial agent state
+ * @param appState - Optional initial app state
  * @returns Mock ToolContext object
  */
-export function createMockContext(toolUse, agentState) {
+export function createMockContext(toolUse, appState) {
     return {
         toolUse,
         agent: {
-            state: new AgentState(agentState),
+            state: new AppState(appState),
             messages: [],
         },
     };
@@ -24,7 +24,7 @@ export function createMockContext(toolUse, agentState) {
  * Helper to create a mock tool for testing.
  *
  * @param name - The name of the mock tool
- * @param resultFn - Function that returns a ToolResultBlock or an AsyncGenerator that yields nothing and returns a ToolResultBlock
+ * @param resultFn - Function that returns a ToolResultBlock (plain object or class instance) or an AsyncGenerator
  * @returns Mock Tool object
  */
 export function createMockTool(name, resultFn) {

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

@@ -1 +1 @@
-{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../../src/__fixtures__/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA8D,EAC9D,UAAsC;IAEtC,OAAO;QACL,OAAO;QACP,KAAK,EAAE;YACL,KAAK,EAAE,IAAI,UAAU,CAAC,UAAU,CAAC;YACjC,QAAQ,EAAE,EAAE;SACb;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,QAA+E;IAE/E,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,aAAa,IAAI,EAAE;QAChC,QAAQ,EAAE;YACR,IAAI;YACJ,WAAW,EAAE,aAAa,IAAI,EAAE;YAChC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SAChD;QACD,yCAAyC;QACzC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ;YACpB,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAA;YACzB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,EAAE,CAAC;gBACpF,mCAAmC;gBACnC,MAAM,GAAG,GAAG,MAAuD,CAAA;gBACnE,IAAI,IAAI,GAAG,KAAK,CAAA;gBAChB,OAAO,CAAC,IAAI,EAAE,CAAC;oBACb,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;oBAChD,IAAI,GAAG,MAAM,IAAI,KAAK,CAAA;oBACtB,IAAI,IAAI,EAAE,CAAC;wBACT,OAAO,KAAK,CAAA;oBACd,CAAC;gBACH,CAAC;gBACD,6DAA6D;gBAC7D,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;YACjD,CAAC;iBAAM,CAAC;gBACN,OAAO,MAAyB,CAAA;YAClC,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,QAAQ,GAAG,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;IACvD,OAAO,cAAc,CACnB,QAAQ,EACR,GAAG,EAAE,CACH,IAAI,eAAe,CAAC;QAClB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAkB;QAC1B,OAAO,EAAE,EAAE;KACZ,CAAC,CACL,CAAA;AACH,CAAC"}
+{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../../src/__fixtures__/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAG1C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA8D,EAC9D,QAAoC;IAEpC,OAAO;QACL,OAAO;QACP,KAAK,EAAE;YACL,KAAK,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC;YAC7B,QAAQ,EAAE,EAAE;SACb;KACF,CAAA;AACH,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAAsB;IACjE,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,aAAa,IAAI,EAAE;QAChC,QAAQ,EAAE;YACR,IAAI;YACJ,WAAW,EAAE,aAAa,IAAI,EAAE;YAChC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SAChD;QACD,yCAAyC;QACzC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ;YACpB,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAA;YACzB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,EAAE,CAAC;gBACpF,mCAAmC;gBACnC,MAAM,GAAG,GAAG,MAAuD,CAAA;gBACnE,IAAI,IAAI,GAAG,KAAK,CAAA;gBAChB,OAAO,CAAC,IAAI,EAAE,CAAC;oBACb,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;oBAChD,IAAI,GAAG,MAAM,IAAI,KAAK,CAAA;oBACtB,IAAI,IAAI,EAAE,CAAC;wBACT,OAAO,KAAK,CAAA;oBACd,CAAC;gBACH,CAAC;gBACD,6DAA6D;gBAC7D,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;YACjD,CAAC;iBAAM,CAAC;gBACN,OAAO,MAAyB,CAAA;YAClC,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,QAAQ,GAAG,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;IACvD,OAAO,cAAc,CACnB,QAAQ,EACR,GAAG,EAAE,CACH,IAAI,eAAe,CAAC;QAClB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAkB;QAC1B,OAAO,EAAE,EAAE;KACZ,CAAC,CACL,CAAA;AACH,CAAC"}

package/dist/src/__tests__/app-state.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-state.test.d.ts.map

package/dist/src/__tests__/app-state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-state.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/app-state.test.ts"],"names":[],"mappings":""}

package/dist/src/{agent/__tests__/state.test.js → __tests__/app-state.test.js}

@@ -1,19 +1,19 @@
 import { describe, expect, it } from 'vitest';
-import { AgentState } from '../state.js';
-describe('AgentState', () => {
+import { AppState } from '../app-state.js';
+describe('AppState', () => {
     describe('constructor', () => {
         it('creates empty state when no initial state provided', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(state.keys()).toEqual([]);
         });
         it('creates state with initial values', () => {
-            const state = new AgentState({ key1: 'value1', key2: 42 });
+            const state = new AppState({ key1: 'value1', key2: 42 });
             expect(state.get('key1')).toBe('value1');
             expect(state.get('key2')).toBe(42);
         });
         it('stores deep copy of initial state', () => {
             const initial = { nested: { value: 'test' } };
-            const state = new AgentState(initial);
+            const state = new AppState(initial);
             // Mutate original
             initial.nested.value = 'changed';
             // State should not be affected
@@ -21,42 +21,42 @@ describe('AgentState', () => {
         });
         it('throws error for function in initial state', () => {
             const invalidState = { func: () => 'test', value: 'keep' };
-            expect(() => new AgentState(invalidState)).toThrow('initialState.func contains a function which cannot be serialized');
+            expect(() => new AppState(invalidState)).toThrow('initialState.func contains a function which cannot be serialized');
         });
         it('throws error for symbol in initial state', () => {
             const sym = Symbol('test');
             const invalidState = { sym, value: 'keep' };
-            expect(() => new AgentState(invalidState)).toThrow('initialState.sym contains a symbol which cannot be serialized');
+            expect(() => new AppState(invalidState)).toThrow('initialState.sym contains a symbol which cannot be serialized');
         });
         it('throws error for undefined in initial state', () => {
             const invalidState = { undef: undefined, value: 'keep' };
-            expect(() => new AgentState(invalidState)).toThrow('initialState.undef is undefined which cannot be serialized');
+            expect(() => new AppState(invalidState)).toThrow('initialState.undef is undefined which cannot be serialized');
         });
         it('throws error for nested function in initial state', () => {
             const invalidState = { nested: { func: () => 'test' } };
-            expect(() => new AgentState(invalidState)).toThrow('initialState.nested.func contains a function which cannot be serialized');
+            expect(() => new AppState(invalidState)).toThrow('initialState.nested.func contains a function which cannot be serialized');
         });
         it('throws error for function in array in initial state', () => {
             const invalidState = { arr: [1, () => 'test', 3] };
-            expect(() => new AgentState(invalidState)).toThrow('initialState.arr[1] contains a function which cannot be serialized');
+            expect(() => new AppState(invalidState)).toThrow('initialState.arr[1] contains a function which cannot be serialized');
         });
     });
     describe('get', () => {
         it('throws error when key is null or undefined', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(() => state.get(null)).toThrow('key is required');
             expect(() => state.get(undefined)).toThrow('key is required');
         });
         it('returns undefined when key does not exist', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(state.get('nonexistent')).toBeUndefined();
         });
         it('returns value when key exists', () => {
-            const state = new AgentState({ key1: 'value1' });
+            const state = new AppState({ key1: 'value1' });
             expect(state.get('key1')).toBe('value1');
         });
         it('returns deep copy that cannot mutate stored state', () => {
-            const state = new AgentState({ nested: { value: 'test' } });
+            const state = new AppState({ nested: { value: 'test' } });
             const retrieved = state.get('nested');
             // Mutate retrieved value
             retrieved.value = 'changed';
@@ -64,7 +64,7 @@ describe('AgentState', () => {
             expect(state.get('nested')).toEqual({ value: 'test' });
         });
         it('infers correct type with generic state interface', () => {
-            const state = new AgentState({ user: { name: 'John', age: 30 }, count: 5, items: ['a', 'b'] });
+            const state = new AppState({ user: { name: 'John', age: 30 }, count: 5, items: ['a', 'b'] });
             // Type inference tests
             const user = state.get('user');
             const count = state.get('count');
@@ -74,11 +74,11 @@ describe('AgentState', () => {
             expect(items).toEqual(['a', 'b']);
         });
         it('returns undefined for non-existent key with typed interface', () => {
-            const state = new AgentState({ existing: 'value' });
+            const state = new AppState({ existing: 'value' });
             const result = state.get('existing');
             expect(result).toBe('value');
             // Non-existent key
-            const state2 = new AgentState();
+            const state2 = new AppState();
             const missing = state2.get('existing');
             expect(missing).toBeUndefined();
             // @ts-expect-error properties not on the TestsState are an error
@@ -87,42 +87,42 @@ describe('AgentState', () => {
     });
     describe('set', () => {
         it('sets string value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', 'value1');
             expect(state.get('key1')).toBe('value1');
         });
         it('sets number value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', 42);
             expect(state.get('key1')).toBe(42);
         });
         it('sets boolean value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', true);
             expect(state.get('key1')).toBe(true);
         });
         it('sets null value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', null);
             expect(state.get('key1')).toBeNull();
         });
         it('sets object value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', { nested: 'value' });
             expect(state.get('key1')).toEqual({ nested: 'value' });
         });
         it('sets array value successfully', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('key1', [1, 2, 3]);
             expect(state.get('key1')).toEqual([1, 2, 3]);
         });
         it('overwrites existing value', () => {
-            const state = new AgentState({ key1: 'old' });
+            const state = new AppState({ key1: 'old' });
             state.set('key1', 'new');
             expect(state.get('key1')).toBe('new');
         });
         it('stores deep copy that cannot mutate stored state', () => {
-            const state = new AgentState();
+            const state = new AppState();
             const value = { nested: { value: 'test' } };
             state.set('key1', value);
             // Mutate original
@@ -131,35 +131,35 @@ describe('AgentState', () => {
             expect(state.get('key1')).toEqual({ nested: { value: 'test' } });
         });
         it('throws error for function in value', () => {
-            const state = new AgentState({ existing: 'value' });
+            const state = new AppState({ existing: 'value' });
             const obj = { func: () => 'test', value: 'keep' };
             expect(() => state.set('key1', obj)).toThrow('value for key "key1".func contains a function which cannot be serialized');
         });
         it('throws error for symbol in value', () => {
-            const state = new AgentState();
+            const state = new AppState();
             const sym = Symbol('test');
             expect(() => state.set('key1', { sym })).toThrow('value for key "key1".sym contains a symbol which cannot be serialized');
         });
         it('throws error for nested function in value', () => {
-            const state = new AgentState();
+            const state = new AppState();
             const obj = { nested: { func: () => 'test' } };
             expect(() => state.set('key1', obj)).toThrow('value for key "key1".nested.func contains a function which cannot be serialized');
         });
         it('throws error for function in array', () => {
-            const state = new AgentState();
+            const state = new AppState();
             const arr = [1, () => 'test', 3];
             expect(() => state.set('key1', arr)).toThrow('value for key "key1"[1] contains a function which cannot be serialized');
         });
         it('throws error for top-level symbol values', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(() => state.set('key1', Symbol('test'))).toThrow('value for key "key1" contains a symbol which cannot be serialized');
         });
         it('throws error for top-level undefined values', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(() => state.set('key1', undefined)).toThrow('value for key "key1" is undefined which cannot be serialized');
         });
         it('accepts typed value with generic state interface', () => {
-            const state = new AgentState();
+            const state = new AppState();
             state.set('user', { name: 'Alice', age: 25 });
             state.set('count', 10);
             expect(state.get('user')).toEqual({ name: 'Alice', age: 25 });
@@ -170,17 +170,17 @@ describe('AgentState', () => {
     });
     describe('delete', () => {
         it('removes existing key', () => {
-            const state = new AgentState({ key1: 'value1', key2: 'value2' });
+            const state = new AppState({ key1: 'value1', key2: 'value2' });
             state.delete('key1');
             expect(state.get('key1')).toBeUndefined();
             expect(state.get('key2')).toBe('value2');
         });
         it('does not throw error for non-existent key', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(() => state.delete('nonexistent')).not.toThrow();
         });
         it('supports typed usage with generic state interface', () => {
-            const state = new AgentState({ user: { name: 'Alice' }, count: 5 });
+            const state = new AppState({ user: { name: 'Alice' }, count: 5 });
             // Typed delete
             state.delete('user');
             expect(state.get('user')).toBeUndefined();
@@ -189,43 +189,62 @@ describe('AgentState', () => {
     });
     describe('clear', () => {
         it('removes all values', () => {
-            const state = new AgentState({ key1: 'value1', key2: 'value2' });
+            const state = new AppState({ key1: 'value1', key2: 'value2' });
             state.clear();
             expect(state.keys()).toEqual([]);
             expect(state.get('key1')).toBeUndefined();
             expect(state.get('key2')).toBeUndefined();
         });
         it('works on empty state', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(() => state.clear()).not.toThrow();
             expect(state.keys()).toEqual([]);
         });
     });
     describe('getAll', () => {
         it('returns object with all state', () => {
-            const state = new AgentState({ key1: 'value1', key2: 42 });
+            const state = new AppState({ key1: 'value1', key2: 42 });
             expect(state.getAll()).toEqual({ key1: 'value1', key2: 42 });
         });
         it('returns empty object for empty state', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(state.getAll()).toEqual({});
         });
     });
     describe('keys', () => {
         it('returns array of all keys', () => {
-            const state = new AgentState({ key1: 'value1', key2: 'value2' });
+            const state = new AppState({ key1: 'value1', key2: 'value2' });
             expect(state.keys().sort()).toEqual(['key1', 'key2']);
         });
         it('returns empty array for empty state', () => {
-            const state = new AgentState();
+            const state = new AppState();
             expect(state.keys()).toEqual([]);
         });
         it('returns new array each time', () => {
-            const state = new AgentState({ key1: 'value1' });
+            const state = new AppState({ key1: 'value1' });
             const keys1 = state.keys();
             const keys2 = state.keys();
             expect(keys1).not.toBe(keys2);
         });
     });
+    describe('toJSON', () => {
+        it('returns deep copy of state', () => {
+            const state = new AppState({ key1: 'value1', nested: { deep: true } });
+            const json = state.toJSON();
+            expect(json).toEqual({ key1: 'value1', nested: { deep: true } });
+        });
+    });
+    describe('loadStateFromJson', () => {
+        it('replaces state with json data', () => {
+            const state = new AppState({ old: 'data' });
+            state.loadStateFromJson({ new: 'data', count: 42 });
+            expect(state.getAll()).toEqual({ new: 'data', count: 42 });
+        });
+        it('clears state when given non-object', () => {
+            const state = new AppState({ key: 'value' });
+            state.loadStateFromJson(null);
+            expect(state.getAll()).toEqual({});
+        });
+    });
 });
-//# sourceMappingURL=state.test.js.map
+//# sourceMappingURL=app-state.test.js.map

package/dist/src/__tests__/app-state.test.js.map

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

package/dist/src/__tests__/mcp.test.js

@@ -1,8 +1,9 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { McpClient } from '../mcp.js';
 import { McpTool } from '../tools/mcp-tool.js';
 import { JsonBlock } from '../types/messages.js';
+import { context, propagation, trace, TraceFlags } from '@opentelemetry/api';
 /**
  * Helper to create a mock async generator that yields a result message.
  * This simulates the behavior of callToolStream returning a stream that ends with a result.
@@ -27,10 +28,8 @@ vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
     }),
 }));
 vi.mock('../tools/tool.js', () => ({
-    // Mock the abstract base class
     Tool: class {
     },
-    // Mock helper to return a valid ToolResultBlock structure without prepending "Error: "
     createErrorResult: (err, toolUseId) => ({
         type: 'toolResultBlock',
         status: 'error',
@@ -38,20 +37,36 @@ vi.mock('../tools/tool.js', () => ({
         content: [{ type: 'textBlock', text: err instanceof Error ? err.message : String(err) }],
     }),
 }));
-vi.mock('../../__fixtures__/environment.js', () => ({ isNode: true }));
 /**
  * Executes a tool stream to completion and returns the final result.
- * We use a Generic <T> and cast the return value to ensure TypeScript
- * knows the result is defined (and matches the Tool's return type).
  */
 async function runTool(gen) {
     let result = await gen.next();
     while (!result.done) {
         result = await gen.next();
     }
-    // Force cast because we know our McpTool always returns a value when done
     return result.value;
 }
+/**
+ * Mock an active span with a valid trace ID via trace.getSpan,
+ * and stub propagation.inject to populate the carrier with a traceparent.
+ */
+function mockActiveSpan(traceId = '1234567890abcdef1234567890abcdef', traceFlags = TraceFlags.SAMPLED) {
+    const mockSpan = {
+        spanContext: () => ({
+            traceId,
+            spanId: '1234567890abcdef',
+            traceFlags,
+        }),
+    };
+    vi.spyOn(trace, 'getSpan').mockReturnValue(mockSpan);
+    vi.spyOn(propagation, 'inject').mockImplementation((_context, carrier) => {
+        if (carrier && typeof carrier === 'object') {
+            ;
+            carrier.traceparent = `00-${traceId}-1234567890abcdef-01`;
+        }
+    });
+}
 const mockTransport = {
     connect: vi.fn(),
     close: vi.fn(),
@@ -61,6 +76,9 @@ describe('MCP Integration', () => {
     beforeEach(() => {
         vi.clearAllMocks();
     });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
     describe('McpClient', () => {
         let client;
         let sdkClientMock;
@@ -74,6 +92,70 @@ describe('MCP Integration', () => {
         it('initializes SDK client with correct configuration', () => {
             expect(Client).toHaveBeenCalledWith({ name: 'TestApp', version: '0.0.1' });
         });
+        it('injects trace context into tool arguments when active span exists', async () => {
+            mockActiveSpan();
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client });
+            sdkClientMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            await client.callTool(tool, { op: 'add' });
+            const callArgs = sdkClientMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({
+                op: 'add',
+                _meta: { traceparent: '00-1234567890abcdef1234567890abcdef-1234567890abcdef-01' },
+            });
+        });
+        it('merges trace context with existing _meta field', async () => {
+            mockActiveSpan();
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client });
+            sdkClientMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            await client.callTool(tool, { op: 'add', _meta: { progressToken: 'tok-1' } });
+            const callArgs = sdkClientMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({
+                op: 'add',
+                _meta: {
+                    progressToken: 'tok-1',
+                    traceparent: '00-1234567890abcdef1234567890abcdef-1234567890abcdef-01',
+                },
+            });
+        });
+        it('passes args unchanged when no active span exists', async () => {
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client });
+            sdkClientMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            await client.callTool(tool, { op: 'add' });
+            const callArgs = sdkClientMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({ op: 'add' });
+        });
+        it('passes args unchanged when span has empty trace ID', async () => {
+            mockActiveSpan('', TraceFlags.NONE);
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client });
+            sdkClientMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            await client.callTool(tool, { op: 'add' });
+            const callArgs = sdkClientMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({ op: 'add' });
+        });
+        it('passes args unchanged when context injection fails', async () => {
+            vi.spyOn(context, 'active').mockImplementation(() => {
+                throw new Error('Context error');
+            });
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client });
+            sdkClientMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            await client.callTool(tool, { op: 'add' });
+            const callArgs = sdkClientMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({ op: 'add' });
+        });
+        it('skips trace context injection when disableMcpInstrumentation is true', async () => {
+            mockActiveSpan();
+            const noInstrClient = new McpClient({
+                applicationName: 'TestApp',
+                transport: mockTransport,
+                disableMcpInstrumentation: true,
+            });
+            const noInstrSdkMock = vi.mocked(Client).mock.results.at(-1).value;
+            noInstrSdkMock.experimental.tasks.callToolStream.mockReturnValue(createMockCallToolStream({ content: [] })());
+            const tool = new McpTool({ name: 'calc', description: '', inputSchema: {}, client: noInstrClient });
+            await noInstrClient.callTool(tool, { op: 'add' });
+            const callArgs = noInstrSdkMock.experimental.tasks.callToolStream.mock.calls[0][0];
+            expect(callArgs.arguments).toStrictEqual({ op: 'add' });
+        });
         it('manages connection state lazily', async () => {
             await client.connect();
             expect(sdkClientMock.connect).toHaveBeenCalledTimes(1);
@@ -124,7 +206,7 @@ describe('MCP Integration', () => {
             inputSchema: {},
             client: mockClientWrapper,
         });
-        const context = {
+        const toolContext = {
             toolUse: { toolUseId: 'id-123', name: 'weather', input: { city: 'NYC' } },
             agent: {},
         };
@@ -132,8 +214,7 @@ describe('MCP Integration', () => {
             vi.mocked(mockClientWrapper.callTool).mockResolvedValue({
                 content: [{ type: 'text', text: 'Sunny' }],
             });
-            // runTool<ToolResultBlock> explicitly tells TS the return type
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             expect(result).toBeDefined();
             expect(result.status).toBe('success');
             expect(result.content[0].text).toBe('Sunny');
@@ -143,14 +224,14 @@ describe('MCP Integration', () => {
             vi.mocked(mockClientWrapper.callTool).mockResolvedValue({
                 content: [{ type: 'data', value: data }],
             });
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             const content = result.content[0];
             expect(content).toBeInstanceOf(JsonBlock);
             expect(content.json).toEqual(expect.objectContaining({ value: data }));
         });
         it('provides default message for empty output', async () => {
             vi.mocked(mockClientWrapper.callTool).mockResolvedValue({ content: [] });
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             expect(result.content[0].text).toContain('completed successfully');
         });
         it('handles protocol-level errors', async () => {
@@ -158,19 +239,19 @@ describe('MCP Integration', () => {
                 isError: true,
                 content: [{ type: 'text', text: 'Service Unavailable' }],
             });
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             expect(result.status).toBe('error');
             expect(result.content[0].text).toBe('Service Unavailable');
         });
         it('catches and wraps client exceptions', async () => {
             vi.mocked(mockClientWrapper.callTool).mockRejectedValue(new Error('Network Error'));
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             expect(result.status).toBe('error');
             expect(result.content[0].text).toBe('Network Error');
         });
         it('validates SDK response format', async () => {
             vi.mocked(mockClientWrapper.callTool).mockResolvedValue({ content: null });
-            const result = await runTool(tool.stream(context));
+            const result = await runTool(tool.stream(toolContext));
             expect(result.status).toBe('error');
             expect(result.content[0].text).toContain('missing content array');
         });