@replayci/replay 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -50,6 +50,7 @@ var CaptureBuffer = class {
   apiKey;
   endpoint;
   diagnostics;
+  onStateChange;
   fetchImpl;
   now;
   queue = [];
@@ -59,6 +60,11 @@ var CaptureBuffer = class {
   circuitOpenUntil = 0;
   remoteDisabled = false;
   closed = false;
+  droppedOverflowTotal = 0;
+  lastFlushAttemptMs = 0;
+  lastFlushSuccessMs = 0;
+  lastFlushErrorMs = 0;
+  lastFlushErrorMsg = null;
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.endpoint = normalizeEndpoint(opts.endpoint);
@@ -69,6 +75,7 @@ var CaptureBuffer = class {
       MAX_SEND_TIMEOUT
     );
     this.diagnostics = opts.diagnostics;
+    this.onStateChange = opts.onStateChange;
     this.fetchImpl = opts.fetchImpl ?? fetch;
     this.now = opts.now ?? Date.now;
     this.scheduleNextDrain();
@@ -85,6 +92,21 @@ var CaptureBuffer = class {
   get isRemoteDisabled() {
     return this.remoteDisabled;
   }
+  get droppedOverflow() {
+    return this.droppedOverflowTotal;
+  }
+  get lastFlushAttemptAt() {
+    return this.lastFlushAttemptMs;
+  }
+  get lastFlushSuccessAt() {
+    return this.lastFlushSuccessMs;
+  }
+  get lastFlushErrorAt() {
+    return this.lastFlushErrorMs;
+  }
+  get lastFlushError() {
+    return this.lastFlushErrorMsg;
+  }
   push(item) {
     if (this.closed || this.remoteDisabled) {
       return;
@@ -94,10 +116,12 @@ var CaptureBuffer = class {
     }
     if (this.queue.length >= this.maxBuffer) {
       this.queue.shift();
+      this.droppedOverflowTotal += 1;
       emitDiagnostics(this.diagnostics, {
         type: "buffer_overflow",
         dropped: 1
       });
+      emitStateChange(this.onStateChange, { type: "buffer_overflow", dropped: 1 });
     }
     this.queue.push(item);
   }
@@ -155,11 +179,13 @@ var CaptureBuffer = class {
     if (batch.length === 0) {
       return;
     }
+    this.lastFlushAttemptMs = this.now();
+    emitStateChange(this.onStateChange, { type: "flush_attempt" });
     let payload = "";
     try {
       payload = JSON.stringify({ captures: batch });
     } catch {
-      this.handleFailure();
+      this.handleFailure("JSON serialization failed");
       return;
     }
     const controller = new AbortController();
@@ -181,22 +207,35 @@ var CaptureBuffer = class {
         this.clearTimer();
         this.failureCount = 0;
         this.circuitOpenUntil = Number.MAX_SAFE_INTEGER;
+        emitDiagnostics(this.diagnostics, { type: "remote_disabled" });
+        emitStateChange(this.onStateChange, { type: "remote_disabled" });
         return;
       }
       if (!response.ok) {
-        this.handleFailure();
+        this.handleFailure(`HTTP ${response.status}`);
         return;
       }
       this.failureCount = 0;
       this.circuitOpenUntil = 0;
-    } catch {
-      this.handleFailure();
+      this.lastFlushSuccessMs = this.now();
+      this.lastFlushErrorMsg = null;
+      emitStateChange(this.onStateChange, { type: "flush_success", batch_size: batch.length });
+    } catch (err) {
+      this.handleFailure(err instanceof Error ? err.message : String(err));
     } finally {
       clearTimeout(timeout);
     }
   }
-  handleFailure() {
+  handleFailure(errorMsg) {
     this.failureCount += 1;
+    const errorStr = errorMsg ?? "unknown error";
+    this.lastFlushErrorMs = this.now();
+    this.lastFlushErrorMsg = errorStr;
+    emitDiagnostics(this.diagnostics, {
+      type: "flush_error",
+      error: errorStr
+    });
+    emitStateChange(this.onStateChange, { type: "flush_error", error: errorStr });
     if (this.failureCount >= CIRCUIT_BREAKER_FAILURE_LIMIT) {
       this.circuitOpenUntil = this.now() + CIRCUIT_BREAKER_MS;
       emitDiagnostics(this.diagnostics, {
@@ -204,6 +243,12 @@ var CaptureBuffer = class {
         failures: this.failureCount,
         backoffMs: CIRCUIT_BREAKER_MS
       });
+      emitStateChange(this.onStateChange, {
+        type: "circuit_open",
+        failures: this.failureCount,
+        backoffMs: CIRCUIT_BREAKER_MS,
+        openUntil: this.circuitOpenUntil
+      });
       try {
         console.warn(
           `[replayci] Capture buffer circuit breaker open after ${this.failureCount} consecutive failures. Captures will be dropped for ${CIRCUIT_BREAKER_MS / 6e4} minutes.`
@@ -283,6 +328,12 @@ function emitDiagnostics(diagnostics, event) {
   } catch {
   }
 }
+function emitStateChange(listener, event) {
+  try {
+    listener?.(event);
+  } catch {
+  }
+}
 function isRemoteDisable(response) {
   return response.headers.get("x-replayci-disable")?.toLowerCase() === "true";
 }
@@ -933,7 +984,8 @@ function parseNodeMajorVersion(nodeVersion) {
 
 // src/captureSchema.ts
 var CAPTURE_SCHEMA_VERSION_LEGACY = "2026-03-04";
-var CAPTURE_SCHEMA_VERSION_CURRENT = "2026-03-06";
+var CAPTURE_SCHEMA_VERSION_V2 = "2026-03-06";
+var CAPTURE_SCHEMA_VERSION_CURRENT = "2026-03-09";
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -1097,9 +1149,19 @@ function validateUsage(value, path) {
     total_tokens: requireNonNegativeInt(usage.total_tokens, `${path}.total_tokens`)
   };
 }
+function optionalString(value, path) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${path} must be a string when provided`);
+  }
+  return value;
+}
 function parseCommonCapture(capture, index, modelId, schemaVersion) {
   const toolNames = requireStringArray(capture.tool_names, `captures[${index}].tool_names`);
   const primaryToolName = capture.primary_tool_name === void 0 ? toolNames[0] ?? null : nullableString(capture.primary_tool_name, `captures[${index}].primary_tool_name`);
+  const sdkSessionId = optionalString(capture.sdk_session_id, `captures[${index}].sdk_session_id`);
   return {
     schema_version: schemaVersion,
     agent: requireString(capture.agent, `captures[${index}].agent`),
@@ -1112,7 +1174,8 @@ function parseCommonCapture(capture, index, modelId, schemaVersion) {
     response: validateResponse(capture.response, `captures[${index}].response`),
     ...capture.validation !== void 0 ? { validation: validateValidation(capture.validation, `captures[${index}].validation`) } : {},
     ...capture.usage !== void 0 ? { usage: validateUsage(capture.usage, `captures[${index}].usage`) } : {},
-    latency_ms: requireNonNegativeInt(capture.latency_ms, `captures[${index}].latency_ms`)
+    latency_ms: requireNonNegativeInt(capture.latency_ms, `captures[${index}].latency_ms`),
+    ...sdkSessionId !== void 0 ? { sdk_session_id: sdkSessionId } : {}
   };
 }
 function parseLegacyCapturedCall(capture, index) {
@@ -1123,6 +1186,14 @@ function parseLegacyCapturedCall(capture, index) {
     CAPTURE_SCHEMA_VERSION_LEGACY
   );
 }
+function parseV2CapturedCall(capture, index) {
+  return parseCommonCapture(
+    capture,
+    index,
+    requireString(capture.model_id, `captures[${index}].model_id`),
+    CAPTURE_SCHEMA_VERSION_V2
+  );
+}
 function parseCurrentCapturedCall(capture, index) {
   return parseCommonCapture(
     capture,
@@ -1133,25 +1204,254 @@ function parseCurrentCapturedCall(capture, index) {
 }
 var CAPTURE_SCHEMA_PARSERS = {
   [CAPTURE_SCHEMA_VERSION_LEGACY]: parseLegacyCapturedCall,
+  [CAPTURE_SCHEMA_VERSION_V2]: parseV2CapturedCall,
   [CAPTURE_SCHEMA_VERSION_CURRENT]: parseCurrentCapturedCall
 };
 
+// src/healthStore.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_meta = {};
+var SESSIONS_DIR = "observe-sessions";
+var SCHEMA_VERSION = "1.0";
+var JANITOR_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+function generateSessionId() {
+  return `obs_${(0, import_node_crypto.randomBytes)(12).toString("hex")}`;
+}
+function resolveStateDir(opts) {
+  let explicit;
+  let workDir;
+  if (typeof opts === "string") {
+    workDir = opts;
+  } else if (opts != null) {
+    explicit = opts.stateDir;
+    workDir = opts.cwd;
+  }
+  if (typeof explicit === "string" && explicit.length > 0) {
+    return explicit;
+  }
+  const envValue = typeof process !== "undefined" ? process.env.REPLAYCI_STATE_DIR : void 0;
+  if (typeof envValue === "string" && envValue.length > 0) {
+    return envValue;
+  }
+  const base = workDir ?? process.cwd();
+  return (0, import_node_path.join)(base, ".replayci", "runtime");
+}
+function resolveSessionsDir(stateDir) {
+  return (0, import_node_path.join)(stateDir, SESSIONS_DIR);
+}
+function sessionFilePath(sessionsDir, sessionId) {
+  return (0, import_node_path.join)(sessionsDir, `${sessionId}.json`);
+}
+function writeHealthSnapshot(sessionsDir, sessionId, snapshot) {
+  ensureDir(sessionsDir);
+  const destPath = sessionFilePath(sessionsDir, sessionId);
+  const tmpPath = (0, import_node_path.join)(sessionsDir, `.tmp_${sessionId}_${(0, import_node_crypto.randomBytes)(4).toString("hex")}.json`);
+  const content = JSON.stringify(snapshot, null, 2);
+  const fd = (0, import_node_fs.openSync)(tmpPath, "w", 384);
+  try {
+    (0, import_node_fs.writeFileSync)(fd, content);
+    (0, import_node_fs.fsyncSync)(fd);
+  } finally {
+    (0, import_node_fs.closeSync)(fd);
+  }
+  (0, import_node_fs.renameSync)(tmpPath, destPath);
+}
+function parseHealthFile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isValidHealthSnapshot(parsed)) {
+    return null;
+  }
+  return parsed;
+}
+function isValidHealthSnapshot(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const obj = value;
+  if (obj.schema_version !== SCHEMA_VERSION) {
+    return false;
+  }
+  if (typeof obj.session_id !== "string" || obj.session_id.length === 0) {
+    return false;
+  }
+  if (typeof obj.agent !== "string") {
+    return false;
+  }
+  const validProviders = ["openai", "anthropic", null];
+  if (!validProviders.includes(obj.provider)) {
+    return false;
+  }
+  const validStates = ["active", "inactive", "stopped", "stale"];
+  if (typeof obj.state !== "string" || !validStates.includes(obj.state)) {
+    return false;
+  }
+  if (!isValidActivation(obj.activation)) {
+    return false;
+  }
+  if (!isValidProcess(obj.process)) {
+    return false;
+  }
+  if (!isValidRuntime(obj.runtime)) {
+    return false;
+  }
+  if (typeof obj.last_heartbeat_at !== "string") {
+    return false;
+  }
+  return true;
+}
+function isValidActivation(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const act = value;
+  if (typeof act.active !== "boolean") {
+    return false;
+  }
+  const validReasons = [
+    "active",
+    "disabled",
+    "missing_api_key",
+    "unsupported_client",
+    "double_wrap",
+    "patch_target_unwritable",
+    "internal_error"
+  ];
+  if (typeof act.reason_code !== "string" || !validReasons.includes(act.reason_code)) {
+    return false;
+  }
+  if (typeof act.activated_at !== "string") {
+    return false;
+  }
+  return true;
+}
+function isValidProcess(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const proc = value;
+  if (typeof proc.cwd !== "string") {
+    return false;
+  }
+  if (typeof proc.node_version !== "string") {
+    return false;
+  }
+  if (typeof proc.sdk_version !== "string") {
+    return false;
+  }
+  return true;
+}
+function isValidRuntime(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const rt = value;
+  if (typeof rt.captures_seen !== "number") {
+    return false;
+  }
+  if (typeof rt.dropped_overflow !== "number") {
+    return false;
+  }
+  if (typeof rt.queue_size !== "number") {
+    return false;
+  }
+  if (typeof rt.consecutive_failures !== "number") {
+    return false;
+  }
+  if (typeof rt.remote_disabled !== "boolean") {
+    return false;
+  }
+  return true;
+}
+function runJanitor(sessionsDir, currentSessionId, now) {
+  try {
+    if (!(0, import_node_fs.existsSync)(sessionsDir)) {
+      return;
+    }
+    const nowMs = now ?? Date.now();
+    const entries = (0, import_node_fs.readdirSync)(sessionsDir);
+    for (const entry of entries) {
+      if (!entry.endsWith(".json") || entry.startsWith(".tmp_")) {
+        continue;
+      }
+      const sessionId = entry.replace(/\.json$/, "");
+      if (sessionId === currentSessionId) {
+        continue;
+      }
+      const filePath = (0, import_node_path.join)(sessionsDir, entry);
+      let snapshot = null;
+      try {
+        const raw = (0, import_node_fs.readFileSync)(filePath, "utf-8");
+        snapshot = parseHealthFile(raw);
+      } catch {
+        continue;
+      }
+      if (!snapshot) {
+        continue;
+      }
+      const isTerminal = snapshot.state === "stopped" || snapshot.state === "stale";
+      if (!isTerminal) {
+        continue;
+      }
+      const heartbeatAge = nowMs - new Date(snapshot.last_heartbeat_at).getTime();
+      if (heartbeatAge < JANITOR_TTL_MS) {
+        continue;
+      }
+      try {
+        (0, import_node_fs.unlinkSync)(filePath);
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function getSdkVersion() {
+  try {
+    const url = new URL("../package.json", import_meta.url);
+    const raw = (0, import_node_fs.readFileSync)(url, "utf-8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function ensureDir(dir) {
+  try {
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  } catch (err) {
+    if (err.code !== "EEXIST") {
+      throw err;
+    }
+  }
+}
+
 // src/observe.ts
 var REPLAY_WRAPPED = /* @__PURE__ */ Symbol.for("replayci.wrapped");
 var DEFAULT_AGENT = "default";
+var IDLE_HEARTBEAT_MS = 3e4;
 function observe(client, opts = {}) {
   assertSupportedNodeRuntime();
+  const sessionId = generateSessionId();
+  const agent = typeof opts.agent === "string" && opts.agent.length > 0 ? opts.agent : DEFAULT_AGENT;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
   try {
     if (isDisabled(opts)) {
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "disabled", void 0, now, opts.diagnostics, opts.stateDir);
     }
     const apiKey = resolveApiKey(opts);
     if (!apiKey) {
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "missing_api_key", void 0, now, opts.diagnostics, opts.stateDir);
     }
     const provider = detectProviderSafely(client, opts.diagnostics);
     if (!provider) {
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", "Could not detect provider.", now, opts.diagnostics, opts.stateDir);
     }
     const patchTarget = resolvePatchTarget(client, provider);
     if (!patchTarget) {
@@ -1160,14 +1460,14 @@ function observe(client, opts = {}) {
         mode: "observe",
         detail: `Unsupported ${provider} client shape.`
       });
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "unsupported_client", `Unsupported ${provider} client shape.`, now, opts.diagnostics, opts.stateDir);
     }
     if (isWrapped(client, patchTarget.target)) {
       emitDiagnostic(opts.diagnostics, {
         type: "double_wrap",
         mode: "observe"
       });
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "double_wrap", void 0, now, opts.diagnostics, opts.stateDir);
     }
     const patchabilityError = getPatchabilityError(patchTarget.target, patchTarget.methodName);
     if (patchabilityError) {
@@ -1176,19 +1476,171 @@ function observe(client, opts = {}) {
         mode: "observe",
         detail: patchabilityError
       });
-      return createNoopHandle(client);
+      return createInactiveHandle(client, sessionId, agent, "patch_target_unwritable", patchabilityError, now, opts.diagnostics, opts.stateDir);
     }
     const captureLevel = normalizeCaptureLevel(opts.captureLevel);
-    const agent = typeof opts.agent === "string" && opts.agent.length > 0 ? opts.agent : DEFAULT_AGENT;
+    const patchTargetName = `${provider}.${provider === "openai" ? "chat.completions.create" : "messages.create"}`;
+    const runtimeState = {
+      captures_seen: 0,
+      dropped_overflow: 0,
+      last_capture_at: null,
+      last_flush_attempt_at: null,
+      last_flush_success_at: null,
+      last_flush_error_at: null,
+      last_flush_error: null,
+      queue_size: 0,
+      consecutive_failures: 0,
+      circuit_open_until: null,
+      remote_disabled: false
+    };
+    let lastHealthStoreErrorAt = null;
+    let lastHealthStoreError = null;
+    const sessionsDir = resolveSessionsDir(
+      resolveStateDir(opts.stateDir ? { stateDir: opts.stateDir } : void 0)
+    );
+    const buildCurrentSnapshot = () => ({
+      schema_version: "1.0",
+      session_id: sessionId,
+      agent,
+      provider,
+      patch_target: patchTargetName,
+      state: "active",
+      activation: {
+        active: true,
+        reason_code: "active",
+        activated_at: now
+      },
+      process: {
+        pid: typeof process !== "undefined" ? process.pid : null,
+        cwd: typeof process !== "undefined" ? process.cwd() : "",
+        node_version: typeof process !== "undefined" ? process.versions?.node ?? "" : "",
+        sdk_version: getSdkVersion()
+      },
+      runtime: { ...runtimeState },
+      stopped_at: null,
+      last_heartbeat_at: (/* @__PURE__ */ new Date()).toISOString(),
+      last_health_store_error_at: lastHealthStoreErrorAt,
+      last_health_store_error: lastHealthStoreError
+    });
+    const persistHealth = (snapshot) => {
+      const s = snapshot ?? buildCurrentSnapshot();
+      try {
+        writeHealthSnapshot(sessionsDir, sessionId, s);
+        if (lastHealthStoreErrorAt !== null) {
+          lastHealthStoreErrorAt = null;
+          lastHealthStoreError = null;
+        }
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : "Failed to write health snapshot";
+        lastHealthStoreErrorAt = (/* @__PURE__ */ new Date()).toISOString();
+        lastHealthStoreError = detail;
+        emitDiagnostic(opts.diagnostics, {
+          type: "health_store_error",
+          detail
+        });
+      }
+    };
+    let lastEventWriteAt = Date.now();
+    let heartbeatTimer;
+    const persistHealthEvent = () => {
+      lastEventWriteAt = Date.now();
+      persistHealth();
+    };
+    const startHeartbeat = () => {
+      heartbeatTimer = setInterval(() => {
+        const sinceLast = Date.now() - lastEventWriteAt;
+        if (sinceLast >= IDLE_HEARTBEAT_MS) {
+          persistHealth();
+        }
+      }, IDLE_HEARTBEAT_MS);
+      unrefTimerHandle(heartbeatTimer);
+    };
+    const stopHeartbeat = () => {
+      if (heartbeatTimer !== void 0) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = void 0;
+      }
+    };
+    const onBufferStateChange = (event) => {
+      if (restored) return;
+      switch (event.type) {
+        case "flush_attempt":
+          runtimeState.last_flush_attempt_at = (/* @__PURE__ */ new Date()).toISOString();
+          persistHealthEvent();
+          break;
+        case "flush_success":
+          runtimeState.last_flush_success_at = (/* @__PURE__ */ new Date()).toISOString();
+          runtimeState.last_flush_error = null;
+          runtimeState.consecutive_failures = 0;
+          runtimeState.circuit_open_until = null;
+          runtimeState.queue_size = buffer.size;
+          emitDiagnostic(opts.diagnostics, {
+            type: "flush_succeeded",
+            batch_size: event.batch_size
+          });
+          persistHealthEvent();
+          break;
+        case "flush_error":
+          runtimeState.last_flush_error_at = (/* @__PURE__ */ new Date()).toISOString();
+          runtimeState.last_flush_error = event.error;
+          runtimeState.consecutive_failures = buffer.consecutiveFailures;
+          runtimeState.queue_size = buffer.size;
+          persistHealthEvent();
+          break;
+        case "buffer_overflow":
+          runtimeState.dropped_overflow = buffer.droppedOverflow;
+          runtimeState.queue_size = buffer.size;
+          persistHealthEvent();
+          break;
+        case "circuit_open":
+          runtimeState.circuit_open_until = new Date(event.openUntil).toISOString();
+          runtimeState.consecutive_failures = event.failures;
+          persistHealthEvent();
+          break;
+        case "remote_disabled":
+          runtimeState.remote_disabled = true;
+          runtimeState.queue_size = 0;
+          persistHealthEvent();
+          break;
+      }
+    };
     const buffer = new CaptureBuffer({
       apiKey,
       endpoint: opts.endpoint,
       maxBuffer: opts.maxBuffer,
       flushMs: opts.flushMs,
       timeoutMs: opts.timeoutMs,
-      diagnostics: opts.diagnostics
+      diagnostics: opts.diagnostics,
+      onStateChange: onBufferStateChange
     });
     registerBeforeExit(buffer);
+    let exitSnapshotWritten = false;
+    const beforeExitHandler = () => {
+      if (exitSnapshotWritten || restored) return;
+      exitSnapshotWritten = true;
+      try {
+        stopHeartbeat();
+        const stoppedSnapshot = buildCurrentSnapshot();
+        stoppedSnapshot.state = "stopped";
+        stoppedSnapshot.stopped_at = (/* @__PURE__ */ new Date()).toISOString();
+        stoppedSnapshot.last_heartbeat_at = (/* @__PURE__ */ new Date()).toISOString();
+        persistHealth(stoppedSnapshot);
+      } catch {
+      }
+    };
+    if (typeof process !== "undefined" && typeof process.on === "function") {
+      process.on("beforeExit", beforeExitHandler);
+    }
+    persistHealthEvent();
+    safeRunJanitor(sessionsDir, sessionId);
+    startHeartbeat();
+    emitDiagnostic(opts.diagnostics, {
+      type: "observe_activated",
+      session_id: sessionId,
+      provider,
+      agent,
+      patch_target: patchTargetName
+    });
     const wrappedCreate = function observeWrappedCreate(...args) {
       const requestSnapshot = snapshotRequest(args[0], captureLevel);
       const startedAt = Date.now();
@@ -1201,7 +1653,11 @@ function observe(client, opts = {}) {
           provider,
           requestSnapshot,
           response,
-          startedAt
+          startedAt,
+          sessionId,
+          runtimeState,
+          persistHealthEvent,
+          diagnostics: opts.diagnostics
         });
         return response;
       });
@@ -1211,11 +1667,18 @@ function observe(client, opts = {}) {
     let restored = false;
     return {
       client,
+      flush() {
+        return buffer.flush();
+      },
       restore() {
         if (restored) {
           return;
         }
         restored = true;
+        stopHeartbeat();
+        if (typeof process !== "undefined" && typeof process.removeListener === "function") {
+          process.removeListener("beforeExit", beforeExitHandler);
+        }
         if (patchTarget.target[patchTarget.methodName] === wrappedCreate) {
           if (patchTarget.hadOwnMethod) {
             patchTarget.target[patchTarget.methodName] = patchTarget.originalCreate;
@@ -1224,11 +1687,124 @@ function observe(client, opts = {}) {
           }
         }
         clearWrapped(client, patchTarget.target);
+        const stoppedSnapshot = buildCurrentSnapshot();
+        stoppedSnapshot.state = "stopped";
+        stoppedSnapshot.stopped_at = (/* @__PURE__ */ new Date()).toISOString();
+        stoppedSnapshot.last_heartbeat_at = (/* @__PURE__ */ new Date()).toISOString();
+        persistHealth(stoppedSnapshot);
         buffer.close();
+      },
+      getHealth() {
+        if (restored) {
+          const snapshot = buildCurrentSnapshot();
+          snapshot.state = "stopped";
+          snapshot.stopped_at = snapshot.stopped_at ?? (/* @__PURE__ */ new Date()).toISOString();
+          return snapshot;
+        }
+        runtimeState.queue_size = buffer.size;
+        return buildCurrentSnapshot();
       }
     };
+  } 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);
+  }
+}
+function createInactiveHandle(client, sessionId, agent, reasonCode, detail, activatedAt, diagnostics, stateDir) {
+  const healthSnapshot = buildHealthSnapshot({
+    sessionId,
+    agent,
+    provider: null,
+    patchTarget: null,
+    state: "inactive",
+    reasonCode,
+    active: false,
+    activatedAt,
+    detail
+  });
+  const sessionsDir = resolveSessionsDir(
+    resolveStateDir(stateDir ? { stateDir } : void 0)
+  );
+  safeWriteHealth(sessionsDir, sessionId, healthSnapshot, diagnostics);
+  emitDiagnostic(diagnostics, {
+    type: "observe_inactive",
+    reason_code: reasonCode,
+    ...detail ? { detail } : {}
+  });
+  return {
+    client,
+    flush() {
+      return Promise.resolve();
+    },
+    restore() {
+    },
+    getHealth() {
+      return { ...healthSnapshot };
+    }
+  };
+}
+function unrefTimerHandle(timer) {
+  if (typeof timer === "object" && timer !== null && "unref" in timer) {
+    try {
+      timer.unref?.call(timer);
+    } catch {
+    }
+  }
+}
+function buildHealthSnapshot(input) {
+  const snapshot = {
+    schema_version: "1.0",
+    session_id: input.sessionId,
+    agent: input.agent,
+    provider: input.provider,
+    patch_target: input.patchTarget,
+    state: input.state,
+    activation: {
+      active: input.active,
+      reason_code: input.reasonCode,
+      activated_at: input.activatedAt,
+      ...input.detail ? { detail: input.detail } : {}
+    },
+    process: {
+      pid: typeof process !== "undefined" ? process.pid : null,
+      cwd: typeof process !== "undefined" ? process.cwd() : "",
+      node_version: typeof process !== "undefined" ? process.versions?.node ?? "" : "",
+      sdk_version: getSdkVersion()
+    },
+    runtime: {
+      captures_seen: 0,
+      dropped_overflow: 0,
+      last_capture_at: null,
+      last_flush_attempt_at: null,
+      last_flush_success_at: null,
+      last_flush_error_at: null,
+      last_flush_error: null,
+      queue_size: 0,
+      consecutive_failures: 0,
+      circuit_open_until: null,
+      remote_disabled: false
+    },
+    stopped_at: null,
+    last_heartbeat_at: input.activatedAt,
+    last_health_store_error_at: null,
+    last_health_store_error: null
+  };
+  return snapshot;
+}
+function safeWriteHealth(sessionsDir, sessionId, snapshot, diagnostics) {
+  try {
+    writeHealthSnapshot(sessionsDir, sessionId, snapshot);
+  } catch (err) {
+    emitDiagnostic(diagnostics, {
+      type: "health_store_error",
+      detail: err instanceof Error ? err.message : "Failed to write health snapshot"
+    });
+  }
+}
+function safeRunJanitor(sessionsDir, currentSessionId) {
+  try {
+    runJanitor(sessionsDir, currentSessionId);
   } catch {
-    return createNoopHandle(client);
   }
 }
 function safelyCaptureResponse(input) {
@@ -1258,10 +1834,19 @@ function safelyCaptureResponse(input) {
         usage: extractUsage(input.response, input.provider)
       },
       endedAt: Date.now(),
-      startedAt: input.startedAt
+      startedAt: input.startedAt,
+      sessionId: input.sessionId
     });
     if (capture) {
       input.buffer.push(capture);
+      input.runtimeState.captures_seen += 1;
+      input.runtimeState.last_capture_at = (/* @__PURE__ */ new Date()).toISOString();
+      input.runtimeState.queue_size = input.buffer.size;
+      emitDiagnostic(input.diagnostics, {
+        type: "capture_seen",
+        session_id: input.sessionId
+      });
+      input.persistHealthEvent();
     }
   } catch {
   }
@@ -1278,10 +1863,19 @@ function safelyPushStreamCapture(input) {
       requestSnapshot: input.requestSnapshot,
       responseData: input.summary,
       startedAt: input.startedAt,
-      endedAt: Date.now()
+      endedAt: Date.now(),
+      sessionId: input.sessionId
     });
     if (capture) {
       input.buffer.push(capture);
+      input.runtimeState.captures_seen += 1;
+      input.runtimeState.last_capture_at = (/* @__PURE__ */ new Date()).toISOString();
+      input.runtimeState.queue_size = input.buffer.size;
+      emitDiagnostic(input.diagnostics, {
+        type: "capture_seen",
+        session_id: input.sessionId
+      });
+      input.persistHealthEvent();
     }
   } catch {
   }
@@ -1307,7 +1901,8 @@ function buildCapturedCall(input) {
         ...input.captureLevel === "full" && input.responseData.textBlocks && input.responseData.textBlocks.length > 0 ? { text_blocks: input.responseData.textBlocks } : {}
       },
       ...input.responseData.usage ? { usage: input.responseData.usage } : {},
-      latency_ms: Math.max(0, input.endedAt - input.startedAt)
+      latency_ms: Math.max(0, input.endedAt - input.startedAt),
+      ...input.sessionId ? { sdk_session_id: input.sessionId } : {}
     };
   } catch {
     return null;
@@ -1486,13 +2081,6 @@ function clearWrapped(client, target) {
   } catch {
   }
 }
-function createNoopHandle(client) {
-  return {
-    client,
-    restore() {
-    }
-  };
-}
 function resolveApiKey(opts) {
   return typeof opts.apiKey === "string" && opts.apiKey.length > 0 ? opts.apiKey : toNonEmptyString(process.env.REPLAYCI_API_KEY);
 }
@@ -1536,8 +2124,8 @@ var import_contracts_core3 = require("@replayci/contracts-core");
 
 // src/contracts.ts
 var import_contracts_core2 = require("@replayci/contracts-core");
-var import_node_fs = require("fs");
-var import_node_path = require("path");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
 var CONTRACT_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml"]);
 var MAX_REGEX_BYTES = 1024;
 var NESTED_QUANTIFIER_RE = /\((?:[^()\\]|\\.)*[+*{](?:[^()\\]|\\.)*\)(?:[+*]|\{\d+(?:,\d*)?\})/;
@@ -1586,39 +2174,51 @@ function loadContractsFromPaths(inputs) {
   const repoRoot = process.cwd();
   const contractFiles = inputs.flatMap((input) => {
     try {
-      return collectContractFiles((0, import_node_path.resolve)(repoRoot, input));
+      return collectContractFiles((0, import_node_path2.resolve)(repoRoot, input));
     } catch (error) {
       throw new ReplayConfigurationError(
         `Failed to load contracts from "${input}": ${formatErrorMessage(error)}`
       );
     }
   });
-  return contractFiles.map((contractFile) => {
-    const contractPath = (0, import_node_path.relative)(repoRoot, contractFile);
-    const contract = (0, import_contracts_core2.loadContractSync)({
-      repoRoot,
-      contractPath
-    });
-    return normalizeInlineContract({
-      ...contract,
-      contract_file: contractFile
-    });
-  });
+  const loaded = [];
+  for (const contractFile of contractFiles) {
+    const contractPath = (0, import_node_path2.relative)(repoRoot, contractFile);
+    try {
+      const contract = (0, import_contracts_core2.loadContractSync)({
+        repoRoot,
+        contractPath
+      });
+      loaded.push(normalizeInlineContract({
+        ...contract,
+        contract_file: contractFile
+      }));
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.startsWith("ContractMissingTool:")) {
+        continue;
+      }
+      throw new ReplayConfigurationError(
+        `Failed to parse contract "${contractPath}": ${msg}`
+      );
+    }
+  }
+  return loaded;
 }
 function collectContractFiles(inputPath) {
-  const stat = (0, import_node_fs.statSync)(inputPath);
+  const stat = (0, import_node_fs2.statSync)(inputPath);
   if (stat.isFile()) {
     return [inputPath];
   }
   if (!stat.isDirectory()) {
     return [];
   }
-  return (0, import_node_fs.readdirSync)(inputPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
-    const fullPath = (0, import_node_path.join)(inputPath, entry.name);
+  return (0, import_node_fs2.readdirSync)(inputPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+    const fullPath = (0, import_node_path2.join)(inputPath, entry.name);
     if (entry.isDirectory()) {
       return collectContractFiles(fullPath);
     }
-    if (entry.isFile() && CONTRACT_EXTENSIONS.has((0, import_node_path.extname)(entry.name).toLowerCase())) {
+    if (entry.isFile() && CONTRACT_EXTENSIONS.has((0, import_node_path2.extname)(entry.name).toLowerCase())) {
       return [fullPath];
     }
     return [];