feat(project): support local Runtime invocation

[aidandaly24]

Summary

• add --local and --port to agentcore project invoke runtime
• invoke an already-running headless project dev server through 127.0.0.1:<port>/invocations
• bypass project resource selection, deployment targets, CloudFormation, and Runtime lookup for local invocations
• preserve the existing streaming, JSON, binary, and output-file response handling
• reject deployed-only request options and report an actionable error when the local server is unavailable

Testing

• bun test src/handlers/project/invoke/index.test.tsx (8 passed)
• bun test (2962 passed)
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run build
• manually created an agent-python project and invoked its real headless project dev server successfully on the default port 8080
• repeated the manual invocation with explicit --port 8081

Notes

• --local is intentionally headless and requires --payload
• the existing bare deployed Runtime invoke TUI remains unchanged

[agentcore-devx-automation]

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

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Solid change. The new local-invoke path is a self-contained branch in the existing runtime invoke handler with the right guardrails:

• Validates that --port requires --local, and that all deployed-runtime-only flags are rejected with a specific --<flag> cannot be used with --local error.
• Preserves the existing --payload requirement (with correct ExitCode.USAGE) and the --json + --output-file mutual-exclusion.
• The --target change from .default("default") to .optional() with a ?? "default" fallback at the resolve site is behaviorally equivalent for the deployed path.
• z.boolean() on --local correctly defaults to false (confirmed in router tests), and adding "local" to the hasHeadlessOnlyFlag exclusion list prevents the boolean's false value from being treated as a headless-only signal in the TUI branch.
• invokeLocalRuntime uses redirect: "manual", honors AbortSignal (rethrowing signal.reason on aborts), and converts fetch failures into a helpful InvalidEnvironmentError that points users at agentcore project dev.
• Non-2xx responses are surfaced via RuntimeInvokeResponseError after the body is written, which is a reasonable UX for local debugging (differs from the deployed path that discards the body on non-ok, but that's a deliberate trade-off).

Test coverage exercises the happy path and the server-down path against a real startHttpServer — no excessive mocking. The console.error spy is needed because runWithExitCode writes directly to console.error rather than injected IO.

No new telemetry needed; the invoke handlers don't instrument per-invocation and telemetry is captured at the router/command-path level.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.49624% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (97d3d9a) to head (83dd3ae).

Files with missing lines	Patch %	Lines
src/core/dev/localInvoke.ts	98.24%	1 Missing ⚠️
src/handlers/project/invoke/runtime.tsx	98.68%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           refactor    #2209    +/-   ##
==========================================
  Coverage     97.07%   97.08%            
==========================================
  Files           544      545     +1     
  Lines         37866    37994   +128     
==========================================
+ Hits          36760    36886   +126     
- Misses         1106     1108     +2     

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

[tejaskash]

A few things worth actioning, mostly around parity between --local and the deployed invoke path. Details inline.

[agentcore-devx-automation]

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