vg-coder-cli 2.0.46 → 2.0.48

package/INTEGRATION.md

@@ -0,0 +1,418 @@
+# VG Coder — Remote Task API Integration Guide
+
+Hướng dẫn tích hợp service ngoài để gửi task chat AI Studio và nhận kết quả qua local server VG Coder.
+
+## Kiến trúc
+
+```
+External Service ──HTTP──▶ POST /api/tasks (multipart)
+                                │  enqueue, persist .vg/tasks/<id>/task.json
+                                ▼
+                        TaskQueue (FIFO)
+                                │  load-balance → idle worker
+                                ▼
+              Socket.IO  task:execute  ──▶  Browser tab(s) on aistudio.google.com
+                                              │  AIChat.send({prompt, files})
+                                              │  copyLastTurnAsMarkdown()
+                                              ▼
+              Socket.IO  task:complete ◀──── result
+                                │  persist result.md, fire webhook
+                                ▼
+                        Launcher recycle ───▶ chrome.tabs.remove + create
+                                              │  fresh tab w/ ?model=<id>
+                                              ▼  next task gets clean chat
+External Service ◀── GET /api/tasks/:id   (polling)
+External Service ◀── POST <webhookUrl>    (push, retry 3×)
+```
+
+- **Server**: `http://127.0.0.1:6868` (localhost-only, không auth).
+- **Workers**: mỗi tab Chrome trên `aistudio.google.com` với extension VG Coder = 1 worker. Server tự load-balance song song giữa các worker idle.
+- **Launchers**: mỗi Chrome profile = 1 launcher (background service worker của extension). Dùng để mở/đóng tab AI Studio và lock model cho từng task.
+- **Auto-recycle**: sau mỗi task done/failed, server gọi launcher đóng tab worker đó + mở lại tab mới với `?model=<target>` — guarantee model lock per task. Mark worker `recycling` để tránh race.
+- **Failover**: rate-limit / quota error → mark worker `rate_limited` 30 phút, requeue task sang worker khác (max 3 attempts). Tab giữ nguyên qua cooldown (không recycle khi rate-limited).
+- **Default model**: `gemini-3-flash-preview` (free + multimodal — verified working với image + PDF). Avoid `-lite` (text-only) hoặc `-pro-preview` (paid alias to Deep Research).
+- **Persistence**: tasks lưu vào `.vg/tasks/<id>/{task.json,result.md,files/}` của active project.
+
+## Setup chạy
+
+### Server
+
+```bash
+npm install -g vg-coder-cli   # hoặc: cd repo && npm run build
+vg start                      # khởi động server :6868
+```
+
+### Worker (browser tab)
+
+Mỗi Google account muốn dùng → 1 Chrome profile riêng:
+
+1. Chrome → user menu góc trên-phải → **Add → Person** → đặt tên (ví dụ "Account 2") → Continue.
+2. Cửa sổ mới: login Google account đó.
+3. `chrome://extensions` → bật **Developer mode** → **Load unpacked** → chọn:
+   ```
+   /Users/<you>/.nvm/.../node_modules/vg-coder-cli/src/server/views/vg-coder
+   ```
+   (Có thể dùng đường dẫn local repo nếu dev: `<repo>/src/server/views/vg-coder`.)
+4. Truy cập `https://aistudio.google.com`.
+5. Click **Allow** trên popup `Access other apps and services on this device` (Chrome 130+ Private Network Access — chỉ hiện 1 lần / profile).
+
+> Worker tự register sau ~3-5s. Email được scrape từ DOM AI Studio. Verify:
+> ```bash
+> curl -s http://127.0.0.1:6868/api/workers | jq
+> ```
+
+## REST API
+
+### POST `/api/tasks` — submit task
+
+`Content-Type: multipart/form-data`
+
+| Field | Required | Mô tả |
+|---|---|---|
+| `prompt` | yes (hoặc files) | Text gửi cho AI |
+| `files[]` | no | File đính kèm (max 50 MB / file, max 10 file). PDF, ảnh, audio, video — AI Studio không nhận text |
+| `webhookUrl` | no | URL nhận callback khi task xong |
+| `meta` | no | JSON string, đính kèm metadata tùy ý (forward nguyên về webhook) |
+| `workerLabel` | no | Email worker để pin task vào tài khoản cụ thể (vd `alice@gmail.com`) |
+
+**Response 202**
+
+```json
+{
+  "taskId": "t_1778250830243_8630f8",
+  "status": "queued",
+  "position": 1,
+  "pollUrl": "/api/tasks/t_1778250830243_8630f8",
+  "createdAt": 1778250830243
+}
+```
+
+**Errors**: 400 (thiếu prompt + files), 413 (file > 50 MB), 500 (server error).
+
+### GET `/api/tasks/:id` — poll status
+
+```json
+{
+  "id": "t_...",
+  "status": "queued|running|done|failed|canceled",
+  "prompt": "...",
+  "meta": { ... },
+  "files": [{ "idx": 0, "name": "...", "mime": "...", "size": 1234 }],
+  "webhookUrl": "https://...",
+  "webhook": { "attempts": [{ "at": 0, "status": 200 }], "deliveredAt": 0 },
+  "worker": { "socketId": "...", "email": "alice@gmail.com", "chatId": "..." },
+  "workerLabel": null,
+  "attempts": [
+    { "workerEmail": "alice@gmail.com", "code": "rate_limit_exceeded", "at": 0 }
+  ],
+  "result": { "chatId": "...", "markdown": "..." },
+  "error": { "code": "...", "message": "..." },
+  "timing": { "createdAt": 0, "queuedAt": 0, "startedAt": 0, "finishedAt": 0, "durationMs": 0 },
+  "workingDir": "/abs/path"
+}
+```
+
+`result.markdown` chỉ có khi `status="done"`. `attempts[]` ghi mọi lần worker bị rate-limit và task được requeue.
+
+### GET `/api/tasks` — list tasks
+
+Query: `?status=done&limit=50`. Trả về summary (`id`, `status`, `prompt[0..200]`, `createdAt`, `durationMs`, `webhookUrl`).
+
+### DELETE `/api/tasks/:id` — cancel
+
+- `queued` → status `canceled`, remove khỏi queue.
+- `running` → best-effort: server gửi `task:cancel` cho worker, mark worker idle, status `canceled`, kết quả discard.
+- `done|failed|canceled` → 409.
+
+### GET `/api/tasks/:id/files/:idx` — file blob
+
+Worker dùng để fetch file đã upload. Caller thường không gọi.
+
+### GET `/api/workers` — list workers
+
+```json
+{
+  "workers": [
+    {
+      "id": "abc...",
+      "email": "alice@gmail.com",
+      "status": "idle|busy|rate_limited",
+      "currentTaskId": null,
+      "cooldownUntil": 1778252081156,
+      "lastSeen": 1778250177105,
+      "meta": { "domain": "aistudio.google.com", "chatId": "...", "registeredAt": 0 }
+    }
+  ]
+}
+```
+
+### GET `/api/launchers` — list profile launchers
+
+Mỗi Chrome profile có extension cài → background service worker = 1 launcher kết nối tới server qua socket.io. Launcher dùng để **auto-open AI Studio tab** khi không còn worker nào idle khớp với task (kể cả task pin email).
+
+```json
+{
+  "launchers": [
+    {
+      "id": "X0cKPmkz...",
+      "chromeId": "75cd593d-a861-4a6f-89a0-386e1e9e61c5",
+      "email": "alice@gmail.com",
+      "lastSeen": 1778305286920
+    }
+  ]
+}
+```
+
+`chromeId` là UUID lưu `chrome.storage.sync` lúc cài extension (per-profile). `email` được bind lúc worker đầu tiên trong profile đó register — sau đó server biết profile nào sign in account nào → routing pin chính xác.
+
+Auto-open flow:
+1. Task `enqueue` + không có worker idle khớp pin → server emit `launcher:open_aistudio` cho launcher có email khớp.
+2. Launcher SW: `chrome.tabs.query({ url: '*://aistudio.google.com/*' })` — nếu có tab cũ thì focus, không có thì `chrome.tabs.create({ url: '...?model=gemini-3-flash-preview' })`.
+3. Worker mới register sau ~3-5s → task dispatch.
+4. Fallback nếu không có launcher: server `open https://aistudio.google.com` qua OS default browser handler (cũ).
+
+### Tab management API (qua launcher)
+
+Server có thể chủ động list / đóng / mở tab AI Studio trong từng profile:
+
+| Method | Path | Body / Query | Mô tả |
+|---|---|---|---|
+| `GET` | `/api/launcher/tabs` | `?label=<email>` (optional) | List tabs trong profile (hoặc all profiles nếu bỏ label) |
+| `POST` | `/api/launcher/close-tab` | `{ workerLabel?, tabId? }` | Đóng tab cụ thể, hoặc tất cả tab AI Studio nếu bỏ `tabId` |
+| `POST` | `/api/launcher/open-tab` | `{ workerLabel?, model?, url?, active? }` | Mở tab mới. `model` mặc định `gemini-3-flash-preview` |
+
+```bash
+# List tab tất cả profile
+curl -s http://127.0.0.1:6868/api/launcher/tabs | jq
+
+# Reset tab profile alice về model multimodal
+curl -X POST -d '{"workerLabel":"alice@gmail.com"}' \
+  -H 'Content-Type: application/json' http://127.0.0.1:6868/api/launcher/close-tab
+curl -X POST -d '{"workerLabel":"alice@gmail.com","model":"gemini-3-flash-preview"}' \
+  -H 'Content-Type: application/json' http://127.0.0.1:6868/api/launcher/open-tab
+```
+
+### Modal auto-handling
+
+AI Studio thỉnh thoảng pop modal chặn task. Worker tự detect + click button đúng (poll mỗi 400 ms):
+
+| Modal heading | Action |
+|---|---|
+| `Start creating with media in Google AI Studio` | Click **Acknowledge** |
+| `Link a paid API key` / `Set up billing` | Click X (close) — fallback model multimodal free khác |
+| `We have updated our Terms of Service` | Click **Dismiss** |
+| Preference voting (`Skip`) | Click Skip |
+
+## Webhook payload
+
+Khi task chuyển `done | failed | canceled` và caller có `webhookUrl`, server `POST <url>` với:
+
+```json
+{
+  "taskId": "t_...",
+  "status": "done",
+  "result": { "markdown": "...", "chatId": "..." },
+  "error": null,
+  "durationMs": 14178,
+  "meta": { "your-custom-data": 123 }
+}
+```
+
+- 3 lần retry với delay 1s/4s/16s nếu non-2xx.
+- Failure không làm fail task; xem `task.webhook.attempts[]` để debug.
+
+## Error codes
+
+| Code | Khi nào | Failover? |
+|---|---|---|
+| `rate_limit_exceeded` | "You've reached your rate limit" | ✅ retry sang worker khác |
+| `quota_exceeded` | "Failed to generate content: user has exceeded quota" | ✅ |
+| `generation_failed` | Toast "Failed to generate content" khác | ✅ |
+| `model_internal_error` | "An internal error has occurred" | ❌ task fails |
+| `token_count_failed` | `.token-status-error` element | ❌ |
+| `worker_disconnected` | Worker tab đóng giữa chừng | ✅ nếu pin cho phép |
+| `server_restart` | Server restart khi task đang running | ❌ task fails, fire webhook 1 lần |
+| `dispatch_failed` | Lỗi gửi task tới worker | ❌ |
+
+Failover chỉ kick khi:
+- Code thuộc nhóm rate-limit/quota
+- `attempts.length < 3`
+- Có worker khác `idle` (và worker đó match `workerLabel` nếu pin)
+
+## Pin to specific account
+
+Pin = task chỉ chạy trên worker có email khớp `workerLabel`. Nếu worker đó `rate_limited` → task stay `queued` đến khi cooldown reset (30 phút). Không failover khi pin set.
+
+```bash
+curl -F prompt="Use alice's quota only" \
+     -F workerLabel="alice@gmail.com" \
+     http://127.0.0.1:6868/api/tasks
+```
+
+## Examples
+
+### Submit + poll
+
+```bash
+TID=$(curl -s -F prompt="Tóm tắt PDF này 3 gạch đầu dòng" \
+              -F files=@spec.pdf \
+              http://127.0.0.1:6868/api/tasks \
+        | jq -r .taskId)
+
+while true; do
+  RESP=$(curl -s "http://127.0.0.1:6868/api/tasks/$TID")
+  STATUS=$(echo "$RESP" | jq -r .status)
+  echo "status=$STATUS"
+  case $STATUS in done|failed|canceled) break;; esac
+  sleep 2
+done
+
+echo "$RESP" | jq -r .result.markdown
+```
+
+### Submit with webhook
+
+```bash
+curl -F prompt="Phân tích file đính kèm" \
+     -F files=@image.png \
+     -F webhookUrl="https://your-service.example/vg-callback" \
+     -F meta='{"jobId":"abc","userId":42}' \
+     http://127.0.0.1:6868/api/tasks
+```
+
+Service nhận POST từ server local → forward lên cloud / write DB.
+
+### Node.js client
+
+```javascript
+async function submitVgTask({ prompt, files = [], webhookUrl, workerLabel, meta }) {
+  const fd = new FormData();
+  fd.append('prompt', prompt);
+  if (webhookUrl) fd.append('webhookUrl', webhookUrl);
+  if (workerLabel) fd.append('workerLabel', workerLabel);
+  if (meta) fd.append('meta', JSON.stringify(meta));
+  for (const f of files) fd.append('files', f.blob, f.name);
+
+  const r = await fetch('http://127.0.0.1:6868/api/tasks', { method: 'POST', body: fd });
+  if (r.status !== 202) throw new Error(`HTTP ${r.status}`);
+  return r.json();
+}
+
+async function pollVgTask(taskId, { intervalMs = 2000, timeoutMs = 5 * 60_000 } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const r = await fetch(`http://127.0.0.1:6868/api/tasks/${taskId}`);
+    const t = await r.json();
+    if (['done', 'failed', 'canceled'].includes(t.status)) return t;
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  throw new Error('timeout');
+}
+```
+
+## Debug API
+
+Cùng tiếp đầu `/api/worker/...`. Optional query/body `workerLabel` để target worker cụ thể; bỏ qua = worker idle đầu tiên.
+
+| Endpoint | Mô tả |
+|---|---|
+| `GET /api/worker/url` | URL/title/chatId/rateLimit hiện tại |
+| `POST /api/worker/probe` | `{selector, kind}` → query DOM, kind = `text\|html\|outer\|attrs` |
+| `POST /api/worker/dom` | `{selector?, maxBytes?}` → outerHTML, truncate nếu > maxBytes (default 200 KB) |
+| `POST /api/worker/eval` | `{code, timeoutMs?}` → eval JS trong page (async được, return value serialize JSON) |
+| `POST /api/worker/logs` | `{since?, level?, limit?, clear?}` → console + window.error + unhandledrejection (ring buffer 200) |
+| `GET /api/worker/screenshot?format=png\|jpeg&quality=NN` | Native viewport capture qua `chrome.tabs.captureVisibleTab` (~250-500 ms). Tab AI Studio phải active. |
+
+```bash
+# Xem worker đang ở chat nào
+curl http://127.0.0.1:6868/api/worker/url?label=alice@gmail.com | jq
+
+# Inspect rate-limit text bất kỳ lúc nào
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"selector":".model-error, ms-upgrade-options-callout","kind":"text"}' \
+  http://127.0.0.1:6868/api/worker/probe | jq
+
+# Eval custom code
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"code":"return document.querySelectorAll(\"ms-chat-turn\").length"}' \
+  http://127.0.0.1:6868/api/worker/eval | jq
+
+# Capture screenshot worker hiện tại (PNG mặc định)
+curl http://127.0.0.1:6868/api/worker/screenshot -o /tmp/snap.png && open /tmp/snap.png
+
+# JPEG nén nhẹ — nhanh hơn, file nhỏ hơn (~50% size)
+curl "http://127.0.0.1:6868/api/worker/screenshot?format=jpeg&quality=60&label=alice@gmail.com" -o /tmp/snap.jpg
+
+# Xem console errors gần đây
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"level":"error","limit":20}' \
+  http://127.0.0.1:6868/api/worker/logs | jq
+
+# Logs từ thời điểm cụ thể (epoch ms) — polling incremental
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"since":1778300000000,"limit":50}' \
+  http://127.0.0.1:6868/api/worker/logs | jq '.logs[] | {at, level, message}'
+```
+
+## Known limitations
+
+- **PNA prompt** lần đầu / profile: Chrome 130+ bắt user click Allow. Server-side `Access-Control-Allow-Private-Network` header có nhưng Chrome vẫn show prompt; click 1 lần → permanent.
+- **AI Studio file types**: chỉ chấp nhận PDF / ảnh / audio / video. File text/markdown/code thường fail upload.
+- **Chat reset per task = recycle tab**: mỗi task xong server đóng tab + mở tab mới (`?model=<target>`). Tab disconnect ~3-5s giữa các task. Không "continue same chat".
+- **Single quota per account/day**: rate-limit auto-failover chỉ chuyển sang account còn quota.
+- **AI Studio đôi khi treo silent**: turn không render sau Run. Worker timeout default 5 phút sẽ đẩy task về `failed`.
+- **Tab AI Studio phải visible + active trong khi task chạy** — xem mục _Tab visibility constraint_ bên dưới.
+- **Model selection bị Angular routerLink ignore href**: AI Studio's "+ New chat" link không preserve `?model=` query → session drift sang Deep Research Preview. Workaround = recycle tab per task (đã implement).
+- **Binary file upload**: phải dùng direct fetch + Blob, KHÔNG qua extension proxy fetch (`vetgoFetch arrayBuffer`) vì chrome.runtime structured-clone corrupt ArrayBuffer (verify SHA-256 mismatch).
+
+## Tab visibility constraint
+
+Hệ thống dùng cơ chế "Copy as markdown" của AI Studio để lấy kết quả task — cụ thể: mở menu ⋮ trên turn cuối → click "Copy as markdown" → AI Studio gọi `document.execCommand('copy')` → script hook bắt nội dung. Đây là path duy nhất lấy được markdown chuẩn (DOM scrape không lossless cho code block / table / latex).
+
+Chrome enforce 2 điều kiện ở C++ layer cho `execCommand('copy')`, **không thể bypass bằng API hay flag**:
+
+1. Tab phải là **active tab** trong window của nó (`document.visibilityState === 'visible'`).
+2. Window chứa tab phải **không bị occlude** (không minimize, không bị app khác fullscreen che kín).
+
+Hệ quả: trong khi 1 task đang chạy (~10-15s) trên 1 worker tab, **user không được**:
+
+- Click sang tab khác trong cùng window AI Studio.
+- Minimize window đó (Cmd+M / nút vàng).
+- Để app khác fullscreen che kín window đó (đặc biệt trên macOS — strict occlusion detection).
+
+User vẫn có thể:
+
+- Làm việc ở **window Chrome khác** hoặc **app khác** (Cmd+Tab) — chỉ cần window AI Studio không bị che kín. Tab vẫn `visible` vì là active trong window của nó.
+- Đặt window AI Studio trên **monitor thứ 2** — luôn visible, không vướng workflow chính.
+- Đóng tab giữa các task (không đụng vào trong khi task chạy) — task tiếp theo launcher tự mở lại.
+
+Đã thử các approach để bypass và đều fail:
+
+| Approach | Vấn đề |
+|---|---|
+| `chrome.windows.create({ state: 'minimized' })` | `visibilityState='hidden'` → clipboard fail |
+| `state: 'normal' + focused: false` | macOS occlusion → vẫn `hidden` nếu bị app khác che |
+| Tab group collapsed | Tab bị treat như background tab → `hidden` |
+| `Page.bringToFront` (CDP) | Không override OS-level occlusion |
+| DOM scrape thay clipboard | Mất format code/latex/table → không acceptable |
+
+**Trade-off**: muốn task chạy 100% reliable thì user cần tuân thủ điều kiện trên. Nếu chấp nhận task fail thỉnh thoảng (do user vô tình minimize hoặc occlude), có thể bỏ qua — task sẽ failover sang worker khác hoặc retry.
+
+## Health check
+
+```bash
+curl http://127.0.0.1:6868/health
+# {"status":"ok","version":"2.0.49"}
+```
+
+## End-to-end smoke test
+
+```bash
+# T1-T5: submit, file+webhook, cancel, list workers, pin
+node tests/remote-task-e2e.js
+
+# D1-D4: debug API + file upload (logs, screenshot, image, PDF)
+node tests/debug-and-files-test.js
+```
+
+`debug-and-files-test.js` ghi log ra `/tmp/vg-test-log.txt`, screenshot ra `/tmp/vg-test-screenshot.{png,jpg}`, kết quả markdown ra `/tmp/vg-test-{image,pdf}-result.md`. Cần ≥1 worker idle với email thật + file fixture `tests/feline-xray-chest7.jpg` + `tests/REMOTE-SIGNING.pdf`. Verified: 4/4 tests pass trong ~87s.

package/bin/vg-coder.js

@@ -4,6 +4,13 @@
  * VG Coder CLI Entry Point
  */
 
+// Notify the user when a newer version is on npm. See bin/vg.js for details.
+try {
+  const updateNotifier = require('update-notifier');
+  const pkg = require('../package.json');
+  updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 6 }).notify({ defer: true });
+} catch (_) { /* ignore */ }
+
 const VGCoderCLI = require('../src/index');
 
 // Create and run CLI

package/bin/vg.js

@@ -4,6 +4,16 @@
  * VG Coder CLI Entry Point
  */
 
+// Notify the user when a newer version is on npm. update-notifier caches
+// the check (default ~6 hours via configstore) and prints a banner on
+// next process exit (defer: true) so it never blocks startup. Wrapped in
+// try/catch so a missing module / offline environment never breaks the CLI.
+try {
+  const updateNotifier = require('update-notifier');
+  const pkg = require('../package.json');
+  updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 6 }).notify({ defer: true });
+} catch (_) { /* ignore */ }
+
 const VGCoderCLI = require('../src/index');
 
 // Create and run CLI