@reproapp/node-sdk 0.0.37 → 0.0.39

package/src/index.ts

@@ -323,6 +323,9 @@ const KAFKA_HEADER_SESSION_ID = 'x-bug-session-id';
 const KAFKA_HEADER_ACTION_ID = 'x-bug-action-id';
 const DEFAULT_INGEST_BASE = 'http://localhost:8080';
 const DEFAULT_INGEST_PATH = '/v1/ingest/events';
+const DEFAULT_LIVE_SESSION_DURATION_MS = 3 * 60_000;
+const DEFAULT_LIVE_SEGMENT_IDLE_MS = 15_000;
+const DEFAULT_LIVE_SEGMENT_DURATION_MS = DEFAULT_LIVE_SESSION_DURATION_MS;
 
 function escapeRx(s: string) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 let __TRACER__: TracerApi | null = null;
@@ -2078,6 +2081,397 @@ function toIngestConfig(cfg: IngestClientConfig): IngestClientConfig {
     };
 }
 
+function normalizeLiveModeConfig(cfg: ReproMiddlewareConfig): ReproLiveModeConfig | null {
+    const liveMode = cfg.liveMode;
+    if (liveMode === true) {
+        return { enabled: true };
+    }
+    if (!liveMode || typeof liveMode !== 'object') {
+        return null;
+    }
+    if (liveMode.enabled === false) {
+        return null;
+    }
+    return liveMode;
+}
+
+type BackendLiveTimingConfig = {
+    sessionMaxDurationMs: number;
+    segmentMaxDurationMs: number;
+    segmentIdleMs: number;
+};
+
+let backendLiveTimingOverrideForTest: Partial<BackendLiveTimingConfig> | null = null;
+
+function positiveInternalDuration(value: unknown, fallback: number): number {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+    return Math.max(1, Math.trunc(numeric));
+}
+
+function getBackendLiveTiming(): BackendLiveTimingConfig {
+    return {
+        sessionMaxDurationMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.sessionMaxDurationMs,
+            DEFAULT_LIVE_SESSION_DURATION_MS,
+        ),
+        segmentMaxDurationMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.segmentMaxDurationMs,
+            DEFAULT_LIVE_SEGMENT_DURATION_MS,
+        ),
+        segmentIdleMs: positiveInternalDuration(
+            backendLiveTimingOverrideForTest?.segmentIdleMs,
+            DEFAULT_LIVE_SEGMENT_IDLE_MS,
+        ),
+    };
+}
+
+function normalizeLiveActorId(value: unknown): string | null {
+    if (value === undefined || value === null) return null;
+    const normalized = String(value).trim();
+    return normalized.length ? normalized : null;
+}
+
+function normalizeLiveActorLabels(
+    value: Record<string, string | number | boolean | null | undefined> | null | undefined,
+): Record<string, string> | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const labels: Record<string, string> = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        const normalizedKey = key.trim();
+        if (!normalizedKey || rawValue === undefined || rawValue === null) continue;
+        const normalizedValue = String(rawValue).trim();
+        if (normalizedValue) labels[normalizedKey] = normalizedValue;
+    }
+    return Object.keys(labels).length ? labels : undefined;
+}
+
+function newSessionId(base: number = Date.now()): string {
+    return `S_${Math.max(0, Math.trunc(base))}_${randomUUID().slice(0, 8)}`;
+}
+
+function newActionId(base: number = Date.now()): string {
+    return `A_${Math.max(0, Math.trunc(base))}_${randomUUID().slice(0, 8)}`;
+}
+
+function resolveLiveApiBase(cfg: ReproMiddlewareConfig, liveMode?: ReproLiveModeConfig | null): string | null {
+    const env = typeof process !== 'undefined' ? (process as any)?.env : undefined;
+    const raw =
+        liveMode?.apiBase ||
+        cfg.apiBase ||
+        env?.REPRO_API_BASE_URL ||
+        env?.REPRO_API_BASE ||
+        (cfg.privacy as RuntimePrivacyConfig | undefined)?.apiBase ||
+        null;
+    if (typeof raw !== 'string' || !raw.trim()) return null;
+    return raw.trim().replace(/\/+$/, '');
+}
+
+function liveApiHeaders(cfg: ReproMiddlewareConfig): Record<string, string> {
+    const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'X-App-Id': cfg.appId,
+    };
+    if (cfg.appSecret) {
+        headers['X-App-Secret'] = cfg.appSecret;
+    }
+    if (cfg.appName) {
+        headers['X-App-Name'] = cfg.appName;
+    }
+    return headers;
+}
+
+async function postLiveApi(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    path: string,
+    body: Record<string, any>,
+): Promise<void> {
+    await postLiveApiJson(cfg, liveMode, path, body);
+}
+
+async function postLiveApiJson<T = Record<string, any>>(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    path: string,
+    body: Record<string, any>,
+): Promise<T | null> {
+    const apiBase = resolveLiveApiBase(cfg, liveMode);
+    const fetchImpl = (globalThis as any).fetch;
+    if (!apiBase || !cfg.appId || !cfg.appSecret || typeof fetchImpl !== 'function') {
+        return null;
+    }
+    try {
+        const res = await fetchImpl(`${apiBase}${path}`, {
+            method: 'POST',
+            headers: liveApiHeaders(cfg),
+            body: JSON.stringify(body),
+        });
+        if (!res?.ok) {
+            return null;
+        }
+        try {
+            return await res.json();
+        } catch {
+            return null;
+        }
+    } catch {
+        // never break user code
+        return null;
+    }
+}
+
+function enqueueLiveSessionStart(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    payload: Record<string, any>,
+): void {
+    scheduleSdkBackgroundWork(
+        () => postLiveApi(cfg, liveMode, '/v1/live-sessions', payload),
+        { priority: 'high' },
+    );
+}
+
+function enqueueLiveSessionFinish(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    sessionId: string,
+): void {
+    scheduleSdkBackgroundWork(
+        () => postLiveApi(
+            cfg,
+            liveMode,
+            `/v1/live-sessions/${encodeURIComponent(sessionId)}/finish`,
+            { notes: '' },
+        ),
+        { priority: 'high' },
+    );
+}
+
+function emitBackendLiveSessionManifest(
+    cfg: ReproMiddlewareConfig,
+    session: BackendLiveParentSession | BackendLiveChildSession,
+    options: {
+        sessionKind: 'parent' | 'child';
+        actorId: string;
+        actorType: string;
+        actorLabels?: Record<string, string>;
+        parentSessionId?: string | null;
+        previousSessionId?: string | null;
+        closedAt: number;
+    },
+): void {
+    post(cfg, session.sessionId, {
+        entries: [{
+            sessionCaptureManifest: {
+                mode: 'backend-only',
+                captureMode: 'backend-only',
+                sessionKind: options.sessionKind,
+                parentSessionId: options.parentSessionId ?? null,
+                previousSessionId: options.previousSessionId ?? null,
+                actorId: options.actorId,
+                actorType: options.actorType,
+                actorLabels: options.actorLabels,
+                expected: {
+                    frontendActionDoc: 0,
+                    rrwebChunk: 0,
+                    frontendSessionEnd: 0,
+                },
+                closedAt: options.closedAt,
+            },
+            t: options.closedAt,
+        }],
+    }, { priority: 'high' });
+}
+
+function closeBackendLiveParent(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    parent: BackendLiveParentSession,
+    closedAt: number,
+): void {
+    if (parent.closed) {
+        return;
+    }
+    parent.closed = true;
+    if (parent.closeTimer) {
+        try { clearTimeout(parent.closeTimer); } catch {}
+        parent.closeTimer = null;
+    }
+    state.previousParentSessionId = parent.sessionId;
+    if (state.parent === parent) {
+        state.parent = null;
+    }
+    emitBackendLiveSessionManifest(cfg, parent, {
+        sessionKind: 'parent',
+        actorId: parent.actorId,
+        actorType: parent.actorType,
+        actorLabels: parent.actorLabels,
+        previousSessionId: parent.previousSessionId,
+        closedAt,
+    });
+    enqueueLiveSessionFinish(cfg, liveMode, parent.sessionId);
+}
+
+function scheduleBackendLiveParentClose(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    parent: BackendLiveParentSession,
+): void {
+    if (parent.closed) {
+        return;
+    }
+    if (parent.closeTimer) {
+        try { clearTimeout(parent.closeTimer); } catch {}
+        parent.closeTimer = null;
+    }
+
+    const now = Date.now();
+    const activeChild = state.activeChild;
+    const activeChildBelongsToParent =
+        activeChild?.parentSessionId === parent.sessionId;
+    const closeAt =
+        activeChildBelongsToParent && now >= parent.expiresAt
+            ? Math.max(parent.expiresAt, activeChild.closeDeadline, now + 1)
+            : parent.expiresAt;
+
+    parent.closeTimer = setTimeout(() => {
+        parent.closeTimer = null;
+        if (parent.closed || state.parent !== parent) {
+            return;
+        }
+
+        const currentChild = state.activeChild;
+        if (currentChild?.parentSessionId === parent.sessionId) {
+            if (currentChild.requestsInFlight <= 0) {
+                scheduleBackendLiveChildClose(cfg, liveMode, state, currentChild);
+            }
+            scheduleBackendLiveParentClose(cfg, liveMode, state, parent);
+            return;
+        }
+
+        closeBackendLiveParent(cfg, liveMode, state, parent, Date.now());
+    }, Math.max(0, closeAt - now));
+    try { (parent.closeTimer as any).unref?.(); } catch {}
+}
+
+function scheduleBackendLiveChildClose(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    child: BackendLiveChildSession,
+): void {
+    if (child.closeTimer) {
+        try { clearTimeout(child.closeTimer); } catch {}
+        child.closeTimer = null;
+    }
+    const delay = Math.max(0, child.closeDeadline - Date.now());
+    child.closeTimer = setTimeout(() => {
+        child.closeTimer = null;
+        if (child.requestsInFlight > 0 || Date.now() < child.closeDeadline) {
+            scheduleBackendLiveChildClose(cfg, liveMode, state, child);
+            return;
+        }
+        if (state.activeChild === child) {
+            state.activeChild = null;
+        }
+        state.previousChildSessionId = child.sessionId;
+        const closedAt = Date.now();
+        emitBackendLiveSessionManifest(cfg, child, {
+            sessionKind: 'child',
+            actorId: child.actorId,
+            actorType: child.actorType,
+            actorLabels: child.actorLabels,
+            parentSessionId: child.parentSessionId,
+            previousSessionId: child.previousSessionId,
+            closedAt,
+        });
+        enqueueLiveSessionFinish(cfg, liveMode, child.sessionId);
+    }, delay);
+    try { (child.closeTimer as any).unref?.(); } catch {}
+}
+
+function releaseBackendLiveRequest(
+    cfg: ReproMiddlewareConfig,
+    liveMode: ReproLiveModeConfig | null,
+    state: BackendLiveActorState,
+    child: BackendLiveChildSession,
+    finishedAt: number,
+): void {
+    child.requestsInFlight = Math.max(0, child.requestsInFlight - 1);
+    const idleMs = getBackendLiveTiming().segmentIdleMs;
+    child.closeDeadline = Math.max(child.closeDeadline, finishedAt + idleMs);
+    if (child.requestsInFlight <= 0) {
+        scheduleBackendLiveChildClose(cfg, liveMode, state, child);
+    }
+}
+
+async function resolveBackendLiveContext(
+    cfg: ReproMiddlewareConfig,
+    req: Request,
+    requestStart: number,
+): Promise<BackendLiveResolvedContext | null> {
+    const liveMode = normalizeLiveModeConfig(cfg);
+    if (!liveMode?.backendOnly) {
+        return null;
+    }
+
+    const method = String(req.method || 'GET').toUpperCase();
+    if (method === 'OPTIONS' && !hasReproRequestCorrelation(req)) {
+        return null;
+    }
+    const identity = await resolveLiveActorIdentity(cfg, req);
+    if (!identity) {
+        return null;
+    }
+    const { actorId, actorType, actorLabels } = identity;
+
+    const claim = await postLiveApiJson<BackendLiveClaimResponse>(
+        cfg,
+        liveMode,
+        '/v1/live-sessions/claim',
+        {
+            clientTime: requestStart,
+            captureMode: 'backend-only',
+            actorId,
+            actorIds: [actorId],
+            actorType,
+            actorLabels,
+        },
+    );
+    const sid =
+        normalizeLiveActorId(claim?.childSessionId) ??
+        normalizeLiveActorId(claim?.sessionId);
+    if (!sid) {
+        return null;
+    }
+
+    const aid = normalizeLiveActorId(claim?.actionId) ?? newActionId(requestStart);
+    const parentSessionId = normalizeLiveActorId(claim?.parentSessionId) ?? '';
+    const liveChild: BackendLiveChildSession = {
+        sessionId: sid,
+        parentSessionId,
+        previousSessionId: null,
+        actorId,
+        actorType,
+        actorLabels,
+        startedAt: requestStart,
+        expiresAt: requestStart,
+        closeDeadline: requestStart,
+        requestsInFlight: 0,
+        closeTimer: null,
+    };
+
+    return {
+        sid: liveChild.sessionId,
+        aid,
+        requestStart,
+        child: liveChild,
+    };
+}
+
 function resolveIngestUrl(cfg: IngestClientConfig): string {
     const envBase = typeof process !== 'undefined' ? (process as any)?.env?.REPRO_INGEST_BASE : undefined;
     const ingestBase = String(envBase || cfg.ingestBase || DEFAULT_INGEST_BASE).replace(/\/+$/, '');
@@ -2125,6 +2519,24 @@ function readRequestQueryNumber(req: Request, name: string): number | null {
     return Number.isFinite(parsed) ? parsed : null;
 }
 
+function hasReproRequestCorrelation(req: Request): boolean {
+    const headers = req.headers || {};
+    if (
+        hasHttpHeader(headers, KAFKA_HEADER_SESSION_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_ACTION_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_REQUEST_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_TRACE_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_SPAN_ID) ||
+        hasHttpHeader(headers, KAFKA_HEADER_PARENT_SPAN_ID)
+    ) {
+        return true;
+    }
+    return Boolean(
+        readRequestQueryParam(req, REPRO_QUERY_SESSION_PARAM) ||
+        readRequestQueryParam(req, REPRO_QUERY_ACTION_PARAM),
+    );
+}
+
 function stripReproQueryFromUrl(rawUrl: string): string {
     if (!rawUrl || !rawUrl.includes('?')) {
         return rawUrl;
@@ -4955,18 +5367,246 @@ async function maybeCaptureDbValueAsync(
     return result.captureRef;
 }
 
+function pushUniqueCaptureCandidate(candidates: any[], value: any): void {
+    if (value === undefined) return;
+    if (candidates.some((candidate) => candidate === value)) return;
+    candidates.push(value);
+}
+
+function buildResultMetaFullValueCandidates(resultMetaRaw: any, resultMetaSource: any): any[] {
+    const candidates: any[] = [];
+    pushUniqueCaptureCandidate(candidates, resultMetaRaw);
+    if (
+        resultMetaSource &&
+        typeof resultMetaSource === 'object' &&
+        Object.prototype.hasOwnProperty.call(resultMetaSource, 'result')
+    ) {
+        pushUniqueCaptureCandidate(candidates, resultMetaSource.result);
+    }
+    pushUniqueCaptureCandidate(candidates, resultMetaSource);
+    return candidates;
+}
+
+async function maybeCaptureDbValueFromCandidatesAsync(
+    params: {
+        target: 'db.pk' | 'db.before' | 'db.after' | 'db.query' | 'db.resultMeta' | 'db.error';
+        rawValues: any[];
+        previewValue: any;
+        capture: FullValueCaptureContext;
+    },
+    sink: TraceValueBatchEntry[],
+): Promise<TraceValueCaptureRef | undefined> {
+    let skippedRef: TraceValueCaptureRef | undefined;
+    for (const rawValue of params.rawValues) {
+        const result = await createCapturedValueEntryAsync({
+            target: params.target,
+            rawValue,
+            previewValue: params.previewValue,
+            capture: params.capture,
+        });
+        if (!result) continue;
+        if (result.entry) {
+            sink.push(result.entry);
+            return result.captureRef;
+        }
+        if (!skippedRef) {
+            skippedRef = result.captureRef;
+        }
+    }
+    return skippedRef;
+}
+
 // ===================================================================
 // reproMiddleware — unchanged behavior + passive per-request trace
 // ===================================================================
 export type ReproMiddlewareConfig = IngestClientConfig & {
+    /** API base used for backend-owned live session documents. Defaults to REPRO_API_BASE_URL/REPRO_API_BASE/privacy.apiBase. */
+    apiBase?: string;
     /** Configure header capture/masking. Defaults to capturing with sensitive headers masked. */
     captureHeaders?: boolean | HeaderCaptureOptions;
     /** Optional masking rules for request/response payloads and function traces. */
     masking?: ReproMaskingConfig;
     /** Optional privacy policy config for deterministic runtime transformations. */
     privacy?: RuntimePrivacyConfig;
+    /** Opt-in production/live capture mode. Staging/manual tagged capture is unchanged when disabled. */
+    liveMode?: ReproLiveModeConfig | boolean;
+};
+
+export type ReproLiveActorArgs = {
+    req: Request;
+    headers: Request['headers'];
+    method: string;
+    url: string;
+    path: string;
+    ip?: string | null;
+    appId: string;
+    appName?: string;
+    serviceName?: string;
+};
+
+export type ReproLiveActorDecision = ReproLiveActorArgs & {
+    actorId: string;
+    actorType?: string;
+    actorLabels?: Record<string, string>;
+};
+
+export type ReproLiveModeConfig = {
+    enabled?: boolean;
+    backendOnly?: boolean;
+    /**
+     * Stable actor/correlation key for live capture. Return null/undefined/empty
+     * to skip capture for that request.
+     */
+    defineActorId?: (
+        args: ReproLiveActorArgs,
+    ) => string | number | null | undefined | Promise<string | number | null | undefined>;
+    /**
+     * Optional filter for segmenting which actors/requests are captured.
+     */
+    shouldCapture?: (
+        args: ReproLiveActorDecision,
+    ) => boolean | Promise<boolean>;
+    actorType?: string;
+    actorLabels?:
+        | Record<string, string | number | boolean | null | undefined>
+        | ((args: ReproLiveActorDecision) =>
+            | Record<string, string | number | boolean | null | undefined>
+            | null
+            | undefined
+            | Promise<Record<string, string | number | boolean | null | undefined> | null | undefined>);
+    apiBase?: string;
+};
+
+type BackendLiveParentSession = {
+    sessionId: string;
+    startedAt: number;
+    expiresAt: number;
+    previousSessionId: string | null;
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
+    closeTimer?: NodeJS.Timeout | null;
+    closed?: boolean;
+};
+
+type BackendLiveChildSession = {
+    sessionId: string;
+    parentSessionId: string;
+    previousSessionId: string | null;
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
+    startedAt: number;
+    expiresAt: number;
+    closeDeadline: number;
+    requestsInFlight: number;
+    closeTimer?: NodeJS.Timeout | null;
+};
+
+type BackendLiveActorState = {
+    actorId: string;
+    parent: BackendLiveParentSession | null;
+    previousParentSessionId: string | null;
+    activeChild: BackendLiveChildSession | null;
+    previousChildSessionId: string | null;
+};
+
+type BackendLiveActorIdentity = {
+    actorId: string;
+    actorType: string;
+    actorLabels?: Record<string, string>;
 };
 
+type BackendLiveResolvedContext = {
+    sid: string;
+    aid: string;
+    requestStart: number;
+    child: BackendLiveChildSession;
+};
+
+type BackendLiveClaimResponse = {
+    parentSessionId?: string | null;
+    childSessionId?: string | null;
+    sessionId?: string | null;
+    actionId?: string | null;
+    clockOffsetMs?: number | null;
+};
+
+function buildLiveActorArgs(cfg: ReproMiddlewareConfig, req: Request): ReproLiveActorArgs {
+    const rawUrl = String((req as any).originalUrl || req.url || '/');
+    const path = rawUrl.split('?')[0] || '/';
+    return {
+        req,
+        headers: req.headers,
+        method: String(req.method || 'GET').toUpperCase(),
+        url: rawUrl,
+        path,
+        ip: (req as any).ip ?? (req as any).socket?.remoteAddress ?? null,
+        appId: cfg.appId,
+        appName: cfg.appName,
+        serviceName: cfg.serviceName,
+    };
+}
+
+async function resolveLiveActorIdentity(
+    cfg: ReproMiddlewareConfig,
+    req: Request,
+): Promise<BackendLiveActorIdentity | null> {
+    const liveMode = normalizeLiveModeConfig(cfg);
+    if (!liveMode) {
+        return null;
+    }
+
+    const args = buildLiveActorArgs(cfg, req);
+    let rawActorId: string | number | null | undefined;
+    try {
+        rawActorId = liveMode.defineActorId
+            ? await liveMode.defineActorId(args)
+            : cfg.actorId;
+    } catch {
+        rawActorId = null;
+    }
+    const actorId = normalizeLiveActorId(rawActorId);
+    if (!actorId) {
+        return null;
+    }
+
+    const actorType = normalizeLiveActorId(liveMode.actorType) ?? cfg.actorType ?? 'user';
+    const decision: ReproLiveActorDecision = {
+        ...args,
+        actorId,
+        actorType,
+    };
+    if (liveMode.shouldCapture) {
+        let shouldCapture = false;
+        try {
+            shouldCapture = (await liveMode.shouldCapture(decision)) === true;
+        } catch {
+            shouldCapture = false;
+        }
+        if (!shouldCapture) {
+            return null;
+        }
+    }
+
+    let rawLabels:
+        | Record<string, string | number | boolean | null | undefined>
+        | null
+        | undefined;
+    try {
+        rawLabels =
+            typeof liveMode.actorLabels === 'function'
+                ? await liveMode.actorLabels(decision)
+                : liveMode.actorLabels;
+    } catch {
+        rawLabels = undefined;
+    }
+    const actorLabels = normalizeLiveActorLabels(rawLabels) ?? normalizeLiveActorLabels(cfg.actorLabels);
+    return { actorId, actorType, actorLabels };
+}
+
+const backendLiveActors = new Map<string, BackendLiveActorState>();
+
 export type ReproInitConfig = ReproMiddlewareConfig & {
     /**
      * Tracing configuration for function/http instrumentation.
@@ -5011,20 +5651,65 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
             endClientRequest();
         };
 
-        const sid = (req.headers['x-bug-session-id'] as string) || querySid || '';
-        const aid = (req.headers['x-bug-action-id'] as string) || queryAid || '';
+        const requestStartRaw = Date.now();
+        const headerTs = readHeaderNumber(req.headers[REQUEST_START_HEADER]) ?? queryTs;
+        const requestEpochMs = headerTs !== null ? headerTs : requestStartRaw;
+        let backendLiveState: BackendLiveActorState | null = null;
+        let backendLiveChild: BackendLiveChildSession | null = null;
+        const headerSid = (req.headers['x-bug-session-id'] as string) || '';
+        const headerAid = (req.headers['x-bug-action-id'] as string) || '';
+        const hasIncomingReproSession = Boolean(headerSid || querySid || headerAid || queryAid);
+        const backendLiveContext =
+            !hasIncomingReproSession
+                ? await resolveBackendLiveContext(cfg, req, requestEpochMs)
+                : null;
+        const taggedActorIdentity = hasIncomingReproSession
+            ? await resolveLiveActorIdentity(cfg, req)
+            : null;
+        if (backendLiveContext) {
+            backendLiveState = backendLiveActors.get(backendLiveContext.child.actorId) ?? null;
+            backendLiveChild = backendLiveContext.child;
+        }
+        const sid = headerSid || querySid || backendLiveContext?.sid || '';
+        const aid = headerAid || queryAid || backendLiveContext?.aid || '';
         if (!sid || !aid) {
             res.on('finish', endTrackedClientRequest);
             res.on('close', endTrackedClientRequest);
             return next(); // only capture tagged requests
         }
+        const captureCfg: ReproMiddlewareConfig = backendLiveChild
+            ? {
+                ...cfg,
+                actorId: backendLiveChild.actorId,
+                actorType: backendLiveChild.actorType,
+                actorLabels: backendLiveChild.actorLabels,
+            }
+            : taggedActorIdentity
+                ? {
+                    ...cfg,
+                    actorId: taggedActorIdentity.actorId,
+                    actorType: taggedActorIdentity.actorType,
+                    actorLabels: taggedActorIdentity.actorLabels,
+                }
+            : cfg;
+        if (taggedActorIdentity) {
+            post(captureCfg, sid, {
+                entries: [{
+                    actionId: aid,
+                    sessionActor: {
+                        actorId: taggedActorIdentity.actorId,
+                        actorType: taggedActorIdentity.actorType,
+                        actorLabels: taggedActorIdentity.actorLabels,
+                        source: 'node-sdk',
+                    },
+                    t: requestEpochMs,
+                }],
+            }, { priority: 'high' });
+        }
         const resolvePrivacy = (): NormalizedRuntimePrivacyPolicy | null =>
-            getRuntimePrivacyState(cfg).policy ?? null;
+            getRuntimePrivacyState(captureCfg).policy ?? null;
 
-        const requestStartRaw = Date.now();
-        const headerTs = readHeaderNumber(req.headers[REQUEST_START_HEADER]) ?? queryTs;
         const clockSkewMs = headerTs !== null ? headerTs - requestStartRaw : 0;
-        const requestEpochMs = headerTs !== null ? headerTs : requestStartRaw + clockSkewMs;
         const rid = nextRequestId(requestEpochMs);
         const captureScope = createRequestCaptureScope(rid, 'http');
         const t0 = requestStartRaw;
@@ -5222,7 +5907,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     ?? await materializeInlinePrivacyValueAsync(
                         'request.body',
                         sanitizeRequestSnapshot(requestBodyRaw),
-                        cfg,
+                        captureCfg,
                         maskReq,
                         endpointTraceCtx,
                         masking,
@@ -5232,7 +5917,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const requestParams = await applyPrivacyThenMaskAsync(
                     'request.params',
                     sanitizeRequestSnapshot((req as any).params),
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5241,7 +5926,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const requestQuery = await applyPrivacyThenMaskAsync(
                     'request.query',
                     sanitizeRequestSnapshot((req as any).query),
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5250,7 +5935,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                 const maskedHeaders = await applyPrivacyThenMaskAsync(
                     'request.headers',
                     requestHeaders,
-                    cfg,
+                    captureCfg,
                     maskReq,
                     endpointTraceCtx,
                     masking,
@@ -5262,7 +5947,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         ?? await materializeInlinePrivacyValueAsync(
                             'response.body',
                             sanitizeRequestSnapshot(capturedBody),
-                            cfg,
+                            captureCfg,
                             maskReq,
                             endpointTraceCtx,
                             masking,
@@ -5277,7 +5962,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         rawValue: (req as any).body,
                         previewValue: requestBody,
                         capture: {
-                            runtimeConfig: cfg,
+                            runtimeConfig: captureCfg,
                             captureHeaders: cfg.captureHeaders,
                             maskReq,
                             trace: endpointTraceCtx,
@@ -5290,7 +5975,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: (req as any).params,
                     previewValue: requestParams,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5303,7 +5988,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: (req as any).query,
                     previewValue: requestQuery,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5316,7 +6001,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                     rawValue: req.headers,
                     previewValue: maskedHeaders,
                     capture: {
-                        runtimeConfig: cfg,
+                        runtimeConfig: captureCfg,
                         captureHeaders: cfg.captureHeaders,
                         maskReq,
                         trace: endpointTraceCtx,
@@ -5331,7 +6016,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         rawValue: capturedBody,
                         previewValue: responseBody,
                         capture: {
-                            runtimeConfig: cfg,
+                            runtimeConfig: captureCfg,
                             captureHeaders: cfg.captureHeaders,
                             maskReq,
                             trace: endpointTraceCtx,
@@ -5391,7 +6076,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         chosenEndpoint,
                         hasTraceEvents,
                     );
-                    post(cfg, sid, {
+                    post(captureCfg, sid, {
                         entries: [{
                             actionId: aid,
                             request: requestPayload,
@@ -5408,7 +6093,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
             const emitRequestCaptureManifest = (traceBatchTotal: number): void => {
                 if (requestCaptureManifestScheduled) return;
                 requestCaptureManifestScheduled = true;
-                post(cfg, sid, {
+                post(captureCfg, sid, {
                     entries: [{
                         actionId: aid,
                         requestRid: rid,
@@ -5520,7 +6205,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                         try {
                             const pendingEvents = preparePendingTraceEventsForFlush(events.slice());
                             const materializedEvents = await materializePendingTraceEventsAsync(pendingEvents, {
-                                cfg,
+                                cfg: captureCfg,
                                 maskReq,
                                 masking,
                                 resolvePrivacy,
@@ -5553,7 +6238,7 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                                 const batch = traceBatches[i];
                                 const traceValues = collectBatchTraceValueEntries(batch, i);
 
-                                post(cfg, sid, {
+                                post(captureCfg, sid, {
                                     entries: [{
                                         actionId: aid,
                                         trace: batch,
@@ -5575,6 +6260,15 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
 
                 sessionDrainWait = waitForSessionDrain(sid);
                 endSessionRequest(sid);
+                if (backendLiveState && backendLiveChild) {
+                    releaseBackendLiveRequest(
+                        cfg,
+                        normalizeLiveModeConfig(cfg),
+                        backendLiveState,
+                        backendLiveChild,
+                        finishedAtAligned ?? alignedNow(),
+                    );
+                }
                 endTrackedClientRequest();
 
                 if (__TRACER_READY) {
@@ -6241,9 +6935,9 @@ async function emitDbQueryAsync(cfg: any, sid?: string, aid?: string, payload?:
         previewValue: queryPreview,
         capture,
     }, dbValues);
-    const resultMetaValueCapture = resultMetaMaterialization.skipped ? undefined : await maybeCaptureDbValueAsync({
+    const resultMetaValueCapture = resultMetaMaterialization.skipped ? undefined : await maybeCaptureDbValueFromCandidatesAsync({
         target: 'db.resultMeta',
-        rawValue: payload.resultMetaRaw ?? resultMetaSource,
+        rawValues: buildResultMetaFullValueCandidates(payload.resultMetaRaw, resultMetaSource),
         previewValue: resultMetaPreview,
         capture,
     }, dbValues);
@@ -9996,9 +10690,11 @@ export async function initRepro(cfg: ReproInitConfig): Promise<void> {
     const ingestCfg = toIngestConfig(cfg);
     reproAutoMiddlewareConfig = {
         ...ingestCfg,
+        apiBase: cfg.apiBase,
         captureHeaders: cfg.captureHeaders,
         masking: cfg.masking,
         privacy: cfg.privacy,
+        liveMode: cfg.liveMode,
     };
     const integrationCfg = {
         ...reproAutoMiddlewareConfig,
@@ -10053,6 +10749,9 @@ export const __reproTestHooks = {
         lastClientActivityAt = 0;
         sdkBackgroundQuietUntil = 0;
     },
+    setBackendLiveTimingForTest(override: Partial<BackendLiveTimingConfig> | null): void {
+        backendLiveTimingOverrideForTest = override;
+    },
     runWithRequestContextForTest<T>(ctx: Partial<Ctx>, fn: () => T): T {
         return als.run({
             ...ctx,