pi-roundtable-sandbox 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## Unreleased
+## [Unreleased]
+
+## [0.24.0] - 2026-10-29
+
+The core peer range is now `>=0.24.0 <0.25.0`. Every new option is optional; with none set, behavior, mounts, files on disk, the worker protocol and the public API are as in 0.23.x, and `PiSandboxRuntime` is unchanged.
+
+### Added
+
+- `sandbox({ guilds })`: Discord guild ids whose every channel and thread is a sandbox channel, with no `/roundtable sandbox on`. The claim now answers the router's `owns(channel, space)`; asked without a guild (stop, start fresh, delete, background turns, other plugins) it answers for channels it has seen in a listed guild, a process-local set of at most 20,000 that drops the least recently seen. `/roundtable sandbox off` is refused in a listed guild, `on` says it is already on and `status` names the configuration. Ids are validated as snowflakes at startup. `SANDBOX.channels.owns(channel, guild?)` answers for both sources; `has` keeps meaning "enabled by command". `SandboxChannelStore` takes `{ guilds }` as its third argument and has `configured(guild)`.
+- `sandbox({ workspace: "server" })` (`"channel"` stays the default): every sandbox channel of one guild shares one workspace (memory notes and files), while each channel keeps its own last ten exchanges in a state directory mounted at `/channel`, a third bind mount in this mode only. Turns that share a workspace run one at a time in arrival order; the turn timeout starts when a turn runs, `stop` cancels a waiting turn, `busy()` lists both; at most `maxWaiting` (default 4) turns wait behind the running one in a guild, and one past that is refused as busy. `SandboxRuntime.runTurn` takes an optional fourth argument `{ space }`. On disk (under `workspaceRoot`): `guild-<sha256("guild\0" + surface + ":" + id)>` and `state-<sha256("state\0" + channel)>`; per-channel workspaces keep their names, and switching modes migrates nothing.
+- `sandbox({ files })`: `files_list`, `files_read`, `files_write` and `files_delete` in the sealed worker, inside `files/` of the workspace (relative paths, a symlink at any segment refused, 256 KiB per file and 32 MiB in all by default, both settable). They run in the worker and spend no broker calls.
+- `sandbox({ skills })`: directories of skill folders (`SKILL.md` with `name` and `description` frontmatter). The system prompt ends with a skill index, and the host tool `host_read_skill({ name, path?, offset? })` pages a skill's files from the host; nothing is mounted. Startup stops on a missing directory, bad frontmatter, a duplicate name or a configured host tool named `read_skill`.
+- `sandbox({ budgets: { promptBytes, toolResultBytes, requestBytes } })` (defaults 8,192, 4,096 and 196,608; at most 32,768, 32,768 and 196,608), and `maxCalls` and `maxOutputTokens` settable through `sandbox()`. A prompt (with the skill index) over `promptBytes` stops startup naming both sizes. Host tools get `HostToolContext.resultBytes`, the allowance their result will be cut to net of the broker wrapper; `toolResultTextBytes` and `pageText` fit a page to it. A cut tool result is marked as cut and no longer points at `memory_get`.
+- `modelUrl` may be a cleartext `http://` URL on `127.0.0.1`, `::1` or `localhost` without `allowHttp`; any other cleartext URL still needs it.
+- Importing history: `guildWorkspaceDir`, `channelStateDir`, `channelWorkspaceDir`, `historyFilePath`, `workspaceFilesDir`, `HISTORY_FILE`, `HISTORY_MAX_ENTRIES`, `HISTORY_ENTRY_BYTES`, `encodeHistory` and `userHistoryContent` describe the on-disk layout and the history entries the worker reads.
+
+### Changed
+
+- The worker's request trim never drops the newest tool-call group (the model would call the same tools again until the call limit): when it does not fit, each of its results is cut to a fair share of what is left and marked as cut. Startup stops when `budgets.requestBytes` cannot hold `promptBytes` + 8,192 bytes of memory notes + 49,152 bytes for the current message + 8 KiB of tool-result room, naming every size.
+- `budgets: {}` (or one whose keys are all undefined) no longer demands a protocol-2 image; only a budget with a key set does.
+- With `workspace: "server"` the memory tools and the system line call the shared notes server notes, shared by every channel of the server; the `channel` scope name is unchanged.
+- A turn stopped while it waits for its workspace, or refused because the queue is full, rejects with `SandboxTurnRefused` (exported; `reason` is `"stopped"` or `"busy"`), and the claim answers it without logging an infrastructure failure.
+- The worker image carries the label `pi-roundtable-sandbox.protocol` (2), and the Dockerfile copies the new modules (`history.ts`, `paging.ts`, `files.ts`). **Rebuild the image** when you set `workspace: "server"`, `files`, `skills` or `budgets`: startup reads the label through the container driver (`ContainerDriver.imageProtocol`, optional; `DockerContainerDriver` uses `docker image inspect`) and stops on an older image, so an old worker never writes a channel's history into a shared workspace. The README's "exactly two bind mounts" now describes both modes.
+
+## 0.23.2
+
+- Release in lockstep with pi-roundtable 0.23.2; no package-specific behavior changes. The core peer range stays `>=0.23.0 <0.24.0`.
 
 ## 0.23.1
 

package/README.md

@@ -5,12 +5,13 @@ Source lives in [`packages/sandbox`][source] in the pi-roundtable repository and
 Each addressed message runs a small tool-using agent in a new Docker container with no network and no real credentials.
 A host-side Unix-socket broker is its only way out.
 Channel memory and recent conversation text persist in the channel's dedicated workspace between containers.
+Opt-in options (below) can also sandbox a whole Discord server, share one workspace across its channels, and give the guest file tools, skills and larger budgets.
 
 [source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/sandbox
 
 ## Requirements
 
-- Bun 1.4.4 or later and pi-roundtable `>=0.23.0 <0.24.0`.
+- Bun 1.4.4 or later and pi-roundtable `>=0.24.0 <0.25.0`.
 - A native Linux host with a local Docker daemon and a non-root service account permitted to run Docker.
 - The worker UID/GID match that account; root workers are refused.
 - A trusted OpenAI-compatible, non-streaming Chat Completions endpoint supporting function tools and `max_tokens`.
@@ -83,7 +84,148 @@ These commands are guarded by the published owner-command helper and serialized
 Do not disable sandbox routing in a channel that should remain a guest-only boundary.
 `initialChannels` seeds the first state file only; subsequent starts use its saved state.
 The `SANDBOX` service exposes `channels` and `runtime` for other trusted plugins.
-Threads have separate channel keys and do not inherit a parent channel's sandbox mode; enable each thread explicitly through the trusted channel service if needed.
+Threads have separate channel keys and do not inherit a parent channel's sandbox mode; enable each thread explicitly through the trusted channel service if needed, or sandbox the whole server with `guilds` (below).
+
+## Serving a whole server
+
+Every option in this section is optional.
+With none set, behavior, mounts, files on disk, the worker protocol and the public API are those of 0.23.x.
+Options marked "protocol 2" need a worker image built from this release; see [Worker image protocol](#worker-image-protocol).
+
+| Option | Meaning |
+| --- | --- |
+| `guilds: string[]` | Discord guild ids whose every channel and thread is a sandbox channel, with no `/roundtable sandbox on`. |
+| `workspace: "channel" \| "server"` | `"channel"` (default): one workspace per channel. `"server"` (protocol 2): the channels of one guild share one workspace. |
+| `files: boolean \| { maxFileBytes?, maxTotalBytes? }` | Workspace file tools in the worker (protocol 2). |
+| `skills: string[]` | Directories of skill folders, read through `host_read_skill` (protocol 2). |
+| `budgets: { promptBytes?, toolResultBytes?, requestBytes? }` | Byte limits for the prompt, a tool result and a model request (protocol 2). |
+| `maxCalls`, `maxOutputTokens` | The broker's calls per turn (default 48, at most 1,000) and output tokens per model call (default 4,096, at most 32,768; a thinking model's thinking counts). |
+
+"Bytes" are measured the way the worker measures text: `Buffer.byteLength(JSON.stringify(text))`, so a Traditional Chinese character is 3 bytes and a newline 2.
+
+### `guilds`
+
+The claim answers the router's `owns(channel, space)`: a channel whose guild id (the `space` Discord sets, threads included) is listed is a sandbox channel whatever the state file says, including channels and threads created after start. Nothing is stored for it.
+Answering rules are unchanged: a non-bot, non-integration message that mentions the bot or replies to it, from an author the host's `access` rules serve.
+The admission check and the recheck inside the queued turn both use the message's guild.
+Direct messages and other guilds are not affected; a channel enabled by command in another guild keeps working.
+Ids must be Discord snowflakes (17 to 20 digits); an invalid id stops startup naming `guilds`.
+
+Operations that ask `owns(channel)` without a guild (stop, start fresh, delete, background turns, other plugins) are answered from the channels the claim has been asked about with a listed guild, kept in process: an idempotent set of at most 20,000 channels that drops the least recently seen.
+After a restart nobody owns a configured guild's channel for those questions until its first message; nothing runs there then, so stop has nothing to stop and start fresh answers that there is nothing to reset.
+`SANDBOX.channels.has(channel)` keeps meaning "enabled by command"; `SANDBOX.channels.owns(channel, guild?)` answers for both sources.
+
+In a listed guild `/roundtable sandbox off` is refused ("This server is sandboxed by configuration (`guilds`); change the configuration to turn it off."), `on` answers that it is already on, and `status` says the channel is sandboxed by configuration.
+
+### `workspace: "server"`
+
+Every sandbox channel of one guild, listed in `guilds` or enabled by command, shares one workspace: memory notes (speaker and channel scopes) and workspace files.
+Guilds never share, and a channel whose message carries no guild keeps its own per-channel workspace.
+Conversation history stays per channel: each channel keeps its own last ten exchanges in its own state directory, mounted at `/channel`, so a turn's container sees its guild's workspace and its own channel's state, never another channel's history.
+
+Under `workspaceRoot`, a guild workspace is `guild-<sha256("guild\0" + surface + ":" + id)>`, a channel's state directory is `state-<sha256("state\0" + channel)>`, and today's per-channel workspaces are unchanged (`<sha256(channel)>`).
+Switching from `"channel"` to `"server"` migrates nothing: the old per-channel workspaces stay on disk untouched, and so do their memory and history.
+
+Turns that share a workspace run one at a time, in arrival order, in a queue inside the runtime keyed by workspace.
+The turn timeout starts when a turn begins running, not while it waits; `stop` cancels a waiting turn as well as a running one; `busy()` lists both; the typing indicator shows while a turn waits.
+A second turn for the same channel still cannot start while one is running or waiting.
+At most `maxWaiting` turns (default 4, 0 to 100) wait behind the running one in a guild's queue; one past that is refused as busy and not queued, so one guest mentioning the bot in many channels or threads cannot hold the guild's workspace for N turns of the turn timeout.
+`SandboxRuntime.runTurn(channel, speaker, text, { space })` takes the guild as an optional fourth argument; callers that omit it get the per-channel workspace.
+
+### `files`
+
+`files: true` (256 KiB per file, 32 MiB under `files/`) or `files: { maxFileBytes, maxTotalBytes }` gives the guest four tools in every sandbox channel of this plugin:
+
+- `files_list({ path? })`: files under a directory, recursively, with sizes; at most 500 entries, then a note that more exist.
+- `files_read({ path, offset? })`: text from character `offset`, as much as the tool-result budget allows; when more follows, the first line is `[More: next offset N]`, so a cut never removes it.
+- `files_write({ path, content })`: create or replace a UTF-8 text file; parent directories are created. A write over a limit returns an error and writes nothing.
+- `files_delete({ path })`: delete a file or an empty directory.
+
+Paths are relative, `/`-separated and inside `files/` of the workspace; `..`, absolute paths, empty segments, NUL and a symlink at any segment (checked with `lstat` per segment) are refused. Memory and history are not reachable through them.
+These tools run in the worker and do not spend the broker's per-turn call budget.
+The checks run in the worker, so they bound the tools only: a compromised worker can still write anything into its mount.
+Keep a filesystem quota on `workspaceRoot`.
+
+### `skills`
+
+`skills: ["/srv/bot/skills"]` names directories that each hold skill folders: `<dir>/<name>/SKILL.md` whose frontmatter has `name` equal to the folder name and a `description`.
+The system prompt ends with an index (one sentence telling the model to read a matching skill with `host_read_skill` before answering, then each skill's name and description).
+`host_read_skill({ name, path?, offset? })` returns `SKILL.md`, or the file `path` inside the folder of skill `name`, paged by character offset like `files_read`; to point one skill at another's file, name that skill.
+Paths outside the folder are refused, links that leave it too.
+It runs on the host: skill files are never mounted into a container.
+Startup stops on a missing directory, a folder without valid frontmatter, two skills of one name (both paths are named), or a configured host tool named `read_skill`.
+Host tools reach the model as `host_<name>`, so a skill that names a tool must write `host_roll_dice`, not `roll_dice`.
+
+### `budgets`
+
+| Budget | Default | At most | Meaning |
+| --- | --- | --- | --- |
+| `promptBytes` | 8,192 | 32,768 | `prompt` plus the skill index. Startup stops when they exceed it, naming both sizes; nothing is cut silently. The current time, speaker memory and channel notes keep their own 4,096-byte caps outside it. |
+| `toolResultBytes` | 4,096 | 32,768 | The per-call cap on a tool result, as the worker measures it after encoding. A cut result is marked with a note saying it was cut. |
+| `requestBytes` | 196,608 | 196,608 | The size the worker trims each model request to, dropping the oldest history first and then the oldest complete tool-call groups, but never the newest group: when that does not fit, each of its results is cut to a fair share of what is left (small results stay whole) and marked as cut. Lower it to fit a smaller model context. |
+
+Startup stops when `requestBytes` cannot hold `promptBytes` + 8,192 bytes of memory notes + 49,152 bytes for the largest current message the worker keeps + 8 KiB of tool-result room (the worker allows 8 tool calls per reply, and 1,024 bytes each is the least worth having), naming each size. The tool descriptions, the speaker's history and the assistant's tool calls also count against the request but are not part of the floor, so leave headroom above it; a turn whose fixed parts alone exceed `requestBytes` fails instead of looping. The example below (24,576 / 98,304 / 12,288) passes, and after eight full-size results each is cut to about 8.8 KiB.
+
+Host tools receive the allowance their result text will be cut to as `context.resultBytes`, net of the broker's `{"text":…}` wrapper, so a paging tool can fit its page.
+The text is encoded twice on its way into the model's context, so a newline or a quote costs four bytes; measure a candidate with `toolResultTextBytes(text)`, or let `pageText(text, offset, budget, measure)` cut a page that begins with the `[More: next offset N]` line.
+The broker's 256 KiB body limit, the 256 KiB turn input limit, the 12 model calls per turn and the 8 tools per reply stay.
+Without `budgets` and `skills`, an oversized `prompt` is still cut at 8,192 bytes by the worker, as before.
+
+### A model on the host's loopback
+
+`modelUrl` may use `http://` when its host is `127.0.0.1`, `::1` or `localhost`: the broker runs on the host, so the request never leaves it, and a local gateway needs no TLS.
+Any other cleartext URL still needs `allowHttp`, and credentials in the URL stay refused.
+This applies to `modelUrl` only, not to MCP servers.
+
+### Worker image protocol
+
+The worker image carries the label `pi-roundtable-sandbox.protocol` with the worker protocol version (2 in this release, exported as `SANDBOX_PROTOCOL`).
+At startup the plugin reads it through the container driver (`docker image inspect`; a test driver answers directly).
+With `workspace: "server"`, `files`, `skills` or `budgets` set, an image without version 2 stops startup with a message to rebuild it, so an old worker can never write a channel's history into the shared guild workspace.
+A custom `ContainerDriver` that cannot report the protocol (`imageProtocol?(image)`) stops a startup that needs it.
+Rebuild with the `docker build` command above after upgrading; the Dockerfile copies the new modules.
+
+### A whole-server guest bot
+
+```ts
+import { sandbox } from "pi-roundtable-sandbox";
+
+export const plugins = [sandbox({
+  image: "pi-roundtable-sandbox:local",
+  runRoot: "/run/bot/sandbox",
+  workspaceRoot: "/srv/bot/workspaces",
+  stateFile: "/srv/bot/state/channels.json",
+  model: "operator-selected-model",
+  modelUrl: "http://127.0.0.1:4000/v1/chat/completions",
+  apiKey: () => process.env.MODEL_API_KEY,
+  prompt: "You are the server's helper. Answer in the asker's language.",
+  guilds: ["900000000000000001"],
+  workspace: "server",
+  files: true,
+  skills: ["/srv/bot/skills"],
+  budgets: { promptBytes: 24_576, toolResultBytes: 12_288, requestBytes: 98_304 },
+  maxOutputTokens: 12_288,
+  tools: [/* host tools: the model sees them as host_<name> */],
+})];
+```
+
+Pair it with the host's `access` rules so every member of the guild is served at guest level, and with `agentServer: false` when the host has no agents.
+
+### Importing old chats
+
+A host that writes history before a channel's first turn (for example a one-shot import of old conversations) should not re-derive hashes. The package exports:
+
+| Export | Meaning |
+| --- | --- |
+| `guildWorkspaceDir(workspaceRoot, surface, guild)` | The shared workspace of a guild (`workspace: "server"`). |
+| `channelStateDir(workspaceRoot, channel)` | A channel's own state directory in `"server"` mode; its history lives here. |
+| `channelWorkspaceDir(workspaceRoot, channel)` | A channel's own workspace (`"channel"` mode, and a message with no guild); its history lives here. |
+| `historyFilePath(directory)`, `HISTORY_FILE` | `<directory>/history.json`. |
+| `workspaceFilesDir(workspaceDir)` | `<workspace>/files`, where the file tools keep their files. |
+| `encodeHistory(entries)`, `SandboxHistoryEntry` | The text of a history file for `{ role: "user" \| "assistant", content }` entries; refuses more than `HISTORY_MAX_ENTRIES` (20) entries or content over `HISTORY_ENTRY_BYTES` (8,192) bytes. |
+| `userHistoryContent({ id, name }, message)` | The JSON text a user entry's `content` holds, as new turns write it. |
+
+Write directories with mode `0700` and files with `0600` as the service user, history last, and do it while no turn runs in that channel.
 
 ## Allowed host tools
 
@@ -107,6 +249,7 @@ const tools: HostTool[] = [{
 Pass `tools` to `sandbox()`.
 Host tool and MCP server/tool names must match `[a-z][a-z0-9_]{0,47}`.
 The worker exposes them as `host_clock`, while the broker accepts only `POST /tools/clock`.
+A tool also receives `context.resultBytes`, how large its result text may be (see `budgets`).
 The host binds `context.channel` and `context.speaker` to the current admitted turn; `context.speaker.principalId` is the principal the author was admitted as.
 The callback signal combines the request's deadline/closure and the turn's cancellation, and aborts when either scope ends.
 Body fields cannot change that identity, even if a guest replaces the worker or forges a broker call.
@@ -139,9 +282,10 @@ A container has:
 
 - `--network none`, a read-only root filesystem, all capabilities dropped, and `no-new-privileges`.
 - A non-root UID/GID, 512 MiB RAM with no additional swap, one CPU, 64 PIDs, and a bounded temporary filesystem.
-- Exactly two bind mounts: its channel workspace (writable) and its current-turn broker directory (read-only).
+- Exactly two bind mounts by default: its channel workspace (writable) and its current-turn broker directory (read-only).
+  With `workspace: "server"` there are three: the guild's shared workspace at `/workspace`, the channel's own state directory at `/channel` (writable, history only) and the broker directory; the three host directories must be separate.
   The workspace remains executable; the threat model already assumes arbitrary container code execution and does not rely on `noexec`.
-- No Docker socket, host home, owner workspace, auth file, host environment, host tool registry or other channel's files.
+- No Docker socket, host home, owner workspace, auth file, host environment, host tool registry or other channel's history. With `workspace: "channel"` it sees no other channel's files either; with `"server"` it sees the guild's files and notes, which every channel of that guild shares.
 - Only the public tool descriptions, current message and speaker, system prompt, time zone, and a dummy API key in worker code.
 
 The worker talks to the broker over a read-only Unix-socket mount.
@@ -153,7 +297,7 @@ A short second removal covers the local create/attach race.
 An unresponsive daemon or delayed create request may still leave a stopped orphan; treat daemon failures and host crashes as an operator cleanup condition.
 Containers use `--log-driver none` to avoid unbounded daemon log files and `--pull never` to run only the image the operator already built.
 Channel keys are hashed for workspace names and are not interpreted as paths.
-The channel queue prevents overlapping turns; other channels run independently.
+The channel queue prevents overlapping turns; other channels run independently, except that channels sharing a `"server"` workspace take turns, with at most `maxWaiting` (default 4) waiting behind the running one, so a guest cannot queue a guild behind N × the turn timeout.
 
 The broker accepts only POSTs to `/model`, explicitly listed `/tools/<name>`, and explicitly listed `/mcp/<server>`.
 Queries, extra path segments, unknown routes, hop headers, cookies, proxy headers, forwarded headers, unknown headers and non-dummy caller credentials are refused.
@@ -172,7 +316,10 @@ No broker payloads or credentials are logged.
 The real model/MCP credential exists only on the host and is swapped in immediately before an upstream call.
 This protects the credential value, not the ability to spend it through the allowed model endpoint during a turn.
 A malicious guest can call allowed routes directly and exercise every granted capability.
-Default bounds are 48 broker calls per turn, 256 KiB request bodies, 1 MiB upstream/tool responses, one in-flight broker call, a 60-second upstream deadline, a 120-second turn deadline, and 4,096 output tokens per model request.
+Default bounds are 48 broker calls per turn, 256 KiB request bodies, 1 MiB upstream/tool responses, one in-flight broker call, a 60-second upstream deadline, a 120-second turn deadline, and 4,096 output tokens per model request; `maxCalls`, `maxOutputTokens` and `budgets` change them.
+Larger budgets mean larger requests to your model and more spend per turn, so raise them only as far as the model's context needs.
+A cleartext `modelUrl` on the host's own loopback never leaves the machine; any other cleartext endpoint needs `allowHttp` and exposes the credential on the network.
+The file tools' per-file and total caps bound the tools only; set a filesystem quota on `workspaceRoot`, because code that compromises a worker can write anything into its mounts.
 Each broker listener permits at most 16 connections, a ten-second initial-header deadline and a 60-second request deadline.
 The worker itself stops after 12 model calls and eight tools per response.
 Malformed or unavailable provider tool names are refused through a local placeholder; invalid or duplicate call IDs are normalized together with their paired replies.
@@ -186,14 +333,14 @@ An abrupt host crash can leave an isolated container behind; inspect and remove
 
 `memory_set`, `memory_get`, and `memory_remove` run inside the sandbox and accept a `speaker` or `channel` scope.
 The current speaker selects the speaker namespace; a tool argument cannot select somebody else.
-Channel notes are shared within that workspace; other channels and host agents do not see them.
+Channel notes are shared within that workspace: with `workspace: "server"` that is every sandbox channel of the guild, otherwise one channel; other workspaces and host agents do not see them.
 Entries are persisted as JSON, capped at 256 entries, 2,048 characters per value and 512 KiB total.
 Up to ten settled user/assistant exchanges persist as channel conversation context; raw tool transcripts are not retained.
 History entries are capped at 8 KiB of JSON-encoded text, system-prompt memory previews at 4 KiB per scope, and current user context at 48 KiB.
 Full notes remain in the store and can be retrieved or removed by key with the memory tools.
-Model request context stays below 192 KiB by dropping old text history or complete tool-call groups, not partial tool transcripts.
+Model request context stays below 192 KiB (`budgets.requestBytes`) by dropping old text history or complete tool-call groups, not partial tool transcripts.
 The worker marks truncated text; bounded tool descriptions and tool results cannot grow a later turn past the broker's body limit.
-Treat every channel's history and memory as potentially visible to all guests in that channel.
+Treat every channel's history and memory as potentially visible to all guests in that channel, and with `workspace: "server"` the memory and files as visible to all guests in the guild.
 Speaker namespaces prevent accidental tool cross-talk, not access by code that compromises the shared channel container.
 Never put confidential data in a guest workspace.
 `startFresh` resets history on the next successful turn and preserves memory; a pending reset is process-local and does not survive host restart.
@@ -201,7 +348,7 @@ Turning mode off does not erase workspace files.
 
 The default sealed mode is text-only and uses a minimal Chat Completions agent loop rather than loading a full Pi session inside the container.
 Attachments are not downloaded; the agent is told they are unsupported.
-It does not load skills or extensions and has no shell, schedules, delegation, image tools, personas, or access to the host runtime.
+It loads no Pi skills or extensions (the `skills` option reads plain skill folders on the host, never in the container) and has no shell, schedules, delegation, image tools, personas, or access to the host runtime.
 
 ## Explicit Pi/subscription mode
 

package/examples/roundtable.config.ts

@@ -34,3 +34,35 @@ export const sandboxConfig = {
 		}),
 	],
 } satisfies Pick<RoundtableConfig, "plugins">;
+
+/**
+ * A whole-server guest bot: every channel and thread of one guild is sandboxed and shares one
+ * workspace, with file tools, skills and byte budgets sized to a local model's context.
+ * Build the worker image from this release first; these options need protocol 2.
+ */
+export const guestServerConfig = {
+	plugins: [
+		sandbox({
+			image: "pi-roundtable-sandbox:local",
+			runRoot: "/tmp/roundtable-sandbox-run",
+			workspaceRoot: join(home, ".local/share/roundtable-sandbox/workspaces"),
+			stateFile: join(
+				home,
+				".local/share/roundtable-sandbox/state/channels.json",
+			),
+			model: "operator-selected-model",
+			modelUrl: "http://127.0.0.1:4000/v1/chat/completions",
+			apiKey: () => process.env.MODEL_API_KEY,
+			guilds: ["900000000000000001"],
+			workspace: "server",
+			files: true,
+			skills: [join(home, ".local/share/roundtable-sandbox/skills")],
+			budgets: {
+				promptBytes: 24_576,
+				toolResultBytes: 12_288,
+				requestBytes: 98_304,
+			},
+			maxOutputTokens: 12_288,
+		}),
+	],
+} satisfies Pick<RoundtableConfig, "plugins">;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.23.1",
+	"version": "0.24.0",
 	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -36,7 +36,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
-		"pi-roundtable": ">=0.23.0 <0.24.0",
+		"pi-roundtable": ">=0.24.0 <0.25.0",
 		"typebox": ">=1.3.34 <2"
 	},
 	"peerDependenciesMeta": {
@@ -52,7 +52,7 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.3",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.23.1",
+		"pi-roundtable": "0.24.0",
 		"typebox": "1.3.37",
 		"typescript": "7.0.2"
 	}

package/src/broker.ts

@@ -5,9 +5,11 @@ import { Readable } from "node:stream";
 import type { ChannelKey } from "pi-roundtable";
 import { modelInput } from "./model-input.ts";
 import {
+	BUDGET_DEFAULTS,
 	boundedText,
 	DUMMY_KEY,
 	isRecord,
+	TOOL_RESULT_WRAPPER_BYTES,
 	type ToolSpec,
 	validName,
 } from "./protocol.ts";
@@ -26,11 +28,20 @@ export interface SandboxSpeaker {
 	name: string;
 	principalId: string;
 }
-export interface HostToolContext {
+/** The turn a host tool or a broker serves, as the host fixed it. */
+export interface HostToolScope {
 	channel: ChannelKey;
 	speaker: SandboxSpeaker;
 	signal: AbortSignal;
 }
+export interface HostToolContext extends HostToolScope {
+	/**
+	 * How large the tool's result text may be before the worker cuts it, net of the broker's
+	 * `{"text":…}` wrapper, so a paging tool can fit its page. Measure a candidate with
+	 * `toolResultTextBytes` (newlines and quotes cost four bytes each, not two).
+	 */
+	resultBytes: number;
+}
 /**
  * Who a model call is made for; a credential hook can pick a token per channel, speaker or
  * principal. A `sandbox` plugin turn always carries the principal; a `PiSandboxRuntime` turn
@@ -54,7 +65,9 @@ export interface McpServer {
 	tools: ToolSpec[];
 }
 export interface BrokerOptions {
-	context: HostToolContext;
+	context: HostToolScope;
+	/** The worker's per-result cap (default 4,096); host tools are told what is left of it. */
+	toolResultBytes?: number;
 	model: string;
 	/** Fixed complete URL, not a guest-selected base URL. */
 	modelUrl: string;
@@ -64,7 +77,10 @@ export interface BrokerOptions {
 	) => Promise<string | undefined> | string | undefined;
 	tools?: readonly HostTool[];
 	mcp?: readonly McpServer[];
-	/** Allow cleartext endpoints only for local testing. */
+	/**
+	 * Allow cleartext endpoints, for local testing. A model URL on `127.0.0.1`, `::1` or
+	 * `localhost` is cleartext-capable without it.
+	 */
 	allowHttp?: boolean;
 	fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
 	maxCalls?: number;
@@ -88,7 +104,13 @@ const FORBIDDEN_HEADERS = new Set([
 	"x-forwarded-proto",
 ]);
 
-function checkUrl(raw: string, allowHttp: boolean): void {
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+
+/**
+ * `loopbackHttp` lets the model URL use cleartext when it names the host's own loopback: the
+ * broker runs on the host, so that request never leaves it.
+ */
+function checkUrl(raw: string, allowHttp: boolean, loopbackHttp = false): void {
 	let url: URL;
 	try {
 		url = new URL(raw);
@@ -96,7 +118,13 @@ function checkUrl(raw: string, allowHttp: boolean): void {
 		throw new Error("invalid broker endpoint URL");
 	}
 	if (
-		(!allowHttp && url.protocol !== "https:") ||
+		(!allowHttp &&
+			url.protocol !== "https:" &&
+			!(
+				loopbackHttp &&
+				url.protocol === "http:" &&
+				LOOPBACK_HOSTS.has(url.hostname)
+			)) ||
 		(allowHttp && !["http:", "https:"].includes(url.protocol)) ||
 		url.username ||
 		url.password ||
@@ -114,7 +142,7 @@ export class SandboxBroker {
 	#active = false;
 
 	constructor(options: BrokerOptions) {
-		checkUrl(options.modelUrl, options.allowHttp ?? false);
+		checkUrl(options.modelUrl, options.allowHttp ?? false, true);
 		this.#options = options;
 		this.#remaining = options.maxCalls ?? 48;
 		if (
@@ -206,6 +234,9 @@ export class SandboxBroker {
 				const result = await tool.run(body, {
 					...this.#options.context,
 					signal,
+					resultBytes:
+						(this.#options.toolResultBytes ?? BUDGET_DEFAULTS.toolResultBytes) -
+						TOOL_RESULT_WRAPPER_BYTES,
 				});
 				if (
 					typeof result !== "string" ||

package/src/channel-store.ts

@@ -10,11 +10,35 @@ import {
 import { dirname } from "node:path";
 import type { ChannelKey } from "pi-roundtable";
 
+/** A Discord snowflake, which is what Discord sets as the space of a guild's channels and threads. */
+const GUILD_ID = /^\d{17,20}$/;
+/** Channels the store remembers asking about for a listed guild, least recently seen dropped. */
+const REMEMBERED_CHANNELS = 20_000;
+
+export interface SandboxChannelStoreOptions {
+	/** Discord guild ids whose every channel and thread is a sandbox channel. */
+	guilds?: readonly string[];
+}
+
 /** Host-only routing state. The file is never mounted into a worker. Invalid state fails closed. */
 export class SandboxChannelStore {
 	readonly #path: string;
 	readonly #channels: Set<ChannelKey>;
-	constructor(path: string, initial: readonly ChannelKey[] = []) {
+	readonly #guilds: ReadonlySet<string>;
+	/** In process only: nothing is stored for a configured guild's channel. */
+	readonly #remembered = new Set<ChannelKey>();
+	constructor(
+		path: string,
+		initial: readonly ChannelKey[] = [],
+		options: SandboxChannelStoreOptions = {},
+	) {
+		for (const guild of options.guilds ?? []) {
+			if (typeof guild !== "string" || !GUILD_ID.test(guild))
+				throw new Error(
+					`guilds: ${JSON.stringify(guild)} is not a Discord guild id`,
+				);
+		}
+		this.#guilds = new Set(options.guilds);
 		this.#path = path;
 		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 		const parent = statSync(dirname(path));
@@ -45,9 +69,35 @@ export class SandboxChannelStore {
 		this.#channels = new Set(raw as ChannelKey[]);
 		if (!existsSync(path)) this.#save();
 	}
+	/** Whether the channel was enabled by command; a configured guild's channels are not. */
 	has(channel: ChannelKey): boolean {
 		return this.#channels.has(channel);
 	}
+	/** Whether the guild is listed in the `guilds` option. */
+	configured(guild: string | undefined): boolean {
+		return guild !== undefined && this.#guilds.has(guild);
+	}
+	/**
+	 * Whether the channel is a sandbox channel, enabled by command or in a listed `guild`. A
+	 * channel asked about with a listed guild is remembered, so later questions that carry no
+	 * guild (stop, start fresh) still find it; asking again changes nothing but its recency.
+	 */
+	owns(channel: ChannelKey, guild?: string): boolean {
+		if (this.#channels.has(channel)) return true;
+		if (guild !== undefined) {
+			// Only Discord sets a guild id; another surface's space is not one.
+			if (!channel.startsWith("discord:") || !this.#guilds.has(guild))
+				return false;
+			this.#remembered.delete(channel);
+			this.#remembered.add(channel);
+			if (this.#remembered.size > REMEMBERED_CHANNELS) {
+				const oldest = this.#remembered.values().next().value;
+				if (oldest !== undefined) this.#remembered.delete(oldest);
+			}
+			return true;
+		}
+		return this.#remembered.has(channel);
+	}
 	list(): ChannelKey[] {
 		return [...this.#channels];
 	}

package/src/claim.ts

@@ -6,10 +6,12 @@ import type {
 } from "pi-roundtable";
 import { splitReply } from "pi-roundtable/kit";
 import type { SandboxChannelStore } from "./channel-store.ts";
-import type { SandboxRuntime } from "./runtime.ts";
+import { type SandboxRuntime, SandboxTurnRefused } from "./runtime.ts";
 
 export interface SandboxClaimOptions {
-	channels: Pick<SandboxChannelStore, "has">;
+	/** `owns` adds channels in configured guilds; without it only `has` decides. */
+	channels: Pick<SandboxChannelStore, "has"> &
+		Partial<Pick<SandboxChannelStore, "owns">>;
 	runtime: Pick<SandboxRuntime, "runTurn" | "stop" | "startFresh">;
 	surfaces: Pick<SurfacePort, "sendReply" | "startTyping">;
 	reportFailure?: (channel: ChannelKey) => void;
@@ -26,14 +28,23 @@ export function isSandboxAddress(message: InboundMessage): boolean {
 
 /** Outranks the agent server's priority 100; ignored messages never fall through to host agents. */
 export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
+	const owns = (channel: ChannelKey, space?: string): boolean =>
+		options.channels.owns
+			? options.channels.owns(channel, space)
+			: options.channels.has(channel);
+	// A message names its own guild; one without a space is a sandbox message only when its channel
+	// was enabled by command, never because the channel was remembered from an earlier question.
+	const admits = (message: InboundMessage): boolean =>
+		message.space === undefined
+			? options.channels.has(message.channel)
+			: owns(message.channel, message.space);
 	return {
 		name: "sandbox",
 		priority: 200,
 		postsInPlace: true,
-		owns: (channel) => options.channels.has(channel),
+		owns,
 		admit: (message) => {
-			if (!options.channels.has(message.channel) || !isSandboxAddress(message))
-				return undefined;
+			if (!admits(message) || !isSandboxAddress(message)) return undefined;
 			// The router resolved the author; one the host's access rules serve no one by goes
 			// unanswered, as does a message whose author it could not resolve.
 			const { speaker } = message;
@@ -43,7 +54,7 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 				failure: "sandbox turn failed",
 				run: async () => {
 					// A queued turn rechecks mode, so an off command cannot send it to host tools.
-					if (!options.channels.has(message.channel)) return;
+					if (!admits(message)) return;
 					const stopTyping = options.surfaces.startTyping(message.channel);
 					try {
 						const text = `${message.reference?.text ? `Quoted message (untrusted): ${message.reference.text}\n\n` : ""}${message.text}${message.attachments.length ? "\n[Attachments are not supported in this sandbox.]" : ""}`;
@@ -55,14 +66,17 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 								principalId: speaker.principalId,
 							},
 							text,
+							{ space: message.space },
 						);
 						await options.surfaces.sendReply(message.channel, {
 							chunks: splitReply(
 								reply.ok ? reply.text : "The sandbox turn failed.",
 							),
 						});
-					} catch {
-						options.reportFailure?.(message.channel);
+					} catch (error) {
+						// A stop or a full queue is the runtime working as designed, not a failure.
+						if (!(error instanceof SandboxTurnRefused))
+							options.reportFailure?.(message.channel);
 						await options.surfaces.sendReply(message.channel, {
 							chunks: ["The sandbox turn failed or was stopped."],
 						});

package/src/commands.ts

@@ -11,7 +11,10 @@ import type { SandboxChannelStore } from "./channel-store.ts";
 /** Owner-only /roundtable sandbox on|off|status; mode changes use the same channel queue as turns. */
 export function sandboxCommands(
 	guard: CommandGuard,
-	channels: SandboxChannelStore,
+	channels: Pick<
+		SandboxChannelStore,
+		"configured" | "disable" | "enable" | "has"
+	>,
 	queue: QueuePort,
 ): InteractionContribution {
 	return {
@@ -47,8 +50,21 @@ export function sandboxCommands(
 						"Sandbox commands require a guild channel.",
 					);
 				const channel = `discord:${interaction.channelId}` as const;
+				const configured = channels.configured(
+					interaction.guildId ?? undefined,
+				);
 				await queue.run(channel, async () => {
 					const action = interaction.options.getSubcommand(true);
+					if (configured) {
+						await interaction.editReply(
+							action === "off"
+								? "This server is sandboxed by configuration (`guilds`); change the configuration to turn it off."
+								: action === "on"
+									? "Sandbox routing is already on: this server is sandboxed by configuration (`guilds`)."
+									: "Sandbox routing is enabled: this server is sandboxed by configuration (`guilds`).",
+						);
+						return;
+					}
 					if (action === "on") channels.enable(channel);
 					else if (action === "off") channels.disable(channel);
 					await interaction.editReply(