@fxz26284407/yuanma-gateway 0.1.0 → 0.1.3

package/LICENSE

@@ -200,4 +200,3 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-

package/NOTICE

@@ -23,4 +23,3 @@ qrcode-terminal includes QRCode for JavaScript, Copyright (c) 2009 Kazuhiko Aras
 Development and transitive dependencies retain their respective licenses in the npm packages and package lock metadata. Relay packaging copies the complete ws package, including its license. No third-party copyright notices are removed.
 
 Original Yuanma gateway code is licensed under Apache-2.0; dependency licenses remain unchanged.
-

package/README.md

@@ -1,23 +1,23 @@
 # 远码网关（yuanma-gateway）
 
-远码的 Mac 本地网关与 HTTP/WS 公网密文中继。只包含两端网关，不包含鸿蒙工程、签名文件、个人文档库或运行数据。
+远码的 Mac 本地网关与 HTTP/WS 局域网密文中继。只包含两端网关，不包含鸿蒙工程、签名文件、个人文档库或运行数据。
 
 ## 项目系列
 
 [远码 Yuanma · GitHub Project](https://github.com/users/fxz26284407/projects/2)
 
-- [远码网关与公网中继](https://github.com/fxz26284407/yuanma-gateway)
+- [远码网关与局域网中继](https://github.com/fxz26284407/yuanma-gateway)
 - [远码鸿蒙客户端](https://github.com/fxz26284407/yuanma-harmony)
 
 ## 部署架构
 
 ![远码部署架构](docs/assets/deployment.svg)
 
-手机和 Mac 主动连接同一个公网 WS 入口；业务内容通过 Noise 在两端加密，中继只负责转发。Codex Desktop 与 Mac 网关连接同一个 app-server，任务、文件操作和审批发生在 Mac。SQLite 消息账本与设备授权也保存在 Mac。
+手机与 Mac 位于同一局域网，主动连接用户自行部署的内网 WS 中继，例如 `ws://192.168.1.10:19088`。业务内容通过 Noise 在两端加密，中继只负责转发。Codex Desktop 与 Mac 网关连接同一个 app-server，任务、文件操作和审批发生在 Mac。SQLite 消息账本与设备授权也保存在 Mac。
 
-中继默认直接拉取 [Docker Hub 公开镜像](https://hub.docker.com/r/fxz26284407/yuanma-relay)，端口映射为 `19088:8080`，支持 amd64 / arm64。既可部署在公网服务器，也可部署在本机 Docker 并通过花生壳 HTTPS 穿透，以 `wss://域名` 连接。
+中继部署在 Mac 的 Docker 或同一局域网内的主机，端口映射为 `19088:8080`，支持 amd64 / arm64。示例使用私有 IP，不需要公网域名、内网穿透或外部反向代理；不要在路由器上配置公网端口转发。按下文将服务绑定到宿主机实际的局域网 IP，并由防火墙仅允许可信内网设备访问。
 
-容器内只有 Node HTTP/WS relay，不含 Nginx，也无需配置域名或证书。HTTPS/WSS 的证书和 WebSocket 升级由花生壳或外部反代处理；直接使用 `ws://服务器地址:19088` 时不需要外部反代。
+这里的“局域网”指手机、网关与中继之间的连接范围，不表示模型在本地离线运行。Mac 上的 Codex、DeepSeek 及所选模型服务仍按各自配置联网；安装依赖和拉取镜像也需要访问相应软件源。
 
 [架构图源文件](docs/deployment.archify.json)
 
@@ -26,7 +26,7 @@
 | 目录 | 内容 | 运行位置 |
 | --- | --- | --- |
 | `gateway/` | Codex 适配、鉴权、项目权限、SQLite 消息账本、自有队列、图片和审批路由 | 工作 Mac |
-| `gateway/relay.ts`、`deploy/relay/` | HTTP 健康检查、WebSocket 密文路由、Docker 配置 | 公网服务器或本机 Docker |
+| `gateway/relay.ts`、`deploy/relay/` | HTTP 健康检查、WebSocket 密文路由、Docker 配置 | 局域网主机或 Mac Docker |
 | `scripts/` | 配对二维码、Mac 本地批准页、网关重启和中继打包 | Mac |
 
 手机与 Mac 建立固定公钥的 Noise 加密通道，中继只转发密文。Codex 桌面和网关需要连接同一后端才能共享实时会话。
@@ -66,18 +66,18 @@ yuanma-gateway projects
 ### 初始化
 
 ```sh
-yuanma-gateway init --relay-url wss://relay.example.com
+yuanma-gateway init --relay-url ws://192.168.1.10:19088
 ```
 
-将示例域名替换为实际 relay 地址。初始化读取真实 Codex 项目列表，由你选择初始项目。**现有产品会继续同步发现其他项目；配对后所有发现的项目和工作区默认可执行，初始列表不是权限白名单。** 初始化会明确说明并要求接受这项既有策略；会话中的执行审批仍独立管理。
+将示例 IP 替换为运行中继的主机局域网 IP，并先按下文启动中继。初始化读取真实 Codex 项目列表，由你选择初始项目。**现有产品会继续同步发现其他项目；配对后所有发现的项目和工作区默认可执行，初始列表不是权限白名单。** 初始化会明确说明并要求接受这项既有策略；会话中的执行审批仍独立管理。
 
-当前版本的远程连接还需显式启用本机私有文件保存传输密钥的模式；交互界面会说明并征求选择。
+当前版本的跨设备连接还需显式启用本机私有文件保存传输密钥的模式；交互界面会说明并征求选择。
 
 在非交互环境中，提供真实项目 ID 和对应选项：
 
 ```sh
 yuanma-gateway init \
-  --relay-url wss://relay.example.com \
+  --relay-url ws://192.168.1.10:19088 \
   --projects '真实项目ID1,真实项目ID2' \
   --allow-development-keys \
   --accept-project-access
@@ -107,7 +107,7 @@ yuanma-gateway restart
 更新中继地址并保存，供后续重启/启动复用：
 
 ```sh
-yuanma-gateway restart --relay-url wss://new-relay.example.com
+yuanma-gateway restart --relay-url ws://192.168.1.20:19088
 ```
 
 网关尚未运行时使用 `start --relay-url 地址`。URL 支持 `ws://` 和 `wss://`，拒绝内嵌账号密码、查询参数、片段或非法端口。状态输出中的 `relayUrl` 是实际生效地址，末尾 `/` 属正常规范化结果。
@@ -126,7 +126,7 @@ yuanma-gateway pair
 
 ### 手机版本要求
 
-使用花生壳 HTTPS/WSS 时，手机必须安装包含 WSS 支持的 **0.1.1（versionCode 100003）或后续版本**。原 **0.1.0（100002）** 不支持本次 WSS 地址。更新 relay 镜像或 npm 网关，不会自动升级手机 App。
+局域网连接使用 `ws://内网IP:19088`。建议手机与 Mac 网关保持兼容版本；更新 relay 镜像或 npm 网关，不会自动升级手机 App。
 
 使用同一签名的新包覆盖安装，保留应用数据与原配对；不要先卸载或清空数据。在手机连接页选择“扫码更新连接地址”，扫描刚生成且未过期的二维码。手机和 Mac 须连接同一套 relay，两套中继之间不共享注册路由。
 
@@ -199,7 +199,7 @@ yuanma-gateway devices
 
 同步前会在网关私有状态目录保存桌面状态备份；桌面运行时不会写入其状态文件。待同步记录在网关重启后保留，旧版手机分区记录会自动纳入一次补同步。
 
-## 中继部署：直接拉取 Docker Hub 镜像
+## 局域网中继部署：直接拉取 Docker Hub 镜像
 
 公开仓库：[fxz26284407/yuanma-relay](https://hub.docker.com/r/fxz26284407/yuanma-relay)。普通部署不再需要在 Mac 打包源码、上传发布目录或在服务器构建镜像；宿主机只需 Docker，不需要安装 Node、Codex 或网关依赖。
 
@@ -212,14 +212,14 @@ yuanma-gateway devices
 
 ### 启动与端口
 
-先确认宿主机 `19088` 未被占用，再执行：
+以下假设中继宿主机的局域网 IP 为 `192.168.1.10`。先替换为本机实际 IP，确认 `19088` 未被占用，再执行：
 
 ```sh
 docker pull fxz26284407/yuanma-relay:2026.11.03
 
 docker run -d --name yuanma-relay \
   --restart unless-stopped --init \
-  -p 19088:8080 \
+  -p 192.168.1.10:19088:8080 \
   --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
   --cap-drop ALL --security-opt no-new-privileges:true \
   --memory 128m --cpus 0.5 --pids-limit 64 \
@@ -227,82 +227,38 @@ docker run -d --name yuanma-relay \
   fxz26284407/yuanma-relay:2026.11.03
 ```
 
-`19088:8080` 表示 **宿主机 19088 → 容器 8080**。如需换端口，只改左边并同步修改穿透回源端口。无需给 relay 挂载工作目录、数据库、网关配置或 Mac 私钥。镜像自带 Node 运行时，内部不含 Nginx。
+`192.168.1.10:19088:8080` 表示 **宿主机局域网 IP 的 19088 → 容器 8080**，仅绑定指定内网接口。如需换端口，同步修改两端连接地址。无需给 relay 挂载工作目录、数据库、网关配置或 Mac 私钥。镜像自带 Node 运行时，内部不含 Nginx。
 
 ```sh
-curl --max-time 5 -fsS http://127.0.0.1:19088/health
+curl --max-time 5 -fsS http://192.168.1.10:19088/health
 docker inspect yuanma-relay --format '{{.State.Status}} / {{.State.Health.Status}}'
 docker logs --tail 30 yuanma-relay
 ```
 
 健康接口应返回 `{"ok":true}`；启动后短暂的 `starting` 会在健康检查完成后转为 `healthy`。重启已有容器可执行 `docker restart yuanma-relay`。仅拉取新镜像不会自动替换运行中的容器，升级时按原部署方式重建并保留端口和资源配置；已有 relay 占用端口时不要重复启动。
 
-### 花生壳 HTTPS / WSS
+### 手机与 Mac 连接同一局域网
 
-花生壳客户端需上线，并能访问宿主机发布的 relay 端口：
-
-```text
-手机 / Mac 网关
-    → wss://你的花生壳域名:443
-    → 花生壳 HTTPS 入口（TLS 与证书）
-    → 花生壳客户端
-    → 宿主机可达地址:19088
-    → relay 容器 8080（HTTP/WS）
-```
-
-| 花生壳配置项 | 填写方式 |
-| --- | --- |
-| 映射协议 | HTTPS |
-| 外网域名 | 花生壳分配或绑定的实际域名 |
-| 外网端口 | 默认 443，或产品实际提供的 HTTPS 外网端口 |
-| 内网主机 | 从花生壳客户端所在环境可达的宿主机地址 |
-| 内网端口 | 19088 |
-| 回源协议（如有此选项） | HTTP，relay 内部不提供 TLS |
-
-**公网 HTTPS 不等于内网也要 HTTPS。** 花生壳负责证书和 TLS，relay 继续用 HTTP/WS。外层入口需要支持 WebSocket 升级；若有单独的 WebSocket 开关，应开启。容器内加 Nginx 无法替代外层的 WS 支持。
-
-“内网主机”按花生壳实际运行位置选择：
-
-- 花生壳直接运行在 relay 宿主机上：可以使用 `127.0.0.1:19088`。
-- 花生壳在 Docker 容器里：`127.0.0.1` 是花生壳容器自身，应改为可达的宿主机地址。
-- Mac Docker Desktop 可查询 `host.docker.internal`；本次环境解析为 `192.168.65.254`，已核对从花生壳容器能访问 `192.168.65.254:19088`。该 IP 不是所有机器的固定值。
-- Linux 或其他环境使用从花生壳客户端可达的宿主机内网 IP，不直接照抄 Mac 示例。
-
-例如花生壳容器名为 `oray`，且内置以下工具：
+1. 将手机连接到与 Mac、中继互通的 Wi-Fi；Mac 或中继主机可使用同一路由器下的有线网络。不要使用隔离设备的访客网络。
+2. 为中继主机配置 DHCP 地址保留或固定内网 IP，允许可信内网设备访问 TCP `19088`，关闭路由器端口转发、穿透及其他对外入口。
+3. 在 Mac 检查 `http://192.168.1.10:19088/health`，返回 `{"ok":true}` 后更新网关并配对：
 
 ```sh
-docker exec oray getent hosts host.docker.internal
-docker exec oray wget -qO- -T 5 -t 1 http://192.168.65.254:19088/health
-curl --max-time 10 -fsS https://relay.example.com/health
+yuanma-gateway pair --relay-url ws://192.168.1.10:19088
 ```
 
-容器名、内网 IP 和公网域名均应替换为实际值。两跳健康接口都应返回 `{"ok":true}`，HTTPS 证书应有效。健康检查通过不等于 WebSocket 可用；还需确认 WSS 的 HTTP 101 升级及手机安全登录。
-
-配置完成后，已通过 npm 初始化的 Mac 网关可在任意目录执行：
-
-```sh
-source ~/.nvm/nvm.sh
-nvm use 22
-yuanma-gateway pair --relay-url wss://relay.example.com
-```
-
-将 `relay.example.com` 换成花生壳实际域名；非 443 外网端口需写入 URL。npm 配对命令会按现有安装启动网关，地址变化时安全重启原实例；已配对手机通过“扫码更新连接地址”沿用原身份登录。使用 HTTPS 穿透时，网关参数写 `wss://`，不能写 `https://`。手机须先升级至上文要求的 WSS 版本。
-
-本机部署依赖 Mac、Docker Desktop 和花生壳持续在线。休眠、退出 Docker 或花生壳离线都会中断连接；中继镜像不会自动配置这些运行条件。
-
-### 公网服务器直连或外部反代
+将示例 IP 替换为中继主机实际的内网 IP。手机扫描 Mac 生成的二维码；已有配对通过“扫码更新连接地址”沿用原身份。手机和 Mac 须使用同一个中继地址，手机不能将 `127.0.0.1` 或 `localhost` 作为 Mac 地址。
 
-也可在公网服务器运行同一镜像，放行实际端口后使用 `ws://服务器地址:19088`。需要 HTTPS/WSS 域名时，由外部 Nginx 或其他支持 WebSocket 的反代处理 TLS 和升级，再回源 HTTP `19088`；无需修改容器内部域名或证书。
+离开该局域网后，此部署方式无法连接 Mac；回到互通网络后可重新连接。更换局域网或中继 IP 后，更新网关地址并重新扫码。部署在 Mac Docker 上时，Mac 与 Docker 必须持续运行；休眠或退出 Docker 会中断连接。
 
 ### 常见连接问题
 
 | 现象 | 优先核对 |
 | --- | --- |
-| 宿主机健康检查失败 | relay 是否运行、端口映射是否正确或被占用 |
-| 宿主机可达，花生壳容器访问失败 | 是否误用 127.0.0.1、内网 IP 是否从该容器可达 |
-| 内网可达，外网域名失败 | 花生壳是否在线、映射是否保存、回源地址和协议是否正确 |
-| HTTPS 200，但 WSS 失败 | 外层 WebSocket 支持、证书和实际外网端口 |
-| 手机扫码后仍恢复旧连接 | 手机版本是否支持 WSS、二维码是否过期、新地址是否成功登录并保存 |
+| 宿主机健康检查失败 | relay 是否运行、绑定的内网 IP 是否属于本机、端口是否被占用 |
+| Mac 可达，手机不可达 | 手机是否连接同一局域网、是否启用访客隔离、防火墙是否允许内网端口 |
+| 手机扫码后仍恢复旧连接 | 二维码是否过期、新地址是否成功登录并保存 |
+| 更换网络后无法连接 | 是否仍能访问中继内网 IP；地址变化后需更新网关并重新扫码 |
 | WS 打开后路由立即断开 | Mac 网关是否注册到同一套 relay；“配置了中继”不等于注册成功 |
 
 Docker Hub 首页有完整的镜像使用说明。源码构建和 `npm run package:relay` 仍保留给需要自行修改中继的开发者，不作为普通部署的前置步骤。

package/dist/agents.js

@@ -1,4 +1,4 @@
-export const AGENT_KINDS = ['codex', 'deepseek'];
+export const AGENT_KINDS = ['codex', 'deepseek', 'antigravity'];
 export const DEFAULT_AGENT = AGENT_KINDS[0];
 export function isAgentKind(value) {
     return AGENT_KINDS.some(kind => kind === value);

package/dist/antigravity-conversation.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
+import { requireValue } from './domain.js';
+export const fingerprint = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+const valueText = (value) => typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value, null, 2);
+export function userText(step) {
+    const text = valueText(step.content);
+    // Strip only the observed whole envelope, never arbitrary user-authored tags.
+    const match = /^<USER_REQUEST>\s*([\s\S]*?)\s*<\/USER_REQUEST>(?:\s*<(ADDITIONAL_METADATA|USER_SETTINGS_CHANGE)>[\s\S]*?<\/\2>)*\s*$/.exec(text);
+    return match ? match[1] : text;
+}
+export function stepParts(step) {
+    const parts = [];
+    if (step.source === 'USER_EXPLICIT' && step.type === 'USER_INPUT') {
+        const text = userText(step);
+        if (text.trim() && !/^<USER_SETTINGS_CHANGE>[\s\S]*<\/USER_SETTINGS_CHANGE>$/.test(text.trim()))
+            parts.push({ part: 'content', role: 'user', text });
+    }
+    else if (step.source === 'MODEL' && step.type === 'PLANNER_RESPONSE') {
+        if (step.thinking)
+            parts.push({ part: 'thinking', role: 'tool', text: valueText(step.thinking), label: '思考记录' });
+        if (Array.isArray(step.tool_calls) && step.tool_calls.length)
+            parts.push({ part: 'tools', role: 'tool', text: valueText(step.tool_calls), label: '工具调用记录' });
+        if (step.content)
+            parts.push({ part: 'content', role: 'assistant', text: valueText(step.content) });
+    }
+    else if (step.source === 'MODEL' && step.type === 'GENERIC' && step.content) {
+        parts.push({ part: 'content', role: 'tool', text: valueText(step.content), label: step.label ?? '执行记录' });
+    }
+    return parts;
+}
+export function recordSteps(lines) {
+    const records = [];
+    let turnId = 'agy-context';
+    const latest = new Map();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let step;
+        try {
+            step = JSON.parse(line);
+        }
+        catch {
+            throw new Error('Antigravity 历史格式损坏，请刷新后重试');
+        }
+        requireValue(Number.isSafeInteger(step.step_index) && step.step_index >= 0 && typeof step.type === 'string' && typeof step.source === 'string', 'PROTOCOL_INCOMPATIBLE', 'Antigravity 历史步骤格式已变化', 503);
+        latest.set(step.step_index, step);
+    }
+    // Native rewrites may append another version of an existing step.
+    for (const step of [...latest.values()].sort((a, b) => a.step_index - b.step_index)) {
+        if (step.source === 'USER_EXPLICIT' && step.type === 'USER_INPUT' && !/^<USER_SETTINGS_CHANGE>/.test(userText(step).trim()))
+            turnId = 'agy-turn-' + step.step_index;
+        records.push({ step, turnId });
+    }
+    return records;
+}
+// Content changes during generation; identity must survive native updates and disk catch-up.
+export function partId(step, part) { const date = Date.parse(step.created_at); return 'agy:' + step.step_index + ':' + fingerprint([step.source, step.type, Number.isFinite(date) ? date : step.created_at]) + ':' + part; }
+export function stepStatus(status) {
+    const value = status.replace('CORTEX_STEP_STATUS_', '');
+    return value === 'DONE' ? 'completed' : value === 'ERROR' ? 'failed' : value === 'CANCELED' ? 'cancelled' : value === 'WAITING' ? 'waiting' : ['RUNNING', 'GENERATING'].includes(value) ? 'running' : 'pending';
+}
+export function nativeRecords(steps, fallbackTurn = 'agy-context') {
+    let turnId = fallbackTurn;
+    const records = [];
+    for (const [index, raw] of [...steps].sort((a, b) => a[0] - b[0])) {
+        if (raw.userInput?.isQueuedMessage)
+            continue;
+        const source = String(raw.metadata?.source ?? '').replace('CORTEX_STEP_SOURCE_', ''), type = String(raw.type ?? '').replace('CORTEX_STEP_TYPE_', '');
+        const step = { step_index: index, source, type, status: String(raw.status ?? '').replace('CORTEX_STEP_STATUS_', ''), created_at: raw.metadata?.createdAt ?? '' };
+        if (raw.userInput) {
+            step.content = (raw.userInput.items ?? []).filter((i) => typeof i.text === 'string').map((i) => i.text).join('');
+            if (source === 'USER_EXPLICIT' && !raw.userInput.isQueuedMessage && !/^<USER_SETTINGS_CHANGE>/.test(userText(step).trim()))
+                turnId = 'agy-turn-' + index;
+        }
+        else if (raw.plannerResponse) {
+            step.content = raw.plannerResponse.response ?? raw.plannerResponse.modifiedResponse;
+            if (!raw.plannerResponse.thinkingRedacted)
+                step.thinking = raw.plannerResponse.thinking;
+            step.tool_calls = raw.plannerResponse.toolCalls;
+        }
+        else if (source === 'MODEL') {
+            const key = ['runCommand', 'viewFile', 'codeAction', 'generic'].find(k => raw[k]);
+            if (key) {
+                step.type = 'GENERIC';
+                step.content = raw[key];
+                const render = raw.generic?.result?.stepRenderInfo, name = raw.metadata?.toolCall?.name;
+                const action = { edit_file: '编辑文件', write_to_file: '写入文件', write_file: '写入文件', create_file: '创建文件', read_file: '读取文件', view_file: '读取文件', run_command: '执行命令', run_terminal_command: '执行命令', list_dir: '浏览目录', find_by_name: '查找文件', grep_search: '搜索文件', search_web: '搜索网页' }[name] ?? { edit: '编辑文件', read: '读取文件', write: '写入文件' }[render?.icon] ?? { runCommand: '执行命令', viewFile: '读取文件', codeAction: '执行文件操作', generic: '执行操作' }[key];
+                const files = [];
+                for (const part of Array.isArray(render?.titleParts) ? render.titleParts : []) {
+                    const uri = part?.file?.uri ?? part?.fileDiff?.uri;
+                    if (typeof uri === 'string')
+                        try {
+                            const file = basename(decodeURIComponent(new URL(uri).pathname));
+                            if (file && !files.includes(file))
+                                files.push(file);
+                        }
+                        catch { /* Optional display metadata must not break conversation reading. */ }
+                }
+                const status = stepStatus(step.status), summary = raw.metadata?.toolSummary ?? raw.metadata?.toolAction;
+                step.label = status === 'waiting' ? (name === 'ask_question' ? '等待回答…' : '等待批准…') : typeof summary === 'string' && summary.trim() ? summary.slice(0, 200) : (status === 'running' || status === 'pending' ? '正在' : status === 'completed' ? '已' : status === 'failed' ? '失败 · ' : '已停止 · ') + action + (files.length ? ' ' + files.join('、') : '');
+                step.label = step.label.slice(0, 240);
+                step.execution_kind = { edit_file: 'edit', write_to_file: 'write', write_file: 'write', create_file: 'write', read_file: 'read', view_file: 'read', run_command: 'command', run_terminal_command: 'command', ask_question: 'question' }[name] ?? { runCommand: 'command', viewFile: 'read', codeAction: 'edit', generic: 'tool' }[key];
+            }
+        }
+        records.push({ step, turnId });
+    }
+    return records;
+}
+export function conversationPage(records, nextCursor, fullReplies = new Map()) {
+    const turns = new Map();
+    for (const { step, turnId } of records)
+        for (const part of stepParts(step)) {
+            const fields = step.truncated_fields ?? [];
+            const id = partId(step, part.part), reply = part.role === 'assistant';
+            const text = fullReplies.get(id) ?? part.text;
+            const truncated = (!reply && text.length > 1000) || (fields.includes(part.part === 'tools' ? 'tool_calls' : part.part) && !fullReplies.has(id));
+            const item = { id, type: part.role === 'user' ? 'userMessage' : reply ? 'agentMessage' : 'commandExecution', role: part.role, text: reply ? text : text.slice(0, 1000), totalChars: text.length, truncated };
+            item.readId = id + ':' + fingerprint(step);
+            item.groupKey = turnId + ':' + step.step_index;
+            if (part.role === 'tool')
+                item.execution = { kind: part.part === 'thinking' ? 'reasoning' : step.execution_kind ?? 'tool', label: part.label, status: stepStatus(step.status) };
+            if (!turns.has(turnId))
+                turns.set(turnId, { id: turnId, status: 'recorded', items: [] });
+            turns.get(turnId).items.push(item);
+        }
+    return { data: [...turns.values()].reverse(), nextCursor };
+}

package/dist/antigravity-native.js

@@ -0,0 +1,184 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { request } from 'node:https';
+import { readFile, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { Fault, requireValue } from './domain.js';
+const exec = promisify(execFile);
+const app = '/Applications/Antigravity.app/Contents/Resources/app';
+const binary = '/Applications/Antigravity.app/Contents/Resources/bin/language_server';
+/** Same-user desktop process only. Local CSRF credentials never leave this client. */
+export class AntigravityNative {
+    #authority;
+    #checked = 0;
+    ready = false;
+    get generation() { return this.#authority ? this.#authority.pid + ':' + this.#authority.port : ''; }
+    async connect() {
+        if (this.ready && Date.now() - this.#checked < 1000)
+            return;
+        requireValue(process.platform === 'darwin', 'BACKEND_UNAVAILABLE', 'Antigravity 桌面接入需要 macOS', 503);
+        const version = JSON.parse(await readFile(app + '/package.json', 'utf8')).version;
+        requireValue(version === '2.29.0', 'PROTOCOL_INCOMPATIBLE', '当前仅适配 Antigravity App 2.29.0，请核对桌面版本', 503);
+        const { stdout } = await exec('/bin/ps', ['-axo', 'uid,pid,ppid,command'], { maxBuffer: 4 * 1024 * 1024 });
+        const processes = stdout.split('\n').flatMap(line => {
+            const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+            if (!match || Number(match[1]) !== process.getuid?.() || !match[4].startsWith(binary + ' '))
+                return [];
+            const flag = (name) => new RegExp('--' + name + '(?:=|\\s+)([^\\s]+)').exec(match[4])?.[1];
+            if (flag('app_data_dir') !== 'antigravity' || flag('subclient_type') !== 'hub' || flag('override_ide_name') !== 'antigravity')
+                return [];
+            const token = flag('csrf_token');
+            return token ? [{ pid: Number(match[2]), token }] : [];
+        });
+        requireValue(processes.length === 1, 'BACKEND_UNAVAILABLE', '请打开唯一的 Antigravity App 桌面实例', 503);
+        const desktop = processes[0];
+        const { stdout: listeners } = await exec('/usr/sbin/lsof', ['-nP', '-a', '-p', String(desktop.pid), '-iTCP', '-sTCP:LISTEN', '-Fn'], { maxBuffer: 65536 });
+        const ports = [...new Set([...listeners.matchAll(/^n(?:127\.0\.0\.1|\*|\[::1\]):(\d+)$/gm)].map(m => Number(m[1])))];
+        requireValue(ports.length > 0 && ports.length <= 4, 'BACKEND_UNAVAILABLE', '无法核实 Antigravity 桌面监听地址', 503);
+        const executable = await stat(binary);
+        requireValue(executable.isFile() && !(executable.mode & 0o002), 'UNSAFE_STORAGE', 'Antigravity 可执行文件权限异常', 403);
+        let found;
+        for (const port of ports) {
+            const authority = { ...desktop, port };
+            try {
+                const value = await this.rpc(authority, 'GetAllCascadeTrajectories', { excludeSubtrajectories: true }, 5000);
+                if (value.trajectorySummaries && typeof value.trajectorySummaries === 'object') {
+                    found = authority;
+                    break;
+                }
+            }
+            catch { /* Only ports owned by the verified desktop process are considered. */ }
+        }
+        requireValue(found, 'BACKEND_UNAVAILABLE', 'Antigravity 桌面会话接口未就绪', 503);
+        this.#authority = found;
+        this.#checked = Date.now();
+        this.ready = true;
+    }
+    async call(method, params, timeout = 15000, signal) {
+        await this.connect();
+        const authority = this.#authority;
+        try {
+            return await this.rpc(authority, method, params, timeout, signal);
+        }
+        catch (error) {
+            if (!signal?.aborted) {
+                this.ready = false;
+                this.#checked = 0;
+            }
+            throw error;
+        }
+    }
+    async state() {
+        return this.readState('JetboxSubscribeToState', {});
+    }
+    async subscribeAgentState(conversationId, startIndex, onValue, onEnd) {
+        return this.stream('StreamAgentStateUpdates', { conversationId, subscriberId: 'yuanma-live:' + randomUUID(), disableRehydration: true, trajectoryVerbosity: 'CLIENT_TRAJECTORY_VERBOSITY_PROD_UI', initialStepsPageBounds: { startIndex } }, onValue, onEnd);
+    }
+    async readState(method, params) {
+        return new Promise((resolve, reject) => {
+            let close, received = false;
+            void this.stream(method, params, value => { received = true; resolve(value); close?.(); }, error => reject(error ?? new Error('Antigravity 状态流提前结束'))).then(stop => { close = stop; if (received)
+                stop(); }, reject);
+        });
+    }
+    async stream(method, params, onValue, onEnd) {
+        await this.connect();
+        const authority = this.#authority;
+        const payload = Buffer.from(JSON.stringify(params));
+        requireValue(payload.length <= 1024 * 1024, 'PAYLOAD_TOO_LARGE', 'Antigravity 流请求过大', 413);
+        const frame = Buffer.alloc(5 + payload.length);
+        frame.writeUInt32BE(payload.length, 1);
+        payload.copy(frame, 5);
+        let ended = false, received = false;
+        const finish = (error) => { if (ended)
+            return; ended = true; clearTimeout(first); req.destroy(); onEnd(error); };
+        const req = request({ hostname: '127.0.0.1', port: authority.port, path: '/exa.language_server_pb.LanguageServerService/' + method, method: 'POST', rejectUnauthorized: false, headers: { 'content-type': 'application/connect+json', 'connect-protocol-version': '1', 'x-codeium-csrf-token': authority.token } }, res => {
+            if (res.statusCode !== 200) {
+                finish(new Error('Antigravity 状态订阅不可用（HTTP ' + res.statusCode + '）'));
+                return;
+            }
+            if (!res.headers['content-type']?.startsWith('application/connect+json')) {
+                finish(new Error('Antigravity 状态订阅协议不兼容'));
+                return;
+            }
+            let buffer = Buffer.alloc(0);
+            res.on('data', (chunk) => {
+                if (ended)
+                    return;
+                buffer = Buffer.concat([buffer, chunk]);
+                try {
+                    while (buffer.length >= 5) {
+                        const flags = buffer[0], length = buffer.readUInt32BE(1);
+                        if (length > 32 * 1024 * 1024)
+                            throw new Error('Antigravity 状态帧过大');
+                        if (buffer.length < 5 + length)
+                            break;
+                        const value = JSON.parse(buffer.subarray(5, 5 + length).toString('utf8'));
+                        buffer = buffer.subarray(5 + length);
+                        if (flags === 2) {
+                            finish(value.error ? new Error('Antigravity 状态订阅中断') : undefined);
+                            return;
+                        }
+                        if (flags !== 0)
+                            throw new Error('Antigravity 状态帧不兼容');
+                        received = true;
+                        clearTimeout(first);
+                        onValue(value);
+                        if (ended)
+                            return;
+                    }
+                }
+                catch {
+                    finish(new Error('Antigravity 状态帧解析失败'));
+                }
+            });
+            res.on('end', () => finish(buffer.length ? new Error('Antigravity 状态帧不完整') : received ? undefined : new Error('Antigravity 状态流为空')));
+            res.on('error', () => finish(new Error('Antigravity 状态连接中断')));
+            res.on('aborted', () => finish(new Error('Antigravity 状态连接中断')));
+        });
+        const first = setTimeout(() => finish(new Error('Antigravity 状态订阅超时')), 10000);
+        first.unref();
+        req.on('error', () => finish(new Error('Antigravity 桌面连接中断')));
+        req.end(frame);
+        return () => { ended = true; clearTimeout(first); req.destroy(); };
+    }
+    rpc(authority, method, params, timeout, signal) {
+        return new Promise((resolve, reject) => {
+            const payload = Buffer.from(JSON.stringify(params));
+            if (payload.length > 32 * 1024 * 1024) {
+                reject(new Fault('PAYLOAD_TOO_LARGE', 'Antigravity 输入超过接口容量限制', 413));
+                return;
+            }
+            // Match the desktop's trust policy only for the loopback port owned by its verified PID.
+            // Never disable TLS validation globally or forward this authorization to a remote host.
+            const req = request({ hostname: '127.0.0.1', port: authority.port, path: '/exa.language_server_pb.LanguageServerService/' + method, method: 'POST', rejectUnauthorized: false, signal, headers: { 'content-type': 'application/json', 'connect-protocol-version': '1', 'content-length': payload.length, 'x-codeium-csrf-token': authority.token } }, res => {
+                let size = 0;
+                const chunks = [];
+                res.on('data', (chunk) => { size += chunk.length; if (size > 32 * 1024 * 1024) {
+                    req.destroy(new Error('Antigravity 返回内容超过容量限制'));
+                    return;
+                } chunks.push(chunk); });
+                res.on('error', () => reject(new Error('Antigravity 本地响应中断，结果可能未知')));
+                res.on('end', () => {
+                    let value;
+                    try {
+                        value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    }
+                    catch {
+                        reject(new Error('Antigravity 返回了不兼容的响应'));
+                        return;
+                    }
+                    if (res.statusCode !== 200) {
+                        reject(Object.assign(new Error('Antigravity 本地请求未完成，需核对原生状态'), { rpcError: { code: value.code, message: value.message } }));
+                        return;
+                    }
+                    resolve(value);
+                });
+            });
+            req.on('error', () => reject(new Error('Antigravity 桌面连接中断，结果可能未知')));
+            req.setTimeout(timeout, () => req.destroy(new Error('Antigravity 本地请求超时')));
+            req.end(payload);
+        });
+    }
+    close() { this.#authority = undefined; this.#checked = 0; this.ready = false; }
+}