pi-roundtable 0.7.19 → 0.9.0

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

@@ -1,8 +1,16 @@
 import type { AgentRuntime } from "../contract/runtime.ts";
 import type { SurfacePort } from "../contract/surface.ts";
+import type {
+	ConversationRegistry,
+	ConversationVisibility,
+} from "../conversations/conversation-registry.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type { TurnResult } from "../domain/conversation.ts";
+import type { TurnConversation } from "../domain/ports.ts";
+import type { TurnProgress } from "../domain/progress.ts";
+import { PluginError } from "../errors.ts";
 import { messages } from "../i18n/index.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
 import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
@@ -36,6 +44,11 @@ export interface ConversationTurnInput {
 	 * notice); the claim formats its own. A throw is logged, never rethrown.
 	 */
 	reply?(result: TurnResult): Promise<void>;
+	/**
+	 * How the conversation is recorded at its first turn: `private` to the speaker, or `shared`
+	 * (the default). Later turns keep what the first recorded, and give a title only then.
+	 */
+	conversation?: { visibility: ConversationVisibility; title?: string };
 }
 
 /**
@@ -48,7 +61,13 @@ export interface ConversationTurns {
 	 * task. It shows typing and the stop control on the channel's surface, emits `turnStarted` and
 	 * `turnEnded` with the turn's `kind`, settles a runtime that throws into a failed result, and
 	 * posts the reply, or a failure or stopped notice, through the surface unless `reply` is given.
-	 * It rejects during setup (NotLinkedError) and when the host has no runtime to run the turn on.
+	 * It rejects during setup (NotLinkedError), when the host has no runtime to run the turn on,
+	 * when the conversation cannot be recorded in the host's registry (a database error, or a
+	 * `private` conversation without a speaker), and when the conversation is recorded private to a
+	 * principal other than the speaker's, unless the speaker is the host's own (`SYSTEM_PRINCIPAL`).
+	 * Each of these rejects before the turn starts:
+	 * nothing is shown, no event is emitted, and `reply` is not called, so a claim that answers
+	 * its person tells them itself.
 	 */
 	run(input: ConversationTurnInput): Promise<TurnResult>;
 }
@@ -58,6 +77,8 @@ export interface ConversationTurnsOptions {
 	linked: () => void;
 	/** The runtime that runs the turn; throws PluginError when the host has none yet. */
 	runtime: () => AgentRuntime;
+	/** Where each turn records its conversation; absent, or undefined, records none. */
+	registry?: () => Pick<ConversationRegistry, "register"> | undefined;
 	surfaces: SurfacePort;
 	events: EventSink;
 	/** The plugins' agent selection, read at each turn that gives none of its own. */
@@ -68,6 +89,52 @@ export interface ConversationTurnsOptions {
 /** The selection of a turn that gives none: the plugins' `agentSelection`. */
 const DEFAULT_SELECTION = "turns";
 
+/**
+ * Records the conversation of a turn, private to the speaker when asked, else shared, and returns
+ * who it belongs to as the record keeps it; without a registry, as the turn asks, if it does.
+ */
+async function record(
+	registry: Pick<ConversationRegistry, "register"> | undefined,
+	input: ConversationTurnInput,
+): Promise<TurnConversation | undefined> {
+	const visibility = input.conversation?.visibility ?? "shared";
+	if (visibility === "private" && !input.speaker)
+		throw new PluginError(
+			`a private conversation needs the speaker it belongs to; ${input.channel} was run without one.`,
+		);
+	if (!registry)
+		return input.conversation && conversationOf(visibility, input.speaker);
+	const title = input.conversation?.title;
+	const kept = await registry.register({
+		key: input.channel,
+		kind: input.kind,
+		visibility,
+		...(visibility === "private"
+			? { principalId: input.speaker.principalId }
+			: {}),
+		...(title === undefined ? {} : { title }),
+	});
+	if (kept.visibility !== "private" || kept.principalId === undefined)
+		return { visibility: "shared" };
+	// Only its person, or the host itself, speaks in a private conversation: anyone else's turn would
+	// read and act on what is theirs.
+	const { principalId } = input.speaker;
+	if (principalId !== kept.principalId && principalId !== SYSTEM_PRINCIPAL)
+		throw new PluginError(
+			`${input.channel} is private to ${kept.principalId}, so ${principalId} may not speak in it; run their turn in a conversation of their own.`,
+		);
+	return { visibility: "private", principalId: kept.principalId };
+}
+
+function conversationOf(
+	visibility: ConversationVisibility,
+	speaker: Speaker,
+): TurnConversation {
+	return visibility === "private"
+		? { visibility, principalId: speaker.principalId }
+		: { visibility };
+}
+
 export function conversationTurns(
 	options: ConversationTurnsOptions,
 ): ConversationTurns {
@@ -78,12 +145,26 @@ export function conversationTurns(
 			options.linked();
 			// A host without a runtime is a setup mistake, so it is refused before anything is shown.
 			const runtime = options.runtime();
+			// A conversation that cannot be recorded runs no turn: who it belongs to would be lost.
+			const conversation = await record(options.registry?.(), input);
 			const stopTyping = surfaces.startTyping(channel);
 			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);
+			// What the runtime reports as it goes reaches the surface and the handlers until the turn ends.
+			let live = true;
+			const progress = (event: TurnProgress) => {
+				if (!live) return;
+				events.turnProgress?.({ ...turn, progress: event });
+				// pi-lens-ignore: no-unknown-parameters — a rejection reason is unknown; it only reaches the logger
+				surfaces
+					.progress?.(channel, event)
+					?.catch((error: unknown) =>
+						logger.warn({ channel, kind, err: error }, "progress not shown"),
+					);
+			};
 			let result: TurnResult;
 			try {
 				result = await settleTurn(
@@ -98,6 +179,7 @@ export function conversationTurns(
 								},
 								text: input.text,
 								speaker,
+								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }
 									: {}),
@@ -105,11 +187,13 @@ export function conversationTurns(
 								...(input.steerable ? { steerable: true } : {}),
 								...(input.interactive ? { interactive: true } : {}),
 								...(interim ? { interim } : {}),
+								progress,
 							}),
 						),
 					"conversation turn",
 				);
 			} finally {
+				live = false;
 				hideStop();
 			}
 			events.turnEnded({

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

@@ -1,13 +1,27 @@
 import type { ChatSurface, SurfacePort } from "../contract/surface.ts";
 import { parseChannelKey } from "../contract/surface.ts";
 import { PluginError } from "../errors.ts";
+import {
+	isPromptScope,
+	type PromptScope,
+	promptScope,
+} from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+
+export interface SurfacePortOptions {
+	/** Told when a caller uses a form that goes away, such as `prompts(channel, speaker)`. */
+	deprecated?(message: string): void;
+}
 
 /**
  * The port over the contributed surfaces, each chosen by the prefix of a channel's key. `linked`
  * gives the surfaces once every plugin is set up and throws NotLinkedError before.
  */
-export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
+export function surfacePort(
+	linked: () => readonly ChatSurface[],
+	options: SurfacePortOptions = {},
+): SurfacePort {
 	const of = (channel: ChannelKey): ChatSurface | undefined => {
 		const at = channel.indexOf(":");
 		if (at <= 0) return undefined;
@@ -40,7 +54,26 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 			of(channel)?.react?.(channel, messageId, emoji),
 		unreact: async (channel, messageId, emoji) =>
 			of(channel)?.unreact?.(channel, messageId, emoji),
-		prompts: (channel, speaker) => of(channel)?.prompts?.(channel, speaker),
+		prompts: (channel, scope) =>
+			of(channel)?.prompts?.(channel, scopeOf(scope, options)),
 		interim: (channel) => of(channel)?.interim?.(channel),
+		progress: async (channel, event) => {
+			await of(channel)?.progress?.(channel, event);
+		},
 	};
 }
+
+/**
+ * The scope a surface's prompts get: as given, or, from the 0.8 form's speaker, theirs in a
+ * shared conversation, as 0.8 had them, with a warning.
+ */
+function scopeOf(
+	given: PromptScope | Speaker | undefined,
+	options: SurfacePortOptions,
+): PromptScope | undefined {
+	if (!given || isPromptScope(given)) return given;
+	options.deprecated?.(
+		"deprecated: prompts(channel, speaker) takes a PromptScope since 0.9, made with promptScope(speaker, visibility); a speaker is read as theirs in a shared conversation, and this form goes away in 1.0",
+	);
+	return promptScope(given);
+}

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

@@ -0,0 +1,29 @@
+import type { BackgroundTurn } from "../contract/channels.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+
+/** The turns the host itself made, by identity: a copy, or one a plugin writes, is not one of them. */
+const made = new WeakSet<BackgroundTurn>();
+
+/**
+ * A background turn the host itself starts as the system principal, such as a logged error's
+ * report or a Discord webhook's post, at the tier its starter gives; the router runs it as the
+ * system principal's speaker. Core-internal: a plugin cannot make one, and a turn it writes naming
+ * the system principal is skipped.
+ */
+export function systemTurn(
+	turn: Omit<BackgroundTurn, "author" | "speaker"> & {
+		author: { id: string; name: string };
+	},
+): BackgroundTurn {
+	const own: BackgroundTurn = {
+		...turn,
+		author: { ...turn.author, principalId: SYSTEM_PRINCIPAL },
+	};
+	made.add(own);
+	return own;
+}
+
+/** Whether the host made this very turn with `systemTurn`. */
+export function isSystemTurn(turn: BackgroundTurn): boolean {
+	return made.has(turn);
+}

package/src/core/runtime/bridge-guard.ts

@@ -0,0 +1,225 @@
+import type {
+	AgentSession,
+	ContextWithSystemEvent,
+	ModelRuntime,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentSessions } from "../contract/runtime.ts";
+import { AgentRunError, ConfigError } from "../domain/errors.ts";
+import type { AccessRules, AccessTier } from "../identity/access-policy.ts";
+import type { IdentityService } from "../identity/identity-service.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import {
+	formatModelRef,
+	type ModelRef,
+	parseModelRef,
+	type ThinkingSetting,
+} from "../models.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { guardHidesPrivateExchange } from "./extensions/private-memory.ts";
+import { bridgeHistoryHidesMemoryFor } from "./reader-history.ts";
+
+/**
+ * The Pi provider pi-claude-bridge registers. Its sessions resume the history Claude Code stored
+ * for a conversation, tool results as they came, rather than each request the core projects, so
+ * the core's per-request hiding of private memory does not reach it.
+ */
+export const CLAUDE_BRIDGE = "claude-bridge";
+
+/** Whether the model runs on claude-bridge, by its provider id. */
+export function onClaudeBridge(model: { provider: string }): boolean {
+	return model.provider === CLAUDE_BRIDGE;
+}
+
+/**
+ * Whether the tier admits someone besides the owners: everyone, a role, which anyone may hold, or
+ * an identity that is not already an owner's, since an owner listed again is still one person.
+ */
+const admits = (
+	tier: AccessTier | undefined,
+	owners: ReadonlySet<string>,
+): boolean => {
+	if (!tier) return false;
+	const { everyone } = tier;
+	if (everyone === true || (Array.isArray(everyone) && everyone.length > 0))
+		return true;
+	return (
+		(tier.identities ?? []).some((identity) => !owners.has(identity)) ||
+		(tier.roles?.length ?? 0) > 0
+	);
+};
+
+/**
+ * Why, by the configuration, a shared conversation of the host may have more than one person
+ * speaking in it; undefined when the one owner alone does. More than one owner, rules that admit
+ * admins or members besides the owner's own identities, or a plugin's identity bound to a
+ * principal other than the primary owner's.
+ */
+export function configuredCrowd(
+	rules: Pick<AccessRules, "owners" | "admins" | "members">,
+	plugins: readonly Pick<RoundtablePlugin, "name" | "identities">[],
+): string | undefined {
+	if (rules.owners.length > 1)
+		return `access.owners names ${rules.owners.length} owners`;
+	const owners = new Set(rules.owners.flatMap((owner) => owner.identities));
+	for (const tier of ["admins", "members"] as const)
+		if (admits(rules[tier], owners))
+			return `access.${tier} admits people besides the owner`;
+	const primary = rules.owners[0]?.principal;
+	for (const plugin of plugins)
+		for (const { identity, principal } of plugin.identities ?? [])
+			if (principal !== undefined && principal !== primary)
+				return `plugin ${plugin.name} binds ${identity} to principal ${principal}, not the owner's`;
+	return undefined;
+}
+
+/**
+ * Why, by the roles the host stores, such as those `roundtable principal grant` gives, a shared
+ * conversation may have more than one person speaking in it; undefined when only the primary
+ * owner holds a lasting role.
+ */
+async function grantedCrowd(
+	identity: Pick<IdentityService, "list" | "tierOf" | "owners">,
+	primary: string,
+): Promise<string | undefined> {
+	const owners = await identity.owners();
+	if (owners.length > 1)
+		return `${owners.length} principals hold the owner role: ${owners.map((owner) => owner.id).join(", ")}`;
+	for (const principal of await identity.list()) {
+		if (principal.id === primary || principal.id === SYSTEM_PRINCIPAL) continue;
+		const tier = await identity.tierOf(principal.id);
+		if (tier) return `principal ${principal.id} holds the ${tier} role`;
+	}
+	return undefined;
+}
+
+/** Why claude-bridge may not serve a host whose shared conversations hold several people's memory. */
+export function bridgeMemoryProblem(model: string, crowd: string): string {
+	return `model ${model} runs on ${CLAUDE_BRIDGE}, and this host keeps each person's private memory while ${crowd}. ${CLAUDE_BRIDGE} resumes the history Claude Code stored for a conversation, unfiltered, so one person's private memory could reach another reader. Shared bridge turns refuse when raw reader records show private memory carried for another reader (including prompt-only memory and reasoning), or an exchange is inaccessible. Turns without private memory stay shareable; malformed memory calls belong to their recorded reader. SYSTEM counts as primary owner and may read that owner's raw exchanges/reasoning; untagged pre-scope legacy memory results keep primary-owner attribution. Public replies, untagged custom tools, and old prompts/reasoning/summaries without reader records remain a risk.`;
+}
+
+/** How to fix it. */
+export const BRIDGE_MEMORY_FIX =
+	"Use another provider, or start a fresh conversation before sharing incompatible private history. memory: false or persona memory: none prevents future core memory loading, but does not bypass recorded private history.";
+
+/** The refusal of claude-bridge on a host whose shared conversations hold several people's memory. */
+export function bridgeMemoryError(model: string, crowd: string): ConfigError {
+	return new ConfigError(
+		`${bridgeMemoryProblem(model, crowd)} ${BRIDGE_MEMORY_FIX}`,
+	);
+}
+
+export interface AgentModelSettings {
+	model: string;
+	thinking: ThinkingSetting;
+}
+
+/** Copy the turn's selected model/settings once: checking and using separate reads can race a switch. */
+export function chosenAgentModel(
+	agent: string | undefined,
+	options: { agents?: Pick<AgentSessions, "modelOf"> },
+): AgentModelSettings | undefined {
+	return agent !== undefined && options.agents
+		? { ...options.agents.modelOf(agent) }
+		: undefined;
+}
+
+/** Apply exactly the model snapshot the guard checked, never a later live settings read. */
+export async function useChosenAgentModel(
+	session: AgentSession,
+	modelRuntime: Pick<ModelRuntime, "getModel">,
+	name: string,
+	chosen: AgentModelSettings | undefined,
+): Promise<ThinkingSetting> {
+	if (!chosen)
+		throw new ConfigError("agent turns need the runtime's agents option");
+	const { model, thinking } = chosen;
+	const ref = parseModelRef(model);
+	if (
+		session.model?.provider !== ref?.provider ||
+		session.model?.id !== ref?.id
+	) {
+		const resolved = ref && 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;
+}
+
+interface BridgeHistory {
+	messages: ContextWithSystemEvent["messages"];
+	reader: string | undefined;
+	/** The persisted branch retains exchanges removed from the active context by compaction. */
+	sessionManager?: Pick<SessionManager, "getBranch">;
+}
+
+/** Only results recorded before the first 0.9 scope marker inherit legacy owner attribution. */
+function hidesBridgeHistory(
+	history: BridgeHistory,
+	reader: string | undefined,
+	primary: string,
+): boolean {
+	const view = { shared: true, reader };
+	const branch = history.sessionManager?.getBranch();
+	if (!branch)
+		return guardHidesPrivateExchange(history.messages, {
+			...view,
+			legacyOwner: primary,
+		});
+	return bridgeHistoryHidesMemoryFor(branch, reader, primary);
+}
+
+/**
+ * Why raw private history prevents a shared turn from running on its selected bridge model;
+ * undefined when it may. The model is the agent's own for an agent's turn, the host's otherwise.
+ */
+export async function bridgeTurnRefusal(
+	agent: string | undefined,
+	options: {
+		model: ModelRef;
+		agents?: Pick<AgentSessions, "modelOf"> | undefined;
+		memory?: boolean;
+		owner: { id: string };
+	},
+	history: BridgeHistory,
+	chosen?: AgentModelSettings,
+): Promise<string | undefined> {
+	const model =
+		agent === undefined
+			? options.model
+			: parseModelRef(
+					chosen?.model ?? options.agents?.modelOf(agent).model ?? "",
+				);
+	if (!model || !onClaudeBridge(model)) return undefined;
+	const reader =
+		history.reader === SYSTEM_PRINCIPAL ? options.owner.id : history.reader;
+	if (!hidesBridgeHistory(history, reader, options.owner.id)) return undefined;
+	const why =
+		"this conversation's raw history holds another reader's private memory or a private exchange the current reader may not see";
+	const message = bridgeMemoryError(formatModelRef(model), why).message;
+	return agent === undefined ? message : `${agent}: ${message}`;
+}
+
+/**
+ * Why startup should warn about claude-bridge: the configuration's crowd, or
+ * the roles the host stores as they are now, so one granted after the boot counts at once.
+ * Undefined while one person alone may speak, or the host keeps no memory.
+ */
+export function liveBridgeRefusal(options: {
+	memory: boolean | undefined;
+	crowd: string | undefined;
+	identity: () =>
+		| Pick<IdentityService, "list" | "tierOf" | "owners">
+		| undefined;
+	primary: string;
+}): () => Promise<string | undefined> {
+	return async () => {
+		if (!options.memory) return undefined;
+		if (options.crowd) return options.crowd;
+		const identity = options.identity();
+		return identity && (await grantedCrowd(identity, options.primary));
+	};
+}

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

@@ -164,16 +164,20 @@ export class CompactionTiers {
 	/**
 	 * Wraps a compaction extension so a compaction past the hard ceiling skips it and pi's summary
 	 * runs. pi keeps the last handler result and stops only on cancel, so a handler of the assistant's
-	 * own could not keep the extension from answering; wrapping its registration can.
+	 * own could not keep the extension from answering; wrapping its registration can. `prepare`
+	 * changes what the extension is given before it reads it, such as a shared conversation's
+	 * history without anyone's private memory.
 	 */
 	wrapCompactor(
 		compactor: ExtensionFactory,
 		onBypass: (details: { reason: string; tokensBefore: number }) => void,
+		prepare?: (event: SessionBeforeCompactEvent) => void,
 	): ExtensionFactory {
 		const gate = (event: SessionBeforeCompactEvent): boolean => {
 			const { tokensBefore } = event.preparation;
 			const reason = extensionBypass(tokensBefore, this.latest());
 			if (reason) onBypass({ reason, tokensBefore });
+			else prepare?.(event);
 			return reason === undefined;
 		};
 		type Handler = (event: unknown, ctx: unknown) => unknown;