# Overview / Giới thiệu
<!-- id: overview source: docs/wiki/overview.md -->

# Giới thiệu

> What Kazuo AI and Kazuo Hub are, who they are for, and what the ecosystem contains.

# Giới thiệu / Overview

## Tiếng Việt

**Kazuo AI** là ứng dụng desktop dạng **overlay trong suốt, click-through, luôn nổi trên màn hình** (giống Rainmeter). Người dùng thả các **widget dạng plugin** lên desktop: AI chat với agent Claude Code hoặc Codex thật, terminal, ghi chú, đồng hồ, quản trị server (Docker, Kubernetes, NGINX, database), quản lý Cloudflare, ghi màn hình, lập lịch công việc... Widget kéo thả, thu nhỏ, đổi kích thước hoặc tách thành cửa sổ riêng.

**Kazuo Hub** là ứng dụng launcher riêng (giống Steam/Discord updater): tải về từ `kazuo.kaiitech.net`, đăng nhập Google (tuỳ chọn), rồi cài đặt, cập nhật và khởi chạy Kazuo AI bằng một cú bấm trên Windows, macOS và Linux.

Hệ sinh thái gồm:

- **Web Dashboard**: cùng bộ widget như overlay nhưng mở trong trình duyệt, kể cả từ máy khác hoặc trên Linux/WSL không có giao diện đồ hoạ. Đăng nhập tại `dash.kaiitech.net` để chọn và điều khiển nhiều máy của cùng tài khoản.
- **Plugin Store, Skills Store, MCP Store**: cài plugin mới, cài "Skill" cho AI agent, và cài MCP server remote vào Claude Code / Codex / Hermes / ai-chat trực tiếp từ trong ứng dụng, không cần build lại.
- **Điều phối nhiều agent AI**: định nghĩa vai trò agent (agent-role), giao việc cho agent trên máy khác (orchestrator, task-manager), chạy agent theo lịch (cron-job), gọi agent từ plugin khác theo kiểu lập trình (run-agent).
- **Bridge + MCP server cục bộ**: cho AI agent điều khiển chính ứng dụng như người dùng thật, hữu ích khi tự phát triển và kiểm thử plugin bằng AI.
- **Ứng dụng di động** (Android/iOS) để xem Web Dashboard và nhận thông báo đẩy.
- **Dịch vụ đám mây**: đăng nhập, quản lý thiết bị từ xa, giấy phép theo tổ chức/gói, và relay giữa trình duyệt với từng máy.

Dành cho ai: lập trình viên và người vận hành hệ thống muốn một "bàn làm việc" trên desktop nơi AI agent và công cụ vận hành đứng cạnh nhau; đội nhỏ muốn quản lý nhiều máy từ một tài khoản.

Công nghệ: Electron 33 + Svelte 5 + Vite + TypeScript; dịch vụ đám mây chạy trên Cloudflare Workers.

## English

**Kazuo AI** is a **transparent, click-through, always-on-top desktop overlay** (in the spirit of Rainmeter). Users drop **plugin widgets** onto the desktop: AI chat backed by a real Claude Code or Codex agent, a terminal, notes, a clock, server administration (Docker, Kubernetes, NGINX, databases), Cloudflare management, screen recording, scheduled jobs and more. Widgets can be dragged, minimised, resized or popped out into their own window.

**Kazuo Hub** is a separate launcher (think Steam or the Discord updater): download it from `kazuo.kaiitech.net`, optionally sign in with Google, and install, update and launch Kazuo AI with one click on Windows, macOS and Linux.

The ecosystem includes:

- **Web Dashboard**: the same widgets as the overlay, opened in a browser, including from another machine or on Linux/WSL without a graphical desktop. Sign in at `dash.kaiitech.net` to pick and control any of your machines.
- **Plugin Store, Skills Store, MCP Store**: install new plugins, install "Skills" for AI agents, and register remote MCP servers into Claude Code / Codex / Hermes / ai-chat from inside the app, without rebuilding anything.
- **Multi-agent orchestration**: define agent roles (agent-role), delegate work to agents on other machines (orchestrator, task-manager), run agents on a schedule (cron-job), and call an agent programmatically from another plugin (run-agent).
- **Local bridge + MCP server**: lets an AI agent drive the application itself like a user would, which is how plugins are developed and tested with AI.
- **Mobile app** (Android/iOS) for the Web Dashboard and push notifications.
- **Cloud services**: sign-in, remote device management, per-organisation licensing, and the relay between a browser and each machine.

Who it is for: developers and operators who want a desktop "workbench" where AI agents and operations tooling sit side by side; small teams that want to manage several machines from one account.

Stack: Electron 33 + Svelte 5 + Vite + TypeScript; cloud services run on Cloudflare Workers.


---

# Kazuo AI (desktop app) / Kazuo AI (ứng dụng desktop)
<!-- id: kazuo-ai source: docs/wiki/kazuo-ai.md -->

# Kazuo AI (ứng dụng desktop)

> Transparent overlay, Web Dashboard, Plugin Store and headline features.

# Kazuo AI (ứng dụng desktop) / Kazuo AI (desktop app)

## Tiếng Việt

### Cài đặt và sử dụng

1. Tải **Kazuo Hub** tại `kazuo.kaiitech.net` cho đúng hệ điều hành.
2. Mở Hub → đăng nhập Google (tuỳ chọn, dùng cho quản lý thiết bị từ xa) → bấm **Cài đặt Kazuo AI**. Hub tải và cài im lặng, rồi có nút **Khởi chạy**.
3. Những lần sau Hub tự phát hiện bản mới và cập nhật bằng một cú bấm.

Sau khi cài, Kazuo AI chạy ẩn trong khay hệ thống và hiển thị overlay trong suốt trên desktop. Widget được thêm, gỡ và cấu hình qua màn hình **Settings** (icon bánh răng), nơi cũng có **Plugin Store**. Nếu overlay không hiển thị đúng trong máy ảo hoặc remote desktop, bật **Chế độ tương thích VM** (software rendering) trong Settings.

Trên macOS bản `.dmg` chưa ký số: cài qua Hub thì không vướng Gatekeeper; cài tay thì cần cho phép trong Privacy & Security. Phím tắt mở Launcher mặc định trên macOS là Option+Space. Ứng dụng xin quyền Accessibility (phím tắt toàn cục) và Screen Recording (chỉ khi dùng plugin ghi màn hình).

### Tính năng nổi bật

- Overlay desktop trong suốt, click-through; widget kéo thả, đổi kích thước 8 hướng, tách thành cửa sổ pop-out.
- **Web Dashboard** qua trình duyệt, dùng chung khung widget với overlay; chạy được ở chế độ headless trên Linux/WSL.
- **Plugin Store**, **Skills Store**, **MCP Store** ngay trong ứng dụng.
- **Terminal tích hợp** (node-pty + xterm) trên desktop.
- **Background động** cho overlay (gradient, hạt, mạch điện tử...), có thể đặt làm hình nền Windows.
- **Bridge server + MCP server cục bộ** để AI agent điều khiển ứng dụng.
- **Quản lý thiết bị từ xa**: đăng nhập Google; admin khoá máy hoặc ép cập nhật từ xa.
- **Phân quyền và giấy phép**: tổ chức, thành viên, gói với giới hạn số thiết bị và số ghế; giới hạn thiết bị thực thi cứng phía đám mây, plugin trả phí gate mềm phía ứng dụng.
- Đa nền tảng Windows (nsis), macOS (dmg, Intel + Apple Silicon), Linux (AppImage).

### Nhóm plugin

| Nhóm | Ví dụ |
|---|---|
| AI và agent | ai-chat, agent-role, orchestrator, agent-review, task-manager, cron-job, ai-voice, kchat |
| Năng suất | notepad, clock, notification, entity-notes, file-explorer, screen-lock |
| Ghi màn hình | capture-record, video-editor |
| Hạ tầng / DevOps | docker-manager, kubernetes, nginx-manager, service-manager, process-manager, prometheus, grafana, database-manager, ssh-reverse-proxy, window-sync, file-storage, backup-manager, device-manager, sandbox-manager, git-manager |
| Cloudflare | cloudflare-dashboard, cloudflare-dns, cloudflare-r2, cloudflare-security, cloudflare-tunnel, cloudflare-tunnel-runner, cloudflare-workers |
| Khác | kazuo-remote-desktop, game-analytic, awesome-selfhosted, n8n, telegram-web-archiver, kazuo-router, nine-router |

Danh sách đầy đủ kèm mô tả từng plugin nằm ở nhánh **Plugin** của wiki này. Plugin nào đi kèm bộ cài do cấu hình build quyết định; phần còn lại cài thêm qua Plugin Store.

### Kiến trúc tổng quan

```
Kazuo Hub (launcher)  ──tải & cài──►  Kazuo AI (Electron)
                                       ├─ main process: cửa sổ, vòng đời plugin, IPC,
                                       │   bridge server (loopback) + dashboard server, cloud client
                                       ├─ renderer (Svelte 5): overlay, Settings, Launcher,
                                       │   Web Dashboard, cửa sổ pop-out
                                       └─ mỗi plugin = một khung riêng (webview / iframe) + manifest.json
          ▲                                               ▲
   MCP server cục bộ                               dịch vụ đám mây (đăng nhập, thiết bị,
   (AI điều khiển app khi dev)                     giấy phép, relay nhiều máy)
```

Chi tiết "vì sao chia như vậy" ở trang **Kiến trúc**.

## English

### Install and use

1. Download **Kazuo Hub** for your OS at `kazuo.kaiitech.net`.
2. Open the Hub → optionally sign in with Google (used for remote device management) → click **Install Kazuo AI**. The Hub downloads and installs silently, then offers **Launch**.
3. Later the Hub detects new versions and updates with one click.

Once installed, Kazuo AI lives in the system tray and shows a transparent overlay on the desktop. Widgets are added, removed and configured from the **Settings** screen (gear icon), which also hosts the **Plugin Store**. If the overlay renders incorrectly inside a VM or remote desktop, enable **VM compatibility mode** (software rendering) in Settings.

On macOS the `.dmg` is not code-signed yet: installing through the Hub avoids Gatekeeper; a manual install needs approval in Privacy & Security. The default Launcher shortcut on macOS is Option+Space. The app asks for Accessibility (global shortcuts) and Screen Recording (only for the capture plugin).

### Headline features

- Transparent, click-through desktop overlay; drag, 8-direction resize, pop-out windows.
- **Web Dashboard** in the browser, sharing the widget frame with the overlay; headless mode on Linux/WSL.
- **Plugin Store**, **Skills Store** and **MCP Store** inside the app.
- **Built-in terminal** (node-pty + xterm) on the desktop.
- **Animated backgrounds** for the overlay (gradients, particles, circuitry), optionally as the Windows wallpaper.
- **Local bridge server + MCP server** so AI agents can drive the app.
- **Remote device management**: Google sign-in; admins can lock a machine or force an update remotely.
- **RBAC and licensing**: organisations, members and plans with device and seat limits; the device limit is enforced in the cloud, premium plugins are soft-gated in the app.
- Cross-platform: Windows (nsis), macOS (dmg, Intel + Apple Silicon), Linux (AppImage).

### Plugin groups

| Group | Examples |
|---|---|
| AI & agents | ai-chat, agent-role, orchestrator, agent-review, task-manager, cron-job, ai-voice, kchat |
| Productivity | notepad, clock, notification, entity-notes, file-explorer, screen-lock |
| Screen capture | capture-record, video-editor |
| Infrastructure / DevOps | docker-manager, kubernetes, nginx-manager, service-manager, process-manager, prometheus, grafana, database-manager, ssh-reverse-proxy, window-sync, file-storage, backup-manager, device-manager, sandbox-manager, git-manager |
| Cloudflare | cloudflare-dashboard, cloudflare-dns, cloudflare-r2, cloudflare-security, cloudflare-tunnel, cloudflare-tunnel-runner, cloudflare-workers |
| Other | kazuo-remote-desktop, game-analytic, awesome-selfhosted, n8n, telegram-web-archiver, kazuo-router, nine-router |

The full list with a page per plugin is under the **Plugins** branch of this wiki. Which plugins ship inside the installer is a build-time choice; the rest install from the Plugin Store.

### Architecture at a glance

```
Kazuo Hub (launcher)  ──download & install──►  Kazuo AI (Electron)
                                                ├─ main process: windows, plugin lifecycle, IPC,
                                                │   bridge server (loopback) + dashboard server, cloud client
                                                ├─ renderer (Svelte 5): overlay, Settings, Launcher,
                                                │   Web Dashboard, pop-out windows
                                                └─ each plugin = its own frame (webview / iframe) + manifest.json
          ▲                                                        ▲
   local MCP server                                        cloud services (sign-in, devices,
   (AI drives the app during development)                  licensing, multi-machine relay)
```

See the **Architecture** page for the reasoning behind this split.


---

# Architecture / Kiến trúc
<!-- id: architecture source: docs/wiki/architecture.md -->

# Kiến trúc

> Processes, plugin isolation and the reasoning behind the split.

# Kiến trúc / Architecture

## Tiếng Việt

Trang này trả lời **"vì sao chia như vậy"**, không phải "code nằm ở đâu".

### 1. Các tiến trình và ranh giới

| Vùng | Tiến trình | Vai trò |
|---|---|---|
| main (Node, Electron) | Main | Cửa sổ, vòng đời plugin, IPC, hai HTTP server cục bộ, cloud client |
| renderer (Svelte 5) | Renderer | Overlay, Settings, Launcher, Web Dashboard, cửa sổ pop-out |
| Plugin UI | `<webview>` (desktop) hoặc `<iframe>` (dashboard) | Mỗi plugin một khung riêng |
| Plugin backend | Main | Chỉ plugin có `mainEntry`; `activate()` / `deactivate()` |
| Dịch vụ đám mây | Cloudflare Worker | Đăng nhập, thiết bị, giấy phép, relay nhiều máy |
| Kazuo Hub | App Electron riêng | Cài và cập nhật Kazuo AI |

### 2. Một nguồn chân lý cho mỗi việc

Ba quyết định cùng một mô-típ, và đều sinh ra **sau khi sự cố lệch đã xảy ra thật**: điều khiển plugin (cài/gỡ/bật/tắt/pop-out) đi qua **một** module thay vì năm cổng tự viết; API `window['kazuo-ai']` mà plugin dùng có **một** lõi bridge dùng chung cho desktop lẫn web; gửi tin tới mọi cửa sổ có **một** hàm thay vì sáu vòng lặp tự chép. Bài học: cùng một nghiệp vụ viết ở nhiều nơi không sai ngay, chúng **trôi dần ra xa nhau** cho tới khi người dùng thấy hành vi khác nhau ở hai chỗ.

### 3. Một plugin hỏng không được kéo sập phần còn lại

Hàm bật plugin **không bao giờ reject**: vòng khởi động chạy tuần tự, nên một `manifest.json` hỏng từng làm mọi plugin xếp sau không bao giờ được bật. Bốn chi tiết bắt buộc: khởi động trên microtask; giải phóng slot ở cả hai nhánh và bọc cả `onError`; chờ 10 giây rồi thôi nhưng **không huỷ** (lần chạy đầu có thể cài npm hoặc tải Python mất hàng phút); kiểm tra lại sau khi `activate()` xong vì người dùng có thể đã tắt plugin trong lúc nó đang khởi động.

### 4. Vì sao hai HTTP server cục bộ, không phải một

| | Bridge server | Dashboard server |
|---|---|---|
| Phục vụ ai | Công cụ dev / MCP trên chính máy này | Trình duyệt, kể cả máy khác trong LAN |
| Bind | Loopback | Mọi giao diện mạng (cho WSL, máy khác, tunnel) |
| Luật Origin | Từ chối mọi request có header `Origin` | Phải chấp nhận trình duyệt |
| Xác thực | Không cần | Token bắt buộc cho mọi route API, cả GET; WebSocket dùng vé sống 60 giây |

Hai server có **threat model ngược nhau**, nên gộp làm một sẽ buộc chọn luật lỏng hơn cho cả hai. Luật từ chối mọi `Origin` của bridge chống một vector cụ thể: trang web độc trong trình duyệt của nạn nhân gọi tới loopback; CORS không cứu được vì CORS chỉ chặn đọc phản hồi, còn ở đây chỉ cần gửi được request là đã có hậu quả. Phía dashboard, chặn theo Origin là không đủ vì client không phải trình duyệt giả được header; token mới là thứ bảo vệ thật.

### 5. Cái gì tin được, cái gì không

- `pluginId` do client tự khai **không phải danh tính**: đường WebSocket mà mọi widget dùng từng trả nguyên settings của plugin khác. Nay settings đi qua lớp lọc.
- **Lọc bí mật theo kiểu dữ liệu, không theo tên key**: khớp theo tên từng biến cờ boolean thành falsy và tắt luôn yêu cầu xác thực. Bí mật luôn là chuỗi, nên chỉ lọc chuỗi.
- **Danh tính người phát hành plugin lấy từ tên file index**, không từ trường `author` tự khai. Danh sách người phát hành fail closed: file hỏng thì thu hẹp về một tên.
- **Mọi dữ liệu đọc từ registry là đầu vào không tin được**: id từ registry không được ghép thẳng vào đường dẫn, file nén không được tạo symlink trỏ ra ngoài, so khớp tiền tố phải có dấu phân cách thư mục.

### 6. Desktop và Web Dashboard dùng chung khung widget

Khung widget (kéo, resize, header, nút) nằm trong một component dùng chung, **không biết** bên trong là `<webview>` hay `<iframe>`. Khác biệt còn lại là có chủ đích: overlay trong suốt, dashboard nền đặc; dashboard cố tình hiển thị cả plugin chế độ cửa sổ vì trình duyệt không có cửa sổ hệ điều hành để bàn giao. Hai quyết định chống điều kiện tranh chấp: trạng thái phóng to không được lưu (chuỗi lưu → phát tin → nạp lại trên dashboard độ trễ cao có thể về lệch thứ tự); bộ đếm yêu cầu focus là biến thường, không phải trạng thái phản ứng.

### 7. Nhiều máy: relay qua Cloudflare

Mỗi thiết bị có một Durable Object làm điểm hẹn. Nguyên tắc: **token của máy không bao giờ rời khỏi máy**; trình duyệt định danh bằng token tài khoản, kiểm tại Worker trước khi chạm tới Durable Object; vé WebSocket bị gỡ khỏi URL trước khi chuyển tiếp. Chỉ một số tiền tố đường dẫn được tunnel; vỏ ứng dụng phục vụ tĩnh. Hai chi tiết phản trực giác: lỗi 401 từ relay không có nghĩa token hết hạn (có nhiều nguyên nhân cùng trả 401, agent phải hỏi lại server); đồng hồ máy lệch không được phép đăng xuất ai, server luôn là bên quyết định.

### 8. Cấu hình nền tảng tách khỏi mã nguồn

Mọi hằng số backend (tên miền, khoá đọc store, OAuth) gom vào hồ sơ cấu hình chọn lúc build, để người fork trỏ **cả hai app** về hạ tầng riêng bằng cách sửa một file. Các giá trị nằm trong bộ cài gửi tới người dùng vốn không thể giữ kín; yêu cầu thật chỉ là giữ khỏi git.

### 9. Khoá phiên khi nhiều agent cùng làm việc

Nhiều phiên AI song song dùng chung một thư mục làm việc, một tiến trình Electron, một thư mục build. Hook của công cụ AI ghi khoá (chỉ hook biết mã phiên), và hook **fail-open**: đây là công cụ điều phối chống nhầm lẫn, không phải hàng rào bảo mật, nên một guard hỏng không được làm tê liệt mọi phiên.

## English

This page explains **why the system is split the way it is**, not where the code lives.

### 1. Processes and boundaries

| Area | Process | Role |
|---|---|---|
| main (Node, Electron) | Main | Windows, plugin lifecycle, IPC, two local HTTP servers, cloud client |
| renderer (Svelte 5) | Renderer | Overlay, Settings, Launcher, Web Dashboard, pop-out windows |
| Plugin UI | `<webview>` (desktop) or `<iframe>` (dashboard) | One frame per plugin |
| Plugin backend | Main | Only plugins with `mainEntry`; `activate()` / `deactivate()` |
| Cloud services | Cloudflare Worker | Sign-in, devices, licensing, multi-machine relay |
| Kazuo Hub | Separate Electron app | Installs and updates Kazuo AI |

### 2. One source of truth per concern

Three decisions share a pattern, and each was made **after a real drift incident**: plugin control (install/uninstall/toggle/pop-out) goes through **one** module instead of five hand-written gateways; the `window['kazuo-ai']` API that plugins use has **one** bridge core shared by desktop and web; broadcasting to every window is **one** function instead of six copied loops. The lesson: the same logic written in several places is not wrong at first, it **drifts apart** until users see different behaviour in two places.

### 3. A broken plugin must not take the rest down

Plugin activation **never rejects**: the startup loop is sequential, so one broken `manifest.json` once prevented every later plugin from starting. Four mandatory details: start on a microtask; release the slot on both branches and wrap `onError` too; wait 10 seconds then move on but **never cancel** (a first run may legitimately install npm packages or download Python for minutes); re-check after `activate()` returns because the user may have disabled the plugin meanwhile.

### 4. Why two local HTTP servers, not one

| | Bridge server | Dashboard server |
|---|---|---|
| Serves | Dev tools / MCP on this machine | Browsers, including other machines on the LAN |
| Bind | Loopback | All interfaces (for WSL, other machines, tunnels) |
| Origin rule | Rejects every request carrying an `Origin` header | Must accept browsers |
| Auth | None needed | Token required on every API route, GET included; WebSocket uses a 60-second ticket |

The two servers have **opposite threat models**, so merging them would force the weaker rule on both. The bridge's reject-any-Origin rule defeats one specific vector: a malicious page in the victim's browser calling loopback; CORS does not help because CORS only blocks reading the response, while here merely sending the request has consequences. On the dashboard side, Origin checks are not enough because non-browser clients can forge the header; the token is the real protection.

### 5. What to trust

- A client-supplied `pluginId` is **not an identity**: the WebSocket path every widget uses once returned another plugin's raw settings. Settings now pass through a filter.
- **Filter secrets by value type, not key name**: name matching turned boolean flags into falsy values and silently disabled authentication. Secrets are always strings, so only strings are filtered.
- **Plugin publisher identity comes from the index file name**, not from a self-declared `author` field. The publisher list fails closed: a broken file narrows it to one name.
- **Everything read from the registry is untrusted input**: registry ids are never joined straight into paths, archives may not create symlinks pointing outside, prefix checks must include the directory separator.

### 6. Desktop and Web Dashboard share the widget frame

The frame (drag, resize, header, buttons) is one shared component that **does not know** whether it hosts a `<webview>` or an `<iframe>`. Remaining differences are deliberate: the overlay is transparent, the dashboard opaque; the dashboard intentionally shows window-mode plugins too, because a browser has no OS window to hand over to. Two race-condition decisions: maximised state is not persisted (the save → broadcast → reload chain can arrive out of order on a high-latency dashboard); the focus-request counter is a plain variable, not reactive state.

### 7. Many machines: relay through Cloudflare

Each device gets a Durable Object as its meeting point. Rule: **the machine's token never leaves the machine**; the browser identifies with an account token checked at the Worker before anything touches the Durable Object; the WebSocket ticket is stripped from the URL before forwarding. Only a few path prefixes are tunnelled; the app shell is served statically. Two counter-intuitive details: a 401 from the relay does not mean the token expired (several causes share that status, the agent must ask the server); a skewed clock must never log anyone out, the server always decides.

### 8. Platform configuration outside the source

Every backend constant (domains, store read key, OAuth) lives in a configuration profile chosen at build time, so a fork can point **both apps** at its own infrastructure by editing one file. Values shipped inside an installer cannot be kept secret from users anyway; the real requirement is keeping them out of git.

### 9. Session locks when several agents work at once

Several AI sessions share one working tree, one Electron process and one build directory. A hook of the AI tooling writes the lock (only the hook knows the session id), and the hook **fails open**: it is a coordination aid against mistakes, not a security barrier, so a broken guard must never paralyse every session.


---

# Agent Review / Agent Review
<!-- id: plugin-agent-review source: plugins-library/agent-review/README.md -->

# Agent Review

> Aggregate all Claude sessions (Windows + WSL) with conversationId, title and description; exclude workspaces/sessions and push sessions into Task Manager

| | |
|---|---|
| Version | 1.3.2 |
| Category | AI & Agents |
| Permissions | filesystem.read, filesystem.write |
| Depends on | ai-chat |

# Agent Review

Aggregate all Claude sessions (Windows + WSL) with conversationId, title and description; exclude workspaces/sessions and push sessions into Task Manager

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — scans `~/.claude/projects/**/*.jsonl` across Windows + WSL, exposes list + exclude IPC channels
- `main/code-review-ipc.ts` / `main/code-review.ts` / `main/discovery.ts` — separate **Code & Plan
  Review** feature: main-process-owned review lifecycle, read-only source review store (Markdown
  reports, freshness fingerprints, handoff claims), and plan-file discovery/fingerprinting. Requires
  an ai-chat build that exposes `capabilities.readOnlyReview`/`startExecution` on
  `globalThis.__kazuoAiChat` (older ai-chat versions make `start-code-review` reject with a
  restart-required error, no unrestricted fallback). Details: `.claude/features/agent-review-plugin.md`
  (section "Code & Plan Review"), `.claude/features/code-plan-review-ipc.md`.
- `js/code-review.js` / `css/code-review.css` — standalone dialog UI for the Code & Plan Review
  feature, added alongside `widget.html`'s existing toolbar; does not modify `js/widget.js`. Details:
  `.claude/features/code-plan-review-ui.md`.

## Default settings

- `excludedWorkspaces` — default: `[]`
- `excludedSessions` — default: `[]`
- `scanWsl` — default: `true` (also scan WSL Claude config dirs over UNC)

## Task Manager link

Each session's "+ Task" button calls `invoke('plugin:task-manager:upsert', ...)`. Task Manager must be
installed + enabled for that button to work; otherwise Agent Review runs standalone. See
`.claude/features/agent-review-plugin.md`.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts` or `main/code-review*.ts`/`main/discovery.ts`, recompile before testing:
`npx tsc -p tsconfig.plugins.json` (run from the project root). Code & Plan Review's Electron
end-to-end behavior has not been re-verified live as of this doc update — see
`.claude/features/agent-review-plugin.md`'s "Code & Plan Review" section for what is and isn't
confirmed yet.


---

# AgentRole / AgentRole
<!-- id: plugin-agent-role source: plugins-library/agent-role/README.md -->

# AgentRole

> Create and name multiple agents (a role is a system prompt + model + plugin list), then attach one to a workspace or session in AI Chat.

| | |
|---|---|
| Version | 1.0.5 |
| Category | AI & Agents |
| Depends on | ai-chat |

# AgentRole

Tạo và đặt tên nhiều **agent** (vai trò). Mỗi agent gói sẵn: tên + avatar + `systemPrompt` + danh sách
plugin. Agent được gán vào workspace/session của plugin **AI Chat** để tự động cấp bộ plugin + áp
system-prompt cho phiên chat (xem `plugins-library/ai-chat/.claude/features/attach-agent-role.md`).
Agent **không** đặt model — phiên luôn dùng model hiện tại của chính nó.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Mô hình dữ liệu

`settings.agents: Array<{ id, name, systemPrompt, plugins: string[], avatar }>`

- `id`: **đặt được lúc TẠO** (ô ID trong trình soạn) — slug `^[a-z0-9][a-z0-9-]{0,63}$`, unique; để trống
  thì tự sinh (`genId()`). **Khoá (read-only) khi sửa** để không gãy các tham chiếu `[agent-<id>]`.
- `systemPrompt`: có thể chứa tag tham chiếu `[agent-<id>]` (vd `[agent-kazuo-ui]`). Đây là **text nhắc
  tên thuần** — KHÔNG expand ở runtime; trình soạn có autocomplete (gõ `[agent-` → chọn agent → chèn
  `[agent-<id>]`). Dùng để agent/Manager biết id agent nào tồn tại mà `dispatch_agent(role: '<id>')`.
- `device`: **thiết bị mặc định** để `dispatch_agent` chạy agent này (`''` = máy hiện tại/local). Dropdown
  trong trình soạn lấy từ `plugin:device-manager:fleet-devices`. Khi Manager gọi `dispatch_agent(role)` mà
  KHÔNG truyền `device`, dùng giá trị này.
- `cwd`: **thư mục làm việc mặc định** cho agent (`''` = mặc định của máy đích). Tương tự, tool arg `cwd`
  (nếu có) sẽ được ưu tiên; không có thì dùng `cwd` của role.
- `plugins`: id các plugin (đang bật, có MCP tool) mà agent này gói theo.
- `avatar`: ảnh upload đã thu nhỏ về **32×32** (PNG data URL); rỗng = dùng ô chữ cái đầu tên. Thu nhỏ
  bằng canvas ngay trong renderer nên settings không phình to.

## Files

- `manifest.json` — metadata, `defaultSettings` (`{ agents: [] }`), `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — UI quản lý agent (danh sách + trình soạn:
  tên, model, system prompt, checklist plugin). Đọc/ghi `agents` qua `getSettings`/`setSettings`.
- `settings.html` / `js/settings.js` — trang thông tin ngắn (Plugin Manager); agent quản lý trong widget.
- `locales/en.json5` / `locales/vi.json5` — UI strings, namespace `widget.*` / `settings.*`
- `main/index.ts` (+ compiled `main/index.js`) — chạy ở Electron main process; chỉ 1 IPC read-only
  `plugin:agent-role:list-plugins` trả danh sách plugin đang bật có tool (cho checklist trong trình
  soạn). Việc lưu agent do renderer làm; ai-chat đọc `agents` trực tiếp qua `pluginControl`.

## Default settings

- `agents` — default: `[]`

## Test

Mở Kazuo AI → Plugin Manager — plugin xuất hiện tự động (host tự quét `plugins-library/`) → Install →
Enable. Tạo vài agent trong widget (đặt tên, viết system-prompt, tick plugin), rồi qua plugin
**AI Chat**: chuột phải vào thư mục hoặc phiên → "🎭 Gán agent" → chọn agent → gửi tin để agent kết
nối với bộ plugin + system-prompt đã gán (model vẫn là model đang chọn của phiên).

Sau khi sửa `main/index.ts`, biên dịch lại trước khi test: `npx tsc -p tsconfig.plugins.json`
(chạy từ project root).

## Orchestration tools (Manager Role — chia việc đa thiết bị)

`main/index.ts` export `getMcpTools` với 4 tool cho phép một role điều phối agent Claude Code chạy
local hoặc trên máy khác của cùng tài khoản (qua fleet relay). Chi tiết kiến trúc + bảo mật:
`.claude/features/distributed-agent-orchestration.md`.

- `list_devices` — máy của account + trạng thái online.
- `dispatch_agent({task, cwd?, device?, role?, model?, mode?, timeoutMs?})` — chạy 1 việc; trả `{jobId}`
  ngay (async). `device` rỗng/self = local; khác = remote. `role` = tên/id agent trên MÁY NÀY (resolve
  systemPrompt+plugins rồi truyền sang worker).
- `agent_status({jobId})` — snapshot không chặn.
- `agent_result({jobId, maxWaitMs?})` — poll có giới hạn (mặc định 90s), trả text khi xong; `running` thì gọi lại.

Tool nạp khi agent-role nằm trong bundle của session — **không cần Dev Mode** (đường MCP của ai-chat
không gate theo Dev Mode). Cần `zod` (khai trong `package.json`) + `ai-chat` bật (dùng
`globalThis.__kazuoAiChat.runAgent` cho local). Máy nhận việc cần bật kill-switch `acceptRemoteDispatch`
(mặc định on) + `claude` đã login.

**Preset "Manager" systemPrompt** (dán vào role, bundle `agent-role` + `task-manager`):
> Bạn là Manager điều phối. Chẻ yêu cầu thành các việc con ĐỘC LẬP. Mỗi việc gọi `dispatch_agent`
> (đặt `device` nếu cần máy khác — xem `list_devices`). Gọi nhiều `dispatch_agent` trong một lượt để
> chạy song song, rồi `agent_result(jobId)` từng việc và tổng hợp. Ghi tiến độ qua task-manager.


---

# AI Chat / AI Chat
<!-- id: plugin-ai-chat source: plugins-library/ai-chat/README.md -->

# AI Chat

> Claude Code agent chat: real tool use, permission prompts, session resume and a working folder — plus a plain Claude API fallback.

| | |
|---|---|
| Version | 2.4.18 |
| Category | AI & Agents |
| Permissions | network.remote, shell.exec |

# AI Chat

## Mục đích

Plugin chat với AI, chạy như một **Claude Code agent thực thụ** (giống app AgentSupport): làm việc trong một thư mục chọn được, hiện tool use (Read/Edit/Bash…) và kết quả, hỏi quyền Allow/Deny, thinking + thanh token context + slash commands. **Danh sách chat là cây workspace → session đọc trực tiếp từ các phiên Claude trên đĩa** (`~/.claude/projects`), không phải danh sách lưu trong plugin settings. Vẫn giữ nhánh Claude API (text thuần) làm dự phòng.

## File liên quan

- `plugins-library/ai-chat/manifest.json`
- `plugins-library/ai-chat/main/index.ts` — đăng ký IPC `plugin:ai-chat:*`
- `plugins-library/ai-chat/main/agent-session.ts` — bọc Claude Agent SDK (`query()` streaming input)
- `plugins-library/ai-chat/main/chat-manager.ts` — quản lý hội thoại, điều phối agent/API, lưu transcript
- `plugins-library/ai-chat/main/omp-cli.ts`, `omp-session.ts`, `omp-sessions.ts` — động cơ thứ hai **omp** (oh-my-pi):
  tự tải Bun + omp, chạy `omp --mode rpc` và đổi sự kiện sang cùng giao thức, đọc file phiên omp cho sidebar.
  Xem `.claude/features/omp-engine.md`.
- `plugins-library/ai-chat/main/plugin-control-mcp.ts` — MCP tool server chạy trong-process (Dev Mode
  only), cho AI agent của chính ai-chat list/toggle/đọc-ghi plugin KHÁC. Xem
  `.claude/features/plugin-mcp-control.md` cho toàn bộ kiến trúc (host-side + quy ước cho plugin mới).
- `plugins-library/ai-chat/package.json` — thêm dependency `zod` (dùng cho input schema của MCP tool)
- `plugins-library/ai-chat/main/providers/{base,registry,claude-code,claude}.ts`
- `plugins-library/ai-chat/widget.html`, `js/widget.js`, `css/widget.css` — gồm cả màn Settings nhúng
  (`#settingsScreen`, mở qua nút ⚙️ trong sidebar chat) — đây là giao diện Settings DUY NHẤT của
  ai-chat còn dùng được. (Mục "🛠️ Theo dõi dữ liệu gửi/nhận với Claude" đã bị gỡ — xem mục riêng
  bên dưới.) Màn này hiện là **sidebar bên trái**, mỗi section (AI Provider / Defaults / Instructions / Notifications / Snippets / Live Chat / Claude CLI / RTK / Codex / Backup) là một trang — dựng lúc runtime bởi `setupSettingsSidebar()` trong `js/widget.js` (gom mỗi `.settings-title` cấp cao nhất trong `.fullscreen-body` thành `.settings-page`; hẹp hơn ~520px thu thành icon rail), CSS scoped `#settingsScreen` trong `css/widget.css`. Xem `.claude/features/global-instructions.md`.
- `plugins-library/ai-chat/settings.html`, `js/settings.js`, `css/settings.css` — bản cũ, KHÔNG còn
  nơi nào load nữa (nút ⚙️ Settings trong mục Installed của Kazuo đã bị xóa, xem
  `.claude/features/plugin-settings-bridge.md`). Giữ nguyên file, không xóa, phòng khi cần dùng lại.
  Giao diện accordion mới của nó (commit restyle) đã được port sang màn Settings nhúng ở trên.
- `src/lib/plugin-bridge.ts` — `getPluginSettingsBridgeScript()` không còn được gọi ở đâu trong `src/`
  nữa (dead export, giữ lại). `src/config/PluginManager.svelte` không còn nút/panel Settings cho bất kỳ
  plugin nào — mỗi plugin tự lo giao diện Settings trong widget của chính nó.
- `plugins-library/ai-chat/locales/{en,vi}.json5` — chỉ có nhãn trạng thái kết nối (`chat.connection.*`), phần UI còn lại vẫn hardcode tiếng Việt
- `plugins-library/_shared/plugin-host-types.d.ts` — thêm `modules.claudeAgent`
- `electron/plugin-host.ts` — expose `@anthropic-ai/claude-agent-sdk` qua `ctx.modules.claudeAgent`
- `electron/plugin-ipc.ts` — `plugin:open-file-dialog` tôn trọng `options.properties` (để chọn thư mục)
- `src/components/WidgetLayer.svelte` — `ALWAYS_ALIVE_PLUGIN_IDS` (giữ webview ai-chat sống khi minimized)
- `src/components/PluginWidget.svelte` — prop `minimized` (ẩn bằng CSS thay vì unmount)
- `package.json` — dependency `@anthropic-ai/claude-agent-sdk`

## Cách hoạt động

- **Provider claude-code (mặc định)**: mỗi hội thoại gắn một `AgentSession`. Session mở một `query()` streaming-input sống lâu; mỗi lượt người dùng được push vào hàng đợi async, SDK stream trả về assistant/tool/result.
  - `AgentSession` serialize message SDK thành event đơn giản rồi phát qua `ctx.broadcast('plugin:ai-chat:event')`. Widget lắng nghe qua `window['kazuo-ai'].on('plugin-event')`.
  - Event: `connected` (sessionId + slash_commands), `stream_text`, `stream_thinking`, `assistant` (text/thinking/tool_use/tool_result), `tool_response`, `permission_request`, `result`, `context_window`, `done`, `error`, `mode_changed`, `slash_commands`, `task_status`.
  - **Quyền**: `canUseTool` chỉ được gọi ở chế độ cần duyệt (`default`/`plan`), không gọi ở `bypassPermissions` (auto). Nó phát `permission_request`, chờ widget trả lời qua `respondPermission`.
  - **Resume**: `sessionId` lưu trong conversation. Khi kết nối lại, nếu checkpoint `~/.claude/projects/<cwd-sanitized>/<id>.jsonl` tồn tại thì truyền `resume`.
  - `bypassPermissions` cần `allowDangerouslySkipPermissions: true`.
  - CLI: luôn dùng `claude` của hệ thống qua `pathToClaudeCodeExecutable` (bản bundled của SDK bị `npmPrune` xóa khỏi kho npm). Plugin tự dò/cài/nâng CLI — xem `.claude/features/claude-cli-install.md`.
  - **Thinking bị redact mặc định — đã verify thực tế**: nếu không set `thinking.display`, SDK vẫn phát `stream_thinking`/block `thinking` nhưng nội dung **rỗng** (chỉ là ping đếm token ẩn, xem `SDKThinkingTokensMessage`). Phải set `thinking: { type: 'adaptive', display: 'summarized' }` mới có tóm tắt suy nghĩ thật hiển thị được (verify: 0 ký tự → 160 ký tự khi bật `display:'summarized'`). `AgentStartConfig.thinking` nhận `'adaptive'` (mặc định) hoặc `'disabled'`.
  - **Subagent (Task tool) — đã verify thực tế**: `forwardSubagentText: true` được bật cứng trong `agent-session.ts` — mặc định SDK chỉ forward tool_use/tool_result của subagent (không text/thinking); bật cờ này để có luôn text/thinking subagent báo cáo. Message của subagent mang `parent_tool_use_id` + `subagent_type` (khớp `tool_use_id` của lệnh gọi Task) — `agent-session.ts` đính kèm 2 field này (`parentToolUseId`/`subagentType`) vào mọi event `assistant`/`tool_response`/`stream_text`/`stream_thinking` liên quan, để widget nhóm riêng.
  - **Task/subagent lifecycle**: xử lý system subtype `task_started`/`task_progress`/`task_updated`/`task_notification` → gộp thành event `task_status` (`{taskId, toolUseId, subagentType, description, status, summary, usage}`). `task_id → tool_use_id` được nhớ (`taskToToolUse` map) vì `task_updated` chỉ mang `task_id`. Bỏ qua khi `skip_transcript: true` (task nội bộ/ambient, CLI khuyến nghị ẩn khỏi transcript).
- **Động cơ omp (oh-my-pi) — chọn theo phiên**: ngoài Claude Code, mỗi tab có thể chạy bằng omp.
  - Chọn ở dòng "Động cơ" trong popup cài đặt phiên. Động cơ bị khoá sau tin nhắn đầu tiên.
  - omp chỉ chạy với **hồ sơ router** (có `ANTHROPIC_BASE_URL` + token). Hồ sơ "Mặc định" (gói Claude) bị chặn,
    vì omp chỉ đi được gói Claude bằng cách giả danh Claude Code (rủi ro khoá tài khoản).
  - `OmpSession` có cùng các hàm với `AgentSession` và phát ra cùng bộ event, nên widget không cần render riêng.
    Đổi model thì omp đổi ngay trên tiến trình đang chạy, không kết nối lại.
  - Phiên omp nằm chung sidebar (nhãn "omp"), xem lịch sử, mở lại, đổi tên và xoá được.
    Chưa hỗ trợ rẽ nhánh và xuất phiên.
  - `run-agent`/headless, review chỉ-đọc, agent-role có bộ tool riêng: **luôn chạy Claude Code**.
  - Tool của plugin đã gắn (phiên / thư mục / agent-role) dùng được với omp: ai-chat đăng ký chúng với omp qua lệnh RPC `set_host_tools` và tự chạy khi omp gọi.
  - Agent con của omp hiện như viên trạng thái subagent. Cảnh báo, lượt thử lại và lần rút gọn hội thoại của omp hiện thành dòng ghi chú trong khung chat.
  - Lý do + số đo (omp nhanh và tiết kiệm token hơn 2–4 lần với việc dài qua router, chất lượng như nhau):
    `plans/2026-09-26-omp-engine/reports/benchmark.md`.
- **Provider claude (API)**: đi qua `provider.sendMessageStream`, bắc cầu sang cùng bộ event (`stream_text`/`done`) để widget dùng chung một giao thức. Không có tool/quyền/session. Provider này có `modelSwitchMode: 'runtime'`, nên đổi model trong tab hiện tại vẫn hoạt động như trước.
- **Danh sách chat = session trên đĩa**: `configSources()` gom mọi config dir có `projects`: `~/.claude` của máy + `CLAUDE_CONFIG_DIR`/`CLAUDE_EXTRA_CONFIG_DIRS`. **Không còn tự dò WSL qua UNC** `\wsl.localhost\<distro>\home\*\.claude`: đó là share 9p của một máy ảo thường đang ngủ, đọc bằng lệnh **đồng bộ** trên tiến trình chính Electron — đo được ~250ms cho một lần đọc thư mục nguội, vài lần mỗi đợt quét cộng thêm một lần kiểm tra tồn tại cho mỗi phiên WSL, làm **đơ mọi cửa sổ tới 2,5 giây sau mỗi lượt chat**. Ai vẫn cần nguồn WSL thì khai báo thẳng đường dẫn đó trong `CLAUDE_EXTRA_CONFIG_DIRS`. Với mỗi nguồn, `withConfigDir()` set tạm `CLAUDE_CONFIG_DIR` rồi gọi `sdk.listSessions()`. `toLocalPath()` map cwd chéo nền tảng (`/mnt/c/…`→`C:\…`, `/home/…`→UNC). Gom theo cwd đã map (một thư mục có thể có phiên cả Win lẫn WSL), mỗi phiên mang `source` (Win/WSL) + `configDir`. Chọn phiên → `sdk.getSessionMessages()` (pin `CLAUDE_CONFIG_DIR` theo nguồn) để replay. Xóa qua `sdk.deleteSession()`.
- **Workspace ghim mặc định**: `workspaces()` luôn chèn 1 entry `pinned: true` với `cwd = process.cwd()` — thư mục root của dự án đang chạy app (plugin main chạy chung tiến trình Electron, không sandbox, nên `process.cwd()` trong plugin CHÍNH LÀ cwd của host). Luôn hiện đầu danh sách kể cả chưa có session nào; nếu đã có session thật ở đúng thư mục đó thì gộp chung (không tạo trùng). Widget: viền/nền vàng riêng + icon 📌, mặc định được chọn khi mở widget lần đầu (trước khi user bấm gì), nút `+` trên mỗi folder (kể cả 0 session) để mở phiên ngay.
- **Giới hạn resume WSL**: CLI Windows định vị phiên theo cwd đã sanitize; tên project dir của phiên WSL (`-mnt-c-…`) không khớp đường Windows nên **không live-resume phiên WSL từ Windows được**. Xử lý: phiên WSL **xem được lịch sử**; khi tiếp tục thì tạo **phiên mới cùng thư mục** (config Windows), không báo lỗi. Phiên Windows resume bình thường.

- **Provider/model metadata theo session**: khi Claude Code phát `connected` và có `sessionId`, `chat-manager.ts` lưu snapshot `{provider, model, contextSuffix, envProfileId}` vào `sessionMeta` cùng với `systemPrompt`. **`model` và `contextSuffix` là 2 field riêng** (base id + hậu tố `[..]`, vd `kimi-k3` + `[1m]`) — không bao giờ lưu id đã ghép vào metadata, chỉ ghép đúng 1 lần khi `agent.start()` (tránh session cũ chết khi proxy không còn nhận id ghép, vd lỗi "selected model may not exist"). Metadata cũ dạng `model: 'x[1m]'` được tách tự động khi đọc (migrate lướt dần). `workspaces()` merge metadata này vào mỗi session để sidebar hiện đúng provider/model; session cũ chưa có metadata fallback về `claude-code` + `sonnet` + `auto`.
- **Model switch runtime vs fixed-session**: provider expose `modelSwitchMode` qua `listProviders()`. Provider `claude`/`claude-code` mặc định vẫn runtime. Riêng profile proxy/WSL (`envProfileId === 'wsl-proxy'`, gồm cả `auto` trên session WSL khi profile này tồn tại) được widget coi là model cố định theo session: chọn model khác không đổi tab hiện tại mà hỏi tạo session mới cùng workspace với model mới.
- **Đa-tab song song**: `chat-manager` giữ `Map<tabId, TabState>`, **mỗi tab một `AgentSession` sống riêng** (một tiến trình `claude`) → chạy nhiều phiên cùng lúc. Mọi event mang `tabId` để widget route vào đúng tab (kể cả tab nền đang stream). Permission route theo `tabId` (map `permId→tabId`). IPC: `open-tab`/`close-tab`/`send`/`interrupt`/`set-*`/`permission` đều nhận `tabId`.
- **Kết nối CLI lười (lazy-connect) + chỉ báo trạng thái**: `open-tab` (IPC) giờ chỉ đăng ký state của tab (cwd/session/model/mode), **không** spawn tiến trình `claude` nữa (trước đây connect ngay khi mở tab). Tiến trình chỉ thực sự khởi động khi:
  1. Widget gọi IPC mới `connect-tab` — trigger duy nhất: người dùng **focus lần đầu** vào ô nhập (`#input`, hàm `onInputFocus` trong widget.js) trong khi tab đang ở trạng thái `disconnected`. Focus lại sau đó (đã connecting/connected) là no-op.
  2. Hoặc fallback có sẵn từ trước: `send()` (chat-manager.ts) tự gọi `connectAgentFor` nếu `t.agent` chưa có (vd. lỡ bấm Send mà chưa từng focus ô nhập).
  - `connectAgentFor` phát event `connecting` ngay trước khi tạo `AgentSession`; event `connected` có sẵn (system/init) coi như đã kết nối xong. Đổi model (`set-model`) / system prompt (`set-system-prompt`) vẫn dispose agent như cũ (không tự emit event) — widget tự set lại `disconnected` phía client ngay sau khi gọi các IPC này (`onModelChange`/`saveSysPrompt`) để tránh chỉ báo bị "kẹt" ở Connected trong khi tiến trình thật đã bị huỷ.
  - **UI**: chấm tròn + nhãn trong `subbar` (`#connStatus`/`#connDot`/`#connLabel`, ngay trên khung tin nhắn) — xám khi `disconnected`, vàng nhấp nháy khi `connecting`, xanh khi `connected`. Ẩn hẳn với tab dùng provider `claude` (API) vì loại này không có tiến trình sống để theo dõi. Mỗi tab giữ `connStatus` riêng (`t.connStatus`), phản ánh lại đúng khi chuyển tab (`activateTab` → `renderConnStatus()`).
  - Nhãn hiển thị đọc qua `window['kazuo-ai'].i18n` (khoá `chat.connection.connecting/connected/disconnected`, file `locales/{en,vi}.json5`), theo đúng ngôn ngữ đang chọn ở Settings > General — đây là chỗ đầu tiên trong ai-chat dùng cơ chế i18n chung của app; phần UI còn lại (placeholder, nút, hint...) vẫn hardcode tiếng Việt như trước, chưa refactor toàn bộ.
  - Chỉ ảnh hưởng tốc độ có sẵn danh sách slash-commands: trước đây connect ngay khi mở tab nên gõ `/` gần như luôn có sẵn danh sách lệnh; giờ nếu người dùng gõ `/` mà chưa từng focus ô nhập trong phiên đó, danh sách lệnh chỉ có sau khi kết nối xong (đã đánh đổi có chủ đích, xem thảo luận lúc thêm tính năng).
- **Đổi tên tab = đổi tên phiên thật**: `rename-session` gọi `sdk.renameSession()` (lưu `customTitle`, hiện luôn ở cây workspace). Sửa inline trên tab (double-click).
- **Rẽ nhánh hội thoại (bản widget của `/branch`)**: `fork-session` gọi `sdk.forkSession()` — copy transcript sang session mới, cắt tại một lượt hỏi nếu muốn, rồi mở thành tab mới. Bốn lối vào: nút 🌱 khi rê chuột lên bong bóng tin nhắn của mình (cắt tại đúng chỗ đó), chuột phải session ở sidebar, chuột phải tab, và gõ `/branch`. Session gốc không đổi. Chi tiết + các điểm dễ vấp: `.claude/features/branch-session.md`.
- **Bug đã sửa: minimize plugin xoá mất session/tiến trình.** `WidgetLayer.svelte` trước đây lọc bỏ MỌI plugin đang `minimized` khỏi danh sách render → Svelte unmount hẳn `<PluginWidget>` → cleanup của `onMount` xoá luôn thẻ `<webview>` (`plugins-library` chạy trong đó) → mất tiến trình renderer + toàn bộ state UI (tab đang mở, workspace đang chọn), dù CLI `claude` phía main process có thể vẫn sống (orphan, không dispose vì minimize không gọi `deactivatePlugin`). Widget thường (`WidgetConfig`) đã có cờ `keepAliveOnMinimize` để tuỳ chọn giữ sống, nhưng plugin thì không có cơ chế tương đương. Đã sửa: `WidgetLayer.svelte` hard-code `ai-chat` vào tập `ALWAYS_ALIVE_PLUGIN_IDS` — plugin này không bao giờ bị lọc khỏi render dù đang minimized; thay vào đó truyền prop `minimized` xuống `PluginWidget.svelte`, ẩn bằng `display:none` (webview vẫn sống) giống hệt cách `Widget.svelte`/`TerminalWidget.svelte` đã làm cho widget có `keepAliveOnMinimize`. Các plugin khác không đổi hành vi (vẫn unmount khi minimize).
- **Bug đã sửa: chạy lại plugin (tắt/bật, đóng app, đóng cửa sổ pop-out) không mở lại workspace/session đang mở.** `widget.js` chỉ giữ `tabs`/`selectedWs`/`activeTabId` trong biến JS của trang, không lưu ở đâu; `init()` cũ luôn khởi động với 0 tab mở. Đã sửa: mỗi lần `activateTab()` đổi lựa chọn (tab/workspace), widget gọi `persistLastActive()` → IPC `plugin:ai-chat:save-last-active` lưu `{cwd, tab: {cwd, originalCwd, configDir, sessionId, systemPrompt, model, contextSuffix, mode, provider, title, source}}` vào plugin settings (`chat-manager.ts`: `getLastActive`/`saveLastActive`, key `lastActive`, cùng cơ chế với `sessionMeta`). `init()` gọi `refreshTree().then(restoreLastActive)`: đọc lại qua IPC `plugin:ai-chat:last-active`, nếu workspace đã lưu còn tồn tại trên đĩa thì `selectWorkspace()` lại đúng workspace đó, và nếu có `sessionId` thì `reopenPersistedTab()` (giống hệt `openTabForSession`) mở lại đúng tab đó (resume qua checkpoint có sẵn). Chỉ khôi phục **workspace + tab active gần nhất** (không khôi phục toàn bộ tab từng mở) — các tab khác vẫn còn nguyên trong sidebar, bấm vào để mở lại khi cần. Biến `suppressPersist` chặn việc `activateTab(null)` (placeholder lúc boot) ghi đè state đã lưu trước khi `restoreLastActive()` kịp đọc.
- **Bug đã sửa: chuyển tab không cache/nạp lại nội dung đang gõ dở.** Mọi tab dùng chung một ô soạn tin nhắn (`#input`), nhưng `activateTab()` trước đây không hề đụng tới nó khi đổi tab — nội dung gõ dở của tab cũ vẫn còn nguyên trong ô, "dính" theo sang tab mới thay vì được cache lại theo đúng tab. Đã sửa: thêm field `draft` cho mỗi tab; `activateTab()` giờ lưu `$('input').value` vào `prev.draft` của tab đang rời đi (đọc qua `activeTab()` trước khi đổi `activeTabId`), rồi nạp `t.draft || ''` vào ô input của tab mới (kèm `autoResize`/`updateCharCount`/`hideAutocomplete`).
- **System prompt riêng mỗi phiên**: lưu ở plugin settings key `sessionMeta` ({[sessionId]: {systemPrompt}}) — thứ duy nhất plugin tự lưu; còn lại đọc từ đĩa.
- **CLI**: dùng `claude` hệ thống, thứ tự `KAZUO_CLAUDE_CLI` → `claudeCli.binaryPath` (máy tự ghi) → `~/.local/bin/claude[.exe]`. Chỉ nhận file **spawn trực tiếp được**, từ chối `.cmd`/`.bat` (Node ném EINVAL trên Windows) — nên KHÔNG dò trần tên `claude` trên PATH. Ô "CLI Path" trong Settings đã bị xóa; xem `.claude/features/claude-cli-install.md`.
- **Chọn thư mục**: widget gọi `window['kazuo-ai'].openFileDialog({properties:['openDirectory']})` (native dialog). Không cần modal browse như AgentSupport.
- **Gửi ảnh trong khung chat (chỉ provider claude-code)**: `sendMessage()` (widget.js) gom `pendingImages` (mảng `{mimeType, data, previewUrl, name}`, thêm qua nút 📎/paste/kéo-thả) và gọi `invoke('send', tabId, text, images)` với `images = [{mimeType, data}]`. `agent-session.ts` → `send(text, images)` đóng gói thành content block chuẩn Anthropic Messages API: `[{type:'image', source:{type:'base64', media_type, data}}, ..., {type:'text', text}]` (bỏ qua block text nếu rỗng — cho phép gửi ảnh không kèm chữ). Không hỗ trợ provider `claude` (API) — `pickImages()`/`sendMessage()` chặn và báo lỗi nếu tab đang dùng provider đó.
  - Đọc file thành base64 hoàn toàn ở renderer qua `FileReader.readAsDataURL()` — không cần IPC đọc file mới (khác với `openFileDialog` chỉ trả về path).
  - Giới hạn 8MB/ảnh (`MAX_IMAGE_BYTES` trong widget.js), không giới hạn số lượng ảnh mỗi lượt gửi.
  - Lịch sử: `sessionHistory()` (chat-manager.ts) đã nhận diện block `{type:'image'}` nằm trực tiếp trong content của tin nhắn user (không chỉ trong tool_result — xem bug đã sửa bên dưới) để ảnh đã gửi hiện lại đúng khi mở lại phiên cũ.

## IPC channels (`plugin:ai-chat:`)

Động cơ omp: `set-engine` (tabId, engine — `{ok, error?}`, bị khoá khi tab đã có sessionId), `omp-status` (trạng thái cài đặt), `omp-install` (tải Bun + omp, phát `omp_install_progress`/`omp_install_done`; từ chối khi đang có phiên omp chạy). `open-tab` nhận thêm `engine`.

`workspaces`, `session-history` (sessionId, configDir), `session-meta` (sessionId), `session-delete` (sessionId, configDir), `workspace-delete` (cwd đã map), `rename-session` (sessionId, title, configDir), `fork-session` (sessionId, configDir, upToUserIndex?, title? — trả `{sessionId}` của nhánh mới), `open-tab` (tabId, cfg — chỉ đăng ký, không connect), `connect-tab` (tabId — kết nối CLI lười, gọi khi focus ô nhập lần đầu), `close-tab` (tabId), `send` (tabId, text, images? — `{mimeType, data}[]`), `interrupt` (tabId), `permission` (tabId, id, allow), `set-mode` (tabId, mode), `set-model` (tabId, provider, model, contextSuffix?), `set-system-prompt` (tabId, prompt), `providers`, `reconfigure`, `last-active` (đọc workspace/tab đã lưu), `save-last-active` (cwd, tab).

## Chạy agent thay cho plugin khác (headless / visible execution)

Ngoài UI chat bình thường, ai-chat expose 2 cách cho **plugin khác** chạy 1 lượt Claude Code agent
theo lập trình, không qua widget:

- **Headless** (`runAgent()`/`plugin:ai-chat:run-agent`) — chạy 1 lượt rồi luôn tự đóng tab, không ai
  theo dõi được giữa chừng. Dùng cho automation im lặng (vd `agent-review`'s review mã nguồn). Chi
  tiết: `.claude/features/headless-run-agent.md`.
- **Visible** (`createExecutionService`'s `startExecution`/`executionState`/`revealExecution`) — mở
  tab và **giữ tab sống** sau khi dispatch để một widget mở sau có thể "bắt sống" (attach) lại, thay
  vì tự đóng. Dùng khi cần người dùng thấy được tiến trình đang chạy. Chi tiết:
  `.claude/features/visible-execution-service.md`.

Cả hai đều chỉ lộ qua **global service main→main** `globalThis.__kazuoAiChat` (`invoke` của Electron
chỉ đi renderer→main, nên main process của plugin khác không gọi thẳng IPC handler của ai-chat được;
mọi plugin backend chạy chung 1 tiến trình main nên ai-chat publish hàm lên biến global, guard
`version === 1` khi gỡ ở `deactivate()`). Cờ `capabilities.readOnlyReview: true` trên service này báo
cho bên gọi biết chế độ **chỉ-đọc có giới hạn quyền cứng** (`main/tool-policy.ts`'s
`buildReadOnlyReviewPolicy` — allowlist tool tường minh + chặn hết MCP tool + hook kiểm tra đường dẫn
đã resolve symlink) đã sẵn sàng cho các lượt chạy truyền `readOnlyScopeRoots`; thiếu cờ này (ai-chat
bản cũ) là lý do các bên gọi như `agent-review` từ chối chạy và yêu cầu khởi động lại app thay vì âm
thầm chạy không giới hạn quyền.

## UI

- **Dock engine**: Golden Layout v2, vendor bản UMD offline vào `js/vendor/golden-layout.min.js` + `goldenlayout-base.css` + `goldenlayout-dark-theme.css` (không CDN). Build lại khi cần nâng version: `npm i golden-layout@2 && npm run build:bundles` trong thư mục tạm, copy `dist/bundle/umd/golden-layout.js` rồi commit đè 3 file trên. Chi tiết: `.claude/features/dockable-ui.md`.
- Sidebar: cây **workspace (thư mục) → session**; mỗi folder mở/đóng, có số phiên, nút `+` tạo phiên mới, và menu chuột phải (`📂 Mở thư mục` — mở workspace trong File Explorer qua IPC `open-folder`/`shell.openPath`; `🎨 Đặt màu`/`🏷️ Đặt nhãn` — gắn màu accent + nhãn để phân biệt, lưu qua `set-session-deco`/`set-workspace-deco`; `Delete` để xóa workspace/session). Mỗi session hiện **badge nguồn (Win/WSL)** + tiêu đề + dòng phụ **provider · model** (ưu tiên metadata từ tab đang mở, fallback metadata đã lưu theo `sessionId`). Nút 📁 (mở thư mục mới) và ↻ (làm mới) ở đầu sidebar.
- **Thanh tab theo workspace**: tab bar chỉ hiện tab của **workspace đang chọn** (`selectedWs`). Click folder ở sidebar = chọn workspace → load lại danh sách tab đang mở của nó (nhớ tab active gần nhất qua `lastActiveByWs`); tab các workspace khác vẫn chạy nền. Workspace đang chọn được tô sáng + badge số tab mở. Mỗi tab: title, dấu ● khi đang chạy, nút × đóng; **double-click để đổi tên** (inline, lưu qua rename-session); **chuột phải mở menu** với `Export conversation` (mở UI chọn `Full` hoặc `Optimize`, rồi chọn nơi lưu file `.json`), `Import conversation` (xem mục riêng bên dưới) và `Đóng tab`. `Full` ghi raw session messages; `Optimize` chỉ giữ `{role, content}` từ text block user/assistant, bỏ thinking/tool_use/tool_result/tool nội bộ. Chọn phiên ở sidebar → mở tab mới (hoặc focus tab đã mở), tự chọn workspace của phiên. Nhiều tab chạy song song.
- **Import conversation** (menu chuột phải tab, cạnh `Export conversation`): chọn 1 file `.json` do chính tính năng Export tạo ra (mode `full` hoặc `optimize`), xác nhận qua `confirm()`, rồi tạo 1 tab **mới cùng thư mục** với tab đang chuột-phải vào và tự động gửi lại toàn bộ nội dung cũ (`role`/`content` đã chuẩn hoá qua `optimizedSessionMessages()`) làm **1 tin nhắn mở đầu** để Claude đọc ngữ cảnh rồi tiếp tục. **Không phải resume session thật** — file export không mang `sessionId` sống nên không cấy được vào 1 phiên CLI mới (giới hạn tương tự phần "Giới hạn resume WSL" ở trên); Claude chỉ "đọc lại" nội dung cũ dưới dạng text bình thường, không phân biệt turn như lịch sử thật. IPC: `import-conversation` (filePath) → `{ok, messages?, error?}` (`chat-manager.ts`'s `importConversationFile`).
- Topbar: sidebar toggle, tiêu đề là session title của tab hiện tại (tên workspace nằm trên dock tab của khung chat), nút `+` (phiên mới cùng thư mục), ✎ (system prompt). Nút mở thư mục mới và nút `/` skills không còn nằm trong topbar vì đã thừa với sidebar/input.
- Subbar: **chỉ báo trạng thái kết nối CLI** (chấm + nhãn, xem mục "Kết nối CLI lười" ở trên), đường dẫn cwd, chọn model, chọn chế độ quyền (Tự động / Tự sửa file / Hỏi trước / Kế hoạch). Responsive: cwd-label tự co/ellipsis, ẩn hẳn ở ≤640px và các select co lại — xem `.claude/features/subbar-layout.md`.
- Thanh context window (token) dưới subbar.
- Messages: bong bóng user/assistant, khối thinking (nay có nội dung thật, không rỗng), khối tool (bấm để mở input/kết quả), prompt quyền, dòng result (thời gian · token · cost).
- **Subagent turn** (`.subagent-turn` trong widget.js): text/thinking/tool_use/tool_result mang `parentToolUseId` được `ensureSubagentGroup()` gom vào một khối lồng riêng (viền xanh, nhãn "🤖 Subagent: <type>") thay vì trộn vào luồng chính — tái dùng nguyên `renderAssistant`/`renderToolResponse`/`appendStreamText`/`appendStreamThinking` bằng cách truyền một "sink" object cùng shape với tab (`{msgEl, assistant, thinking, lastToolName}`).
- **Subagent status pill** (`.subagent-status`, `updateTaskStatus()`): 1 dòng cập nhật tại chỗ theo `taskId`, chuyển "Đang chạy" → "Xong"/"Lỗi" khi có event `task_status`.
- **Raw Data** (`pinRaw`/`rawHostFrom`/`toggleMsgRaw` trong widget.js): chuột phải một mục bất kỳ trong transcript (bong bóng assistant, thẻ tool, kết quả tool, khối thinking, ảnh, dòng result, bảng tác vụ) → `{ } Dữ liệu thô` bung JSON gốc mà CLI gửi, ngay trong chính mục đó. Object được ghim vào phần tử lúc vẽ (`node._rawData`) nên không phải dựng lại từ HTML. Bong bóng `.msg.user` cố ý không có (đã có menu lưu câu mẫu / sao chép riêng), thẻ subagent cũng không (đã có nút `{ }` riêng). Chi tiết: `.claude/features/raw-data-context-menu.md`.
- **Markdown đầy đủ** (`renderMarkdown` trong widget.js): heading, **bảng** (`| a | b |` + `|---|`), list (ul/ol), blockquote, hr, fenced code (tách ra placeholder `@@CODEn@@` trước để không bị mangle), inline (code/bold/italic/strikethrough/link). Text đã stream cũng được convert markdown khi `assistant` event tới (trước đây bong bóng stream giữ nguyên plain text → bảng không hiện). CSS: `.md-table/.md-h/.md-list/.md-quote/.md-hr`.
- `handlePluginEvent` bọc try/catch → `console.error('[ai-chat] ...')` nếu một event render lỗi, để không làm chết handler cho các event sau + dễ chẩn đoán qua DevTools.
- Autocomplete slash khi gõ `/`; modal skills; modal system prompt.
- **Đính ảnh / tệp vào tin nhắn** (nút 📎 `#attachBtn`, `#attachPreview`, `#imageFileInput` trong widget.html): 3 cách nạp dùng chung `handleAttachedFiles()` — định tuyến theo loại file: (a) **ảnh** → `attachImageFile()` → `readImageAsDataUrl()` (FileReader) đẩy vào `pendingImages` **và** chèn token tham chiếu `[image#N]` vào ô nhập tại con trỏ (`insertComposerToken()`); (b) **tệp khác** → `insertFilePath()` lấy đường dẫn tuyệt đối rồi chèn vào ô nhập (bọc nháy kép nếu có khoảng trắng) để Claude Code tự đọc từ đĩa. 3 nguồn nạp: (1) bấm 📎 mở `<input type="file" accept="image/*" multiple">` ẩn, (2) paste (Ctrl+V) trên `#input` — bắt mọi `clipboardData.items` loại `file`, (3) kéo-thả file vào `#inputArea` (`dragover`/`drop`, class `.drag-over`). Ảnh chờ gửi hiện thumbnail 52×52 trong `#attachPreview` (nút × bỏ từng ảnh, `removePendingImage()`); gửi xong ảnh hiện trong bong bóng bằng `renderImage()`.
  - **Đánh số `[image#N]` theo từng tin nhắn**: số = vị trí ảnh trong `pendingImages` của tin nhắn hiện tại; gửi xong reset về `[image#1]`. Xóa 1 ảnh (`removePendingImage` → `removeImageTokenAt` + `renumberImageTokens`) thì gỡ token đó + đánh lại dãy `1..K` liền mạch. Agent ghép token với image block theo thứ tự trong lượt nói.
  - **Tô màu tham chiếu** (`renderRefText()`, CSS `.ref-chip`): tin nhắn user đã gửi tô xanh `#6495ed` cho `[image#N]`, URL, đường dẫn file/thư mục (drive/UNC/quoted/`/a/b`). Chỉ ở bong bóng chat — ô nhập (textarea) không tô được.
  - **Lấy đường dẫn đầy đủ** (`resolveFilePath()` → `window.__dwNative.getPathForFile`): Electron 32 đã gỡ `File.path`, nên host gắn preload tối thiểu `electron/webview-preload.ts` (expose `webUtils.getPathForFile`) vào mọi plugin webview qua thuộc tính `preload` (URL lấy từ `electronAPI.webviewPreloadUrl` — xem `PluginWidget.svelte`). Thiếu (chế độ web dashboard) thì fallback về tên tệp + cảnh báo `attach.pathUnavailable`.
- **Đã test render bằng jsdom** (harness ngoài): mô phỏng chuỗi event thật (stream_text → assistant có tool_use → tool_response) và xác nhận DOM sinh ra đúng `.tool` (Read/Bash/kết quả) + `.md-table/.md-h/.md-list`. Đây là cách đúng để verify tầng widget (trước đây chỉ verify tiến trình main phát event, KHÔNG đủ).
- **Xếp cặp tool_use ↔ tool_result** (`appendToolBlock`/`renderToolResult`/`appendInlineResult` trong widget.js): mỗi thẻ tool_use lưu chính nó vào `t.toolCards[block.id]`. Khi tool_result tới, nếu `tool_use_id` khớp một thẻ đã lưu thì **nối kết quả vào bên trong chính thẻ đó** (`.tool-result-inline`) thay vì tạo khối rời phía sau — đúng khi nhiều tool chạy song song và kết quả trả về không theo thứ tự gọi. Không tìm thấy thì fallback về khối rời như cũ (`appendResultBlock`). Đã verify jsdom: 2 tool_use (A, B) + result B đến trước result A → mỗi card vẫn chứa đúng kết quả của nó (không lẫn), không sinh khối rời.
- **Bug đã sửa: câu hỏi `AskUserQuestion` trong lịch sử cũ hiện JSON thô, sau đó làm cho tương tác lại được.** `renderToolUse` (widget.js) có case riêng cho từng loại tool (TodoWrite, Task, Edit, Write, Read, ExitPlanMode...) nhưng thiếu case cho `AskUserQuestion` → khi mở lại phiên cũ có câu hỏi này, nó rơi vào fallback chung và in JSON thô của `input.questions`. Đã thêm `renderAskUserQuestionHistory(t, questions)` xử lý riêng.
  - **Đã verify thực tế bằng 3 script probe gọi thẳng SDK (đã xoá sau khi verify xong)**: (1) khi tiến trình agent bị đóng/abort lúc `AskUserQuestion` còn treo, chính SDK tự ghi 1 `tool_result` lỗi vào transcript tại thời điểm abort (không phải do code plugin) — nên câu hỏi treo hầu như luôn có sẵn tool_result (dù là lỗi), trừ khi tiến trình bị **kill cứng thật sự** (SIGKILL, đã dựng lại bằng `child_process.spawn` + `child.kill('SIGKILL')` để verify) mới ra transcript hoàn toàn không có tool_result. (2) Dù ở tình huống nào, **resume KHÔNG bao giờ tự gọi lại `canUseTool`** cho lời gọi tool đã treo đó — kể cả khi (3) resume xong gửi thêm 1 tin nhắn mới ngay sau đó (model chỉ lờ đi và trả lời tin mới bình thường). Kết luận: promise chờ trả lời chỉ sống trong bộ nhớ tiến trình cũ, chết theo tiến trình — **không có cách nào làm SDK tự hỏi lại y hệt câu đó**, dù resume kiểu gì.
  - **Vì vậy hướng đi**: không cố "hồi sinh" đúng lời gọi cũ (bất khả thi, verify ở trên) — `renderAskUserQuestionHistory` render lại UI nút chọn/option y hệt bản live (tái dùng cấu trúc `renderAskUserQuestion`), nhưng khi bấm "Gửi câu trả lời" thì gọi `sendAsFollowupMessage(tabId, text)` — gửi 1 **tin nhắn chat mới bình thường** dạng `Trả lời câu hỏi trước đó:\n- <câu hỏi>: <trả lời>` (đã verify: gửi tin nhắn mới sau resume hoạt động bình thường). Có ghi chú nhỏ (`.perm-history-note`) trong khối để minh bạch với người dùng đây là tin nhắn mới, không phải trả lời trực tiếp cho lời gọi tool cũ. `sendAsFollowupMessage` là bản rút gọn của phần đuôi `sendMessage()` (thêm bong bóng user + set streaming + gọi IPC `send`), dùng `findTab(tabId)` vì có thể được gọi từ trong 1 nhóm subagent lồng (`sink !== t`) nhưng vẫn cần tab thật để gửi/theo dõi streaming.
- **Bug đã sửa: ảnh trong kết quả tool (tool_result) hiện JSON thô khi mở lại phiên cũ.** Live path (`agent-session.ts` → `serializeToolResult`) tách ảnh (`content` là mảng `[{type:'image', source:{...}}]`, ví dụ `Read` trên file ảnh) thành event `type:'image'` để widget vẽ `<img>` thật. Nhưng `chat-manager.ts` → `sessionHistory()` (đọc lịch sử tĩnh từ đĩa) thiếu case này, `JSON.stringify()` toàn bộ content không phải string → hiện khối JSON base64 khổng lồ thay vì tấm ảnh. Đã thêm cùng logic nhận diện ảnh vào `sessionHistory()`, đẩy ra `{type:'image', mimeType, data}` — widget đã có sẵn `renderImage()` xử lý đúng loại này trong `renderHistory()`.
- **Bug đã sửa: tool_result trong lịch sử cũ bị bỏ qua hoàn toàn.** `renderHistory` trước đây chỉ đọc `m.tools` khi `m.role==='assistant'` — nhưng tool_result nằm ở message `role==='user'`, nên khi mở lại phiên cũ, mọi kết quả tool biến mất, tool_use trông "mồ côi". Đã sửa: xử lý `m.tools` cho cả hai role.
- **Thanh ghim tin nhắn user = điều hướng lùi qua từng tin đã gửi** (`.pinned-user-bar`/`pinnedUserText`, `updatePinnedUserBar`/`scrollToLastUserMessage` trong widget.js): mỗi tab giữ `userMsgEls` (mảng phần tử DOM tin nhắn user top-level, cũ→mới) + `userMsgCursor` (index tin sẽ được cuộn tới ở lần bấm kế tiếp). Bấm thanh ghim: cuộn tới `userMsgEls[userMsgCursor]` (căn giữa khung chat), rồi lùi `userMsgCursor` về 1 tin cũ hơn và đổi luôn chữ hiển thị trên thanh ghim theo tin đó — bấm lặp lại để đi ngược qua toàn bộ tin đã gửi trong tab. Hết tin cũ hơn (`userMsgCursor < 0`) thì thanh ghim tự ẩn. Gửi tin mới hoặc mở lại lịch sử phiên (`renderHistory`) đều reset `userMsgCursor` về tin mới nhất. Đổi tab thì thanh ghim phản ánh đúng con trỏ riêng của tab đó. **Tự hiện lại khi cuộn về đáy** (`handleMsgScroll`/`scrollActiveToBottom`): cuộn tay (hoặc bấm nút cuộn-xuống-đáy) chạm đáy khung chat (`autoScroll` bật lại) sẽ reset `userMsgCursor` về tin mới nhất + gọi lại `updatePinnedUserBar` — tránh bug thanh ghim bị "kẹt ẩn" mãi sau khi đã lùi hết vòng, chỉ chờ tin mới mới hiện lại.
- **Bug đã sửa: chiều cao tool/message co lại thành 1 đường ngang sau nhiều lượt.** Nguyên nhân: `.messages`/`.subagent-turn-body` là flex column + `overflow-y:auto`; theo spec flexbox, container có scroll thì `min-height` tự động của con = 0 (không phải theo nội dung) — cộng `flex-shrink:1` mặc định khiến trình duyệt **co từng khối** để nhồi vừa thay vì cuộn, càng nhiều tool/message thì co càng mạnh. Fix: `flex-shrink: 0` cho `.msg, .tool, .perm, .subagent-turn, .subagent-status, .tool-image` — ép giữ chiều cao tự nhiên, để container cuộn (đúng ý muốn).

## Format hiển thị tool use / permission / option (giống claude-web-ui)

Port từ dự án tham chiếu `claude-web-ui` (`static/js/render/{tools,perms,results,todo}.js`), điều chỉnh cho đúng hành vi SDK Node đã verify thực tế:

- **Tool use theo từng loại** (`renderToolUse` trong widget.js): TodoWrite (checklist mở sẵn, nhóm theo trạng thái), Edit/MultiEdit (khối old/new đỏ/xanh), Write (preview nội dung), Read (đường dẫn + offset/limit), Task/Agent (badge loại subagent + prompt), ExitPlanMode (thẻ tóm tắt kế hoạch, không tương tác), fallback chung cho Bash/Glob/Grep/WebFetch/WebSearch/MCP (dòng tóm tắt + JSON thô).
- **Tool result**: nhận diện lỗi qua field `is_error` thật của SDK (đã verify `block.is_error` có trên tool_result — đáng tin hơn dò chuỗi `<tool_use_error>`), tự nhận diện diff (unified diff → tô màu +/-), tự nhận diện payload TodoWrite dạng JSON → render checklist thay vì JSON thô.
- **Permission — AskUserQuestion ("option")**: hiện nút chọn theo từng câu hỏi (label/description) + ô nhập "Khác..." tự do, nút "Gửi câu trả lời" gộp mọi câu. **Giao thức đã verify khác với Python reference**: SDK Node **không** áp dụng `updatedInput: {answers,...}` (model báo "chưa trả lời"). Cách đúng đã verify: `respondPermission` với AskUserQuestion luôn trả về `{behavior:'deny', message:'User answered:\n- <câu hỏi>: <trả lời>'}` — model đọc message và tiếp tục đúng.
- **Permission — ExitPlanMode**: thẻ riêng (markdown kế hoạch + đường dẫn file), nút Duyệt/Từ chối + phím tắt y/n (chỉ tác dụng khi tab đó đang active — tránh xung đột phím tắt giữa nhiều tab). Duyệt xong tự chuyển mode tab đó sang `bypassPermissions` (khớp hành vi reference `_switchToAutoAfterPlan`) để không bị hỏi lại từng tool sau khi kế hoạch được duyệt.
- **Permission — thường + suggestions**: nút Allow/Deny + phím tắt y/n (tab-scoped), cộng nút gợi ý "luôn cho phép/luôn từ chối theo rule" từ `canUseTool`'s `options.suggestions` (SDK `PermissionUpdate[]`) — bấm gửi `{allow:true, updatedPermissions:[su]}`.
- `agent-session.ts`: `makeCanUseTool()` giờ nhận tham số thứ 3 (`opts`) để lấy `suggestions`; phát hiện `AskUserQuestion` để đính `question_message`/`question_options`/`all_questions` vào event `permission_request`. `respondPermission(id, response)` nhận `boolean | answersMap | {allow, updatedPermissions}` tùy loại.

## Theo dõi traffic gửi/nhận với Claude (backend-only, UI đã gỡ)

> **Lưu ý**: mục Settings "🛠️ Theo dõi dữ liệu gửi/nhận với Claude (Dev Mode)" **đã bị gỡ**
> khỏi cả `widget.html` (màn Settings nhúng) lẫn `settings.html`. Phần ghi log backend bên dưới
> **vẫn chạy** nhưng hiện **không còn giao diện nào tiêu thụ** — giữ lại IPC/ring buffer để có thể
> debug hoặc dựng lại UI sau này.

- **Chỉ áp dụng cho provider `claude-code`** (CLI Agent) — đây là provider duy nhất có khái niệm
  workspace/session thật; provider `claude` (API) không có session nên không được theo dõi.
- **Ghi log**: `chat-manager.ts` có 1 ring buffer `traffic` (tối đa 300 dòng, cùng quy ước với
  `pluginLogs` phía host) — ghi LUÔN. Ghi ở 2 điểm: `send()` (hướng `send`, mỗi lượt user gửi
  tin/ảnh) và `handleAgentEvent()` (hướng `receive`, chỉ với các loại event có ý nghĩa —
  `connected`/`assistant`/`tool_response`/`permission_request`/`result`/`error`/`done` — bỏ qua các
  delta stream token-by-token `stream_text`/`stream_thinking` và event thuần UI để log không bị rác).
  Mỗi dòng ghi kèm `tabId`/`cwd`/`sessionId` tại thời điểm đó.
- **Lấy dữ liệu**: `getTraffic()` + IPC `plugin:ai-chat:traffic` (trong `main/index.ts`) và broadcast
  `emit({type:'traffic', entry})` qua kênh `plugin:ai-chat:event` vẫn còn nhưng không còn listener nào
  ở frontend.

## Test

```bash
cd plugins-library/ai-chat
node --check js/widget.js
node --test "test/**/*.test.js"
```

Sửa `main/*.ts` thì phải build lại **trước** khi chạy test (test main-process nạp `main/*.js`):

```bash
cd ../..            # thư mục gốc drawwindow
npx tsc -p tsconfig.plugins.json
```

⚠️ Phải có dấu nháy quanh glob. Từ Node 22, `node --test test/` coi tham số là **glob**, không phải thư mục
→ lỗi `MODULE_NOT_FOUND`. `node --test` không tham số thì nhặt cả `test/pretooluse-hook.demo.mjs` và fail.

| File | Phạm vi |
|---|---|
| `test/attach-filter.test.js`, `test/fs-index.test.js`, `test/rtk-*.test.js` | tiến trình main (`main/*.js` — **sản phẩm biên dịch** của `tsc -p tsconfig.plugins.json`; sửa `main/*.ts` thì phải build lại trước khi chạy test) |
| `test/widget-harness.js` | factory dựng `widget.html` + `js/widget.js` thật trong jsdom với bridge `window['kazuo-ai']` giả — không phải file test |
| `test/widget-pane.test.js` | 50 test tầng widget: T1-T18 characterization (Đợt 1), T19-T24 pane component, T25-T35 nhiều pane, T36-T41 kéo-thả tab, T42-T50 lưu/khôi phục + phím tắt + báo hiệu |

`jsdom` là devDependency ở **root** `drawwindow/package.json` (Node tự tìm ngược lên) — cố ý **không**
thêm vào `plugins-library/ai-chat/package.json`, vì file đó được cài vào `userData/plugins/` của người dùng.

**Harness giả lập 5 thứ jsdom không có** — mọi thứ đi qua chúng phải verify bằng tay, không tin test:
`ResizeObserver` (thiếu nó thì Golden Layout luôn ném và widget luôn rơi `dockFallback`),
`Element.scrollIntoView` (widget gọi **không bọc try** ở js:1394/3729/3851/5723), `Element.scrollTo`,
`window.matchMedia`, `window.__dwNative` (bridge clipboard do host tiêm).

Test có nhãn `[LOCK]` phải xanh vĩnh viễn. Nhãn `[CHANGED IN Pn]` là hành vi mà kế hoạch multi-pane
(`plans/2026-07-28-multi-pane-chat-sessions/`) **đã cố ý** đổi ở đợt n:

- **T14′** — phím `y`/`n`/`Escape` của hộp xin quyền không còn ăn khi con trỏ đang ở ô nhập
  (`canTakeHotkey`). Với nhiều khung, hành vi cũ khiến gõ chữ "n" ở khung này từ chối quyền của khung kia.
- **T2′ / T6′ / T8′** — "đang hiện" và bộ lọc workspace giờ là **theo từng khung** (`pane.activeTabId`,
  `pane.filterWs`), không còn là biến toàn cục.

T17 giữ nguyên: heading markdown `# input` vẫn sinh `id="input"` toàn cục, nhưng không còn hại — không
call site nào trong widget đọc `$('input')` nữa, mọi tra cứu trong khung đi qua `pe(pane, 'input')`.

## Kiến trúc tầng widget: chat panes

Vùng chat không còn là một khối duy nhất. `<template id="chatPaneTpl">` được nhân bản
thành N **pane**, mỗi pane có dải tab, ô nhập, dropdown và bộ lọc thư mục riêng; `tabs[]`
vẫn phẳng và mỗi tab mang `t.paneId`. Truy cập DOM trong pane đi qua `pe(pane, name)`
(theo `data-el`), không dùng `getElementById`. Chi tiết đầy đủ — 6 quy tắc kiến trúc,
kéo-thả, lưu/khôi phục, 2 IPC backend mới (`session-exists`, `open-tab` trả `false`) —
xem `.claude/features/multi-pane-chat.md`.

## Giới hạn / lưu ý

- **MCP tool điều khiển plugin khác (Dev Mode only)**: `connectAgentFor` (chat-manager.ts) gọi
  `buildPluginControlMcpServers(ctx)` mỗi lần 1 tab kết nối agent (`plugin-control-mcp.ts`) — trả về
  `undefined` nếu `ctx.store.get('devMode')` false, nên người dùng thường không cho AI đụng vào plugin
  khác. Khi Dev Mode bật, agent có thêm 8 tool chung (`list_plugins`, `get_plugin_manifest`,
  `toggle_plugin`, `get_plugin_settings`, `set_plugin_settings`, `read_plugin_source`,
  `write_plugin_source` — đọc/ghi CẢ source code plugin khác, `get_plugin_logs` — đọc log gần đây plugin
  đó tự gửi qua `ctx.log()`) cộng tool riêng của
  từng plugin đang active có export `getMcpTools(ctx)` (gom qua `electron/plugin-host.ts`'s
  `collectPluginMcpTools()`, tên tự thêm tiền tố `<pluginId>_`). Bật/tắt Dev Mode giữa chừng 1 phiên
  chat đang mở KHÔNG áp dụng ngay — cần agent kết nối lại (giống đổi model/system prompt).
- Cần CLI `claude` đã đăng nhập (dùng subscription local) hoặc auth qua env.
- Với proxy/WSL profile (`wsl-proxy`), model bị cố định theo session tại thời điểm tạo/kết nối. Muốn dùng model khác thì tạo session mới; session cũ vẫn giữ provider/model đã lưu.
- **Model theo proxy**: mỗi profile ngoài `default` có thể khai báo danh sách model nó hỗ trợ (nhập tay, mỗi dòng 1 model, ô riêng trong Settings). Khi có, dropdown model chỉ hiện các model này cho tab dùng profile đó (thay list Claude mặc định). Chỉ là chuyện UI — backend vẫn gửi model đã chọn cho CLI như cũ. Xem `.claude/features/env-profiles.md`.
- Mỗi tab một `AgentSession` sống riêng (xem mục Đa-tab); trong MỘT tab, đổi model/system prompt vẫn dispose agent của tab đó rồi kết nối lại (resume giữ ngữ cảnh).
- Lịch sử replay đọc từ đĩa: gộp text + tool blocks + `thinking` mỗi message. Subagent transcript (Task tool) KHÔNG được replay lồng khi mở lại phiên cũ — `getSessionMessages()` mặc định chỉ trả message luồng chính; muốn có cần `listSubagents`/`getSubagentMessages` riêng (chưa làm, biết giới hạn này).
- **omp**:
  - Lần đầu phải tải khoảng **1GB** (Bun ~82MB + omp ~918MB, không tỉa gói tuỳ chọn) vào `userData/ai-chat/omp`.
    Xoá thư mục đó là gỡ sạch.
  - Phiên bản được **ghim** (`OMP_VERSION` trong `main/omp-cli.ts`, hiện 18.3.2). Không tự cập nhật,
    vì giao thức RPC của omp đổi nhanh.
  - omp vẫn ghi cache/log vào `~/.omp` dù đã đặt `PI_CODING_AGENT_DIR`. Log request lỗi đã kiểm, không chứa token.
  - Token router chỉ truyền qua biến môi trường, không ghi ra `models.yml`.
- Plugin chạy từ bản đã cài `userData/plugins/ai-chat/`. Sau khi sửa `plugins-library/ai-chat`, phải build lại (`tsc -p tsconfig.plugins.json`) và cài lại/đồng bộ plugin để bản chạy cập nhật.


---

# AI Voice / AI Voice
<!-- id: plugin-ai-voice source: plugins-library/ai-voice/README.md -->

# AI Voice

> Nhận diện giọng nói thành văn bản (Speech-to-Text) qua OpenRouter + Gemini, hỗ trợ wake word và ghi mic

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Permissions | network.remote, process.spawn, filesystem.read, filesystem.write |
| Depends on | ai-chat |

# AI Voice

Nhận diện giọng nói thành văn bản (Speech-to-Text) qua OpenRouter + Gemini, hỗ trợ wake word và ghi mic.

Đây là bản port của app `stt` (OpenRouter + Gemini) thành plugin Kazuo. Toàn bộ xử lý audio
(ghi mic, VU meter, waveform, wake word bằng openWakeWord/ONNX, gọi OpenRouter) do **backend Python**
đảm nhiệm — plugin bundle sẵn code Python trong `python/` và `main/index.ts` spawn nó khi enable.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Yêu cầu (bắt buộc)

- **Python 3.10+** cài sẵn và có trong PATH (main thử `python` → `py` → `python3`).
- Cài thư viện Python 1 lần:
  ```bash
  pip install -r plugins-library/ai-voice/python/requirements.txt
  ```
  (khi cài plugin, thư mục được copy sang `userData/plugins/ai-voice/python/` — nếu chưa cài deps ở
  môi trường Python đang dùng thì backend sẽ thoát và widget hiện thông báo `pip install ...`).
- Nhập **OpenRouter API Key** trong Settings của plugin (lấy tại openrouter.ai/keys).

## Cách hoạt động

- `main/index.ts` (main process): khi `activate` → spawn `python backend.py` (cwd = `python/`), truyền
  `OPENROUTER_API_KEY` từ settings qua env. `deactivate` → kill tiến trình. Kênh IPC:
  - `plugin:ai-voice:status` — widget hỏi trạng thái backend (đang chạy? lỗi gì?) để hiện thông báo.
  - `plugin:ai-voice:restartBackend` — respawn để nhận API key mới sau khi lưu Settings.
  - `plugin:ai-voice:writeText` — ghi transcript ra file người dùng chọn (sandbox không tự ghi được).
- `python/backend.py`: mở WebSocket `ws://127.0.0.1:8765`, xử lý lệnh phiên âm/ghi/wake word.
- `js/widget.js` (webview): kết nối thẳng WebSocket đó (không qua IPC), vẽ UI. Chỉ dùng
  `window['kazuo-ai']` cho 3 việc: `openFileDialog` (chọn file), `serveLocalFile` (nghe lại bản ghi),
  `saveFileDialog` + `invoke writeText` (lưu .txt).

## VAD endpointing (cắt đoạn giọng nói)

Thay vì luôn ghi cứng đủ số giây rồi gửi Gemini, plugin dùng **Silero VAD** (bundle sẵn trong
`openwakeword` — 0 dependency mới) để: chờ tới khi bạn **bắt đầu nói** → ghi → **dừng khi im lặng** →
cắt đúng đoạn giọng nói (kèm đệm) rồi mới gửi. Nếu không nói trong thời gian chờ → **hủy, không gửi**
(tránh gửi audio rỗng/noise, đỡ tốn token, bỏ transcript rác). Áp cho cả wake-word tự kích hoạt lẫn
nút "▶ Phiên âm".

### Profile môi trường (switch nhanh)

Dropdown **"Môi trường"** trên widget: mỗi profile (Yên tĩnh / Văn phòng / Ngoài trời / Trên xe /
Máy lạnh·quạt, hoặc do bạn **tạo thêm**) giữ **bộ tham số VAD riêng**. **Switch profile → áp ngay** tham số
của môi trường đó (đi đâu chọn đó). Trong wizard có thể **➕ Tạo** profile mới (đặt tên) và **🗑 Xóa**.

### Hiệu chỉnh tự động (wizard)

VAD phụ thuộc mic/giọng/môi trường. Có **wizard hiệu chỉnh theo bộ mẫu nhiều môi trường**: tự mở lần đầu
(hoặc bấm **"🎚 Chạy hiệu chỉnh VAD"** trong ⚙ Settings của widget). **Thu tự do**: nhập **tên môi trường**
rồi bấm **"🤫 Thu tiếng nền (2s)"** hoặc **"🗣 Thu giọng nói (4s)"** — thu bao nhiêu mẫu ở bao nhiêu môi
trường tùy ý; mỗi lần lưu 1 bản ghi WAV ở `vad-samples/`. **Danh sách bản ghi** cho chọn nhiều (checkbox),
**nghe lại (▶)**, **Chọn tất cả / Xóa đã chọn / Mở thư mục** (xóa & mở thư mục dùng plugin **File Explorer**,
cần bấm Grant 1 lần). Mẫu thu + danh sách gắn theo **profile đang chọn**. Bấm **"⚙ Tính tham số từ bộ
mẫu"** → gộp bản ghi nền/giọng của **profile đó** → tự tính
**Khuếch đại + Ngưỡng âm lượng + Ngưỡng VAD** + hiện sóng giọng-gộp so với vạch ngưỡng đề xuất →
**"Áp dụng & xác nhận"**. Bản ghi **chỉ mất khi bạn tự xóa**. Cờ `vad_calibrated` đánh dấu đã hiệu chỉnh.

**Học môi trường một chạm** (nhạc nền, quạt, tiếng ồn liên tục): bấm **"🎵 Học môi trường (8s)"** trong
wizard khi đang **im lặng** → thu 8 giây tiếng nền, **không cần mẫu giọng nói và không lưu bản ghi**. Giữ
nguyên Khuếch đại hiện tại, đặt **Ngưỡng âm lượng** = mức nền (phân vị 95%) × 1.3 + 0.03 (kẹp 0.02–0.5) và
**Ngưỡng VAD** = max(0.5, xác suất Silero nền + 0.15) (tối đa 0.9). Kết quả hiện ở khu "Tham số đề xuất" →
bấm **"Áp dụng & xác nhận"**. Nếu nền quá to (ngưỡng chạm trần 0.5) thì nên giảm âm lượng nhạc.

- Bật/tắt bằng ô **"Bỏ qua khi không có giọng nói"**. **Tắt → về hành vi ghi cứng đủ ô "Giây" như cũ.**
- Slider **"Ngưỡng VAD"** (cao = chặt hơn, ít bắt nhầm noise). Nên để ~0.5; quá thấp (vd 0.05) khiến
  VAD luôn tưởng có giọng → không bao giờ dừng/bỏ qua.
- **Ô "Giây" KHÔNG áp cho chế độ VAD** — khi bật VAD, cơ chế dừng là im lặng, còn trần an toàn là
  `vad_max_record` (mặc định **30s**, chỉnh trong `python/config.json5`). Ô "Giây" chỉ dùng khi VAD tắt
  (ghi cứng). Trần đếm từ lúc bắt đầu nói.
- **5 tham số VAD chỉnh trực tiếp trên widget** (tự lưu vào `config.json5`):
  - **Chờ tối đa** (`vad_max_wait`, 3.0s) — quá hạn chưa nghe thấy giọng → bỏ qua.
  - **Im lặng dừng** (`vad_silence`, 0.8s) — im liên tục bấy nhiêu sau khi nói → dừng & gửi. Bị cắt cụt
    khi nói ngập ngừng → **tăng** giá trị này.
  - **Giọng tối thiểu** (`vad_min_speech`, 0.2s) — thời lượng giọng nói để coi là "bắt đầu".
  - **Đệm** (`vad_pad`, 0.2s) — thêm trước/sau đoạn cắt; hụt đầu/cuối câu → **tăng**.
  - **Trần ghi** (`vad_max_record`, 30s) — chốt chặn an toàn, đếm từ lúc bắt đầu nói.
  - Không bắt được giọng / cắt sớm → **giảm Ngưỡng VAD** trước, rồi tăng Im lặng / Chờ tối đa.
- **Sóng âm + VU meter** hiển thị mức tín hiệu khi nghe wake và khi đang ghi (giúp căn micro/độ to).
  Trên sóng còn có **đường ngưỡng** (vàng, di chuyển live khi kéo slider) + **đường xác suất giọng nói**
  (xanh, chỉ khi đang ghi): bấm "▶ Phiên âm" nói thử, chỉnh slider sao cho lúc nói đường xanh vượt đường
  vàng, lúc im thì dưới.
- **Hạn chế:** VAD chỉ phân biệt "có/không có giọng nói", **không lọc giọng người khác** — ai nói trong
  khoảng ghi đều bị thu. Nói ngập ngừng quá `vad_silence` có thể bị cắt cụt (tăng `vad_silence` nếu cần).
  Sóng âm hiển thị **biên độ** (độ to), không trực tiếp bằng ngưỡng VAD (ngưỡng so với xác suất giọng nói).

## STT cục bộ (on-device) + chữ tạm

Ngoài OpenRouter (cloud), backend chạy được 3 engine **ngay trên máy**: `faster-whisper`
(CPU/GPU), `whisper.cpp` (`pywhispercpp`) và `sherpa-onnx` (model tiếng Việt 30M, rất nhẹ).
Thư viện + model **tự cài khi chọn lần đầu** (pip + tải về `stt-models/`, đã `.gitignore`), có tiến
trình trong widget. Cấu hình (`config.json5`): `stt_live`, `stt_final` (`cloud`|`local`),
`stt_priority` (`speed`|`accuracy`|`light`|`custom`), `stt_order`, `stt_models`, `stt_device`.

- **Chữ tạm (`stt_live`)**: khi ghi có VAD, mỗi vài trăm ms engine đầu tiên *đã sẵn sàng* trong
  plan phiên âm lại đoạn đã nói và phát event `partial {text}` (rỗng = xoá). ai-chat hiện chữ này mờ
  trong ô nhập. Không tải model giữa chừng: engine chưa có model bị bỏ qua.
- **Chữ cuối (`stt_final=local`)**: thử engine theo thứ tự plan; lỗi → engine kế tiếp; tới
  `openrouter` thì dùng cloud. Nếu plan KHÔNG có `openrouter` mà không engine nào dùng được → báo lỗi,
  không tự gửi audio lên cloud. Chỉ áp cho WAV 16kHz mono (file khác → cloud).
- Lệnh WS mới: `stt_list` → `stt_engines`; `stt_install {engine, model}` → `stt_install` (tiến trình/xong).

## Files

- `manifest.json` — `type=backend`, `mainEntry: main/index.js`, `defaultSettings: { apiKey, keyRef }`, size `460×680`.
- `widget.html` / `js/widget.js` / `css/widget.css` — UI **rút gọn**: chọn mic (+ số giây), model,
  ngôn ngữ, prompt, khối wake word, nút "▶ Phiên âm" (ghi mic rồi phiên âm), dòng trạng thái và ô kết
  quả (tích lũy transcript theo giờ — hiện cả khi wake word tự kích hoạt rồi phiên âm). Có nút "⚙" +
  overlay settings (chỉ API key) ngay trong widget (host bỏ nút gear per-widget — xem
  references/plugin-runtime-api.md 1b).
- `settings.html` / `js/settings.js` / `css/settings.css` — cùng field `apiKey` (dùng bởi Plugin Manager
  + cửa sổ pop-out); lưu xong tự gọi `restartBackend`.
- `locales/en.json5` / `locales/vi.json5` — chuỗi UI, namespace `widget.*`/`settings.*`.
- `main/index.ts` (+ `main/index.js` đã compile) — supervisor tiến trình Python + IPC.
- `python/` — backend STT bundle từ `stt`: `backend.py`, `stt_core.py`, `config.py`,
  `download_wakewords.py`, `requirements.txt`, `wakewords/Hey_Nova.onnx` (1 model wake word custom
  duy nhất — builtin đã tắt trong `stt_core.WAKEWORD_CHOICES`).

## Default settings

- `keyRef` — default: `""` (tên key trong Settings của Kazuo AI > API Keys; có giá trị thì dùng key đó thay cho `apiKey`).
- `apiKey` — default: `""` (OpenRouter API key; các cấu hình khác lưu trong `python/config.json5` do
  backend tự quản qua WebSocket, chỉnh trực tiếp trên widget).

## Hạn chế đã biết

- Cổng WebSocket cố định `8765` — không chạy song song với app `stt` gốc (trùng cổng).
- Ghi mic/wake word cần thư viện âm thanh gốc (`sounddevice`, `openwakeword`, `onnxruntime`) — phải
  `pip install` trước; thiếu sẽ báo lỗi trên widget.

## Test

Mở Kazuo AI → Plugin Manager — plugin xuất hiện tự động (host tự quét `plugins-library/`) → Install →
Enable. Sau khi sửa `main/index.ts`, biên dịch lại: `npx tsc -p tsconfig.plugins.json` (chạy ở project root).


---

# GameAnalytic / GameAnalytic
<!-- id: plugin-game-analytic source: plugins-library/game-analytic/README.md -->

# GameAnalytic

> Analyze any Play Store / App Store game via Scrapling: scrape metadata + all reviews, then let ai-chat's agent synthesize marketing & game-design docs to recreate the product

| | |
|---|---|
| Version | 1.0.1 |
| Category | AI & Agents |
| Permissions | process.spawn, shell.exec, filesystem.read, filesystem.write, network.remote |
| Depends on | ai-chat |

# GameAnalytic

Analyze any Play Store / App Store game from its URL: scrape metadata + user reviews with Scrapling,
then let the ai-chat agent synthesize Marketing & Game-Design docs detailed enough to recreate the
product. The plugin owns the **data** (scraping); the ai-chat agent owns the **intelligence** (analysis
+ writing the docs), so no LLM API key lives here.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`.
Full design notes: `.claude/features/game-analytic.md`.

## Requirements

Python + Scrapling on the machine running the app:

```
pip install "scrapling[fetchers]"
```

Set the interpreter in Settings → `pythonPath` if it isn't on PATH. The 🔧 button (Check deps) reports
what's missing.

## Files

- `manifest.json` — `mainEntry=main/index.js`; `defaultSettings`: `pythonPath`, `maxReviews`, `docLang`;
  `requirements.python=true`.
- `widget.html` / `js/widget.js` / `css/widget.css` — **multi-line URL box (one link per line)** +
  max-reviews + language. One line → single report; **2+ lines → cross-platform report** (scrape-multi →
  mini comparison + combined analysis, Export HTML → export-html-multi). Ctrl/⌘+Enter to run. Single-report
  preview: metadata, review stats, an **Analysis & estimates card** (investment score + signal, downloads/
  revenue, game age, version-regression warning, top features, tech score) and **Top evidence** (most-voted
  praise/complaint — replaces the raw review list). Optional analysis-docs textarea, Export HTML, Copy
  analysis prompt (builds 3 docs: Marketing + Game Design + **Investment**) / Copy raw JSON, 🔧 check-deps.
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay, used by
  the Plugin Manager screen and the pop-out window.
- `locales/en.json5` / `locales/vi.json5` — UI strings.
- `main/index.ts` (+ `main/index.js`) — IPC channels `plugin:game-analytic:{check-deps,scrape,scrape-multi,
  fetch-page,youtube,export-html,export-html-multi}` + `getMcpTools` exposing `check_deps`, `scrape_game(url)` (full),
  `analyze_game(url)` (compact), `export_html(url, docs?, lang?)`, plus **cross-platform**:
  `analyze_multi(urls[], maxReviews?)` (scrape + merge several URLs into one compact multi analysis),
  `export_html_multi(urls[], ...)` (open one combined report), and **research**: `fetch_page(url)` (fetch a
  homepage/guide/company page) + `youtube_research(query, withComments?, maxVideos?)` (top videos + **Shorts**
  + real comments via innertube; honest `commentsError` when a clip has none). Both export tools accept `homepageUrls[]` and
  `youtubeQueries[]` → the plugin fetches them and renders an "External sources" section (homepage cards +
  YouTube video lists).
- `main/analytics.ts` (+ `.js`) — in-plugin analytics engine (no LLM, no deps): `computeAnalytics(result)`
  returns a rough downloads & revenue estimate, rating health, sentiment, monetization signals + depth,
  technical health, top praises/complaints, **lifecycle** (age, last update, launch→update), **per-version
  score breakdown + regression flag**, **rating trend over time** (Play), **current-vs-lifetime rating**
  (App Store), **feature inventory** (each feature tagged by source — developer/description vs players —
  and by player sentiment: positive/negative mention counts → like-ratio → liked/mixed/disliked),
  **dev responsiveness**, **localization/reach**, **platform support**
  (OS + iPhone/iPad/iPod form-factor breakdown + tablet flag), an **investment
  scorecard** (5 sub-scores + overall + risks), and **most-voted praise/complaint quotes**. Also owns the
  shared NLP (`tokenize`, `EMOTION_LEXICON`, `STOPWORDS`, `buildWordClouds`). `scraper-engine.scrape()`
  attaches `result.analytics` automatically. Honest limits: no pre-launch dev time, no real
  retention/DAU/revenue — only labelled proxies.
- `main/html-report.ts` (+ `.js`) — self-contained report via a shared `pageShell` + sticky **table of
  contents** + hero-stats band, organised into **numbered, colour-accented sections** (1 Executive
  summary + verdict, 2 Platforms, 🌐 External sources when `research.pages` given, 3 Technical, 4 Business,
  5 Users & sentiment, 6 Features with source + like/dislike sentiment, 7 Docs). External sources renders
  homepage guide cards + YouTube video lists (with honest comment-error notes).
  `buildReportHtml(result, docs, lang, research?)` = single platform; `buildMultiReportHtml(multi, docs, lang, research?)` = **cross-platform**
  (section 1 adds a gap card, section 2 a per-store comparison table; sections 3–6 run on the pooled
  combined analysis). Content per section: investment scorecard, downloads/revenue estimate + disclaimer,
  lifecycle + version breakdown + rating trend, supported platforms (clickable store link + Apple/Google-Play
  icon, OS + iPhone/iPad/iPod form factors + tablet + languages + size), rating health, monetization,
  feature inventory, technical health + dev replies, praises/complaints (each risk has a title + a detailed
  numbers-backed reason), top-voted evidence quotes + two **word clouds** (player emotions + features talked
  about, hover for counts). Raw reviews are NOT listed. `test/build-report.test.js` checks it
  (`node test/build-report.test.js`).
- `main/scraper-engine.ts` (+ `.js`) — resolves the Python interpreter, runs the scraper scripts, and
  attaches `computeAnalytics(result)` to every scrape result.
- `main/scraper/` — Python (Scrapling): `check_deps.py`, `common.py`, `appstore.py`, `playstore.py`
  (metadata from ld+json + the richer `ds:5` blob → installs/exact-installs, version, release/updated
  dates, screenshots; index paths verified 07/2026, null on mismatch), `scrape.py`, **`fetchpage.py`**
  (fetch a web page → title/description/headings/text/links), **`youtube.py`** (search videos + Shorts +
  real comments), `requirements.txt`. Runnable standalone: `python scrape.py --url <store-url> --max-reviews 200`
  / `python fetchpage.py --url <homepage-url>` / `python youtube.py --query "<game> gameplay" --with-comments`.

## Default settings

- `pythonPath` — default: `""` (auto-detect `python`/`python3`)
- `maxReviews` — default: `2000` (Play Store fetches up to 2000 via internal RPC; App Store is capped at
  ~500 by Apple's review RSS)
- `docLang` — default: `"vi"`

## Usage

1. Open Kazuo AI → Plugin Manager → GameAnalytic appears automatically → Install → Enable.
2. In the widget, paste a game URL (e.g. `https://play.google.com/store/apps/details?id=...` or
   `https://apps.apple.com/us/app/.../id...`), pick language + max reviews, click Analyze.
3. To get the Marketing / Game-Design docs: attach this plugin to an ai-chat session (the agent calls
   `scrape_game` itself), or click **Copy analysis prompt** and paste it into ai-chat.
4. For a visual report: click **Export HTML** (optionally paste the AI docs first) to open a dashboard +
   docs report in your browser. The agent can also call `export_html` to do this in one step.

After editing any `main/*.ts`, recompile: `npx tsc -p tsconfig.plugins.json` (from the project root).


---

# Kazuo Router / Kazuo Router
<!-- id: plugin-kazuo-router source: plugins-library/kazuo-router/README.md -->

# Kazuo Router

> OpenAI-compatible local AI gateway: route requests across multiple providers with auto-fallback, key rotation, model mapping and usage stats.

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Permissions | network.remote, network.localhost |

# Kazuo Router

OpenAI-compatible local AI gateway. Runs an HTTP server on `127.0.0.1:<port>` that
speaks the OpenAI REST shape (`/v1/chat/completions`, `/v1/models`, …) and forwards
each request to one of several configured upstream providers — with auto-fallback,
round-robin key rotation, model mapping and per-provider usage stats. Point any
OpenAI-compatible tool (Cursor, Cline, SDKs, …) at `http://127.0.0.1:20128/v1`.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings` (server/apiKey/routing/providers/modelMap), `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — dashboard: server control, provider CRUD, routing + model map, live usage
  - has its own "⚙" button + settings overlay (server host/port/auth/autostart) built into widget.html/widget.js
- `settings.html` / `js/settings.js` / `css/settings.css` — same server fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*` / `server.*` / `providers.*` / `routing.*` / `stats.*` / `settings.*`
- `main/index.ts` (+ compiled `main/index.js`) — main-process entry: `activate`/`deactivate`, IPC handlers, key generation, auto-start
- `main/router-server.ts` (+ compiled `main/router-server.js`) — the OpenAI-compatible HTTP server + routing/fallback/rotation/stats
- `main/claude-cli-bridge.ts` (+ compiled `main/claude-cli-bridge.js`) — `claude-sub` provider: runs the real Claude Code CLI via claude-agent-sdk, keeps live sessions, and hooks client tool calls (park/resume) for OpenAI function-calling
- `main/openai-anthropic-bridge.ts` — `openai-anthropic` provider: the reverse direction, serving Anthropic Messages from an OpenAI upstream (upstream call, SSE consumption, tool-call reassembly, `<think>` splitting)
- `main/anthropic-to-openai.ts` — request translation (system/messages/tool_result fan-out/schema sanitising/tool allowlist/context budget)
- `main/anthropic-wire.ts` — Anthropic SSE emission with a content-block **index allocator** (thinking → text → tool_use)
- `main/sse-parse.ts` — incremental SSE parser (streaming `TextDecoder`, so multi-byte characters split across chunk boundaries survive)

## How it works

- The main process runs one `http.createServer` bound to `server.host:server.port`.
- Config is read **fresh from plugin settings on every request**, so provider edits in the widget apply live without a restart.
- Auth: when `server.requireApiKey` is on, clients must send `Authorization: Bearer <apiKey>` (or `x-api-key`, or `?key=`). The key is generated on first activation.
- Routing for `POST /v1/chat/completions` (and other `/v1/*`):
  1. Parse the requested `model`; resolve it through `modelMap` (alias → forced provider and/or real model).
  2. Order candidate providers: forced provider first, then providers that declare the model, then the rest — sorted by `priority` (`priority-fallback`) or rotated (`round-robin`).
  3. Try each candidate; pick one of its keys round-robin. On network error / 429 / 5xx (before any bytes are sent) fall through to the next candidate.
  4. Stream (SSE) or buffer the winning response back to the client; record request + token stats.
- `GET /v1/models` aggregates the models declared by enabled providers plus mapping aliases.
- `POST /v1/messages` (Anthropic Messages API) is accepted for `claude-sub` providers, so a Claude Code CLI (e.g. the ai-chat plugin) can point `ANTHROPIC_BASE_URL` at this router and use it as a hub — and for `openai-anthropic` providers, which translate it down to `/v1/chat/completions` on a local OpenAI-compatible server.
- Errors are emitted in the caller's dialect: requests under `/v1/messages` get the Anthropic
  `{type:'error', error:{…}}` envelope, everything else keeps the OpenAI shape. An Anthropic
  SDK handed the OpenAI shape reports an opaque parse failure instead of the real problem.

## Default settings

- `server` — `{ port: 20128, host: "127.0.0.1", autoStart: false, requireApiKey: true }`
- `apiKey` — local access key (auto-generated on first activation)
- `routing` — `{ strategy: "priority-fallback" }` (or `"round-robin"`)
- `providers` — `[]` (each: `{ id, name, type, baseUrl, keys[], models[], priority, enabled }`)
  - `type: "claude-sub"` runs through the **real Claude Code CLI** via `@anthropic-ai/claude-agent-sdk` (`main/claude-cli-bridge.ts`) — the SDK spawns `claude.exe`, which uses the machine's Claude subscription login (OAuth; `ANTHROPIC_BASE_URL`/`AUTH_TOKEN` are stripped from the spawned env so it uses the subscription directly and can't loop back), so it is **not rate-limited** like a forged OAuth request. No `baseUrl`/`keys` needed. Serves **both** protocols so it can be a hub for OpenAI clients AND Claude Code CLIs: `POST /v1/chat/completions` (OpenAI) and `POST /v1/messages` (Anthropic). Function-calling passthrough: the client's tools are registered as in-process MCP tools (the spawned CLI's own built-in tools are disabled so only the client's tools exist); when the model calls one, the bridge does not run it — it emits a `tool_calls`/`tool_use` response and PARKS the session, then resumes (matched by the minted id) once the client posts the tool result back. `models[]` is just the client-facing list; the CLI maps them to `sonnet`/`opus`/`haiku`.
  - `type: "openai-anthropic"` is the **mirror image of `claude-sub`**: it serves the Anthropic Messages API *from* an OpenAI-compatible upstream (Ollama, vLLM, llama.cpp), so the real Claude Code CLI — and therefore ai-chat's Agent mode — can drive a **local model with tools**. Extra fields: `ctxTokens` (upstream context window) and `allowTools[]` (see below). `POST /v1/messages` is translated; `POST /v1/chat/completions` falls through to the plain relay, so one provider entry serves both protocols. `/v1/messages/count_tokens` is answered with an estimate — returning 404 there breaks the CLI's context meter and `/compact`.
- `modelMap` — `[]` (each: `{ alias, providerId, model }`)

### Running a local model in Agent mode (`openai-anthropic`)

Two constraints dominate this path, both measured rather than assumed:

**1. Tool schemas do not fit.** Claude Code advertises ~24 tools totalling ~24k tokens of
JSON Schema; with its ~8k-token system prompt, a bare `hello` costs **~34k tokens** before
the user types anything. `allowTools[]` filters which tool definitions reach the model —
the CLI still offers all of them, the model is simply never shown the rest. The default
(`Bash, Read, Edit, Write`) brings the same request down to **~15k**. This lives in the
router, so **ai-chat needs no code changes**.

**2. Prompt prefixes must be byte-stable.** llama.cpp reuses the KV cache when the leading
bytes of a prompt are identical. Measured on a 27B Q4: a stable ~15k-token prefix prefills
in **15.0s cold and 1.1s warm**. The system prompt plus tool schemas are most of every
request, so any nondeterminism in translation — a timestamp, a re-sorted tool list — costs
~14 seconds on *every* turn. `anthropic-to-openai.ts` never sorts or injects varying data.

Also worth knowing:

- An over-long prompt returns **400**, never a truncated request. Ollama silently discards
  the front of an oversized prompt, which presents as a model that ignores its tools with
  nothing in any log to explain why.
- Client disconnect aborts the upstream generation. Without it an abandoned 3k-token reply
  pins the GPU for minutes and blocks the next request.
- Reasoning is read from `delta.reasoning` / `delta.reasoning_content`, falling back to
  scanning inline `<think>` tags. Note that Ollama sends reasoning chunks with an **empty
  `content` string** alongside — testing `content` for truthiness rather than length opens
  a text block before the thinking block and corrupts block order for the whole message.
- Tool arguments are parsed and repaired before emission, not relayed as upstream
  fragments: one malformed `partial_json` kills the CLI mid-turn, and truncated or
  trailing-comma JSON is routine from a quantised model.

Wiring it to ai-chat is configuration only — add an env profile under
`providers['claude-code'].envProfiles` pointing `ANTHROPIC_BASE_URL` at this router.
Set every model variable (`ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_{SONNET,OPUS,HAIKU}_MODEL`,
`ANTHROPIC_SMALL_FAST_MODEL`) to the same id, or the CLI will call a "small fast model" for
background work like conversation titles and that request will miss your provider.

## IPC channels (`plugin:kazuo-router:*`)

`start`, `stop`, `status`, `stats`, `clearStats`, `regenKey`, `testProvider` — all take the plugin id as the first arg (`ensureIsSelf`).

Events on `plugin:kazuo-router:event`: `{type:'status'|'request'|'stats', ...}`.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically → Install → Enable.
Add a provider (pick a preset, paste one or more API keys), press **Start**, then point a
client at `http://127.0.0.1:20128/v1` using the shown API key.

After editing `main/*.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# KChat / KChat
<!-- id: plugin-kchat source: plugins-library/kchat/README.md -->

# KChat

> ChatGPT-style chat on top of Claude Code: one flat session list, no workspace folder to pick, and a layout built for phones.

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Permissions | network.remote, shell.exec |

# KChat

## Mục đích

Chat với AI theo kiểu **ChatGPT web**: một danh sách phiên phẳng bên trái, khung trả lời ở giữa,
ô nhập dạng viên thuốc ở dưới. **Không có khái niệm thư mục làm việc**, không tool use, không hỏi
quyền — chỉ hỏi và đáp.

Bên dưới vẫn là **Claude Code CLI** chạy qua Claude Agent SDK, cấu hình điểm kết nối giống hệt
`ai-chat` (hồ sơ biến môi trường trỏ `ANTHROPIC_BASE_URL` vào endpoint bất kỳ). Giao diện
**co giãn được tới khổ điện thoại**.

Đây là plugin viết mới, chép có chọn lọc từ `ai-chat` — không phải bản gọt bớt. Lý do: `ai-chat` lấy
danh sách chat từ các phiên Claude Code trên đĩa **gom theo thư mục dự án**, nên bỏ thư mục đi thì
mất luôn cấu trúc danh sách; còn `js/widget.js` của nó dài 10.196 dòng với dock nhiều khung, tool
card, prompt quyền, đính file — gọt thì tốn công hơn viết lại.

## So với `ai-chat`

| | ai-chat | KChat |
|---|---|---|
| Danh sách chat | cây thư mục → phiên | danh sách phẳng |
| Thư mục làm việc | người dùng chọn | ghim cứng `~/.kazuo/kchat` |
| Công cụ (Read/Bash/Edit…) | có, kèm hỏi quyền | **không có** (khoá 4 lớp) — trừ 3 công cụ lập lịch của chính KChat |
| Lập lịch hỏi định kỳ | qua `cron-job` (action `agent`) | form ⏰ **và** nói thẳng trong chat, qua `cron-job` |
| Nhiều khung / tách cửa sổ | có (Golden Layout) | không |
| Điện thoại | không dùng được | ngăn kéo trượt, nút cỡ ngón tay |
| Cấu hình endpoint | hồ sơ biến môi trường | **dùng chung của ai-chat** |
| `js/widget.js` | 10.196 dòng | ~640 dòng |

## File liên quan

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `main/index.ts` — đăng ký IPC `plugin:kchat:*`, điều phối các chat đang mở
- `main/agent-session.ts` — bọc Agent SDK, **khoá toàn bộ công cụ**
- `main/sessions.ts` — thư mục ghim, danh sách/lịch sử/đổi tên/xoá phiên, dò CLI, tách mã model
- `main/schedules.ts` — dịch lịch dạng phẳng `When` ⇄ job của `cron-job`; chỉ đụng job của KChat
- `main/schedule-tools.ts` — 3 công cụ lập lịch cho model (MCP server chạy ngay trong tiến trình)
- `widget.html` / `css/widget.css` / `js/widget.js` — khung chat
- `settings.html` / `css/settings.css` / `js/settings.js` — trang cài đặt riêng
- `js/common.js` — helper dùng chung cho mọi trang
- `js/settings-form.js` — **form cài đặt viết một lần, cả hai trang cùng nạp**
- `locales/{en,vi}.json5` — mọi chuỗi hiển thị
- `test/` — kiểm thử jsdom (giao diện) + node (backend)

`package.json` chỉ khai `zod` (^4, bản Agent SDK yêu cầu) — thư viện mô tả tham số cho 3 công cụ lập
lịch. Agent SDK thì host cấp sẵn qua `ctx.modules.claudeAgent`. Thiếu `zod` thì KChat vẫn chat bình
thường, chỉ là model không tự đặt lịch được (form ⏰ vẫn chạy).

## Cách hoạt động

### Thư mục ghim làm cho danh sách phẳng

Agent SDK **bắt buộc** có một thư mục làm việc có thật, và xếp mỗi bản ghi phiên vào
`<config>/projects/<đường-dẫn-đã-làm-sạch>/`. `ai-chat` biến điều đó thành cây thư mục vì chat của nó
thực sự thuộc về dự án. KChat không có dự án nào, nên nó ghim **một** thư mục cho mọi cuộc trò
chuyện — thế là mọi bản ghi rơi vào cùng một rổ, và "liệt kê các cuộc trò chuyện" thành một danh sách
phẳng đúng kiểu ChatGPT, **không phải viết kho lưu trữ mới**.

Thư mục là `~/.kazuo/kchat` (của riêng plugin) để chat của KChat không hiện thành một workspace lạ
trỏ vào dự án thật của ai đó trong sidebar `ai-chat`.

### Khoá công cụ — bốn lớp

Một lớp là danh sách cấm chạy theo tên tool, mà tên tool thì thay đổi theo phiên bản. Nên
`agent-session.ts` dùng cả bốn:

1. `tools: []` — theo SDK, mảng tường minh là **toàn bộ** tập tool có sẵn, nên mảng rỗng là không có gì.
2. `disallowedTools: ['mcp__*']` — tool MCP không đi qua `tools`, phải có công tắc riêng.
3. `settingSources: []` — không nạp gì từ `~/.claude` của người dùng, nên hook/MCP server không lọt vào.
4. `canUseTool` từ chối mọi lời gọi, kèm lý do để model trả lời bằng lời thay vì cố gọi tiếp.

Vì vậy `permissionMode` để `'default'` — cờ `allowDangerouslySkipPermissions` mà `ai-chat` cần chỉ
tồn tại để tắt hộp thoại cho những tool KChat không có.

**Ngoại lệ duy nhất — công cụ lập lịch.** Khi chat bình thường, lớp 2 đổi từ "không có MCP nào" thành
"chỉ có server `kchat` của chính mình" (`mcpServers: { kchat }` + `allowedTools` đúng 3 tên), lớp 4
cho qua **đúng 3 tên** `mcp__kchat__{create,list,delete}_schedule` và vẫn từ chối mọi thứ khác
(Bash, tool của server khác…). Lớp 1 và 3 giữ nguyên. Lượt chạy **theo lịch** thì không có công cụ nào,
kể cả lập lịch — một lịch tự tạo được lịch là chỉ cách một câu lệnh để tự nhân bản.

### Lập lịch và thông báo

KChat **không có bộ lập lịch riêng** — dùng `cron-job`. Một lịch của KChat là một job `cron-job` có
action `{ type:'service', pluginId:'kchat', method:'runScheduled', payload }`; đến giờ `cron-job` gọi
`globalThis.__kazuoPluginServices.kchat.runScheduled(payload)`. Ngược lại, KChat tạo/liệt kê/xoá job
qua dịch vụ `__kazuoPluginServices['cron-job']` (vì kênh IPC chỉ gọi được từ giao diện, còn công cụ của
model chạy ở tiến trình nền). Chưa cài/bật `cron-job` → bảng ⏰ báo rõ, công cụ trả lỗi để model nói lại
với người dùng.

- **Hai cách tạo**: form trong bảng ⏰ (thanh trên cùng), hoặc nói trong chat ("9h sáng mai nhắc tôi…").
  Cả hai dùng chung một dạng phẳng `When`: `once` (`at` giờ địa phương `YYYY-MM-DDTHH:mm`), `daily`
  (`time`), `weekly` (`time` + `days` 0=CN…6=T7), `interval` (`everyMinutes` ≥ 5), `cron` (`expr` 5 trường).
  Model điền dạng này đúng hơn nhiều so với kiểu gốc của `cron-job` (epoch ms lồng trong object).
- **Model biết giờ hiện tại**: system prompt có giờ địa phương kèm múi giờ lúc khởi chạy; mỗi kết quả
  công cụ cũng trả `now`. Giờ đã qua bị từ chối kèm giờ hiện tại để model tự sửa.
- **Câu trả lời vào đúng cuộc trò chuyện** đã tạo lịch. Lịch tạo trong chat chưa bắt đầu (chưa có
  session) sẽ tạo một chat riêng mang tên lịch ở lần chạy đầu. Nối lịch → chat qua `scheduleThreads`
  (khoá `payload.key`), không sửa job trong `cron-job`, để khỏi đua với một lượt đang chạy.
- **Không chen ngang**: chat đó đang trả lời thì lượt theo lịch bị bỏ qua và ghi lỗi (hai tiến trình
  ghi một transcript sẽ làm rẽ nhánh lịch sử). Chat đang mở nhưng rảnh thì tiến trình CLI của nó bị
  huỷ, tin nhắn sau sẽ đọc lại lịch sử từ đĩa.
- **Thông báo**: trên máy tính là thông báo Windows (bấm vào → mở đúng chat, đưa cửa sổ KChat lên nếu
  đang tách riêng). Trên web dashboard (điện thoại) là toast của app qua `plugin:notification:show`
  kèm `activate` → `plugin:kchat:reveal-session`. Mỗi nền tảng một loại, để không báo hai lần.
- **Chưa đọc**: `sessionMeta[id].unread`; chấm xanh + chữ đậm trong danh sách, mở chat là xoá. Chat
  đang mở luôn coi là đã đọc (tránh một lượt làm mới danh sách trả lời muộn vẽ lại chấm).
- `runScheduled` **ném lỗi** khi thất bại để `cron-job` ghi lượt chạy là lỗi (nó coi mọi giá trị trả về
  là thành công). Tối đa 10 phút một lượt.

### Điểm kết nối — dùng chung với `ai-chat`

KChat **không bắt khai lại** những gì `ai-chat` đã có. Host cho phép một plugin đọc cài đặt của plugin
khác (`ctx.modules.pluginControl.getPluginSettingsFor`), nên KChat lấy thẳng danh sách điểm kết nối
của `ai-chat` và dùng nguyên. Bản của riêng KChat chỉ là **phương án dự phòng** cho máy không có
`ai-chat`, hoặc `ai-chat` chưa cấu hình gì.

Ba điểm cần nhớ:

- **Chỉ đọc, cố ý.** Hồ sơ của `ai-chat` mang các trường KChat không biết tới (`modelType`,
  `routerType`…). Ghi ngược một object hình dạng KChat sẽ **âm thầm xoá** chúng và làm hỏng giao diện
  của `ai-chat`. Nên màn Cài đặt của KChat hiện chúng dạng tóm tắt, sửa thì sửa bên `ai-chat`.
- **Token không bao giờ ra khỏi tiến trình nền.** Kênh `endpoints` chỉ trả `{id, name, models,
  configured}` — giao diện không cần `env`, nên không nhận `env`.
- **Một mục `default` trống không tính là đã cấu hình.** Đó là thứ `ai-chat` mặc định có sẵn; coi nó
  là cấu hình sẽ che mất danh sách mà chính KChat đang giữ.

Một "điểm kết nối" là một nhóm biến môi trường đưa cho CLI khi khởi chạy, gộp **đè lên** toàn bộ
`process.env` (binary vẫn cần `PATH`, `HOME`…). Thường là:

```
ANTHROPIC_BASE_URL   = http://127.0.0.1:20128
ANTHROPIC_AUTH_TOKEN = sk-...
```

- `CLAUDE_CONFIG_DIR` **luôn bị ghim** bởi plugin, không bao giờ thừa kế. Lý do: mọi plugin backend
  dùng chung một tiến trình Electron, và `ai-chat` có đổi tạm biến này khi quét phiên ở config dir
  khác — đọc đúng lúc đó là KChat sẽ khởi chạy CLI nhầm cài đặt.
- Nút "Lấy" đọc `/v1/models` **qua backend**, vì trang chạy trên origin `app://` bảo mật còn endpoint
  cục bộ là `http://` — Chromium chặn thẳng gọi từ renderer. Nhận cả hai dạng trả về: mảng trần hoặc
  `{data:[…]}`.
- Độ dài ngữ cảnh là **hậu tố riêng** (`[1m]`), giữ tách khỏi mã model và chỉ ghép đúng một lần lúc
  khởi chạy. Lưu dạng đã ghép sẽ làm chết các phiên cũ vào ngày endpoint thôi nhận `sonnet[1m]`.

### Cài đặt không bị chép hai lần

Host đã bỏ nút ⚙ ở góc widget, nên plugin phải tự mở được Cài đặt từ trong `widget.html`; nhưng
`settings.html` vẫn cần tồn tại cho Plugin Manager và cửa sổ pop-out. `ai-chat` giải quyết bằng cách
chép nguyên form sang hai nơi rồi lệch nhau dần.

KChat để toàn bộ form trong `js/settings-form.js`, và **cả hai trang cùng nạp file đó**. Hai trang vẫn
là hai sandbox riêng — mỗi trang có bản sao của mình — nhưng chỉ có một bản mã nguồn. Ràng buộc duy
nhất: id phần tử trong `widget.html` và `settings.html` phải trùng nhau.

### Giao diện điện thoại

- Có thẻ `viewport` (`ai-chat` không có, nên không dùng được trên điện thoại).
- `100dvh` chứ không phải `100vh` — trên điện thoại thanh địa chỉ tính vào `vh` và che mất ô nhập.
- Dưới 720px: danh sách phiên thành ngăn kéo trượt + lớp che, nút to lên 38px, chữ trong ô nhập 16px
  (dưới ngưỡng này iOS Safari tự phóng to trang khi bấm vào).
- `env(safe-area-inset-bottom)` để ô nhập không nằm dưới vạch home.
- Enter gửi tin trên máy tính; trên màn cảm ứng Enter xuống dòng (không có Shift để giữ).

## IPC channels (`plugin:kchat:`)

Mọi channel nhận plugin id làm tham số đầu để kiểm tra.

`state`, `endpoints`, `sessions`, `session-history` (sessionId), `session-title` (sessionId),
`session-rename` (sessionId, title), `session-delete` (sessionId), `open` (chatId, cfg),
`connect` (chatId), `close` (chatId), `send` (chatId, text), `interrupt` (chatId),
`set-model` (chatId, model, contextSuffix), `set-env-profile` (chatId, envProfileId),
`fetch-models` (url, headers), `ping`, `schedules` (sessionId) → `{ available, items }`,
`schedule-create` (sessionId, `{ prompt, name?, when }`), `schedule-delete` (id),
`schedule-toggle` (id, enabled), `mark-read` (sessionId).

`reveal-session` (`{ sessionId }`) là ngoại lệ **không** kiểm tra plugin id: toast của host gọi nó khi
người dùng bấm, và nó chỉ phát sự kiện `reveal_session` cho widget mở chat đó.

Sự kiện đi ra trên **một** channel `plugin:kchat:event`, mỗi sự kiện mang `chatId`: `connecting`,
`connected`, `session_started`, `models`, `stream_text`, `stream_thinking`, `assistant`, `tool_use`,
`context_window`, `result`, `done`, `stopped`, `error`. Ba sự kiện **không** gắn chat nào, mọi widget
đều xử lý: `scheduled_done` (`sessionId, title, ok, body`), `schedules_changed`, `reveal_session`.

Một lượt có gọi công cụ gồm **nhiều** sự kiện `assistant` (lời → gọi công cụ → lời tiếp). Widget cộng
dồn các phần (`base` + `live`), không để phần sau đè phần trước.

`connect` tách khỏi `open` để bấm xem một cuộc trò chuyện **không tốn gì** — tiến trình CLI chỉ khởi
động khi người dùng đặt con trỏ vào ô nhập hoặc bấm gửi.

`open` trả về `{ model, contextSuffix, envProfileId }` đã phân giải chứ không phải `true`: một cuộc
trò chuyện mở lại chạy bằng đúng model/điểm kết nối **nó** từng dùng, nên các ô chọn trên thanh trên
cùng phải lấy theo giá trị này.

## Giao diện

- **Thanh trên cùng**: ☰ (mở danh sách, chỉ ở khổ hẹp) · tiêu đề · **ô chọn điểm kết nối** · ô chọn
  model · **nút ⏰ lịch hẹn** · **nút bánh răng**. Hai ô chọn áp cho *cuộc trò chuyện đang mở*; đổi ô nào thì tiến trình CLI
  bị huỷ và tin nhắn kế tiếp mới khởi động lại (CLI chỉ đọc chúng lúc khởi chạy).
- **Lối vào Cài đặt có ở hai chỗ**: nút bánh răng trên thanh trên cùng và mục ở chân thanh bên. Phải
  có cái thứ nhất, vì bề rộng mặc định của widget (420px) **nằm dưới** ngưỡng ngăn kéo (720px) — thanh
  bên mặc định đã đóng, nên lối vào chỉ nằm trong đó là không nhìn thấy được.
- Dưới 720px: tiêu đề nhường chỗ cho hai ô chọn và nút bánh răng.

## Cài đặt mặc định

- `providers['claude-code'].envProfiles` — `[{ id:'default', name:'Default', env:{} }]`
  (chỉ dùng khi không mượn được của `ai-chat`)
- `contextLevels` — `[]` (mỗi dòng một mức, vd `1m`; cũng mượn theo điểm kết nối)
- `sessionDefaults` — `{ model:'', contextSuffix:'', envProfileId:'default' }`
- `claudeCli` — `{ binaryPath:'' }` (thứ tự dò: `KAZUO_CLAUDE_CLI` → ô này → `~/.local/bin/claude`)
- `systemPrompt` — `''`
- `thinkingDisplay` — `'collapsed'` (`'hidden'` **tắt luôn** phần suy nghĩ ở model, không chỉ ẩn đi)
- `sessionMeta` — model/endpoint đã dùng của từng phiên, để mở lại đúng như cũ; cờ `unread`
- `scheduleThreads` — `{ [payload.key]: sessionId }`, lịch nào trả lời vào chat nào

## Kiểm thử

```bash
npx tsc -p tsconfig.plugins.json          # phải chạy lại sau khi sửa main/*.ts
node --test plugins-library/kchat/test/widget.test.js            # 23 bài, jsdom
node --test plugins-library/kchat/test/widget-schedules.test.js  # 14 bài, jsdom — bảng ⏰, chưa đọc, toast
node --test plugins-library/kchat/test/backend.test.js           # 27 bài
node --test plugins-library/kchat/test/schedules.test.js         # 11 bài — When, khoá công cụ, runScheduled
```

Truyền **từng file**; `node --test plugins-library/kchat/test/` (thư mục) không chạy được trên Node 24.

`test/widget-harness.js` nạp **chính** `widget.html` và các script thật vào jsdom với một bridge giả,
nên bài kiểm tra soi đúng DOM mà widget dựng ra chứ không phải một bản dựng lại.

## Chạy thử

Lần đầu: mở Kazuo AI → Plugin Manager → plugin tự xuất hiện → Install → Enable.
Nếu chưa có Claude CLI, màn Cài đặt sẽ báo và cho điền đường dẫn.

### Đẩy bản sửa vào app đang chạy

App nạp plugin từ `<userData>/plugins/kchat/`, **không phải** từ `plugins-library/`. Script nạp lại
của dự án chỉ đồng bộ `main/`, nên phần giao diện phải tự chép:

```bash
# 1. chép giao diện (script reload KHÔNG làm bước này)
cp -r js css locales "$APPDATA/kazuo-ai/plugins/kchat/"
cp widget.html settings.html manifest.json icon.svg "$APPDATA/kazuo-ai/plugins/kchat/"

# 2. biên dịch main/, chép nó, rồi tắt/bật plugin
node scripts/session-lock/reload-plugin.js kchat    # chạy từ thư mục gốc dự án

# 3. nạp lại trang widget — bước 2 chỉ khởi động lại backend
```

Quên bước 1 hoặc 3 thì giao diện cũ vẫn hiện và bản sửa trông như không ăn.

**Cảnh báo:** `reload-plugin.js` chạy `tsc` cho **toàn bộ** thư viện plugin, nên nó sinh lại `main/*.js`
của mọi plugin có `.ts` đang sửa dở — làm bẩn `git status` của người khác. Script có in ra danh sách
đó, đọc kỹ.


---

# n8n / n8n
<!-- id: plugin-n8n source: plugins-library/n8n/README.md -->

# n8n

> Công cụ quản lý và thực thi n8n workflow, điều khiển qua SSH/local-exec

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Permissions | shell.exec, network.remote |

# n8n

Công cụ quản lý và thực thi n8n workflow, điều khiển qua SSH/local-exec

**Type:** `exec` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces (REQUIRED, same key set in both)

## Default settings

- `mode` — default: `"local"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

## Accessibility + i18n

This plugin must keep the i18n + accessibility contract in `.claude/skills/kazuo-create-plugin/references/a11y-i18n-checklist.md`: both locale files present with the same keys, no hardcoded user-visible strings (aria-label included), a name on every icon-only button, a <label for> on every field, keyboard reachable controls with a visible focus ring, and a live region for status text. The scaffold ships all of that — keep it when you extend the UI.

Fill in host/port/username/password in Settings before using SSH mode.


---

# 9Router / 9Router
<!-- id: plugin-nine-router source: plugins-library/nine-router/README.md -->

# 9Router

> Launch and control the real 9Router AI gateway (multi-provider, key rotation, auto-fallback) and open its local web dashboard.

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Permissions | shell.exec |

# 9Router

Launch and control the real **9Router** AI gateway from Kazuo AI, and open its web dashboard.

**Type:** `backend` — spawns the real `9router` CLI as a child process in the Electron main process.
**Platforms:** Windows, macOS, Linux (spawns through the system shell; Stop kills the whole process tree).

## What it does

This plugin does NOT route requests itself. It runs the real **9router** (npm package `9router`) on
your machine and opens its built-in web dashboard. Providers, API keys, fallback rules and the local
Bearer token are all managed in 9router's own dashboard (data stored under `~/.9router`).

- Start / Stop the `9router` server.
- Open its dashboard at `http://localhost:<port>` (default `20128`).
- Live log tail + status in the widget.

Point your OpenAI/Claude-compatible tools (Cursor, Cline, Codex, Claude Code…) at
`http://localhost:20128/v1` and copy the API key shown in the dashboard.

## Requirements

Node.js ≥ 18 available on PATH (the default command uses `npx`). Or set a custom launch command in
Settings (e.g. a global install, a pinned version, or a Docker command) — use `{port}` as a placeholder.

## Files

- `manifest.json` — metadata, `platforms`, `defaultSettings`, `permissions` (`shell.exec`)
- `main/index.ts` (+ compiled `main/index.js`) — IPC wiring + auto-start
- `main/runner.ts` (+ compiled `.js`) — spawns/stops the `9router` process, opens the dashboard
- `widget.html` / `js/widget.js` / `css/widget.css` — control panel (status, Start/Stop/Open, log, settings overlay)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields for the Plugin Manager / pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces (same key set in both)

## Default settings

- `port` — `20128`
- `command` — `npx -y 9router --port {port} --host 127.0.0.1 --no-browser --skip-update` (`{port}` is replaced at launch)
- `autoStart` — `false`
- `openOnStart` — `true` (open the dashboard right after Start)

## Build

After editing `main/*.ts`, recompile before testing (from the project root):

```
npx tsc -p tsconfig.plugins.json
```

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically → Install → Enable → open the
widget → Start. The first start may take a moment while `npx` fetches 9router. Then click
**Open dashboard** and configure your providers there.


---

# Orchestrator / Orchestrator
<!-- id: plugin-orchestrator source: plugins-library/orchestrator/README.md -->

# Orchestrator

> Dispatch board: chat with the orchestrating agent, watch which devices are online, and follow the tasks it starts.

| | |
|---|---|
| Version | 1.0.0 |
| Category | AI & Agents |
| Depends on | ai-chat |

# Orchestrator

Ban dieu khien giao viec: chat voi agent dieu phoi, xem thiet bi online va task dang chay — trong MOT khung.

**Type:** `ui + main` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

Plugin giữ nguyên phần UI tổng hợp ai-chat / device-manager / task-manager và bổ sung backend lưu task bền vững. Backend hiện có 4 lát cắt: (1) state machine + SQLite store + IPC, (2) resource lease (`resource_leases`) + cổng năng lực `withForegroundInput` + reconcile khi khởi động + drain có thời hạn khi tắt, (3) sổ cái tác động ngoài (`side_effect_ledger`) để khởi động lại không làm lại commit/push/tin nhắn đã xảy ra, (4) chọn provider/model (mặc định chung + ghi đè theo task, từ chối chứ không tự thay thế). Sau đó bổ sung tiếp: giao việc thật (`executor-adapter.ts`), `attest()` (kiểm chứng OS process), bằng chứng kiểm chứng (`recipe_runs`), Telegram + phê duyệt có ràng buộc nội dung, Git broker, chỉ mục tài liệu, cách ly output, và **vòng tự giao việc** (`runSchedulerOnce` — việc đã duyệt tự chạy khi môi trường rảnh; mặc định TẮT). Chi tiết kiến trúc: `.claude/features/orchestrator-plugin.md`.

## Files

- `manifest.json` — metadata, `mainEntry: "main/index.js"`, `defaultSettings` (`{ agentId: '', cwd: '' }`), `defaultWidgetConfig`
  (860x620), `dependencies: ["ai-chat"]`.
- `main/` — state machine, SQLite task/event store, 10 migration (`tasks`/`task_events`, `resource_leases`,
  `side_effect_ledger`, run target, `attempts`, `recipe_runs`, `approvals`+Telegram, lời worker, `documents`
  +`quarantined_artifacts`, lý do trên sự kiện `task_events.note`), lease manager (`acquireLease`/`renewLease`/`releaseLease`/`withForegroundInput`),
  sổ cái tác động ngoài (`beginSideEffect`/`settleSideEffect`/`getSideEffect`), `git-broker.ts` (worktree riêng cho từng task ở **mỗi** repo của môi trường, danh sách lệnh git được phép, cổng kiểm read-only tách riêng (`checkIntegrable`), merge có duyệt, không push, và xoá worktree theo thứ tự lồng-trước-ngoài-sau (`removeWorktrees`)),
  `approvals.ts` + `telegram.ts` (phê duyệt có ràng buộc nội dung, Telegram **khoá mặc định**),
  `token-store.ts` (**token bot được mã hoá bằng `safeStorage`/DPAPI, KHÔNG nằm trong settings** — không mã
  hoá được thì không lưu; giao diện chỉ thấy trạng thái, không bao giờ thấy giá trị),
  `verify-runner.ts` + bảng `recipe_runs` (coordinator tự chạy lệnh kiểm chứng của môi trường và quan sát mã thoát),
  `environment-identity.ts` + `attest()` (coordinator tự hỏi OS xem Unity Editor có còn là cái đã claim không, fail closed),
  `document-index.ts` (chỉ **gắn cờ** tài liệu trùng tên khác nội dung / lâu không đổi — không bao giờ sửa gì),
  `artifact-cleanup.ts` (**cách ly, không có lệnh xoá nào**; chứng minh bằng danh tính tệp `bigint` rằng đã
  chuyển đúng tệp; một lượt quét mỗi thư mục),
  `executor-adapter.ts` (giao việc thật:
  chỉ task `ready`, môi trường theo id từ settings, lease trên thư mục, không tự đổi provider/model), reconcile khi
  `activate()` và drain có thời hạn khi `deactivate()`, IPC theo hằng `CHANNELS` được export, và 9 công cụ MCP cho
  điều phối viên (`list_environments`/`create_task`/`list_tasks`/`task_detail`/`dispatch_task`/
  `list_unity_dialogs`/`click_unity_dialog`/`scan_documents`/`preview_cleanup` — **không có công cụ nào duyệt được phạm vi, và không công cụ nào chuyển
  được tệp**: dọn thật và khôi phục chỉ gọi được từ widget).
- `test/` — 418 test cho state machine, transaction/rollback/crash/lifecycle/IPC, lease/generation/reconcile/drain,
  sổ cái tác động ngoài, bảng `attempts`, giao việc thật, vòng tự giao việc, kho token (mã hoá tại chỗ),
  truy vết, chỉ mục tài liệu, cách ly/khôi phục output và packaging; chạy bằng `npm test`.
- `widget.html` — nạp chat embed + Golden Layout của ai-chat qua `app://./plugins/ai-chat/...`;
  layout: head (title + select agent + ↻ + ＋ chat mới + ⊞ khôi phục bố cục + ⚙) → `#dockRoot` + `#dockStaging`
  (5 vùng Thiết bị / Task / Hàng việc / Chat / Tài liệu & Dọn dẹp, dock được, kéo thả + đổi kích thước,
  bố cục tự lưu). Panel Tài liệu & Dọn dẹp chung ngăn với Chat vì nó liệt kê đường dẫn đầy đủ — thêm
  một vùng làm bố cục đã lưu cũ bị dựng lại **một lần** (xem `isValidDockLayout`).
- `js/widget.js` — `loadRoles()`, `mountChat(agentId)` (KazuoChatEmbed), `loadDevices()`, `loadTasks()`,
  `loadJobs()` + panel Hàng việc (tạo việc, duyệt, giao — mỗi nút là một sự kiện chuyển trạng thái có thật),
  panel Tài liệu & Dọn dẹp (`runDocsScan`/`runDocsPreview`/`docsRun`/`loadQuarantine`/`restoreQuarantined`)
  — **không** nằm trong `refreshAll()`/poll vì quét và xem trước đều đi hết thư mục trên đĩa; nút dọn chỉ
  bật khi đang có bản xem trước của đúng môi trường, và phải bấm hai lần với số tệp + dung lượng hiện
  trên nhãn nút,
  `refreshAll()` + poll 5s, refresh ngay khi agent kết thúc lượt (`chat.on('turn-end')`).
- `css/widget.css` — layout 2 cột (side 250px + chat), chấm online, viền trái task theo status.
- `locales/en.json5` / `locales/vi.json5` — UI strings, namespace `widget.*` / `status.*`.

`settings.html` + `js/settings.js` chỉ có cwd + nhịp làm mới; agent điều phối, provider và model mặc định
đều chọn ngay trong widget (dropdown + ⚙) và lưu vào settings của plugin.

## Default settings

- `agentId` — default: `''` (rỗng → tự chọn agent khớp `manager|nova|orchestr`, không có thì agent đầu)
- `cwd` — default: `''` (rỗng → thư mục mặc định của phiên chat)
- `defaultProviderId` — default: `''` — hồ sơ môi trường ai-chat dùng chung cho mọi task chưa tự chọn
- `defaultModel` — default: `''` — model dùng chung cho mọi task chưa tự chọn
- `unityProjectRoots` — default: `[]` — thư mục gốc các môi trường Unity được phép bấm hộp thoại.
  **Rỗng = không cho phép gì**, tính năng tắt.
- `docStaleAfterDays` — default: `90` — bao lâu không đổi nội dung thì tài liệu bị gắn cờ "lâu không xem lại".
  Đây là **giá trị khởi điểm để người dùng chỉnh**, không phải con số đo được từ ba repo này.
- `outputExpireAfterDays` — default: `30` — output cũ hơn bấy nhiêu ngày thì được coi là hết hạn. Cũng là giá
  trị khởi điểm, chưa đo.
- `preflightRamPerEnvironmentGb` — default: `8` — RAM cần cho mỗi môi trường sắp khởi (đo thật lúc rảnh:
  5,3–5,7 GB/môi trường, cộng dư cho lúc Unity nạp/biên dịch).
- `preflightRamReserveGb` — default: `16` — RAM luôn chừa cho Windows và app khác.
- `preflightMinFreeDiskGb` — default: `20` — ổ chứa mỗi môi trường phải còn trống ít nhất bấy nhiêu. Giá trị
  khởi điểm, **chưa đo**.

Ba ngưỡng trên dùng cho công cụ `check_capacity` (xem feature doc): hỏi TRƯỚC khi mở Unity/game, thiếu thì
từ chối **tất cả** môi trường được hỏi.

Mỗi môi trường trong `environments` có thêm ba trường, **cả ba đều trống mặc định**:

- `docs` — danh sách đường dẫn (tương đối với `cwd`) mà chỉ mục tài liệu được phép nhìn. Rỗng = không quét gì.
  Là danh sách chọn lọc chứ không phải quét cả dự án: thứ không khai ở đây thì **không thể** thành phát hiện.
- `outputRoot` — thư mục chứa output của môi trường, nơi **duy nhất** lệnh dọn được phép chuyển tệp. Rỗng =
  không dọn được. **Không bao giờ suy ra từ `cwd`** — suy ra là chĩa một lượt chuyển tệp vào cả dự án ngay lần
  đầu có người thử. **Phải là đường dẫn tuyệt đối**, khác `docs` ở ngay trên: `docs` được giải quyết tương đối
  với `cwd`, còn `outputRoot` đi thẳng vào `path.resolve()` nên đường dẫn tương đối sẽ trỏ theo thư mục làm
  việc của Electron. Cũng không có gì bắt nó phải nằm trong `cwd`.
- `nestedRepo` — `{ path, integrationBranch }`: repo git **thứ hai** nằm bên trong `cwd` mà repo ngoài
  gitignore chứ không theo dõi (ví dụ: repo dự án gitignore thư mục `engine/`, còn `engine/` là
  clone của một repo khác). `path` tương đối với `cwd`, được **resolve rồi mới kiểm** nên `..` không thoát ra
  ngoài được. Khai sai làm **cả môi trường bị bỏ** — chạy với một nửa Git còn tệ hơn không chạy. Một object,
  không phải mảng: có đúng một repo lồng.

- `game` — `{ exe, args, profile }`: game của môi trường cho `login_game` / nút "Đăng nhập game". `exe`
  (vd `Bin/Game.exe`) và `profile` (vd `tools/profiles/dev01.json`) tương đối với `cwd` và phải
  nằm trong `cwd`. Game chưa chạy thì được mở (sau `check_capacity`), rồi đăng nhập bằng script tự động
  của dự án. Không khai = môi trường đó không đăng nhập game được.

- `unity` — `{ exe, project, mcpUrl }`: Unity Editor cho `restart_unity` / nút "Khởi động lại Unity". `exe`
  tuyệt đối tới `Unity.exe`, `project` (vd `engine`) tương đối và nằm trong `cwd`, `mcpUrl` là
  `http://localhost:<cổng>/`. Từ chối (không đóng gì) khi có task đang chạy, scene chưa lưu, hoặc Unity Hub tắt.

Bật `integrationBranch` + `nestedRepo` cho ba môi trường thử nghiệm tốn khoảng **1,1 GB đĩa mỗi task**
(≈ 780 MB repo ngoài + ≈ 350 MB repo lồng); worktree dùng chung kho object nên **không** copy `.git`
(610 MB + 6,3 GB). Submodule `StreamingAssets` **không** được init (7,3 GB mỗi task), nên worktree **không mở
được bằng Unity Editor như một project hoàn chỉnh** — nó là nơi sửa mã, không phải nơi build.

## Kênh IPC sử dụng (của plugin khác, đều mở)

- `plugin:ai-chat:list-agents` — danh sách agent-role để chọn agent điều phối
- `plugin:device-manager:fleet-devices` — thiết bị của tài khoản + trạng thái online
- `plugin:task-manager:list` — task (agent-role tự log mỗi lần `dispatch_agent`)

Thiếu device-manager/task-manager → 2 pane hiện dòng gợi ý bật plugin, phần chat vẫn dùng bình thường.

## Test

```bash
cd plugins-library/orchestrator
npm test
```

Kết quả nghiệm thu hiện tại: 126 test pass. Từ gốc repo, chạy thêm `npx tsc -p tsconfig.plugins.json --noEmit`.

Không reload/toggle `ai-chat` để kiểm tra backend Orchestrator. Chỉ triển khai runtime sau khi đã đồng bộ plugin theo quy trình host và có quyền bảo trì phù hợp.


---

# Backup Manager / Backup Manager
<!-- id: plugin-backup-manager source: plugins-library/backup-manager/README.md -->

# Backup Manager

> Quan ly danh muc backup cua cac plugin, luu qua file-storage.

| | |
|---|---|
| Version | 1.0.1 |
| Category | Productivity |
| Permissions | network.localhost |
| Depends on | file-storage, ai-chat |

# Backup Manager

Quản lý danh mục backup của các plugin, lưu blob **qua plugin `file-storage`**. Backup
là kho lưu trữ / nguồn knowledge — KHÔNG restore ngược vào máy đang chạy.

**Type:** `backend`

## Cách hoạt động

- Backup 1 plugin = snapshot **settings** của nó (đọc qua `ctx.modules.pluginControl.getPluginSettingsFor`)
  + tùy chọn **extra files** trên đĩa do plugin nguồn cung cấp qua registry global
  `__kazuoPluginServices` (xem `references/plugin-runtime-api.md` mục 4d).
- Blob JSON: `{ formatVersion:1, sourcePluginId, createdAt, settings, extraFiles:[{relPath, contentBase64}] }`
  — base64, KHÔNG nén (MVP).
- Blob lưu **bắt buộc** qua file-storage: đọc `port`+`apiKey` từ settings file-storage (cross-plugin)
  rồi POST/GET/DELETE `http://127.0.0.1:<port>/files`. file-storage tắt/thiếu key → báo lỗi (fail-closed).
- **Retention**: sau mỗi backup giữ `maxBackupsPerPlugin` bản mới nhất mỗi `sourcePluginId` (mặc định 10),
  xóa bản cũ (cả blob + catalog).
- **Headless**: `globalThis.__kazuoPluginServices['backup-manager'].runBackup(spec)` = cùng lõi với IPC
  `create`, để cron-job (action `service`) chạy backup theo lịch mà không cần mở widget.

## IPC channels (`plugin:backup-manager:*`) — KHÔNG self-scope

Arg đầu luôn là `callerPluginId` (attribution). Plugin khác (ai-chat) gọi được.

| Channel | Args | Mô tả |
|---|---|---|
| `list` | `(caller, filter?{sourcePluginId})` | Danh mục backup (lọc theo plugin nguồn nếu có), mới nhất trước |
| `create` | `(caller, spec)` | Tạo backup ngay. `spec = { sourcePluginId, title?, desc?, includeSettings?, extraProvider?{pluginId,method} }` |
| `get` | `(caller, id)` | 1 entry hoặc null |
| `update` | `(caller, id, {title?,desc?})` | Sửa metadata |
| `delete` | `(caller, id)` | Xóa entry + blob trên file-storage |
| `get-content` | `(caller, id)` | Tải blob (object JSON) để dùng làm knowledge |

Broadcast `plugin:backup-manager:event` `{type:'backups-changed'}` sau mọi thay đổi.

## Default settings

- `backups` — default: `[]`
- `maxBackupsPerPlugin` — default: `10`

## Dependencies

`file-storage` (bắt buộc bật để lưu blob). Khai báo trong `manifest.json.dependencies` (chỉ kiểm ở cài đặt).

## Files

- `main/index.ts` — activate/deactivate, IPC CRUD, `performBackup`, registry global service
- `main/storage.ts` — upload/download/delete blob qua HTTP file-storage
- `widget.html` / `js/widget.js` / `css/widget.css` — danh mục backup (xem/sửa/xóa/xem nội dung)
- `settings.html` / `js/settings.js` — chỉnh `maxBackupsPerPlugin`
- `locales/en.json5` / `locales/vi.json5`

## Test

Plugin Manager → Install → Enable (cần bật cả `file-storage`). Sau khi sửa `main/*.ts`:
`npx tsc -p tsconfig.plugins.json` (từ project root).


---

# Clock / Clock
<!-- id: plugin-clock source: plugins-library/clock/README.md -->

# Clock

> Digital clock overlay

| | |
|---|---|
| Version | 1.0.1 |
| Category | Productivity |
| Depends on | ai-chat |

# Clock

Digital clock overlay

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Shows the time, optionally with seconds and the full date.
- The date follows the app language (Settings > General > Language) rather than a fixed locale.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `format` — default: `"24h"`
- `showSeconds` — default: `true`
- `showDate` — default: `true`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cron Job / Cron Job
<!-- id: plugin-cron-job source: plugins-library/cron-job/README.md -->

# Cron Job

> Schedule jobs; fire events for other plugins (IPC) or run AI Chat agents on a schedule.

| | |
|---|---|
| Version | 1.0.0 |
| Category | Productivity |
| Permissions | process.control |
| Depends on | agent-role, ai-chat |

# Cron Job

Schedule jobs; fire events for other plugins (IPC) or run AI Chat agents on a schedule.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; `activate`/`deactivate` + optional `getMcpTools` (exposed to ai-chat's AI agent, Dev Mode only)

## Job actions

Mỗi job có 1 `action` chạy khi tới giờ:

- `event` — `broadcast` tín hiệu tới event channel của 1 plugin đích (renderer/widget nhận).
- `agent` — chạy 1 lượt AI Chat agent headless qua `globalThis.__kazuoAiChat.runAgent`.
- `service` — gọi headless 1 service trong registry global `globalThis.__kazuoPluginServices[pluginId][method](payload)`.
  Dùng khi plugin đích cần chạy nền mà không mở widget (vd backup theo lịch của `backup-manager`).
  Spec: `{ type:'service', pluginId, method, payload? }`. Nếu service chưa đăng ký (plugin tắt) → job ghi
  `lastRun` lỗi rõ, tick không crash. Service phải **ném lỗi** thì lượt chạy mới bị ghi là lỗi.
  Xem `references/plugin-runtime-api.md` mục 4d.

Ngược lại, plugin khác (ở tiến trình nền) tạo/liệt kê/xoá job qua dịch vụ
`globalThis.__kazuoPluginServices['cron-job']` — `createJob(spec, pluginId)`, `listJobs()`,
`deleteJob(id)`, `setEnabled(id, enabled)`. KChat dùng nó để model tự đặt lịch.

## Default settings

- `jobs` — default: `[]`

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Entity Notes / Entity Notes
<!-- id: plugin-entity-notes source: plugins-library/entity-notes/README.md -->

# Entity Notes

> Notes tagged to agents, plugins, applications and skills — synced to your account

| | |
|---|---|
| Version | 1.0.0 |
| Category | Productivity |
| Depends on | ai-chat |

# Entity Notes

Notes tagged to agents, plugins, applications and skills — synced to your account

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces

## Default settings

- `exampleSetting` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.


---

# File Explorer / File Explorer
<!-- id: plugin-file-explorer source: plugins-library/file-explorer/README.md -->

# File Explorer

> Browse the local filesystem like Windows Explorer: navigate folders, open files, filter by file type, and manage files (new folder, rename, delete, copy/cut/paste, upload, download).

| | |
|---|---|
| Version | 1.5.2 |
| Category | Productivity |
| Permissions | filesystem.read, filesystem.write |
| Depends on | ai-chat |

# File Explorer

Browse the local filesystem like Windows Explorer: navigate folders, open files, filter by file type, and manage files (new folder, rename, delete, copy/cut/paste, upload, download).

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; `activate`/`deactivate` + optional `getMcpTools` (exposed to ai-chat's AI agent, Dev Mode only)

## Default settings

- `showHidden` — default: `false` — show dotfiles/dot-folders (names starting with `.`) in the list
- `allowedCallers` — default: `[]` — plugin IDs granted access to the `public:*` API below
- `pendingRequests` — default: `[]` — `{ pluginId, requestedAt }` entries awaiting Grant/Deny in Settings

## Backend channels (`plugin:file-explorer:*`, main/index.ts)

### Private (only this plugin's own widget/settings call these)

All take `pluginId` as the first arg (`ensureIsSelf` guard). Reached from the widget via `invoke()`:

- `home` → `{ path }` — the user's home directory (`os.homedir()`)
- `list(dirPath, showHidden)` → `{ path, parent, entries[] }` — directory listing; each entry is `{ name, path, isDir, size, mtime, ext }`, folders first then A→Z. Symlinked directories that fail an `opendirSync` probe (Windows' legacy XP-compat junctions like `SendTo`/`Cookies`/`Recent`, deny-ACL'd) are excluded outright, matching real Explorer. If the directory itself can't be read (`EPERM`/`EACCES`), throws a clear "Access denied" error instead of a raw Node error.
- `open(targetPath)` — open a file/folder with the OS default app (`shell.openPath`)
- `mkdir(parentPath, name)` — create a folder (auto "name (2)" on collision)
- `rename(targetPath, newName)` — rename in place
- `trash(paths[])` → `{ ok, count, failed: [{ path, reason: 'in-use' | 'other', message }] }` — move to the Recycle Bin
  (`shell.trashItem`, recoverable — never a permanent delete). Every item is tried even if an earlier one fails
  (a file locked by another program makes Windows answer "Operation was aborted"). `public:trash` still throws
  when anything failed, after trying them all.
- `paste(sources[], destDir, mode)` — `mode` is `'copy'` or `'cut'`; auto-renames on collision, guards against moving a folder into itself, handles cross-device moves (EXDEV) by copy+remove
- `prepare-download(paths[])` → `{ path, name }` — one plain file is returned as-is; a folder or several items are zipped (host `ctx.modules.archiver`) into `os.tmpdir()/kazuo-file-explorer/` (pruned after 1 hour). The widget then streams it via the bridge's `serveLocalFile(path)` + `?download=<name>`.
- `upload-begin(destDir, name)` → `{ dest, part, exists }` — `part` is a `<name>.<rand>.part` sibling the bytes go to; `exists` lets the widget ask before overwriting. Throws if a folder has that name.
- `upload-commit(part, dest)` — rename the finished part onto `dest` (replaces an existing file). `upload-abort(part)` — delete it.
- `info(path)` → `{ name, path, isDir, size, created, modified, accessed, readOnly, hidden, image: {width,height}|null }`
  — Properties panel. Hidden/read-only come from `attrib` on Windows; image size is read from the file header only.
- `dir-size-start(paths[])` → job id; `dir-size-poll(id)` → `{ size, files, dirs, skipped, done }` | null;
  `dir-size-cancel(id)`. Background async walk (no symlink following); stops by itself after 10s without a poll.
- `thumbnail(path)` → small data URL (longest side 160px) or `null` — used by the web dashboard, which can't load
  `app://local-file`. OS thumbnailer first (async, `nativeImage.createThumbnailFromPath`, Windows/macOS), then
  `nativeImage.createFromPath`.

Double-clicking an image opens an in-widget viewer (←/→ to step, Esc to close); right-click → "Open with default app"
still hands it to the OS.

### Upload / download

File bytes never go through `invoke()`. Download: `prepare-download` → `serveLocalFile(path)` → hidden iframe on
`<url>?download=<name>` (server answers `Content-Disposition: attachment`; desktop shows the OS Save dialog).
Upload (toolbar button, blank-area right-click, or drag-and-drop from the OS): `upload-begin` → bridge
`prepareUpload(part)` → POST the file in 512 KiB chunks to `<url>?offset=N` → `upload-commit`. Chunked because
the cloud relay carries a request body inline in one WebSocket frame. Needs a host with `prepareUpload` and
`ctx.modules.archiver` (added together with this plugin version).

### Public (other plugins may call these — cross-plugin filesystem API)

Same underlying logic as the private channels above (`doOpen`/`doMkdir`/`doRename`/`doTrash`/`doPaste`/`listDir`
are shared functions, not duplicated). Reached by any plugin via
`invoke('plugin:file-explorer:public:<action>', '<your-plugin-id>', ...args)`:

- `public:capabilities` → `{ ok, actions: [...] }` — always open, no gate; lists what's callable.
- `public:requestAccess(callerId)` → `{ ok, status: 'granted' | 'pending' }` — always open. If `callerId`
  isn't already allowed, queues it into `pendingRequests` and logs it (`ctx.log`) so it shows up in
  Dev Mode. The user must open File Explorer's own Settings and press **Grant** before that plugin can
  call anything below.
- `public:home`, `public:list`, `public:open`, `public:mkdir`, `public:rename`, `public:trash`, `public:paste`
  — same signatures as their private counterparts, but every call runs `ensureAuthorizedCaller(callerId)`
  first: throws unless `callerId` is in `allowedCallers`.

**Security note — this is a soft, opt-in gate, not a hard boundary.** `callerId` is whatever the calling
plugin's own renderer code chooses to pass to `invoke()` — the host does not verify it (same limitation
`ensureIsSelf` has, see `.claude/skills/kazuo-create-plugin/references/plugin-runtime-api.md` section 4c).
Granting access stops accidental/well-behaved callers from touching the filesystem before the user
approves them, and gives the user visibility into who's allowed — it does **not** stop a plugin that
deliberately lies about its own id to impersonate an already-granted one.

**Grant/Deny/Revoke UI:** duplicated in both `widget.html`'s settings overlay and `settings.html` (same
`settings.pendingTitle`/`allowedTitle` locale keys), rendering `pendingRequests`/`allowedCallers` as plain
lists with Grant/Deny/Revoke buttons that call `setSettings(...)` directly — no extra IPC channel needed
for the human side, since granting is just editing this plugin's own settings. Because a backend-initiated
`ctx.setSettings` call (e.g. from another plugin's `requestAccess`) doesn't push a live update to an
already-open Settings panel, the panel re-fetches `getSettings()` every time it's opened, so new requests
show up next time it's reopened rather than instantly.

**Web Dashboard:** the backend channels above work fine there too — the Web Dashboard is a browser
tab connected via WebSocket to the SAME running desktop app (`electron/dashboard-server.ts`), so
`ctx.ipcMain.handle` still runs on that machine's real filesystem. The one thing that doesn't work
remotely is the native "Choose folder" dialog (`openFileDialog` — a browser can't pop a local OS
picker for a machine it isn't running on): the widget catches that rejection and falls back to typing
the path manually, same pattern as the git-manager plugin's "Open repository".

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Notepad / Notepad
<!-- id: plugin-notepad source: plugins-library/notepad/README.md -->

# Notepad

> Simple no-login notepad widget — jot text anywhere, auto-saved locally

| | |
|---|---|
| Version | 1.0.3 |
| Category | Productivity |
| Depends on | ai-chat |

# Notepad

Simple no-login notepad widget — jot text anywhere, auto-saved locally.

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## What it does

- One large text area. Type freely; text auto-saves ~400ms after you stop typing.
- Persistence uses the plugin settings store (`setSettings`), so notes are saved **locally on
  this machine** — no account, no server, matching the "no login" requirement.
- Live word / character count in the header.
- Trash button clears the note (asks for confirmation first).

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI (text area + auto-save)
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer
    provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same appearance fields as the widget
  overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces

## Default settings

- `content` — default: `""` (the note text)
- `fontSize` — default: `14` (editor font size in px)
- `wordWrap` — default: `true` (off = horizontal scroll instead of wrapping)

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans
`plugins-library/` on its own, no registration needed) → Install → Enable.


---

# Notification / Notification
<!-- id: plugin-notification source: plugins-library/notification/README.md -->

# Notification

> Show native Windows notifications; other plugins can call in via invoke('plugin:notification:show', {title, body})

| | |
|---|---|
| Version | 1.0.2 |
| Category | Productivity |
| Depends on | ai-chat |

# Notification

Show native Windows notifications; other plugins can call in via invoke('plugin:notification:show', {title, body})

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; registers the IPC channels and shows the native notifications

## Public API — how OTHER plugins call in

Any enabled plugin (from its `widget.js`/`settings.js`) shows a notification with:

```js
await window['kazuo-ai'].invoke('plugin:notification:show', {
  title: 'Build finished',
  body: 'image myapp:latest is ready',
  source: 'docker-manager', // optional — shown as "[docker-manager] ..." when Show source is on
  silent: false,            // optional — overrides the default sound setting for this one call
});
// resolves to { ok: true, at: <timestamp> } or { ok: false, error: 'notifications-unsupported' }
```

This works because the host's `invoke` forwards to any `plugin:*` channel and `plugin:notification:show`
is intentionally NOT restricted to the notification plugin itself. Clicking a notification focuses the app.

Self-only channels (used by this plugin's own widget): `plugin:notification:history`,
`plugin:notification:clear` (both require passing `'notification'` as the first arg).

## Default settings

- `showSource` — default: `true` — prefix the body with `[source]` when the caller passes one
- `silent` — default: `false` — default sound behaviour (each call can override via `silent`)

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable. Use the widget's compose box to send a test notification; recent notifications appear in the History list.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Task Manager / Task Manager
<!-- id: plugin-task-manager source: plugins-library/task-manager/README.md -->

# Task Manager

> Central task store: create/update tasks from the widget, from other plugins via invoke(), or from ai-chat's AI agent via MCP tools

| | |
|---|---|
| Version | 1.0.2 |
| Category | Productivity |
| Depends on | ai-chat |

# Task Manager

Central task store: create/update tasks from the widget, from other plugins via invoke(), or from ai-chat's AI agent via MCP tools

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`filter.*`/`status.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — task store (persisted in this plugin's settings slice) + IPC channels + `getMcpTools` (task_create/task_update/task_list, ai-chat AI agent, Dev Mode only)
- `package.json` — declares `zod` (only needed for the MCP tools; host runs `npm install --omit=dev` on install)

## Default settings

- `tasks` — default: `[]` (array of task objects)
- `hideCompleted` — default: `false`

## IPC channels (open to any plugin)

`invoke('plugin:task-manager:upsert' | 'update' | 'remove' | 'list' | 'get', arg)` — see
`.claude/features/task-manager-plugin.md` for payload shapes. `clear` is self-gated (`'task-manager'`).

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Telegram Web Archiver / Telegram Web Archiver
<!-- id: plugin-telegram-web-archiver source: plugins-library/telegram-web-archiver/README.md -->

# Telegram Web Archiver

> Log into Telegram Web with a dedicated profile stored inside the plugin folder, archive private and group message history locally, then summarize or ask questions about your groups.

| | |
|---|---|
| Version | 1.0.2 |
| Category | Productivity |
| Permissions | network.remote, filesystem.write, process.spawn |

# Telegram Web Archiver

Log into Telegram Web with a dedicated profile stored inside the plugin folder, archive private and group message history locally, then summarize or ask questions about your groups.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces (REQUIRED, same key set in both)
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; `activate`/`deactivate` + optional `getMcpTools` (exposed to ai-chat's AI agent, Dev Mode only)
- `main/navigation.ts` (+ compiled `main/navigation.js`) — deterministic `/k/` navigation layer (viewport/window state, safe click primitives, chat/topic entry by name); see `.claude/features/telegram-web-archiver.md` for the full design and current verification status
- `test/navigation.test.ts` — pure-logic unit tests for `navigation.ts` (`node --test`)
- `tools/verify-navigation.ts` — live verification harness for the navigation layer (needs a real Telegram login; not yet run — see the feature doc)

## Default settings

- `exampleSetting` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

## Accessibility + i18n

This plugin must keep the i18n + accessibility contract in `.claude/skills/kazuo-create-plugin/references/a11y-i18n-checklist.md`: both locale files present with the same keys, no hardcoded user-visible strings (aria-label included), a name on every icon-only button, a <label for> on every field, keyboard reachable controls with a visible focus ring, and a live region for status text. The scaffold ships all of that — keep it when you extend the UI.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Capture & Record / Capture & Record
<!-- id: plugin-capture-record source: plugins-library/capture-record/README.md -->

# Capture & Record

> Capture screenshots and record video - full screen, a single window, or a selected region.

| | |
|---|---|
| Version | 1.0.2 |
| Category | Media |
| Permissions | filesystem.write |
| Depends on | notification, ai-chat |

# Capture & Record

Chụp ảnh và quay video màn hình - toàn màn hình, cửa sổ, vùng chọn

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — chọn chế độ (toàn màn hình/cửa sổ/vùng chọn),
  nút chụp ảnh, nút bắt đầu/dừng quay video, nút thu mic. Nút Chụp/Quay **2 bước**: bấm lần 1 chọn
  (nút kia bỏ chọn), bấm lại nút đang chọn mới chạy. Settings overlay tự chứa (⚙) có ô nhập phím tắt.
- `settings.html` / `js/settings.js` / `css/settings.css` — cùng field/hành vi với overlay trên, dùng
  bởi Plugin Manager và cửa sổ pop-out
- `locales/en.json5` / `locales/vi.json5` — toàn bộ text UI
- `main/index.ts` — IPC glue (`list-sources`, `capture`, `start-recording`, `stop-recording`,
  `choose-folder`, `list-displays`, `set-position`, `set-shortcut`, `ensure-shortcut`). Thư mục lưu
  theo hệ điều hành + phím tắt toàn cục mở chụp Vùng chọn (`globalShortcut`).
- `main/capture.ts` — chụp ảnh qua `desktopCapturer` (không cần stream/BrowserWindow riêng), tự động
  copy ảnh vào clipboard sau khi lưu file (không áp dụng cho video). `saveDataUrlPng` lưu ảnh vùng
  chọn đã ghép chú thích; `captureDisplayDataUrl` đóng băng ảnh nền cho overlay.
- `main/region-picker.ts` + `main/overlay.html` + `main/overlay-preload.ts` — overlay chọn vùng +
  **chú thích** (vẽ nhiều hình chữ nhật/tròn ghi thẳng vào ảnh), 1 cửa sổ overlay/màn hình
  (multi-monitor), theo mẫu "đóng băng màn hình trước" rồi ghép ảnh bằng canvas
- `main/recorder.ts` + `main/recorder.html` + `main/recorder-preload.ts` — quay video WebM qua
  `getUserMedia({chromeMediaSource:'desktop'})` + `MediaRecorder` trong 1 cửa sổ ẩn

Xem chi tiết cách hoạt động + giới hạn đã biết tại `.claude/features/capture-record.md`.

## Default settings

- `platformFolders[<os>]` — thư mục lưu **theo hệ điều hành** (`win32`/`darwin`/`linux`), mỗi OS giữ
  đường dẫn riêng. Giá trị của OS hiện tại được mirror ra 2 key phẳng `screenshotFolder`/`videoFolder`
  để widget + `capture.ts` đọc như cũ. Lần đầu tự resolve `Pictures/CaptureRecord`, `Videos/CaptureRecord`;
  bản cài cũ (chỉ có key phẳng) được migrate sang slot của OS hiện tại.
- `captureShortcut` — phím tắt toàn cục mở chụp Vùng chọn, mặc định `Ctrl+Shift+S` (Win+Shift+S bị
  Windows chiếm dụng nên không dùng được).
- `micEnabled` — mặc định: `true` (bật/tắt bằng nút 🎤 trên widget).

## Giới hạn đã biết

- Quay video ở chế độ "Vùng chọn" hiện tự chuyển thành quay toàn màn hình (chưa hỗ trợ crop video
  real-time theo vùng). Chú thích chỉ áp dụng cho **ảnh** vùng chọn, không áp dụng cho video.
- Phím tắt toàn cục có thể bị host `globalShortcut.unregisterAll()` xoá khi bật/tắt plugin khác; widget
  tự đăng ký lại qua `ensure-shortcut` mỗi lần `settingsChanged` (còn 1 khe hở khi widget bị ẩn).
- Quyền microphone cấp hệ điều hành (đặc biệt macOS) nằm ngoài khả năng của plugin.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`
on its own, no registration needed) → Install → Enable. Thử đủ 4 luồng: chụp toàn màn hình, chụp cửa
sổ, chụp vùng chọn, quay video (bật/tắt mic).

After editing `main/*.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the
project root).


---

# Video Editor / Video Editor
<!-- id: plugin-video-editor source: plugins-library/video-editor/README.md -->

# Video Editor

> Crop & trim videos using FFmpeg

| | |
|---|---|
| Version | 1.0.1 |
| Category | Media |
| Permissions | shell.exec, filesystem.read, filesystem.write |
| Depends on | ai-chat |

# Video Editor

Crop & trim videos using FFmpeg

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `shell.exec`, `filesystem.read`, `filesystem.write` — shown to the user before install; the host does not sandbox on them.

## What it does

- Loads a video, sets a crop box and in/out points, then re-encodes with FFmpeg — or trims without re-encoding, which is much faster.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `ffmpegPath` — default: `"ffmpeg"`
- `outputCodec` — default: `"libx264"`
- `outputQuality` — default: `"23"`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Database Manager / Database Manager
<!-- id: plugin-database-manager source: plugins-library/database-manager/README.md -->

# Database Manager

> Manage MySQL, MongoDB, Redis & SQL Server databases

| | |
|---|---|
| Version | 1.0.1 |
| Category | Dev Tools |
| Permissions | shell.exec, network.localhost, network.remote |
| Depends on | ai-chat |

# Database Manager

Manage MySQL, MongoDB, Redis & SQL Server databases

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `shell.exec`, `network.localhost`, `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Query MySQL, MongoDB, Redis and SQL Server from tabs, browse tables, inspect server info and re-run past queries.
- Three exec modes: the local CLI client, the same client over SSH, or the official npm driver from the main process (installed on demand).

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `main/index.ts` (compiled to `main/index.js`) — runs in the Electron main process: `activate` / `deactivate`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `connections` — default: array, 4 entries by default
- `activeConnection` — default: `"default-mysql"`
- `queryHistory` — default: empty array
- `maxHistorySize` — default: `50`
- `refreshInterval` — default: `0`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json`
(from the project root).


---

# Debug Snapshot / Debug Snapshot
<!-- id: plugin-debug-snapshot source: plugins-library/debug-snapshot/README.md -->

# Debug Snapshot

> Capture a redacted debug bundle (state, screenshots, DOM, logs) for AI analysis (debug-only)

| | |
|---|---|
| Version | 1.0.0 |
| Category | Dev Tools |
| Depends on | ai-chat |

# Debug Snapshot

Capture a redacted debug bundle (state, screenshots, DOM, logs) for AI analysis (debug-only)

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*`, applied to widget.html by `KazuoUtil.applyI18n()` through `data-i18n` attributes
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; `activate`/`deactivate` + optional `getMcpTools` (exposed to ai-chat's AI agent, Dev Mode only)

## Default settings

- `exampleSetting` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Git / Git
<!-- id: plugin-git-manager source: plugins-library/git-manager/README.md -->

# Git

> Git repository manager — commit history & graph, branches, staging, diff viewer, fetch/pull/push (Fork-style)

| | |
|---|---|
| Version | 2.8.0 |
| Category | Dev Tools |
| Permissions | process.spawn, filesystem.read, filesystem.write |
| Depends on | ai-chat |

# Git

Fork-style Git repository manager: commit history & graph, branches / remotes / tags /
stashes sidebar, working-directory staging & commit, a colored diff viewer, and
fetch / pull / push.

**Type:** plugin with a `main/` backend — see
`.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

Every git command runs in the main process as `spawn('git', argv)` with **no shell**
involved. The renderer never executes git itself.

## Files

### Backend (`main/`) — compiled, and the `.js` is committed

- `main/git-run.ts` — `runGit(repoPath, argv, opts)` → `{ ok, code, stdout, stderr, notFound? }`.
  Imports no Electron and needs no `PluginContext`, so tests `require()` it directly.
- `main/git-http.ts` — `apiGet(url, headers, opts)` for the hosting APIs. Also never rejects.
  `opts.request` is injectable so tests need no TLS certificate — the same reason `gitBin` exists.
- `main/index.ts` — `activate` / `deactivate`, `ensureIsSelf`, and five channels
  (`:ping`, `:run`, `:api`, `:clone`, `:testremote`). Exports `BACKEND_VERSION`. Builds the
  per-provider request headers and the clone credentials itself — the renderer sends a provider
  name and a token, never raw headers, so it cannot have the backend attach an arbitrary header to
  an arbitrary host. `:testremote` (`git ls-remote`, for the clone dialog's Test Connection button)
  shares its auth-building with `:clone` through `buildAuthEnv()`, so the two cannot disagree about
  whether a URL is reachable.

### Renderer — twenty files, one namespace each

No bundler and no module system: each file is an IIFE publishing exactly one `window.KZGit*`.
**The `<script>` order in `widget.html` IS the dependency order** — a file may only use
namespaces declared above it. Calls pointing the other way go through `window.KZGitApp` at call
time. Every file but one stays under 400 lines; see `js/view-clone.js` below.

| File | Namespace | Contents |
|---|---|---|
| `js/git-parse.js` | `KZGitParse` | git text → objects. Pure: no DOM, no bridge, no git. |
| `js/graph.js` | `KZGitGraph` | commits → graph lanes and segments. Pure. |
| `js/branch-tree.js` | `KZGitBranchTree` | branch names → folder tree. Pure. |
| `js/bridge.js` | `KZGitBridge` | The only door to git; detects a dead backend. |
| `js/state.js` | `KZGitState` | `S.tabs[]`, `tab()`, hydrate/persist, shared helpers. |
| `js/git-api.js` | `KZGitApi` | `gitRun`, `refreshAll`, `reloadWorking`, selection. The individual loaders stay private. |
| `js/view-diff.js` | `KZGitViewDiff` | The coloured diff pane. |
| `js/view-sidebar.js` | `KZGitViewSidebar` | Left rail, five sections (Submodules included). |
| `js/view-changes.js` | `KZGitViewChanges` | Staged / Changes columns + commit box. |
| `js/view-history.js` | `KZGitViewHistory` | Commit list + three-tab detail pane. |
| `js/view-tabs.js` | `KZGitViewTabs` | The repository tab strip: chips, scroll arrows, drag-to-reorder. |
| `js/git-host.js` | `KZGitHost` | GitHub/GitLab differences and clone-progress parsing. Pure. |
| `js/accounts.js` | `KZGitAccounts` | Saved accounts, token checks, repository listings. |
| `js/clone-run.js` | `KZGitCloneRun` | Runs one clone. Draws nothing; both callers share it. |
| `js/view-accounts.js` | `KZGitViewAccounts` | The Accounts window: list on the left, tabs on the right. |
| `js/view-account-add.js` | `KZGitViewAccountAdd` | The seven service tiles, the sign-in form, Update token. |
| `js/view-account-repos.js` | `KZGitViewAccountRepos` | The Repositories tab: grouped by owner, Clone per row. |
| `js/view-clone.js` | `KZGitViewClone` | The + menu, the repository browser, and the clone confirm screen (protocol, parent folder, name, Test Connection). 457 lines — the one file over the 400-line target, see the file's own header comment. |
| `js/actions-repo.js` | `KZGitActRepo` | Repository selection, fetch/pull/push. |
| `js/actions-branch.js` | `KZGitActBranch` | Branches, tags, stashes. |
| `js/actions-stage.js` | `KZGitActStage` | Stage / unstage / discard / commit. |
| `js/widget.js` | `KZGitApp` | Shell: boot, `render()`, click dispatch, settings overlay. |

`settings.html` / `js/settings.js` mirror the widget's settings overlay for the Plugin Manager
screen and the pop-out window (intentionally duplicated — each plugin HTML file is its own sandbox).

## Build

**After editing anything in `main/`:**

```bash
tsc -p tsconfig.plugins.json      # from the repository root
```

Commit the generated `main/*.js` and `main/*.js.map` — the host loads the `.js`.

Forgetting this is silent: the host keeps using the previous build with no warning. The guard is
`BACKEND_VERSION` in `main/index.ts` versus `EXPECTED_BACKEND_VERSION` in `js/bridge.js` — a
mismatch shows a "rebuild the plugin" screen instead of failing somewhere confusing later.

**Bump `version` in `manifest.json` in any release that changes `js/`.** The installed copy under
`userData/plugins/` is refreshed by `syncInstalledMainFolders()` only when the library declares a
`mainEntry` the installed copy lacks, or a higher version — and it runs only at app startup. Without
a bump, renderer changes never reach users. During development: restart the app; toggling the plugin
off and on is not enough.

## Test

```bash
cd plugins-library/git-manager
node --test test/*.test.js          # 494 tests, about 30-40 seconds
```

Refresh the recorded git output (only when the sample repo changes, or a new command is added):

```bash
node test/fixtures/capture.js
```

- `test/fixtures/make-repo.js` builds a deterministic repository — pinned dates, identity and
  config, isolated from the machine's gitconfig. Two runs produce identical SHAs.
- `test/fixtures/golden/` holds real git output. Its `.gitattributes` sets `* -text`: without it,
  `core.autocrlf=true` (the Git for Windows default) rewrites every LF on checkout and the parsers
  receive input no git ever produced.
- `test/widget-harness.js` loads the real `widget.html` and every `js/` file into jsdom behind
  a fake bridge, and documents every place jsdom differs from the webview.
- `test/load-renderer.js` loads a pure renderer file with `vm` into a sandbox with **no `document`**.

Characterization tests are labelled `[LOCK]` (must stay green, body must not be edited) or
`[CHANGES IN Pn]` (that phase changes it deliberately, with the reason).

## Default settings

- `openTabs` — default: `[]` — repository path per open tab, in order. **Source of truth.**
- `activeTabIndex` — default: `0`
- `repoPath` — default: `""` — always equals `openTabs[activeTabIndex]`. Kept so `js/settings.js`
  can go on reading and writing one path without knowing tabs exist.
- `accounts` — default: `[]` — saved GitHub/GitLab accounts. Each holds a personal access token
  IN CLEAR: this app has no safeStorage, and file-storage keeps its Google refresh token the same
  way. The token is never shown again after saving, and never reaches a log, a status message,
  the DOM or a git argument.
- `recentRepos` — default: `[]` — most-recently-opened repositories
- `logLimit` — default: `1000` — max commits loaded into the history list
- `showAllBranches` — default: `true` — `--branches --tags --remotes` vs the current branch only

Settings from before `openTabs` existed hold only `repoPath`; that becomes the single tab on first
load after upgrading.

## Architecture notes

- **argv arrays, never a shell.** Branch names and paths containing spaces, `'`, `&`, `;` or `$`
  are ordinary data. There is no quoting layer because there is nothing to quote for.
- **`exec`'s 5MB cap is gone.** `git show` of a large commit used to fail outright; chunks are
  collected and joined at close. A 256MB ceiling remains as a backstop — this runs in the main
  process, so an unbounded read of a multi-gigabyte blob would take the whole app down rather than
  failing one command.
- **`runGit` never rejects** — every path resolves `{ ok, … }` and callers branch on `ok`. A missing
  git binary sets `notFound` rather than being recognised by matching an error string.
- **One transport, no fallback.** A backend that is not answering gets an explicit screen with a
  Retry button and one of four distinct explanations, never a blank widget.
- **Tab-shaped state.** `S.tabs[]`, one entry per open repository, shown as a tab strip. An empty
  list is legal — the strip hides and the welcome screen takes the pane — but `tab()` still never
  returns undefined, because 24 of its call sites dereference a property straight away — it answers
  with an empty placeholder tab instead.
- **Wholesale re-render.** Everything derives from the active tab; actions mutate the repository,
  reload the affected slice and repaint.
- **Virtualised history.** Only the rows on screen exist in the DOM, so a ten thousand commit
  repository scrolls without stutter. Row height is fixed in both CSS and JS, and a test asserts the
  two agree — drift shows up as rows sliding away from the scroll position.
- **Graph lanes are pure and cached.** js/graph.js reproduces `git log --graph` row for row; the
  layout is computed once per commit list and reused across scrolls.
- **The graph column may never be shorter than a row.** Its SVG carries a `viewBox` exactly `ROW_H`
  tall, but the CSS height resolves against `.commit-row`'s content box — give that row vertical
  padding or a border and the browser silently scales the whole drawing down and centres it, so the
  lines stop short of both edges and the graph breaks between rows while the markup stays correct.
  jsdom computes no layout, so a stylesheet test pins it instead.

## Open repository — via the shared in-app file picker

"Open repository" calls `window['kazuo-ai'].openFileDialog({ properties: ['openDirectory'] })`, which
opens the host's shared in-app file picker (`FilePickerDialog`, styled like Windows File Explorer and
identical on desktop and the Web Dashboard — see `.claude/features/shared-in-app-dialogs.md`). If
file-explorer is not installed or enabled, the picker itself offers a manual path-entry fallback.

## Known limitations

- No merge / rebase / cherry-pick / reset UI, no blame, no line-level staging.
- Submodules are read-only: list, status and open-as-tab. No init / update / sync, and no recursive
  nesting.
- Tabs have no rename, context menu, keyboard shortcuts, or drag between windows.
- Accounts cover seven services by personal access token — no OAuth device flow, no
  key management. Gitea, Bitbucket and Bitbucket Server were written from their
  documentation and have never been tried against a real server; their tiles say so.
  No creating repositories, pull requests or issues.
- Cloning needs **git 2.31 or newer**: the token is passed through GIT_CONFIG_* environment
  variables so it stays out of argv (readable by other processes) and out of .git/config (written to
  disk). The consequence is that a freshly cloned private repository can only fetch and push if the
  machine already has a credential stored — the widget says so when the clone finishes.
- Untracked files show a placeholder instead of a synthetic diff until staged.
- Push/pull use the default upstream; no per-remote/-branch picker yet.
- No progress streaming channel; no `gitPath` setting.
- The commit filter searches only the commits already loaded (`logLimit`), not the whole history.
- Two known defects are deliberately preserved and locked by tests — see
  `plans/2026-08-09-git-manager-fork-parity/notes-for-m1.md`. The third, the phantom "origin" remote
  row, was fixed in M1.
- Running under the web dashboard is **unverified**: the backend channels are not blocked there, but
  nobody has tried it.

## Requirements

The `git` CLI must be installed and on `PATH` — the PATH of the **main process**, which is not
necessarily the one your terminal has. If it cannot be found the widget says so explicitly.


---

# Kazuo AI Analytic / Kazuo AI Analytic
<!-- id: plugin-kazuo-ai-analytic source: plugins-library/kazuo-ai-analytic/README.md -->

# Kazuo AI Analytic

> Live performance analytics: FPS, per-process CPU/RAM, webview count (debug-only)

| | |
|---|---|
| Version | 1.0.0 |
| Category | Dev Tools |
| Depends on | ai-chat |

# Kazuo AI Analytic

Live performance analytics: FPS, per-process CPU/RAM, webview count (debug-only)

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `debugOnly: true` (only listed/loaded while app Debug Mode is on), `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — analytics panel: live FPS meter (renderer rAF) + per-process CPU/RAM table + process/webview counts, polled every 1.5s (pauses when hidden)
- `locales/en.json5` / `locales/vi.json5` — UI strings (unused by the panel; kept for future i18n)
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; exposes `plugin:kazuo-ai-analytic:metrics` returning `app.getAppMetrics()` + webview count

## Notes

- This plugin has no settings — it is a read-only diagnostic panel.
- `debugOnly` gating is enforced app-side: hidden from Plugin Manager, overlay, web store, and HTTP bridge, and its backend is not activated while Debug Mode is off.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/` on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Terminal / Terminal
<!-- id: plugin-terminal source: plugins-library/terminal/README.md -->

# Terminal

> Full-featured terminal widget (xterm.js + node-pty): local shell with configurable font, theme, shell, cwd, scrollback and startup commands.

| | |
|---|---|
| Version | 1.0.1 |
| Category | Dev Tools |
| Permissions | process.spawn, process.control, shell.exec |
| Depends on | ai-chat |

# Terminal

Full-featured terminal widget (xterm.js + node-pty): local shell with configurable font, theme, shell,
cwd, scrollback and startup commands. Extracted from the app's built-in terminal into a self-contained,
removable plugin.

**Type:** `backend` (needs a long-lived PTY process). Local shell only — no SSH.

## Architecture

`xterm.js (webview) ↔ invoke/on bridge ↔ main/index.ts (Electron main) ↔ main/pty-host.js (node-pty)`

node-pty (a native module) runs in a child process. `main/index.ts` spawns `main/pty-host.js` using the
app's own Electron binary in Node mode (`process.execPath` + `ELECTRON_RUN_AS_NODE=1`) and talks to it
over newline-delimited JSON on stdin/stdout. This needs NO system `node` on PATH; node-pty's prebuild
loads under Electron's ABI (verified). node-pty lives in the host's shared npm store, passed to pty-host
via NODE_PATH + argv. See `.claude/features/terminal-plugin.md` for the full write-up.

## Files

- `manifest.json` — `mainEntry`, `defaultSettings`, `defaultWidgetConfig`, permissions.
- `package.json` — declares `node-pty` (host runs `npm install --omit=dev` into the install dir on install).
- `main/index.ts` (+ compiled `main/index.js`) — Electron main. Channels `plugin:terminal:create|write|resize|kill`,
  manages one pty-host process, forwards output via `ctx.broadcast('plugin:terminal:event', …)`.
- `main/pty-host.js` — runs under system `node`, spawns node-pty; receives shell/cwd/name/args from main.
- `vendor/xterm.js` + `xterm.css` + `xterm-addon-fit.js` — UMD builds loaded as global scripts (no bundler).
- `widget.html` / `js/widget.js` / `css/widget.css` — multi-tab terminal UI (one xterm + PTY session per
  tab, file-explorer-style tab bar with `+`/`×`/middle-click-close) + self-contained "⚙" settings overlay
  and "↻" restart (active tab).
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay
  (intentionally duplicated), used by the Plugin Manager screen and the pop-out window.
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*` / `settings.*` namespaces.
- `icon.svg` — `>` prompt + cursor on a dark slate gradient.

## Default settings

- `shell` — `"default"` (default | cmd | powershell | pwsh | bash | git-bash | custom)
- `customShellPath` — `""` (used when shell = custom)
- `cwd` — `""` (empty = home folder)
- `fontSize` — `13`
- `fontFamily` — `"Consolas, 'Courier New', monospace"`
- `theme` — `"dark"` (dark | light | solarized-dark | monokai)
- `cursorBlink` — `true`
- `scrollback` — `9999`
- `termType` — `"xterm-256color"` (xterm-256color | dumb)
- `startupCommands` — `""` (one command per line)
- `startupDelay` — `500` (ms between startup commands)

Live-applied (no restart): font size/family, theme, cursor blink, scrollback.
Needs restart (↻): shell, cwd, terminal mode.

## Requirements & test

No system `node` needed (uses the app's Electron binary via `process.execPath` + `ELECTRON_RUN_AS_NODE`).
After editing `main/index.ts`, recompile: `npx tsc -p tsconfig.plugins.json` (from the project root).

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`) →
Install (host installs node-pty) → Enable.


---

# Awesome Selfhosted / Awesome Selfhosted
<!-- id: plugin-awesome-selfhosted source: plugins-library/awesome-selfhosted/README.md -->

# Awesome Selfhosted

> Browse awesome-selfhosted categories and git-clone apps into a folder

| | |
|---|---|
| Version | 1.0.0 |
| Category | System |
| Permissions | shell.exec, filesystem.write |
| Depends on | ai-chat |

# Awesome Selfhosted

Browse the [awesome-selfhosted](https://github.com/awesome-selfhosted/awesome-selfhosted) list
(categories + apps) inside Kazuo, then `git clone` an app's source repository into a folder you choose.

**Type:** `exec` — uses `window['kazuo-ai'].localExec()` to run `git clone` locally. No backend (`main/`).

## How it works

1. On open, the widget fetches the awesome-selfhosted `README.md` from GitHub, parses it into
   categories → apps (name, description, license, language, website, source repo, ⚠ unmaintained flag),
   and caches the result in the webview's `localStorage` (`as_cache_v1`, 24h TTL). **Refresh** forces a re-fetch.
2. Left pane = categories; right pane = apps in the selected category. The search box filters apps
   across all categories.
3. Each app has **Website** / **Source** (open in the default browser via the OS opener) and **Install**.
4. **Install** runs `git -C "<installDir>" clone [--depth 1] "<repoUrl>"` through `localExec` and streams
   the output into the log panel. If no folder is set yet, the native folder picker opens first.
   Apps with no clonable git repository show **Install** disabled (use **Website** instead).

The clone URL is the app's `Source Code` link, or its homepage when that already points at a git host.
URLs are validated (`isSafeUrl`) before being placed on the shell command line.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI (category browser + install)
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces

## Default settings

- `installDir` — default: `""` — folder that apps are cloned into (chosen via the folder picker or typed in)
- `shallow` — default: `true` — clone with `--depth 1` (latest commit only, faster)

## Requirements

- `git` must be installed and on the system `PATH` (the plugin runs `git clone`).
- Internet access on first load (to fetch the list); afterwards the cached list works offline.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`
on its own, no registration needed) → Install → Enable. Pick a folder, open a category, and click
**Install** on any app with a source repo.


---

# Desktop Automation / Desktop Automation
<!-- id: plugin-desktop-automation source: plugins-library/desktop-automation/README.md -->

# Desktop Automation

> Drive the mouse, keyboard and windows and read the screen the way a real user would (pyautogui-based).

| | |
|---|---|
| Version | 1.0.0 |
| Category | System |
| Permissions | process.spawn, shell.exec, filesystem.read, filesystem.write |
| Depends on | ai-chat |

# Desktop Automation

Dieu khien chuot/ban phim/cua so va nhan dien man hinh nhu nguoi dung that (pyautogui) - mo public API + MCP cho plugin/agent khac

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI
  - has its own "⚙" button + settings overlay built into widget.html/widget.js (host no longer provides a per-widget gear icon — see references/plugin-runtime-api.md section 1b)
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; manages the python daemon, exposes IPC (private + public) and `getMcpTools` (ai-chat AI agent, Dev Mode only)
- `python/da_agent.py` — long-lived automation daemon (pyautogui/pygetwindow), JSON-line protocol over stdin/stdout
- `package.json` — declares `zod` (only used by the MCP schema; host runs `npm install --omit=dev` on install)

## Default settings

- `pythonPath` — default `""` → uses `python` (Windows) / `python3` on PATH
- `failsafe` — default `true` (slam mouse to a screen corner to abort)
- `actionPause` — default `0` (seconds between pyautogui actions)

## Python dependencies (auto-installed)

The backend checks for `pyautogui pillow opencv-python pygetwindow` **on enable** and, if any are
missing, runs `python -m pip install …` automatically (with the configured interpreter) and restarts
the daemon. The widget shows an "Install deps" bar you can also trigger manually.

Manual equivalent, if you prefer:

```
pip install pyautogui pillow opencv-python pygetwindow
```

`opencv-python` is optional — without it `locate` still works but `confidence` matching is off. If the
python interpreter is a system-wide install, pip may need admin rights (the log will say so).

## Public API (for other plugins / agents)

```js
await window['kazuo-ai'].invoke('plugin:desktop-automation:public:exec', 'caller-id',
  'click', { x: 500, y: 300, button: 'left', clicks: 2 });
await window['kazuo-ai'].invoke('plugin:desktop-automation:public:capabilities'); // list commands
```

Commands: move / move_rel / click / double_click / right_click / mouse_down / mouse_up / drag /
scroll / type / paste / press / hotkey / key_down / key_up / pixel / screenshot / locate / locate_all /
windows / active_window / window_find / activate / minimize / maximize / restore / close_window /
move_window / resize_window / position / size / probe.

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically → Install → Enable → click **Probe**
in the widget. If it reports `pyautogui missing`, run the pip command above.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from the project root).


---

# Device Manager / Device Manager
<!-- id: plugin-device-manager source: plugins-library/device-manager/README.md -->

# Device Manager

> Central device registry: add/edit/remove devices (Windows/Linux/macOS/Android/iOS) from the widget, other plugins via invoke(), or ai-chat's AI agent via MCP tools

| | |
|---|---|
| Version | 1.0.2 |
| Category | System |
| Depends on | ai-chat |

# Device Manager

Central device registry: add/edit/remove devices (Windows/Linux/macOS/Android/iOS) from the widget,
other plugins via `invoke()`, or ai-chat's AI agent via MCP tools.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

> Phase 1 (skeleton): CRUD only. A device stores `{ id, name, os, note, createdAt, updatedAt }`.
> Connection/control fields (host, port, credentials, live status) are intentionally deferred to a
> later phase.

## Files

- `manifest.json` — metadata, `defaultSettings = { devices: [] }`, `defaultWidgetConfig`. No `settings`
  entry point (nothing to configure yet).
- `widget.html` / `js/widget.js` / `css/widget.css` — main UI: OS filter, add/edit form, device list
  with Edit/Delete per row.
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*` / `filter.*` / `os.*` namespaces.
- `main/index.ts` (+ compiled `main/index.js`) — runs in the Electron main process; the central device
  store. Registers `plugin:device-manager:list/get/upsert/update/remove` (open to any caller) and
  `:clear` (self-gated). Optional `getMcpTools` exposes `device_list/device_add/device_update/device_remove`
  to ai-chat's AI agent (Dev Mode only).
- `package.json` — declares `zod` (only needed for the MCP tools; host runs `npm install --omit=dev` on
  install). Missing zod → `getMcpTools` returns `[]`, everything else still works.

## Default settings

- `devices` — default: `[]`

## Public API (for other plugins)

```js
// Create (no id) or update (known id). Returns the saved device.
await window['kazuo-ai'].invoke('plugin:device-manager:upsert', { name: 'Server 1', os: 'linux', note: '' });
await window['kazuo-ai'].invoke('plugin:device-manager:update', { id, patch: { note: 'prod' } });
await window['kazuo-ai'].invoke('plugin:device-manager:remove', id);
const devices = await window['kazuo-ai'].invoke('plugin:device-manager:list', { os: 'linux' }); // os optional
```

`os` is one of `windows | linux | macos | android | ios` (anything else is coerced to `unknown`).

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`
on its own, no registration needed) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (run from
the project root).


---

# Docker Manager / Docker Manager
<!-- id: plugin-docker-manager source: plugins-library/docker-manager/README.md -->

# Docker Manager

> Manage Docker containers & images via SSH

| | |
|---|---|
| Version | 1.0.1 |
| Category | System |
| Depends on | ai-chat |

# Docker Manager

Manage Docker containers & images via SSH

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Lists containers and images, follows container logs, and starts, stops, removes or updates containers.
- Runs the docker CLI either on this machine or on a remote host over SSH.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"local"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Kubernetes Manager / Kubernetes Manager
<!-- id: plugin-kubernetes source: plugins-library/kubernetes/README.md -->

# Kubernetes Manager

> Monitor and manage Kubernetes clusters, pods, services, deployments

| | |
|---|---|
| Version | 1.0.1 |
| Category | System |
| Depends on | ai-chat |

# Kubernetes Manager

Monitor and manage Kubernetes clusters, pods, services, deployments

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Lists pods, services and deployments, follows pod logs, scales a deployment and runs a command inside a pod.
- Runs kubectl either on this machine or on a remote host over SSH.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"local"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`
- `namespace` — default: `""`
- `kubeconfig` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# NGINX Manager / NGINX Manager
<!-- id: plugin-nginx-manager source: plugins-library/nginx-manager/README.md -->

# NGINX Manager

> Manage NGINX web server via SSH or locally – status, sites, config, logs

| | |
|---|---|
| Version | 1.0.1 |
| Category | System |
| Depends on | ai-chat |

# NGINX Manager

Manage NGINX web server via SSH or locally – status, sites, config, logs

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Shows NGINX status, edits site configs, tails logs, and requests or renews Let's Encrypt certificates through certbot.
- Only paths under nginxConfigPath can be opened, so the editor cannot be pointed at arbitrary files.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"ssh"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`
- `nginxConfigPath` — default: `"/etc/nginx"`
- `nginxLogPath` — default: `"/var/log/nginx"`
- `certbotEmail` — default: `""`
- `certbotAutoRenew` — default: `true`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Sandbox Manager / Sandbox Manager
<!-- id: plugin-sandbox-manager source: plugins-library/sandbox-manager/README.md -->

# Sandbox Manager

> Manage local app sandbox sessions with separate profiles and window focus control

| | |
|---|---|
| Version | 1.0.1 |
| Category | System |
| Permissions | process.spawn, process.control |
| Depends on | ai-chat |

# Sandbox Manager

## Mục đích

Sandbox Manager là plugin quản lý các session chạy ứng dụng Windows thật. Bản đầu tập trung vào quản lý process và focus cửa sổ, không phải sandbox bảo mật kiểu VM.

## File liên quan

- `plugins-library/sandbox-manager/manifest.json`
- `plugins-library/sandbox-manager/main/index.ts`
- `plugins-library/sandbox-manager/main/sandbox-manager.ts`
- `plugins-library/sandbox-manager/main/window-probe.ts`
- `plugins-library/sandbox-manager/widget.html`
- `plugins-library/sandbox-manager/js/widget.js`
- `plugins-library/sandbox-manager/css/widget.css`
- `plugins-library/sandbox-manager/settings.html`
- `plugins-library/sandbox-manager/js/settings.js`
- `plugins-library/sandbox-manager/css/settings.css`
- `electron/plugin-loader.ts`
- `src/lib/types.ts`

## Cách hoạt động

- Plugin có `mainEntry` riêng và đăng ký IPC channels `plugin:sandbox-manager:*`.
- Mỗi sandbox config lưu trong plugin settings gồm tên, executable path, arguments, working directory, profile directory và trạng thái enabled.
- Runtime giữ session trong `Map<sessionId, Session>`.
- Một session chỉ được có một process root đang chạy. Nếu start lại session đang chạy, plugin trả lỗi thay vì spawn thêm process.
- Khi start, plugin tạo profile directory và spawn app bằng `child_process.spawn`.
- Khi stop, plugin dùng `taskkill /PID <pid> /T /F` để dừng cây process.
- Window list/focus dùng PowerShell gọi Windows APIs: lấy cửa sổ theo process tree và focus HWND bằng `SetForegroundWindow`.

## UI

- Widget hiển thị danh sách sandbox sessions, status, PID, số window, Start/Stop/Restart/Refresh windows/Focus.
- Settings cho phép thêm, sửa, xóa sandbox config và chỉnh auto-refresh interval.

## Giới hạn MVP

- Đây là process/profile isolation, không cô lập bảo mật như Windows Sandbox/VM/container.
- Chưa hỗ trợ click/gõ phím/chuột.
- Chưa hỗ trợ screenshot/capture window.
- Focus có thể thất bại nếu app/game chạy quyền cao hơn, bị anti-cheat chặn, hoặc cửa sổ thật thuộc process launcher phức tạp.
- Nếu app không hỗ trợ profile riêng qua args/env/cwd, mức không xung đột phụ thuộc vào chính app đó.


---

# Service Manager / Service Manager
<!-- id: plugin-service-manager source: plugins-library/service-manager/README.md -->

# Service Manager

> Manage systemctl services via SSH or locally – view, start, stop, restart

| | |
|---|---|
| Version | 1.0.1 |
| Category | System |
| Depends on | ai-chat |

# Service Manager

Manage systemctl services via SSH or locally – view, start, stop, restart

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Lists systemd services and starts, stops or restarts them, on this machine or over SSH.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"ssh"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`
- `filter` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# FileStorage / FileStorage
<!-- id: plugin-file-storage source: plugins-library/file-storage/README.md -->

# FileStorage

> File storage (local disk or Google Drive) exposed via HTTP API for external apps and scripts

| | |
|---|---|
| Version | 1.0.4 |
| Category | Networking |
| Permissions | filesystem.read, filesystem.write, network.remote |
| Depends on | ai-chat |

# FileStorage

## Mục đích

FileStorage là plugin backend biến máy chạy Kazuo AI thành 1 nơi lưu trữ file, expose qua HTTP REST API để các app/script khác (local hoặc từ xa qua mạng) upload/tải/xoá file. Hỗ trợ 2 storage provider có thể chuyển đổi trong Settings: **Local Disk** (mặc định) hoặc **Google Drive**.

## File liên quan

- `plugins-library/file-storage/manifest.json`
- `plugins-library/file-storage/main/index.ts` — activate/deactivate, đăng ký IPC `plugin:file-storage:*`
- `plugins-library/file-storage/main/storage-server.ts` — HTTP server thật (Node `http` module qua `ctx.modules.http`), điều phối request tới backend đang active
- `plugins-library/file-storage/main/types.ts` — interface `FileItem`, `FolderItem`, `StorageItem`, `StorageBackend` dùng chung
- `plugins-library/file-storage/main/local-backend.ts` — backend lưu đĩa cục bộ
- `plugins-library/file-storage/main/google-drive.ts` — backend Google Drive (OAuth2 + REST API)
- `plugins-library/file-storage/widget.html`, `js/widget.js`, `css/widget.css`
- `plugins-library/file-storage/settings.html`, `js/settings.js`, `css/settings.css`
- `plugins-library/file-storage/locales/en.json5`, `vi.json5`

## Cách hoạt động

- Loại plugin: `backend` (có `mainEntry: main/index.js`, cần tiến trình HTTP server sống liên tục).
- Server lắng nghe trên **mọi network interface** (không truyền host cho `server.listen`) vì người dùng chọn phương án cho phép truy cập từ xa qua mạng, không giới hạn localhost.
- Xác thực: mọi request (trừ `GET /health`) bắt buộc header `X-API-Key` khớp với setting `apiKey`. Nếu `apiKey` rỗng thì server từ chối tất cả (fail-closed). `activate()` tự sinh API key ngẫu nhiên (`crypto.randomBytes(24)`) nếu chưa có.
- Giới hạn dung lượng: setting `maxFileSizeMB` (mặc định 100). Toàn bộ body upload được đọc vào bộ nhớ (Buffer) trước khi giao cho backend ghi — đơn giản hoá để 1 luồng xử lý dùng chung cho cả 2 backend (local ghi file, Drive cần multipart request); đây là đánh đổi chấp nhận được ở quy mô mặc định 100MB, không phù hợp cho file rất lớn.
- Đổi `port` cần bấm nút "Restart server" trong widget (gọi IPC `plugin:file-storage:restart`) vì server đã bind port cũ. Đổi `storageProvider`/`apiKey`/`maxFileSizeMB` có hiệu lực **ngay lập tức, không cần restart** — mỗi request đọc lại `ctx.getSetting()` để chọn backend.
- **Provider là kiểu "chuyển đổi" (switch), không đồng bộ song song**: tại 1 thời điểm chỉ 1 nơi lưu trữ hoạt động. File upload lúc đang ở Local Disk sẽ KHÔNG xuất hiện khi chuyển sang Google Drive và ngược lại (2 cây thư mục độc lập).
- **Mô hình thư mục** (`main/types.ts`): `StorageItem` = `FolderItem | FileItem`, phân biệt bằng field `kind`. Mọi item có `parentId: string | null` — `null` nghĩa là "thư mục gốc"; mỗi backend tự quy đổi `null` thành gốc thật của nó (Local: `null` thật sự; Drive: id của thư mục `googleFolderName`). Phần gọi API/IPC/UI không cần biết quy đổi này, chỉ truyền lại đúng id mà backend đã trả về trước đó. Phạm vi tính năng thư mục: xem + điều hướng (breadcrumb) + tạo mới + **xoá thư mục rỗng** (từ chối nếu còn item bên trong) — KHÔNG hỗ trợ move/rename/xoá đệ quy (xem "Giới hạn MVP").

### Local Disk backend (`local-backend.ts`)

- `storage-data/<id>` (trong `ctx.installPath`) — blob file thật, tên = UUID.
- `storage-index.json` — mảng metadata `{ id, name, size, mimeType, uploadedAt }`.
- Thư mục này KHÔNG bị xoá khi cài lại plugin (host chỉ copy đè file có trong `plugins-library/`, không xoá file thừa trong install dir) — chỉ mất khi Uninstall.

### Google Drive backend (`google-drive.ts`)

- **Xác thực OAuth2** — Google chặn đăng nhập trong webview nhúng, nên flow là: mở trình duyệt hệ thống thật (`electron.shell.openExternal`) tới URL consent của Google → Google redirect về 1 local HTTP server tạm (`127.0.0.1:<port ngẫu nhiên>`) do plugin tự dựng để bắt `?code=...` → đổi code lấy `access_token`/`refresh_token` qua `https://oauth2.googleapis.com/token`. Không dùng `googleapis` SDK — gọi thẳng REST API Drive v3 qua module `https` có sẵn của Node để không phải thêm npm dependency.
- **Người dùng phải tự tạo OAuth Client ID (loại "Desktop app") trên Google Cloud Console** rồi nhập Client ID/Secret vào Settings — Kazuo AI không thể tạo hộ vì đây là định danh ứng dụng gắn với tài khoản Google Cloud của người dùng. Các bước:
  1. Vào https://console.cloud.google.com/apis/credentials, tạo project (nếu chưa có).
  2. Bật "Google Drive API" trong API Library.
  3. Cấu hình màn hình đồng ý OAuth (OAuth consent screen) — nếu app ở trạng thái "Testing", phải thêm chính email Google của mình vào danh sách "Test users". **Nên bấm "Publish app" ngay ở bước này**: để ở "Testing" thì refresh token chỉ sống 7 ngày, cứ 1 tuần lại phải đăng nhập lại (xem mục refresh token bên dưới).
  4. Tạo Credentials → OAuth client ID → loại **Desktop app**. Copy Client ID + Client Secret.
- **Scope xin quyền: `https://www.googleapis.com/auth/drive` (đầy đủ)** — ĐÃ ĐỔI từ `drive.file` (hẹp) theo yêu cầu người dùng, vì `drive.file` chỉ cho thấy file do CHÍNH APP tạo ra qua API — file người dùng tự tay upload trực tiếp qua trang drive.google.com vào cùng thư mục sẽ KHÔNG hiện trong widget (đây là hạn chế thật của Google, không phải bug). Đánh đổi: quyền rộng hơn (đọc/ghi được toàn bộ Drive của người dùng, không chỉ file do app tạo), người dùng đã được hỏi và đồng ý đánh đổi này. **Người đã kết nối bằng scope cũ (`drive.file`) phải bấm Disconnect rồi Connect lại** để refresh token mới được cấp theo scope mới — đổi hằng số `SCOPE` trong code không tự nâng cấp token cũ.
- Toàn bộ dữ liệu nằm trong 1 thư mục gốc riêng trong Drive thật của người dùng (hiển thị bình thường qua Drive UI) — đây chính là "root" (`parentId: null`) của cây thư mục ảo. **Tên thư mục gốc cấu hình được qua setting `googleFolderName`** (mặc định `"FileStorage (Kazuo AI)"`, không còn hardcode). Id thư mục gốc thật cache trong setting `googleFolderId` sau lần tạo/tìm đầu tiên (`ensureRootFolderId()` trong `google-drive.ts`) — có `googleFolderId` rồi thì không gọi lại Drive API để tra cứu nữa.
- **Đổi `googleFolderName` sẽ tự xoá `googleFolderId` đang cache** (thực hiện ở tầng UI — `fieldPatch()` trong `js/widget.js` và `js/settings.js` gửi cả 2 key cùng lúc khi field này đổi). Lần gọi Drive tiếp theo sẽ tìm-hoặc-tạo thư mục gốc theo tên mới, có hiệu lực ngay, không cần disconnect/reconnect lại OAuth. File ở thư mục gốc cũ vẫn còn nguyên trên Drive nhưng plugin sẽ không thấy nữa (đổi tên = đổi "cửa sổ nhìn vào Drive", không di chuyển dữ liệu).
- **Thư mục con** (tạo qua `createFolder`) là thư mục Drive thật lồng bên trong thư mục gốc (hoặc lồng nhau tiếp) — Drive vốn hỗ trợ sẵn khái niệm này (`mimeType: application/vnd.google-apps.folder` + field `parents`), không cần thêm cơ chế riêng. `deleteFolder(id)` kiểm tra còn item con hay không (`'<id>' in parents`) trước khi gọi DELETE, ném lỗi nếu còn.
- `refreshToken` lưu plain-text trong plugin settings (giống mức bảo mật của các field password khác trong hệ thống plugin hiện tại, ví dụ `docker-manager`) — không có mã hoá riêng.
- Access token cache trong bộ nhớ (module-level), tự làm mới qua `refresh_token` grant khi hết hạn hoặc chưa có.
- **Refresh token chết thì tự ngắt kết nối** — khi grant `refresh_token` bị Google trả về `invalid_grant`, `getAccessToken()` gọi `disconnect()` (xoá `googleRefreshToken` + `googleFolderId`) rồi ném lỗi tiếng Việt hướng dẫn kết nối lại. Không làm vậy thì `isConnected()` vẫn thấy chuỗi refresh token cũ trong settings và UI báo "Connected" trong khi mọi thao tác đều lỗi, buộc người dùng phải tự mò bấm Disconnect. `requestJson()` gắn `googleErrorCode` vào Error để phân biệt được `invalid_grant` với các lỗi 400 khác — endpoint token trả mã lỗi dạng chuỗi trần (`{"error":"invalid_grant"}`), khác dạng object của Drive API.
- **Nguyên nhân số 1 khiến refresh token chết: OAuth consent screen còn ở trạng thái "Testing"** — Google giới hạn refresh token sống đúng **7 ngày** ở trạng thái này, hết hạn là phải đăng nhập lại. Cách chữa tận gốc nằm ngoài code: Google Cloud Console → OAuth consent screen → **Publish app** (chuyển "In production"). App chỉ mình mình dùng thì không cần Google xét duyệt, chỉ hiện cảnh báo "app chưa xác minh" lúc đăng nhập. Hai nguyên nhân còn lại: người dùng thu hồi quyền ở myaccount.google.com/permissions, hoặc đổi mật khẩu Google.
- Upload dùng `multipart/related` upload (metadata JSON + bytes trong 1 request) — không dùng resumable upload, phù hợp file vừa/nhỏ (giới hạn bởi `maxFileSizeMB`).

## REST API

Base URL: `http://<host>:<port>` (port mặc định `8787`, cấu hình trong Settings). API giống hệt nhau bất kể provider nào đang active. `parentId` bỏ trống/omit = thư mục gốc.

| Method | Path | Auth | Mô tả |
|---|---|---|---|
| GET | `/health` | Không | `{ ok: true }` — kiểm tra server sống |
| GET | `/items?parentId=<id>` | Có | Danh sách thư mục + file bên trong `parentId` (gốc nếu bỏ trống): `[{ kind, id, name, parentId, size?, mimeType?, uploadedAt?, createdAt? }]` |
| POST | `/folders` | Có | Tạo thư mục — JSON body `{ name, parentId }` → trả về `FolderItem` vừa tạo |
| DELETE | `/folders/:id` | Có | Xoá thư mục — trả lỗi 409 nếu thư mục còn item bên trong |
| POST | `/files?parentId=<id>` | Có | Upload — body = raw bytes, header `X-File-Name` bắt buộc (percent-encoded UTF-8), trả về `FileItem` vừa tạo |
| GET | `/files/:id` | Có | Tải file, `Content-Disposition: attachment` |
| DELETE | `/files/:id` | Có | Xoá file, `{ ok: true }` |

Header xác thực: `X-API-Key: <apiKey trong Settings>`. **Không tương thích ngược** với API bản cũ (`GET /files` trả danh sách phẳng) — đã xác nhận chưa có app/script nào phụ thuộc bản cũ trước khi đổi.

## IPC channels (`plugin:file-storage:*`)

`status`, `list-items` (parentId), `create-folder` (name, parentId), `delete-folder` (id), `delete-file` (id), `restart` (server HTTP) + `drive-status`, `connect-drive`, `disconnect-drive` (Google Drive OAuth, gọi `server.drive.*` trong `storage-server.ts`).

## UI

- **Widget kiểu File Explorer** (`js/widget.js`): breadcrumb đường dẫn (`pathStack`, mảng `{id, name}`, phần tử đầu luôn là gốc `{id: null, name: 'Home'}`) + danh sách thư mục (📁, click để mở, nút Xoá) rồi tới file (📄, size, nút Xoá) + nút "+ New Folder". Đổi provider hoặc connect/disconnect Drive đều reset `pathStack` về gốc (khác cây thư mục, id của bên này vô nghĩa với bên kia). Widget mặc định 700×600 (tăng từ 480×500 để duyệt thư mục dễ hơn).
- **"New Folder" dùng `window['kazuo-ai'].prompt()` chung** (dialog in-app của platform, chạy cả desktop lẫn web) — hàm `createFolderViaPrompt()` hỏi tên rồi gọi `create-folder`. Trước đây dùng dialog tự vẽ (`#new-folder-overlay`) vì `window.prompt()` native không render được trong webview overlay trong suốt; nay đã thay bằng prompt CHUNG của platform (không phải `window.prompt` native) nên render đúng — dialog tự vẽ đã gỡ. Mọi báo lỗi (folder không rỗng, lỗi tạo thư mục, lỗi Drive, download) dùng `window['kazuo-ai'].alert()` chung; file "Download" dùng `window['kazuo-ai'].saveFileDialog()` để chọn nơi lưu (không còn `dialog.showSaveDialog` native ở backend). Xem `.claude/features/shared-in-app-dialogs.md`.
- Dòng "Storage: Local Disk / Google Drive"; nếu đang ở Drive thì hiện thêm trạng thái kết nối + nút "Connect Google Drive"/"Disconnect"; trạng thái server (đang chạy/dừng + port); tổng số thư mục + số file + tổng dung lượng. Tự cập nhật realtime qua event `plugin:file-storage:event` (backend broadcast `files-changed` sau mọi thao tác tạo/xoá file hoặc thư mục).
- Settings (cả `settings.html` và overlay trong widget, 2 nơi giữ đồng bộ theo đúng quy ước của hệ thống plugin): chọn Storage Provider, Port, Max file size (MB), API Key, Google Client ID/Secret, Drive Folder Name, và nút Connect/Disconnect Google Drive.
- **Lưu setting theo từng field riêng lẻ** (`fieldPatch(fieldId)` trong `js/widget.js`/`js/settings.js`): mỗi ô chỉ gửi đúng key của chính nó khi đổi, KHÔNG gộp gửi toàn bộ form. Đây là fix cho 1 bug thật đã gặp: bản cũ gộp cả 6+ field vào 1 patch mỗi lần đổi 1 ô, nên 1 ô hiển thị giá trị cũ/rỗng (vd `apiKey` chưa kịp load) có thể ghi đè mất giá trị đúng đang lưu ở field khác. Nút "Back" (`settings-close` trong widget) còn chủ động gọi `flushSettingsOverlay()` để lưu lại toàn bộ trước khi đóng, phòng trường hợp field vừa sửa chưa kịp fire `change` event.
- **`toggleSettingsOverlay(show)` trong `js/widget.js` luôn `await loadSettings()` (tải lại settings mới nhất) trước khi hiện panel** — fix cho 1 race condition thật đã gặp: nếu panel Settings mở ra ngay sau khi widget vừa tải lại (vd sau bật/tắt plugin) nhưng TRƯỚC KHI `getSettings()` (IPC round-trip) hoàn tất, các field sẽ hiện giá trị rỗng từ biến `settings = {}` ban đầu; do `flushSettingsOverlay()` luôn gửi lại TOÀN BỘ field khi bấm "Back" (kể cả field không đổi), việc này từng xoá mất `googleClientId`/`googleClientSecret`/`apiKey` thật đang lưu. Luôn gọi `loadSettings()` ngay trước khi hiện panel đảm bảo dữ liệu hiển thị/flush luôn là dữ liệu thật, bất kể `init()` đã chạy xong hay chưa.
- **Ẩn/hiện nhóm "Google Drive OAuth" theo Storage Provider**: nhóm field Client ID/Secret/Drive Folder Name (+ trạng thái/nút Connect trong `settings.html`) chỉ hiển thị khi `storageProvider === 'drive'`, ẩn khi chọn Local Disk. Toggle bằng class `.hidden` trên `#ov-google-group` (widget overlay) / `#google-group` (settings.html), cập nhật ngay khi đổi provider — không cần đóng/mở lại Settings.
- **`boot(retries)` trong `js/widget.js` — retry chờ cầu nối `window['kazuo-ai']` sẵn sàng**: host inject `window['kazuo-ai']` vào webview bất đồng bộ (lúc webview bắn sự kiện `dom-ready`), chạy đua với chính script này (script nằm cuối `<body>`, chạy ngay khi HTML parse xong) — KHÔNG đảm bảo `window['kazuo-ai']` đã tồn tại lúc script chạy. Bug thật đã gặp: code cũ gọi `init()` ngay lập tức không retry, nếu thua cuộc đua thì TOÀN BỘ IPC call (`getSettings`, `invoke(...)`) im lặng trả về rỗng/null mãi mãi (không có cơ chế nào chạy lại sau đó) — biểu hiện: widget kẹt hiển thị "Storage: Local Disk" (sai), "Status unknown", "0 folders • 0 files • 0 B" dù setting thật đúng, và mọi nút (kể cả "+ New Folder") bấm không phản ứng gì (vì `invoke()` trả `null` ngay lập tức khi thiếu cầu nối, không throw nên không có alert lỗi). Fix: bọc toàn bộ `init()` + đăng ký event listener (`settingsChanged`, `plugin:file-storage:event`, i18n) trong `boot(retries)`, thử lại mỗi 200ms tối đa 20 lần (~4 giây) — cùng pattern `tryLoad(retries)` mà `js/settings.js` đã dùng từ đầu. `js/widget.js` trước đây KHÔNG có cơ chế này dù `js/settings.js` đã có — đây là chỗ khác biệt cần nhớ nếu sửa lại 1 trong 2 file sau này.
- **"Storage Location" + nút "Open" trong Settings** (cả `settings.html` và overlay widget): hiện đường dẫn thật của nơi lưu trữ đang active và cho phép mở trực tiếp.
  - IPC mới: `plugin:file-storage:get-location` (trả `{ kind: 'local'|'drive', path?, url? }`) và `plugin:file-storage:open-location` (thực thi mở), cả 2 implement trong `main/index.ts` (không phải trong từng backend, vì đây là hành vi UI-support, không phải logic lưu trữ cốt lõi).
  - Local Disk: `path` = `<installPath>/storage-data` (thư mục thật trên máy), nút Open gọi `electron.shell.openPath()` → mở File Explorer.
  - Google Drive: `url` = `https://drive.google.com/drive/folders/<googleFolderId>` (chỉ có khi đã kết nối và folder gốc đã resolve xong), nút Open gọi `electron.shell.openExternal()` → mở trình duyệt. Nếu chưa kết nối/chưa có folder id, ô hiện text "Connect Google Drive first..." và nút bị disable.
  - `refreshLocation()` (widget.js) / `refreshLocation()` (settings.js) được gọi lại mỗi khi: mở panel Settings, đổi Storage Provider, đổi Drive Folder Name (vì folder id bị xoá cache), connect/disconnect Drive — vì kết quả `get-location` phụ thuộc vào tất cả các thứ đó.

## Giới hạn MVP

- Không có CORS handling (dùng cho app/script gọi trực tiếp, không phải fetch từ trình duyệt cross-origin).
- Thư mục chỉ hỗ trợ **xem + điều hướng + tạo mới + xoá khi rỗng** — KHÔNG hỗ trợ move file/thư mục giữa các nơi, không đổi tên, không xoá đệ quy (xoá thư mục còn item bên trong sẽ bị từ chối, phải xoá hết bên trong trước).
- Không hỗ trợ resumable upload. Toàn bộ upload buffer vào RAM trước khi ghi (không stream trực tiếp xuống đĩa/Drive) — đơn giản nhưng không phù hợp file cực lớn.
- Không đồng bộ Local Disk và Google Drive — chuyển provider là đổi hẳn "nơi nhìn thấy file", không copy dữ liệu qua lại. Đổi provider cũng reset breadcrumb widget về gốc.
- Widget chưa có nút Upload file trực tiếp (chỉ xem/xoá/tạo thư mục qua UI) — upload vẫn phải qua REST API từ app/script ngoài.
- Chưa expose `getMcpTools` cho AI agent (ai-chat) — có thể bổ sung sau nếu cần AI thao tác trực tiếp (list/upload/delete) qua Dev Mode.
- Icon còn là placeholder (`icon.svg` sinh tự động) — nên thay icon thật trước khi dùng lâu dài.


---

# Kazuo Remote Desktop / Kazuo Remote Desktop
<!-- id: plugin-kazuo-remote-desktop source: plugins-library/kazuo-remote-desktop/README.md -->

# Kazuo Remote Desktop

> Google Remote Desktop embedded in a widget with a Chrome user-agent and persistent login

| | |
|---|---|
| Version | 1.0.0 |
| Category | Networking |
| Permissions | network.remote |
| Depends on | ai-chat |

# Kazuo Remote Desktop

Embeds Google Remote Desktop (`https://remotedesktop.google.com/`) inside a Kazuo
widget. Ported from the standalone **ChromeRemote** Electron project — it keeps that
project's core trick (a `<webview>` with a faked Chrome user-agent + a persistent
partition so the Google login sticks) and its toolbar/status-bar shell, but drops the
parts that don't fit the plugin sandbox (native keyboard hook, CDP-embedded chrome.exe,
OS-level tab manager).

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## How it works

- `js/widget.js` builds a nested `<webview>` inside `#view-host` with:
  - `useragent` = Chrome 131 (Google refuses webview logins that advertise Electron)
  - `partition` = `persist:kazuo-grd` (dedicated persistent session; login survives restarts)
  - `allowpopups` = true (Google auth sometimes opens a popup)
- Toolbar wires Back / Forward / Reload / Home + an address bar (Enter to navigate).
- Status bar shows loading state + current URL.

### Host requirement

A guest `<webview>` cannot embed another `<webview>` unless the host opts in. Two host
files set `webpreferences="webviewTag"` on the plugin webview so this plugin can nest one:
`src/components/PluginWidget.svelte` (docked widget) and
`src/components/PluginWindowApp.svelte` (popped-out window).

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — toolbar + nested webview + status bar
  - has its own "⚙" button + settings overlay built into widget.html/widget.js
- `settings.html` / `js/settings.js` / `css/settings.css` — same field as the widget overlay
  (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings, `widget.*`/`settings.*` namespaces

## Default settings

- `homeUrl` — default: `"https://remotedesktop.google.com/"` — page opened on load and on Home

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans
`plugins-library/` on its own, no registration needed) → Install → Enable. The widget
should load the Google Remote Desktop sign-in page. Log in once; the session persists.

> If Google still blocks sign-in ("this browser may not be secure"), that is the same
> limitation the original ChromeRemote project worked around with the Chrome UA — no
> further workaround is available from inside the plugin sandbox.


---

# SSH Reverse Proxy / SSH Reverse Proxy
<!-- id: plugin-ssh-reverse-proxy source: plugins-library/ssh-reverse-proxy/README.md -->

# SSH Reverse Proxy

> Open reverse SSH tunnels (multiple ports) through a remote host.

| | |
|---|---|
| Version | 1.0.1 |
| Category | Networking |
| Depends on | ai-chat |

# SSH Reverse Proxy

Open reverse SSH tunnels (multiple ports) through a remote host.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Keeps one or more reverse SSH tunnels open to a remote host, reconnecting when the link drops.
- Other plugins reach it through the bridge aliases startTunnel / stopTunnel / getTunnelStatus.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `main/index.ts` (compiled to `main/index.js`) — runs in the Electron main process: `activate` / `deactivate`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `authMethod` — default: `"password"`
- `password` — default: `""`
- `privateKeyPath` — default: `""`
- `passphrase` — default: `""`
- `serverAliveInterval` — default: `60`
- `autoStart` — default: `false`
- `autoReconnect` — default: `true`
- `portForwards` — default: array, 1 entry by default

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json`
(from the project root).


---

# Window Sync / Window Sync
<!-- id: plugin-window-sync source: plugins-library/window-sync/README.md -->

# Window Sync

> Browse, copy, and auto-sync files with a peer machine over SSH.

| | |
|---|---|
| Version | 1.0.1 |
| Category | Networking |
| Permissions | filesystem.read, filesystem.write, network.localhost, ssh-tunnel.use |
| Depends on | ssh-reverse-proxy, ai-chat |

# Window Sync

Browse, copy, and auto-sync files with a peer machine over SSH.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ssh-reverse-proxy`, `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `filesystem.read`, `filesystem.write`, `network.localhost`, `ssh-tunnel.use` — shown to the user before install; the host does not sandbox on them.

## What it does

- Browses the file tree on a peer machine, copies files in either direction, and can keep a folder pair in sync automatically.
- It reaches the peer over the tunnel ssh-reverse-proxy holds open, which is why it depends on that plugin.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `main/index.ts` (compiled to `main/index.js`) — runs in the Electron main process: `activate` / `deactivate`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `localServerPort` — default: `9999`
- `peerHost` — default: `"127.0.0.1"`
- `peerPort` — default: `10000`
- `peerAlias` — default: `"Peer"`
- `syncDirectory` — default: `""`
- `peerSyncDirectory` — default: `""`
- `autoSync` — default: `false`
- `watchDebounceMs` — default: `750`
- `includeGlobs` — default: array, 1 entry by default
- `excludeGlobs` — default: array, 2 entries by default
- `authToken` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json`
(from the project root).


---

# Cloudflare Dashboard / Cloudflare Dashboard
<!-- id: plugin-cloudflare-dashboard source: plugins-library/cloudflare-dashboard/README.md -->

# Cloudflare Dashboard

> Cloudflare overview - zones, traffic analytics, SSL status, cache management

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare Dashboard

Cloudflare overview - zones, traffic analytics, SSL status, cache management

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Reads zones, traffic analytics, SSL status and cache state through the Cloudflare API.
- Needs an API token with read access. Purging the cache asks for confirmation first.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `zoneId` — default: `""`
- `refreshInterval` — default: `60`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cloudflare DNS / Cloudflare DNS
<!-- id: plugin-cloudflare-dns source: plugins-library/cloudflare-dns/README.md -->

# Cloudflare DNS

> DNS records management - create, edit, delete records, DNSSEC status

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare DNS

DNS records management - create, edit, delete records, DNSSEC status

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Lists, creates, edits and deletes DNS records for one zone, and shows DNSSEC status.
- The filter box narrows the record list; deleting a record asks for confirmation.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `zoneId` — default: `""`
- `refreshInterval` — default: `60`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cloudflare R2 Storage / Cloudflare R2 Storage
<!-- id: plugin-cloudflare-r2 source: plugins-library/cloudflare-r2/README.md -->

# Cloudflare R2 Storage

> R2 object storage - manage buckets, browse objects, usage stats

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare R2 Storage

R2 object storage - manage buckets, browse objects, usage stats

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Browses R2 buckets and their objects, with usage figures.
- Bucket listing goes through the Cloudflare API, object listing through the S3-compatible endpoint, so it needs both an API token and an S3 access key pair.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `s3AccessKeyId` — default: `""`
- `s3SecretAccessKey` — default: `""`
- `refreshInterval` — default: `60`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cloudflare Security / Cloudflare Security
<!-- id: plugin-cloudflare-security source: plugins-library/cloudflare-security/README.md -->

# Cloudflare Security

> WAF rules, firewall events, DDoS protection, IP access management

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare Security

WAF rules, firewall events, DDoS protection, IP access management

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Shows WAF rules, firewall events, DDoS protection state and IP access rules for one zone.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `zoneId` — default: `""`
- `refreshInterval` — default: `30`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cloudflare Tunnel / Cloudflare Tunnel
<!-- id: plugin-cloudflare-tunnel source: plugins-library/cloudflare-tunnel/README.md -->

# Cloudflare Tunnel

> Manage Cloudflare Tunnels - create, monitor, and configure tunnel connections

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare Tunnel

Manage Cloudflare Tunnels - create, monitor, and configure tunnel connections

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Creates, inspects and deletes Cloudflare Tunnels, and shows each connector and the colo it landed in.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `refreshInterval` — default: `30`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Cloudflare Tunnel Runner / Cloudflare Tunnel Runner
<!-- id: plugin-cloudflare-tunnel-runner source: plugins-library/cloudflare-tunnel-runner/README.md -->

# Cloudflare Tunnel Runner

> Run and manage the cloudflared process that publishes the dashboard through a Cloudflare Tunnel.

| | |
|---|---|
| Version | 1.0.0 |
| Category | Cloud |
| Permissions | shell.exec |
| Depends on | ai-chat |

# Cloudflare Tunnel Runner

Run and manage the cloudflared process that publishes the dashboard through a Cloudflare Tunnel.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `shell.exec` — shown to the user before install; the host does not sandbox on them.

## What it does

- Starts and stops the local cloudflared process that publishes this machine through a named tunnel.
- The backend owns the process, so it keeps running while the widget is closed; the widget streams its log.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `main/index.ts` (compiled to `main/index.js`) — runs in the Electron main process: `activate` / `deactivate`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `cloudflaredPath` — default: `"%USERPROFILE%\\cloudflared\\cloudflared.exe"`
- `tunnelName` — default: `"kazuo-dashboard"`
- `configPath` — default: `"%USERPROFILE%\\.cloudflared\\config.yml"`
- `publicUrl` — default: `"https://dash.kaiitech.net"`
- `autoStart` — default: `false`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.

After editing `main/index.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json`
(from the project root).


---

# Cloudflare Workers / Cloudflare Workers
<!-- id: plugin-cloudflare-workers source: plugins-library/cloudflare-workers/README.md -->

# Cloudflare Workers

> Manage Cloudflare Workers, KV, R2 buckets, and D1 databases

| | |
|---|---|
| Version | 1.0.1 |
| Category | Cloud |
| Permissions | network.remote |
| Depends on | ai-chat |

# Cloudflare Workers

Manage Cloudflare Workers, KV, R2 buckets, and D1 databases

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

**Permissions declared:** `network.remote` — shown to the user before install; the host does not sandbox on them.

## What it does

- Manages Workers scripts plus the KV namespaces, R2 buckets and D1 databases in the same account.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.png` — Store and Plugin Manager icon

## Default settings

- `apiToken` — default: `""`
- `accountId` — default: `""`
- `refreshInterval` — default: `60`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Grafana Monitor / Grafana Monitor
<!-- id: plugin-grafana source: plugins-library/grafana/README.md -->

# Grafana Monitor

> Monitor Grafana dashboards, alerts, and datasources

| | |
|---|---|
| Version | 1.0.1 |
| Category | Monitoring |
| Depends on | ai-chat |

# Grafana Monitor

Monitor Grafana dashboards, alerts, and datasources

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Lists dashboards, alerts and datasources from a Grafana server and shows their health.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"local"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`
- `grafanaUrl` — default: `"http://localhost:3000"`
- `apiKey` — default: `""`
- `useServiceAccount` — default: `false`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Process Manager / Process Manager
<!-- id: plugin-process-manager source: plugins-library/process-manager/README.md -->

# Process Manager

> Monitor running processes with live CPU/RAM usage and end tasks - works on Windows, macOS and Linux

| | |
|---|---|
| Version | 1.0.0 |
| Category | Monitoring |
| Permissions | shell.exec, process.control |

# Process Manager

Live view of the processes running on the host machine — CPU %, memory, and an "End task" button,
like the OS task manager. Works on Windows, macOS and Linux, in the desktop app and in the Web
Dashboard (where it still reports the machine hosting the app, not the browser's device).

**Type:** `exec` (no backend) — the widget shells out through `window['kazuo-ai'].localExec()`.
See `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`, `platforms`
  (`win`/`mac`/`linux`/`webapp`)
- `widget.html` / `js/widget.js` / `css/widget.css` — CPU + memory meters, process table, settings overlay
- `settings.html` / `js/settings.js` / `css/settings.css` — same two fields as the widget overlay
  (intentionally duplicated), used by the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings (`widget.*` / `settings.*`)

## How the numbers are collected

`localExec` runs on the machine hosting the app in BOTH runtimes (the Web Dashboard forwards it over
its WebSocket to the same `child_process.exec`), so the widget must not infer the OS from
`navigator.userAgent` — a phone browser viewing a Windows host would guess wrong. It asks the host
instead: `echo %OS%` prints `Windows_NT` under cmd.exe and stays literal under a POSIX shell. Probed
once per widget load, then cached.

One shell command per refresh, parsed in `js/widget.js`:

| OS | Command | Notes |
|----|---------|-------|
| Windows | `powershell -EncodedCommand …` (`Get-Process` + `Win32_OperatingSystem`) | base64 UTF-16LE avoids cmd.exe quoting problems; returns JSON |
| macOS / Linux | `getconf _NPROCESSORS_ONLN`, `/proc/meminfo` or `sysctl`+`vm_stat`, `ps -axo pid=,rss=,time=,args=` | per-OS parts fail silently on the other OS, so one string covers both |

Both probes report **cumulative** CPU seconds per process, so the percentage is a delta between two
consecutive samples: `(cpuNow - cpuBefore) / (elapsed × cores) × 100`. The first sample after opening
the widget therefore shows `--` in the CPU column.

"End task" runs `taskkill /F /PID …` on Windows and `kill -9 …` elsewhere, after the shared
`confirm()` modal. Killing a process owned by another user needs elevation; the error is surfaced in
the toolbar status line.

## Default settings

- `refreshInterval` — default `5` (seconds; `0` disables auto-refresh)
- `groupByName` — default `false` (merge processes sharing a name into one row, summing CPU/RAM)

## Test

Open Kazuo AI → Plugin Manager — this plugin appears automatically (the host scans `plugins-library/`
on its own, no registration needed) → Install → Enable.


---

# Prometheus Monitor / Prometheus Monitor
<!-- id: plugin-prometheus source: plugins-library/prometheus/README.md -->

# Prometheus Monitor

> Monitor Prometheus metrics, targets, alerts, and rules

| | |
|---|---|
| Version | 1.0.1 |
| Category | Monitoring |
| Depends on | ai-chat |

# Prometheus Monitor

Monitor Prometheus metrics, targets, alerts, and rules

**Type:** `ui-settings` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

**Requires:** `ai-chat` — checked when installing, not installed for you.

## What it does

- Runs PromQL queries and lists targets, alerts and rules from a Prometheus server.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — the widget, including its own gear button and settings overlay (the host draws no per-widget gear icon)
- `settings.html` / `js/settings.js` / `css/settings.css` — the same fields again, for the Plugin Manager screen and the pop-out window
- `locales/en.json5` / `locales/vi.json5` — UI strings under `widget.*` and `settings.*`
- `icon.svg` — Store and Plugin Manager icon

## Default settings

- `mode` — default: `"local"`
- `host` — default: `""`
- `port` — default: `"22"`
- `username` — default: `"root"`
- `password` — default: `""`
- `refreshInterval` — default: `30`
- `prometheusUrl` — default: `"http://localhost:9090"`
- `basicAuthUser` — default: `""`
- `basicAuthPassword` — default: `""`

## Test

Open Kazuo AI → Plugin Manager — the plugin appears on its own (the host scans `plugins-library/`,
nothing to register) → Install → Enable.


---

# Screen Lock / Screen Lock
<!-- id: plugin-screen-lock source: plugins-library/screen-lock/README.md -->

# Screen Lock

> Khoa man hinh mem: phim tat hoac tu khoa khi idle, hoat anh 2 con mat phan ung theo du lieu he thong, o nhap mat khau tuong lai.

| | |
|---|---|
| Version | 1.0.0 |
| Category | Security |
| Permissions | process.control |
| Depends on | ai-chat |

# Screen Lock

Soft screen lock: global-hotkey or idle auto-lock, a fullscreen kiosk overlay with two
animated eyes that react to live system data, and a futuristic password field to unlock.

**Type:** `backend`. This is an app-level SOFT lock (immersive overlay), NOT an OS lock — a
determined user can still bypass it via Task Manager. Password is stored as a salted SHA-256 hash.

## Files

- `manifest.json` — metadata, `defaultSettings`, `defaultWidgetConfig`.
- `main/index.ts` (+ compiled `index.js`) — main process: global shortcut, idle watcher
  (`powerMonitor`), one fullscreen kiosk `BrowserWindow` per display, password verify + lockout,
  1 Hz CPU/mem/duration stats feed.
- `main/lock-preload.ts` (+ `lock-preload.js`) — `contextBridge` bridge (`window.screenLock`).
- `main/lock.html` / `main/lock.css` / `main/lock.js` — the lock window UI (real BrowserWindow):
  aurora backdrop, HUD telemetry, two reactive eyes, neon unlock panel.
- `widget.html` / `js/widget.js` / `css/widget.css` — status + "Lock now" + settings overlay.
- `settings.html` / `js/settings.js` / `css/settings.css` — standalone settings page.
- `js/settings-form.js` / `css/form.css` — the settings form shared by both the widget overlay
  and the settings page (same plugin origin → one shared script instead of duplicated markup).
- `locales/en.json5` / `locales/vi.json5` — UI strings (`widget.*` / `settings.*`).
- `icon.svg` — padlock carrying two eyes.

## Default settings

- `hotkey` — `"Ctrl+Alt+L"` (global shortcut to lock)
- `autoLock` — `true` (auto-lock when idle)
- `idleMinutes` — `5`
- `maxAttempts` — `3` (wrong tries before a lockout)
- `lockoutSeconds` — `15`
- `coverAllMonitors` — `true`
- `passwordHash` / `pwSalt` — `""` (set via Settings; blank = unlock is free)

## Test

Open Kazuo AI → Plugin Manager — the plugin appears automatically → Install → Enable. Trigger with
the **Lock now** button, `Ctrl+Alt+L`, or by staying idle for `idleMinutes`. With no password set,
press Enter on the lock screen to unlock.

After editing `main/*.ts`, recompile before testing: `npx tsc -p tsconfig.plugins.json` (from the
project root). `lock.html/css/js` are static and are not compiled.


---

# Distributed agent orchestration / Điều phối agent phân tán
<!-- id: distributed-orchestration source: .claude/features/distributed-agent-orchestration.md -->

# Điều phối agent phân tán

> A manager agent delegates to agents on other machines through a dispatch tool and the relay; how jobs are tracked and results returned.

# Distributed Agent Orchestration (Manager Role chia việc đa thiết bị)

## Mục đích

Cho phép một **Agent Role "Manager"** (một phiên `ai-chat`) **tự chẻ việc** rồi giao mỗi việc con cho
một **agent Claude Code tự chủ** chạy trên **máy hiện tại (local)** hoặc **máy khác của cùng tài khoản**
(remote, qua fleet relay). Kết quả gom về, Manager tổng hợp. Song song = Manager gọi `dispatch_agent`
nhiều lần trong một lượt.

Phạm vi build: **Sub 1 (nền tảng dispatch) + Sub 2 (tool orchestration)**. Xem plan
`plans/2026-07-15-distributed-agent-orchestration/`.

## Kiến trúc (async job + poll)

```
  MÁY A (Manager, ai-chat)            fleet-api (relay, đã có)        MÁY B (worker)
 ┌─────────────────────────┐         ┌──────────────────┐          ┌──────────────────────────┐
 │ agent-role MCP tools:    │         │ RelayDeviceDO(B) │          │ dashboard-server          │
 │  list_devices            │ POST    │ /d/<B>/api/*     │  tunnel  │  handleApiRoute:          │
 │  dispatch_agent ─────────┼─relay──►│ (đã tunnel /api) │─────────►│   POST /agent/dispatch    │
 │  agent_status            │         └──────────────────┘          │    → job nền              │
 │  agent_result (poll) ◄───┼─ GET /agent/result?jobId ────────────│    invokeHandler(         │
 │                          │                                       │      plugin:ai-chat:      │
 │ local: __kazuoAiChat     │                                       │      run-agent)           │
 │        .runAgent() ──────┼── in-process (không qua relay) ──────►│  (chạy trên máy B)        │
 └─────────────────────────┘                                       └──────────────────────────┘
```

- **Async**: `POST /agent/dispatch` khởi job nền, trả `{jobId}` NGAY (không giữ HTTP request lâu qua
  Cloudflare). `GET /agent/status|result?jobId=` poll bằng request ngắn.
- **Local** (máy A tự chạy): `dispatch_agent` gọi thẳng `globalThis.__kazuoAiChat.runAgent` in-process,
  KHÔNG qua relay.
- **Remote**: `dispatch_agent` gọi `POST ${FLEET}/d/<device>/api/agent/dispatch` (Bearer accountToken).

## Files

**Worker (Electron main):**
- `electron/dashboard-server.ts` — job store `agentJobs` (Map, TTL 30') + `newAgentJobId()`
  (`randomBytes`) + `pruneAgentJobs()`; 3 case trong `handleApiRoute`: `POST /agent/dispatch`
  (fire-and-store `invokeHandler('plugin:ai-chat:run-agent', opts)`, unwrap `{result,found}`), `GET
  /agent/status`, `GET /agent/result`. cwd rỗng → `process.cwd()`; validate `fs.existsSync`.
- `electron/store.ts` — `AppConfig.acceptRemoteDispatch: boolean` (default `true`) — kill-switch nhận việc.

**Orchestrator (plugin agent-role):**
- `plugins-library/agent-role/main/index.ts` — `getMcpTools` export 4 tool: `list_devices`,
  `dispatch_agent`, `agent_status`, `agent_result`. Job registry cục bộ `dispatchJobs` (local + remote).
  Helper: `fleetFetch` (Bearer accountToken), `resolveRole` (id/name → systemPrompt+plugins+
  toolProfile+toolOverrides từ settings máy A), `selfDeviceId`, `accountToken`. jobId = `crypto.randomUUID`.
  Nhánh remote của `dispatch_agent` gửi `toolProfile`/`toolOverrides` trong body (by value) — xem
  `agent-role-tool-profiles.md`.
- `plugins-library/agent-role/package.json` — thêm `zod` (host chạy `npm install --omit=dev` khi cài plugin).

**Auto-log Task Manager:** `dispatch_agent` tự tạo 1 task trong `task-manager` khi phóng việc (status
`in_progress`, title = tóm tắt task, agentName = device/role) và tự cập nhật `completed`/`cancelled` +
comment khi job xong — KHÔNG phụ thuộc agent nhớ gọi `task_create`. Ghi trực tiếp qua
`pluginControl.getPluginSettingsFor/setPluginSettingsFor('task-manager')` (best-effort, no-op nếu
task-manager chưa bật). Xem `tmCreate`/`tmFinish`.

**Xem chi tiết agent (nút "Xem" trong Task Manager):** mỗi dispatch LOCAL lưu `conversationId` = sessionId
của worker + `cwd` vào task. Widget task-manager hiện nút **Xem** (khi có `conversationId`+`cwd`) →
`invoke('plugin:show-on-overlay','ai-chat')` (hiện widget ai-chat, reuse của Launcher) +
`invoke('plugin:ai-chat:reveal-session', {cwd, sessionId, configDir})`. ai-chat main re-broadcast
`{type:'reveal-session', cfg}` → widget ai-chat `revealSession()` mở/focus đúng phiên (full tool use +
thinking, tận dụng render sẵn). **Chỉ local** — remote worker chạy phiên trên máy khác nên không mở được
tại đây.

**Xem LIVE (lúc worker đang chạy):** dispatch local truyền `opts.tabId = 'dispatch:'+jobId` cho `runAgent`
+ lưu `task.liveTabId`. Nút "Xem live" (khi task `in_progress`) → `revealSession({liveTabId, cwd})` →
`attachLiveTab()` tạo 1 **tab view-only** (`t.viewOnly=true`) khớp tabId, KHÔNG gọi open-tab/connect →
event broadcast của worker (route theo tabId) render **realtime** vào tab. Guard: tab viewOnly khoá ô nhập
+ chặn `sendMessage` (tránh spawn agent trùng tabId); `closeTabUI` KHÔNG gọi `close-tab` cho viewOnly
(đóng tab live không giết worker); nút Stop vẫn cho phép interrupt worker. Giới hạn: mở muộn thì mất event
trước đó (xem từ lúc mở).

## Tab mở bằng code kế thừa `sessionDefaults` (fix lỗi "OAuth session expired")

`openTab` (chat-manager) trước đây chỉ có hard default khi caller không truyền: `envProfileId='auto'`,
model `sonnet`, mode `bypassPermissions`. Với người dùng chạy **env profile proxy** (vd "SMIT Router"),
mọi tab mở bằng code — **khung chat embed (Orchestrator, cron-job) VÀ worker dispatch** — lại chạy bằng
đăng nhập **OAuth mặc định**; OAuth hết hạn → `Failed to authenticate: OAuth session expired`, trong khi
chat tay của người dùng vẫn chạy bình thường (khó lần ra).

Nay `openTab` fallback vào **`sessionDefaults`** của chính người dùng (`envProfileId` → `model` → `mode`
→ `contextSuffix`) qua helper `tabDefaults()`. Tab mở tự động vì thế hành xử như tab người dùng tự mở.
**Lưu ý còn lại:** `runAgent` vẫn truyền `model`/`mode` tường minh (`DEFAULT_MODEL='sonnet'`), nên worker
dispatch chạy `sonnet` trừ khi caller chỉ định model khác — chỉ `envProfileId` là kế thừa.

## Bảo mật & gating (chốt)

- **POST /agent/dispatch** kế thừa gate có sẵn: `dashboard-server` chặn MỌI `POST /api/*` thiếu
  `Authorization: Bearer <dashboardToken>` (local) / appToken owner (qua relay) **trước** `handleApiRoute`.
- Thêm kill-switch `acceptRemoteDispatch !== false` (mặc định on) — đặt `false` để máy này từ chối nhận việc.
- **Remote** qua relay: fleet verify appToken + `device.account_id === accountId` (org-ownership) — nên chỉ
  máy của chính tài khoản mới dispatch được cho nhau. Đúng chủ trương "tất cả máy của mình + auto-trust".
- **Bridge server KHÔNG** dùng `handleApiRoute` (nó có bảng route riêng) → 3 route agent chỉ hiện
  trên dashboard server/relay, không lộ thêm qua bridge loopback.
- `GET /agent/status|result` đi qua cùng lớp bắt dashboard token như mọi `/api/*` (kể cả GET); jobId ngẫu
  nhiên + không CORS-read + relay đã auth là các lớp bổ sung.

## Dev Mode — KHÔNG cần

Verify khi build: đường MCP của ai-chat (`chat-manager.ts` `connectAgentFor` →
`buildPluginControlMcpServers`) **không** gate theo Dev Mode (không có ref `devMode` nào trong
`plugins-library/ai-chat/main/` hay `electron/plugin-host.ts`). Tool nạp khi plugin **được attach vào
bundle của session**. Do đó 4 tool orchestration có sẵn **bất kể Dev Mode on/off**, miễn role Manager
bundle `agent-role`. (README ai-chat ghi "Dev Mode only" đã lỗi thời cho phần này.)

## Cách dùng — tạo role Manager

1. Bật plugin **agent-role** (và **ai-chat**, **task-manager**).
2. Trong widget agent-role, tạo role "Manager": bundle plugin gồm `agent-role` (bắt buộc — để có tool) +
   `task-manager` (để track). systemPrompt gợi ý:
   > Bạn là Manager điều phối. Chẻ yêu cầu thành các việc con ĐỘC LẬP. Với mỗi việc gọi `dispatch_agent`
   > (đặt `device` nếu cần chạy máy khác — dùng `list_devices` để xem máy online). Gọi nhiều
   > `dispatch_agent` trong một lượt để chạy song song. Sau đó `agent_result(jobId)` từng việc, tổng hợp
   > kết quả. Dùng task-manager để ghi tiến độ.
3. Trong **ai-chat**, gán role Manager cho một phiên → chat giao việc lớn.

## Giới hạn đã biết

- **Máy B cần `claude` đã đăng nhập riêng** + cwd hợp lệ (mỗi máy 1 ghế subscription).
- **cwd cross-OS chưa auto-map** — truyền cwd đúng OS máy B, hoặc để rỗng (dùng project root máy B).
- **Role không đồng bộ giữa máy** — Manager resolve role→systemPrompt+plugins ở MÁY A rồi truyền
  `systemPrompt`/`attachedPlugins` sang worker; plugin attach chỉ hiệu lực nếu plugin đó cũng bật ở máy B.
  Hồ sơ tool (`toolProfile`/`toolOverrides`, xem `agent-role-tool-profiles.md`) đi theo đúng cách này —
  by value, không phải id — từ fix 2026-09-28: trước đó remote dispatch không truyền hồ sơ gì cả nên
  worker remote luôn chạy full quyền bất kể role khai `orchestrator`/`worker`.
- **Headless (Linux/WSL) chưa có relay-agent** (xem `multi-device-relay.md`) → máy B chạy bằng
  `npm run headless` chưa nhận remote dispatch. Máy B GUI OK — kể cả GUI trên Linux: lần verify
  2026-09-10 dispatch sang một máy `os: linux` qua relay chạy được, nên hạn chế này là ở **chế độ
  headless**, không phải ở hệ điều hành.
- **Ngoài phạm vi:** device-affinity/capability routing tự động, retry/hồi phục worker chết, UI tiến độ
  realtime, cột `device` trong task-manager, cap song song.

## Kết quả verify runtime (2026-09-10)

Chạy trên app thật đang mở, không khởi động lại. Toàn bộ qua REST để tách phần hạ tầng ra khỏi phần
MCP tool của `agent-role`.

| Việc | Kết quả |
|---|---|
| Local: `POST /api/agent/dispatch` → `{jobId}` → `GET /api/agent/result` | `{status:'done', ok:true, text:'ORCHESTRATION-OK'}` |
| Local fan-out 2 job song song | Cả hai `done`, `sessionId` khác nhau, mỗi job trả đúng chuỗi của nó |
| Relay tunnel A→B (truy vấn vô hại trước) | `GET /d/<B>/api/agent/status?jobId=<không tồn tại>` → HTTP 200 `{status:'not_found'}` — máy B trả lời, không phải máy A |
| **Remote thật 2 máy** A(win32) → B(linux) | `{status:'done', ok:true, text:'REMOTE-DEVICE-B-OK'}` |
| Job chạy đúng trên B, không phải A | `status.device` = id máy B; cùng `jobId` tra trên máy A → `not_found` |

Xác thực: local dùng `dashboardToken`, remote dùng `accountToken` qua `https://fleet.kaiitech.net/d/<deviceId>/api/*`.

Chưa verify bằng runtime: đường **MCP tool** (`dispatch_agent`/`agent_result` của `agent-role`) — mới
chỉ verify lớp REST mà các tool đó gọi xuống — và **live view**, vì cả hai đều cần một agent Manager
thật gọi MCP tool. Route REST `POST /api/agent/dispatch` không nhận `tabId` nên không dựng được live
tab qua đường đó; đúng thiết kế, live view chỉ dành cho worker local.

Live view bản thân nó **đã cài đặt xong** từ 2026-07-17 (commit `2e589c7`) và **đã verify chạy thật**
2026-09-10: gọi `reveal-session {cwd, liveTabId}` tạo tab `viewOnly` đúng như thiết kế —
`sessionId: null`, `disconnected`, composer khoá ở đúng pane, gọi lần hai chỉ focus lại. Quan trọng
hơn: mở khoá composer rồi cố gửi tin vẫn **không** spawn agent nào, tức chặn nằm ở tầng logic chứ
không chỉ ở UI. Bảng chi tiết trong `plans/2026-07-15-distributed-agent-orchestration/phase-04-live-view.md`.

## Test

- **Local (1 máy):** bật ai-chat+agent-role+task-manager → tạo role Manager → giao 1 việc chia được 2 phần
  → Manager gọi `dispatch_agent` 2 lần (local) → `agent_result` từng jobId → gom kết quả.
- **REST trực tiếp:** `POST /api/agent/dispatch` (dashboard server, loopback) (kèm `Authorization: Bearer
  <dashboardToken>`, body `{"task":"...","timeoutMs":60000}`) → `{jobId}`; `GET
  /api/agent/result?jobId=<id>` → `{status:'done', ok, text}`.
- **Remote (2 máy):** cả 2 online + đăng nhập cùng account; Manager `dispatch_agent({device:B,...})` →
  `agent_result` poll → kết quả từ máy B.
- Sau khi sửa `main/*.ts`: `npx tsc -p tsconfig.plugins.json` (plugin) / `tsc -p tsconfig.node.json`
  (electron); cài lại/đồng bộ plugin bản chạy (host `npm install` zod).


---

# Orchestrator: the dispatch console / Orchestrator: bàn điều khiển giao việc
<!-- id: orchestrator source: docs/wiki/orchestrator.md -->

# Orchestrator: bàn điều khiển giao việc

> Chat with the coordinator next to online devices and running tasks; a persistent task backend with leases, a side-effect ledger, a git broker and approvals.

# Orchestrator: bàn điều khiển giao việc / Orchestrator: the dispatch console

## Tiếng Việt

**Mục đích.** Một khung duy nhất để nói chuyện với **agent điều phối** (một agent-role đóng vai quản lý) và đồng thời thấy **thiết bị nào online** và **task nào đang chạy**. Trước đó phải mở ai-chat, tự nhớ chọn phiên đã gán role quản lý, rồi mở riêng Task Manager và Device Manager để theo dõi.

**Ghép từ các plugin có sẵn, không nhân bản code.** Widget gồm ba vùng dock kéo thả được: danh sách thiết bị (từ `device-manager`), danh sách task (từ `task-manager`) và khung chat (UI chat tái dùng của `ai-chat`, ghim vào agent điều phối đã chọn). Các vùng được "nhận nuôi" vào bố cục dock chứ không dựng lại, vì dựng lại khung chat đang sống nghĩa là mất phiên.

**Backend lưu task bền vững** (SQLite trong main process), xây dần theo từng lát cắt:

1. **Máy trạng thái + kho task**: task có vòng đời rõ ràng, mọi chuyển trạng thái ghi thành sự kiện kèm lý do; truy vết một việc bằng một lần đọc.
2. **Thuê tài nguyên (lease)**: môi trường nào đang bị task nào chiếm; khởi động lại thì **đối chiếu** (reconcile) với thực tế thay vì tin bảng; tắt plugin thì xả (drain) có thời hạn; luôn có đường bỏ việc.
3. **Sổ cái tác động ngoài**: commit, push, tin nhắn đã gửi được ghi lại trước khi làm, để khởi động lại không làm lại việc đã xảy ra.
4. **Chọn provider/model**: mặc định chung cộng ghi đè theo task; không có thì **từ chối** chứ không tự thay thế.
5. **Giao việc thật**: giao cho agent chạy trong môi trường đã thuê, thu kết quả, chuyển trạng thái.

**Những cơ chế đáng chú ý:**

- **Git broker**: mỗi task làm việc trong worktree riêng của từng repo trong môi trường, chỉ được dùng một danh sách lệnh git cho phép, có cổng kiểm chỉ-đọc trước khi tích hợp, merge phải được duyệt, không bao giờ push hộ. Hỗ trợ repo lồng nhau (repo thứ hai nằm trong repo ngoài và bị gitignore). Xoá worktree theo thứ tự lồng trước, ngoài sau vì làm ngược lại là phá hoại đo được.
- **Phê duyệt có ràng buộc nội dung**: ghi lại *cái gì* đã được duyệt, không chỉ *đã duyệt hay chưa*; nội dung đổi thì duyệt cũ vô hiệu. Kênh Telegram **khoá mặc định**; token bot được mã hoá bằng kho khoá của hệ điều hành, không nằm trong settings, giao diện chỉ thấy trạng thái.
- **Bước kiểm chứng thật**: điều phối viên tự chạy lệnh kiểm chứng của môi trường và quan sát mã thoát; trạng thái "đang kiểm chứng" thật sự kiểm chứng điều gì đó.
- **Xác minh môi trường (attest)**: lease chưa hết hạn không có nghĩa tiến trình vẫn đúng chỗ; hỏi lại hệ điều hành, fail closed.
- **Chỉ mục tài liệu chỉ giơ tay**: gắn cờ tài liệu trùng tên khác nội dung hoặc lâu không đổi; không bao giờ tự sửa.
- **Dọn output hết hạn là cách ly, không xoá**: chuyển vào vùng cách ly, chứng minh đã chuyển đúng tệp bằng danh tính tệp, không có lệnh xoá nào.
- **Kiểm tra tài nguyên trước khi khởi môi trường**: RAM, đĩa; thiếu thì từ chối tất cả môi trường được hỏi.
- **Vòng tự giao việc** (việc đã duyệt tự chạy khi môi trường rảnh): **mặc định tắt**, bật có chủ đích.
- **Công cụ MCP cho điều phối viên**: tạo/duyệt/giao/huỷ task, hỏi năng lực, xem kết quả kiểm chứng, tất cả qua một đường giao việc duy nhất.

**Giới hạn.** Cần `ai-chat`; thiếu `device-manager` hoặc `task-manager` thì hai pane hiện gợi ý bật plugin, phần chat vẫn dùng được. Các thông số ngưỡng (bao lâu tài liệu bị coi là cũ, output hết hạn sau bao lâu, RAM/đĩa tối thiểu) là giá trị khởi điểm để người dùng chỉnh.

## English

**Purpose.** One frame to talk to the **coordinating agent** (an agent-role acting as manager) while seeing **which devices are online** and **which tasks are running**. Before, you had to open ai-chat, remember which session carried the manager role, and open Task Manager and Device Manager separately.

**Composed from existing plugins, no duplicated code.** The widget has three dockable regions: the device list (from `device-manager`), the task list (from `task-manager`) and the chat (ai-chat's reusable chat UI pinned to the chosen coordinator). Regions are *adopted* into the dock layout rather than rebuilt, because rebuilding a live chat frame means losing the session.

**A persistent task backend** (SQLite in the main process), built in slices:

1. **State machine + task store**: tasks have an explicit lifecycle, every transition is an event with a reason; a task can be traced with one read.
2. **Resource leases**: which environment is held by which task; on restart the store is **reconciled** against reality instead of trusted; on plugin shutdown leases drain with a deadline; there is always a way to abandon work.
3. **Side-effect ledger**: commits, pushes and sent messages are recorded before they happen, so a restart never repeats what already happened.
4. **Provider/model selection**: a shared default plus per-task overrides; when nothing fits the task is **refused**, never silently substituted.
5. **Real dispatch**: hand the work to an agent inside the leased environment, collect the result, advance the state.

**Mechanisms worth knowing:**

- **Git broker**: each task works in its own worktree per repository of the environment, may only use an allow-list of git commands, passes a read-only integrability gate, merges require approval, and nothing is ever pushed on your behalf. Nested repositories (a second repo inside the outer one, gitignored) are supported. Worktrees are removed inner-first, because the opposite order is measurable damage.
- **Content-bound approvals**: record *what* was approved, not just *that* it was; if the content changes the old approval is void. The Telegram channel is **off by default**; the bot token is encrypted with the OS key store, never kept in settings, and the UI only shows status.
- **A real verification step**: the coordinator runs the environment's verification command and reads the exit code, so "validating" actually validates something.
- **Environment attestation**: an unexpired lease does not prove the process is still the right one; ask the OS, fail closed.
- **A document index that only raises its hand**: flags documents with the same name but different content, or untouched for too long; never edits anything.
- **Expired output is quarantined, never deleted**: files are moved to a quarantine area, the move is proven by file identity, and there is no delete command.
- **Capacity preflight** before starting an environment: RAM and disk; if short, every requested environment is refused.
- **Self-dispatch loop** (approved work runs when an environment is free): **off by default**, enabled deliberately.
- **MCP tools for the coordinator**: create/approve/dispatch/cancel tasks, query capacity, read verification results, all through a single dispatch path.

**Limits.** Requires `ai-chat`; without `device-manager` or `task-manager` the two panes show a hint and the chat still works. Threshold settings (when a document counts as stale, when output expires, minimum RAM/disk) are starting values for the user to tune.


---

# Agent roles and tool profiles / Agent role và hồ sơ công cụ
<!-- id: agent-role source: .claude/features/agent-role-tool-profiles.md -->

# Agent role và hồ sơ công cụ

> Each agent role loads only the tools it needs; measured before/after on coordinator and worker roles.

# Hồ sơ công cụ theo AgentRole (tool profiles)

**Ngày:** 2026-09-15 · **Trạng thái:** đã cài đặt, chờ khởi động lại Kazuo để có hiệu lực

## Vấn đề

Một role điều phối game nạp **71 công cụ / 182 KB mô tả mỗi lượt chat**, trong khi 12 phiên thật chỉ dùng
6 công cụ. Hai hậu quả: mỗi lượt im lặng khá lâu trước chữ đầu tiên, và điều phối viên luôn *có*
`Write`/`Edit`/`Agent` trong tay dù system prompt cấm nó tự sửa code.

## Cách hoạt động

Mỗi role chọn một **hồ sơ**. Hồ sơ suy ra hai thứ mà Agent SDK nhận:

| | Ý nghĩa |
|---|---|
| `tools` | Tập **công cụ gốc**. Theo type của SDK: *"the base set of available built-in tools"* — **không đụng tới công cụ MCP**, nên bộ plugin của role (`dispatch_agent`…) vẫn chạy dưới mọi hồ sơ. |
| `settingSources` | Nạp cấu hình từ nguồn nào trong `user` / `project` / `local`. Là **mảng ba nguồn, không phải công tắc** — nhờ vậy Thợ giữ được MCP Unity của chính project (`project`) trong khi bỏ MCP trình duyệt/ảnh toàn máy, danh mục skill và CLAUDE.md (đến từ `user`). |

### Ba hồ sơ

| Hồ sơ | Giữ | Bỏ | `settingSources` |
|---|---|---|---|
| **full** *(mặc định)* | tất cả — y như trước | — | không đổi |
| **orchestrator** | `Bash`, `PowerShell`, `Read`, `AskUserQuestion` + MCP theo `role.plugins` | `Write`, `Edit`, `Agent`, `Workflow`, trình duyệt, ảnh, skill, CLAUDE.md | `[]` |
| **worker** | `Read`, `Write`, `Edit`, `NotebookEdit`, `Glob`, `Grep`, `Bash`, `PowerShell`, `WebFetch`, `WebSearch`, `Monitor`, `TaskOutput`, `TaskStop`, `EnterPlanMode`, `ExitPlanMode` | `AskUserQuestion` (chạy không người trực → hỏi là treo tới hết giờ), `Agent` (một việc không được đẻ thêm việc), trình duyệt, ảnh, skill, CLAUDE.md | `['project']` — chính là nơi có MCP Unity |

**`full` là mặc định và không đổi gì.** Role không khai `toolProfile` (hoặc khai tên lạ) → trả về rỗng
và mọi thứ giữ nguyên. Đây là ràng buộc tương thích ngược cứng: 7 role sẵn có không được đổi hành vi.

### Tùy chỉnh nâng cao

`toolOverrides: { add: [], remove: [] }`, áp **sau** hồ sơ, `remove` thắng `add`. Chỉ có tác dụng khi
đã chọn một hồ sơ khác `full` — nên ô nhập trong giao diện chỉ hiện ra lúc đó, thay vì nhận vào rồi
âm thầm không làm gì.

## Nơi nó được diễn giải — một chỗ duy nhất

`connectAgentFor()` trong `plugins-library/ai-chat/main/chat-manager.ts` là chỗ **vốn đã** tra cứu
role (để lấy system prompt + bộ plugin), nên hồ sơ cũng được diễn giải tại đó. Vì vậy:

- `dispatch_agent` (worker **local**) truyền `attachedAgentId` (id role đã tra được) thay vì chỉ
  truyền prompt + plugins. Việc tra `attachedAgentId` → hồ sơ diễn ra **trên máy chạy worker** — với
  local, đó là cùng một máy đã tra role, nên luôn tìm thấy.
- Một phiên chat ghim role và một worker local được giao việc vào role đó **dùng chung một định nghĩa**.
- Phương án "dispatch tự tra hồ sơ rồi truyền `tools`" đã bị loại: nó tạo nguồn sự thật thứ hai.

### Worker **remote** (qua relay) — hồ sơ truyền BY VALUE, không truyền `attachedAgentId`

Sửa 2026-09-28: `dispatch_agent` nhánh remote trước đây quên truyền cả `attachedAgentId` lẫn hồ sơ —
worker ở máy khác chạy **không giới hạn tool nào** (bug, xem báo cáo debug ngày 2026-09-28). Không thể
fix bằng cách đơn giản là thêm `attachedAgentId` vào body remote như nhánh local, vì **role không đồng
bộ giữa máy** (xem `distributed-agent-orchestration.md`): id đó có thể không tồn tại trên máy đích
(im lặng rơi về "full" — đúng bug đang sửa) hoặc tệ hơn, trùng id với một role KHÁC không liên quan
trên máy đích, áp nhầm hồ sơ/systemPrompt của người ta.

Thay vào đó, máy A (nơi role thật sự được khai) tự tra `toolProfile`/`toolOverrides` của role rồi gửi
**by value** trong body của `POST /agent/dispatch` — cùng cách `systemPrompt`/`attachedPlugins` đã làm.
Máy B áp thẳng cặp giá trị này, không tra role nào theo id.

- `plugins-library/agent-role/main/index.ts`: `resolveRole()` trả thêm `toolProfile`/`toolOverrides`;
  `dispatch_agent` nhánh remote thêm `rbody.toolProfile`/`rbody.toolOverrides` (nhánh local giữ nguyên
  `attachedAgentId`, không đổi).
- `electron/dashboard-server.ts` `POST /agent/dispatch`: forward `body.toolProfile`/`body.toolOverrides`
  vào `opts.toolProfile`/`opts.toolOverrides` của `RunAgentOptions`.
- `plugins-library/ai-chat/main/chat-manager.ts`: `RunAgentOptions`/`TabState`/`openTab()` thêm
  `toolProfile`/`toolOverrides`. `connectAgentFor()` dùng `resolveToolProfileFor()` (mới, trong
  `tool-profiles.ts`) thay vì gọi `resolveToolProfile(agent.toolProfile, ...)` trực tiếp: nếu tab có
  `toolProfile` tường minh (remote dispatch) thì **thắng tuyệt đối**, không gộp với role tra được cục
  bộ — tránh đúng kiểu va chạm id nói trên. Tab local/UI bình thường không đặt `t.toolProfile` nên hành
  vi cũ (tra qua `agent`) giữ nguyên 100%.
- `plugins-library/ai-chat/main/tool-profiles.ts`: thêm `resolveToolProfileFor(explicit, role)` — hàm
  thuần, có test trong `tool-profiles.test.ts`.

**Không phải "role không tồn tại trên máy đích → cấp full quyền" nữa.** Máy đích giờ không tra role
theo id cho đường remote — nó chỉ áp đúng hồ sơ mà máy A đã tính sẵn. Nếu role không khai `toolProfile`
(dùng `full`), remote worker vẫn `full` như trước — không đổi hành vi cho các role hiện có.

## Files

- `plugins-library/ai-chat/main/tool-profiles.ts` — module **thuần**, định nghĩa hồ sơ + `resolveToolProfile()`
- `plugins-library/ai-chat/test/tool-profiles.test.ts` — 15 test
- `plugins-library/ai-chat/main/chat-manager.ts` — áp hồ sơ trong `connectAgentFor()`; `AgentBundle` thêm `toolProfile`/`toolOverrides`
- `plugins-library/agent-role/main/index.ts` — `resolveRole()` trả thêm `id`; `dispatch_agent` truyền `attachedAgentId`
- `plugins-library/agent-role/widget.html` + `js/widget.js` + `locales/{vi,en}.json5` — ô chọn hồ sơ trong trình sửa role

## Đo thật sau khi áp (2026-09-16)

Đo bằng cách cho mỗi role chạy thật một lần rồi tự liệt kê công cụ của nó — không ước lượng.

| Role | Trước | Sau | Ghi chú |
|---|---|---|---|
| role điều phối | 71 | **14** | 4 công cụ gốc + 10 MCP của chính nó |
| role thợ | 71 + MCP dự án | **88** | trong đó **54 là Unity MCP** — thợ vẫn gọi được đúng môi trường của nó |

Thợ nhiều hơn điều phối viên là **đúng thiết kế**: nó giữ `settingSources: ['project']` nên còn nguyên
Unity MCP và wiki arkon của chính dự án. Cái bị cắt là MCP toàn máy (trình duyệt 29, ảnh 3), danh mục
skill và CLAUDE.md — khoảng 32 công cụ cộng ~92 KB mô tả mỗi lượt.

Tiêu chí nghiệm thu 1-6 của báo cáo brainstorm đến đây đã đủ: role không khai hồ sơ thì không đổi;
điều phối viên giảm mạnh mà vẫn giao được việc đầu-cuối; thợ vẫn gọi được Unity MCP; `toolOverrides`
có test; module hồ sơ là thuần và có test; số trước/sau đã đo chứ không ước lượng.

## Giới hạn phải nói rõ

**Đây KHÔNG phải ranh giới an toàn.** Một worker vẫn còn `Bash` thì vẫn ghi được file dù đã cắt
`Write`. Cắt công cụ **thu hẹp** cơ hội làm sai và giảm chi phí mỗi lượt; cưỡng chế thật cần
PreToolUse hook (xem `tool-policy.ts`, `buildReadOnlyReviewPolicy`). Không được mô tả tính năng này
như một cơ chế bảo vệ.

Năm công cụ `Monitor`/`TaskOutput`/`TaskStop`/`EnterPlanMode`/`ExitPlanMode` được **giữ lại có chủ ý**
cho Thợ: mẫu dữ liệu sạch duy nhất là các việc chỉ-đọc, nên cắt chúng lúc này là đoán. Đo lại sau khi
có việc code thật.

## Hiệu lực

Thay đổi nằm trong `main/*.js` của ai-chat và agent-role — **không reload được** (reload `ai-chat`
sẽ giết mọi phiên Claude đang chạy). Hồ sơ chỉ có hiệu lực **từ lần khởi động Kazuo kế tiếp**.


---

# Task Manager: the central task store / Task Manager: kho công việc trung tâm
<!-- id: task-manager source: .claude/features/task-manager-plugin.md -->

# Task Manager: kho công việc trung tâm

> Create and update tasks from the widget, from other plugins via invoke, or from AI agents via MCP.

# Task Manager plugin (plugins-library/task-manager)

## Mục đích

Kho **task trung tâm** cho toàn app. Một task gồm: `taskId`, `conversationId`, `providerName`,
`agentName`, `title`, `desc`, `status`, `comment` (+ `createdAt`/`updatedAt`). Task được tạo/cập nhật
từ 3 nguồn:

1. **Widget** của chính plugin (form tạo thủ công, đổi status, sửa comment, xóa).
2. **Plugin khác** gọi vào qua `invoke('plugin:task-manager:*', ...)` — giống cách plugin `notification`
   cho gọi `plugin:notification:show`. Đây là kênh Agent Review dùng để đẩy session thành task.
3. **AI agent của ai-chat** qua **MCP tools** `task_create` / `task_update` / `task_list` (chỉ khi
   Dev Mode bật) — khi Claude quản lý task trong lúc chat thì ghi thẳng vào kho này.

Loại plugin: `backend` (có `main/` chạy trong Electron main process để đăng ký IPC channel dùng chung
+ giữ store bền vững).

Status hợp lệ: `pending` / `in_progress` / `completed` / `cancelled` (giá trị khác bị ép về `pending`).

## File liên quan

- `plugins-library/task-manager/manifest.json` — `mainEntry = "main/index.js"`,
  `defaultSettings = { tasks: [], hideCompleted: false }`, `defaultWidgetConfig = 780x580 @ (80,80)`.
- `plugins-library/task-manager/main/index.ts` (+ `main/index.js` đã compile) — backend: store + IPC +
  MCP tools. **Sửa `.ts` xong phải chạy lại `npx tsc -p tsconfig.plugins.json`.**
- `plugins-library/task-manager/package.json` — chỉ khai báo `zod` (dùng cho MCP tools; host chạy
  `npm install --omit=dev` khi cài plugin). Thiếu zod thì `getMcpTools` trả `[]`, phần còn lại vẫn chạy.
- `plugins-library/task-manager/widget.html` + `js/widget.js` + `css/widget.css` — UI: toolbar (lọc theo
  status + nút "+ New"), form thêm task, danh sách task (đổi status, sửa comment, xóa), overlay Settings.
- `plugins-library/task-manager/settings.html` + `js/settings.js` + `css/settings.css` — 1 checkbox
  `hideCompleted`, dùng bởi Plugin Manager và cửa sổ pop-out (trùng lặp có chủ đích với overlay trong widget).
- `plugins-library/task-manager/locales/en.json5` + `vi.json5` — chuỗi UI, namespace `widget.*` /
  `filter.*` / `status.*` / `settings.*`.

## Cách hoạt động

### Lưu trữ

Task được lưu trong **settings slice của chính plugin** (`ctx.getSetting('tasks')` /
`ctx.setSettings({ tasks })`), KHÔNG dùng file riêng. Lý do:

- Bền vững qua restart app và qua nâng cấp plugin (settings nằm trong ConfigStore của app, không bị
  ghi đè khi copy lại thư mục plugin lúc cài).
- Mỗi `setSettings` tự bắn `settingsChanged` → widget nghe event này để tự refresh, không cần
  `broadcast` custom.

### IPC channels (điểm cốt lõi — mở cho mọi caller)

`list` / `get` / `upsert` / `update` / `remove` **cố tình KHÔNG dùng `ensureIsSelf`** để plugin khác
gọi được (giống `plugin:notification:show`). Chỉ `clear` là self-gated (phải truyền `'task-manager'`).

```js
// Tạo mới (không có taskId) hoặc cập nhật (taskId đã tồn tại). Trả về task đã lưu.
await window['kazuo-ai'].invoke('plugin:task-manager:upsert', {
  taskId: 'session:<id>',        // tùy chọn — có thì upsert theo id (idempotent)
  conversationId: '<id>', providerName: 'claude-code', agentName: '',
  title: '...', desc: '...', status: 'pending', comment: '',
});
await window['kazuo-ai'].invoke('plugin:task-manager:update', { taskId, patch: { status: 'completed' } });
await window['kazuo-ai'].invoke('plugin:task-manager:remove', taskId);
const tasks = await window['kazuo-ai'].invoke('plugin:task-manager:list', { status: 'pending' }); // status optional
```

- `upsert`: có `taskId` khớp → merge (chỉ ghi đè field được truyền); không có/không khớp → tạo mới với
  `taskId` sinh tự động (`t_<base36 time>_<rand>`), `unshift` lên đầu.
- `update`: patch theo `taskId`, trả `null` nếu không tìm thấy.

### MCP tools (`getMcpTools`, Dev Mode only)

Export `task_create` / `task_update` / `task_list` bằng `ctx.modules.claudeAgent.tool(...)`. Host tự
thêm tiền tố → agent thấy `task-manager_task_create`... Chúng gọi CÙNG hàm `upsertTask`/`updateTask`
với IPC nên UI và AI chia sẻ đúng một store. `zod` require lazily, thiếu → trả `[]` (không vỡ `activate`).

### Widget

- Đọc task qua `plugin:task-manager:list`; nghe `settingsChanged` để cập nhật khi task đổi (kể cả do
  plugin khác/AI ghi vào). Mọi thao tác dựng bằng DOM API (`textContent`) nên nội dung task không bị
  chèn thẳng vào HTML.
- Lọc theo status; `hideCompleted` ẩn task `completed`/`cancelled` khi đang xem "All".

## Lưu ý / giới hạn

- Không chống đua ghi đồng thời phức tạp: mỗi handler đọc → sửa → `setSettings` trong 1 lượt sync
  (main process 1 luồng) nên đủ an toàn cho quy mô vài chục–vài trăm task (KISS). Không dành cho hàng
  chục nghìn task.
- MCP tools chỉ có tác dụng khi Dev Mode bật và agent kết nối lại (gate tính lại mỗi lần connect —
  giống các plugin MCP khác). Người dùng thường không cho AI đụng store qua đường này.
- `conversationId`/`providerName`/`agentName` chỉ là field lưu trữ — plugin không tự suy ra, do caller
  (Agent Review, AI, hoặc người dùng) cung cấp.


---

# Multi-device relay through Cloudflare / Relay nhiều máy qua Cloudflare
<!-- id: multi-device-relay source: .claude/features/multi-device-relay.md -->

# Relay nhiều máy qua Cloudflare

> A browser picks one of several online machines; each machine has a Durable Object as meeting point and its token never leaves it.

# Multi-Device Dashboard Relay (dash.kaiitech.net chọn nhiều PC)

## Mục đích
Cho phép **nhiều PC** cùng online và người dùng mở `dash.kaiitech.net`, đăng nhập Google,
thấy **danh sách device thuộc org của mình**, chọn 1 máy → điều khiển đúng **web dashboard sẵn có**
của máy đó (HTTP + WebSocket). Thay cho mô hình cũ: `dash.kaiitech.net` chỉ trỏ 1 PC qua 1
`cloudflare-tunnel-runner` tunnel.

Kiến trúc: **central relay broker** trên Cloudflare Workers + Durable Objects (DO), đặt trong `fleet-api`.
Plan đầy đủ 6 phase: `plans/` (serene-hopping-glade) — file này mô tả trạng thái đã build.

## Kiến trúc
```
Browser (dash.kaiitech.net)   CF Worker fleet-api            PC KazuoAI
 /d/<id>/api (fetch) ─┐                                       dashboard-server.ts (loopback)
 /d/<id>/ws  (WS)    ─┼─► RelayDeviceDO(<deviceId>) ◄══ 1 WSS bền ══► relay-agent.ts
                                (agent tunnel)                 tự đính dashboardToken → local-fetch
```
- **1 DO / deviceId** (`env.RELAY.idFromName(deviceId)`): giữ 1 agent-WS + N browser-session, route theo `rid`/`sid`.
- `dashboardToken` của máy **không rời PC**: relay-agent tự đính `Authorization: Bearer <dashboardToken>` phía loopback.
  Browser định danh bằng **appToken** (verify + ownership tại Worker TRƯỚC khi vào DO).
- Agent mở local `/ws` với `Origin === Host` (`http://127.0.0.1:<port>`) để qua `verifyClient` của dashboard-server.

## Frame protocol (`fleet-api/src/relay/frames.ts` + bản copy `electron/relay-frames.ts` — GIỮ ĐỒNG BỘ)
HTTP + WS gói trên 1 agent-WebSocket:
- HTTP request: `{t:'req', rid, method, path, headers, body?}` (request body inline base64 — nhỏ).
- HTTP response **STREAM** (Phase 2): `{t:'res-head', rid, status, headers}` → N **binary chunk** `[kind:1][ridLen:1][rid][payload]`
  (`encodeBinaryChunk`/`decodeBinaryChunk`, `BIN_RES_BODY`) → `{t:'res-end', rid}`. Media (`/serve/*`) không base64 cả file,
  không nạp vào RAM Worker/DO. Backpressure: agent `res.pause()` tới khi `ws.send` callback flush xong.
- WS ảo: `{t:'ws-open', sid, path}` → `ws-open-ok|ws-open-err`; `{t:'ws-msg', sid, dir:'up'|'down', enc:'text'|'b64', data}`; `{t:'ws-close', sid}`
- **Notify (agent → DO, mobile push):** `{t:'notify', title, body, source?}`. Agent gửi khi có `plugin:notification:show`
  (`sendRelayNotify` trong `electron/relay-agent.ts`, drop im lặng nếu uplink chưa OPEN, không queue). DO: `sanitizeNotify`
  (cắt title 100 / body 500 / source 64, rỗng cả 2 → bỏ) → `NotifyThrottle` (10/phút/device, dư thì drop; state trong RAM
  DO nên hibernate thì reset) → `ctx.waitUntil(pushNotify)` đọc `devices` (owner `account_id`, tên `name||hostname||id`,
  bỏ nếu không active) → `sendPushToAccount` (`fleet-api/src/lib/fcm.ts`). DO biết `deviceId` nhờ Worker gắn header
  `X-Relay-Device` khi forward agent upgrade → lưu trong attachment `{role:'agent', deviceId}` (DO không đọc ngược được
  tên từ `idFromName`). Chi tiết: `.claude/features/mobile-app-push.md`.

## Files
**fleet-api (Cloudflare Worker):**
- `src/relay/frames.ts` — codec dùng chung (types + encode/decode).
- `src/relay/RelayDeviceDO.ts` — Durable Object 1/deviceId. Nhận agent upgrade + browser ws + browser http;
  route `rid` / `sid` (tag `browser:<sid>`, agent tag `agent`). HTTP response dùng `TransformStream` (await `res-head` →
  `Response(readable)`; binary chunk → `writer.write`; `res-end` → `writer.close`). Hibernation API (`acceptWebSocket` +
  `serializeAttachment`). Agent drop → fail head 502 + đóng writer + đóng browser 1011.
  **Hibernation (Phase 3):** constructor set `setWebSocketAutoResponse('ping','pong')` → keepalive không đánh thức DO.
  Browser socket được stamp `{accountId,orgId}` (từ header Worker); `onBrowserMessage` **drop frame nếu thiếu identity**
  (authZ per-frame). Route `presence` (`X-Relay-Role: presence`) → `{online: có agent-socket?}`.
  **Device reconnect (máy restart):** `acceptAgent` đóng socket cũ rồi nhận socket mới, nhưng socket đã `close()`
  **vẫn nằm trong `getWebSockets('agent')`** cho tới khi đầu kia đáp close-handshake — tiến trình bị kill thì không bao giờ đáp.
  Vì vậy `agentSocket()` **chỉ lấy socket `readyState === OPEN`**; lấy `[0]` sẽ route vào socket chết → `send()` ném
  `TypeError: Can't call WebSocket send() after close()` → thoát ra khỏi DO → **HTTP 500 cho MỌI `/d/<id>/api/*` và `/ws`**
  suốt cửa sổ reconnect. Phòng thủ nhiều lớp: mọi `agent.send()` đều bọc try/catch → `forwardHttp` trả **502
  'device offline'** (thay vì 504/500), `acceptBrowserWs` đóng browser socket 1011; và `webSocketClose` nhánh agent
  **bỏ qua teardown nếu đã có agent OPEN khác** — close muộn của socket cũ không được đá văng phiên của agent mới.
  Regression test: `test/relay.test.ts` → "serves HTTP through the new agent after the device reconnects" +
  "opens a browser WebSocket through the new agent after the device reconnects".
  **Cap (Phase 6):** `MAX_BROWSER_SESSIONS=32` — `acceptBrowserWs` trả **429** khi vượt (bound memory/CPU mỗi DO).
  ⚠️ **`browserCount()` CHỈ đếm socket `readyState === OPEN`** — đúng cái bẫy mà `agentSocket()` đã phải né:
  socket còn nằm trong `getWebSockets()` tới khi close-handshake xong, mà trình duyệt đã rời trang/ngủ/mất mạng
  thì **không bao giờ đáp**. Đếm cả xác thì việc đổi thiết bị, tải lại trang hay một vòng reconnect bình thường
  cũng lấp đủ 32 chỗ → device bị **429 với mọi viewer mới**, và vì con số nằm trong DO chứ không nằm ở trang,
  **tải lại tab không xoá được nó**.
- `src/routes/relay.ts` — `isRelayUpgrade`/`handleRelayUpgrade` (agent `/relay/agent?token&deviceId`, browser `/d/:id/ws?ticket`)
  + `isRelayHttp`/`handleRelayHttp` (`ALL /d/:id/api/*`, Bearer hoặc `?ticket`). `authorizeDevice` (agent uplink) verify appToken +
  `device.account_id === accountId` + `status='active'`; đường browser dùng `authorizeBrowser` (owner/org/share — `device-sharing.md`). **Strip `ticket` khỏi query khi forward** (không leak token xuống device).
  Browser ws forward kèm `X-Relay-Account/Org` (stamp identity). `isDeviceOnline(env, deviceId)` — hỏi DO presence.
  **Browser API (Phase 4):** `GET /api/relay/devices` (org-scope `resolveEffectiveOrgId` + `isDeviceOnline` mỗi device,
  trả cả cột `name`), `GET /api/relay/ticket?deviceId` (mint ticket cho device org sở hữu). Browser ws giờ **verify relay ticket** (không phải appToken).
  **Naming (self-service):** `GET /api/relay/org` (`{id,name,isOwner}`), `POST /api/relay/org/name` (chỉ owner), `POST /api/relay/devices/:id/name`
  (org sở hữu device; body rỗng ⇒ xoá tên → fallback hostname). Chi tiết: `.claude/features/device-fleet-naming.md`.
  **Prefix allowlist (Phase 5):** `isRelayHttp` CHỈ tunnel
  `/d/:id/{api,plugins,plugins-library,backgrounds,backgrounds-library,resources,serve,upload}` — bare `/d/:id/`
  + client-route KHÔNG tunnel (là SPA shell, serve tĩnh; tránh leak dashboardToken + tải máy).
  **CẢNH BÁO khi thêm route mới vào `dashboard-server.ts`:** phải thêm prefix vào allowlist này cùng lúc.
  Thiếu prefix KHÔNG gây 404 — nó rơi xuống shell và trả về `dashboard.html` kèm HTTP 200. Với `<img>` thì
  chỉ là icon vỡ, nhưng với một `<iframe>` thì shell tự boot BÊN TRONG chính nó; nếu frame đó lại mount
  lớp background thì thành lồng vô hạn (đã xảy ra với `backgrounds`). Regression test:
  `test/relay.test.ts` → "tunnels only device sub-paths, never the SPA shell".
- `src/lib/relayTicket.ts` (mới) — sign/verify ticket TTL 60s `{deviceId,orgId,accountId,exp}`, crypto giống `appToken.ts`.
- `src/index.ts` — thêm nhánh relay TRƯỚC chuỗi `/api/*`; re-export `RelayDeviceDO`.
- `src/types.ts` — `Env.RELAY: DurableObjectNamespace`.
- `wrangler.toml` — `[[durable_objects.bindings]] RELAY` + `[[migrations]] v1 new_sqlite_classes`.
- `wrangler.toml` — `[observability] enabled = true` (Workers Logs, 100% sampling): xem log từng request ở tab Observability của Worker `kazuo-fleet-api`. Có hiệu lực sau lần `wrangler deploy` kế tiếp.
- `test/relay.test.ts` — integration test (agent connect, HTTP tunnel, WS echo, offline 502, unauthorized 401, device reconnect).

**src (web-dashboard client, Phase 5):**
- `src/lib/relay-session.ts` (mới) — `isRelay` (không có `__KAZUO_DASH_TOKEN__`), `deviceId` từ path `/d/<id>`, `appToken`
  (localStorage), `refreshTicket()` gọi `/api/relay/ticket`, `resolveAssetUrl()` prefix `/d/<id>`.
- `src/lib/ipc-web-transport.ts` — `apiBase()` (relay: `/d/<id>/api`, local: `/api`), `authHeader()` (relay: appToken, local: dashboardToken),
  `connectWS` async **refresh ticket** trước mỗi (re)connect ở relay mode. `ipc-web.ts`/`electron-api-web.ts` KHÔNG đổi.
  **Reconnect có phanh:** `scheduleReconnect()` giãn dần 3s → 30s (`WS_RETRY_MIN_MS`/`WS_RETRY_MAX_MS`), reset về 3s
  khi `onopen`, và giữ **một** timer duy nhất (cặp `onerror` → `close()` → `onclose` không được xếp chồng hai lần thử).
  **Vé rỗng bị chặn từ đầu:** `refreshTicket()` nuốt mọi lỗi (mạng, 401, 403, 429) và trả `''`; mở socket với vé rỗng
  là 401 cầm chắc mà vẫn tốn một handshake, nên `connectWS` coi đó là lần thử hỏng → `ws:disconnected` + backoff,
  không mở socket. Trước đó: thử lại phẳng 3 giây/lần **vĩnh viễn**, mỗi lần mint thêm một ticket.
- `src/DevicePicker.svelte` (mới) — GIS 'Sign in with Google' → `/api/auth/google` → appToken; list `/api/relay/devices` + chấm online → chọn → `/d/<id>/`.
  Hiển thị tên `name || hostname || id`, nút ✏ đổi tên mỗi device + khối tên fleet (đổi tên nếu `isOwner`) — xem `device-fleet-naming.md`.
- `src/DashboardApp.svelte` — **header device switcher** (chỉ relay mode). Thay ô "● Connected"/"Disconnected"
  bằng: **dot trạng thái WS + tên thiết bị đang kết nối** (`name || hostname`, fallback `deviceId`) +
  nút mở dropdown liệt kê các device trong org (fetch lại `/api/relay/devices` lúc `onMount`, mỗi item có dot
  `online`); chọn máy khác → `switchDevice()` điều hướng `/d/<id>/` (full reload, giống picker, vì device mới
  cần WS/ticket mới). Dot vẫn phản ánh `connected` (WS live) như cũ, chỉ bỏ chữ. **Local mode** (không relay,
  không `deviceId`) giữ nguyên "Connected/Disconnected" — không có khái niệm device để đổi. Dùng lại style
  dropdown `.dev-menu`/`.dev-menu-backdrop` có sẵn của menu Dev.
- `src/dashboard-entry.ts` — gate: relay+chưa chọn device → mount DevicePicker; relay+device+chưa login → về `/`; else **dynamic import** DashboardApp
  (để WS chỉ connect sau khi có device). Local mode không đổi.
- `fleet-api/RELAY-DEPLOY.md` (mới) — runbook deploy: Web OAuth client (GIS), `build:dash` → `deploy`, DNS, deprecate cloudflared, rate-limit edge.
- **Deploy Topology B (đã wire + verify):** `vite.dash.config.mts` (build shell base `/_dash/` → `fleet-api/admin/dist/_dash/`),
  npm script `build:dash` (+ `scripts/stage-dash-shell.mjs` copy shell → `_dash/index.html`), `fleet-api/src/index.ts` phục vụ shell
  trên dash host (`/_dash/*` → ASSETS; path khác → `env.ASSETS.fetch('/_dash/')` directory index; KHÔNG rơi về admin), route
  `dash.kaiitech.net/*` active trong `wrangler.toml`. Verify: vitest `worker.fetch('https://dash.kaiitech.net/')` → 200 shell chứa `/_dash/assets/`
  (KHÔNG phải admin), 52 test pass.

**electron (main process):**
- `electron/relay-frames.ts` — bản copy frames (byte-for-byte với fleet-api).
- `electron/relay-agent.ts` — WSS client lên `<fleet>/relay/agent`, reconnect backoff, self-gate theo `store.accountToken`.
  Replay `req` → local `http://127.0.0.1:<port>` (đính dashboardToken, `Accept-Encoding: identity`, strip hop-by-hop);
  `ws-open` → mở local `/ws` với Origin=Host; echo 2 chiều theo `sid`.
- `electron/dashboard-server.ts` — thêm `getDashboardPort()` + persist `boundPort` thực (vá luôn resolve khi EADDRINUSE +1).
- `electron/main.ts` — `startRelayAgent()` sau `startDashboardServer` (app-ready), `stopRelayAgent()` ở `will-quit`.
- `electron/cloud-client.ts` — `startRelayAgent()` sau login+register; `stopRelayAgent()` ở logout.
  **SSO mượn token từ Kazuo Hub:** Kazuo AI và Kazuo Hub là 2 app Electron tách biệt (userData riêng),
  nên đăng nhập ở Hub KHÔNG tự đăng nhập AI → relay uplink của AI đứng im (dashboard 502 "device offline").
  `initCloudClient()` (chạy lúc app-ready, trước `startRelayAgent()`) gọi `adoptHubTokenIfSignedOut()`:
  nếu AI chưa có `accountToken` của riêng nó → đọc `appData/kazuo-hub/config.json` (read-only, KHÔNG ghi
  ngược), lấy `accountToken`+`accountEmail`, `store.set` làm của mình, rồi `registerDevice()`. Sau đó
  `startRelayAgent()` ở `main.ts` thấy token → dial uplink. Chỉ mượn khi AI trống token (không đè phiên
  AI tự đăng nhập bằng tài khoản khác).

## Heartbeat qua relay (giảm tải Worker)
Trước đây mỗi máy gọi `POST /api/devices/heartbeat` mỗi 45s (~1.900 request/ngày/máy, ~4 thao tác D1 mỗi lần). Giờ khi relay uplink đang mở:
- **Lệnh admin đến tức thì:** `handleCreateCommand` (`routes/admin.ts`) INSERT lệnh vào D1 rồi `wakeDevice()` (`routes/relay.ts`) → DO (`X-Relay-Role: wake`)
  gửi frame `{t:'wake'}` xuống agent. Agent gọi handler do `cloud-client` đăng ký (`setRelayWakeHandler`, tránh import vòng) → `heartbeatOnce(true)`
  để lấy lệnh qua đường HTTP cũ (D1 vẫn là nguồn sự thật, `delivered_at` chống giao trùng). `wakeDevice` best-effort: máy offline thì lệnh
  nằm chờ trong D1.
- **Heartbeat HTTP thành lưới an toàn:** `cloud-client.heartbeatOnce()` bỏ qua gọi mạng nếu `isRelayConnected()` và chưa quá
  `RELAY_HEARTBEAT_INTERVAL_MS` (10 phút). Timer 45s vẫn chạy để kiểm tra gating entitlement cục bộ (không tốn mạng). Relay mất kết nối → quay về 45s.
- **Nối lại là lấy lệnh ngay:** agent gọi wake handler ở sự kiện `open` của uplink → lệnh xếp hàng lúc offline không phải chờ 10 phút.
- **`last_seen_at`:** DO ghi `devices.last_seen_at` khi agent nối (`acceptAgent`) và khi rớt (`webSocketClose`, bỏ qua socket bị thay thế).
  Khi đang nối, admin UI có thể thấy "last seen" cũ tới 10 phút (heartbeat an toàn) — online thực dùng presence DO.
- **Tương thích ngược:** bản app cũ bỏ qua frame `wake` (switch không có case) và vẫn heartbeat 45s → deploy Worker trước không hỏng gì;
  mức giảm request chỉ có sau khi người dùng cập nhật app.
- Test: `test/relay.test.ts` → "command wake-up over the relay uplink" (wake frame, máy offline vẫn queue lệnh, last_seen_at khi nối).

## Auth (chốt)
- Đăng nhập web = **Google Identity Services (GIS)** trên trình duyệt → id_token → `/api/auth/google` → appToken (localStorage).
  **CẦN Web OAuth client riêng** (client Desktop không dùng được cho GIS).
- **Multi-aud** (`src/lib/googleAuth.ts` `audAllowed`): `/api/auth/google` verify `aud` theo **danh sách client id phân tách dấu phẩy**
  (`GOOGLE_CLIENT_ID = "<desktop-id>,<web-id>"`) → Desktop app + web dashboard login chung fleet-api. Test: `test/aud-allowlist.test.ts`.
  Allowlist hiện tại có **3 id**: desktop cũ (project A, giữ cho bản đã phát hành),
  desktop mới + web (cùng project B). Bỏ id desktop cũ khi không còn bản cũ nào ngoài thực tế.
- **Sliding renewal** (`POST /api/auth/refresh`, `src/routes/auth.ts` `handleRefreshToken`): nhận appToken **còn hạn**, ký lại token 30 ngày mới
  cho cùng account (chặn nếu `accounts.status != 'active'`). Không dùng refresh_token của Google — appToken là HMAC của chính mình nên
  "gia hạn" chỉ là ký lại. Test: `test/auth-refresh.test.ts`.
- **Client**: `electron/lib/app-token.ts` (thuần, có test) giải mã `exp` cục bộ để biết **khi nào** hỏi; server luôn là bên quyết định
  phiên còn sống hay không (đồng hồ máy lệch không được phép đăng xuất ai). `electron/token-renewal.ts` giữ single-flight + latch +
  cooldown 15 phút, gọi từ `initCloudClient()` lúc boot và từ keepalive tick 30s của relay agent. Ngưỡng gia hạn 7 ngày.
- **Relay 401 KHÔNG đồng nghĩa token hết hạn**: `authorizeDevice` trả 401 cho 5 nguyên nhân (thiếu token, token hỏng/hết hạn, device
  không tồn tại, device thuộc account khác, device không active). Agent bắt `unexpected-response` lấy status rồi hỏi `/api/auth/refresh`
  phân xử: `expired` → thông báo + `stopRelayAgent()`; `ok` → nối lại ngay (token mới đã nằm trong store); `unknown` (mất mạng) → backoff
  bình thường. 401 lần hai sau khi server xác nhận token tốt ⇒ lỗi ở **device**, backoff max thay vì báo sai "hết hạn".
  ⚠️ `ws` bỏ `abortHandshake` khi có listener `unexpected-response` → phải tự `res.resume()` + `ws.close()`, nếu không socket treo ở
  CONNECTING và vòng reconnect (dựa vào `close`) chết hẳn.
- **Cứu phiên chết bằng Kazuo Hub** (`renewFromHub` trong `token-renewal.ts`): khi `/api/auth/refresh` trả 401 cho token của AI,
  trước khi latch `expired` thì đọc token Hub (`electron/hub-session.ts` `readHubSession()`, read-only, dùng chung với
  `adoptHubTokenIfSignedOut()`). Chỉ dùng nếu **khác** token chết và **cùng `accountId`** (`sameAccount()` trong `lib/app-token.ts`,
  bỏ qua `exp`) — token Hub của account khác sẽ lặng lẽ chuyển device sang fleet người khác nên bị từ chối. Đổi token Hub lấy token
  **mới của riêng AI** qua `/api/auth/refresh` rồi mới lưu (không lưu nguyên token Hub → 2 app giữ phiên độc lập). Thành công → `ok`
  → relay nối lại ngay. Trước đây `adoptHubTokenIfSignedOut()` chỉ mượn khi AI **trống** token, nên AI giữ token chết thì kẹt offline
  mãi dù Hub còn phiên hợp lệ.
- **Hiện hết hạn trong Settings**: `getAccountStatus()` có thêm `sessionExpired` = `isSessionExpired()` (latch server đã xác nhận)
  **HOẶC** `isExpired(token)` cục bộ — check cục bộ để Settings báo ngay, không phải chờ vòng 401 của relay; chỉ dẫn tới cảnh báo,
  không bao giờ đăng xuất, nên đồng hồ lệch tối đa gây 1 gợi ý "đăng nhập lại" thừa. `AccountSection.svelte` hiện "Phiên đăng nhập
  đã hết hạn" + nút **Đăng nhập lại** (gọi `login()`) cạnh Đăng xuất; `SidebarAccount.svelte` đổi nhãn sang màu cảnh báo. Trước đây
  Settings chỉ xét `!!accountToken` nên vẫn ghi "Signed in as" với token đã chết, và tín hiệu duy nhất là 1 toast Windows dễ bỏ lỡ.
  Settings chỉ đọc trạng thái lúc mount (không có push event) — mở lại tab là thấy.
- **Giới hạn**: máy tắt liên tục quá 30 ngày **và** Hub cũng không còn phiên hợp lệ cùng account → phải đăng nhập lại tay.
- Phạm vi device = **org của người dùng** (`devices.org_id`, `resolveEffectiveOrgId`) **+ máy được chia sẻ riêng**
  (`device_shares`, xem `.claude/features/device-sharing.md`).
- **Browser HTTP** `/d/:id/api/*` + cookie WS: `Authorization: Bearer <appToken>` → `authorizeBrowser` (owner / org / share,
  `lib/deviceShares.ts` `loadAccessibleDevice`). `authorizeDevice` (chỉ owner) giờ chỉ dùng cho agent uplink.
- **Browser WS** `/d/:id/ws`: **relay ticket** (TTL 60s) lấy qua `GET /api/relay/ticket` (WS handshake không set header được).
- **Agent uplink** `/relay/agent`: appToken + `deviceId` (verify ownership qua D1).

## Trạng thái
- **Phase 1 — COMPLETED** (tunnel end-to-end: agent WS + DO + browser HTTP/WS qua CF).
- **Phase 2 — COMPLETED** (streaming HTTP response bằng binary chunk cho media, backpressure).
  **LƯU Ý:** phần "serve SPA shell tĩnh từ ASSETS" đã dồn sang **Phase 5** (phụ thuộc bundle web-dashboard trong ASSETS + route dash).
- **Phase 3 — COMPLETED** (hibernation ping/pong; presence; authZ per-frame stamp identity → đóng residual WS auth).
- **Phase 4 — COMPLETED** (`/api/relay/devices` org-scope + online; `/api/relay/ticket` TTL 60s; browser ws verify ticket;
  `serveLocalFile` đổi sang relative `/serve/<token>`). Verify: `test/relay.test.ts` (11 test, gồm devices list org-scope,
  ticket mint/403, bad-ticket 401), fleet-api typecheck + 49 test pass, electron `tsc -p tsconfig.node.json` sạch.
- **Phase 5 — CODE COMPLETED** (client device-aware transport + `relay-session` + device-picker GIS login + prefix allowlist).
  Verify: `vite build` sạch, fleet-api typecheck + 50 test pass (thêm test allowlist prefix), tsc 2 file client-TS sạch.
  **DEPLOY PENDING (chủ dự án làm):** tạo Web OAuth client (`VITE_GIS_CLIENT_ID`), serve shell (Pages/Worker assets), enable route
  `dash.kaiitech.net`, trỏ DNS — xem `fleet-api/RELAY-DEPLOY.md`.
- **Phase 6 — COMPLETED** (cap browser session/DO = 8 → 429; rate-limit ticket/devices ghi hướng dẫn edge Cloudflare WAF trong
  `RELAY-DEPLOY.md`; cập nhật `dashboard-server-security.md` — residual WS đóng cho đường relay). Verify: fleet-api typecheck + 51 test pass
  (thêm test cap 429). Cờ tắt exec-class cho relay session: **bỏ qua (YAGNI)** — RCE đã chặn bởi org-ownership + `isRegisteredEnabledPlugin`.

## Known limitations / TODO
- **SSO Hub→AI 1 chiều, chỉ lúc boot:** AI mượn token của Hub 1 lần khi khởi động (nếu AI trống token).
  KHÔNG đồng bộ ngược lại: nếu Hub đăng xuất/đổi token SAU khi AI đã mượn, AI vẫn giữ token cũ tới khi
  AI tự đăng xuất hoặc khởi động lại + Hub trống. Chấp nhận được (token hết hạn thì relay/heartbeat tự 401),
  chưa làm watch/sync realtime (YAGNI).
- **Headless (`electron/headless.ts`) CHƯA có relay-agent** — headless là bản dashboard-server độc lập (port/token riêng),
  wiring cần parameter hoá relay-agent (port/token provider). Hoãn (mục tiêu chính là app GUI).
- Request body vẫn inline base64 (nhỏ, JSON POST) — chỉ RESPONSE body mới stream binary.
- `serveLocalFile` trả relative `/serve/<token>` (host-absolute) → local desktop OK; qua relay CẦN prefix `/d/<id>/serve/...`.
  `relaySession.resolveAssetUrl()` đã có nhưng **CHƯA áp vào đường dữ liệu plugin** (URL trả qua WS invoke tới iframe plugin) —
  cần hook chỗ plugin dùng media, verify trong trình duyệt (Phase 6 / khi deploy). Đây là điểm CHƯA verify được cục bộ.
- Toàn bộ Phase 5 client (GIS login, picker, transport) mới verify bằng build + typecheck; **chưa chạy thực trên trình duyệt**
  (cần deploy + Web OAuth client). Chủ dự án verify sau deploy theo checklist `RELAY-DEPLOY.md`.
- `isolatedStorage: false` trong `fleet-api/vitest.config.ts` (DO WS + Windows EBUSY) — test mới phải tự seed UUID.


---

# Session locks for concurrent agents / Khoá phiên khi nhiều agent cùng làm việc
<!-- id: session-lock source: .claude/features/session-lock-protocol.md -->

# Khoá phiên khi nhiều agent cùng làm việc

> A hook of the AI tooling writes build/relaunch/file locks so parallel sessions do not destroy each other's work; fails open.

# Session-lock protocol (chạy nhiều session Claude song song)

## Mục đích

Cho phép **nhiều session Claude cùng sửa một working tree** tại cùng một thời điểm, chạy từ bên trong plugin ai-chat của chính bản Kazuo AI đang mở, mà không session nào giẫm chân session khác và không session nào restart app giữa chừng.

Bài toán cụ thể: một vòng hardening được chia thành 5 luồng việc (stream) chạy song song. Cả 5 dùng chung một checkout, một tiến trình Electron, một thư mục `dist/`. Ba thứ sẽ hỏng nếu không có gì điều phối:

1. Hai session sửa cùng một file → mất thay đổi của nhau.
2. Một session restart/kill Electron → **mọi** session ai-chat chết theo (session là tiến trình con của `electron.exe`).
3. Hai session cùng `vite build` → `dist/` lẫn lộn hai bản build.

Giao thức giải quyết bằng: mỗi stream khai báo **file mình sở hữu** trong frontmatter của plan, và một hook `PreToolUse` chặn thao tác vượt ranh giới đó cũng như các lệnh có sức phá hoại lan rộng.

Hook là **công cụ điều phối, không phải hàng rào bảo mật**. Nó fail-open khi gặp lỗi nội bộ — các quy tắc viết trong `session-lock/PROTOCOL.md` vẫn là thứ ràng buộc thật.

## File liên quan

- `scripts/session-lock/lib.js` — dùng chung: chuẩn hoá path về dạng repo-relative POSIX, glob matcher tối giản (`*`, `**`, tiền tố `!` để loại trừ), đọc `owns:` từ frontmatter các plan `plans/*-ms-NN-*/plan.md`, đọc/ghi lock kiểu atomic (ghi file tạm rồi `rename`).
- `scripts/session-lock/guard.js` — hook `PreToolUse`. Đọc JSON từ stdin, `exit 0` = cho phép, `exit 2` = chặn kèm lý do trên stderr. Mọi lỗi nội bộ → `exit 0`.
- `scripts/session-lock/claim.js` — lệnh đầu tiên của mỗi session. Không tự ghi lock (xem *Cách hoạt động*), chỉ kiểm tra và in quy tắc.
- `scripts/session-lock/release.js` — cổng kết thúc: bắt buộc 2 typecheck sạch + mọi file mình sở hữu đã commit, rồi mới ghi `<stream>.done`.
- `scripts/session-lock/status.js` — bảng trạng thái; `--wait` chặn tới khi mọi stream đã release (dùng bởi `run.bat [W]`).
- `scripts/session-lock/wait-milestone.js` — chờ một milestone hoặc một stream khác xong.
- `scripts/session-lock/build-renderer.js` — cách **duy nhất** được phép build renderer; giữ `build.lock` để tuần tự hoá.
- `scripts/session-lock/reload-plugin.js` — nạp lại backend một plugin không cần restart: typecheck → emit → copy `main/` sang userData → toggle 2 lần → broadcast. **Từ chối `ai-chat`.**
- `scripts/session-lock/selftest.js` — 144 kiểm tra cho `guard.js`. Chạy sau mỗi lần sửa guard. Nhóm "shared working tree detection" trỏ `APPDATA` vào thư mục tạm để không đụng dữ liệu thật của app.
- `.claude/settings.json` — đăng ký hook với `matcher: ""` (phủ mọi tool).
- `session-lock/PROTOCOL.md` — bản rút gọn dán cho mỗi session; file duy nhất trong `session-lock/` được commit.
- `run.bat` / `run.sh` — thêm phím `[W]`.
- `.gitignore` — bỏ qua `session-lock/*` trừ `PROTOCOL.md`.

## Cách hoạt động

### Claim: vì sao hook ghi lock chứ không phải claim.js

Chỉ hook mới nhận được `session_id` (Claude Code truyền qua stdin); bản thân agent không biết id của chính mình. Một lock không có danh tính thì không phân biệt được hai session, nên:

1. Session chạy `node scripts/session-lock/claim.js <stream>`.
2. Hook **nhìn thấy lệnh đó trước khi nó chạy**, khớp regex `claim\.js\s+(\S+)`, và tự ghi `session-lock/<stream>.lock` kèm `sessionId` thật + `owns` đọc từ plan.
3. Sau đó `claim.js` mới chạy, đọc lock vừa được tạo và in ra quy tắc. Nếu không thấy lock → hook không chạy → báo lỗi ngay.

Nếu stream đã bị session khác giữ và còn sống, hook chặn luôn ở bước 2.

### Chặn theo quyền sở hữu

Áp cho **mọi đường ghi mà hook nhìn thấy**: `Edit` / `Write` / `MultiEdit` / `NotebookEdit`, và cả MCP `write_project_file` / `write_plugin_source` (hai tool này ghi file y hệt Edit, bỏ sót là hở toang). Hook lấy path, đưa về dạng repo-relative, rồi so với `owns` của **mọi lock khác đang sống**. Khớp → chặn. Quy tắc phụ:

- Lock của chính mình luôn thắng (không tự chặn mình).
- Path không thuộc ai → cho qua. Trong vòng này đó là các thư mục đóng băng (`docs/`, `package.json`, …), quy ước cấm sửa nằm ở PROTOCOL.md chứ hook không ép.
- Path ngoài repo → cho qua.
- Lock đã có `.done`, hoặc heartbeat quá 30 phút → không còn chặn nữa (chống lock chết khi session crash).

`owns` hỗ trợ loại trừ: `electron/**` cộng `!electron/store.ts` nghĩa là "cả electron trừ store.ts". Loại trừ luôn thắng, không phụ thuộc thứ tự.

### Heartbeat

Mọi tool call đều làm hook cập nhật `heartbeatAt` của lock thuộc session đó. Nhờ vậy "còn sống" đo bằng hoạt động thật, không cần tiến trình nền.

**Cái bẫy đi kèm:** chờ (`wait-milestone.js`) là **một** tool call rất dài — suốt thời gian đó không có tool call nào khác, nên lock tự stale sau 30 phút. Session làm đúng quy trình lại bị phạt: stream khác được phép sửa file của nó, session khác claim được stream của nó, và tới 60 phút thì `[W]` coi vòng chạy đã xong rồi **restart app ngay dưới chân nó**. Vì vậy `wait-milestone.js` có `--stream <của mình>` để tự đập nhịp mỗi vòng poll, và **từ chối** chờ quá 25 phút nếu không có cờ đó.

### Bảo vệ chính giao thức

`session-lock/**`, `scripts/session-lock/**`, `.claude/settings.json` bị đóng băng với mọi stream **trừ chủ sở hữu** khi đang có vòng chạy. Lý do: stream nào sửa được `guard.js` hoặc `settings.json` thì tắt được hàng rào của tất cả; stream nào ghi được `<stream>.done` thì làm `[W]` restart app trong lúc người khác còn đang làm. Tương tự, `release.js <stream>` bị chặn nếu lock của stream đó thuộc session khác.

Khi **không** có lock nào đang sống thì các file này sửa được bình thường — nếu không thì không ai bảo trì được giao thức.

### Chặn theo sức phá hoại

Với `Bash`, hook đối chiếu command với danh sách regex cấm; với MCP thì đối chiếu tên tool. Nhóm chính:

| Nhóm | Vì sao cấm |
|---|---|
| `taskkill`/`Stop-Process` electron, `run.bat`, `dev-rebuild`, `electron .`, `/app/relaunch` | Restart app = giết mọi session ai-chat. |
| `tsc -p tsconfig.node.json` không kèm `--noEmit` | Electron đang giữ handle `dist-electron/`; ghi đè làm hỏng app đang chạy. |
| `vite build` ngoài `build-renderer.js`, `npm run build\|dev\|start\|headless` | Hai build song song làm lẫn `dist/`. |
| `plugins/toggle\|install\|uninstall` với `ai-chat`, `live_plugin_toggle` với `ai-chat` | `deactivate()` của ai-chat gọi `disposeAll()` → chấm dứt mọi session Claude đang chạy. |
| `git checkout\|switch\|reset --hard\|stash\|rebase\|merge\|clean` | Working tree dùng chung; đổi HEAD sẽ xoá việc của session khác. **Chỉ chặn khi thực sự còn session khác** — xem "Phát hiện session khác" bên dưới. |
| `git add .`/`-A` | Stage bừa lên cả sửa đổi dở của session khác. Chặn **không điều kiện**: kể cả một mình, `git add <path>` vẫn là thói quen đúng. |
| `rm -rf dist`/`dist-electron` | Xoá thư mục Electron đang đọc. |
| MCP `kill_process`, `build_project`, `execute_command`, `terminal_execute`, … | Chạy lệnh tuỳ ý ngoài tầm kiểm soát của guard. |

### Phát hiện session khác (luật git tự mở khi chỉ còn một mình)

Nhóm luật git đổi HEAD hỏi `lib.liveAiChatSessions()` xem **còn ai đang làm việc
trong cây này không**, thay vì chặn cứng như trước.

**Vì sao không dùng lock.** Lock chỉ sinh ra khi session chạy `claim.js`. Đã gặp
thực tế 8 tiến trình `claude` chạy song song trong khi `status.js` báo "No stream
has claimed a lock" — nếu luật git tin vào lock, nó sẽ mở cửa đúng lúc nguy hiểm
nhất. Lock trả lời được "ai sở hữu file nào", không trả lời được "còn ai ở đây".

**Nguồn sự thật.** Plugin ai-chat công bố các tab đang mở ra
`%APPDATA%/kazuo-ai/ai-chat-live.json` (xem
`plugins-library/ai-chat/.claude/features/live-sessions-file.md`). Hook lọc theo
`cwd` — khớp `ROOT` **hoặc thư mục con của nó**, vì session chạy trong
`plugins-library/` vẫn dùng chung cây này.

**Ba câu trả lời:**

| `liveAiChatSessions()` | Nghĩa | Luật git |
|---|---|---|
| `null` | Không biết: chưa có file, file hỏng, hoặc `pid` trong file đã chết | **Chặn** |
| Không có dòng nào khác `session_id` của mình | Chỉ còn mình | **Cho qua** |
| Có dòng khác | Còn người khác | **Chặn** |

`null` phải chặn: trước khi app được restart với tính năng này thì file **không
tồn tại**, và đọc "không có file" thành "không có ai" sẽ mở khoá cây đúng lúc
session khác đang sửa dở.

**`pid` thay cho ngưỡng thời gian.** App bị giết thì file ở lại, mô tả những
phiên đã chết theo nó. `process.kill(pid, 0)` phân biệt xác chết với app đang
sống trong vài micro giây — không cần đợi hết hạn như lock (30 phút), và không
cần đoán "im lặng bao lâu thì coi là đã đóng".

**Tự nhận ra mình.** Hook so `session_id` trong payload với `sessionId` từng
dòng. Thiếu bước này thì một session chạy từ terminal (không có dòng nào của
mình) sẽ đọc "1 tab đang mở" thành "chỉ có mình" và mở cửa sai.

**Giới hạn:** chỉ thấy session ai-chat. Session chạy từ terminal thường vô hình
với mọi người, kể cả chính nó — nên một session terminal cộng một tab ai-chat
vẫn đọc ra "có một session khác" và vẫn chặn. Sai về phía an toàn.

Chỉ nhóm luật git được nới. Các luật còn lại (restart Electron, toggle `ai-chat`,
`vite build`, `rm -rf dist`, `git add -A`) vẫn chặn vô điều kiện — chúng phá
hỏng app hoặc chính session đang chạy, không phụ thuộc có bao nhiêu người.

### Verify mà không restart

| Thay đổi ở | Cách thấy kết quả |
|---|---|
| UI plugin (html/css/js) | Reload webview — phục vụ trực tiếp từ `plugins-library/` với `Cache-Control: no-store`. |
| Backend plugin (`main/`) | `reload-plugin.js <id>` |
| Renderer (`src/`) | `build-renderer.js` rồi reload cửa sổ qua CDP 9222 |
| Theme / ngôn ngữ | `POST /settings` (bridge server, loopback) |
| Main process (`electron/`) | Không verify live được. Typecheck + `node --test`, ghi vào checklist sau restart. |

### Kết thúc vòng

Khi mọi stream có `.done`, người dùng bấm `[W]` trong `run.bat`. Nó chờ đúng điều kiện đó (ngưỡng stale 60 phút), dời `*.lock`, `*.done`, `milestones/` vào `session-lock/history/<timestamp>/`, rồi rebuild + restart như `[R]`. Sau restart mỗi session claim lại (`round` tăng theo số thư mục trong `history/`) và chạy checklist "sau restart" trong plan của mình.

## Giới hạn

- **Bash không kiểm tra path.** Guard chỉ so khớp chuỗi lệnh. Một session vẫn có thể sửa file của người khác bằng `sed -i`, `cp`, hay `> file`. Đây là công cụ điều phối, không phải sandbox — nó chặn nhầm lẫn, không chặn được người cố tình.
- **Cách viết luật quyết định độ chính xác.** Luật "chạy cái gì" (`run.bat`, `npm run build`, `vite build`, `git checkout`, `electron .`, `release.js`) chỉ khớp ở **đầu đoạn lệnh**, sau khi bóc các lớp bọc (`bash`, `npx`, `cmd /c`, `FOO=1`, `rtk`). Luật về cờ/đường dẫn khớp trên bản **đã xoá nội dung trong ngoặc**, nên `git commit -m "wrap vite build"` hay `grep "app/relaunch"` không bị chặn. Chỉ luật cần đọc payload (bắt `ai-chat` trong body JSON của curl) mới nhìn chuỗi thô.
- **Build trong `docker run` được phép** (`blankContainerPayloads` trong `guard.js`): phần trong ngoặc của đoạn `docker run` bị làm trống trước khi tách `heads`, nên `npm run build...` chạy bên trong container không bị coi là lệnh trên máy. Chỉ áp dụng khi container không chạm được file của app đang chạy: mọi `-v` phải là **named volume** hoặc bind mount **`:ro`**; có bind mount ghi được, `--mount` hay `--volumes-from` thì vẫn chặn như cũ. `docker exec` không được miễn (không biết container đó mount gì). Phần ngoài ngoặc không bị làm trống, nên `docker run ... && npm run build:win` vẫn bị chặn. Lý do cần luật này: build bản Linux (AppImage) chạy trong `electronuserland/builder` trên volume `kazuo-linux`, tách hẳn khỏi `dist/`/`dist-electron/` mà app dev đang chạy (`node_modules/electron`) đọc. Ngược lại `npm run build:win` ở thư mục gốc **vẫn phải chặn**, vì nó ghi đè đúng những file đó.
- **Giới hạn đã biết:** luật `npm run build` chưa bắt được mọi cách bọc lệnh, và hook chỉ xét tool `Bash`, không xét tool `PowerShell`.
- **Heredoc chỉ trơ khi thứ đọc nó cũng trơ.** `cat > f <<EOF` là dữ liệu → bóc. `bash <<EOF` và `cat <<EOF | bash` là **script thật đang chạy** → giữ nguyên để soi, nếu không thì mọi lệnh cấm chỉ cần núp sau 2 dòng heredoc là thoát. Heredoc không tìm thấy dấu đóng cũng không bóc.
- **`release.js` bắt buộc tên stream viết tường minh.** Bản thân script không biết mình là session nào (chỉ hook nhận được `session_id`), nên phép so khớp văn bản trong hook **là toàn bộ hàng rào**. Tên stream tính động (`$S`, `$(...)`) thì hook không kiểm được → **chặn**, vì ghi giả `.done` của người khác sẽ khiến `[W]` restart app trong lúc họ còn đang làm.
- **`tsc -p tsconfig.plugins.json` ghi `main/*.js` của *mọi* plugin**, không chỉ plugin đang cần. Nếu mọi `.ts` đều sạch thì output y hệt, không ai thấy gì. Nhưng nếu stream khác đang có `.ts` sửa dở trong cây thì lần emit này sinh lại `.js` của họ → bẩn `git status` của họ và chặn `release.js` của họ. `reload-plugin.js` so `git status` trước/sau và **in ra danh sách file bị ghi ngoài phạm vi plugin được yêu cầu** để người ta không phải đi mò. Bản thân bước copy thì chỉ copy `main/` của đúng plugin đó.
- **`ai-chat` không reload backend được** trong vòng chạy. Thay đổi trong `plugins-library/ai-chat/main/` phải chờ restart cuối vòng.
- **`POST /broadcast` nay đã nhận `{channel, payload}`** (thêm ở MS-01, `electron/bridge-server.ts` mục "Broadcast"): có `channel` thì phát thẳng tới mọi cửa sổ trên đúng kênh đó; không có thì vẫn phát tín hiệu settings-changed chung như trước. **`reload-plugin.js` vẫn gọi `POST /broadcast` không kèm `channel`** (`scripts/session-lock/reload-plugin.js`), nên hiện tại nó chỉ đang dùng nhánh settings-changed chung, chưa tận dụng kênh riêng theo plugin — vẫn đủ để widget đang mở tự đọc lại state, nhưng chưa phải reload theo đúng kênh của plugin đó.
- **File không thuộc ai thì không được bảo vệ.** Hai session cùng sửa `docs/` hoặc một `.claude/features/*.md` không nằm trong `owns` nào sẽ không bị chặn.
- **Hook fail-open.** Guard lỗi → cho qua. Đổi lại là guard hỏng không bao giờ làm tê liệt cả 5 session.
- **Chỉ tác dụng với session Claude Code trong repo này.** Hook nằm ở `.claude/settings.json` (project scope). Session ai-chat dùng Agent SDK với `settingSources: ['user','project','local']` nên đọc được file này. **Đã kiểm chứng bằng chạy thật** (`scripts/session-lock/gate-ai-chat.mjs`, exit 0): kể cả khi ai-chat tự gắn hook RTK qua `options.hooks`, hook từ `settings.json` **vẫn chạy** — hai cơ chế cộng gộp, không đè nhau. Chạy lại gate sau khi nâng SDK, đổi `settings.json`, hoặc sửa cách `chat-manager.ts` dựng hooks.


---

# MCP Store / MCP Store
<!-- id: mcp-store source: .claude/features/mcp-store.md -->

# MCP Store

> Browse and install remote MCP servers into Claude Code, Codex, Hermes or ai-chat; publish new MCP entries to the registry.

# MCP Store (sub-tab MCP trong tab Store)

## Mục đích

Settings → Store → sub-tab **MCP** (desktop và Web Dashboard; trên web thao tác chạy trên thiết bị đang xem qua relay, xem mục "Web Dashboard" bên dưới). Duyệt danh sách **MCP server từ xa** (remote, Streamable HTTP) trên registry, deploy MCP mới bằng cách nhập URL + kiểu xác thực (giống deploy plugin/skill), và cài MCP vào nhiều engine AI khác nhau:

- **Cài tự động** (app tự làm trên máy này): Claude Code, Codex, Hermes, ai-chat (Kazuo). Chọn **global** (mọi dự án) hoặc **local** (một folder: mặc định workspace đang mở trong ai-chat, có nút "Chọn folder khác"). Hermes chỉ có global.
- **Nhờ AI cài**: chép lời nhắn (có URL, kiểu xác thực, lệnh tham khảo, KHÔNG có token) dán vào AI agent.
- **Tự gõ lệnh**: các bước + lệnh/đoạn cấu hình có nút Chép. Claude.ai, ChatGPT, Hermes server (Telegram) chỉ có hướng dẫn (không cài tự động được).
- Hiện trạng thái **Đã cài** theo từng engine (global/local) và nút **Gỡ**.
- **Icon**: lúc Deploy/Sửa chọn file ảnh (png/svg/jpg/webp, ≤ 256 KB) qua hộp thoại hệ thống, có xem trước. Icon hiện trên thẻ MCP và đầu modal cài; không có icon → 🔌.
- **Sửa (Edit)**: devMode + đúng tác giả → nút ✏️ trên thẻ mở lại dialog Deploy với dữ liệu cũ. **Không đổi được `name`** (định danh trong config của máy đã cài). Không chọn icon mới → giữ icon cũ. Nút ✏️/🗑️ chỉ hiện trên MCP của chính username đang đăng nhập (`mcp:me`).

## File liên quan

- `electron/mcp-config-edit.ts` — logic thuần (test được bằng `node --test`): validate tên (`^[A-Za-z0-9_-]{1,64}$`), URL (https, http chỉ cho localhost, cấm user:pass), token (1 dòng), header; sửa TOML của Codex bằng text (`upsertTomlMcp/removeTomlMcp/hasTomlMcp` — chỉ đụng khối `[mcp_servers.<name>]` + sub-table, giữ nguyên mọi dòng khác kể cả comment, giữ CRLF); `claudeHasMcp` đọc `~/.claude.json` (user = `mcpServers`, local = `projects[<path dạng C:/x>].mcpServers`, so khớp không phân biệt hoa thường).
- `electron/mcp-config-edit.test.ts` — unit test cho file trên.
- `electron/mcp-store.ts` — registry + installer:
  - Registry: `plugin-store/mcp-index.json` (chung folder với `skills-index.json`), entry `McpIndexEntry { id: <author>/<name>, name, title, description, url, auth: none|oauth|bearer, headerName?, iconFileId?, iconMime?, author, uploadedAt }`. **Chỉ metadata + icon, không có zip, không bao giờ có token.** `fetchEntries()` lọc theo `authors.json` (`fetchApprovedAuthors`) + `sanitizeEntry` validate lại mọi field (registry dùng key ghi công khai → không tin; icon chỉ giữ khi `iconFileId` đúng charset và `iconMime` thuộc whitelist ảnh). `listMcps()` = `fetchEntries()` + tải icon thành `iconDataUri` (qua `fetchStoreMediaDataUri`, cache theo fileId, lỗi → không icon).
  - `deployMcp(input)`: gate devMode ở IPC + `requireDeployAuthor`; id = `<username>/<name>` nên chỉ sửa được entry của chính mình. `edit: false` mà id đã tồn tại → lỗi (chống ghi đè nhầm); `edit: true` mà chưa tồn tại → lỗi. Icon mới upload vào `plugin-store/mcp/<md5(id)[0..8]>/icon-<md5(nội dung)[0..12]>.<ext>` (tên theo hash nội dung → ảnh mới = fileId mới, cache không bị cũ); không có icon mới → giữ `iconFileId/iconMime` cũ. `undeployMcp` chỉ cho xoá entry của chính username đang đăng nhập. `currentAuthor()` cho UI biết username.
  - Install/uninstall luôn tra lại entry từ registry theo `id` qua `fetchEntries()` (không tải icon; renderer không truyền URL).
  - **Claude Code**: CLI `claude mcp add --transport http --scope user|local <name> <url> [--header "H: v"]` (`--header` là variadic → đặt SAU positional). Local = chạy với `cwd = folder`. Cài lại = `remove` trước rồi `add`. Tìm CLI: `~/.local/bin/claude(.exe)` (chỗ ai-chat cài) rồi PATH. Không có CLI → báo lỗi, gợi ý tab Tự gõ lệnh.
  - **Codex**: CLI `codex mcp add <name> --url <url>` khi: global + không có token + có binary native trên PATH (`codex.exe` trên Windows — shim `.cmd` bị bỏ qua để không cần shell). Còn lại (có token / local / không có CLI) → sửa `config.toml` trực tiếp, token ghi vào `http_headers`. Global: `$CODEX_HOME/config.toml` (mặc định `~/.codex`); local: `<folder>/.codex/config.toml` (Codex chỉ nạp khi folder được đánh dấu **trusted**).
  - **Hermes**: CLI `hermes mcp add` hỏi tương tác (đã thử: stdin null → thoát không ghi gì) nên luôn sửa `$HERMES_HOME/config.yaml` (mặc định `~/.hermes`) bằng thư viện `yaml` (giữ comment). OAuth → `auth: oauth`; token → `headers`.
  - **ai-chat**: ghi vào cả cấu hình Claude Code lẫn Codex (engine Claude của ai-chat dùng `settingSources` mặc định `user/project/local` nên đọc `~/.claude.json`; engine Codex chỉ thêm `--config` nên vẫn đọc `~/.codex/config.toml` của user). Đã cài = cài ở cả hai.
  - Ghi file: sao lưu `<file>.kazuo-bak` rồi ghi tạm + rename (atomic).
  - `mcpStatus(names, folder?)` đọc file cấu hình (chỉ đọc, nhanh, không chạy CLI). Tôn trọng `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `HERMES_HOME`.
- `electron/mcp-ipc.ts` — `mcp:list/me/status/cli/install/uninstall/pick-folder/pick-icon/deploy/undeploy` (`deploy/undeploy` gate `devMode`). `mcp:pick-icon` mở hộp thoại chọn ảnh, validate (đuôi + ≤ 256 KB) rồi trả `{ path, dataUri }` để xem trước; main nhớ path vừa chọn và `mcp:deploy` **chỉ nhận `iconPath` trùng path đó** → renderer không thể bắt main upload file tuỳ ý lên registry công khai. Đăng ký trong `electron/main.ts` cạnh `registerSkillIpcHandlers()`.
- `electron/preload.ts` (`electronAPI.mcp`), `src/lib/types.ts` (`McpIndexEntry`, `McpInstallRequest`, `McpDeployInput`, `McpEngineStatus`, `ElectronAPI.mcp`), `src/lib/ipc.ts` (`mcpAPI`), `src/lib/electron-api-web.ts` (nối sang route `/mcp/*`; chỉ `pickFolder`/`pickIcon` vẫn `notOnWeb`).
- `src/lib/mcp-guides.ts` — danh sách 7 engine (`GUIDE_ENGINES`: auto/ai/globalOnly/noBearer) + `manualCommand()` sinh lệnh/đoạn config với placeholder `<YOUR_TOKEN>`, `fillTemplate()`.
- `src/config/McpStore.svelte` — grid thẻ MCP (badge kiểu xác thực, tác giả, "✓ engine đã cài"), search, dialog Deploy (devMode), nút gỡ khỏi Store (devMode).
- `src/config/McpInstallModal.svelte` — modal cài: lưới "Bạn dùng AI nào?" → panel "Kết nối {engine}" với tab Cài tự động / Nhờ AI cài / Tự gõ lệnh.
- `src/config/ConfigApp.svelte` — `storeSub` thêm `'mcp'`, nút sub-tab hiện ở cả desktop lẫn web.
- `src/locales/{en,vi}.json5` — `store.mcpTab`, `store.mcp.*` (kể cả `store.mcp.engines.<id>.{name,sub,desc,step1..3,after}`).
- `package.json` — thêm dependency `yaml`.

## Giới hạn / rủi ro tồn dư

- Chỉ hỗ trợ MCP **remote qua URL** (không có stdio/`npx`).
- Token được ghi **dạng chữ thường** vào file cấu hình của engine (giống cách các engine tự làm). UI cảnh báo không commit file local có token lên git. Với Claude, local scope nằm trong `~/.claude.json` (không nằm trong folder dự án). Còn Codex local thì nằm trong `<folder>/.codex/config.toml`.
- Token đi qua tham số dòng lệnh của `claude mcp add` (có thể thấy trong danh sách tiến trình trong tích tắc).
- TOML editor chỉ nhận dạng dạng table `[mcp_servers.<name>]`. Nếu user tự khai báo kiểu inline/dotted-key (`mcp_servers.x.url = …`) thì trạng thái có thể sai, và cài thêm có thể tạo khoá trùng.
- Claude.ai / ChatGPT custom connector không hỗ trợ token riêng → UI báo không dùng được với MCP kiểu bearer.
- Không có nút "Xoá icon" (chỉ thay được bằng ảnh khác). File icon cũ trên registry không bị dọn khi thay (giống plugin store).
- SVG được hiển thị qua `<img src="data:...">` nên script trong SVG không chạy.
- Chưa smoke test end-to-end trong app chạy thật (cần registry + Dev Mode). Installer đã được kiểm chứng riêng lẻ với CLI thật trong thư mục tạm: Claude (`CLAUDE_CONFIG_DIR`), Codex (`CODEX_HOME`, `codex mcp list --json` đọc đúng `http_headers`), Hermes (`HERMES_HOME`, `hermes mcp list` thấy cả oauth lẫn header).

### Web Dashboard

`electron/dashboard-server.ts` có các route cùng nghĩa với IPC `mcp:*`: `GET /mcp/list`, `GET /mcp/me` (`{author}`), `POST /mcp/status`, `GET /mcp/cli`, `POST /mcp/install`, `POST /mcp/uninstall`, `POST /mcp/deploy`, `POST /mcp/undeploy`. Mọi `/api/*` đã bắt token như các route khác. Install/uninstall ghi file cấu hình của engine trên **thiết bị đang xem** (không phải máy chạy trình duyệt). Token bearer của MCP đi qua relay (TLS, nhưng qua edge Cloudflare) rồi mới tới thiết bị.

- Không có hộp thoại hệ thống trong trình duyệt: phạm vi local nhập đường dẫn folder trên thiết bị bằng ô text (mặc định là workspace ai-chat, qua `skill/active-workspace`); `requireFolder` vẫn bắt đường dẫn tuyệt đối và phải tồn tại. Icon khi Deploy/Sửa chọn bằng `<input type=file>` rồi gửi dạng data URI (`iconDataUri`, ≤ 256 KB); thiết bị ghi ra file tạm bằng `iconFileFromDataUri`, `deployMcp` kiểm tra lại như file chọn, rồi xoá file tạm. `iconPath` do trình duyệt gửi bị bỏ.
- Deploy/Undeploy chỉ gate bằng `devMode` — cùng điểm yếu đã biết với `POST /store/deploy` (xem `dashboard-server-security.md`: `devMode` ghi được từ web nên ai có write-token đều bật được). Cần phát hành lại app desktop thì thiết bị mới có các route này; thiết bị cũ trả lỗi 404 ở tab MCP.

### Tốc độ tải danh sách

`listMcps()` dùng `StoreListCache` (TTL 5 phút, stale-while-revalidate, xoá ngay khi Deploy/Undeploy). `fetchEntries()` đọc `mcp-index.json` và `authors.json` song song (đường cài/gỡ vẫn đọc registry trực tiếp, không qua cache). `ensureStoreFolderId` (`store-conn.ts`) nhớ id thư mục gốc 10 phút để mỗi lần đọc index bớt một request tới registry. Registry chậm vì mỗi request mất 1–2 giây, xem `files-api.md`.

### Built-in Kazuo AI MCP

Store always includes the trusted `kazuo-ai/kazuo-ai` entry, including when the remote registry is unavailable. It supports automatic installation into Claude Code, Codex, AI Chat (both configs), and Hermes (global only). It is not a remote URL and cannot be edited/published through the registry form.

The installer derives paths from the running app and writes stdio configuration using `process.execPath` with `ELECTRON_RUN_AS_NODE=1`, plus explicit user-data and workspace paths. No shell or system Node installation is required. Existing MCP entries are preserved and config backups follow the normal Store write path. Restart the client/MCP connection after installation. Live application tools require Kazuo AI to be running.

`npm run build:mcp` installs locked production MCP dependencies and compiles the server; desktop builds include the server and dependencies under `resources/mcp-server`. Changes to this Store integration require rebuilding the desktop app, not just updating the AI Chat plugin.


---

# Controlling plugins through MCP / Điều khiển plugin bằng MCP
<!-- id: mcp-control source: .claude/features/plugin-mcp-control.md -->

# Điều khiển plugin bằng MCP

> The agent in ai-chat calls tools of plugins attached to the session; tools are filtered per plugin and dangerous actions always prompt.

# Plugin MCP Control

## Mục đích

Cho phép AI agent chạy bên trong plugin `ai-chat` (Claude Agent SDK, cùng tiến trình Electron)
list/toggle/đọc-ghi CÁC PLUGIN KHÁC qua MCP tool — giống hệt những gì `mcp-server/` (dev tool ngoài,
chạy qua HTTP bridge) đã làm cho Claude Code, nhưng chạy trực tiếp trong-process (không cần bridge).
Mỗi plugin backend mới cũng có thể tự khai báo thêm tool riêng qua `getMcpTools(ctx)`, được `ai-chat`
tự động gom vào.

> **CẬP NHẬT (per-session attachment):** Dev Mode ĐÃ BỎ khỏi cơ chế này. Tool KHÔNG còn "tất cả
> hoặc không" theo Dev Mode nữa — mỗi session tự chọn plugin nào được gán (kể cả nhóm 8 tool điều
> khiển). Xem mục "Per-Session Plugin Attachment" bên dưới.

## File liên quan

**Host (`electron/`) — thêm hàm mới, KHÔNG đổi hành vi IPC handler cũ:**
- `electron/plugin-ipc.ts` — tách thân các `ipcMain.handle` cũ (`list-installed`, `get/set-settings`,
  `toggle`) thành hàm export riêng (`listInstalledPlugins`, `getPluginSettingsFor`,
  `setPluginSettingsFor`, `togglePluginEnabled`) — handler cũ gọi lại y hệt, hành vi không đổi. Thêm
  MỚI `getPluginManifestFor`, `readInstalledPluginSource`, `writeInstalledPluginSource` (đọc/ghi file
  plugin đã cài, chặn path traversal — port từ `mcp-server/src/tools/plugin-manager.ts`).
- `electron/plugin-loader.ts` — thêm export `getLibraryPluginPath()` (trước đó là hàm nội bộ
  `getLibraryPath()`), dùng cho fallback đọc manifest/source khi plugin chưa cài.
- `electron/plugin-host.ts` — import các hàm trên từ `plugin-ipc.ts` (lưu ý: tạo dependency vòng
  giữa 2 file, AN TOÀN vì cả 2 chiều chỉ dùng function bên trong thân hàm khác, không dùng ở top-level
  module — pattern CommonJS phổ biến). Build `ctx.modules.pluginControl` (gom các hàm trên) trong
  `buildContext()`. Thêm `collectPluginMcpTools()` — quét registry `loaded` (Map plugin đang active),
  gọi `module.getMcpTools?.(ctx)` của từng plugin, gộp lại + tự thêm tiền tố `<pluginId>_` vào tên tool
  để tránh trùng. Thêm ring buffer `pluginLogs` (Map<pluginId, entry[]>, tối đa 300 dòng/plugin) —
  `ctx.log()` (đã có sẵn) giờ ghi thêm vào buffer này song song với việc broadcast tới renderer; expose
  qua `getPluginLogsFor(pluginId, limit?)`.
- `plugins-library/_shared/plugin-host-types.d.ts` — thêm `modules.pluginControl` vào `PluginContext`
  + optional `getMcpTools?(ctx): any[]` vào `PluginMainModule` (chỉ thêm type, không đổi runtime).

**ai-chat (`plugins-library/ai-chat/`):**
- `main/plugin-control-mcp.ts` (file mới) — `buildPluginControlMcpServers(ctx)`: trả `undefined` nếu
  `ctx.store.get('devMode')` false; ngược lại dùng `ctx.modules.claudeAgent.createSdkMcpServer`/`.tool`
  (in-process MCP server, có sẵn từ SDK 0.3.201, không cần subprocess/stdio) tạo server `kazuo-plugins`
  gồm **8 tool chung** (`list_plugins`, `get_plugin_manifest`, `toggle_plugin`, `get_plugin_settings`,
  `set_plugin_settings`, `read_plugin_source`, `write_plugin_source`, `get_plugin_logs` — wrap
  `ctx.modules.pluginControl.*`) + tool riêng từ `collectPluginMcpTools()`. Mỗi tool handler bọc
  try/catch trả `isError: true` thay vì throw (pattern giống `mcp-server`'s dev tool).
- `main/agent-session.ts` — `AgentStartConfig` thêm field optional `mcpServers?: Record<string, any>`;
  `start()` chỉ set `options.mcpServers` nếu có giá trị (no-op khi absent, không đổi hành vi cũ).
- `main/chat-manager.ts` — `connectAgentFor()` gọi `buildPluginControlMcpServers(ctx)` trước khi
  `t.agent.start(...)`, truyền qua field `mcpServers` ở trên.
- `package.json` — thêm dependency `zod` (input schema cho `sdk.tool(...)`).

**Skill scaffold:**
- `.claude/skills/kazuo-create-plugin/scripts/scaffold-plugin.js` — `type=backend` sinh thêm ví dụ
  `getMcpTools(ctx)` mẫu (tool `ping`) trong `main/index.ts`.
- `.claude/skills/kazuo-create-plugin/references/plugin-runtime-api.md` — mục 2b giải thích quy ước.

## Cách hoạt động

1. Khi 1 tab trong `ai-chat` kết nối agent (`connectAgentFor`), gọi
   `buildPluginControlMcpServers(ctx, t.attachedPlugins)` — trả `undefined` nếu session chưa gán
   plugin nào (`undefined`/`[]`). Dev Mode KHÔNG còn được kiểm tra.
2. Nếu có gán: gói `mcpServers: { 'kazuo-plugins': <in-process McpServer> }` được truyền vào `query()`'s
   options — nhưng CHỈ chứa tool của plugin nằm trong `attachedPlugins` (lọc bởi `attach-filter.ts`).
   8 tool điều khiển chỉ có mặt khi `__plugin-control__` được gán. Tên tool business vẫn là
   `<pluginId>_<tên ngắn>`; tên 8 tool control giữ nguyên (không prefix).
3. Mọi tool đều gọi thẳng hàm trong `electron/plugin-ipc.ts` (qua `ctx.modules.pluginControl`) — CÙNG
   code path Plugin Manager UI dùng, nên toggle/set-settings qua AI cũng broadcast live-update tới
   widget đang mở y hệt thao tác tay.
4. `read_plugin_source`/`write_plugin_source` đọc/ghi trực tiếp file trong
   `userData/plugins/<id>/...` (write chỉ áp dụng plugin ĐÃ CÀI, không ghi được vào
   `plugins-library/` gốc) — có chặn path traversal.
5. `get_plugin_logs` đọc ring buffer main-process (KHÔNG phải `window.__dwPluginLogs` phía renderer —
   2 buffer riêng biệt, cùng nguồn dữ liệu là `ctx.log()` nhưng lưu ở 2 nơi khác nhau). Chỉ bắt được
   message đi qua `ctx.log()`; `console.log` trực tiếp trong `main/index.ts` không được ghi lại.

## Giới hạn / rủi ro đã biết

- **Thay đổi gán plugin không áp dụng giữa lượt** — tools chỉ được tính lại khi tab kết nối lại agent
  (giống việc đổi model/system prompt). `setAttachedPlugins` dispose agent để lần gửi sau kết nối lại.
- Dependency vòng `plugin-ipc.ts` ↔ `plugin-host.ts`: đã biên dịch sạch qua `tsc -p
  tsconfig.node.json --noEmit` sau khi thêm; nếu sau này thêm code chạy Ở TOP-LEVEL module (không
  phải trong thân hàm) tham chiếu 2 chiều, cần kiểm tra lại thứ tự load.
- `write_plugin_source` cho AI quyền ghi đè file code plugin khác đang chạy thật. Sau khi bỏ Dev Mode,
  2 lớp bảo vệ: (1) người dùng phải TỰ TAY gán nhóm `__plugin-control__` vào session; (2) **`write_plugin_source`
  LUÔN bật prompt xác nhận Allow/Deny** (kể cả ở `bypassPermissions` mode) — xem `requestConfirm` /
  `makeConfirmRequest` / `pendingConfirms` (tái dùng event `permission_request` + IPC `permission` sẵn có).
  7 tool control còn lại (list/toggle/settings/read/logs...) vẫn chạy thẳng khi đã gán.
- Đã biên dịch kiểm tra: `tsc -p tsconfig.node.json --noEmit` (host) và `tsc -p tsconfig.plugins.json`
  (ai-chat + mọi plugin backend, kể cả plugin test có `getMcpTools` scaffold) — cả hai pass sau mỗi
  bước sửa.
- Chưa test runtime thật trong Electron (chỉ verify qua tsc + unit test) — cần chạy `npm run dev`,
  mở ai-chat, gán plugin cho session, thử hỏi AI "liệt kê tool bạn có" để xác nhận lọc đúng.

## Per-Session Plugin Attachment

Mỗi session (tab) của `ai-chat` tự chọn plugin nào được gán; chỉ tool của plugin được gán mới lọt vào
agent của session đó. Gán được cho nhiều session độc lập, lưu bền theo session. **Dev Mode vô can.**

### File liên quan (chỉ `plugins-library/ai-chat/`, KHÔNG đụng host)

- `main/attach-filter.ts` (MỚI) — logic thuần, không phụ thuộc ctx/SDK/Dev Mode:
  - `CONTROL_PLUGIN_ID = '__plugin-control__'` — pseudo-plugin cho 8 tool điều khiển.
  - `pluginIdOf(toolName, knownIds)` — match prefix DÀI NHẤT (id có dấu `-` như `database-manager`
    không bị nhầm với `database`).
  - `filterMcpTools(allTools, attachedPlugins, knownIds)` — `undefined`→tất cả (no-filter), `[]`→rỗng,
    `[...]`→lọc theo owner.
  - `groupAttachablePlugins(allTools, installed, {controlToolCount})` — gom tool theo plugin cho picker,
    LUÔN kèm entry control.
- `test/attach-filter.test.js` (MỚI) — unit test `node:test` (chạy `node --test` từ thư mục ai-chat,
  sau khi `tsc -p tsconfig.plugins.json`). Nằm ngoài `main/**` nên KHÔNG bị compile/ship.
- `main/plugin-control-mcp.ts` — `buildPluginControlMcpServers(ctx, attachedPlugins?)`: bỏ gate Dev Mode;
  8 tool control giữ tên gốc (unprefixed), chỉ gồm khi `__plugin-control__` được gán; business tool lọc
  qua `filterMcpTools`; trả `undefined` khi rỗng. Thêm `listAttachablePlugins(ctx, attachedPlugins)` —
  plugin đang bật có tool + control + plugin đã gán mà đang tắt (`enabled:false`, hiện mờ trong picker).
- `main/chat-manager.ts` — `TabState.attachedPlugins` + `SessionMeta.attachedPlugins`;
  `saveSessionSnapshot` lưu; `workspaces()` trả kèm; `connectAgentFor` truyền `unionPlugins(t.attachedPlugins,
  workspacePlugins[cwd])` (session + workspace). Có `setSessionAttachedPlugins(sessionId, list)`,
  `attachableForSession(sessionId, cwd)`, `setWorkspaceAttachedPlugins(cwd, list)`,
  `attachableForWorkspace(cwd)` — xem mục "Hai cấp" bên dưới. **Không còn** `setAttachedPlugins(tabId, ...)`
  / `attachablePlugins(tabId)` kiểu tab-based (đã thay bằng 4 hàm session/workspace ở Phase 5).
- `main/index.ts` — 4 IPC trong `CHANNELS`: `set-session-plugins`, `attachable-for-session`,
  `set-workspace-plugins`, `attachable-for-workspace` (không còn `set-attached-plugins`/`attachable-plugins`).
- `widget.html` + `js/widget.js` + `css/widget.css` — **picker nổi mở từ context menu chuột phải**
  ở sidebar (KHÔNG còn nút subbar). Chuột phải session → "🧩 Gán plugin…"; chuột phải workspace →
  "🧩 Gán plugin cho thư mục…". `createTab`/`tabCfg`/`openTabForSession` vẫn mang `attachedPlugins`.

### Hai cấp: session + workspace (kế thừa union)

- **Session-level:** `sessionMeta[sessionId].attachedPlugins` (như trên).
- **Workspace-level:** setting `workspacePlugins: { [cwdLower]: string[] }` — mặc định của thư mục.
  Đặt qua chuột phải workspace.
- **Effective (lúc connect):** `unionPlugins(session.attachedPlugins, workspacePlugins[cwd])` — session
  tự kế thừa plugin của thư mục khi (re)connect ("khởi động lại tự nhận").
- **Picker session:** plugin do workspace cấp hiện **tick mờ + khóa** (`fromWorkspace`), chỉ sửa được
  phần riêng của session.
- **Warning ⚠️** trên dòng session ở sidebar khi `session.attachedPlugins ∩ workspacePlugins[cwd] ≠ ∅`
  (session tự gán trùng plugin thư mục đã cấp) — dùng `overlapPlugins`.
- Backend: `setSessionAttachedPlugins` / `attachableForSession` / `setWorkspaceAttachedPlugins` /
  `attachableForWorkspace`; IPC `set-session-plugins`, `attachable-for-session`, `set-workspace-plugins`,
  `attachable-for-workspace`. `setWorkspacePlugins` dispose agent mọi tab cùng cwd để reconnect nhận union.

### Semantics

- `attachedPlugins` là mảng pluginId (dùng `__plugin-control__` cho nhóm control). `undefined`/`[]` →
  không tool từ cấp đó (backend coalesce `?? []`). Không có khái niệm "legacy full".
- **Điều kiện 1 tool chạy** = plugin (session hoặc workspace) được gán AND plugin đang BẬT. Plugin tắt
  mà đã gán → inert cho tới khi bật lại.
- Đổi gán (session hoặc workspace) → dispose agent → áp dụng ở lần gửi kế tiếp.
- Chat MỚI chưa gửi tin (chưa có sessionId) chưa có picker riêng — dựa plugin workspace kế thừa.


---

# Run-agent: calling an agent programmatically / Run-agent: gọi agent theo kiểu lập trình
<!-- id: run-agent source: plugins-library/ai-chat/.claude/features/headless-run-agent.md -->

# Run-agent: gọi agent theo kiểu lập trình

> An API for other plugins to run one agent turn and get the result back, via IPC or a global service in the main process.

# Headless run-agent — chạy agent thay cho plugin khác (API dùng chung)

## Mục đích

Cho **plugin khác** (đầu tiên là `agent-review`, sau này bất kỳ automation nào) chạy một lượt Claude
Code agent **theo kiểu lập trình** và **nhận kết quả trả về**, thay vì phải thao tác qua UI widget.
Đây là mảnh còn thiếu để dựng pipeline: trước đây các kênh của ai-chat (`open-tab`/`connect-tab`/
`send`) chỉ **phát sự kiện broadcast** theo `tabId` cho webview, không trả kết quả cho người gọi.

## Hai đường gọi

1. **Kênh IPC (renderer→main)** — cho widget/settings của plugin khác gọi qua `window['kazuo-ai'].invoke(...)`.
2. **Global service (main→main)** — cho **main process** của plugin khác gọi trực tiếp, KHÔNG cần widget nào mở.
   `invoke` chỉ đi renderer→main nên main của plugin khác (vd `cron-job`) không với tới handler IPC được;
   mọi backend plugin chạy chung 1 tiến trình Electron main nên ai-chat publish hàm lên biến global.

### 1. Kênh IPC

- `plugin:ai-chat:run-agent` → `manager.runAgent(opts)` — **request→response** (Promise trả về kết quả).

### 2. Global service `globalThis.__kazuoAiChat`

- Đăng ký ở `activate()`, gỡ ở `deactivate()` (guard `version === 1` để không xoá nhầm publisher khác).
- Hình dạng: `{ version: 1, runAgent(opts): Promise<RunAgentResult> }`.
- Người gọi PHẢI guard: `const svc = globalThis.__kazuoAiChat; if (!svc?.runAgent) { /* ai-chat đang tắt */ }`.
- Cùng `RunAgentOptions`/`RunAgentResult` như kênh IPC bên dưới.

### Input (`RunAgentOptions`)

| Field | Bắt buộc | Mặc định | Ý nghĩa |
|---|---|---|---|
| `cwd` | ✅ | — | Thư mục làm việc (đường dẫn dùng được trên Windows) agent chạy trong đó |
| `prompt` | ✅ | — | Nội dung lượt user gửi cho agent |
| `pluginId` | — | `'external'` | Chỉ để đặt tên tab tạm `run:<pluginId>:<n>` |
| `sessionId` | — | `null` | Resume 1 session có sẵn thay vì tạo mới |
| `model` | — | `sonnet` | Model claude-code |
| `systemPrompt` | — | `''` | System prompt phụ (append preset claude_code) |
| `mode` | — | `bypassPermissions` | Permission mode; mặc định bypass để **không treo** vì không ai bấm cấp quyền |
| `attachedPlugins` | — | — | Danh sách pluginId có MCP tool cấp cho lượt chạy |
| `tabId` | — | tự sinh | Tab id do người gọi chọn (để tự `interrupt` sau) |
| `timeoutMs` | — | 15 phút | Giới hạn cứng; hết giờ → interrupt + trả `error:'timeout'` |
| `tools` | — | (SDK mặc định) | Allowlist tool tường minh, truyền thẳng qua SDK (không tự suy diễn gì thêm) |
| `disallowedTools` | — | (không có) | Blocklist tool tường minh, truyền thẳng qua SDK |
| `readOnlyScopeRoots` | — | (không có) | Bật **read-only review contract** — xem mục riêng bên dưới. Khác `null`/rỗng thì bỏ qua `sessionId` (luôn chạy phiên mới) |
| `workspaceUnityState` | — | `false` | Bật **workspace Unity-state contract** — chỉ đọc trong `cwd` + đúng 1 tool MCP đọc trạng thái Unity Editor của workspace đó. Xem mục riêng. Luôn phiên mới; bỏ qua `readOnlyScopeRoots` truyền kèm |
| `envProfileId` | — | (không có) | Hồ sơ môi trường (`providers['claude-code'].envProfiles`) dùng để spawn CLI — quyết định endpoint + credential. Bỏ trống = giữ nguyên hành vi cũ (rơi về `sessionDefaults`). **Id không khớp hồ sơ nào → lượt chạy trả `error`, KHÔNG âm thầm chạy bằng hồ sơ mặc định** — xem mục riêng bên dưới |
| `notifyPluginId` | — | (không có) | Phát thêm sự kiện của lượt chạy này trên `plugin:<id>:event` (ngoài `tabId`-scoped event như mọi tab) |

### Output (`RunAgentResult`)

`{ ok, tabId, sessionId, text, isError, costUsd?, error? }`
- `text` — toàn bộ **assistant text ở tầng chính** (bỏ qua lượt của subagent) gộp lại.
- `sessionId` — **resume được**: truyền lại vào lần gọi sau để tiếp tục cùng hội thoại.
- `ok=false` kèm `error` khi: thiếu SDK/cwd/prompt, cwd không tồn tại, send lỗi, hoặc timeout.

## Cách hoạt động (`chat-manager.ts` → `runAgent`)

1. Validate `sdk`/`cwd`/`prompt`; `openTab(tabId, {cwd, sessionId, ...})` (tab tạm).
2. Đăng ký 1 listener vào `runWaiters` (map `tabId → sink`). `handleAgentEvent` sau khi `emit` broadcast
   sẽ gọi luôn sink này → runAgent gom sự kiện của đúng tab đó.
3. `send(tabId, prompt)` — tự lazily connect CLI agent.
4. Gom `assistant` text (chỉ khi `!parentToolUseId`); nhớ `result` (is_error, cost) ở tầng chính.
5. Kết thúc khi nhận `done` (hoặc `error`, hoặc timeout) → **đóng tab** (dispose CLI, transcript vẫn
   còn trên đĩa để resume) → resolve Promise.

Vì sự kiện vẫn broadcast trên `plugin:ai-chat:event` theo `tabId` như mọi tab, tiến trình vẫn được
ghi vào ring buffer `traffic` phía backend (UI traffic monitor đã bị gỡ — xem README, mục "Theo dõi
traffic gửi/nhận với Claude"). Có thể dựng lại UI hiển thị sau nếu cần — đọc bằng
`plugin:ai-chat:traffic` (kéo khi cần). Ring buffer **không còn broadcast** từng mục: không còn ai
nghe từ khi gỡ UI, mà mỗi mục vẫn bị sao chép sang mọi cửa sổ. Ảnh/screenshot cũng bị bỏ phần
base64 trước khi lưu (giữ khối `image`, thay `data` bằng độ dài) để 300 mục không ghim hàng trăm MB.

## Chọn hồ sơ môi trường (`envProfileId`)

`resolveEnvOverride()` trong `chat-manager.ts` cố ý **lùi ngầm** về hồ sơ `default` khi id không khớp:

```ts
const profile = profiles.find((p) => p.id === targetId) || profiles.find((p) => p.id === DEFAULT_ENV_PROFILE);
```

Với tab của người dùng thì hợp lý — họ vừa bấm chọn từ dropdown, và một lựa chọn cũ không còn tồn tại
thì chạy tiếp còn hơn chặn. Với caller tự động thì **sai**: nó chỉ đích danh một tài khoản, và chạy bằng
tài khoản khác rồi báo thành công là che mất hoàn toàn sai sót.

Nên `runAgent()` kiểm tra tồn tại **trước khi mở tab**, và từ chối nếu không thấy:

```ts
if (envProfileId && !hasEnvProfile(ctx.getSetting('providers', {}), envProfileId)) {
  return { ...base, error: `Không có env profile "${envProfileId}" trong cấu hình ai-chat.` };
}
```

`hasEnvProfile()` nằm ở `main/env-profiles.ts` — module thuần, không import `electron`, nên test được
trực tiếp (`test/env-profiles.test.ts`, 5 test: khớp, không khớp, khoảng trắng thừa, id rỗng, config
thiếu/sai dạng). Hành vi của **tab người dùng KHÔNG đổi** — chỉ đường `runAgent()` là fail-closed.

Bỏ trống `envProfileId` giữ nguyên hành vi trước đây từng dòng một, nên mọi caller sẵn có
(agent-review, agent-role, kênh IPC `plugin:ai-chat:run-agent`, global `__kazuoAiChat.runAgent`) không
phải sửa gì: đây là 1 field tuỳ chọn thêm vào, không phải đổi hợp đồng.

## Read-only review contract (`readOnlyScopeRoots`)

Dành cho caller cần chạy agent **chỉ đọc, giới hạn đường dẫn** (vd `agent-review` review code mà
không được sửa/chạy lệnh gì, và không được đọc ra ngoài phạm vi đã xác nhận). Caller (ở tiến trình
khác, gọi qua IPC/global service) CHỈ gửi `readOnlyScopeRoots: string[]` (mảng string đơn thuần,
đường dẫn tuyệt đối đã canonical hoá) — không tự dựng `tools`/`disallowedTools`/`hooks`, vì một
`PreToolUse` hook là hàm JS, không thể vượt ranh giới IPC (structured-clone) từ renderer của plugin
khác sang main của ai-chat. Việc dựng policy hoàn toàn nằm trong `chat-manager.ts`'s
`connectAgentFor()` (in-process), gọi `tool-policy.ts`'s `buildReadOnlyReviewPolicy(scopeRoots, cwd)`.

Ba lớp, đi cùng nhau (một `disallowedTools` blocklist một mình KHÔNG deny-by-default trước danh
sách tool có thể mở rộng sau này):

1. **`tools: ['Read', 'Grep', 'Glob']`** — allowlist tường minh. Theo SDK đã cài
   (`node_modules/@anthropic-ai/claude-agent-sdk/sdk.d.ts`), option này khai báo "the base set of
   available **built-in** tools", nên mảng tường minh loại hẳn Bash/Write/Edit/Task/Skill/WebFetch/
   WebSearch mà không cần liệt kê từng cái. Nhưng nó **không** kiểm soát tool MCP (tool MCP đến từ
   `mcpServers`) — MCP bị loại nhờ lớp 2 cộng với `mcpServers: undefined` và `settingSources: []`
   bên dưới, chứ không phải nhờ dòng này.
2. **`disallowedTools: ['mcp__*']`** — công tắc tắt MCP theo wildcard, phòng thủ thêm lớp 1.
3. **`pathBoundaryHook`** (trong `tool-policy.ts`) — `PreToolUse` hook chặn mọi lời gọi Read/Grep/Glob
   có target (đã resolve symlink qua `fs.realpathSync`, fail-closed nếu resolve lỗi) nằm ngoài mọi
   scope root đã xác nhận. Dùng `path.relative()` để so khớp chứa, KHÔNG dùng `startsWith` (tránh
   nhận nhầm thư mục anh em cùng tiền tố, vd `C:\proj\foo` vs `C:\proj\foobar`). Grep/Glob khi không
   truyền `path` sẽ mặc định dùng cwd của session (đúng hành vi mặc định của SDK) — hook áp dụng lại
   đúng fallback này để không bị lách qua việc bỏ trống `path`. Hook tự nó cũng deny-by-default: tool
   không nằm trong `Read/Grep/Glob` bị deny thẳng ở hook (không dựa vào việc caller có truyền đúng
   `tools` allowlist hay không); path tương đối (`file_path`/`path`) được resolve tường minh so với
   `sessionCwd` của phiên đó (KHÔNG phải `process.cwd()` của tiến trình main dùng chung cho mọi tab)
   trước khi realpath; nếu **bất kỳ** root nào trong `scopeRoots` resolve lỗi thì cả danh sách bị coi
   là không hợp lệ (deny mọi thứ) thay vì âm thầm bỏ qua mỗi root lỗi và dùng phần còn lại.

   Grep/Glob còn có 2 lớp kiểm tra riêng mà Read (luôn nhắm 1 file) không cần:
   - **Pattern traversal**: `pattern` của Glob và `glob` filter (tuỳ chọn) của Grep bị deny nếu chứa
     segment `..`, hoặc là đường dẫn tuyệt đối (POSIX hoặc `C:\`/`C:/` kiểu Windows) — các giá trị này
     do chính tool évaluate tương đối với base directory đã được hook duyệt, nên một pattern kiểu
     `'../outside/**'` có thể thoát khỏi base đó dù base đã hợp lệ.
   - **Quét symlink lồng trong thư mục**: khi target đã resolve là một **thư mục** (không phải file
     đơn), hook chạy `scanForEscapingSymlinks()` — duyệt đệ quy có giới hạn (bounded, cycle-safe qua
     `visited: Set` để tránh vòng lặp symlink) toàn bộ nội dung thư mục đó; nếu gặp bất kỳ symlink nào
     resolve ra ngoài mọi scope root → deny; đệ quy tiếp vào cả thư mục symlink nếu chính nó resolve
     trong scope (bắt được cả trường hợp thoát qua một chuỗi symlink lồng nhau); nếu số mục duyệt vượt
     `SYMLINK_SCAN_BUDGET` (5000) mà chưa xong → deny (`'too-large'`, không âm thầm dừng giữa chừng rồi
     cho qua). Đây là fix thật trong code, không phải giới hạn chỉ ghi chú lại — quét này chạy trước
     khi Grep/Glob thật sự được phép đụng vào thư mục đó.

Đi kèm bắt buộc: `settingSources: []` cho lượt connect này (không load hook/MCP server nào của
user/project/local `.claude` config), `mcpServers` bị ghi đè thành `undefined` (không khởi động
plugin-control MCP server nào), và **không resume session cũ** — `openTab()` ép `sessionId: null`
bất kể `cfg.sessionId` truyền gì, để một lượt bị giới hạn không kế thừa ngữ cảnh/cấu hình của một
session trước đó (có thể không bị giới hạn). Nếu tab đang giới hạn mà `provider !== 'claude-code'`
(vd API provider) thì `connectAgentFor()` **fail-closed** — trả lỗi thay vì âm thầm "thành công"
không có session sống như nhánh API-provider bình thường.

**Kiểm chứng thực nghiệm (2026-09-10):**
- 22/22 unit test (`tool-policy.test.ts`, `node:test`) pass, gồm test symlink-escape thật (tạo
  symlink thật bằng `fs.symlinkSync` trên máy Windows này — không phải giả lập — và xác nhận bị
  deny) cho cả trường hợp symlink làm target trực tiếp VÀ symlink lồng trong một thư mục được
  Grep/Glob quét, test pattern traversal (`'../outside/**'`, pattern tuyệt đối), test fail-closed khi
  một root hợp lệ đi kèm một root lỗi, test resolve path tương đối theo `sessionCwd`, và test vượt
  ngân sách quét (5001 file thật trong 1 thư mục → deny `'too-large'`).
- Runtime proof thật với SDK sống (`tool-policy.runtime-proof.test.ts`, opt-in qua
  `AI_CHAT_RUNTIME_PROOF=1`, dùng TEMP fixture độc lập, không đụng tiến trình ai-chat đang chạy):
  **đã chạy thành công** (~9s, model thật gọi qua API thật). Model gọi đúng 2 `tool_use`, cả hai đều
  `Read` (không có Write/Bash/Task/Skill/`mcp__*` nào xuất hiện) — 1 lần đọc file trong scope (đọc
  được), 1 lần thử đọc file NGOÀI scope (bị hook deny, nội dung decoy không rò rỉ ra tool_result hay
  câu trả lời cuối). Lưu ý môi trường: khi không truyền `pathToClaudeCodeExecutable`, SDK tự dùng CLI
  đóng gói kèm nó (trong `node_modules/@anthropic-ai/claude-agent-sdk`), bản này cũ hơn CLI hệ thống
  trên PATH và bị API từ chối (`426: client cli version 2.1.220 < required 2.1.258`) — không liên
  quan gì đến logic policy. Trỏ tường minh `pathToClaudeCodeExecutable` vào CLI hệ thống (`where
  claude` → `2.1.267`, cùng cách `claude-cli.ts`'s `resolveCliPath()` làm cho app thật) thì chạy qua.
  `AgentSession`/`connectAgentFor()` trong app thật vốn đã tự resolve `cliPath` theo cách này rồi nên
  không bị ảnh hưởng — đây chỉ là điều cần lưu ý khi tái chạy script kiểm chứng độc lập này sau này.

## Workspace Unity-state contract (`workspaceUnityState`)

Dành cho caller cần agent **chỉ đọc, giới hạn trong 1 workspace**, nhưng **có thêm đúng 1 tool MCP**:
đọc trạng thái Unity Editor của chính workspace đó. Khác `readOnlyScopeRoots` ở chỗ contract cũ tắt
sạch MCP, còn contract này phải mở đúng một cửa — và phải mở mà không làm thủng phần còn lại.

Bật bằng `workspaceUnityState: true`. Caller **không** truyền url/port/tên tool/cwd của endpoint — không
có tham số nào để truyền, và model cũng vậy.

### Endpoint đến từ đâu (`workspace-unity-state.ts` → `resolveUnityStateEndpoint`)

Host tự resolve **trước khi mở tab**, đọc đúng `<cwd>/.mcp.json` của workspace và chỉ lấy entry
`ai-game-developer`. Fail-closed toàn bộ, không đoán:

| Tình huống | Kết quả |
|---|---|
| Không có `.mcp.json`, JSON hỏng, không khai báo `ai-game-developer` | Chặn |
| `type` khác `http`, hoặc entry có `command`/`args`/`env` | Chặn (resolver không chạy gì cả) |
| URL không phải `http:` (https/file/ws), hoặc host không phải loopback | Chặn |
| Thư mục con của workspace có khai báo | Chặn — **không** kế thừa `.mcp.json` của thư mục cha |
| Có server khác trong cùng file (vd `arkon` kèm Bearer token) | Bỏ qua hoàn toàn; credential của nó không bao giờ được mang theo |

Không dò port, không quét `~/.claude.json`, không merge cấu hình. Resolve không chắc chắn → `runAgent`
trả lỗi ngay, **không** hạ cấp thành lượt chạy không giới hạn.

### Vì sao KHÔNG dùng lại `disallowedTools: ['mcp__*']`

Theo SDK đang cài (`0.3.220`), `disallowedTools` là "cannot be used, **even if they would otherwise be
allowed**" — deny thắng allow. Nên không thể chặn `mcp__*` rồi mở ngoại lệ cho proxy: wildcard sẽ giết
luôn chính tool mà chế độ này sinh ra để dùng. Contract này bỏ wildcard và thay bằng **ràng buộc cấu
trúc**, bốn lớp:

1. `mcpServers` chỉ chứa **một** server in-process (`unity-state`) với **một** tool — không có tool MCP
   nào khác tồn tại để model gọi.
2. `settingSources: []` — không nạp MCP server/hook nào của user/project/local.
3. `tools: ['Read','Grep','Glob']` — toàn bộ bề mặt built-in.
4. `PreToolUse` hook (`buildWorkspaceUnityStatePolicy`) cho qua đúng một tên
   `mcp__unity-state__editor-application-get-state`, mọi tên khác rơi xuống `pathBoundaryHook` (dùng
   chung với read-only review) và bị deny-by-default.

**Lưu ý quan trọng đã kiểm chứng:** `tools` trong SDK này chỉ khai báo *built-in tools*, **không** kiểm
soát tool MCP. Đây là lý do lớp 1–2 ở trên là bắt buộc, và cũng là lý do contract `readOnlyScopeRoots`
cũ an toàn — nó an toàn nhờ `mcpServers: undefined` + `settingSources: []` + wildcard, chứ không phải
nhờ `tools`.

Tool proxy khai báo **schema rỗng** (`{}`): không có tham số nào để model đổi hướng nó sang url, port,
cwd hay tool khác. Vì thế hook chỉ cần cho qua theo tên là đủ.

### Transport (`fetchEditorState`)

MCP Streamable HTTP: `initialize` → `notifications/initialized` → `tools/call`
(`editor-application-get-state`, arguments rỗng) → **`DELETE` dọn session** (kể cả khi tool call lỗi,
best-effort, không bao giờ tắt server). Đọc được cả `text/event-stream` lẫn JSON thuần. Có timeout
(mặc định 15s), chặn cứng kích thước phản hồi (256 KiB), `redirect: 'error'` (không đi theo 3xx sang
host chưa qua kiểm tra). Lỗi trả về dạng lý do, **không kèm request header** — auth không bao giờ lọt
vào log/tool result/prompt.

### Tương tác với agent role

Role (`attachedAgentId`) vẫn cấp **persona** (system prompt). Nhưng bundle plugin của role **bị bỏ qua**
ở chế độ này: `connectAgentFor()` dựng `mcpServers` chỉ từ proxy, không gọi
`buildPluginControlMcpServers`, nên role không thể cộng thêm tool vào một lượt chạy bị giới hạn.

Ngoài ra: luôn phiên mới (`openTab()` ép `sessionId: null`), chỉ hỗ trợ provider `claude-code`
(fail-closed nếu khác), và nếu caller truyền kèm `readOnlyScopeRoots` thì giá trị đó **bị bỏ qua** —
một tab chỉ chịu một contract.

### Tình trạng kiểm chứng (2026-09-11)

- Unit test: 39 test mới pass (`workspace-unity-state.test.ts` 12 resolver, `.transport.test.ts` 12,
  `.policy.test.ts` 10, `.mcp.test.ts` 5) + 22 test read-only review cũ vẫn pass sau khi tách helper
  `resolveScopeRoots` dùng chung trong `tool-policy.ts`.
- Runtime proof thật (`workspace-unity-state.runtime-proof.test.ts`, opt-in
  `AI_CHAT_UNITY_PROOF=1`): **đã chạy thành công** với 3 workspace game thử nghiệm → 3 endpoint Unity MCP riêng,
  role điều phối game, model thật. Mỗi lượt chỉ xuất hiện đúng 2 `tool_use`: proxy +
  1 `Read` ra ngoài scope (đã xác nhận bị hook deny với đúng đường dẫn thật). Ba editor trả
  `IsPlaying` khác nhau (true/false/false) — bằng chứng không đấu nhầm dây.
- **Đã kiểm chứng qua `runAgent()` trong app thật (2026-09-11, sau restart).** Gọi qua kênh
  `plugin:ai-chat:run-agent`, 4/4 pass: 3 workspace thử nghiệm đều `ok=true` (3.8–4.7s/lượt),
  và workspace không khai báo endpoint (`drawwindow`) bị **từ chối** đúng như thiết kế
  (`workspace-unity-state bị từ chối: Workspace does not declare an "ai-game-developer" server.`) —
  không hạ cấp thành lượt chạy không giới hạn.

  Bằng chứng lấy từ **transcript `.jsonl` của CLI** (trace thật, không phải lời agent):
  - Mỗi phiên đúng **một** `tool_use` = `mcp__unity-state__editor-application-get-state`, không có
    tool nào ngoài hợp đồng.
  - Transcript nằm đúng thư mục project của từng workspace, `cwd` khớp từng workspace.
  - `IsPlaying` khác nhau giữa 3 editor (true/false/false) → không đấu nhầm dây.
  - Lượt thử phá: model gọi `Read` ra ngoài scope → `tool_result` trả
    `Path outside confirmed review scope: ...\drawwindow\package.json` (đúng chuỗi hook sinh ra),
    nội dung file không rò rỉ; model báo **không có tool Bash** trong phiên.

  Lưu ý: ring buffer `traffic` KHÔNG ghi tab của `runAgent` (chỉ ghi tab UI), nên đừng dùng nó làm
  nguồn trace cho chế độ này — dùng transcript `.jsonl` theo `sessionId` mà `runAgent` trả về.
- Trạng thái editor **không** trả project path (chỉ có đường dẫn cài Unity, giống nhau cả 3 máy).
  Không được kết luận "đã xác minh danh tính project" chỉ từ state/port.
- `readOnlyHint` của MCP **không** phải sandbox bảo mật chống tiến trình cùng OS user.

## Lưu ý / giới hạn

- 1 lần gọi = **1 lượt** (single turn). Muốn nhiều lượt → gọi lại với `sessionId` trả về.
- Mặc định `bypassPermissions` (`allowDangerouslySkipPermissions`): agent tự chạy tool không hỏi phép.
  Nếu cần chế độ hỏi phép, truyền `mode` khác — nhưng permission_request chỉ có UI ai-chat trả lời được.
- Sau khi xong tab bị `closeTab` (kill CLI). Không giữ tiến trình sống giữa các lần gọi.
- Chưa có UI trong widget ai-chat để hiển thị riêng các tab `run:*` — chỉ còn ghi vào ring buffer
  `traffic` phía backend (UI traffic monitor đã gỡ).

## Liên quan

- Muốn **hiển thị** hội thoại streaming (không chỉ lấy kết quả cuối) trong widget của plugin khác →
  xem `.claude/features/embeddable-chat-ui.md` (mount UI chat qua `window.KazuoChatEmbed`, dùng chung
  cơ chế `notifyPluginId` để định tuyến sự kiện tab).
- **Bảo vệ workspace của `agent-review`**: `deleteWorkspace()` (`chat-manager.ts`) từ chối xóa bất kỳ
  thư mục nào nằm dưới `~/.kazuo/agent-review/reviews/`, trả `{ protected: true }` thay vì xóa —
  workspace review tạo bởi `run-agent` không bị người dùng lỡ tay xóa mất báo cáo. Xóa **1 session**
  bên trong workspace đó vẫn được (chỉ chặn xóa cả thư mục). Chi tiết pipeline gọi `run-agent`:
  `.claude/features/agent-review-plugin.md`.


---

# How AI can access this wiki / Cách AI truy cập wiki này
<!-- id: how-to-access source: docs/wiki/how-to-access.md -->

# Cách AI truy cập wiki này

> Three ways to read this wiki: llms.txt, JSON API and the MCP server.

# Cách AI truy cập wiki này / How AI can access this wiki

## Tiếng Việt

Wiki này được sinh tự động từ tài liệu của dự án mỗi lần phát hành trang web, nên luôn khớp với bản hiện tại. Có ba cách đọc:

1. **Tệp tĩnh** — bắt đầu từ `https://kazuo.kaiitech.net/llms.txt` (mục lục theo chuẩn llmstxt.org). Mỗi mục trỏ tới một trang markdown tại `https://kazuo.kaiitech.net/wiki/pages/<id>.md`. Bản gộp toàn bộ: `https://kazuo.kaiitech.net/llms-full.txt`.
2. **API JSON** — `GET /api/wiki/tree` trả cây tính năng; `GET /api/wiki/page/<id>` trả một trang; `GET /api/wiki/search?q=<từ khoá>` tìm theo từ khoá. Mọi route chỉ đọc, không cần đăng nhập.
3. **MCP server** — `https://kazuo.kaiitech.net/mcp` (Streamable HTTP, không cần xác thực) với ba tool `wiki_tree`, `wiki_get`, `wiki_search`. Cài vào Claude Code bằng lệnh:

```
claude mcp add --transport http kazuo-wiki https://kazuo.kaiitech.net/mcp
```

Trong ứng dụng Kazuo AI, mở Settings → Store → MCP và cài `kazuo-wiki` bằng một cú bấm.

## English

This wiki is generated from the project's documentation on every website release, so it always matches the current build. Three ways to read it:

1. **Static files** — start at `https://kazuo.kaiitech.net/llms.txt` (an index following llmstxt.org). Each entry links to a markdown page at `https://kazuo.kaiitech.net/wiki/pages/<id>.md`. Everything in one file: `https://kazuo.kaiitech.net/llms-full.txt`.
2. **JSON API** — `GET /api/wiki/tree` returns the feature tree; `GET /api/wiki/page/<id>` returns one page; `GET /api/wiki/search?q=<keywords>` runs a keyword search. All routes are read-only and need no sign-in.
3. **MCP server** — `https://kazuo.kaiitech.net/mcp` (Streamable HTTP, no authentication) exposing three tools: `wiki_tree`, `wiki_get`, `wiki_search`. Add it to Claude Code with:

```
claude mcp add --transport http kazuo-wiki https://kazuo.kaiitech.net/mcp
```

Inside Kazuo AI, open Settings → Store → MCP and install `kazuo-wiki` with one click.