@jsonstudio/rcc 0.90.876 → 0.90.1270

package/dist/providers/core/utils/snapshot-writer.js

@@ -6,12 +6,44 @@ import { writeSnapshotViaHooks } from '../../../modules/llmswitch/bridge.js';
 import { buildInfo } from '../../../build-info.js';
 import { resolveRccSnapshotsDirFromEnv } from '../../../config/user-data-paths.js';
 import { runtimeFlags } from '../../../runtime/runtime-flags.js';
+import { shouldCaptureSnapshotStage } from '../../../utils/snapshot-stage-policy.js';
+import { canWriteSnapshotToLocalDisk } from '../../../utils/snapshot-local-disk-gate.js';
 import { writeErrorsampleJson } from '../../../utils/errorsamples.js';
 import { redactSensitiveData } from '../../../utils/sensitive-redaction.js';
+import { coerceSnapshotPayloadForWrite } from '../../../utils/snapshot-payload-guard.js';
+import { ensureSnapshotRuntimeMarker, pruneSnapshotRequestDirsKeepRecent, resolveSnapshotKeepRecentRequestDirs } from '../../../utils/snapshot-request-retention.js';
 import { resetProviderSnapshotErrorBufferForTests, } from './snapshot-writer-buffer.js';
+const DEFAULT_PROVIDER_SNAPSHOT_QUEUE_MAX_ITEMS = 32;
+const DEFAULT_PROVIDER_SNAPSHOT_QUEUE_MEMORY_BUDGET_BYTES = 8 * 1024 * 1024;
+const DEFAULT_PROVIDER_SNAPSHOT_QUEUE_BATCH_SIZE = 8;
+const PROVIDER_SNAPSHOT_QUEUE = [];
+let providerSnapshotQueueBytes = 0;
+let providerSnapshotDrainScheduled = false;
+let providerSnapshotDrainInFlight = null;
+let providerSnapshotDroppedCount = 0;
+let providerSnapshotLastDropLogAt = 0;
 function resolveSnapshotBase() {
     return resolveRccSnapshotsDirFromEnv();
 }
+function resolvePositiveIntegerFromEnv(names, fallback) {
+    for (const name of names) {
+        const raw = String(process.env[name] ?? '').trim();
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
+function resolveProviderSnapshotQueueMaxItems() {
+    return resolvePositiveIntegerFromEnv(['ROUTECODEX_PROVIDER_SNAPSHOT_QUEUE_MAX_ITEMS', 'RCC_PROVIDER_SNAPSHOT_QUEUE_MAX_ITEMS'], DEFAULT_PROVIDER_SNAPSHOT_QUEUE_MAX_ITEMS);
+}
+function resolveProviderSnapshotQueueMemoryBudgetBytes() {
+    return resolvePositiveIntegerFromEnv(['ROUTECODEX_PROVIDER_SNAPSHOT_QUEUE_MEMORY_BUDGET_BYTES', 'RCC_PROVIDER_SNAPSHOT_QUEUE_MEMORY_BUDGET_BYTES'], DEFAULT_PROVIDER_SNAPSHOT_QUEUE_MEMORY_BUDGET_BYTES);
+}
+function resolveProviderSnapshotQueueBatchSize() {
+    return resolvePositiveIntegerFromEnv(['ROUTECODEX_PROVIDER_SNAPSHOT_QUEUE_BATCH_SIZE', 'RCC_PROVIDER_SNAPSHOT_QUEUE_BATCH_SIZE'], DEFAULT_PROVIDER_SNAPSHOT_QUEUE_BATCH_SIZE);
+}
 async function ensureDir(dir) {
     try {
         await fsp.mkdir(dir, { recursive: true });
@@ -46,10 +78,16 @@ function resolveEndpoint(entryEndpoint) {
     // Bucket codex-samples strictly by inbound API entry endpoint.
     // Never infer snapshot folder from upstream provider URL/protocol.
     const ep = String(entryEndpoint || '').trim().toLowerCase();
-    if (ep.includes('/v1/responses') || ep.includes('/responses.submit')) {
+    if (ep.includes('/v1/responses')
+        || ep.includes('/responses.submit')
+        || ep.includes('openai-responses')
+        || ep === 'responses') {
         return { endpoint: '/v1/responses', folder: 'openai-responses' };
     }
-    if (ep.includes('/v1/messages')) {
+    if (ep.includes('/v1/messages')
+        || ep.includes('anthropic-messages')
+        || ep === 'messages'
+        || ep === 'anthropic') {
         return { endpoint: '/v1/messages', folder: 'anthropic-messages' };
     }
     return { endpoint: '/v1/chat/completions', folder: 'openai-chat' };
@@ -94,10 +132,212 @@ function toErrorCode(error) {
     const code = error.code;
     return typeof code === 'string' && code.trim() ? code : undefined;
 }
+function toFiniteNumber(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return undefined;
+    }
+    return value;
+}
+function toNonEmptyString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+function isRateLimitCode(code) {
+    if (!code) {
+        return false;
+    }
+    const upper = code.toUpperCase();
+    return (upper === 'HTTP_429'
+        || upper.includes('RATE_LIMIT')
+        || upper.includes('TOO_MANY_REQUEST')
+        || upper.includes('429'));
+}
+function read429HintFromSnapshotPayload(value) {
+    const queue = [value];
+    const seen = new WeakSet();
+    let steps = 0;
+    while (queue.length > 0 && steps < 400) {
+        steps += 1;
+        const current = queue.shift();
+        if (!current || typeof current !== 'object') {
+            continue;
+        }
+        if (seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const record = current;
+        const statusCode = toFiniteNumber(record.statusCode)
+            ?? toFiniteNumber(record.status)
+            ?? toFiniteNumber(record.httpStatus)
+            ?? toFiniteNumber(record.error?.status)
+            ?? toFiniteNumber(record.error?.statusCode);
+        if (statusCode === 429) {
+            return true;
+        }
+        const codeCandidates = [
+            toNonEmptyString(record.code),
+            toNonEmptyString(record.errorCode),
+            toNonEmptyString(record.upstreamCode),
+            toNonEmptyString(record.error?.code)
+        ];
+        if (codeCandidates.some((candidate) => isRateLimitCode(candidate))) {
+            return true;
+        }
+        for (const child of Object.values(record)) {
+            if (!child || typeof child !== 'object') {
+                continue;
+            }
+            queue.push(child);
+        }
+    }
+    return false;
+}
+function shouldSuppressSnapshotFor429(stage, payload) {
+    const normalizedStage = String(stage || '').trim().toLowerCase();
+    if (!normalizedStage) {
+        return false;
+    }
+    if (!normalizedStage.includes('provider-error')
+        && !normalizedStage.includes('provider-response')
+        && !normalizedStage.includes('provider-request.retry')
+        && !normalizedStage.includes('provider-response.retry')) {
+        return false;
+    }
+    return read429HintFromSnapshotPayload(payload);
+}
+async function purge429ProviderSnapshotArtifacts(options) {
+    const { folder } = resolveEndpoint(options.entryEndpoint);
+    const base = resolveSnapshotBase();
+    const groupRequestId = normalizeRequestId(options.clientRequestId || options.requestId);
+    const providerToken = normalizeProviderToken(options.providerKey || options.providerId || '');
+    if (providerToken) {
+        const providerDir = path.join(base, folder, providerToken, groupRequestId);
+        try {
+            await fsp.rm(providerDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            logSnapshotNonBlockingError(`purge429.providerDir:${providerToken}/${groupRequestId}`, error);
+        }
+    }
+    // Legacy fallback layout: <base>/<folder>/<groupRequestId>/provider-*.json
+    const legacyDir = path.join(base, folder, groupRequestId);
+    try {
+        const entries = await fsp.readdir(legacyDir, { withFileTypes: true });
+        const providerFilePattern = /^provider-(request|response|error)(\.retry)?(?:_\d+)?\.json$/;
+        await Promise.all(entries
+            .filter((entry) => entry.isFile() && providerFilePattern.test(entry.name))
+            .map((entry) => fsp.rm(path.join(legacyDir, entry.name), { force: true })));
+    }
+    catch (error) {
+        const code = toErrorCode(error);
+        if (code !== 'ENOENT') {
+            logSnapshotNonBlockingError(`purge429.legacyDir:${groupRequestId}`, error);
+        }
+    }
+}
+function schedule429ProviderSnapshotPurge(options) {
+    const recheckDelaysMs = [250, 1000, 3000];
+    for (const delayMs of recheckDelaysMs) {
+        const timer = setTimeout(() => {
+            void purge429ProviderSnapshotArtifacts(options).catch((error) => {
+                logSnapshotNonBlockingError(`purge429.schedule:${options.requestId}:${delayMs}`, error);
+            });
+        }, delayMs);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    }
+}
 function logSnapshotNonBlockingError(operation, error) {
     const reason = error instanceof Error ? error.message : String(error);
     console.warn(`[provider-snapshot] ${operation} failed (non-blocking): ${reason}`);
 }
+function estimateProviderSnapshotQueueBytes(input) {
+    try {
+        const json = JSON.stringify(input.payload);
+        if (typeof json === 'string' && json.length > 0) {
+            return Math.max(1, Buffer.byteLength(json, 'utf8'));
+        }
+    }
+    catch {
+        // fall through
+    }
+    return 1024;
+}
+function flushProviderSnapshotDropLog(force = false) {
+    if (providerSnapshotDroppedCount <= 0) {
+        return;
+    }
+    const now = Date.now();
+    if (!force && now - providerSnapshotLastDropLogAt < 10_000) {
+        return;
+    }
+    providerSnapshotLastDropLogAt = now;
+    const dropped = providerSnapshotDroppedCount;
+    providerSnapshotDroppedCount = 0;
+    console.warn(`[provider-snapshot] queue overflow: dropped ${dropped} old snapshot task(s) ` +
+        `(pending=${PROVIDER_SNAPSHOT_QUEUE.length}, bytes=${providerSnapshotQueueBytes})`);
+}
+async function drainProviderSnapshotQueue() {
+    const batchSize = resolveProviderSnapshotQueueBatchSize();
+    let processed = 0;
+    while (PROVIDER_SNAPSHOT_QUEUE.length > 0 && processed < batchSize) {
+        const item = PROVIDER_SNAPSHOT_QUEUE.shift();
+        if (!item) {
+            continue;
+        }
+        providerSnapshotQueueBytes = Math.max(0, providerSnapshotQueueBytes - Math.max(1, item.sizeBytes));
+        await persistProviderSnapshot(item.input);
+        processed += 1;
+    }
+    flushProviderSnapshotDropLog();
+}
+function scheduleProviderSnapshotDrain() {
+    if (providerSnapshotDrainScheduled || providerSnapshotDrainInFlight) {
+        return;
+    }
+    providerSnapshotDrainScheduled = true;
+    setImmediate(() => {
+        providerSnapshotDrainScheduled = false;
+        if (providerSnapshotDrainInFlight) {
+            return;
+        }
+        providerSnapshotDrainInFlight = drainProviderSnapshotQueue()
+            .catch((error) => {
+            logSnapshotNonBlockingError('providerSnapshotQueueDrain', error);
+        })
+            .finally(() => {
+            providerSnapshotDrainInFlight = null;
+            if (PROVIDER_SNAPSHOT_QUEUE.length > 0) {
+                scheduleProviderSnapshotDrain();
+            }
+            else {
+                flushProviderSnapshotDropLog(true);
+            }
+        });
+    });
+}
+function enqueueProviderSnapshotPersist(input) {
+    const sizeBytes = estimateProviderSnapshotQueueBytes(input);
+    const queueMaxItems = resolveProviderSnapshotQueueMaxItems();
+    const queueBudgetBytes = resolveProviderSnapshotQueueMemoryBudgetBytes();
+    while (PROVIDER_SNAPSHOT_QUEUE.length > 0
+        && (PROVIDER_SNAPSHOT_QUEUE.length >= queueMaxItems || providerSnapshotQueueBytes + sizeBytes > queueBudgetBytes)) {
+        const dropped = PROVIDER_SNAPSHOT_QUEUE.shift();
+        if (!dropped) {
+            break;
+        }
+        providerSnapshotQueueBytes = Math.max(0, providerSnapshotQueueBytes - Math.max(1, dropped.sizeBytes));
+        providerSnapshotDroppedCount += 1;
+    }
+    PROVIDER_SNAPSHOT_QUEUE.push({ input, sizeBytes });
+    providerSnapshotQueueBytes += sizeBytes;
+    scheduleProviderSnapshotDrain();
+}
 async function writeUniqueFile(dir, baseName, contents) {
     const parsed = path.parse(baseName);
     const ext = parsed.ext || '.json';
@@ -118,6 +358,39 @@ async function writeUniqueFile(dir, baseName, contents) {
     const fallback = `${stem}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}${ext}`;
     await fsp.writeFile(path.join(dir, fallback), contents, 'utf-8');
 }
+function resolveSnapshotDir(folder, groupRequestId, providerToken) {
+    if (providerToken) {
+        return path.join(resolveSnapshotBase(), folder, providerToken, groupRequestId);
+    }
+    return path.join(resolveSnapshotBase(), folder, groupRequestId);
+}
+async function writeCanonicalSnapshotFileIfMissing(dir, baseName, contents) {
+    try {
+        await fsp.writeFile(path.join(dir, baseName), contents, { encoding: 'utf-8', flag: 'wx' });
+    }
+    catch (error) {
+        if (toErrorCode(error) === 'EEXIST') {
+            return;
+        }
+        throw error;
+    }
+}
+async function mirrorSnapshotToLocalDisk(input) {
+    if (!canWriteSnapshotToLocalDisk(input.requestId, input.groupRequestId)) {
+        return;
+    }
+    const dir = resolveSnapshotDir(input.folder, input.groupRequestId, input.providerToken || undefined);
+    await ensureDir(dir);
+    await ensureSnapshotRuntimeMarker(dir, {
+        endpoint: input.endpoint,
+        requestId: input.requestId,
+        groupRequestId: input.groupRequestId,
+        providerKey: input.providerToken || undefined
+    });
+    const safeStage = input.stage.replace(/[^\w.-]/g, '_') || 'snapshot';
+    await writeCanonicalSnapshotFileIfMissing(dir, `${safeStage}.json`, JSON.stringify(input.payload, null, 2));
+    await pruneSnapshotRequestDirsKeepRecent(path.dirname(dir), resolveSnapshotKeepRecentRequestDirs());
+}
 async function persistProviderSnapshot(input) {
     try {
         await writeSnapshotViaHooks({
@@ -129,15 +402,13 @@ async function persistProviderSnapshot(input) {
             data: input.payload,
             verbosity: 'verbose'
         });
+        await mirrorSnapshotToLocalDisk(input);
         return;
     }
     catch (error) {
         logSnapshotNonBlockingError(`writeSnapshotViaHooks:${input.stage}`, error);
         try {
-            const dir = path.join(resolveSnapshotBase(), input.folder, input.providerToken || '__pending__', input.groupRequestId);
-            await ensureDir(dir);
-            const safeStage = input.stage.replace(/[^\w.-]/g, '_') || 'snapshot';
-            await writeUniqueFile(dir, safeStage + '.json', JSON.stringify(input.payload, null, 2));
+            await mirrorSnapshotToLocalDisk(input);
         }
         catch (fallbackError) {
             logSnapshotNonBlockingError(`fallbackWrite:${input.stage}`, fallbackError);
@@ -150,7 +421,7 @@ function buildProviderSnapshotPersistInput(options) {
     const requestId = normalizeRequestId(options.requestId);
     const groupRequestId = normalizeRequestId(options.clientRequestId || options.requestId);
     const providerToken = normalizeProviderToken(options.providerKey || options.providerId || '');
-    const payload = buildSnapshotPayload({
+    const payload = coerceSnapshotPayloadForWrite(stage, buildSnapshotPayload({
         stage,
         data: options.data,
         headers: options.headers,
@@ -161,12 +432,32 @@ function buildProviderSnapshotPersistInput(options) {
             ...(options.providerKey ? { providerKey: options.providerKey } : {}),
             ...(options.providerId ? { providerId: options.providerId } : {})
         }
-    });
+    }));
     return { endpoint, folder, stage, requestId, groupRequestId, providerToken, payload };
 }
 export function __resetProviderSnapshotErrorBufferForTests() {
     resetProviderSnapshotErrorBufferForTests();
 }
+export async function __flushProviderSnapshotQueueForTests() {
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+        if (PROVIDER_SNAPSHOT_QUEUE.length === 0
+            && providerSnapshotQueueBytes === 0
+            && !providerSnapshotDrainScheduled
+            && !providerSnapshotDrainInFlight) {
+            flushProviderSnapshotDropLog(true);
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    throw new Error('provider snapshot queue did not flush in time');
+}
+export function __resetProviderSnapshotQueueForTests() {
+    PROVIDER_SNAPSHOT_QUEUE.splice(0, PROVIDER_SNAPSHOT_QUEUE.length);
+    providerSnapshotQueueBytes = 0;
+    providerSnapshotDrainScheduled = false;
+    providerSnapshotDroppedCount = 0;
+    providerSnapshotLastDropLogAt = 0;
+}
 function isErrorPhase(phase) {
     return String(phase || '').trim().toLowerCase().includes('error');
 }
@@ -191,8 +482,33 @@ async function writeProviderErrorsample(snapshot) {
     });
 }
 export async function writeProviderSnapshot(options) {
+    const stage = String(options.phase || '').trim();
+    if (shouldSuppressSnapshotFor429(stage, options.data)) {
+        const purgeInput = {
+            entryEndpoint: options.entryEndpoint,
+            requestId: options.requestId,
+            clientRequestId: options.clientRequestId,
+            providerKey: options.providerKey,
+            providerId: options.providerId
+        };
+        await purge429ProviderSnapshotArtifacts(purgeInput);
+        schedule429ProviderSnapshotPurge(purgeInput);
+        return;
+    }
+    if (!shouldCaptureSnapshotStage(stage)) {
+        return;
+    }
     const snapshot = buildProviderSnapshotPersistInput(options);
     if (!runtimeFlags.snapshotsEnabled) {
+        if (options.forceLocalDiskWriteWhenDisabled) {
+            try {
+                await mirrorSnapshotToLocalDisk(snapshot);
+            }
+            catch (error) {
+                logSnapshotNonBlockingError(`forceLocalDiskWrite:${snapshot.stage}`, error);
+            }
+            return;
+        }
         if (isErrorPhase(snapshot.stage)) {
             try {
                 await writeProviderErrorsample(snapshot);
@@ -203,7 +519,7 @@ export async function writeProviderSnapshot(options) {
         }
         return;
     }
-    await persistProviderSnapshot(snapshot);
+    enqueueProviderSnapshotPersist(snapshot);
 }
 function toBuffer(chunk) {
     if (Buffer.isBuffer(chunk)) {
@@ -339,21 +655,36 @@ export function attachProviderSseSnapshotStream(stream, options) {
     return tee;
 }
 export async function writeProviderRetrySnapshot(options) {
+    if (shouldSuppressSnapshotFor429(options.type === 'request' ? 'provider-request.retry' : 'provider-response.retry', options.data)) {
+        const purgeInput = {
+            entryEndpoint: options.entryEndpoint,
+            requestId: options.requestId,
+            clientRequestId: options.clientRequestId,
+            providerKey: options.providerKey,
+            providerId: options.providerId
+        };
+        await purge429ProviderSnapshotArtifacts(purgeInput);
+        schedule429ProviderSnapshotPurge(purgeInput);
+        return;
+    }
     if (!runtimeFlags.snapshotsEnabled) {
         return;
     }
     const { endpoint, folder } = resolveEndpoint(options.entryEndpoint);
     const stage = options.type === 'request' ? 'provider-request.retry' : 'provider-response.retry';
+    if (!shouldCaptureSnapshotStage(stage)) {
+        return;
+    }
     const requestId = normalizeRequestId(options.requestId);
     const groupRequestId = normalizeRequestId(options.clientRequestId || options.requestId);
     const providerToken = normalizeProviderToken(options.providerKey || options.providerId || '');
-    const payload = buildSnapshotPayload({
+    const payload = coerceSnapshotPayloadForWrite(stage, buildSnapshotPayload({
         stage,
         data: options.data,
         headers: options.headers,
         url: options.url,
         extraMeta: options.clientRequestId ? { clientRequestId: options.clientRequestId } : undefined
-    });
+    }));
     try {
         await writeSnapshotViaHooks({
             endpoint,
@@ -364,15 +695,13 @@ export async function writeProviderRetrySnapshot(options) {
             data: payload,
             verbosity: 'verbose'
         });
+        await mirrorSnapshotToLocalDisk({ endpoint, folder, stage, requestId, groupRequestId, providerToken, payload });
         return;
     }
     catch (error) {
         logSnapshotNonBlockingError(`writeSnapshotViaHooks(retry):${stage}`, error);
         try {
-            const dir = path.join(resolveSnapshotBase(), folder, providerToken || '__pending__', groupRequestId);
-            await ensureDir(dir);
-            const safeStage = stage.replace(/[^\w.-]/g, '_') || 'snapshot';
-            await writeUniqueFile(dir, `${safeStage}.json`, JSON.stringify(payload, null, 2));
+            await mirrorSnapshotToLocalDisk({ endpoint, folder, stage, requestId, groupRequestId, providerToken, payload });
         }
         catch (fallbackError) {
             logSnapshotNonBlockingError(`fallbackWrite(retry):${stage}`, fallbackError);
@@ -383,22 +712,34 @@ export async function writeRepairFeedbackSnapshot(options) {
     if (!runtimeFlags.snapshotsEnabled) {
         return;
     }
+    if (!shouldCaptureSnapshotStage('repair-feedback')) {
+        return;
+    }
     try {
         // const requestId = normalizeRequestId(options.requestId);
-        const { folder } = resolveEndpoint(options.entryEndpoint);
+        const { endpoint, folder } = resolveEndpoint(options.entryEndpoint);
         const groupRequestId = normalizeRequestId(options.groupRequestId || options.requestId);
-        const providerToken = normalizeProviderToken(options.providerKey || options.providerId || '');
-        const dir = path.join(resolveSnapshotBase(), folder, providerToken || '__pending__', groupRequestId);
+        if (!canWriteSnapshotToLocalDisk(options.requestId, groupRequestId)) {
+            return;
+        }
+        const dir = path.join(resolveSnapshotBase(), folder, groupRequestId);
         await ensureDir(dir);
-        const payload = {
+        await ensureSnapshotRuntimeMarker(dir, {
+            entryEndpoint: options.entryEndpoint || endpoint,
+            requestId: options.requestId,
+            groupRequestId,
+            providerKey: options.providerKey || options.providerId || undefined
+        });
+        const payload = coerceSnapshotPayloadForWrite('repair-feedback', {
             meta: {
                 stage: 'repair-feedback',
                 version: String(process.env.ROUTECODEX_VERSION || 'dev'),
                 buildTime: String(process.env.ROUTECODEX_BUILD_TIME || new Date().toISOString())
             },
             feedback: options.feedback
-        };
+        });
         await writeUniqueFile(dir, 'repair-feedback.json', JSON.stringify(payload, null, 2));
+        await pruneSnapshotRequestDirsKeepRecent(path.dirname(dir), resolveSnapshotKeepRecentRequestDirs());
     }
     catch (error) {
         logSnapshotNonBlockingError('writeRepairFeedbackSnapshot', error);
@@ -408,6 +749,9 @@ export async function writeClientSnapshot(options) {
     if (!runtimeFlags.snapshotsEnabled) {
         return;
     }
+    if (!shouldCaptureSnapshotStage('client-request')) {
+        return;
+    }
     try {
         const stage = 'client-request';
         const { endpoint, folder } = resolveEndpoint(options.entryEndpoint);
@@ -418,13 +762,13 @@ export async function writeClientSnapshot(options) {
         const groupRequestId = normalizeRequestId(groupRequestIdCandidate || requestId);
         const providerToken = normalizeProviderToken(options.providerKey || '');
         const metadataSnapshot = options.metadata && typeof options.metadata === 'object'
-            ? JSON.parse(JSON.stringify(options.metadata))
+            ? options.metadata
             : undefined;
         const snapshotPayload = {
             body: options.body,
             metadata: metadataSnapshot || {}
         };
-        const payload = buildSnapshotPayload({
+        const payload = coerceSnapshotPayloadForWrite(stage, buildSnapshotPayload({
             stage,
             data: snapshotPayload,
             headers: options.headers,
@@ -435,7 +779,7 @@ export async function writeClientSnapshot(options) {
                 userAgent: options.metadata?.userAgent,
                 ...(metadataSnapshot ? { requestMetadata: metadataSnapshot } : {})
             }
-        });
+        }));
         try {
             await writeSnapshotViaHooks({
                 endpoint,
@@ -446,13 +790,28 @@ export async function writeClientSnapshot(options) {
                 data: payload,
                 verbosity: 'verbose'
             });
+            await mirrorSnapshotToLocalDisk({
+                endpoint,
+                folder,
+                stage,
+                requestId,
+                groupRequestId,
+                providerToken,
+                payload
+            });
             return;
         }
         catch (error) {
             logSnapshotNonBlockingError(`writeSnapshotViaHooks(client):${requestId}`, error);
-            const dir = path.join(resolveSnapshotBase(), folder, providerToken || '__pending__', groupRequestId);
-            await ensureDir(dir);
-            await writeUniqueFile(dir, `${stage}.json`, JSON.stringify(payload, null, 2));
+            await mirrorSnapshotToLocalDisk({
+                endpoint,
+                folder,
+                stage,
+                requestId,
+                groupRequestId,
+                providerToken,
+                payload
+            });
         }
     }
     catch (error) {