@strands-agents/sdk 1.0.0-rc.4 → 1.0.0

package/dist/src/hooks/__tests__/events.test.js

@@ -26,34 +26,50 @@ describe('InitializedEvent', () => {
 describe('BeforeInvocationEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
-        const event = new BeforeInvocationEvent({ agent });
+        const event = new BeforeInvocationEvent({ agent, invocationState: {} });
         expect(event).toEqual({
             type: 'beforeInvocationEvent',
             agent: agent,
+            cancel: false,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
     });
     it('returns false for _shouldReverseCallbacks', () => {
         const agent = new Agent();
-        const event = new BeforeInvocationEvent({ agent });
+        const event = new BeforeInvocationEvent({ agent, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(false);
     });
+    it('allows cancel to be set to true', () => {
+        const agent = new Agent();
+        const event = new BeforeInvocationEvent({ agent, invocationState: {} });
+        expect(event.cancel).toBe(false);
+        event.cancel = true;
+        expect(event.cancel).toBe(true);
+    });
+    it('allows cancel to be set to a string message', () => {
+        const agent = new Agent();
+        const event = new BeforeInvocationEvent({ agent, invocationState: {} });
+        event.cancel = 'unauthorized';
+        expect(event.cancel).toBe('unauthorized');
+    });
 });
 describe('AfterInvocationEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
-        const event = new AfterInvocationEvent({ agent });
+        const event = new AfterInvocationEvent({ agent, invocationState: {} });
         expect(event).toEqual({
             type: 'afterInvocationEvent',
             agent: agent,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
     });
     it('returns true for _shouldReverseCallbacks', () => {
         const agent = new Agent();
-        const event = new AfterInvocationEvent({ agent });
+        const event = new AfterInvocationEvent({ agent, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(true);
     });
 });
@@ -61,11 +77,12 @@ describe('MessageAddedEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [new TextBlock('Hello')] });
-        const event = new MessageAddedEvent({ agent, message });
+        const event = new MessageAddedEvent({ agent, message, invocationState: {} });
         expect(event).toEqual({
             type: 'messageAddedEvent',
             agent: agent,
             message: message,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -75,7 +92,7 @@ describe('MessageAddedEvent', () => {
     it('returns false for _shouldReverseCallbacks', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [] });
-        const event = new MessageAddedEvent({ agent, message });
+        const event = new MessageAddedEvent({ agent, message, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(false);
     });
 });
@@ -93,13 +110,14 @@ describe('BeforeToolCallEvent', () => {
             toolUseId: 'test-id',
             input: { arg: 'value' },
         };
-        const event = new BeforeToolCallEvent({ agent, toolUse, tool });
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool, invocationState: {} });
         expect(event).toEqual({
             type: 'beforeToolCallEvent',
             agent: agent,
             toolUse: toolUse,
             tool: tool,
             cancel: false,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -115,25 +133,26 @@ describe('BeforeToolCallEvent', () => {
             toolUseId: 'test-id',
             input: {},
         };
-        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined });
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
         expect(event).toEqual({
             type: 'beforeToolCallEvent',
             agent: agent,
             toolUse: toolUse,
             tool: undefined,
             cancel: false,
+            invocationState: {},
         });
     });
     it('returns false for _shouldReverseCallbacks', () => {
         const agent = new Agent();
         const toolUse = { name: 'test', toolUseId: 'id', input: {} };
-        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined });
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(false);
     });
     it('allows cancel to be set to true', () => {
         const agent = new Agent();
         const toolUse = { name: 'test', toolUseId: 'id', input: {} };
-        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined });
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
         expect(event.cancel).toBe(false);
         event.cancel = true;
         expect(event.cancel).toBe(true);
@@ -141,7 +160,7 @@ describe('BeforeToolCallEvent', () => {
     it('allows cancel to be set to a string message', () => {
         const agent = new Agent();
         const toolUse = { name: 'test', toolUseId: 'id', input: {} };
-        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined });
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
         event.cancel = 'tool not allowed';
         expect(event.cancel).toBe('tool not allowed');
     });
@@ -165,7 +184,7 @@ describe('AfterToolCallEvent', () => {
             status: 'success',
             content: [new TextBlock('Success')],
         });
-        const event = new AfterToolCallEvent({ agent, toolUse, tool, result });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool, result, invocationState: {} });
         expect(event).toEqual({
             type: 'afterToolCallEvent',
             agent: agent,
@@ -173,6 +192,7 @@ describe('AfterToolCallEvent', () => {
             tool: tool,
             result: result,
             error: undefined,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -180,8 +200,19 @@ describe('AfterToolCallEvent', () => {
         event.toolUse = toolUse;
         // @ts-expect-error verifying that property is readonly
         event.tool = tool;
-        // @ts-expect-error verifying that property is readonly
-        event.result = result;
+    });
+    it('allows result to be replaced', () => {
+        const agent = new Agent();
+        const toolUse = { name: 'test', toolUseId: 'id', input: {} };
+        const result = new ToolResultBlock({ toolUseId: 'id', status: 'success', content: [new TextBlock('original')] });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, invocationState: {} });
+        const replacedResult = new ToolResultBlock({
+            toolUseId: 'id',
+            status: 'success',
+            content: [new TextBlock('replaced')],
+        });
+        event.result = replacedResult;
+        expect(event.result).toBe(replacedResult);
     });
     it('creates instance with error property when tool execution fails', () => {
         const agent = new Agent();
@@ -192,7 +223,7 @@ describe('AfterToolCallEvent', () => {
             content: [new TextBlock('Error')],
         });
         const error = new Error('Tool failed');
-        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error, invocationState: {} });
         expect(event).toEqual({
             type: 'afterToolCallEvent',
             agent: agent,
@@ -200,6 +231,7 @@ describe('AfterToolCallEvent', () => {
             tool: undefined,
             result: result,
             error: error,
+            invocationState: {},
         });
     });
     it('returns true for _shouldReverseCallbacks', () => {
@@ -210,7 +242,7 @@ describe('AfterToolCallEvent', () => {
             status: 'success',
             content: [],
         });
-        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(true);
     });
     it('allows retry to be set when error is present', () => {
@@ -222,7 +254,7 @@ describe('AfterToolCallEvent', () => {
             content: [new TextBlock('Error')],
         });
         const error = new Error('Tool failed');
-        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error, invocationState: {} });
         expect(event.retry).toBeUndefined();
         event.retry = true;
         expect(event.retry).toBe(true);
@@ -237,7 +269,7 @@ describe('AfterToolCallEvent', () => {
             status: 'success',
             content: [new TextBlock('Success')],
         });
-        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result });
+        const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, invocationState: {} });
         expect(event.retry).toBeUndefined();
         event.retry = true;
         expect(event.retry).toBe(true);
@@ -246,20 +278,62 @@ describe('AfterToolCallEvent', () => {
 describe('BeforeModelCallEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
-        const event = new BeforeModelCallEvent({ agent, model: agent.model });
+        const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
         expect(event).toEqual({
             type: 'beforeModelCallEvent',
             agent: agent,
             model: agent.model,
+            cancel: false,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
     });
+    it('includes projectedInputTokens when provided', () => {
+        const agent = new Agent();
+        const event = new BeforeModelCallEvent({
+            agent,
+            model: agent.model,
+            invocationState: {},
+            projectedInputTokens: 500,
+        });
+        expect(event).toEqual({
+            type: 'beforeModelCallEvent',
+            agent,
+            model: agent.model,
+            cancel: false,
+            invocationState: {},
+            projectedInputTokens: 500,
+        });
+        expect(event.toJSON()).toStrictEqual({
+            type: 'beforeModelCallEvent',
+            projectedInputTokens: 500,
+        });
+    });
+    it('excludes projectedInputTokens from toJSON when not provided', () => {
+        const agent = new Agent();
+        const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
+        expect(event.projectedInputTokens).toBeUndefined();
+        expect(event.toJSON()).toStrictEqual({ type: 'beforeModelCallEvent' });
+    });
     it('returns false for _shouldReverseCallbacks', () => {
         const agent = new Agent();
-        const event = new BeforeModelCallEvent({ agent, model: agent.model });
+        const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(false);
     });
+    it('allows cancel to be set to true', () => {
+        const agent = new Agent();
+        const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
+        expect(event.cancel).toBe(false);
+        event.cancel = true;
+        expect(event.cancel).toBe(true);
+    });
+    it('allows cancel to be set to a string message', () => {
+        const agent = new Agent();
+        const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
+        event.cancel = 'rate limited';
+        expect(event.cancel).toBe('rate limited');
+    });
 });
 describe('AfterModelCallEvent', () => {
     it('creates instance with correct properties on success', () => {
@@ -267,13 +341,14 @@ describe('AfterModelCallEvent', () => {
         const message = new Message({ role: 'assistant', content: [new TextBlock('Response')] });
         const stopReason = 'endTurn';
         const response = { message, stopReason };
-        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response });
+        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response, invocationState: {} });
         expect(event).toEqual({
             type: 'afterModelCallEvent',
             agent: agent,
             model: agent.model,
             stopData: response,
             error: undefined,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -285,26 +360,27 @@ describe('AfterModelCallEvent', () => {
         const message = new Message({ role: 'assistant', content: [] });
         const error = new Error('Model failed');
         const response = { message, stopReason: 'error' };
-        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response, error });
+        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response, error, invocationState: {} });
         expect(event).toEqual({
             type: 'afterModelCallEvent',
             agent: agent,
             model: agent.model,
             stopData: response,
             error: error,
+            invocationState: {},
         });
     });
     it('returns true for _shouldReverseCallbacks', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [] });
         const response = { message, stopReason: 'endTurn' };
-        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response });
+        const event = new AfterModelCallEvent({ agent, model: agent.model, stopData: response, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(true);
     });
     it('allows retry to be set when error is present', () => {
         const agent = new Agent();
         const error = new Error('Model failed');
-        const event = new AfterModelCallEvent({ agent, model: agent.model, error });
+        const event = new AfterModelCallEvent({ agent, model: agent.model, error, invocationState: {} });
         // Initially undefined
         expect(event.retry).toBeUndefined();
         // Can be set to true
@@ -317,7 +393,7 @@ describe('AfterModelCallEvent', () => {
     it('retry is optional and defaults to undefined', () => {
         const agent = new Agent();
         const error = new Error('Model failed');
-        const event = new AfterModelCallEvent({ agent, model: agent.model, error });
+        const event = new AfterModelCallEvent({ agent, model: agent.model, error, invocationState: {} });
         expect(event.retry).toBeUndefined();
     });
 });
@@ -328,11 +404,12 @@ describe('ModelStreamUpdateEvent', () => {
             type: 'modelMessageStartEvent',
             role: 'assistant',
         };
-        const hookEvent = new ModelStreamUpdateEvent({ agent, event: streamEvent });
+        const hookEvent = new ModelStreamUpdateEvent({ agent, event: streamEvent, invocationState: {} });
         expect(hookEvent).toEqual({
             type: 'modelStreamUpdateEvent',
             agent: agent,
             event: streamEvent,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         hookEvent.agent = new Agent();
@@ -344,11 +421,12 @@ describe('ContentBlockEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
         const contentBlock = new TextBlock('Hello');
-        const event = new ContentBlockEvent({ agent, contentBlock });
+        const event = new ContentBlockEvent({ agent, contentBlock, invocationState: {} });
         expect(event).toEqual({
             type: 'contentBlockEvent',
             agent: agent,
             contentBlock: contentBlock,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -360,12 +438,13 @@ describe('ModelMessageEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [new TextBlock('Hello')] });
-        const event = new ModelMessageEvent({ agent, message, stopReason: 'endTurn' });
+        const event = new ModelMessageEvent({ agent, message, stopReason: 'endTurn', invocationState: {} });
         expect(event).toEqual({
             type: 'modelMessageEvent',
             agent: agent,
             message: message,
             stopReason: 'endTurn',
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -383,11 +462,12 @@ describe('ToolResultEvent', () => {
             status: 'success',
             content: [new TextBlock('Result')],
         });
-        const event = new ToolResultEvent({ agent, result: toolResult });
+        const event = new ToolResultEvent({ agent, result: toolResult, invocationState: {} });
         expect(event).toEqual({
             type: 'toolResultEvent',
             agent: agent,
             result: toolResult,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -399,11 +479,12 @@ describe('ToolStreamUpdateEvent', () => {
     it('creates instance with correct properties', () => {
         const agent = new Agent();
         const toolStreamEvent = new ToolStreamEvent({ data: 'progress' });
-        const event = new ToolStreamUpdateEvent({ agent, event: toolStreamEvent });
+        const event = new ToolStreamUpdateEvent({ agent, event: toolStreamEvent, invocationState: {} });
         expect(event).toEqual({
             type: 'toolStreamUpdateEvent',
             agent: agent,
             event: toolStreamEvent,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -418,12 +499,14 @@ describe('AgentResultEvent', () => {
             stopReason: 'endTurn',
             lastMessage: new Message({ role: 'assistant', content: [new TextBlock('Done')] }),
             metrics: new AgentMetrics(),
+            invocationState: {},
         });
-        const event = new AgentResultEvent({ agent, result });
+        const event = new AgentResultEvent({ agent, result, invocationState: {} });
         expect(event).toEqual({
             type: 'agentResultEvent',
             agent: agent,
             result: result,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -444,12 +527,13 @@ describe('BeforeToolsEvent', () => {
                 }),
             ],
         });
-        const event = new BeforeToolsEvent({ agent, message });
+        const event = new BeforeToolsEvent({ agent, message, invocationState: {} });
         expect(event).toEqual({
             type: 'beforeToolsEvent',
             agent: agent,
             message: message,
             cancel: false,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -459,13 +543,13 @@ describe('BeforeToolsEvent', () => {
     it('returns false for _shouldReverseCallbacks', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [] });
-        const event = new BeforeToolsEvent({ agent, message });
+        const event = new BeforeToolsEvent({ agent, message, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(false);
     });
     it('allows cancel to be set to true', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [] });
-        const event = new BeforeToolsEvent({ agent, message });
+        const event = new BeforeToolsEvent({ agent, message, invocationState: {} });
         expect(event.cancel).toBe(false);
         event.cancel = true;
         expect(event.cancel).toBe(true);
@@ -473,7 +557,7 @@ describe('BeforeToolsEvent', () => {
     it('allows cancel to be set to a string message', () => {
         const agent = new Agent();
         const message = new Message({ role: 'assistant', content: [] });
-        const event = new BeforeToolsEvent({ agent, message });
+        const event = new BeforeToolsEvent({ agent, message, invocationState: {} });
         event.cancel = 'tools not allowed';
         expect(event.cancel).toBe('tools not allowed');
     });
@@ -491,11 +575,12 @@ describe('AfterToolsEvent', () => {
                 }),
             ],
         });
-        const event = new AfterToolsEvent({ agent, message });
+        const event = new AfterToolsEvent({ agent, message, invocationState: {} });
         expect(event).toEqual({
             type: 'afterToolsEvent',
             agent: agent,
             message: message,
+            invocationState: {},
         });
         // @ts-expect-error verifying that property is readonly
         event.agent = new Agent();
@@ -505,7 +590,7 @@ describe('AfterToolsEvent', () => {
     it('returns true for _shouldReverseCallbacks', () => {
         const agent = new Agent();
         const message = new Message({ role: 'user', content: [] });
-        const event = new AfterToolsEvent({ agent, message });
+        const event = new AfterToolsEvent({ agent, message, invocationState: {} });
         expect(event._shouldReverseCallbacks()).toBe(true);
     });
 });
@@ -522,7 +607,7 @@ describe('toJSON serialization', () => {
     describe('BeforeInvocationEvent', () => {
         it('excludes agent and returns only type', () => {
             const agent = new Agent();
-            const event = new BeforeInvocationEvent({ agent });
+            const event = new BeforeInvocationEvent({ agent, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({ type: 'beforeInvocationEvent' });
         });
@@ -530,7 +615,7 @@ describe('toJSON serialization', () => {
     describe('AfterInvocationEvent', () => {
         it('excludes agent and returns only type', () => {
             const agent = new Agent();
-            const event = new AfterInvocationEvent({ agent });
+            const event = new AfterInvocationEvent({ agent, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({ type: 'afterInvocationEvent' });
         });
@@ -538,7 +623,7 @@ describe('toJSON serialization', () => {
     describe('BeforeModelCallEvent', () => {
         it('excludes agent and model and returns only type', () => {
             const agent = new Agent();
-            const event = new BeforeModelCallEvent({ agent, model: agent.model });
+            const event = new BeforeModelCallEvent({ agent, model: agent.model, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({ type: 'beforeModelCallEvent' });
         });
@@ -547,7 +632,7 @@ describe('toJSON serialization', () => {
         it('includes message and excludes agent', () => {
             const agent = new Agent();
             const message = new Message({ role: 'assistant', content: [new TextBlock('Hello')] });
-            const event = new MessageAddedEvent({ agent, message });
+            const event = new MessageAddedEvent({ agent, message, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'messageAddedEvent',
@@ -562,7 +647,7 @@ describe('toJSON serialization', () => {
                 type: 'modelContentBlockDeltaEvent',
                 delta: { type: 'textDelta', text: 'Hi' },
             };
-            const event = new ModelStreamUpdateEvent({ agent, event: streamEvent });
+            const event = new ModelStreamUpdateEvent({ agent, event: streamEvent, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'modelStreamUpdateEvent',
@@ -574,7 +659,7 @@ describe('toJSON serialization', () => {
         it('includes content block and excludes agent', () => {
             const agent = new Agent();
             const contentBlock = new TextBlock('Hello world');
-            const event = new ContentBlockEvent({ agent, contentBlock });
+            const event = new ContentBlockEvent({ agent, contentBlock, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'contentBlockEvent',
@@ -586,7 +671,7 @@ describe('toJSON serialization', () => {
         it('includes message and stopReason, excludes agent', () => {
             const agent = new Agent();
             const message = new Message({ role: 'assistant', content: [new TextBlock('Done')] });
-            const event = new ModelMessageEvent({ agent, message, stopReason: 'endTurn' });
+            const event = new ModelMessageEvent({ agent, message, stopReason: 'endTurn', invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'modelMessageEvent',
@@ -603,7 +688,7 @@ describe('toJSON serialization', () => {
                 status: 'success',
                 content: [new TextBlock('42')],
             });
-            const event = new ToolResultEvent({ agent, result });
+            const event = new ToolResultEvent({ agent, result, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'toolResultEvent',
@@ -615,7 +700,7 @@ describe('toJSON serialization', () => {
         it('includes tool stream event and excludes agent', () => {
             const agent = new Agent();
             const toolStreamEvent = new ToolStreamEvent({ data: { progress: 50 } });
-            const event = new ToolStreamUpdateEvent({ agent, event: toolStreamEvent });
+            const event = new ToolStreamUpdateEvent({ agent, event: toolStreamEvent, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'toolStreamUpdateEvent',
@@ -630,8 +715,9 @@ describe('toJSON serialization', () => {
                 stopReason: 'endTurn',
                 lastMessage: new Message({ role: 'assistant', content: [new TextBlock('Done')] }),
                 metrics: new AgentMetrics(),
+                invocationState: {},
             });
-            const event = new AgentResultEvent({ agent, result });
+            const event = new AgentResultEvent({ agent, result, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'agentResultEvent',
@@ -653,7 +739,7 @@ describe('toJSON serialization', () => {
                 callback: () => 'result',
             });
             const toolUse = { name: 'testTool', toolUseId: 'id-1', input: { query: 'hello' } };
-            const event = new BeforeToolCallEvent({ agent, toolUse, tool });
+            const event = new BeforeToolCallEvent({ agent, toolUse, tool, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'beforeToolCallEvent',
@@ -670,7 +756,7 @@ describe('toJSON serialization', () => {
                 status: 'success',
                 content: [new TextBlock('42')],
             });
-            const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result });
+            const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'afterToolCallEvent',
@@ -687,7 +773,7 @@ describe('toJSON serialization', () => {
                 content: [new TextBlock('Error')],
             });
             const error = new Error('Tool crashed');
-            const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error });
+            const event = new AfterToolCallEvent({ agent, toolUse, tool: undefined, result, error, invocationState: {} });
             event.retry = true;
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
@@ -703,7 +789,7 @@ describe('toJSON serialization', () => {
             const agent = new Agent();
             const message = new Message({ role: 'assistant', content: [new TextBlock('Hi')] });
             const stopData = { message, stopReason: 'endTurn' };
-            const event = new AfterModelCallEvent({ agent, model: agent.model, stopData });
+            const event = new AfterModelCallEvent({ agent, model: agent.model, stopData, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'afterModelCallEvent',
@@ -716,7 +802,7 @@ describe('toJSON serialization', () => {
         it('converts error to message string and excludes retry', () => {
             const agent = new Agent();
             const error = new Error('Model failed');
-            const event = new AfterModelCallEvent({ agent, model: agent.model, error });
+            const event = new AfterModelCallEvent({ agent, model: agent.model, error, invocationState: {} });
             event.retry = true;
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
@@ -732,7 +818,7 @@ describe('toJSON serialization', () => {
                 role: 'assistant',
                 content: [new ToolUseBlock({ name: 'calc', toolUseId: 'id-1', input: {} })],
             });
-            const event = new BeforeToolsEvent({ agent, message });
+            const event = new BeforeToolsEvent({ agent, message, invocationState: {} });
             event.cancel = 'not allowed';
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
@@ -754,7 +840,7 @@ describe('toJSON serialization', () => {
                     }),
                 ],
             });
-            const event = new AfterToolsEvent({ agent, message });
+            const event = new AfterToolsEvent({ agent, message, invocationState: {} });
             const json = JSON.parse(JSON.stringify(event));
             expect(json).toStrictEqual({
                 type: 'afterToolsEvent',
@@ -773,6 +859,7 @@ describe('toJSON serialization', () => {
             const event = new ModelStreamUpdateEvent({
                 agent,
                 event: { type: 'modelContentBlockDeltaEvent', delta: { type: 'textDelta', text: 'Hi' } },
+                invocationState: {},
             });
             const json = JSON.stringify(event);
             // Should be small (no agent serialized)
@@ -792,7 +879,7 @@ describe('toJSON serialization completeness', () => {
      * If you add a new field to an event and it should be excluded from wire serialization,
      * add it here. Otherwise, add it to toJSON() so it gets serialized.
      */
-    const EXCLUDED_FIELDS = new Set(['agent', 'model', 'tool', 'cancel', 'retry']);
+    const EXCLUDED_FIELDS = new Set(['agent', 'model', 'tool', 'cancel', 'retry', 'invocationState']);
     /**
      * Fields where toJSON() transforms the value (e.g., Error to message object).
      * These appear in both instance and JSON but with different shapes.
@@ -817,30 +904,50 @@ describe('toJSON serialization completeness', () => {
             stopReason: 'endTurn',
             lastMessage: message,
             metrics: new AgentMetrics(),
+            invocationState: {},
         });
         return [
             { name: 'InitializedEvent', event: new InitializedEvent({ agent }) },
-            { name: 'BeforeInvocationEvent', event: new BeforeInvocationEvent({ agent }) },
-            { name: 'AfterInvocationEvent', event: new AfterInvocationEvent({ agent }) },
-            { name: 'BeforeModelCallEvent', event: new BeforeModelCallEvent({ agent, model: agent.model }) },
+            { name: 'BeforeInvocationEvent', event: new BeforeInvocationEvent({ agent, invocationState: {} }) },
+            { name: 'AfterInvocationEvent', event: new AfterInvocationEvent({ agent, invocationState: {} }) },
+            {
+                name: 'BeforeModelCallEvent',
+                event: new BeforeModelCallEvent({
+                    agent,
+                    model: agent.model,
+                    invocationState: {},
+                    projectedInputTokens: 100,
+                }),
+            },
             {
                 name: 'AfterModelCallEvent',
-                event: Object.assign(new AfterModelCallEvent({ agent, model: agent.model, stopData, error }), { retry: true }),
+                event: Object.assign(new AfterModelCallEvent({ agent, model: agent.model, stopData, error, invocationState: {} }), { retry: true }),
+            },
+            { name: 'MessageAddedEvent', event: new MessageAddedEvent({ agent, message, invocationState: {} }) },
+            {
+                name: 'ModelStreamUpdateEvent',
+                event: new ModelStreamUpdateEvent({ agent, event: streamEvent, invocationState: {} }),
+            },
+            { name: 'ContentBlockEvent', event: new ContentBlockEvent({ agent, contentBlock, invocationState: {} }) },
+            {
+                name: 'ModelMessageEvent',
+                event: new ModelMessageEvent({ agent, message, stopReason: 'endTurn', invocationState: {} }),
             },
-            { name: 'MessageAddedEvent', event: new MessageAddedEvent({ agent, message }) },
-            { name: 'ModelStreamUpdateEvent', event: new ModelStreamUpdateEvent({ agent, event: streamEvent }) },
-            { name: 'ContentBlockEvent', event: new ContentBlockEvent({ agent, contentBlock }) },
-            { name: 'ModelMessageEvent', event: new ModelMessageEvent({ agent, message, stopReason: 'endTurn' }) },
-            { name: 'ToolResultEvent', event: new ToolResultEvent({ agent, result }) },
-            { name: 'ToolStreamUpdateEvent', event: new ToolStreamUpdateEvent({ agent, event: toolStreamEvent }) },
-            { name: 'AgentResultEvent', event: new AgentResultEvent({ agent, result: agentResult }) },
-            { name: 'BeforeToolCallEvent', event: new BeforeToolCallEvent({ agent, toolUse, tool }) },
+            { name: 'ToolResultEvent', event: new ToolResultEvent({ agent, result, invocationState: {} }) },
+            {
+                name: 'ToolStreamUpdateEvent',
+                event: new ToolStreamUpdateEvent({ agent, event: toolStreamEvent, invocationState: {} }),
+            },
+            { name: 'AgentResultEvent', event: new AgentResultEvent({ agent, result: agentResult, invocationState: {} }) },
+            { name: 'BeforeToolCallEvent', event: new BeforeToolCallEvent({ agent, toolUse, tool, invocationState: {} }) },
             {
                 name: 'AfterToolCallEvent',
-                event: Object.assign(new AfterToolCallEvent({ agent, toolUse, tool, result, error }), { retry: true }),
+                event: Object.assign(new AfterToolCallEvent({ agent, toolUse, tool, result, error, invocationState: {} }), {
+                    retry: true,
+                }),
             },
-            { name: 'BeforeToolsEvent', event: new BeforeToolsEvent({ agent, message }) },
-            { name: 'AfterToolsEvent', event: new AfterToolsEvent({ agent, message }) },
+            { name: 'BeforeToolsEvent', event: new BeforeToolsEvent({ agent, message, invocationState: {} }) },
+            { name: 'AfterToolsEvent', event: new AfterToolsEvent({ agent, message, invocationState: {} }) },
         ];
     }
     const eventInstances = createEventInstances();