@adaptic/utils 0.0.1034 → 0.0.1035

package/dist/index.cjs

@@ -7506,6 +7506,68 @@ class DuplicateClientOrderIdError extends AlpacaApiError {
         this.wasDerived = wasDerived;
     }
 }
+/** Stable `code` carried by {@link PendingCancelError}. */
+const PENDING_CANCEL_ERROR_CODE = "ORDER_PENDING_CANCEL";
+/**
+ * Alpaca's numeric code for an unprocessable order request. It is shared by
+ * many distinct reasons (pending cancel, not cancelable, bad replace), so the
+ * reason text is what separates them.
+ */
+const ALPACA_UNPROCESSABLE_BROKER_CODE = 42210000;
+/** HTTP status Alpaca answers an unprocessable order request on. */
+const HTTP_UNPROCESSABLE_STATUS = 422;
+/** Alpaca's reason text for an order it already holds in `pending_cancel`. */
+const PENDING_CANCEL_REASON = /pending[ _]cancel/i;
+/**
+ * Alpaca refused a DELETE because it has already accepted a cancel for the
+ * order and holds it in `pending_cancel` until the venue confirms (HTTP 422,
+ * code 42210000, "order pending cancel").
+ *
+ * This is a distinct broker answer from "not cancelable" (the order already
+ * filled or is otherwise terminal): the order is being torn down, so it is
+ * NOT live protection, and a second DELETE only returns the same 422. A caller
+ * must treat the order as dying and wait for terminal truth (a `canceled` or
+ * `filled` trade update, or a GET), never re-cancel it and never count it as
+ * kept.
+ *
+ * The `message` is kept byte-identical to the generic rewrite
+ * ("Order X is not cancelable") so consumers that still match that text keep
+ * their behaviour; new consumers branch on the type, on
+ * {@link PENDING_CANCEL_ERROR_CODE}, or on {@link isPendingCancelRejection}.
+ * Never retryable.
+ */
+class PendingCancelError extends AlpacaApiError {
+    orderId;
+    constructor(message, 
+    /** The broker order id the DELETE targeted. */
+    orderId, cause) {
+        super(message, PENDING_CANCEL_ERROR_CODE, HTTP_UNPROCESSABLE_STATUS, cause, extractAlpacaBrokerError(cause));
+        this.orderId = orderId;
+    }
+}
+/**
+ * Did Alpaca answer that the order is already pending cancel?
+ *
+ * True for a {@link PendingCancelError}, and for any thrown value whose broker
+ * payload (on the value or its `cause` chain) is a 422 / 42210000 whose reason
+ * names `pending cancel` / `pending_cancel`. A payload with no reason text is
+ * never read as pending cancel: absence stays unknown.
+ *
+ * @param error - The thrown value.
+ * @returns Whether the broker holds the order in `pending_cancel`.
+ */
+function isPendingCancelRejection(error) {
+    if (error instanceof PendingCancelError) {
+        return true;
+    }
+    const detail = extractAlpacaBrokerError(error);
+    if (detail === undefined || detail.brokerMessage === null) {
+        return false;
+    }
+    const unprocessable = detail.statusCode === HTTP_UNPROCESSABLE_STATUS ||
+        detail.brokerCode === ALPACA_UNPROCESSABLE_BROKER_CODE;
+    return unprocessable && PENDING_CANCEL_REASON.test(detail.brokerMessage);
+}
 /** Max depth walked along the `error.cause` chain when locating a broker payload. */
 const MAX_BROKER_ERROR_CAUSE_DEPTH = 6;
 /**
@@ -11026,6 +11088,9 @@ class AlpacaTradingAPI {
     /**
      * Cancel a specific order by its ID
      * @param orderId The id of the order to cancel
+     * @throws PendingCancelError if the broker already holds the order in
+     *   `pending_cancel` (422 / 42210000 "order pending cancel"): the order is
+     *   being torn down, so it is not live and must not be cancelled again
      * @throws Error if the order is not cancelable (status 422) or if the order doesn't exist
      * @returns Promise that resolves when the order is successfully canceled
      */
@@ -11036,6 +11101,12 @@ class AlpacaTradingAPI {
             this.log(`Successfully canceled order ${orderId}`);
         }
         catch (error) {
+            // A cancel the broker already accepted: the order is dying, not kept.
+            // Typed so callers stop reading it as "not cancelable, still live".
+            if (isPendingCancelRejection(error)) {
+                this.log(`Order ${orderId} is already pending cancel at the broker; not re-cancelling`, { type: "warn" });
+                throw new PendingCancelError(`Order ${orderId} is not cancelable`, orderId, error);
+            }
             // If the error is a 422, it means the order is not cancelable
             if (error instanceof Error && error.message.includes("422")) {
                 this.log(`Order ${orderId} is not cancelable`, {
@@ -12315,6 +12386,9 @@ async function replaceOrder$1(auth, orderId, params) {
  * @param auth - The authentication details for Alpaca
  * @param orderId - The ID of the order to cancel
  * @returns Success status and optional message if order not found
+ * @throws PendingCancelError if the broker already holds the order in
+ *   `pending_cancel` (the order is dying; never cancel it again). The message
+ *   is the same "Failed to cancel order: ..." text as any other refusal.
  */
 async function cancelOrder$1(auth, orderId) {
     try {
@@ -12334,7 +12408,13 @@ async function cancelOrder$1(auth, orderId) {
                 return { success: false, message: `Order not found: ${orderId}` };
             }
             else {
-                throw alpacaHttpError(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
+                const httpError = alpacaHttpError(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
+                // A cancel the broker already accepted: the order is dying, not kept,
+                // and a second DELETE only returns the same 422.
+                if (isPendingCancelRejection(httpError)) {
+                    throw new PendingCancelError(httpError.message, orderId, httpError);
+                }
+                throw httpError;
             }
         }
         return { success: true };
@@ -68338,6 +68418,8 @@ async function getOrders(client, params = {}) {
  *
  * @param client - The AlpacaClient instance
  * @param orderId - The unique identifier of the order to cancel
+ * @throws PendingCancelError if the broker already holds the order in
+ *   `pending_cancel` (the order is dying; never cancel it again)
  * @throws Error if order cannot be canceled (e.g., already filled or canceled)
  *
  * @example
@@ -68353,6 +68435,11 @@ async function cancelOrder(client, orderId) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        // A cancel the broker already accepted: the order is dying, not kept.
+        if (isPendingCancelRejection(error)) {
+            log$6(`Order ${orderId} is already pending cancel at the broker; not re-cancelling`, { type: "warn" });
+            throw new PendingCancelError(`Order ${orderId} is not cancelable`, orderId, error);
+        }
         // Check for specific error conditions
         if (errorMessage.includes("422") ||
             errorMessage.includes("not cancelable")) {
@@ -72495,6 +72582,10 @@ const MAX_TOKENS_PARAM_BY_API_STYLE = {
 };
 /** The response-format key an OpenAI-compatible provider expects. */
 const RESPONSE_FORMAT_KEY = "response_format";
+/** The tool-choice key, in the OpenAI-compatible vocabulary the gateway speaks. */
+const TOOL_CHOICE_KEY = "tool_choice";
+/** The mandatory tool-choice value: the answer must be a tool call. */
+const TOOL_CHOICE_REQUIRED = "required";
 /**
  * Normalise a caller's options into the exact parameter set one leg accepts.
  *
@@ -72542,12 +72633,91 @@ function normaliseParams(options, route, responseFormat) {
         // tool calls concurrently reorders its own effects, and ordering is part
         // of the meaning of a sequence of trading actions.
         params.parallel_tool_calls = false;
+        const toolChoice = normaliseToolChoice(options.toolChoice, route);
+        if (toolChoice !== undefined) {
+            params[TOOL_CHOICE_KEY] = toolChoice;
+        }
     }
     if (options.metadata !== undefined) {
         params.metadata = { ...options.metadata };
     }
     return params;
 }
+/**
+ * Translate the caller's tool-choice policy into the value one leg is sent.
+ *
+ * `"auto"` is every provider's default once tools are present, so it is never
+ * sent. `"required"` is sent only to a route MEASURED to honour it: serving
+ * stacks accept the parameter and silently answer in prose anyway, so sending
+ * it to an unmeasured route would assert a constraint nobody checked. Omitting
+ * it there leaves that leg exactly as it was, with the caller's own validation
+ * as the guard.
+ *
+ * @param toolChoice The caller's policy, if any.
+ * @param route The leg being prepared.
+ * @returns The value to send, or undefined to omit the parameter.
+ */
+function normaliseToolChoice(toolChoice, route) {
+    if (toolChoice !== TOOL_CHOICE_REQUIRED) {
+        return undefined;
+    }
+    return route.params.supports_tool_choice === true ? TOOL_CHOICE_REQUIRED : undefined;
+}
+/**
+ * Fail a leg that was sent a mandatory tool choice and answered without a tool call.
+ *
+ * The parameter is sent only to a route declared to honour it, so an answer
+ * with no tool call means the declaration no longer holds for this leg — a
+ * serving-stack upgrade can drop the constraint without an error. Returning
+ * that answer would hand a caller prose where it demanded an action; failing
+ * the leg lets the chain advance and names the broken declaration.
+ *
+ * @param route The leg that answered.
+ * @param params The parameters it was sent.
+ * @param response The leg's answer: its tool calls, and the usage and serving
+ *   model the error carries so the leg's spend and attribution are not lost.
+ * @throws {ToolChoiceIgnoredError} When a mandatory choice produced no tool call.
+ */
+function assertToolChoiceHonoured(route, params, response) {
+    if (params[TOOL_CHOICE_KEY] !== TOOL_CHOICE_REQUIRED) {
+        return;
+    }
+    if (response.tool_calls !== undefined && response.tool_calls.length > 0) {
+        return;
+    }
+    throw new ToolChoiceIgnoredError(route, response.usage, response.servedModel ?? null);
+}
+/**
+ * Thrown when a route declared to honour a mandatory tool choice answered
+ * without a tool call.
+ *
+ * Distinct from a provider outage: the route answered, but not in the form it
+ * is declared to guarantee. The chain advances, and the route's health is not
+ * charged, because the fault is in the declaration, not in availability. The
+ * provider still billed for the answer, so the error carries the leg's usage:
+ * the spend belongs in the chain's total whether or not a later leg serves.
+ */
+class ToolChoiceIgnoredError extends Error {
+    /** The leg that ignored the choice. */
+    routeKey;
+    /** What the provider billed for the answer that carried no tool call. */
+    usage;
+    /** The model the provider reports as having answered, or `null` when unreported. */
+    servedModel;
+    /**
+     * @param route The leg.
+     * @param usage What the provider billed for the answer.
+     * @param servedModel The provider-reported serving model, or `null`.
+     */
+    constructor(route, usage, servedModel) {
+        super(`route ${route.routeKey} (${route.providerName}/${route.modelId}) was sent tool_choice "required" ` +
+            "and answered without a tool call; its supports_tool_choice declaration no longer holds");
+        this.name = "ToolChoiceIgnoredError";
+        this.routeKey = route.routeKey;
+        this.usage = usage;
+        this.servedModel = servedModel;
+    }
+}
 /**
  * Translate the requested response shape into the parameter a route accepts.
  *
@@ -73249,6 +73419,9 @@ class ChainExhaustedError extends Error {
  * understate spend by exactly the amount the failures cost — which is the
  * amount a fallback chain is most likely to run up.
  *
+ * A count one attempt did not report makes the total for that count unknown
+ * (`null`): a sum that skipped it would present a partial figure as complete.
+ *
  * @param a The running total.
  * @param b The attempt to add, if any.
  * @returns The combined usage.
@@ -73258,8 +73431,8 @@ function sumUsage(a, b) {
         return a;
     }
     return {
-        prompt_tokens: a.prompt_tokens + b.prompt_tokens,
-        completion_tokens: a.completion_tokens + b.completion_tokens,
+        prompt_tokens: addKnown(a.prompt_tokens, b.prompt_tokens),
+        completion_tokens: addKnown(a.completion_tokens, b.completion_tokens),
         reasoning_tokens: a.reasoning_tokens === undefined && b.reasoning_tokens === undefined
             ? undefined
             : (a.reasoning_tokens ?? 0) + (b.reasoning_tokens ?? 0),
@@ -73268,9 +73441,38 @@ function sumUsage(a, b) {
             : (a.cached_tokens ?? 0) + (b.cached_tokens ?? 0),
         provider: b.provider,
         model: b.model,
-        cost: a.cost + b.cost,
+        cost: addKnown(a.cost, b.cost),
     };
 }
+/**
+ * Add two measured quantities, either of which may be unreported.
+ *
+ * @param a The running total, or null when already unknown.
+ * @param b The value to add, or null when unreported.
+ * @returns The sum, or null when either side is unknown.
+ */
+function addKnown(a, b) {
+    return a === null || b === null ? null : a + b;
+}
+/**
+ * The budget one leg may spend.
+ *
+ * The route's own budget, cut to what remains of the caller's deadline. The
+ * route budget is never widened, so a caller with a long deadline still has a
+ * slow leg abandoned in time for the next one to run; and the deadline is never
+ * exceeded, so the last leg reached ends when the caller stops waiting.
+ *
+ * @param routeBudgetMs The leg's route budget.
+ * @param deadlineAtMs The caller's deadline instant, if any.
+ * @param nowMs The current instant on the same clock.
+ * @returns The leg's budget in milliseconds; zero or less means none is left.
+ */
+function legBudgetMs(routeBudgetMs, deadlineAtMs, nowMs) {
+    if (deadlineAtMs === undefined) {
+        return routeBudgetMs;
+    }
+    return Math.min(routeBudgetMs, deadlineAtMs - nowMs);
+}
 /** Raised internally when a leg exceeds its budget. */
 class LegTimeoutError extends Error {
     /**
@@ -73292,11 +73494,11 @@ class LegTimeoutError extends Error {
  * @param leg The leg to run.
  * @param params Normalised parameters for this leg.
  * @param execution The call context.
+ * @param budgetMs The leg's budget: its route budget cut to the caller's deadline.
  * @returns The provider's answer.
  */
-async function runLeg(leg, params, execution) {
+async function runLeg(leg, params, execution, budgetMs) {
     const controller = new AbortController();
-    const budgetMs = leg.route.timeoutMs;
     const timer = setTimeout(() => {
         controller.abort(new LegTimeoutError(leg.route.routeKey, budgetMs));
     }, budgetMs);
@@ -73318,7 +73520,7 @@ async function runLeg(leg, params, execution) {
         // provider, and only one clock should govern both. The leg's own signal is
         // handed to the guard as well, so a leg whose budget or caller is gone
         // leaves the queue at once instead of holding its place in it.
-        return await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
+        const response = await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
             route: leg.route,
             content: execution.content,
             responseFormat: execution.responseFormat,
@@ -73328,6 +73530,8 @@ async function runLeg(leg, params, execution) {
             signal: controller.signal,
             correlationId: execution.correlationId,
         }), budgetMs, { modelId: leg.route.modelId, signal: controller.signal });
+        assertToolChoiceHonoured(leg.route, params, response);
+        return response;
     }
     finally {
         clearTimeout(timer);
@@ -73360,6 +73564,11 @@ function classify(error, callerSignal) {
     if (error instanceof UnsupportedCapabilityError) {
         return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
     }
+    if (error instanceof ToolChoiceIgnoredError) {
+        // The route answered; it broke a declared guarantee rather than failing to
+        // be available, so its breaker is not charged for it.
+        return { outcome: "error", reason: error.message, countsAgainstHealth: false };
+    }
     if (error instanceof RateGuardTimeoutError) {
         // Self-inflicted pacing, not provider ill-health. Counting it would let the
         // client's own throttling open a breaker on a perfectly healthy provider
@@ -73391,6 +73600,22 @@ function classify(error, callerSignal) {
 function isAborted(signal) {
     return signal !== undefined && signal.aborted;
 }
+/**
+ * The usage a failed leg was billed for, when the leg reached an answer.
+ *
+ * A leg that failed after the provider answered — content that does not parse,
+ * or prose where a tool call was mandatory — was still charged. A leg that
+ * never answered (timeout, outage, skip) carries no usage, and none is invented.
+ *
+ * @param error The thrown value.
+ * @returns The billed usage, or undefined when the leg never produced an answer.
+ */
+function billedUsageOf(error) {
+    if (error instanceof LlmResponseFormatError || error instanceof ToolChoiceIgnoredError) {
+        return error.usage;
+    }
+    return undefined;
+}
 /**
  * Walk a chain until a leg answers.
  *
@@ -73438,10 +73663,27 @@ async function executeChain(alias, execution) {
             execution.onAttempt?.(record);
             continue;
         }
+        const budgetMs = legBudgetMs(route.timeoutMs, execution.deadlineAtMs, now());
+        if (budgetMs <= 0) {
+            // The caller's deadline is spent. Dispatching now would start a call
+            // that is cancelled the moment it begins, and charge nothing but noise.
+            const record = {
+                routeKey: route.routeKey,
+                role: route.role,
+                provider: route.providerName,
+                modelId: route.modelId,
+                outcome: "skipped",
+                durationMs: 0,
+                reason: "caller deadline exhausted before this leg",
+            };
+            attempts.push(record);
+            execution.onAttempt?.(record);
+            continue;
+        }
         const startedAt = now();
         const holdsProbe = execution.breakers.onAttemptStart(route.routeKey);
         try {
-            const response = await runLeg(leg, leg.params, execution);
+            const response = await runLeg(leg, leg.params, execution, budgetMs);
             execution.breakers.onSuccess(route.routeKey);
             totalUsage = sumUsage(totalUsage, response.usage);
             const record = {
@@ -73451,6 +73693,8 @@ async function executeChain(alias, execution) {
                 modelId: route.modelId,
                 outcome: "ok",
                 durationMs: now() - startedAt,
+                budgetMs,
+                servedModel: response.servedModel ?? null,
                 usage: response.usage,
             };
             attempts.push(record);
@@ -73467,9 +73711,11 @@ async function executeChain(alias, execution) {
                 // took must come back, or a half-open route admits no probe ever again.
                 execution.breakers.onAttemptAbandoned(route.routeKey);
             }
-            // A provider that answered with unparseable content still billed for the
-            // answer; the spend belongs in the total whether or not a later leg serves.
-            const billed = error instanceof LlmResponseFormatError ? error.usage : undefined;
+            // A provider that answered — with unparseable content, or in prose where a
+            // tool call was mandatory — still billed for the answer; the spend belongs
+            // in the total whether or not a later leg serves.
+            const billed = billedUsageOf(error);
+            const answeredBy = error instanceof ToolChoiceIgnoredError ? error.servedModel : undefined;
             totalUsage = sumUsage(totalUsage, billed);
             const record = {
                 routeKey: route.routeKey,
@@ -73478,7 +73724,9 @@ async function executeChain(alias, execution) {
                 modelId: route.modelId,
                 outcome,
                 durationMs: now() - startedAt,
+                budgetMs,
                 reason,
+                ...(answeredBy === undefined ? {} : { servedModel: answeredBy }),
                 ...(billed === undefined ? {} : { usage: billed }),
             };
             attempts.push(record);
@@ -73670,6 +73918,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: false,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -73696,6 +73945,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: true,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -73722,6 +73972,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: true,
+					supports_tool_choice: true,
 					context_window: 1000000
 				},
 				price_per_mtok: {
@@ -73766,6 +74017,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: true,
+					supports_tool_choice: true,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -73792,6 +74044,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: false,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -73818,6 +74071,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: true,
+					supports_tool_choice: true,
 					context_window: 1000000
 				},
 				price_per_mtok: {
@@ -73862,6 +74116,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: false,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -73888,6 +74143,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: false,
 					supports_vision: false,
+					supports_tool_choice: true,
 					context_window: 131072
 				},
 				price_per_mtok: {
@@ -73914,6 +74170,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: true,
+					supports_tool_choice: true,
 					context_window: 200000
 				},
 				price_per_mtok: {
@@ -73957,6 +74214,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: false,
 					supports_vision: false,
+					supports_tool_choice: true,
 					context_window: 131072
 				},
 				price_per_mtok: {
@@ -73983,6 +74241,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: true,
 					context_window: 262144
 				},
 				price_per_mtok: {
@@ -74009,6 +74268,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: true,
+					supports_tool_choice: true,
 					context_window: 200000
 				},
 				price_per_mtok: {
@@ -74054,6 +74314,7 @@ var aliases = {
 					supports_tools: true,
 					supports_cache_control: true,
 					supports_vision: false,
+					supports_tool_choice: false,
 					context_window: 1048576
 				},
 				price_per_mtok: {
@@ -74065,6 +74326,105 @@ var aliases = {
 				notes: "Pinned with no fallback (PD-6). A judge that failed over would grade one model's output against another model's standard, corrupting every gate decided by it."
 			}
 		]
+	},
+	"llm.decide": {
+		workload: "Per-symbol trading decision: a multi-turn tool-calling read that ends in exactly one decision tool call",
+		latency_class: "hot-path",
+		criticality: "trading-adjacent",
+		isolation_capable: false,
+		eval_gate: "tool-call",
+		policy_note: "The dedicated decision alias. The per-symbol decision call is a trading decision, not a latency-critical extraction, so it gets its own chain instead of borrowing llm.fast's. It is evaluated in SHADOW beside the live llm.fast path (schema-valid rate, latency, served model, action agreement) and serves live traffic only through the engine's governed routing flag after that evidence. Leg budgets are the hot-path class's today; budgets set from each model's measured p95 are a separate, evidence-gated change. Its monthly budget bounds the shadow's own spend and is added to the gateway total, so the shadow cannot consume the live aliases' budget.",
+		budget: {
+			basis: "provisional-pre-baseline",
+			monthly_usd: 600,
+			alert_pct: [
+				50,
+				80,
+				100
+			]
+		},
+		routes: [
+			{
+				role: "primary",
+				provider: "deepinfra",
+				model_id: "deepseek-ai/DeepSeek-V4-Pro",
+				model_id_status: "confirmed",
+				model_id_source: "DeepInfra /v1/openai/models catalogue queried against the live account 2026-09-11; tool-calling and latency verified by direct call on the same account",
+				model_family: "DeepSeek V4 Pro",
+				lumic_model: "deepseek-ai/DeepSeek-V4-Pro",
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: false,
+					supports_tool_choice: false,
+					context_window: 1048576
+				},
+				price_per_mtok: {
+					input: 1.3,
+					output: 2.6,
+					as_of: "2026-09-11",
+					source: "DeepInfra /v1/openai/models catalogue queried against the live account 2026-09-11; tool-calling and latency verified by direct call on the same account"
+				},
+				notes: "The advanced tier the per-symbol decision prompt was written for: a long, multi-turn, tool-calling read of about 21k prompt tokens, where the hot-path alias's small models answer faster but lose the schema contract more often. It ignores a mandatory tool_choice (measured), so the decision contract's own validation stays the guard on this leg."
+			},
+			{
+				role: "secondary",
+				provider: "deepinfra",
+				model_id: "deepseek-ai/DeepSeek-V4-Flash",
+				model_id_status: "confirmed",
+				model_id_source: "DeepInfra /v1/openai/models catalogue queried against the live account 2026-09-11; tool-calling and latency verified by direct call on the same account",
+				model_family: "DeepSeek V4 Flash",
+				lumic_model: "deepseek-ai/DeepSeek-V4-Flash",
+				params: {
+					temperature: null,
+					max_output_tokens: null,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: false,
+					supports_tool_choice: false,
+					context_window: 1048576
+				},
+				price_per_mtok: {
+					input: 0.09,
+					output: 0.18,
+					as_of: "2026-09-11",
+					source: "DeepInfra /v1/openai/models catalogue queried against the live account 2026-09-11; tool-calling and latency verified by direct call on the same account"
+				},
+				notes: "The current decision model, kept as the secondary so a slow or failing primary falls back to the model the decision path already runs on."
+			},
+			{
+				role: "closed_incumbent",
+				provider: "anthropic",
+				model_id: "claude-haiku-4-5",
+				model_id_status: "confirmed",
+				model_id_source: "lumic-utils/src/types/openai-types.ts SUPPORTED_MODELS — already routed on in production",
+				model_family: "Haiku-class",
+				lumic_model: "claude-haiku-4-5",
+				params: {
+					temperature: null,
+					max_output_tokens: 64000,
+					supports_temperature: true,
+					supports_json_schema: true,
+					supports_tools: true,
+					supports_cache_control: true,
+					supports_vision: true,
+					supports_tool_choice: true,
+					context_window: 200000
+				},
+				price_per_mtok: {
+					input: 1,
+					output: 5,
+					as_of: "2026-09-10",
+					source: "docs/llm-provider-migration.md#3 Haiku-class anchor"
+				}
+			}
+		]
 	}
 };
 var open_items = [
@@ -74554,6 +74914,10 @@ function createDirectTransport(config) {
                 tool_calls: Array.isArray(result.tool_calls)
                     ? result.tool_calls
                     : undefined,
+                // The incumbent client reports the model it resolved; unreported stays null.
+                servedModel: typeof result.usage?.model === "string" && result.usage.model !== ""
+                    ? result.usage.model
+                    : null,
             };
         },
     };
@@ -74561,9 +74925,9 @@ function createDirectTransport(config) {
 /**
  * Normalise the incumbent client's usage shape.
  *
- * Missing counts stay zero rather than being estimated, for the same reason
- * they do on the gateway path: an invented token count flows straight into the
- * budget accounting the spend controls depend on.
+ * A missing count is `null` rather than zero or an estimate, for the same
+ * reason as on the gateway path: an invented token count — zero included —
+ * flows straight into the budget accounting the spend controls depend on.
  *
  * @param usage The incumbent client's usage, if any.
  * @param request The request it answers.
@@ -74571,13 +74935,13 @@ function createDirectTransport(config) {
  */
 function readUsage$1(usage, request) {
     return {
-        prompt_tokens: usage?.prompt_tokens ?? 0,
-        completion_tokens: usage?.completion_tokens ?? 0,
+        prompt_tokens: usage?.prompt_tokens ?? null,
+        completion_tokens: usage?.completion_tokens ?? null,
         reasoning_tokens: usage?.reasoning_tokens,
         cached_tokens: usage?.cached_tokens,
         provider: usage?.provider ?? request.route.providerName,
         model: usage?.model ?? request.route.modelId,
-        cost: usage?.cost ?? 0,
+        cost: usage?.cost ?? null,
     };
 }
 /**
@@ -74630,10 +74994,12 @@ async function resolveDefaultDirectCaller() {
  * never in application code (PD-5), which is what makes a model swap a config
  * change rather than a deploy.
  *
- * The client still walks its own chain on top of the gateway's, and the
- * duplication is deliberate. The gateway's fallbacks cover a provider being
- * down; the client's cover the gateway being down. Only one of those two can
- * cover the other, so the outer chain is the one that must exist.
+ * The client's chain is the single fallback owner: every leg is addressed to the
+ * gateway by its own model name, so the gateway serves one deployment per leg
+ * and needs no fallback of its own. A proxy-side fallback inside a leg would
+ * spend the leg's budget on a model the chain did not choose and report the
+ * answer as the leg's; the served model is read from the response body so such
+ * a substitution stays visible while any remains configured.
  *
  * The gateway key is read from the environment by NAME at call time and never
  * stored, logged, or included in an error (PD-2). Reading it per call rather
@@ -74645,6 +75011,10 @@ async function resolveDefaultDirectCaller() {
 const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 /** Maximum characters of an error body echoed into a message. */
 const ERROR_BODY_EXCERPT = 400;
+/** Response header in which the LiteLLM proxy reports the call's cost in USD. */
+const RESPONSE_COST_HEADER = "x-litellm-response-cost";
+/** Response header naming the proxy deployment that served the call. */
+const DEPLOYMENT_ID_HEADER = "x-litellm-model-id";
 /**
  * Thrown when the gateway itself is unreachable, as opposed to a provider
  * behind it failing.
@@ -74701,31 +75071,67 @@ function readGatewayKey(envVar) {
 /**
  * Extract usage from a chat-completion response.
  *
- * Absent counts stay zero rather than being estimated. A fabricated token count
- * would flow straight into the budget accounting that the spend controls are
- * built on, and a budget computed from invented numbers is worse than one that
- * knows it is missing a call.
+ * A count the provider did not report is `null`, never zero and never an
+ * estimate. A fabricated count — zero included — would flow straight into the
+ * budget accounting the spend controls are built on, where a zero reads as a
+ * free call and can never trip a limit.
+ *
+ * Cost is read from the body's `usage.response_cost` or, failing that, from the
+ * proxy's cost header, which is where the LiteLLM proxy reports it.
  *
  * @param payload The parsed response body.
  * @param request The request it answers.
+ * @param headers The response headers.
  * @returns The usage record.
  */
-function readUsage(payload, request) {
+function readUsage(payload, request, headers) {
     const usage = (payload.usage ?? {});
     const details = (usage.prompt_tokens_details ?? {});
     const cached = details.cached_tokens;
     const reasoningDetails = (usage.completion_tokens_details ?? {});
     const reasoning = reasoningDetails.reasoning_tokens;
     return {
-        prompt_tokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0,
-        completion_tokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0,
+        prompt_tokens: finiteOrNull(usage.prompt_tokens),
+        completion_tokens: finiteOrNull(usage.completion_tokens),
         reasoning_tokens: typeof reasoning === "number" ? reasoning : undefined,
         cached_tokens: typeof cached === "number" ? cached : undefined,
         provider: request.route.providerName,
         model: request.route.modelId,
-        cost: typeof usage.response_cost === "number" ? usage.response_cost : 0,
+        cost: finiteOrNull(usage.response_cost) ?? headerNumber(headers, RESPONSE_COST_HEADER),
     };
 }
+/**
+ * A reported number, or null when it was not reported as a finite number.
+ *
+ * @param value The raw value.
+ * @returns The number, or null.
+ */
+function finiteOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * A numeric response header, or null when absent or not a finite number.
+ *
+ * @param headers The response headers, if the transport exposes them.
+ * @param name The header name.
+ * @returns The number, or null.
+ */
+function headerNumber(headers, name) {
+    const raw = headers?.get(name);
+    if (raw === undefined || raw === null || raw.trim() === "") {
+        return null;
+    }
+    return finiteOrNull(Number(raw));
+}
+/**
+ * A non-empty string, or null.
+ *
+ * @param value The raw value.
+ * @returns The string, or null.
+ */
+function nonEmptyOrNull(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
 /**
  * Build the gateway transport.
  *
@@ -74776,13 +75182,17 @@ function createGatewayTransport(config) {
             // Usage is read before the content is interpreted. The provider billed for
             // this answer whether or not it parses, and a parse failure that dropped
             // the count would report the attempt as free.
-            const usage = readUsage(payload, request);
+            const usage = readUsage(payload, request, response.headers);
             return {
                 response: interpretContent(message?.content, request.responseFormat, usage),
                 usage,
                 tool_calls: Array.isArray(message?.tool_calls)
                     ? message.tool_calls
                     : undefined,
+                // The model the provider says answered, which a proxy-side fallback can
+                // make differ from the leg's route model; unreported stays null.
+                servedModel: nonEmptyOrNull(payload.model),
+                servedDeploymentId: nonEmptyOrNull(response.headers?.get(DEPLOYMENT_ID_HEADER)),
             };
         },
     };
@@ -74851,7 +75261,10 @@ function interpretContent(content, responseFormat, usage) {
  * table, per-provider parameter normalisation, a hard per-leg timeout, a
  * per-route circuit breaker, an ordered fallback chain ending at the closed
  * incumbent, and — where the caller supplies a validator — one schema-feedback
- * retry ahead of the chain. None of them is optional, because a control that a
+ * retry ahead of the chain. The caller's `timeoutMs` is ONE deadline for the
+ * whole call: each leg runs for its route budget or for what remains of that
+ * deadline, whichever is shorter, so the chain is the single fallback owner and
+ * a slow primary cannot spend the time its fallbacks need. None of them is optional, because a control that a
  * caller can switch off is a control that will be off on the call that needed
  * it.
  *
@@ -74987,10 +75400,14 @@ function prepareLegs(chain, options, responseFormat, transport) {
  * @throws {SchemaRetryExhaustedError} When a validated payload failed twice.
  */
 async function callLLMByAlias(content, responseFormat = "text", options) {
-    const chain = resolveChain(options.alias, {
-        isolated: options.isolated,
-        timeoutMsOverride: options.timeoutMs,
-    });
+    // Legs keep their route budgets; the caller's timeout is the deadline they
+    // share, fixed once here so a validation retry and the degraded direct path
+    // spend what is left of it rather than starting a fresh one.
+    const chain = resolveChain(options.alias, { isolated: options.isolated });
+    const clock = config.now ?? Date.now;
+    const deadlineAtMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
+        ? clock() + options.timeoutMs
+        : undefined;
     if (chain.routes.length === 0) {
         // Nothing is servable. The exclusions say why each leg was unavailable,
         // which is the difference between an operator reading config and an
@@ -75033,6 +75450,7 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
                     breakers,
                     correlationId: options.correlationId,
                     callerSignal: options.signal,
+                    deadlineAtMs,
                     now: config.now,
                     onAttempt: (record) => attemptLog.push(record),
                 });
@@ -75067,6 +75485,7 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
             breakers,
             correlationId: options.correlationId,
             callerSignal: options.signal,
+            deadlineAtMs,
             now: config.now,
             onAttempt: (record) => attemptLog.push(record),
         });
@@ -75079,6 +75498,7 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
             usage: outcome.response.usage,
             tool_calls: outcome.response.tool_calls,
             servedBy: outcome.servedBy,
+            servedModel: outcome.response.servedModel ?? null,
             attempts: attemptLog,
             degraded: outcome.degraded,
             totalUsage: outcome.totalUsage,
@@ -75112,6 +75532,7 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
         usage: validated.response.usage,
         tool_calls: validated.response.tool_calls,
         servedBy: routing.servedBy,
+        servedModel: validated.response.servedModel ?? null,
         attempts: attemptLog,
         degraded: routing.degraded,
         totalUsage: validated.totalUsage,
@@ -80598,6 +81019,8 @@ exports.NewsError = NewsError;
 exports.NoServableRouteError = NoServableRouteError;
 exports.OptionStrategyError = OptionStrategyError;
 exports.OptionsDataError = OptionsDataError;
+exports.PENDING_CANCEL_ERROR_CODE = PENDING_CANCEL_ERROR_CODE;
+exports.PendingCancelError = PendingCancelError;
 exports.QuoteError = QuoteError;
 exports.RISK_FREE_RATE_TTL_MS = RISK_FREE_RATE_TTL_MS;
 exports.RateGuardTimeoutError = RateGuardTimeoutError;
@@ -80610,6 +81033,7 @@ exports.StreamTruncatedError = StreamTruncatedError;
 exports.TRADING_API = TRADING_API;
 exports.TimeoutError = TimeoutError;
 exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+exports.ToolChoiceIgnoredError = ToolChoiceIgnoredError;
 exports.TradeError = TradeError;
 exports.TrailingStopValidationError = TrailingStopValidationError;
 exports.USDC_PAIRS = USDC_PAIRS;
@@ -80628,6 +81052,7 @@ exports.adptc = adptc;
 exports.alpaca = alpaca;
 exports.analyzeBars = analyzeBars;
 exports.approximateImpliedVolatility = approximateImpliedVolatility;
+exports.assertToolChoiceHonoured = assertToolChoiceHonoured;
 exports.atr = atrNs;
 exports.availableStatistic = availableStatistic;
 exports.bracketOrders = bracketOrders;
@@ -80814,8 +81239,10 @@ exports.isOrderFillable = isOrderFillable;
 exports.isOrderFilled = isOrderFilled;
 exports.isOrderOpen = isOrderOpen;
 exports.isOrderTerminalStatus = isOrderTerminal$1;
+exports.isPendingCancelRejection = isPendingCancelRejection;
 exports.isSupportedCryptoPair = isSupportedCryptoPair;
 exports.isTransientNetworkError = isTransientNetworkError;
+exports.legBudgetMs = legBudgetMs;
 exports.legacyApi = index$1;
 exports.limitBuyWithTakeProfit = limitBuyWithTakeProfit;
 exports.limitsFor = limitsFor;