pi-roundtable 0.8.0 → 0.9.0

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

@@ -7,12 +7,24 @@ import type {
 } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { InterimTextMode } from "../domain/interim.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
 import type { OwnerIdentity } from "../identity.ts";
+import type { PromptScope } from "../interactions/prompts.ts";
 import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
-import type { ModelRef, ThinkingLevel } from "../models.ts";
+import {
+	formatModelRef,
+	type ModelRef,
+	type ThinkingLevel,
+} from "../models.ts";
 import type { PluginContext, RoundtablePlugin } from "../plugin.ts";
-import { RUNTIME } from "../services.ts";
+import { CONVERSATIONS, IDENTITY, RUNTIME } from "../services.ts";
 import type { Speaker } from "../speakers.ts";
+import {
+	BRIDGE_MEMORY_FIX,
+	bridgeMemoryProblem,
+	liveBridgeRefusal,
+	onClaudeBridge,
+} from "./bridge-guard.ts";
 import { PendingConfirmationStore } from "./pending-confirmation-store.ts";
 import { PiAgentRuntime } from "./pi-agent-runtime.ts";
 
@@ -63,6 +75,10 @@ export interface RuntimePluginOptions {
 	interimText?: InterimTextMode;
 	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
 	interimPrimaryChars?: number;
+	/** Whether the host keeps each person's memory; bridge turns then check private history. */
+	memory?: boolean;
+	/** Why the configuration lets several people speak in a shared conversation, as `configuredCrowd` says. */
+	crowd?: string;
 }
 
 /**
@@ -79,18 +95,36 @@ export function runtimePlugin(
 		PendingConfirmationStore.attach(context.database()),
 ): RoundtablePlugin {
 	let runtime: AgentRuntime | undefined;
+	let identity: IdentityService | undefined;
+	let warn: ((message: string) => void) | undefined;
+	// Admission is a startup risk warning, not proof that this conversation holds private history.
+	const bridgeRefusal = liveBridgeRefusal({
+		memory: options.memory,
+		crowd: options.crowd,
+		identity: () => identity,
+		primary: options.owner.id,
+	});
 	return {
 		name: RUNTIME_PLUGIN,
 		migrations: PendingConfirmationStore.migrations(),
 		provides: [RUNTIME],
 		preflight: async () => {
+			if (onClaudeBridge(options.model)) {
+				const why = await bridgeRefusal();
+				if (why)
+					warn?.(
+						`${bridgeMemoryProblem(formatModelRef(options.model), why)} ${BRIDGE_MEMORY_FIX}`,
+					);
+			}
 			await runtime?.preflight?.();
 		},
 		setup: async (context) => {
-			const { logger, providers } = context;
+			const { logger, providers, services } = context;
+			identity = services.find(IDENTITY);
+			warn = (message) => logger.warn({}, message);
 			const heldActions = await openHeldActions(context);
-			const prompts = (channel: ChannelKey, speaker?: Speaker) =>
-				context.surfaces.prompts(channel, speaker);
+			const prompts = (channel: ChannelKey, scope?: PromptScope | Speaker) =>
+				context.surfaces.prompts(channel, scope);
 			const agents = () => options.agents?.current();
 			const running: AgentRuntime = providers.filled.has("runtime")
 				? providers.runtime(
@@ -108,6 +142,17 @@ export function runtimePlugin(
 					)
 				: new PiAgentRuntime({
 						owner: options.owner,
+						// Read at every turn that names no conversation, after every plugin set up.
+						conversationOf: async (key) => {
+							const record = await services.find(CONVERSATIONS)?.get(key);
+							if (!record) return undefined;
+							return record.visibility === "private" &&
+								record.principalId !== undefined
+								? { visibility: "private", principalId: record.principalId }
+								: { visibility: "shared" };
+						},
+						principalOf: async (id) => services.find(IDENTITY)?.principal(id),
+						memory: options.memory === true,
 						sessions: context.sessions,
 						agentDir: options.agentDir,
 						modelRuntime: options.modelRuntime,

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

@@ -7,20 +7,24 @@ import type {
 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 { TurnConversation } from "../domain/ports.ts";
+import type { Principal } from "../identity/principal-store.ts";
 import type { OwnerIdentity } from "../identity.ts";
+import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
 import type { ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
 	type SessionContext,
+	type SessionConversation,
 	type SessionPlan,
 	type SessionTool,
 } from "../sessions.ts";
-import type { Speaker } from "../speakers.ts";
 import type { ToolTiers } from "../tool-tiers.ts";
+import type { MemoryDraws } from "./extensions/private-memory.ts";
 import type { PendingConfirmationStore } from "./pending-confirmation-store.ts";
+import { scopedCalls } from "./tool-call-scope.ts";
 
 export type TurnMessage = Extract<
 	AgentSessionEvent,
@@ -33,8 +37,19 @@ export type CompactionEnd = Extract<
 export const TRANSCRIPT_ENTRY_CHARS = 1000;
 
 export interface PiAgentRuntimeOptions {
-	/** Who the conversations serve, as prompts and tool results name them. */
-	owner: OwnerIdentity;
+	/**
+	 * The primary owner, by their principal id: their conversations' prompts and tool results name
+	 * them as configured, and the host's own turns address them.
+	 */
+	owner: OwnerIdentity & { id: string };
+	/**
+	 * The host's record of a conversation, read at every turn that names none, so a record changed
+	 * while its session is open counts, and when its transcript is read; without it, or without a
+	 * record, the conversation is as its open session or its history was made, else shared.
+	 */
+	conversationOf?: (key: ChannelKey) => Promise<TurnConversation | undefined>;
+	/** A principal's name and pronouns, which a private conversation's tool descriptions use. */
+	principalOf?: (id: string) => Promise<Principal | undefined>;
 	agentDir: string;
 	/** Shared by the host's sessions, so logins refresh in one place. */
 	modelRuntime: ModelRuntime;
@@ -56,13 +71,11 @@ export interface PiAgentRuntimeOptions {
 	/** The agent server's sessions: their shared workspace, model, and skills. */
 	agents?: AgentSessions;
 	/**
-	 * Cards the owner answers in a channel, for interactive turns; undefined for a channel that
-	 * cannot show them. Without it every held action waits for their next message.
+	 * The prompts of a channel for an interactive turn's scope, made from its speaker and its
+	 * conversation's visibility; undefined for a channel that cannot show them. Without it every
+	 * held action waits for a message that approves it.
 	 */
-	prompts?: (
-		channel: ChannelKey,
-		speaker?: Speaker,
-	) => OwnerPrompts | undefined;
+	prompts?: (channel: ChannelKey, scope?: PromptScope) => Prompts | undefined;
 	/** The lowest tier that may use each tool; the default names the core's tools and leaves the rest to the owner. */
 	toolTiers?: ToolTiers;
 	/** A run that takes longer, not counting time spent waiting on the owner's cards, is aborted and reported as failed. */
@@ -76,6 +89,8 @@ export interface PiAgentRuntimeOptions {
 	interimPrimaryChars?: number;
 	/** How long a new session waits for its MCP tools to register. */
 	mcpConnectTimeoutMs?: number;
+	/** Defaults to true: bridge shared turns refuse raw private exchanges inaccessible to the reader. */
+	memory?: boolean;
 }
 
 export type { AgentSessions, LoadedSkill };
@@ -91,12 +106,14 @@ export interface CoreExtensions {
 	confirmationGate: ExtensionFactory;
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
+	privateMemory: ExtensionFactory;
 	activeTools: ExtensionFactory;
 }
 
 /**
  * A session's extensions in load order: the tools phase, the core's attachment, gate, ask-user,
- * and compact guard, the compactor, the MCP phase, and active-tools last, so its
+ * and compact guard, the compactor, the MCP phase, the memory projection, so each request is
+ * projected after every other extension changed it, and active-tools last, so its
  * before_agent_start handler runs after every other extension's.
  */
 export function sessionExtensions(
@@ -107,7 +124,9 @@ export function sessionExtensions(
 	const contributed = (tools: readonly SessionTool[]) =>
 		tools.flatMap((tool) => {
 			const factory = tool.snapshot().factory(session);
-			return factory ? [{ name: tool.name, factory }] : [];
+			return factory
+				? [{ name: tool.name, factory: scopedCalls(factory) }]
+				: [];
 		});
 	return [
 		...contributed(plan.tools),
@@ -117,6 +136,7 @@ export function sessionExtensions(
 		{ name: "self-compact-guard", factory: core.selfCompactGuard },
 		...contributed(plan.compaction ? [plan.compaction] : []),
 		...contributed(plan.mcp),
+		{ name: "private-memory", factory: core.privateMemory },
 		{ name: "active-tools", factory: core.activeTools },
 	];
 }
@@ -129,4 +149,12 @@ export interface ChannelSession {
 	revisions: string;
 	/** The skills an agent session was built with, as skillsKey. */
 	skills: string;
+	/** Whom the session's conversation serves, fixed when it was built. */
+	conversation: SessionConversation;
+	/** Whom its tool descriptions address. */
+	addressee: OwnerIdentity;
+	/** Whose memory its turns read, as resolved when it was built; a worker beside it keeps the same. */
+	memory: SessionContext["memory"];
+	/** Its tool calls running now, which a task that reads the reader's memory marks as drawing on it. */
+	draws: MemoryDraws;
 }

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

@@ -0,0 +1,143 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { TurnConversation, TurnRequest } from "../domain/ports.ts";
+import {
+	type Principal,
+	SYSTEM_PRINCIPAL,
+} from "../identity/principal-store.ts";
+import { addresseeOf, type OwnerIdentity } from "../identity.ts";
+import type { SessionConversation } from "../sessions.ts";
+import { addressee, type Speaker, THE_SPEAKER } from "../speakers.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+
+/**
+ * Whom a conversation serves as something says so: an agent's is shared; another is as the turn
+ * says, else as the host's record says; undefined when neither does.
+ */
+export async function namedConversation(
+	key: ChannelKey,
+	request: Pick<TurnRequest, "agent" | "conversation"> | undefined,
+	options: Pick<PiAgentRuntimeOptions, "conversationOf">,
+): Promise<TurnConversation | undefined> {
+	if (request?.agent) return { visibility: "shared" };
+	return request?.conversation ?? (await options.conversationOf?.(key));
+}
+
+/**
+ * Whom a new session's conversation serves: as the turn or the host's record names it, else
+ * shared, never the owner's by default. A private one's person is looked up for their name and
+ * pronouns.
+ */
+export async function sessionConversation(
+	key: ChannelKey,
+	request: Pick<TurnRequest, "agent" | "conversation"> | undefined,
+	options: Pick<PiAgentRuntimeOptions, "conversationOf" | "principalOf">,
+): Promise<SessionConversation> {
+	const given = await namedConversation(key, request, options);
+	if (given?.visibility !== "private") return { visibility: "shared" };
+	const principal = await options.principalOf?.(given.principalId);
+	return {
+		visibility: "private",
+		principalId: given.principalId,
+		...(principal ? { principal } : {}),
+	};
+}
+
+/** Whether the turn names its conversation otherwise than the session was made for, so it is rebuilt. */
+export function conversationChanged(
+	session: SessionConversation,
+	given: TurnConversation | undefined,
+): boolean {
+	if (!given) return false;
+	if (given.visibility !== session.visibility) return true;
+	return (
+		given.visibility === "private" &&
+		session.visibility === "private" &&
+		given.principalId !== session.principalId
+	);
+}
+
+/**
+ * Whom a session's tool descriptions address: the primary owner as configured, so their own
+ * conversations read as in 0.8; another private conversation's person by their name and
+ * pronouns; and the speaker, unnamed, in a shared one or a private one of someone the host has
+ * no name for.
+ */
+export function sessionAddressee(
+	conversation: SessionConversation,
+	owner: OwnerIdentity & { id: string },
+): OwnerIdentity {
+	if (conversation.visibility !== "private") return THE_SPEAKER;
+	if (conversation.principalId === owner.id) return owner;
+	const named = namedPrincipal(conversation);
+	return named ? addresseeOf(named) : THE_SPEAKER;
+}
+
+/**
+ * A private conversation's person, when the host knows them by a name: one carried over from 0.8
+ * may be named by their id alone until someone names them, and an id is no name to address.
+ */
+export function namedPrincipal(
+	conversation: SessionConversation,
+): Principal | undefined {
+	if (conversation.visibility !== "private") return undefined;
+	const { principal } = conversation;
+	return principal && principal.displayName !== principal.id
+		? principal
+		: undefined;
+}
+
+/**
+ * Whom a turn's approvals and answers name: a private conversation's person as its session
+ * addresses them; the host's own turns and the primary owner as the owner; anyone else, a
+ * second owner too, by their name.
+ */
+export function turnAddressee(
+	speaker: Speaker | undefined,
+	session: { conversation: SessionConversation; addressee: OwnerIdentity },
+	owner: OwnerIdentity & { id: string },
+): OwnerIdentity {
+	const { conversation } = session;
+	if (
+		speaker &&
+		conversation.visibility === "private" &&
+		speaker.principalId === conversation.principalId &&
+		session.addressee !== THE_SPEAKER
+	)
+		return session.addressee;
+	const own =
+		!speaker ||
+		speaker.principalId === owner.id ||
+		speaker.principalId === SYSTEM_PRINCIPAL;
+	return own ? owner : addressee({ ...speaker, tier: "member" }, owner);
+}
+
+/**
+ * Whose memory a session's running turn reads: a private conversation's person's, whoever speaks
+ * in it, and in a shared one the speaker's; no one's for the host's own turns there, nor while
+ * no turn runs.
+ */
+export function memoryReader(
+	conversation: SessionConversation,
+	speaker: Speaker | undefined,
+): string | undefined {
+	if (conversation.visibility === "private") return conversation.principalId;
+	if (!speaker || speaker.principalId === SYSTEM_PRINCIPAL) return undefined;
+	return speaker.principalId;
+}
+
+/**
+ * Why a turn may not run in the session's conversation: someone other than its person speaking
+ * in a private one. The host's own turns may.
+ */
+export function refusedSpeaker(
+	conversation: SessionConversation,
+	speaker: Speaker,
+): string | undefined {
+	if (conversation.visibility !== "private") return undefined;
+	if (
+		speaker.principalId === conversation.principalId ||
+		speaker.principalId === SYSTEM_PRINCIPAL
+	)
+		return undefined;
+	return `the conversation is private to ${conversation.principalId}, so a turn of ${speaker.principalId} may not run in it`;
+}

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

@@ -17,6 +17,7 @@ import type { LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
 	type SessionContext,
+	type SessionConversation,
 	type SessionPlan,
 	type ToolSelection,
 	type TransientTask,
@@ -24,7 +25,8 @@ import {
 import { activeToolsExtension } from "../shared/active-tools.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
-import { addressee, type Speaker, THE_SPEAKER } from "../speakers.ts";
+import { type Speaker, THE_SPEAKER } from "../speakers.ts";
+import { currentToolNames } from "../tool-tiers.ts";
 import {
 	CompactionTiers,
 	compactionEngine,
@@ -35,6 +37,11 @@ import {
 	type ConfirmationGate,
 	confirmationGateExtension,
 } from "./extensions/confirmation-gate.ts";
+import {
+	MemoryDraws,
+	privateCompaction,
+	privateMemoryExtension,
+} from "./extensions/private-memory.ts";
 import {
 	COMPACT_TOOL,
 	selfCompactGuardExtension,
@@ -51,13 +58,26 @@ import {
 	sessionExtensions,
 	skillsKey,
 } from "./runtime-types.ts";
+import {
+	memoryReader,
+	sessionAddressee,
+	turnAddressee,
+} from "./session-conversation.ts";
 
 /** What a session factory asks of the runtime that owns the turns. */
 export interface SessionFactoryDeps {
 	/** The person the conversation's running turn is for. */
 	speaker(channel: ChannelKey): Speaker | undefined;
-	/** Runs a task beside the conversation, under its gate. */
-	runTask(channel: ChannelKey, task: TransientTask): Promise<string>;
+	/** Whether the conversation's running turn loads no memory, as the agent server's option keeps a speaker out of it. */
+	withholdsMemory(channel: ChannelKey): boolean;
+	/**
+	 * Runs a task beside the conversation of `home`, under its gate, at the tier of the running
+	 * turn of `turn`: the conversation's own channel, or an agent's seat in a group.
+	 */
+	runTask(
+		scope: { turn: ChannelKey; home: ChannelKey },
+		task: TransientTask,
+	): Promise<string>;
 }
 
 /** Builds Pi sessions for the runtime: one resource loader per session, its extensions in order. */
@@ -107,7 +127,7 @@ export class SessionFactory {
 			(tool) => tool.snapshot().groups ?? [],
 		);
 		return [
-			...selection.tools,
+			...currentToolNames(selection.tools, this.#options.logger),
 			COMPACT_TOOL,
 			ASK_USER_TOOL,
 			...groups
@@ -116,6 +136,30 @@ export class SessionFactory {
 		];
 	}
 
+	/** The tools of a task beside a turn: its selection without what it excludes, and it never asks. */
+	taskTools(selection: ToolSelection, exclude: readonly string[]): string[] {
+		const excluded = new Set([
+			...currentToolNames(exclude, this.#options.logger),
+			ASK_USER_TOOL,
+		]);
+		return this.toolsFor(selection).filter((name) => !excluded.has(name));
+	}
+
+	/** Every tool startup refuses to run without: the plugins', the core's, and the session tools'. */
+	requiredTools(): string[] {
+		return currentToolNames(
+			[
+				...this.link().requiredTools,
+				COMPACT_TOOL,
+				ASK_USER_TOOL,
+				...planOrder(this.plan).flatMap(
+					(tool) => tool.snapshot().requiredTools ?? [],
+				),
+			],
+			this.#options.logger,
+		);
+	}
+
 	/** Waits for the tools the session tools register late, such as pi-mcp-adapter's after its eager connection. */
 	async #awaitTools(
 		session: AgentSession,
@@ -212,15 +256,41 @@ export class SessionFactory {
 		attachmentDir: string,
 		agent: AgentTurnScope | undefined,
 		kind: string,
+		/** Whom the conversation serves, fixed for the session's life. */
+		conversation: SessionConversation,
+		/**
+		 * A worker's: the conversation whose running turn it acts in, and that conversation's memory
+		 * policy, which it keeps rather than reading its own kind's.
+		 */
+		worker?: { turn: ChannelKey; memory: SessionContext["memory"] },
 	): Promise<ChannelSession> {
 		const { agentDir, model, thinking, logger } = this.#options;
 		// An agent's prompt is set before each run; the other kinds are refused here, before a session is built.
 		const persona = agent ? undefined : this.personaOf(kind);
 		const skills = this.skillsOf(agent);
+		const addressee = agent
+			? THE_SPEAKER
+			: sessionAddressee(conversation, this.#options.owner);
+		// An agent's conversations read each speaker's memory; another kind's, as its persona says;
+		// a worker's, as the conversation it works for.
+		const memory =
+			worker?.memory ??
+			(agent ? "speaker" : (this.link().personaMemory?.(kind) ?? "speaker"));
+		// The running turn is the conversation's: an agent's seat in a group, or its own channel; a
+		// worker's is the turn that started it.
+		const turnKey = worker?.turn ?? agent?.session ?? channel;
+		const deps = this.#deps;
 		const state = {
 			tools: [] as readonly string[],
 			revisions: revisionsKey(this.plan),
 			skills: skillsKey(skills),
+			conversation,
+			addressee,
+			// A turn the agent server keeps out of memory reads none, and so does a worker beside it.
+			get memory(): SessionContext["memory"] {
+				return deps.withholdsMemory(turnKey) ? "none" : memory;
+			},
+			draws: new MemoryDraws(),
 		};
 		const awaited = planOrder(this.plan).flatMap(
 			(tool) => tool.snapshot().awaitTools ?? [],
@@ -240,16 +310,34 @@ export class SessionFactory {
 			homeChannel: channel,
 			turnChannel: agent && agents ? agents.turnChannel(agent) : channel,
 			compaction: {
+				// A shared conversation's compactor summarizes no one's private memory.
 				wrap: (compactor) =>
-					tiers.wrapCompactor(compactor, (bypass) =>
-						logger.info(
-							{ channel, ...bypass, ceiling: HARD_COMPACT_TOKENS },
-							"compaction skips the extension for Pi's summary",
-						),
+					tiers.wrapCompactor(
+						compactor,
+						(bypass) =>
+							logger.info(
+								{ channel, ...bypass, ceiling: HARD_COMPACT_TOKENS },
+								"compaction skips the extension for Pi's summary",
+							),
+						conversation.visibility === "shared"
+							? (event) =>
+									privateCompaction(
+										event.preparation,
+										event.branchEntries.flatMap((entry) =>
+											entry.type === "message" ? [entry.message] : [],
+										),
+									)
+							: undefined,
 					),
 			},
-			speaker: () => this.#deps.speaker(channel),
-			runTask: (task) => this.#deps.runTask(channel, task),
+			conversation,
+			addressee,
+			get memory() {
+				return state.memory;
+			},
+			speaker: () => this.#deps.speaker(turnKey),
+			runTask: (task) =>
+				this.#deps.runTask({ turn: turnKey, home: channel }, task),
 		};
 		if (agent) context.agent = agent;
 		const resourceLoader = new DefaultResourceLoader({
@@ -265,12 +353,23 @@ export class SessionFactory {
 			extensionFactories: sessionExtensions(this.plan, context, {
 				readAttachment: readAttachmentExtension(attachmentDir),
 				confirmationGate: confirmationGateExtension(gate, slot),
-				askUser: askUserExtension(
-					slot,
-					agent ? THE_SPEAKER : this.#options.owner,
-					() => addressee(this.#deps.speaker(channel), this.#options.owner),
+				askUser: askUserExtension(slot, addressee, () =>
+					turnAddressee(
+						this.#deps.speaker(turnKey),
+						state,
+						this.#options.owner,
+					),
 				),
 				selfCompactGuard: selfCompactGuardExtension(),
+				// Each request carries no one's memory but the running turn's reader's.
+				privateMemory: privateMemoryExtension(
+					conversation.visibility === "shared",
+					() =>
+						deps.withholdsMemory(turnKey)
+							? undefined
+							: memoryReader(conversation, deps.speaker(turnKey)),
+					state.draws,
+				),
 				activeTools: activeToolsExtension(() => state.tools),
 			}),
 			// An agent's prompt is set before each run by the agent-prompt extension.
@@ -314,6 +413,7 @@ export class SessionFactory {
 
 /** Pi's bash tool with TMPDIR set to `scratchDir`, so `mktemp` and tools write there. */
 export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
+	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
 	return createBashToolDefinition(cwd, {
 		spawnHook: (context) => ({
 			...context,

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

@@ -0,0 +1,78 @@
+import { existsSync } from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { TurnConversation } from "../domain/ports.ts";
+import { archiveSessions } from "./session-archive.ts";
+
+/** The custom entry a session's history records whom it served in. */
+export const SCOPE_ENTRY = "roundtable-conversation";
+
+/** Whom a conversation serves, as a session's history records it. */
+type Scope = Pick<TurnConversation, "visibility"> & { principalId?: string };
+
+function scopeOf(conversation: Scope): TurnConversation {
+	return conversation.visibility === "private" &&
+		conversation.principalId !== undefined
+		? { visibility: "private", principalId: conversation.principalId }
+		: { visibility: "shared" };
+}
+
+/** Whether two scopes are the same: shared both, or private to the same principal. */
+export function sameScope(a: Scope, b: Scope): boolean {
+	return JSON.stringify(scopeOf(a)) === JSON.stringify(scopeOf(b));
+}
+
+/** The scope the history last recorded, or undefined when it records none, as before 0.9. */
+function recordedScope(manager: SessionManager): TurnConversation | undefined {
+	const entry = manager
+		.getEntries()
+		.findLast(
+			(entry) => entry.type === "custom" && entry.customType === SCOPE_ENTRY,
+		);
+	return entry?.type === "custom"
+		? scopeOf(entry.data as TurnConversation)
+		: undefined;
+}
+
+/**
+ * The latest history in `dir` for a session of the scope. A history recorded in another scope is
+ * archived, so the session starts with none: one person's conversation never replays for someone
+ * else, nor a private one in a shared one or the other way. A history that records no scope, as
+ * one made before 0.9, carries on. The history the session continues records its scope.
+ */
+export function scopedHistory(
+	dir: string,
+	cwd: string,
+	scope: Scope,
+): { history: SessionManager; archived: number } {
+	let history = SessionManager.continueRecent(cwd, dir);
+	const recorded = recordedScope(history);
+	let archived = 0;
+	if (recorded && !sameScope(recorded, scope)) {
+		archived = archiveSessions(dir);
+		history = SessionManager.continueRecent(cwd, dir);
+	}
+	if (!recorded || archived > 0)
+		history.appendCustomEntry(SCOPE_ENTRY, scopeOf(scope));
+	return { history, archived };
+}
+
+/** The scope the latest history in `dir` records, if any. */
+export function historyScope(
+	dir: string,
+	cwd: string,
+): TurnConversation | undefined {
+	if (!existsSync(dir)) return undefined;
+	return recordedScope(SessionManager.continueRecent(cwd, dir));
+}
+
+/**
+ * The messages of the latest history in `dir`, read without opening a session, so reading them
+ * fixes no scope; none when it was recorded in another scope than `scope`.
+ */
+export function historyMessages(dir: string, cwd: string, scope: Scope) {
+	if (!existsSync(dir)) return [];
+	const history = SessionManager.continueRecent(cwd, dir);
+	const recorded = recordedScope(history);
+	if (recorded && !sameScope(recorded, scope)) return [];
+	return history.buildSessionContext().messages;
+}

package/src/core/runtime/steerable-run.ts

@@ -1,7 +1,16 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { TurnAttachments } from "../domain/attachment.ts";
 
 export type PromptImages = NonNullable<Parameters<AgentSession["steer"]>[1]>;
 
+/** A turn's images as Pi takes them with a prompt or a steer. */
+export function promptImages(attachments: TurnAttachments): PromptImages {
+	return attachments.images.map((image) => ({
+		type: "image" as const,
+		...image,
+	}));
+}
+
 /** The part of a Pi session a steerable run drives. */
 export type SteeringSession = Pick<
 	AgentSession,