@juspay/neurolink 13.2.0 → 13.4.0

package/dist/core/baseProvider.d.ts

@@ -599,7 +599,6 @@ export declare abstract class BaseProvider implements AIProvider {
     /**
      * Get AI SDK model with middleware applied
      * This method wraps the base model with any configured middleware
-     * TODO(#1953): Implement global level middlewares that can be used
      */
     protected getAISDKModelWithMiddleware(options?: TextGenerationOptions | StreamOptions): Promise<LanguageModel>;
     /**

package/dist/core/baseProvider.js

@@ -117,7 +117,11 @@ export class BaseProvider {
     modelName;
     providerName;
     defaultTimeout = 30000; // 30 seconds
-    middlewareOptions; // TODO(#1953): Implement global level middlewares that can be used
+    // Only set by a subclass passing the 4th constructor argument; no provider
+    // does. NeuroLink resolves its instance, global and environment middleware
+    // defaults into `options.middleware` before a call reaches here (see
+    // middleware/defaults.ts), so a per-call value already carries them.
+    middlewareOptions;
     // Tools are conditionally included based on centralized configuration
     directTools = shouldDisableBuiltinTools()
         ? {}
@@ -2509,7 +2513,6 @@ export class BaseProvider {
     /**
      * Get AI SDK model with middleware applied
      * This method wraps the base model with any configured middleware
-     * TODO(#1953): Implement global level middlewares that can be used
      */
     async getAISDKModelWithMiddleware(options = {}) {
         return this.applyMiddlewareToModel(await this.getAISDKModel(), options);

package/dist/index.d.ts

@@ -89,6 +89,7 @@ export { shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, set
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+export { clearGlobalMiddleware, configureGlobalMiddleware, } from "./middleware/defaults.js";
 export { tool, jsonSchema, stepCountIs } from "./utils/tool.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";

package/dist/index.js

@@ -178,6 +178,7 @@ export { shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, set
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
+export { clearGlobalMiddleware, configureGlobalMiddleware, } from "./middleware/defaults.js";
 // Tool + schema helpers. Previously a consumer reached for `tool()` and
 // `jsonSchema()` from the ai package to build tools for generate({tools}).
 // That package is no longer a dependency, so the equivalents ship here.

package/dist/middleware/defaults.d.ts

@@ -0,0 +1,68 @@
+import type { MiddlewareFactoryOptions } from "../types/index.js";
+/**
+ * Middleware defaults.
+ *
+ * A generate()/stream() call resolves its middleware from up to four layers,
+ * lowest precedence first:
+ *
+ *   1. NEUROLINK_MIDDLEWARE_PRESET        (process environment)
+ *   2. configureGlobalMiddleware()        (module-level, set at runtime)
+ *   3. new NeuroLink({ middleware })      (per instance)
+ *   4. generate({ middleware })           (per call)
+ *
+ * A layer that is absent changes nothing, so a call made with no default set
+ * keeps exactly the middleware it passed.
+ */
+export declare const MIDDLEWARE_PRESET_ENV_VAR = "NEUROLINK_MIDDLEWARE_PRESET";
+/**
+ * Layer `override` over `base`.
+ *
+ * - `preset`, `middleware`, `enabledMiddleware` and `disabledMiddleware`: the
+ *   override's value replaces the base's whole; arrays are never concatenated.
+ * - `middlewareConfig`: merged per middleware id. Within an id, `enabled` and
+ *   `conditions` come from the override when it sets them, and `config` is
+ *   merged key by key, so a key the override sets replaces the base's value
+ *   for that key as a whole (nested objects and arrays are not combined).
+ * - `global`: merged key by key.
+ *
+ * The factory applies `disabledMiddleware` after `enabledMiddleware`, so an id
+ * the override switches on must be taken out of a disabled list it inherits
+ * (and the reverse), or a lower layer's list would out-vote a call that asked
+ * for the opposite.
+ */
+export declare function mergeMiddlewareOptions(base: MiddlewareFactoryOptions, override: MiddlewareFactoryOptions): MiddlewareFactoryOptions;
+/**
+ * Resolve the options a call runs with. `defaults` is ordered lowest
+ * precedence first; the per-call options sit on top.
+ *
+ * With no default present this returns `call` itself, so callers that never
+ * opted in see no change at all.
+ */
+export declare function resolveMiddlewareOptions(defaults: ReadonlyArray<MiddlewareFactoryOptions | undefined>, call: MiddlewareFactoryOptions | undefined): MiddlewareFactoryOptions | undefined;
+/**
+ * Validate a default layer and copy it, so later edits to the caller's object
+ * cannot change a default that was already set. Plain data (a word list, a
+ * replacement string) is copied in full; custom middleware, callbacks and
+ * model handles keep their identity. Throws a TypeError for a value that is
+ * not an object and for a preset name that is not built in.
+ */
+export declare function snapshotMiddlewareOptions(options: MiddlewareFactoryOptions, source: string): MiddlewareFactoryOptions;
+/**
+ * Process-wide middleware defaults. Applies to every NeuroLink instance, below
+ * the instance's own `middleware` option and above NEUROLINK_MIDDLEWARE_PRESET.
+ * Replaces any earlier call rather than adding to it, and is read on each
+ * generate()/stream(), so instances that already exist pick it up. Throws a
+ * TypeError when `options` is not an object or names a preset that is not
+ * built in.
+ */
+export declare function configureGlobalMiddleware(options: MiddlewareFactoryOptions): void;
+/** Remove the defaults set by {@link configureGlobalMiddleware}. */
+export declare function clearGlobalMiddleware(): void;
+/** The current global defaults, or undefined when none are set. */
+export declare function getGlobalMiddleware(): MiddlewareFactoryOptions | undefined;
+/**
+ * The preset named by NEUROLINK_MIDDLEWARE_PRESET, as the lowest default layer.
+ * An unset or blank variable is no layer; an unrecognised name is reported
+ * on stderr once per distinct value and ignored.
+ */
+export declare function readEnvMiddlewarePreset(env?: NodeJS.ProcessEnv): MiddlewareFactoryOptions | undefined;

package/dist/middleware/defaults.js

@@ -0,0 +1,225 @@
+import { logger } from "../utils/logger.js";
+import { BUILT_IN_MIDDLEWARE_PRESET_NAMES } from "./presets.js";
+/**
+ * Middleware defaults.
+ *
+ * A generate()/stream() call resolves its middleware from up to four layers,
+ * lowest precedence first:
+ *
+ *   1. NEUROLINK_MIDDLEWARE_PRESET        (process environment)
+ *   2. configureGlobalMiddleware()        (module-level, set at runtime)
+ *   3. new NeuroLink({ middleware })      (per instance)
+ *   4. generate({ middleware })           (per call)
+ *
+ * A layer that is absent changes nothing, so a call made with no default set
+ * keeps exactly the middleware it passed.
+ */
+export const MIDDLEWARE_PRESET_ENV_VAR = "NEUROLINK_MIDDLEWARE_PRESET";
+let globalMiddleware;
+const warnedPresets = new Set();
+const isPlainObject = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Date) &&
+    !(value instanceof RegExp);
+/** Own entries whose value is not `undefined`, so an unset key never wins. */
+const definedEntries = (value) => Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined));
+const isPureData = (value) => {
+    if (value === null || typeof value !== "object") {
+        return typeof value !== "function" && typeof value !== "symbol";
+    }
+    if (Array.isArray(value)) {
+        return value.every(isPureData);
+    }
+    const proto = Object.getPrototypeOf(value);
+    return ((proto === Object.prototype || proto === null) &&
+        Object.values(value).every(isPureData));
+};
+/**
+ * Copy a value only when it is plain data (JSON-like, no functions or class
+ * instances anywhere inside). A model handle, a callback or a custom
+ * middleware keeps its identity, because copying one would split its state
+ * from the object the caller still holds.
+ */
+const copyIfPureData = (value) => isPureData(value) ? structuredClone(value) : value;
+const isEmptyLayer = (layer) => Object.keys(definedEntries(layer)).length === 0;
+const mergeConfigEntry = (base, override) => {
+    const merged = {
+        ...definedEntries(base),
+        ...definedEntries(override),
+    };
+    if (base?.config !== undefined || override?.config !== undefined) {
+        merged.config = {
+            ...definedEntries(base?.config),
+            ...definedEntries(override?.config),
+        };
+    }
+    return merged;
+};
+/** Middleware ids this layer switches on or off, by any of the three routes. */
+const idsSwitched = (layer, state) => {
+    const ids = new Set((state ? layer.enabledMiddleware : layer.disabledMiddleware) ?? []);
+    for (const [id, entry] of Object.entries(layer.middlewareConfig ?? {})) {
+        if (entry?.enabled === state) {
+            ids.add(id);
+        }
+    }
+    return ids;
+};
+/**
+ * Layer `override` over `base`.
+ *
+ * - `preset`, `middleware`, `enabledMiddleware` and `disabledMiddleware`: the
+ *   override's value replaces the base's whole; arrays are never concatenated.
+ * - `middlewareConfig`: merged per middleware id. Within an id, `enabled` and
+ *   `conditions` come from the override when it sets them, and `config` is
+ *   merged key by key, so a key the override sets replaces the base's value
+ *   for that key as a whole (nested objects and arrays are not combined).
+ * - `global`: merged key by key.
+ *
+ * The factory applies `disabledMiddleware` after `enabledMiddleware`, so an id
+ * the override switches on must be taken out of a disabled list it inherits
+ * (and the reverse), or a lower layer's list would out-vote a call that asked
+ * for the opposite.
+ */
+export function mergeMiddlewareOptions(base, override) {
+    const merged = {};
+    const preset = override.preset ?? base.preset;
+    if (preset !== undefined) {
+        merged.preset = preset;
+    }
+    const custom = override.middleware ?? base.middleware;
+    if (custom !== undefined) {
+        merged.middleware = [...custom];
+    }
+    const switchedOn = idsSwitched(override, true);
+    const switchedOff = idsSwitched(override, false);
+    const enabled = override.enabledMiddleware ??
+        base.enabledMiddleware?.filter((id) => !switchedOff.has(id));
+    if (enabled !== undefined) {
+        merged.enabledMiddleware = [...enabled];
+    }
+    const disabled = override.disabledMiddleware ??
+        base.disabledMiddleware?.filter((id) => !switchedOn.has(id));
+    if (disabled !== undefined) {
+        merged.disabledMiddleware = [...disabled];
+    }
+    if (base.middlewareConfig || override.middlewareConfig) {
+        const ids = new Set([
+            ...Object.keys(base.middlewareConfig ?? {}),
+            ...Object.keys(override.middlewareConfig ?? {}),
+        ]);
+        merged.middlewareConfig = Object.fromEntries([...ids].map((id) => [
+            id,
+            mergeConfigEntry(base.middlewareConfig?.[id], override.middlewareConfig?.[id]),
+        ]));
+    }
+    if (base.global || override.global) {
+        merged.global = {
+            ...definedEntries(base.global),
+            ...definedEntries(override.global),
+        };
+    }
+    return merged;
+}
+/**
+ * Resolve the options a call runs with. `defaults` is ordered lowest
+ * precedence first; the per-call options sit on top.
+ *
+ * With no default present this returns `call` itself, so callers that never
+ * opted in see no change at all.
+ */
+export function resolveMiddlewareOptions(defaults, call) {
+    const layers = defaults.filter((layer) => layer !== undefined && !isEmptyLayer(layer));
+    if (layers.length === 0) {
+        return call;
+    }
+    const inherited = layers.reduce((acc, layer) => mergeMiddlewareOptions(acc, layer), {});
+    return isPlainObject(call)
+        ? mergeMiddlewareOptions(inherited, call)
+        : inherited;
+}
+/**
+ * Validate a default layer and copy it, so later edits to the caller's object
+ * cannot change a default that was already set. Plain data (a word list, a
+ * replacement string) is copied in full; custom middleware, callbacks and
+ * model handles keep their identity. Throws a TypeError for a value that is
+ * not an object and for a preset name that is not built in.
+ */
+export function snapshotMiddlewareOptions(options, source) {
+    if (!isPlainObject(options)) {
+        throw new TypeError(`${source}: middleware must be an object of MiddlewareFactoryOptions`);
+    }
+    if (options.preset !== undefined &&
+        !BUILT_IN_MIDDLEWARE_PRESET_NAMES.includes(options.preset)) {
+        // An unknown name left in the layer would replace a valid lower-layer
+        // preset and leave guardrails off with no sign of it, so a typo fails here.
+        throw new TypeError(`${source}: unknown middleware preset ${JSON.stringify(options.preset)}. Known presets: ${BUILT_IN_MIDDLEWARE_PRESET_NAMES.join(", ")}.`);
+    }
+    const merged = mergeMiddlewareOptions({}, options);
+    return {
+        ...merged,
+        ...(merged.middlewareConfig
+            ? {
+                middlewareConfig: Object.fromEntries(Object.entries(merged.middlewareConfig).map(([id, entry]) => [
+                    id,
+                    {
+                        ...entry,
+                        ...(entry.config
+                            ? {
+                                config: Object.fromEntries(Object.entries(entry.config).map(([key, value]) => [
+                                    key,
+                                    copyIfPureData(value),
+                                ])),
+                            }
+                            : {}),
+                        ...(entry.conditions
+                            ? { conditions: copyIfPureData(entry.conditions) }
+                            : {}),
+                    },
+                ])),
+            }
+            : {}),
+    };
+}
+/**
+ * Process-wide middleware defaults. Applies to every NeuroLink instance, below
+ * the instance's own `middleware` option and above NEUROLINK_MIDDLEWARE_PRESET.
+ * Replaces any earlier call rather than adding to it, and is read on each
+ * generate()/stream(), so instances that already exist pick it up. Throws a
+ * TypeError when `options` is not an object or names a preset that is not
+ * built in.
+ */
+export function configureGlobalMiddleware(options) {
+    globalMiddleware = snapshotMiddlewareOptions(options, "configureGlobalMiddleware");
+}
+/** Remove the defaults set by {@link configureGlobalMiddleware}. */
+export function clearGlobalMiddleware() {
+    globalMiddleware = undefined;
+}
+/** The current global defaults, or undefined when none are set. */
+export function getGlobalMiddleware() {
+    return globalMiddleware;
+}
+/**
+ * The preset named by NEUROLINK_MIDDLEWARE_PRESET, as the lowest default layer.
+ * An unset or blank variable is no layer; an unrecognised name is reported
+ * on stderr once per distinct value and ignored.
+ */
+export function readEnvMiddlewarePreset(env = process.env) {
+    const raw = env[MIDDLEWARE_PRESET_ENV_VAR]?.trim();
+    if (!raw) {
+        return undefined;
+    }
+    if (BUILT_IN_MIDDLEWARE_PRESET_NAMES.includes(raw)) {
+        return { preset: raw };
+    }
+    if (!warnedPresets.has(raw)) {
+        warnedPresets.add(raw);
+        // Written to stderr rather than through logger.warn, which drops warnings
+        // unless debugging: a mistyped preset would otherwise leave guardrails off
+        // with no sign of it.
+        logger.alwaysStderr(`[Middleware] Ignoring ${MIDDLEWARE_PRESET_ENV_VAR}=${JSON.stringify(raw)}: not a known preset. Known presets: ${BUILT_IN_MIDDLEWARE_PRESET_NAMES.join(", ")}.`);
+    }
+    return undefined;
+}

package/dist/middleware/factory.js

@@ -1,4 +1,5 @@
 import { MiddlewareRegistry } from "./registry.js";
+import { createBuiltInMiddlewarePresets } from "./presets.js";
 import { createAnalyticsMiddleware } from "./builtin/analytics.js";
 import { createGuardrailsMiddleware } from "./builtin/guardrails.js";
 import { createAutoEvaluationMiddleware } from "./builtin/autoEvaluation.js";
@@ -30,21 +31,9 @@ export class MiddlewareFactory {
             lifecycle: createLifecycleMiddleware,
         };
         // Register built-in presets
-        this.registerPreset({
-            name: "default",
-            description: "Default preset with analytics enabled.",
-            config: { analytics: { enabled: true } },
-        });
-        this.registerPreset({
-            name: "all",
-            description: "Enables all available middleware.",
-            config: { analytics: { enabled: true }, guardrails: { enabled: true } },
-        });
-        this.registerPreset({
-            name: "security",
-            description: "Focuses on security with guardrails.",
-            config: { guardrails: { enabled: true } },
-        });
+        for (const preset of createBuiltInMiddlewarePresets()) {
+            this.registerPreset(preset);
+        }
         // Register custom middleware if provided
         logger.debug("Initializing MiddlewareFactory", { options });
         if (options.middleware) {

package/dist/middleware/presets.d.ts

@@ -0,0 +1,12 @@
+import type { MiddlewarePreset } from "../types/index.js";
+/**
+ * The presets every `MiddlewareFactory` registers. Built fresh on each call so
+ * a factory that edits its own `presets` map cannot change another factory's.
+ *
+ * `all` is deliberately not "everything": autoEvaluation and lifecycle are
+ * opt-in per call and stay out of it. `security` only switches guardrails on;
+ * it ships no word list and no model filter, so it redacts nothing until the
+ * caller supplies `badWords` or `modelFilter`.
+ */
+export declare function createBuiltInMiddlewarePresets(): MiddlewarePreset[];
+export declare const BUILT_IN_MIDDLEWARE_PRESET_NAMES: readonly string[];

package/dist/middleware/presets.js

@@ -0,0 +1,29 @@
+/**
+ * The presets every `MiddlewareFactory` registers. Built fresh on each call so
+ * a factory that edits its own `presets` map cannot change another factory's.
+ *
+ * `all` is deliberately not "everything": autoEvaluation and lifecycle are
+ * opt-in per call and stay out of it. `security` only switches guardrails on;
+ * it ships no word list and no model filter, so it redacts nothing until the
+ * caller supplies `badWords` or `modelFilter`.
+ */
+export function createBuiltInMiddlewarePresets() {
+    return [
+        {
+            name: "default",
+            description: "Default preset with analytics enabled.",
+            config: { analytics: { enabled: true } },
+        },
+        {
+            name: "all",
+            description: "Enables analytics and guardrails.",
+            config: { analytics: { enabled: true }, guardrails: { enabled: true } },
+        },
+        {
+            name: "security",
+            description: "Enables guardrails. Filters nothing until badWords or modelFilter is configured.",
+            config: { guardrails: { enabled: true } },
+        },
+    ];
+}
+export const BUILT_IN_MIDDLEWARE_PRESET_NAMES = createBuiltInMiddlewarePresets().map((preset) => preset.name);

package/dist/neurolink.d.ts

@@ -159,6 +159,8 @@ export declare class NeuroLink {
     /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
     private discoveryPins;
     private enableOrchestration;
+    private readonly envMiddleware?;
+    private readonly constructorMiddleware?;
     private authProvider?;
     private pendingAuthConfig?;
     private authInitPromise?;
@@ -234,6 +236,13 @@ export declare class NeuroLink {
     private enforceSessionBudget;
     private assertInputText;
     private applyAuthenticatedRequestContext;
+    /**
+     * Fold the instance, global and environment middleware defaults beneath the
+     * call's own `middleware`. Runs before the lifecycle helpers so they layer
+     * onFinish/onError on top of the resolved config rather than replacing it.
+     * With no default set the options are left untouched.
+     */
+    private applyMiddlewareDefaults;
     private applyGenerateLifecycleMiddleware;
     private applyStreamLifecycleMiddleware;
     private initializeMemoryConfig;

package/dist/neurolink.js

@@ -94,6 +94,7 @@ import { hasLifecycleErrorFired, markLifecycleErrorFired, markLifecycleStreamCal
 import { interleaveTTSStream } from "./utils/ttsStream.js";
 import { resolveLifecycleTimeoutMs } from "./utils/lifecycleTimeout.js";
 import { cloneOptionsForCallIsolation } from "./utils/cloneOptions.js";
+import { getGlobalMiddleware, readEnvMiddlewarePreset, resolveMiddlewareOptions, snapshotMiddlewareOptions, } from "./middleware/defaults.js";
 import { preserveLiveStreamAccessors } from "./utils/streamResultAccessors.js";
 import { coerceJsonToSchema, recoverScalarRoot, schemaAccepts, } from "./utils/json/coerce.js";
 // Factory processing imports
@@ -655,6 +656,12 @@ export class NeuroLink {
     discoveryPins = new Map();
     // Add orchestration property
     enableOrchestration;
+    // Language-model middleware defaults, lowest precedence first: the layer
+    // read from NEUROLINK_MIDDLEWARE_PRESET, then the constructor's `middleware`
+    // option. The module-level global registry sits between them and is read on
+    // each call, so it can change after construction. See middleware/defaults.ts.
+    envMiddleware;
+    constructorMiddleware;
     // Authentication provider for secure access control
     authProvider;
     pendingAuthConfig;
@@ -900,6 +907,18 @@ export class NeuroLink {
             ...tokenDerivedFields,
         };
     }
+    /**
+     * Fold the instance, global and environment middleware defaults beneath the
+     * call's own `middleware`. Runs before the lifecycle helpers so they layer
+     * onFinish/onError on top of the resolved config rather than replacing it.
+     * With no default set the options are left untouched.
+     */
+    applyMiddlewareDefaults(options) {
+        const resolved = resolveMiddlewareOptions([this.envMiddleware, getGlobalMiddleware(), this.constructorMiddleware], options.middleware);
+        if (resolved !== options.middleware) {
+            options.middleware = resolved;
+        }
+    }
     applyGenerateLifecycleMiddleware(options) {
         if (!options.onFinish && !options.onError) {
             return;
@@ -1207,6 +1226,13 @@ export class NeuroLink {
         return metricsTraceContextStorage.getStore() ?? null;
     }
     constructor(config) {
+        // Validated first: an invalid default must throw before the constructor
+        // starts telemetry or any other process-wide state.
+        this.envMiddleware = readEnvMiddlewarePreset();
+        this.constructorMiddleware =
+            config?.middleware === undefined
+                ? undefined
+                : snapshotMiddlewareOptions(config.middleware, "NeuroLink constructor");
         if (config?.toolRegistry) {
             // A supplied registry (a host's, shared with a worker) keeps its owner's
             // roots; per-call executeTool() binds this instance's policy anyway.
@@ -4157,6 +4183,7 @@ Current user's request: ${currentInput}`;
             options.input.text = piiResult.text;
         }
         this.enforceSessionBudget(options.maxBudgetUsd);
+        this.applyMiddlewareDefaults(options);
         this.applyGenerateLifecycleMiddleware(options);
         await this.applyAuthenticatedRequestContext(options);
         return { options, originalPrompt };
@@ -5470,6 +5497,9 @@ Current user's request: ${currentInput}`;
         // NL-004: Resolve model aliases/deprecations before processing
         isolated.model = resolveModel(isolated.model, this.modelAliasConfig);
         bindFileToolRoots(isolated, this.resolveFileToolRoots(isolated.toolRoots));
+        // generateText() reaches the same providers as generate() without passing
+        // through its prelude, so the middleware defaults are folded in here too.
+        this.applyMiddlewareDefaults(isolated);
         // Use internal generation method directly
         return await this.generateTextInternal(isolated);
     }
@@ -8291,6 +8321,7 @@ Current user's request: ${currentInput}`;
         this.enforceSessionBudget(options.maxBudgetUsd);
         await this.applyAuthenticatedRequestContext(options);
         this.emitStreamStartEvents(options, startTime);
+        this.applyMiddlewareDefaults(options);
         this.applyStreamLifecycleMiddleware(options);
     }
     async maybeHandleWorkflowStreamRequest(params) {

package/dist/types/config.d.ts

@@ -17,6 +17,7 @@ import type { ContextRelevanceOptions } from "./context.js";
 import type { DecisionHooks } from "./decision.js";
 import type { SkillsConfig } from "./skills.js";
 import type { KnowledgeGroundingConfig } from "./knowledge.js";
+import type { MiddlewareFactoryOptions } from "./middleware.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -184,6 +185,27 @@ export type NeurolinkConstructorConfig = {
      * {@link KnowledgeGroundingConfig}.
      */
     knowledgeGrounding?: KnowledgeGroundingConfig;
+    /**
+     * Language-model middleware applied to every generate()/stream() on this
+     * instance (guardrails, analytics, custom middleware). Spares each call from
+     * repeating the same `middleware` option.
+     *
+     * Precedence, lowest to highest: `NEUROLINK_MIDDLEWARE_PRESET`,
+     * `configureGlobalMiddleware()`, this option, then the call's own
+     * `middleware`. `middlewareConfig` merges per middleware id, and a key set
+     * by a higher layer replaces the lower layer's value; arrays are replaced,
+     * never concatenated. A call can switch off an inherited middleware with
+     * `disabledMiddleware` or `middlewareConfig.<id>.enabled: false`.
+     *
+     * Throws a TypeError at construction when this is not an object or its
+     * `preset` is not a built-in preset (`default`, `all` or `security`).
+     *
+     * Unset by default, in which case calls behave exactly as before. Note that
+     * `preset: "security"` only turns guardrails on: nothing is redacted until
+     * `middlewareConfig.guardrails.config` supplies `badWords` or `modelFilter`.
+     * See {@link MiddlewareFactoryOptions}.
+     */
+    middleware?: MiddlewareFactoryOptions;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/livekit.d.ts

@@ -421,30 +421,52 @@ export type LiveKitServerCredentials = {
     apiKey: string;
     apiSecret: string;
 };
+/**
+ * The realtime speech-to-speech model a call runs on: Gemini Live on Vertex
+ * (the default) or xAI Grok Voice through LiveKit's xAI plugin.
+ */
+export type RealtimeVoiceBackend = "gemini" | "xai";
+/**
+ * A LiveKit realtime model as far as callers of the model factory can rely on.
+ * It is declared structurally so the published declarations name no optional
+ * LiveKit plugin; at runtime it is a `RealtimeModel` subclass of the backend's
+ * plugin.
+ */
+export type RealtimeLlm = {
+    readonly model: string;
+    label: () => string;
+    close: () => Promise<void>;
+};
 /**
  * Realtime voice configuration resolved from the environment.
  *
- * In speech-to-speech mode one realtime model (Gemini Live on Vertex) does STT,
- * reasoning, TTS, and turn detection — so there is no separate STT/TTS/VAD/EOU
- * config. `resolveRealtimeVoiceConfig` fills every field from `process.env`
- * (with defaults); `RealtimeVoiceAgentConfig` lets a caller override any of them.
+ * In speech-to-speech mode one realtime model (Gemini Live on Vertex, or xAI
+ * Grok Voice) does STT, reasoning, TTS, and turn detection — so there is no
+ * separate STT/TTS/VAD/EOU config. `resolveRealtimeVoiceConfig` fills every
+ * field from `process.env` (with defaults); `RealtimeVoiceAgentConfig` lets a
+ * caller override any of them. The API key of the xai backend is deliberately
+ * not part of the config: the xAI plugin reads `XAI_API_KEY` itself.
  */
 export type RealtimeVoiceConfig = {
-    /** Vertex project id (from VERTEX_PROJECT / GOOGLE_AUTH_* / GOOGLE_CLOUD_PROJECT_ID). */
+    /** Which realtime model family handles the call (VOICE_REALTIME_BACKEND; default "gemini"). */
+    backend: RealtimeVoiceBackend;
+    /** Vertex project id (from VERTEX_PROJECT / GOOGLE_AUTH_* / GOOGLE_CLOUD_PROJECT_ID). Gemini only. */
     project: string | undefined;
-    /** Vertex location; native-audio Live is served on `global`, not regionally. */
+    /** Vertex location; native-audio Live is served on `global`, not regionally. Gemini only. */
     location: string;
-    /** Realtime model id (e.g. "gemini-live-2.5-flash"). */
+    /** Realtime model id (e.g. "gemini-live-2.5-flash" for gemini, "grok-voice-3.0" for xai). */
     model: string;
-    /** Optional Gemini voice name; omit for the plugin default. */
+    /** Optional voice name for either backend; omit for the plugin default. */
     voice: string | undefined;
-    /** Response modality: "AUDIO" (native S2S) or "TEXT" (half-cascade). */
+    /** xai only: WebSocket base URL of the realtime endpoint (XAI_REALTIME_BASE_URL); unset keeps the plugin's own endpoint. */
+    xaiBaseURL: string | undefined;
+    /** Response modality: "AUDIO" (native S2S) or "TEXT" (half-cascade). Gemini only. */
     responseModality: string;
     /** System prompt / instructions for the agent. */
     systemPrompt: string;
     /** Opening line the agent speaks on connect ("" disables). */
     greeting: string;
-    /** Whether to bridge Lighthouse MCP tools as Gemini function tools. */
+    /** Whether to bridge Lighthouse MCP tools as function tools of the realtime model (either backend). */
     toolsEnabled: boolean;
     /** Full URL of the MCP server the tools are bridged from. */
     mcpUrl: string;
@@ -474,10 +496,14 @@ export type RealtimeVoiceLogContext = {
  * everything via env.
  */
 export type RealtimeVoiceAgentConfig = {
+    /** Realtime backend; omitted means the environment's VOICE_REALTIME_BACKEND, and without it "gemini". */
+    backend?: RealtimeVoiceBackend;
     project?: string;
     location?: string;
     model?: string;
     voice?: string;
+    /** xai only: WebSocket base URL of the realtime endpoint. */
+    xaiBaseURL?: string;
     responseModality?: string;
     systemPrompt?: string;
     greeting?: string;
@@ -736,7 +762,7 @@ export type BuildRealtimeMcpToolsParams = {
      * Hard cap per MCP tool call, in milliseconds (default 30000).
      *
      * Without one, a stalled MCP server holds the realtime turn open forever:
-     * Gemini waits on the function result, so the user gets silence rather than
+     * The realtime model waits on the function result, so the user gets silence rather than
      * an error. Bounding the call turns that into a normal tool failure the
      * model can talk about.
      */