pi-roundtable-sandbox 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.7.0
+
+- Move into the pi-roundtable monorepo at `packages/sandbox`, preserving Git history.
+- Align the version, core development dependency, and peer range with core 0.7.0 (`>=0.7.0 <0.8.0`).
+- Use the shared checks and lockstep publication workflow; the Docker integration remains opt-in locally and runs explicitly in Linux CI.
+
+## 0.1.0
+
+- Add sealed text-only guest channels for pi-roundtable 0.6.1 using Docker on Linux.
+- Add a per-turn Unix broker with fixed model forwarding, host-only credential swapping, tool and MCP allow-lists, and bounded requests.
+- Add persistent channel and speaker memory inside each isolated workspace.
+- Add owner-only sandbox on, off, and status commands using the shared channel queue.
+- Ship the minimal worker image, setup example, threat model, offline tests, optional Docker integration test, and CI/publish workflows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-roundtable-sandbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# pi-roundtable-sandbox
+
+Sealed guest channels for pi-roundtable 0.7.
+Source lives in [`packages/sandbox`][source] in the pi-roundtable repository and releases in lockstep with the core.
+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.
+
+[source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/sandbox
+
+## Requirements
+
+- Bun 1.4.2 or later and pi-roundtable `>=0.7.0 <0.8.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`.
+- A host-side API credential for that endpoint.
+  A subscription-specific login is not necessarily compatible with Chat Completions.
+
+macOS supports offline development, tests, and building the image.
+Actual sandbox execution requires Linux: Docker Desktop does not share host Unix sockets into its Linux VM.
+Remote Docker daemons are unsupported because bind paths and Unix sockets must exist on the same host.
+
+## Setup
+
+Install the package alongside pi-roundtable after it is published:
+
+```sh
+bun add pi-roundtable-sandbox
+```
+
+Build the image from the installed package, or from this repository during development:
+
+```sh
+docker build -f node_modules/pi-roundtable-sandbox/worker/Dockerfile -t pi-roundtable-sandbox:local node_modules/pi-roundtable-sandbox
+```
+
+Add the plugin to `roundtable.config.ts`:
+
+```ts
+import { join } from "node:path";
+import { sandbox } from "pi-roundtable-sandbox";
+
+const home = process.env.HOME;
+if (!home) throw new Error("HOME is required");
+
+// Merge with the rest of the configuration generated by pi-roundtable init.
+export const guestPlugins = [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"),
+  provider: "openai",
+  model: "operator-selected-model",
+  modelUrl: "https://api.openai.com/v1/chat/completions",
+})];
+```
+
+Choose a model available to your endpoint and sign the host into its provider.
+By default, `context.apiKey(provider)` is read on every request, allowing login refresh without copying credentials into the worker.
+Alternatively supply `apiKey: () => process.env.MODEL_API_KEY` when the endpoint uses a separate key.
+Keep secrets in the service's protected environment, not configuration source or the worker image.
+All directories must be dedicated to this package and owned by the service account.
+Existing roots and the state directory must have no group/other permissions; insecure permissions are refused at startup.
+The `uid` and `gid` options may make deployment settings explicit but must match the host process.
+Keep `runRoot` short enough for a Unix socket path (at most 100 characters including the per-turn suffix).
+Keep `stateFile` outside both roots; it is host-only routing state.
+Keep the roots outside Docker's daemon data directory; Docker rejects private propagation for bind sources inside that directory.
+Back up that state and the workspaces together, without following workspace symlinks.
+Only one host process may own these directories.
+
+Restart the bot, then run `/roundtable sandbox on` in a guild channel as the owner.
+The command root follows your `discord.rootCommand` setting.
+The claim outranks the core agent-server claim (priority 200 versus 100), including when the owner speaks there.
+It answers non-bot, non-integration guild messages that mention the bot or reply to it.
+Other messages are dropped, never routed to a host agent.
+`/roundtable sandbox status` shows the mode; `/roundtable sandbox off` retains memory and restores normal routing after queued work completes.
+These commands are guarded by the published owner-command helper and serialized through the shared channel queue.
+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.
+
+## Allowed host tools
+
+No host tool is enabled by default.
+Supply only capabilities you intend every guest in every configured sandbox channel to use:
+
+```ts
+import type { HostTool } from "pi-roundtable-sandbox";
+
+const tools: HostTool[] = [{
+  name: "clock",
+  description: "Read the current UTC time",
+  parameters: { type: "object", properties: {}, additionalProperties: false },
+  run: (_input, context) => {
+    context.signal.throwIfAborted();
+    return new Date().toISOString();
+  },
+}];
+```
+
+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`.
+The host binds `context.channel` and `context.speaker` to the current admitted turn.
+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.
+Callbacks must validate every input field, enforce their own authorization and rate limits, obey cancellation, and avoid returning secrets.
+Parameter schemas are model guidance, not a host-side validator.
+Do not expose shell execution, arbitrary file paths, arbitrary URLs, owner memory, or a generic tool dispatcher.
+All configured tools are available to all sandbox channels; use a context-aware callback when policies differ.
+
+## Optional MCP tools
+
+Supply `mcp: [{ name, url, apiKey, tools }]` to allow specific tools of specific servers.
+Each tool declares `name`, `description` and a JSON-schema `parameters` object.
+The worker exposes names such as `mcp_0_search` and sends calls through `POST /mcp/<server>`.
+Only single `tools/call` requests naming a declared tool are accepted.
+Unknown servers, tools, RPC batches, resources, prompts, discovery and arbitrary RPC methods are refused.
+The endpoint is operator-configured and never sent to the container.
+`apiKey` is optional for unauthenticated servers and otherwise read on each call; the broker inserts a bearer credential.
+This minimal adapter supports stateless Streamable HTTP endpoints returning JSON directly.
+It does not perform initialization/session negotiation, accept SSE, or provide a raw general-purpose MCP proxy.
+Choose narrow server tools, and apply server-side authorization as well.
+
+## Threat model
+
+Treat guest prompts, model outputs and everything in a container as untrusted, including a worker compromised into arbitrary code execution.
+The operator, Docker daemon, Linux kernel, built image, host callbacks and upstream model/MCP services are trusted.
+Docker is a process-isolation boundary, not a VM or a guarantee against kernel vulnerabilities.
+Use a patched host and a dedicated machine for higher-risk workloads.
+
+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).
+  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.
+- 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.
+The host reads its final reply from Docker stdout, never from a guest-writable socket or file path.
+A new container and broker are created per turn and never reused across channels.
+On cancellation, the run CLI is killed with SIGKILL and the exact named container is force-removed; each removal command has a five-second deadline.
+Cleanup failures end the turn with an error and a generic host log requiring operator inspection, rather than hanging a channel queue.
+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 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.
+Request headers are rebuilt rather than forwarded.
+The model route fixes the complete upstream URL, model, non-streaming mode and output-token limit; the guest cannot select another endpoint or increase that limit.
+It accepts only system/user/assistant/tool roles with string content and function tool calls.
+Media URLs, account file references, audio payloads and native provider tools are refused.
+Schema keywords `$ref`, `$dynamicRef`, `$recursiveRef`, `$id`, `$schema` and `$vocabulary` accept only local fragments, not remote URLs.
+Checks visit actual schema positions, not property names or enum/const data.
+Upstream redirects are refused and no upstream response headers or cookies reach the guest.
+Only bounded JSON responses are accepted; obvious raw, URL-encoded, base64, base64url and hex credential reflections are refused after JSON decoding.
+This is defense in depth for trusted upstreams, not a detector for every possible encoding or secret fragment.
+Errors are generic and never include upstream URLs, headers or exception text.
+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.
+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.
+Tune container resources with `limits: { memoryMb, cpus, pids }` and the turn deadline with `turnTimeoutMs` (1 to 600 seconds).
+These are not billing quotas, global concurrency limits or disk quotas.
+Apply provider spend limits, ingress rate limits, a per-workspace filesystem quota, and host capacity controls before exposing a busy public channel.
+Host callbacks that ignore cancellation cannot be forcibly undone; write them to honor `context.signal`.
+An abrupt host crash can leave an isolated container behind; inspect and remove only stale containers prefixed `roundtable-sandbox-` belonging to this installation before restarting.
+
+## Memory and scope
+
+`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.
+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.
+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.
+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.
+Turning mode off does not erase workspace files.
+
+This first version 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.
+
+## Development and verification
+
+From the pi-roundtable repository root:
+
+```sh
+bun install --frozen-lockfile
+bun run --cwd packages/sandbox test
+bun run --cwd packages/sandbox typecheck
+bun run --cwd packages/sandbox lint
+```
+
+Offline tests cover credential swapping and reflection, route/header/media refusals, host-bound identity, host-tool and MCP allow-lists, real Unix transport, generated Docker arguments, routing precedence, cancellation/cleanup, persistence and memory scopes.
+The Docker integration test is skipped by default and requires a native Linux non-root host with local Docker:
+
+```sh
+cd packages/sandbox
+SANDBOX_DOCKER_TEST=1 bun test src/docker.integration.test.ts
+```
+
+It builds the image and runs a turn against a fake model endpoint on the host, checking that only the broker receives the real test credential.
+It also runs a hostile PID 1 that ignores SIGTERM and verifies that the turn deadline removes that container.
+No live provider, Discord connection or database is needed.
+Shared CI runs offline checks and explicitly enables that Linux Docker test on its Ubuntu runner.
+The shared publish workflow repeats local checks and requires a version-matching `v*` tag for the core and all official packages.
+The owner performs the first sandbox publication and configures trusted publishing as described in [workspace releases][releases].
+
+[releases]: https://github.com/wayne930242/pi-roundtable/blob/master/.github/PACKAGE-RELEASES.md

package/examples/roundtable.config.ts

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+import type { RoundtableConfig } from "pi-roundtable";
+import { sandbox } from "../src/index.ts";
+
+const home = process.env.HOME;
+if (!home) throw new Error("HOME is required");
+
+/** Merge these plugins into the configuration generated by pi-roundtable init. */
+export const sandboxConfig = {
+	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",
+			),
+			provider: "openai",
+			model: "operator-selected-model",
+			modelUrl: "https://api.openai.com/v1/chat/completions",
+			tools: [
+				{
+					name: "clock",
+					description: "Read the current UTC time",
+					parameters: {
+						type: "object",
+						properties: {},
+						additionalProperties: false,
+					},
+					run: () => new Date().toISOString(),
+				},
+			],
+		}),
+	],
+} satisfies Pick<RoundtableConfig, "plugins">;

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "pi-roundtable-sandbox",
+	"version": "0.7.0",
+	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"bun": ">=1.4.2"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"worker",
+		"!worker/**/*.test.ts",
+		"examples",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/sandbox"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.7.0 <0.8.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@types/bun": "1.4.2",
+		"discord.js": "14.27.0",
+		"pi-roundtable": "0.7.0",
+		"typescript": "7.0.2"
+	}
+}