@replayci/replay 0.1.2 → 0.1.3

package/dist/index.js

@@ -22,6 +22,7 @@ var CaptureBuffer = class {
   apiKey;
   endpoint;
   diagnostics;
+  onStateChange;
   fetchImpl;
   now;
   queue = [];
@@ -31,6 +32,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);
@@ -41,6 +47,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();
@@ -57,6 +64,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;
@@ -66,10 +88,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);
   }
@@ -127,11 +151,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();
@@ -153,22 +179,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, {
@@ -176,6 +215,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.`
@@ -255,6 +300,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";
 }
@@ -905,7 +956,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);
 }
@@ -1069,9 +1121,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`),
@@ -1084,7 +1146,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) {
@@ -1095,6 +1158,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,
@@ -1105,25 +1176,264 @@ 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
+import { randomBytes } from "crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { readFile } from "fs/promises";
+import { join } from "path";
+var SESSIONS_DIR = "observe-sessions";
+var SCHEMA_VERSION = "1.0";
+var JANITOR_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+function generateSessionId() {
+  return `obs_${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 join(base, ".replayci", "runtime");
+}
+function resolveSessionsDir(stateDir) {
+  return join(stateDir, SESSIONS_DIR);
+}
+function sessionFilePath(sessionsDir, sessionId) {
+  return join(sessionsDir, `${sessionId}.json`);
+}
+function writeHealthSnapshot(sessionsDir, sessionId, snapshot) {
+  ensureDir(sessionsDir);
+  const destPath = sessionFilePath(sessionsDir, sessionId);
+  const tmpPath = join(sessionsDir, `.tmp_${sessionId}_${randomBytes(4).toString("hex")}.json`);
+  const content = JSON.stringify(snapshot, null, 2);
+  const fd = openSync(tmpPath, "w", 384);
+  try {
+    writeFileSync(fd, content);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  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 (!existsSync(sessionsDir)) {
+      return;
+    }
+    const nowMs = now ?? Date.now();
+    const entries = 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 = join(sessionsDir, entry);
+      let snapshot = null;
+      try {
+        const raw = 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 {
+        unlinkSync(filePath);
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function getSdkVersion() {
+  try {
+    const url = new URL("../package.json", import.meta.url);
+    const raw = 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 {
+    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) {
@@ -1132,14 +1442,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) {
@@ -1148,19 +1458,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();
@@ -1173,7 +1635,11 @@ function observe(client, opts = {}) {
           provider,
           requestSnapshot,
           response,
-          startedAt
+          startedAt,
+          sessionId,
+          runtimeState,
+          persistHealthEvent,
+          diagnostics: opts.diagnostics
         });
         return response;
       });
@@ -1183,11 +1649,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;
@@ -1196,11 +1669,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) {
@@ -1230,10 +1816,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 {
   }
@@ -1250,10 +1845,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 {
   }
@@ -1279,7 +1883,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;
@@ -1458,13 +2063,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);
 }
@@ -1517,12 +2115,12 @@ import {
   normalizeToolArray as normalizeToolArray2
 } from "@replayci/contracts-core";
 import {
-  readdirSync,
+  readdirSync as readdirSync2,
   statSync
 } from "fs";
 import {
   extname,
-  join,
+  join as join2,
   relative,
   resolve
 } from "path";
@@ -1613,8 +2211,8 @@ function collectContractFiles(inputPath) {
   if (!stat.isDirectory()) {
     return [];
   }
-  return readdirSync(inputPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
-    const fullPath = join(inputPath, entry.name);
+  return readdirSync2(inputPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+    const fullPath = join2(inputPath, entry.name);
     if (entry.isDirectory()) {
       return collectContractFiles(fullPath);
     }