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

[opieter-aws]

/strands review

[github-actions]

Assessment: Comment

Clean, minimal feature port from the Python SDK. The implementation follows existing patterns well — Meter tracks the value, AgentMetrics stores it, and AgentResult provides a convenience accessor.

Review Categories

• API Design: Naming is consistent with the Python SDK port (latestContextSize/contextSize). The needs-api-review label is correctly applied. The API is well-scoped — two new read-only properties with zero overhead.
• Documentation: TSDoc descriptions reference "context window utilization" which slightly overstates what inputTokens represents. Suggested more precise wording aligned with the Python PR's framing.
• Testing: Thorough coverage of edge cases. Minor organization suggestion to merge toJSON with latestContextSize into the existing toJSON describe block.
• Documentation PR: Consider a follow-up docs PR since this adds public API surface that enables context management workflows.

Well-structured, focused change with good test coverage. 👍

[github-actions]

Assessment: Approve

All prior review threads have been resolved with clear rationale from the author and reviewers. The code is unchanged from the original commit — the design decisions around persistence across invocations and using inputTokens alone are well-justified and align with the Python SDK port.

No new issues found. Implementation is clean, well-tested (11 new test cases, all passing), and follows existing SDK patterns.