@caplets/core 0.15.0 → 0.16.0

package/dist/native/options.d.ts

@@ -0,0 +1,34 @@
+export type NativeCapletsMode = "auto" | "local" | "remote";
+export type NativeRemoteCapletsOptions = {
+    url?: string;
+    user?: string;
+    password?: string;
+    pollIntervalMs?: number;
+    fetch?: typeof fetch;
+};
+export type NativeCapletsServiceResolutionInput = {
+    mode?: NativeCapletsMode;
+    remote?: NativeRemoteCapletsOptions;
+};
+export type NativeCapletsEnv = Partial<Record<"CAPLETS_NATIVE_MODE" | "CAPLETS_REMOTE_URL" | "CAPLETS_REMOTE_USER" | "CAPLETS_REMOTE_PASSWORD", string>>;
+export type NativeRemoteAuthOptions = {
+    enabled: false;
+    user: string;
+} | {
+    enabled: true;
+    user: string;
+    password: string;
+};
+export type ResolvedNativeCapletsServiceOptions = {
+    mode: "local";
+} | {
+    mode: "remote";
+    remote: {
+        url: URL;
+        auth: NativeRemoteAuthOptions;
+        pollIntervalMs: number;
+        requestInit: RequestInit;
+        fetch?: typeof fetch;
+    };
+};
+export declare function resolveNativeCapletsServiceOptions(input?: NativeCapletsServiceResolutionInput, env?: NativeCapletsEnv): ResolvedNativeCapletsServiceOptions;

package/dist/native/remote.d.ts

@@ -0,0 +1,46 @@
+import type { ResolvedNativeCapletsServiceOptions } from "./options";
+import type { NativeCapletsService, NativeCapletsToolsChangedListener, NativeCapletTool } from "./service";
+export type RemoteCapletsTool = {
+    name: string;
+    title?: string | undefined;
+    description?: string | undefined;
+};
+export type RemoteCapletsClient = {
+    listTools(): Promise<RemoteCapletsTool[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    onToolsChanged(listener: () => void): () => void;
+    close(): Promise<void>;
+};
+export type RemoteCapletsClientOptions = ResolvedNativeCapletsServiceOptions & {
+    mode: "remote";
+};
+export type RemoteNativeCapletsServiceOptions = {
+    client: RemoteCapletsClient;
+    clientFactory?: () => RemoteCapletsClient;
+    pollIntervalMs: number;
+    writeErr?: (value: string) => void;
+};
+export declare function createSdkRemoteCapletsClient(options: RemoteCapletsClientOptions["remote"]): RemoteCapletsClient;
+export declare class RemoteNativeCapletsService implements NativeCapletsService {
+    private readonly options;
+    private tools;
+    private readonly listeners;
+    private readonly clientFactory;
+    private client;
+    private unsubscribeRemote;
+    private readonly pollTimer;
+    private closed;
+    private resetInFlight;
+    constructor(options: RemoteNativeCapletsServiceOptions);
+    listTools(): NativeCapletTool[];
+    execute(capletId: string, request: unknown): Promise<unknown>;
+    reload(): Promise<boolean>;
+    onToolsChanged(listener: NativeCapletsToolsChangedListener): () => void;
+    close(): Promise<void>;
+    private reloadFromClient;
+    private subscribeRemote;
+    private resetClient;
+    private doResetClient;
+    private emitToolsChanged;
+    private warn;
+}

package/dist/native/service.d.ts

@@ -1,10 +1,16 @@
-export type NativeCapletsServiceOptions = {
+import type { NativeCapletsServiceResolutionInput } from "./options";
+import { resolveNativeCapletsServiceOptions } from "./options";
+import { type RemoteCapletsClient } from "./remote";
+export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput & {
     configPath?: string;
     projectConfigPath?: string;
     authDir?: string;
     watchDebounceMs?: number;
     watch?: boolean;
     writeErr?: (value: string) => void;
+    remoteClientFactory?: (options: Extract<ReturnType<typeof resolveNativeCapletsServiceOptions>, {
+        mode: "remote";
+    }>["remote"]) => RemoteCapletsClient;
 };
 export type NativeCapletTool = {
     caplet: string;

package/dist/native.d.ts

@@ -3,3 +3,5 @@ export { registerNativeCapletsProcessCleanup } from "./native/process-cleanup";
 export { nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, } from "./native/tools";
 export { generatedToolInputSchema } from "./tools";
 export { generatedToolInputJsonSchema } from "./generated-tool-input-schema";
+export { resolveNativeCapletsServiceOptions, type NativeCapletsEnv, type NativeCapletsMode, type NativeCapletsServiceResolutionInput, type NativeRemoteAuthOptions, type NativeRemoteCapletsOptions, type ResolvedNativeCapletsServiceOptions, } from "./native/options";
+export { createSdkRemoteCapletsClient, RemoteNativeCapletsService, type RemoteCapletsClient, type RemoteCapletsClientOptions, type RemoteCapletsTool, type RemoteNativeCapletsServiceOptions, } from "./native/remote";

package/dist/native.js

@@ -1,5 +1,77 @@
-import { a as capabilityDescription, n as generatedToolInputSchema, t as CapletsEngine } from "./engine-Bh55p8Lm.js";
+import { K as ToolListChangedNotificationSchema, Tt as CapletsError, a as capabilityDescription, d as StreamableHTTPClientTransport, m as Client, n as generatedToolInputSchema, t as CapletsEngine } from "./engine-Brwid_mq.js";
 import { generatedToolInputJsonSchema } from "./generated-tool-input-schema.js";
+import { Buffer } from "node:buffer";
+//#region src/native/options.ts
+const DEFAULT_REMOTE_USER = "caplets";
+const DEFAULT_POLL_INTERVAL_MS = 3e4;
+function resolveNativeCapletsServiceOptions(input = {}, env = process.env) {
+	const mode = parseMode(input.mode ?? env.CAPLETS_NATIVE_MODE ?? "auto");
+	if (mode === "local") return { mode: "local" };
+	const rawUrl = nonEmpty(input.remote?.url, "remote.url") ?? nonEmpty(env.CAPLETS_REMOTE_URL, "CAPLETS_REMOTE_URL");
+	if (mode === "remote" && rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_NATIVE_MODE=remote requires CAPLETS_REMOTE_URL or remote.url.");
+	if (rawUrl === void 0) return { mode: "local" };
+	const url = parseRemoteUrl(rawUrl);
+	const userWasExplicit = input.remote?.user !== void 0 || hasEnv(env.CAPLETS_REMOTE_USER);
+	const user = nonEmpty(input.remote?.user, "remote.user") ?? nonEmpty(env.CAPLETS_REMOTE_USER, "CAPLETS_REMOTE_USER") ?? DEFAULT_REMOTE_USER;
+	const password = nonEmpty(input.remote?.password, "remote.password") ?? nonEmpty(env.CAPLETS_REMOTE_PASSWORD, "CAPLETS_REMOTE_PASSWORD");
+	if (userWasExplicit && password === void 0) throw new CapletsError("REQUEST_INVALID", "Remote Caplets Basic Auth requires a password; set CAPLETS_REMOTE_PASSWORD or remote.password.");
+	const auth = password === void 0 ? {
+		enabled: false,
+		user
+	} : {
+		enabled: true,
+		user,
+		password
+	};
+	const requestInit = auth.enabled ? { headers: { Authorization: basicAuthHeader(auth.user, auth.password) } } : {};
+	return {
+		mode: "remote",
+		remote: {
+			url,
+			auth,
+			pollIntervalMs: parsePollInterval(input.remote?.pollIntervalMs),
+			requestInit,
+			...input.remote?.fetch ? { fetch: input.remote.fetch } : {}
+		}
+	};
+}
+function parseMode(value) {
+	if (value === "auto" || value === "local" || value === "remote") return value;
+	throw new CapletsError("REQUEST_INVALID", `Expected CAPLETS_NATIVE_MODE to be auto, local, or remote, got ${value}`);
+}
+function parseRemoteUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new CapletsError("REQUEST_INVALID", "Invalid remote Caplets URL.");
+	}
+	if (url.username !== "" || url.password !== "") throw new CapletsError("REQUEST_INVALID", "Remote Caplets URL must not include username or password; use CAPLETS_REMOTE_USER/CAPLETS_REMOTE_PASSWORD or remote.user/remote.password instead.");
+	if (url.protocol === "https:") return url;
+	if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
+	throw new CapletsError("REQUEST_INVALID", "Remote Caplets URL must use https except loopback development URLs.");
+}
+function isLoopbackHost(host) {
+	return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+function parsePollInterval(value) {
+	if (value === void 0) return DEFAULT_POLL_INTERVAL_MS;
+	if (!Number.isInteger(value) || value < 1e3) throw new CapletsError("REQUEST_INVALID", "remote.pollIntervalMs must be an integer >= 1000.");
+	return value;
+}
+function basicAuthHeader(user, password) {
+	return `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+}
+function nonEmpty(value, label) {
+	if (value === void 0) return;
+	const trimmed = value.trim();
+	if (!trimmed) throw new CapletsError("REQUEST_INVALID", `${label} must not be empty`);
+	return trimmed;
+}
+function hasEnv(value) {
+	return value !== void 0 && value.trim() !== "";
+}
+//#endregion
 //#region src/native/tools.ts
 function nativeCapletToolName(capletId) {
 	return `caplets_${capletId.replace(/_/g, "__").replace(/-/g, "_")}`;
@@ -29,8 +101,210 @@ function nativeCapletToolDescription(toolName, caplet) {
 	].join("\n");
 }
 //#endregion
+//#region src/native/remote.ts
+function createSdkRemoteCapletsClient(options) {
+	const client = new Client({
+		name: "caplets-native",
+		version: "1.0.0"
+	}, { capabilities: {} });
+	const transport = new StreamableHTTPClientTransport(options.url, {
+		requestInit: options.requestInit,
+		...options.fetch ? { fetch: options.fetch } : {}
+	});
+	const ready = client.connect(transport);
+	const readyObserved = ready.catch(() => void 0);
+	const listeners = /* @__PURE__ */ new Set();
+	client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+		for (const listener of listeners) listener();
+	});
+	return {
+		async listTools() {
+			await ready;
+			return ((await client.listTools()).tools ?? []).map((tool) => ({
+				name: tool.name,
+				...tool.title ? { title: tool.title } : {},
+				...tool.description ? { description: tool.description } : {}
+			}));
+		},
+		async callTool(name, args) {
+			await ready;
+			const toolArguments = args && typeof args === "object" && !Array.isArray(args) ? args : void 0;
+			return await client.callTool({
+				name,
+				arguments: toolArguments
+			});
+		},
+		onToolsChanged(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		async close() {
+			listeners.clear();
+			await readyObserved;
+			await transport.terminateSession().catch(() => void 0);
+			await client.close();
+		}
+	};
+}
+var RemoteNativeCapletsService = class {
+	options;
+	tools = [];
+	listeners = /* @__PURE__ */ new Set();
+	clientFactory;
+	client;
+	unsubscribeRemote;
+	pollTimer;
+	closed = false;
+	resetInFlight;
+	constructor(options) {
+		this.options = options;
+		this.client = options.client;
+		this.clientFactory = options.clientFactory ?? (() => options.client);
+		this.unsubscribeRemote = this.subscribeRemote(this.client);
+		this.pollTimer = setInterval(() => {
+			this.reload();
+		}, options.pollIntervalMs);
+		this.pollTimer.unref?.();
+	}
+	listTools() {
+		return [...this.tools];
+	}
+	async execute(capletId, request) {
+		try {
+			return await this.client.callTool(capletId, request);
+		} catch (error) {
+			if (isAuthFailure(error)) throw remoteAuthError();
+			if (isSessionFailure(error)) {
+				if (!await this.resetClient() || this.closed) throw error;
+				try {
+					return await this.client.callTool(capletId, request);
+				} catch (retryError) {
+					if (isAuthFailure(retryError)) throw remoteAuthError();
+					throw retryError;
+				}
+			}
+			throw error;
+		}
+	}
+	async reload() {
+		if (this.closed) return false;
+		try {
+			await this.reloadFromClient();
+			return true;
+		} catch (error) {
+			if (isSessionFailure(error)) try {
+				if (!await this.resetClient() || this.closed) return false;
+				await this.reloadFromClient();
+				return !this.closed;
+			} catch (retryError) {
+				this.warn(`Could not reload remote Caplets tools: ${errorMessage(retryError)}\n`);
+				return false;
+			}
+			this.warn(`Could not reload remote Caplets tools: ${errorMessage(error)}\n`);
+			return false;
+		}
+	}
+	onToolsChanged(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		clearInterval(this.pollTimer);
+		this.unsubscribeRemote();
+		this.listeners.clear();
+		await this.client.close();
+	}
+	async reloadFromClient() {
+		const tools = (await this.client.listTools()).map(remoteToolToNativeTool);
+		const changed = JSON.stringify(tools) !== JSON.stringify(this.tools);
+		this.tools = tools;
+		if (changed) this.emitToolsChanged();
+	}
+	subscribeRemote(client) {
+		return client.onToolsChanged(() => {
+			this.reload();
+		});
+	}
+	async resetClient() {
+		if (this.resetInFlight) return await this.resetInFlight;
+		this.resetInFlight = this.doResetClient();
+		try {
+			return await this.resetInFlight;
+		} finally {
+			this.resetInFlight = void 0;
+		}
+	}
+	async doResetClient() {
+		if (this.closed) return false;
+		this.unsubscribeRemote();
+		await this.client.close().catch(() => void 0);
+		if (this.closed) return false;
+		const nextClient = this.clientFactory();
+		if (this.closed) {
+			await nextClient.close().catch(() => void 0);
+			return false;
+		}
+		this.client = nextClient;
+		this.unsubscribeRemote = this.subscribeRemote(this.client);
+		return true;
+	}
+	emitToolsChanged() {
+		const tools = this.listTools();
+		for (const listener of this.listeners) listener(tools);
+	}
+	warn(message) {
+		if (this.options.writeErr) {
+			this.options.writeErr(message);
+			return;
+		}
+		process.stderr.write(message);
+	}
+};
+function remoteToolToNativeTool(tool) {
+	const toolName = nativeCapletToolName(tool.name);
+	return {
+		caplet: tool.name,
+		toolName,
+		title: tool.title ?? tool.name,
+		description: [
+			tool.description ?? "Remote Caplets tool.",
+			"",
+			`Native tool name: ${toolName}`,
+			`Remote Caplet ID: ${tool.name}`
+		].join("\n"),
+		promptGuidance: [`Use ${toolName} through the remote Caplets service.`]
+	};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function remoteAuthError() {
+	return new CapletsError("AUTH_FAILED", "Remote Caplets authentication failed; check CAPLETS_REMOTE_USER and CAPLETS_REMOTE_PASSWORD.");
+}
+function isSessionFailure(error) {
+	const message = errorMessage(error).toLowerCase();
+	return /session|transport|connection|connect|closed|invalid/u.test(message);
+}
+function isAuthFailure(error) {
+	const candidate = error;
+	const status = typeof candidate?.status === "number" ? candidate.status : void 0;
+	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));
+}
+//#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 } : {}
+	});
 	return new DefaultNativeCapletsService(options);
 }
 var DefaultNativeCapletsService = class {
@@ -90,4 +364,4 @@ function registerNativeCapletsProcessCleanup(service) {
 	process.once("SIGTERM", closeAndExit);
 }
 //#endregion
-export { createNativeCapletsService, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, registerNativeCapletsProcessCleanup };
+export { RemoteNativeCapletsService, createNativeCapletsService, createSdkRemoteCapletsClient, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, registerNativeCapletsProcessCleanup, resolveNativeCapletsServiceOptions };

package/dist/runtime.d.ts

@@ -1,7 +1,6 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { type CapletsConfig } from "./config";
-type ToolServer = Pick<McpServer, "registerTool" | "connect" | "close">;
+import type { CapletsConfig } from "./config";
+import { type ToolServer } from "./serve/session";
 type CapletsRuntimeOptions = {
     configPath?: string;
     projectConfigPath?: string;
@@ -13,8 +12,7 @@ type CapletsRuntimeOptions = {
 export declare class CapletsRuntime {
     readonly server: ToolServer;
     private readonly engine;
-    private readonly tools;
-    private readonly unsubscribeReload;
+    private readonly session;
     constructor(options?: CapletsRuntimeOptions);
     connect(transport: Transport): Promise<void>;
     scheduleReload(): void;
@@ -23,8 +21,5 @@ export declare class CapletsRuntime {
     currentConfig(): CapletsConfig;
     registeredToolIds(): string[];
     watchedPaths(): string[];
-    private reconcileTools;
-    private registerCapletTool;
-    private handleTool;
 }
 export {};

package/dist/serve/http.d.ts

@@ -0,0 +1,12 @@
+import { Hono } from "hono";
+import { CapletsEngine, type CapletsEngineOptions } from "../engine";
+import type { HttpServeOptions } from "./options";
+type HttpServeIo = {
+    writeErr?: (value: string) => void;
+};
+export type CapletsHttpApp = Hono & {
+    closeCapletsSessions: () => Promise<void>;
+};
+export declare function createHttpServeApp(options: HttpServeOptions, engine: CapletsEngine, io?: HttpServeIo): CapletsHttpApp;
+export declare function serveHttp(options: HttpServeOptions, engineOptions?: CapletsEngineOptions, writeErr?: (value: string) => void): Promise<void>;
+export {};

package/dist/serve/index.d.ts

@@ -0,0 +1,14 @@
+import type { CapletsEngineOptions } from "../engine";
+import { type RawServeOptions, type ServeOptions } from "./options";
+export { serveHttp } from "./http";
+export { resolveServeOptions } from "./options";
+export type { HttpServeOptions, RawServeOptions, ServeOptions, StdioServeOptions } from "./options";
+export { serveStdio } from "./stdio";
+export type ServeCapletsOptions = {
+    raw: RawServeOptions;
+    engine?: CapletsEngineOptions;
+    env?: NodeJS.ProcessEnv;
+    writeErr?: (value: string) => void;
+};
+export declare function serveCaplets(options: ServeCapletsOptions): Promise<void>;
+export declare function serveResolvedCaplets(resolved: ServeOptions, engineOptions?: CapletsEngineOptions, writeErr?: (value: string) => void): Promise<void>;

package/dist/serve/options.d.ts

@@ -0,0 +1,34 @@
+export type ServeTransport = "stdio" | "http";
+export type RawServeOptions = {
+    transport?: string;
+    host?: string;
+    port?: string | number;
+    path?: string;
+    user?: string;
+    password?: string;
+    allowUnauthenticatedHttp?: boolean;
+};
+export type StdioServeOptions = {
+    transport: "stdio";
+};
+export type HttpServeOptions = {
+    transport: "http";
+    host: string;
+    port: number;
+    path: string;
+    auth: HttpBasicAuthOptions;
+    warnUnauthenticatedNetwork: boolean;
+    loopback: boolean;
+};
+export type HttpBasicAuthOptions = {
+    enabled: false;
+    user: string;
+} | {
+    enabled: true;
+    user: string;
+    password: string;
+};
+export type ServeOptions = StdioServeOptions | HttpServeOptions;
+export type ServeEnv = Partial<Record<"CAPLETS_SERVER_USER" | "CAPLETS_SERVER_PASSWORD", string>>;
+export declare function resolveServeOptions(raw: RawServeOptions, env?: ServeEnv): ServeOptions;
+export declare function isLoopbackHost(host: string): boolean;

package/dist/serve/session.d.ts

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { CapletsEngine } from "../engine";
+export type ToolServer = Pick<McpServer, "registerTool" | "connect" | "close">;
+export type CapletsMcpSessionOptions = {
+    server?: ToolServer;
+};
+export declare class CapletsMcpSession {
+    private readonly engine;
+    readonly server: ToolServer;
+    private readonly tools;
+    private readonly unsubscribeReload;
+    private closed;
+    constructor(engine: CapletsEngine, options?: CapletsMcpSessionOptions);
+    connect(transport: Transport): Promise<void>;
+    registeredToolIds(): string[];
+    close(): Promise<void>;
+    private reconcileTools;
+    private registerCapletTool;
+    private handleTool;
+}

package/dist/serve/stdio.d.ts

@@ -0,0 +1,5 @@
+import { type CapletsEngineOptions } from "../engine";
+export type ServeStdioOptions = CapletsEngineOptions & {
+    signalHandling?: boolean;
+};
+export declare function serveStdio(options?: ServeStdioOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Core runtime library for Caplets progressive disclosure gateways.",
   "keywords": [
     "caplets",
@@ -45,9 +45,12 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
+    "@hono/mcp": "^0.3.0",
+    "@hono/node-server": "^1.19.14",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.3",
     "graphql": "^16.14.0",
+    "hono": "^4.12.19",
     "vfile": "^6.0.3",
     "vfile-matter": "^5.0.1",
     "zod": "^4.4.3"