[hsadhvani]

Why

LaunchDarkly can now attach Shadow Requests to an AI Config's targeting rules and fallthrough, and delivers them inside the served variation as shadowConfiguration (AIC-3429). The SDK needs to run them: while serving variation A, also run variation B in the background on the same input and report B on the normal AI metrics, so customers can compare models on real traffic. This is the TypeScript counterpart of launchdarkly/python-ai-sdk#241, experimental and opt in until the UI ships.

Summary

New exports from @launchdarkly/ai-server/experimental (and so @launchdarkly/ai-node/experimental): enableShadowRequests({ timeoutMs, onTask }), disableShadowRequests(), runShadow(), and the types ShadowTask, ShadowResult and EnableShadowRequestsOptions. Selection, sampling (same bucket as Python), stripping and event fields match the Python SDK. ShadowTask is plain data, so it survives structuredClone and JSON for apps that run shadows on their own queue.

Core changes, none naming the feature (spec §0.3):

• A generic invocation hook registry (invocation-hooks.ts), run by config().invoke() and .stream() before the handler.
• extractVariation calls variationDetail() only while a hook is registered and the client has it, so apps that never enable this keep calling variation(). LDClientInterface gains an optional variationDetail.
• executeAndTrack / executeAndStream / makeRunTrackData take optional runId, extraTrackData and spanAttributes. This shows in the root API report.

Spec: TESTING.md §9 and A.22 in ai-sdks-monorepo (launchdarkly/ai-sdks-monorepo#114). Draft until the Shadow Testing UI is ready.

BEGIN_COMMIT_OVERRIDE
feat(shadow-requests): run Shadow Requests from the experimental entry point
feat(client): add invocation hooks and runId, extraTrackData and spanAttributes options to executeAndTrack
END_COMMIT_OVERRIDE

Testing approaches

• Added tests for selecting shadows by reason, end time, missing variations and missing handlers
• Added tests for sticky sampling, its rate and parity with the Python bucket
• Added tests that a failing or timed out shadow never reaches the caller and records an error
• Added tests for deferred mode, serializable tasks and matching events between modes
• Added tests for shadow event fields, unchanged real events and shadow span attributes
• Added tests for the invocation hook registry and the experimental export list

Feature flags

N/A. Off unless the app calls enableShadowRequests(); LaunchDarkly only sends shadows while enable-shadow-requests is on.