fix(dev): support multiple A2A runtime ports

[notgitika]

Summary

• Allocate A2A development ports from 9000 + runtime index, while honoring an explicit --port for the selected runtime.
• Apply the same port resolution across direct logs mode, terminal UI, web UI, and prompt invocation.
• Map each container's unique host port to its internal A2A port and advertise the reachable host URL in the agent card.
• Pass PORT and AGENTCORE_RUNTIME_URL to CodeZip A2A processes.
• Keep MCP on its framework-required fixed port and retain existing explicit-port conflict behavior.

Closes #1657.

SDK dependency

Container A2A runtimes work independently because each container still binds internally to 9000. CodeZip A2A runtimes require aws/bedrock-agentcore-sdk-python#593 so serve_a2a honors the CLI-provided PORT; that PR is stacked on the A2A v1 migration in aws/bedrock-agentcore-sdk-python#591.

Agent Inspector requires no change: it routes start, invocation, and agent-card requests through the CLI backend by agent name, and the backend stores each runtime's resolved port.

Testing

• npm run build
• npm test (415 files, 5,980 tests passed)
• npm run typecheck
• npm run lint -- --no-cache (no errors; existing warnings only)
• Focused dev-port suite (74 tests passed)
• Prettier and pre-commit checks

[github-actions]

Package Tarball

aws-agentcore-0.24.1.tgz

How to install

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

[agentcore-devx-automation]

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	40.32%	15056 / 37335
🔵	Statements	39.58%	16048 / 40537
🔵	Functions	34.43%	2568 / 7458
🔵	Branches	33.76%	10030 / 29708

Generated in workflow #4191 for commit 1e2e21c by the Vitest Coverage Report Action

[agentcore-cli-automation]

LGTM. The port allocation change is well-structured and consistent across the four entry points (CLI --logs, TUI hook, web-UI handleStart, and invoke). A few observations from the review, none blocking:

• Container A2A works standalone (the 9001:9000 port mapping is done at the Docker layer), but CodeZip A2A depends on aws/bedrock-agentcore-sdk-python#593 to actually honor PORT. Worth double-checking that PR merges before/with this one is released widely, otherwise users on the current SDK will see the CLI report port 9001 while the server still binds to 9000.
• The invoke flow now recomputes getDevPort on the client side and uses that to reach the server. If a server auto-shifted off the index-derived port (e.g., 9001 was taken → bound to 9002), invoke against the second A2A runtime will fail the same way it does for HTTP today. Pre-existing behavior for HTTP, but new for A2A. Not blocking.
• getDevPort tests only cover A2A and MCP; a couple of HTTP / null-project cases would round it out, but getAgentPort already has that coverage so it's fine.

No new telemetry needed — agent_protocol is already recorded on the existing cli.command_run emissions. Tests reuse the established spawn/fs mocks at true I/O boundaries. Approving.

[jariy17]

Pretty good just need some changes.

[jariy17]

Now, A2A startup could shift from 9000 to 9001. A later agentcore dev --runtime "" recomputes the original port and still targets 9000. That can fail or send the prompt to the wrong local process. Can we still fail fast?

[jariy17]

with one A2A runtime, agentcore dev --port 9100 falls through here and uses 9000. browser mode only sets selectedAgent when --runtime is provided, even though the only runtime is implicitly selected.

can we default selectedAgent to the sole supported runtime?

  selectedAgent:
    agentName ?? (supportedAgents.length === 1 ? supportedAgents[0]?.name : undefined)

[jariy17]

ctx.options.agents contains only dev-supported agents, but getDevPort() calculates the offset from the full project.runtimes list. if an unsupported runtime appears before an A2A runtime, browser mode assigns 9000 while terminal mode assigns 9001.

Can we carry the original runtime index into AgentInfo or reuse the shared port resolver here? we should also add a test with an unsupported runtime before the A2A runtime.