@caplets/core 0.18.9 → 0.20.0

package/dist/config.d.ts

@@ -35,11 +35,41 @@ export type RemoteAuthConfig = {
     scopes?: string[] | undefined;
     redirectUri?: string | undefined;
 };
-export type CapletServerConfig = {
+export type CapletSetupCommandConfig = {
+    label: string;
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    timeoutMs?: number | undefined;
+    maxOutputBytes?: number | undefined;
+};
+export type CapletSetupConfig = {
+    commands?: CapletSetupCommandConfig[] | undefined;
+    verify?: CapletSetupCommandConfig[] | undefined;
+};
+export type ProjectBindingConfig = {
+    required: true;
+};
+export type RuntimeFeature = "docker" | "browser";
+export type RuntimeResourceClass = "standard" | "large" | "heavy";
+export type RuntimeRequirementsConfig = {
+    features?: RuntimeFeature[] | undefined;
+    resources?: {
+        class?: RuntimeResourceClass | undefined;
+    } | undefined;
+};
+export type AgentSelectionHintsConfig = {
+    useWhen?: string | undefined;
+    avoidWhen?: string | undefined;
+};
+export type CapletExposure = "direct" | "progressive" | "code_mode" | "direct_and_code_mode" | "progressive_and_code_mode";
+export type CapletServerConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "mcp";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     transport: "stdio" | "http" | "sse";
@@ -53,6 +83,9 @@ export type CapletServerConfig = {
     callTimeoutMs: number;
     toolCacheTtlMs: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
 export type OpenApiAuthConfig = {
     type: "none";
@@ -65,11 +98,12 @@ export type OpenApiAuthConfig = {
 } | Extract<RemoteAuthConfig, {
     type: "oauth2" | "oidc";
 }>;
-export type OpenApiEndpointConfig = {
+export type OpenApiEndpointConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "openapi";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     specPath?: string | undefined;
@@ -79,18 +113,22 @@ export type OpenApiEndpointConfig = {
     requestTimeoutMs: number;
     operationCacheTtlMs: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
-export type GraphQlOperationConfig = {
+export type GraphQlOperationConfig = AgentSelectionHintsConfig & {
     document?: string | undefined;
     documentPath?: string | undefined;
     operationName?: string | undefined;
     description?: string | undefined;
 };
-export type GraphQlEndpointConfig = {
+export type GraphQlEndpointConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "graphql";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     endpointUrl: string;
@@ -103,8 +141,11 @@ export type GraphQlEndpointConfig = {
     operationCacheTtlMs: number;
     selectionDepth: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
-export type HttpActionConfig = {
+export type HttpActionConfig = AgentSelectionHintsConfig & {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     path: string;
     description?: string | undefined;
@@ -114,11 +155,12 @@ export type HttpActionConfig = {
     headers?: Record<string, string | number | boolean> | undefined;
     jsonBody?: unknown;
 };
-export type HttpApiConfig = {
+export type HttpApiConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "http";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     baseUrl: string;
@@ -127,11 +169,14 @@ export type HttpApiConfig = {
     requestTimeoutMs: number;
     maxResponseBytes: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
 export type CliToolOutputConfig = {
     type: "text" | "json";
 };
-export type CliToolActionConfig = {
+export type CliToolActionConfig = AgentSelectionHintsConfig & {
     description?: string | undefined;
     inputSchema?: Record<string, unknown> | undefined;
     outputSchema?: Record<string, unknown> | undefined;
@@ -149,11 +194,12 @@ export type CliToolActionConfig = {
         openWorldHint?: boolean | undefined;
     } | undefined;
 };
-export type CliToolsConfig = {
+export type CliToolsConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "cli";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     actions: Record<string, CliToolActionConfig>;
@@ -162,12 +208,16 @@ export type CliToolsConfig = {
     timeoutMs: number;
     maxOutputBytes: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
-export type CapletSetConfig = {
+export type CapletSetConfig = AgentSelectionHintsConfig & {
     server: string;
     backend: "caplets";
     name: string;
     description: string;
+    exposure?: CapletExposure | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     configPath?: string | undefined;
@@ -176,11 +226,17 @@ export type CapletSetConfig = {
     maxSearchLimit: number;
     toolCacheTtlMs: number;
     disabled: boolean;
+    setup?: CapletSetupConfig | undefined;
+    projectBinding?: ProjectBindingConfig | undefined;
+    runtime?: RuntimeRequirementsConfig | undefined;
 };
 export type CapletConfig = CapletServerConfig | OpenApiEndpointConfig | GraphQlEndpointConfig | HttpApiConfig | CliToolsConfig | CapletSetConfig;
 export type CapletsOptions = {
     defaultSearchLimit: number;
     maxSearchLimit: number;
+    exposure: CapletExposure;
+    exposureDiscoveryTimeoutMs: number;
+    exposureDiscoveryConcurrency: number;
     completion: CompletionConfig;
 };
 export type CompletionConfig = {
@@ -228,6 +284,17 @@ export declare const configFileSchema: z.ZodObject<{
         cacheTtlMs: z.ZodDefault<z.ZodNumber>;
         negativeCacheTtlMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
+    options: z.ZodDefault<z.ZodObject<{
+        exposure: z.ZodDefault<z.ZodEnum<{
+            direct: "direct";
+            progressive: "progressive";
+            code_mode: "code_mode";
+            direct_and_code_mode: "direct_and_code_mode";
+            progressive_and_code_mode: "progressive_and_code_mode";
+        }>>;
+        exposureDiscoveryTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        exposureDiscoveryConcurrency: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
     openapiEndpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
     graphqlEndpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;

package/dist/downstream.d.ts

@@ -2,11 +2,23 @@ import { type Prompt, type Resource, type ResourceTemplate as McpResourceTemplat
 import type { CapletServerConfig } from "./config";
 import type { ServerRegistry } from "./registry";
 export type CompactTool = {
-    id: string;
-    tool: string;
+    name: string;
     description?: string;
+    useWhen?: string;
+    avoidWhen?: string;
     hasInputSchema: boolean;
     hasOutputSchema: boolean;
+    supportsFields: boolean;
+    requiredArgs?: string[];
+    acceptedArgs?: string[];
+    argsTemplate?: Record<string, unknown>;
+    callTemplate?: {
+        operation: "call_tool";
+        name: string;
+        args: Record<string, unknown>;
+    };
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
 };
 export type CompactResource = {
     id: string;
@@ -202,8 +214,14 @@ export declare class DownstreamManager {
     private isCacheFresh;
     private refreshTools;
     private connect;
+    private connectionStartError;
+    private markConnectionStartUnavailable;
+    private startConnection;
     private createTransport;
     private oauthProvider;
     private currentServer;
     private currentServerFingerprint;
 }
+export declare function compactToolSafetyHints(tool: Tool): Pick<CompactTool, "readOnlyHint" | "destructiveHint">;
+export declare function compactToolSchemaHints(tool: Tool): Pick<CompactTool, "requiredArgs" | "acceptedArgs" | "argsTemplate" | "callTemplate">;
+export declare function compactToolSelectionHints(tool: unknown): Pick<CompactTool, "useWhen" | "avoidWhen">;

package/dist/engine.d.ts

@@ -1,4 +1,6 @@
 import { type CapletConfig, type CapletsConfig } from "./config";
+import { type ObservedOutputShapeKey, type ObservedOutputShapeStore } from "./observed-output-shapes";
+import { type ExposureSnapshot } from "./exposure/discovery";
 export type CapletsEngineOptions = {
     configPath?: string;
     projectConfigPath?: string;
@@ -7,6 +9,10 @@ export type CapletsEngineOptions = {
     watch?: boolean;
     writeErr?: (value: string) => void;
     configLoader?: (configPath: string, projectConfigPath: string) => CapletsConfig;
+    observedOutputShapeStore?: ObservedOutputShapeStore | undefined;
+    observedOutputShapeScope?: ObservedOutputShapeKey["scope"] | undefined;
+    observedOutputShapeCacheDir?: string | undefined;
+    projectFingerprint?: string | undefined;
 };
 export type CapletsEngineReloadEvent = {
     previous: CapletsConfig;
@@ -26,7 +32,11 @@ export declare class CapletsEngine {
     private readonly watchEnabled;
     private readonly writeErr;
     private readonly configLoader;
+    private readonly observedOutputShapeStore;
+    private readonly observedOutputShapeScope;
+    private readonly projectFingerprint;
     private readonly reloadListeners;
+    private lastExposureSnapshot;
     private watchers;
     private reloadTimer;
     private watcherRefreshTimer;
@@ -36,14 +46,24 @@ export declare class CapletsEngine {
     constructor(options?: CapletsEngineOptions);
     currentConfig(): CapletsConfig;
     enabledServers(): CapletConfig[];
+    exposureSnapshot(options?: {
+        discoverNonDirectMcpSurfaces?: boolean | undefined;
+    }): Promise<ExposureSnapshot>;
+    currentExposureSnapshot(): ExposureSnapshot | undefined;
     watchedPaths(): string[];
     onReload(listener: (event: CapletsEngineReloadEvent) => void): () => void;
     scheduleReload(): void;
     reload(): Promise<boolean>;
     execute(serverId: string, request: unknown): Promise<unknown>;
+    executeDirectTool(serverId: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    readDirectResource(serverId: string, downstreamUri: string): Promise<unknown>;
+    getDirectPrompt(serverId: string, promptName: string, args: Record<string, unknown>): Promise<unknown>;
     completeCliWords(words: string[]): Promise<string[]>;
     close(): Promise<void>;
     private listCompletionTools;
+    private listTools;
+    private callTool;
+    private optionalMcpList;
     private reloadOnce;
     private reloadUntilSettled;
     private emitReload;

package/dist/exposure/direct-names.d.ts

@@ -0,0 +1,9 @@
+export declare function directToolName(capletId: string, operationName: string): string;
+export declare function directPromptName(capletId: string, promptName: string): string;
+export declare function nativeDirectToolName(capletId: string, operationName: string): string;
+export declare function directResourceUri(capletId: string, downstreamUri: string): string;
+export declare function directResourceTemplateUri(capletId: string, downstreamUriTemplate: string): string;
+export declare function decodeDirectResourceUri(uri: string): {
+    capletId: string;
+    downstreamUri: string;
+};

package/dist/exposure/discovery.d.ts

@@ -0,0 +1,75 @@
+import type { Prompt, Resource, ResourceTemplate, Tool } from "@modelcontextprotocol/sdk/types";
+import type { CapletConfig, CapletsConfig } from "../config";
+import { type SafeErrorSummary } from "../errors";
+import { type ResolvedExposure } from "./policy";
+export type HiddenCapletReason = "disabled" | "setup_required" | "project_binding_required" | "discovery_failed" | "empty_surface";
+export type HiddenCaplet = {
+    capletId: string;
+    reason: HiddenCapletReason;
+    error?: SafeErrorSummary | undefined;
+};
+export type CallableCaplet = {
+    caplet: CapletConfig;
+    exposure: ResolvedExposure;
+    tools: Tool[];
+    resources: Resource[];
+    resourceTemplates: ResourceTemplate[];
+    prompts: Prompt[];
+    discoveredAt: number;
+};
+export type DirectToolRegistration = {
+    caplet: CapletConfig;
+    downstreamName: string;
+    name: string;
+    tool: Tool;
+};
+export type DirectResourceRegistration = {
+    caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>;
+    downstreamUri: string;
+    uri: string;
+    resource: Resource;
+};
+export type DirectResourceTemplateRegistration = {
+    caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>;
+    downstreamUriTemplate: string;
+    uriTemplate: string;
+    resourceTemplate: ResourceTemplate;
+};
+export type DirectPromptRegistration = {
+    caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>;
+    downstreamName: string;
+    name: string;
+    prompt: Prompt;
+};
+export type ExposureSnapshot = {
+    callableCaplets: CallableCaplet[];
+    progressiveCaplets: CallableCaplet[];
+    codeModeCaplets: CallableCaplet[];
+    directTools: DirectToolRegistration[];
+    directResources: DirectResourceRegistration[];
+    directResourceTemplates: DirectResourceTemplateRegistration[];
+    directPrompts: DirectPromptRegistration[];
+    hiddenCaplets: HiddenCaplet[];
+};
+export type DiscoverExposureSnapshotOptions = {
+    config: CapletsConfig;
+    caplets: CapletConfig[];
+    discoverNonDirectMcpSurfaces?: boolean | undefined;
+    listTools(caplet: CapletConfig): Promise<Tool[]>;
+    listResources?(caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>): Promise<Resource[]>;
+    listResourceTemplates?(caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>): Promise<ResourceTemplate[]>;
+    listPrompts?(caplet: Extract<CapletConfig, {
+        backend: "mcp";
+    }>): Promise<Prompt[]>;
+};
+export declare function discoverExposureSnapshot(options: DiscoverExposureSnapshotOptions): Promise<ExposureSnapshot>;

package/dist/exposure/policy.d.ts

@@ -0,0 +1,8 @@
+import type { CapletExposure } from "../config";
+export type ResolvedExposure = {
+    value: CapletExposure;
+    direct: boolean;
+    progressive: boolean;
+    codeMode: boolean;
+};
+export declare function resolveExposure(capletExposure: CapletExposure | undefined, globalExposure: CapletExposure): ResolvedExposure;

package/dist/filesystem-Kkg32TOJ.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+//#region src/caplet-source/types.ts
+function normalizeCapletSourcePath(path) {
+	const normalized = path.trim().replace(/\\/g, "/").replace(/^\.\//u, "");
+	if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) return;
+	const stack = [];
+	for (const segment of normalized.split("/")) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") {
+			if (stack.length === 0) return;
+			stack.pop();
+			continue;
+		}
+		stack.push(segment);
+	}
+	return stack.length > 0 ? stack.join("/") : void 0;
+}
+//#endregion
+//#region src/caplet-source/filesystem.ts
+var FilesystemCapletSource = class {
+	root;
+	constructor(root) {
+		this.root = resolve(root);
+	}
+	async listFiles() {
+		if (!existsSync(this.root) || !statSync(this.root).isDirectory()) return [];
+		return walkFiles(this.root, this.root).sort((left, right) => left.path.localeCompare(right.path));
+	}
+	async readFile(path) {
+		const normalized = normalizeCapletSourcePath(path);
+		if (!normalized) return;
+		const absolute = resolve(this.root, normalized);
+		if (!isWithinRoot(this.root, absolute) || !existsSync(absolute) || !statSync(absolute).isFile()) return;
+		return {
+			path: normalized,
+			content: readFileSync(absolute, "utf8")
+		};
+	}
+};
+function walkFiles(root, dir) {
+	const files = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true }).sort(compareDirents)) {
+		const absolute = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...walkFiles(root, absolute));
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		const normalized = normalizeCapletSourcePath(relative(root, absolute));
+		if (normalized) files.push({
+			path: normalized,
+			content: readFileSync(absolute, "utf8")
+		});
+	}
+	return files;
+}
+function compareDirents(left, right) {
+	return left.name.localeCompare(right.name);
+}
+function isWithinRoot(root, absolute) {
+	const rel = relative(root, absolute);
+	return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+//#endregion
+export { normalizeCapletSourcePath as n, FilesystemCapletSource as t };