@browserbasehq/browse-cli 0.4.1 → 0.4.2-alpha-2df4b01

package/README.md

@@ -173,22 +173,23 @@ browse env
 # Switch current session to Browserbase (restarts daemon if needed)
 browse env remote
 
-# Switch back to local Chrome (auto-discovers existing Chrome, falls back to isolated)
+# Switch back to local Chrome (clean isolated browser by default)
 browse env local
 ```
 
 #### Local Browser Strategies
 
-By default, `browse env local` auto-discovers an already-running Chrome with remote
-debugging enabled. This lets agents use your existing cookies, logins, and browser state.
-If no debuggable Chrome is found, it falls back to launching an isolated browser.
+By default, `browse env local` launches a clean isolated local browser.
+Use `browse env local --auto-connect` to opt into reusing an already-running
+Chrome with remote debugging enabled. If no debuggable Chrome is found, it
+falls back to launching an isolated browser.
 
 ```bash
-# Auto-discover local Chrome, fallback to isolated (default)
+# Use a clean isolated browser (default)
 browse env local
 
-# Force a clean isolated browser (no auto-discovery)
-browse env local --isolated
+# Auto-discover local Chrome, fallback to isolated
+browse env local --auto-connect
 
 # Attach to a specific CDP target (port or URL)
 browse env local 9222
@@ -210,7 +211,7 @@ Use `browse status` to see which strategy was resolved:
 
 ```bash
 browse status
-# {"running":true,"session":"default","mode":"local","localStrategy":"auto","localSource":"attached-existing","resolvedCdpUrl":"ws://..."}
+# {"running":true,"session":"default","mode":"local","localStrategy":"isolated","localSource":"isolated"}
 ```
 
 #### General Behavior
@@ -283,19 +284,19 @@ browse --session personal open https://twitter.com
 
 ## Direct CDP Connection
 
-Connect to an existing Chrome instance:
+Opt into using an existing Chrome instance:
 
 To make your Chrome discoverable:
 
 1. Open `chrome://inspect/#remote-debugging`
 2. Check the box **"Allow remote debugging for this browser instance"**
-3. Re-run the CLI and it will auto-connect!
+3. Re-run the CLI with auto-connect enabled.
 
 For more information, see the [Chrome DevTools docs](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session).
 
 ```bash
 # Auto-discover Chrome with remote debugging enabled
-browse env local
+browse env local --auto-connect
 browse open https://example.com
 
 # Or target a specific port / WebSocket URL

package/dist/index.js

@@ -119791,10 +119791,13 @@ var AISdkClient2 = class extends LLMClient {
   type = "aisdk";
   model;
   logger;
-  constructor({ model, logger }) {
+  constructor({ model, logger, clientOptions }) {
     super(model.modelId);
     this.model = model;
     this.logger = logger;
+    if (clientOptions) {
+      this.clientOptions = clientOptions;
+    }
   }
   getLanguageModel() {
     return this.model;
@@ -119872,9 +119875,11 @@ var AISdkClient2 = class extends LLMClient {
     let objectResponse;
     const isGPT5 = this.model.modelId.includes("gpt-5");
     const isCodex = this.model.modelId.includes("codex");
-    const usesLowReasoningEffort = (this.model.modelId.includes("gpt-5.1") || this.model.modelId.includes("gpt-5.2")) && !isCodex;
     const isKimi = this.model.modelId.includes("kimi");
     const temperature = isKimi ? 1 : options.temperature;
+    const isGPT5SubModel = this.model.modelId.includes("gpt-5.") && !isCodex;
+    const userReasoningEffort = this.clientOptions?.reasoningEffort;
+    const resolvedReasoningEffort = userReasoningEffort ?? (isGPT5SubModel ? "none" : void 0);
     const PROMPT_JSON_FALLBACK_PATTERNS = ["deepseek", "kimi", "glm"];
     const needsPromptJsonFallback = PROMPT_JSON_FALLBACK_PATTERNS.some((p2) => this.model.modelId.includes(p2));
     if (options.response_model) {
@@ -119903,11 +119908,10 @@ You must respond in JSON format. respond WITH JSON. Do not include any other tex
           messages: formattedMessages,
           schema: options.response_model.schema,
           temperature,
-          providerOptions: isGPT5 ? {
+          providerOptions: resolvedReasoningEffort ? {
             openai: {
-              textVerbosity: isCodex ? "medium" : "low",
-              // codex models only support 'medium'
-              reasoningEffort: isCodex ? "medium" : usesLowReasoningEffort ? "low" : "minimal"
+              ...isGPT5 ? { textVerbosity: isCodex ? "medium" : "low" } : {},
+              reasoningEffort: resolvedReasoningEffort
             }
           } : void 0
         });
@@ -152796,27 +152800,34 @@ var modelToProviderMap = {
   "gemini-2.5-flash-preview-04-17": "google",
   "gemini-2.5-pro-preview-03-25": "google"
 };
-function getAISDKLanguageModel(subProvider, subModelName, clientOptions) {
+function getAISDKLanguageModel(subProvider, subModelName, clientOptions, middleware) {
   const hasValidOptions = clientOptions && Object.values(clientOptions).some((v2) => v2 !== void 0 && v2 !== null);
+  let model;
   if (hasValidOptions) {
     const creator = AISDKProvidersWithAPIKey[subProvider];
     if (!creator) {
       throw new UnsupportedAISDKModelProviderError(subProvider, Object.keys(AISDKProvidersWithAPIKey));
     }
     const provider = creator(clientOptions);
-    return provider(subModelName);
+    model = provider(subModelName);
   } else {
     const provider = AISDKProviders[subProvider];
     if (!provider) {
       throw new UnsupportedAISDKModelProviderError(subProvider, Object.keys(AISDKProviders));
     }
-    return provider(subModelName);
+    model = provider(subModelName);
+  }
+  if (middleware) {
+    return wrapLanguageModel({ model, middleware });
   }
+  return model;
 }
 var LLMProvider = class {
   logger;
-  constructor(logger) {
+  middleware;
+  constructor(logger, middleware) {
     this.logger = logger;
+    this.middleware = middleware;
   }
   getClient(modelName, clientOptions, options) {
     if (modelName.includes("/")) {
@@ -152826,10 +152837,12 @@ var LLMProvider = class {
       if (subProvider === "vertex" && !options?.disableAPI && !options?.experimental) {
         throw new ExperimentalNotConfiguredError("Vertex provider");
       }
-      const languageModel = getAISDKLanguageModel(subProvider, subModelName, clientOptions);
+      const effectiveMiddleware = options?.middleware ?? this.middleware;
+      const languageModel = getAISDKLanguageModel(subProvider, subModelName, clientOptions, effectiveMiddleware);
       return new AISdkClient2({
         model: languageModel,
-        logger: this.logger
+        logger: this.logger,
+        clientOptions
       });
     }
     const provider = modelToProviderMap[modelName];
@@ -162834,13 +162847,14 @@ function resolveModelConfiguration(model) {
     return { modelName: model };
   }
   if (model && typeof model === "object") {
-    const { modelName, ...clientOptions } = model;
+    const { modelName, middleware, ...clientOptions } = model;
     if (!modelName) {
       throw new StagehandInvalidArgumentError("model.modelName is required when providing client options.");
     }
     return {
       modelName,
-      clientOptions
+      clientOptions,
+      middleware
     };
   }
   return { modelName: DEFAULT_MODEL_NAME };
@@ -163015,11 +163029,11 @@ var V3 = (() => {
         }
       } catch {
       }
-      const { modelName, clientOptions } = resolveModelConfiguration(opts.model);
+      const { modelName, clientOptions, middleware } = resolveModelConfiguration(opts.model);
       this.modelName = modelName;
       this.experimental = opts.experimental ?? false;
       this.logInferenceToFile = opts.logInferenceToFile ?? false;
-      this.llmProvider = new LLMProvider(this.logger);
+      this.llmProvider = new LLMProvider(this.logger, middleware);
       this.domSettleTimeoutMs = opts.domSettleTimeout;
       this.disableAPI = opts.disableAPI ?? false;
       const baseClientOptions = clientOptions ? { ...clientOptions } : {};
@@ -163101,14 +163115,16 @@ var V3 = (() => {
       }
       let modelName;
       let clientOptions;
+      let perCallMiddleware;
       if (typeof model === "string") {
         modelName = model;
       } else {
-        const { modelName: overrideModelName, ...rest } = model;
+        const { modelName: overrideModelName, middleware, ...rest } = model;
         modelName = overrideModelName;
         clientOptions = rest;
+        perCallMiddleware = middleware;
       }
-      if (modelName === this.modelName && (!clientOptions || Object.keys(clientOptions).length === 0)) {
+      if (modelName === this.modelName && !perCallMiddleware && (!clientOptions || Object.keys(clientOptions).length === 0)) {
         return this.llmClient;
       }
       const overrideProvider = String(modelName).split("/")[0];
@@ -163124,6 +163140,13 @@ var V3 = (() => {
           mergedOptions.apiKey = apiKey;
         }
       }
+      if (perCallMiddleware) {
+        return this.llmProvider.getClient(modelName, mergedOptions, {
+          experimental: this.experimental,
+          disableAPI: this.disableAPI,
+          middleware: perCallMiddleware
+        });
+      }
       const cacheKey = JSON.stringify({
         modelName,
         clientOptions: mergedOptions
@@ -163132,7 +163155,10 @@ var V3 = (() => {
       if (cached2) {
         return cached2;
       }
-      const client = this.llmProvider.getClient(modelName, mergedOptions, { experimental: this.experimental, disableAPI: this.disableAPI });
+      const client = this.llmProvider.getClient(modelName, mergedOptions, {
+        experimental: this.experimental,
+        disableAPI: this.disableAPI
+      });
       this.overrideLlmClients.set(cacheKey, client);
       return client;
     }
@@ -164626,7 +164652,72 @@ var import_child_process4 = require("child_process");
 var readline = __toESM(require("readline"));
 
 // package.json
-var version3 = "0.4.1";
+var version3 = "0.4.2";
+
+// src/local-strategy.ts
+init_cjs_shims();
+var DEFAULT_LOCAL_CONFIG = { strategy: "isolated" };
+var ISOLATED_MODE_HINT = "Hint: Run `browse env local --auto-connect` to reuse your local browsing credentials and cookies.";
+var ATTACHED_EXISTING_HINT = "Hint: Run `browse env local` without `--auto-connect` to switch back to an isolated Chromium browser.";
+function getLocalModeHint(localConfig, localInfo) {
+  if (localInfo?.localSource === "attached-existing") {
+    return ATTACHED_EXISTING_HINT;
+  }
+  if (localInfo?.localSource === "isolated-fallback") {
+    return null;
+  }
+  if (localConfig.strategy === "auto" && !localInfo) {
+    return ATTACHED_EXISTING_HINT;
+  }
+  if (localInfo?.localSource === "isolated" || localConfig.strategy === "isolated" && !localInfo) {
+    return ISOLATED_MODE_HINT;
+  }
+  return null;
+}
+async function resolveLocalStrategy({
+  localConfig,
+  headless,
+  defaultViewport,
+  discoverLocalCdp: discoverLocalCdp2,
+  resolveWsTarget: resolveWsTarget2
+}) {
+  if (localConfig.strategy === "isolated") {
+    return {
+      localLaunchOptions: { headless, viewport: defaultViewport },
+      localInfo: { localSource: "isolated" }
+    };
+  }
+  if (localConfig.strategy === "cdp") {
+    if (!localConfig.cdpTarget) {
+      throw new Error("Local CDP strategy requires a cdpTarget");
+    }
+    const cdpUrl = await resolveWsTarget2(localConfig.cdpTarget);
+    return {
+      localLaunchOptions: { cdpUrl },
+      localInfo: {
+        localSource: "attached-explicit",
+        resolvedCdpUrl: cdpUrl
+      }
+    };
+  }
+  const discovered = await discoverLocalCdp2();
+  if (discovered) {
+    return {
+      localLaunchOptions: { cdpUrl: discovered.wsUrl },
+      localInfo: {
+        localSource: "attached-existing",
+        resolvedCdpUrl: discovered.wsUrl
+      }
+    };
+  }
+  return {
+    localLaunchOptions: { headless, viewport: defaultViewport },
+    localInfo: {
+      localSource: "isolated-fallback",
+      fallbackReason: "no debuggable local browser found"
+    }
+  };
+}
 
 // src/resolve-ws.ts
 init_cjs_shims();
@@ -164651,6 +164742,7 @@ async function resolveWsTarget(input) {
 }
 
 // src/index.ts
+var import_node_html_markdown = require("node-html-markdown");
 var program = new import_commander.Command();
 var SOCKET_DIR = os3.tmpdir();
 function getSocketPath(session) {
@@ -164756,7 +164848,7 @@ async function readLocalConfig(session) {
     const raw = await import_fs11.promises.readFile(getLocalConfigPath(session), "utf-8");
     return JSON.parse(raw);
   } catch {
-    return { strategy: "auto" };
+    return { ...DEFAULT_LOCAL_CONFIG };
   }
 }
 async function writeLocalConfig(session, config3) {
@@ -164773,6 +164865,23 @@ async function readLocalInfo(session) {
     return null;
   }
 }
+async function waitForLocalInfo(session, timeoutMs = 1500) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    const localInfo = await readLocalInfo(session);
+    if (localInfo) {
+      return localInfo;
+    }
+    await new Promise((resolve4) => setTimeout(resolve4, 50));
+  }
+  return readLocalInfo(session);
+}
+function logLocalModeHint(localConfig, localInfo) {
+  const hint = getLocalModeHint(localConfig, localInfo);
+  if (hint) {
+    console.error(hint);
+  }
+}
 function hasBrowserbaseCredentials() {
   return Boolean(process.env.BROWSERBASE_API_KEY);
 }
@@ -165070,33 +165179,15 @@ async function runDaemon(session, headless) {
       let localLaunchOptions;
       let localInfo;
       if (!useBrowserbase) {
-        const localConfig = await readLocalConfig(session);
-        if (localConfig.strategy === "isolated") {
-          localLaunchOptions = { headless, viewport: DEFAULT_VIEWPORT2 };
-          localInfo = { localSource: "isolated" };
-        } else if (localConfig.strategy === "cdp") {
-          const cdpUrl = await resolveWsTarget(localConfig.cdpTarget);
-          localLaunchOptions = { cdpUrl };
-          localInfo = {
-            localSource: "attached-explicit",
-            resolvedCdpUrl: cdpUrl
-          };
-        } else {
-          const discovered = await discoverLocalCdp();
-          if (discovered) {
-            localLaunchOptions = { cdpUrl: discovered.wsUrl };
-            localInfo = {
-              localSource: "attached-existing",
-              resolvedCdpUrl: discovered.wsUrl
-            };
-          } else {
-            localLaunchOptions = { headless, viewport: DEFAULT_VIEWPORT2 };
-            localInfo = {
-              localSource: "isolated-fallback",
-              fallbackReason: "no debuggable local browser found"
-            };
-          }
-        }
+        const resolvedLocalStrategy = await resolveLocalStrategy({
+          localConfig: await readLocalConfig(session),
+          headless,
+          defaultViewport: DEFAULT_VIEWPORT2,
+          discoverLocalCdp,
+          resolveWsTarget
+        });
+        localLaunchOptions = resolvedLocalStrategy.localLaunchOptions;
+        localInfo = resolvedLocalStrategy.localInfo;
       }
       stagehand = new V3({
         env: useBrowserbase ? "BROWSERBASE" : "LOCAL",
@@ -165472,6 +165563,11 @@ async function executeCommand(context, command, args, stagehand) {
           return {
             checked: await page.deepLocator(resolveSelector(selector)).isChecked()
           };
+        case "markdown": {
+          const target = selector ? resolveSelector(selector) : "body";
+          const html = await page.deepLocator(target).innerHtml();
+          return { markdown: import_node_html_markdown.NodeHtmlMarkdown.translate(html) };
+        }
         default:
           throw new Error(`Unknown get type: ${what}`);
       }
@@ -166040,7 +166136,8 @@ program.command("status").description("Check daemon status").action(async () =>
     }
     if (mode === "local") {
       const localConfig = await readLocalConfig(session);
-      const localInfo = await readLocalInfo(session);
+      const localInfo = await readLocalInfo(session) ?? await waitForLocalInfo(session);
+      logLocalModeHint(localConfig, localInfo);
       localDetails = {
         localStrategy: localConfig.strategy,
         ...localInfo ?? {}
@@ -166058,9 +166155,20 @@ program.command("status").description("Check daemon status").action(async () =>
     })
   );
 });
-program.command("env [target] [cdpTarget]").description(
-  "Show or switch browser environment (local | remote)\n\n  browse env              Show current environment\n  browse env local        Auto-discover local Chrome, fallback to isolated\n  browse env local --isolated  Force clean isolated browser\n  browse env local <port|url>  Attach to specific CDP target\n  browse env remote       Use Browserbase (requires API key)"
-).option("--isolated", "Force isolated local browser (no auto-discovery)").action(
+var envUsage = "Usage: browse env [local|remote]\n  browse env local [--auto-connect|<port|url>]";
+var envCommand = program.command("env [target] [cdpTarget]").description(
+  "Show or switch browser environment (local | remote)\n\n  browse env                    Show current environment\n  browse env local              Use clean isolated local browser (default)\n  browse env local --auto-connect  Auto-discover local Chrome, fallback to isolated\n  browse env local <port|url>   Attach to specific CDP target\n  browse env remote             Use Browserbase (requires API key)"
+).option(
+  "--auto-connect",
+  "Auto-discover an existing local Chrome instance via CDP"
+);
+envCommand.addOption(
+  new import_commander.Option(
+    "--isolated",
+    "Deprecated alias for the default isolated local browser"
+  ).hideHelp()
+);
+envCommand.action(
   async (target, cdpTarget, cmdOpts) => {
     const opts = program.opts();
     const session = getSession(opts);
@@ -166091,9 +166199,7 @@ program.command("env [target] [cdpTarget]").description(
     };
     const mapped = modeMap[target];
     if (!mapped) {
-      console.error(
-        "Usage: browse env [local|remote]\n  browse env local [--isolated] [<port|url>]"
-      );
+      console.error(envUsage);
       process.exit(1);
     }
     try {
@@ -166102,10 +166208,22 @@ program.command("env [target] [cdpTarget]").description(
       console.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
-    let localConfig = { strategy: "auto" };
+    let localConfig = { ...DEFAULT_LOCAL_CONFIG };
     if (mapped === "local") {
-      if (cmdOpts.isolated) {
-        localConfig = { strategy: "isolated" };
+      const selectedLocalStrategies = [
+        Boolean(cmdOpts.autoConnect),
+        Boolean(cmdOpts.isolated),
+        Boolean(cdpTarget)
+      ].filter(Boolean);
+      if (selectedLocalStrategies.length > 1) {
+        console.error(envUsage);
+        console.error(
+          "Use only one of --auto-connect, --isolated, or <port|url>."
+        );
+        process.exit(1);
+      }
+      if (cmdOpts.autoConnect) {
+        localConfig = { strategy: "auto" };
       } else if (cdpTarget) {
         localConfig = { strategy: "cdp", cdpTarget };
       }
@@ -166128,6 +166246,9 @@ program.command("env [target] [cdpTarget]").description(
       await stopDaemonAndCleanup(session);
     }
     await ensureDaemon(session, isHeadless(opts));
+    if (mapped === "local") {
+      logLocalModeHint(localConfig, await waitForLocalInfo(session));
+    }
     console.log(
       JSON.stringify({
         mode: toModeTarget(mapped),
@@ -166401,7 +166522,7 @@ program.command("highlight <selector>").description("Highlight element").option(
   }
 });
 program.command("get <what> [selector]").description(
-  "Get page info: url, title, text, html, value, box, visible, checked"
+  "Get page info: url, title, text, html, markdown, value, box, visible, checked"
 ).action(async (what, selector) => {
   const opts = program.opts();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/browse-cli",
-  "version": "0.4.1",
+  "version": "0.4.2-alpha-2df4b01",
   "description": "Browser automation CLI for AI agents, built on Stagehand",
   "type": "commonjs",
   "license": "MIT",
@@ -44,10 +44,11 @@
   "dependencies": {
     "commander": "^12.0.0",
     "dotenv": "^16.4.5",
+    "node-html-markdown": "^1.3.0",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "ws": "^8.18.0",
-    "@browserbasehq/stagehand": "3.2.1-alpha-ad055f91530a84bd5d0735f7d5be82912580914b"
+    "@browserbasehq/stagehand": "3.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",