pi-roundtable 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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
+
+- `ToolTurn.origin`, `TurnRequest.origin`, `ConversationTurnInput.origin` and `SessionContext.origin()`: where a turn's request came from, as the transport that carried it reported it, such as the browser origin of a web chat connection (`https://chat.example.com`). A tool's `run` and its `hold` read it from the `ToolTurn` they receive, so a tool can label what it creates (an issue's source line) and fail closed when it is undefined. A claim passes it to `context.turns.run({ ..., origin })`; the runtime keeps it with the turn's speaker and clears it when the turn ends. Only the transport sets it, never the message text or the model. A turn whose channel gives none (Discord, a schedule, an agent's turn, the CLI) leaves it undefined, and `testPlugin().runTool` takes `origin` in its options. Additive: nothing changes for a claim or a tool that does not use it, and `SessionContext.origin` is optional on the type so a context built before this still type-checks.
+
 ## [0.9.9] - 2026-10-10
 
 ### Added

package/docs/plugins.md

@@ -586,13 +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";
@@ -746,7 +762,7 @@ export const cleanup = definePlugin({
 #### A hold that looks things up
 
 A hold may need something it must fetch as the speaker before it can describe the call, such as the display name of the entity an id stands for, read with the speaker's own credentials.
-A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel` and the `agent` of the turn that makes the call.
+A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel`, the `agent` and the `origin` of the turn that makes the call.
 
 ```ts
 defineTool({
@@ -1861,6 +1877,8 @@ 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:
 
@@ -2012,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 `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.
@@ -2955,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, 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; `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 |
@@ -3360,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 |
@@ -3522,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.9",
+	"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";
 
@@ -26,6 +34,22 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/**
+	 * Where the turn's request came from, as its transport reported it, such as the browser origin
+	 * of a web chat connection (`https://chat.example.com`); undefined for a turn whose channel gives
+	 * none, such as a Discord message or a schedule. Only the transport sets it, never the message
+	 * text or the model, so a tool may label a record with it; a tool that needs one fails closed
+	 * 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.
@@ -40,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[]>;
 }
 
 /**
@@ -77,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;
@@ -134,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";
@@ -30,6 +31,19 @@ export interface TurnRequest {
 	 * starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`.
 	 */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the transport that carried it knows: the browser origin of a
+	 * web chat connection, such as `https://chat.example.com`. A channel with no such thing leaves it
+	 * out. Only a channel's transport sets it, never the message text or the model; a tool reads it
+	 * 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";
@@ -29,6 +30,17 @@ export interface ConversationTurnInput {
 	text: string;
 	/** Who the turn is for; its tier limits the tools. */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the claim's transport knows it, such as a web chat
+	 * connection's browser origin; tools read it as `ToolTurn.origin`. Leave it out for a turn the
+	 * 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. */
@@ -184,6 +196,8 @@ 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 and speaker of each conversation's running turn. */
-	readonly #turns = new Map<
-		ChannelKey,
-		{ tier: Tier; speaker: Speaker; 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>();
@@ -87,6 +84,8 @@ export class PiAgentRuntime implements AgentRuntime {
 		this.#tiers = options.toolTiers ?? toolTiers();
 		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),
 		});
@@ -192,7 +191,13 @@ export class PiAgentRuntime implements AgentRuntime {
 				loadsMemory(registered),
 		);
 		this.#memoryTurns.set(key, markPrivateMemory);
-		this.#turns.set(key, { tier, speaker: request.speaker, withheld });
+		this.#turns.set(key, {
+			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));
 		if (missing.length > 0) {
 			logger.warn(

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";
@@ -73,6 +74,10 @@ import {
 export interface SessionFactoryDeps {
 	/** The person the conversation's running turn is for. */
 	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;
 	/**
@@ -355,6 +360,8 @@ export class SessionFactory {
 				return state.memory;
 			},
 			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";
@@ -92,6 +93,18 @@ export interface SessionContext {
 	attachmentDir?: string;
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
+	/**
+	 * Where the running turn's request came from, as `TurnRequest.origin` says; undefined between
+	 * turns and for a turn whose transport gives none. A context built before 0.9.10 has no such
+	 * 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.
@@ -15,13 +37,21 @@ export function toolTurn(
 	context: SessionContext,
 	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,12 +265,18 @@ 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>,
 		/** `workspace` gives the session a workspace and scratch dir, as an agent's session has. */
 		options?: {
 			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"];
 		},
@@ -604,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,
@@ -615,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`);
@@ -624,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;
 				}>;
 			}[] = [];
@@ -640,6 +654,8 @@ export async function testPlugin(
 				...(runOptions?.workspace ? { workspace: runOptions.workspace } : {}),
 				attachmentDir: ownerAttachmentDir(attachmentDir, channel),
 				speaker: () => runOptions?.speaker,
+				origin: () => runOptions?.origin,
+				client: () => runOptions?.client,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");
 				},
@@ -658,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"),
 					};
 				},
 			);