magpie-gemini-web 0.3.3 → 0.4.0

package/README.en.md

@@ -26,15 +26,15 @@ From then on, Magpie starts the backend automatically every time it launches. To
 
 ## Plugin options
 
-Tool calls and image input are off by default. Turn them on if a coding agent needs tools:
+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 '{"allowTools":true,"allowImages":true}'
+magpie plugin options magpie-gemini-web '{"allowImages":true}'
 ```
 
 | Option | Default | Description |
 | :--- | :--- | :--- |
-| `allowTools` | `false` | Allows tool calls (experimental). When off, requests with tools get a 400 |
+| `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 |
@@ -75,6 +75,12 @@ So with a proxy pool, an account just added by one-click setup has no email yet.
 - 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.
 
+## 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.
+
+This is an alpha: it supports only the verified Gemini.app build, needs a local setup first (Gemini.app signed in, plus session templates), hasn't passed an end-to-end check against real Argon yet, and shows no usage. See [native-task/README.md](native-task/README.md) for setup, session requirements and limitations.
+
 ## Argon patched build (optional)
 
 The official backend already supports `gemini-4-argon`, which needs a paid or Ultra account. This repo's patched build also verifies that responses really come from Argon, so a silent downgrade is caught, and it lowers latency. It also makes the backend's requests look more like a browser's: on a direct connection every request carries the full set of Chrome headers (the official build's direct chat requests say `Go-http-client/2.0`), and refreshing the cookies to keep a session alive no longer fetches the `/app` page right away. Building it requires Go 1.26+:

package/README.md

@@ -26,15 +26,15 @@
 
 ## 插件选项
 
-工具调用和图片输入默认关闭，Coding Agent 需要工具时请开启：
+工具调用默认开启（Coding Agent 每个请求都带工具），图片输入默认关闭。需要图片输入时：
 
 ```bash
-magpie plugin options magpie-gemini-web '{"allowTools":true,"allowImages":true}'
+magpie plugin options magpie-gemini-web '{"allowImages":true}'
 ```
 
 | 选项 | 默认值 | 说明 |
 | :--- | :--- | :--- |
-| `allowTools` | `false` | 允许工具调用（实验性）。关闭时带工具的请求会返回 400 |
+| `allowTools` | `true` | 允许工具调用（实验性，由上游用提示词模拟）。设为 `false` 时带工具的请求会返回 400 |
 | `allowImages` | `false` | 允许图片输入 |
 | `baseURL` | `http://127.0.0.1:8083/v1` | 默认后端地址 |
 | `contextLimit` / `outputLimit` | `1000000` / `8192` | 向客户端声明的上下文 / 输出上限 |
@@ -75,6 +75,12 @@ Magpie 的额度卡片会显示 Google 账号的 **5 小时** 和 **每周** 用
 - 工具调用由上游用提示词模拟，不一定可靠，Flash 系列经常不调用工具。
 - 只开放 `gemini-` 开头的文本模型；`cost` 显示为 0 不代表 Google 的实际配额。
 
+## macOS 原生 Task（实验性）
+
+在 macOS 上登录时会多出一个「macOS 原生 Task（实验性）」选项：请求不走 Gemini Web 后端，而是交给本机常驻服务，由 Gemini.app 自己的 Task 模式执行，工具调用走原生的 Function Calling 通道，模型为 `gemini-task-argon`。Windows 和 Linux 上不会出现这个选项，请继续使用上面的一键配置。
+
+当前为 Alpha：仅支持已验证的 Gemini.app 版本，选这个选项之前需要先在本机完成 setup（需要 Gemini.app 已登录，以及会话模板），尚未完成真实 Argon 的端到端验收，读不到额度。配置步骤、会话要求和限制见 [native-task/README.md](native-task/README.md)。
+
 ## Argon 增强版（可选）
 
 官方后端已支持 `gemini-4-argon`（需付费 / Ultra 账号）。本仓库的补丁版额外校验返回的确实是 Argon（防止被静默降级），并降低延迟。它也让后端的请求更像浏览器：直连时每个请求都带齐 Chrome 请求头（官方版直连时，对话请求的 UA 是 `Go-http-client/2.0`），保活刷新 Cookie 后也不再立即重新抓取 `/app` 页面。需要 Go 1.26+：

package/index.mjs

@@ -2,6 +2,7 @@ import { normalizeBaseURL, settings, credentials, listModels, forward, UNREACHAB
 import { ensureBackend, localBackend } from './lib/native.mjs';
 import { parseCookieInput, importCookie } from './lib/setup.mjs';
 import { usage, poolChoices, poolAccounts, accountEmail } from './lib/usage.mjs';
+import { taskSupported, taskMethod, taskLoader, taskModels, isTaskAuth } from './lib/task.mjs';
 
 const ID = 'gemini-web';
 const GEMINI_URL = 'https://gemini.google.com/app';
@@ -158,9 +159,10 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
             callback: async () => signInFor(local, chosen)
           };
         }
-      }],
+      }, ...(taskSupported() ? [taskMethod] : [])],
       async loader(getAuth) {
         const auth = await getAuth();
+        if (isTaskAuth(auth)) return taskLoader(auth);
         if (auth?.type !== 'api') return {};
         const c = credentials(auth, opts);
         return {
@@ -176,6 +178,7 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
       async usage(getAuth) {
         const auth = await getAuth();
         if (auth?.type !== 'api') return { error: 'Gemini Web 还没有登录', windows: [], signIn: 'kept' };
+        if (isTaskAuth(auth)) return { error: '原生 Task 登录读不到额度', windows: [], signIn: 'kept' };
         let c;
         try {
           c = credentials(auth, opts);
@@ -193,6 +196,7 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
       id: ID,
       async models(provider, { auth } = {}) {
         if (auth?.type !== 'api') return provider.models;
+        if (isTaskAuth(auth)) return taskModels(auth, ID);
         const c = credentials(auth, opts);
         try {
           return await listModels(c, opts);
@@ -202,6 +206,16 @@ export const GeminiWebPlugin = async (_input, options = {}) => {
           return listModels(c, opts);
         }
       }
+    },
+    // The Task bridge keeps a conversation's state by its session, so each request carries the
+    // host's session id. The Web backend's forward() passes on only the headers it needs, so
+    // this doesn't reach it.
+    async 'chat.headers'(input, output) {
+      if (input?.model?.providerID !== ID && input?.provider?.info?.id !== ID) return;
+      if (typeof input.sessionID === 'string' && input.sessionID) {
+        output.headers ??= {};
+        output.headers['X-Gemini-Session'] = input.sessionID;
+      }
     }
   };
 };

package/lib/backend.mjs

@@ -115,7 +115,9 @@ export function settings(options = {}) {
     baseURL = normalizeBaseURL(options.baseURL);
   }
 
-  let allowTools = false;
+  // On by default: coding agents send tools with every request and don't read toolcall,
+  // so turning this off only means every one of their requests gets a 400.
+  let allowTools = true;
   if (options.allowTools !== undefined) {
     if (typeof options.allowTools !== 'boolean') {
       throw new Error('Invalid option allowTools: must be a boolean');
@@ -440,7 +442,7 @@ export async function forward(input, init, getAuth, opts) {
     const hasTools = (Array.isArray(body.tools) && body.tools.length > 0) ||
                      (Array.isArray(body.functions) && body.functions.length > 0);
     if (!opts.allowTools && hasTools) {
-      return makeOpenAIError(400, 'Experimental tools are disabled; set allowTools: true');
+      return makeOpenAIError(400, `Tool calls are turned off for magpie-gemini-web. Turn them on with: magpie plugin options magpie-gemini-web '{"allowTools":true}'`);
     }
 
     if (body.messages !== undefined) {
@@ -462,7 +464,7 @@ export async function forward(input, init, getAuth, opts) {
               }
             } else if (part.type === 'image_url') {
               if (!opts.allowImages) {
-                return makeOpenAIError(400, 'Image input is disabled; set allowImages: true');
+                return makeOpenAIError(400, `Image input is turned off for magpie-gemini-web. Turn it on with: magpie plugin options magpie-gemini-web '{"allowImages":true}'`);
               }
               if (!part.image_url || typeof part.image_url.url !== 'string' || !part.image_url.url.trim()) {
                 return makeOpenAIError(400, 'Image content must contain an image_url URL');

package/lib/task.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createForwarder, ensureService, getDefaultDataDir } from '../native-task/lib/runtime.mjs';
+
+// The experimental Task route: on macOS, a sign-in can go to the native-task bridge (see
+// native-task/), which runs Gemini.app's own Task mode, instead of the Gemini Web backend.
+// The sign-in says which with metadata.mode.
+
+export const TASK_MODE = 'task';
+export const TASK_MODEL = 'gemini-task-argon';
+
+const BRIDGE_CLI = fileURLToPath(new URL('../native-task/scripts/bridge.mjs', import.meta.url));
+
+// taskSupported is whether this computer can run the bridge: it drives Gemini.app for macOS.
+export function taskSupported(platform = process.platform) {
+  return platform === 'darwin';
+}
+
+export function isTaskAuth(auth) {
+  return auth?.type === 'api' && auth.metadata?.mode === TASK_MODE;
+}
+
+// startTask starts the bridge set up in dataDir. The bridge's setup needs files only a capture
+// gives, so the plugin can't run it: without one, the error says how.
+async function startTask(dataDir = getDefaultDataDir()) {
+  if (!fs.existsSync(path.join(dataDir, 'config.json'))) {
+    throw new Error(`还没有配置本机 Task 服务（${dataDir}）。先在终端运行 node "${BRIDGE_CLI}" setup，需要的文件见 native-task/README.md`);
+  }
+  return ensureService({ dataDir });
+}
+
+// taskMethod is the Magpie sign-in method for the bridge.
+export const taskMethod = {
+  type: 'oauth',
+  label: 'macOS 原生 Task（实验性，需先完成本机 setup）',
+  async authorize() {
+    const service = await startTask();
+    return {
+      url: '',
+      method: 'auto',
+      instructions: '',
+      callback: async () => ({
+        type: 'success',
+        key: service.apiKey,
+        accountId: `native:${service.instance_id}`,
+        metadata: { mode: TASK_MODE, baseURL: `${service.baseURL}/v1`, dataDir: service.dataDir }
+      })
+    };
+  }
+};
+
+// taskLoader is the auth loader for a Task sign-in: requests go to the bridge, starting it when
+// it isn't running.
+export async function taskLoader(auth) {
+  const service = await startTask(auth.metadata?.dataDir);
+  if (auth.key !== service.apiKey) {
+    throw Object.assign(new Error('本机 Task 服务的密钥变了，请重新登录'), { signIn: 'expired' });
+  }
+  return { apiKey: auth.key, baseURL: `${service.baseURL}/v1`, fetch: createForwarder(service) };
+}
+
+// taskModels is the one model the bridge serves, in the shape listModels gives.
+export function taskModels(auth, providerID) {
+  return {
+    [TASK_MODEL]: {
+      id: TASK_MODEL,
+      providerID,
+      name: 'Argon Task',
+      api: { id: TASK_MODEL, url: auth.metadata?.baseURL, npm: '@ai-sdk/openai-compatible' },
+      limit: { context: 65536, output: 8192 },
+      capabilities: {
+        temperature: false,
+        reasoning: false,
+        attachment: false,
+        toolcall: true,
+        input: { text: true, image: false },
+        output: { text: true }
+      },
+      cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
+      options: {},
+      headers: {},
+      variants: {},
+      status: 'active'
+    }
+  };
+}

package/native-task/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 magpie-gemini-web contributors
+
+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/native-task/README.md

@@ -0,0 +1,87 @@
+# Gemini Native Task 桥接与 Magpie 扩展
+
+本目录包含针对 macOS 原生 Gemini App 任务模式（Task Mode / Argon）的本地常驻守护进程与 Magpie 扩展插件。此实现为 Alpha 预览版本，提供文本对话及串行 OpenAI Function Calling 工具调用能力。
+
+## 前置要求与环境限制
+
+1. **操作系统**：仅支持 macOS（arm64），需已安装 `/Applications/Gemini.app`（版本 `1.128.14.1166`，SHA-256 `8cd89234b23182234e8e211e1449ae44e0a831b2185e98f4d1371a83c66f8964`）。
+2. **已登录账户**：需在 Gemini.app 中已登录可用账户，桥接器通过只读 Keychain API 读取原生凭据并执行 OAuth 续期。
+3. **App 必须退出**：在运行原生 Task 任务时，本机运行的 Gemini.app 进程必须处于退出状态（`pgrep -x Gemini` 必须为空），避免长连接与设备状态冲突。
+4. **抓取模板**：首次配置需要有效的会话头与消息模板（`task-headers.json`、`tool-headers.json`、`task-template.bin`、`turn-template.bin`）。`x-server-token` 与设备凭据暂未实现自动续期，需由已抓取模板手工提供。
+
+## 架构与行为特性
+
+- **模型标识**：网关模型 ID 为 `gemini-web/gemini-task-argon`（本地服务模型 ID 为 `gemini-task-argon`）。
+- **工具调用**：支持 OpenAI Function Calling 格式的串行工具调用（单轮至多 1 个工具调用），由客户端执行并回传结果。工具声明映射至 `agent_bridge` 服务。单个 Task 上限 32 次工具调用（非整个会话全局上限）。
+- **并发与超时**：全局同一时刻仅允许 1 个活跃 Task。任务全局超时为 240 秒，单次工具等待超时为 50 秒。无断线自动重连或重放机制。
+- **会话与持久化**：调用 Magpie 网关时必须提供稳定的 `X-Session-ID`，由插件的 `chat.headers` 将它转换为本机服务使用的 `X-Gemini-Session`。直接访问本机服务时使用 `X-Gemini-Session`。仅在网关传 `X-Magpie-Session` 不足以保证重试和续轮使用同一 ID。会话状态持久化于私有目录（`~/.local/share/gemini-native-task/sessions/*.json`，权限 `0600`）。
+- **容量与历史限制**：单个会话最多缓存 256 次请求记录，本地最多存储 128 个会话。不支持透明的历史压缩、修改或分支分叉（修改历史需开启新会话）。
+- **中断恢复与取消**：守护进程重启时，未完成的会话将标记为 `interrupted`，不会继续重放或悬挂。本地取消仅中止本地工作线程与流，服务端不保证原生任务取消。
+- **协议与参数说明**：
+  - 允许传入 `system` / `developer` 角色消息，通过精确的前置提示词进行转译兼容，但服务端无原生系统角色通道。
+  - `max_tokens` / `max_completion_tokens` 仅作为兼容性提示词建议注入，服务端无硬性切断。
+  - 不提供 Token 用量统计（Token Usage）。
+  - 流式响应（SSE）按阶段（工具调用 / 最终答案）缓冲输出，非逐字 Token 流。
+  - 不支持采样参数（temperature / top_p）或结构化输出（JSON Schema response format）。
+  - 原生对话记录保留在 Google 服务端。
+
+## 验证状态
+
+2026-10-15：已执行通过 41 项 Python 测试和 12 项 Node 测试；真实 Magpie `0.1.1244` 的隔离环境完成了插件安装、本地连接、模型发现及 8 个 HTTP 请求的工具往返测试。该网关测试使用模拟原生上游，包含两次串行工具、最终答案重试、错误会话/调用 ID 拒绝、旧工具阶段拒绝和下一轮用户消息。
+
+当前实现已使用现有登录完成 OAuth 续期及保存轮次读取，但真实 Task 请求被 Google 返回的 `Remy quota exhausted`（gRPC 8）拒绝，尚未完成本版真实 Argon 工具端到端验收。服务将该错误映射为 `native_quota_exhausted`，不会自动重发 Task。
+
+## Magpie 插件安装与登录
+
+Task 已并入 `magpie-gemini-web` 插件，不需要单独安装。先完成下面的本地服务 Setup，再登录并选择「macOS 原生 Task（实验性）」：
+
+```bash
+magpie plugin login gemini-web
+```
+
+登录后模型为 `gemini-web/gemini-task-argon`。没有完成 Setup 时，这个选项会报错并给出 setup 命令。
+
+## 本地桥接守护进程 CLI
+
+默认数据目录为 `~/.local/share/gemini-native-task`，默认监听端口为 `8084`。
+
+### 1. 引导配置（Setup）
+
+```bash
+node native-task/scripts/bridge.mjs setup \
+  --data-dir ~/.local/share/gemini-native-task \
+  --auth-file /path/to/encrypted_auth_file \
+  --task-headers /path/to/task-headers.json \
+  --tool-headers /path/to/tool-headers.json \
+  --task-template /path/to/task-template.bin \
+  --turn-template /path/to/turn-template.bin
+```
+
+### 2. 启动服务（Start）
+
+```bash
+node native-task/scripts/bridge.mjs start --data-dir ~/.local/share/gemini-native-task
+```
+
+### 3. 查看状态（Status）
+
+```bash
+node native-task/scripts/bridge.mjs status --data-dir ~/.local/share/gemini-native-task
+```
+
+### 4. 停止服务（Stop）
+
+```bash
+node native-task/scripts/bridge.mjs stop --data-dir ~/.local/share/gemini-native-task
+```
+
+## 离线开发与回归测试命令
+
+在仓库根目录下执行（Python 3.10+、Node 22+）：
+
+```bash
+python3 -m venv native-task/.venv
+native-task/.venv/bin/pip install -e ./native-task
+native-task/.venv/bin/python -m unittest discover -s native-task/tests -v
+node --test native-task/test/*.test.mjs
+```

package/native-task/bridge/gemini_native_bridge/__init__.py

@@ -0,0 +1,3 @@
+"""Gemini Native Task Bridge package."""
+
+__version__ = "0.1.0"

package/native-task/bridge/gemini_native_bridge/__main__.py

@@ -0,0 +1,235 @@
+"""CLI entrypoint for bootstrap and daemon serving."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import secrets
+import signal
+import sys
+import threading
+from pathlib import Path
+
+from .config import (
+    RuntimeConfig,
+    acquire_bootstrap_lock,
+    acquire_daemon_lock,
+    atomic_write_file,
+    ensure_data_dir,
+    get_default_data_dir,
+    load_config,
+    require_macos,
+    save_config,
+    validate_config_values,
+)
+from .contract import BridgeError
+from .oauth import extract_client, read_credential, refresh_access
+from .protocol import (
+    TASK_RPC,
+    TOOLS_RPC,
+    TURN_RPC,
+    fields,
+    messages,
+    one,
+    turn_request,
+    validate_headers,
+    validate_task_template,
+)
+from .server import BridgeServer
+from .state import Manager
+from .transport import unary
+
+
+def sanitize_headers(raw_headers: list) -> list[list[str]]:
+    out = []
+    for item in raw_headers:
+        if isinstance(item, list) and len(item) == 2:
+            k, v = str(item[0]), str(item[1])
+            if k.lower() not in ("authorization", "grpc-encoding", "grpc-accept-encoding"):
+                out.append([k, v])
+    out.append(["grpc-accept-encoding", "identity"])
+    return out
+
+
+def cmd_bootstrap(args: argparse.Namespace):
+    require_macos()
+    data_dir = Path(args.data_dir).expanduser().resolve()
+    ensure_data_dir(data_dir, create=True)
+
+    # Acquire bootstrap lock before checking or creating configuration
+    boot_lock = acquire_bootstrap_lock(data_dir)
+    try:
+        cfg_file = data_dir / "config.json"
+        if cfg_file.exists():
+            raise BridgeError("config_exists", f"Configuration already exists at {data_dir}. Preserve config or use a new directory.", 409)
+
+        # Validate numeric options before live refresh
+        validate_config_values(
+            api_key="a" * 32,
+            instance_id="init",
+            subject_sha256="0" * 64,
+            port=args.port,
+            task_timeout=args.task_timeout,
+            tool_timeout=args.tool_timeout,
+            max_tool_calls=args.max_tool_calls,
+        )
+
+        source_dir = data_dir / "source"
+        source_dir.mkdir(parents=True, mode=0o700, exist_ok=True)
+
+        auth_file = Path(args.auth_file).expanduser().resolve()
+        if not auth_file.exists():
+            raise BridgeError("file_not_found", f"Auth file {auth_file} does not exist.", 409)
+
+        binary = Path(args.binary).expanduser().resolve()
+        if not binary.exists():
+            raise BridgeError("file_not_found", f"App binary {binary} does not exist.", 409)
+
+        task_h_path = Path(args.task_headers).expanduser().resolve()
+        task_raw = json.loads(task_h_path.read_text(encoding="utf-8"))
+        task_entries = task_raw.get("out_headers") if isinstance(task_raw, dict) else task_raw
+        task_clean = sanitize_headers(task_entries)
+        validate_headers(task_clean, TASK_RPC)
+        atomic_write_file(source_dir / "task-headers.json", json.dumps({"out_headers": task_clean}, indent=2).encode(), mode=0o600)
+
+        tool_h_path = Path(args.tool_headers).expanduser().resolve()
+        tool_raw = json.loads(tool_h_path.read_text(encoding="utf-8"))
+        tool_entries = tool_raw.get("out_headers") if isinstance(tool_raw, dict) else tool_raw
+        tool_clean = sanitize_headers(tool_entries)
+        validate_headers(tool_clean, TOOLS_RPC)
+        atomic_write_file(source_dir / "tool-headers.json", json.dumps({"out_headers": tool_clean}, indent=2).encode(), mode=0o600)
+
+        task_tmpl_path = Path(args.task_template).expanduser().resolve()
+        task_tmpl_bytes = task_tmpl_path.read_bytes()
+        validate_task_template(task_tmpl_bytes)
+        atomic_write_file(source_dir / "task-template.bin", task_tmpl_bytes, mode=0o600)
+
+        turn_tmpl_path = Path(args.turn_template).expanduser().resolve()
+        turn_tmpl_bytes = turn_tmpl_path.read_bytes()
+        initial_conv = one(messages(turn_tmpl_bytes)[0], 1)
+        turn_req = turn_request(turn_tmpl_bytes, initial_conv)
+        atomic_write_file(source_dir / "turn-template.bin", turn_tmpl_bytes, mode=0o600)
+
+        cred = read_credential(auth_file, data_dir)
+        subject_hash = hashlib.sha256(cred.subject.encode()).hexdigest()
+        account_label = auth_file.parent.name
+        client = extract_client(binary)
+        token_data = refresh_access(client, cred)
+
+        atomic_write_file(data_dir / "token-cache.json", json.dumps(token_data, indent=2).encode(), mode=0o600)
+
+        pseudo = []
+        regular = []
+        for k, v in task_clean:
+            k_lower = k.lower()
+            if k == ":path":
+                pseudo.append([":path", TURN_RPC])
+            elif k.startswith(":"):
+                pseudo.append([k, v])
+            elif k_lower in ("grpc-encoding", "grpc-accept-encoding"):
+                continue
+            elif k_lower == "grpc-timeout":
+                regular.append([k, f"{args.task_timeout * 1000}m"])
+            else:
+                regular.append([k, v])
+        regular.insert(0, ["authorization", f"Bearer {token_data['access_token']}"])
+        regular.append(["grpc-accept-encoding", "identity"])
+        verify_headers = pseudo + regular
+        validate_headers(verify_headers, TURN_RPC)
+
+        _, resp_data = unary(verify_headers, turn_req, rpc_path=TURN_RPC, timeout=15.0)
+        matched = False
+        for msg in messages(resp_data):
+            for n, w, turn, _ in fields(msg):
+                if n == 1 and w == 2:
+                    turn_ids = one(turn, 1)
+                    if one(turn_ids, 1) == initial_conv:
+                        matched = True
+                        break
+        if not matched:
+            raise BridgeError("turn_verification_failed", "Turn verification failed for configured account.", 409)
+
+        api_key = secrets.token_urlsafe(32)
+        instance_id = secrets.token_hex(16)
+        config = RuntimeConfig(
+            data_dir=data_dir,
+            api_key=api_key,
+            instance_id=instance_id,
+            auth_file=auth_file,
+            binary=binary,
+            subject_sha256=subject_hash,
+            account_label=account_label,
+            port=args.port,
+            task_timeout=args.task_timeout,
+            tool_timeout=args.tool_timeout,
+            max_tool_calls=args.max_tool_calls,
+        )
+        save_config(config)
+
+        print(json.dumps({
+            "configured": True,
+            "port": config.port,
+            "account_label": config.account_label,
+            "instance_id": config.instance_id,
+        }))
+    finally:
+        boot_lock.close()
+
+
+def cmd_serve(args: argparse.Namespace):
+    data_dir = Path(args.data_dir).expanduser().resolve()
+    config = load_config(data_dir)
+    lock = acquire_daemon_lock(data_dir)
+    manager = Manager(config)
+    server = BridgeServer(config, manager)
+
+    def trigger_shutdown(*_):
+        threading.Thread(target=server.stop, daemon=True).start()
+
+    signal.signal(signal.SIGINT, trigger_shutdown)
+    signal.signal(signal.SIGTERM, trigger_shutdown)
+
+    try:
+        server.serve_forever()
+    finally:
+        manager.close()
+        server.server_close()
+        lock.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Gemini Native Task Bridge")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p_boot = subparsers.add_parser("bootstrap", help="Bootstrap configuration")
+    p_boot.add_argument("--data-dir", required=True)
+    p_boot.add_argument("--auth-file", required=True)
+    p_boot.add_argument("--task-headers", required=True)
+    p_boot.add_argument("--tool-headers", required=True)
+    p_boot.add_argument("--task-template", required=True)
+    p_boot.add_argument("--turn-template", required=True)
+    p_boot.add_argument("--binary", default="/Applications/Gemini.app/Contents/MacOS/Gemini")
+    p_boot.add_argument("--port", type=int, default=8084)
+    p_boot.add_argument("--task-timeout", type=int, default=240)
+    p_boot.add_argument("--tool-timeout", type=int, default=50)
+    p_boot.add_argument("--max-tool-calls", type=int, default=32)
+
+    p_serve = subparsers.add_parser("serve", help="Run HTTP server")
+    p_serve.add_argument("--data-dir", default=str(get_default_data_dir()))
+
+    args = parser.parse_args()
+    try:
+        if args.command == "bootstrap":
+            cmd_bootstrap(args)
+        elif args.command == "serve":
+            cmd_serve(args)
+    except BridgeError as be:
+        sys.stderr.write(f"Error ({be.code}): {be.message}\n")
+        sys.exit(1)
+    except Exception:
+        sys.stderr.write("Error (internal_failure): Unexpected error during command execution.\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()