pi-roundtable 0.8.0 → 0.9.1

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

@@ -6,9 +6,11 @@ import type {
 } 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 { HostStoppingError, 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";
@@ -59,9 +61,12 @@ 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), when the host has no runtime to run the turn on,
-	 * and when the conversation cannot be recorded in the host's registry (a database error, or a
-	 * `private` conversation without a speaker). Each of these rejects before the turn starts:
+	 * It rejects during setup (NotLinkedError), once the host is shutting down (HostStoppingError),
+	 * 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.
 	 */
@@ -71,6 +76,8 @@ export interface ConversationTurns {
 export interface ConversationTurnsOptions {
 	/** Throws NotLinkedError until every plugin is set up and linked. */
 	linked: () => void;
+	/** Whether the host is shutting down, so no turn starts; undefined or false while it serves. */
+	stopping?: () => boolean;
 	/** 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. */
@@ -85,25 +92,50 @@ 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. */
+/**
+ * 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<void> {
-	if (!registry) return;
+): 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;
-	await registry.register({
+	const kept = await registry.register({
 		key: input.channel,
 		kind: input.kind,
 		visibility,
-		...(visibility === "private" ? { principalId: input.speaker.id } : {}),
+		...(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(
@@ -114,10 +146,12 @@ export function conversationTurns(
 		async run(input) {
 			const { channel, kind, speaker } = input;
 			options.linked();
+			// Refused before anything is shown or recorded, like a turn the host cannot run.
+			if (options.stopping?.()) throw new HostStoppingError();
 			// 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.
-			await record(options.registry?.(), input);
+			const conversation = await record(options.registry?.(), input);
 			const stopTyping = surfaces.startTyping(channel);
 			const hideStop = surfaces.showStop(channel);
 			const turn = { kind, channel, speaker };
@@ -150,6 +184,7 @@ export function conversationTurns(
 								},
 								text: input.text,
 								speaker,
+								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }
 									: {}),

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,10 +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/abort-guard.ts

@@ -0,0 +1,58 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { AgentRunError } from "../domain/errors.ts";
+
+/** How long a run told to abort gets to end before its session is disposed of; default for the guard. */
+const ABORT_GRACE_MS = 15_000;
+
+/**
+ * Aborts a Pi session's run and does not trust the abort to work. A model behind a subprocess that
+ * ignores the abort would leave the run, and the queue behind it, waiting for ever, so a run still
+ * going once the grace is over has its session disposed of, which drops its model connection, and
+ * `gaveUp` rejects so the caller can end the turn as failed.
+ */
+export class AbortGuard {
+	/** Rejects when the abort did not end the run in time; never resolves. */
+	readonly gaveUp: Promise<never>;
+	readonly #session: Pick<AgentSession, "abort" | "dispose">;
+	readonly #graceMs: number;
+	readonly #onGiveUp: () => void;
+	#reject: (error: Error) => void = () => undefined;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(
+		session: Pick<AgentSession, "abort" | "dispose">,
+		options: { graceMs?: number; onGiveUp?: () => void } = {},
+	) {
+		this.#session = session;
+		this.#graceMs = options.graceMs ?? ABORT_GRACE_MS;
+		this.#onGiveUp = options.onGiveUp ?? (() => undefined);
+		this.gaveUp = new Promise<never>((_resolve, reject) => {
+			this.#reject = reject;
+		});
+		// Nobody waits on it unless the abort fails.
+		this.gaveUp.catch(() => undefined);
+	}
+
+	/** Aborts the run, and starts the grace the first time. */
+	abort(): void {
+		void this.#session.abort();
+		this.#timer ??= setTimeout(() => {
+			this.#onGiveUp();
+			try {
+				this.#session.dispose();
+			} catch {
+				// A session that cannot be disposed of is dropped all the same.
+			}
+			this.#reject(
+				new AgentRunError(
+					"the run did not stop after it was aborted, so its session was disposed of",
+				),
+			);
+		}, this.#graceMs);
+	}
+
+	/** The run ended: no session is disposed of any more. */
+	release(): void {
+		clearTimeout(this.#timer);
+	}
+}

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;