@juspay/neurolink 13.4.7 → 13.4.9

package/dist/proxy/geminiFormat.js

@@ -37,13 +37,70 @@ function partsToText(parts) {
         .filter(Boolean)
         .join("");
 }
+/** `image/<subtype>` as a MIME restricted-name (RFC 6838): no space, comma or semicolon. */
+const IMAGE_MIME_TYPE = /^image\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i;
+/** Standard or URL-safe base64, the two alphabets Google's JSON `bytes` fields accept. */
+const RAW_BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/;
+/**
+ * `data` as padded standard-alphabet base64, which is what a `data:` URI carries,
+ * or undefined when it is not well-formed base64.
+ *
+ * The SDK forwards the base64 text of a `data:` URI to the provider as it is, so
+ * a URL-safe or unpadded payload would reach a provider that expects neither.
+ * The alphabet check alone lets through a payload no decoder takes: one
+ * character over a multiple of four is no base64 length at all, and padding
+ * must be exactly what the length calls for.
+ */
+function toStandardBase64(data) {
+    const standard = /[-_]/.test(data)
+        ? data.replace(/-/g, "+").replace(/_/g, "/")
+        : data;
+    const body = standard.replace(/=+$/, "");
+    const padding = standard.length - body.length;
+    const missing = (4 - (body.length % 4)) % 4;
+    if (missing === 3 || (padding > 0 && padding !== missing)) {
+        return undefined;
+    }
+    return `${body}${"=".repeat(missing)}`;
+}
+/**
+ * The `input.images` entry for one `inlineData`, or undefined when it has none.
+ *
+ * Google's wire format puts raw base64 in `data` and the type in a sibling
+ * `mimeType`, while the image vetter takes only `data:` URIs and https URLs, so
+ * raw base64 of an image type is wrapped into a `data:` URI here. The SDK reads
+ * a `data:` string as inline bytes and never as a path or URL.
+ *
+ * Anything else is passed on as it came and left to the vetter: a value that
+ * is not base64 (a `data:` URI, an https URL, a path) is judged as the
+ * reference it names, and base64 with a missing, non-image or malformed
+ * `mimeType`, an impossible length or inconsistent padding is refused there as
+ * `invalid_image_reference`. Audio and PDF parts land in the same place; this
+ * parser has never told them from images.
+ */
+function inlineDataToImage(inlineData) {
+    const data = inlineData?.data;
+    if (typeof data !== "string" || data.length === 0) {
+        return undefined;
+    }
+    const mimeType = inlineData?.mimeType;
+    if (typeof mimeType !== "string" ||
+        !IMAGE_MIME_TYPE.test(mimeType) ||
+        !RAW_BASE64.test(data)) {
+        return data;
+    }
+    const standard = toStandardBase64(data);
+    return standard === undefined
+        ? data
+        : `data:${mimeType.toLowerCase()};base64,${standard}`;
+}
 function partsToImages(parts) {
     if (!Array.isArray(parts)) {
         return [];
     }
     return parts
-        .map((p) => p?.inlineData?.data)
-        .filter((d) => typeof d === "string" && d.length > 0);
+        .map((p) => inlineDataToImage(p?.inlineData))
+        .filter((d) => d !== undefined);
 }
 /**
  * Parse a `generateContent` body into the shape the translation engine takes.

package/dist/proxy/proxyImageInput.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Client image references on the proxy's translation routes, vetted before the
+ * SDK sees them.
+ *
+ * The OpenAI, Gemini and (once a model is routed or falls back to another
+ * provider) Claude routes copy whatever a client put in an image slot into
+ * `input.images`, and the SDK resolves a string itself: an `http(s)` URL is
+ * fetched with redirects followed and no address check, and anything else that
+ * names an existing file is read from the local disk. Both suit a program that
+ * names its own files. Neither suits a request that arrived over a socket.
+ *
+ * So the proxy resolves every reference itself and hands the SDK nothing but
+ * `data:` URIs and downloaded bytes:
+ *   - `data:` URIs pass through untouched, they carry their own content;
+ *   - `https://` URLs are downloaded with the same helper the agent routes use
+ *     (`resolveAgentInput` -> `safeDownload`): redirects refused, addresses
+ *     checked, size capped;
+ *   - everything else (local paths, `http://`, `file://`, any other scheme) is
+ *     refused before the file system or the network is touched, so the answer
+ *     for a path that exists and one that does not is the same.
+ *
+ * Unlike the agent routes there is no allowed-roots setting: the proxy listens
+ * on loopback without credentials by default, and a path allow-list on a server
+ * with no caller identity would still hand its owner's disk to every local
+ * process, and to every holder of a share token. Local paths are refused
+ * outright.
+ *
+ * Count and size are bounded as the agent routes bound them: at most 20 images,
+ * each at most 50 MB, all together at most 100 MB, with a `data:` URI charged
+ * its string length.
+ *
+ * The refusal is a {@link ProxyContextPreflightError}, so every site that
+ * already answers a local admission refusal (400, no retry, no fallback) answers
+ * this one in the client's own error format.
+ *
+ * @module proxy/proxyImageInput
+ */
+import { ProxyContextPreflightError } from "./proxyContextPreflight.js";
+/** An image reference the proxy refuses; answers 400 in the client's format. */
+export declare class ProxyImageInputError extends ProxyContextPreflightError {
+    constructor(code: string, message: string);
+}
+/**
+ * Resolve one list of client image references to what the SDK may be given.
+ *
+ * `signal` cancels the work: a download in flight is aborted and no further
+ * reference is started. A cancellation rejects with the signal's own error, not
+ * with a {@link ProxyImageInputError}, since nothing was refused.
+ *
+ * @throws {ProxyImageInputError} for the first reference that is refused, or
+ *   for a list that carries too many images or too many bytes.
+ */
+export declare function vetProxyImages(images: readonly unknown[], signal?: AbortSignal): Promise<Array<string | Buffer>>;
+/**
+ * Per-request holder of vetted images.
+ *
+ * A translated request can make several attempts, each handing the SDK the same
+ * references, so each reference is resolved once and looked up by its text
+ * afterwards. `apply` fails closed: a list that carries a reference `vet` has
+ * not seen is refused, never forwarded.
+ */
+export declare function createProxyImageVetter(): {
+    /**
+     * Vet the images `body` would hand the SDK that no earlier call vetted.
+     * `signal` cancels downloads still running; see {@link vetProxyImages}.
+     */
+    vet(body: object, signal?: AbortSignal): Promise<void>;
+    /** `body` with its `input.images` replaced by the vetted content. */
+    apply<T extends object>(body: T): T;
+};

package/dist/proxy/proxyImageInput.js

@@ -0,0 +1,168 @@
+/**
+ * Client image references on the proxy's translation routes, vetted before the
+ * SDK sees them.
+ *
+ * The OpenAI, Gemini and (once a model is routed or falls back to another
+ * provider) Claude routes copy whatever a client put in an image slot into
+ * `input.images`, and the SDK resolves a string itself: an `http(s)` URL is
+ * fetched with redirects followed and no address check, and anything else that
+ * names an existing file is read from the local disk. Both suit a program that
+ * names its own files. Neither suits a request that arrived over a socket.
+ *
+ * So the proxy resolves every reference itself and hands the SDK nothing but
+ * `data:` URIs and downloaded bytes:
+ *   - `data:` URIs pass through untouched, they carry their own content;
+ *   - `https://` URLs are downloaded with the same helper the agent routes use
+ *     (`resolveAgentInput` -> `safeDownload`): redirects refused, addresses
+ *     checked, size capped;
+ *   - everything else (local paths, `http://`, `file://`, any other scheme) is
+ *     refused before the file system or the network is touched, so the answer
+ *     for a path that exists and one that does not is the same.
+ *
+ * Unlike the agent routes there is no allowed-roots setting: the proxy listens
+ * on loopback without credentials by default, and a path allow-list on a server
+ * with no caller identity would still hand its owner's disk to every local
+ * process, and to every holder of a share token. Local paths are refused
+ * outright.
+ *
+ * Count and size are bounded as the agent routes bound them: at most 20 images,
+ * each at most 50 MB, all together at most 100 MB, with a `data:` URI charged
+ * its string length.
+ *
+ * The refusal is a {@link ProxyContextPreflightError}, so every site that
+ * already answers a local admission refusal (400, no retry, no fallback) answers
+ * this one in the client's own error format.
+ *
+ * @module proxy/proxyImageInput
+ */
+import { AgentInputError, resolveAgentInput, } from "../server/utils/agentInput.js";
+import { logger } from "../utils/logger.js";
+import { ProxyContextPreflightError } from "./proxyContextPreflight.js";
+const INVALID_REFERENCE_MESSAGE = "Image references must be data: URIs or public https URLs. Local file paths, http URLs and other schemes are not accepted by this proxy.";
+const UNFETCHABLE_URL_MESSAGE = "An image URL could not be fetched. It must be a public https URL, answer without a redirect and fit the size limit.";
+/** An image reference the proxy refuses; answers 400 in the client's format. */
+export class ProxyImageInputError extends ProxyContextPreflightError {
+    constructor(code, message) {
+        super(code, message);
+        this.name = "ProxyImageInputError";
+    }
+}
+const isDataUri = (entry) => entry.startsWith("data:");
+const isHttpsUrl = (entry) => /^https:\/\//i.test(entry);
+/**
+ * What kind of reference was refused, for the operator's log. The reference
+ * itself is never logged: it can be a server path, or a URL with credentials.
+ */
+function describeRefusal(entry) {
+    if (typeof entry !== "string") {
+        return "non-string";
+    }
+    if (/^https?:\/\//i.test(entry)) {
+        return "http-url";
+    }
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]+:/.test(entry)) {
+        return "other-scheme";
+    }
+    return "path";
+}
+function refuseReference(entry) {
+    logger.warn("[proxy] refused a client image reference", {
+        kind: describeRefusal(entry),
+    });
+    return new ProxyImageInputError("invalid_image_reference", INVALID_REFERENCE_MESSAGE);
+}
+function asProxyImageInputError(error) {
+    if (!(error instanceof AgentInputError)) {
+        return error;
+    }
+    // agentInput's messages name a limit, never the input, so the size and count
+    // refusals pass through. Its download refusal is already logged there.
+    if (error.status === 413) {
+        return new ProxyImageInputError("image_input_too_large", error.message);
+    }
+    return new ProxyImageInputError("image_url_unfetchable", UNFETCHABLE_URL_MESSAGE);
+}
+/**
+ * Resolve one list of client image references to what the SDK may be given.
+ *
+ * `signal` cancels the work: a download in flight is aborted and no further
+ * reference is started. A cancellation rejects with the signal's own error, not
+ * with a {@link ProxyImageInputError}, since nothing was refused.
+ *
+ * @throws {ProxyImageInputError} for the first reference that is refused, or
+ *   for a list that carries too many images or too many bytes.
+ */
+export async function vetProxyImages(images, signal) {
+    const references = [];
+    for (const entry of images) {
+        if (typeof entry !== "string" || !(isDataUri(entry) || isHttpsUrl(entry))) {
+            throw refuseReference(entry);
+        }
+        references.push(entry);
+    }
+    try {
+        const resolved = await resolveAgentInput({ text: "", images: references }, { signal });
+        return resolved.images ?? [];
+    }
+    catch (error) {
+        throw asProxyImageInputError(error);
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The `input.images` list of an SDK options object, when it has one. */
+function imagesOf(body) {
+    const input = Reflect.get(body, "input");
+    return isRecord(input) && Array.isArray(input.images)
+        ? input.images
+        : undefined;
+}
+/**
+ * Per-request holder of vetted images.
+ *
+ * A translated request can make several attempts, each handing the SDK the same
+ * references, so each reference is resolved once and looked up by its text
+ * afterwards. `apply` fails closed: a list that carries a reference `vet` has
+ * not seen is refused, never forwarded.
+ */
+export function createProxyImageVetter() {
+    const resolved = new Map();
+    return {
+        /**
+         * Vet the images `body` would hand the SDK that no earlier call vetted.
+         * `signal` cancels downloads still running; see {@link vetProxyImages}.
+         */
+        async vet(body, signal) {
+            const pending = (imagesOf(body) ?? []).filter((entry) => typeof entry !== "string" || !resolved.has(entry));
+            if (pending.length === 0) {
+                return;
+            }
+            const vetted = await vetProxyImages(pending, signal);
+            pending.forEach((entry, index) => {
+                if (typeof entry === "string") {
+                    resolved.set(entry, vetted[index]);
+                }
+            });
+        },
+        /** `body` with its `input.images` replaced by the vetted content. */
+        apply(body) {
+            const input = Reflect.get(body, "input");
+            const images = imagesOf(body);
+            if (!isRecord(input) || images === undefined) {
+                return body;
+            }
+            return {
+                ...body,
+                input: {
+                    ...input,
+                    images: images.map((entry) => {
+                        const vetted = typeof entry === "string" ? resolved.get(entry) : undefined;
+                        if (vetted === undefined) {
+                            throw refuseReference(entry);
+                        }
+                        return vetted;
+                    }),
+                },
+            };
+        },
+    };
+}

package/dist/proxy/proxyTranslationEngine.js

@@ -18,6 +18,7 @@ import { prepareProxyRequestContext, ProxyContextPreflightError, } from "./proxy
 import { reserveProxyTokenBudget, settleProxyTokenBudget, getProxyTokenBudgetPolicy, getProxyTokenBudgetSessionKey, getProxyTokenBudgetError, } from "./proxyTokenBudget.js";
 import { isProxyRequestFinalized, getProxyRequestAccounting, registerProxyResponseObserver, } from "./proxyActivity.js";
 import { getProxyUpstreamFailure } from "./proxyFailureDetails.js";
+import { createProxyImageVetter } from "./proxyImageInput.js";
 import { sanitizeForLog } from "../utils/logSanitize.js";
 import { createProxyRouteBodyCapture } from "./proxyRouteBodyCapture.js";
 import { DEFAULT_PROXY_MODEL_IDS } from "../constants/proxyModels.js";
@@ -290,6 +291,10 @@ function createTranslationRequest(args) {
     let budgetLease;
     let budgetSettlement;
     let terminalWork;
+    // The SDK reads a local path or fetches an http(s) URL named in an image slot,
+    // so a client's references are resolved here, once per request, and the SDK is
+    // handed only what this vetted.
+    const imageVetter = createProxyImageVetter();
     let attempt;
     let iterator;
     let firstUsefulOutputMs;
@@ -431,6 +436,10 @@ function createTranslationRequest(args) {
             cleanupIterator();
         },
         stream,
+        // The race is kept so an abort still rejects at once, as it did before the
+        // vetter could be cancelled; the signal is what stops the download itself.
+        vetImages: (body, abort) => raceWithAbort(imageVetter.vet(body, abort), abort),
+        withVettedImages: (body) => imageVetter.apply(body),
         cancel(reason) {
             controller.abort(reason);
         },
@@ -499,6 +508,7 @@ async function* runTranslationAttempts(args) {
                 ...args.options,
                 abortSignal: signal,
             };
+            await request.vetImages(options, signal);
             const prepared = prepareProxyRequestContext({
                 provider: attempt.provider ?? "auto",
                 model: attempt.model ?? parsed.model,
@@ -572,7 +582,7 @@ async function* runTranslationAttempts(args) {
                 },
             });
             recordAttempt(attempt.label ?? "translation", "translation");
-            const result = await raceWithAbort(ctx.neurolink.stream(prepared.body), signal);
+            const result = await raceWithAbort(ctx.neurolink.stream(request.withVettedImages(prepared.body)), signal);
             request.setResult(result);
             const iterator = result.stream[Symbol.asyncIterator]();
             request.setIterator(iterator);

package/dist/server/routes/claudeProxyRoutes.js

@@ -45,6 +45,7 @@ import { evaluateResidentAccount, getResidentGrantForAccount, recordResidentSpen
 import { buildProvisionClaim, isLeaseRefusal, issueLease, } from "../../proxy/shareLease.js";
 import { forwardToPeer } from "../../proxy/peerTransport.js";
 import { getShareContext } from "../../proxy/shareContext.js";
+import { ProxyImageInputError } from "../../proxy/proxyImageInput.js";
 import { buildShareRefusal, extractShareToken } from "../../proxy/shareGate.js";
 import { debitShareGrantCoins, getNodePublicUrl, getNoteSecret, getShareGrant, resolveShareToken, setShareGrantState, } from "../../proxy/shareGrants.js";
 import { recordAuditObservation } from "../../proxy/shareAudit.js";
@@ -8022,7 +8023,12 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                                 error.evidence) {
                                 ctx.metadata.contextPreflight = error.evidence;
                             }
-                            const refusal = buildLoggedClaudeError(localRefusal.status, localRefusal.message, localRefusal.code, { errorCode: localRefusal.code, retryable: false });
+                            const refusal = buildLoggedClaudeError(localRefusal.status, localRefusal.message, 
+                            // A refused image reference is a malformed request in
+                            // Anthropic's vocabulary; its code stays in `error.code`.
+                            error instanceof ProxyImageInputError
+                                ? "invalid_request_error"
+                                : localRefusal.code, { errorCode: localRefusal.code, retryable: false });
                             return new Response(JSON.stringify({
                                 ...refusal,
                                 error: {

package/dist/server/utils/agentInput.d.ts

@@ -33,7 +33,7 @@
  *
  * @module server/utils/agentInput
  */
-import type { ServerAgentResolvedInput, ServerAgentRouteOptions } from "../../types/index.js";
+import type { ServerAgentResolvedInput, ServerAgentResolveOptions } from "../../types/index.js";
 /** An attachment the server refuses, with the HTTP status that says why. */
 export declare class AgentInputError extends Error {
     readonly status: number;
@@ -50,4 +50,4 @@ export declare function resolveAgentInput(input: {
     text: string;
     images?: string[];
     files?: string[];
-}, options?: ServerAgentRouteOptions): Promise<ServerAgentResolvedInput>;
+}, options?: ServerAgentResolveOptions): Promise<ServerAgentResolvedInput>;

package/dist/server/utils/agentInput.js

@@ -201,7 +201,7 @@ async function readWithinLimit(handle, limit) {
     }
     return Buffer.concat(chunks, total);
 }
-async function downloadAttachment(url, limit) {
+async function downloadAttachment(url, limit, signal) {
     // Dynamic import keeps undici off the static import graph; see
     // test/continuous-test-suite-import-cost.ts.
     const { safeDownload } = await import("../../utils/safeFetch.js");
@@ -209,9 +209,15 @@ async function downloadAttachment(url, limit) {
         return await safeDownload(url, {
             maxBytes: limit,
             label: "agent attachment",
+            signal,
         });
     }
     catch (error) {
+        // A cancelled download is not a refused URL: the caller is gone, and
+        // reporting it as one would put a refusal in the log that never happened.
+        if (signal?.aborted) {
+            throw error;
+        }
         // The reason can name the address a host resolved to; the caller gets none
         // of it, the operator gets it in the log.
         const reason = error instanceof Error ? error.message : String(error);
@@ -222,9 +228,9 @@ async function downloadAttachment(url, limit) {
     }
 }
 /** The bytes of one attachment that is not a `data:` URI, read within `limit`. */
-async function resolveAttachment(entry, roots, limit) {
+async function resolveAttachment(entry, roots, limit, signal) {
     if (/^https?:\/\//i.test(entry)) {
-        return downloadAttachment(entry, limit);
+        return downloadAttachment(entry, limit, signal);
     }
     if (URL_SCHEME.test(entry)) {
         throw new AgentInputError("attachment must be a data: URI, an https URL, or a path under an allowed directory", 400, "VALIDATION_ERROR");
@@ -270,6 +276,8 @@ export async function resolveAgentInput(input, options) {
         }
         const resolved = [];
         for (const entry of list) {
+            // A caller that has gone away starts nothing further.
+            options?.signal?.throwIfAborted();
             // Exactly the prefix the SDK keys on, so nothing that reaches it as a
             // string is anything but a data URI.
             if (isDataUri(entry)) {
@@ -279,7 +287,7 @@ export async function resolveAgentInput(input, options) {
             const limit = Math.min(perAttachment, remaining);
             let bytes;
             try {
-                bytes = await resolveAttachment(entry, roots, limit);
+                bytes = await resolveAttachment(entry, roots, limit, options?.signal);
             }
             catch (error) {
                 if (limit < perAttachment &&

package/dist/types/proxy.d.ts

@@ -3598,6 +3598,7 @@ export type OpenAIErrorResponse = {
 export type ProxyGeminiPart = {
     text?: string;
     inlineData?: {
+        mimeType?: string;
         data?: string;
     };
 };

package/dist/types/server.d.ts

@@ -463,6 +463,19 @@ export type ServerAgentRouteOptions = {
      */
     maxInputTotalBytes?: number;
 };
+/**
+ * The route options plus the one thing that belongs to a single call:
+ * `resolveAgentInput` options. A signal is not route configuration, so it is
+ * kept off {@link ServerAgentRouteOptions}, where `createAgentRoutes` would
+ * apply it to every request.
+ */
+export type ServerAgentResolveOptions = ServerAgentRouteOptions & {
+    /**
+     * Cancels the resolution: an `https` download in flight is aborted and no
+     * further attachment is started. Omitted, nothing can cancel it.
+     */
+    signal?: AbortSignal;
+};
 /**
  * An agent request's `input` once every attachment has been vetted: URLs and
  * allowed local paths are replaced by the bytes the server read itself, `data:`

package/dist/voice/livekit/config.d.ts

@@ -24,14 +24,12 @@ export declare function resolveLiveKitServerConfig(): LiveKitServerConfig;
  */
 export declare function resolveBrainDefaults(): LiveKitBrainDefaults;
 /**
- * Refuse a `ws://` URL to a host other than loopback unless
- * `XAI_REALTIME_ALLOW_INSECURE=true`: the xAI plugin sends `XAI_API_KEY` to the
- * URL it is given, and `ws://` sends it unencrypted. Anything else passes,
- * including a value that is not a ws or wss URL, which is for the caller's own
- * check. The error names the setting and the opt-in and does not repeat the
- * value.
+ * A ws or wss URL that passes `requireNoCleartextCrossHost`. The error names the
+ * setting and does not repeat the value. Exported so the model factory applies
+ * the same check to a hand-built config as config resolution applies to the
+ * variable and to a caller's override.
  */
-export declare function requireNoCleartextCrossHost(value: string, name: string): void;
+export declare function requireWebSocketUrl(value: string, name: string): string;
 /**
  * Resolve the realtime (speech-to-speech) voice configuration from the
  * environment.

package/dist/voice/livekit/config.js

@@ -134,7 +134,7 @@ function isLoopbackHost(hostname) {
  * check. The error names the setting and the opt-in and does not repeat the
  * value.
  */
-export function requireNoCleartextCrossHost(value, name) {
+function requireNoCleartextCrossHost(value, name) {
     const url = parseWebSocketUrl(value);
     if (url?.protocol === "ws:" &&
         !isLoopbackHost(url.hostname) &&
@@ -142,8 +142,13 @@ export function requireNoCleartextCrossHost(value, name) {
         throw new Error(`${name} is a ws:// URL to a host other than localhost, 127.0.0.0/8 or [::1], which would send XAI_API_KEY unencrypted. Use wss://, or set ${ALLOW_INSECURE_ENV}=true to accept that`);
     }
 }
-/** A ws or wss URL that passes `requireNoCleartextCrossHost`. The error names the setting and does not repeat the value. */
-function requireWebSocketUrl(value, name) {
+/**
+ * A ws or wss URL that passes `requireNoCleartextCrossHost`. The error names the
+ * setting and does not repeat the value. Exported so the model factory applies
+ * the same check to a hand-built config as config resolution applies to the
+ * variable and to a caller's override.
+ */
+export function requireWebSocketUrl(value, name) {
     if (parseWebSocketUrl(value) === undefined) {
         throw new Error(`${name} must be a ws:// or wss:// URL`);
     }

package/dist/voice/livekit/realtimeModel.d.ts

@@ -28,8 +28,11 @@ export declare function requireXaiApiKey(): void;
  * The gemini branch builds exactly what the agent has always built: Vertex AI,
  * the configured model, transcripts of both sides, and project, location,
  * voice and modality when set. The xai branch needs `XAI_API_KEY` in the
- * environment and throws before touching the plugin when it is missing. It also
- * throws before touching the plugin for a `ws://` base URL to a host other than
- * loopback, unless `XAI_REALTIME_ALLOW_INSECURE=true`, as config resolution does.
+ * environment and throws before touching the plugin when it is missing. It then
+ * checks `xaiBaseURL` as config resolution does, and throws before touching the
+ * plugin for a value that is not a `ws://` or `wss://` URL, and for a `ws://`
+ * URL to a host other than localhost, 127.0.0.0/8 or [::1] unless
+ * `XAI_REALTIME_ALLOW_INSECURE=true`. That opt-in never admits a value that is
+ * not a ws or wss URL. The errors name `xaiBaseURL` and do not repeat the value.
  */
 export declare function createRealtimeLlm(cfg: RealtimeVoiceConfig): Promise<RealtimeLlm>;

package/dist/voice/livekit/realtimeModel.js

@@ -13,7 +13,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
-import { requireNoCleartextCrossHost } from "./config.js";
+import { requireWebSocketUrl } from "./config.js";
 /**
  * Fail early, naming the variable, when `XAI_API_KEY` is blank or absent.
  *
@@ -55,9 +55,11 @@ async function createGeminiRealtimeLlm(cfg) {
 async function createXaiRealtimeLlm(cfg) {
     requireXaiApiKey();
     // `cfg` can be built by hand, without `resolveRealtimeVoiceConfig`, so the
-    // key-leak check runs here as well as there.
+    // whole base URL check runs here as well as there: the ws or wss shape, and
+    // the cross-host rule that keeps XAI_API_KEY off an unencrypted link. The
+    // cross-host rule alone lets an http(s) or unparseable value reach the plugin.
     if (cfg.xaiBaseURL) {
-        requireNoCleartextCrossHost(cfg.xaiBaseURL, "xaiBaseURL");
+        requireWebSocketUrl(cfg.xaiBaseURL, "xaiBaseURL");
     }
     const xai = await import("@livekit/agents-plugin-xai");
     // Keys are added only when set. The plugin spreads these options over its
@@ -81,9 +83,12 @@ async function createXaiRealtimeLlm(cfg) {
  * The gemini branch builds exactly what the agent has always built: Vertex AI,
  * the configured model, transcripts of both sides, and project, location,
  * voice and modality when set. The xai branch needs `XAI_API_KEY` in the
- * environment and throws before touching the plugin when it is missing. It also
- * throws before touching the plugin for a `ws://` base URL to a host other than
- * loopback, unless `XAI_REALTIME_ALLOW_INSECURE=true`, as config resolution does.
+ * environment and throws before touching the plugin when it is missing. It then
+ * checks `xaiBaseURL` as config resolution does, and throws before touching the
+ * plugin for a value that is not a `ws://` or `wss://` URL, and for a `ws://`
+ * URL to a host other than localhost, 127.0.0.0/8 or [::1] unless
+ * `XAI_REALTIME_ALLOW_INSECURE=true`. That opt-in never admits a value that is
+ * not a ws or wss URL. The errors name `xaiBaseURL` and do not repeat the value.
  */
 export async function createRealtimeLlm(cfg) {
     switch (cfg.backend) {