pi-roundtable 0.6.1 → 0.7.2

package/CHANGELOG.md

@@ -5,6 +5,50 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-10-02
+
+### Fixed
+
+- The release preflight reads npm 12's `npm pack --json` report (an object keyed by package name) and `npm view --json` name (a one-element array) as well as npm 11's, so the `v0.7.1` tag stopped before publishing anything.
+
+## [0.7.1] - 2026-10-02
+
+Tagged but not published: the release preflight failed under npm 12 before any package was published. Its changes ship in 0.7.2.
+
+### Docs
+
+- Document five official packages on the site and link their guides from `docs/plugins.md`, including installation, configuration, platform requirements, and security models.
+  Add a Traditional Chinese `release-notice` guide and reply-attachment guide.
+
+### Changed
+
+- Official drawing, coding, web, sandbox, and MCP plugins now live under `packages/` as Bun workspaces with their original Git history.
+  They remain separate npm packages, checked alongside the core in CI and released in lockstep from one `v*` tag through `publish.yml`.
+  The core's npm file list and release tags are unchanged.
+- `pi-roundtable-mcp` moves from its standalone repository to `packages/mcp` and jumps from 0.4.1 to lockstep 0.7.0, retaining its public API.
+  Both MCP and sandbox now peer on `>=0.7.0 <0.8.0` and test against the live core 0.7.0.
+  Shared CI runs MCP's PostgreSQL tests and explicitly opts into sandbox's native Linux Docker integration.
+
+## [0.7.0] - 2026-10-02
+
+### Added
+
+- Turn reply attachments: `ToolTurn.attachFile(file)` queues raw bytes with the agent's reply instead of posting as the bot ahead of it.
+  The main entry exports `ReplyFile` (`{ name, data: Uint8Array }`), `attachReplyFile` (`(file): void`) for raw session and Pi package tools, `ReplyFileError`, and frozen `REPLY_FILE_LIMITS` (10 files, 10 MiB each, 50 MiB total per turn).
+  Successful `TurnResult` may carry `files`; a successful textless Pi answer with files is posted, while stopped or failed turns discard them.
+  Discord sends files through the same agent webhook identity as the text.
+  Transient tasks and calls outside a conversation turn refuse attachments.
+- `testPlugin` records files attached by `runTool` as `files: { channel, file }[]`; inject a file-capable surface for attachment tests.
+  The guide includes the tested `examples/reply-files.ts` plugin.
+- `roundtable add plugin release-notice` copies a third official plugin. After the agent server is up it posts once in the coordinator's channel when the running release differs from the one last announced, with the commits the release added since the release last announced, read from a `release.json` that the deploy writes (`{ "sha": "...", "commits": ["subject", ...] }`); it also names the channels whose work the previous shutdown cut short, recorded from the `shutdown` event. It remembers the announced `sha` only after the post succeeds. `createReleaseNotice` takes `releaseFile`, `dataDir`, and `announce` to change where the release is read, where the state is kept, and where the post goes.
+
+### Changed
+
+- Chat surfaces explicitly opt in with `ChatSurface.supportsFiles: true` and must deliver every reply file or reject.
+  Existing custom surfaces that handle files must add this flag; absent or false refuses attachment calls and direct `SurfacePort.sendReply` file sends instead of silently losing them.
+  Replacement-runtime result files pass the same capability and size checks; custom turn reply callbacks receive the files and own delivery.
+- `release-notice` joins `codex-images` and `dice` as a reserved name for `add plugin`, and the usage text lists all three.
+
 ## [0.6.1] - 2026-10-02
 
 ### Fixed

package/docs/plugins.md

@@ -52,7 +52,7 @@ Import fixtures and fake threads from `pi-roundtable/testing` for tests.
 
 #### Helpers for a Pi session of your own
 
-Use the kit's building blocks for a plugin that runs Pi itself, such as a coding worker or a container with no network:
+Use the kit's building blocks for a plugin that runs Pi itself, such as a coding worker:
 
 - MCP: `mcpExtension` and `VirtualServer` expose MCP servers to a session, and `mcpAdapterExtension` and `readAttachmentExtension` do the same inside an out-of-process worker.
 - Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard` and `canonicalJson` for the cards of held actions.
@@ -63,9 +63,12 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
 - Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`).
 - Presentation and small helpers: `thinkingLine`, `zonedStamp(date, timeZone)`, `channelQueue()` (a queue of your own, so work does not wait behind a running turn), `checkRepoName` and `SKILL_LIST_TOOL` with `skillListExtension` for repositories and skills, and `searchTerms` for memory search.
 
+The [coding package source][coding-source] shows these helpers in an out-of-process Pi worker.
+The [MCP package source][mcp-source] is a full example of connectors and remote MCP endpoints.
+
 `roundtable add plugin <name>` creates `plugins/<name>.ts` and its test from a small template and lists it in `roundtable.config.ts`.
 The name is lowercase words joined by dashes, such as `my-notes`.
-Two names are reserved for the [official plugins](#official-plugins): `codex-images` and `dice` copy a ready-made plugin into the project.
+Three names are reserved for the [official plugins](#official-plugins): `codex-images`, `dice`, and `release-notice` copy a ready-made plugin into the project.
 
 `roundtable add package <spec>` adds a Pi package from npm: it runs `bun add <spec>`, loads the package's extensions to find the tools they register, and writes `plugins/<name>.ts` and its test, named after the package without its scope, as [`piPackages`](#pipackages-pi-extensions-every-session-loads) describes.
 
@@ -338,7 +341,7 @@ A key the contract does not have stops the start and names the closest one.
 ### `tools`: what agents can call
 
 `defineTool` takes a name (lowercase words joined by underscores), a description the model reads to decide when to call it, a Typebox parameter schema, the lowest tier that may call it, and the function.
-`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, and an abort signal.
+`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, and `attachFile`.
 It returns the text the model reads.
 Throw `ToolRefusal` for a call the model should correct; any other error fails the call.
 
@@ -377,11 +380,79 @@ export const notes = definePlugin({
 
 The tool names `bash`, `read`, `edit`, and `write` belong to the agents already.
 
+#### Attach files to the agent's reply
+
+Call `turn.attachFile(file)` from a tool's `run` to queue a file for the turn's reply, and still return the text the model reads.
+A `ReplyFile` is `{ name: string; data: Uint8Array }`: raw bytes, including images, not a path or base64 string.
+The core copies the bytes when the call succeeds, so the tool may reuse its buffer afterwards.
+The tool does not send a message itself; the successful turn returns `TurnResult.files` and the reply path hands them to the surface as `OutboundReply.files`.
+On Discord, files follow the text as one file per message to avoid image grids, all through the same agent webhook name and avatar as the text.
+Other surfaces may send the text and files in one message or a message group.
+The [drawing package source][drawing-source] uses `turn.attachFile` to deliver images produced by its tools.
+
+<!-- example: examples/reply-files.ts -->
+```ts
+import { definePlugin, defineTool } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** A small PNG keeps this example runnable without an image provider. */
+export const imageReply = definePlugin({
+	name: "image-reply",
+	setup: () => ({
+		tools: [
+			defineTool({
+				name: "reply_image",
+				description: "Attach a sample image to your reply.",
+				parameters: Type.Object({}),
+				minTier: "member",
+				run: (_args, turn) => {
+					turn.attachFile({
+						name: "sample.png",
+						data: Buffer.from(
+							"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aD1sAAAAASUVORK5CYII=",
+							"base64",
+						),
+					});
+					return "The sample image is attached to this turn's reply.";
+				},
+			}),
+		],
+	}),
+});
+```
+<!-- /example -->
+
+`attachReplyFile(file): void`, `ReplyFile`, `ReplyFileError`, and the frozen `REPLY_FILE_LIMITS` are exported from `pi-roundtable`.
+Raw `sessionTools` and Pi package tools may import and call `attachReplyFile` during their awaited tool execution; it is the same function as `turn.attachFile`.
+It uses the current asynchronous turn, not a global channel queue, so simultaneous turns and nested conversation turns keep separate files.
+A Pi package should use the host's peer dependency on `pi-roundtable`, not bundle another copy of it.
+Transient `SessionContext.runTask` tasks return only text and cannot attach to their parent's reply.
+Calling the helper outside `context.turns.run` or an agent-team turn, or after that turn finishes, throws `ReplyFileError`; direct standalone runtime calls have no reply collector.
+Await work that produces files before returning from the tool.
+
+| Case | Behavior |
+|---|---|
+| Successful final answer with no text | Files are posted without a placeholder text; a final answer with neither text nor files still fails in the Pi runtime |
+| Stopped, timed-out, or failed turn | Accepted files are discarded; only the usual stopped or failure notice is posted |
+| A tool fails but the model recovers and completes the turn | Files already accepted remain queued for the successful reply; a tool failure does not roll back earlier attachment calls |
+| Unsupported surface | `ChatSurface.supportsFiles` must be `true`; absent or false makes attachment calls throw `ReplyFileError`, which Pi reports to the model as a tool error |
+| Too many or too large files | At most 10 files per turn, 10 MiB (10,485,760 bytes) per file, and 50 MiB (52,428,800 bytes) in total across all tools; the exceeding call throws `ReplyFileError` without queuing that file |
+| Invalid file | Empty bytes, non-`Uint8Array` data, empty filenames, names over 255 characters, paths, `.`/`..`, or control characters throw `ReplyFileError` |
+| A surface rejects delivery | The reply path logs `reply not posted` or `agent reply not posted`; delivery may be partial, is not retried, and does not change the completed runtime result |
+
+A surface declaring `supportsFiles: true` must deliver every `OutboundReply.files` entry with the reply's speaker identity, or reject with an error; its transport may impose stricter limits.
+`SurfacePort.sendReply` also refuses direct file sends to a surface without that declaration instead of silently dropping files.
+A replacement runtime may return `files` in its successful `TurnResult`; the turn path applies the same limits and capability check before posting.
+Use either the helper or the result for each file: returning an already attached file queues a second copy, counted against the same limits.
+A custom `ConversationTurnInput.reply(result)` receives `result.files` and owns their delivery instead of the default surface reply.
+Test an attachment tool with an injected file-capable surface and inspect `harness.files` (see [`reply-files.test.ts`](../examples/reply-files.test.ts)); `runTool` itself posts nothing.
+
 ### `holdRules`, and a tool's `hold`: calls that wait for the owner
 
 A held call is described to the owner, who approves or refuses it in Discord before the call runs.
 A tool's `hold` returns the description for its own calls, and `holdRules` are rules over every tool call, asked in order until one describes the call.
 Each rule needs a name, unique across plugins.
+The [coding package source][coding-source] uses an owner hold for `repo_push`.
 
 <!-- example: examples/holds.ts -->
 ```ts
@@ -801,6 +872,7 @@ When no `images` provider is configured, `agent_create` has no `avatar_prompt` p
 The owner's profile panel reports the missing provider and offers no redraw option.
 Each agent gets a picture generated from its display name and the assistant's icon, so you can tell agents apart.
 `bunx roundtable doctor` reports whether the slot is filled.
+The copy-in [`codex-images` provider template][codex-images-template] is a complete implementation of the `images` slot.
 
 <!-- example: examples/providers.ts -->
 ```ts
@@ -1193,6 +1265,7 @@ The configuration's `http` block opens a listener named `public`, which serves t
 A route names the listener, a path (`{ exact }` or `{ prefix }`), optionally the methods, and a handler that gets a `Request` and returns a `Response`.
 Two routes that could take the same request are refused, so a route cannot shadow the avatars.
 This listener is reachable from the internet, so check a secret in the handler before taking action.
+The [web package source][web-source] is a complete owner-console implementation built on these HTTP routes.
 A handler that throws, or returns a rejected promise, answers `500 Internal Server Error` with that fixed body, and the listener keeps serving.
 The host logs one error line with the route's `name` and its `listener`; it never logs the request URL, since a path may hold a secret.
 
@@ -1389,6 +1462,8 @@ Give `stop` to a claim whose conversations run turns that can be interrupted.
 
 For a claim with its own conversations, return the conversation's kind from `startFresh`.
 Run turns with [`context.turns`](#personas-and-contextturns-conversations-of-a-kind-of-your-own), which handles typing, the stop control, events, and replies.
+The [sandbox package source][sandbox-source] is a complete guest-only channel claim backed by a no-network Docker agent and a host-side broker.
+Its container runs a minimal Chat Completions loop rather than a Pi session.
 
 <!-- example: examples/channels.ts -->
 ```ts
@@ -1811,27 +1886,90 @@ The following fields and parts from 0.1.0 were removed because only built-in plu
 
 ## Official plugins
 
-The package ships two plugins you can copy into a project and change.
-`roundtable add plugin codex-images` and `roundtable add plugin dice` write `plugins/<name>.ts` and `plugins/<name>.test.ts`, import the plugin in `roundtable.config.ts`, and list it in `plugins`.
+The package ships three plugins you can copy into a project and change.
+`roundtable add plugin codex-images`, `roundtable add plugin dice`, and `roundtable add plugin release-notice` write `plugins/<name>.ts` and `plugins/<name>.test.ts`, import the plugin in `roundtable.config.ts`, and list it in `plugins`.
 You can edit the copied files; `add plugin` refuses to overwrite existing ones.
-Both names are reserved for these copies.
+The three names are reserved for these copies.
+Inspect the ready-made implementations in the [codex-images][codex-images-template], [dice][dice-template], and [release-notice][release-notice-template] templates.
 
-A separate package, [pi-roundtable-mcp](https://www.npmjs.com/package/pi-roundtable-mcp), adds two more plugins, `mcpConnectors` and `remoteMcp`.
+The [pi-roundtable-mcp][mcp-package] workspace, published separately on npm, adds two more plugins, `mcpConnectors` and `remoteMcp`.
 The first lets the owner add MCP servers such as Notion or a calendar from Discord and gives your code the list; the second lets an agent outside Discord reach your agent.
-Install it with `bun add pi-roundtable-mcp`.
+Install it with `bun add pi-roundtable-mcp` after the next lockstep release publishes the migrated package.
+Until then, npm's MCP 0.4.1 requires core below 0.6.0 and is not compatible with core 0.7.x.
+
+Five official packages live in this repository as Bun workspaces and publish as separate npm packages, versioned in lockstep with the core.
+The [site guide source files][package-guides] describe installation, requirements, configuration, and security considerations:
+
+- [pi-roundtable-drawing][drawing-package]: [site guide source][drawing-guide] · local relationship maps, magic circles, sigils, sacred geometry, and card spreads.
+- [pi-roundtable-coding][coding-package]: [site guide source][coding-guide] · repository shelves and owner-approved Pi coding workers.
+- [pi-roundtable-web][web-package]: [site guide source][web-guide] · an owner-only console for conversations, transcripts, and memory notes with live updates.
+- [pi-roundtable-sandbox][sandbox-package]: [site guide source][sandbox-guide] · sealed guest channels on native Linux Docker with a host-only credential broker and allow-listed tools.
+- [pi-roundtable-mcp][mcp-package]: [site guide source][mcp-guide] · MCP connectors through a gateway and remote MCP endpoints for agent turns and owner-granted Discord channel tools.
+
+[drawing-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/drawing/README.md
+[coding-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/coding/README.md
+[web-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/web/README.md
+[sandbox-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/sandbox/README.md
+[mcp-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/mcp/README.md
+[package-guides]: https://github.com/wayne930242/pi-roundtable/tree/master/site/src/content/docs/plugins/
+[drawing-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/drawing-package.mdx
+[coding-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/coding-package.mdx
+[web-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/web-package.mdx
+[sandbox-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/sandbox-package.mdx
+[mcp-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/mcp-package.mdx
+[coding-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/coding
+[sandbox-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/sandbox
+[web-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/web
+[drawing-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/drawing
+[mcp-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/mcp
+[codex-images-template]: https://github.com/wayne930242/pi-roundtable/blob/master/templates/official/codex-images/plugin.ts
+[dice-template]: https://github.com/wayne930242/pi-roundtable/blob/master/templates/official/dice/plugin.ts
+[release-notice-template]: https://github.com/wayne930242/pi-roundtable/blob/master/templates/official/release-notice/plugin.ts
+
+Install only the packages your host uses; the core does not depend on these workspaces.
 
 | Plugin | What it does | What it needs |
 |---|---|---|
 | `codex-images` | Fills the [`images` slot](#providers-replace-a-part-the-core-runs-on), so agents can draw avatars from a prompt and reference pictures | A login to the `openai-codex` provider; setup throws a `PluginError` that says so when the host has none |
 | `dice` | Adds the `roll_dice` tool for members: `2d6+3`, `4d6k3` (keep or drop the highest or lowest dice), several groups, and fate dice `dF`, answered as text such as `2d6+3: [3, 5] + 3 = 11` | Nothing; it takes at most 100 dice in all and 1000 sides per die |
+| `release-notice` | After a deploy, posts once in the coordinator's channel which commits the running release added since the release last announced, and says which channels the previous shutdown cut short | A `release.json` that your deploy writes (see below); without the file it posts nothing |
 
 `codex-images` takes the login through [`context.apiKey("openai-codex")`](#the-context).
 It sends requests to ChatGPT's Codex backend using the owner's ChatGPT subscription login.
 OpenAI doesn't document the backend for this use, so it can stop working without notice; the subscription's terms apply.
 The copied file begins with this warning.
 
-Each copy has a test that runs offline: `codex-images` with a fake `fetch`, `dice` with a fake random source.
-Both files export a `create...` function (`createCodexImages`, `createDice`) that takes the part a test replaces, and the plugin you list in the config, built from it.
+`release-notice` listens to two [events](#events-hear-what-the-core-does).
+When the agent server's team service reports `ready`, it reads the release file and posts if the release's `sha` differs from the one it last announced (`announced-release` in the data directory), or if the previous shutdown cut work short.
+It records the announced `sha` only after the post succeeds, so a failed post is tried again at the next start, and a `release.json` that is not valid (not JSON, an empty `sha`, or `commits` that is not a list of strings) fails the handler with its path in the log.
+At `shutdown(left)` it adds the channels in `left`, the work the drain gave up on after an hour, to `aborted-on-shutdown.json` in the data directory; the next start's announcement names them as cut short (a Discord channel key as a `<#id>` mention), and once it is posted they are removed from the file. A shutdown that arrives while a post is still in flight keeps its channels for the next announcement.
+A plain restart of the same release with nothing cut short posts nothing.
+
+The deploy writes `release.json` into the release directory, where the bot runs, before it starts the bot.
+The file holds the commit the release was built from and the subjects of the commits it added over the release last announced, newest first, so that a release whose announcement failed or never ran is not skipped over:
+
+```json
+{ "sha": "abc1234", "commits": ["fix: handle an empty reply", "feat: add a notes tool"] }
+```
+
+The plugin keeps the sha it last announced in `announced-release` in its data directory, so a deploy script on the same host can read the range's start from there.
+This script writes the file from the checkout, and stops the deploy when `git log` or `jq` fails; the first deploy, with nothing announced yet, gets an empty `commits` list:
+
+```sh
+set -euo pipefail
+previous=$(cat data/announced-release 2>/dev/null || true)
+commits='[]'
+if [ -n "$previous" ]; then
+  commits=$(git log --format=%s "$previous..HEAD" | jq -R . | jq -s .)
+fi
+printf '{"sha":"%s","commits":%s}\n' "$(git rev-parse --short HEAD)" "$commits" > release.json
+```
+
+`createReleaseNotice(options)` takes `releaseFile` (default `release.json` in the working directory), `dataDir` (default `./data`, where a new project's config keeps its data, so set it when the config's `dataDir` differs), and `announce` (default: the agent team's `announce`, which posts in the coordinator's channel and splits a long text).
+The plugin you list in the config, `releaseNotice`, uses the defaults.
+
+Each copy has a test that runs offline: `codex-images` with a fake `fetch`, `dice` with a fake random source, `release-notice` with temporary directories and its own `announce`.
+Each file exports a `create...` function (`createCodexImages`, `createDice`, `createReleaseNotice`) that takes the part a test replaces, and the plugin you list in the config, built from it.
 
 ## Testing a plugin
 
@@ -1847,6 +1985,7 @@ It returns:
 | `tools`, `tiers` | The tool names, and the table that says what tier each needs |
 | `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace? })` returns the description of a call that must be approved first, or `undefined` |
 | `runTool(name, args, { speaker, channel }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads |
+| `files` | Accepted files from `runTool`, recorded as `{ channel, file: ReplyFile }`; inject a surface with `supportsFiles: true` and pass its channel to test attachment tools |
 | `events` | The events the plugin itself reported through `context.events`, and those of `context.turns` |
 | `conversations`, `turns`, `surfaces` | What the plugin sees as `context.conversations`, `context.turns`, and `context.surfaces`, for a test to drive its claims |
 | `runtime` | The runtime the plugin's `runtime` provider built, given stand-in dependencies; `undefined` when it fills no such slot |
@@ -2283,6 +2422,9 @@ Import from the entries listed below; source area files are internal.
 | `ResolvedProviders` | `pi-roundtable` | type |
 | `ResolvedSkill` | `pi-roundtable` | type |
 | `Roundtable` | `pi-roundtable` | value |
+| `ReplyFile` | `pi-roundtable` | type |
+| `ReplyFileError` | `pi-roundtable` | value |
+| `REPLY_FILE_LIMITS` | `pi-roundtable` | value |
 | `RoundtableConfig` | `pi-roundtable` | type |
 | `RoundtableOptions` | `pi-roundtable` | type |
 | `RoundtablePlugin` | `pi-roundtable` | type |
@@ -2336,6 +2478,7 @@ Import from the entries listed below; source area files are internal.
 | `TurnResult` | `pi-roundtable` | type |
 | `TurnSelection` | `pi-roundtable` | type |
 | `Weekday` | `pi-roundtable` | type |
+| `attachReplyFile` | `pi-roundtable` | value |
 | `channelKey` | `pi-roundtable` | value |
 | `definePlugin` | `pi-roundtable` | value |
 | `defineRoundtable` | `pi-roundtable` | value |

package/examples/reply-files.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test";
+import type { ChatSurface } from "pi-roundtable";
+import { testPlugin } from "pi-roundtable/testing";
+import { imageReply } from "./reply-files.ts";
+
+test("reply_image records its attachment without posting ahead of the agent", async () => {
+	let posted = false;
+	const surface: ChatSurface = {
+		surface: "fake",
+		supportsFiles: true,
+		start: async () => undefined,
+		sendReply: async () => {
+			posted = true;
+		},
+	};
+	const harness = await testPlugin(imageReply, { surfaces: [surface] });
+	try {
+		expect(
+			await harness.runTool("reply_image", {}, { channel: "fake:room" }),
+		).toBe("The sample image is attached to this turn's reply.");
+		expect(posted).toBe(false);
+		expect(harness.files).toHaveLength(1);
+		expect(harness.files[0]?.channel).toBe("fake:room");
+		expect(harness.files[0]?.file.name).toBe("sample.png");
+		expect(harness.files[0]?.file.data.slice(0, 8)).toEqual(
+			new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+		);
+		await expect(harness.runTool("reply_image", {})).rejects.toThrow(
+			"does not support reply files",
+		);
+	} finally {
+		await harness.stop();
+	}
+});

package/examples/reply-files.ts

@@ -0,0 +1,27 @@
+import { definePlugin, defineTool } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** A small PNG keeps this example runnable without an image provider. */
+export const imageReply = definePlugin({
+	name: "image-reply",
+	setup: () => ({
+		tools: [
+			defineTool({
+				name: "reply_image",
+				description: "Attach a sample image to your reply.",
+				parameters: Type.Object({}),
+				minTier: "member",
+				run: (_args, turn) => {
+					turn.attachFile({
+						name: "sample.png",
+						data: Buffer.from(
+							"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aD1sAAAAASUVORK5CYII=",
+							"base64",
+						),
+					});
+					return "The sample image is attached to this turn's reply.";
+				},
+			}),
+		],
+	}),
+});

package/package.json

@@ -1,9 +1,15 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.6.1",
+	"version": "0.7.2",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",
+	"workspaces": [
+		"packages/*"
+	],
+	"overrides": {
+		"pi-roundtable": "link:."
+	},
 	"engines": {
 		"bun": ">=1.3.0"
 	},
@@ -45,7 +51,8 @@
 	"scripts": {
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check .",
-		"test": "bun test"
+		"test": "bun test ./src ./scripts ./examples",
+		"check:packages": "bun run --workspaces typecheck && bun run --workspaces lint && bun run --workspaces test"
 	},
 	"dependencies": {
 		"@babel/parser": "7.29.9",
@@ -63,7 +70,7 @@
 	},
 	"devDependencies": {
 		"typescript": "7.0.2",
-		"@biomejs/biome": "2.5.14",
+		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
 		"pi-web-access": "0.35.0"
 	}

package/src/cli/cli.ts

@@ -36,7 +36,7 @@ const USAGE = `roundtable: a Discord agent server on Pi
   roundtable doctor [--reachable]  check the setup and say how to fix what is wrong
   roundtable start              run the checks that need no network, then the bot
   roundtable add plugin <name>  add plugins/<name>.ts and its test, and list it in the config
-                                the names ${OFFICIAL_PLUGINS.join(" and ")} are reserved for the official plugins,
+                                the names ${new Intl.ListFormat("en").format(OFFICIAL_PLUGINS)} are reserved for the official plugins,
                                 which are copied in ready to run instead of the template
   roundtable add package <spec> install a Pi package with bun add, and add plugins/<name>.ts that
                                 loads it and gives its tools to every agent turn

package/src/cli/templates.ts

@@ -20,7 +20,11 @@ const OFFICIAL_DIR = "official";
 const PACKAGE_DIR = "package";
 
 /** The plugins the package ships ready-made: `add plugin <name>` copies these instead of the `hello` template, so the names are reserved. */
-export const OFFICIAL_PLUGINS = ["codex-images", "dice"] as const;
+export const OFFICIAL_PLUGINS = [
+	"codex-images",
+	"dice",
+	"release-notice",
+] as const;
 
 /** Whether `name` is one of the official plugins. */
 export const isOfficialPlugin = (name: string): boolean =>

package/src/core/agents/team-turns.ts

@@ -2,6 +2,7 @@ import type { TurnAttachments } from "../domain/attachment.ts";
 import type {
 	ChannelKey,
 	PendingConfirmation,
+	ReplyFile,
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
@@ -9,6 +10,7 @@ import type { AgentTurnScope } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { thinkingLine } from "../presentation/thinking-line.ts";
+import { withReplyFiles } from "../reply-files.ts";
 import { endOf, settleTurn } from "../routing/settle-turn.ts";
 import type { Speaker } from "../speakers.ts";
 import { toolTiers } from "../tool-tiers.ts";
@@ -183,17 +185,19 @@ export class TeamTurns {
 		try {
 			result = await settleTurn(
 				() =>
-					this.#options.runtime().runTurn({
-						channel: postTo,
-						selection: this.#options.selection(scope),
-						text,
-						...(extra.attachments ? { attachments: extra.attachments } : {}),
-						...(extra.confirmed ? { confirmed: true } : {}),
-						...(extra.steerable ? { steerable: true } : {}),
-						...(extra.interactive ? { interactive: true } : {}),
-						agent: scope,
-						speaker: chain.speaker,
-					}),
+					withReplyFiles(true, () =>
+						this.#options.runtime().runTurn({
+							channel: postTo,
+							selection: this.#options.selection(scope),
+							text,
+							...(extra.attachments ? { attachments: extra.attachments } : {}),
+							...(extra.confirmed ? { confirmed: true } : {}),
+							...(extra.steerable ? { steerable: true } : {}),
+							...(extra.interactive ? { interactive: true } : {}),
+							agent: scope,
+							speaker: chain.speaker,
+						}),
+					),
 				"agent turn",
 			);
 		} finally {
@@ -220,6 +224,7 @@ export class TeamTurns {
 			await this.#post(postTo, this.#current(agent), {
 				...(thinking ? { thinking } : {}),
 				chunks: result.ok ? splitReply(result.text) : [noticeOf(result)],
+				...(result.ok && result.files?.length ? { files: result.files } : {}),
 			});
 		} catch (error) {
 			logger.error({ agent: agent.name, err: error }, "agent reply not posted");
@@ -248,7 +253,12 @@ export class TeamTurns {
 	async #post(
 		channel: ChannelKey,
 		as: Agent,
-		body: { thinking?: string; chunks: string[]; threadId?: string },
+		body: {
+			thinking?: string;
+			chunks: string[];
+			files?: ReplyFile[];
+			threadId?: string;
+		},
 	): Promise<void> {
 		const { store, channels, studio, logger } = this.#options;
 		if (!channelOwner(store, channel)) {

package/src/core/contract/surface.ts

@@ -39,6 +39,8 @@ export function channelKey(surface: string, id: string): ChannelKey {
 export interface ChatSurface {
 	/** The key prefix of this surface's channels, such as "discord"; unique per host. */
 	readonly surface: string;
+	/** Explicit opt-in to delivering OutboundReply.files; absent or false refuses turn attachments. */
+	readonly supportsFiles?: boolean;
 	/**
 	 * Connects and delivers every incoming message; the host passes its conversation router. A
 	 * message whose channel key has another prefix is logged and dropped.

package/src/core/define.ts

@@ -1,7 +1,9 @@
 import type { Static, TObject } from "typebox";
+import type { ReplyFile } from "./domain/conversation.ts";
 import { PluginError } from "./errors.ts";
 import type { HoldRule } from "./holds.ts";
 import { type RoundtablePlugin, refuseRemovedFields } from "./plugin.ts";
+import { attachReplyFile } from "./reply-files.ts";
 import type { AgentTurnScope, ChannelKey, SessionTool } from "./sessions.ts";
 import { toolError, toolText } from "./shared/tool-result.ts";
 import { type Speaker, TIERS, type Tier } from "./speakers.ts";
@@ -22,6 +24,8 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/** Queues a file for this turn's successful reply; throws ReplyFileError when refused. */
+	attachFile(file: ReplyFile): void;
 }
 
 /**
@@ -108,6 +112,7 @@ export function defineTool<Schema extends TObject>(
 									channel: context.turnChannel,
 									agent: context.agent,
 									signal,
+									attachFile: attachReplyFile,
 								}),
 							);
 						} catch (error) {

package/src/core/discord/discord-surface.ts

@@ -64,6 +64,7 @@ export class DiscordSurface
 	implements ChatSurface, OwnerNotifier, DiscordConnection
 {
 	readonly surface = "discord";
+	readonly supportsFiles = true;
 	readonly #options: DiscordSurfaceOptions;
 	readonly #client = new Client({
 		intents: [

package/src/core/domain/conversation.ts

@@ -25,8 +25,14 @@ export interface PendingConfirmation {
 	calls: HeldCall[];
 }
 
+/** A file produced for a reply; data is raw bytes, not a path or base64. */
+export interface ReplyFile {
+	name: string;
+	data: Uint8Array;
+}
+
 export type TurnResult =
-	| { ok: true; text: string; thinking?: string }
+	| { ok: true; text: string; thinking?: string; files?: ReplyFile[] }
 	| { ok: false; error: Error; stopped?: true };
 
 export interface OutboundReply {
@@ -37,5 +43,5 @@ export interface OutboundReply {
 	/** Message texts in posting order; the card is posted before them. */
 	chunks: string[];
 	/** Files the run produced, posted after the text. */
-	files?: { name: string; data: Uint8Array }[];
+	files?: ReplyFile[];
 }