@caplets/core 0.19.0 → 0.20.0

package/dist/observed-output-shapes-uzAMQPhg.js

@@ -0,0 +1,485 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+//#region src/observed-output-shapes/types.ts
+const OBSERVED_OUTPUT_SHAPE_VERSION = 1;
+const OBSERVED_OUTPUT_SHAPE_LIMITS = {
+	maxDepth: 6,
+	maxObjectFields: 40,
+	maxArrayElements: 20,
+	maxUnionVariants: 4,
+	maxTypeScriptChars: 4e3,
+	maxStoredJsonBytes: 16e3,
+	ttlMs: 720 * 60 * 60 * 1e3,
+	maxLocalEntries: 2e3
+};
+//#endregion
+//#region src/stable-json.ts
+function stableJsonValue(value) {
+	if (Array.isArray(value)) return value.map((item) => stableJsonValue(item));
+	if (isPlainObject$2(value)) {
+		const sorted = {};
+		for (const key of Object.keys(value).sort()) {
+			const item = value[key];
+			if (item !== void 0) sorted[key] = stableJsonValue(item);
+		}
+		return sorted;
+	}
+	return value;
+}
+function stableJsonStringify(value) {
+	return JSON.stringify(stableJsonValue(value));
+}
+function isPlainObject$2(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/schema-hash.ts
+function schemaHash(schema) {
+	if (schema === void 0 || schema === null) return null;
+	const json = stableJsonStringify(schema);
+	return `sha256:${createHash("sha256").update(json).digest("hex")}`;
+}
+//#endregion
+//#region src/observed-output-shapes/key.ts
+function observedOutputShapeStorageKey(key) {
+	return stableHash(key);
+}
+function observedOutputShapeKey(input) {
+	const toolDescriptorHash = input.toolDescriptor ? stableHash(input.toolDescriptor) : void 0;
+	const outputSchemaHash = schemaHash(input.outputSchema) ?? void 0;
+	return {
+		scope: input.scope,
+		...input.workspaceId ? { workspaceId: input.workspaceId } : {},
+		...input.projectFingerprint ? { projectFingerprint: input.projectFingerprint } : {},
+		capletId: input.caplet.server,
+		backendKind: input.caplet.backend,
+		backendFingerprint: backendFingerprint(input.caplet),
+		toolName: input.toolName,
+		...toolDescriptorHash ? { toolDescriptorHash } : {},
+		...outputSchemaHash ? { outputSchemaHash } : {},
+		resultVersion: 1
+	};
+}
+function backendFingerprint(caplet) {
+	return stableHash(nonSecretBackendIdentity(caplet));
+}
+function stableHash(value) {
+	return createHash("sha256").update(stableJsonStringify(value)).digest("hex");
+}
+function nonSecretBackendIdentity(caplet) {
+	switch (caplet.backend) {
+		case "mcp": return caplet.transport === "stdio" ? {
+			backend: caplet.backend,
+			server: caplet.server,
+			transport: caplet.transport,
+			command: caplet.command,
+			args: caplet.args,
+			cwd: caplet.cwd
+		} : {
+			backend: caplet.backend,
+			server: caplet.server,
+			transport: caplet.transport,
+			url: caplet.url
+		};
+		case "openapi": return {
+			backend: caplet.backend,
+			server: caplet.server,
+			specPath: caplet.specPath,
+			specUrl: caplet.specUrl,
+			baseUrl: caplet.baseUrl
+		};
+		case "graphql": return {
+			backend: caplet.backend,
+			server: caplet.server,
+			endpointUrl: caplet.endpointUrl,
+			schemaPath: caplet.schemaPath,
+			schemaUrl: caplet.schemaUrl,
+			introspection: caplet.introspection,
+			operations: caplet.operations
+		};
+		case "http": return {
+			backend: caplet.backend,
+			server: caplet.server,
+			baseUrl: caplet.baseUrl,
+			actions: Object.fromEntries(Object.entries(caplet.actions).map(([name, action]) => [name, {
+				method: action.method,
+				path: action.path,
+				query: action.query,
+				hasJsonBody: action.jsonBody !== void 0
+			}]))
+		};
+		case "cli": return {
+			backend: caplet.backend,
+			server: caplet.server,
+			cwd: caplet.cwd,
+			actions: Object.fromEntries(Object.entries(caplet.actions).map(([name, action]) => [name, {
+				command: action.command,
+				args: action.args,
+				cwd: action.cwd,
+				output: action.output
+			}]))
+		};
+		case "caplets": return {
+			backend: caplet.backend,
+			server: caplet.server,
+			configPath: caplet.configPath,
+			capletsRoot: caplet.capletsRoot
+		};
+	}
+}
+//#endregion
+//#region src/observed-output-shapes/file-store.ts
+var FileObservedOutputShapeStore = class {
+	cacheDir;
+	options;
+	constructor(cacheDir, options = {}) {
+		this.cacheDir = cacheDir;
+		this.options = options;
+	}
+	async read(key) {
+		try {
+			const parsed = JSON.parse(readFileSync(this.pathFor(key), "utf8"));
+			if (Date.now() > Date.parse(parsed.expiresAt)) return void 0;
+			if (!isObservedOutputShape(parsed.shape)) return void 0;
+			return parsed.shape;
+		} catch {
+			return;
+		}
+	}
+	async write(key, shape) {
+		const payload = {
+			key,
+			shape,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			expiresAt: new Date(Date.now() + this.ttlMs()).toISOString()
+		};
+		if (new TextEncoder().encode(JSON.stringify(payload)).byteLength > OBSERVED_OUTPUT_SHAPE_LIMITS.maxStoredJsonBytes) return;
+		mkdirSync(this.cacheDir, { recursive: true });
+		const path = this.pathFor(key);
+		const tempPath = `${path}.${process.pid}.tmp`;
+		writeFileSync(tempPath, JSON.stringify(payload), { mode: 384 });
+		renameSync(tempPath, path);
+		this.prune().catch(() => void 0);
+	}
+	async prune(now = /* @__PURE__ */ new Date()) {
+		if (!existsSync(this.cacheDir)) return {
+			removed: 0,
+			remaining: 0
+		};
+		const files = this.entries();
+		let removed = 0;
+		const live = [];
+		for (const file of files) try {
+			const parsed = JSON.parse(readFileSync(file.path, "utf8"));
+			const expiresAt = Date.parse(parsed.expiresAt);
+			if (!Number.isFinite(expiresAt) || now.getTime() > expiresAt || !isObservedOutputShape(parsed.shape)) {
+				rmSync(file.path, { force: true });
+				removed++;
+				continue;
+			}
+			live.push({
+				path: file.path,
+				expiresAt,
+				mtimeMs: file.mtimeMs
+			});
+		} catch {
+			rmSync(file.path, { force: true });
+			removed++;
+		}
+		const maxEntries = this.maxEntries();
+		const overflow = Math.max(0, live.length - maxEntries);
+		if (overflow > 0) for (const entry of live.sort((a, b) => a.mtimeMs - b.mtimeMs).slice(0, overflow)) {
+			rmSync(entry.path, { force: true });
+			removed++;
+		}
+		return {
+			removed,
+			remaining: Math.max(0, live.length - overflow)
+		};
+	}
+	async health() {
+		try {
+			mkdirSync(this.cacheDir, { recursive: true });
+			const probe = join(this.cacheDir, `.health-${process.pid}.json`);
+			writeFileSync(probe, "{}", { mode: 384 });
+			rmSync(probe, { force: true });
+			const prune = await this.prune();
+			return {
+				path: this.cacheDir,
+				readable: true,
+				writable: true,
+				entryCount: this.entries().length,
+				prune
+			};
+		} catch (error) {
+			return {
+				path: this.cacheDir,
+				readable: false,
+				writable: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	pathFor(key) {
+		return join(this.cacheDir, `${observedOutputShapeStorageKey(key)}.json`);
+	}
+	entries() {
+		try {
+			return readdirSync(this.cacheDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => {
+				const path = join(this.cacheDir, entry.name);
+				return {
+					path,
+					mtimeMs: readMtimeMs(path)
+				};
+			});
+		} catch {
+			return [];
+		}
+	}
+	ttlMs() {
+		return this.options.ttlMs ?? OBSERVED_OUTPUT_SHAPE_LIMITS.ttlMs;
+	}
+	maxEntries() {
+		return this.options.maxEntries ?? OBSERVED_OUTPUT_SHAPE_LIMITS.maxLocalEntries;
+	}
+};
+function readMtimeMs(path) {
+	try {
+		return statSync(path).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+function isObservedOutputShape(value) {
+	return Boolean(value && typeof value === "object" && value.version === 1 && value.source === "observed" && typeof value.typeScript === "string" && typeof value.sampleCount === "number");
+}
+//#endregion
+//#region src/observed-output-shapes/merge.ts
+function mergeJsonShapes(left, right) {
+	if (left.kind === "unknown" || right.kind === "unknown") return { kind: "unknown" };
+	if (left.kind === right.kind) {
+		if (left.kind === "object" && right.kind === "object") return mergeObjects(left, right);
+		if (left.kind === "array" && right.kind === "array") return mergeArrays(left, right);
+		if (left.kind === "union" && right.kind === "union") return boundedUnion([...left.variants, ...right.variants]);
+		return left;
+	}
+	return boundedUnion([...left.kind === "union" ? left.variants : [left], ...right.kind === "union" ? right.variants : [right]]);
+}
+function mergeObjects(left, right) {
+	const fields = {};
+	const keys = [...new Set([...Object.keys(left.fields), ...Object.keys(right.fields)])].sort();
+	let truncated = left.truncated === true || right.truncated === true;
+	const selected = keys.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxObjectFields);
+	truncated = truncated || keys.length > selected.length;
+	for (const key of selected) {
+		const leftField = left.fields[key];
+		const rightField = right.fields[key];
+		if (leftField && rightField) fields[key] = {
+			optional: true,
+			shape: mergeJsonShapes(leftField.shape, rightField.shape)
+		};
+		else fields[key] = {
+			optional: true,
+			shape: (leftField ?? rightField).shape
+		};
+	}
+	return {
+		kind: "object",
+		fields,
+		...truncated ? { truncated: true } : {}
+	};
+}
+function mergeArrays(left, right) {
+	const element = left.element && right.element ? mergeJsonShapes(left.element, right.element) : left.element ?? right.element;
+	return {
+		kind: "array",
+		...element ? { element } : {},
+		...left.truncated === true || right.truncated === true ? { truncated: true } : {}
+	};
+}
+function boundedUnion(variants) {
+	const flattened = variants.flatMap((variant) => variant.kind === "union" ? variant.variants : [variant]);
+	const unique = [];
+	for (const variant of flattened) {
+		if (variant.kind === "unknown") return { kind: "unknown" };
+		const key = JSON.stringify(variant);
+		if (!unique.some((existing) => JSON.stringify(existing) === key)) unique.push(variant);
+	}
+	if (unique.length === 1) return unique[0];
+	if (unique.length > OBSERVED_OUTPUT_SHAPE_LIMITS.maxUnionVariants) return { kind: "unknown" };
+	return {
+		kind: "union",
+		variants: unique.sort((a, b) => a.kind.localeCompare(b.kind))
+	};
+}
+//#endregion
+//#region src/observed-output-shapes/typescript.ts
+function shapeToTypeScript(shape, typeName = "ObservedOutput", maxChars = OBSERVED_OUTPUT_SHAPE_LIMITS.maxTypeScriptChars) {
+	const typeScript = `type ${typeName} = ${shapeType(shape)};`;
+	if (typeScript.length <= maxChars) return {
+		typeScript,
+		truncated: hasTruncatedShape(shape)
+	};
+	return {
+		typeScript: `type ${typeName} = unknown;`,
+		truncated: true
+	};
+}
+function shapeType(shape) {
+	switch (shape.kind) {
+		case "null": return "null";
+		case "boolean": return "boolean";
+		case "number": return "number";
+		case "string": return "string";
+		case "unknown": return "unknown";
+		case "array": return `${shape.element ? wrapArrayElement(shapeType(shape.element)) : "unknown"}[]`;
+		case "object": return objectType(shape);
+		case "union": return unionType(shape.variants);
+	}
+}
+function hasTruncatedShape(shape) {
+	if ("truncated" in shape && shape.truncated === true) return true;
+	if (shape.kind === "array") return shape.element ? hasTruncatedShape(shape.element) : false;
+	if (shape.kind === "object") return Object.values(shape.fields).some((field) => hasTruncatedShape(field.shape));
+	if (shape.kind === "union") return shape.variants.some((variant) => hasTruncatedShape(variant));
+	return false;
+}
+function objectType(shape) {
+	const entries = Object.entries(shape.fields);
+	if (entries.length === 0) return "Record<string, unknown>";
+	return `{ ${entries.map(([key, field]) => `${propertyName(key)}?: ${shapeType(field.shape)};`).join(" ")} }`;
+}
+function unionType(variants) {
+	const rendered = [...new Set(variants.map((variant) => shapeType(variant)))];
+	return rendered.length === 0 ? "unknown" : rendered.join(" | ");
+}
+function wrapArrayElement(value) {
+	return value.includes(" | ") ? `(${value})` : value;
+}
+function propertyName(key) {
+	return /^[A-Za-z_$][\w$]*$/u.test(key) ? key : JSON.stringify(key);
+}
+//#endregion
+//#region src/observed-output-shapes/extract.ts
+function observeOutputShape(input) {
+	const shape = extractJsonShape(input.value);
+	if (!shape) return void 0;
+	const merged = input.existing ? mergeJsonShapes(input.existing.jsonShape, shape) : shape;
+	const emitted = shapeToTypeScript(merged);
+	const observed = {
+		version: 1,
+		source: "observed",
+		observedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
+		sampleCount: (input.existing?.sampleCount ?? 0) + 1,
+		typeScript: emitted.typeScript,
+		jsonShape: merged,
+		truncated: emitted.truncated || hasTruncatedShape(merged)
+	};
+	return storedBytes(observed) > OBSERVED_OUTPUT_SHAPE_LIMITS.maxStoredJsonBytes ? {
+		...observed,
+		typeScript: "type ObservedOutput = unknown;",
+		jsonShape: { kind: "unknown" },
+		truncated: true
+	} : observed;
+}
+function extractJsonShape(value) {
+	if (!isShapeableJsonRoot(value)) return void 0;
+	return shapeFor(value, 0);
+}
+function parseShapeableJsonText(value) {
+	if (!isPlainObject$1(value) || !Array.isArray(value.content) || value.content.length !== 1) return;
+	const [item] = value.content;
+	if (!isPlainObject$1(item) || item.type !== "text" || typeof item.text !== "string") return;
+	const text = item.text.trim();
+	if (!text || !text.startsWith("{") && !text.startsWith("[")) return void 0;
+	try {
+		const parsed = JSON.parse(text);
+		return isShapeableJsonRoot(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+function normalizedObservableValue(result) {
+	if (isPlainObject$1(result)) {
+		const structured = result.structuredContent;
+		if (structured !== void 0) {
+			if (isPlainObject$1(structured) && "caplets" in structured && "result" in structured) return isShapeableJsonRoot(structured.result) ? structured.result : void 0;
+			return isShapeableJsonRoot(structured) ? structured : void 0;
+		}
+	}
+	return parseShapeableJsonText(result);
+}
+function shapeFor(value, depth) {
+	if (depth >= OBSERVED_OUTPUT_SHAPE_LIMITS.maxDepth) return { kind: "unknown" };
+	if (value === null) return { kind: "null" };
+	if (typeof value === "boolean") return { kind: "boolean" };
+	if (typeof value === "number") return { kind: "number" };
+	if (typeof value === "string") return { kind: "string" };
+	if (Array.isArray(value)) return arrayShape(value, depth);
+	if (isPlainObject$1(value)) return objectShape(value, depth);
+	return { kind: "unknown" };
+}
+function arrayShape(value, depth) {
+	const sampled = value.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxArrayElements);
+	let element;
+	for (const item of sampled) {
+		const itemShape = shapeFor(item, depth + 1);
+		element = element ? mergeJsonShapes(element, itemShape) : itemShape;
+	}
+	return {
+		kind: "array",
+		...element ? { element } : {},
+		...value.length > sampled.length ? { truncated: true } : {}
+	};
+}
+function objectShape(value, depth) {
+	const keys = Object.keys(value).sort();
+	const selected = keys.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxObjectFields);
+	const fields = {};
+	for (const key of selected) fields[key] = {
+		optional: true,
+		shape: shapeFor(value[key], depth + 1)
+	};
+	return {
+		kind: "object",
+		fields,
+		...keys.length > selected.length ? { truncated: true } : {}
+	};
+}
+function isShapeableJsonRoot(value) {
+	return Array.isArray(value) || isPlainObject$1(value);
+}
+function isPlainObject$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function storedBytes(value) {
+	return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+//#endregion
+//#region src/observed-output-shapes/schema.ts
+function usefulOutputSchema(schema) {
+	if (!isPlainObject(schema)) return false;
+	if (Object.keys(schema).length === 0) return false;
+	if ("const" in schema || Array.isArray(schema.enum)) return true;
+	const type = schema.type;
+	if (Array.isArray(type)) return type.some((item) => usefulOutputSchema({
+		...schema,
+		type: item
+	}));
+	if (type === "object" || isPlainObject(schema.properties)) {
+		if (isPlainObject(schema.properties) && Object.keys(schema.properties).length > 0) return true;
+		if (schema.additionalProperties === false) return true;
+		if (isPlainObject(schema.additionalProperties)) return true;
+		return false;
+	}
+	if (type === "array") return usefulOutputSchema(schema.items);
+	if (typeof type === "string") return true;
+	if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf) || Array.isArray(schema.allOf)) return true;
+	return false;
+}
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { parseShapeableJsonText as a, shapeType as c, backendFingerprint as d, observedOutputShapeKey as f, OBSERVED_OUTPUT_SHAPE_VERSION as g, OBSERVED_OUTPUT_SHAPE_LIMITS as h, observeOutputShape as i, mergeJsonShapes as l, stableHash as m, extractJsonShape as n, hasTruncatedShape as o, observedOutputShapeStorageKey as p, normalizedObservableValue as r, shapeToTypeScript as s, usefulOutputSchema as t, FileObservedOutputShapeStore as u };

package/dist/observed-output-shapes.js

@@ -0,0 +1,2 @@
+import { a as parseShapeableJsonText, c as shapeType, d as backendFingerprint, f as observedOutputShapeKey, g as OBSERVED_OUTPUT_SHAPE_VERSION, h as OBSERVED_OUTPUT_SHAPE_LIMITS, i as observeOutputShape, l as mergeJsonShapes, m as stableHash, n as extractJsonShape, o as hasTruncatedShape, p as observedOutputShapeStorageKey, r as normalizedObservableValue, s as shapeToTypeScript, t as usefulOutputSchema, u as FileObservedOutputShapeStore } from "./observed-output-shapes-uzAMQPhg.js";
+export { FileObservedOutputShapeStore, OBSERVED_OUTPUT_SHAPE_LIMITS, OBSERVED_OUTPUT_SHAPE_VERSION, backendFingerprint, extractJsonShape, hasTruncatedShape, mergeJsonShapes, normalizedObservableValue, observeOutputShape, observedOutputShapeKey, observedOutputShapeStorageKey, parseShapeableJsonText, shapeToTypeScript, shapeType, stableHash, usefulOutputSchema };

package/dist/openapi.d.ts

@@ -1,6 +1,6 @@
 import type { CompatibilityCallToolResult, Tool } from "@modelcontextprotocol/sdk/types";
 import type { OpenApiEndpointConfig } from "./config";
-import type { CompactTool } from "./downstream";
+import { type CompactTool } from "./downstream";
 import type { ServerRegistry } from "./registry";
 export declare class OpenApiManager {
     private registry;

package/dist/project-binding/index.d.ts

@@ -0,0 +1,2 @@
+export { PROJECT_BINDING_STATES, PROJECT_BINDING_SYNC_STATES } from "./types";
+export type { BindingTerminalReason, ProjectBindingLease, ProjectBindingSetupReceipt, ProjectBindingState, ProjectBindingSyncState, ProjectBindingWorkspaceMetadata, } from "./types";

package/dist/project-binding.js

@@ -0,0 +1,22 @@
+//#region src/project-binding/types.ts
+const PROJECT_BINDING_STATES = [
+	"not_attached",
+	"attaching",
+	"syncing",
+	"ready",
+	"degraded",
+	"blocked",
+	"offline",
+	"cleaning_up",
+	"ended",
+	"expired"
+];
+const PROJECT_BINDING_SYNC_STATES = [
+	"not_started",
+	"pending",
+	"syncing",
+	"idle",
+	"failed"
+];
+//#endregion
+export { PROJECT_BINDING_STATES, PROJECT_BINDING_SYNC_STATES };

package/dist/redaction.d.ts

@@ -0,0 +1,14 @@
+export declare const SECRET_KEY_PATTERN: RegExp;
+export declare const SECRET_TEXT_PATTERNS: readonly [RegExp, RegExp, RegExp];
+export type RedactionResult = {
+    text: string;
+    redacted: boolean;
+};
+export type RedactionOptions = {
+    patterns?: readonly RegExp[] | undefined;
+    additionalSecrets?: readonly string[] | undefined;
+    replacement?: string | undefined;
+};
+export declare function isSecretKey(key: string): boolean;
+export declare function redactSecretText(value: string, options?: RedactionOptions): RedactionResult;
+export declare function redactUnknownSecrets<T>(value: T, options?: RedactionOptions): T;

package/dist/redaction.js

@@ -0,0 +1,30 @@
+//#region src/redaction.ts
+const SECRET_KEY_PATTERN = /(token|secret|authorization|auth|api[-_]?key|password|credential|clientsecret|client_secret|code|refresh)/iu;
+const SECRET_TEXT_PATTERNS = [
+	/(Authorization:\s*Bearer\s+)[0-9A-Za-z._~+/=-]+/giu,
+	/(bearer\s+)[a-z0-9._~+/=-]+/giu,
+	/([?&](?:access_token|refresh_token|token|code)=)[^&\s]+/giu
+];
+function isSecretKey(key) {
+	return SECRET_KEY_PATTERN.test(key);
+}
+function redactSecretText(value, options = {}) {
+	const replacement = options.replacement ?? "[REDACTED]";
+	let text = value;
+	for (const pattern of [...options.patterns ?? [], ...SECRET_TEXT_PATTERNS]) text = text.replace(pattern, (...args) => {
+		return `${typeof args[1] === "string" ? args[1] : ""}${replacement}`;
+	});
+	for (const secret of options.additionalSecrets?.filter(Boolean) ?? []) text = text.split(secret).join(replacement);
+	return {
+		text,
+		redacted: text !== value
+	};
+}
+function redactUnknownSecrets(value, options = {}) {
+	if (typeof value === "string") return redactSecretText(value, options).text;
+	if (Array.isArray(value)) return value.map((item) => redactUnknownSecrets(item, options));
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, isSecretKey(key) ? "[REDACTED]" : redactUnknownSecrets(entry, options)]));
+}
+//#endregion
+export { SECRET_KEY_PATTERN, SECRET_TEXT_PATTERNS, isSecretKey, redactSecretText, redactUnknownSecrets };

package/dist/registry.d.ts

@@ -6,6 +6,8 @@ export type CapletServerSummary = {
     id: string;
     name: string;
     description: string;
+    useWhen?: string;
+    avoidWhen?: string;
     disabled?: boolean;
     status: ServerStatus;
     lastError?: SafeErrorSummary;
@@ -14,6 +16,8 @@ export type CapletServerDetail = {
     id: string;
     name: string;
     description: string;
+    useWhen?: string;
+    avoidWhen?: string;
     tags?: string[];
     backend: {
         type: "mcp";

package/dist/remote/options.d.ts

@@ -38,5 +38,7 @@ export declare function resolveRemoteMode(input?: CapletsRemoteModeInput, env?:
     mode: CapletsRemoteMode;
 };
 export declare function resolveCapletsRemote(input?: CapletsRemoteInput, env?: CapletsRemoteEnv): ResolvedCapletsRemote;
+export declare function resolveHostedCloudRemote(input?: CapletsRemoteInput, env?: CapletsRemoteEnv): ResolvedCapletsRemote;
+export declare function hostedCloudWorkspaceFromRemoteUrl(value: string): string | undefined;
 export declare function projectBindingWebSocketUrlForBase(baseUrl: URL): URL;
 export declare function isCapletsCloudUrl(value: string): boolean;

package/dist/remote-control/types.d.ts

@@ -1,5 +1,5 @@
 import type { CapletsErrorCode } from "../errors";
-export type RemoteCliCommand = "list" | "inspect" | "check_backend" | "list_tools" | "search_tools" | "get_tool" | "call_tool" | "list_resources" | "search_resources" | "list_resource_templates" | "read_resource" | "list_prompts" | "search_prompts" | "get_prompt" | "complete" | "init" | "add" | "install" | "complete_cli" | "auth_login_start" | "auth_login_complete" | "auth_logout" | "auth_list";
+export type RemoteCliCommand = "list" | "inspect" | "check" | "tools" | "search_tools" | "describe_tool" | "call_tool" | "resources" | "search_resources" | "resource_templates" | "read_resource" | "prompts" | "search_prompts" | "get_prompt" | "complete" | "init" | "add" | "install" | "complete_cli" | "auth_login_start" | "auth_login_complete" | "auth_logout" | "auth_list";
 export type RemoteCliRequest = {
     command: RemoteCliCommand;
     arguments: Record<string, unknown>;

package/dist/runtime-plan/resources.d.ts

@@ -1,4 +1,6 @@
 import type { HostedRuntimeResourceClass, RuntimeResourcePolicy, RuntimeResourceResolution } from "./types";
+export declare function resourceClassRank(value: string): number;
+export declare function isRuntimeResourceClassAllowed(requested: string, maximum: string): boolean;
 type ResourceInput = {
     backend?: string | undefined;
     features: string[];

package/dist/runtime-plan.js

@@ -171,6 +171,12 @@ const rank = {
 	large: 2,
 	heavy: 3
 };
+function resourceClassRank(value) {
+	return rank[value] ?? 0;
+}
+function isRuntimeResourceClassAllowed(requested, maximum) {
+	return resourceClassRank(requested) <= resourceClassRank(maximum);
+}
 function resolveRuntimeResources(inputOrCaplet, features, policy) {
 	const caplet = inputOrCaplet;
 	const input = features === void 0 ? inputOrCaplet : {
@@ -205,7 +211,7 @@ function explicitResourceClass$1(caplet) {
 }
 function capClass(requested, maxClass) {
 	if (!maxClass) return requested;
-	return (rank[requested] ?? 0) > (rank[maxClass] ?? 0) ? maxClass : requested;
+	return isRuntimeResourceClassAllowed(requested, maxClass) ? requested : maxClass;
 }
 //#endregion
 //#region src/runtime-plan/planner.ts
@@ -272,4 +278,4 @@ function explicitResourceClass(caplet) {
 	return value === "small" || value === "medium" || value === "standard" || value === "large" || value === "heavy" ? value : void 0;
 }
 //#endregion
-export { HIDDEN_REASON_CODES, classifyCapletRuntimeRoute, inferRuntimeFeatures, planCapletRuntimeRoute, planCapletRuntimeRoutes, resolveRuntimeResources };
+export { HIDDEN_REASON_CODES, classifyCapletRuntimeRoute, inferRuntimeFeatures, isRuntimeResourceClassAllowed, planCapletRuntimeRoute, planCapletRuntimeRoutes, resolveRuntimeResources, resourceClassRank };