caplets 0.8.0 → 0.10.0

package/README.md

@@ -11,6 +11,52 @@ or call that backend's underlying tools or operations.
 This keeps the initial MCP tool list small, makes tool selection easier, and avoids
 flattened tool-name collisions across servers.
 
+## Why It Matters
+
+Large MCP setups make agents worse before they make them better. If every downstream
+server exposes every tool up front, the model starts with a noisy flat list, duplicate
+tool names, and a bigger context surface before it knows which capability matters.
+
+Caplets turns that flat tool wall into progressive disclosure: one capability card first,
+then scoped discovery only after the agent chooses the relevant domain.
+
+## Benchmark Results
+
+In Caplets' reproducible coding-agent benchmark, the same three mock MCP servers are
+exposed two ways: direct flat MCP aggregation versus Caplets progressive disclosure.
+
+| Initial Agent Surface     |   Direct Flat MCP |      Caplets |     Reduction |
+| ------------------------- | ----------------: | -----------: | ------------: |
+| Visible tools             |               106 |            3 |   97.2% fewer |
+| Serialized MCP payload    |      32,090 bytes |  8,358 bytes | 74.0% smaller |
+| Approx. context surface   |      8,023 tokens | 2,090 tokens |   5,933 fewer |
+| Top-level name collisions | 3 duplicate names |            0 |    eliminated |
+
+The important part: Caplets does not remove access to the downstream tools. It hides
+them behind scoped discovery operations like `search_tools`, `get_tool`, and `call_tool`,
+so the agent sees less up front while still being able to reach the same capabilities.
+
+A local OpenCode live benchmark also completed the full benchmark matrix successfully:
+
+| Agent                          | Mode            | Tasks Passed |
+| ------------------------------ | --------------- | -----------: |
+| OpenCode `openai/gpt-5.5-fast` | Direct flat MCP |          2/2 |
+| OpenCode `openai/gpt-5.5-fast` | Caplets         |          2/2 |
+
+Live results are intentionally not committed as product claims because they depend on
+local agent CLIs, credentials, models, providers, and agent behavior. The deterministic
+surface benchmark is the reproducible claim.
+
+See [`docs/benchmarks/coding-agent.md`](docs/benchmarks/coding-agent.md) for methodology,
+limitations, and reproduction commands.
+
+```sh
+pnpm benchmark
+pnpm benchmark:check
+pnpm build
+CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5-fast
+```
+
 ## Inspiration
 
 Caplets is a mashup of two ideas that work well separately but leave a gap together:
@@ -28,7 +74,7 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## What It Does
 
-- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from `~/.caplets/config.json`.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from the user config file.
 - Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, or HTTP API.
 - Uses the configured server ID as the generated tool name.
 - Uses the configured `name` and `description` as the capability card shown to agents.
@@ -59,7 +105,7 @@ pnpm build
 
 ## Configure
 
-Create a starter `~/.caplets/config.json`:
+Create a starter user config at `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms or `%APPDATA%\caplets\config.json` on Windows:
 
 ```sh
 caplets init
@@ -143,7 +189,7 @@ you want Caplets to expose:
 }
 ```
 
-The default config path can be overridden with `CAPLETS_CONFIG`:
+The default config path is `${XDG_CONFIG_HOME:-~/.config}/caplets/config.json` on Unix-like platforms and `%APPDATA%\caplets\config.json` on Windows. It can be overridden with `CAPLETS_CONFIG`:
 
 ```sh
 CAPLETS_CONFIG=/path/to/config.json caplets init
@@ -279,11 +325,13 @@ caplets install spiritledsoftware/caplets github linear
 ```
 
 `caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
-It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
-of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
-unless `--force` is passed.
+It installs into your user Caplets root, which is `${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms,
+`%APPDATA%\caplets` on Windows, or the parent directory of `CAPLETS_CONFIG` when that environment variable is set.
+Existing Caplets are not overwritten unless `--force` is passed.
+
+On Unix-like platforms, relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
 
-Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
+Caplets always loads user Caplet files from the user Caplets root. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
 
@@ -511,10 +559,11 @@ For headless terminals:
 caplets auth login <server> --no-open
 ```
 
-OAuth/OIDC tokens are stored under `~/.caplets/auth/<server>.json` with owner-only file
-permissions where the platform supports them. Caplets supports well-known OAuth/OIDC
-discovery and dynamic client registration when advertised. When a token expires, run
-`caplets auth login <server>` again.
+OAuth/OIDC tokens are stored under `${XDG_STATE_HOME:-~/.local/state}/caplets/auth/<server>.json`
+on Unix-like platforms and `%LOCALAPPDATA%\caplets\auth\<server>.json` on Windows.
+Token files use owner-only file permissions where the platform supports them. Caplets supports
+well-known OAuth/OIDC discovery and dynamic client registration when advertised. When a token expires,
+run `caplets auth login <server>` again.
 
 To inspect or remove stored OAuth credentials:
 

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from "node:module";
 import minproc, { stdin, stdout, default as process$1 } from "node:process";
 import { execFileSync } from "node:child_process";
-import minpath, { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import minpath, { basename, dirname, extname, isAbsolute, join, parse, posix, relative, resolve, win32 } from "node:path";
 import { accessSync, chmodSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
@@ -180,7 +180,7 @@ const allowsEval = /* @__PURE__ */ cached(() => {
 		return false;
 	}
 });
-function isPlainObject$5(o) {
+function isPlainObject$6(o) {
 	if (isObject(o) === false) return false;
 	const ctor = o.constructor;
 	if (ctor === void 0) return true;
@@ -191,7 +191,7 @@ function isPlainObject$5(o) {
 	return true;
 }
 function shallowClone(o) {
-	if (isPlainObject$5(o)) return { ...o };
+	if (isPlainObject$6(o)) return { ...o };
 	if (Array.isArray(o)) return [...o];
 	if (o instanceof Map) return new Map(o);
 	if (o instanceof Set) return new Set(o);
@@ -274,7 +274,7 @@ function omit(schema, mask) {
 	}));
 }
 function extend(schema, shape) {
-	if (!isPlainObject$5(shape)) throw new Error("Invalid input to extend: expected a plain object");
+	if (!isPlainObject$6(shape)) throw new Error("Invalid input to extend: expected a plain object");
 	const checks = schema._zod.def.checks;
 	if (checks && checks.length > 0) {
 		const existingShape = schema._zod.def.shape;
@@ -290,7 +290,7 @@ function extend(schema, shape) {
 	} }));
 }
 function safeExtend(schema, shape) {
-	if (!isPlainObject$5(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
+	if (!isPlainObject$6(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
 	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
@@ -1904,7 +1904,7 @@ function mergeValues$1(a, b) {
 		valid: true,
 		data: a
 	};
-	if (isPlainObject$5(a) && isPlainObject$5(b)) {
+	if (isPlainObject$6(a) && isPlainObject$6(b)) {
 		const bKeys = Object.keys(b);
 		const sharedKeys = Object.keys(a).filter((key) => bKeys.indexOf(key) !== -1);
 		const newObj = {
@@ -1980,7 +1980,7 @@ const $ZodRecord = /* @__PURE__ */ $constructor("$ZodRecord", (inst, def) => {
 	$ZodType.init(inst, def);
 	inst._zod.parse = (payload, ctx) => {
 		const input = payload.value;
-		if (!isPlainObject$5(input)) {
+		if (!isPlainObject$6(input)) {
 			payload.issues.push({
 				expected: "record",
 				code: "invalid_type",
@@ -9619,7 +9619,7 @@ const { program, createCommand, createArgument, createOption, CommanderError, In
 })))(), 1)).default;
 //#endregion
 //#region package.json
-var version = "0.8.0";
+var version = "0.10.0";
 //#endregion
 //#region node_modules/.pnpm/pkce-challenge@5.0.1/node_modules/pkce-challenge/dist/index.node.js
 let crypto;
@@ -10658,6 +10658,41 @@ async function registerClient(authorizationServerUrl, { metadata, clientMetadata
 	return OAuthClientInformationFullSchema.parse(await response.json());
 }
 //#endregion
+//#region src/config/paths.ts
+function defaultConfigBaseDir(env = process.env, home = homedir(), platform = process.platform) {
+	if (platform === "win32") return env.APPDATA && win32.isAbsolute(env.APPDATA) ? env.APPDATA : win32.join(home, "AppData", "Roaming");
+	return env.XDG_CONFIG_HOME && posix.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : posix.join(home, ".config");
+}
+function defaultStateBaseDir(env = process.env, home = homedir(), platform = process.platform) {
+	if (platform === "win32") return env.LOCALAPPDATA && win32.isAbsolute(env.LOCALAPPDATA) ? env.LOCALAPPDATA : win32.join(home, "AppData", "Local");
+	return env.XDG_STATE_HOME && posix.isAbsolute(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : posix.join(home, ".local", "state");
+}
+function defaultConfigPath(env = process.env, home = homedir(), platform = process.platform) {
+	return (platform === "win32" ? win32.join : posix.join)(defaultConfigBaseDir(env, home, platform), "caplets", "config.json");
+}
+function defaultAuthDir(env = process.env, home = homedir(), platform = process.platform) {
+	return (platform === "win32" ? win32.join : posix.join)(defaultStateBaseDir(env, home, platform), "caplets", "auth");
+}
+const DEFAULT_CONFIG_PATH = defaultConfigPath();
+const DEFAULT_AUTH_DIR = defaultAuthDir();
+const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
+const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
+function resolveConfigPath(path) {
+	return path ?? DEFAULT_CONFIG_PATH;
+}
+function resolveProjectConfigPath(cwd = process.cwd()) {
+	return join(cwd, PROJECT_CONFIG_FILE);
+}
+function resolveCapletsRoot(configPath = resolveConfigPath()) {
+	return dirname(configPath);
+}
+function resolveProjectCapletsRoot(cwd = process.cwd()) {
+	return join(cwd, ".caplets");
+}
+function isTrustedEnvEnabled(value) {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+//#endregion
 //#region src/errors.ts
 var CapletsError = class extends Error {
 	code;
@@ -10708,11 +10743,12 @@ function errorResult(error, fallback) {
 }
 //#endregion
 //#region src/auth/store.ts
-function authStorePath(server, authDir = join(homedir(), ".caplets", "auth")) {
+function authStorePath(server, authDir = DEFAULT_AUTH_DIR) {
 	if (!server || server.includes("/") || server.includes("\\") || server.includes("..")) throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
 	const authRoot = resolve(authDir);
 	const candidate = resolve(authRoot, `${server}.json`);
-	if (candidate !== authRoot && candidate.startsWith(`${authRoot}${sep}`)) return candidate;
+	const relativePath = relative(authRoot, candidate);
+	if (relativePath && !relativePath.startsWith("..") && !isAbsolute(relativePath)) return candidate;
 	throw new CapletsError("REQUEST_INVALID", `Invalid auth store server name ${server}`);
 }
 function readTokenBundle(server, authDir) {
@@ -10780,11 +10816,13 @@ var FileOAuthProvider = class {
 	verifier = base64url(randomBytes(32));
 	stateValue = base64url(randomBytes(24));
 	clientInfo;
+	clientMetadataUrl;
 	constructor(server, redirectUrl, onRedirect, authDir) {
 		this.server = server;
 		this.redirectUrl = redirectUrl;
 		this.onRedirect = onRedirect;
 		this.authDir = authDir;
+		if ((this.server.auth?.type === "oauth2" || this.server.auth?.type === "oidc") && this.server.auth.clientMetadataUrl) this.clientMetadataUrl = this.server.auth.clientMetadataUrl;
 	}
 	get clientMetadata() {
 		return {
@@ -10884,10 +10922,19 @@ async function runOAuthFlow(server, options = {}) {
 			authorizationCode: completion.code,
 			...scope ? { scope } : {}
 		});
+	} catch (error) {
+		throw normalizeMcpOAuthError(server, error);
 	} finally {
 		await callback.close();
 	}
 }
+function normalizeMcpOAuthError(server, error) {
+	if ((server.auth?.type === "oauth2" || server.auth?.type === "oidc") && !server.auth.clientId && !server.auth.clientMetadataUrl && error instanceof Error && error.message.includes("does not support dynamic client registration")) return new CapletsError("AUTH_FAILED", "OAuth is not available for this server without a host-specific OAuth app or PAT auth", {
+		server: server.server,
+		nextAction: "configure_bearer_auth_or_host_oauth_app"
+	});
+	return error;
+}
 async function runGenericOAuthFlow(target, options = {}) {
 	if (target.auth?.type !== "oauth2" && target.auth?.type !== "oidc") throw new CapletsError("REQUEST_INVALID", `${target.server} is not configured for OAuth`);
 	const authConfig = target.auth;
@@ -11057,6 +11104,11 @@ async function resolveGenericClient(target, authConfig, metadata, redirectUri, a
 		...authConfig.clientSecret ? { clientSecret: authConfig.clientSecret } : {},
 		dynamic: false
 	};
+	if (authConfig.clientMetadataUrl) return {
+		clientId: authConfig.clientMetadataUrl,
+		...authConfig.clientSecret ? { clientSecret: authConfig.clientSecret } : {},
+		dynamic: false
+	};
 	if (!metadata.registration_endpoint) throw new CapletsError("AUTH_FAILED", "OAuth clientId is required without dynamic registration", { server: target.server });
 	const response = await fetchJson(metadata.registration_endpoint, target.requestTimeoutMs, {
 		method: "POST",
@@ -11125,8 +11177,9 @@ function assertAllowedAuthUrl(value, label, allowLoopbackHttp = false) {
 	throw new CapletsError("AUTH_FAILED", `${label} must use https except loopback development URLs`);
 }
 function assertTokenBundleMatchesTarget(bundle, target, authConfig) {
+	const configuredClientId = authConfig.clientId ?? authConfig.clientMetadataUrl;
 	const expectedOrigin = protectedResourceOrigin(target, authConfig);
-	if (bundle.authType !== authConfig.type || expectedOrigin && bundle.protectedResourceOrigin !== expectedOrigin || authConfig.clientId && bundle.clientId !== authConfig.clientId || authConfig.issuer && bundle.issuer !== authConfig.issuer) throw new CapletsError("AUTH_REQUIRED", `OAuth credentials for ${target.server} do not match the configured backend`, {
+	if (bundle.authType !== authConfig.type || expectedOrigin && bundle.protectedResourceOrigin !== expectedOrigin || configuredClientId && bundle.clientId !== configuredClientId || authConfig.issuer && bundle.issuer !== authConfig.issuer) throw new CapletsError("AUTH_REQUIRED", `OAuth credentials for ${target.server} do not match the configured backend`, {
 		server: target.server,
 		backend: target.backend,
 		authType: authConfig.type,
@@ -18762,6 +18815,7 @@ const capletRemoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18775,6 +18829,7 @@ const capletRemoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18799,6 +18854,7 @@ const capletEndpointAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18812,6 +18868,7 @@ const capletEndpointAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().min(1).optional(),
 		authorizationServerMetadataUrl: string().min(1).optional(),
 		openidConfigurationUrl: string().min(1).optional(),
+		clientMetadataUrl: string().min(1).optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -18855,10 +18912,11 @@ const capletMcpServerSchema = object$1({
 		path: ["url"],
 		message: "remote url must use https except loopback development urls"
 	});
-	if (server.auth?.type === "oauth2") for (const field of [
+	if (server.auth?.type === "oauth2" || server.auth?.type === "oidc") for (const field of [
 		"authorizationUrl",
 		"tokenUrl",
 		"issuer",
+		"clientMetadataUrl",
 		"redirectUri"
 	]) {
 		const value = server.auth[field];
@@ -19015,13 +19073,13 @@ function loadCapletFiles(root) {
 	for (const candidate of discoverCapletFiles(root)) {
 		if (servers[candidate.id] || openapiEndpoints[candidate.id] || graphqlEndpoints[candidate.id] || httpApis[candidate.id]) throw new CapletsError("CONFIG_INVALID", `Duplicate Caplet ID ${candidate.id} under ${root}`);
 		const config = readCapletFile(candidate.path);
-		if (isPlainObject$4(config) && config.backend === "openapi") {
+		if (isPlainObject$5(config) && config.backend === "openapi") {
 			const { backend: _backend, ...endpoint } = config;
 			openapiEndpoints[candidate.id] = endpoint;
-		} else if (isPlainObject$4(config) && config.backend === "graphql") {
+		} else if (isPlainObject$5(config) && config.backend === "graphql") {
 			const { backend: _backend, ...endpoint } = config;
 			graphqlEndpoints[candidate.id] = endpoint;
-		} else if (isPlainObject$4(config) && config.backend === "http") {
+		} else if (isPlainObject$5(config) && config.backend === "http") {
 			const { backend: _backend, ...endpoint } = config;
 			httpApis[candidate.id] = endpoint;
 		} else servers[candidate.id] = config;
@@ -19142,7 +19200,7 @@ function parseFrontmatter(text, path) {
 			value: text
 		});
 		matter(file, { strip: true });
-		if (!isPlainObject$4(file.data.matter) || Object.keys(file.data.matter).length === 0) throw new Error("empty frontmatter");
+		if (!isPlainObject$5(file.data.matter) || Object.keys(file.data.matter).length === 0) throw new Error("empty frontmatter");
 		return {
 			frontmatter: file.data.matter,
 			body: String(file)
@@ -19151,7 +19209,7 @@ function parseFrontmatter(text, path) {
 		throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} has invalid YAML frontmatter`, redactSecrets(error));
 	}
 }
-function isPlainObject$4(value) {
+function isPlainObject$5(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function validateCapletId(id, path) {
@@ -19161,27 +19219,6 @@ function hasEnvReference$1(value) {
 	return /\$\{[A-Za-z_][A-Za-z0-9_]*\}|\$env:[A-Za-z_][A-Za-z0-9_]*/.test(value);
 }
 //#endregion
-//#region src/config/paths.ts
-const DEFAULT_CONFIG_PATH = join(homedir(), ".caplets", "config.json");
-const DEFAULT_AUTH_DIR = join(homedir(), ".caplets", "auth");
-const PROJECT_CONFIG_FILE = join(".caplets", "config.json");
-const TRUST_PROJECT_CAPLETS_ENV = "CAPLETS_TRUST_PROJECT_CAPLETS";
-function resolveConfigPath(path) {
-	return path ?? DEFAULT_CONFIG_PATH;
-}
-function resolveProjectConfigPath(cwd = process.cwd()) {
-	return join(cwd, PROJECT_CONFIG_FILE);
-}
-function resolveCapletsRoot(configPath = resolveConfigPath()) {
-	return dirname(configPath);
-}
-function resolveProjectCapletsRoot(cwd = process.cwd()) {
-	return join(cwd, ".caplets");
-}
-function isTrustedEnvEnabled(value) {
-	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
-}
-//#endregion
 //#region src/config.ts
 const NON_INTERPOLATED_SERVER_FIELDS = new Set([
 	"name",
@@ -19207,6 +19244,7 @@ const remoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().url().optional(),
 		authorizationServerMetadataUrl: string().url().optional(),
 		openidConfigurationUrl: string().url().optional(),
+		clientMetadataUrl: string().url().optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -19220,6 +19258,7 @@ const remoteAuthSchema = discriminatedUnion("type", [
 		resourceMetadataUrl: string().url().optional(),
 		authorizationServerMetadataUrl: string().url().optional(),
 		openidConfigurationUrl: string().url().optional(),
+		clientMetadataUrl: string().url().optional(),
 		clientId: string().min(1).optional(),
 		clientSecret: string().min(1).optional(),
 		scopes: array(string().min(1)).optional(),
@@ -19234,6 +19273,7 @@ const oauthLikeAuthSchema = union([object$1({
 	resourceMetadataUrl: string().url().optional(),
 	authorizationServerMetadataUrl: string().url().optional(),
 	openidConfigurationUrl: string().url().optional(),
+	clientMetadataUrl: string().url().optional(),
 	clientId: string().min(1).optional(),
 	clientSecret: string().min(1).optional(),
 	scopes: array(string().min(1)).optional(),
@@ -19246,6 +19286,7 @@ const oauthLikeAuthSchema = union([object$1({
 	resourceMetadataUrl: string().url().optional(),
 	authorizationServerMetadataUrl: string().url().optional(),
 	openidConfigurationUrl: string().url().optional(),
+	clientMetadataUrl: string().url().optional(),
 	clientId: string().min(1).optional(),
 	clientSecret: string().min(1).optional(),
 	scopes: array(string().min(1)).optional(),
@@ -19345,6 +19386,7 @@ const httpActionSchema = object$1({
 	path: string().min(1).regex(/^\//, "HTTP action path must start with /").describe("URL path appended to the HTTP API baseUrl.").refine((value) => !value.startsWith("//"), "HTTP action path must not start with //").refine((value) => !isUrl(value), "HTTP action path must be a URL path, not a URL"),
 	description: string().min(1).optional().describe("Action capability description."),
 	inputSchema: record(string(), unknown()).optional().describe("JSON Schema for call_tool arguments."),
+	outputSchema: record(string(), unknown()).optional().describe("JSON Schema for structuredContent returned by this action."),
 	query: httpScalarMappingSchema.optional().describe("Query parameter mapping."),
 	headers: httpScalarMappingSchema.optional().describe("Request header mapping."),
 	jsonBody: unknown().optional().describe("JSON request body mapping.")
@@ -19609,7 +19651,7 @@ function normalizeLocalPaths(input, baseDir) {
 }
 function normalizeEndpointPaths(endpoints, baseDir, normalize) {
 	if (!endpoints) return;
-	return Object.fromEntries(Object.entries(endpoints).map(([id, endpoint]) => [id, isPlainObject$3(endpoint) ? normalize(endpoint, baseDir) : endpoint]));
+	return Object.fromEntries(Object.entries(endpoints).map(([id, endpoint]) => [id, isPlainObject$4(endpoint) ? normalize(endpoint, baseDir) : endpoint]));
 }
 function normalizeOpenApiPath(endpoint, baseDir) {
 	return {
@@ -19618,7 +19660,7 @@ function normalizeOpenApiPath(endpoint, baseDir) {
 	};
 }
 function normalizeGraphQlPath(endpoint, baseDir) {
-	const operations = isPlainObject$3(endpoint.operations) ? Object.fromEntries(Object.entries(endpoint.operations).map(([name, operation]) => [name, isPlainObject$3(operation) ? {
+	const operations = isPlainObject$4(endpoint.operations) ? Object.fromEntries(Object.entries(endpoint.operations).map(([name, operation]) => [name, isPlainObject$4(operation) ? {
 		...operation,
 		documentPath: normalizeLocalPath(operation.documentPath, baseDir)
 	} : operation])) : endpoint.operations;
@@ -19737,7 +19779,7 @@ function isPublicMetadataPath(path) {
 	if (path.length < 3 || path[0] !== "mcpServers" && path[0] !== "openapiEndpoints" && path[0] !== "graphqlEndpoints" && path[0] !== "httpApis") return false;
 	return NON_INTERPOLATED_SERVER_FIELDS.has(path[2] ?? "");
 }
-function isPlainObject$3(value) {
+function isPlainObject$4(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function hasEnvReference(value) {
@@ -19896,12 +19938,14 @@ function formatCapletList(rows) {
 }
 function resolveCliConfigPaths(envConfigPath, authDir) {
 	const configPath = resolveConfigPath(envConfigPath);
+	const effectiveAuthDir = authDir ?? DEFAULT_AUTH_DIR;
 	return {
 		userConfig: configPath,
 		projectConfig: resolveProjectConfigPath(),
 		userRoot: resolveCapletsRoot(configPath),
+		stateRoot: dirname(effectiveAuthDir),
 		projectRoot: resolveProjectCapletsRoot(),
-		authDir: authDir ?? DEFAULT_AUTH_DIR,
+		authDir: effectiveAuthDir,
 		envConfig: envConfigPath ?? null,
 		projectCapletsTrusted: isTrustedProjectCapletsEnabled()
 	};
@@ -19911,6 +19955,7 @@ function formatConfigPaths(paths) {
 		`userConfig: ${paths.userConfig}`,
 		`projectConfig: ${paths.projectConfig}`,
 		`userRoot: ${paths.userRoot}`,
+		`stateRoot: ${paths.stateRoot}`,
 		`projectRoot: ${paths.projectRoot}`,
 		`authDir: ${paths.authDir}`,
 		`envConfig: ${paths.envConfig ?? "unset"}`,
@@ -25820,7 +25865,7 @@ var Protocol = class {
 		};
 	}
 };
-function isPlainObject$2(value) {
+function isPlainObject$3(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function mergeCapabilities(base, additional) {
@@ -25830,7 +25875,7 @@ function mergeCapabilities(base, additional) {
 		const addValue = additional[k];
 		if (addValue === void 0) continue;
 		const baseValue = result[k];
-		if (isPlainObject$2(baseValue) && isPlainObject$2(addValue)) result[k] = {
+		if (isPlainObject$3(baseValue) && isPlainObject$3(addValue)) result[k] = {
 			...baseValue,
 			...addValue
 		};
@@ -35726,7 +35771,8 @@ var DownstreamManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(server, tools, query, limit) {
@@ -50705,7 +50751,8 @@ var GraphQLManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(endpoint, tools, query, limit) {
@@ -51103,7 +51150,8 @@ var HttpActionManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(api, tools, query, limit) {
@@ -51115,6 +51163,7 @@ var HttpActionManager = class {
 			name: operation.name,
 			...operation.description ? { description: operation.description } : {},
 			inputSchema: operation.inputSchema ?? DEFAULT_INPUT_SCHEMA,
+			...operation.outputSchema ? { outputSchema: operation.outputSchema } : {},
 			annotations: {
 				readOnlyHint: operation.method === "GET",
 				destructiveHint: operation.method === "DELETE"
@@ -51186,7 +51235,7 @@ function resolveMapping(mapping, input) {
 function resolveMappingToRecord(mapping, input, name) {
 	if (mapping === void 0) return {};
 	const resolved = resolveMapping(mapping, input);
-	if (!isPlainObject$1(resolved)) throw new CapletsError("REQUEST_INVALID", `HTTP action ${name} mapping must resolve to an object`);
+	if (!isPlainObject$2(resolved)) throw new CapletsError("REQUEST_INVALID", `HTTP action ${name} mapping must resolve to an object`);
 	return resolved;
 }
 function valueAtPath(input, path) {
@@ -51281,9 +51330,9 @@ function buildActionUrl(base, actionPath, options = {}) {
 	return baseUrl;
 }
 function asRecord$1(value) {
-	return isPlainObject$1(value) ? value : {};
+	return isPlainObject$2(value) ? value : {};
 }
-function isPlainObject$1(value) {
+function isPlainObject$2(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
@@ -60897,7 +60946,8 @@ var OpenApiManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(endpoint, tools, query, limit) {
@@ -60940,6 +60990,7 @@ var OpenApiManager = class {
 			name: operation.name,
 			...operation.summary || operation.description ? { description: operation.summary ?? operation.description } : {},
 			inputSchema: operation.inputSchema,
+			...operation.outputSchema ? { outputSchema: operation.outputSchema } : {},
 			annotations: {
 				readOnlyHint: operation.method === "get" || operation.method === "head",
 				destructiveHint: operation.method === "delete"
@@ -60975,6 +61026,7 @@ function extractOperations(endpoint, document) {
 			seen.add(name);
 			const parameters = [...inheritedParameters, ...Array.isArray(operation.parameters) ? operation.parameters : []];
 			const requestBody = requestBodyFor(operation);
+			const outputSchema = outputSchemaFor(operation);
 			const baseUrl = endpoint.baseUrl ?? firstServerUrl(document);
 			validateOperationBaseUrl(endpoint, baseUrl);
 			operations.push({
@@ -60984,6 +61036,7 @@ function extractOperations(endpoint, document) {
 				...typeof operation.summary === "string" ? { summary: operation.summary } : {},
 				...typeof operation.description === "string" ? { description: operation.description } : {},
 				inputSchema: inputSchemaFor(parameters, requestBody),
+				...outputSchema ? { outputSchema } : {},
 				...requestBody?.contentType ? { requestBodyContentType: requestBody.contentType } : {},
 				...baseUrl ? { baseUrl } : {}
 			});
@@ -61004,6 +61057,53 @@ function requestBodyFor(operation) {
 		contentType
 	};
 }
+function outputSchemaFor(operation) {
+	const responses = operation.responses;
+	if (!responses || typeof responses !== "object") return;
+	const schemas = [];
+	for (const [status, response] of Object.entries(responses)) {
+		if (!/^2\d\d$/.test(status) || !response || typeof response !== "object") continue;
+		const content = response.content;
+		if (!content || typeof content !== "object") continue;
+		const contentType = JSON_CONTENT_TYPES.find((candidate) => content[candidate]);
+		if (!contentType) continue;
+		const schema = actualSchema(content[contentType]?.schema);
+		if (!schema) continue;
+		schemas.push(schema);
+	}
+	if (schemas.length === 0) return;
+	const firstSchema = schemas[0];
+	if (schemas.slice(1).some((schema) => JSON.stringify(schema) !== JSON.stringify(firstSchema))) return;
+	return structuredOutputSchema(firstSchema);
+}
+function actualSchema(value) {
+	rejectExternalRefs(value);
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const schema = value;
+	return typeof schema.$ref === "string" ? void 0 : schema;
+}
+function structuredOutputSchema(bodySchema) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"status",
+			"statusText",
+			"headers"
+		],
+		properties: {
+			status: { type: "number" },
+			statusText: { type: "string" },
+			headers: {
+				type: "object",
+				additionalProperties: false,
+				required: ["content-type"],
+				properties: { "content-type": { type: "string" } }
+			},
+			body: bodySchema
+		}
+	};
+}
 function inputSchemaFor(parameters, requestBody) {
 	const schema = {
 		type: "object",
@@ -61163,6 +61263,26 @@ function openApiCacheKey(endpoint) {
 	});
 }
 //#endregion
+//#region src/capability-description.mjs
+function capabilityDescription(server) {
+	const backendName = server.backend === "mcp" ? "MCP server" : server.backend === "openapi" ? "OpenAPI endpoint" : server.backend === "graphql" ? "GraphQL endpoint" : "HTTP API";
+	const checkOperation = server.backend === "mcp" ? "check_mcp_server" : "check_backend";
+	const hint = [
+		`Use this Caplet to inspect and call tools from its ${backendName} backend.`,
+		"",
+		"Recommended flow:",
+		"- Read the full Caplet card: {\"operation\":\"get_caplet\"}",
+		`- Check the backend: {"operation":"${checkOperation}"}`,
+		"- Discover tools: {\"operation\":\"list_tools\"} or {\"operation\":\"search_tools\",\"query\":\"<what you need>\"}",
+		"- Read one tool schema: {\"operation\":\"get_tool\",\"tool\":\"<tool name>\"}",
+		"- Invoke one downstream tool: {\"operation\":\"call_tool\",\"tool\":\"<tool name>\",\"arguments\":{...}}",
+		"",
+		"Important: Do not put downstream arguments at the top level; put them inside \"arguments\".",
+		"After get_tool shows outputSchema (non-GraphQL), call_tool may use fields: [\"path.to.field\"]."
+	].join("\n");
+	return `${server.name}\n\n${server.description}\n\n${hint}`;
+}
+//#endregion
 //#region src/registry.ts
 var ServerRegistry = class {
 	config;
@@ -61230,23 +61350,6 @@ var ServerRegistry = class {
 		];
 	}
 };
-function capabilityDescription(server) {
-	const backendName = server.backend === "mcp" ? "MCP server" : server.backend === "openapi" ? "OpenAPI endpoint" : server.backend === "graphql" ? "GraphQL endpoint" : "HTTP API";
-	const checkOperation = server.backend === "mcp" ? "check_mcp_server" : "check_backend";
-	const hint = [
-		`Use this Caplet to inspect and call tools from its ${backendName} backend.`,
-		"",
-		"Recommended flow:",
-		"- Read the full Caplet card: {\"operation\":\"get_caplet\"}",
-		`- Check the backend: {"operation":"${checkOperation}"}`,
-		"- Discover tools: {\"operation\":\"list_tools\"} or {\"operation\":\"search_tools\",\"query\":\"<what you need>\"}",
-		"- Read one tool schema: {\"operation\":\"get_tool\",\"tool\":\"<tool name>\"}",
-		"- Invoke one downstream tool: {\"operation\":\"call_tool\",\"tool\":\"<tool name>\",\"arguments\":{...}}",
-		"",
-		"Important: call_tool requires a top-level \"arguments\" JSON object containing the downstream tool inputs. Do not put downstream arguments at the top level of this wrapper request."
-	].join("\n");
-	return `${server.name}\n\n${server.description}\n\n${hint}`;
-}
 function backendDetail(server) {
 	if (server.backend === "openapi") return {
 		type: "openapi",
@@ -61284,7 +61387,110 @@ function graphQlSource(server) {
 	return "introspection";
 }
 //#endregion
-//#region src/tools.ts
+//#region src/field-selection.ts
+function projectStructuredContent(value, outputSchema, fields) {
+	validateFieldSelection(outputSchema, fields);
+	if (!isPlainObject$1(value)) throwInvalid("Field selection requires object structured content");
+	const result = createJsonObject();
+	for (const field of fields) {
+		const projected = projectPath(value, outputSchema, field.split("."));
+		if (projected !== void 0) mergeValue(result, projected);
+	}
+	return result;
+}
+function validateFieldSelection(outputSchema, fields) {
+	if (!isPlainObject$1(outputSchema)) throwInvalid("Field selection requires an output schema");
+	if (!Array.isArray(fields) || fields.some((field) => typeof field !== "string")) throwInvalid("Field selection requires an array of field paths");
+	for (const field of fields) validateSchemaPath(outputSchema, field.split("."), field);
+}
+function validateSchemaPath(schema, path, field) {
+	let current = schema;
+	for (const segment of path) {
+		if (!isSupportedSegment(segment)) throwInvalid(`Unsupported field selection path: ${field}`);
+		if (current?.type === "array") current = Array.isArray(current.items) ? void 0 : current.items;
+		current = getOwnSchemaProperty(current?.properties, segment);
+		if (!current) throwInvalid(`Field is not allowed by output schema: ${field}`);
+	}
+}
+function getOwnSchemaProperty(properties, segment) {
+	if (!properties || !Object.prototype.hasOwnProperty.call(properties, segment)) return;
+	return properties[segment];
+}
+function projectPath(value, schema, path) {
+	if (path.length === 0) return pruneToSchema(value, schema);
+	if (Array.isArray(value)) {
+		const itemSchema = arrayItemSchema(schema);
+		return value.map((item) => projectPath(item, itemSchema, path) ?? {});
+	}
+	const segment = path[0];
+	if (!isPlainObject$1(value) || !Object.prototype.hasOwnProperty.call(value, segment)) return;
+	const rest = path.slice(1);
+	const propertySchema = getSchemaProperty(schema, segment);
+	const projected = projectPath(value[segment], propertySchema, rest);
+	if (projected === void 0) return;
+	return { [segment]: projected };
+}
+function pruneToSchema(value, schema) {
+	if (Array.isArray(value)) {
+		const itemSchema = arrayItemSchema(schema);
+		return value.map((item) => pruneToSchema(item, itemSchema));
+	}
+	if (!isPlainObject$1(value)) return cloneJsonValue(value);
+	const properties = isPlainObject$1(schema) ? schema.properties : void 0;
+	if (!isPlainObject$1(properties)) return cloneJsonValue(value);
+	const result = createJsonObject();
+	for (const [key, nestedSchema] of Object.entries(properties)) if (isSupportedSegment(key) && Object.prototype.hasOwnProperty.call(value, key)) result[key] = pruneToSchema(value[key], nestedSchema);
+	return result;
+}
+function getSchemaProperty(schema, segment) {
+	const properties = isPlainObject$1(schema) ? schema.properties : void 0;
+	if (!properties || !Object.prototype.hasOwnProperty.call(properties, segment)) return;
+	return properties[segment];
+}
+function arrayItemSchema(schema) {
+	if (!isPlainObject$1(schema) || Array.isArray(schema.items)) return;
+	return schema.items;
+}
+function mergeValue(target, value) {
+	if (!isPlainObject$1(value)) return;
+	for (const [key, nested] of Object.entries(value)) {
+		if (!isSupportedSegment(key)) continue;
+		target[key] = mergeNested(target[key], nested);
+	}
+}
+function mergeNested(existing, next) {
+	if (next === void 0) return existing;
+	if (Array.isArray(existing) && Array.isArray(next)) return Array.from({ length: Math.max(existing.length, next.length) }, (_, index) => mergeNested(existing[index], next[index]));
+	if (isPlainObject$1(existing) && isPlainObject$1(next)) {
+		const merged = Object.assign(createJsonObject(), existing);
+		mergeValue(merged, next);
+		return merged;
+	}
+	return next;
+}
+function isSupportedSegment(segment) {
+	return segment !== "" && segment !== "*" && segment !== "__proto__" && segment !== "prototype" && segment !== "constructor" && !/^\d+$/.test(segment);
+}
+function isPlainObject$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function createJsonObject() {
+	return Object.create(null);
+}
+function cloneJsonValue(value) {
+	if (Array.isArray(value)) return value.map(cloneJsonValue);
+	if (isPlainObject$1(value)) {
+		const result = createJsonObject();
+		for (const [key, nested] of Object.entries(value)) if (isSupportedSegment(key)) result[key] = cloneJsonValue(nested);
+		return result;
+	}
+	return value;
+}
+function throwInvalid(message) {
+	throw new CapletsError("REQUEST_INVALID", message);
+}
+//#endregion
+//#region src/generated-tool-input-schema.mjs
 const operations = [
 	"get_caplet",
 	"check_backend",
@@ -61294,16 +61500,25 @@ const operations = [
 	"get_tool",
 	"call_tool"
 ];
-const generatedToolInputSchema = object$1({
-	operation: _enum(operations).describe([
+const generatedToolInputDescriptions = {
+	operation: [
 		"Caplets wrapper operation to perform for this configured Caplet backend.",
 		"Use get_caplet to read the full Caplet card, check_backend to check any backend, check_mcp_server to check an MCP backend, list_tools or search_tools to discover downstream tools, get_tool to read a downstream input schema, and call_tool to run one downstream tool or OpenAPI operation.",
 		"For call_tool, pass downstream inputs only inside the top-level \"arguments\" object."
-	].join(" ")),
-	query: string().optional().describe("Required only for search_tools. Example: {\"operation\":\"search_tools\",\"query\":\"web search\",\"limit\":5}. Do not use query for call_tool; put downstream query values under arguments.query."),
-	limit: number$1().int().positive().optional().describe("Optional only for search_tools; defaults to the configured search limit. For downstream result limits, use call_tool.arguments with the downstream schema field name."),
-	tool: string().optional().describe("Exact downstream tool name for get_tool or call_tool. Example: {\"operation\":\"get_tool\",\"tool\":\"web_search_exa\"} before calling it."),
-	arguments: record(string(), unknown()).optional().describe("Required JSON object only for call_tool. Put every downstream tool input inside this object. Example: {\"operation\":\"call_tool\",\"tool\":\"web_search_exa\",\"arguments\":{\"query\":\"latest MCP docs\",\"numResults\":3}}. Do not send downstream inputs as top-level query, limit, url, path, or other fields.")
+	].join(" "),
+	query: "Required only for search_tools. Example: {\"operation\":\"search_tools\",\"query\":\"web search\",\"limit\":5}. Do not use query for call_tool; put downstream query values under arguments.query.",
+	limit: "Optional only for search_tools; defaults to the configured search limit. For downstream result limits, use call_tool.arguments with the downstream schema field name.",
+	tool: "Exact downstream tool name for get_tool or call_tool. Example: {\"operation\":\"get_tool\",\"tool\":\"web_search_exa\"} before calling it.",
+	arguments: "Required JSON object only for call_tool. Put every downstream tool input inside this object. Example: {\"operation\":\"call_tool\",\"tool\":\"web_search_exa\",\"arguments\":{\"query\":\"latest MCP docs\",\"numResults\":3}}. Do not send downstream inputs as top-level query, limit, url, path, or other fields.",
+	fields: "Optional for call_tool after get_tool shows outputSchema on a non-GraphQL tool. Example: fields: [\"path.to.field\"]."
+};
+const generatedToolInputSchema = object$1({
+	operation: _enum(operations).describe(generatedToolInputDescriptions.operation),
+	query: string().optional().describe(generatedToolInputDescriptions.query),
+	limit: number$1().int().positive().optional().describe(generatedToolInputDescriptions.limit),
+	tool: string().optional().describe(generatedToolInputDescriptions.tool),
+	arguments: record(string(), unknown()).optional().describe(generatedToolInputDescriptions.arguments),
+	fields: array(string().min(1)).min(1).optional().describe(generatedToolInputDescriptions.fields)
 }).strict();
 async function handleServerTool(server, request, registry, downstream, openapi, graphql, http) {
 	const parsed = validateOperationRequest(request, registry.config.options.maxSearchLimit);
@@ -61338,7 +61553,15 @@ async function handleServerTool(server, request, registry, downstream, openapi,
 				tool
 			});
 		}
-		case "call_tool": return backendFor(server, downstream, openapi, graphql, http).callTool(server, parsed.tool, parsed.arguments);
+		case "call_tool": {
+			const backend = backendFor(server, downstream, openapi, graphql, http);
+			if (parsed.fields === void 0) return backend.callTool(server, parsed.tool, parsed.arguments);
+			if (server.backend === "graphql") throw new CapletsError("REQUEST_INVALID", "call_tool.fields is not supported for GraphQL-backed Caplets; select fields in the GraphQL operation document instead");
+			const tool = await backend.getTool(server, parsed.tool);
+			if (!tool.outputSchema) throw new CapletsError("REQUEST_INVALID", "Field selection requires an output schema");
+			validateFieldSelection(tool.outputSchema, parsed.fields);
+			return projectCallToolResult(await backend.callTool(server, parsed.tool, parsed.arguments), tool.outputSchema, parsed.fields);
+		}
 	}
 }
 function validateOperationRequest(request, maxSearchLimit) {
@@ -61379,13 +61602,22 @@ function validateOperationRequest(request, maxSearchLimit) {
 				tool: value.tool
 			};
 		case "call_tool":
-			allowed(["tool", "arguments"]);
+			allowed([
+				"tool",
+				"arguments",
+				"fields"
+			]);
 			if (!value.tool) throw new CapletsError("REQUEST_INVALID", "call_tool requires tool");
 			if (!isPlainObject(value.arguments)) throw new CapletsError("REQUEST_INVALID", "call_tool.arguments must be a JSON object");
-			return {
+			return value.fields === void 0 ? {
 				operation: "call_tool",
 				tool: value.tool,
 				arguments: value.arguments
+			} : {
+				operation: "call_tool",
+				tool: value.tool,
+				arguments: value.arguments,
+				fields: value.fields
 			};
 	}
 }
@@ -61398,6 +61630,20 @@ function jsonResult(value) {
 		structuredContent: { result: value }
 	};
 }
+function projectCallToolResult(result, outputSchema, fields) {
+	if (result.isError === true) return result;
+	const structuredContent = result.structuredContent;
+	if (!isPlainObject(structuredContent)) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "Field selection requires the downstream tool to return object structuredContent");
+	const projected = projectStructuredContent(structuredContent, outputSchema, fields);
+	return {
+		...result,
+		content: [{
+			type: "text",
+			text: JSON.stringify(projected, null, 2)
+		}],
+		structuredContent: projected
+	};
+}
 function isPlainObject(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplets",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Progressive disclosure gateway for MCP servers.",
   "keywords": [
     "caplets",
@@ -67,6 +67,11 @@
   "scripts": {
     "build": "rolldown -c",
     "build:watch": "rolldown -c --watch",
+    "benchmark": "node benchmarks/run-deterministic.mjs",
+    "benchmark:check": "node benchmarks/run-deterministic.mjs --check",
+    "benchmark:live": "node benchmarks/run-live.mjs",
+    "benchmark:live:opencode": "node benchmarks/run-live.mjs --agent opencode",
+    "benchmark:live:pi": "node benchmarks/run-live.mjs --agent pi",
     "changeset": "changeset",
     "dev": "node ./scripts/dev.mjs",
     "format": "oxfmt .",
@@ -78,7 +83,7 @@
     "schema:generate": "rolldown -c rolldown.schema.config.ts && node dist-schema/generate-config-schema.js && rm -rf dist-schema",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm build",
+    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm benchmark:check && pnpm build",
     "version-packages": "changeset version"
   }
 }

package/schemas/caplet.schema.json

@@ -149,6 +149,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -203,6 +207,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -353,6 +361,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -407,6 +419,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -591,6 +607,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -645,6 +665,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -788,6 +812,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1
@@ -842,6 +870,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "clientMetadataUrl": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "clientId": {
                   "type": "string",
                   "minLength": 1

package/schemas/caplets-config.schema.json

@@ -168,6 +168,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -222,6 +226,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -403,6 +411,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -457,6 +469,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -670,6 +686,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -724,6 +744,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -896,6 +920,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -950,6 +978,10 @@
                     "type": "string",
                     "format": "uri"
                   },
+                  "clientMetadataUrl": {
+                    "type": "string",
+                    "format": "uri"
+                  },
                   "clientId": {
                     "type": "string",
                     "minLength": 1
@@ -1009,6 +1041,14 @@
                   },
                   "additionalProperties": {}
                 },
+                "outputSchema": {
+                  "description": "JSON Schema for structuredContent returned by this action.",
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {}
+                },
                 "query": {
                   "description": "Query parameter mapping.",
                   "type": "object",