surf-cli 2.6.0 → 2.7.0

package/native/cli.cjs

@@ -2655,6 +2655,18 @@ delete toolArgs.output;
 if (tool === "aistudio.build" && outputPath) {
   toolArgs.output = path.resolve(outputPath);
 }
+if (tool === "gemini") {
+  if (outputPath) toolArgs.output = path.resolve(outputPath);
+  if (toolArgs["generate-image"] && typeof toolArgs["generate-image"] === "string") {
+    toolArgs["generate-image"] = path.resolve(toolArgs["generate-image"]);
+  }
+  if (toolArgs["edit-image"] && typeof toolArgs["edit-image"] === "string") {
+    toolArgs["edit-image"] = path.resolve(toolArgs["edit-image"]);
+  }
+  if (toolArgs.file && typeof toolArgs.file === "string") {
+    toolArgs.file = path.resolve(toolArgs.file);
+  }
+}
 
 if (tool === "screenshot" && outputPath) {
   if (typeof outputPath !== "string") {

package/native/gemini-client.cjs

@@ -143,7 +143,15 @@ function httpsGet(url, headers, opts = {}) {
 }
 
 function httpsPost(url, headers, body, opts = {}) {
-  const { timeoutMs = 30000, log = null, label = "httpsPost" } = opts;
+  return httpsSend("POST", url, headers, body, opts);
+}
+
+function httpsPut(url, headers, body, opts = {}) {
+  return httpsSend("PUT", url, headers, body, opts);
+}
+
+function httpsSend(method, url, headers, body, opts = {}) {
+  const { timeoutMs = 30000, log = null, label = "httpsSend" } = opts;
   return new Promise((resolve, reject) => {
     const urlObj = new URL(url);
     const bodyBuffer = body == null
@@ -156,7 +164,7 @@ function httpsPost(url, headers, body, opts = {}) {
       hostname: urlObj.hostname,
       port: 443,
       path: urlObj.pathname + urlObj.search,
-      method: "POST",
+      method,
       headers: {
         "user-agent": USER_AGENT,
         ...headers,
@@ -224,6 +232,32 @@ async function fetchGeminiAccessToken(cookieMap, opts = {}) {
 }
 
 function trimGeminiJsonEnvelope(text) {
+  // Handle streaming chunk format: )]}\n\n<size>\n<json>\n<size>\n<json>...
+  const lines = text.split("\n");
+  const chunks = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line === ")]}'" || /^\d+$/.test(line)) continue;
+    if (line.startsWith("[")) {
+      chunks.push(line);
+    }
+  }
+
+  if (chunks.length > 1) {
+    const merged = [];
+    for (const chunk of chunks) {
+      try {
+        const parsed = JSON.parse(chunk);
+        if (Array.isArray(parsed)) {
+          merged.push(...parsed);
+        }
+      } catch {
+        // ignore
+      }
+    }
+    return JSON.stringify(merged);
+  }
+
   const start = text.indexOf("[");
   const end = text.lastIndexOf("]");
   if (start === -1 || end === -1 || end <= start) {
@@ -347,32 +381,48 @@ function parseGeminiStreamGenerateResponse(rawText) {
 // File Upload
 // ============================================================================
 
-async function uploadGeminiFile(filePath, opts = {}) {
+async function uploadGeminiFile(filePath, cookieMap, opts = {}) {
   const absPath = path.resolve(process.cwd(), filePath);
   const data = fs.readFileSync(absPath);
   const fileName = path.basename(absPath);
-  
-  // Build multipart form data manually
-  const boundary = "----FormBoundary" + Math.random().toString(36).slice(2);
-  const header = `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName}"\r\nContent-Type: application/octet-stream\r\n\r\n`;
-  const footer = `\r\n--${boundary}--\r\n`;
-  
-  const body = Buffer.concat([
-    Buffer.from(header, "utf-8"),
-    data,
-    Buffer.from(footer, "utf-8"),
-  ]);
-
-  const res = await httpsPost(GEMINI_UPLOAD_URL, {
-    "content-type": `multipart/form-data; boundary=${boundary}`,
+  const cookieHeader = buildCookieHeader(cookieMap);
+
+  // Step 1: Initiate resumable upload
+  const initRes = await httpsPut(GEMINI_UPLOAD_URL, {
+    "authorization": "Basic c2F2ZXM6cyNMdGhlNmxzd2F2b0RsN3J1d1U=",
+    "content-type": "application/x-www-form-urlencoded;charset=UTF-8",
+    "cookie": cookieHeader,
     "push-id": GEMINI_UPLOAD_PUSH_ID,
-  }, body, { ...opts, label: opts.label || "geminiUpload" });
+    "referer": "https://gemini.google.com/",
+    "x-goog-upload-command": "start",
+    "x-goog-upload-header-content-length": String(data.length),
+    "x-goog-upload-header-content-type": "application/octet-stream",
+    "x-goog-upload-protocol": "resumable",
+    "x-tenant-id": "bard-storage",
+  }, data, { ...opts, label: opts.label || "geminiUploadInit" });
+
+  const uploadId = initRes.headers["x-guploader-uploadid"];
+  if (!uploadId) {
+    throw new Error(`File upload init failed: no upload ID (${initRes.status})`);
+  }
 
-  if (res.status < 200 || res.status >= 300) {
-    throw new Error(`File upload failed: ${res.status} (${res.text.slice(0, 200)})`);
+  // Step 2: Upload data and finalize
+  const uploadUrl = `${GEMINI_UPLOAD_URL}?upload_id=${encodeURIComponent(uploadId)}&upload_protocol=resumable`;
+  const finalRes = await httpsPut(uploadUrl, {
+    "content-type": "application/octet-stream",
+    "cookie": cookieHeader,
+    "origin": "https://gemini.google.com",
+    "referer": "https://gemini.google.com/",
+    "x-goog-upload-command": "upload, finalize",
+    "x-goog-upload-offset": "0",
+    "x-tenant-id": "bard-storage",
+  }, data, { ...opts, label: opts.label || "geminiUpload" });
+
+  if (finalRes.status < 200 || finalRes.status >= 300) {
+    throw new Error(`File upload failed: ${finalRes.status} (${finalRes.text.slice(0, 200)})`);
   }
 
-  return { id: res.text, name: fileName };
+  return { id: finalRes.text, name: fileName };
 }
 
 // ============================================================================
@@ -402,18 +452,51 @@ async function downloadGeminiImage(url, cookieMap, outputPath, opts = {}) {
   fs.writeFileSync(outputPath, res.buffer);
 }
 
+async function downloadGeminiImageViaExtension(url, outputPath, opts = {}) {
+  const { fetchUrl, log } = opts;
+  const fullUrl = ensureFullSizeImageUrl(url);
+  
+  const result = await fetchUrl(fullUrl);
+  if (!result || result.error) throw new Error(`Image download failed: ${result?.error || "no response"}`);
+  if (!result.b64) throw new Error("Image download returned no data");
+  
+  const dir = path.dirname(outputPath);
+  if (dir && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  
+  fs.writeFileSync(outputPath, Buffer.from(result.b64, "base64"));
+}
+
 async function saveFirstGeminiImage(output, cookieMap, outputPath, opts = {}) {
-  // Try generated or web images first
-  const genOrWeb = output.images.find(img => img.kind === "generated") ?? output.images[0];
-  if (genOrWeb?.url) {
-    await downloadGeminiImage(genOrWeb.url, cookieMap, outputPath, opts);
+  const useExtensionDownload = !!opts.fetchUrl;
+  const img = output.images?.find(i => i.kind === "generated") ?? output.images?.[0];
+
+  if (img?.b64) {
+    const dir = path.dirname(outputPath);
+    if (dir && !fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, Buffer.from(img.b64, "base64"));
+    return { saved: true, imageCount: output.images.length };
+  }
+
+  if (img?.url) {
+    if (useExtensionDownload) {
+      await downloadGeminiImageViaExtension(img.url, outputPath, opts);
+    } else {
+      await downloadGeminiImage(img.url, cookieMap, outputPath, opts);
+    }
     return { saved: true, imageCount: output.images.length };
   }
 
-  // Fall back to gg-dl URLs in raw response
-  const ggdl = extractGgdlUrls(output.rawResponseText);
+  const ggdl = extractGgdlUrls(output.rawResponseText || "");
   if (ggdl[0]) {
-    await downloadGeminiImage(ggdl[0], cookieMap, outputPath, opts);
+    if (useExtensionDownload) {
+      await downloadGeminiImageViaExtension(ggdl[0], outputPath, opts);
+    } else {
+      await downloadGeminiImage(ggdl[0], cookieMap, outputPath, opts);
+    }
     return { saved: true, imageCount: ggdl.length };
   }
 
@@ -426,7 +509,7 @@ async function saveFirstGeminiImage(output, cookieMap, outputPath, opts = {}) {
 
 function buildGeminiFReqPayload(prompt, uploaded, chatMetadata) {
   const promptPayload = uploaded.length > 0
-    ? [prompt, 0, null, uploaded.map(file => [[file.id, 1]])]
+    ? [prompt, 0, null, uploaded.map(file => [[file.id, 1], file.name])]
     : [prompt];
 
   const innerList = [promptPayload, null, chatMetadata ?? null];
@@ -443,7 +526,7 @@ async function runGeminiWebOnce(input) {
   // 2. Upload files
   const uploaded = [];
   for (const file of files ?? []) {
-    uploaded.push(await uploadGeminiFile(file, { timeoutMs, log, label: "geminiUpload" }));
+    uploaded.push(await uploadGeminiFile(file, cookieMap, { timeoutMs, log, label: "geminiUpload" }));
   }
 
   // 3. Build request
@@ -519,6 +602,137 @@ async function runGeminiWebWithFallback(input) {
   return { ...attempt, effectiveModel: input.model };
 }
 
+// ============================================================================
+// In-Page Execution (for image generation)
+// ============================================================================
+
+async function runGeminiWebViaPage(input) {
+  const { prompt, files, model, timeoutMs = 120000, log = null, createTab, closeTab, jsEval, fetchUrl, uploadFile } = input;
+
+  if (!createTab || !closeTab || !jsEval) {
+    throw new Error("In-page execution requires createTab, closeTab, and jsEval callbacks");
+  }
+
+  let tabId = null;
+  try {
+    if (log) log("Creating Gemini tab...");
+    const tabResult = await createTab();
+    tabId = tabResult?.tabId;
+    if (!tabId) throw new Error("Failed to create Gemini tab");
+    if (log) log(`Gemini tab created: ${tabId}`);
+    await new Promise(r => setTimeout(r, 12000));
+
+    if (files?.length && uploadFile) {
+      const absFiles = files.map(f => path.resolve(process.cwd(), f));
+      if (log) log(`Uploading ${absFiles.length} file(s) via file chooser...`);
+      const result = await uploadFile(tabId, absFiles);
+      if (result?.error) throw new Error(`File upload failed: ${result.error}`);
+      if (log) log("File uploaded, waiting for processing...");
+      await new Promise(r => setTimeout(r, 3000));
+    }
+
+    const checkJsResult = (result, context) => {
+      if (result?.error) throw new Error(`${context}: ${result.error}`);
+      if (result?.output === undefined) throw new Error(`${context}: no output`);
+      return result.output;
+    };
+
+    // Type prompt
+    const fullPrompt = prompt.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+    if (log) log("Typing prompt...");
+    const typeResult = await jsEval(tabId, `
+      const editor = document.querySelector('.ql-editor[contenteditable=true]');
+      if (!editor) return JSON.stringify({ error: "No editor found on page" });
+      editor.focus();
+      document.execCommand('selectAll', false, null);
+      document.execCommand('insertText', false, '${fullPrompt}');
+      return JSON.stringify({ ok: true, len: editor.textContent.length });
+    `);
+    const typed = JSON.parse(JSON.parse(checkJsResult(typeResult, "Type prompt")));
+    if (typed.error) throw new Error(typed.error);
+
+    const beforeResult = await jsEval(tabId, `
+      return String(Array.from(document.querySelectorAll('img[src*="gg-dl"]')).filter(i => i.naturalWidth >= 512).length);
+    `);
+    const imgCountBefore = parseInt(JSON.parse(checkJsResult(beforeResult, "Count images")) || "0", 10);
+
+    if (log) log("Submitting...");
+    const sendResult = await jsEval(tabId, `
+      const btn = document.querySelector('button[aria-label="Send message"]');
+      if (!btn) return 'no-btn';
+      btn.click();
+      return 'sent';
+    `);
+    const sendVal = JSON.parse(checkJsResult(sendResult, "Click send"));
+    if (sendVal === "no-btn") throw new Error("Send button not found on Gemini page");
+
+    // Poll for response
+    if (log) log("Waiting for response...");
+    const deadline = Date.now() + timeoutMs;
+    let imageUrls = [];
+    let responseText = "";
+
+    while (Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 2000));
+      const pollResult = await jsEval(tabId, `
+        const ggImgs = Array.from(document.querySelectorAll('img[src*="gg-dl"]'))
+          .filter(i => i.naturalWidth >= 512)
+          .map(i => i.src);
+        const loading = !!document.querySelector('mat-progress-bar, .loading-indicator, message-loading');
+        const turns = document.querySelectorAll('message-content');
+        const lastTurn = turns.length ? turns[turns.length - 1] : null;
+        const text = lastTurn ? lastTurn.textContent?.trim() : "";
+        return JSON.stringify({ ggImgs, loading, text, turns: turns.length });
+      `);
+      const poll = JSON.parse(JSON.parse(checkJsResult(pollResult, "Poll response")));
+      const newImgs = poll.ggImgs.slice(imgCountBefore);
+
+      if (newImgs.length > 0) {
+        imageUrls = newImgs;
+        responseText = poll.text || "";
+        if (log) log(`Found ${newImgs.length} generated image(s)`);
+        break;
+      }
+      if (!poll.loading && poll.text && poll.turns > 0) {
+        responseText = poll.text;
+        break;
+      }
+    }
+
+    if (!imageUrls.length && !responseText) {
+      throw new Error("Gemini response timed out");
+    }
+
+    // Download images via extension
+    const images = [];
+    if (fetchUrl) {
+      for (const url of imageUrls) {
+        if (log) log(`Downloading image (${url.slice(0, 60)}...)...`);
+        const dlResult = await fetchUrl(url);
+        if (dlResult?.b64) {
+          images.push({ url, b64: dlResult.b64, type: dlResult.type || "image/png" });
+        }
+      }
+    } else {
+      for (const url of imageUrls) {
+        images.push({ url });
+      }
+    }
+
+    return {
+      text: responseText,
+      thoughts: null,
+      metadata: null,
+      images,
+      effectiveModel: model,
+      _pageTabId: tabId,
+    };
+  } catch (err) {
+    if (tabId) { try { await closeTab(tabId); } catch {} }
+    throw err;
+  }
+}
+
 // ============================================================================
 // Main Query Function
 // ============================================================================
@@ -534,9 +748,15 @@ async function query(options) {
     youtube,
     aspectRatio,
     getCookies,
+    createTab,
+    closeTab,
+    jsEval,
+    fetchUrl,
+    uploadFile,
     timeout = 300000,
     log = () => {},
   } = options;
+  const hasPageCallbacks = !!(createTab && closeTab && jsEval);
 
   const startTime = Date.now();
   log("Starting Gemini query");
@@ -579,59 +799,80 @@ async function query(options) {
 
   try {
     if (editImage) {
-      // Two-turn conversation for image editing
-      log("Uploading image for editing...");
-      const intro = await runGeminiWebWithFallback({
-        prompt: "Here is an image to edit",
+      // Image editing
+      if (!hasPageCallbacks) {
+        throw new Error("Image editing requires the Chrome extension. Make sure it's loaded.");
+      }
+
+      log("Uploading and editing image...");
+      const out = await runGeminiWebViaPage({
+        prompt: fullPrompt,
         files: [editImage],
         model: resolvedModel,
-        cookieMap,
-        chatMetadata: null,
-        timeoutMs: timeout,
-        log,
-      });
-      
-      log("Sending edit request...");
-      const editPrompt = `Use image generation tool to ${fullPrompt}`;
-      const out = await runGeminiWebWithFallback({
-        prompt: editPrompt,
-        files,
-        model: resolvedModel,
-        cookieMap,
-        chatMetadata: intro.metadata,
         timeoutMs: timeout,
         log,
+        createTab,
+        closeTab,
+        jsEval,
+        fetchUrl,
+        uploadFile,
       });
 
       response = out;
       
       // Save output image
       const outputPath = output || generateImage || "edited.png";
-      const imageSave = await saveFirstGeminiImage(out, cookieMap, outputPath, { timeoutMs: timeout, log });
-      if (!imageSave.saved) {
-        throw new Error(`No images generated. Response: ${out.text?.slice(0, 200) || "(empty)"}`);
+      const saveOpts = { timeoutMs: timeout, log };
+      if (fetchUrl) saveOpts.fetchUrl = fetchUrl;
+      try {
+        const imageSave = await saveFirstGeminiImage(out, cookieMap, outputPath, saveOpts);
+        if (!imageSave.saved) {
+          throw new Error(`No images generated. Response: ${out.text?.slice(0, 200) || "(empty)"}`);
+        }
+      } finally {
+        if (out._pageTabId && closeTab) { try { await closeTab(out._pageTabId); } catch {} }
       }
       imagePath = outputPath;
       
     } else if (generateImage) {
       // Image generation
       log("Generating image...");
-      const out = await runGeminiWebWithFallback({
-        prompt: fullPrompt,
-        files,
-        model: resolvedModel,
-        cookieMap,
-        chatMetadata: null,
-        timeoutMs: timeout,
-        log,
-      });
+      let out;
+      if (hasPageCallbacks) {
+        out = await runGeminiWebViaPage({
+          prompt: fullPrompt,
+          model: resolvedModel,
+          timeoutMs: timeout,
+          log,
+          createTab,
+          closeTab,
+          jsEval,
+          fetchUrl,
+        });
+      } else {
+        out = await runGeminiWebWithFallback({
+          prompt: fullPrompt,
+          files,
+          model: resolvedModel,
+          cookieMap,
+          chatMetadata: null,
+          timeoutMs: timeout,
+          log,
+        });
+      }
 
       response = out;
       
       // Save output image
-      const imageSave = await saveFirstGeminiImage(out, cookieMap, generateImage, { timeoutMs: timeout, log });
-      if (!imageSave.saved) {
-        throw new Error(`No images generated. Response: ${out.text?.slice(0, 200) || "(empty)"}`);
+      const saveOpts = { timeoutMs: timeout, log };
+      if (fetchUrl) saveOpts.fetchUrl = fetchUrl;
+      try {
+        const imageSave = await saveFirstGeminiImage(out, cookieMap, generateImage, saveOpts);
+        if (!imageSave.saved) {
+          throw new Error(`No images generated. Response: ${out.text?.slice(0, 200) || "(empty)"}`);
+        }
+      } finally {
+        if (out._pageTabId && closeTab) { try { await closeTab(out._pageTabId); } catch {} }
       }
       imagePath = generateImage;
       

package/native/host.cjs

@@ -697,6 +697,57 @@ function handleToolRequest(msg, socket) {
           });
           writeMessage({ type: "GET_GOOGLE_COOKIES", id: cookieId });
         }),
+        createTab: () => new Promise((resolve) => {
+          const tabCreateId = ++requestCounter;
+          pendingToolRequests.set(tabCreateId, {
+            socket: null,
+            originalId: null,
+            tool: "create_tab",
+            onComplete: (r) => resolve(r)
+          });
+          writeMessage({ type: "GEMINI_NEW_TAB", id: tabCreateId });
+        }),
+        closeTab: (tabIdToClose) => new Promise((resolve) => {
+          const tabCloseId = ++requestCounter;
+          pendingToolRequests.set(tabCloseId, {
+            socket: null,
+            originalId: null,
+            tool: "close_tab",
+            onComplete: (r) => resolve(r)
+          });
+          writeMessage({ type: "GEMINI_CLOSE_TAB", tabId: tabIdToClose, id: tabCloseId });
+        }),
+        jsEval: (tabId, code) => new Promise((resolve) => {
+          const jsId = ++requestCounter;
+          pendingToolRequests.set(jsId, {
+            socket: null,
+            originalId: null,
+            tool: "js_eval",
+            onComplete: (r) => resolve(r)
+          });
+          log(`[gemini] Sending EXECUTE_JAVASCRIPT id=${jsId} tabId=${tabId} code=${code.length} chars`);
+          writeMessage({ type: "EXECUTE_JAVASCRIPT", tabId, code, id: jsId });
+        }),
+        uploadFile: (tabId, filePaths) => new Promise((resolve) => {
+          const uploadId = ++requestCounter;
+          pendingToolRequests.set(uploadId, {
+            socket: null,
+            originalId: null,
+            tool: "upload_file",
+            onComplete: (r) => resolve(r)
+          });
+          writeMessage({ type: "UPLOAD_FILE_TO_TAB", tabId, filePaths, id: uploadId });
+        }),
+        fetchUrl: (url) => new Promise((resolve) => {
+          const fetchId = ++requestCounter;
+          pendingToolRequests.set(fetchId, {
+            socket: null,
+            originalId: null,
+            tool: "fetch_url",
+            onComplete: (r) => resolve(r)
+          });
+          writeMessage({ type: "GEMINI_FETCH_URL", url, id: fetchId });
+        }),
         log: (msg) => log(`[gemini] ${msg}`)
       });
       

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -51,21 +51,21 @@
   },
   "dependencies": {
     "@google/generative-ai": "^0.24.1",
-    "@modelcontextprotocol/sdk": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "buffer": "^6.0.3",
     "crypto-browserify": "^3.12.1",
     "events": "^3.3.0",
     "stream-browserify": "^3.0.0",
     "vite-plugin-node-polyfills": "^0.25.0",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
-    "@types/chrome": "^0.0.287",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vitest/ui": "^4.0.16",
+    "@biomejs/biome": "^2.4.4",
+    "@types/chrome": "^0.1.37",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
     "typescript": "^5.7.2",
     "vite": "^7.3.1",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   }
 }

package/skills/README.md

@@ -8,10 +8,10 @@ To use the surf skill with [Pi coding agent](https://github.com/badlogic/pi-mono
 
 ```bash
 # Option 1: Symlink (auto-updates)
-ln -s "$(pwd)/skills/surf" ~/.pi/agent/skills/surf
+ln -s "$(pwd)/skills/surf" ~/.agents/skills/surf
 
 # Option 2: Copy
-cp -r skills/surf ~/.pi/agent/skills/
+cp -r skills/surf ~/.agents/skills/
 ```
 
 The skill will be available when pi detects browser automation tasks.

package/skills/surf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: surf
-description: Control Chrome browser via CLI for testing, automation, and debugging. Use when the user needs browser automation, screenshots, form filling, page inspection, network/CPU emulation, DevTools streaming, or AI queries via ChatGPT/Gemini/Perplexity/Grok.
+description: Control Chrome browser via CLI for testing, automation, and debugging. Use when the user needs browser automation, screenshots, form filling, page inspection, network/CPU emulation, DevTools streaming, or AI queries via ChatGPT/Gemini/Perplexity/Grok/AI Studio.
 ---
 
 # Surf Browser Automation
@@ -87,13 +87,42 @@ surf grok --validate
 surf grok --validate --save-models
 ```
 
+### AI Studio (via aistudio.google.com - requires Google login in Chrome)
+```bash
+surf aistudio "explain quantum computing"
+surf aistudio "redteam this" --with-page          # Include current page context
+surf aistudio "quick answer" --model gemini-3-flash-preview  # Model selection
+surf aistudio "analyze" --timeout 600             # Custom timeout (default: 300s)
+```
+
+**Why AI Studio over Gemini?** AI Studio gives access to less restricted Gemini models. For Gemini 3 Pro the difference can be significant with certain prompts. Downside: aggressive per-day rate limits on Pro and Flash models.
+
+**Model selection is best-effort:** Pass any AI Studio model id (e.g. `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-flash-lite-latest`). If the model isn't found, AI Studio uses whatever model was last selected in the UI.
+
+### AI Studio App Builder
+```bash
+surf aistudio.build "build a portfolio site"
+surf aistudio.build "todo app" --model gemini-3.1-pro-preview   # Model override
+surf aistudio.build "crm dashboard" --output ./out              # Extract zip to directory
+surf aistudio.build "game" --keep-open --timeout 600            # Keep tab open, 10min timeout
+```
+
+Automates AI Studio's App Builder at `aistudio.google.com/apps`. Types your prompt, clicks Build, waits for completion, downloads the generated zip, and optionally extracts it.
+
+- `--output <dir>` extracts the zip to a directory
+- `--model <id>` overrides the model in Advanced Settings
+- `--timeout <seconds>` build timeout (default: 600s)
+- `--keep-open` leaves the AI Studio tab open after completion
+
+Returns `zipPath`, `extractedPath`, `model`, `buildDuration`, and `tookMs`.
+
 ### AI Tool Troubleshooting
 
 When AI queries fail, check these common issues:
 
-1. **Not logged in**: The error "login required" means you need to log into the service in Chrome
+1. **Not logged in**: The error "login required" means you need to log into the service in Chrome (chatgpt.com, gemini.google.com, perplexity.ai, x.com, or aistudio.google.com)
 2. **Model selection failed**: The UI may have changed. Run `surf grok --validate` to check
-3. **Response timeout**: Thinking models (ChatGPT o1, Grok thinking) can take 45+ seconds
+3. **Response timeout**: Thinking models (ChatGPT o1, Grok thinking) can take 45+ seconds. AI Studio builds can take several minutes.
 4. **Element not found**: The service's UI changed. Check for surf-cli updates
 
 **Debugging workflow for agents:**
@@ -527,14 +556,15 @@ surf wait.element ".missing" --auto-capture --timeout 2000
 3. **JS method for contenteditable** - Modern editors (ChatGPT, Claude, Notion) need `--method js`
 4. **Named tabs for workflows** - `tab.name app` then `tab.switch app`
 5. **Auto-capture for debugging** - `--auto-capture` saves diagnostics on failure
-6. **AI tools use browser session** - Must be logged into the service, no API keys needed
+6. **AI tools use browser session** - Must be logged into the service (ChatGPT, Gemini, Perplexity, Grok, AI Studio), no API keys needed
 7. **Grok validation** - Run `surf grok --validate` if queries fail to check UI changes
-8. **Long timeouts for thinking models** - ChatGPT o1, Grok thinking can take 60+ seconds
-9. **Use `surf do` for multi-step tasks** - Reduces token overhead and improves reliability
-10. **Dry-run workflows first** - `surf do '...' --dry-run` validates without executing
-11. **Window isolation** - Use `window.new` + `--window-id` to keep agent work separate from your browsing
-12. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
-13. **Frame context** - Use `frame.switch` before interacting with iframe content
+8. **Long timeouts for thinking models** - ChatGPT o1, Grok thinking can take 60+ seconds. AI Studio builds default to 600s.
+9. **AI Studio for unrestricted Gemini** - `surf aistudio` gives less filtered responses than `surf gemini` for the same models
+10. **Use `surf do` for multi-step tasks** - Reduces token overhead and improves reliability
+11. **Dry-run workflows first** - `surf do '...' --dry-run` validates without executing
+12. **Window isolation** - Use `window.new` + `--window-id` to keep agent work separate from your browsing
+13. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
+14. **Frame context** - Use `frame.switch` before interacting with iframe content
 
 ## Socket API