@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.0

package/src/profiles/loader.ts

@@ -0,0 +1,325 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type {
+	LoadedProfile,
+	ProfileCatalog,
+	ProfileDefinition,
+	ProfileDiagnostic,
+	ProfileSource,
+	ResolvedProfile,
+} from "./types.js";
+
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_PROFILE_BYTES = 256 * 1024;
+const PROFILE_CONFIG_FILE = "config.json";
+const PROFILE_INSTRUCTIONS_FILE = "instructions.md";
+const MAX_INSTRUCTIONS_CHARACTERS = 64 * 1024;
+const ALLOWED_KEYS = new Set([
+	"version",
+	"name",
+	"description",
+	"model",
+	"thinkingLevel",
+	"sessionPersistence",
+	"invocation",
+	"tools",
+	"skills",
+	"instructions",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringArray(value: unknown, maxItems: number): value is string[] {
+	return Array.isArray(value) && value.length <= maxItems
+		&& value.every((item) => typeof item === "string" && item.trim().length > 0 && item.length <= 4096);
+}
+
+function parseProfile(value: unknown, expectedName: string): ProfileDefinition {
+	if (!isRecord(value)) throw new Error("profile must be a JSON object");
+	const unknownKeys = Object.keys(value).filter((key) => !ALLOWED_KEYS.has(key));
+	if (unknownKeys.length > 0) throw new Error(`unknown fields: ${unknownKeys.join(", ")}`);
+	if (value.version !== 1) throw new Error("version must be 1");
+	if (typeof value.name !== "string" || !PROFILE_NAME.test(value.name)) {
+		throw new Error("name must be 1-64 characters using letters, numbers, dot, underscore, or hyphen");
+	}
+	if (!stringArray(value.tools, 128) || value.tools.length === 0) throw new Error("tools must be a non-empty string array with at most 128 entries");
+	if (value.skills !== undefined && !stringArray(value.skills, 128)) throw new Error("skills must be a string array with at most 128 entries");
+	if (value.sessionPersistence !== undefined && value.sessionPersistence !== "ephemeral" && value.sessionPersistence !== "persistent") {
+		throw new Error("sessionPersistence must be 'ephemeral' or 'persistent'");
+	}
+	if (value.invocation !== undefined && value.invocation !== "both" && value.invocation !== "manual") {
+		throw new Error("invocation must be 'both' or 'manual'");
+	}
+	for (const key of ["description", "model", "thinkingLevel", "instructions"] as const) {
+		if (value[key] !== undefined && (typeof value[key] !== "string" || value[key].trim().length === 0)) {
+			throw new Error(`${key} must be a non-empty string`);
+		}
+	}
+	if (typeof value.description === "string" && value.description.length > 1024) throw new Error("description exceeds 1024 characters");
+	if (typeof value.model === "string" && value.model.length > 512) throw new Error("model exceeds 512 characters");
+	if (typeof value.thinkingLevel === "string" && value.thinkingLevel.length > 128) throw new Error("thinkingLevel exceeds 128 characters");
+	if (typeof value.instructions === "string" && value.instructions.length > MAX_INSTRUCTIONS_CHARACTERS) throw new Error(`instructions exceeds ${MAX_INSTRUCTIONS_CHARACTERS} characters`);
+	if (expectedName !== value.name) throw new Error(`name '${value.name}' must match profile entry '${expectedName}'`);
+	return {
+		version: 1,
+		name: value.name,
+		tools: [...new Set(value.tools)],
+		...(value.invocation === "both" || value.invocation === "manual" ? { invocation: value.invocation } : {}),
+		...(typeof value.description === "string" ? { description: value.description } : {}),
+		...(typeof value.model === "string" ? { model: value.model } : {}),
+		...(typeof value.thinkingLevel === "string" ? { thinkingLevel: value.thinkingLevel } : {}),
+		...(value.sessionPersistence === "ephemeral" || value.sessionPersistence === "persistent"
+			? { sessionPersistence: value.sessionPersistence }
+			: {}),
+		...(Array.isArray(value.skills) ? { skills: [...new Set(value.skills as string[])] } : {}),
+		...(typeof value.instructions === "string" ? { instructions: value.instructions } : {}),
+	};
+}
+
+function readInstructions(file: string): string | undefined {
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(file);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	if (!stat.isFile()) throw new Error("instructions.md must be a regular file");
+	// Bound the read while allowing multi-byte UTF-8 instructions.
+	if (stat.size > MAX_INSTRUCTIONS_CHARACTERS * 4) throw new Error("instructions.md exceeds maximum byte size");
+	const instructions = fs.readFileSync(file, "utf8");
+	if (!instructions.trim()) throw new Error("instructions.md must be a non-empty string");
+	if (instructions.length > MAX_INSTRUCTIONS_CHARACTERS) throw new Error(`instructions.md exceeds ${MAX_INSTRUCTIONS_CHARACTERS} characters`);
+	return instructions;
+}
+
+interface ProfileCandidate {
+	name: string;
+	configPath: string;
+	instructionsPath?: string;
+}
+
+interface LoadedProfileDirectory {
+	profiles: Map<string, LoadedProfile>;
+	invalidNames: Set<string>;
+}
+
+function loadDirectory(directory: string, source: ProfileSource, diagnostics: ProfileDiagnostic[]): LoadedProfileDirectory {
+	const profiles = new Map<string, LoadedProfile>();
+	const invalidNames = new Set<string>();
+	let entryNames: string[];
+	try {
+		entryNames = fs.readdirSync(directory).sort();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { profiles, invalidNames };
+		diagnostics.push({ path: directory, message: String(error) });
+		return { profiles, invalidNames };
+	}
+
+	const candidates = new Map<string, ProfileCandidate[]>();
+	for (const entryName of entryNames) {
+		const entryPath = path.join(directory, entryName);
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(entryPath);
+		} catch (error) {
+			diagnostics.push({ path: entryPath, message: error instanceof Error ? error.message : String(error) });
+			continue;
+		}
+		let candidate: ProfileCandidate | undefined;
+		if (stat.isFile() && entryName.endsWith(".json")) {
+			candidate = { name: path.basename(entryName, ".json"), configPath: entryPath };
+		} else if (stat.isDirectory()) {
+			candidate = {
+				name: entryName,
+				configPath: path.join(entryPath, PROFILE_CONFIG_FILE),
+				instructionsPath: path.join(entryPath, PROFILE_INSTRUCTIONS_FILE),
+			};
+		}
+		if (!candidate) continue;
+		const entries = candidates.get(candidate.name) ?? [];
+		entries.push(candidate);
+		candidates.set(candidate.name, entries);
+	}
+
+	for (const [name, matches] of candidates) {
+		if (!PROFILE_NAME.test(name)) {
+			invalidNames.add(name);
+			diagnostics.push({ path: matches[0]!.configPath, message: "profile entry name must be 1-64 characters using letters, numbers, dot, underscore, or hyphen" });
+			continue;
+		}
+		if (matches.length > 1) {
+			invalidNames.add(name);
+			diagnostics.push({ path: directory, message: `duplicate profile '${name}' is defined as both a JSON file and a directory` });
+			continue;
+		}
+
+		const candidate = matches[0]!;
+		let parsed: ProfileDefinition;
+		let diagnosticPath = candidate.configPath;
+		try {
+			const stat = fs.statSync(candidate.configPath);
+			if (!stat.isFile()) throw new Error(`${path.basename(candidate.configPath)} must be a regular file`);
+			if (stat.size > MAX_PROFILE_BYTES) throw new Error(`profile exceeds ${MAX_PROFILE_BYTES} bytes`);
+			parsed = parseProfile(JSON.parse(fs.readFileSync(candidate.configPath, "utf8")) as unknown, name);
+			if (candidate.instructionsPath) {
+				diagnosticPath = candidate.instructionsPath;
+				const instructions = readInstructions(candidate.instructionsPath);
+				if (instructions !== undefined) parsed.instructions = instructions;
+			}
+		} catch (error) {
+			invalidNames.add(name);
+			diagnostics.push({ path: diagnosticPath, message: error instanceof Error ? error.message : String(error) });
+			continue;
+		}
+
+		profiles.set(parsed.name, {
+			...parsed,
+			source,
+			sourcePath: candidate.configPath,
+		});
+	}
+	return { profiles, invalidNames };
+}
+
+export function globalProfilesDir(): string {
+	return path.join(getAgentDir(), "subagent", "profiles");
+}
+
+export function projectProfilesDir(cwd: string): string {
+	return path.join(cwd, CONFIG_DIR_NAME, "subagent", "profiles");
+}
+
+function ancestorDirectories(cwd: string): string[] {
+	const directories: string[] = [];
+	let current = path.resolve(cwd);
+	while (true) {
+		directories.push(current);
+		const parent = path.dirname(current);
+		if (parent === current) return directories;
+		current = parent;
+	}
+}
+
+export function loadProfiles(cwd: string, includeProject: boolean): ProfileCatalog {
+	const diagnostics: ProfileDiagnostic[] = [];
+	const global = loadDirectory(globalProfilesDir(), "global", diagnostics);
+	const profiles = global.profiles;
+	if (includeProject) {
+		for (const directory of ancestorDirectories(cwd).reverse()) {
+			const project = loadDirectory(projectProfilesDir(directory), "project", diagnostics);
+			for (const name of project.invalidNames) profiles.delete(name);
+			for (const [name, profile] of project.profiles) profiles.set(name, profile);
+		}
+	}
+	return { profiles, diagnostics };
+}
+
+function expandHome(value: string): string {
+	return value === "~" ? os.homedir() : value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+
+function skillCandidate(candidate: string): string | undefined {
+	try {
+		const stat = fs.statSync(candidate);
+		if (stat.isFile()) return candidate;
+		if (stat.isDirectory()) {
+			const entry = path.join(candidate, "SKILL.md");
+			if (fs.statSync(entry).isFile()) return entry;
+		}
+	} catch {}
+	return undefined;
+}
+
+function resolveSkill(reference: string, profile: LoadedProfile, cwd: string, includeProject: boolean): string {
+	const expanded = expandHome(reference);
+	const looksLikePath = path.isAbsolute(expanded) || expanded.startsWith(".") || expanded.includes("/") || expanded.includes("\\");
+	const candidates = looksLikePath
+		? [path.resolve(path.dirname(profile.sourcePath), expanded)]
+		: [
+			path.join(getAgentDir(), "skills", expanded),
+			path.join(os.homedir(), ".agents", "skills", expanded),
+			...(includeProject ? ancestorDirectories(cwd).flatMap((directory) => [
+				path.join(directory, CONFIG_DIR_NAME, "skills", expanded),
+				path.join(directory, ".agents", "skills", expanded),
+			]) : []),
+		];
+	for (const candidate of candidates) {
+		const resolved = skillCandidate(candidate) ?? skillCandidate(`${candidate}.md`);
+		if (resolved) return path.resolve(resolved);
+	}
+	throw new Error(`Profile '${profile.name}' references unknown skill '${reference}'.`);
+}
+
+/** Discover only the selected directory profile's private skills, never sibling profiles. */
+function discoverProfileSkills(profile: LoadedProfile): string[] {
+	// Legacy profiles share a parent directory and must not scan its skills folder.
+	if (path.basename(profile.sourcePath) !== PROFILE_CONFIG_FILE
+		|| path.basename(path.dirname(profile.sourcePath)) !== profile.name) return [];
+	const root = path.join(path.dirname(profile.sourcePath), "skills");
+	const skills: string[] = [];
+	const visited = new Set<string>();
+	function visit(directory: string, isRoot: boolean): void {
+		let realPath: string;
+		try {
+			realPath = fs.realpathSync(directory);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		if (visited.has(realPath)) return;
+		visited.add(realPath);
+		const entry = skillCandidate(path.join(directory, "SKILL.md"));
+		if (entry) {
+			skills.push(entry);
+			return; // Supporting Markdown and nested assets are not separate skills.
+		}
+		for (const name of fs.readdirSync(directory).sort()) {
+			if (name.startsWith(".") || name === "node_modules") continue;
+			const file = path.join(directory, name);
+			let stat: fs.Stats;
+			try { stat = fs.statSync(file); } catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+				throw error;
+			}
+			if (stat.isDirectory()) visit(file, false);
+			else if (isRoot && stat.isFile() && name.endsWith(".md")) skills.push(file);
+		}
+	}
+	visit(root, true);
+	return skills;
+}
+
+export function resolveProfile(name: string, cwd: string, includeProject: boolean, options: { agentOnly?: boolean } = {}): ResolvedProfile {
+	const catalog = loadProfiles(cwd, includeProject);
+	const invalid = catalog.diagnostics.map((item) => `${item.path}: ${item.message}`);
+	const profile = catalog.profiles.get(name);
+	if (!profile) {
+		const available = [...catalog.profiles.values()].filter((item) => !options.agentOnly || item.invocation !== "manual").map((item) => item.name).sort().join(", ") || "(none)";
+		const suffix = !options.agentOnly && invalid.length > 0 ? ` Invalid profiles: ${invalid.join("; ")}` : "";
+		throw new Error(`Unknown Pi Subagent profile '${name}'. Available: ${available}.${suffix}`);
+	}
+	if (options.agentOnly && profile.invocation === "manual") {
+		throw new Error(`Profile '${name}' is user-invoked only. The user can start it with /sub:${name}; delegate cannot start it.`);
+	}
+	const skillPaths = [
+		...discoverProfileSkills(profile),
+		...(profile.skills ?? []).map((skill) => resolveSkill(skill, profile, cwd, includeProject)),
+	];
+	const seen = new Set<string>();
+	const resolvedSkills = skillPaths.filter((skill) => {
+		const realPath = fs.realpathSync(skill);
+		if (seen.has(realPath)) return false;
+		seen.add(realPath);
+		return true;
+	});
+	return {
+		...profile,
+		resolvedSkills,
+		resolvedExtensions: [],
+	};
+}

package/src/profiles/mcp.ts

@@ -0,0 +1,16 @@
+// MCP is ambient Pi context, not selected or validated by a Pi Subagent profile.
+export const MCP_EXTENSIONS = ["builtin:codemode", "builtin:tool-search", "builtin:mcp"] as const;
+export const MCP_DISCOVERY_TOOLS = ["codemode", "tool_search"] as const;
+const RESOURCE_TOOLS = ["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"];
+
+// Keep all MCP tools eligible for native registration/exposure, including tools
+// discovered after startup. Tool-name patterns require Pi 1.0.4 or newer.
+export const MCP_TOOL_SELECTION = [...MCP_DISCOVERY_TOOLS, "mcp__*", ...RESOURCE_TOOLS];
+
+export function isMcpTool(name: string): boolean {
+	return name.startsWith("mcp__") || RESOURCE_TOOLS.includes(name);
+}
+
+export function isMcpContextTool(name: string): boolean {
+	return isMcpTool(name) || (MCP_DISCOVERY_TOOLS as readonly string[]).includes(name);
+}

package/src/profiles/runtime.ts

@@ -0,0 +1,102 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { buildProfilesContext } from "./context.js";
+import { loadProfiles, resolveProfile } from "./loader.js";
+import { applyStartupPromptSections, bindPromptSections } from "./system-prompt.js";
+import { applyProfileTools } from "./tool-selection.js";
+import type { ResolvedProfile } from "./types.js";
+import { isMcpTool } from "./mcp.js";
+
+export class StartupProfileRuntime {
+	private active?: ResolvedProfile;
+	private startupError?: string;
+	private profilesContext = "";
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	register(): void {
+		this.pi.registerFlag("profile", {
+			description: "Pi Subagent profile name to apply at process startup",
+			type: "string",
+		});
+
+		this.pi.on("session_start", async (_event, ctx) => {
+			this.profilesContext = buildProfilesContext(loadProfiles(ctx.cwd, ctx.isProjectTrusted()));
+			const selected = this.pi.getFlag("profile");
+			if (typeof selected !== "string" || !selected.trim()) {
+				this.active = undefined;
+				this.startupError = undefined;
+				ctx.ui.setStatus("subagent-profile", undefined);
+				return;
+			}
+			try {
+				this.active = resolveProfile(selected.trim(), ctx.cwd, ctx.isProjectTrusted());
+				await this.apply(this.active, ctx);
+				this.startupError = undefined;
+				ctx.ui.setStatus("subagent-profile", `profile:${this.active.name}`);
+			} catch (error) {
+				this.active = undefined;
+				this.startupError = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(this.startupError, "error");
+				if (!ctx.hasUI) console.error(`Pi Subagent profile error: ${this.startupError}`);
+			}
+		});
+
+		this.pi.on("input", (_event, ctx) => {
+			if (!this.startupError) return;
+			ctx.ui.notify(`Cannot start agent: ${this.startupError}`, "error");
+			return { action: "handled" as const };
+		});
+
+		this.pi.on("resources_discover", () => {
+			if (!this.active?.resolvedSkills.length) return;
+			return { skillPaths: this.active.resolvedSkills };
+		});
+
+		bindPromptSections(this.pi, ["subagent_profiles", "subagent_profile"], () => {
+			const sections: Record<string, string> = {};
+			applyStartupPromptSections(sections, this.active, this.profilesContext);
+			return sections;
+		});
+
+		this.pi.registerCommand("profiles", {
+			description: "List startup profiles and their source",
+			handler: async (_args, ctx) => {
+				const catalog = loadProfiles(ctx.cwd, ctx.isProjectTrusted());
+				const lines = [...catalog.profiles.values()]
+					.sort((left, right) => left.name.localeCompare(right.name))
+					.map((profile) => `${profile.name} (${profile.source}, ${profile.invocation ?? "both"})${profile.description ? ` — ${profile.description}` : ""}`);
+				const diagnostics = catalog.diagnostics.map((item) => `${item.path}: ${item.message}`);
+				ctx.ui.notify([
+					lines.length > 0 ? lines.join("\n") : "No Pi Subagent profiles configured.",
+					...(diagnostics.length > 0 ? [`Invalid profiles:\n${diagnostics.join("\n")}`] : []),
+				].join("\n\n"), diagnostics.length > 0 ? "warning" : "info");
+			},
+		});
+	}
+
+	private async apply(profile: ResolvedProfile, ctx: ExtensionContext): Promise<void> {
+		const allTools = new Set(this.pi.getAllTools().map((tool) => tool.name));
+		const unknownTools = profile.tools.filter((tool) => !isMcpTool(tool) && !allTools.has(tool));
+		if (unknownTools.length > 0) throw new Error(`Profile '${profile.name}' references unknown tools: ${unknownTools.join(", ")}.`);
+
+		if (profile.model) {
+			const separator = profile.model.indexOf("/");
+			if (separator <= 0 || separator === profile.model.length - 1) {
+				throw new Error(`Profile '${profile.name}' model must use provider/model format.`);
+			}
+			const model = ctx.modelRegistry.find(profile.model.slice(0, separator), profile.model.slice(separator + 1));
+			if (!model) throw new Error(`Profile '${profile.name}' model '${profile.model}' is unavailable.`);
+			if (!(await this.pi.setModel(model))) throw new Error(`Profile '${profile.name}' model '${profile.model}' has no usable credentials.`);
+		}
+
+		applyProfileTools(this.pi, profile.name, profile.tools);
+		if (profile.thinkingLevel) {
+			this.pi.setThinkingLevel(profile.thinkingLevel as ThinkingLevel);
+			const effective = this.pi.getThinkingLevel();
+			if (effective !== profile.thinkingLevel) {
+				ctx.ui.notify(`Profile '${profile.name}' requested thinking '${profile.thinkingLevel}'; Pi selected '${effective}'.`, "warning");
+			}
+		}
+	}
+}

package/src/profiles/system-prompt.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ResolvedProfile } from "./types.js";
+
+/** Talk uses Pi's user-input path, so idle deliveries share normal prompt assembly. */
+export function bindPromptSections(pi: ExtensionAPI, keys: readonly string[], getSections: () => Record<string, string>): void {
+	pi.on("before_agent_start", (event) => {
+		const sections = getSections();
+		for (const key of keys) {
+			if (sections[key]) event.systemPromptOptions.sections[key] = sections[key]!;
+			else delete event.systemPromptOptions.sections[key];
+		}
+	});
+}
+
+export const SUB_PROTOCOL = `## Pi Subagent Sub protocol
+You are an isolated Sub Pi working with a Main Pi. You have not received the Main's conversation and must not read Pi session files. Use talk whenever you need information from the Main or need to deliver work. Each talk sends one message to the Main and ends the current turn. Remain available after delivery. The Main alone decides whether to respond, request more work, or close this Sub session. Never close the session yourself.`;
+
+export function applySubPromptSections(sections: Record<string, string>, profile: ResolvedProfile): void {
+	sections.subagent_sub_protocol = SUB_PROTOCOL;
+	if (profile.instructions) sections.subagent_profile = `## Pi Subagent profile: ${profile.name}\n${profile.instructions}`;
+	else delete sections.subagent_profile;
+}
+
+export function applyStartupPromptSections(
+	sections: Record<string, string>,
+	profile: ResolvedProfile | undefined,
+	profilesContext: string,
+): void {
+	if (profilesContext) sections.subagent_profiles = profilesContext;
+	else delete sections.subagent_profiles;
+	if (profile?.instructions) sections.subagent_profile = `## Active Pi Subagent profile: ${profile.name}\n${profile.instructions}`;
+	else delete sections.subagent_profile;
+}

package/src/profiles/tool-selection.ts

@@ -0,0 +1,21 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isMcpTool, isMcpContextTool } from "./mcp.js";
+
+/** Select the model-facing tool set; profiles do not install execution guards. */
+export function applyProfileTools(pi: ExtensionAPI, profileName: string, tools: readonly string[]): void {
+	// Leave MCP visibility and discovery helpers as Pi configured them. Explicit
+	// MCP names in a profile neither restrict servers nor delay Sub readiness.
+	const selected = tools.filter((name) => !isMcpTool(name));
+	const ambient = pi.getActiveTools().filter(isMcpContextTool);
+	const available = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
+	const unavailable = selected.filter((name) => !available.has(name) || available.get(name)?.exposure === "hidden");
+	if (unavailable.length > 0) {
+		throw new Error(`Profile '${profileName}' references unavailable tools: ${unavailable.join(", ")}.`);
+	}
+	pi.setActiveTools([...new Set([...selected, ...ambient])]);
+	const active = new Set(pi.getActiveTools());
+	const missing = selected.filter((name) => !active.has(name));
+	if (missing.length > 0) {
+		throw new Error(`Profile '${profileName}' could not activate tools: ${missing.join(", ")}.`);
+	}
+}

package/src/profiles/tool-sources.ts

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ResolvedProfile } from "./types.js";
+import { isMcpTool, MCP_EXTENSIONS } from "./mcp.js";
+
+const NATIVE_TOOLS = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+const SUPPORTED_BUILTIN_EXTENSIONS = new Set<string>(MCP_EXTENSIONS);
+
+interface ToolSource {
+	name: string;
+	sourceInfo: {
+		path: string;
+		source: string;
+	};
+}
+
+export function resolveToolExtensions(profile: ResolvedProfile, tools: ToolSource[]): ResolvedProfile {
+	const available = new Map(tools.map((tool) => [tool.name, tool]));
+	const extensionPaths = new Set<string>();
+	for (const name of profile.tools) {
+		// Native MCP connects asynchronously; do not require its tools in Main yet.
+		if (isMcpTool(name)) continue;
+		const tool = available.get(name);
+		if (!tool) throw new Error(`Profile '${profile.name}' references unavailable tool '${name}'.`);
+		const sourcePath = tool.sourceInfo.path;
+		if (tool.sourceInfo.source === "builtin") {
+			if (NATIVE_TOOLS.has(name) && (sourcePath === `builtin:${name}` || sourcePath === `<builtin:${name}>`)) continue;
+			if (!SUPPORTED_BUILTIN_EXTENSIONS.has(sourcePath)) {
+				throw new Error(`Profile '${profile.name}' tool '${name}' requires unsupported isolated built-in extension '${sourcePath}'.`);
+			}
+			extensionPaths.add(sourcePath);
+			continue;
+		}
+		if (tool.sourceInfo.source === "sdk" || !sourcePath || sourcePath.startsWith("<")) {
+			throw new Error(`Profile '${profile.name}' tool '${name}' cannot be loaded in an isolated Sub process.`);
+		}
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(sourcePath);
+		} catch {
+			throw new Error(`Profile '${profile.name}' tool '${name}' extension is missing: ${sourcePath}.`);
+		}
+		if (!stat.isFile() && !stat.isDirectory()) {
+			throw new Error(`Profile '${profile.name}' tool '${name}' has an unsupported extension path: ${sourcePath}.`);
+		}
+		extensionPaths.add(path.resolve(sourcePath));
+	}
+	return { ...profile, resolvedExtensions: [...extensionPaths] };
+}

package/src/profiles/types.ts

@@ -0,0 +1,37 @@
+export type ProfileSource = "global" | "project";
+export type SessionPersistence = "ephemeral" | "persistent";
+export type ProfileInvocation = "both" | "manual";
+
+export interface ProfileDefinition {
+	version: 1;
+	name: string;
+	description?: string;
+	model?: string;
+	thinkingLevel?: string;
+	sessionPersistence?: SessionPersistence;
+	/** Manual profiles are started by user commands, not model delegation. */
+	invocation?: ProfileInvocation;
+	tools: string[];
+	skills?: string[];
+	instructions?: string;
+}
+
+export interface LoadedProfile extends ProfileDefinition {
+	source: ProfileSource;
+	sourcePath: string;
+}
+
+export interface ResolvedProfile extends LoadedProfile {
+	resolvedSkills: string[];
+	resolvedExtensions: string[];
+}
+
+export interface ProfileDiagnostic {
+	path: string;
+	message: string;
+}
+
+export interface ProfileCatalog {
+	profiles: Map<string, LoadedProfile>;
+	diagnostics: ProfileDiagnostic[];
+}