pi-roundtable 0.8.0 → 0.9.1

package/src/core/config/adapters.ts

@@ -1,5 +1,65 @@
+import type { ChannelContextOptions } from "../contract/channel-context.ts";
 import { ConfigError } from "../domain/errors.ts";
-import { bool, optional, shape, text } from "./schema.ts";
+import {
+	bool,
+	integer,
+	number,
+	oneOf,
+	optional,
+	orOff,
+	shape,
+	text,
+} from "./schema.ts";
+
+/** The Discord bot and its guild, as the top-level `discord` or `discord()` from `pi-roundtable/discord` gives them. */
+export interface DiscordConfig {
+	/** The bot token; keep it in `.env`, not in this file. */
+	token: string;
+	/** The agent server's guild id. */
+	guild: string;
+	/** The channel the coordinator lives in. */
+	entryChannel: string;
+	/** The root slash command, without the slash; default the lowercase assistant name. */
+	rootCommand?: string;
+	/**
+	 * Whether the owner's conversations have Discord administration tools; default true. `false`
+	 * leaves the `discord-admin` addon out.
+	 */
+	admin?: boolean;
+	/**
+	 * Text appended as it is to the refusal a non-owner gets from the root command, such as a
+	 * pointer to the commands anyone may use; include the space or punctuation your language
+	 * needs before it. Default none.
+	 */
+	refusalHint?: string;
+	/**
+	 * Whose turns in the agents' channels load memory: `"everyone"` (default) lets each speaker
+	 * read their own, `"owners"` only the owners, so a guest's turn has no memory in its prompt and
+	 * no memory tools, and never makes claude-bridge refuse the owner afterwards.
+	 */
+	agentMemory?: "everyone" | "owners";
+	/**
+	 * What a turn addressed to the assistant in a server channel reads of the messages posted there
+	 * since its last post, mentions or not; on with the defaults when left out. `false` turns it off
+	 * for the agent server and every plugin's claim.
+	 */
+	channelContext?: ChannelContextOptions | false;
+	/**
+	 * The divider the assistant posts in a server channel or thread when its conversation starts
+	 * over (a new conversation by an owner's command), which ends the window channel context reads;
+	 * never in a direct message. Default `─── new conversation ───`; `false` posts none.
+	 */
+	freshMarker?: string | false;
+}
+
+/** What `discord.channelContext` takes besides `false`. */
+const channelContextShape = shape({
+	fetch: optional(integer(1, 100)),
+	keep: optional(integer(1, 100)),
+	similarity: optional(number(0, 1)),
+	messageChars: optional(integer(1, 4000)),
+	botMessageChars: optional(integer(1, 4000)),
+});
 
 /** The Discord settings, at the top level or in a Discord adapter. */
 export const discordShape = shape({
@@ -9,6 +69,9 @@ export const discordShape = shape({
 	rootCommand: optional(text),
 	admin: optional(bool),
 	refusalHint: optional(text),
+	agentMemory: optional(oneOf<"everyone" | "owners">("everyone", "owners")),
+	channelContext: optional(orOff(channelContextShape)),
+	freshMarker: optional(orOff(text)),
 });
 
 /** The adapters `adapters` takes, by the name their factory gives them. */

package/src/core/config/config.ts

@@ -3,7 +3,9 @@ import { join } from "node:path";
 import type { AgentSeed } from "../agents/agent-rules.ts";
 import { ConfigError } from "../domain/errors.ts";
 import type { InterimTextMode } from "../domain/interim.ts";
+import { DRAIN_LIMIT_MS } from "../drain.ts";
 import { isLocale, type Locale } from "../i18n/index.ts";
+import type { AccessRules } from "../identity/access-policy.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import {
 	type ModelRef,
@@ -11,11 +13,13 @@ import {
 	THINKING_LEVELS,
 	type ThinkingLevel,
 } from "../models.ts";
+import type { PerPrincipalLimits } from "../modules/background/personal-target.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
 import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
-import { discordShape, liftAdapters } from "./adapters.ts";
+import { type AccessConfig, accessOf, accessShape } from "./access.ts";
+import { type DiscordConfig, discordShape, liftAdapters } from "./adapters.ts";
 import {
 	bool,
 	guarded,
@@ -30,6 +34,8 @@ import {
 	text,
 } from "./schema.ts";
 
+export type { DiscordConfig };
+
 /** How prompts refer back to the owner. */
 export type Pronouns = "he" | "she" | "they";
 
@@ -43,29 +49,6 @@ export interface TierConfig {
 	everyone?: boolean;
 }
 
-/** The Discord bot and its guild, as the top-level `discord` or `discord()` from `pi-roundtable/discord` gives them. */
-export interface DiscordConfig {
-	/** The bot token; keep it in `.env`, not in this file. */
-	token: string;
-	/** The agent server's guild id. */
-	guild: string;
-	/** The channel the coordinator lives in. */
-	entryChannel: string;
-	/** The root slash command, without the slash; default the lowercase assistant name. */
-	rootCommand?: string;
-	/**
-	 * Whether the owner's conversations have Discord administration tools; default true. `false`
-	 * leaves the `discord-admin` addon out.
-	 */
-	admin?: boolean;
-	/**
-	 * Text appended as it is to the refusal a non-owner gets from the root command, such as a
-	 * pointer to the commands anyone may use; include the space or punctuation your language
-	 * needs before it. Default none.
-	 */
-	refusalHint?: string;
-}
-
 /** A chat network the host talks through, as its adapter's factory makes it; `adapter` names the network. */
 export interface AdapterConfig {
 	readonly adapter: string;
@@ -77,12 +60,21 @@ export interface DiscordAdapterConfig extends AdapterConfig {
 	readonly discord: DiscordConfig;
 }
 
+/** The configuration's `background`: each person's share of the host's background work. */
+export interface BackgroundConfig {
+	perPrincipal?: PerPrincipalLimits;
+}
+
 /** What `roundtable.config.ts` gives `defineRoundtable`. */
 export interface RoundtableConfig {
 	/** The assistant's display name; default "Roundtable". */
 	name?: string;
-	/** The one owner: the only person who can change everything. */
-	owner: { id: string; name: string; pronouns?: Pronouns };
+	/**
+	 * The one owner, as 0.8 wrote it: their id, which is both their principal and their Discord
+	 * user id, their name, and pronouns. Deprecated, going away in 0.10: write `access` instead,
+	 * never both; `roundtable upgrade` rewrites it.
+	 */
+	owner?: { id: string; name: string; pronouns?: Pronouns };
 	/**
 	 * The Discord bot, its guild, and the agent server that lives there. Leave it out for a host
 	 * without Discord: no Discord plugins, no agent server or agents, no skills, and no tool that
@@ -113,8 +105,19 @@ export interface RoundtableConfig {
 	locale?: Locale;
 	/** The IANA time zone schedules and stamps use; default "UTC". */
 	timeZone?: string;
-	/** Who may talk to the agents besides the owner, and what each tier may use. */
+	/** Who may talk to the agents besides the owner, by Discord user and role ids, as 0.8 wrote it. Deprecated with `owner`: write `access` instead. */
 	speakers?: { admins?: TierConfig; members?: TierConfig };
+	/**
+	 * Who the host serves: the owners, the first the primary one, and the admins and members by
+	 * identity (`<provider>:<subject>`), role (`<surface>:role:<name>`), or everyone. Required
+	 * unless the deprecated `owner` is given, and never with it.
+	 */
+	access?: AccessConfig;
+	/**
+	 * Each person's limits across all their conversations: `perPrincipal.schedules` they may keep and
+	 * `perPrincipal.delegations` running at once. Unset, only each conversation's, as in 0.8.
+	 */
+	background?: BackgroundConfig;
 	toolTiers?: Record<string, Tier>;
 	/** Prompt files, read once at start; `shared` starts every agent's prompt. */
 	prompts?: { shared: string; guest?: string };
@@ -162,6 +165,11 @@ export interface RoundtableConfig {
 	 * conversation or no plugin's claim owns it; the web chat takes no error reports.
 	 */
 	ops?: { agent: string } | { conversation: string };
+	/**
+	 * Seconds a shutdown waits for running turns before stopping them; default 180. Give the
+	 * service manager a stop timeout a minute longer, such as systemd's `TimeoutStopSec`.
+	 */
+	drainSeconds?: number;
 	/**
 	 * Whether a turn posts the text it writes before its final answer as it goes: long or
 	 * structured text as ordinary messages, short narration and the tools called in one small
@@ -187,11 +195,13 @@ const isPlugin = (value: unknown): value is RoundtablePlugin =>
 
 const schema = shape({
 	name: optional(text),
-	owner: shape({
-		id: text,
-		name: text,
-		pronouns: optional(oneOf<Pronouns>("he", "she", "they")),
-	}),
+	owner: optional(
+		shape({
+			id: text,
+			name: text,
+			pronouns: optional(oneOf<Pronouns>("he", "she", "they")),
+		}),
+	),
 	discord: optional(discordShape),
 	database: shape({ url: text }),
 	dataDir: text,
@@ -216,6 +226,17 @@ const schema = shape({
 	speakers: optional(
 		shape({ admins: optional(tierMembers), members: optional(tierMembers) }),
 	),
+	access: optional(accessShape),
+	background: optional(
+		shape({
+			perPrincipal: optional(
+				shape({
+					schedules: optional(integer(1, 10_000)),
+					delegations: optional(integer(1, 1_000)),
+				}),
+			),
+		}),
+	),
 	toolTiers: optional(record(oneOf<Tier>("owner", "admin", "member"))),
 	prompts: optional(shape({ shared: text, guest: optional(text) })),
 	agents: optional(
@@ -246,6 +267,7 @@ const schema = shape({
 	),
 	memory: optional(bool),
 	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),
+	drainSeconds: optional(integer(1, 3_600)),
 	interimText: optional(oneOf<InterimTextMode>("on", "off")),
 	interimPrimaryChars: optional(integer(1, 100_000)),
 	plugins: optional(
@@ -255,12 +277,6 @@ const schema = shape({
 	),
 });
 
-const PRONOUNS: Record<Pronouns, OwnerIdentity["pronouns"]> = {
-	he: { subject: "he", object: "him", possessive: "his" },
-	she: { subject: "she", object: "her", possessive: "her" },
-	they: { subject: "they", object: "them", possessive: "their" },
-};
-
 /** The configuration with every default filled in. */
 export interface ResolvedConfig {
 	name: string;
@@ -269,7 +285,17 @@ export interface ResolvedConfig {
 	 * with Discord. `discord.rootCommand` when Discord is on, else the lowercase assistant name.
 	 */
 	slug: string;
+	/**
+	 * The primary owner, `access.owners[0]` (or the 0.8 `owner`): their principal id, name, and
+	 * pronouns, and the Discord user id the Discord parts act for until 0.10.
+	 */
+	primaryOwner: OwnerIdentity & { id: string; discordId?: string };
+	/** The primary owner as 0.8 knew them, `id` their principal id. Deprecated: read `primaryOwner`. */
 	owner: OwnerIdentity & { id: string };
+	/** Who the host serves, the 0.8 `owner` and `speakers` converted when they are what the configuration gives. */
+	access: AccessRules;
+	/** What the configuration wrote in a deprecated form, which the host logs once. */
+	deprecations: string[];
 	/** Undefined on a host without Discord. */
 	discord?: {
 		token: string;
@@ -278,6 +304,10 @@ export interface ResolvedConfig {
 		rootCommand: string;
 		admin: boolean;
 		refusalHint?: string;
+		agentMemory?: "everyone" | "owners";
+		/** As configured: `{}` when left out, so the defaults apply, or `false`. */
+		channelContext: NonNullable<DiscordConfig["channelContext"]>;
+		freshMarker?: string | false;
 	};
 	databaseUrl: string;
 	dataDir: string;
@@ -288,7 +318,10 @@ export interface ResolvedConfig {
 	delegation: { model: ModelRef; thinking: ThinkingLevel };
 	locale: Locale;
 	timeZone: string;
+	/** The 0.8 `speakers`; empty when the configuration writes `access`. Deprecated: read `access`. */
 	speakers: { admins?: TierMembers; members?: TierMembers };
+	/** Each person's limits across their conversations; a limit left out is unset. */
+	background: { perPrincipal: PerPrincipalLimits };
 	toolTiers: Record<string, Tier>;
 	prompts: { shared?: string; guest?: string };
 	agents: AgentSeed[];
@@ -308,6 +341,7 @@ export interface ResolvedConfig {
 	skills: false | { builtinDir?: string; reposDir?: string };
 	memory: boolean;
 	ops?: { agent: string } | { conversation: ChannelKey };
+	drainMs: number;
 	interimText: InterimTextMode;
 	interimPrimaryChars: number;
 	plugins: RoundtablePlugin[];
@@ -378,13 +412,16 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 	const slug =
 		discord?.rootCommand ?? name.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
 	const ops = opsOf(config.ops, discord !== undefined);
+	const access = accessOf(config, discord !== undefined);
+	const { primaryOwner } = access;
 	return {
 		name,
 		slug,
+		...access,
 		owner: {
-			id: config.owner.id,
-			name: config.owner.name,
-			pronouns: PRONOUNS[config.owner.pronouns ?? "they"],
+			id: primaryOwner.id,
+			name: primaryOwner.name,
+			pronouns: primaryOwner.pronouns,
 		},
 		...(discord
 			? {
@@ -397,6 +434,13 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 						...(discord.refusalHint === undefined
 							? {}
 							: { refusalHint: discord.refusalHint }),
+						...(discord.agentMemory === undefined
+							? {}
+							: { agentMemory: discord.agentMemory }),
+						channelContext: discord.channelContext ?? {},
+						...(discord.freshMarker === undefined
+							? {}
+							: { freshMarker: discord.freshMarker }),
 					},
 				}
 			: {}),
@@ -423,6 +467,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 			...(config.speakers?.admins ? { admins: config.speakers.admins } : {}),
 			...(config.speakers?.members ? { members: config.speakers.members } : {}),
 		},
+		background: { perPrincipal: { ...config.background?.perPrincipal } },
 		toolTiers: config.toolTiers ?? {},
 		prompts: config.prompts ?? {},
 		agents: config.agents ?? [],
@@ -446,6 +491,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		skills: config.skills ?? (discord ? {} : false),
 		memory: config.memory ?? true,
 		...(ops ? { ops } : {}),
+		drainMs: (config.drainSeconds ?? DRAIN_LIMIT_MS / 1_000) * 1_000,
 		interimText: config.interimText ?? "on",
 		interimPrimaryChars: config.interimPrimaryChars ?? PRIMARY_CHARS,
 		plugins: config.plugins ?? [],

package/src/core/contract/channel-context.ts

@@ -0,0 +1,53 @@
+// What a surface tells a turn about the channel around the message it answers. Discord fills it
+// (`DISCORD.channelContext`); the types and the way a turn carries it are any surface's.
+
+/** How much of a channel a turn reads as its channel context; every member has a default. */
+export interface ChannelContextOptions {
+	/** How many messages before the addressed one are fetched; default 50, at most 100 (Discord's page). */
+	fetch?: number;
+	/** How many of the window's messages are kept, the newest; default 15. */
+	keep?: number;
+	/**
+	 * How alike (0 to 1) two consecutive messages of one author must be to count as one, the later
+	 * kept, such as a message and its corrected repost; default 0.8.
+	 */
+	similarity?: number;
+	/** Where a message's text is cut; default 500 characters. */
+	messageChars?: number;
+	/** Where another bot's message is cut; default 80 characters. */
+	botMessageChars?: number;
+}
+
+/** One channel message a turn reads around the message that addressed the assistant. */
+export interface ChannelContextMessage {
+	id: string;
+	authorId: string;
+	/** How the author appears in the channel. */
+	authorName: string;
+	/** Another bot, or an integration such as a webhook that is not the assistant's. */
+	bot: boolean;
+	/** One of the host's owners. */
+	owner: boolean;
+	/** The text, with mentions by name and stickers and files as text, cut where the options say. */
+	text: string;
+	at: Date;
+}
+
+/**
+ * What was said in a server channel since the assistant last posted there, before the message that
+ * addressed it: public channel text, not anyone's private memory, and not from the turn's speaker.
+ */
+export interface ChannelContext {
+	/** Oldest first; never empty. */
+	readonly messages: readonly ChannelContextMessage[];
+	/** The delimited block `withChannelContext` appends to a turn's text. */
+	readonly text: string;
+}
+
+/** The turn's text, then its channel context when there is one, as `withReference` adds a replied-to message. */
+export function withChannelContext(
+	text: string,
+	context: ChannelContext | undefined,
+): string {
+	return context ? `${text}\n\n${context.text}` : text;
+}

package/src/core/contract/channels.ts

@@ -1,6 +1,7 @@
 import type { Locale } from "../i18n/index.ts";
+import type { ActorFacts } from "../identity/actor-facts.ts";
 import type { ChannelKey } from "../sessions.ts";
-import type { Tier } from "../speakers.ts";
+import type { Speaker, Tier } from "../speakers.ts";
 
 /** A file attached to a chat message, as the surface reports it; nothing is downloaded yet. */
 export interface AttachmentRef {
@@ -16,6 +17,21 @@ export interface InboundMessage {
 	channel: ChannelKey;
 	/** Unique per surface; keeps the files of different messages apart. */
 	messageId: string;
+	/**
+	 * Who wrote it, as the surface reports them: the router resolves them to `speaker` through the
+	 * identity service. A surface that leaves it out has it read from `authorId`, `authorName`, and
+	 * `authorRoleIds` under its own name as the provider, with a `deprecated` warning; that goes
+	 * away in 1.0.
+	 */
+	actor?: ActorFacts;
+	/**
+	 * Who the author is, with their principal and tier, as the router resolved them before any
+	 * claim admits the message: undefined when the access rules serve no one by them, and for a bot
+	 * or an integration, which are not resolved. Only the router sets it; a surface's own value is
+	 * dropped. A claim that serves only people the host serves answers only when it is set.
+	 */
+	speaker?: Speaker;
+	/** The id the surface knows the author by; who they are to the host is `speaker`. */
 	authorId: string;
 	/** How the author appears in the channel, for example a server nickname. */
 	authorName: string;
@@ -77,10 +93,22 @@ export interface BackgroundTarget {
 	name: string;
 	/** How lists such as `/<root> schedule` name it, in the host's locale. */
 	label(locale: Locale): string;
-	/** Limits of the schedules made for it; absent, nothing may be scheduled for it. */
-	schedules?: { perChannel: number; promptChars: number; aheadDays: number };
-	/** Limits of the delegated tasks reporting to it; absent, nothing may be delegated to it. */
-	delegation?: { maxRunning: number };
+	/**
+	 * Limits of the schedules made for it; absent, nothing may be scheduled for it. `perPrincipal`,
+	 * when set, holds each person to that many of its schedules across all their conversations.
+	 */
+	schedules?: {
+		perChannel: number;
+		perPrincipal?: number;
+		promptChars: number;
+		aheadDays: number;
+	};
+	/**
+	 * Limits of the delegated tasks reporting to it; absent, nothing may be delegated to it.
+	 * `maxRunningPerPrincipal`, when set, holds each person to that many running at once across
+	 * all their conversations.
+	 */
+	delegation?: { maxRunning: number; maxRunningPerPrincipal?: number };
 }
 
 /** A turn nobody wrote in the channel: a schedule's, or a report of work done elsewhere. */
@@ -91,18 +119,31 @@ export interface BackgroundTurn {
 	 * plugin contributes, and a claim skips one it does not serve.
 	 */
 	target: string;
-	author: { id: string; name: string };
 	/**
-	 * The tier the turn runs at, which is its creator's when a person set it up; absent for
-	 * the operator's own automation, which runs at the owner's.
+	 * Whom the turn is for: the principal who set up the work, and the id and name they are shown
+	 * by, such as the identity they spoke as. The system principal is the host's alone.
 	 */
-	tier?: Tier;
+	author: { principalId: string; id: string; name: string };
+	/**
+	 * The tier the turn asks to run at, its creator's when they set it up. It runs at that tier or
+	 * the principal's own now, whichever is lower.
+	 */
+	tier: Tier;
 	turnId: string;
 	text: string;
 	/** It delivers a report the owner is waiting for, so it may ask them on cards. */
 	report?: boolean;
+	/**
+	 * Who the turn runs as, set by the router alone once it checked the author: their principal
+	 * exists and is not disabled, and the tier is capped at theirs. A claim runs the turn as this
+	 * speaker; one the caller sets is replaced.
+	 */
+	speaker?: Speaker;
 }
 
+/** Who a background turn runs as, once checked; or why it may not run now. */
+export type BackgroundRunsAs = { speaker: Speaker } | { skipped: string };
+
 /**
  * Whose conversation a channel holds, as the claim that owns it names it when `startFresh` says
  * whose it was: any string, such as "owner" or "study". The host reads none of them, so a plugin
@@ -125,6 +166,12 @@ export type Admission =
 			};
 			/** The turn, run in the channel's queue. */
 			run(): Promise<void>;
+			/**
+			 * Called instead of `run` when the router drops the message the claim admitted, because
+			 * its author, once recorded, was not who they were when admitted; frees what the claim
+			 * holds for it.
+			 */
+			dropped?(): void;
 			/** The log line when the turn throws. */
 			failure: string;
 	  }
@@ -161,13 +208,32 @@ export interface ChannelClaim {
 	deleteConversation?(channel: ChannelKey): Promise<void>;
 	/** Reports of work started in an owned channel stay in it instead of opening a thread. */
 	postsInPlace?: boolean;
+	/**
+	 * Whether the claim's `background` answers the host's own turns (`SYSTEM_PRINCIPAL`), such as
+	 * `ops.conversation`'s error reports, in its conversations; true when left out. A claim whose
+	 * conversations are each private to the person who opened them, such as the web chat's, says
+	 * false, and a host whose `ops.conversation` names one of them does not start.
+	 */
+	takesSystemReports?: boolean;
 }
 
 /** The conversations of every claimed channel, through the channel queue. */
 export interface ConversationPort {
 	/** Never rejects; resolves when the message's turn is done or dropped. */
 	handle(message: InboundMessage): Promise<void>;
+	/**
+	 * Runs a turn nobody wrote, as its author's principal at the lower of its tier and theirs; it
+	 * is skipped, with the reason, when the principal is unknown, disabled, holds no tier, or was
+	 * last seen too long ago (`access.backgroundStaleDays`), or when the turn names no principal or
+	 * tier. Never rejects.
+	 */
 	background(turn: BackgroundTurn): Promise<ScheduledOutcome>;
+	/**
+	 * Who a background turn would run as now, checked as `background` checks it, without running
+	 * it: for work that must not happen for an author who may not run the turn, such as a
+	 * schedule's precheck. Throws when the identity service cannot tell.
+	 */
+	runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs>;
 	/** A contributed background target, read when used; undefined when no plugin contributes it. */
 	target(name: string): BackgroundTarget | undefined;
 	/** Waits for the channel's running turn, then starts its conversation over; says whose it was. */
@@ -182,6 +248,8 @@ export interface ConversationPort {
 	owns(channel: ChannelKey): boolean;
 	/** Whether the claim that owns the channel runs background turns there; false when none owns it. */
 	takesBackground(channel: ChannelKey): boolean;
+	/** Whether the claim that owns the channel takes the host's own turns; false when none owns it. */
+	takesSystemReports(channel: ChannelKey): boolean;
 }
 
 /** The host's channel queue, as plugins use it. */
@@ -191,6 +259,11 @@ export interface QueuePort {
 	size(channel: ChannelKey): number;
 	/** Channels with a task running or waiting. */
 	busy(): ChannelKey[];
+	/**
+	 * Whether the host is shutting down: a task that has not started is then refused with
+	 * HostStoppingError, and a plugin that starts work on its own, such as a timer, starts none.
+	 */
+	readonly closed: boolean;
 	/** Called whenever a channel's count of running and waiting tasks changes. */
 	onChange(listener: (channel: ChannelKey) => void): void;
 }

package/src/core/contract/runtime.ts

@@ -5,8 +5,8 @@ import type {
 	TranscriptEntry,
 	TurnResult,
 } from "../domain/conversation.ts";
-import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import type { TurnRequest } from "../domain/ports.ts";
+import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
 import type { ThinkingSetting } from "../models.ts";
 import type { HostEnv, LinkedSessions } from "../plugin.ts";
@@ -51,11 +51,18 @@ export interface AgentRuntime {
 	startFresh(conversation: ChannelKey): Promise<void>;
 	/** Like `startFresh`, but removes the conversation and every archive of it for good; called between turns. */
 	deleteConversation(conversation: ChannelKey): Promise<void>;
-	/** The conversation's held actions known in memory since startup. */
+	/**
+	 * The conversation's held actions known in memory: those of a turn run since startup, and those
+	 * `heldActions` or `recentTranscript` restored from the store for it. After a restart, ask one of
+	 * those first.
+	 */
 	pendingConfirmation(
 		conversation: ChannelKey,
 	): PendingConfirmation | undefined;
-	/** The conversation's held actions, restored from the store after a restart. */
+	/**
+	 * The conversation's held actions, restored from the store after a restart, so that
+	 * `pendingConfirmation` knows them too, as `recentTranscript` does. Expired ones count as none.
+	 */
 	heldActions(
 		conversation: ChannelKey,
 	): Promise<PendingConfirmation | undefined>;
@@ -96,6 +103,13 @@ export interface AgentSessions {
 	modelOf(name: string): { model: string; thinking: ThinkingSetting };
 	/** The channel the scope's turns run in: the group's for a seat in one, else the agent's own. */
 	turnChannel(scope: AgentTurnScope): ChannelKey;
+	/**
+	 * Whose turns in an agent's conversation load memory: `"everyone"` (the default) lets each
+	 * speaker read their own, `"owners"` only the owners, so a speaker below the owner tier gets no
+	 * memory in their prompt and no memory tools, and their turn never carries private memory into
+	 * the conversation's history.
+	 */
+	memory?: "everyone" | "owners";
 }
 
 /** Where a runtime keeps each conversation's held actions, so they survive a restart. */
@@ -124,13 +138,15 @@ export interface RuntimeDeps {
 	/** What each tool needs; plugin tools are added when the host links, so ask at use time. */
 	toolTiers: ToolTiers;
 	/**
-	 * The owner's approval and question prompts in a conversation, from its chat surface; undefined
-	 * when the surface has none, and the action then waits for the owner's next message.
+	 * The approval and question prompts in a conversation for a turn's scope, made with
+	 * `promptScope(speaker, visibility)`, from its chat surface; undefined when the surface has
+	 * none, and the action then waits for a message that approves it. A `Speaker`, the 0.8 form,
+	 * is read as theirs in a shared conversation, with a deprecation warning, until 1.0.
 	 */
 	prompts(
 		conversation: ChannelKey,
-		speaker?: Speaker,
-	): OwnerPrompts | undefined;
+		scope?: PromptScope | Speaker,
+	): Prompts | undefined;
 	/**
 	 * The agent server's per-agent settings, for agent turns. The runtime is built before the agent
 	 * server, so read this when a turn runs, not in the factory; it stays undefined on a host without