@caplets/core 0.13.1 → 0.15.0

package/dist/native/process-cleanup.d.ts

@@ -0,0 +1,2 @@
+import type { NativeCapletsService } from "./service";
+export declare function registerNativeCapletsProcessCleanup(service: NativeCapletsService): void;

package/dist/native/service.d.ts

@@ -0,0 +1,24 @@
+export type NativeCapletsServiceOptions = {
+    configPath?: string;
+    projectConfigPath?: string;
+    authDir?: string;
+    watchDebounceMs?: number;
+    watch?: boolean;
+    writeErr?: (value: string) => void;
+};
+export type NativeCapletTool = {
+    caplet: string;
+    toolName: string;
+    title: string;
+    description: string;
+    promptGuidance: string[];
+};
+export type NativeCapletsToolsChangedListener = (tools: NativeCapletTool[]) => void;
+export type NativeCapletsService = {
+    listTools(): NativeCapletTool[];
+    execute(capletId: string, request: unknown): Promise<unknown>;
+    reload(): Promise<boolean>;
+    onToolsChanged(listener: NativeCapletsToolsChangedListener): () => void;
+    close(): Promise<void>;
+};
+export declare function createNativeCapletsService(options?: NativeCapletsServiceOptions): NativeCapletsService;

package/dist/native/tools.d.ts

@@ -0,0 +1,5 @@
+import type { CapletConfig } from "../config";
+export declare function nativeCapletToolName(capletId: string): string;
+export declare function nativeCapletsSystemGuidance(toolNames: string[]): string;
+export declare function nativeCapletPromptGuidance(toolName: string, caplet: CapletConfig): string[];
+export declare function nativeCapletToolDescription(toolName: string, caplet: CapletConfig): string;

package/dist/native.d.ts

@@ -0,0 +1,5 @@
+export { createNativeCapletsService, type NativeCapletTool, type NativeCapletsService, type NativeCapletsServiceOptions, type NativeCapletsToolsChangedListener, } from "./native/service";
+export { registerNativeCapletsProcessCleanup } from "./native/process-cleanup";
+export { nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, } from "./native/tools";
+export { generatedToolInputSchema } from "./tools";
+export { generatedToolInputJsonSchema } from "./generated-tool-input-schema";

package/dist/native.js

@@ -0,0 +1,93 @@
+import { a as capabilityDescription, n as generatedToolInputSchema, t as CapletsEngine } from "./engine-Bh55p8Lm.js";
+import { generatedToolInputJsonSchema } from "./generated-tool-input-schema.js";
+//#region src/native/tools.ts
+function nativeCapletToolName(capletId) {
+	return `caplets_${capletId.replace(/_/g, "__").replace(/-/g, "_")}`;
+}
+function nativeCapletsSystemGuidance(toolNames) {
+	return [
+		"## Caplets Native Tools",
+		"",
+		"Caplets tools expose configured capability domains through progressive discovery.",
+		"",
+		"Available Caplets native tools:",
+		toolNames.length > 0 ? toolNames.map((tool) => `- ${tool}`).join("\n") : "- none",
+		"",
+		"Flow: get_caplet when the domain is unfamiliar; search_tools or list_tools to find exact downstream names; get_tool only when schemas are unclear; call_tool with downstream inputs inside arguments.",
+		"Use fields on call_tool when a non-GraphQL downstream outputSchema allows selecting only needed structured paths."
+	].join("\n");
+}
+function nativeCapletPromptGuidance(toolName, caplet) {
+	return [`Use ${toolName} for the ${caplet.name} Caplet capability domain.`];
+}
+function nativeCapletToolDescription(toolName, caplet) {
+	return [
+		capabilityDescription(caplet),
+		"",
+		`Native tool name: ${toolName}`,
+		`Original Caplet ID: ${caplet.server}`
+	].join("\n");
+}
+//#endregion
+//#region src/native/service.ts
+function createNativeCapletsService(options = {}) {
+	return new DefaultNativeCapletsService(options);
+}
+var DefaultNativeCapletsService = class {
+	engine;
+	constructor(options) {
+		this.engine = new CapletsEngine(options);
+	}
+	listTools() {
+		return this.engine.enabledServers().map((caplet) => {
+			const toolName = nativeCapletToolName(caplet.server);
+			return {
+				caplet: caplet.server,
+				toolName,
+				title: caplet.name,
+				description: nativeCapletToolDescription(toolName, caplet),
+				promptGuidance: nativeCapletPromptGuidance(toolName, caplet)
+			};
+		});
+	}
+	async execute(capletId, request) {
+		return await this.engine.execute(capletId, request);
+	}
+	async reload() {
+		return await this.engine.reload();
+	}
+	onToolsChanged(listener) {
+		return this.engine.onReload(() => listener(this.listTools()));
+	}
+	async close() {
+		await this.engine.close();
+	}
+};
+//#endregion
+//#region src/native/process-cleanup.ts
+function registerNativeCapletsProcessCleanup(service) {
+	let closed = false;
+	const close = async () => {
+		if (closed) return;
+		closed = true;
+		try {
+			await service.close();
+		} catch (error) {
+			console.error("Failed to close Caplets service:", error);
+			process.exitCode = 1;
+		}
+	};
+	const closeBeforeExit = () => {
+		close();
+	};
+	const closeAndExit = () => {
+		close().finally(() => {
+			process.exit(process.exitCode ?? 0);
+		});
+	};
+	process.once("beforeExit", closeBeforeExit);
+	process.once("SIGINT", closeAndExit);
+	process.once("SIGTERM", closeAndExit);
+}
+//#endregion
+export { createNativeCapletsService, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, registerNativeCapletsProcessCleanup };

package/dist/openapi.d.ts

@@ -0,0 +1,29 @@
+import type { CompatibilityCallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { OpenApiEndpointConfig } from "./config";
+import type { CompactTool } from "./downstream";
+import type { ServerRegistry } from "./registry";
+export declare class OpenApiManager {
+    private registry;
+    private readonly options;
+    private readonly cache;
+    constructor(registry: ServerRegistry, options?: {
+        authDir?: string;
+    });
+    updateRegistry(registry: ServerRegistry): void;
+    invalidate(serverId: string): void;
+    checkEndpoint(endpoint: OpenApiEndpointConfig): Promise<{
+        id: string;
+        status: string;
+        toolCount?: number;
+        elapsedMs: number;
+        error?: unknown;
+    }>;
+    listTools(endpoint: OpenApiEndpointConfig): Promise<Tool[]>;
+    getTool(endpoint: OpenApiEndpointConfig, toolName: string): Promise<Tool>;
+    callTool(endpoint: OpenApiEndpointConfig, toolName: string, args: Record<string, unknown>): Promise<CompatibilityCallToolResult>;
+    compact(endpoint: OpenApiEndpointConfig, tool: Tool): CompactTool;
+    search(endpoint: OpenApiEndpointConfig, tools: Tool[], query: string, limit: number): CompactTool[];
+    private getOperation;
+    private refreshOperations;
+    private toTool;
+}

package/dist/registry.d.ts

@@ -0,0 +1,68 @@
+import type { CapletConfig, CapletsConfig, CapletServerConfig } from "./config";
+import type { SafeErrorSummary } from "./errors";
+export { capabilityDescription } from "./capability-description";
+export type ServerStatus = "disabled" | "not_started" | "starting" | "available" | "unavailable";
+export type CapletServerSummary = {
+    id: string;
+    name: string;
+    description: string;
+    disabled?: boolean;
+    status: ServerStatus;
+    lastError?: SafeErrorSummary;
+};
+export type CapletServerDetail = {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    backend: {
+        type: "mcp";
+        transport: CapletServerConfig["transport"];
+        disabled: boolean;
+        startupTimeoutMs: number;
+        callTimeoutMs: number;
+        toolCacheTtlMs: number;
+    } | {
+        type: "openapi";
+        disabled: boolean;
+        requestTimeoutMs: number;
+        operationCacheTtlMs: number;
+        source: "specPath" | "specUrl";
+    } | {
+        type: "graphql";
+        disabled: boolean;
+        requestTimeoutMs: number;
+        operationCacheTtlMs: number;
+        source: "schemaPath" | "schemaUrl" | "introspection";
+        configuredOperations: boolean;
+    } | {
+        type: "http";
+        disabled: boolean;
+        requestTimeoutMs: number;
+        configuredActions: number;
+    } | {
+        type: "cli";
+        disabled: boolean;
+        timeoutMs: number;
+        maxOutputBytes: number;
+        configuredActions: number;
+    } | {
+        type: "caplets";
+        disabled: boolean;
+        source: "configPath" | "capletsRoot" | "both";
+        toolCacheTtlMs: number;
+    };
+};
+export declare class ServerRegistry {
+    readonly config: CapletsConfig;
+    private readonly statuses;
+    constructor(config: CapletsConfig);
+    enabledServers(): CapletConfig[];
+    get(serverId: string): CapletConfig | undefined;
+    require(serverId: string): CapletConfig;
+    setStatus(serverId: string, status: ServerStatus, lastError?: SafeErrorSummary): void;
+    getStatus(serverId: string): ServerStatus;
+    summary(server: CapletConfig): CapletServerSummary;
+    detail(server: CapletConfig): CapletServerDetail;
+    private allCaplets;
+}

package/dist/result-content.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export type TextContentBlock = {
+    type: "text";
+    text: string;
+};
+export declare function structuredOnlyContent(): [];
+export declare function textContent(text: string): TextContentBlock[];
+export declare function compactJsonText(value: unknown, maxLength?: number): string;
+export declare function compactText(value: string, maxLength?: number): string;
+export declare function resultKeys(value: unknown): string;
+export declare function statusSummary(value: unknown): string;
+export declare function compactStructuredContent(value: unknown): TextContentBlock[];
+export declare function compactCallToolResultContent(result: CallToolResult): TextContentBlock[];
+export declare function byteLimitHint(maxBytes: number): string;

package/dist/runtime.d.ts

@@ -0,0 +1,30 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type CapletsConfig } from "./config";
+type ToolServer = Pick<McpServer, "registerTool" | "connect" | "close">;
+type CapletsRuntimeOptions = {
+    configPath?: string;
+    projectConfigPath?: string;
+    authDir?: string;
+    watchDebounceMs?: number;
+    server?: ToolServer;
+    writeErr?: (value: string) => void;
+};
+export declare class CapletsRuntime {
+    readonly server: ToolServer;
+    private readonly engine;
+    private readonly tools;
+    private readonly unsubscribeReload;
+    constructor(options?: CapletsRuntimeOptions);
+    connect(transport: Transport): Promise<void>;
+    scheduleReload(): void;
+    reload(): Promise<boolean>;
+    close(): Promise<void>;
+    currentConfig(): CapletsConfig;
+    registeredToolIds(): string[];
+    watchedPaths(): string[];
+    private reconcileTools;
+    private registerCapletTool;
+    private handleTool;
+}
+export {};

package/dist/schema-hash.d.ts

@@ -0,0 +1 @@
+export declare function schemaHash(schema: unknown | undefined): string | null;

package/dist/schema-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function nestedSchema<T>(value: unknown, key: string): T | undefined;
+export declare function schemaPath<T>(value: unknown, path: string[]): T | undefined;

package/dist/tool-search.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare function searchToolList<T>(tools: Tool[], query: string, limit: number, compact: (tool: Tool) => T): T[];

package/dist/tools.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CapletSetManager } from "./caplet-sets";
+import type { CapletConfig } from "./config";
+import type { CliToolsManager } from "./cli-tools";
+import type { DownstreamManager } from "./downstream";
+import type { GraphQLManager } from "./graphql";
+import type { HttpActionManager } from "./http-actions";
+import type { OpenApiManager } from "./openapi";
+import type { ServerRegistry } from "./registry";
+export declare const generatedToolInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        get_caplet: "get_caplet";
+        check_backend: "check_backend";
+        list_tools: "list_tools";
+        search_tools: "search_tools";
+        get_tool: "get_tool";
+        call_tool: "call_tool";
+    }>;
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    tool: z.ZodOptional<z.ZodString>;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type GeneratedServerToolRequest = z.infer<typeof generatedToolInputSchema>;
+export declare function handleServerTool(server: CapletConfig, request: unknown, registry: ServerRegistry, downstream: DownstreamManager, openapi?: OpenApiManager, graphql?: GraphQLManager, http?: HttpActionManager, cli?: CliToolsManager, caplets?: CapletSetManager): Promise<any>;
+export declare function validateOperationRequest(request: unknown, maxSearchLimit: number): RequiredOperationRequest;
+type RequiredOperationRequest = {
+    operation: "get_caplet" | "check_backend";
+} | {
+    operation: "list_tools";
+    limit?: number;
+} | {
+    operation: "search_tools";
+    query: string;
+    limit?: number;
+} | {
+    operation: "get_tool";
+    tool: string;
+} | {
+    operation: "call_tool";
+    tool: string;
+    arguments: Record<string, unknown>;
+    fields?: string[];
+};
+export type CapletArtifact = {
+    kind: "screenshot" | "snapshot" | "console-log" | "network-log" | "file";
+    displayPath: string;
+    pathResolution: "absolute" | "relative-to-mcp-server";
+};
+export type CapletResultMetadata = {
+    id: string;
+    name: string;
+    backend: string;
+    operation: RequiredOperationRequest["operation"];
+    tool?: string;
+    status: "ok" | "error";
+    elapsedMs?: number;
+    artifacts?: CapletArtifact[];
+};
+export declare function metadataFor(server: CapletConfig, operation: RequiredOperationRequest["operation"], tool?: string, startedAt?: number): CapletResultMetadata;
+export declare function jsonResult(value: unknown, metadata?: CapletResultMetadata): CallToolResult;
+export declare function annotateCallToolResult<T extends object>(result: T, metadata: CapletResultMetadata): T & CallToolResult;
+export declare function projectCallToolResult<T extends object>(result: T, outputSchema: unknown, fields: string[]): T & CallToolResult;
+export declare function extractArtifacts(result: unknown): CapletArtifact[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Core runtime library for Caplets progressive disclosure gateways.",
   "keywords": [
     "caplets",
@@ -21,14 +21,24 @@
     "directory": "packages/core"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "type": "module",
   "main": "dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./generated-tool-input-schema": "./dist/generated-tool-input-schema.js",
-    "./native": "./dist/native.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./generated-tool-input-schema": {
+      "types": "./dist/generated-tool-input-schema.d.ts",
+      "default": "./dist/generated-tool-input-schema.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "default": "./dist/native.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -43,8 +53,9 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
-    "rolldown": "^1.0.0",
+    "@types/node": "^25.9.0",
+    "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "rolldown": "^1.0.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   },
@@ -52,9 +63,9 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "rm -rf dist && rolldown -c",
+    "build": "rm -rf dist && rolldown -c && tsc -p tsconfig.build.json",
     "build:watch": "rolldown -c --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run"
   }
 }