# Làm một màn hình cho Nest

Thêm một màn hình vào Nest mà không phát hành lại Nest: Soot tự viết, hoặc pack mang tới; người vận hành quyết gì; giới hạn và an toàn.

Nest là một super app: mọi màn hình trong nó là một **mảnh** (piece) đặt vào một **chỗ** (slot). Ngoài các mảnh Nest dựng sẵn, có hai cách đưa thêm màn hình vào mà không phải phát hành lại Nest: một Soot hay một đội **tự viết** màn hình của mình, hoặc một **pack** mang màn hình tới cùng tool của nó. Trang này dẫn từng bước cho cả hai, và cho người vận hành biết mình có quyền gì với các màn hình đó.

| Bạn là | Bạn muốn | Đọc |
|---|---|---|
| Một Soot, hay Đầu mối của một đội | Một màn hình để người làm việc cùng dùng dữ liệu, công cụ của mình và hỏi mình | [Đường 1](#duong-1-soot-hay-doi-tu-viet) |
| Người viết pack | Một màn hình dùng lại được ở nhiều nơi, có tool riêng | [Đường 2](#duong-2-pack-mang-man-hinh-toi) |
| Người vận hành Nest | Đặt, xếp, quay lại, gỡ màn hình | [Người vận hành quyết gì](#nguoi-van-hanh-quyet-gi) |

## Chọn đường

| | Soot hay đội tự viết | Pack |
|---|---|---|
| Ai viết | Chính Soot: ghi file ở scratch rồi `storage push` | Người viết pack |
| Nằm ở đâu | `ui/<id>/` trong file của Soot hay đội | `interface.pieces` trong `pack.json` |
| Đọc dữ liệu | Truy vấn có tên trên việc, bảng, file, việc cần người, kết quả, trí nhớ của chính chủ, hoặc một công cụ đọc chủ tự viết | Một tool đọc của pack, trả về gì cũng được |
| Làm việc | Gọi công cụ hay ghi bảng của chủ ngay, không qua model; hoặc hỏi Soot chủ và nhận câu trả lời | Một tool ghi của pack |
| Gọi dịch vụ ngoài | Công cụ tự viết: khai một request HTTPS, khóa do người nhập trong Nest | Tool của pack, chạy chương trình riêng |
| Lên Nest | Lần đầu hỏi người một lần (màn hình và công cụ trong một thẻ), các bản sau tự lên | Soot chọn pack là có |
| Phát hành | Không | Pack, qua Forge hoặc thư mục pack của bạn |

Chọn tự viết khi màn hình cần thứ Soot đã đọc được, cộng tối đa vài lời gọi tới một dịch vụ ngoài: đây là đường rẻ nhất, một Soot làm xong trong một lượt chạy. Chọn pack khi cần chương trình chạy trên máy chủ (logic không gói được trong một request), hoặc muốn nhiều workspace dùng chung.

Hai đường dùng chung mọi thứ còn lại: cùng các chỗ đặt, cùng bộ kit, cùng khung sandbox, cùng cách Nest giữ cho màn hình nhẹ.

| Chỗ (`slot`) | Hiện ở đâu | Tự viết | Pack |
|---|---|---|---|
| `home` | Một phần của Hộp việc | có | có |
| `rail` | Một khu riêng trên thanh bên | có | có |
| `project.tab` | Một tab của dự án đang chọn (cần `tab {id, label}`) | có | có |
| `data.tab` | Một tab trong Dữ liệu | có | có |
| `settings` | Một mục Cài đặt | không | có |

## Đường 1: Soot hay đội tự viết

_[0.19.0]_ Công cụ tự viết, hành động có tên, `ask` và kit mức 2 (`soot.run`, `soot.ask`, `soot.asks`) có trong runtime và Nest từ 0.19.0. Nest 0.18.0 chỉ có truy vấn và `soot.action`.

Một màn hình tự viết gồm hai nửa, cả hai là file Soot ghi ở scratch của nó rồi đẩy bằng `storage push` vào level của chính nó (`soot:<id>`; của đội thì `team:<id>`, chỉ Đầu mối đẩy):

- **Nửa sau** là công cụ: `tools/<id>/tool.json` khai **một** request HTTPS tới một host có tên. Nó là khai báo, không phải code: không có gì Soot viết chạy trong runtime. Host gửi request, chèn khóa ngay trước khi gửi, rồi xoá khóa khỏi câu trả lời.
- **Nửa trước** là mảnh: `ui/<id>/` với `index.html`, script, và `piece.json` ghi sau cùng. Mọi logic của màn hình nằm trong JavaScript của nó, chạy trong khung sandbox của Nest.

Màn hình không có quyền riêng. Nó đọc qua các truy vấn có tên, làm việc qua các hành động có tên, và hỏi Soot chủ qua `ask`, đúng những gì `piece.json` khai và người đã duyệt. Mọi thứ chạy bằng quyền của chủ.

### Ví dụ: màn hình dịch

Người nhắn Soot `writer`: "Làm cho tôi một màn hình dịch". Soot đề xuất một dịch vụ dịch và nói nó cần một khóa API mà người sẽ nhập trên thẻ duyệt trong Nest, không gửi trong chat. Rồi Soot ghi năm thứ theo thứ tự này:

```text
data: create_table glossary   bảng thuật ngữ mà màn hình đọc và ghi
tools/translate/tool.json     công cụ: một request tới dịch vụ dịch
ui/translate/index.html       màn hình, link _kit/piece.css và _kit/piece.js
ui/translate/app.js           soot.run("translate"), soot.view("terms"), soot.ask(...)
ui/translate/piece.json       khai báo, ghi sau cùng: đây là lần lưu
```

Dịch vụ trong ví dụ ở `api.example.com` là giả định; thay bằng dịch vụ bạn dùng thật thì đổi `url`, header, `body` và `output.pick` theo tài liệu của nó. `TestTranslateGuideExample` chạy đúng các file dưới đây với một API giả.

### Công cụ

`tools/translate/tool.json`:

```json
{
  "id": "translate",
  "label": {"vi": "Dịch văn bản", "en": "Translate text"},
  "description": "Gửi đoạn chữ và ngôn ngữ đích tới dịch vụ dịch ở api.example.com, nhận về bản dịch.",
  "mode": "read",
  "input": {
    "type": "object",
    "required": ["text", "target"],
    "properties": {
      "text": {"type": "string", "minLength": 1, "maxLength": 5000, "description": "The text to translate."},
      "target": {"type": "string", "enum": ["EN", "VI", "JA"], "description": "The language to translate into."}
    }
  },
  "run": {"http": {
    "method": "POST",
    "url": "https://api.example.com/v2/translate",
    "headers": {"Authorization": "Bearer {{cred:TRANSLATE_KEY}}"},
    "body": {"text": ["{{input.text}}"], "target_lang": "{{input.target}}"},
    "timeout": "20s"
  }},
  "output": {"pick": "/translations/0"},
  "needs": {
    "hosts": ["api.example.com"],
    "credentials": {
      "TRANSLATE_KEY": {
        "title": {"vi": "Khóa dịch vụ dịch", "en": "Translation service key"},
        "description": "Tạo khóa ở trang tài khoản của dịch vụ dịch, mục Khóa API.",
        "url": "https://example.com/account/keys"
      }
    }
  }
}
```

- `description` và `label` hiện trên thẻ duyệt cho người đọc, và là mô tả model đọc khi Soot tự gọi công cụ: viết bằng ngôn ngữ của người, nói gửi gì tới đâu. Mỗi chữ nằm trên một dòng, không có ký tự điều khiển hay ký tự đổi hướng chữ (lưu sẽ bị từ chối).
- `mode` là `read` khi request không đổi gì ở dịch vụ (dịch chỉ trả bản dịch), `write` khi nó tạo, sửa, xoá hay gửi thứ gì đi. `read` chỉ đi với `GET` và `POST`; `PUT`, `PATCH`, `DELETE` luôn là `write` (lưu `read` với chúng bị từ chối `method_needs_write`). Header `X-HTTP-Method-Override`, `X-Method-Override` và `X-HTTP-Method` bị từ chối ở mọi công cụ. Với `POST`, `read` là lời Soot cam kết, nên thẻ ghi rõ phương thức và việc dữ liệu được gửi tới host. Công cụ `write` đi qua effect journal và chính sách duyệt của host.
- Truy vấn `{source: "tool"}` (đọc khi mở màn hình) chỉ gắn được công cụ `GET`. Công cụ `POST` như ví dụ này gắn làm hành động có tên và gọi bằng `soot.run`.
- `input` là một JSON Schema nhỏ: object của string, number, integer, boolean (có `enum`, giới hạn độ dài và giá trị) hoặc mảng của chúng. Host kiểm mọi lời gọi.
- `{{input.<trường>}}` đặt được trong đường dẫn, giá trị query, header và chuỗi của `body`; một chuỗi chỉ gồm đúng một chỗ giữ thì nhận nguyên giá trị có kiểu. `{{cred:<TÊN>}}` chỉ đặt được trong header hay giá trị query. Scheme, host và tên header luôn là chữ viết sẵn.
- `needs` là thứ người duyệt: các host (tên miền, không IP, không cổng) và các khóa. Mỗi khóa có `title`, `description` và `url` để người biết lấy khóa ở đâu; thẻ hiện link "Lấy khóa ở đâu" khi có cả `description` lẫn `url`.

Dịch vụ giả định trả `{"translations": [{"text": "…", "detected_source_language": "EN"}]}`; `output.pick` lấy phần tử đầu, nên màn hình nhận `{text, detected_source_language}`.

Ghi `tool.json` là lưu công cụ. Kết quả của lệnh ghi có một note:

```json
{"tool": "soot:writer:translate", "saved": true, "revision": "…", "state": "proposed", "credentials_missing": ["TRANSLATE_KEY"],
 "message": "proposed: the person is asked once to approve it (with the screen that uses it, when a proposed screen binds it); until then it cannot be called. The person enters TRANSLATE_KEY in Nest; never ask for a key in chat"}
```

### Bảng thuật ngữ

Màn hình đọc và ghi bảng `glossary` của Soot. Bảng phải có trước khi lưu `piece.json` (lúc lưu runtime chạy thử truy vấn). Soot tạo nó bằng tool `data`:

```json
{"op": "create_table", "scope": "soot:writer", "table": "glossary", "description": "Terms the translate screen keeps.",
 "columns": [{"name": "term", "type": "text", "required": true}, {"name": "meaning", "type": "text", "required": true}]}
```

### Màn hình

`ui/translate/index.html`. CSP của bundle chặn script và style viết thẳng trong HTML, nên script là file riêng. Không dùng `<form>`: khung chỉ có `allow-scripts`, sự kiện submit không bao giờ tới; nút là `type="button"` có click handler.

```html
<!doctype html>
<html lang="vi">
<meta charset="utf-8">
<title>Dịch</title>
<link rel="stylesheet" href="_kit/piece.css">
<h1>Dịch</h1>
<p id="state" class="muted"></p>
<section class="card stack">
  <textarea id="text" rows="4" maxlength="5000" aria-label="Chữ cần dịch" placeholder="Dán chữ cần dịch"></textarea>
  <div class="row">
    <select id="target" aria-label="Dịch sang">
      <option value="EN">Tiếng Anh</option>
      <option value="VI">Tiếng Việt</option>
      <option value="JA">Tiếng Nhật</option>
    </select>
    <button id="go" type="button" class="primary">Dịch</button>
  </div>
  <p id="result" class="muted">Bản dịch hiện ở đây.</p>
</section>
<section class="card stack">
  <h2>Hỏi Soot</h2>
  <div class="row">
    <input id="question" class="grow" maxlength="4000" aria-label="Câu hỏi" placeholder="Bản dịch này đã tự nhiên chưa?">
    <button id="ask" type="button">Hỏi</button>
  </div>
  <p id="answer" class="muted"></p>
</section>
<section class="card stack">
  <h2>Thuật ngữ</h2>
  <ul id="terms" class="list"></ul>
  <div class="row">
    <input id="term" aria-label="Thuật ngữ" placeholder="Thuật ngữ">
    <input id="meaning" class="grow" aria-label="Nghĩa" placeholder="Nghĩa">
    <button id="add" type="button">Lưu</button>
  </div>
</section>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>
```

`ui/translate/app.js`:

```js
const $ = id => document.getElementById(id);
const say = (el, text, cls = "muted") => { el.textContent = text; el.className = cls; };
let last = null; // the last translation, sent along with a question

async function translate() {
  const text = $("text").value.trim(), target = $("target").value;
  if (!text) return say($("result"), "Nhập chữ cần dịch.", "error");
  $("go").disabled = true;
  say($("result"), "Đang dịch…");
  try {
    const { output } = await soot.run("translate", { text, target });
    last = { text, target, translation: output.text };
    say($("result"), output.text, "");
  } catch (err) {
    // Nest itself says a key is missing, with its "Mở Kho khóa" button; do not repeat it.
    say($("result"), err.code === "credential_missing" ? "Chưa dịch được: thiếu khóa." : "Chưa dịch được: " + err.message, "error");
  } finally {
    $("go").disabled = false;
  }
}

function showAsk(s) {
  if (s.state === "done") {
    const better = s.reply.data && s.reply.data.translation;
    say($("answer"), s.reply.text + (better ? " Gợi ý: " + better : ""), "");
  } else if (s.state === "waiting") say($("answer"), "Soot cần bạn trả lời trong cuộc trò chuyện.");
  else if (s.state === "failed") say($("answer"), "Soot chưa trả lời được câu này.", "error");
  else say($("answer"), "Soot đang trả lời…");
}

async function ask() {
  const text = $("question").value.trim();
  if (!text) return;
  $("ask").disabled = true;
  try {
    const s = await soot.ask(last ? { text, data: last } : { text }, { onState: showAsk });
    showAsk(s);
    if (s.state === "done") $("question").value = ""; // asked and answered: the box is empty for the next one; a failed question stays to retry
  } catch (err) {
    say($("answer"), "Chưa hỏi được: " + err.message, "error");
  } finally {
    $("ask").disabled = false;
  }
}

function drawTerms(out) {
  $("terms").replaceChildren(...out.rows.map(row => soot.el("li", { class: "row" },
    soot.el("strong", {}, row.term), soot.el("span", { class: "grow muted" }, row.meaning))));
  if (!out.total) $("terms").replaceChildren(soot.el("li", { class: "empty" }, "Chưa có thuật ngữ nào."));
}

async function addTerm() {
  const term = $("term").value.trim(), meaning = $("meaning").value.trim();
  if (!term || !meaning) return;
  $("add").disabled = true;
  try {
    await soot.run("add_term", { rows: [{ term, meaning }] });
    $("term").value = $("meaning").value = "";
    drawTerms(await soot.view("terms"));
  } catch (err) {
    say($("state"), "Chưa lưu được thuật ngữ: " + err.message, "error");
  } finally {
    $("add").disabled = false;
  }
}

soot.ready(async () => {
  if (soot.level < 2) {
    say($("state"), "Màn hình này cần Nest mới hơn. Cập nhật Nest rồi mở lại.", "error");
    document.querySelectorAll("button").forEach(b => { b.disabled = true; });
    return;
  }
  $("go").addEventListener("click", translate);
  $("ask").addEventListener("click", ask);
  $("add").addEventListener("click", addTerm);
  const kept = soot.cached("terms");
  if (kept) drawTerms(kept);
  soot.live(async () => {
    try { drawTerms(await soot.view("terms")); } catch (err) { say($("state"), "Chưa đọc được thuật ngữ: " + err.message, "error"); }
    // The newest question and its answer, also when the screen is opened again.
    try { const prev = (await soot.asks()).asks[0]; if (prev) showAsk(prev); } catch (err) { /* nothing asked yet */ }
  });
});
```

- `soot.run(name, input)` chạy hành động có tên `name`, runtime làm ngay, không có lượt model. Mỗi lần gọi một `request_id` mới; gửi lại đúng `request_id` cũ chỉ đọc lại kết quả, không gọi lần hai.
- `soot.ask(input, {onState})` gửi câu hỏi vào cuộc trò chuyện riêng của người xem với Soot chủ. Promise trả trạng thái `done` có `reply {text, data?}`, bị từ chối với `ask_failed` khi run hỏng. `soot.asks()` cho các câu đã hỏi, mới nhất trước, nên mở lại màn hình là thấy câu trả lời; `soot.live` đọc lại khi cuộc trò chuyện đổi.
- Nest chỉ chuyển `soot.run`, `soot.action` và `soot.ask` khi người vừa bấm hay gõ trong màn hình; gọi chúng lúc màn hình vừa mở hay từ hẹn giờ bị từ chối với `gesture_required`. `soot.view` và `soot.asks` thì không cần, và theo lại một câu đã hỏi (cùng `request_id`, sau khi tải lại) cũng không cần.
- Khóa thiếu, khóa sai hay dịch vụ lỗi đều đến dưới dạng một lỗi có `code` và `message` người đọc được. Khi thiếu khóa (`credential_missing`), Nest tự báo ở đầu màn hình kèm nút "Mở Kho khóa", nên màn hình chỉ nói ngắn là chưa làm được; lỗi khác thì màn hình hiện `err.message`.

### Khai báo

`ui/translate/piece.json`, ghi sau cùng:

```json
{
  "id": "translate",
  "slot": "rail",
  "label": {"vi": "Dịch", "en": "Translate"},
  "icon": "globe",
  "order": 300,
  "access": "operator",
  "data": {
    "queries": {
      "terms": {"source": "table", "table": "glossary", "order": "term", "limit": 100}
    },
    "actions": {
      "translate": {"tool": "translate"},
      "add_term": {"table": "glossary", "op": "insert"}
    },
    "ask": true
  }
}
```

- `queries` là các lần đọc có tên (`task`, `table`, `file`, `need`, `outcome`, `memory`, hoặc `{source: "tool", tool}` cho một công cụ `read` dùng `GET` của chủ). Tối đa 8.
- `actions` là các hành động có tên: `{tool}` gọi công cụ của chủ, `{table, op: "insert" | "update" | "delete"}` ghi bảng trong quyền ghi của chủ. Tối đa 8. `insert` nhận `{rows: [{cột: giá trị}]}` và trả `{ids}`.
- `ask: true` cho màn hình hỏi Soot chủ. Mặc định tắt.
- Công cụ phải được ghi trước `piece.json`: một hành động trỏ tới công cụ chưa có thì lưu bị từ chối với `tool_unknown`.

Kết quả của lệnh ghi có note `{"screen": "soot:writer:translate", "saved": true, "state": "proposed", …}`.

### Người duyệt một lần

Lần lưu đầu tạo **một** việc trong Cần bạn cho cả màn hình lẫn công cụ nó dùng. Thẻ cho người thấy: màn hình nằm ở đâu, ai thấy, đọc gì, có nút gì; với mỗi công cụ: làm gì (chỉ đọc, hay gửi đi và thay đổi dữ liệu), phương thức và host nó gửi tới, cần khóa nào (tên và mã khóa), khóa đó "Đã có" hay "Chưa có". Khóa đã có mà bản này sẽ gửi tới một host mới thì thẻ báo ngay trên nút duyệt; host mà ô nhập đã ghi khi người nhập khóa không tính là mới. Khóa chưa có thì thẻ có một ô nhập kín và link "Lấy khóa ở đâu", link này hỏi người xác nhận host trước khi mở. Người nhập khóa, bấm "Lưu khóa" (giá trị đi thẳng tới runtime, ô tự xoá), rồi "Duyệt và đặt vào Nest": màn hình hiện ở thanh bên, công cụ chạy được.

Soot không bao giờ thấy khóa và không bao giờ hỏi khóa trong chat. Thiếu khóa vẫn duyệt được; khi đó lần dịch đầu báo thiếu khóa và Nest đưa người tới Kho khóa.

Sau khi đặt, Soot sửa giao diện thoải mái và các bản mới lên ngay. Nhưng thêm host, thêm khóa, đổi phương thức, đổi `read` sang `write`, thêm hành động trỏ tới đích mới, đổi chữ tìm (`search`) của truy vấn trí nhớ, bật `ask` hay đổi chỗ đặt và người thấy đều bị từ chối (`approval_needed`); muốn với xa hơn thì lưu dưới id mới để người được hỏi lại.

### Trả lời câu hỏi từ màn hình

Một câu hỏi tới Soot như một tin nhắn trong cuộc trò chuyện riêng của người xem: dòng đầu là `Hỏi từ màn hình “Dịch”`, rồi câu hỏi, rồi `data` của màn hình trong một khối JSON. Soot trả lời như mọi tin nhắn: tin nhắn cuối của nó là `reply.text`. Run này có thêm tool `piece_reply`; Soot gọi nó với `data` là một giá trị JSON (viết thành chuỗi, tối đa 16 KiB) để màn hình nhận dữ liệu có cấu trúc, ở ví dụ là `{"translation": "…"}`. Người mở được cuộc trò chuyện đó từ đầu màn hình ("Mở cuộc trò chuyện") và gõ tiếp ở đó.

Câu hỏi của người vận hành chạy trong workspace của chủ, nên Soot dùng được công cụ của mình (`tool_translate`) và bảng thuật ngữ. Câu hỏi của một thành viên chạy trong chỗ của thành viên: không có công cụ hay khóa của chủ.

### Thử

1. Cho Soot chọn pack `soot-nest` (đi kèm runtime): skill `nest-pieces` dạy đúng các bước trên. Soot có `read` thì đã có tool `storage` và `data`.
2. Nhắn Soot điều bạn cần. Soot ghi file và nói việc đang chờ ở Cần bạn.
3. Mở thẻ, xem trước màn hình, nhập khóa, duyệt. Mở "Dịch" ở thanh bên, dịch một câu, hỏi Soot một câu.
4. Không có Nest thì mở `http://<runtime>/v1/pieces/soot:writer:translate/` trong trình duyệt để xem màn hình; vỏ này ở mức cầu 1, nên `soot.run` và `soot.ask` chỉ chạy trong Nest.

Hướng dẫn đầy đủ cho mảnh tự viết (mọi nguồn truy vấn, vòng đời, bộ kit): Màn hình Soot tự làm.

## Đường 2: pack mang màn hình tới

Ví dụ dưới là một pack tối thiểu, `hello-board`: một phần "Bảng tin" ở Hộp việc, đọc bằng một tool, ghim một dòng bằng tool thứ hai. `soot init-pack hello-board --with tool` tạo khung thư mục; bốn file dưới đây là toàn bộ phần còn lại.

```text
hello-board/pack.json
hello-board/tools/board.mjs
hello-board/ui/board/index.html
hello-board/ui/board/app.js
```

### Khai báo

`pack.json`. Mảnh nằm trong `interface.pieces`; `data.view_tool` và `data.action_tool` là tên hai tool của chính pack này.

```json
{
  "name": {"vi": "Bảng tin", "en": "Board"},
  "description": "A first piece: one section of the inbox, served by two tools.",
  "tools": [
    {
      "name": "board_view",
      "description": "List the board's lines, optionally filtered by q.",
      "parameters": {"type": "object", "properties": {"q": {"type": "string"}}},
      "run": {"program": "node", "args": ["tools/board.mjs", "view"], "stdin": "context", "mode": "read"}
    },
    {
      "name": "board_pin",
      "description": "Pin one line of the board.",
      "parameters": {"type": "object", "properties": {"pin": {"type": "string"}}, "required": ["pin"]},
      "run": {"program": "node", "args": ["tools/board.mjs", "pin"], "stdin": "context", "mode": "write"}
    }
  ],
  "interface": {
    "pieces": [
      {
        "id": "board",
        "slot": "home",
        "label": {"vi": "Bảng tin", "en": "Board"},
        "icon": "pin",
        "order": 200,
        "access": "operator",
        "bundle": "ui/board/",
        "data": {"view_tool": "board_view", "action_tool": "board_pin"}
      }
    ]
  }
}
```

- `id` của mảnh là tiếng Anh, chữ thường, gạch nối, duy nhất trong pack. Một pack khai 1 đến 8 mảnh.
- `access` là `operator` (chỉ người vận hành) hoặc `member` (cả thành viên vào được Soot phục vụ mảnh).
- `bundle` là một thư mục trong pack, có `index.html`, không quá 5 MiB.
- Tool đọc phải có `run.mode: "read"`; cả hai tool nhận `run.stdin: "context"`. Tool cần người duyệt (`approval`) không dùng được làm tool của mảnh: màn hình không vẽ bước duyệt.
- Trường lạ là lỗi. `interface.pages` là tên cũ: pack mới khai nó bị từ chối khi cài, lỗi nói cách chuyển sang `pieces`. Pack đã cài từ trước vẫn chạy công cụ và kỹ năng, chỉ không hiện màn hình cho tới khi được cập nhật.

### Tool đọc và tool làm

Runtime chạy tool với một object JSON trên stdin và đọc một object JSON trên stdout. Ngoài `input` do màn hình gửi, tool nhận `piece` (Soot đang phục vụ, id mảnh, `mode` là `view` hay `action`) và `viewer` (ai đang xem).

`tools/board.mjs`:

```js
import { readFileSync } from "node:fs";

// stdin: {piece: {soot, piece, mode}, input, viewer: {kind, id}, ...}
const ctx = JSON.parse(readFileSync(0, "utf8"));
const input = ctx.input ?? {};
const LINES = [
  { id: "release", text: "Phát hành bản 1.4 vào thứ Sáu" },
  { id: "interview", text: "Phỏng vấn ứng viên hỗ trợ lúc 14:00" },
];
const reply = value => console.log(JSON.stringify(value));

if (process.argv[2] === "view") {
  const q = String(input.q ?? "").toLowerCase();
  const lines = LINES.filter(line => line.text.toLowerCase().includes(q));
  reply({ lines, total: lines.length });
} else if (LINES.some(line => line.id === input.pin)) {
  reply({ pinned: input.pin });
} else {
  reply({ error: "no such line", reason: "invalid_input" });
  process.exit(1);
}
```

- Coi `input` là dữ liệu chưa đáng tin: nó đến từ một trang trong sandbox, kiểm như kiểm mọi đầu vào.
- Tool chạy dưới tên Soot phục vụ mảnh, với đúng quyền và credential như khi Soot đó tự gọi tool. Màn hình không thêm quyền nào.
- Một hành động chạy đúng một lần cho mỗi `request_id`. Gửi lại cùng id thì nhận lại kết quả cũ, tool không chạy lần hai.
- Đừng trả bí mật trong kết quả đọc: Nest giữ kết quả lần trước trên máy người xem để mở lại là thấy ngay.

### Bundle

Bundle là một trang web thường. Hai link `_kit/piece.css` và `_kit/piece.js` do runtime phục vụ trong mọi phiên: kit lo cầu nối với Nest, màu và chữ theo Nest, sáng và tối. CSP của bundle chặn script và style viết thẳng trong trang, nên script là file riêng.

`ui/board/index.html`:

```html
<!doctype html>
<html lang="vi">
<meta charset="utf-8">
<title>Bảng tin</title>
<link rel="stylesheet" href="_kit/piece.css">
<p id="state" class="muted">Đang tải…</p>
<ul id="lines" class="list"></ul>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>
```

`ui/board/app.js`:

```js
const state = document.getElementById("state");
const list = document.getElementById("lines");

function draw(out) {
  list.replaceChildren(...out.lines.map(line => soot.el("li", { class: "row" },
    soot.el("span", { class: "grow" }, line.text),
    soot.el("button", { type: "button", onclick: event => pin(event.target, line) }, "Ghim"))));
  state.textContent = out.total ? out.total + " dòng" : "Chưa có dòng nào.";
}

async function pin(button, line) {
  button.disabled = true;
  try {
    await soot.action({ pin: line.id });
    button.textContent = "Đã ghim";
  } catch (err) {
    button.disabled = false;
    state.textContent = "Chưa ghim được: " + err.message;
  }
}

// Mở lại thì vẽ ngay kết quả lần trước, rồi đọc số mới.
soot.ready(() => { const last = soot.cached({}); if (last) draw(last); });
// Tự đọc lại khi có thay đổi, khi hiện lại, và mỗi phút khi đang hiện; khuất thì nghỉ.
soot.live(async () => {
  try { draw(await soot.view({})); } catch (err) { state.textContent = "Chưa đọc được: " + err.message; }
});
```

Mảnh của pack gọi `soot.view(input)` và `soot.cached(input)` không có tên; mảnh Soot tự viết gọi theo tên truy vấn. Phần còn lại của kit giống nhau, xem bộ kit.

### Thử

1. Đặt thư mục pack vào `packs_dir` của workspace và cho một Soot chọn nó: `{"packs": ["hello-board"]}`.
2. `soot check --show` nạp pack như runtime sẽ nạp. Khai báo mảnh sai thì báo `piece_invalid` kèm tên mảnh và lý do (`tool_missing`, `view_not_read`, `stdin_not_context`, `bundle_missing`, `bundle_too_large`, `tab_required`, `unknown_slot`…).
3. Chạy tool bằng tay với đúng thứ runtime sẽ gửi (lệnh ở dưới); nó phải in ra một object JSON.
4. Chạy runtime và mở Nest: mảnh có ngay ở Hộp việc, không hỏi ai, vì người vận hành đã chọn pack. Không có Nest thì mở `http://<runtime>/v1/pieces/pack:hello-board:board/` trong trình duyệt: đó là một trang vỏ dựng đúng khung và cầu như Nest, hỏi key vận hành một lần (origin của runtime phải có trong `server.browser_origins`).
5. Sửa bundle rồi mở lại màn hình. Một khung đang mở giữ bản cũ tối đa 10 phút (tuổi của một phiên).

```sh
echo '{"piece":{"soot":"helper","piece":"board","mode":"view"},"input":{"q":"bản"},"viewer":{"kind":"operator","id":"operator"}}' | node tools/board.mjs view
```

Phát hành pack như mọi pack khác; xem [Agent, nhóm, pack, Forge](https://trysoot.com/vi/docs/agents/index.md).

## Người vận hành quyết gì

Màn hình của người khác chạy trong Nest của bạn, nên quyền cuối cùng ở bạn.

- **Màn hình Soot tự làm phải được bạn đặt.** Lần đầu, nó là một việc trong Cần bạn: bạn xem trước, thấy nó sẽ nằm ở đâu, ai thấy, đọc những gì, có gửi hành động không, rồi đặt hoặc từ chối. Từ chối thì Soot được báo và không hỏi lại cho tới khi nó đổi nội dung.
- **Đã đặt thì không tự với xa hơn.** Soot sửa giao diện và cách lọc thoải mái, nhưng không tự đổi được chỗ đặt, người thấy, quyền gửi hành động hay nguồn dữ liệu của màn hình bạn đã duyệt.
- **Quay lại và gỡ.** Mỗi màn hình tự viết có lịch sử bản; bạn quay về bản trước hoặc gỡ hẳn khỏi Nest ngay trên màn hình đó. Bản mới mà hỏng hai lần tải trên máy bạn, chưa từng tải được, thì runtime tự quay về bản tốt gần nhất.
- **Màn hình của pack đi theo pack.** Soot chọn pack thì có, bỏ chọn thì mất. Chọn pack là việc của bạn, nên Nest không hỏi thêm.
- **Bố cục là của bạn.** Cài đặt › Màn hình cho xếp thứ tự và ẩn từng màn hình; bố cục nằm trên máy bạn. Một Soot chỉ đề xuất được bố cục, bạn áp dụng hoặc từ chối.
- **Công cụ và khóa do bạn duyệt.** _[0.19.0]_ Màn hình dùng công cụ Soot tự viết thì thẻ duyệt ghi rõ từng công cụ làm gì (chỉ đọc hay gửi đi), gửi bằng phương thức nào tới host nào và cần khóa nào, đã có hay chưa. Khóa chưa có thì nhập ngay trên thẻ, hoặc để sau và bấm "Mở Kho khóa" khi màn hình báo thiếu. Thiếu khóa vẫn duyệt được; công cụ chỉ chạy khi đã có khóa.
- **Thấy cái nào nặng.** Cũng ở Cài đặt › Màn hình: mỗi màn hình mở mất bao lâu trên máy này, bao nhiêu lần không mở kịp, lần đọc nào quá lớn.

## Giới hạn và an toàn

- **Khung sandbox.** Mỗi màn hình chạy trong một khung riêng, không có credential, không gọi mạng được (`connect-src 'none'`), không gửi form. Nó chỉ nói chuyện với Nest qua cầu `postMessage`, và Nest chỉ chuyển lời gọi tới chính mảnh đó.
- **Điều khung vẫn làm được.** CSP không chặn được một trang tự chuyển hướng chính nó. Khi khung rời bundle, Nest đóng nó và tính là một lần tải hỏng, nhưng địa chỉ nó chuyển tới đã được gọi. Vì vậy hãy coi dữ liệu màn hình đọc được là dữ liệu tác giả của nó đọc được: chỉ đặt màn hình của Soot và pack bạn tin, như khi cấp quyền cho chính chúng.
- **Không cấp quyền.** Mức truy cập của chủ là trần, kiểm lúc lưu và kiểm lại mỗi lần gọi. Màn hình không tự cấp được quyền nào, không đọc được khóa, và chỉ biết thiếu khóa khi runtime trả lời một lần gọi.
- **Mở link.** `soot.open` và thẻ `<a>` nhờ Nest mở link. Nest chỉ nhận khi màn hình đang hiện, nhiều nhất một lần mỗi giây, và không mở khung trình duyệt của Nest theo lời một màn hình.
- **Con số.** Bundle ≤ 5 MiB; ở `home`, script và style ≤ 512 KiB. Gọi `soot.ready()` trong 1 giây (quá 5 giây là một lần tải hỏng). Mỗi lần đọc trả về dưới 256 KiB. Cùng một lần đọc tới runtime nhiều nhất một lần mỗi giây khi hiện, mười giây khi khuất; sau một hành động hoặc khi runtime báo có thay đổi thì lần đọc kế tiếp luôn tới runtime. Mảnh tự viết: tối đa 8 mảnh mỗi chủ, 8 truy vấn mỗi mảnh, 10 hành động mỗi phút. _[0.19.0]_ Hành động và câu hỏi tính chung: 10 mỗi phút cho mỗi người xem, 30 cho cả mảnh; đầu vào của `soot.run` và `soot.ask` tối đa 8 KiB, chữ hỏi 4000 ký tự. Công cụ tự viết: tối đa 16 mỗi chủ, 30 lời gọi mỗi phút mỗi công cụ, câu trả lời tối đa 256 KiB, chờ tối đa 60 giây (mặc định 20).
- **Nhẹ là mặc định.** Nest chỉ mở khung khi nó sắp vào màn hình, nhiều nhất 4 khung cùng lúc; khuất thì không hẹn giờ, không hỏi runtime. Dùng `soot.live` thay cho tự hẹn giờ.

## Khi Soot và Nest lên bản mới

Màn hình bạn làm hôm nay vẫn chạy ở các bản sau. Bốn điều cần biết:

- **`kit`.** Manifest có thể ghi `"kit": 1`: bản bộ kit mà bundle được viết cho. Bỏ trống cũng là 1, và mặc định đó không bao giờ đổi. Runtime gặp bản nó không phục vụ thì từ chối với `kit_unsupported` và nói nó phục vụ bản nào.
- **Tính năng thêm sau.** Cầu giữa khung và Nest có một mức (`soot.level`). Nest 0.18.0 có mức 1; mức 2 thêm `soot.run`, `soot.ask` và `soot.asks`. Tính năng thêm sau này mang mức cao hơn. Màn hình muốn dùng thì kiểm `soot.level` trước, nên vẫn chạy được trên Nest cũ: ở mức 1, kit từ chối ba lời gọi đó với `unsupported` và không gửi gì.
- **Tin Nest gửi có thể có thêm trường.** Nest được thêm trường vào một tin (`init`, `result`…) mà không đổi mức. Màn hình dùng kit thì không phải làm gì: kit chỉ đọc trường nó cần. Bundle tự nói chuyện qua cầu thì phải bỏ qua trường và loại tin nó không biết, đừng so tin với một danh sách trường cố định: làm thế thì màn hình hỏng ở lần Nest thêm trường tiếp theo.
- **Thay đổi phá vỡ.** Luôn mang số `kit` mới và đi qua hai bản phát hành: bản đầu phục vụ cả kit cũ lẫn mới, bản sau mới bỏ kit cũ. Trong lúc đó runtime báo cho Soot chủ để nó viết lại màn hình; pack thì ra bản mới trên Forge.

Quy tắc đầy đủ ở Mảnh: chuẩn mở rộng Nest.

## Khi có lỗi

| Thấy gì | Vì sao | Làm gì |
|---|---|---|
| Lệnh ghi `piece.json` trả `saved: false` | `reason` nói lỗi gì, `message` nói cách sửa | Sửa rồi ghi lại `piece.json` |
| `approval_needed` | Màn hình đã đặt đang với xa hơn bản người duyệt | Giữ nguyên tầm với, hoặc lưu dưới id mới |
| `kit_unsupported` | Manifest ghi bản kit mà runtime này không phục vụ | Bỏ `kit` hoặc ghi bản runtime nêu trong lỗi; nếu màn hình cần kit mới hơn thì cập nhật Soot |
| `soot check` báo `piece_invalid` | Khai báo mảnh của pack sai | Xem `reason` và con trỏ tới trường sai |
| `retired_field` ở `/interface/pages` | Pack còn dùng tên cũ | Chuyển sang `interface.pieces` theo gợi ý của lỗi |
| Khung trắng, rồi "không mở kịp" | Trang không gọi `ready` trong 5 giây, thường do script viết thẳng trong HTML bị CSP chặn | Đưa script ra file, link `_kit/piece.js` trước |
| `tool_refused` với `approval_required` | Tool của mảnh cần người duyệt | Dùng tool không cần duyệt cho màn hình |
| `429 busy` | Mọi mảnh dùng chung 8 lượt tool | Nest tự thử lại; giữ tool đọc nhanh (dưới 500 ms) |
| `rate_limited` | Quá 10 hành động mỗi phút trên một mảnh tự viết | Chờ theo `retry_after` |
| `owner_unavailable` | Chủ màn hình chưa nhận việc lúc này | Chưa có gì được gửi: cho người bấm thử lại sau |
| `ask` luôn trả `owner_unavailable` | Soot chủ chỉ là thành viên của một đội, không phải Soot mở được cuộc trò chuyện trực tiếp | Cho Soot đó đứng một mình hoặc làm một cửa vào (`entries`) của đội; hoặc để Đầu mối viết màn hình ở level của đội |
| `gesture_required` _[0.19.0]_ | Màn hình gọi `soot.run` hay `soot.ask` lúc tải hay từ hẹn giờ, không phải ngay sau một cú bấm hay phím của người | Chỉ gọi hai lệnh đó trong click handler; đọc khi tải bằng `soot.view` và `soot.asks` |
| Bấm nút trong một `<form>` không có gì xảy ra | Khung chỉ có `allow-scripts`, không `allow-forms`: sự kiện submit không bao giờ tới | Bỏ `<form>`, dùng `button type="button"` với click handler |
| Bundle tự nói cầu hỏng sau khi Nest cập nhật | Màn hình so tin của Nest với một danh sách trường cố định | Bỏ qua trường và loại tin không biết; hoặc dùng kit |
| "Mở cuộc trò chuyện" không tới đúng chỗ | Màn hình ghép link từ `run_id` hay id khác | Hội thoại của câu hỏi là `conversation_id` trong kết quả (32 ký tự hex): `soot.open("nest://conversation/<conversation_id>")` |
| `credential_missing` _[0.19.0]_ | Khóa của công cụ chưa được nhập | Người nhập khóa trên thẻ hoặc ở Kho khóa ("Mở Kho khóa" hiện trên màn hình); không bao giờ gửi khóa trong chat |
| `credential_rejected` _[0.19.0]_ | Dịch vụ trả 401 hay 403: khóa sai hoặc hết hạn | Người thay khóa ở Kho khóa |
| `upstream_error`, `timeout`, `request_failed` _[0.19.0]_ | Dịch vụ trả lỗi, chậm quá `timeout`, hoặc không tới được | Xem `status` và `body` (đã che khóa); kiểm `url`, `body` theo tài liệu của dịch vụ |
| Lưu `tool.json` bị từ chối _[0.19.0]_ | `reason` nói lỗi gì: `run_invalid`, `method_needs_write`, `host_not_declared`, `credential_not_declared`, `input_invalid`, `manifest_invalid`, `approval_needed`… | Sửa đúng trường `message` nêu, ghi lại `tool.json` |
| Lưu `piece.json` trả `tool_unknown` _[0.19.0]_ | Hành động hay truy vấn trỏ tới công cụ chưa ghi, đã gỡ, hoặc truy vấn đọc một công cụ không dùng `GET` (`write`, hay `read` dùng `POST`) | Ghi `tools/<id>/tool.json` trước, rồi ghi lại `piece.json` |
| Màn hình không đổi sau khi sửa | Khung đang mở giữ phiên cũ | Đóng mở lại màn hình |
