caplets 0.15.0 → 0.16.0

package/dist/index.js

@@ -9,6 +9,7 @@ import { homedir, tmpdir } from "node:os";
 import { PassThrough } from "node:stream";
 import { createServer } from "node:http";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { Buffer as Buffer$1 } from "node:buffer";
 import { createInterface } from "node:readline/promises";
 import { createServer as createServer$1 } from "http";
 import { Http2ServerRequest, constants as constants$1 } from "http2";
@@ -72,7 +73,7 @@ function generatedToolInputJsonSchema() {
 	};
 }
 //#endregion
-//#region ../core/dist/engine-Brwid_mq.js
+//#region ../core/dist/options-CJEOqS87.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -95,6 +96,25 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
+const CAPLETS_ERROR_CODES = [
+	"CONFIG_NOT_FOUND",
+	"CONFIG_EXISTS",
+	"CONFIG_INVALID",
+	"REQUEST_INVALID",
+	"SERVER_NOT_FOUND",
+	"SERVER_UNAVAILABLE",
+	"SERVER_START_TIMEOUT",
+	"UNKNOWN_OPERATION",
+	"TOOL_NOT_FOUND",
+	"TOOL_CALL_TIMEOUT",
+	"AUTH_REQUIRED",
+	"AUTH_FAILED",
+	"AUTH_REFRESH_FAILED",
+	"DOWNSTREAM_PROTOCOL_ERROR",
+	"DOWNSTREAM_TOOL_ERROR",
+	"UNSUPPORTED_TRANSPORT",
+	"INTERNAL_ERROR"
+];
 var CapletsError = class extends Error {
 	code;
 	details;
@@ -13442,7 +13462,7 @@ function loadConfigWithSources(path = resolveConfigPath(), projectPath = resolve
 	const userConfig = hasUserConfig ? readPublicConfigInput(path) : void 0;
 	const userCaplets = loadCapletFilesWithPaths(resolveCapletsRoot(path));
 	const projectConfig = hasProjectConfig ? rejectProjectConfigExecutableBackendMaps(readPublicConfigInput(projectPath), projectPath) : void 0;
-	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath(projectPath);
+	const projectCapletsRoot = resolveProjectCapletsRootForConfigPath$1(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 {
@@ -13496,7 +13516,7 @@ function loadIsolatedConfig(options) {
 	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", "Nested Caplet set must define at least one Caplet");
 	return config;
 }
-function resolveProjectCapletsRootForConfigPath(projectPath) {
+function resolveProjectCapletsRootForConfigPath$1(projectPath) {
 	const root = dirname(projectPath);
 	return basename(root) === ".caplets" && basename(projectPath) === "config.json" ? root : void 0;
 }
@@ -30743,8 +30763,45 @@ var FileOAuthProvider = class {
 		headers.set("content-type", "application/x-www-form-urlencoded");
 	};
 };
-async function runOAuthFlow(server, options = {}) {
+async function startOAuthFlow(server, options) {
 	if (server.transport === "stdio" || !server.url || server.auth?.type !== "oauth2" && server.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${server.server} is not a configured OAuth remote server`);
+	let redirectUrl;
+	const provider = new FileOAuthProvider(server, options.redirectUri, (url) => {
+		redirectUrl = url;
+		options.print?.(`Open this URL to authorize ${server.server}:\n${url.toString()}`);
+	}, options.authDir);
+	const scope = scopesFor(server.auth);
+	try {
+		if (await auth(provider, {
+			serverUrl: server.url,
+			...scope ? { scope } : {}
+		}) === "AUTHORIZED") return {
+			authorizationUrl: "",
+			complete: async () => {}
+		};
+	} catch (error) {
+		throw normalizeMcpOAuthError(server, error);
+	}
+	if (!redirectUrl) throw new CapletsError("AUTH_FAILED", "OAuth authorization URL was not provided");
+	return {
+		authorizationUrl: redirectUrl.toString(),
+		complete: async (callbackUrl) => {
+			assertNoOAuthCallbackError(server, callbackUrl);
+			const completion = extractCompletion(callbackUrl);
+			if (completion.state !== provider.state()) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
+			try {
+				await auth(provider, {
+					serverUrl: server.url,
+					authorizationCode: completion.code,
+					...scope ? { scope } : {}
+				});
+			} catch (error) {
+				throw normalizeMcpOAuthError(server, error);
+			}
+		}
+	};
+}
+async function runOAuthFlow(server, options = {}) {
 	let callbackCode;
 	let callbackState;
 	const callback = await createLoopbackCallback((url) => {
@@ -30752,37 +30809,43 @@ async function runOAuthFlow(server, options = {}) {
 		callbackCode = url.searchParams.get("code") ?? void 0;
 		callbackState = url.searchParams.get("state") ?? void 0;
 	});
-	let redirectUrl;
-	const provider = new FileOAuthProvider(server, callback.redirectUri, (url) => {
-		redirectUrl = url;
-		options.print?.(`Open this URL to authorize ${server.server}:\n${url.toString()}`);
-	}, options.authDir);
 	try {
-		const scope = scopesFor(server.auth);
-		const first = await auth(provider, {
-			serverUrl: server.url,
-			...scope ? { scope } : {}
+		const started = await startOAuthFlow(server, {
+			redirectUri: callback.redirectUri,
+			...options.authDir ? { authDir: options.authDir } : {},
+			...options.print ? { print: options.print } : {}
 		});
-		if (first === "AUTHORIZED") return first;
-		if (!options.noOpen && redirectUrl) await (options.open ? options.open(redirectUrl.toString()) : openBrowser(redirectUrl.toString()));
+		if (!started.authorizationUrl) return "AUTHORIZED";
+		if (!options.noOpen) await (options.open ? options.open(started.authorizationUrl) : openBrowser$1(started.authorizationUrl));
 		const manualInput = options.manualInput ?? (options.noOpen ? await options.readManualInput?.() : void 0);
 		const completion = manualInput ? extractCompletion(manualInput) : await callback.waitForCode(() => callbackCode ? {
 			code: callbackCode,
 			...callbackState ? { state: callbackState } : {}
 		} : void 0);
-		const expectedState = provider.state();
-		if (completion.state !== expectedState) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
-		return await auth(provider, {
-			serverUrl: server.url,
-			authorizationCode: completion.code,
-			...scope ? { scope } : {}
-		});
+		await started.complete(completion.state ? `${callback.redirectUri}?code=${encodeURIComponent(completion.code)}&state=${encodeURIComponent(completion.state)}` : `${callback.redirectUri}?code=${encodeURIComponent(completion.code)}`);
+		return "AUTHORIZED";
 	} catch (error) {
 		throw normalizeMcpOAuthError(server, error);
 	} finally {
 		await callback.close();
 	}
 }
+function assertNoOAuthCallbackError(target, callbackUrl) {
+	let url;
+	try {
+		url = new URL(callbackUrl);
+	} catch {
+		return;
+	}
+	const error = url.searchParams.get("error");
+	if (!error) return;
+	const description = url.searchParams.get("error_description");
+	throw new CapletsError("AUTH_FAILED", description ? `OAuth provider returned an error: ${description}` : "OAuth provider returned an error", redactSecrets({
+		server: target.server,
+		error,
+		error_description: description ?? void 0
+	}));
+}
 function normalizeMcpOAuthError(server, error) {
 	if ((server.auth?.type === "oauth2" || server.auth?.type === "oidc") && !server.auth.clientId && !server.auth.clientMetadataUrl && error instanceof Error && error.message.includes("does not support dynamic client registration")) return new CapletsError("AUTH_FAILED", "OAuth is not available for this server without a host-specific OAuth app or PAT auth", {
 		server: server.server,
@@ -30790,6 +30853,75 @@ function normalizeMcpOAuthError(server, error) {
 	});
 	return error;
 }
+async function startGenericOAuthFlow(target, options) {
+	if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${target.server} is not configured for OAuth`);
+	const authConfig = target.auth;
+	const redirectUri = authConfig.redirectUri ?? options.redirectUri;
+	const verifier = base64url(randomBytes(32));
+	const state = base64url(randomBytes(24));
+	const allowLoopbackHttp = isLoopbackDevelopmentTarget(target, authConfig);
+	const metadata = await discoverAuthorizationServer(target, authConfig, allowLoopbackHttp);
+	const authorizationEndpoint = authConfig.authorizationUrl ?? metadata.authorization_endpoint;
+	const tokenEndpoint = authConfig.tokenUrl ?? metadata.token_endpoint;
+	if (!authorizationEndpoint || !tokenEndpoint) throw new CapletsError("AUTH_FAILED", "OAuth metadata is missing endpoints", { server: target.server });
+	assertAllowedAuthUrl(authorizationEndpoint, "authorization endpoint", allowLoopbackHttp);
+	assertAllowedAuthUrl(tokenEndpoint, "token endpoint", allowLoopbackHttp);
+	const client = await resolveGenericClient(target, authConfig, metadata, redirectUri, allowLoopbackHttp);
+	const scope = scopesFor(authConfig);
+	const authorizationUrl = new URL(authorizationEndpoint);
+	authorizationUrl.searchParams.set("response_type", "code");
+	authorizationUrl.searchParams.set("client_id", client.clientId);
+	authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+	authorizationUrl.searchParams.set("code_challenge", pkceChallenge(verifier));
+	authorizationUrl.searchParams.set("code_challenge_method", "S256");
+	authorizationUrl.searchParams.set("state", state);
+	if (scope) authorizationUrl.searchParams.set("scope", scope);
+	options.print?.(`Open this URL to authorize ${target.server}:\n${authorizationUrl.toString()}`);
+	return {
+		authorizationUrl: authorizationUrl.toString(),
+		complete: async (callbackUrl) => {
+			assertNoOAuthCallbackError(target, callbackUrl);
+			const completion = extractCompletion(callbackUrl);
+			if (completion.state !== state) throw new CapletsError("AUTH_FAILED", "OAuth callback state did not match");
+			const params = new URLSearchParams({
+				grant_type: "authorization_code",
+				code: completion.code,
+				redirect_uri: redirectUri,
+				client_id: client.clientId,
+				code_verifier: verifier
+			});
+			if (client.clientSecret) params.set("client_secret", client.clientSecret);
+			const tokenResponse = await fetchJson(tokenEndpoint, target.requestTimeoutMs, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: params.toString()
+			}, allowLoopbackHttp);
+			const idToken = asString(tokenResponse.id_token);
+			const idClaims = parseJwtPayload(idToken);
+			validateOidcToken(authConfig, metadata, idToken, idClaims, client.clientId);
+			writeTokenBundle(stripUndefined({
+				server: target.server,
+				authType: authConfig.type,
+				accessToken: requireString(tokenResponse.access_token, "access_token"),
+				refreshToken: asString(tokenResponse.refresh_token),
+				tokenType: asString(tokenResponse.token_type),
+				expiresAt: typeof tokenResponse.expires_in === "number" ? new Date(Date.now() + tokenResponse.expires_in * 1e3).toISOString() : void 0,
+				scope: asString(tokenResponse.scope) ?? scope,
+				idToken,
+				issuer: asString(idClaims?.iss) ?? metadata.issuer ?? authConfig.issuer,
+				subject: asString(idClaims?.sub),
+				clientId: client.clientId,
+				clientSecret: client.clientSecret,
+				protectedResourceOrigin: protectedResourceOrigin(target, authConfig),
+				metadata: redactSecrets({
+					protectedResource: target.url ?? target.baseUrl ?? target.specUrl,
+					authorizationServer: metadata,
+					dynamicClient: client.dynamic ? { client_id: client.clientId } : void 0
+				})
+			}), options.authDir);
+		}
+	};
+}
 async function runGenericOAuthFlow(target, options = {}) {
 	if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${target.server} is not configured for OAuth`);
 	const authConfig = target.auth;
@@ -30822,7 +30954,7 @@ async function runGenericOAuthFlow(target, options = {}) {
 		authorizationUrl.searchParams.set("state", state);
 		if (scope) authorizationUrl.searchParams.set("scope", scope);
 		options.print?.(`Open this URL to authorize ${target.server}:\n${authorizationUrl.toString()}`);
-		if (!options.noOpen) await (options.open ? options.open(authorizationUrl.toString()) : openBrowser(authorizationUrl.toString()));
+		if (!options.noOpen) await (options.open ? options.open(authorizationUrl.toString()) : openBrowser$1(authorizationUrl.toString()));
 		const manualInput = options.manualInput ?? (options.noOpen ? await options.readManualInput?.() : void 0);
 		const completion = manualInput ? extractCompletion(manualInput) : await callback.waitForCode(() => callbackCode ? {
 			code: callbackCode,
@@ -30925,7 +31057,7 @@ async function createLoopbackCallback(onCallback) {
 		close: () => new Promise((resolve) => server.close(() => resolve()))
 	};
 }
-async function openBrowser(url) {
+async function openBrowser$1(url) {
 	const { spawn } = await import("node:child_process");
 	spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open", process.platform === "win32" ? [
 		"/c",
@@ -57259,6 +57391,90 @@ function isDirectory(path) {
 		return false;
 	}
 }
+const DEFAULT_SERVER_USER = "caplets";
+function resolveCapletsMode(input = {}, env = process.env) {
+	const mode = parseCapletsMode(input.mode ?? env.CAPLETS_MODE ?? "auto");
+	if (mode === "local") return { mode: "local" };
+	const rawUrl = nonEmpty$1(input.serverUrl, "serverUrl") ?? nonEmpty$1(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
+	if (mode === "remote") {
+		if (rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_MODE=remote requires CAPLETS_SERVER_URL or serverUrl.");
+		return { mode: "remote" };
+	}
+	return rawUrl === void 0 ? { mode: "local" } : { mode: "remote" };
+}
+function resolveCapletsServer(input = {}, env = process.env) {
+	const rawUrl = nonEmpty$1(input.url, "url") ?? nonEmpty$1(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL");
+	if (rawUrl === void 0) throw new CapletsError("REQUEST_INVALID", "CAPLETS_SERVER_URL or url is required.");
+	const baseUrl = parseServerBaseUrl(rawUrl);
+	const userWasExplicit = input.user !== void 0 || hasEnv$1(env.CAPLETS_SERVER_USER);
+	const user = nonEmpty$1(input.user, "user") ?? nonEmpty$1(env.CAPLETS_SERVER_USER, "CAPLETS_SERVER_USER") ?? DEFAULT_SERVER_USER;
+	const password = nonEmpty$1(input.password, "password") ?? nonEmpty$1(env.CAPLETS_SERVER_PASSWORD, "CAPLETS_SERVER_PASSWORD");
+	if (userWasExplicit && password === void 0) throw new CapletsError("REQUEST_INVALID", "Caplets server Basic Auth requires a password; set CAPLETS_SERVER_PASSWORD or 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 {
+		baseUrl,
+		mcpUrl: mcpUrlForBase(baseUrl),
+		controlUrl: controlUrlForBase(baseUrl),
+		healthUrl: healthUrlForBase(baseUrl),
+		auth,
+		requestInit,
+		...input.fetch ? { fetch: input.fetch } : {}
+	};
+}
+function mcpUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "mcp");
+}
+function controlUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "control");
+}
+function healthUrlForBase(baseUrl) {
+	return appendBasePath(baseUrl, "healthz");
+}
+function appendBasePath(baseUrl, path) {
+	const url = new URL(baseUrl.href);
+	url.pathname = `${url.pathname === "/" ? "" : url.pathname}/${path}`;
+	return url;
+}
+function parseServerBaseUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new CapletsError("REQUEST_INVALID", "Invalid Caplets server URL.");
+	}
+	if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") throw new CapletsError("REQUEST_INVALID", "Caplets server URL must not include username, password, query string, or fragment.");
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost$1(url.hostname))) throw new CapletsError("REQUEST_INVALID", "Caplets server URL must use https except loopback development URLs.");
+	url.pathname = url.pathname === "/" ? "/" : url.pathname.replace(/\/+$/u, "");
+	return url;
+}
+function isLoopbackHost$1(host) {
+	const normalized = host.toLocaleLowerCase();
+	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+function parseCapletsMode(value) {
+	if (value === "auto" || value === "local" || value === "remote") return value;
+	throw new CapletsError("REQUEST_INVALID", `Expected CAPLETS_MODE to be auto, local, or remote, got ${value}`);
+}
+function basicAuthHeader(user, password) {
+	return `Basic ${Buffer$1.from(`${user}:${password}`).toString("base64")}`;
+}
+function nonEmpty$1(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$1(value) {
+	return value !== void 0 && value.trim() !== "";
+}
 //#endregion
 //#region ../core/dist/index.js
 /**
@@ -58557,7 +58773,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 	values: [],
 	hasMore: false
 } };
-var version$1 = "0.16.0";
+var version$1 = "0.17.0";
 var CapletsMcpSession = class {
 	engine;
 	server;
@@ -62090,49 +62306,56 @@ async function loginAuth(serverId, options) {
 	}
 }
 function logoutAuth(serverId, options) {
-	assertLoginTarget(findAuthTarget(serverId, loadConfig(options.configPath)), serverId);
-	if (deleteTokenBundle(serverId, options.authDir)) options.writeOut(`Deleted OAuth credentials for \`${serverId}\`.\n`);
+	if (logoutAuthResult(serverId, options).deleted) options.writeOut(`Deleted OAuth credentials for \`${serverId}\`.\n`);
 	else options.writeOut(`No OAuth credentials found for \`${serverId}\`.\n`);
 }
+function logoutAuthResult(serverId, options) {
+	assertLoginTarget(findAuthTarget(serverId, loadConfig(options.configPath)), serverId);
+	return {
+		server: serverId,
+		deleted: deleteTokenBundle(serverId, options.authDir)
+	};
+}
 function listAuth(options) {
-	const servers = authTargets(loadConfig(options.configPath)).sort((left, right) => left.server.localeCompare(right.server));
+	const rows = listAuthRows(options);
 	const format = options.format ?? "plain";
 	if (format === "json") {
-		const rows = servers.map((server) => {
-			const bundle = readTokenBundle(server.server, options.authDir);
-			const status = !bundle ? "missing" : isTokenBundleExpired(bundle) ? "expired" : "authenticated";
-			return {
-				server: server.server,
-				status,
-				...bundle?.expiresAt ? { expiresAt: bundle.expiresAt } : {},
-				...bundle?.scope ? { scope: bundle.scope } : {}
-			};
-		});
 		options.writeOut(`${JSON.stringify(rows, null, 2)}\n`);
 		return;
 	}
-	if (servers.length === 0) {
-		options.writeOut(format === "markdown" ? "## OAuth credentials\n\nNo configured remote OAuth servers found.\n" : "No configured remote OAuth servers found.\n");
-		return;
-	}
-	if (format === "markdown") options.writeOut("## OAuth credentials\n\n");
-	else options.writeOut("OAuth credentials\n\n");
-	for (const server of servers) {
+	options.writeOut(formatAuthRows(rows, format));
+}
+function listAuthRows(options) {
+	return authTargets(loadConfig(options.configPath)).sort((left, right) => left.server.localeCompare(right.server)).map((server) => {
 		const bundle = readTokenBundle(server.server, options.authDir);
 		const status = !bundle ? "missing" : isTokenBundleExpired(bundle) ? "expired" : "authenticated";
-		const details = [bundle?.expiresAt ? `expires ${bundle.expiresAt}` : void 0, bundle?.scope ? `scope ${bundle.scope}` : void 0].filter(Boolean).join("; ");
+		return {
+			server: server.server,
+			status,
+			...bundle?.expiresAt ? { expiresAt: bundle.expiresAt } : {},
+			...bundle?.scope ? { scope: bundle.scope } : {}
+		};
+	});
+}
+function formatAuthRows(rows, format) {
+	if (rows.length === 0) return format === "markdown" ? "## OAuth credentials\n\nNo configured remote OAuth servers found.\n" : "No configured remote OAuth servers found.\n";
+	let output = "";
+	if (format === "markdown") output += "## OAuth credentials\n\n";
+	else output += "OAuth credentials\n\n";
+	for (const row of rows) {
+		const details = [row.expiresAt ? `expires ${row.expiresAt}` : void 0, row.scope ? `scope ${row.scope}` : void 0].filter(Boolean).join("; ");
 		if (format === "markdown") {
-			options.writeOut(`- \`${server.server}\` — ${status}${details ? ` (${details})` : ""}\n`);
+			output += `- \`${row.server}\` — ${row.status}${details ? ` (${details})` : ""}\n`;
 			continue;
 		}
-		options.writeOut([
-			server.server,
-			`  Status: ${status}`,
-			...bundle?.expiresAt ? [`  Expires: ${bundle.expiresAt}`] : [],
-			...bundle?.scope ? [`  Scope: ${bundle.scope}`] : []
-		].join("\n"));
-		options.writeOut("\n\n");
+		output += [
+			row.server,
+			`  Status: ${row.status}`,
+			...row.expiresAt ? [`  Expires: ${row.expiresAt}`] : [],
+			...row.scope ? [`  Scope: ${row.scope}`] : []
+		].join("\n") + "\n\n";
 	}
+	return output;
 }
 function findAuthTarget(serverId, config = loadConfig()) {
 	return authTargets(config).find((server) => server.server === serverId);
@@ -62552,6 +62775,94 @@ function nearestExistingParent(path) {
 	if (parent === path) return parent;
 	return nearestExistingParent(parent);
 }
+var RemoteControlClient = class {
+	#baseUrl;
+	#requestInit;
+	#fetch;
+	constructor(options) {
+		this.#baseUrl = options.baseUrl;
+		this.#requestInit = options.requestInit;
+		this.#fetch = options.fetch ?? fetch;
+	}
+	async request(command, args) {
+		const controlUrl = controlUrlForBase(this.#baseUrl);
+		let response;
+		try {
+			response = await this.#fetch(controlUrl, {
+				...this.#requestInit,
+				method: "POST",
+				headers: mergeJsonHeaders(this.#requestInit.headers),
+				body: JSON.stringify({
+					command,
+					arguments: args
+				})
+			});
+		} catch (error) {
+			throw new CapletsError("SERVER_UNAVAILABLE", `Could not connect to Caplets server at ${safeBaseUrl(this.#baseUrl)}.`, toSafeError(error, "SERVER_UNAVAILABLE"));
+		}
+		if (response.status === 401 || response.status === 403) throw new CapletsError("AUTH_FAILED", "Caplets server authentication failed. Check CAPLETS_SERVER_USER and CAPLETS_SERVER_PASSWORD.");
+		if (!response.ok) throw new CapletsError("SERVER_UNAVAILABLE", `Caplets server at ${safeBaseUrl(this.#baseUrl)} returned HTTP ${response.status}.`);
+		const payload = await parseRemoteCliResponse(response);
+		if (!payload.ok) throw new CapletsError(payload.error.code, redactRemoteMessage(payload.error.message), payload.error.nextAction === void 0 ? void 0 : { nextAction: payload.error.nextAction });
+		return payload.result;
+	}
+};
+function mergeJsonHeaders(headers) {
+	const merged = new Headers(headers);
+	merged.set("content-type", "application/json");
+	return merged;
+}
+function safeBaseUrl(baseUrl) {
+	const safe = new URL(baseUrl.href);
+	safe.username = "";
+	safe.password = "";
+	safe.search = "";
+	safe.hash = "";
+	return safe.toString();
+}
+async function parseRemoteCliResponse(response) {
+	let payload;
+	try {
+		payload = await response.json();
+	} catch (error) {
+		throw invalidRemoteControlResponse(error);
+	}
+	if (!isRecord(payload)) throw invalidRemoteControlResponse();
+	if (payload.ok === true) {
+		if (!("result" in payload)) throw invalidRemoteControlResponse();
+		return {
+			ok: true,
+			result: payload.result
+		};
+	}
+	if (payload.ok === false) {
+		const error = payload.error;
+		if (!isRecord(error) || typeof error.code !== "string" || typeof error.message !== "string") throw invalidRemoteControlResponse();
+		if ("nextAction" in error && error.nextAction !== void 0 && typeof error.nextAction !== "string") throw invalidRemoteControlResponse();
+		const errorResponse = {
+			ok: false,
+			error: {
+				code: isCapletsErrorCode(error.code) ? error.code : "DOWNSTREAM_TOOL_ERROR",
+				message: error.message
+			}
+		};
+		if (typeof error.nextAction === "string") errorResponse.error.nextAction = error.nextAction;
+		return errorResponse;
+	}
+	throw invalidRemoteControlResponse();
+}
+function invalidRemoteControlResponse(cause) {
+	return new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "Caplets server returned an invalid remote control response.", cause === void 0 ? void 0 : toSafeError(cause, "DOWNSTREAM_PROTOCOL_ERROR"));
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isCapletsErrorCode(value) {
+	return CAPLETS_ERROR_CODES.includes(value);
+}
+function redactRemoteMessage(message) {
+	return String(redactSecrets(message)).replace(/\b(authorization\s*:\s*(?:basic|bearer)\s+)[^\s,;]+/giu, "$1[REDACTED]").replace(/\b((?:access_)?token=)[^\s,;]+/giu, "$1[REDACTED]").replace(/\b((?:token|secret|authorization|auth|api[-_]?key|password|credential|clientsecret|client_secret|code|refresh(?:_token)?)\s*[=:]\s*)[^\s,;]+/giu, "$1[REDACTED]");
+}
 var compose = (middleware, onError, onNotFound) => {
 	return (context, next) => {
 		let index = -1;
@@ -65421,29 +65732,343 @@ var logger = (fn = console.log) => {
 		await log(fn, "-->", method, path, c.res.status, time(start));
 	};
 };
+const ENGINE_COMMANDS = new Set([
+	"get_caplet",
+	"check_backend",
+	"list_tools",
+	"search_tools",
+	"get_tool",
+	"call_tool"
+]);
+async function dispatchRemoteCliRequest(request, context) {
+	try {
+		return {
+			ok: true,
+			result: await dispatch(request, context)
+		};
+	} catch (error) {
+		const safe = toSafeError(error);
+		const action = nextAction(safe.details);
+		return {
+			ok: false,
+			error: {
+				code: safe.code,
+				message: redactControlErrorMessage(safe.message),
+				...action ? { nextAction: action } : {}
+			}
+		};
+	}
+}
+async function dispatch(request, context) {
+	assertObject(request, "remote control request");
+	assertObject(request.arguments, "remote control request arguments");
+	if (request.command === "list") return listCaplets(loadConfigWithSources(context.configPath, context.projectConfigPath), { includeDisabled: optionalBoolean(request.arguments, "includeDisabled") ?? false });
+	if (ENGINE_COMMANDS.has(request.command)) {
+		const caplet = requiredString(request.arguments, "caplet");
+		const toolRequest = requiredEngineRequest(request.arguments, request.command);
+		const engine = new CapletsEngine(context);
+		try {
+			return await engine.execute(caplet, toolRequest);
+		} finally {
+			await engine.close();
+		}
+	}
+	if (request.command === "init") return {
+		remote: true,
+		path: initConfig({
+			...optionalProp("path", context.configPath),
+			...optionalProp("force", optionalBoolean(request.arguments, "force"))
+		})
+	};
+	if (request.command === "add") return dispatchAdd(request.arguments, context);
+	if (request.command === "install") return {
+		remote: true,
+		...installCaplets(requiredString(request.arguments, "repo"), {
+			...optionalProp("capletIds", optionalStringArray(request.arguments, "capletIds")),
+			destinationRoot: context.projectCapletsRoot,
+			...optionalProp("force", optionalBoolean(request.arguments, "force"))
+		})
+	};
+	if (request.command === "auth_list") return listAuthRows({
+		...optionalProp("configPath", context.configPath),
+		...optionalProp("authDir", context.authDir)
+	});
+	if (request.command === "auth_logout") return logoutAuthResult(requiredString(request.arguments, "server"), {
+		...optionalProp("configPath", context.configPath),
+		...optionalProp("authDir", context.authDir)
+	});
+	if (request.command === "auth_login_start") return startRemoteAuthLogin(requiredString(request.arguments, "server"), context);
+	if (request.command === "auth_login_complete") return completeRemoteAuthLogin(requiredString(request.arguments, "flowId"), requiredString(request.arguments, "callbackUrl"), context);
+	throw new CapletsError("UNKNOWN_OPERATION", `Unsupported remote control command ${request.command}`);
+}
+async function startRemoteAuthLogin(serverId, context) {
+	if (!context.authFlowStore || !context.controlCallbackBaseUrl) throw new CapletsError("REQUEST_INVALID", "Remote auth login is not available on this server");
+	const config = loadConfigWithSources(context.configPath, context.projectConfigPath).config;
+	const target = findAuthTarget(serverId, config);
+	assertLoginTarget(target, serverId);
+	const flowId = randomUUID();
+	const baseUrl = context.controlCallbackBaseUrl.endsWith("/") ? context.controlCallbackBaseUrl : `${context.controlCallbackBaseUrl}/`;
+	const redirectUri = new URL(`auth/callback/${flowId}`, baseUrl).toString();
+	const started = target.backend === "mcp" ? await startOAuthFlow(target, {
+		redirectUri,
+		...optionalProp("authDir", context.authDir)
+	}) : await startGenericOAuthFlow(target, {
+		redirectUri,
+		...optionalProp("authDir", context.authDir)
+	});
+	if (!started.authorizationUrl) return {
+		server: serverId,
+		authenticated: true
+	};
+	const flow = context.authFlowStore.create({
+		server: serverId,
+		authorizationUrl: started.authorizationUrl,
+		complete: started.complete
+	}, flowId);
+	return {
+		server: serverId,
+		flowId: flow.id,
+		authorizationUrl: flow.authorizationUrl
+	};
+}
+async function completeRemoteAuthLogin(flowId, callbackUrl, context) {
+	const flow = context.authFlowStore?.get(flowId);
+	if (!flow) throw new CapletsError("REQUEST_INVALID", `Unknown auth flow ${flowId}`);
+	context.authFlowStore?.delete(flowId);
+	await flow.complete(callbackUrl);
+	return {
+		server: flow.server,
+		authenticated: true
+	};
+}
+function dispatchAdd(args, context) {
+	const kind = requiredString(args, "kind");
+	const id = requiredString(args, "id");
+	const options = remoteAddOptions$1(kind, optionalObject(args, "options"));
+	switch (kind) {
+		case "cli": return {
+			remote: true,
+			label: "CLI",
+			...addCliCaplet(id, {
+				...options,
+				destinationRoot: context.projectCapletsRoot,
+				print: false
+			})
+		};
+		case "mcp": return {
+			remote: true,
+			label: "MCP",
+			...addMcpCaplet(id, {
+				...options,
+				destinationRoot: context.projectCapletsRoot,
+				print: false
+			})
+		};
+		case "openapi": return {
+			remote: true,
+			label: "OpenAPI",
+			...addOpenApiCaplet(id, {
+				...options,
+				destinationRoot: context.projectCapletsRoot,
+				print: false
+			})
+		};
+		case "graphql": return {
+			remote: true,
+			label: "GraphQL",
+			...addGraphqlCaplet(id, {
+				...options,
+				destinationRoot: context.projectCapletsRoot,
+				print: false
+			})
+		};
+		case "http": return {
+			remote: true,
+			label: "HTTP",
+			...addHttpCaplet(id, {
+				...options,
+				destinationRoot: context.projectCapletsRoot,
+				print: false
+			})
+		};
+		default: throw new CapletsError("REQUEST_INVALID", "add.kind must be cli, mcp, openapi, graphql, or http");
+	}
+}
+function optionalProp(key, value) {
+	return value === void 0 ? {} : { [key]: value };
+}
+function assertObject(value, label) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new CapletsError("REQUEST_INVALID", `${label} must be an object`);
+}
+function requiredString(args, key) {
+	const value = args[key];
+	if (typeof value !== "string" || value.length === 0) throw new CapletsError("REQUEST_INVALID", `${key} must be a non-empty string`);
+	return value;
+}
+function optionalObject(args, key) {
+	const value = args[key];
+	if (value === void 0) return {};
+	assertObject(value, key);
+	return value;
+}
+function requiredEngineRequest(args, command) {
+	const toolRequest = optionalObject(args, "request");
+	if (typeof toolRequest.operation !== "string") throw new CapletsError("REQUEST_INVALID", "request.operation must be a string");
+	if (toolRequest.operation !== command) throw new CapletsError("REQUEST_INVALID", `request.operation must match remote command ${command}`);
+	return toolRequest;
+}
+function remoteAddOptions$1(kind, options) {
+	rejectServerOwnedAddOptions(options);
+	switch (kind) {
+		case "cli": return pickOptions(options, {
+			repo: "string",
+			include: "string",
+			command: "string",
+			force: "boolean"
+		});
+		case "mcp": return pickOptions(options, {
+			command: "string",
+			arg: "string-array",
+			cwd: "string",
+			env: "string-array",
+			url: "string",
+			transport: "string",
+			tokenEnv: "string",
+			force: "boolean"
+		});
+		case "openapi": return pickOptions(options, {
+			spec: "string",
+			baseUrl: "string",
+			tokenEnv: "string",
+			force: "boolean"
+		});
+		case "graphql": return pickOptions(options, {
+			endpointUrl: "string",
+			schema: "string",
+			introspection: "boolean",
+			tokenEnv: "string",
+			force: "boolean"
+		});
+		case "http": return pickOptions(options, {
+			baseUrl: "string",
+			action: "string-array",
+			tokenEnv: "string",
+			force: "boolean"
+		});
+		default: return options;
+	}
+}
+function pickOptions(options, schema) {
+	const next = {};
+	for (const [key, type] of Object.entries(schema)) {
+		const value = options[key];
+		if (value === void 0) continue;
+		validateOptionType(key, value, type);
+		next[key] = value;
+	}
+	return next;
+}
+function rejectServerOwnedAddOptions(options) {
+	if ("output" in options) throw new CapletsError("REQUEST_INVALID", "Remote add output is not supported remotely; the server owns destinationRoot and output path selection");
+	for (const key of ["destinationRoot", "print"]) if (key in options) throw new CapletsError("REQUEST_INVALID", `Remote add ${key} is not supported remotely; the server owns destinationRoot and print behavior`);
+}
+function validateOptionType(key, value, type) {
+	if (type === "string" && typeof value !== "string") throw new CapletsError("REQUEST_INVALID", `add.options.${key} must be a string`);
+	if (type === "boolean" && typeof value !== "boolean") throw new CapletsError("REQUEST_INVALID", `add.options.${key} must be a boolean`);
+	if (type === "string-array") {
+		if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) throw new CapletsError("REQUEST_INVALID", `add.options.${key} must be an array of strings`);
+	}
+}
+function optionalBoolean(args, key) {
+	const value = args[key];
+	if (value === void 0) return;
+	if (typeof value !== "boolean") throw new CapletsError("REQUEST_INVALID", `${key} must be a boolean`);
+	return value;
+}
+function optionalStringArray(args, key) {
+	const value = args[key];
+	if (value === void 0) return;
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) throw new CapletsError("REQUEST_INVALID", `${key} must be an array of strings`);
+	return value;
+}
+function nextAction(details) {
+	if (details && typeof details === "object" && "nextAction" in details) {
+		const value = details.nextAction;
+		return typeof value === "string" ? value : void 0;
+	}
+}
+function redactControlErrorMessage(message) {
+	return message.replace(/(["'])(authorization|(?:access[_-]?)?token|refresh(?:[_-]?token)?|password|client[_-]?secret|clientsecret|api[-_]?key|apikey|secret|credential|code)\1\s*:\s*(["'])(?:\\.|[^\\])*?\3/giu, "$1$2$1:$3[REDACTED]$3").replace(/\b(authorization\s*:\s*(?:basic|bearer)\s+)[^\s,;]+/giu, "$1[REDACTED]").replace(/\b((?:access[_-]?)?token|refresh(?:[_-]?token)?|password|client[_-]?secret|clientsecret|api[-_]?key|apikey|secret|credential|code)(\s*[=:]\s*)[^\s,;]+/giu, "$1$2[REDACTED]");
+}
+const DEFAULT_AUTH_FLOW_TTL_MS = 600 * 1e3;
+var RemoteAuthFlowStore = class {
+	options;
+	flows = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	create(flow, id = randomUUID()) {
+		this.pruneExpired();
+		const created = {
+			id,
+			createdAt: this.now(),
+			...flow
+		};
+		this.flows.set(created.id, created);
+		return { ...created };
+	}
+	get(id) {
+		this.pruneExpired();
+		const flow = this.flows.get(id);
+		if (flow && this.isExpired(flow)) {
+			this.flows.delete(id);
+			return;
+		}
+		return flow;
+	}
+	delete(id) {
+		this.flows.delete(id);
+	}
+	pruneExpired() {
+		for (const [id, flow] of this.flows) if (this.isExpired(flow)) this.flows.delete(id);
+	}
+	isExpired(flow) {
+		return this.now() - flow.createdAt > (this.options.ttlMs ?? DEFAULT_AUTH_FLOW_TTL_MS);
+	}
+	now() {
+		return this.options.now?.() ?? Date.now();
+	}
+};
 function createHttpServeApp(options, engine, io = {}) {
 	const app = new Hono();
 	const sessions = /* @__PURE__ */ new Map();
 	const writeErr = io.writeErr ?? process.stderr.write.bind(process.stderr);
+	const paths = servicePaths(options.path);
+	const authFlowStore = io.authFlowStore ?? new RemoteAuthFlowStore();
 	app.use("*", logger((message, ...rest) => {
 		writeErr(`${[message, ...rest].join(" ")}\n`);
 	}));
-	app.get("/", (c) => c.json({
+	app.get(paths.base, (c) => c.json({
 		name: "caplets",
 		transport: "http",
-		mcp: options.path,
-		health: "/healthz",
+		base: paths.base,
+		mcp: paths.mcp,
+		control: paths.control,
+		health: paths.health,
 		auth: {
 			type: "basic",
 			enabled: options.auth.enabled
 		}
 	}));
-	app.get("/healthz", (c) => c.json({
+	app.get(paths.health, (c) => c.json({
 		status: "ok",
 		transport: "http",
-		mcpPath: options.path
+		base: paths.base,
+		mcpPath: paths.mcp,
+		controlPath: paths.control,
+		healthPath: paths.health
 	}));
-	app.all(options.path, basicAuth(options.auth), async (c) => {
+	app.all(paths.mcp, basicAuth(options.auth), async (c) => {
 		const sessionId = c.req.header("mcp-session-id");
 		if (sessionId) {
 			const existing = sessions.get(sessionId);
@@ -65474,6 +66099,36 @@ function createHttpServeApp(options, engine, io = {}) {
 		sessions.set(nextSessionId, session);
 		return session.transport.handleRequest(c);
 	});
+	app.post(paths.control, basicAuth(options.auth), async (c) => {
+		let request;
+		try {
+			const parsed = await c.req.json();
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new CapletsError("REQUEST_INVALID", "Control request JSON must be an object");
+			request = parsed;
+		} catch (error) {
+			const safe = toSafeError(error instanceof CapletsError ? error : new CapletsError("REQUEST_INVALID", "Control request body must be valid JSON", error), "REQUEST_INVALID");
+			return c.json({
+				ok: false,
+				error: {
+					code: safe.code,
+					message: safe.message
+				}
+			});
+		}
+		return c.json(await dispatchRemoteCliRequest(request, controlContext(io, writeErr, authFlowStore, c.req.url, paths.control, options.trustProxy, (name) => c.req.header(name))));
+	});
+	app.get(routePath(paths.control, "auth/callback/:flowId"), async (c) => {
+		const flowId = c.req.param("flowId");
+		const result = await dispatchRemoteCliRequest({
+			command: "auth_login_complete",
+			arguments: {
+				flowId,
+				callbackUrl: c.req.url
+			}
+		}, controlContext(io, writeErr, authFlowStore, c.req.url, paths.control, options.trustProxy, (name) => c.req.header(name)));
+		if (!result.ok) writeErr(`Caplets authentication failed for flow ${flowId}: ${result.error.message}\n`);
+		return result.ok ? c.text("Caplets authentication complete. You can return to your terminal.") : c.text("Caplets authentication failed. Check server logs for details.", 400);
+	});
 	app.notFound((c) => c.json({ error: "not_found" }, 404));
 	app.closeCapletsSessions = async () => {
 		await Promise.allSettled([...sessions.values()].map(async (session) => {
@@ -65484,19 +66139,66 @@ function createHttpServeApp(options, engine, io = {}) {
 	if (options.warnUnauthenticatedNetwork) writeErr(`Warning: Caplets MCP HTTP server is listening on ${options.host} without authentication.\n`);
 	return app;
 }
+function controlContext(io, writeErr, authFlowStore, requestUrl, controlPath, trustProxy, header) {
+	return {
+		...io.control,
+		projectCapletsRoot: io.control?.projectCapletsRoot ?? resolveProjectCapletsRoot(),
+		authFlowStore,
+		controlCallbackBaseUrl: new URL(controlPath, publicRequestOrigin(requestUrl, trustProxy, header)).toString(),
+		writeErr
+	};
+}
+function publicRequestOrigin(requestUrl, trustProxy, header) {
+	const url = new URL(requestUrl);
+	if (!trustProxy) return `${url.protocol.slice(0, -1)}://${header("host") ?? url.host}`;
+	const forwardedProto = firstForwardedValue(header("x-forwarded-proto"));
+	const forwardedHost = firstForwardedValue(header("x-forwarded-host"));
+	return `${forwardedProto === "http" || forwardedProto === "https" ? forwardedProto : url.protocol.slice(0, -1)}://${forwardedHost ?? header("host") ?? url.host}`;
+}
+function firstForwardedValue(value) {
+	return value?.split(",", 1)[0]?.trim() || void 0;
+}
 async function serveHttp(options, engineOptions = {}, writeErr = (value) => process.stderr.write(value)) {
 	const engine = new CapletsEngine(engineOptions);
-	const app = createHttpServeApp(options, engine, { writeErr });
+	const app = createHttpServeApp(options, engine, {
+		writeErr,
+		control: {
+			...engineOptions,
+			projectCapletsRoot: projectCapletsRootForEngineOptions(engineOptions)
+		}
+	});
+	const paths = servicePaths(options.path);
+	const origin = `http://${formatHost(options.host)}:${options.port}`;
+	const baseUrl = `${origin}${paths.base === "/" ? "" : paths.base}`;
 	installHttpSignalHandlers(serve({
 		fetch: app.fetch,
 		hostname: options.host,
 		port: options.port
 	}, () => {
-		writeErr(`Caplets MCP HTTP server listening on http://${formatHost(options.host)}:${options.port}${options.path}\n`);
-		writeErr(`Health check: http://${formatHost(options.host)}:${options.port}/healthz\n`);
+		writeErr(`Caplets HTTP service listening on ${baseUrl}\n`);
+		writeErr(`MCP endpoint: ${origin}${paths.mcp}\n`);
+		writeErr(`Control endpoint: ${origin}${paths.control}\n`);
+		writeErr(`Health check: ${origin}${paths.health}\n`);
 		writeErr(`Basic Auth: ${options.auth.enabled ? `enabled (user: ${options.auth.user})` : "disabled"}\n`);
 	}), app, engine, writeErr);
 }
+function projectCapletsRootForEngineOptions(engineOptions) {
+	return engineOptions.projectConfigPath ? resolveProjectCapletsRootForConfigPath(engineOptions.projectConfigPath) : resolveProjectCapletsRoot();
+}
+function resolveProjectCapletsRootForConfigPath(projectConfigPath) {
+	return dirname(projectConfigPath);
+}
+function routePath(base, path) {
+	return base === "/" ? `/${path}` : `${base}/${path}`;
+}
+function servicePaths(base) {
+	return {
+		base,
+		mcp: routePath(base, "mcp"),
+		control: routePath(base, "control"),
+		health: routePath(base, "healthz")
+	};
+}
 async function createHttpSession(engine, sessionId, options, onClose) {
 	const transport = new StreamableHTTPTransport({
 		sessionIdGenerator: () => sessionId,
@@ -65574,7 +66276,8 @@ const HTTP_ONLY_OPTIONS = [
 	"path",
 	"user",
 	"password",
-	"allowUnauthenticatedHttp"
+	"allowUnauthenticatedHttp",
+	"trustProxy"
 ];
 function resolveServeOptions(raw, env = process.env) {
 	const transport = parseTransport(raw.transport ?? "stdio");
@@ -65583,9 +66286,10 @@ function resolveServeOptions(raw, env = process.env) {
 		if (invalid.length > 0) throw new CapletsError("REQUEST_INVALID", `${invalid.map((key) => `--${key}`).join(", ")} ${invalid.length === 1 ? "is" : "are"} only valid with --transport http`);
 		return { transport };
 	}
-	const host = nonEmpty(raw.host, "--host") ?? "127.0.0.1";
-	const port = parsePort(raw.port ?? 5387);
-	const path = normalizeHttpPath(raw.path ?? "/mcp");
+	const serverUrl = env.CAPLETS_SERVER_URL ? parseServeServerUrl(nonEmpty(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL")) : void 0;
+	const host = nonEmpty(raw.host, "--host") ?? serverUrlHost(serverUrl) ?? "127.0.0.1";
+	const port = parsePort(raw.port ?? (serverUrl?.port ? Number(serverUrl.port) : 5387));
+	const path = normalizeHttpPath(raw.path ?? serverUrl?.pathname ?? "/");
 	const userWasExplicit = raw.user !== void 0 || hasEnv(env.CAPLETS_SERVER_USER);
 	const user = nonEmpty(raw.user, "--user") ?? nonEmpty(env.CAPLETS_SERVER_USER, "CAPLETS_SERVER_USER") ?? "caplets";
 	const password = nonEmpty(raw.password, "--password") ?? nonEmpty(env.CAPLETS_SERVER_PASSWORD, "CAPLETS_SERVER_PASSWORD");
@@ -65607,13 +66311,22 @@ function resolveServeOptions(raw, env = process.env) {
 		path,
 		auth,
 		warnUnauthenticatedNetwork: !loopback && !auth.enabled,
-		loopback
+		loopback,
+		trustProxy: raw.trustProxy === true
 	};
 }
 function isLoopbackHost(host) {
 	const normalized = host.toLocaleLowerCase();
 	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
 }
+function parseServeServerUrl(value) {
+	try {
+		return parseServerBaseUrl(value);
+	} catch (error) {
+		if (error instanceof CapletsError && error.message.includes("must use https except loopback development URLs")) throw new CapletsError("REQUEST_INVALID", "CAPLETS_SERVER_URL must use https except loopback development URLs; use --host, --port, and --path separately for non-loopback HTTP bind addresses.");
+		throw error;
+	}
+}
 function parseTransport(value) {
 	if (value === "stdio" || value === "http") return value;
 	throw new CapletsError("REQUEST_INVALID", `Expected --transport to be stdio or http, got ${value}`);
@@ -65628,6 +66341,9 @@ function normalizeHttpPath(value) {
 	if (value.includes("?") || value.includes("#")) throw new CapletsError("REQUEST_INVALID", "HTTP --path must not include a query string or fragment");
 	return value === "/" ? value : value.replace(/\/+$/u, "");
 }
+function serverUrlHost(url) {
+	return url?.hostname.replace(/^\[(.*)\]$/u, "$1");
+}
 function nonEmpty(value, label) {
 	if (value === void 0) return;
 	const trimmed = value.trim();
@@ -65754,6 +66470,8 @@ async function runCli(args, io = {}) {
 function createProgram(io = {}) {
 	const writeOut = io.writeOut ?? ((value) => process.stdout.write(value));
 	const writeErr = io.writeErr ?? ((value) => process.stderr.write(value));
+	const env = io.env ?? process.env;
+	const currentConfigPath = () => envConfigPath(env);
 	const setExitCode = io.setExitCode ?? ((code) => {
 		process.exitCode = code;
 	});
@@ -65763,42 +66481,78 @@ function createProgram(io = {}) {
 		writeErr,
 		outputError: (value, write) => write(value)
 	});
-	program.command("serve").description("Serve configured Caplets as an MCP server.").option("--transport <transport>", "server transport: stdio or http").option("--host <host>", "HTTP bind host").option("--port <port>", "HTTP bind port").option("--path <path>", "HTTP MCP endpoint path").option("--user <user>", "HTTP Basic Auth username").option("--password <password>", "HTTP Basic Auth password").option("--allow-unauthenticated-http", "allow unauthenticated HTTP serving on non-loopback hosts").action(async (options) => {
+	program.command("serve").description("Serve configured Caplets as an MCP server.").option("--transport <transport>", "server transport: stdio or http").option("--host <host>", "HTTP bind host").option("--port <port>", "HTTP bind port").option("--path <path>", "HTTP service base path").option("--user <user>", "HTTP Basic Auth username").option("--password <password>", "HTTP Basic Auth password").option("--allow-unauthenticated-http", "allow unauthenticated HTTP serving on non-loopback hosts").option("--trust-proxy", "trust X-Forwarded-* headers from a reverse proxy").action(async (options) => {
 		const resolved = resolveServeOptions(options);
-		const configPath = envConfigPath();
+		const configPath = currentConfigPath();
 		await (io.serve ?? ((serveOptions) => serveResolvedCaplets(serveOptions, {
 			...configPath ? { configPath } : {},
 			...io.authDir ? { authDir: io.authDir } : {}
 		}, writeErr)))(resolved);
 	});
-	program.command("init").description("Create a starter Caplets config file.").option("--force", "overwrite an existing config file").action((options) => {
-		const configPath = envConfigPath();
+	program.command("init").description("Create a starter Caplets config file.").option("--force", "overwrite an existing config file").action(async (options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeOut(`Created remote Caplets config at ${(await remote.request("init", { force: Boolean(options.force) })).path}\n`);
+			return;
+		}
+		const configPath = currentConfigPath();
 		writeOut(`Created Caplets config at ${initConfig({
 			...configPath ? { path: configPath } : {},
 			force: Boolean(options.force)
 		})}\n`);
 	});
-	program.command("list").description("List configured Caplets.").option("--all", "include disabled Caplets").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action((options) => {
-		const rows = listCaplets(loadConfigWithSources(envConfigPath()), { includeDisabled: Boolean(options.all) });
+	program.command("list").description("List configured Caplets.").option("--all", "include disabled Caplets").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action(async (options) => {
+		const includeDisabled = Boolean(options.all);
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			const rows = await remote.request("list", { includeDisabled });
+			if (options.json || options.format === "json") {
+				writeOut(`${JSON.stringify(rows, null, 2)}\n`);
+				return;
+			}
+			writeOut(formatCapletList(rows, options.format ?? "plain"));
+			return;
+		}
+		const rows = listCaplets(loadConfigWithSources(currentConfigPath()), { includeDisabled });
 		if (options.json || options.format === "json") {
 			writeOut(`${JSON.stringify(rows, null, 2)}\n`);
 			return;
 		}
 		writeOut(formatCapletList(rows, options.format ?? "plain"));
 	});
-	program.command("install").description("Install Caplets from a repo's caplets directory.").argument("<repo>", "local repo path, Git URL, or GitHub owner/repo").argument("[caplets...]", "optional Caplet IDs to install").option("-g, --global", "install to the user Caplets root").option("--force", "overwrite installed Caplets").action((repo, capletIds, options) => {
+	program.command("install").description("Install Caplets from a repo's caplets directory.").argument("<repo>", "local repo path, Git URL, or GitHub owner/repo").argument("[caplets...]", "optional Caplet IDs to install").option("-g, --global", "install to the user Caplets root").option("--force", "overwrite installed Caplets").action(async (repo, capletIds, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			if (options.global) writeErr("Warning: --global is not supported in remote mode; the server controls the installation destination.\n");
+			const result = await remote.request("install", {
+				repo,
+				capletIds,
+				force: Boolean(options.force)
+			});
+			for (const caplet of result.installed) writeOut(`Installed ${caplet.id} to remote ${caplet.destination}\n`);
+			return;
+		}
 		const result = installCaplets(repo, {
 			capletIds,
 			force: Boolean(options.force),
-			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(envConfigPath())) : resolveProjectCapletsRoot()
+			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : resolveProjectCapletsRoot()
 		});
 		for (const caplet of result.installed) writeOut(`Installed ${caplet.id} to ${caplet.destination}\n`);
 	});
 	const add = program.command("add").description("Add generated Caplet files.");
-	add.command("cli").description("Add a CLI tools Caplet.").argument("<id>", "Caplet ID/display seed").option("--repo <path>", "repository path to inspect").option("--include <items>", "comma-separated generators to include: git,gh,package").option("--command <name>", "single CLI command template to generate").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action((id, options) => {
+	add.command("cli").description("Add a CLI tools Caplet.").argument("<id>", "Caplet ID/display seed").option("--repo <path>", "repository path to inspect").option("--include <items>", "comma-separated generators to include: git,gh,package").option("--command <name>", "single CLI command template to generate").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeAddResult(writeOut, "CLI", await remote.request("add", {
+				kind: "cli",
+				id,
+				options: remoteAddOptions(options)
+			}));
+			return;
+		}
 		const result = addCliCaplet(id, {
 			...options,
-			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(envConfigPath())) : resolveProjectCapletsRoot()
+			destinationRoot: options.global ? resolveCapletsRoot(resolveConfigPath(currentConfigPath())) : resolveProjectCapletsRoot()
 		});
 		if (result.path) {
 			writeOut(`Wrote CLI Caplet to ${result.path}\n`);
@@ -65806,28 +66560,64 @@ function createProgram(io = {}) {
 		}
 		writeOut(result.text);
 	});
-	add.command("mcp").description("Add an MCP backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--command <name>", "stdio command").option("--arg <value>", "stdio command argument", collect, []).option("--cwd <path>", "stdio working directory").option("--env <KEY=VALUE>", "stdio environment variable", collect, []).option("--url <url>", "remote MCP server URL").option("--transport <transport>", "remote transport: http or sse").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action((id, options) => {
+	add.command("mcp").description("Add an MCP backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--command <name>", "stdio command").option("--arg <value>", "stdio command argument", collect, []).option("--cwd <path>", "stdio working directory").option("--env <KEY=VALUE>", "stdio environment variable", collect, []).option("--url <url>", "remote MCP server URL").option("--transport <transport>", "remote transport: http or sse").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeAddResult(writeOut, "MCP", await remote.request("add", {
+				kind: "mcp",
+				id,
+				options: remoteAddOptions(options)
+			}));
+			return;
+		}
 		writeAddResult(writeOut, "MCP", addMcpCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options)
+			destinationRoot: addDestinationRoot(options, currentConfigPath())
 		}));
 	});
-	add.command("openapi").description("Add an OpenAPI backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--spec <path-or-url>", "OpenAPI spec path or URL").option("--base-url <url>", "request base URL override").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action((id, options) => {
+	add.command("openapi").description("Add an OpenAPI backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--spec <path-or-url>", "OpenAPI spec path or URL").option("--base-url <url>", "request base URL override").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeAddResult(writeOut, "OpenAPI", await remote.request("add", {
+				kind: "openapi",
+				id,
+				options: remoteAddOptions(options)
+			}));
+			return;
+		}
 		writeAddResult(writeOut, "OpenAPI", addOpenApiCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options)
+			destinationRoot: addDestinationRoot(options, currentConfigPath())
 		}));
 	});
-	add.command("graphql").description("Add a GraphQL backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--endpoint-url <url>", "GraphQL endpoint URL").option("--schema <path-or-url>", "GraphQL schema path or URL").option("--introspection", "load schema through endpoint introspection").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action((id, options) => {
+	add.command("graphql").description("Add a GraphQL backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--endpoint-url <url>", "GraphQL endpoint URL").option("--schema <path-or-url>", "GraphQL schema path or URL").option("--introspection", "load schema through endpoint introspection").option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeAddResult(writeOut, "GraphQL", await remote.request("add", {
+				kind: "graphql",
+				id,
+				options: remoteAddOptions(options)
+			}));
+			return;
+		}
 		writeAddResult(writeOut, "GraphQL", addGraphqlCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options)
+			destinationRoot: addDestinationRoot(options, currentConfigPath())
 		}));
 	});
-	add.command("http").description("Add an HTTP actions backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--base-url <url>", "HTTP API base URL").option("--action <name:METHOD:/path>", "HTTP action", collect, []).option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action((id, options) => {
+	add.command("http").description("Add an HTTP actions backend Caplet.").argument("<id>", "Caplet ID/display seed").option("--base-url <url>", "HTTP API base URL").option("--action <name:METHOD:/path>", "HTTP action", collect, []).option("--token-env <ENV>", "bearer token environment variable reference").option("-g, --global", "write to the user Caplets root").option("--print", "print generated Caplet text without writing a file").option("--output <path>", "output path").option("--force", "overwrite an existing destination file").action(async (id, options) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeAddResult(writeOut, "HTTP", await remote.request("add", {
+				kind: "http",
+				id,
+				options: remoteAddOptions(options)
+			}));
+			return;
+		}
 		writeAddResult(writeOut, "HTTP", addHttpCaplet(id, {
 			...options,
-			destinationRoot: addDestinationRoot(options)
+			destinationRoot: addDestinationRoot(options, currentConfigPath())
 		}));
 	});
 	program.command("get-caplet").description("Print a configured Caplet card.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
@@ -65836,6 +66626,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -65845,6 +66637,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -65854,6 +66648,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -65870,6 +66666,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -65883,6 +66681,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -65898,15 +66698,17 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
 	const config = program.command("config").description("Inspect Caplets config locations.");
 	config.command("path").description("Print the effective user config path.").action(() => {
-		writeOut(`${resolveConfigPath(envConfigPath())}\n`);
+		writeOut(`${resolveConfigPath(currentConfigPath())}\n`);
 	});
 	config.command("paths").description("Print resolved Caplets config, root, and auth paths.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action((options) => {
-		const paths = resolveCliConfigPaths(envConfigPath(), io.authDir);
+		const paths = resolveCliConfigPaths(currentConfigPath(), io.authDir);
 		if (options.json || options.format === "json") {
 			writeOut(`${JSON.stringify(paths, null, 2)}\n`);
 			return;
@@ -65915,7 +66717,19 @@ function createProgram(io = {}) {
 	});
 	const auth = program.command("auth").description("Manage OAuth credentials for remote servers.");
 	auth.command("login").description("Authenticate a configured remote OAuth server.").argument("<server>", "configured server ID").option("--no-open", "print the authorization URL without opening a browser").action(async (serverId, options) => {
-		const configPath = envConfigPath();
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			const started = await remote.request("auth_login_start", { server: serverId });
+			if (started.authorizationUrl) {
+				writeOut(`Open this URL to authorize ${serverId}:\n${started.authorizationUrl}\n`);
+				if (options.open !== false) await openBrowser(started.authorizationUrl);
+				writeOut("Complete authentication in your browser. The server callback will store credentials.\n");
+				return;
+			}
+			if (started.authenticated) writeOut(`Authenticated \`${serverId}\`.\n`);
+			return;
+		}
+		const configPath = currentConfigPath();
 		await loginAuth(serverId, {
 			noOpen: options.open === false,
 			writeOut,
@@ -65924,27 +66738,78 @@ function createProgram(io = {}) {
 			...io.authDir ? { authDir: io.authDir } : {}
 		});
 	});
-	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").action((serverId) => {
-		const configPath = envConfigPath();
+	auth.command("logout").description("Delete stored OAuth credentials for a server.").argument("<server>", "configured server ID").action(async (serverId) => {
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			writeOut((await remote.request("auth_logout", { server: serverId })).deleted ? `Deleted remote OAuth credentials for \`${serverId}\`.\n` : `No remote OAuth credentials found for \`${serverId}\`.\n`);
+			return;
+		}
+		const configPath = currentConfigPath();
 		logoutAuth(serverId, {
 			writeOut,
 			...configPath ? { configPath } : {},
 			...io.authDir ? { authDir: io.authDir } : {}
 		});
 	});
-	auth.command("list").description("List servers with stored OAuth credentials.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action((options) => {
-		const configPath = envConfigPath();
+	auth.command("list").description("List servers with stored OAuth credentials.").option("--json", "print JSON output").option("--format <format>", "output format: plain, markdown, md, or json", parseOutputFormat).action(async (options) => {
+		const configPath = currentConfigPath();
+		const format = options.json || options.format === "json" ? "json" : options.format ?? "plain";
+		const remote = remoteClientForCli(io);
+		if (remote) {
+			const rows = await remote.request("auth_list", {});
+			if (format === "json") {
+				writeOut(`${JSON.stringify(rows, null, 2)}\n`);
+				return;
+			}
+			writeOut(formatAuthRows(rows, format));
+			return;
+		}
 		listAuth({
 			writeOut,
-			format: options.json || options.format === "json" ? "json" : options.format ?? "plain",
+			format,
 			...configPath ? { configPath } : {},
 			...io.authDir ? { authDir: io.authDir } : {}
 		});
 	});
 	return program;
 }
-function envConfigPath() {
-	return process.env.CAPLETS_CONFIG?.trim() || void 0;
+function envConfigPath(env) {
+	return env.CAPLETS_CONFIG?.trim() || void 0;
+}
+function remoteClientForCli(io) {
+	const env = io.env ?? process.env;
+	if (resolveCapletsMode({}, env).mode !== "remote") return;
+	return new RemoteControlClient(resolveCapletsServer(io.fetch ? { fetch: io.fetch } : {}, env));
+}
+async function openBrowser(url) {
+	const { spawn } = await import("node:child_process");
+	spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open", process.platform === "win32" ? [
+		"/c",
+		"start",
+		"",
+		url
+	] : [url], {
+		stdio: "ignore",
+		detached: true
+	}).unref();
+}
+function remoteCommandForOperation(operation) {
+	switch (operation) {
+		case "get_caplet":
+		case "check_backend":
+		case "list_tools":
+		case "search_tools":
+		case "get_tool":
+		case "call_tool": return operation;
+		default: return;
+	}
+}
+function remoteAddOptions(options) {
+	const { output, print, global, destinationRoot, ...remoteOptions } = options;
+	if (global) throw new CapletsError("REQUEST_INVALID", "--global is not supported in remote mode; the server controls the add destination.");
+	if (print) throw new CapletsError("REQUEST_INVALID", "--print is not supported in remote mode; the server controls add output.");
+	if (output !== void 0) throw new CapletsError("REQUEST_INVALID", "--output is not supported in remote mode; the server controls the add destination.");
+	return remoteOptions;
 }
 function collect(value, previous) {
 	previous.push(value);
@@ -65987,7 +66852,21 @@ function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 async function executeOperation(caplet, request, io) {
-	const configPath = envConfigPath();
+	const command = remoteCommandForOperation(request.operation);
+	if (io.remote && command) {
+		const result = await io.remote.request(command, {
+			caplet,
+			request
+		});
+		const output = cliOutputForOperation(result, {
+			...request,
+			caplet
+		}, io.format ?? "markdown");
+		io.writeOut(typeof output === "string" ? `${output}\n` : `${JSON.stringify(output, null, 2)}\n`);
+		if (isPlainObject(result) && result.isError === true) io.setExitCode(1);
+		return;
+	}
+	const configPath = envConfigPath(io.env ?? process.env);
 	const engine = new CapletsEngine({
 		...configPath ? { configPath } : {},
 		...io.authDir ? { authDir: io.authDir } : {},
@@ -66233,19 +67112,19 @@ function schemaSummary(schema) {
 		required.length > 0 ? `required ${required.join(", ")}` : "no required fields"
 	].filter((part) => Boolean(part)).join("; ");
 }
-function addDestinationRoot(options) {
-	return options.global ? resolveCapletsRoot(resolveConfigPath(envConfigPath())) : resolveProjectCapletsRoot();
+function addDestinationRoot(options, configPath) {
+	return options.global ? resolveCapletsRoot(resolveConfigPath(configPath)) : resolveProjectCapletsRoot();
 }
 function writeAddResult(writeOut, label, result) {
 	if (result.path) {
-		writeOut(`Wrote ${label} Caplet to ${result.path}\n`);
+		writeOut(`Wrote ${result.remote ? "remote " : ""}${label} Caplet to ${result.path}\n`);
 		return;
 	}
 	writeOut(result.text);
 }
 //#endregion
 //#region package.json
-var version = "0.15.0";
+var version = "0.16.0";
 //#endregion
 //#region src/index.ts
 async function main() {