feat: add project aware trace support for runtime

[nborges-aws]

Description

Adds project-aware runtime traces through agentcore project traces runtime list|get. The commands resolve a runtime and target to its physical id and region, thendelegates to the existing shared observability trace handlers.

This PR builds on the project observability setup introduced in PR #2271. Also adds tests exercising routing and updates the readMe with project trace examples.

agentcore project traces runtime list
agentcore project traces runtime list --name FooRuntime --target production --since 30m
agentcore project traces runtime get <traceId> --name FooRuntime --output trace.json

Type of Change

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

Testing

How have you tested the change?

Manual testing, plus added tests exercising runtime resolution, explicit target/qualifier selection, and region propagation.

• bun run test (3170 pass, 0 fail)
• 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.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice, focused addition that mirrors the existing project log runtime handler almost exactly.

• Reuses createListTracesHandler / createGetTraceHandler and the shared runtimeLogGroup / DEFAULT_ENDPOINT_QUALIFIER helpers so behavior stays consistent with runtime traces.
• resolveProjectRuntime correctly pins the region from deployed.target.region (rather than trusting the backend echo) — matches the note in ProjectManager.resolveDeployedResource.
• Command path (/agentcore/project/traces/runtime/{list,get}) satisfies the telemetry commandPathSchema, so cli.command_run events emitted by the router will still validate — no extra telemetry wiring needed.
• Tests use tmpdir + a real ProjectSpecSchema-parsed project and only stub at the true boundaries (ProjectBackend, core.observability), which matches the workspace guidance on mocking.
• README tree and examples are updated to match the new subcommand.

Minor consistency observation (non-blocking): the imperative runtime traces router is built via createTracesHandler({ description, list, get }), while createProjectRuntimeTracesHandler constructs new Router("runtime", ...).handler(list).handler(get) inline. Functionally equivalent, but you could route through createTracesHandler for symmetry with runtime/traces/index.tsx.

Nothing here needs to change before merge.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.03%. Comparing base (53f13f6) to head (1d92497).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2273   +/-   ##
=========================================
  Coverage     97.03%   97.03%           
=========================================
  Files           580      583    +3     
  Lines         39630    39688   +58     
=========================================
+ Hits          38453    38511   +58     
  Misses         1177     1177           

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

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)