@saptools/cf-live-trace 0.1.6 → 0.1.8

package/dist/cli.js

@@ -519,29 +519,48 @@ function extractEvaluateValue(result) {
 }
 
 // src/preview.ts
-function truncatePreview(preview, maxChars) {
-  if (maxChars <= 0) {
+import { Buffer as Buffer2 } from "buffer";
+function truncatePreview(preview, maxBytes) {
+  if (maxBytes <= 0) {
     return { preview, truncated: false };
   }
-  if (preview.length <= maxChars) {
+  const encoded = Buffer2.from(preview);
+  if (encoded.length <= maxBytes) {
     return { preview, truncated: false };
   }
-  return { preview: preview.slice(0, maxChars), truncated: true };
+  return {
+    preview: encoded.subarray(0, utf8Boundary(encoded, maxBytes)).toString("utf8"),
+    truncated: true
+  };
+}
+function utf8Boundary(encoded, maxBytes) {
+  let boundary = Math.min(maxBytes, encoded.length);
+  while (boundary > 0 && isContinuationByte(encoded[boundary])) {
+    boundary -= 1;
+  }
+  return boundary;
+}
+function isContinuationByte(value) {
+  return value !== void 0 && (value & 192) === 128;
 }
 
 // src/payload.ts
 var fallbackEventId = 0;
 function parseDrainResult(payload, options) {
   if (!isRecord2(payload)) {
-    return { events: [], droppedCount: 0, queueSize: 0 };
+    return { drainId: null, events: [], droppedCount: 0, queueSize: 0 };
   }
   const rawEvents = Array.isArray(payload["events"]) ? payload["events"] : [];
   return {
+    drainId: readDrainId(payload["drainId"]),
     events: rawEvents.map((event) => parseRuntimeEvent(event, options)).filter((event) => event !== null),
     droppedCount: readNonNegativeNumber(payload["droppedCount"]),
     queueSize: readNonNegativeNumber(payload["queueSize"])
   };
 }
+function readDrainId(value) {
+  return typeof value === "string" && /^d\d+$/.test(value) ? value : null;
+}
 function parseRuntimeEvent(payload, options) {
   if (!isRecord2(payload)) {
     return null;
@@ -635,16 +654,20 @@ function isRecord2(value) {
 
 // src/runtime-source.ts
 var CF_LIVE_TRACE_GLOBAL_NAME = "__SAPTOOLS_CF_LIVE_TRACE__";
-var CF_LIVE_TRACE_RUNTIME_VERSION = 2;
+var CF_LIVE_TRACE_RUNTIME_VERSION = 3;
 var CF_LIVE_TRACE_RUNTIME_SOURCE = `
 (() => {
   const name = '${CF_LIVE_TRACE_GLOBAL_NAME}';
   const runtimeVersion = ${String(CF_LIVE_TRACE_RUNTIME_VERSION)};
   const existing = globalThis[name];
   if (existing && typeof existing.version === 'number' && existing.version >= runtimeVersion) return existing;
+  let staleCleanup = null;
   if (existing && typeof existing.uninstall === 'function') {
     try {
-      existing.uninstall();
+      const cleanup = existing.uninstall();
+      if (cleanup && typeof cleanup.then === 'function') {
+        staleCleanup = Promise.resolve(cleanup).catch(() => undefined);
+      }
     } catch {}
   }
   let BufferCtor = globalThis.Buffer;
@@ -657,7 +680,9 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
     droppedCount: 0,
     originals: {},
     seen: new WeakSet(),
-    nextId: 1
+    nextId: 1,
+    nextDrainId: 1,
+    pendingDrain: null
   };
   const loadRequire = () => {
     if (typeof require === 'function') return require;
@@ -690,13 +715,62 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
     if (chunk instanceof Uint8Array && BufferCtor) return BufferCtor.from(chunk).toString('utf8');
     return '';
   };
-  const byteLength = (text) => BufferCtor ? BufferCtor.byteLength(text) : text.length;
-  const appendPreview = (current, chunk, enabled) => {
-    if (!enabled) return current;
+  const chunkBuffer = (chunk) => {
+    if (!BufferCtor || chunk === undefined || chunk === null) return null;
+    if (BufferCtor.isBuffer(chunk)) return chunk;
+    if (typeof chunk === 'string' || chunk instanceof Uint8Array) return BufferCtor.from(chunk);
+    return null;
+  };
+  const textByteLength = (text) => BufferCtor ? BufferCtor.byteLength(text) : text.length;
+  const chunkByteLength = (chunk) => {
+    if (chunk === undefined || chunk === null) return 0;
+    if (BufferCtor && BufferCtor.isBuffer(chunk)) return chunk.length;
+    if (chunk instanceof Uint8Array) return chunk.byteLength;
+    return textByteLength(typeof chunk === 'string' ? chunk : '');
+  };
+  const truncateTextToBytes = (text, maxBytes) => {
+    if (!BufferCtor) return text.slice(0, maxBytes);
+    const encoded = BufferCtor.from(text);
+    if (encoded.length <= maxBytes) return text;
+    let boundary = Math.min(maxBytes, encoded.length);
+    while (boundary > 0 && encoded[boundary] !== undefined && (encoded[boundary] & 0xc0) === 0x80) {
+      boundary -= 1;
+    }
+    return encoded.subarray(0, boundary).toString('utf8');
+  };
+  const appendPreview = (chunks, currentBytes, chunk, enabled) => {
+    if (!enabled) return currentBytes;
+    const maxBytes = Math.floor(Number(state.options.maxBodyBytes) || 0);
+    if (maxBytes <= 0) return currentBytes;
+    const remaining = maxBytes - currentBytes;
+    if (remaining <= 0) return currentBytes;
+    const buffer = chunkBuffer(chunk);
+    if (buffer) {
+      const addition = buffer.subarray(0, remaining);
+      chunks.push(addition);
+      return currentBytes + addition.length;
+    }
     const text = chunkText(chunk);
-    if (state.options.maxBodyBytes <= 0) return current + text;
-    if (current.length >= state.options.maxBodyBytes) return current;
-    return (current + text).slice(0, state.options.maxBodyBytes);
+    const addition = truncateTextToBytes(text, remaining);
+    chunks.push(addition);
+    return currentBytes + textByteLength(addition);
+  };
+  const completeUtf8Length = (buffer) => {
+    if (!buffer || buffer.length === 0) return 0;
+    let start = buffer.length - 1;
+    while (start > 0 && (buffer[start] & 0xc0) === 0x80) start -= 1;
+    const lead = buffer[start];
+    const expected = lead <= 0x7f ? 1 : lead <= 0xdf ? 2 : lead <= 0xef ? 3 : lead <= 0xf7 ? 4 : 1;
+    return buffer.length - start < expected ? start : buffer.length;
+  };
+  const previewText = (chunks, retainedBytes) => {
+    if (!BufferCtor) {
+      const text = chunks.join('');
+      return { text, bytes: textByteLength(text) };
+    }
+    const buffer = BufferCtor.concat(chunks, retainedBytes);
+    const completeBytes = completeUtf8Length(buffer);
+    return { text: buffer.subarray(0, completeBytes).toString('utf8'), bytes: completeBytes };
   };
   const enqueue = (event) => {
     if (state.queue.length >= state.options.maxEvents) {
@@ -713,31 +787,30 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
     const traceId = String(state.nextId++);
     let requestBytes = 0;
     let responseBytes = 0;
-    let requestPreview = '';
-    let responsePreview = '';
+    const requestPreviewChunks = [];
+    const responsePreviewChunks = [];
+    let requestPreviewBytes = 0;
+    let responsePreviewBytes = 0;
     let finished = false;
     const originalReqEmit = req.emit;
     const originalWrite = res.write;
     const originalEnd = res.end;
     req.emit = function patchedReqEmit(eventName, ...args) {
       if (eventName === 'data' && args[0] !== undefined) {
-        const text = chunkText(args[0]);
-        requestBytes += byteLength(text);
-        requestPreview = appendPreview(requestPreview, args[0], state.options.captureRequestBody);
+        requestBytes += chunkByteLength(args[0]);
+        requestPreviewBytes = appendPreview(requestPreviewChunks, requestPreviewBytes, args[0], state.options.captureRequestBody);
       }
       return originalReqEmit.apply(this, [eventName, ...args]);
     };
     res.write = function patchedWrite(chunk, ...args) {
-      const text = chunkText(chunk);
-      responseBytes += byteLength(text);
-      responsePreview = appendPreview(responsePreview, chunk, state.options.captureResponseBody);
+      responseBytes += chunkByteLength(chunk);
+      responsePreviewBytes = appendPreview(responsePreviewChunks, responsePreviewBytes, chunk, state.options.captureResponseBody);
       return originalWrite.apply(this, [chunk, ...args]);
     };
     res.end = function patchedEnd(chunk, ...args) {
       if (chunk !== undefined) {
-        const text = chunkText(chunk);
-        responseBytes += byteLength(text);
-        responsePreview = appendPreview(responsePreview, chunk, state.options.captureResponseBody);
+        responseBytes += chunkByteLength(chunk);
+        responsePreviewBytes = appendPreview(responsePreviewChunks, responsePreviewBytes, chunk, state.options.captureResponseBody);
       }
       return originalEnd.apply(this, [chunk, ...args]);
     };
@@ -748,6 +821,8 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
       res.write = originalWrite;
       res.end = originalEnd;
       const rawUrl = initialUrl || String(req.url || '');
+      const requestPreview = previewText(requestPreviewChunks, requestPreviewBytes);
+      const responsePreview = previewText(responsePreviewChunks, responsePreviewBytes);
       enqueue({
         id: traceId,
         timestamp: new Date().toISOString(),
@@ -762,10 +837,10 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
         responseBytes,
         requestHeaders: toHeaderRecord(req.headers),
         responseHeaders: toHeaderRecord(typeof res.getHeaders === 'function' ? res.getHeaders() : {}),
-        requestBodyPreview: requestPreview,
-        responseBodyPreview: responsePreview,
-        requestBodyTruncated: state.options.maxBodyBytes > 0 && requestPreview.length >= state.options.maxBodyBytes,
-        responseBodyTruncated: state.options.maxBodyBytes > 0 && responsePreview.length >= state.options.maxBodyBytes,
+        requestBodyPreview: requestPreview.text,
+        responseBodyPreview: responsePreview.text,
+        requestBodyTruncated: state.options.captureRequestBody && state.options.maxBodyBytes > 0 && requestBytes > requestPreview.bytes,
+        responseBodyTruncated: state.options.captureResponseBody && state.options.maxBodyBytes > 0 && responseBytes > responsePreview.bytes,
         droppedBeforeEvent: state.droppedCount,
         traceId,
         correlationId: req.headers && typeof req.headers['x-saptools-trace-id'] === 'string' ? req.headers['x-saptools-trace-id'] : null
@@ -789,10 +864,10 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
     const numeric = Number(value);
     return Number.isFinite(numeric) && numeric > 0 ? Math.floor(numeric) : 0;
   };
-  const limitPreview = (event, previewKey, truncatedKey, maxChars) => {
+  const limitPreview = (event, previewKey, truncatedKey, maxBytes) => {
     const preview = event[previewKey];
-    if (maxChars <= 0 || typeof preview !== 'string' || preview.length <= maxChars) return event;
-    return { ...event, [previewKey]: preview.slice(0, maxChars), [truncatedKey]: true };
+    if (maxBytes <= 0 || typeof preview !== 'string' || textByteLength(preview) <= maxBytes) return event;
+    return { ...event, [previewKey]: truncateTextToBytes(preview, maxBytes), [truncatedKey]: true };
   };
   const eventForDrain = (event, maxChars) => {
     if (!event || typeof event !== 'object') return event;
@@ -801,10 +876,44 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
     output = limitPreview(output, 'responseBodyPreview', 'responseBodyTruncated', maxChars);
     return output;
   };
+  const acknowledgeDrain = (drainId) => {
+    const pending = state.pendingDrain;
+    if (!pending || drainId !== pending.id) return;
+    const drainedEvents = new Set(pending.sourceEvents);
+    state.queue = state.queue.filter((event) => !drainedEvents.has(event));
+    state.pendingDrain = null;
+  };
+  const drainResult = () => {
+    const pending = state.pendingDrain;
+    if (!pending) {
+      return { drainId: null, events: [], droppedCount: state.droppedCount, queueSize: state.queue.length };
+    }
+    return {
+      drainId: pending.id,
+      events: pending.events,
+      droppedCount: state.droppedCount,
+      queueSize: state.queue.length
+    };
+  };
   const api = {
     version: runtimeVersion,
     async install(options) {
-      state.options = { ...state.options, ...options };
+      if (staleCleanup) {
+        await staleCleanup;
+        staleCleanup = null;
+      }
+      state.options = {
+        ...state.options,
+        ...options,
+        maxBodyBytes: toTransportLimit(options && options.maxBodyBytes),
+        maxEvents: Math.max(1, Math.floor(Number(options && options.maxEvents) || 1))
+      };
+      state.queue = [];
+      state.pendingDrain = null;
+      state.droppedCount = 0;
+      state.seen = new WeakSet();
+      state.nextId = 1;
+      state.nextDrainId = 1;
       if (!state.installed) {
         if (!BufferCtor) {
           const bufferModule = await loadModule('buffer');
@@ -823,11 +932,19 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
       state.enabled = false;
       return api.status();
     },
-    drainEvents(maxCount, maxTransportBodyBytes) {
+    drainEvents(maxCount, maxTransportBodyBytes, acknowledgedDrainId) {
+      acknowledgeDrain(acknowledgedDrainId);
+      if (state.pendingDrain) return drainResult();
       const count = Math.max(0, Math.min(Number(maxCount) || 0, state.queue.length));
       const transportLimit = toTransportLimit(maxTransportBodyBytes);
-      const events = state.queue.splice(0, count).map((event) => eventForDrain(event, transportLimit));
-      return { events, droppedCount: state.droppedCount, queueSize: state.queue.length };
+      if (count === 0) return drainResult();
+      const sourceEvents = state.queue.slice(0, count);
+      state.pendingDrain = {
+        id: 'd' + String(state.nextDrainId++),
+        sourceEvents,
+        events: sourceEvents.map((event) => eventForDrain(event, transportLimit))
+      };
+      return drainResult();
     },
     status() {
       return { installed: state.installed, enabled: state.enabled, queueSize: state.queue.length, droppedCount: state.droppedCount, maxEvents: state.options.maxEvents };
@@ -839,6 +956,8 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
       if (state.originals.httpServerEmit && http && http.Server) http.Server.prototype.emit = state.originals.httpServerEmit;
       if (state.originals.httpsServerEmit && https && https.Server) https.Server.prototype.emit = state.originals.httpsServerEmit;
       state.installed = false;
+      state.queue = [];
+      state.pendingDrain = null;
       return api.status();
     }
   };
@@ -849,8 +968,9 @@ var CF_LIVE_TRACE_RUNTIME_SOURCE = `
 function buildInstallExpression(options) {
   return `${CF_LIVE_TRACE_RUNTIME_SOURCE}.install(${JSON.stringify(options)})`;
 }
-function buildDrainExpression(maxCount, maxTransportBodyBytes) {
-  return `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.drainEvents(${String(maxCount)}, ${String(maxTransportBodyBytes)}) ?? { events: [], droppedCount: 0, queueSize: 0 }`;
+function buildDrainExpression(maxCount, maxTransportBodyBytes, acknowledgedDrainId = null) {
+  const acknowledgement = JSON.stringify(acknowledgedDrainId);
+  return `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.drainEvents(${String(maxCount)}, ${String(maxTransportBodyBytes)}, ${acknowledgement}) ?? { drainId: null, events: [], droppedCount: 0, queueSize: 0 }`;
 }
 function buildStopExpression(options) {
   return options.uninstallRuntimeHook ? `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.uninstall() ?? { installed: false, enabled: false }` : `globalThis.${CF_LIVE_TRACE_GLOBAL_NAME}?.disable() ?? { installed: false, enabled: false }`;
@@ -942,7 +1062,8 @@ var RUNTIME_QUEUE_SIZE = 1e3;
 var CONTROL_EVALUATE_TIMEOUT_MS = 5e3;
 var DRAIN_EVALUATE_TIMEOUT_MS = 1e4;
 var DRAIN_TIMEOUT_RETRY_LIMIT = 3;
-var DRAIN_TRANSPORT_BODY_LIMIT = 2e4;
+var MAX_DRAIN_EVALUATE_TIMEOUT_MS = 6e4;
+var DRAIN_BODY_BUDGET_BYTES = 8 * 1024 * 1024;
 var defaultDependencies = {
   prepareCfSession,
   ensureSshEnabled,
@@ -959,11 +1080,12 @@ var LiveTraceSession = class {
   }
   options;
   dependencies;
-  events = [];
+  summaryEvents = [];
   consecutiveDrainTimeouts = 0;
-  drainInFlight = false;
+  drainTask;
   inspectorClient;
   pollTimer;
+  pendingDrainAcknowledgement = null;
   state = "idle";
   stopRequested = false;
   tunnelHandle;
@@ -972,6 +1094,8 @@ var LiveTraceSession = class {
       return;
     }
     this.stopRequested = false;
+    this.pendingDrainAcknowledgement = null;
+    this.summaryEvents.splice(0);
     await this.startRuntimeTrace(resolveStartOptions(options));
   }
   async stop(options) {
@@ -1057,36 +1181,65 @@ var LiveTraceSession = class {
     this.stopPolling();
     this.consecutiveDrainTimeouts = 0;
     this.pollTimer = this.dependencies.setInterval(() => {
-      void this.drainTraceEvents(maxBodyBytes);
+      this.startDrain(maxBodyBytes);
     }, DRAIN_INTERVAL_MS);
   }
-  async drainTraceEvents(maxBodyBytes) {
-    if (this.drainInFlight || this.inspectorClient === void 0 || this.state !== "streaming") {
+  startDrain(maxBodyBytes) {
+    if (this.drainTask !== void 0 || this.inspectorClient === void 0 || this.state !== "streaming") {
       return;
     }
-    this.drainInFlight = true;
+    const task = this.drainTraceEvents(maxBodyBytes);
+    this.drainTask = task;
+    void task.then(
+      () => {
+        this.clearDrainTask(task);
+      },
+      () => {
+        this.clearDrainTask(task);
+      }
+    );
+  }
+  clearDrainTask(task) {
+    if (this.drainTask === task) {
+      this.drainTask = void 0;
+    }
+  }
+  async drainTraceEvents(maxBodyBytes) {
+    const batchSize = resolveDrainBatchSize(maxBodyBytes);
     try {
-      const payload = await this.inspectorClient.evaluate(
-        buildDrainExpression(DRAIN_BATCH_SIZE, resolveDrainTransportBodyLimit(maxBodyBytes)),
-        DRAIN_EVALUATE_TIMEOUT_MS
+      const payload = await this.requireInspector().evaluate(
+        buildDrainExpression(
+          batchSize,
+          resolveDrainTransportBodyLimit(maxBodyBytes),
+          this.pendingDrainAcknowledgement
+        ),
+        resolveDrainEvaluateTimeout(maxBodyBytes, batchSize)
       );
       this.consecutiveDrainTimeouts = 0;
-      this.publishDrainedEvents(payload, maxBodyBytes);
+      try {
+        await this.publishDrainedEvents(payload, maxBodyBytes);
+      } catch (error) {
+        await this.handleEventHandlerFailure(error);
+      }
     } catch (error) {
       await this.handleDrainFailure(error);
-    } finally {
-      this.drainInFlight = false;
     }
   }
-  publishDrainedEvents(payload, maxBodyBytes) {
+  async publishDrainedEvents(payload, maxBodyBytes) {
     const drained = parseDrainResult(payload, { appId: this.options.target.app, maxBodyBytes });
-    if (drained.events.length === 0) {
+    if (drained.events.length > 0) {
+      await this.options.onEvents?.(drained.events);
+      this.publishSummary(drained.events);
+    }
+    this.pendingDrainAcknowledgement = drained.drainId;
+  }
+  publishSummary(events) {
+    if (this.options.onSummary === void 0) {
       return;
     }
-    this.events.push(...drained.events);
-    this.events.splice(0, Math.max(0, this.events.length - RUNTIME_QUEUE_SIZE));
-    this.options.onEvents?.(drained.events);
-    this.options.onSummary?.(buildUrlSummaries(this.events));
+    this.summaryEvents.push(...events.map(toSummaryEvent));
+    this.summaryEvents.splice(0, Math.max(0, this.summaryEvents.length - RUNTIME_QUEUE_SIZE));
+    this.options.onSummary(buildUrlSummaries(this.summaryEvents));
   }
   async handleDrainFailure(error) {
     if (isEvaluateTimeout(error)) {
@@ -1097,11 +1250,19 @@ var LiveTraceSession = class {
       }
     }
     this.log(`Live Trace stream failed for ${this.options.target.app}: ${formatError(error)}`);
-    await this.stopRuntimeTrace(false);
+    await this.stopRuntimeTrace(false, false);
     this.postState("error", "Runtime HTTP trace connection was lost.", false, true);
   }
-  async stopRuntimeTrace(uninstallRuntimeHook) {
+  async handleEventHandlerFailure(error) {
+    this.log(`Live Trace event handler failed for ${this.options.target.app}: ${formatError(error)}`);
+    await this.stopRuntimeTrace(false, false);
+    this.postState("error", "Trace event handler failed.", false, true);
+  }
+  async stopRuntimeTrace(uninstallRuntimeHook, waitForDrain = true) {
     this.stopPolling();
+    if (waitForDrain) {
+      await this.drainTask;
+    }
     this.consecutiveDrainTimeouts = 0;
     const uninstalled = await this.stopInspectorHook(uninstallRuntimeHook);
     await this.closeInspectorClient();
@@ -1185,12 +1346,20 @@ var LiveTraceStartupError = class extends Error {
   stateMessage;
 };
 function resolveStartOptions(options) {
+  const maxBodyBytes = options.maxBodyBytes ?? 4096;
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes <= 0) {
+    throw new Error("maxBodyBytes must be a positive safe integer.");
+  }
+  const runtimeQueueSize = options.runtimeQueueSize ?? RUNTIME_QUEUE_SIZE;
+  if (!Number.isSafeInteger(runtimeQueueSize) || runtimeQueueSize <= 0) {
+    throw new Error("runtimeQueueSize must be a positive safe integer.");
+  }
   return {
     captureHeaders: options.captureHeaders ?? true,
     captureRequestBody: options.captureRequestBody ?? true,
     captureResponseBody: options.captureResponseBody ?? true,
-    maxBodyBytes: options.maxBodyBytes ?? 4096,
-    runtimeQueueSize: options.runtimeQueueSize ?? RUNTIME_QUEUE_SIZE
+    maxBodyBytes,
+    runtimeQueueSize
   };
 }
 function stopLateTunnel(tunnel) {
@@ -1199,7 +1368,16 @@ function stopLateTunnel(tunnel) {
   }
 }
 function resolveDrainTransportBodyLimit(maxBodyBytes) {
-  return maxBodyBytes > 0 ? Math.min(maxBodyBytes, DRAIN_TRANSPORT_BODY_LIMIT) : DRAIN_TRANSPORT_BODY_LIMIT;
+  return maxBodyBytes > 0 ? maxBodyBytes : 1;
+}
+function resolveDrainBatchSize(maxBodyBytes) {
+  const perEventBytes = Math.max(1, maxBodyBytes * 2);
+  return Math.max(1, Math.min(DRAIN_BATCH_SIZE, Math.floor(DRAIN_BODY_BUDGET_BYTES / perEventBytes)));
+}
+function resolveDrainEvaluateTimeout(maxBodyBytes, batchSize) {
+  const estimatedBytes = Math.min(Number.MAX_SAFE_INTEGER, maxBodyBytes * 2 * batchSize);
+  const extraMegabytes = Math.ceil(Math.max(0, estimatedBytes - 1e6) / 1e6);
+  return Math.min(MAX_DRAIN_EVALUATE_TIMEOUT_MS, DRAIN_EVALUATE_TIMEOUT_MS + extraMegabytes * 5e3);
 }
 function isEvaluateTimeout(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -1222,8 +1400,569 @@ function formatError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.trim().length > 0 ? message.trim() : "Unknown error";
 }
+function toSummaryEvent(event) {
+  return {
+    ...event,
+    requestHeaders: {},
+    responseHeaders: {},
+    requestBodyPreview: "",
+    responseBodyPreview: ""
+  };
+}
+
+// src/trace-compact.ts
+var COMPACT_BODY_PREVIEW_CHARS = 128;
+var SENSITIVE_QUERY_KEYS = new Set([
+  "access_token",
+  "api_key",
+  "auth",
+  "authorization",
+  "client_secret",
+  "oauth_code",
+  "passwd",
+  "password",
+  "refresh_token",
+  "sig",
+  "signature",
+  "token"
+].map(normalizeQueryKey));
+function detectBodyFormat(body, headers) {
+  if (body.length === 0) {
+    return "empty";
+  }
+  const contentType = headerValue(headers, "content-type").toLowerCase();
+  if (contentType.includes("json")) {
+    return "json";
+  }
+  if (contentType.includes("html")) {
+    return "html";
+  }
+  if (contentType.includes("xml")) {
+    return "xml";
+  }
+  if (contentType.includes("x-www-form-urlencoded")) {
+    return "form";
+  }
+  if (contentType.includes("octet-stream")) {
+    return "binary";
+  }
+  return detectBodyFormatFromText(body, contentType);
+}
+function compactTraceEvent(record) {
+  const event = record.event;
+  const requestBody = compactBody(event.requestBodyPreview);
+  const responseBody = compactBody(event.responseBodyPreview);
+  return {
+    id: event.id,
+    sessionId: record.sessionId,
+    requestId: record.requestId,
+    timestamp: event.timestamp,
+    instance: event.instance,
+    method: event.method,
+    path: event.path,
+    url: redactSensitiveQueryValues(event.url),
+    normalizedUrl: redactSensitiveQueryValues(event.normalizedUrl),
+    status: event.status,
+    durationMs: event.durationMs,
+    requestBytes: event.requestBytes,
+    responseBytes: event.responseBytes,
+    requestBodyFormat: record.requestBodyFormat,
+    responseBodyFormat: record.responseBodyFormat,
+    requestBodyPreview: requestBody.preview,
+    requestBodyPreviewRemainingChars: requestBody.remainingChars,
+    responseBodyPreview: responseBody.preview,
+    responseBodyPreviewRemainingChars: responseBody.remainingChars,
+    requestBodyTruncated: event.requestBodyTruncated,
+    responseBodyTruncated: event.responseBodyTruncated,
+    droppedBeforeEvent: event.droppedBeforeEvent,
+    source: event.source,
+    traceId: event.traceId,
+    correlationId: event.correlationId
+  };
+}
+function headerValue(headers, name) {
+  const lowerName = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lowerName) {
+      return value;
+    }
+  }
+  return "";
+}
+function detectBodyFormatFromText(body, contentType) {
+  const trimmed = body.trim();
+  if (isJsonText(trimmed)) {
+    return "json";
+  }
+  if (/^<!doctype\s+html/i.test(trimmed) || /^<html(?:\s|>)/i.test(trimmed)) {
+    return "html";
+  }
+  if (/^<\?xml(?:\s|>)/i.test(trimmed) || /^<[A-Za-z_][\w:.-]*(?:\s|>|\/>)/.test(trimmed)) {
+    return "xml";
+  }
+  if (contentType.startsWith("text/")) {
+    return "text";
+  }
+  if (hasBinaryControlChars(body)) {
+    return "binary";
+  }
+  return "text";
+}
+function isJsonText(text) {
+  if (!text.startsWith("{") && !text.startsWith("[")) {
+    return false;
+  }
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasBinaryControlChars(text) {
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code <= 8 || code === 11 || code === 12 || code >= 14 && code <= 31) {
+      return true;
+    }
+  }
+  return false;
+}
+function compactBody(body) {
+  let preview = "";
+  let length = 0;
+  for (const character of body) {
+    if (length < COMPACT_BODY_PREVIEW_CHARS) {
+      preview += character;
+    }
+    length += 1;
+  }
+  return {
+    preview,
+    remainingChars: Math.max(0, length - COMPACT_BODY_PREVIEW_CHARS)
+  };
+}
+function redactSensitiveQueryValues(rawUrl) {
+  const queryIndex = rawUrl.indexOf("?");
+  if (queryIndex < 0) {
+    return rawUrl;
+  }
+  const fragmentIndex = rawUrl.indexOf("#", queryIndex);
+  const queryEnd = fragmentIndex < 0 ? rawUrl.length : fragmentIndex;
+  const query = rawUrl.slice(queryIndex + 1, queryEnd);
+  const redacted = query.split("&").map(redactQueryPart).join("&");
+  return `${rawUrl.slice(0, queryIndex + 1)}${redacted}${rawUrl.slice(queryEnd)}`;
+}
+function redactQueryPart(part) {
+  const separatorIndex = part.indexOf("=");
+  const rawKey = separatorIndex < 0 ? part : part.slice(0, separatorIndex);
+  if (!SENSITIVE_QUERY_KEYS.has(normalizeQueryKey(rawKey))) {
+    return part;
+  }
+  return `${rawKey}=redacted`;
+}
+function normalizeQueryKey(rawKey) {
+  try {
+    return decodeURIComponent(rawKey).toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+  } catch {
+    return rawKey.toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+  }
+}
+
+// src/trace-store.ts
+import { createHash, randomBytes } from "crypto";
+import { access, mkdir, readFile, readdir, rename, rm as rm2, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join as join2 } from "path";
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_LIVE_TRACE_DIR_NAME = "cf-live-trace";
+var SESSIONS_DIR_NAME = "sessions";
+var EVENTS_DIR_NAME = "events";
+var MANIFEST_FILE_NAME = "manifest.json";
+var TRACE_TTL_MS = 2 * 60 * 60 * 1e3;
+var MAX_TARGET_SLUG_BYTES = 160;
+var SESSION_ID_PATTERN = /^s(?:[0-9a-f]{8}|[0-9a-f]{16})$/;
+var REQUEST_ID_PATTERN = /^r(?:[0-9a-f]{8}|[0-9a-f]{16})$/;
+function traceSessionsRoot(saptoolsRoot) {
+  return join2(saptoolsRoot ?? join2(homedir(), SAPTOOLS_DIR_NAME), CF_LIVE_TRACE_DIR_NAME, SESSIONS_DIR_NAME);
+}
+async function createTraceSession(input, options = {}) {
+  await pruneTraceSessions(options);
+  const sessionId = resolveSessionId(options.sessionId);
+  const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
+  const target = toTargetIdentity(input.target);
+  const directory = sessionDirectory(sessionId, options.saptoolsRoot);
+  const eventsDirectory2 = join2(directory, EVENTS_DIR_NAME);
+  const manifestPath2 = join2(directory, MANIFEST_FILE_NAME);
+  await mkdir(eventsDirectory2, { recursive: true, mode: 448 });
+  await writeJsonFile(manifestPath2, createManifest(sessionId, createdAt, target));
+  return { sessionId, createdAt, target, directory, eventsDirectory: eventsDirectory2, manifestPath: manifestPath2 };
+}
+async function writeTraceEvent(session, event, options = {}) {
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const requestId = resolveRequestId(options.requestId?.());
+  await ensureSessionManifest(session);
+  const record = {
+    version: 1,
+    sessionId: session.sessionId,
+    requestId,
+    createdAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + TRACE_TTL_MS).toISOString(),
+    target: session.target,
+    requestBodyFormat: detectBodyFormat(event.requestBodyPreview, event.requestHeaders),
+    responseBodyFormat: detectBodyFormat(event.responseBodyPreview, event.responseHeaders),
+    event
+  };
+  const backupPath = join2(session.eventsDirectory, eventFileName(record, now));
+  await mkdir(session.eventsDirectory, { recursive: true, mode: 448 });
+  await writeJsonFile(backupPath, record);
+  return { ...record, backupPath };
+}
+async function readTraceEvent(sessionId, requestId, options = {}) {
+  const resolvedSessionId = resolveSessionId(sessionId);
+  const resolvedRequestId = resolveRequestId(requestId);
+  const entries = await listEventFilePaths(resolvedSessionId, options.saptoolsRoot);
+  const candidates = entries.filter((path) => path.includes(`-${resolvedRequestId}-`));
+  for (const path of candidates) {
+    const record = await readStoredTraceEvent(path, resolvedSessionId);
+    if (record === void 0 || isExpired(record, options)) {
+      await rm2(path, { force: true });
+      continue;
+    }
+    if (record.requestId === resolvedRequestId) {
+      return record;
+    }
+  }
+  throw new Error("Saved trace request not found or expired");
+}
+async function visitTraceEvents(sessionId, visitor, options = {}) {
+  const resolvedSessionId = resolveSessionId(sessionId);
+  const entries = await listEventFilePaths(resolvedSessionId, options.saptoolsRoot);
+  for (const path of entries) {
+    const record = await readStoredTraceEvent(path, resolvedSessionId);
+    if (record === void 0 || isExpired(record, options)) {
+      await rm2(path, { force: true });
+      continue;
+    }
+    if (!await visitor(record)) {
+      return;
+    }
+  }
+}
+async function listTraceSessions(options = {}) {
+  await pruneTraceSessions(options);
+  const sessionIds = await listSessionIds(options.saptoolsRoot);
+  const summaries = await Promise.all(sessionIds.map(async (sessionId) => await readSessionSummary(sessionId, options)));
+  return summaries.filter((summary) => summary !== void 0).sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+async function pruneTraceSessions(options = {}) {
+  const sessionIds = await listSessionIds(options.saptoolsRoot);
+  const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+  let removed = 0;
+  for (const sessionId of sessionIds) {
+    removed += await pruneSession(sessionId, now, options.saptoolsRoot);
+  }
+  return removed;
+}
+function toTargetIdentity(target) {
+  return {
+    ...target.region === void 0 ? {} : { region: target.region },
+    ...target.apiEndpoint === void 0 ? {} : { apiEndpoint: target.apiEndpoint },
+    org: target.org,
+    space: target.space,
+    app: target.app,
+    instance: String(target.instanceIndex ?? 0)
+  };
+}
+function createManifest(sessionId, createdAt, target) {
+  return { version: 1, sessionId, createdAt, target };
+}
+async function ensureSessionManifest(session) {
+  try {
+    await access(session.manifestPath);
+    return;
+  } catch (error) {
+    if (!isNodeError(error, "ENOENT")) {
+      throw error;
+    }
+  }
+  await mkdir(session.eventsDirectory, { recursive: true, mode: 448 });
+  await writeJsonFile(
+    session.manifestPath,
+    createManifest(session.sessionId, session.createdAt, session.target)
+  );
+}
+function isExpired(record, options) {
+  const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+  return Date.parse(record.expiresAt) <= now;
+}
+async function readSessionSummary(sessionId, options) {
+  const manifest = await readStoredManifest(manifestPath(sessionId, options.saptoolsRoot));
+  if (manifest?.sessionId !== sessionId) {
+    return void 0;
+  }
+  const eventCount = (await listEventFilePaths(sessionId, options.saptoolsRoot)).length;
+  return {
+    sessionId,
+    createdAt: manifest.createdAt,
+    target: manifest.target,
+    eventCount,
+    directory: sessionDirectory(sessionId, options.saptoolsRoot)
+  };
+}
+async function pruneSession(sessionId, now, saptoolsRoot) {
+  const manifest = await readStoredManifest(manifestPath(sessionId, saptoolsRoot));
+  const eventPaths = await listEventFilePaths(sessionId, saptoolsRoot);
+  let removed = 0;
+  let remaining = 0;
+  for (const path of eventPaths) {
+    const expiresAt = eventPathExpiresAt(path) ?? await storedEventExpiresAt(path);
+    if (expiresAt === void 0 || expiresAt <= now) {
+      await rm2(path, { force: true });
+      removed += 1;
+    } else {
+      remaining += 1;
+    }
+  }
+  if (remaining === 0 && isManifestExpiredOrMissing(manifest, now)) {
+    await rm2(sessionDirectory(sessionId, saptoolsRoot), { recursive: true, force: true });
+  }
+  return removed;
+}
+async function storedEventExpiresAt(path) {
+  const record = await readStoredTraceEvent(path);
+  return record === void 0 ? void 0 : Date.parse(record.expiresAt);
+}
+function isManifestExpiredOrMissing(manifest, now) {
+  if (manifest === void 0) {
+    return true;
+  }
+  return Date.parse(manifest.createdAt) + TRACE_TTL_MS <= now;
+}
+async function listSessionIds(saptoolsRoot) {
+  try {
+    const entries = await readdir(traceSessionsRoot(saptoolsRoot), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory() && SESSION_ID_PATTERN.test(entry.name)).map((entry) => entry.name);
+  } catch (error) {
+    if (isNodeError(error, "ENOENT")) {
+      return [];
+    }
+    throw error;
+  }
+}
+async function listEventFilePaths(sessionId, saptoolsRoot) {
+  try {
+    const directory = eventsDirectory(sessionId, saptoolsRoot);
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => join2(directory, entry.name)).sort(compareEventPaths);
+  } catch (error) {
+    if (isNodeError(error, "ENOENT")) {
+      return [];
+    }
+    throw error;
+  }
+}
+function compareEventPaths(left, right) {
+  const leftTimestamp = eventPathTimestamp(left);
+  const rightTimestamp = eventPathTimestamp(right);
+  return leftTimestamp.localeCompare(rightTimestamp) || left.localeCompare(right);
+}
+function eventPathTimestamp(path) {
+  return /-(\d{8}T\d{9}Z)\.json$/.exec(path)?.[1] ?? "";
+}
+function eventPathExpiresAt(path) {
+  const compact = eventPathTimestamp(path);
+  if (compact.length === 0) {
+    return void 0;
+  }
+  const iso = compact.replace(
+    /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})Z$/,
+    "$1-$2-$3T$4:$5:$6.$7Z"
+  );
+  const createdAt = Date.parse(iso);
+  return Number.isNaN(createdAt) ? void 0 : createdAt + TRACE_TTL_MS;
+}
+async function readStoredManifest(path) {
+  const parsed = await readJsonFile(path);
+  return parsed !== void 0 && isStoredManifest(parsed) ? parsed : void 0;
+}
+async function readStoredTraceEvent(path, expectedSessionId) {
+  const parsed = await readJsonFile(path);
+  if (parsed === void 0 || !isStoredTraceEvent(parsed)) {
+    return void 0;
+  }
+  if (expectedSessionId !== void 0 && parsed.sessionId !== expectedSessionId) {
+    return void 0;
+  }
+  return { ...parsed, backupPath: path };
+}
+async function readJsonFile(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isNodeError(error, "ENOENT")) {
+      return void 0;
+    }
+    throw error;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) {
+      throw error;
+    }
+    return void 0;
+  }
+}
+async function writeJsonFile(path, value) {
+  const temporaryPath = `${path}.tmp-${process.pid.toString()}-${randomHex(4)}`;
+  let renamed = false;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}
+`, {
+      encoding: "utf8",
+      mode: 384
+    });
+    await rename(temporaryPath, path);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      await rm2(temporaryPath, { force: true });
+    }
+  }
+}
+function eventFileName(record, now) {
+  const parts = [
+    targetSlug(record.target),
+    record.sessionId,
+    record.requestId,
+    fileTimestamp(now)
+  ].join("-");
+  return `${parts}.json`;
+}
+function targetSlug(target) {
+  const regionOrApi = target.region ?? target.apiEndpoint ?? "api";
+  const fullSlug = [regionOrApi, target.org, target.space, target.app].map(sanitizePathPart).join("-");
+  if (Buffer.byteLength(fullSlug) <= MAX_TARGET_SLUG_BYTES) {
+    return fullSlug;
+  }
+  const hash = createHash("sha256").update(fullSlug).digest("hex").slice(0, 12);
+  const prefix = fullSlug.slice(0, MAX_TARGET_SLUG_BYTES - hash.length - 1).replace(/-+$/, "");
+  return `${prefix}-${hash}`;
+}
+function sanitizePathPart(value) {
+  const sanitized = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized.length === 0 ? "unknown" : sanitized;
+}
+function fileTimestamp(now) {
+  return now.toISOString().replaceAll("-", "").replaceAll(":", "").replace(".", "");
+}
+function sessionDirectory(sessionId, saptoolsRoot) {
+  return join2(traceSessionsRoot(saptoolsRoot), sessionId);
+}
+function eventsDirectory(sessionId, saptoolsRoot) {
+  return join2(sessionDirectory(sessionId, saptoolsRoot), EVENTS_DIR_NAME);
+}
+function manifestPath(sessionId, saptoolsRoot) {
+  return join2(sessionDirectory(sessionId, saptoolsRoot), MANIFEST_FILE_NAME);
+}
+function resolveSessionId(value) {
+  const sessionId = value ?? `s${randomHex(8)}`;
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    throw new Error("Invalid trace session id");
+  }
+  return sessionId;
+}
+function resolveRequestId(value) {
+  const requestId = value ?? `r${randomHex(8)}`;
+  if (!REQUEST_ID_PATTERN.test(requestId)) {
+    throw new Error("Invalid trace request id");
+  }
+  return requestId;
+}
+function randomHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+function isStoredManifest(value) {
+  return isRecord3(value) && value["version"] === 1 && isSessionId(value["sessionId"]) && isIsoTimestamp(value["createdAt"]) && isTraceTargetIdentity(value["target"]);
+}
+function isStoredTraceEvent(value) {
+  return isRecord3(value) && value["version"] === 1 && isStoredEventMetadata(value) && isTraceTargetIdentity(value["target"]) && isTraceBodyFormat(value["requestBodyFormat"]) && isTraceBodyFormat(value["responseBodyFormat"]) && isLiveTraceEvent(value["event"]);
+}
+function isStoredEventMetadata(value) {
+  return isSessionId(value["sessionId"]) && isRequestId(value["requestId"]) && isIsoTimestamp(value["createdAt"]) && isIsoTimestamp(value["expiresAt"]);
+}
+function isTraceTargetIdentity(value) {
+  return isRecord3(value) && optionalString(value["region"]) && optionalString(value["apiEndpoint"]) && typeof value["org"] === "string" && typeof value["space"] === "string" && typeof value["app"] === "string" && typeof value["instance"] === "string";
+}
+function isLiveTraceEvent(value) {
+  return isRecord3(value) && hasLiveTraceStrings(value) && hasLiveTraceMetrics(value) && isStringRecord(value["requestHeaders"]) && isStringRecord(value["responseHeaders"]) && typeof value["requestBodyTruncated"] === "boolean" && typeof value["responseBodyTruncated"] === "boolean" && value["source"] === "runtime-http" && optionalNullableString(value["correlationId"]);
+}
+function hasLiveTraceStrings(value) {
+  const fields = [
+    "id",
+    "appId",
+    "instance",
+    "method",
+    "path",
+    "url",
+    "normalizedUrl",
+    "requestBodyPreview",
+    "responseBodyPreview",
+    "traceId"
+  ];
+  return isIsoTimestamp(value["timestamp"]) && fields.every((field) => typeof value[field] === "string");
+}
+function hasLiveTraceMetrics(value) {
+  return isNullableFiniteNumber(value["status"]) && isNullableNonNegativeNumber(value["durationMs"]) && isNonNegativeFiniteNumber(value["requestBytes"]) && isNonNegativeFiniteNumber(value["responseBytes"]) && isNonNegativeFiniteNumber(value["droppedBeforeEvent"]);
+}
+function isTraceBodyFormat(value) {
+  return value === "empty" || value === "json" || value === "xml" || value === "html" || value === "form" || value === "text" || value === "binary" || value === "unknown";
+}
+function optionalString(value) {
+  return value === void 0 || typeof value === "string";
+}
+function optionalNullableString(value) {
+  return value === null || typeof value === "string";
+}
+function isStringRecord(value) {
+  return isRecord3(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isSessionId(value) {
+  return typeof value === "string" && SESSION_ID_PATTERN.test(value);
+}
+function isRequestId(value) {
+  return typeof value === "string" && REQUEST_ID_PATTERN.test(value);
+}
+function isIsoTimestamp(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const parsed = new Date(value);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}
+function isNullableFiniteNumber(value) {
+  return value === null || isFiniteNumber(value);
+}
+function isNullableNonNegativeNumber(value) {
+  return value === null || isNonNegativeFiniteNumber(value);
+}
+function isNonNegativeFiniteNumber(value) {
+  return isFiniteNumber(value) && value >= 0;
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error, code) {
+  return isRecord3(error) && error["code"] === code;
+}
 
 // src/cli/options.ts
+var MAX_TIMER_SECONDS = 2147483;
 function buildRunOptions2(flags, env) {
   requireRegionOrApi(flags);
   const target = buildTarget(flags, env);
@@ -1250,7 +1989,7 @@ function parsePositiveInteger(raw, label) {
     return void 0;
   }
   const value = Number.parseInt(raw, 10);
-  if (!Number.isInteger(value) || value <= 0 || String(value) !== raw.trim()) {
+  if (!Number.isSafeInteger(value) || value <= 0 || String(value) !== raw.trim()) {
     throw new Error(`Invalid ${label}: "${raw}" \u2014 expected a positive integer.`);
   }
   return value;
@@ -1318,6 +2057,9 @@ function buildTarget(flags, env) {
 function buildLimits(flags) {
   const duration = parsePositiveInteger(flags.duration, "--duration");
   const maxEvents = parsePositiveInteger(flags.maxEvents, "--max-events");
+  if (duration !== void 0 && duration > MAX_TIMER_SECONDS) {
+    throw new Error(`--duration is too large; maximum is ${String(MAX_TIMER_SECONDS)} seconds.`);
+  }
   return {
     ...duration === void 0 ? {} : { durationMs: duration * 1e3 },
     ...maxEvents === void 0 ? {} : { maxEvents }
@@ -1352,14 +2094,11 @@ function parseInstanceIndex(value) {
   return parsed ?? 0;
 }
 function parseBodyLimit(value) {
-  if (value === void 0) {
-    return 4096;
-  }
-  return parseNonNegativeInteger(value, "--max-body-bytes");
+  return parsePositiveInteger(value, "--max-body-bytes") ?? 4096;
 }
 function parseNonNegativeInteger(raw, label) {
   const value = Number.parseInt(raw, 10);
-  if (!Number.isInteger(value) || value < 0 || String(value) !== raw.trim()) {
+  if (!Number.isSafeInteger(value) || value < 0 || String(value) !== raw.trim()) {
     throw new Error(`Invalid ${label}: "${raw}" \u2014 expected a non-negative integer.`);
   }
   return value;
@@ -1395,22 +2134,384 @@ function writeLog(message) {
 function writeSummaryLine(event) {
   const status = event.status === null ? "-" : String(event.status);
   const duration = event.durationMs === null ? "-" : `${event.durationMs.toString()}ms`;
-  process2.stdout.write(`${event.timestamp} ${event.method} ${event.normalizedUrl} ${status} ${duration}
+  const request = event.sessionId === void 0 || event.requestId === void 0 ? "" : ` ${event.sessionId}/${event.requestId}`;
+  process2.stdout.write(`${event.timestamp} ${event.method} ${event.normalizedUrl} ${status} ${duration}${request}
 `);
 }
 
+// src/trace-inspect.ts
+var DEFAULT_BODY_LIMIT = 4e3;
+function inspectTraceBodyResult(record, options) {
+  const limit = positive("limit", options.limit ?? DEFAULT_BODY_LIMIT);
+  const maxRows = positive("max rows", options.maxRows ?? Number.MAX_SAFE_INTEGER);
+  const pointer = options.path ?? "";
+  const parsed = parseJsonBody(bodyText(record, options.body));
+  const selected = resolvePointer(parsed, pointer);
+  const rows = inspectionRows(selected, pointer, limit, maxRows);
+  return {
+    rows: rows.values,
+    totalRows: rows.total,
+    rowsTruncated: rows.total > rows.values.length
+  };
+}
+function inspectionRows(selected, pointer, valueLimit, maxRows) {
+  if (Array.isArray(selected)) {
+    const values = selected.slice(0, maxRows).map(
+      (item, index) => inspectionRow(`${pointer}/${String(index)}`, item, valueLimit)
+    );
+    return { values, total: selected.length };
+  }
+  if (!isRecord4(selected)) {
+    return { values: [inspectionRow(pointer, selected, valueLimit)], total: 1 };
+  }
+  return objectInspectionRows(selected, pointer, valueLimit, maxRows);
+}
+function objectInspectionRows(selected, pointer, valueLimit, maxRows) {
+  const values = [];
+  let total = 0;
+  for (const key in selected) {
+    if (!Object.hasOwn(selected, key)) {
+      continue;
+    }
+    if (values.length < maxRows) {
+      values.push(inspectionRow(`${pointer}/${escapePointerToken(key)}`, selected[key], valueLimit));
+    }
+    total += 1;
+  }
+  return { values, total };
+}
+function searchTraceRecords(records, searchTerm, options) {
+  const term = searchTerm.trim().toLowerCase();
+  if (term.length === 0) {
+    throw new Error("search text must not be empty");
+  }
+  const limit = positive("limit", options.limit);
+  const previewLength = positive("preview length", options.previewLength ?? 128);
+  const matches = [];
+  for (const record of records) {
+    for (const side of selectedSides(options.body)) {
+      const remaining = limit - matches.length;
+      matches.push(...searchBody(record, side, term, remaining, previewLength));
+      if (matches.length >= limit) {
+        return matches;
+      }
+    }
+  }
+  return matches;
+}
+function searchBody(record, side, term, limit, previewLength) {
+  if (limit <= 0) {
+    return [];
+  }
+  const body = bodyText(record, side);
+  const parsed = tryParseJson(body);
+  return parsed === void 0 ? plainTextMatches(record, side, body, term, limit, previewLength) : jsonSearchMatches(record, side, parsed.value, term, limit, previewLength);
+}
+function plainTextMatches(record, side, text, term, limit, previewLength) {
+  const matches = [];
+  const lowerText = text.toLowerCase();
+  let offset = lowerText.indexOf(term);
+  while (offset >= 0 && matches.length < limit) {
+    const start = Math.max(0, offset - 32);
+    matches.push(toSearchMatch(record, side, "", text.slice(start, start + previewLength).replaceAll(/[\r\n\t]/g, " "), offset));
+    offset = lowerText.indexOf(term, offset + Math.max(1, term.length));
+  }
+  return matches;
+}
+function jsonSearchMatches(record, side, root, term, limit, previewLength) {
+  const matches = [];
+  const stack = [{ path: "", value: root }];
+  while (stack.length > 0 && matches.length < limit) {
+    const entry = stack.pop();
+    if (entry === void 0) {
+      break;
+    }
+    inspectJsonSearchEntry(record, side, entry, term, limit, previewLength, matches, stack);
+  }
+  return matches.slice(0, limit);
+}
+function inspectJsonSearchEntry(record, side, entry, term, limit, previewLength, matches, stack) {
+  if (typeof entry.value === "object" && entry.value !== null) {
+    pushJsonChildren(record, side, entry, term, limit, previewLength, matches, stack);
+    return;
+  }
+  const text = jsonScalarSearchText(entry.value);
+  if (text.toLowerCase().includes(term)) {
+    matches.push(toSearchMatch(record, side, entry.path, text.slice(0, previewLength)));
+  }
+}
+function pushJsonChildren(record, side, entry, term, limit, previewLength, matches, stack) {
+  if (!Array.isArray(entry.value) && !isRecord4(entry.value)) {
+    return;
+  }
+  const entries = Array.isArray(entry.value) ? entry.value.map((item, index) => [String(index), item]) : Object.entries(entry.value);
+  for (const [key, value] of entries.reverse()) {
+    if (matches.length >= limit) {
+      return;
+    }
+    const path = `${entry.path}/${escapePointerToken(key)}`;
+    if (key.toLowerCase().includes(term)) {
+      matches.push(toSearchMatch(record, side, path, jsonValueText(value, previewLength)));
+    }
+    stack.push({ path, value });
+  }
+}
+function toSearchMatch(record, side, path, preview, offset) {
+  return {
+    sessionId: record.sessionId,
+    requestId: record.requestId,
+    timestamp: record.event.timestamp,
+    method: record.event.method,
+    normalizedUrl: record.event.normalizedUrl,
+    status: record.event.status,
+    body: side,
+    path,
+    ...offset === void 0 ? {} : { offset },
+    preview
+  };
+}
+function selectedSides(body) {
+  return body === "both" ? ["request", "response"] : [body];
+}
+function bodyText(record, body) {
+  return body === "request" ? record.event.requestBodyPreview : record.event.responseBodyPreview;
+}
+function parseJsonBody(body) {
+  try {
+    return JSON.parse(body);
+  } catch (error) {
+    throw new Error("Saved trace body does not contain valid JSON", { cause: error });
+  }
+}
+function tryParseJson(body) {
+  try {
+    return { value: JSON.parse(body) };
+  } catch {
+    return void 0;
+  }
+}
+function decodePointerToken(token) {
+  if (/~(?:[^01]|$)/.test(token)) {
+    throw new Error("Invalid JSON Pointer escape");
+  }
+  return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function pointerTokens(pointer) {
+  if (pointer === "") {
+    return [];
+  }
+  if (!pointer.startsWith("/")) {
+    throw new Error("JSON Pointer must be empty or start with /");
+  }
+  return pointer.slice(1).split("/").map(decodePointerToken);
+}
+function resolvePointer(root, pointer) {
+  let current = root;
+  for (const token of pointerTokens(pointer)) {
+    current = resolvePointerToken(current, token, pointer);
+  }
+  return current;
+}
+function resolvePointerToken(current, token, pointer) {
+  if (Array.isArray(current)) {
+    const index = Number(token);
+    if (!Number.isSafeInteger(index) || index < 0 || index >= current.length) {
+      throw new Error(`JSON Pointer path "${pointer}" not found`);
+    }
+    return current[index];
+  }
+  if (isRecord4(current) && Object.hasOwn(current, token)) {
+    return current[token];
+  }
+  throw new Error(`JSON Pointer path "${pointer}" not found`);
+}
+function escapePointerToken(token) {
+  return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function inspectionRow(path, value, limit) {
+  return { path, type: jsonType(value), value: jsonValueText(value, limit) };
+}
+function jsonType(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return typeof value;
+}
+function jsonValueText(value, limit) {
+  if (Array.isArray(value)) {
+    return `items=${String(value.length)}`;
+  }
+  if (typeof value === "object" && value !== null) {
+    return `keys=${String(Object.keys(value).length)}`;
+  }
+  if (typeof value === "string") {
+    return value.slice(0, limit);
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+function jsonScalarSearchText(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+function positive(name, value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/cli/session-commands.ts
+function registerSessionCommands(program) {
+  const session = program.command("session").description("inspect saved live trace sessions");
+  session.command("list").description("list active trace sessions").action(async () => {
+    writeJson({ sessions: await listTraceSessions() });
+  });
+  session.command("events <sessionId>").description("list compact events saved for a trace session").option("--method <method>", "filter by HTTP method").option("--status <code>", "filter by HTTP status", parseIntOption).option("--path <text>", "filter by URL/path substring").option("--limit <count>", "maximum events to print", parseIntOption).action(async (sessionId, _options, command) => {
+    await runEvents(sessionId, command.opts());
+  });
+  session.command("search <sessionId> <text>").description("search saved request and response bodies").option("--body <side>", "request, response, or both", parseSearchBodySide, "both").option("--limit <count>", "maximum matches to print", parseIntOption).option("--length <chars>", "maximum preview characters", parseIntOption).action(async (sessionId, text, _options, command) => {
+    await runSearch(sessionId, text, command.opts());
+  });
+  session.command("body <sessionId> <requestId>").description("inspect a saved JSON request or response body").option("--body <side>", "request or response", parseBodySide, "response").option("--path <pointer>", "JSON Pointer inside the saved body").option("--limit <chars>", "maximum characters per value", parseIntOption).option("--rows <count>", "maximum structure rows to print", parseIntOption).action(async (sessionId, requestId, _options, command) => {
+    await runBody(sessionId, requestId, command.opts());
+  });
+  session.command("prune").description("remove expired trace event files").action(async () => {
+    writeJson({ removed: await pruneTraceSessions() });
+  });
+}
+async function runEvents(sessionId, options) {
+  const limit = positive2("--limit", options.limit, 50);
+  const status = optionalHttpStatus(options.status);
+  const events = [];
+  await visitTraceEvents(sessionId, (record) => {
+    if (matchesEvent(record, options, status)) {
+      events.push(compactTraceEvent(record));
+    }
+    return events.length < limit;
+  });
+  writeJson({ sessionId, events });
+}
+async function runSearch(sessionId, text, options) {
+  const limit = positive2("--limit", options.limit, 20);
+  const body = options.body ?? "both";
+  const previewLength = positive2("--length", options.length, 128);
+  const matches = [];
+  await visitTraceEvents(sessionId, (record) => {
+    const found = searchTraceRecords([record], text, {
+      body,
+      limit: limit - matches.length,
+      previewLength
+    });
+    matches.push(...found);
+    return matches.length < limit;
+  });
+  writeJson({ sessionId, matches });
+}
+async function runBody(sessionId, requestId, options) {
+  const record = await readTraceEvent(sessionId, requestId);
+  const body = options.body ?? "response";
+  const inspection = inspectTraceBodyResult(record, {
+    body,
+    ...options.path === void 0 ? {} : { path: options.path },
+    limit: positive2("--limit", options.limit, 4e3),
+    maxRows: positive2("--rows", options.rows, 100)
+  });
+  writeJson({
+    sessionId,
+    requestId,
+    body,
+    format: body === "request" ? record.requestBodyFormat : record.responseBodyFormat,
+    ...inspection
+  });
+}
+function matchesEvent(record, options, status) {
+  const method = options.method?.trim().toUpperCase();
+  const path = options.path?.trim().toLowerCase();
+  if (method !== void 0 && record.event.method !== method) {
+    return false;
+  }
+  if (status !== void 0 && record.event.status !== status) {
+    return false;
+  }
+  return path === void 0 || record.event.normalizedUrl.toLowerCase().includes(path);
+}
+function parseIntOption(value) {
+  const trimmed = value.trim();
+  if (!/^-?\d+$/.test(trimmed)) {
+    throw new Error(`Expected an integer but received "${value}"`);
+  }
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`Expected a safe integer but received "${value}"`);
+  }
+  return parsed;
+}
+function positive2(name, value, fallback) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new Error(`${name} must be a positive safe integer`);
+  }
+  return resolved;
+}
+function optionalHttpStatus(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value < 100 || value > 599) {
+    throw new Error("--status must be an integer from 100 through 599");
+  }
+  return value;
+}
+function parseSearchBodySide(value) {
+  if (value === "request" || value === "response" || value === "both") {
+    return value;
+  }
+  throw new Error(`Invalid --body: "${value}" \u2014 expected request, response, or both.`);
+}
+function parseBodySide(value) {
+  if (value === "request" || value === "response") {
+    return value;
+  }
+  throw new Error(`Invalid --body: "${value}" \u2014 expected request or response.`);
+}
+
 // src/cli/program.ts
 async function main(argv) {
   const program = new Command();
-  program.name("cf-live-trace").description("Inject a runtime HTTP trace hook into a Cloud Foundry Node.js app and stream request/response events").option("-r, --region <key>", "CF region key (default: current cf target)").option("--api-endpoint <url>", "Explicit CF API endpoint").option("-o, --org <name>", "CF org name (default: current cf target)").option("-s, --space <name>", "CF space name (default: current cf target)").requiredOption("-a, --app <name>", "CF app name").option("--email <value>", "SAP email (default: SAP_EMAIL)").option("--password <value>", "SAP password (default: SAP_PASSWORD)").option("-i, --instance <index>", "CF app instance index (default: 0)").option("--cf-home <dir>", "Use an existing CF_HOME instead of a temporary one").option("--cf-command <path>", "CF CLI executable or test shim").option("--duration <seconds>", "Stop after N seconds").option("--max-events <count>", "Stop after N trace events").option("--max-body-bytes <bytes>", "Maximum request/response preview bytes; 0 keeps unlimited previews locally", "4096").option("--no-capture-headers", "Do not capture request/response headers").option("--no-capture-request-body", "Do not capture request body previews").option("--no-capture-response-body", "Do not capture response body previews").option("--no-uninstall-on-exit", "Disable the runtime hook instead of uninstalling it on exit").option("--format <format>", "Output format: ndjson, summary, json", "ndjson").option("--quiet", "Suppress progress messages on stderr").action(async (flags) => {
+  program.name("cf-live-trace").description("Inject a runtime HTTP trace hook into a Cloud Foundry Node.js app and stream request/response events").option("-r, --region <key>", "CF region key (default: current cf target)").option("--api-endpoint <url>", "Explicit CF API endpoint").option("-o, --org <name>", "CF org name (default: current cf target)").option("-s, --space <name>", "CF space name (default: current cf target)").option("-a, --app <name>", "CF app name").option("--email <value>", "SAP email (default: SAP_EMAIL)").option("--password <value>", "SAP password (default: SAP_PASSWORD)").option("-i, --instance <index>", "CF app instance index (default: 0)").option("--cf-home <dir>", "Use an existing CF_HOME instead of a temporary one").option("--cf-command <path>", "CF CLI executable or test shim").option("--duration <seconds>", "Stop after N seconds").option("--max-events <count>", "Stop after N trace events").option("--max-body-bytes <bytes>", "Maximum request/response capture bytes; must be greater than 0", "4096").option("--no-capture-headers", "Do not capture request/response headers").option("--no-capture-request-body", "Do not capture request body previews").option("--no-capture-response-body", "Do not capture response body previews").option("--no-uninstall-on-exit", "Disable the runtime hook instead of uninstalling it on exit").option("--format <format>", "Output format: ndjson, summary, json", "ndjson").option("--quiet", "Suppress progress messages on stderr").action(async (flags) => {
     await runTraceCommand(await buildRunOptionsWithCurrentTarget(flags, process3.env));
   });
+  registerSessionCommands(program);
   await program.parseAsync([...argv]);
 }
 async function runTraceCommand(options) {
   const cfHome = await resolveCfHome(options);
+  let retention;
   try {
-    const events = [];
+    const traceSession = await createTraceSession({ target: options.target });
+    retention = startRetentionPruner(options);
+    writeSessionHints(traceSession, options);
+    const output = { count: 0, events: [] };
     const eventLimit = createEventLimit(options);
     const runtimeError = createRuntimeErrorStopWaiter();
     const session = new LiveTraceSession({
@@ -1426,30 +2527,61 @@ async function runTraceCommand(options) {
           writeLog(message);
         }
       },
-      onEvents: (batch) => {
-        handleEvents(batch, options, events);
-        eventLimit.check(events.length);
+      onEvents: async (batch) => {
+        await handleEvents(batch, options, output, traceSession);
+        eventLimit.check(output.count);
       }
     });
     await runUntilStopped(session, options, eventLimit, runtimeError);
     if (options.format === "json") {
-      writeJson({ events });
+      writeJson({ sessionId: traceSession.sessionId, events: output.events });
     }
   } finally {
+    retention?.cleanup();
     await cfHome.dispose();
   }
 }
-function handleEvents(batch, options, events) {
-  for (const event of batch) {
-    events.push(event);
+function startRetentionPruner(options) {
+  const timer = setInterval(() => {
+    void pruneTraceSessions().catch((error) => {
+      if (!options.quiet) {
+        writeLog(`session: retention cleanup failed: ${formatError2(error)}`);
+      }
+    });
+  }, 6e4);
+  timer.unref();
+  return {
+    cleanup() {
+      clearInterval(timer);
+    }
+  };
+}
+async function handleEvents(batch, options, output, traceSession) {
+  const remaining = options.limits.maxEvents === void 0 ? batch.length : Math.max(0, options.limits.maxEvents - output.count);
+  for (const event of batch.slice(0, remaining)) {
+    const record = await writeTraceEvent(traceSession, event);
+    const compact = compactTraceEvent(record);
+    output.count += 1;
+    if (options.format === "json") {
+      output.events.push(compact);
+    }
     if (options.format === "ndjson") {
-      writeJsonLine(event);
+      writeJsonLine(compact);
     }
     if (options.format === "summary") {
-      writeSummaryLine(event);
+      writeSummaryLine(compact);
     }
   }
 }
+function writeSessionHints(traceSession, options) {
+  if (options.quiet) {
+    return;
+  }
+  writeLog(`session: id=${traceSession.sessionId} backups=${traceSession.directory} ttl=2h`);
+  writeLog(`session: list events with \`cf-live-trace session events ${traceSession.sessionId}\``);
+  writeLog(`session: search bodies with \`cf-live-trace session search ${traceSession.sessionId} <text>\``);
+  writeLog(`session: inspect JSON with \`cf-live-trace session body ${traceSession.sessionId} <requestId> --body response --path / --limit 4000\``);
+}
 async function runUntilStopped(session, options, eventLimit, runtimeError) {
   const abort = createAbortPromise();
   const duration = createDurationStopWaiter(options.limits.durationMs);
@@ -1593,6 +2725,10 @@ async function resolveCfHome(options) {
     }
   };
 }
+function formatError2(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.trim().length > 0 ? message.trim() : "Unknown error";
+}
 
 // src/cli.ts
 try {