pi-roundtable 0.1.0

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

@@ -0,0 +1,16 @@
+import type { InboundMessage } from "../domain/conversation.ts";
+import type { OwnerIdentity } from "../identity.ts";
+
+/** The message text, then the message it replies to and the message it forwards, when there are. */
+export function withReference(
+	message: InboundMessage,
+	owner: OwnerIdentity,
+): string {
+	const quoted = message.reference?.text.trim();
+	const replied = quoted
+		? `${message.text}\n\n## The message this replies to\n${quoted}`
+		: 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();
+}

package/src/core/routing/settle-turn.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { AgentRunError } from "../domain/errors.ts";
+import { settleTurn } from "./settle-turn.ts";
+
+describe("settleTurn", () => {
+	test("passes a finished turn's result through", async () => {
+		expect(await settleTurn(async () => ({ ok: true }), "turn")).toEqual({
+			ok: true,
+		});
+	});
+
+	test("turns a thrown error into a failed result naming what crashed", async () => {
+		const result = await settleTurn(async () => {
+			throw new Error("socket closed");
+		}, "party turn");
+		expect(result).toEqual({
+			ok: false,
+			error: new AgentRunError("party turn crashed: Error: socket closed"),
+		});
+	});
+});

package/src/core/routing/settle-turn.ts

@@ -0,0 +1,26 @@
+import type { ScheduledOutcome } from "../contract/channels.ts";
+import { AgentRunError } from "../domain/errors.ts";
+
+/** Runs a turn; a thrown error becomes its failed result, labelled `<what> crashed`. */
+export async function settleTurn<R>(
+	run: () => Promise<R>,
+	what: string,
+): Promise<R | { ok: false; error: AgentRunError }> {
+	try {
+		return await run();
+	} catch (error) {
+		return {
+			ok: false,
+			error: new AgentRunError(`${what} crashed: ${String(error)}`),
+		};
+	}
+}
+
+/** The result of a turn nobody wrote, as the scheduler and reports see it. */
+export function outcome(
+	result: { ok: true } | { ok: false; error: { message: string } },
+): ScheduledOutcome {
+	return result.ok
+		? { status: "ran" }
+		: { status: "failed", error: result.error.message };
+}

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

@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test";
+import {
+	type ExtensionAPI,
+	SessionManager,
+	shouldCompact,
+} from "@earendil-works/pi-coding-agent";
+import {
+	CompactionTiers,
+	compactionEngine,
+	HARD_COMPACT_TOKENS,
+	SOFT_COMPACT_TOKENS,
+} from "./compaction-tiers.ts";
+
+const WINDOWS: Record<string, number> = {
+	"anthropic/claude-opus-5-5": 1_000_000,
+	"anthropic/claude-200k-opus-5-5": 200_000,
+};
+const LARGE = { provider: "anthropic", id: "claude-opus-5-5" };
+const SMALL = { provider: "anthropic", id: "claude-200k-opus-5-5" };
+const PI_RESERVE = 16_384;
+/** The `engine` a compaction extension records in its compactions' details. */
+const EXTENSION_ENGINE = "acme-compaction";
+
+/** pi estimates a message at a token per four characters. */
+function text(tokens: number): string {
+	return "x".repeat(tokens * 4);
+}
+
+function say(session: SessionManager, tokens: number): string {
+	return session.appendMessage({
+		role: "user",
+		content: text(tokens),
+		timestamp: Date.now(),
+	});
+}
+
+/** Appends a compaction that leaves about `left` tokens: its summary and one small kept message. */
+function compacted(
+	session: SessionManager,
+	engine: "extension" | "pi",
+	left: number,
+): void {
+	const kept = say(session, 1_000);
+	session.appendCompaction(
+		text(left - 1_000),
+		kept,
+		SOFT_COMPACT_TOKENS,
+		engine === "extension" ? { engine: EXTENSION_ENGINE } : {},
+	);
+}
+
+function tiersOver(session: SessionManager): CompactionTiers {
+	return new CompactionTiers(
+		session,
+		(provider, id) => WINDOWS[`${provider}/${id}`],
+		EXTENSION_ENGINE,
+	);
+}
+
+/** The context size the model compacts past, as pi's own check sees it. */
+function trigger(tiers: CompactionTiers, model = LARGE): number {
+	const settings = tiers.settings().getCompactionSettings(model);
+	const window = WINDOWS[`${model.provider}/${model.id}`] ?? 0;
+	const at = window - settings.reserveTokens;
+	expect(shouldCompact(at, window, settings)).toBe(false);
+	expect(shouldCompact(at + 1, window, settings)).toBe(true);
+	return at;
+}
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+/** Loads a stand-in for a compaction extension through the tiers' wrapper. */
+function loadExtension(tiers: CompactionTiers) {
+	const extensionCalls: number[] = [];
+	const bypasses: { reason: string; tokensBefore: number }[] = [];
+	const handlers = new Map<string, Handler>();
+	const onStart: Handler = () => undefined;
+	tiers.wrapCompactor(
+		(pi) => {
+			pi.on("session_start", onStart as never);
+			pi.on("session_before_compact", (event) => {
+				extensionCalls.push(event.preparation.tokensBefore);
+				return { compaction: { summary: "extension" } } as never;
+			});
+		},
+		(bypass) => bypasses.push(bypass),
+	)({
+		on: (event: string, handler: Handler) => handlers.set(event, handler),
+	} as unknown as ExtensionAPI);
+	const compact = (tokensBefore: number) =>
+		handlers.get("session_before_compact")?.(
+			{ type: "session_before_compact", preparation: { tokensBefore } },
+			{},
+		);
+	return { compact, extensionCalls, bypasses, onStart, handlers };
+}
+
+describe("soft threshold", () => {
+	test("a 1M model compacts past 300k", () => {
+		const tiers = tiersOver(SessionManager.inMemory("/tmp"));
+		expect(trigger(tiers)).toBe(SOFT_COMPACT_TOKENS);
+	});
+
+	test("a 200k model keeps pi's default reserve", () => {
+		const tiers = tiersOver(SessionManager.inMemory("/tmp"));
+		expect(tiers.settings().getCompactionSettings(SMALL).reserveTokens).toBe(
+			PI_RESERVE,
+		);
+		expect(trigger(tiers, SMALL)).toBe(200_000 - PI_RESERVE);
+	});
+
+	test("an unknown model keeps pi's default reserve", () => {
+		const tiers = tiersOver(SessionManager.inMemory("/tmp"));
+		expect(
+			tiers.settings().getCompactionSettings({ provider: "x", id: "y" })
+				.reserveTokens,
+		).toBe(PI_RESERVE);
+	});
+});
+
+describe("hard ceiling", () => {
+	test("a compaction above 500k skips the extension, so pi's summary runs", async () => {
+		const extension = loadExtension(tiersOver(SessionManager.inMemory("/tmp")));
+		expect(await extension.compact(HARD_COMPACT_TOKENS + 1)).toBeUndefined();
+		expect(extension.extensionCalls).toEqual([]);
+		expect(extension.bypasses).toEqual([
+			{
+				reason: "above the hard ceiling",
+				tokensBefore: HARD_COMPACT_TOKENS + 1,
+			},
+		]);
+	});
+
+	test("a compaction at or below 500k goes to the extension", async () => {
+		const extension = loadExtension(tiersOver(SessionManager.inMemory("/tmp")));
+		expect(await extension.compact(HARD_COMPACT_TOKENS)).toEqual({
+			compaction: { summary: "extension" },
+		});
+		expect(await extension.compact(SOFT_COMPACT_TOKENS + 1)).toEqual({
+			compaction: { summary: "extension" },
+		});
+		expect(extension.extensionCalls).toEqual([
+			HARD_COMPACT_TOKENS,
+			SOFT_COMPACT_TOKENS + 1,
+		]);
+		expect(extension.bypasses).toEqual([]);
+	});
+
+	test("after the extension left more than 500k, the next compaction is pi's", async () => {
+		const session = SessionManager.inMemory("/tmp");
+		say(session, 10_000);
+		compacted(session, "extension", 520_000);
+		const tiers = tiersOver(session);
+		expect(tiers.latest()?.contextTokens).toBeGreaterThan(HARD_COMPACT_TOKENS);
+		const extension = loadExtension(tiers);
+		expect(await extension.compact(450_000)).toBeUndefined();
+		expect(extension.extensionCalls).toEqual([]);
+		expect(extension.bypasses[0]?.reason).toContain(
+			"The extension's last compaction",
+		);
+	});
+
+	test("only session_before_compact is wrapped", () => {
+		const extension = loadExtension(tiersOver(SessionManager.inMemory("/tmp")));
+		expect(extension.handlers.get("session_start")).toBe(extension.onStart);
+	});
+});
+
+describe("no compaction loop", () => {
+	test("the extension leaving the context near 300k moves the next compaction to 500k", () => {
+		const session = SessionManager.inMemory("/tmp");
+		say(session, 10_000);
+		compacted(session, "extension", 310_000);
+		const tiers = tiersOver(session);
+		// The same request's next check sees about what the extension left, and does not compact again.
+		const settings = tiers.settings().getCompactionSettings(LARGE);
+		expect(shouldCompact(311_000, 1_000_000, settings)).toBe(false);
+		expect(trigger(tiers)).toBe(HARD_COMPACT_TOKENS);
+
+		session.appendMessage({
+			role: "user",
+			content: "small",
+			timestamp: Date.now(),
+		});
+		compacted(session, "extension", 280_000);
+		expect(trigger(tiers)).toBe(HARD_COMPACT_TOKENS);
+	});
+
+	test("a compaction well below 300k keeps the soft threshold", () => {
+		const session = SessionManager.inMemory("/tmp");
+		say(session, 10_000);
+		compacted(session, "extension", 310_000);
+		const tiers = tiersOver(session);
+		expect(trigger(tiers)).toBe(HARD_COMPACT_TOKENS);
+		// pi's summary at the ceiling brings the session back to the soft tier.
+		compacted(session, "pi", 30_000);
+		expect(trigger(tiers)).toBe(SOFT_COMPACT_TOKENS);
+	});
+
+	test("pi's summary leaving the context near 500k falls back to pi's own threshold", () => {
+		const session = SessionManager.inMemory("/tmp");
+		say(session, 10_000);
+		compacted(session, "pi", 480_000);
+		expect(trigger(tiersOver(session))).toBe(1_000_000 - PI_RESERVE);
+	});
+
+	test("the extension leaving the context near 500k still leaves pi the ceiling", () => {
+		const session = SessionManager.inMemory("/tmp");
+		say(session, 10_000);
+		compacted(session, "extension", 480_000);
+		expect(trigger(tiersOver(session))).toBe(HARD_COMPACT_TOKENS);
+	});
+});
+
+describe("compaction engine", () => {
+	test("a compaction is the extension's only when it records the engine the plugin declared", () => {
+		expect(
+			compactionEngine({ engine: EXTENSION_ENGINE }, EXTENSION_ENGINE),
+		).toBe("extension");
+		expect(compactionEngine({ engine: "other" }, EXTENSION_ENGINE)).toBe("pi");
+		expect(compactionEngine({}, EXTENSION_ENGINE)).toBe("pi");
+		expect(compactionEngine(undefined, EXTENSION_ENGINE)).toBe("pi");
+		expect(compactionEngine({ engine: EXTENSION_ENGINE }, undefined)).toBe(
+			"pi",
+		);
+	});
+});

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

@@ -0,0 +1,203 @@
+import {
+	type ExtensionAPI,
+	type ExtensionFactory,
+	estimateTokens,
+	type SessionBeforeCompactEvent,
+	type SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+/** Past this, a large-window session compacts through the compaction extension. */
+export const SOFT_COMPACT_TOKENS = 300_000;
+/** Past this, a compaction is pi's own summary, never the extension's. */
+export const HARD_COMPACT_TOKENS = 500_000;
+/**
+ * How far below a threshold a compaction must leave the context for that threshold to fire
+ * again, so a compaction that barely helped does not repeat on the next request.
+ */
+export const COMPACT_HEADROOM_TOKENS = 50_000;
+
+/** Who wrote a compaction: the plugin's compaction extension or Pi's own summary. */
+export type CompactionEngine = "extension" | "pi";
+
+/** The session reads the tiers need; a SessionManager or an extension's read-only one. */
+export type CompactionHistory = Pick<
+	SessionManager,
+	"getBranch" | "buildSessionProjection"
+>;
+
+export interface LatestCompaction {
+	id: string;
+	engine: CompactionEngine;
+	/** Estimated context the compaction left: its summary and the entries it kept. */
+	contextTokens: number;
+}
+
+/** The extension's compactions record its `engine` in their details; Pi's own do not. */
+export function compactionEngine(
+	details: unknown,
+	extensionEngine: string | undefined,
+): CompactionEngine {
+	const engine = (details as { engine?: unknown } | undefined)?.engine;
+	return extensionEngine !== undefined && engine === extensionEngine
+		? "extension"
+		: "pi";
+}
+
+/** The branch's latest compaction, measured from the session as it stands now. */
+export function latestCompaction(
+	history: CompactionHistory,
+	extensionEngine: string | undefined,
+): LatestCompaction | undefined {
+	const branch = history.getBranch();
+	const index = branch.findLastIndex((entry) => entry.type === "compaction");
+	const entry = branch[index];
+	if (entry?.type !== "compaction") return undefined;
+	const upToCompaction = new Set(
+		branch.slice(0, index + 1).map((each) => each.id),
+	);
+	let contextTokens = 0;
+	for (const projected of history.buildSessionProjection().entries) {
+		if (!upToCompaction.has(projected.sourceEntry.id)) continue;
+		for (const message of projected.messages)
+			contextTokens += estimateTokens(message);
+	}
+	return {
+		id: entry.id,
+		engine: compactionEngine(entry.details, extensionEngine),
+		contextTokens,
+	};
+}
+
+/**
+ * The context size a session compacts past, or undefined for pi's own threshold. Large windows
+ * compact at the soft threshold; a compaction that left the context near or above it moves the
+ * next one to the hard ceiling, and one of pi's that left it near the ceiling to pi's threshold.
+ */
+export function compactionTrigger(
+	contextWindow: number,
+	reserveTokens: number,
+	latest: LatestCompaction | undefined,
+): number | undefined {
+	const native = contextWindow - reserveTokens;
+	if (native <= SOFT_COMPACT_TOKENS) return undefined;
+	const left = latest?.contextTokens ?? 0;
+	if (left <= SOFT_COMPACT_TOKENS - COMPACT_HEADROOM_TOKENS)
+		return SOFT_COMPACT_TOKENS;
+	if (native <= HARD_COMPACT_TOKENS) return undefined;
+	// Only pi's summary fires at the ceiling, so the extension's compaction near it still leaves pi a turn.
+	const piStalled =
+		latest?.engine === "pi" &&
+		left > HARD_COMPACT_TOKENS - COMPACT_HEADROOM_TOKENS;
+	return piStalled ? undefined : HARD_COMPACT_TOKENS;
+}
+
+/** Why a compaction of this size must be pi's summary rather than the extension's, if it must. */
+export function extensionBypass(
+	tokensBefore: number,
+	latest: LatestCompaction | undefined,
+): string | undefined {
+	if (tokensBefore > HARD_COMPACT_TOKENS) return "above the hard ceiling";
+	if (
+		latest?.engine === "extension" &&
+		latest.contextTokens > HARD_COMPACT_TOKENS
+	)
+		return "The extension's last compaction left the context above the hard ceiling";
+	return undefined;
+}
+
+/** One session's compaction tiers, measured from its own history. */
+export class CompactionTiers {
+	readonly #history: CompactionHistory;
+	readonly #contextWindow: (provider: string, id: string) => number | undefined;
+	readonly #extensionEngine: string | undefined;
+	#cached: { id: string; latest: LatestCompaction } | undefined;
+
+	constructor(
+		history: CompactionHistory,
+		contextWindow: (provider: string, id: string) => number | undefined,
+		/** The `engine` the compaction extension records in its compactions' details. */
+		extensionEngine?: string,
+	) {
+		this.#history = history;
+		this.#contextWindow = contextWindow;
+		this.#extensionEngine = extensionEngine;
+	}
+
+	/** The latest compaction; measured once per compaction, since pi checks before every request. */
+	latest(): LatestCompaction | undefined {
+		const branch = this.#history.getBranch();
+		const entry = branch.findLast((each) => each.type === "compaction");
+		if (!entry) return undefined;
+		if (this.#cached?.id !== entry.id) {
+			const latest = latestCompaction(this.#history, this.#extensionEngine);
+			if (!latest) return undefined;
+			this.#cached = { id: entry.id, latest };
+		}
+		return this.#cached.latest;
+	}
+
+	/** The context size the model compacts past, or undefined for pi's own threshold. */
+	trigger(
+		model: { provider: string; id: string },
+		reserveTokens: number,
+	): number | undefined {
+		const window = this.#contextWindow(model.provider, model.id);
+		if (!window) return undefined;
+		return compactionTrigger(window, reserveTokens, this.latest());
+	}
+
+	/** pi's in-memory settings, with each model's reserve set so it compacts at its tier. */
+	settings(): SettingsManager {
+		const settings = SettingsManager.inMemory({});
+		const base = settings.getCompactionSettings.bind(settings);
+		settings.getCompactionSettings = (model) => {
+			const resolved = base(model);
+			const window = model && this.#contextWindow(model.provider, model.id);
+			const trigger = model && this.trigger(model, resolved.reserveTokens);
+			if (!window || trigger === undefined) return resolved;
+			return { ...resolved, reserveTokens: window - trigger };
+		};
+		return settings;
+	}
+
+	/**
+	 * 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.
+	 */
+	wrapCompactor(
+		compactor: ExtensionFactory,
+		onBypass: (details: { reason: string; tokensBefore: number }) => void,
+	): ExtensionFactory {
+		const gate = (event: SessionBeforeCompactEvent): boolean => {
+			const { tokensBefore } = event.preparation;
+			const reason = extensionBypass(tokensBefore, this.latest());
+			if (reason) onBypass({ reason, tokensBefore });
+			return reason === undefined;
+		};
+		type Handler = (event: unknown, ctx: unknown) => unknown;
+		return (pi) => {
+			const register = pi.on.bind(pi) as (
+				event: string,
+				handler: Handler,
+			) => () => void;
+			const on = ((event: string, handler: Handler) =>
+				register(
+					event,
+					event === "session_before_compact"
+						? (compaction, ctx) =>
+								gate(compaction as SessionBeforeCompactEvent)
+									? handler(compaction, ctx)
+									: undefined
+						: handler,
+				)) as ExtensionAPI["on"];
+			return compactor(
+				new Proxy(pi, {
+					get: (target, prop, receiver) =>
+						prop === "on" ? on : Reflect.get(target, prop, receiver),
+				}),
+			);
+		};
+	}
+}

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

@@ -0,0 +1,162 @@
+import { mkdirSync } from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
+import type {
+	ChannelKey,
+	PendingConfirmation,
+} from "../domain/conversation.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { ThinkingLevel } from "../models.ts";
+import type { ToolTiers } from "../tool-tiers.ts";
+import { ConfirmationGate } from "./extensions/confirmation-gate.ts";
+import { PromptSlot } from "./prompt-slot.ts";
+import type { ChannelSession, PiAgentRuntimeOptions } from "./runtime-types.ts";
+import { revisionsKey, skillsKey } from "./runtime-types.ts";
+import type { SessionFactory } from "./session-factory.ts";
+
+/** The open sessions of a runtime's conversations and what is held for each of them. */
+export class ConversationSessions {
+	readonly #options: PiAgentRuntimeOptions;
+	readonly #factory: SessionFactory;
+	readonly #tiers: ToolTiers;
+	readonly #sessions = new Map<ChannelKey, Promise<ChannelSession>>();
+	readonly #gates = new Map<ChannelKey, ConfirmationGate>();
+	/** Each conversation's way to ask the owner during its current turn. */
+	readonly #slots = new Map<ChannelKey, PromptSlot>();
+	/** Each conversation's level the judge picked for its last turn, kept while the judge is unsure. */
+	readonly judged = new Map<ChannelKey, ThinkingLevel>();
+	/** Each conversation's context use after its latest turn, for the agent dashboard. */
+	readonly usage = new Map<
+		ChannelKey,
+		{ tokens: number | null; contextWindow: number }
+	>();
+
+	constructor(
+		options: PiAgentRuntimeOptions,
+		factory: SessionFactory,
+		tiers: ToolTiers,
+	) {
+		this.#options = options;
+		this.#factory = factory;
+		this.#tiers = tiers;
+	}
+
+	/** The held actions of a conversation whose gate is open. */
+	pending(channel: ChannelKey): PendingConfirmation | undefined {
+		return this.#gates.get(channel)?.pending();
+	}
+
+	/** Disposes every open session. */
+	dispose(): void {
+		for (const pending of this.#sessions.values()) {
+			void pending
+				.then(({ session }) => session.dispose())
+				.catch(() => undefined);
+		}
+		this.#sessions.clear();
+	}
+
+	/**
+	 * One gate per conversation, restored from the store the first time it is used. An agent's
+	 * gate also judges its shell and file tools against the shared workspace.
+	 */
+	async gate(key: ChannelKey, agent: boolean): Promise<ConfirmationGate> {
+		let gate = this.#gates.get(key);
+		if (!gate) {
+			const workspace = agent ? this.#options.agents?.workDir : undefined;
+			gate = new ConfirmationGate(
+				this.#factory.link().holds,
+				this.#options.owner,
+				await this.#options.confirmations.load(key),
+				workspace,
+				this.#tiers,
+			);
+			this.#gates.set(key, gate);
+		}
+		return gate;
+	}
+
+	slot(key: ChannelKey): PromptSlot {
+		let slot = this.#slots.get(key);
+		if (!slot) {
+			slot = new PromptSlot();
+			this.#slots.set(key, slot);
+		}
+		return slot;
+	}
+
+	/**
+	 * The conversation's session, created on first use. `request` says what a new one is for:
+	 * an agent session gets the agent tools; absent, an owner channel's session is opened.
+	 */
+	session(
+		key: ChannelKey,
+		request?: Pick<TurnRequest, "channel" | "agent">,
+	): Promise<ChannelSession> {
+		let pending = this.#sessions.get(key);
+		if (!pending) {
+			const sessionDir = this.#factory.sessionDir(key);
+			mkdirSync(sessionDir, { recursive: true });
+			const channel = request?.channel ?? key;
+			const agent = request?.agent;
+			pending = (async () =>
+				this.#factory.create(
+					agent?.home ?? channel,
+					SessionManager.continueRecent(this.#factory.cwd(agent), sessionDir),
+					await this.gate(key, agent !== undefined),
+					this.slot(key),
+					ownerAttachmentDir(this.#options.dataDir, channel),
+					agent,
+				))();
+			pending.catch(() => this.#sessions.delete(key));
+			this.#sessions.set(key, pending);
+		}
+		return pending;
+	}
+
+	/** The conversation's session, rebuilt with its history when its connectors or skills changed. */
+	async freshSession(
+		key: ChannelKey,
+		request: TurnRequest,
+	): Promise<ChannelSession> {
+		const channelSession = await this.session(key, request);
+		const stale = this.#staleReason(channelSession, request);
+		if (!stale) return channelSession;
+		this.#options.logger.info(
+			{ channel: key },
+			`${stale}; rebuilding the session`,
+		);
+		channelSession.session.dispose();
+		this.#sessions.delete(key);
+		return this.session(key, request);
+	}
+
+	/** Why a cached session must be rebuilt before this turn, or undefined when it is current. */
+	#staleReason(
+		channelSession: ChannelSession,
+		request: TurnRequest,
+	): string | undefined {
+		if (channelSession.revisions !== revisionsKey(this.#factory.plan))
+			return "connectors changed";
+		if (
+			channelSession.skills !== skillsKey(this.#factory.skillsOf(request.agent))
+		)
+			return "skills changed";
+		return undefined;
+	}
+
+	/** Drops the open session and everything held for the conversation, leaving its files. */
+	// pi-lens-ignore: mixed-async-styles — disposal failures of a dropped session are swallowed in a chain on purpose
+	async forget(channel: ChannelKey): Promise<void> {
+		const pending = this.#sessions.get(channel);
+		this.#sessions.delete(channel);
+		await pending
+			?.then(({ session }) => session.dispose())
+			.catch(() => undefined);
+		this.#gates.delete(channel);
+		this.#slots.delete(channel);
+		this.usage.delete(channel);
+		this.judged.delete(channel);
+		await this.#options.confirmations.save(channel, undefined);
+	}
+}

package/src/core/runtime/extensions/agent-prompt.ts

@@ -0,0 +1,16 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Puts the agent's current prompt first in the system prompt's appended part before each run,
+ * keeping what earlier handlers appended, such as the owner memory section.
+ */
+export function agentPromptExtension(prompt: () => string): ExtensionFactory {
+	return (pi) => {
+		pi.on("before_agent_start", (event) => {
+			const appended = event.systemPromptOptions.appendSystemPrompt;
+			event.systemPromptOptions.appendSystemPrompt = appended
+				? `${prompt()}\n\n${appended}`
+				: prompt();
+		});
+	};
+}