@pentoshi/clai 4.2.2 → 4.4.0

package/dist/llm/http.js

@@ -1,4 +1,5 @@
 import { modelAcceptsImages, modelSupportsThinking, isReasoningUnsupported, modelReasoningEfforts, learnModelEmitsReasoning, registerModelCatalog, } from "./capabilities.js";
+import { catalogEffortList, catalogEntriesFromPayload, parseCatalogFacts, } from "./catalog-facts.js";
 import { resolveSampling } from "./sampling.js";
 import { accumulateOpenAiToolCallDelta, finalizeOpenAiToolCalls, fromWireName, parseOpenAiMessageToolCalls, } from "./tool-protocol.js";
 import { openAiToolBodyFields, toOpenAiToolMessages, } from "./adapters/openai-tools.js";
@@ -7,6 +8,9 @@ import { generationFetch } from "./operation-usage.js";
 import { isOperationPolicyError } from "./operation-ledger.js";
 import { emitStreamReasoningArtifacts, emitStreamReasoningDelta, } from "./stream-events.js";
 import { CHAT_COMPLETIONS_STREAM_TERMINAL, requireTerminalProof, } from "./stream-terminal.js";
+import { modelMaxOutputTokens } from "./context-windows.js";
+import { inBandBadRequestStatus, isMissingReasoningContentError, } from "./reasoning-errors.js";
+import { emitReasoningControls, } from "./reasoning-controls.js";
 import { createReasoningArtifact, createReasoningArtifactProvenance, } from "./reasoning-artifacts.js";
 import { classifyBynaraModel, classifyNvidiaModel, } from "./model-families.js";
 import { compileRequestPlan, } from "./request-plan.js";
@@ -23,6 +27,31 @@ export class ProviderError extends Error {
         this.name = "ProviderError";
     }
 }
+const USAGE_INPUT_KEYS = [
+    "prompt_tokens",
+    "promptTokens",
+    "input_tokens",
+    "inputTokens",
+];
+const USAGE_OUTPUT_KEYS = [
+    "completion_tokens",
+    "completionTokens",
+    "output_tokens",
+    "outputTokens",
+];
+function isFinalUsageFrame(parsed) {
+    if (Array.isArray(parsed.choices) && parsed.choices.length > 0)
+        return false;
+    const usage = parsed.usage;
+    if (!usage || typeof usage !== "object" || Array.isArray(usage))
+        return false;
+    const raw = usage;
+    const reported = (keys) => keys.some((key) => {
+        const value = raw[key];
+        return typeof value === "number" && Number.isFinite(value);
+    });
+    return reported(USAGE_INPUT_KEYS) && reported(USAGE_OUTPUT_KEYS);
+}
 function parseRetryAfterHeader(value) {
     if (!value)
         return undefined;
@@ -68,116 +97,26 @@ function statusCodeHint(status) {
     }
     return "";
 }
-function modalitiesDeclareImage(value) {
-    if (Array.isArray(value)) {
-        const items = value.filter((item) => typeof item === "string");
-        if (items.length === 0)
-            return undefined;
-        return items.some((item) => /image|vision/i.test(item));
-    }
-    if (typeof value === "string") {
-        if (!/text|image|audio|video/i.test(value))
-            return undefined;
-        return /image|vision/i.test(value);
-    }
-    if (value && typeof value === "object") {
-        const nested = value;
-        if (typeof nested.vision === "boolean")
-            return nested.vision;
-        if (typeof nested.image === "boolean")
-            return nested.image;
-        if (nested.input !== undefined)
-            return modalitiesDeclareImage(nested.input);
-    }
-    return undefined;
-}
 export function catalogEntryVision(entry) {
-    if (!entry || typeof entry !== "object")
-        return undefined;
-    const raw = entry;
-    for (const flag of [raw.vision, raw.supports_vision, raw.multimodal]) {
-        if (typeof flag === "boolean")
-            return flag;
-    }
-    for (const candidate of [
-        raw.architecture?.input_modalities,
-        raw.architecture?.modality,
-        raw.input_modalities,
-        raw.modalities,
-        raw.capabilities,
-        raw.features,
-    ]) {
-        const declared = modalitiesDeclareImage(candidate);
-        if (declared !== undefined)
-            return declared;
-    }
-    return undefined;
-}
-const REASONING_FEATURE_RE = /^(?:reasoning|reasoning_effort|include_reasoning|thinking|reasoning_content)$/i;
-function catalogEntryReasoning(entry) {
-    const raw = entry;
-    if (typeof raw?.reasoning === "boolean")
-        return raw.reasoning;
-    if (Array.isArray(raw?.reasoning_options) && raw.reasoning_options.length > 0) {
-        return true;
-    }
-    for (const container of [
-        raw?.supported_features,
-        raw?.supported_parameters,
-        raw?.features,
-        raw?.capabilities,
-    ]) {
-        if (!Array.isArray(container))
-            continue;
-        const names = container.filter((value) => typeof value === "string");
-        if (names.length === 0)
-            continue;
-        return names.some((name) => REASONING_FEATURE_RE.test(name.trim()));
-    }
-    return undefined;
-}
-function catalogEntryReasoningEfforts(entry) {
-    const raw = entry;
-    const collected = [];
-    const pushValues = (values) => {
-        if (!Array.isArray(values))
-            return;
-        for (const value of values) {
-            if (typeof value === "string" && value.trim())
-                collected.push(value.trim());
-        }
-    };
-    if (Array.isArray(raw?.reasoning_options)) {
-        for (const option of raw.reasoning_options) {
-            const shaped = option;
-            if (shaped?.type !== undefined && shaped.type !== "effort")
-                continue;
-            pushValues(shaped?.values);
-        }
-    }
-    pushValues(raw?.supported_reasoning_efforts);
-    if (raw?.reasoning_effort && typeof raw.reasoning_effort === "object") {
-        pushValues(raw.reasoning_effort.values);
-    }
-    return collected.length > 0 ? collected : undefined;
+    return parseCatalogFacts(entry)?.vision;
 }
 export function ingestModelCatalogEntries(provider, entries) {
     const models = [];
     const seen = new Set();
     for (const entry of entries) {
-        const raw = typeof entry === "string" ? entry : entry?.id;
-        if (typeof raw !== "string")
+        const facts = parseCatalogFacts(entry);
+        if (!facts)
             continue;
-        const id = raw.trim();
-        if (id.length === 0 || seen.has(id))
+        const id = facts.id;
+        if (seen.has(id))
             continue;
         seen.add(id);
-        const vision = typeof entry === "string" ? undefined : catalogEntryVision(entry);
-        const reasoning = typeof entry === "string" ? undefined : catalogEntryReasoning(entry);
-        const reasoningEfforts = typeof entry === "string" ? undefined : catalogEntryReasoningEfforts(entry);
+        const reasoning = facts.reasoning?.supported;
+        const reasoningEfforts = catalogEffortList(facts.reasoning?.supportedEfforts);
         models.push({
             id,
-            ...(vision === undefined ? {} : { vision }),
+            facts,
+            ...(facts.vision === undefined ? {} : { vision: facts.vision }),
             ...(reasoning === undefined ? {} : { reasoning }),
             ...(reasoningEfforts === undefined ? {} : { reasoningEfforts }),
         });
@@ -187,15 +126,7 @@ export function ingestModelCatalogEntries(provider, entries) {
     return models.map((model) => model.id).sort();
 }
 export function ingestOpenAiModelCatalog(provider, payload) {
-    const container = payload;
-    const entries = Array.isArray(payload)
-        ? payload
-        : Array.isArray(container?.data)
-            ? container.data
-            : Array.isArray(container?.models)
-                ? container.models
-                : [];
-    return ingestModelCatalogEntries(provider, entries);
+    return ingestModelCatalogEntries(provider, catalogEntriesFromPayload(payload));
 }
 export async function readJson(response, signal) {
     const text = await readBodyCapped(response, MAX_JSON_RESPONSE_BYTES, signal);
@@ -552,6 +483,15 @@ const DEFAULT_COMPATIBLE_REASONING_ARTIFACT_POLICY = {
     scope: "all-history",
     persistence: "tool-turn",
 };
+const PRESERVED_FINAL_TURN_ARTIFACT_POLICY = {
+    scope: "all-history",
+    persistence: "all-turns",
+};
+export function compatibleArtifactPolicyFor(preservation) {
+    return preservation === "required"
+        ? PRESERVED_FINAL_TURN_ARTIFACT_POLICY
+        : DEFAULT_COMPATIBLE_REASONING_ARTIFACT_POLICY;
+}
 function artifactRaw(value) {
     if (typeof value === "string")
         return value;
@@ -726,7 +666,16 @@ function pickAdvertisedEffort(effort, advertised) {
     return (order.find((candidate) => advertised.includes(candidate)) ??
         advertised[advertised.length - 1]);
 }
-export function buildReasoningPayload(reasoning, style, model, providerId) {
+export function buildReasoningPayload(reasoning, style, model, providerId, control) {
+    if (control) {
+        return {
+            ...emitReasoningControls({
+                profile: control.profile,
+                preference: reasoning,
+                willReplayReasoning: control.willReplayReasoning,
+            }),
+        };
+    }
     if (style === "none")
         return {};
     const enabled = Boolean(reasoning?.enabled);
@@ -866,18 +815,6 @@ export function buildReasoningPayload(reasoning, style, model, providerId) {
             // off, so compaction would still buy hidden reasoning tokens. vLLM's
             // StepFun template honours this explicit per-request switch.
             return { chat_template_kwargs: { enable_thinking: enabled } };
-        case "groq": {
-            const m = (model ?? "").toLowerCase();
-            if (/qwen\/qwen3-32b/.test(m)) {
-                return { reasoning_effort: enabled ? "default" : "none" };
-            }
-            if (/openai\/gpt-oss-(?:20b|120b)/.test(m)) {
-                return enabled
-                    ? { reasoning_effort: clampEffort(effort), include_reasoning: true }
-                    : { reasoning_effort: "low", include_reasoning: false };
-            }
-            return {};
-        }
         case "nvidia": {
             const kind = classifyNvidiaModel(model ?? "");
             switch (kind) {
@@ -964,6 +901,8 @@ export function buildReasoningPayload(reasoning, style, model, providerId) {
  * payload and retries so an unsupported option never fails the whole request.
  */
 export function isReasoningUnsupportedError(error) {
+    if (isMissingReasoningContentError(error))
+        return false;
     const status = error && typeof error === "object" && "status" in error
         ? Number(error.status)
         : undefined;
@@ -1043,30 +982,46 @@ export function isOpenAiReasoningModel(model) {
         /(?:^|\/)o[134](?:\.|-|$)/.test(m) ||
         /muse-spark/.test(m));
 }
+const DEFAULT_REASONING_OUTPUT_FLOOR = 16_384;
+function outputBudgetWithReasoning(requested, options) {
+    const floor = options.control?.profile.reasoning.minOutputTokens ??
+        DEFAULT_REASONING_OUTPUT_FLOOR;
+    const ceiling = modelMaxOutputTokens(options.providerId, options.model, options.outputTokenLimit);
+    const floored = Math.max(requested, floor);
+    return ceiling !== undefined ? Math.min(floored, ceiling) : floored;
+}
 function emitChatCompletionsBody(options) {
     // Skip reasoning knobs entirely for models observed to reject them this
     // session (see isReasoningUnsupportedError). This is how thinking degrades
     // gracefully: the request still runs, just without the unsupported option.
-    const capabilityDeniesThinking = options.providerId !== undefined &&
+    const capabilityDeniesThinking = options.control === undefined &&
+        options.providerId !== undefined &&
         Boolean(options.reasoning?.enabled) &&
         !modelSupportsThinking(options.providerId, options.model);
-    const reasoning = (options.providerId !== undefined &&
-        isReasoningUnsupported(options.providerId, options.model)) ||
-        capabilityDeniesThinking
+    const legacyControlDenied = options.control === undefined &&
+        options.providerId !== undefined &&
+        isReasoningUnsupported(options.providerId, options.model);
+    const reasoning = legacyControlDenied ||
+        capabilityDeniesThinking ||
+        options.control?.suppressed === true
         ? {}
-        : buildReasoningPayload(options.reasoning, options.reasoningStyle ?? "none", options.model, options.providerId);
+        : buildReasoningPayload(options.reasoning, options.reasoningStyle ?? "none", options.model, options.providerId, options.control);
     const reasoningOn = Boolean(options.reasoning?.enabled);
     // Kimchi exposes this model as `minimax-m3`; NVIDIA uses the longer
     // `minimaxai/minimax-m3` ID. Both need the larger default output budget.
     const isMinimaxM3 = /minimax-m3/i.test(options.model);
     const defaultMaxTokens = isMinimaxM3 ? 8_192 : reasoningOn ? 8_192 : 4_096;
     // One declarative sampling policy; explicit caller value wins.
-    const sampling = resolveSampling({
-        model: options.model,
-        reasoningEnabled: reasoningOn,
-        requestedTemperature: options.temperature,
-    });
+    const sampling = options.resolvedSampling ?? {
+        ...resolveSampling({
+            model: options.model,
+            reasoningEnabled: reasoningOn,
+            requestedTemperature: options.temperature,
+        }),
+    };
     const reasoningModel = isOpenAiReasoningModel(options.model);
+    const emitTemperature = sampling.temperature !== undefined &&
+        (options.resolvedSampling !== undefined || !reasoningModel);
     // Claude extended thinking via AgentRouter maps reasoning_effort to an
     // Anthropic `thinking.budget_tokens`, and the gateway (Bedrock) rejects the
     // request with HTTP 400 unless `max_tokens > budget_tokens`. Some upstream
@@ -1077,15 +1032,20 @@ function emitChatCompletionsBody(options) {
     const claudeThinking = reasoningOn &&
         options.reasoningStyle === "agentrouter" &&
         /claude/i.test(options.model);
-    const effectiveMaxTokens = claudeThinking
-        ? Math.max(options.maxTokens ?? defaultMaxTokens, 32_000)
-        : (options.maxTokens ?? defaultMaxTokens);
+    const requestedMaxTokens = options.maxTokens ?? defaultMaxTokens;
+    const claudeFloored = claudeThinking
+        ? Math.max(requestedMaxTokens, 32_000)
+        : requestedMaxTokens;
+    const effectiveMaxTokens = reasoningOn
+        ? outputBudgetWithReasoning(claudeFloored, options)
+        : claudeFloored;
     const body = {
         model: options.model,
         messages: toOpenAiMessages(singleLeadingSystemMessages(options.messages), options.supportsVision, options.replayTarget
             ? {
                 target: options.replayTarget,
                 observe: options.reasoningArtifactReplayObserver,
+                ...(options.forceReasoningReplay ? { forceScope: true } : {}),
             }
             : undefined),
         stream: options.stream,
@@ -1098,7 +1058,7 @@ function emitChatCompletionsBody(options) {
         // gpt-5.x / o1 / o3 / o4 only accept the default temperature (1) and
         // reject any explicit value — omit the field entirely rather than send
         // our 0.2 default and get a 400.
-        ...(reasoningModel ? {} : { temperature: sampling.temperature }),
+        ...(emitTemperature ? { temperature: sampling.temperature } : {}),
         ...reasoning,
         ...openAiToolBodyFields({
             tools: options.tools,
@@ -1106,7 +1066,7 @@ function emitChatCompletionsBody(options) {
             parallelToolCalls: options.parallelToolCalls,
         }),
     };
-    if (!reasoningModel && sampling.topP !== undefined) {
+    if (emitTemperature && sampling.topP !== undefined) {
         body.top_p = sampling.topP;
     }
     // OpenAI + many OpenAI-compatible gateways attach usage on the final SSE
@@ -1136,6 +1096,21 @@ export function chatCompletionsBodyFromPlan(plan, extras = {}) {
         reasoning: plan.controls.reasoning,
         reasoningStyle: extras.reasoningStyle,
         supportsVision: plan.images.visionAccepted,
+        control: {
+            profile: {
+                reasoning: plan.policy.reasoning,
+                capabilities: { acceptedParameters: plan.policy.acceptedParameters },
+            },
+            willReplayReasoning: plan.replay.decisions.some((entry) => entry.decision.action === "replayed"),
+            suppressed: plan.controls.controlSuppression !== undefined,
+        },
+        resolvedSampling: {
+            temperature: plan.controls.temperature,
+            topP: plan.controls.topP,
+        },
+        ...(plan.policy.limits.outputTokens !== undefined
+            ? { outputTokenLimit: plan.policy.limits.outputTokens }
+            : {}),
         tools: plan.tools.definitions.length
             ? [...plan.tools.definitions]
             : undefined,
@@ -1143,6 +1118,7 @@ export function chatCompletionsBodyFromPlan(plan, extras = {}) {
         parallelToolCalls: plan.tools.parallelToolCalls,
         replayTarget: plan.replay.target,
         reasoningArtifactReplayObserver: extras.reasoningArtifactReplayObserver,
+        ...(extras.forceReasoningReplay ? { forceReasoningReplay: true } : {}),
     });
 }
 function sentReasoningEffort(requestBody) {
@@ -1185,6 +1161,7 @@ export async function openAiCompatibleComplete(options) {
     const requestBody = chatCompletionsBodyFromPlan(plan, {
         reasoningStyle: options.reasoningStyle,
         reasoningArtifactReplayObserver: options.reasoningArtifactReplayObserver,
+        ...(options.forceReasoningReplay ? { forceReasoningReplay: true } : {}),
     });
     let response;
     try {
@@ -1244,7 +1221,8 @@ export async function openAiCompatibleComplete(options) {
         model: options.model,
         baseUrl: options.baseUrl,
         toolCalls,
-        policy: options.reasoningArtifactPolicy,
+        policy: options.reasoningArtifactPolicy ??
+            compatibleArtifactPolicyFor(plan.policy.reasoning.finalTurnPreservation),
         ...(typeof reasoning === "string" && reasoning
             ? { reasoning: { text: reasoning, sequence: 0 } }
             : {}),
@@ -1374,6 +1352,7 @@ export async function openAiCompatibleStream(options) {
         reasoningStyle: options.reasoningStyle,
         includeStreamUsage: options.includeStreamUsage,
         reasoningArtifactReplayObserver: options.reasoningArtifactReplayObserver,
+        ...(options.forceReasoningReplay ? { forceReasoningReplay: true } : {}),
     });
     let response;
     try {
@@ -1441,7 +1420,8 @@ export async function openAiCompatibleStream(options) {
                 model: options.model,
                 baseUrl: options.baseUrl,
                 toolCalls,
-                policy: options.reasoningArtifactPolicy,
+                policy: options.reasoningArtifactPolicy ??
+                    compatibleArtifactPolicyFor(plan.policy.reasoning.finalTurnPreservation),
                 ...(typeof reasoning === "string" && reasoning
                     ? { reasoning: { text: reasoning, sequence: 0 } }
                     : {}),
@@ -1509,7 +1489,10 @@ export async function openAiCompatibleStream(options) {
     let reasoningWireSeen = "";
     let finishReason;
     let terminalSignal;
-    const terminalPolicy = options.streamTerminal ?? CHAT_COMPLETIONS_STREAM_TERMINAL;
+    const terminalPolicy = options.streamTerminal ??
+        (plan.policy.terminal.proofs.length > 0
+            ? plan.policy.terminal
+            : CHAT_COMPLETIONS_STREAM_TERMINAL);
     const emittedByteCounts = () => {
         let toolArgumentBytes = 0;
         for (const state of toolCallState.values()) {
@@ -1545,7 +1528,8 @@ export async function openAiCompatibleStream(options) {
             model: options.model,
             baseUrl: options.baseUrl,
             toolCalls,
-            policy: options.reasoningArtifactPolicy,
+            policy: options.reasoningArtifactPolicy ??
+                compatibleArtifactPolicyFor(plan.policy.reasoning.finalTurnPreservation),
             ...(reasoningSeen
                 ? {
                     reasoning: {
@@ -1763,7 +1747,7 @@ export async function openAiCompatibleStream(options) {
                     const detail = typeof parsed.error === "string"
                         ? parsed.error
                         : (parsed.error.message ?? parsed.error.type ?? "unknown error");
-                    throw new ProviderError(`${options.provider} stream error: ${detail}`, undefined, payload.slice(0, 500));
+                    throw new ProviderError(`${options.provider} stream error: ${detail}`, inBandBadRequestStatus(parsed.error), payload.slice(0, 500));
                 }
                 {
                     const chunkUsage = options.providerId === "fireworks"
@@ -1771,6 +1755,7 @@ export async function openAiCompatibleStream(options) {
                         : parseOpenAiUsage(parsed.usage, options.usageAliases);
                     if (chunkUsage)
                         streamUsage = chunkUsage;
+                    const finalUsageFrame = isFinalUsageFrame(parsed);
                     const choice = parsed.choices?.[0];
                     const delta = choice?.delta;
                     const reasoningToken = delta?.reasoning_content ?? delta?.reasoning;
@@ -1790,10 +1775,17 @@ export async function openAiCompatibleStream(options) {
                         toolProgress) {
                         resetIdleTimer();
                     }
+                    if (terminalSignal === "usage-chunk" &&
+                        (token || reasoningToken || toolProgress)) {
+                        terminalSignal = undefined;
+                    }
                     if (choice?.finish_reason) {
                         finishReason = choice.finish_reason;
                         terminalSignal = "finish-reason";
                     }
+                    else if (finalUsageFrame && terminalSignal === undefined) {
+                        terminalSignal = "usage-chunk";
+                    }
                     if (reasoningToken) {
                         const normalized = normalizeChannelDelta(reasoningToken, reasoningWireSeen);
                         reasoningWireSeen = normalized.seen;