magpie-gemini-web 0.3.2 → 0.4.0

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()

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

@@ -0,0 +1,143 @@
+"""Authentication management, credential renewal, and header injection."""
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import math
+import threading
+import time
+from pathlib import Path
+
+from .config import RuntimeConfig, atomic_write_file
+from .contract import BridgeError
+from .oauth import extract_client, read_credential, refresh_access
+from .protocol import TASK_RPC, TOOLS_RPC, validate_headers
+
+
+class AuthManager:
+    def __init__(self, config: RuntimeConfig):
+        self.config = config
+        self._lock = threading.Lock()
+        self.source_dir = self.config.data_dir / "source"
+        self.cache_file = self.config.data_dir / "token-cache.json"
+
+    def _read_cache(self) -> dict | None:
+        if not self.cache_file.exists():
+            return None
+        try:
+            data = json.loads(self.cache_file.read_text(encoding="utf-8"))
+        except Exception as e:
+            raise BridgeError("corrupt_cache", "Token cache cannot be decoded.", 409) from e
+
+        if not isinstance(data, dict):
+            raise BridgeError("corrupt_cache", "Token cache is corrupt.", 409)
+
+        # Well-formed cache with wrong or missing identity is a terminal account_mismatch before read_credential
+        if data.get("subject_sha256") != self.config.subject_sha256:
+            raise BridgeError("account_mismatch", "Token cache account binding is missing or mismatched.", 409)
+
+        expires_at_raw = data.get("expires_at")
+        if not isinstance(expires_at_raw, (int, float)) or isinstance(expires_at_raw, bool) or not math.isfinite(expires_at_raw):
+            return None
+
+        expires_at = float(expires_at_raw)
+        if expires_at <= time.time() + 300:
+            return None
+
+        if not isinstance(data.get("access_token"), str) or not data["access_token"]:
+            return None
+
+        return data
+
+    def _read_prior_rotation(self) -> str | None:
+        if not self.cache_file.exists():
+            return None
+        try:
+            data = json.loads(self.cache_file.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return None
+            if data.get("subject_sha256") != self.config.subject_sha256:
+                raise BridgeError("account_mismatch", "Token cache account binding is missing or mismatched.", 409)
+            rot = data.get("rotated_refresh_token")
+            if isinstance(rot, str) and rot.startswith("1//"):
+                return rot
+        except BridgeError:
+            raise
+        except Exception:
+            return None
+        return None
+
+    def get_token_data(self) -> dict:
+        with self._lock:
+            cached = self._read_cache()
+            if cached is not None:
+                return cached
+
+            # Only load prior rotation from a validated cache of this configured account
+            rotated_refresh = self._read_prior_rotation()
+
+            cred = read_credential(self.config.auth_file, self.config.data_dir)
+            subject_hash = hashlib.sha256(cred.subject.encode()).hexdigest()
+            if subject_hash != self.config.subject_sha256:
+                raise BridgeError("account_mismatch", "The local login account does not match the configured subject.", 409)
+
+            client = extract_client(self.config.binary)
+            token_data = refresh_access(client, cred, rotated_refresh)
+            if token_data.get("subject_sha256") != self.config.subject_sha256:
+                raise BridgeError("account_mismatch", "Renewed token subject does not match configured account.", 409)
+
+            atomic_write_file(self.cache_file, json.dumps(token_data, indent=2).encode(), mode=0o600)
+            return token_data
+
+    def _load_base_headers(self, filename: str) -> list[list[str]]:
+        path = self.source_dir / filename
+        if not path.exists():
+            raise BridgeError("missing_source_headers", f"Missing template headers file: {path}")
+        try:
+            content = json.loads(path.read_text(encoding="utf-8"))
+            raw = content.get("out_headers") if isinstance(content, dict) else content
+            if not isinstance(raw, list):
+                raise ValueError()
+            return [[str(k), str(v)] for k, v in raw]
+        except Exception as e:
+            raise BridgeError("corrupt_source_headers", "Header template cannot be decoded.") from e
+
+    def _inject_headers(self, base_headers: list[list[str]], access_token: str, expected_path: str) -> list[list[str]]:
+        pseudo = []
+        regular = []
+        grpc_timeout_set = False
+
+        for k, v in base_headers:
+            k_lower = k.lower()
+            if k_lower in ("authorization", "grpc-encoding", "grpc-accept-encoding"):
+                continue
+            if k_lower == "grpc-timeout":
+                regular.append(["grpc-timeout", f"{self.config.task_timeout * 1000}m"])
+                grpc_timeout_set = True
+                continue
+            if k.startswith(":"):
+                pseudo.append([k, v])
+            else:
+                regular.append([k, v])
+
+        if not grpc_timeout_set:
+            regular.append(["grpc-timeout", f"{self.config.task_timeout * 1000}m"])
+
+        regular.insert(0, ["authorization", f"Bearer {access_token}"])
+        regular.append(["grpc-accept-encoding", "identity"])
+
+        combined = pseudo + regular
+        validate_headers(combined, expected_path)
+        return combined
+
+    def headers(self) -> tuple[list[list[str]], list[list[str]]]:
+        token_data = self.get_token_data()
+        access_token = token_data["access_token"]
+
+        task_base = self._load_base_headers("task-headers.json")
+        tool_base = self._load_base_headers("tool-headers.json")
+
+        task_h = self._inject_headers(task_base, access_token, TASK_RPC)
+        tool_h = self._inject_headers(tool_base, access_token, TOOLS_RPC)
+        return copy.deepcopy(task_h), copy.deepcopy(tool_h)