feat(bb-agent): server-resolved tool context from verified JWT claims (4/5)

[pjkroker]

Problem

Browser-direct WebSocket streaming (PRs #250–#252) lets the browser stream straight to the AgentCore Runtime, bypassing the app's API Gateway → Lambda. In the old Lambda world, every turn ran through the app's sendMessage method, which held the HTTP request and built tool context (auth.getCurrentUser() + DB) before calling the agent. That per-turn app hop is gone, so a toolContextSchema agent (which requires context) could only run on the buffered server-mediated path — not browser-direct, where the transport carries no context. PR #251 hardcoded one thing: inject the verified JWT sub as context.userId.

Change

Add an optional AgentConfig.resolveToolContext(claims) hook. It runs in the AgentCore container each turn against the gateway-verified JWT claims and returns the tool context. Because the runtime's JWT authorizer already validated the token, the claims are trustworthy and unforgeable by the browser. The verified sub is always overlaid as context.userId afterward, so identity stays authoritative.

This is an in-process hook (the container already co-bundles and runs the app backend) — no network callback, no API URL, no IAM execute-api, no 30s cap.

• types.ts: new resolveToolContext?: (claims) => TContext | Promise<TContext>.
• agentcore-entry.ts: userIdFromContext → claimsFromContext (full payload) + userIdFromContext; new buildToolContext(claims, rawContext, resolver) runs the resolver then overlays sub; wired into both /invocations and /ws.
• agent.ts: AgentBase.toolContextResolver getter so the entry handler can read the hook.
• Reference app: wsAgent gains toolContextSchema + resolveToolContext + a whoami tool, plus an e2e asserting a context-scoped tool runs browser-direct.
• Docs: README "Server-resolved tool context" subsection + DESIGN.md identity section.

Scope / boundaries (by design)

• Access-token claims only. For AuthCognito the runtime gets the access token: sub, username, cognito:groups, scope — not email/custom:* (ID-token-only; would need a pre-token-generation Lambda, future work).
• Cognito-only today — OIDC has no getAgentCoreToken, so no token reaches the container on that path yet.
• Identity/scoping context only. Non-identity, request-varying data belongs in the tool handler (also runs in the container) or as model input — not this hook. Matches the toAgentTools() scope((ctx)=>...) design (Chorus l3Jtq1L2LST6), which only ever uses context for identity.
• Does not build toAgentTools/scope — this PR only produces the ctx that scope will later consume.

Backward compatibility

• No resolver configured → behavior identical to feat(bb-agent): browser-direct WebSocket streaming + server-verified identity (2/5) #251 (sub→userId injection).
• No token (IAM runtime / local dev) → resolver not called; client/body context passes through unchanged.
• Verified sub overrides any resolver- or client-supplied userId (no spoofing).

Tests

101 pass in packages/bb-agent (+8). New buildToolContext cases: resolver builds from claims; sub overrides resolver output and client value; no-token passthrough; async resolver; claimsFromContext decode. Comprehensive app typechecks; new sandbox e2e for the browser-direct context-scoped turn.

Stacked on #252 (agentcore/3-docs). Rebase onto main if the migration merges first.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f47bc07

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR