feat(runtime): add interactive shell

[aidandaly24]

Summary

Adds agentcore runtime shell, a native interactive PTY session for AgentCore
Runtimes.

• Bare runtime shell opens Runtime and endpoint pickers.
• --id skips the Runtime picker.
• --id with --qualifier connects directly.
• --session-id with --shell-id reattaches to an existing shell.
• IAM and CUSTOM_JWT Runtimes are supported.
• Ctrl+C, terminal resize, ANSI/full-screen applications, detach, reconnect,
  and remote exit status are preserved.
• Shells launched from the TUI return to their originating Runtime picker,
  endpoint picker, or Runtime details screen when the native terminal ends.

The ownership boundaries are intentional:

• Handler: target/auth policy and orchestration.
• Core: remote shell connection.
• IO: local terminal ownership.

The TUI uses a post-render handoff so Ink fully restores the terminal before IO
enters raw mode. This keeps the picker experience in the existing TUI while the
actual shell remains a native terminal session. When that handoff completes,
Ink remounts the route that launched it.

Command

agentcore runtime shell
agentcore runtime shell --id <runtimeId>
agentcore runtime shell --id <runtimeId> --qualifier DEFAULT
agentcore runtime shell \
  --id <runtimeId> \
  --qualifier DEFAULT \
  --session-id <runtimeSessionId> \
  --shell-id <shellId>

Additional behavior:

• --bearer-token accepts inline or file:// CUSTOM_JWT tokens.
• stdin token sources are rejected because the PTY owns stdin.
• --json and --endpoint-url are rejected.
• Ctrl+] detaches and prints the exact reattach command.

Validation

• bun test src: 2,886 passed, 0 failed.
• Focused Runtime Shell/TUI suite: 81 passed, 0 failed.
• bun run format:check
• bun run secrets:check
• bun run build
• bun run compile:linux-x64
• Standalone Linux binary smoke test
• Fresh bun install --frozen-lockfile
• bun audit

The current refactor base has a duplicate resolveProjectResources key in
src/handlers/project/buildDeploy.screen.test.tsx, so repository-wide
typecheck and lint fail on that unchanged upstream file. Targeted lint for every
file changed by this PR passes.

Live TUI Harness validation against a READY IAM Runtime in us-west-2 covered:

• direct and picker-based launch
• raw command input and exact output
• working-directory and environment persistence
• Ctrl+C interrupt without disconnecting
• ANSI clear-screen output
• Ctrl+] detach
• reattach with buffered screen replay and preserved process state
• clean exit with exit code 0
• bare picker shell exit returning to the Runtime picker
• --id shell detach returning to the endpoint picker
• Runtime-details shell exit returning to the same Runtime details screen

Merge blocker

This PR must not merge until
aws/bedrock-agentcore-sdk-typescript#249
is merged and published, then bedrock-agentcore and bun.lock are refreshed.

The current npm release (0.4.3) exposes the required TypeScript API and keeps
this branch reproducible, but its ShellSession.close() permanently terminates
the remote PTY. Live detach/reattach validation used the exact PR head
3b83f6e63b87f5753ccfb05b66a99a45c7e6826f, where close() detaches and the
updated shell wire protocol is implemented.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 92.33792% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (a665955) to head (860f0c1).
⚠️ Report is 1 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/runtimeShell.ts	87.65%	10 Missing ⚠️
src/handlers/runtime/shell/operation.ts	82.75%	10 Missing ⚠️
src/handlers/runtime/shell/index.tsx	87.87%	8 Missing ⚠️
src/handlers/runtime/shell/request.ts	90.47%	6 Missing ⚠️
src/core/runtime.tsx	28.57%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2189      +/-   ##
============================================
- Coverage     97.15%   97.08%   -0.07%     
============================================
  Files           542      550       +8     
  Lines         37728    38227     +499     
============================================
+ Hits          36653    37113     +460     
- Misses         1075     1114      +39     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice, well-layered addition. Shell transport, terminal I/O, TUI handoff, and the handler are cleanly separated, and each layer has focused tests that mock at real boundaries (SDK openShell, InteractiveTerminalPeer) rather than at implementation details. Telemetry is picked up automatically by the router/TUI middleware (command_path and is_tui), consistent with sibling commands like invoke, so no extra instrumentation is needed here.

A few things I looked at closely and am satisfied with:

• InteractiveTerminal.run restores raw mode, pause state, SIGWINCH, and stdin listeners in finally, and covers the abort / pump-failure / detach-byte paths in tests.
• resolveRuntimeShellBearerToken correctly rejects - (stdin) because the PTY owns stdin, and strips only a single trailing newline.
• normalizeRuntimeShellRequest refuses non-READY runtimes, malformed ARNs, non-CUSTOM_JWT authorizers, and enforces the token/no-token combinations for IAM vs CUSTOM_JWT.
• The RuntimeShellScreen -> TuiHandoffController pattern correctly unmounts Ink before running the interactive shell, and renderTuiAt invokes handoffs.take() after waitUntilExit, which the screen test asserts.
• The 64 KiB - 1 chunking in RuntimeShellSessionAdapter.send is exercised by a boundary test that verifies bytes are preserved across the split.
• withTuiOnEmptyFlagsAndArgs handles the bare agentcore runtime shell case (no flags → TUI), and the handler's --id-required branch correctly kicks in only when any flag is supplied, matching the documented UX.

Nothing blocking from me.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[AlexanderRichey]

Interesting mechanism here. Looks like it'll work, but we'll have to be careful. Abusing this could cause a lot of weird behavior.

[AlexanderRichey]

Looks like there are some merge conflicts.

[agentcore-devx-automation]

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

[aidandaly24]

Superseded by the upstream-native stack:

• feat(runtime): add interactive shell #2198 — SDK-independent Runtime Shell
• feat(runtime): add shell detach and reattach #2199 — detach/reattach follow-up (draft, pending SDK release)

The replacement branches now live directly in aws/agentcore-cli; the original fork branches remain preserved.