feat: add traces to observability client and wire to runtime handlers

[nborges-aws]

Description

Add trace logic in shared observability abstraction established for logging, and wire runtime handlers to use it.

• adds generic listTraces and getTrace operations
• moves trace query construction, validation, and normalization into core observability
• adds reusable trace list/get handlers for time windows, table/JSON output, cancellation, and file writing
• write downloaded traces atomically
• updates the test Core client and coverage for the shared APIs and Runtime wiring
• add logic to warn user of truncation when selected time windows exceeds TRACE_RECORD_LIMIT

Note: --id flag has become required when using observability commands. This is intentional. Previous logic mixed project resolution with imperative command, which is why id was supported as optional.

Type of Change

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

Testing

How have you tested the change?

• bun run test (2788 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.

[agentcore-devx-automation]

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.95817% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (b57f237) to head (4fa3550).

Files with missing lines	Patch %	Lines
src/handlers/observability/traces.ts	96.52%	5 Missing ⚠️
src/core/observability/traces.ts	95.08%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2180      +/-   ##
============================================
- Coverage     97.15%   97.08%   -0.07%     
============================================
  Files           542      544       +2     
  Lines         37740    37768      +28     
============================================
+ Hits          36665    36666       +1     
- Misses         1075     1102      +27     

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

AgentCore Harness Review

Verdict: Looks good

Nice consolidation of trace logic into the shared observability layer, mirroring the earlier runtime logs refactor. Tests use real temp dirs (good), and telemetry is handled at the router layer so no per-handler instrumentation is needed.

A couple of behavior changes to runtime traces that are worth an explicit callout in the PR description (or a confirmation that they’re intentional) — they’re not necessarily wrong, but they aren’t mentioned in the PR body:

1. --id is now required for both runtime traces list and runtime traces get. Previously it was runtimeIdSchema.optional() with a "defaults to the project's deployed runtime" fallback via resolveRuntimeTarget. The new runtimeFlags in src/handlers/runtime/traces/{list,get}/index.tsx drops that path. This matches what runtime logs did in #2169, so probably intentional — just want to confirm.

2. get default output path changed from agentcore/.cli/traces/<runtimeId>-<traceId>.json (when inside a project) to <traceId>.json in the cwd, always. The deleted src/handlers/runtime/traces/get/outputPath.ts used to be project-aware and prefixed the filename with the runtime id so per-runtime downloads didn’t collide. The new src/handlers/runtime/traces/outputPath.ts and the outputDescription in get/index.tsx unconditionally drop into cwd with just <traceId>.json. If a user in a project pulls the same trace id from two different runtimes back-to-back they’ll now overwrite. If this is deliberate (and not a regression from the shared-abstraction simplification) it’d be worth calling out — the PR body only mentions the atomic write.

Minor, non-blocking:

• In src/handlers/observability/traces.ts, getTraceFlags (line 52) is defined only so its typeof can produce GetTraceFlagValues; createGetTraceHandler then reconstructs the same flag list inline at lines 151–155. It works, but the two definitions can drift. Either derive the runtime getFlags from getTraceFlags ([...config.flags, ...getTraceFlags]) or drop the top-level constant and type the values structurally — reviewer’s choice.

Everything else (validation in listTracesInsightsQuery/getTraceInsightsQuery, the TRACE_RECORD_LIMIT warning path, atomicWrite for the JSON dump, and the TestObservabilityClient shape) looks solid. Happy to see this merge once the behavior changes above are acknowledged.

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

[jariy17]

nit: SessionIds are custom attributes for traces. So don't expect every trace to have a sessionId attribute. This should be fine for agents' traces but I'm not sure for gateway and etc.

[agentcore-devx-automation]

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

[agentcore-devx-automation]

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