pi-roundtable 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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
+
+- `add plugin` and `add package` kept a one-line `plugins` list on one line however long it grew, so a project's `biome check` failed once the line passed 80 columns. A list that would pass 80 columns is now put one element a line, as the formatter writes it; a list already over several lines keeps its layout, and one holding a comment stays as it was.
+
 ## [0.6.0] - 2026-10-02
 
 ### Added

package/docs/plugins.md

@@ -65,7 +65,7 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
 
 `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 +338,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,6 +377,72 @@ 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.
+
+<!-- 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.
@@ -1811,10 +1877,10 @@ 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.
 
 A separate package, [pi-roundtable-mcp](https://www.npmjs.com/package/pi-roundtable-mcp), 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.
@@ -1824,14 +1890,44 @@ Install it with `bun add pi-roundtable-mcp`.
 |---|---|---|
 | `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 +1943,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 +2380,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 +2436,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,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

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/config-edit.ts

@@ -115,6 +115,50 @@ function pluginList(object: Node): Node | undefined {
 interface Insertion {
 	at: number;
 	text: string;
+	/** How many characters from `at` the text replaces; none when it only inserts. */
+	replaces?: number;
+}
+
+/** The width the formatter gives a line: a tab counts as its default indent width of 2. */
+const LINE_WIDTH = 80;
+const width = (line: string): number => line.replaceAll("\t", "  ").length;
+
+/**
+ * The one-line list with `ident` added, put one element a line when the line it sits on would
+ * pass the formatter's width, as the project's formatter would; undefined when the list already
+ * spans lines, holds anything besides its elements and commas, or still fits.
+ */
+function expandedList(
+	source: string,
+	list: Node,
+	elements: readonly Node[],
+	ident: string,
+): Insertion | undefined {
+	const inner = source.slice(list.start + 1, list.end - 1);
+	if (inner.includes("\n")) return undefined;
+	const items = elements.map((element) =>
+		source.slice(element.start, element.end),
+	);
+	// The text around and between the elements, which must be only commas and spaces.
+	const edges = [
+		list.start + 1,
+		...elements.flatMap((element) => [element.start, element.end]),
+		list.end - 1,
+	];
+	let gaps = "";
+	for (let index = 0; index < edges.length; index += 2)
+		gaps += source.slice(edges[index], edges[index + 1]);
+	if (!/^[\s,]*$/.test(gaps)) return undefined;
+	const lineStart = source.lastIndexOf("\n", list.start) + 1;
+	const lineEnd = source.indexOf("\n", list.end);
+	const line = `${source.slice(lineStart, list.start)}[${[...items, ident].join(", ")}]${source.slice(list.end, lineEnd === -1 ? undefined : lineEnd)}`;
+	if (width(line) <= LINE_WIDTH) return undefined;
+	const indent = /^[ \t]*/.exec(source.slice(lineStart, list.start))?.[0] ?? "";
+	return {
+		at: list.start,
+		replaces: list.end - list.start,
+		text: `[\n${[...items, ident].map((item) => `${indent}\t${item},\n`).join("")}${indent}]`,
+	};
 }
 
 /** The text to add so `ident` joins the list, in the list's own layout. */
@@ -122,6 +166,8 @@ function listInsertion(source: string, list: Node, ident: string): Insertion {
 	const elements = (list.elements as (Node | null)[]).filter(
 		(element): element is Node => element !== null,
 	);
+	const expanded = expandedList(source, list, elements, ident);
+	if (expanded) return expanded;
 	const last = elements.at(-1);
 	if (!last) return { at: list.start + 1, text: ident };
 	const between = source.slice(last.end, list.end - 1);
@@ -161,8 +207,9 @@ function importInsertion(
 
 /**
  * Adds the plugin's import line and lists it in the `plugins` array of the default export, in the
- * file's own layout. It refuses, changing nothing, a file that does not parse, a default export
- * with no `plugins` list it can find, and a name already bound.
+ * file's own layout; a one-line list that would pass 80 columns is put one element a line. It
+ * refuses, changing nothing, a file that does not parse, a default export with no `plugins` list
+ * it can find, and a name already bound.
  */
 export function addPluginToConfig(
 	source: string,
@@ -192,7 +239,10 @@ export function addPluginToConfig(
 	].sort((a, b) => b.at - a.at);
 	let edited = source;
 	for (const edit of edits)
-		edited = edited.slice(0, edit.at) + edit.text + edited.slice(edit.at);
+		edited =
+			edited.slice(0, edit.at) +
+			edit.text +
+			edited.slice(edit.at + (edit.replaces ?? 0));
 	// A result that does not parse is a bug here; never write it.
 	parseModule(edited, file);
 	return edited;

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[];
 }

package/src/core/reply-files.ts

@@ -0,0 +1,107 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ReplyFile, TurnResult } from "./domain/conversation.ts";
+
+/** Limits across all tools in one turn, independent of the surface's own limits. */
+export const REPLY_FILE_LIMITS = Object.freeze({
+	maxFiles: 10,
+	maxFileBytes: 10 * 1024 * 1024,
+	maxTotalBytes: 50 * 1024 * 1024,
+});
+
+/** An attachment was refused; its message names the reason instead of dropping the file. */
+export class ReplyFileError extends Error {
+	override name = "ReplyFileError";
+}
+
+interface ReplyFiles {
+	active: boolean;
+	supported: boolean;
+	files: ReplyFile[];
+	bytes: number;
+}
+
+const current = new AsyncLocalStorage<ReplyFiles | undefined>();
+
+/**
+ * Queues a copy of a file for the current turn's successful reply. Session tools and Pi package
+ * tools may call this directly; outside a supported running turn it throws ReplyFileError.
+ */
+export function attachReplyFile(file: ReplyFile): void {
+	const turn = current.getStore();
+	if (!turn?.active)
+		throw new ReplyFileError(
+			"attachReplyFile requires a running conversation turn; await it inside the turn's tool call.",
+		);
+	if (!turn.supported)
+		throw new ReplyFileError(
+			"this turn's chat surface does not support reply files.",
+		);
+	if (
+		!file ||
+		typeof file.name !== "string" ||
+		!file.name.trim() ||
+		file.name.length > 255 ||
+		/[\\/]/.test(file.name) ||
+		[...file.name].some(
+			(char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+		) ||
+		file.name === "." ||
+		file.name === ".."
+	)
+		throw new ReplyFileError(
+			"a reply file needs a non-empty filename of at most 255 characters, without paths or control characters.",
+		);
+	if (!(file.data instanceof Uint8Array) || file.data.byteLength === 0)
+		throw new ReplyFileError("a reply file needs non-empty Uint8Array data.");
+	if (turn.files.length >= REPLY_FILE_LIMITS.maxFiles)
+		throw new ReplyFileError(
+			`a turn may attach at most ${REPLY_FILE_LIMITS.maxFiles} reply files.`,
+		);
+	if (file.data.byteLength > REPLY_FILE_LIMITS.maxFileBytes)
+		throw new ReplyFileError(
+			`a reply file may contain at most ${REPLY_FILE_LIMITS.maxFileBytes} bytes.`,
+		);
+	if (turn.bytes + file.data.byteLength > REPLY_FILE_LIMITS.maxTotalBytes)
+		throw new ReplyFileError(
+			`a turn's reply files may contain at most ${REPLY_FILE_LIMITS.maxTotalBytes} bytes in total.`,
+		);
+	turn.files.push({ name: file.name, data: new Uint8Array(file.data) });
+	turn.bytes += file.data.byteLength;
+}
+
+/** Used by test fixtures to forward attachments only when called inside a turn. */
+export function hasReplyFileScope(): boolean {
+	return current.getStore()?.active === true;
+}
+
+/** Whether an otherwise empty final answer has files to show. */
+export function hasReplyFiles(): boolean {
+	const turn = current.getStore();
+	return turn?.active === true && turn.files.length > 0;
+}
+
+/** One isolated collector per turn, also when turns run concurrently or nest. */
+export async function withReplyFiles(
+	supported: boolean,
+	run: () => Promise<TurnResult>,
+): Promise<TurnResult> {
+	const turn: ReplyFiles = { active: true, supported, files: [], bytes: 0 };
+	return current.run(turn, async () => {
+		try {
+			const result = await run();
+			if (!result.ok) return result;
+			// A replacement runtime may produce files in its result rather than calling the helper.
+			for (const file of result.files ?? []) attachReplyFile(file);
+			return turn.files.length ? { ...result, files: [...turn.files] } : result;
+		} finally {
+			turn.active = false;
+			turn.files = [];
+			turn.bytes = 0;
+		}
+	});
+}
+
+/** A transient task reports text, not a conversation reply: it cannot borrow its parent's collector. */
+export function withoutReplyFiles<T>(run: () => Promise<T>): Promise<T> {
+	return current.run(undefined, run);
+}

package/src/core/routing/conversation-turns.ts

@@ -7,6 +7,7 @@ import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { thinkingLine } from "../presentation/thinking-line.ts";
+import { withReplyFiles } from "../reply-files.ts";
 import type { ChannelKey, ToolSelection, TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import { endOf, settleTurn } from "./settle-turn.ts";
@@ -85,20 +86,24 @@ export function conversationTurns(
 			try {
 				result = await settleTurn(
 					() =>
-						runtime.runTurn({
-							channel,
-							kind,
-							selection: input.selection ?? {
-								id: DEFAULT_SELECTION,
-								...options.selection(),
-							},
-							text: input.text,
-							speaker,
-							...(input.attachments ? { attachments: input.attachments } : {}),
-							...(input.confirmed ? { confirmed: true } : {}),
-							...(input.steerable ? { steerable: true } : {}),
-							...(input.interactive ? { interactive: true } : {}),
-						}),
+						withReplyFiles(surfaces.of(channel)?.supportsFiles === true, () =>
+							runtime.runTurn({
+								channel,
+								kind,
+								selection: input.selection ?? {
+									id: DEFAULT_SELECTION,
+									...options.selection(),
+								},
+								text: input.text,
+								speaker,
+								...(input.attachments
+									? { attachments: input.attachments }
+									: {}),
+								...(input.confirmed ? { confirmed: true } : {}),
+								...(input.steerable ? { steerable: true } : {}),
+								...(input.interactive ? { interactive: true } : {}),
+							}),
+						),
 					"conversation turn",
 				);
 			} finally {
@@ -135,5 +140,6 @@ function replyOf(result: TurnResult) {
 	return {
 		...(thinking ? { thinking } : {}),
 		chunks: splitReply(result.text),
+		...(result.files?.length ? { files: result.files } : {}),
 	};
 }

package/src/core/routing/surface-port.ts

@@ -24,8 +24,14 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 	};
 	return {
 		of,
-		sendReply: async (channel, reply) =>
-			served(channel).sendReply(channel, reply),
+		sendReply: async (channel, reply) => {
+			const surface = served(channel);
+			if (reply.files?.length && surface.supportsFiles !== true)
+				throw new PluginError(
+					`surface ${surface.surface} does not support reply files; declare supportsFiles: true and deliver every file in sendReply.`,
+				);
+			await surface.sendReply(channel, reply);
+		},
 		startTyping: (channel) =>
 			of(channel)?.startTyping?.(channel) ?? (() => undefined),
 		showStop: (channel) =>

package/src/core/runtime/pi-agent-runtime.ts

@@ -24,6 +24,7 @@ import {
 	type ThinkingLevel,
 	type ThinkingSetting,
 } from "../models.ts";
+import { withoutReplyFiles } from "../reply-files.ts";
 import { planOrder, type TransientTask } from "../sessions.ts";
 import { textOf } from "../shared/session-messages.ts";
 import { addressee, type Speaker, type Tier } from "../speakers.ts";
@@ -352,7 +353,7 @@ export class PiAgentRuntime implements AgentRuntime {
 						this.#tiers.allows(tier, name),
 				);
 			session.setActiveToolsByName([...worker.tools]);
-			await session.prompt(task.text);
+			await withoutReplyFiles(() => session.prompt(task.text));
 			return workerReport(
 				session.messages,
 				"the worker stopped before it reported",

package/src/core/runtime/turn-answer.ts

@@ -1,5 +1,6 @@
 import type { TurnResult } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
+import { hasReplyFiles } from "../reply-files.ts";
 import { lastAssistant, textOf } from "../shared/session-messages.ts";
 
 interface MessagePart {
@@ -67,7 +68,7 @@ export function turnAnswer(
 					.join("\n\n")
 			: textOf(last.message.content)
 	).trim();
-	if (!text)
+	if (!text && !hasReplyFiles())
 		return {
 			ok: false,
 			error: new AgentRunError("the final assistant message has no text"),

package/src/index.ts

@@ -77,6 +77,7 @@ export type {
 	HeldCall,
 	OutboundReply,
 	PendingConfirmation,
+	ReplyFile,
 	TranscriptEntry,
 	TurnResult,
 } from "./core/domain/conversation.ts";
@@ -157,6 +158,11 @@ export type {
 	TurnEndEvent,
 	TurnEvent,
 } from "./core/plugin.ts";
+export {
+	attachReplyFile,
+	REPLY_FILE_LIMITS,
+	ReplyFileError,
+} from "./core/reply-files.ts";
 export type {
 	ConversationTurnInput,
 	ConversationTurns,

package/src/testing.ts

@@ -25,7 +25,10 @@ import type {
 	InteractionContribution,
 } from "./core/discord/interaction-module.ts";
 import { OwnerGuard, ownerRootCommand } from "./core/discord/owner-command.ts";
-import type { PendingConfirmation } from "./core/domain/conversation.ts";
+import type {
+	PendingConfirmation,
+	ReplyFile,
+} from "./core/domain/conversation.ts";
 import { NotLinkedError, PluginError } from "./core/errors.ts";
 import { EventBus } from "./core/events.ts";
 import type { HoldCheck } from "./core/holds.ts";
@@ -48,6 +51,11 @@ import {
 } from "./core/registry/contributions.ts";
 import { resolveProviders } from "./core/registry/providers.ts";
 import { ServiceRegistry } from "./core/registry/services.ts";
+import {
+	attachReplyFile,
+	hasReplyFileScope,
+	withReplyFiles,
+} from "./core/reply-files.ts";
 import { ChannelQueue } from "./core/routing/channel-queue.ts";
 import { ChannelRouter } from "./core/routing/channel-router.ts";
 import {
@@ -203,6 +211,8 @@ export interface TestPluginResult {
 	tools: readonly string[];
 	tiers: ToolTierTable;
 	events: RecordedEvent[];
+	/** Files accepted by successful runTool calls, copied and recorded with their channel. */
+	files: { channel: ChannelKey; file: ReplyFile }[];
 	runTool(
 		name: string,
 		args: Record<string, unknown>,
@@ -233,7 +243,10 @@ function unlinked(part: keyof typeof NOT_LINKED): never {
 const PROBED = new Set(["then", "toJSON", "asymmetricMatch"]);
 
 /** A service the test gave only some members of: reading another names the option that adds it. */
-function partialService(key: ServiceKey<unknown>, given: object): object {
+function partialService<T extends object>(
+	key: ServiceKey<unknown>,
+	given: T,
+): T {
 	return new Proxy(given, {
 		get(target, member, receiver) {
 			if (member in target || typeof member === "symbol" || PROBED.has(member))
@@ -495,6 +508,7 @@ export async function testPlugin(
 	for (const surface of options.surfaces ?? []) await surface.start(deliver);
 	await runtime?.preflight?.();
 	let stopped = false;
+	const files: { channel: ChannelKey; file: ReplyFile }[] = [];
 	return {
 		contribution,
 		holds: linked.holds,
@@ -505,6 +519,7 @@ export async function testPlugin(
 		tools: registry.tools.map((tool) => tool.name),
 		tiers,
 		events,
+		files,
 		async runTool(name, args, runOptions) {
 			const tool = registry.tools.find((item) => item.name === name);
 			if (!tool) throw new PluginError(`tool ${name} is not registered`);
@@ -539,8 +554,23 @@ export async function testPlugin(
 			const execute = registered[0]?.execute;
 			if (!execute)
 				throw new PluginError(`tool ${name} did not register in the session`);
-			const result = await execute("test-call", args);
-			return result.content.map((item) => item.text ?? "").join("\n");
+			const result = await withReplyFiles(
+				surfaces.of(channel)?.supportsFiles === true,
+				async () => {
+					const output = await execute("test-call", args);
+					return {
+						ok: true,
+						text: output.content.map((item) => item.text ?? "").join("\n"),
+					};
+				},
+			);
+			if (!result.ok) throw result.error;
+			for (const file of result.files ?? []) {
+				files.push({ channel, file });
+				// When runTool is used by a fake runtime, forward into the enclosing real turn.
+				if (hasReplyFileScope()) attachReplyFile(file);
+			}
+			return result.text;
 		},
 		async stop() {
 			if (stopped) return;

package/templates/official/release-notice/plugin.test.ts.tmpl

@@ -0,0 +1,248 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENT_SERVER_PLUGIN,
+	AGENT_TEAM_SERVICE,
+	AGENTS,
+	type AgentTeam,
+} from "pi-roundtable";
+import { partial, servicePair, testPlugin } from "pi-roundtable/testing";
+import { createReleaseNotice, noticeText } from "./release-notice.ts";
+
+let dir: string;
+let posted: string[];
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "release-notice-"));
+	posted = [];
+});
+afterEach(() => rm(dir, { recursive: true, force: true }));
+
+const releaseFile = () => join(dir, "release.json");
+const dataDir = () => join(dir, "data");
+const writeRelease = (sha: string, commits: string[]) =>
+	writeFile(releaseFile(), JSON.stringify({ sha, commits }));
+
+/** The plugin over the temporary directory, posting into `posted`; `fail` makes the post throw. */
+async function started(fail = false) {
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: async (text) => {
+				if (fail) throw new Error("the channel is gone");
+				posted.push(text);
+			},
+		}),
+	);
+	const events = harness.contribution.events;
+	return {
+		harness,
+		/** What the host delivers when the agent server's channels are up. */
+		ready: () =>
+			events?.serviceStarted?.({
+				plugin: AGENT_SERVER_PLUGIN,
+				service: AGENT_TEAM_SERVICE,
+				outcome: "ready",
+			}),
+		/** What the host delivers when the shutdown drain ends. */
+		shutdown: (left: string[]) => events?.shutdown?.(left),
+	};
+}
+
+test("a start with no release.json announces nothing", async () => {
+	const run = await started();
+	await run.ready();
+	expect(posted).toEqual([]);
+	await run.harness.stop();
+});
+
+test("a new release is announced once, with its commits", async () => {
+	await writeRelease("abc1234", ["fix: b", "feat: a"]);
+	const first = await started();
+	await first.ready();
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b\n- feat: a"]);
+	await first.harness.stop();
+	// The next start of the same release says nothing.
+	const second = await started();
+	await second.ready();
+	expect(posted).toHaveLength(1);
+	await second.harness.stop();
+	// A different release is announced again.
+	await writeRelease("def5678", ["feat: c"]);
+	const third = await started();
+	await third.ready();
+	expect(posted[1]).toBe("🔄 Updated to `def5678`\n- feat: c");
+	await third.harness.stop();
+});
+
+test("only the agent server's ready event announces", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: async (text) => {
+				posted.push(text);
+			},
+		}),
+	);
+	const serviceStarted = harness.contribution.events?.serviceStarted;
+	await serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "failed",
+	});
+	await serviceStarted?.({
+		plugin: "other",
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	await serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: "other",
+		outcome: "ready",
+	});
+	expect(posted).toEqual([]);
+	await harness.stop();
+});
+
+test("work a shutdown cut short is reported once, after a restart of the same release", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const first = await started();
+	await first.ready();
+	await first.shutdown(["discord:111", "agentgroup:222.infra", "discord:111"]);
+	const second = await started();
+	await second.ready();
+	expect(posted[1]).toBe(
+		"🔄 Restarted (`abc1234`)\n-# Cut short by the restart, still running when the shutdown wait ended: <#111>, <#222>",
+	);
+	await second.harness.stop();
+	const third = await started();
+	await third.ready();
+	expect(posted).toHaveLength(2);
+	await third.harness.stop();
+});
+
+test("a shutdown that left nothing records nothing", async () => {
+	await writeRelease("abc1234", []);
+	const first = await started();
+	await first.ready();
+	await first.shutdown([]);
+	await first.harness.stop();
+	const second = await started();
+	await second.ready();
+	expect(posted).toHaveLength(1);
+	await second.harness.stop();
+});
+
+test("a post that fails leaves the release unannounced, so the next start tries again", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const failing = await started(true);
+	await expect(failing.ready()).rejects.toThrow("the channel is gone");
+	await failing.harness.stop();
+	expect(await Bun.file(join(dataDir(), "announced-release")).exists()).toBe(
+		false,
+	);
+	const next = await started();
+	await next.ready();
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b"]);
+	await next.harness.stop();
+});
+
+test("a release.json that is not a valid description fails with its path and announces nothing", async () => {
+	for (const bad of [
+		"",
+		"{ not json",
+		"null",
+		"[]",
+		"{}",
+		'{"sha":"","commits":[]}',
+		'{"sha":"abc1234"}',
+		'{"sha":"abc1234","commits":"fix: b"}',
+		'{"sha":"abc1234","commits":["fix: b",null,{}]}',
+	]) {
+		await writeFile(releaseFile(), bad);
+		const run = await started();
+		await expect(run.ready()).rejects.toThrow(
+			`${releaseFile()} is not a valid release description`,
+		);
+		await run.harness.stop();
+	}
+	expect(posted).toEqual([]);
+});
+
+test("a recorded list that is not a list of strings fails with its path", async () => {
+	await writeRelease("abc1234", []);
+	await mkdir(dataDir(), { recursive: true });
+	await writeFile(join(dataDir(), "aborted-on-shutdown.json"), '["a", 1]');
+	const run = await started();
+	await expect(run.ready()).rejects.toThrow("is not a list of strings");
+	await run.harness.stop();
+});
+
+test("a shutdown during the post is not lost, and one that ends before the next start adds to the unannounced", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	let finish = () => {};
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: (text) =>
+				new Promise<void>((resolve) => {
+					posted.push(text);
+					finish = resolve;
+				}),
+		}),
+	);
+	const events = harness.contribution.events;
+	const announcing = events?.serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	// The host shuts down while the notice is still being posted.
+	while (posted.length === 0) await Bun.sleep(1);
+	await events?.shutdown?.(["discord:111"]);
+	finish();
+	await announcing;
+	await events?.shutdown?.(["discord:333"]);
+	await harness.stop();
+	const next = await started();
+	await next.ready();
+	expect(posted[1]).toContain("<#111>, <#333>");
+	await next.harness.stop();
+});
+
+test("without an announce option the notice goes to the agent team", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const harness = await testPlugin(
+		createReleaseNotice({ releaseFile: releaseFile(), dataDir: dataDir() }),
+		{
+			services: [
+				servicePair(AGENTS, {
+					team: partial<AgentTeam>({
+						announce: async (text) => {
+							posted.push(text);
+						},
+					}),
+				}),
+			],
+		},
+	);
+	await harness.contribution.events?.serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b"]);
+	await harness.stop();
+});
+
+test("a channel key that is not Discord's is named as it is", () => {
+	expect(noticeText({ sha: "a", commits: [] }, false, ["slack:C1"])).toContain(
+		"slack:C1",
+	);
+});

package/templates/official/release-notice/plugin.ts

@@ -0,0 +1,194 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+	AGENT_SERVER_PLUGIN,
+	AGENT_TEAM_SERVICE,
+	AGENTS,
+	type AgentServer,
+	definePlugin,
+} from "pi-roundtable";
+
+/**
+ * What a deploy writes as `release.json`: the commit the running release was built from, and
+ * the subjects of the commits it added since the release that ran before, newest first.
+ */
+export interface ReleaseInfo {
+	sha: string;
+	commits: string[];
+}
+
+export interface ReleaseNoticeOptions {
+	/** The file a deploy writes with the release's description; default `release.json` in the working directory. A start with no such file announces nothing. */
+	releaseFile?: string;
+	/** Where the plugin keeps what it has announced and what a shutdown cut short; default `./data`, the data directory a new project's config names. */
+	dataDir?: string;
+	/** Posts the announcement; default the coordinator's channel, through the agent server. It throws to say the post failed, and the announcement is then tried again at the next start. */
+	announce?: (text: string) => Promise<void>;
+}
+
+const ANNOUNCED = "announced-release";
+const ABORTED = "aborted-on-shutdown.json";
+
+async function readText(path: string): Promise<string | undefined> {
+	return readFile(path, "utf8").catch((error: NodeJS.ErrnoException) => {
+		if (error.code === "ENOENT") return undefined;
+		throw error;
+	});
+}
+
+/** A list of strings from JSON, such as the aborted channels; anything else fails with the file's path. */
+function parseStrings(text: string, path: string): string[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new Error(`${path} is not a JSON list`, { cause: error });
+	}
+	if (!isStrings(parsed)) throw new Error(`${path} is not a list of strings`);
+	return parsed;
+}
+
+const isStrings = (value: unknown): value is string[] =>
+	Array.isArray(value) && value.every((item) => typeof item === "string");
+
+/** `release.json`'s content; anything but a non-empty `sha` and a list of commit subjects fails with the file's path. */
+function parseRelease(text: string, path: string): ReleaseInfo {
+	const invalid = (reason: string, cause?: unknown) =>
+		new Error(`${path} is not a valid release description: ${reason}`, {
+			cause,
+		});
+	let parsed: Partial<ReleaseInfo> | null;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw invalid("not JSON", error);
+	}
+	if (typeof parsed?.sha !== "string" || parsed.sha === "")
+		throw invalid("needs a non-empty sha");
+	if (!isStrings(parsed.commits))
+		throw invalid("commits is not a list of strings");
+	return { sha: parsed.sha, commits: parsed.commits };
+}
+
+/** `discord:<id>` and `agentgroup:<id>.<agent>` as a Discord channel mention; any other key as it is. */
+function channelMention(key: string): string {
+	const id =
+		/^discord:(\d+)$/.exec(key)?.[1] ?? /^agentgroup:(\d+)\./.exec(key)?.[1];
+	return id ? `<#${id}>` : key;
+}
+
+/** The announcement: the new version and its commits, or a plain restart, then any channels the previous shutdown cut short. */
+export function noticeText(
+	release: ReleaseInfo,
+	updated: boolean,
+	aborted: string[],
+): string {
+	const lines = updated
+		? [
+				`🔄 Updated to \`${release.sha}\``,
+				...release.commits.map((subject) => `- ${subject}`),
+			]
+		: [`🔄 Restarted (\`${release.sha}\`)`];
+	if (aborted.length > 0)
+		lines.push(
+			`-# Cut short by the restart, still running when the shutdown wait ended: ${[...new Set(aborted.map(channelMention))].join(", ")}`,
+		);
+	return lines.join("\n");
+}
+
+/** Posts through the agent server's team, read when the first notice is due, since the server is linked after setup. */
+function throughTeam(agents: () => AgentServer) {
+	return (text: string) => agents().team.announce(text);
+}
+
+/**
+ * The plugin, with where the release is described, where its state is kept, and where the
+ * announcement goes replaceable. After the agent server is up it announces once when the
+ * running release differs from the one last announced, or when the previous shutdown cut work
+ * short; at shutdown it records the channels whose work the drain gave up on.
+ */
+export function createReleaseNotice(options: ReleaseNoticeOptions = {}) {
+	const releaseFile = options.releaseFile ?? "release.json";
+	const dataDir = options.dataDir ?? "./data";
+	const announcedPath = join(dataDir, ANNOUNCED);
+	const abortedPath = join(dataDir, ABORTED);
+
+	// The shutdown's record and an announcement's acknowledgement both rewrite the state files, and
+	// the host does not wait for a start's handlers before it shuts down, so they take turns.
+	let turn: Promise<unknown> = Promise.resolve();
+	const exclusive = <T>(work: () => Promise<T>): Promise<T> => {
+		const run = turn.then(work);
+		turn = run.catch(() => undefined);
+		return run;
+	};
+
+	async function readAborted(): Promise<string[]> {
+		const text = await readText(abortedPath);
+		return text === undefined ? [] : parseStrings(text, abortedPath);
+	}
+
+	/** The announcement due now and what acknowledges it, or undefined when nothing is due. */
+	function pending() {
+		return exclusive(async () => {
+			const text = await readText(releaseFile);
+			if (text === undefined) return undefined;
+			const release = parseRelease(text, releaseFile);
+			const announced = (await readText(announcedPath))?.trim();
+			const aborted = await readAborted();
+			const updated = announced !== release.sha;
+			if (!updated && aborted.length === 0) return undefined;
+			return {
+				text: noticeText(release, updated, aborted),
+				// A shutdown may add channels while the post is in flight: only the ones it named are cleared.
+				done: () =>
+					exclusive(async () => {
+						await mkdir(dataDir, { recursive: true });
+						await writeFile(announcedPath, release.sha);
+						const rest = (await readAborted()).slice(aborted.length);
+						if (rest.length > 0)
+							await writeFile(abortedPath, JSON.stringify(rest));
+						else await rm(abortedPath, { force: true });
+					}),
+			};
+		});
+	}
+
+	return definePlugin({
+		name: "release-notice",
+		setup: ({ logger, services }) => {
+			const announce = options.announce ?? throughTeam(services.lazy(AGENTS));
+			return {
+				events: {
+					// The agent server's team service is ready once its channels are up, so the notice posts after it.
+					serviceStarted: async ({ plugin, service, outcome }) => {
+						if (
+							plugin !== AGENT_SERVER_PLUGIN ||
+							service !== AGENT_TEAM_SERVICE ||
+							outcome !== "ready"
+						)
+							return;
+						const notice = await pending();
+						if (!notice) return;
+						await announce(notice.text);
+						await notice.done();
+						logger.info("release announced");
+					},
+					// The drain ended with work still running: the next start says it was cut short.
+					shutdown: (left) =>
+						left.length === 0
+							? undefined
+							: exclusive(async () => {
+									const earlier = await readAborted();
+									await mkdir(dataDir, { recursive: true });
+									await writeFile(
+										abortedPath,
+										JSON.stringify([...earlier, ...left]),
+									);
+								}),
+				},
+			};
+		},
+	});
+}
+
+export const releaseNotice = createReleaseNotice();