pi-roundtable 0.9.3 → 0.9.6

package/src/core/runtime/compaction-tiers.ts

@@ -1,9 +1,12 @@
 import {
+	buildSessionProjection,
 	type ExtensionAPI,
 	type ExtensionFactory,
 	estimateTokens,
 	type SessionBeforeCompactEvent,
+	type SessionEntry,
 	type SessionManager,
+	type SessionProjection,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
@@ -29,8 +32,14 @@ export type CompactionHistory = Pick<
 export interface LatestCompaction {
 	id: string;
 	engine: CompactionEngine;
-	/** Estimated context the compaction left: its summary and the entries it kept. */
+	/**
+	 * The context the compaction left, as a request sends it: system prompt and tools included.
+	 * The first request after it reports this; until then, its summary and kept entries plus the
+	 * fixed part the last request before it carried.
+	 */
 	contextTokens: number;
+	/** Whether a request after the compaction reported `contextTokens`, or it is still estimated. */
+	measured: boolean;
 }
 
 /** The extension's compactions record its `engine` in their details; Pi's own do not. */
@@ -44,6 +53,41 @@ export function compactionEngine(
 		: "pi";
 }
 
+/** What a request sent, as its reply's usage reports it: undefined for a reply without usable usage. */
+function sentTokens(entry: SessionEntry | undefined): number | undefined {
+	if (entry?.type !== "message") return undefined;
+	const message = entry.message;
+	if (message.role !== "assistant") return undefined;
+	if (message.stopReason === "aborted" || message.stopReason === "error")
+		return undefined;
+	const { input, cacheRead, cacheWrite } = message.usage;
+	const sent = input + cacheRead + cacheWrite;
+	return sent > 0 ? sent : undefined;
+}
+
+function estimated(messages: SessionProjection["messages"]): number {
+	let tokens = 0;
+	for (const message of messages) tokens += estimateTokens(message);
+	return tokens;
+}
+
+/**
+ * The part of a request that is not the conversation, system prompt and tool definitions, as the
+ * last reply before `index` reported it: what that request sent less the estimate of its messages.
+ */
+function fixedTokens(branch: readonly SessionEntry[], index: number): number {
+	for (let at = index - 1; at >= 0; at--) {
+		const sent = sentTokens(branch[at]);
+		if (sent === undefined) continue;
+		const messages = buildSessionProjection(
+			branch.slice(0, at),
+			branch[at - 1]?.id ?? null,
+		).messages;
+		return Math.max(0, sent - estimated(messages));
+	}
+	return 0;
+}
+
 /** The branch's latest compaction, measured from the session as it stands now. */
 export function latestCompaction(
 	history: CompactionHistory,
@@ -56,16 +100,22 @@ export function latestCompaction(
 	const upToCompaction = new Set(
 		branch.slice(0, index + 1).map((each) => each.id),
 	);
-	let contextTokens = 0;
+	const engine = compactionEngine(entry.details, extensionEngine);
+	for (const after of branch.slice(index + 1)) {
+		const sent = sentTokens(after);
+		if (sent !== undefined)
+			return { id: entry.id, engine, contextTokens: sent, measured: true };
+	}
+	let messages = 0;
 	for (const projected of history.buildSessionProjection().entries) {
 		if (!upToCompaction.has(projected.sourceEntry.id)) continue;
-		for (const message of projected.messages)
-			contextTokens += estimateTokens(message);
+		messages += estimated(projected.messages);
 	}
 	return {
 		id: entry.id,
-		engine: compactionEngine(entry.details, extensionEngine),
-		contextTokens,
+		engine,
+		contextTokens: messages + fixedTokens(branch, index),
+		measured: false,
 	};
 }
 
@@ -124,12 +174,15 @@ export class CompactionTiers {
 		this.#extensionEngine = extensionEngine;
 	}
 
-	/** The latest compaction; measured once per compaction, since pi checks before every request. */
+	/**
+	 * The latest compaction; pi checks before every request, so it is measured once per compaction
+	 * after a request reports it, and estimated again until one does.
+	 */
 	latest(): LatestCompaction | undefined {
 		const branch = this.#history.getBranch();
 		const entry = branch.findLast((each) => each.type === "compaction");
 		if (!entry) return undefined;
-		if (this.#cached?.id !== entry.id) {
+		if (this.#cached?.id !== entry.id || !this.#cached.latest.measured) {
 			const latest = latestCompaction(this.#history, this.#extensionEngine);
 			if (!latest) return undefined;
 			this.#cached = { id: entry.id, latest };

package/src/core/runtime/conversation-sessions.ts

@@ -107,6 +107,8 @@ export class ConversationSessions {
 						}
 					: {},
 				this.#tiers,
+				// Owner sessions have no shell workspace but still send files from their own directory.
+				agents ? agents.workDir : this.#factory.cwd(undefined),
 			);
 			this.#gates.set(key, gate);
 			this.#restored.delete(key);

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

@@ -1,7 +1,7 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { messages } from "../../i18n/index.ts";
-import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import { type OwnerIdentity, ownerWords, PRONOUNS } from "../../identity.ts";
 import type { OwnerAnswer, OwnerQuestion } from "../../interactions/prompts.ts";
 import { toolText } from "../../shared/tool-result.ts";
 import type { PromptSlot } from "../prompt-slot.ts";
@@ -10,12 +10,14 @@ export const ASK_USER_TOOL = "ask_user";
 
 /** The tool's result: what the owner chose and wrote. */
 export function answerText(
-	answer: OwnerAnswer | undefined,
+	answer: OwnerAnswer | "pending" | undefined,
 	owner: OwnerIdentity,
 ): string {
 	const o = ownerWords(owner);
+	if (answer === "pending")
+		return `${o.name} has not answered yet. The card stays open, so do not ask again and do not wait for it. End your turn now: say briefly that you are waiting for ${o.his} answer on the card. When ${o.he} answers, a new turn brings you the answer and you continue from there.`;
 	if (!answer)
-		return `No answer: ${o.name} did not answer in time. Go on without it if you safely can, otherwise ask in your reply.`;
+		return `No answer: ${o.name} did not answer. Go on without it if you safely can, otherwise ask in your reply.`;
 	const lines = [
 		...(answer.choices.length > 0
 			? [`${o.name} chose: ${answer.choices.join("; ")}`]
@@ -25,6 +27,15 @@ export function answerText(
 	return lines.length > 0 ? lines.join("\n") : `${o.name} chose nothing.`;
 }
 
+/** The turn a late answer starts: the question it answers and what was chosen and written. */
+export function lateAnswerText(
+	question: string,
+	answer: OwnerAnswer,
+	by: string,
+): string {
+	return `(${by} answered your earlier ask_user question on its card, after your turn had ended. Continue from where you stopped, with this answer.)\nQuestion: ${question}\n${answerText(answer, { name: by, pronouns: PRONOUNS.they })}`;
+}
+
 /** Registers ask_user, which asks the owner on a card in the turn's channel and waits. */
 export function askUserExtension(
 	slot: PromptSlot,
@@ -37,7 +48,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. 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.`,
+			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. If ${o.he} does not answer soon, the result says so and the card stays open: then end your turn saying you are waiting, and ${o.his} answer comes in a new turn.`,
 			parameters: Type.Object(
 				{
 					question: Type.String({ minLength: 1, maxLength: 1500 }),
@@ -88,6 +99,12 @@ export function askUserExtension(
 							messages().askTitle(slot.asker),
 							question,
 							signal,
+							{
+								late: (late) =>
+									late.kind === "question"
+										? lateAnswerText(p.question, late.answer, late.by)
+										: undefined,
+							},
 						),
 						addressee?.() ?? owner,
 					),

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -1,3 +1,5 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import type {
 	HeldCall,
@@ -6,7 +8,7 @@ import type {
 import { type HoldCheck, type HoldContext, higherTier } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
-import type { Prompts } from "../../interactions/prompts.ts";
+import type { LateAnswer, Prompts } from "../../interactions/prompts.ts";
 import type { Speaker } from "../../speakers.ts";
 import type { ToolTiers } from "../../tool-tiers.ts";
 import type { PromptSlot } from "../prompt-slot.ts";
@@ -70,16 +72,22 @@ export class ConfirmationGate {
 	#speaker: Pick<Speaker, "id" | "principalId"> | undefined;
 	#pending: PendingConfirmation | undefined;
 	#approved: HeldCall[] = [];
+	/** Calls approved on their cards after the turn that asked stopped waiting; each runs once, in any turn. */
+	#lateApproved: HeldCall[] = [];
 	readonly #holds: HoldCheck;
 	readonly #owner: OwnerIdentity;
 	/** Whom the running turn's held actions and refusals speak of: the turn's speaker. */
 	#addressee: OwnerIdentity;
 	readonly #context: HoldContext;
 	readonly #tiers: ToolTiers | undefined;
+	/** Where the session's relative file paths resolve, for the sizes a card shows. */
+	readonly #fileRoot: string | undefined;
 
 	/**
 	 * `holds` decides which calls wait for the owner. With a workspace, the session has a shell,
 	 * and its writes outside the workspace and the context's scratch dir are held too.
+	 * `fileRoot` is the session's working directory, where a card resolves relative file paths;
+	 * it defaults to the workspace.
 	 */
 	constructor(
 		holds: HoldCheck,
@@ -87,8 +95,10 @@ export class ConfirmationGate {
 		pending?: PendingConfirmation,
 		context: HoldContext = {},
 		tiers?: ToolTiers,
+		fileRoot?: string,
 	) {
 		this.#tiers = tiers;
+		this.#fileRoot = fileRoot ?? context.workspace;
 		this.#holds = holds;
 		this.#owner = owner;
 		this.#addressee = owner;
@@ -155,11 +165,18 @@ export class ConfirmationGate {
 		if (!ask) return { reason: this.#record(call) };
 		const answer = await ask.prompts.confirm(
 			messages().confirmTitle(ask.asker),
-			approvalCard(call),
+			approvalCard(call, this.#fileRoot),
 			ask.signal,
 			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
+			{ late: (late) => this.#late(call, late) },
 		);
 		if (answer === "approved") return { approvedOnCard: true };
+		if (answer === "pending") {
+			const o = ownerWords(this.#addressee);
+			return {
+				reason: `Awaiting ${o.name}'s approval: this would ${call.action}. Its card stays open, and the call did not run. Do not retry it or ask again in this turn. End your turn now: say briefly that you are waiting for ${o.his} approval on the card. When ${o.he} answers, a new turn tells you.`,
+			};
+		}
 		if (answer === "declined") {
 			const o = ownerWords(this.#addressee);
 			return {
@@ -170,6 +187,18 @@ export class ConfirmationGate {
 		return { reason: this.#record(call) };
 	}
 
+	/**
+	 * A late answer on a call's card: an approval lets the identical call run once, in whichever
+	 * turn makes it next; returns the text of the turn that tells the model.
+	 */
+	#late(call: HeldCall, late: LateAnswer): string | undefined {
+		if (late.kind !== "approval") return undefined;
+		if (!late.approved)
+			return `(${late.by} declined on its card the action you were waiting on: it would ${call.action}. It did not run; do not make the call again. Go on without it, or ask what ${late.by} wants instead.)`;
+		this.#lateApproved.push(call);
+		return `(${late.by} approved on its card the action you were waiting on: it would ${call.action}. Make this call now with exactly this input, and it runs once; then report its result.)\n- ${call.tool} ${call.input}`;
+	}
+
 	/** The call when it needs the owner's confirmation and no approval releases it. */
 	#needing(tool: string, input: Record<string, unknown>): HeldCall | undefined {
 		const context = this.#context;
@@ -182,12 +211,14 @@ export class ConfirmationGate {
 			action,
 			...(minTier ? { minTier } : {}),
 		};
-		const approved = this.#approved.findIndex(
-			(c) => c.tool === call.tool && c.input === call.input,
-		);
-		if (approved !== -1) {
-			this.#approved.splice(approved, 1);
-			return undefined;
+		for (const released of [this.#approved, this.#lateApproved]) {
+			const approved = released.findIndex(
+				(c) => c.tool === call.tool && c.input === call.input,
+			);
+			if (approved !== -1) {
+				released.splice(approved, 1);
+				return undefined;
+			}
 		}
 		return call;
 	}
@@ -229,13 +260,44 @@ export function confirmedTurnText(
 	return `(${owner.name} approved the held actions below with this message. Make each call now with exactly this input.)\n${calls}\n\n${text}`;
 }
 
-/** What an approval card says: the held action's words, then the exact call. */
-export function approvalCard(call: HeldCall): string {
+/**
+ * What an approval card says: the held action's words, the exact call, and each file it sends by
+ * path with the file's size now; relative paths resolve against `workspace`.
+ */
+export function approvalCard(call: HeldCall, workspace?: string): string {
 	const input =
 		call.input.length > CARD_INPUT_CHARS
 			? `${call.input.slice(0, CARD_INPUT_CHARS)}…`
 			: call.input;
-	return `**${call.action}**\n-# \`${call.tool}\`\n\`\`\`json\n${input.replaceAll("```", "`\u200b``")}\n\`\`\``;
+	const files = pathFiles(call.input).map(
+		(path) => `\n-# ${messages().cardFile(path, fileSize(path, workspace))}`,
+	);
+	return `**${call.action}**\n-# \`${call.tool}\`\n\`\`\`json\n${input.replaceAll("```", "`\u200b``")}\n\`\`\`${files.join("")}`;
+}
+
+/** The paths of a call's `files` entries that name one. */
+function pathFiles(input: string): string[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		return [];
+	}
+	const files = isPlainObject(parsed) ? parsed.files : undefined;
+	if (!Array.isArray(files)) return [];
+	return files.flatMap((file: unknown) =>
+		isPlainObject(file) && typeof file.path === "string" ? [file.path] : [],
+	);
+}
+
+/** A file's size in bytes, or undefined when it cannot be read. */
+function fileSize(path: string, workspace: string | undefined) {
+	try {
+		const info = statSync(resolve(workspace ?? "/", path));
+		return info.isFile() ? info.size : undefined;
+	} catch {
+		return undefined;
+	}
 }
 
 /** Without a slot, or with an empty one, every call that needs confirmation is held. */

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

@@ -46,10 +46,12 @@ export class PromptSlot {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
 		return {
-			confirm: (title, message, signal, minTier) =>
-				this.#waiting(() => prompts.confirm(title, message, signal, minTier)),
-			ask: (title, question: OwnerQuestion, signal) =>
-				this.#waiting(() => prompts.ask(title, question, signal)),
+			confirm: (title, message, signal, minTier, wait) =>
+				this.#waiting(() =>
+					prompts.confirm(title, message, signal, minTier, wait),
+				),
+			ask: (title, question: OwnerQuestion, signal, wait) =>
+				this.#waiting(() => prompts.ask(title, question, signal, wait)),
 		};
 	}
 

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

@@ -111,6 +111,8 @@ export const revisionsKey = (plan: SessionPlan) =>
 /** The core's own extensions of one session, which the plan's contributions surround. */
 export interface CoreExtensions {
 	readAttachment: ExtensionFactory;
+	/** `attach_file`, for a session with a workspace. */
+	attachFile?: ExtensionFactory;
 	confirmationGate: ExtensionFactory;
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
@@ -139,6 +141,9 @@ export function sessionExtensions(
 	return [
 		...contributed(plan.tools),
 		{ name: "read-attachment", factory: core.readAttachment },
+		...(core.attachFile
+			? [{ name: "attach-file", factory: core.attachFile }]
+			: []),
 		{ name: "confirmation-gate", factory: core.confirmationGate },
 		{ name: "ask-user", factory: core.askUser },
 		{ name: "self-compact-guard", factory: core.selfCompactGuard },

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

@@ -23,6 +23,10 @@ import {
 	type TransientTask,
 } from "../sessions.ts";
 import { activeToolsExtension } from "../shared/active-tools.ts";
+import {
+	ATTACH_FILE_TOOL,
+	attachFileExtension,
+} from "../shared/attach-file-tool.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
@@ -130,6 +134,8 @@ export class SessionFactory {
 			...currentToolNames(selection.tools, this.#options.logger),
 			COMPACT_TOOL,
 			ASK_USER_TOOL,
+			// Registered only by a session with a workspace.
+			ATTACH_FILE_TOOL,
 			...groups
 				.filter((group) => selection.groups.includes(group.name))
 				.flatMap((group) => group.tools),
@@ -201,12 +207,14 @@ export class SessionFactory {
 
 	/**
 	 * Logs who compacted a conversation, the compaction extension or Pi's summary, by how much, and the context size
-	 * that compacts it next, so a move to the hard ceiling shows.
+	 * that compacts it next, so a move to the hard ceiling shows. `contextAfter` is the context the tiers measure,
+	 * system prompt and tools included, which `tokensAfter`, the conversation alone, leaves out.
 	 */
 	#logCompaction(
 		channel: ChannelKey,
 		event: CompactionEnd,
 		session: AgentSession,
+		tiers: CompactionTiers,
 	): void {
 		const { logger } = this.#options;
 		const trigger = event.reason === "manual" ? "self" : event.reason;
@@ -233,6 +241,7 @@ export class SessionFactory {
 				),
 				tokensBefore: event.result.tokensBefore,
 				tokensAfter: event.result.estimatedTokensAfter,
+				contextAfter: tiers.latest()?.contextTokens,
 				nextCompactionAt:
 					model &&
 					model.contextWindow -
@@ -332,6 +341,14 @@ export class SessionFactory {
 			},
 			conversation,
 			addressee,
+			...(agents
+				? {
+						workspace: {
+							workspace: cwd,
+							...(agents.scratchDir ? { scratchDir: agents.scratchDir } : {}),
+						},
+					}
+				: {}),
 			attachmentDir,
 			get memory() {
 				return state.memory;
@@ -353,6 +370,9 @@ export class SessionFactory {
 			additionalExtensionPaths: this.link().extensionPaths,
 			extensionFactories: sessionExtensions(this.plan, context, {
 				readAttachment: readAttachmentExtension(attachmentDir),
+				...(context.workspace
+					? { attachFile: attachFileExtension(context.workspace) }
+					: {}),
 				confirmationGate: confirmationGateExtension(gate, slot),
 				askUser: askUserExtension(slot, addressee, () =>
 					turnAddressee(
@@ -406,7 +426,7 @@ export class SessionFactory {
 		await this.#awaitTools(session, awaited);
 		session.subscribe((event) => {
 			if (event.type === "compaction_end")
-				this.#logCompaction(channel, event, session);
+				this.#logCompaction(channel, event, session, tiers);
 		});
 		return Object.assign(state, { session });
 	}

package/src/core/sessions.ts

@@ -83,6 +83,11 @@ export interface SessionContext {
 	 * it reads `"none"` for that turn alone.
 	 */
 	memory: "speaker" | "none";
+	/**
+	 * The shared workspace of a session with a shell, and its scratch dir: the roots its shell writes
+	 * in without a hold, and where its tools may read a file by path. Absent for a session without one.
+	 */
+	workspace?: { workspace: string; scratchDir?: string };
 	/** Where the session's conversation keeps the files people attached; absent when the session keeps none. */
 	attachmentDir?: string;
 	/** The person the session's running turn is for; undefined between turns. */
@@ -124,6 +129,7 @@ export interface SessionTool {
 /** Extensions the core places itself; no contribution may take their names. */
 const CORE_EXTENSIONS = [
 	"read-attachment",
+	"attach-file",
 	"confirmation-gate",
 	"ask-user",
 	"self-compact-guard",

package/src/core/shared/attach-file-tool.ts

@@ -0,0 +1,72 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	attachReplyFile,
+	REPLY_FILE_LIMITS,
+	ReplyFileError,
+} from "../reply-files.ts";
+import { toolError, toolText } from "./tool-result.ts";
+import {
+	findWorkspaceFile,
+	readWorkspaceFile,
+	WorkspaceFileError,
+	type WorkspaceRoots,
+} from "./workspace-files.ts";
+
+export const ATTACH_FILE_TOOL = "attach_file";
+
+/** Registers `attach_file`, which posts a file from the session's disk with the turn's reply. */
+export function attachFileExtension(roots: WorkspaceRoots): ExtensionFactory {
+	return (pi) => {
+		pi.registerTool({
+			name: ATTACH_FILE_TOOL,
+			label: "Attach file",
+			description:
+				"Show a file you have on disk, such as a picture you made, by attaching it to your reply in this conversation. Give its path inside the workspace or the scratch dir; never read an image or base64 a file to show it.",
+			parameters: Type.Object(
+				{
+					path: Type.String({
+						minLength: 1,
+						maxLength: 4096,
+						description:
+							"The file's path inside the workspace or the scratch dir.",
+					}),
+					filename: Type.Optional(
+						Type.String({
+							minLength: 1,
+							maxLength: 255,
+							description:
+								"The name it is posted under, without a path; defaults to the path's base name.",
+						}),
+					),
+				},
+				{ additionalProperties: false },
+			),
+			execute: async (_toolCallId, params) => {
+				try {
+					const file = await findWorkspaceFile(params.path, roots);
+					if (file.size > REPLY_FILE_LIMITS.maxFileBytes)
+						throw new ReplyFileError(
+							`${params.path} is ${file.size} bytes; a reply file may contain at most ${REPLY_FILE_LIMITS.maxFileBytes} bytes.`,
+						);
+					const data = await readWorkspaceFile(
+						file,
+						REPLY_FILE_LIMITS.maxFileBytes,
+					);
+					const name = params.filename ?? file.name;
+					attachReplyFile({ name, data });
+					return toolText(
+						`${name} (${data.byteLength} bytes) will appear with your reply.`,
+					);
+				} catch (error) {
+					if (
+						error instanceof WorkspaceFileError ||
+						error instanceof ReplyFileError
+					)
+						return toolError(`Not attached: ${error.message}`);
+					throw error;
+				}
+			},
+		});
+	};
+}

package/src/core/shared/workspace-files.ts

@@ -0,0 +1,76 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+/** Where a session may read files by path: its shared workspace and its scratch dir. */
+export interface WorkspaceRoots {
+	workspace: string;
+	scratchDir?: string;
+}
+
+/** A file refused by path; its message names the path and is safe to show the model. */
+export class WorkspaceFileError extends Error {
+	override name = "WorkspaceFileError";
+}
+
+/** A local file found inside the roots, not read yet. */
+export interface WorkspaceFile {
+	/** The path as the caller gave it. */
+	path: string;
+	/** Where it resolves, symlinks followed. */
+	realPath: string;
+	/** Its base name, the default name it is sent under. */
+	name: string;
+	size: number;
+}
+
+/** Whether `child` is `parent` or inside it. */
+function within(parent: string, child: string): boolean {
+	const rel = relative(parent, child);
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+async function realRoot(root: string): Promise<string | undefined> {
+	return realpath(root).catch(() => undefined);
+}
+
+/**
+ * Finds a regular file by path, relative paths against the workspace, and refuses one that does
+ * not resolve inside the workspace or the scratch dir, so a symlink counts by its target.
+ */
+export async function findWorkspaceFile(
+	path: string,
+	roots: WorkspaceRoots,
+): Promise<WorkspaceFile> {
+	const given = resolve(roots.workspace, path);
+	let real: string;
+	try {
+		real = await realpath(given);
+	} catch {
+		throw new WorkspaceFileError(`${path} does not exist.`);
+	}
+	const allowed = await Promise.all(
+		[roots.workspace, roots.scratchDir]
+			.filter((root): root is string => root !== undefined)
+			.map(realRoot),
+	);
+	if (!allowed.some((root) => root !== undefined && within(root, real)))
+		throw new WorkspaceFileError(
+			`${path} is outside the workspace${roots.scratchDir ? " and the scratch dir" : ""}; only files inside ${roots.scratchDir ? "them" : "it"} can be sent.`,
+		);
+	const info = await stat(real);
+	if (!info.isFile()) throw new WorkspaceFileError(`${path} is not a file.`);
+	return { path, realPath: real, name: basename(given), size: info.size };
+}
+
+/** Reads a file `findWorkspaceFile` found; a file that grew past `maxBytes` since is refused. */
+export async function readWorkspaceFile(
+	file: WorkspaceFile,
+	maxBytes: number,
+): Promise<Uint8Array> {
+	const data = new Uint8Array(await readFile(file.realPath));
+	if (data.byteLength > maxBytes)
+		throw new WorkspaceFileError(
+			`${file.path} is ${data.byteLength} bytes, over the ${maxBytes} allowed.`,
+		);
+	return data;
+}

package/src/core/testing/thread-host.ts

@@ -5,6 +5,7 @@ import {
 	DispatchThreads,
 	type ThreadHost,
 } from "../discord/dispatch-threads.ts";
+import type { InterimMessage } from "../domain/interim.ts";
 import { silentLogger } from "../log.ts";
 
 /** A ThreadHost that records what happens; parents in `hostless` cannot host threads. */
@@ -14,6 +15,8 @@ export class FakeThreadHost implements ThreadHost {
 	readonly opened: { parentId: string; name: string; id: string }[] = [];
 	readonly posts: { threadId: string; text: string }[] = [];
 	readonly closed: string[] = [];
+	/** Edits of messages `send` posted, in order; each also changes its entry in `posts`. */
+	readonly edits: { threadId: string; text: string }[] = [];
 	readonly hostless = new Set<string>();
 	failOpen = false;
 	#next = 900;
@@ -35,6 +38,17 @@ export class FakeThreadHost implements ThreadHost {
 		this.posts.push({ threadId, text });
 	}
 
+	async send(threadId: string, text: string): Promise<InterimMessage> {
+		const post = { threadId, text };
+		this.posts.push(post);
+		return {
+			edit: async (change) => {
+				post.text = change;
+				this.edits.push({ threadId, text: change });
+			},
+		};
+	}
+
 	async close(threadId: string): Promise<void> {
 		this.closed.push(threadId);
 	}

package/src/index.ts

@@ -162,11 +162,13 @@ export { SYSTEM_PRINCIPAL } from "./core/identity/principal-store.ts";
 export type {
 	Approval,
 	AskOption,
+	LateAnswer,
 	OwnerAnswer,
 	OwnerPrompts,
 	OwnerQuestion,
 	PromptScope,
 	Prompts,
+	PromptWait,
 } from "./core/interactions/prompts.ts";
 export { promptScope } from "./core/interactions/prompts.ts";
 export type { JudgeModel } from "./core/judging/model-judge.ts";