pi-roundtable 0.8.0 → 0.9.1

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,
@@ -24,13 +33,22 @@ export class SteerableRun {
 	readonly #canSteer: () => boolean;
 	/** Steered prompts in arrival order, each with its images. */
 	readonly #steers: { text: string; images: PromptImages }[] = [];
+	readonly #abort: () => void;
 	#stopped = false;
 	#done = false;
 
-	/** `canSteer` is asked at each steer: the turn is the owner's and holds no actions. */
-	constructor(session: SteeringSession, canSteer: () => boolean) {
+	/**
+	 * `canSteer` is asked at each steer: the turn is the owner's and holds no actions. `abort`
+	 * ends the session's run when the turn is stopped; by default the session's own abort.
+	 */
+	constructor(
+		session: SteeringSession,
+		canSteer: () => boolean,
+		abort: () => void = () => void session.abort(),
+	) {
 		this.#session = session;
 		this.#canSteer = canSteer;
+		this.#abort = abort;
 	}
 
 	get stopped(): boolean {
@@ -97,7 +115,7 @@ export class SteerableRun {
 		if (this.#done) return false;
 		this.#stopped = true;
 		this.#session.clearQueue();
-		void this.#session.abort();
+		this.#abort();
 		return true;
 	}
 

package/src/core/runtime/thinking-level.ts

@@ -0,0 +1,47 @@
+import type {
+	AgentSession,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import { AUTO_THINKING, type ThinkingLevel } from "../models.ts";
+import {
+	type AgentModelSettings,
+	useChosenAgentModel,
+} from "./bridge-guard.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+import { lastReply } from "./turn-answer.ts";
+
+/** Uses the checked model snapshot; auto thinking keeps the last pick while the judge is unsure. */
+export async function thinkingLevel(
+	parts: {
+		modelRuntime: ModelRuntime;
+		effort: PiAgentRuntimeOptions["effort"];
+		/** The level last judged for each conversation. */
+		judged: Map<ChannelKey, ThinkingLevel>;
+	},
+	key: ChannelKey,
+	session: AgentSession,
+	request: TurnRequest,
+	agentModel?: AgentModelSettings,
+): Promise<ThinkingLevel> {
+	const { modelRuntime, effort, judged } = parts;
+	const setting = request.agent
+		? await useChosenAgentModel(
+				session,
+				modelRuntime,
+				request.agent.name,
+				agentModel,
+			)
+		: AUTO_THINKING;
+	if (setting !== AUTO_THINKING) {
+		judged.delete(key);
+		return setting;
+	}
+	const level = await effort.judge(request.text, {
+		reply: lastReply(session.messages),
+		level: judged.get(key),
+	});
+	judged.set(key, level);
+	return level;
+}

package/src/core/runtime/tool-call-scope.ts

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** The ids of the tool calls whose code is running, outermost first. */
+const calls = new AsyncLocalStorage<readonly string[]>();
+
+/**
+ * The ids of the tool calls the code asking runs within, outermost first: the call of a session
+ * part's tool, and the calls it runs within in turn, such as a worker's call inside the call that
+ * started the worker. Empty outside every such call.
+ */
+export function runningCalls(): readonly string[] {
+	return calls.getStore() ?? [];
+}
+
+/**
+ * A session part's extension whose tools each run within their call's id, so what a call starts,
+ * a task's worker among them, knows which call it serves rather than every call running at once.
+ */
+export function scopedCalls(factory: ExtensionFactory): ExtensionFactory {
+	return (pi) =>
+		factory(
+			new Proxy(pi, {
+				get(target, key) {
+					if (key === "registerTool")
+						return (tool: ToolDefinition) =>
+							target.registerTool({
+								...tool,
+								execute: (toolCallId, ...rest) =>
+									calls.run([...runningCalls(), toolCallId], () =>
+										tool.execute(toolCallId, ...rest),
+									),
+							});
+					const value: unknown = Reflect.get(target, key, target);
+					return typeof value === "function" ? value.bind(target) : value;
+				},
+			}) satisfies ExtensionAPI,
+		);
+}

package/src/core/runtime/turn-answer.ts

@@ -1,7 +1,8 @@
-import type { TurnResult } from "../domain/conversation.ts";
+import type { TranscriptEntry, TurnResult } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
 import { hasReplyFiles } from "../reply-files.ts";
 import { lastAssistant, textOf } from "../shared/session-messages.ts";
+import { TRANSCRIPT_ENTRY_CHARS } from "./runtime-types.ts";
 
 interface MessagePart {
 	type?: unknown;
@@ -20,6 +21,34 @@ type Assistant = Message & {
 const isAssistant = (message: Message): message is Assistant =>
 	message.role === "assistant";
 
+/** The answer to a turn sent without a speaker: refused, never run as the owner's by default. */
+export function unspokenTurn(): TurnResult {
+	return {
+		ok: false,
+		error: new AgentRunError(
+			"a turn needs a speaker: pass TurnRequest.speaker, the person the turn is for; for a turn started on someone's behalf, get theirs from IDENTITY.speakerFor",
+		),
+	};
+}
+
+/** The last `limit` user and assistant messages as transcript entries, each cut to its first characters. */
+export function transcriptOf(
+	messages: readonly (Message & { content?: unknown })[],
+	limit: number,
+): TranscriptEntry[] {
+	const entries: TranscriptEntry[] = [];
+	for (const message of 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 session's last answer, which tells the judge what a short follow-up continues. */
 export function lastReply(messages: readonly Message[]): string | undefined {
 	const last = messages.findLast(isAssistant);

package/src/core/runtime/turn-wrapup.ts

@@ -0,0 +1,63 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { ConfirmationGate } from "./extensions/confirmation-gate.ts";
+import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
+
+/**
+ * What a turn leaves behind when it ends, whatever way it ended: the gate stops counting the turn,
+ * the conversation's context usage and held actions are recorded, and the turn is logged. A
+ * session disposed of under a turn that would not stop has no usage to read.
+ */
+export async function wrapUpTurn(parts: {
+	key: ChannelKey;
+	request: TurnRequest;
+	session: AgentSession;
+	gate: ConfirmationGate;
+	toolCalls: readonly string[];
+	options: Pick<PiAgentRuntimeOptions, "confirmations" | "logger">;
+	recordUsage: (usage: {
+		tokens: number | null;
+		contextWindow: number;
+	}) => void;
+}): Promise<void> {
+	const { key, request, session, gate, toolCalls, options, recordUsage } =
+		parts;
+	const { logger } = options;
+	gate.endTurn();
+	try {
+		const usage = session.getContextUsage();
+		if (usage)
+			recordUsage({
+				tokens: usage.tokens,
+				contextWindow: usage.contextWindow,
+			});
+	} catch (error) {
+		logger.warn({ channel: key, err: error }, "context usage not read");
+	}
+	const held = gate.pending();
+	await 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",
+	);
+}

package/src/core/services.ts

@@ -1,12 +1,16 @@
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
-import type { ScheduledOutcome } from "./contract/channels.ts";
+import type {
+	BackgroundRunsAs,
+	ScheduledOutcome,
+} from "./contract/channels.ts";
 import type { AgentRuntime } from "./contract/runtime.ts";
 import { type ServiceKey, serviceKey } from "./contract/services.ts";
 import type { ConversationRegistry } from "./conversations/conversation-registry.ts";
 import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
+import type { IdentityService } from "./identity/identity-service.ts";
 import type { ThinkingSetting } from "./models.ts";
 import type {
 	DelegationJob,
@@ -36,6 +40,12 @@ import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
 // interface, so an object with the same methods satisfies it without being one of the built-in
 // classes; a plugin replaces a built-in by providing its own under the same key.
 
+/**
+ * Who the host serves: its principals, the identities linked to each, and their lasting roles.
+ * Provided by the `identity` plugin, which every host registers first, so every plugin may read it.
+ */
+export const IDENTITY: ServiceKey<IdentityService> =
+	serviceKey<IdentityService>("roundtable.identity");
 /**
  * The runtime every conversation turn runs on: the agent server's, and each turn run through
  * `context.turns`. The `runtime` provider slot's when a plugin fills it, Pi's otherwise. Provided
@@ -178,6 +188,16 @@ export interface AgentTeam {
 /** Scheduled turns, stored. A one-time schedule is deleted once it fires. */
 export interface ScheduleStore {
 	create(schedule: NewSchedule): Promise<Schedule>;
+	/**
+	 * Creates a schedule unless its creator already has `limit.max` of its target's schedules,
+	 * counting those whose creator id is one of `limit.creators`; resolves the count reached instead.
+	 * Two calls for one creator never count at once, so creates at once in many conversations stay
+	 * within the limit.
+	 */
+	createWithin(
+		schedule: NewSchedule,
+		limit: { creators: readonly string[]; max: number },
+	): Promise<{ created: Schedule } | { reached: number }>;
 	get(id: number): Promise<Schedule | undefined>;
 	forChannel(channel: ChannelKey): Promise<Schedule[]>;
 	all(): Promise<Schedule[]>;
@@ -208,6 +228,12 @@ export interface BackgroundTurns {
 		firedAt: Date,
 		finding?: PrecheckFinding,
 	): Promise<ScheduledOutcome>;
+	/**
+	 * Who a due schedule's turn would run as now, checked as the turn is: asked before its
+	 * precheck, which runs only for a creator who may run the turn, at the tier it would run at.
+	 * Throws when the identity service cannot tell.
+	 */
+	runsAs(schedule: Schedule): Promise<BackgroundRunsAs>;
 	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
 	runDelegated(job: DelegationJob, result: DelegationOutcome): Promise<void>;
 	/** The process's own logged error, reported to an agent in its channel as a report turn. */

package/src/core/sessions.ts

@@ -1,5 +1,7 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { PluginError } from "./errors.ts";
+import type { Principal } from "./identity/principal-store.ts";
+import type { OwnerIdentity } from "./identity.ts";
 import type { Speaker } from "./speakers.ts";
 
 /** `<surface>:<channel id>`, for example `discord:1234`. A DM is one channel. */
@@ -41,6 +43,15 @@ export interface TransientTask {
 	onFinished?(toolCalls: readonly string[]): void;
 }
 
+/**
+ * Whom a session's conversation serves, fixed when the session is made: `private` to one
+ * principal, whose name and pronouns are known when the host has a record of them, or `shared`
+ * by whoever its claim admits, as an agent's session always is.
+ */
+export type SessionConversation =
+	| { visibility: "private"; principalId: string; principal?: Principal }
+	| { visibility: "shared" };
+
 /** What one Pi session is for, as a session tool's factory sees it. */
 export interface SessionContext {
 	/** "agent" for an agent's session; otherwise the kind of conversation, which the claim that owns the channel names. */
@@ -53,6 +64,25 @@ export interface SessionContext {
 	agent?: AgentTurnScope;
 	/** Wraps a compactor so the core's compaction tiers decide when it may answer. */
 	compaction: { wrap(compactor: ExtensionFactory): ExtensionFactory };
+	/**
+	 * Whom the conversation serves, as `TurnRequest.conversation` or the host's record says when the
+	 * session is made; shared when neither says. A private conversation's tools serve its person:
+	 * their memory, their notices. A shared one's serve each turn's speaker.
+	 */
+	conversation: SessionConversation;
+	/**
+	 * Whom the session's tool descriptions address, fixed when it is made: a private conversation's
+	 * person by their name and pronouns, the primary owner exactly as 0.8 wrote them, and
+	 * `THE_SPEAKER` in a shared conversation, where each turn's prompt says who speaks.
+	 */
+	addressee: OwnerIdentity;
+	/**
+	 * Whose memory the session's turns may read: `"speaker"` (the default), as `conversation` and
+	 * each turn's speaker decide, or `"none"`, for a persona that declares it; then no memory loads.
+	 * While the running turn is one the agent server keeps out of memory (`AgentSessions.memory`),
+	 * it reads `"none"` for that turn alone.
+	 */
+	memory: "speaker" | "none";
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */