@caplets/core 0.18.3 → 0.18.5

package/dist/native/process-cleanup.d.ts

@@ -1,2 +1,5 @@
 import type { NativeCapletsService } from "./service";
-export declare function registerNativeCapletsProcessCleanup(service: NativeCapletsService): void;
+export type NativeCapletsProcessCleanupOptions = {
+    writeErr?: (message: string) => void;
+};
+export declare function registerNativeCapletsProcessCleanup(service: NativeCapletsService, options?: NativeCapletsProcessCleanupOptions): void;

package/dist/native/service.d.ts

@@ -1,6 +1,7 @@
 import type { NativeCapletsServiceResolutionInput } from "./options";
 import { resolveNativeCapletsServiceOptions } from "./options";
 import { type RemoteCapletsClient } from "./remote";
+import { type CapletsConfig } from "../config";
 import { generatedToolInputJsonSchemaForCaplet } from "../generated-tool-input-schema";
 export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput & {
     configPath?: string;
@@ -12,6 +13,7 @@ export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput &
     remoteClientFactory?: (options: Extract<ReturnType<typeof resolveNativeCapletsServiceOptions>, {
         mode: "remote";
     }>["remote"]) => RemoteCapletsClient;
+    localServiceFactory?: (options: LocalNativeCapletsServiceOptions) => NativeCapletsService;
 };
 export type NativeCapletTool = {
     caplet: string;
@@ -31,3 +33,7 @@ export type NativeCapletsService = {
     close(): Promise<void>;
 };
 export declare function createNativeCapletsService(options?: NativeCapletsServiceOptions): NativeCapletsService;
+type LocalNativeCapletsServiceOptions = NativeCapletsServiceOptions & {
+    configLoader?: (configPath: string, projectConfigPath: string) => CapletsConfig;
+};
+export {};

package/dist/native.d.ts

@@ -1,5 +1,5 @@
 export { createNativeCapletsService, type NativeCapletTool, type NativeCapletsService, type NativeCapletsServiceOptions, type NativeCapletsToolsChangedListener, } from "./native/service";
-export { registerNativeCapletsProcessCleanup } from "./native/process-cleanup";
+export { registerNativeCapletsProcessCleanup, type NativeCapletsProcessCleanupOptions, } from "./native/process-cleanup";
 export { nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, } from "./native/tools";
 export { generatedToolInputSchema } from "./tools";
 export { generatedToolInputJsonSchema } from "./generated-tool-input-schema";

package/dist/native.js

@@ -1,4 +1,4 @@
-import { Ot as CapletsError, Q as ToolListChangedNotificationSchema, _ as StreamableHTTPClientTransport, a as resolveCapletsServer, b as Client, i as resolveCapletsMode, l as capabilityDescription, n as mcpUrlForBase, o as CapletsEngine } from "./options-j9p3L3r1.js";
+import { Q as ToolListChangedNotificationSchema, _ as StreamableHTTPClientTransport, a as resolveCapletsServer, b as Client, bt as parseConfig, i as resolveCapletsMode, jt as CapletsError, l as capabilityDescription, n as mcpUrlForBase, o as CapletsEngine, vt as loadLocalOverlayConfigWithSources } from "./options-BlNyqF_E.js";
 import { a as generatedToolInputJsonSchemaForCaplet, i as generatedToolInputJsonSchema, l as operations, o as generatedToolInputSchema } from "./generated-tool-input-schema-BYoyY-l-.js";
 //#region src/native/options.ts
 const DEFAULT_POLL_INTERVAL_MS = 3e4;
@@ -155,10 +155,10 @@ var RemoteNativeCapletsService = class {
 				await this.reloadFromClient();
 				return !this.closed;
 			} catch (retryError) {
-				this.warn(`Could not reload remote Caplets tools: ${errorMessage(retryError)}\n`);
+				this.warn(`Could not reload remote Caplets tools: ${errorMessage$2(retryError)}\n`);
 				return false;
 			}
-			this.warn(`Could not reload remote Caplets tools: ${errorMessage(error)}\n`);
+			this.warn(`Could not reload remote Caplets tools: ${errorMessage$2(error)}\n`);
 			return false;
 		}
 	}
@@ -213,11 +213,7 @@ var RemoteNativeCapletsService = class {
 		for (const listener of this.listeners) listener(tools);
 	}
 	warn(message) {
-		if (this.options.writeErr) {
-			this.options.writeErr(message);
-			return;
-		}
-		process.stderr.write(message);
+		this.options.writeErr?.(message);
 	}
 };
 function remoteToolToNativeTool(tool) {
@@ -248,14 +244,14 @@ function operationNamesFromSchema(schema) {
 function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function errorMessage(error) {
+function errorMessage$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function remoteAuthError() {
 	return new CapletsError("AUTH_FAILED", "Remote Caplets authentication failed; check CAPLETS_SERVER_USER and CAPLETS_SERVER_PASSWORD.");
 }
 function isSessionFailure(error) {
-	const message = errorMessage(error).toLowerCase();
+	const message = errorMessage$2(error).toLowerCase();
 	return /session|transport|connection|connect|closed|invalid/u.test(message);
 }
 function isAuthFailure(error) {
@@ -264,24 +260,42 @@ function isAuthFailure(error) {
 	const statusCode = typeof candidate?.statusCode === "number" ? candidate.statusCode : void 0;
 	const code = typeof candidate?.code === "number" ? candidate.code : void 0;
 	if (status === 401 || status === 403 || statusCode === 401 || statusCode === 403 || code === 401 || code === 403) return true;
-	return /\b(401|403|unauthorized|forbidden)\b/iu.test(errorMessage(error));
+	return /\b(401|403|unauthorized|forbidden)\b/iu.test(errorMessage$2(error));
 }
 //#endregion
 //#region src/native/service.ts
 function createNativeCapletsService(options = {}) {
 	const resolved = resolveNativeCapletsServiceOptions(options);
-	if (resolved.mode === "remote") return new RemoteNativeCapletsService({
-		client: (options.remoteClientFactory ?? createSdkRemoteCapletsClient)(resolved.remote),
-		clientFactory: () => (options.remoteClientFactory ?? createSdkRemoteCapletsClient)(resolved.remote),
-		pollIntervalMs: resolved.remote.pollIntervalMs,
-		...options.writeErr ? { writeErr: options.writeErr } : {}
-	});
+	if (resolved.mode === "remote") {
+		const localOptions = {
+			...options,
+			mode: "local",
+			configLoader: createLocalOverlayConfigLoader(options)
+		};
+		const local = (options.localServiceFactory ?? createDefaultNativeCapletsService)(localOptions);
+		try {
+			return new CompositeNativeCapletsService(new RemoteNativeCapletsService({
+				client: (options.remoteClientFactory ?? createSdkRemoteCapletsClient)(resolved.remote),
+				clientFactory: () => (options.remoteClientFactory ?? createSdkRemoteCapletsClient)(resolved.remote),
+				pollIntervalMs: resolved.remote.pollIntervalMs,
+				...options.writeErr ? { writeErr: options.writeErr } : {}
+			}), local, options);
+		} catch (error) {
+			local.close().catch((closeError) => {
+				writeErr(options, `Could not close local overlay Caplets service: ${errorMessage$1(closeError)}\n`);
+			});
+			throw error;
+		}
+	}
 	return new DefaultNativeCapletsService(options);
 }
 var DefaultNativeCapletsService = class {
 	engine;
 	constructor(options) {
-		this.engine = new CapletsEngine(options);
+		this.engine = new CapletsEngine({
+			...options,
+			writeErr: options.writeErr ?? (() => void 0)
+		});
 	}
 	listTools() {
 		return this.engine.enabledServers().map((caplet) => {
@@ -311,9 +325,111 @@ var DefaultNativeCapletsService = class {
 		await this.engine.close();
 	}
 };
+function createDefaultNativeCapletsService(options) {
+	return new DefaultNativeCapletsService(options);
+}
+var CompositeNativeCapletsService = class {
+	remote;
+	local;
+	options;
+	listeners = /* @__PURE__ */ new Set();
+	unsubscribers;
+	tools = [];
+	closed = false;
+	batchingReload = false;
+	constructor(remote, local, options) {
+		this.remote = remote;
+		this.local = local;
+		this.options = options;
+		this.unsubscribers = [this.remote.onToolsChanged(() => this.updateMergedTools()), this.local.onToolsChanged(() => this.updateMergedTools())];
+		this.tools = this.mergeTools();
+	}
+	listTools() {
+		return [...this.tools];
+	}
+	async execute(capletId, request) {
+		if (this.local.listTools().some((tool) => tool.caplet === capletId)) return await this.local.execute(capletId, request);
+		return await this.remote.execute(capletId, request);
+	}
+	async reload() {
+		if (this.closed) return false;
+		this.batchingReload = true;
+		const remoteReloaded = await this.reloadChild(this.remote, "remote");
+		const localReloaded = await this.reloadChild(this.local, "local overlay");
+		this.batchingReload = false;
+		if (remoteReloaded === void 0 || localReloaded === void 0) return false;
+		this.updateMergedTools();
+		return remoteReloaded || localReloaded;
+	}
+	onToolsChanged(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const unsubscribe of this.unsubscribers.splice(0)) unsubscribe();
+		this.listeners.clear();
+		await Promise.all([this.remote.close(), this.local.close()]);
+	}
+	updateMergedTools() {
+		if (this.closed || this.batchingReload) return;
+		const tools = this.mergeTools();
+		if (JSON.stringify(tools) === JSON.stringify(this.tools)) return;
+		this.tools = tools;
+		for (const listener of this.listeners) try {
+			listener(this.listTools());
+		} catch (error) {
+			writeErr(this.options, `Caplets tools-changed listener failed: ${errorMessage$1(error)}\n`);
+		}
+	}
+	mergeTools() {
+		const localTools = this.local.listTools();
+		const localIds = new Set(localTools.map((tool) => tool.caplet));
+		return [...this.remote.listTools().filter((tool) => !localIds.has(tool.caplet)), ...localTools];
+	}
+	async reloadChild(service, label) {
+		try {
+			return await service.reload();
+		} catch (error) {
+			writeErr(this.options, `Could not reload composite Caplets tools from ${label}: ${errorMessage$1(error)}\n`);
+			return;
+		}
+	}
+};
+function createLocalOverlayConfigLoader(options) {
+	let hasLoaded = false;
+	let previousWarnings = /* @__PURE__ */ new Set();
+	return (configPath, projectConfigPath) => {
+		let result;
+		try {
+			result = loadLocalOverlayConfigWithSources(configPath, projectConfigPath);
+		} catch (error) {
+			writeErr(options, `Caplets local overlay warning: Could not load local overlay config: ${errorMessage$1(error)}\n`);
+			if (hasLoaded) throw new CapletsError("CONFIG_INVALID", "Caplets local overlay reload failed; keeping last known-good config.", error);
+			hasLoaded = true;
+			return parseConfig({});
+		}
+		for (const warning of result.warnings) writeErr(options, `Caplets local overlay warning${typeof warning.path === "string" ? ` at ${warning.path}` : ""}: ${warning.message}\n`);
+		const warnings = new Set(result.warnings.map(warningKey));
+		if (hasLoaded && [...warnings].some((warning) => !previousWarnings.has(warning))) throw new CapletsError("CONFIG_INVALID", "Caplets local overlay reload produced new warnings; keeping last known-good config.");
+		previousWarnings = warnings;
+		hasLoaded = true;
+		return result.config;
+	};
+}
+function warningKey(warning) {
+	return `${warning.kind}\0${warning.path}\0${warning.message}`;
+}
+function writeErr(options, message) {
+	options.writeErr?.(message);
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region src/native/process-cleanup.ts
-function registerNativeCapletsProcessCleanup(service) {
+function registerNativeCapletsProcessCleanup(service, options = {}) {
 	let closed = false;
 	const close = async () => {
 		if (closed) return;
@@ -321,7 +437,7 @@ function registerNativeCapletsProcessCleanup(service) {
 		try {
 			await service.close();
 		} catch (error) {
-			console.error("Failed to close Caplets service:", error);
+			options.writeErr?.(`Failed to close Caplets service: ${errorMessage(error)}\n`);
 			process.exitCode = 1;
 		}
 	};
@@ -337,5 +453,8 @@ function registerNativeCapletsProcessCleanup(service) {
 	process.once("SIGINT", closeAndExit);
 	process.once("SIGTERM", closeAndExit);
 }
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 export { RemoteNativeCapletsService, createNativeCapletsService, createSdkRemoteCapletsClient, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, registerNativeCapletsProcessCleanup, resolveNativeCapletsServiceOptions };

package/dist/{options-j9p3L3r1.js → options-BlNyqF_E.js}

@@ -8380,6 +8380,82 @@ function loadCapletFilesWithPaths(root) {
 		paths
 	} : void 0;
 }
+function loadCapletFilesWithPathsBestEffort(root) {
+	if (!existsSync(root)) return;
+	const warnings = [];
+	return buildCapletFileLoadResult(root, discoverCapletFilesBestEffort(root, warnings), warnings);
+}
+function buildCapletFileLoadResult(root, candidates, warnings) {
+	const servers = {};
+	const openapiEndpoints = {};
+	const graphqlEndpoints = {};
+	const httpApis = {};
+	const cliTools = {};
+	const capletSets = {};
+	const paths = {};
+	function hasId(id) {
+		return Boolean(servers[id] || openapiEndpoints[id] || graphqlEndpoints[id] || httpApis[id] || cliTools[id] || capletSets[id]);
+	}
+	for (const candidate of candidates) {
+		if (hasId(candidate.id)) {
+			const message = `Duplicate Caplet ID ${candidate.id} under ${root}`;
+			if (!warnings) throw new CapletsError("CONFIG_INVALID", message);
+			warnings.push({
+				path: candidate.path,
+				message: `${message}; skipping duplicate at ${candidate.path}`
+			});
+			continue;
+		}
+		let config;
+		try {
+			config = readCapletFile(candidate.path);
+		} catch (error) {
+			if (!warnings) throw error;
+			warnings.push({
+				path: candidate.path,
+				message: `Skipping invalid Caplet file at ${candidate.path}: ${errorMessage$1(error)}`
+			});
+			continue;
+		}
+		paths[candidate.id] = candidate.path;
+		if (isPlainObject$5(config) && config.backend === "openapi") {
+			const { backend: _backend, ...endpoint } = config;
+			openapiEndpoints[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "graphql") {
+			const { backend: _backend, ...endpoint } = config;
+			graphqlEndpoints[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "http") {
+			const { backend: _backend, ...endpoint } = config;
+			httpApis[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "cli") {
+			const { backend: _backend, ...endpoint } = config;
+			cliTools[candidate.id] = endpoint;
+		} else if (isPlainObject$5(config) && config.backend === "caplets") {
+			const { backend: _backend, ...endpoint } = config;
+			capletSets[candidate.id] = endpoint;
+		} else servers[candidate.id] = config;
+	}
+	const hasServers = Object.keys(servers).length > 0;
+	const hasOpenApi = Object.keys(openapiEndpoints).length > 0;
+	const hasGraphQl = Object.keys(graphqlEndpoints).length > 0;
+	const hasHttpApis = Object.keys(httpApis).length > 0;
+	const hasCliTools = Object.keys(cliTools).length > 0;
+	const hasCapletSets = Object.keys(capletSets).length > 0;
+	const config = {
+		...hasServers ? { mcpServers: servers } : {},
+		...hasOpenApi ? { openapiEndpoints } : {},
+		...hasGraphQl ? { graphqlEndpoints } : {},
+		...hasHttpApis ? { httpApis } : {},
+		...hasCliTools ? { cliTools } : {},
+		...hasCapletSets ? { capletSets } : {}
+	};
+	if (!(Object.keys(config).length > 0) && warnings?.length === 0) return;
+	return {
+		config,
+		paths,
+		warnings: warnings ?? []
+	};
+}
 function discoverCapletFiles(root) {
 	const entries = readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
 	const candidates = [];
@@ -8404,6 +8480,82 @@ function discoverCapletFiles(root) {
 	}
 	return candidates;
 }
+function discoverCapletFilesBestEffort(root, warnings) {
+	const entries = readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+	const byId = /* @__PURE__ */ new Map();
+	const duplicateIds = /* @__PURE__ */ new Set();
+	function addCandidate(id, path, isDirectoryCaplet) {
+		try {
+			validateCapletId(id, path);
+		} catch (error) {
+			warnings.push({
+				path,
+				message: `Skipping invalid Caplet file at ${path}: ${errorMessage$1(error)}`
+			});
+			return;
+		}
+		if (duplicateIds.has(id)) {
+			warnings.push({
+				path,
+				message: `Duplicate Caplet ID ${id} under ${root}; skipping duplicate at ${path}`
+			});
+			return;
+		}
+		const existing = byId.get(id);
+		if (!existing) {
+			byId.set(id, {
+				id,
+				path,
+				isDirectoryCaplet
+			});
+			return;
+		}
+		if (isDirectoryCaplet && !existing.isDirectoryCaplet) {
+			warnings.push({
+				path: existing.path,
+				message: `Caplet file at ${existing.path} was shadowed by ${path}`
+			});
+			byId.set(id, {
+				id,
+				path,
+				isDirectoryCaplet
+			});
+			return;
+		}
+		if (!isDirectoryCaplet && existing.isDirectoryCaplet) {
+			warnings.push({
+				path,
+				message: `Caplet file at ${path} was shadowed by ${existing.path}`
+			});
+			return;
+		}
+		warnings.push({
+			path,
+			message: `Duplicate Caplet ID ${id} under ${root}; skipping ${existing.path} and ${path}`
+		});
+		byId.delete(id);
+		duplicateIds.add(id);
+	}
+	for (const entry of entries) {
+		if (entry.name === "auth" || entry.name === "config.json") continue;
+		const path = join(root, entry.name);
+		if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
+			addCandidate(basename(entry.name, extname(entry.name)), path, false);
+			continue;
+		}
+		if (entry.isDirectory()) {
+			const capletPath = join(path, "CAPLET.md");
+			if (existsSync(capletPath) && statSync(capletPath).isFile()) addCandidate(entry.name, capletPath, true);
+		}
+	}
+	return Array.from(byId.values()).map(({ id, path }) => ({
+		id,
+		path
+	}));
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function readCapletFile(path) {
 	if (statSync(path).size > MAX_CAPLET_FILE_BYTES) throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} exceeds the ${MAX_CAPLET_FILE_BYTES} byte limit`);
 	const { frontmatter, body } = parseFrontmatter(readFileSync(path, "utf8"), path);
@@ -9084,35 +9236,78 @@ function loadConfigWithSources(path = resolveConfigPath(), projectPath = resolve
 	const projectConfig = hasProjectConfig ? rejectProjectConfigExecutableBackendMaps(readPublicConfigInput(projectPath), projectPath) : void 0;
 	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath(projectPath);
 	const projectCaplets = projectCapletsRoot ? loadCapletFilesWithPaths(projectCapletsRoot) : void 0;
-	if (!hasUserConfig && !hasProjectConfig && !userCaplets && !projectCaplets) throw new CapletsError("CONFIG_NOT_FOUND", `Caplets config not found at ${path} or ${projectPath}`);
-	try {
-		const { input, sources, shadows } = mergeConfigInputsWithSources({
+	return buildConfigWithSources([
+		{
 			input: userConfig,
 			source: {
 				kind: "global-config",
 				path
 			}
-		}, userCaplets ? {
+		},
+		userCaplets ? {
 			input: userCaplets.config,
 			source: {
 				kind: "global-file",
 				path: userCaplets.paths
 			}
-		} : void 0, {
+		} : void 0,
+		{
 			input: projectConfig,
 			source: {
 				kind: "project-config",
 				path: projectPath
 			}
-		}, projectCaplets ? {
+		},
+		projectCaplets ? {
 			input: projectCaplets.config,
 			source: {
 				kind: "project-file",
 				path: projectCaplets.paths
 			}
-		} : void 0);
+		} : void 0
+	], `Caplets config not found at ${path} or ${projectPath}`, "Caplets config must define at least one MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, CLI tools backend, or Caplet set");
+}
+function loadGlobalConfig(path = resolveConfigPath()) {
+	const userConfig = existsSync(path) ? readPublicConfigInput(path) : void 0;
+	const userCaplets = loadCapletFilesWithPaths(resolveCapletsRoot(path));
+	return buildConfigWithSources([{
+		input: userConfig,
+		source: {
+			kind: "global-config",
+			path
+		}
+	}, userCaplets ? {
+		input: userCaplets.config,
+		source: {
+			kind: "global-file",
+			path: userCaplets.paths
+		}
+	} : void 0], `Caplets user config not found at ${path}`, void 0).config;
+}
+function loadProjectConfig(projectPath = resolveProjectConfigPath()) {
+	const projectConfig = existsSync(projectPath) ? rejectProjectConfigExecutableBackendMaps(readPublicConfigInput(projectPath), projectPath) : void 0;
+	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath(projectPath);
+	const projectCaplets = projectCapletsRoot ? loadCapletFilesWithPaths(projectCapletsRoot) : void 0;
+	return buildConfigWithSources([{
+		input: projectConfig,
+		source: {
+			kind: "project-config",
+			path: projectPath
+		}
+	}, projectCaplets ? {
+		input: projectCaplets.config,
+		source: {
+			kind: "project-file",
+			path: projectCaplets.paths
+		}
+	} : void 0], `Caplets project config not found at ${projectPath}`, void 0).config;
+}
+function buildConfigWithSources(inputs, notFoundMessage, emptyMessage) {
+	if (!inputs.some((entry) => entry?.input !== void 0)) throw new CapletsError("CONFIG_NOT_FOUND", notFoundMessage);
+	try {
+		const { input, sources, shadows } = mergeConfigInputsWithSources(...inputs);
 		const config = parseConfig(input);
-		if (Object.keys(config.mcpServers).length === 0 && Object.keys(config.openapiEndpoints).length === 0 && Object.keys(config.graphqlEndpoints).length === 0 && Object.keys(config.httpApis).length === 0 && Object.keys(config.cliTools).length === 0 && Object.keys(config.capletSets).length === 0) throw new CapletsError("CONFIG_INVALID", "Caplets config must define at least one MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, CLI tools backend, or Caplet set");
+		if (emptyMessage && Object.keys(config.mcpServers).length === 0 && Object.keys(config.openapiEndpoints).length === 0 && Object.keys(config.graphqlEndpoints).length === 0 && Object.keys(config.httpApis).length === 0 && Object.keys(config.cliTools).length === 0 && Object.keys(config.capletSets).length === 0) throw new CapletsError("CONFIG_INVALID", emptyMessage);
 		return {
 			config,
 			sources,
@@ -9123,6 +9318,74 @@ function loadConfigWithSources(path = resolveConfigPath(), projectPath = resolve
 		throw new CapletsError("CONFIG_INVALID", "Caplets config is not valid JSON", redactSecrets(error));
 	}
 }
+function loadLocalOverlayConfigWithSources(path = resolveConfigPath(), projectPath = resolveProjectConfigPath()) {
+	const warnings = [];
+	const userConfig = existsSync(path) ? readBestEffortConfigInput(path, "global-config", warnings) : void 0;
+	const userCaplets = loadBestEffortCapletFiles(resolveCapletsRoot(path), "global-file", warnings);
+	const projectConfig = existsSync(projectPath) ? readBestEffortConfigInput(projectPath, "project-config", warnings, (input) => rejectProjectConfigExecutableBackendMaps(input, projectPath)) : void 0;
+	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath(projectPath);
+	const projectCaplets = projectCapletsRoot ? loadBestEffortCapletFiles(projectCapletsRoot, "project-file", warnings) : void 0;
+	const { input, sources, shadows } = mergeConfigInputsWithSources({
+		input: userConfig,
+		source: {
+			kind: "global-config",
+			path
+		}
+	}, userCaplets ? {
+		input: userCaplets.config,
+		source: {
+			kind: "global-file",
+			path: userCaplets.paths
+		}
+	} : void 0, {
+		input: projectConfig,
+		source: {
+			kind: "project-config",
+			path: projectPath
+		}
+	}, projectCaplets ? {
+		input: projectCaplets.config,
+		source: {
+			kind: "project-file",
+			path: projectCaplets.paths
+		}
+	} : void 0);
+	return {
+		config: parseConfig(input),
+		sources,
+		shadows,
+		warnings
+	};
+}
+function readBestEffortConfigInput(path, kind, warnings, transform) {
+	try {
+		const input = readPublicConfigInput(path);
+		return transform ? transform(input) : input;
+	} catch (error) {
+		warnings.push({
+			kind,
+			path,
+			message: errorMessage(error)
+		});
+		return;
+	}
+}
+function loadBestEffortCapletFiles(root, kind, warnings) {
+	const result = loadCapletFilesWithPathsBestEffort(root);
+	if (!result) return;
+	for (const warning of result.warnings) warnings.push({
+		kind,
+		path: warning.path ?? root,
+		message: warning.message
+	});
+	return {
+		config: result.config,
+		paths: result.paths
+	};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function loadIsolatedConfig(options) {
 	if (!options.configPath && !options.capletsRoot) throw new CapletsError("CONFIG_INVALID", "Nested Caplet set must define at least one source: configPath or capletsRoot");
 	const configInput = options.configPath ? readPublicConfigInput(options.configPath) : void 0;
@@ -53822,6 +54085,7 @@ var CapletsEngine = class {
 	watchDebounceMs;
 	watchEnabled;
 	writeErr;
+	configLoader;
 	reloadListeners = /* @__PURE__ */ new Set();
 	watchers = [];
 	reloadTimer;
@@ -53834,7 +54098,8 @@ var CapletsEngine = class {
 			configPath: resolveConfigPath(options.configPath),
 			projectConfigPath: options.projectConfigPath ?? resolveProjectConfigPath()
 		};
-		const config = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
+		this.configLoader = options.configLoader ?? loadConfig;
+		const config = this.configLoader(this.paths.configPath, this.paths.projectConfigPath);
 		this.registry = new ServerRegistry(config);
 		this.downstream = new DownstreamManager(this.registry, selectAuthOptions(options.authDir));
 		this.openapi = new OpenApiManager(this.registry, selectAuthOptions(options.authDir));
@@ -53889,7 +54154,7 @@ var CapletsEngine = class {
 		}
 	}
 	async completeCliWords(words) {
-		const { completeCliWords } = await import("./completion-Cq1z7ci2.js").then((n) => n.r);
+		const { completeCliWords } = await import("./completion-DRPTunQd.js").then((n) => n.r);
 		return await completeCliWords(words, {
 			config: this.registry.config,
 			managers: {
@@ -53949,7 +54214,7 @@ var CapletsEngine = class {
 		if (this.closed) return false;
 		let nextConfig;
 		try {
-			nextConfig = loadConfig(this.paths.configPath, this.paths.projectConfigPath);
+			nextConfig = this.configLoader(this.paths.configPath, this.paths.projectConfigPath);
 		} catch (error) {
 			this.writeErr(`Caplets config reload failed; keeping last known-good config.\n`);
 			this.writeErr(`${JSON.stringify(toSafeError(error, "CONFIG_INVALID"), null, 2)}\n`);
@@ -54229,4 +54494,4 @@ function hasEnv(value) {
 	return value !== void 0 && value.trim() !== "";
 }
 //#endregion
-export { assertCompleteRequestPrompt as $, CreateMessageResultSchema as A, toSafeError as At, JSONRPCMessageSchema as B, AjvJsonSchemaValidator as C, resolveProjectConfigPath as Ct, CallToolRequestSchema as D, CAPLETS_ERROR_CODES as Dt, toJsonSchemaCompat as E, SERVER_ID_PATTERN as Et, EmptyResultSchema as F, ListRootsResultSchema as G, ListPromptsRequestSchema as H, ErrorCode as I, McpError as J, ListToolsRequestSchema as K, GetPromptRequestSchema as L, CreateTaskResultSchema as M, __exportAll as Mt, DEFAULT_NEGOTIATED_PROTOCOL_VERSION as N, __require as Nt, CallToolResultSchema as O, CapletsError as Ot, ElicitResultSchema as P, __toESM as Pt, ToolListChangedNotificationSchema as Q, InitializeRequestSchema as R, assertToolsCallTaskCapability as S, resolveProjectCapletsRoot as St, mergeCapabilities as T, validateCapletFile as Tt, ListResourceTemplatesRequestSchema as U, LATEST_PROTOCOL_VERSION as V, ListResourcesRequestSchema as W, SUPPORTED_PROTOCOL_VERSIONS as X, ReadResourceRequestSchema as Y, SetLevelRequestSchema as Z, StreamableHTTPClientTransport as _, parseConfig as _t, resolveCapletsServer as a, getLiteralValue as at, Client as b, resolveCapletsRoot as bt, ServerRegistry as c, getSchemaDescription as ct, runOAuthFlow as d, normalizeObjectSchema as dt, assertCompleteRequestResourceTemplate as et, startGenericOAuthFlow as f, objectFromShape as ft, readTokenBundle as g, loadConfigWithSources as gt, isTokenBundleExpired as h, loadConfig as ht, resolveCapletsMode as i, isJSONRPCResultResponse as it, CreateMessageResultWithToolsSchema as j, __commonJSMin as jt, CompleteRequestSchema as k, redactSecrets as kt, capabilityDescription as l, isSchemaOptional as lt, deleteTokenBundle as m, safeParseAsync as mt, mcpUrlForBase as n, isJSONRPCErrorResponse as nt, CapletsEngine as o, getObjectShape as ot, startOAuthFlow as p, safeParse as pt, LoggingLevelSchema as q, parseServerBaseUrl as r, isJSONRPCRequest as rt, handleServerTool as s, getParseErrorMessage as st, controlUrlForBase as t, isInitializeRequest as tt, runGenericOAuthFlow as u, isZ4Schema as ut, ReadBuffer as v, DEFAULT_AUTH_DIR as vt, Protocol as w, discoverCapletFiles as wt, assertClientRequestTaskCapability as x, resolveConfigPath as xt, serializeMessage as y, DEFAULT_COMPLETION_CACHE_DIR as yt, InitializedNotificationSchema as z };
+export { assertCompleteRequestPrompt as $, CreateMessageResultSchema as A, CAPLETS_ERROR_CODES as At, JSONRPCMessageSchema as B, AjvJsonSchemaValidator as C, resolveCapletsRoot as Ct, CallToolRequestSchema as D, discoverCapletFiles as Dt, toJsonSchemaCompat as E, resolveProjectConfigPath as Et, EmptyResultSchema as F, __exportAll as Ft, ListRootsResultSchema as G, ListPromptsRequestSchema as H, ErrorCode as I, __require as It, McpError as J, ListToolsRequestSchema as K, GetPromptRequestSchema as L, __toESM as Lt, CreateTaskResultSchema as M, redactSecrets as Mt, DEFAULT_NEGOTIATED_PROTOCOL_VERSION as N, toSafeError as Nt, CallToolResultSchema as O, validateCapletFile as Ot, ElicitResultSchema as P, __commonJSMin as Pt, ToolListChangedNotificationSchema as Q, InitializeRequestSchema as R, assertToolsCallTaskCapability as S, DEFAULT_COMPLETION_CACHE_DIR as St, mergeCapabilities as T, resolveProjectCapletsRoot as Tt, ListResourceTemplatesRequestSchema as U, LATEST_PROTOCOL_VERSION as V, ListResourcesRequestSchema as W, SUPPORTED_PROTOCOL_VERSIONS as X, ReadResourceRequestSchema as Y, SetLevelRequestSchema as Z, StreamableHTTPClientTransport as _, loadGlobalConfig as _t, resolveCapletsServer as a, getLiteralValue as at, Client as b, parseConfig as bt, ServerRegistry as c, getSchemaDescription as ct, runOAuthFlow as d, normalizeObjectSchema as dt, assertCompleteRequestResourceTemplate as et, startGenericOAuthFlow as f, objectFromShape as ft, readTokenBundle as g, loadConfigWithSources as gt, isTokenBundleExpired as h, loadConfig as ht, resolveCapletsMode as i, isJSONRPCResultResponse as it, CreateMessageResultWithToolsSchema as j, CapletsError as jt, CompleteRequestSchema as k, SERVER_ID_PATTERN as kt, capabilityDescription as l, isSchemaOptional as lt, deleteTokenBundle as m, safeParseAsync as mt, mcpUrlForBase as n, isJSONRPCErrorResponse as nt, CapletsEngine as o, getObjectShape as ot, startOAuthFlow as p, safeParse as pt, LoggingLevelSchema as q, parseServerBaseUrl as r, isJSONRPCRequest as rt, handleServerTool as s, getParseErrorMessage as st, controlUrlForBase as t, isInitializeRequest as tt, runGenericOAuthFlow as u, isZ4Schema as ut, ReadBuffer as v, loadLocalOverlayConfigWithSources as vt, Protocol as w, resolveConfigPath as wt, assertClientRequestTaskCapability as x, DEFAULT_AUTH_DIR as xt, serializeMessage as y, loadProjectConfig as yt, InitializedNotificationSchema as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Core runtime library for Caplets progressive disclosure gateways.",
   "keywords": [
     "caplets",
@@ -50,7 +50,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.3",
     "graphql": "^16.14.0",
-    "hono": "^4.12.21",
+    "hono": "^4.12.22",
     "vfile": "^6.0.3",
     "vfile-matter": "^5.0.1",
     "yaml": "^2.9.0",
@@ -58,7 +58,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260519.1",
+    "@typescript/native-preview": "7.0.0-dev.20260523.1",
     "rolldown": "^1.0.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"
@@ -67,8 +67,9 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "rm -rf dist && rolldown -c && tsc -p tsconfig.build.json",
-    "build:watch": "rolldown -c --watch",
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && rolldown -c && tsc -p tsconfig.build.json",
+    "build:watch": "pnpm run clean && rolldown -c --watch",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run"
   }