07 / Company and goals
Build a screen for Nest
Add a screen to Nest without a Nest release: a Soot writes it, or a pack brings it; what the operator decides; limits and safety.
Nest is a super app: every screen in it is a piece placed in a slot. Besides the pieces Nest ships with, there are two ways to add a screen without a new Nest release: a Soot or a team writes its own screen, or a pack brings a screen along with its tools. This page walks through both, and tells the operator what they decide about those screens.
| You are | You want | Read |
|---|---|---|
| A Soot, or a team's coordinator | A screen where the people you work with use your data and tools and ask you | Path 1 |
| A pack author | A screen that many workspaces can reuse, with its own tools | Path 2 |
| The operator of a Nest | To place, arrange, go back on and remove screens | What the operator decides |
Choosing a path
| Written by a Soot or a team | Pack | |
|---|---|---|
| Who writes it | The Soot itself: it writes the files in its workspace and pushes them with storage push | The pack author |
| Where it lives | ui/<id>/ in the Soot's or the team's files | interface.pieces in pack.json |
| Reading data | Named queries over the owner's own tasks, tables, files, needs, outcomes and memory, or a read tool the owner wrote | One read tool of the pack, returning anything |
| Doing work | The owner's tool or table write, at once with no model turn; or a question to the owning Soot that gets an answer | One write tool of the pack |
| Calling an outside service | A written tool: one declared HTTPS request, with a key the person enters in Nest | A pack tool running its own program |
| Getting into Nest | The person is asked once (the screen and its tools on one card); later versions go live by themselves | There as soon as a Soot selects the pack |
| Release | None | The pack, through Forge or your own packs directory |
Write it when the screen needs what the Soot can already read, plus at most a few calls to an outside service: it is the cheapest path, and a Soot finishes one in a single run. Use a pack when you need a program that runs on the host (logic that does not fit in one request), or the same screen in many workspaces.
Both paths share everything else: the same slots, the same kit, the same sandboxed frame, and the same way Nest keeps a screen light.
Slot (slot) | Where it shows | Written | Pack |
|---|---|---|---|
home | A section of Hộp việc (the inbox) | yes | yes |
rail | An area of its own in the side bar | yes | yes |
project.tab | A tab of the chosen project (needs tab {id, label}) | yes | yes |
data.tab | A tab in Dữ liệu (Data) | yes | yes |
settings | A Settings section | no | yes |
Path 1: a Soot or a team writes it
_[0.19.0]_ Written tools, named actions, ask and kit level 2 (soot.run, soot.ask, soot.asks) are in the runtime and Nest since 0.19.0. Nest 0.18.0 has only queries and soot.action.
A written screen has two halves, both files the Soot writes in its workspace and pushes with storage push into its own level (soot:<id>; a team's is team:<id>, pushed only by its coordinator):
- The back end is a tool:
tools/<id>/tool.jsondeclares one HTTPS request to a named host. It is a declaration, not code: nothing a Soot writes runs in the runtime. The host sends the request, puts the key in just before it goes, and removes the key from the answer. - The front end is a piece:
ui/<id>/withindex.html, scripts, andpiece.jsonwritten last. All of the screen's logic is its own JavaScript, running in Nest's sandboxed frame.
A screen has no access of its own. It reads through named queries, works through named actions and asks its owning Soot through ask: exactly what piece.json declares and the person approved. Everything runs with the owner's access.
Example: a translation screen
The person writes to the Soot writer: "Make me a translation screen". The Soot proposes a translation service and says it needs an API key, which the person will enter on the approval card in Nest, not in chat. Then the Soot writes five things in this order:
data: create_table glossary the glossary table the screen reads and writes
tools/translate/tool.json the tool: one request to the translation service
ui/translate/index.html the screen; links _kit/piece.css and _kit/piece.js
ui/translate/app.js soot.run("translate"), soot.view("terms"), soot.ask(...)
ui/translate/piece.json the declaration, written last: this is the saveThe service in the example, at api.example.com, is made up; for a real one, change url, the headers, body and output.pick to match its documentation. TestTranslateGuideExample runs the files of the Vietnamese guide against a fake API; the files below differ only in display text.
The tool
tools/translate/tool.json:
{
"id": "translate",
"label": {"vi": "Dịch văn bản", "en": "Translate text"},
"description": "Sends a text and a target language to the translation service at api.example.com and gets the translation back.",
"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": "Create a key on the translation service's account page, under API keys.",
"url": "https://example.com/account/keys"
}
}
}
}descriptionandlabelshow on the approval card for the person, and are what the model reads when the Soot calls the tool itself: write them in the person's language and say what is sent where. Each stays on one line, with no control or text-direction character (the save is refused).modeisreadwhen the request changes nothing at the service (translating only returns a translation),writewhen it creates, changes, deletes or sends something.readgoes withGETandPOSTonly;PUT,PATCHandDELETEare alwayswrite(savingreadwith one is refused withmethod_needs_write). The headersX-HTTP-Method-Override,X-Method-OverrideandX-HTTP-Methodare refused on every tool. WithPOST,readis the Soot's word, so the card names the method and says data is sent to the host. Awritetool goes through the effect journal and the host's approval policy.- A
{source: "tool"}query (a read when the screen opens) binds only aGETtool. APOSTtool like this one is bound as a named action and called withsoot.run. inputis a small JSON Schema: an object of strings, numbers, integers and booleans (withenum, length and value bounds) or arrays of them. The host checks every call.{{input.<field>}}may stand in the path, query values, headers andbodystrings; a string that is exactly one placeholder takes the typed value.{{cred:<NAME>}}may stand only in a header or a query value. The scheme, the host and header names are always literal.needsis what the person approves: the hosts (domain names, no IP, no port) and the keys. Each key has atitle, adescriptionand aurlso the person knows where to get it; the card shows a "where to get the key" link when there are both adescriptionand aurl.
The made-up service answers {"translations": [{"text": "…", "detected_source_language": "EN"}]}; output.pick takes the first item, so the screen gets {text, detected_source_language}.
Writing tool.json saves the tool. The write's result carries one note:
{"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"}The glossary table
The screen reads and writes the Soot's glossary table. The table must exist before piece.json is saved (the save runs the query once). The Soot creates it with the data tool:
{"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}]}The screen
ui/translate/index.html. The bundle's CSP blocks scripts and styles written in the HTML, so the script is a file. Do not use a <form>: the frame has allow-scripts only, so a submit event never arrives; buttons are type="button" with click handlers.
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Translate</title>
<link rel="stylesheet" href="_kit/piece.css">
<h1>Translate</h1>
<p id="state" class="muted"></p>
<section class="card stack">
<textarea id="text" rows="4" maxlength="5000" aria-label="Text to translate" placeholder="Paste the text to translate"></textarea>
<div class="row">
<select id="target" aria-label="Translate into">
<option value="EN">English</option>
<option value="VI">Vietnamese</option>
<option value="JA">Japanese</option>
</select>
<button id="go" type="button" class="primary">Translate</button>
</div>
<p id="result" class="muted">The translation shows here.</p>
</section>
<section class="card stack">
<h2>Ask the Soot</h2>
<div class="row">
<input id="question" class="grow" maxlength="4000" aria-label="Question" placeholder="Does this translation read naturally?">
<button id="ask" type="button">Ask</button>
</div>
<p id="answer" class="muted"></p>
</section>
<section class="card stack">
<h2>Glossary</h2>
<ul id="terms" class="list"></ul>
<div class="row">
<input id="term" aria-label="Term" placeholder="Term">
<input id="meaning" class="grow" aria-label="Meaning" placeholder="Meaning">
<button id="add" type="button">Save</button>
</div>
</section>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>ui/translate/app.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"), "Type the text to translate.", "error");
$("go").disabled = true;
say($("result"), "Translating…");
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 "Open the key vault" button; do not repeat it.
say($("result"), err.code === "credential_missing" ? "Could not translate: the key is missing." : "Could not translate: " + 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 ? " Suggestion: " + better : ""), "");
} else if (s.state === "waiting") say($("answer"), "The Soot needs your answer in the conversation.");
else if (s.state === "failed") say($("answer"), "The Soot could not answer this one.", "error");
else say($("answer"), "The Soot is answering…");
}
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"), "Could not ask: " + 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" }, "No terms yet."));
}
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"), "Could not save the term: " + err.message, "error");
} finally {
$("add").disabled = false;
}
}
soot.ready(async () => {
if (soot.level < 2) {
say($("state"), "This screen needs a newer Nest. Update Nest and open it again.", "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"), "Could not read the glossary: " + 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)runs the named actionname; the runtime does it at once, with no model turn. Every call gets a newrequest_id; sending an oldrequest_idagain only reads its result back, it never calls twice.soot.ask(input, {onState})sends the question into the viewer's own conversation with the owning Soot. The promise resolves with thedonestate and itsreply {text, data?}, and rejects withask_failedwhen the run fails.soot.asks()lists the questions asked, newest first, so a reopened screen shows the answer;soot.livereads again when the conversation moves.- Nest forwards
soot.run,soot.actionandsoot.askonly right after the person clicks or types in the screen; calling them on load or from a timer is refused withgesture_required.soot.viewandsoot.asksneed no gesture, and neither does following an ask already sent (the samerequest_id, after a reload). - A missing key, a wrong key or a failing service all arrive as an error with a
codeand amessagea person can read. When a key is missing (credential_missing), Nest says so itself at the top of the screen with an "Open the key vault" button, so the screen only says briefly that it could not; for any other error the screen showserr.message.
Declaration
ui/translate/piece.json, written last:
{
"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
}
}queriesare the named reads (task,table,file,need,outcome,memory, or{source: "tool", tool}for aGETreadtool of the owner). At most 8.actionsare the named actions:{tool}calls a tool of the owner,{table, op: "insert" | "update" | "delete"}writes a table within the owner's write access. At most 8.inserttakes{rows: [{column: value}]}and answers{ids}.ask: truelets the screen ask the owning Soot. Off by default.- The tool must be written before
piece.json: an action pointing at a tool that does not exist refuses the save withtool_unknown.
The write's result carries the note {"screen": "soot:writer:translate", "saved": true, "state": "proposed", …}.
The person approves once
The first save raises one item in Cần bạn (Needs you) for the screen and the tools it uses. The card shows where the screen sits, who sees it, what it reads and which buttons it has; and for each tool: what it does (only reads, or sends and changes data), the method and the host it sends to, which keys it needs (title and name) and whether each is set ("Đã có" / "Chưa có", set / not set). A key already set that this version would send to a new host is said right above the approve button; a host the key's field named when the person typed it is not new. A key that is not set gets one secret field and a "where to get the key" link, which asks the person to confirm its host before it opens. The person enters the key, presses "Lưu khóa" (Save key; the value goes straight to the runtime and the field clears), then "Duyệt và đặt vào Nest" (Approve and place in Nest): the screen shows in the side bar and the tool can run.
The Soot never sees the key and never asks for it in chat. Approving without the key is allowed; the first translation then says the key is missing and Nest takes the person to the key vault.
Once placed, the Soot may change the look freely and new versions go live at once. But adding a host or a key, changing the method, going from read to write, adding an action with a new target, changing a memory query's search, turning ask on, or changing the slot or who sees it is refused (approval_needed); to reach further, save under a new id so the person is asked again.
Answering a question from the screen
A question reaches the Soot as a message in the viewer's own conversation: the first line is Hỏi từ màn hình “Dịch” (asked from the screen “Dịch”), then the question, then the screen's data as a JSON block. The Soot answers as it answers any message: its last message is reply.text. This run also has the piece_reply tool; the Soot calls it with data holding one JSON value (written as a string, at most 16 KiB) so the screen gets structured data, here {"translation": "…"}. The person can open that conversation from the screen's header ("Mở cuộc trò chuyện", Open the conversation) and keep typing there.
The operator's question runs in the owner's workspace, so the Soot can use its own tool (tool_translate) and the glossary. A member's question runs in the member's own place, without the owner's tools or keys.
Trying it
- Let the Soot select the
soot-nestpack (it ships with the runtime): itsnest-piecesskill teaches exactly these steps. A Soot that selectsreadalready has thestorageanddatatools. - Tell the Soot what you need. It writes the files and says the item waits in Cần bạn.
- Open the card, preview the screen, enter the key, approve. Open "Dịch" in the side bar, translate a sentence, ask the Soot a question.
- Without Nest, open
http://<runtime>/v1/pieces/soot:writer:translate/in a browser to see the screen; that shell is at bridge level 1, sosoot.runandsoot.askwork only in Nest.
The full guide for written pieces (every query source, the lifecycle, the kit) is Screens a Soot makes (written-pieces, in the repository).
Path 2: a pack brings the screen
The example below is a minimal pack, hello-board: a "Board" section in Hộp việc, read by one tool, with a second tool that pins a line. soot init-pack hello-board --with tool creates the folder; the four files below are all the rest.
hello-board/pack.json
hello-board/tools/board.mjs
hello-board/ui/board/index.html
hello-board/ui/board/app.jsDeclaration
pack.json. Pieces sit in interface.pieces; data.view_tool and data.action_tool name two tools of this same pack.
{
"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"}
}
]
}
}- A piece's
idis English, lower case with hyphens, unique in the pack. A pack declares 1 to 8 pieces. accessisoperator(the operator only) ormember(also members who reach the Soot that serves the piece).bundleis a directory in the pack that holdsindex.html, 5 MiB at most.- The read tool must have
run.mode: "read"; both tools takerun.stdin: "context". A tool that needs approval (approval) cannot be a piece's tool: a screen does not draw an approval step. - An unknown field is an error.
interface.pagesis the older name and no longer loads; the load error says how to move topieces.
The read tool and the action tool
The runtime runs a tool with one JSON object on stdin and reads one JSON object from stdout. Besides the input the screen sent, the tool gets piece (the serving Soot, the piece id, and mode: view or action) and viewer (who is looking).
tools/board.mjs:
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: "Release 1.4 ships on Friday" },
{ id: "interview", text: "Interview the support candidate at 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);
}- Treat
inputas untrusted: it comes from a page in a sandbox, so check it like any other input. - The tool runs as the Soot that serves the piece, with the same grants and credentials as when that Soot calls the tool itself. The screen adds no access.
- An action runs exactly once per
request_id. Sending the same id again returns the earlier result; the tool does not run twice. - Never return a secret from a read: Nest keeps the last result on the viewer's device so a screen opened again shows at once.
Bundle
A bundle is an ordinary web page. The two links _kit/piece.css and _kit/piece.js are served by the runtime in every session: the kit handles the bridge to Nest, and colours and type that follow Nest, light and dark. The bundle's CSP blocks inline script and style, so the script is its own file.
ui/board/index.html:
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Board</title>
<link rel="stylesheet" href="_kit/piece.css">
<p id="state" class="muted">Loading…</p>
<ul id="lines" class="list"></ul>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>ui/board/app.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) }, "Pin"))));
state.textContent = out.total ? out.total + " lines" : "Nothing here yet.";
}
async function pin(button, line) {
button.disabled = true;
try {
await soot.action({ pin: line.id });
button.textContent = "Pinned";
} catch (err) {
button.disabled = false;
state.textContent = "Could not pin: " + err.message;
}
}
// Opened again: draw the last result at once, then read fresh data.
soot.ready(() => { const last = soot.cached({}); if (last) draw(last); });
// Reads again on a change, when shown again, and every minute while shown; rests while hidden.
soot.live(async () => {
try { draw(await soot.view({})); } catch (err) { state.textContent = "Could not read: " + err.message; }
});A pack piece calls soot.view(input) and soot.cached(input) without a name; a written piece calls them by query name. The rest of the kit is the same for both.
Trying it
- Put the pack folder in the workspace's
packs_dirand let a Soot select it:{"packs": ["hello-board"]}. soot check --showloads the pack as the runtime will. A wrong piece declaration is reported aspiece_invalidwith the piece and the reason (tool_missing,view_not_read,stdin_not_context,bundle_missing,bundle_too_large,tab_required,unknown_slot…).- Run the tool by hand with what the runtime will send (the command below); it must print one JSON object.
- Start the runtime and open Nest: the piece is in Hộp việc at once, with no question asked, because the operator already selected the pack. Without Nest, open
http://<runtime>/v1/pieces/pack:hello-board:board/in a browser: it is a shell page that builds the same frame and bridge as Nest and asks for an operator key once (the runtime's own origin must be inserver.browser_origins). - Edit the bundle and open the screen again. An open frame keeps the earlier copy for up to 10 minutes (the life of a session).
echo '{"piece":{"soot":"helper","piece":"board","mode":"view"},"input":{"q":"release"},"viewer":{"kind":"operator","id":"operator"}}' | node tools/board.mjs viewRelease the pack like any other; see Agents, teams, packs, Forge.
What the operator decides
Other people's screens run in your Nest, so the last word is yours.
- A screen a Soot wrote must be placed by you. The first time, it is an item in Cần bạn: you see a preview, where it will sit, who will see it, what it reads and whether it sends actions, then place it or decline. When you decline, the Soot is told and does not ask again until it changes the content.
- Once placed, it does not reach further by itself. The Soot is free to change the look and the filters, but it cannot change the slot, who sees it, whether it sends actions or which data it reads on a screen you approved.
- Going back and removing. Every written screen has a version history; you go back to the earlier version or remove it from Nest on the screen itself. A new version that fails to load twice on your device, and never loaded, is rolled back by the runtime to the last good one.
- A pack's screen follows the pack. It is there when a Soot selects the pack and gone when it does not. Selecting a pack is your decision, so Nest asks nothing more.
- The layout is yours. Cài đặt › Màn hình (Settings › Screens) lets you order and hide each screen; the layout lives on your device. A Soot can only propose a layout, and you apply or decline it.
- You approve tools and keys. _[0.19.0]_ When a screen uses a tool a Soot wrote, its card says what each tool does (only reads, or sends), which method and host it sends with and which keys it needs, set or not. A key that is not set can be entered right on the card, or later with "Mở Kho khóa" (Open the key vault) when the screen says it is missing. You can approve without the key; the tool runs only once the key is set.
- See which one is heavy. Also in Cài đặt › Màn hình: how long each screen takes to open on this device, how often it failed to open in time, and which read was too large.
Limits and safety
- A sandboxed frame. Each screen runs in a frame of its own, with no credentials, no network calls (
connect-src 'none') and no form posts. It talks to Nest only over thepostMessagebridge, and Nest passes a call only to that same piece. - What a frame can still do. A CSP cannot stop a page from navigating itself. When a frame leaves its bundle, Nest closes it and counts a failed load, but the address it went to has been requested. So treat what a screen can read as something its author can read: place screens only from Soots and packs you trust, as when you grant them access.
- No access of its own. The owner's access is the ceiling, checked at save and again on every call. A screen cannot grant itself any permission, cannot read a key, and learns that a key is missing only from the runtime's answer to a call.
- Opening links.
soot.openand an<a>tag ask Nest to open a link. Nest accepts one only while the screen is shown, at most once a second, and never opens Nest's own browser frame for a screen. - The numbers. A bundle is 5 MiB at most; in
home, script and style are 512 KiB at most. Callsoot.ready()within 1 second (over 5 seconds is a failed load). Each read returns under 256 KiB. The same read reaches the runtime at most once a second while shown and once every ten seconds while hidden; after an action, or when the runtime says something changed, the next read always reaches the runtime. Written pieces: at most 8 per owner, 8 queries per piece, 10 actions a minute. _[0.19.0]_ Actions and questions count together: 10 a minute per viewer, 30 for the whole piece; the input ofsoot.runandsoot.askis 8 KiB at most, a question's text 4000 characters. Written tools: at most 16 per owner, 30 calls a minute per tool, an answer of at most 256 KiB, a wait of at most 60 seconds (20 by default). - Light by default. Nest opens a frame only when it is about to come on screen, at most 4 at once; a hidden frame sets no timer and asks the runtime nothing. Use
soot.liveinstead of a timer of your own.
When Soot and Nest move to a new version
A screen you make today keeps running on later versions. Four things to know:
- `kit`. The manifest may say
"kit": 1: the version of the kit the bundle was written for. Leaving it out also means 1, and that default never moves. A runtime that does not serve the version you name refuses withkit_unsupportedand says which one it serves. - Later additions. The bridge between a frame and Nest has a level (
soot.level). Nest 0.18.0 is at level 1; level 2 addssoot.run,soot.askandsoot.asks. A feature added later carries a higher level. A screen that wants it checkssoot.levelfirst, so it still runs on an older Nest: at level 1 the kit refuses those three calls withunsupportedand sends nothing. - Nest's messages may gain fields. Nest may add a field to one of its messages (
init,result, …) without a level change. A screen that uses the kit has nothing to do: the kit reads only the fields it needs. A bundle that speaks the bridge itself must ignore a field or a message type it does not know, and never check a message against a fixed list of fields: such a screen breaks the next time Nest adds one. - Breaking changes. They always carry a new
kitnumber and take two releases: the first serves both the old kit and the new one, and only the next drops the old one. In between, the runtime tells the owner Soot so it can rewrite its screen; a pack ships a new version on Forge.
The full rules are in the pieces standard, under versions and migration.
When something goes wrong
| What you see | Why | What to do |
|---|---|---|
Writing piece.json answers saved: false | reason names the problem and message says how to fix it | Fix it and write piece.json again |
approval_needed | A placed screen is reaching further than the version the person approved | Keep the reach as placed, or save under a new id |
kit_unsupported | The manifest names a kit version this runtime does not serve | Leave kit out or write the version the error names; if the screen needs a newer kit, update Soot |
soot check reports piece_invalid | A pack's piece declaration is wrong | Read reason and the pointer to the field |
retired_field at /interface/pages | The pack still uses the older name | Move to interface.pieces as the error's hint says |
| A blank frame, then "did not open in time" | The page did not call ready within 5 seconds, usually because an inline script was blocked by the CSP | Move the script to a file and link _kit/piece.js first |
tool_refused with approval_required | The piece's tool needs approval | Use a tool that needs none for a screen |
429 busy | All pack pieces share 8 tool slots | Nest retries by itself; keep the read tool fast (under 500 ms) |
rate_limited | More than 10 actions a minute on one written piece | Wait for retry_after |
owner_unavailable | The screen's owner cannot take work now | Nothing was sent: let the person try again later |
ask always answers owner_unavailable | The owning Soot is only a member of a team, not a Soot a direct conversation can open with | Let that Soot stand alone or be one of the team's entries (entries); or let the coordinator write the screen at the team's level |
gesture_required _[0.19.0]_ | The screen called soot.run or soot.ask on load or from a timer, not right after a click or a key press by the person | Call those two only from a click handler; read on load with soot.view and soot.asks |
A button inside a <form> does nothing | The frame has allow-scripts only, no allow-forms: the submit event never arrives | Drop the <form>; use button type="button" with a click handler |
| A bundle that speaks the bridge itself breaks after a Nest update | The screen checks Nest's messages against a fixed list of fields | Ignore fields and message types it does not know; or use the kit |
| "Mở cuộc trò chuyện" (Open the conversation) goes to the wrong place | The screen builds the link from run_id or another id | A question's conversation is the conversation_id in its result (32 hex characters): soot.open("nest://conversation/<conversation_id>") |
credential_missing _[0.19.0]_ | The tool's key has not been entered | The person enters the key on the card or in the key vault ("Mở Kho khóa" shows on the screen); never send a key in chat |
credential_rejected _[0.19.0]_ | The service answered 401 or 403: the key is wrong or expired | The person replaces the key in the key vault |
upstream_error, timeout, request_failed _[0.19.0]_ | The service answered an error, took longer than timeout, or could not be reached | Read status and body (the key is removed); check url and body against the service's documentation |
Saving tool.json is refused _[0.19.0]_ | reason names the problem: run_invalid, method_needs_write, host_not_declared, credential_not_declared, input_invalid, manifest_invalid, approval_needed… | Fix exactly the field message names and write tool.json again |
Saving piece.json answers tool_unknown _[0.19.0]_ | An action or query points at a tool not written yet or retired, or a query reads a tool that does not use GET (write, or read with POST) | Write tools/<id>/tool.json first, then write piece.json again |
| The screen does not change after an edit | An open frame keeps its earlier session | Close the screen and open it again |
Content reviewed: 2026-11-12