pi-profile-switch 0.1.0

package/src/profile-resolver.ts

@@ -0,0 +1,247 @@
+/**
+ * ProfileResolver: turns one profile definition plus an optional runtime
+ * overlay into an immutable selection, resolved against Pi's LIVE resources.
+ *
+ * ADR-0007 semantics:
+ * - `skills` resolves to a visibility filter (see skill-selection.ts), not
+ *   to loaded resources: every skill stays loaded and user-invocable.
+ * - `mcp` resolves to a runtime server allowlist; a declared MCP intent that
+ *   cannot be satisfied (adapter absent, literal server unknown) fails the
+ *   activation before anything is applied.
+ * - `tools` resolves to an active tool set; literals the live registry does
+ *   not provide yet become `pendingTools` and are retried, because MCP and
+ *   extension tools register after session start.
+ * - `model` and `instructions` pass through unchanged; applying them is the
+ *   caller's job.
+ *
+ * The resolver is a pure function: same inputs, same selection, no I/O.
+ */
+
+import { isGlob, matchesReference, suggestNames } from "./name-matching.ts";
+import type { ProfileModel, ProfileSource, ResolvedProfile } from "./profile-catalog.ts";
+import type { RuntimeOverlay } from "./runtime-state-store.ts";
+
+/** The live resource view a resolution runs against. */
+export interface LiveResources {
+	skills: Array<{ name: string; filePath: string }>;
+	toolNames: string[];
+	/** MCP adapter state: presence plus discovered server names. */
+	mcp: { adapterPresent: boolean; servers: string[] };
+}
+
+/** The skill references of a visibility filter: literals/globs, or `"all"`
+ *  when the profile declares none and only the overlay narrows (nothing is
+ *  hidden by omission). An empty array means "no skill is visible". */
+export type SkillRefs = string[] | "all";
+
+/** The skill visibility filter handed to the prompt builder each turn. */
+export interface SkillsFilter {
+	refs: SkillRefs;
+	/** Skill name references removed from the visible set. */
+	disabled: string[];
+}
+
+/** A literal reference no live resource provides, with near-name hints. */
+export interface UnresolvedRef {
+	reference: string;
+	suggestions: string[];
+}
+
+export interface SelectionWarnings {
+	skillsUnresolved: UnresolvedRef[];
+	skillsUnmatched: string[];
+	mcpUnmatched: string[];
+	toolsUnmatched: string[];
+}
+
+export interface ResolvedSelection {
+	name: string;
+	source: ProfileSource;
+	instructions?: string;
+	model?: ProfileModel;
+	/** Undefined means no visibility filtering (the whole loaded set). */
+	skills?: SkillsFilter;
+	/** Runtime MCP allowlist; undefined means publish nothing. */
+	mcp?: string[];
+	/** Active tool names; undefined means leave Pi's active set untouched. */
+	tools?: string[];
+	/** Tool literals the live registry does not provide yet. */
+	pendingTools: string[];
+	warnings: SelectionWarnings;
+}
+
+export class SelectionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SelectionError";
+	}
+}
+
+function resolveSkills(
+	declared: string[] | undefined,
+	disabled: string[],
+	live: LiveResources["skills"],
+): { filter?: SkillsFilter; warning: Pick<SelectionWarnings, "skillsUnresolved" | "skillsUnmatched"> } {
+	const refs = declared ?? [];
+	const warning = { skillsUnresolved: [] as UnresolvedRef[], skillsUnmatched: [] as string[] };
+	if (declared === undefined) {
+		// The profile declares nothing; an overlay may still hide skills.
+		return { ...(disabled.length > 0 ? { filter: { refs: "all" as const, disabled } } : {}), warning };
+	}
+	for (const ref of refs) {
+		const hits = live.filter((skill) => matchesReference(ref, skill.name));
+		if (hits.length === 0) {
+			if (isGlob(ref)) warning.skillsUnmatched.push(ref);
+			else warning.skillsUnresolved.push({ reference: ref, suggestions: suggestNames(ref, live.map((s) => s.name)) });
+		}
+	}
+	return { filter: { refs, disabled }, warning };
+}
+
+function resolveMcp(
+	declared: string[] | undefined,
+	disabled: string[],
+	live: LiveResources["mcp"],
+	profileName: string,
+): { servers?: string[]; warning: Pick<SelectionWarnings, "mcpUnmatched"> } {
+	const warning = { mcpUnmatched: [] as string[] };
+	if (declared === undefined) {
+		// No declared intent: only an overlay narrowing publishes an allowlist.
+		if (disabled.length === 0 || !live.adapterPresent) return { warning };
+		return { servers: live.servers.filter((server) => !disabled.includes(server)), warning };
+	}
+	if (!live.adapterPresent) {
+		throw new SelectionError(
+			`profile "${profileName}" declares MCP servers but pi-mcp-adapter is not active in this session — ` +
+				`install the adapter or remove the "mcp" declaration`,
+		);
+	}
+	const selected: string[] = [];
+	const missing: string[] = [];
+	for (const ref of declared) {
+		const hits = live.servers.filter((server) => matchesReference(ref, server));
+		if (hits.length > 0) {
+			selected.push(...hits);
+			continue;
+		}
+		if (isGlob(ref)) warning.mcpUnmatched.push(ref);
+		else missing.push(ref);
+	}
+	if (missing.length > 0) {
+		throw new SelectionError(
+			`profile "${profileName}": unknown MCP server ${missing.map((name) => JSON.stringify(name)).join(", ")} — ` +
+				`adapter discovered: [${live.servers.join(", ")}]`,
+		);
+	}
+	const servers = [...new Set(selected)].filter((server) => !disabled.includes(server));
+	return { servers, warning };
+}
+
+function resolveTools(
+	refs: string[] | undefined,
+	live: LiveResources["toolNames"],
+): {
+	tools?: string[];
+	pendingTools: string[];
+	warning: Pick<SelectionWarnings, "toolsUnmatched">;
+} {
+	const warning = { toolsUnmatched: [] as string[] };
+	if (refs === undefined) return { pendingTools: [], warning };
+	const selected: string[] = [];
+	const pending: string[] = [];
+	for (const ref of refs) {
+		const hits = live.filter((name) => matchesReference(ref, name));
+		if (hits.length > 0) {
+			selected.push(...hits);
+			continue;
+		}
+		if (isGlob(ref)) warning.toolsUnmatched.push(ref);
+		else pending.push(ref);
+	}
+	return { tools: [...new Set([...selected, ...pending])], pendingTools: [...new Set(pending)], warning };
+}
+
+/** Resolves one profile (plus overlay) against the live resources. Throws
+ *  SelectionError when the profile's declared MCP intent cannot be
+ *  satisfied; the caller applies nothing in that case.
+ *
+ *  `suppressTools` drops the profile's tool selection entirely, so a
+ *  CLI-declared `--tools`/`--exclude-tools` keeps owning the active set
+ *  (the preference table in docs/product/prd.md). */
+export function resolveSelection(input: {
+	profile: ResolvedProfile;
+	overlay?: RuntimeOverlay;
+	live: LiveResources;
+	suppressTools?: boolean;
+}): ResolvedSelection {
+	const { profile, overlay, live } = input;
+	const definition = profile.definition;
+
+	const skills = resolveSkills(definition.skills, overlay?.disabledSkills ?? [], live.skills);
+	const mcp = resolveMcp(definition.mcp, overlay?.disabledMcp ?? [], live.mcp, profile.name);
+	const tools = input.suppressTools === true
+		? { pendingTools: [], warning: { toolsUnmatched: [] } }
+		: resolveTools(overlay?.tools ?? definition.tools, live.toolNames);
+
+	const selection: ResolvedSelection = {
+		name: profile.name,
+		source: profile.source,
+		pendingTools: tools.pendingTools,
+		warnings: {
+			...skills.warning,
+			...mcp.warning,
+			...tools.warning,
+		},
+	};
+	if (definition.instructions !== undefined && definition.instructions.length > 0) {
+		selection.instructions = definition.instructions;
+	}
+	if (definition.model !== undefined) {
+		selection.model = definition.model;
+	}
+	if (skills.filter !== undefined) {
+		selection.skills = skills.filter;
+	}
+	if (mcp.servers !== undefined) {
+		selection.mcp = mcp.servers;
+	}
+	if (tools.tools !== undefined) {
+		selection.tools = tools.tools;
+	}
+	return selection;
+}
+
+/** User-facing warning lines for one resolved selection. */
+export function formatSelectionWarnings(selection: ResolvedSelection): string[] {
+	const lines: string[] = [];
+	for (const unresolved of selection.warnings.skillsUnresolved) {
+		const hint =
+			unresolved.suggestions.length > 0
+				? ` — did you mean: ${unresolved.suggestions.map((name) => JSON.stringify(name)).join(", ")}?`
+				: "";
+		lines.push(
+			`profile "${selection.name}": skill ${JSON.stringify(unresolved.reference)} is not loaded in this session${hint}`,
+		);
+	}
+	if (selection.warnings.skillsUnmatched.length > 0) {
+		lines.push(
+			`profile "${selection.name}": skill glob(s) ${selection.warnings.skillsUnmatched.map((ref) => JSON.stringify(ref)).join(", ")} matched nothing`,
+		);
+	}
+	if (selection.warnings.mcpUnmatched.length > 0) {
+		lines.push(
+			`profile "${selection.name}": MCP glob(s) ${selection.warnings.mcpUnmatched.map((ref) => JSON.stringify(ref)).join(", ")} matched nothing`,
+		);
+	}
+	if (selection.warnings.toolsUnmatched.length > 0) {
+		lines.push(
+			`profile "${selection.name}": tool glob(s) ${selection.warnings.toolsUnmatched.map((ref) => JSON.stringify(ref)).join(", ")} matched nothing`,
+		);
+	}
+	if (selection.pendingTools.length > 0) {
+		lines.push(
+			`profile "${selection.name}": tool(s) ${selection.pendingTools.map((name) => JSON.stringify(name)).join(", ")} are not registered yet — applied when they appear`,
+		);
+	}
+	return lines;
+}

package/src/runtime-state-store.ts

@@ -0,0 +1,105 @@
+/**
+ * RuntimeStateStore: reads and writes a `pi-profile-state.json` runtime
+ * state file.
+ *
+ * Constructed with the directory holding the state file: the real agent dir
+ * for global state, the project's `.pi` dir for project state (project
+ * state is only touched when Pi reports the project trusted).
+ *
+ * `activeProfile` is the saved selection applied on the next start;
+ * `overlay` is the temporary narrowing of the active profile, written by
+ * `/profile customize` and deleted by `/profile reset`.
+ *
+ * A missing or malformed state file is not an error on read — it simply
+ * means "fall back to the default profile". Unexpected I/O errors
+ * propagate. A state file written by an older pi-profile-switch is read with its
+ * retired fields (`lastVerifiedProfile`, `overlay.disabledExtensions`)
+ * ignored; the next write drops them.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { isRecord, readJsonFile } from "./json-file.ts";
+import type { ProfileSource } from "./profile-catalog.ts";
+
+/** The state directory for one profile's source scope: the project's `.pi`
+ *  dir for project profiles, the agent dir otherwise (built-in `default` is
+ *  treated as global). */
+export function stateDirFor(source: ProfileSource, dirs: { agentDir: string; cwd: string }): string {
+	return source === "project" ? path.join(dirs.cwd, ".pi") : dirs.agentDir;
+}
+
+export interface RuntimeState {
+	activeProfile?: string;
+	overlay?: RuntimeOverlay;
+}
+
+export interface RuntimeOverlay {
+	disabledSkills?: string[];
+	disabledMcp?: string[];
+	/** Replaces the profile's tool references when set. */
+	tools?: string[];
+}
+
+function parseOverlay(value: unknown): RuntimeOverlay | undefined {
+	if (!isRecord(value)) return undefined;
+	const overlay: RuntimeOverlay = {};
+	for (const key of ["disabledSkills", "disabledMcp", "tools"] as const) {
+		const list = value[key];
+		if (Array.isArray(list) && list.every((entry) => typeof entry === "string")) {
+			overlay[key] = list;
+		}
+	}
+	return Object.keys(overlay).length > 0 ? overlay : undefined;
+}
+
+export class RuntimeStateStore {
+	readonly #statePath: string;
+
+	/** @param stateDir Directory holding `pi-profile-state.json` (agent dir or
+	 *  project `.pi` dir). */
+	constructor(stateDir: string) {
+		this.#statePath = path.join(stateDir, "pi-profile-state.json");
+	}
+
+	async read(): Promise<RuntimeState> {
+		const result = await readJsonFile(this.#statePath);
+		if (!result.ok || !isRecord(result.value)) return {};
+		const state: RuntimeState = {};
+		if (typeof result.value.activeProfile === "string") {
+			state.activeProfile = result.value.activeProfile;
+		}
+		const overlay = parseOverlay(result.value.overlay);
+		if (overlay !== undefined) {
+			state.overlay = overlay;
+		}
+		return state;
+	}
+
+	async write(state: RuntimeState): Promise<void> {
+		await mkdir(path.dirname(this.#statePath), { recursive: true });
+		const document: RuntimeState = {};
+		if (state.activeProfile !== undefined) document.activeProfile = state.activeProfile;
+		if (state.overlay !== undefined) document.overlay = state.overlay;
+		await writeFile(this.#statePath, `${JSON.stringify(document, null, 2)}\n`);
+	}
+
+	/** Read-modify-write merge. A field set to `undefined` is deleted; absent
+	 *  fields keep their stored value. Used by the switch/customize paths so
+	 *  one concern (selection, overlay) never clobbers another. */
+	async update(patch: Partial<RuntimeState>): Promise<RuntimeState> {
+		const current = await this.read();
+		const next: RuntimeState = { ...current };
+		if ("activeProfile" in patch) {
+			if (patch.activeProfile === undefined) delete next.activeProfile;
+			else next.activeProfile = patch.activeProfile;
+		}
+		if ("overlay" in patch) {
+			if (patch.overlay === undefined) delete next.overlay;
+			else next.overlay = patch.overlay;
+		}
+		await this.write(next);
+		return next;
+	}
+}

package/src/skill-selection.ts

@@ -0,0 +1,81 @@
+/**
+ * SkillSelection: the skills visibility filter (ADR-0007).
+ *
+ * A profile's `skills` references do not load or unload anything. Pi loads
+ * every installed skill; `/skill:name` stays available to the user for all
+ * of them. What the profile controls is what the MODEL sees: the
+ * `<available_skills>` section of the system prompt.
+ *
+ * The filter recomputes that section with Pi's own exported formatter over
+ * the profile's selection and replaces it inside the chained system prompt.
+ * Because the original section was produced by the same formatter from the
+ * same skill array (`BuildSystemPromptOptions.skills`), the recomputation is
+ * byte-identical; when it is not found the turn proceeds unfiltered and the
+ * caller reports a warning.
+ */
+
+import { formatSkillsForPrompt, type BuildSystemPromptOptions, type Skill } from "@earendil-works/pi-coding-agent";
+
+import { matchesReference } from "./name-matching.ts";
+import type { SkillsFilter } from "./profile-resolver.ts";
+
+export type SkillsFilterOutcome =
+	/** The prompt's skills section was replaced with the filtered one. */
+	| "filtered"
+	/** No filter applies (default profile without an overlay). */
+	| "no-filter"
+	/** Neither `read` nor `bash` is active, so Pi emitted no skills section. */
+	| "no-read-tool"
+	/** The expected section is absent from the prompt; left unfiltered. */
+	| "section-missing";
+
+/** The skills the model may see. `undefined` means "no filtering". */
+export function visibleSkills(skills: Skill[], filter: SkillsFilter | undefined): Skill[] | undefined {
+	if (filter === undefined) return undefined;
+	const visible = new Set(visibleSkillNames(skills, filter) ?? []);
+	return skills.filter((skill) => visible.has(skill.name));
+}
+
+/** The visible skill names, for status reporting and prompt filtering.
+ *  `undefined` means "no filtering". */
+export function visibleSkillNames(
+	all: Array<{ name: string }>,
+	filter: SkillsFilter | undefined,
+): string[] | undefined {
+	if (filter === undefined) return undefined;
+	const refs = filter.refs;
+	const base = refs === "all" ? all : all.filter((skill) => refs.some((ref) => matchesReference(ref, skill.name)));
+	return base
+		.filter((skill) => !filter.disabled.some((ref) => matchesReference(ref, skill.name)))
+		.map((skill) => skill.name);
+}
+
+/** Replaces the system prompt's skills section with the filtered one. */
+export function applySkillsFilter(input: {
+	systemPrompt: string;
+	options: BuildSystemPromptOptions;
+	filter: SkillsFilter | undefined;
+}): { systemPrompt: string; outcome: SkillsFilterOutcome } {
+	const { systemPrompt, options, filter } = input;
+	if (filter === undefined) {
+		return { systemPrompt, outcome: "no-filter" };
+	}
+	// Pi emits the section only when a skill-reading tool is active; without
+	// one there is nothing to replace.
+	const fileReadTool = (["read", "bash"] as const).find((tool) => options.selectedTools?.includes(tool));
+	if (fileReadTool === undefined) {
+		return { systemPrompt, outcome: "no-read-tool" };
+	}
+	const all = options.skills ?? [];
+	const original = formatSkillsForPrompt(all, fileReadTool);
+	if (original.length === 0 || !systemPrompt.includes(original)) {
+		return { systemPrompt, outcome: "section-missing" };
+	}
+	const filtered = formatSkillsForPrompt(visibleSkills(all, filter) ?? [], fileReadTool);
+	return { systemPrompt: systemPrompt.replace(original, filtered), outcome: "filtered" };
+}
+
+/** The per-profile instructions block appended after the (filtered) prompt. */
+export function formatInstructionsBlock(profile: string, instructions: string): string {
+	return `\n\n<profile_instructions name="${profile}">\n${instructions}\n</profile_instructions>`;
+}

package/src/startup-selection.ts

@@ -0,0 +1,147 @@
+/**
+ * StartupSelection: how a session decides which profile to activate.
+ *
+ * - `--profile <name>` (a flag this extension registers) is an explicit,
+ *   one-run selection: it is never written back to runtime state.
+ * - Without the flag the saved selection applies: the trusted project's
+ *   state wins over the global state, then the built-in `default`.
+ * - A saved selection that no longer resolves falls back to `default` with
+ *   a warning — restore is a convenience, not a commitment. An explicit
+ *   flag value never falls back: an unknown name is a loud error.
+ *
+ * Explicit CLI declarations (`--model`, `--thinking`, `--tools`,
+ * `--exclude-tools`) outrank the profile's matching declaration. They are
+ * detected by re-parsing this process's argv with Pi's own exported parser,
+ * so the aliases and value forms stay Pi's rather than a hand-rolled copy.
+ */
+
+import { parseArgs } from "@earendil-works/pi-coding-agent";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { DEFAULT_PROFILE_NAME, ProfileCatalog } from "./profile-catalog.ts";
+import { RuntimeStateStore } from "./runtime-state-store.ts";
+
+/** Which settings the user stated on the command line this run. */
+export interface ExplicitDeclarations {
+	model: boolean;
+	thinking: boolean;
+	tools: boolean;
+}
+
+export const PROFILE_FLAG = "profile";
+
+/** Registers the `--profile <name>` CLI flag. Pi has no flag of that name;
+ *  unknown flags are collected by its parser and validated against flags
+ *  registered by loaded extensions. */
+export function registerProfileFlag(pi: ExtensionAPI): void {
+	pi.registerFlag(PROFILE_FLAG, {
+		type: "string",
+		description: "pi-profile-switch: activate a profile for this run (not saved)",
+	});
+}
+
+/** The `--profile` value, when the user passed one. */
+export function readProfileFlag(pi: ExtensionAPI): string | undefined {
+	const value = pi.getFlag(PROFILE_FLAG);
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Detects explicit CLI declarations by re-parsing argv with Pi's parser. */
+export function detectExplicitDeclarations(argv: string[]): ExplicitDeclarations {
+	const parsed = parseArgs(argv);
+	return {
+		model: parsed.model !== undefined,
+		thinking: parsed.thinking !== undefined,
+		tools: parsed.tools !== undefined || parsed.excludeTools !== undefined,
+	};
+}
+
+export interface StartupProfile {
+	name: string;
+	/** Non-fatal notices (e.g. a saved profile that no longer exists). */
+	warnings: string[];
+}
+
+async function exists(filePath: string): Promise<boolean> {
+	try {
+		await stat(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Files the retired extension registry lived in; they are no longer read
+ *  (ADR-0007), and a leftover file is called out once per startup. */
+async function legacyRegistryWarnings(input: {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+}): Promise<string[]> {
+	const candidates = [path.join(input.agentDir, "resources.json")];
+	if (input.projectTrusted) candidates.push(path.join(input.cwd, ".pi", "resources.json"));
+	const warnings: string[] = [];
+	for (const filePath of candidates) {
+		if (await exists(filePath)) {
+			warnings.push(
+				`${filePath} is no longer read (ADR-0007): extensions load natively in every profile — manage them with pi install`,
+			);
+		}
+	}
+	return warnings;
+}
+
+/** Resolves the profile name for this session: explicit flag → trusted
+ *  project state → global state → default. Never writes state. */
+export async function resolveStartupProfile(input: {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+	requested?: string;
+}): Promise<StartupProfile> {
+	const catalog = await ProfileCatalog.load(input.agentDir, {
+		projectDir: input.projectTrusted ? input.cwd : undefined,
+	});
+	const warnings: string[] = [
+		...catalog.warnings,
+		...(await legacyRegistryWarnings(input)),
+	];
+
+	if (input.requested !== undefined) {
+		if (catalog.resolve(input.requested) === undefined) {
+			throw new UnknownProfileError(input.requested, catalog.list().map((profile) => profile.name));
+		}
+		return { name: input.requested, warnings };
+	}
+
+	let saved: string | undefined;
+	if (input.projectTrusted) {
+		saved = (await new RuntimeStateStore(path.join(input.cwd, ".pi")).read()).activeProfile;
+	}
+	saved ??= (await new RuntimeStateStore(input.agentDir).read()).activeProfile;
+
+	if (saved === undefined || saved === DEFAULT_PROFILE_NAME) {
+		return { name: DEFAULT_PROFILE_NAME, warnings };
+	}
+	if (catalog.resolve(saved) === undefined) {
+		warnings.push(
+			`saved profile ${JSON.stringify(saved)} no longer exists — starting with "${DEFAULT_PROFILE_NAME}"; ` +
+				`available: [${catalog.list().map((profile) => profile.name).join(", ")}]`,
+		);
+		return { name: DEFAULT_PROFILE_NAME, warnings };
+	}
+	return { name: saved, warnings };
+}
+
+export class UnknownProfileError extends Error {
+	readonly requested: string;
+
+	constructor(requested: string, available: string[]) {
+		super(`unknown profile ${JSON.stringify(requested)} — available: [${available.join(", ")}]`);
+		this.name = "UnknownProfileError";
+		this.requested = requested;
+	}
+}

package/src/switching/activate-profile.ts

@@ -0,0 +1,113 @@
+/**
+ * SwitchProfile: the in-session activation orchestrator (ADR-0007).
+ *
+ * There is no reload and no generated-settings rewrite. Activating a profile
+ * means: resolve it against Pi's live resources, apply the runtime parts
+ * (model, tools, MCP allowlist), and remember the choice. Skills and
+ * instructions need no action here — they are applied by the next
+ * `before_agent_start` from the returned selection.
+ *
+ * Flow:
+ *   1. load the catalog (project entries only when Pi reports the project
+ *      trusted) and resolve the name — unknown names fail with candidates
+ *   2. resolve the selection against the live resources; a declared MCP
+ *      intent that cannot be satisfied fails here
+ *   3. validate the model preset (exists, has auth) — still nothing applied
+ *   4. persist the choice to the target profile's scope state file
+ *   5. apply model/thinking/tools/MCP; a failure reports loudly
+ *
+ * Startup activation passes `persist: false` (the flag selection must not
+ * overwrite the saved one) and `overlay: null` (a stored overlay never
+ * outlives its runtime).
+ */
+
+import { ProfileCatalog } from "../profile-catalog.ts";
+import { decidePreset, type SessionChoices } from "../model-selection.ts";
+import { resolveSelection, type LiveResources, type ResolvedSelection } from "../profile-resolver.ts";
+import type { ExplicitDeclarations } from "../startup-selection.ts";
+import { RuntimeStateStore, stateDirFor, type RuntimeOverlay } from "../runtime-state-store.ts";
+import { applySelection, validateSelection, type ApplySurface } from "./apply-profile.ts";
+
+export class ActivationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ActivationError";
+	}
+}
+
+export interface ActivationDeps {
+	/** The user's real agent dir (e.g. ~/.pi/agent). */
+	agentDir: string;
+	/** The project working directory. */
+	cwd: string;
+	/** Pi's trust decision for `cwd` (`ctx.isProjectTrusted()`). */
+	projectTrusted: boolean;
+	/** The live resource view loaded by the caller. */
+	live: LiveResources;
+	/** The narrow Pi surface the selection is applied to. */
+	surface: ApplySurface;
+	/** Inputs for the model-preset precedence decision (decided after the
+	 *  profile resolves, since it depends on the declared model). */
+	presetInputs: { explicit: ExplicitDeclarations; session: SessionChoices; force: boolean };
+}
+
+export interface ActivationResult {
+	selection: ResolvedSelection;
+	warnings: string[];
+}
+
+/** Resolves a profile against the live resources without applying it.
+ *  Throws ActivationError for unknown names and SelectionError for declared
+ *  MCP intents that cannot be satisfied. A CLI-declared
+ *  `--tools`/`--exclude-tools` suppresses the profile's tool selection
+ *  unless the user made an explicit `/profile use` choice. */
+export async function resolveProfileSelection(
+	name: string,
+	deps: Pick<ActivationDeps, "agentDir" | "cwd" | "projectTrusted" | "live" | "presetInputs">,
+	overlay?: RuntimeOverlay,
+): Promise<{ selection: ResolvedSelection; warnings: string[] }> {
+	const catalog = await ProfileCatalog.load(deps.agentDir, {
+		projectDir: deps.projectTrusted ? deps.cwd : undefined,
+	});
+	const profile = catalog.resolve(name);
+	if (profile === undefined) {
+		throw new ActivationError(
+			`unknown profile ${JSON.stringify(name)} — available: [${catalog.list().map((entry) => entry.name).join(", ")}]`,
+		);
+	}
+	const suppressTools = !deps.presetInputs.force && deps.presetInputs.explicit.tools;
+	const selection = resolveSelection({ profile, overlay, live: deps.live, suppressTools });
+	return { selection, warnings: [...catalog.warnings] };
+}
+
+/** Activates a profile: resolve, validate, optionally persist, apply. */
+export async function activateProfile(
+	name: string,
+	deps: ActivationDeps,
+	options?: { overlay?: RuntimeOverlay | null; persist?: boolean },
+): Promise<ActivationResult> {
+	const overlay = options?.overlay ?? undefined;
+	const { selection, warnings } = await resolveProfileSelection(name, deps, overlay);
+	const preset = decidePreset({ model: selection.model, ...deps.presetInputs });
+
+	// Validate before touching anything: the model preset is the only
+	// fallible runtime step.
+	const validationError = validateSelection(selection, deps.surface, preset);
+	if (validationError !== undefined) {
+		throw new ActivationError(validationError);
+	}
+
+	if (options?.persist !== false) {
+		await new RuntimeStateStore(stateDirFor(selection.source, deps)).update({
+			activeProfile: selection.name,
+			overlay: overlay ?? undefined,
+		});
+	}
+
+	const result = await applySelection({ selection, surface: deps.surface, preset });
+	if (!result.applied) {
+		throw new ActivationError(result.error ?? `profile "${name}" could not be applied`);
+	}
+
+	return { selection, warnings };
+}