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

[jsonbailey]

BEGIN_COMMIT_OVERRIDE
feat!: Add per-execution runId, at-most-once tracking, and cross-process tracker resumption
feat!: Replace tracker tuple from completion_config with AIConfig#create_tracker factory
feat!: Track each AIConfigTracker metric at most once per tracker
feat: Add per-execution runId to correlate AIConfigTracker events
feat: Add Client#create_tracker(token:, context:) to resume a tracker across processes
END_COMMIT_OVERRIDE

Summary

• Per-execution runId: Every tracker event now includes a unique runId (UUID v4) for billing isolation and deduplication
• At-most-once semantics: Each metric type (duration, tokens, success/error, feedback, TTFT) can only be tracked once per tracker instance; subsequent calls are dropped with a warning
• AIConfig#create_tracker factory: The completion config object returned by Client#completion_config exposes a create_tracker method that returns a fresh AIConfigTracker with a new runId on each call, replacing the old single-tracker pattern. The SDK always supplies a working tracker factory, even for disabled flag evaluations.
• AIConfigDefault / AIConfig are independent classes: AIConfigDefault is the application-supplied fallback type (passed as default: to Client#completion_config); AIConfig is the SDK-returned type that carries a tracker factory. Direct construction of AIConfig is not supported.
• Resumption token: AIConfigTracker#resumption_token returns a URL-safe Base64-encoded JSON token ({ runId, configKey, variationKey, version }) for cross-process tracker reconstruction
• Client#create_tracker(token:, context:): Reconstructs a tracker from a resumption token for deferred tracking (e.g. feedback from a different process). modelName and providerName are set to empty strings on reconstruction.
• base64 gem dependency: Added as a runtime dependency (removed from Ruby 3.4 default gems)

Test plan

• AIConfig#create_tracker returns new tracker instances with distinct runIds
• AIConfig#create_tracker preserves flag metadata (configKey, variationKey, version, modelName, providerName)
• AIConfigDefault.disabled returns a disabled fallback config
• AIConfig is not a subclass of AIConfigDefault and does not expose a disabled class method
• AIConfig.new requires a tracker_factory: keyword argument
• Trackers from the same config have independent at-most-once tracking state
• resumption_token encodes exactly { runId, configKey, variationKey, version } (no modelName/providerName)
• from_resumption_token round-trips correctly and sets modelName/providerName to ""
• Restored tracker can send track events with the original runId
• Client#create_tracker round-trips through resumption token
• All 57 tests pass (0 failures)

🤖 Generated with Claude Code

---

Note

High Risk
High risk because it changes the public tracking API (AIConfig/default handling) and modifies emitted analytics event payloads by introducing per-run runId and at-most-once semantics, which could affect downstream metrics/billing expectations.

Overview
Introduces per-execution tracking by minting a UUIDv4 runId for each AI run and attaching it to all tracker events, with a new AIConfig#create_tracker factory replacing the previous single-tracker pattern.

Adds at-most-once semantics to AIConfigTracker metric methods (duration, TTFT, tokens, success/error, feedback), dropping subsequent calls with warnings, and implements cross-process tracker resumption via AIConfigTracker#resumption_token plus Client#create_tracker(token:, context:).

Splits fallback vs returned config types by adding AIConfigDefault for completion_config(default:), removes AIConfig.disabled, updates examples/tests accordingly, and adds a runtime base64 dependency.

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

[cursor]

Cursor Bugbot has reviewed your changes using default mode and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 822734b. Configure here.}