pi-roundtable 0.9.10 → 0.9.12

package/CHANGELOG.md

@@ -5,6 +5,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.12] - 2026-10-11
+
+### Added
+
+- `generate_image({ prompt, reference_paths? })`: a core session tool, offered to agent and owner sessions only when a plugin fills the `images` provider, that draws a new picture from a description, saves it under `<scratch dir or workspace>/drawings/`, attaches it to the reply, and names the saved path. Up to 4 reference images (PNG, JPEG, WebP or GIF by content, 20 MiB each, 40 MiB together) resolve inside the workspace or the scratch dir like `attach_file` paths. A provider error is a tool error with its message. Owner-only by default; the agents' prompt names it only when offered.
+- `ImageDrawer` takes an optional third argument `{ signal? }`, the asking turn's abort signal; an existing two-argument drawer still fits.
+
+## [0.9.11] - 2026-10-11
+
+### Added
+
+- `ToolTurn.client`, `TurnRequest.client`, `ConversationTurnInput.client` and `SessionContext.client()`: what the client that started a turn can do for its tools, as a `ClientPort` (`names`, and `call(name, args, options?)` with `ClientCallOptions`: `{ timeoutMs?, maxValueBytes?, signal? }`). A transport that carries a client able to run functions for a tool, such as the browser extension of a web chat, provides one with `context.turns.run({ ..., client })`; the runtime keeps it with the turn and clears it when the turn ends. `call` never rejects for a transport problem: it resolves `ClientCallResult`, `{ ok: true, value, parts }` with `ClientPart`s (`{ mimeType, data }`, such as a screenshot) or `{ ok: false, error, message }` where `error` is a `ClientCallError`: `no_client`, `refused`, `timeout`, `cancelled`, `disconnected`, `too_large`, `busy` or `failed`. One call is open on a client at a time. The core adds the turn's signal to every call, so stopping the turn cancels a call in flight. A turn whose transport gives none (Discord, a schedule, an agent's turn, the CLI) leaves it undefined, and `SessionContext.client` is optional on the type so a context built before this still type-checks.
+- `ToolOutput` (`string | { text, images? }`): a tool's `run` may return text with images, which reach the model as image parts of the tool result. Each image goes through the same checks as a user's attachment (png, jpeg, gif or webp, size and pixel limits, at most 4, a large one downscaled); one that fails is the tool's error result, not a provider rejection.
+- `ToolTurn.attachments?()` (optional, so a `ToolTurn` built by hand still type-checks; the turns the core builds always have it; `ToolAttachmentInfo`: `{ file, name, contentType, size, addedAt }`): the files someone attached to the conversation, the newest first, only the names `ToolTurn.attachment()` opens; a session without an attachment store lists none.
+- `testPlugin().runTool` takes `client` in its options (a `ClientPort` the test fakes), and `testPlugin().images` records the images a successful `runTool` returned.
+
 ## [0.9.10] - 2026-10-10
 
 ### Added

package/docs/plugins.md

@@ -586,17 +586,29 @@ The host logs counts only (`files`, `bytes`, `unattributedBytes`), never a file
 ### `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, an abort signal, `workspace`, `attachFile`, and `attachment`.
+`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `workspace`, `attachFile`, `attachment`, `attachments`, `origin`, and `client`.
 `turn.workspace` is `{ workspace, scratchDir? }` in a session with a shared workspace (an agent's), the same roots as `SessionContext.workspace`, and undefined elsewhere: a tool that makes a file can save it there, under the scratch dir when there is one, and name its path, so the model sends it on with `attach_file` or a `discord_send_message` file `path` instead of carrying its bytes.
-It returns the text the model reads.
+It returns the text the model reads, or `{ text, images? }` (`ToolOutput`) to show the model images beside it: each image is `{ mimeType, data: Uint8Array }` and reaches the model as an image part of the tool result.
 `turn.origin` is where the turn's request came from, as the transport that carried it reported it, and undefined when the channel gives none: the web chat sets it to the browser origin its connection opened with (`https://chat.example.com`, `chrome-extension://<id>`), a Discord message, a schedule or an agent's turn leave it undefined.
 Only a channel's transport sets it, never the message text or the model, so a tool may write it on a record it creates, such as an issue's source line; a tool that needs it fails closed when it is undefined.
 A claim passes it to `context.turns.run` as `origin`, and the hold of the same call sees it too, since `hold` receives the same `ToolTurn`.
 
 `turn.attachment(file)` opens a file someone attached to the conversation, by the name the turn's `## Attachments` block lists, and returns `{ file, name, contentType, size, bytes() }`: a tool passes a user's file on without the model carrying its bytes.
 Only the conversation's own files open; a path, a hidden name, or a missing file throws a `ToolRefusal` the model reads, and so does a file the host's [retention period](#retention-removing-used-files-after-a-period) removed, which says so.
+`turn.attachments?.()` lists those files, the newest first, as `{ file, name, contentType, size, addedAt }` (`ToolAttachmentInfo`): the names `attachment` opens and nothing else; a session that keeps no attachments lists none. The turns the core builds always have it; it is optional on the type for code that builds a turn by hand.
 Throw `ToolRefusal` for a call the model should correct; any other error fails the call.
 
+##### `turn.client`: asking the party that started the turn
+
+Some transports carry a client that can do something for a tool: the web chat's browser extension can read the page the person has open.
+`turn.client` is that client's `ClientPort` when the turn's transport provides one and the client declared it, and undefined otherwise (a Discord message, a schedule, an agent's turn, and a web chat connection that declared nothing have none), so a tool that needs it fails closed with a `ToolRefusal` when it is undefined.
+`client.names` lists the functions the client declared, and `client.call(name, args, { timeoutMs?, maxValueBytes? })` asks it to run one.
+The call never rejects for a transport problem: it resolves `{ ok: true, value, parts }`, with the value the client answered with and its binary `parts` (`{ mimeType, data }`, such as a screenshot), or `{ ok: false, error, message }` where `error` is `no_client`, `refused`, `timeout`, `cancelled`, `disconnected`, `too_large`, `busy`, or `failed`.
+One call is open on a client at a time: a second one made meanwhile resolves `busy`, so make calls one after another.
+The core gives every call the turn's `signal`, so stopping the turn cancels the call in flight (`cancelled`) and the tool need not handle it.
+The value and the parts come from the client, outside the host, so a tool treats them as untrusted data: it checks their shape, and passes images on as `ToolOutput` images rather than trusting their names or types.
+The transport sets `client` and bounds each call (its default timeout, its ceiling and its size limits); a claim passes it to `context.turns.run` as `client`.
+
 <!-- example: examples/tools.ts -->
 ```ts
 import { definePlugin, defineTool, ToolRefusal } from "pi-roundtable";
@@ -681,6 +693,8 @@ A Pi package should use the host's peer dependency on `pi-roundtable`, not bundl
 Transient `SessionContext.runTask` tasks return only text and cannot attach to their parent's reply.
 
 The model attaches a file it already has on disk with the core's `attach_file({ path, filename? })`. A session with a workspace (`SessionContext.workspace`, an agent's) registers it; the path must resolve, symlinks followed, inside the workspace or the scratch dir, a relative path resolves in the workspace, and `filename` defaults to the path's base name. It queues the file with `attachReplyFile`, so `REPLY_FILE_LIMITS` apply and a surface without reply files refuses it as a tool error; its result tells the model the file will appear with its reply. It holds nothing, since it only posts in the channel the turn answers in, and its tier defaults to the owner, like any tool the core's table does not name.
+
+With an `images` provider, agent and owner sessions also offer the core's `generate_image({ prompt, reference_paths? })`, which draws a new picture from a description (`prompt`, at most 4,000 characters). `reference_paths` lists up to 4 local images, checked like `attach_file` paths (inside the workspace or the scratch dir, symlinks followed, regular files only), each a PNG, JPEG, WebP or GIF by content, at most 20 MiB each and 40 MiB together; a refused reference is a tool error before the provider is called. It passes them to the provider as `ReferenceImage`s with the turn's signal, saves the picture under `<scratch dir or workspace>/drawings/generated-<ISO time>.<ext>`, and attaches it with `attachReplyFile`; when it cannot be attached the file is kept and the result says so. The result names the saved path, never the bytes, so the model can send it on or edit it. A provider error, such as a refusal, is a tool error carrying the provider's message. It holds nothing, and its tier defaults to the owner; `toolTiers` lowers it. The agents' prompt mentions it only when it is offered.
 The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?, limits?)`) lists each file it sends by path with the file's size now, never its bytes, and shows an input within `limits.totalChars` (1,500) whole; a longer input has its string values cut, longest first and never below `limits.valueChars` (200), to their start plus `… [N chars]` (N in code points) until it fits, and if it still does not, the rest is dropped and the keys no longer shown are listed. `approvalDetails(call, workspace?)` gives the same call as data (`{ action, tool, input, files? }`, the whole input, files as `{ path, bytes? }`); the gate passes it to `Prompts.confirm` as `details`, for a surface that is not text.
 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.
@@ -1267,10 +1281,11 @@ An unknown or misspelled slot stops startup with an error listing the valid name
 | Slot | The core's default | Your replacement |
 |---|---|---|
 | `judge` | Asks the configured model small questions: does this reply approve the held actions, how hard is this turn, which agents does this group message concern | An object with `askYesNo`, `askChoice`, and `askScore` |
-| `images` | No drawing; each agent gets an avatar generated from its display name | `async (prompt, references) => bytes` returning PNG bytes |
+| `images` | No drawing; each agent gets an avatar generated from its display name, and no session offers `generate_image` | `async (prompt, references, options?) => bytes` returning PNG, JPEG, WebP or GIF bytes; `options.signal` aborts with the turn that asked |
 | `runtime` | None: the runtime plugin builds the Pi runtime itself | `(deps) => runtime`, an [`AgentRuntime`](#the-runtime-slot-replace-pi) that runs every conversation |
 
-When no `images` provider is configured, `agent_create` has no `avatar_prompt` parameter and `agent_avatar` is unavailable.
+A filled `images` slot draws agents' avatars and also powers the core's [`generate_image`](#attach-files-to-the-agents-reply) tool.
+When no `images` provider is configured, `agent_create` has no `avatar_prompt` parameter, `agent_avatar` is unavailable, and no session offers `generate_image`.
 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.
@@ -1865,6 +1880,7 @@ The factory gets the session's `SessionContext`, fixed when the session is made:
 - `addressee` is whom tool descriptions should name: the primary owner exactly as configured in their own private conversation, another person by their name and pronouns (their name alone when they gave none), and `THE_SPEAKER` in a shared conversation, or a private one of someone the host knows by no name yet.
 - `memory` is `"none"` for a persona that declares it, and `"speaker"` otherwise; a memory tool of your own loads nothing for `"none"`. A task the session runs with `runTask` keeps its conversation's `memory`.
 - `speaker()` is the running turn's speaker, undefined between turns; a tool reads it when it runs, never when the session is made, since a session outlives the turn it is built in.
+- `client()` is what the client that started the running turn can do for its tools, as `TurnRequest.client` says, and undefined between turns and for a turn whose transport gives none; it is optional on the type so a context built before 0.9.11 still type-checks.
 - `origin()` is where the running turn's request came from, as `TurnRequest.origin` says, and undefined between turns and for a turn whose transport gives none; read it when the tool runs, like `speaker()`. It is optional on the type so a context built before 0.9.10 still type-checks.
 
 The core's Jev compactor is one such extension:
@@ -2017,7 +2033,7 @@ Call `context.turns.run(input)` inside your claim's queue task to run a turn in
 It shows typing and the stop control on the channel's surface, runs the turn, and emits `turnStarted` and `turnEnded` with the turn's `kind`.
 It catches runtime errors as failed results and posts the answer, failure notice, or stopped notice through the surface.
 Supply `reply(result)` to handle the reply yourself.
-`input` has `channel`, `kind`, `text`, `speaker`, and optionally `origin` (where the request came from, as your claim's transport knows it, such as a connection's browser origin; tools read it as `turn.origin`, so never fill it from message text), `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
+`input` has `channel`, `kind`, `text`, `speaker`, and optionally `origin` (where the request came from, as your claim's transport knows it, such as a connection's browser origin; tools read it as `turn.origin`, so never fill it from message text), `client` (a `ClientPort` for what the client that started the turn can do, which tools read as `turn.client`; only your transport provides one), `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
 It rejects with `NotLinkedError` during `setup`, and with a `PluginError` on a host whose runtime plugin has not provided a runtime.
 
 Before each turn runs, `context.turns.run` records its conversation in the host's registry, `CONVERSATIONS`: at the first turn its key, surface, kind, visibility, owner, and title, and at every later turn only that it was active.
@@ -2960,7 +2976,8 @@ It returns:
 | `contribution` | What the plugin added, as the host would collect it: `tools`, `prompt`, `seeds`, `events`, `services`, `http`, and the rest |
 | `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?, scratchDir? })` returns the description of a call that must be approved first, or `undefined`; `holds.inTurn(tool, input, context, turn)` asks them as a turn does, and returns a promise when a hold looks things up |
-| `runTool(name, args, { speaker, origin, channel, workspace }?)` | 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; `origin` is the turn's `turn.origin`, and `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
+| `runTool(name, args, { speaker, origin, client, channel, workspace }?)` | 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; `origin` is the turn's `turn.origin`, `client` its `turn.client` (a `ClientPort` the test fakes), and `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
+| `images` | The images successful `runTool` calls returned as `ToolOutput` images, recorded as `{ channel, image: { mimeType, data } }` |
 | `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 |
@@ -3365,6 +3382,11 @@ Import from the entries listed below; source area files are internal.
 | `ChannelClaim` | `pi-roundtable` | type |
 | `ChannelKey` | `pi-roundtable` | type |
 | `ChatSurface` | `pi-roundtable` | type |
+| `ClientCallError` | `pi-roundtable` | type |
+| `ClientCallOptions` | `pi-roundtable` | type |
+| `ClientCallResult` | `pi-roundtable` | type |
+| `ClientPart` | `pi-roundtable` | type |
+| `ClientPort` | `pi-roundtable` | type |
 | `ConfigError` | `pi-roundtable` | value |
 | `ContextUse` | `pi-roundtable` | type |
 | `Contribution` | `pi-roundtable` | type |
@@ -3527,7 +3549,9 @@ Import from the entries listed below; source area files are internal.
 | `Tier` | `pi-roundtable` | type |
 | `TierConfig` | `pi-roundtable` | type |
 | `ToolAttachment` | `pi-roundtable` | type |
+| `ToolAttachmentInfo` | `pi-roundtable` | type |
 | `ToolContribution` | `pi-roundtable` | type |
+| `ToolOutput` | `pi-roundtable` | type |
 | `ToolRefusal` | `pi-roundtable` | value |
 | `ToolSelection` | `pi-roundtable` | type |
 | `ToolSpec` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.9.10",
+	"version": "0.9.12",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/agents/agent-prompt.ts

@@ -25,6 +25,8 @@ export function agentSystemPrompt(input: {
 	speaker?: Speaker;
 	/** Whether agents can redraw avatars; false without an image provider. Default true. */
 	avatars?: boolean;
+	/** Whether the session offers generate_image; true only with an image provider. Default false. */
+	images?: boolean;
 }): string {
 	const { agent, coordinator, shared, workDir, owner, shellUser, group } =
 		input;
@@ -37,7 +39,7 @@ export function agentSystemPrompt(input: {
 		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} Discord agent server. Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
 		roleText(agent, coordinator, who),
 		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; ${input.avatars === false ? "" : "agent_avatar redraws an avatar; "}schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
-		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}.${input.scratchDir ? ` Write temporary files under the scratch dir ${input.scratchDir} ($TMPDIR), not elsewhere in /tmp.` : ""} Commands that are destructive or change the system, and writes outside the workspace${input.scratchDir ? " and the scratch dir" : ""}, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm. To show a file you have, attach it to your reply with attach_file or give its path to discord_send_message; never read an image or base64 a file to send it.`,
+		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}.${input.scratchDir ? ` Write temporary files under the scratch dir ${input.scratchDir} ($TMPDIR), not elsewhere in /tmp.` : ""} Commands that are destructive or change the system, and writes outside the workspace${input.scratchDir ? " and the scratch dir" : ""}, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm. To show a file you have, attach it to your reply with attach_file or give its path to discord_send_message; never read an image or base64 a file to send it.${input.images ? " To make a new picture, describe it to generate_image, which saves it and attaches it to your reply." : ""}`,
 	];
 	if (group) {
 		const others = group.members

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

@@ -149,6 +149,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			shellUser,
 			...(scratchDir ? { scratchDir } : {}),
 			avatars: this.#avatars(),
+			images: this.#avatars(),
 			...(group
 				? {
 						group: {

package/src/core/attachments/tool-attachment.ts

@@ -1,5 +1,6 @@
+import { stat } from "node:fs/promises";
 import { join } from "node:path";
-import { RECORDS } from "./attachment-dir.ts";
+import { listDir, RECORDS } from "./attachment-dir.ts";
 import { expiredMessage, wasExpired } from "./attachment-expiry.ts";
 import { isAttachmentName, plainText } from "./attachment-name.ts";
 
@@ -15,6 +16,18 @@ export interface ToolAttachment {
 	bytes(): Promise<Uint8Array>;
 }
 
+/** A file someone attached to the conversation, as a tool lists it. */
+export interface ToolAttachmentInfo {
+	/** The file name inside the conversation's attachment store; what `## Attachments` lists. */
+	file: string;
+	/** The name the person gave it, when the core recorded one; else the file name. */
+	name: string;
+	contentType: string;
+	size: number;
+	/** When the file was saved, as an ISO time. */
+	addedAt: string;
+}
+
 /** A name that is no attachment of the conversation, or a file that is not there. */
 export class AttachmentLookupError extends Error {
 	override name = "AttachmentLookupError";
@@ -72,3 +85,32 @@ export async function openAttachment(
 		},
 	};
 }
+
+/**
+ * The files of a conversation's attachment store that a tool may open, the newest first. Only
+ * names an attachment can have are listed: no hidden entry, no directory. A directory that is not
+ * there lists nothing.
+ */
+export async function listAttachments(
+	dir: string,
+): Promise<ToolAttachmentInfo[]> {
+	const listed: ToolAttachmentInfo[] = [];
+	for (const file of await listDir(dir)) {
+		if (!isAttachmentName(file)) continue;
+		const info = await stat(join(dir, file)).catch(() => undefined);
+		if (!info?.isFile()) continue;
+		const opened = await openAttachment(dir, file).catch(() => undefined);
+		if (!opened) continue;
+		listed.push({
+			file,
+			name: opened.name,
+			contentType: opened.contentType,
+			size: opened.size,
+			addedAt: info.mtime.toISOString(),
+		});
+	}
+	return listed.sort(
+		(a, b) =>
+			b.addedAt.localeCompare(a.addedAt) || a.file.localeCompare(b.file),
+	);
+}

package/src/core/contract/providers.ts

@@ -56,10 +56,14 @@ export interface ReferenceImage {
 	mimeType: string;
 }
 
-/** Draws one image from a prompt and reference images; returns PNG or other decodable bytes. */
+/**
+ * Draws one image from a prompt and reference images; returns PNG or other decodable bytes.
+ * `options.signal`, when given, aborts with the turn that asked; a drawer may ignore it.
+ */
 export type ImageDrawer = (
 	prompt: string,
 	references: readonly ReferenceImage[],
+	options?: { signal?: AbortSignal },
 ) => Promise<Uint8Array>;
 
 /** The replaceable parts the core runs on; a plugin provides at most the ones it replaces. */

package/src/core/define.ts

@@ -1,12 +1,20 @@
 import type { Static, TObject } from "typebox";
-import type { ToolAttachment } from "./attachments/tool-attachment.ts";
+import type {
+	ToolAttachment,
+	ToolAttachmentInfo,
+} from "./attachments/tool-attachment.ts";
+import type { ClientPort } from "./domain/client.ts";
 import type { ReplyFile } from "./domain/conversation.ts";
 import { PluginError } from "./errors.ts";
 import { type HoldRule, isPromise } from "./holds.ts";
 import { messages } from "./i18n/index.ts";
 import { type RoundtablePlugin, refuseRemovedFields } from "./plugin.ts";
 import type { AgentTurnScope, ChannelKey, SessionTool } from "./sessions.ts";
-import { toolError, toolText } from "./shared/tool-result.ts";
+import {
+	type ToolOutput,
+	toolError,
+	toolOutput,
+} from "./shared/tool-result.ts";
 import { type Speaker, TIERS, type Tier } from "./speakers.ts";
 import { toolTurn } from "./tool-turn.ts";
 
@@ -34,6 +42,14 @@ export interface ToolTurn {
 	 * when it is undefined.
 	 */
 	origin?: string;
+	/**
+	 * What the client that started the turn can do for this tool, such as run a function in the
+	 * browser the person chats from; undefined for a turn whose transport gives none, such as a
+	 * Discord message or a schedule, or whose client declared nothing. Every call carries this turn's
+	 * `signal`, so stopping the turn cancels a call in flight. A tool that needs one fails closed
+	 * when it is undefined.
+	 */
+	client?: ClientPort;
 	/**
 	 * The session's shared workspace and scratch dir, where a tool may save a file for the model to
 	 * pass on by path; undefined for a session without a workspace.
@@ -48,6 +64,12 @@ export interface ToolTurn {
 	 * refuses every call.
 	 */
 	attachment(file: string): Promise<ToolAttachment>;
+	/**
+	 * The files someone attached to this conversation, the newest first; only names that
+	 * `attachment` opens. A session without an attachment store lists none. The turns the core builds
+	 * always have it; code that builds a turn by hand may leave it out.
+	 */
+	attachments?(): Promise<readonly ToolAttachmentInfo[]>;
 }
 
 /**
@@ -85,9 +107,11 @@ export interface ToolSpec<Schema extends TObject> {
 		args: Static<Schema>,
 		turn: ToolTurn,
 	) => string | undefined | Promise<string | undefined>;
-	run(args: Static<Schema>, turn: ToolTurn): Promise<string> | string;
+	run(args: Static<Schema>, turn: ToolTurn): Promise<ToolOutput> | ToolOutput;
 }
 
+export type { ToolAttachmentInfo, ToolOutput };
+
 /** A tool a plugin adds, as `defineTool` builds it. */
 export interface ToolContribution {
 	readonly name: string;
@@ -142,7 +166,7 @@ export function defineTool<Schema extends TObject>(
 					parameters: spec.parameters,
 					execute: async (_toolCallId, params, signal) => {
 						try {
-							return toolText(
+							return toolOutput(
 								await spec.run(
 									params as Static<Schema>,
 									toolTurn(context, signal),

package/src/core/domain/client.ts

@@ -0,0 +1,61 @@
+/** A binary piece of a client call's result, such as a screenshot. */
+export interface ClientPart {
+	mimeType: string;
+	data: Uint8Array;
+}
+
+/** Why a client call did not return a value. */
+export type ClientCallError =
+	/** The turn has no client, or its client is gone. */
+	| "no_client"
+	/** The client declined the call. */
+	| "refused"
+	/** The client did not answer in time. */
+	| "timeout"
+	/** The turn was stopped, or the caller's signal aborted, before the client answered. */
+	| "cancelled"
+	/** The client's connection closed before it answered. */
+	| "disconnected"
+	/** The client's answer passed the size the transport accepts. */
+	| "too_large"
+	/** A call is already open on this client; make calls one at a time. */
+	| "busy"
+	/** The client tried and failed, or answered with something that is not a result. */
+	| "failed";
+
+/** What a client call comes to: the value the client answered with and its binary parts, or why not. */
+export type ClientCallResult =
+	| { ok: true; value: unknown; parts: readonly ClientPart[] }
+	| { ok: false; error: ClientCallError; message: string };
+
+/** How one client call is bounded. */
+export interface ClientCallOptions {
+	/** How long to wait for the client's answer; the transport has a default and its own ceiling. */
+	timeoutMs?: number;
+	/** The most bytes of JSON the answer's value may take; the transport has a default and its own ceiling. */
+	maxValueBytes?: number;
+	/**
+	 * Cancels the call when it aborts: the client is told, and the call resolves `cancelled`. A tool
+	 * need not pass the turn's signal; the core adds it to every call.
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * What the client that started a turn can do for its tools, such as a browser extension running a
+ * function on the page the person has open. Only the transport that carries the turn provides one.
+ */
+export interface ClientPort {
+	/** The names of the functions the client declared it can run. */
+	readonly names: readonly string[];
+	/**
+	 * Asks the client to run `name` with `args`. It never rejects for a transport problem: a failure
+	 * resolves `{ ok: false }`. One call is open at a time; another call meanwhile resolves `busy`.
+	 * The value and the parts come from the client, so a tool treats them as untrusted data.
+	 */
+	call(
+		name: string,
+		args: unknown,
+		options?: ClientCallOptions,
+	): Promise<ClientCallResult>;
+}

package/src/core/domain/ports.ts

@@ -1,6 +1,7 @@
 import type { AgentTurnScope, TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import type { TurnAttachments } from "./attachment.ts";
+import type { ClientPort } from "./client.ts";
 import type { ChannelKey } from "./conversation.ts";
 import type { InterimPosts } from "./interim.ts";
 import type { TurnProgress } from "./progress.ts";
@@ -37,6 +38,12 @@ export interface TurnRequest {
 	 * as `ToolTurn.origin`.
 	 */
 	origin?: string;
+	/**
+	 * What the client that started the turn can do for its tools, such as run a function in a
+	 * browser; a tool reads it as `ToolTurn.client`. A channel whose transport has no such client
+	 * leaves it out. Only a channel's transport provides one, never the message text or the model.
+	 */
+	client?: ClientPort;
 	/**
 	 * Who the conversation belongs to, as the host records it: `private` to one principal, or
 	 * `shared` by whoever its claim admits, which it is taken to be when absent. A private

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

@@ -5,6 +5,7 @@ import type {
 	ConversationVisibility,
 } from "../conversations/conversation-registry.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
+import type { ClientPort } from "../domain/client.ts";
 import type { TurnResult } from "../domain/conversation.ts";
 import type { TurnConversation } from "../domain/ports.ts";
 import type { TurnProgress } from "../domain/progress.ts";
@@ -35,6 +36,11 @@ export interface ConversationTurnInput {
 	 * transport gives none, and never fill it from message text.
 	 */
 	origin?: string;
+	/**
+	 * What the client that started the turn can do for its tools, as the claim's transport knows it;
+	 * tools read it as `ToolTurn.client`. Leave it out for a turn the transport gives none.
+	 */
+	client?: ClientPort;
 	/** Files and images the message carries. */
 	attachments?: TurnAttachments;
 	/** The turn's tools; by default the plugins' `agentSelection`, read at the turn. */
@@ -191,6 +197,7 @@ export function conversationTurns(
 								text: input.text,
 								speaker,
 								...(input.origin === undefined ? {} : { origin: input.origin }),
+								...(input.client === undefined ? {} : { client: input.client }),
 								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }

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

@@ -24,7 +24,6 @@ import { promptScopeOf } from "../interactions/prompts.ts";
 import { MEMORY_TOOLS } from "../modules/memory/owner-memory.ts";
 import { withoutReplyFiles } from "../reply-files.ts";
 import type { TransientTask } from "../sessions.ts";
-import type { Speaker, Tier } from "../speakers.ts";
 import { type ToolTiers, toolsForTier, toolTiers } from "../tool-tiers.ts";
 import { AbortGuard } from "./abort-guard.ts";
 import { bridgeTurnRefusal, chosenAgentModel } from "./bridge-guard.ts";
@@ -36,6 +35,7 @@ import { interimPoster } from "./interim-text.ts";
 import { preflightTools } from "./preflight-tools.ts";
 import { PromptSlot, workTimeout } from "./prompt-slot.ts";
 import { carriesMemory, recordMemoryTurn } from "./reader-history.ts";
+import type { RunningTurn } from "./running-turn.ts";
 import type { PiAgentRuntimeOptions, TurnMessage } from "./runtime-types.ts";
 import { archiveSessions } from "./session-archive.ts";
 import {
@@ -71,11 +71,8 @@ export class PiAgentRuntime implements AgentRuntime {
 	readonly #tiers: ToolTiers;
 	readonly #factory: SessionFactory;
 	readonly #sessions: ConversationSessions;
-	/** The tier, speaker and origin of each conversation's running turn. */
-	readonly #turns = new Map<
-		ChannelKey,
-		{ tier: Tier; speaker: Speaker; origin?: string; withheld: boolean }
-	>();
+	/** The tier, speaker, origin and client of each conversation's running turn. */
+	readonly #turns = new Map<ChannelKey, RunningTurn>();
 	/** Each conversation's turn in progress, which the owner may steer or stop. */
 	readonly #running = new Map<ChannelKey, SteerableRun>();
 	readonly #memoryTurns = new Map<ChannelKey, () => void>();
@@ -88,6 +85,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		this.#factory = new SessionFactory(options, {
 			speaker: (channel) => this.#turns.get(channel)?.speaker,
 			origin: (channel) => this.#turns.get(channel)?.origin,
+			client: (channel) => this.#turns.get(channel)?.client,
 			withholdsMemory: (channel) => this.#turns.get(channel)?.withheld === true,
 			runTask: (scope, task) => this.#runTask(scope, task),
 		});
@@ -197,6 +195,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			tier,
 			speaker: request.speaker,
 			...(request.origin === undefined ? {} : { origin: request.origin }),
+			...(request.client === undefined ? {} : { client: request.client }),
 			withheld,
 		});
 		const missing = wanted.filter((name) => !registered.has(name));

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

@@ -0,0 +1,14 @@
+import type { ClientPort } from "../domain/client.ts";
+import type { Speaker, Tier } from "../speakers.ts";
+
+/** What the runtime keeps about a conversation's running turn, for its tools to read. */
+export interface RunningTurn {
+	tier: Tier;
+	speaker: Speaker;
+	/** Where the turn's request came from, as `TurnRequest.origin` says. */
+	origin?: string;
+	/** What the client that started the turn can do, as `TurnRequest.client` says. */
+	client?: ClientPort;
+	/** Whether the turn loads no memory. */
+	withheld: boolean;
+}

package/src/core/runtime/runtime-plugin.ts

@@ -168,6 +168,9 @@ export function runtimePlugin(
 						}),
 						confirmations: heldActions,
 						toolTiers: context.toolTiers,
+						...(providers.filled.has("images")
+							? { images: providers.images }
+							: {}),
 						stopping: () => context.queue.closed,
 						get agents() {
 							return agents();

package/src/core/runtime/runtime-types.ts

@@ -4,6 +4,7 @@ import type {
 	ExtensionFactory,
 	ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
+import type { ImageDrawer } from "../contract/providers.ts";
 import type { AgentSessions, LoadedSkill } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { InterimTextMode } from "../domain/interim.ts";
@@ -97,6 +98,8 @@ export interface PiAgentRuntimeOptions {
 	interimPrimaryChars?: number;
 	/** How long a new session waits for its MCP tools to register. */
 	mcpConnectTimeoutMs?: number;
+	/** The host's image provider, when one fills the slot; sessions then offer `generate_image`. */
+	images?: ImageDrawer;
 	/** Defaults to true: bridge shared turns refuse raw private exchanges inaccessible to the reader. */
 	memory?: boolean;
 }
@@ -113,6 +116,8 @@ export interface CoreExtensions {
 	readAttachment: ExtensionFactory;
 	/** `attach_file`, for a session with a workspace. */
 	attachFile?: ExtensionFactory;
+	/** `generate_image`, for a host with an image provider. */
+	generateImage?: ExtensionFactory;
 	confirmationGate: ExtensionFactory;
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
@@ -144,6 +149,9 @@ export function sessionExtensions(
 		...(core.attachFile
 			? [{ name: "attach-file", factory: core.attachFile }]
 			: []),
+		...(core.generateImage
+			? [{ name: "generate-image", factory: core.generateImage }]
+			: []),
 		{ name: "confirmation-gate", factory: core.confirmationGate },
 		{ name: "ask-user", factory: core.askUser },
 		{ name: "self-compact-guard", factory: core.selfCompactGuard },

package/src/core/runtime/session-factory.ts

@@ -10,6 +10,8 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.ts";
+import type { ImageDrawer } from "../contract/providers.ts";
+import type { ClientPort } from "../domain/client.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
@@ -27,8 +29,13 @@ import {
 	ATTACH_FILE_TOOL,
 	attachFileExtension,
 } from "../shared/attach-file-tool.ts";
+import {
+	GENERATE_IMAGE_TOOL,
+	generateImageExtension,
+} from "../shared/generate-image-tool.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
+import type { WorkspaceRoots } from "../shared/workspace-files.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
 import { toolTurn } from "../tool-turn.ts";
@@ -55,6 +62,7 @@ import type { PromptSlot } from "./prompt-slot.ts";
 import type {
 	ChannelSession,
 	CompactionEnd,
+	CoreExtensions,
 	PiAgentRuntimeOptions,
 } from "./runtime-types.ts";
 import {
@@ -75,6 +83,8 @@ export interface SessionFactoryDeps {
 	speaker(channel: ChannelKey): Speaker | undefined;
 	/** Where the conversation's running turn came from, as its transport reported it. */
 	origin(channel: ChannelKey): string | undefined;
+	/** What the client that started the conversation's running turn can do for its tools. */
+	client(channel: ChannelKey): ClientPort | undefined;
 	/** Whether the conversation's running turn loads no memory, as the agent server's option keeps a speaker out of it. */
 	withholdsMemory(channel: ChannelKey): boolean;
 	/**
@@ -139,6 +149,8 @@ export class SessionFactory {
 			ASK_USER_TOOL,
 			// Registered only by a session with a workspace.
 			ATTACH_FILE_TOOL,
+			// Registered only with an image provider.
+			GENERATE_IMAGE_TOOL,
 			...groups
 				.filter((group) => selection.groups.includes(group.name))
 				.flatMap((group) => group.tools),
@@ -358,6 +370,7 @@ export class SessionFactory {
 			},
 			speaker: () => this.#deps.speaker(turnKey),
 			origin: () => this.#deps.origin(turnKey),
+			client: () => this.#deps.client(turnKey),
 			runTask: (task) =>
 				this.#deps.runTask({ turn: turnKey, home: channel }, task),
 		};
@@ -377,6 +390,10 @@ export class SessionFactory {
 				...(context.workspace
 					? { attachFile: attachFileExtension(context.workspace) }
 					: {}),
+				...imageTools(
+					this.#options.images,
+					context.workspace ?? { workspace: cwd },
+				),
 				confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
 					toolTurn(context, signal),
 				),
@@ -438,6 +455,14 @@ export class SessionFactory {
 	}
 }
 
+/** `generate_image` for a session of a host with an image provider; nothing without one. */
+export function imageTools(
+	images: ImageDrawer | undefined,
+	roots: WorkspaceRoots,
+): Pick<CoreExtensions, "generateImage"> {
+	return images ? { generateImage: generateImageExtension(images, roots) } : {};
+}
+
 /** Pi's bash tool with TMPDIR set to `scratchDir`, so `mktemp` and tools write there. */
 export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
 	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.

package/src/core/sessions.ts

@@ -1,4 +1,5 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ClientPort } from "./domain/client.ts";
 import { PluginError } from "./errors.ts";
 import type { Principal } from "./identity/principal-store.ts";
 import type { OwnerIdentity } from "./identity.ts";
@@ -98,6 +99,12 @@ export interface SessionContext {
 	 * method, which reads as undefined.
 	 */
 	origin?(): string | undefined;
+	/**
+	 * What the client that started the running turn can do for its tools, as `TurnRequest.client`
+	 * says; undefined between turns and for a turn whose transport gives none. A context built
+	 * before 0.9.11 has no such method, which reads as undefined.
+	 */
+	client?(): ClientPort | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */
 	runTask(task: TransientTask): Promise<string>;
 }

package/src/core/shared/generate-image-tool.ts

@@ -0,0 +1,173 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ImageDrawer, ReferenceImage } from "../contract/providers.ts";
+import {
+	attachReplyFile,
+	REPLY_FILE_LIMITS,
+	ReplyFileError,
+} from "../reply-files.ts";
+import { toolError, toolText } from "./tool-result.ts";
+import {
+	findWorkspaceFile,
+	readWorkspaceFile,
+	WorkspaceFileError,
+	type WorkspaceRoots,
+} from "./workspace-files.ts";
+
+export const GENERATE_IMAGE_TOOL = "generate_image";
+
+/** The limits on the reference images one call passes to the drawer. */
+export const REFERENCE_IMAGE_LIMITS = Object.freeze({
+	maxImages: 4,
+	maxImageBytes: 20 * 1024 * 1024,
+	maxTotalBytes: 40 * 1024 * 1024,
+});
+
+const MAX_PROMPT_CHARS = 4000;
+
+/** The image type of `data` by its content, or undefined for anything else. */
+export function imageTypeOf(
+	data: Uint8Array,
+): { mimeType: string; ext: string } | undefined {
+	const starts = (bytes: readonly number[], at = 0) =>
+		bytes.every((byte, i) => data[at + i] === byte);
+	if (starts([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+		return { mimeType: "image/png", ext: "png" };
+	if (starts([0xff, 0xd8, 0xff])) return { mimeType: "image/jpeg", ext: "jpg" };
+	if (starts([0x47, 0x49, 0x46, 0x38]))
+		return { mimeType: "image/gif", ext: "gif" };
+	if (starts([0x52, 0x49, 0x46, 0x46]) && starts([0x57, 0x45, 0x42, 0x50], 8))
+		return { mimeType: "image/webp", ext: "webp" };
+	return undefined;
+}
+
+async function readReferences(
+	paths: readonly string[],
+	roots: WorkspaceRoots,
+): Promise<ReferenceImage[]> {
+	const { maxImages, maxImageBytes, maxTotalBytes } = REFERENCE_IMAGE_LIMITS;
+	if (paths.length > maxImages)
+		throw new WorkspaceFileError(
+			`${paths.length} reference images given; at most ${maxImages} are allowed.`,
+		);
+	const files = await Promise.all(
+		paths.map((path) => findWorkspaceFile(path, roots)),
+	);
+	let total = 0;
+	for (const file of files) {
+		if (file.size > maxImageBytes)
+			throw new WorkspaceFileError(
+				`${file.path} is ${file.size} bytes; a reference image may contain at most ${maxImageBytes} bytes.`,
+			);
+		total += file.size;
+	}
+	if (total > maxTotalBytes)
+		throw new WorkspaceFileError(
+			`the reference images total ${total} bytes; at most ${maxTotalBytes} are allowed.`,
+		);
+	const references: ReferenceImage[] = [];
+	for (const file of files) {
+		const data = await readWorkspaceFile(file, maxImageBytes);
+		const type = imageTypeOf(data);
+		if (!type)
+			throw new WorkspaceFileError(
+				`${file.path} is not a PNG, JPEG, WebP or GIF image.`,
+			);
+		references.push({
+			data: Buffer.from(data).toString("base64"),
+			mimeType: type.mimeType,
+		});
+	}
+	return references;
+}
+
+/**
+ * Registers `generate_image`, which draws a new picture with the host's image provider, saves it
+ * under `<scratch dir or workspace>/drawings`, and attaches it to the turn's reply.
+ */
+export function generateImageExtension(
+	draw: ImageDrawer,
+	roots: WorkspaceRoots,
+): ExtensionFactory {
+	return (pi) => {
+		pi.registerTool({
+			name: GENERATE_IMAGE_TOOL,
+			label: "Generate image",
+			description:
+				'Generate a new picture from a description. Describe the subject, style and composition; say "no text" when you will add text to it later. The picture is saved to a file whose path the result names, and attached to your reply.',
+			parameters: Type.Object(
+				{
+					prompt: Type.String({
+						minLength: 1,
+						maxLength: MAX_PROMPT_CHARS,
+						description:
+							"What to draw: subject, style, composition, and anything to leave out.",
+					}),
+					reference_paths: Type.Optional(
+						Type.Array(Type.String({ minLength: 1, maxLength: 4096 }), {
+							maxItems: REFERENCE_IMAGE_LIMITS.maxImages,
+							description:
+								"Paths of PNG, JPEG, WebP or GIF images inside the workspace or the scratch dir to draw from.",
+						}),
+					),
+				},
+				{ additionalProperties: false },
+			),
+			execute: async (_toolCallId, params, signal) => {
+				let references: ReferenceImage[];
+				try {
+					references = await readReferences(
+						params.reference_paths ?? [],
+						roots,
+					);
+				} catch (error) {
+					if (error instanceof WorkspaceFileError)
+						return toolError(`Not drawn: ${error.message}`);
+					throw error;
+				}
+				signal?.throwIfAborted();
+				let data: Uint8Array;
+				try {
+					data = await draw(
+						params.prompt,
+						references,
+						signal ? { signal } : {},
+					);
+				} catch (error) {
+					signal?.throwIfAborted();
+					return toolError(
+						`The image provider did not draw it: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+				signal?.throwIfAborted();
+				const type = imageTypeOf(data);
+				if (!type)
+					return toolError(
+						"The image provider returned something that is not a PNG, JPEG, WebP or GIF image.",
+					);
+				const dir = join(roots.scratchDir ?? roots.workspace, "drawings");
+				await mkdir(dir, { recursive: true });
+				const name = `generated-${new Date().toISOString().replace(/[:.]/g, "-")}.${type.ext}`;
+				const path = join(dir, name);
+				await writeFile(path, data);
+				try {
+					if (data.byteLength > REPLY_FILE_LIMITS.maxFileBytes)
+						throw new ReplyFileError(
+							`it is ${data.byteLength} bytes; a reply file may contain at most ${REPLY_FILE_LIMITS.maxFileBytes} bytes.`,
+						);
+					attachReplyFile({ name, data });
+				} catch (error) {
+					if (!(error instanceof ReplyFileError)) throw error;
+					return toolText(
+						`Drew the picture and saved it to ${path} (${data.byteLength} bytes), but it is not attached: ${error.message}`,
+					);
+				}
+				return toolText(
+					`Drew the picture, saved it to ${path} (${data.byteLength} bytes); it will appear with your reply.`,
+				);
+			},
+		});
+	};
+}

package/src/core/shared/tool-result.ts

@@ -1,8 +1,56 @@
+import {
+	isModelImage,
+	MAX_IMAGES_PER_TURN,
+	prepareImageBytes,
+} from "../attachments/image-prep.ts";
+import { ImagePreparationError } from "../attachments/image-preparation-error.ts";
+
 /** The text a tool returns, in the shape Pi expects. */
 export function toolText(text: string) {
 	return { content: [{ type: "text" as const, text }], details: {} };
 }
 
+/** A tool's output: text, or text with images the model reads beside it. */
+export type ToolOutput =
+	| string
+	| {
+			text: string;
+			images?: readonly { mimeType: string; data: Uint8Array }[];
+	  };
+
+/** `output` in the shape Pi expects: a text part, then one image part for each image. */
+export async function toolOutput(output: ToolOutput) {
+	if (typeof output === "string") return toolText(output);
+	const images = output.images ?? [];
+	if (images.length > MAX_IMAGES_PER_TURN)
+		return toolError(
+			`the tool returned ${images.length} images; at most ${MAX_IMAGES_PER_TURN} fit in one result.`,
+		);
+	const parts: { type: "image"; data: string; mimeType: string }[] = [];
+	for (const [index, image] of images.entries()) {
+		const label = `image ${index + 1} could not be prepared`;
+		const mimeType = image.mimeType.split(";")[0]?.trim().toLowerCase() ?? "";
+		if (!isModelImage({ contentType: mimeType }))
+			return toolError(
+				`${label}: ${image.mimeType} is not an image type the model reads (png, jpeg, gif or webp).`,
+			);
+		try {
+			const ready = await prepareImageBytes(image.data, mimeType);
+			parts.push({ type: "image", ...ready });
+		} catch (error) {
+			if (error instanceof ImagePreparationError)
+				return toolError(`${label}: ${error.message}`);
+			return toolError(
+				`${label}: the bytes are not a readable ${mimeType} image.`,
+			);
+		}
+	}
+	return {
+		content: [{ type: "text" as const, text: output.text }, ...parts],
+		details: {},
+	};
+}
+
 /** A refused call's reason, which the model reads as the tool's error result. */
 export function toolError(text: string) {
 	return { ...toolText(text), isError: true };

package/src/core/tool-turn.ts

@@ -1,12 +1,34 @@
 import {
 	AttachmentLookupError,
+	listAttachments,
 	openAttachment,
 } from "./attachments/tool-attachment.ts";
 import type { ToolTurn } from "./define.ts";
 import { ToolRefusal } from "./define.ts";
+import type { ClientPort } from "./domain/client.ts";
 import { attachReplyFile } from "./reply-files.ts";
 import type { SessionContext } from "./sessions.ts";
 
+/**
+ * `port` as a tool sees it in a turn: every call carries the turn's `signal` beside the caller's,
+ * so stopping the turn cancels the call in flight.
+ */
+function clientIn(port: ClientPort, turn: AbortSignal | undefined): ClientPort {
+	return {
+		names: port.names,
+		call: (name, args, options) => {
+			const signals = [options?.signal, turn].filter(
+				(signal): signal is AbortSignal => signal !== undefined,
+			);
+			const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+			return port.call(name, args, {
+				...options,
+				...(signal ? { signal } : {}),
+			});
+		},
+	};
+}
+
 /**
  * The turn a tool's `run` and `hold` receive, built from the session that makes the call and the
  * signal that stops it.
@@ -16,14 +38,20 @@ export function toolTurn(
 	signal: AbortSignal | undefined,
 ): ToolTurn {
 	const origin = context.origin?.();
+	const client = context.client?.();
 	return {
 		speaker: context.speaker(),
 		channel: context.turnChannel,
 		agent: context.agent,
 		signal,
 		...(origin === undefined ? {} : { origin }),
+		...(client === undefined ? {} : { client: clientIn(client, signal) }),
 		...(context.workspace ? { workspace: context.workspace } : {}),
 		attachFile: attachReplyFile,
+		attachments: async () =>
+			context.attachmentDir === undefined
+				? []
+				: listAttachments(context.attachmentDir),
 		attachment: async (file) => {
 			if (context.attachmentDir === undefined)
 				throw new ToolRefusal("this session keeps no attachments");

package/src/index.ts

@@ -17,7 +17,10 @@ export type {
 	TeamStatus,
 } from "./core/agents/team-status.ts";
 export type { AttachmentRetention } from "./core/attachments/attachment-retention.ts";
-export type { ToolAttachment } from "./core/attachments/tool-attachment.ts";
+export type {
+	ToolAttachment,
+	ToolAttachmentInfo,
+} from "./core/attachments/tool-attachment.ts";
 export {
 	AGENT_SERVER_PLUGIN,
 	AGENT_TEAM_SERVICE,
@@ -86,7 +89,12 @@ export type {
 } from "./core/conversations/conversation-registry.ts";
 export type { Migration, MigrationReport } from "./core/db/migrations.ts";
 export { migrateDatabase } from "./core/db/migrations.ts";
-export type { ToolContribution, ToolSpec, ToolTurn } from "./core/define.ts";
+export type {
+	ToolContribution,
+	ToolOutput,
+	ToolSpec,
+	ToolTurn,
+} from "./core/define.ts";
 export { definePlugin, defineTool, ToolRefusal } from "./core/define.ts";
 export type {
 	DefinedRoundtable,
@@ -100,6 +108,13 @@ export type {
 	TurnAttachments,
 } from "./core/domain/attachment.ts";
 export { NO_ATTACHMENTS } from "./core/domain/attachment.ts";
+export type {
+	ClientCallError,
+	ClientCallOptions,
+	ClientCallResult,
+	ClientPart,
+	ClientPort,
+} from "./core/domain/client.ts";
 export type {
 	HeldCall,
 	OutboundReply,

package/src/testing.ts

@@ -30,6 +30,7 @@ import {
 	commandGuard,
 	ownerRootCommand,
 } from "./core/discord/owner-command.ts";
+import type { ClientPart, ClientPort } from "./core/domain/client.ts";
 import type {
 	PendingConfirmation,
 	ReplyFile,
@@ -264,6 +265,8 @@ export interface TestPluginResult {
 	events: RecordedEvent[];
 	/** Files accepted by successful runTool calls, copied and recorded with their channel. */
 	files: { channel: ChannelKey; file: ReplyFile }[];
+	/** Images returned by successful runTool calls, with their channel. */
+	images: { channel: ChannelKey; image: ClientPart }[];
 	runTool(
 		name: string,
 		args: Record<string, unknown>,
@@ -272,6 +275,8 @@ export interface TestPluginResult {
 			speaker?: Speaker;
 			/** Where the turn's request came from, as `ToolTurn.origin` shows it to the tool. */
 			origin?: string;
+			/** What the party that started the turn can do for the tool, as `ToolTurn.client` shows it. */
+			client?: ClientPort;
 			channel?: ChannelKey;
 			workspace?: SessionContext["workspace"];
 		},
@@ -606,6 +611,7 @@ export async function testPlugin(
 	await runtime?.preflight?.();
 	let stopped = false;
 	const files: { channel: ChannelKey; file: ReplyFile }[] = [];
+	const images: { channel: ChannelKey; image: ClientPart }[] = [];
 	return {
 		contribution,
 		holds: linked.holds,
@@ -617,6 +623,7 @@ export async function testPlugin(
 		tiers,
 		events,
 		files,
+		images,
 		async runTool(name, args, runOptions) {
 			const tool = registry.tools.find((item) => item.name === name);
 			if (!tool) throw new PluginError(`tool ${name} is not registered`);
@@ -626,7 +633,12 @@ export async function testPlugin(
 					params: Record<string, unknown>,
 					signal?: AbortSignal,
 				): Promise<{
-					content: readonly { type: string; text?: string }[];
+					content: readonly {
+						type: string;
+						text?: string;
+						data?: string;
+						mimeType?: string;
+					}[];
 					isError?: boolean;
 				}>;
 			}[] = [];
@@ -643,6 +655,7 @@ export async function testPlugin(
 				attachmentDir: ownerAttachmentDir(attachmentDir, channel),
 				speaker: () => runOptions?.speaker,
 				origin: () => runOptions?.origin,
+				client: () => runOptions?.client,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");
 				},
@@ -661,9 +674,21 @@ export async function testPlugin(
 				surfaces.of(channel)?.supportsFiles === true,
 				async () => {
 					const output = await execute("test-call", args);
+					for (const item of output.content)
+						if (item.type === "image" && item.data && item.mimeType)
+							images.push({
+								channel,
+								image: {
+									mimeType: item.mimeType,
+									data: new Uint8Array(Buffer.from(item.data, "base64")),
+								},
+							});
 					return {
 						ok: true,
-						text: output.content.map((item) => item.text ?? "").join("\n"),
+						text: output.content
+							.filter((item) => item.type === "text")
+							.map((item) => item.text ?? "")
+							.join("\n"),
 					};
 				},
 			);