@caplets/core 0.21.0 → 0.22.0

package/dist/attach/options.d.ts

@@ -4,7 +4,9 @@ export type RawAttachServeOptions = RemoteSelectionInput & RawServeOptions & {
     projectRoot?: string;
 };
 export type AttachServeOptions = ServeOptions & {
+    configPath: string;
     projectRoot: string;
+    projectConfigPath: string;
     selection: ResolvedRemoteSelection;
 };
 export declare function resolveAttachServeOptions(raw?: RawAttachServeOptions, env?: Record<string, string | undefined>): Promise<AttachServeOptions>;

package/dist/caplet-files-bundle.d.ts

@@ -390,6 +390,10 @@ export declare const capletFileSchema: z.ZodObject<{
         direct_and_code_mode: "direct_and_code_mode";
         progressive_and_code_mode: "progressive_and_code_mode";
     }>>;
+    shadowing: z.ZodOptional<z.ZodEnum<{
+        forbid: "forbid";
+        allow: "allow";
+    }>>;
 }, z.core.$strict>;
 export declare function capletJsonSchema(): unknown;
 export type CapletFileConfig = {

package/dist/caplet-source.js

@@ -10166,6 +10166,7 @@ const capletExposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]).describe("How this Caplet is exposed to agents.");
+const capletShadowingSchema = _enum(["forbid", "allow"]).describe("Whether attached local Caplets may shadow this remote Caplet ID.");
 const capletEndpointAuthSchema = discriminatedUnion("type", [
 	object({ type: literal("none") }).strict(),
 	object({
@@ -10446,6 +10447,7 @@ const capletFileSchema = object({
 	description: string().describe("Compact capability description shown before the full Caplet card is disclosed.").refine((value) => value.trim().length >= 10, "description must contain at least 10 non-whitespace characters").refine((value) => value.length <= 1500, "description must be at most 1500 characters"),
 	tags: array(string().trim().min(1).max(80)).optional().describe("Optional tags for grouping or searching Caplets."),
 	exposure: capletExposureSchema.optional(),
+	shadowing: capletShadowingSchema.optional(),
 	...capletAgentSelectionHintsSchema,
 	setup: capletSetupSchema.optional(),
 	projectBinding: capletProjectBindingSchema.optional(),
@@ -10643,6 +10645,7 @@ function sharedCapletFields(frontmatter) {
 	return {
 		...frontmatter.tags ? { tags: frontmatter.tags } : {},
 		...frontmatter.exposure ? { exposure: frontmatter.exposure } : {},
+		...frontmatter.shadowing ? { shadowing: frontmatter.shadowing } : {},
 		...frontmatter.useWhen ? { useWhen: frontmatter.useWhen } : {},
 		...frontmatter.avoidWhen ? { avoidWhen: frontmatter.avoidWhen } : {},
 		...frontmatter.setup ? { setup: frontmatter.setup } : {},
@@ -10797,11 +10800,13 @@ const exposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]);
+const shadowingSchema = _enum(["forbid", "allow"]).default("forbid");
 const commonSchema = {
 	name: string().trim().min(1).max(80),
 	description: string().refine((value) => value.trim().length >= 10, "description must contain at least 10 non-whitespace characters").refine((value) => value.length <= 1500, "description must be at most 1500 characters"),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	body: string().optional(),
 	setup: setupSchema.optional(),

package/dist/cli/auth.d.ts

@@ -82,6 +82,7 @@ declare function authTargets(config: ReturnType<typeof loadConfig>): (import("..
     name: string;
     description: string;
     exposure?: import("../config").CapletExposure | undefined;
+    shadowing?: import("../config").CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     endpointUrl: string;
@@ -103,6 +104,7 @@ declare function authTargets(config: ReturnType<typeof loadConfig>): (import("..
     name: string;
     description: string;
     exposure?: import("../config").CapletExposure | undefined;
+    shadowing?: import("../config").CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     baseUrl: string;

package/dist/code-mode/types.d.ts

@@ -6,6 +6,7 @@ export type CodeModeCallableCaplet = {
     id: string;
     name: string;
     description: string;
+    shadowing?: "forbid" | "allow";
     useWhen?: string;
     avoidWhen?: string;
 };

package/dist/{completion-GTIuH0CW.js → completion-DnQujlrc.js}

@@ -1,4 +1,4 @@
-import { Ct as resolveCapletsRoot, Et as resolveProjectConfigPath, Q as loadConfigWithSources, Sn as __exportAll, _t as DEFAULT_AUTH_DIR, vt as DEFAULT_COMPLETION_CACHE_DIR, wt as resolveConfigPath } from "./service-Bs7l5haO.js";
+import { Ct as resolveCapletsRoot, Et as resolveProjectConfigPath, Q as loadConfigWithSources, Sn as __exportAll, _t as DEFAULT_AUTH_DIR, vt as DEFAULT_COMPLETION_CACHE_DIR, wt as resolveConfigPath } from "./service-4_chB2wu.js";
 import { u as CapletsError } from "./validation-DgxCzt-A.js";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";

package/dist/config-runtime.d.ts

@@ -49,6 +49,7 @@ export type AgentSelectionHintsConfig = {
     avoidWhen?: string | undefined;
 };
 export type CapletExposure = "direct" | "progressive" | "code_mode" | "direct_and_code_mode" | "progressive_and_code_mode";
+export type CapletShadowingPolicy = "forbid" | "allow";
 export type CapletServerConfig = CommonCapletConfig & {
     backend: "mcp";
     transport: "stdio" | "http" | "sse";
@@ -172,6 +173,7 @@ type CommonCapletConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     setup?: CapletSetupConfig | undefined;

package/dist/config-runtime.js

@@ -49,11 +49,13 @@ const exposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]);
+const shadowingSchema = _enum(["forbid", "allow"]).default("forbid");
 const commonSchema = {
 	name: string().trim().min(1).max(80),
 	description: string().refine((value) => value.trim().length >= 10, "description must contain at least 10 non-whitespace characters").refine((value) => value.length <= 1500, "description must be at most 1500 characters"),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	body: string().optional(),
 	setup: setupSchema.optional(),

package/dist/config.d.ts

@@ -63,6 +63,7 @@ export type AgentSelectionHintsConfig = {
     useWhen?: string | undefined;
     avoidWhen?: string | undefined;
 };
+export type CapletShadowingPolicy = "forbid" | "allow";
 export type CapletExposure = "direct" | "progressive" | "code_mode" | "direct_and_code_mode" | "progressive_and_code_mode";
 export type CapletServerConfig = AgentSelectionHintsConfig & {
     server: string;
@@ -70,6 +71,7 @@ export type CapletServerConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     transport: "stdio" | "http" | "sse";
@@ -104,6 +106,7 @@ export type OpenApiEndpointConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     specPath?: string | undefined;
@@ -129,6 +132,7 @@ export type GraphQlEndpointConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     endpointUrl: string;
@@ -161,6 +165,7 @@ export type HttpApiConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     baseUrl: string;
@@ -200,6 +205,7 @@ export type CliToolsConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     actions: Record<string, CliToolActionConfig>;
@@ -218,6 +224,7 @@ export type CapletSetConfig = AgentSelectionHintsConfig & {
     name: string;
     description: string;
     exposure?: CapletExposure | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     tags?: string[] | undefined;
     body?: string | undefined;
     configPath?: string | undefined;

package/dist/index.js

@@ -1,9 +1,9 @@
-import { $ as loadGlobalConfig, $t as ListRootsResultSchema, A as codeModeRunParamsSchema, At as assertToolsCallTaskCapability, B as generateCodeModeRunToolDescription, Bt as CreateTaskResultSchema, C as nativeCapletPromptGuidance, Ct as resolveCapletsRoot, D as nativeCodeModeToolId, Dt as ReadBuffer, Et as resolveProjectConfigPath, F as listCodeModeCallableCaplets, Ft as CallToolRequestSchema, G as directResourceUriMatchesTemplate, Gt as GetPromptRequestSchema, H as CapletsEngine, Ht as ElicitResultSchema, I as CodeModeLogStore, It as CallToolResultSchema, J as handleServerTool, Jt as JSONRPCMessageSchema, K as findProjectRoot, Kt as InitializeRequestSchema, L as redactCodeModeLogText, Lt as CompleteRequestSchema, M as QuickJsCodeModeSandbox, Mt as Protocol, N as diagnoseCodeModeTypeScript, Nt as mergeCapabilities, Ot as serializeMessage, P as createCodeModeCapletsApi, Pt as toJsonSchemaCompat, Q as loadConfigWithSources, Qt as ListResourcesRequestSchema, R as codeModeDeclarationHash, Rt as CreateMessageResultSchema, S as resolveCapletsServer, St as defaultStateBaseDir, T as nativeCapletToolName, Tt as resolveProjectCapletsRoot, U as resolveExposure, Ut as EmptyResultSchema, V as minifyCodeModeDeclarationText, W as decodeDirectResourceUri, Wt as ErrorCode, X as capabilityDescription, Xt as ListPromptsRequestSchema, Y as ServerRegistry, Yt as LATEST_PROTOCOL_VERSION, Z as loadConfig, Zt as ListResourceTemplatesRequestSchema, _ as resolveHostedCloudRemote, _n as isZ4Schema, a as projectBindingError, an as SetLevelRequestSchema, at as loadCapletFilesFromMap, b as parseServerBaseUrl, bn as safeParse, bt as defaultCacheBaseDir, c as cloudAuthPath, cn as isInitializeRequest, ct as markdownStructuredContent, d as CloudAuthClient, dn as isJSONRPCResultResponse, dt as runOAuthFlow, en as ListToolsRequestSchema, et as loadLocalOverlayConfigWithSources, fn as getLiteralValue, ft as startGenericOAuthFlow, g as resolveCapletsRemote, gn as isSchemaOptional, gt as readTokenBundle, hn as getSchemaDescription, ht as isTokenBundleExpired, i as ProjectBindingError, in as SUPPORTED_PROTOCOL_VERSIONS, it as validateCapletFile, j as runCodeMode, jt as AjvJsonSchemaValidator, k as codeModeRunInputSchema, kt as assertClientRequestTaskCapability, l as migrateCredentials, ln as isJSONRPCErrorResponse, lt as refreshOAuthTokenBundle, m as buildProjectSyncManifest, mn as getParseErrorMessage, mt as deleteTokenBundle, n as resolveRemoteSelection, nn as McpError, nt as parseConfig, o as projectBindingRecovery, on as assertCompleteRequestPrompt, ot as hasRenderableStructuredContent, p as createSdkRemoteCapletsClient, pn as getObjectShape, pt as startOAuthFlow, q as fingerprintProjectRoot, qt as InitializedNotificationSchema, r as PROJECT_BINDING_ERROR_CODES, rn as ReadResourceRequestSchema, rt as discoverCapletFiles, s as CloudAuthStore, sn as assertCompleteRequestResourceTemplate, st as markdownCallToolResultContent, t as createNativeCapletsService, tn as LoggingLevelSchema, tt as loadProjectConfig, u as redactedCloudAuthStatus, un as isJSONRPCRequest, ut as runGenericOAuthFlow, v as resolveRemoteMode, vn as normalizeObjectSchema, w as nativeCapletToolDescription, wt as resolveConfigPath, x as resolveCapletsMode, xn as safeParseAsync, xt as defaultConfigBaseDir, y as controlUrlForBase, yn as objectFromShape, yt as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, z as generateCodeModeDeclarations, zt as CreateMessageResultWithToolsSchema } from "./service-Bs7l5haO.js";
+import { $ as loadGlobalConfig, $t as ListRootsResultSchema, A as codeModeRunParamsSchema, At as assertToolsCallTaskCapability, B as generateCodeModeRunToolDescription, Bt as CreateTaskResultSchema, C as nativeCapletPromptGuidance, Ct as resolveCapletsRoot, D as nativeCodeModeToolId, Dt as ReadBuffer, Et as resolveProjectConfigPath, F as listCodeModeCallableCaplets, Ft as CallToolRequestSchema, G as directResourceUriMatchesTemplate, Gt as GetPromptRequestSchema, H as CapletsEngine, Ht as ElicitResultSchema, I as CodeModeLogStore, It as CallToolResultSchema, J as handleServerTool, Jt as JSONRPCMessageSchema, K as findProjectRoot, Kt as InitializeRequestSchema, L as redactCodeModeLogText, Lt as CompleteRequestSchema, M as QuickJsCodeModeSandbox, Mt as Protocol, N as diagnoseCodeModeTypeScript, Nt as mergeCapabilities, Ot as serializeMessage, P as createCodeModeCapletsApi, Pt as toJsonSchemaCompat, Q as loadConfigWithSources, Qt as ListResourcesRequestSchema, R as codeModeDeclarationHash, Rt as CreateMessageResultSchema, S as resolveCapletsServer, St as defaultStateBaseDir, T as nativeCapletToolName, Tt as resolveProjectCapletsRoot, U as resolveExposure, Ut as EmptyResultSchema, V as minifyCodeModeDeclarationText, W as decodeDirectResourceUri, Wt as ErrorCode, X as capabilityDescription, Xt as ListPromptsRequestSchema, Y as ServerRegistry, Yt as LATEST_PROTOCOL_VERSION, Z as loadConfig, Zt as ListResourceTemplatesRequestSchema, _ as resolveHostedCloudRemote, _n as isZ4Schema, a as projectBindingError, an as SetLevelRequestSchema, at as loadCapletFilesFromMap, b as parseServerBaseUrl, bn as safeParse, bt as defaultCacheBaseDir, c as cloudAuthPath, cn as isInitializeRequest, ct as markdownStructuredContent, d as CloudAuthClient, dn as isJSONRPCResultResponse, dt as runOAuthFlow, en as ListToolsRequestSchema, et as loadLocalOverlayConfigWithSources, fn as getLiteralValue, ft as startGenericOAuthFlow, g as resolveCapletsRemote, gn as isSchemaOptional, gt as readTokenBundle, hn as getSchemaDescription, ht as isTokenBundleExpired, i as ProjectBindingError, in as SUPPORTED_PROTOCOL_VERSIONS, it as validateCapletFile, j as runCodeMode, jt as AjvJsonSchemaValidator, k as codeModeRunInputSchema, kt as assertClientRequestTaskCapability, l as migrateCredentials, ln as isJSONRPCErrorResponse, lt as refreshOAuthTokenBundle, m as buildProjectSyncManifest, mn as getParseErrorMessage, mt as deleteTokenBundle, n as resolveRemoteSelection, nn as McpError, nt as parseConfig, o as projectBindingRecovery, on as assertCompleteRequestPrompt, ot as hasRenderableStructuredContent, p as createSdkRemoteCapletsClient, pn as getObjectShape, pt as startOAuthFlow, q as fingerprintProjectRoot, qt as InitializedNotificationSchema, r as PROJECT_BINDING_ERROR_CODES, rn as ReadResourceRequestSchema, rt as discoverCapletFiles, s as CloudAuthStore, sn as assertCompleteRequestResourceTemplate, st as markdownCallToolResultContent, t as createNativeCapletsService, tn as LoggingLevelSchema, tt as loadProjectConfig, u as redactedCloudAuthStatus, un as isJSONRPCRequest, ut as runGenericOAuthFlow, v as resolveRemoteMode, vn as normalizeObjectSchema, w as nativeCapletToolDescription, wt as resolveConfigPath, x as resolveCapletsMode, xn as safeParseAsync, xt as defaultConfigBaseDir, y as controlUrlForBase, yn as objectFromShape, yt as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, z as generateCodeModeDeclarations, zt as CreateMessageResultWithToolsSchema } from "./service-4_chB2wu.js";
 import { _ as record, b as unknown, d as literal, m as object, n as ZodOptional, o as array, p as number, r as _enum, s as boolean, v as string, x as url } from "./schemas-C0PNPwjS.js";
 import { f as redactSecrets, i as SERVER_ID_PATTERN, l as CAPLETS_ERROR_CODES, p as toSafeError, u as CapletsError } from "./validation-DgxCzt-A.js";
 import { generatedToolInputJsonSchemaForCaplet, generatedToolInputSchema, generatedToolInputSchemaForCaplet } from "./generated-tool-input-schema.js";
 import { f as observedOutputShapeKey, g as stableJsonStringify, h as schemaHash, i as observeOutputShape, u as FileObservedOutputShapeStore } from "./observed-output-shapes-CL5MFXwM.js";
-import { a as formatCapletList, c as resolveCliConfigPaths, l as cliCommands$1, n as completionScript, o as formatConfigPaths, s as listCaplets, t as completeCliWords, u as completionShells } from "./completion-GTIuH0CW.js";
+import { a as formatCapletList, c as resolveCliConfigPaths, l as cliCommands$1, n as completionScript, o as formatConfigPaths, s as listCaplets, t as completeCliWords, u as completionShells } from "./completion-DnQujlrc.js";
 import { n as normalizeCapletSourcePath, t as FilesystemCapletSource } from "./filesystem-Kkg32TOJ.js";
 import { parseConfig as parseConfig$1 } from "./config-runtime.js";
 import fs, { accessSync, chmodSync, closeSync, constants, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
@@ -1553,7 +1553,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 } };
 //#endregion
 //#region package.json
-var version = "0.21.0";
+var version = "0.22.0";
 //#endregion
 //#region src/serve/session.ts
 var CapletsMcpSession = class {
@@ -7183,9 +7183,13 @@ function hasEnv(value) {
 //#region src/attach/options.ts
 async function resolveAttachServeOptions(raw = {}, env = process.env) {
 	const selection = await resolveRemoteSelection(raw, env);
+	const serve = resolveServeOptions(attachLocalServeOptions(raw), env);
+	const projectRoot = raw.projectRoot ?? process.cwd();
 	return {
-		...resolveServeOptions(attachLocalServeOptions(raw), env),
-		projectRoot: raw.projectRoot ?? process.cwd(),
+		...serve,
+		configPath: resolveConfigPath(env.CAPLETS_CONFIG?.trim() || void 0),
+		projectRoot,
+		projectConfigPath: env.CAPLETS_PROJECT_CONFIG?.trim() || resolveProjectConfigPath(projectRoot),
 		selection
 	};
 }
@@ -10662,7 +10666,7 @@ function progressiveCapletExport(entry) {
 		inputSchema,
 		schemaHash: schemaHash(inputSchema),
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function codeModeCapletExport(entry) {
@@ -10674,7 +10678,7 @@ function codeModeCapletExport(entry) {
 		description: entry.caplet.description,
 		schemaHash: null,
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function toolExport(entry) {
@@ -10693,7 +10697,7 @@ function toolExport(entry) {
 			output: entry.tool.outputSchema
 		}),
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function resourceExport(entry) {
@@ -10708,7 +10712,7 @@ function resourceExport(entry) {
 		...typeof entry.resource.size === "number" ? { size: entry.resource.size } : {},
 		schemaHash: null,
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function resourceTemplateExport(entry) {
@@ -10722,7 +10726,7 @@ function resourceTemplateExport(entry) {
 		...entry.resourceTemplate.mimeType ? { mimeType: entry.resourceTemplate.mimeType } : {},
 		schemaHash: null,
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function promptExport(entry) {
@@ -10737,11 +10741,11 @@ function promptExport(entry) {
 		inputSchema,
 		schemaHash: schemaHash(inputSchema),
 		capletId: entry.caplet.server,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(entry.caplet)
 	};
 }
 function completionExports(snapshot) {
-	return [...new Set([...snapshot.directPrompts.map((entry) => entry.caplet.server), ...snapshot.directResourceTemplates.map((entry) => entry.caplet.server)])].sort().map((capletId) => ({
+	return [...new Map([...snapshot.directPrompts, ...snapshot.directResourceTemplates].map((entry) => [entry.caplet.server, entry.caplet])).entries()].sort(([left], [right]) => left.localeCompare(right)).map(([capletId, caplet]) => ({
 		stableId: `completion:${capletId}`,
 		kind: "completion",
 		name: `${capletId}:complete`,
@@ -10749,9 +10753,12 @@ function completionExports(snapshot) {
 		description: `MCP completion for ${capletId}.`,
 		schemaHash: null,
 		capletId,
-		shadowing: "forbid"
+		shadowing: shadowingPolicy(caplet)
 	}));
 }
+function shadowingPolicy(caplet) {
+	return caplet.shadowing ?? "forbid";
+}
 function sortAttachProjectionInput(partial) {
 	return {
 		caplets: sortByStableId(partial.caplets),
@@ -11720,6 +11727,8 @@ async function attachResolvedCaplets(options, io = {}) {
 function createAttachNativeService(options, io) {
 	return createNativeCapletsService({
 		mode: options.selection.kind === "hosted_cloud" ? "cloud" : "remote",
+		configPath: options.configPath,
+		projectConfigPath: options.projectConfigPath,
 		server: {
 			url: options.selection.remote.baseUrl.toString(),
 			...options.selection.remote.fetch ? { fetch: options.selection.remote.fetch } : {}

package/dist/native/remote.d.ts

@@ -5,6 +5,7 @@ export type RemoteCapletsTool = {
     name: string;
     capletId?: string | undefined;
     sourceCapletId?: string | undefined;
+    shadowing?: "forbid" | "allow" | undefined;
     title?: string | undefined;
     description?: string | undefined;
     inputSchema?: unknown;

package/dist/native/service.d.ts

@@ -17,6 +17,7 @@ export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput &
 export type NativeCapletTool = {
     caplet: string;
     sourceCaplet?: string;
+    shadowing?: "forbid" | "allow";
     toolName: string;
     title: string;
     description: string;

package/dist/native.js

@@ -1,4 +1,4 @@
-import { C as nativeCapletPromptGuidance, D as nativeCodeModeToolId, E as nativeCapletsSystemGuidance, O as nativeCodeModeToolName, T as nativeCapletToolName, f as RemoteNativeCapletsService, h as resolveNativeCapletsServiceOptions, p as createSdkRemoteCapletsClient, t as createNativeCapletsService, w as nativeCapletToolDescription } from "./service-Bs7l5haO.js";
+import { C as nativeCapletPromptGuidance, D as nativeCodeModeToolId, E as nativeCapletsSystemGuidance, O as nativeCodeModeToolName, T as nativeCapletToolName, f as RemoteNativeCapletsService, h as resolveNativeCapletsServiceOptions, p as createSdkRemoteCapletsClient, t as createNativeCapletsService, w as nativeCapletToolDescription } from "./service-4_chB2wu.js";
 import { generatedToolInputJsonSchema, generatedToolInputSchema } from "./generated-tool-input-schema.js";
 //#region src/native/process-cleanup.ts
 function registerNativeCapletsProcessCleanup(service, options = {}) {

package/dist/{service-Bs7l5haO.js → service-4_chB2wu.js}

@@ -25967,6 +25967,7 @@ const capletExposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]).describe("How this Caplet is exposed to agents.");
+const capletShadowingSchema = _enum(["forbid", "allow"]).describe("Whether attached local Caplets may shadow this remote Caplet ID.");
 const capletEndpointAuthSchema = discriminatedUnion("type", [
 	object$1({ type: literal("none") }).strict(),
 	object$1({
@@ -26247,6 +26248,7 @@ const capletFileSchema = object$1({
 	description: string().describe("Compact capability description shown before the full Caplet card is disclosed.").refine((value) => value.trim().length >= 10, "description must contain at least 10 non-whitespace characters").refine((value) => value.length <= 1500, "description must be at most 1500 characters"),
 	tags: array(string().trim().min(1).max(80)).optional().describe("Optional tags for grouping or searching Caplets."),
 	exposure: capletExposureSchema.optional(),
+	shadowing: capletShadowingSchema.optional(),
 	...capletAgentSelectionHintsSchema,
 	setup: capletSetupSchema.optional(),
 	projectBinding: capletProjectBindingSchema.optional(),
@@ -26444,6 +26446,7 @@ function sharedCapletFields(frontmatter) {
 	return {
 		...frontmatter.tags ? { tags: frontmatter.tags } : {},
 		...frontmatter.exposure ? { exposure: frontmatter.exposure } : {},
+		...frontmatter.shadowing ? { shadowing: frontmatter.shadowing } : {},
 		...frontmatter.useWhen ? { useWhen: frontmatter.useWhen } : {},
 		...frontmatter.avoidWhen ? { avoidWhen: frontmatter.avoidWhen } : {},
 		...frontmatter.setup ? { setup: frontmatter.setup } : {},
@@ -26794,6 +26797,7 @@ const exposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]).describe("How this Caplet is exposed to agents.");
+const shadowingSchema = _enum(["forbid", "allow"]).default("forbid").describe("Whether attached local Caplets may shadow this remote Caplet ID.");
 const publicServerSchema = object$1({
 	name: string().trim().min(1).max(80).describe("Human-readable server display name."),
 	description: string().describe("Capability description shown to agents before downstream tools are disclosed.").refine((value) => value.trim().length >= 10, "description must contain at least 10 non-whitespace characters").refine((value) => value.length <= 1500, "description must be at most 1500 characters"),
@@ -26810,6 +26814,7 @@ const publicServerSchema = object$1({
 	auth: remoteAuthSchema.optional(),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -26829,6 +26834,7 @@ const publicOpenApiEndpointSchema = object$1({
 	auth: openApiAuthSchema.describe("Explicit OpenAPI request auth config. Use {\"type\":\"none\"} for public APIs."),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -26861,6 +26867,7 @@ const publicGraphQlEndpointSchema = object$1({
 	auth: openApiAuthSchema.describe("Explicit GraphQL request auth config. Use {\"type\":\"none\"} for public APIs."),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -26912,6 +26919,7 @@ const publicHttpApiSchema = object$1({
 	actions: record(string().regex(SERVER_ID_PATTERN), httpActionSchema).refine((actions) => Object.keys(actions).length > 0, "HTTP API must define at least one action").describe("Configured HTTP actions keyed by stable tool name."),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -26950,6 +26958,7 @@ const publicCliToolsSchema = object$1({
 	env: record(string(), string()).optional().describe("Default environment variables for CLI actions."),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -26969,6 +26978,7 @@ const publicCapletSetSchema = object$1({
 	toolCacheTtlMs: number$1().int().nonnegative().default(3e4).describe("Milliseconds child Caplet metadata stays fresh. Set 0 to refresh every time."),
 	tags: array(string().trim().min(1).max(80)).optional(),
 	exposure: exposureSchema.optional(),
+	shadowing: shadowingSchema,
 	...agentSelectionHintsSchema,
 	setup: setupSchema.optional(),
 	projectBinding: projectBindingSchema.optional(),
@@ -61896,7 +61906,7 @@ var CapletsEngine = class {
 		}
 	}
 	async completeCliWords(words) {
-		const { completeCliWords } = await import("./completion-GTIuH0CW.js").then((n) => n.r);
+		const { completeCliWords } = await import("./completion-DnQujlrc.js").then((n) => n.r);
 		return await completeCliWords(words, {
 			config: this.registry.config,
 			managers: {
@@ -76978,6 +76988,7 @@ function remoteToolToNativeTool(tool) {
 	return {
 		caplet: capletId,
 		...sourceCaplet && sourceCaplet !== capletId ? { sourceCaplet } : {},
+		...tool.shadowing ? { shadowing: tool.shadowing } : {},
 		toolName,
 		title: tool.title ?? capletId,
 		description: [
@@ -76991,7 +77002,8 @@ function remoteToolToNativeTool(tool) {
 		...tool.codeModeCaplets ? { codeModeCaplets: tool.codeModeCaplets.map((caplet) => ({
 			id: caplet.capletId,
 			name: caplet.name,
-			description: caplet.description ?? ""
+			description: caplet.description ?? "",
+			shadowing: caplet.shadowing
 		})) } : {},
 		inputSchema,
 		...isPlainObject(tool.outputSchema) ? { outputSchema: tool.outputSchema } : {},
@@ -77125,6 +77137,7 @@ function primitiveInvokeInput(capletId, operation, input) {
 }
 function toolsFromManifest(manifest) {
 	const codeModeMarker = attachCodeModeMarker(manifest);
+	const codeModeShadowing = manifest.codeModeCaplets.some((entry) => entry.shadowing === "forbid") ? "forbid" : "allow";
 	return [
 		...manifest.caplets.map((entry) => ({
 			name: entry.capletId,
@@ -77132,6 +77145,7 @@ function toolsFromManifest(manifest) {
 			title: entry.title ?? entry.name,
 			description: entry.description,
 			inputSchema: entry.inputSchema,
+			shadowing: entry.shadowing,
 			...codeModeMarker
 		})),
 		...manifest.tools.map((entry) => ({
@@ -77143,6 +77157,7 @@ function toolsFromManifest(manifest) {
 			inputSchema: entry.inputSchema,
 			outputSchema: entry.outputSchema,
 			annotations: entry.annotations,
+			shadowing: entry.shadowing,
 			...codeModeMarker
 		})),
 		...primitiveToolsFromManifest(manifest, codeModeMarker),
@@ -77153,6 +77168,7 @@ function toolsFromManifest(manifest) {
 			description: "Remote Caplets available to locally-run attached Code Mode.",
 			codeModeRun: true,
 			codeModeCaplets: manifest.codeModeCaplets,
+			shadowing: codeModeShadowing,
 			inputSchema: codeModeRunInputJsonSchema()
 		}] : []
 	];
@@ -77163,46 +77179,50 @@ function attachCodeModeMarker(manifest) {
 function primitiveToolsFromManifest(manifest, codeModeMarker) {
 	const directToolNames = new Set(manifest.tools.map((entry) => entry.name));
 	const byCaplet = /* @__PURE__ */ new Map();
-	const entryFor = (capletId) => {
+	const entryFor = (capletId, shadowing) => {
 		const existing = byCaplet.get(capletId);
-		if (existing) return existing;
+		if (existing) {
+			if (shadowing === "forbid") existing.shadowing = "forbid";
+			return existing;
+		}
 		const next = {
 			resources: false,
 			resourceTemplates: false,
 			prompts: false,
-			completions: false
+			completions: false,
+			shadowing
 		};
 		byCaplet.set(capletId, next);
 		return next;
 	};
-	for (const entry of manifest.resources) entryFor(entry.capletId).resources = true;
-	for (const entry of manifest.resourceTemplates) entryFor(entry.capletId).resourceTemplates = true;
-	for (const entry of manifest.prompts) entryFor(entry.capletId).prompts = true;
-	for (const entry of manifest.completions) entryFor(entry.capletId).completions = true;
+	for (const entry of manifest.resources) entryFor(entry.capletId, entry.shadowing).resources = true;
+	for (const entry of manifest.resourceTemplates) entryFor(entry.capletId, entry.shadowing).resourceTemplates = true;
+	for (const entry of manifest.prompts) entryFor(entry.capletId, entry.shadowing).prompts = true;
+	for (const entry of manifest.completions) entryFor(entry.capletId, entry.shadowing).completions = true;
 	const tools = [];
-	const addPrimitiveTool = (capletId, operation) => {
+	const addPrimitiveTool = (capletId, operation, shadowing) => {
 		const name = `${capletId}__${operation}`;
 		if (directToolNames.has(name)) return;
-		tools.push(primitiveTool(capletId, operation, codeModeMarker));
+		tools.push(primitiveTool(capletId, operation, shadowing, codeModeMarker));
 	};
 	for (const [capletId, flags] of byCaplet) {
 		if (flags.resources) {
-			addPrimitiveTool(capletId, "list_resources");
-			addPrimitiveTool(capletId, "read_resource");
+			addPrimitiveTool(capletId, "list_resources", flags.shadowing);
+			addPrimitiveTool(capletId, "read_resource", flags.shadowing);
 		}
 		if (flags.resourceTemplates) {
-			addPrimitiveTool(capletId, "list_resource_templates");
-			addPrimitiveTool(capletId, "read_resource");
+			addPrimitiveTool(capletId, "list_resource_templates", flags.shadowing);
+			addPrimitiveTool(capletId, "read_resource", flags.shadowing);
 		}
 		if (flags.prompts) {
-			addPrimitiveTool(capletId, "list_prompts");
-			addPrimitiveTool(capletId, "get_prompt");
+			addPrimitiveTool(capletId, "list_prompts", flags.shadowing);
+			addPrimitiveTool(capletId, "get_prompt", flags.shadowing);
 		}
-		if (flags.completions) addPrimitiveTool(capletId, "complete");
+		if (flags.completions) addPrimitiveTool(capletId, "complete", flags.shadowing);
 	}
 	return [...new Map(tools.map((tool) => [tool.name, tool])).values()];
 }
-function primitiveTool(capletId, operation, codeModeMarker) {
+function primitiveTool(capletId, operation, shadowing, codeModeMarker) {
 	return {
 		name: `${capletId}__${operation}`,
 		capletId,
@@ -77210,6 +77230,7 @@ function primitiveTool(capletId, operation, codeModeMarker) {
 		title: operation,
 		description: `MCP ${operation.replace(/_/g, " ")}.`,
 		inputSchema: primitiveInputSchema(operation),
+		shadowing,
 		...codeModeMarker
 	};
 }
@@ -77902,6 +77923,7 @@ var DefaultNativeCapletsService = class {
 		});
 		return {
 			caplet: routeId,
+			sourceCaplet: caplet.server,
 			toolName,
 			title: operationName,
 			description: options.description ?? "",
@@ -78069,6 +78091,7 @@ function codeModeRunNativeTool(capletTools) {
 		id: tool.caplet,
 		name: tool.title,
 		description: tool.description,
+		...tool.shadowing ? { shadowing: tool.shadowing } : {},
 		...tool.useWhen ? { useWhen: tool.useWhen } : {},
 		...tool.avoidWhen ? { avoidWhen: tool.avoidWhen } : {}
 	}));
@@ -78103,6 +78126,7 @@ function codeModeCallableNativeTools(tools, options) {
 			toolName: tool?.toolName ?? nativeCapletToolName(caplet.id),
 			title: caplet.name,
 			description: caplet.description,
+			...caplet.shadowing ? { shadowing: caplet.shadowing } : {},
 			...caplet.useWhen ? { useWhen: caplet.useWhen } : {},
 			...caplet.avoidWhen ? { avoidWhen: caplet.avoidWhen } : {},
 			promptGuidance: tool?.promptGuidance ?? []
@@ -78275,9 +78299,7 @@ var CompositeNativeCapletsService = class {
 	}
 	async execute(capletId, request) {
 		if (capletId === "code_mode") return await executeCodeModeRunNative(this, request);
-		const localHasCaplet = this.local.listTools().some((tool) => tool.caplet === capletId);
-		const remoteHasCaplet = serviceHasCaplet(this.remote, capletId);
-		if (localHasCaplet && !remoteHasCaplet) return await this.local.execute(capletId, request);
+		if (this.localCanExecute(capletId)) return await this.local.execute(capletId, request);
 		return await this.remote.execute(capletId, request);
 	}
 	async reload() {
@@ -78320,8 +78342,8 @@ var CompositeNativeCapletsService = class {
 	mergeTools() {
 		const allLocalTools = this.local.listTools();
 		const allRemoteTools = this.remote.listTools();
-		const remoteCodeModeTools = codeModeCallableNativeTools(allRemoteTools, { fallbackToVisible: true });
-		const remoteIds = new Set([...allRemoteTools.filter((tool) => tool.codeModeRun !== true).map((tool) => tool.sourceCaplet ?? tool.caplet), ...remoteCodeModeTools.map((tool) => tool.caplet)].filter((caplet) => caplet !== nativeCodeModeToolId));
+		const remoteCodeModeTools = remoteCodeModeCallableNativeTools(allRemoteTools);
+		const remoteIds = remoteSuppressedCapletIds(allRemoteTools, remoteCodeModeTools);
 		const localTools = allLocalTools.filter((tool) => tool.codeModeRun !== true && !remoteIds.has(tool.sourceCaplet ?? tool.caplet));
 		this.warnShadowedLocalCaplets(allLocalTools, remoteIds);
 		const localCodeModeTools = codeModeCallableNativeTools(allLocalTools, { fallbackToVisible: false }).filter((tool) => !remoteIds.has(tool.caplet));
@@ -78329,6 +78351,10 @@ var CompositeNativeCapletsService = class {
 		const codeModeTools = [...remoteCodeModeTools, ...localCodeModeTools];
 		return [...mergedTools, ...codeModeTools.length > 0 ? [codeModeRunNativeTool(codeModeTools)] : []];
 	}
+	localCanExecute(capletId) {
+		const remoteIds = remoteSuppressedCapletIds(this.remote.listTools());
+		return localExecutionKeys(this.local.listTools(), capletId).some((key) => !remoteIds.has(key));
+	}
 	warnShadowedLocalCaplets(localTools, remoteIds) {
 		const localIds = new Set([...localTools.filter((tool) => tool.codeModeRun !== true).map((tool) => tool.sourceCaplet ?? tool.caplet), ...codeModeCallableNativeTools(localTools, { fallbackToVisible: false }).map((tool) => tool.caplet)]);
 		for (const capletId of localIds) {
@@ -78347,11 +78373,22 @@ var CompositeNativeCapletsService = class {
 		}
 	}
 };
-function serviceHasCaplet(service, capletId) {
-	return service.listTools().some((tool) => {
-		if (tool.codeModeRun) return tool.codeModeCaplets?.some((caplet) => caplet.id === capletId) ?? false;
-		return tool.caplet === capletId;
-	});
+function remoteCodeModeCallableNativeTools(tools) {
+	return codeModeCallableNativeTools(tools, { fallbackToVisible: true });
+}
+function remoteSuppressedCapletIds(allRemoteTools, remoteCodeModeTools = remoteCodeModeCallableNativeTools(allRemoteTools)) {
+	return new Set([...allRemoteTools.filter((tool) => tool.codeModeRun !== true && tool.shadowing !== "allow").map((tool) => tool.sourceCaplet ?? tool.caplet), ...remoteCodeModeTools.filter((tool) => tool.shadowing !== "allow").map((tool) => tool.caplet)].filter((caplet) => caplet !== nativeCodeModeToolId));
+}
+function localExecutionKeys(tools, capletId) {
+	const keys = [];
+	for (const tool of tools) {
+		if (tool.codeModeRun) {
+			for (const caplet of tool.codeModeCaplets ?? []) if (caplet.id === capletId) keys.push(caplet.id);
+			continue;
+		}
+		if (tool.caplet === capletId || tool.sourceCaplet === capletId) keys.push(tool.sourceCaplet ?? tool.caplet);
+	}
+	return keys;
 }
 function createProjectBindingSessionManager(cloud, local, options) {
 	if (!cloud) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Core runtime library for Caplets Code Mode and progressive disclosure gateways.",
   "keywords": [
     "caplets",