pi-roundtable 0.1.0 → 0.2.0

package/src/core/routing/channel-router.ts

@@ -1,4 +1,5 @@
 import {
+	type BackgroundTarget,
 	type BackgroundTurn,
 	type ChannelClaim,
 	type ConversationPort,
@@ -17,8 +18,8 @@ export interface ChannelRouterOptions {
 	/** Claims in registration order; the router orders them by priority. */
 	claims: readonly ChannelClaim[];
 	queue: ChannelQueue;
-	/** Stops the channel's running turn; false when none runs. */
-	stop(channel: ChannelKey): boolean;
+	/** The contributed background target of a name, read at use time. */
+	targets(name: string): BackgroundTarget | undefined;
 	logger: Logger;
 	/** How long a bare forward waits for the text sent with it; FORWARD_JOIN_MS by default. */
 	forwardJoinMs?: number;
@@ -53,8 +54,8 @@ export class ChannelRouter implements ConversationPort {
 		this.#forwards = new ForwardJoin(options.forwardJoinMs);
 	}
 
-	#owner(channel: ChannelKey, guildId?: string): ChannelClaim | undefined {
-		return this.#claims.find((claim) => claim.owns(channel, guildId));
+	#owner(channel: ChannelKey, space?: string): ChannelClaim | undefined {
+		return this.#claims.find((claim) => claim.owns(channel, space));
 	}
 
 	/**
@@ -74,7 +75,7 @@ export class ChannelRouter implements ConversationPort {
 			!message.forwarded?.text.trim()
 		)
 			return;
-		const admission = this.#owner(message.channel, message.guildId)?.admit(
+		const admission = this.#owner(message.channel, message.space)?.admit(
 			message,
 		);
 		if (!admission) return;
@@ -108,8 +109,20 @@ export class ChannelRouter implements ConversationPort {
 			);
 	}
 
-	/** A turn nobody wrote, run by the channel's claim inside its queue; never rejects. */
+	target(name: string): BackgroundTarget | undefined {
+		return this.#options.targets(name);
+	}
+
+	/**
+	 * A turn nobody wrote, run by the channel's claim inside its queue; never rejects. A turn whose
+	 * target no plugin contributes is skipped, never handed to another target's claim.
+	 */
 	async background(turn: BackgroundTurn): Promise<ScheduledOutcome> {
+		if (!this.#options.targets(turn.target))
+			return {
+				status: "skipped",
+				reason: `no plugin contributes the background target "${turn.target}"`,
+			};
 		try {
 			return await this.#options.queue.run(turn.channel, async () => {
 				const claim = this.#owner(turn.channel);
@@ -147,8 +160,9 @@ export class ChannelRouter implements ConversationPort {
 		});
 	}
 
+	/** Asks only the claim that owns the channel; false when none does or it has no `stop`. */
 	stop(channel: ChannelKey): boolean {
-		return this.#options.stop(channel);
+		return this.#owner(channel)?.stop?.(channel) ?? false;
 	}
 
 	postsInPlace(channel: ChannelKey): boolean {

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

@@ -0,0 +1,139 @@
+import type { AgentRuntime } from "../contract/runtime.ts";
+import type { SurfacePort } from "../contract/surface.ts";
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type { TurnResult } from "../domain/conversation.ts";
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+import type { EventSink } from "../plugin.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+import { thinkingLine } from "../presentation/thinking-line.ts";
+import type { ChannelKey, ToolSelection, TurnSelection } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import { settleTurn } from "./settle-turn.ts";
+
+/** One turn of a conversation, as a claim asks for it. */
+export interface ConversationTurnInput {
+	/** The conversation's channel; its surface shows typing and the stop control, and posts the reply. */
+	channel: ChannelKey;
+	/** The conversation's kind: picks the persona of its session, fixed when the session is made. */
+	kind: string;
+	text: string;
+	/** Who the turn is for; its tier limits the tools. */
+	speaker: Speaker;
+	/** Files and images the message carries. */
+	attachments?: TurnAttachments;
+	/** The turn's tools; by default the plugins' `agentSelection`, read at the turn. */
+	selection?: TurnSelection;
+	/** The owner's own chat turn, which their next messages may steer. */
+	steerable?: boolean;
+	/** The turn may ask the owner on the surface's prompts, such as approvals of held actions. */
+	interactive?: boolean;
+	/** The owner confirmed the channel's held actions, so they may run in this turn. */
+	confirmed?: boolean;
+	/**
+	 * Posts the turn's outcome in place of the default reply (the text, or a failure or stopped
+	 * notice); the claim formats its own. A throw is logged, never rethrown.
+	 */
+	reply?(result: TurnResult): Promise<void>;
+}
+
+/**
+ * Runs the turns of conversations a claim owns, through the runtime and the surfaces, so a claim
+ * writes no turn pipeline of its own.
+ */
+export interface ConversationTurns {
+	/**
+	 * Runs one turn in a conversation the caller's claim owns; call it inside the claim's queue
+	 * 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.
+	 */
+	run(input: ConversationTurnInput): Promise<TurnResult>;
+}
+
+export interface ConversationTurnsOptions {
+	/** Throws NotLinkedError until every plugin is set up and linked. */
+	linked: () => void;
+	/** The runtime that runs the turn; throws PluginError when the host has none yet. */
+	runtime: () => AgentRuntime;
+	surfaces: SurfacePort;
+	events: EventSink;
+	/** The plugins' agent selection, read at each turn that gives none of its own. */
+	selection: () => ToolSelection;
+	logger: Logger;
+}
+
+/** The selection of a turn that gives none: the plugins' `agentSelection`. */
+const DEFAULT_SELECTION = "turns";
+
+export function conversationTurns(
+	options: ConversationTurnsOptions,
+): ConversationTurns {
+	const { surfaces, events, logger } = options;
+	return {
+		async run(input) {
+			const { channel, kind, speaker } = input;
+			options.linked();
+			// A host without a runtime is a setup mistake, so it is refused before anything is shown.
+			const runtime = options.runtime();
+			const stopTyping = surfaces.startTyping(channel);
+			const hideStop = surfaces.showStop(channel);
+			const turn = { kind, channel, speaker };
+			events.turnStarted(turn);
+			let result: TurnResult;
+			try {
+				result = await settleTurn(
+					() =>
+						runtime.runTurn({
+							channel,
+							kind,
+							selection: input.selection ?? {
+								id: DEFAULT_SELECTION,
+								...options.selection(),
+							},
+							text: input.text,
+							speaker,
+							...(input.attachments ? { attachments: input.attachments } : {}),
+							...(input.confirmed ? { confirmed: true } : {}),
+							...(input.steerable ? { steerable: true } : {}),
+							...(input.interactive ? { interactive: true } : {}),
+						}),
+					"conversation turn",
+				);
+			} finally {
+				hideStop();
+			}
+			events.turnEnded({
+				...turn,
+				result: result.ok ? "ok" : result.stopped ? "stopped" : "failed",
+			});
+			try {
+				if (!result.ok && !result.stopped)
+					logger.error({ channel, kind, err: result.error }, "turn failed");
+				if (input.reply) await input.reply(result);
+				else await surfaces.sendReply(channel, replyOf(result));
+			} catch (error) {
+				logger.error({ channel, kind, err: error }, "reply not posted");
+			} finally {
+				stopTyping();
+			}
+			return result;
+		},
+	};
+}
+
+/** The default post: the answer with its thinking line, or the failure or stopped notice. */
+function replyOf(result: TurnResult) {
+	if (!result.ok)
+		return {
+			chunks: [
+				result.stopped ? messages().stoppedNotice : messages().failureNotice,
+			],
+		};
+	const thinking = result.thinking ? thinkingLine(result.thinking) : undefined;
+	return {
+		...(thinking ? { thinking } : {}),
+		chunks: splitReply(result.text),
+	};
+}

package/src/core/routing/message-text.ts

@@ -1,6 +1,13 @@
-import type { InboundMessage } from "../domain/conversation.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { ChannelKey, InboundMessage } from "../domain/conversation.ts";
 import type { OwnerIdentity } from "../identity.ts";
 
+/** How the model is told where a forward came from: a Discord channel as its mention, another surface's as its key. */
+function sourceLabel(source: ChannelKey): string {
+	const { surface, id } = parseChannelKey(source);
+	return surface === "discord" ? `<#${id}>` : source;
+}
+
 /** The message text, then the message it replies to and the message it forwards, when there are. */
 export function withReference(
 	message: InboundMessage,
@@ -12,5 +19,5 @@ export function withReference(
 		: message.text;
 	const forwarded = message.forwarded;
 	if (!forwarded) return replied;
-	return `${replied}\n\n## Forwarded by ${owner.name} from ${forwarded.channelMention} (${forwarded.url})\n${forwarded.text.trim() || "(no text; see the attachments)"}`.trim();
+	return `${replied}\n\n## Forwarded by ${owner.name} from ${sourceLabel(forwarded.source)} (${forwarded.url})\n${forwarded.text.trim() || "(no text; see the attachments)"}`.trim();
 }

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

@@ -0,0 +1,39 @@
+import type { ChatSurface, SurfacePort } from "../contract/surface.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import { PluginError } from "../errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/**
+ * 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 {
+	const of = (channel: ChannelKey): ChatSurface | undefined => {
+		const at = channel.indexOf(":");
+		if (at <= 0) return undefined;
+		const prefix = channel.slice(0, at);
+		return linked().find((surface) => surface.surface === prefix);
+	};
+	const served = (channel: ChannelKey): ChatSurface => {
+		const surface = of(channel);
+		if (!surface)
+			throw new PluginError(
+				`no chat surface serves "${parseChannelKey(channel).surface}" channels, such as ${channel}. A plugin contributes one with \`surfaces\`.`,
+			);
+		return surface;
+	};
+	return {
+		of,
+		sendReply: async (channel, reply) =>
+			served(channel).sendReply(channel, reply),
+		startTyping: (channel) =>
+			of(channel)?.startTyping?.(channel) ?? (() => undefined),
+		showStop: (channel) =>
+			of(channel)?.showStop?.(channel) ?? (() => undefined),
+		react: async (channel, messageId, emoji) =>
+			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),
+	};
+}

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

@@ -91,7 +91,7 @@ export class ConversationSessions {
 	 */
 	session(
 		key: ChannelKey,
-		request?: Pick<TurnRequest, "channel" | "agent">,
+		request?: Pick<TurnRequest, "channel" | "agent" | "kind">,
 	): Promise<ChannelSession> {
 		let pending = this.#sessions.get(key);
 		if (!pending) {
@@ -107,6 +107,7 @@ export class ConversationSessions {
 					this.slot(key),
 					ownerAttachmentDir(this.#options.dataDir, channel),
 					agent,
+					request?.kind ?? "owner",
 				))();
 			pending.catch(() => this.#sessions.delete(key));
 			this.#sessions.set(key, pending);
@@ -114,7 +115,7 @@ export class ConversationSessions {
 		return pending;
 	}
 
-	/** The conversation's session, rebuilt with its history when its connectors or skills changed. */
+	/** The conversation's session, rebuilt with its history when its session tools or skills changed. */
 	async freshSession(
 		key: ChannelKey,
 		request: TurnRequest,
@@ -137,7 +138,7 @@ export class ConversationSessions {
 		request: TurnRequest,
 	): string | undefined {
 		if (channelSession.revisions !== revisionsKey(this.#factory.plan))
-			return "connectors changed";
+			return "session tools changed";
 		if (
 			channelSession.skills !== skillsKey(this.#factory.skillsOf(request.agent))
 		)

package/src/core/runtime/extensions/confirmation-fixture.ts

@@ -0,0 +1,11 @@
+import type { HoldRule } from "../../holds.ts";
+
+/** A tool that waits for the owner's confirmation in the gate's tests. */
+export const MAIL = "send-mail";
+
+/** The one neutral hold rule the gate's tests use: sending mail waits for the owner. */
+export const MAIL_RULE: HoldRule = {
+	name: "mail",
+	describe: (tool, input) =>
+		tool === MAIL ? `send an email to ${String(input.to)}` : undefined,
+};

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -4,7 +4,6 @@ import type {
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import type { OwnerPrompts } from "../../domain/owner-prompts.ts";
-import type { ProfileId } from "../../domain/profile.ts";
 import type { HoldCheck } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
@@ -46,15 +45,15 @@ function byCodeUnit(a: string, b: string): number {
 }
 
 /**
- * Per-channel state of held actions. With the owner's prompts bound, a call that needs his
- * confirmation waits for his answer on a card and runs or is refused in the same turn. Otherwise,
+ * Per-channel state of held actions. With the owner's prompts bound, a call that needs their
+ * confirmation waits for their answer on a card and runs or is refused in the same turn. Otherwise,
  * or when the card expires, the call is held: it records its tool and exact input, and the
  * owner's next message either confirms them, which lets each identical call run once in that
  * turn, or drops them.
  */
 // pi-lens-ignore: large-class — one gate per conversation; its state is the held calls and their approvals
 export class ConfirmationGate {
-	#profile: ProfileId = "general";
+	#selectionId: string | undefined;
 	#pending: PendingConfirmation | undefined;
 	#approved: HeldCall[] = [];
 	readonly #holds: HoldCheck;
@@ -94,11 +93,11 @@ export class ConfirmationGate {
 
 	/** `addressee` is who the turn is for; without one, the owner. */
 	beginTurn(
-		profile: ProfileId,
+		selectionId: string,
 		confirmed: boolean,
 		addressee?: OwnerIdentity,
 	): void {
-		this.#profile = profile;
+		this.#selectionId = selectionId;
 		this.#addressee = addressee ?? this.#owner;
 		this.#approved = confirmed ? [...(this.pending()?.calls ?? [])] : [];
 		this.#pending = undefined;
@@ -115,8 +114,8 @@ export class ConfirmationGate {
 	}
 
 	/**
-	 * Like `hold`, but asks the owner on a card first when `prompts` is given: his approval runs
-	 * the call, his refusal blocks it, and only an expired card holds it.
+	 * Like `hold`, but asks the owner on a card first when `prompts` is given: their approval runs
+	 * the call, their refusal blocks it, and only an expired card holds it.
 	 */
 	async review(
 		tool: string,
@@ -175,8 +174,11 @@ export class ConfirmationGate {
 	}
 
 	#record(call: HeldCall): string {
+		const selectionId = this.#selectionId;
+		if (selectionId === undefined)
+			throw new Error("a call was held outside a turn");
 		const pending = this.#pending ?? {
-			profile: this.#profile,
+			selectionId,
 			heldAt: new Date(),
 			calls: [],
 		};

package/src/core/runtime/mcp.ts

@@ -8,7 +8,7 @@ export interface VirtualServer {
 	tools: string[];
 }
 
-/** The owner's MCP gateway virtual servers, reached with the process's admin token. */
+/** MCP endpoints supplied by a session plugin, reached with its bearer token. */
 export function mcpExtension(
 	servers: readonly VirtualServer[],
 	token: string,

package/src/core/runtime/pending-confirmation-store.ts

@@ -5,10 +5,9 @@ import type {
 	HeldCall,
 	PendingConfirmation,
 } from "../domain/conversation.ts";
-import type { ProfileId } from "../domain/profile.ts";
 
 interface Row {
-	profile: ProfileId;
+	selection_id: string;
 	held_at: Date;
 	calls: string;
 }
@@ -23,12 +22,12 @@ export class PendingConfirmationStore {
 
 	/** The store's tables; the host runs this before any store attaches. */
 	static readonly migration: Migration = {
-		name: "pending-confirmations",
+		name: "held-actions",
 		up: async (sql) => {
 			await sql`
-				CREATE TABLE IF NOT EXISTS pending_confirmations (
+				CREATE TABLE IF NOT EXISTS held_actions (
 					channel_key text PRIMARY KEY,
-					profile text NOT NULL,
+					selection_id text NOT NULL,
 					held_at timestamptz NOT NULL,
 					calls text NOT NULL
 				)`;
@@ -42,12 +41,12 @@ export class PendingConfirmationStore {
 
 	async load(channel: ChannelKey): Promise<PendingConfirmation | undefined> {
 		const rows: Row[] = await this.#sql`
-			SELECT profile, held_at, calls FROM pending_confirmations
+			SELECT selection_id, held_at, calls FROM held_actions
 			WHERE channel_key = ${channel}`;
 		const row = rows[0];
 		return row
 			? {
-					profile: row.profile,
+					selectionId: row.selection_id,
 					heldAt: row.held_at,
 					// pi-lens-ignore: unchecked-throwing-call — this store wrote the JSON; a corrupt row should fail loudly
 					calls: JSON.parse(row.calls) as HeldCall[],
@@ -61,15 +60,14 @@ export class PendingConfirmationStore {
 		pending: PendingConfirmation | undefined,
 	): Promise<void> {
 		if (!pending) {
-			await this
-				.#sql`DELETE FROM pending_confirmations WHERE channel_key = ${channel}`;
+			await this.#sql`DELETE FROM held_actions WHERE channel_key = ${channel}`;
 			return;
 		}
 		await this.#sql`
-			INSERT INTO pending_confirmations (channel_key, profile, held_at, calls)
-			VALUES (${channel}, ${pending.profile}, ${pending.heldAt},
+			INSERT INTO held_actions (channel_key, selection_id, held_at, calls)
+			VALUES (${channel}, ${pending.selectionId}, ${pending.heldAt},
 				${JSON.stringify(pending.calls)})
-			ON CONFLICT (channel_key) DO UPDATE SET profile = EXCLUDED.profile,
+			ON CONFLICT (channel_key) DO UPDATE SET selection_id = EXCLUDED.selection_id,
 				held_at = EXCLUDED.held_at, calls = EXCLUDED.calls`;
 	}
 }

package/src/core/runtime/pi-agent-runtime.ts

@@ -7,6 +7,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
 import { withAttachmentsBlock } from "../attachments/prompt-block.ts";
+import type { AgentRuntime } from "../contract/runtime.ts";
 import { NO_ATTACHMENTS, type TurnAttachments } from "../domain/attachment.ts";
 import type {
 	ChannelKey,
@@ -15,7 +16,7 @@ import type {
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentRunError, ConfigError } from "../domain/errors.ts";
-import type { AgentRuntime, TurnRequest } from "../domain/ports.ts";
+import type { TurnRequest } from "../domain/ports.ts";
 import { assistantName } from "../i18n/index.ts";
 import {
 	AUTO_THINKING,
@@ -99,13 +100,14 @@ export class PiAgentRuntime implements AgentRuntime {
 			new PromptSlot(),
 			join(this.#factory.workDir(), "probe-attachments"),
 			undefined,
+			"owner",
 		);
 		const registered = new Set(
 			probe.session.getAllTools().map((tool) => tool.name),
 		);
 		probe.session.dispose();
 		const expected = [
-			...this.#options.requiredTools,
+			...this.#factory.link().requiredTools,
 			COMPACT_TOOL,
 			ASK_USER_TOOL,
 			...planOrder(this.#factory.plan).flatMap(
@@ -115,7 +117,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		const missing = expected.filter((name) => !registered.has(name));
 		if (missing.length > 0) {
 			throw new ConfigError(
-				`profile tools are not registered: ${missing.join(", ")}`,
+				`required tools are not registered: ${missing.join(", ")}`,
 			);
 		}
 	}
@@ -152,10 +154,10 @@ export class PiAgentRuntime implements AgentRuntime {
 			logger.warn(
 				{
 					channel: request.channel,
-					profile: request.selection.id,
+					selection: request.selection.id,
 					missing,
 				},
-				"profile tools missing; running without them",
+				"selected tools missing; running without them",
 			);
 		}
 		channelSession.tools = wanted.filter((name) => registered.has(name));
@@ -256,7 +258,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			logger.info(
 				{
 					channel: key,
-					profile: request.selection.id,
+					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
@@ -326,6 +328,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			new PromptSlot(),
 			ownerAttachmentDir(dataDir, channel),
 			undefined,
+			"owner",
 		);
 		const { session } = worker;
 		const toolCalls: string[] = [];

package/src/core/runtime/prompt-slot.ts

@@ -2,10 +2,10 @@ import type { OwnerPrompts, OwnerQuestion } from "../domain/owner-prompts.ts";
 import { assistantName } from "../i18n/index.ts";
 
 /**
- * A run's way to ask the owner while it works. A turn he started or a report turn binds the
+ * A run's way to ask the owner while it works. A turn they started or a report turn binds the
  * cards of its channel, and a coding worker those of its dispatch thread; a schedule's turn, or
- * a session with no Discord channel, leaves the slot empty and held actions wait for his next
- * message instead. The slot also counts how long the run waited on him, which its time limit
+ * a session with no Discord channel, leaves the slot empty and held actions wait for their next
+ * message instead. The slot also counts how long the run waited on them, which its time limit
  * leaves out.
  */
 export class PromptSlot {
@@ -58,6 +58,11 @@ export class PromptSlot {
 	}
 }
 
+/** A fresh slot, for a run that asks the owner while it works. */
+export function promptSlot(): PromptSlot {
+	return new PromptSlot();
+}
+
 /**
  * Calls `expire` once the run has worked `ms`, not counting time the slot spent waiting on the
  * owner's cards; returns a function that cancels it.

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

@@ -4,16 +4,12 @@ import type {
 	ExtensionFactory,
 	ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
+import type { AgentSessions, LoadedSkill } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
-import type { AgentTurnScope } from "../domain/ports.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { Logger } from "../log.ts";
-import type {
-	ThinkingLevel,
-	ThinkingPicker,
-	ThinkingSetting,
-} from "../models.ts";
+import type { ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
@@ -39,7 +35,7 @@ export interface PiAgentRuntimeOptions {
 	/** Who the conversations serve, as prompts and tool results name them. */
 	owner: OwnerIdentity;
 	agentDir: string;
-	/** Shared with the party broker, so logins refresh in one place. */
+	/** Shared by the host's sessions, so logins refresh in one place. */
 	modelRuntime: ModelRuntime;
 	dataDir: string;
 	model: { provider: string; id: string };
@@ -47,7 +43,6 @@ export interface PiAgentRuntimeOptions {
 	thinking: ThinkingLevel;
 	/** Picks the level of the assistant's turns and of agents whose thinking is `auto`. */
 	effort: ThinkingPicker;
-	persona: string;
 	/** Held actions survive a restart here, so a confirmation after one still runs. */
 	confirmations: Pick<PendingConfirmationStore, "load" | "save">;
 	logger: Logger;
@@ -57,13 +52,11 @@ export interface PiAgentRuntimeOptions {
 	 * A changed snapshot revision rebuilds each session on its next turn, keeping its history.
 	 */
 	sessions: () => LinkedSessions;
-	/** Tools startup refuses to run without, besides those the session tools require. */
-	requiredTools: readonly string[];
 	/** The agent server's sessions: their shared workspace, model, and skills. */
 	agents?: AgentSessions;
 	/**
 	 * Cards the owner answers in a channel, for interactive turns; undefined for a channel that
-	 * cannot show them. Without it every held action waits for his next message.
+	 * cannot show them. Without it every held action waits for their next message.
 	 */
 	prompts?: (
 		channel: ChannelKey,
@@ -77,26 +70,7 @@ export interface PiAgentRuntimeOptions {
 	mcpConnectTimeoutMs?: number;
 }
 
-export interface AgentSessions {
-	/** The shell's working directory, shared by every agent; writes outside it are held. */
-	workDir: string;
-	/**
-	 * The skills the agent carries, read at the start of every run; a change rebuilds its
-	 * sessions, keeping their history (repos-and-skills spec behavior 21).
-	 */
-	skills(name: string): readonly LoadedSkill[];
-	/** The agent's model (`<provider>/<id>`) and thinking setting, read at the start of every run. */
-	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;
-}
-
-/** A skill file a session loads; only its name and description enter the prompt. */
-export interface LoadedSkill {
-	name: string;
-	description: string;
-	file: string;
-}
+export type { AgentSessions, LoadedSkill };
 
 export const skillsKey = (skills: readonly LoadedSkill[]) =>
 	JSON.stringify(skills);
@@ -109,12 +83,12 @@ export interface CoreExtensions {
 	confirmationGate: ExtensionFactory;
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
-	profileTools: ExtensionFactory;
+	activeTools: ExtensionFactory;
 }
 
 /**
  * A session's extensions in load order: the tools phase, the core's attachment, gate, ask-user,
- * and compact guard, the compactor, the MCP phase, and profile-tools last, so its
+ * and compact guard, the compactor, the MCP phase, and active-tools last, so its
  * before_agent_start handler runs after every other extension's.
  */
 export function sessionExtensions(
@@ -135,13 +109,13 @@ export function sessionExtensions(
 		{ name: "self-compact-guard", factory: core.selfCompactGuard },
 		...contributed(plan.compaction ? [plan.compaction] : []),
 		...contributed(plan.mcp),
-		{ name: "profile-tools", factory: core.profileTools },
+		{ name: "active-tools", factory: core.activeTools },
 	];
 }
 
 export interface ChannelSession {
 	session: AgentSession;
-	/** Read by the profile-tools extension at the start of every run. */
+	/** Read by the active-tools extension at the start of every run. */
 	tools: readonly string[];
 	/** The session tools' revisions the session was built with, as revisionsKey. */
 	revisions: string;