@replayci/replay 0.1.4 → 0.1.5

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -127,7 +137,7 @@ var CaptureBuffer = class {
   }
   flush() {
     if (this.closed || this.remoteDisabled) {
-      return Promise.resolve();
+      return Promise.resolve({ captured: 0, sent: 0, active: true, errors: [] });
     }
     if (this.flushPromise) {
       return this.flushPromise;
@@ -137,6 +147,7 @@ var CaptureBuffer = class {
         type: "flush_error",
         error: err instanceof Error ? err.message : String(err)
       });
+      return { captured: 0, sent: 0, active: true, errors: [err instanceof Error ? err.message : String(err)] };
     }).finally(() => {
       if (this.flushPromise === flushPromise) {
         this.flushPromise = void 0;
@@ -165,11 +176,11 @@ var CaptureBuffer = class {
   }
   async flushOnce() {
     if (this.closed || this.remoteDisabled || this.queue.length === 0) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
     const now = this.now();
     if (this.circuitOpenUntil > now) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
     if (this.circuitOpenUntil !== 0) {
       this.circuitOpenUntil = 0;
@@ -177,8 +188,9 @@ var CaptureBuffer = class {
     }
     const batch = this.queue.splice(0, Math.min(this.queue.length, MAX_BATCH_SIZE));
     if (batch.length === 0) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
+    const captured = batch.length;
     this.lastFlushAttemptMs = this.now();
     emitStateChange(this.onStateChange, { type: "flush_attempt" });
     let payload = "";
@@ -186,7 +198,7 @@ var CaptureBuffer = class {
       payload = JSON.stringify({ captures: batch });
     } catch {
       this.handleFailure("JSON serialization failed");
-      return;
+      return { captured, sent: 0, active: true, errors: ["JSON serialization failed"] };
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -209,19 +221,23 @@ var CaptureBuffer = class {
         this.circuitOpenUntil = Number.MAX_SAFE_INTEGER;
         emitDiagnostics(this.diagnostics, { type: "remote_disabled" });
         emitStateChange(this.onStateChange, { type: "remote_disabled" });
-        return;
+        return { captured, sent: 0, active: true, errors: ["remote_disabled"] };
       }
       if (!response.ok) {
-        this.handleFailure(`HTTP ${response.status}`);
-        return;
+        const msg = `HTTP ${response.status}`;
+        this.handleFailure(msg);
+        return { captured, sent: 0, active: true, errors: [msg] };
       }
       this.failureCount = 0;
       this.circuitOpenUntil = 0;
       this.lastFlushSuccessMs = this.now();
       this.lastFlushErrorMsg = null;
       emitStateChange(this.onStateChange, { type: "flush_success", batch_size: batch.length });
+      return { captured, sent: captured, active: true, errors: [] };
     } catch (err) {
-      this.handleFailure(err instanceof Error ? err.message : String(err));
+      const msg = err instanceof Error ? err.message : String(err);
+      this.handleFailure(msg);
+      return { captured, sent: 0, active: true, errors: [msg] };
     } finally {
       clearTimeout(timeout);
     }
@@ -1436,6 +1452,32 @@ function ensureDir(dir) {
 var REPLAY_WRAPPED = /* @__PURE__ */ Symbol.for("replayci.wrapped");
 var DEFAULT_AGENT = "default";
 var IDLE_HEARTBEAT_MS = 3e4;
+function defaultDiagnosticsHandler(event) {
+  switch (event.type) {
+    case "observe_inactive":
+      if (event.reason_code === "missing_api_key") {
+        console.warn(
+          "[replayci] No API key provided. observe() is inactive \u2014 calls will not be captured. Set REPLAYCI_API_KEY or pass apiKey to observe()."
+        );
+      }
+      break;
+    case "activation_warning":
+      console.warn(`[replayci] ${event.message}`);
+      break;
+    case "flush_error":
+      console.warn(`[replayci] flush failed: ${event.error}`);
+      break;
+    case "flush_empty":
+      console.warn(
+        "[replayci] flush(): No calls were captured. Ensure your LLM calls use the client returned by observe()."
+      );
+      break;
+    case "circuit_open":
+      break;
+    default:
+      break;
+  }
+}
 function observe(client, opts = {}) {
   assertSupportedNodeRuntime();
   const sessionId = generateSessionId();
@@ -1445,38 +1487,45 @@ function observe(client, opts = {}) {
     if (isDisabled(opts)) {
       return createInactiveHandle(client, sessionId, agent, "disabled", void 0, now, opts.diagnostics, opts.stateDir);
     }
+    const diagnosticsHandler = opts.diagnostics ?? defaultDiagnosticsHandler;
     const apiKey = resolveApiKey(opts);
+    if (apiKey && !/^rci_(live|test)_/.test(apiKey)) {
+      emitDiagnostic(diagnosticsHandler, {
+        type: "activation_warning",
+        message: "API key format looks wrong (expected 'rci_live_...' or 'rci_test_...'). Verify your key at app.replayci.com/settings."
+      });
+    }
     if (!apiKey) {
-      return createInactiveHandle(client, sessionId, agent, "missing_api_key", void 0, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "missing_api_key", void 0, now, diagnosticsHandler, opts.stateDir);
     }
-    const provider = detectProviderSafely(client, opts.diagnostics);
+    const provider = detectProviderSafely(client, diagnosticsHandler);
     if (!provider) {
-      return createInactiveHandle(client, sessionId, agent, "unsupported_client", "Could not detect provider.", now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", "Could not detect provider.", now, diagnosticsHandler, opts.stateDir);
     }
     const patchTarget = resolvePatchTarget(client, provider);
     if (!patchTarget) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "unsupported_client",
         mode: "observe",
         detail: `Unsupported ${provider} client shape.`
       });
-      return createInactiveHandle(client, sessionId, agent, "unsupported_client", `Unsupported ${provider} client shape.`, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", `Unsupported ${provider} client shape.`, now, diagnosticsHandler, opts.stateDir);
     }
     if (isWrapped(client, patchTarget.target)) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "double_wrap",
         mode: "observe"
       });
-      return createInactiveHandle(client, sessionId, agent, "double_wrap", void 0, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "double_wrap", void 0, now, diagnosticsHandler, opts.stateDir);
     }
     const patchabilityError = getPatchabilityError(patchTarget.target, patchTarget.methodName);
     if (patchabilityError) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "unsupported_client",
         mode: "observe",
         detail: patchabilityError
       });
-      return createInactiveHandle(client, sessionId, agent, "patch_target_unwritable", patchabilityError, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "patch_target_unwritable", patchabilityError, now, diagnosticsHandler, opts.stateDir);
     }
     const captureLevel = normalizeCaptureLevel(opts.captureLevel);
     const patchTargetName = `${provider}.${provider === "openai" ? "chat.completions.create" : "messages.create"}`;
@@ -1534,7 +1583,7 @@ function observe(client, opts = {}) {
         const detail = err instanceof Error ? err.message : "Failed to write health snapshot";
         lastHealthStoreErrorAt = (/* @__PURE__ */ new Date()).toISOString();
         lastHealthStoreError = detail;
-        emitDiagnostic(opts.diagnostics, {
+        emitDiagnostic(diagnosticsHandler, {
           type: "health_store_error",
           detail
         });
@@ -1574,7 +1623,7 @@ function observe(client, opts = {}) {
           runtimeState.consecutive_failures = 0;
           runtimeState.circuit_open_until = null;
           runtimeState.queue_size = buffer.size;
-          emitDiagnostic(opts.diagnostics, {
+          emitDiagnostic(diagnosticsHandler, {
             type: "flush_succeeded",
             batch_size: event.batch_size
           });
@@ -1610,7 +1659,7 @@ function observe(client, opts = {}) {
       maxBuffer: opts.maxBuffer,
       flushMs: opts.flushMs,
       timeoutMs: opts.timeoutMs,
-      diagnostics: opts.diagnostics,
+      diagnostics: diagnosticsHandler,
       onStateChange: onBufferStateChange
     });
     registerBeforeExit(buffer);
@@ -1634,7 +1683,7 @@ function observe(client, opts = {}) {
     persistHealthEvent();
     safeRunJanitor(sessionsDir, sessionId);
     startHeartbeat();
-    emitDiagnostic(opts.diagnostics, {
+    emitDiagnostic(diagnosticsHandler, {
       type: "observe_activated",
       session_id: sessionId,
       provider,
@@ -1657,7 +1706,7 @@ function observe(client, opts = {}) {
           sessionId,
           runtimeState,
           persistHealthEvent,
-          diagnostics: opts.diagnostics
+          diagnostics: diagnosticsHandler
         });
         return response;
       });
@@ -1667,8 +1716,12 @@ function observe(client, opts = {}) {
     let restored = false;
     return {
       client,
-      flush() {
-        return buffer.flush();
+      async flush() {
+        const result = await buffer.flush();
+        if (result.captured === 0 && result.errors.length === 0) {
+          emitDiagnostic(diagnosticsHandler, { type: "flush_empty" });
+        }
+        return result;
       },
       restore() {
         if (restored) {
@@ -1707,7 +1760,7 @@ function observe(client, opts = {}) {
     };
   } catch (err) {
     const detail = err instanceof Error ? err.message : "Unknown internal error";
-    return createInactiveHandle(client, sessionId, agent, "internal_error", detail, now, opts.diagnostics, opts.stateDir);
+    return createInactiveHandle(client, sessionId, agent, "internal_error", detail, now, opts.diagnostics ?? defaultDiagnosticsHandler, opts.stateDir);
   }
 }
 function createInactiveHandle(client, sessionId, agent, reasonCode, detail, activatedAt, diagnostics, stateDir) {
@@ -1734,7 +1787,7 @@ function createInactiveHandle(client, sessionId, agent, reasonCode, detail, acti
   return {
     client,
     flush() {
-      return Promise.resolve();
+      return Promise.resolve({ captured: 0, sent: 0, active: false, errors: [] });
     },
     restore() {
     },
@@ -2126,6 +2179,14 @@ var import_contracts_core3 = require("@replayci/contracts-core");
 var import_contracts_core2 = require("@replayci/contracts-core");
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
+
+// src/safeRegex.ts
+var import_re2 = __toESM(require("re2"), 1);
+function safeRegex(pattern) {
+  return new import_re2.default(pattern);
+}
+
+// src/contracts.ts
 var CONTRACT_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml"]);
 var MAX_REGEX_BYTES = 1024;
 var NESTED_QUANTIFIER_RE = /\((?:[^()\\]|\\.)*[+*{](?:[^()\\]|\\.)*\)(?:[+*]|\{\d+(?:,\d*)?\})/;
@@ -2319,7 +2380,7 @@ function validateSafeRegexes(contract) {
         );
       }
       try {
-        void new RegExp(invariant.regex);
+        void safeRegex(invariant.regex);
       } catch (error) {
         throw new ReplayConfigurationError(
           `Invalid regex in ${contractLabel} (${group.label}, ${invariant.path}): ${formatErrorMessage(error)}`

package/dist/index.d.cts

@@ -1,5 +1,15 @@
 import { Contract } from '@replayci/contracts-core';
 
+interface FlushResult {
+    /** Number of captures in the buffer when flush was called */
+    captured: number;
+    /** Number of captures successfully sent to the server */
+    sent: number;
+    /** Whether the handle is active (false = no apiKey or disabled) */
+    active: boolean;
+    /** Error messages from send attempts */
+    errors: string[];
+}
 type ContractFailure = {
     path: string;
     operator: string;
@@ -93,6 +103,11 @@ type ObserveDiagnosticEvent = {
     type: "unsupported_client";
     mode: "observe";
     detail: string;
+} | {
+    type: "activation_warning";
+    message: string;
+} | {
+    type: "flush_empty";
 };
 type ObserveOptions = {
     agent?: string;
@@ -109,7 +124,7 @@ type ObserveOptions = {
 };
 type ObserveHandle<T> = {
     client: T;
-    flush: () => Promise<void>;
+    flush: () => Promise<FlushResult>;
     restore: () => void;
     getHealth: () => ObserveHealthSnapshot;
 };
@@ -123,4 +138,4 @@ type ValidateOptions = {
 declare function prepareContracts(input: string | string[] | Contract | Contract[]): Contract[];
 declare function validate(response: unknown, opts?: ValidateOptions): ValidationResult;
 
-export { type ContractFailure, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type ValidationResult, observe, prepareContracts, validate };
+export { type ContractFailure, type FlushResult, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type ValidationResult, observe, prepareContracts, validate };

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 import { Contract } from '@replayci/contracts-core';
 
+interface FlushResult {
+    /** Number of captures in the buffer when flush was called */
+    captured: number;
+    /** Number of captures successfully sent to the server */
+    sent: number;
+    /** Whether the handle is active (false = no apiKey or disabled) */
+    active: boolean;
+    /** Error messages from send attempts */
+    errors: string[];
+}
 type ContractFailure = {
     path: string;
     operator: string;
@@ -93,6 +103,11 @@ type ObserveDiagnosticEvent = {
     type: "unsupported_client";
     mode: "observe";
     detail: string;
+} | {
+    type: "activation_warning";
+    message: string;
+} | {
+    type: "flush_empty";
 };
 type ObserveOptions = {
     agent?: string;
@@ -109,7 +124,7 @@ type ObserveOptions = {
 };
 type ObserveHandle<T> = {
     client: T;
-    flush: () => Promise<void>;
+    flush: () => Promise<FlushResult>;
     restore: () => void;
     getHealth: () => ObserveHealthSnapshot;
 };
@@ -123,4 +138,4 @@ type ValidateOptions = {
 declare function prepareContracts(input: string | string[] | Contract | Contract[]): Contract[];
 declare function validate(response: unknown, opts?: ValidateOptions): ValidationResult;
 
-export { type ContractFailure, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type ValidationResult, observe, prepareContracts, validate };
+export { type ContractFailure, type FlushResult, type ObserveActivationReasonCode, type ObserveDiagnosticEvent, type ObserveHandle, type ObserveHealthSnapshot, type ObserveOptions, type ObserveSessionState, type ValidationResult, observe, prepareContracts, validate };

package/dist/index.js

@@ -99,7 +99,7 @@ var CaptureBuffer = class {
   }
   flush() {
     if (this.closed || this.remoteDisabled) {
-      return Promise.resolve();
+      return Promise.resolve({ captured: 0, sent: 0, active: true, errors: [] });
     }
     if (this.flushPromise) {
       return this.flushPromise;
@@ -109,6 +109,7 @@ var CaptureBuffer = class {
         type: "flush_error",
         error: err instanceof Error ? err.message : String(err)
       });
+      return { captured: 0, sent: 0, active: true, errors: [err instanceof Error ? err.message : String(err)] };
     }).finally(() => {
       if (this.flushPromise === flushPromise) {
         this.flushPromise = void 0;
@@ -137,11 +138,11 @@ var CaptureBuffer = class {
   }
   async flushOnce() {
     if (this.closed || this.remoteDisabled || this.queue.length === 0) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
     const now = this.now();
     if (this.circuitOpenUntil > now) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
     if (this.circuitOpenUntil !== 0) {
       this.circuitOpenUntil = 0;
@@ -149,8 +150,9 @@ var CaptureBuffer = class {
     }
     const batch = this.queue.splice(0, Math.min(this.queue.length, MAX_BATCH_SIZE));
     if (batch.length === 0) {
-      return;
+      return { captured: 0, sent: 0, active: true, errors: [] };
     }
+    const captured = batch.length;
     this.lastFlushAttemptMs = this.now();
     emitStateChange(this.onStateChange, { type: "flush_attempt" });
     let payload = "";
@@ -158,7 +160,7 @@ var CaptureBuffer = class {
       payload = JSON.stringify({ captures: batch });
     } catch {
       this.handleFailure("JSON serialization failed");
-      return;
+      return { captured, sent: 0, active: true, errors: ["JSON serialization failed"] };
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -181,19 +183,23 @@ var CaptureBuffer = class {
         this.circuitOpenUntil = Number.MAX_SAFE_INTEGER;
         emitDiagnostics(this.diagnostics, { type: "remote_disabled" });
         emitStateChange(this.onStateChange, { type: "remote_disabled" });
-        return;
+        return { captured, sent: 0, active: true, errors: ["remote_disabled"] };
       }
       if (!response.ok) {
-        this.handleFailure(`HTTP ${response.status}`);
-        return;
+        const msg = `HTTP ${response.status}`;
+        this.handleFailure(msg);
+        return { captured, sent: 0, active: true, errors: [msg] };
       }
       this.failureCount = 0;
       this.circuitOpenUntil = 0;
       this.lastFlushSuccessMs = this.now();
       this.lastFlushErrorMsg = null;
       emitStateChange(this.onStateChange, { type: "flush_success", batch_size: batch.length });
+      return { captured, sent: captured, active: true, errors: [] };
     } catch (err) {
-      this.handleFailure(err instanceof Error ? err.message : String(err));
+      const msg = err instanceof Error ? err.message : String(err);
+      this.handleFailure(msg);
+      return { captured, sent: 0, active: true, errors: [msg] };
     } finally {
       clearTimeout(timeout);
     }
@@ -1418,6 +1424,32 @@ function ensureDir(dir) {
 var REPLAY_WRAPPED = /* @__PURE__ */ Symbol.for("replayci.wrapped");
 var DEFAULT_AGENT = "default";
 var IDLE_HEARTBEAT_MS = 3e4;
+function defaultDiagnosticsHandler(event) {
+  switch (event.type) {
+    case "observe_inactive":
+      if (event.reason_code === "missing_api_key") {
+        console.warn(
+          "[replayci] No API key provided. observe() is inactive \u2014 calls will not be captured. Set REPLAYCI_API_KEY or pass apiKey to observe()."
+        );
+      }
+      break;
+    case "activation_warning":
+      console.warn(`[replayci] ${event.message}`);
+      break;
+    case "flush_error":
+      console.warn(`[replayci] flush failed: ${event.error}`);
+      break;
+    case "flush_empty":
+      console.warn(
+        "[replayci] flush(): No calls were captured. Ensure your LLM calls use the client returned by observe()."
+      );
+      break;
+    case "circuit_open":
+      break;
+    default:
+      break;
+  }
+}
 function observe(client, opts = {}) {
   assertSupportedNodeRuntime();
   const sessionId = generateSessionId();
@@ -1427,38 +1459,45 @@ function observe(client, opts = {}) {
     if (isDisabled(opts)) {
       return createInactiveHandle(client, sessionId, agent, "disabled", void 0, now, opts.diagnostics, opts.stateDir);
     }
+    const diagnosticsHandler = opts.diagnostics ?? defaultDiagnosticsHandler;
     const apiKey = resolveApiKey(opts);
+    if (apiKey && !/^rci_(live|test)_/.test(apiKey)) {
+      emitDiagnostic(diagnosticsHandler, {
+        type: "activation_warning",
+        message: "API key format looks wrong (expected 'rci_live_...' or 'rci_test_...'). Verify your key at app.replayci.com/settings."
+      });
+    }
     if (!apiKey) {
-      return createInactiveHandle(client, sessionId, agent, "missing_api_key", void 0, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "missing_api_key", void 0, now, diagnosticsHandler, opts.stateDir);
     }
-    const provider = detectProviderSafely(client, opts.diagnostics);
+    const provider = detectProviderSafely(client, diagnosticsHandler);
     if (!provider) {
-      return createInactiveHandle(client, sessionId, agent, "unsupported_client", "Could not detect provider.", now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", "Could not detect provider.", now, diagnosticsHandler, opts.stateDir);
     }
     const patchTarget = resolvePatchTarget(client, provider);
     if (!patchTarget) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "unsupported_client",
         mode: "observe",
         detail: `Unsupported ${provider} client shape.`
       });
-      return createInactiveHandle(client, sessionId, agent, "unsupported_client", `Unsupported ${provider} client shape.`, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", `Unsupported ${provider} client shape.`, now, diagnosticsHandler, opts.stateDir);
     }
     if (isWrapped(client, patchTarget.target)) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "double_wrap",
         mode: "observe"
       });
-      return createInactiveHandle(client, sessionId, agent, "double_wrap", void 0, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "double_wrap", void 0, now, diagnosticsHandler, opts.stateDir);
     }
     const patchabilityError = getPatchabilityError(patchTarget.target, patchTarget.methodName);
     if (patchabilityError) {
-      emitDiagnostic(opts.diagnostics, {
+      emitDiagnostic(diagnosticsHandler, {
         type: "unsupported_client",
         mode: "observe",
         detail: patchabilityError
       });
-      return createInactiveHandle(client, sessionId, agent, "patch_target_unwritable", patchabilityError, now, opts.diagnostics, opts.stateDir);
+      return createInactiveHandle(client, sessionId, agent, "patch_target_unwritable", patchabilityError, now, diagnosticsHandler, opts.stateDir);
     }
     const captureLevel = normalizeCaptureLevel(opts.captureLevel);
     const patchTargetName = `${provider}.${provider === "openai" ? "chat.completions.create" : "messages.create"}`;
@@ -1516,7 +1555,7 @@ function observe(client, opts = {}) {
         const detail = err instanceof Error ? err.message : "Failed to write health snapshot";
         lastHealthStoreErrorAt = (/* @__PURE__ */ new Date()).toISOString();
         lastHealthStoreError = detail;
-        emitDiagnostic(opts.diagnostics, {
+        emitDiagnostic(diagnosticsHandler, {
           type: "health_store_error",
           detail
         });
@@ -1556,7 +1595,7 @@ function observe(client, opts = {}) {
           runtimeState.consecutive_failures = 0;
           runtimeState.circuit_open_until = null;
           runtimeState.queue_size = buffer.size;
-          emitDiagnostic(opts.diagnostics, {
+          emitDiagnostic(diagnosticsHandler, {
             type: "flush_succeeded",
             batch_size: event.batch_size
           });
@@ -1592,7 +1631,7 @@ function observe(client, opts = {}) {
       maxBuffer: opts.maxBuffer,
       flushMs: opts.flushMs,
       timeoutMs: opts.timeoutMs,
-      diagnostics: opts.diagnostics,
+      diagnostics: diagnosticsHandler,
       onStateChange: onBufferStateChange
     });
     registerBeforeExit(buffer);
@@ -1616,7 +1655,7 @@ function observe(client, opts = {}) {
     persistHealthEvent();
     safeRunJanitor(sessionsDir, sessionId);
     startHeartbeat();
-    emitDiagnostic(opts.diagnostics, {
+    emitDiagnostic(diagnosticsHandler, {
       type: "observe_activated",
       session_id: sessionId,
       provider,
@@ -1639,7 +1678,7 @@ function observe(client, opts = {}) {
           sessionId,
           runtimeState,
           persistHealthEvent,
-          diagnostics: opts.diagnostics
+          diagnostics: diagnosticsHandler
         });
         return response;
       });
@@ -1649,8 +1688,12 @@ function observe(client, opts = {}) {
     let restored = false;
     return {
       client,
-      flush() {
-        return buffer.flush();
+      async flush() {
+        const result = await buffer.flush();
+        if (result.captured === 0 && result.errors.length === 0) {
+          emitDiagnostic(diagnosticsHandler, { type: "flush_empty" });
+        }
+        return result;
       },
       restore() {
         if (restored) {
@@ -1689,7 +1732,7 @@ function observe(client, opts = {}) {
     };
   } catch (err) {
     const detail = err instanceof Error ? err.message : "Unknown internal error";
-    return createInactiveHandle(client, sessionId, agent, "internal_error", detail, now, opts.diagnostics, opts.stateDir);
+    return createInactiveHandle(client, sessionId, agent, "internal_error", detail, now, opts.diagnostics ?? defaultDiagnosticsHandler, opts.stateDir);
   }
 }
 function createInactiveHandle(client, sessionId, agent, reasonCode, detail, activatedAt, diagnostics, stateDir) {
@@ -1716,7 +1759,7 @@ function createInactiveHandle(client, sessionId, agent, reasonCode, detail, acti
   return {
     client,
     flush() {
-      return Promise.resolve();
+      return Promise.resolve({ captured: 0, sent: 0, active: false, errors: [] });
     },
     restore() {
     },
@@ -2124,6 +2167,14 @@ import {
   relative,
   resolve
 } from "path";
+
+// src/safeRegex.ts
+import RE2 from "re2";
+function safeRegex(pattern) {
+  return new RE2(pattern);
+}
+
+// src/contracts.ts
 var CONTRACT_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml"]);
 var MAX_REGEX_BYTES = 1024;
 var NESTED_QUANTIFIER_RE = /\((?:[^()\\]|\\.)*[+*{](?:[^()\\]|\\.)*\)(?:[+*]|\{\d+(?:,\d*)?\})/;
@@ -2317,7 +2368,7 @@ function validateSafeRegexes(contract) {
         );
       }
       try {
-        void new RegExp(invariant.regex);
+        void safeRegex(invariant.regex);
       } catch (error) {
         throw new ReplayConfigurationError(
           `Invalid regex in ${contractLabel} (${group.label}, ${invariant.path}): ${formatErrorMessage(error)}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayci/replay",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "ReplayCI SDK for deterministic tool-call validation and observation.",
   "license": "ISC",
   "author": "ReplayCI",
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@replayci/contracts-core": "^0.1.0",
+    "re2": "^1.20.0",
     "yaml": "^2.0.0"
   },
   "peerDependencies": {
@@ -65,9 +66,6 @@
       "optional": true
     }
   },
-  "optionalDependencies": {
-    "re2": "^1.20.0"
-  },
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",