@juspay/neurolink 12.21.1 → 12.22.0

package/dist/core/baseProvider.d.ts

@@ -460,6 +460,24 @@ export declare abstract class BaseProvider implements AIProvider {
      * long-running generations that have always been allowed.
      */
     protected withTurnTimeout<T>(options: TextGenerationOptions, descriptorGenerateMs: number | undefined, run: (timedOptions: TextGenerationOptions) => Promise<T>): Promise<T>;
+    /**
+     * Emit a `turn:lifecycle` event on the SDK emitter (alongside
+     * tool:start/tool:end) so loop conditions that previously only reached
+     * process logs — step-cap, time-limit, stall, abort, tool timeouts,
+     * malformed-call retries — are observable by consumers' own pipelines.
+     *
+     * Lives here rather than on one provider because every native agentic loop
+     * has the same conditions to report, and a second copy is how two loops
+     * come to emit subtly different payloads for the same event name.
+     */
+    protected emitTurnEvent(payload: {
+        phase: "step-cap" | "context-cap" | "time-limit" | "stalled" | "aborted" | "provider-error" | "tool-timeout" | "malformed-retry";
+        step?: number;
+        maxSteps?: number;
+        toolName?: string;
+        toolCallCount?: number;
+        elapsedMs?: number;
+    }): void;
     /**
      * The per-provider generate budget from the descriptor, for native paths
      * that call `withTurnTimeout` directly.

package/dist/core/baseProvider.js

@@ -2014,6 +2014,28 @@ export class BaseProvider {
             timeoutController?.cleanup();
         }
     }
+    /**
+     * Emit a `turn:lifecycle` event on the SDK emitter (alongside
+     * tool:start/tool:end) so loop conditions that previously only reached
+     * process logs — step-cap, time-limit, stall, abort, tool timeouts,
+     * malformed-call retries — are observable by consumers' own pipelines.
+     *
+     * Lives here rather than on one provider because every native agentic loop
+     * has the same conditions to report, and a second copy is how two loops
+     * come to emit subtly different payloads for the same event name.
+     */
+    emitTurnEvent(payload) {
+        try {
+            this.neurolink?.getEventEmitter()?.emit("turn:lifecycle", {
+                provider: this.providerName,
+                timestamp: Date.now(),
+                ...payload,
+            });
+        }
+        catch {
+            /* listener errors are non-fatal */
+        }
+    }
     /**
      * The per-provider generate budget from the descriptor, for native paths
      * that call `withTurnTimeout` directly.

package/dist/core/modules/MessageBuilder.js

@@ -163,9 +163,17 @@ export class MessageBuilder {
                                 };
                             }
                             else if (item.type === "image") {
+                                // Upstream image builders label the resolved format as
+                                // either `mediaType` (canonical ImagePart field) or
+                                // `mimeType` (messageBuilder's convertSimpleImagesToProviderFormat).
+                                // Dropping it here silently reset every transcoded image
+                                // back to the provider's hardcoded PNG default even
+                                // though the transcoded bytes themselves were correct.
+                                const mediaType = (item.mediaType ?? item.mimeType);
                                 return {
                                     type: "image",
                                     image: item.image || "",
+                                    ...(mediaType && { mediaType }),
                                     ...(itemProviderOptions && {
                                         providerOptions: itemProviderOptions,
                                     }),
@@ -287,9 +295,17 @@ export class MessageBuilder {
                                 };
                             }
                             else if (item.type === "image") {
+                                // Upstream image builders label the resolved format as
+                                // either `mediaType` (canonical ImagePart field) or
+                                // `mimeType` (messageBuilder's convertSimpleImagesToProviderFormat).
+                                // Dropping it here silently reset every transcoded image
+                                // back to the provider's hardcoded PNG default even
+                                // though the transcoded bytes themselves were correct.
+                                const mediaType = (item.mediaType ?? item.mimeType);
                                 return {
                                     type: "image",
                                     image: item.image || "",
+                                    ...(mediaType && { mediaType }),
                                     ...(itemProviderOptions && {
                                         providerOptions: itemProviderOptions,
                                     }),

package/dist/factories/providerFactory.d.ts

@@ -43,6 +43,26 @@ export declare class ProviderFactory {
     /**
      * Get list of available providers
      */
+    /**
+     * Explain why a provider name did not resolve, usefully (#354).
+     *
+     * Three distinct situations used to share one generic message:
+     *
+     * - The registry is empty, because `ProviderRegistry.registerAllProviders()`
+     *   has not run yet. Every name is unresolvable, and listing zero available
+     *   providers tells the reader nothing about why.
+     * - The name IS a known provider but has no registration — recognised,
+     *   unavailable. Distinct from a typo and worth saying so.
+     * - The name is not a provider at all, in which case a near-miss is almost
+     *   always a typo and is worth naming: "opennai" -> "openai".
+     *
+     * Canonical names are offered as suggestions ahead of aliases, so a typo
+     * resolves to the name the docs use.
+     *
+     * @param requested - The provider name as the caller supplied it
+     * @returns A message naming the situation and what to do about it
+     */
+    private static describeUnresolvableProvider;
     static getAvailableProviders(): string[];
     /**
      * Get provider registration info

package/dist/factories/providerFactory.js

@@ -1,4 +1,5 @@
 import { logger } from "../utils/logger.js";
+import { suggestClosest } from "../utils/stringDistance.js";
 import { PROVIDER_DESCRIPTORS, PROVIDER_DESCRIPTORS_BY_NAME, PROVIDER_ALIAS_INDEX, } from "./providerDescriptors.js";
 // Pure factory pattern with no hardcoded imports
 // All providers loaded dynamically via registry to avoid circular dependencies
@@ -63,28 +64,52 @@ export class ProviderFactory {
         const normalizedName = resolvedProviderName.toLowerCase();
         const registration = ProviderFactory.providers.get(normalizedName);
         if (!registration) {
-            throw new Error(`Unknown provider: ${resolvedProviderName}. Available providers: ${ProviderFactory.getAvailableProviders().join(", ")}`);
+            throw new Error(ProviderFactory.describeUnresolvableProvider(resolvedProviderName));
         }
-        // Respect environment variables before falling back to registry default
-        let model = modelName;
-        if (!model) {
-            // Check for provider-specific environment variables
-            if (resolvedProviderName.toLowerCase().includes("vertex")) {
-                // Use gemini-2.5-flash as default - latest GA model with best price-performance
-                model = process.env.VERTEX_MODEL || "gemini-2.5-flash";
+        // Everything below this point — model resolution included — is wrapped in
+        // the same try/catch. The dynamic import a few lines down is on this
+        // path too: a load failure there is a provider-construction failure like
+        // any other and must come back as "Failed to create provider ...", not
+        // escape unwrapped.
+        try {
+            // Respect environment variables before falling back to registry default
+            let model = modelName;
+            if (model) {
+                // #337: the model registry has always carried aliases ("gpt4o" ->
+                // "gpt-4o"), and capability lookups resolve through them, but the id
+                // actually sent to the provider did not — so `generate({ model:
+                // "gpt4o" })` put the alias on the wire and the provider 404'd.
+                // Imported lazily: the registry is a large module and this is the only
+                // thing on the construction path that needs it.
+                const { resolveProviderModelAlias } = await import("../models/modelRegistry.js");
+                const canonicalProvider = ProviderFactory.getDescriptor(normalizedName)?.name ?? normalizedName;
+                const canonicalModel = resolveProviderModelAlias(canonicalProvider, model);
+                if (canonicalModel) {
+                    logger.debug("[ProviderFactory] Resolved model alias", {
+                        provider: canonicalProvider,
+                        requested: model,
+                        resolved: canonicalModel,
+                    });
+                    model = canonicalModel;
+                }
             }
-            else if (resolvedProviderName.toLowerCase().includes("bedrock")) {
-                model = process.env.BEDROCK_MODEL || process.env.BEDROCK_MODEL_ID;
+            if (!model) {
+                // Check for provider-specific environment variables
+                if (resolvedProviderName.toLowerCase().includes("vertex")) {
+                    // Use gemini-2.5-flash as default - latest GA model with best price-performance
+                    model = process.env.VERTEX_MODEL || "gemini-2.5-flash";
+                }
+                else if (resolvedProviderName.toLowerCase().includes("bedrock")) {
+                    model = process.env.BEDROCK_MODEL || process.env.BEDROCK_MODEL_ID;
+                }
+                // Fallback to registry default if no env var
+                model = model || registration.defaultModel;
             }
-            // Fallback to registry default if no env var
-            model = model || registration.defaultModel;
-        }
-        const credKey = resolveCredentialKey(normalizedName);
-        // Extract provider-scoped credential slice (e.g. credentials.openai for OpenAI)
-        const scopedCredentials = credentials
-            ? credentials[credKey]
-            : undefined;
-        try {
+            const credKey = resolveCredentialKey(normalizedName);
+            // Extract provider-scoped credential slice (e.g. credentials.openai for OpenAI)
+            const scopedCredentials = credentials
+                ? credentials[credKey]
+                : undefined;
             if (typeof registration.constructor !== "function") {
                 throw new Error(`Invalid constructor for provider ${providerName}: not a function`);
             }
@@ -106,6 +131,62 @@ export class ProviderFactory {
     /**
      * Get list of available providers
      */
+    /**
+     * Explain why a provider name did not resolve, usefully (#354).
+     *
+     * Three distinct situations used to share one generic message:
+     *
+     * - The registry is empty, because `ProviderRegistry.registerAllProviders()`
+     *   has not run yet. Every name is unresolvable, and listing zero available
+     *   providers tells the reader nothing about why.
+     * - The name IS a known provider but has no registration — recognised,
+     *   unavailable. Distinct from a typo and worth saying so.
+     * - The name is not a provider at all, in which case a near-miss is almost
+     *   always a typo and is worth naming: "opennai" -> "openai".
+     *
+     * Canonical names are offered as suggestions ahead of aliases, so a typo
+     * resolves to the name the docs use.
+     *
+     * @param requested - The provider name as the caller supplied it
+     * @returns A message naming the situation and what to do about it
+     */
+    static describeUnresolvableProvider(requested) {
+        const registered = ProviderFactory.getAvailableProviders();
+        if (registered.length === 0) {
+            return (`Cannot resolve provider "${requested}": no providers are registered yet. ` +
+                `ProviderRegistry.registerAllProviders() has not completed, so every name ` +
+                `is unresolvable at this point — this is a lifecycle problem, not a bad name.`);
+        }
+        // `registered` mixes canonical names and aliases (registerProvider sets
+        // both as separate map keys — see registerProvider above), and a name
+        // registered without a descriptor (a caller-supplied registerProvider()
+        // with no 5th argument) has no entry in PROVIDER_ALIAS_INDEX at all. Only
+        // PROVIDER_DESCRIPTORS would previously stand in for "what's registered",
+        // which listed every built-in provider whether or not this factory
+        // instance had actually registered it, and mislabelled a descriptor-less
+        // custom registration as an "alias" simply for not matching that static
+        // list. Deriving both lists from `registered` itself fixes both: a
+        // registered name canonicalizes to what PROVIDER_ALIAS_INDEX resolves it
+        // to (itself, when it has no descriptor), and only a name that resolves
+        // to a *different*, registered canonical name is a true alias.
+        const canonical = Array.from(new Set(registered.map((name) => PROVIDER_ALIAS_INDEX.get(name) ?? name))).sort();
+        const aliases = registered
+            .filter((name) => {
+            const target = PROVIDER_ALIAS_INDEX.get(name);
+            return target !== undefined && target !== name;
+        })
+            .sort();
+        const known = PROVIDER_ALIAS_INDEX.get(requested.toLowerCase());
+        if (known) {
+            return (`Provider "${requested}" is a recognised provider (${known}) but is not registered ` +
+                `in this factory, so it cannot be constructed. Registered providers: ${canonical.join(", ")}.`);
+        }
+        // Canonical names first so a tie resolves to the documented spelling.
+        const suggestions = suggestClosest(requested, [...canonical, ...aliases]);
+        const didYouMean = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+        return (`Unknown provider: "${requested}".${didYouMean} ` +
+            `Valid providers: ${canonical.join(", ")}. Accepted aliases: ${aliases.join(", ")}.`);
+    }
     static getAvailableProviders() {
         return Array.from(ProviderFactory.providers.keys()).filter((name, index, arr) => arr.indexOf(name) === index);
     }

package/dist/models/modelRegistry.d.ts

@@ -34,6 +34,31 @@ export declare function getAllModels(): ModelInfo[];
  * Get model by ID
  */
 export declare function getModelById(id: string): ModelInfo | undefined;
+/**
+ * Resolve a registry alias to the canonical model id for a given provider.
+ *
+ * The registry has carried per-model aliases ("gpt4o" -> "gpt-4o", "gpt4" ->
+ * "gpt-4") all along, and capability lookups like {@link modelSupports}
+ * already resolve through them — but the id actually sent to the provider did
+ * not, so `generate({ model: "gpt4o" })` put the alias on the wire and the
+ * provider 404'd. This closes that gap (#337).
+ *
+ * Deliberately conservative, because a wrong rewrite is worse than no rewrite:
+ *
+ * - An id the registry already knows is returned untouched, so a canonical id
+ *   can never be displaced by an alias that happens to collide with it.
+ * - An alias is only applied when the model it names belongs to the provider
+ *   being constructed. Without that check, an aggregator or self-hosted
+ *   deployment whose model is literally named "gpt4" would be silently
+ *   rewritten to OpenAI's "gpt-4".
+ * - Anything unrecognised passes through, so custom and brand-new model ids
+ *   keep working exactly as before.
+ *
+ * @param provider - Provider being constructed (canonical name)
+ * @param model - Model id or alias as the caller supplied it
+ * @returns The canonical id when an alias resolved, otherwise null
+ */
+export declare function resolveProviderModelAlias(provider: string, model: string): string | null;
 /**
  * Check whether a model supports a registered capability.
  *

package/dist/models/modelRegistry.js

@@ -2689,6 +2689,45 @@ export function getAllModels() {
 export function getModelById(id) {
     return MODEL_REGISTRY[id];
 }
+/**
+ * Resolve a registry alias to the canonical model id for a given provider.
+ *
+ * The registry has carried per-model aliases ("gpt4o" -> "gpt-4o", "gpt4" ->
+ * "gpt-4") all along, and capability lookups like {@link modelSupports}
+ * already resolve through them — but the id actually sent to the provider did
+ * not, so `generate({ model: "gpt4o" })` put the alias on the wire and the
+ * provider 404'd. This closes that gap (#337).
+ *
+ * Deliberately conservative, because a wrong rewrite is worse than no rewrite:
+ *
+ * - An id the registry already knows is returned untouched, so a canonical id
+ *   can never be displaced by an alias that happens to collide with it.
+ * - An alias is only applied when the model it names belongs to the provider
+ *   being constructed. Without that check, an aggregator or self-hosted
+ *   deployment whose model is literally named "gpt4" would be silently
+ *   rewritten to OpenAI's "gpt-4".
+ * - Anything unrecognised passes through, so custom and brand-new model ids
+ *   keep working exactly as before.
+ *
+ * @param provider - Provider being constructed (canonical name)
+ * @param model - Model id or alias as the caller supplied it
+ * @returns The canonical id when an alias resolved, otherwise null
+ */
+export function resolveProviderModelAlias(provider, model) {
+    const normalizedModel = model.toLowerCase();
+    if (MODEL_REGISTRY[model] || MODEL_REGISTRY[normalizedModel]) {
+        return null;
+    }
+    const aliasTarget = MODEL_ALIASES[normalizedModel];
+    if (!aliasTarget) {
+        return null;
+    }
+    const target = MODEL_REGISTRY[aliasTarget];
+    if (!target || target.provider !== provider.toLowerCase()) {
+        return null;
+    }
+    return target.id;
+}
 /**
  * Check whether a model supports a registered capability.
  *