@caplets/core 0.16.0 → 0.17.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as getLiteralValue, A as ErrorCode, B as ListToolsRequestSchema, C as CompleteRequestSchema, Ct as string, Dt as __commonJSMin, E as CreateTaskResultSchema, Et as toSafeError, F as LATEST_PROTOCOL_VERSION, G as SetLevelRequestSchema, H as McpError, I as ListPromptsRequestSchema, J as assertCompleteRequestResourceTemplate, L as ListResourceTemplatesRequestSchema, M as InitializeRequestSchema, N as InitializedNotificationSchema, O as ElicitResultSchema, Ot as __require, P as JSONRPCMessageSchema, Q as isJSONRPCResultResponse, R as ListResourcesRequestSchema, S as CallToolResultSchema, St as object, T as CreateMessageResultWithToolsSchema, Tt as CapletsError, U as ReadResourceRequestSchema, V as LoggingLevelSchema, W as SUPPORTED_PROTOCOL_VERSIONS, X as isJSONRPCErrorResponse, Y as isInitializeRequest, Z as isJSONRPCRequest, _ as AjvJsonSchemaValidator, _t as discoverCapletFiles, a as capabilityDescription, at as normalizeObjectSchema, b as toJsonSchemaCompat, bt as ZodOptional, c as deleteTokenBundle, ct as safeParseAsync, dt as parseConfig, et as getObjectShape, f as ReadBuffer, ft as DEFAULT_AUTH_DIR, g as assertToolsCallTaskCapability, gt as resolveProjectConfigPath, h as assertClientRequestTaskCapability, ht as resolveProjectCapletsRoot, i as ServerRegistry, it as isZ4Schema, j as GetPromptRequestSchema, k as EmptyResultSchema, kt as __toESM, l as isTokenBundleExpired, lt as loadConfig, mt as resolveConfigPath, n as generatedToolInputSchema, nt as getSchemaDescription, o as runGenericOAuthFlow, ot as objectFromShape, p as serializeMessage, pt as resolveCapletsRoot, q as assertCompleteRequestPrompt, r as handleServerTool, rt as isSchemaOptional, s as runOAuthFlow, st as safeParse, t as CapletsEngine, tt as getParseErrorMessage, u as readTokenBundle, ut as loadConfigWithSources, v as Protocol, vt as validateCapletFile, w as CreateMessageResultSchema, wt as url, x as CallToolRequestSchema, xt as literal, y as mergeCapabilities, yt as SERVER_ID_PATTERN, z as ListRootsResultSchema } from "./engine-Brwid_mq.js";
+import { A as CompleteRequestSchema, At as string, B as InitializedNotificationSchema, C as assertToolsCallTaskCapability, Ct as resolveProjectConfigPath, D as toJsonSchemaCompat, Dt as ZodOptional, E as mergeCapabilities, Et as SERVER_ID_PATTERN, F as ElicitResultSchema, Ft as toSafeError, G as ListResourcesRequestSchema, H as LATEST_PROTOCOL_VERSION, I as EmptyResultSchema, It as __commonJSMin, J as LoggingLevelSchema, K as ListRootsResultSchema, L as ErrorCode, Lt as __require, M as CreateMessageResultWithToolsSchema, Mt as CAPLETS_ERROR_CODES, N as CreateTaskResultSchema, Nt as CapletsError, O as CallToolRequestSchema, Ot as literal, Pt as redactSecrets, Q as SetLevelRequestSchema, R as GetPromptRequestSchema, Rt as __toESM, S as assertClientRequestTaskCapability, St as resolveProjectCapletsRoot, T as Protocol, Tt as validateCapletFile, U as ListPromptsRequestSchema, V as JSONRPCMessageSchema, W as ListResourceTemplatesRequestSchema, X as ReadResourceRequestSchema, Y as McpError, Z as SUPPORTED_PROTOCOL_VERSIONS, _ as readTokenBundle, _t as loadConfigWithSources, a as resolveCapletsServer, at as isJSONRPCResultResponse, b as serializeMessage, bt as resolveCapletsRoot, c as handleServerTool, ct as getParseErrorMessage, d as runGenericOAuthFlow, dt as isZ4Schema, et as assertCompleteRequestPrompt, f as runOAuthFlow, ft as normalizeObjectSchema, g as isTokenBundleExpired, gt as loadConfig, h as deleteTokenBundle, ht as safeParseAsync, i as resolveCapletsMode, it as isJSONRPCRequest, j as CreateMessageResultSchema, jt as url, k as CallToolResultSchema, kt as object, l as ServerRegistry, lt as getSchemaDescription, m as startOAuthFlow, mt as safeParse, nt as isInitializeRequest, o as CapletsEngine, ot as getLiteralValue, p as startGenericOAuthFlow, pt as objectFromShape, q as ListToolsRequestSchema, r as parseServerBaseUrl, rt as isJSONRPCErrorResponse, s as generatedToolInputSchema, st as getObjectShape, t as controlUrlForBase, tt as assertCompleteRequestResourceTemplate, u as capabilityDescription, ut as isSchemaOptional, vt as parseConfig, w as AjvJsonSchemaValidator, wt as discoverCapletFiles, xt as resolveConfigPath, y as ReadBuffer, yt as DEFAULT_AUTH_DIR, z as InitializeRequestSchema } from "./options-CJEOqS87.js";
 import { accessSync, chmodSync, closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, join, parse, relative, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -1319,7 +1319,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 } };
 //#endregion
 //#region package.json
-var version = "0.16.0";
+var version = "0.17.0";
 //#endregion
 //#region src/serve/session.ts
 var CapletsMcpSession = class {
@@ -4921,49 +4921,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);
@@ -5390,6 +5397,96 @@ function nearestExistingParent(path) {
 	return nearestExistingParent(parent);
 }
 //#endregion
+//#region src/remote-control/client.ts
+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]");
+}
+//#endregion
 //#region ../../node_modules/.pnpm/hono@4.12.19/node_modules/hono/dist/compose.js
 var compose = (middleware, onError, onNotFound) => {
 	return (context, next) => {
@@ -8309,30 +8406,348 @@ var logger = (fn = console.log) => {
 	};
 };
 //#endregion
+//#region src/remote-control/dispatch.ts
+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]");
+}
+//#endregion
+//#region src/remote-control/auth-flow.ts
+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();
+	}
+};
+//#endregion
 //#region src/serve/http.ts
 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);
@@ -8363,6 +8778,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) => {
@@ -8373,19 +8818,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,
@@ -8465,7 +8957,8 @@ const HTTP_ONLY_OPTIONS = [
 	"path",
 	"user",
 	"password",
-	"allowUnauthenticatedHttp"
+	"allowUnauthenticatedHttp",
+	"trustProxy"
 ];
 function resolveServeOptions(raw, env = process.env) {
 	const transport = parseTransport(raw.transport ?? "stdio");
@@ -8474,9 +8967,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");
@@ -8498,13 +8992,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}`);
@@ -8519,6 +9022,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();
@@ -8656,6 +9162,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;
 	});
@@ -8665,42 +9173,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`);
@@ -8708,28 +9252,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) => {
@@ -8738,6 +9318,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -8747,6 +9329,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -8756,6 +9340,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -8772,6 +9358,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -8785,6 +9373,8 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
@@ -8800,15 +9390,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;
@@ -8817,7 +9409,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,
@@ -8826,27 +9430,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);
@@ -8889,7 +9544,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 } : {},
@@ -9135,12 +9804,12 @@ 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);