feat(agentcore): AWS Bedrock AgentCore Code Interpreter adapter

[miyaontherelay]

Summary

Adds AgentCoreSandboxRuntime implementing SandboxRuntime/WorkflowRuntime
for AWS Bedrock AgentCore's Code Interpreter, following the same
SDK-isolation / capability-reconciliation / provenance discipline as the
Vercel and Modal adapters (agent/vercel-adapter-0821,
agent/modal-adapter-0821).

• Network mode defaults to VPC, never SANDBOX: the March 2026 DNS
  sandbox-escape research (BeyondTrust Phantom Labs, corroborated by Unit 42
  and CSA) is cited inline in config.ts/runtime.ts and in
  docs/agentcore.md. SANDBOX requires an explicit, named opt-in and logs
  a warning citing the hazard every time it's chosen.
• lifecycle (start/stop) is structurally false and the methods are
  omitted entirely — a session's status is READY | TERMINATED only, no
  resume path, same shape modal-adapter-0821 documents for
  Sandbox.terminate().
• warmLease is structurally false — AgentCore sessions carry no
  server-side tag/label field; findAllByLabels searches this runtime
  instance's own in-process registrations only.
• SDK boundary isolated to src/agentcore/internal/sdk.ts (dynamic import,
  optional peer deps @aws-sdk/client-bedrock-agentcore +
  @aws-sdk/client-bedrock-agentcore-control); SDK-free config/capabilities
  in config.ts/capabilities.ts.
• 29 mocked/contract tests (runtime.test.ts, bench.test.ts), all passing.

Verified against the real AWS SDK (update from initial draft)

The first push flagged that npm install/npm test couldn't be run locally
in the build sandbox. Root cause found and fixed: ~/.npmrc on that host is
a symlink into a Dropbox-synced path, and reads of it were hanging/EINTR'ing
inside the sandbox, which stalls npm at startup on every invocation
(npm --version included) before it ever touches the network — unrelated to
AWS. Workaround: NPM_CONFIG_USERCONFIG=/dev/null npm install.

With a real install, npm run typecheck, npm run build, and npm test
all pass clean (242 pass / 0 fail across the whole package, 3 pre-existing
skips unrelated to this change). Running against the real generated SDK
types (not a hand-written shim) surfaced and fixed three real bugs:
InvokeCodeInterpreterCommand's name is a closed ToolName enum not a
plain string; CodeInterpreterResult.isError is optional; and the invoke
stream is a discriminated union whose exception members were being silently
dropped. Running the real test suite also caught a design bug no shim or
review would have: createOrAdoptInterpreter only ever created a new
interpreter, never adopted an existing one by name as its own name and
config.ts's doc comment promised — two runtime instances pointed at the
same owned interpreter name raced to create two different interpreters, and
a session started by one was silently unreachable from the other's
getById. Fixed with a bounded (10-page) list-and-adopt search before
create.

Still blocked — not review-final yet

No AWS credentials or IAM execution role are provisioned in the build
environment. This PR ships mocked-only. The live n=1 canary → n=7 bench —
including the idle-billing measurement that's the load-bearing economics
question for this adapter (does AgentCore's "idle time is free" billing
claim cover session memory, or only CPU?) — and the docs/PRIVATE-sandbox-economics-2026-08-20.md
row extension are not done, per docs/agentcore.md#credential-status.

Khaliq action items

1. Provision AWS credentials for this workload — either static IAM user
   keys or confirmation that an assumable-role default credential chain is
   already reachable — scoped to the bedrock-agentcore* IAM policy listed
   in docs/agentcore.md#credential-status.
2. An IAM execution role ARN (trust policy for
   bedrock-agentcore.amazonaws.com) if the S3 large-file path should be
   exercised in the live bench.
3. A target region, plus at least one subnet id and one security group id
   for the VPC-mode live canary (this adapter's default network mode).

Test plan

• 29 mocked tests in src/agentcore/runtime.test.ts +
  src/agentcore/bench.test.ts, run for real via npm test: 242/242
  pass package-wide, 0 fail.
• npm run typecheck and npm run build both pass clean against the
  real @aws-sdk/client-bedrock-agentcore* type declarations.
• Live n=1 canary — blocked on credentials.
• Live n=7 bench + idle-billing measurement — blocked on credentials.
• Economics doc row — blocked on the above.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H6cB7qLYbvnHjRZXbA4HUH

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7377d1f4-9f3f-413b-adb7-e4b73fb10b52

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}