feat(context): track agent.messages token size

[lizradway]

Description

Adds visibility into LLM context window utilization by exposing the most recent inputTokens count through two new properties:

• AgentMetrics.latestContextSize — the most recent inputTokens value from model responses, enabling threshold-based decisions about context compression or externalization
• AgentResult.contextSize — convenience getter that delegates to metrics.latestContextSize

Zero overhead (reuses inputTokens already returned by every LLM call), zero latency impact (no additional API calls), and provider-agnostic (all providers normalize to the Usage interface).

Usage

const result = await agent.invoke('Do something with tools')

// Via AgentResult (convenience)
result.contextSize

// Via AgentMetrics
result.metrics?.latestContextSize

Port of strands-agents/sdk-python#2009.

Related Issues

#791

Documentation PR

N/A

Type of Change

New feature

Testing

How have you tested the change?

• I ran npm run check
• Added unit tests for Meter.latestContextSize tracking (undefined on fresh instance, updates after model calls, updates across cycles/invocations, handles missing usage)
• Added unit tests for AgentMetrics.toJSON with/without latestContextSize
• Added unit tests for AgentResult.contextSize delegation (with metrics, without context size, without metrics)

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
• 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