feat: add observability abstractions and wire to runtime

[nborges-aws]

Description

This PR adds reusable observability infrastructure. The setup is built to apply generally across our primitives, while allowing for resource-specific customization where necessary. This PR wires runtime to the infrastructure. Remaining primitives wiring will be released as a follow pending alignment on the abstractions added here.

• Adds a reusable, logs-only ObservabilityClient as the shared API entry point
• Adds a source resolver registry, with runtime-specific log-group resolution
• Adds a primitive-agnostic CloudWatch source reader for search and live tail
• Adds a shared observability handler factory and mounts logs under Runtime
• Normalizes provider events into a generic LogRecord

Architecture

Runtime handler → ObservabilityClient → RuntimeSourceResolver → CloudWatchSourceReader → LogRecord

The resolver owns resource-to-log-group translation. The source reader owns CloudWatch mechanics without ever needing knowledge of our resource types. The client is responsible for the orchestration of these layers.

Commands

Tail logs:

agentcore runtime logs --id <runtime-id> --tail

Search logs:

agentcore runtime logs \
    --id <runtime-id> \
    --since 1h \
    --until now \
    --level error \
    --query '"timed out"' \
    --limit 100

--qualifier selects a non-default Runtime endpoint.

Type of Change

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

Testing

How have you tested the change?

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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.33%. Comparing base (3d449c5) to head (b5e008a).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2147      +/-   ##
============================================
+ Coverage     97.29%   97.33%   +0.03%     
============================================
  Files           479      486       +7     
  Lines         29673    30066     +393     
============================================
+ Hits          28871    29264     +393     
  Misses          802      802              

☔ 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, well-factored change. The ObservabilityClient / SourceReader split cleanly separates identity resolution from CloudWatch I/O and leaves an obvious extension point for future resource kinds. A few things I looked at carefully:

• AWS SDK mocking: sourceReader.test.ts and client.test.ts mock at the SDK client boundary (send) rather than the pieces of internal state, which matches the guidance in the review criteria. No excessive mocking.
• Pagination + limit: CloudWatchSourceReader.searchLogs correctly caps the per-page limit at query.limit - yielded, terminates when nextToken === requestToken, and short-circuits on limit <= 0. Edge cases (limit=1, single page, empty page with token) all look right.
• Live Tail: tailLogs handles both the in-band SessionTimeoutException event and the thrown variant, reconnects only when timed out, and exits cleanly on abort. Legacy arn:...:* suffix stripping is guarded and covered.
• Missing log group: nice consistent ResourceNotFoundError translation with actionable message in both search and tail paths (including the pre-flight DescribeLogGroups case for tail).
• Handler wiring: input validation (--tail vs --since/--until, --limit outside search mode, --since > --until) all raise typed InputValidationErrors and are covered in tests. withUserCancellation propagates the abort into the SDK calls.
• Telemetry: this codebase currently instruments telemetry at the top-level command run in src/index.ts rather than per-handler, so no per-feature instrumentation is missing here.

Non-blocking observations if you want to iterate later:

• --tail is effectively a no-op flag when neither --since nor --until is passed (tailing is already the default in that case). Consider either making search the default with --tail required for streaming, or documenting the current behavior in the flag help. Either is fine, just be intentional.
• ResourceFlagValues in handlers/observability/types.ts duplicates the existing FlagsOf in router/handler.tsx. Could reuse or export the router one to keep a single source of truth.
• The log group naming convention /aws/bedrock-agentcore/runtimes/<id>-<qualifier> is hard-coded; if the service ever exposes this via an API, worth switching to that to avoid a lurking coupling.

Nothing here blocks merge. Ship it.

[AlexanderRichey]

There is some good stuff here but I think we can simplify a bit. I like the idea of creating a function that creates these handlers for us, but I think this can be done with a little less abstraction and more directly. It seems like what you want is something like:

const createLogsHandler = (client: ObservabilityClient, io: AppIO) => createHandler(...)

Then use this for Runtime and Harness:

export function createRuntimeHandler(...): Router {
    ...
    runtime.handler(createLogsHandler(obsC, io))
    ...
}

[AlexanderRichey]

Is this importable from a package somewhere? Is this what all log records look like in AC?

[AlexanderRichey]

Do we really need all of these complex types?

[AlexanderRichey]

Interesting. Did you consider writing a function that returns a handler function? That might be simpler.

[AlexanderRichey]

Any reason we're not using date-fns?

[AlexanderRichey]

What's the upshot of an interface for this?