pi-roundtable 0.9.10 → 0.9.11

package/CHANGELOG.md

@@ -5,6 +5,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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";
@@ -1865,6 +1877,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 +2030,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 +2973,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 +3379,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 +3546,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.11",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

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/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/session-factory.ts

@@ -10,6 +10,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.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";
@@ -75,6 +76,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;
 	/**
@@ -358,6 +361,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),
 		};

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/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"),
 					};
 				},
 			);