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

package/README.ja-JP.md

@@ -164,12 +164,12 @@ https://example.com をブラウザ経由で読み、outputs/browser/example.md
 すべての操作を無人で任せるべきではありません。適切なタイミングで人間に操作を戻すためのツールが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` ではなく必ずこちらを使ってください。
+- **インタラクティブなログイン** — `agent_browser_login_handoff` は、Google や OAuth など多くのプロバイダで sign-in がブロックされる問題を解決します。これは、agent-browser が使われた時点でオートメーション検出が起きるため、ログイン中に拒否されるというもの。このツールは CDP が接続されていない無人 Chrome プロセスを起動して人間が正常にログインできるようにし、ログイン成功後に、**そのブラウザはセッションに結合され、閉じられるまで生存し続けます**—リモートデバッグポートが開いたまま表示されます。Google や OAuth の sign-in フローが期待されるタスクでは、`agent_browser_open` ではなく必ずこちらを使ってください。
 - **Commit前の停止** — `agent_browser_commit` は、決済・削除・投稿・送信といった「やり直しのきかない操作」専用の確認ゲートです。証跡を保存し、クリックの前に必ず人間の明示的な確認を求め、承認されない限りクリックは実行されません。対話的なUIが利用できない場合は、クリックせずにそのまま拒否します。こうした操作の最終確認クリックには `agent_browser_click` ではなく必ずこちらを使ってください。
 
 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`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。
+`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`が作るセッションは`headed: true`として記録されます（ログインブラウザが表示・生存し続けるため、開き直す必要はありません）。
 
 ## Troubleshooting
 

package/README.md

@@ -164,12 +164,12 @@ Clear all saved states only when intentionally resetting everything:
 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.
+- **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. After login succeeds, the still-running browser is live-attached to the named session and **kept open as the permanent backing browser**—it remains visible on screen with an open remote-debugging port until closed with `agent_browser_close`. 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.
 
 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.
+`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` records the resulting session as `headed: true` (since the login browser is visible and running); you don't need to reopen it to see it.
 
 ## Troubleshooting
 

package/index.ts

@@ -43,7 +43,9 @@ 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 };
+type SessionState = { headed: boolean; lastUrl?: string; loginBrowserPid?: number; loginDebugPort?: number; updatedAt: string };
+
+type SessionStatePatch = Partial<Omit<SessionState, "updatedAt">> & { clearLoginBrowserPid?: boolean };
 
 function sessionKey(params: JsonObject): string {
   return typeof params.session === "string" && params.session.trim() ? params.session.trim() : DEFAULT_SESSION_KEY;
@@ -58,7 +60,7 @@ async function readSessionStates(cwd: string): Promise<Record<string, SessionSta
   }
 }
 
-async function writeSessionState(cwd: string, session: string, patch: Partial<Omit<SessionState, "updatedAt">>): Promise<void> {
+async function writeSessionState(cwd: string, session: string, patch: SessionStatePatch): Promise<void> {
   const dir = join(cwd, SESSION_STATE_DIR);
   await mkdir(dir, { recursive: true });
   const states = await readSessionStates(cwd);
@@ -66,6 +68,8 @@ async function writeSessionState(cwd: string, session: string, patch: Partial<Om
   states[session] = {
     headed: patch.headed ?? previous?.headed ?? false,
     lastUrl: patch.lastUrl ?? previous?.lastUrl,
+    loginBrowserPid: patch.clearLoginBrowserPid ? undefined : (patch.loginBrowserPid ?? previous?.loginBrowserPid),
+    loginDebugPort: patch.clearLoginBrowserPid ? undefined : (patch.loginDebugPort ?? previous?.loginDebugPort),
     updatedAt: new Date().toISOString(),
   };
   await writeFile(join(dir, SESSION_STATE_FILE), JSON.stringify(states, null, 2), "utf8");
@@ -266,6 +270,11 @@ async function findFreePort(): Promise<number> {
   });
 }
 
+function killPidBestEffort(pid?: number): void {
+  if (!pid) return;
+  try { process.kill(pid); } catch { /* already gone / not ours */ }
+}
+
 function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolveDelay) => {
     if (signal?.aborted) {
@@ -673,12 +682,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
     parameters: CloseSchema,
     async execute(_id, rawParams, signal, onUpdate, ctx) {
       const params = rawParams as JsonObject;
+      const states = await readSessionStates(ctx.cwd);
       const args: string[] = [];
       pushCommonArgs(args, params);
       args.push("close");
       if (params.all === true) args.push("--all");
       pushExtraArgs(args, params);
       const result = await runAgentBrowser(args, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+
+      // agent-browser close only detaches an externally-spawned login Chrome; kill the tracked pid(s) ourselves.
+      if (params.all === true) {
+        for (const [name, st] of Object.entries(states)) {
+          if (!st.loginBrowserPid) continue;
+          killPidBestEffort(st.loginBrowserPid);
+          await writeSessionState(ctx.cwd, name, { clearLoginBrowserPid: true });
+        }
+      } else {
+        const session = sessionKey(params);
+        if (states[session]?.loginBrowserPid) {
+          killPidBestEffort(states[session]?.loginBrowserPid);
+          await writeSessionState(ctx.cwd, session, { clearLoginBrowserPid: true });
+        }
+      }
       return buildTextResult(result);
     },
   });
@@ -764,12 +789,13 @@ 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.",
+    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, live-attaches that still-running browser to the named agent-browser session and keeps it open as the session's backing browser (no cookie/state export). 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.",
+      "On success the login browser stays open and IS the session's live backing browser; drive it with the normal agent_browser_* tools by session name, and call agent_browser_close when done to shut it down (it holds an open remote-debugging port until then).",
       "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,
@@ -805,6 +831,10 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
       const port = await findFreePort();
 
+      // Supersede an older live login browser for this session so re-running doesn't leak it.
+      const prior = (await readSessionStates(ctx.cwd))[session];
+      killPidBestEffort(prior?.loginBrowserPid);
+
       let spawnError: Error | undefined;
       const child = spawn(executablePath, [
         `--remote-debugging-port=${port}`,
@@ -889,15 +919,27 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         };
       }
 
-      const attachArgs = ["--cdp", String(port), "--session", session, "open"];
-      const result = await runAgentBrowser(attachArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+      // Human confirmed login. Bind the STILL-RUNNING login Chrome into the named session
+      // via CDP, WITHOUT navigating (snapshot binds + verifies in one shot; open would
+      // re-navigate away from the authenticated landing page). Keep the browser ALIVE —
+      // it is now the backing browser this session drives from here on.
+
+      // Defensive: surface multi-tab situations (OAuth popups) without failing.
+      const tabArgs = ["--cdp", String(port), "tab", "list"];
+      const tabResult = await runAgentBrowser(tabArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+
+      const bindArgs = ["--session", session, "--cdp", String(port), "snapshot"];
+      const result = await runAgentBrowser(bindArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
 
       if (!result.ok) {
+        // Bind failed: the login browser is still alive but unusable by the session.
+        // Best-effort kill so we don't leak a debug-port Chrome, and report.
+        killPidBestEffort(child.pid);
         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.",
+              "Human confirmed login, but attaching the live browser to the agent-browser session failed. Do not assume the session is usable.",
               `Command: ${result.command} ${result.args.map((a) => JSON.stringify(a)).join(" ")}`,
             ].join("\n"),
           }],
@@ -906,16 +948,25 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         };
       }
 
-      await writeSessionState(ctx.cwd, session, { headed: true, lastUrl: url });
+      // Persist backing-browser identity + the fact that a VISIBLE window exists (headed:true).
+      await writeSessionState(ctx.cwd, session, {
+        headed: true,
+        lastUrl: url,
+        loginBrowserPid: child.pid,
+        loginDebugPort: port,
+      });
 
+      const multiTab = /\bt2\b/.test(tabResult.stdout) || (tabResult.stdout.match(/\[t\d+\]/g)?.length ?? 0) > 1;
       return {
         content: [{
           type: "text",
           text: [
-            "Login handoff complete and agent-browser is now attached to the human's authenticated Chrome session.",
+            "Login handoff complete: the browser you signed in with is now live-attached to the agent-browser session and stays open.",
             `Session: ${session === DEFAULT_SESSION_KEY ? "(default)" : session}`,
-            "Take a fresh agent_browser_snapshot before continuing.",
-          ].join("\n"),
+            multiTab ? `Note: multiple tabs are open — verify the active tab before acting:\n${tabResult.stdout.trim()}` : undefined,
+            "The session drives this real browser window directly. Take a fresh agent_browser_snapshot before continuing.",
+            "This login browser has an open remote-debugging port and will stay open until agent_browser_close is called for this session (or the window is closed manually).",
+          ].filter(Boolean).join("\n"),
         }],
         details: { ...result, artifactPaths: [] },
         terminate: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@53able/pi-agent-browser",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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

@@ -44,7 +44,7 @@ Two tools exist so the agent stops and hands control back to a human instead of
 
 `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.
+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 still-running login browser is **live-attached to the named agent-browser session** (via `agent-browser --session <name> --cdp <port> snapshot`, not `open`, to avoid navigating away from the authenticated page) and **kept open as the permanent backing browser for that session**. All subsequent automated snapshot, read, click, and other operations continue to work against it via `--session <name>` alone, unchanged.
 
 **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.
 
@@ -60,7 +60,11 @@ Example call:
 }
 ```
 
-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.
+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 and operate normally. **The login browser window remains visible and open indefinitely** — this is a real, user-visible Chrome window with an open remote-debugging port on `127.0.0.1` that any local process can access. The session is recorded as `headed: true` (since the authenticated browser is still running).
+
+**Security note:** The login browser's `--remote-debugging-port` remains open on localhost for as long as the session is alive. This gives any local process full browser control — the same caveat agent-browser's own docs give about `--remote-debugging-port`. Call `agent_browser_close` when done with a session that went through login handoff, rather than leaving it open indefinitely. `agent_browser_close` will terminate the tracked login Chrome process and clean up its debugging port.
+
+Re-running `agent_browser_login_handoff` for the same session name will terminate any previous live login browser for that session before spawning a new one.
 
 ## Common examples