# Core và extension: mở rộng Soot và Nest

Cái gì thuộc core, cái gì là extension; hợp đồng tool; mở rộng Nest; nhu cầu mới đặt ở lớp nào.

Soot là một runtime cố định. Việc mới của sản phẩm (hỗ trợ khách, đăng bài, đối soát đơn, duyệt hợp đồng) không đi vào binary mà đi vào config, skill, tool và pack. Tài liệu này nói ranh giới giữa core và extension nằm ở đâu, thứ mới nên đặt ở lớp nào, và những gì không bao giờ được thêm vào core.

Tài liệu dành cho người thêm tính năng cho Soot, Nest hoặc viết pack. Quy tắc gốc nằm trong AGENTS.md (Hard constraints); đây là phần giải thích vì sao và cách áp dụng.

## Mô hình

```text
            ┌────────────────────── EXTENSION (không cần build lại binary) ──────────────────────┐
            │  pack = skills + tools (+ interface, pieces, storage, programs, platforms)          │
            │  adapter / ingress (process riêng, deployment khởi động)                           │
            │  Soot definition + deployment.json (config)                                         │
            └───────────────▲──────────────────────────────▲─────────────────────▲───────────────┘
                 soot/v1 envelope (stdin)        channel-adapter.v1 (HTTP)    pack.json (đọc, hiển thị)
            ┌───────────────┴──────────────────────────────┴─────────────────────┴───────────────┐
            │ CORE (internal/core): AgentCore host, store, auth/grants, credentials vault,       │
            │       management, channel host, piece host, workspace, transport/httpapi           │
            │ FEATURE (internal/feature, cắm qua hook): traces, monitoring, train, improve,      │
            │       jobs, mcpserver, autoupdate, browserinstall, adapter                         │
            │ COMPOSE (internal/compose): app, scaffold, features; nơi link feature vào binary   │
            └───────────────▲─────────────────────────────────────────────────────────────────────┘
                            │ HTTP /v1/* + registry
            ┌───────────────┴────────────────────────────────────────────────────────────────────┐
            │ NEST: shell + registry (rail, Settings, Dữ liệu, renderer). Hiển thị, không cấp quyền│
            └────────────────────────────────────────────────────────────────────────────────────┘
```

Ba nguyên tắc cùng một ý:

1. Việc vào Soot trước: event, rồi Soot, rồi (tùy chọn) tool. Không có bộ điều phối nào đứng trước Soot.
2. Workload là config, skill và tool. Thêm một workload không cần build lại binary.
3. Core không import contrib hay pack. Extension cắm vào core qua hợp đồng hẹp, không qua code.

## Khái niệm

| Thuật ngữ | Nghĩa |
|---|---|
| Core | Phần mọi triển khai đều cần và không đổi theo sản phẩm: vòng chạy agent (qua AgentCore), lưu hội thoại, xác thực, cấp quyền, vault, quản lý cấu hình, host cho kênh chat và cho mảnh của Nest. |
| Feature | Package Go dưới `internal/feature/`, không nằm trong core: traces, monitoring, train, improve, jobs, mcpserver, autoupdate, selfupdate, browserinstall, adapter, evalcase. Cắm vào core qua hook, link bằng blank import. |
| Compose | Lớp ghép dưới `internal/compose/`: `app`, `scaffold` và `features`. Được import cả core lẫn feature; feature được link vào binary ở đây. Không core hay feature nào import lớp này. |
| Extension | Thứ chạy hoặc được đọc mà không build lại binary: pack, tool, skill, adapter, mảnh (piece), renderer. |
| Pack | Gói phân phối skills và tools. Soot chọn cả pack. Cài không phải cấp. Mô hình pack và cách chọn: [agents.md](https://trysoot.com/vi/docs/agents/index.md). |
| Tool | Executable khai trong `pack.json` với `run: {program, args, ...}`. Nói chuyện với host bằng envelope `soot/v1`. |
| Adapter | Process riêng nói giao thức một nền tảng (Telegram, Discord, trình duyệt). Deployment khởi động, không phải pack install. |
| Mảnh (piece) | Bundle HTML nhỏ do pack gửi, đặt vào một slot của Nest (`rail`, `home`, `project.tab`, `data.tab`, `settings`). Chỉ là giao diện. |
| Registry của Nest | Danh sách khu (area), slot, mảnh, Settings section, Dữ liệu tab, renderer mà Nest dựng rail và palette từ đó. |

## Core gồm những gì

Ranh giới nằm ngay trong đường dẫn: mọi package dưới `internal/` thuộc đúng một trong bốn thư mục.

| Thư mục | Chứa gì | Luật import |
|---|---|---|
| `internal/core/` | Phần mọi triển khai cần: `config`, `configstate`, `sqlstore`, `authz`, `access`, `credentials`, `conversation`, `channel`, `workspace`, `operations`, `management`, `pieces`, `principal`, `runtime` (engine), `firstrun`, `ledger`, `transport`, cùng các thư viện chúng dùng (`hostio`, `providers`, `toolrun`...). Package `contract` ở gốc module cũng là core. | Chỉ import core (trừ hai cạnh `allow`); không import `compose/` hay `test/` |
| `internal/feature/` | `train`, `improve`, `monitoring`, `traces`, `adapter`, `browserinstall`, `autoupdate`, `selfupdate`, `jobs`, `mcpserver`, `evalcase` | Import core và feature khác |
| `internal/compose/` | Lớp ghép: `app`, `scaffold` và `features` (danh sách blank import) | Import core và feature |
| `internal/test/` | `guard`, `testutil`, `scenarioe2e`, `projecte2e`, `storebench` | Chỉ test dùng |

`contracts/core-layering/layers.json` khai bốn nhóm này và các cạnh core → feature còn được dung thứ. Hiện có hai cạnh: `core/conversation → feature/monitoring` và `core/conversation → feature/traces` (chờ tách conversation). Danh sách `allow` chỉ được co lại.

`TestCoreLayering` kiểm import trực tiếp của từng package core, kiểm toàn bộ closure của `core/config`, và fail khi một package dưới `internal/` không thuộc nhóm nào hoặc thuộc hai nhóm. Core và feature không được import `compose/...` hay `test/...` (import production); core không build cùng lớp ghép.

Các test khác giữ ranh giới:

| Test | Giữ gì |
|---|---|
| `TestCoreLayering` (`internal/compose/app/layering_test.go`) | Core không import feature, `compose/` hay `test/`; feature không import `compose/` hay `test/`; mọi package dưới `internal/` thuộc đúng một lớp. |
| `TestDependencyDirection`, `TestCoreDoesNotLinkContrib` (`internal/compose/app/architecture_test.go`) | `domain` không biết `os` hay HTTP; `runtime` không biết module, provider, transport; không package core nào import `contrib/`. |
| `TestCoreIsCSFree` (`internal/test/guard/`) | Core, contract, `docs/contracts/` và `desktop/src/` không chứa từ vựng của một ngành cụ thể. Danh sách ngoại lệ chỉ được co lại. |
| `TestCoreIsGoalFree` (`internal/test/guard/`) | File không phải test dưới `internal/core/` và `contract/` không nhắc tới lớp mục tiêu (bảng, section `workspace.goals`, thẻ, route, scope của tính năng workspace). Danh sách ngoại lệ `goal_allowlist.txt` chỉ được co lại. |
| `desktop/tests/pack-names-guard.test.mjs` | Không file Nest nào so sánh hay liệt kê id pack, id nền tảng hay `kind` giao diện cụ thể. Danh sách ngoại lệ bắt đầu rỗng và nên giữ rỗng. |
| `desktop/tests/core-words-guard.test.mjs` | `desktop/src/app/` và `desktop/src/lib/` không gọi tên pack, loại dự án, tab, mục đích của đội hay khái niệm công ty (mục tiêu, sản phẩm, chiến dịch), bằng tiếng Anh lẫn tiếng Việt, dù là định danh hay chuỗi. Chỗ còn gọi tên là một dòng trong `core-words-guard.allow.json` (file, số dòng, lý do), và danh sách chỉ được co lại. |

### Hook: feature cắm vào core thế nào

Hook do core giữ; feature gọi `Register*` từ `init()` của chính package đó. Mọi `Register*` panic nếu trùng.

| Hook | Cắm cái gì | Code |
|---|---|---|
| `config.RegisterSection` | Một khối config top-level của feature (`traces`, `monitoring`, `train`...) | `internal/core/config/sections.go` |
| `config.RegisterMemoryLevel` | Một mức memory (workspace, team, soot, user) | `internal/core/config/memlevels.go` |
| `sqlstore.RegisterTenant` | Bảng và migration của feature trong cùng SQLite | `internal/core/sqlstore/tenants.go` |
| `management` `Register(ActionSpec)` | Một hành động cấu hình (`soot.create`...), vừa là lệnh `soot manage`, vừa là tool MCP, vừa là nút trong Nest, có undo | `internal/core/management` |
| `httpapi.RegisterRoutes` | Route `/v1/...` của feature, mount sau route core, trong ranh operator | `internal/core/transport/httpapi/routes.go` |
| `httpapi.RegisterAttention` | Mục trong `GET /v1/settings/attention` | cùng file |
| `httpapi.RegisterHostAttention`, `RegisterCardKind` | Mục attention của host (gom theo nhóm) và loại thẻ theo tiền tố id, kèm mức độ | `internal/core/transport/httpapi/extend.go` |
| `httpapi.RegisterViewField` | Thêm một khóa vào view của core (`GET /v1/workspace/summary`), ghi sau các khóa riêng của view | cùng file |
| `httpapi.RegisterProjectSource` | Nguồn dự án của `GET /v1/projects`: loại, tên, logo. Core tự tính đội nào thuộc dự án nào. Không có nguồn thì danh sách rỗng | `internal/core/transport/httpapi/projects.go` |
| `workspace.RegisterMigration`, `RegisterPortable` | Bảng của feature trong kho workspace (SQLite và PostgreSQL) và các dòng của nó khi chuyển đội | `internal/core/workspace/extend.go` |
| `workspace.RegisterTool`, `config.RegisterHostTool` | Một tool cho model mà feature cung cấp, ngoài các tool Soot tự chọn | `internal/core/workspace/extend.go`, `internal/core/config/host_tools.go` |
| `workspace.RegisterLinkCheck` | Kiểm tra giá trị liên kết của task (trường `goal`); không có thì core giữ nguyên giá trị | `internal/core/workspace/extend.go` |
| `config.RegisterSection` với tên có dấu chấm | Một khối con trong khối của core (`workspace.goals`): đọc strict, cùng khóa JSON, vẫn có trong schema | `internal/core/config/sections.go` |
| `conversation.Service.RunBlock` | Khối ngữ cảnh host gửi kèm một lượt chạy; compose gán | `internal/core/conversation/service.go` |
| `principal.RegisterEraser` | Xóa dữ liệu của một người khi có yêu cầu erasure hoặc hết retention | `internal/core/principal/registry.go` |
| `ledger.Traces`, `ledger.Jobs`, `ledger.Monitor` | Kho trace, job, monitoring mà engine ghi và đọc. Compose gắn kho vào `runtime.Engine`; slot rỗng nghĩa là engine bỏ qua việc kho đó làm | `internal/core/ledger` |
| `configstate.RegisterBundleAdmission`, `RegisterGeneralOpener` | Nhận bundle deploy và mở bản General của Forge cho `management`; `scaffold` đăng ký. Không có hook thì deployment bị từ chối (`bundle_admission_unavailable`) và bản General lỗi `ErrNoGeneralOpener` | `internal/core/configstate/host_hooks.go` |

Link thật nằm ở `internal/compose/features/features.go`: `cmd/soot` và test end-to-end blank-import package này một lần. `internal/compose/app` không import nó. Binary hay test không link `internal/compose/features` sẽ không có section, route hay action của feature, và khóa đó trong deployment thành "unknown field".

Quy tắc đi kèm: kiểu dữ liệu dùng chung giữa core và feature thì nằm ở core ("types move down"). Ví dụ `adapter.Overlay` chuyển xuống `config`.

`internal/core/principal/registry.go` là ví dụ nhỏ nhất của kiểu hook này. File chỉ import `context`, `sort`, `sync`. Mỗi kho có dữ liệu về một người (`packstore`, `piecereceipts`, kênh chat) đăng ký một `Eraser`; route erasure chạy hết, mỗi eraser idempotent. Core không cần biết có những kho nào.

## Tool: hợp đồng executable

Tool là cách mở rộng thường dùng nhất. Hợp đồng công khai là package `contract/` (`contract/contract.go`), không phụ thuộc runtime. Tool không cần SDK Go: đọc JSON từ stdin, ghi text ra stdout/stderr. SDK TypeScript (`@tofound/soot-sdk`, `contrib/sdk/typescript/`) có sẵn types và codec nếu muốn dùng. Kiểu Go của envelope nằm ở `contract/`; schema của `pack.json` xem bằng `soot schema pack`, khung pack mới bằng `soot init-pack`.

```jsonc
// packs/research/pack.json: tên thư mục là id của pack
{ "tools": [ { "name": "inspect",
    "run": { "program": "tools/inspect.sh", "stdin": "context", "timeout": "30s" } } ],
  "needs": { "env": ["HOME"] } }
// Operation ID luôn là <pack>_<tool>: "research_inspect"
```

Model gọi tool bằng chính id của nó (`research_inspect`); tool không khai báo `parameters` thì nhận `{}`. Với `run.stdin: "context"`, host gửi một object JSON, newline, rồi EOF:

```json
{ "api_version": "soot/v1", "hook": "tool.call", "soot": "assistant", "root": "assistant",
  "operation": "research_inspect",
  "event": { "id": "1", "source": "conversation", "subject": "...", "text": "..." },
  "input": { "query": "..." } }
```

Ngoài các field trên, host có thể thêm `project`, `team`, `principal` + `principal_token` (chữ ký 60 giây, xem principal-token), `piece` + `viewer` (khi tool được gọi từ một mảnh của Nest), `approval`, `read_only`. Tool phải chấp nhận field lạ trong v1, từ chối `api_version` hoặc `hook` không hỗ trợ, và coi toàn bộ `event` và `input` là dữ liệu chưa đáng tin. `tool.preflight` là hook thứ hai, hỏi tool có chạy được lời gọi này không trước khi xin người duyệt; hook này không được thay đổi gì.

Muốn model **nhìn thấy** một ảnh tool vừa ghi vào workspace (ảnh chụp trình duyệt, biểu đồ), tool in ra JSON có thêm `"show": ["tmp/shot.png"]` ở cấp ngoài cùng. Host đọc từng đường dẫn trong workspace của cuộc trò chuyện rồi gắn ảnh vào chính kết quả đó. Như vậy model không mất thêm một lượt `read`. Host chỉ gắn file PNG, JPEG, GIF hoặc WebP, mỗi ảnh không quá 16 MB. Số ảnh không bị giới hạn (provider quyết định model đọc bao nhiêu), chỉ tổng dung lượng ảnh của một lời gọi không quá 64 MB; ảnh vượt quá được ghi tên trong kết quả. Đường dẫn tuyệt đối, `..` và symlink ra ngoài workspace đều bị bỏ qua. Ảnh bị bỏ qua được ghi tên kèm lý do, còn lời gọi vẫn tính là thành công. Khi `run_js` gọi tool, chúng chỉ nhận lại phần text (`internal/core/operations/show.go`).

### Phân giải đường dẫn và quyền

| Điều | Quy tắc |
|---|---|
| `run.program` tương đối | Phân giải từ thư mục của pack khai báo; không thoát được bằng `..` |
| Tên trần (`bun`, `node`) | Tìm trong PATH của operator, chỉ cho operation đã được cấp. Pack chưa chọn không đòi dependency |
| Đường dẫn tuyệt đối | Là binding có chủ đích của operator, giảm tính portable |
| argv, thư mục chạy, environment | Lấy từ config đã xác thực. Model không đổi được; `stdin` là kênh duy nhất cho input của model, và input không vào đường dẫn, argv hay env |
| Secret và env | Chỉ host cấp. Pack khai `needs`, host cấp bằng `grants.packs`. Tool không được đặt `run.env` (`pack_tool_env`) |

Thứ tool không bao giờ nhận: prompt, lịch sử hội thoại, cấu hình provider và khóa API của model, nội dung database của Soot. Muốn gọi ngược runtime thì pack khai `needs.runtime` và nhận token hẹp (runtime của chính nó, không phải runtime khác). Muốn lưu dữ liệu thì dùng [pack storage](#pack-storage) bên dưới.

Hiệu ứng: exit 0 là thành công. Lỗi, timeout hay kết quả không rõ được ghi vào effect journal. Cùng operation và input trong một run được replay từ receipt, không chạy lại. Kết quả không rõ giữ resource fence qua restart, operator kiểm tra trước khi thử lại. Đổi tên operation để né fence là sai. Tool chạy lâu khai `run.background: true` để dùng job của AgentCore ([runtime.md](https://trysoot.com/vi/docs/runtime/index.md)). Receipt của job chưa phải kết quả: agent lấy kết quả bằng tool `job` (op `wait` hoặc `status`), và output tool stream ra khi chạy nền thành output trực tiếp của job. Subagent chỉ nhận năng lực mà AgentCore cho phép, không tự mở rộng quyền host đã cấp.

_[0.19.0]_ `run.http` là cách chạy thứ hai, cho công cụ do Soot hay đội tự viết (`tools/<id>/tool.json`) và cho tool trong `pack.json`. Nó không chạy chương trình nào: host gửi đúng một request HTTPS tới host viết sẵn trong URL và khai trong `needs.hosts` (không IP, không cổng, không đi theo redirect, qua client có guard của `2ai`), chèn input vào chỗ đã đánh dấu và khóa (`{{cred:NAME}}`, chỉ trong header hay query) ngay trước khi gửi, rồi xoá khóa khỏi câu trả lời và lỗi trước khi ghi lại. Khóa của công cụ tự viết nằm trong vault theo (chủ, tên), tách khỏi khóa của pack; người nhập trong Nest, không ai đọc lại được. Công cụ `write` đi qua effect journal và chính sách duyệt như tool của pack. Trong `pack.json`, tool khai `run: {http: {...}, mode}` thay cho `program`, `parameters` là input schema, `output.pick` tùy chọn; pack khai host một lần trong `needs.hosts`, và khóa là khóa của pack như mọi tool khác (`needs.credentials`, nhập trong Kho khóa hay cấp qua `grants.packs`). `mode: read` chỉ là `GET` hay `POST`. Mảnh của pack gọi các tool này theo tên (`data.queries`, `data.actions`) và hỏi Soot phục vụ mảnh (`data.ask`). Hợp đồng: `nest-extensions` §14.

`read_only: true` nghĩa là host chỉ cho lượt chạy này đọc (ví dụ bản tin sáng của Lead), nên tool phải từ chối mọi thay đổi. `case_id` là field cũ, tùy chọn; core không tạo hay cấp case. Pack [casework](https://github.com/2found/soot-forge/blob/main/packs/casework/README.md) là ví dụ một workload dùng hợp đồng này mà không thêm vòng chạy hay kho case nào vào core.

## Pack: những gì một pack mang theo

Pack khai báo thứ nó cung cấp và thứ nó cần. Nó không khai danh tính, prompt, route, trigger, lịch hay credential (mấy thứ này thuộc Soot definition và deployment; xem [agents.md](https://trysoot.com/vi/docs/agents/index.md)).

| Phần trong `pack.json` | Tác dụng | Lớp |
|---|---|---|
| `skills/<name>/SKILL.md`, `tools` | Kiến thức và hành động cho agent; skill mang tên trong frontmatter, không thêm tiền tố pack | cấp quyền theo pack |
| `needs` | Credential, env, runtime mà tool đọc | host cấp qua `grants.packs` |
| `name`, `keywords` | Tên và từ khóa cho Nest. Id của pack là tên thư mục | chỉ hiển thị |
| `interface.tool_areas`, `renderers` | Nest vẽ vùng làm việc cho tool đã cấp (trình duyệt, canvas) | chỉ hiển thị, không cấp thêm tool |
| `interface.pieces` | Mảnh HTML đặt vào slot của Nest | chỉ hiển thị |
| `interface.subject` | Thẻ "người này là ai" cho hội thoại kênh | chỉ hiển thị |
| `storage` | Bảng riêng của pack | host cấp phát và scope |
| `programs` | Chương trình pack cần cài trên máy (Chromium...) | qua `check_op`/`install_op` |
| `channel.platforms` | Nền tảng chat mà binding có thể dùng, kèm form cài đặt | chỉ hiển thị |

Contract chi tiết: pack-manifest-ui, pieces, pack-storage.

### Pack storage

Pack khai bảng riêng trong `storage`. Runtime tạo bảng khi một Soot chọn pack, và mỗi lần gọi tool cấp một token chỉ dùng cho lần đó, buộc vào `(pack, soot, workspace)`: tool không tự chọn scope. Chỉ cho đổi cộng thêm; đổi phá bị từ chối và bản pack cũ vẫn chạy. Cột `principal` tự vào erasure. Pack không khai được trigger, view hay SQL thô, nên không mở rộng core sang schema của nó. Gỡ pack thì bảng bị ẩn 30 ngày rồi xóa.

### Chia sẻ pack

Pack là thư mục tự chứa (không trỏ ra sibling, không symlink), cài bằng `soot add` từ Git hoặc archive có checksum. Cài không cấp quyền và không tự cập nhật. Pack dùng chung đi qua pull request vào Soot Forge, nơi release có checksum là nguồn cài mặc định của `soot spawn`. Pack có logic ở service riêng khai `program: "soot"` với `soot tool-forward`, để chạy được trên VM chỉ có binary `soot`; xem `soot tool-forward --help`.

## Adapter và kênh chat

Adapter là process nói giao thức của một nền tảng. Ba điều giữ nó ngoài core:

- Ingress thuộc về nền tảng. Deployment khởi động và gắn tài khoản. Cài hay chọn pack không bao giờ khởi động ingress.
- Không có registry hay lớp phân phối adapter trong core, và không có dispatcher thứ hai.
- Adapter là ống dẫn bền và ngu. Danh tính, admission, ghép đôi (pairing), ánh xạ hội thoại, nội dung gửi đi và mọi câu chữ người dùng thấy đều do host giữ.

Với kênh chat, hợp đồng là channel-adapter (`channel-adapter.v1`, các revision cộng thêm 1.1 đến 1.3). Binding khai trong deployment; runtime chạy adapter như process con có giám sát (argv cố định từ deployment, không từ pack hay model), cấp một token `sca_` chỉ có hiệu lực trên `/v1/channel/*` của binding đó, và chỉ chuyển môi trường tối thiểu (không có khóa provider hay token operator). Adapter từ xa dựng bằng SDK TypeScript (`./channel`) nói cùng hợp đồng. Pack chỉ khai nền tảng nào có thể gắn (`channel.platforms`) và form cài đặt hiển thị trong Nest; secret nhập qua secret sheet vào vault, không vào `pack.json`. Mã host nằm ở `internal/core/channel/`.

## Nest: mở rộng bằng registry

Nest là một super app: giao diện của nó là các mảnh ghép. Nest giữ khung: mảnh được đặt ở đâu, xếp thế nào, được đọc gì. Phần bên trong khung là mảnh, và mảnh có thể đến từ chính Nest, từ pack, hoặc từ một Soot hay một đội tự viết ra. Một màn hình có sẵn hôm nay chuyển được sang pack, và Soot thêm hay sửa được màn hình cho người nó làm việc cùng mà không cần phát hành Nest: nó ghi vài file, người đồng ý một lần, màn hình hiện. Người vận hành giữ quyền cuối: đặt, xếp, quay lại bản trước, gỡ. Nest chỉ mở khung khi sắp được nhìn thấy và cho nó nghỉ khi khuất, nên thêm mảnh không làm Nest nặng lên. Hướng dẫn từng bước cho từng loại tác giả là [build-a-piece](https://trysoot.com/vi/docs/build-a-piece/index.md); chuẩn chung cho mọi loại mảnh (tên gọi, manifest, giao diện, cấu trúc, cách kiểm) là pieces; hợp đồng là nest-extensions.

Nest dựng rail, command palette (⌘K), Settings và Dữ liệu từ các registry trong `desktop/src/app/registry/` (nest-registry v2). Không có chỗ nào trong Nest rẽ nhánh theo tên pack.

Màn hình riêng của Nest cũng là mảnh, khai qua cùng một manifest. Mỗi extension dựng sẵn nằm trong `desktop/src/extensions/<id>/` và đăng ký một lần ở `src/extensions/index.ts`: `inbox` (Hộp việc: khu mở đầu trên rail, nơi vẽ slot `home`), `workspace` (tab mục tiêu, trình quản lý sản phẩm, Kết quả của một dự án) và `support` (tab Hỗ trợ). Shell không xử lý riêng id nào. Mảnh nào giữ slot `home` thì mảnh đó là vùng mở đầu.

Nest là SPA React + TypeScript + Vite trong Tauri 2 (`desktop/`), dùng `@tofound/ui`. Mỗi vùng chức năng là một thư mục `src/modules/<feature>/`; `src/lib/` không import module hay UI; `src/app/` ghép shell và registry. Dữ liệu từ runtime đi qua một adapter duy nhất, `SootClient` (`src/lib/api/client.ts`): TanStack Query cho phần đọc từ host, store kết nối cho hội thoại và SSE. Ở Tauri, Rust giữ credential và chuyển tiếp HTTP đã xác thực; webview không thấy token và không có proxy URL tùy ý. Phần đọc cấu hình, hiển thị và hành vi của pack đến từ catalog của runtime, không có bản sao quyền hay mặc định trong Nest.

| Muốn thêm | Làm gì | Có đổi Nest không |
|---|---|---|
| Vùng chức năng lõi mới của Nest | Thêm một `AreaManifest` (id, nhãn, icon, `lazy` loader, `group`) | Có, đây là thay đổi core của Nest |
| Một màn hình trong rail, trang chủ, Dữ liệu hoặc Settings cho một nghiệp vụ | Pack khai `interface.pieces` với `slot` `rail`, `home`, `data.tab` hoặc `settings` | Không. Runtime liệt kê nó trong `GET /v1/pieces` với ref `pack:<pack>:<id>` |
| Một tab trong dự án (Hỗ trợ, Marketing, Nội dung) | Mảnh `slot: "project.tab"` kèm `tab {id, label}` và `teams` | Không. `provides: ["flow-<id>"]` cũ bị từ chối; link cũ `flow-<id>` mở tab `<id>` |
| Một màn hình Soot hay đội tự làm cho người nó làm việc cùng | Soot ghi `ui/<id>/index.html` rồi `ui/<id>/piece.json` trong file của chính nó (written-pieces) | Không. Lần đầu người được hỏi một lần; các bản sau tự lên, quay lại được |
| Một màn hình dựng sẵn của Nest | Mảnh `builtin` trong một extension ở `desktop/src/extensions/` | Có, nhưng chỉ ở extension đó; `src/app/` không đổi |
| Cách vẽ một loại giao diện mới | Pack khai `renderers` với `bundle`, Nest đóng khung | Không |
| Form cài đặt một nền tảng chat | Pack khai `channel.platforms[].ui` | Không |
| Nút cài chương trình | Pack khai `programs` | Không |

Quy tắc của registry:

- Rail, palette, deep link, lazy load và quyền xem được tính từ `AreaManifest[]`; Settings từ `SettingsSection[]`. `presence: false` nghĩa là không tab, không dòng palette, không link.
- Entry của registry không cấp quyền. Nó vẽ những gì catalog và grants của host đã cho phép.
- Mỗi mảnh của pack chỉ xuất hiện một lần trên mỗi runtime. Runtime chọn Soot phục vụ (`served_by`): Soot Lead nếu nó được cấp view tool của mảnh, không thì Soot đầu tiên theo id trong số Soot người xem vào được. `teams` là các đội có Soot chọn pack đó. Member chỉ thấy mảnh `access: "member"`; danh sách `invalid` (mảnh không Soot nào phục vụ được) chỉ operator thấy.
- Nest đọc `GET /v1/pieces` trên mọi kết nối và gộp lại thành một danh sách theo thứ tự slot (`order`, rồi chủ mảnh, rồi id). Một mảnh là `piece:<kết nối>:<ref>`, nên cùng một ref trên hai máy chủ là hai mảnh, và trên rail là hai dòng, mỗi dòng ghi tên máy chủ.
- Dự án lấy từ `GET /v1/projects` (`{kind, items}`), gộp theo `id` trên mọi kết nối. Tên gọi trên bộ chọn là `kind.label`, không có thì là "Dự án". Nếu runtime trả `kind: null`, danh sách rỗng, 404 hay 405, Nest coi như không có nguồn dự án: không bộ chọn, và các tab `project.tab` của runtime là tab chung của cả workspace. Nest không tự dựng dự án từ nhãn Soot hay từ `GET /v1/workspace/summary`.
- Tab của một dự án là các mảnh `project.tab` (dựng sẵn lẫn runtime), gom theo `tab.id`, tên lấy từ mảnh đầu tiên. Mảnh của runtime là tab của dự án khi một trong các `teams` của nó là đội của dự án trên cùng kết nối. Một Soot làm cho dự án khi nó thuộc một đội của dự án, hoặc nhãn dữ liệu của nó trùng id dự án.
- Shell Tauri chỉ gọi runtime qua `runtime_request`, với một allow-list khai báo trong `desktop/src-tauri/src/runtime_routes.rs`. Route ngoài danh sách bị chặn trước khi rời máy.

### Mảnh và renderer

Mảnh chạy trong khung sandbox, CSP chặn gọi mạng và form, không có credential. (CSP chưa chặn được khung tự điều hướng; Nest đóng khung đã rời bundle, xem pieces.) Nó chỉ chạm runtime qua cầu `postMessage` v2: gửi `call` (mode `view` hoặc `action`), Nest chuyển thành `POST /v1/pieces/{ref}/call` và trả `result`. Phiên mở bằng `POST /v1/pieces/{ref}/session`, bundle tải từ `GET /v1/pieces/{ref}/s/{pvs}/…`. Nest bỏ message lạ và chỉ gửi `call` cho đúng ref của khung. Message `init` mang `viewer {kind}` và `project` (thay `project`/`projects` của v1).

- `view` đọc; `action` ghi, cần `request_id`, gọi lại cùng id trả receipt chứ không chạy lại.
- Tool chạy dưới tên Soot phục vụ, nhận `piece {soot, piece, mode}` và `viewer` trong envelope, với đúng grants và credential như mọi lần gọi khác của pack.
- Tool cần duyệt bị từ chối trên mảnh (`422 tool_refused`, `reason: "approval_required"`), vì mảnh không có bước duyệt. Mảnh `operator` không hiện cho member.

Renderer của pack dùng cùng cầu và CSP. Với tool area cần stream (trình duyệt), host proxy khung hình qua runtime, không nhúng cửa sổ thật: nhúng không đi qua runtime từ xa (cách phần lớn Nest nối với Soot), macOS không có API nhúng cửa sổ process khác và Wayland cấm. Endpoint riêng của trình duyệt (cổng CDP, token, đường dẫn profile) không bao giờ tới client.

## Bề mặt vận hành: MCP và REST

Operator MCP (mcp-operator) là một cách mở rộng khác: để agent ngoài (coding agent, một Soot khác) điều khiển Soot. Điểm cần nhớ:

- Tool MCP được sinh từ registry `ActionSpec` và các read view, cộng tool `view`/`action` của mỗi mảnh (`piece__<pack>__<id>__view`). Không viết tay endpoint cho từng thứ.
- Xác thực bằng token có scope (`sop_`, hiện một lần). Token host không dùng cho `/v1/mcp`.
- Hành động chỉ người làm được (duyệt) gắn cờ `PersonOnly` trên route; token có scope luôn nhận 403. Mọi lời gọi đều vào audit.

Nghĩa là thêm một `ActionSpec` hoặc read view là tự động có mặt ở `soot manage`, trong Nest và trong MCP, cùng một transaction và cùng undo.

## Không bao giờ đưa vào core

| Đừng làm | Vì sao | Làm gì thay |
|---|---|---|
| Endpoint riêng cho một workload (`/v1/refunds/...`) | Mỗi workload trở thành API cố định, phải build lại, lệch khỏi nguyên tắc workload là config | Skill + tool đã có (có thể qua `builtin/toolbox`), hoặc pack mới |
| Registry hay lớp phân phối adapter | Ingress thuộc nền tảng; core mà biết adapter nào thì thành người điều phối | Process adapter do deployment khởi động, nói `channel-adapter` |
| Dispatcher thứ hai (hàng đợi task/case riêng) | Hai bộ điều phối nghĩa là hai nguồn sự thật về ai làm gì | Việc vào Soot trước; job và subagent dùng AgentCore |
| Cho "case", ticket hay worker thành điểm vào bắt buộc | Case là bản ghi tùy chọn, bị động, không chặn event hay tự kích agent | Soot nhận event; pack casework chỉ là tool để ghi |
| Vòng lặp, compactor, reviewer hay job manager riêng | Chỉ có một runtime agent, thuộc AgentCore | Dùng AgentCore |
| `import` từ `contrib/` hay pack trong code core | Core phải chạy khi không có workload nào | Pack và repo sản phẩm giữ kiến thức ngành |
| Rẽ nhánh theo tên pack hoặc nền tảng trong core hay Nest | Mỗi nhánh là một lần build lại cho mỗi pack mới | Khai trong `pack.json` (`name`, `renderers`, `platforms`) |
| Từ vựng ngành trong `internal/`, `contract/`, `desktop/src/` | `TestCoreIsCSFree` chặn; core phục vụ nhiều loại công ty | Để trong pack |
| Nest chạy việc thay runtime | Nest không làm việc của runtime | Sửa runtime đích; xem [runtime.md](https://trysoot.com/vi/docs/runtime/index.md) |
| Cấp quyền từ `interface` | `tool_area`, mảnh, renderer chỉ là hiển thị | Host cấp bằng `grants.packs` |

## Hướng dẫn quyết định

Đi từ trên xuống, dừng ở dòng đầu tiên khớp.

| Tôi muốn... | Đặt ở | Ghi chú |
|---|---|---|
| Agent biết thêm một quy trình, chính sách, giọng điệu | Skill (trong pack, hoặc `SOUL.md`/`MISSION.md` nếu là danh tính) | Không code. `description` nói khi nào đọc |
| Agent làm được một việc có hiệu ứng (gọi API, ghi file, đăng bài) | Tool trong pack | Executable `soot/v1`, tên operation `<pack>_<tool>`, khai `needs` |
| Cùng skill và tool dùng cho nhiều Soot, bật/tắt một lần | Pack | Pack là đơn vị chọn và cấp quyền |
| Pack cần nhớ dữ liệu riêng | `storage` của pack | Không tự mở DB; không trigger, view, SQL |
| Nhận tin từ một nền tảng mới | Adapter (process), binding trong deployment | Nói `channel-adapter`; pack chỉ khai `channel.platforms` |
| Người dùng cần màn hình xem hoặc thao tác dữ liệu của pack trong Nest | Mảnh (`interface.pieces`) | `data.view_tool` đọc, `data.action_tool` ghi, mọi quyền qua tool |
| Canvas hay giao diện sống cho một tool area | `renderers` của pack | Chức năng stream/input theo `capabilities`, không theo `kind` |
| Chạy theo lịch, theo mục tiêu, giao việc | Config (schedule, task, goal) | Thuộc deployment và [workspace.md](https://trysoot.com/vi/docs/workspace/index.md), không thuộc pack |
| Cho công cụ ngoài điều khiển Soot | MCP / REST với token scope; thêm `ActionSpec` nếu cần hành động mới | Không viết endpoint tay |
| Tính năng Go dùng chung nhưng không bắt buộc (một kho dữ liệu, một route, một khối config) | Feature package + hook `Register*` + dòng trong `internal/compose/features` | Đặt package dưới `internal/feature/`; không cần sửa `layers.json` |
| Vùng chức năng lõi mới của Nest | `AreaManifest` mới trong registry | Không rẽ nhánh theo pack |
| Đổi vòng chạy agent, lưu hội thoại, xác thực, vault | Core change | Đi qua AgentCore trước; xem [runtime.md](https://trysoot.com/vi/docs/runtime/index.md) |

Nếu không dòng nào khớp mà bạn đang nghĩ đến "thêm endpoint" hay "thêm một dispatcher", dừng lại và hỏi lại: gần như chắc chắn đó là skill cộng tool.

### Ví dụ: đối soát đơn hàng

Yêu cầu: một Soot đối soát đơn của cửa hàng với bảng sao kê ngân hàng, báo lệch trong Nest, và đăng cảnh báo lên Telegram.

1. Kiến thức đối soát (quy tắc làm tròn, khi nào coi là lệch): skill `reconcile.md` trong pack `reconcile`.
2. Đọc sao kê và đơn: hai tool `fetch_orders`, `fetch_statements` (`run.mode: read`), khai `needs.credentials` cho khóa API cửa hàng. Host cấp bằng `soot grant reconcile`.
3. Ghi kết quả lệch: tool `record_mismatch` (`mode: write`) lưu vào `storage` của pack, bảng `mismatches` với cột `order_id`, `delta`, `status` (cột chữ có `search: true`).
4. Xem trong Nest: `interface.pieces` có một mảnh `slot: "data.tab"`, `access: "operator"`, `data.view_tool` đọc `mismatches`, `data.action_tool` đánh dấu đã xử lý (có `request_id`). Không sửa dòng nào trong `desktop/`.
5. Chạy hằng ngày: schedule trong `deployment.json`, trỏ vào Soot. Không worker mới.
6. Cảnh báo Telegram: binding Telegram trong deployment; pack `chat-channels` đã có adapter. Pack `reconcile` không đụng đến nền tảng.
7. Kiểm: `soot check --show`; test tool riêng với input đúng và sai; eval trong `evals/` của Soot.

Số dòng Go thêm vào core: 0. Không build lại binary. Nếu sau này cần một mức quyền chưa có (ví dụ token MCP chỉ đọc bảng `mismatches`), đó mới là thay đổi core, và nó đi vào `ActionSpec` hoặc scope chứ không vào endpoint riêng.

## Giới hạn và chưa có

- `conversation → monitoring/traces` còn là hai cạnh core → feature được dung thứ, chờ tách conversation.
- Không còn cạnh core → compose hay feature → compose: `TestCoreLayering` từ chối cả hai. `core/runtime` chạm kho trace, job và monitoring qua interface của `core/ledger`; `core/management` chạm bước nhận bundle và bước mở bản General của Forge qua hook trong `core/configstate` (`scaffold` đăng ký). Bản build không link `internal/compose/scaffold` từ chối deployment (`bundle_admission_unavailable`) và bản General (`ErrNoGeneralOpener`) thay vì bỏ qua kiểm tra; engine chưa gắn kho nào thì bỏ qua việc kho đó làm, như khi kho là nil.
- Cơ chế mảnh ghép của nest-extensions chạy ở cả hai phía cho cả bốn loại chủ: mảnh dựng sẵn, mảnh của pack, mảnh Soot và đội tự viết (đề xuất có xem trước, lịch sử bản, quay lại, báo kết quả tải), cùng bố cục riêng của từng người. Còn thiếu: bố cục chưa đi theo người sang máy khác; mảnh `tool-area` chưa thay renderer; khung tự điều hướng chưa bị chặn từ gốc; tác giả chưa có lệnh kiểm và xem trước riêng. Danh sách đầy đủ ở pieces.
- Chưa có SDK Go chính thức cho MCP; transport thuộc core và SDK, khi thêm, nằm sau cùng giao diện đó.
- SDK TypeScript hiện lo envelope tool và client hội thoại; messaging và storage phía SDK còn dự kiến.
- Một vài chỗ trong tài liệu cũ vẫn nhắc `capabilities.<name>` (như `builtin/README.md`); cấu hình hiện tại là phẳng, không còn `capabilities`.
