@saptools/cf-inspector 0.3.18 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { DebuggerHandle } from '@saptools/cf-debugger';
 
-type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "BREAKPOINT_DID_NOT_BIND" | "INSPECTOR_DISCOVERY_FAILED" | "INSPECTOR_CONNECTION_FAILED" | "CDP_REQUEST_FAILED" | "BREAKPOINT_NOT_HIT" | "UNRELATED_PAUSE" | "UNRELATED_PAUSE_TIMEOUT" | "EVALUATION_FAILED" | "MISSING_TARGET" | "ABORTED";
+type CfInspectorErrorCode = "INVALID_ARGUMENT" | "INVALID_BREAKPOINT" | "INVALID_REMOTE_ROOT" | "INVALID_EXPRESSION" | "INVALID_HIT_COUNT" | "INVALID_PAUSE_TYPE" | "BREAKPOINT_DID_NOT_BIND" | "INSPECTOR_DISCOVERY_FAILED" | "INSPECTOR_CONNECTION_FAILED" | "CDP_REQUEST_FAILED" | "BREAKPOINT_NOT_HIT" | "UNRELATED_PAUSE" | "UNRELATED_PAUSE_TIMEOUT" | "EVALUATION_FAILED" | "MISSING_TARGET" | "ABORTED";
 declare class CfInspectorError extends Error {
     readonly code: CfInspectorErrorCode;
     readonly detail?: string;
@@ -55,6 +55,7 @@ interface PauseEvent {
     readonly hitBreakpoints: readonly string[];
     readonly callFrames: readonly CallFrameInfo[];
     readonly receivedAtMs?: number;
+    readonly data?: unknown;
 }
 interface VariableSnapshot {
     readonly name: string;
@@ -72,6 +73,7 @@ interface FrameSnapshot {
     readonly line: number;
     readonly column: number;
     readonly scopes?: readonly ScopeSnapshot[];
+    readonly captures?: readonly CapturedExpression[];
 }
 interface CapturedExpression {
     readonly expression: string;
@@ -79,16 +81,35 @@ interface CapturedExpression {
     readonly type?: string;
     readonly error?: string;
 }
+interface ExceptionSnapshot {
+    readonly value?: string;
+    readonly type?: string;
+    readonly description?: string;
+    readonly error?: string;
+}
 interface SnapshotCaptureResult {
     readonly reason: string;
     readonly hitBreakpoints: readonly string[];
     readonly capturedAt: string;
     readonly topFrame?: FrameSnapshot;
     readonly captures: readonly CapturedExpression[];
+    readonly stack?: readonly FrameSnapshot[];
+    readonly exception?: ExceptionSnapshot;
 }
 interface SnapshotResult extends SnapshotCaptureResult {
     readonly pausedDurationMs: number | null;
 }
+interface WatchEvent {
+    readonly ts: string;
+    readonly at: string;
+    readonly hit: number;
+    readonly reason: string;
+    readonly hitBreakpoints: readonly string[];
+    readonly topFrame?: FrameSnapshot;
+    readonly captures: readonly CapturedExpression[];
+    readonly stack?: readonly FrameSnapshot[];
+    readonly exception?: ExceptionSnapshot;
+}
 interface ScriptInfo {
     readonly scriptId: string;
     readonly url: string;
@@ -218,20 +239,25 @@ interface CdpProperty {
 interface SetBreakpointInput extends BreakpointLocation {
     readonly remoteRoot?: RemoteRootSetting;
     readonly condition?: string;
+    readonly hitCount?: number;
 }
 interface WaitForPauseOptions {
     readonly timeoutMs: number;
     readonly breakpointIds?: readonly string[];
+    readonly pauseReasons?: readonly string[];
     readonly unmatchedPausePolicy?: "wait-for-resume" | "fail";
     readonly onUnmatchedPause?: (pause: PauseEvent) => void;
 }
 
+declare function buildHitCountedCondition(hitCount: number, counterKey: string, userCondition: string | undefined): string;
 declare function setBreakpoint(session: InspectorSession, input: SetBreakpointInput): Promise<BreakpointHandle>;
 declare function removeBreakpoint(session: InspectorSession, breakpointId: string): Promise<void>;
 
 declare function waitForPause(session: InspectorSession, options: WaitForPauseOptions): Promise<PauseEvent>;
 
+type PauseOnExceptionsState = "none" | "uncaught" | "caught" | "all";
 declare function resume(session: InspectorSession): Promise<void>;
+declare function setPauseOnExceptions(session: InspectorSession, state: PauseOnExceptionsState): Promise<void>;
 declare function evaluateOnFrame(session: InspectorSession, callFrameId: string, expression: string): Promise<CdpEvalResult>;
 declare function evaluateGlobal(session: InspectorSession, expression: string): Promise<CdpEvalResult>;
 declare function listScripts(session: InspectorSession): readonly ScriptInfo[];
@@ -244,10 +270,26 @@ interface CaptureSnapshotOptions {
     readonly captures?: readonly string[];
     readonly includeScopes?: boolean;
     readonly maxValueLength?: number;
+    readonly stackDepth?: number;
+    readonly stackCaptures?: readonly string[];
 }
 declare function captureSnapshot(session: InspectorSession, pause: PauseEvent, options?: CaptureSnapshotOptions): Promise<SnapshotCaptureResult>;
 
-declare function buildLogpointCondition(sentinel: string, expression: string): string;
+declare function captureException(session: InspectorSession, pause: PauseEvent, maxValueLength: number): Promise<ExceptionSnapshot | undefined>;
+
+interface WalkStackOptions {
+    readonly stackDepth: number;
+    readonly stackCaptures: readonly string[];
+    readonly maxValueLength: number;
+}
+declare function walkStack(session: InspectorSession, callFrames: readonly CallFrameInfo[], options: WalkStackOptions): Promise<readonly FrameSnapshot[]>;
+
+interface LogpointConditionOptions {
+    readonly predicate?: string;
+    readonly hitCount?: number;
+    readonly counterKey?: string;
+}
+declare function buildLogpointCondition(sentinel: string, expression: string, options?: LogpointConditionOptions): string;
 
 interface LogpointEvent {
     readonly ts: string;
@@ -257,11 +299,15 @@ interface LogpointEvent {
     readonly raw?: string;
 }
 
+type LogpointStopReason = "duration" | "signal" | "transport-closed" | "max-events";
 interface LogpointStreamOptions {
     readonly location: BreakpointLocation;
     readonly expression: string;
     readonly remoteRoot?: RemoteRootSetting;
     readonly durationMs?: number;
+    readonly maxEvents?: number;
+    readonly hitCount?: number;
+    readonly condition?: string;
     readonly signal?: AbortSignal;
     readonly onEvent: (event: LogpointEvent) => void;
     readonly onBreakpointSet?: (handle: BreakpointHandle) => void;
@@ -270,7 +316,7 @@ interface LogpointStreamResult {
     readonly handle: BreakpointHandle;
     readonly sentinel: string;
     readonly emitted: number;
-    readonly stoppedReason: "duration" | "signal" | "transport-closed";
+    readonly stoppedReason: LogpointStopReason;
 }
 declare function streamLogpoint(session: InspectorSession, options: LogpointStreamOptions): Promise<LogpointStreamResult>;
 
@@ -291,4 +337,4 @@ interface OpenedTunnel {
 }
 declare function openCfTunnel(target: TunnelTarget): Promise<OpenedTunnel>;
 
-export { type BreakpointHandle, type BreakpointLocation, type CallFrameInfo, type CaptureSnapshotOptions, type CapturedExpression, CfInspectorError, type CfInspectorErrorCode, type DebuggerState, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointEvent, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotCaptureResult, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, buildBreakpointUrlRegex, buildLogpointCondition, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, setBreakpoint, streamLogpoint, validateExpression, waitForPause };
+export { type BreakpointHandle, type BreakpointLocation, type CallFrameInfo, type CaptureSnapshotOptions, type CapturedExpression, CfInspectorError, type CfInspectorErrorCode, type DebuggerState, type ExceptionSnapshot, type FrameSnapshot, type InspectorConnectOptions, type InspectorSession, type InspectorTarget, type LogpointConditionOptions, type LogpointEvent, type LogpointStopReason, type LogpointStreamOptions, type LogpointStreamResult, type OpenedTunnel, type PauseEvent, type PauseOnExceptionsState, type RemoteRootSetting, type ResolvedLocation, type ScopeInfo, type ScopeSnapshot, type ScriptInfo, type SetBreakpointInput, type SnapshotCaptureResult, type SnapshotResult, type TunnelTarget, type VariableSnapshot, type WaitForPauseOptions, type WalkStackOptions, type WatchEvent, buildBreakpointUrlRegex, buildHitCountedCondition, buildLogpointCondition, captureException, captureSnapshot, connectInspector, discoverInspectorTargets, evaluateGlobal, evaluateOnFrame, fetchInspectorVersion, getProperties, listScripts, openCfTunnel, parseBreakpointSpec, parseRemoteRoot, removeBreakpoint, resume, setBreakpoint, setPauseOnExceptions, streamLogpoint, validateExpression, waitForPause, walkStack };

package/dist/index.js

@@ -261,6 +261,9 @@ function asString(value, fallback = "") {
 function asNumber(value, fallback = 0) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
 function toResolvedLocations(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -299,7 +302,18 @@ function toScopeChain(value) {
     return [objectId === void 0 ? base : { ...base, objectId }];
   });
 }
-function toCallFrames(value) {
+function resolveCallFrameUrl(frame, scripts) {
+  const direct = nonEmptyString(frame.url);
+  if (direct !== void 0) {
+    return direct;
+  }
+  const scriptId = nonEmptyString(frame.location?.scriptId);
+  if (scriptId === void 0) {
+    return void 0;
+  }
+  return nonEmptyString(scripts?.get(scriptId)?.url);
+}
+function toCallFrames(value, scripts) {
   if (!Array.isArray(value)) {
     return [];
   }
@@ -312,7 +326,7 @@ function toCallFrames(value) {
     if (callFrameId.length === 0) {
       return [];
     }
-    const url = typeof candidate.url === "string" ? candidate.url : void 0;
+    const url = resolveCallFrameUrl(candidate, scripts);
     const base = {
       callFrameId,
       functionName: asString(candidate.functionName),
@@ -323,13 +337,14 @@ function toCallFrames(value) {
     return [url === void 0 ? base : { ...base, url }];
   });
 }
-function toPauseEvent(params, receivedAtMs) {
-  return {
+function toPauseEvent(params, receivedAtMs, scripts) {
+  const base = {
     reason: asString(params.reason),
     hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-    callFrames: toCallFrames(params.callFrames),
+    callFrames: toCallFrames(params.callFrames, scripts),
     receivedAtMs
   };
+  return params.data === void 0 ? base : { ...base, data: params.data };
 }
 function topFrameLocation(pause) {
   const top = pause.callFrames[0];
@@ -348,6 +363,46 @@ function pauseDetail(pause) {
 }
 
 // src/inspector/breakpoints.ts
+var HITS_GLOBAL = "globalThis.__CFI_HITS";
+var counterKeyCounter = 0;
+function nextCounterKey(file, line) {
+  counterKeyCounter += 1;
+  return `${file}:${line.toString()}:${counterKeyCounter.toString()}`;
+}
+function validateHitCount(hitCount) {
+  if (hitCount === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(hitCount) || hitCount <= 0) {
+    throw new CfInspectorError(
+      "INVALID_HIT_COUNT",
+      `hitCount must be a positive integer, received: ${hitCount.toString()}`
+    );
+  }
+  return hitCount;
+}
+function buildHitCountedCondition(hitCount, counterKey, userCondition) {
+  const keyLiteral = JSON.stringify(counterKey);
+  const baseCondition = userCondition !== void 0 && userCondition.trim().length > 0 ? `(${userCondition})` : "true";
+  return [
+    "(function(){",
+    `var m=(${HITS_GLOBAL}=${HITS_GLOBAL}||{});`,
+    `var k=${keyLiteral};`,
+    "m[k]=(m[k]||0)+1;",
+    `if(m[k]<${hitCount.toString()})return false;`,
+    `return ${baseCondition};`,
+    "})()"
+  ].join("");
+}
+function resolveCondition(input) {
+  const condition = input.condition;
+  const hitCount = validateHitCount(input.hitCount);
+  if (hitCount === void 0) {
+    return condition !== void 0 && condition.length > 0 ? condition : void 0;
+  }
+  const counterKey = nextCounterKey(input.file, input.line);
+  return buildHitCountedCondition(hitCount, counterKey, condition);
+}
 async function setBreakpoint(session, input) {
   const remoteRoot = input.remoteRoot ?? { kind: "none" };
   const urlRegex = buildBreakpointUrlRegex({ file: input.file, remoteRoot });
@@ -355,8 +410,9 @@ async function setBreakpoint(session, input) {
     lineNumber: input.line - 1,
     urlRegex
   };
-  if (input.condition !== void 0 && input.condition.length > 0) {
-    params["condition"] = input.condition;
+  const condition = resolveCondition(input);
+  if (condition !== void 0) {
+    params["condition"] = condition;
   }
   const result = await session.client.send(
     "Debugger.setBreakpointByUrl",
@@ -502,7 +558,10 @@ async function fetchInspectorVersion(host, port, timeoutMs) {
 // src/inspector/pause.ts
 init_types();
 import { performance } from "perf_hooks";
-function pauseMatches(pause, breakpointIds) {
+function pauseMatches(pause, breakpointIds, pauseReasons) {
+  if (pauseReasons !== void 0 && pauseReasons.length > 0) {
+    return pauseReasons.includes(pause.reason);
+  }
   if (breakpointIds === void 0 || breakpointIds.length === 0) {
     return true;
   }
@@ -570,13 +629,13 @@ async function waitForPause(session, options) {
       if (buffered === void 0) {
         continue;
       }
-      if (pauseMatches(buffered, options.breakpointIds)) {
+      if (pauseMatches(buffered, options.breakpointIds, options.pauseReasons)) {
         return buffered;
       }
       await handleUnmatchedPause(session, buffered, options, deadlineMs);
     }
     const pause = await waitForLivePause(session, options, deadlineMs);
-    if (pauseMatches(pause, options.breakpointIds)) {
+    if (pauseMatches(pause, options.breakpointIds, options.pauseReasons)) {
       return pause;
     }
     await handleUnmatchedPause(session, pause, options, deadlineMs);
@@ -602,7 +661,7 @@ async function waitForLivePause(session, options, deadlineMs) {
   } finally {
     session.pauseWaitGate.active = false;
   }
-  return toPauseEvent(params, receivedAtMs ?? performance.now());
+  return toPauseEvent(params, receivedAtMs ?? performance.now(), session.scripts);
 }
 
 // src/inspector/runtime.ts
@@ -610,6 +669,9 @@ init_types();
 async function resume(session) {
   await session.client.send("Debugger.resume");
 }
+async function setPauseOnExceptions(session, state) {
+  await session.client.send("Debugger.setPauseOnExceptions", { state });
+}
 async function evaluateOnFrame(session, callFrameId, expression) {
   return await session.client.send("Debugger.evaluateOnCallFrame", {
     callFrameId,
@@ -916,7 +978,7 @@ async function connectInspector(options) {
       return;
     }
     const params = raw;
-    const event = toPauseEvent(params, performance2.now());
+    const event = toPauseEvent(params, performance2.now(), scripts);
     if (pauseBuffer.length >= PAUSE_BUFFER_LIMIT) {
       pauseBuffer.shift();
     }
@@ -1160,6 +1222,93 @@ async function capturePropertyChildren(session, described, depth, maxValueLength
   }
 }
 
+// src/snapshot/exception.ts
+function asString2(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+async function materializeObject(session, objectId, maxValueLength) {
+  try {
+    const properties = await captureProperties(
+      session,
+      objectId,
+      MAX_SCOPE_VARIABLES,
+      MAX_VARIABLE_DEPTH,
+      maxValueLength
+    );
+    if (properties.length === 0) {
+      return void 0;
+    }
+    const structured = {};
+    for (const variable of properties) {
+      structured[variable.name] = toStructuredValue(variable);
+    }
+    return JSON.stringify(structured);
+  } catch {
+    return void 0;
+  }
+}
+async function readPropertyDescription(session, objectId, name) {
+  try {
+    const properties = await getProperties(session, objectId);
+    for (const prop of properties) {
+      if (prop.name !== name) {
+        continue;
+      }
+      const value = prop.value;
+      if (value === void 0) {
+        continue;
+      }
+      if (typeof value.value === "string") {
+        return value.value;
+      }
+      if (typeof value.description === "string") {
+        return value.description;
+      }
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function captureException(session, pause, maxValueLength) {
+  if (pause.reason !== "exception" && pause.reason !== "promiseRejection") {
+    return void 0;
+  }
+  const data = pause.data;
+  if (typeof data !== "object" || data === null) {
+    return { error: "no exception data attached" };
+  }
+  const candidate = data;
+  const type = asString2(candidate.type);
+  const description = asString2(candidate.description);
+  if (typeof candidate.value === "string") {
+    return buildResult(type, description, JSON.stringify(candidate.value), maxValueLength);
+  }
+  if (typeof candidate.value === "number" || typeof candidate.value === "boolean") {
+    return buildResult(type, description, String(candidate.value), maxValueLength);
+  }
+  const objectId = asString2(candidate.objectId);
+  if (objectId === void 0) {
+    if (description !== void 0) {
+      return buildResult(type, description, description, maxValueLength);
+    }
+    return { error: "exception data has no objectId or value" };
+  }
+  const message = await readPropertyDescription(session, objectId, "message");
+  const rendered = await materializeObject(session, objectId, maxValueLength);
+  if (rendered !== void 0) {
+    const result = buildResult(type, description, rendered, maxValueLength);
+    return message === void 0 ? result : { ...result, description: limitValueLength(message, maxValueLength) };
+  }
+  return buildResult(type, description, description ?? "[exception]", maxValueLength);
+}
+function buildResult(type, description, value, maxValueLength) {
+  const safeValue = limitValueLength(value, maxValueLength);
+  const base = { value: safeValue };
+  const withType = type === void 0 ? base : { ...base, type };
+  return description === void 0 ? withType : { ...withType, description: limitValueLength(description, maxValueLength) };
+}
+
 // src/snapshot/objects.ts
 function objectIdFromEvalResult(result) {
   const inner = result.result;
@@ -1262,12 +1411,73 @@ async function captureScopes(session, frame, maxValueLength) {
   );
 }
 
+// src/snapshot/stack.ts
+var DEFAULT_STACK_DEPTH = 1;
+var MAX_STACK_DEPTH = 64;
+function clampDepth(depth, frameCount) {
+  if (depth <= 0) {
+    return 0;
+  }
+  return Math.min(depth, frameCount, MAX_STACK_DEPTH);
+}
+function buildBaseFrame(frame) {
+  const base = {
+    functionName: frame.functionName,
+    line: frame.lineNumber + 1,
+    column: frame.columnNumber + 1
+  };
+  return frame.url === void 0 ? base : { ...base, url: frame.url };
+}
+async function captureFrameExpression(session, callFrameId, expression, maxValueLength) {
+  try {
+    const result = await evaluateOnFrame(session, callFrameId, expression);
+    const captured = evalResultToCaptured(expression, result, maxValueLength);
+    return await withSerializedObjectCapture(session, expression, result, captured, maxValueLength);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { expression, error: limitValueLength(message, maxValueLength) };
+  }
+}
+async function captureFrameExpressions(session, frame, expressions, maxValueLength) {
+  if (expressions.length === 0) {
+    return [];
+  }
+  return await Promise.all(
+    expressions.map(
+      (expression) => captureFrameExpression(session, frame.callFrameId, expression, maxValueLength)
+    )
+  );
+}
+async function walkStack(session, callFrames, options) {
+  const depth = clampDepth(options.stackDepth, callFrames.length);
+  if (depth <= 1) {
+    return [];
+  }
+  const slice = callFrames.slice(0, depth);
+  return await Promise.all(
+    slice.map(async (frame) => {
+      const base = buildBaseFrame(frame);
+      if (options.stackCaptures.length === 0) {
+        return base;
+      }
+      const captures = await captureFrameExpressions(
+        session,
+        frame,
+        options.stackCaptures,
+        options.maxValueLength
+      );
+      return { ...base, captures };
+    })
+  );
+}
+
 // src/snapshot/capture.ts
 async function captureSnapshot(session, pause, options = {}) {
   const maxValueLength = resolveMaxValueLength(options.maxValueLength);
   const top = pause.callFrames[0];
   let topFrame;
   let captures = [];
+  let stack = [];
   if (top) {
     topFrame = {
       functionName: top.functionName,
@@ -1280,14 +1490,31 @@ async function captureSnapshot(session, pause, options = {}) {
       topFrame = { ...topFrame, scopes };
     }
     captures = await captureExpressions(session, top.callFrameId, options.captures, maxValueLength);
+    stack = await walkStack(session, pause.callFrames, {
+      stackDepth: options.stackDepth ?? DEFAULT_STACK_DEPTH,
+      stackCaptures: options.stackCaptures ?? [],
+      maxValueLength
+    });
   }
-  return {
-    reason: pause.reason,
-    hitBreakpoints: pause.hitBreakpoints,
+  const exception = await captureException(session, pause, maxValueLength);
+  return buildResult2({
+    pause,
+    topFrame,
+    captures,
+    stack,
+    exception
+  });
+}
+function buildResult2(input) {
+  const base = {
+    reason: input.pause.reason,
+    hitBreakpoints: input.pause.hitBreakpoints,
     capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    ...topFrame === void 0 ? {} : { topFrame },
-    captures
+    captures: input.captures
   };
+  const withFrame = input.topFrame === void 0 ? base : { ...base, topFrame: input.topFrame };
+  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) {
   if (captures === void 0 || captures.length === 0) {
@@ -1314,7 +1541,8 @@ async function captureExpression(session, callFrameId, expression, maxValueLengt
 import { randomBytes } from "crypto";
 var SENTINEL_PREFIX = "__CFI_LOG_";
 var SENTINEL_SUFFIX = "__";
-function buildLogpointCondition(sentinel, expression) {
+var HITS_GLOBAL2 = "globalThis.__CFI_LOG_HITS";
+function buildLoggingIife(sentinel, expression) {
   return [
     "(function(){",
     `var s=${JSON.stringify(sentinel)};`,
@@ -1329,12 +1557,53 @@ function buildLogpointCondition(sentinel, expression) {
     "})()"
   ].join("");
 }
+function buildHitGate(hitCount, counterKey) {
+  const keyLiteral = JSON.stringify(counterKey);
+  return [
+    "(function(){",
+    `var m=(${HITS_GLOBAL2}=${HITS_GLOBAL2}||{});`,
+    `var k=${keyLiteral};`,
+    "m[k]=(m[k]||0)+1;",
+    `return m[k]>=${hitCount.toString()};`,
+    "})()"
+  ].join("");
+}
+function combineGuards(guards) {
+  const filtered = guards.filter((guard) => guard.length > 0);
+  if (filtered.length === 0) {
+    return void 0;
+  }
+  if (filtered.length === 1) {
+    return filtered[0];
+  }
+  return filtered.map((guard) => `(${guard})`).join("&&");
+}
+function buildLogpointCondition(sentinel, expression, options = {}) {
+  const guards = [];
+  if (options.hitCount !== void 0) {
+    const counterKey = options.counterKey ?? sentinel;
+    guards.push(buildHitGate(options.hitCount, counterKey));
+  }
+  const userPredicate = options.predicate?.trim();
+  if (userPredicate !== void 0 && userPredicate.length > 0) {
+    guards.push(`(${userPredicate})`);
+  }
+  const iife = buildLoggingIife(sentinel, expression);
+  const guard = combineGuards(guards);
+  if (guard === void 0) {
+    return iife;
+  }
+  return `(${guard})?${iife}:false`;
+}
 function generateSentinel() {
   return `${SENTINEL_PREFIX}${randomBytes(8).toString("hex")}${SENTINEL_SUFFIX}`;
 }
 
+// src/logpoint/stream.ts
+init_types();
+
 // src/logpoint/events.ts
-function asString2(value) {
+function asString3(value) {
   return typeof value === "string" ? value : void 0;
 }
 function readArg(arg, index) {
@@ -1381,17 +1650,55 @@ function parsePayload(ts, at, payload) {
 }
 
 // src/logpoint/stream.ts
+function validateMaxEvents(maxEvents) {
+  if (maxEvents === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(maxEvents) || maxEvents <= 0) {
+    throw new CfInspectorError(
+      "INVALID_ARGUMENT",
+      `maxEvents must be a positive integer, received: ${maxEvents.toString()}`
+    );
+  }
+  return maxEvents;
+}
+function validateHitCount2(hitCount) {
+  if (hitCount === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(hitCount) || hitCount <= 0) {
+    throw new CfInspectorError(
+      "INVALID_HIT_COUNT",
+      `hitCount must be a positive integer, received: ${hitCount.toString()}`
+    );
+  }
+  return hitCount;
+}
 async function streamLogpoint(session, options) {
+  const maxEvents = validateMaxEvents(options.maxEvents);
+  const hitCount = validateHitCount2(options.hitCount);
   const sentinel = generateSentinel();
-  const condition = buildLogpointCondition(sentinel, options.expression);
+  const condition = buildLogpointCondition(sentinel, options.expression, {
+    ...options.condition === void 0 ? {} : { predicate: options.condition },
+    ...hitCount === void 0 ? {} : { hitCount }
+  });
   let emitted = 0;
+  let maxEventsReached = false;
+  let stopMaxEvents;
   const offEvent = session.client.on("Runtime.consoleAPICalled", (raw) => {
+    if (maxEventsReached) {
+      return;
+    }
     const event = toLogpointEvent(raw, sentinel, options.location);
     if (event === void 0) {
       return;
     }
     emitted += 1;
     options.onEvent(event);
+    if (maxEvents !== void 0 && emitted >= maxEvents) {
+      maxEventsReached = true;
+      stopMaxEvents?.();
+    }
   });
   let handle;
   try {
@@ -1407,7 +1714,12 @@ async function streamLogpoint(session, options) {
   }
   options.onBreakpointSet?.(handle);
   try {
-    const reason = await waitForStop(session, options);
+    const reason = await waitForStop(session, options, (signal) => {
+      stopMaxEvents = signal;
+      if (maxEventsReached) {
+        signal();
+      }
+    });
     return { handle, sentinel, emitted, stoppedReason: reason };
   } finally {
     offEvent();
@@ -1416,7 +1728,7 @@ async function streamLogpoint(session, options) {
 }
 function toLogpointEvent(raw, sentinel, location) {
   const params = raw;
-  if (asString2(params.type) !== "log") {
+  if (asString3(params.type) !== "log") {
     return void 0;
   }
   const ts = typeof params.timestamp === "number" ? params.timestamp : void 0;
@@ -1428,7 +1740,7 @@ async function removeBreakpointBestEffort(session, breakpointId) {
   } catch {
   }
 }
-async function waitForStop(session, options) {
+async function waitForStop(session, options, registerMaxEventsSignal) {
   return await new Promise((resolve) => {
     let settled = false;
     const finish = (reason) => {
@@ -1452,6 +1764,9 @@ async function waitForStop(session, options) {
     if (options.signal?.aborted === true) {
       finish("signal");
     }
+    registerMaxEventsSignal(() => {
+      finish("max-events");
+    });
     function cleanup() {
       if (timer !== void 0) {
         clearTimeout(timer);
@@ -1487,7 +1802,9 @@ async function openCfTunnel(target) {
 export {
   CfInspectorError,
   buildBreakpointUrlRegex,
+  buildHitCountedCondition,
   buildLogpointCondition,
+  captureException,
   captureSnapshot,
   connectInspector,
   discoverInspectorTargets,
@@ -1502,8 +1819,10 @@ export {
   removeBreakpoint,
   resume,
   setBreakpoint,
+  setPauseOnExceptions,
   streamLogpoint,
   validateExpression,
-  waitForPause
+  waitForPause,
+  walkStack
 };
 //# sourceMappingURL=index.js.map