@caplets/core 0.26.1 → 0.28.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { $ as resolveExposure, $t as mergeCapabilities, A as nativeCapletPromptGuidance, An as isJSONRPCRequest, At as runOAuthFlow, B as CodeModeSessionManager, Bn as safeParse, Bt as defaultConfigBaseDir, C as resolveHostedCloudRemote, Cn as ReadResourceRequestSchema, Ct as validateCapletFile, D as isLoopbackHost, Dn as assertCompleteRequestResourceTemplate, Dt as markdownStructuredContent, E as controlUrlForBase, En as assertCompleteRequestPrompt, Et as markdownCallToolResultContent, Fn as getSchemaDescription, Ft as readTokenBundle, G as CodeModeJournalStore, Gt as resolveProjectCapletsRoot, H as diagnoseCodeModeTypeScript, Ht as defaultStateBaseDir, I as codeModeRunInputSchema, In as isSchemaOptional, It as DEFAULT_AUTH_DIR, J as codeModeDeclarationHash, Jt as serializeMessage, K as CodeModeLogStore, Kt as resolveProjectConfigPath, L as codeModeRunParamsSchema, Ln as isZ4Schema, M as nativeCapletToolName, Mn as getLiteralValue, Mt as startOAuthFlow, Nn as getObjectShape, Nt as deleteTokenBundle, O as parseServerBaseUrl, On as isInitializeRequest, Ot as refreshOAuthTokenBundle, Pn as getParseErrorMessage, Pt as isTokenBundleExpired, Q as CapletsEngine, Qt as Protocol, R as emptyCodeModeRunMeta, Rn as normalizeObjectSchema, Rt as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, S as resolveCapletsRemote, Sn as McpError, St as discoverCapletFiles, T as appendBasePath, Tn as SetLevelRequestSchema, Tt as hasRenderableStructuredContent, U as createCodeModeCapletsApi, Ut as resolveCapletsRoot, V as QuickJsCodeModeSandbox, Vn as safeParseAsync, Vt as defaultConfigPath, W as listCodeModeCallableCaplets, Wt as resolveConfigPath, X as generateCodeModeRunToolDescription, Xt as assertToolsCallTaskCapability, Y as generateCodeModeDeclarations, Yt as assertClientRequestTaskCapability, Z as minifyCodeModeDeclarationText, Zt as AjvJsonSchemaValidator, _ as CapletsCloudClient, _n as ListResourceTemplatesRequestSchema, _t as FileVaultStore, a as CloudAuthStore, an as CreateMessageResultWithToolsSchema, at as ServerRegistry, b as isCapletsCloudUrl, bn as ListToolsRequestSchema, bt as decryptVaultValue, c as redactedCloudAuthStatus, cn as ElicitResultSchema, ct as loadConfig, d as projectBindingError, dn as GetPromptRequestSchema, dt as loadLocalOverlayConfigWithSources, en as toJsonSchemaCompat, et as decodeDirectResourceUri, f as projectBindingRecovery, fn as InitializeRequestSchema, ft as loadProjectConfig, g as buildProjectSyncManifest, gn as ListPromptsRequestSchema, gt as vaultStoreForAuthDir, hn as LATEST_PROTOCOL_VERSION, ht as vaultResolverForAuthDir, i as createRemoteProfileStore, in as CreateMessageResultSchema, it as handleServerTool, j as nativeCapletToolDescription, jn as isJSONRPCResultResponse, jt as startGenericOAuthFlow, k as resolveCapletsServer, kn as isJSONRPCErrorResponse, kt as runGenericOAuthFlow, l as PROJECT_BINDING_ERROR_CODES, ln as EmptyResultSchema, lt as loadConfigWithSources, mn as JSONRPCMessageSchema, mt as vaultBootstrapResolver, n as resolveRemoteSelection, nn as CallToolResultSchema, nt as findProjectRoot, o as cloudAuthPath, on as CreateTaskResultSchema, ot as capabilityDescription, p as CloudAuthClient, pn as InitializedNotificationSchema, pt as parseConfig, q as redactCodeModeLogText, qt as ReadBuffer, r as cloudCredentialsFromRemoteProfile, rn as CompleteRequestSchema, rt as fingerprintProjectRoot, s as migrateCredentials, st as GoogleDiscoveryManager, t as createNativeCapletsService, tn as CallToolRequestSchema, tt as directResourceUriMatchesTemplate, u as ProjectBindingError, un as ErrorCode, ut as loadGlobalConfig, vn as ListResourcesRequestSchema, vt as VAULT_MAX_VALUE_BYTES, w as resolveRemoteMode, wn as SUPPORTED_PROTOCOL_VERSIONS, wt as loadCapletFilesFromMap, x as normalizeRemoteProfileHostUrl, xn as LoggingLevelSchema, xt as encryptVaultValue, y as hostedCloudWorkspaceFromRemoteUrl, yn as ListRootsResultSchema, yt as validateVaultKeyName, z as runCodeMode, zn as objectFromShape, zt as defaultCacheBaseDir } from "./service-aBIn4nrw.js";
+import { $ as redactCodeModeLogText, $n as getParseErrorMessage, $t as readTokenBundle, A as resolveRemoteMode, An as GetPromptRequestSchema, At as loadProjectConfig, Bn as LoggingLevelSchema, Bt as discoverCapletFiles, C as CapletsCloudClient, Cn as CreateMessageResultSchema, Ct as ServerRegistry, D as normalizeRemoteProfileHostUrl, Dn as ElicitResultSchema, Dt as loadConfigWithSources, E as isCapletsCloudUrl, Et as loadConfig, F as resolveCapletsServer, Fn as ListPromptsRequestSchema, Ft as FileVaultStore, G as runCodeMode, Gn as assertCompleteRequestPrompt, Gt as markdownStructuredContent, H as codeModeRunInputSchema, Hn as ReadResourceRequestSchema, Ht as loadCapletFilesFromMap, I as nativeCapletPromptGuidance, In as ListResourceTemplatesRequestSchema, It as VAULT_MAX_VALUE_BYTES, J as diagnoseCodeModeTypeScript, Jn as isJSONRPCErrorResponse, Jt as runOAuthFlow, K as CodeModeSessionManager, Kn as assertCompleteRequestResourceTemplate, Kt as refreshOAuthTokenBundle, L as nativeCapletToolDescription, Ln as ListResourcesRequestSchema, Lt as validateVaultKeyName, M as controlUrlForBase, Mn as InitializedNotificationSchema, Mt as vaultBootstrapResolver, N as isLoopbackHost, Nn as JSONRPCMessageSchema, Nt as vaultResolverForAuthDir, O as resolveCapletsRemote, On as EmptyResultSchema, Ot as loadGlobalConfig, P as parseServerBaseUrl, Pn as LATEST_PROTOCOL_VERSION, Pt as vaultStoreForAuthDir, Q as CodeModeLogStore, Qn as getObjectShape, Qt as isTokenBundleExpired, R as nativeCapletToolName, Rn as ListRootsResultSchema, Rt as decryptVaultValue, S as buildProjectSyncManifest, Sn as CompleteRequestSchema, St as handleServerTool, T as hostedCloudWorkspaceFromRemoteUrl, Tn as CreateTaskResultSchema, Tt as GoogleDiscoveryManager, U as codeModeRunParamsSchema, Un as SUPPORTED_PROTOCOL_VERSIONS, Ut as hasRenderableStructuredContent, Vn as McpError, Vt as validateCapletFile, W as emptyCodeModeRunMeta, Wn as SetLevelRequestSchema, Wt as markdownCallToolResultContent, X as listCodeModeCallableCaplets, Xn as isJSONRPCResultResponse, Xt as startOAuthFlow, Y as createCodeModeCapletsApi, Yn as isJSONRPCRequest, Yt as startGenericOAuthFlow, Z as CodeModeJournalStore, Zn as getLiteralValue, Zt as deleteTokenBundle, _ as attachErrorResponse, _n as Protocol, _t as rotateTelemetryIdentity, a as CloudAuthStore, an as defaultConfigPath, ar as safeParse, at as version, b as invokeAttachExport, bn as CallToolRequestSchema, bt as findProjectRoot, c as redactedCloudAuthStatus, cn as resolveCapletsRoot, ct as buildProductTelemetryEvent, d as projectBindingError, dn as resolveProjectConfigPath, dt as maybePrintTelemetryNotice, en as DEFAULT_AUTH_DIR, er as getSchemaDescription, et as codeModeDeclarationHash, f as projectBindingRecovery, fn as ReadBuffer, ft as resolveTelemetryState, g as CAPLETS_ATTACH_SESSION_HEADER, gn as AjvJsonSchemaValidator, gt as readTelemetryNotice, hn as assertToolsCallTaskCapability, ht as readTelemetryIdentity, i as createRemoteProfileStore, in as defaultConfigBaseDir, ir as objectFromShape, it as CapletsEngine, j as appendBasePath, jn as InitializeRequestSchema, jt as parseConfig, k as resolveHostedCloudRemote, kn as ErrorCode, kt as loadLocalOverlayConfigWithSources, l as PROJECT_BINDING_ERROR_CODES, ln as resolveConfigPath, lt as buildReliabilityTelemetryEvent, mn as assertClientRequestTaskCapability, mt as readTelemetryDeliveryHealth, n as resolveRemoteSelection, nn as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, nr as isZ4Schema, nt as generateCodeModeRunToolDescription, o as cloudAuthPath, on as defaultStateBaseDir, or as safeParseAsync, ot as createTelemetryDispatcher, p as CloudAuthClient, pn as serializeMessage, pt as deleteTelemetryIdentity, q as QuickJsCodeModeSandbox, qn as isInitializeRequest, qt as runGenericOAuthFlow, r as cloudCredentialsFromRemoteProfile, rn as defaultCacheBaseDir, rr as normalizeObjectSchema, rt as minifyCodeModeDeclarationText, s as migrateCredentials, sn as defaultTelemetryStateDir, st as TelemetryDebugSink, t as createNativeCapletsService, tr as isSchemaOptional, tt as generateCodeModeDeclarations, u as ProjectBindingError, un as resolveProjectCapletsRoot, ut as durationBucket, v as buildAttachProjection, vn as mergeCapabilities, vt as resolveExposure, wn as CreateMessageResultWithToolsSchema, wt as capabilityDescription, x as invokeNativeAttachExport, xn as CallToolResultSchema, xt as fingerprintProjectRoot, y as buildNativeAttachProjection, yn as toJsonSchemaCompat, yt as decodeDirectResourceUri, zn as ListToolsRequestSchema, zt as encryptVaultValue } from "./service-BfPCRxQ9.js";
 import { _ as record, b as unknown, d as literal, m as object, n as ZodOptional, o as array, p as number, r as _enum, s as boolean, v as string, x as url } from "./schemas-BoqMu4MG.js";
-import { f as redactSecrets$1, i as SERVER_ID_PATTERN, l as CAPLETS_ERROR_CODES, p as toSafeError, u as CapletsError } from "./validation-GD2x5HW1.js";
-import { generatedToolInputJsonSchemaForCaplet, generatedToolInputSchema, generatedToolInputSchemaForCaplet } from "./generated-tool-input-schema.js";
-import { f as observedOutputShapeKey, g as stableJsonStringify, h as schemaHash, i as observeOutputShape, u as FileObservedOutputShapeStore } from "./observed-output-shapes-DuP7mJQf.js";
-import { a as formatCapletList, c as resolveCliConfigPaths, l as cliCommands$1, n as completionScript, o as formatConfigPaths, s as listCaplets, t as completeCliWords, u as completionShells } from "./completion-CFOJucl5.js";
+import { a as SERVER_ID_PATTERN, d as CapletsError, m as toSafeError, p as redactSecrets$1, u as CAPLETS_ERROR_CODES } from "./validation-CWzd2gtn.js";
+import { generatedToolInputSchema, generatedToolInputSchemaForCaplet } from "./generated-tool-input-schema.js";
+import { f as observedOutputShapeKey, i as observeOutputShape, u as FileObservedOutputShapeStore } from "./observed-output-shapes-DuP7mJQf.js";
+import { a as formatCapletList, c as resolveCliConfigPaths, l as cliCommands$1, n as completionScript, o as formatConfigPaths, s as listCaplets, t as completeCliWords, u as completionShells } from "./completion-CjE0EnbF.js";
 import { n as normalizeCapletSourcePath, t as FilesystemCapletSource } from "./filesystem-Kkg32TOJ.js";
 import { parseConfig as parseConfig$1 } from "./config-runtime.js";
 import fs, { accessSync, chmodSync, closeSync, constants, copyFileSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, writeSync } from "node:fs";
@@ -13,7 +13,7 @@ import process$1, { stdin, stdout } from "node:process";
 import { Readable, Writable } from "node:stream";
 import { STATUS_CODES, createServer } from "node:http";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { homedir, tmpdir, userInfo } from "node:os";
+import { arch, homedir, platform, tmpdir, userInfo } from "node:os";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { EventEmitter } from "node:events";
 import { promisify, stripVTControlCharacters } from "node:util";
@@ -1552,9 +1552,6 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 	hasMore: false
 } };
 //#endregion
-//#region package.json
-var version = "0.26.1";
-//#endregion
 //#region src/serve/session.ts
 var CapletsMcpSession = class {
 	engine;
@@ -1634,7 +1631,7 @@ var CapletsMcpSession = class {
 					downstreamName: entry.downstreamName,
 					exposure: "direct"
 				} },
-				callback: async (request) => this.engine.executeDirectTool(entry.caplet.server, entry.downstreamName, isRecord$4(request) ? request : {}),
+				callback: async (request) => this.engine.executeDirectTool(entry.caplet.server, entry.downstreamName, isRecord$3(request) ? request : {}),
 				enabled: true
 			})
 		});
@@ -1672,6 +1669,7 @@ var CapletsMcpSession = class {
 		}, async (request) => this.handleCodeModeRunTool(request));
 	}
 	async handleCodeModeRunTool(request) {
+		const started = Date.now();
 		const parsed = codeModeRunInputSchema.safeParse(request);
 		const envelope = parsed.success ? await runCodeMode({
 			code: parsed.data.code,
@@ -1697,6 +1695,10 @@ var CapletsMcpSession = class {
 			},
 			meta: emptyCodeModeRunMeta()
 		};
+		this.engine.captureCodeModeOutcome(envelope, {
+			started,
+			...parsed.success && parsed.data.timeoutMs !== void 0 ? { timeoutMs: parsed.data.timeoutMs } : {}
+		}).catch(() => void 0);
 		return {
 			content: [{
 				type: "text",
@@ -1725,7 +1727,7 @@ var CapletsMcpSession = class {
 				downstreamName: entry.downstreamName,
 				exposure: "direct"
 			} }
-		}, async (request) => this.engine.executeDirectTool(entry.caplet.server, entry.downstreamName, isRecord$4(request) ? request : {}));
+		}, async (request) => this.engine.executeDirectTool(entry.caplet.server, entry.downstreamName, isRecord$3(request) ? request : {}));
 	}
 	registerDirectResource(entry) {
 		if (!this.server.registerResource) throw new Error("MCP server does not support resource registration");
@@ -1744,11 +1746,11 @@ var CapletsMcpSession = class {
 			title: entry.prompt.name,
 			...entry.prompt.description ? { description: entry.prompt.description } : {},
 			argsSchema: promptArgsSchema(entry.prompt.arguments)
-		}, async (args) => await this.engine.getDirectPrompt(entry.caplet.server, entry.downstreamName, isRecord$4(args) ? stringifyRecord$1(args) : {}));
+		}, async (args) => await this.engine.getDirectPrompt(entry.caplet.server, entry.downstreamName, isRecord$3(args) ? stringifyRecord(args) : {}));
 	}
 	async directResourceResult(serverId, downstreamUri) {
 		const result = await this.engine.readDirectResource(serverId, downstreamUri);
-		if (isRecord$4(result) && "contents" in result) return result;
+		if (isRecord$3(result) && "contents" in result) return result;
 		return { contents: [{
 			uri: downstreamUri,
 			mimeType: "application/json",
@@ -1819,10 +1821,10 @@ function promptArgsSchema(args) {
 	for (const arg of args ?? []) shape[arg.name] = string().optional();
 	return shape;
 }
-function stringifyRecord$1(value) {
+function stringifyRecord(value) {
 	return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, nested === void 0 ? "" : String(nested)]));
 }
-function isRecord$4(value) {
+function isRecord$3(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function staticExposureSnapshot(config, caplets) {
@@ -5524,7 +5526,12 @@ async function runCodeModeCli(options) {
 		mode: "local",
 		...options.configPath ? { configPath: options.configPath } : {},
 		...options.projectConfigPath ? { projectConfigPath: options.projectConfigPath } : {},
-		...options.authDir ? { authDir: options.authDir } : {}
+		...options.authDir ? { authDir: options.authDir } : {},
+		telemetryEnv: options.env,
+		telemetryStateDir: options.telemetryStateDir ?? defaultTelemetryStateDir(options.env),
+		telemetrySurface: "code_mode",
+		telemetryVisibility: "visible",
+		telemetryRuntimeMode: runtimeScope(options.env) === "local" ? "local" : "unknown"
 	});
 	try {
 		if (options.sessionId !== void 0) {
@@ -5547,12 +5554,18 @@ async function runCodeModeCli(options) {
 			options.setExitCode(1);
 			return;
 		}
+		const code = await readCodeModeCliCode(options);
+		const started = Date.now();
 		const result = await runCodeMode({
-			code: await readCodeModeCliCode(options),
-			service: service.codeModeService?.() ?? service,
+			code,
 			...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+			service: service.codeModeService?.() ?? service,
 			runtimeScope: "cli-one-shot"
 		});
+		await service.captureCodeModeOutcome?.(result, {
+			started,
+			...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+		}).catch(() => void 0);
 		if (options.json) options.writeOut(`${JSON.stringify(result, null, 2)}\n`);
 		else if (result.ok) options.writeOut(`${formatHumanValue(result.value)}\n`);
 		else {
@@ -5587,7 +5600,8 @@ async function codeModeTypesCli(options) {
 	const engine = new CapletsEngine({
 		...options.configPath ? { configPath: options.configPath } : {},
 		...options.projectConfigPath ? { projectConfigPath: options.projectConfigPath } : {},
-		...options.authDir ? { authDir: options.authDir } : {}
+		...options.authDir ? { authDir: options.authDir } : {},
+		telemetryStateDir: options.telemetryStateDir ?? defaultTelemetryStateDir(options.env)
 	});
 	try {
 		const caplets = listCodeModeCallableCaplets$1(engine);
@@ -6919,14 +6933,24 @@ const HTTP_ONLY_OPTIONS = [
 	"port",
 	"path",
 	"remoteStatePath",
+	"upstreamUrl",
 	"allowUnauthenticatedHttp",
 	"trustProxy"
 ];
+const HTTP_ONLY_OPTION_FLAGS = {
+	host: "--host",
+	port: "--port",
+	path: "--path",
+	remoteStatePath: "--remote-state-path",
+	upstreamUrl: "--upstream-url",
+	allowUnauthenticatedHttp: "--allow-unauthenticated-http",
+	trustProxy: "--trust-proxy"
+};
 function resolveServeOptions(raw, env = process.env) {
 	const transport = parseTransport(raw.transport ?? "stdio");
 	if (transport === "stdio") {
 		const invalid = HTTP_ONLY_OPTIONS.filter((key) => raw[key] !== void 0);
-		if (invalid.length > 0) throw new CapletsError("REQUEST_INVALID", `${invalid.map((key) => `--${key}`).join(", ")} ${invalid.length === 1 ? "is" : "are"} only valid with --transport http`);
+		if (invalid.length > 0) throw new CapletsError("REQUEST_INVALID", `${invalid.map((key) => HTTP_ONLY_OPTION_FLAGS[key]).join(", ")} ${invalid.length === 1 ? "is" : "are"} only valid with --transport http`);
 		return { transport };
 	}
 	const serverUrl = env.CAPLETS_SERVER_URL ? parseServeServerUrl(nonEmpty$2(env.CAPLETS_SERVER_URL, "CAPLETS_SERVER_URL")) : void 0;
@@ -6934,6 +6958,13 @@ function resolveServeOptions(raw, env = process.env) {
 	const port = parsePort(raw.port ?? (serverUrl?.port ? Number(serverUrl.port) : 5387));
 	const path = normalizeHttpPath(raw.path ?? serverUrl?.pathname ?? "/");
 	const remoteCredentialStateDir = nonEmpty$2(raw.remoteStatePath, "--remote-state-path") ?? nonEmpty$2(env.CAPLETS_REMOTE_SERVER_STATE_DIR, "CAPLETS_REMOTE_SERVER_STATE_DIR") ?? join(DEFAULT_AUTH_DIR, "remote-server");
+	const upstreamUrl = nonEmpty$2(raw.upstreamUrl, "--upstream-url");
+	if (upstreamUrl) rejectSelfReferentialUpstream(upstreamUrl, {
+		...serverUrl ? { origin: serverUrl.origin } : {},
+		host,
+		port,
+		path
+	});
 	const loopback = isLoopbackHost(host);
 	const auth = raw.allowUnauthenticatedHttp === true ? { type: "development_unauthenticated" } : { type: "remote_credentials" };
 	return {
@@ -6944,6 +6975,7 @@ function resolveServeOptions(raw, env = process.env) {
 		...serverUrl ? { publicOrigin: serverUrl.origin } : {},
 		auth,
 		...auth.type === "remote_credentials" ? { remoteCredentialStateDir } : {},
+		...upstreamUrl ? { upstreamUrl } : {},
 		allowUnauthenticatedHttp: raw.allowUnauthenticatedHttp === true,
 		warnUnauthenticatedNetwork: !loopback && auth.type === "development_unauthenticated",
 		loopback,
@@ -6975,6 +7007,42 @@ function normalizeHttpPath(value) {
 function serverUrlHost(url) {
 	return url?.hostname.replace(/^\[(.*)\]$/u, "$1");
 }
+function rejectSelfReferentialUpstream(upstreamUrl, local) {
+	if (sameServerBase(parseServerBaseUrl(upstreamUrl), localServeBaseUrl(local))) throw new CapletsError("REQUEST_INVALID", "--upstream-url must not point back to this runtime.");
+}
+function localServeBaseUrl(local) {
+	const origin = local.origin ?? `http://${formatHost$3(local.host)}:${local.port}`;
+	const url = new URL(origin);
+	url.pathname = local.path;
+	url.search = "";
+	url.hash = "";
+	return url;
+}
+function sameServerBase(left, right) {
+	return left.protocol === right.protocol && sameHost(left.hostname, right.hostname) && effectivePort(left) === effectivePort(right) && normalizePath(left.pathname) === normalizePath(right.pathname);
+}
+function sameHost(left, right) {
+	if (left === right) return true;
+	const normalizedLeft = normalizeLoopbackHost(left);
+	const normalizedRight = normalizeLoopbackHost(right);
+	return normalizedLeft !== void 0 && normalizedLeft === normalizedRight;
+}
+function normalizeLoopbackHost(host) {
+	const normalized = host.toLowerCase().replace(/^\[(.*)\]$/u, "$1");
+	if (normalized === "localhost" || normalized === "::1") return "loopback";
+	if (normalized === "0.0.0.0" || normalized === "::") return "loopback";
+	if (/^127(?:\.\d{1,3}){3}$/u.test(normalized)) return "loopback";
+}
+function effectivePort(url) {
+	if (url.port) return url.port;
+	return url.protocol === "https:" ? "443" : "80";
+}
+function normalizePath(path) {
+	return path === "/" ? "/" : path.replace(/\/+$/u, "");
+}
+function formatHost$3(host) {
+	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
 function nonEmpty$2(value, label) {
 	if (value === void 0) return;
 	const trimmed = value.trim();
@@ -10481,291 +10549,6 @@ var logger = (fn = console.log) => {
 	};
 };
 //#endregion
-//#region src/attach/api.ts
-async function buildAttachProjection(engine) {
-	const snapshot = await engine.exposureSnapshot();
-	const partial = sortAttachProjectionInput({
-		caplets: snapshot.progressiveCaplets.map(progressiveCapletExport),
-		tools: snapshot.directTools.map(toolExport),
-		resources: snapshot.directResources.map(resourceExport),
-		resourceTemplates: snapshot.directResourceTemplates.map(resourceTemplateExport),
-		prompts: snapshot.directPrompts.map(promptExport),
-		completions: completionExports(snapshot),
-		codeModeCaplets: snapshot.codeModeCaplets.map(codeModeCapletExport),
-		diagnostics: snapshot.hiddenCaplets.map((hidden) => ({
-			code: `ATTACH_CAPLET_${hidden.reason.toUpperCase()}`,
-			message: `Caplet ${hidden.capletId} is not exported: ${hidden.reason}.`,
-			capletId: hidden.capletId,
-			...hidden.error ? { details: hidden.error } : {}
-		}))
-	});
-	const revision = revisionFor(partial);
-	const manifest = {
-		version: 1,
-		revision,
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		...withRevisionExportIds(revision, partial)
-	};
-	return {
-		manifest,
-		routes: routesFor(manifest)
-	};
-}
-async function invokeAttachExport(engine, projection, request) {
-	if (request.revision !== projection.manifest.revision) throw new CapletsError("ATTACH_MANIFEST_STALE", "Attach manifest revision is stale.");
-	const route = projection.routes.get(request.exportId);
-	if (!route || route.kind !== request.kind) throw new CapletsError("ATTACH_EXPORT_NOT_FOUND", "Attach export was not found.");
-	if (route.kind === "caplet") return await engine.execute(route.capletId, request.input);
-	if (route.kind === "tool") return await engine.executeDirectTool(route.capletId, route.downstreamName, isRecord$3(request.input) ? request.input : {});
-	if (route.kind === "resource") return await engine.readDirectResource(route.capletId, route.downstreamUri);
-	if (route.kind === "resourceTemplate") {
-		const uri = isRecord$3(request.input) && typeof request.input.uri === "string" ? request.input.uri : void 0;
-		if (!uri) throw new CapletsError("REQUEST_INVALID", "Attach resource template invoke requires input.uri.");
-		const downstreamUri = downstreamResourceUri(route.capletId, uri);
-		if (!directResourceUriMatchesTemplate(downstreamUri, route.downstreamUriTemplate)) throw new CapletsError("ATTACH_EXPORT_NOT_FOUND", "Attach resource URI does not match the exported resource template.");
-		return await engine.readDirectResource(route.capletId, downstreamUri);
-	}
-	if (route.kind === "prompt") return await engine.getDirectPrompt(route.capletId, route.downstreamName, isRecord$3(request.input) ? stringifyRecord(request.input) : {});
-	if (route.kind === "completion") return await engine.execute(route.capletId, {
-		...normalizeCompletionInput(projection.manifest, route.capletId, request.input),
-		operation: "complete"
-	});
-	throw new CapletsError("REQUEST_INVALID", "Attach export kind is not invokable via /v1/attach/invoke.");
-}
-function attachErrorResponse(error) {
-	const safe = toSafeError(error, "INTERNAL_ERROR");
-	return {
-		status: safe.code === "ATTACH_MANIFEST_STALE" ? 409 : safe.code === "ATTACH_EXPORT_NOT_FOUND" ? 404 : safe.code === "REQUEST_INVALID" ? 400 : 500,
-		body: {
-			ok: false,
-			error: safe
-		}
-	};
-}
-function progressiveCapletExport(entry) {
-	const inputSchema = generatedToolInputJsonSchemaForCaplet(entry.caplet);
-	return {
-		stableId: `progressive:${entry.caplet.server}`,
-		kind: "caplet",
-		name: entry.caplet.server,
-		title: entry.caplet.name,
-		description: entry.caplet.description,
-		inputSchema,
-		schemaHash: schemaHash(inputSchema),
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function codeModeCapletExport(entry) {
-	return {
-		stableId: `code_mode:${entry.caplet.server}`,
-		kind: "caplet",
-		name: entry.caplet.name,
-		title: entry.caplet.name,
-		description: entry.caplet.description,
-		schemaHash: null,
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function toolExport(entry) {
-	return {
-		stableId: `tool:${entry.caplet.server}:${entry.downstreamName}`,
-		kind: "tool",
-		name: entry.name,
-		downstreamName: entry.downstreamName,
-		title: entry.tool.name,
-		description: entry.tool.description,
-		inputSchema: entry.tool.inputSchema,
-		outputSchema: entry.tool.outputSchema,
-		annotations: entry.tool.annotations,
-		schemaHash: schemaHash({
-			input: entry.tool.inputSchema,
-			output: entry.tool.outputSchema
-		}),
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function resourceExport(entry) {
-	return {
-		stableId: `resource:${entry.caplet.server}:${entry.downstreamUri}`,
-		kind: "resource",
-		uri: entry.uri,
-		downstreamUri: entry.downstreamUri,
-		title: entry.resource.name,
-		description: entry.resource.description,
-		...entry.resource.mimeType ? { mimeType: entry.resource.mimeType } : {},
-		...typeof entry.resource.size === "number" ? { size: entry.resource.size } : {},
-		schemaHash: null,
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function resourceTemplateExport(entry) {
-	return {
-		stableId: `resourceTemplate:${entry.caplet.server}:${entry.downstreamUriTemplate}`,
-		kind: "resourceTemplate",
-		uriTemplate: entry.uriTemplate,
-		downstreamUriTemplate: entry.downstreamUriTemplate,
-		title: entry.resourceTemplate.name,
-		description: entry.resourceTemplate.description,
-		...entry.resourceTemplate.mimeType ? { mimeType: entry.resourceTemplate.mimeType } : {},
-		schemaHash: null,
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function promptExport(entry) {
-	const inputSchema = { arguments: entry.prompt.arguments ?? [] };
-	return {
-		stableId: `prompt:${entry.caplet.server}:${entry.downstreamName}`,
-		kind: "prompt",
-		name: entry.name,
-		downstreamName: entry.downstreamName,
-		title: entry.prompt.name,
-		description: entry.prompt.description,
-		inputSchema,
-		schemaHash: schemaHash(inputSchema),
-		capletId: entry.caplet.server,
-		shadowing: shadowingPolicy(entry.caplet)
-	};
-}
-function completionExports(snapshot) {
-	return [...new Map([...snapshot.directPrompts, ...snapshot.directResourceTemplates].map((entry) => [entry.caplet.server, entry.caplet])).entries()].sort(([left], [right]) => left.localeCompare(right)).map(([capletId, caplet]) => ({
-		stableId: `completion:${capletId}`,
-		kind: "completion",
-		name: `${capletId}:complete`,
-		title: "Complete",
-		description: `MCP completion for ${capletId}.`,
-		schemaHash: null,
-		capletId,
-		shadowing: shadowingPolicy(caplet)
-	}));
-}
-function shadowingPolicy(caplet) {
-	return caplet.shadowing ?? "forbid";
-}
-function sortAttachProjectionInput(partial) {
-	return {
-		caplets: sortByStableId(partial.caplets),
-		tools: sortByStableId(partial.tools),
-		resources: sortByStableId(partial.resources),
-		resourceTemplates: sortByStableId(partial.resourceTemplates),
-		prompts: sortByStableId(partial.prompts),
-		completions: sortByStableId(partial.completions),
-		codeModeCaplets: sortByStableId(partial.codeModeCaplets),
-		diagnostics: [...partial.diagnostics].sort((left, right) => diagnosticSortKey(left).localeCompare(diagnosticSortKey(right)))
-	};
-}
-function sortByStableId(entries) {
-	return [...entries].sort((left, right) => left.stableId.localeCompare(right.stableId));
-}
-function diagnosticSortKey(diagnostic) {
-	return stableJsonStringify({
-		code: diagnostic.code,
-		capletId: diagnostic.capletId ?? "",
-		message: diagnostic.message
-	});
-}
-function revisionFor(value) {
-	return `sha256:${createHash("sha256").update(stableJsonStringify(value)).digest("hex")}`;
-}
-function withRevisionExportIds(revision, partial) {
-	return {
-		...partial,
-		caplets: partial.caplets.map((entry) => withExportId(revision, entry)),
-		tools: partial.tools.map((entry) => withExportId(revision, entry)),
-		resources: partial.resources.map((entry) => withExportId(revision, entry)),
-		resourceTemplates: partial.resourceTemplates.map((entry) => withExportId(revision, entry)),
-		prompts: partial.prompts.map((entry) => withExportId(revision, entry)),
-		completions: partial.completions.map((entry) => withExportId(revision, entry)),
-		codeModeCaplets: partial.codeModeCaplets.map((entry) => withExportId(revision, entry))
-	};
-}
-function withExportId(revision, entry) {
-	return {
-		...entry,
-		exportId: `${revision}:${entry.stableId}`
-	};
-}
-function routesFor(manifest) {
-	const routes = /* @__PURE__ */ new Map();
-	for (const entry of manifest.caplets) routes.set(entry.exportId, {
-		kind: "caplet",
-		capletId: entry.capletId
-	});
-	for (const entry of manifest.tools) routes.set(entry.exportId, {
-		kind: "tool",
-		capletId: entry.capletId,
-		downstreamName: entry.downstreamName
-	});
-	for (const entry of manifest.resources) routes.set(entry.exportId, {
-		kind: "resource",
-		capletId: entry.capletId,
-		downstreamUri: entry.downstreamUri
-	});
-	for (const entry of manifest.resourceTemplates) routes.set(entry.exportId, {
-		kind: "resourceTemplate",
-		capletId: entry.capletId,
-		downstreamUriTemplate: entry.downstreamUriTemplate
-	});
-	for (const entry of manifest.prompts) routes.set(entry.exportId, {
-		kind: "prompt",
-		capletId: entry.capletId,
-		downstreamName: entry.downstreamName
-	});
-	for (const entry of manifest.completions) routes.set(entry.exportId, {
-		kind: "completion",
-		capletId: entry.capletId
-	});
-	for (const entry of manifest.codeModeCaplets) routes.set(entry.exportId, {
-		kind: "caplet",
-		capletId: entry.capletId
-	});
-	return routes;
-}
-function normalizeCompletionInput(manifest, capletId, input) {
-	if (!isRecord$3(input)) return {};
-	const ref = input.ref;
-	if (!isRecord$3(ref)) return input;
-	if (ref.type === "prompt" && typeof ref.name === "string") {
-		const prompt = manifest.prompts.find((entry) => entry.capletId === capletId && (entry.name === ref.name || entry.downstreamName === ref.name));
-		if (!prompt) return input;
-		return {
-			...input,
-			ref: {
-				...ref,
-				name: prompt.downstreamName
-			}
-		};
-	}
-	if (ref.type === "resourceTemplate" && typeof ref.uri === "string") {
-		const resourceTemplate = manifest.resourceTemplates.find((entry) => entry.capletId === capletId && (entry.uriTemplate === ref.uri || entry.downstreamUriTemplate === ref.uri));
-		if (!resourceTemplate) return input;
-		return {
-			...input,
-			ref: {
-				...ref,
-				uri: resourceTemplate.downstreamUriTemplate
-			}
-		};
-	}
-	return input;
-}
-function isRecord$3(value) {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function stringifyRecord(record) {
-	return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, typeof value === "string" ? value : JSON.stringify(value)]));
-}
-function downstreamResourceUri(capletId, uri) {
-	if (!uri.startsWith("caplets://")) return uri;
-	const decoded = decodeDirectResourceUri(uri);
-	if (decoded.capletId !== capletId) throw new CapletsError("ATTACH_EXPORT_NOT_FOUND", "Attach resource template URI belongs to a different Caplet.");
-	return decoded.downstreamUri;
-}
-//#endregion
 //#region src/cli/install.ts
 function installCaplets(repo, options = {}) {
 	const source = resolveInstallSource(repo);
@@ -12109,14 +11892,24 @@ function parseSupersededRefreshTokens(value) {
 }
 //#endregion
 //#region src/serve/http.ts
+const CAPLETS_STACK_CHAIN_HEADER = "caplets-stack-chain";
+const ATTACH_SESSION_IDLE_TIMEOUT_MS = 10 * 6e4;
+const ATTACH_SESSION_PRUNE_INTERVAL_MS = 6e4;
 function createHttpServeApp(options, engine, io = {}) {
 	const app = new Hono();
 	const sessions = /* @__PURE__ */ new Map();
+	const attachSessions = /* @__PURE__ */ new Map();
+	const defaultAttachSessions = /* @__PURE__ */ new Map();
+	const defaultAttachSessionPromises = /* @__PURE__ */ new Map();
 	const attachEventStreams = /* @__PURE__ */ new Set();
+	const attachSessionPruneTimer = setInterval(() => pruneIdleAttachSessions(), ATTACH_SESSION_PRUNE_INTERVAL_MS);
+	attachSessionPruneTimer.unref?.();
 	const writeErr = io.writeErr ?? process.stderr.write.bind(process.stderr);
 	const paths = servicePaths(options.path);
+	const stackIdentity = httpStackIdentity(options);
 	const authFlowStore = io.authFlowStore ?? new RemoteAuthFlowStore();
 	const exposeAttach = io.exposeAttach ?? true;
+	const exposeAttachSessions = exposeAttach && Boolean(io.attachSessionFactory);
 	const remoteCredentialStore = remoteCredentialStoreForOptions(options, io.remoteCredentialStore);
 	if (options.auth.type === "remote_credentials" && options.trustProxy === true && options.publicOrigin === void 0) throw new CapletsError("REQUEST_INVALID", "Remote credential auth with --trust-proxy requires CAPLETS_SERVER_URL.");
 	const protectedRouteAuth = routeAuth(options, remoteCredentialStore, paths.base);
@@ -12130,14 +11923,20 @@ function createHttpServeApp(options, engine, io = {}) {
 			name: "caplets",
 			transport: "http",
 			base: paths.base,
-			versions: [versionDiscovery(paths, exposeAttach, remote)],
+			versions: [versionDiscovery(paths, {
+				exposeAttach,
+				exposeAttachSessions
+			}, remote)],
 			auth: { type: options.auth.type },
 			...remote ? { remote } : {}
 		});
 	});
 	app.get(paths.version, (c) => {
 		const remote = remoteCredentialStore ? remoteHostMetadata(c.req.url, paths.base, options, (name) => c.req.header(name)) : void 0;
-		return c.json(versionDiscovery(paths, exposeAttach, remote));
+		return c.json(versionDiscovery(paths, {
+			exposeAttach,
+			exposeAttachSessions
+		}, remote));
 	});
 	app.get(paths.health, (c) => c.json({ status: "ok" }));
 	if (remoteCredentialStore) {
@@ -12272,14 +12071,68 @@ function createHttpServeApp(options, engine, io = {}) {
 		return session.transport.handleRequest(c);
 	});
 	if (exposeAttach) {
+		if (io.attachSessionFactory) {
+			app.post(paths.attachSessions, attachHostProtection, protectedRouteAuth, async (c) => {
+				try {
+					const metadata = parseAttachSessionMetadata(await parseJsonObject(c.req.json(), "Attach session request"), { allowProjectContext: allowAttachSessionProjectContext(options, c.req.url, (name) => c.req.header(name)) });
+					const context = attachSessionContext(c.req.header(CAPLETS_STACK_CHAIN_HEADER));
+					const sessionId = randomUUID();
+					const session = await io.attachSessionFactory(metadata, context);
+					attachSessions.set(sessionId, {
+						session,
+						lastUsedAt: Date.now()
+					});
+					pruneIdleAttachSessions();
+					return c.json({ sessionId }, 201);
+				} catch (error) {
+					const response = attachErrorResponse(error);
+					return c.json(response.body, response.status);
+				}
+			});
+			app.delete(routePath(paths.attachSessions, ":sessionId"), attachHostProtection, protectedRouteAuth, async (c) => {
+				const sessionId = c.req.param("sessionId");
+				if (!sessionId) return c.json({
+					ok: false,
+					error: { code: "REQUEST_INVALID" }
+				}, 400);
+				const record = attachSessions.get(sessionId);
+				attachSessions.delete(sessionId);
+				await record?.session.close();
+				return c.json({ ok: true });
+			});
+		}
 		app.get(paths.attachManifest, attachHostProtection, protectedRouteAuth, async (c) => {
-			const attachProjection = await buildAttachProjection(engine);
-			return c.json(attachProjection.manifest);
+			try {
+				const attachSessionId = c.req.header(CAPLETS_ATTACH_SESSION_HEADER);
+				const attachSession = attachSessionId ? attachSessionForRequest(attachSessionId) : await fallbackAttachSession(attachSessionContext(c.req.header(CAPLETS_STACK_CHAIN_HEADER)));
+				if (attachSession) return c.json(await attachSession.manifest());
+				const attachProjection = await buildAttachProjection(engine);
+				return c.json(attachProjection.manifest);
+			} catch (error) {
+				const response = attachErrorResponse(error);
+				return c.json(response.body, response.status);
+			}
+		});
+		app.get(paths.attachEvents, attachHostProtection, protectedRouteAuth, async (c) => {
+			try {
+				const attachSessionId = c.req.header(CAPLETS_ATTACH_SESSION_HEADER);
+				return attachEventsResponse(attachEventSource(engine, attachSessionId ? attachSessionForRequest(attachSessionId) : await fallbackAttachSession(attachSessionContext(c.req.header(CAPLETS_STACK_CHAIN_HEADER)))), attachEventStreams, { onActivity: () => {
+					if (attachSessionId) touchAttachSession(attachSessionId);
+				} });
+			} catch (error) {
+				const response = attachErrorResponse(error);
+				return c.json(response.body, response.status);
+			}
 		});
-		app.get(paths.attachEvents, attachHostProtection, protectedRouteAuth, () => attachEventsResponse(engine, attachEventStreams));
 		app.post(paths.attachInvoke, attachHostProtection, protectedRouteAuth, async (c) => {
 			try {
 				const request = await parseAttachInvokeRequest(c.req.json());
+				const attachSessionId = c.req.header(CAPLETS_ATTACH_SESSION_HEADER);
+				const attachSession = attachSessionId ? attachSessionForRequest(attachSessionId) : await fallbackAttachSession(attachSessionContext(c.req.header(CAPLETS_STACK_CHAIN_HEADER)));
+				if (attachSession) return c.json({
+					ok: true,
+					data: await attachSession.invoke(request)
+				});
 				const result = await invokeAttachExport(engine, await buildAttachProjection(engine), request);
 				return c.json({
 					ok: true,
@@ -12291,6 +12144,52 @@ function createHttpServeApp(options, engine, io = {}) {
 			}
 		});
 	}
+	function attachSessionForRequest(sessionId) {
+		pruneIdleAttachSessions();
+		if (!sessionId) return void 0;
+		const record = attachSessions.get(sessionId);
+		if (!record) throw new CapletsError("REQUEST_INVALID", "Attach session was not found.");
+		record.lastUsedAt = Date.now();
+		return record.session;
+	}
+	async function fallbackAttachSession(context) {
+		if (!io.defaultAttachSessionFactory) return void 0;
+		const key = context.stackChain.join("\0");
+		const existing = defaultAttachSessions.get(key);
+		if (existing) return existing;
+		let pending = defaultAttachSessionPromises.get(key);
+		if (!pending) {
+			pending = Promise.resolve(io.defaultAttachSessionFactory({}, context)).then((session) => {
+				defaultAttachSessions.set(key, session);
+				defaultAttachSessionPromises.delete(key);
+				return session;
+			}, (error) => {
+				defaultAttachSessionPromises.delete(key);
+				throw error;
+			});
+			defaultAttachSessionPromises.set(key, pending);
+		}
+		return await pending;
+	}
+	function attachSessionContext(header) {
+		const incoming = stackChainFromHeader(header);
+		if (incoming.includes(stackIdentity)) throw new CapletsError("REQUEST_INVALID", "Stacked runtime upstream cycle detected.");
+		return { stackChain: [...incoming, stackIdentity] };
+	}
+	function touchAttachSession(sessionId) {
+		const record = attachSessions.get(sessionId);
+		if (record) record.lastUsedAt = Date.now();
+	}
+	function pruneIdleAttachSessions() {
+		const expiresBefore = Date.now() - ATTACH_SESSION_IDLE_TIMEOUT_MS;
+		for (const [sessionId, record] of attachSessions) {
+			if (record.lastUsedAt >= expiresBefore) continue;
+			attachSessions.delete(sessionId);
+			record.session.close().catch((error) => {
+				writeErr(`Could not close idle attach session: ${errorMessage$1(error)}\n`);
+			});
+		}
+	}
 	app.post(paths.control, protectedRouteAuth, async (c) => {
 		let request;
 		try {
@@ -12314,31 +12213,9 @@ function createHttpServeApp(options, engine, io = {}) {
 		bindingId: c.req.param("bindingId"),
 		state: "not_attached"
 	}));
-	app.post(routePath(paths.projectBindings, "sessions"), protectedRouteAuth, (c) => {
-		const bindingId = randomUUID();
-		return c.json({
-			binding: {
-				bindingId,
-				state: "attaching",
-				syncState: "pending"
-			},
-			sessionId: randomUUID()
-		}, 201);
-	});
-	app.post(routePath(paths.projectBindings, ":bindingId/heartbeat"), protectedRouteAuth, (c) => c.json({
-		ok: true,
-		binding: {
-			bindingId: c.req.param("bindingId"),
-			state: "ready"
-		}
-	}));
-	app.delete(routePath(paths.projectBindings, ":bindingId/session"), protectedRouteAuth, (c) => c.json({
-		ok: true,
-		binding: {
-			bindingId: c.req.param("bindingId"),
-			state: "ended"
-		}
-	}));
+	app.post(routePath(paths.projectBindings, "sessions"), protectedRouteAuth, (c) => c.json(projectBindingUnsupported(), 501));
+	app.post(routePath(paths.projectBindings, ":bindingId/heartbeat"), protectedRouteAuth, (c) => c.json(projectBindingUnsupported(c.req.param("bindingId")), 501));
+	app.delete(routePath(paths.projectBindings, ":bindingId/session"), protectedRouteAuth, (c) => c.json(projectBindingUnsupported(c.req.param("bindingId")), 501));
 	app.get(routePath(paths.control, "auth/callback/:flowId"), async (c) => {
 		const flowId = c.req.param("flowId");
 		const result = await dispatchRemoteCliRequest({
@@ -12353,11 +12230,17 @@ function createHttpServeApp(options, engine, io = {}) {
 	});
 	app.notFound((c) => c.json({ error: "not_found" }, 404));
 	app.closeCapletsSessions = async () => {
+		clearInterval(attachSessionPruneTimer);
 		for (const stream of attachEventStreams) stream.close();
 		await Promise.allSettled([...sessions.values()].map(async (session) => {
 			await session.server.close();
 		}));
 		sessions.clear();
+		await Promise.allSettled([...attachSessions.values()].map((record) => record.session.close()));
+		attachSessions.clear();
+		await Promise.allSettled([...defaultAttachSessions.values()].map((session) => session.close()));
+		defaultAttachSessions.clear();
+		defaultAttachSessionPromises.clear();
 	};
 	if (options.warnUnauthenticatedNetwork) writeErr(`Warning: Caplets MCP HTTP server is listening on ${options.host} without authentication.\n`);
 	return app;
@@ -12390,9 +12273,36 @@ function remoteCredentialSourceHint(trustProxy, header) {
 	const sourceHint = firstForwardedValue(header("x-forwarded-for")) ?? firstForwardedValue(header("x-real-ip")) ?? firstForwardedValue(header("cf-connecting-ip"));
 	return sourceHint ? { sourceHint } : {};
 }
+function projectBindingUnsupported(bindingId) {
+	return {
+		ok: false,
+		error: {
+			code: "UNSUPPORTED_CAPABILITY",
+			message: "Self-hosted Project Binding sessions are not implemented by this runtime."
+		},
+		...bindingId ? { binding: {
+			bindingId,
+			state: "not_attached"
+		} } : {}
+	};
+}
 function firstForwardedValue(value) {
 	return value?.split(",", 1)[0]?.trim() || void 0;
 }
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function httpStackIdentity(options) {
+	const origin = options.publicOrigin ?? `http://${formatHost$2(options.host)}:${options.port}`;
+	const url = new URL(origin);
+	url.pathname = options.path;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+function stackChainFromHeader(header) {
+	return (header ?? "").split(",").map((value) => value.trim()).filter((value) => value.length > 0);
+}
 function remoteHostMetadata(requestUrl, basePath, options, header) {
 	const audience = remoteCredentialHostUrl(requestUrl, basePath, options.publicOrigin, options.trustProxy, header);
 	return {
@@ -12400,7 +12310,9 @@ function remoteHostMetadata(requestUrl, basePath, options, header) {
 		audience
 	};
 }
-function versionDiscovery(paths, exposeAttach = true, remote) {
+function versionDiscovery(paths, options = {}, remote) {
+	const exposeAttach = options.exposeAttach ?? true;
+	const exposeAttachSessions = options.exposeAttachSessions ?? false;
 	return {
 		version: 1,
 		path: paths.version,
@@ -12409,6 +12321,7 @@ function versionDiscovery(paths, exposeAttach = true, remote) {
 			mcp: paths.mcp,
 			admin: paths.control,
 			...exposeAttach ? {
+				...exposeAttachSessions ? { attachSessions: paths.attachSessions } : {},
 				attachManifest: paths.attachManifest,
 				attachEvents: paths.attachEvents,
 				attachInvoke: paths.attachInvoke
@@ -12438,10 +12351,82 @@ async function parseAttachInvokeRequest(input) {
 function isAttachExportKind(value) {
 	return value === "caplet" || value === "tool" || value === "resource" || value === "resourceTemplate" || value === "prompt" || value === "completion";
 }
-function attachEventsResponse(engine, activeStreams) {
+function parseAttachSessionMetadata(input, options) {
+	const rawProjectRoot = optionalStringField(input, "projectRoot");
+	const rawProjectConfigPath = optionalStringField(input, "projectConfigPath");
+	if (!options.allowProjectContext && (rawProjectRoot || rawProjectConfigPath)) throw new CapletsError("REQUEST_INVALID", "Attach session project context is only accepted by loopback runtimes.");
+	const projectRoot = canonicalProjectRoot(rawProjectRoot);
+	const projectConfigPath = canonicalProjectConfigPath(rawProjectConfigPath, projectRoot);
+	return {
+		...projectRoot ? { projectRoot } : {},
+		...projectConfigPath ? { projectConfigPath } : {}
+	};
+}
+function canonicalProjectRoot(projectRoot) {
+	if (!projectRoot) return void 0;
+	try {
+		const canonical = realpathSync(projectRoot);
+		if (!statSync(canonical).isDirectory()) throw new Error("projectRoot is not a directory.");
+		return canonical;
+	} catch (error) {
+		throw new CapletsError("REQUEST_INVALID", "projectRoot must be an existing directory.", error);
+	}
+}
+function canonicalProjectConfigPath(projectConfigPath, projectRoot) {
+	if (!projectRoot) {
+		if (!projectConfigPath) return void 0;
+		throw new CapletsError("REQUEST_INVALID", "projectConfigPath requires projectRoot.");
+	}
+	const expectedProjectConfigPath = resolve(projectRoot, ".caplets", "config.json");
+	const lexicalConfigPath = projectConfigPath === void 0 ? expectedProjectConfigPath : isAbsolute(projectConfigPath) ? projectConfigPath : resolve(projectRoot, projectConfigPath);
+	if (resolve(projectConfigPath === void 0 ? expectedProjectConfigPath : canonicalizeExistingParentPath(lexicalConfigPath)) !== expectedProjectConfigPath) throw new CapletsError("REQUEST_INVALID", "projectConfigPath must be <projectRoot>/.caplets/config.json.");
+	if (!existsSync(expectedProjectConfigPath)) return expectedProjectConfigPath;
+	const expected = realpathSync(expectedProjectConfigPath);
+	if (!pathIsInside(expected, projectRoot)) throw new CapletsError("REQUEST_INVALID", "projectConfigPath must resolve inside projectRoot.");
+	return expected;
+}
+function canonicalizeExistingParentPath(path) {
+	const parent = dirname(path);
+	try {
+		return resolve(realpathSync(parent), path.slice(parent.length + 1));
+	} catch {
+		return resolve(path);
+	}
+}
+function pathIsInside(candidate, root) {
+	const rel = relative(root, candidate);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function allowAttachSessionProjectContext(options, requestUrl, header) {
+	if (!options.loopback) return false;
+	return isLoopbackHost(attachRequestHost(options, requestUrl, header));
+}
+function attachRequestHost(options, requestUrl, header) {
+	const fallback = new URL(requestUrl).host;
+	const host = (options.trustProxy ? firstForwardedValue(header("x-forwarded-host")) : void 0) ?? header("host") ?? fallback;
+	try {
+		return new URL(`http://${host}`).hostname;
+	} catch {
+		return host.split(":")[0] ?? host;
+	}
+}
+function attachEventSource(engine, session) {
+	if (session) return {
+		manifestRevision: async () => (await session.manifest()).revision,
+		onManifestChanged: (listener) => session.onManifestChanged(listener)
+	};
+	return {
+		manifestRevision: async () => (await buildAttachProjection(engine)).manifest.revision,
+		onManifestChanged: (listener) => engine.onReload(() => {
+			listener();
+		})
+	};
+}
+function attachEventsResponse(source, activeStreams, options = {}) {
 	const encoder = new TextEncoder();
 	let unsubscribe = () => void 0;
 	let activeStream;
+	let keepAliveTimer;
 	let closed = false;
 	const readable = new ReadableStream({
 		start(controller) {
@@ -12449,17 +12434,30 @@ function attachEventsResponse(engine, activeStreams) {
 				if (closed) return;
 				closed = true;
 				unsubscribe();
+				if (keepAliveTimer) clearInterval(keepAliveTimer);
 				if (activeStream) activeStreams.delete(activeStream);
 				try {
 					controller.close();
 				} catch {}
 			} };
 			activeStreams.add(activeStream);
+			options.onActivity?.();
 			controller.enqueue(encoder.encode(": connected\n\n"));
-			unsubscribe = engine.onReload(() => {
-				buildAttachProjection(engine).then((projection) => {
+			keepAliveTimer = setInterval(() => {
+				if (closed) return;
+				options.onActivity?.();
+				try {
+					controller.enqueue(encoder.encode(": keepalive\n\n"));
+				} catch {
+					activeStream?.close();
+				}
+			}, 3e4);
+			keepAliveTimer.unref?.();
+			unsubscribe = source.onManifestChanged(() => {
+				options.onActivity?.();
+				source.manifestRevision().then((revision) => {
 					if (closed) return;
-					controller.enqueue(encoder.encode(`event: manifest_changed\ndata: ${JSON.stringify({ revision: projection.manifest.revision })}\n\n`));
+					controller.enqueue(encoder.encode(`event: manifest_changed\ndata: ${JSON.stringify({ revision })}\n\n`));
 				}).catch(() => void 0);
 			});
 		},
@@ -12489,7 +12487,7 @@ async function serveHttp(options, engineOptions = {}, writeErr = (value) => proc
 		}
 	});
 	const paths = servicePaths(options.path);
-	const origin = `http://${formatHost$1(options.host)}:${options.port}`;
+	const origin = `http://${formatHost$2(options.host)}:${options.port}`;
 	const baseUrl = `${origin}${paths.base === "/" ? "" : paths.base}`;
 	installHttpSignalHandlers(serve({
 		fetch: app.fetch,
@@ -12504,20 +12502,26 @@ async function serveHttp(options, engineOptions = {}, writeErr = (value) => proc
 		writeErr(`Auth: ${authDescription(options)}\n`);
 	}), app, engine, writeErr);
 }
-async function serveHttpWithSessionFactory(options, createSession, writeErr = (value) => process.stderr.write(value)) {
-	const resolvedEngineOptions = { exposeLocalArtifactPaths: false };
+async function serveHttpWithSessionFactory(options, createSession, writeErr = (value) => process.stderr.write(value), io = {}, engineOptions = {}) {
+	const resolvedEngineOptions = {
+		exposeLocalArtifactPaths: false,
+		vaultRecoveryTarget: "remote",
+		...engineOptions
+	};
 	const engine = new CapletsEngine(resolvedEngineOptions);
 	const app = createHttpServeApp(options, engine, {
 		writeErr,
-		exposeAttach: false,
+		exposeAttach: io.exposeAttach ?? false,
 		sessionFactory: createSession,
+		...io.attachSessionFactory ? { attachSessionFactory: io.attachSessionFactory } : {},
+		...io.defaultAttachSessionFactory ? { defaultAttachSessionFactory: io.defaultAttachSessionFactory } : {},
 		control: {
 			...resolvedEngineOptions,
-			projectCapletsRoot: resolveProjectCapletsRoot()
+			projectCapletsRoot: projectCapletsRootForEngineOptions(resolvedEngineOptions)
 		}
 	});
 	const paths = servicePaths(options.path);
-	const origin = `http://${formatHost$1(options.host)}:${options.port}`;
+	const origin = `http://${formatHost$2(options.host)}:${options.port}`;
 	const baseUrl = `${origin}${paths.base === "/" ? "" : paths.base}`;
 	installHttpSignalHandlers(serve({
 		fetch: app.fetch,
@@ -12549,6 +12553,7 @@ function servicePaths(base) {
 		version,
 		mcp: routePath(version, "mcp"),
 		control: routePath(version, "admin"),
+		attachSessions: routePath(attach, "sessions"),
 		attachManifest: routePath(attach, "manifest"),
 		attachEvents: routePath(attach, "events"),
 		attachInvoke: routePath(attach, "invoke"),
@@ -12692,7 +12697,7 @@ function installHttpSignalHandlers(server, app, engine, writeErr) {
 function closeAllServerConnections(server) {
 	server.closeAllConnections?.call(server);
 }
-function formatHost$1(host) {
+function formatHost$2(host) {
 	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 //#endregion
@@ -12823,11 +12828,11 @@ async function allocateLoopbackPort() {
 	if (!address || typeof address === "string") throw new CapletsError("SERVER_UNAVAILABLE", "Could not allocate a validation port.");
 	return address.port;
 }
-function formatHost(host) {
+function formatHost$1(host) {
 	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 function healthUrl(config, port = config.serve.port) {
-	return `http://${formatHost(config.serve.host)}:${port}${servicePaths(config.serve.path).health}`;
+	return `http://${formatHost$1(config.serve.host)}:${port}${servicePaths(config.serve.path).health}`;
 }
 function validationSpawnCommand(config) {
 	const planned = serviceCommand(config);
@@ -14708,6 +14713,7 @@ function createAttachNativeService(options, io) {
 	return createNativeCapletsService({
 		mode: options.selection.kind === "hosted_cloud" ? "cloud" : "remote",
 		configPath: options.configPath,
+		projectRoot: options.projectRoot,
 		projectConfigPath: options.projectConfigPath,
 		...options.authDir ? { authDir: options.authDir } : {},
 		remote: {
@@ -15325,15 +15331,95 @@ async function serveResolvedCaplets(resolved, engineOptions = {}, writeErr) {
 		});
 		return;
 	}
+	if (resolved.upstreamUrl) {
+		await serveHttpWithUpstream(resolved, resolved.upstreamUrl, engineOptions, writeErr);
+		return;
+	}
 	await serveHttp(resolved, {
 		...engineOptions,
 		...writeErr ? { writeErr } : {}
 	}, writeErr);
 }
+async function serveHttpWithUpstream(resolved, upstreamUrl, engineOptions, writeErr) {
+	const stackChain = [serveStackIdentity(resolved)];
+	await serveHttpWithSessionFactory(resolved, async () => new NativeCapletsMcpSession(await createReloadedUpstreamService(upstreamUrl, engineOptions, writeErr, {}, stackChain)), writeErr, {
+		exposeAttach: true,
+		defaultAttachSessionFactory: async (_metadata, context) => nativeAttachSession(await createReloadedUpstreamService(upstreamUrl, engineOptions, writeErr, {}, context.stackChain)),
+		attachSessionFactory: async (metadata, context) => {
+			return nativeAttachSession(await createReloadedUpstreamService(upstreamUrl, engineOptions, writeErr, metadata, context.stackChain));
+		}
+	}, engineOptions);
+}
+async function createReloadedUpstreamService(upstreamUrl, engineOptions, writeErr, metadata = {}, stackChain = []) {
+	const service = createUpstreamNativeService(upstreamUrl, engineOptions, writeErr, metadata, stackChain);
+	try {
+		await service.reload();
+		return service;
+	} catch (error) {
+		await service.close().catch(() => void 0);
+		throw error;
+	}
+}
+function createUpstreamNativeService(upstreamUrl, engineOptions, writeErr, metadata = {}, stackChain = []) {
+	return createNativeCapletsService({
+		...engineOptions,
+		...metadata.projectRoot ? { projectRoot: metadata.projectRoot } : {},
+		...metadata.projectConfigPath ? { projectConfigPath: metadata.projectConfigPath } : {},
+		mode: isCapletsCloudUrl(upstreamUrl) ? "cloud" : "remote",
+		remote: {
+			url: upstreamUrl,
+			...stackChain.length > 0 ? { requestHeaders: { [CAPLETS_STACK_CHAIN_HEADER]: stackChain.join(",") } } : {}
+		},
+		...writeErr ? { writeErr } : {}
+	});
+}
+function serveStackIdentity(options) {
+	const origin = options.publicOrigin ?? `http://${formatHost(options.host)}:${options.port}`;
+	const url = new URL(origin);
+	url.pathname = options.path;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+function formatHost(host) {
+	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function nativeAttachSession(service) {
+	let cachedProjection;
+	const getProjection = async () => {
+		cachedProjection ??= await buildNativeAttachProjection(service);
+		return cachedProjection;
+	};
+	const unsubscribe = service.onToolsChanged(() => {
+		cachedProjection = void 0;
+	});
+	return {
+		manifest: async () => (await getProjection()).manifest,
+		invoke: async (request) => await invokeNativeAttachExport(service, await getProjection(), request),
+		onManifestChanged: (listener) => service.onToolsChanged(() => listener()),
+		close: async () => {
+			unsubscribe();
+			await service.close();
+		}
+	};
+}
 //#endregion
 //#region src/cli.ts
 async function runCli(args, io = {}) {
-	const program = createProgram(io);
+	let observedExitCode = 0;
+	const wrappedIo = {
+		...io,
+		setExitCode: (code) => {
+			observedExitCode = code;
+			if (io.setExitCode) io.setExitCode(code);
+			else process.exitCode = code;
+		}
+	};
+	const program = createProgram(wrappedIo);
+	const trackedCommand = telemetryCommandFamilyFromArgs(args);
+	const startedAt = Date.now();
+	const telemetryContext = telemetryContextForIo(wrappedIo);
+	const dispatcher = createTelemetryDispatcher({ stateDir: telemetryContext.stateDir });
 	try {
 		if (args.length === 0) {
 			program.outputHelp();
@@ -15344,12 +15430,35 @@ async function runCli(args, io = {}) {
 			"caplets",
 			...args
 		]);
+		if (trackedCommand) await captureCliTelemetry(telemetryContext, {
+			debugSink: wrappedIo.telemetryDebugSink,
+			dispatcher,
+			commandFamily: trackedCommand.commandFamily,
+			surface: trackedCommand.surface,
+			outcome: observedExitCode === 0 ? "success" : "failure",
+			startedAt
+		});
 	} catch (error) {
+		let normalizedError = error;
+		let captureProductEvent = true;
 		if (error instanceof CommanderError) {
 			if (error.code === "commander.helpDisplayed" || error.code === "commander.version" || error.message === "(outputHelp)") return;
-			throw new CapletsError("REQUEST_INVALID", error.message);
-		}
-		throw error;
+			normalizedError = new CapletsError("REQUEST_INVALID", error.message);
+			captureProductEvent = false;
+		}
+		if (trackedCommand) await captureCliTelemetry(telemetryContext, {
+			debugSink: wrappedIo.telemetryDebugSink,
+			dispatcher,
+			commandFamily: trackedCommand.commandFamily,
+			surface: trackedCommand.surface,
+			outcome: "failure",
+			startedAt,
+			error: normalizedError,
+			productEvent: captureProductEvent
+		}).catch(() => void 0);
+		throw normalizedError;
+	} finally {
+		await dispatcher.shutdown();
 	}
 }
 function normalizeCompletionWords(words) {
@@ -15370,6 +15479,249 @@ function collectValues(value, previous) {
 	return [...previous, value];
 }
 const HIDDEN_INPUT_PROMPT_LABELS = { vaultValue: "Value: " };
+function telemetryContextForIo(io) {
+	const env = io.env ?? process.env;
+	return {
+		env,
+		configPath: envConfigPath(env),
+		projectConfigPath: envProjectConfigPath(env),
+		stateDir: io.telemetryStateDir ?? defaultTelemetryStateDir(env),
+		stderrIsTTY: io.stderrIsTTY ?? process.stderr.isTTY === true,
+		writeErr: io.writeErr ?? ((value) => process.stderr.write(value))
+	};
+}
+function telemetryCommandFamilyFromArgs(args) {
+	const command = args[0];
+	if (command === void 0 || command === "--help" || command === "-h" || command === "--version" || command === "-V" || command === cliCommands$1.telemetry || command === cliCommands$1.completion || command === cliCommands$1.completeHidden) return;
+	if (command === cliCommands$1.serve) return {
+		commandFamily: "serve",
+		surface: "serve"
+	};
+	if (command === cliCommands$1.attach) return {
+		commandFamily: "attach",
+		surface: "attach"
+	};
+	if (command === cliCommands$1.daemon) return {
+		commandFamily: "daemon",
+		surface: "daemon"
+	};
+	if (command === cliCommands$1.codeMode) return {
+		commandFamily: "code_mode",
+		surface: "code_mode"
+	};
+	if (command === cliCommands$1.setup) return {
+		commandFamily: "setup",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.init) return {
+		commandFamily: "init",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.install) return {
+		commandFamily: "install",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.add) return {
+		commandFamily: "add",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.doctor) return {
+		commandFamily: "doctor",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.auth) return {
+		commandFamily: "auth",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.remote || command === cliCommands$1.cloud) return {
+		commandFamily: "remote",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.inspect) return {
+		commandFamily: "inspect",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.checkBackend) return {
+		commandFamily: "check",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.listTools || command === cliCommands$1.searchTools || command === cliCommands$1.getTool || command === cliCommands$1.callTool) return {
+		commandFamily: "tools",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.listResources || command === cliCommands$1.searchResources || command === cliCommands$1.listResourceTemplates || command === cliCommands$1.readResource) return {
+		commandFamily: "resources",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.listPrompts || command === cliCommands$1.searchPrompts || command === cliCommands$1.getPrompt) return {
+		commandFamily: "prompts",
+		surface: "cli"
+	};
+	if (command === cliCommands$1.complete) return {
+		commandFamily: "complete",
+		surface: "cli"
+	};
+	return {
+		commandFamily: "unknown",
+		surface: "cli"
+	};
+}
+function telemetryConfigForCli(context) {
+	try {
+		return loadConfigWithSources(context.configPath, context.projectConfigPath, { vaultResolver: vaultBootstrapResolver }).config;
+	} catch (error) {
+		if (error instanceof CapletsError && error.code !== "CONFIG_INVALID") return {};
+		return telemetryOnlyConfigForCli(resolveConfigPath(context.configPath)) ?? { telemetry: false };
+	}
+}
+function telemetryOnlyConfigForCli(path) {
+	try {
+		const config = readUserConfigObject(path);
+		return typeof config.telemetry === "boolean" ? { telemetry: config.telemetry } : void 0;
+	} catch {
+		return;
+	}
+}
+function maybePrintCliTelemetryNotice(context, surface) {
+	const state = resolveTelemetryState({
+		config: telemetryConfigForCli(context),
+		env: context.env,
+		stateDir: context.stateDir,
+		surface,
+		visibility: "visible",
+		allowWithoutNotice: true,
+		createIdentity: false
+	});
+	if (state.status !== "enabled" || state.notice.shown) return;
+	maybePrintTelemetryNotice({
+		stateDir: context.stateDir,
+		surface,
+		stderrIsTTY: context.stderrIsTTY,
+		writeErr: context.writeErr
+	});
+}
+async function captureCliTelemetry(context, options) {
+	try {
+		maybePrintCliTelemetryNotice(context, options.surface ?? "cli");
+	} catch {}
+	const state = resolveTelemetryState({
+		config: telemetryConfigForCli(context),
+		env: context.env,
+		stateDir: context.stateDir,
+		surface: options.surface ?? "cli",
+		visibility: "visible",
+		debug: context.env.CAPLETS_TELEMETRY_DEBUG === "1"
+	});
+	if (state.status !== "enabled" && state.status !== "debug") return;
+	const identity = state.status === "debug" ? readTelemetryIdentity({
+		stateDir: context.stateDir,
+		create: false
+	}) : state.identity ?? readTelemetryIdentity({
+		stateDir: context.stateDir,
+		create: true
+	});
+	if (options.productEvent !== false) {
+		const product = buildProductTelemetryEvent({
+			name: "caplets_cli_command",
+			distinctId: identity.id,
+			properties: {
+				package: "@caplets/core",
+				version,
+				surface: options.surface ?? "cli",
+				runtime_mode: runtimeModeForEnv(context.env),
+				execution_context: state.executionContext,
+				command_family: options.commandFamily,
+				outcome: options.outcome,
+				duration_bucket: durationBucket(Date.now() - options.startedAt)
+			}
+		});
+		if (state.status === "debug") options.debugSink?.capture("debug", product);
+		else await (options.dispatcher ?? createTelemetryDispatcher({ stateDir: context.stateDir })).capture(state, product);
+	}
+	if (options.outcome !== "failure") return;
+	if (options.error === void 0) return;
+	const reliability = buildReliabilityTelemetryEvent({
+		name: "caplets_reliability_error",
+		properties: {
+			package: "@caplets/core",
+			version,
+			surface: options.surface ?? "cli",
+			runtime_mode: runtimeModeForEnv(context.env),
+			command_family: options.commandFamily,
+			error_code: errorCodeForTelemetry(options.error),
+			diagnostic_category: diagnosticCategoryForError(options.error),
+			os_family: platform(),
+			arch: arch(),
+			node_major: Number(process.versions.node.split(".")[0] ?? 0)
+		}
+	});
+	if (state.status === "debug") {
+		options.debugSink?.capture("debug", reliability);
+		return;
+	}
+	await (options.dispatcher ?? createTelemetryDispatcher({ stateDir: context.stateDir })).capture(state, reliability);
+}
+function readUserConfigObject(path) {
+	if (!existsSync(path)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+	} catch (error) {
+		throw new CapletsError("CONFIG_INVALID", `Caplets config at ${path} is not valid JSON`, error);
+	}
+}
+function runtimeModeForEnv(env) {
+	const mode = env.CAPLETS_MODE;
+	return mode === "remote" || mode === "cloud" || mode === "local" ? mode : "unknown";
+}
+function errorCodeForTelemetry(error) {
+	if (error instanceof CapletsError) return error.code;
+	return "UNKNOWN";
+}
+function diagnosticCategoryForError(error) {
+	if (!(error instanceof CapletsError)) return "unknown";
+	if (error.code.startsWith("CONFIG")) return "config";
+	if (error.code.startsWith("AUTH")) return "auth";
+	if (error.code.includes("NETWORK") || error.code.includes("UNAVAILABLE")) return "network";
+	if (error.code.includes("VALID") || error.code.includes("REQUEST")) return "validation";
+	return "runtime";
+}
+function writeTelemetryConfig(path, enabled) {
+	const config = {
+		...readUserConfigObject(path),
+		$schema: "https://caplets.dev/config.schema.json",
+		telemetry: enabled
+	};
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
+}
+function formatTelemetryStatus(context) {
+	const config = telemetryConfigForCli(context);
+	const state = resolveTelemetryState({
+		config,
+		env: context.env,
+		stateDir: context.stateDir,
+		surface: "cli",
+		visibility: "visible",
+		createIdentity: false
+	});
+	const notice = readTelemetryNotice({ stateDir: context.stateDir });
+	const identity = readTelemetryIdentity({
+		stateDir: context.stateDir,
+		create: false
+	});
+	const health = readTelemetryDeliveryHealth({ stateDir: context.stateDir });
+	return `${[
+		`Telemetry: ${state.status}`,
+		`Decision: ${state.decider}`,
+		`Config: ${config.telemetry === false ? "disabled" : "enabled"}`,
+		`Environment: ${context.env.CAPLETS_DISABLE_TELEMETRY === "1" ? "disabled" : "enabled"}`,
+		`Notice shown: ${notice.shown ? `yes (${notice.surface})` : "no"}`,
+		`Anonymous ID: ${identity.kind === "stable" ? "present" : "not stored"}`,
+		`Delivery health: ${Object.keys(health).length === 0 ? "none" : JSON.stringify(health)}`,
+		"Disable with CAPLETS_DISABLE_TELEMETRY=1 or `caplets telemetry disable`."
+	].join("\n")}\n`;
+}
 function remoteProfileStore(authDir, env) {
 	return createRemoteProfileStore({
 		authDir,
@@ -15380,6 +15732,21 @@ function attachRemoteUrlFromArgs(positionalUrl, legacyRemoteUrl) {
 	if (positionalUrl && legacyRemoteUrl && positionalUrl !== legacyRemoteUrl) throw new CapletsError("REQUEST_INVALID", "Pass either attach URL or --remote-url, not both. Use caplets attach <url> for new configs.");
 	return positionalUrl ?? legacyRemoteUrl;
 }
+function rejectAttachHttpServeFlags(options) {
+	const invalid = [
+		options.transport !== void 0 ? "--transport" : void 0,
+		options.host !== void 0 ? "--host" : void 0,
+		options.port !== void 0 ? "--port" : void 0,
+		options.path !== void 0 ? "--path" : void 0,
+		options.allowUnauthenticatedHttp === true ? "--allow-unauthenticated-http" : void 0,
+		options.trustProxy === true ? "--trust-proxy" : void 0
+	].filter((value) => value !== void 0);
+	if (invalid.length === 0) return;
+	throw new CapletsError("REQUEST_INVALID", `caplets attach is stdio-only; ${invalid.join(", ")} ${invalid.length === 1 ? "is" : "are"} no longer supported. Use caplets serve --transport http --upstream-url <url> to start an HTTP stacked runtime.`);
+}
+function hiddenOption(flags, description) {
+	return new Option(flags, description).hideHelp();
+}
 function remoteServerCredentialStore(statePath, env) {
 	return new RemoteServerCredentialStore({ dir: statePath ?? env.CAPLETS_REMOTE_SERVER_STATE_DIR ?? join(DEFAULT_AUTH_DIR, "remote-server") });
 }
@@ -15801,9 +16168,33 @@ function createProgram(io = {}) {
 	const writeErr = io.writeErr ?? ((value) => process.stderr.write(value));
 	const env = io.env ?? process.env;
 	const currentConfigPath = () => envConfigPath(env);
+	const telemetryContext = () => ({
+		env,
+		configPath: currentConfigPath(),
+		projectConfigPath: envProjectConfigPath(env),
+		stateDir: io.telemetryStateDir ?? defaultTelemetryStateDir(env),
+		stderrIsTTY: io.stderrIsTTY ?? process.stderr.isTTY === true,
+		writeErr
+	});
+	const printTelemetryNotice = (surface) => {
+		try {
+			maybePrintCliTelemetryNotice(telemetryContext(), surface);
+		} catch {}
+	};
 	const setExitCode = io.setExitCode ?? ((code) => {
 		process.exitCode = code;
 	});
+	const executeOperationIo = (format) => ({
+		writeOut,
+		writeErr,
+		setExitCode,
+		authDir: io.authDir,
+		env,
+		remote: remoteClientForCli(io),
+		format,
+		telemetryStateDir: telemetryContext().stateDir,
+		telemetryDebugSink: io.telemetryDebugSink
+	});
 	const program = new Command();
 	program.name("caplets").description("Progressive-disclosure gateway for MCP servers.").version(io.version ?? version).exitOverride().configureOutput({
 		writeOut,
@@ -15847,7 +16238,51 @@ function createProgram(io = {}) {
 		}
 		if (suggestions.length > 0) writeOut(`${suggestions.join("\n")}\n`);
 	});
+	const telemetry = program.command(cliCommands$1.telemetry).description("Inspect and control anonymous Caplets telemetry.");
+	telemetry.command("status").description("Show anonymous telemetry status.").action(() => {
+		writeOut(formatTelemetryStatus(telemetryContext()));
+	});
+	telemetry.command("enable").description("Enable anonymous telemetry in the user config.").action(() => {
+		const path = resolveConfigPath(currentConfigPath());
+		writeTelemetryConfig(path, true);
+		writeOut(`Enabled anonymous telemetry in ${path}.\n`);
+		if (env.CAPLETS_DISABLE_TELEMETRY === "1") writeOut("CAPLETS_DISABLE_TELEMETRY=1 still disables telemetry for this process.\n");
+	});
+	telemetry.command("disable").description("Disable anonymous telemetry in the user config.").action(() => {
+		const path = resolveConfigPath(currentConfigPath());
+		writeTelemetryConfig(path, false);
+		writeOut(`Disabled anonymous telemetry in ${path}.\n`);
+	});
+	telemetry.command("delete-id").description("Delete the local anonymous telemetry ID.").action(() => {
+		deleteTelemetryIdentity({ stateDir: telemetryContext().stateDir });
+		writeOut("Deleted the local anonymous telemetry ID. This does not delete provider-side historical anonymous events; provider retention controls historical data.\n");
+	});
+	telemetry.command("rotate-id").description("Rotate the local anonymous telemetry ID.").action(() => {
+		rotateTelemetryIdentity({ stateDir: telemetryContext().stateDir });
+		writeOut("Rotated the local anonymous telemetry ID. This does not delete provider-side historical anonymous events; provider retention controls historical data.\n");
+	});
+	telemetry.command("debug").description("Run a Caplets command with local telemetry debug output.").allowUnknownOption(true).argument("[args...]", "Caplets command and arguments after --").action(async (args) => {
+		const nestedArgs = args[0] === "--" ? args.slice(1) : args;
+		const sink = new TelemetryDebugSink();
+		try {
+			if (nestedArgs.length > 0) await runCli(nestedArgs, {
+				...io,
+				env: {
+					...env,
+					CAPLETS_TELEMETRY_DEBUG: "1"
+				},
+				telemetryDebugSink: sink,
+				writeOut,
+				writeErr
+			});
+		} finally {
+			writeOut(`${JSON.stringify({ telemetryDebug: sink.toJSON() }, null, 2)}\n`);
+		}
+	});
 	program.command(cliCommands$1.codeMode).description("Run, inspect, and debug Caplets Code Mode.").argument("[code]", "inline TypeScript code to run").option("--file <path>", "read TypeScript code from a file relative to the current directory").option("--session-id <id>", "optional Code Mode session identifier").option("--recover <ref>", "recover a prior Code Mode REPL session when supported").option("--timeout-ms <ms>", "execution timeout in milliseconds", parsePositiveInteger).option("--json", "print the structured run envelope").action(async (code, options) => {
+		try {
+			maybePrintCliTelemetryNotice(telemetryContext(), "code_mode");
+		} catch {}
 		if (code === "repl" && options.file === void 0) {
 			await runCodeModeReplCli({
 				env,
@@ -15881,6 +16316,7 @@ function createProgram(io = {}) {
 			...currentConfigPath() ? { configPath: currentConfigPath() } : {},
 			projectConfigPath: envProjectConfigPath(env),
 			...io.authDir ? { authDir: io.authDir } : {},
+			telemetryStateDir: telemetryContext().stateDir,
 			...code === void 0 ? {} : { inlineCode: code },
 			...options.file === void 0 ? {} : { file: options.file },
 			...options.sessionId === void 0 ? {} : { sessionId: options.sessionId },
@@ -15897,16 +16333,23 @@ function createProgram(io = {}) {
 			...currentConfigPath() ? { configPath: currentConfigPath() } : {},
 			projectConfigPath: envProjectConfigPath(env),
 			...io.authDir ? { authDir: io.authDir } : {},
+			telemetryStateDir: telemetryContext().stateDir,
 			...options.json === void 0 && parentOptions.json === void 0 ? {} : { json: options.json ?? parentOptions.json },
 			writeOut
 		});
 	});
-	const serve = program.command(cliCommands$1.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("--remote-state-path <path>", "server-owned remote credential state directory").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 serve = program.command(cliCommands$1.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("--remote-state-path <path>", "server-owned remote credential state directory").option("--upstream-url <url>", "upstream Caplets runtime URL to compose with this HTTP service").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) => {
+		printTelemetryNotice("serve");
 		const resolved = resolveServeOptions(options);
 		const configPath = currentConfigPath();
 		await (io.serve ?? ((serveOptions) => serveResolvedCaplets(serveOptions, {
 			...configPath ? { configPath } : {},
-			...io.authDir ? { authDir: io.authDir } : {}
+			...io.authDir ? { authDir: io.authDir } : {},
+			telemetryEnv: env,
+			telemetryStateDir: io.telemetryStateDir ?? defaultTelemetryStateDir(env),
+			telemetrySurface: "serve",
+			telemetryVisibility: "visible",
+			telemetryRuntimeMode: runtimeModeForEnv(env)
 		}, writeErr)))(resolved);
 	});
 	const daemonOptions = () => ({
@@ -15923,6 +16366,7 @@ function createProgram(io = {}) {
 	})) addServeMigrationCommand(serve, name, replacement);
 	const daemon = program.command(cliCommands$1.daemon).description("Install and manage the default Caplets daemon.");
 	addDaemonInstallOptions(daemon.command("install").description("Install or update the default Caplets daemon.")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const prompt = options.json ? void 0 : createSetupPromptHandle(io, writeOut);
 		try {
 			const result = await installDaemon(daemonInstallOptions(options), {
@@ -15946,6 +16390,7 @@ function createProgram(io = {}) {
 		}
 	});
 	addJsonOption(daemon.command("uninstall").description("Uninstall the default Caplets daemon.").option("--purge", "remove daemon config, state, and logs").option("--dry-run", "preview uninstall actions without mutation")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const result = await uninstallDaemon({
 			purge: options.purge === true,
 			dryRun: options.dryRun === true
@@ -15957,6 +16402,7 @@ function createProgram(io = {}) {
 		writeOut(result.dryRun ? "Would uninstall Caplets daemon.\n" : "Uninstalled Caplets daemon.\n");
 	});
 	addJsonOption(daemon.command("start").description("Start the default Caplets daemon.")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const result = await startDaemon(daemonOptions());
 		if (options.json) {
 			writeOut(`${JSON.stringify(result, null, 2)}\n`);
@@ -15965,6 +16411,7 @@ function createProgram(io = {}) {
 		writeOut(result.action === "restart" ? "Restarted Caplets daemon.\n" : "Started Caplets daemon.\n");
 	});
 	addJsonOption(daemon.command("restart").description("Restart the default Caplets daemon.")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const result = await restartDaemon(daemonOptions());
 		if (options.json) {
 			writeOut(`${JSON.stringify(result, null, 2)}\n`);
@@ -15973,6 +16420,7 @@ function createProgram(io = {}) {
 		writeOut("Restarted Caplets daemon.\n");
 	});
 	addJsonOption(daemon.command("stop").description("Stop the default Caplets daemon.")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const result = await stopDaemon(daemonOptions());
 		if (options.json) {
 			writeOut(`${JSON.stringify(result, null, 2)}\n`);
@@ -15981,6 +16429,7 @@ function createProgram(io = {}) {
 		writeOut("Stopped Caplets daemon.\n");
 	});
 	addJsonOption(daemon.command("status").description("Show the default Caplets daemon status.")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const status = await daemonStatus(daemonOptions());
 		if (options.json) {
 			writeOut(`${JSON.stringify(status, null, 2)}\n`);
@@ -15989,6 +16438,7 @@ function createProgram(io = {}) {
 		writeOut(formatDaemonStatus(status));
 	});
 	addJsonOption(daemon.command("logs").description("Show Caplets daemon logs.").option("--follow", "follow appended log lines").option("--tail <lines>", "show the last number of lines").option("--stream <stream>", "log stream: stdout, stderr, or all")).action(async (options) => {
+		printTelemetryNotice("daemon");
 		const tail = options.tail === void 0 ? 10 : parseNonNegativeInteger(options.tail, "--tail");
 		const stream = parseLogStream(options.stream);
 		if (options.follow) {
@@ -16023,8 +16473,10 @@ function createProgram(io = {}) {
 		}
 		for (const entry of result.entries) writeOut(stream === "all" ? `[${entry.stream}] ${entry.line}\n` : `${entry.line}\n`);
 	});
-	program.command(cliCommands$1.attach).description("Start a remote-backed Caplets MCP server.").argument("[url]", "remote Caplets service base URL").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").addOption(new Option("--remote-url <url>", "legacy alias for the remote Caplets service base URL").hideHelp()).option("--workspace <workspace>", "hosted Cloud workspace ID or slug").option("--allow-unauthenticated-http", "allow unauthenticated HTTP serving on non-loopback hosts").option("--trust-proxy", "trust X-Forwarded-* headers from a reverse proxy").option("--json", "print JSON status events").option("--verbose", "print detailed attach diagnostics").option("--once", "validate Project Binding once and exit").option("--project-root <path>", "test-only project root override").action(async (url, options) => {
+	program.command(cliCommands$1.attach).description("Start a remote-backed Caplets MCP server.").argument("[url]", "remote Caplets service base URL").addOption(hiddenOption("--transport <transport>", "server transport: stdio or http")).addOption(hiddenOption("--host <host>", "HTTP bind host")).addOption(hiddenOption("--port <port>", "HTTP bind port")).addOption(hiddenOption("--path <path>", "HTTP service base path")).addOption(new Option("--remote-url <url>", "legacy alias for the remote Caplets service base URL").hideHelp()).option("--workspace <workspace>", "hosted Cloud workspace ID or slug").addOption(hiddenOption("--allow-unauthenticated-http", "allow unauthenticated HTTP serving on non-loopback hosts")).addOption(hiddenOption("--trust-proxy", "trust X-Forwarded-* headers from a reverse proxy")).option("--json", "print JSON status events").option("--verbose", "print detailed attach diagnostics").option("--once", "validate Project Binding once and exit").option("--project-root <path>", "test-only project root override").action(async (url, options) => {
+		printTelemetryNotice("attach");
 		try {
+			rejectAttachHttpServeFlags(options);
 			const remoteUrl = attachRemoteUrlFromArgs(url, options.remoteUrl);
 			const attachOptions = {
 				...options,
@@ -16396,6 +16848,7 @@ function createProgram(io = {}) {
 		writeOut(`Created ${localMutationTargetLabel(target, io)}Caplets config at ${path}\n`);
 	});
 	program.command(cliCommands$1.setup).description("Install or configure an agent integration for Caplets.").argument("[integration]", "integration: codex, claude-code, opencode, pi, or mcp-client").option("--remote", "configure for a remote Caplets server").option("--remote-url <url>", "remote Caplets service base URL").option("--server-url <url>", "remote Caplets service base URL").option("--output <path>", "config path to write for generic MCP setup").option("--dry-run", "print actions without running commands or writing files").option("--yes", "approve Caplet setup commands for the exact current content hash").option("--target <target>", "Caplet setup target: local, remote, or cloud", parseSetupTarget).option("--format <format>", "output format: plain or json", parseSetupFormat).action(async (integration, options) => {
+		printTelemetryNotice("cli");
 		const setupOptions = {
 			...options,
 			env
@@ -16584,6 +17037,7 @@ function createProgram(io = {}) {
 		writeOut(formatCapletList(rows, options.format ?? "plain"));
 	});
 	program.command(cliCommands$1.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("--project", "install to the project Caplets root").option("-g, --global", "install to the user Caplets root").option("--remote", "install through remote control").option("--force", "overwrite installed Caplets").action(async (repo, capletIds, options) => {
+		printTelemetryNotice("cli");
 		const target = parseMutationTarget(options);
 		if (target === "remote") {
 			const result = await requireRemoteClientForTarget(io).request("install", {
@@ -16703,37 +17157,13 @@ function createProgram(io = {}) {
 		writeAddResult(writeOut, `${localMutationTargetLabel(target, io)}HTTP`, result);
 	});
 	program.command(cliCommands$1.inspect).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: "inspect" }, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		await executeOperation(caplet, { operation: "inspect" }, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.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" }, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		await executeOperation(caplet, { operation: "check" }, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.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: "tools" }, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		await executeOperation(caplet, { operation: "tools" }, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.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 ? {
@@ -16743,30 +17173,14 @@ function createProgram(io = {}) {
 			operation: "search_tools",
 			query,
 			limit: options.limit
-		}, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		}, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.getTool).description("Print one downstream tool schema.").argument("<caplet-or-target>", "Caplet ID or qualified <caplet.tool> target").argument("[tool]", "downstream tool name when caplet is provided separately").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (capletOrTarget, toolArgument, options) => {
 		const { caplet, tool } = parseQualifiedTarget(capletOrTarget, toolArgument);
 		await executeOperation(caplet, {
 			operation: "describe_tool",
 			name: tool
-		}, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		}, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.callTool).description("Call one downstream tool.").argument("<caplet-or-target>", "Caplet ID or qualified <caplet.tool> target").argument("[tool]", "downstream tool name when caplet is provided separately").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 (capletOrTarget, toolArgument, options) => {
 		const { caplet, tool } = parseQualifiedTarget(capletOrTarget, toolArgument);
@@ -16775,28 +17189,12 @@ function createProgram(io = {}) {
 			name: tool,
 			args: parseCallToolArgs(options.args),
 			...options.field && options.field.length > 0 ? { fields: options.field } : {}
-		}, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		}, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.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: "resources" } : {
 		operation: "resources",
 		limit: options.limit
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.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
@@ -16804,51 +17202,19 @@ function createProgram(io = {}) {
 		operation: "search_resources",
 		query,
 		limit: options.limit
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.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: "resource_templates" } : {
 		operation: "resource_templates",
 		limit: options.limit
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.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
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.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: "prompts" } : {
 		operation: "prompts",
 		limit: options.limit
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.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
@@ -16856,30 +17222,14 @@ function createProgram(io = {}) {
 		operation: "search_prompts",
 		query,
 		limit: options.limit
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	program.command(cliCommands$1.getPrompt).description("Get one MCP prompt by name.").argument("<caplet-or-target>", "MCP Caplet ID or qualified <caplet.prompt> target").argument("[prompt]", "prompt name when caplet is provided separately").option("--args <json-object>", "JSON object of prompt arguments").option("--format <format>", "output format: markdown, md, plain, or json", parseOutputFormat).action(async (capletOrTarget, promptArgument, options) => {
 		const { caplet, tool: prompt } = parseQualifiedTarget(capletOrTarget, promptArgument);
 		await executeOperation(caplet, {
 			operation: "get_prompt",
 			name: prompt,
 			args: parseJsonObjectOption(options.args, "get-prompt --args")
-		}, {
-			writeOut,
-			writeErr,
-			setExitCode,
-			authDir: io.authDir,
-			env,
-			remote: remoteClientForCli(io),
-			format: options.format
-		});
+		}, executeOperationIo(options.format));
 	});
 	program.command(cliCommands$1.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",
@@ -16888,15 +17238,7 @@ function createProgram(io = {}) {
 			name: options.argument,
 			value: options.value
 		}
-	}, {
-		writeOut,
-		writeErr,
-		setExitCode,
-		authDir: io.authDir,
-		env,
-		remote: remoteClientForCli(io),
-		format: options.format
-	}));
+	}, executeOperationIo(options.format)));
 	const config = program.command(cliCommands$1.config).description("Inspect Caplets config locations.");
 	config.command("path").description("Print the effective user config path.").action(() => {
 		writeOut(`${resolveConfigPath(currentConfigPath())}\n`);
@@ -17487,8 +17829,17 @@ function mergeRemoteAndLocalRows(remoteRows, localOverlay, options) {
 	});
 	if (!localOverlay) return [...rows.values()].filter((row) => options.includeDisabled || !row.disabled).sort((left, right) => left.server.localeCompare(right.server));
 	for (const row of listCaplets(localOverlay, { includeDisabled: true })) {
-		if (rows.get(row.server)) {
+		const remote = rows.get(row.server);
+		if (remote) {
 			if (row.disabled) continue;
+			if (remote.shadowing === "namespace") {
+				options.writeErr(`Local Caplet '${row.server}' is exposed under a qualified ID because the remote Caplet uses namespace shadowing for that Caplet ID.\n`);
+				continue;
+			}
+			if (remote.shadowing !== "allow") {
+				options.writeErr(`Local Caplet '${row.server}' is suppressed because the remote Caplet forbids shadowing that Caplet ID.\n`);
+				continue;
+			}
 			options.writeErr(`Warning: ${formatOverlaySource(row.source)} Caplet ${row.server} shadows remote Caplet\n`);
 		}
 		rows.set(row.server, row);
@@ -17512,6 +17863,12 @@ async function executeLocalOperation(caplet, request, io, config) {
 		...io.authDir ? { authDir: io.authDir } : {},
 		watch: false,
 		writeErr: io.writeErr,
+		telemetryEnv: io.env ?? process.env,
+		telemetryStateDir: io.telemetryStateDir ?? defaultTelemetryStateDir(io.env ?? process.env),
+		telemetrySurface: "cli",
+		telemetryVisibility: "visible",
+		telemetryRuntimeMode: runtimeModeForEnv(io.env ?? process.env),
+		telemetryDebugSink: io.telemetryDebugSink,
 		...config ? { configLoader: () => config } : {}
 	});
 	try {