@agentyx/core 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -97,6 +97,30 @@ var LocalSkillDirectoryError = class extends AgentyxError {
 	}
 };
 //#endregion
+//#region src/hook/schema.ts
+const HOOK_ACTIVATION_LEVELS = ["default", "optional"];
+const hookActivationLevelSchema = z.enum(HOOK_ACTIVATION_LEVELS);
+const HOOK_EVENTS = ["SessionStart"];
+const hookEventSchema = z.enum(HOOK_EVENTS);
+const hookNameSchema = z.string().min(1, "Hook names must be non-empty strings.").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Hook names must be lowercase kebab-case, for example \"session-doctor-bootstrap\".");
+const hookDefinitionSchema = z.strictObject({
+	name: hookNameSchema.describe("Unique hook identifier."),
+	description: z.string().trim().min(1, "Hook descriptions must be non-empty strings."),
+	event: hookEventSchema.describe("The provider lifecycle event this hook runs on."),
+	command: z.string().trim().min(1, "Hook command must be a non-empty string."),
+	args: z.array(z.string()).default([])
+});
+const hookReferenceSchema = z.union([hookNameSchema, z.strictObject({
+	name: hookNameSchema.describe("Hook identifier."),
+	activation: hookActivationLevelSchema.default("default")
+})]).transform((value) => typeof value === "string" ? {
+	name: value,
+	activation: "default"
+} : value).pipe(z.strictObject({
+	name: hookNameSchema.describe("Hook identifier."),
+	activation: hookActivationLevelSchema.describe("Whether this hook is active by default or explicit opt-in.")
+}));
+//#endregion
 //#region src/mcp/schema.ts
 const MCP_CAPABILITY_LEVELS = ["default", "optional"];
 const mcpCapabilityLevelSchema = z.enum(MCP_CAPABILITY_LEVELS);
@@ -204,7 +228,8 @@ const packDefinitionSchema = z.strictObject({
 	description: z.string().min(1, "Pack descriptions must be non-empty when provided.").describe("Short human-readable summary of the pack.").optional(),
 	skills: z.array(skillNameSchema).describe("Skills this pack contributes, in declaration order.").default([]),
 	mcpServers: z.array(mcpServerReferenceSchema).describe("MCP servers this pack contributes, in declaration order.").default([]),
-	tools: z.array(toolReferenceSchema).describe("Local tools this pack contributes, in declaration order.").default([])
+	tools: z.array(toolReferenceSchema).describe("Local tools this pack contributes, in declaration order.").default([]),
+	hooks: z.array(hookReferenceSchema).describe("Provider lifecycle hooks this pack contributes, in declaration order.").default([])
 });
 //#endregion
 //#region src/source/schema.ts
@@ -434,6 +459,10 @@ const builtInPacks = [
 		tools: [{
 			name: "rtk",
 			activation: "optional"
+		}],
+		hooks: [{
+			name: "session-doctor-bootstrap",
+			activation: "default"
 		}]
 	},
 	{
@@ -641,14 +670,14 @@ var InvalidSkillError = class extends AgentyxError {
 	origin;
 	reason;
 	constructor(origin, reason, options) {
-		const detail = typeof reason === "string" ? reason : formatIssues$1(reason);
+		const detail = typeof reason === "string" ? reason : formatIssues$2(reason);
 		super("invalid_skill", `Invalid skill in ${origin}: ${detail}`, options);
 		this.name = "InvalidSkillError";
 		this.origin = origin;
 		this.reason = detail;
 	}
 };
-function formatIssues$1(error) {
+function formatIssues$2(error) {
 	return error.issues.map((issue) => {
 		const path = issue.path.map(String).join(".");
 		return path === "" ? issue.message : `${path}: ${issue.message}`;
@@ -969,13 +998,20 @@ async function loadLocalSkillSources(projectDir, directories) {
 		for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
 			if (!entry.isDirectory()) continue;
 			const filePath = join(rootRealPath, entry.name, "SKILL.md");
-			let markdown;
+			let realFilePath;
 			try {
-				markdown = await readFile(filePath, "utf8");
+				realFilePath = await realpath(filePath);
 			} catch (cause) {
 				if (cause instanceof Error && cause.code === "ENOENT") continue;
 				throw localDirectoryError(directory, `cannot read ${entry.name}/SKILL.md`, cause);
 			}
+			if (!isInside$1(realFilePath, rootRealPath)) throw new LocalSkillDirectoryError(directory, `${entry.name}/SKILL.md resolves outside the skill directory`);
+			let markdown;
+			try {
+				markdown = await readFile(realFilePath, "utf8");
+			} catch (cause) {
+				throw localDirectoryError(directory, `cannot read ${entry.name}/SKILL.md`, cause);
+			}
 			const skill = parseSkillMarkdown(markdown, filePath);
 			if (skill.name !== entry.name) throw new LocalSkillDirectoryError(directory, `${entry.name}/SKILL.md declares the name "${skill.name}"`);
 			sources.push({
@@ -994,6 +1030,148 @@ function localDirectoryError(directory, reason, cause) {
 	return new LocalSkillDirectoryError(directory, reason, cause instanceof Error ? { cause } : void 0);
 }
 //#endregion
+//#region src/hook/errors.ts
+var UnknownHookError = class extends AgentyxError {
+	hookName;
+	requiredBy;
+	knownHooks;
+	constructor(hookName, requiredBy, knownHooks) {
+		const origin = requiredBy === void 0 ? "" : ` (required by "${requiredBy}")`;
+		const known = knownHooks.length > 0 ? [...knownHooks].sort().join(", ") : "none";
+		super("unknown_hook", `Unknown hook "${hookName}"${origin}. Known hooks: ${known}.`);
+		this.name = "UnknownHookError";
+		this.hookName = hookName;
+		this.requiredBy = requiredBy;
+		this.knownHooks = knownHooks;
+	}
+};
+var DuplicateHookError = class extends AgentyxError {
+	hookName;
+	constructor(hookName) {
+		super("duplicate_hook", `Duplicate hook definition: "${hookName}".`);
+		this.name = "DuplicateHookError";
+		this.hookName = hookName;
+	}
+};
+var InvalidHookError = class extends AgentyxError {
+	origin;
+	reason;
+	constructor(origin, reason, options) {
+		const detail = typeof reason === "string" ? reason : formatIssues$1(reason);
+		super("invalid_hook", `Invalid hook in ${origin}: ${detail}`, options);
+		this.name = "InvalidHookError";
+		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/hook/registry.ts
+function createHookRegistry(sources) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const name = hookNameSchema.safeParse(source.name);
+		if (!name.success) throw new InvalidHookError(`Hook source "${source.name}"`, name.error);
+		if (byName.has(name.data)) throw new DuplicateHookError(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 UnknownHookError(name, void 0, names);
+		const origin = `Hook "${name}"`;
+		const hook = hookDefinitionSchema.safeParse(source.load());
+		if (!hook.success) throw new InvalidHookError(origin, hook.error);
+		if (hook.data.name !== name) throw new InvalidHookError(origin, `it declares the name "${hook.data.name}"`);
+		loaded.set(name, hook.data);
+		return hook.data;
+	};
+	return {
+		names,
+		has: (name) => byName.has(name),
+		listMetadata: () => names.map((name) => {
+			const hook = get(name);
+			return {
+				name: hook.name,
+				description: hook.description,
+				event: hook.event
+			};
+		}),
+		get
+	};
+}
+const builtInHookRegistry = createHookRegistry([{
+	name: "session-doctor-bootstrap",
+	load: () => ({
+		name: "session-doctor-bootstrap",
+		description: "Reports Agentyx project health at session start; silent when healthy.",
+		event: "SessionStart",
+		command: "npx",
+		args: [
+			"agentyx",
+			"doctor",
+			"--hook"
+		]
+	})
+}]);
+const builtInHookNames = builtInHookRegistry.names;
+//#endregion
+//#region src/pack/resolver.ts
+/**
+* Resolves selected packs without hidden inheritance.
+*
+* The result preserves configured order, removes duplicates by first
+* occurrence, and validates every requested pack.
+*
+* @throws {UnknownPackError} when a requested pack is missing.
+*/
+function resolvePacks(requestedPacks, registry = builtInPackRegistry) {
+	const resolved = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of requestedPacks) {
+		if (seen.has(name)) continue;
+		if (!registry.has(name)) throw new UnknownPackError(name, void 0, [...registry.keys()]);
+		seen.add(name);
+		resolved.push(name);
+	}
+	return resolved;
+}
+//#endregion
+//#region src/hook/resolver.ts
+function collectPackHookReferences(resolvedPacks, packRegistry, hookRegistry) {
+	const hooks = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const packName of resolvedPacks) for (const hook of packRegistry.get(packName)?.hooks ?? []) {
+		const hookName = hook.name;
+		if (seen.has(hookName)) continue;
+		if (!hookRegistry.has(hookName)) throw new UnknownHookError(hookName, packName, hookRegistry.names);
+		seen.add(hookName);
+		hooks.push(hook);
+	}
+	return hooks;
+}
+function filterEffectiveHooks(hooks, enabledCapabilities) {
+	const enabled = new Set(enabledCapabilities);
+	return hooks.filter((hook) => hook.activation === "default" || enabled.has(hook.name)).map((hook) => hook.name);
+}
+function collectPackHooks(resolvedPacks, packRegistry, hookRegistry, enabledCapabilities = []) {
+	return filterEffectiveHooks(collectPackHookReferences(resolvedPacks, packRegistry, hookRegistry), enabledCapabilities);
+}
+function resolvePackHookReferences(requestedPacks, packRegistry = builtInPackRegistry, hookRegistry = builtInHookRegistry) {
+	return collectPackHookReferences(resolvePacks(requestedPacks, packRegistry), packRegistry, hookRegistry);
+}
+function resolvePackHooks(requestedPacks, packRegistry = builtInPackRegistry, hookRegistry = builtInHookRegistry, enabledCapabilities = []) {
+	return collectPackHooks(resolvePacks(requestedPacks, packRegistry), packRegistry, hookRegistry, enabledCapabilities);
+}
+//#endregion
 //#region src/mcp/errors.ts
 var UnknownMcpServerError = class extends AgentyxError {
 	serverName;
@@ -1151,27 +1329,6 @@ const builtInMcpServerRegistry = createMcpServerRegistry([
 ]);
 const builtInMcpServerNames = builtInMcpServerRegistry.names;
 //#endregion
-//#region src/pack/resolver.ts
-/**
-* Resolves selected packs without hidden inheritance.
-*
-* The result preserves configured order, removes duplicates by first
-* occurrence, and validates every requested pack.
-*
-* @throws {UnknownPackError} when a requested pack is missing.
-*/
-function resolvePacks(requestedPacks, registry = builtInPackRegistry) {
-	const resolved = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const name of requestedPacks) {
-		if (seen.has(name)) continue;
-		if (!registry.has(name)) throw new UnknownPackError(name, void 0, [...registry.keys()]);
-		seen.add(name);
-		resolved.push(name);
-	}
-	return resolved;
-}
-//#endregion
 //#region src/mcp/resolver.ts
 function collectPackMcpServerReferences(resolvedPacks, packRegistry, mcpRegistry) {
 	const servers = [];
@@ -1347,12 +1504,17 @@ function resolvePackTools(requestedPacks, packRegistry = builtInPackRegistry, to
 * @throws {UnknownPackError} when a configured pack is missing.
 * @throws {UnknownSkillError} when a pack references an unknown skill.
 */
-function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegistry = builtInSkillRegistry, mcpRegistry = builtInMcpServerRegistry, toolRegistry = builtInToolRegistry) {
+function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegistry = builtInSkillRegistry, mcpRegistry = builtInMcpServerRegistry, toolRegistry = builtInToolRegistry, hookRegistry = builtInHookRegistry) {
 	const requestedPacks = [...config.packs];
 	const resolvedPacks = resolvePacks(requestedPacks, registry);
 	const declaredMcpServers = collectPackMcpServerReferences(resolvedPacks, registry, mcpRegistry);
 	const declaredTools = collectPackToolReferences(resolvedPacks, registry, toolRegistry);
-	const knownOptionalCapabilities = [...declaredMcpServers.filter((server) => server.activation === "optional").map((server) => server.name), ...declaredTools.filter((tool) => tool.activation === "optional").map((tool) => tool.name)];
+	const declaredHooks = collectPackHookReferences(resolvedPacks, registry, hookRegistry);
+	const knownOptionalCapabilities = [
+		...declaredMcpServers.filter((server) => server.activation === "optional").map((server) => server.name),
+		...declaredTools.filter((tool) => tool.activation === "optional").map((tool) => tool.name),
+		...declaredHooks.filter((hook) => hook.activation === "optional").map((hook) => hook.name)
+	];
 	for (const capability of config.enable) if (!knownOptionalCapabilities.includes(capability)) throw new UnknownEnabledCapabilityError(capability, knownOptionalCapabilities);
 	return {
 		requestedPacks,
@@ -1362,6 +1524,8 @@ function resolveAgentyxConfig(config, registry = builtInPackRegistry, skillRegis
 		mcpServers: filterEffectiveMcpServers(declaredMcpServers, config.enable),
 		declaredTools,
 		tools: filterEffectiveTools(declaredTools, config.enable),
+		declaredHooks,
+		hooks: filterEffectiveHooks(declaredHooks, config.enable),
 		enabled: [...config.enable],
 		targets: [...config.targets]
 	};
@@ -1440,7 +1604,26 @@ const mcpManifestEntrySchema = z.strictObject({
 	hash: contentHashSchema,
 	created: z.boolean()
 });
-const installManifestEntrySchema = z.discriminatedUnion("kind", [skillManifestEntrySchema, mcpManifestEntrySchema]);
+/**
+* A provider hook configuration file Agentyx contributed entries to.
+*
+* Shares the `mcp` entry's shape and rationale: the file is shared with the
+* user, so the entry records the hook names Agentyx added rather than
+* claiming the whole document.
+*/
+const hookManifestEntrySchema = z.strictObject({
+	kind: z.literal("hook"),
+	path: managedPathSchema,
+	hooks: z.array(z.string().min(1, "Hook names must be non-empty strings.")),
+	targets: targetsSchema,
+	hash: contentHashSchema,
+	created: z.boolean()
+});
+const installManifestEntrySchema = z.discriminatedUnion("kind", [
+	skillManifestEntrySchema,
+	mcpManifestEntrySchema,
+	hookManifestEntrySchema
+]);
 /** The `.agentyx.lock.json` record of everything Agentyx installed into a project. */
 const installManifestSchema = z.strictObject({
 	version: z.literal(1),
@@ -1517,13 +1700,21 @@ async function loadInstallManifest(projectPath = process.cwd()) {
 * touches the filesystem.
 */
 function formatInstallManifest(manifest) {
-	const entries = [...manifest.entries].map((entry) => entry.kind === "skill" ? {
-		...entry,
-		targets: sorted(entry.targets)
-	} : {
-		...entry,
-		targets: sorted(entry.targets),
-		servers: sorted(entry.servers)
+	const entries = [...manifest.entries].map((entry) => {
+		if (entry.kind === "skill") return {
+			...entry,
+			targets: sorted(entry.targets)
+		};
+		if (entry.kind === "mcp") return {
+			...entry,
+			targets: sorted(entry.targets),
+			servers: sorted(entry.servers)
+		};
+		return {
+			...entry,
+			targets: sorted(entry.targets),
+			hooks: sorted(entry.hooks)
+		};
 	}).sort((left, right) => left.path.localeCompare(right.path));
 	return `${JSON.stringify({
 		version: manifest.version,
@@ -1792,6 +1983,6 @@ function trustedSourceLoadError(sourceName, reason, cause) {
 	return new TrustedSourceLoadError(sourceName, reason, cause instanceof Error ? { cause } : void 0);
 }
 //#endregion
-export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_MANIFEST_FILENAME, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, AgentyxManifestParseError, AgentyxManifestValidationError, CircularPackDependencyError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, DuplicateTrustedSourceError, INSTALL_MANIFEST_VERSION, InvalidMcpServerError, InvalidSkillError, InvalidToolError, LocalSkillDirectoryError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, TOOL_ACTIVATION_LEVELS, TrustedSourceLoadError, UnknownEnabledCapabilityError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, UnknownTrustedSourceError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxManifestPath, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, codexPluginManifestSchema, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, createTrustedSourceRegistry, detectProject, emptyInstallManifest, enabledCapabilityNameSchema, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatInstallManifest, formatSkillMarkdown, getCoreStatus, getTrustedSourceDefinition, hashContent, inspectTrustedSource, installManifestEntrySchema, installManifestSchema, knownTrustedSourceRegistry, knownTrustedSources, loadAgentyxConfig, loadAgentyxProject, loadInstallManifest, manifestEntriesByPath, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpManifestEntrySchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseInstallManifest, parseSkillMarkdown, resolveAgentyxConfig, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, skillDefinitionSchema, skillDirectorySchema, skillManifestEntrySchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema, trustedSourceDefinitionSchema, trustedSourceNameSchema, trustedSourcePathSchema, trustedSourceReferenceSchema, trustedSourceSkillSummarySchema };
+export { AGENTYX_CONFIG_FILENAME, AGENTYX_CONFIG_SCHEMA_ID, AGENTYX_MANIFEST_FILENAME, AgentyxConfigNotFoundError, AgentyxConfigParseError, AgentyxConfigValidationError, AgentyxError, AgentyxManifestParseError, AgentyxManifestValidationError, CircularPackDependencyError, DuplicateHookError, DuplicateMcpServerError, DuplicatePackError, DuplicateSkillError, DuplicateToolError, DuplicateTrustedSourceError, HOOK_ACTIVATION_LEVELS, HOOK_EVENTS, INSTALL_MANIFEST_VERSION, InvalidHookError, InvalidMcpServerError, InvalidSkillError, InvalidToolError, LocalSkillDirectoryError, MCP_CAPABILITY_LEVELS, MCP_CONTEXT_COSTS, PACKAGE_MANAGERS, PACK_CATEGORIES, TOOL_ACTIVATION_LEVELS, TrustedSourceLoadError, UnknownEnabledCapabilityError, UnknownHookError, UnknownMcpServerError, UnknownPackError, UnknownSkillError, UnknownToolError, UnknownTrustedSourceError, agentyxConfigPath, agentyxConfigSchema, agentyxCoreName, agentyxManifestPath, agentyxTargetSchema, buildAgentyxConfig, buildAgentyxConfigJsonSchema, builtInHookNames, builtInHookRegistry, builtInMcpServerNames, builtInMcpServerRegistry, builtInPackRegistry, builtInPacks, builtInSkillNames, builtInSkillRegistry, builtInToolNames, builtInToolRegistry, codexPluginManifestSchema, collectPackHookReferences, collectPackHooks, collectPackMcpServerReferences, collectPackMcpServers, collectPackToolReferences, createHookRegistry, createMcpServerRegistry, createPackRegistry, createSkillRegistry, createToolRegistry, createTrustedSourceRegistry, detectProject, emptyInstallManifest, enabledCapabilityNameSchema, filterEffectiveHooks, filterEffectiveMcpServers, filterEffectiveTools, formatAgentyxConfig, formatInstallManifest, formatSkillMarkdown, getCoreStatus, getTrustedSourceDefinition, hashContent, hookActivationLevelSchema, hookDefinitionSchema, hookEventSchema, hookManifestEntrySchema, hookNameSchema, hookReferenceSchema, inspectTrustedSource, installManifestEntrySchema, installManifestSchema, knownTrustedSourceRegistry, knownTrustedSources, loadAgentyxConfig, loadAgentyxProject, loadInstallManifest, manifestEntriesByPath, mcpCapabilityLevelSchema, mcpContextCostSchema, mcpEnvReferenceSchema, mcpManifestEntrySchema, mcpServerDefinitionSchema, mcpServerReferenceSchema, packCategorySchema, packDefinitionSchema, packNameSchema, parseAgentyxConfig, parseInstallManifest, parseSkillMarkdown, resolveAgentyxConfig, resolvePackHookReferences, resolvePackHooks, resolvePackMcpServerReferences, resolvePackMcpServers, resolvePackSkills, resolvePackToolReferences, resolvePackTools, resolvePacks, skillDefinitionSchema, skillDirectorySchema, skillManifestEntrySchema, toolActivationLevelSchema, toolDefinitionSchema, toolNameSchema, toolReferenceSchema, trustedSourceDefinitionSchema, trustedSourceNameSchema, trustedSourcePathSchema, trustedSourceReferenceSchema, trustedSourceSkillSummarySchema };
 
 //# sourceMappingURL=index.mjs.map