@juspay/neurolink 12.18.0 → 12.19.0

package/dist/neurolink.js

@@ -34,6 +34,7 @@ import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRouti
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
 import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
+import { resolveDefaultDecisionProvider } from "./factories/providerDescriptors.js";
 import { resolveRequestKind } from "./core/resolveRequestKind.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderFactory } from "./factories/providerFactory.js";
@@ -66,6 +67,9 @@ import { getMetricsAggregator, MetricsAggregator, } from "./observability/metric
 import { AnalyticsService, calculateAdvancedCost, parseAnalyticsQualityScore, } from "./analytics/index.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
+import { withSpan } from "./telemetry/withSpan.js";
+import { getActiveTraceContext } from "./telemetry/traceContext.js";
+import { calculateCost } from "./utils/pricing.js";
 import { flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, stampGuestRescueIdentity, } from "./services/server/ai/observability/instrumentation.js";
 import { clearChecklistState, createChecklistTools, getChecklistState, resolveChecklistSessionId, } from "./agent/taskChecklist.js";
 import { cancelDelegates as cancelBackgroundDelegates, collectDelegates as collectBackgroundDelegates, configureDelegation, createDelegationTools, spawnDelegate as spawnBackgroundDelegate, } from "./agent/backgroundDelegation.js";
@@ -485,6 +489,10 @@ export class NeuroLink {
     // ClassifierRouter: opt-in "classify → pick model + tools" pre-call router.
     // Built from config.classifierRouter; null when not configured.
     classifierRouter;
+    // Tuning for the decision-driven relevance stage of context compaction.
+    // Undefined = the stage's own defaults; the stage itself is gated on a
+    // decision provider being configured, not on this.
+    contextRelevanceOptions;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -943,6 +951,10 @@ export class NeuroLink {
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
         this.requestRouter = config?.requestRouter ?? null;
+        // Tuning for the relevance stage of compaction. Storing it (rather than
+        // reading config at each call site) keeps compactor construction uniform
+        // across the five places that build one.
+        this.contextRelevanceOptions = config?.contextRelevance;
         // ClassifierRouter: opt-in. The LLM strategy reuses this instance's
         // generate() (marked so it never recursively re-routes). Fails open.
         this.classifierRouter = config?.classifierRouter?.enabled
@@ -950,6 +962,10 @@ export class NeuroLink {
                 generate: (genOptions) => this.generate({
                     ...genOptions,
                 }),
+                // Fail-open by construction: tryDecide returns null rather than
+                // throwing, so an absent or broken decision provider leaves routing
+                // exactly as it was.
+                decide: (decideOptions) => this.tryDecide(decideOptions),
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -3955,6 +3971,19 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Dependencies handed to every `ContextCompactor`.
+     *
+     * `tryDecide` returns null whenever no decision provider is configured or
+     * the call fails, so passing this unconditionally is safe: the compactor
+     * runs its previous pipeline unchanged and pays nothing for the option.
+     */
+    contextCompactorDeps() {
+        return {
+            decide: (decisionOptions) => this.tryDecide(decisionOptions),
+            relevance: this.contextRelevanceOptions,
+        };
+    }
     /**
      * Applies the host-configured `classifierRouter` to `options` in place.
      *
@@ -4029,12 +4058,47 @@ Current user's request: ${currentInput}`;
                             : [...allow];
                 }
             }
+            // Context budget: only ever narrowed, and only when the caller left it
+            // unset. A caller that pinned a threshold has made a statement about
+            // their own traffic that a per-request guess should not overrule.
+            if (decision.compactionThreshold !== undefined &&
+                options.compactionThreshold === undefined) {
+                options.compactionThreshold = decision.compactionThreshold;
+                logger.debug("[NeuroLink] classifierRouter context budget", {
+                    compactionThreshold: decision.compactionThreshold,
+                    contextScope: decision.contextScope,
+                });
+            }
             // Mark routed so orchestration/requestRouter stand down this turn.
             if (decision.provider || decision.model) {
                 const ctx = opt.context ?? {};
                 ctx.__classifierRouted = true;
                 opt.context = ctx;
             }
+            // Telemetry: a debug log is not an observability surface. Routing
+            // silently changes which model — and therefore which bill — serves a
+            // request, so the decision has to be visible on the trace next to the
+            // generation it produced.
+            try {
+                const activeSpan = trace.getActiveSpan();
+                if (activeSpan) {
+                    activeSpan.setAttribute("classifier_routing.difficulty", decision.difficulty ?? "unknown");
+                    activeSpan.setAttribute("classifier_routing.provider", options.provider ?? "");
+                    activeSpan.setAttribute("classifier_routing.model", options.model ?? "");
+                    if (decision.contextScope) {
+                        activeSpan.setAttribute("classifier_routing.context_scope", decision.contextScope);
+                    }
+                    if (decision.compactionThreshold !== undefined) {
+                        activeSpan.setAttribute("classifier_routing.compaction_threshold", decision.compactionThreshold);
+                    }
+                    if (decision.reason) {
+                        activeSpan.setAttribute("classifier_routing.reason", decision.reason);
+                    }
+                }
+            }
+            catch {
+                // Telemetry must never affect routing behaviour.
+            }
             if (decision.reason) {
                 logger.debug("[NeuroLink] classifierRouter decision", {
                     reason: decision.reason,
@@ -5142,7 +5206,7 @@ Current user's request: ${currentInput}`;
                     enableDeduplicate: true,
                     enableTruncate: true,
                     truncationFraction: fraction,
-                });
+                }, this.contextCompactorDeps());
                 const compactionResult = await compactor.compact(originalMessages, compactionTarget, undefined, options.context?.requestId);
                 if (!compactionResult.compacted) {
                     continue;
@@ -5715,6 +5779,7 @@ Current user's request: ${currentInput}`;
             conversationMessages: conversationMessages,
             currentPrompt: options.prompt,
             toolDefinitions: availableTools,
+            compactionThreshold: options.compactionThreshold,
         });
         logger.info("[TokenBudget] Token breakdown", {
             requestId,
@@ -5759,7 +5824,7 @@ Current user's request: ${currentInput}`;
             availableTools,
             conversationMessages,
             availableInputTokens: budgetResult.availableInputTokens,
-            historyBudget: resolveHistoryBudget(budgetResult),
+            historyBudget: resolveHistoryBudget(budgetResult, options.compactionThreshold),
             usageRatio: budgetResult.usageRatio,
             estimatedInputTokens: budgetResult.estimatedInputTokens,
             compactionSessionId,
@@ -5777,7 +5842,7 @@ Current user's request: ${currentInput}`;
             summarizationProvider: this.conversationMemoryConfig?.conversationMemory
                 ?.summarizationProvider,
             summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
-        });
+        }, this.contextCompactorDeps());
         // Fixed overhead (system + prompt + tools + files) already exceeds the
         // window — no amount of history compaction can fit this request, and
         // compacting to an empty history would only hide the real cause.
@@ -5792,7 +5857,7 @@ Current user's request: ${currentInput}`;
                 breakdown: {},
             });
         }
-        const compactionResult = await compactor.compact(conversationMessages, historyBudget, this.conversationMemoryConfig?.conversationMemory, requestId);
+        const compactionResult = await compactor.compact(conversationMessages, historyBudget, this.conversationMemoryConfig?.conversationMemory, requestId, { currentRequest: options.prompt });
         let compactedMessages = conversationMessages;
         if (compactionResult.compacted) {
             const repairedResult = repairToolPairs(compactionResult.messages);
@@ -6169,6 +6234,7 @@ Current user's request: ${currentInput}`;
                     toolDefinitions: options.tools
                         ? Object.values(options.tools)
                         : undefined,
+                    compactionThreshold: options.compactionThreshold,
                 });
                 const dpgMessageCount = conversationMessages?.length || 0;
                 const dpgCompactionSessionId = this.getCompactionSessionId(options);
@@ -6311,8 +6377,8 @@ Current user's request: ${currentInput}`;
                             ?.summarizationProvider,
                         summarizationModel: this.conversationMemoryConfig?.conversationMemory
                             ?.summarizationModel,
-                    });
-                    const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(budgetCheck), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+                    }, this.contextCompactorDeps());
+                    const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(budgetCheck, options.compactionThreshold), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId, { currentRequest: options.prompt });
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         conversationMessages = repairedResult.messages;
@@ -7158,6 +7224,14 @@ Current user's request: ${currentInput}`;
                     if (decision.granularity !== undefined) {
                         activeSpan.setAttribute("tool_routing.granularity", decision.granularity);
                     }
+                    // Which router actually decided. Three strategies can produce an
+                    // "applied" outcome and they have wildly different cost and
+                    // latency profiles, so an outcome without a strategy cannot be
+                    // acted on — and a decision router that silently stopped firing
+                    // looks identical to one that was never configured.
+                    if (decision.strategy !== undefined) {
+                        activeSpan.setAttribute("tool_routing.strategy", decision.strategy);
+                    }
                 }
                 catch {
                     // Telemetry must never affect routing behaviour.
@@ -7288,6 +7362,14 @@ Current user's request: ${currentInput}`;
                         ...generateOptions,
                         abortSignal: options.abortSignal,
                     }),
+                    // Calibrated per-server routing when a decision provider is
+                    // configured. tryDecide returns null without one, so the resolver
+                    // falls straight through to the generative router as before.
+                    decideFn: (decisionOptions) => this.tryDecide({
+                        ...decisionOptions,
+                        signal: options.abortSignal,
+                    }),
+                    decisionMinDropConfidence: routingConfig.minDropConfidence,
                     emitDecision: captureDecision,
                     // L2 / ITEM D — only populated when embedding is configured.
                     embedFn: routingEmbedFn,
@@ -8570,6 +8652,7 @@ Current user's request: ${currentInput}`;
             conversationMessages: conversationMessages,
             currentPrompt: options.input.text,
             toolDefinitions: availableTools,
+            compactionThreshold: options.compactionThreshold,
         });
         const streamMessageCount = conversationMessages?.length || 0;
         const streamCompactionSessionId = this.getCompactionSessionId(options);
@@ -8617,9 +8700,10 @@ Current user's request: ${currentInput}`;
                 provider: providerName,
                 summarizationProvider: this.conversationMemoryConfig?.conversationMemory
                     ?.summarizationProvider,
-                summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
-            });
-            const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(streamBudget), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+                summarizationModel: this.conversationMemoryConfig?.conversationMemory
+                    ?.summarizationModel,
+            }, this.contextCompactorDeps());
+            const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(streamBudget, options.compactionThreshold), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId, { currentRequest: options.input.text });
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;
@@ -12563,6 +12647,166 @@ Current user's request: ${currentInput}`;
         logger.debug(`[NeuroLink] Created evaluation pipeline: ${config.name ?? "custom"}`);
         return pipeline;
     }
+    /**
+     * Run the `decide` inference type: evaluate a `state` against a batch of
+     * named, typed questions and get one typed answer each.
+     *
+     * This is NOT {@link NeuroLink.evaluate}, which scores an already-generated
+     * response with RAGAS scorers. `decide` calls a decision model — one that
+     * emits no text at all and returns calibrated, typed judgements your code
+     * can branch on.
+     *
+     * **Batch, never fan out.** On a decision model, latency is flat in
+     * question count (measured: 1 question 393ms, 400 questions 465ms) while
+     * concurrent requests queue. Put every question you might need into one
+     * call — speculative questions are nearly free, a second round trip is not.
+     *
+     * A `choice` answer carries the full probability distribution, so one
+     * question over N options also ranks all N.
+     *
+     * @example
+     * ```typescript
+     * const result = await neurolink.decide({
+     *   state: ticketText,
+     *   questions: {
+     *     team: {
+     *       type: "choice",
+     *       instructions: "Which team should handle this?",
+     *       criteria: { billing: "Payments", technical: "Bugs", sales: "Pricing" },
+     *     },
+     *     urgent: { type: "boolean", instructions: "Is this urgent?" },
+     *   },
+     * });
+     * const team = readDecisionChoice(result.answers, "team");
+     * if (team && team.confidence > 0.7) { assign(team.choice); }
+     * ```
+     *
+     * @throws when no decision provider is configured, or the call fails
+     */
+    async decide(options) {
+        const providerName = options.provider ?? resolveDefaultDecisionProvider();
+        if (!providerName) {
+            throw new Error("No decision provider is configured. Set TYPESAFE_API_KEY, or pass `provider` explicitly.");
+        }
+        const questionCount = Object.keys(options.questions).length;
+        // Observability parity with generate()/stream(): an OTEL span for the
+        // trace view, a serialized span for the in-process metrics aggregator,
+        // and a cost figure. Without these a decision model is invisible — and
+        // "invisible" is the failure mode that matters here, because every
+        // internal consumer is fail-open, so a decision path that has silently
+        // stopped working looks exactly like one that was never configured.
+        return withSpan({
+            name: `gen_ai.${providerName}.decide`,
+            tracer: tracers.decision,
+            attributes: {
+                "gen_ai.system": providerName,
+                "gen_ai.operation.name": "decide",
+                "ai.provider": providerName,
+                "decision.question_count": questionCount,
+            },
+        }, async (otelSpan) => {
+            const { traceId, parentSpanId } = getActiveTraceContext();
+            const startedAt = Date.now();
+            let span = SpanSerializer.createSpan(SpanType.MODEL_DECISION, `decision.${providerName}`, {
+                "ai.provider": providerName,
+                "ai.model": options.model ?? "",
+                "decision.question_count": questionCount,
+            }, parentSpanId, traceId);
+            try {
+                // enableMCP: false — a decision model has no tools and never will.
+                const provider = await AIProviderFactory.createProvider(providerName, options.model, false, this, undefined, this.resolveCredentials(options.credentials));
+                if (typeof provider.decide !== "function") {
+                    throw new Error(`Provider "${providerName}" does not serve the decide inference type.`);
+                }
+                const result = await provider.decide({
+                    state: options.state,
+                    questions: options.questions,
+                    model: options.model,
+                    signal: options.signal,
+                    timeoutMs: options.timeoutMs,
+                });
+                const answerCount = Object.keys(result.answers).length;
+                const cost = calculateCost(providerName, result.model, {
+                    input: result.usage.inputTokens,
+                    output: result.usage.outputTokens,
+                    total: result.usage.inputTokens + result.usage.outputTokens,
+                });
+                otelSpan.setAttribute("gen_ai.response.model", result.model);
+                otelSpan.setAttribute("gen_ai.usage.input_tokens", result.usage.inputTokens);
+                otelSpan.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
+                otelSpan.setAttribute("decision.answer_count", answerCount);
+                otelSpan.setAttribute("ai.cost.total", cost);
+                if (result.upstreamMs !== undefined) {
+                    otelSpan.setAttribute("decision.upstream_ms", result.upstreamMs);
+                }
+                if (result.requestId) {
+                    otelSpan.setAttribute("gen_ai.response.id", result.requestId);
+                }
+                span.durationMs = Date.now() - startedAt;
+                span = SpanSerializer.updateAttributes(span, {
+                    // The key names the cost aggregator reads. `ai.model` is
+                    // overwritten with the RESOLVED model (e.g. "jev-1.13.0"), not
+                    // the alias that was sent, so spend is attributed to what
+                    // actually ran.
+                    "ai.model": result.model,
+                    "ai.tokens.input": result.usage.inputTokens,
+                    "ai.tokens.output": result.usage.outputTokens,
+                    "ai.cost.input": cost,
+                    "ai.cost.output": 0,
+                    "ai.cost.total": cost,
+                    "decision.answer_count": answerCount,
+                    "decision.latency_ms": result.latencyMs,
+                    ...(result.upstreamMs !== undefined
+                        ? { "decision.upstream_ms": result.upstreamMs }
+                        : {}),
+                });
+                // BOTH aggregators, exactly as the generate path does. The
+                // instance one is what `neurolink.getMetrics()` / `getSpans()`
+                // read; the global one is what the exporters drain. Recording to
+                // only the global one would make a decision invisible to the very
+                // API a caller would use to check whether it ran.
+                const ended = SpanSerializer.endSpan(span, SpanStatus.OK);
+                this.metricsAggregator.recordSpan(ended);
+                getMetricsAggregator().recordSpan(ended);
+                return result;
+            }
+            catch (error) {
+                span.durationMs = Date.now() - startedAt;
+                const ended = SpanSerializer.endSpan(span, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
+                this.metricsAggregator.recordSpan(ended);
+                getMetricsAggregator().recordSpan(ended);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Fail-open {@link NeuroLink.decide}: returns null on any failure instead
+     * of throwing.
+     *
+     * This is the contract every internal consumer relies on. A decision model
+     * that is unconfigured, slow, rate-limited or down must never change
+     * NeuroLink's observable behaviour — the caller falls back to whatever it
+     * did before the decision was available.
+     */
+    async tryDecide(options) {
+        try {
+            const result = await this.decide(options);
+            if (logger.shouldLog("debug")) {
+                logger.debug(`decide: ${Object.keys(result.answers).length} answers in ${result.latencyMs}ms` +
+                    (result.upstreamMs ? ` (upstream ${result.upstreamMs}ms)` : ""), {
+                    provider: result.provider,
+                    model: result.model,
+                    requestId: result.requestId,
+                    usage: result.usage,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            logger.debug(`decide unavailable: ${error instanceof Error ? error.message : String(error)} — falling back`);
+            return null;
+        }
+    }
     /**
      * Evaluate an AI response using the specified pipeline or scorers.
      * This is a convenience method that creates a pipeline and executes it in one call.
@@ -13796,7 +14040,7 @@ Current user's request: ${currentInput}`;
                     ?.summarizationProvider,
             summarizationModel: config?.summarizationModel ??
                 this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
-        });
+        }, this.contextCompactorDeps());
         // Use actual context window to determine target, not arbitrary heuristic
         const budgetInfo = checkContextBudget({
             provider: config?.provider || "openai",

package/dist/observability/exporters/laminarExporter.js

@@ -222,6 +222,9 @@ export class LaminarExporter extends BaseExporter {
             [SpanType.WORKFLOW_STEP]: "workflow",
             [SpanType.TOOL_CALL]: "tool",
             [SpanType.MODEL_GENERATION]: "llm",
+            // Laminar has no decision primitive; "llm" is the closest bucket that
+            // keeps it visible on a model-spend view.
+            [SpanType.MODEL_DECISION]: "llm",
             [SpanType.EMBEDDING]: "embedding",
             [SpanType.RETRIEVAL]: "retrieval",
             [SpanType.MEMORY]: "memory",

package/dist/observability/exporters/posthogExporter.js

@@ -205,6 +205,9 @@ export class PostHogExporter extends BaseExporter {
             [SpanType.WORKFLOW_STEP]: "ai_workflow_step",
             [SpanType.TOOL_CALL]: "ai_tool_call",
             [SpanType.MODEL_GENERATION]: "ai_generation",
+            // A distinct event name: a decision is not a generation, and merging
+            // them would silently inflate generation funnels in PostHog.
+            [SpanType.MODEL_DECISION]: "ai_decision",
             [SpanType.EMBEDDING]: "ai_embedding",
             [SpanType.RETRIEVAL]: "ai_retrieval",
             [SpanType.MEMORY]: "ai_memory_operation",

package/dist/observability/utils/spanSerializer.js

@@ -223,6 +223,10 @@ export class SpanSerializer {
             [SpanType.WORKFLOW_STEP]: "chain",
             [SpanType.TOOL_CALL]: "tool",
             [SpanType.MODEL_GENERATION]: "llm",
+            // Langfuse observation kinds are a closed set with no decision member;
+            // "llm" keeps the call on the model-cost views, which is where a
+            // reader looking for spend will go find it.
+            [SpanType.MODEL_DECISION]: "llm",
             [SpanType.EMBEDDING]: "embedding",
             [SpanType.RETRIEVAL]: "retriever",
             [SpanType.MEMORY]: "chain",

package/dist/providers/catalog/schema.d.ts

@@ -73,8 +73,8 @@ export declare const providerCatalogJsonSchema: z.ZodObject<{
         class: z.ZodEnum<{
             network: "network";
             provider: "provider";
-            "invalid-model": "invalid-model";
             authentication: "authentication";
+            "invalid-model": "invalid-model";
             "rate-limit": "rate-limit";
         }>;
         message: z.ZodString;

package/dist/providers/typesafe.d.ts

@@ -0,0 +1,112 @@
+import type { AIProviderName } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import type { DecisionModelCard, DecisionRequest, DecisionResult, LanguageModel, NeurolinkCredentials, StreamOptions, StreamResult, ValidationSchema } from "../types/index.js";
+/**
+ * The binding limit in practice: `state` plus the SINGLE LONGEST question.
+ * Measured by bisection at single-character resolution — 33,002 reported
+ * input tokens accepted, 33,003 not.
+ */
+export declare const TYPESAFE_MAX_STATE_TOKENS = 33000;
+/**
+ * The separate, larger ceiling on `state` plus ALL questions combined. A
+ * request can carry a near-ceiling state *and* 400 extra questions (37,679
+ * tokens total, verified) — questions do not compete with state for the
+ * 33K budget, only for this one.
+ */
+export declare const TYPESAFE_MAX_REQUEST_TOKENS = 64000;
+/**
+ * TypeSafe Provider — the `decide` inference type only.
+ *
+ * Jev is a "System One" model: it takes one `state` plus a map of typed
+ * questions and returns one typed answer each, evaluated in a single
+ * parallel pass. It emits no text, so `generate()` / `stream()` are not
+ * available and `getAISDKModel()` throws — the same shape Voyage and Jina
+ * already use for embedding-only providers.
+ *
+ * Its descriptor declares `inferenceKinds: ["decide"]`, which keeps it out
+ * of auto-select and the health sweep, so those throws should be unreachable
+ * in practice.
+ *
+ * Two measured properties shape the API: latency is flat in question count
+ * (1 question 393ms, 400 questions 465ms) while concurrent requests queue.
+ * Callers therefore batch every question into one `decide()` call.
+ *
+ * Two transports reach the same model. The direct one is TypeSafe's own API,
+ * billed against a TypeSafe key. The gateway one is Vercel's AI Gateway
+ * evaluation-model route, billed against a Vercel account — useful to a host
+ * that already has one and does not want a second vendor relationship. They
+ * differ on the wire (vocabulary, where the model is named, and whether
+ * `confidence` is reported at all) and not at all in `DecisionResult`; the
+ * one thing to know is that gateway confidence is DERIVED from the
+ * probability distribution rather than being the vendor's calibrated figure,
+ * so a threshold tuned on one transport should be re-checked on the other.
+ *
+ * @see https://docs.typesafe.ai/api
+ */
+export declare class TypeSafeProvider extends BaseProvider {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly proxyFetch;
+    private readonly maxRetries;
+    /** Which wire this instance speaks. Resolved once, in the constructor. */
+    private readonly transport;
+    /**
+     * Set once the key has been rejected. A bad key cannot fix itself, and
+     * without this every later request would pay a full round trip (~265ms
+     * measured) to be told so again — a permanent tax on the hot path for a
+     * misconfiguration.
+     */
+    private authFailed;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["typesafe"]);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getDefaultDecisionModel(): string | undefined;
+    supportsTools(): boolean;
+    /**
+     * Jev produces no text, so there is no chat model behind this provider.
+     * Unreachable while the descriptor declares `inferenceKinds: ["decide"]`;
+     * kept actionable for the case where something routes here anyway.
+     */
+    protected getAISDKModel(): LanguageModel;
+    protected executeStream(_options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    /**
+     * Must RETURN the error, never throw it (CLAUDE.md rule 6).
+     */
+    protected formatProviderError(error: unknown): Error;
+    /**
+     * Evaluate a state against a batch of typed questions.
+     *
+     * Throws a {@link ProviderError} carrying a normalised {@link DecisionError}
+     * in `cause`. Internal hot paths should prefer `NeuroLink.tryDecide()`,
+     * which returns null instead.
+     */
+    decide(request: DecisionRequest): Promise<DecisionResult>;
+    /** Where a decision request goes for this instance's transport. */
+    private endpoint;
+    /**
+     * Headers for this instance's transport.
+     *
+     * The gateway's three `ai-*` headers are all load-bearing:
+     * `ai-gateway-protocol-version` omitted fails the request outright rather
+     * than defaulting, `ai-model-id` is how the model is named at all (the body
+     * carries no `model`), and `ai-evaluation-model-specification-version`
+     * selects the request/response shape this provider parses.
+     */
+    private headers;
+    /** Which transport this instance resolved to. Exposed for diagnostics. */
+    getDecisionTransport(): "direct" | "gateway";
+    /**
+     * The model aliases this key may send in `model`.
+     *
+     * Direct transport only: the gateway names the model in a header and
+     * publishes its own catalogue, so there is no equivalent listing behind
+     * this key.
+     */
+    listDecisionModels(): Promise<DecisionModelCard[]>;
+    /**
+     * Wrap a normalised decision failure in the provider error type, keeping
+     * the structured detail reachable via `cause` for callers that branch on
+     * `kind` (authentication vs rate_limit vs max_tokens_exceeded).
+     */
+    private decisionError;
+}