magpie-gemini-web 0.5.1 → 0.5.3

package/LICENSE-AISTUDIO

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mag1cFall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -2,178 +2,165 @@
 
 [中文](README.md) | English
 
-Use Gemini on the web and Google AI Studio through your Google account in [Magpie](https://usemagpie.ai/). The plugin runs [gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) and [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API) backends on your machine, turning Google web interfaces into OpenAI-compatible APIs.
-
-The plugin provides two independent providers:
-- `gemini-web`: the Gemini web app; see [Getting started](#getting-started-gemini-web).
-- `ai-studio`: Google AI Studio, with native tool calling; see [Google AI Studio](#google-ai-studio-ai-studio).
+Use **Google AI Studio** and **Gemini on the web** through your Google account in [Magpie](https://usemagpie.ai/). The plugin runs [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API) and [gemini-web2api-go](https://github.com/zexadev/gemini-web2api-go) locally, turning Google web interfaces into OpenAI-compatible APIs.
 
 > **2026-10-16 update:** Full-price Google AI Pro accounts can now use `gemini-4-argon` directly in Antigravity, and can likewise be proxied directly with Magpie.
 
-## Getting started (Gemini Web)
-
-1. Install **magpie-gemini-web** from the Magpie plugin market.
-2. Sign in to Gemini Web and choose **一键配置本地 Gemini Web (one-click local setup, recommended)**. The plugin downloads this project's optimized backend, verifies its SHA-256 and starts it in the background. No Go installation or manual patching is needed.
-3. Copy your cookie when prompted. **Use a private / incognito window** (Firefox recommended):
-   1. In the private window, open <https://gemini.google.com/app> and sign in to the Google account you want to use.
-   2. Press F12 (⌥⌘I on macOS), switch to **Network** and reload the page.
-   3. Click any `gemini.google.com` request and go to **Headers** → **Request Headers**.
-   4. Copy the value of the `cookie` line and paste it into Magpie.
-   5. Close the private window. **Don't sign out**, because signing out invalidates the cookie.
-4. The plugin checks that the account works, then finishes signing in.
-
-> **Why a private window?** The backend refreshes this sign-in periodically to keep it alive. If it shares a session with the browser you normally use, Google revokes the session and your browser gets signed out of every Google service. A private window gives the backend a session of its own. Using a separate Google account for the backend is safer still.
-
-From then on, Magpie starts the backend automatically every time it launches. To add another account, run the one-click setup again.
-
-> Need a proxy to reach Google? The backend ignores `HTTP_PROXY`. Add the proxy in the proxy pool of the admin panel at `http://127.0.0.1:8083/admin`. The admin password is `adminToken` in `secrets.json` in the data directory.
+## Which Provider Should I Choose?
 
-**Connecting an existing backend:** if you already run gemini-web2api-go yourself, choose 连接已有后端 (connect an existing backend with a custom URL and API key). Enter its URL (ending in `/v1`) and its `API_KEY`.
-
-## Plugin options (Gemini Web)
-
-Tool calls are on by default (coding agents send tools with every request); image input is off. To allow images:
-
-```bash
-magpie plugin options magpie-gemini-web '{"allowImages":true}'
-```
+The plugin provides two independent providers that can be used individually or together:
 
-| Option | Default | Description |
+| Feature | Google AI Studio (`ai-studio`) | Gemini Web (`gemini-web`) |
 | :--- | :--- | :--- |
-| `allowTools` | `true` | Allows tool calls (experimental; upstream emulates them with prompts). When `false`, requests with tools get a 400 |
-| `allowImages` | `false` | Allows image input |
-| `baseURL` | `http://127.0.0.1:8083/v1` | Default backend URL |
-| `contextLimit` / `outputLimit` | `1000000` / `8192` | Context and output limits reported to clients |
-| `requestTimeoutMs` / `modelTimeoutMs` | `240000` / `10000` | Timeouts in ms for requests and for fetching the model list. The request timeout counts each wait on the backend, so a reply that keeps coming is never cut off |
-| `stripCitations` | `true` | Removes the citation markers Gemini adds to replies, `[cite: 1]` and `[cite_start]`, tool call arguments included. Set it to `false` while Gemini edits code that contains such text itself |
-
-## Thinking effort
-
-You can switch a model between `low` and `high` effort in Magpie if it has a `-thinking` version. `low` uses the base model and `high` uses the `-thinking` model with extended thinking, so the `-thinking` model isn't listed on its own. After upgrading the plugin, run `magpie provider models gemini-web` to refresh the model list. Argon's medium tier will be added once upstream supports it ([#5](https://github.com/BUKOWSKIREAL/magpie-gemini-web/issues/5)).
-
-## Security and data
+| **Best for** | **Coding agents (recommended)** | General chat, web-only models & web quota |
+| **Tool calling** | **Native Function Calling**, reliable | Prompt-emulated (experimental; Flash often skips tools) |
+| **Thinking levels** | `minimal` / `low` / `medium` / `high` (`minimal` is fastest & cheapest) | `low` (base) / `high` (`-thinking` extended thinking) |
+| **Sign-in method** | Sign in directly in an isolated popup browser window | Copy `cookie` from a private/incognito window |
+| **Usage cards** | Shows models currently on cooldown and recovery times | Syncs **5-hour** & **weekly** usage and reset times from the web |
+| **Local backend** | AIStudio2API (`v0.2.13`) | gemini-web2api-go (`4.22.0-magpie.1` optimized build) |
 
-- The backend listens on `127.0.0.1` only. Your cookie goes only to that local backend, and Magpie stores a locally generated API key instead.
-- The default backend is this project's **4.22.0-magpie.1**, built from pinned upstream v4.22.0 sources with this repository's patch. SHA-256 is checked on download and before launching a new process. Builds cover macOS, Linux and Windows on x64 and arm64; the release includes sources, build metadata and checksums.
-- The data directory is `~/.local/share/magpie-gemini-web` (set `GEMINI_WEB_DATA_DIR` to change it). The backend writes its log to `backend.log` there.
-- The plugin sends one request at a time, but this can't guarantee that Google won't flag your account. Use it at your own risk.
+---
 
-## Usage
+## Quick Start
 
-Magpie's usage cards show each Google account's **5-hour** and **weekly** usage and reset times, as <https://gemini.google.com/usage> does. Each Google account gets a card of its own, named by its email:
+Install **magpie-gemini-web** from the Magpie plugin market, then sign in to either (or both) providers below. The plugin automatically downloads the corresponding backend, verifies its SHA-256 checksum, and runs it in the background—no Go installation or extra setup required.
 
-- An account added by one-click setup becomes its own card.
-- For an account already in the backend (one added by an older version, say), add another Gemini Web account in Magpie and pick **「添加本地后端里已有的 Google 账号」** (add an account already in the local backend), then choose it from the list. The old `API key …` sign-in can then go: it shows the whole pool as one card (each window at the account that has used the most).
+### Option 1: Google AI Studio (`ai-studio`)
 
-Note that the backend picks the Google account for each request from its pool in turn: how Magpie spreads requests over the cards doesn't decide which account serves them. Only the one-click local backend has usage; a backend you connect to yourself keeps its cookies out of the plugin's reach.
+1. Sign in to **Google AI Studio** in Magpie and choose **「用 Google 账号登录（推荐）」** (Sign in with a Google account).
+2. Sign in to your Google account in the separate login window that opens (your regular browser is unaffected), then close the window.
+   > On first run, the login browser Camoufox (~300 MB) is downloaded first, so the window may take a few minutes to appear. Complete sign-in within 15 minutes.
+3. **Managing accounts:** Choose "Sign in with a Google account" again at any time to **add a new account**, create a card for an existing local account, or **re-authenticate** an expired account.
 
-To send Google fewer requests, usage isn't read on every refresh. An account is read again once the backend has used it or one of its windows has reset, and never twice within 10 minutes. An idle account is read at most every 6 hours, which also picks up what you used in the Gemini web app.
+### Option 2: Gemini Web (`gemini-web`)
 
-Usage and emails are read the way the backend reaches Google for that account. When that way isn't certain, nothing is read and the card says why:
+1. Sign in to **Gemini Web** in Magpie and choose **「一键配置本地 Gemini Web（推荐）」** (One-click local setup).
+2. Copy your cookie using a **private / incognito window** (Firefox recommended):
+   1. Open <https://gemini.google.com/app> in the private window and sign in to your Google account.
+   2. Press `F12` (`⌥⌘I` on macOS), switch to the **Network** tab, and reload the page.
+   3. Click any `gemini.google.com` request → **Headers** → **Request Headers**, copy the `cookie` value, and paste it into Magpie.
+   4. **Close the private window directly—do not sign out** (signing out invalidates the cookie).
+3. The plugin verifies the account and completes sign-in. Repeat the steps above to add more accounts.
 
-- the backend has a proxy pool, but the account isn't bound to a proxy yet (the backend binds it on its first request);
-- the account's proxy is disabled, or is a SOCKS proxy.
+> **Why is a private window required?** The backend periodically refreshes this session to keep it alive. If it shares a session with your daily browser, Google will revoke the session and sign your browser out of all Google services. A private window (or a dedicated secondary Google account) gives the backend an isolated session.
 
-So with a proxy pool, an account just added by one-click setup has no email yet. Send one request with it, sign in to it again with **「添加本地后端里已有的 Google 账号」**, then remove the sign-in without an email.
+---
 
-## Limitations (Gemini Web)
+## Multiple Accounts & Usage Cards
 
-- Upstream emulates tool calls with prompts, so they aren't always reliable. Flash models often don't call tools.
-- Only text models whose names start with `gemini-` are exposed. A `cost` of 0 doesn't reflect your actual Google quota.
+- **One card per account:** Each Google account gets its own usage card titled with its email address.
+  - *Migrating older Gemini Web accounts:* For accounts added in earlier versions, add a Gemini Web account in Magpie and choose **「添加本地后端里已有的 Google 账号」** (Add an existing Google account from the local backend) to create individual cards, then remove the old pooled `API key …` card.
+- **Automatic account rotation:** The local backend selects which Google account serves each request (Gemini Web rotates across the pool; AI Studio uses one account until cooldown and switches to the next). Switching cards in Magpie does not change which account the backend picks.
+- **Usage reporting:**
+  - `gemini-web`: Available only with the one-click local backend. To minimize requests to Google, usage is refreshed only after an account is used or a quota window resets (at least 10 minutes apart, and at most once every 6 hours when idle).
+  - `ai-studio`: AI Studio does not report remaining total quota; cards display models currently on cooldown and their recovery times, or prompt when re-authentication is needed.
 
-## Google AI Studio (`ai-studio`)
+---
 
-Uses Google AI Studio through [AIStudio2API](https://github.com/Mag1cFall/AIStudio2API) (pinned to v0.2.12). Unlike Gemini Web, tool calls use native Function Calling, thinking models offer four levels in Magpie, `minimal` / `low` / `medium` / `high` (`minimal` is the fastest and uses the least quota), and generation needs no browser.
+## Configuration & Advanced Usage
 
-### Getting started
+<details>
+<summary><b>⚙️ Plugin Options & Proxy Setup</b> (image input, proxy configuration, custom backends)</summary>
 
-1. Sign in to Google AI Studio and choose **用 Google 账号登录（推荐）** (sign in with a Google account). The first time, the plugin downloads AIStudio2API, verifies its SHA-256 and starts it in the background.
-2. Sign in to your Google account in the separate login window that opens (your usual browser is not affected), then close it. The first time, the login browser Camoufox (about 300 MB) is downloaded first, so the window can take a few minutes to appear while Magpie shows no change; the login must finish within 15 minutes.
+<br>
 
-Choosing it again later lists:
+Tool calling is enabled by default; image input is disabled by default. Configure plugin options via the CLI:
 
-- **添加新的 Google 账号** (add a new Google account): opens the login window for another account;
-- **the accounts already on this machine**: makes a card for one at once; one marked as needing to sign in again opens the login window to do so.
-
-Each Google account gets a card of its own. As with Gemini Web, the local service picks the account for each request (one until it cools down, then the next), whichever card Magpie uses.
+```bash
+# Enable image input (applies to both providers)
+magpie plugin options magpie-gemini-web '{"allowImages":true}'
 
-If you run AIStudio2API yourself, choose **连接已有 AIStudio2API** (connect an existing AIStudio2API) and enter its address (default `http://127.0.0.1:2048/v1`) and `PROXY_API_KEY`.
+# Configure a proxy for AI Studio
+magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
+```
 
-Usage card: AI Studio reports no remaining quota. The card shows the models the account is cooling down on and when each comes back, or that the account needs to sign in again.
+| Option | Default | Scope | Description |
+| :--- | :--- | :--- | :--- |
+| `allowTools` | `true` | Shared (override via `studio.allowTools`) | Allow tool calls. When `false`, requests with tools return 400 |
+| `allowImages` | `false` | Shared (override via `studio.allowImages`) | Allow image input |
+| `requestTimeoutMs` / `modelTimeoutMs` | Web: `240000` / `10000`; Studio: `1800000` / `10000` | Shared (override via `studio.*`) | Timeout (ms) per backend wait or model list fetch; resets on stream data, explicit settings take precedence |
+| `stripCitations` | `true` | `gemini-web` only | Strip `[cite: 1]` and `[cite_start]` markers from replies and tool arguments (not supported on AI Studio) |
+| `baseURL` | `http://127.0.0.1:8083/v1` | `gemini-web` only | Default Gemini Web backend URL |
+| `contextLimit` / `outputLimit` | `1000000` / `8192` | `gemini-web` only | Context and output limits reported to clients |
+| `studio.proxy` | none | `ai-studio` only | Proxy for reaching Google (`http` / `https` / `socks5`), or set `AI_STUDIO_PROXY` env var; when set, it takes precedence over the proxy saved in the admin page. An empty value counts as unset |
+| `studio.baseURL` | `http://127.0.0.1:2048/v1` | `ai-studio` only | Default URL when connecting an existing AIStudio2API instance |
+| `studio.contextLimit` / `studio.outputLimit` | Model catalog defaults | `ai-studio` only | Limits reported to clients (can only lower the catalog defaults) |
 
-### Plugin options
+**Using a proxy to reach Google:**
+- **AI Studio:** Preferably set it in the local admin page. Open the address on the usage card's "管理页" (admin page) line (default `http://127.0.0.1:2048`) and sign in as `magpie` with `adminPassword` from `config.json` in the data directory. Save the proxy, then restart the service from the admin page. The plugin keeps the saved value when it restarts the backend.
+  - Alternatively, `studio.proxy` or `AI_STUDIO_PROXY` take precedence over the saved proxy. A change applies after the local service restarts (`npm run studio:stop`; the next request starts it again).
+  - With neither set, the backend falls back to the `HTTPS_PROXY` environment variable or the system proxy (Windows proxy settings).
+  - **The provider proxy set for `ai-studio` in Magpie is not passed to the local backend**; use one of the options above.
+  - The usage card's "代理出口" (proxy) line, the Google sign-in instructions and failure messages, and `npm run studio:status` show the proxy the backend actually uses, where it comes from, and whether a new setting still needs a restart.
+  - The listen address, API key and admin credentials are managed by the plugin; changing them in the admin page has no effect.
+- **Gemini Web:** The backend ignores `HTTP_PROXY`. Add your proxy to the proxy pool in the local admin panel at `http://127.0.0.1:8083/admin` (password is `adminToken` in `secrets.json` inside the data directory).
+  - *Note:* When using a proxy pool, send one request with a newly added account so the backend binds it to a proxy, then re-add it via "Add an existing Google account from the local backend" to load its email and usage (SOCKS proxies are not supported for usage reads).
 
-`allowTools`, `allowImages`, `requestTimeoutMs` and `modelTimeoutMs` apply to both providers; the other AI Studio options go under `studio`. The root `baseURL`, `contextLimit`, `outputLimit` and `stripCitations` apply to Gemini Web only.
+**Connecting a self-hosted backend:**
+If you already run `gemini-web2api-go` or `AIStudio2API` yourself, select **Connect an existing backend / AIStudio2API** during sign-in and provide its `/v1` URL and API key.
 
-```bash
-magpie plugin options magpie-gemini-web '{"studio":{"proxy":"http://127.0.0.1:7890"}}'
-```
+**Refreshing the model list:**
+After upgrading the plugin, run `magpie provider models gemini-web` to refresh available models.
 
-| Option | Default | Description |
-| :--- | :--- | :--- |
-| `studio.proxy` | none | Proxy for reaching Google (http / https / socks5). The `AI_STUDIO_PROXY` environment variable works too |
-| `studio.baseURL` | `http://127.0.0.1:2048/v1` | Default address for connecting an existing AIStudio2API |
-| `studio.contextLimit` / `studio.outputLimit` | the model catalog's | Limits declared to clients; they can only lower the catalog's |
-| `studio.allowTools` etc. | as at the root | Override the root option of the same name for AI Studio only |
+</details>
 
-AI Studio replies keep their citation marks such as `[cite: 1]`; they can't be stripped.
+<details>
+<summary><b>🛠️ AI Studio CLI Commands</b> (service status, re-login, offline install)</summary>
 
-### Command line
+<br>
 
-When an error from the plugin asks you to run a command, it gives the command with its full path, ready to copy. In the plugin's directory you can also use:
+When a plugin error asks you to run a command, it includes the full ready-to-copy path. From the plugin directory, you can also run:
 
-| Command | What it does |
+| Command | Description |
 | :--- | :--- |
-| `npm run studio:status` | Show the service and account status |
+| `npm run studio:status` | Show local service and account status |
 | `npm run studio:start` / `studio:stop` | Start / stop the local service |
 | `npm run studio:login` | Add a Google account |
-| `npm run studio:relogin -- [<account>]` | Sign an expired account in again (optional when only one is) |
-| `npm run studio:install -- --archive <file>` | Install offline from a downloaded archive |
+| `npm run studio:relogin -- [<account>]` | Re-authenticate an expired account (argument optional if only one) |
+| `npm run studio:install -- --archive <file>` | Offline install from a pre-downloaded archive |
 | `node scripts/studio.mjs import <dir>` | Import existing accounts while the service is stopped |
-| `npm run studio:smoke` | Live acceptance run (uses account quota) |
-
-### Security and data
-
-- The service listens on `127.0.0.1` only; Magpie keeps a locally generated API key.
-- Data directory: `~/.local/share/magpie-ai-studio` (override with `AI_STUDIO_DATA_DIR`). The log is `backend.log`, started afresh on the next start once it passes 10 MB.
-- A first setup uses port 2048, or another free port when 2048 is taken (by an AIStudio2API of your own, say), saved in the data directory's `config.json`.
-- The downloaded archive stays in the data directory; installing again uses it when its checksum matches.
-- Supported on macOS, Linux (x64 / arm64) and Windows x64.
-
-## Native Task on macOS (experimental)
-
-On macOS, sign-in offers one more option, "macOS 原生 Task（实验性）": requests skip the Gemini Web backend and go to a local daemon that runs them in Gemini.app's own Task mode, with tool calls on its native Function Calling channel, as the model `gemini-task-argon`. Windows and Linux don't offer it; keep using one-click setup there.
+| `npm run studio:smoke` | Run a live acceptance check (consumes account quota) |
 
-This is an alpha: it supports only the verified Gemini.app build, needs a local setup first (Gemini.app signed in, plus session templates), has passed only one live tool round trip against real Argon, and shows no usage; if an agent is interrupted before it returns a tool result, that call holds the only Task slot for up to about 4 minutes. See [native-task/README.md](native-task/README.md) for setup, session requirements and limitations.
+</details>
 
-## Default optimized backend and rollback
+<details>
+<summary><b>🔒 Security, Data Directories & Backend Version Management</b> (logs, rollback, macOS Native Task)</summary>
 
-Starting with plugin **0.4.1**, one-click setup uses [4.22.0-magpie.1](https://github.com/BUKOWSKIREAL/magpie-gemini-web/releases/tag/backend-v4.22.0-magpie.1). It includes the changes that previously required a manual build: stable XSRF caching, cancellation propagation for the main generation and upload requests, early completion after complete tool calls, browser headers, and verification of the returned Argon model. Your Google account still needs access to the requested model.
+<br>
 
-**Upgrading an existing installation:** the plugin leaves a running backend alone. Stop the existing backend process (its process ID is in `backend.pid` in the data directory), then start Magpie or send a request. A stopped old official backend is upgraded automatically, preserving configuration, the cookie database and API keys. Explicitly installed local Argon builds are kept; to replace one with the published build, stop it and run `backend:install` below.
+**Security & data directories:**
+- Both backends listen on `127.0.0.1` only. Cookies and sessions remain on your machine; Magpie stores only a locally generated API key.
+- **Gemini Web data directory:** `~/.local/share/magpie-gemini-web` (override with `GEMINI_WEB_DATA_DIR`), logs at `backend.log`. Supports macOS, Linux, and Windows (x64 / arm64).
+- **AI Studio data directory:** `~/.local/share/magpie-ai-studio` (override with `AI_STUDIO_DATA_DIR`), logs at `backend.log` (rotated on next start after exceeding 10 MB). Uses port 2048 by default (or picks a free port and saves it in `config.json`). Supports macOS, Linux (x64 / arm64), and Windows x64.
+- Concurrency is capped at 1, but Google account rate-limiting or flagging cannot be completely ruled out—use at your own risk.
 
-To roll back, stop the backend and run this from the plugin directory:
+**AI Studio upgrades and model selection:**
+- The plugin pins SHA-256-verified `v0.2.13-magpie.1`, based on upstream `v0.2.13`. Upgrade the plugin to update the backend. Official managed releases at or below that upstream version are upgraded on the next managed startup, preserving accounts, port and sign-in credentials.
+- **Online updates are disabled in the managed backend on macOS, Linux, and Windows.** The admin page directs users to upgrade through the Magpie plugin; the update endpoint returns HTTP 403 and update checks do not contact GitHub. Independently managed external servers are unaffected. See [docs/studio-release.md](docs/studio-release.md) for the patch and reproducible build process.
+- Managed Unix installs still attempt to set `package/` to `0555` as additional file protection. Permission failures do not block service, and disabling online updates does not depend on permissions. To reset by manually deleting the data directory, stop the service first, then run `chmod -R u+w "<data-dir>/package"` before deleting it; replace `<data-dir>` with the actual path.
+- If a newer or custom version is installed, the plugin reports a conflict with `stop`, `install`, and `start` commands carrying the correct `--data-dir`. Stop can recover a changed listener PID and verifies its executable path before signaling it. If HTTP is down but the process is still alive, the plugin refuses to reinstall or launch a second process.
+- When stopped, a replaced executable is restored from the verified pinned archive; failed verification never launches the replacement. Existing account and runtime data files are kept, but **an older backend may not read data migrated by a newer version**. Before manually downgrading, stop the service and back up the entire data directory, including `auth/` and `runtime/requests.db`. If data migration is known to have occurred, update the plugin to match the newer backend.
+- The backend's base request deadline and the plugin's default response/stream-idle timeout are 30 minutes (override via `studio.requestTimeoutMs`). This allows long non-streaming replies to finish collecting on the server. A stalled backend can also take 30 minutes to time out, and its single worker can hold up later requests. Cancel a request or choose a shorter timeout when needed; shorter limits can interrupt valid long replies. Upstream controls deadline scaling for automatic continuation.
+- Source review of the locally installed Magpie `v0.1.1285` (`d783df46`) found no shorter fixed total timeout on this plugin's generation path: `Provider.Do → plugin.Fetch → loader.fetch` bypasses the ordinary HTTP transport's 10-minute response-header timeout. The gateway's 5-minute `IdleTimeout` applies between requests. Clients or reverse proxies can impose shorter limits; this was not a 30-minute end-to-end waiting test.
+- Models with `-build` or `assistant_route` are filtered out: they inject the Build coding assistant's own system prompt and are not offered as ordinary Agent models. Refresh with `magpie provider models ai-studio` after upgrading.
 
-```bash
-npm run backend:install:upstream
-```
-
-This installs the checksum-verified official v4.22.0 and saves the selection, so automatic starts keep using upstream. To restore the default optimized build:
+**Gemini Web optimized backend upgrades & rollback:**
+- One-click setup uses [4.22.0-magpie.1](https://github.com/BUKOWSKIREAL/magpie-gemini-web/releases/tag/backend-v4.22.0-magpie.1) by default (built from pinned upstream v4.22.0 with XSRF caching, request cancellation propagation, early tool-call completion, and Argon model verification).
+- **Upgrading:** Running backends are not interrupted automatically. Stop the existing process (PID in `backend.pid` inside the data directory); the next Magpie launch or request will upgrade the binary while preserving config and cookies.
+- **Rollback to upstream / restore optimized build** (run in the plugin directory after stopping the backend):
+  ```bash
+  npm run backend:install:upstream  # Roll back and pin to official v4.22.0
+  npm run backend:install           # Restore default optimized build
+  ```
+- For reproducible builds and release procedures, see [docs/backend-release.md](docs/backend-release.md).
 
-```bash
-npm run backend:install
-```
+**Native Task on macOS (experimental):**
+On macOS, Gemini Web sign-in includes an experimental **macOS Native Task** option that routes requests through `Gemini.app`'s native Task mode (`gemini-task-argon` with native Function Calling). Currently in Alpha and requires local setup first—see [native-task/README.md](native-task/README.md).
 
-A failed download or checksum verification keeps the previous binary. On Windows, stop the old process before replacing its executable.
-
-The backend release includes source and build metadata. Developers with Git, Node 22+ and Go 1.27.1 can reproduce all six builds and compare the pinned hashes from this repository:
-
-```bash
-npm run backend:release:build
-```
+</details>
 
-The script extracts clean sources from the pinned upstream commit and applies `patches/argon.patch`; it never changes the developer's `backend-source` working tree. See [docs/backend-release.md](docs/backend-release.md) for the release procedure.
+---
 
 ## License
 
-MIT. The upstream gemini-web2api-go project is also MIT (see `LICENSE-UPSTREAM`).
+MIT. The upstream `gemini-web2api-go` project is also MIT (see `LICENSE-UPSTREAM`).