fix: create global entrypoint for tui

[Hweinstock]

Description

Previously, commands like agentcore add, agentcore deploy, etc. rendered TUI screens inline via direct render() calls. This made it difficult to distinguish CLI vs TUI code paths, and caused telemetry to be mislabeled as mode="cli" even when running interactive TUI flows. Additionally, bare agentcore (no args) never called TelemetryClientAccessor.init() or shutdown(), so telemetry was never emitted for the full-screen TUI.

This PR creates a unified renderTUI() entrypoint with a RenderTUIOptions interface that all TUI-rendering code paths now use. This ensures:

1. Telemetry is correctly initialized with mode="tui" for all TUI sessions
2. TelemetryClientAccessor.shutdown() is always called on TUI exit
3. Consistent behavior (alt screen, exit handling) across all TUI entry points
4. Type-safe route navigation via InitialRoute

Changes

• Add renderTUI() with RenderTUIOptions for configurable behavior
• Migrate add, deploy, create, remove, invoke commands to use renderTUI()
• Add InitialRoute type for type-safe initial route navigation
• Add actionOnBack option to control escape/back behavior (navigate to help vs exit)
• Add enterAltScreen option for inline vs full-screen rendering
• Initialize and shutdown TelemetryClientAccessor within renderTUI()

Related Issue

Fixes #895

Documentation PR

N/A

Type of Change

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

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

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

---

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

[github-actions]

Package Tarball

aws-agentcore-0.14.2.tgz

How to install

gh release download pr-1350-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.14.2.tgz

[agentcore-devx-automation]

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

[agentcore-cli-automation]

Looks good — small, targeted fix that correctly addresses both stated issues:

1. TelemetryClientAccessor.init('tui', 'tui') is now called before renderTUI(), so the bare-agentcore invocation gets tagged with mode=tui instead of falling back to the lazy mode=cli default.
2. TelemetryClientAccessor.shutdown() is now invoked from the waitUntilExit().then(...) handler, so the OTLP exporter gets a chance to flush buffered metrics before process exit.

I verified the init signature (init(entrypoint, mode)) — both args being 'tui' is correct. Ink's default Ctrl+C handling unmounts cleanly and resolves waitUntilExit(), so the new shutdown() also runs on the common Ctrl+C-from-TUI exit path. Browser-dev exit action doesn't emit telemetry, so calling shutdown() before launchBrowserDev() is fine for now.

No new issues worth blocking on.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	44.3%	9531 / 21512
🔵	Statements	43.54%	10114 / 23225
🔵	Functions	41.01%	1655 / 4035
🔵	Branches	40.84%	6162 / 15086

Generated in workflow #3228 for commit 36beb61 by the Vitest Coverage Report Action

[agentcore-devx-automation]

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