@agentyx/core 0.1.0

package/dist/index.mjs

@@ -0,0 +1,981 @@
+import { z } from "zod";
+import { access, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/errors.ts
+/**
+* Base class for every failure Agentyx raises deliberately.
+*
+* Consumers can catch `AgentyxError` to separate expected domain failures from
+* unexpected runtime errors, and branch on the stable `code` when they need to
+* handle a specific failure.
+*/
+var AgentyxError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "AgentyxError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/config/errors.ts
+/** Raised when the supplied directory has no `.agentyx.json`. */
+var AgentyxConfigNotFoundError = class extends AgentyxError {
+	filePath;
+	constructor(filePath, options) {
+		super("agentyx_config_not_found", `Agentyx configuration file not found: ${filePath}`, options);
+		this.name = "AgentyxConfigNotFoundError";
+		this.filePath = filePath;
+	}
+};
+/** Raised when `.agentyx.json` is not valid JSON. */
+var AgentyxConfigParseError = class extends AgentyxError {
+	filePath;
+	constructor(filePath, reason, options) {
+		super("agentyx_config_parse_error", `${filePath} is not valid JSON: ${reason}`, options);
+		this.name = "AgentyxConfigParseError";
+		this.filePath = filePath;
+	}
+};
+/** Raised when the document parses as JSON but violates the Agentyx schema. */
+var AgentyxConfigValidationError = class extends AgentyxError {
+	issues;
+	/** The file the configuration came from, when it was read from disk. */
+	filePath;
+	constructor(error, filePath) {
+		const issues = toConfigIssues(error);
+		const location = filePath === void 0 ? "" : ` in ${filePath}`;
+		const details = issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n");
+		super("agentyx_config_invalid", `Invalid Agentyx configuration${location}:\n${details}`);
+		this.name = "AgentyxConfigValidationError";
+		this.issues = issues;
+		this.filePath = filePath;
+	}
+};
+function toConfigIssues(error) {
+	return error.issues.map((issue) => ({
+		path: formatIssuePath(issue.path),
+		message: issue.message
+	}));
+}
+function formatIssuePath(path) {
+	if (path.length === 0) return "(root)";
+	return path.reduce((formatted, segment) => {
+		if (typeof segment === "number") return `${formatted}[${segment}]`;
+		return formatted === "" ? String(segment) : `${formatted}.${String(segment)}`;
+	}, "");
+}
+//#endregion
+//#region src/mcp/schema.ts
+const MCP_CAPABILITY_LEVELS = [
+	"essential",
+	"recommended",
+	"optional"
+];
+const mcpCapabilityLevelSchema = z.enum(MCP_CAPABILITY_LEVELS);
+const MCP_CONTEXT_COSTS = [
+	"low",
+	"medium",
+	"high"
+];
+const mcpContextCostSchema = z.enum(MCP_CONTEXT_COSTS);
+const mcpServerNameSchema = z.string().min(1, "MCP server names must be non-empty strings.").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "MCP server names must be lowercase kebab-case, for example \"context7\".");
+const mcpEnvReferenceSchema = z.strictObject({ fromEnv: z.string().trim().min(1, "Environment variable references must be non-empty strings.").regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "Environment variable names must be valid shell names.") });
+const commonMcpServerDefinitionSchema = z.strictObject({
+	name: mcpServerNameSchema.describe("Unique MCP server identifier."),
+	description: z.string().trim().min(1, "MCP server descriptions must be non-empty strings."),
+	transport: z.enum(["stdio", "http"]),
+	contextCost: mcpContextCostSchema.describe("Qualitative context/tool-schema overhead classification; not token accounting.").optional()
+});
+const explicitMcpServerReferenceSchema = z.strictObject({
+	name: mcpServerNameSchema.describe("MCP server identifier."),
+	level: mcpCapabilityLevelSchema.describe("How important this MCP capability is to the declaring stack.").default("recommended")
+});
+const mcpServerReferenceSchema = z.union([mcpServerNameSchema, explicitMcpServerReferenceSchema]).transform((value) => typeof value === "string" ? {
+	name: value,
+	level: "recommended"
+} : value).pipe(z.strictObject({
+	name: mcpServerNameSchema.describe("MCP server identifier."),
+	level: mcpCapabilityLevelSchema.describe("How important this MCP capability is to the declaring stack.")
+}));
+const stdioMcpServerDefinitionSchema = commonMcpServerDefinitionSchema.extend({
+	transport: z.literal("stdio"),
+	command: z.string().trim().min(1, "MCP stdio command must be a non-empty string."),
+	args: z.array(z.string()).default([]),
+	env: z.record(z.string().min(1), mcpEnvReferenceSchema).default({})
+});
+const httpMcpServerDefinitionSchema = commonMcpServerDefinitionSchema.extend({
+	transport: z.literal("http"),
+	url: z.url("MCP HTTP URL must be a valid URL."),
+	headers: z.record(z.string().min(1), mcpEnvReferenceSchema).default({})
+});
+const mcpServerDefinitionSchema = z.discriminatedUnion("transport", [stdioMcpServerDefinitionSchema, httpMcpServerDefinitionSchema]);
+//#endregion
+//#region src/skill/schema.ts
+/**
+* Skill names double as directory names for `SKILL.md` files, so they are
+* constrained to a lowercase slug. That keeps them stable across filesystems
+* and makes them safe to join onto a path.
+*/
+const skillNameSchema = z.string().min(1, "Skill names must be non-empty strings.").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Skill names must be lowercase kebab-case, for example \"typescript-modern\".");
+/**
+* The metadata a Skill carries, and exactly what a `SKILL.md` frontmatter block
+* may declare. Kept separate from the full definition so the parser can reject
+* a frontmatter key that tries to supply the body.
+*/
+const skillMetadataSchema = z.strictObject({
+	name: skillNameSchema.describe("Unique skill identifier."),
+	description: z.string().trim().min(1, "Skill descriptions must be non-empty strings.").describe("One-line summary of what the skill tells an agent to do.")
+});
+/**
+* A Skill is reusable instruction text for a coding agent. It is deliberately
+* provider-independent: nothing here says how or where a provider installs it.
+*/
+const skillDefinitionSchema = skillMetadataSchema.extend({ content: z.string().trim().min(1, "Skill content must be non-empty.").describe("The Markdown instructions handed to an agent.") });
+//#endregion
+//#region src/stack/schema.ts
+/**
+* Stack names are plain identifiers. They are intentionally not constrained to
+* a closed list so that external registries can contribute stacks later.
+*/
+const stackNameSchema = z.string().min(1, "Stack names must be non-empty strings.");
+/**
+* A stack describes a development environment that can build on other stacks
+* and contribute provider-agnostic capabilities to them.
+*/
+const stackDefinitionSchema = z.strictObject({
+	name: stackNameSchema.describe("Unique stack identifier."),
+	description: z.string().min(1, "Stack descriptions must be non-empty when provided.").describe("Short human-readable summary of the stack.").optional(),
+	extends: z.array(stackNameSchema).describe("Stacks this stack builds on, in dependency-first order.").default([]),
+	skills: z.array(skillNameSchema).describe("Skills this stack contributes, in declaration order.").default([]),
+	mcpServers: z.array(mcpServerReferenceSchema).describe("MCP servers this stack contributes, in declaration order.").default([])
+});
+//#endregion
+//#region src/config/schema.ts
+/** How much autonomy the generated environment should grant an agent. */
+const AGENTYX_PROFILES = [
+	"lean",
+	"balanced",
+	"autonomous"
+];
+const agentyxProfileSchema = z.enum(AGENTYX_PROFILES, { error: `Profile must be one of: ${AGENTYX_PROFILES.join(", ")}.` });
+/** Applied when a configuration omits `profile`. */
+const DEFAULT_AGENTYX_PROFILE = "balanced";
+/**
+* Targets stay free-form strings on purpose: third-party adapters should be
+* able to register providers without a change to this schema.
+*/
+const agentyxTargetSchema = z.string().min(1, "Targets must be non-empty strings.");
+/** The `.agentyx.json` project configuration. */
+const agentyxConfigSchema = z.strictObject({
+	$schema: z.string().min(1, "$schema must be a non-empty string.").describe("Optional path or URL to the Agentyx JSON Schema.").optional(),
+	extends: z.array(stackNameSchema).describe("Stacks this project builds on.").default([]),
+	profile: agentyxProfileSchema.describe("How much autonomy the generated environment grants.").default(DEFAULT_AGENTYX_PROFILE),
+	targets: z.array(agentyxTargetSchema).describe("Coding-agent providers this project targets.").default([])
+});
+//#endregion
+//#region src/config/json-schema.ts
+/** Canonical identifier of the published `.agentyx.json` schema. */
+const AGENTYX_CONFIG_SCHEMA_ID = "https://agentyx.dev/schema/agentyx.schema.json";
+/**
+* Derives the JSON Schema for `.agentyx.json` from the Zod model, which stays the
+* single source of truth. The committed `schema/agentyx.schema.json` is generated
+* from this function and verified by tests.
+*
+* The `input` view is used so that fields with defaults stay optional, which is
+* what an author writing the file cares about.
+*/
+function buildAgentyxConfigJsonSchema() {
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		$id: AGENTYX_CONFIG_SCHEMA_ID,
+		title: "Agentyx project configuration",
+		description: "Configuration for an Agentyx project (.agentyx.json).",
+		...z.toJSONSchema(agentyxConfigSchema, { io: "input" })
+	};
+}
+//#endregion
+//#region src/config/loader.ts
+const AGENTYX_CONFIG_FILENAME = ".agentyx.json";
+/** The absolute path `.agentyx.json` is read from for a given project. */
+function agentyxConfigPath(projectPath = process.cwd()) {
+	return resolve(projectPath, AGENTYX_CONFIG_FILENAME);
+}
+/**
+* Validates an already-parsed configuration document.
+*
+* @throws {AgentyxConfigValidationError} when the document violates the schema.
+*/
+function parseAgentyxConfig(value, filePath) {
+	const result = agentyxConfigSchema.safeParse(value);
+	if (!result.success) throw new AgentyxConfigValidationError(result.error, filePath);
+	return result.data;
+}
+/**
+* Reads and validates `.agentyx.json` from `projectPath`.
+*
+* Parent directories are not searched, and invalid configurations are never
+* silently repaired.
+*
+* @throws {AgentyxConfigNotFoundError} when the file does not exist.
+* @throws {AgentyxConfigParseError} when the file is not valid JSON.
+* @throws {AgentyxConfigValidationError} when the document violates the schema.
+*/
+async function loadAgentyxConfig(projectPath = process.cwd()) {
+	const filePath = agentyxConfigPath(projectPath);
+	let contents;
+	try {
+		contents = await readFile(filePath, "utf8");
+	} catch (cause) {
+		if (isFileNotFound(cause)) throw new AgentyxConfigNotFoundError(filePath, { cause });
+		throw cause;
+	}
+	let document;
+	try {
+		document = JSON.parse(contents);
+	} catch (cause) {
+		throw new AgentyxConfigParseError(filePath, cause instanceof Error ? cause.message : String(cause), { cause });
+	}
+	return parseAgentyxConfig(document, filePath);
+}
+function isFileNotFound(cause) {
+	return cause instanceof Error && cause.code === "ENOENT";
+}
+//#endregion
+//#region src/mcp/errors.ts
+var UnknownMcpServerError = class extends AgentyxError {
+	serverName;
+	requiredBy;
+	knownServers;
+	constructor(serverName, requiredBy, knownServers) {
+		const origin = requiredBy === void 0 ? "" : ` (required by stack "${requiredBy}")`;
+		const known = knownServers.length > 0 ? [...knownServers].sort().join(", ") : "none";
+		super("unknown_mcp_server", `Unknown MCP server "${serverName}"${origin}. Known MCP servers: ${known}.`);
+		this.name = "UnknownMcpServerError";
+		this.serverName = serverName;
+		this.requiredBy = requiredBy;
+		this.knownServers = knownServers;
+	}
+};
+var DuplicateMcpServerError = class extends AgentyxError {
+	serverName;
+	constructor(serverName) {
+		super("duplicate_mcp_server", `Duplicate MCP server definition: "${serverName}".`);
+		this.name = "DuplicateMcpServerError";
+		this.serverName = serverName;
+	}
+};
+var InvalidMcpServerError = class extends AgentyxError {
+	origin;
+	reason;
+	constructor(origin, reason, options) {
+		const detail = typeof reason === "string" ? reason : formatIssues$1(reason);
+		super("invalid_mcp_server", `Invalid MCP server in ${origin}: ${detail}`, options);
+		this.name = "InvalidMcpServerError";
+		this.origin = origin;
+		this.reason = detail;
+	}
+};
+function formatIssues$1(error) {
+	return error.issues.map((issue) => {
+		const path = issue.path.map(String).join(".");
+		return path === "" ? issue.message : `${path}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/mcp/registry.ts
+function createMcpServerRegistry(sources) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const name = mcpServerNameSchema.safeParse(source.name);
+		if (!name.success) throw new InvalidMcpServerError(`MCP server source "${source.name}"`, name.error);
+		if (byName.has(name.data)) throw new DuplicateMcpServerError(name.data);
+		byName.set(name.data, source);
+	}
+	const names = [...byName.keys()];
+	const loaded = /* @__PURE__ */ new Map();
+	const get = (name) => {
+		const cached = loaded.get(name);
+		if (cached !== void 0) return cached;
+		const source = byName.get(name);
+		if (source === void 0) throw new UnknownMcpServerError(name, void 0, names);
+		const origin = `MCP server "${name}"`;
+		const server = mcpServerDefinitionSchema.safeParse(source.load());
+		if (!server.success) throw new InvalidMcpServerError(origin, server.error);
+		if (server.data.name !== name) throw new InvalidMcpServerError(origin, `it declares the name "${server.data.name}"`);
+		loaded.set(name, server.data);
+		return server.data;
+	};
+	return {
+		names,
+		has: (name) => byName.has(name),
+		listMetadata: () => names.map((name) => {
+			const server = get(name);
+			return {
+				name: server.name,
+				description: server.description,
+				transport: server.transport,
+				contextCost: server.contextCost
+			};
+		}),
+		get
+	};
+}
+const builtInMcpServerRegistry = createMcpServerRegistry([{
+	name: "context7",
+	load: () => ({
+		name: "context7",
+		description: "Fetch up-to-date library documentation from Context7.",
+		transport: "http",
+		contextCost: "medium",
+		url: "https://mcp.context7.com/mcp"
+	})
+}, {
+	name: "playwright",
+	load: () => ({
+		name: "playwright",
+		description: "Automate and inspect browsers through Playwright MCP.",
+		transport: "stdio",
+		contextCost: "high",
+		command: "npx",
+		args: ["@playwright/mcp@latest"]
+	})
+}]);
+const builtInMcpServerNames = builtInMcpServerRegistry.names;
+//#endregion
+//#region src/optimization/profile.ts
+const optimizationProfiles = [
+	{
+		name: "lean",
+		goal: "Minimum context and tool overhead.",
+		mcpLevels: ["essential"],
+		notes: [
+			"Installs all resolved Skills.",
+			"Keeps MCP exposure to essential capabilities.",
+			"Prefers local CLI or native tools when they cover the same workflow."
+		]
+	},
+	{
+		name: "balanced",
+		goal: "Good default developer experience with conservative autonomy.",
+		mcpLevels: ["essential", "recommended"],
+		notes: ["Installs all resolved Skills.", "Includes default and recommended MCP capabilities."]
+	},
+	{
+		name: "autonomous",
+		goal: "Maximum agent capability from declared stack capabilities.",
+		mcpLevels: [
+			"essential",
+			"recommended",
+			"optional"
+		],
+		notes: ["Installs all resolved Skills.", "Includes optional MCP capabilities declared by the selected stacks."]
+	}
+];
+const optimizationProfileNames = optimizationProfiles.map((profile) => profile.name);
+function getOptimizationProfile(name) {
+	const profile = optimizationProfiles.find((candidate) => candidate.name === name);
+	if (profile === void 0) throw new Error(`Unknown optimization profile: ${name}`);
+	return profile;
+}
+function isMcpLevelEnabled(profile, level) {
+	return getOptimizationProfile(profile).mcpLevels.includes(level);
+}
+//#endregion
+//#region src/stack/errors.ts
+/**
+* Raised when a requested or inherited stack is not present in the registry.
+*
+* The offending name is exposed as `stackName`; `stack` stays the JS stack
+* trace inherited from `Error`.
+*/
+var UnknownStackError = class extends AgentyxError {
+	stackName;
+	requiredBy;
+	knownStacks;
+	constructor(stackName, requiredBy, knownStacks) {
+		const origin = requiredBy === void 0 ? "" : ` (required by "${requiredBy}")`;
+		const known = knownStacks.length > 0 ? [...knownStacks].sort().join(", ") : "none";
+		super("unknown_stack", `Unknown stack "${stackName}"${origin}. Known stacks: ${known}.`);
+		this.name = "UnknownStackError";
+		this.stackName = stackName;
+		this.requiredBy = requiredBy;
+		this.knownStacks = knownStacks;
+	}
+};
+/** Raised when stack inheritance forms a cycle. */
+var CircularStackDependencyError = class extends AgentyxError {
+	/** The cycle path, starting and ending with the same stack. */
+	cycle;
+	constructor(cycle) {
+		super("circular_stack_dependency", `Circular stack dependency: ${cycle.join(" -> ")}.`);
+		this.name = "CircularStackDependencyError";
+		this.cycle = cycle;
+	}
+};
+/** Raised when a registry is built from definitions that reuse a stack name. */
+var DuplicateStackError = class extends AgentyxError {
+	stackName;
+	constructor(stackName) {
+		super("duplicate_stack", `Duplicate stack definition: "${stackName}".`);
+		this.name = "DuplicateStackError";
+		this.stackName = stackName;
+	}
+};
+//#endregion
+//#region src/stack/registry.ts
+/** Validates definitions and indexes them by name. */
+function createStackRegistry(definitions) {
+	const registry = /* @__PURE__ */ new Map();
+	for (const definition of definitions) {
+		const stack = stackDefinitionSchema.parse(definition);
+		if (registry.has(stack.name)) throw new DuplicateStackError(stack.name);
+		registry.set(stack.name, stack);
+	}
+	return registry;
+}
+/**
+* The stacks Agentyx ships with, expressed as data. Relationships live here, not
+* in the resolver.
+*/
+const builtInStacks = [
+	{
+		name: "core",
+		description: "Baseline development environment shared by every Agentyx stack.",
+		skills: [
+			"planning",
+			"systematic-debugging",
+			"verification"
+		]
+	},
+	{
+		name: "typescript",
+		description: "TypeScript development environment.",
+		extends: ["core"],
+		skills: ["typescript-modern"]
+	},
+	{
+		name: "angular",
+		description: "Modern Angular development environment.",
+		extends: ["typescript"],
+		skills: ["angular-modern"],
+		mcpServers: [{
+			name: "context7",
+			level: "recommended"
+		}]
+	}
+];
+/** The registry used by default when no explicit registry is supplied. */
+const builtInStackRegistry = createStackRegistry(builtInStacks);
+//#endregion
+//#region src/stack/resolver.ts
+/**
+* Expands the requested stacks into the full inheritance chain.
+*
+* The result is dependency-first, de-duplicated and deterministic: stacks are
+* visited in the order they are requested, and each stack's parents are visited
+* in declaration order before the stack itself.
+*
+* @throws {UnknownStackError} when a requested or inherited stack is missing.
+* @throws {CircularStackDependencyError} when inheritance forms a cycle.
+*/
+function resolveStacks(requestedStacks, registry = builtInStackRegistry) {
+	const resolved = [];
+	const settled = /* @__PURE__ */ new Set();
+	const path = [];
+	const visit = (name, requiredBy) => {
+		if (settled.has(name)) return;
+		const cycleStart = path.indexOf(name);
+		if (cycleStart !== -1) throw new CircularStackDependencyError([...path.slice(cycleStart), name]);
+		const definition = registry.get(name);
+		if (definition === void 0) throw new UnknownStackError(name, requiredBy, [...registry.keys()]);
+		path.push(name);
+		for (const parent of definition.extends) visit(parent, name);
+		path.pop();
+		settled.add(name);
+		resolved.push(name);
+	};
+	for (const name of requestedStacks) visit(name, void 0);
+	return resolved;
+}
+//#endregion
+//#region src/mcp/resolver.ts
+function collectStackMcpServerReferences(resolvedStacks, stackRegistry, mcpRegistry) {
+	const servers = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const stackName of resolvedStacks) for (const server of stackRegistry.get(stackName)?.mcpServers ?? []) {
+		const serverName = server.name;
+		if (seen.has(serverName)) continue;
+		if (!mcpRegistry.has(serverName)) throw new UnknownMcpServerError(serverName, stackName, mcpRegistry.names);
+		seen.add(serverName);
+		servers.push(server);
+	}
+	return servers;
+}
+function filterEffectiveMcpServers(servers, profile) {
+	return servers.filter((server) => isMcpLevelEnabled(profile, server.level)).map((server) => server.name);
+}
+function collectStackMcpServers(resolvedStacks, stackRegistry, mcpRegistry, profile = DEFAULT_AGENTYX_PROFILE) {
+	return filterEffectiveMcpServers(collectStackMcpServerReferences(resolvedStacks, stackRegistry, mcpRegistry), profile);
+}
+function resolveStackMcpServerReferences(requestedStacks, stackRegistry = builtInStackRegistry, mcpRegistry = builtInMcpServerRegistry) {
+	return collectStackMcpServerReferences(resolveStacks(requestedStacks, stackRegistry), stackRegistry, mcpRegistry);
+}
+function resolveStackMcpServers(requestedStacks, stackRegistry = builtInStackRegistry, mcpRegistry = builtInMcpServerRegistry, profile = DEFAULT_AGENTYX_PROFILE) {
+	return collectStackMcpServers(resolveStacks(requestedStacks, stackRegistry), stackRegistry, mcpRegistry, profile);
+}
+//#endregion
+//#region src/assets.ts
+/**
+* Location of the non-code assets that ship with `@agentyx/core`.
+*
+* **This module must stay directly under `src/`.** The path is derived from
+* `import.meta.url` rather than the working directory, and `src/assets.ts` and
+* the bundled `dist/index.mjs` sit at the same depth below the package root, so
+* one relative path is correct both in development and in the published
+* package. Moving this file into a subdirectory breaks built-in skill loading;
+* `packages/core/test/built-in-skills.test.ts` guards against that.
+*
+* `skills/` is listed in the package's `files`, so it is published alongside
+* `dist/`.
+*/
+const BUILT_IN_SKILLS_PATH = fileURLToPath(new URL("../skills", import.meta.url));
+//#endregion
+//#region src/skill/errors.ts
+/**
+* Raised when a stack references a skill the registry does not know.
+*
+* The offending name is exposed as `skillName`; `stack` stays the JS stack
+* trace inherited from `Error`.
+*/
+var UnknownSkillError = class extends AgentyxError {
+	skillName;
+	/** The stack that declared the skill, when the failure came from resolution. */
+	requiredBy;
+	knownSkills;
+	constructor(skillName, requiredBy, knownSkills) {
+		const origin = requiredBy === void 0 ? "" : ` (required by stack "${requiredBy}")`;
+		const known = knownSkills.length > 0 ? [...knownSkills].sort().join(", ") : "none";
+		super("unknown_skill", `Unknown skill "${skillName}"${origin}. Known skills: ${known}.`);
+		this.name = "UnknownSkillError";
+		this.skillName = skillName;
+		this.requiredBy = requiredBy;
+		this.knownSkills = knownSkills;
+	}
+};
+/** Raised when a registry is built from sources that reuse a skill name. */
+var DuplicateSkillError = class extends AgentyxError {
+	skillName;
+	constructor(skillName) {
+		super("duplicate_skill", `Duplicate skill definition: "${skillName}".`);
+		this.name = "DuplicateSkillError";
+		this.skillName = skillName;
+	}
+};
+/**
+* Raised when a skill exists but cannot be turned into a valid definition —
+* malformed `SKILL.md` frontmatter, a missing field, an unreadable file.
+*
+* Built-in skills ship with Agentyx, so this is a programmer error rather than
+* something a user can fix in their project.
+*/
+var InvalidSkillError = class extends AgentyxError {
+	/** Where the skill came from: a file path, or a label for an in-memory source. */
+	origin;
+	reason;
+	constructor(origin, reason, options) {
+		const detail = typeof reason === "string" ? reason : formatIssues(reason);
+		super("invalid_skill", `Invalid skill in ${origin}: ${detail}`, options);
+		this.name = "InvalidSkillError";
+		this.origin = origin;
+		this.reason = detail;
+	}
+};
+function formatIssues(error) {
+	return error.issues.map((issue) => {
+		const path = issue.path.map(String).join(".");
+		return path === "" ? issue.message : `${path}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/skill/markdown.ts
+const DELIMITER = "---";
+const BYTE_ORDER_MARK = /^\uFEFF/;
+const LINE_BREAK = /[\r\n]/;
+/**
+* A `SKILL.md` file is a frontmatter block followed by the Markdown body:
+*
+* ```md
+* ---
+* name: planning
+* description: Plan non-trivial work before editing.
+* ---
+*
+* Instructions...
+* ```
+*
+* The frontmatter is a deliberately small YAML subset — a flat block of
+* `key: value` pairs, values optionally quoted — so that core keeps depending
+* on Zod alone. Anything richer is rejected rather than guessed at.
+*
+* The body is preserved as written apart from trimming the blank lines around
+* it, and `origin` is only used to make errors readable.
+*
+* @throws {InvalidSkillError} when the frontmatter or the resulting skill is invalid.
+*/
+function parseSkillMarkdown(markdown, origin) {
+	const lines = markdown.replace(BYTE_ORDER_MARK, "").split(/\r?\n/);
+	if (lines[0]?.trim() !== DELIMITER) throw new InvalidSkillError(origin, `the file must start with a "${DELIMITER}" frontmatter line`);
+	const closing = lines.findIndex((line, index) => index > 0 && line.trim() === DELIMITER);
+	if (closing === -1) throw new InvalidSkillError(origin, `the frontmatter block is never closed with "${DELIMITER}"`);
+	const metadata = skillMetadataSchema.safeParse(parseFrontmatter(lines.slice(1, closing), origin));
+	if (!metadata.success) throw new InvalidSkillError(origin, metadata.error);
+	const skill = skillDefinitionSchema.safeParse({
+		...metadata.data,
+		content: lines.slice(closing + 1).join("\n")
+	});
+	if (!skill.success) throw new InvalidSkillError(origin, skill.error);
+	return skill.data;
+}
+/**
+* Renders a skill as canonical `SKILL.md` text — the inverse of
+* `parseSkillMarkdown`, and the single representation every consumer installs.
+*
+* Keeping this in core is what stops a provider from owning a copy of a skill
+* body: an adapter decides *where* a skill goes, never what it says.
+*
+* The output is deterministic. Frontmatter is always `name` then `description`,
+* the body is the trimmed content, and the file ends with exactly one newline,
+* so re-rendering an unchanged skill produces a byte-identical file and an
+* installer can compare content instead of guessing.
+*
+* @throws {InvalidSkillError} when the definition is invalid, or when the
+* description cannot be represented in the flat frontmatter subset the parser
+* accepts.
+*/
+function formatSkillMarkdown(skill) {
+	const origin = typeof skill.name === "string" ? `skill "${skill.name}"` : "skill definition";
+	const parsed = skillDefinitionSchema.safeParse(skill);
+	if (!parsed.success) throw new InvalidSkillError(origin, parsed.error);
+	const { name, description, content } = parsed.data;
+	if (LINE_BREAK.test(description)) throw new InvalidSkillError(origin, "the description must not contain a line break");
+	return `${DELIMITER}\nname: ${name}\ndescription: ${description}\n${DELIMITER}\n\n${content}\n`;
+}
+function parseFrontmatter(lines, origin) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const [index, line] of lines.entries()) {
+		if (line.trim() === "") continue;
+		const separator = line.indexOf(":");
+		const lineNumber = index + 2;
+		if (separator === -1) throw new InvalidSkillError(origin, `frontmatter line ${lineNumber} is not "key: value": ${line}`);
+		const key = line.slice(0, separator).trim();
+		if (key === "") throw new InvalidSkillError(origin, `frontmatter line ${lineNumber} has an empty key`);
+		if (entries.has(key)) throw new InvalidSkillError(origin, `duplicate frontmatter key "${key}" on line ${lineNumber}`);
+		entries.set(key, unquote(line.slice(separator + 1).trim()));
+	}
+	return Object.fromEntries(entries);
+}
+function unquote(value) {
+	const quoted = /^"(.*)"$|^'(.*)'$/.exec(value);
+	return quoted?.[1] ?? quoted?.[2] ?? value;
+}
+//#endregion
+//#region src/skill/registry.ts
+/**
+* Indexes skill sources by name.
+*
+* Names and duplicates are validated here; the definitions themselves are
+* validated the first time each skill is loaded.
+*
+* @throws {DuplicateSkillError} when two sources share a name.
+* @throws {InvalidSkillError} when a source name is not a valid skill name.
+*/
+function createSkillRegistry(sources) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const name = skillNameSchema.safeParse(source.name);
+		if (!name.success) throw new InvalidSkillError(`skill source "${source.name}"`, name.error);
+		if (byName.has(name.data)) throw new DuplicateSkillError(name.data);
+		byName.set(name.data, source);
+	}
+	const names = [...byName.keys()];
+	const loaded = /* @__PURE__ */ new Map();
+	return {
+		names,
+		has: (name) => byName.has(name),
+		get: (name) => {
+			const cached = loaded.get(name);
+			if (cached !== void 0) return cached;
+			const source = byName.get(name);
+			if (source === void 0) throw new UnknownSkillError(name, void 0, names);
+			const origin = `skill "${name}"`;
+			const skill = skillDefinitionSchema.safeParse(source.load());
+			if (!skill.success) throw new InvalidSkillError(origin, skill.error);
+			if (skill.data.name !== name) throw new InvalidSkillError(origin, `it declares the name "${skill.data.name}"`);
+			loaded.set(name, skill.data);
+			return skill.data;
+		}
+	};
+}
+//#endregion
+//#region src/skill/built-in.ts
+/**
+* The skills Agentyx ships with. The names are the directory names under
+* `packages/core/skills`, and knowing them without touching the filesystem is
+* what lets stack resolution validate references without reading any body.
+*/
+const builtInSkillNames = [
+	"planning",
+	"systematic-debugging",
+	"verification",
+	"typescript-modern",
+	"angular-modern"
+];
+/** The absolute path of a built-in skill's `SKILL.md`. */
+function builtInSkillPath(name) {
+	return join(BUILT_IN_SKILLS_PATH, name, "SKILL.md");
+}
+/** The registry used by default when no explicit registry is supplied. */
+const builtInSkillRegistry = createSkillRegistry(builtInSkillNames.map((name) => ({
+	name,
+	load: () => loadBuiltInSkill(name)
+})));
+/**
+* Reads one built-in `SKILL.md`.
+*
+* Reading is synchronous on purpose: the files are small package assets, they
+* are only touched when a command asks for instructions, and a synchronous read
+* keeps `SkillRegistry.get` a plain lookup instead of infecting every caller
+* with a promise.
+*/
+function loadBuiltInSkill(name) {
+	const filePath = builtInSkillPath(name);
+	let markdown;
+	try {
+		markdown = readFileSync(filePath, "utf8");
+	} catch (cause) {
+		throw new InvalidSkillError(filePath, `the file could not be read: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	return parseSkillMarkdown(markdown, filePath);
+}
+//#endregion
+//#region src/skill/resolver.ts
+/**
+* Collects the skills contributed by an already-resolved stack chain.
+*
+* Only identifiers are produced — no skill body is read — so this stays cheap
+* enough to run on every `resolve`.
+*
+* @throws {UnknownSkillError} when a stack references a skill the registry lacks.
+*/
+function collectStackSkills(resolvedStacks, stackRegistry, skillRegistry) {
+	const skills = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const stackName of resolvedStacks) for (const skillName of stackRegistry.get(stackName)?.skills ?? []) {
+		if (seen.has(skillName)) continue;
+		if (!skillRegistry.has(skillName)) throw new UnknownSkillError(skillName, stackName, skillRegistry.names);
+		seen.add(skillName);
+		skills.push(skillName);
+	}
+	return skills;
+}
+/**
+* Expands the requested stacks and returns the skills they contribute.
+*
+* The result follows the resolved stack order, then each stack's declaration
+* order, and is de-duplicated by first occurrence. Skills do not extend other
+* skills, so there is nothing further to expand.
+*
+* @throws {UnknownStackError} when a requested or inherited stack is missing.
+* @throws {CircularStackDependencyError} when stack inheritance forms a cycle.
+* @throws {UnknownSkillError} when a stack references a skill the registry lacks.
+*/
+function resolveStackSkills(requestedStacks, stackRegistry = builtInStackRegistry, skillRegistry = builtInSkillRegistry) {
+	return collectStackSkills(resolveStacks(requestedStacks, stackRegistry), stackRegistry, skillRegistry);
+}
+//#endregion
+//#region src/config/resolver.ts
+/**
+* Combines a validated project configuration with stack and skill resolution.
+* The input is never mutated.
+*
+* @throws {UnknownStackError} when a configured stack is missing.
+* @throws {CircularStackDependencyError} when inheritance forms a cycle.
+* @throws {UnknownSkillError} when a stack references an unknown skill.
+*/
+function resolveAgentyxConfig(config, registry = builtInStackRegistry, skillRegistry = builtInSkillRegistry, mcpRegistry = builtInMcpServerRegistry) {
+	const requestedStacks = [...config.extends];
+	const resolvedStacks = resolveStacks(requestedStacks, registry);
+	const declaredMcpServers = collectStackMcpServerReferences(resolvedStacks, registry, mcpRegistry);
+	return {
+		requestedStacks,
+		resolvedStacks,
+		skills: collectStackSkills(resolvedStacks, registry, skillRegistry),
+		declaredMcpServers,
+		mcpServers: filterEffectiveMcpServers(declaredMcpServers, config.profile),
+		profile: config.profile,
+		targets: [...config.targets]
+	};
+}
+//#endregion
+//#region src/meta.ts
+const agentyxCoreName = "agentyx-core";
+function getCoreStatus() {
+	return "ready";
+}
+//#endregion
+//#region src/project/detector.ts
+const PACKAGE_MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+const lockfileManagers = /* @__PURE__ */ new Map([
+	["pnpm-lock.yaml", "pnpm"],
+	["package-lock.json", "npm"],
+	["yarn.lock", "yarn"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"]
+]);
+async function detectProject(projectDir) {
+	const packageJsonPath = join(projectDir, "package.json");
+	const packageJson = await readPackageJson(packageJsonPath);
+	const packageManager = await detectPackageManager(projectDir, packageJson.data);
+	const detectedStacks = await detectStacks(projectDir, packageJson.data);
+	return {
+		projectDir,
+		packageJson: {
+			present: packageJson.present,
+			valid: packageJson.valid,
+			path: packageJsonPath,
+			name: getString(packageJson.data?.name),
+			packageManager: getString(packageJson.data?.packageManager),
+			error: packageJson.error
+		},
+		packageManager,
+		detectedStacks,
+		recommendedStack: recommendStack(detectedStacks)
+	};
+}
+function buildAgentyxConfig(input) {
+	return {
+		extends: [input.stack],
+		profile: input.profile,
+		targets: [...input.targets]
+	};
+}
+function formatAgentyxConfig(config) {
+	return `${JSON.stringify(config, null, 2)}\n`;
+}
+function recommendStack(detectedStacks) {
+	if (detectedStacks.includes("angular")) return "angular";
+	if (detectedStacks.includes("typescript")) return "typescript";
+}
+async function detectStacks(projectDir, packageJson) {
+	const stacks = [];
+	const dependencies = collectDependencies(packageJson);
+	const hasAngular = dependencies.has("@angular/core");
+	if (dependencies.has("typescript") || await exists(join(projectDir, "tsconfig.json")) || hasAngular) stacks.push("typescript");
+	if (hasAngular) stacks.push("angular");
+	return stacks;
+}
+async function detectPackageManager(projectDir, packageJson) {
+	const lockfiles = [];
+	const managers = /* @__PURE__ */ new Set();
+	for (const [file, manager] of lockfileManagers) if (await exists(join(projectDir, file))) {
+		lockfiles.push(file);
+		managers.add(manager);
+	}
+	if (managers.size === 1) return {
+		name: [...managers][0],
+		source: "lockfile",
+		lockfiles,
+		ambiguous: false
+	};
+	if (managers.size > 1) return {
+		name: void 0,
+		source: "lockfile",
+		lockfiles,
+		ambiguous: true
+	};
+	const declared = parsePackageManagerName(getString(packageJson?.packageManager));
+	return {
+		name: declared,
+		source: declared === void 0 ? void 0 : "package-json",
+		lockfiles,
+		ambiguous: false
+	};
+}
+async function readPackageJson(path) {
+	let contents;
+	try {
+		contents = await readFile(path, "utf8");
+	} catch (cause) {
+		if (isNotFound(cause)) return {
+			present: false,
+			valid: false,
+			data: void 0,
+			error: void 0
+		};
+		return {
+			present: true,
+			valid: false,
+			data: void 0,
+			error: cause instanceof Error ? cause.message : String(cause)
+		};
+	}
+	try {
+		return {
+			present: true,
+			valid: true,
+			data: JSON.parse(contents),
+			error: void 0
+		};
+	} catch (cause) {
+		return {
+			present: true,
+			valid: false,
+			data: void 0,
+			error: cause instanceof Error ? cause.message : String(cause)
+		};
+	}
+}
+function collectDependencies(packageJson) {
+	const dependencies = /* @__PURE__ */ new Set();
+	for (const field of [
+		packageJson?.dependencies,
+		packageJson?.devDependencies,
+		packageJson?.peerDependencies,
+		packageJson?.optionalDependencies
+	]) if (isRecord(field)) for (const name of Object.keys(field)) dependencies.add(name);
+	return dependencies;
+}
+function parsePackageManagerName(value) {
+	const name = value?.split("@")[0];
+	return PACKAGE_MANAGERS.includes(name) ? name : void 0;
+}
+function getString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function exists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch (cause) {
+		if (isNotFound(cause)) return false;
+		throw cause;
+	}
+}
+function isNotFound(cause) {
+	return cause instanceof Error && cause.code === "ENOENT";
+}
+//#endregion
+export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_PROFILES, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, CircularStackDependencyError, DEFAULT_AGENTYX_PROFILE, DuplicateMcpServerError, DuplicateSkillError, DuplicateStackError, InvalidMcpServerError, InvalidSkillError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, UnknownMcpServerError, UnknownSkillError, UnknownStackError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxProfileSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInMcpServerNames, builtInMcpServerRegistry, builtInSkillNames, builtInSkillRegistry, builtInStackRegistry, builtInStacks, collectStackMcpServerReferences, collectStackMcpServers, createMcpServerRegistry, createSkillRegistry, createStackRegistry, detectProject, filterEffectiveMcpServers, formatAgentyxConfig, formatSkillMarkdown, getCoreStatus, getOptimizationProfile, isMcpLevelEnabled, loadAgentyxConfig, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, optimizationProfileNames, optimizationProfiles, parseAgentyxConfig, parseSkillMarkdown, resolveAgentyxConfig, resolveStackMcpServerReferences, resolveStackMcpServers, resolveStackSkills, resolveStacks, skillDefinitionSchema, stackDefinitionSchema };
+
+//# sourceMappingURL=index.mjs.map