pi-roundtable 0.8.0 → 0.9.1

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

@@ -1,7 +1,5 @@
 import { rmSync } from "node:fs";
-import { join } from "node:path";
 import {
-	type AgentSession,
 	type ModelRuntime,
 	SessionManager,
 } from "@earendil-works/pi-coding-agent";
@@ -15,42 +13,40 @@ import type {
 	TranscriptEntry,
 	TurnResult,
 } from "../domain/conversation.ts";
-import { AgentRunError, ConfigError } from "../domain/errors.ts";
+import { AgentRunError } from "../domain/errors.ts";
 import type { TurnRequest } from "../domain/ports.ts";
+import { HostStoppingError } from "../errors.ts";
 import { assistantName } from "../i18n/index.ts";
-import {
-	AUTO_THINKING,
-	parseModelRef,
-	type ThinkingLevel,
-	type ThinkingSetting,
-} from "../models.ts";
+import { promptScopeOf } from "../interactions/prompts.ts";
+import { MEMORY_TOOLS } from "../modules/memory/owner-memory.ts";
 import { withoutReplyFiles } from "../reply-files.ts";
-import { planOrder, type TransientTask } from "../sessions.ts";
-import { textOf } from "../shared/session-messages.ts";
-import { addressee, type Speaker, type Tier } from "../speakers.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";
 import { ConversationSessions } from "./conversation-sessions.ts";
-import { ASK_USER_TOOL } from "./extensions/ask-user.ts";
-import {
-	ConfirmationGate,
-	confirmedTurnText,
-} from "./extensions/confirmation-gate.ts";
-import {
-	COMPACT_TOOL,
-	missingToolsError,
-} from "./extensions/self-compact-guard.ts";
+import { confirmedTurnText } from "./extensions/confirmation-gate.ts";
+import { loadsMemory } from "./extensions/private-memory.ts";
+import { missingToolsError } from "./extensions/self-compact-guard.ts";
 import { interimPoster } from "./interim-text.ts";
+import { preflightTools } from "./preflight-tools.ts";
 import { PromptSlot, workTimeout } from "./prompt-slot.ts";
-import {
-	type PiAgentRuntimeOptions,
-	TRANSCRIPT_ENTRY_CHARS,
-	type TurnMessage,
-} from "./runtime-types.ts";
+import { carriesMemory, recordMemoryTurn } from "./reader-history.ts";
+import type { PiAgentRuntimeOptions, TurnMessage } from "./runtime-types.ts";
 import { archiveSessions } from "./session-archive.ts";
+import {
+	memoryReader,
+	refusedSpeaker,
+	turnAddressee,
+} from "./session-conversation.ts";
 import { SessionFactory } from "./session-factory.ts";
-import { type PromptImages, SteerableRun } from "./steerable-run.ts";
-import { lastReply, turnAnswer } from "./turn-answer.ts";
+import { promptImages, SteerableRun } from "./steerable-run.ts";
+import { thinkingLevel } from "./thinking-level.ts";
+import { runningCalls } from "./tool-call-scope.ts";
+import { transcriptOf, turnAnswer, unspokenTurn } from "./turn-answer.ts";
 import { progressReporter } from "./turn-progress.ts";
+import { wrapUpTurn } from "./turn-wrapup.ts";
 import { workerReport } from "./worker-task.ts";
 
 export {
@@ -60,6 +56,8 @@ export {
 	sessionExtensions,
 } from "./runtime-types.ts";
 
+const MEMORY = new Set<string>(MEMORY_TOOLS);
+
 /** AgentRuntime over the Pi SDK: one persistent session per channel, each with its own loader. */
 const STOPPED = "stopped by the owner";
 
@@ -73,10 +71,11 @@ export class PiAgentRuntime implements AgentRuntime {
 	/** The tier and speaker of each conversation's running turn. */
 	readonly #turns = new Map<
 		ChannelKey,
-		{ tier: Tier; speaker: Speaker | undefined }
+		{ tier: Tier; speaker: Speaker; withheld: boolean }
 	>();
 	/** 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>();
 
 	/** Builds the runtime without starting a session; the preflight proves it can run. */
 	constructor(options: PiAgentRuntimeOptions) {
@@ -85,7 +84,8 @@ export class PiAgentRuntime implements AgentRuntime {
 		this.#tiers = options.toolTiers ?? toolTiers();
 		this.#factory = new SessionFactory(options, {
 			speaker: (channel) => this.#turns.get(channel)?.speaker,
-			runTask: (channel, task) => this.#runTask(channel, task),
+			withholdsMemory: (channel) => this.#turns.get(channel)?.withheld === true,
+			runTask: (scope, task) => this.#runTask(scope, task),
 		});
 		this.#sessions = new ConversationSessions(
 			options,
@@ -94,50 +94,80 @@ export class PiAgentRuntime implements AgentRuntime {
 		);
 	}
 
-	/**
-	 * Proves the model and every required tool resolve, in a throwaway session that runs no turn;
-	 * startup stops here before anything connects.
-	 */
+	/** Resolves the model and required tools in throwaway shared and private sessions, without a turn. */
 	async preflight(): Promise<void> {
-		const probe = await this.#factory.create(
-			"probe:startup",
-			SessionManager.inMemory(this.#factory.workDir()),
-			new ConfirmationGate(this.#factory.link().holds, this.#options.owner),
-			new PromptSlot(),
-			join(this.#factory.workDir(), "probe-attachments"),
-			undefined,
-			"owner",
-		);
-		const registered = new Set(
-			probe.session.getAllTools().map((tool) => tool.name),
+		const required = this.#factory.requiredTools();
+		const registered = await preflightTools(
+			this.#factory,
+			this.#options.owner,
+			required,
 		);
-		probe.session.dispose();
-		const expected = [
-			...this.#factory.link().requiredTools,
-			COMPACT_TOOL,
-			ASK_USER_TOOL,
-			...planOrder(this.#factory.plan).flatMap(
-				(tool) => tool.snapshot().requiredTools ?? [],
-			),
-		];
-		const missing = expected.filter((name) => !registered.has(name));
+		const missing = required.filter((name) => !registered.has(name));
 		if (missing.length > 0) throw missingToolsError(missing);
 	}
 
 	// pi-lens-ignore: high-complexity, high-fan-out, mixed-async-styles — one turn's lifecycle end to end; batch 4 splits it with the channel router
 	async runTurn(request: TurnRequest): Promise<TurnResult> {
 		const { logger, turnTimeoutMs = 10 * 60_000 } = this.#options;
+		if (!request.speaker) return unspokenTurn();
+		// A turn that is only asked for now, such as a group's next member, starts nothing.
+		if (this.#options.stopping?.())
+			return {
+				ok: false,
+				error: new AgentRunError(new HostStoppingError().message),
+			};
 		const key = request.agent?.session ?? request.channel;
-		const channelSession = await this.#sessions.freshSession(key, request);
+		// Resolve current scope; refuse a foreign private speaker before touching its session.
+		const conversation = await this.#sessions.conversation(key, request);
+		const refused = refusedSpeaker(conversation, request.speaker);
+		if (refused) return { ok: false, error: new AgentRunError(refused) };
+		const scoped = { ...request, conversation };
+		const channelSession = await this.#sessions.freshSession(key, scoped);
+		const who = turnAddressee(
+			request.speaker,
+			channelSession,
+			this.#options.owner,
+		);
 		const { session } = channelSession;
-		const level = await this.#thinkingLevel(key, session, request);
+		const agentModel = chosenAgentModel(request.agent?.name, this.#options);
+		const bridgeRefused =
+			conversation.visibility === "shared"
+				? await bridgeTurnRefusal(
+						request.agent?.name,
+						this.#options,
+						{
+							messages: session.messages,
+							sessionManager: session.sessionManager,
+							reader: request.speaker.principalId,
+						},
+						agentModel,
+					)
+				: undefined;
+		if (bridgeRefused)
+			return { ok: false, error: new AgentRunError(bridgeRefused) };
+		const level = await thinkingLevel(
+			{
+				modelRuntime: this.#modelRuntime,
+				effort: this.#options.effort,
+				judged: this.#sessions.judged,
+			},
+			key,
+			session,
+			request,
+			agentModel,
+		);
 		if (session.thinkingLevel !== level) session.setThinkingLevel(level);
 		const gate = await this.#sessions.gate(key, request.agent !== undefined);
 		const pending = gate.pending();
 		const registered = new Set(session.getAllTools().map((tool) => tool.name));
-		// The speaker's tier limits the tools; a turn nobody spoke in, such as the owner's own chat, is the owner's.
-		const tier = request.speaker?.tier ?? "owner";
+		// The speaker's tier limits the tools.
+		const { tier } = request.speaker;
 		// An approving turn also has the held calls' tools, which a dispatched worker may have used.
+		// The agent server may keep a speaker below the owner tier out of memory: no tools, no block.
+		const withheld =
+			request.agent !== undefined &&
+			this.#options.agents?.memory === "owners" &&
+			tier !== "owner";
 		const wanted = toolsForTier(
 			[
 				...new Set([
@@ -149,8 +179,17 @@ export class PiAgentRuntime implements AgentRuntime {
 			],
 			tier,
 			this.#tiers,
+		).filter((name) => !withheld || !MEMORY.has(name));
+		const markPrivateMemory = recordMemoryTurn(
+			session.sessionManager,
+			request.speaker.principalId,
+			!withheld &&
+				channelSession.memory !== "none" &&
+				memoryReader(conversation, request.speaker) !== undefined &&
+				loadsMemory(registered),
 		);
-		this.#turns.set(key, { tier, speaker: request.speaker });
+		this.#memoryTurns.set(key, markPrivateMemory);
+		this.#turns.set(key, { tier, speaker: request.speaker, withheld });
 		const missing = wanted.filter((name) => !registered.has(name));
 		if (missing.length > 0) {
 			logger.warn(
@@ -167,8 +206,8 @@ export class PiAgentRuntime implements AgentRuntime {
 		gate.beginTurn(
 			request.selection.id,
 			request.confirmed === true,
-			addressee(request.speaker, this.#options.owner),
-			request.speaker?.id,
+			who,
+			request.speaker,
 		);
 		if (request.confirmed && pending) {
 			logger.info(
@@ -196,6 +235,7 @@ export class PiAgentRuntime implements AgentRuntime {
 				interim?.toolStart(event.toolName);
 			}
 			if (event.type === "message_end") {
+				if (carriesMemory(event.message)) markPrivateMemory();
 				turnMessages.push(event.message);
 				interim?.messageEnd(event.message);
 			}
@@ -203,22 +243,34 @@ export class PiAgentRuntime implements AgentRuntime {
 		const slot = this.#sessions.slot(key);
 		slot.bind(
 			request.interactive
-				? this.#options.prompts?.(request.channel, request.speaker)
+				? this.#options.prompts?.(request.channel, promptScopeOf(scoped))
 				: undefined,
 			request.agent?.name ?? assistantName(),
 			interim ? () => interim.flush() : undefined,
 		);
+		// A model that ignores the abort must not hold the turn: its session is disposed of instead.
+		const guard = new AbortGuard(session, {
+			graceMs: this.#options.turnAbortGraceMs,
+			onGiveUp: () => {
+				logger.error(
+					{ channel: request.channel },
+					"turn did not stop after its abort; disposing of its session",
+				);
+				this.#sessions.drop(key, channelSession);
+			},
+		});
 		// Time spent waiting on the owner's cards does not count towards the timeout.
 		const cancelTimeout = workTimeout(turnTimeoutMs, slot, () => {
 			logger.warn(
 				{ channel: request.channel, turnTimeoutMs },
 				"turn timed out; aborting",
 			);
-			void session.abort();
+			guard.abort();
 		});
 		const running = new SteerableRun(
 			session,
 			() => request.steerable === true && !gate.pending(),
+			() => guard.abort(),
 		);
 		this.#running.set(key, running);
 
@@ -226,13 +278,9 @@ export class PiAgentRuntime implements AgentRuntime {
 			const attachments = request.attachments ?? NO_ATTACHMENTS;
 			const text =
 				request.confirmed && pending
-					? confirmedTurnText(
-							pending,
-							request.text,
-							addressee(request.speaker, this.#options.owner),
-						)
+					? confirmedTurnText(pending, request.text, who)
 					: request.text;
-			await running.run(() =>
+			const prompted = running.run(() =>
 				session.prompt(
 					withAttachmentsBlock(text, attachments),
 					attachments.images.length > 0
@@ -240,6 +288,9 @@ export class PiAgentRuntime implements AgentRuntime {
 						: undefined,
 				),
 			);
+			// A run abandoned by the guard may still reject later; nobody waits for it then.
+			prompted.catch(() => undefined);
+			await Promise.race([prompted, guard.gaveUp]);
 		} catch (error) {
 			if (running.stopped)
 				return { ok: false, error: new AgentRunError(STOPPED), stopped: true };
@@ -250,43 +301,22 @@ export class PiAgentRuntime implements AgentRuntime {
 		} finally {
 			this.#running.delete(key);
 			this.#turns.delete(key);
+			this.#memoryTurns.delete(key);
 			cancelTimeout();
+			guard.release();
 			slot.unbind();
 			unsubscribe();
 			progress?.close();
 			await interim?.flush();
-			gate.endTurn();
-			const usage = session.getContextUsage();
-			if (usage)
-				this.#sessions.usage.set(key, {
-					tokens: usage.tokens,
-					contextWindow: usage.contextWindow,
-				});
-			const held = gate.pending();
-			await this.#options.confirmations
-				.save(key, held)
-				// pi-lens-ignore: no-unknown-parameters — a rejection reason is unknown; it only reaches the logger
-				.catch((error: unknown) =>
-					logger.error({ channel: key, err: error }, "held actions not saved"),
-				);
-			if (held)
-				logger.info(
-					{ channel: key, held: held.calls.map((call) => call.action) },
-					"actions held for confirmation",
-				);
-			logger.info(
-				{
-					channel: key,
-					selection: request.selection.id,
-					toolCalls,
-					thinking: session.thinkingLevel,
-					// pi-lens-ignore: no-conditional-empty-object-spread — owner turns keep their log line without a model key
-					...(request.agent
-						? { model: `${session.model?.provider}/${session.model?.id}` }
-						: {}),
-				},
-				"turn finished",
-			);
+			await wrapUpTurn({
+				key,
+				request,
+				session,
+				gate,
+				toolCalls,
+				options: this.#options,
+				recordUsage: (usage) => this.#sessions.usage.set(key, usage),
+			});
 		}
 
 		if (running.stopped)
@@ -331,53 +361,73 @@ export class PiAgentRuntime implements AgentRuntime {
 		return stopped;
 	}
 
-	/**
-	 * Runs a task in a fresh, unsaved session with the selected tools and the channel's
-	 * confirmation gate, and returns its final text.
-	 */
+	/** Runs a task in an unsaved session with the selected tools and conversation's gate. */
 	// pi-lens-ignore: high-fan-out — builds, runs, and disposes one transient session; batch 4 turns it into the core's child-run API
-	async #runTask(channel: ChannelKey, task: TransientTask): Promise<string> {
+	async #runTask(
+		scope: { turn: ChannelKey; home: ChannelKey },
+		task: TransientTask,
+	): Promise<string> {
 		const { dataDir } = this.#options;
 		const { signal } = task;
-		// A worker asks nothing: its held actions wait for the owner's next message.
+		if (this.#options.stopping?.())
+			throw new AgentRunError(new HostStoppingError().message);
+		// A task works at the tier of the turn that started it; without one there is no tier to take.
+		const turn = this.#turns.get(scope.turn);
+		if (!turn)
+			throw new AgentRunError(
+				`a task runs beside a turn of its conversation, at that turn's tier, and ${scope.turn} has no turn running`,
+			);
+		// A worker inherits the starting turn's conversation and memory policy, without asking.
+		const parent = await this.#sessions.session(scope.turn);
+		const { conversation, memory } = parent;
 		const worker = await this.#factory.create(
-			channel,
+			scope.home,
 			SessionManager.inMemory(this.#factory.workDir()),
-			await this.#sessions.gate(channel, false),
+			await this.#sessions.gate(scope.home, false),
 			new PromptSlot(),
-			ownerAttachmentDir(dataDir, channel),
+			ownerAttachmentDir(dataDir, scope.home),
 			undefined,
 			"owner",
+			conversation,
+			{ turn: scope.turn, memory },
 		);
 		const { session } = worker;
 		const toolCalls: string[] = [];
 		const unsubscribe = session.subscribe((event) => {
 			if (event.type === "tool_execution_start") toolCalls.push(event.toolName);
 		});
-		const abort = () => void session.abort();
+		// A worker whose model ignores the abort is given up on, like a turn's.
+		const guard = new AbortGuard(session, {
+			graceMs: this.#options.turnAbortGraceMs,
+		});
+		const abort = () => guard.abort();
 		signal?.addEventListener("abort", abort, { once: true });
 		const timer = setTimeout(abort, task.timeoutMs);
 		try {
 			const registered = new Set(session.getAllTools().map((t) => t.name));
-			const excluded = new Set([...task.exclude, ASK_USER_TOOL]);
-			// A task works at the tier of the turn that started it.
-			const tier = this.#turns.get(channel)?.tier ?? "owner";
+			// A worker that loaded the reader's memory may report it: the call that started it, and the
+			// calls that one runs within, then record their results as the reader's.
+			if (memoryReader(conversation, turn.speaker) && loadsMemory(registered)) {
+				parent.draws.drawn(runningCalls());
+				this.#memoryTurns.get(scope.turn)?.();
+			}
+			const { tier } = turn;
 			worker.tools = this.#factory
-				.toolsFor(task.selection)
+				.taskTools(task.selection, task.exclude)
 				.filter(
-					(name) =>
-						!excluded.has(name) &&
-						registered.has(name) &&
-						this.#tiers.allows(tier, name),
+					(name) => registered.has(name) && this.#tiers.allows(tier, name),
 				);
 			session.setActiveToolsByName([...worker.tools]);
-			await withoutReplyFiles(() => session.prompt(task.text));
+			const prompted = withoutReplyFiles(() => session.prompt(task.text));
+			prompted.catch(() => undefined);
+			await Promise.race([prompted, guard.gaveUp]);
 			return workerReport(
 				session.messages,
 				"the worker stopped before it reported",
 			);
 		} finally {
 			clearTimeout(timer);
+			guard.release();
 			signal?.removeEventListener("abort", abort);
 			unsubscribe();
 			session.dispose();
@@ -416,84 +466,18 @@ export class PiAgentRuntime implements AgentRuntime {
 	async heldActions(
 		session: ChannelKey,
 	): Promise<PendingConfirmation | undefined> {
-		const gate = await this.#sessions.gate(session, true);
-		return gate.pending();
+		return this.#sessions.held(session);
 	}
 
 	async recentTranscript(
 		channel: ChannelKey,
 		limit: number,
 	): Promise<TranscriptEntry[]> {
-		const { session } = await this.#sessions.session(channel);
-		const entries: TranscriptEntry[] = [];
-		for (const message of session.messages) {
-			if (message.role !== "user" && message.role !== "assistant") continue;
-			const text = textOf(message.content).trim();
-			if (text)
-				entries.push({
-					role: message.role,
-					text: text.slice(0, TRANSCRIPT_ENTRY_CHARS),
-				});
-		}
-		return entries.slice(-limit);
-	}
-
-	/**
-	 * The turn's thinking level: an agent's fixed setting, or the judge's pick, which is kept for the
-	 * next turn while the judge is unsure. An agent session also switches to the agent's model here.
-	 */
-	async #thinkingLevel(
-		key: ChannelKey,
-		session: AgentSession,
-		request: TurnRequest,
-	): Promise<ThinkingLevel> {
-		const setting = request.agent
-			? await this.#useAgentModel(session, request.agent.name)
-			: AUTO_THINKING;
-		if (setting !== AUTO_THINKING) {
-			this.#sessions.judged.delete(key);
-			return setting;
-		}
-		const level = await this.#options.effort.judge(request.text, {
-			reply: lastReply(session.messages),
-			level: this.#sessions.judged.get(key),
-		});
-		this.#sessions.judged.set(key, level);
-		return level;
-	}
-
-	/** Switches an agent session to the agent's current model; returns its thinking setting. */
-	async #useAgentModel(
-		session: AgentSession,
-		name: string,
-	): Promise<ThinkingSetting> {
-		const agents = this.#options.agents;
-		if (!agents)
-			throw new ConfigError("agent turns need the runtime's agents option");
-		const { model, thinking } = agents.modelOf(name);
-		const ref = parseModelRef(model);
-		if (
-			session.model?.provider !== ref?.provider ||
-			session.model?.id !== ref?.id
-		) {
-			const resolved = ref && this.#modelRuntime.getModel(ref.provider, ref.id);
-			if (!resolved)
-				throw new AgentRunError(
-					`${name}'s model ${model} is not available on this host`,
-				);
-			await session.setModel(resolved);
-		}
-		return thinking;
+		await this.#sessions.held(channel);
+		return transcriptOf(await this.#sessions.messages(channel), limit);
 	}
 
 	dispose(): void {
 		this.#sessions.dispose();
 	}
 }
-
-function promptImages(attachments: TurnAttachments): PromptImages {
-	return attachments.images.map((image) => ({
-		type: "image" as const,
-		...image,
-	}));
-}

package/src/core/runtime/preflight-tools.ts

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { ConfirmationGate } from "./extensions/confirmation-gate.ts";
+import { PromptSlot } from "./prompt-slot.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+import type { SessionFactory } from "./session-factory.ts";
+
+/**
+ * Tools available in either startup scope, without running a turn or retaining a session.
+ * The private probe is built only when the shared one lacks a required tool, so a host
+ * without scoped tools starts exactly as before.
+ */
+export async function preflightTools(
+	factory: SessionFactory,
+	owner: PiAgentRuntimeOptions["owner"],
+	required: readonly string[],
+): Promise<Set<string>> {
+	const registered = new Set<string>();
+	for (const conversation of [
+		{ visibility: "shared" },
+		{ visibility: "private", principalId: owner.id },
+	] as const) {
+		if (
+			conversation.visibility === "private" &&
+			required.every((name) => registered.has(name))
+		)
+			break;
+		const probe = await factory.create(
+			conversation.visibility === "shared"
+				? "probe:startup"
+				: "probe:startup-private",
+			SessionManager.inMemory(factory.workDir()),
+			new ConfirmationGate(factory.link().holds, owner),
+			new PromptSlot(),
+			join(factory.workDir(), "probe-attachments"),
+			undefined,
+			"owner",
+			conversation,
+		);
+		try {
+			for (const tool of probe.session.getAllTools()) registered.add(tool.name);
+		} finally {
+			probe.session.dispose();
+		}
+	}
+	return registered;
+}

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

@@ -1,5 +1,5 @@
-import type { OwnerPrompts, OwnerQuestion } from "../domain/owner-prompts.ts";
 import { assistantName } from "../i18n/index.ts";
+import type { OwnerQuestion, Prompts } from "../interactions/prompts.ts";
 
 /**
  * A run's way to ask the owner while it works. A turn they started or a report turn binds the
@@ -9,7 +9,7 @@ import { assistantName } from "../i18n/index.ts";
  * leaves out.
  */
 export class PromptSlot {
-	#prompts: OwnerPrompts | undefined;
+	#prompts: Prompts | undefined;
 	#beforeCard: (() => Promise<void>) | undefined;
 	#asker = assistantName();
 	#open = 0;
@@ -21,7 +21,7 @@ export class PromptSlot {
 	 * runs before each card opens, such as posting the text the turn wrote before it.
 	 */
 	bind(
-		prompts: OwnerPrompts | undefined,
+		prompts: Prompts | undefined,
 		asker: string,
 		beforeCard?: () => Promise<void>,
 	): void {
@@ -42,7 +42,7 @@ export class PromptSlot {
 	}
 
 	/** The turn's prompts, each open card counted as waiting; undefined when none is bound. */
-	get prompts(): OwnerPrompts | undefined {
+	get prompts(): Prompts | undefined {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
 		return {