opensteer 0.4.12 → 0.4.14

package/dist/{chunk-HQLFJFJM.js → chunk-WXUXG76V.js}

@@ -2,6 +2,232 @@ import {
   flattenExtractionDataToFieldPlan
 } from "./chunk-3H5RRIMZ.js";
 
+// src/error-normalization.ts
+function extractErrorMessage(error, fallback = "Unknown error.") {
+  if (error instanceof Error) {
+    const message = error.message.trim();
+    if (message) return message;
+    const name = error.name.trim();
+    if (name) return name;
+  }
+  if (typeof error === "string" && error.trim()) {
+    return error.trim();
+  }
+  const record = asRecord(error);
+  const recordMessage = toNonEmptyString(record?.message) || toNonEmptyString(record?.error);
+  if (recordMessage) {
+    return recordMessage;
+  }
+  return fallback;
+}
+function normalizeError(error, fallback = "Unknown error.", maxCauseDepth = 2) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return normalizeErrorInternal(error, fallback, maxCauseDepth, seen);
+}
+function normalizeErrorInternal(error, fallback, depthRemaining, seen) {
+  const record = asRecord(error);
+  if (record) {
+    if (seen.has(record)) {
+      return {
+        message: extractErrorMessage(error, fallback)
+      };
+    }
+    seen.add(record);
+  }
+  const message = extractErrorMessage(error, fallback);
+  const code = extractCode(error);
+  const name = extractName(error);
+  const details = extractDetails(error);
+  if (depthRemaining <= 0) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const cause = extractCause(error);
+  if (!cause) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const normalizedCause = normalizeErrorInternal(
+    cause,
+    "Caused by an unknown error.",
+    depthRemaining - 1,
+    seen
+  );
+  return compactErrorInfo({
+    message,
+    ...code ? { code } : {},
+    ...name ? { name } : {},
+    ...details ? { details } : {},
+    cause: normalizedCause
+  });
+}
+function compactErrorInfo(info) {
+  const safeDetails = toJsonSafeRecord(info.details);
+  return {
+    message: info.message,
+    ...info.code ? { code: info.code } : {},
+    ...info.name ? { name: info.name } : {},
+    ...safeDetails ? { details: safeDetails } : {},
+    ...info.cause ? { cause: info.cause } : {}
+  };
+}
+function extractCode(error) {
+  const record = asRecord(error);
+  const raw = record?.code;
+  if (typeof raw === "string" && raw.trim()) {
+    return raw.trim();
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return String(raw);
+  }
+  return void 0;
+}
+function extractName(error) {
+  if (error instanceof Error && error.name.trim()) {
+    return error.name.trim();
+  }
+  const record = asRecord(error);
+  return toNonEmptyString(record?.name);
+}
+function extractDetails(error) {
+  const record = asRecord(error);
+  if (!record) return void 0;
+  const details = {};
+  const rawDetails = asRecord(record.details);
+  if (rawDetails) {
+    Object.assign(details, rawDetails);
+  }
+  const action = toNonEmptyString(record.action);
+  if (action) {
+    details.action = action;
+  }
+  const selectorUsed = toNonEmptyString(record.selectorUsed);
+  if (selectorUsed) {
+    details.selectorUsed = selectorUsed;
+  }
+  if (typeof record.status === "number" && Number.isFinite(record.status)) {
+    details.status = record.status;
+  }
+  const failure = asRecord(record.failure);
+  if (failure) {
+    const failureCode = toNonEmptyString(failure.code);
+    const classificationSource = toNonEmptyString(
+      failure.classificationSource
+    );
+    const failureDetails = asRecord(failure.details);
+    if (failureCode || classificationSource || failureDetails) {
+      details.actionFailure = {
+        ...failureCode ? { code: failureCode } : {},
+        ...classificationSource ? { classificationSource } : {},
+        ...failureDetails ? { details: failureDetails } : {}
+      };
+    }
+  }
+  return Object.keys(details).length ? details : void 0;
+}
+function extractCause(error) {
+  if (error instanceof Error) {
+    return error.cause;
+  }
+  const record = asRecord(error);
+  return record?.cause;
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function toNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function toJsonSafeRecord(value) {
+  if (!value) return void 0;
+  const sanitized = toJsonSafeValue(value, /* @__PURE__ */ new WeakSet());
+  if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+    return void 0;
+  }
+  const record = sanitized;
+  return Object.keys(record).length > 0 ? record : void 0;
+}
+function toJsonSafeValue(value, seen) {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return void 0;
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = value.map((item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Set) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = Array.from(value, (item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Map) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = {};
+    for (const [key, item] of value.entries()) {
+      const normalizedKey = String(key);
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[normalizedKey] = next;
+      }
+    }
+    seen.delete(value);
+    return output;
+  }
+  if (typeof value === "object") {
+    const objectValue = value;
+    if (seen.has(objectValue)) return "[Circular]";
+    seen.add(objectValue);
+    const output = {};
+    for (const [key, item] of Object.entries(objectValue)) {
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[key] = next;
+      }
+    }
+    seen.delete(objectValue);
+    return output;
+  }
+  return void 0;
+}
+
 // src/storage/namespace.ts
 import path from "path";
 var DEFAULT_NAMESPACE = "default";
@@ -607,9 +833,11 @@ import path2 from "path";
 var LocalSelectorStorage = class {
   rootDir;
   namespace;
-  constructor(rootDir, namespace) {
+  debug;
+  constructor(rootDir, namespace, options = {}) {
     this.rootDir = rootDir;
     this.namespace = normalizeNamespace(namespace);
+    this.debug = options.debug === true;
   }
   getRootDir() {
     return this.rootDir;
@@ -643,7 +871,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = fs.readFileSync(file, "utf8");
       return JSON.parse(raw);
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to parse selector registry JSON."
+      );
+      if (this.debug) {
+        console.warn(
+          `[opensteer] failed to read selector registry "${file}": ${message}`
+        );
+      }
       return createEmptyRegistry(this.namespace);
     }
   }
@@ -660,7 +897,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = fs.readFileSync(file, "utf8");
       return JSON.parse(raw);
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to parse selector file JSON."
+      );
+      if (this.debug) {
+        console.warn(
+          `[opensteer] failed to read selector file "${file}": ${message}`
+        );
+      }
       return null;
     }
   }
@@ -3906,7 +4152,7 @@ function defaultActionFailureMessage(action) {
 function classifyActionFailure(input) {
   const typed = classifyTypedError(input.error);
   if (typed) return typed;
-  const message = extractErrorMessage(input.error, input.fallbackMessage);
+  const message = extractErrorMessage2(input.error, input.fallbackMessage);
   const fromCallLog = classifyFromPlaywrightMessage(message, input.probe);
   if (fromCallLog) return fromCallLog;
   const fromProbe = classifyFromProbe(input.probe);
@@ -3915,7 +4161,7 @@ function classifyActionFailure(input) {
   if (fromHeuristic) return fromHeuristic;
   return buildFailure({
     code: "UNKNOWN",
-    message: ensureMessage(input.fallbackMessage, "Action failed."),
+    message: ensureMessage(message, input.fallbackMessage),
     classificationSource: "unknown"
   });
 }
@@ -4175,13 +4421,22 @@ function defaultRetryableForCode(code) {
       return true;
   }
 }
-function extractErrorMessage(error, fallbackMessage) {
+function extractErrorMessage2(error, fallbackMessage) {
   if (error instanceof Error && error.message.trim()) {
     return error.message;
   }
   if (typeof error === "string" && error.trim()) {
     return error.trim();
   }
+  if (error && typeof error === "object" && !Array.isArray(error)) {
+    const record = error;
+    if (typeof record.message === "string" && record.message.trim()) {
+      return record.message.trim();
+    }
+    if (typeof record.error === "string" && record.error.trim()) {
+      return record.error.trim();
+    }
+  }
   return ensureMessage(fallbackMessage, "Action failed.");
 }
 function ensureMessage(value, fallback) {
@@ -5140,7 +5395,8 @@ function withTokenQuery(wsUrl, token) {
 // src/cloud/local-cache-sync.ts
 import fs2 from "fs";
 import path3 from "path";
-function collectLocalSelectorCacheEntries(storage) {
+function collectLocalSelectorCacheEntries(storage, options = {}) {
+  const debug = options.debug === true;
   const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
   if (!fs2.existsSync(namespaceDir)) return [];
@@ -5149,7 +5405,7 @@ function collectLocalSelectorCacheEntries(storage) {
   for (const fileName of fileNames) {
     if (fileName === "index.json" || !fileName.endsWith(".json")) continue;
     const filePath = path3.join(namespaceDir, fileName);
-    const selector = readSelectorFile(filePath);
+    const selector = readSelectorFile(filePath, debug);
     if (!selector) continue;
     const descriptionHash = normalizeDescriptionHash(selector.id);
     const method = normalizeMethod(selector.method);
@@ -5174,11 +5430,20 @@ function collectLocalSelectorCacheEntries(storage) {
   }
   return dedupeNewest(entries);
 }
-function readSelectorFile(filePath) {
+function readSelectorFile(filePath, debug) {
   try {
     const raw = fs2.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
-  } catch {
+  } catch (error) {
+    const message = extractErrorMessage(
+      error,
+      "Unable to parse selector cache file JSON."
+    );
+    if (debug) {
+      console.warn(
+        `[opensteer] failed to read local selector cache file "${filePath}": ${message}`
+      );
+    }
     return null;
   }
 }
@@ -7824,11 +8089,12 @@ function dotenvFileOrder(nodeEnv) {
   files.push(".env");
   return files;
 }
-function loadDotenvValues(rootDir, baseEnv) {
+function loadDotenvValues(rootDir, baseEnv, options = {}) {
   const values = {};
   if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
     return values;
   }
+  const debug = options.debug ?? parseBool(baseEnv.OPENSTEER_DEBUG) === true;
   const baseDir = path4.resolve(rootDir);
   const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
   for (const filename of dotenvFileOrder(nodeEnv)) {
@@ -7842,15 +8108,24 @@ function loadDotenvValues(rootDir, baseEnv) {
           values[key] = value;
         }
       }
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to read or parse dotenv file."
+      );
+      if (debug) {
+        console.warn(
+          `[opensteer] failed to load dotenv file "${filePath}": ${message}`
+        );
+      }
       continue;
     }
   }
   return values;
 }
-function resolveEnv(rootDir) {
+function resolveEnv(rootDir, options = {}) {
   const baseEnv = process.env;
-  const dotenvValues = loadDotenvValues(rootDir, baseEnv);
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv, options);
   return {
     ...dotenvValues,
     ...baseEnv
@@ -7894,13 +8169,22 @@ function assertNoLegacyRuntimeConfig(source, config) {
     );
   }
 }
-function loadConfigFile(rootDir) {
+function loadConfigFile(rootDir, options = {}) {
   const configPath = path4.join(rootDir, ".opensteer", "config.json");
   if (!fs3.existsSync(configPath)) return {};
   try {
     const raw = fs3.readFileSync(configPath, "utf8");
     return JSON.parse(raw);
-  } catch {
+  } catch (error) {
+    const message = extractErrorMessage(
+      error,
+      "Unable to read or parse config file."
+    );
+    if (options.debug) {
+      console.warn(
+        `[opensteer] failed to load config file "${configPath}": ${message}`
+      );
+    }
     return {};
   }
 }
@@ -8032,6 +8316,8 @@ function resolveCloudSelection(config, env = process.env) {
   };
 }
 function resolveConfig(input = {}) {
+  const processEnv = process.env;
+  const debugHint = typeof input.debug === "boolean" ? input.debug : parseBool(processEnv.OPENSTEER_DEBUG) === true;
   const initialRootDir = input.storage?.rootDir ?? process.cwd();
   const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
     storage: {
@@ -8040,12 +8326,16 @@ function resolveConfig(input = {}) {
   });
   assertNoLegacyAiConfig("Opensteer constructor config", input);
   assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
-  const fileConfig = loadConfigFile(initialRootDir);
+  const fileConfig = loadConfigFile(initialRootDir, {
+    debug: debugHint
+  });
   assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
   assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
   const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
-  const env = resolveEnv(envRootDir);
+  const env = resolveEnv(envRootDir, {
+    debug: debugHint
+  });
   if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
       "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
@@ -9511,7 +9801,7 @@ function clonePersistedExtractNode(node) {
 }
 
 // src/cloud/runtime.ts
-var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
+var DEFAULT_CLOUD_BASE_URL = "https://api.opensteer.com";
 function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
   const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
   return {
@@ -9579,7 +9869,9 @@ var Opensteer = class _Opensteer {
     this.aiExtract = this.createLazyExtractCallback(model);
     const rootDir = resolved.storage?.rootDir || process.cwd();
     this.namespace = resolveNamespace(resolved, rootDir);
-    this.storage = new LocalSelectorStorage(rootDir, this.namespace);
+    this.storage = new LocalSelectorStorage(rootDir, this.namespace, {
+      debug: Boolean(resolved.debug)
+    });
     this.pool = new BrowserPool(resolved.browser || {});
     if (cloudSelection.cloud) {
       const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
@@ -9598,12 +9890,20 @@ var Opensteer = class _Opensteer {
       this.cloud = null;
     }
   }
+  logDebugError(context, error) {
+    if (!this.config.debug) return;
+    const normalized = normalizeError(error, "Unknown error.");
+    const codeSuffix = normalized.code && normalized.code.trim() ? ` [${normalized.code.trim()}]` : "";
+    console.warn(
+      `[opensteer] ${context}: ${normalized.message}${codeSuffix}`
+    );
+  }
   createLazyResolveCallback(model) {
     let resolverPromise = null;
     return async (...args) => {
       try {
         if (!resolverPromise) {
-          resolverPromise = import("./resolver-HVZJQZ32.js").then(
+          resolverPromise = import("./resolver-ZREUOOTV.js").then(
             (m) => m.createResolveCallback(model)
           );
         }
@@ -9620,7 +9920,7 @@ var Opensteer = class _Opensteer {
     const extract = async (args) => {
       try {
         if (!extractorPromise) {
-          extractorPromise = import("./extractor-I6TJPTXV.js").then(
+          extractorPromise = import("./extractor-CZFCFUME.js").then(
             (m) => m.createExtractCallback(model)
           );
         }
@@ -9688,7 +9988,8 @@ var Opensteer = class _Opensteer {
     let tabs;
     try {
       tabs = await this.invokeCloudAction("tabs", {});
-    } catch {
+    } catch (error) {
+      this.logDebugError("cloud page reference sync (tabs lookup) failed", error);
       return;
     }
     if (!tabs.length) {
@@ -9826,12 +10127,7 @@ var Opensteer = class _Opensteer {
         try {
           await this.syncLocalSelectorCacheToCloud();
         } catch (error) {
-          if (this.config.debug) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.warn(
-              `[opensteer] cloud selector cache sync failed: ${message}`
-            );
-          }
+          this.logDebugError("cloud selector cache sync failed", error);
         }
         localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
         this.cloud.localRunId = localRunId;
@@ -9863,7 +10159,12 @@ var Opensteer = class _Opensteer {
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session2.cloudSessionUrl;
-        await this.syncCloudPageRef().catch(() => void 0);
+        await this.syncCloudPageRef().catch((error) => {
+          this.logDebugError(
+            "cloud page reference sync after launch failed",
+            error
+          );
+        });
         this.announceCloudSession({
           sessionId: session2.sessionId,
           workspaceId: session2.cloudSession.workspaceId,
@@ -9950,7 +10251,9 @@ var Opensteer = class _Opensteer {
   }
   async syncLocalSelectorCacheToCloud() {
     if (!this.cloud) return;
-    const entries = collectLocalSelectorCacheEntries(this.storage);
+    const entries = collectLocalSelectorCacheEntries(this.storage, {
+      debug: Boolean(this.config.debug)
+    });
     if (!entries.length) return;
     await this.cloud.sessionClient.importSelectorCache({
       entries
@@ -9959,9 +10262,12 @@ var Opensteer = class _Opensteer {
   async goto(url, options) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("goto", { url, options });
-      await this.syncCloudPageRef({ expectedUrl: url }).catch(
-        () => void 0
-      );
+      await this.syncCloudPageRef({ expectedUrl: url }).catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after goto failed",
+          error
+        );
+      });
       return;
     }
     const { waitUntil = "domcontentloaded", ...rest } = options ?? {};
@@ -10473,7 +10779,12 @@ var Opensteer = class _Opensteer {
         }
       );
       await this.syncCloudPageRef({ expectedUrl: result.url }).catch(
-        () => void 0
+        (error) => {
+          this.logDebugError(
+            "cloud page reference sync after newTab failed",
+            error
+          );
+        }
       );
       return result;
     }
@@ -10485,7 +10796,12 @@ var Opensteer = class _Opensteer {
   async switchTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("switchTab", { index });
-      await this.syncCloudPageRef().catch(() => void 0);
+      await this.syncCloudPageRef().catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after switchTab failed",
+          error
+        );
+      });
       return;
     }
     const page = await switchTab(this.context, index);
@@ -10495,7 +10811,12 @@ var Opensteer = class _Opensteer {
   async closeTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("closeTab", { index });
-      await this.syncCloudPageRef().catch(() => void 0);
+      await this.syncCloudPageRef().catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after closeTab failed",
+          error
+        );
+      });
       return;
     }
     const newPage = await closeTab(this.context, this.page, index);
@@ -10669,8 +10990,12 @@ var Opensteer = class _Opensteer {
         }
         return await counterFn(handle);
       } catch (err) {
-        const message = err instanceof Error ? err.message : `${method} failed.`;
-        throw new Error(message);
+        if (err instanceof Error) {
+          throw err;
+        }
+        throw new Error(
+          `${method} failed. ${extractErrorMessage(err, "Unknown error.")}`
+        );
       } finally {
         await handle.dispose();
       }
@@ -10797,6 +11122,9 @@ var Opensteer = class _Opensteer {
     if (this.cloud) {
       return await this.invokeCloudAction("extract", options);
     }
+    if (options.schema !== void 0) {
+      assertValidExtractSchemaRoot(options.schema);
+    }
     const storageKey = this.resolveStorageKey(options.description);
     const schemaHash = options.schema ? computeSchemaHash(options.schema) : null;
     const stored = storageKey ? this.storage.readSelector(storageKey) : null;
@@ -10805,7 +11133,7 @@ var Opensteer = class _Opensteer {
       try {
         payload = normalizePersistedExtractPayload(stored.path);
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
+        const message = extractErrorMessage(err, "Unknown error.");
         const selectorFile = storageKey ? this.storage.getSelectorPath(storageKey) : "unknown selector file";
         throw new Error(
           `Cached extraction selector is invalid for the current schema at "${selectorFile}". Delete the cached selector and rerun extraction. ${message}`
@@ -10822,7 +11150,16 @@ var Opensteer = class _Opensteer {
       fields.push(...schemaFields);
     }
     if (!fields.length) {
-      const planResult = await this.parseAiExtractPlan(options);
+      let planResult;
+      try {
+        planResult = await this.parseAiExtractPlan(options);
+      } catch (error) {
+        const message = extractErrorMessage(error, "Unknown error.");
+        const contextMessage = options.schema ? "Schema extraction did not resolve deterministic field targets, so Opensteer attempted AI extraction planning." : "Opensteer attempted AI extraction planning.";
+        throw new Error(`${contextMessage} ${message}`, {
+          cause: error
+        });
+      }
       if (planResult.fields.length) {
         fields.push(...planResult.fields);
       } else if (planResult.data !== void 0) {
@@ -11484,12 +11821,6 @@ var Opensteer = class _Opensteer {
     };
   }
   async buildFieldTargetsFromSchema(schema) {
-    if (!schema || typeof schema !== "object") {
-      return [];
-    }
-    if (Array.isArray(schema)) {
-      return [];
-    }
     const fields = [];
     await this.collectFieldTargetsFromSchemaObject(
       schema,
@@ -11563,6 +11894,10 @@ var Opensteer = class _Opensteer {
             path: path5,
             attribute: normalized.attribute
           });
+        } else {
+          throw new Error(
+            `Extraction schema field "${fieldKey}" uses selector "${normalized.selector}", but no matching element path could be built from the current page snapshot.`
+          );
         }
         return;
       }
@@ -11913,13 +12248,28 @@ function countNonNullLeaves(value) {
 function isPrimitiveLike(value) {
   return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
+function assertValidExtractSchemaRoot(schema) {
+  if (!schema || typeof schema !== "object") {
+    throw new Error(
+      "Invalid extraction schema: expected a JSON object at the top level."
+    );
+  }
+  if (Array.isArray(schema)) {
+    throw new Error(
+      'Invalid extraction schema: top-level arrays are not supported. Wrap array fields in an object (for example {"items":[...]}).'
+    );
+  }
+}
 function parseAiExtractResponse(response) {
   if (typeof response === "string") {
     const trimmed = stripCodeFence(response);
     try {
       return JSON.parse(trimmed);
     } catch {
-      throw new Error("LLM extraction returned a non-JSON string.");
+      const preview = summarizeForError(trimmed);
+      throw new Error(
+        `LLM extraction returned a non-JSON response.${preview ? ` Preview: "${preview}"` : ""}`
+      );
     }
   }
   if (response && typeof response === "object") {
@@ -11944,6 +12294,12 @@ function stripCodeFence(input) {
   if (lastFence === -1) return withoutHeader.trim();
   return withoutHeader.slice(0, lastFence).trim();
 }
+function summarizeForError(input, maxLength = 180) {
+  const compact = input.replace(/\s+/g, " ").trim();
+  if (!compact) return "";
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, maxLength)}...`;
+}
 function getScrollDelta2(options) {
   const amount = typeof options.amount === "number" ? options.amount : 600;
   const absoluteAmount = Math.abs(amount);
@@ -11970,6 +12326,7 @@ function buildLocalRunId(namespace) {
 }
 
 export {
+  normalizeError,
   normalizeNamespace,
   resolveNamespaceDir,
   waitForVisualStability,