@juspay/neurolink 13.6.1 → 13.6.3

package/dist/providers/catalog/provider-catalog.schema.json

@@ -311,7 +311,13 @@
                     "description": "The rule also needs the error message to match this case-insensitive regular expression (first 2,000 characters, key removed). Bounded: outside a character class no unescaped *, + or {n,}, no quantifier on a group, no count above 255, and the counts side by side multiply to at most 4,096 ways (each ? is 2, each {n,m} is m-n+1)."
                   },
                   "kind": { "$ref": "#/definitions/decisionErrorKind" },
-                  "retryable": { "type": "boolean" }
+                  "retryable": { "type": "boolean" },
+                  "hint": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 300,
+                    "description": "Text added after the error message, behind a dash, when this rule matches. For a status the vendor uses for more than one cause. {apiKeyEnvVar} is the only placeholder."
+                  }
                 }
               }
             },

package/dist/providers/catalog/scaledown.json

@@ -24,6 +24,7 @@
             }
         }
     },
+    "timeouts": { "decideMs": 30000 },
     "decide": {
         "dialect": "system-one",
         "order": 8,
@@ -35,14 +36,27 @@
         "errors": {
             "rules": [
                 { "status": 401, "kind": "authentication" },
-                { "status": [402, 422], "kind": "invalid_request" },
+                {
+                    "status": 402,
+                    "kind": "invalid_request",
+                    "hint": "ScaleDown answers HTTP 402 both when the account has no credit left and when it does not recognise the API key; check {apiKeyEnvVar} first."
+                },
+                { "status": 422, "kind": "invalid_request" },
                 { "status": 429, "kind": "rate_limit" },
                 { "status": 502, "kind": "server" },
                 { "status": 504, "kind": "timeout" },
                 { "statusMin": 500, "kind": "server" }
             ],
             "default": "invalid_request",
-            "bodyShapes": [{ "path": "detail.message" }, { "path": "detail" }]
+            "bodyShapes": [
+                { "path": "detail.message" },
+                { "path": "detail" },
+                {
+                    "path": "detail",
+                    "isArray": true,
+                    "formatter": "fastapi-validation"
+                }
+            ]
         }
     },
     "setup": {
@@ -54,7 +68,7 @@
             "1. Create an account and an API key, following https://docs.scaledown.ai",
             "2. Set {apiKeyEnvVar} in your .env file",
             "3. ScaleDown's documentation says the key goes in an x-api-key header rather than Authorization: Bearer, and NeuroLink sends it that way",
-            "4. ScaleDown's documentation says a request made with no credit left returns HTTP 402"
+            "4. ScaleDown's documentation says a request made with no credit left returns HTTP 402; a live test on 2026-10-20 saw it return 402 for an unrecognised key as well, so check {apiKeyEnvVar} before adding credit"
         ]
     },
     "evidence": {

package/dist/providers/catalog/schema.js

@@ -482,6 +482,13 @@ const decideMessagePatternSchema = z
     .refine((pattern) => !hasRiskyQuantifier(pattern), {
     message: "messagePattern must be bounded: an unescaped * or +, an open-ended {n,}, a {n,m} count above 255, or any quantifier on a group, outside a character class, can backtrack catastrophically on an error message. Put ?, or {n,m} up to 255, only on a plain character, a character class or an escape, and keep the counts side by side to 4096 ways in all (each ? is 2, each {n,m} is m-n+1)",
 });
+const decideErrorHintSchema = z
+    .string()
+    .min(1)
+    .max(300)
+    .refine((hint) => !/[{}]/.test(hint.split("{apiKeyEnvVar}").join("")), {
+    message: "hint may only use the {apiKeyEnvVar} placeholder",
+});
 const decideErrorRuleSchema = z.strictObject({
     status: z
         .union([decideStatusSchema, z.array(decideStatusSchema).min(1)])
@@ -490,6 +497,7 @@ const decideErrorRuleSchema = z.strictObject({
     messagePattern: decideMessagePatternSchema.optional(),
     kind: decideErrorKindSchema,
     retryable: z.boolean().optional(),
+    hint: decideErrorHintSchema.optional(),
 });
 const UNSAFE_PATH_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
 const HTTP_TOKEN_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;

package/dist/providers/configuredDecision.js

@@ -136,6 +136,7 @@ export class ConfiguredDecisionProvider extends SystemOneDecisionProvider {
             requestId,
             label: this.entry.displayName,
             apiKey: this.apiKey,
+            apiKeyEnvVar: catalogEnvVar(this.entry, "apiKey"),
         });
     }
     readRequestId(headers) {

package/dist/providers/decide/errors.d.ts

@@ -5,4 +5,5 @@ export declare function classifyDecisionError(spec: DecideErrors, input: {
     requestId: string | undefined;
     label: string;
     apiKey: string;
+    apiKeyEnvVar?: string;
 }): DecisionError;

package/dist/providers/decide/errors.js

@@ -52,7 +52,7 @@ function firstShapeText(shapes, payload) {
     return undefined;
 }
 export function classifyDecisionError(spec, input) {
-    const { status, payload, requestId, label, apiKey } = input;
+    const { status, payload, requestId, label, apiKey, apiKeyEnvVar } = input;
     // Redacted once, here: it stands in for a shape's text that redaction
     // empties, and the label is catalog data a key can match. Redaction is not
     // idempotent for a key such as "e" (it matches inside "[redacted]"), so the
@@ -65,9 +65,16 @@ export function classifyDecisionError(spec, input) {
     const rule = spec.rules.find((candidate) => ruleMatches(candidate, status, message));
     const ruleKind = rule?.kind ?? spec.default;
     const ruleRetryable = rule?.retryable ?? isRetryableByDefault(ruleKind);
+    // Added after the rule is chosen, so a pattern never has to allow for it,
+    // and redacted on its own, once, for the same reason as the fallback above.
+    const hinted = rule?.hint
+        ? `${message} — ${redactCredentials(rule.hint
+            .split("{apiKeyEnvVar}")
+            .join(apiKeyEnvVar ?? "the API key variable"), apiKey)}`
+        : message;
     const build = (kind, retryable) => ({
         kind,
-        message,
+        message: hinted,
         status,
         requestId,
         retryable,

package/dist/types/generate.d.ts

@@ -1838,7 +1838,12 @@ export type NativeGenerateLoopArgs = {
     conversation: Array<Record<string, unknown>>;
     /** Tool declarations in the v3 shape doGenerate already knows how to convert. */
     tools?: Array<Record<string, unknown>>;
-    /** Registered tools, used to execute a call the model asks for. */
+    /**
+     * Registered tools, used to execute a call the model asks for. Typed
+     * `Record<string, Tool>`; it was `Record<string, unknown>` before discovery
+     * learned to declare tools that join it mid-turn, so a caller that builds
+     * this record from loosely typed tools now needs a cast to `Tool`.
+     */
     toolsRecord: Record<string, Tool>;
     /**
      * Builds the v3 declaration for one tool. When set, every step declares any

package/dist/types/livekit.d.ts

@@ -9,6 +9,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
+import type { EventEmitter } from "node:events";
 import type { NeuroLinkEvents, TypedEventEmitter } from "./common.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
 import type { ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, StreamEventSequence } from "./conversation.js";
@@ -437,6 +438,24 @@ export type RealtimeLlm = {
     label: () => string;
     close: () => Promise<void>;
 };
+/**
+ * A session of the xAI plugin as far as the xai model's watcher needs it: an
+ * event emitter (the plugin republishes every server event as
+ * `openai_server_event_received`) that can be closed.
+ */
+export type XaiObservedSession = EventEmitter & {
+    close: () => Promise<void>;
+};
+/**
+ * Token counts of one xAI response. xAI sends them at the top level of
+ * `response.done`; the plugin reads `response.usage`, which xAI leaves empty.
+ */
+export type XaiResponseUsage = {
+    inputTokens: number;
+    inputAudioTokens: number;
+    outputTokens: number;
+    outputAudioTokens: number;
+};
 /**
  * Realtime voice configuration resolved from the environment.
  *

package/dist/types/providerCatalog.d.ts

@@ -290,6 +290,14 @@ export type DecideErrorRule = {
     messagePattern?: string;
     kind: DecisionErrorKind;
     retryable?: boolean;
+    /**
+     * Text added after the error message, behind a dash, when this rule is the
+     * one that matches. For a status the vendor uses for more than one cause,
+     * where the body's own words name only one of them. `{apiKeyEnvVar}` is the
+     * only placeholder. A `messagePattern` is judged on the message without it,
+     * and the key is removed from it as from the message.
+     */
+    hint?: string;
 };
 export type DecideBodyShape = {
     /** Dot path into the parsed error body. */

package/dist/voice/livekit/config.js

@@ -68,8 +68,9 @@ export function resolveBrainDefaults() {
     };
 }
 const DEFAULT_REALTIME_MODEL = "gemini-live-2.5-flash";
-// xAI's documented flagship Grok Voice id. Never exercised against the real
-// service; the plugin's own default is `grok-voice-think-fast-1.0`.
+// xAI's documented flagship Grok Voice id, accepted and honoured by the live
+// service (2026-10-20). The plugin's own default, `grok-voice-think-fast-1.0`,
+// ran as `grok-voice-3.0` there.
 const DEFAULT_XAI_REALTIME_MODEL = "grok-voice-3.0";
 const DEFAULT_REALTIME_LOCATION = "global";
 const DEFAULT_RESPONSE_MODALITY = "AUDIO";

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

@@ -8,8 +8,8 @@
  * `@google/genai` are imported dynamically so the core package does not require
  * them unless the realtime agent is used.
  *
- * The xai backend has only been exercised against a stub WebSocket server. It
- * has never talked to the real xAI service.
+ * The xai backend was run against the real xAI service on 2026-10-20; what that
+ * showed, and what is still unmeasured, is in the document below.
  *
  * See docs/features/livekit-voice-agent.md.
  */

package/dist/voice/livekit/realtimeModel.js

@@ -8,12 +8,13 @@
  * `@google/genai` are imported dynamically so the core package does not require
  * them unless the realtime agent is used.
  *
- * The xai backend has only been exercised against a stub WebSocket server. It
- * has never talked to the real xAI service.
+ * The xai backend was run against the real xAI service on 2026-10-20; what that
+ * showed, and what is still unmeasured, is in the document below.
  *
  * See docs/features/livekit-voice-agent.md.
  */
 import { requireWebSocketUrl } from "./config.js";
+import { observeXaiSession } from "./xaiSessionWatch.js";
 /**
  * Fail early, naming the variable, when `XAI_API_KEY` is blank or absent.
  *
@@ -66,16 +67,34 @@ async function createXaiRealtimeLlm(cfg) {
     // own defaults, so a key holding `undefined` would erase the default: a
     // missing `baseURL` would send the xAI key to OPENAI_BASE_URL or
     // api.openai.com, and no `apiKey` option is passed at all because the plugin
-    // reads XAI_API_KEY itself. The plugin forwards `baseURL` although its
-    // declared option type leaves it out.
-    const modelOptions = { model: cfg.model };
+    // reads XAI_API_KEY itself. The plugin forwards `baseURL` and
+    // `inputAudioTranscription` although its declared option type leaves them out.
+    //
+    // `inputAudioTranscription` is the one key set to `undefined` on purpose, to
+    // erase the plugin's OpenAI default of `gpt-4o-mini-transcribe`. With it xAI
+    // answered one spoken utterance with five "completed" transcripts, which the
+    // turn recorder stored as one user message with the utterance repeated;
+    // without it xAI sends one. `undefined`, unlike `null`, keeps the plugin's
+    // user-transcription capability on, and JSON.stringify leaves the key out of
+    // the `session.update` it sends.
+    const modelOptions = {
+        model: cfg.model,
+        inputAudioTranscription: undefined,
+    };
     if (cfg.voice) {
         modelOptions.voice = cfg.voice;
     }
     if (cfg.xaiBaseURL) {
         modelOptions.baseURL = cfg.xaiBaseURL;
     }
-    return new xai.realtime.RealtimeModel(modelOptions);
+    class ObservedXaiRealtimeModel extends xai.realtime.RealtimeModel {
+        session() {
+            const session = super.session();
+            observeXaiSession(session, cfg.model);
+            return session;
+        }
+    }
+    return new ObservedXaiRealtimeModel(modelOptions);
 }
 /**
  * Build the realtime model for `cfg.backend`.

package/dist/voice/livekit/realtimeVoiceAgent.js

@@ -343,7 +343,9 @@ export function defineRealtimeVoiceAgent(config = {}) {
         };
         session.on(voice.AgentSessionEventTypes.MetricsCollected, (ev) => {
             const metrics = ev.metrics;
-            if (metrics.type !== "realtime_model_metrics") {
+            // xAI leaves `response.usage` empty, which is where the plugin reads, so
+            // its metrics are zero; the xai model logs `realtime.usage` itself.
+            if (!isGemini || metrics.type !== "realtime_model_metrics") {
                 return;
             }
             const inAudio = metrics.inputTokenDetails.audioTokens;

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

@@ -0,0 +1,26 @@
+/**
+ * What this package adds around an xAI realtime session.
+ *
+ * The LiveKit xAI plugin is the OpenAI realtime plugin pointed at xAI, and the
+ * live service differs from OpenAI in three ways the plugin does not cover
+ * (measured 2026-10-20, see docs/features/livekit-voice-agent.md):
+ *
+ *  - xAI sends usage at the top level of `response.done` and leaves
+ *    `response.usage` an empty object, which is what the plugin reads, so its
+ *    metrics are zero for every response;
+ *  - an unknown model id is accepted and runs a default model, with no error;
+ *  - a wrong key is refused with HTTP 400 at the WebSocket upgrade, and the
+ *    plugin opens its socket without an 'error' listener, so the refusal is an
+ *    uncaught exception.
+ *
+ * `observeXaiSession` reads the stream of server events the plugin republishes
+ * as `openai_server_event_received` for the first two, and watches for the
+ * third.
+ */
+import type { XaiObservedSession } from "../../types/index.js";
+/**
+ * Log the usage of every response, warn when the service runs another model
+ * than the one asked for, and report a refused upgrade as a session error.
+ * `requestedModel` is the id the session was configured with.
+ */
+export declare function observeXaiSession(session: XaiObservedSession, requestedModel: string): void;

package/dist/voice/livekit/xaiSessionWatch.js

@@ -0,0 +1,157 @@
+/**
+ * What this package adds around an xAI realtime session.
+ *
+ * The LiveKit xAI plugin is the OpenAI realtime plugin pointed at xAI, and the
+ * live service differs from OpenAI in three ways the plugin does not cover
+ * (measured 2026-10-20, see docs/features/livekit-voice-agent.md):
+ *
+ *  - xAI sends usage at the top level of `response.done` and leaves
+ *    `response.usage` an empty object, which is what the plugin reads, so its
+ *    metrics are zero for every response;
+ *  - an unknown model id is accepted and runs a default model, with no error;
+ *  - a wrong key is refused with HTTP 400 at the WebSocket upgrade, and the
+ *    plugin opens its socket without an 'error' listener, so the refusal is an
+ *    uncaught exception.
+ *
+ * `observeXaiSession` reads the stream of server events the plugin republishes
+ * as `openai_server_event_received` for the first two, and watches for the
+ * third.
+ */
+import { logger } from "../../utils/logger.js";
+const TOKEN_COUNT_KEYS = ["input_tokens", "output_tokens"];
+const REFUSED_UPGRADE = /^Unexpected server response: (\d{3})$/;
+const KEY_REFUSAL_STATUSES = new Set([400, 401, 403]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function countOf(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : 0;
+}
+function detailOf(source, group, key) {
+    const details = source[group];
+    return isRecord(details) ? countOf(details, key) : 0;
+}
+/**
+ * The token counts of a `response.done` event, or `undefined` when it reports
+ * none. xAI's own place is the top level of the event; `response.usage`, where
+ * OpenAI puts them, is the fallback, so a service that fills it still works.
+ * A report with seconds but no token count (a cancelled response) is not usage
+ * and would log as zeros.
+ */
+function readXaiResponseUsage(event) {
+    if (!isRecord(event) || event.type !== "response.done") {
+        return undefined;
+    }
+    const nested = isRecord(event.response) ? event.response.usage : undefined;
+    const usage = [event.usage, nested].find((candidate) => isRecord(candidate) &&
+        TOKEN_COUNT_KEYS.some((key) => typeof candidate[key] === "number"));
+    if (usage === undefined) {
+        return undefined;
+    }
+    return {
+        inputTokens: countOf(usage, "input_tokens"),
+        inputAudioTokens: detailOf(usage, "input_token_details", "audio_tokens"),
+        outputTokens: countOf(usage, "output_tokens"),
+        outputAudioTokens: detailOf(usage, "output_token_details", "audio_tokens"),
+    };
+}
+/** The same record the agent logs for the Gemini backend, built from the same three counts. */
+function logUsage(usage) {
+    logger.info("realtime.usage", {
+        inputTokens: usage.inputTokens,
+        inputAudioTokens: usage.inputAudioTokens,
+        inputTextTokens: Math.max(0, usage.inputTokens - usage.inputAudioTokens),
+        outputTokens: usage.outputTokens,
+        outputAudioTokens: usage.outputAudioTokens,
+        outputTextTokens: Math.max(0, usage.outputTokens - usage.outputAudioTokens),
+    });
+}
+function describeRefusal(status) {
+    const keyHint = KEY_REFUSAL_STATUSES.has(status)
+        ? " xAI answers a wrong XAI_API_KEY with HTTP 400, not 401, so check the key first."
+        : "";
+    return `xAI refused the realtime connection with HTTP ${status}.${keyHint}`;
+}
+/**
+ * Turn the plugin's uncaught socket error into the error event the plugin
+ * meant to emit. Returns the function that ends the watch.
+ *
+ * `uncaughtExceptionMonitor` observes a crash without handling it, so the
+ * process still fails exactly as it would have; what changes is that the
+ * session reports a classified, unrecoverable error first, which the agent
+ * entry already logs and publishes. The watch is on only while the connection
+ * is being made, so it cannot take a crash elsewhere in the process for a
+ * refused upgrade once the call is running.
+ *
+ * A crash event carries no socket, so a refusal cannot be tied to one session:
+ * every session still connecting is told. That is accurate, because the crash
+ * ends the process for all of them, and the sessions of one process share
+ * `XAI_API_KEY`, so a refused key is refused for each.
+ */
+function watchForRefusedUpgrade(session) {
+    const onCrash = (error) => {
+        const status = error instanceof Error
+            ? Number(REFUSED_UPGRADE.exec(error.message)?.[1])
+            : Number.NaN;
+        if (Number.isNaN(status)) {
+            return;
+        }
+        stop();
+        const message = describeRefusal(status);
+        logger.error("realtime.xai.connectRefused", { status, error: message });
+        if (session.listenerCount("error") === 0) {
+            return;
+        }
+        try {
+            session.emit("error", {
+                type: "realtime_model_error",
+                timestamp: Date.now(),
+                label: "xai.RealtimeModel",
+                error: new Error(message),
+                recoverable: false,
+            });
+        }
+        catch {
+            /* the process is already failing; a listener's error must not mask it */
+        }
+    };
+    const stop = () => {
+        process.off("uncaughtExceptionMonitor", onCrash);
+    };
+    process.on("uncaughtExceptionMonitor", onCrash);
+    return stop;
+}
+/**
+ * Log the usage of every response, warn when the service runs another model
+ * than the one asked for, and report a refused upgrade as a session error.
+ * `requestedModel` is the id the session was configured with.
+ */
+export function observeXaiSession(session, requestedModel) {
+    const stopWatching = watchForRefusedUpgrade(session);
+    session.on("openai_server_event_received", (event) => {
+        if (isRecord(event) && event.type === "session.created") {
+            stopWatching();
+            const served = isRecord(event.session) ? event.session.model : undefined;
+            if (typeof served === "string" && served !== requestedModel) {
+                logger.warn("realtime.xai.modelMismatch", {
+                    requested: requestedModel,
+                    served,
+                    note: "xAI runs a default model for an id it does not know, without an error; an alias comes back as the model it points to",
+                });
+            }
+            return;
+        }
+        const usage = readXaiResponseUsage(event);
+        if (usage !== undefined) {
+            logUsage(usage);
+        }
+    });
+    const close = session.close.bind(session);
+    session.close = async () => {
+        stopWatching();
+        await close();
+    };
+}