@agimon-ai/po-team 0.0.0-alpha.0

package/dist/agentDiscovery-ZQlFkKvB.mjs

@@ -0,0 +1,1529 @@
+import "./atomicJson-D2t0CDh9.mjs";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadHarnessState, loadMajorModesConfig, resolvePackageConfigurations } from "@agimon-ai/po-config";
+import * as os from "node:os";
+import { piAgentDirectory } from "@agimon-ai/po-core/piSettings";
+//#region src/schemas/team/packageConfig.ts
+const PO_TEAM_PACKAGE = "@agimon-ai/po-team";
+const TEAM_CONFIG_KEYS = ["models", "excludeTools"];
+const TEAM_MODEL_KEYS = ["model", "thinking"];
+const THINKING_VALUES = /* @__PURE__ */ new Set([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertKnownKeys(value, keys, location) {
+	const unsupported = Object.keys(value).filter((key) => !keys.includes(key));
+	if (unsupported.length > 0) throw new Error(`${location} has unsupported field(s): ${unsupported.join(", ")}`);
+}
+/** Validate and normalize one Team-owned package configuration mapping. */
+function parseTeamPackageConfig(value, location) {
+	if (!isRecord(value)) throw new Error(`${location} must be a mapping`);
+	assertKnownKeys(value, TEAM_CONFIG_KEYS, location);
+	const hasModels = Object.hasOwn(value, "models");
+	const hasExcludeTools = Object.hasOwn(value, "excludeTools");
+	if (!hasModels && !hasExcludeTools) throw new Error(`${location} must define models or excludeTools`);
+	let models;
+	if (hasModels) {
+		if (!Array.isArray(value.models) || value.models.length === 0) throw new Error(`${location}.models must be a non-empty array`);
+		models = value.models.map((entry, index) => {
+			const entryLocation = `${location}.models[${index}]`;
+			if (!isRecord(entry)) throw new Error(`${entryLocation} must be a mapping`);
+			assertKnownKeys(entry, TEAM_MODEL_KEYS, entryLocation);
+			if (typeof entry.model !== "string" || !entry.model.trim()) throw new Error(`${entryLocation}.model must be a non-empty string`);
+			if (entry.thinking !== void 0 && (typeof entry.thinking !== "string" || !THINKING_VALUES.has(entry.thinking))) throw new Error(`${entryLocation}.thinking must be one of: ${[...THINKING_VALUES].join(", ")}`);
+			return {
+				model: entry.model.trim(),
+				...entry.thinking ? { thinking: entry.thinking } : {}
+			};
+		});
+	}
+	let excludeTools;
+	if (hasExcludeTools) {
+		if (!Array.isArray(value.excludeTools) || value.excludeTools.length === 0) throw new Error(`${location}.excludeTools must be a non-empty array`);
+		excludeTools = [...new Set(value.excludeTools.map((entry, index) => {
+			if (typeof entry !== "string" || !entry.trim()) throw new Error(`${location}.excludeTools[${index}] must be a non-empty string`);
+			return entry.trim();
+		}))];
+	}
+	return {
+		...models ? { models } : {},
+		...excludeTools ? { excludeTools } : {}
+	};
+}
+/** Merge Team configurations contributed by selected layers in selection order. */
+function mergeTeamPackageConfigurations(entries) {
+	let models;
+	const excludeTools = /* @__PURE__ */ new Set();
+	let hasExcludeTools = false;
+	for (const entry of entries) {
+		const location = `Package "${entry.specifier}" config in layer "${entry.layer}" of .po/modes.yaml`;
+		const next = parseTeamPackageConfig(entry.config, location);
+		if (next.models) models = next.models.map((model) => ({ ...model }));
+		if (next.excludeTools) {
+			hasExcludeTools = true;
+			for (const tool of next.excludeTools) excludeTools.add(tool);
+		}
+	}
+	if (!models && !hasExcludeTools) return void 0;
+	return {
+		...models ? { models } : {},
+		...hasExcludeTools ? { excludeTools: [...excludeTools] } : {}
+	};
+}
+//#endregion
+//#region src/services/agentFrontmatter/index.ts
+/**
+* Parsing the YAML frontmatter block at the head of an agent or chain file.
+*
+* This is a deliberately partial YAML reader, not a call into a YAML library.
+* The block is read once, keys are kept as raw strings, and each consumer
+* interprets its own key. That is what lets an unrecognised key survive a
+* read/write round-trip: the loader copies it into `extraFields` verbatim
+* instead of losing it to a typed parse.
+*
+* DESIGN PATTERNS:
+* - Nested and folded blocks are captured as one string with newlines intact.
+*   A consumer that wants structure re-parses that string with a real YAML
+*   parser, so structural validation stays with the field that needs it
+* - Common leading whitespace is stripped from a block, so a serializer can
+*   re-indent to its own level without the original indent accumulating
+*
+* AVOID:
+* - Growing this into a general YAML parser; hand a block value to `yaml`
+*   instead
+* - Interpreting field semantics here
+*/
+const OPENING_FENCE = "---";
+/** Length of the opening `---` fence, before the newline that follows it. */
+const FENCE_LENGTH = 3;
+/** Length of the fence plus its trailing newline, used to slice past it. */
+const FENCE_WITH_NEWLINE_LENGTH = 4;
+/** Offset of the first frontmatter character: past `---\n`. */
+const FRONTMATTER_START_INDEX = FENCE_WITH_NEWLINE_LENGTH;
+/** The closing fence as it appears mid-document, searched from after the opener. */
+const CLOSING_FENCE = "\n---";
+const FOLDED_BLOCK_INDICATORS = /* @__PURE__ */ new Set([">", ">-"]);
+/** Escape regex metacharacters so a literal string can be used in a RegExp. */
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Fold a YAML folded block scalar.
+*
+* Folding joins lines with a space, except that more-indented lines and blank
+* separators are structural in YAML and must survive as real newlines. Getting
+* this wrong silently reflows a user's prompt, so the two cases are tracked
+* explicitly rather than approximated by a global replace.
+*/
+function foldBlock(block) {
+	let folded = "";
+	let hasContent = false;
+	let previousIsMoreIndented = false;
+	let blankLines = 0;
+	for (const line of block.split("\n")) {
+		const current = line.trimEnd();
+		if (current.trim() === "") {
+			if (hasContent) blankLines++;
+			continue;
+		}
+		const currentIsMoreIndented = current.length > current.trimStart().length;
+		if (hasContent) {
+			if (blankLines > 0) folded += "\n".repeat(blankLines + (previousIsMoreIndented || currentIsMoreIndented ? 1 : 0));
+			else folded += previousIsMoreIndented || currentIsMoreIndented ? "\n" : " ";
+		}
+		folded += current;
+		hasContent = true;
+		previousIsMoreIndented = currentIsMoreIndented;
+		blankLines = 0;
+	}
+	return folded.trim();
+}
+/**
+* Read a list-valued field written either comma-separated or as a block list.
+*
+* Only a leading `- ` marker is treated as a list bullet. A bare hyphen inside
+* a value is left alone, so hyphenated names like `context-builder` survive.
+*/
+function parseFrontmatterList(raw) {
+	if (raw === void 0) return void 0;
+	return raw.split("\n").flatMap((line) => {
+		const value = line.trim();
+		return (value.match(/^-\s+(.+)$/)?.[1] ?? value).split(",");
+	}).map((value) => value.trim()).filter(Boolean);
+}
+/** Strip the block's common leading whitespace so it can be re-indented later. */
+function dedentBlock(blockLines) {
+	const rawBlock = blockLines.join("\n");
+	const prefix = rawBlock.match(/^[ \t]+(?=\S)/m)?.[0] ?? "";
+	if (!prefix) return rawBlock;
+	return rawBlock.replace(new RegExp(`^${escapeRegex(prefix)}`, "gm"), "").replace(/^\n/, "");
+}
+/**
+* Split a file into its frontmatter map and its body.
+*
+* A file with no opening fence, or with an unterminated one, is treated as all
+* body with empty frontmatter. The loader then rejects it for want of a name,
+* which is the right outcome: a malformed file should be skipped, not crash a
+* directory sweep.
+*/
+function parseFrontmatter(content) {
+	const frontmatter = {};
+	const normalized = content.replace(/\r\n/g, "\n");
+	if (!normalized.startsWith(OPENING_FENCE)) return {
+		frontmatter,
+		body: normalized
+	};
+	const endIndex = normalized.indexOf(CLOSING_FENCE, FENCE_LENGTH);
+	if (endIndex === -1) return {
+		frontmatter,
+		body: normalized
+	};
+	const frontmatterBlock = normalized.slice(FRONTMATTER_START_INDEX, endIndex);
+	const body = normalized.slice(endIndex + FENCE_WITH_NEWLINE_LENGTH).trim();
+	let currentKey = null;
+	let currentBlockLines = null;
+	let currentIndent = null;
+	let currentFolded = false;
+	const flushBlock = () => {
+		if (currentKey === null || currentBlockLines === null) return;
+		const stripped = dedentBlock(currentBlockLines);
+		frontmatter[currentKey] = currentFolded ? foldBlock(stripped) : stripped;
+		currentKey = null;
+		currentBlockLines = null;
+		currentIndent = null;
+		currentFolded = false;
+	};
+	for (const line of frontmatterBlock.split("\n")) {
+		const indent = line.search(/\S|$/);
+		const trimmed = line.trim();
+		if (currentKey !== null && currentBlockLines !== null && (indent > (currentIndent ?? 0) || currentFolded && trimmed === "")) {
+			currentBlockLines.push(line);
+			continue;
+		}
+		flushBlock();
+		const match = line.match(/^([\w-]+):\s*(.*)$/);
+		if (!match) continue;
+		const key = match[1] ?? "";
+		const rawValue = (match[2] ?? "").trim();
+		const isQuoted = rawValue.startsWith("\"") && rawValue.endsWith("\"") || rawValue.startsWith("'") && rawValue.endsWith("'");
+		const value = isQuoted ? rawValue.slice(1, -1) : rawValue;
+		const isFolded = !isQuoted && FOLDED_BLOCK_INDICATORS.has(rawValue);
+		if (value === "" || isFolded) {
+			currentKey = key;
+			currentBlockLines = [];
+			currentIndent = indent;
+			currentFolded = isFolded;
+		} else frontmatter[key] = value;
+	}
+	flushBlock();
+	return {
+		frontmatter,
+		body
+	};
+}
+//#endregion
+//#region src/services/configDir/index.ts
+/**
+* Locating the coding agent's config directory.
+*
+* The directory is normally `.pi`, but a rebranded build of the coding agent
+* can rename it, so the real name is discovered from the running installation
+* rather than assumed. Discovery order runs from most to least authoritative:
+* the loaded module's own export, then an explicitly configured package root,
+* then a walk upward from the process entry point, then the default.
+*
+* DESIGN PATTERNS:
+* - Resolution is a pure function of its inputs; the process-wide convenience
+*   wrapper is a separate, memoized entry point
+* - Every discovery step is best-effort. A detached runner must still start
+*   when package metadata is unreadable, so failures fall through to the default
+*
+* PERFORMANCE:
+* `getConfigDirName` is memoized because the uncached path walks from the entry
+* point to the filesystem root, reading and parsing a package.json per level.
+* Callers join it into paths, so it was previously re-walked per path built.
+*
+* AVOID:
+* - Hardcoding `.pi` at a call site
+* - Calling the uncached resolver on a hot path
+*/
+const DEFAULT_CONFIG_DIR_NAME = ".pi";
+const PI_CODING_AGENT_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+/** Overrides the upward package walk when the installation root is known. */
+const PI_CODING_AGENT_PACKAGE_ROOT_ENV = "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT";
+function validConfigDirName(value) {
+	return typeof value === "string" && value.trim() ? value : void 0;
+}
+/** Read the config dir name from a directory, if it is the coding agent's package root. */
+function readConfigDirNameFromPackageRoot(packageRoot) {
+	if (!packageRoot) return void 0;
+	try {
+		const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
+		if (typeof manifest !== "object" || manifest === null) return void 0;
+		const record = manifest;
+		if (record.name !== PI_CODING_AGENT_PACKAGE_NAME) return void 0;
+		return validConfigDirName((typeof record.piConfig === "object" && record.piConfig !== null ? record.piConfig : void 0)?.configDir);
+	} catch {
+		return;
+	}
+}
+function resolveConfigDirNameFromPackageJson(entryPoint = process.argv[1], packageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV]) {
+	const configuredRootValue = readConfigDirNameFromPackageRoot(packageRoot);
+	if (configuredRootValue) return configuredRootValue;
+	if (!entryPoint) return void 0;
+	try {
+		let dir = path.dirname(fs.realpathSync(entryPoint));
+		while (dir !== path.dirname(dir)) {
+			const value = readConfigDirNameFromPackageRoot(dir);
+			if (value) return value;
+			dir = path.dirname(dir);
+		}
+	} catch {}
+}
+/**
+* Resolve the config directory name from explicit inputs.
+*
+* Pure with respect to its arguments, which is what makes it testable; the
+* process-wide answer comes from `getConfigDirName`.
+*/
+function resolveConfigDirName(codingAgentModule, entryPoint, packageRoot) {
+	return (codingAgentModule && typeof codingAgentModule === "object" ? validConfigDirName(codingAgentModule.CONFIG_DIR_NAME) : void 0) ?? resolveConfigDirNameFromPackageJson(entryPoint, packageRoot) ?? DEFAULT_CONFIG_DIR_NAME;
+}
+let memoizedConfigDirName;
+/** The config directory name for this process. Resolved once, then reused. */
+function getConfigDirName(environment = process.env) {
+	if (environment !== process.env) return resolveConfigDirName(void 0, process.argv[1], environment["PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT"] ?? "");
+	memoizedConfigDirName ??= resolveConfigDirName();
+	return memoizedConfigDirName;
+}
+/** The project-local config directory, for example `<projectRoot>/.pi`. */
+function getProjectConfigDir(projectRoot, environment = process.env) {
+	return path.join(projectRoot, getConfigDirName(environment));
+}
+/** Read a JSON settings file as an object, retaining strict path-specific errors. */
+function readSettingsFileStrict(filePath) {
+	if (!fs.existsSync(filePath)) return {};
+	let raw;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read settings file '${filePath}': ${message}`, { cause: error });
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse settings file '${filePath}': ${message}`, { cause: error });
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Settings file '${filePath}' must contain a JSON object.`);
+	return parsed;
+}
+/** The user-level agent directory Po runs with, from Po's own resolver. */
+function getAgentDir(environment = process.env) {
+	return piAgentDirectory(environment, environment.HOME ?? os.homedir());
+}
+//#endregion
+//#region src/services/agentProjectRoot/index.ts
+/**
+* Locating the project root that agent configuration hangs off.
+*
+* A project root is any ancestor of the working directory that carries a config
+* directory or a legacy `.agents` directory. There can be several: a package
+* inside a monorepo and the monorepo itself both qualify. Which one wins is a
+* setting, because both answers are legitimate. Teams that keep one shared set
+* of agents at the repository root want `git-root`, teams that give each package
+* its own want `nearest`, and neither can be inferred from the tree alone.
+*
+* DESIGN PATTERNS:
+* - Candidates are collected once, nearest first, then a policy picks from them.
+*   Separating collection from policy is what lets `git-root` be answered
+*   without a second walk
+* - Path derivation goes through `shared/configDir.ts`, so a rebranded build
+*   that renames its config directory needs no change here
+*
+* AVOID:
+* - Hardcoding the config directory name; it is discovered, not assumed
+* - Treating the nearest candidate as the project root without reading the
+*   setting first
+*/
+const SETTINGS_FILE_NAME = "settings.json";
+const GIT_DIR_NAME$1 = ".git";
+/**
+* Bare `.agents`. Two roles, one name: under a project root it is the legacy
+* location that predates the config directory, under the home directory it is
+* the current one. Both are read.
+*/
+const DOT_AGENTS_DIR_NAME = ".agents";
+/** Agents inside a config directory, project-level or user-level. */
+const AGENTS_DIR_NAME = "agents";
+const SUBAGENTS_SETTINGS_KEY$1 = "subagents";
+const PROJECT_ROOT_RESOLUTION_KEY = "projectRootResolution";
+/** Stable cache identity for equivalent absolute, relative, and symlinked cwd spellings. */
+function canonicalizeDiscoveryCwd(cwd) {
+	const resolved = path.resolve(cwd);
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+/** Whether a path exists and is a directory. Any failure reads as "no". */
+function isDirectory$1(dirPath) {
+	try {
+		return fs.statSync(dirPath).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** True when `dir` carries either marker that makes it a project root. */
+function isProjectRootCandidate(dir, environment = process.env) {
+	return isDirectory$1(getProjectConfigDir(dir, environment)) || isDirectory$1(path.join(dir, DOT_AGENTS_DIR_NAME));
+}
+/** Every project root above `cwd`, nearest first. */
+function findProjectRootCandidates(cwd, environment = process.env) {
+	const roots = [];
+	let currentDir = cwd;
+	while (true) {
+		if (isProjectRootCandidate(currentDir, environment)) roots.push(currentDir);
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return roots;
+		currentDir = parentDir;
+	}
+}
+/**
+* Nearest ancestor containing `.git`.
+*
+* Existence is enough: a worktree or submodule has a `.git` file rather than a
+* directory, and both are real repository roots.
+*/
+function findNearestGitRoot(cwd) {
+	let currentDir = cwd;
+	while (true) {
+		if (fs.existsSync(path.join(currentDir, GIT_DIR_NAME$1))) return currentDir;
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+/**
+* Read a candidate's declared resolution policy.
+*
+* Deliberately throws on an unrecognised value rather than falling back: a typo
+* here silently changes which agents the whole session sees.
+*/
+function readProjectRootResolution(projectRoot, environment = process.env) {
+	const settingsPath = path.join(getProjectConfigDir(projectRoot, environment), SETTINGS_FILE_NAME);
+	if (!fs.existsSync(settingsPath)) return void 0;
+	const subagents = readSettingsFileStrict(settingsPath)[SUBAGENTS_SETTINGS_KEY$1];
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return void 0;
+	const value = subagents[PROJECT_ROOT_RESOLUTION_KEY];
+	if (value === void 0) return void 0;
+	if (value === "nearest" || value === "git-root") return value;
+	throw new Error(`Subagent settings in '${settingsPath}' have invalid '${PROJECT_ROOT_RESOLUTION_KEY}'; expected 'nearest' or 'git-root'.`);
+}
+/**
+* The project root to use, honouring the resolution policy.
+*
+* The policy is read from the nearest candidate first so a package can opt out
+* of its monorepo's shared agents, and from the git root second so a repository
+* can claim its packages without editing each one.
+*/
+function findConfiguredProjectRoot(cwd, environment = process.env) {
+	const candidates = findProjectRootCandidates(cwd, environment);
+	const nearestRoot = candidates[0];
+	if (!nearestRoot) return null;
+	const nearestMode = readProjectRootResolution(nearestRoot, environment);
+	if (nearestMode === "nearest") return nearestRoot;
+	const gitRoot = findNearestGitRoot(cwd);
+	const gitProjectRoot = gitRoot ? candidates.find((candidate) => path.resolve(candidate) === path.resolve(gitRoot)) : void 0;
+	if (gitProjectRoot && (nearestMode === "git-root" || readProjectRootResolution(gitProjectRoot, environment) === "git-root")) return gitProjectRoot;
+	return nearestRoot;
+}
+/**
+* User-level agent directories, in load order.
+*
+* Two locations, not one: agents used to live in the config directory and now
+* also live in `~/.agents`, and both are still read so an existing setup keeps
+* working after the move. Returned unfiltered because the caller reads each
+* directory anyway and a missing one costs nothing.
+*/
+function userAgentDirs(environment = process.env) {
+	return [path.join(getAgentDir(environment), AGENTS_DIR_NAME), path.join(environment.HOME ?? os.homedir(), DOT_AGENTS_DIR_NAME)];
+}
+/** The user-level settings file. Always resolvable, unlike the project one. */
+function getUserAgentSettingsPath(environment = process.env) {
+	return path.join(getAgentDir(environment), SETTINGS_FILE_NAME);
+}
+/** The project settings file, or null when `cwd` sits under no project root. */
+function getProjectAgentSettingsPath(cwd, environment = process.env) {
+	const projectRoot = findConfiguredProjectRoot(cwd, environment);
+	return projectRoot ? path.join(getProjectConfigDir(projectRoot, environment), SETTINGS_FILE_NAME) : null;
+}
+/**
+* Project agent directories for `cwd`.
+*
+* `readDirs` holds only directories that exist, so discovery never stats twice,
+* and lists the legacy location first so a project mid-migration still resolves.
+* `preferredDir` is where a newly created agent should be written, and is
+* returned whether or not it exists yet.
+*/
+function resolveNearestProjectAgentDirs(cwd, environment = process.env) {
+	const projectRoot = findConfiguredProjectRoot(cwd, environment);
+	if (!projectRoot) return {
+		readDirs: [],
+		preferredDir: null
+	};
+	const legacyDir = path.join(projectRoot, DOT_AGENTS_DIR_NAME);
+	const preferredDir = path.join(getProjectConfigDir(projectRoot, environment), AGENTS_DIR_NAME);
+	const readDirs = [];
+	if (isDirectory$1(legacyDir)) readDirs.push(legacyDir);
+	if (isDirectory$1(preferredDir)) readDirs.push(preferredDir);
+	return {
+		readDirs,
+		preferredDir
+	};
+}
+//#endregion
+//#region src/services/agentMemory/index.ts
+/** Tools that let an agent append to its own memory file. */
+const WRITE_TOOLS = /* @__PURE__ */ new Set([
+	"edit",
+	"write",
+	"bash"
+]);
+function unquoteFrontmatterValue(value) {
+	const trimmed = value.trim();
+	if (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1);
+	return trimmed;
+}
+function parseMemoryScope(value) {
+	return value === "project" || value === "user" ? value : void 0;
+}
+function parseMemoryBoolean(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+}
+function parsePositiveInteger(value) {
+	if (value === void 0) return void 0;
+	const parsed = Number(value);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+/** Split a `memory` frontmatter block into key/value pairs, either spelling. */
+function readMemoryEntries(raw) {
+	const entries = /* @__PURE__ */ new Map();
+	const inlineObject = raw.trim().match(/^\{(.*)\}$/s);
+	const parts = inlineObject?.[1] !== void 0 ? inlineObject[1].split(",") : raw.split("\n");
+	for (const part of parts) {
+		const match = part.trim().match(/^([\w-]+)\s*:\s*(.*)$/);
+		if (!match?.[1] || match[2] === void 0) continue;
+		entries.set(match[1], unquoteFrontmatterValue(match[2]));
+	}
+	return entries;
+}
+/**
+* Parse a `memory` frontmatter block, or undefined when it declares nothing.
+*
+* Accepts both the inline `{ scope: project }` form and the indented block form,
+* because agent files in the wild use each.
+*/
+function parseMemoryFrontmatter(raw) {
+	if (!raw) return void 0;
+	const entries = readMemoryEntries(raw);
+	const enabled = parseMemoryBoolean(entries.get("enabled"));
+	const scope = parseMemoryScope(entries.get("scope"));
+	const maxEntries = parsePositiveInteger(entries.get("maxEntries"));
+	if (enabled === void 0 && scope === void 0 && maxEntries === void 0) return void 0;
+	const config = {};
+	if (enabled !== void 0) config.enabled = enabled;
+	if (scope !== void 0) config.scope = scope;
+	if (maxEntries !== void 0) config.maxEntries = maxEntries;
+	return config;
+}
+/** Whether an agent can write files this run. An unset `tools` inherits the builtins. */
+function agentHasWriteTools(agent) {
+	const tools = agent.tools;
+	if (!tools) return true;
+	return tools.some((tool) => WRITE_TOOLS.has(tool));
+}
+//#endregion
+//#region src/services/agentSettings/index.ts
+const SUBAGENTS_SETTINGS_KEY = "subagents";
+const AGENT_OVERRIDES_KEY = "agentOverrides";
+/** Prefix marking a tool the child calls on an MCP server directly. */
+const MCP_DIRECT_TOOL_PREFIX = "mcp:";
+/**
+* Returned whenever there is nothing to read.
+*
+* Shared rather than freshly built per call because it is returned on the hot
+* discovery path for every session with no project settings file.
+*/
+const EMPTY_SUBAGENT_SETTINGS = { overrides: {} };
+/**
+* Which fields of a config came from its file's frontmatter.
+*
+* Keyed by the config object rather than by agent name because configs are
+* copied on write: each `apply*` pass produces new objects, and the new one
+* inherits the entry so later passes still know what the author declared.
+* A WeakMap means a discarded config's entry is collectable with it.
+*/
+const agentFrontmatterFields = /* @__PURE__ */ new WeakMap();
+/** Record which fields a freshly parsed config took from frontmatter. */
+function setAgentFrontmatterFields(agent, fields) {
+	agentFrontmatterFields.set(agent, fields);
+}
+/** True when the agent's file declared any of `fields` in its frontmatter. */
+function agentHasFrontmatterField(agent, ...fields) {
+	const frontmatterFields = agentFrontmatterFields.get(agent);
+	return frontmatterFields ? fields.some((field) => frontmatterFields.has(field)) : false;
+}
+/** Carry the frontmatter record onto a copy produced by an `apply*` pass. */
+function inheritFrontmatterFields(source, next) {
+	const frontmatterFields = agentFrontmatterFields.get(source);
+	if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
+	return next;
+}
+/** Split a flat tool list into host tools and direct MCP tools. */
+function splitToolList$1(rawTools) {
+	const mcpDirectTools = [];
+	const tools = [];
+	for (const tool of rawTools ?? []) if (tool.startsWith(MCP_DIRECT_TOOL_PREFIX)) mcpDirectTools.push(tool.slice(4));
+	else tools.push(tool);
+	return {
+		...rawTools !== void 0 ? { tools } : {},
+		...mcpDirectTools.length > 0 ? { mcpDirectTools } : {}
+	};
+}
+/** Read a settings object at `key`, or undefined when it is absent or not an object. */
+function readObjectField(source, key) {
+	const value = source[key];
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	return value;
+}
+/**
+* Parse the model-scope block.
+*
+* Lives here rather than beside the scope enforcement logic because parsing is
+* a settings concern and the agents domain may not reach into the runs domain.
+*/
+function parseModelScopeConfig(value, filePath) {
+	if (value === void 0) return void 0;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Subagent settings in '${filePath}' have invalid 'modelScope'; expected an object.`);
+	const input = value;
+	const config = {};
+	if ("enforce" in input) {
+		if (typeof input.enforce !== "boolean") throw new Error(`Subagent settings in '${filePath}' have invalid 'modelScope.enforce'; expected a boolean.`);
+		config.enforce = input.enforce;
+	}
+	if ("allow" in input) {
+		if (!Array.isArray(input.allow)) throw new Error(`Subagent settings in '${filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);
+		const allow = [];
+		for (const entry of input.allow) {
+			if (typeof entry !== "string") throw new Error(`Subagent settings in '${filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);
+			const trimmed = entry.trim();
+			if (trimmed) allow.push(trimmed);
+		}
+		if (allow.length === 0) throw new Error(`Subagent settings in '${filePath}' have invalid 'modelScope.allow'; expected a non-empty array of patterns.`);
+		config.allow = allow;
+	}
+	if (config.enforce === true && (!config.allow || config.allow.length === 0)) throw new Error(`Subagent settings in '${filePath}' set modelScope.enforce without a non-empty 'allow' list; supply allowed model patterns or disable enforcement.`);
+	return Object.keys(config).length > 0 ? config : void 0;
+}
+/**
+* Parse a string-array override field, which may also be `false` to clear it.
+*
+* Empty entries are dropped rather than rejected: trailing commas in a hand
+* edited list are common and unambiguous.
+*/
+function parseOverrideStringArrayOrFalse(value, meta) {
+	if (value === void 0) return void 0;
+	if (value === false) return false;
+	if (!Array.isArray(value)) throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`);
+	const items = [];
+	for (const item of value) {
+		if (typeof item !== "string") throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`);
+		const trimmed = item.trim();
+		if (trimmed) items.push(trimmed);
+	}
+	return items;
+}
+/**
+* Parse one entry of `subagents.agentOverrides`.
+*
+* Returns undefined for an entry that declared nothing, so an empty object in
+* the file does not register as an override and mark the agent as overridden.
+*/
+function parseBuiltinOverrideEntry(name, value, filePath) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Builtin override '${name}' in '${filePath}' must be an object.`);
+	const input = value;
+	const override = {};
+	if ("model" in input) {
+		if (typeof input.model === "string" || input.model === false) override.model = input.model;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`);
+	}
+	if ("thinking" in input) {
+		if (typeof input.thinking === "string" || input.thinking === false) override.thinking = input.thinking;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'thinking'; expected a string or false.`);
+	}
+	if ("systemPromptMode" in input) {
+		if (input.systemPromptMode === "append" || input.systemPromptMode === "replace") override.systemPromptMode = input.systemPromptMode;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPromptMode'; expected 'append' or 'replace'.`);
+	}
+	if ("inheritProjectContext" in input) {
+		if (typeof input.inheritProjectContext === "boolean") override.inheritProjectContext = input.inheritProjectContext;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritProjectContext'; expected a boolean.`);
+	}
+	if ("inheritSkills" in input) {
+		if (typeof input.inheritSkills === "boolean") override.inheritSkills = input.inheritSkills;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritSkills'; expected a boolean.`);
+	}
+	if ("defaultContext" in input) {
+		if (input.defaultContext === "fresh" || input.defaultContext === "fork" || input.defaultContext === false) override.defaultContext = input.defaultContext;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultContext'; expected 'fresh', 'fork', or false.`);
+	}
+	if ("disabled" in input) {
+		if (typeof input.disabled === "boolean") override.disabled = input.disabled;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'disabled'; expected a boolean.`);
+	}
+	if ("completionGuard" in input) {
+		if (typeof input.completionGuard === "boolean") override.completionGuard = input.completionGuard;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'completionGuard'; expected a boolean.`);
+	}
+	if ("toolBudget" in input) {
+		const toolBudget = parseToolBudgetOverride(input.toolBudget, name, filePath);
+		if (toolBudget !== void 0) override.toolBudget = toolBudget;
+	}
+	if ("systemPrompt" in input) {
+		if (typeof input.systemPrompt === "string") override.systemPrompt = input.systemPrompt;
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
+	}
+	const parseArrayField = (field) => parseOverrideStringArrayOrFalse(input[field], {
+		filePath,
+		name,
+		field
+	});
+	const fallbackModels = parseArrayField("fallbackModels");
+	if (fallbackModels !== void 0) override.fallbackModels = fallbackModels;
+	const skills = parseArrayField("skills");
+	if (skills !== void 0) override.skills = skills;
+	const tools = parseArrayField("tools");
+	if (tools !== void 0) override.tools = tools;
+	const extensions = parseArrayField("extensions");
+	if (extensions !== void 0) override.extensions = extensions;
+	const subagentOnlyExtensions = parseArrayField("subagentOnlyExtensions");
+	if (subagentOnlyExtensions !== void 0) override.subagentOnlyExtensions = subagentOnlyExtensions;
+	return Object.keys(override).length > 0 ? override : void 0;
+}
+/**
+* Parse a `toolBudget` override.
+*
+* `hard` is required by the contract, so an object without a usable one is
+* rejected here instead of producing a budget that never blocks.
+*/
+function parseToolBudgetOverride(value, name, filePath) {
+	if (value === false) return false;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'toolBudget'; expected an object or false.`);
+	const input = value;
+	if (typeof input.hard !== "number") throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'toolBudget.hard'; expected a number.`);
+	const budget = { hard: input.hard };
+	if ("soft" in input) {
+		if (typeof input.soft !== "number") throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'toolBudget.soft'; expected a number.`);
+		budget.soft = input.soft;
+	}
+	if ("block" in input) {
+		if (input.block === "*") budget.block = "*";
+		else if (Array.isArray(input.block) && input.block.every((entry) => typeof entry === "string")) budget.block = [...input.block];
+		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'toolBudget.block'; expected an array of strings or '*'.`);
+	}
+	return budget;
+}
+/** Read and validate one settings file's `subagents` block. */
+function readSubagentSettings(filePath) {
+	if (!filePath) return EMPTY_SUBAGENT_SETTINGS;
+	const subagentsObject = readObjectField(readSettingsFileStrict(filePath), SUBAGENTS_SETTINGS_KEY);
+	if (!subagentsObject) return EMPTY_SUBAGENT_SETTINGS;
+	let disableBuiltins;
+	if ("disableBuiltins" in subagentsObject) {
+		if (typeof subagentsObject.disableBuiltins === "boolean") disableBuiltins = subagentsObject.disableBuiltins;
+		else throw new Error(`Subagent settings in '${filePath}' have invalid 'disableBuiltins'; expected a boolean.`);
+	}
+	let disableThinking;
+	if ("disableThinking" in subagentsObject) {
+		if (typeof subagentsObject.disableThinking === "boolean") disableThinking = subagentsObject.disableThinking;
+		else throw new Error(`Subagent settings in '${filePath}' have invalid 'disableThinking'; expected a boolean.`);
+	}
+	let defaultModel;
+	if ("defaultModel" in subagentsObject) {
+		if (typeof subagentsObject.defaultModel === "string" && subagentsObject.defaultModel.trim()) defaultModel = subagentsObject.defaultModel.trim();
+		else throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultModel'; expected a non-empty string.`);
+	}
+	let defaultThinking;
+	if ("defaultThinking" in subagentsObject) {
+		if (typeof subagentsObject.defaultThinking === "string" && subagentsObject.defaultThinking.trim()) defaultThinking = subagentsObject.defaultThinking.trim();
+		else throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultThinking'; expected a non-empty string.`);
+	}
+	let defaultExtensions;
+	if ("defaultExtensions" in subagentsObject) {
+		const raw = subagentsObject.defaultExtensions;
+		if (!Array.isArray(raw) || raw.some((item) => typeof item !== "string" || !item.trim())) throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultExtensions'; expected an array of non-empty strings.`);
+		defaultExtensions = raw.map((item) => String(item).trim());
+	}
+	const modelScope = parseModelScopeConfig(subagentsObject.modelScope, filePath);
+	const overrides = {};
+	const agentOverrides = readObjectField(subagentsObject, AGENT_OVERRIDES_KEY);
+	if (agentOverrides) for (const [name, value] of Object.entries(agentOverrides)) {
+		const override = parseBuiltinOverrideEntry(name, value, filePath);
+		if (override) overrides[name] = override;
+	}
+	return {
+		overrides,
+		defaultModel,
+		defaultThinking,
+		defaultExtensions,
+		disableBuiltins,
+		disableThinking,
+		modelScope
+	};
+}
+/** Which settings file supplies `defaultModel`, project winning over user. */
+function resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath) {
+	if (projectSettingsPath && projectSettings.defaultModel !== void 0) return {
+		type: "subagents.defaultModel",
+		scope: "project",
+		path: projectSettingsPath,
+		model: projectSettings.defaultModel
+	};
+	return userSettings.defaultModel !== void 0 ? {
+		type: "subagents.defaultModel",
+		scope: "user",
+		path: userSettingsPath,
+		model: userSettings.defaultModel
+	} : void 0;
+}
+/**
+* Fill in the default model for agents that declared none.
+*
+* `modelSource` is recorded alongside so callers can tell an inherited model
+* from a requested one, which decides how hard model-scope enforcement bites.
+*/
+function applySubagentDefaultModel(agents, defaultModel) {
+	if (!defaultModel) return agents;
+	return agents.map((agent) => {
+		if (agent.model !== void 0) return agent;
+		return inheritFrontmatterFields(agent, {
+			...agent,
+			model: defaultModel.model,
+			modelSource: defaultModel
+		});
+	});
+}
+/** Fill in fallback models only when the agent declared no fallback policy. */
+function applySubagentDefaultFallbackModels(agents, fallbackModels) {
+	if (fallbackModels === void 0) return agents;
+	return agents.map((agent) => {
+		if (agent.fallbackModels !== void 0) return agent;
+		return inheritFrontmatterFields(agent, {
+			...agent,
+			fallbackModels: [...fallbackModels]
+		});
+	});
+}
+function resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath) {
+	if (projectSettingsPath && projectSettings.defaultThinking !== void 0) return projectSettings.defaultThinking;
+	return userSettings.defaultThinking;
+}
+function applySubagentDefaultThinking(agents, defaultThinking) {
+	if (defaultThinking === void 0) return agents;
+	return agents.map((agent) => {
+		if (agent.thinking !== void 0) return agent;
+		return inheritFrontmatterFields(agent, {
+			...agent,
+			thinking: defaultThinking
+		});
+	});
+}
+function resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath) {
+	if (projectSettingsPath && projectSettings.defaultExtensions !== void 0) return projectSettings.defaultExtensions;
+	return userSettings.defaultExtensions;
+}
+/**
+* Fill in default extensions for agents that declared none.
+*
+* The `extensionsFromDefault` flag matters when the agent is later overridden:
+* a snapshot must not record a settings default as if the builtin had declared
+* it, or removing the override would bake the default in permanently.
+*/
+function applySubagentDefaultExtensions(agents, defaultExtensions) {
+	if (defaultExtensions === void 0) return agents;
+	return agents.map((agent) => {
+		if (agent.extensions !== void 0) return agent;
+		return inheritFrontmatterFields(agent, {
+			...agent,
+			extensions: [...defaultExtensions],
+			extensionsFromDefault: true
+		});
+	});
+}
+function applySubagentDefaults(agents, defaultModel, defaultThinking, defaultExtensions, defaultFallbackModels) {
+	return applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultFallbackModels(applySubagentDefaultModel(agents, defaultModel), defaultFallbackModels), defaultThinking), defaultExtensions);
+}
+/**
+* Snapshot the fields an override may replace, so it can be undone.
+*
+* `extensions` is omitted when it came from a settings default rather than the
+* agent itself; restoring it would turn a default into a permanent value.
+*/
+function cloneOverrideBase(agent) {
+	return {
+		model: agent.model,
+		fallbackModels: agent.fallbackModels ? [...agent.fallbackModels] : void 0,
+		thinking: agent.thinking,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		defaultContext: agent.defaultContext,
+		disabled: agent.disabled,
+		systemPrompt: agent.systemPrompt,
+		skills: agent.skills ? [...agent.skills] : void 0,
+		skillPath: agent.skillPath ? [...agent.skillPath] : void 0,
+		tools: agent.tools ? [...agent.tools] : void 0,
+		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : void 0,
+		extensions: agent.extensionsFromDefault ? void 0 : agent.extensions ? [...agent.extensions] : void 0,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : void 0,
+		completionGuard: agent.completionGuard,
+		toolBudget: agent.toolBudget
+	};
+}
+/**
+* Apply an override to a custom agent, filling only unset fields.
+*
+* A custom agent has a file the user could have edited, so a settings value
+* must never contradict its frontmatter. Nothing is copied and no `override`
+* is recorded unless at least one field was actually filled, which keeps agents
+* that declared everything from being reported as overridden.
+*/
+function applyCustomAgentOverride(agent, override, meta) {
+	let next;
+	let anyFilled = false;
+	const mutable = () => {
+		next ??= { ...agent };
+		return next;
+	};
+	const fill = (field, frontmatterFields, value) => {
+		if (agentHasFrontmatterField(agent, ...frontmatterFields)) return;
+		mutable()[field] = value;
+		anyFilled = true;
+	};
+	if (override.model !== void 0 && !agentHasFrontmatterField(agent, "model")) {
+		const target = mutable();
+		target.model = override.model === false ? void 0 : override.model;
+		target.modelSource = void 0;
+		anyFilled = true;
+	}
+	if (override.fallbackModels !== void 0) fill("fallbackModels", ["fallbackModels"], override.fallbackModels === false ? void 0 : [...override.fallbackModels]);
+	if (override.thinking !== void 0) fill("thinking", ["thinking"], override.thinking === false ? void 0 : override.thinking);
+	if (override.systemPromptMode !== void 0) fill("systemPromptMode", ["systemPromptMode"], override.systemPromptMode);
+	if (override.inheritProjectContext !== void 0) fill("inheritProjectContext", ["inheritProjectContext"], override.inheritProjectContext);
+	if (override.inheritSkills !== void 0) fill("inheritSkills", ["inheritSkills"], override.inheritSkills);
+	if (override.defaultContext !== void 0) fill("defaultContext", ["defaultContext"], override.defaultContext === false ? void 0 : override.defaultContext);
+	if (override.disabled !== void 0 && agent.disabled === void 0) {
+		mutable().disabled = override.disabled;
+		anyFilled = true;
+	}
+	if (override.skills !== void 0) fill("skills", ["skill", "skills"], override.skills === false ? void 0 : [...override.skills]);
+	if (override.tools !== void 0 && !agentHasFrontmatterField(agent, "tools")) {
+		const { tools, mcpDirectTools } = splitToolList$1(override.tools === false ? [] : override.tools);
+		const target = mutable();
+		target.tools = tools;
+		target.mcpDirectTools = mcpDirectTools;
+		anyFilled = true;
+	}
+	if (override.extensions !== void 0) fill("extensions", ["extensions"], override.extensions === false ? void 0 : [...override.extensions]);
+	if (override.subagentOnlyExtensions !== void 0) fill("subagentOnlyExtensions", ["subagentOnlyExtensions"], override.subagentOnlyExtensions === false ? void 0 : [...override.subagentOnlyExtensions]);
+	if (override.completionGuard !== void 0) fill("completionGuard", ["completionGuard"], override.completionGuard);
+	if (override.toolBudget !== void 0) fill("toolBudget", ["toolBudget"], override.toolBudget === false ? void 0 : override.toolBudget);
+	if (!anyFilled || !next) return agent;
+	next.override = {
+		...meta,
+		base: cloneOverrideBase(agent)
+	};
+	return inheritFrontmatterFields(agent, next);
+}
+function applyCustomAgentOverrides(agents, userSettings, projectSettings, userSettingsPath, projectSettingsPath) {
+	return agents.map((agent) => {
+		const projectOverride = projectSettings.overrides[agent.name];
+		if (projectOverride && projectSettingsPath) return applyCustomAgentOverride(agent, projectOverride, {
+			scope: "project",
+			path: projectSettingsPath
+		});
+		const userOverride = userSettings.overrides[agent.name];
+		if (userOverride) return applyCustomAgentOverride(agent, userOverride, {
+			scope: "user",
+			path: userSettingsPath
+		});
+		return agent;
+	});
+}
+//#endregion
+//#region src/services/agentLoader/index.ts
+/**
+* Reading agent definitions off disk into `AgentConfig` values.
+*
+* One markdown file is one agent: YAML frontmatter declares how the child run
+* should be shaped, and the body is its system prompt. This module owns the walk
+* that finds those files and the field-by-field interpretation of what it finds.
+* Precedence between sources, settings defaults, and builtin overrides are
+* applied by discovery afterwards, never here.
+*
+* DESIGN PATTERNS:
+* - A malformed value fails loudly, a malformed file is skipped quietly. A file
+*   missing `name` or `description` is simply not an agent and must not stop the
+*   sweep, but a `timeoutMs` of "soon" is an authoring mistake that has to
+*   surface rather than be silently dropped
+* - Frontmatter keys this module does not interpret are copied into
+*   `extraFields` verbatim, so a later writer can round-trip a file it did not
+*   fully understand
+* - The directory walk prunes at project boundaries, so an agent directory that
+*   happens to contain a checked-out sub-repository does not absorb its agents
+*
+* ASYNC-ONLY:
+* This package has no synchronous run mode, so the `async` frontmatter field is
+* not interpreted. It falls through into `extraFields` like any other key,
+* which keeps a definition written for the predecessor readable here.
+*
+* AVOID:
+* - Applying settings defaults or builtin overrides in this module
+* - Adding a field here without adding it to `LOADER_KNOWN_FIELDS`, which would
+*   leak it into `extraFields` and get it written back twice
+*/
+/**
+* The one builtin that extends the host's context instead of replacing it.
+*
+* `delegate` exists to carry out work on the operator's behalf in the same
+* project, so it inherits the host system prompt and project context. Every
+* other agent starts clean, which is what makes its output reproducible.
+*/
+const CONTEXT_INHERITING_BUILTIN = "delegate";
+function defaultSystemPromptMode(name) {
+	return name === CONTEXT_INHERITING_BUILTIN ? "append" : "replace";
+}
+function defaultInheritProjectContext(name) {
+	return name === CONTEXT_INHERITING_BUILTIN;
+}
+function defaultInheritSkills() {
+	return false;
+}
+/**
+* Every frontmatter key this module interprets.
+*
+* Anything absent from this set is preserved in `extraFields` instead. `async`
+* is deliberately absent: this package is async-only, so the key is data to
+* carry, not a setting to honour.
+*/
+const LOADER_KNOWN_FIELDS = /* @__PURE__ */ new Set([
+	"name",
+	"package",
+	"description",
+	"tools",
+	"model",
+	"fallbackModels",
+	"thinking",
+	"systemPromptMode",
+	"inheritProjectContext",
+	"inheritSkills",
+	"defaultContext",
+	"timeoutMs",
+	"skill",
+	"skills",
+	"skillPath",
+	"extensions",
+	"subagentOnlyExtensions",
+	"output",
+	"defaultReads",
+	"defaultProgress",
+	"interactive",
+	"maxSubagentDepth",
+	"completionGuard",
+	"toolBudget",
+	"memory"
+]);
+const TRUE_LITERAL = "true";
+const FALSE_LITERAL = "false";
+/** Frontmatter carries strings, so a boolean field is a tri-state until parsed. */
+function parseOptionalBoolean(raw) {
+	if (raw === TRUE_LITERAL) return true;
+	if (raw === FALSE_LITERAL) return false;
+}
+/** A package-qualified agent name: dot-separated lowercase segments. */
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+const PACKAGE_NAME_SEPARATOR = ".";
+/**
+* Reduce an authored package name to the canonical form used in runtime names.
+*
+* Sanitizing rather than rejecting outright keeps a human-written `My Tools`
+* usable, while the pattern check afterwards still rejects anything that
+* sanitizes down to nothing meaningful.
+*/
+function normalizePackageName(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return void 0;
+	return trimmed.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9.-]/g, "").replace(/-+/g, "-").replace(/\.+/g, ".").replace(/(?:^[-.]+|[-.]+$)/g, "");
+}
+/** Validate a `package` frontmatter value. An absent or empty value is not an error. */
+function parsePackageName(value, label = "package") {
+	if (value === void 0 || value === false || value === "") return { packageName: void 0 };
+	if (typeof value !== "string") return { error: `${label} must be a string or false when provided.` };
+	const packageName = normalizePackageName(value);
+	if (!packageName || !IDENTIFIER_PATTERN.test(packageName)) return { error: `${label} is invalid after sanitization.` };
+	return { packageName };
+}
+/** The name an agent is addressed by, qualified when it belongs to a package. */
+function buildRuntimeName(localName, packageName) {
+	const trimmedPackage = packageName?.trim();
+	return trimmedPackage ? `${trimmedPackage}${PACKAGE_NAME_SEPARATOR}${localName}` : localName;
+}
+/** Marks a tool that is reached through an MCP server rather than the host. */
+const MCP_TOOL_PREFIX = "mcp:";
+/**
+* Split an authored `tools` list into host tools and MCP tools.
+*
+* The two are separate fields on `AgentConfig` because they are enforced by
+* different layers, but a single flat list is what an author wants to write.
+*/
+function splitToolList(rawTools) {
+	const mcpDirectTools = [];
+	const tools = [];
+	for (const tool of rawTools ?? []) if (tool.startsWith(MCP_TOOL_PREFIX)) mcpDirectTools.push(tool.slice(4));
+	else tools.push(tool);
+	return {
+		...rawTools !== void 0 ? { tools } : {},
+		...mcpDirectTools.length > 0 ? { mcpDirectTools } : {}
+	};
+}
+const DISCOVERY_PRUNED_DIR_NAMES = /* @__PURE__ */ new Set([".git", "node_modules"]);
+const GIT_DIR_NAME = ".git";
+const LEGACY_AGENTS_DIR_NAME = ".agents";
+const LEGACY_SKILLS_DIR_NAME = "skills";
+const AGENT_FILE_EXTENSION = ".md";
+const CHAIN_FILE_EXTENSION = ".chain.md";
+function isDirectory(target) {
+	try {
+		return fs.statSync(target).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** A directory that owns its own agent configuration is a separate project. */
+function isDiscoveryNestedProjectRoot(dir, environment) {
+	return isDirectory(getProjectConfigDir(dir, environment)) || isDirectory(path.join(dir, LEGACY_AGENTS_DIR_NAME));
+}
+/**
+* Decide whether the walk should skip a subdirectory.
+*
+* A nested repository or nested project root is pruned because its agents
+* belong to that project, not to the one being scanned. The root itself is
+* exempt: scanning a project's own agent directory must not prune it.
+*/
+function shouldPruneDiscoveryDir(rootDir, dir, dirName, environment) {
+	if (DISCOVERY_PRUNED_DIR_NAMES.has(dirName)) return true;
+	if (fs.existsSync(path.join(dir, GIT_DIR_NAME))) return true;
+	return path.resolve(dir) !== path.resolve(rootDir) && isDiscoveryNestedProjectRoot(dir, environment);
+}
+/**
+* Collect matching files under `dir`, sorted so discovery order is stable.
+*
+* Symlinked entries are followed as files, because staging an agent by symlink
+* is a supported way to share one definition across projects.
+*/
+function listFilesRecursive(dir, predicate, rootDir = dir, environment = process.env) {
+	const files = [];
+	if (!fs.existsSync(dir)) return files;
+	let entries;
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	} catch {
+		return files;
+	}
+	for (const entry of entries) {
+		const filePath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (!shouldPruneDiscoveryDir(rootDir, filePath, entry.name, environment)) files.push(...listFilesRecursive(filePath, predicate, rootDir, environment));
+			continue;
+		}
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+		if (!predicate(entry.name)) continue;
+		files.push(filePath);
+	}
+	return files;
+}
+/**
+* Recognise a file that lives under a legacy `.agents/skills/` directory.
+*
+* Those markdown files are skill documents, not agent definitions, and they
+* predate the split. They would otherwise be loaded as nameless agents.
+*/
+function isLegacyAgentSkillPath(rootDir, filePath) {
+	const parts = path.relative(rootDir, filePath).split(path.sep).map((part) => part.toLowerCase());
+	if (path.basename(rootDir).toLowerCase() === LEGACY_AGENTS_DIR_NAME) parts.unshift(LEGACY_AGENTS_DIR_NAME);
+	return parts.some((part, index) => part === LEGACY_AGENTS_DIR_NAME && parts[index + 1] === LEGACY_SKILLS_DIR_NAME);
+}
+function parseSystemPromptMode(raw, localName) {
+	if (raw === "replace" || raw === "append") return raw;
+	return defaultSystemPromptMode(localName);
+}
+function parseDefaultContext(raw) {
+	return raw === "fork" || raw === "fresh" ? raw : void 0;
+}
+function parseTimeoutMs(raw, localName) {
+	if (raw === void 0) return void 0;
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`Agent '${localName}' has invalid timeoutMs frontmatter; expected a positive integer.`);
+	return parsed;
+}
+function parseToolBudget(raw, localName) {
+	if (raw === void 0 || !raw.trim()) return void 0;
+	const parsed = JSON.parse(raw);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`Agent '${localName}' has invalid toolBudget frontmatter; expected a JSON object.`);
+	return parsed;
+}
+/** True for an agent definition file, false for a chain or anything else. */
+function isAgentFileName(fileName) {
+	return fileName.endsWith(AGENT_FILE_EXTENSION) && !fileName.endsWith(CHAIN_FILE_EXTENSION);
+}
+/**
+* Load every agent definition under `dir`.
+*
+* The returned configs carry only what the file itself declared. Settings
+* defaults, builtin overrides, and cross-source precedence are the caller's job.
+*/
+function loadAgentsFromDir(dir, source, environment = process.env) {
+	const agents = [];
+	for (const filePath of listFilesRecursive(dir, isAgentFileName, dir, environment)) {
+		if (isLegacyAgentSkillPath(dir, filePath)) continue;
+		let content;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		const { frontmatter, body } = parseFrontmatter(content);
+		if (!frontmatter.name || !frontmatter.description) continue;
+		const localName = frontmatter.name;
+		const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
+		if (parsedPackage.error) continue;
+		const rawTools = parseFrontmatterList(frontmatter.tools);
+		const { tools, mcpDirectTools } = splitToolList(rawTools);
+		const skills = parseFrontmatterList(frontmatter.skill || frontmatter.skills);
+		const skillPath = parseFrontmatterList(frontmatter.skillPath);
+		const fallbackModels = parseFrontmatterList(frontmatter.fallbackModels);
+		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
+		const maxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+		const extraFields = {};
+		for (const [key, value] of Object.entries(frontmatter)) if (!LOADER_KNOWN_FIELDS.has(key)) extraFields[key] = value;
+		const agent = {
+			name: buildRuntimeName(localName, parsedPackage.packageName),
+			localName,
+			packageName: parsedPackage.packageName,
+			description: frontmatter.description,
+			tools: rawTools !== void 0 ? tools ?? [] : void 0,
+			mcpDirectTools: mcpDirectTools && mcpDirectTools.length > 0 ? mcpDirectTools : void 0,
+			model: frontmatter.model,
+			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : void 0,
+			thinking: frontmatter.thinking === FALSE_LITERAL ? false : frontmatter.thinking,
+			systemPromptMode: parseSystemPromptMode(frontmatter.systemPromptMode, localName),
+			inheritProjectContext: parseOptionalBoolean(frontmatter.inheritProjectContext) ?? defaultInheritProjectContext(localName),
+			inheritSkills: parseOptionalBoolean(frontmatter.inheritSkills) ?? defaultInheritSkills(),
+			defaultContext: parseDefaultContext(frontmatter.defaultContext),
+			defaultTimeoutMs: parseTimeoutMs(frontmatter.timeoutMs, localName),
+			systemPrompt: body,
+			source,
+			filePath,
+			skills: skills && skills.length > 0 ? skills : void 0,
+			skillPath: skillPath && skillPath.length > 0 ? skillPath : void 0,
+			extensions: parseFrontmatterList(frontmatter.extensions),
+			subagentOnlyExtensions: parseFrontmatterList(frontmatter.subagentOnlyExtensions),
+			output: frontmatter.output,
+			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : void 0,
+			defaultProgress: frontmatter.defaultProgress === TRUE_LITERAL,
+			interactive: frontmatter.interactive === TRUE_LITERAL,
+			maxSubagentDepth: Number.isInteger(maxSubagentDepth) && maxSubagentDepth >= 0 ? maxSubagentDepth : void 0,
+			completionGuard: parseOptionalBoolean(frontmatter.completionGuard),
+			toolBudget: parseToolBudget(frontmatter.toolBudget, localName),
+			memory: parseMemoryFrontmatter(frontmatter.memory),
+			extraFields: Object.keys(extraFields).length > 0 ? extraFields : void 0
+		};
+		setAgentFrontmatterFields(agent, new Set(Object.keys(frontmatter)));
+		agents.push(agent);
+	}
+	return agents;
+}
+/**
+* Read-only agent directories contributed by plugins.
+*
+* Read from the environment on every call rather than captured once, because a
+* host can stage a plugin directory after this module is first imported.
+*/
+function pluginAgentDirs(environment = process.env) {
+	return (environment["PI_SUBAGENT_EXTRA_AGENT_DIRS"] ?? "").split(path.delimiter).map((directory) => directory.trim()).filter((directory) => directory.length > 0);
+}
+//#endregion
+//#region src/services/lruCache/index.ts
+/**
+* LruCache - a bounded cache with least-recently-used eviction.
+*
+* DESIGN PATTERNS:
+* - Backed by a Map, which iterates in insertion order. Re-inserting a key on
+*   read moves it to the end, so the first key is always the least recently used
+*
+* WHY LRU AND NOT FIFO:
+* The predecessor package evicted in insertion order at a cap of 50. Once more
+* than 50 runs were live it evicted the entry it was about to read next, so the
+* cache degenerated to a permanent miss while still paying for the stat that
+* populated it. Recency-based eviction keeps the hot entries.
+*
+* AVOID:
+* - Reading through `map.get` directly anywhere; that skips the recency update
+*/
+const MINIMUM_CAPACITY = 1;
+var LruCache = class {
+	entries = /* @__PURE__ */ new Map();
+	capacity;
+	constructor(capacity) {
+		if (!Number.isInteger(capacity) || capacity < MINIMUM_CAPACITY) throw new Error(`LruCache capacity must be an integer of at least ${MINIMUM_CAPACITY}.`);
+		this.capacity = capacity;
+	}
+	get size() {
+		return this.entries.size;
+	}
+	has(key) {
+		return this.entries.has(key);
+	}
+	/** Read a value, marking it most recently used. */
+	get(key) {
+		if (!this.entries.has(key)) return void 0;
+		const value = this.entries.get(key);
+		this.entries.delete(key);
+		this.entries.set(key, value);
+		return value;
+	}
+	/** Insert or replace a value, marking it most recently used. */
+	set(key, value) {
+		if (this.entries.has(key)) this.entries.delete(key);
+		this.entries.set(key, value);
+		while (this.entries.size > this.capacity) {
+			const oldest = this.entries.keys().next();
+			if (oldest.done === true) break;
+			this.entries.delete(oldest.value);
+		}
+	}
+	delete(key) {
+		return this.entries.delete(key);
+	}
+	clear() {
+		this.entries.clear();
+	}
+	/** Keys from least to most recently used. Intended for tests and diagnostics. */
+	keysFromOldest() {
+		return [...this.entries.keys()];
+	}
+};
+//#endregion
+//#region src/services/agentDiscovery/index.ts
+/**
+* Cached discovery of the agents visible from a working directory.
+*
+* WHY THIS IS A SERVICE AND NOT A FUNCTION:
+* Discovery reads two settings files and walks every agent directory in scope,
+* parsing the frontmatter of every file it finds. The slash-command completion
+* path asks for the agent list on each keystroke, and preflight asks again for
+* each launch, so the predecessor's plain function re-walked the tree many times
+* per second. Caching needs somewhere to live, and invalidation needs an owner.
+*
+* DESIGN PATTERNS:
+* - Two-layer validity. A short TTL bounds how stale an answer can be, and a
+*   cheap source fingerprint catches the common edits sooner than the TTL would
+* - Bounded by an LRU keyed on cwd and scope, so a long session that visits many
+*   directories cannot grow the cache without limit
+* - Mutations invalidate explicitly rather than relying on the TTL, so an agent
+*   the user just created is visible immediately
+*
+* WHY THE FINGERPRINT IS NOT ENOUGH ON ITS OWN:
+* It stats the settings files and the agent directories, not every agent file.
+* A directory's mtime moves when a file is added or removed but not when an
+* existing file's contents change, so an in-place edit is caught by the TTL
+* rather than by the fingerprint. Stat'ing every agent file on every keystroke
+* would reintroduce the cost this cache exists to remove.
+*
+* AVOID:
+* - Handing out the cached array without copying it; a caller that sorts or
+*   splices in place would corrupt every later reader
+* - Raising the TTL to hide a missing invalidate call
+*/
+/** How long a discovery result may be reused without revalidation. */
+const DISCOVERY_TTL_MS = 5e3;
+/**
+* How many (cwd, scope) combinations stay cached.
+*
+* A session works in a handful of directories and there are three scopes, so
+* this is far above real usage; it exists to bound a pathological case.
+*/
+const MAX_CACHED_DISCOVERIES = 64;
+const FINGERPRINT_FIELD_SEPARATOR = ":";
+const FINGERPRINT_ENTRY_SEPARATOR = "|";
+const MISSING_SOURCE_MARKER = "-";
+const MAJOR_MODES_CONFIG_RELATIVE_PATH = path.join(".po", "modes.yaml");
+const THINKING_SUFFIX = /:(?:off|minimal|low|medium|high|xhigh|max)$/;
+/**
+* Merge the sources into one list, later sources shadowing earlier ones.
+*
+* Precedence is plugin, then user, then project: the definition closest to the
+* work being done wins, which is what lets a repository pin an agent that the
+* user has also defined globally.
+*/
+function mergeAgentsForScope(scope, userAgents, projectAgents, pluginAgents = []) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const agent of pluginAgents) byName.set(agent.name, agent);
+	if (scope !== "project") for (const agent of userAgents) byName.set(agent.name, agent);
+	if (scope !== "user") for (const agent of projectAgents) byName.set(agent.name, agent);
+	return [...byName.values()];
+}
+/** Size and mtime of one path, or a marker when it does not exist. */
+function stampOf(target) {
+	try {
+		const stat = fs.statSync(target);
+		return `${target}${FINGERPRINT_FIELD_SEPARATOR}${stat.mtimeMs}${FINGERPRINT_FIELD_SEPARATOR}${stat.size}`;
+	} catch {
+		return `${target}${FINGERPRINT_FIELD_SEPARATOR}${MISSING_SOURCE_MARKER}`;
+	}
+}
+/** Resolve Team-owned package configuration from the current parent harness state. */
+function resolveActiveTeamPackageConfig(environment = process.env) {
+	const harness = loadHarnessState(environment).state;
+	if (!harness.root) return void 0;
+	const layers = loadMajorModesConfig(harness.root, environment.HOME);
+	const config = mergeTeamPackageConfigurations(resolvePackageConfigurations(layers, harness.layers, PO_TEAM_PACKAGE));
+	return config ? {
+		config,
+		path: path.join(harness.root, MAJOR_MODES_CONFIG_RELATIVE_PATH)
+	} : void 0;
+}
+function teamModelSpecs(config) {
+	if (!config?.models) return void 0;
+	return config.models.map(({ model, thinking }) => thinking ? `${model.replace(THINKING_SUFFIX, "")}:${thinking}` : model);
+}
+/** Resolve Team's ordered package model policy without merging it into an agent definition. */
+function resolveActiveTeamModelSpecs(environment = process.env) {
+	return teamModelSpecs(resolveActiveTeamPackageConfig(environment)?.config);
+}
+var AgentDiscoveryService = class {
+	environment;
+	constructor(environment = process.env) {
+		this.environment = environment;
+	}
+	cache = new LruCache(MAX_CACHED_DISCOVERIES);
+	/**
+	* Seams for tests, as protected members rather than constructor arguments.
+	*
+	* Runtime tuning is not part of this service's dependency contract. A test
+	* subclass overrides these values without abstracting the clock.
+	*/
+	ttlMs = DISCOVERY_TTL_MS;
+	now() {
+		return Date.now();
+	}
+	discover(cwd, scope) {
+		const resolvedCwd = path.resolve(cwd);
+		const canonicalCwd = canonicalizeDiscoveryCwd(resolvedCwd);
+		const key = `${scope}${FINGERPRINT_ENTRY_SEPARATOR}${canonicalCwd}`;
+		const cached = this.cache.get(key);
+		const timestamp = this.now();
+		if (cached && cached.expiresAt > timestamp && cached.fingerprint === this.fingerprint(canonicalCwd)) return cloneResult(cached.result);
+		const result = this.load(resolvedCwd, scope);
+		this.cache.set(key, {
+			result,
+			expiresAt: timestamp + this.ttlMs,
+			fingerprint: this.fingerprint(canonicalCwd)
+		});
+		return cloneResult(result);
+	}
+	find(cwd, scope, name) {
+		return this.discover(cwd, scope).agents.find((agent) => agent.name === name);
+	}
+	invalidate() {
+		this.cache.clear();
+	}
+	/**
+	* A cheap stamp of everything discovery reads at the directory level.
+	*
+	* Deliberately independent of scope: a user-scoped and a project-scoped lookup
+	* from the same directory read overlapping sources, and computing one stamp
+	* keeps the stat count fixed regardless of how many scopes are queried.
+	*/
+	fingerprint(cwd) {
+		const harness = loadHarnessState(this.environment).state;
+		const sources = [
+			getUserAgentSettingsPath(this.environment),
+			getProjectAgentSettingsPath(cwd, this.environment) ?? MISSING_SOURCE_MARKER,
+			...userAgentDirs(this.environment),
+			...resolveNearestProjectAgentDirs(cwd, this.environment).readDirs,
+			...pluginAgentDirs(this.environment)
+		];
+		if (harness.root) sources.push(path.join(harness.root, MAJOR_MODES_CONFIG_RELATIVE_PATH));
+		return [...sources.map(stampOf), `active-layers${FINGERPRINT_FIELD_SEPARATOR}${harness.layers.join(",")}`].join(FINGERPRINT_ENTRY_SEPARATOR);
+	}
+	/**
+	* The uncached read. Protected so a test can count how often it actually runs,
+	* which is the only direct way to assert that the cache is doing its job.
+	*/
+	load(cwd, scope) {
+		const userSettingsPath = getUserAgentSettingsPath(this.environment);
+		const projectSettingsPath = getProjectAgentSettingsPath(cwd, this.environment);
+		const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
+		const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
+		const legacyDefaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+		const teamPackage = resolveActiveTeamPackageConfig(this.environment);
+		const packagePrimaryModel = teamModelSpecs(teamPackage?.config)?.[0];
+		const defaultModel = packagePrimaryModel && teamPackage ? {
+			type: "packages.team.defaultModel",
+			scope: "package",
+			path: teamPackage.path,
+			model: packagePrimaryModel
+		} : legacyDefaultModel;
+		const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+		const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
+		const resolve = (agents) => applyCustomAgentOverrides(applySubagentDefaults(agents, defaultModel, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+		const plugin = resolve(pluginAgentDirs(this.environment).flatMap((directory) => loadAgentsFromDir(directory, "plugin", this.environment)));
+		return {
+			agents: mergeAgentsForScope(scope, scope === "project" ? [] : resolve(userAgentDirs(this.environment).flatMap((directory) => loadAgentsFromDir(directory, "user", this.environment))), scope === "user" ? [] : resolve(resolveNearestProjectAgentDirs(cwd, this.environment).readDirs.flatMap((directory) => loadAgentsFromDir(directory, "project", this.environment))), plugin).filter((agent) => agent.disabled !== true),
+			projectAgentsDir: resolveNearestProjectAgentDirs(cwd, this.environment).preferredDir,
+			modelScope: projectSettings.modelScope ?? userSettings.modelScope
+		};
+	}
+};
+/**
+* Copy the parts a caller could mutate in place.
+*
+* The agent objects themselves are treated as immutable by every consumer, so
+* only the array is copied; deep-cloning every config on each keystroke would
+* cost more than the walk this cache replaced.
+*/
+function cloneResult(result) {
+	return {
+		...result,
+		agents: [...result.agents]
+	};
+}
+//#endregion
+export { agentHasWriteTools as a, getProjectConfigDir as c, LruCache as i, resolveActiveTeamModelSpecs as n, canonicalizeDiscoveryCwd as o, resolveActiveTeamPackageConfig as r, getAgentDir as s, AgentDiscoveryService as t };
+
+//# sourceMappingURL=agentDiscovery-ZQlFkKvB.mjs.map