feat!: Add per-execution runId, at-most-once tracking, and cross-process tracker resumption

[jsonbailey]

Summary

• Each tracker now carries a runId (UUIDv4) included in all emitted events, scoping every metric to a single execution
• At-most-once semantics enforce that trackDuration, trackTokens, trackSuccess/trackError, trackFeedback, and trackTimeToFirstToken can only fire once per tracker instance; subsequent calls are dropped with a warning
• tracker property on config objects replaced by a createTracker() factory — each call returns a new tracker with a fresh runId, making repeated invoke() / evaluate() calls fully independent
• TrackedChat and Judge call createTracker() internally at the start of each invocation rather than holding a shared tracker
• resumptionToken getter on the tracker encodes runId, configKey, variationKey, and version as URL-safe Base64 JSON, enabling cross-process event correlation
• LDAIConfigTrackerImpl.fromResumptionToken() and LDAIClient.createTracker() reconstruct a tracker from a token with the original runId preserved — useful for associating deferred user feedback with the originating execution

Breaking changes

• tracker property removed from all config types; replaced by createTracker?: () => LDAIConfigTracker
• TrackedChat and Judge constructors no longer accept a tracker argument
• getTracker() removed from both TrackedChat and Judge
• getTrackData() return type now includes runId: string as the first field

Test plan

• yarn workspace @launchdarkly/server-sdk-ai test — all 110 tests pass
• yarn workspace @launchdarkly/server-sdk-ai lint — no lint errors
• Verify resumptionToken round-trips correctly through fromResumptionToken
• Verify duplicate metric calls on the same tracker produce warnings and are dropped

🤖 Generated with Claude Code

---

Note

Medium Risk
Breaking API change replaces tracker with createTracker() and changes how metrics are emitted; incorrect adoption could drop or misattribute analytics events. Adds new runId/resumption-token parsing and at-most-once guards that may affect existing metric call patterns.

Overview
Refactors AI config tracking to be per-execution. Config objects no longer expose a shared tracker; they now provide createTracker() which returns a fresh tracker (new runId) each invocation, and TrackedChat/Judge construct a tracker internally at the start of invoke()/evaluate().

Adds run correlation and tracker resumption. LDAIConfigTracker now includes runId in getTrackData(), LDAIConfigTrackerImpl can emit/parse a URL-safe Base64 resumptionToken, and LDAIClientImpl adds createTracker(token, context) to reconstruct a tracker for deferred tracking across processes.

Enforces at-most-once metric emission per tracker instance. Duplicate calls to trackDuration, trackTokens, trackSuccess/trackError, trackFeedback, and trackTimeToFirstToken are dropped with warnings. Tests and examples are updated to the new createTracker() flow and constructor signatures (removing getTracker() and tracker constructor args).

^{Reviewed by Cursor Bugbot for commit e2b5362. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25623 bytes
Compressed size limit: 29000
Uncompressed size: 125843 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 31655 bytes
Compressed size limit: 34000
Uncompressed size: 112792 bytes

[github-actions]

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 179375 bytes
Compressed size limit: 200000
Uncompressed size: 829982 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 37169 bytes
Compressed size limit: 38000
Uncompressed size: 204305 bytes

[andrewklatzke]

Had one question but overall LGTM