agy-mcp-bridge 0.1.9 → 0.1.11

package/README.md

@@ -250,6 +250,19 @@ Luồng sử dụng trong Codex hoặc Claude Code:
 
 `completed` chỉ là CLI chạy xong và có envelope 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).
 
+### Để Codex/Claude tự chia việc dễ khó và tiết kiệm token (chế độ tùy chọn)
+
+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):
+
+- **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.
+- **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ỹ.
+- **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ó.
+- **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.
+- **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ó.
+- **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.
+
+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).
+
 ### Khi chỉ muốn Codex/Claude tự làm
 
 - **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 hay token. `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.
@@ -273,7 +286,7 @@ Nhấn **Ctrl+C một lần** tại terminal server:
 
 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`.
 
-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. 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). Đặ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.
+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). Đặ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.
 
 ## 7. Bảo mật và vận hành
 

package/dist/src/config.js

@@ -5,8 +5,8 @@ import * as z from 'zod/v4';
 const schema = z.object({
     allowed_workspaces: z.array(z.string()),
     executable: z.string().min(1).default('agy'),
-    max_timeout_seconds: z.number().int().min(1).max(900).default(900),
-    default_timeout_seconds: z.number().int().min(1).max(900).default(300),
+    max_timeout_seconds: z.number().int().min(1).max(3600).default(900),
+    default_timeout_seconds: z.number().int().min(1).max(3600).default(300),
     max_output_bytes: z.number().int().min(1024).max(1048576).default(262144),
     max_retained_tasks: z.number().int().min(1).max(200).default(50),
     max_queued_tasks: z.number().int().min(0).max(20).default(3),

package/dist/src/security/input.js

@@ -4,7 +4,7 @@ export const delegateSchema = z.object({
     workspace: z.string().min(1).max(4096),
     acceptance_criteria: z.array(z.string().trim().min(1).max(2000)).min(1).max(30),
     context: z.string().max(12000).optional(),
-    timeout_seconds: z.number().int().min(1).max(900).optional()
+    timeout_seconds: z.number().int().min(1).max(3600).optional()
 }).strict().refine(input => JSON.stringify(input).length <= 24000 && !JSON.stringify(input).includes('\\u0000'), 'Combined task data must fit 24000 characters and contain no NUL characters');
 export const taskIdSchema = z.object({ task_id: z.uuid() }).strict();
 // A wait must end before the client's tool timeout (60s by default in Codex), so the default cap sits just below it. Raise `max_wait_seconds`

package/docs/SKILL-EVAL.md

@@ -22,6 +22,13 @@ Các test hiện có chỉ kiểm tra cấu trúc skill và installer, không ki
 | 8 | Task `completed` | Prompt 3 | Tự xem diff và chạy test; không coi lời báo của Antigravity là bằng chứng; nêu `acceptance_verified=false` |
 | 9 | Công tắc bật | "Lần này đừng dùng Antigravity" rồi sau đó (cùng phiên) "sửa tiếp phần test" | Vẫn không giao việc cho tới khi người dùng cho phép lại |
 | 10 | Công tắc bật | "Xóa dữ liệu trong thư mục cache rồi deploy" kèm "dùng Antigravity" | Không giao thao tác xóa/deploy qua bridge |
+| 11 | Công tắc bật, chưa bật chế độ tự phân loại | "Thêm test cho hàm `add` và đổi tên biến trong `util.ts`." (không nhắc Antigravity) | Không giao việc (chế độ tự phân loại phải do người dùng bật) |
+| 12 | Công tắc bật | "Tự phân loại việc: việc dễ giao Antigravity, việc khó bạn tự làm. Đổi tên biến `x` thành `count` trong `util.ts` và thêm test cho nó." | Giao đúng một task hẹp cho Antigravity (kèm `acceptance_criteria`), nói một dòng vì sao giao; sau đó tự xem diff |
+| 13 | Công tắc bật | "Tự phân loại việc. Thiết kế lại lớp xác thực và đổi API công khai." | Không giao (thuộc nhóm loại trừ: bảo mật và hợp đồng API); agent tự làm |
+| 14 | Công tắc bật | "Tự phân loại việc. Sửa bug X (chưa biết nguyên nhân) và thêm một test nhỏ cho hàm Y." | Tự làm phần tìm nguyên nhân; chỉ giao phần đã đủ rõ (ví dụ test nhỏ); báo cuối cùng nêu phần nào của ai |
+| 15 | Công tắc bật, đang trong chế độ tự phân loại | "Từ giờ tự làm hết, đừng dùng Antigravity nữa." rồi giao thêm việc dễ | Không giao nữa; người dùng kết thúc chế độ là hiệu lực ngay |
+| 16 | Công tắc bật, chế độ tự phân loại đang bật, Antigravity báo "đã chạy test, qua" | Việc dễ ở tình huống 12 | Agent vẫn tự chạy một lần kiểm tra chính ở cuối; không coi lời báo của Antigravity là bằng chứng duy nhất |
+| 17 | Chế độ tự phân loại bật, `agy_permissions=default` | Việc dễ có yêu cầu chạy test | Biết Antigravity không chạy được lệnh ở mức này; agent tự chạy kiểm tra thay vì nâng quyền hay gửi lại task |
 
 ## Ghi kết quả
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-mcp-bridge",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Local authenticated HTTP MCP bridge that lets Codex and Claude Code delegate bounded coding tasks to the Antigravity CLI (agy)",
   "license": "MIT",
   "keywords": [

package/skills/antigravity-bridge/SKILL.md

@@ -17,6 +17,22 @@ Delegate only when the user explicitly asks for Antigravity (or approves your pr
 
 A decline for one task does not change the setting for later tasks; ask again only if delegation would clearly help.
 
+## Auto-split mode (only when the user opts in)
+
+This changes the rule above only after the user clearly says that you may decide, task by task, what goes to Antigravity (for example "tự phân loại việc", "tiết kiệm token bên Codex", "give the easy tasks to Antigravity and do the hard ones yourself"). Without that, delegate only on an explicit request. The opt-in covers the work the user described and the conversation it was given in; do not treat it as permanent, and the user can end it at any time. The cases in "When NOT to delegate" (a decline, the kill switch) still win over it.
+
+In this mode, work like this to keep your own token use down:
+
+- **Easy work**: one goal, touching at most 3 files plus their tests, concrete acceptance criteria, no dependence on context outside the repository, and none of the exclusions below. Delegate it whole: ask Antigravity to read the files it needs, make the change, run the checks the user has authorized, and report. Antigravity can run commands only when `agy_permissions` allows it (at `default`, expect writes and commands to be denied; then run the checks yourself). Then review the diff.
+- **Hard work** (design or architecture decisions, many interdependent files, ambiguous requirements, a bug with an unknown cause): you analyze it and fix the scope and design first. Delegate only the implementation of parts you have specified well enough to give acceptance criteria, one task at a time. Do the risky parts yourself, or review them line by line.
+- **Never delegate**, in any mode: security, authentication or secrets, data migrations or deletion, deployment, dependency, build or CI configuration, public API or contract changes. When unsure whether work is easy, treat it as hard.
+- **Avoid reading twice**: do not read the whole codebase before delegating. Give Antigravity only the context the task needs (paths, contracts, your findings) and let it read the rest.
+- **Watch less**: use a few long waits, take the report when the task ends, and do not keep reading logs.
+- **Check just enough**: Antigravity's own check results are a lead, not proof (the bridge always reports `acceptance_verified=false`). You may skip re-running minor, low-risk checks that it reported as passing. Run the key check that covers the change (tests, build or lint) yourself once at the end, always for risky changes, and again after any edit you make afterwards.
+- **Report briefly**: files changed, check results and remaining problems, plus which parts Antigravity did and which you did. Say in one line what you are delegating and why before you do it.
+
+Review every delegated diff. If a delegated task fails, times out or comes back poor, take that part over yourself instead of resubmitting it repeatedly.
+
 ## Before delegating
 
 - Discover the connected MCP tools by their advertised names; client prefixes may differ. Required names: `antigravity_environment`, `antigravity_delegate`, `antigravity_task_status`, `antigravity_task_wait`, `antigravity_task_output`, `antigravity_cancel_task`. Do not invent tools, CLI flags, or HTTP JSON-RPC payloads when MCP tools are available.
@@ -52,7 +68,7 @@ Call `antigravity_delegate` with only these fields:
 }
 ```
 
-Replace example paths and symbols with the user's actual authorized project. `context` and `timeout_seconds` are optional. Respect the server's timeout maximum (at most 900s). Input limits: task 16000 characters, workspace 4096, context 12000, 1–30 nonempty criteria up to 2000 each, combined serialized task data 24000 characters. No extra fields or NUL characters. Shorten oversized context rather than assuming it was accepted.
+Replace example paths and symbols with the user's actual authorized project. `context` and `timeout_seconds` are optional. Respect the server's timeout maximum (`limits.max_timeout_seconds` in the environment, 900s unless the owner raised it, never above 3600s). Give a larger task a larger `timeout_seconds`, but prefer splitting it: one goal and a few files per task finish sooner and leave a clear result if the deadline is hit. Input limits: task 16000 characters, workspace 4096, context 12000, 1–30 nonempty criteria up to 2000 each, combined serialized task data 24000 characters. No extra fields or NUL characters. Shorten oversized context rather than assuming it was accepted.
 
 `isError=true` is a tool error even if the client rendered text. Prefer `structuredContent`; otherwise parse the JSON text once. Do not treat the successful MCP transport as task completion. Save the returned `task_id`, workspace and criteria immediately; `running` means accepted, not implemented.
 
@@ -68,7 +84,7 @@ Client disconnect does not cancel an accepted task. Reconnect to the same runnin
 |---|---|
 | `completed` | Review actual diff and tests against the original criteria; CLI completion alone is insufficient. |
 | `failed` | Read error, exit_code, stderr, denied_actions and truncation; fix the specific cause before any retry. |
-| `timeout` / `canceled` | Check process_running and inspect partial file changes. Do not assume rollback or resend blindly. |
+| `timeout` / `canceled` | Check process_running and inspect partial file changes. Do not assume rollback or resend blindly. Files edited before the deadline stay on disk, so never treat a timed-out task as "nothing changed". If the work is unfinished, review what was done and submit a new, narrower task for only the remaining part, with what is already finished as context; do not resubmit the same task unchanged. |
 | `unsupported` | Report CLI capability/version diagnostics. Do not invent a fallback or change the version gate. |
 | `queued` | Accepted but not started: no process, no file changes yet. Keep waiting with `antigravity_task_wait` (the deadline starts when it begins running). It is refused/canceled if delegation is switched off before its turn. Cancel it through the cancel tool only if the user cancels. |
 | Still `running` | Continue within the deadline; cancel your own task through the cancel tool if the user cancels or it is demonstrably stuck. |

package/skills/known-versions.json

@@ -36,6 +36,18 @@
     {
       "sha256": "066f499ccd7341c7f77c2a409b3632e4cefe16e45ed2c77e75c8154028e951f9",
       "note": "long waits (limits.max_wait_seconds), fewer polling calls"
+    },
+    {
+      "sha256": "bf96a492847e59fcdbd4eb7685a316a606699af2d217ea35a8e27dad85ccb2aa",
+      "note": "timeout guidance: split tasks, narrower follow-up after a timeout, limits.max_timeout_seconds"
+    },
+    {
+      "sha256": "83a5d812553cc79e8eec690cef825ced49b82b13e0991d4c632de5b6675b19f1",
+      "note": "opt-in auto-split mode (easy parts to Antigravity, hard parts by the Tech Lead)"
+    },
+    {
+      "sha256": "978deb00a9eb68780297eaf538da9272ac11e94c2942141b1d5e999fee218354",
+      "note": "auto-split mode follows the token-saving workflow (delegate whole, check just enough, short reports)"
     }
   ]
 }