@qduc/term2 0.20.0 → 0.22.0

package/dist/services/logging/provider-traffic.js

@@ -1,8 +1,113 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 export const TRAFFIC_TEXT_LIMIT = 100;
 const PREVIEW_LIMIT = 160;
-import { classifyProviderFailure } from '../retry/provider-failure-classification.js';
+import { classifyProviderFailure, isClassifiedCancellation } from '../retry/provider-failure-classification.js';
+export const PROVIDER_REQUEST_FINGERPRINT_VERSION = 'provider-request-fingerprint-v1';
+function fingerprintValue(value) {
+    let encoded;
+    if (typeof value === 'string') {
+        encoded = value;
+    }
+    else {
+        try {
+            encoded = JSON.stringify(value) ?? String(value);
+        }
+        catch {
+            encoded = '[unserializable-provider-request-component]';
+        }
+    }
+    return {
+        encoded,
+        sha256: createHash('sha256').update(encoded, 'utf8').digest('hex'),
+        bytes: Buffer.byteLength(encoded, 'utf8'),
+    };
+}
+/**
+ * Hash the unsanitized request prefix and tool definitions at the logging
+ * boundary. The ordered component hashes and byte counts show which prefix
+ * components were sent and whether they match across requests without putting
+ * prompt text or tool schemas in logs. This proves serialized-component
+ * equality, not provider tokenization or cache acceptance.
+ */
+export function buildProviderRequestFingerprint(body) {
+    const parts = [];
+    const rawParts = [];
+    const addPart = (source, value) => {
+        const measurement = fingerprintValue(value);
+        parts.push({ source, sha256: measurement.sha256, bytes: measurement.bytes });
+        rawParts.push(source + '\0' + measurement.encoded);
+        return { sha256: measurement.sha256, bytes: measurement.bytes };
+    };
+    const direct = {};
+    if (body.instructions !== undefined)
+        direct.instructions = addPart('instructions', body.instructions);
+    if (body.system !== undefined)
+        direct.system = addPart('system', body.system);
+    const addRoleParts = (source, value) => {
+        if (!Array.isArray(value))
+            return;
+        value.forEach((item, index) => {
+            if (!item || typeof item !== 'object')
+                return;
+            if (item.type === 'additional_tools')
+                return;
+            const role = item.role;
+            if (role === 'system' || role === 'developer')
+                addPart(source + '[' + index + ']', item);
+        });
+    };
+    addRoleParts('messages', body.messages);
+    addRoleParts('input', body.input);
+    const toolGroups = [];
+    if (Array.isArray(body.tools))
+        toolGroups.push({ source: 'tools', value: body.tools });
+    if (Array.isArray(body.additional_tools))
+        toolGroups.push({ source: 'additional_tools', value: body.additional_tools });
+    if (Array.isArray(body.input)) {
+        body.input.forEach((item, index) => {
+            if (!item || typeof item !== 'object')
+                return;
+            const itemTools = item.tools;
+            if (!Array.isArray(itemTools))
+                return;
+            toolGroups.push({ source: 'input[' + index + '].tools', value: itemTools });
+        });
+    }
+    const toolValues = toolGroups.flatMap(({ source, value }) => value.map((tool) => ({ source, tool })));
+    const tools = toolValues.length > 0
+        ? (() => {
+            const measurement = fingerprintValue(toolValues);
+            return { sha256: measurement.sha256, bytes: measurement.bytes, count: toolValues.length };
+        })()
+        : undefined;
+    const prefixMeasurement = fingerprintValue(rawParts.join('\0'));
+    return {
+        version: PROVIDER_REQUEST_FINGERPRINT_VERSION,
+        prefix: {
+            sha256: prefixMeasurement.sha256,
+            bytes: prefixMeasurement.bytes,
+            parts,
+        },
+        ...(direct.instructions ? { instructions: direct.instructions } : {}),
+        ...(direct.system ? { system: direct.system } : {}),
+        ...(tools ? { tools } : {}),
+    };
+}
+/**
+ * Same truth table as `parseBooleanEnv` in logging-service.ts (kept local:
+ * that module imports this one, so importing it here would be a cycle).
+ * Only consulted for the opt-in raw-traffic sidecar, which must be
+ * impossible to enable by accident — absent/unset means off.
+ */
+const parseBooleanEnvValue = (value) => {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+};
 const asRecord = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return null;
@@ -72,6 +177,34 @@ const sanitizeToolDefinitions = (tools) => {
  * actually round-tripping on the Responses lane.
  */
 export const ENCRYPTED_CONTENT_REDACTION = '<redacted>';
+/**
+ * Field-name pattern for values that may carry bearer credentials in a
+ * request body (API keys, tokens, secrets). Applied only to the opt-in raw
+ * sidecar, where the body is otherwise written unsanitized — headers arrive
+ * pre-sanitized via `sanitizeHeaders` at every call site, but nothing stands
+ * between the body and disk there. Keep in sync with the pattern in
+ * `source/utils/header-sanitizer.ts`.
+ */
+const RAW_CREDENTIAL_KEY_PATTERN = /authorization|api[_-]?key|key|cookie|token|secret|signature/i;
+export const isRawTrafficCaptureEnabled = (env = process.env) => parseBooleanEnvValue(env.TERM2_RAW_TRAFFIC);
+const redactRawCredentialFields = (value) => {
+    if (Array.isArray(value))
+        return value.map(redactRawCredentialFields);
+    if (value && typeof value === 'object') {
+        const record = value;
+        const out = {};
+        for (const [key, v] of Object.entries(record)) {
+            out[key] = RAW_CREDENTIAL_KEY_PATTERN.test(key) ? '[REDACTED]' : redactRawCredentialFields(v);
+        }
+        return out;
+    }
+    return value;
+};
+/**
+ * Derives the sidecar path for an opt-in raw (unsanitized) request-body
+ * capture from the sanitized artifact path: `<request>_raw.json` next to it.
+ */
+export const rawCapturePathForRequestPath = (requestPath) => requestPath.replace(/\.json$/, '_raw.json');
 const sanitizeReasoningDetails = (reasoningDetails) => {
     if (!Array.isArray(reasoningDetails))
         return reasoningDetails;
@@ -630,10 +763,19 @@ export async function summarizeReceivedTraffic(response) {
 export class ProviderTrafficArtifactStore {
     #rootDir;
     #requestPaths = new Map();
-    constructor({ rootDir }) {
+    #rawCaptureEnabled;
+    #enabled;
+    constructor({ rootDir, rawCaptureEnabled, enabled = true, }) {
         this.#rootDir = rootDir;
+        this.#enabled = enabled;
+        // Resolved once at construction so a mid-process env change cannot flip
+        // capture on for a store that started with it off (and tests can inject
+        // the flag directly without touching process.env).
+        this.#rawCaptureEnabled = rawCaptureEnabled ?? isRawTrafficCaptureEnabled();
     }
     recordRequestStart(input) {
+        if (!this.#enabled)
+            return;
         const { dayDir, requestPath, sessionDirName } = this.#pathsFor(input);
         this.#requestPaths.set(input.requestId, requestPath);
         try {
@@ -646,11 +788,18 @@ export class ProviderTrafficArtifactStore {
                 ...(input.modelClass ? { modelClass: input.modelClass } : {}),
                 ...(input.modelWrapperClass ? { modelWrapperClass: input.modelWrapperClass } : {}),
                 sessionId: input.sessionId,
+                ...(input.promptCacheKey ? { promptCacheKey: input.promptCacheKey } : {}),
+                ...(input.providerHistoryKey ? { providerHistoryKey: input.providerHistoryKey } : {}),
+                ...(input.transportDiagnostics ? { transportDiagnostics: input.transportDiagnostics } : {}),
+                ...(input.requestFingerprint ? { requestFingerprint: input.requestFingerprint } : {}),
                 mode: input.mode ?? 'unknown',
                 ...(input.headers ? { headers: input.headers } : {}),
                 body: sanitizeSentTrafficBody(input.sentBody),
             };
             writeTrafficEnvelope(requestPath, { sent: sentRecord, received: emptyTrafficRecord() });
+            if (this.#rawCaptureEnabled) {
+                this.#writeRawCapture(requestPath, input);
+            }
             this.#upsertDailyIndex(dayDir, {
                 sessionId: input.sessionId,
                 sessionDir: sessionDirName,
@@ -675,6 +824,8 @@ export class ProviderTrafficArtifactStore {
         }
     }
     recordRequestComplete(input) {
+        if (!this.#enabled)
+            return;
         const { dayDir, requestPath: fallbackRequestPath, sessionDirName } = this.#pathsFor(input);
         const requestPath = this.#requestPaths.get(input.requestId) ?? fallbackRequestPath;
         try {
@@ -713,6 +864,27 @@ export class ProviderTrafficArtifactStore {
             this.#requestPaths.delete(input.requestId);
         }
     }
+    #writeRawCapture(requestPath, input) {
+        // Best-effort by design: a raw sidecar must never fail the request it
+        // observes, nor disturb the sanitized artifact. Swallow write failures
+        // silently (the sanitized envelope + winston record remain the source of
+        // truth; ProviderTraffic's residual boundary already covers those).
+        try {
+            const rawPath = rawCapturePathForRequestPath(requestPath);
+            fs.mkdirSync(path.dirname(rawPath), { recursive: true });
+            fs.writeFileSync(rawPath, `${JSON.stringify({
+                requestId: input.requestId,
+                timestamp: input.timestamp,
+                provider: input.provider,
+                model: input.model,
+                ...(input.headers ? { headers: input.headers } : {}),
+                body: redactRawCredentialFields(input.sentBody),
+            }, null, 2)}\n`, 'utf8');
+        }
+        catch {
+            // Intentionally silent: see above.
+        }
+    }
     #pathsFor(input) {
         const dateKey = input.timestamp.slice(0, 10);
         const dayDir = `${this.#rootDir}/${dateKey}`;
@@ -756,7 +928,28 @@ export class ProviderTrafficArtifactStore {
             entries.push(entry);
         }
         else {
-            entries[index] = entry;
+            const current = entries[index];
+            const isNewerRequest = entry.lastRequestAt >= current.lastRequestAt;
+            entries[index] = {
+                ...current,
+                // A request is counted when its sent envelope is created. Completion
+                // is best-effort and may never run for a failed stream, so counting at
+                // completion loses exactly the requests this index is meant to find.
+                requestCount: current.requestCount + entry.requestCount,
+                firstRequestAt: entry.firstRequestAt < current.firstRequestAt ? entry.firstRequestAt : current.firstRequestAt,
+                lastRequestAt: entry.lastRequestAt > current.lastRequestAt ? entry.lastRequestAt : current.lastRequestAt,
+                firstUserMessagePreview: current.firstUserMessagePreview || entry.firstUserMessagePreview,
+                ...(isNewerRequest
+                    ? {
+                        latestProvider: entry.latestProvider,
+                        latestModel: entry.latestModel,
+                        latestMode: entry.latestMode,
+                    }
+                    : {}),
+                providersSeen: [...new Set([...(current.providersSeen ?? []), ...entry.providersSeen])],
+                modelsSeen: [...new Set([...(current.modelsSeen ?? []), ...entry.modelsSeen])],
+                modesSeen: [...new Set([...(current.modesSeen ?? []), ...entry.modesSeen])],
+            };
         }
         this.#writeDailyIndex(dayDir, entries);
     }
@@ -767,16 +960,20 @@ export class ProviderTrafficArtifactStore {
             return;
         }
         const current = entries[index];
+        const isNewerRequest = update.lastRequestAt >= current.lastRequestAt;
         entries[index] = {
             ...current,
-            lastRequestAt: update.lastRequestAt,
-            requestCount: current.requestCount + 1,
-            latestProvider: update.latestProvider,
-            latestModel: update.latestModel,
-            latestMode: update.latestMode,
-            providersSeen: [...new Set([...current.providersSeen, update.latestProvider])],
-            modelsSeen: [...new Set([...current.modelsSeen, update.latestModel])],
-            modesSeen: [...new Set([...current.modesSeen, update.latestMode])],
+            lastRequestAt: update.lastRequestAt > current.lastRequestAt ? update.lastRequestAt : current.lastRequestAt,
+            ...(isNewerRequest
+                ? {
+                    latestProvider: update.latestProvider,
+                    latestModel: update.latestModel,
+                    latestMode: update.latestMode,
+                }
+                : {}),
+            providersSeen: [...new Set([...(current.providersSeen ?? []), update.latestProvider])],
+            modelsSeen: [...new Set([...(current.modelsSeen ?? []), update.latestModel])],
+            modesSeen: [...new Set([...(current.modesSeen ?? []), update.latestMode])],
         };
         this.#writeDailyIndex(dayDir, entries);
     }
@@ -957,6 +1154,9 @@ export class ProviderTraffic {
         const sessionStartedAt = trafficContext?.sessionStartedAt ?? timestamp;
         const mode = trafficContext?.mode ?? 'unknown';
         const firstUserMessagePreview = trafficContext?.firstUserMessagePreview;
+        const promptCacheKey = input.promptCacheKey ?? trafficContext?.promptCacheKey;
+        const providerHistoryKey = input.providerHistoryKey ?? trafficContext?.providerHistoryKey;
+        const requestFingerprint = buildProviderRequestFingerprint(input.sentBody);
         // 1. Write the sent request to artifact store directly
         this.#runArtifactStoreOperation('recordRequestStart', input.requestId, () => {
             this.store.recordRequestStart({
@@ -970,6 +1170,10 @@ export class ProviderTraffic {
                 sessionStartedAt,
                 mode,
                 firstUserMessagePreview,
+                promptCacheKey,
+                providerHistoryKey,
+                transportDiagnostics: input.transportDiagnostics,
+                requestFingerprint,
                 sentBody: input.sentBody,
                 headers: input.headers,
                 evaluator: isEvaluator,
@@ -986,6 +1190,10 @@ export class ProviderTraffic {
             model: input.model,
             modelClass: input.modelClass,
             modelWrapperClass: input.modelWrapperClass,
+            promptCacheKey,
+            providerHistoryKey,
+            requestFingerprint,
+            transportDiagnostics: input.transportDiagnostics,
         };
         // 2. Log request start via logging service for winston
         this.loggingService.debug(`${input.provider} request start`, {
@@ -1010,6 +1218,8 @@ export class ProviderTraffic {
         const sessionStartedAt = trafficContext?.sessionStartedAt ?? timestamp;
         const mode = trafficContext?.mode ?? 'unknown';
         const firstUserMessagePreview = trafficContext?.firstUserMessagePreview;
+        const promptCacheKey = trafficContext?.promptCacheKey;
+        const providerHistoryKey = trafficContext?.providerHistoryKey;
         const baseMeta = {
             requestId: input.requestId,
             traceId: trafficContext?.traceId ?? this.loggingService.getCorrelationId?.(),
@@ -1021,6 +1231,9 @@ export class ProviderTraffic {
             model: input.model,
             modelClass: input.modelClass,
             modelWrapperClass: input.modelWrapperClass,
+            promptCacheKey,
+            providerHistoryKey,
+            transportDiagnostics: input.transportDiagnostics,
         };
         if (input.error) {
             // 1. Write failure to artifact store
@@ -1039,13 +1252,19 @@ export class ProviderTraffic {
                     evaluator: isEvaluator,
                 });
             });
-            // 2. Log failure to winston
-            this.loggingService.error(`${input.provider} request failed`, {
-                eventType: 'provider.response.failed',
-                category: 'provider',
-                phase: 'provider_response',
+            // 2. Log failure to winston. A body read can be interrupted by the same
+            // user cancellation that stopped the provider stream; keep that expected
+            // outcome out of the error channel without dropping the artifact above.
+            const classification = classifyProviderFailure(input.error);
+            const cancelled = isClassifiedCancellation(input.error);
+            const log = cancelled ? this.loggingService.debug : this.loggingService.error;
+            log.call(this.loggingService, cancelled ? `${input.provider} response aborted` : `${input.provider} request failed`, {
+                eventType: cancelled ? 'stream.aborted' : 'provider.response.failed',
+                category: cancelled ? 'stream' : 'provider',
+                phase: cancelled ? 'abort' : 'provider_response',
                 ...baseMeta,
                 error: input.error,
+                errorKind: classification.errorKind,
             });
             return;
         }
@@ -1098,6 +1317,9 @@ export class ProviderTraffic {
         if (input.receiveTiming) {
             summary = { ...summary, receiveTiming: input.receiveTiming };
         }
+        if (input.transportDiagnostics) {
+            summary = { ...summary, transportDiagnostics: input.transportDiagnostics };
+        }
         // 1. Write complete payload to artifact store
         this.#runArtifactStoreOperation('recordRequestComplete', input.requestId, () => {
             this.store.recordRequestComplete({
@@ -1147,6 +1369,7 @@ export class ProviderTraffic {
             outcome: input.outcome,
             eventCount: input.eventCount,
             ...(input.diagnostics ? input.diagnostics : {}),
+            ...(input.transportDiagnostics ? { transportDiagnostics: input.transportDiagnostics } : {}),
         };
         this.#runArtifactStoreOperation('recordRequestComplete', input.requestId, () => {
             this.store.recordRequestComplete({
@@ -1177,6 +1400,7 @@ export class ProviderTraffic {
             sessionStartedAt,
             firstUserMessagePreview,
             mode,
+            transportDiagnostics: input.transportDiagnostics,
             provider: input.provider,
             model: input.model,
             modelClass: input.modelClass,
@@ -1235,6 +1459,9 @@ export class ProviderTraffic {
         if (input.diagnostics !== undefined) {
             errorDetails.diagnostics = input.diagnostics;
         }
+        if (input.transportDiagnostics !== undefined) {
+            errorDetails.transportDiagnostics = input.transportDiagnostics;
+        }
         // 1. Write failure to artifact store
         this.#runArtifactStoreOperation('recordRequestComplete', input.requestId, () => {
             this.store.recordRequestComplete({
@@ -1251,11 +1478,14 @@ export class ProviderTraffic {
                 evaluator: isEvaluator,
             });
         });
-        // 2. Log failure to winston
-        this.loggingService.error(`${input.provider} request failed`, {
-            eventType: 'provider.response.failed',
-            category: 'provider',
-            phase: 'provider_response',
+        // 2. Log failure to winston. Cancellation remains a retained provider
+        // artifact, but is an expected stream outcome rather than an error.
+        const cancelled = isClassifiedCancellation(input.error);
+        const log = cancelled ? this.loggingService.debug : this.loggingService.error;
+        log.call(this.loggingService, cancelled ? `${input.provider} request aborted` : `${input.provider} request failed`, {
+            eventType: cancelled ? 'stream.aborted' : 'provider.response.failed',
+            category: cancelled ? 'stream' : 'provider',
+            phase: cancelled ? 'abort' : 'provider_response',
             ...baseMeta,
             error: errorDetails.message,
             errorKind: errorDetails.errorKind,