feat(agent): add invocationState support for per-request state

[Aparnap2]

---

Enables passing arbitrary state through the agent invocation lifecycle, accessible in hooks and tool contexts. Not persisted between invocations.

Description

This PR implements invocationState support for the Agent invoke and stream methods, achieving feature parity with the Python SDK. This allows developers to pass transient, per-request context (such as userId, requestId, or sessionId) through the agent's lifecycle hooks and tool executions without modifying the agent's persistent state.

Key Implementation Details:

1. Agent API (src/agent/agent.ts)

   • Introduced InvokeOptions interface: type InvokeOptions = { invocationState?: Record<string, unknown> }
   • Updated invoke() and stream() to accept options?: InvokeOptions.
   • Plumbed invocationState through the internal _stream loop to hooks and tool executors.

2. Lifecycle Hooks (src/hooks/events.ts)

   • Added invocationState to BeforeInvocationEvent for request-level context.
   • Added invocationState to granular events (BeforeModelCallEvent, BeforeToolCallEvent, etc.) to enable precise tracing and logging deep in the execution stack.

3. Tool Context (src/tools/tool.ts)

   • Updated ToolContext to include invocationState, allowing tools to access request-specific data.

4. Type Safety

   • Used Record<string, unknown> to ensure strict type safety (avoiding any) while allowing flexible user data.

Usage Example:

await agent.invoke('Analyze data', {
  invocationState: { userId: '123', traceId: 'abc' }
});

Related Issues

Fixes #427

Documentation PR

(N/A - Documentation updates included in this PR via README usage examples)

Type of Change

New feature

Testing

How have you tested the change?

• I ran npm run check
• Unit Tests: Added tests in src/agent/__tests__/agent.test.ts verifying invocationState propagation to hooks and tool contexts.
• Integration Tests: Added tests in test/integ/agent.test.ts verifying the full flow from invocation to tool execution.
• Manual Verification: Verified type safety and lint compliance.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly (README usage example)
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.