fix(bma): create the BMA session role in client.py and pass it as role_arn

[siwachabhi]

Description

Bedrock Managed Agents (BMA) assumes a session role to call the model and the AgentCore Runtime (ACR). The BedrockManagedAgents template did not create this role, and client.py did not send it. A new account failed in CreateAgentSession with a 400 error until the reader created BedrockManagedAgentsPreviewInferenceServiceRole by hand. No public page tells the reader to do that.

This PR makes client.py create the session role and send it as role_arn. It needs no construct change and no construct release.

When client.py creates a session and the reader does not give --role-arn, the client does these steps:

1. It gets the partition, the Region, and the account from the ACR ARN, and it puts them in policies/bma-session-trust.json and policies/bma-session-policy.json.
2. If the role BmaSessionRole-<region> does not exist, the client creates it.
3. If the trust policy or the inline policy BmaSession is not the same as the file, the client writes the file to the role.
4. If it changed the role, the client waits 15 seconds, because IAM needs this time before BMA can use the change.

--role-arn uses a role that the reader created, and the client then makes no IAM calls. If the caller has no IAM permissions, the client stops and tells the reader to give --role-arn.

The session policies are limited to the account and the Region of the ACR. They do not name one Runtime, because the Runtime ARN is not known when you create the role:

• Trust: bedrock-mantle.amazonaws.com, with aws:SourceAccount and aws:SourceArn on session/* and project/*.
• Policy: bedrock-mantle:CreateInference on *, InvokeAgentRuntime and StopRuntimeSession on runtime/* and runtime/*/runtime-endpoint/*, and InvokeGateway on gateway/*.

Changes:

• client.py: add --role-arn, create or repair the session role with boto3, and send the role with extra_body={"role_arn": ...}, because the OpenAI SDK has no role_arn parameter.
• policies/bma-session-trust.json and policies/bma-session-policy.json: new.
• policies/bma-acr-policy.json: moved from the template root. The content is the same.
• bmaProfile.ts: the new path in additionalPolicies.
• pyproject.toml: add boto3 to the dev group.
• README.md (template) and docs/frameworks.md: a "Session role" section. It says clearly that client.py creates an IAM role in your account, that agentcore remove does not delete it, what the client repairs and what it does not change, and the IAM permissions of the caller.
• bma.test.ts and the asset snapshot.

Related Issue

No issue. The problem came from the BMA launch tests on 2026-09-29.

Documentation PR

The AgentCore developer guide page runtime-get-started-bma gets a matching change in a separate internal docs review.

Type of Change

• Bug fix

Testing

• npm run test:unit (6,332 passed). npm run test:integ not run. The TUI integration suites need a terminal.
• npm run typecheck
• prettier on the changed files, and ruff check and ruff format --check on client.py
• Updated the asset snapshots

End to end in one account in us-east-1, after I deleted BedrockManagedAgentsPreviewInferenceServiceRole:

Scenario	Result
No session role, no --role-arn	The client creates the role. The turn completes.
A second turn with --session-id	Passes.
The role exists and has no change	Passes. No IAM write and no wait.
Someone breaks the policy, breaks the trust policy, or deletes the policy	The next new session puts the files back. The turn completes.
The reader changes policies/bma-session-policy.json, then reverts it	The role follows the file each time.
--role-arn with a good role	Passes.
A wrong role or a missing role in --role-arn	BMA returns a 400 validation_error with param: role_arn.
A caller with no IAM permissions, no --role-arn	The client stops with a clear error.
A caller with only the BMA permissions and iam:PassRole, with --role-arn	Passes.
A caller with the 5 IAM actions in the README	Create and repair both pass.
A caller without iam:PassRole	BMA returns a 403 that names iam:PassRole.
--delete	Passes.

CloudTrail showed 51 AssumeRole calls from bedrock-mantle.amazonaws.com on BmaSessionRole-us-east-1. None failed, and none went to the preview role.

Known limits, which the README states:

• The client manages only the trust policy and BmaSession. Another policy on the role, for example a Deny, stays.
• A turn with --session-id does not check the role. If the role is broken, the turn fails until a new session repairs it.

Checklist

• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• My changes generate no new warnings

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Reviewed the full diff and traced the policy-file plumbing. The change is well-scoped: it moves bma-acr-policy.json under policies/, adds bma-session-trust.json / bma-session-policy.json, and extends client.py to create/repair a BmaSessionRole-<region> and pass it to BMA via extra_body={"role_arn": ...}.

Things I checked and found fine:

• ARN parsing in session_role: runtime_arn.split(":")[:5] correctly maps to (arn, partition, service, region, account) for the AgentCore runtime ARN format.
• Trust/policy equality checks: role["AssumeRolePolicyDocument"] and get_role_policy(...)["PolicyDocument"] are returned as decoded dicts by boto3, so comparing against json.loads(trust) / json.loads(policy) is correct, and placeholder substitution runs before json.loads.
• ${AWS::...} substitution happens on the raw text before parsing, so the stored trust/inline policy never contains unexpanded placeholders.
• Control flow around --session-id / --role-arn: session_role() is only invoked when creating a new session and no --role-arn was passed; the existing-session branch doesn't hit extra_body, matching the documented behavior.
• Tests (src/cli/templates/__tests__/bma.test.ts) use real file I/O against the template directory — no excessive mocking.
• Telemetry: this PR only touches scaffolded template content (Python client, policy JSON, docs), so no CLI telemetry instrumentation is needed.

Nothing blocking. A couple of small things the author may want to consider as follow-ups (not required to merge):

• boto3 is added to the dev group of pyproject.toml without a version constraint, while the other entries use >=. Pinning a lower bound would be consistent.
• The 15-second time.sleep for IAM eventual consistency is a known pragmatic workaround and is already documented in the README, so OK as-is.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	41.28%	15848 / 38384
🔵	Statements	40.55%	16912 / 41697
🔵	Functions	35.37%	2730 / 7718
🔵	Branches	34.47%	10621 / 30805

Generated in workflow #4507 for commit f1f14dd by the Vitest Coverage Report Action

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)