@zhivex-ai/gateway 1.2.2 → 1.4.0

package/dist/index.js

@@ -1,4 +1,17 @@
-import { ConflictError, GuardrailTriggeredError, ProviderHTTPError, ValidationError, createAgent, createStructuredOutputPrompt, createTextMessage, generateObject, generateText, runAgent, streamAgent, streamObject, streamText } from "@zhivex-ai/core";
+import { targetKey, sameTarget } from "./target.js";
+import { operationControl, GatewayDeadlineError } from "./operation.js";
+import { createGatewayExecutor, cachedResults } from "./execution.js";
+import { GatewayBudgetError } from "./budget.js";
+import { GatewayAdmissionError } from "./admission.js";
+export { GatewayDeadlineError } from "./operation.js";
+export { createGatewayAdmissionController, GatewayAdmissionError } from "./admission.js";
+export { createGatewayBudgetStore, GatewayBudgetError } from "./budget.js";
+export { createGatewayRoutingPolicy } from "./adaptive-routing.js";
+import { ConflictError, GuardrailTriggeredError, ProviderHTTPError, ValidationError, createAgent, calculateModelCost, createStructuredOutputPrompt, createTextMessage, generateObject, generateText, runAgent, streamAgent, streamObject, streamText } from "@zhivex-ai/core";
+import { GatewayCircuitOpenError } from "./circuit-breaker.js";
+import { scoreAdaptiveTarget, validateAdaptivePolicy } from "./adaptive-routing.js";
+export { createGatewayCircuitBreaker, GatewayCircuitOpenError } from "./circuit-breaker.js";
+export { createGatewayMetrics } from "./metrics.js";
 import { createRouteDecision, gatewayMessagesToModelMessages } from "./compat.js";
 import { hasToolHistory, validateGatewayMessages } from "./history.js";
 import { GatewayError } from "./types.js";
@@ -59,7 +72,7 @@ const scoreTarget = (mode, intent, target, primary, config) => {
         mode,
         intent,
         target,
-        isPrimary: target.provider === primary.provider && target.modelId === primary.modelId,
+        isPrimary: sameTarget(target, primary),
         configuredCostPer1kTokens: config.providerCostsPer1kTokens?.[target.provider],
         catalogCostPer1kTokens: config.modelCatalog?.find(target.provider, target.modelId)?.costPer1kTokens,
         latencyBiasMs: config.latencyBiasMs?.[target.provider]
@@ -107,11 +120,21 @@ const validateTarget = (target, label) => {
 const validateRouteRequest = (config, request) => {
     if (request.messages !== undefined)
         validateGatewayMessages(request.messages);
+    if (config.budget && !request.budgetScope)
+        throw new GatewayBudgetError();
     const fallbacks = request.fallbacks ?? [];
+    for (const scope of [request.budgetScope, request.cacheScope, request.affinityKey]) {
+        if (scope !== undefined && (typeof scope !== "string" || !scope.trim() || scope.length > 256))
+            throw new GatewayError("Invalid gateway scope.", false);
+    }
     const maxFallbacks = getMaxFallbacks(config);
     if (fallbacks.length > maxFallbacks) {
         throw new GatewayError(`Gateway request contains ${fallbacks.length} fallback targets; the configured maximum is ${maxFallbacks}.`, false);
     }
+    for (const target of [request.primary, ...fallbacks]) {
+        if (target.deploymentId !== undefined && (typeof target.deploymentId !== "string" || !/^[a-zA-Z0-9_.-]{1,128}$/.test(target.deploymentId)))
+            throw new GatewayError("Invalid deploymentId.", false);
+    }
     validateTarget(request.primary, "Gateway primary target");
     fallbacks.forEach((target, index) => validateTarget(target, `Gateway fallback target at index ${index}`));
     if (request.maxCostPer1kTokens != null &&
@@ -121,7 +144,7 @@ const validateRouteRequest = (config, request) => {
     }
 };
 const orderTargets = (mode, intent, primary, fallbacks, config) => [primary, ...fallbacks]
-    .filter((target, index, list) => list.findIndex((candidate) => candidate.provider === target.provider && candidate.modelId === target.modelId) === index)
+    .filter((target, index, list) => list.findIndex((candidate) => sameTarget(candidate, target)) === index)
     .map((target, index) => ({
     target,
     index,
@@ -227,6 +250,7 @@ const createAttemptControl = (parentSignal, timeoutMs) => {
             reject(controller.signal.reason instanceof Error ? controller.signal.reason : timeoutError);
         };
         if (controller.signal.aborted) {
+            void promise.catch(() => undefined);
             onAbort();
             return;
         }
@@ -276,6 +300,8 @@ const redactSensitiveErrorMessage = (message) => message
     .replace(/([?&](?:api[-_]?key|key|token|access[-_]?token|secret)=)[^&#\s]*/gi, "$1[REDACTED]")
     .replace(/\b(Bearer)\s+[a-z\d._~+/=-]+/gi, "$1 [REDACTED]");
 const normalizeError = (error) => {
+    if (error instanceof GatewayBudgetError || error instanceof GatewayDeadlineError)
+        return { error, retrySameTarget: false, fallbackNextTarget: false };
     if (error instanceof ValidationError || error instanceof ConflictError || error instanceof GuardrailTriggeredError) {
         return {
             error: new GatewayError(redactSensitiveErrorMessage(error.message), false),
@@ -367,6 +393,7 @@ const retryBackoffMs = (config, retry, retryAfterMs) => {
 const createAttempt = (target, ok, latencyMs, targetRank, options = {}) => ({
     provider: target.provider,
     modelId: target.modelId,
+    ...(target.deploymentId ? { deploymentId: target.deploymentId } : {}),
     ok,
     latencyMs,
     targetRank,
@@ -406,24 +433,27 @@ const runBoundedObserver = (config, parentSignal, observer) => {
         return;
     }
     const completion = Promise.resolve(observerResult).catch(() => undefined);
-    void Promise.race([completion, boundary]).finally(cleanup);
+    return Promise.race([completion, boundary]).finally(cleanup);
 };
 const notifyAttempt = async (config, attempt, parentSignal) => {
     if (!config.onAttempt) {
         return;
     }
-    runBoundedObserver(config, parentSignal, (abortSignal) => config.onAttempt?.({
+    const completion = runBoundedObserver(config, parentSignal, (abortSignal) => config.onAttempt?.({
         ...attempt,
         retry: attempt.retry ?? 0,
         targetRank: attempt.targetRank ?? 0,
         abortSignal
     }));
+    if (config.observerMode === "await" || config.observerMode === "background")
+        await completion;
 };
 const normalizeUsage = (usage, inputText, outputText) => {
     const inputTokens = usage?.inputTokens ?? estimateTokens(inputText);
     const outputTokens = usage?.outputTokens ?? estimateTokens(outputText);
     const totalTokens = usage?.totalTokens ?? inputTokens + outputTokens;
     return {
+        ...usage,
         inputTokens,
         outputTokens,
         totalTokens,
@@ -494,11 +524,41 @@ const historyAbortSignal = (signal) => {
     historySignals.set(signal, controller.signal);
     return controller.signal;
 };
-const assertLegacyAgentMessages = (request) => {
-    if (request.messages?.some((message) => "parts" in message)) {
-        throw new GatewayError("Canonical gateway history is not supported by agent operations.", false);
+const prepareAgentHistoryRequest = (request) => {
+    if (request.prompt !== undefined && request.messages !== undefined)
+        throw new GatewayError("Pass prompt or messages, not both.", false);
+    if (!request.messages?.some(message => "parts" in message))
+        return request;
+    validateGatewayMessages(request.messages);
+    if (request.state || request.runId || request.handoff || request.approvals || request.idempotencyKey) {
+        throw new GatewayError("Import canonical agent history as a fresh run; resume durable state using state or runId without messages or an import idempotency key.", false);
     }
+    return { ...request, metadata: { ...request.metadata, gatewayPortableHistory: true }, abortSignal: historyAbortSignal(request.abortSignal) };
 };
+const agentHistoryStore = (store, context, binding) => store ? new Proxy(store, {
+    get(target, key) {
+        const value = Reflect.get(target, key);
+        if (key === "load")
+            return async (...args) => {
+                const state = await target.load(...args);
+                if (state && binding !== undefined && state.metadata?.gatewayAgentRouteBinding !== binding)
+                    throw new ConflictError("Agent state belongs to a different gateway route binding.");
+                if (state?.metadata?.gatewayPortableHistory === true)
+                    context.toolHistory = true;
+                return state;
+            };
+        if (key === "claimIdempotencyKey" && target.claimIdempotencyKey)
+            return async (...args) => {
+                const claim = await target.claimIdempotencyKey(...args);
+                if (binding !== undefined && claim.state.metadata?.gatewayAgentRouteBinding !== binding)
+                    throw new ConflictError("Agent idempotency key belongs to a different gateway route binding.");
+                if (claim.state.metadata?.gatewayPortableHistory === true)
+                    context.toolHistory = true;
+                return claim;
+            };
+        return typeof value === "function" ? value.bind(target) : value;
+    }
+}) : undefined;
 const buildRequiredCapabilities = (request, extra = {}) => ({
     ...(request.requiredCapabilities ?? {}),
     ...(request.tools || requestHasToolHistory(request) ? { tools: true } : {}),
@@ -595,6 +655,9 @@ const createAgentRunInput = (request) => {
         providerOptions: request.providerOptions,
         policy: request.policy,
         metadata: request.metadata,
+        context: request.context,
+        compaction: request.compaction,
+        executionEnvironment: request.executionEnvironment,
         abortSignal: request.abortSignal
     };
 };
@@ -611,12 +674,115 @@ const enrichAgentResult = (target, attempts, routeDecision, startedAt, result) =
     }
 });
 export const createGateway = (config) => {
+    for (const value of [config.resourceTimeoutMs, config.cache?.timeoutMs]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1 || value > 60000))
+            throw new GatewayError("Invalid resource/cache timeout.", false);
+    }
+    const executor = createGatewayExecutor(config);
+    if (config.budget && (!config.modelCatalog || !config.budget.currency.trim() || !Number.isFinite(config.budget.reserveAmount) || config.budget.reserveAmount <= 0))
+        throw new GatewayError("Budget requires a catalog, currency and positive reservation amount.", false);
+    if (config.cache && !config.cache.scope.trim())
+        throw new GatewayError("Cache requires an authentication scope.", false);
+    if (config.observerMode !== undefined && !["legacy", "await", "background"].includes(config.observerMode))
+        throw new GatewayError("Invalid observer mode.", false);
+    const observerCapacity = config.observerQueueCapacity ?? 256;
+    if (!Number.isSafeInteger(observerCapacity) || observerCapacity < 1 || observerCapacity > 10000)
+        throw new GatewayError("Invalid observer queue capacity.", false);
+    const affinityTtl = config.affinity?.ttlMs ?? 300000, affinityCapacity = config.affinity?.maxEntries ?? 1000, affinityLoss = config.affinity?.maxScoreLoss ?? 0;
+    if (config.affinity && (!config.adaptiveRouting || !Number.isSafeInteger(affinityTtl) || affinityTtl < 1 || affinityTtl > 86400000 || !Number.isSafeInteger(affinityCapacity) || affinityCapacity < 1 || affinityCapacity > 100000 || !Number.isFinite(affinityLoss) || affinityLoss < 0))
+        throw new GatewayError("Affinity requires adaptive routing and valid bounded limits.", false);
+    const affinities = new Map();
+    let routingOperations = 0, explorationCursor = 0;
+    const pendingObservers = new Set();
+    let droppedObservers = 0, observerTail = Promise.resolve();
+    const backgroundObserver = (action) => {
+        if (pendingObservers.size >= observerCapacity) {
+            droppedObservers++;
+            return;
+        }
+        const task = observerTail.then(action).catch(() => undefined);
+        observerTail = task;
+        pendingObservers.add(task);
+        void task.finally(() => pendingObservers.delete(task));
+    };
+    if (config.adaptiveRouting) {
+        validateAdaptivePolicy(config.adaptiveRouting);
+        if (config.scoreTarget)
+            throw new GatewayError("Choose adaptiveRouting or scoreTarget, not both.", false);
+    }
+    const configuredAgentRequest = (request) => {
+        const definition = request.agent;
+        if (!definition)
+            return request;
+        const defaults = {
+            agentId: definition.id, instructions: definition.instructions, tools: Array.isArray(definition.tools) ? Object.fromEntries(definition.tools.map(tool => [tool.name, tool])) : definition.tools,
+            maxSteps: definition.maxSteps, temperature: definition.temperature, maxTokens: definition.maxTokens,
+            reasoning: definition.reasoning, toolExecution: definition.toolExecution, toolApprovalPolicy: definition.toolApprovalPolicy,
+            providerOptions: definition.providerOptions, store: definition.store, memory: definition.memory,
+            onTelemetryEvent: definition.onTelemetryEvent, hookFailurePolicy: definition.hookFailurePolicy,
+            compaction: definition.compaction, executionEnvironment: definition.executionEnvironment
+        };
+        const merged = { ...defaults, ...Object.fromEntries(Object.entries(request).filter(([, value]) => value !== undefined)),
+            policy: { ...definition.policy, ...request.policy }, metadata: { ...definition.metadata, ...request.metadata }
+        };
+        const binding = JSON.stringify([1, merged.agentId ?? null, request.primary, request.fallbacks ?? [], config.adaptiveRouting?.version ?? "legacy", definition.harness?.fingerprint ?? null]);
+        merged.metadata = { ...merged.metadata, gatewayAgentRouteBinding: binding };
+        if (request.state && request.state.metadata?.gatewayAgentRouteBinding !== binding)
+            throw new ConflictError("Agent state belongs to a different gateway route binding.");
+        return merged;
+    };
+    const beginMetrics = (target, signal) => {
+        let handle;
+        try {
+            handle = config.metrics?.begin(target);
+        }
+        catch { /* Metrics cannot affect execution. */ }
+        let ended = false;
+        const end = (outcome, outputTokens) => {
+            if (ended)
+                return;
+            ended = true;
+            signal?.removeEventListener("abort", onAbort);
+            try {
+                handle?.end(outcome, outputTokens);
+            }
+            catch { /* Best effort. */ }
+        };
+        const onAbort = () => end("cancelled");
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        return { end, firstText: () => { try {
+                handle?.firstText();
+            }
+            catch { /* Best effort. */ } } };
+    };
+    if (config.costAccounting && !config.modelCatalog)
+        throw new GatewayError("costAccounting requires a modelCatalog snapshot.", false);
+    if (config.costAccounting?.unknownCostPolicy !== undefined && !["allow", "reject"].includes(config.costAccounting.unknownCostPolicy))
+        throw new GatewayError("Invalid detailed unknownCostPolicy.", false);
+    if (config.costAccounting?.cacheAssumption !== undefined && !["reported", "none"].includes(config.costAccounting.cacheAssumption))
+        throw new GatewayError("Invalid cacheAssumption.", false);
     const createRouteContext = (request, options = {}) => {
         validateRouteRequest(config, request);
         const mode = request.routingMode ?? "balanced";
         const intent = request.taskIntent ?? options.defaultIntent ?? "chat";
-        const orderedTargets = orderTargets(mode, intent, request.primary, request.fallbacks ?? [], config);
+        const orderedTargets = config.adaptiveRouting
+            ? [request.primary, ...(request.fallbacks ?? [])].filter((target, index, all) => all.findIndex(x => sameTarget(x, target)) === index)
+            : orderTargets(mode, intent, request.primary, request.fallbacks ?? [], config);
         const routeDecision = createRouteDecision(mode, intent, orderedTargets);
+        const affinityId = config.affinity && request.affinityKey && request.cacheScope
+            ? JSON.stringify([request.budgetScope ?? null, request.cacheScope, request.affinityKey]) : undefined;
+        if (config.costAccounting) {
+            routeDecision.estimatedCosts = orderedTargets.map(target => calculateModelCost({
+                catalog: config.modelCatalog, ...target,
+                usage: {
+                    inputTokens: estimateTokens([request.systemPrompt, request.system, request.instructions, request.prompt, JSON.stringify(request.messages ?? [])].filter(Boolean).join("\n")),
+                    outputTokens: config.costAccounting.expectedOutputTokens ?? request.maxTokens
+                },
+                cacheAssumption: "none", estimated: true
+            }));
+        }
         const attempts = [];
         const candidates = [];
         let notificationChain = Promise.resolve();
@@ -624,11 +790,16 @@ export const createGateway = (config) => {
             attempt = { ...attempt, ...(attempt.errorMessage !== undefined
                     ? { errorMessage: redactSensitiveErrorMessage(attempt.errorMessage) } : {}) };
             attempts.push(attempt);
-            notificationChain = notificationChain.then(() => notifyAttempt(config, attempt, request.abortSignal));
+            if (config.observerMode === "background")
+                backgroundObserver(() => notifyAttempt(config, attempt));
+            else
+                notificationChain = notificationChain.then(() => notifyAttempt(config, attempt, request.abortSignal));
         };
         const requiredCapabilities = buildRequiredCapabilities(request, options.extraRequiredCapabilities ?? {});
         for (const [targetRank, target] of orderedTargets.entries()) {
-            const adapter = config.adapters[target.provider];
+            const deployment = target.deploymentId === undefined ? undefined : config.deployments?.[target.deploymentId];
+            const adapter = target.deploymentId === undefined ? config.adapters[target.provider]
+                : deployment?.provider === target.provider ? deployment.adapter : undefined;
             if (!adapter) {
                 queueAttempt(createAttempt(target, false, 0, targetRank, {
                     reasonCode: "operation-skip",
@@ -670,6 +841,10 @@ export const createGateway = (config) => {
                 }));
                 continue;
             }
+            if (config.costAccounting?.unknownCostPolicy === "reject" && routeDecision.estimatedCosts?.[targetRank]?.status === "unknown") {
+                queueAttempt(createAttempt(target, false, 0, targetRank, { reasonCode: "cost-budget", errorMessage: "Skipped because detailed request cost is unknown." }));
+                continue;
+            }
             const skip = options.getSkipReason?.(model, target);
             if (skip) {
                 queueAttempt(createAttempt(target, false, 0, targetRank, {
@@ -680,10 +855,62 @@ export const createGateway = (config) => {
             }
             candidates.push({ target, targetRank, model });
         }
+        if (config.adaptiveRouting) {
+            const policy = config.adaptiveRouting;
+            const evaluated = orderedTargets.map((target, index) => {
+                const candidate = candidates.find(x => x.target === target);
+                let snapshot;
+                try {
+                    snapshot = config.metrics?.snapshot(target);
+                }
+                catch { /* Treat unavailable metrics as cold start. */ }
+                const evaluation = scoreAdaptiveTarget(policy, target, intent, snapshot, routeDecision.estimatedCosts?.[index]);
+                if (!candidate)
+                    evaluation.exclusions.push(...attempts.filter(x => sameTarget(x, target)).map(x => x.reasonCode ?? "operation-skip"));
+                if (config.circuitBreaker && !config.circuitBreaker.canAttempt(target))
+                    evaluation.exclusions.push("circuit-open");
+                if (evaluation.exclusions.length && candidate)
+                    queueAttempt(createAttempt(target, false, 0, index, { reasonCode: evaluation.exclusions.includes("circuit-open") ? "circuit-open" : "operation-skip", errorMessage: `Adaptive exclusion: ${evaluation.exclusions.join(", ")}.` }));
+                return evaluation;
+            });
+            routeDecision.reasonCode = "routing-adaptive";
+            routeDecision.adaptive = { policyVersion: policy.version, candidates: evaluated };
+            const byTarget = new Map(evaluated.map(value => [targetKey(value.target), value]));
+            const eligible = candidates.filter(candidate => !byTarget.get(targetKey(candidate.target)).exclusions.length);
+            eligible.sort((left, right) => byTarget.get(targetKey(right.target)).score - byTarget.get(targetKey(left.target)).score || left.targetRank - right.targetRank);
+            const every = policy.explorationEvery;
+            if (every && ++routingOperations % every === 0) {
+                const cold = eligible.filter(candidate => byTarget.get(targetKey(candidate.target)).missingSignals.includes("health"));
+                if (cold.length) {
+                    const probe = cold[explorationCursor++ % cold.length];
+                    eligible.splice(eligible.indexOf(probe), 1);
+                    eligible.unshift(probe);
+                    routeDecision.adaptive.exploration = true;
+                }
+            }
+            const sticky = affinityId ? affinities.get(affinityId) : undefined;
+            if (sticky && sticky.expires <= Date.now())
+                affinities.delete(affinityId);
+            if (sticky && sticky.expires > Date.now() && !routeDecision.adaptive.exploration && eligible.length) {
+                const index = eligible.findIndex(candidate => targetKey(candidate.target) === sticky.target);
+                if (index > 0 && byTarget.get(targetKey(eligible[0].target)).score - byTarget.get(sticky.target).score <= affinityLoss) {
+                    eligible.unshift(eligible.splice(index, 1)[0]);
+                    routeDecision.adaptive.affinity = true;
+                }
+            }
+            candidates.splice(0, candidates.length, ...eligible);
+            candidates.forEach((candidate, index) => { candidate.targetRank = index; });
+            routeDecision.orderedTargets = candidates.map(x => x.target);
+            routeDecision.reason = `Ordered by adaptive policy ${policy.version}; ties preserve request order.`;
+        }
         if (!candidates.length) {
+            if (attempts.at(-1)?.reasonCode === "circuit-open")
+                throw new GatewayCircuitOpenError();
             throw new GatewayError(attempts.at(-1)?.errorMessage ?? "No gateway target satisfied the request.", false);
         }
         const context = {
+            budgetScope: request.budgetScope,
+            cacheScope: request.cacheScope,
             toolHistory: requestHasToolHistory(request),
             attempts,
             candidates,
@@ -691,12 +918,29 @@ export const createGateway = (config) => {
             startedAt: Date.now(),
             flushAttempts: () => notificationChain,
             recordAttempt: async (attempt) => {
+                if (affinityId && attempt.ok && attempt.reasonCode === "provider-success") {
+                    affinities.delete(affinityId);
+                    if (affinities.size >= affinityCapacity)
+                        affinities.delete(affinities.keys().next().value);
+                    affinities.set(affinityId, { target: targetKey(attempt), expires: Date.now() + affinityTtl });
+                }
+                if (config.costAccounting && ["provider-success", "provider-error", "request-aborted"].includes(attempt.reasonCode ?? "")) {
+                    const costInput = { catalog: config.modelCatalog, provider: attempt.provider, modelId: attempt.modelId };
+                    try {
+                        attempt = { ...attempt, cost: calculateModelCost({ ...costInput, usage: attempt.cacheHit ? { inputTokens: 0, outputTokens: 0, totalTokens: 0, cachedInputTokens: 0, cacheWriteTokens: 0 } : attempt.usage, cacheAssumption: config.costAccounting.cacheAssumption, reasoningAccounting: config.costAccounting.reasoningAccounting?.[attempt.provider] }) };
+                    }
+                    catch {
+                        // Accounting cannot turn a successful model invocation into a retry.
+                        const cost = calculateModelCost(costInput);
+                        cost.unknownReasons.push("invalid-reported-usage");
+                        attempt = { ...attempt, cost };
+                    }
+                }
                 queueAttempt(attempt);
                 await notificationChain;
             },
             lock: async (candidate) => {
-                if (context.winner?.target.provider === candidate.target.provider &&
-                    context.winner.target.modelId === candidate.target.modelId) {
+                if (context.winner && sameTarget(context.winner.target, candidate.target)) {
                     return;
                 }
                 context.winner = candidate;
@@ -743,6 +987,10 @@ export const createGateway = (config) => {
             }));
         };
         const throwFinalError = () => {
+            if (context.attempts.at(-1)?.reasonCode === "circuit-open")
+                throw new GatewayCircuitOpenError();
+            if (context.attempts.at(-1)?.reasonCode === "admission-denied")
+                throw new GatewayAdmissionError();
             throw new GatewayError(context.attempts.at(-1)?.errorMessage ?? "All gateway attempts failed.", false);
         };
         const generate = async (input) => {
@@ -754,24 +1002,41 @@ export const createGateway = (config) => {
             for (const candidate of candidates) {
                 const candidateInput = prepareInput(candidate.model, input);
                 const inputSkipReason = modelInputSkipReason(candidate.model, candidateInput) ??
-                    (context.toolHistory ? historyInputSkipReason(candidate.model, input) : undefined);
+                    (context.toolHistory ? historySkipReason(candidate.model, hasToolHistory(input.messages)) ?? historyInputSkipReason(candidate.model, input) : undefined);
                 if (inputSkipReason) {
                     await recordInputSkip(candidate, inputSkipReason);
                     continue;
                 }
                 for (let retry = 0; retry <= maxRetries; retry += 1) {
-                    reserveProviderAttempt();
+                    const timeoutMs = getAttemptTimeoutMs(config, candidate.target.provider);
+                    const permit = config.circuitBreaker?.acquire(candidate.target);
+                    if (config.circuitBreaker && !permit) {
+                        await context.recordAttempt(createAttempt(candidate.target, false, 0, candidate.targetRank, { reasonCode: "circuit-open", errorMessage: "Destination circuit is open or probe capacity is exhausted." }));
+                        break;
+                    }
+                    try {
+                        reserveProviderAttempt();
+                    }
+                    catch (error) {
+                        permit?.end("neutral");
+                        throw error;
+                    }
                     const attemptStartedAt = Date.now();
-                    const control = createAttemptControl(input.abortSignal, getAttemptTimeoutMs(config, candidate.target.provider));
+                    const control = createAttemptControl(input.abortSignal, timeoutMs);
+                    const metrics = beginMetrics(candidate.target, input.abortSignal);
                     try {
-                        const result = await control.waitFor(candidate.model.generate({
+                        const result = await control.waitFor(executor.generate(candidate.model, candidate.target, {
                             ...prepareHistoryInput(candidate.model, candidateInput, context.toolHistory),
                             abortSignal: control.signal
-                        }));
+                        }, context.budgetScope, context.cacheScope));
                         control.stopTimeout();
+                        metrics.end(cachedResults.has(result) ? "cache" : "success", result.usage?.outputTokens);
+                        permit?.end(cachedResults.has(result) ? "neutral" : "success");
                         await context.recordAttempt(createAttempt(candidate.target, true, Date.now() - attemptStartedAt, candidate.targetRank, {
                             retry,
-                            reasonCode: "provider-success"
+                            reasonCode: "provider-success",
+                            ...(cachedResults.has(result) ? { cacheHit: true } : {}),
+                            ...(config.costAccounting ? { usage: result.usage } : {})
                         }));
                         await context.lock(candidate);
                         control.dispose();
@@ -779,10 +1044,12 @@ export const createGateway = (config) => {
                     }
                     catch (rawError) {
                         const callerAborted = input.abortSignal?.aborted === true;
+                        metrics.end(callerAborted || rawError instanceof GatewayAdmissionError || rawError instanceof GatewayBudgetError ? "cancelled" : "error");
                         const error = control.timedOut() ? control.timeoutError : rawError;
                         control.abort(error);
                         control.dispose();
                         if (callerAborted) {
+                            permit?.end("neutral");
                             await context.recordAttempt(createAttempt(candidate.target, false, Date.now() - attemptStartedAt, candidate.targetRank, {
                                 retry,
                                 reasonCode: "request-aborted",
@@ -791,11 +1058,14 @@ export const createGateway = (config) => {
                             throw abortReason(input.abortSignal);
                         }
                         const disposition = dispositionFor(error);
+                        permit?.end(disposition.retrySameTarget ? "retryable-error" : "neutral", disposition.retryAfterMs);
                         await context.recordAttempt(createAttempt(candidate.target, false, Date.now() - attemptStartedAt, candidate.targetRank, {
                             retry,
-                            reasonCode: "provider-error",
+                            reasonCode: error instanceof GatewayAdmissionError ? "admission-denied" : error instanceof GatewayBudgetError ? "budget-denied" : "provider-error",
                             errorMessage: disposition.error.message
                         }));
+                        if (config.circuitBreaker?.snapshot(candidate.target)?.state === "open")
+                            break;
                         if (retry < maxRetries && disposition.retrySameTarget) {
                             await abortableSleep(retryBackoffMs(config, retry, disposition.retryAfterMs), input.abortSignal);
                             continue;
@@ -818,7 +1088,7 @@ export const createGateway = (config) => {
             for (const candidate of candidates) {
                 const candidateInput = prepareInput(candidate.model, input);
                 const inputSkipReason = modelInputSkipReason(candidate.model, candidateInput) ??
-                    (context.toolHistory ? historyInputSkipReason(candidate.model, input) : undefined);
+                    (context.toolHistory ? historySkipReason(candidate.model, hasToolHistory(input.messages)) ?? historyInputSkipReason(candidate.model, input) : undefined);
                 if (inputSkipReason) {
                     await recordInputSkip(candidate, inputSkipReason);
                     continue;
@@ -828,15 +1098,28 @@ export const createGateway = (config) => {
                     continue;
                 }
                 for (let retry = 0; retry <= maxRetries; retry += 1) {
-                    reserveProviderAttempt();
+                    const timeoutMs = getAttemptTimeoutMs(config, candidate.target.provider);
+                    const permit = config.circuitBreaker?.acquire(candidate.target);
+                    if (config.circuitBreaker && !permit) {
+                        await context.recordAttempt(createAttempt(candidate.target, false, 0, candidate.targetRank, { reasonCode: "circuit-open", errorMessage: "Destination circuit is open or probe capacity is exhausted." }));
+                        break;
+                    }
+                    try {
+                        reserveProviderAttempt();
+                    }
+                    catch (error) {
+                        permit?.end("neutral");
+                        throw error;
+                    }
                     const attemptStartedAt = Date.now();
-                    const control = createAttemptControl(input.abortSignal, getAttemptTimeoutMs(config, candidate.target.provider));
+                    const control = createAttemptControl(input.abortSignal, timeoutMs);
                     let iterator;
+                    const metrics = beginMetrics(candidate.target, input.abortSignal);
                     try {
-                        const providerStream = await control.waitFor(candidate.model.stream({
+                        const providerStream = await control.waitFor(executor.stream(candidate.model, candidate.target, {
                             ...prepareHistoryInput(candidate.model, candidateInput, context.toolHistory),
                             abortSignal: control.signal
-                        }));
+                        }, context.budgetScope));
                         iterator = providerStream[Symbol.asyncIterator]();
                         const firstEvent = await control.waitFor(iterator.next());
                         if (firstEvent.done) {
@@ -845,6 +1128,8 @@ export const createGateway = (config) => {
                         if (firstEvent.value.type === "error") {
                             throw firstEvent.value.error;
                         }
+                        if (firstEvent.value.type === "text-delta")
+                            metrics.firstText();
                         control.stopTimeout();
                         await context.lock(candidate);
                         const streamIdleTimeoutMs = getStreamIdleTimeoutMs(config, candidate.target.provider);
@@ -863,28 +1148,39 @@ export const createGateway = (config) => {
                         };
                         return (async function* () {
                             let completed = false;
+                            let usage = firstEvent.value.type === "finish" ? firstEvent.value.usage : undefined;
                             try {
                                 yield firstEvent.value;
                                 for (;;) {
                                     const next = await nextEvent();
                                     if (next.done) {
                                         completed = true;
+                                        metrics.end("success", usage?.outputTokens);
+                                        permit?.end("success");
                                         await context.recordAttempt(createAttempt(candidate.target, true, Date.now() - attemptStartedAt, candidate.targetRank, {
-                                            retry, reasonCode: "provider-success"
+                                            retry, reasonCode: "provider-success", ...(config.costAccounting ? { usage } : {})
                                         }));
                                         return;
                                     }
                                     if (next.value.type === "error")
                                         throw next.value.error;
+                                    if (next.value.type === "text-delta")
+                                        metrics.firstText();
+                                    if (next.value.type === "finish" && next.value.usage)
+                                        usage = { ...usage, ...next.value.usage };
                                     yield next.value;
                                 }
                             }
                             catch (error) {
                                 const aborted = input.abortSignal?.aborted === true;
-                                const diagnostic = dispositionFor(error).error;
+                                metrics.end(aborted ? "cancelled" : "error");
+                                const disposition = dispositionFor(error);
+                                permit?.end(aborted ? "neutral" : disposition.retrySameTarget ? "retryable-error" : "neutral", disposition.retryAfterMs);
+                                const diagnostic = disposition.error;
                                 const failure = aborted ? abortReason(input.abortSignal) : context.toolHistory ? diagnostic : error;
                                 await context.recordAttempt(createAttempt(candidate.target, false, Date.now() - attemptStartedAt, candidate.targetRank, {
                                     retry,
+                                    ...(config.costAccounting ? { usage } : {}),
                                     reasonCode: aborted ? "request-aborted" : "provider-error",
                                     errorMessage: aborted ? abortReason(input.abortSignal).message : diagnostic.message
                                 }));
@@ -892,6 +1188,8 @@ export const createGateway = (config) => {
                             }
                             finally {
                                 if (!completed) {
+                                    metrics.end("cancelled");
+                                    permit?.end("neutral");
                                     control.abort(new DOMException("Gateway stream consumer closed.", "AbortError"));
                                 }
                                 control.dispose();
@@ -908,6 +1206,7 @@ export const createGateway = (config) => {
                     }
                     catch (rawError) {
                         const callerAborted = input.abortSignal?.aborted === true;
+                        metrics.end(callerAborted || rawError instanceof GatewayAdmissionError || rawError instanceof GatewayBudgetError ? "cancelled" : "error");
                         const error = control.timedOut() ? control.timeoutError : rawError;
                         control.abort(error);
                         control.dispose();
@@ -918,6 +1217,7 @@ export const createGateway = (config) => {
                             catch { /* Cleanup must not prevent fallback. */ }
                         }
                         if (callerAborted) {
+                            permit?.end("neutral");
                             await context.recordAttempt(createAttempt(candidate.target, false, Date.now() - attemptStartedAt, candidate.targetRank, {
                                 retry,
                                 reasonCode: "request-aborted",
@@ -926,11 +1226,14 @@ export const createGateway = (config) => {
                             throw abortReason(input.abortSignal);
                         }
                         const disposition = dispositionFor(error);
+                        permit?.end(disposition.retrySameTarget ? "retryable-error" : "neutral", disposition.retryAfterMs);
                         await context.recordAttempt(createAttempt(candidate.target, false, Date.now() - attemptStartedAt, candidate.targetRank, {
                             retry,
-                            reasonCode: "provider-error",
+                            reasonCode: error instanceof GatewayAdmissionError ? "admission-denied" : error instanceof GatewayBudgetError ? "budget-denied" : "provider-error",
                             errorMessage: disposition.error.message
                         }));
+                        if (config.circuitBreaker?.snapshot(candidate.target)?.state === "open")
+                            break;
                         if (retry < maxRetries && disposition.retrySameTarget) {
                             await abortableSleep(retryBackoffMs(config, retry, disposition.retryAfterMs), input.abortSignal);
                             continue;
@@ -968,7 +1271,7 @@ export const createGateway = (config) => {
             model: createRoutedLanguageModel(context)
         };
     };
-    return {
+    const gateway = {
         async generate(request) {
             const route = createStandardRoute(request);
             const result = await generateText(createTextOptions(route.model, request));
@@ -1036,7 +1339,7 @@ export const createGateway = (config) => {
             };
         },
         async runAgent(request) {
-            assertLegacyAgentMessages(request);
+            request = prepareAgentHistoryRequest(configuredAgentRequest(request));
             const route = createStandardRoute(request, {
                 defaultIntent: "tool-heavy",
                 getSkipReason: (model) => supportsRequiredAgentCapabilities(model, request.requiredAgentCapabilities)
@@ -1056,7 +1359,10 @@ export const createGateway = (config) => {
                     });
                 }
             });
+            if (request.state?.metadata?.gatewayPortableHistory === true)
+                route.context.toolHistory = true;
             const agent = createAgent({
+                ...request.agent,
                 id: request.agentId,
                 model: route.model,
                 instructions: request.instructions,
@@ -1070,7 +1376,7 @@ export const createGateway = (config) => {
                 providerOptions: request.providerOptions,
                 policy: request.policy,
                 metadata: request.metadata,
-                store: request.store,
+                store: agentHistoryStore(request.store, route.context, request.agent ? request.metadata?.gatewayAgentRouteBinding : undefined),
                 memory: request.memory,
                 onTelemetryEvent: request.onTelemetryEvent,
                 hookFailurePolicy: request.hookFailurePolicy
@@ -1079,7 +1385,7 @@ export const createGateway = (config) => {
             return enrichAgentResult(targetForResult(route.context), route.context.attempts, route.context.routeDecision, route.context.startedAt, result);
         },
         streamAgent(request) {
-            assertLegacyAgentMessages(request);
+            request = prepareAgentHistoryRequest(configuredAgentRequest(request));
             const route = createStandardRoute(request, {
                 defaultIntent: "tool-heavy",
                 extraRequiredCapabilities: { streaming: true },
@@ -1100,7 +1406,10 @@ export const createGateway = (config) => {
                     });
                 }
             });
+            if (request.state?.metadata?.gatewayPortableHistory === true)
+                route.context.toolHistory = true;
             const agent = createAgent({
+                ...request.agent,
                 id: request.agentId,
                 model: route.model,
                 instructions: request.instructions,
@@ -1114,7 +1423,7 @@ export const createGateway = (config) => {
                 providerOptions: request.providerOptions,
                 policy: request.policy,
                 metadata: request.metadata,
-                store: request.store,
+                store: agentHistoryStore(request.store, route.context, request.agent ? request.metadata?.gatewayAgentRouteBinding : undefined),
                 memory: request.memory,
                 onTelemetryEvent: request.onTelemetryEvent,
                 hookFailurePolicy: request.hookFailurePolicy
@@ -1130,5 +1439,80 @@ export const createGateway = (config) => {
             };
         }
     };
+    const operationSignal = (request) => {
+        const candidate = request;
+        return requestHasToolHistory(candidate) || candidate.state?.metadata?.gatewayPortableHistory === true
+            ? historyAbortSignal(request.abortSignal) : request.abortSignal;
+    };
+    const timeoutFor = (request) => {
+        for (const value of [request.timeoutMs, config.timeoutMs]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 1 || value > 2147483647))
+                throw new GatewayError("Invalid operation timeoutMs.", false);
+        }
+        return request.timeoutMs === undefined ? config.timeoutMs : config.timeoutMs === undefined ? request.timeoutMs : Math.min(request.timeoutMs, config.timeoutMs);
+    };
+    const managedCall = async (request, start) => {
+        const control = operationControl(operationSignal(request), timeoutFor(request));
+        try {
+            control.signal.throwIfAborted();
+            return await control.wait(start({ ...request, abortSignal: control.signal }));
+        }
+        finally {
+            control.dispose();
+        }
+    };
+    const managedStream = (request, start) => {
+        const timeoutMs = timeoutFor(request);
+        if (!config.metrics && !config.circuitBreaker && !config.admission && !config.budget && timeoutMs === undefined)
+            return start(request);
+        const control = operationControl(operationSignal(request), timeoutMs);
+        try {
+            control.signal.throwIfAborted();
+            const result = start({ ...request, abortSignal: control.signal });
+            const completion = control.wait(result.collect()).finally(control.dispose);
+            void completion.catch(() => undefined);
+            const wrapped = { ...result, collect: () => completion };
+            for (const key of ["eventStream", "textStream", "partialObjectStream"]) {
+                const source = result[key];
+                if (!source)
+                    continue;
+                wrapped[key] = {
+                    [Symbol.asyncIterator]() {
+                        const iterator = source[Symbol.asyncIterator]();
+                        return {
+                            next: () => control.wait(Promise.resolve(iterator.next())),
+                            return: async () => {
+                                control.cancel();
+                                control.dispose();
+                                try {
+                                    void Promise.resolve(iterator.return?.()).catch(() => undefined);
+                                }
+                                catch { /* Best effort. */ }
+                                return { done: true, value: undefined };
+                            }
+                        };
+                    }
+                };
+            }
+            return wrapped;
+        }
+        catch (error) {
+            control.cancel();
+            control.dispose();
+            throw error;
+        }
+    };
+    return {
+        ...gateway,
+        flushControls: executor.flush,
+        flushObservers: async () => { await Promise.all([...pendingObservers]); },
+        diagnostics: () => ({ pendingObservers: pendingObservers.size, droppedObservers, affinityEntries: affinities.size, ...executor.diagnostics() }),
+        generate: (request) => managedCall(request, gateway.generate),
+        generateObject: (request) => managedCall(request, gateway.generateObject),
+        runAgent: (request) => managedCall(request, gateway.runAgent),
+        streamText: (request) => managedStream(request, gateway.streamText),
+        streamObject: (request) => managedStream(request, gateway.streamObject),
+        streamAgent: (request) => managedStream(request, gateway.streamAgent)
+    };
 };
 //# sourceMappingURL=index.js.map