@saptools/cf-inspector 0.4.11 → 0.5.0

package/dist/index.js

@@ -474,42 +474,93 @@ async function removeBreakpoint(session, breakpointId) {
 // src/inspector/discovery.ts
 init_types();
 import { request } from "http";
+import { performance } from "perf_hooks";
+var InvalidDiscoveryPayloadError = class extends CfInspectorError {
+};
 async function fetchJson(url, timeoutMs) {
-  return await new Promise((resolve, reject) => {
-    const req = request(url, { method: "GET" }, (res) => {
-      const chunks = [];
-      res.on("data", (chunk) => {
-        chunks.push(chunk);
-      });
-      res.on("end", () => {
-        try {
-          resolve(parseJsonResponse(chunks));
-        } catch (err) {
-          reject(parseDiscoveryError(url, err));
-        }
-      });
-      res.on("error", (err) => {
-        reject(newDiscoveryError(`Inspector discovery response error: ${err.message}`));
+  const deadline = performance.now() + timeoutMs;
+  let lastError;
+  while (performance.now() < deadline) {
+    try {
+      const remainingMs = deadline - performance.now();
+      if (remainingMs <= 0) {
+        break;
+      }
+      return await new Promise((resolve, reject) => {
+        const req = request(url, { method: "GET" }, (res) => {
+          const chunks = [];
+          res.on("data", (chunk) => {
+            chunks.push(chunk);
+          });
+          res.on("end", () => {
+            try {
+              resolve(parseJsonResponse(chunks));
+            } catch (err) {
+              reject(parseDiscoveryError(url, err));
+            }
+          });
+          res.on("error", (err) => {
+            reject(newDiscoveryError(`Inspector discovery response error: ${err.message}`));
+          });
+        });
+        const attemptTimeoutMs = Math.min(2e3, remainingMs);
+        req.setTimeout(attemptTimeoutMs, () => {
+          req.destroy(
+            new CfInspectorError(
+              "INSPECTOR_DISCOVERY_FAILED",
+              `Inspector discovery at ${url} timed out after ${timeoutMs.toString()}ms`
+            )
+          );
+        });
+        req.on("error", (err) => {
+          reject(err instanceof CfInspectorError ? err : formatDiscoveryRequestError(url, err));
+        });
+        req.end();
       });
-    });
-    req.setTimeout(timeoutMs, () => {
-      req.destroy(
-        new CfInspectorError(
-          "INSPECTOR_DISCOVERY_FAILED",
-          `Inspector discovery at ${url} timed out after ${timeoutMs.toString()}ms`
-        )
-      );
-    });
-    req.on("error", (err) => {
-      reject(
-        err instanceof CfInspectorError ? err : new CfInspectorError(
-          "INSPECTOR_DISCOVERY_FAILED",
-          `Inspector discovery at ${url} failed: ${err.message}`
-        )
-      );
-    });
-    req.end();
-  });
+    } catch (err) {
+      if (err instanceof InvalidDiscoveryPayloadError) {
+        throw err;
+      }
+      lastError = err;
+      const now = performance.now();
+      if (now < deadline) {
+        const sleepMs = Math.min(1e3, deadline - now);
+        await new Promise((r) => setTimeout(r, sleepMs));
+      }
+    }
+  }
+  if (lastError instanceof Error) {
+    throw lastError;
+  }
+  throw new CfInspectorError("INSPECTOR_DISCOVERY_FAILED", `Inspector discovery at ${url} timed out after ${timeoutMs.toString()}ms`);
+}
+function isNodeSystemError(err) {
+  return err instanceof Error;
+}
+function isConnectionRefusedOrUnreachable(code) {
+  return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "ETIMEDOUT" || code === "EHOSTUNREACH" || code === "ENETUNREACH";
+}
+function formatEndpoint(url, err) {
+  if (typeof err.address === "string" && typeof err.port === "number") {
+    return `${err.address}:${err.port.toString()}`;
+  }
+  const parsed = new URL(url);
+  return parsed.host;
+}
+function formatDiscoveryRequestError(url, err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  if (!isNodeSystemError(err) || !isConnectionRefusedOrUnreachable(err.code)) {
+    return new CfInspectorError(
+      "INSPECTOR_DISCOVERY_FAILED",
+      `Inspector discovery at ${url} failed: ${detail}`
+    );
+  }
+  const endpoint = formatEndpoint(url, err);
+  return new CfInspectorError(
+    "INSPECTOR_DISCOVERY_FAILED",
+    `Cannot reach Node inspector discovery at ${url}. Nothing is listening on ${endpoint}, or the inspector tunnel is stale/closed. Restart the local inspector or tunnel and retry. If this port came from cf-debugger, stop the stale session and start a fresh tunnel, or run cf-inspector with --app/--region/--org/--space so it can open a tunnel.`,
+    detail
+  );
 }
 function parseJsonResponse(chunks) {
   const text = Buffer.concat(chunks).toString("utf8");
@@ -517,7 +568,10 @@ function parseJsonResponse(chunks) {
 }
 function parseDiscoveryError(url, err) {
   const message = err instanceof Error ? err.message : String(err);
-  return newDiscoveryError(`Failed to parse inspector discovery response from ${url}: ${message}`);
+  return new InvalidDiscoveryPayloadError(
+    "INSPECTOR_DISCOVERY_FAILED",
+    `Failed to parse inspector discovery response from ${url}: ${message}`
+  );
 }
 function newDiscoveryError(message) {
   return new CfInspectorError("INSPECTOR_DISCOVERY_FAILED", message);
@@ -591,7 +645,7 @@ async function fetchInspectorVersion(host, port, timeoutMs) {
 
 // src/inspector/pause.ts
 init_types();
-import { performance } from "perf_hooks";
+import { performance as performance2 } from "perf_hooks";
 function pauseMatches(pause, breakpointIds, pauseReasons) {
   if (pauseReasons !== void 0 && pauseReasons.length > 0) {
     return pauseReasons.includes(pause.reason);
@@ -602,7 +656,7 @@ function pauseMatches(pause, breakpointIds, pauseReasons) {
   return pause.hitBreakpoints.some((id) => breakpointIds.includes(id));
 }
 function remainingUntil(deadlineMs) {
-  return Math.max(0, deadlineMs - performance.now());
+  return Math.max(0, deadlineMs - performance2.now());
 }
 function hasResumedSincePause(session, pause) {
   const pauseAt = pause.receivedAtMs;
@@ -632,7 +686,7 @@ async function waitForUnmatchedPauseToResume(session, pause, deadlineMs, timeout
   }
   try {
     await session.client.waitFor("Debugger.resumed", { timeoutMs: remainingMs });
-    session.debuggerState.lastResumedAtMs = performance.now();
+    session.debuggerState.lastResumedAtMs = performance2.now();
   } catch (err) {
     if (err instanceof CfInspectorError && err.code === "BREAKPOINT_NOT_HIT") {
       throwUnrelatedPauseTimeout(pause, timeoutMs);
@@ -655,7 +709,7 @@ async function handleUnmatchedPause(session, pause, options, deadlineMs) {
   await waitForUnmatchedPauseToResume(session, pause, deadlineMs, options.timeoutMs);
 }
 async function waitForPause(session, options) {
-  const deadlineMs = performance.now() + options.timeoutMs;
+  const deadlineMs = performance2.now() + options.timeoutMs;
   const buffer = session.pauseBuffer;
   while (buffer.length > 0 || remainingUntil(deadlineMs) > 0) {
     while (buffer.length > 0) {
@@ -688,14 +742,14 @@ async function waitForLivePause(session, options, deadlineMs) {
     params = await session.client.waitFor("Debugger.paused", {
       timeoutMs: remainingMs,
       predicate: () => {
-        receivedAtMs = performance.now();
+        receivedAtMs = performance2.now();
         return true;
       }
     });
   } finally {
     session.pauseWaitGate.active = false;
   }
-  return toPauseEvent(params, receivedAtMs ?? performance.now(), session.scripts);
+  return toPauseEvent(params, receivedAtMs ?? performance2.now(), session.scripts);
 }
 
 // src/inspector/runtime.ts
@@ -706,15 +760,30 @@ async function resume(session) {
 async function setPauseOnExceptions(session, state) {
   await session.client.send("Debugger.setPauseOnExceptions", { state });
 }
-async function evaluateOnFrame(session, callFrameId, expression) {
+async function evaluateOnFrame(session, callFrameId, expression, options = {}) {
   return await session.client.send("Debugger.evaluateOnCallFrame", {
     callFrameId,
     expression,
     returnByValue: false,
     generatePreview: true,
-    silent: true
+    silent: true,
+    ...options.throwOnSideEffect === void 0 ? {} : { throwOnSideEffect: options.throwOnSideEffect }
   });
 }
+function isSideEffectRefusal(result) {
+  const classNames = [
+    result.result?.className,
+    result.exceptionDetails?.exception?.className
+  ];
+  const descriptions = [
+    result.result?.description,
+    result.exceptionDetails?.exception?.description
+  ];
+  const isEvalError = classNames.includes("EvalError");
+  return isEvalError && descriptions.some(
+    (description) => typeof description === "string" && description.toLowerCase().includes("possible side-effect in debug-evaluate")
+  );
+}
 async function evaluateGlobal(session, expression) {
   return await session.client.send("Runtime.evaluate", {
     expression,
@@ -766,7 +835,7 @@ async function getProperties(session, objectId) {
 }
 
 // src/inspector/session.ts
-import { performance as performance2 } from "perf_hooks";
+import { performance as performance3 } from "perf_hooks";
 
 // src/cdp/client.ts
 init_types();
@@ -1008,12 +1077,203 @@ var CdpClient = class _CdpClient {
     this.emitter.removeAllListeners();
   }
 };
+var NodeWorkerTransport = class {
+  constructor(parent, sessionId) {
+    this.parent = parent;
+    this.sessionId = sessionId;
+    this.detachParentListeners = [
+      parent.on("NodeWorker.receivedMessageFromWorker", (raw) => {
+        this.forwardWorkerMessage(raw);
+      }),
+      parent.on("NodeWorker.detachedFromWorker", (raw) => {
+        this.handleWorkerDetach(raw);
+      }),
+      parent.onClose((error) => {
+        this.closeWithError(error);
+      })
+    ];
+  }
+  parent;
+  sessionId;
+  emitter = new EventEmitter();
+  detachParentListeners;
+  readyState = 1;
+  send(payload) {
+    if (this.readyState !== 1) {
+      throw new CfInspectorError("INSPECTOR_CONNECTION_FAILED", "Worker inspector session is closed");
+    }
+    void this.parent.send("NodeWorker.sendMessageToWorker", {
+      sessionId: this.sessionId,
+      message: payload
+    }).catch((error) => {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      this.closeWithError(normalized);
+    });
+  }
+  close() {
+    this.finishClose();
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  forwardWorkerMessage(raw) {
+    const params = asNodeWorkerEventParams(raw);
+    if (params.sessionId !== this.sessionId || typeof params.message !== "string") {
+      return;
+    }
+    this.emitter.emit("message", params.message);
+  }
+  handleWorkerDetach(raw) {
+    const params = asNodeWorkerEventParams(raw);
+    if (params.sessionId === this.sessionId) {
+      this.finishClose();
+    }
+  }
+  closeWithError(error) {
+    if (this.readyState !== 1) {
+      return;
+    }
+    this.emitter.emit("error", error);
+    this.finishClose();
+  }
+  finishClose() {
+    if (this.readyState !== 1) {
+      return;
+    }
+    this.readyState = 3;
+    for (const detach of this.detachParentListeners) {
+      detach();
+    }
+    this.emitter.emit("close");
+    this.emitter.removeAllListeners();
+  }
+};
+function asNodeWorkerEventParams(raw) {
+  if (!isUnknownRecord(raw)) {
+    return {};
+  }
+  const sessionId = raw["sessionId"];
+  const message = raw["message"];
+  return {
+    ...typeof sessionId === "string" ? { sessionId } : {},
+    ...typeof message === "string" ? { message } : {}
+  };
+}
+function isUnknownRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+async function createNodeWorkerClient(parent, sessionId, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const transport = new NodeWorkerTransport(parent, sessionId);
+  return await CdpClient.connect({
+    url: `node-worker://${sessionId}`,
+    transportFactory: () => Promise.resolve(transport),
+    requestTimeoutMs
+  });
+}
 
 // src/inspector/session.ts
 init_types();
 var DEFAULT_CONNECT_TIMEOUT_MS = 5e3;
 var DEFAULT_HOST = "127.0.0.1";
 var PAUSE_BUFFER_LIMIT = 32;
+var NodeWorkerDiscovery = class {
+  constructor(client) {
+    this.client = client;
+    this.detachListeners = [
+      client.on("NodeWorker.attachedToWorker", (raw) => {
+        const worker = toInspectorWorkerTarget(raw);
+        if (worker !== void 0) {
+          this.workers.set(worker.sessionId, worker);
+        }
+      }),
+      client.on("NodeWorker.detachedFromWorker", (raw) => {
+        const sessionId = readField(raw, "sessionId");
+        if (typeof sessionId === "string") {
+          this.workers.delete(sessionId);
+        }
+      })
+    ];
+  }
+  client;
+  workers = /* @__PURE__ */ new Map();
+  detachListeners;
+  supported = false;
+  disposed = false;
+  async enable() {
+    try {
+      await this.client.send("NodeWorker.enable", { waitForDebuggerOnStart: false });
+      this.supported = true;
+    } catch (error) {
+      if (!isUnsupportedNodeWorkerDomain(error)) {
+        throw error;
+      }
+    }
+  }
+  list() {
+    return [...this.workers.values()].sort(compareWorkers);
+  }
+  async dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    if (this.supported && !this.client.isClosed) {
+      try {
+        await this.client.send("NodeWorker.disable");
+      } catch {
+      }
+    }
+    for (const detach of this.detachListeners) {
+      detach();
+    }
+  }
+};
+function isUnsupportedNodeWorkerDomain(error) {
+  if (!(error instanceof CfInspectorError) || error.code !== "CDP_REQUEST_FAILED") {
+    return false;
+  }
+  return error.detail?.includes('"code":-32601') === true;
+}
+function compareWorkers(left, right) {
+  const leftId = Number.parseInt(left.workerId, 10);
+  const rightId = Number.parseInt(right.workerId, 10);
+  if (!Number.isNaN(leftId) && !Number.isNaN(rightId) && leftId !== rightId) {
+    return leftId - rightId;
+  }
+  return left.workerId.localeCompare(right.workerId);
+}
+function toInspectorWorkerTarget(raw) {
+  const sessionId = readField(raw, "sessionId");
+  const info = readField(raw, "workerInfo");
+  if (typeof sessionId !== "string" || !isUnknownRecord2(info)) {
+    return void 0;
+  }
+  const workerId = asString(info["workerId"]);
+  if (workerId.length === 0) {
+    return void 0;
+  }
+  return {
+    sessionId,
+    workerId,
+    type: asString(info["type"]),
+    title: asString(info["title"]),
+    url: asString(info["url"])
+  };
+}
+function readField(value, name) {
+  return isUnknownRecord2(value) ? value[name] : void 0;
+}
+function isUnknownRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+async function startNodeWorkerDiscovery(client) {
+  const discovery = new NodeWorkerDiscovery(client);
+  await discovery.enable();
+  return discovery;
+}
 async function connectInspector(options) {
   const host = options.host ?? DEFAULT_HOST;
   const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
@@ -1030,13 +1290,70 @@ async function connectInspector(options) {
     url: target.webSocketDebuggerUrl,
     connectTimeoutMs
   });
+  let workerDiscovery;
   try {
-    return await initSession(client, target);
+    workerDiscovery = await startNodeWorkerDiscovery(client);
+    if (options.workerIndex === void 0) {
+      const session = await initSession(client, target);
+      return withWorkerMetadata(session, workerDiscovery, targetIndex, targets.length);
+    }
+    return await initWorkerSession(
+      client,
+      workerDiscovery,
+      options.workerIndex,
+      targetIndex,
+      targets.length
+    );
   } catch (err) {
+    await workerDiscovery?.dispose();
     client.dispose();
     throw err;
   }
 }
+async function initWorkerSession(parent, discovery, workerIndex, targetIndex, targetCount) {
+  const workers = discovery.list();
+  if (!discovery.supported) {
+    throw new CfInspectorError(
+      "INSPECTOR_DISCOVERY_FAILED",
+      "This runtime does not expose the NodeWorker CDP domain; --worker cannot be used. Run list-targets for available raw targets."
+    );
+  }
+  const worker = workers[workerIndex];
+  if (worker === void 0) {
+    throw new CfInspectorError(
+      "INSPECTOR_DISCOVERY_FAILED",
+      `No NodeWorker sub-session at index ${workerIndex.toString()} (available: ${workers.length.toString()}). Ensure the worker is alive, then rerun list-targets.`
+    );
+  }
+  const client = await createNodeWorkerClient(parent, worker.sessionId);
+  const session = await initSession(client, workerToInspectorTarget(worker));
+  return withWorkerMetadata(session, discovery, targetIndex, targetCount, workerIndex, parent);
+}
+function withWorkerMetadata(session, discovery, targetIndex, targetCount, workerIndex, parent) {
+  return {
+    ...session,
+    targetIndex,
+    targetCount,
+    ...workerIndex === void 0 ? {} : { workerIndex },
+    workerTargets: discovery.list(),
+    workerDiscoverySupported: discovery.supported,
+    dispose: async () => {
+      await session.dispose();
+      await discovery.dispose();
+      parent?.dispose();
+    }
+  };
+}
+function workerToInspectorTarget(worker) {
+  return {
+    description: "Node worker sub-session",
+    id: worker.workerId,
+    title: worker.title,
+    type: worker.type,
+    url: worker.url,
+    webSocketDebuggerUrl: `node-worker://${worker.sessionId}`
+  };
+}
 async function initSession(client, target) {
   const scripts = /* @__PURE__ */ new Map();
   client.on("Debugger.scriptParsed", (raw) => {
@@ -1056,14 +1373,14 @@ async function initSession(client, target) {
       return;
     }
     const params = raw;
-    const event = toPauseEvent(params, performance2.now(), scripts);
+    const event = toPauseEvent(params, performance3.now(), scripts);
     if (pauseBuffer.length >= PAUSE_BUFFER_LIMIT) {
       pauseBuffer.shift();
     }
     pauseBuffer.push(event);
   });
   client.on("Debugger.resumed", () => {
-    debuggerState.lastResumedAtMs = performance2.now();
+    debuggerState.lastResumedAtMs = performance3.now();
   });
   await client.send("Runtime.enable");
   await client.send("Debugger.enable");
@@ -1084,9 +1401,61 @@ async function initSession(client, target) {
   };
 }
 
+// src/cli/captureParser.ts
+function isQuoteChar(value) {
+  return value === "'" || value === '"' || value === "`";
+}
+function consumeQuotedChar(state, char) {
+  if (state.quote === void 0) {
+    return false;
+  }
+  if (state.escaped) {
+    state.escaped = false;
+    return true;
+  }
+  if (char === "\\") {
+    state.escaped = true;
+    return true;
+  }
+  if (char === state.quote) {
+    state.quote = void 0;
+  }
+  return true;
+}
+function stripQuotedText(expression) {
+  const state = { quote: void 0, escaped: false };
+  let stripped = "";
+  for (const char of expression) {
+    if (consumeQuotedChar(state, char)) {
+      stripped += " ";
+      continue;
+    }
+    if (isQuoteChar(char)) {
+      state.quote = char;
+      stripped += " ";
+      continue;
+    }
+    stripped += char;
+  }
+  return stripped;
+}
+function looksLikeMutation(expression) {
+  const stripped = stripQuotedText(expression);
+  const hasUpdate = /(?:\+\+|--)/u.test(stripped);
+  const hasAssignment = /(?:\*\*=|&&=|\|\|=|\?\?=|[+\-*/%&|^]=|(?:^|[^=!<>])=(?!=|>))/u.test(stripped);
+  const hasDelete = /\bdelete\b/u.test(stripped);
+  const hasMutatingMethod = /\.\s*(?:push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin|set|add|delete|clear)\s*\(/u.test(stripped);
+  const hasObjectMutation = /\bObject\s*\.\s*(?:assign|defineProperty|defineProperties)\s*\(/u.test(stripped);
+  return hasUpdate || hasAssignment || hasDelete || hasMutatingMethod || hasObjectMutation;
+}
+
+// src/snapshot/evaluation.ts
+init_types();
+
 // src/snapshot/values.ts
 init_types();
-var DEFAULT_MAX_VALUE_LENGTH = 4096;
+var DEFAULT_MAX_VALUE_LENGTH = 131072;
+var DEFAULT_STREAM_MAX_VALUE_LENGTH = 4096;
 function isPrimitive(value) {
   const t = typeof value;
   return t === "string" || t === "number" || t === "boolean" || t === "bigint" || t === "symbol";
@@ -1114,9 +1483,16 @@ function resolveMaxValueLength(value) {
 }
 function limitValueLength(raw, maxValueLength = DEFAULT_MAX_VALUE_LENGTH) {
   if (raw.length <= maxValueLength) {
-    return raw;
+    return { text: raw, truncated: false };
   }
-  return `${raw.slice(0, maxValueLength)}...`;
+  return {
+    text: raw.slice(0, maxValueLength),
+    truncated: true,
+    originalLength: raw.length
+  };
+}
+function textTruncationFields(limited) {
+  return limited.truncated ? { truncated: true, originalLength: limited.originalLength } : {};
 }
 function parseQuotedString(value) {
   try {
@@ -1201,7 +1577,12 @@ function toStructuredValue(variable) {
 // src/snapshot/evaluation.ts
 function evalResultToCaptured(expression, result, maxValueLength = DEFAULT_MAX_VALUE_LENGTH) {
   if (result.exceptionDetails !== void 0) {
-    return { expression, error: readEvalError(result, maxValueLength) };
+    const limited = readEvalError(result, maxValueLength);
+    return {
+      expression,
+      error: limited.text,
+      ...textTruncationFields(limited)
+    };
   }
   const inner = result.result;
   if (!inner) {
@@ -1209,8 +1590,12 @@ function evalResultToCaptured(expression, result, maxValueLength = DEFAULT_MAX_V
   }
   const type = typeof inner.type === "string" ? inner.type : void 0;
   const buildCaptured = (rendered) => {
-    const sanitized = limitValueLength(rendered, maxValueLength);
-    const base = { expression, value: sanitized };
+    const limited = limitValueLength(rendered, maxValueLength);
+    const base = {
+      expression,
+      value: limited.text,
+      ...textTruncationFields(limited)
+    };
     return type === void 0 ? base : { ...base, type };
   };
   if (type === "string" && typeof inner.value === "string") {
@@ -1227,6 +1612,18 @@ function evalResultToCaptured(expression, result, maxValueLength = DEFAULT_MAX_V
   }
   return buildCaptured("undefined");
 }
+function sideEffectRefusalToCaptured(expression) {
+  const error = new CfInspectorError(
+    "MUTATION_NOT_ALLOWED",
+    `V8 blocked the capture expression "${expression}" because it may have side effects. Pass --allow-mutation to run it explicitly.`
+  );
+  return {
+    expression,
+    error: `${error.code}: ${error.message}`,
+    mutationRisk: true,
+    blocked: true
+  };
+}
 function readEvalError(result, maxValueLength) {
   const text = typeof result.exceptionDetails?.exception?.description === "string" ? result.exceptionDetails.exception.description : typeof result.exceptionDetails?.text === "string" ? result.exceptionDetails.text : "evaluation failed";
   return limitValueLength(text, maxValueLength);
@@ -1284,56 +1681,88 @@ async function captureProperties(session, objectId, limit, depth, maxValueLength
       return await captureProperty(session, prop, depth, maxValueLength);
     })
   );
-  return variables;
+  const omittedCount = Math.max(properties.length - limited.length, 0);
+  return omittedCount === 0 ? { variables } : { variables, omittedCount };
 }
 async function captureProperty(session, prop, depth, maxValueLength) {
   const name = typeof prop.name === "string" ? prop.name : "?";
   const described = describeProperty(prop);
-  const children = await capturePropertyChildren(session, described, depth, maxValueLength);
-  const sanitizedValue = limitValueLength(described.value, maxValueLength);
-  const base = { name, value: sanitizedValue };
+  const capturedChildren = await capturePropertyChildren(
+    session,
+    described,
+    depth,
+    maxValueLength
+  );
+  const limited = limitValueLength(described.value, maxValueLength);
+  const base = {
+    name,
+    value: limited.text,
+    ...textTruncationFields(limited)
+  };
   const withType = described.type === void 0 ? base : { ...base, type: described.type };
-  return children === void 0 ? withType : { ...withType, children };
+  const children = capturedChildren?.variables;
+  const withChildren = children === void 0 || children.length === 0 ? withType : { ...withType, children };
+  const omittedCount = capturedChildren?.omittedCount ?? 0;
+  return omittedCount === 0 ? withChildren : { ...withChildren, truncated: true, omittedCount };
 }
 async function capturePropertyChildren(session, described, depth, maxValueLength) {
-  if (depth <= 0 || described.objectId === void 0 || !isExpandable(described.type)) {
+  if (described.objectId === void 0 || !isExpandable(described.type)) {
     return void 0;
   }
+  if (depth <= 0) {
+    return await countDepthOmissions(session, described.objectId);
+  }
   try {
-    const nested = await captureProperties(
+    return await captureProperties(
       session,
       described.objectId,
       MAX_CHILD_VARIABLES,
       depth - 1,
       maxValueLength
     );
-    return nested.length > 0 ? nested : void 0;
   } catch {
     return void 0;
   }
 }
+async function countDepthOmissions(session, objectId) {
+  try {
+    const properties = await getProperties(session, objectId);
+    return properties.length === 0 ? void 0 : { variables: [], omittedCount: properties.length };
+  } catch {
+    return void 0;
+  }
+}
+function countPropertyOmissions(captured) {
+  return (captured.omittedCount ?? 0) + captured.variables.reduce((total, variable) => {
+    const childOmissions = variable.children === void 0 ? 0 : countPropertyOmissions({ variables: variable.children });
+    return total + (variable.omittedCount ?? 0) + childOmissions;
+  }, 0);
+}
 
 // src/snapshot/exception.ts
 function asString2(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
-async function materializeObject(session, objectId, maxValueLength) {
+async function materializeObject(session, objectId) {
   try {
-    const properties = await captureProperties(
+    const captured = await captureProperties(
       session,
       objectId,
       MAX_SCOPE_VARIABLES,
       MAX_VARIABLE_DEPTH,
-      maxValueLength
+      Number.MAX_SAFE_INTEGER
     );
-    if (properties.length === 0) {
+    if (captured.variables.length === 0) {
       return void 0;
     }
     const structured = {};
-    for (const variable of properties) {
+    for (const variable of captured.variables) {
       structured[variable.name] = toStructuredValue(variable);
     }
-    return JSON.stringify(structured);
+    return {
+      value: JSON.stringify(structured),
+      omittedCount: countPropertyOmissions(captured)
+    };
   } catch {
     return void 0;
   }
@@ -1386,18 +1815,44 @@ async function captureException(session, pause, maxValueLength) {
     return { error: "exception data has no objectId or value" };
   }
   const message = await readPropertyDescription(session, objectId, "message");
-  const rendered = await materializeObject(session, objectId, maxValueLength);
+  const rendered = await materializeObject(session, objectId);
   if (rendered !== void 0) {
-    const result = buildResult(type, description, rendered, maxValueLength);
-    return message === void 0 ? result : { ...result, description: limitValueLength(message, maxValueLength) };
+    return buildResult(
+      type,
+      message ?? description,
+      rendered.value,
+      maxValueLength,
+      rendered.omittedCount
+    );
   }
   return buildResult(type, description, description ?? "[exception]", maxValueLength);
 }
-function buildResult(type, description, value, maxValueLength) {
-  const safeValue = limitValueLength(value, maxValueLength);
-  const base = { value: safeValue };
+function buildResult(type, description, value, maxValueLength, omittedCount = 0) {
+  const limitedValue = limitValueLength(value, maxValueLength);
+  const limitedDescription = description === void 0 ? void 0 : limitValueLength(description, maxValueLength);
+  const base = {
+    value: limitedValue.text,
+    ...exceptionTruncationFields(limitedValue, limitedDescription)
+  };
   const withType = type === void 0 ? base : { ...base, type };
-  return description === void 0 ? withType : { ...withType, description: limitValueLength(description, maxValueLength) };
+  const withDescription = limitedDescription === void 0 ? withType : { ...withType, description: limitedDescription.text };
+  return omittedCount === 0 ? withDescription : { ...withDescription, truncated: true, omittedCount };
+}
+function exceptionTruncationFields(value, description) {
+  const valueLength = value.truncated ? value.originalLength : void 0;
+  const descriptionLength = description?.truncated === true ? description.originalLength : void 0;
+  const lengths = [valueLength, descriptionLength].filter(
+    (length) => length !== void 0
+  );
+  if (lengths.length === 0) {
+    return {};
+  }
+  return {
+    truncated: true,
+    originalLength: Math.max(...lengths),
+    ...valueLength === void 0 ? {} : { valueOriginalLength: valueLength },
+    ...descriptionLength === void 0 ? {} : { descriptionOriginalLength: descriptionLength }
+  };
 }
 
 // src/snapshot/objects.ts
@@ -1412,20 +1867,23 @@ function objectIdFromEvalResult(result) {
   }
   return objectId;
 }
-async function renderObjectCapture(session, objectId, maxValueLength) {
+async function renderObjectCapture(session, objectId) {
   try {
-    const properties = await captureProperties(
+    const captured = await captureProperties(
       session,
       objectId,
       MAX_SCOPE_VARIABLES,
       MAX_VARIABLE_DEPTH,
-      maxValueLength
+      Number.MAX_SAFE_INTEGER
     );
     const structured = {};
-    for (const variable of properties) {
+    for (const variable of captured.variables) {
       structured[variable.name] = toStructuredValue(variable);
     }
-    return JSON.stringify(structured);
+    return {
+      value: JSON.stringify(structured),
+      omittedCount: countPropertyOmissions(captured)
+    };
   } catch {
     return void 0;
   }
@@ -1447,16 +1905,22 @@ async function withSerializedObjectCapture(session, expression, evalResult, capt
   if (objectId === void 0) {
     return captured;
   }
-  const rendered = await renderObjectCapture(session, objectId, maxValueLength);
+  const rendered = await renderObjectCapture(session, objectId);
   if (rendered === void 0) {
     return captured;
   }
-  const normalized = normalizeRenderedObjectCapture(rendered, captured.value);
+  const normalized = normalizeRenderedObjectCapture(rendered.value, captured.value);
   if (normalized === void 0) {
     return captured;
   }
-  const value = limitValueLength(normalized, maxValueLength);
-  return captured.type === void 0 ? { expression, value } : { expression, value, type: captured.type };
+  const limited = limitValueLength(normalized, maxValueLength);
+  const base = {
+    expression,
+    value: limited.text,
+    ...textTruncationFields(limited),
+    ...captured.type === void 0 ? {} : { type: captured.type }
+  };
+  return rendered.omittedCount === 0 ? base : { ...base, truncated: true, omittedCount: rendered.omittedCount };
 }
 
 // src/snapshot/scopes.ts
@@ -1471,35 +1935,39 @@ var PRIORITY_BY_TYPE = {
   module: 6,
   script: 7
 };
-function selectScopes(scopeChain) {
+function rankedScopes(scopeChain) {
   const eligible = scopeChain.filter((scope) => scope.objectId !== void 0 && scope.type !== "global");
-  return [...eligible].sort((a, b) => priorityOf(a.type) - priorityOf(b.type)).slice(0, MAX_SCOPES);
+  return [...eligible].sort((a, b) => priorityOf(a.type) - priorityOf(b.type));
 }
 function priorityOf(type) {
   return PRIORITY_BY_TYPE[type] ?? Number.MAX_SAFE_INTEGER;
 }
 async function captureScopes(session, frame, maxValueLength) {
-  const scopes = selectScopes(frame.scopeChain);
-  return await Promise.all(
+  const ranked = rankedScopes(frame.scopeChain);
+  const scopes = ranked.slice(0, MAX_SCOPES);
+  const capturedScopes = await Promise.all(
     scopes.map(async (scope) => {
       const objectId = scope.objectId;
       if (objectId === void 0) {
         return { type: scope.type, variables: [] };
       }
       try {
-        const variables = await captureProperties(
+        const captured = await captureProperties(
           session,
           objectId,
           MAX_SCOPE_VARIABLES,
           MAX_VARIABLE_DEPTH,
           maxValueLength
         );
-        return { type: scope.type, variables };
+        const base = { type: scope.type, variables: captured.variables };
+        return captured.omittedCount === void 0 ? base : { ...base, truncated: true, omittedCount: captured.omittedCount };
       } catch {
         return { type: scope.type, variables: [] };
       }
     })
   );
+  const omittedCount = Math.max(ranked.length - capturedScopes.length, 0);
+  return omittedCount === 0 ? { scopes: capturedScopes } : { scopes: capturedScopes, omittedCount };
 }
 
 // src/snapshot/stack.ts
@@ -1519,23 +1987,48 @@ function buildBaseFrame(frame) {
   };
   return frame.url === void 0 ? base : { ...base, url: frame.url };
 }
-async function captureFrameExpression(session, callFrameId, expression, maxValueLength) {
+async function captureFrameExpression(session, callFrameId, expression, maxValueLength, throwOnSideEffect) {
+  const mutationRisk = throwOnSideEffect === false && looksLikeMutation(expression);
   try {
-    const result = await evaluateOnFrame(session, callFrameId, expression);
+    const result = await evaluateOnFrame(session, callFrameId, expression, {
+      ...throwOnSideEffect === void 0 ? {} : { throwOnSideEffect }
+    });
+    if (isSideEffectRefusal(result)) {
+      return sideEffectRefusalToCaptured(expression);
+    }
     const captured = evalResultToCaptured(expression, result, maxValueLength);
-    return await withSerializedObjectCapture(session, expression, result, captured, maxValueLength);
+    const serialized = await withSerializedObjectCapture(
+      session,
+      expression,
+      result,
+      captured,
+      maxValueLength
+    );
+    return mutationRisk ? { ...serialized, mutationRisk: true } : serialized;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return { expression, error: limitValueLength(message, maxValueLength) };
+    const limited = limitValueLength(message, maxValueLength);
+    const captured = {
+      expression,
+      error: limited.text,
+      ...textTruncationFields(limited)
+    };
+    return mutationRisk ? { ...captured, mutationRisk: true } : captured;
   }
 }
-async function captureFrameExpressions(session, frame, expressions, maxValueLength) {
+async function captureFrameExpressions(session, frame, expressions, maxValueLength, throwOnSideEffect) {
   if (expressions.length === 0) {
     return [];
   }
   return await Promise.all(
     expressions.map(
-      (expression) => captureFrameExpression(session, frame.callFrameId, expression, maxValueLength)
+      (expression) => captureFrameExpression(
+        session,
+        frame.callFrameId,
+        expression,
+        maxValueLength,
+        throwOnSideEffect
+      )
     )
   );
 }
@@ -1555,7 +2048,8 @@ async function walkStack(session, callFrames, options) {
         session,
         frame,
         options.stackCaptures,
-        options.maxValueLength
+        options.maxValueLength,
+        options.throwOnSideEffect
       );
       return { ...base, captures };
     })
@@ -1577,14 +2071,25 @@ async function captureSnapshot(session, pause, options = {}) {
       column: top.columnNumber + 1
     };
     if (options.includeScopes === true) {
-      const scopes = await captureScopes(session, top, maxValueLength);
-      topFrame = { ...topFrame, scopes };
+      const capturedScopes = await captureScopes(session, top, maxValueLength);
+      topFrame = {
+        ...topFrame,
+        scopes: capturedScopes.scopes,
+        ...capturedScopes.omittedCount === void 0 ? {} : { truncated: true, omittedCount: capturedScopes.omittedCount }
+      };
     }
-    captures = await captureExpressions(session, top.callFrameId, options.captures, maxValueLength);
+    captures = await captureExpressions(
+      session,
+      top.callFrameId,
+      options.captures,
+      maxValueLength,
+      options.throwOnSideEffect
+    );
     stack = await walkStack(session, pause.callFrames, {
       stackDepth: options.stackDepth ?? DEFAULT_STACK_DEPTH,
       stackCaptures: options.stackCaptures ?? [],
-      maxValueLength
+      maxValueLength,
+      ...options.throwOnSideEffect === void 0 ? {} : { throwOnSideEffect: options.throwOnSideEffect }
     });
   }
   const exception = await captureException(session, pause, maxValueLength);
@@ -1607,24 +2112,49 @@ function buildResult2(input) {
   const withStack = input.stack.length > 0 ? { ...withFrame, stack: input.stack } : withFrame;
   return input.exception === void 0 ? withStack : { ...withStack, exception: input.exception };
 }
-async function captureExpressions(session, callFrameId, captures, maxValueLength) {
+async function captureExpressions(session, callFrameId, captures, maxValueLength, throwOnSideEffect) {
   if (captures === void 0 || captures.length === 0) {
     return [];
   }
   return await Promise.all(
     captures.map(async (expression) => {
-      return await captureExpression(session, callFrameId, expression, maxValueLength);
+      return await captureExpression(
+        session,
+        callFrameId,
+        expression,
+        maxValueLength,
+        throwOnSideEffect
+      );
     })
   );
 }
-async function captureExpression(session, callFrameId, expression, maxValueLength) {
+async function captureExpression(session, callFrameId, expression, maxValueLength, throwOnSideEffect) {
+  const mutationRisk = throwOnSideEffect === false && looksLikeMutation(expression);
   try {
-    const result = await evaluateOnFrame(session, callFrameId, expression);
+    const result = await evaluateOnFrame(session, callFrameId, expression, {
+      ...throwOnSideEffect === void 0 ? {} : { throwOnSideEffect }
+    });
+    if (isSideEffectRefusal(result)) {
+      return sideEffectRefusalToCaptured(expression);
+    }
     const captured = evalResultToCaptured(expression, result, maxValueLength);
-    return await withSerializedObjectCapture(session, expression, result, captured, maxValueLength);
+    const serialized = await withSerializedObjectCapture(
+      session,
+      expression,
+      result,
+      captured,
+      maxValueLength
+    );
+    return mutationRisk ? { ...serialized, mutationRisk: true } : serialized;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return { expression, error: limitValueLength(message, maxValueLength) };
+    const limited = limitValueLength(message, maxValueLength);
+    const captured = {
+      expression,
+      error: limited.text,
+      ...textTruncationFields(limited)
+    };
+    return mutationRisk ? { ...captured, mutationRisk: true } : captured;
   }
 }
 
@@ -1712,7 +2242,7 @@ function readArg(arg, index) {
   }
   return index === 0 ? void 0 : "";
 }
-function parseLogEvent(rawArgs, sentinel, location, timestamp) {
+function parseLogEvent(rawArgs, sentinel, location, timestamp, maxValueLength = DEFAULT_STREAM_MAX_VALUE_LENGTH) {
   if (!Array.isArray(rawArgs) || rawArgs.length < 2) {
     return void 0;
   }
@@ -1724,21 +2254,37 @@ function parseLogEvent(rawArgs, sentinel, location, timestamp) {
   const ts = new Date(typeof timestamp === "number" ? timestamp : Date.now()).toISOString();
   const at = `${location.file}:${location.line.toString()}`;
   if (payload.startsWith("!err:")) {
-    return { ts, at, error: payload.slice("!err:".length) };
+    const limited = limitValueLength(payload.slice("!err:".length), maxValueLength);
+    return {
+      ts,
+      at,
+      error: limited.text,
+      ...textTruncationFields(limited)
+    };
   }
-  return parsePayload(ts, at, payload);
+  return parsePayload(ts, at, payload, maxValueLength);
 }
-function parsePayload(ts, at, payload) {
+function parsePayload(ts, at, payload, maxValueLength) {
   try {
     const parsed = JSON.parse(payload);
     if (typeof parsed === "string") {
-      return { ts, at, value: parsed };
+      return buildValueEvent(ts, at, parsed, maxValueLength);
     }
-    return { ts, at, value: JSON.stringify(parsed) };
+    return buildValueEvent(ts, at, JSON.stringify(parsed), maxValueLength);
   } catch {
-    return { ts, at, value: payload, raw: payload };
+    return buildValueEvent(ts, at, payload, maxValueLength, true);
   }
 }
+function buildValueEvent(ts, at, value, maxValueLength, includeRaw = false) {
+  const limited = limitValueLength(value, maxValueLength);
+  return {
+    ts,
+    at,
+    value: limited.text,
+    ...includeRaw ? { raw: limited.text } : {},
+    ...textTruncationFields(limited)
+  };
+}
 
 // src/logpoint/stream.ts
 function validateMaxEvents(maxEvents) {
@@ -1768,6 +2314,9 @@ function validateHitCount2(hitCount) {
 async function streamLogpoint(session, options) {
   const maxEvents = validateMaxEvents(options.maxEvents);
   const hitCount = validateHitCount2(options.hitCount);
+  const maxValueLength = resolveMaxValueLength(
+    options.maxValueLength ?? DEFAULT_STREAM_MAX_VALUE_LENGTH
+  );
   const sentinel = generateSentinel();
   const condition = buildLogpointCondition(sentinel, options.expression, {
     ...options.condition === void 0 ? {} : { predicate: options.condition },
@@ -1780,7 +2329,7 @@ async function streamLogpoint(session, options) {
     if (maxEventsReached) {
       return;
     }
-    const event = toLogpointEvent(raw, sentinel, options.location);
+    const event = toLogpointEvent(raw, sentinel, options.location, maxValueLength);
     if (event === void 0) {
       return;
     }
@@ -1820,13 +2369,13 @@ async function streamLogpoint(session, options) {
     await removeBreakpointBestEffort(session, handle.breakpointId);
   }
 }
-function toLogpointEvent(raw, sentinel, location) {
+function toLogpointEvent(raw, sentinel, location, maxValueLength) {
   const params = raw;
   if (asString3(params.type) !== "log") {
     return void 0;
   }
   const ts = typeof params.timestamp === "number" ? params.timestamp : void 0;
-  return parseLogEvent(params.args, sentinel, location, ts);
+  return parseLogEvent(params.args, sentinel, location, ts, maxValueLength);
 }
 async function removeBreakpointBestEffort(session, breakpointId) {
   try {