@caplets/core 0.26.1 → 0.27.0

package/dist/attach/api.d.ts

@@ -1,4 +1,5 @@
 import type { CapletsEngine } from "../engine";
+import type { CapletShadowingPolicy } from "../config";
 export type AttachExportKind = "caplet" | "tool" | "resource" | "resourceTemplate" | "prompt" | "completion";
 export type AttachInvokeRequest = {
     revision: string;
@@ -26,7 +27,7 @@ export type AttachManifestExport = {
     annotations?: unknown;
     schemaHash: string | null;
     capletId: string;
-    shadowing: "forbid" | "allow";
+    shadowing: CapletShadowingPolicy;
 };
 export type AttachProgressiveCapletExport = AttachManifestExport & {
     kind: "caplet";

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

@@ -454,6 +454,7 @@ export declare const capletFileSchema: z.ZodObject<{
     shadowing: z.ZodOptional<z.ZodEnum<{
         forbid: "forbid";
         allow: "allow";
+        namespace: "namespace";
     }>>;
 }, z.core.$strict>;
 export declare function capletJsonSchema(): unknown;

package/dist/caplet-source.js

@@ -10031,6 +10031,7 @@ function superRefine(fn, params) {
 //#endregion
 //#region src/config/validation.ts
 const SERVER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const NAMESPACE_ALIAS_LABEL_PATTERN = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
 const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const HTTP_BASE_URL_PATTERN = /^(?![a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*@)[^?#]*$/;
 const FORBIDDEN_HEADERS = /* @__PURE__ */ new Set([
@@ -10169,7 +10170,11 @@ 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 capletShadowingSchema = _enum([
+	"forbid",
+	"allow",
+	"namespace"
+]).describe("Whether attached local Caplets may shadow this remote Caplet ID.");
 const capletEndpointAuthSchema = discriminatedUnion("type", [
 	object({ type: literal("none") }).strict(),
 	object({
@@ -10849,7 +10854,11 @@ const exposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]);
-const shadowingSchema = _enum(["forbid", "allow"]).default("forbid");
+const shadowingSchema = _enum([
+	"forbid",
+	"allow",
+	"namespace"
+]).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"),
@@ -10988,6 +10997,28 @@ const capletSetSchema = object({
 	maxSearchLimit: number().int().positive().max(50).default(50),
 	toolCacheTtlMs: number().int().nonnegative().default(3e4)
 }).strict();
+const namespaceAliasLabelSchema = string().regex(NAMESPACE_ALIAS_LABEL_PATTERN, "namespace alias labels must be lowercase DNS-style labels using letters, numbers, or hyphens");
+const namespaceAliasesSchema = object({
+	local: namespaceAliasLabelSchema.optional(),
+	upstreams: record(string().trim().min(1), namespaceAliasLabelSchema).default({})
+}).strict().default({ upstreams: {} }).superRefine((aliases, ctx) => {
+	const seen = /* @__PURE__ */ new Map();
+	const addAlias = (value, path) => {
+		if (!value) return;
+		const existing = seen.get(value);
+		if (existing) {
+			ctx.addIssue({
+				code: "custom",
+				path,
+				message: `namespace alias '${value}' is already used at ${existing.join(".")}`
+			});
+			return;
+		}
+		seen.set(value, path);
+	};
+	addAlias(aliases.local, ["local"]);
+	for (const [selector, alias] of Object.entries(aliases.upstreams)) addAlias(alias, ["upstreams", selector]);
+});
 const configSchema = object({
 	version: literal(1).default(1),
 	defaultSearchLimit: number().int().positive().default(20),
@@ -11018,7 +11049,8 @@ const configSchema = object({
 	graphqlEndpoints: record(string().regex(SERVER_ID_PATTERN), graphQlEndpointSchema).default({}),
 	httpApis: record(string().regex(SERVER_ID_PATTERN), httpApiSchema).default({}),
 	cliTools: record(string().regex(SERVER_ID_PATTERN), cliToolsSchema).default({}),
-	capletSets: record(string().regex(SERVER_ID_PATTERN), capletSetSchema).default({})
+	capletSets: record(string().regex(SERVER_ID_PATTERN), capletSetSchema).default({}),
+	namespaceAliases: namespaceAliasesSchema
 }).strict().superRefine((config, ctx) => {
 	if (config.defaultSearchLimit > config.maxSearchLimit) ctx.addIssue({
 		code: "custom",
@@ -11041,6 +11073,10 @@ function parseConfig(input) {
 			exposureDiscoveryConcurrency: config.options.exposureDiscoveryConcurrency,
 			completion: config.completion
 		},
+		namespaceAliases: stripUndefined({
+			local: config.namespaceAliases.local,
+			upstreams: config.namespaceAliases.upstreams
+		}),
 		mcpServers: mapBackend(config.mcpServers, "mcp", (id, raw) => {
 			const server = raw;
 			return {

package/dist/cli/inspection.d.ts

@@ -1,4 +1,4 @@
-import { type CapletConfig, type ConfigSource, type ConfigWithSources } from "../config";
+import { type CapletConfig, type CapletShadowingPolicy, type ConfigSource, type ConfigWithSources } from "../config";
 import type { ServerStatus } from "../registry";
 type CapletListRow = {
     server: string;
@@ -10,6 +10,7 @@ type CapletListRow = {
     source: ConfigSource["kind"] | "remote" | "unknown";
     path: string | null;
     shadows: ConfigSource[];
+    shadowing?: CapletShadowingPolicy | undefined;
 };
 type ConfigPaths = {
     userConfig: string;

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

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

package/dist/{completion-CFOJucl5.js → completion-1wDjwHkC.js}

@@ -1,5 +1,5 @@
-import { Hn as __exportAll, It as DEFAULT_AUTH_DIR, Kt as resolveProjectConfigPath, Lt as DEFAULT_COMPLETION_CACHE_DIR, Ut as resolveCapletsRoot, Wt as resolveConfigPath, lt as loadConfigWithSources } from "./service-aBIn4nrw.js";
-import { u as CapletsError } from "./validation-GD2x5HW1.js";
+import { Hn as __exportAll, It as DEFAULT_AUTH_DIR, Kt as resolveProjectConfigPath, Lt as DEFAULT_COMPLETION_CACHE_DIR, Ut as resolveCapletsRoot, Wt as resolveConfigPath, lt as loadConfigWithSources } from "./service-BGGiZLHa.js";
+import { d as CapletsError } from "./validation-CWzd2gtn.js";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createHash } from "node:crypto";
@@ -165,7 +165,8 @@ function listCaplets(configWithSources, options) {
 		status: initialServerStatus(server),
 		source: sources[server.server]?.kind ?? "unknown",
 		path: sources[server.server]?.path ?? null,
-		shadows: shadows[server.server] ?? []
+		shadows: shadows[server.server] ?? [],
+		shadowing: server.shadowing
 	})).sort((left, right) => left.server.localeCompare(right.server));
 }
 function initialServerStatus(server) {

package/dist/config/validation.d.ts

@@ -1,4 +1,5 @@
 export declare const SERVER_ID_PATTERN: RegExp;
+export declare const NAMESPACE_ALIAS_LABEL_PATTERN: RegExp;
 export declare const HEADER_NAME_PATTERN: RegExp;
 export declare const HTTP_BASE_URL_PATTERN: RegExp;
 export declare const FORBIDDEN_HEADERS: Set<string>;
@@ -10,6 +11,7 @@ type ValidationIssueSink = {
     }): void;
 };
 export declare function validateHttpActionHeaders(headers: Record<string, unknown>, ctx: ValidationIssueSink, path: Array<string>): void;
+export declare function isValidNamespaceAliasLabel(value: string): boolean;
 export declare function isAllowedRemoteUrl(value: string): boolean;
 export declare function isAllowedHttpBaseUrl(value: string): boolean;
 export declare function isUrl(value: string): boolean;

package/dist/config-runtime.d.ts

@@ -49,7 +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 CapletShadowingPolicy = "forbid" | "allow" | "namespace";
 export type CapletServerConfig = CommonCapletConfig & {
     backend: "mcp";
     transport: "stdio" | "http" | "sse";
@@ -157,6 +157,10 @@ export type CapletSetConfig = CommonCapletConfig & {
     toolCacheTtlMs: number;
 };
 export type CapletConfig = CapletServerConfig | OpenApiEndpointConfig | GoogleDiscoveryApiConfig | GraphQlEndpointConfig | HttpApiConfig | CliToolsConfig | CapletSetConfig;
+export type NamespaceAliasesConfig = {
+    local?: string | undefined;
+    upstreams: Record<string, string>;
+};
 export type CapletsConfig = {
     version: 1;
     options: {
@@ -172,6 +176,7 @@ export type CapletsConfig = {
             negativeCacheTtlMs: number;
         };
     };
+    namespaceAliases: NamespaceAliasesConfig;
     mcpServers: Record<string, CapletServerConfig>;
     openapiEndpoints: Record<string, OpenApiEndpointConfig>;
     googleDiscoveryApis: Record<string, GoogleDiscoveryApiConfig>;

package/dist/config-runtime.js

@@ -1,5 +1,5 @@
 import { _ as record, b as unknown, d as literal, l as discriminatedUnion, m as object, o as array, p as number, r as _enum, s as boolean, v as string, y as union } from "./schemas-BoqMu4MG.js";
-import { a as isAllowedHttpBaseUrl, c as validateHttpActionHeaders, i as SERVER_ID_PATTERN, n as HEADER_NAME_PATTERN, o as isAllowedRemoteUrl, r as HTTP_BASE_URL_PATTERN, s as isUrl, t as FORBIDDEN_HEADERS, u as CapletsError } from "./validation-GD2x5HW1.js";
+import { a as SERVER_ID_PATTERN, c as isUrl, d as CapletsError, i as NAMESPACE_ALIAS_LABEL_PATTERN, l as validateHttpActionHeaders, n as HEADER_NAME_PATTERN, o as isAllowedHttpBaseUrl, r as HTTP_BASE_URL_PATTERN, s as isAllowedRemoteUrl, t as FORBIDDEN_HEADERS } from "./validation-CWzd2gtn.js";
 //#region src/config-runtime.ts
 const stringMapSchema = record(string(), string());
 const authSchema = discriminatedUnion("type", [
@@ -49,7 +49,11 @@ const exposureSchema = _enum([
 	"direct_and_code_mode",
 	"progressive_and_code_mode"
 ]);
-const shadowingSchema = _enum(["forbid", "allow"]).default("forbid");
+const shadowingSchema = _enum([
+	"forbid",
+	"allow",
+	"namespace"
+]).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"),
@@ -188,6 +192,28 @@ const capletSetSchema = object({
 	maxSearchLimit: number().int().positive().max(50).default(50),
 	toolCacheTtlMs: number().int().nonnegative().default(3e4)
 }).strict();
+const namespaceAliasLabelSchema = string().regex(NAMESPACE_ALIAS_LABEL_PATTERN, "namespace alias labels must be lowercase DNS-style labels using letters, numbers, or hyphens");
+const namespaceAliasesSchema = object({
+	local: namespaceAliasLabelSchema.optional(),
+	upstreams: record(string().trim().min(1), namespaceAliasLabelSchema).default({})
+}).strict().default({ upstreams: {} }).superRefine((aliases, ctx) => {
+	const seen = /* @__PURE__ */ new Map();
+	const addAlias = (value, path) => {
+		if (!value) return;
+		const existing = seen.get(value);
+		if (existing) {
+			ctx.addIssue({
+				code: "custom",
+				path,
+				message: `namespace alias '${value}' is already used at ${existing.join(".")}`
+			});
+			return;
+		}
+		seen.set(value, path);
+	};
+	addAlias(aliases.local, ["local"]);
+	for (const [selector, alias] of Object.entries(aliases.upstreams)) addAlias(alias, ["upstreams", selector]);
+});
 const configSchema = object({
 	version: literal(1).default(1),
 	defaultSearchLimit: number().int().positive().default(20),
@@ -218,7 +244,8 @@ const configSchema = object({
 	graphqlEndpoints: record(string().regex(SERVER_ID_PATTERN), graphQlEndpointSchema).default({}),
 	httpApis: record(string().regex(SERVER_ID_PATTERN), httpApiSchema).default({}),
 	cliTools: record(string().regex(SERVER_ID_PATTERN), cliToolsSchema).default({}),
-	capletSets: record(string().regex(SERVER_ID_PATTERN), capletSetSchema).default({})
+	capletSets: record(string().regex(SERVER_ID_PATTERN), capletSetSchema).default({}),
+	namespaceAliases: namespaceAliasesSchema
 }).strict().superRefine((config, ctx) => {
 	if (config.defaultSearchLimit > config.maxSearchLimit) ctx.addIssue({
 		code: "custom",
@@ -241,6 +268,10 @@ function parseConfig(input) {
 			exposureDiscoveryConcurrency: config.options.exposureDiscoveryConcurrency,
 			completion: config.completion
 		},
+		namespaceAliases: stripUndefined({
+			local: config.namespaceAliases.local,
+			upstreams: config.namespaceAliases.upstreams
+		}),
 		mcpServers: mapBackend(config.mcpServers, "mcp", (id, raw) => {
 			const server = raw;
 			return {

package/dist/config.d.ts

@@ -64,7 +64,7 @@ export type AgentSelectionHintsConfig = {
     useWhen?: string | undefined;
     avoidWhen?: string | undefined;
 };
-export type CapletShadowingPolicy = "forbid" | "allow";
+export type CapletShadowingPolicy = "forbid" | "allow" | "namespace";
 export type CapletExposure = "direct" | "progressive" | "code_mode" | "direct_and_code_mode" | "progressive_and_code_mode";
 export type CapletServerConfig = AgentSelectionHintsConfig & {
     server: string;
@@ -261,6 +261,10 @@ export type CapletSetConfig = AgentSelectionHintsConfig & {
     runtime?: RuntimeRequirementsConfig | undefined;
 };
 export type CapletConfig = CapletServerConfig | OpenApiEndpointConfig | GoogleDiscoveryApiConfig | GraphQlEndpointConfig | HttpApiConfig | CliToolsConfig | CapletSetConfig;
+export type NamespaceAliasesConfig = {
+    local?: string | undefined;
+    upstreams: Record<string, string>;
+};
 export type CapletsOptions = {
     defaultSearchLimit: number;
     maxSearchLimit: number;
@@ -278,6 +282,7 @@ export type CompletionConfig = {
 export type CapletsConfig = {
     version: 1;
     options: CapletsOptions;
+    namespaceAliases: NamespaceAliasesConfig;
     mcpServers: Record<string, CapletServerConfig>;
     openapiEndpoints: Record<string, OpenApiEndpointConfig>;
     googleDiscoveryApis: Record<string, GoogleDiscoveryApiConfig>;
@@ -350,6 +355,10 @@ export declare const configFileSchema: z.ZodObject<{
         exposureDiscoveryTimeoutMs: z.ZodDefault<z.ZodNumber>;
         exposureDiscoveryConcurrency: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
+    namespaceAliases: z.ZodDefault<z.ZodObject<{
+        local: z.ZodOptional<z.ZodString>;
+        upstreams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, 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>>>>;
     googleDiscoveryApis: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const CAPLETS_ERROR_CODES: readonly ["CONFIG_NOT_FOUND", "CONFIG_EXISTS", "CONFIG_INVALID", "REQUEST_INVALID", "SERVER_NOT_FOUND", "SERVER_UNAVAILABLE", "SERVER_START_TIMEOUT", "UNKNOWN_OPERATION", "TOOL_NOT_FOUND", "TOOL_CALL_TIMEOUT", "AUTH_REQUIRED", "AUTH_FAILED", "REMOTE_CREDENTIALS_REVOKED", "AUTH_REFRESH_FAILED", "DOWNSTREAM_PROTOCOL_ERROR", "DOWNSTREAM_TOOL_ERROR", "UNSUPPORTED_OPERATION", "UNSUPPORTED_CAPABILITY", "PROMPT_NOT_FOUND", "DOWNSTREAM_RESOURCE_ERROR", "DOWNSTREAM_PROMPT_ERROR", "DOWNSTREAM_COMPLETION_ERROR", "ATTACH_MANIFEST_STALE", "ATTACH_EXPORT_NOT_FOUND", "UNSUPPORTED_TRANSPORT", "INTERNAL_ERROR"];
+export declare const CAPLETS_ERROR_CODES: readonly ["CONFIG_NOT_FOUND", "CONFIG_EXISTS", "CONFIG_INVALID", "REQUEST_INVALID", "SERVER_NOT_FOUND", "SERVER_UNAVAILABLE", "SERVER_START_TIMEOUT", "UNKNOWN_OPERATION", "CAPLET_NAMESPACE_COLLISION", "TOOL_NOT_FOUND", "TOOL_CALL_TIMEOUT", "AUTH_REQUIRED", "AUTH_FAILED", "REMOTE_CREDENTIALS_REVOKED", "AUTH_REFRESH_FAILED", "DOWNSTREAM_PROTOCOL_ERROR", "DOWNSTREAM_TOOL_ERROR", "UNSUPPORTED_OPERATION", "UNSUPPORTED_CAPABILITY", "PROMPT_NOT_FOUND", "DOWNSTREAM_RESOURCE_ERROR", "DOWNSTREAM_PROMPT_ERROR", "DOWNSTREAM_COMPLETION_ERROR", "ATTACH_MANIFEST_STALE", "ATTACH_EXPORT_NOT_FOUND", "UNSUPPORTED_TRANSPORT", "INTERNAL_ERROR"];
 export type CapletsErrorCode = (typeof CAPLETS_ERROR_CODES)[number];
 export type SafeErrorSummary = {
     code: CapletsErrorCode;

package/dist/exposure/namespace.d.ts

@@ -0,0 +1,39 @@
+import type { CapletShadowingPolicy } from "../config";
+export type NamespaceSourceKind = "local" | "upstream";
+export type NamespaceDiagnosticReason = "namespace_collision" | "missing_durable_source_identity" | "namespace_alias_invalid" | "generated_id_collision" | "unsupported_protocol";
+export type NamespaceSourceEntry<Route = unknown> = {
+    baseId: string;
+    sourceKind: NamespaceSourceKind;
+    sourceLabel?: string | undefined;
+    namespaceAlias?: string | undefined;
+    durableSourceIdentity?: string | undefined;
+    shadowing: CapletShadowingPolicy;
+    route: Route;
+};
+export type NamespaceVisibleRecord<Route = unknown> = NamespaceSourceEntry<Route> & {
+    id: string;
+    label: string;
+    namespaced: boolean;
+};
+export type NamespaceDiagnostic = {
+    requestedId: string;
+    reason: NamespaceDiagnosticReason;
+    alternatives: string[];
+    sources: Array<{
+        sourceKind: NamespaceSourceKind;
+        label: string;
+        durableSourceIdentity?: string | undefined;
+    }>;
+    hint: string;
+};
+export type NamespaceResolution<Route = unknown> = {
+    visibleRecords: NamespaceVisibleRecord<Route>[];
+    routes: Map<string, Route>;
+    suppressedBareIds: Map<string, NamespaceDiagnostic>;
+    unavailableDiagnostics: NamespaceDiagnostic[];
+};
+export type NamespaceResolutionOptions = {
+    hashLength?: number | undefined;
+    maxHashLength?: number | undefined;
+};
+export declare function resolveNamespaceExposure<Route>(entries: NamespaceSourceEntry<Route>[], options?: NamespaceResolutionOptions): NamespaceResolution<Route>;

package/dist/index.js

@@ -1,9 +1,9 @@
-import { $ as resolveExposure, $t as mergeCapabilities, A as nativeCapletPromptGuidance, An as isJSONRPCRequest, At as runOAuthFlow, B as CodeModeSessionManager, Bn as safeParse, Bt as defaultConfigBaseDir, C as resolveHostedCloudRemote, Cn as ReadResourceRequestSchema, Ct as validateCapletFile, D as isLoopbackHost, Dn as assertCompleteRequestResourceTemplate, Dt as markdownStructuredContent, E as controlUrlForBase, En as assertCompleteRequestPrompt, Et as markdownCallToolResultContent, Fn as getSchemaDescription, Ft as readTokenBundle, G as CodeModeJournalStore, Gt as resolveProjectCapletsRoot, H as diagnoseCodeModeTypeScript, Ht as defaultStateBaseDir, I as codeModeRunInputSchema, In as isSchemaOptional, It as DEFAULT_AUTH_DIR, J as codeModeDeclarationHash, Jt as serializeMessage, K as CodeModeLogStore, Kt as resolveProjectConfigPath, L as codeModeRunParamsSchema, Ln as isZ4Schema, M as nativeCapletToolName, Mn as getLiteralValue, Mt as startOAuthFlow, Nn as getObjectShape, Nt as deleteTokenBundle, O as parseServerBaseUrl, On as isInitializeRequest, Ot as refreshOAuthTokenBundle, Pn as getParseErrorMessage, Pt as isTokenBundleExpired, Q as CapletsEngine, Qt as Protocol, R as emptyCodeModeRunMeta, Rn as normalizeObjectSchema, Rt as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, S as resolveCapletsRemote, Sn as McpError, St as discoverCapletFiles, T as appendBasePath, Tn as SetLevelRequestSchema, Tt as hasRenderableStructuredContent, U as createCodeModeCapletsApi, Ut as resolveCapletsRoot, V as QuickJsCodeModeSandbox, Vn as safeParseAsync, Vt as defaultConfigPath, W as listCodeModeCallableCaplets, Wt as resolveConfigPath, X as generateCodeModeRunToolDescription, Xt as assertToolsCallTaskCapability, Y as generateCodeModeDeclarations, Yt as assertClientRequestTaskCapability, Z as minifyCodeModeDeclarationText, Zt as AjvJsonSchemaValidator, _ as CapletsCloudClient, _n as ListResourceTemplatesRequestSchema, _t as FileVaultStore, a as CloudAuthStore, an as CreateMessageResultWithToolsSchema, at as ServerRegistry, b as isCapletsCloudUrl, bn as ListToolsRequestSchema, bt as decryptVaultValue, c as redactedCloudAuthStatus, cn as ElicitResultSchema, ct as loadConfig, d as projectBindingError, dn as GetPromptRequestSchema, dt as loadLocalOverlayConfigWithSources, en as toJsonSchemaCompat, et as decodeDirectResourceUri, f as projectBindingRecovery, fn as InitializeRequestSchema, ft as loadProjectConfig, g as buildProjectSyncManifest, gn as ListPromptsRequestSchema, gt as vaultStoreForAuthDir, hn as LATEST_PROTOCOL_VERSION, ht as vaultResolverForAuthDir, i as createRemoteProfileStore, in as CreateMessageResultSchema, it as handleServerTool, j as nativeCapletToolDescription, jn as isJSONRPCResultResponse, jt as startGenericOAuthFlow, k as resolveCapletsServer, kn as isJSONRPCErrorResponse, kt as runGenericOAuthFlow, l as PROJECT_BINDING_ERROR_CODES, ln as EmptyResultSchema, lt as loadConfigWithSources, mn as JSONRPCMessageSchema, mt as vaultBootstrapResolver, n as resolveRemoteSelection, nn as CallToolResultSchema, nt as findProjectRoot, o as cloudAuthPath, on as CreateTaskResultSchema, ot as capabilityDescription, p as CloudAuthClient, pn as InitializedNotificationSchema, pt as parseConfig, q as redactCodeModeLogText, qt as ReadBuffer, r as cloudCredentialsFromRemoteProfile, rn as CompleteRequestSchema, rt as fingerprintProjectRoot, s as migrateCredentials, st as GoogleDiscoveryManager, t as createNativeCapletsService, tn as CallToolRequestSchema, tt as directResourceUriMatchesTemplate, u as ProjectBindingError, un as ErrorCode, ut as loadGlobalConfig, vn as ListResourcesRequestSchema, vt as VAULT_MAX_VALUE_BYTES, w as resolveRemoteMode, wn as SUPPORTED_PROTOCOL_VERSIONS, wt as loadCapletFilesFromMap, x as normalizeRemoteProfileHostUrl, xn as LoggingLevelSchema, xt as encryptVaultValue, y as hostedCloudWorkspaceFromRemoteUrl, yn as ListRootsResultSchema, yt as validateVaultKeyName, z as runCodeMode, zn as objectFromShape, zt as defaultCacheBaseDir } from "./service-aBIn4nrw.js";
+import { $ as resolveExposure, $t as mergeCapabilities, A as nativeCapletPromptGuidance, An as isJSONRPCRequest, At as runOAuthFlow, B as CodeModeSessionManager, Bn as safeParse, Bt as defaultConfigBaseDir, C as resolveHostedCloudRemote, Cn as ReadResourceRequestSchema, Ct as validateCapletFile, D as isLoopbackHost, Dn as assertCompleteRequestResourceTemplate, Dt as markdownStructuredContent, E as controlUrlForBase, En as assertCompleteRequestPrompt, Et as markdownCallToolResultContent, Fn as getSchemaDescription, Ft as readTokenBundle, G as CodeModeJournalStore, Gt as resolveProjectCapletsRoot, H as diagnoseCodeModeTypeScript, Ht as defaultStateBaseDir, I as codeModeRunInputSchema, In as isSchemaOptional, It as DEFAULT_AUTH_DIR, J as codeModeDeclarationHash, Jt as serializeMessage, K as CodeModeLogStore, Kt as resolveProjectConfigPath, L as codeModeRunParamsSchema, Ln as isZ4Schema, M as nativeCapletToolName, Mn as getLiteralValue, Mt as startOAuthFlow, Nn as getObjectShape, Nt as deleteTokenBundle, O as parseServerBaseUrl, On as isInitializeRequest, Ot as refreshOAuthTokenBundle, Pn as getParseErrorMessage, Pt as isTokenBundleExpired, Q as CapletsEngine, Qt as Protocol, R as emptyCodeModeRunMeta, Rn as normalizeObjectSchema, Rt as DEFAULT_OBSERVED_OUTPUT_SHAPE_CACHE_DIR, S as resolveCapletsRemote, Sn as McpError, St as discoverCapletFiles, T as appendBasePath, Tn as SetLevelRequestSchema, Tt as hasRenderableStructuredContent, U as createCodeModeCapletsApi, Ut as resolveCapletsRoot, V as QuickJsCodeModeSandbox, Vn as safeParseAsync, Vt as defaultConfigPath, W as listCodeModeCallableCaplets, Wt as resolveConfigPath, X as generateCodeModeRunToolDescription, Xt as assertToolsCallTaskCapability, Y as generateCodeModeDeclarations, Yt as assertClientRequestTaskCapability, Z as minifyCodeModeDeclarationText, Zt as AjvJsonSchemaValidator, _ as CapletsCloudClient, _n as ListResourceTemplatesRequestSchema, _t as FileVaultStore, a as CloudAuthStore, an as CreateMessageResultWithToolsSchema, at as ServerRegistry, b as isCapletsCloudUrl, bn as ListToolsRequestSchema, bt as decryptVaultValue, c as redactedCloudAuthStatus, cn as ElicitResultSchema, ct as loadConfig, d as projectBindingError, dn as GetPromptRequestSchema, dt as loadLocalOverlayConfigWithSources, en as toJsonSchemaCompat, et as decodeDirectResourceUri, f as projectBindingRecovery, fn as InitializeRequestSchema, ft as loadProjectConfig, g as buildProjectSyncManifest, gn as ListPromptsRequestSchema, gt as vaultStoreForAuthDir, hn as LATEST_PROTOCOL_VERSION, ht as vaultResolverForAuthDir, i as createRemoteProfileStore, in as CreateMessageResultSchema, it as handleServerTool, j as nativeCapletToolDescription, jn as isJSONRPCResultResponse, jt as startGenericOAuthFlow, k as resolveCapletsServer, kn as isJSONRPCErrorResponse, kt as runGenericOAuthFlow, l as PROJECT_BINDING_ERROR_CODES, ln as EmptyResultSchema, lt as loadConfigWithSources, mn as JSONRPCMessageSchema, mt as vaultBootstrapResolver, n as resolveRemoteSelection, nn as CallToolResultSchema, nt as findProjectRoot, o as cloudAuthPath, on as CreateTaskResultSchema, ot as capabilityDescription, p as CloudAuthClient, pn as InitializedNotificationSchema, pt as parseConfig, q as redactCodeModeLogText, qt as ReadBuffer, r as cloudCredentialsFromRemoteProfile, rn as CompleteRequestSchema, rt as fingerprintProjectRoot, s as migrateCredentials, st as GoogleDiscoveryManager, t as createNativeCapletsService, tn as CallToolRequestSchema, tt as directResourceUriMatchesTemplate, u as ProjectBindingError, un as ErrorCode, ut as loadGlobalConfig, vn as ListResourcesRequestSchema, vt as VAULT_MAX_VALUE_BYTES, w as resolveRemoteMode, wn as SUPPORTED_PROTOCOL_VERSIONS, wt as loadCapletFilesFromMap, x as normalizeRemoteProfileHostUrl, xn as LoggingLevelSchema, xt as encryptVaultValue, y as hostedCloudWorkspaceFromRemoteUrl, yn as ListRootsResultSchema, yt as validateVaultKeyName, z as runCodeMode, zn as objectFromShape, zt as defaultCacheBaseDir } from "./service-BGGiZLHa.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-BoqMu4MG.js";
-import { f as redactSecrets$1, i as SERVER_ID_PATTERN, l as CAPLETS_ERROR_CODES, p as toSafeError, u as CapletsError } from "./validation-GD2x5HW1.js";
+import { a as SERVER_ID_PATTERN, d as CapletsError, m as toSafeError, p as redactSecrets$1, u as CAPLETS_ERROR_CODES } from "./validation-CWzd2gtn.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-DuP7mJQf.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-CFOJucl5.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-1wDjwHkC.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, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, writeSync } from "node:fs";
@@ -1553,7 +1553,7 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 } };
 //#endregion
 //#region package.json
-var version = "0.26.1";
+var version = "0.27.0";
 //#endregion
 //#region src/serve/session.ts
 var CapletsMcpSession = class {
@@ -17487,8 +17487,17 @@ function mergeRemoteAndLocalRows(remoteRows, localOverlay, options) {
 	});
 	if (!localOverlay) return [...rows.values()].filter((row) => options.includeDisabled || !row.disabled).sort((left, right) => left.server.localeCompare(right.server));
 	for (const row of listCaplets(localOverlay, { includeDisabled: true })) {
-		if (rows.get(row.server)) {
+		const remote = rows.get(row.server);
+		if (remote) {
 			if (row.disabled) continue;
+			if (remote.shadowing === "namespace") {
+				options.writeErr(`Local Caplet '${row.server}' is exposed under a qualified ID because the remote Caplet uses namespace shadowing for that Caplet ID.\n`);
+				continue;
+			}
+			if (remote.shadowing !== "allow") {
+				options.writeErr(`Local Caplet '${row.server}' is suppressed because the remote Caplet forbids shadowing that Caplet ID.\n`);
+				continue;
+			}
 			options.writeErr(`Warning: ${formatOverlaySource(row.source)} Caplet ${row.server} shadows remote Caplet\n`);
 		}
 		rows.set(row.server, row);

package/dist/native/remote.d.ts

@@ -1,11 +1,12 @@
 import type { AttachCodeModeCaplet } from "../attach/api";
+import type { CapletShadowingPolicy } from "../config";
 import type { ResolvedNativeCapletsServiceOptions } from "./options";
 import type { NativeCapletsService, NativeCapletsToolsChangedListener, NativeCapletTool } from "./service";
 export type RemoteCapletsTool = {
     name: string;
     capletId?: string | undefined;
     sourceCapletId?: string | undefined;
-    shadowing?: "forbid" | "allow" | undefined;
+    shadowing?: CapletShadowingPolicy | undefined;
     title?: string | undefined;
     description?: string | undefined;
     inputSchema?: unknown;

package/dist/native/service.d.ts

@@ -2,7 +2,7 @@ import type { NativeCapletsServiceResolutionInput } from "./options";
 import { resolveNativeCapletsServiceOptions } from "./options";
 import { type RemoteCapletsClient } from "./remote";
 import type { CodeModeCallableCaplet } from "../code-mode/types";
-import { type CapletsConfig } from "../config";
+import { type CapletShadowingPolicy, type CapletsConfig } from "../config";
 import { generatedToolInputJsonSchemaForCaplet } from "../generated-tool-input-schema";
 export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput & {
     configPath?: string;
@@ -18,7 +18,7 @@ export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput &
 export type NativeCapletTool = {
     caplet: string;
     sourceCaplet?: string;
-    shadowing?: "forbid" | "allow";
+    shadowing?: CapletShadowingPolicy;
     toolName: string;
     title: string;
     description: string;

package/dist/native.js

@@ -1,4 +1,4 @@
-import { A as nativeCapletPromptGuidance, F as nativeCodeModeToolName, M as nativeCapletToolName, N as nativeCapletsSystemGuidance, P as nativeCodeModeToolId, h as createSdkRemoteCapletsClient, j as nativeCapletToolDescription, m as RemoteNativeCapletsService, t as createNativeCapletsService, v as resolveNativeCapletsServiceOptions } from "./service-aBIn4nrw.js";
+import { A as nativeCapletPromptGuidance, F as nativeCodeModeToolName, M as nativeCapletToolName, N as nativeCapletsSystemGuidance, P as nativeCodeModeToolId, h as createSdkRemoteCapletsClient, j as nativeCapletToolDescription, m as RemoteNativeCapletsService, t as createNativeCapletsService, v as resolveNativeCapletsServiceOptions } from "./service-BGGiZLHa.js";
 import { generatedToolInputJsonSchema, generatedToolInputSchema } from "./generated-tool-input-schema.js";
 //#region src/native/process-cleanup.ts
 function registerNativeCapletsProcessCleanup(service, options = {}) {

package/dist/{service-aBIn4nrw.js → service-BGGiZLHa.js}

@@ -1,5 +1,5 @@
 import { A as safeParseAsync$1, C as toJSONSchema, D as parse$3, E as $ZodType, F as NEVER, M as defineLazy, N as normalizeParams, O as parseAsync, P as $constructor, S as datetime, T as $ZodObject, _ as record, a as any, b as unknown, c as custom, d as literal, f as looseObject, g as preprocess, h as optional, i as _null, j as clone, k as safeParse$1, l as discriminatedUnion, m as object$1, o as array, p as number$1, r as _enum, s as boolean, t as ZodNumber$1, u as intersection, v as string, w as _coercedNumber, x as url, y as union } from "./schemas-BoqMu4MG.js";
-import { a as isAllowedHttpBaseUrl, c as validateHttpActionHeaders, d as errorResult, f as redactSecrets, i as SERVER_ID_PATTERN, n as HEADER_NAME_PATTERN, o as isAllowedRemoteUrl, p as toSafeError, r as HTTP_BASE_URL_PATTERN, s as isUrl, t as FORBIDDEN_HEADERS, u as CapletsError } from "./validation-GD2x5HW1.js";
+import { a as SERVER_ID_PATTERN, c as isUrl, d as CapletsError, f as errorResult, i as NAMESPACE_ALIAS_LABEL_PATTERN, l as validateHttpActionHeaders, m as toSafeError, n as HEADER_NAME_PATTERN, o as isAllowedHttpBaseUrl, p as redactSecrets, r as HTTP_BASE_URL_PATTERN, s as isAllowedRemoteUrl, t as FORBIDDEN_HEADERS } from "./validation-CWzd2gtn.js";
 import { generatedToolInputJsonSchema, generatedToolInputJsonSchemaForCaplet, generatedToolInputSchemaForCaplet, mcpOperations, operations } from "./generated-tool-input-schema.js";
 import { f as observedOutputShapeKey, i as observeOutputShape, r as normalizedObservableValue, t as usefulOutputSchema, u as FileObservedOutputShapeStore } from "./observed-output-shapes-DuP7mJQf.js";
 import { createRequire } from "node:module";
@@ -26005,7 +26005,11 @@ 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 capletShadowingSchema = _enum([
+	"forbid",
+	"allow",
+	"namespace"
+]).describe("Whether attached local Caplets may shadow this remote Caplet ID.");
 const capletEndpointAuthSchema = discriminatedUnion("type", [
 	object$1({ type: literal("none") }).strict(),
 	object$1({
@@ -27288,7 +27292,33 @@ 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 shadowingSchema = _enum([
+	"forbid",
+	"allow",
+	"namespace"
+]).default("forbid").describe("Whether attached local Caplets may shadow this remote Caplet ID.");
+const namespaceAliasLabelSchema = string().regex(NAMESPACE_ALIAS_LABEL_PATTERN, "namespace alias labels must be lowercase DNS-style labels using letters, numbers, or hyphens").describe("Namespace label used when qualifying colliding Caplet IDs.");
+const namespaceAliasesSchema = object$1({
+	local: namespaceAliasLabelSchema.optional(),
+	upstreams: record(string().trim().min(1), namespaceAliasLabelSchema).default({}).describe("Namespace aliases keyed by durable upstream source identity.")
+}).strict().default({ upstreams: {} }).superRefine((aliases, ctx) => {
+	const seen = /* @__PURE__ */ new Map();
+	const addAlias = (value, path) => {
+		if (!value) return;
+		const existing = seen.get(value);
+		if (existing) {
+			ctx.addIssue({
+				code: "custom",
+				path,
+				message: `namespace alias '${value}' is already used at ${existing.join(".")}`
+			});
+			return;
+		}
+		seen.set(value, path);
+	};
+	addAlias(aliases.local, ["local"]);
+	for (const [selector, alias] of Object.entries(aliases.upstreams)) addAlias(alias, ["upstreams", selector]);
+}).describe("Source-level namespace aliases for hash-qualified Caplet IDs.");
 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"),
@@ -27545,6 +27575,7 @@ function configSchemaFor(serverValueSchema, openApiEndpointValueSchema, googleDi
 			exposureDiscoveryTimeoutMs: 15e3,
 			exposureDiscoveryConcurrency: 4
 		}).describe("Global Caplets runtime options."),
+		namespaceAliases: namespaceAliasesSchema,
 		mcpServers: record(string().regex(SERVER_ID_PATTERN), serverValueSchema).default({}).describe("Downstream MCP servers keyed by stable server ID."),
 		openapiEndpoints: record(string().regex(SERVER_ID_PATTERN), openApiEndpointValueSchema).default({}).describe("OpenAPI endpoints keyed by stable Caplet ID."),
 		googleDiscoveryApis: record(string().regex(SERVER_ID_PATTERN), googleDiscoveryApiValueSchema).default({}).describe("Google Discovery APIs keyed by stable Caplet ID."),
@@ -28321,6 +28352,7 @@ function mergeConfigInputs(...inputs) {
 		merged = {
 			...merged,
 			...input,
+			namespaceAliases: mergeNamespaceAliases(merged?.namespaceAliases, input.namespaceAliases),
 			mcpServers: {
 				...merged?.mcpServers,
 				...input.mcpServers
@@ -28353,6 +28385,23 @@ function mergeConfigInputs(...inputs) {
 	}
 	return merged;
 }
+function mergeNamespaceAliases(left, right) {
+	if (right !== void 0 && !isPlainObject$5(right)) return right;
+	if (left !== void 0 && !isPlainObject$5(left)) return left;
+	if (!isPlainObject$5(left) && !isPlainObject$5(right)) return;
+	const leftRecord = isPlainObject$5(left) ? left : void 0;
+	const rightRecord = isPlainObject$5(right) ? right : void 0;
+	const leftUpstreams = isPlainObject$5(leftRecord?.upstreams) ? leftRecord.upstreams : void 0;
+	const rightUpstreams = isPlainObject$5(rightRecord?.upstreams) ? rightRecord.upstreams : void 0;
+	return stripUndefined({
+		...leftRecord,
+		...rightRecord,
+		upstreams: {
+			...leftUpstreams,
+			...rightUpstreams
+		}
+	});
+}
 function mergeConfigInputsWithSources(...inputs) {
 	let merged = {};
 	const sources = {};
@@ -28477,6 +28526,10 @@ function parseConfig(input, options = {}) {
 			exposureDiscoveryConcurrency: parsed.data.options.exposureDiscoveryConcurrency,
 			completion: parsed.data.completion
 		},
+		namespaceAliases: stripUndefined({
+			local: parsed.data.namespaceAliases.local,
+			upstreams: parsed.data.namespaceAliases.upstreams
+		}),
 		mcpServers: servers,
 		openapiEndpoints,
 		googleDiscoveryApis,
@@ -64028,7 +64081,7 @@ var CapletsEngine = class {
 		}
 	}
 	async completeCliWords(words) {
-		const { completeCliWords } = await import("./completion-CFOJucl5.js").then((n) => n.r);
+		const { completeCliWords } = await import("./completion-1wDjwHkC.js").then((n) => n.r);
 		return await completeCliWords(words, {
 			config: this.registry.config,
 			managers: {
@@ -81409,7 +81462,7 @@ function primitiveInvokeInput(capletId, operation, input) {
 function toolsFromManifest(manifest) {
 	const codeModeCaplets = manifest.codeModeCaplets ?? [];
 	const codeModeMarker = attachCodeModeMarker(codeModeCaplets);
-	const codeModeShadowing = codeModeCaplets.some((entry) => entry.shadowing === "forbid") ? "forbid" : "allow";
+	const codeModeShadowing = codeModeCaplets.some((entry) => entry.shadowing === "forbid") ? "forbid" : codeModeCaplets.some((entry) => entry.shadowing === "namespace") ? "namespace" : "allow";
 	return [
 		...manifest.caplets.map((entry) => ({
 			name: entry.capletId,
@@ -81711,6 +81764,119 @@ function isPermanentRemoteCredentialsCode(code) {
 	return code === "remote_credentials_required" || code === "remote_credentials_revoked" || code === "remote_auth_failed";
 }
 //#endregion
+//#region src/exposure/namespace.ts
+function resolveNamespaceExposure(entries, options = {}) {
+	const hashLength = options.hashLength ?? 4;
+	const maxHashLength = options.maxHashLength ?? 8;
+	const groups = groupByBaseId(entries);
+	const visibleRecords = [];
+	const suppressedBareIds = /* @__PURE__ */ new Map();
+	const unavailableDiagnostics = [];
+	const reservedBareIds = new Set(groups.keys());
+	for (const [baseId, group] of groups) {
+		if (group.length === 1) {
+			visibleRecords.push(visibleRecord(group[0], baseId, false));
+			continue;
+		}
+		if (!isNamespaceCollisionGroup(group)) {
+			visibleRecords.push(visibleRecord(nonNamespaceWinner(group), baseId, false));
+			continue;
+		}
+		const diagnostics = validateNamespaceGroup(baseId, group);
+		if (diagnostics.length > 0) {
+			unavailableDiagnostics.push(...diagnostics);
+			continue;
+		}
+		const resolved = qualifyNamespaceGroup(group, {
+			baseId,
+			hashLength,
+			maxHashLength,
+			reservedBareIds
+		});
+		if ("diagnostic" in resolved) {
+			unavailableDiagnostics.push(resolved.diagnostic);
+			continue;
+		}
+		visibleRecords.push(...resolved.records);
+		suppressedBareIds.set(baseId, diagnostic(baseId, "namespace_collision", group, resolved.records.map((record) => record.id)));
+	}
+	return {
+		visibleRecords,
+		routes: new Map(visibleRecords.map((record) => [record.id, record.route])),
+		suppressedBareIds,
+		unavailableDiagnostics
+	};
+}
+function groupByBaseId(entries) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const entry of entries) groups.set(entry.baseId, [...groups.get(entry.baseId) ?? [], entry]);
+	return groups;
+}
+function isNamespaceCollisionGroup(group) {
+	const upstreams = group.filter((entry) => entry.sourceKind === "upstream");
+	return upstreams.length > 0 && upstreams.every((entry) => entry.shadowing === "namespace");
+}
+function nonNamespaceWinner(group) {
+	const forbiddingUpstream = group.find((entry) => entry.sourceKind === "upstream" && entry.shadowing === "forbid");
+	if (forbiddingUpstream) return forbiddingUpstream;
+	const local = group.find((entry) => entry.sourceKind === "local");
+	if (local) return local;
+	return group.find((entry) => entry.sourceKind === "upstream") ?? group[0];
+}
+function validateNamespaceGroup(baseId, group) {
+	const diagnostics = [];
+	for (const entry of group) {
+		if (!entry.durableSourceIdentity) {
+			diagnostics.push(diagnostic(baseId, "missing_durable_source_identity", group, []));
+			break;
+		}
+		if (entry.namespaceAlias && !NAMESPACE_ALIAS_LABEL_PATTERN.test(entry.namespaceAlias)) {
+			diagnostics.push(diagnostic(baseId, "namespace_alias_invalid", group, []));
+			break;
+		}
+	}
+	return diagnostics;
+}
+function qualifyNamespaceGroup(group, options) {
+	const ids = group.map((entry) => qualifiedId(entry, options.baseId, options.hashLength));
+	if (!(new Set(ids).size !== ids.length || ids.some((id) => options.reservedBareIds.has(id) || !SERVER_ID_PATTERN.test(id)))) return { records: group.map((entry, index) => visibleRecord(entry, ids[index], true)) };
+	return { diagnostic: diagnostic(options.baseId, "generated_id_collision", group, []) };
+}
+function qualifiedId(entry, baseId, hashLength) {
+	return `${namespaceLabel(entry)}-${createHash("sha256").update(entry.durableSourceIdentity ?? "").digest("hex").slice(0, hashLength)}__${baseId}`;
+}
+function visibleRecord(entry, id, namespaced) {
+	return {
+		...entry,
+		id,
+		label: namespaceLabel(entry),
+		namespaced
+	};
+}
+function namespaceLabel(entry) {
+	return entry.namespaceAlias ?? entry.sourceLabel ?? entry.sourceKind;
+}
+function diagnostic(requestedId, reason, group, alternatives) {
+	return {
+		requestedId,
+		reason,
+		alternatives,
+		sources: group.map((entry) => ({
+			sourceKind: entry.sourceKind,
+			label: namespaceLabel(entry),
+			...entry.durableSourceIdentity ? { durableSourceIdentity: entry.durableSourceIdentity } : {}
+		})),
+		hint: diagnosticHint(requestedId, reason, alternatives)
+	};
+}
+function diagnosticHint(requestedId, reason, alternatives) {
+	if (reason === "namespace_collision") return `Caplet '${requestedId}' is unavailable because namespace shadowing exposes qualified alternatives: ${alternatives.join(", ")}.`;
+	if (reason === "missing_durable_source_identity") return `Caplet '${requestedId}' could not be namespaced because at least one source has no durable identity.`;
+	if (reason === "namespace_alias_invalid") return `Caplet '${requestedId}' could not be namespaced because an alias label is invalid.`;
+	if (reason === "unsupported_protocol") return `Caplet '${requestedId}' could not be namespaced because a source protocol cannot represent namespace metadata.`;
+	return `Caplet '${requestedId}' could not be namespaced because generated qualified IDs were not unique.`;
+}
+//#endregion
 //#region src/cloud-auth/errors.ts
 const SECRET_PATTERN = /(cap_access_[a-z0-9._~+/=-]+|cap_refresh_[a-z0-9._~+/=-]+|one_time_code_[a-z0-9._~+/=-]+|Bearer\s+)[^\s"]*/giu;
 function redactCloudAuthSecrets(value) {
@@ -83197,7 +83363,7 @@ function createLocalOverlayService(options) {
 }
 function createCompositeRemoteService(remoteOptions, local, options, authKind) {
 	const { remote, presence } = createCompositeRemoteParts(remoteOptions, local, options, authKind);
-	return new CompositeNativeCapletsService(remote, local, options, presence);
+	return new CompositeNativeCapletsService(remote, local, options, remoteOptions.url.toString(), presence);
 }
 function createCompositeRemoteParts(remoteOptions, local, options, authKind, resolveRuntimeRemoteOptions) {
 	const remote = new RemoteNativeCapletsService({
@@ -83289,7 +83455,7 @@ var ProfileBackedNativeCapletsService = class {
 			const signature = remoteOptionsSignature(remoteOptions);
 			if (!this.delegate) {
 				const { remote, presence } = createCompositeRemoteParts(remoteOptions, this.local, this.options, this.authKind, () => this.resolveProfileRemoteOptions());
-				this.delegate = new CompositeNativeCapletsService(remote, this.local, this.options, presence);
+				this.delegate = new CompositeNativeCapletsService(remote, this.local, this.options, remoteOptions.url.toString(), presence);
 				this.unsubscribeDelegate = this.delegate.onToolsChanged((tools) => this.emit(tools));
 				this.remoteSignature = signature;
 				this.credentialExpiresAt = remoteOptions.credentialExpiresAt;
@@ -83301,7 +83467,7 @@ var ProfileBackedNativeCapletsService = class {
 				await Promise.all([remote.close(), presence?.close()]);
 				return;
 			}
-			await this.delegate.replaceRemote(remote, presence);
+			await this.delegate.replaceRemote(remote, remoteOptions.url.toString(), presence);
 			this.remoteSignature = signature;
 			this.credentialExpiresAt = remoteOptions.credentialExpiresAt;
 		} catch (error) {
@@ -83386,23 +83552,30 @@ var CompositeNativeCapletsService = class {
 	remote;
 	local;
 	options;
+	remoteIdentity;
 	presence;
 	listeners = /* @__PURE__ */ new Set();
 	unsubscribeRemote;
 	unsubscribeLocal;
 	warnedShadowedLocalCaplets = /* @__PURE__ */ new Set();
 	tools = [];
+	routes = /* @__PURE__ */ new Map();
+	namespaceDiagnostics = /* @__PURE__ */ new Map();
 	closed = false;
 	batchingReload = false;
 	codeModeSessions = new CodeModeSessionManager();
-	constructor(remote, local, options, presence) {
+	constructor(remote, local, options, remoteIdentity, presence) {
 		this.remote = remote;
 		this.local = local;
 		this.options = options;
+		this.remoteIdentity = remoteIdentity;
 		this.presence = presence;
 		this.unsubscribeRemote = this.remote.onToolsChanged(() => this.updateMergedTools());
 		this.unsubscribeLocal = this.local.onToolsChanged(() => this.updateMergedTools());
-		this.tools = this.mergeTools();
+		const merged = this.mergeTools();
+		this.tools = merged.tools;
+		this.routes = merged.routes;
+		this.namespaceDiagnostics = merged.namespaceDiagnostics;
 		this.startPresence();
 	}
 	listTools() {
@@ -83410,7 +83583,11 @@ var CompositeNativeCapletsService = class {
 	}
 	async execute(capletId, request) {
 		if (capletId === "code_mode") return await executeCodeModeRunNative(this, request, this.codeModeSessions);
-		if (this.localCanExecute(capletId)) return await this.local.execute(capletId, request);
+		const route = this.routes.get(capletId);
+		if (route?.service === "local") return await this.local.execute(route.capletId, request);
+		if (route?.service === "remote") return await this.remote.execute(route.capletId, request);
+		const diagnostic = this.namespaceDiagnostics.get(capletId);
+		if (diagnostic) throw new CapletsError("CAPLET_NAMESPACE_COLLISION", diagnostic.hint, diagnostic);
 		return await this.remote.execute(capletId, request);
 	}
 	codeModeService() {
@@ -83451,16 +83628,19 @@ var CompositeNativeCapletsService = class {
 			this.presence?.close()
 		]);
 	}
-	async replaceRemote(remote, presence) {
+	async replaceRemote(remote, remoteIdentityOrPresence, presence) {
+		const remoteIdentity = typeof remoteIdentityOrPresence === "string" ? remoteIdentityOrPresence : this.remoteIdentity;
+		const nextPresence = typeof remoteIdentityOrPresence === "string" ? presence : remoteIdentityOrPresence;
 		if (this.closed) {
-			await Promise.all([remote.close(), presence?.close()]);
+			await Promise.all([remote.close(), nextPresence?.close()]);
 			return;
 		}
 		const previousRemote = this.remote;
 		const previousPresence = this.presence;
 		this.unsubscribeRemote();
 		this.remote = remote;
-		this.presence = presence;
+		this.remoteIdentity = remoteIdentity;
+		this.presence = nextPresence;
 		this.unsubscribeRemote = this.remote.onToolsChanged(() => this.updateMergedTools());
 		await Promise.all([previousRemote.close(), previousPresence?.close()]);
 		if (this.closed) return;
@@ -83469,9 +83649,15 @@ var CompositeNativeCapletsService = class {
 	}
 	updateMergedTools() {
 		if (this.closed || this.batchingReload) return;
-		const tools = this.mergeTools();
-		if (JSON.stringify(tools) === JSON.stringify(this.tools)) return;
-		this.tools = tools;
+		const merged = this.mergeTools();
+		if (JSON.stringify(merged.tools) === JSON.stringify(this.tools)) {
+			this.routes = merged.routes;
+			this.namespaceDiagnostics = merged.namespaceDiagnostics;
+			return;
+		}
+		this.tools = merged.tools;
+		this.routes = merged.routes;
+		this.namespaceDiagnostics = merged.namespaceDiagnostics;
 		for (const listener of this.listeners) try {
 			listener(this.listTools());
 		} catch (error) {
@@ -83483,16 +83669,89 @@ var CompositeNativeCapletsService = class {
 		const allRemoteTools = this.remote.listTools();
 		const remoteCodeModeTools = remoteCodeModeCallableNativeTools(allRemoteTools);
 		const remoteIds = remoteSuppressedCapletIds(allRemoteTools, remoteCodeModeTools);
-		const localTools = allLocalTools.filter((tool) => tool.codeModeRun !== true && !remoteIds.has(tool.sourceCaplet ?? tool.caplet));
+		const unsuppressedLocalTools = 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));
-		const mergedTools = [...allRemoteTools.filter((tool) => tool.codeModeRun !== true), ...localTools];
-		const codeModeTools = [...remoteCodeModeTools, ...localCodeModeTools];
-		return [...mergedTools, ...codeModeTools.length > 0 ? [codeModeRunNativeTool(codeModeTools)] : []];
+		const unsuppressedLocalCodeModeTools = codeModeCallableNativeTools(allLocalTools, { fallbackToVisible: false }).filter((tool) => !remoteIds.has(tool.caplet));
+		const remoteTools = allRemoteTools.filter((tool) => tool.codeModeRun !== true);
+		const resolved = this.resolveVisibleToolIds(remoteTools, unsuppressedLocalTools, remoteCodeModeTools, unsuppressedLocalCodeModeTools);
+		const codeModeTools = [...resolved.remoteCodeModeTools, ...resolved.localCodeModeTools];
+		return {
+			tools: [
+				...resolved.remoteTools,
+				...resolved.localTools,
+				...codeModeTools.length > 0 ? [codeModeRunNativeTool(codeModeTools)] : []
+			],
+			routes: resolved.routes,
+			namespaceDiagnostics: resolved.namespaceDiagnostics
+		};
 	}
-	localCanExecute(capletId) {
-		const remoteIds = remoteSuppressedCapletIds(this.remote.listTools());
-		return localExecutionKeys(this.local.listTools(), capletId).some((key) => !remoteIds.has(key));
+	resolveVisibleToolIds(remoteTools, localTools, remoteCodeModeTools, localCodeModeTools) {
+		const resolution = resolveNamespaceExposure(nativeNamespaceEntries([{
+			service: "remote",
+			tools: [...remoteTools, ...remoteCodeModeTools]
+		}, {
+			service: "local",
+			tools: [...localTools, ...localCodeModeTools]
+		}], {
+			...nativeNamespaceContext(this.options),
+			remoteIdentity: this.remoteIdentity
+		}));
+		const namespacedRecords = resolution.visibleRecords.filter((record) => record.namespaced);
+		const namespacedBaseIds = new Set(namespacedRecords.map((record) => record.baseId));
+		const diagnosticBaseIds = new Set(resolution.unavailableDiagnostics.map((diagnostic) => diagnostic.requestedId));
+		const routes = /* @__PURE__ */ new Map();
+		const namespaceDiagnostics = new Map(resolution.suppressedBareIds);
+		for (const diagnostic of resolution.unavailableDiagnostics) namespaceDiagnostics.set(diagnostic.requestedId, diagnostic);
+		const alternativesByBaseId = /* @__PURE__ */ new Map();
+		const staleIdsByBaseId = /* @__PURE__ */ new Map();
+		const setRoute = (visibleCapletId, route, overwrite) => {
+			if (overwrite || !routes.has(visibleCapletId)) routes.set(visibleCapletId, route);
+		};
+		const rewrite = (service, tools, overwrite) => {
+			const rewritten = [];
+			for (const tool of tools) {
+				const baseId = sourceBaseId(tool);
+				if (diagnosticBaseIds.has(baseId)) continue;
+				if (!namespacedBaseIds.has(baseId)) {
+					rewritten.push(tool);
+					setRoute(tool.caplet, {
+						service,
+						capletId: tool.caplet
+					}, overwrite);
+					continue;
+				}
+				const record = namespacedRecords.find((candidate) => candidate.baseId === baseId && candidate.route.service === service);
+				if (!record) continue;
+				const visibleTool = renameNativeTool(tool, record.id);
+				rewritten.push(visibleTool);
+				addMapSetValue(alternativesByBaseId, baseId, visibleTool.caplet);
+				if (tool.caplet !== visibleTool.caplet) addMapSetValue(staleIdsByBaseId, baseId, tool.caplet);
+				setRoute(visibleTool.caplet, {
+					service,
+					capletId: tool.caplet
+				}, overwrite);
+			}
+			return rewritten;
+		};
+		const remoteVisibleTools = rewrite("remote", remoteTools, false);
+		const localVisibleTools = rewrite("local", localTools, true);
+		const remoteVisibleCodeModeTools = rewrite("remote", remoteCodeModeTools, false);
+		const localVisibleCodeModeTools = rewrite("local", localCodeModeTools, true);
+		for (const [baseId, alternatives] of alternativesByBaseId) {
+			const baseDiagnostic = resolution.suppressedBareIds.get(baseId);
+			if (!baseDiagnostic) continue;
+			const alternativeList = [...alternatives];
+			namespaceDiagnostics.set(baseId, namespaceDiagnosticWithAlternatives(baseId, baseDiagnostic, alternativeList));
+			for (const staleId of staleIdsByBaseId.get(baseId) ?? []) namespaceDiagnostics.set(staleId, namespaceDiagnosticWithAlternatives(staleId, baseDiagnostic, alternativeList));
+		}
+		return {
+			remoteTools: remoteVisibleTools,
+			localTools: localVisibleTools,
+			remoteCodeModeTools: remoteVisibleCodeModeTools,
+			localCodeModeTools: localVisibleCodeModeTools,
+			routes,
+			namespaceDiagnostics
+		};
 	}
 	warnShadowedLocalCaplets(localTools, remoteIds) {
 		const localIds = /* @__PURE__ */ new Set([...localTools.filter((tool) => tool.codeModeRun !== true).map((tool) => tool.sourceCaplet ?? tool.caplet), ...codeModeCallableNativeTools(localTools, { fallbackToVisible: false }).map((tool) => tool.caplet)]);
@@ -83517,22 +83776,85 @@ var CompositeNativeCapletsService = class {
 		});
 	}
 };
-function remoteCodeModeCallableNativeTools(tools) {
-	return codeModeCallableNativeTools(tools, { fallbackToVisible: true });
+function addMapSetValue(map, key, value) {
+	let values = map.get(key);
+	if (!values) {
+		values = /* @__PURE__ */ new Set();
+		map.set(key, values);
+	}
+	values.add(value);
 }
-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 namespaceDiagnosticWithAlternatives(requestedId, diagnostic, alternatives) {
+	return {
+		...diagnostic,
+		requestedId,
+		alternatives,
+		hint: `Caplet '${requestedId}' is unavailable because namespace shadowing exposes qualified alternatives: ${alternatives.join(", ")}.`
+	};
 }
-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;
+function nativeNamespaceContext(options) {
+	const configPath = options.configPath ?? resolveConfigPath();
+	const projectConfigPath = options.projectConfigPath ?? resolveProjectConfigPath();
+	let namespaceAliases = parseConfig({}).namespaceAliases;
+	try {
+		namespaceAliases = loadLocalOverlayConfigWithSources(configPath, projectConfigPath).config.namespaceAliases;
+	} catch {}
+	return {
+		localIdentity: `local:${configPath}\0${projectConfigPath}`,
+		namespaceAliases
+	};
+}
+function nativeNamespaceEntries(groups, identities) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const group of groups) {
+		const byBaseId = /* @__PURE__ */ new Map();
+		for (const tool of group.tools) {
+			const baseId = sourceBaseId(tool);
+			byBaseId.set(baseId, [...byBaseId.get(baseId) ?? [], tool]);
+		}
+		for (const [baseId, tools] of byBaseId) {
+			const service = group.service;
+			entries.set(`${service}:${baseId}`, {
+				baseId,
+				sourceKind: service === "local" ? "local" : "upstream",
+				sourceLabel: service === "local" ? "local" : "remote",
+				namespaceAlias: service === "local" ? identities.namespaceAliases.local : identities.namespaceAliases.upstreams[identities.remoteIdentity],
+				durableSourceIdentity: service === "local" ? identities.localIdentity : identities.remoteIdentity,
+				shadowing: aggregateShadowing(tools),
+				route: {
+					service,
+					baseId
+				}
+			});
 		}
-		if (tool.caplet === capletId || tool.sourceCaplet === capletId) keys.push(tool.sourceCaplet ?? tool.caplet);
 	}
-	return keys;
+	return [...entries.values()];
+}
+function aggregateShadowing(tools) {
+	if (tools.some((tool) => (tool.shadowing ?? "forbid") === "forbid")) return "forbid";
+	if (tools.some((tool) => tool.shadowing === "namespace")) return "namespace";
+	return "allow";
+}
+function sourceBaseId(tool) {
+	return tool.sourceCaplet ?? tool.caplet;
+}
+function renameNativeTool(tool, visibleBaseId) {
+	const baseId = sourceBaseId(tool);
+	const visibleCapletId = tool.sourceCaplet && tool.caplet.startsWith(`${baseId}__`) ? `${visibleBaseId}${tool.caplet.slice(baseId.length)}` : visibleBaseId;
+	const operationName = tool.sourceCaplet && tool.caplet.startsWith(`${baseId}__`) ? tool.caplet.slice(baseId.length + 2) : void 0;
+	const toolName = operationName ? nativeDirectToolName(visibleBaseId, operationName) : nativeCapletToolName(visibleCapletId);
+	return {
+		...tool,
+		caplet: visibleCapletId,
+		...tool.sourceCaplet ? { sourceCaplet: visibleBaseId } : {},
+		toolName
+	};
+}
+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 ?? "forbid") === "forbid").map((tool) => tool.sourceCaplet ?? tool.caplet), ...remoteCodeModeTools.filter((tool) => (tool.shadowing ?? "forbid") === "forbid").map((tool) => tool.caplet)].filter((caplet) => caplet !== nativeCodeModeToolId));
 }
 function createProjectBindingSessionManager(cloud, local, options) {
 	if (!cloud) return;

package/dist/{validation-GD2x5HW1.js → validation-CWzd2gtn.js}

@@ -31,6 +31,7 @@ const CAPLETS_ERROR_CODES = [
 	"SERVER_UNAVAILABLE",
 	"SERVER_START_TIMEOUT",
 	"UNKNOWN_OPERATION",
+	"CAPLET_NAMESPACE_COLLISION",
 	"TOOL_NOT_FOUND",
 	"TOOL_CALL_TIMEOUT",
 	"AUTH_REQUIRED",
@@ -112,6 +113,7 @@ function errorResult(error, fallback) {
 //#endregion
 //#region src/config/validation.ts
 const SERVER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const NAMESPACE_ALIAS_LABEL_PATTERN = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
 const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const HTTP_BASE_URL_PATTERN = /^(?![a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*@)[^?#]*$/;
 const FORBIDDEN_HEADERS = /* @__PURE__ */ new Set([
@@ -174,4 +176,4 @@ function isUrl(value) {
 	}
 }
 //#endregion
-export { isAllowedHttpBaseUrl as a, validateHttpActionHeaders as c, errorResult as d, redactSecrets as f, SERVER_ID_PATTERN as i, CAPLETS_ERROR_CODES as l, HEADER_NAME_PATTERN as n, isAllowedRemoteUrl as o, toSafeError as p, HTTP_BASE_URL_PATTERN as r, isUrl as s, FORBIDDEN_HEADERS as t, CapletsError as u };
+export { SERVER_ID_PATTERN as a, isUrl as c, CapletsError as d, errorResult as f, NAMESPACE_ALIAS_LABEL_PATTERN as i, validateHttpActionHeaders as l, toSafeError as m, HEADER_NAME_PATTERN as n, isAllowedHttpBaseUrl as o, redactSecrets as p, HTTP_BASE_URL_PATTERN as r, isAllowedRemoteUrl as s, FORBIDDEN_HEADERS as t, CAPLETS_ERROR_CODES as u };

package/package.json

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