06 / Extensions
Core and extensions: extending Soot and Nest
What belongs to the core and what is an extension; the tool contract; extending Nest; which layer a new need goes in.
Soot is a fixed runtime. New project work (customer support, publishing posts, order reconciliation, contract review) does not go into the binary. It goes into config, skills, tools and packs. This document describes where the boundary between core and extensions sits, which layer new things belong in, and what must never be added to core.
It is for people adding features to Soot or Nest, or writing packs. The root rules are in AGENTS.md (Hard constraints); this document explains why they exist and how to apply them.
Model
┌────────────────────── EXTENSION (no binary rebuild needed) ────────────────────────┐
│ pack = skills + tools (+ interface, pieces, storage, programs, platforms) │
│ adapter / ingress (separate process, started by the deployment) │
│ Soot definition + deployment.json (config) │
└───────────────▲──────────────────────────────▲─────────────────────▲───────────────┘
soot/v1 envelope (stdin) channel-adapter.v1 (HTTP) pack.json (read, displayed)
┌───────────────┴──────────────────────────────┴─────────────────────┴───────────────┐
│ CORE (internal/core): AgentCore host, store, auth/grants, credentials vault, │
│ management, channel host, piece host, workspace, transport/httpapi │
│ FEATURE (internal/feature, via hooks): traces, monitoring, train, improve, │
│ jobs, mcpserver, autoupdate, browserinstall, adapter │
│ COMPOSE (internal/compose): app, scaffold, features; where features are linked in │
└───────────────▲────────────────────────────────────────────────────────────────────┘
│ HTTP /v1/* + registry
┌───────────────┴────────────────────────────────────────────────────────────────────┐
│ NEST: shell + registry (rail, Settings, Dữ liệu, renderer). Displays, grants none │
└────────────────────────────────────────────────────────────────────────────────────┘Three principles that say the same thing:
- Work reaches a Soot first: an event, then a Soot, then (optionally) a tool. No dispatcher stands in front of Soots.
- A workload is config, skills and tools. Adding a workload does not require rebuilding the binary.
- Core does not import contrib or packs. Extensions plug into core through narrow contracts, not through code.
Concepts
| Term | Meaning |
|---|---|
| Core | What every deployment needs and what does not change per project: the agent run loop (via AgentCore), conversation storage, authentication, grants, the vault, config management, the host for chat channels and for Nest pieces. |
| Feature | A Go package under internal/feature/ that is not part of core: traces, monitoring, train, improve, jobs, mcpserver, autoupdate, selfupdate, browserinstall, adapter, evalcase. Plugged into core through hooks and linked with a blank import. |
| Compose | The composition layer under internal/compose/: app, scaffold and features. It may import both core and features; features are linked into the binary here. No core or feature package imports it. |
| Extension | Anything that runs or is read without rebuilding the binary: pack, tool, skill, adapter, piece, renderer. |
| Pack | A distribution bundle of skills and tools. A Soot selects a whole pack. Installing is not granting. The pack model and how selection works: agents.md. |
| Tool | An executable declared in pack.json with run: {program, args, ...}. It talks to the host with the soot/v1 envelope. |
| Adapter | A separate process that speaks one platform's protocol (Telegram, Discord, a browser). Started by the deployment, not by a pack install. |
| Piece | A small HTML bundle shipped by a pack and placed in one of Nest's slots (rail, home, project.tab, data.tab, settings). It is only UI. |
| Nest registry | The list of areas, slots, pieces, Settings sections, Dữ liệu tabs and renderers from which Nest builds the rail and palette. |
What core contains
The boundary is in the path: every package under internal/ belongs to exactly one of four directories.
| Directory | Holds | Import rule |
|---|---|---|
internal/core/ | What every deployment needs: config, configstate, sqlstore, authz, access, credentials, conversation, channel, workspace, operations, management, pieces, principal, runtime (the engine), firstrun, ledger, transport, and the libraries they use (hostio, providers, toolrun...). The module-root package contract is core too. | Imports only core (but for the two allow edges); never compose/ or test/ |
internal/feature/ | train, improve, monitoring, traces, adapter, browserinstall, autoupdate, selfupdate, jobs, mcpserver, evalcase | Imports core and other features |
internal/compose/ | The composition layer: app, scaffold and features (the blank-import list) | Imports core and features |
internal/test/ | guard, testutil, scenarioe2e, projecte2e, storebench | Used by tests only |
contracts/core-layering/layers.json declares these four groups and the core → feature edges that are still tolerated. There are currently two: core/conversation → feature/monitoring and core/conversation → feature/traces (waiting for conversation to be split). The allow list can only shrink.
TestCoreLayering checks the direct imports of every core package and the full closure of core/config, and fails when a package under internal/ is in no group or in two. Core and features may not import compose/... or test/... (production imports); core builds without the composition layer.
Other tests hold the boundary:
| Test | What it holds |
|---|---|
TestCoreLayering (internal/compose/app/layering_test.go) | Core does not import features, compose/ or test/; features do not import compose/ or test/; every package under internal/ belongs to exactly one layer. |
TestDependencyDirection, TestCoreDoesNotLinkContrib (internal/compose/app/architecture_test.go) | domain knows nothing of os or HTTP; runtime knows nothing of modules, providers or transports; no core package imports contrib/. |
TestCoreIsCSFree (internal/test/guard/) | Core, contract, docs/contracts/ and desktop/src/ contain no vocabulary of a specific industry. The exception list can only shrink. |
TestCoreIsGoalFree (internal/test/guard/) | Non-test files under internal/core/ and contract/ do not name the goal layer (the workspace feature's tables, workspace.goals section, cards, routes and scopes). The exception list goal_allowlist.txt can only shrink. |
desktop/tests/pack-names-guard.test.mjs | No Nest file compares or lists a specific pack id, platform id or interface kind. The exception list started empty and should stay empty. |
desktop/tests/core-words-guard.test.mjs | desktop/src/app/ and desktop/src/lib/ name no pack, project kind, tab, team purpose or workspace concept (goal, project, campaign), in English or Vietnamese, as an identifier or a string. What still names one is a row of core-words-guard.allow.json (file, line count, why), and the list only shrinks. |
Hooks: how a feature plugs into core
Core owns the hooks; a feature calls Register* from its own package's init(). Every Register* panics on a duplicate.
| Hook | What it plugs in | Code |
|---|---|---|
config.RegisterSection | A top-level config block for the feature (traces, monitoring, train...) | internal/core/config/sections.go |
config.RegisterMemoryLevel | A memory level (workspace, team, soot, user) | internal/core/config/memlevels.go |
sqlstore.RegisterTenant | The feature's tables and migrations in the same SQLite | internal/core/sqlstore/tenants.go |
management Register(ActionSpec) | A config action (soot.create...), which is at once a soot manage command, an MCP tool and a button in Nest, with undo | internal/core/management |
httpapi.RegisterRoutes | The feature's /v1/... routes, mounted after core routes, inside the operator boundary | internal/core/transport/httpapi/routes.go |
httpapi.RegisterAttention | An entry in GET /v1/settings/attention | same file |
httpapi.RegisterHostAttention, RegisterCardKind | A host attention source (grouped items) and a card kind by id prefix, with its severity | internal/core/transport/httpapi/extend.go |
httpapi.RegisterViewField | One more member on a core view (GET /v1/workspace/summary), written after the view's own | same file |
httpapi.RegisterProjectSource | The project source of GET /v1/projects: kind, names, logos. Core works out which teams carry which project. With no source the list is empty | internal/core/transport/httpapi/projects.go |
workspace.RegisterMigration, RegisterPortable | A feature's tables in the workspace store (SQLite and PostgreSQL) and their rows when a team moves | internal/core/workspace/extend.go |
workspace.RegisterTool, config.RegisterHostTool | A model-facing tool the feature offers besides a Soot's own selection | internal/core/workspace/extend.go, internal/core/config/host_tools.go |
workspace.RegisterLinkCheck | Checks a task's link value (the goal field); without one core keeps the value as given | internal/core/workspace/extend.go |
config.RegisterSection with a dotted name | A child block inside a core block (workspace.goals): strict decoding, same JSON key, still in the schema | internal/core/config/sections.go |
conversation.Service.RunBlock | The host context block a run is given; compose sets it | internal/core/conversation/service.go |
principal.RegisterEraser | Delete a person's data on an erasure request or when retention expires | internal/core/principal/registry.go |
ledger.Traces, ledger.Jobs, ledger.Monitor | The trace, job and monitoring stores the engine writes and reads. Compose attaches them to runtime.Engine; an empty slot means the engine skips what that store would do | internal/core/ledger |
configstate.RegisterBundleAdmission, RegisterGeneralOpener | Admitting a deploy bundle and opening the Forge General for management; scaffold registers them. Without them a deployment is refused (bundle_admission_unavailable) and a General release fails with ErrNoGeneralOpener | internal/core/configstate/host_hooks.go |
The actual linking is in internal/compose/features/features.go: cmd/soot and the end-to-end tests blank-import this package once. internal/compose/app does not import it. A binary or test that does not link internal/compose/features has no feature sections, routes or actions, and the feature's key in a deployment becomes an "unknown field".
An acworkspaceing rule: types shared between core and a feature live in core ("types move down"). For example, adapter.Overlay moved down to config.
internal/core/principal/registry.go is the smallest example of this kind of hook. The file imports only context, sort, sync. Every store that holds data about a person (packstore, piecereceipts, chat channels) registers an Eraser; the erasure route runs all of them, and each eraser is idempotent. Core does not need to know which stores exist.
Tools: the executable contract
Tools are the most common way to extend Soot. The public contract is the contract/ package (contract/contract.go), which does not depend on the runtime. A tool does not need a Go SDK: it reads JSON from stdin and writes text to stdout/stderr. The TypeScript SDK (@tofound/soot-sdk, contrib/sdk/typescript/) has types and a codec ready if you want them. The Go types of the envelope are in contract/; see the pack.json schema with soot schema pack, and scaffold a new pack with soot init-pack.
// packs/research/pack.json: the folder name is the pack id
{ "tools": [ { "name": "inspect",
"run": { "program": "tools/inspect.sh", "stdin": "context", "timeout": "30s" } } ],
"needs": { "env": ["HOME"] } }
// Operation ID is always <pack>_<tool>: "research_inspect"The model calls the tool by its id (research_inspect); a tool that declares no parameters takes {}. With run.stdin: "context", the host sends one JSON object, a newline, then EOF:
{ "api_version": "soot/v1", "hook": "tool.call", "soot": "assistant", "root": "assistant",
"operation": "research_inspect",
"event": { "id": "1", "source": "conversation", "subject": "...", "text": "..." },
"input": { "query": "..." } }Beyond the fields above, the host may add project, team, principal + principal_token (a 60-second signature, see principal-token), piece + viewer (when the tool is called from a Nest piece), approval, read_only. A tool must accept unknown fields in v1, reject an unsupported api_version or hook, and treat all of event and input as untrusted data. tool.preflight is the second hook: it asks the tool whether this call can run before asking a person to approve; this hook must not change anything.
Path resolution and permissions
| Item | Rule |
|---|---|
Relative run.program | Resolved from the declaring pack's directory; cannot escape with .. |
Bare name (bun, node) | Looked up in the operator's PATH, only for operations that have been granted. A pack that is not selected demands no dependency |
| Absolute path | A deliberate operator binding, which reduces portability |
| argv, working directory, environment | Taken from validated config. The model cannot change them; stdin is the only channel for model input, and input never enters a path, argv or env |
| Secrets and env | Granted only by the host. The pack declares needs, and the host grants through grants.packs. A tool may not set run.env (pack_tool_env) |
What a tool never receives: the prompt, conversation history, provider config and the model's API key, the contents of the Soot's database. To call back into the runtime, the pack declares needs.runtime and receives a narrow token (its own runtime, not another one). To store data, use pack storage below.
Effects: exit 0 is success. An error, a timeout or an unclear result is written to the effect journal. The same operation and input within one run is replayed from the receipt, not run again. An unclear result keeps the resource fence across restarts, and the operator checks before retrying. Renaming an operation to get around the fence is wrong. A long-running tool declares run.background: true to use AgentCore jobs (runtime.md). A job's receipt is not the result: the agent gets the result with the job tool (op wait or status), and tool output streamed while running in the background becomes the job's live output. A subagent receives only the capabilities AgentCore allows, and does not widen the permissions the host has granted.
_[0.19.0]_ run.http is a second runner, for tools a Soot or a team writes itself (tools/<id>/tool.json) and for tools in pack.json. It runs no program: the host sends exactly one HTTPS request to the host written in the URL and listed in needs.hosts (no IP, no port, no redirects, through the 2ai guarded client), fills input into the marked places and the key ({{cred:NAME}}, only in a header or the query) right before sending, then removes the key from the answer and errors before anything is recorded. A written tool's keys live in the vault by (owner, name), apart from pack keys; the person enters them in Nest and nobody reads them back. A write tool goes through the effect journal and the approval policy like a pack tool. In pack.json a tool declares run: {http: {...}, mode} instead of a program, with parameters as its input schema and an optional output.pick; the pack lists its hosts once in needs.hosts, and the keys are the pack's like any other tool's (needs.credentials, entered in Kho khóa or granted through grants.packs). mode: read is GET or POST only. A pack piece calls these tools by name (data.queries, data.actions) and asks the Soot serving it (data.ask). Contract: nest-extensions §14.
read_only: true means the host lets this run only read (for example Lead's morning briefing), so the tool must refuse every change. case_id is an old, optional field; core does not create or grant cases. The casework pack is an example of a workload that uses this contract without adding any run loop or case store to core.
Pack: what a pack carries
A pack declares what it provides and what it needs. It does not declare identity, prompts, routes, triggers, schedules or credentials (those belong to the Soot definition and the deployment; see agents.md).
Part of pack.json | Effect | Layer |
|---|---|---|
skills/<name>/SKILL.md, tools | Knowledge and actions for the agent; a skill keeps the name in its frontmatter, with no pack prefix | granted per pack |
needs | Credentials, env, runtime that tools read | granted by the host through grants.packs |
name, keywords | Name and keywords for Nest. The pack id is the folder name | display only |
interface.tool_areas, renderers | Nest draws a work area for granted tools (browser, canvas) | display only, grants no extra tools |
interface.pieces | HTML pieces placed in Nest's slots | display only |
interface.subject | A "who is this person" card for channel conversations | display only |
storage | The pack's own tables | provisioned and scoped by the host |
programs | Programs the pack needs installed on the machine (Chromium...) | through check_op/install_op |
channel.platforms | Chat platforms a binding can use, with an install form | display only |
Detailed contracts: pack-manifest-ui, pieces, pack-storage.
Pack storage
A pack declares its own tables in storage. The runtime creates the tables when a Soot selects the pack, and each tool call is given a token that works only for that call, bound to (pack, soot, workspace): the tool does not choose its own scope. Only additive changes are allowed; a breaking change is rejected and the old pack version keeps running. A principal column goes into erasure automatically. A pack cannot declare triggers, views or raw SQL, so core is not extended into its schema. When the pack is removed, its tables are hidden for 30 days and then deleted.
Sharing packs
A pack is a self-contained directory (no pointers to siblings, no symlinks), installed with soot add from Git or from an archive with a checksum. Installing does not grant permissions and does not auto-update. Shared packs go through a pull request into Soot Forge, where a release with a checksum is the default install source for soot spawn. A pack whose logic lives in a separate service declares program: "soot" with soot tool-forward, so it can run on a VM that has only the soot binary; see soot tool-forward --help.
Adapters and chat channels
An adapter is a process that speaks one platform's protocol. Three things keep it out of core:
- Ingress belongs to the platform. The deployment starts it and attaches the account. Installing or selecting a pack never starts ingress.
- There is no registry or distribution layer for adapters in core, and no second dispatcher.
- An adapter is a durable, dumb pipe. Identity, admission, pairing, conversation mapping, outgoing content and every word the user sees are held by the host.
For chat channels the contract is channel-adapter (channel-adapter.v1, with additive revisions 1.1 through 1.3). Bindings are declared in the deployment; the runtime runs the adapter as a supervised child process (fixed argv from the deployment, not from a pack or the model), issues an sca_ token valid only on that binding's /v1/channel/*, and passes along only a minimal environment (no provider key or operator token). A remote adapter is built with the TypeScript SDK (./channel) and speaks the same contract. A pack only declares which platforms can be attached (channel.platforms) and the install form shown in Nest; secrets are entered through the secret sheet into the vault, never into pack.json. The host code is in internal/core/channel/.
Nest: extending through registries
Nest is a super app: its interface is made of pieces. Nest owns the frame: where a piece can go, how it is laid out, what it may read. What sits inside the frame is a piece, and a piece can come from Nest itself, from a pack, or from a Soot or a team that wrote it. A screen built in today can move to a pack, and a Soot can add or change a screen for the person it works with without a Nest release: it writes a few files, the person agrees once, and the screen is there. The operator keeps the last word: place, arrange, go back to the earlier version, remove. Nest opens a frame only when it is about to be seen and lets it rest when it is not, so more pieces do not make Nest heavier. The step-by-step guide for each kind of author is build-a-piece; the standard every piece follows (names, manifest, interfaces, structure, checks) is pieces; the contract is nest-extensions.
Nest builds the rail, the command palette (⌘K), Settings and Dữ liệu (Data) from the registries in desktop/src/app/registry/ (nest-registry v2). Nowhere in Nest does code branch on a pack name.
Nest's own screens are pieces too, declared through the same manifest. Each builtin extension lives in desktop/src/extensions/<id>/ and is registered once in src/extensions/index.ts: inbox (Hộp việc: the start area on the rail, which hosts the home slot), workspace (the goals tab, the project manager, a project's Kết quả) and support (the Hỗ trợ tab). The shell special-cases no id. The piece that hosts home is the start area.
Nest is a React + TypeScript + Vite SPA inside Tauri 2 (desktop/), using @tofound/ui. Each functional area is a folder src/modules/<feature>/; src/lib/ imports no modules or UI; src/app/ assembles the shell and registries. Data from the runtime goes through a single adapter, SootClient (src/lib/api/client.ts): TanStack Query for reads from the host, a connection store for conversations and SSE. In Tauri, Rust holds the credentials and forwards authenticated HTTP; the webview never sees the token and has no arbitrary URL proxy. Config reads, display and pack behavior come from the runtime's catalog, and Nest keeps no copy of permissions or defaults.
| To add | What to do | Does Nest change |
|---|---|---|
| A new core functional area of Nest | Add a AreaManifest (id, label, icon, lazy loader, group) | Yes, this is a core change to Nest |
| A screen in the rail, on home, in Dữ liệu or in Settings for a business function | The pack declares interface.pieces with slot rail, home, data.tab or settings | No. The runtime lists it in GET /v1/pieces as ref pack:<pack>:<id> |
| A tab inside a project (Hỗ trợ, Marketing, Nội dung: Support, Marketing, Content) | A piece with slot: "project.tab", tab {id, label} and teams | No. The old provides: ["flow-<id>"] is refused; an old flow-<id> link opens tab <id> |
| A screen a Soot or a team makes for the person it works with | The Soot writes ui/<id>/index.html, then ui/<id>/piece.json, in its own files (written-pieces) | No. The person is asked once, the first time; later versions publish themselves and can be rolled back |
| A builtin screen of Nest | A builtin piece in an extension under desktop/src/extensions/ | Yes, but only in that extension; src/app/ does not change |
| A way to draw a new kind of interface | The pack declares renderers with a bundle, and Nest frames it | No |
| An install form for a chat platform | The pack declares channel.platforms[].ui | No |
| A program install button | The pack declares programs | No |
Registry rules:
- The rail, palette, deep links, lazy loading and view permissions are computed from
AreaManifest[]; Settings fromSettingsSection[].presence: falsemeans no tab, no palette row, no link. - A registry entry grants nothing. It draws what the host's catalog and grants already allow.
- Each pack piece appears once per runtime. The runtime picks the serving Soot (
served_by): the Lead if it holds the piece's view tool, otherwise the first such Soot by id among those the viewer reaches.teamsare the teams with a Soot that selects the pack. Members see onlyaccess: "member"pieces; theinvalidlist (pieces no Soot can serve) is for operators only. - Nest reads
GET /v1/pieceson every connection and merges the catalogs into one list in slot order (order, then owner, then id). A piece ispiece:<connection>:<ref>, so one ref on two servers is two pieces, and two rail rows, each naming its server. - Projects come from
GET /v1/projects({kind, items}), merged byidacross connections. The switcher's noun iskind.label, else "Dự án" (Project). When the runtime answerskind: null, an empty list, a 404 or a 405, Nest treats it as no project source: no switcher, and the runtime'sproject.tabpieces are tabs of the whole workspace. Nest never builds projects from Soot labels or fromGET /v1/workspace/summary. - A project's tabs are the
project.tabpieces (builtin and runtime), grouped bytab.idand named by the first piece. A runtime piece is a tab of a project when one of itsteamsis one of the project's teams on the same connection. A Soot works for a project when it is in one of the project's teams, or its data label equals the project id. - The Tauri shell calls the runtime only through
runtime_request, with an allow-list declared indesktop/src-tauri/src/runtime_routes.rs. Routes outside the list are blocked before they leave the machine.
Pieces and renderers
A piece runs in a sandboxed frame, with a CSP that blocks network calls and forms, and no credentials. (The CSP cannot yet stop a frame from navigating itself; Nest closes a frame that left its bundle, see pieces.) It touches the runtime only through the postMessage v2 bridge: it sends a call (mode view or action), Nest turns it into POST /v1/pieces/{ref}/call and returns the result. A session opens with POST /v1/pieces/{ref}/session and the bundle loads from GET /v1/pieces/{ref}/s/{pvs}/…. Nest drops unknown messages and sends a call only for the frame's own ref. The init message carries viewer {kind} and project (which replaces v1's project/projects).
viewreads;actionwrites, needs arequest_id, and calling again with the same id returns the receipt instead of running again.- The tool runs as the serving Soot, receives
piece {soot, piece, mode}andviewerin the envelope, and has the same grants and credentials as any other call of the pack. - A tool that needs approval is refused from a piece (
422 tool_refused,reason: "approval_required"), because a piece has no approval step. Anoperatorpiece is not shown to members.
A pack's renderers use the same bridge and CSP. For a tool area that needs streaming (the browser), the host proxies frames through the runtime and does not embed a real window: embedding does not go through a remote runtime (how most Nests connect to Soot), macOS has no API for embedding another process's window, and Wayland forbids it. The browser's own endpoint (CDP port, token, profile path) never reaches the client.
Operating surfaces: MCP and REST
The operator MCP (mcp-operator) is another way to extend: it lets an outside agent (a coding agent, another Soot) control Soot. Points to remember:
- MCP tools are generated from the
ActionSpecregistry and the read views, plus each piece'sview/actiontools (piece__<pack>__<id>__view). Endpoints are not hand-written for each thing. - Authentication uses a scoped token (
sop_, shown once). A host token is not used for/v1/mcp. - Actions only a person may perform (approval) are flagged
PersonOnlyon the route; a scoped token always gets 403. Every call goes into the audit log.
This means that adding an ActionSpec or a read view automatically makes it available in soot manage, in Nest and in MCP, in the same transaction and with the same undo.
Never put in core
| Don't | Why | Do instead |
|---|---|---|
A dedicated endpoint for one workload (/v1/refunds/...) | Each workload becomes a fixed API that needs a rebuild, against the principle that a workload is config | Existing skill + tool (possibly through builtin/toolbox), or a new pack |
| A registry or distribution layer for adapters | Ingress belongs to the platform; if core knows which adapters exist, it becomes the dispatcher | An adapter process started by the deployment, speaking channel-adapter |
| A second dispatcher (its own task/case queue) | Two dispatchers mean two sources of truth about who does what | Work reaches a Soot first; jobs and subagents use AgentCore |
| Making a "case", ticket or worker a mandatory entry point | A case is an optional, passive record that neither blocks events nor triggers agents | A Soot receives the event; the casework pack is only a tool for recording |
| Its own loop, compactor, reviewer or job manager | There is only one agent runtime, and it belongs to AgentCore | Use AgentCore |
An import from contrib/ or a pack in core code | Core must run with no workload present | Packs and project repos hold industry knowledge |
| Branching on a pack or platform name in core or Nest | Every branch is a rebuild for each new pack | Declare it in pack.json (name, renderers, platforms) |
Industry vocabulary in internal/, contract/, desktop/src/ | TestCoreIsCSFree blocks it; core serves many kinds of workspace | Keep it in a pack |
| Nest running work in place of the runtime | Nest does not do the runtime's job | Fix the target runtime; see runtime.md |
Granting permissions from interface | tool_area, pieces and renderers are display only | The host grants through grants.packs |
Decision guide
Go from the top and stop at the first row that matches.
| I want... | Put it in | Notes |
|---|---|---|
| The agent to know one more procedure, policy or tone | Skill (in a pack, or SOUL.md/MISSION.md if it is identity) | No code. description says when to read it |
| The agent to do something with effects (call an API, write a file, publish a post) | Tool in a pack | A soot/v1 executable, operation name <pack>_<tool>, declare needs |
| The same skills and tools for many Soots, switched on/off once | Pack | A pack is the unit of selection and granting |
| A pack that needs to remember its own data | The pack's storage | Don't open your own DB; no triggers, views or SQL |
| Receive messages from a new platform | Adapter (process), binding in the deployment | Speaks channel-adapter; the pack only declares channel.platforms |
| Users need a screen in Nest to view or act on the pack's data | Piece (interface.pieces) | data.view_tool reads, data.action_tool writes, all permissions go through the tool |
| A canvas or live interface for a tool area | The pack's renderers | Streaming/input features follow capabilities, not kind |
| Run on a schedule, toward a goal, assign work | Config (schedule, task, goal) | Belongs to the deployment and workspace.md, not to a pack |
| Let an outside tool control Soot | MCP / REST with a scoped token; add an ActionSpec if a new action is needed | Don't hand-write endpoints |
| A shared Go feature that is not mandatory (a data store, a route, a config block) | Feature package + Register* hook + a line in internal/compose/features | Put the package under internal/feature/; layers.json needs no edit |
| A new core functional area of Nest | A new AreaManifest in the registry | Don't branch on packs |
| Change the agent run loop, conversation storage, authentication, the vault | Core change | Go through AgentCore first; see runtime.md |
If no row matches and you are thinking of "adding an endpoint" or "adding a dispatcher", stop and ask again: it is almost certainly a skill plus a tool.
Example: order reconciliation
Requirement: a Soot reconciles the store's orders against a bank statement table, reports mismatches in Nest, and posts alerts to Telegram.
- Reconciliation knowledge (rounding rules, when to count a mismatch): the skill
reconcile.mdin the packreconcile. - Reading statements and orders: two tools,
fetch_ordersandfetch_statements(run.mode: read), declaringneeds.credentialsfor the store's API key. The host grants it withsoot grant reconcile. - Recording mismatches: the tool
record_mismatch(mode: write) saves into the pack'sstorage, a tablemismatcheswith columnsorder_id,delta,status(text columns havesearch: true). - Viewing in Nest:
interface.pieceshas a piece withslot: "data.tab",access: "operator", adata.view_toolthat readsmismatches, and adata.action_toolthat marks a row handled (withrequest_id). Not one line changes indesktop/. - Running daily: a schedule in
deployment.jsonpointing at the Soot. No new worker. - Telegram alerts: a Telegram binding in the deployment; the pack
chat-channelsalready has the adapter. Thereconcilepack does not touch the platform. - Checking:
soot check --show; test the tools separately with valid and invalid input; evals in the Soot'sevals/.
Go lines added to core: 0. No binary rebuild. If you later need a permission level that does not exist yet (for example an MCP token that can only read the mismatches table), that is a core change, and it goes into an ActionSpec or a scope, not into a dedicated endpoint.
Limits and what is missing
conversation → monitoring/tracesremain two tolerated core → feature edges, waiting for conversation to be split.- No core → compose or feature → compose edge remains:
TestCoreLayeringrefuses both.core/runtimereaches the trace, job and monitoring stores through thecore/ledgerinterfaces, andcore/managementreaches bundle admission and the Forge General opener through thecore/configstatehooks (scaffoldregisters them). A build that does not linkinternal/compose/scaffoldrefuses a deployment (bundle_admission_unavailable) and a General release (ErrNoGeneralOpener) instead of skipping the check; an engine with no store attached skips the work that store would do, as it did with a nil store. - The pieces mechanism of nest-extensions runs on both sides for all four owners: builtin pieces, pack pieces, and pieces a Soot or a team wrote (a proposal with a preview, version history, going back, load reports), with each person's own layout. Still missing: a layout does not follow the person to another device;
tool-areapieces do not replace renderers yet; a frame navigating itself is not stopped at the source; authors have no check and preview command of their own. The full list is in pieces. - There is no official Go SDK for MCP; the transport belongs to core, and an SDK, when added, will sit behind the same interface.
- The TypeScript SDK currently covers the tool envelope and the conversation client; messaging and storage on the SDK side are planned.
- A few places in older documents still mention
capabilities.<name>(such asbuiltin/README.md); the current config is flat and no longer hascapabilities.
Content reviewed: 2026-11-12