feat(telemetry): add OpenTelemetry-compatible instrumentation hooks

[collinsezedike]

Summary

• Add a minimal, pluggable Tracer/Span interface (src/telemetry.ts) plus setTracer()/getTracer(), exported from the package root. Zero runtime dependency on @opentelemetry/* or any tracing library — every instrumented call site defaults to a no-op tracer until setTracer() is called.
• Instrument the hot paths named in the issue:
  • deriveStealthKeys() / deriveStealthKeysFromSigner() (stellar.deriveStealthKeys)
  • scanAnnouncementsStream() — one stellar.scan span per call with aggregate counts, plus a stellar.scan.match span per (comparatively rare) match, deliberately not per-candidate to avoid dwarfing scan cost with span overhead
  • RpcClient.request() (stellar.rpc.request, covering internal retries/failover)
  • Every ClaudeAgentTools method (agent.tool.*)
• Every instrumented function accepts a tracer option that overrides the global tracer for that one call.
• Along the way, found and fixed a real gap: scanAnnouncementsStream was never exported from the public @wraith-protocol/sdk/chains/stellar entry point (only reachable via a relative import) — needed to make its new tracer option actually usable.
• docs/observability.md documents every instrumented span and its stable attribute names.
• examples/otel/ ships a reference adapter targeting @opentelemetry/api's Tracer/Span shape. It's written against local structural types (not an import of @opentelemetry/api), so it has no dependency on the package — a real OTel tracer already satisfies the shape. A tiny console-based stand-in tracer lets the example run standalone end-to-end (key derivation → stealth address generation → scan) without installing any tracing library. Added to the Examples CI matrix.

Closes #177.

Semver

Additive-only: new src/telemetry.ts module and root exports (setTracer, getTracer, withSpan, NOOP_TRACER, Tracer, Span), new optional tracer/opts parameters on existing functions (all optional, existing call sites unaffected), and scanAnnouncementsStream becoming a public export it previously wasn't. No existing signature or behavior changes.

Test plan

• pnpm build and pnpm test — full suite passes (1136 tests, 0 failures)
• New test/telemetry.test.ts — Tracer/Span/setTracer/getTracer/withSpan unit coverage (no-op default, sync/async success and failure paths, per-call override, attribute mutation)
• New test/bench/telemetry.bench.ts — no-op tracer overhead vs. uninstrumented call
• Telemetry coverage added to each existing test file for the instrumented call sites: test/chains/stellar/keys.test.ts, test/chains/stellar/scan.test.ts, test/chains/stellar/rpc.test.ts, test/agent/tools.test.ts — span emission, per-call override precedence, global tracer fallback
• pnpm-lock.yaml diff is scoped to exactly the new examples/otel workspace importer (verified against the pinned [email protected])
• pnpm format:check

Note on CI

The Examples CI type-check step for otel (like all CLI-style examples) runs with continue-on-error: true, matching the existing convention for examples that lag the SDK API slightly — non-blocking either way.

[drips-wave]

@collinsezedike Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[truthixify]

Thanks @collinsezedike. test (20) and test (22) fail on pnpm api:check rather than on a test:

Warning: You have changed the API signature for this project.
Please copy the file "temp/sdk.api.md" to "etc/sdk.api.md"

Exporting the Tracer and setTracer surface changes the public API, so the api-extractor baseline needs regenerating:

pnpm build
git add etc/
git commit -m "chore: refresh api-extractor baseline"
git push

Everything else is green, including all the examples jobs, so that single commit should clear it. This gate has now caught five PRs across two waves, so it is us, not you. I am going to make it print the fix command directly.