feat(runtime): add interactive shell

[aidandaly24]

Summary

Adds agentcore runtime shell, a native interactive PTY session for AgentCore
Runtimes using the currently published TypeScript SDK (bedrock-agentcore
0.4.3).

• Bare runtime shell opens Runtime and endpoint pickers.
• --id skips the Runtime picker.
• --id with --qualifier connects directly.
• --session-id opens the shell in a specific Runtime session.
• IAM and CUSTOM_JWT Runtimes are supported.
• Raw input, Ctrl+C, Ctrl+D, terminal resize, ANSI/full-screen
  applications, transparent 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 Runtime Shell screen uses Ink's suspendTerminal() API so Ink releases raw
input and the alternate screen before IO takes terminal ownership. When the
shell ends, Ink restores the same TUI instance and the screen navigates back to
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>

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.
• Running exit or sending Ctrl+D terminates the remote shell.

Validation

• CI=true bun test --coverage --coverage-reporter=lcov
• Focused Runtime Shell/TUI suite
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run secrets:check
• bun run build

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
• clean exit with exit code 0
• return to the Runtime picker, endpoint picker, and Runtime details origin

Stack

This PR is independently mergeable and does not require a TypeScript SDK
release. Follow-up PR #2199 adds detach and reattach after the corresponding SDK
behavior is published.

[agentcore-devx-automation]

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.24619% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.03%. Comparing base (97d3d9a) to head (afbfd61).

Files with missing lines	Patch %	Lines
src/core/runtimeShell.ts	89.18%	8 Missing ⚠️
src/handlers/runtime/shell/index.tsx	84.90%	8 Missing ⚠️
src/handlers/runtime/shell/request.ts	88.88%	6 Missing ⚠️
src/core/runtime.tsx	28.57%	5 Missing ⚠️
src/handlers/runtime/shell/operation.ts	92.00%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2198      +/-   ##
============================================
- Coverage     97.07%   97.03%   -0.05%     
============================================
  Files           544      551       +7     
  Lines         37866    38323     +457     
============================================
+ Hits          36760    37186     +426     
- Misses         1106     1137      +31     

☔ 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]

AgentCore Harness Review

Verdict: Looks good

Nice work — the shell command is well‑structured and the abstraction boundaries are clean:

• InteractiveTerminal is decoupled from the runtime SDK via InteractiveTerminalPeer and gets solid unit coverage using real PassThrough streams.
• The SDK adapter (createRuntimeShellOpener) is testable via createClient/sleep injection, and the retry policy on 409/424/429 upgrade failures is bounded and covered.
• Auth + endpoint constraints (CUSTOM_JWT requires --bearer-token, IAM rejects it, --endpoint-url and --json are rejected, TTY is required) are all enforced in normalizeRuntimeShellRequest and runRuntimeShell with matching tests.
• The TuiHandoffController cleanly solves the "unmount Ink, run raw‑mode PTY, remount Ink" problem, and the renderTuiAt loop remounts the requested origin.
• The bundler plugin correctly rewrites bedrock-agentcore/runtime to the client entry so the server‑side deps get tree‑shaken.

A couple of small things worth being aware of but not blocking:

• Pulling in bedrock-agentcore transitively brings the legacy @aws-sdk/protocol-http@3.374.0 and @aws-sdk/signature-v4@3.374.0 (2023) alongside the current @smithy/* equivalents already in the tree. Nothing to fix here — just something to watch as the SDK team consolidates.
• In InteractiveTerminal.run, if the pump() iterator rejects, pending is not awaited before entering the finally (control jumps past await pending). In practice queued sends/resizes are best‑effort and cleanup still runs, so this is fine, but if you ever surface a "no lost writes on failure" guarantee you'd want to await pending.catch(() => {}) in the finally.

[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)

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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

[notgitika]

LGTM

[AlexanderRichey]

A lot going on in this PR! I presume a lot of this is a copy/paste job from the old CLI?