scalix 1.4.1 → 1.5.0

package/dist/api-client.js

@@ -1,15 +1,38 @@
-import { USER_AGENT, aiEndpointUrl } from './constants.js';
+import { USER_AGENT, aiEndpointUrl, AI_MAX_OUTPUT_TOKENS, AI_LEGACY_MAX_OUTPUT_TOKENS } from './constants.js';
 export class ApiError extends Error {
     status;
     body;
-    constructor(status, statusText, body) {
+    /** Parsed Retry-After header (ms) on 429/503 responses, when the server sent one. */
+    retryAfterMs;
+    constructor(status, statusText, body, retryAfterMs) {
         super(`API request failed: ${status} ${statusText}${body ? ` — ${body.slice(0, 200)}` : ''}`);
         this.name = 'ApiError';
         this.status = status;
         this.body = body;
+        this.retryAfterMs = retryAfterMs;
     }
 }
+/**
+ * Parse a Retry-After header value into milliseconds. Accepts both forms from
+ * RFC 9110: delta-seconds ("120") and HTTP-date. Returns undefined for absent
+ * or unparseable values, and clamps negatives to 0.
+ */
+export function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return parseInt(v, 10) * 1000;
+    const date = Date.parse(v);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
 const DEFAULT_TIMEOUT_MS = 120_000;
+// The capability probe only decides whether a turn streams. It must never be
+// the reason a turn is slow to start, so it gives up quickly and falls back to
+// the conservative answer.
+const CAPABILITY_PROBE_TIMEOUT_MS = 5_000;
 export class ScalixClient {
     baseURL;
     apiKey;
@@ -19,31 +42,133 @@ export class ScalixClient {
         this.apiKey = apiKey;
         this.timeoutMs = timeoutMs;
     }
-    async chatComplete(req, signal) {
-        // baseURL is the API host root; the gateway nests AI under /v1/ai.
-        // aiEndpointUrl() also tolerates a legacy base ending in /v1.
-        const url = aiEndpointUrl(this.baseURL, 'chat/completions');
-        const body = JSON.stringify(req);
-        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
-        const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${this.apiKey}`,
-                'User-Agent': USER_AGENT,
-            },
-            body,
-            signal: combined,
-        });
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new ApiError(response.status, response.statusText, text);
+    /** URL of the chat-completions endpoint. The Scalix gateway nests AI under
+     *  /v1/ai (aiEndpointUrl also tolerates a legacy base ending in /v1);
+     *  provider adapters override this with their own composition. */
+    chatUrl() {
+        return aiEndpointUrl(this.baseURL, 'chat/completions');
+    }
+    /**
+     * Set once an endpoint has rejected `stream_options`, so adapters stop
+     * asking for streamed usage for the rest of the session. See the retry in
+     * chatComplete below.
+     */
+    streamUsageUnsupported = false;
+    /**
+     * Session ceiling for `max_tokens` on the Scalix path. Starts at the current
+     * platform cap and drops to the legacy one the first time an endpoint
+     * rejects the larger value — a published CLI cannot assume which router
+     * version it is talking to, and a hard 422 mid-turn is a much worse outcome
+     * than one wasted round trip.
+     */
+    maxTokensCeiling = AI_MAX_OUTPUT_TOKENS;
+    /** Whether `maxTokensCeiling` can still be lowered (one step, once). */
+    canLowerMaxTokens() {
+        return this.maxTokensCeiling > AI_LEGACY_MAX_OUTPUT_TOKENS;
+    }
+    /** URL of the model-list endpoint, which also carries the capability block. */
+    modelsUrl() {
+        return aiEndpointUrl(this.baseURL, 'models');
+    }
+    capabilityProbe;
+    /**
+     * Capabilities the endpoint advertises on /models. There is no version header
+     * on the inference path, and a published CLI does not choose which deployment
+     * it is pointed at, so it asks rather than assuming. An older endpoint sends
+     * no capability block and an unreachable one must not fail a turn — both come
+     * back as `{}`, meaning "assume nothing". Probed once per client.
+     */
+    async endpointCapabilities() {
+        this.capabilityProbe ??= this.probeCapabilities();
+        return this.capabilityProbe;
+    }
+    async probeCapabilities() {
+        try {
+            const response = await fetch(this.modelsUrl(), {
+                headers: { 'Authorization': `Bearer ${this.apiKey}`, 'User-Agent': USER_AGENT },
+                signal: AbortSignal.timeout(CAPABILITY_PROBE_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return {};
+            const body = await response.json();
+            return body.capabilities ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Adapter hook: last-mile request rewrite before serialization (e.g. drop
+     *  fields a third-party endpoint would reject). Default for the Scalix path:
+     *  hold max_tokens under the session ceiling. BYOK adapters deliberately do
+     *  NOT inherit this — their ceiling is the user's own model, not ours. */
+    prepareRequest(req) {
+        if (req.max_tokens != null && req.max_tokens > this.maxTokensCeiling) {
+            return { ...req, max_tokens: this.maxTokensCeiling };
         }
-        if (req.stream) {
-            return this.parseSSEStream(response);
+        return req;
+    }
+    async chatComplete(req, signal) {
+        const url = this.chatUrl();
+        // Looped rather than straight-line so a request the endpoint won't accept
+        // can be narrowed and re-sent — see the !response.ok branch below. Each
+        // narrowing is one-way and latched on the client, so the loop can only run
+        // as many times as there are narrowings left.
+        for (;;) {
+            const prepared = this.prepareRequest(req);
+            const body = JSON.stringify(prepared);
+            const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+            const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'User-Agent': USER_AGENT,
+                    'x-client-type': 'cli',
+                },
+                body,
+                signal: combined,
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => '');
+                // `stream_options` is a late addition to the OpenAI wire — Azure only
+                // accepts it on recent api-versions, and a few compat servers validate
+                // strictly enough to 400 on it. Failing the turn to protect a token
+                // count is the wrong trade: drop the field for the rest of the session
+                // and send the request again.
+                if (!this.streamUsageUnsupported && response.status === 400 && prepared.stream_options && /stream_options/i.test(text)) {
+                    this.streamUsageUnsupported = true;
+                    continue;
+                }
+                // The platform's own output cap was raised; older deployments still
+                // hard-reject (422) anything over the legacy ceiling, and a published
+                // CLI does not get to choose which one it is pointed at. Take the
+                // endpoint's word for it, lower the ceiling for the session, and re-send
+                // rather than failing a turn over a number we can simply reduce.
+                if (this.canLowerMaxTokens() && (response.status === 422 || response.status === 400)
+                    && prepared.max_tokens != null && prepared.max_tokens > AI_LEGACY_MAX_OUTPUT_TOKENS
+                    && /max_tokens/i.test(text)) {
+                    this.maxTokensCeiling = AI_LEGACY_MAX_OUTPUT_TOKENS;
+                    continue;
+                }
+                throw new ApiError(response.status, response.statusText, text, parseRetryAfter(response.headers.get('retry-after')));
+            }
+            if (req.stream) {
+                return this.parseSSEStream(response);
+            }
+            const result = await response.json();
+            // Non-streaming inference responses carry the platform's cost estimate as a
+            // header (x-scalix-cost-cents). Attach it to usage so cost tracking shows
+            // REAL platform-derived figures — never fabricated client-side prices. The
+            // body's own usage.cost (if the platform ever sends one) takes precedence.
+            if (result.usage && result.usage.cost == null) {
+                const cents = parseFloat(response.headers.get('x-scalix-cost-cents') || '');
+                if (Number.isFinite(cents) && cents > 0) {
+                    result.usage.cost = cents / 100;
+                }
+            }
+            return result;
         }
-        return await response.json();
     }
     async *parseSSEStream(response) {
         const reader = response.body?.getReader();