pi-roundtable 0.7.16 → 0.7.17

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.17] - 2026-10-04
+
+### Added
+
+- A turn posts the text it writes before its final answer as it goes, so a proposal written before `ask_user` shows above its card instead of never reaching the channel. Primary text (400 characters or more, or with a Markdown heading, list, table or code fence) of a tool-calling assistant message is posted as ordinary messages when the message ends; shorter narration and the tools called (`-# bash ×3 · read`, names only) share one small-text progress message per run of tool calls, edited at most every 1.5 s, bounded to 2000 characters by dropping its oldest lines. Before any card the pending text is posted first. The final reply, its thinking line, and steered runs are unchanged; a failed interim post is logged and never fails the turn. See [interim text](docs/plugins.md#interim-text-what-a-turn-writes-before-its-final-answer).
+  - Config `interimText: "on" | "off"` (default `"on"`) and `interimPrimaryChars` (default 400), also on `PiAgentRuntimeOptions` and the agent server's options.
+  - `TurnRequest.interim`, `ChatSurface.interim(channel)` and `SurfacePort.interim(channel)` (Discord's surface implements it), optional `AgentChannels.interim(channelId, as)` (the agents' webhooks), and `PromptSlot.bind`'s optional `beforeCard`.
+  - Types: `InterimMessage`, `InterimPosts`, `InterimTextMode`.
+
+### Changed
+
+- `ask_user`'s description asks for a question that reads on its own, with the context it needs.
+
 ## [0.7.16] - 2026-10-04
 
 ### Added

package/docs/plugins.md

@@ -1056,7 +1056,7 @@ An `AgentRuntime` has these methods:
 | `preflight?()` | Runs in the host's preflight, before anything starts; a throw stops the boot |
 | `dispose?()` | Runs when the host stops the agent server's runtime service |
 
-A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker`, and flags (`steerable`, `interactive`, `confirmed`).
+A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker`, flags (`steerable`, `interactive`, `confirmed`), and `interim`, where the turn may post the text it writes before its final answer ([interim text](#interim-text-what-a-turn-writes-before-its-final-answer)).
 An agent's turn also has `agent`, the agent's scope, whose `session` is the conversation's key.
 Other turns use `kind` to name the conversation's persona, defaulting to `"owner"` when absent.
 
@@ -1882,6 +1882,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `showStop(channel)` | Shows the owner a stop control until the returned function is called; using it calls `conversations.stop(channel)` | none is shown |
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
 | `prompts(channel, speaker?)` | The owner's way to approve a held action or answer `ask_user` inside a running turn, as `OwnerPrompts`: `confirm` and `ask` | the action is held until the owner's next message |
+| `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
 
 The host starts each surface as `surface:<prefix>` at the contributing plugin's place in the order, before that plugin's own services.
 It stops surfaces in reverse order, like other services.
@@ -1893,6 +1894,22 @@ If `prompts` is unavailable, it returns `undefined` and held actions wait for th
 `of(channel)` returns the surface, or `undefined`.
 The agent server asks the owner for approvals through `context.surfaces.prompts`, so a surface that gives `prompts` gets them in its own channels.
 
+#### Interim text: what a turn writes before its final answer
+
+A model often writes text in an assistant message that then calls tools, such as a proposal before it asks `ask_user` "go with this version?".
+On a surface that gives `interim`, and in the agent server's channels through the agents' webhooks, the host posts that text as the turn goes, sorted in two:
+
+- **Primary** text is posted as ordinary messages as soon as its assistant message ends: text of 400 characters or more, or written with a Markdown heading, list, table or code fence.
+- **Secondary** text, short narration between tool calls, goes to one progress message per run of tool-calling messages, in Discord's small text (`-# ` per line): each text as a line, then the tools called in the run, such as `-# bash ×3 · read · web_search` (names only). It is edited in place at most every 1.5 seconds, its last state always lands, and it stays inside 2000 characters by dropping its oldest lines behind `-# …`. A primary post or a card starts a new progress message.
+
+Before any card, an `ask_user` question or an approval, the host posts the pending text and brings the progress message up to date, so what the model wrote before the card shows above it.
+The final reply is posted at the end as before, with its thinking line; an intermediate message is never the final one, so nothing is posted twice, and a steered run keeps its final text.
+A failed interim post or edit is logged and never fails the turn.
+Turns with nowhere to post, such as transient tasks, coding workers, and turns of a claim that passes its own `reply` to `context.turns.run`, post only their final reply.
+A runtime that fills [the `runtime` slot](#the-runtime-slot-replace-pi) receives the place to post as `TurnRequest.interim` and may use it or not.
+
+The config's `interimText: "off"` posts only the final reply (default `"on"`), and `interimPrimaryChars` sets the length of primary text (default 400).
+
 The Discord plugin collects [slash commands](#slash-commands-commandsadd); the host doesn't compose them or pass them to surfaces on other networks.
 
 This in-memory chat surface records everything the host asks of it.
@@ -2525,6 +2542,9 @@ Import from the entries listed below; source area files are internal.
 | `HttpRoute` | `pi-roundtable` | type |
 | `ImageDrawer` | `pi-roundtable` | type |
 | `InboundMessage` | `pi-roundtable` | type |
+| `InterimMessage` | `pi-roundtable` | type |
+| `InterimPosts` | `pi-roundtable` | type |
+| `InterimTextMode` | `pi-roundtable` | type |
 | `Judge` | `pi-roundtable` | type |
 | `JudgeError` | `pi-roundtable` | value |
 | `JudgeModel` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.16",
+	"version": "0.7.17",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

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

@@ -1,4 +1,5 @@
 import type { AgentRuntime, ContextUse } from "../contract/runtime.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { ThinkingSetting } from "../models.ts";
 
 export type { ContextUse };
@@ -47,6 +48,14 @@ export interface ChannelMessage {
 /** The agent server's channels as the agent team needs them. */
 export interface AgentChannels {
 	post(channelId: string, post: AgentPost): Promise<void>;
+	/**
+	 * Where a running turn posts the text it writes before its final answer, under the same name
+	 * and avatar as `post`; absent = only the final reply is posted.
+	 */
+	interim?(
+		channelId: string,
+		as: Omit<AgentPost, "thinking" | "chunks" | "files">,
+	): InterimPosts;
 	/** Creates a text channel under the category, made when missing; returns its id. */
 	createChannel(
 		name: string,

package/src/core/agents/team-turn-types.ts

@@ -44,7 +44,7 @@ export interface TeamTurnsOptions {
 	/** Who the agents work for, as their prompts and group history name them. */
 	owner: OwnerIdentity;
 	store: PgAgentStore;
-	channels: Pick<AgentChannels, "post">;
+	channels: Pick<AgentChannels, "post" | "interim">;
 	studio: Pick<AvatarStudio, "url">;
 	/** Set once the runtime exists, which itself needs the team's tools. */
 	runtime: () => AgentTurnRunner;

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

@@ -6,6 +6,7 @@ import type {
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
@@ -185,6 +186,7 @@ export class TeamTurns {
 			...(scope.group ? { group: scope.group } : {}),
 		};
 		this.#options.events?.turnStarted(turn);
+		const interim = this.#interim(postTo, agent);
 		let result: TurnResult;
 		try {
 			result = await settleTurn(
@@ -200,6 +202,7 @@ export class TeamTurns {
 							...(extra.interactive ? { interactive: true } : {}),
 							agent: scope,
 							speaker: chain.speaker,
+							...(interim ? { interim } : {}),
 						}),
 					),
 				"agent turn",
@@ -250,6 +253,27 @@ export class TeamTurns {
 		return this.#options.store.agent(agent.name) ?? agent;
 	}
 
+	/**
+	 * The turn's interim posts under the agent's name, read as each goes out so a name changed
+	 * during the turn shows; none in a channel no agent or group owns any more.
+	 */
+	#interim(channel: ChannelKey, agent: Agent): InterimPosts | undefined {
+		const { store, channels, studio } = this.#options;
+		if (!channels.interim) return undefined;
+		const interim = channels.interim.bind(channels);
+		return {
+			post: async (text) => {
+				if (!channelOwner(store, channel))
+					throw new AgentError(`${channel} is archived`);
+				const as = this.#current(agent);
+				return interim(channelIdOf(channel), {
+					name: as.displayName,
+					avatarUrl: studio.url(as.avatarHash),
+				}).post(text);
+			},
+		};
+	}
+
 	/**
 	 * Posts under the agent's name. A channel no agent or group owns any more, archived while a
 	 * turn ran, gets nothing, so its webhook is not made again.

package/src/core/builtin/agent-server.ts

@@ -14,6 +14,7 @@ import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
 import type { AgentRuntime, AgentSessions } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import { ConfirmationJudge } from "../judging/confirmation-judge.ts";
 import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
@@ -72,6 +73,10 @@ export interface AgentServerOptions {
 	avatarReference: string;
 	/** Reports the process's own errors to an agent; without one nothing is reported. */
 	errorReporter?: ErrorReporter;
+	/** Whether turns post the text they write before their final answer as they go; default "on". */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
 }
 
 /** The name of the agent server's plugin, as `serviceStarted` events name it. */
@@ -278,6 +283,12 @@ export function agentServerPlugin(
 						agents: agentSessions,
 						prompts,
 						logger,
+						...(options.interimText
+							? { interimText: options.interimText }
+							: {}),
+						...(options.interimPrimaryChars
+							? { interimPrimaryChars: options.interimPrimaryChars }
+							: {}),
 					});
 			runtime = running;
 			context.services.provide(AGENTS, {

package/src/core/config/config.ts

@@ -2,6 +2,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { AgentSeed } from "../agents/agent-rules.ts";
 import { ConfigError } from "../domain/errors.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
 import { isLocale, type Locale } from "../i18n/index.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import {
@@ -11,6 +12,7 @@ import {
 	type ThinkingLevel,
 } from "../models.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
+import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
 import {
 	bool,
@@ -123,6 +125,14 @@ export interface RoundtableConfig {
 	memory?: boolean;
 	/** The agent that investigates the process's own errors, by name. */
 	ops?: { agent: string };
+	/**
+	 * Whether a turn posts the text it writes before its final answer as it goes: long or
+	 * structured text as ordinary messages, short narration and the tools called in one small
+	 * progress message. Default "on"; "off" posts only the final reply.
+	 */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
 	plugins?: RoundtablePlugin[];
 }
 
@@ -204,6 +214,8 @@ const schema = shape({
 	),
 	memory: optional(bool),
 	ops: optional(shape({ agent: text })),
+	interimText: optional(oneOf<InterimTextMode>("on", "off")),
+	interimPrimaryChars: optional(integer(1, 100_000)),
 	plugins: optional(
 		list(
 			guarded("a plugin, an object with a name and a setup function", isPlugin),
@@ -256,6 +268,8 @@ export interface ResolvedConfig {
 	skills: false | { builtinDir?: string; reposDir?: string };
 	memory: boolean;
 	ops?: { agent: string };
+	interimText: InterimTextMode;
+	interimPrimaryChars: number;
 	plugins: RoundtablePlugin[];
 }
 
@@ -335,6 +349,8 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		skills: config.skills ?? {},
 		memory: config.memory ?? true,
 		...(config.ops ? { ops: config.ops } : {}),
+		interimText: config.interimText ?? "on",
+		interimPrimaryChars: config.interimPrimaryChars ?? PRIMARY_CHARS,
 		plugins: config.plugins ?? [],
 	};
 }

package/src/core/contract/surface.ts

@@ -1,4 +1,5 @@
 import type { OutboundReply } from "../domain/conversation.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import { PluginError } from "../errors.ts";
 import type { ChannelKey } from "../sessions.ts";
@@ -68,6 +69,11 @@ export interface ChatSurface {
 	 * absent, = the action is held until the owner's next message.
 	 */
 	prompts?(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	/**
+	 * Where a running turn posts the text it writes before its final answer: ordinary messages it
+	 * may edit in place. Absent, or undefined, = only the final reply is posted.
+	 */
+	interim?(channel: ChannelKey): InterimPosts | undefined;
 }
 
 /**
@@ -87,4 +93,6 @@ export interface SurfacePort {
 	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
 	/** The owner's prompts in the channel; undefined when its surface has none. */
 	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	/** The channel's interim posts; undefined when its surface has none. */
+	interim(channel: ChannelKey): InterimPosts | undefined;
 }

package/src/core/define-roundtable.ts

@@ -217,6 +217,8 @@ export async function defineRoundtable(
 				avatarListener: "public",
 				avatarUrl: config.http.publicUrl,
 				avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+				interimText: config.interimText,
+				interimPrimaryChars: config.interimPrimaryChars,
 				...(errorReporter ? { errorReporter } : {}),
 			}),
 			seedsPlugin(config.agents),

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

@@ -23,6 +23,7 @@ import type {
 	DashboardBoard,
 } from "../agents/agent-ports.ts";
 import { AgentError } from "../domain/errors.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import { messages } from "../i18n/index.ts";
 import type { Logger } from "../log.ts";
 
@@ -69,6 +70,38 @@ export class DiscordAgentChannels implements AgentChannels {
 		}
 	}
 
+	interim(
+		channelId: string,
+		as: Omit<AgentPost, "thinking" | "chunks" | "files">,
+	): InterimPosts {
+		const threadId = as.threadId ? { threadId: as.threadId } : {};
+		return {
+			post: async (text) => {
+				const webhook = await this.#webhook(channelId);
+				try {
+					const message = await webhook.send({
+						username: as.name,
+						avatarURL: as.avatarUrl,
+						allowedMentions: { parse: ["users"] },
+						...threadId,
+						content: text,
+					});
+					return {
+						edit: async (change) => {
+							await webhook.editMessage(message, {
+								content: change,
+								...threadId,
+							});
+						},
+					};
+				} catch (error) {
+					this.#webhooks.delete(channelId);
+					throw error;
+				}
+			},
+		};
+	}
+
 	async createChannel(
 		name: string,
 		topic: string,

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

@@ -17,6 +17,7 @@ import type {
 	InboundMessage,
 	OutboundReply,
 } from "../domain/conversation.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import type { OwnerNotifier } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
@@ -159,6 +160,25 @@ export class DiscordSurface
 		return this.#options.prompts(channel, speaker);
 	}
 
+	/** The channel's interim posts: ordinary messages, edited in place for the progress line. */
+	interim(channel: ChannelKey): InterimPosts | undefined {
+		if (!channel.startsWith(PREFIX)) return undefined;
+		return {
+			post: async (text) => {
+				const target = await this.#sendable(channel);
+				const message = await target.send({
+					content: text,
+					allowedMentions: { parse: ["users"] },
+				});
+				return {
+					edit: async (change) => {
+						await message.edit({ content: change });
+					},
+				};
+			},
+		};
+	}
+
 	async start(onMessage: (message: InboundMessage) => void): Promise<void> {
 		const { logger, token } = this.#options;
 		this.#client.on(Events.MessageCreate, (message) => {

package/src/core/domain/interim.ts

@@ -0,0 +1,16 @@
+/** A message an interim post made, which the turn edits in place as it goes. */
+export interface InterimMessage {
+	edit(text: string): Promise<void>;
+}
+
+/**
+ * Where a running turn posts the text it writes before its final answer: the channel the
+ * final reply goes to, under the same name. Each call posts one ordinary message of at most
+ * Discord's 2000 characters.
+ */
+export interface InterimPosts {
+	post(text: string): Promise<InterimMessage>;
+}
+
+/** Whether a turn posts its intermediate text as it goes; "on" by default. */
+export type InterimTextMode = "on" | "off";

package/src/core/domain/ports.ts

@@ -2,6 +2,7 @@ import type { AgentTurnScope, TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import type { TurnAttachments } from "./attachment.ts";
 import type { ChannelKey } from "./conversation.ts";
+import type { InterimPosts } from "./interim.ts";
 
 export type { AgentTurnScope };
 
@@ -32,6 +33,11 @@ export interface TurnRequest {
 	 * schedule's turn is not.
 	 */
 	interactive?: boolean;
+	/**
+	 * Where the turn posts the text it writes before its final answer, as it goes; the caller
+	 * hands the channel its reply goes to. Absent = only the final reply is posted.
+	 */
+	interim?: InterimPosts;
 }
 
 /** The judge's question and answer shapes. */

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

@@ -82,6 +82,8 @@ export function conversationTurns(
 			const hideStop = surfaces.showStop(channel);
 			const turn = { kind, channel, speaker };
 			events.turnStarted(turn);
+			// A claim that posts its own reply formats its own text, so only the default reply posts as it goes.
+			const interim = input.reply ? undefined : surfaces.interim(channel);
 			let result: TurnResult;
 			try {
 				result = await settleTurn(
@@ -102,6 +104,7 @@ export function conversationTurns(
 								...(input.confirmed ? { confirmed: true } : {}),
 								...(input.steerable ? { steerable: true } : {}),
 								...(input.interactive ? { interactive: true } : {}),
+								...(interim ? { interim } : {}),
 							}),
 						),
 					"conversation turn",

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

@@ -41,5 +41,6 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 		unreact: async (channel, messageId, emoji) =>
 			of(channel)?.unreact?.(channel, messageId, emoji),
 		prompts: (channel, speaker) => of(channel)?.prompts?.(channel, speaker),
+		interim: (channel) => of(channel)?.interim?.(channel),
 	};
 }

package/src/core/runtime/extensions/ask-user.ts

@@ -37,7 +37,7 @@ export function askUserExtension(
 		pi.registerTool({
 			name: ASK_USER_TOOL,
 			label: `Ask ${o.name}`,
-			description: `Ask ${o.name} a question on a card with buttons in this channel and wait for ${o.his} answer, within this turn. Use it when you need ${o.his} decision to continue, instead of ending your turn with a question. Offer options when the choices are known; set multi when several may apply and allow_other to let ${o.him} write ${o.his} own answer. ${o.He} has 30 minutes; after that the result says there was no answer.`,
+			description: `Ask ${o.name} a question on a card with buttons in this channel and wait for ${o.his} answer, within this turn. Use it when you need ${o.his} decision to continue, instead of ending your turn with a question. The card should read on its own, so put the context ${o.he} needs in the question too. Offer options when the choices are known; set multi when several may apply and allow_other to let ${o.him} write ${o.his} own answer. ${o.He} has 30 minutes; after that the result says there was no answer.`,
 			parameters: Type.Object(
 				{
 					question: Type.String({ minLength: 1, maxLength: 1500 }),

package/src/core/runtime/interim-text.ts

@@ -0,0 +1,207 @@
+import type { InterimMessage, InterimPosts } from "../domain/interim.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { Logger } from "../log.ts";
+import {
+	DISCORD_MESSAGE_LIMIT,
+	splitReply,
+} from "../presentation/reply-splitter.ts";
+import { textOf } from "../shared/session-messages.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+
+/** An intermediate text this long or longer is posted as an ordinary message. */
+export const PRIMARY_CHARS = 400;
+/** The progress message is edited at most this often; its last state always lands. */
+export const PROGRESS_EDIT_MS = 1_500;
+
+const STRUCTURE = /^\s{0,3}(#{1,6}\s|```|~~~|[-*+]\s|\d+[.)]\s|\|.*\|)/m;
+
+/**
+ * Whether an intermediate text is content the owner must read, such as a proposal or findings:
+ * long, or written with a Markdown heading, list, table, or code fence. Shorter narration
+ * between tool calls goes to the progress message instead.
+ */
+export function isPrimaryText(
+	text: string,
+	primaryChars = PRIMARY_CHARS,
+): boolean {
+	return text.length >= primaryChars || STRUCTURE.test(text);
+}
+
+/**
+ * A run's progress message: its narration lines, then the tools it called, all in Discord's
+ * small text and kept inside one message by dropping the oldest lines behind a "…" marker.
+ */
+export function progressText(
+	lines: readonly string[],
+	tools: ReadonlyMap<string, number>,
+): string {
+	const small = (line: string) => `-# ${line}`;
+	const toolLine =
+		tools.size > 0
+			? small(
+					[...tools]
+						.map(([name, count]) => (count > 1 ? `${name} ×${count}` : name))
+						.join(" · "),
+				).slice(0, DISCORD_MESSAGE_LIMIT)
+			: undefined;
+	const body = lines
+		.flatMap((text) => text.split("\n"))
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map(small);
+	const tail = toolLine ? [toolLine] : [];
+	const fits = (kept: string[]) =>
+		[...kept, ...tail].join("\n").length <= DISCORD_MESSAGE_LIMIT;
+	if (fits(body)) return [...body, ...tail].join("\n");
+	const marker = small("…");
+	let kept = body;
+	while (kept.length > 0 && !fits([marker, ...kept])) kept = kept.slice(1);
+	if (kept.length === 0 && body.length > 0) {
+		// One line alone is too long: keep its end.
+		const room =
+			DISCORD_MESSAGE_LIMIT - [marker, ...tail].join("\n").length - 4;
+		const last = body.at(-1) ?? "";
+		kept = room > 0 ? [small(`…${last.slice(-room)}`)] : [];
+		return [...kept, ...tail].join("\n");
+	}
+	return [marker, ...kept, ...tail].join("\n");
+}
+
+interface Run {
+	lines: string[];
+	tools: Map<string, number>;
+	message?: InterimMessage;
+	shown?: string;
+	lastAt: number;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface InterimPosterOptions {
+	logger: Logger;
+	channel: string;
+	primaryChars?: number;
+	editMs?: number;
+}
+
+/**
+ * Posts a turn's intermediate text as it goes. A tool-calling assistant message whose text is
+ * primary is posted as ordinary messages; shorter text joins the run's progress message with
+ * the tools called, edited in place. A primary post or a card starts a new run. Posts go out
+ * in order, and a failed one is logged, never thrown.
+ */
+export class InterimPoster {
+	readonly #posts: InterimPosts;
+	readonly #options: InterimPosterOptions;
+	#queue: Promise<void> = Promise.resolve();
+	#run: Run = newRun();
+
+	constructor(posts: InterimPosts, options: InterimPosterOptions) {
+		this.#posts = posts;
+		this.#options = options;
+	}
+
+	/** A finished message of the turn; only a tool-calling assistant message is posted. */
+	messageEnd(message: {
+		role: string;
+		content?: unknown;
+		stopReason?: string;
+	}): void {
+		if (message.role !== "assistant" || message.stopReason !== "toolUse")
+			return;
+		const text = textOf(message.content).trim();
+		if (!text) return;
+		if (isPrimaryText(text, this.#options.primaryChars)) {
+			this.#endRun();
+			for (const chunk of splitReply(text))
+				this.#enqueue(async () => {
+					await this.#posts.post(chunk);
+				}, "interim text not posted");
+			return;
+		}
+		this.#run.lines.push(text);
+		this.#changed();
+	}
+
+	/** A tool the turn started, counted on the run's tool line. */
+	toolStart(name: string): void {
+		const { tools } = this.#run;
+		tools.set(name, (tools.get(name) ?? 0) + 1);
+		this.#changed();
+	}
+
+	/**
+	 * Brings every post up to date and waits for them, then starts a new run: before a card, so
+	 * the text written before it shows above it, and when the turn ends, before its final reply.
+	 */
+	async flush(): Promise<void> {
+		this.#endRun();
+		await this.#queue;
+	}
+
+	#endRun(): void {
+		const run = this.#run;
+		this.#run = newRun();
+		clearTimeout(run.timer);
+		run.timer = undefined;
+		this.#render(run);
+	}
+
+	/** The run changed: shown now, or once the edit interval has passed. */
+	#changed(): void {
+		const run = this.#run;
+		if (run.timer) return;
+		const wait =
+			run.lastAt + (this.#options.editMs ?? PROGRESS_EDIT_MS) - now();
+		if (wait <= 0) {
+			this.#render(run);
+			return;
+		}
+		run.timer = setTimeout(() => {
+			run.timer = undefined;
+			this.#render(run);
+		}, wait);
+	}
+
+	#render(run: Run): void {
+		if (run.lines.length === 0 && run.tools.size === 0) return;
+		run.lastAt = now();
+		const text = progressText(run.lines, run.tools);
+		this.#enqueue(async () => {
+			if (text === run.shown) return;
+			if (run.message) await run.message.edit(text);
+			else run.message = await this.#posts.post(text);
+			run.shown = text;
+		}, "progress message not posted");
+	}
+
+	#enqueue(step: () => Promise<void>, failure: string): void {
+		const { logger, channel } = this.#options;
+		this.#queue = this.#queue.then(step).catch((error: unknown) => {
+			logger.warn({ channel, err: error }, failure);
+		});
+	}
+}
+
+/** The turn's poster, when its caller gave a place for interim posts and the host left them on. */
+export function interimPoster(
+	request: Pick<TurnRequest, "interim" | "channel">,
+	options: Pick<
+		PiAgentRuntimeOptions,
+		"interimText" | "interimPrimaryChars" | "logger"
+	>,
+): InterimPoster | undefined {
+	if (!request.interim || options.interimText === "off") return undefined;
+	return new InterimPoster(request.interim, {
+		logger: options.logger,
+		channel: request.channel,
+		...(options.interimPrimaryChars
+			? { primaryChars: options.interimPrimaryChars }
+			: {}),
+	});
+}
+
+function newRun(): Run {
+	return { lines: [], tools: new Map(), lastAt: 0 };
+}
+
+const now = () => Date.now();

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

@@ -36,6 +36,7 @@ import {
 	confirmedTurnText,
 } from "./extensions/confirmation-gate.ts";
 import { COMPACT_TOOL } from "./extensions/self-compact-guard.ts";
+import { interimPoster } from "./interim-text.ts";
 import { PromptSlot, workTimeout } from "./prompt-slot.ts";
 import {
 	type PiAgentRuntimeOptions,
@@ -181,9 +182,17 @@ export class PiAgentRuntime implements AgentRuntime {
 		// Collected as they end: a compaction during the turn shortens session.messages.
 		const turnMessages: TurnMessage[] = [];
 		const toolCalls: string[] = [];
+		// Text written before the final answer is posted as the turn goes; the final reply stays the caller's.
+		const interim = interimPoster(request, this.#options);
 		const unsubscribe = session.subscribe((event) => {
-			if (event.type === "tool_execution_start") toolCalls.push(event.toolName);
-			if (event.type === "message_end") turnMessages.push(event.message);
+			if (event.type === "tool_execution_start") {
+				toolCalls.push(event.toolName);
+				interim?.toolStart(event.toolName);
+			}
+			if (event.type === "message_end") {
+				turnMessages.push(event.message);
+				interim?.messageEnd(event.message);
+			}
 		});
 		const slot = this.#sessions.slot(key);
 		slot.bind(
@@ -191,6 +200,7 @@ export class PiAgentRuntime implements AgentRuntime {
 				? this.#options.prompts?.(request.channel, request.speaker)
 				: undefined,
 			request.agent?.name ?? assistantName(),
+			interim ? () => interim.flush() : undefined,
 		);
 		// Time spent waiting on the owner's cards does not count towards the timeout.
 		const cancelTimeout = workTimeout(turnTimeoutMs, slot, () => {
@@ -237,6 +247,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			cancelTimeout();
 			slot.unbind();
 			unsubscribe();
+			await interim?.flush();
 			gate.endTurn();
 			const usage = session.getContextUsage();
 			if (usage)

package/src/core/runtime/prompt-slot.ts

@@ -10,14 +10,23 @@ import { assistantName } from "../i18n/index.ts";
  */
 export class PromptSlot {
 	#prompts: OwnerPrompts | undefined;
+	#beforeCard: (() => Promise<void>) | undefined;
 	#asker = assistantName();
 	#open = 0;
 	#openSince = 0;
 	#waited = 0;
 
-	/** Binds the turn's prompts; `asker` names who asks, the assistant or an agent. */
-	bind(prompts: OwnerPrompts | undefined, asker: string): void {
+	/**
+	 * Binds the turn's prompts; `asker` names who asks, the assistant or an agent. `beforeCard`
+	 * runs before each card opens, such as posting the text the turn wrote before it.
+	 */
+	bind(
+		prompts: OwnerPrompts | undefined,
+		asker: string,
+		beforeCard?: () => Promise<void>,
+	): void {
 		this.#prompts = prompts;
+		this.#beforeCard = beforeCard;
 		this.#asker = asker;
 		this.#open = 0;
 		this.#waited = 0;
@@ -25,6 +34,7 @@ export class PromptSlot {
 
 	unbind(): void {
 		this.#prompts = undefined;
+		this.#beforeCard = undefined;
 	}
 
 	get asker(): string {
@@ -49,6 +59,7 @@ export class PromptSlot {
 	}
 
 	async #waiting<T>(ask: () => Promise<T>): Promise<T> {
+		await this.#beforeCard?.();
 		if (this.#open++ === 0) this.#openSince = Date.now();
 		try {
 			return await ask();

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

@@ -6,6 +6,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { AgentSessions, LoadedSkill } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { Logger } from "../log.ts";
@@ -66,6 +67,13 @@ export interface PiAgentRuntimeOptions {
 	toolTiers?: ToolTiers;
 	/** A run that takes longer, not counting time spent waiting on the owner's cards, is aborted and reported as failed. */
 	turnTimeoutMs?: number;
+	/**
+	 * Whether a turn given a place for interim posts shows the text it writes before its final
+	 * answer as it goes; default "on". "off" posts only the final reply.
+	 */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
 	/** How long a new session waits for its MCP tools to register. */
 	mcpConnectTimeoutMs?: number;
 }

package/src/index.ts

@@ -88,6 +88,11 @@ export {
 	MemoryError,
 	ScheduleError,
 } from "./core/domain/errors.ts";
+export type {
+	InterimMessage,
+	InterimPosts,
+	InterimTextMode,
+} from "./core/domain/interim.ts";
 export type {
 	Approval,
 	AskOption,