@botim/mp-debug-sdk 0.5.2 → 0.6.1

package/dist/index.d.cts

@@ -52,6 +52,36 @@ interface BuiltinHostHooks {
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    /**
+     * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
+     * of registration entirely; pass an object to inject extra locals into
+     * every snippet's scope.
+     *
+     *   builtins: { exec: false }
+     *     → exec NOT registered; agents calling exec see `unknown-command`.
+     *
+     *   builtins: { exec: { globals: { app, store } } }
+     *     → exec registered; snippets can reference `app` and `store` as
+     *       bare identifiers. Default locals (`BOT`, `window`, `document`)
+     *       are always present.
+     *
+     *   builtins.exec is undefined / not set
+     *     → default behaviour: exec registered with default locals only.
+     *
+     * See `openspec/changes/add-default-exec-builtin/design.md` for the
+     * security rationale (no prod-specific gating in MVP; relies on the
+     * existing `enableRemoteDebug` consent gate).
+     */
+    exec?: false | ExecOptions;
+}
+interface ExecOptions {
+    /**
+     * Additional locals bound into every snippet's scope. Keys MUST be
+     * valid identifier names (the SDK does not validate this — passing a
+     * key like "1foo" or "a-b" will throw at AsyncFunction construction
+     * time and surface as a `command-rejected`).
+     */
+    globals?: Record<string, unknown>;
 }
 type ScreenshotResult = string | {
     data: string;
@@ -71,6 +101,7 @@ type ScreenshotResult = string | {
      */
      | 'html-snapshot';
 };
+declare function getBOT(): unknown;
 
 /**
  * Per-signature sliding-window event deduper.
@@ -211,4 +242,4 @@ declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug, getBOT };

package/dist/index.d.ts

@@ -52,6 +52,36 @@ interface BuiltinHostHooks {
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    /**
+     * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
+     * of registration entirely; pass an object to inject extra locals into
+     * every snippet's scope.
+     *
+     *   builtins: { exec: false }
+     *     → exec NOT registered; agents calling exec see `unknown-command`.
+     *
+     *   builtins: { exec: { globals: { app, store } } }
+     *     → exec registered; snippets can reference `app` and `store` as
+     *       bare identifiers. Default locals (`BOT`, `window`, `document`)
+     *       are always present.
+     *
+     *   builtins.exec is undefined / not set
+     *     → default behaviour: exec registered with default locals only.
+     *
+     * See `openspec/changes/add-default-exec-builtin/design.md` for the
+     * security rationale (no prod-specific gating in MVP; relies on the
+     * existing `enableRemoteDebug` consent gate).
+     */
+    exec?: false | ExecOptions;
+}
+interface ExecOptions {
+    /**
+     * Additional locals bound into every snippet's scope. Keys MUST be
+     * valid identifier names (the SDK does not validate this — passing a
+     * key like "1foo" or "a-b" will throw at AsyncFunction construction
+     * time and surface as a `command-rejected`).
+     */
+    globals?: Record<string, unknown>;
 }
 type ScreenshotResult = string | {
     data: string;
@@ -71,6 +101,7 @@ type ScreenshotResult = string | {
      */
      | 'html-snapshot';
 };
+declare function getBOT(): unknown;
 
 /**
  * Per-signature sliding-window event deduper.
@@ -211,4 +242,4 @@ declare const DEFAULT_BUFFER_SIZE = 1000;
 declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, ConsentInput, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, enableRemoteDebug, getBOT };

package/dist/index.js

@@ -817,6 +817,10 @@ var CommandRegistry = class {
 };
 var MAX_DUMP_BYTES = 64 * 1024;
 var MAX_SCREENSHOT_BYTES = 1024 * 1024;
+var MAX_EXEC_CODE_BYTES = 8 * 1024;
+var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
+var MIN_EXEC_TIMEOUT_MS = 250;
+var MAX_EXEC_TIMEOUT_MS = 3e4;
 async function defaultDomScreenshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
@@ -931,6 +935,9 @@ function registerBuiltins(registry, hooks = {}) {
   registry.register("dump-state", makeDumpState(hooks.getState));
   registry.register("set-feature-flag", makeSetFlag(hooks.setFeatureFlag));
   registry.register("screenshot", makeScreenshot(hooks.screenshot));
+  if (hooks.exec !== false) {
+    registry.register("exec", makeExec(hooks.exec ?? {}));
+  }
 }
 var ping = () => ({ ok: true, ts: Date.now() });
 function makeReload(reload) {
@@ -993,6 +1000,168 @@ function makeScreenshot(screenshot) {
     return { format, data, bytes: data.length };
   };
 }
+var cachedBOT = void 0;
+function getBOT() {
+  if (cachedBOT !== void 0) return cachedBOT;
+  if (typeof window === "undefined") {
+    cachedBOT = null;
+    return null;
+  }
+  try {
+    const w = window;
+    if (w.BOT) {
+      cachedBOT = w.BOT;
+      return cachedBOT;
+    }
+  } catch {
+  }
+  try {
+    const w = window;
+    const ng = w.angular;
+    if (ng?.element && typeof document !== "undefined") {
+      const injector = ng.element(document).injector?.();
+      const bot = injector?.get?.("BOT");
+      if (bot != null) {
+        cachedBOT = bot;
+        return cachedBOT;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function makeExec(opts) {
+  const extraGlobalNames = Object.keys(opts.globals ?? {});
+  const extraGlobalValues = extraGlobalNames.map((k) => opts.globals[k]);
+  return async (args, ctx) => {
+    if (typeof args.code !== "string" || args.code.length === 0) {
+      throw new Error("args.code (non-empty string) is required");
+    }
+    if (args.code.length > MAX_EXEC_CODE_BYTES) {
+      throw new Error(`args.code ${args.code.length} bytes exceeds limit ${MAX_EXEC_CODE_BYTES}`);
+    }
+    const timeoutMs = clamp(
+      typeof args.timeoutMs === "number" ? args.timeoutMs : DEFAULT_EXEC_TIMEOUT_MS,
+      MIN_EXEC_TIMEOUT_MS,
+      MAX_EXEC_TIMEOUT_MS
+    );
+    const start = Date.now();
+    const logs = [];
+    const consoleMethods = ["log", "info", "warn", "error", "debug"];
+    const originals = {};
+    if (typeof console !== "undefined") {
+      for (const m of consoleMethods) {
+        const orig = console[m];
+        if (typeof orig !== "function") continue;
+        originals[m] = orig;
+        const captured = (...callArgs) => {
+          logs.push({ method: m, args: callArgs.map(execSafeClone), ts: Date.now() });
+          try {
+            orig.call(console, ...callArgs);
+          } catch {
+          }
+        };
+        console[m] = captured;
+      }
+    }
+    let value;
+    let threw = void 0;
+    try {
+      const AsyncFunction = Object.getPrototypeOf(async function() {
+      }).constructor;
+      const localNames = ["BOT", "window", "document", ...extraGlobalNames];
+      const localValues = [
+        getBOT(),
+        typeof window !== "undefined" ? window : void 0,
+        typeof document !== "undefined" ? document : void 0,
+        ...extraGlobalValues
+      ];
+      let fnTry = null;
+      try {
+        fnTry = new AsyncFunction(...localNames, `return (${args.code});`);
+      } catch (e) {
+        if (!(e instanceof SyntaxError)) throw e;
+      }
+      const fn = fnTry ?? new AsyncFunction(...localNames, args.code);
+      let timer = null;
+      let abortReject = null;
+      const onAbort = () => abortReject?.(new Error("exec cancelled"));
+      ctx.signal?.addEventListener?.("abort", onAbort);
+      try {
+        value = await Promise.race([
+          fn(...localValues),
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(new Error(`exec exceeded ${timeoutMs}ms`)),
+              timeoutMs
+            );
+          }),
+          new Promise((_, reject) => {
+            abortReject = reject;
+          })
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+        ctx.signal?.removeEventListener?.("abort", onAbort);
+      }
+    } catch (err) {
+      threw = err;
+    } finally {
+      if (typeof console !== "undefined") {
+        for (const m of consoleMethods) {
+          if (originals[m]) {
+            console[m] = originals[m];
+          }
+        }
+      }
+    }
+    if (threw !== void 0) {
+      const e = threw instanceof Error ? threw : new Error(String(threw));
+      const stackTruncated = typeof e.stack === "string" ? e.stack.split("\n").slice(0, 20).join("\n") : void 0;
+      const detail = {
+        name: e.name,
+        message: e.message,
+        stack: stackTruncated,
+        logs,
+        durationMs: Date.now() - start
+      };
+      const wrapped = new Error(JSON.stringify(detail));
+      wrapped.detail = detail;
+      throw wrapped;
+    }
+    return {
+      ok: true,
+      value: execSafeClone(value),
+      logs,
+      durationMs: Date.now() - start
+    };
+  };
+}
+function clamp(n, lo, hi) {
+  if (!Number.isFinite(n)) return lo;
+  return Math.min(Math.max(n, lo), hi);
+}
+function execSafeClone(v) {
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, val) => {
+      if (typeof val === "function") {
+        return `[Function: ${val.name || "anonymous"}]`;
+      }
+      if (val instanceof Error) {
+        return { name: val.name, message: val.message, stack: val.stack };
+      }
+      if (typeof val === "bigint") return val.toString() + "n";
+      if (typeof val === "undefined") return null;
+      if (val && typeof val === "object" && val.nodeType === 1) {
+        const el = val;
+        return `[${el.tagName ?? "Element"}${el.id ? "#" + el.id : ""}]`;
+      }
+      return val;
+    }));
+  } catch {
+    return { __unserializable: typeof v };
+  }
+}
 function safeStringify(v) {
   try {
     const seen = /* @__PURE__ */ new WeakSet();
@@ -1430,6 +1599,6 @@ async function enableRemoteDebug(options) {
   };
 }
 
-export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, enableRemoteDebug };
+export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, enableRemoteDebug, getBOT };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map