@juspay/neurolink 13.4.4 → 13.4.6

package/dist/cli/commands/decide.js

@@ -221,7 +221,7 @@ export const decideCommand = {
     })
         .example('$0 decide "Refund request for a damaged item" --questions \'{"urgent":{"type":"boolean","instructions":"Is this urgent?"}}\'', "Ask a single yes/no question")
         .example("$0 decide --state-file ticket.json --questions-file questions.json --format json", "Read state and questions from files, emit raw JSON")
-        .example('$0 decide "What color is this?" --provider xor --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR, Perplexity, Cloudflare Clef and OpenAI Decisions read images)"),
+        .example('$0 decide "What color is this?" --provider xor --model xor-omni --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR with its xor-omni model, Perplexity, Cloudflare Clef and OpenAI Decisions read images)"),
     handler: async (argv) => {
         const outputFormat = argv.format ?? "text";
         // --- Validate before any provider work ---------------------------------

package/dist/constants/enums.d.ts

@@ -1777,6 +1777,8 @@ export declare enum XiaomiMimoModels {
     MIMO_V2_6_FLASH = "mimo-v2.6-flash"
 }
 export declare enum XorModels {
+    XOR_LATEST = "xor-latest",
+    XOR_OMNI = "xor-omni",
     XOR_1_1 = "xor-1.1"
 }
 export declare enum ZAiModels {

package/dist/constants/enums.js

@@ -2104,6 +2104,8 @@ export var XiaomiMimoModels;
 })(XiaomiMimoModels || (XiaomiMimoModels = {}));
 export var XorModels;
 (function (XorModels) {
+    XorModels["XOR_LATEST"] = "xor-latest";
+    XorModels["XOR_OMNI"] = "xor-omni";
     XorModels["XOR_1_1"] = "xor-1.1";
 })(XorModels || (XorModels = {}));
 export var ZAiModels;

package/dist/hitl/hitlManager.js

@@ -49,7 +49,7 @@ export class HITLManager extends EventEmitter {
             dangerousActions: config.dangerousActions,
             timeout: config.timeout ?? DEFAULT_TIMEOUT, // Default: 30 seconds
             confirmationMethod: config.confirmationMethod ?? "event", // Default: "event"
-            allowArgumentModification: config.allowArgumentModification ?? DEFAULT_ALLOW_MODIFICATION, // Default: true
+            allowArgumentModification: config.allowArgumentModification ?? DEFAULT_ALLOW_MODIFICATION, // Default: false
             autoApproveOnTimeout: config.autoApproveOnTimeout ?? false, // Default: false (safe)
             autoApproveExclusions: Array.isArray(config.autoApproveExclusions)
                 ? [...config.autoApproveExclusions]

package/dist/neurolink.d.ts

@@ -334,9 +334,9 @@ export declare class NeuroLink {
      * @param config.enableOrchestration - Whether to enable smart model orchestration (default: false)
      * @param config.hitl - Configuration for Human-in-the-Loop safety features
      * @param config.hitl.enabled - Whether to enable HITL tool confirmation (default: false)
-     * @param config.hitl.dangerousActions - Keywords that trigger confirmation (default: ['delete', 'remove', 'drop'])
+     * @param config.hitl.dangerousActions - Keywords that trigger confirmation; required when HITL is enabled
      * @param config.hitl.timeout - Confirmation timeout in milliseconds (default: 30000)
-     * @param config.hitl.allowArgumentModification - Allow users to modify tool parameters (default: true)
+     * @param config.hitl.allowArgumentModification - Advertised to the approval UI as `allowModification` (default: false); not enforced, a response's `modifiedArguments` is applied either way
      * @param config.toolRegistry - Optional tool registry instance for advanced use cases (default: new MCPToolRegistry())
      *
      * @example

package/dist/neurolink.js

@@ -242,13 +242,26 @@ const MEMORY_WRITE_TIMEOUT_MS = 30_000;
  *
  * @example With HITL security
  * ```typescript
+ * import type { ConfirmationRequestEvent } from '@juspay/neurolink';
+ *
  * const neurolink = new NeuroLink({
  *   hitl: {
  *     enabled: true,
- *     requireApproval: ['writeFile', 'executeCode'],
- *     confidenceThreshold: 0.85
+ *     dangerousActions: ['writeFile', 'executeCode'],
+ *     timeout: 30000
  *   }
  * });
+ *
+ * // Approval is event-based; answer each request with the matching id
+ * const emitter = neurolink.getEventEmitter();
+ * emitter.on('hitl:confirmation-request', async (event) => {
+ *   const { payload } = event as ConfirmationRequestEvent; // listeners are typed unknown
+ *   const approved = await askUser(payload); // your approval UI
+ *   emitter.emit('hitl:confirmation-response', {
+ *     type: 'hitl:confirmation-response',
+ *     payload: { confirmationId: payload.confirmationId, approved }
+ *   });
+ * });
  * ```
  *
  * @example With Redis memory
@@ -1173,9 +1186,9 @@ export class NeuroLink {
      * @param config.enableOrchestration - Whether to enable smart model orchestration (default: false)
      * @param config.hitl - Configuration for Human-in-the-Loop safety features
      * @param config.hitl.enabled - Whether to enable HITL tool confirmation (default: false)
-     * @param config.hitl.dangerousActions - Keywords that trigger confirmation (default: ['delete', 'remove', 'drop'])
+     * @param config.hitl.dangerousActions - Keywords that trigger confirmation; required when HITL is enabled
      * @param config.hitl.timeout - Confirmation timeout in milliseconds (default: 30000)
-     * @param config.hitl.allowArgumentModification - Allow users to modify tool parameters (default: true)
+     * @param config.hitl.allowArgumentModification - Advertised to the approval UI as `allowModification` (default: false); not enforced, a response's `modifiedArguments` is applied either way
      * @param config.toolRegistry - Optional tool registry instance for advanced use cases (default: new MCPToolRegistry())
      *
      * @example

package/dist/providers/catalog/xor.json

@@ -6,15 +6,29 @@
     "inferenceKinds": ["decide"],
     "wire": {},
     "models": {
-        "default": "xor-1.1",
-        "topModels": ["xor-1.1"],
+        "default": "xor-latest",
+        "topModels": ["xor-latest", "xor-omni"],
         "catalog": {
-            "xor-1.1": {
+            "xor-latest": {
                 "contextWindow": 250000,
                 "maxOutputTokens": 256,
                 "vision": false,
                 "status": "production",
-                "description": "Recommended - XOR 1.1, decision model that also reads images and video"
+                "description": "Recommended - XOR text alias; boolean, choice and score questions, 2 to 64 options each"
+            },
+            "xor-omni": {
+                "contextWindow": 250000,
+                "maxOutputTokens": 256,
+                "vision": true,
+                "status": "production",
+                "description": "XOR multimodal alias; reads images and video alongside the state, for boolean, choice and score questions"
+            },
+            "xor-1.1": {
+                "contextWindow": 250000,
+                "maxOutputTokens": 256,
+                "vision": false,
+                "status": "retired",
+                "description": "Name served by the deprecated /v1/systemone route; superseded by xor-latest and xor-omni. Still sent as given when you name it - the endpoint decides whether it accepts it"
             }
         }
     },
@@ -30,7 +44,7 @@
         "baseURLRequired": true,
         "baseURLNormalize": ["strip-trailing-slash", "strip-v1-suffix"],
         "baseURLShape": "origin",
-        "endpoint": "{baseURL}/v1/systemone",
+        "endpoint": "{baseURL}/v1/decisions",
         "model": { "placement": "body" },
         "media": { "imagesKey": "images", "videoKey": "video" },
         "requestIdHeaders": [
@@ -71,14 +85,14 @@
         "description": "API key for your XOR endpoint",
         "instructions": [
             "1. Reach an XOR deployment, or use a LiteLLM proxy with a pass-through route to one",
-            "2. Set XOR_BASE_URL to its origin (NeuroLink calls <XOR_BASE_URL>/v1/systemone)",
-            "3. Set {apiKeyEnvVar} to the key it accepts (on LiteLLM, a virtual key whose team allows xor-1.1)"
+            "2. Set XOR_BASE_URL to its origin (NeuroLink calls <XOR_BASE_URL>/v1/decisions)",
+            "3. Set {apiKeyEnvVar} to the key it accepts (on LiteLLM, a virtual key whose team allows xor-latest, and xor-omni for media)"
         ]
     },
     "evidence": {
         "rosterVerified": {
-            "date": "2026-09-29",
-            "method": "The single model id xor-1.1 is the roster the hand-written XOR descriptor shipped; 2026-09-29 is the date it was added, not a date it was checked. The roster was never verified against a live XOR endpoint, and no live probe was run in this change"
+            "date": "2026-10-18",
+            "method": "POST <origin>/v1/decisions with model xor-latest and a 3-option choice question returned HTTP 200 with served model xor-text-2, through NeuroLink's decide(); a 65-option choice question returned HTTP 422 reading 2..64 options, got 65. A 64-option question returned 200 and 77 options returned 422 on both aliases when probed by hand the same day. A successful xor-omni answer, and any image, audio or video request, were not exercised. The figures contextWindow 250000, maxOutputTokens 256, the 200000-token state window and the media limits are carried over from xor-1.1, not re-measured for the aliases; xor-1.1 is kept only as a retired name"
         },
         "liveMatrix": null,
         "addedInPR": "https://github.com/juspay/neurolink/pull/1984"

package/dist/types/hitl.d.ts

@@ -18,7 +18,7 @@ export type HITLConfig = {
     timeout?: number;
     /** Communication method - currently only "event" is supported (default: "event") */
     confirmationMethod?: "event";
-    /** Whether users can modify tool arguments during approval (default: true) */
+    /** Advertised to the approval UI as allowModification (default: false); not enforced, a response's modifiedArguments is applied either way */
     allowArgumentModification?: boolean;
     /** Auto-approve requests when they timeout (default: false - rejects on timeout) */
     autoApproveOnTimeout?: boolean;
@@ -72,7 +72,7 @@ export type ConfirmationResult = {
     approved: boolean;
     /** Optional reason for rejection (if approved is false) */
     reason?: string;
-    /** User-modified arguments (if allowArgumentModification is enabled) */
+    /** User-modified arguments; applied whether or not allowArgumentModification is enabled */
     modifiedArguments?: unknown;
     /** Time taken for user to respond in milliseconds */
     responseTime: number;
@@ -107,7 +107,7 @@ export type ConfirmationRequestEvent = {
         };
         /** Confirmation timeout in milliseconds */
         timeoutMs: number;
-        /** Whether user can modify arguments */
+        /** Hint for the approval UI, copied from allowArgumentModification; not enforced */
         allowModification: boolean;
     };
 };

package/dist/types/livekit.d.ts

@@ -502,7 +502,7 @@ export type RealtimeVoiceAgentConfig = {
     location?: string;
     model?: string;
     voice?: string;
-    /** xai only: WebSocket base URL of the realtime endpoint. */
+    /** xai only: WebSocket base URL of the realtime endpoint. A `ws://` URL to a host other than localhost, 127.0.0.0/8 or [::1] is refused unless `XAI_REALTIME_ALLOW_INSECURE=true`, because the xAI key would cross the network unencrypted. */
     xaiBaseURL?: string;
     responseModality?: string;
     systemPrompt?: string;

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

@@ -23,6 +23,15 @@ export declare function resolveLiveKitServerConfig(): LiveKitServerConfig;
  * `VOICE_LLM_MODEL`.
  */
 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.
+ */
+export declare function requireNoCleartextCrossHost(value: string, name: string): void;
 /**
  * Resolve the realtime (speech-to-speech) voice configuration from the
  * environment.
@@ -31,7 +40,10 @@ export declare function resolveBrainDefaults(): LiveKitBrainDefaults;
  * env at all. `VOICE_REALTIME_BACKEND` picks the model family (`gemini`, the
  * default, or `xai`); `backend` here overrides it and then the environment's
  * value is not read. A non-blank `xaiBaseURL` here likewise replaces
- * `XAI_REALTIME_BASE_URL` after the same ws or wss check.
+ * `XAI_REALTIME_BASE_URL` after the same ws or wss check. Either URL is
+ * checked whatever the backend. A `ws://` URL to a host other than `localhost`,
+ * `127.0.0.0/8` or `[::1]` is refused unless `XAI_REALTIME_ALLOW_INSECURE=true`,
+ * because the xAI plugin sends `XAI_API_KEY` to it unencrypted.
  * `VOICE_LIVE_MODEL` overrides the backend's default model.
  * Vertex `project` is resolved from `VERTEX_PROJECT`, then the service-account
  * project (`GOOGLE_AUTH_BREEZE_PROJECT_ID`), then `GOOGLE_CLOUD_PROJECT_ID`;

package/dist/voice/livekit/config.js

@@ -77,6 +77,7 @@ const DEFAULT_SYSTEM_PROMPT = "You are a concise voice assistant for a merchant
 const DEFAULT_GREETING = "Briefly greet the merchant and ask how you can help with their store today.";
 const DEFAULT_LIGHTHOUSE_URL = "http://localhost:5173";
 const DEFAULT_MCP_PATH = "/ai/mcp/v2";
+const ALLOW_INSECURE_ENV = "XAI_REALTIME_ALLOW_INSECURE";
 /**
  * The backend named by `VOICE_REALTIME_BACKEND`: `gemini` or `xai`, matched
  * case-insensitively, with blank or absent meaning `gemini`. The error names the
@@ -100,20 +101,53 @@ function requireKnownBackend(value) {
     }
     throw new Error('The realtime voice backend must be "gemini" or "xai"');
 }
-function isWebSocketUrl(value) {
+function parseWebSocketUrl(value) {
     try {
-        const { protocol } = new URL(value);
-        return protocol === "ws:" || protocol === "wss:";
+        const url = new URL(value);
+        return url.protocol === "ws:" || url.protocol === "wss:" ? url : undefined;
     }
     catch {
-        return false;
+        return undefined;
     }
 }
-/** A ws or wss URL. The error names the setting and does not repeat the value. */
+/**
+ * Whether a WHATWG-parsed hostname is `localhost`, an address in `127.0.0.0/8`
+ * or `[::1]`. The parser has already lowercased the name and reduced shorthand
+ * IPv4 forms (`127.1`, `0x7f.1`) to dotted decimal, and a userinfo prefix such
+ * as `localhost@host` never reaches `hostname`, so neither can pass for a
+ * loopback host.
+ */
+function isLoopbackHost(hostname) {
+    if (hostname === "localhost" || hostname === "[::1]") {
+        return true;
+    }
+    const octets = hostname.split(".");
+    return (octets.length === 4 &&
+        octets[0] === "127" &&
+        octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255));
+}
+/**
+ * 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.
+ */
+export function requireNoCleartextCrossHost(value, name) {
+    const url = parseWebSocketUrl(value);
+    if (url?.protocol === "ws:" &&
+        !isLoopbackHost(url.hostname) &&
+        readEnv(ALLOW_INSECURE_ENV, "").toLowerCase() !== "true") {
+        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) {
-    if (!isWebSocketUrl(value)) {
+    if (parseWebSocketUrl(value) === undefined) {
         throw new Error(`${name} must be a ws:// or wss:// URL`);
     }
+    requireNoCleartextCrossHost(value, name);
     return value;
 }
 /** `XAI_REALTIME_BASE_URL`, which must be a ws or wss URL when set. */
@@ -136,7 +170,10 @@ function resolveXaiBaseUrl(override) {
  * env at all. `VOICE_REALTIME_BACKEND` picks the model family (`gemini`, the
  * default, or `xai`); `backend` here overrides it and then the environment's
  * value is not read. A non-blank `xaiBaseURL` here likewise replaces
- * `XAI_REALTIME_BASE_URL` after the same ws or wss check.
+ * `XAI_REALTIME_BASE_URL` after the same ws or wss check. Either URL is
+ * checked whatever the backend. A `ws://` URL to a host other than `localhost`,
+ * `127.0.0.0/8` or `[::1]` is refused unless `XAI_REALTIME_ALLOW_INSECURE=true`,
+ * because the xAI plugin sends `XAI_API_KEY` to it unencrypted.
  * `VOICE_LIVE_MODEL` overrides the backend's default model.
  * Vertex `project` is resolved from `VERTEX_PROJECT`, then the service-account
  * project (`GOOGLE_AUTH_BREEZE_PROJECT_ID`), then `GOOGLE_CLOUD_PROJECT_ID`;

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

@@ -28,6 +28,8 @@ 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.
+ * 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.
  */
 export declare function createRealtimeLlm(cfg: RealtimeVoiceConfig): Promise<RealtimeLlm>;

package/dist/voice/livekit/realtimeModel.js

@@ -13,6 +13,7 @@
  *
  * See docs/features/livekit-voice-agent.md.
  */
+import { requireNoCleartextCrossHost } from "./config.js";
 /**
  * Fail early, naming the variable, when `XAI_API_KEY` is blank or absent.
  *
@@ -53,6 +54,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.
+    if (cfg.xaiBaseURL) {
+        requireNoCleartextCrossHost(cfg.xaiBaseURL, "xaiBaseURL");
+    }
     const xai = await import("@livekit/agents-plugin-xai");
     // Keys are added only when set. The plugin spreads these options over its
     // own defaults, so a key holding `undefined` would erase the default: a
@@ -75,7 +81,9 @@ 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.
+ * 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.
  */
 export async function createRealtimeLlm(cfg) {
     switch (cfg.backend) {