opensteer 0.9.4 → 0.9.6

package/dist/cli/bin.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import '../chunk-KCINASQC.js';
-import { runLocalViewService } from '../chunk-ZRF7WMS3.js';
-import { createOpensteerSemanticRuntime, dispatchSemanticOperation, loadEnvironment, normalizeOpensteerProviderMode, resolveOpensteerRuntimeConfig, assertProviderSupportsEngine, resolveOpensteerProvider, requireCloudAppBaseUrl, CloudSessionProxy, FlowRecorderCollector, generateReplayScript, OpensteerCloudClient } from '../chunk-GEUHKPC2.js';
-import { OpensteerBrowserManager, stopLocalViewService, setLocalViewMode, ensureLocalViewServiceRunning, buildLocalViewSessionUrl, resolveOpensteerEngineName, resolveFilesystemWorkspacePath } from '../chunk-GSCQQKZZ.js';
+import { runLocalViewService } from '../chunk-3I3A5OLB.js';
+import { createOpensteerSemanticRuntime, dispatchSemanticOperation, isBrowserCoreError, loadEnvironment, normalizeOpensteerProviderMode, resolveOpensteerRuntimeConfig, assertProviderSupportsEngine, resolveOpensteerProvider, requireCloudAppBaseUrl, CloudSessionProxy, FlowRecorderCollector, generateReplayScript, OpensteerCloudClient } from '../chunk-BVRIPCWA.js';
+import { isOpensteerProtocolError, OpensteerBrowserManager, stopLocalViewService, setLocalViewMode, ensureLocalViewServiceRunning, buildLocalViewSessionUrl, resolveOpensteerEngineName, resolveFilesystemWorkspacePath } from '../chunk-3XBQRZZC.js';
 import { discoverLocalCdpBrowsers, inspectCdpEndpoint, readPersistedLocalBrowserSessionRecord, isProcessRunning, buildLocalViewSessionId, pathExists, readPersistedCloudSessionRecord } from '../chunk-T5P2QGZ3.js';
 import process4 from 'process';
 import { mkdir, writeFile } from 'fs/promises';
@@ -15,13 +14,115 @@ import { fileURLToPath } from 'url';
 
 // package.json
 var package_default = {
-  version: "0.9.4"};
+  version: "0.9.6"};
 
 // src/cli/env-loader.ts
 async function loadCliEnvironment(cwd) {
   loadEnvironment(cwd);
 }
 
+// src/cli/errors.ts
+var CliError = class extends Error {
+  type;
+  usage;
+  constructor(type, message, usage) {
+    super(message);
+    this.name = "CliError";
+    this.type = type;
+    this.usage = usage;
+  }
+  format() {
+    return this.usage === void 0 ? this.message : `${this.message}
+Usage: ${this.usage}`;
+  }
+};
+function isCliError(value) {
+  return value instanceof CliError;
+}
+function formatCliErrorOutput(error) {
+  if (isCliError(error)) {
+    return {
+      success: false,
+      error: error.format(),
+      type: error.type
+    };
+  }
+  if (isOpensteerProtocolError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (isBrowserCoreError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (error instanceof Error && "opensteerError" in error) {
+    const oe = error.opensteerError;
+    return {
+      success: false,
+      error: oe.message,
+      code: oe.code,
+      retriable: oe.retriable
+    };
+  }
+  if (error instanceof SyntaxError) {
+    return {
+      success: false,
+      error: error.message,
+      type: "invalid_value"
+    };
+  }
+  return {
+    success: false,
+    error: error instanceof Error ? error.message : String(error)
+  };
+}
+function emitWarning(warning) {
+  process.stderr.write(`${JSON.stringify({ warning })}
+`);
+}
+var CLI_USAGE_HINTS = {
+  "session.open": "opensteer open <url> [--workspace <id>]",
+  "page.goto": "opensteer goto <url>",
+  "page.evaluate": "opensteer evaluate <script>",
+  "page.add-init-script": "opensteer init-script <script>",
+  "dom.click": "opensteer click <element> --persist <key>",
+  "dom.hover": "opensteer hover <element> --persist <key>",
+  "dom.input": "opensteer input <element> <text> --persist <key>",
+  "dom.scroll": "opensteer scroll <direction> <amount> --persist <key>",
+  "dom.extract": "opensteer extract <template> --persist <key>",
+  "network.detail": "opensteer network detail <recordId>",
+  "session.fetch": "opensteer fetch <url>",
+  "captcha.solve": "opensteer captcha solve --provider <name> --api-key <key>",
+  "scripts.capture": "opensteer scripts capture",
+  "scripts.beautify": "opensteer scripts beautify <artifactId>",
+  "scripts.deobfuscate": "opensteer scripts deobfuscate <artifactId>",
+  "scripts.sandbox": "opensteer scripts sandbox <artifactId>",
+  "interaction.capture": "opensteer interaction capture",
+  "interaction.get": "opensteer interaction get <traceId>",
+  "interaction.replay": "opensteer interaction replay <traceId>",
+  "interaction.diff": "opensteer interaction diff <leftTraceId> <rightTraceId>",
+  "artifact.read": "opensteer artifact read <artifactId>",
+  "computer.click": "opensteer computer click <x> <y>",
+  "computer.type": "opensteer computer type <text>",
+  "computer.key": "opensteer computer key <key>",
+  "computer.scroll": "opensteer computer scroll <x> <y> --dx <n> --dy <n>",
+  "computer.move": "opensteer computer move <x> <y>",
+  "computer.drag": "opensteer computer drag <x1> <y1> <x2> <y2>",
+  "computer.screenshot": "opensteer computer screenshot",
+  exec: "opensteer exec <expression>",
+  record: "opensteer record --url <url> --workspace <id>",
+  "browser.inspect": "opensteer browser inspect <endpoint>",
+  "browser.clone": "opensteer browser clone --source-user-data-dir <path>"
+};
+
 // src/cli/help.ts
 function getHelpText() {
   return `Opensteer CLI
@@ -40,11 +141,11 @@ Navigation:
 
 DOM:
   snapshot [action|extraction]
-  click <element> [--button left|middle|right] [--persist <key>] [--capture-network <label>]
-  hover <element> [--persist <key>] [--capture-network <label>]
-  input <element> <text> [--press-enter] [--persist <key>] [--capture-network <label>]
-  scroll <direction> <amount> [--element <n>] [--persist <key>] [--capture-network <label>]
-  extract <schema> [--persist <key>]
+  click <element> --persist <key> [--button left|middle|right] [--capture-network <label>]
+  hover <element> --persist <key> [--capture-network <label>]
+  input <element> <text> --persist <key> [--press-enter] [--capture-network <label>]
+  scroll <direction> <amount> --persist <key> [--element <n>] [--capture-network <label>]
+  extract <template> --persist <key>
   evaluate <script>
   init-script <script>
 
@@ -280,7 +381,7 @@ function parseCommandLine(argv) {
     const key = token.slice(2, separator === -1 ? void 0 : separator);
     const spec = CLI_OPTION_SPECS[key];
     if (spec === void 0) {
-      throw new Error(`Unknown option: --${key}.`);
+      throw new CliError("unknown_option", `Unknown option: --${key}.`);
     }
     if (separator !== -1) {
       rawOptions.set(key, [...rawOptions.get(key) ?? [], token.slice(separator + 1)]);
@@ -309,7 +410,8 @@ function parseCommandLine(argv) {
       continue;
     }
     if (next === void 0 || next.startsWith("--")) {
-      throw new Error(
+      throw new CliError(
+        "missing_arguments",
         `Option "--${key}" requires a value.${next?.startsWith("--") === true ? ` Use "--${key}=<value>" when the value begins with "--".` : ``}`
       );
     }
@@ -355,10 +457,14 @@ function parseCommandLine(argv) {
   const autoLocalView = readOptionalBoolean(rawOptions, "auto");
   const noAutoLocalView = readOptionalBoolean(rawOptions, "no-auto");
   if (autoLocalView === true && noAutoLocalView === true) {
-    throw new Error('Options "--auto" and "--no-auto" cannot be combined.');
+    throw new CliError("invalid_option", 'Options "--auto" and "--no-auto" cannot be combined.');
   }
   if (command[0] !== "view" && (autoLocalView !== void 0 || noAutoLocalView !== void 0)) {
-    throw new Error('Options "--auto" and "--no-auto" are only supported with "view".');
+    throw new CliError(
+      "invalid_option",
+      'Options "--auto" and "--no-auto" are only supported with "view".',
+      "opensteer view --auto"
+    );
   }
   const global = readOptionalBoolean(rawOptions, "global");
   const yes = readOptionalBoolean(rawOptions, "yes");
@@ -414,7 +520,7 @@ function parseKeyValueList(values) {
     values.map((entry) => {
       const separator = entry.indexOf("=");
       if (separator <= 0) {
-        throw new Error(`Expected NAME=VALUE, received "${entry}".`);
+        throw new CliError("invalid_value", `Expected NAME=VALUE, received "${entry}".`);
       }
       return [entry.slice(0, separator), entry.slice(separator + 1)];
     })
@@ -445,7 +551,7 @@ function readOptionalBoolean(options, name) {
   if (value === "false") {
     return false;
   }
-  throw new Error(`Option "--${name}" must be true or false.`);
+  throw new CliError("invalid_value", `Option "--${name}" must be true or false.`);
 }
 function readOptionalNumber(options, name) {
   const value = readSingle(options, name);
@@ -454,13 +560,20 @@ function readOptionalNumber(options, name) {
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(`Option "--${name}" must be a number.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a number.`);
   }
   return parsed;
 }
 function readJsonValue(options, name) {
   const value = readSingle(options, name);
-  return value === void 0 ? void 0 : JSON.parse(value);
+  if (value === void 0) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `Option "--${name}" contains invalid JSON.`);
+  }
 }
 function readJsonObject(options, name) {
   const parsed = readJsonValue(options, name);
@@ -468,7 +581,7 @@ function readJsonObject(options, name) {
     return void 0;
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON object.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON object.`);
   }
   return parsed;
 }
@@ -478,7 +591,7 @@ function readJsonArray(options, name) {
     return void 0;
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON array.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON array.`);
   }
   return parsed;
 }
@@ -498,7 +611,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.open": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("open requires a URL.");
+        throw new CliError("missing_arguments", "open requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       return {
         url,
@@ -531,7 +644,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "page.goto": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("goto requires a URL.");
+        throw new CliError("missing_arguments", "goto requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const captureNetwork = readSingle(parsed.rawOptions, "capture-network");
       return {
@@ -543,14 +656,14 @@ async function buildOperationInput(operation, parsed, runtime) {
       return parsed.rest[0] === void 0 ? {} : { mode: parsed.rest[0] };
     case "page.evaluate":
       if (parsed.rest[0] === void 0) {
-        throw new Error("evaluate requires a script.");
+        throw new CliError("missing_arguments", "evaluate requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
       };
     case "page.add-init-script":
       if (parsed.rest[0] === void 0) {
-        throw new Error("init-script requires a script.");
+        throw new CliError("missing_arguments", "init-script requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
@@ -566,7 +679,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       return buildElementTargetInput(parsed, "hover");
     case "dom.input": {
       if (parsed.rest[1] === void 0) {
-        throw new Error("input requires an element number and text.");
+        throw new CliError("missing_arguments", "input requires an element number and text.", CLI_USAGE_HINTS[operation]);
       }
       const pressEnter = readOptionalBoolean(parsed.rawOptions, "press-enter");
       return {
@@ -591,18 +704,18 @@ async function buildOperationInput(operation, parsed, runtime) {
         },
         direction,
         amount,
-        ...persist === void 0 ? {} : { persist },
+        persist,
         ...captureNetwork === void 0 ? {} : { captureNetwork }
       };
     }
     case "dom.extract": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("extract requires a schema.");
+        throw new CliError("missing_arguments", "extract requires a template.", CLI_USAGE_HINTS[operation]);
       }
-      const persist = readExtractPersistKey(parsed);
+      const persist = readPersistKey(parsed, "extract");
       return {
-        schema: parseRequiredJsonObjectArgument(joinRest(parsed.rest, 0), "extract schema"),
-        ...persist === void 0 ? {} : { persist }
+        persist,
+        template: parseRequiredJsonObjectArgument(joinRest(parsed.rest, 0), "extract template")
       };
     }
     case "network.query": {
@@ -633,7 +746,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "network.detail": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("network detail requires a record id.");
+        throw new CliError("missing_arguments", "network detail requires a record id.", CLI_USAGE_HINTS[operation]);
       }
       const probeFlag = readOptionalBoolean(parsed.rawOptions, "probe");
       return {
@@ -644,7 +757,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.fetch": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("fetch requires a URL.");
+        throw new CliError("missing_arguments", "fetch requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const bodyJson = readJsonValue(parsed.rawOptions, "body");
       const bodyText = readSingle(parsed.rawOptions, "body-text");
@@ -652,7 +765,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const query = parseKeyValueList(parsed.rawOptions.get("query"));
       const headers = parseKeyValueList(parsed.rawOptions.get("header"));
       if (bodyJson !== void 0 && bodyText !== void 0) {
-        throw new Error('Use either "--body" or "--body-text", not both.');
+        throw new CliError("invalid_option", 'Use either "--body" or "--body-text", not both.');
       }
       const transport = readSingle(parsed.rawOptions, "transport");
       const cookies = readOptionalBoolean(parsed.rawOptions, "cookies");
@@ -683,7 +796,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const siteKey = readSingle(parsed.rawOptions, "site-key");
       const pageUrl = readSingle(parsed.rawOptions, "page-url");
       if (provider === void 0 || apiKey === void 0) {
-        throw new Error('captcha solve requires "--provider" and "--api-key".');
+        throw new CliError("missing_arguments", 'captcha solve requires "--provider" and "--api-key".', CLI_USAGE_HINTS[operation]);
       }
       return {
         provider: readCaptchaProvider(provider),
@@ -713,7 +826,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "scripts.beautify":
     case "scripts.deobfuscate": {
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires an artifact id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires an artifact id.`, CLI_USAGE_HINTS[operation]);
       }
       const persist = readOptionalBoolean(parsed.rawOptions, "persist");
       return {
@@ -723,7 +836,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "scripts.sandbox":
       if (parsed.rest[0] === void 0) {
-        throw new Error("scripts sandbox requires an artifact id.");
+        throw new CliError("missing_arguments", "scripts sandbox requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       {
         const fidelity = readSingle(parsed.rawOptions, "fidelity");
@@ -772,14 +885,14 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "interaction.get":
     case "interaction.replay":
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires a trace id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires a trace id.`, CLI_USAGE_HINTS[operation]);
       }
       return {
         traceId: parsed.rest[0]
       };
     case "interaction.diff":
       if (parsed.rest[0] === void 0 || parsed.rest[1] === void 0) {
-        throw new Error("interaction diff requires two trace ids.");
+        throw new CliError("missing_arguments", "interaction diff requires two trace ids.", CLI_USAGE_HINTS[operation]);
       }
       return {
         leftTraceId: parsed.rest[0],
@@ -787,7 +900,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       };
     case "artifact.read":
       if (parsed.rest[0] === void 0) {
-        throw new Error("artifact read requires an artifact id.");
+        throw new CliError("missing_arguments", "artifact read requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       return {
         artifactId: parsed.rest[0]
@@ -795,7 +908,8 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.close":
       return {};
     default:
-      throw new Error(
+      throw new CliError(
+        "unsupported_operation",
         `${operation} does not have a direct CLI input shape. Use a supported command or the SDK.`
       );
   }
@@ -812,7 +926,7 @@ function buildElementTargetInput(parsed, verb) {
       kind: "element",
       element
     },
-    ...persist === void 0 ? {} : { persist },
+    persist,
     ...captureNetwork === void 0 ? {} : { captureNetwork }
   };
 }
@@ -842,7 +956,7 @@ function buildComputerExecuteInput(parsed) {
     }
     case "type":
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer type requires text.");
+        throw new CliError("missing_arguments", "computer type requires text.");
       }
       return {
         action: {
@@ -853,7 +967,7 @@ function buildComputerExecuteInput(parsed) {
       };
     case "key": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer key requires a key.");
+        throw new CliError("missing_arguments", "computer key requires a key.");
       }
       const modifiers = readKeyModifiers(readSingle(parsed.rawOptions, "modifiers"));
       return {
@@ -869,7 +983,7 @@ function buildComputerExecuteInput(parsed) {
       const dx = readOptionalNumber(parsed.rawOptions, "dx");
       const dy = readOptionalNumber(parsed.rawOptions, "dy");
       if (dx === void 0 || dy === void 0) {
-        throw new Error('computer scroll requires "--dx" and "--dy".');
+        throw new CliError("missing_arguments", 'computer scroll requires "--dx" and "--dy".');
       }
       return {
         action: {
@@ -924,49 +1038,50 @@ function buildComputerExecuteInput(parsed) {
         }
       };
     default:
-      throw new Error(`Unknown computer command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown computer command: ${parsed.command.join(" ")}`);
   }
 }
 async function resolvePageRefByIndex(runtime, index) {
   const pages = (await runtime.listPages({})).pages;
   const page = pages[index - 1];
   if (page === void 0) {
-    throw new Error(`tab ${String(index)} does not exist.`);
+    throw new CliError("invalid_value", `tab ${String(index)} does not exist.`);
   }
   return page.pageRef;
 }
 function readRequiredPositiveInteger(value, message) {
   const parsed = readRequiredNumber(value, message);
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readRequiredNumber(value, message) {
   if (value === void 0) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readSingleDirection(value) {
   if (value === void 0 || !SCROLL_DIRECTIONS.has(value)) {
-    throw new Error("scroll requires a direction: up, down, left, or right.");
+    throw new CliError("missing_arguments", "scroll requires a direction: up, down, left, or right.");
   }
   return value;
 }
 function readClickButton(value) {
   if (value === void 0 || !CLICK_BUTTONS.has(value)) {
-    throw new Error('Expected "--button" to be one of: left, middle, right.');
+    throw new CliError("invalid_value", 'Expected "--button" to be one of: left, middle, right.');
   }
   return value;
 }
 function readFetchTransport(value) {
   if (value === void 0 || !FETCH_TRANSPORTS.has(value)) {
-    throw new Error(
+    throw new CliError(
+      "invalid_value",
       'Expected "--transport" to be one of: auto, direct, matched-tls, context, page.'
     );
   }
@@ -974,31 +1089,31 @@ function readFetchTransport(value) {
 }
 function readCaptchaProvider(value) {
   if (value === void 0 || !CAPTCHA_PROVIDERS.has(value)) {
-    throw new Error('Expected "--provider" to be one of: 2captcha, capsolver.');
+    throw new CliError("invalid_value", 'Expected "--provider" to be one of: 2captcha, capsolver.');
   }
   return value;
 }
 function readCaptchaType(value) {
   if (value === void 0 || !CAPTCHA_TYPES.has(value)) {
-    throw new Error('Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
+    throw new CliError("invalid_value", 'Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
   }
   return value;
 }
 function readSandboxFidelity(value) {
   if (value === void 0 || !SANDBOX_FIDELITIES.has(value)) {
-    throw new Error('Expected "--fidelity" to be one of: minimal, standard, full.');
+    throw new CliError("invalid_value", 'Expected "--fidelity" to be one of: minimal, standard, full.');
   }
   return value;
 }
 function readSandboxClockMode(value) {
   if (value === void 0 || !SANDBOX_CLOCK_MODES.has(value)) {
-    throw new Error('Expected "--clock" to be one of: real, manual.');
+    throw new CliError("invalid_value", 'Expected "--clock" to be one of: real, manual.');
   }
   return value;
 }
 function readScreenshotFormat(value) {
   if (value === void 0 || !SCREENSHOT_FORMATS.has(value)) {
-    throw new Error('Expected "--format" to be one of: png, jpeg, webp.');
+    throw new CliError("invalid_value", 'Expected "--format" to be one of: png, jpeg, webp.');
   }
   return value;
 }
@@ -1009,7 +1124,7 @@ function readKeyModifiers(value) {
   }
   for (const modifier of modifiers) {
     if (!KEY_MODIFIERS.has(modifier)) {
-      throw new Error('Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
+      throw new CliError("invalid_value", 'Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
     }
   }
   return [...new Set(modifiers)];
@@ -1017,30 +1132,22 @@ function readKeyModifiers(value) {
 function readPersistKey(parsed, verb) {
   const value = readSingle(parsed.rawOptions, "persist");
   if (value === void 0) {
-    return void 0;
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   if (value === "true" || value === "false") {
-    throw new Error(`${verb} requires "--persist <key>" when using --persist.`);
-  }
-  if (verb === "scroll" && readOptionalNumber(parsed.rawOptions, "element") === void 0) {
-    throw new Error('scroll requires "--element <n>" when using "--persist <key>".');
-  }
-  return value;
-}
-function readExtractPersistKey(parsed) {
-  const value = readSingle(parsed.rawOptions, "persist");
-  if (value === void 0) {
-    return void 0;
-  }
-  if (value === "true" || value === "false") {
-    throw new Error('extract requires "--persist <key>" when using --persist.');
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   return value;
 }
 function parseRequiredJsonObjectArgument(value, label) {
-  const parsed = JSON.parse(value);
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `${label} contains invalid JSON.`);
+  }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${label} must be a JSON object.`);
+    throw new CliError("invalid_value", `${label} must be a JSON object.`);
   }
   return parsed;
 }
@@ -2196,7 +2303,7 @@ async function handleViewCommand(parsed, options = {}) {
     return;
   }
   if (subcommand !== void 0) {
-    throw new Error(`Unknown view command: view ${subcommand}`);
+    throw new CliError("unknown_command", `Unknown view command: view ${subcommand}`);
   }
   if (parsed.options.localViewMode !== void 0) {
     const preference = await setLocalViewMode(parsed.options.localViewMode);
@@ -2244,7 +2351,10 @@ async function resolveWorkspaceSessionId(input) {
 }
 function assertNoViewPreferenceFlag(parsed) {
   if (parsed.options.localViewMode !== void 0) {
-    throw new Error("View preference flags cannot be combined with this subcommand.");
+    throw new CliError(
+      "invalid_option",
+      "View preference flags cannot be combined with this subcommand."
+    );
   }
 }
 function writeViewOutput(parsed, value) {
@@ -2329,10 +2439,10 @@ async function main() {
   }
   const operation = resolveOperation(parsed.command);
   if (!operation) {
-    throw new Error(`Unknown command: ${parsed.command.join(" ")}`);
+    throw new CliError("unknown_command", `Unknown command: ${parsed.command.join(" ")}`);
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error('Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const { engineName, provider, runtimeProvider } = resolveCliRuntimeSelection(parsed);
   if (operation === "session.close") {
@@ -2354,28 +2464,43 @@ async function main() {
   let renderOperation = operation;
   try {
     const input = await buildOperationInput(operation, parsed, runtime);
-    result = await dispatchSemanticOperation(runtime, operation, input);
+    const rawResult = await dispatchSemanticOperation(runtime, operation, input);
     if (parsed.command[0] === "tab" && operation !== "page.list") {
       renderOperation = "page.list";
       result = await runtime.listPages({});
+    } else {
+      result = rawResult;
+    }
+    let warning;
+    if (result !== null && typeof result === "object" && "warning" in result) {
+      const { warning: w, ...rest } = result;
+      if (typeof w === "string") {
+        warning = w;
+        result = rest;
+      }
     }
     process4.stdout.write(renderOperationOutput(renderOperation, result, input));
+    if (warning !== void 0) {
+      emitWarning(warning);
+    }
   } finally {
     await runtime.disconnect().catch(() => void 0);
   }
 }
 async function handleExecCommand(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const expression = parsed.rest.join(" ");
   if (!expression) {
-    throw new Error(
-      `exec requires an expression. Example: exec "await this.evaluate('document.title')"`
+    throw new CliError(
+      "missing_arguments",
+      "exec requires an expression.",
+      "opensteer exec <expression>"
     );
   }
   const { engineName, runtimeProvider } = resolveCliRuntimeSelection(parsed);
-  const { Opensteer } = await import('../opensteer-PJI7VUIT.js');
+  const { Opensteer } = await import('../opensteer-UGA6YBRN.js');
   const opensteer = new Opensteer({
     workspace: parsed.options.workspace,
     rootDir: process4.cwd(),
@@ -2407,8 +2532,10 @@ async function handleBrowserCommand(parsed) {
   if (subcommand === "inspect") {
     const endpoint = parsed.options.attachEndpoint ?? parsed.rest[0];
     if (!endpoint) {
-      throw new Error(
-        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.'
+      throw new CliError(
+        "missing_arguments",
+        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.',
+        "opensteer browser inspect <endpoint>"
       );
     }
     const result = await inspectCdpEndpoint({
@@ -2421,7 +2548,8 @@ async function handleBrowserCommand(parsed) {
     return;
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error(
+    throw new CliError(
+      "missing_workspace",
       'Browser workspace commands require "--workspace <id>" or OPENSTEER_WORKSPACE.'
     );
   }
@@ -2444,7 +2572,11 @@ async function handleBrowserCommand(parsed) {
     case "clone": {
       const sourceUserDataDir = parsed.options.sourceUserDataDir;
       if (!sourceUserDataDir) {
-        throw new Error('browser clone requires "--source-user-data-dir <path>".');
+        throw new CliError(
+          "missing_arguments",
+          'browser clone requires "--source-user-data-dir <path>".',
+          "opensteer browser clone --source-user-data-dir <path>"
+        );
       }
       const result = await manager.clonePersistentBrowser({
         sourceUserDataDir,
@@ -2467,7 +2599,7 @@ async function handleBrowserCommand(parsed) {
       return;
     }
     default:
-      throw new Error(`Unknown browser command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown browser command: ${parsed.command.join(" ")}`);
   }
 }
 async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvider) {
@@ -2500,23 +2632,27 @@ async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvi
 }
 async function handleRecordCommandEntry(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const url = parsed.options.url ?? parsed.rest[0];
   if (url === void 0) {
-    throw new Error('record requires "--url <value>" or a positional URL.');
+    throw new CliError(
+      "missing_arguments",
+      'record requires "--url <value>" or a positional URL.',
+      "opensteer record --url <url> --workspace <id>"
+    );
   }
   const provider = resolveCliProvider(parsed);
   assertCloudCliOptionsMatchProvider(parsed, provider.mode);
   const engineName = resolveCliEngineName(parsed);
   if (engineName !== "playwright") {
-    throw new Error("record requires engine=playwright.");
+    throw new CliError("config_conflict", "record requires engine=playwright.");
   }
   const rootDir = process4.cwd();
   const recordBrowser = parsed.options.browser;
   if (provider.mode === "cloud") {
     if (typeof recordBrowser === "object") {
-      throw new Error('record does not support browser.mode="attach".');
+      throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
     }
     const runtimeProvider = buildCliRuntimeProvider(parsed, provider.mode);
     const runtimeConfig = resolveOpensteerRuntimeConfig({
@@ -2536,10 +2672,10 @@ async function handleRecordCommandEntry(parsed) {
     return;
   }
   if (parsed.options.launch?.headless === true) {
-    throw new Error('record requires a headed browser. Remove "--headless true".');
+    throw new CliError("config_conflict", 'record requires a headed browser. Remove "--headless true".');
   }
   if (typeof recordBrowser === "object") {
-    throw new Error('record does not support browser.mode="attach".');
+    throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
   }
   const launch = {
     ...parsed.options.launch ?? {},
@@ -2608,7 +2744,7 @@ function resolveCliBootstrapAction(argv) {
 }
 function buildCliBrowserProfile(parsed) {
   if (parsed.options.cloudProfileReuseIfActive === true && parsed.options.cloudProfileId === void 0) {
-    throw new Error('"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
+    throw new CliError("invalid_option", '"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
   }
   return parsed.options.cloudProfileId === void 0 ? void 0 : {
     profileId: parsed.options.cloudProfileId,
@@ -2669,7 +2805,8 @@ function buildCliRuntimeProvider(parsed, providerMode) {
 }
 function assertCloudCliOptionsMatchProvider(parsed, providerMode) {
   if (providerMode !== "cloud" && (parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudAppBaseUrl !== void 0 || parsed.options.cloudProfileId !== void 0 || parsed.options.cloudProfileReuseIfActive === true)) {
-    throw new Error(
+    throw new CliError(
+      "config_conflict",
       'Cloud-specific options require provider=cloud. Set "--provider cloud" or OPENSTEER_PROVIDER=cloud.'
     );
   }
@@ -2703,17 +2840,7 @@ function printVersion() {
 `);
 }
 main().catch((error) => {
-  const payload = error instanceof Error ? {
-    error: {
-      name: error.name,
-      message: error.message
-    }
-  } : {
-    error: {
-      name: "Error",
-      message: String(error)
-    }
-  };
+  const payload = formatCliErrorOutput(error);
   process4.stderr.write(`${JSON.stringify(payload)}
 `);
   process4.exitCode = 1;