@caplets/core 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,4 +1,6 @@
-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 { $ as assertCompleteRequestPrompt, A as CreateMessageResultSchema, At as toSafeError, B as JSONRPCMessageSchema, C as AjvJsonSchemaValidator, D as CallToolRequestSchema, Dt as CAPLETS_ERROR_CODES, E as toJsonSchemaCompat, Et as SERVER_ID_PATTERN, F as EmptyResultSchema, G as ListRootsResultSchema, H as ListPromptsRequestSchema, I as ErrorCode, J as McpError, K as ListToolsRequestSchema, L as GetPromptRequestSchema, M as CreateTaskResultSchema, Nt as __require, O as CallToolResultSchema, Ot as CapletsError, P as ElicitResultSchema, Pt as __toESM, R as InitializeRequestSchema, S as assertToolsCallTaskCapability, St as resolveProjectCapletsRoot, T as mergeCapabilities, Tt as validateCapletFile, U as ListResourceTemplatesRequestSchema, V as LATEST_PROTOCOL_VERSION, W as ListResourcesRequestSchema, X as SUPPORTED_PROTOCOL_VERSIONS, Y as ReadResourceRequestSchema, Z as SetLevelRequestSchema, _t as parseConfig, a as resolveCapletsServer, at as getLiteralValue, bt as resolveCapletsRoot, c as ServerRegistry, ct as getSchemaDescription, d as runOAuthFlow, dt as normalizeObjectSchema, et as assertCompleteRequestResourceTemplate, f as startGenericOAuthFlow, ft as objectFromShape, g as readTokenBundle, gt as loadConfigWithSources, h as isTokenBundleExpired, ht as loadConfig, i as resolveCapletsMode, it as isJSONRPCResultResponse, j as CreateMessageResultWithToolsSchema, jt as __commonJSMin, k as CompleteRequestSchema, kt as redactSecrets, l as capabilityDescription, lt as isSchemaOptional, m as deleteTokenBundle, mt as safeParseAsync, nt as isJSONRPCErrorResponse, o as CapletsEngine, ot as getObjectShape, p as startOAuthFlow, pt as safeParse, q as LoggingLevelSchema, r as parseServerBaseUrl, rt as isJSONRPCRequest, s as handleServerTool, st as getParseErrorMessage, t as controlUrlForBase, tt as isInitializeRequest, u as runGenericOAuthFlow, ut as isZ4Schema, v as ReadBuffer, w as Protocol, wt as discoverCapletFiles, x as assertClientRequestTaskCapability, xt as resolveConfigPath, y as serializeMessage, z as InitializedNotificationSchema } from "./options-DM1cMRcp.js";
+import { A as url, C as object, D as string, b as literal, d as ZodOptional, o as generatedToolInputSchema, s as generatedToolInputSchemaForCaplet } from "./generated-tool-input-schema-B6rce396.js";
+import { a as formatCapletList, c as resolveCliConfigPaths, l as cliCommands, n as completionScript, o as formatConfigPaths, s as listCaplets, t as completeCliWords, u as completionShells } from "./completion-CxGG6ae3.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 +1321,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 } };
 //#endregion
 //#region package.json
-var version = "0.16.0";
+var version = "0.18.0";
 //#endregion
 //#region src/serve/session.ts
 var CapletsMcpSession = class {
@@ -1363,6 +1365,7 @@ var CapletsMcpSession = class {
 			if (!previousCaplet || serializeCaplet(previousCaplet) !== serializeCaplet(caplet)) tool.update({
 				title: caplet.name,
 				description: capabilityDescription(caplet),
+				paramsSchema: generatedToolInputSchemaForCaplet(caplet).shape,
 				callback: async (request) => this.handleTool(serverId, request),
 				enabled: true
 			});
@@ -1376,7 +1379,7 @@ var CapletsMcpSession = class {
 		return this.server.registerTool(caplet.server, {
 			title: caplet.name,
 			description: capabilityDescription(caplet),
-			inputSchema: generatedToolInputSchema
+			inputSchema: generatedToolInputSchemaForCaplet(caplet).shape
 		}, async (request) => this.handleTool(caplet.server, request));
 	}
 	async handleTool(serverId, request) {
@@ -4921,49 +4924,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);
@@ -5035,126 +5045,6 @@ function starterConfig() {
 	}, null, 2);
 }
 //#endregion
-//#region src/cli/inspection.ts
-function listCaplets(configWithSources, options) {
-	const { config, sources, shadows } = configWithSources;
-	return allCaplets(config).filter((server) => options.includeDisabled || !server.disabled).map((server) => ({
-		server: server.server,
-		backend: server.backend,
-		name: server.name,
-		description: server.description,
-		disabled: server.disabled,
-		status: initialServerStatus(server),
-		source: sources[server.server]?.kind ?? "unknown",
-		path: sources[server.server]?.path ?? null,
-		shadows: shadows[server.server] ?? []
-	})).sort((left, right) => left.server.localeCompare(right.server));
-}
-function initialServerStatus(server) {
-	return server.disabled ? "disabled" : "not_started";
-}
-function allCaplets(config) {
-	return [
-		...Object.values(config.mcpServers),
-		...Object.values(config.openapiEndpoints),
-		...Object.values(config.graphqlEndpoints),
-		...Object.values(config.httpApis),
-		...Object.values(config.cliTools)
-	];
-}
-function formatCapletList(rows, format = "plain") {
-	return format === "markdown" ? formatCapletListMarkdown(rows) : formatCapletListPlain(rows);
-}
-function formatCapletListMarkdown(rows) {
-	if (rows.length === 0) return "## Configured Caplets\n\nNo configured Caplets found.\n";
-	const heading = [
-		"## Configured Caplets",
-		"",
-		`${rows.length} ${rows.length === 1 ? "Caplet" : "Caplets"} shown.`,
-		""
-	];
-	const entries = rows.flatMap((row) => [
-		`- \`${row.server}\` — ${row.name}`,
-		`  - Backend: ${row.backend}`,
-		`  - Status: ${row.status}`,
-		`  - Source: ${row.source}`,
-		...row.disabled ? ["  - Disabled: true"] : [],
-		...row.path ? [`  - Path: ${row.path}`] : []
-	]);
-	const warnings = rows.flatMap((row) => row.shadows.map((shadow) => `Warning: ${formatSourceKind(row.source)} Caplet ${row.server} shadows ${formatSourceKind(shadow.kind)} Caplet at ${shadow.path}`));
-	if (warnings.length === 0) return `${[...heading, ...entries].join("\n")}\n`;
-	return `${[
-		...heading,
-		...entries,
-		"",
-		"Warnings:",
-		...warnings.map((warning) => `- ${warning}`)
-	].join("\n")}\n`;
-}
-function formatCapletListPlain(rows) {
-	if (rows.length === 0) return "No configured Caplets found.\n";
-	const entries = rows.map((row) => [
-		row.server,
-		`  Name: ${row.name}`,
-		`  Backend: ${row.backend}`,
-		`  Status: ${row.status}`,
-		`  Source: ${row.source}`,
-		...row.disabled ? ["  Disabled: true"] : [],
-		...row.path ? [`  Path: ${row.path}`] : []
-	].join("\n")).join("\n\n");
-	const warnings = rows.flatMap((row) => row.shadows.map((shadow) => `Warning: ${formatSourceKind(row.source)} Caplet ${row.server} shadows ${formatSourceKind(shadow.kind)} Caplet at ${shadow.path}`));
-	if (warnings.length === 0) return `Configured Caplets (${rows.length})\n\n${entries}\n`;
-	return `Configured Caplets (${rows.length})\n\n${entries}\n\n${warnings.join("\n")}\n`;
-}
-function formatSourceKind(kind) {
-	if (kind.startsWith("project")) return "project";
-	if (kind.startsWith("global")) return "global";
-	return kind;
-}
-function resolveCliConfigPaths(envConfigPath, authDir) {
-	const configPath = resolveConfigPath(envConfigPath);
-	const effectiveAuthDir = authDir ?? DEFAULT_AUTH_DIR;
-	return {
-		userConfig: configPath,
-		projectConfig: resolveProjectConfigPath(),
-		userRoot: resolveCapletsRoot(configPath),
-		stateRoot: dirname(effectiveAuthDir),
-		projectRoot: resolveProjectCapletsRoot(),
-		authDir: effectiveAuthDir,
-		envConfig: envConfigPath ?? null
-	};
-}
-function formatConfigPaths(paths, format = "plain") {
-	if (format === "markdown") return formatConfigPathsMarkdown(paths);
-	return formatConfigPathsPlain(paths);
-}
-function formatConfigPathsMarkdown(paths) {
-	return [
-		"## Caplets paths",
-		"",
-		`- User config: ${paths.userConfig}`,
-		`- Project config: ${paths.projectConfig}`,
-		`- User Caplets root: ${paths.userRoot}`,
-		`- State root: ${paths.stateRoot}`,
-		`- Project Caplets root: ${paths.projectRoot}`,
-		`- Auth directory: ${paths.authDir}`,
-		`- CAPLETS_CONFIG: ${paths.envConfig ?? "unset"}`
-	].join("\n") + "\n";
-}
-function formatConfigPathsPlain(paths) {
-	return [
-		"Caplets paths",
-		"",
-		`User config: ${paths.userConfig}`,
-		`Project config: ${paths.projectConfig}`,
-		`User root: ${paths.userRoot}`,
-		`State root: ${paths.stateRoot}`,
-		`Project root: ${paths.projectRoot}`,
-		`Auth directory: ${paths.authDir}`,
-		`CAPLETS_CONFIG: ${paths.envConfig ?? "unset"}`
-	].join("\n") + "\n";
-}
-//#endregion
 //#region src/cli/install.ts
 function installCaplets(repo, options = {}) {
 	const source = resolveInstallSource(repo);
@@ -5390,6 +5280,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 +8289,372 @@ 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",
+	"list_resources",
+	"search_resources",
+	"list_resource_templates",
+	"read_resource",
+	"list_prompts",
+	"search_prompts",
+	"get_prompt",
+	"complete"
+]);
+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 === "complete_cli") {
+		const shell = optionalString(request.arguments, "shell") ?? "bash";
+		if (!completionShells.includes(shell)) return [];
+		const engine = new CapletsEngine(context);
+		try {
+			return await engine.completeCliWords(optionalStringArray(request.arguments, "words") ?? [""]);
+		} finally {
+			await engine.close();
+		}
+	}
+	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 optionalString(args, key) {
+	const value = args[key];
+	if (value === void 0) return;
+	if (typeof value !== "string") throw new CapletsError("REQUEST_INVALID", `${key} must be a 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 +8685,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 +8725,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 +8864,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 +8874,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 +8899,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 +8929,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();
@@ -8653,9 +9066,14 @@ async function runCli(args, io = {}) {
 		throw error;
 	}
 }
+function normalizeCompletionWords(words) {
+	return words.map((word) => word === "__CAPLETS_TRAILING_SPACE__" ? "" : word);
+}
 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 +9083,98 @@ 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(cliCommands.completion).description("Print a shell completion script.").argument("<shell>", "completion shell: bash, zsh, fish, powershell, or cmd").action((shell) => {
+		if (!completionShells.includes(shell)) throw new CapletsError("REQUEST_INVALID", "completion shell must be bash, zsh, fish, powershell, or cmd");
+		writeOut(completionScript(shell));
+	});
+	program.command(cliCommands.completeHidden, { hidden: true }).description("Internal shell completion endpoint.").option("--shell <shell>", "completion shell").allowUnknownOption(true).argument("[words...]", "words to complete").action(async (words, options) => {
+		const shell = completionShells.includes(options.shell) ? options.shell : "bash";
+		const remote = remoteClientForCli(io);
+		const configPath = currentConfigPath();
+		const completionWords = normalizeCompletionWords(words);
+		let suggestions = [];
+		try {
+			suggestions = remote ? await remote.request("complete_cli", {
+				shell,
+				words: completionWords
+			}) : await completeCliWords(completionWords, configPath ? { configPath } : {});
+		} catch {
+			suggestions = [];
+		}
+		if (suggestions.length > 0) writeOut(`${suggestions.join("\n")}\n`);
+	});
+	program.command(cliCommands.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(cliCommands.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(cliCommands.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(cliCommands.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) => {
+	const add = program.command(cliCommands.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(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,58 +9182,100 @@ 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) => {
+	program.command(cliCommands.getCaplet).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) => {
 		await executeOperation(caplet, { operation: "get_caplet" }, {
 			writeOut,
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	program.command("check-backend").description("Check backend availability for a configured Caplet.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
+	program.command(cliCommands.checkBackend).description("Check backend availability for a configured Caplet.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
 		await executeOperation(caplet, { operation: "check_backend" }, {
 			writeOut,
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	program.command("list-tools").description("List downstream tools for a configured Caplet.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
+	program.command(cliCommands.listTools).description("List downstream tools for a configured Caplet.").argument("<caplet>", "configured Caplet ID").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => {
 		await executeOperation(caplet, { operation: "list_tools" }, {
 			writeOut,
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	program.command("search-tools").description("Search downstream tools for a configured Caplet.").argument("<caplet>", "configured Caplet ID").argument("<query>", "search query").option("--limit <n>", "maximum number of tools to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, query, options) => {
+	program.command(cliCommands.searchTools).description("Search downstream tools for a configured Caplet.").argument("<caplet>", "configured Caplet ID").argument("<query>", "search query").option("--limit <n>", "maximum number of tools to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, query, options) => {
 		await executeOperation(caplet, options.limit === void 0 ? {
 			operation: "search_tools",
 			query
@@ -8772,10 +9288,12 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	program.command("get-tool").description("Print one downstream tool schema.").argument("<caplet.tool>", "qualified target, split on the first dot").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (target, options) => {
+	program.command(cliCommands.getTool).description("Print one downstream tool schema.").argument("<caplet.tool>", "qualified target, split on the first dot").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (target, options) => {
 		const { caplet, tool } = parseQualifiedTarget(target);
 		await executeOperation(caplet, {
 			operation: "get_tool",
@@ -8785,10 +9303,12 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	program.command("call-tool").description("Call one downstream tool.").argument("<caplet.tool>", "qualified target, split on the first dot").option("--args <json-object>", "JSON object of downstream tool arguments").option("--field <path>", "project a field from structured output", collect, []).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (target, options) => {
+	program.command(cliCommands.callTool).description("Call one downstream tool.").argument("<caplet.tool>", "qualified target, split on the first dot").option("--args <json-object>", "JSON object of downstream tool arguments").option("--field <path>", "project a field from structured output", collect, []).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (target, options) => {
 		const { caplet, tool } = parseQualifiedTarget(target);
 		await executeOperation(caplet, {
 			operation: "call_tool",
@@ -8800,24 +9320,150 @@ function createProgram(io = {}) {
 			writeErr,
 			setExitCode,
 			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
+			format: options.format
+		});
+	});
+	program.command(cliCommands.listResources).description("List MCP resources for a configured MCP Caplet.").argument("<caplet>").option("--limit <n>", "maximum number of resources to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => executeOperation(caplet, options.limit === void 0 ? { operation: "list_resources" } : {
+		operation: "list_resources",
+		limit: options.limit
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.searchResources).description("Search MCP resources and resource templates for a configured MCP Caplet.").argument("<caplet>").argument("<query>").option("--limit <n>", "maximum number of matches to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, query, options) => executeOperation(caplet, options.limit === void 0 ? {
+		operation: "search_resources",
+		query
+	} : {
+		operation: "search_resources",
+		query,
+		limit: options.limit
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.listResourceTemplates).description("List MCP resource templates for a configured MCP Caplet.").argument("<caplet>").option("--limit <n>", "maximum number of templates to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => executeOperation(caplet, options.limit === void 0 ? { operation: "list_resource_templates" } : {
+		operation: "list_resource_templates",
+		limit: options.limit
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.readResource).description("Read one MCP resource by URI.").argument("<caplet>").argument("<uri>").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, uri, options) => executeOperation(caplet, {
+		operation: "read_resource",
+		uri
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.listPrompts).description("List MCP prompts for a configured MCP Caplet.").argument("<caplet>").option("--limit <n>", "maximum number of prompts to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => executeOperation(caplet, options.limit === void 0 ? { operation: "list_prompts" } : {
+		operation: "list_prompts",
+		limit: options.limit
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.searchPrompts).description("Search MCP prompts for a configured MCP Caplet.").argument("<caplet>").argument("<query>").option("--limit <n>", "maximum number of prompts to return", parsePositiveInteger).option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, query, options) => executeOperation(caplet, options.limit === void 0 ? {
+		operation: "search_prompts",
+		query
+	} : {
+		operation: "search_prompts",
+		query,
+		limit: options.limit
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	program.command(cliCommands.getPrompt).description("Get one MCP prompt by name.").argument("<caplet.prompt>", "qualified target, split on the first dot").option("--args <json-object>", "JSON object of prompt arguments").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (target, options) => {
+		const { caplet, tool: prompt } = parseQualifiedTarget(target);
+		await executeOperation(caplet, {
+			operation: "get_prompt",
+			prompt,
+			arguments: parseJsonObjectOption(options.args, "get-prompt --args")
+		}, {
+			writeOut,
+			writeErr,
+			setExitCode,
+			authDir: io.authDir,
+			env,
+			remote: remoteClientForCli(io),
 			format: options.format
 		});
 	});
-	const config = program.command("config").description("Inspect Caplets config locations.");
+	program.command(cliCommands.complete).description("Complete an MCP prompt or resource-template argument.").argument("<caplet>").requiredOption("--argument <name>", "argument name").option("--value <value>", "argument prefix", "").option("--prompt <name>", "prompt name to complete").option("--resource-template <uri-template>", "resource template URI to complete").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (caplet, options) => executeOperation(caplet, {
+		operation: "complete",
+		ref: completionRefFromOptions(options),
+		argument: {
+			name: options.argument,
+			value: options.value
+		}
+	}, {
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format: options.format
+	}));
+	const config = program.command(cliCommands.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;
 		}
 		writeOut(formatConfigPaths(paths, options.format ?? "plain"));
 	});
-	const auth = program.command("auth").description("Manage OAuth credentials for remote servers.");
+	const auth = program.command(cliCommands.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 +9472,86 @@ 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":
+		case "list_resources":
+		case "search_resources":
+		case "list_resource_templates":
+		case "read_resource":
+		case "list_prompts":
+		case "search_prompts":
+		case "get_prompt":
+		case "complete": 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);
@@ -8885,11 +9590,48 @@ function parseCallToolArgs(value) {
 	if (!isPlainObject(parsed)) throw new CapletsError("REQUEST_INVALID", "call-tool --args must be a JSON object");
 	return parsed;
 }
+function parseJsonObjectOption(value, label) {
+	if (value === void 0) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch (error) {
+		throw new CapletsError("REQUEST_INVALID", `${label} must be valid JSON`, error);
+	}
+	if (!isPlainObject(parsed)) throw new CapletsError("REQUEST_INVALID", `${label} must be a JSON object`);
+	return parsed;
+}
+function completionRefFromOptions(options) {
+	if (options.prompt && options.resourceTemplate) throw new CapletsError("REQUEST_INVALID", "complete accepts either --prompt or --resource-template, not both");
+	if (options.prompt) return {
+		type: "prompt",
+		name: options.prompt
+	};
+	if (options.resourceTemplate) return {
+		type: "resourceTemplate",
+		uri: options.resourceTemplate
+	};
+	throw new CapletsError("REQUEST_INVALID", "complete requires --prompt or --resource-template");
+}
 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 } : {},
@@ -9001,6 +9743,55 @@ function markdownSummaryForOperation(result, request) {
 			"",
 			"Use `--format json` to inspect the full structured result."
 		].filter((line) => line !== void 0).join("\n");
+		case "list_resources":
+		case "search_resources": {
+			const resources = Array.isArray(payload.resources) ? payload.resources : [];
+			const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
+			const matches = Array.isArray(payload.matches) ? payload.matches : [...resources, ...templates];
+			return [
+				`## MCP resources for \`${id}\``,
+				"",
+				`${matches.length} item${matches.length === 1 ? "" : "s"} found.`,
+				"",
+				...formatResourceLines(matches, "markdown")
+			].join("\n");
+		}
+		case "list_resource_templates": {
+			const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
+			return [
+				`## MCP resource templates for \`${id}\``,
+				"",
+				...formatResourceLines(templates, "markdown")
+			].join("\n");
+		}
+		case "read_resource": return [
+			`## Resource \`${String(request.uri ?? "")}\``,
+			"",
+			summarizeResourceRead(payload),
+			"",
+			"Use `--format json` to inspect all contents."
+		].join("\n");
+		case "list_prompts":
+		case "search_prompts": {
+			const prompts = Array.isArray(payload.prompts) ? payload.prompts : [];
+			return [
+				`## MCP prompts for \`${id}\``,
+				"",
+				...formatPromptLines(prompts, "markdown")
+			].join("\n");
+		}
+		case "get_prompt": return [
+			`## Prompt \`${String(request.caplet)}.${String(request.prompt)}\``,
+			"",
+			summarizePromptResult(payload),
+			"",
+			"Use `--format json` to inspect all messages."
+		].join("\n");
+		case "complete": return [
+			`## Completion for \`${id}\``,
+			"",
+			summarizeCompletionResult(payload)
+		].join("\n");
 		default: return JSON.stringify(payload, null, 2);
 	}
 }
@@ -9057,6 +9848,33 @@ function plainSummaryForOperation(result, request) {
 			`Result: ${summarizeCallResult(payload)}`,
 			"Use --format json to inspect the full structured result."
 		].filter((line) => Boolean(line)).join("\n");
+		case "list_resources":
+		case "search_resources": {
+			const resources = Array.isArray(payload.resources) ? payload.resources : [];
+			const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
+			const matches = Array.isArray(payload.matches) ? payload.matches : [...resources, ...templates];
+			return [`MCP resources for ${id} (${matches.length}):`, ...formatResourceLines(matches, "plain")].join("\n");
+		}
+		case "list_resource_templates": {
+			const templates = Array.isArray(payload.resourceTemplates) ? payload.resourceTemplates : [];
+			return [`MCP resource templates for ${id}:`, ...formatResourceLines(templates, "plain")].join("\n");
+		}
+		case "read_resource": return [
+			`Resource ${String(request.uri ?? "")}`,
+			summarizeResourceRead(payload),
+			"Use --format json to inspect all contents."
+		].join("\n");
+		case "list_prompts":
+		case "search_prompts": {
+			const prompts = Array.isArray(payload.prompts) ? payload.prompts : [];
+			return [`MCP prompts for ${id}:`, ...formatPromptLines(prompts, "plain")].join("\n");
+		}
+		case "get_prompt": return [
+			`Prompt ${String(request.caplet)}.${String(request.prompt)}`,
+			summarizePromptResult(payload),
+			"Use --format json to inspect all messages."
+		].join("\n");
+		case "complete": return [`Completion for ${id}`, summarizeCompletionResult(payload)].join("\n");
 		default: return JSON.stringify(payload, null, 2);
 	}
 }
@@ -9073,6 +9891,44 @@ function formatToolLines(tools, format) {
 		return `- ${displayName}${flags ? ` (${flags})` : ""}${tool.description ? ` — ${compactDescription(String(tool.description))}` : ""}`;
 	});
 }
+function formatResourceLines(resources, format) {
+	if (resources.length === 0) return ["- none"];
+	return resources.map((resource) => {
+		if (!isPlainObject(resource)) return `- ${String(resource)}`;
+		const name = String(resource.uri ?? resource.uriTemplate ?? "unknown");
+		const displayName = format === "markdown" ? `\`${name}\`` : name;
+		const label = typeof resource.name === "string" ? ` (${resource.name})` : "";
+		return `- ${typeof resource.kind === "string" ? `${resource.kind}: ` : ""}${displayName}${label}${resource.description ? ` — ${compactDescription(String(resource.description))}` : ""}`;
+	});
+}
+function formatPromptLines(prompts, format) {
+	if (prompts.length === 0) return ["- none"];
+	return prompts.map((prompt) => {
+		if (!isPlainObject(prompt)) return `- ${String(prompt)}`;
+		const name = String(prompt.prompt ?? prompt.name ?? "unknown");
+		return `- ${format === "markdown" ? `\`${name}\`` : name}${Array.isArray(prompt.arguments) ? ` (${prompt.arguments.length} args)` : ""}${prompt.description ? ` — ${compactDescription(String(prompt.description))}` : ""}`;
+	});
+}
+function summarizeResourceRead(payload) {
+	const contents = Array.isArray(payload.contents) ? payload.contents : [];
+	if (contents.length === 0) return "No contents returned.";
+	const first = contents.find(isPlainObject);
+	if (!first) return `${contents.length} content item${contents.length === 1 ? "" : "s"} returned.`;
+	return previewValue(typeof first.text === "string" ? first.text : first.blob) ?? `${contents.length} content item${contents.length === 1 ? "" : "s"} returned.`;
+}
+function summarizePromptResult(payload) {
+	const messages = Array.isArray(payload.messages) ? payload.messages : [];
+	if (messages.length === 0) return "No messages returned.";
+	const first = messages.find(isPlainObject);
+	if (!first) return `${messages.length} message${messages.length === 1 ? "" : "s"} returned.`;
+	return previewValue((isPlainObject(first.content) ? first.content : void 0)?.text ?? first.content) ?? `${messages.length} message${messages.length === 1 ? "" : "s"} returned.`;
+}
+function summarizeCompletionResult(payload) {
+	const completion = isPlainObject(payload.completion) ? payload.completion : void 0;
+	const values = Array.isArray(completion?.values) ? completion.values : [];
+	if (values.length > 0) return values.map((value) => `- ${String(value)}`).join("\n");
+	return previewValue(payload) ?? "No completions returned.";
+}
 function compactDescription(value) {
 	const firstParagraph = value.trim().split(/\n\s*\n/u)[0] ?? "";
 	const collapsed = (firstParagraph.match(/^.*?(?:[.!?](?=\s|$)|$)/u)?.[0] ?? firstParagraph).replace(/\s+/gu, " ").trim();
@@ -9135,12 +9991,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);