pi-roundtable 0.20.0 → 0.22.0

package/src/core/modules/delegation/worker-session.ts

@@ -0,0 +1,111 @@
+import { mkdirSync } from "node:fs";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	type ExtensionFactory,
+	type ModelRuntime,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevel } from "../../models.ts";
+import { runWorkerTask } from "../../runtime/worker-task.ts";
+import type { WorkerSessionRequest, WorkerSessions } from "../../services.ts";
+import { activeToolsExtension } from "../../shared/active-tools.ts";
+
+export interface WorkerSessionOptions {
+	/** Shared with the rest of the host, so the Codex login refreshes in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	workDir: string;
+	/** `<provider>/<id>`. */
+	model: string;
+	thinking: ThinkingLevel;
+	prompt: string;
+	/** Installed Pi extension packages that register tools. */
+	extensionPaths?: readonly string[];
+	/** Extensions that register tools. */
+	extensions?: readonly { name: string; factory: ExtensionFactory }[];
+	/** The only tools active in the session; no built-in tool is. */
+	toolNames: readonly string[];
+	task: string;
+	signal: AbortSignal;
+	aborted: string;
+}
+
+/**
+ * Runs one task in a fresh, unsaved session with no built-in tool, no skills, no context files and
+ * only the named tools active, and returns the worker's report.
+ */
+export async function runWorkerSession(
+	options: WorkerSessionOptions,
+): Promise<string> {
+	const { modelRuntime, agentDir, workDir, model, thinking } = options;
+	mkdirSync(workDir, { recursive: true });
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: workDir,
+		agentDir,
+		noExtensions: true,
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		noContextFiles: true,
+		additionalExtensionPaths: [...(options.extensionPaths ?? [])],
+		extensionFactories: [
+			...(options.extensions ?? []),
+			// Last, so it undoes any tool another extension re-activates.
+			{
+				name: "worker-tools-only",
+				factory: activeToolsExtension(() => options.toolNames),
+			},
+		],
+		appendSystemPrompt: [options.prompt],
+	});
+	await resourceLoader.reload();
+	options.signal.throwIfAborted();
+	const { session } = await createAgentSession({
+		cwd: workDir,
+		agentDir,
+		thinkingLevel: thinking,
+		modelRuntime,
+		resourceLoader,
+		sessionManager: SessionManager.inMemory(workDir),
+		settingsManager: SettingsManager.inMemory({}),
+		noTools: "builtin",
+	});
+	return runWorkerTask(session, {
+		modelRuntime,
+		model,
+		task: options.task,
+		signal: options.signal,
+		aborted: options.aborted,
+	});
+}
+
+/** The `WORKER_SESSIONS` service: worker sessions on the host's model runtime and delegation settings. */
+export function workerSessions(options: {
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	workDir: string;
+	delegation: { model: string; thinking: ThinkingLevel };
+}): WorkerSessions {
+	return {
+		delegation: options.delegation,
+		run: (request: WorkerSessionRequest) =>
+			runWorkerSession({
+				modelRuntime: options.modelRuntime,
+				agentDir: options.agentDir,
+				workDir: options.workDir,
+				model: request.model ?? options.delegation.model,
+				thinking: request.thinking ?? options.delegation.thinking,
+				prompt: request.prompt,
+				extensions: request.extensions.map((factory, index) => ({
+					name: `worker-tools-${index}`,
+					factory,
+				})),
+				toolNames: request.toolNames,
+				task: request.task,
+				signal: request.signal,
+				aborted: request.aborted ?? "the worker ran out of time",
+			}),
+	};
+}

package/src/core/modules/skills/package-skills-fixture.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { packageDir } from "../../shared/package-dir.ts";
+
+/**
+ * Installs a fake npm package under `<root>/node_modules` with the layout of `pi-workflow-skills`:
+ * `"pi": { "skills": ["./skills"] }` and one folder with a SKILL.md per skill.
+ */
+export function installPackage(
+	root: string,
+	name: string,
+	skills: Record<string, string>,
+	manifest: Record<string, unknown> = { pi: { skills: ["./skills"] } },
+): void {
+	const dir = join(root, "node_modules", name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(
+		join(dir, "package.json"),
+		JSON.stringify({ name, version: "1.0.0", ...manifest }),
+	);
+	for (const [skill, description] of Object.entries(skills)) {
+		mkdirSync(join(dir, "skills", skill, "playbooks"), { recursive: true });
+		writeFileSync(
+			join(dir, "skills", skill, "SKILL.md"),
+			`---\nname: ${skill}\ndescription: ${description}\n---\n\n# ${skill}\n`,
+		);
+	}
+}
+
+/** Looks packages up from `<root>`, the way a host finds its own dependencies. */
+export const packageDirIn = (root: string) => (name: string) =>
+	packageDir(name, pathToFileURL(join(root, "host.js")));

package/src/core/modules/skills/package-skills.ts

@@ -0,0 +1,121 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as relativePath, resolve } from "node:path";
+import { PluginError } from "../../errors.ts";
+import { packageDir } from "../../shared/package-dir.ts";
+import {
+	BUILTIN_SKILLS,
+	checkSkillName,
+	type PackageSkill,
+	readSkillFile,
+} from "./skill-rules.ts";
+
+/** The SKILL.md files under `path`: the file itself, or each skill folder found below a directory. */
+function skillFilesAt(path: string): string[] {
+	if (statSync(path).isFile()) return [path];
+	if (existsSync(join(path, "SKILL.md"))) return [join(path, "SKILL.md")];
+	return readdirSync(path, { withFileTypes: true })
+		.filter(
+			(entry) =>
+				entry.isDirectory() &&
+				!entry.name.startsWith(".") &&
+				entry.name !== "node_modules",
+		)
+		.flatMap((entry) => skillFilesAt(join(path, entry.name)));
+}
+
+/** The `pi.skills` entries of a package manifest, or undefined when it declares none. */
+function manifestSkills(manifest: unknown): string[] | undefined {
+	const skills = (manifest as { pi?: { skills?: unknown } } | null)?.pi?.skills;
+	return Array.isArray(skills) &&
+		skills.length > 0 &&
+		skills.every((entry) => typeof entry === "string")
+		? skills
+		: undefined;
+}
+
+function packageSkillsOf(
+	name: string,
+	resolveDir: (name: string) => string,
+): PackageSkill[] {
+	let dir: string;
+	try {
+		dir = resolveDir(name);
+	} catch {
+		throw new PluginError(
+			`config skills.packages: the package "${name}" is not installed. Install it next to the host, or remove it from skills.packages.`,
+		);
+	}
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch (error) {
+		throw new PluginError(
+			`config skills.packages: the package "${name}" has no readable package.json (${(error as Error).message}). Reinstall it, or remove it from skills.packages.`,
+		);
+	}
+	const entries = manifestSkills(manifest);
+	if (!entries)
+		throw new PluginError(
+			`config skills.packages: the package "${name}" lists no skills in its package.json "pi.skills". Remove it from skills.packages, or use a package that ships skills.`,
+		);
+	const files = entries.flatMap((entry) => {
+		const path = resolve(dir, entry);
+		const relative = relativePath(dir, path);
+		if (relative.startsWith("..") || isAbsolute(relative))
+			throw new PluginError(
+				`config skills.packages: "${name}" lists the skills path "${entry}" outside the package. Use a package whose pi.skills stay inside it.`,
+			);
+		if (!existsSync(path))
+			throw new PluginError(
+				`config skills.packages: "${name}" lists the skills path "${entry}", which is not in the installed package. Reinstall the package, or remove it from skills.packages.`,
+			);
+		return skillFilesAt(path);
+	});
+	if (files.length === 0)
+		throw new PluginError(
+			`config skills.packages: the package "${name}" has no SKILL.md under its pi.skills. Remove it from skills.packages, or use a package that ships skills.`,
+		);
+	return files.map((file) => {
+		const read = readSkillFile(file);
+		if ("error" in read)
+			throw new PluginError(
+				`config skills.packages: the skill file ${relativePath(dir, file)} of "${name}" cannot be read (${read.error}). Reinstall the package, or remove it from skills.packages.`,
+			);
+		try {
+			checkSkillName(read.name);
+		} catch (error) {
+			throw new PluginError(
+				`config skills.packages: "${name}" holds a skill that cannot be offered. ${(error as Error).message} Use another version of the package, or remove it from skills.packages.`,
+			);
+		}
+		return { name: read.name, package: name, file };
+	});
+}
+
+/**
+ * The skills of installed npm packages, read from each package's `pi.skills` folders (Pi's
+ * manifest). Throws a PluginError naming the fix when a package is not installed or has no
+ * skills, or when two packages (or one package twice) offer the same name or a built-in name.
+ * A clash with a linked or written skill is found by the registry, which holds those.
+ */
+export function discoverPackageSkills(
+	packages: readonly string[],
+	resolveDir: (name: string) => string = packageDir,
+): PackageSkill[] {
+	const found = new Map<string, PackageSkill>();
+	for (const name of new Set(packages))
+		for (const skill of packageSkillsOf(name, resolveDir)) {
+			const earlier = found.get(skill.name);
+			if (earlier)
+				throw new PluginError(
+					`config skills.packages: the skill "${skill.name}" comes from both "${earlier.package}" and "${skill.package}". Drop one of the packages from skills.packages.`,
+				);
+			if ((BUILTIN_SKILLS as readonly string[]).includes(skill.name))
+				throw new PluginError(
+					`config skills.packages: the skill "${skill.name}" of "${skill.package}" has the name of a built-in skill. Drop the package from skills.packages.`,
+				);
+			found.set(skill.name, skill);
+		}
+	// pi-lens-ignore: no-sort-without-comparator — skill names sort by code unit, the same order on every machine
+	return [...found.values()].sort((a, b) => (a.name < b.name ? -1 : 1));
+}

package/src/core/modules/skills/skill-listing.ts

@@ -3,6 +3,7 @@ import {
 	BUILTIN_SKILLS,
 	cut,
 	MAX_LIST_DESCRIPTION_CHARS,
+	type PackageSkill,
 	type ResolvedSkill,
 	type SkillCatalogEntry,
 	type SkillSource,
@@ -17,6 +18,7 @@ export type SkillResolver = (
 /** Every skill, built-in ones first, with what `list` shows as text (web app spec behavior 15). */
 export function skillCatalog(
 	store: SkillStore,
+	packageSkills: readonly PackageSkill[],
 	resolveOne: SkillResolver,
 ): SkillCatalogEntry[] {
 	const sources: { name: string; source: SkillSource }[] = [
@@ -24,6 +26,10 @@ export function skillCatalog(
 			name,
 			source: { kind: "builtin" } as const,
 		})),
+		...packageSkills.map((skill) => ({
+			name: skill.name,
+			source: { kind: "package", package: skill.package } as const,
+		})),
 		...store.skills().map((entry) => ({
 			name: entry.name,
 			source:
@@ -51,6 +57,7 @@ export function skillCatalog(
 /** Every skill, or those of a group or matching a query (behavior 14). */
 export function skillListText(
 	store: SkillStore,
+	packageSkills: readonly PackageSkill[],
 	resolveOne: SkillResolver,
 	filter: { group?: string; query?: string } = {},
 ): string {
@@ -72,6 +79,10 @@ export function skillListText(
 	}));
 	const entries = [
 		...builtins,
+		...packageSkills.map((skill) => ({
+			name: skill.name,
+			source: `from the package ${skill.package}`,
+		})),
 		...store.skills().map((entry) => ({
 			name: entry.name,
 			source:

package/src/core/modules/skills/skill-registry.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { AgentError } from "../../domain/errors.ts";
+import { PluginError } from "../../errors.ts";
 import type { SkillRegistry } from "../../services.ts";
 import { planLinkedSkills } from "./skill-link.ts";
 import { skillCatalog, skillListText } from "./skill-listing.ts";
@@ -9,6 +10,7 @@ import {
 	checkBody,
 	checkDescription,
 	checkSkillName,
+	type PackageSkill,
 	type ResolvedSkill,
 	readSkillFile,
 	type SkillCatalogEntry,
@@ -22,6 +24,7 @@ export {
 	BUILTIN_SKILLS,
 	checkSkillName,
 	MAX_SKILL_BODY_CHARS,
+	type PackageSkill,
 	type ResolvedSkill,
 	type SkillCatalogEntry,
 	type SkillRegistryOptions,
@@ -32,9 +35,19 @@ export {
 /** The skill registry and what each agent carries. */
 export class StoredSkillRegistry implements SkillRegistry {
 	readonly #options: SkillRegistryOptions;
+	readonly #packageSkills = new Map<string, PackageSkill>();
 
+	/** Throws a PluginError when a package skill has the name of a linked or written one. */
 	constructor(options: SkillRegistryOptions) {
 		this.#options = options;
+		for (const skill of options.packageSkills ?? []) {
+			const stored = options.store.skill(skill.name);
+			if (stored)
+				throw new PluginError(
+					`The skill "${skill.name}" of the package "${skill.package}" clashes with a ${stored.kind} skill of the same name. Drop the package from skills.packages and start, remove the ${stored.kind} skill (${stored.kind === "linked" ? "skill_unlink" : "skill_delete"}), then list the package again.`,
+				);
+			this.#packageSkills.set(skill.name, skill);
+		}
 	}
 
 	/** Writes every agent-written skill for Pi and removes folders left by deleted ones. */
@@ -105,13 +118,18 @@ export class StoredSkillRegistry implements SkillRegistry {
 
 	/** Every skill, built-in ones first, with what `list` shows as text (web app spec behavior 15). */
 	catalog(): SkillCatalogEntry[] {
-		return skillCatalog(this.#options.store, (name) => this.#resolveOne(name));
+		return skillCatalog(
+			this.#options.store,
+			[...this.#packageSkills.values()],
+			(name) => this.#resolveOne(name),
+		);
 	}
 
 	/** Every skill, or those of a group or matching a query (behavior 14). */
 	list(filter: { group?: string; query?: string } = {}): string {
 		return skillListText(
 			this.#options.store,
+			[...this.#packageSkills.values()],
 			(name) => this.#resolveOne(name),
 			filter,
 		);
@@ -119,7 +137,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 
 	/** Throws when a name is not registered; built-in names are carried already. */
 	checkRegistered(names: readonly string[]): void {
-		const unknown = names.filter((name) => !this.#options.store.skill(name));
+		const unknown = names.filter((name) => !this.#registered(name));
 		if (unknown.length > 0)
 			throw new AgentError(
 				`Unknown skills: ${unknown.join(", ")}. Find names with skill_list.${unknown.some((n) => (BUILTIN_SKILLS as readonly string[]).includes(n)) ? " Built-in skills are always carried." : ""}`,
@@ -142,6 +160,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 	}
 
 	async unlink(name: string): Promise<string> {
+		this.#refusePackage(name);
 		const entry = this.#entry(name);
 		if (entry.kind !== "linked")
 			throw new AgentError(
@@ -206,7 +225,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 			throw new AgentError("A skill group needs a description.");
 		const unknown = skills.filter(
 			(skill) =>
-				!this.#options.store.skill(skill) &&
+				!this.#registered(skill) &&
 				!(BUILTIN_SKILLS as readonly string[]).includes(skill),
 		);
 		if (unknown.length > 0)
@@ -270,6 +289,8 @@ export class StoredSkillRegistry implements SkillRegistry {
 		const { store, reposDir, writtenDir, builtinDir } = this.#options;
 		if ((BUILTIN_SKILLS as readonly string[]).includes(name))
 			return join(builtinDir, name, "SKILL.md");
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage) return fromPackage.file;
 		const entry = store.skill(name);
 		if (!entry) return undefined;
 		return entry.kind === "linked"
@@ -288,7 +309,24 @@ export class StoredSkillRegistry implements SkillRegistry {
 		return entry;
 	}
 
+	#registered(name: string): boolean {
+		return (
+			this.#packageSkills.has(name) ||
+			this.#options.store.skill(name) !== undefined
+		);
+	}
+
+	/** Package skills change with their package, never here. */
+	#refusePackage(name: string): void {
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage)
+			throw new AgentError(
+				`${name} comes from the package ${fromPackage.package} and is read-only here. It changes when the package is upgraded.`,
+			);
+	}
+
 	#writable(name: string): Extract<SkillEntry, { kind: "written" }> {
+		this.#refusePackage(name);
 		const entry = this.#entry(name);
 		if (entry.kind !== "written")
 			throw new AgentError(
@@ -298,8 +336,14 @@ export class StoredSkillRegistry implements SkillRegistry {
 	}
 
 	#checkFreeName(name: string): void {
+		const fromPackage = this.#packageSkills.get(name);
+		if (fromPackage)
+			throw new AgentError(
+				`A skill named "${name}" already exists: it comes from the package ${fromPackage.package}.`,
+			);
 		if (
 			(BUILTIN_SKILLS as readonly string[]).includes(name) ||
+			this.#packageSkills.has(name) ||
 			this.#options.store.skill(name)
 		)
 			throw new AgentError(`A skill named "${name}" already exists.`);

package/src/core/modules/skills/skill-rules.ts

@@ -28,7 +28,8 @@ export interface SkillSet {
 export type SkillSource =
 	| { kind: "builtin" }
 	| { kind: "linked"; repo: string; path: string }
-	| { kind: "written" };
+	| { kind: "written" }
+	| { kind: "package"; package: string };
 
 /** One skill as the web app lists it; a skill whose file cannot be read has `missing` instead. */
 export interface SkillCatalogEntry {
@@ -43,6 +44,15 @@ export interface SkillCatalogEntry {
 	carriers: string[];
 }
 
+/** A skill an installed npm package offers through its `pi.skills` folders. */
+export interface PackageSkill {
+	name: string;
+	/** The npm package that holds it. */
+	package: string;
+	/** Its SKILL.md in the installed package. */
+	file: string;
+}
+
 export interface SkillRegistryOptions {
 	store: SkillStore;
 	/** Managed repositories, as `<dir>/<owner>/<repo>`. */
@@ -51,6 +61,8 @@ export interface SkillRegistryOptions {
 	writtenDir: string;
 	/** The release's built-in skills, as `<dir>/<name>/SKILL.md`. */
 	builtinDir: string;
+	/** Skills of installed packages, as `discoverPackageSkills` found them at startup. */
+	packageSkills?: readonly PackageSkill[];
 	logger: Logger;
 }
 

package/src/core/runtime/extensions/card-ask.ts

@@ -18,6 +18,8 @@ export interface CardAsk {
 	wait: PromptWait;
 	details: ApprovalDetails;
 	approvers: readonly string[] | undefined;
+	/** Only the speaker may answer the card; see `HoldDescription`. */
+	speakerOnly: boolean;
 	/** The call's watch, when its plugin may withdraw it. */
 	watch: Watch | undefined;
 }
@@ -41,6 +43,7 @@ export async function askOnCard(
 	const found: Omit<CardAnswer, "answer"> = {};
 	const options: ApprovalOptions = {
 		...(ask.approvers ? { approvers: ask.approvers } : {}),
+		...(ask.speakerOnly ? { speakerOnly: true } : {}),
 		approvedBy: (by) => {
 			found.approvedBy = by;
 		},

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

@@ -334,6 +334,7 @@ export class ConfirmationGate {
 				wait: { late: (late) => this.#late(call, late, watch) },
 				details: approvalDetails(call, this.#fileRoot, needing.copy),
 				approvers: call.approverIds,
+				speakerOnly: needing.speakerOnly === true,
 				watch,
 			},
 		);
@@ -446,6 +447,7 @@ export class ConfirmationGate {
 			held: call,
 			...(judged.copy ? { copy: judged.copy } : {}),
 			...(judged.supersede ? { supersede: judged.supersede } : {}),
+			...(judged.speakerOnly ? { speakerOnly: judged.speakerOnly } : {}),
 		};
 	}
 

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

@@ -34,6 +34,8 @@ export type Needing =
 			copy?: NonNullable<ApprovalDetails["copy"]>;
 			/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
 			supersede?: AbortSignal;
+			/** The card is the speaker's alone; see `HoldDescription`. */
+			speakerOnly?: true;
 	  }
 	| { released: Release };
 

package/src/core/runtime/extensions/hold-lookups.ts

@@ -32,6 +32,8 @@ export interface Judgment {
 	/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
 	supersede?: AbortSignal;
 	approvers?: readonly string[];
+	/** The card is the speaker's alone; see `HoldDescription`. */
+	speakerOnly?: true;
 }
 
 export type Judged = Judgment | undefined | typeof STOPPED;
@@ -55,13 +57,16 @@ function isSignal(value: unknown): value is AbortSignal {
 export function described(
 	answer: HoldDescription,
 	tool: string,
-): Pick<Judgment, "action" | "copy" | "supersede"> {
+): Pick<Judgment, "action" | "copy" | "supersede" | "speakerOnly"> {
 	if (typeof answer === "string") return { action: answer };
 	if (typeof answer !== "object" || answer === null)
 		return { action: messages().holdGeneric(tool) };
-	const { text, copy, supersede } = answer;
+	const { text, copy, supersede, approval } = answer;
 	if (typeof text !== "string") return { action: messages().holdGeneric(tool) };
-	const withdrawal = isSignal(supersede) ? { supersede } : {};
+	const withdrawal = {
+		...(isSignal(supersede) ? { supersede } : {}),
+		...(approval === "speaker" ? { speakerOnly: true as const } : {}),
+	};
 	if (
 		!copy ||
 		typeof copy !== "object" ||
@@ -125,7 +130,12 @@ export function joinApprovers(
 	if (!lookup) return withoutApprovers(answer, tool);
 	const join = (action: Described): Judged | Promise<Judged> => {
 		if (action === STOPPED || action === undefined) return action;
-		const { action: text, copy, supersede } = described(action, tool);
+		const {
+			action: text,
+			copy,
+			supersede,
+			speakerOnly,
+		} = described(action, tool);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
 		let named:
@@ -149,6 +159,7 @@ export function joinApprovers(
 				action: text,
 				...(copy ? { copy } : {}),
 				...(supersede ? { supersede } : {}),
+				...(speakerOnly ? { speakerOnly } : {}),
 				...(named ? { approvers: named } : {}),
 			};
 		}
@@ -159,6 +170,7 @@ export function joinApprovers(
 					action: text,
 					...(copy ? { copy } : {}),
 					...(supersede ? { supersede } : {}),
+					...(speakerOnly ? { speakerOnly } : {}),
 					...(approvers ? { approvers } : {}),
 				};
 			},

package/src/core/services.ts

@@ -1,3 +1,4 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
@@ -12,7 +13,7 @@ import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
 import type { IdentityLinks } from "./identity/identity-links.ts";
 import type { IdentityService } from "./identity/identity-service.ts";
-import type { ThinkingSetting } from "./models.ts";
+import type { ThinkingLevel, ThinkingSetting } from "./models.ts";
 import type {
 	DelegationJob,
 	DelegationOutcome,
@@ -91,6 +92,12 @@ export const BACKGROUND_TURNS: ServiceKey<BackgroundTurns> =
 export const DELEGATION: ServiceKey<Delegator> = serviceKey<Delegator>(
 	"roundtable.delegation",
 );
+/**
+ * Worker sessions on the host's models: a fresh, unsaved Pi session that has only the tools a
+ * plugin gives it. Provided by the `worker-sessions` plugin.
+ */
+export const WORKER_SESSIONS: ServiceKey<WorkerSessions> =
+	serviceKey<WorkerSessions>("roundtable.worker-sessions");
 /**
  * The remembered facts of each speaker. Provided by the `memory` plugin, an addon: read it with
  * `find` when your plugin works without memory, and with `get` when it cannot.
@@ -267,6 +274,42 @@ export interface Delegator {
 	idle(): Promise<void>;
 }
 
+/** One task for a worker session. */
+export interface WorkerSessionRequest {
+	/** What the worker is asked to do, as its one prompt. */
+	task: string;
+	/** Aborting it stops the worker; `run` then rejects. */
+	signal: AbortSignal;
+	/** Appended to the worker's system prompt: its role, its rules, and any instructions it should follow. */
+	prompt: string;
+	/** Extensions that register the worker's tools with `pi.registerTool`. */
+	extensions: readonly ExtensionFactory[];
+	/** The only tools active in the session. The session has no built-in tool, skill, context file or other extension. */
+	toolNames: readonly string[];
+	/** `<provider>/<id>`; default: the host's delegation model. */
+	model?: string;
+	/** Default: the host's delegation thinking level. */
+	thinking?: ThinkingLevel;
+	/** Why an aborted run stopped, as the rejection's message; default "the worker ran out of time". */
+	aborted?: string;
+}
+
+/**
+ * Runs one task in a fresh, unsaved Pi session on the host's model login and returns the worker's
+ * final answer. The session is disposed of either way. It has no access to the conversation, the
+ * owner's memory or the agents' tools: it can do only what `toolNames` lets it, and the tools a
+ * plugin registers for it are that plugin's to bound.
+ */
+export interface WorkerSessions {
+	/** The model and thinking level a request without its own uses: the host's `delegation` settings. */
+	readonly delegation: {
+		readonly model: string;
+		readonly thinking: ThinkingLevel;
+	};
+	/** Rejects with an `AgentRunError` when the worker ends without an answer. */
+	run(request: WorkerSessionRequest): Promise<string>;
+}
+
 /** Remembered facts, each speaker's own; every agent shares the memory of whoever is speaking. */
 export interface MemoryStore {
 	/** One speaker's memory; it never reads or changes another's. */

package/src/core/testing/surface-contract-support.ts

@@ -95,6 +95,7 @@ export async function answeredOnlyByThem(
 	other: SurfaceContractAnswerer | undefined,
 	visibility: "private" | "shared",
 	approvers?: readonly string[],
+	speakerOnly = false,
 ): Promise<void> {
 	const { surface, channel, answer } = running.subject;
 	const prompts = surface.prompts?.(
@@ -114,7 +115,12 @@ export async function answeredOnlyByThem(
 			speakerOf(running.subject).tier,
 			undefined,
 			undefined,
-			approvers ? { approvers } : undefined,
+			approvers || speakerOnly
+				? {
+						...(approvers ? { approvers } : {}),
+						...(speakerOnly ? { speakerOnly } : {}),
+					}
+				: undefined,
 		)
 		.then((value) => {
 			settled = value;