Complete AgentTab credential and task lifecycle

CHANGELOG.md

@@ -1,9 +1,12 @@
 # Changelog
 
 ## Unreleased
-- Replaced the Chrome Bridge v1 runtime with the AgentTab 2.0 release candidate: a Rust production host over OS-native local IPC, seven task-scoped Standard methods, explicit resumable capabilities, a developer-only eighth method, TypeScript and Python SDKs, MCP and OMP adapters, a transactional installer, and a minimal extension. Consequential controls now use a two-party Commit flow: `browser_act` stages an exact effect, the popup approves the durable review record without executing it, and the requesting task must consume its private one-use token through `browser_commit`.
+- Replaced the Chrome Bridge v1 runtime with the AgentTab 2.0 release candidate: a Rust production host over OS-native local IPC, nine task-scoped Standard methods, explicit resumable capabilities, a developer-only tenth method, TypeScript and Python SDKs, MCP and OMP adapters, a transactional installer, and a minimal extension. Consequential controls now use a two-party Commit flow: `browser_act` stages an exact effect, the popup approves the durable review record without executing it, and the requesting task must consume its private one-use token through `browser_commit`.
+- Added explicit `browser_finish` lifecycle finalization across Core RPC, the extension, TypeScript and Python SDKs, CLI, MCP, OMP, and Pi. Automatic cleanup tracks tab provenance, closes task-created tabs, retains adopted tabs, ungroups retained tabs, and releases ownership; popup policy can require confirmation or retain all tabs, while active handoff, Commit review, and in-flight work defer cleanup without destroying resumability.
 - Fixed OMP adapter compatibility with providers that reject top-level union tool schemas. `browser_open` and `browser_snapshot` now expose provider-compatible object schemas while retaining strict runtime validation for their mode-specific parameters.
 - Added a focus-safe GPT-Control browser driver backed by AgentTab task ownership and durable resume capabilities. It creates background task tabs, fills and sends prompts through Standard actions and Commit review, uploads through a bounded file-input selector, captures the latest assistant message without activating Chrome, persists session state owner-only, and closes the underlying task explicitly.
+- Added a disabled-by-default, host-managed 1Password credential broker. `browser_credentials` derives the current origin from task-owned host state, accepts at most three matching Login items and attempts, and uses short-lived one-use tokens to fill username, password, or one-time-code refs without exposing values through Core RPC, MCP, OMP, Pi, responses, or audit output. More than three matches, provider failures, exhausted attempts, and unsupported verification return `needs_user`. The extension's private fill path blocks capture before injecting selected values and never submits the form.
+- Fixed credential-broker activation against upgraded local state and GUI-launched browser hosts. Legacy `staged_commits` columns are migrated before dependent indexes are created, and policy can pin an absolute 1Password CLI executable when the browser process does not inherit the user's shell `PATH`.
 - Added task-owned background window creation to Standard `browser_open` through `placement: "new_window"`. It is operation-specific rather than a general window-control grant: only an otherwise empty task can request it, the extension creates an unfocused normal window, `background: false` is rejected, ownership is derived from persisted task state, and a failed visible group grant removes the new tab. Focus, state changes, and closure of unrelated windows remain unavailable.
 - Added explicit restricted-origin routing for task tabs. `browser_open` and `browser_tabs` now report `automation_route: "full" | "tab_only"`; Chrome system pages, extension pages, DevTools, and the Chrome Web Store retain task-owned explicit navigation, reload, close, and bounded waits, while page inspection, interaction, and raw CDP fail before execution with the stable `browser_restricted_origin` / `not_started` result and non-retry recovery. History movement remains available without managed origin constraints and fails closed when constraints are configured because Chrome does not expose its destination for pre-navigation authorization.
 - Migrated the Python MCP server to SDK 2.0 and the `2026-07-28` protocol while preserving legacy stdio compatibility, scoped tool registration, resources, annotations, per-request HTTP bridge tokens, and streamable HTTP configuration.

README.md

@@ -6,7 +6,7 @@
 
 > Give an agent a tab, not the keys to your browser.
 
-AgentTab lets an agent work in your existing signed-in Chrome profile without giving it unrestricted control of the profile. Each connection receives a task-owned browser workspace. The agent can create tabs, inspect and act in those tabs, wait for page state, and ask for help. Passwords, passkeys, 2FA, CAPTCHA, payment secrets, and other human-only input belong to **Your Turn**. Recognizable consequential actions are staged for **Commit** instead of being performed immediately.
+AgentTab lets an agent work in your existing signed-in Chrome profile without giving it unrestricted control of the profile. Each connection receives a task-owned browser workspace. The agent can create tabs, inspect and act in those tabs, wait for page state, and ask for help. A disabled-by-default 1Password broker can fill a matching login or one-time code without exposing its value to the agent; passkeys, security keys, CAPTCHA, payment secrets, account recovery, and unsupported verification remain **Your Turn**. Recognizable consequential actions are staged for **Commit** instead of being performed immediately.
 
 ## Release status
 
@@ -24,9 +24,10 @@ The command has no path, token, or shell-specific argument and is suitable for P
 
 1. An agent calls `browser_open` with `mode: "create"`. AgentTab creates a background tab for that task and returns its task, tab, window, page-revision, and automation-route identifiers. `placement: "new_window"` may create the task's first tab in a separate unfocused normal window.
 2. On a normal web origin, the agent calls `browser_snapshot`, works from revisioned accessibility references, then calls `browser_act` with the expected page revision. It cannot act on unrelated tabs.
-3. If a site requires human-only input, the agent calls `browser_handoff`. AgentTab focuses that tab, pauses automation, and blocks browser observation until the declared completion condition or **I'm done**.
+3. If managed policy enables 1Password and an ordinary sign-in page has at most three origin-matching Login items, the agent can request a short-lived opaque token and ask the host to fill named field refs. Credential values travel only from `op` to the host and extension, never through Core RPC or the adapter. Every other human-only input uses `browser_handoff`, which focuses that tab, pauses automation, and blocks browser observation until the declared completion condition or **I'm done**.
 4. If AgentTab recognizes a send, publish, purchase, delete, upload, authorization, or permission-grant control, `browser_act` can return `commit_required`. The extension shows the staged effect in its popup. A human must approve it there before the agent can call `browser_commit` with the one-use staged token.
 5. The task can list only its own tabs with `browser_tabs`. A separate client gets a separate task unless it proves its durable resume capability.
+6. When browser work is complete, the agent calls `browser_finish`. Automatic cleanup closes tabs created by the task, preserves tabs adopted from the user's existing browser state, ungroups retained tabs, and releases task ownership. The popup setting can instead require confirmation or retain every tab.
 
 Chrome does not expose page scripting or debugger access on browser-restricted origins such as `chrome://`, `chrome-extension://`, `devtools://`, and the Chrome Web Store. AgentTab reports these task tabs with `automation_route: "tab_only"`. Explicit navigation, reload, close, load or URL waits, and human-only `browser_handoff` remain available. History movement is also available when managed origin constraints are absent; with constraints, AgentTab rejects it because Chrome does not expose the destination for authorization before navigation. Download waits require the `full` route because exact task-tab attribution comes from tab-scoped debugger events, not browser-global download state. Page snapshots, element actions, page-content waits, and raw Developer-mode CDP fail immediately with `browser_restricted_origin` and `outcome: "not_started"` before AgentTab attempts the blocked route. Use a focus-safe OS accessibility driver bound to the exact browser window when native UI work is required.
 
@@ -41,7 +42,7 @@ Commit is a two-party, best-effort semantic barrier, not proof that a page has n
 
 ## Tool surface
 
-Standard mode exposes exactly seven MCP tools:
+Standard mode exposes exactly nine tools:
 
 | Tool | Purpose |
 |---|---|
@@ -52,6 +53,8 @@ Standard mode exposes exactly seven MCP tools:
 | `browser_tabs` | List only tabs owned by the current task, including each tab's automation route. |
 | `browser_handoff` | Give the user control for human-only input. |
 | `browser_commit` | Execute one staged consequential action. |
+| `browser_credentials` | Prepare and fill an origin-matching 1Password login through opaque, short-lived host tokens when managed policy explicitly enables it. |
+| `browser_finish` | Finish the task, apply its cleanup policy, return closed and retained tab receipts, and release ownership. |
 
 Developer mode adds one tool, `browser_developer`. It is absent from Standard discovery. It requires both the persistent Developer mode control in the AgentTab popup and `AGENTTAB_DEVELOPER=1` in the adapter environment. Treat it as an explicit expansion of the normal boundary.
 

docs/adr/0001-agenttab-runtime.md

@@ -26,7 +26,7 @@ A task workspace is visible in Chrome. Task-owned tabs are grouped for display,
 
 ### Your Turn
 
-**Your Turn** is the human-only input boundary. AgentTab MUST hand control to the user for passwords, passkeys, two-factor authentication, CAPTCHA, payment secrets, and other input that automation must not observe or synthesize.
+**Your Turn** is the human-only input boundary. AgentTab MUST hand control to the user for passkeys, security keys, CAPTCHA, payment secrets, account recovery, unsupported verification, and any credential workflow that returns `needs_user`. A disabled-by-default managed 1Password broker MAY fill an origin-matching Login item through the private host-to-extension path, but MUST NOT expose the value to an agent or submit the form.
 
 While any Your Turn handoff is active, AgentTab MUST enforce a global observation blackout across every task and client. The extension and host each fail closed. AgentTab MUST NOT capture human keystrokes. Handoff clears only after its declared completion condition or explicit Done, capture scrubbing, and host acknowledgement.
 
@@ -47,7 +47,7 @@ Task ownership is an execution and coordination boundary. It is not cookie, iden
 Standard mode MUST NOT expose:
 
 - raw cookies or browser storage
-- passwords, passkeys, payment secrets, or human-only input
+- credential values, saved-item lists, passkeys, payment secrets, or human-only input; an explicitly enabled managed broker MAY fill one origin-matching Login item without returning its value
 - arbitrary JavaScript execution
 - raw Chrome DevTools Protocol access
 - coordinate-based actions
@@ -80,7 +80,7 @@ TCP and bearer-token access are not Standard transport. They exist only behind t
 
 AgentTab Core RPC and the host-to-extension native protocol are separately versioned. They MUST NOT silently downgrade across an incompatible version.
 
-MCP, OMP, CLI, TypeScript, and Python are adapters over Core RPC. They are not alternate hosts. The public Standard surface has exactly seven tools:
+MCP, OMP, CLI, TypeScript, and Python are adapters over Core RPC. They are not alternate hosts. The public Standard surface has exactly nine tools:
 
 1. `browser_open`
 2. `browser_snapshot`
@@ -89,8 +89,14 @@ MCP, OMP, CLI, TypeScript, and Python are adapters over Core RPC. They are not a
 5. `browser_tabs`
 6. `browser_handoff`
 7. `browser_commit`
+8. `browser_credentials`
+9. `browser_finish`
 
-`browser_developer` is the eighth tool and is absent unless Developer mode is enabled.
+`browser_credentials` is disabled by managed policy unless explicitly enabled. It MUST derive the page origin and task ownership in the host, enforce a candidate and attempt limit no greater than three, use one-use short-lived tokens, and keep credential values out of Core RPC, adapters, responses, and audit output.
+
+`browser_finish` applies the task's cleanup policy, closes task-created tabs unless retained, preserves adopted tabs by default, ungroups retained tabs, and releases task ownership. Active handoff, staged Commit review, or another in-flight task operation MUST defer finalization rather than destroy resumability.
+
+`browser_developer` is the tenth tool and is absent unless Developer mode is enabled.
 
 Core RPC schemas are normative. Unknown fields and methods fail closed. Every mutation requires a UUIDv7 `idempotency_key`. Existing-page mutations also require the authoritative `tab_id` and expected `page_revision`. `browser_commit` is bound by its staged record rather than caller-supplied tab or revision.
 

docs/commands.md

@@ -82,7 +82,7 @@ The extension layer is a diagnostic label around the status check. It does not r
 agenttab mcp
 ```
 
-Starts the AgentTab MCP server over stdin and stdout. It accepts no CLI options. The packaged `agenttab-mcp` binary starts the same server and also accepts no CLI options. Both expose seven Standard tools by default. Use the configured `agenttab` wrapper after a local installation, or the `agenttab-mcp` package binary only after that package is published.
+Starts the AgentTab MCP server over stdin and stdout. It accepts no CLI options. The packaged `agenttab-mcp` binary starts the same server and also accepts no CLI options. Both expose nine Standard tools by default. Use the configured `agenttab` wrapper after a local installation, or the `agenttab-mcp` package binary only after that package is published.
 
 The installer writes supported MCP client entries as an absolute local AgentTab wrapper plus `mcp`. For a manual configuration, use `agenttab mcp` only when that wrapper is on the client's `PATH`. The exact stdio configuration and protocol behavior are in [MCP](mcp.md).
 

docs/launch/chrome-web-store.md

@@ -28,11 +28,11 @@ An agent starts with a task workspace, not general access to every tab. AgentTab
 
 The runtime consists of one minimal MV3 extension, a local Rust host, and per-user operating-system-native IPC. The extension uses Chrome Native Messaging to reach the local host. Client adapters, including MCP, connect to the host through a user-owned Unix socket on macOS and Linux or a current-user named pipe on Windows. AgentTab has no cloud relay, remote browser session, telemetry service, or routine network control plane.
 
-Standard MCP access exposes exactly seven tools: `browser_open`, `browser_snapshot`, `browser_act`, `browser_wait`, `browser_tabs`, `browser_handoff`, and `browser_commit`. `browser_developer` is available only after a persistent, explicit Developer mode opt-in. Standard mode does not expose raw cookie, storage, arbitrary script, CDP, or network APIs.
+Standard MCP access exposes exactly nine tools: `browser_open`, `browser_snapshot`, `browser_act`, `browser_wait`, `browser_tabs`, `browser_handoff`, `browser_commit`, `browser_credentials`, and `browser_finish`. The finalization tool applies provenance-aware cleanup: task-created tabs close by default, adopted tabs are retained, retained tabs are ungrouped, and task ownership is released. The credential tool is inert unless managed policy explicitly enables the local 1Password broker, and it never returns a credential value. `browser_developer` is available only after a persistent, explicit Developer mode opt-in. Standard mode does not expose raw cookie, storage, arbitrary script, CDP, or network APIs.
 
 ### Human controls
 
-**Your Turn** is for passwords, passkeys, two-factor authentication, CAPTCHA, payment secrets, and other human-only input. During a handoff, AgentTab applies an observation blackout: standard capture and observation requests for every task return `needs_user`. The runtime clears the blackout only after the declared completion condition or explicit Done and its recovery checks. AgentTab does not capture human keystrokes.
+The optional local 1Password broker can fill one of at most three origin-matching Login items directly into a selected field without revealing the value to the agent. **Your Turn** remains the path for passkeys, security keys, CAPTCHA, payment secrets, account recovery, unsupported verification, or a broker result that needs the user. During a handoff, AgentTab applies an observation blackout: standard capture and observation requests for every task return `needs_user`. The runtime clears the blackout only after the declared completion condition or explicit Done and its recovery checks. AgentTab does not capture human keystrokes.
 
 **Commit** is a best-effort review barrier for recognizable sends, publishes, purchases, deletes, uploads, authorizations, and permission grants. Before acting, AgentTab prepares, classifies, and revalidates the target. A recognizable consequential action is staged with a preview, then requires approval in a human popup and the requesting agent's one-use token. The record expires after a short interval, cannot be replayed, and is invalidated if the page or target changes. Harmless actions proceed without Commit review. Commit reduces recognizable risk; it cannot prove that a page has no hidden external effect.
 
@@ -68,7 +68,7 @@ These notes are for a controlled reviewer package only. They are not public inst
 5. Demonstrate Your Turn with a harmless test page. Verify that observations from every task return `needs_user` during the handoff and that the agent resumes only after Done or the declared completion condition.
 6. Demonstrate Commit with a controlled test control labelled as a send, upload, delete, authorization, or permission action. Verify that no side effect occurs before the human popup approves the staged action with the requesting agent's one-use token. Do not use a real message, purchase, upload, deletion, or authorization.
 7. Demonstrate Pause and Resume, including that queued work does not start after Pause and that task status remains visible after recovery.
-8. Verify that Standard discovery exposes exactly the seven Standard tools and that the Developer-only tool is absent until the reviewer explicitly enables Developer mode.
+8. Verify that Standard discovery exposes exactly the nine Standard tools, that `browser_finish` retains an adopted tab while releasing its task ownership, that `browser_credentials` returns a disabled-policy result before any provider call, and that the Developer-only tool is absent until the reviewer explicitly enables Developer mode.
 
 ## Privacy declaration draft