@juspay/neurolink 12.46.1 → 12.47.0

package/dist/providers/cloudflareClef.js

@@ -0,0 +1,331 @@
+import { CloudflareClefModels } from "../constants/enums.js";
+import { logger } from "../utils/logger.js";
+import { redactUrlForError } from "../utils/logSanitize.js";
+import { getProviderModel } from "../utils/providerConfig.js";
+import { isRecord, redactCredentials, SystemOneDecisionProvider, } from "./systemOneDecision.js";
+const CLOUDFLARE_DEFAULT_BASE_URL = "https://api.cloudflare.com/client/v4";
+const MODEL_PREFIX = "@cf/cloudflare/";
+/**
+ * Cloudflare account ids are 32 hex digits. The pattern is wider so that a
+ * change of format needs no release, but it still keeps `/`, `.`, `?` and
+ * whitespace out of the URL path the id is placed in.
+ */
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** The only image formats the API reads; anything else is a 422. */
+const SUPPORTED_IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+]);
+/**
+ * The uuid Workers AI appends to an `AiError` message, in parentheses. It starts
+ * at a literal `(`, with no leading `\s*`: that one backtracks quadratically on
+ * a long run of spaces, and the message is whatever the server sent.
+ */
+const TRAILING_REQUEST_ID = /\(([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\)\s*$/i;
+const MAX_ERROR_MESSAGE_CHARS = 500;
+/**
+ * An error message is cut to this before any pattern runs on it, so a hostile or
+ * garbled body cannot hold the event loop. Cloudflare's own messages are far
+ * shorter (the longest seen was about 350 characters).
+ */
+const MAX_PARSED_MESSAGE_CHARS = 4096;
+function normalizeBaseURL(raw) {
+    return raw.replace(/\/+$/, "");
+}
+/**
+ * A base URL that cannot work is refused up front, and its text is never
+ * repeated: `fetch` rejects a URL with userinfo and echoes it in the error, the
+ * route is appended after a query string or fragment, and any of them can hold
+ * a credential.
+ */
+function baseURLProblem(baseURL) {
+    const fix = `Set CLOUDFLARE_CLEF_BASE_URL or pass credentials.cloudflareClef.baseURL to a base URL, or leave both unset to use ${CLOUDFLARE_DEFAULT_BASE_URL}.`;
+    try {
+        const url = new URL(baseURL);
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            return `The Cloudflare base URL must start with https:// or http://. ${fix}`;
+        }
+        // `url.search` and `url.hash` are empty for a bare trailing `?` or `#`, which
+        // would still put the route into the query or the fragment, so the text is
+        // checked as well.
+        return url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            /[?#]/.test(baseURL)
+            ? `The Cloudflare base URL must not carry credentials, a query string or a fragment. ${fix}`
+            : undefined;
+    }
+    catch {
+        return `The Cloudflare base URL is not a valid absolute URL. ${fix}`;
+    }
+}
+/**
+ * The name Cloudflare wants in the path and the body: `clef` or `clef-flash`,
+ * given either bare or as `@cf/cloudflare/clef`. Anything with a `/` in it is
+ * refused, so a model name cannot reach a different route.
+ */
+function wireModel(model) {
+    const bare = model.trim().replace(/^@cf\/cloudflare\//i, "");
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(bare) ? bare.toLowerCase() : undefined;
+}
+/**
+ * Why this image cannot be sent, or undefined when it can. The data URL is
+ * never repeated: it is megabytes of base64. Size limits are left to the
+ * server, which refuses an oversized image at once with a clear 422.
+ */
+function imageProblem(dataUrl, position) {
+    const type = /^data:([a-z]+\/[a-z0-9.+-]+);base64,/i
+        .exec(dataUrl)?.[1]
+        ?.toLowerCase();
+    return type && SUPPORTED_IMAGE_TYPES.has(type)
+        ? undefined
+        : `Image ${position} is not a PNG, JPEG or WebP image, the only formats Cloudflare Clef reads.`;
+}
+/** The API takes a string or structured data as `state`; a number or a boolean is sent as its text. */
+function wireState(state) {
+    return typeof state === "number" || typeof state === "boolean"
+        ? String(state)
+        : state;
+}
+/**
+ * `{"success":false,"errors":[{"code","message"}],...}` is Cloudflare's own
+ * envelope. A model-side refusal nests a second one inside the message:
+ * `AiError: AiError: {"error":{"message","details":{"fieldErrors":{...}}}} (<uuid>)`.
+ * Both are flattened to one readable line, with the uuid taken out as the
+ * request id. A body that is not this envelope reads as undefined and the
+ * caller falls back to the status.
+ */
+function readCloudflareError(body) {
+    if (!isRecord(body) || !Array.isArray(body.errors)) {
+        return undefined;
+    }
+    const first = body.errors.find(isRecord);
+    if (!first || typeof first.message !== "string" || first.message === "") {
+        return undefined;
+    }
+    let text = first.message.slice(0, MAX_PARSED_MESSAGE_CHARS).trimEnd();
+    let requestId;
+    const trailing = TRAILING_REQUEST_ID.exec(text);
+    if (trailing) {
+        requestId = trailing[1];
+        text = text.slice(0, trailing.index).trimEnd();
+    }
+    text = text.replace(/^(?:AiError:\s*|Ai:\s*)+/, "").trim();
+    if (text.startsWith("{")) {
+        try {
+            const inner = JSON.parse(text);
+            if (isRecord(inner) && isRecord(inner.error)) {
+                const details = isRecord(inner.error.details)
+                    ? inner.error.details
+                    : undefined;
+                const fields = isRecord(details?.fieldErrors)
+                    ? Object.entries(details.fieldErrors).flatMap(([field, problems]) => Array.isArray(problems)
+                        ? problems
+                            .filter((p) => typeof p === "string")
+                            .map((p) => `${field}: ${p}`)
+                        : [])
+                    : [];
+                const head = typeof inner.error.message === "string" ? inner.error.message : text;
+                text = fields.length > 0 ? `${head}: ${fields.join("; ")}` : head;
+            }
+        }
+        catch {
+            // not JSON after all; keep the text as it is
+        }
+    }
+    return {
+        message: text,
+        code: typeof first.code === "number" ? first.code : undefined,
+        requestId,
+    };
+}
+/**
+ * Only 401 is `authentication`, and so only 401 trips the breaker: Cloudflare
+ * answered a token it does not know with a 401 and code 10000 (seen live). A 403
+ * was never seen, and no such token was available to provoke one; if Cloudflare
+ * uses it for a token that lacks Workers AI permission, that is fixed in the
+ * dashboard, and a breaker that latched on it would keep this instance disabled
+ * until the process restarted, even after the permission was granted. So a 403
+ * is a non-retried `invalid_request` that carries Cloudflare's own message. A
+ * request over the context window is a 413, code 5021, and a 429 is "Capacity
+ * temporarily exceeded" (code 3040, no Retry-After), which is retryable.
+ * Validation refusals are 422, and a malformed body or a wrong route is a 400;
+ * none of those is retried.
+ */
+function cloudflareErrorKind(status, code) {
+    if (status === 401) {
+        return "authentication";
+    }
+    if (status === 413 || code === 5021) {
+        return "max_tokens_exceeded";
+    }
+    if (status === 429) {
+        return "rate_limit";
+    }
+    if (status === 503) {
+        return "overloaded";
+    }
+    return status >= 500 ? "server" : "invalid_request";
+}
+/**
+ * Cloudflare Clef — the `decide` inference type only.
+ *
+ * `@cf/cloudflare/clef` (27B) and `@cf/cloudflare/clef-flash` (9B) answer the
+ * same typed `noul` / `choice` / `score` questions as the other decision
+ * providers, follow the System One wire, and read images. They are reached
+ * through the Workers AI REST API, which wraps every answer in Cloudflare's own
+ * `{ result, success, errors }` envelope and puts the model in the URL path.
+ *
+ * The token and account id are the ones the Cloudflare Workers AI text provider
+ * reads (`CLOUDFLARE_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`), so a host that has
+ * configured that provider has also configured this one.
+ *
+ * The Workers AI endpoint ignores text past about 2,048 tokens, far below
+ * the documented 64K (hosted service or model: unknown). See `decisionLimits`
+ * on the descriptor for the measured figures.
+ *
+ * @see https://developers.cloudflare.com/workers-ai/models/clef/
+ */
+export class CloudflareClefProvider extends SystemOneDecisionProvider {
+    apiKey;
+    accountId;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        super(modelName, "cloudflare-clef", sdk);
+        // A slice that names its own base URL must bring its own token: the shared
+        // CLOUDFLARE_API_KEY also runs the host's Workers AI text provider, and it
+        // must never be sent as a bearer token to an endpoint a caller chose.
+        const ownEndpoint = Boolean(credentials?.baseURL?.trim());
+        this.apiKey =
+            credentials?.apiKey?.trim() ||
+                (ownEndpoint ? "" : (process.env.CLOUDFLARE_API_KEY?.trim() ?? ""));
+        this.accountId =
+            credentials?.accountId?.trim() ||
+                (process.env.CLOUDFLARE_ACCOUNT_ID?.trim() ?? "");
+        // `||`, not `??`, so a blank override counts as unset.
+        this.baseURL = normalizeBaseURL(credentials?.baseURL?.trim() ||
+            process.env.CLOUDFLARE_CLEF_BASE_URL?.trim() ||
+            CLOUDFLARE_DEFAULT_BASE_URL);
+        // A base URL that `baseURLProblem` refuses is not logged at all: it can
+        // carry `user:pass@` or a `?token=`.
+        logger.debug("Cloudflare Clef decision provider initialized (decide only)", {
+            modelName: this.modelName,
+            baseURL: baseURLProblem(this.baseURL)
+                ? "(invalid)"
+                : redactUrlForError(this.baseURL),
+            accountConfigured: this.accountId !== "",
+        });
+    }
+    getDefaultModel() {
+        return getProviderModel("CLOUDFLARE_CLEF_MODEL", CloudflareClefModels.CLEF);
+    }
+    vendorLabel() {
+        return "Cloudflare";
+    }
+    vendorDisplayName() {
+        return "Cloudflare Clef";
+    }
+    decisionApiKey() {
+        return this.apiKey;
+    }
+    missingKeyMessage() {
+        return "Cloudflare Clef requires an API token with Workers AI permission. Set CLOUDFLARE_API_KEY or pass credentials.cloudflareClef.apiKey.";
+    }
+    missingConfigMessage() {
+        if (this.accountId === "") {
+            return "Cloudflare Clef requires the account id. Set CLOUDFLARE_ACCOUNT_ID or pass credentials.cloudflareClef.accountId.";
+        }
+        if (!ACCOUNT_ID_PATTERN.test(this.accountId)) {
+            return "The Cloudflare account id may contain only letters, digits, '-' and '_'. Copy it from the Cloudflare dashboard.";
+        }
+        return baseURLProblem(this.baseURL);
+    }
+    /** The model is part of the path, so the endpoint depends on the model asked for. */
+    decisionEndpoint(model) {
+        return `${this.baseURL}/accounts/${encodeURIComponent(this.accountId)}/ai/run/${MODEL_PREFIX}${encodeURIComponent(wireModel(model) ?? model)}`;
+    }
+    decisionHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    /**
+     * Images travel in their own `images` array, as `data:` URLs, placed before
+     * the state by the server. `model` is sent although the path already names
+     * it: the API documents it as required, and refuses a body whose `model`
+     * differs from the path.
+     */
+    buildDecisionBody(state, questions, model, media) {
+        const wire = wireModel(model);
+        if (!wire) {
+            throw this.decisionError({
+                kind: "invalid_request",
+                message: `"${model.slice(0, 40)}" is not a Cloudflare model name. Use "clef" or "clef-flash".`,
+                retryable: false,
+            });
+        }
+        // Workers AI also accepts image/jpg; use the canonical JPEG MIME type.
+        const images = (media?.images ?? []).map((dataUrl) => dataUrl.replace(/^data:image\/jpg;base64,/i, "data:image/jpeg;base64,"));
+        images.forEach((dataUrl, index) => {
+            const problem = imageProblem(dataUrl, index + 1);
+            if (problem) {
+                throw this.decisionError({
+                    kind: "invalid_request",
+                    message: problem,
+                    retryable: false,
+                });
+            }
+        });
+        // The canonical JPEG prefix is one byte longer than image/jpg. Keep the
+        // prepared media metadata aligned with the URLs actually sent.
+        if (media) {
+            media.images = images;
+            media.bytes = images.reduce((total, image) => total + Buffer.byteLength(image), 0);
+        }
+        return {
+            model: wire,
+            state: wireState(state),
+            questions,
+            ...(images.length > 0 ? { images } : {}),
+        };
+    }
+    /** A success is `{ result: { model, answers, usage }, success: true }`. */
+    readDecisionPayload(payload) {
+        return isRecord(payload) && isRecord(payload.result)
+            ? payload.result
+            : payload;
+    }
+    parseDecisionError(status, payload, requestId) {
+        const fallback = `Cloudflare request failed with HTTP ${status}`;
+        const parsed = readCloudflareError(payload);
+        const kind = cloudflareErrorKind(status, parsed?.code);
+        let message = redactCredentials(parsed?.message ?? fallback, this.apiKey)
+            .trim()
+            .slice(0, MAX_ERROR_MESSAGE_CHARS) || fallback;
+        if (kind === "max_tokens_exceeded") {
+            message +=
+                " Cloudflare counts the whole request, image data included, at about four characters per token.";
+        }
+        else if (parsed?.code === 7000) {
+            message += `. Check the model name (Clef is served as "clef" and "clef-flash") and the base URL, which must end in /client/v4 and name your account.`;
+        }
+        return {
+            kind,
+            message,
+            status,
+            requestId: requestId ?? parsed?.requestId,
+            retryable: kind === "rate_limit" || kind === "overloaded" || kind === "server",
+        };
+    }
+    /**
+     * `cf-ai-req-id` is on every answer that reached the model, success or
+     * refusal. A 401 and a wrong-path 400 never reach it, so they carry only the
+     * edge's `cf-ray`.
+     */
+    readRequestId(headers) {
+        return headers.get("cf-ai-req-id") ?? headers.get("cf-ray") ?? undefined;
+    }
+}

package/dist/providers/systemOneDecision.d.ts

@@ -59,7 +59,11 @@ export declare abstract class SystemOneDecisionProvider extends BaseProvider {
      * nothing is missing.
      */
     protected missingConfigMessage(): string | undefined;
-    protected abstract decisionEndpoint(): string;
+    /**
+     * Where the request goes. The model asked for is passed in because one
+     * vendor names it in the URL path; every other provider ignores it.
+     */
+    protected abstract decisionEndpoint(model: string): string;
     protected abstract decisionHeaders(): Record<string, string>;
     protected abstract buildDecisionBody(state: DecisionState, questions: Record<string, Record<string, unknown>>, model: string, media?: DecisionPreparedMedia): Record<string, unknown>;
     protected abstract parseDecisionError(status: number, payload: unknown, requestId: string | undefined): DecisionError;
@@ -81,6 +85,13 @@ export declare abstract class SystemOneDecisionProvider extends BaseProvider {
      * grows with the number of questions scales the descriptor's allowance here.
      */
     protected defaultTimeoutMs(_questionCount: number): number | undefined;
+    /**
+     * The part of a successful response that holds `answers`, `usage` and
+     * `model`. The default is the response itself; a vendor that wraps every
+     * answer in an envelope returns what is inside it. Errors are not passed
+     * through here: they are read from the whole response.
+     */
+    protected readDecisionPayload(payload: unknown): unknown;
     /** Per-question confidence a transport reports outside the answer objects. */
     protected reportedConfidence(_payload: unknown): Record<string, number>;
     protected resolveResponseModel(payload: Record<string, unknown>, requestedModel: string): string;

package/dist/providers/systemOneDecision.js

@@ -6,7 +6,7 @@ import { ProviderError } from "../types/index.js";
 import { prepareDecisionMedia } from "../utils/decisionMedia.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlsInText } from "../utils/logSanitize.js";
-import { estimateTokens, serializeForEstimate, } from "../utils/tokenEstimation.js";
+import { CHARS_PER_TOKEN, estimateTokens, serializeForEstimate, } from "../utils/tokenEstimation.js";
 /**
  * Generous enough for a cold start (measured at 2.0–2.7s after idle on Jev)
  * while still bounded. Every internal caller is fail-open, so this only bites
@@ -177,15 +177,52 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
  * tokenizer, so when a provider declares a rate, non-ASCII characters are
  * counted at it instead. ASCII text is estimated exactly as before.
  */
-function estimateDecisionStateTokens(text, nonAsciiTokensPerChar) {
-    if (nonAsciiTokensPerChar === undefined) {
+function estimateDecisionStateTokens(text, nonAsciiTokensPerChar, rates = {}) {
+    const { digit, symbol, astral } = rates;
+    if (nonAsciiTokensPerChar === undefined &&
+        digit === undefined &&
+        symbol === undefined &&
+        astral === undefined) {
         return estimateTokens(text);
     }
-    const chars = [...text];
-    const isAscii = (c) => (c.codePointAt(0) ?? 0) <= 0x7f;
-    const ascii = chars.filter(isAscii).join("");
-    const nonAsciiCount = chars.length - ascii.length;
-    return (estimateTokens(ascii) + Math.ceil(nonAsciiCount * nonAsciiTokensPerChar));
+    // Each class of character is counted once, at its own rate. A class with no
+    // declared rate stays in the ordinary four-characters-a-token estimate (or,
+    // for non-ASCII, at that estimate's per-character rate), so a provider that
+    // declares none of the extra rates is estimated exactly as before.
+    const isDigit = (c) => c >= "0" && c <= "9";
+    const isSymbol = (c) => /[!-/:-@[-`{-~]/.test(c);
+    let digits = 0;
+    let symbols = 0;
+    let astrals = 0;
+    let nonAscii = 0;
+    const rest = [];
+    for (const c of text) {
+        const code = c.codePointAt(0) ?? 0;
+        if (code > 0xffff && astral !== undefined) {
+            astrals += 1;
+        }
+        else if (code > 0x7f) {
+            nonAscii += 1;
+        }
+        else if (digit !== undefined && isDigit(c)) {
+            digits += 1;
+        }
+        else if (symbol !== undefined && isSymbol(c)) {
+            symbols += 1;
+        }
+        else {
+            rest.push(c);
+        }
+    }
+    // Digits, punctuation and astral characters (emoji) are charged separately
+    // only when the provider declares a rate for them: a tokenizer that reads each
+    // digit, and most punctuation, on its own makes a number-heavy or JSON-heavy
+    // state several times longer than four characters a token suggests.
+    return (estimateTokens(rest.join("")) +
+        Math.ceil(digits * (digit ?? 0)) +
+        Math.ceil(symbols * (symbol ?? 0)) +
+        Math.ceil(astrals * (astral ?? 0)) +
+        Math.ceil(nonAscii * (nonAsciiTokensPerChar ?? 1 / CHARS_PER_TOKEN)));
 }
 /**
  * The shared half of every "System One" decision provider — a model that takes
@@ -251,6 +288,15 @@ export class SystemOneDecisionProvider extends BaseProvider {
     defaultTimeoutMs(_questionCount) {
         return this.getDescriptorDecideMs();
     }
+    /**
+     * The part of a successful response that holds `answers`, `usage` and
+     * `model`. The default is the response itself; a vendor that wraps every
+     * answer in an envelope returns what is inside it. Errors are not passed
+     * through here: they are read from the whole response.
+     */
+    readDecisionPayload(payload) {
+        return payload;
+    }
     /** Per-question confidence a transport reports outside the answer objects. */
     reportedConfidence(_payload) {
         return {};
@@ -354,7 +400,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
                 const signal = request.signal
                     ? AbortSignal.any([request.signal, timeout])
                     : timeout;
-                const response = await this.proxyFetch(this.decisionEndpoint(), {
+                const response = await this.proxyFetch(this.decisionEndpoint(resolvedModel), {
                     method: "POST",
                     headers: this.decisionHeaders(),
                     body,
@@ -393,7 +439,8 @@ export class SystemOneDecisionProvider extends BaseProvider {
                     await sleep(retryAfterMs ?? 2 ** attempt * 250 + Math.random() * 250, request.signal);
                     continue;
                 }
-                if (!isRecord(payload) || !isRecord(payload.answers)) {
+                const decoded = this.readDecisionPayload(payload);
+                if (!isRecord(decoded) || !isRecord(decoded.answers)) {
                     throw this.decisionError({
                         kind: "server",
                         message: `${label} returned a response without an answers map.`,
@@ -402,9 +449,9 @@ export class SystemOneDecisionProvider extends BaseProvider {
                         retryable: false,
                     });
                 }
-                const reported = this.reportedConfidence(payload);
+                const reported = this.reportedConfidence(decoded);
                 const answers = {};
-                for (const [id, raw] of Object.entries(payload.answers)) {
+                for (const [id, raw] of Object.entries(decoded.answers)) {
                     const parsed = parseDecisionAnswer(raw, reported[id]);
                     if (parsed) {
                         answers[id] = parsed;
@@ -415,13 +462,13 @@ export class SystemOneDecisionProvider extends BaseProvider {
                         });
                     }
                 }
-                const usage = isRecord(payload.usage) ? payload.usage : {};
+                const usage = isRecord(decoded.usage) ? decoded.usage : {};
                 return {
                     // `resolvedModel`, not `this.modelName`: when the caller pinned a
                     // model for this one request and the response omits its own, the
                     // instance default would be reported instead of the model actually
                     // asked for.
-                    model: this.resolveResponseModel(payload, resolvedModel),
+                    model: this.resolveResponseModel(decoded, resolvedModel),
                     provider: this.providerName,
                     answers,
                     // Two spellings for one field. The System One wire sends
@@ -485,8 +532,9 @@ export class SystemOneDecisionProvider extends BaseProvider {
      * applies to.
      */
     assertWithinRequestBytes(body) {
-        const limit = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)
-            ?.decisionLimits?.media?.maxRequestBytes;
+        const media = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)
+            ?.decisionLimits?.media;
+        const limit = media?.maxRequestBytes;
         if (limit === undefined) {
             return;
         }
@@ -494,7 +542,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
         if (bytes > limit) {
             throw this.decisionError({
                 kind: "invalid_request",
-                message: `The request is ${bytes} bytes; ${this.vendorLabel()} accepts at most ${limit}. Send fewer or smaller images, or a shorter video.`,
+                message: `The request is ${bytes} bytes; ${this.vendorLabel()} accepts at most ${limit}. Send fewer or smaller images${media?.video ? ", or a shorter video" : ""}.`,
                 retryable: false,
             });
         }
@@ -520,7 +568,11 @@ export class SystemOneDecisionProvider extends BaseProvider {
         }
         const modelLimits = limits.models?.[model];
         const maxStateTokens = modelLimits?.maxStateTokens ?? limits.maxStateTokens;
-        const stateTokens = estimateDecisionStateTokens(serializeForEstimate(request.state), modelLimits?.nonAsciiTokensPerChar ?? limits.nonAsciiTokensPerChar);
+        const stateTokens = estimateDecisionStateTokens(serializeForEstimate(request.state), modelLimits?.nonAsciiTokensPerChar ?? limits.nonAsciiTokensPerChar, {
+            digit: limits.digitTokensPerChar,
+            symbol: limits.symbolTokensPerChar,
+            astral: limits.astralTokensPerChar,
+        });
         if (stateTokens > maxStateTokens) {
             throw this.decisionError({
                 kind: "max_tokens_exceeded",

package/dist/types/decision.d.ts

@@ -153,6 +153,28 @@ export type DecisionLimits = {
      * estimate for every character.
      */
     nonAsciiTokensPerChar?: number;
+    /**
+     * Tokens charged per ASCII digit. A tokenizer that reads every digit as its
+     * own token makes numbers, ids and timestamps several times longer than the
+     * default estimate of four characters per token. Absent = digits are
+     * estimated like any other ASCII character.
+     */
+    digitTokensPerChar?: number;
+    /**
+     * Tokens charged per ASCII punctuation or symbol character (`,` `.` `{` `"`
+     * `:` and the like). The same tokenizers that read each digit alone read most
+     * punctuation alone too, so JSON, logs and lists of numbers run far above four
+     * characters a token. Absent = punctuation is estimated like any other ASCII
+     * character.
+     */
+    symbolTokensPerChar?: number;
+    /**
+     * Tokens charged per character outside the Basic Multilingual Plane (emoji
+     * and the like), which is counted separately from `nonAsciiTokensPerChar`
+     * because it costs about twice as much. Absent = charged at
+     * `nonAsciiTokensPerChar`.
+     */
+    astralTokensPerChar?: number;
     /** Per-model limits, keyed by model id; each field overrides the one above. */
     models?: Readonly<Record<string, {
         maxStateTokens: number;

package/dist/types/providers.d.ts

@@ -583,6 +583,19 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    /**
+     * Cloudflare Clef — the `decide` inference type, reached through Workers AI.
+     * The token and account id are the ones the `cloudflare` text provider reads
+     * (`CLOUDFLARE_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`), but this slice is separate
+     * so the two cannot be mixed up. Both are required. `baseURL` is optional and
+     * defaults to `https://api.cloudflare.com/client/v4`; requests go to
+     * `<baseURL>/accounts/<accountId>/ai/run/@cf/cloudflare/<model>`.
+     */
+    cloudflareClef?: {
+        apiKey?: string;
+        accountId?: string;
+        baseURL?: string;
+    };
 };
 /**
  * Voyage AI /embeddings response shape.
@@ -2325,6 +2338,8 @@ export type ProviderDescriptor = {
         extraRequired?: readonly string[];
         /** Alternate ways to satisfy extraRequired when it isn't a plain env-var list (e.g. Vertex's file-path-OR-individual-fields auth). Each entry is either a single env var name (satisfied alone) or a nested array of names that must ALL be present together (e.g. Vertex's GOOGLE_AUTH_CLIENT_EMAIL + GOOGLE_AUTH_PRIVATE_KEY pair, which is only valid as a pair). Evaluate with `satisfiesFallbacks()` (providerConfig.ts) rather than re-deriving this logic at each call site. */
         extraRequiredFallbacks?: readonly (string | readonly string[])[];
+        /** For an `extraRequired` name that can also be given in `credentials.<credentialsKey>`: the field of that slice that stands for it (e.g. `{ CLOUDFLARE_ACCOUNT_ID: "accountId" }`). A base URL needs no entry; it is matched through `baseURL` above. */
+        extraRequiredCredentialFields?: Readonly<Record<string, string>>;
         /** True when the provider is usable with zero configuration (local runtime with a documented default URL, or a documented non-secret default like LiteLLM's "sk-anything"). */
         optional?: boolean;
     };

package/dist/utils/modelChoices.js

@@ -2,7 +2,7 @@
  * Centralized model choices for CLI commands
  * Derives choices from model enums to ensure consistency
  */
-import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, ReplicateModels, } from "../constants/enums.js";
+import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, CloudflareClefModels, ReplicateModels, } from "../constants/enums.js";
 import { getCatalogJsonEntries } from "../providers/catalog/loader.js";
 /**
  * Looks up the JSON catalog entry for a provider, if it is one of the 11
@@ -399,6 +399,16 @@ const TOP_MODELS_CONFIG = {
             description: "Recommended - Perplexity decision model that also reads images",
         },
     ],
+    [AIProviderName.CLOUDFLARE_CLEF]: [
+        {
+            model: CloudflareClefModels.CLEF,
+            description: "Recommended - Cloudflare Clef 27B decision model that also reads images (state limited to ~2,000 tokens)",
+        },
+        {
+            model: CloudflareClefModels.CLEF_FLASH,
+            description: "Clef-flash 9B - the faster, cheaper Cloudflare decision model (same ~2,000-token state limit)",
+        },
+    ],
     [AIProviderName.AUTO]: [],
 };
 /**
@@ -441,6 +451,7 @@ export const DEFAULT_MODELS = {
     [AIProviderName.LAYA]: LayaModels.TYPED_DECISIONS,
     [AIProviderName.XOR]: XorModels.XOR_1_1,
     [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels.PPLX_DECIDER_V1_27B,
+    [AIProviderName.CLOUDFLARE_CLEF]: CloudflareClefModels.CLEF,
 };
 /**
  * Model enum mappings for getAllModels.
@@ -476,6 +487,7 @@ const MODEL_ENUMS = {
     [AIProviderName.LAYA]: LayaModels,
     [AIProviderName.XOR]: XorModels,
     [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels,
+    [AIProviderName.CLOUDFLARE_CLEF]: CloudflareClefModels,
     [AIProviderName.AUTO]: null,
 };
 /**

package/dist/utils/pricing.js

@@ -788,6 +788,18 @@ const PRICING = {
         _default: { input: 0.04 / 1_000_000, output: 0 },
         "pplx-decider-v1-27b": { input: 0.04 / 1_000_000, output: 0 },
     },
+    "cloudflare-clef": {
+        // Workers AI bills Clef per million INPUT tokens ($0.24 for clef, $0.09 for
+        // clef-flash); no output price is listed. `output: 0` is a price, not a token
+        // count, so do not "correct" it from `usage.output_tokens`. The `cf-ai-neurons`
+        // response header was checked against the published neuron rates on
+        // 2026-10-03 and matched them exactly (21,818 and 8,182 neurons per million
+        // input tokens). Rates from Cloudflare's Workers AI pricing page. An unknown
+        // model name is priced as clef, the dearer of the two.
+        _default: { input: 0.24 / 1_000_000, output: 0 },
+        clef: { input: 0.24 / 1_000_000, output: 0 },
+        "clef-flash": { input: 0.09 / 1_000_000, output: 0 },
+    },
     stability: {
         // Stability AI bills per image; symbolic per-token rate.
         _default: { input: 0, output: 0.04 / 1_000 },

package/dist/utils/providerConfig.d.ts

@@ -416,3 +416,10 @@ export declare function createXorConfig(): ProviderConfigOptions;
  * provider and has a public endpoint, so the key alone configures it.
  */
 export declare function createPerplexityDeciderConfig(): ProviderConfigOptions;
+/**
+ * Cloudflare Clef — the `decide` inference type, reached through Workers AI,
+ * not the Workers AI text models. It reads the same CLOUDFLARE_API_KEY and
+ * CLOUDFLARE_ACCOUNT_ID as the `cloudflare` text provider; the endpoint is
+ * Cloudflare's own, so the two together configure it.
+ */
+export declare function createCloudflareClefConfig(): ProviderConfigOptions;