pi-roundtable 0.7.15 → 0.7.17

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/conversation-sessions.ts

@@ -63,12 +63,17 @@ export class ConversationSessions {
 	async gate(key: ChannelKey, agent: boolean): Promise<ConfirmationGate> {
 		let gate = this.#gates.get(key);
 		if (!gate) {
-			const workspace = agent ? this.#options.agents?.workDir : undefined;
+			const agents = agent ? this.#options.agents : undefined;
 			gate = new ConfirmationGate(
 				this.#factory.link().holds,
 				this.#options.owner,
 				await this.#options.confirmations.load(key),
-				workspace,
+				agents
+					? {
+							workspace: agents.workDir,
+							...(agents.scratchDir ? { scratchDir: agents.scratchDir } : {}),
+						}
+					: {},
 				this.#tiers,
 			);
 			this.#gates.set(key, gate);

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/extensions/confirmation-gate.ts

@@ -4,7 +4,7 @@ import type {
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import type { OwnerPrompts } from "../../domain/owner-prompts.ts";
-import { type HoldCheck, higherTier } from "../../holds.ts";
+import { type HoldCheck, type HoldContext, higherTier } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
 import type { ToolTiers } from "../../tool-tiers.ts";
@@ -60,18 +60,18 @@ export class ConfirmationGate {
 	readonly #owner: OwnerIdentity;
 	/** Whom the running turn's held actions and refusals speak of: the turn's speaker. */
 	#addressee: OwnerIdentity;
-	readonly #workspace: string | undefined;
+	readonly #context: HoldContext;
 	readonly #tiers: ToolTiers | undefined;
 
 	/**
 	 * `holds` decides which calls wait for the owner. With a workspace, the session has a shell,
-	 * and its writes outside the workspace are held too.
+	 * and its writes outside the workspace and the context's scratch dir are held too.
 	 */
 	constructor(
 		holds: HoldCheck,
 		owner: OwnerIdentity,
 		pending?: PendingConfirmation,
-		workspace?: string,
+		context: HoldContext = {},
 		tiers?: ToolTiers,
 	) {
 		this.#tiers = tiers;
@@ -79,7 +79,7 @@ export class ConfirmationGate {
 		this.#owner = owner;
 		this.#addressee = owner;
 		this.#pending = pending;
-		this.#workspace = workspace;
+		this.#context = context;
 	}
 
 	/** Held actions awaiting the owner's answer; expired ones count as none. */
@@ -156,8 +156,7 @@ export class ConfirmationGate {
 
 	/** 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.#workspace === undefined ? {} : { workspace: this.#workspace };
+		const context = this.#context;
 		const action = this.#holds(tool, input, context);
 		if (!action) return undefined;
 		const minTier = this.#holds.approvalTier?.(tool, input, context);

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

@@ -3,9 +3,11 @@ import { join } from "node:path";
 import {
 	type AgentSession,
 	createAgentSession,
+	createBashToolDefinition,
 	DefaultResourceLoader,
 	type ModelRuntime,
 	type SessionManager,
+	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
@@ -279,6 +281,10 @@ export class SessionFactory {
 		const { session } = await createAgentSession({
 			cwd,
 			agentDir,
+			// Pi's bash under its own name, run with TMPDIR at the agents' scratch dir.
+			...(agents?.scratchDir
+				? { customTools: [scratchBash(cwd, agents.scratchDir)] }
+				: {}),
 			thinkingLevel: thinking,
 			modelRuntime: this.#modelRuntime,
 			resourceLoader,
@@ -305,3 +311,13 @@ export class SessionFactory {
 		return Object.assign(state, { session });
 	}
 }
+
+/** Pi's bash tool with TMPDIR set to `scratchDir`, so `mktemp` and tools write there. */
+export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
+	return createBashToolDefinition(cwd, {
+		spawnHook: (context) => ({
+			...context,
+			env: { ...context.env, TMPDIR: scratchDir },
+		}),
+	}) as unknown as ToolDefinition;
+}

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,

package/src/kit/index.ts

@@ -44,6 +44,24 @@ export {
 	thinkingLabel,
 } from "./domain.ts";
 export { holdChain } from "./holds.ts";
+export type {
+	JevCompactInput,
+	JevCompactOptions,
+	JevCompactOutcome,
+	JevCompactor,
+	JevCompactRequest,
+	JevExtensionOptions,
+	JevSkipReason,
+} from "./jev.ts";
+export {
+	isRuleLoad,
+	JEV_COMPACTION_ENGINE,
+	JEV_GOAL,
+	JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS,
+	jevCompact,
+	jevCompactionExtension,
+	jevCompactor,
+} from "./jev.ts";
 export type {
 	EffortBrief,
 	EffortJudgeOptions,
@@ -79,8 +97,10 @@ export {
 } from "./presentation.ts";
 export { packageDir, serveUnix } from "./process.ts";
 export {
+	type PushPolicy,
 	SHELL_TOOLS,
 	shellHoldRule,
+	shellHoldRuleFor,
 } from "./shell.ts";
 export {
 	checkRepoName,