agy-mcp-bridge 0.1.19 → 0.1.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -421
- package/config/workspaces.example.json +4 -0
- package/dist/src/agents/antigravity.js +1 -1
- package/dist/src/agents/registry.js +1 -1
- package/dist/src/antigravity/process.js +5 -3
- package/dist/src/config.js +9 -0
- package/dist/src/isolation/orphans.js +281 -0
- package/dist/src/isolation/worktree.js +195 -5
- package/dist/src/models.js +2 -2
- package/dist/src/runtime.js +27 -5
- package/dist/src/tasks/manager.js +91 -8
- package/docs/HARDENING.md +13 -1
- package/docs/VERIFICATION.md +6 -2
- package/package.json +2 -1
- package/ui/app.css +10 -2
- package/ui/app.js +105 -44
package/README.md
CHANGED
|
@@ -1,482 +1,132 @@
|
|
|
1
|
-
#
|
|
1
|
+
# agy-mcp-bridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**An MCP server that hands bounded coding tasks to the CLI agents already logged in on your machine.** One TypeScript process speaks MCP Streamable HTTP on `127.0.0.1` and drives `agy` (Antigravity) and/or `codex`. Every task declares its workspace, acceptance criteria, which agent runs it, how isolated it is, and how much it may self-approve. The orchestrating agent (Codex, Claude Code, any MCP client) keeps the review; the bridge does the reading, writing and waiting.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> **There is no authentication, on purpose.** The bridge binds `127.0.0.1` only, but any process running as your user on this machine can call its tools, read and cancel tasks, and shut it down. Do not expose the port, do not put it behind a public reverse proxy, do not run it where you do not control local processes. [Security model](#security-model).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Package `agy-mcp-bridge` on npm · requires Node.js ≥ 20 · Git · a logged-in `agy` 1.4.x and/or Codex CLI.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
npm install -g agy-mcp-bridge # cần Node.js >= 20; Antigravity CLI `agy` 1.4.x và/hoặc Codex CLI là tùy chọn
|
|
11
|
-
agy-mcp-bridge workspaces add /duong/dan/toi/project # cấp quyền cho một thư mục (khởi động lại server sau khi đổi)
|
|
12
|
-
agy-mcp-bridge # mở server http://127.0.0.1:3000 ; giao diện web ở /ui
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Bridge tự dò `agy` và `codex` khi khởi động; agent nào không có thì bị đánh dấu unavailable và không nhận task. Chọn thứ tự ưu tiên và bật/tắt từng agent trong `agents` của `config/workspaces.json`.
|
|
16
|
-
|
|
17
|
-
**Cách nhanh nhất:** mở terminal tại thư mục dự án rồi chạy `agy-mcp-bridge --workspace .` (cho phép thư mục hiện tại **chỉ trong lần chạy này**, không lưu vào cấu hình; có thể lặp lại cờ cho nhiều thư mục, và log in ra từng thư mục đã được cho phép; thư mục sai hoặc là chính thư mục cài bridge thì dừng ngay, không khởi động server). Muốn lưu lâu dài thì dùng `agy-mcp-bridge workspaces add .`. Trong giao diện web, mục Cài đặt đánh dấu "chỉ lần chạy này" bên cạnh các thư mục này.
|
|
18
|
-
|
|
19
|
-
Các lệnh khác: `agy-mcp-bridge check | setup codex|claude|both | delegation on|off|status | skill install --client codex|claude|both | config | update | help`. Thêm `--open` để tự mở giao diện web trong trình duyệt mặc định khi server đã chạy (`agy-mcp-bridge --open`). Cấu hình và lịch sử task nằm trong thư mục dữ liệu của người dùng (Linux `~/.config/agy-mcp-bridge`, macOS `~/Library/Application Support/agy-mcp-bridge`, Windows `%APPDATA%\agy-mcp-bridge`), không nằm trong thư mục cài đặt nên không mất khi cập nhật; đổi chỗ bằng `BRIDGE_HOME`. `agy-mcp-bridge config` in ra các đường dẫn thật. Phần dưới đây dùng `npm start`/`npm run ...` cho bản clone từ git; với bản cài từ npm hãy dùng lệnh `agy-mcp-bridge` tương ứng.
|
|
20
|
-
|
|
21
|
-
**Skill cho Codex / Claude Code:** gói npm chứa file skill nhưng `npm install` không tự ghi vào thư mục cấu hình của client. Thay vào đó, lần đầu bạn chạy `agy-mcp-bridge` trong terminal tương tác, bridge hiện đường dẫn sẽ ghi rồi hỏi `Install it now? [codex / claude / both / N]`. Chọn mới cài (chỉ cho client chưa có skill; skill bạn đã tự sửa không bao giờ bị đụng tới); chọn `N` hoặc nhấn Enter thì không cài gì và không hỏi lại (câu trả lời lưu ở `onboarding.json` trong thư mục state). Không hỏi khi chạy ngoài terminal tương tác hoặc `CI=true`; tắt hẳn bằng `--no-skill-prompt` hoặc `BRIDGE_NO_SKILL_PROMPT=1`. Cài sau bất kỳ lúc nào bằng `agy-mcp-bridge skill install --client both`. Lỗi khi cài chỉ được báo, server vẫn khởi động. Khi đã cài mà gói có skill mới hơn, bridge hỏi riêng một lần cho việc cập nhật (chỉ với bản cũ do gói phát hành; bản bạn tự sửa không bao giờ được đề nghị hay bị đụng tới).
|
|
22
|
-
|
|
23
|
-
**Cập nhật:** khi chạy bản cài từ npm, bridge hỏi npm registry bản mới nhất (tối đa một lần mỗi ngày, timeout 3 giây, lỗi mạng thì bỏ qua). Có bản mới và đang ở terminal tương tác thì hỏi `Update now with "npm install -g agy-mcp-bridge@X"? [y/N]`: chọn `y` mới chạy `npm install -g`, rồi thoát để bạn chạy lại bản mới; chọn `n` thì chạy tiếp và hỏi lại sau 24 giờ. Không bao giờ tự cập nhật âm thầm; ngoài terminal tương tác chỉ in thông báo; khi server đang chạy, giao diện web và log hiện thông báo kèm lệnh `agy-mcp-bridge update` (lệnh này, hoặc `update --check` để chỉ xem). Tắt hoàn toàn bằng `--no-update-check` hoặc `BRIDGE_NO_UPDATE_CHECK=1`; tự tắt khi `CI=true` và với bản clone từ git. Lần kiểm tra chỉ gửi một request GET tên gói tới registry (lộ địa chỉ IP như mọi lần `npm view`).
|
|
24
|
-
|
|
25
|
-
**Phát hành tự động lên npm:** mỗi lần push hoặc merge vào `main`, workflow [publish.yml](.github/workflows/publish.yml) chạy CI trên Windows/Linux với Node 20/22, gồm test và cài thử gói đã pack. Khi toàn bộ CI đạt, job release dùng Node 24 chạy `npm version patch --no-git-tag-version`, commit hai manifest, tạo tag `vX.Y.Z`, push commit/tag và chạy `npm publish`. Bạn không cần tự tăng version, tạo tag hay đăng nhập npm cho mỗi lần phát hành. Nếu CI lỗi thì không tăng version và không publish. PR chỉ chạy [CI](.github/workflows/ci.yml), chưa phát hành.
|
|
26
|
-
|
|
27
|
-
Cấu hình một lần tại [Settings của gói npm](https://www.npmjs.com/package/agy-mcp-bridge/access), phần **Trusted Publisher**, chọn GitHub Actions:
|
|
28
|
-
|
|
29
|
-
- Organization or user: `thanhdo257205`
|
|
30
|
-
- Repository: `MCP-bridge`
|
|
31
|
-
- Workflow filename: `publish.yml` (không nhập đường dẫn đầy đủ)
|
|
32
|
-
- Environment name: để trống
|
|
33
|
-
- Cho phép **npm publish** để phát hành trực tiếp.
|
|
34
|
-
|
|
35
|
-
Workflow dùng OIDC với `id-token: write` riêng cho job publish, không cần npm token trong GitHub Secrets hay OTP mỗi lần chạy. Job này cần `contents: write` để ghi commit tăng version và tag bằng `GITHUB_TOKEN`; push do token này tạo không kích hoạt workflow push khác, nên không tạo vòng lặp phát hành. npm tự tạo provenance cho bản phát hành. Xem [tài liệu Trusted Publishing](https://docs.npmjs.com/trusted-publishers/). Việc cấp quyền lần đầu có thể yêu cầu 2FA; không đưa token hoặc OTP vào repo.
|
|
36
|
-
|
|
37
|
-
Từ bản clone trên nhánh `main`, chỉ cần commit và push code như bình thường:
|
|
9
|
+
## Install
|
|
38
10
|
|
|
39
11
|
```bash
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
# Chỉnh sửa code, git add và git commit như bình thường
|
|
44
|
-
git push origin main
|
|
12
|
+
npm install -g agy-mcp-bridge
|
|
13
|
+
agy-mcp-bridge workspaces add /path/to/your/project # grant one folder (restart to apply)
|
|
14
|
+
agy-mcp-bridge # serves http://127.0.0.1:3000, UI at /ui
|
|
45
15
|
```
|
|
46
16
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Các job release được tuần tự hóa. Khi nhiều push liên tiếp, CI cũ không phát hành nếu `main` đã có code mới hơn; bản mới nhất chỉ phát hành sau khi CI của chính nó đạt. Push commit version và tag là một giao dịch atomic, không force-push: nếu ai đó push code trong lúc tăng version, giao dịch bị từ chối và không publish code chưa kiểm thử. Chỉ hai manifest được đổi version sau CI; mọi thay đổi code khác đều bị chặn.
|
|
50
|
-
|
|
51
|
-
Nếu publish lỗi sau khi commit version/tag đã được push, dùng **Re-run failed jobs** của lượt workflow đó: job nhận diện commit release từ cùng SHA nguồn, giữ nguyên version và tag thay vì tăng lần nữa. Registry đã có version đó thì bỏ qua publish; lỗi mạng/registry khác không bị coi nhầm là chưa đăng. Nếu đã có push mới hơn, lượt cũ bị bỏ qua và CI mới phụ trách phát hành. Không chạy `npm publish` hoặc tự tạo tag release song song; trigger theo tag cũ đã được thay bằng trigger theo `main`. Kiểm tra kết quả bằng `npm view agy-mcp-bridge version`; registry có thể mất vài phút để xử lý. Gói sử dụng giấy phép MIT và chứa file `LICENSE`.
|
|
52
|
-
|
|
53
|
-
## Quickstart
|
|
54
|
-
|
|
55
|
-
Requires Git, Node.js ≥20 and a logged-in Antigravity CLI `agy` 1.4.x on PATH (real agent execution was verified on 1.4.3 and 1.4.7). The longer sections below use PowerShell; the POSIX equivalents are:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
git clone https://github.com/thanhdo257205/MCP-bridge.git && cd MCP-bridge
|
|
59
|
-
agy --version && npm ci && npm run build
|
|
60
|
-
npm start # terminal 1: server on http://127.0.0.1:3000/mcp
|
|
61
|
-
npm run check # terminal 2, same clone: calls antigravity_environment
|
|
62
|
-
```
|
|
17
|
+
Fastest first run: from inside the project you want to work on, `agy-mcp-bridge --workspace .` grants the current directory **for this run only** and does not touch config. Repeat the flag for several folders; a wrong path, or the bridge's own install directory, stops startup.
|
|
63
18
|
|
|
64
|
-
|
|
19
|
+
`agy-mcp-bridge check | setup codex|claude|both | delegation on|off|status | skill install | config | update | help`. `--open` launches the web UI in your browser. Config and task history live in the user data directory (`%APPDATA%\agy-mcp-bridge`, `~/.config/agy-mcp-bridge`, `~/Library/Application Support/agy-mcp-bridge`; override with `BRIDGE_HOME`), so an upgrade never deletes them. `agy-mcp-bridge config` prints the real paths.
|
|
65
20
|
|
|
66
|
-
|
|
21
|
+
At startup the bridge probes each CLI. An agent that is missing or unsupported is marked unavailable and takes no task; if `agy` is unavailable, the default agent silently becomes the next enabled one, so check `agents_list` after changing machines. Priority and per-agent switches live under `agents` in `config/workspaces.json`. Verified against real agent execution on `agy` 1.4.3 and 1.4.7; other 1.4.x patches run with a logged warning; other majors are refused.
|
|
67
22
|
|
|
68
|
-
|
|
23
|
+
From a git clone instead of npm: `npm ci && npm run build && npm start`, then `npm run check` in a second terminal. `npm run dev` builds and runs; there is no hot reload, because an automatic restart would cut off a task mid-edit.
|
|
69
24
|
|
|
70
|
-
|
|
25
|
+
## Connect a client
|
|
71
26
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
```powershell
|
|
75
|
-
git clone https://github.com/thanhdo257205/MCP-bridge.git
|
|
76
|
-
Set-Location .\MCP-bridge
|
|
77
|
-
agy --version
|
|
78
|
-
npm install
|
|
79
|
-
npm run build
|
|
80
|
-
npm start
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Nếu đã clone, mở terminal tại thư mục gốc của bản clone (nơi có `package.json`) và bỏ qua hai lệnh clone/chuyển thư mục. Các đường dẫn tương đối trong hướng dẫn được tính từ thư mục này; bạn có thể lưu repo ở bất kỳ vị trí nào.
|
|
84
|
-
|
|
85
|
-
Mặc định bridge tìm `agy` trong PATH, không phụ thuộc tên tài khoản Windows hay thư mục cài đặt của tác giả. Nếu không tìm thấy, kiểm tra `Get-Command agy`; thêm thư mục cài CLI vào PATH rồi mở terminal mới, hoặc đặt `executable` trong `config/workspaces.json` thành đường dẫn tuyệt đối tới `agy.exe` trên máy của bạn.
|
|
86
|
-
|
|
87
|
-
`npm ci` có thể thay `npm install` để cài đúng lockfile.
|
|
88
|
-
|
|
89
|
-
Repo kèm skill **antigravity-bridge** để client giao task và xử lý kết quả theo đúng hợp đồng MCP. Sau build, xem [cách cài skill cho Codex/Claude Code](#9-skill-giao-tiếp-với-antigravity) để cài bằng một lệnh. `npm install` chỉ cài dependency, không tự ghi vào thư mục cấu hình hay skill của client.
|
|
90
|
-
|
|
91
|
-
Chế độ phát triển:
|
|
92
|
-
|
|
93
|
-
```powershell
|
|
94
|
-
npm run dev
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
`dev` build rồi chạy HTTP; hiện không có hot reload. Sau khi sửa source, Ctrl+C rồi chạy `npm run dev` lại. Không tự restart để tránh gián đoạn task đang sửa code.
|
|
98
|
-
|
|
99
|
-
Server giữ terminal hoạt động tới khi **Ctrl+C**, SIGTERM hoặc lỗi nghiêm trọng. Việc đóng Codex, Claude Code hoặc stdin của bridge không dừng HTTP server. Đóng cưỡng bức cửa sổ terminal không tương đương shutdown an toàn.
|
|
100
|
-
|
|
101
|
-
Mặc định bind duy nhất `127.0.0.1:3000`. Khi cổng còn trống, terminal in:
|
|
102
|
-
|
|
103
|
-
```text
|
|
104
|
-
[bridge] HTTP server: http://127.0.0.1:3000
|
|
105
|
-
[bridge] MCP endpoint: http://127.0.0.1:3000/mcp
|
|
106
|
-
[bridge] Health check: http://127.0.0.1:3000/health
|
|
107
|
-
[bridge] No authentication: any local process running as this user can control the bridge. Keep it on this machine.
|
|
108
|
-
[bridge] Web UI: http://127.0.0.1:3000/ui (open in a browser on this machine)
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
Dòng `Web UI` là đường dẫn tới giao diện web; nhấn giữ Ctrl (hoặc Cmd) và bấm vào nó trong terminal hỗ trợ liên kết để mở trình duyệt.
|
|
112
|
-
|
|
113
|
-
Cổng bị chiếm: server báo lỗi, thoát mã 1, không tự đổi cổng hoặc địa chỉ bind. Chọn cổng khác:
|
|
114
|
-
|
|
115
|
-
```powershell
|
|
116
|
-
$env:PORT = '3001'
|
|
117
|
-
npm start
|
|
118
|
-
```
|
|
27
|
+
`agy-mcp-bridge setup codex` (or `claude`, `both`, with `--port` and `--shell`) prints the exact lines for your machine and changes nothing; `setup codex --apply` shows the diff, asks, and backs up `config.toml` first.
|
|
119
28
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
## 2. Không xác thực và health check
|
|
123
|
-
|
|
124
|
-
Bridge **không có bearer token**. `/mcp` và `/health` nhận request trực tiếp từ loopback. Đây là lựa chọn có chủ đích cho công cụ cục bộ; đổi lại, bất kỳ tiến trình nào trên cùng máy với cùng user đều có thể dùng tool, xem và hủy task, hoặc tắt server. Chỉ chạy bridge trên máy cá nhân hoặc máy bạn kiểm soát hoàn toàn.
|
|
125
|
-
|
|
126
|
-
Các lớp bảo vệ còn lại: chỉ bind `127.0.0.1`, kiểm tra `Host`/`Origin`, giới hạn body, timeout, allowlist workspace và allowlist biến môi trường cho tiến trình con.
|
|
127
|
-
|
|
128
|
-
Mở **terminal thứ hai tại thư mục gốc của cùng bản clone** (nơi có `package.json`):
|
|
129
|
-
|
|
130
|
-
```powershell
|
|
131
|
-
Invoke-RestMethod 'http://127.0.0.1:3000/health'
|
|
132
|
-
npm run check
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
`npm run check` không khởi động server hay gọi AI; nó kết nối HTTP và gọi `antigravity_environment`. Khi server tắt hoặc URL sai, script thoát mã 1 và hướng dẫn chạy `npm start`, kiểm tra PORT/URL, rồi kết nối lại.
|
|
136
|
-
|
|
137
|
-
Với cổng khác, ví dụ 3001:
|
|
138
|
-
|
|
139
|
-
```powershell
|
|
140
|
-
$env:BRIDGE_MCP_URL = 'http://127.0.0.1:3001/mcp'
|
|
141
|
-
npm run check
|
|
142
|
-
Invoke-RestMethod 'http://127.0.0.1:3001/health'
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
`BRIDGE_MCP_URL` dành cho script check; URL của Codex và Claude Code phải cập nhật riêng. Child `agy` chỉ nhận allowlist môi trường; tên chứa `TOKEN`, `SECRET`, `PASSWORD`, `API_KEY` bị chặn mặc định. Chỉ dùng `extra_env_passthrough` cho biến thực sự cần. Xem danh sách và ví dụ trong [HARDENING.md](docs/HARDENING.md).
|
|
146
|
-
|
|
147
|
-
## 3. Kết nối Codex
|
|
148
|
-
|
|
149
|
-
> Muốn có sẵn đúng lệnh cho máy của bạn (cổng, PowerShell/cmd/bash) chạy `agy-mcp-bridge setup codex` hoặc `setup claude` (hoặc `setup both`, thêm `--port` và `--shell` nếu cần). Lệnh chỉ in ra, không sửa cấu hình của Codex hay Claude Code; bạn xem rồi tự áp dụng.
|
|
150
|
-
|
|
151
|
-
**Các đoạn dưới là thay đổi đề xuất, chưa áp dụng.** Trình bày để chủ máy duyệt trước khi chạy lệnh ghi cấu hình. Mẫu: [config/codex-mcp.windows.toml](config/codex-mcp.windows.toml).
|
|
29
|
+
Codex — `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`):
|
|
152
30
|
|
|
153
31
|
```toml
|
|
154
32
|
[mcp_servers.antigravity]
|
|
155
33
|
url = 'http://127.0.0.1:3000/mcp'
|
|
156
34
|
startup_timeout_sec = 30
|
|
157
35
|
tool_timeout_sec = 115
|
|
158
|
-
enabled = true
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
File cấu hình Codex mặc định là `~/.codex/config.toml` (trên Windows: `$env:USERPROFILE\.codex\config.toml`). Nếu bạn đã đặt biến môi trường `CODEX_HOME`, dùng file `config.toml` trong thư mục đó. Nếu đã có mục antigravity kiểu command/args, thay mục đó bằng HTTP sau khi được duyệt, không tạo mục trùng. Không còn command/args nên Codex không spawn bridge.
|
|
162
|
-
|
|
163
|
-
Sau khi được duyệt có thể dùng CLI thay cho merge TOML (CLI dùng timeout mặc định, thêm timeout bằng TOML nếu cần):
|
|
164
|
-
|
|
165
|
-
```powershell
|
|
166
|
-
codex mcp add antigravity --url 'http://127.0.0.1:3000/mcp'
|
|
167
|
-
codex mcp get antigravity
|
|
168
|
-
codex mcp list
|
|
169
|
-
codex
|
|
170
36
|
```
|
|
171
37
|
|
|
172
|
-
|
|
38
|
+
Claude Code:
|
|
173
39
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
Khi đổi cổng, sửa `url` rồi mở phiên mới. Khi server tắt, Codex báo lỗi kết nối/MCP startup. Không có tiến trình HTTP nào có thể tự trả hướng dẫn khi nó đã tắt; chạy `npm run check` để có chẩn đoán và hướng dẫn cụ thể, sau đó `npm start` ở terminal server và mở lại phiên Codex.
|
|
177
|
-
|
|
178
|
-
Tham khảo [tài liệu MCP chính thức của Codex](https://developers.openai.com/codex/mcp/).
|
|
179
|
-
|
|
180
|
-
## 4. Kết nối Claude Code
|
|
181
|
-
|
|
182
|
-
Mẫu cấu hình đề xuất ở [config/claude-mcp.http.json](config/claude-mcp.http.json), chưa ghi vào cấu hình hiện có:
|
|
183
|
-
|
|
184
|
-
```json
|
|
185
|
-
{
|
|
186
|
-
"mcpServers": {
|
|
187
|
-
"antigravity": {
|
|
188
|
-
"type": "http",
|
|
189
|
-
"url": "http://127.0.0.1:3000/mcp"
|
|
190
|
-
}
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
Sau khi duyệt, từ thư mục project của bạn:
|
|
196
|
-
|
|
197
|
-
```powershell
|
|
40
|
+
```bash
|
|
198
41
|
claude mcp add --transport http --scope local antigravity 'http://127.0.0.1:3000/mcp'
|
|
199
|
-
claude mcp get antigravity
|
|
200
|
-
claude mcp list
|
|
201
|
-
claude
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
`--scope local` chỉ cấu hình cho project và người dùng hiện tại. Mẫu JSON wrapper dành cho `.mcp.json`; không tự tạo file đó trong repository ứng dụng.
|
|
205
|
-
|
|
206
|
-
Trong Claude Code dùng `/mcp` để xem trạng thái, reconnect hoặc disable server, và gọi `antigravity_environment` để kiểm tra tool. Nếu server tắt, `/mcp` hiển thị lỗi kết nối; chạy `npm run check`, bật server bằng `npm start`, rồi reconnect qua `/mcp` hoặc mở lại phiên. Thoát Claude Code/disable kết nối không hủy task.
|
|
207
|
-
|
|
208
|
-
Gỡ sau khi duyệt: `claude mcp remove antigravity --scope local`. Đổi cổng: cập nhật URL trong cùng entry, hoặc remove rồi add lại URL mới, sau đó reconnect. Không cần dừng server vì client ngắt kết nối.
|
|
209
|
-
|
|
210
|
-
Tham khảo [tài liệu MCP chính thức của Claude Code](https://code.claude.com/docs/en/mcp). Các phiên bản CLI và kết quả đã kiểm chứng được ghi trong [báo cáo khảo sát](docs/VERIFICATION.md). Sau khi cấu hình trên máy của bạn, hãy gọi tool thật từ từng client để kiểm tra kết nối; kiểm thử protocol bằng SDK không thay thế bước này.
|
|
211
|
-
|
|
212
|
-
## 5. Cho phép workspace và giao task
|
|
213
|
-
|
|
214
|
-
`config/workspaces.json` là file cục bộ, không nằm trong git; lần chạy đầu tự tạo với `allowed_workspaces: []` (không file nào bị ghi đè). Chỉ thêm đường dẫn tuyệt đối đã được cấp quyền; [mẫu](config/workspaces.example.json). Có thể chọn file JSON khác qua env `ANTIGRAVITY_BRIDGE_CONFIG`; restart server để áp dụng. Đừng giao workspace chứa chính source bridge đang chạy.
|
|
215
|
-
|
|
216
|
-
Đăng ký client thành công chưa cấp quyền sửa file cho Antigravity. Lần thử thật trước đây bị `write_file` từ chối. Cần phê duyệt rule tối thiểu trong settings Antigravity hoặc cấp quyền qua phiên tương tác, rồi kiểm thử lại. Ví dụ **chưa áp dụng**:
|
|
217
|
-
|
|
218
|
-
```json
|
|
219
|
-
{"permissions":{"allow":["write_file(C:/absolute/path/to/approved-project/)"]}}
|
|
220
42
|
```
|
|
221
43
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
Luồng sử dụng trong Codex hoặc Claude Code:
|
|
44
|
+
Then call `antigravity_environment` from a fresh session — that is the proof; `codex mcp list` and `/mcp` only show configuration. Closing or disconnecting a client does not stop the server or cancel an accepted task. Reconnect, read `recent_tasks`, and reuse the task id instead of delegating the same work twice.
|
|
225
45
|
|
|
226
|
-
|
|
227
|
-
2. Gọi `antigravity_delegate` với arguments mẫu ở dưới.
|
|
228
|
-
3. Lưu `task_id`; gọi `antigravity_task_wait` (mỗi lần chờ tối đa `max_wait_seconds`, mặc định 55 giây, trả sớm khi task xong) hoặc `antigravity_task_status`, rồi lấy `antigravity_task_output`.
|
|
229
|
-
4. Nếu client bị đóng, bật lại client, gọi environment để xem `recent_tasks`, rồi query task ID cũ. Không giao trùng task khi chưa kiểm tra trạng thái.
|
|
230
|
-
5. Tech Lead review diff thực tế, gồm file untracked, chạy test và đánh giá từng tiêu chí. Nếu chưa đạt, giao task sửa tiếp.
|
|
46
|
+
## Delegate
|
|
231
47
|
|
|
232
48
|
```json
|
|
233
49
|
{
|
|
234
|
-
"task": "
|
|
50
|
+
"task": "Reject negative input in parseCount in src/count.ts. Change this function and its tests only. Do not run commands; the reviewer runs tests.",
|
|
235
51
|
"workspace": "C:/absolute/path/to/approved-project",
|
|
236
|
-
"acceptance_criteria": ["
|
|
237
|
-
"timeout_seconds": 300,
|
|
238
|
-
"agent": "codex",
|
|
239
|
-
"autonomy": "auto"
|
|
240
|
-
}
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
Task chạy song song an toàn dùng `isolation: "worktree"` và khai báo đúng các đường dẫn agent được sửa trong `owns`:
|
|
244
|
-
|
|
245
|
-
```json
|
|
246
|
-
{
|
|
247
|
-
"task": "Thêm validate cho parser và test tương ứng.",
|
|
248
|
-
"workspace": "C:/absolute/path/to/approved-project",
|
|
249
|
-
"acceptance_criteria": ["Test mới chạy qua"],
|
|
52
|
+
"acceptance_criteria": ["Negative input returns the existing validation error", "0 and positive values keep their behaviour"],
|
|
250
53
|
"agent": "codex",
|
|
251
54
|
"isolation": "worktree",
|
|
252
|
-
"owns": ["src/
|
|
55
|
+
"owns": ["src/count.ts", "test/count.test.ts"],
|
|
56
|
+
"autonomy": "auto",
|
|
57
|
+
"timeout_seconds": 300
|
|
253
58
|
}
|
|
254
59
|
```
|
|
255
60
|
|
|
256
|
-
|
|
257
|
-
- `isolation`: `none` (mặc định, sửa trực tiếp workspace, chạy tuần tự toàn cục) hoặc `worktree` (tạo branch `bridge/<task_id>` trong `.bridge-state/worktrees/<task_id>`, chạy song song tối đa `max_parallel_worktrees`). Task worktree bắt buộc có `owns`.
|
|
258
|
-
- `owns`: đường dẫn tương đối trong workspace. Sau khi agent xong, bridge so diff thực tế với danh sách này; file ngoài phạm vi được báo trong `scope.out_of_scope` và task cần review. Bridge **không tự merge** worktree.
|
|
259
|
-
- `autonomy`: `suggest` | `auto` | `full` (mặc định lấy `default_autonomy`, thường là `auto`). Đây là chỉ dẫn cho agent CLI; các hành động phá hủy, deploy, xóa dữ liệu, đọc credential và thay đổi hệ thống vẫn bị cấm tuyệt đối, không có cờ bypass permission.
|
|
260
|
-
|
|
261
|
-
| Tool | Công dụng |
|
|
61
|
+
| Field | Meaning |
|
|
262
62
|
|---|---|
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `antigravity_task_wait` | Chờ tối đa `wait_seconds` (1 đến `max_wait_seconds`, mặc định là mức tối đa, 55 giây) tới khi task kết thúc, trả cùng nội dung như status; còn chạy thì gọi lại |
|
|
268
|
-
| `antigravity_task_output` | Phản hồi cuối, stdout/stderr, lỗi, denied_actions, truncation theo task_id |
|
|
269
|
-
| `antigravity_cancel_task` | Hủy cây tiến trình thuộc task; không rollback thay đổi file |
|
|
270
|
-
|
|
271
|
-
`completed` chỉ là CLI chạy xong và có kết quả hợp lệ. Luôn `review_required=true`, `acceptance_verified=false`. SUCCESS/exit 0 vẫn có thể bị bridge đánh dấu failed do permission denial hoặc timeout. Prompt mẫu review/sửa tiếp: [docs/PROMPTS.md](docs/PROMPTS.md).
|
|
272
|
-
|
|
273
|
-
### Để Codex/Claude tự chia việc dễ khó và tiết kiệm token (chế độ tùy chọn)
|
|
274
|
-
|
|
275
|
-
Mặc định agent chỉ giao việc khi bạn nhắc Antigravity. Nếu muốn agent tự quyết định, hãy nói rõ trong cuộc trò chuyện, ví dụ "tự phân loại việc" hoặc "tiết kiệm token bên Codex". Khi đó agent làm theo quy trình sau (do skill quy định):
|
|
276
|
-
|
|
277
|
-
- **Việc dễ** (một mục tiêu, tối đa 3 file kèm test, tiêu chí nghiệm thu cụ thể, không phụ thuộc ngữ cảnh ngoài repo): giao trọn cho Antigravity đọc file cần thiết, sửa, chạy các kiểm tra bạn đã cho phép và báo cáo; agent xem diff. Antigravity chỉ chạy được lệnh khi mức quyền `agy_permissions` cho phép; ở mức mặc định lệnh bị từ chối, nên agent tự chạy kiểm tra.
|
|
278
|
-
- **Việc khó** (thiết kế, nhiều file phụ thuộc nhau, yêu cầu mơ hồ, lỗi chưa rõ nguyên nhân): agent tự phân tích phạm vi và thiết kế trước, chỉ giao phần triển khai đã đủ rõ để viết tiêu chí nghiệm thu, từng task một; phần rủi ro tự làm hoặc review kỹ.
|
|
279
|
-
- **Không bao giờ giao** (kể cả trong chế độ này): bảo mật, xác thực, secret; di chuyển hoặc xóa dữ liệu; triển khai; phụ thuộc, build, CI; thay đổi API công khai. Không chắc thì coi là việc khó.
|
|
280
|
-
- **Tránh đọc trùng:** không đọc cả codebase trước khi giao; chỉ đưa ngữ cảnh cần thiết. **Theo dõi ít:** dùng vài lượt chờ dài, lấy báo cáo khi xong, không đọc log liên tục.
|
|
281
|
-
- **Kiểm tra vừa đủ:** kết quả kiểm tra do Antigravity báo chỉ là gợi ý, không phải bằng chứng (bridge luôn báo `acceptance_verified=false`). Agent có thể bỏ qua việc chạy lại các kiểm tra nhỏ, ít rủi ro mà Antigravity báo đã qua, nhưng **tự chạy một lần** kiểm tra chính bao phủ thay đổi (test, build hoặc lint) ở cuối, luôn làm vậy với thay đổi rủi ro, và chạy lại sau mọi sửa đổi thêm của chính nó.
|
|
282
|
-
- **Báo cáo ngắn:** file đã đổi, kết quả kiểm tra, lỗi còn lại, và phần nào do Antigravity làm, phần nào do agent làm; nói một dòng lý do trước khi giao. Mọi diff giao đi đều được xem lại; task giao đi lỗi, hết giờ hoặc kém thì agent tự làm tiếp thay vì gửi lại nhiều lần.
|
|
283
|
-
|
|
284
|
-
Bạn kết thúc chế độ bất cứ lúc nào bằng cách bảo agent tự làm hết; công tắc giao việc và lời từ chối của bạn luôn có hiệu lực trước. Đây là chỉ dẫn cho agent, không phải rào chắn kỹ thuật, và việc phân loại dựa trên phán đoán của agent. Các tình huống kiểm tra thủ công ở [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) (11 đến 17).
|
|
285
|
-
|
|
286
|
-
### Khi chỉ muốn Codex/Claude tự làm
|
|
287
|
-
|
|
288
|
-
- **Công tắc cứng (khuyến nghị):** `npm run delegation -- off` chặn mọi lần giao task mới ngay lập tức, không cần restart. `npm run delegation -- on` bật lại, `-- status` xem trạng thái. Có thể đặt `BRIDGE_DELEGATION=off` trước `npm start` (giá trị khác `on`/`off` cũng bị coi là tắt). Khi tắt, `antigravity_delegate` trả lỗi nêu rõ "disabled by the bridge owner" và `antigravity_environment` trả `delegation: {enabled: false, reason}`. Task đang chạy không bị dừng và vẫn xem/hủy được.
|
|
289
|
-
- **Chỉ dẫn cho agent:** skill có mục "When NOT to delegate": agent không giao việc khi bạn bảo tự làm, khi bạn không nhắc Antigravity, hoặc khi công tắc đang tắt. Đây là chỉ dẫn, không phải rào chắn; muốn chắc chắn hãy dùng công tắc. Chạy lại `npm run skill:install` sau khi pull để cập nhật skill.
|
|
290
|
-
- Muốn tắt theo từng client: `enabled=false` trong cấu hình Codex hoặc `/mcp` trong Claude Code (xem mục 3, 4).
|
|
291
|
-
|
|
292
|
-
## 6. Vòng đời, giới hạn và dừng an toàn
|
|
293
|
-
|
|
294
|
-
TaskManager thuộc HTTP server, không thuộc phiên MCP. Server sử dụng handler stateless cho kết nối MCP; mọi request truy cập cùng TaskManager. Disconnect, DELETE session, request cancellation hoặc client thoát không tự hủy task đã tiếp nhận. Nếu mất response giao task, tra `recent_tasks` trước khi thử lại. Mọi client kết nối tới cùng bridge đều xem/hủy được task của nhau.
|
|
295
|
-
|
|
296
|
-
**Hàng đợi:** task `isolation: "none"` chạy tuần tự toàn cục. Task `isolation: "worktree"` chạy song song tối đa `max_parallel_worktrees` (mặc định 2, cấu hình 1–8 trong `config/workspaces.json`); hai lane không chạy chồng lên nhau (đang có task normal thì worktree xếp hàng và ngược lại). Khi bridge đang bận, tối đa `max_queued_tasks` task nữa (mặc định 3, cấu hình 0–20) được nhận với trạng thái `queued` và chạy theo thứ tự gửi. `0` trả về hành vi cũ: từ chối ngay với "busy". Task đang chờ chưa có tiến trình, chưa đụng file, có thể hủy; thời hạn (`timeout`) chỉ tính từ lúc bắt đầu chạy. Nếu công tắc giao việc bị tắt trước khi đến lượt thì task bị hủy; server dừng thì hủy hết; crash giữa chừng thì task đang chờ được nạp lại ở trạng thái `failed` ("never started").
|
|
297
|
-
|
|
298
|
-
Task worktree tạo branch `bridge/<task_id>` và thư mục `.bridge-state/worktrees/<task_id>` tại HEAD của repo; thay đổi chưa commit trong workspace gốc **không** được copy sang. Sau khi task kết thúc, bridge so diff với `owns`, giữ nguyên worktree và branch để Tech Lead review/merge thủ công. Bridge không tự merge, không tự xóa branch, và không chạy hook của repo khi tạo worktree. Chỉ dùng worktree cho repo đã có ít nhất một commit; workspace là thư mục con của repo vẫn được hỗ trợ.
|
|
299
|
-
|
|
300
|
-
Mặc định giữ 50 task (tối đa cấu hình 200); task cũ hoàn tất bị loại bỏ. Bản ghi task được lưu tại `.bridge-state/tasks/<task_id>.json` (mode 0600 trên POSIX; nội dung đã qua lọc secret) và nạp lại khi khởi động, nên tra được kết quả sau restart. Task đang chạy lúc server dừng đột ngột được nạp lại với trạng thái `failed` ("Bridge restarted…"): tiến trình agent không được khôi phục, hãy kiểm tra diff dở dang. Đây là lịch sử kết quả, không phải durable task recovery. Task vẫn timeout nếu không có client theo dõi. Lane normal giữ khóa giữa các process dùng cùng bản cài tại `.bridge-state/execution.lock`; lane worktree dựa vào branch riêng và không dùng khóa này.
|
|
301
|
-
|
|
302
|
-
Nhấn **Ctrl+C một lần** tại terminal server:
|
|
303
|
-
|
|
304
|
-
1. Ngừng lắng nghe kết nối và không nhận task mới.
|
|
305
|
-
2. Hủy ngay các task đang chạy, dọn cây process do server khởi tạo; không đợi task tự hoàn thành.
|
|
306
|
-
3. Đóng MCP handler, cho kết nối đang có tối đa 3 giây để drain sau khi cleanup; sau đó đóng cưỡng bức socket còn lại.
|
|
307
|
-
4. In `[bridge] Stopped` khi thành công. Không rollback file đã sửa. Xem diff trước lần chạy tiếp theo.
|
|
308
|
-
|
|
309
|
-
Nếu cleanup thất bại, báo lỗi và giữ execution lock khi process chưa đóng. Khi khởi động hoặc lấy lock, bridge chỉ tự thu hồi nếu đọc được owner hợp lệ, cả `server_pid` lẫn `child_pid` đều đã chết và record khớp lock. Lệnh `agy-mcp-bridge unlock` dùng cùng kiểm tra; PID còn sống, thiếu thông tin hoặc quyền sở hữu không rõ thì giữ lock và in lý do. Bridge không kill process Antigravity khác. PID có thể được tái sử dụng nên trường hợp không rõ cần kiểm tra thủ công. Force kill/OS crash vẫn không bảo đảm cleanup: chưa có Windows Job Object. POSIX gửi SIGTERM cho nhóm process, chờ tối đa 8 giây rồi SIGKILL; Windows giữ taskkill cây PID. Ctrl+C tiếp trong lúc cleanup chỉ báo `cleanup in progress, please wait`.
|
|
310
|
-
|
|
311
|
-
Giới hạn mặc định: CLI task 300s, tối đa 900s; watchdog của bridge cộng thêm 10s để CLI tự báo timeout trước. Chủ máy nâng mức tối đa (và mặc định) lên tới 3600s bằng `max_timeout_seconds` / `default_timeout_seconds` trong file cấu hình (khởi động lại bridge); mỗi task đặt `timeout_seconds` riêng, không vượt mức tối đa đó. Task hết thời hạn không bị hoàn tác: file đã sửa trước đó vẫn nằm trên đĩa (xem "Thay đổi trong workspace" hoặc `git diff`), trạng thái là `timeout`, và skill dặn Codex/Claude giao task mới hẹp hơn cho phần còn lại thay vì gửi lại y nguyên. Task lớn nên chia nhỏ hơn là chỉ tăng thời hạn. Output mỗi stream 256 KiB (cấu hình 1 KiB–1 MiB), vượt trần sẽ hủy task và trả failed/truncated. Tổng task JSON vẫn tối đa 24000 ký tự; HTTP body tối đa 128 KiB. Prompt mặc định đi qua argv với print/json (`prompt_transport: "argv"`, đường đã chạy thật với `agy` 1.4.3 và 1.4.7). Đặt `prompt_transport: "stdin"` để gửi qua stdin stream-json, không lộ prompt trong danh sách tiến trình; chế độ này chưa được chạy thử với `agy` thật, và stream gồm cả init/progress nên có thể chạm output cap sớm hơn. Snapshot log được cập nhật tối đa mỗi giây và flush khi kết thúc. Không dùng CLI detach/remote-control API chưa được xác minh.
|
|
312
|
-
|
|
313
|
-
## 7. Bảo mật và vận hành
|
|
314
|
-
|
|
315
|
-
Chỉ listen `127.0.0.1`, không có tùy chọn bind LAN trong bản này. Host phải đúng địa chỉ/cổng thực tế; Origin khác bị từ chối; không bật CORS cho website ngoài. **Không có xác thực**: mọi tiến trình cục bộ cùng user đều có thể gọi tool, đọc task, điều khiển agent và tắt server. Đây là mô hình tin cậy cục bộ có chủ đích; không mở cổng, không đặt sau proxy công khai. Không log HTTP headers/body.
|
|
316
|
-
|
|
317
|
-
Cách ly worktree là ranh giới **quy trình**, không phải sandbox OS: agent vẫn chạy dưới quyền user hiện tại. Bridge tạo worktree trong `.bridge-state/worktrees` với `core.hooksPath` rỗng, so diff sau khi chạy và báo `scope.out_of_scope`; file ngoài `owns` không bao giờ được tự merge. Codex chạy với `--sandbox workspace-write`; các hành động cần approval vẫn thất bại thay vì được bypass. Không dùng `--dangerously-*`, `--yolo` hoặc bất kỳ cờ bỏ qua permission nào. Deploy, publish, xóa dữ liệu, push nhánh bảo vệ, đọc credential và thay đổi hệ thống ngoài workspace là hành động bị cấm tuyệt đối, không phụ thuộc `autonomy`.
|
|
318
|
-
|
|
319
|
-
Allowlist kiểm tra realpath, boundary, traversal; link/junction trong thành phần đường dẫn đầu vào vẫn bị từ chối. Trong cây, link phải resolve được vào cùng workspace; không theo alias/cycle. Quét bỏ qua nội dung thư mục `node_modules` và `.git`; trần 200000 chỉ tính các entry còn lại. Task từ queue được kiểm tra lại trước launch. **Đây không phải OS sandbox**: đặc biệt nội dung hai thư mục được bỏ qua không được kiểm tra, và tiến trình khác vẫn có thể đổi link sau preflight. Quyền agent/hooks/MCP và file ngoài workspace vẫn cần kiểm soát OS/CLI phù hợp. Lọc output không nhận ra mọi bí mật; không đưa secret vào task.
|
|
320
|
-
|
|
321
|
-
Để truy cập từ máy khác, cần thiết kế riêng TLS, xác thực/authorization và cách ly workspace. Bản này không triển khai remote/LAN; không đổi bind sang 0.0.0.0 hoặc mở firewall để né lỗi cổng.
|
|
322
|
-
|
|
323
|
-
Các lỗi thường gặp:
|
|
324
|
-
|
|
325
|
-
- `Port is already in use`: chọn PORT khác, cập nhật URL cả hai client.
|
|
326
|
-
- 403: sai Host/Origin; dùng đúng URL 127.0.0.1 được in ra, không đi qua proxy/alias.
|
|
327
|
-
- Connection refused/fetch failed: server tắt hoặc sai cổng; chạy check, bật lại server và reconnect.
|
|
328
|
-
- CLI unsupported: kiểm tra agy path/version/help; environment vẫn có thể hoạt động dù không giao được task.
|
|
329
|
-
- Agent unavailable: gọi `agents_list`; kiểm tra `codex --version` và `codex exec --help`, hoặc tên/`agents.enabled` trong cấu hình.
|
|
330
|
-
- Worktree bị từ chối: workspace phải là git repo có ít nhất một commit; `owns` phải là đường dẫn tương đối, không chứa `..`.
|
|
331
|
-
- `scope.out_of_scope` khác rỗng: agent sửa file ngoài phạm vi; review worktree, không merge tự động.
|
|
332
|
-
- `denied_actions`: Antigravity chưa cho phép thao tác; xin quyền tối thiểu, không bỏ permission check.
|
|
333
|
-
- Workspace bị từ chối: kiểm tra allowlist, link/junction hoặc số entry vượt trần.
|
|
334
|
-
- Timeout/canceled/output limit: có thể có diff dở dang; review trước khi giao task tiếp theo.
|
|
63
|
+
| `agent` | id from `agents_list` (`antigravity`, `codex`). Omit for the highest-priority available agent; naming an unavailable agent errors rather than switching silently. |
|
|
64
|
+
| `isolation` | `none` (default — edits the workspace, globally serial) or `worktree` (branch `bridge/<task_id>` under `.bridge-state/worktrees/<task_id>`, parallel up to `max_parallel_worktrees`). Worktree tasks must declare `owns`, and the repo needs at least one commit. Uncommitted changes in the main checkout are **not** copied in. |
|
|
65
|
+
| `owns` | relative paths the agent may touch. After the run the bridge diffs the worktree against this list and reports anything else in `scope.out_of_scope`. It never auto-merges, never deletes the branch, and does not run repo hooks. |
|
|
66
|
+
| `autonomy` | `suggest` \| `auto` \| `full` — an instruction to the CLI agent, not a permission grant. Destructive actions stay hard-denied (see below). |
|
|
335
67
|
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
```powershell
|
|
339
|
-
npm test
|
|
340
|
-
npm run test:live
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
`npm test` (cũng chạy trong [CI](.github/workflows/ci.yml) trên Ubuntu và Windows, Node 20/22): unit/integration dùng executable giả, không gọi AI. Bao gồm lifecycle/security cũ và HTTP startup/port conflict/PORT tùy chọn/Host/Origin/body limit/kết nối hai protocol era/client reconnect/task completion/cancel/server shutdown.
|
|
344
|
-
|
|
345
|
-
`test:live`: **gọi AI thật**, dùng cached login/quota. Test harness khởi động HTTP server riêng với PORT=0 và scratch workspace, dùng official SDK HTTP client, ngắt/kết nối lại khi task chạy, xác minh `BRIDGE_SMOKE_OK` và sentinel không đổi, hủy task thật, rồi kiểm tra shutdown có task đang chạy. Trên Windows, harness phát event SIGINT vào đúng handler của entry point qua IPC riêng của harness; kiểm tra Ctrl+C terminal được ghi riêng trong báo cáo. Đây không phải yêu cầu client production tự khởi động server. Kết quả ở `test-results/live-report.json`; phần sửa file thật vẫn bị chặn đến khi cấp quyền.
|
|
346
|
-
|
|
347
|
-
`src/index.ts`: HTTP entry; `src/http.ts`: listener/routing/shutdown; `src/runtime.ts`: CLI và TaskManager dùng chung; `src/agents`: adapter Antigravity/Codex, registry và contract; `src/isolation`: tạo worktree và kiểm tra phạm vi `owns`; `src/tools`: tool; `src/antigravity`: child process; `src/security`: validation/workspace/redaction; `src/tasks`: lifecycle/lock/output; `scripts/check.ts`: kiểm tra server đang chạy; `scripts/live.ts`: AI smoke test. Không thay cấu hình Codex/Claude Code/Antigravity trong test.
|
|
348
|
-
|
|
349
|
-
## 9. Skill giao tiếp với Antigravity
|
|
350
|
-
|
|
351
|
-
Skill [antigravity-bridge](skills/antigravity-bridge/SKILL.md) hướng dẫn client dùng 6 tool theo schema thật, ghi task ID, xử lý disconnect/reconnect, timeout, permission denial, output bị cắt và review diff. Skill dùng chung chuẩn `SKILL.md` cho Codex và Claude Code. Đây là hướng dẫn cho Tech Lead, không cài vào Antigravity; prompt Developer đã được bridge gửi kèm mỗi task.
|
|
352
|
-
|
|
353
|
-
Sau `npm install` và `npm run build`, chạy từ thư mục clone:
|
|
354
|
-
|
|
355
|
-
```powershell
|
|
356
|
-
# Chọn client bạn sử dụng; không cần chạy cả ba lệnh.
|
|
357
|
-
npm run skill:install -- --client codex
|
|
358
|
-
npm run skill:install -- --client claude
|
|
359
|
-
npm run skill:install -- --client both
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
Đích mặc định cho người dùng hiện tại, không chứa đường dẫn riêng của tác giả:
|
|
363
|
-
|
|
364
|
-
| Client | File được cài |
|
|
365
|
-
|---|---|
|
|
366
|
-
| Codex | `~/.agents/skills/antigravity-bridge/SKILL.md` |
|
|
367
|
-
| Claude Code | `~/.claude/skills/antigravity-bridge/SKILL.md` |
|
|
368
|
-
|
|
369
|
-
`~` là thư mục tài khoản hệ điều hành đang chạy lệnh. Cài cho riêng một project bằng `--project` là đường dẫn tuyệt đối tới project đã có; cài đặt sẽ tạo `.agents/skills/antigravity-bridge` và/hoặc `.claude/skills/antigravity-bridge` bên trong project đó. Ví dụ PowerShell, thay đường dẫn mẫu bằng project thật:
|
|
370
|
-
|
|
371
|
-
```powershell
|
|
372
|
-
npm run skill:install -- --client both --project 'C:\path\to\your-project'
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
Installer chỉ ghi `SKILL.md`, không sửa config MCP, allowlist, AGENTS.md/CLAUDE.md hay settings Antigravity. Nội dung giống nhau thì không ghi lại (khác nhau kiểu xuống dòng CRLF/LF không tính là khác). Khi file đã cài khác nội dung, bridge phân biệt hai trường hợp bằng danh sách hash `skills/known-versions.json` (sha256 của mọi bản `SKILL.md` đã phát hành):
|
|
376
|
-
- **Bản cũ do gói này phát hành** (khớp một hash trong danh sách): `skill install` báo cần `--update`; chạy `agy-mcp-bridge skill install --client both --update` (hoặc `npm run skill:install -- --client both --update`) sẽ thay bằng bản mới, ghi nguyên tử qua file tạm. Khi chạy server lần đầu sau khi có skill mới, bridge cũng hỏi `Update them now? [y / N]` đúng một lần cho mỗi bản skill mới (không hỏi lại nếu bạn trả lời không, cho tới khi có bản mới hơn).
|
|
377
|
-
- **Bản bạn tự sửa** (không khớp bản nào): không bao giờ bị ghi đè hay xóa, kể cả khi có `--update`; lệnh báo lỗi để bạn tự review/gộp.
|
|
378
|
-
|
|
379
|
-
Với client có nhiều đích, mọi đích được quyết định trước khi ghi bất cứ file nào, nên không có trạng thái cập nhật dở. **Người bảo trì:** mỗi khi sửa `skills/antigravity-bridge/SKILL.md`, thêm sha256 của bản mới vào `skills/known-versions.json` (test `skill versions` báo đúng giá trị cần thêm); các hash cũ giữ nguyên để người đã cài bản cũ vẫn cập nhật được. Có thể copy thư mục skill vào đường dẫn discovery do client/môi trường của bạn hỗ trợ nếu không dùng vị trí mặc định.
|
|
380
|
-
|
|
381
|
-
Mở lại client nếu skill chưa xuất hiện. Codex có thể chọn qua `/skills` hoặc gọi trong prompt:
|
|
382
|
-
|
|
383
|
-
```text
|
|
384
|
-
$antigravity-bridge Phân tích lỗi parseCount, giao task sửa có tiêu chí nghiệm thu
|
|
385
|
-
cho Antigravity trong workspace đã cấp quyền, rồi review diff và chạy test.
|
|
386
|
-
```
|
|
387
|
-
|
|
388
|
-
Trong Claude Code:
|
|
389
|
-
|
|
390
|
-
```text
|
|
391
|
-
/antigravity-bridge Phân tích lỗi parseCount, giao task sửa có tiêu chí nghiệm thu
|
|
392
|
-
cho Antigravity trong workspace đã cấp quyền, rồi review diff và chạy test.
|
|
393
|
-
```
|
|
394
|
-
|
|
395
|
-
Skill có thể được client tự chọn khi yêu cầu phù hợp. Cài skill không tự kết nối HTTP server hoặc đăng ký MCP tools; cần hoàn thành phần cấu hình client và workspace trước. Skill không thể bảo đảm không có lỗi CLI/model/mạng, không mở thêm quyền và không thay thế kiểm tra diff/test. Kết nối bị mất không phải lý do tự giao lại task; skill yêu cầu tìm task cũ trước để tránh chạy trùng.
|
|
396
|
-
|
|
397
|
-
Vị trí và cách gọi đã đối chiếu [Codex skills](https://developers.openai.com/codex/skills/) và [Claude Code skills](https://code.claude.com/docs/en/skills). Validator kiểm tra cấu trúc skill; test installer dùng thư mục tạm, không gọi AI hay cài vào skill cá nhân. Chưa đánh giá chất lượng quyết định của agent bằng behavioral eval chỉ từ các test này.
|
|
398
|
-
|
|
399
|
-
## 10. Giao diện web
|
|
400
|
-
|
|
401
|
-
Khi `npm start` đang chạy, mở `http://127.0.0.1:3000/ui` (đúng cổng đã in ở terminal) trên cùng máy. Giao diện chỉ chạy trong server của bridge, **không đi qua Codex/Claude nên không tốn thêm token của chúng**, và không thêm tool MCP nào.
|
|
402
|
-
|
|
403
|
-
Không cần đăng nhập: giao diện mở trực tiếp vì bridge không có xác thực. Trang chỉ dùng được từ loopback và bị chặn nếu `Host`/`Origin` không khớp. Đóng tab chỉ đóng giao diện, không dừng server; dùng nút **Tắt bridge** trong Cài đặt để dừng server và dọn tiến trình.
|
|
404
|
-
|
|
405
|
-
| Màn hình | Nội dung |
|
|
68
|
+
| Tool | What it does |
|
|
406
69
|
|---|---|
|
|
407
|
-
|
|
|
408
|
-
|
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
70
|
+
| `antigravity_environment` | CLI versions, allowlist, limits, agents, parallelism, `recent_tasks`, delegation switch |
|
|
71
|
+
| `agents_list` | probed agents, capabilities, availability, default agent, worktree limits (read-only) |
|
|
72
|
+
| `antigravity_delegate` | accepts a task, returns `running` (or `queued`) with a `task_id` |
|
|
73
|
+
| `antigravity_task_status` | cheap poll: state, pid, elapsed, errors, `denied_actions`, byte counts |
|
|
74
|
+
| `antigravity_task_wait` | blocks up to `wait_seconds` (default cap 55 s), returns early when the task ends |
|
|
75
|
+
| `antigravity_task_output` | final response, stdout/stderr, errors, `denied_actions`, truncation |
|
|
76
|
+
| `antigravity_cancel_task` | kills the task's process tree; does not revert file changes |
|
|
413
77
|
|
|
414
|
-
|
|
78
|
+
`completed` means the CLI exited with a parseable result — always `review_required: true`, `acceptance_verified: false`. A 0 exit code can still be reported as `failed` after a permission denial or a timeout. While a task runs, `wait`/`status` return a short `activity` line instead of making the client read logs.
|
|
415
79
|
|
|
416
|
-
|
|
80
|
+
Two switches control delegation itself: `agy-mcp-bridge delegation off` blocks new tasks immediately without a restart, and `BRIDGE_DELEGATION=off` pins it at startup. Tasks still refuse to be delegated by policy the skill describes (security, auth, secrets, data deletion, deploy, CI and public API changes are not delegated).
|
|
417
81
|
|
|
418
|
-
|
|
82
|
+
## Lifecycle and limits
|
|
419
83
|
|
|
420
|
-
|
|
84
|
+
Task state belongs to the HTTP server, not to the MCP session, and all clients share one TaskManager. `none`-lane tasks take a cross-process lock (`.bridge-state/execution.lock`); `worktree`-lane tasks rely on their own branch. Results persist to `.bridge-state/tasks/<task_id>.json` (0600, secret-redacted) and reload at startup, so you can recover an answer after a reconnect — this is history, not durable task recovery. Ctrl+C once: stop listening, cancel running tasks and reap their process trees, drain sockets for up to 3 s, print `[bridge] Stopped`. It does not revert files.
|
|
421
85
|
|
|
422
|
-
|
|
423
|
-
2. **Thời hạn tool của client phải lớn hơn thời gian chờ**, nếu không client cắt lần chờ và báo timeout. Codex: đặt `tool_timeout_sec` trong `config.toml` ở mục `[mcp_servers.antigravity]`, bằng thời gian chờ cộng thêm khoảng 60 giây (ví dụ chờ 600 giây thì `tool_timeout_sec = 660`), rồi mở lại Codex. Lệnh `agy-mcp-bridge setup codex` in sẵn dòng này theo mức đang chọn; giao diện cũng hiện đúng giá trị cần đặt. Claude Code: biến môi trường `MCP_TOOL_TIMEOUT` tính bằng mili giây, theo tài liệu của Claude Code (chưa kiểm chứng ở đây). Nếu chưa chắc về thời hạn tool của client, giữ mặc định 55 giây.
|
|
424
|
-
3. **Skill dặn agent chỉ chờ:** trong lúc task chạy, agent chỉ gọi `antigravity_task_wait`, không đọc file, không chạy git, test hay đọc log, không tự review cùng thay đổi và không viết gì giữa các lần chờ; chỉ khi task kết thúc mới lấy `antigravity_task_output` một lần rồi review. Mỗi lần chờ mà task còn chạy trả kèm ghi chú `next_step` nhắc đúng điều đó ngay lúc agent quyết định bước tiếp theo. Skill cũng cấm agent tự viết script hay client HTTP để gọi bridge: nếu phiên không có các tool `antigravity_*`, agent báo cho bạn (nguyên nhân thường là bridge chưa chạy hoặc client chưa trỏ đúng endpoint) rồi dừng.
|
|
86
|
+
Defaults: 300 s per task (max 900 s; the owner may raise both to 3600 s in config), 256 KiB per output stream (1 KiB–1 MiB configurable, exceeding it cancels the task and reports `truncated`), 50 retained tasks (max 200), 2 parallel worktrees (1–8), 3 queued tasks (0–20). A timed-out task leaves its partial edits on disk — review them, then delegate a narrower task rather than resending the same one.
|
|
425
87
|
|
|
426
|
-
|
|
88
|
+
CLI agents spawn their own children (MCP servers, shells, tool helpers) rooted in the worktree; on Windows those outlive the agent and pin the directory, which is why the bridge records the process tree during the run and reaps the surviving branches after the agent exits, with `taskkill /T /F` after `git worktree remove` fails. PIDs are re-checked against a fresh process table before anything is signalled, so a recycled PID is skipped and reported in `cleanup.skipped`. The result appears as `cleanup` on the task record and in the UI. Watch cadence is `tree_watch` in config (`delays_ms`, or `enabled: false` to accept that an intermediate shell that exited early leaves its children invisible). A crash still has no guarantee: there is no Windows Job Object yet.
|
|
427
89
|
|
|
428
|
-
|
|
90
|
+
## Security model
|
|
429
91
|
|
|
430
|
-
-
|
|
431
|
-
-
|
|
432
|
-
-
|
|
433
|
-
- **
|
|
434
|
-
-
|
|
92
|
+
- **Loopback only.** `127.0.0.1` is the only bind; there is no LAN option. `Host` must match the real address and port, foreign `Origin` is rejected, CORS stays off. `PORT` may change the port, or `PORT=0` to let the OS pick one — the URL printed at startup is then the truth for every client.
|
|
93
|
+
- **No auth.** Deliberate for a single-user dev machine: the protections that remain are loopback binding, Host/Origin checks, body limits, timeouts, a workspace allowlist, and an environment allowlist for child processes (names containing `TOKEN`, `SECRET`, `PASSWORD`, `API_KEY` are stripped unless you explicitly add them to `extra_env_passthrough`).
|
|
94
|
+
- **Worktree isolation is a process boundary, not an OS sandbox.** The agent still runs as you. The allowlist validates realpath, boundary and traversal and rejects links/junctions in inputs, but `node_modules` and `.git` contents are not inspected, and OS/CLI-level permissions remain yours to control.
|
|
95
|
+
- **Hard-denied regardless of `autonomy`:** deploy/publish, data deletion, pushing to protected branches, reading credentials, system changes outside the workspace. The bridge never adds a bypass flag on its own initiative, and Codex tasks are never run with `--yolo` or a skipped approval prompt — an action that would need approval fails instead. The Antigravity permission level (`default` / `plan` / `accept-edits` / `auto` / `full`) is owner-only, set in the web UI; only `full` passes `--dangerously-skip-permissions` to `agy`, it takes approval away for commands and paths outside the workspace, and the two highest levels ask for confirmation and show a standing warning strip.
|
|
96
|
+
- Remote access from another machine would need TLS, real authentication/authorization and per-workspace isolation. Nothing here provides that.
|
|
435
97
|
|
|
436
|
-
|
|
98
|
+
Redaction recognises common secret shapes; it does not catch everything. Keep secrets out of tasks. Task records and prompts are stored so the UI can re-read them after a restart.
|
|
437
99
|
|
|
438
|
-
|
|
100
|
+
## Web UI
|
|
439
101
|
|
|
440
|
-
|
|
102
|
+
`http://127.0.0.1:3000/ui` on the same machine, no login (there is no auth to log into). It reads the same task store as the tools, so it costs your other agents no tokens. Pages: **Tasks** (bridge state, ready agents, delegation switch, per-task request/criteria/response, `denied_actions`, stdout/stderr, full prompt, worktree/branch and `owns` verdict, workspace changes with per-file line counts) and **Settings** (delegation, MCP endpoint, per-agent probe results, allowed workspaces, permission level, model, effort, wait cadence, soft deadline, step progress, usage, shutdown button). Regions patch in place, so selecting log text survives an update.
|
|
441
103
|
|
|
442
|
-
|
|
104
|
+
Long explanations, unverified notes and rarely-changed numbers live behind **More** blocks; decisions-worthy state stays visible. The no-auth warning is always visible, and the "allowlist is not a sandbox" warning is always visible at `auto`/`full`.
|
|
443
105
|
|
|
444
|
-
|
|
106
|
+
Model and effort apply to new tasks immediately, without a restart, and each task records what it was given. Only ids from `agy models` are offered. `probe-stream` shows what `agy --output-format stream-json` emits; step progress is opt-in and off by default. The **Usage** tab aggregates `usage` from every finished task to `.bridge-state/usage.jsonl`, per model and per effort; the token budget fields are an indicator light, not a cap — `agy` exposes no quota to the bridge.
|
|
445
107
|
|
|
446
|
-
|
|
447
|
-
- Bridge **không biết trước** các trường bên trong `usage` (tên trường do `agy` quyết định): nó cộng mọi giá trị số; một vài tên phổ biến (`input_tokens`, `output_tokens`, `total_tokens`...) được dịch nhãn. Task nào kết quả không có `usage` thì ghi nhận là "không có", không phải 0.
|
|
448
|
-
- Chỉ thống kê task bắt đầu từ bản có tính năng này trở đi. Số liệu usage không được gửi cho Codex/Claude (không tốn token).
|
|
108
|
+
**Workspace changes** are computed in a throwaway git directory with an empty config, borrowing only the object store: `git status`/`git diff` normally execute commands declared by the repository itself (`core.fsmonitor`, `filter.*.clean`, `diff.*.textconv`), and the agent can write files, so a poisoned `.git/config` is a real path. Disabling the external diff alone is not enough — there is a test that builds a poisoned repo and proves nothing runs.
|
|
449
109
|
|
|
450
|
-
|
|
110
|
+
## Development
|
|
451
111
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
- **Chưa kiểm chứng:** tôi chưa biết `agy` có ghi log đều đặn trong lúc suy luận hay chỉ ghi lúc bắt đầu và kết thúc. Nếu log không tăng khi `agy` đang chạy thì không có dấu hiệu nào để gia hạn, và task dừng đúng hạn như khi tắt tính năng (không tệ hơn). Cách kiểm tra: bật tính năng, giao một task kéo dài vài chục giây và xem dòng "Log của agy cập nhật…" tăng khi task đang chạy.
|
|
457
|
-
- Tắt tính năng thì mọi thứ như cũ: hạn cứng, không có `--log-file`.
|
|
458
|
-
|
|
459
|
-
**Cấp bậc chờ:** khi Codex/Claude gọi `antigravity_task_wait` mà không chọn số giây, lần chờ đầu của mỗi task dài 1 phút, lần hai 5 phút, từ lần ba là mức tối đa bạn chọn (không bao giờ vượt mức đó; với mặc định 55 giây thì cả ba đều 55 giây). Lệnh chờ kết thúc ngay khi task xong, nên cấp bậc này chủ yếu giúp báo "vẫn đang chạy" đến sớm ở đầu task, không tiết kiệm thêm token. Thời hạn tool của client vẫn phải lớn hơn mức tối đa đó.
|
|
460
|
-
|
|
461
|
-
**Quyền của Antigravity:** mục Cài đặt → Quyền của Antigravity chọn Antigravity được tự làm đến đâu khi chạy task. Ở chế độ không tương tác, Antigravity tự từ chối việc cần phê duyệt (thấy ở `denied_actions`), nên task sửa file hay chạy lệnh có thể không làm được nếu cài đặt Antigravity chưa cấp quyền. Năm mức, từ thấp đến cao:
|
|
112
|
+
```bash
|
|
113
|
+
npm test # build + unit/integration with fake executables; no AI calls
|
|
114
|
+
npm run test:live # REAL agent calls, scratch workspace, disconnect/reconnect, cancel, shutdown
|
|
115
|
+
```
|
|
462
116
|
|
|
463
|
-
|
|
464
|
-
|---|---|---|
|
|
465
|
-
| Mặc định | (không có) | Quyền theo file cài đặt của Antigravity; an toàn nhất, là mặc định |
|
|
466
|
-
| Chỉ lập kế hoạch | `--mode plan` | Chỉ lập kế hoạch |
|
|
467
|
-
| Tự duyệt sửa file | `--mode accept-edits` | Sửa file được duyệt tự động |
|
|
468
|
-
| Tự động | `--mode auto` | Chế độ tự động của Antigravity |
|
|
469
|
-
| Toàn quyền | `--dangerously-skip-permissions` | Duyệt mọi yêu cầu, gồm chạy lệnh và truy cập ngoài thư mục dự án |
|
|
117
|
+
`npm test` runs serially (`--test-concurrency=1`, ~158 s): most cases start a real loopback server and time its output, so a parallel failure reflects machine load, not code. CI runs Windows and Linux on Node 20/22. Source map: `src/index.ts` entry, `src/http.ts` routing/shutdown, `src/runtime.ts` shared CLI + TaskManager, `src/agents` adapters and registry, `src/isolation` worktrees and `owns`, `src/tasks` lifecycle/lock/output, `src/security` validation and redaction, `src/tools` tool definitions, `src/antigravity` child process, `ui/` plain HTML/CSS/JS with `src/ui/` behind it.
|
|
470
118
|
|
|
471
|
-
|
|
119
|
+
Pushing or merging to `main` runs CI and, when it passes, publishes to npm automatically: the [publish workflow](.github/workflows/publish.yml) bumps the patch version, tags, pushes and publishes through OIDC Trusted Publishing — no npm token in secrets, no manual version bump, nothing published if CI fails. PRs run [CI](.github/workflows/ci.yml) only. Set up once under the package's **Trusted Publisher** settings: user `thanhdo257205`, repository `MCP-bridge`, workflow `publish.yml`, empty environment, allow direct npm publish.
|
|
472
120
|
|
|
473
|
-
|
|
121
|
+
## Documentation
|
|
474
122
|
|
|
475
|
-
|
|
123
|
+
- [docs/HARDENING.md](docs/HARDENING.md) — hardening changes and the limits of what was verified.
|
|
124
|
+
- [docs/VERIFICATION.md](docs/VERIFICATION.md) — client CLI versions and live connection results.
|
|
125
|
+
- [docs/MULTI-AGENT-PLAN.md](docs/MULTI-AGENT-PLAN.md) — the multi-agent roadmap and per-phase status.
|
|
126
|
+
- [docs/HANDOFF.md](docs/HANDOFF.md) — open work (Job Object, POSIX E2E, worktree TTL) with mutation-test evidence.
|
|
127
|
+
- [docs/PROMPTS.md](docs/PROMPTS.md) — review and follow-up task prompts.
|
|
128
|
+
- [skills/antigravity-bridge/SKILL.md](skills/antigravity-bridge/SKILL.md) and [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) — the client-side contract and manual evaluation cases.
|
|
476
129
|
|
|
477
|
-
-
|
|
478
|
-
- **Tiến độ thật của task:** stdin stream-json hiện đã được xác minh ở đường kiểm tra lỗi không gọi AI, và parser lấy terminal `result` theo tài liệu chính thức. Luồng thành công đang được test bằng mock; chưa thực thi AI thật trong đợt hardening. UI hiện hiển thị log snapshot, chưa diễn giải từng `step_update` thành phần trăm tiến độ. Trong lúc task chạy, trang chi tiết có thanh thời gian đã chạy so với giới hạn, thời điểm `agy` ghi output gần nhất, và danh sách thay đổi trong workspace tự làm mới mỗi vài giây khi mở mục "Thay đổi trong workspace" (các tín hiệu này không phụ thuộc định dạng output của `agy`; ở chế độ print/json `agy` chỉ in khi xong nên dòng output có thể trống).
|
|
479
|
-
- **`outputSchema` cho tool MCP:** đã thử và bỏ. Schema đầy đủ làm danh sách tool tăng từ khoảng 3,9 KB lên 12,1 KB; nếu client đưa vào ngữ cảnh của agent thì tốn thêm token ở mỗi lượt, trái với mục tiêu giữ chi phí thấp.
|
|
480
|
-
- **Đánh giá hành vi của skill:** xem [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md): bộ tình huống và tiêu chí chấm để chạy thủ công với Codex/Claude Code; chưa được chạy tự động.
|
|
481
|
-
- **Dọn tiến trình khi crash trên Windows:** xem mục 6; mới có cảnh báo, chưa có bảo đảm.
|
|
130
|
+
The bundled `antigravity-bridge` skill teaches a client the real tool schemas, task-id recovery, timeouts, permission denials and diff review. First interactive run offers to install it (`agy-mcp-bridge skill install --client codex|claude|both` writes `~/.agents/skills/…` or `~/.claude/skills/…`); a SKILL.md you edited yourself is never overwritten. Installing the skill does not connect the server or grant any permission.
|
|
482
131
|
|
|
132
|
+
MIT licensed; see `LICENSE`.
|