pi-roundtable 0.1.0

package/src/core/runtime/session-archive.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { archiveSessions } from "./session-archive.ts";
+
+describe("archiveSessions", () => {
+	test("moves the conversations out of the top level, keeping them", () => {
+		const dir = mkdtempSync(join(tmpdir(), "roundtable-archive-"));
+		writeFileSync(join(dir, "a.jsonl"), "{}\n");
+		writeFileSync(join(dir, "notes.txt"), "stay");
+		expect(archiveSessions(dir, new Date("2026-09-27T01:02:03Z"))).toBe(1);
+		expect(readdirSync(dir).sort()).toEqual(["archive", "notes.txt"]);
+		expect(
+			readdirSync(join(dir, "archive", "2026-09-27T01-02-03.000Z")),
+		).toEqual(["a.jsonl"]);
+		expect(archiveSessions(dir)).toBe(0);
+		expect(archiveSessions(join(dir, "missing"))).toBe(0);
+	});
+});

package/src/core/runtime/session-archive.ts

@@ -0,0 +1,17 @@
+import { existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Moves a session directory's conversations into `archive/<time>/`, so the next session
+ * opened there starts with no history. Pi only reads `.jsonl` files at the directory's top
+ * level. Returns how many were moved.
+ */
+export function archiveSessions(dir: string, now = new Date()): number {
+	if (!existsSync(dir)) return 0;
+	const files = readdirSync(dir).filter((file) => file.endsWith(".jsonl"));
+	if (files.length === 0) return 0;
+	const target = join(dir, "archive", now.toISOString().replaceAll(":", "-"));
+	mkdirSync(target, { recursive: true });
+	for (const file of files) renameSync(join(dir, file), join(target, file));
+	return files.length;
+}

package/src/core/runtime/session-factory.ts

@@ -0,0 +1,291 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type AgentSession,
+	createAgentSession,
+	DefaultResourceLoader,
+	type ModelRuntime,
+	type SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { channelSegment } from "../attachments/attachment-dir.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import { ConfigError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { LinkedSessions } from "../plugin.ts";
+import {
+	planOrder,
+	type SessionContext,
+	type SessionPlan,
+	type ToolSelection,
+	type TransientTask,
+} from "../sessions.ts";
+import { packageDir } from "../shared/package-dir.ts";
+import { profileToolsExtension } from "../shared/profile-tools.ts";
+import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
+import { addressee, type Speaker, THE_SPEAKER } from "../speakers.ts";
+import {
+	CompactionTiers,
+	compactionEngine,
+	HARD_COMPACT_TOKENS,
+} from "./compaction-tiers.ts";
+import { ASK_USER_TOOL, askUserExtension } from "./extensions/ask-user.ts";
+import {
+	type ConfirmationGate,
+	confirmationGateExtension,
+} from "./extensions/confirmation-gate.ts";
+import {
+	COMPACT_TOOL,
+	selfCompactGuardExtension,
+} from "./extensions/self-compact-guard.ts";
+import type { PromptSlot } from "./prompt-slot.ts";
+import type {
+	ChannelSession,
+	CompactionEnd,
+	PiAgentRuntimeOptions,
+} from "./runtime-types.ts";
+import {
+	type LoadedSkill,
+	revisionsKey,
+	sessionExtensions,
+	skillsKey,
+} from "./runtime-types.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>;
+}
+
+/** Builds Pi sessions for the runtime: one resource loader per session, its extensions in order. */
+export class SessionFactory {
+	readonly #options: PiAgentRuntimeOptions;
+	readonly #modelRuntime: ModelRuntime;
+	readonly #deps: SessionFactoryDeps;
+	/** The linked session parts, with each package's directory; resolved on first use. */
+	#linked: (LinkedSessions & { extensionPaths: string[] }) | undefined;
+
+	constructor(options: PiAgentRuntimeOptions, deps: SessionFactoryDeps) {
+		this.#options = options;
+		this.#modelRuntime = options.modelRuntime;
+		this.#deps = deps;
+	}
+
+	link(): LinkedSessions & { extensionPaths: string[] } {
+		if (!this.#linked) {
+			const linked = this.#options.sessions();
+			this.#linked = {
+				...linked,
+				extensionPaths: linked.piPackages.map(packageDir),
+			};
+		}
+		return this.#linked;
+	}
+
+	get plan(): SessionPlan {
+		return this.link().plan;
+	}
+
+	toolsFor(selection: ToolSelection): string[] {
+		const groups = planOrder(this.plan).flatMap(
+			(tool) => tool.snapshot().groups ?? [],
+		);
+		return [
+			...selection.tools,
+			COMPACT_TOOL,
+			ASK_USER_TOOL,
+			...groups
+				.filter((group) => selection.groups.includes(group.name))
+				.flatMap((group) => group.tools),
+		];
+	}
+
+	/** Waits for the tools the session tools register late, such as pi-mcp-adapter's after its eager connection. */
+	async #awaitTools(
+		session: AgentSession,
+		expected: readonly string[],
+	): Promise<void> {
+		const deadline = Date.now() + (this.#options.mcpConnectTimeoutMs ?? 30_000);
+		while (Date.now() < deadline) {
+			const registered = new Set(
+				session.getAllTools().map((tool) => tool.name),
+			);
+			if (expected.every((name) => registered.has(name))) return;
+			await Bun.sleep(250);
+		}
+	}
+
+	workDir(): string {
+		const dir = join(this.#options.dataDir, "work");
+		mkdirSync(dir, { recursive: true });
+		return dir;
+	}
+
+	sessionDir(channel: ChannelKey): string {
+		return join(this.#options.dataDir, "sessions", channelSegment(channel));
+	}
+
+	/** An agent's carried skills; owner sessions carry none. */
+	skillsOf(agent: AgentTurnScope | undefined): readonly LoadedSkill[] {
+		const agents = this.#options.agents;
+		return agent && agents ? agents.skills(agent.name) : [];
+	}
+
+	/** Agents work in their shared workspace; owner sessions in the assistant's own. */
+	cwd(agent: AgentTurnScope | undefined): string {
+		const agents = this.#options.agents;
+		if (!agent || !agents) return this.workDir();
+		mkdirSync(agents.workDir, { recursive: true });
+		return agents.workDir;
+	}
+
+	/**
+	 * Logs who compacted a conversation, the compaction extension or Pi's summary, by how much, and the context size
+	 * that compacts it next, so a move to the hard ceiling shows.
+	 */
+	#logCompaction(
+		channel: ChannelKey,
+		event: CompactionEnd,
+		session: AgentSession,
+	): void {
+		const { logger } = this.#options;
+		const trigger = event.reason === "manual" ? "self" : event.reason;
+		if (!event.result) {
+			logger.warn(
+				{
+					channel,
+					trigger,
+					aborted: event.aborted,
+					error: event.errorMessage,
+				},
+				"compaction failed",
+			);
+			return;
+		}
+		const { model, settingsManager } = session;
+		logger.info(
+			{
+				channel,
+				trigger,
+				engine: compactionEngine(
+					event.result.details,
+					this.plan.compaction?.engine,
+				),
+				tokensBefore: event.result.tokensBefore,
+				tokensAfter: event.result.estimatedTokensAfter,
+				nextCompactionAt:
+					model &&
+					model.contextWindow -
+						settingsManager.getCompactionSettings(model).reserveTokens,
+			},
+			"conversation compacted",
+		);
+	}
+
+	/**
+	 * Each channel gets its own resource loader: Pi binds extension actions such as
+	 * setActiveTools to the loader's shared runtime, so sessions sharing a loader would
+	 * act on whichever session bound last.
+	 */
+	// pi-lens-ignore: long-parameter-list, high-fan-out — the build inputs of one session; its SessionContext is derived here from them
+	async create(
+		channel: ChannelKey,
+		sessionManager: SessionManager,
+		gate: ConfirmationGate,
+		slot: PromptSlot,
+		attachmentDir: string,
+		agent: AgentTurnScope | undefined,
+	): Promise<ChannelSession> {
+		const { agentDir, model, thinking, persona, logger } = this.#options;
+		const skills = this.skillsOf(agent);
+		const state = {
+			tools: [] as readonly string[],
+			revisions: revisionsKey(this.plan),
+			skills: skillsKey(skills),
+		};
+		const awaited = planOrder(this.plan).flatMap(
+			(tool) => tool.snapshot().awaitTools ?? [],
+		);
+		const cwd = this.cwd(agent);
+		const agents = agent ? this.#options.agents : undefined;
+		if (agent && !agents)
+			throw new ConfigError("agent turns need the runtime's agents option");
+		const tiers = new CompactionTiers(
+			sessionManager,
+			(provider, id) =>
+				this.#modelRuntime.getModel(provider, id)?.contextWindow,
+			this.plan.compaction?.engine,
+		);
+		const context: SessionContext = {
+			kind: agent ? "agent" : "owner",
+			homeChannel: channel,
+			turnChannel: agent && agents ? agents.turnChannel(agent) : channel,
+			compaction: {
+				wrap: (compactor) =>
+					tiers.wrapCompactor(compactor, (bypass) =>
+						logger.info(
+							{ channel, ...bypass, ceiling: HARD_COMPACT_TOKENS },
+							"compaction skips the extension for Pi's summary",
+						),
+					),
+			},
+			speaker: () => this.#deps.speaker(channel),
+			runTask: (task) => this.#deps.runTask(channel, task),
+		};
+		if (agent) context.agent = agent;
+		const resourceLoader = new DefaultResourceLoader({
+			cwd,
+			agentDir,
+			noExtensions: true,
+			noSkills: true,
+			additionalSkillPaths: skills.map((skill) => skill.file),
+			noPromptTemplates: true,
+			noThemes: true,
+			noContextFiles: true,
+			additionalExtensionPaths: this.link().extensionPaths,
+			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),
+				),
+				selfCompactGuard: selfCompactGuardExtension(),
+				profileTools: profileToolsExtension(() => state.tools),
+			}),
+			// An agent's prompt is set before each run by the agent-prompt extension.
+			appendSystemPrompt: agent ? [] : [persona],
+		});
+		await resourceLoader.reload();
+
+		const { session } = await createAgentSession({
+			cwd,
+			agentDir,
+			thinkingLevel: thinking,
+			modelRuntime: this.#modelRuntime,
+			resourceLoader,
+			sessionManager,
+			// Large windows compact through the extension at SOFT_COMPACT_TOKENS, and through pi's summary
+			// past HARD_COMPACT_TOKENS.
+			settingsManager: tiers.settings(),
+		});
+
+		// Extension providers such as claude-bridge exist only after the session loads its extensions.
+		const resolved = this.#modelRuntime.getModel(model.provider, model.id);
+		if (!resolved) {
+			session.dispose();
+			throw new ConfigError(
+				`model ${model.provider}/${model.id} is not available`,
+			);
+		}
+		await session.setModel(resolved);
+		await this.#awaitTools(session, awaited);
+		session.subscribe((event) => {
+			if (event.type === "compaction_end")
+				this.#logCompaction(channel, event, session);
+		});
+		return Object.assign(state, { session });
+	}
+}

package/src/core/runtime/steerable-run.test.ts

@@ -0,0 +1,264 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	type AssistantMessage,
+	createFauxCore,
+	type FauxResponseStep,
+	fauxAssistantMessage,
+	type TranscriptContext,
+} from "@earendil-works/pi-ai";
+import {
+	type AgentSession,
+	createAgentSession,
+	DefaultResourceLoader,
+	ModelRuntime,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { SteerableRun, type SteeringSession } from "./steerable-run.ts";
+
+/** A real Pi session on the faux provider, whose scripted answers may wait on the test. */
+async function fauxSession(steps: FauxResponseStep[]) {
+	const dir = mkdtempSync(join(tmpdir(), "roundtable-steer-"));
+	const core = createFauxCore({ provider: "faux", models: [{ id: "faux-1" }] });
+	core.setResponses(steps);
+	const modelRuntime = await ModelRuntime.create({
+		authPath: join(dir, "auth.json"),
+		modelsPath: null,
+		allowModelNetwork: false,
+		refreshOnCreate: false,
+	});
+	modelRuntime.registerProvider("faux", {
+		api: core.api,
+		apiKey: "test",
+		baseUrl: "http://faux.invalid",
+		streamSimple: core.streamSimple,
+		models: [
+			{
+				id: "faux-1",
+				name: "Faux",
+				reasoning: false,
+				input: ["text", "image"],
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 100_000,
+				maxTokens: 1_000,
+			},
+		],
+	});
+	const model = modelRuntime.getModel("faux", "faux-1");
+	if (!model) throw new Error("faux model not registered");
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: dir,
+		agentDir: dir,
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+	});
+	await resourceLoader.reload();
+	const { session } = await createAgentSession({
+		cwd: dir,
+		agentDir: dir,
+		modelRuntime,
+		model,
+		resourceLoader,
+		sessionManager: SessionManager.inMemory(),
+		settingsManager: SettingsManager.inMemory({}),
+		noTools: "all",
+	});
+	return { session, core };
+}
+
+/** A promise the test resolves by hand. */
+function gate() {
+	let open = () => {};
+	const opened = new Promise<void>((resolve) => {
+		open = resolve;
+	});
+	return { opened, open };
+}
+
+const userTexts = (context: TranscriptContext) =>
+	context.messages
+		.filter((m) => m.role === "user")
+		.map((m) =>
+			typeof m.content === "string"
+				? m.content
+				: m.content.map((c) => (c.type === "text" ? c.text : "")).join(""),
+		);
+
+const answers = (session: AgentSession) =>
+	session.messages
+		.filter((m): m is AssistantMessage => m.role === "assistant")
+		.map((m) =>
+			m.content.map((c) => (c.type === "text" ? c.text : "")).join(""),
+		);
+
+describe("SteerableRun on a Pi session", () => {
+	let seen: string[][];
+	beforeEach(() => {
+		seen = [];
+	});
+
+	test("a steer during the run is answered in the same turn", async () => {
+		const thinking = gate();
+		const started = gate();
+		const { session } = await fauxSession([
+			async (context) => {
+				seen.push(userTexts(context));
+				started.open();
+				await thinking.opened;
+				return fauxAssistantMessage("first answer");
+			},
+			(context) => {
+				seen.push(userTexts(context));
+				return fauxAssistantMessage("answer after the addition");
+			},
+		]);
+		const run = new SteerableRun(session, () => true);
+		const done = run.run(() => session.prompt("look this up for me"));
+		await started.opened;
+		expect(await run.steer("also check journald", [])).toBe(true);
+		thinking.open();
+		await done;
+		expect(run.steered).toBe(true);
+		expect(seen[1]).toEqual(["look this up for me", "also check journald"]);
+		expect(answers(session)).toEqual([
+			"first answer",
+			"answer after the addition",
+		]);
+	});
+
+	test("a steer at agent_end is answered in the same turn by Pi itself", async () => {
+		const { session } = await fauxSession([
+			fauxAssistantMessage("first answer"),
+			(context) => {
+				seen.push(userTexts(context));
+				return fauxAssistantMessage("answer after the addition");
+			},
+		]);
+		const run = new SteerableRun(session, () => true);
+		let late: Promise<boolean> | undefined;
+		// agent_end fires after Pi's last look at its steering queue.
+		session.subscribe((event) => {
+			if (event.type === "agent_end" && !late)
+				late = run.steer("a late addition", []);
+		});
+		await run.run(() => session.prompt("look this up for me"));
+		expect(await late).toBe(true);
+		expect(seen.at(-1)).toContain("a late addition");
+		expect(session.getSteeringMessages()).toEqual([]);
+	});
+
+	test("stop aborts the run and drops its steers", async () => {
+		const started = gate();
+		const { session, core } = await fauxSession([
+			(_context, options) => {
+				started.open();
+				return new Promise<AssistantMessage>((resolve) =>
+					options?.signal?.addEventListener("abort", () =>
+						resolve(fauxAssistantMessage("", { stopReason: "aborted" })),
+					),
+				);
+			},
+			fauxAssistantMessage("must not appear"),
+		]);
+		const run = new SteerableRun(session, () => true);
+		const done = run.run(() => session.prompt("a long-running job"));
+		await started.opened;
+		expect(await run.steer("this line is dropped", [])).toBe(true);
+		expect(run.stop()).toBe(true);
+		await done;
+		expect(run.stopped).toBe(true);
+		expect(core.state.callCount).toBe(1);
+		expect(session.getSteeringMessages()).toEqual([]);
+		expect(run.stop()).toBe(false);
+	});
+
+	test("a turn that may not be steered, or has ended, takes nothing", async () => {
+		const started = gate();
+		const finish = gate();
+		const { session } = await fauxSession([
+			async () => {
+				started.open();
+				await finish.opened;
+				return fauxAssistantMessage("done");
+			},
+		]);
+		const run = new SteerableRun(session, () => false);
+		const done = run.run(() => session.prompt("a scheduled job"));
+		await started.opened;
+		expect(await run.steer("cannot be inserted", [])).toBe(false);
+		finish.open();
+		await done;
+		expect(await run.steer("too late", [])).toBe(false);
+		expect(session.getSteeringMessages()).toEqual([]);
+	});
+});
+
+/**
+ * The window Pi leaves open: its input handling ends after the session settled, so the steer
+ * sits in the queue with no run to take it.
+ */
+class SettledSession {
+	isStreaming = true;
+	queue: string[] = [];
+	prompts: string[] = [];
+	async steer(text: string) {
+		this.queue.push(text);
+	}
+	getSteeringMessages() {
+		return this.queue;
+	}
+	clearQueue() {
+		const steering = this.queue;
+		this.queue = [];
+		return { steering, followUp: [] };
+	}
+	async abort() {}
+	async waitForIdle() {}
+	async prompt(text: string) {
+		this.prompts.push(text);
+	}
+}
+
+describe("SteerableRun leftovers", () => {
+	test("a steer Pi left queued as the run ended is prompted in the same turn", async () => {
+		const session = new SettledSession();
+		const run = new SteerableRun(
+			session as unknown as SteeringSession,
+			() => true,
+		);
+		await run.run(async () => {
+			expect(await run.steer("a late addition", [])).toBe(true);
+			session.isStreaming = false;
+		});
+		expect(session.prompts).toEqual(["a late addition"]);
+		expect(session.queue).toEqual([]);
+	});
+
+	test("a steer queued after the turn ended is taken back", async () => {
+		const session = new SettledSession();
+		const run = new SteerableRun(
+			session as unknown as SteeringSession,
+			() => true,
+		);
+		const settled = gate();
+		let late: Promise<boolean> | undefined;
+		session.steer = async (text: string) => {
+			// Pi's input handling finishes only after the turn is over.
+			await settled.opened;
+			session.queue.push(text);
+		};
+		await run.run(async () => {
+			late = run.steer("a late addition", []);
+		});
+		settled.open();
+		expect(await late).toBe(false);
+		expect(session.queue).toEqual([]);
+		expect(session.prompts).toEqual([]);
+	});
+});

package/src/core/runtime/steerable-run.ts

@@ -0,0 +1,109 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+export type PromptImages = NonNullable<Parameters<AgentSession["steer"]>[1]>;
+
+/** The part of a Pi session a steerable run drives. */
+export type SteeringSession = Pick<
+	AgentSession,
+	| "isStreaming"
+	| "steer"
+	| "getSteeringMessages"
+	| "clearQueue"
+	| "abort"
+	| "prompt"
+	| "waitForIdle"
+>;
+
+/**
+ * One turn of a Pi session that the owner may steer or stop. Pi checks its queue once more
+ * after a run, but a steer whose input handling ends after the session settled stays queued,
+ * where the next run would pick it up out of order; `run` answers it in the same turn instead.
+ */
+export class SteerableRun {
+	readonly #session: SteeringSession;
+	readonly #canSteer: () => boolean;
+	/** Steered prompts in arrival order, each with its images. */
+	readonly #steers: { text: string; images: PromptImages }[] = [];
+	#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) {
+		this.#session = session;
+		this.#canSteer = canSteer;
+	}
+
+	get stopped(): boolean {
+		return this.#stopped;
+	}
+
+	/** Whether any message was steered into the turn. */
+	get steered(): boolean {
+		return this.#steers.length > 0;
+	}
+
+	/** Runs the turn's first prompt, then any steer Pi left queued as the run ended. */
+	async run(first: () => Promise<void>): Promise<void> {
+		try {
+			await first();
+			for (
+				let left = this.#leftovers();
+				left.length > 0 && !this.#stopped;
+				left = this.#leftovers()
+			) {
+				this.#session.clearQueue();
+				await this.#session.waitForIdle();
+				const images = left.flatMap((steer) => steer.images);
+				await this.#session.prompt(
+					left.map((steer) => steer.text).join("\n\n"),
+					images.length > 0 ? { images } : undefined,
+				);
+			}
+		} finally {
+			// Synchronous with the last leftover check, so no steer slips between the two.
+			this.#done = true;
+		}
+	}
+
+	/** Adds the text to the running turn; false when it must wait for a turn of its own. */
+	async steer(text: string, images: PromptImages): Promise<boolean> {
+		if (
+			this.#stopped ||
+			this.#done ||
+			!this.#session.isStreaming ||
+			!this.#canSteer()
+		)
+			return false;
+		const steer = { text, images };
+		// Recorded first, so a run ending meanwhile finds it among the leftovers.
+		this.#steers.push(steer);
+		try {
+			await this.#session.steer(text, images.length > 0 ? images : undefined);
+		} catch (error) {
+			this.#steers.splice(this.#steers.indexOf(steer), 1);
+			throw error;
+		}
+		// Queued after the turn stopped taking steers: taken back to wait for its own turn.
+		if (this.#done && this.#session.getSteeringMessages().includes(text)) {
+			this.#session.clearQueue();
+			this.#steers.splice(this.#steers.indexOf(steer), 1);
+			return false;
+		}
+		return true;
+	}
+
+	/** Aborts the turn and drops what was steered into it; false once it has ended. */
+	stop(): boolean {
+		if (this.#done) return false;
+		this.#stopped = true;
+		this.#session.clearQueue();
+		void this.#session.abort();
+		return true;
+	}
+
+	/** Steers still in Pi's queue: sent as the run ended, so the model never saw them. */
+	#leftovers() {
+		const queued = this.#session.getSteeringMessages();
+		return this.#steers.filter((steer) => queued.includes(steer.text));
+	}
+}