@53able/pi-agent-browser 0.2.0 → 0.4.0

package/README.ja-JP.md

@@ -66,6 +66,7 @@ pi install ./pi-agent-browser
 - `agent_browser_state` — saved state を save / load / list / show / rename / clear / clean する
 - `agent_browser_close` — browser session を閉じる
 - `agent_browser_handoff` — 2FA・CAPTCHA・本人確認のために一時停止し、人間に操作を戻す
+- `agent_browser_login_handoff` — インタラクティブなログイン（Google、OAuth など）のための無人 browser を起動する
 - `agent_browser_commit` — 決済・削除・投稿・送信など、やり直しのきかない操作の確認ゲート
 - `agent_browser_doctor` — `agent-browser doctor` を実行する
 
@@ -160,12 +161,15 @@ https://example.com をブラウザ経由で読み、outputs/browser/example.md
 
 ## 人間への handoff（引き渡し）
 
-すべての操作を無人で任せるべきではありません。適切なタイミングで人間に操作を戻すためのツールが2つあります。
+すべての操作を無人で任せるべきではありません。適切なタイミングで人間に操作を戻すためのツールが3つあります。
 
 - **安全な境界線** — `agent_browser_handoff` は、AI自身では対応できない・すべきでない操作（2FA/OTPの入力、CAPTCHA、本人確認）の直前でエージェントを一時停止させます。スクリーンショットで状況を記録したあと、実際のUIダイアログでブロックし、人間が「対応完了」または「中止」を選ぶまで待ちます。`agent_browser_read` / `agent_browser_snapshot` も簡易なキーワード検知を行い、こうしたチェックポイントらしき内容を出力に警告として付加します（この警告自体は停止ではなく、`agent_browser_handoff` を呼ぶきっかけとして扱ってください）。
+- **インタラクティブなログイン** — `agent_browser_login_handoff` は、Google や OAuth など多くのプロバイダで sign-in がブロックされる問題を解決します。これは、agent-browser が使われた時点でオートメーション検出が起きるため、ログイン中に拒否されるというもの。このツールは CDP が接続されていない無人 Chrome プロセスを起動し、人間が正常にログインできるようにしてから、ログイン成功後に `agent-browser` を接続します。Google や OAuth の sign-in フローが期待されるタスクでは、`agent_browser_open` ではなく必ずこちらを使ってください。
 - **Commit前の停止** — `agent_browser_commit` は、決済・削除・投稿・送信といった「やり直しのきかない操作」専用の確認ゲートです。証跡を保存し、クリックの前に必ず人間の明示的な確認を求め、承認されない限りクリックは実行されません。対話的なUIが利用できない場合は、クリックせずにそのまま拒否します。こうした操作の最終確認クリックには `agent_browser_click` ではなく必ずこちらを使ってください。
 
-どちらのツールも対話的なセッション（TUI、またはUI対応のRPC）を必要とします。無人・headless実行では、黙って進めるのではなく拒否します。
+3つのツールすべてが対話的なセッション（TUI、またはUI対応のRPC）を必要とします。無人・headless実行では、黙って進めるのではなく拒否します。
+
+`agent_browser_open` と `agent_browser_login_handoff` は、各セッションが`headed: true`で起動されたかどうかも記録します。`agent_browser_handoff`が、headedで開かれていないセッションに対して呼ばれた場合、人間への警告に加えて、可視ウィンドウを開き直すための`agent_browser_open`の引数（セッション名、`headed: true`、`restore: true`、最後に開いていたURL）をそのまま提示します — どのコマンドを打ち直せばよいか推測する必要はありません。ログインや2FA、CAPTCHA、本人確認に差し掛かる可能性があるタスクでは、最初から`headed: true`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。
 
 ## Troubleshooting
 

package/README.md

@@ -66,6 +66,7 @@ pi install ./pi-agent-browser
 - `agent_browser_state` — save, load, list, show, rename, clear, or clean saved state
 - `agent_browser_close` — close a browser session
 - `agent_browser_handoff` — pause and hand control to a human for 2FA, CAPTCHA, or identity verification
+- `agent_browser_login_handoff` — spawn an unattended browser for interactive login flows (Google, OAuth)
 - `agent_browser_commit` — confirmation gate for irreversible actions (payment, delete, publish, send)
 - `agent_browser_doctor` — run `agent-browser doctor`
 
@@ -160,12 +161,15 @@ Clear all saved states only when intentionally resetting everything:
 
 ## Human handoff
 
-Not every step should run unattended. Two tools hand control back to a human at the right moments:
+Not every step should run unattended. Three tools hand control back to a human at the right moments:
 
 - **Safe boundaries** — `agent_browser_handoff` pauses the agent for steps it cannot or should not perform itself: 2FA/OTP entry, CAPTCHA, identity verification. It captures a screenshot for context, then blocks on a real confirmation dialog until a human resumes or aborts. `agent_browser_read` and `agent_browser_snapshot` also run a lightweight keyword scan and flag likely checkpoints in their output as a nudge to call this tool.
+- **Interactive login flows** — `agent_browser_login_handoff` solves the problem that Google, OAuth, and similar providers block sign-in when agent-browser is used, because automation detection happens during the login step itself. This tool spawns an unattended Chrome process (with no CDP attached) so the human can log in normally, then attaches `agent-browser` after login succeeds. Use this instead of `agent_browser_open` whenever a task is expected to hit an interactive Google or OAuth sign-in flow.
 - **Stop before commit** — `agent_browser_commit` is a dedicated gate for irreversible actions: payment, deletion, publishing, sending. It captures evidence, requires explicit human confirmation before clicking, and refuses outright (without clicking) if no interactive UI is available to ask. Use it instead of `agent_browser_click` for the final confirming step of any such action.
 
-Both tools require an interactive session (TUI or RPC with UI support); in headless/unattended runs they refuse rather than proceed silently.
+All three tools require an interactive session (TUI or RPC with UI support); in headless/unattended runs they refuse rather than proceed silently.
+
+`agent_browser_open` and `agent_browser_login_handoff` both remember whether each named session was launched with `headed: true`. If `agent_browser_handoff` is called for a session that was not opened headed, it automatically warns the human and includes the exact `agent_browser_open` arguments (session name, `headed: true`, `restore: true`, and the last known URL) needed to reopen a visible window — no more guessing which command to rerun. Prefer `headed: true` up front for any task that might hit a login, 2FA, CAPTCHA, or identity-verification step, since some challenges are single-use and reopening mid-flow may require restarting the login.
 
 ## Troubleshooting
 

package/index.ts

@@ -1,9 +1,10 @@
 import type { ExtensionAPI, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { access, mkdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { constants, existsSync } from "node:fs";
 import { join, resolve, basename } from "node:path";
 import { spawn } from "node:child_process";
+import { createServer } from "node:net";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_PREVIEW_CHARS = 12_000;
@@ -35,6 +36,51 @@ function scanForSensitiveContent(text: string): string[] {
   return hits;
 }
 
+// Tracks whether each agent-browser session was last opened headed, so
+// agent_browser_handoff / agent_browser_commit can tell a human definitively
+// whether a visible browser window exists for them to act in, instead of guessing.
+const SESSION_STATE_DIR = ".pi-agent-browser";
+const SESSION_STATE_FILE = "sessions.json";
+const DEFAULT_SESSION_KEY = "__default__";
+
+type SessionState = { headed: boolean; lastUrl?: string; updatedAt: string };
+
+function sessionKey(params: JsonObject): string {
+  return typeof params.session === "string" && params.session.trim() ? params.session.trim() : DEFAULT_SESSION_KEY;
+}
+
+async function readSessionStates(cwd: string): Promise<Record<string, SessionState>> {
+  try {
+    const raw = await readFile(join(cwd, SESSION_STATE_DIR, SESSION_STATE_FILE), "utf8");
+    return JSON.parse(raw) as Record<string, SessionState>;
+  } catch {
+    return {};
+  }
+}
+
+async function writeSessionState(cwd: string, session: string, patch: Partial<Omit<SessionState, "updatedAt">>): Promise<void> {
+  const dir = join(cwd, SESSION_STATE_DIR);
+  await mkdir(dir, { recursive: true });
+  const states = await readSessionStates(cwd);
+  const previous = states[session];
+  states[session] = {
+    headed: patch.headed ?? previous?.headed ?? false,
+    lastUrl: patch.lastUrl ?? previous?.lastUrl,
+    updatedAt: new Date().toISOString(),
+  };
+  await writeFile(join(dir, SESSION_STATE_FILE), JSON.stringify(states, null, 2), "utf8");
+}
+
+function reopenHeadedGuidance(session: string, lastUrl: string | undefined): string[] {
+  const sessionArg = session === DEFAULT_SESSION_KEY ? {} : { session };
+  const reopenArgs = JSON.stringify({ ...sessionArg, headed: true, restore: true, ...(lastUrl ? { url: lastUrl } : {}) });
+  return [
+    `⚠ このセッション(${session === DEFAULT_SESSION_KEY ? "既定セッション" : session})はheadless(ウィンドウ非表示)で開かれています。`,
+    `人間が直接操作できるようにするには、agent_browser_open を次の引数で呼び直してください: ${reopenArgs}`,
+    "同じセッション名なのでcookie等は復元されますが、2FA/CAPTCHAなど使い切り・期限付きのチャレンジは、再度最初からやり直しになる場合があります。",
+  ];
+}
+
 type JsonObject = Record<string, unknown>;
 
 type RunResult = {
@@ -155,6 +201,15 @@ const HandoffSchema = Type.Object(commonSchema({
   screenshot: optionalBoolean("Capture a screenshot for the human before waiting. Defaults to true."),
 }));
 
+const LoginHandoffSchema = Type.Object({
+  url: Type.String({ description: "Login/app URL to open in a real, non-automated browser for the human to sign in." }),
+  session: optionalString("agent-browser session name to attach as after login completes. Defaults to the default session."),
+  reason: Type.String({ description: "Human-readable reason for the login handoff (e.g. 'Googleアカウントへのログインが必要です')." }),
+  executablePath: optionalString("Override path to a real Chrome executable. Auto-detected on macOS if omitted."),
+  profileDir: optionalString("Override persistent user-data-dir for the login browser. Defaults to a per-session directory reused across runs so re-running the same session reuses the same authenticated profile."),
+  timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Tool execution timeout in milliseconds for the post-login attach step." })),
+});
+
 const CommitSchema = Type.Object(commonSchema({
   selector: Type.String({ description: "Element ref from snapshot, such as @e2, or a CSS selector, for the irreversible action (e.g. final pay/post/delete button)." }),
   summary: Type.String({ description: "Plain-language description of what this click will do, e.g. '¥12,000 の決済を確定する' or 'この投稿を完全に削除する'." }),
@@ -190,6 +245,61 @@ async function findAgentBrowserBin(): Promise<string> {
   return "agent-browser";
 }
 
+function findRealChromeExecutable(): string | undefined {
+  const macPath = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  if (existsSync(macPath)) return macPath;
+  return undefined;
+}
+
+async function findFreePort(): Promise<number> {
+  return await new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : undefined;
+      server.close(() => {
+        if (port) resolvePort(port);
+        else reject(new Error("Could not determine a free port."));
+      });
+    });
+  });
+}
+
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolveDelay) => {
+    if (signal?.aborted) {
+      resolveDelay();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolveDelay();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolveDelay();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+async function waitForDebugPort(port: number, timeoutMs = 8000, intervalMs = 300, signal?: AbortSignal): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) return false;
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+      if (res.ok) return true;
+    } catch {
+      // Not up yet; keep polling.
+    }
+    if (signal?.aborted) return false;
+    await abortableDelay(intervalMs, signal);
+  }
+  return false;
+}
+
 function pushCommonArgs(args: string[], params: JsonObject): void {
   if (typeof params.session === "string" && params.session.trim()) {
     args.push("--session", params.session.trim());
@@ -346,6 +456,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
     promptGuidelines: [
       "Use agent_browser_snapshot after opening or navigating before clicking by @ref.",
       "Pass allowedDomains for untrusted or task-scoped browsing when possible.",
+      "Prefer headed: true whenever the task might hit a login, 2FA, CAPTCHA, or identity-verification step — a human can only intervene through agent_browser_handoff if a visible window already exists.",
     ],
     parameters: OpenSchema,
     async execute(_id, rawParams, signal, onUpdate, ctx) {
@@ -365,6 +476,12 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
       if (typeof params.url === "string" && params.url.trim()) args.push(params.url.trim());
       pushExtraArgs(args, params);
       const result = await runAgentBrowser(args, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+      if (result.ok) {
+        await writeSessionState(ctx.cwd, sessionKey(params), {
+          headed: params.headed === true,
+          lastUrl: typeof params.url === "string" && params.url.trim() ? params.url.trim() : undefined,
+        });
+      }
       return buildTextResult(result);
     },
   });
@@ -582,6 +699,9 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
       const category = String(params.category);
       const reason = String(params.reason);
       const artifacts: string[] = [];
+      const session = sessionKey(params);
+      const sessionState = (await readSessionStates(ctx.cwd))[session];
+      const headlessNotes = sessionState?.headed === true ? [] : reopenHeadedGuidance(session, sessionState?.lastUrl);
 
       if (params.screenshot !== false) {
         const path = resolveOutputPath(ctx, undefined, "handoff.png");
@@ -601,6 +721,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
               `Human handoff required (${category}) but no interactive UI is available in this run mode.`,
               `Reason: ${reason}`,
               artifacts.length ? `Evidence: ${artifacts.join(", ")}` : undefined,
+              ...headlessNotes,
               "Stop this task now and ask the operator to rerun it interactively so the handoff can be completed.",
             ].filter(Boolean).join("\n"),
           }],
@@ -609,8 +730,9 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         };
       }
 
+      if (headlessNotes.length) ctx.ui.notify(headlessNotes.join(" "), "warning");
       ctx.ui.notify(`Human handoff needed (${category}): ${reason}`, "warning");
-      ctx.ui.setStatus("agent-browser-handoff", `⏸ Waiting for human: ${reason}`);
+      ctx.ui.setStatus("agent-browser-handoff", headlessNotes.length ? `⏸ ブラウザ非表示 — ${reason}` : `⏸ Waiting for human: ${reason}`);
       let choice: string | undefined;
       try {
         choice = await ctx.ui.select(
@@ -626,6 +748,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         content: [{
           type: "text",
           text: [
+            ...headlessNotes,
             resumed
               ? "Human confirmed the handoff step is complete. Take a fresh agent_browser_snapshot before continuing."
               : "Human aborted the task during handoff. Stop and report back; do not retry automatically.",
@@ -638,6 +761,168 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "agent_browser_login_handoff",
+    label: "Agent Browser Login Handoff",
+    description: "Launch a real, non-CDP-attached Chrome for an interactive login (e.g. Google sign-in) that automation frameworks get blocked from, then attach agent-browser to the resulting session once the human confirms login is complete. Blocks until the human confirms or aborts.",
+    promptSnippet: "Use agent_browser_login_handoff (not agent_browser_open) whenever a task requires an interactive Google/OAuth-style login.",
+    promptGuidelines: [
+      "Never attempt an interactive Google/OAuth-style login via agent_browser_open, agent_browser_click, or agent_browser_fill — those attach CDP immediately, and Google blocks sign-in for CDP-attached sessions regardless of profile or cookies.",
+      "Call this tool instead whenever a task is expected to require signing into a Google account or a similarly automation-hostile login flow.",
+      "After this tool reports success, take a fresh agent_browser_snapshot before continuing — do not assume page state.",
+      "If this tool reports no interactive UI, a decline, or a failure, stop the task and report back; do not retry via agent_browser_open.",
+    ],
+    parameters: LoginHandoffSchema,
+    async execute(_id, rawParams, signal, onUpdate, ctx) {
+      const params = rawParams as JsonObject;
+      const url = String(params.url);
+      const reason = String(params.reason);
+      const session = sessionKey(params);
+
+      const executablePath = typeof params.executablePath === "string" && params.executablePath.trim()
+        ? params.executablePath.trim()
+        : findRealChromeExecutable();
+
+      if (!executablePath) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Could not find a real Chrome executable for the login handoff.",
+              "Auto-detection only checks the default macOS install path (/Applications/Google Chrome.app/Contents/MacOS/Google Chrome).",
+              "Pass executablePath explicitly, or install Google Chrome, and retry. Do not fall back to agent-browser's bundled test browser — it will be blocked by Google the same way.",
+            ].join("\n"),
+          }],
+          details: { ok: false, command: "login-handoff", args: [], stdout: "", stderr: "no chrome executable found", exitCode: null, signal: null, durationMs: 0 },
+          terminate: true,
+        };
+      }
+
+      const profileDir = typeof params.profileDir === "string" && params.profileDir.trim()
+        ? params.profileDir.trim()
+        : join(ctx.cwd, SESSION_STATE_DIR, "login-profiles", session);
+      await mkdir(profileDir, { recursive: true });
+
+      const port = await findFreePort();
+
+      let spawnError: Error | undefined;
+      const child = spawn(executablePath, [
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${profileDir}`,
+        "--no-first-run",
+        "--no-default-browser-check",
+        url,
+      ], { detached: true, stdio: "ignore" });
+      // Persistent handler: without this, an 'error' event (e.g. ENOENT for a bad
+      // executablePath) on this detached/unref'd child is unhandled and crashes the
+      // whole host process whenever it fires, even long after this tool call returns.
+      child.on("error", (error) => {
+        spawnError = error;
+      });
+      child.unref();
+
+      const debugPortWaitController = new AbortController();
+      const debugPortUp = spawnError ? false : await Promise.race([
+        waitForDebugPort(port, undefined, undefined, debugPortWaitController.signal),
+        new Promise<boolean>((resolveRace) => {
+          child.once("error", () => resolveRace(false));
+        }),
+      ]);
+      // Whichever branch lost the race must stop polling promptly instead of
+      // holding the event loop open for its own full timeout in the background.
+      debugPortWaitController.abort();
+      if (spawnError || !debugPortUp) {
+        try { child.kill(); } catch { /* best-effort */ }
+        return {
+          content: [{
+            type: "text",
+            text: [
+              spawnError
+                ? `Failed to launch the login browser: ${spawnError.message}`
+                : `Failed to confirm the login browser's debug port (127.0.0.1:${port}) came up in time.`,
+              `Attempted to launch: ${executablePath}`,
+              "The login browser was not confirmed usable; it has been asked to close. Stop and report back.",
+            ].join("\n"),
+          }],
+          details: { ok: false, command: "login-handoff", args: [executablePath, url], stdout: "", stderr: spawnError ? spawnError.message : "debug port did not come up", exitCode: null, signal: null, durationMs: 0 },
+          terminate: true,
+        };
+      }
+
+      if (!ctx.hasUI) {
+        try { child.kill(); } catch { /* best-effort */ }
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Login handoff required but no interactive UI is available in this run mode.",
+              `Reason: ${reason}`,
+              "The login browser has been closed. Stop this task now and ask the operator to rerun it interactively so the login can be completed.",
+            ].join("\n"),
+          }],
+          details: { ok: false, command: "login-handoff", args: [executablePath, url], stdout: "", stderr: "no interactive UI", exitCode: null, signal: null, durationMs: 0 },
+          terminate: true,
+        };
+      }
+
+      ctx.ui.notify(`Login handoff needed: ${reason}`, "warning");
+      ctx.ui.setStatus("agent-browser-login-handoff", `⏸ ログイン待機中 — ${reason}`);
+      let choice: string | undefined;
+      try {
+        choice = await ctx.ui.select(
+          `Login required: ${reason}`,
+          ["Resume - I completed the login", "Abort this task"],
+        );
+      } finally {
+        ctx.ui.setStatus("agent-browser-login-handoff", undefined);
+      }
+
+      if (choice !== "Resume - I completed the login") {
+        try { child.kill(); } catch { /* best-effort */ }
+        return {
+          content: [{
+            type: "text",
+            text: "Human aborted the task during login handoff. Stop and report back; do not retry automatically.",
+          }],
+          details: { ok: false, command: "login-handoff", args: [executablePath, url], stdout: choice ?? "", stderr: "", exitCode: 1, signal: null, durationMs: 0 },
+          terminate: true,
+        };
+      }
+
+      const attachArgs = ["--cdp", String(port), "--session", session, "open"];
+      const result = await runAgentBrowser(attachArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+
+      if (!result.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Login browser was confirmed by the human, but attaching agent-browser via --cdp failed. Do not assume the session is usable.",
+              `Command: ${result.command} ${result.args.map((a) => JSON.stringify(a)).join(" ")}`,
+            ].join("\n"),
+          }],
+          details: { ...result, artifactPaths: [] },
+          terminate: true,
+        };
+      }
+
+      await writeSessionState(ctx.cwd, session, { headed: true, lastUrl: url });
+
+      return {
+        content: [{
+          type: "text",
+          text: [
+            "Login handoff complete and agent-browser is now attached to the human's authenticated Chrome session.",
+            `Session: ${session === DEFAULT_SESSION_KEY ? "(default)" : session}`,
+            "Take a fresh agent_browser_snapshot before continuing.",
+          ].join("\n"),
+        }],
+        details: { ...result, artifactPaths: [] },
+        terminate: true,
+      };
+    },
+  });
+
   pi.registerTool({
     name: "agent_browser_commit",
     label: "Agent Browser Commit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@53able/pi-agent-browser",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Typed Pi tools for browser automation, rendered-page context extraction, screenshots, and saved session state via agent-browser.",
   "type": "module",
   "license": "MIT",

package/skills/agent-browser/SKILL.md

@@ -36,6 +36,32 @@ Two tools exist so the agent stops and hands control back to a human instead of
 
 `agent_browser_read` and `agent_browser_snapshot` also run a lightweight heuristic scan for 2FA/CAPTCHA/identity-verification keywords and prepend a warning to their output when detected — treat that warning as a signal to call `agent_browser_handoff` next, not as a blocker by itself.
 
+### If the human can't find the browser window
+
+`agent_browser_open` records whether each named session was launched with `headed: true`. When `agent_browser_handoff` runs for a session that was not opened headed, it automatically prepends a warning naming the session and the exact `agent_browser_open` arguments (including the last known URL) needed to reopen it visibly, instead of leaving the human to guess. Prefer `headed: true` from the start for any task that might hit a login, 2FA, CAPTCHA, or identity-verification step — a human can only intervene through `agent_browser_handoff` if a visible window already exists. Note that some verification challenges are single-use or session-bound, so reopening may require restarting the login flow rather than resuming mid-challenge.
+
+### For interactive login flows (Google, OAuth, and similar)
+
+`agent_browser_login_handoff` solves a specific problem: Google and similar OAuth providers block sign-in when `agent-browser open` is used, because agent-browser attaches a remote debugging protocol (CDP) session the instant Chrome launches, and Google detects this automation marker and rejects the login attempt regardless of profile, cookies, or executable.
+
+This tool spawns a plain, un-instrumented Chrome process (not through `agent-browser open`) with a remote debugging port and a dedicated persistent profile, so no CDP client is attached while the human logs in. Chrome behaves like an ordinary browser to Google during sign-in. Only after the human confirms login is complete does the tool attach `agent-browser` via CDP to that already-authenticated browser for all subsequent automated snapshot, read, and click operations.
+
+**Important:** this is an architecture fix, not detection evasion. The tool does not hide webdriver flags or automation fingerprints — it simply avoids having a CDP session attached during the interactive login moment itself.
+
+Use `agent_browser_login_handoff` instead of `agent_browser_open` for any task expected to hit an interactive Google, OAuth, or similar sign-in flow. Never try to push through such a login via `agent_browser_open` + click/fill — that's the exact failure mode this tool exists to avoid.
+
+Example call:
+
+```json
+{
+  "url": "https://myapp.com/login",
+  "session": "google-oauth-flow",
+  "reason": "User must complete Google OAuth sign-in for app access"
+}
+```
+
+After the human confirms login is complete, subsequent `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, and other calls with the same `session` name will reuse the authenticated browser state and operate normally. The session is marked as headed in the session-state tracking, so later calls to `agent_browser_handoff` on the same session won't false-flag it as headless.
+
 ## Common examples
 
 Read a public page: