Soot DocsHow Soot is designedMarkdown ↗

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

Sample text · not a command
            ┌────────────────────── 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:

  1. Work reaches a Soot first: an event, then a Soot, then (optionally) a tool. No dispatcher stands in front of Soots.
  2. A workload is config, skills and tools. Adding a workload does not require rebuilding the binary.
  3. Core does not import contrib or packs. Extensions plug into core through narrow contracts, not through code.

Concepts

TermMeaning
CoreWhat 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.
FeatureA 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.
ComposeThe 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.
ExtensionAnything that runs or is read without rebuilding the binary: pack, tool, skill, adapter, piece, renderer.
PackA 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.
ToolAn executable declared in pack.json with run: {program, args, ...}. It talks to the host with the soot/v1 envelope.
AdapterA separate process that speaks one platform's protocol (Telegram, Discord, a browser). Started by the deployment, not by a pack install.
PieceA 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 registryThe 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.

DirectoryHoldsImport 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, evalcaseImports 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, storebenchUsed 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:

TestWhat 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.mjsNo 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.mjsdesktop/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.

HookWhat it plugs inCode
config.RegisterSectionA top-level config block for the feature (traces, monitoring, train...)internal/core/config/sections.go
config.RegisterMemoryLevelA memory level (workspace, team, soot, user)internal/core/config/memlevels.go
sqlstore.RegisterTenantThe feature's tables and migrations in the same SQLiteinternal/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 undointernal/core/management
httpapi.RegisterRoutesThe feature's /v1/... routes, mounted after core routes, inside the operator boundaryinternal/core/transport/httpapi/routes.go
httpapi.RegisterAttentionAn entry in GET /v1/settings/attentionsame file
httpapi.RegisterHostAttention, RegisterCardKindA host attention source (grouped items) and a card kind by id prefix, with its severityinternal/core/transport/httpapi/extend.go
httpapi.RegisterViewFieldOne more member on a core view (GET /v1/workspace/summary), written after the view's ownsame file
httpapi.RegisterProjectSourceThe project source of GET /v1/projects: kind, names, logos. Core works out which teams carry which project. With no source the list is emptyinternal/core/transport/httpapi/projects.go
workspace.RegisterMigration, RegisterPortableA feature's tables in the workspace store (SQLite and PostgreSQL) and their rows when a team movesinternal/core/workspace/extend.go
workspace.RegisterTool, config.RegisterHostToolA model-facing tool the feature offers besides a Soot's own selectioninternal/core/workspace/extend.go, internal/core/config/host_tools.go
workspace.RegisterLinkCheckChecks a task's link value (the goal field); without one core keeps the value as giveninternal/core/workspace/extend.go
config.RegisterSection with a dotted nameA child block inside a core block (workspace.goals): strict decoding, same JSON key, still in the schemainternal/core/config/sections.go
conversation.Service.RunBlockThe host context block a run is given; compose sets itinternal/core/conversation/service.go
principal.RegisterEraserDelete a person's data on an erasure request or when retention expiresinternal/core/principal/registry.go
ledger.Traces, ledger.Jobs, ledger.MonitorThe 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 dointernal/core/ledger
configstate.RegisterBundleAdmission, RegisterGeneralOpenerAdmitting 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 ErrNoGeneralOpenerinternal/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.

Sample text · not a command
// 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:

JSON sample · not a command
{ "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

ItemRule
Relative run.programResolved 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 pathA deliberate operator binding, which reduces portability
argv, working directory, environmentTaken 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 envGranted 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.jsonEffectLayer
skills/<name>/SKILL.md, toolsKnowledge and actions for the agent; a skill keeps the name in its frontmatter, with no pack prefixgranted per pack
needsCredentials, env, runtime that tools readgranted by the host through grants.packs
name, keywordsName and keywords for Nest. The pack id is the folder namedisplay only
interface.tool_areas, renderersNest draws a work area for granted tools (browser, canvas)display only, grants no extra tools
interface.piecesHTML pieces placed in Nest's slotsdisplay only
interface.subjectA "who is this person" card for channel conversationsdisplay only
storageThe pack's own tablesprovisioned and scoped by the host
programsPrograms the pack needs installed on the machine (Chromium...)through check_op/install_op
channel.platformsChat platforms a binding can use, with an install formdisplay 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 addWhat to doDoes Nest change
A new core functional area of NestAdd 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 functionThe pack declares interface.pieces with slot rail, home, data.tab or settingsNo. 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 teamsNo. 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 withThe 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 NestA 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 interfaceThe pack declares renderers with a bundle, and Nest frames itNo
An install form for a chat platformThe pack declares channel.platforms[].uiNo
A program install buttonThe pack declares programsNo

Registry rules:

  • The rail, palette, deep links, lazy loading and view permissions are computed from AreaManifest[]; Settings from SettingsSection[]. presence: false means 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. teams are the teams with a Soot that selects the pack. Members see only access: "member" pieces; the invalid list (pieces no Soot can serve) is for operators only.
  • Nest reads GET /v1/pieces on every connection and merges the catalogs into one list in slot order (order, then owner, then id). A piece is piece:<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 by id across connections. The switcher's noun is kind.label, else "Dự án" (Project). When the runtime answers kind: null, an empty list, a 404 or a 405, Nest treats it as no project source: no switcher, and the runtime's project.tab pieces are tabs of the whole workspace. Nest never builds projects from Soot labels or from GET /v1/workspace/summary.
  • A project's tabs are the project.tab pieces (builtin and runtime), grouped by tab.id and named by the first piece. A runtime piece is a tab of a project when one of its teams is 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 in desktop/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).

  • view reads; action writes, needs a request_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} and viewer in 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. An operator piece 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 ActionSpec registry and the read views, plus each piece's view/action tools (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 PersonOnly on 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'tWhyDo 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 configExisting skill + tool (possibly through builtin/toolbox), or a new pack
A registry or distribution layer for adaptersIngress belongs to the platform; if core knows which adapters exist, it becomes the dispatcherAn 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 whatWork reaches a Soot first; jobs and subagents use AgentCore
Making a "case", ticket or worker a mandatory entry pointA case is an optional, passive record that neither blocks events nor triggers agentsA Soot receives the event; the casework pack is only a tool for recording
Its own loop, compactor, reviewer or job managerThere is only one agent runtime, and it belongs to AgentCoreUse AgentCore
An import from contrib/ or a pack in core codeCore must run with no workload presentPacks and project repos hold industry knowledge
Branching on a pack or platform name in core or NestEvery branch is a rebuild for each new packDeclare it in pack.json (name, renderers, platforms)
Industry vocabulary in internal/, contract/, desktop/src/TestCoreIsCSFree blocks it; core serves many kinds of workspaceKeep it in a pack
Nest running work in place of the runtimeNest does not do the runtime's jobFix the target runtime; see runtime.md
Granting permissions from interfacetool_area, pieces and renderers are display onlyThe host grants through grants.packs

Decision guide

Go from the top and stop at the first row that matches.

I want...Put it inNotes
The agent to know one more procedure, policy or toneSkill (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 packA soot/v1 executable, operation name <pack>_<tool>, declare needs
The same skills and tools for many Soots, switched on/off oncePackA pack is the unit of selection and granting
A pack that needs to remember its own dataThe pack's storageDon't open your own DB; no triggers, views or SQL
Receive messages from a new platformAdapter (process), binding in the deploymentSpeaks channel-adapter; the pack only declares channel.platforms
Users need a screen in Nest to view or act on the pack's dataPiece (interface.pieces)data.view_tool reads, data.action_tool writes, all permissions go through the tool
A canvas or live interface for a tool areaThe pack's renderersStreaming/input features follow capabilities, not kind
Run on a schedule, toward a goal, assign workConfig (schedule, task, goal)Belongs to the deployment and workspace.md, not to a pack
Let an outside tool control SootMCP / REST with a scoped token; add an ActionSpec if a new action is neededDon'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/featuresPut the package under internal/feature/; layers.json needs no edit
A new core functional area of NestA new AreaManifest in the registryDon't branch on packs
Change the agent run loop, conversation storage, authentication, the vaultCore changeGo 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.

  1. Reconciliation knowledge (rounding rules, when to count a mismatch): the skill reconcile.md in the pack reconcile.
  2. Reading statements and orders: two tools, fetch_orders and fetch_statements (run.mode: read), declaring needs.credentials for the store's API key. The host grants it with soot grant reconcile.
  3. Recording mismatches: the tool record_mismatch (mode: write) saves into the pack's storage, a table mismatches with columns order_id, delta, status (text columns have search: true).
  4. Viewing in Nest: interface.pieces has a piece with slot: "data.tab", access: "operator", a data.view_tool that reads mismatches, and a data.action_tool that marks a row handled (with request_id). Not one line changes in desktop/.
  5. Running daily: a schedule in deployment.json pointing at the Soot. No new worker.
  6. Telegram alerts: a Telegram binding in the deployment; the pack chat-channels already has the adapter. The reconcile pack does not touch the platform.
  7. Checking: soot check --show; test the tools separately with valid and invalid input; evals in the Soot's evals/.

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/traces remain two tolerated core → feature edges, waiting for conversation to be split.
  • No core → compose or feature → compose edge remains: TestCoreLayering refuses both. core/runtime reaches the trace, job and monitoring stores through the core/ledger interfaces, and core/management reaches bundle admission and the Forge General opener through the core/configstate hooks (scaffold registers them). A build that does not link internal/compose/scaffold refuses 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-area pieces 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 as builtin/README.md); the current config is flat and no longer has capabilities.

Content reviewed: 2026-11-12