opensteer 0.4.13 → 0.4.14

package/dist/cli/server.cjs

@@ -108,6 +108,15 @@ function resolveProviderInfo(modelStr) {
       return info;
     }
   }
+  const slash = modelStr.indexOf("/");
+  if (slash > 0) {
+    const provider = modelStr.slice(0, slash).trim().toLowerCase();
+    if (provider) {
+      throw new Error(
+        `Unsupported model provider prefix "${provider}" in model "${modelStr}". Use one of: openai, anthropic, google, xai, groq.`
+      );
+    }
+  }
   return { pkg: "@ai-sdk/openai", providerFn: "openai" };
 }
 function stripProviderPrefix(modelStr) {
@@ -821,6 +830,232 @@ var import_path3 = __toESM(require("path"), 1);
 var import_url = require("url");
 var import_dotenv = require("dotenv");
 
+// 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
 var import_path2 = __toESM(require("path"), 1);
 var DEFAULT_NAMESPACE = "default";
@@ -884,11 +1119,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 = import_path3.default.resolve(rootDir);
   const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
   for (const filename of dotenvFileOrder(nodeEnv)) {
@@ -902,15 +1138,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
@@ -954,13 +1199,22 @@ function assertNoLegacyRuntimeConfig(source, config) {
     );
   }
 }
-function loadConfigFile(rootDir) {
+function loadConfigFile(rootDir, options = {}) {
   const configPath = import_path3.default.join(rootDir, ".opensteer", "config.json");
   if (!import_fs.default.existsSync(configPath)) return {};
   try {
     const raw = import_fs.default.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 {};
   }
 }
@@ -1092,6 +1346,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: {
@@ -1100,12 +1356,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."
@@ -1789,9 +2049,11 @@ function createEmptyRegistry(name) {
 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;
@@ -1825,7 +2087,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = import_fs2.default.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);
     }
   }
@@ -1842,7 +2113,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = import_fs2.default.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;
     }
   }
@@ -5092,7 +5372,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);
@@ -5101,7 +5381,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"
   });
 }
@@ -5361,13 +5641,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) {
@@ -7677,7 +7966,8 @@ function withTokenQuery(wsUrl, token) {
 // src/cloud/local-cache-sync.ts
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
-function collectLocalSelectorCacheEntries(storage) {
+function collectLocalSelectorCacheEntries(storage, options = {}) {
+  const debug = options.debug === true;
   const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
   if (!import_fs3.default.existsSync(namespaceDir)) return [];
@@ -7686,7 +7976,7 @@ function collectLocalSelectorCacheEntries(storage) {
   for (const fileName of fileNames) {
     if (fileName === "index.json" || !fileName.endsWith(".json")) continue;
     const filePath = import_path5.default.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);
@@ -7711,11 +8001,20 @@ function collectLocalSelectorCacheEntries(storage) {
   }
   return dedupeNewest(entries);
 }
-function readSelectorFile(filePath) {
+function readSelectorFile(filePath, debug) {
   try {
     const raw = import_fs3.default.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;
   }
 }
@@ -9923,7 +10222,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;
@@ -9942,6 +10243,14 @@ 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) => {
@@ -10032,7 +10341,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) {
@@ -10170,12 +10480,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;
@@ -10207,7 +10512,12 @@ var Opensteer = class _Opensteer {
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session3.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: session3.sessionId,
           workspaceId: session3.cloudSession.workspaceId,
@@ -10294,7 +10604,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
@@ -10303,9 +10615,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 ?? {};
@@ -10817,7 +11132,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;
     }
@@ -10829,7 +11149,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);
@@ -10839,7 +11164,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);
@@ -11013,8 +11343,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();
       }
@@ -11141,6 +11475,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;
@@ -11149,7 +11486,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}`
@@ -11166,7 +11503,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) {
@@ -11828,12 +12174,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,
@@ -11907,6 +12247,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;
       }
@@ -12257,13 +12601,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 = stripCodeFence2(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") {
@@ -12288,6 +12647,12 @@ function stripCodeFence2(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);
@@ -12627,7 +12992,16 @@ function enqueueRequest(request, socket) {
     void handleRequest(request, socket);
     return;
   }
-  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch(() => {
+  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch((error) => {
+    sendResponse(
+      socket,
+      buildErrorResponse(
+        request.id,
+        error,
+        "Unexpected server error while handling request.",
+        "CLI_INTERNAL_ERROR"
+      )
+    );
   });
 }
 async function handleRequest(request, socket) {
@@ -12636,7 +13010,11 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down.`
+      error: `Session '${session}' is shutting down.`,
+      errorInfo: {
+        message: `Session '${session}' is shutting down.`,
+        code: "SESSION_SHUTTING_DOWN"
+      }
     });
     return;
   }
@@ -12644,7 +13022,11 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down. Retry your command.`
+      error: `Session '${session}' is shutting down. Retry your command.`,
+      errorInfo: {
+        message: `Session '${session}' is shutting down. Retry your command.`,
+        code: "SESSION_SHUTTING_DOWN"
+      }
     });
     return;
   }
@@ -12660,7 +13042,16 @@ async function handleRequest(request, socket) {
         sendResponse(socket, {
           id,
           ok: false,
-          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`
+          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
+          errorInfo: {
+            message: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
+            code: "SESSION_NAMESPACE_MISMATCH",
+            details: {
+              session,
+              activeNamespace: selectorNamespace,
+              requestedNamespace: requestedName
+            }
+          }
         });
         return;
       }
@@ -12718,11 +13109,10 @@ async function handleRequest(request, socket) {
         }
       });
     } catch (err) {
-      sendResponse(socket, {
-        id,
-        ok: false,
-        error: err instanceof Error ? err.message : String(err)
-      });
+      sendResponse(
+        socket,
+        buildErrorResponse(id, err, "Failed to open browser session.")
+      );
     }
     return;
   }
@@ -12738,11 +13128,10 @@ async function handleRequest(request, socket) {
         result: { sessionClosed: true }
       });
     } catch (err) {
-      sendResponse(socket, {
-        id,
-        ok: false,
-        error: err instanceof Error ? err.message : String(err)
-      });
+      sendResponse(
+        socket,
+        buildErrorResponse(id, err, "Failed to close browser session.")
+      );
     }
     beginShutdown();
     return;
@@ -12755,7 +13144,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`
+      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+      errorInfo: {
+        message: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+        code: "SESSION_NOT_OPEN",
+        details: {
+          session
+        }
+      }
     });
     return;
   }
@@ -12764,7 +13160,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Unknown command: ${command}`
+      error: `Unknown command: ${command}`,
+      errorInfo: {
+        message: `Unknown command: ${command}`,
+        code: "UNKNOWN_COMMAND",
+        details: {
+          command
+        }
+      }
     });
     return;
   }
@@ -12772,11 +13175,12 @@ async function handleRequest(request, socket) {
     const result = await handler(instance, args);
     sendResponse(socket, { id, ok: true, result });
   } catch (err) {
-    sendResponse(socket, {
-      id,
-      ok: false,
-      error: err instanceof Error ? err.message : String(err)
-    });
+    sendResponse(
+      socket,
+      buildErrorResponse(id, err, `Command "${command}" failed.`, void 0, {
+        command
+      })
+    );
   }
 }
 if ((0, import_fs4.existsSync)(socketPath)) {
@@ -12797,7 +13201,11 @@ var server = (0, import_net.createServer)((socket) => {
         sendResponse(socket, {
           id: 0,
           ok: false,
-          error: "Invalid JSON request"
+          error: "Invalid JSON request",
+          errorInfo: {
+            message: "Invalid JSON request",
+            code: "INVALID_JSON_REQUEST"
+          }
         });
       }
     }
@@ -12836,3 +13244,25 @@ async function shutdown() {
 }
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);
+function buildErrorResponse(id, error, fallbackMessage, fallbackCode, details) {
+  const normalized = normalizeError(error, fallbackMessage);
+  let mergedDetails;
+  if (normalized.details || details) {
+    mergedDetails = {
+      ...normalized.details || {},
+      ...details || {}
+    };
+  }
+  return {
+    id,
+    ok: false,
+    error: normalized.message,
+    errorInfo: {
+      message: normalized.message,
+      ...normalized.code || fallbackCode ? { code: normalized.code || fallbackCode } : {},
+      ...normalized.name ? { name: normalized.name } : {},
+      ...mergedDetails ? { details: mergedDetails } : {},
+      ...normalized.cause ? { cause: normalized.cause } : {}
+    }
+  };
+}