@53able/pi-agent-browser 0.6.0 → 0.7.0

package/README.ja-JP.md

@@ -18,7 +18,7 @@ Pi が Web ページを開き、rendered context を抽出し、ログイン状
 ## Requirements
 
 - package support 付きの Pi / Feynman runtime
-- [`agent-browser`](https://github.com/vercel-labs/agent-browser) が `PATH` 上にあること
+- [`agent-browser`](https://github.com/vercel-labs/agent-browser) 0.40.0 以降が `PATH` 上にあること
 - `agent-browser install` で Chrome for Testing が入っていること
 
 確認:
@@ -164,7 +164,7 @@ 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 プロセスを起動して人間が正常にログインできるようにし、ログイン成功後に、**そのブラウザはセッションに結合され、閉じられるまで生存し続けます**—リモートデバッグポートが開いたまま表示されます。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` ではなく必ずこちらを使ってください。エージェントは、そのセッションが不要になった時点で速やかに `agent_browser_close` を呼ぶべきで、デバッグポートを無期限に開けたままにするべきではありません。
 - **Commit前の停止** — `agent_browser_commit` は、決済・削除・投稿・送信といった「やり直しのきかない操作」専用の確認ゲートです。証跡を保存し、クリックの前に必ず人間の明示的な確認を求め、承認されない限りクリックは実行されません。対話的なUIが利用できない場合は、クリックせずにそのまま拒否します。こうした操作の最終確認クリックには `agent_browser_click` ではなく必ずこちらを使ってください。
 
 3つのツールすべてが対話的なセッション（TUI、またはUI対応のRPC）を必要とします。無人・headless実行では、黙って進めるのではなく拒否します。

package/README.md

@@ -18,7 +18,7 @@ Use this package when Pi needs to operate real web pages, extract rendered conte
 ## Requirements
 
 - Pi / Feynman runtime with package support
-- [`agent-browser`](https://github.com/vercel-labs/agent-browser) installed and available on `PATH`
+- [`agent-browser`](https://github.com/vercel-labs/agent-browser) 0.40.0 or later installed and available on `PATH`
 - Chrome for Testing installed through `agent-browser install`
 
 Check your local setup:
@@ -164,7 +164,7 @@ 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. 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.
+- **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. Agents should call `agent_browser_close` as soon as the session is no longer needed, rather than leaving the debugging port open indefinitely.
 - **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.

package/index.ts

@@ -9,6 +9,7 @@ import { createServer } from "node:net";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_PREVIEW_CHARS = 12_000;
 const DEFAULT_ARTIFACT_DIR = "outputs/browser";
+const MIN_AGENT_BROWSER_VERSION = [0, 40, 0];
 
 // Heuristics for content that signals a human-only checkpoint (2FA, CAPTCHA, identity
 // verification). These are advisory only — read/snapshot stay non-destructive, so we
@@ -232,7 +233,6 @@ const DoctorSchema = Type.Object({
 async function findAgentBrowserBin(): Promise<string> {
   if (process.env.AGENT_BROWSER_BIN) return process.env.AGENT_BROWSER_BIN;
   const candidates = [
-    "/Users/tadano-go/.local/bin/agent-browser",
     join(process.env.HOME ?? "", ".local/bin/agent-browser"),
     "agent-browser",
   ];
@@ -652,6 +652,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
     promptGuidelines: [
       "Use operation=list before destructive clear/clean operations unless the user explicitly asks to clear everything.",
       "Use session + restore on agent_browser_open for automatic state persistence; use state save/load for explicit files.",
+      "state load / restore only writes storage while the page is on the saved origin; origins that redirect elsewhere are skipped and listed in the output. Open the target origin first if its storage must apply.",
       "Do not clear all saved states unless the user clearly asks for global cleanup.",
     ],
     parameters: StateSchema,
@@ -790,7 +791,9 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
           ].filter(Boolean).join("\n"),
         }],
         details: { ok: resumed, command: "handoff", args: [category], stdout: choice ?? "", stderr: "", exitCode: resumed ? 0 : 1, signal: null, durationMs: 0, artifactPaths: artifacts },
-        terminate: true,
+        // Only force a stop-and-wait turn on abort -- a genuine dead end needing a human/
+        // operator decision. On resume the checkpoint is cleared, so continue immediately.
+        ...(resumed ? {} : { terminate: true }),
       };
     },
   });
@@ -804,7 +807,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
       "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).",
+      "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.",
+      "Once the current task no longer needs this session (no further browser-driven steps planned), call agent_browser_close for it before finishing — it holds an open remote-debugging port on localhost until closed, and leaving it open is a real, unnecessary security exposure. Only skip closing it when the user's task explicitly spans multiple steps/turns that will keep reusing this same session.",
       "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,
@@ -937,7 +941,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
       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 bindArgs = ["--session", session, "--cdp", String(port), "--pin-tab", "snapshot"];
       const result = await runAgentBrowser(bindArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
 
       if (!result.ok) {
@@ -993,7 +997,9 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
           ].filter(Boolean).join("\n"),
         }],
         details: { ...result, artifactPaths: [] },
-        terminate: true,
+        // No terminate:true here (unlike the failure/abort/no-UI paths above): login
+        // succeeded and the session is immediately usable, so the agent should continue
+        // the original task right away instead of forcing a stop-and-wait-for-the-user turn.
       };
     },
   });
@@ -1086,6 +1092,15 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
       const result = await runAgentBrowser(args, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
       const textResult = buildTextResult(result);
 
+      const versionResult = await runAgentBrowser(["--version"], { signal, cwd: ctx.cwd });
+      const version = versionResult.stdout.match(/(\d+)\.(\d+)\.(\d+)/)?.slice(1).map(Number);
+      if (version) {
+        const diff = version.map((n, i) => n - MIN_AGENT_BROWSER_VERSION[i]).find((d) => d !== 0) ?? 0;
+        if (diff < 0) {
+          textResult.content[0].text += `\nagent-browser ${version.join(".")} is older than ${MIN_AGENT_BROWSER_VERSION.join(".")}, the minimum supported version. Run \`npm install -g agent-browser@latest\`.`;
+        }
+      }
+
       const states = await readSessionStates(ctx.cwd);
       const liveBrowsers: { session: string; pid: number; port: number | undefined; lastUrl?: string }[] = [];
       for (const [session, state] of Object.entries(states)) {

package/package.json

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

@@ -25,6 +25,7 @@ Use the `agent_browser_*` tools instead of raw `bash` commands when browser stat
 - Prefer `agent_browser_read` over screenshots for textual evidence.
 - Use `agent_browser_eval` only when read/snapshot cannot expose the required state.
 - To keep login state automatically, open with a stable `session` and `restore: true`.
+- State load/restore only writes storage while the page is on the saved origin; origins that redirect elsewhere are skipped and listed. Open the target origin first if its storage must apply.
 - Before clearing state, list saved states with `agent_browser_state` unless the user explicitly asks for broad cleanup.
 
 ## Human handoff and commit gates
@@ -36,6 +37,8 @@ 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.
 
+On resume, `agent_browser_handoff` does not force the agent to stop and wait for a new user turn — the checkpoint is cleared, so continue the original task right away (after a fresh `agent_browser_snapshot`). Only abort ends the turn, since that's a genuine dead end needing a human/operator decision.
+
 ### 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.
@@ -60,16 +63,20 @@ 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 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).
+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). The session is pinned to the login tab: if that tab is closed, later calls fail with `tab_gone` instead of silently driving another tab — re-run `agent_browser_login_handoff` to recover.
 
 **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.
 
+Agents should call `agent_browser_close` for the session as soon as the current task no longer needs it (no further browser-driven steps planned) — don't wait for the user to ask. Only leave it open when the task explicitly spans multiple steps or turns that will keep reusing the same session.
+
 Run `agent_browser_doctor` to see which sessions still have live login browsers open. It reports any that are still running (session name, process ID, debugging port, and last known URL) with a reminder to call `agent_browser_close`. Stale tracking entries for processes no longer running are cleaned up silently with no user notification.
 
 `agent_browser_login_handoff` also surfaces this automatically: its success message names any *other* sessions that still have a live login browser open (session name and process ID), so you don't have to run `agent_browser_doctor` separately just to notice one was left open.
 
 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.
 
+On a successful login, the tool does not force the agent to stop and wait for a new user turn — the session is immediately usable, so continue the original task right away (after a fresh `agent_browser_snapshot`). Only the failure/abort/no-UI paths end the turn, since those genuinely need a human or operator decision before anything else can happen.
+
 ## Common examples
 
 Read a public page: