feat(harness): add interactive shell command

[aidandaly24]

Description

Add agentcore harness shell, alongside the Runtime-shell diagnostic fix in #2544. These PRs are intended to ship together: merge the Harness shell command before the diagnostic starts recommending it.

agentcore harness shell --id <harness-id> --qualifier DEFAULT
agentcore harness shell --id <harness-id> --qualifier DEFAULT --session-id <session-id>

• Follow the Runtime shell CLI/TUI flow: choose a harness and endpoint, or connect directly with --qualifier; preserve --session-id and sensitive --bearer-token through the picker.
• Address the Harness ARN through core.harness.openHarnessShell, never the backing Runtime ARN. Use the existing cached SDK data client's endpoint/credentials/signing configuration.
• Reuse the SDK ShellSession for framing, reconnect, keepalive, writes, resize, and close. The high-level Runtime SDK helper does not accept Harness ARNs.
• Match the Runtime SDK's SigV4 handshake without requesting a subprotocol; keep the JWT bearer subprotocols unchanged. The live smoke caught the unnecessary SigV4 protocol request, and the existing signing assertion was updated before the fix.
• Allow the documented 330-second WebSocket upgrade and wait separately for the initial STATUS before handing over the terminal, including when initialization exceeds the SDK's fixed metadata wait.
• Share terminal handoff, exit handling, cleanup, and reconnect messages with Runtime shell. Retain connection failures in the TUI with retry/back/quit, and allow the Runtime consumer to supply its HTTP 400 hint. Add the Harness-detail action and generated command reference.
• Declare the already-locked ws and @types/ws packages directly. No package versions change.

Tests focus on the Harness-specific connection/CLI boundaries and extend existing menu/detail coverage. Existing Runtime/terminal tests cover shared behavior, including the retained error, Runtime hint, retry, endpoint back navigation, and a subsequent successful attempt.

Related Issue

Paired with #2544. CLI v1 feedback, item 20; no separate GitHub issue supplied.

Documentation PR

Included: generated command.md section for harness shell; unrelated pre-existing reference drift is excluded.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

• I ran bun test
• I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run build
• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them (not applicable)

Results:

• Rebased onto refactor (133fb626); range-diff confirms all eight commits retain identical patches.
• Focused Harness/Runtime-shell tests: 216 pass; focused new connection/command/menu tests: 111 pass.
• Typecheck, lint, formatting, secrets scan, and git diff --check: pass.
• Frozen-lockfile installation: pass, no installed package changes.
• npm bundle, Linux native binary, and harness shell --help from both distributions: pass.
• Full bun test after rebasing, outside the restricted sandbox: 3,990 pass, 0 fail.
• Connection tests exercise the real SDK ShellSession over an in-memory WebSocket boundary: signing/ARN/qualifier/session mapping, JWT subprotocols, delayed readiness, initialization failure/timeout cleanup, provisioning/server retries, and unchanged authorization rejection.
• Live smokes below were run before the patch-identical rebase.
• Live AWS smoke with --profile deploy against an existing demo harness: the Node bundle connected through the Harness ARN, a marker command returned the expected output, and exit closed the shell with code 0.
• Live Linux-native TUI smoke: the endpoint picker preserved the supplied --session-id, the shell connected and ran a second marker command, and closing it with code 0 returned to the endpoint picker.
• No infrastructure was created or updated. The deployment E2E suite was not run; the manual existing-Harness flows above cover this command's live transport and terminal handoff. JWT and reconnect edge cases are covered by unit tests, not claimed as live validation.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published (no SDK/service changes required; paired diagnostic is fix(runtime): explain harness-managed shell rejections #2544)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice refactor pulling ShellOperation and ShellHandoff out of the Runtime shell path so Harness can reuse them, and the new src/core/harnessShell.ts with its retry/initialization-wait logic is well covered by harnessShell.test.ts. Validation in request.ts (readiness, ARN shape, CUSTOM_JWT vs IAM authorizer vs --bearer-token) is thorough, and the screen navigation (preselected harness → endpoint picker, returnOnEscape from the detail hub) is backed by tests. Didn't find anything that requires changes before merging.

One thing worth double-checking (not blocking): in createHarnessShellOpener's _wsFactory, every connection reassigns currentReadiness and attaches a .then(..., (err) => { initializationFailed(err); void session.close(); }). After the initial openShell has returned, initializationFailed on the already-resolved promise is a no-op, but the session.close() still fires if a reconnect fails its initialization handshake — effectively tearing the whole session down on any reconnect-time init failure. If that's intentional (fail-fast on reconnect init), great; if the SDK is expected to retry reconnects internally, this will short-circuit them. Worth confirming against the SDK's reconnect semantics, but not blocking.

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.33024% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.41%. Comparing base (133fb62) to head (750af9f).

Files with missing lines	Patch %	Lines
src/handlers/harness/shell/request.ts	90.62%	3 Missing ⚠️
src/components/ShellHandoff.tsx	97.05%	2 Missing ⚠️
src/core/harnessShell.ts	99.02%	2 Missing ⚠️
src/handlers/harness/shell/operation.ts	95.23%	1 Missing ⚠️
src/handlers/harness/shell/screen.tsx	98.24%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2548      +/-   ##
============================================
+ Coverage     97.39%   97.41%   +0.01%     
============================================
  Files           642      651       +9     
  Lines         46910    47346     +436     
============================================
+ Hits          45689    46120     +431     
- Misses         1221     1226       +5     

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