@wildo-ai/external-connectors-models 1.1.9 → 1.1.11

package/dist/esm/protocols/llm.external-connectors-models.schemas.js

@@ -648,6 +648,55 @@ export const LLM_MODEL_APPLICABILITY_PREFERENCE = {
 const LLM_MODEL_APPLICABILITY_REQUIRED_IO = {
     [LLM_Model_Applicability.VISUAL_JUDGMENT]: [LLM_Model_IO_Capability.MULTIMODAL_VISION],
 };
+const isDeclarationRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNonEmptyDeclarationString = (value) => typeof value === "string" && value.trim().length > 0;
+const listsOnlyMembersOf = (value, members) => Array.isArray(value) && value.every((member) => members.has(member));
+/**
+ * Why a provider's declared chat models ({@link LLM_ModelDeclaration}) cannot be used, or `undefined` (#2516). Absent is
+ * fine: an engine provider has none.
+ *
+ * A registry provider's module is loaded at runtime, so nothing here compiled its `models`; this is the check that holds
+ * them to their shape before resolution reads them. Every vocabulary is checked against its enum, because an unknown
+ * applicability would simply never match, and an unknown IO capability would read as evidence it is not.
+ */
+export const describeLLMModelDeclarationsDefect = (models) => {
+    if (models === undefined)
+        return undefined;
+    if (!Array.isArray(models))
+        return "are not a list";
+    const applicabilities = new Set(Object.values(LLM_Model_Applicability));
+    const ioCapabilities = new Set(Object.values(LLM_Model_IO_Capability));
+    const thinking = new Set(Object.values(LLM_Model_Thinking_Capability));
+    const efforts = new Set(Object.values(LLMProvider_ReasoningEffort));
+    const seen = new Set();
+    for (const [index, declaration] of models.entries()) {
+        if (!isDeclarationRecord(declaration) || !isNonEmptyDeclarationString(declaration.model))
+            return `have no \`model\` at position ${index}`;
+        const model = declaration.model;
+        if (seen.has(model))
+            return `declare "${model}" twice`;
+        seen.add(model);
+        if (!listsOnlyMembersOf(declaration.applicabilities, applicabilities))
+            return `give "${model}" unknown \`applicabilities\``;
+        if (declaration.applicabilities.includes(LLM_Model_Applicability.WORKSPACE_CODING_AGENT)) {
+            return `declare "${model}" for workspace coding, which is served over the Agent Client Protocol and never through a chat model`;
+        }
+        if (declaration.ioCapabilities !== undefined && !listsOnlyMembersOf(declaration.ioCapabilities, ioCapabilities))
+            return `give "${model}" unknown \`ioCapabilities\``;
+        if (declaration.thinkingCapability !== undefined && !thinking.has(declaration.thinkingCapability))
+            return `give "${model}" an unknown \`thinkingCapability\``;
+        if (declaration.unsupportedReasoningEfforts !== undefined && !listsOnlyMembersOf(declaration.unsupportedReasoningEfforts, efforts)) {
+            return `give "${model}" unknown \`unsupportedReasoningEfforts\``;
+        }
+    }
+    return undefined;
+};
+/**
+ * Whether the engine's catalog knows this provider, which decides where its model facts come from (#2516): catalog rows
+ * for an engine provider, the provider's own `models` declaration otherwise. One predicate, so the resolver and the agent
+ * registration that reads declarations cannot disagree about which side a provider is on.
+ */
+export const isLLMCatalogProvider = (providerRef, catalog = LLM_MODEL_CATALOG) => Object.values(catalog).some((entry) => entry.providerRef === providerRef);
 /** Why {@link resolveModelForApplicability} could not answer — carried into a named CONFIGURATION error. */
 export var LLM_ModelResolutionFailure;
 (function (LLM_ModelResolutionFailure) {
@@ -657,6 +706,11 @@ export var LLM_ModelResolutionFailure;
     LLM_ModelResolutionFailure["NO_RESOLVABLE_AVAILABILITY"] = "no_resolvable_availability";
     /** Candidates exist and are available, but none evidences the required IO capability. */
     LLM_ModelResolutionFailure["REQUIRED_IO_CAPABILITY_UNEVIDENCED"] = "required_io_capability_unevidenced";
+    /**
+     * An engine provider (one the catalog knows) also declares models. Its models are catalog rows; a declaration beside
+     * them would be a second, unchecked source of the same facts, so it is refused rather than merged.
+     */
+    LLM_ModelResolutionFailure["CATALOG_PROVIDER_DECLARES_MODELS"] = "catalog_provider_declares_models";
 })(LLM_ModelResolutionFailure || (LLM_ModelResolutionFailure = {}));
 /**
  * Resolve an applicability to ONE concrete model id for a given provider.
@@ -667,6 +721,13 @@ export var LLM_ModelResolutionFailure;
  * this layer exists to remove — the author asked for a KIND of model, and
  * quietly handing them a different kind is worse than refusing.
  *
+ * Two sources, decided by whether the catalog knows the provider (as document extraction decides, #2021):
+ * - an ENGINE provider resolves through {@link LLM_MODEL_APPLICABILITY_PREFERENCE} and its catalog rows, every gate
+ *   below applying, and is refused if it also declares models;
+ * - any other provider resolves from its own `declaredModels`, in declared order: the first model declaring the
+ *   applicability and evidencing the required IO capability. A provider that declares none fails with the same
+ *   named failure, naming what it considered.
+ *
  * Note this function answers the semantic question only. Whether the resolved
  * model is reachable over the agent's TRANSPORT (a profile that
  * declares it) is a separate gate owned by the backend, because the transport
@@ -680,9 +741,26 @@ export var LLM_ModelResolutionFailure;
  * nothing.
  */
 export const resolveModelForApplicability = (input, catalog = LLM_MODEL_CATALOG) => {
+    const requiredIo = LLM_MODEL_APPLICABILITY_REQUIRED_IO[input.applicability] ?? [];
+    const declared = input.declaredModels ?? [];
+    const catalogKnowsProvider = isLLMCatalogProvider(input.providerRef, catalog);
+    if (catalogKnowsProvider && declared.length > 0) {
+        return { resolved: false, failure: LLM_ModelResolutionFailure.CATALOG_PROVIDER_DECLARES_MODELS, consideredModels: declared.map((entry) => entry.model) };
+    }
+    if (!catalogKnowsProvider) {
+        const applicable = declared.filter((entry) => entry.applicabilities.includes(input.applicability));
+        if (applicable.length === 0) {
+            return { resolved: false, failure: LLM_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: declared.map((entry) => entry.model) };
+        }
+        const capable = applicable.filter((entry) => requiredIo.every((capability) => (entry.ioCapabilities ?? []).includes(capability)));
+        if (capable.length === 0) {
+            return { resolved: false, failure: LLM_ModelResolutionFailure.REQUIRED_IO_CAPABILITY_UNEVIDENCED, consideredModels: applicable.map((entry) => entry.model) };
+        }
+        const { model, ...facts } = capable[0];
+        return { resolved: true, model, facts, fromOverride: false };
+    }
     const override = input.preferenceOverride?.[input.applicability];
     const candidates = override ?? LLM_MODEL_APPLICABILITY_PREFERENCE[input.applicability];
-    const requiredIo = LLM_MODEL_APPLICABILITY_REQUIRED_IO[input.applicability] ?? [];
     const forProvider = candidates.filter((model) => {
         const entry = catalog[model];
         return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);
@@ -705,7 +783,18 @@ export const resolveModelForApplicability = (input, catalog = LLM_MODEL_CATALOG)
         return { resolved: false, failure: LLM_ModelResolutionFailure.REQUIRED_IO_CAPABILITY_UNEVIDENCED, consideredModels: available };
     }
     const model = capable[0];
-    return { resolved: true, model, entry: catalog[model], fromOverride: override !== undefined };
+    const entry = catalog[model];
+    return {
+        resolved: true,
+        model,
+        facts: {
+            applicabilities: entry.applicabilities,
+            ...(entry.ioCapabilities === undefined ? {} : { ioCapabilities: entry.ioCapabilities }),
+            ...(entry.thinkingCapability === undefined ? {} : { thinkingCapability: entry.thinkingCapability }),
+            ...(entry.unsupportedReasoningEfforts === undefined ? {} : { unsupportedReasoningEfforts: entry.unsupportedReasoningEfforts }),
+        },
+        fromOverride: override !== undefined,
+    };
 };
 /**
  * Model → thinking capability, DERIVED from {@link LLM_MODEL_CATALOG}.
@@ -754,13 +843,15 @@ export const getModelThinkingCapability = (model) => LLM_MODEL_THINKING_CAPABILI
  *
  * @param model The configured model id (free-form; unknown ids pass).
  * @param effort The configured effort; omit/undefined always passes.
+ * @param declared For a model a registry provider declares (#2516), its own thinking facts; they replace the catalog's,
+ *   which knows nothing of it. Absent facts fail open, exactly as for an unprobed catalog row.
  * @returns A violation message, or `null` if valid/unjudgeable.
  */
-export const validateReasoningEffortForModel = (model, effort) => {
+export const validateReasoningEffortForModel = (model, effort, declared) => {
     /** @wildo_source:part:end saas.external-providers.llm.model-configuration */
     if (effort === undefined)
         return null;
-    const capability = getModelThinkingCapability(model);
+    const capability = declared !== undefined ? declared.thinkingCapability : getModelThinkingCapability(model);
     if (capability === undefined)
         return null;
     if (capability === LLM_Model_Thinking_Capability.NONE) {
@@ -769,7 +860,7 @@ export const validateReasoningEffortForModel = (model, effort) => {
     if (capability === LLM_Model_Thinking_Capability.ALWAYS && effort === LLMProvider_ReasoningEffort.NONE) {
         return `Model "${model}" always reasons — its thinking cannot be disabled, so reasoningEffort "none" is rejected by the provider. Use "low" for the cheapest reasoning, or omit reasoningEffort for the model default.`;
     }
-    const unsupported = LLM_MODEL_UNSUPPORTED_REASONING_EFFORTS[model];
+    const unsupported = declared !== undefined ? declared.unsupportedReasoningEfforts : LLM_MODEL_UNSUPPORTED_REASONING_EFFORTS[model];
     if (unsupported?.includes(effort)) {
         const hint = effort === LLMProvider_ReasoningEffort.PROVIDER_DEFAULT
             ? 'Omit reasoningEffort entirely to get the model default.'