# Surfaces: nơi con người gặp Soot

Founder, thành viên và khách gặp Soot ở đâu, mỗi người dùng credential gì, và khi nào Soot chờ người quyết.

Một Soot không có giao diện riêng. Con người gặp nó qua các **surface**: Nest, CLI, coding agent (MCP), SDK và widget trên website, và ứng dụng chat như Telegram. Tài liệu này nói ai dùng surface nào, họ thấy gì, project nối vào Soot ra sao, và vì sao mọi surface cùng một bộ luật. Nếu mỗi nơi tự quyết "ai được trả lời, ai được duyệt, khách thấy gì" thì quyền sẽ lệch nhau và lộ dữ liệu mỗi khi thêm một kênh.

## Mô hình: một kernel, một bộ luật

Runtime là kernel. Nó giữ hội thoại, run, mục cần người (attention item), danh tính và mọi quyết định "ai được làm gì". Surface chỉ làm ba việc: hiển thị phần runtime chiếu ra cho nơi đó, nhận lại điều người ta quyết, và gắn đúng người nói vào từng tin. Nó không suy quyền từ loại kênh và không giữ bản luật thứ hai.

```text
 Chủ (operator)        Thành viên          Khách / visitor
 Nest · CLI · MCP     Nest · chat DM       website · app · chat công khai
        │                   │                       │
        ▼                   ▼                       ▼
 ┌─ surface: chiếu dữ liệu, gắn người nói, nhận quyết định ─────────┐
 │  Runtime (kernel)                                                │
 │  hội thoại theo nơi · run · attention item · Authorize()         │
 │  Soot tự quyết trong quyền của nó; hỏi người khi cần             │
 └──────────────────────────────────────────────────────────────────┘
```

Hai hệ quả. Một câu hỏi hay một yêu cầu duyệt ở Nest và ở Telegram là cùng một mục với một câu trả lời; ai trả lời trước thì nơi kia thấy "đã xử lý". Và Soot làm được gì không phụ thuộc người đang nói với nó: công cụ, credential và danh sách việc chờ duyệt nằm trong cấu hình Soot và host. Surface chỉ quyết ai được **nói** và ai được **xử lý** một mục.

## Ba nhóm người và credential

| Nhóm | Là ai | Credential | Thấy gì |
|---|---|---|---|
| Chủ (owner) | Founder, người vận hành runtime | Operator token (Nest, CLI); token `sop_` có phạm vi (coding agent) | Mọi thứ trên runtime, mọi yêu cầu duyệt |
| Thành viên | Nhân viên của chủ | Member key (fixed-user key có `conversations:read_team`, `control`...), hoặc tài khoản chat đã liên kết | Phần việc của họ; approver còn duyệt được việc của các Soot được cấp |
| Khách | Người dùng cuối của project | Trusted backend (`conversation_clients`) đặt `X-Soot-User`; hoặc `spk_` cộng visitor `svs_` cho người ẩn danh | Chỉ hội thoại của chính họ, ở dạng chiếu công khai |

Mỗi loại credential đi qua một cổng riêng và không loại nào thay được loại khác: operator token không xuống browser; key của người dùng gọi route quản trị nhận 403 (chỉ token chưa từng phát hành hoặc đã thu hồi nhận 401); backend tự xác thực user rồi đặt identity, browser không gửi được header đó. `spk_` là khóa công khai chọn một client policy, không chứng minh ai là nhân viên hay khách hàng, nên quyền riêng tư theo tổ chức phải đi qua backend của project. Hội thoại thuộc `tenant/user/Soot`; biết ID không cấp quyền sang tenant khác. Operator connection cố ý không mở sang tenant của khách: chủ nhận **mục cần xử lý**, không đọc transcript của khách. Đổi cấu hình client chỉ có hiệu lực sau khi activate (saved chưa phải active). Khai báo client: `soot schema deployment`; cấp và thu hồi key: `soot auth --help`.

**Ghép máy**: muốn mở Nest của một người trên máy khác, chủ phát một mã dùng một lần; Nest ở máy kia đổi mã đó (`/pair`, `/v1/pair/claim`) lấy device key riêng, thu hồi được từng máy. Bước đổi mã không cần credential nào khác vì mã chính là credential. Chỉ chủ mới phát mã và thu hồi máy.

## Hai loại kênh

Kênh của chủ và đội (Nest, CLI, MCP, Telegram hoặc Discord nội bộ) nói với Lead hoặc Đầu mối, nhận mục cần chủ và trả lời tại chỗ theo vai trò. Kênh của khách (widget, app channel, bot công khai) nói với Soot phục vụ khách do đội gắn vào; mục cần chủ không bao giờ mang nội dung tới đó, khách chỉ thấy một con trỏ không có chữ của host.

Mỗi bot chat thuộc một đội (hoặc một Soot) và chỉ trả lời bằng đội đó. Bot **nội bộ** chỉ cho người đã liên kết nói chuyện. Bot **ngoài** cho khách nói, có giới hạn, và không bao giờ là kênh chat của chủ. Lead nằm trong Nest và không thuộc đội nào, nên không bao giờ là đích của bot; binding của đội chưa có Đầu mối thì chưa có đích. Gắn bot không đổi công cụ, pack, credential hay vai trò của Soot. Xem places-settings.

## Các surface

| Surface | Dành cho | Cổng vào | Mã nguồn |
|---|---|---|---|
| Nest | Chủ, thành viên | Operator connection, hoặc kết nối thành viên | `desktop/` |
| CLI `soot` | Chủ, script, CI | Operator token | `cmd/soot/` |
| Coding agent (MCP) | Chủ, qua Claude Code, Codex, Cursor | Token `sop_`, stdio hoặc `/v1/mcp` | `cmd/soot/mcp.go`, `internal/feature/mcpserver/` |
| Chat channel (Telegram, Discord) | Chủ, thành viên, khách | `/v1/channel/*` với credential `sca_` | `internal/core/channel/`, adapter ở Soot Forge `packs/chat-channels` |
| App channel / bridge | Backend của project, khách trong app: hội thoại riêng của từng người và nơi chung nhiều người cùng đọc (channel-adapter §12) | SDK `@tofound/soot-sdk` | `contrib/sdk/typescript/src/{channel,livechat}` |
| Browser SDK và widget | Visitor trên website | `/public/v1/*` với `spk_`, `svs_` | `contrib/sdk/typescript/src/browser.ts`, `internal/core/transport/httpapi/public*.go` |

Một nền tảng mới là một adapter nói contract channel-adapter, không phải thay đổi trong core ([extensions.md](https://trysoot.com/vi/docs/extensions/index.md)).

### Nhiều kênh, một bộ luật

Thêm một kênh chat không thêm luật nào, vì mỗi tầng chỉ biết một thứ:

1. **Adapter** biết giao thức của nền tảng. Nó dịch mỗi tin về một hình chung: ai nói, ở nơi nào, có gọi Soot không, trả lời tin nào. Nó không quyết ai được nói, không tự trả lời và không viết chữ cho người dùng.
2. **Runtime** biết danh tính và nơi chốn. Nó ghép binding, nơi và người nói thành một hội thoại, quyết ai được nói, và nhớ câu trả lời của hội thoại đó đi đâu ([Ai nói, ở đâu, ai xử lý](#ai-noi-o-dau-ai-xu-ly)).
3. **Soot** chỉ thấy một hội thoại có tin nhắn. Nó trả lời, không chọn kênh hay nơi gửi.
4. **Đường ra** đi ngược lại: runtime gắn địa chỉ vào câu trả lời, adapter vẽ nó theo kiểu của nền tảng (trích tin, con trỏ sang DM).

Quyền đi theo người sở hữu hội thoại (chủ, thành viên, khách), không theo loại kênh, nên kênh mới dùng lại [bộ luật chung](#bo-luat-chung-cho-moi-surface).

Mã của adapter chạy ở ba nơi có mức tin cậy khác nhau, nên có ba dạng đóng gói. Ba dạng này không gộp được thành một gói; thứ chúng dùng chung là luật của host và từ vựng của hai hợp đồng.

| Mã chạy ở đâu | Dạng | Dùng cho | Hợp đồng, credential |
|---|---|---|---|
| Cạnh runtime, do deployment khởi động | Tiến trình `soot-channel` trong pack `chat-channels` (Soot Forge) | Nền tảng có API bot công khai: Telegram, Discord. Người vận hành chỉ nhập token của bot, không viết mã | channel-adapter, `sca_` |
| Trong backend của project | Thư viện: SDK `channel` | Chat của chính app. Chỉ backend của project biết user đã đăng nhập là ai, và tin nằm trong kho của nó | channel-adapter (binding từ xa), khóa binding |
| Trong trình duyệt của khách | Widget, hoặc SDK `browser` | Khách vãng lai trên website. Trình duyệt không giữ được bí mật của server | live-chat-attention, `/public/v1/*`, `spk_` và `svs_` |

SDK `live-chat` là dạng thứ hai cho project đã có hệ thống chat riêng: một cầu inbox/outbox bền chạy trong backend của project.

## Đường đi đầu tiên

Có ba cách bắt đầu, cùng một runtime. Cá nhân: cài app Nest (đóng gói sẵn runtime) hoặc `soot nest`, chọn nhà cung cấp AI, chat với Lead. Terminal: `soot spawn <dir>` tạo workspace và khởi động runtime, `soot check --show` xem quyền đã resolve, `soot run "..."` giao việc. Project: `soot spawn --project <dir>` ghi scaffold (Soot `support`, quyền công cụ rỗng, AI scripted offline, `docs/soot.md` cho coding agent), `soot serve`, thêm kết nối trong Nest, backend gọi bằng SDK.

Model scripted chỉ thử hành vi local; chỉ một lượt chat thật mới chứng minh AI sẵn sàng (`/readyz` và `soot check` thì không). Provider key nằm ở vault của host, Soot không đọc `.env`.

## Nest

Nest là app Tauri (có bản chạy trong trình duyệt) viết bằng React. Mọi quyết định nằm ở runtime; Nest chiếu và gửi lại.

### Cấu trúc trang

Rail là danh sách module trong một registry (`desktop/src/app/registry/areas.ts`). Rail, bảng lệnh ⌘K, link `nest://` và phím tắt đều sinh từ cùng mảng đó, nên thêm một trang là thêm một dòng (nest-registry).

| Khu vực | Việc của nó |
|---|---|
| Hộp việc | Cửa sổ rộng (trên 760 px) luôn có danh sách việc bên trái (một `nav`): dòng Lead ở đầu, rồi ba nhóm cố định Cần bạn, Đang chạy, Xong, và nút soạn việc mới. Mỗi việc một dòng và một luồng; mở một dòng là mở luồng của nó ở bên phải, kể cả thẻ của một việc cần bạn. Chưa chọn dòng nào thì bên phải là trang bắt đầu: ô "Gửi tới" (mặc định Lead, `@đội` hay `@Soot` gửi thẳng), thẻ "Bước tiếp" cho việc cần bạn đầu tiên, số đếm bấm được, mảnh `home`; các dòng không vẽ hai lần. Cửa sổ hẹp (760 px trở xuống) hiện một khung một lúc, có nút quay lại, và trang bắt đầu tự mang ba nhóm. Mỗi nhóm có giới hạn rồi "Xem cả N …"; việc không ai sẽ chạy là một dòng Cần bạn "N việc chưa có ai làm"; nhóm còn khung xám tới khi mọi lượt đọc đã trả lời. Mảnh `home` nằm dưới ba nhóm; mảnh `project.tab` là tab của sản phẩm đang xem (Mục tiêu và việc, Hỗ trợ…). Thay Tổng quan và Cuộc trò chuyện; từ cũ và link cũ mở Hộp việc |
| Đội Soot, Sản phẩm | Soot, nhóm, quyền, kênh của từng đội; gom Soot theo sản phẩm |
| Dữ liệu | Bảng, trí nhớ, tệp, tài liệu ([data.md](https://trysoot.com/vi/docs/data/index.md)) |
| Kết quả | Việc đã xong, chi phí, tự cải thiện ([evolution.md](https://trysoot.com/vi/docs/evolution/index.md)) |
| Trang của Soot | Trang do pack khai báo, runtime phục vụ (pieces) |
| Cài đặt | Chung, Máy chủ, Thành viên (kể cả ai được duyệt), Màn hình, Kho khóa (mọi khóa ở một chỗ, [runtime.md](https://trysoot.com/vi/docs/runtime/index.md#credential-vault-va-redaction)), AI, Quyền (công cụ nào chờ duyệt), Kênh (bot chat, website, SDK và kết nối coding agent), Trình duyệt, Kiến thức công khai, Cập nhật |

Nest hiện dần: nhóm "Quản lý" chỉ hiện khi có từ hai Soot, có trang dữ liệu, hoặc chủ tự bật; ẩn thì vẫn mở được bằng ⌘K và link. Người mới thấy một đường chính: nói với Lead. Việc quen thuộc của người quản lý không rành kỹ thuật: xem đội làm gì và duyệt ở Hộp việc › Cần bạn; giao việc trong ô "Gửi tới" của Hộp việc, tạo Soot, lập đội, đặt lịch bằng cách nhắn Lead; nhận khách khó qua mục chuyển giao; đặt chat lên website ở Đội Soot › đội › Kênh.

### Lead và Đầu mối

Lead là trợ lý của chủ trong Nest. Mỗi server có một Lead, tên luôn là "Lead", nằm ngoài mọi đội. Chỉ Lead có công cụ quản trị (`nest-lead_manage`): tạo Soot, lập đội, đặt lịch, đổi model, cấp quyền dữ liệu. Các thao tác đi qua cùng management action với màn hình thủ công, cùng revision và receipt, nên không có bản cấu hình thứ hai trong prompt. Việc đảo ngược được thì Lead làm ngay rồi báo kèm link; xóa, nới quyền, tăng ngân sách vào Cần bạn. Lead không bao giờ nói là "đã tạo" khi chưa có receipt. Màn hình thủ công vẫn còn, là đường dự phòng.

Mỗi đội có một **Đầu mối**: Soot nhận việc đầu tiên của đội, chạy lịch của đội và trả lời bot của đội. Đầu mối không có quyền quản trị. Xem [agents.md](https://trysoot.com/vi/docs/agents/index.md) và contracts/lead.md.

### Nhiều runtime trong một Nest

Một Nest nối được nhiều runtime (máy local, server, VM). Soot, đội và việc được gộp từ mọi kết nối; khái niệm máy chủ chỉ lộ khi hai Soot trùng tên hoặc khi chủ chọn lọc theo máy ở thanh cửa sổ. Mỗi kết nối có operator key và định danh riêng.

Nest tin từng server riêng (Cài đặt › Máy chủ). `GET /v1/runtime` trả `runtime_id` bền; đổi định danh thì Nest hủy phiên và xóa cache. Khóa operator ở bản đóng gói nằm trong kho riêng của app, ở bản trình duyệt chỉ nằm trong bộ nhớ trang, không bao giờ ở URL hay web storage. Browser gọi thẳng server cần HTTPS và `browser_origins` (`soot schema deployment`). Các lần đọc một màn hình hỏi cùng lúc đi chung một `GET /v1/reads` (mỗi lần đọc vẫn qua đúng quyền của khóa; `work-reads` §4), nên kết nối lần đầu tới máy chủ ở xa tốn hai lượt đi về: `GET /v1/runtime` rồi một lô.

Ngắt kết nối chỉ ngừng quan sát, không dừng hay hoàn tác việc trên server.

Thêm server bằng link ghép máy (Cài đặt › Máy chủ › Thêm máy chủ). Cài đặt › Thành viên gộp người theo mã người trên mọi server: một người, nhiều thiết bị, quyền theo đội và Soot; quản trị không phải chọn server. Một đội đổi server bằng ⋯ › Chuyển sang máy chủ khác… ([runtime.md](https://trysoot.com/vi/docs/runtime/index.md#chuyen-doi-sang-runtime-khac)).

### Cài đặt: lưu, áp dụng, thử

Cấu hình thuộc server đang chạy runtime, không thuộc Nest. Nest hiển thị bản **đã lưu** và bản **đang chạy** riêng vì chúng có thể khác nhau.

Bốn bước: kiểm tra (chỉ hỏi host, không lưu, không gọi model), lưu (một revision), áp dụng (host chuyển sang revision đó, có thể chờ việc đang chạy; chỉ nhãn "Đã áp dụng" xác nhận bản đang chạy) và thử (một lượt chat thật, chỉ khi bản lưu trùng bản chạy).

Ghi đi kèm `expected_revision` và `request_id` ổn định. Xung đột (409) giữ bản nháp để người đọc bản mới rồi gửi lại. Mất phản hồi thì Nest hỏi lại receipt bằng GET, không POST lặp. Bí mật chỉ nhập ở Nest hoặc CLI trên host, không dán vào chat vì hội thoại được ghi lại; khi cần, Lead mở một form an toàn.

## Cần bạn: nơi con người quyết định

Sự chú ý của chủ là thứ khan hiếm nhất. Soot tự quyết mọi thứ trong thẩm quyền và chỉ tìm người khi: host chọn chặn hành động (tiền, đăng công khai, xóa); chỉ người làm được (đăng nhập, cắm credential); ngoài thẩm quyền (giá, ngày, lời hứa); hoặc không ai biết điều gì đã xảy ra (lệnh ghi hết thời gian chờ). "Muốn có ý kiến thứ hai" không phải lý do. Mỗi lần hỏi là một quyết định: một dòng nói cần gì và vì sao, các lựa chọn với đề xuất của Soot, việc Soot đã làm, và link tới đối tượng. Người chọn một nút hoặc viết một dòng.

Nest có một nơi duy nhất cho việc này, Hộp việc › Cần bạn, một danh sách và một số đếm dùng chung cho huy hiệu rail và tiêu đề cửa sổ. Mỗi mục mang một trong ba động từ: Trả lời (câu hỏi, chuyển giao), Duyệt (quyết định, cấp quyền, mục mà một need view vẽ như màn hình hay bố cục Soot đề xuất), Sửa (lỗi).

| Mục (`kind`) | Do đâu mà có | Người trả lời bằng |
|---|---|---|
| Duyệt (`approval`) | Soot gọi công cụ mà host chặn | Duyệt và chạy, hoặc Từ chối kèm lý do Soot đọc được |
| Quyết định (`decision`) | `report_blocker` có lựa chọn | Chọn nút, hoặc một dòng chỉ dẫn. `if_unanswered` cho phép im lặng thì chọn mặc định, chỉ với lựa chọn đảo ngược được |
| Chuyển giao (`handoff`) | `report_blocker` không có lựa chọn | Tự làm rồi bấm "Đã xử lý" |
| Cấp quyền (`grant`) | Soot xin kho dữ liệu hoặc pack chưa có | Cấp và tiếp tục, hoặc Từ chối |
| Cấp dòng hợp đồng (`need`, id `contract-grant:<id>`, action `contract.grant`) | Soot đội A bị từ chối khi đọc bảng hay ghi hàng đợi của đội B, rồi xin bằng `report_blocker` grant kind `contract`; mọi lượt xin cùng một dòng là một mục | Cấp và tiếp tục, hoặc Từ chối kèm lý do (`POST /v1/settings/contract-grants/{id}`, `soot teams grant` / `decline`; [workspace.md](https://trysoot.com/vi/docs/workspace/index.md#cap-dong-hop-dong-khi-can)) |
| Câu hỏi (`question`) | `ask` trong hội thoại tương tác | Trả lời |
| Kết quả chưa rõ (`unknown_outcome`) | Lệnh ghi không biết thành hay bại | Kiểm tra đích rồi chốt |
| Lỗi, lịch, credential thiếu, ngân sách token, đề xuất cải thiện, kiến thức lỗi thời | Runtime phát hiện | Sửa nguyên nhân, chạy lại, bỏ qua, áp dụng hoặc bỏ |
| Thẻ (`card`) | Một bước của lịch trả `raise`, không tốn model | Chọn nút. `id` chỉ lập một lần, nên công cụ nêu lại thẻ mỗi nhịp mà không giữ trạng thái |
| Việc gửi đi vòng lại (`mail_loop`) | Việc gửi qua lại giữa các đội quá `mail.max_hops` lần | Bắt đầu tay, hoặc bỏ |
| Việc gửi chưa chạy (`mail_held`) | Việc gửi tới một đội chưa có Đầu mối (`team_needs_coordinator`), đội chỉ nhận việc đã duyệt (`inbox_hold`), bắt đầu lỗi (`start_failed`), hoặc đội gửi đã đủ số việc trong ngày (`mail_rate_limited`); `payload.code` nói lý do | Chọn Đầu mối ngay trong Hộp việc (việc tự chạy), hoặc bắt đầu tay |
| Việc chưa tới (`mail_undelivered`) | Việc gửi cho đội ở runtime khác chưa tới sau 30 phút, hoặc bị từ chối hẳn (`mail_not_granted`, `mail_unsupported`, …) | Thử lại ngay (`POST /v1/workspace/mail/sync`), hoặc sửa quyền ở runtime kia |
| Việc chờ bạn (`task_waiting`, id `task-waiting:<task>`) | Một việc đang mở bị chặn, chờ duyệt, là việc của chính bạn, hoặc lần chạy cuối dừng chờ người hay lỗi (`payload.state`: `waiting`, `blocked`, `failed`); không có mục này khi một mục khác đã đứng cho cùng việc (need của luồng việc, thẻ thư, thẻ lịch) | Mở luồng việc rồi trả lời, gỡ chặn hoặc chạy lại |
| Việc chưa có ai làm (`tasks_unowned`, id `tasks-unowned[:<sản phẩm>]`) | Việc `todo` chưa giao ai hoặc chưa ai bấm Bắt đầu, không phải thư; một mục cho mỗi sản phẩm, `payload.count` và tối đa 20 việc mẫu (`payload.sample`), phần còn lại đọc qua danh sách việc | Giao cho một đội hay Soot rồi bắt đầu, hoặc đóng lại |
| Khách chờ bạn trả lời (`live_chat_handoff`, id `live-chat:<phiên>:<lượt>`) | Soot chuyển cho người một chat của khách (app, website, kênh) bằng `report_blocker` không có lựa chọn; mục ở tenant của khách (live-chat-attention) | Trả lời khách ngay trong Cần bạn rồi trả lại Soot (`POST /v1/sessions/{id}/member-messages`, `/control`; chỉ chủ, không qua token có phạm vi) |

Mỗi mục có `severity` (`error`, `warning`, `info`); nhóm theo mức này chứ không theo `kind`. Việc do eval tạo ra bị loại khỏi danh sách trừ khi hỏi rõ. Danh sách: `soot attention list`; trả lời: `soot attention answer`. Số đếm là số mục runtime trả về: Nest không tự đếm thêm từ danh sách việc, nên huy hiệu rail, tiêu đề cửa sổ, đầu nhóm Cần bạn và `soot attention list` nói cùng một số.

Gửi việc cho một đội ([workspace.md](https://trysoot.com/vi/docs/workspace/index.md#gui-viec-viec-la-tin-nhan)) là `soot tasks send --to team:<id> "…"` hoặc `POST /v1/workspace/tasks` với `deliver: true`; Lead gửi bằng `send` trong công cụ workspace. Việc có trường `mail` (đường đi, trạng thái, `reply`); các mốc là sự kiện `mail_delivered`, `mail_held`, `mail_reply`. Trong Nest, ô "Gửi tới" của Hộp việc gửi việc theo đúng đường này; gửi cho Lead vẫn là một cuộc trò chuyện (`mail_for_lead`). Việc gửi đi là một dòng ở Đang chạy, kể cả khi chưa tới nơi; một mã từ chối thành một câu và một nút sửa (`retarget`, `reconnect`, `coordinator`, `budget`, `start`, `sync`).

Pack khai báo mặc định `"approval": "operator"` cho một công cụ, an toàn cho host lạ. Host sở hữu quyết định thật qua `grants.approvals` trong deployment, ghi đè pack cả hai chiều; chỉ deployment của host mới nới được. Nest hiện mọi công cụ bị chặn trong Cài đặt › Quyền với 30 ngày quyết định, và gợi ý "Để Soot tự chạy" cho công cụ đã duyệt nhiều lần mà chưa từng bị từ chối: quyền tự chủ tăng theo điều chủ đã chứng tỏ chấp nhận. Thông báo hệ điều hành theo cùng danh sách: duyệt và kết quả chưa rõ báo ngay, mục khác báo một lần hoặc gộp.

Cùng các mục đó đến DM đã liên kết của chủ trong Telegram hoặc Discord, kèm nút cho lựa chọn trả lời tại chỗ; việc nút không giải quyết được thì có link về Nest.

## Bộ luật chung cho mọi surface

Các luật này nằm trong code (`internal/core/authz`, `internal/core/channel`, `internal/core/conversation/attention.go`) và được contract kiểm bằng fixture.

| Luật | Nội dung |
|---|---|
| Một mục, một câu trả lời | Giải quyết ở đâu thì mọi nơi khác thấy đã xử lý |
| Hỏi ở nơi việc phát sinh | Chỉ `question` (và `decision` cho người hỏi đã liên kết) xuất hiện ở nơi chung |
| Danh sách đóng | Loại mục khác chỉ đến nơi của chủ; loại mới mặc định cần quyền `own` |
| Chỉ người hỏi trả lời | Người khác, kể cả chủ, nhận `403 not_asker` |
| Con trỏ, không nội dung | Mục chỉ dành cho chủ gặp khách hoặc nơi chung chỉ để lại tối đa một dòng cố định |
| Riêng tư | Bí mật chỉ ở Nest. Nơi chung và live chat nhận bản chiếu công khai. Dữ liệu theo người được tra từ nơi hội thoại, không từ chữ trong tin |
| Chữ do ai viết | Host viết câu cho người dùng Nest và chat. Với khách, runtime chỉ gửi mã; client viết chữ |
| Soot là ranh giới quyền | Công cụ, phạm vi credential, cấu hình duyệt và grant quyết định run làm được gì, giống nhau ở mọi surface |
| Ai cũng được nói | Liên kết không phải cổng; lạm dụng xử lý bằng giới hạn và danh sách chặn |

## Ai nói, ở đâu, ai xử lý

Mỗi tin đến từ một **người nói** (`speaker`) có id ổn định, không lộ handle nền tảng. Hội thoại khóa theo **nơi**, không theo người: một DM, một nhóm hay thread, một thread của bridge, một phiên widget. Mọi người trong nơi đó thấy trả lời của Soot, nên transcript là chung và gắn tên người nói. Khi một run đang chạy, tin mới của cùng người nói được hấp thụ vào run đó (lái run); tin của người khác xếp thành run riêng. Câu hỏi mở thuộc về người hỏi: tin người khác không trả lời và không đóng nó. Luật này nằm ở `internal/core/conversation/steer.go`, nên chat host, bridge và widget cư xử như nhau.

**Liên kết** thay cho ghép cặp: ai trong nơi chung cũng nói chuyện được với Soot, không phải làm gì trước. Liên kết (mã dùng một lần từ Nest, gửi cho bot) chỉ nói "tài khoản chat này là người Nest kia", để DM của họ nhận mục của chủ và nút bấm mang đúng vai trò. Người chưa liên kết bị giới hạn theo người và theo pool của binding (pool `0` nghĩa là chỉ người đã liên kết nói được), cộng danh sách chặn; vượt giới hạn thì nhận một thông báo rồi im lặng. Số mặc định: `internal/core/channel/places.go`, `internal/core/config/channels.go`.

Một hàm `Authorize(principal, place, action, item)` (`internal/core/authz/authorize.go`) trả lời cho mọi surface, chạy lại ở mỗi lần bấm và không cache vai trò.

| Vai trò | Ai | Phạm vi |
|---|---|---|
| `owner` | Operator connection, tài khoản chat của chủ | Tất cả |
| `approver` | Thành viên chủ cấp (mọi Soot hoặc vài Soot) | `handle` và `approve` cho Soot được cấp |
| `member` | Khóa có `read_team` và `control` | `handle` việc chuyển giao của các Soot trong khóa |
| `anyone` | Người chưa liên kết, khách, visitor | Chỉ nói, và trả lời câu hỏi của chính mình |

`handle` là việc của đội (chuyển giao, quyết định, tiếp quản live chat). `approve` là duyệt công cụ và chốt kết quả chưa rõ. `own` là mọi thứ còn lại của chủ: cấp quyền, ngân sách, kênh, vai trò. Quyền thành viên không rộng hơn khóa của họ.

| Nơi | Mục chỉ dành cho chủ |
|---|---|
| Nest | Có, theo vai trò |
| DM của người đã liên kết | Có, nếu vai trò xử lý được |
| `owner_chat` (nhóm chat chủ chỉ định bằng mã `/owner`) | Có, thay DM của chủ. Ai cũng thấy tiêu đề và lựa chọn; bí mật và diff ở Nest. Ai không đủ quyền bấm nhận `403 not_authorized` |
| Nơi chung, live chat | Không bao giờ; tối đa một con trỏ |

## Project nối vào Soot (SDK)

Project dùng `@tofound/soot-sdk` (`contrib/sdk/typescript/`; cách dùng ở README của nó) để nối vào cùng runtime. Các đường chính:

| Muốn | Dùng | Credential |
|---|---|---|
| Backend chat với Soot thay cho user đã đăng nhập | Conversation API, SDK `client` | `conversation_clients` |
| Hệ thống ngoài báo việc (alert, webhook) | `POST /v1/events` qua adapter của bạn | operator token, chỉ ở backend |
| Giao một việc nền, nhận kết quả có cấu trúc | `/v1/jobs`, SDK `jobs`, `soot jobs` | operator hoặc `sop_` scope `jobs` |
| Khách vãng lai chat trên website | Widget hoặc SDK `browser` | `spk_` và `svs_` |
| Chat của chính app là giao diện | SDK `channel` hoặc `live-chat` | khóa binding |
| Tool của Soot gọi API của bạn, cần biết ai đang nói | Principal token | JWKS của host |

Các khái niệm cần nắm:

- **Run.** Gửi tin tạo run `queued`, rồi `running`, rồi `completed`, `failed` hoặc `stopped`; `waiting_input` là Soot hỏi lại người dùng và đã dừng thực thi, câu trả lời là một message mới. Khi POST mất phản hồi, giữ conversation ID, request ID và run ID rồi đối soát bằng GET; gửi lại như một run mới sẽ bỏ qua trạng thái chưa rõ. Lỗi run có mã ổn định, không lộ lỗi thô của provider.
- **Event.** `(soot, source, subject)` xác định hội thoại; `id` là khóa retry. Core không có receiver riêng cho từng vendor: adapter của bạn xác thực webhook rồi chuẩn hóa. Phản hồi 202 là đã nhận bền vững, chưa phải đã xong. Core không có case hay takeover cho event; việc đó thuộc pack. `text` tối đa 64 KiB UTF-8 và Soot đọc trọn; dài hơn bị từ chối 400 kèm giới hạn.
- **Job.** Một lần chạy nền của Soot hoặc đội, có `idempotency_key`, kết quả JSON và callback ký JWS (xác minh bằng JWKS của host). Job chỉ là cổng vào; theo dõi nội bộ thuộc [workspace.md](https://trysoot.com/vi/docs/workspace/index.md). Hợp đồng: jobs. `task`, `input` và `output_schema` tới model trọn vẹn, ngay trong run (tối đa 60 KiB văn bản run); vượt thì bị từ chối `invalid_job` kèm giới hạn, không bị cắt.
- **Public web.** Khách chat ngay trên website, không qua backend của bạn: `spk_` cộng challenge đổi lấy phiên `svs_` ngắn hạn. Vì khóa công khai, khách bị chặn bởi ngân sách và chính sách của client, và các Soot được lộ ra chỉ được dùng công cụ đọc. Widget (nguồn ở Soot Forge `packs/live-chat/widget/`, được runtime phục vụ ở `/public/widget/*`) giữ credential ngoài trang chủ trong iframe; adopter muốn UI riêng dùng SDK `browser`, cùng mô hình.
- **Kênh của app.** SDK `channel` là adapter chế độ server của channel-adapter: host giữ gộp tin, lượt và owner, SDK không tự trả lời, và chỉ ack sau khi đã ghi vào store của bạn. SDK `live-chat` là cầu inbox/outbox bền: gửi lỗi thành `uncertain`, không bao giờ tự gửi lại.
- **Principal token.** Một JWS ngắn hạn cho mỗi lần gọi tool, để API của bạn biết người trong hội thoại mà model không chọn hay thấy: principal-token.

## Live chat và khách

Khách chỉ trả lời được **câu hỏi** của chính họ. Câu hỏi hiện thành thẻ có nút, hiện một lần, và đóng lại với kết quả đã chọn. Việc cần chủ (duyệt, chuyển giao, quyết định) không đến khách; khách nhận một con trỏ chỉ có mã (`team`, `approval`, `not_ready`, `unavailable`) và client tự viết chữ, hoặc không hiện gì nếu Soot đã tự trả lời. Runtime không viết chữ cho khách.

Các quyết định thiết kế đáng nhớ: đây là hợp đồng anh em của `channel-adapter` (cùng từ vựng mục, hai ranh giới tin cậy khác nhau, vì khách không phải người dùng Nest); quyền của người hỏi do runtime ép, không do client; và widget không có luật riêng, mọi trạng thái attention nằm trong SDK `browser` để đổi luật chỉ cần nâng runtime.

Khi cần người thật, thành viên có `read_team` và `control` thấy hội thoại live chat trong Nest, tiếp quản, trả lời công khai dưới tên mình, hoặc nhắn riêng cho Soot (khách không thấy). Trong lúc người giữ hội thoại, tin mới của khách vẫn được lưu và hiện cho thành viên, Soot không tự chạy.

Trạng thái hiện tại: runtime đã chiếu thẻ câu hỏi, kết quả và con trỏ (`internal/core/conversation/attention.go`, sự kiện `attention.pointer`, khả năng `live-chat-attention-v1`). Hợp đồng live-chat-attention và places-settings đã chuyển sang dự án `soot-cs-engine` (`internal/test/guard/cs_allowlist.txt` giữ bản sao ở đây cho tới khi gỡ); đừng sửa bản sao. Phần chăm sóc khách (console, chính sách chuyển giao) là extension, không thuộc core: [extensions.md](https://trysoot.com/vi/docs/extensions/index.md). Bridge `cs/` cũ đã bị xóa; project production dùng app channel của SDK.

## CLI và coding agent

`soot` là surface cho script, CI và người ưa terminal; mọi thao tác quản trị là cùng management action với Nest. `soot --help` liệt kê lệnh.

Chủ cũng điều khiển Soot từ Claude Code, Codex hay Cursor. `soot mcp` (stdio, máy local) hoặc `<server>/v1/mcp` (HTTP, server từ xa) sinh công cụ từ cùng registry hành động với CLI. Token `sop_` có phạm vi (`read`, `jobs`, `manage`, `data`) tạo ở Cài đặt › Kênh › Kết nối coding agent hoặc `soot tokens`, chỉ hiện một lần, và là credential riêng (`SOOT_MCP_TOKEN`), không phải operator token. Con người vẫn giữ quyết định: duyệt, cấp quyền, nhả mục bị giữ và tạo hay thu hồi token **không có** trong MCP và bị từ chối với token có phạm vi (`approval_needs_person`). Coding agent của bạn không tự cho Soot `support` quyền sửa file hay chạy shell. Hợp đồng: mcp-operator.

## Việc gửi đi qua các surface

Ai được giao việc cho đội tùy vào hội thoại thuộc về ai, không tùy loại kênh. Hội thoại nằm trong không gian của chủ (tenant `operator` và không phải live chat) thì Soot có công cụ `task` ghi được và có `send`. Đó là chat trong Nest, DM của chủ với bot đã ghép trên Telegram hay Discord, và chat của chủ qua coding agent. Run chỉ đọc không gửi được: eval, dry run và bản tin của Lead. Khách, thành viên và app nối bằng SDK không bao giờ gửi việc vào không gian của chủ. Cả ba chỗ đều đọc một hàm `conversation.InOwnerWorkspace` (`internal/core/conversation/reach.go`).

Việc Soot gửi từ chat của chủ là thư của Soot, không phải của người. Vì vậy mọi giới hạn vẫn áp: số bước trong một chuỗi, giới hạn mỗi ngày, đội đang giữ hộp nhận.

Câu trả lời quay về nơi người đã hỏi. Khi Soot gửi hoặc bắt đầu việc từ một chat ngoài Nest (DM đã ghép), lúc đội trả lời xong Soot được chạy thêm một lượt trong chat đó để báo cho người, như khi Soot tự chọn `wait`. Mỗi câu trả lời chỉ đánh thức một lần. Không áp dụng khi Soot đang làm cho đồng đội, và câu trả lời `needs_person` không đánh thức. Hàm: `conversation.AnswersOutsideNest`.

Trong lúc chờ, người ở surface nào cũng không bị mù. Khi việc dừng vì chờ một người ở đâu đó trong chuỗi (kể cả ở máy chủ khác), khi quá `due`, hay khi chạy lâu (báo lại thưa dần), host đưa một dòng cho phía người gửi. Chat của khách qua intake nhận một lượt để nói với khách việc đang ở đâu. Soot đã gửi với `wait` nhận một lượt trong thread đó. Nest đọc trên nhật ký việc (`mail_progress`). Dòng đó chỉ nói việc đang ở đâu, không lộ đội hay người. Luật chung ở work-mail D6.

Coding agent có cùng một cửa gửi việc: công cụ MCP `task_send` (cùng phạm vi với `task_start`) gọi đúng hàm gửi mà `POST /v1/workspace/tasks` với `deliver: true` và `soot tasks send` gọi. Người gửi ghi là `mcp:<token>`.

Với khóa thành viên, Hộp việc là các hội thoại do chính khóa đó mở (`GET /v1/workspace/inbox`). Thành viên không thấy task, không thấy việc của chủ, của thành viên khác hay của khách, kể cả qua `GET /v1/reads`. "Gửi tới" chỉ có những Soot và đội mà khóa được nói chuyện, và gửi là mở một hội thoại với Soot đó. Mọi route `/v1/workspace/*` khác vẫn chỉ của chủ; thành viên gọi `POST /v1/workspace/tasks` nhận `403`.

Từ khách tới việc là do người làm. Thẻ chuyển giao của khách ở Cần bạn có nút "Giao cho đội". Nút mở ô giao việc của Hộp việc, điền sẵn câu Soot tóm tắt điều nó cần (Soot không tóm tắt thì là một tiêu đề chung) và một dòng nói việc đến từ chat của khách, kèm nơi khách viết. Nest không chép tin nhắn của khách, kể cả câu đầu tiên của họ, và không mang mã hội thoại. Chủ đọc, chọn "Gửi tới" rồi tự gửi; thẻ vẫn ở Cần bạn.

Chủ cũng có thể mở sẵn một cửa cho một loại báo cáo: intake (contract intake). Trong deployment, chủ khai các trường của báo cáo, Soot nào được nhận và đội nào trên runtime này xử lý. Soot đó có thêm công cụ `file_report`. Đây không phải `send`: khách vẫn không gửi được việc, chỉ đi qua cửa chủ đã mở, tới đúng đội chủ đã chọn. Thư tới đội chỉ có nội dung: các trường, lời tóm tắt của Soot, câu người báo viết nếu có, và số người đã báo. Runtime giữ chỗ trả lời từng người báo cùng với việc, không đặt vào thư. Đội nhận không bao giờ biết báo cáo đến từ đâu: không mã hội thoại, không tên, không kênh. Báo trùng chủ đề thì gộp vào việc đang mở. Khi việc xong, lỗi hay bị chặn, runtime đánh thức Soot đã nhận báo cáo trong từng hội thoại có người báo, mỗi hội thoại một lượt. Ai được trả lời ở đâu xem [Ai nói, ở đâu, ai xử lý](#ai-noi-o-dau-ai-xu-ly); phần việc của runtime, adapter và pack xem [Ranh giới: ai sở hữu gì](#ranh-gioi-ai-so-huu-gi).

Khi thêm một surface mới:

1. Hội thoại của nó thuộc tenant nào? Chỉ chủ là `operator`; người khác ở tenant của họ.
2. Không thêm luật theo `Source.Kind`: quyền gửi việc đọc `InOwnerWorkspace`, câu trả lời về chat đọc `AnswersOutsideNest`.
3. Mọi cửa gửi việc gọi hàm gửi của engine (`SendTask`, `StartTask`), không viết đường gửi thứ hai.
4. Thêm hàng cho surface đó vào `TestOpSendOnlyInWorkspaceRuns`, và một test đọc với khóa không phải của chủ.

## Ranh giới: ai sở hữu gì

Runtime (core) giữ quyền, danh tính, chọn nơi gửi và giới hạn. Adapter (Soot Forge, hoặc tự viết bằng SDK `channel`) giữ giao thức nền tảng, định dạng tin và dedup. Client (widget, SDK, app của project) viết chữ cho khách. Pack (extension) giữ hành vi chăm sóc khách và chính sách chuyển giao. Cấu hình host và Soot quyết công cụ nào chờ duyệt và credential nào chạm công cụ nào. Nest chỉ hiển thị, soạn nháp và giữ thay đổi chưa lưu.

Surface cố ý không làm: quyết định ai được trả lời; suy quyền từ loại kênh; giữ cấu hình thứ hai trong UI hay prompt; đưa bí mật qua chat; mở operator connection sang transcript của khách.

## Chưa có

Adapter Messenger, Zalo, email. Lead chỉ ở Nest, không phải đích của bot. Duyệt bằng nút ở nơi chung cố ý không làm.
