@53able/pi-agent-browser 0.3.0 → 0.4.1

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,14 +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 プロセスを起動して人間が正常にログインできるようにし、ログイン成功後にその認証済みCookie/storageを取り出して、新しい通常の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`は、各セッションが`headed: true`で起動されたかどうかも記録します。`agent_browser_handoff`が、headedで開かれていないセッションに対して呼ばれた場合、人間への警告に加えて、可視ウィンドウを開き直すための`agent_browser_open`の引数（セッション名、`headed: true`、`restore: true`、最後に開いていたURL）をそのまま提示します — どのコマンドを打ち直せばよいか推測する必要はありません。ログインや2FA、CAPTCHA、本人確認に差し掛かる可能性があるタスクでは、最初から`headed: true`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。
+`agent_browser_open`は、各セッションが`headed: true`で起動されたかどうかを記録します。`agent_browser_handoff`が、headedで開かれていないセッションに対して呼ばれた場合、人間への警告に加えて、可視ウィンドウを開き直すための`agent_browser_open`の引数（セッション名、`headed: true`、`restore: true`、最後に開いていたURL）をそのまま提示します — どのコマンドを打ち直せばよいか推測する必要はありません。ログインや2FA、CAPTCHA、本人確認に差し掛かる可能性があるタスクでは、最初から`headed: true`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。`agent_browser_login_handoff`が作るセッションは常にheadlessです（使い捨てのログイン用ブラウザではなく、新規セッションのため）。見たい場合は`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,14 +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 captures the authenticated cookies/storage and loads them into a fresh, ordinary agent-browser session 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` also remembers 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.
+`agent_browser_open` remembers 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. `agent_browser_login_handoff` always leaves the resulting session headless (it's a fresh session, not the disposable login browser), so reopen with `headed: true` if you need to see it.
 
 ## Troubleshooting
 

package/index.ts

@@ -4,6 +4,7 @@ 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;
@@ -200,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 'この投稿を完全に削除する'." }),
@@ -235,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());
@@ -696,6 +761,195 @@ 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. Once the human confirms login is complete, captures the authenticated cookies/storage and loads them into a fresh, ordinary agent-browser session. 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,
+        };
+      }
+
+      // Do NOT keep driving the live --cdp connection as the ongoing session: `agent-browser
+      // --cdp <port> ... open` (no url) opens a brand-new blank page/context in the connected
+      // browser rather than reusing the tab the human actually authenticated in, leaving the
+      // "attached" session on about:blank with no auth. Instead follow agent-browser's own
+      // documented pattern for this exact scenario (see its authentication.md "Import Auth
+      // from Your Browser" / "Two-Factor Authentication" sections): extract the authenticated
+      // cookies/storage from the login browser via `state save`, close the disposable login
+      // browser, then load that state into a normal, freshly-launched session via `--state`.
+      const authStatePath = join(profileDir, "auth-state.json");
+      const saveArgs = ["--cdp", String(port), "state", "save", authStatePath];
+      const saveResult = await runAgentBrowser(saveArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+      try { child.kill(); } catch { /* best-effort; the login browser is disposable once we've extracted its auth state */ }
+
+      if (!saveResult.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Login browser was confirmed by the human, but extracting its authenticated state via `state save` failed. Do not assume the session is usable.",
+              `Command: ${saveResult.command} ${saveResult.args.map((a) => JSON.stringify(a)).join(" ")}`,
+            ].join("\n"),
+          }],
+          details: { ...saveResult, artifactPaths: [] },
+          terminate: true,
+        };
+      }
+
+      const loadArgs = ["--session", session, "--restore", "--state", authStatePath, "open", url];
+      const result = await runAgentBrowser(loadArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+
+      if (!result.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Login state was captured from the human's browser, but loading it into a fresh agent-browser session 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: false, lastUrl: url });
+
+      return {
+        content: [{
+          type: "text",
+          text: [
+            "Login handoff complete: the human's authenticated cookies/storage were captured and loaded into a fresh agent-browser 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.3.0",
+  "version": "0.4.1",
   "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

@@ -40,6 +40,28 @@ Two tools exist so the agent stops and hands control back to a human instead of
 
 `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. After the human confirms login is complete, the tool captures the authenticated cookies and storage from that browser (`agent-browser state save`), closes the disposable login browser, and loads that captured state into a fresh, ordinary agent-browser session (`agent-browser state load`) for all subsequent automated snapshot, read, and click operations. (An earlier version tried to keep driving the login browser live over CDP; that opened a disconnected blank tab instead of reusing the authenticated one, so state capture-and-load is used instead.)
+
+**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. This new session runs headless by default (it is a fresh agent-browser session, not the disposable login browser, which is closed once its auth state is captured); reopen it with `headed: true` if you need to see it.
+
 ## Common examples
 
 Read a public page: