01 / Surfaces
Surfaces: where people meet Soot
Where founders, members and customers meet Soot, which credential each one uses, and when Soot waits for a person to decide.
A Soot has no interface of its own. People meet it through surfaces: Nest, the CLI, a coding agent (MCP), the SDK and the widget on a website, and chat apps such as Telegram. This document covers who uses which surface, what they see, how a project plugs into Soot, and why every surface follows the same rules. If each place decided for itself "who may answer, who may approve, what the customer sees", permissions would drift apart and data would leak every time a channel is added.
Model: one kernel, one rule set
The runtime is the kernel. It holds conversations, runs, attention items, identity and every "who may do what" decision. A surface does three things: it displays the part of the runtime's state projected for that place, passes back what people decide, and tags each message with the right speaker. It does not derive permissions from the channel type and it does not keep a second copy of the rules.
Owner (operator) Member Customer / visitor
Nest · CLI · MCP Nest · chat DM website · app · public chat
│ │ │
▼ ▼ ▼
┌─ surface: project data, tag the speaker, receive decisions ──────┐
│ Runtime (kernel) │
│ conversation per place · run · attention item · Authorize() │
│ A Soot decides within its permissions; asks a person when needed│
└──────────────────────────────────────────────────────────────────┘Two consequences. A question or an approval request in Nest and in Telegram is the same item with one answer; whoever answers first, the other place shows "handled". And what a Soot can do does not depend on who is talking to it: tools, credentials and the list of tasks waiting for approval live in the Soot and host configuration. A surface only decides who may speak and who may handle an item.
Three groups of people and their credentials
| Group | Who | Credential | What they see |
|---|---|---|---|
| Owner | Founder, the person running the runtime | Operator token (Nest, CLI); scoped sop_ token (coding agent) | Everything on the runtime, every approval request |
| Member | The owner's staff | Member key (a fixed-user key with conversations:read_team, control...), or a linked chat account | Their own work; an approver can also approve work of the Soots they were granted |
| Customer | End user of the project | Trusted backend (conversation_clients) sets X-Soot-User; or spk_ plus visitor svs_ for anonymous people | Only their own conversations, in the public projection |
Each credential type goes through its own gate and none can stand in for another: an operator token never goes down to the browser; a user's key calling an admin route gets 403 (only a token that was never issued or has been revoked gets 401); the backend authenticates the user itself and then sets the identity, and a browser cannot send that header. spk_ is a public key that selects a client policy. It does not prove who is staff or who is a customer, so organization-level privacy has to go through the project's backend. A conversation belongs to tenant/user/Soot; knowing an ID grants nothing in another tenant. An operator connection deliberately does not open into customer tenants: the owner receives items that need handling and does not read customer transcripts. A client config change only takes effect after activate (saved is not active). Declare clients with soot schema deployment; issue and revoke keys with soot auth --help.
Device pairing: to open someone's Nest on another machine, the owner issues a one-time code; the Nest on the other machine exchanges it (/pair, /v1/pair/claim) for its own device key, which can be revoked per machine. The exchange step needs no other credential because the code is the credential. Only the owner issues codes and revokes machines.
Two kinds of channel
Channels for the owner and the team (Nest, CLI, MCP, internal Telegram or Discord) talk to Lead or the coordinator (Đầu mối), receive the items that need the owner, and answer in place according to role. Customer channels (widget, app channel, public bot) talk to the customer-facing Soot that the team attached; an item that needs the owner never carries its content there, and the customer sees only a pointer with no host-written text.
Each chat bot belongs to one team (or one Soot) and answers only with that team. An internal bot lets only linked people talk to it. An external bot lets customers talk, with limits, and is never the owner's chat channel. Lead lives in Nest and belongs to no team, so it is never the target of a bot; a team binding that has no coordinator yet has no target. Attaching a bot does not change the Soot's tools, packs, credentials or role. See places-settings.
The surfaces
| Surface | For | Entry point | Source |
|---|---|---|---|
| Nest | Owner, members | Operator connection, or member connection | desktop/ |
CLI soot | Owner, scripts, CI | Operator token | cmd/soot/ |
| Coding agent (MCP) | Owner, through Claude Code, Codex, Cursor | sop_ token, stdio or /v1/mcp | cmd/soot/mcp.go, internal/feature/mcpserver/ |
| Chat channel (Telegram, Discord) | Owner, members, customers | /v1/channel/* with an sca_ credential | internal/core/channel/, adapter in Soot Forge packs/chat-channels |
| App channel / bridge | The project's backend, customers inside the app: each person's own conversation and shared places many readers see (channel-adapter §12) | SDK @tofound/soot-sdk | contrib/sdk/typescript/src/{channel,livechat} |
| Browser SDK and widget | Visitors on a website | /public/v1/* with spk_, svs_ | contrib/sdk/typescript/src/browser.ts, internal/core/transport/httpapi/public*.go |
A new platform is an adapter that speaks the channel-adapter contract, not a change in core (extensions.md).
Many channels, one rule set
Adding a chat channel adds no rule, because each layer knows one thing:
- The adapter knows the platform's protocol. It translates every message into one shape: who spoke, in which place, whether the Soot was addressed, which message is being answered. It does not decide who may speak, never answers on its own and writes no text for people.
- The runtime knows identity and place. It maps binding, place and speaker to a conversation, decides who may speak, and remembers where that conversation's answers go (Who speaks, where, who handles it).
- The Soot sees only a conversation with messages. It answers; it never picks a channel or a destination.
- The way out runs in reverse: the runtime addresses the answer and the adapter renders it the platform's way (a quoted reply, a pointer to a DM).
Permissions follow who owns the conversation (owner, member, visitor), not the kind of channel, so a new channel reuses the shared rules.
Adapter code runs in three places with three levels of trust, so it ships in three forms. They cannot be one package; what they share is the host's rules and the vocabulary of the two contracts.
| Where the code runs | Form | For | Contract, credential |
|---|---|---|---|
| Beside the runtime, started by the deployment | The soot-channel process in the chat-channels pack (Soot Forge) | Platforms with a public bot API: Telegram, Discord. The operator enters a bot token and writes no code | channel-adapter, sca_ |
| In the project's backend | A library: SDK channel | The project's own chat. Only the project's backend knows who the signed-in user is, and the messages live in its store | channel-adapter (remote binding), binding key |
| In the visitor's browser | The widget, or SDK browser | Visitors on a website. A browser cannot hold a server secret | live-chat-attention, /public/v1/*, spk_ and svs_ |
SDK live-chat is a second form for a project that already has its own chat system: a durable inbox/outbox bridge that runs in the project's backend.
First path
There are three ways to start, all on the same runtime. Individual: install the Nest app (which bundles the runtime) or run soot nest, pick an AI provider, chat with Lead. Terminal: soot spawn <dir> creates a workspace and starts the runtime, soot check --show shows the resolved permissions, soot run "..." hands over a task. Project: soot spawn --project <dir> writes a scaffold (a support Soot, empty tool permissions, offline scripted AI, docs/soot.md for coding agents), then soot serve, add a connection in Nest, and the backend calls it with the SDK.
The scripted model only tests behavior locally; only a real chat turn proves the AI is ready (/readyz and soot check do not). Provider keys live in the host's vault; Soot does not read .env.
Nest
Nest is a Tauri app (with a build that runs in the browser) written in React. All decisions live in the runtime; Nest projects state and sends answers back.
Page structure
The rail is a list of modules in a registry (desktop/src/app/registry/areas.ts). The rail, the ⌘K command palette, nest:// links and shortcuts are all generated from that same array, so adding a page means adding one line (nest-registry).
| Area | Its job |
|---|---|
| Hộp việc (Work inbox) | A wide window (over 760 px) always has the work list on the left (one nav): the Lead row first, then three fixed groups, Cần bạn ("Needs you"), Đang chạy ("Running") and Xong ("Done"), and the button that composes new work. Each piece of work is one row and one thread; opening a row opens its thread on the right, including the card of work that needs you. With no row chosen, the right side is the start view: the "Gửi tới" ("Send to") box (Lead by default; @team or @Soot sends directly), the "Bước tiếp" ("Next step") card for the first work that needs you, counts you can click, and the home pieces; no row is drawn twice. A narrow window (760 px or less) shows one pane at a time with a back button, and its start view carries the three groups itself. Each group is bounded, then "Xem cả N …" ("See all N …"); work nobody will run is one Cần bạn row, "N việc chưa có ai làm" ("N pieces of work nobody is doing"); a group keeps its grey skeleton until every read has answered. home pieces sit under the three groups; project.tab pieces are tabs of the project being viewed (goals and work, support…). It replaces Tổng quan (Overview) and Cuộc trò chuyện (Conversations); the old words and old links open Hộp việc |
| Đội Soot, Sản phẩm (Soot teams, Projects) | Each team's Soots, groups, permissions and channels; Soots grouped by project |
| Dữ liệu (Data) | Tables, memory, files, documents (data.md) |
| Kết quả (Results) | Finished tasks, cost, self-improvement (evolution.md) |
| Trang của Soot (Soot pages) | Pages declared by a pack and served by the runtime (pieces) |
| Cài đặt (Settings) | General, Server, Members (including who may approve), Screens, Kho khóa (the vault: every key in one place), AI, Permissions (which tools wait for approval), Channels (chat bots, website, SDK and the coding agent connection), Browser, Public knowledge, Updates |
Nest reveals itself gradually: the "Quản lý" ("Manage") group appears only when there are at least two Soots, a data page, or the owner turns it on; when hidden it can still be opened with ⌘K and links. A new user sees one main path: talk to Lead. Familiar jobs for a non-technical manager: see what the team does and approve at Hộp việc › Cần bạn ("Needs you"); hand over work in the "Gửi tới" box of Hộp việc; create a Soot, form a team, set a schedule by messaging Lead; take hard customers through the handoff items; put chat on a website at Đội Soot › team › Kênh (Channels).
Lead and coordinator
Lead is the owner's assistant in Nest. Each server has one Lead, always named "Lead", outside every team. Only Lead has the admin tool (nest-lead_manage): create a Soot, form a team, set a schedule, change the model, grant data permissions. Its actions go through the same management actions as the manual screens, with the same revisions and receipts, so there is no second copy of configuration in a prompt. For reversible work Lead acts right away and reports with a link; deleting, widening permissions and raising budgets go to Cần bạn. Lead never says "created" before there is a receipt. The manual screens remain as the fallback path.
Each team has a coordinator (Đầu mối): the Soot that takes the team's first task, runs the team's schedules and answers the team's bot. The coordinator has no admin permissions. See agents.md and contracts/lead.md.
Several runtimes in one Nest
One Nest can connect to several runtimes (local machine, server, VM). Soots, teams and tasks are merged across all connections; the notion of a server shows up only when two Soots have the same name or when the owner filters by machine in the window bar. Each connection has its own operator key and identity.
Nest trusts each server separately (Settings › Server). GET /v1/runtime returns a durable runtime_id; when the identity changes, Nest drops the session and clears the cache. In the packaged build the operator key sits in the app's own store; in the browser build it lives only in page memory, never in a URL or web storage. A browser calling a server directly needs HTTPS and browser_origins (soot schema deployment). Reads that one screen asks for at the same time share one GET /v1/reads (each read still passes the key's own permissions; work-reads §4), so a first connection to a remote server costs two round trips: GET /v1/runtime, then one batch.
Disconnecting only stops observing; it does not stop or undo work on the server.
Settings: save, apply, try
Configuration belongs to the server running the runtime, not to Nest. Nest shows the saved version and the running version separately because they can differ.
Four steps: validate (only asks the host; saves nothing, calls no model), save (one revision), apply (the host switches to that revision, possibly waiting for running work; only the "Đã áp dụng" ("Applied") label confirms the running version) and try (one real chat turn, only when the saved version equals the running version).
Writes carry expected_revision and a stable request_id. A conflict (409) keeps the draft so the person can read the new version and send again. If a response is lost, Nest asks for the receipt with a GET and does not repeat the POST. Secrets are entered only in Nest or in the CLI on the host, never pasted into chat because conversations are recorded; when needed, Lead opens a safe form.
Cần bạn ("Needs you"): where people decide
The owner's attention is the scarcest resource. A Soot decides everything within its authority and looks for a person only when: the host chose to block the action (money, public posting, deletion); only a person can do it (logging in, plugging in a credential); it is outside its authority (price, date, promise); or nobody knows what happened (a write timed out). "Wants a second opinion" is not a reason. Each ask is one decision: a line saying what is needed and why, the options with the Soot's recommendation, what the Soot has already done, and a link to the object. The person picks a button or writes one line.
Nest has exactly one place for this, Hộp việc › Cần bạn: one list and one count shared by the rail badge and the window title. Each item carries one of three verbs: Answer (question, handoff), Review (decision, grant, an item that a need view draws as a screen or a layout the Soot proposes), Fix (error).
Item (kind) | How it arises | The person answers with |
|---|---|---|
Approval (approval) | A Soot calls a tool the host blocks | Approve and run, or Reject with a reason the Soot can read |
Decision (decision) | report_blocker with options | Pick a button, or write one line of guidance. If if_unanswered allows silence, the default is chosen, only for reversible options |
Handoff (handoff) | report_blocker without options | Do it themselves, then press "Đã xử lý" ("Handled") |
Grant (grant) | A Soot asks for a data store or a pack it does not have | Grant and continue, or Reject |
Contract line grant (need, id contract-grant:<id>, action contract.grant) | A Soot of team A is refused when it reads a table or writes a queue of team B, then asks with report_blocker grant kind contract; every request for the same line is one item | Grant and continue, or Reject with a reason (POST /v1/settings/contract-grants/{id}, soot teams grant / decline; workspace.md) |
Question (question) | ask in an interactive conversation | Answer |
Unknown outcome (unknown_outcome) | A write whose success or failure is unknown | Check the target, then settle it |
| Error, schedule, missing credential, token budget, improvement proposal, outdated knowledge | The runtime detects it | Fix the cause, rerun, skip, apply or discard |
Card (card) | A schedule step returns raise, costs no model | Pick a button. id is set only once, so the tool restates the card each tick without keeping state |
Work sent in a loop (mail_loop) | Work passed back and forth between teams more than mail.max_hops times | Start it by hand, or discard |
Work sent but not running (mail_held) | Work sent to a team with no coordinator (team_needs_coordinator), a team that takes only approved work (inbox_hold), a start that failed (start_failed), or a sending team that has used its daily count (mail_rate_limited); payload.code gives the reason | Pick a coordinator right in Hộp việc (the work then runs by itself), or start it by hand |
Work not delivered (mail_undelivered) | Work sent to a team on another runtime has not arrived after 30 minutes, or was refused outright (mail_not_granted, mail_unsupported, ...) | Retry now (POST /v1/workspace/mail/sync), or fix the permission on the other runtime |
Work waiting on you (task_waiting, id task-waiting:<task>) | An open task is blocked, waits for approval, is your own, or its last run stopped for a person or an error (payload.state: waiting, blocked, failed); there is no such item when another item already stands for the same task (a task thread need, a mail card, a schedule card) | Open the thread and answer, unblock it or run it again |
Work with no one on it (tasks_unowned, id tasks-unowned[:<project>]) | A todo task nobody was assigned or nobody pressed Start on, not a mail; one item per project, with payload.count and up to 20 sample tasks (payload.sample), the rest read through the task list | Assign it to a team or a Soot and start it, or close it |
A customer waits for your reply (live_chat_handoff, id live-chat:<session>:<turn>) | A Soot hands a customer chat (app, website, channel) to a person with report_blocker without options; the item belongs to the customer's tenant (live-chat-attention) | Reply to the customer right in Cần bạn, then give the chat back to the Soot (POST /v1/sessions/{id}/member-messages, /control; owner only, not through a scoped token) |
Each item has a severity (error, warning, info); group by that level, not by kind. Work created by evals is left out of the list unless asked for. List: soot attention list; answer: soot attention answer. The count is the number of items the runtime returns: Nest adds nothing from the task list, so the rail badge, the window title, the head of the Cần bạn group and soot attention list all show the same number.
Sending work to a team (workspace.md) is soot tasks send --to team:<id> "…" or POST /v1/workspace/tasks with deliver: true; Lead sends with send in the workspace tool. The task has a mail field (route, state, reply); the milestones are the events mail_delivered, mail_held, mail_reply. In Nest, the "Gửi tới" box of Hộp việc sends work by this same route; sending to Lead is still a conversation (mail_for_lead). Sent work is a row in Đang chạy even before it arrives; a refusal code becomes one sentence and a fix button (retarget, reconnect, coordinator, budget, start, sync).
A pack declares "approval": "operator" by default for a tool, which is safe for an unknown host. The host owns the real decision through grants.approvals in the deployment, which overrides the pack in both directions; only the host's own deployment can loosen it. Nest shows every blocked tool in Settings › Permissions with 30 days of decisions, and suggests "Để Soot tự chạy" ("Let Soot run it") for a tool that was approved many times and never rejected: autonomy grows with what the owner has shown they accept. Operating-system notifications follow the same list: approvals and unknown outcomes notify immediately, other items notify once or are batched.
The same items reach the owner's linked DM in Telegram or Discord, with buttons for the options so they can be answered in place; for anything the buttons cannot resolve there is a link back to Nest.
Shared rules for every surface
These rules live in code (internal/core/authz, internal/core/channel, internal/core/conversation/attention.go) and the contracts check them with fixtures.
| Rule | Content |
|---|---|
| One item, one answer | Once resolved anywhere, every other place sees it as handled |
| Ask where the work arises | Only question (and decision for a linked asker) appears in a shared place |
| Closed list | Other item types reach only the owner's places; a new type by default requires the own permission |
| Only the asker answers | Anyone else, including the owner, gets 403 not_asker |
| Pointer, not content | An owner-only item meeting a customer or a shared place leaves at most one fixed line |
| Privacy | Secrets stay in Nest. Shared places and live chat receive the public projection. Per-person data is looked up from the conversation's place, not from words in a message |
| Who writes the text | The host writes the sentences for Nest and chat users. For customers the runtime sends only a code; the client writes the text |
| The Soot is the permission boundary | Tools, credential scope, approval config and grants decide what a run can do, the same on every surface |
| Anyone may speak | Linking is not a gate; abuse is handled with limits and a blocklist |
Who speaks, where, who handles it
Every message comes from a speaker (speaker) with a stable id that does not expose the platform handle. A conversation is keyed by place, not by person: a DM, a group or thread, a bridge thread, a widget session. Everyone in the place sees the Soot's replies, so the transcript is shared and labeled with the speaker. While a run is in progress, a new message from the same speaker is absorbed into that run (steering the run); a message from someone else is queued as its own run. An open question belongs to the asker: a message from someone else does not answer it and does not close it. This rule is in internal/core/conversation/steer.go, so the host chat, the bridge and the widget behave the same.
Linking replaces pairing: anyone in a shared place can talk to the Soot without doing anything first. Linking (a one-time code from Nest, sent to the bot) only says "this chat account is that Nest person", so their DM receives owner items and their button presses carry the right role. People who have not linked are limited per person and per binding pool (pool 0 means only linked people may speak), plus a blocklist; past the limit they get one notice and then silence. Default numbers: internal/core/channel/places.go, internal/core/config/channels.go.
One function, Authorize(principal, place, action, item) (internal/core/authz/authorize.go), answers for every surface. It runs again on every press and does not cache roles.
| Role | Who | Scope |
|---|---|---|
owner | Operator connection, the owner's chat account | Everything |
approver | A member the owner granted (all Soots or some) | handle and approve for the granted Soots |
member | A key with read_team and control | handle handoffs of the Soots in the key |
anyone | Unlinked people, customers, visitors | Speak only, and answer their own question |
handle is the team's work (handoffs, decisions, taking over live chat). approve is approving tools and settling unknown outcomes. own is everything else of the owner's: grants, budgets, channels, roles. A member's permissions are never wider than their key.
| Place | Owner-only items |
|---|---|
| Nest | Yes, by role |
| DM of a linked person | Yes, if the role can handle it |
owner_chat (a chat group the owner designates with the /owner code) | Yes, in place of the owner's DM. Everyone sees the title and options; secrets and diffs stay in Nest. Anyone without enough permission who presses gets 403 not_authorized |
| Shared place, live chat | Never; at most a pointer |
Projects plug into Soot (SDK)
A project uses @tofound/soot-sdk (contrib/sdk/typescript/; usage is in its README) to plug into the same runtime. The main paths:
| Want | Use | Credential |
|---|---|---|
| A backend chats with a Soot on behalf of a logged-in user | Conversation API, SDK client | conversation_clients |
| An outside system reports work (alert, webhook) | POST /v1/events through your adapter | operator token, backend only |
| Hand over a background task and receive a structured result | /v1/jobs, SDK jobs, soot jobs | operator or sop_ with scope jobs |
| A drive-by visitor chats on a website | Widget or SDK browser | spk_ and svs_ |
| The app's own chat is the interface | SDK channel or live-chat | binding key |
| A Soot tool calls your API and needs to know who is speaking | Principal token | the host's JWKS |
Concepts to know:
- Run. Sending a message creates a run that is
queued, thenrunning, thencompleted,failedorstopped;waiting_inputmeans the Soot asked the user again and has stopped executing, and the answer is a new message. When a POST loses its response, keep the conversation ID, request ID and run ID and reconcile with a GET; resending as a new run would skip the unknown state. Run errors have stable codes and do not expose the provider's raw error. - Event.
(soot, source, subject)identifies the conversation;idis the retry key. Core has no receiver per vendor: your adapter authenticates the webhook and then normalizes it. A 202 response means durably received, not finished. Core has no case or takeover for events; that belongs to packs.textis at most 64 KiB of UTF-8 and the Soot reads it whole; a longer one is refused with 400 naming the limit. - Job. One background run of a Soot or team, with an
idempotency_key, a JSON result and a JWS-signed callback (verify with the host's JWKS). A job is only an entry point; internal tracking belongs to workspace.md. Contract: jobs. The model readstask,inputandoutput_schemawhole, inline in the run (at most 60 KiB of run text); more is refused withinvalid_jobnaming the limit, never cut. - Public web. A customer chats right on the website without going through your backend:
spk_plus a challenge exchanged for a short-livedsvs_session. Because the key is public, the customer is bound by the client's budget and policy, and the Soots exposed may use read tools only. The widget (source in Soot Forgepacks/live-chat/widget/, served by the runtime at/public/widget/*) keeps credentials out of the host page in an iframe; adopters who want their own UI use the SDKbrowser, same model. - App channel. The SDK
channelis the server-mode adapter of channel-adapter: the host keeps message merging, turns and owner, the SDK does not reply by itself, and it acks only after writing to your store. The SDKlive-chatis a durable inbox/outbox bridge: a send failure becomesuncertainand is never resent automatically. - Principal token. A short-lived JWS for each tool call, so your API knows the person in the conversation, whom the model neither chooses nor sees: principal-token.
Live chat and customers
A customer can answer only their own questions. A question shows as a card with buttons, shows once, and closes with the chosen result. Work that needs the owner (approval, handoff, decision) does not reach the customer; the customer receives a pointer that is just a code (team, approval, not_ready, unavailable) and the client writes the text, or shows nothing if the Soot already replied on its own. The runtime does not write text for customers.
Design decisions worth remembering: this is a sibling contract of channel-adapter (same item vocabulary, two different trust boundaries, because a customer is not a Nest user); the asker's permission is enforced by the runtime, not by the client; and the widget has no rules of its own, every attention state lives in the SDK browser, so changing a rule only needs a runtime upgrade.
When a real person is needed, a member with read_team and control sees the live-chat conversation in Nest, takes over, replies publicly under their own name, or messages the Soot privately (the customer does not see it). While a person holds the conversation, new customer messages are still stored and shown to the member, and the Soot does not run on its own.
Current status: the runtime already projects question cards, results and pointers (internal/core/conversation/attention.go, event attention.pointer, capability live-chat-attention-v1). The live-chat-attention and places-settings contracts have moved to the soot-cs-engine project (internal/test/guard/cs_allowlist.txt keeps a copy here until removal); do not edit the copy. Customer care (console, handoff policy) is an extension, not part of core: extensions.md. The old cs/ bridge has been deleted; production projects use the SDK's app channel.
CLI and coding agent
soot is the surface for scripts, CI and people who prefer a terminal; every admin operation is the same management action as in Nest. soot --help lists commands.
The owner also controls Soot from Claude Code, Codex or Cursor. soot mcp (stdio, local machine) or <server>/v1/mcp (HTTP, remote server) generates tools from the same action registry as the CLI. A scoped sop_ token (read, jobs, manage, data) is created in Settings › Channels › Coding agent connection or with soot tokens, is shown only once, and is its own credential (SOOT_MCP_TOKEN), not an operator token. People keep the decisions: approving, granting permissions, releasing a held item and creating or revoking tokens are not in MCP and are rejected with a scoped token (approval_needs_person). Your coding agent cannot give the support Soot permission to edit files or run a shell on its own. Contract: mcp-operator.
Sent work across surfaces
Who may hand work to a team depends on who owns the conversation, not on the kind of channel. A conversation in the owner's workspace (tenant operator and not a live chat) gives the Soot a writable task tool and send. That is a chat in Nest, the owner's DM with a paired bot on Telegram or Discord, and the owner's chat through a coding agent. Read-only runs cannot send: evals, dry runs and the Lead's brief. Customers, members and apps connected through the SDK never send work into the owner's workspace. All three places read one function, conversation.InOwnerWorkspace (internal/core/conversation/reach.go).
Work a Soot sends from the owner's chat is the Soot's mail, not the person's. So every limit still applies: the hops in a chain, the daily bound, a team that holds its inbox.
The reply comes back where the person asked. When a Soot sends or starts work from a chat outside Nest (a paired DM), once the team replies the Soot gets one more turn in that chat to tell the person, as when the Soot chose wait itself. Each reply wakes it once. This does not apply while the Soot works for a teammate, and a needs_person reply does not wake it. Function: conversation.AnswersOutsideNest.
While it waits, a person on any surface is not left blind. When the work stops to wait for someone in the chain (even on another server), when it passes due, or when it runs long (reported less and less often), the host hands the sender's side one line. A customer's chat that came through an intake gets one turn to tell the customer where the work is. A Soot that sent with wait gets one turn in that thread. Nest reads it from the task log (mail_progress). The line says only where the work is; it does not reveal the team or the person. The shared rule is in work-mail D6.
A coding agent has the same single door for sending work: the MCP tool task_send (same scope as task_start) calls the same send that POST /v1/workspace/tasks with deliver: true and soot tasks send call. The sender is recorded as mcp:<token>.
With a member key, Hộp việc is the conversations that key opened (GET /v1/workspace/inbox). A member sees no task, nothing of the owner's work, another member's or a customer's, also through GET /v1/reads. "Gửi tới" lists only the Soots and teams the key may talk to, and a send opens a conversation with that Soot. Every other /v1/workspace/* route stays the owner's; a member's POST /v1/workspace/tasks gets 403.
From a customer to work is a person's step. A customer's hand-off card in Cần bạn has a "Giao cho đội" button. It opens Hộp việc's composer filled with the Soot's summary of what it needs (a general title when it left none) and one line saying the work comes from a customer chat, with where the customer wrote. Nest copies none of the customer's messages, not even their first one, and carries no conversation id. The owner reads it, picks "Gửi tới" and sends; the card stays in Cần bạn.
The owner can also open a door ahead of time for one kind of report: an intake (contract intake). In the deployment, the owner declares the report's fields, which Soot takes reports and which team on this runtime handles them. That Soot gets one more tool, file_report. It is not send: a customer still cannot send work, only go through the door the owner opened, to the team the owner chose. The mail to the team carries content only: the fields, the Soot's summary, the reporter's own words if any, and how many people reported it. The runtime keeps where to answer each reporter with the work, not in the mail. The receiving team never learns where a report came from: no conversation id, no name, no channel. A report of the same subject joins the open work. When the work is done, failed or blocked, the runtime wakes the Soot that took the reports inside each conversation that reported, one turn per conversation. Who gets answered where: Who speaks, where, who handles it; what the runtime, adapters and packs each own: Boundaries: who owns what.
When you add a new surface:
- Which tenant do its conversations belong to? Only the owner is
operator; everyone else is in their own tenant. - Add no rule by
Source.Kind: sending work readsInOwnerWorkspace, the reply in the chat readsAnswersOutsideNest. - Every door that sends work calls the engine's send (
SendTask,StartTask); write no second send path. - Add rows for the surface to
TestOpSendOnlyInWorkspaceRuns, and a read test with a key that is not the owner's.
Boundaries: who owns what
The runtime (core) holds permissions, identity, choice of where to send, and limits. An adapter (Soot Forge, or one you write with the SDK channel) holds the platform protocol, message format and dedup. A client (widget, SDK, the project's app) writes the text for customers. A pack (extension) holds customer-care behavior and handoff policy. Host and Soot config decide which tools wait for approval and which credential touches which tool. Nest only displays, drafts and keeps unsaved changes.
Things surfaces deliberately do not do: decide who may answer; derive permissions from the channel type; keep a second configuration in the UI or a prompt; pass secrets through chat; open an operator connection into customer transcripts.
Not yet available
Messenger, Zalo and email adapters. Lead exists only in Nest and is not a bot target. Approving with a button in a shared place is deliberately not built.
Content reviewed: 2026-11-12