@juspay/neurolink 13.1.1 → 13.3.0

package/dist/cli/commands/decide.d.ts

@@ -10,7 +10,8 @@
  * Credentials are env-only here, exactly as every other CLI command: the
  * decision provider reads its own settings (TYPESAFE_API_KEY, LAYA_API_KEY and
  * LAYA_BASE_URL, XOR_API_KEY and XOR_BASE_URL, SUBQ_API_KEY, PERPLEXITY_API_KEY,
- * CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID, or OPENAI_API_KEY) itself. An
+ * CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID, OPENAI_API_KEY, or
+ * SCALEDOWN_API_KEY) itself. An
  * OPENAI_API_KEY beside an OPENAI_BASE_URL, OPENAI_API_BASE or credentials.openai.baseURL that names a host
  * other than https://api.openai.com is a gateway's and is not used by default.
  */

package/dist/cli/commands/decide.js

@@ -10,7 +10,8 @@
  * Credentials are env-only here, exactly as every other CLI command: the
  * decision provider reads its own settings (TYPESAFE_API_KEY, LAYA_API_KEY and
  * LAYA_BASE_URL, XOR_API_KEY and XOR_BASE_URL, SUBQ_API_KEY, PERPLEXITY_API_KEY,
- * CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID, or OPENAI_API_KEY) itself. An
+ * CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID, OPENAI_API_KEY, or
+ * SCALEDOWN_API_KEY) itself. An
  * OPENAI_API_KEY beside an OPENAI_BASE_URL, OPENAI_API_BASE or credentials.openai.baseURL that names a host
  * other than https://api.openai.com is a gateway's and is not used by default.
  */

package/dist/cli/commands/setup.d.ts

@@ -13,7 +13,7 @@ import type { ProviderConfigOptions, SetupArgs } from "../../types/index.js";
  * perplexity, sambanova, together-ai, xai — mistral is the 9th catalog
  * provider but keeps its own handleMistralSetup() flow above, so it's
  * excluded here), spread directly from the catalog JSON via
- * buildCatalogConfigOptions(); decide-kind catalog entries (laya, xor, subq, openai-decisions) are
+ * buildCatalogConfigOptions(); decide-kind catalog entries (laya, xor, subq, openai-decisions, scaledown) are
  * spread the same way from getDecideCatalogEntries(). The hand rows listed
  * first reuse the existing createXConfig() factories in providerConfig.ts; the
  * remaining 5 (ollama, litellm, sagemaker, lm-studio, llamacpp) don't have a

package/dist/cli/commands/setup.js

@@ -150,7 +150,7 @@ const PROVIDERS = [
  * perplexity, sambanova, together-ai, xai — mistral is the 9th catalog
  * provider but keeps its own handleMistralSetup() flow above, so it's
  * excluded here), spread directly from the catalog JSON via
- * buildCatalogConfigOptions(); decide-kind catalog entries (laya, xor, subq, openai-decisions) are
+ * buildCatalogConfigOptions(); decide-kind catalog entries (laya, xor, subq, openai-decisions, scaledown) are
  * spread the same way from getDecideCatalogEntries(). The hand rows listed
  * first reuse the existing createXConfig() factories in providerConfig.ts; the
  * remaining 5 (ollama, litellm, sagemaker, lm-studio, llamacpp) don't have a

package/dist/cli/factories/commandFactory.js

@@ -649,7 +649,7 @@ export class CLICommandFactory {
         },
         classifierStrategy: {
             type: "string",
-            description: "Classifier strategy: 'auto' (default — 'jev' when a decision provider is configured, such as TYPESAFE_API_KEY, LAYA_API_KEY with LAYA_BASE_URL, XOR_API_KEY with XOR_BASE_URL, SUBQ_API_KEY, PERPLEXITY_API_KEY, CLOUDFLARE_API_KEY with CLOUDFLARE_ACCOUNT_ID, or OPENAI_API_KEY unless OPENAI_BASE_URL, OPENAI_API_BASE or credentials.openai.baseURL names a host other than https://api.openai.com, else 'heuristic'), 'heuristic' (no LLM), 'llm' (a cheap model picks per prompt), or 'jev' (a decision model — whichever decision provider is configured: TypeSafe Jev, Laya, XOR, SubQ, Perplexity, Cloudflare Clef or OpenAI Decisions — with the confidence it reports).",
+            description: "Classifier strategy: 'auto' (default — 'jev' when a decision provider is configured, such as TYPESAFE_API_KEY, LAYA_API_KEY with LAYA_BASE_URL, XOR_API_KEY with XOR_BASE_URL, SUBQ_API_KEY, PERPLEXITY_API_KEY, CLOUDFLARE_API_KEY with CLOUDFLARE_ACCOUNT_ID, OPENAI_API_KEY unless OPENAI_BASE_URL, OPENAI_API_BASE or credentials.openai.baseURL names a host other than https://api.openai.com, or SCALEDOWN_API_KEY, else 'heuristic'), 'heuristic' (no LLM), 'llm' (a cheap model picks per prompt), or 'jev' (a decision model — whichever decision provider is configured: TypeSafe Jev, Laya, XOR, SubQ, Perplexity, Cloudflare Clef, OpenAI Decisions or ScaleDown — with the confidence it reports).",
             choices: ["auto", "heuristic", "llm", "jev"],
             alias: "classifier-strategy",
         },

package/dist/constants/contextWindows.d.ts

@@ -11,6 +11,13 @@
  * - Others: Provider documentation as of Feb 2026
  */
 export { stripBedrockGeoPrefix } from "./bedrockIdentifiers.js";
+/**
+ * The output-token ceiling a JSON-catalog provider declares for one model, or
+ * undefined when the provider is not a catalog provider, the model is not
+ * listed, or the listing records no maxOutputTokens for it. Never falls back
+ * to the provider-wide default (see {@link CATALOG_OUTPUT_CEILINGS}).
+ */
+export declare function getCatalogOutputCeiling(provider: string, model?: string): number | undefined;
 /** Default context window when provider/model is unknown */
 export declare const DEFAULT_CONTEXT_WINDOW = 128000;
 /** Maximum output reserve when maxTokens not specified */

package/dist/constants/contextWindows.js

@@ -37,6 +37,54 @@ const CATALOG_CONTEXT_WINDOWS = Object.fromEntries(getCatalogJsonEntries().map((
             : [])),
     },
 ]));
+/**
+ * Per-model output-token ceilings for the JSON-catalog providers, derived
+ * from models.catalog[*].maxOutputTokens and keyed by lowercased provider id
+ * and alias. Each provider's map holds every model id as written plus its
+ * lowercased form, so a lookup tries the exact spelling first.
+ *
+ * Deliberately NOT models.defaultMaxOutputTokens: for about 28 catalog
+ * providers (groq, xai, together-ai, fireworks, perplexity, cloudflare,
+ * mistral ...) that is a generic 4096 placeholder (see manifestRegistry.ts),
+ * far below the real ceilings of their models. A model with no recorded
+ * maxOutputTokens has no entry here, so it is never capped by a guess.
+ */
+const CATALOG_OUTPUT_CEILINGS = new Map(getCatalogJsonEntries().flatMap((entry) => {
+    const ceilings = Object.entries(entry.models.catalog).flatMap(([modelId, spec]) => spec.maxOutputTokens !== undefined &&
+        Number.isFinite(spec.maxOutputTokens) &&
+        spec.maxOutputTokens > 0
+        ? [[modelId, spec.maxOutputTokens]]
+        : []);
+    if (ceilings.length === 0) {
+        return [];
+    }
+    // Lowercased spellings go in first so an exact id always overrides a
+    // case-folded one; two ids differing only by case keep the smaller cap.
+    const byModel = new Map();
+    for (const [modelId, ceiling] of ceilings) {
+        const folded = modelId.toLowerCase();
+        byModel.set(folded, Math.min(byModel.get(folded) ?? ceiling, ceiling));
+    }
+    for (const [modelId, ceiling] of ceilings) {
+        byModel.set(modelId, ceiling);
+    }
+    return [entry.id, ...entry.aliases].map((name) => [name.toLowerCase(), byModel]);
+}));
+/**
+ * The output-token ceiling a JSON-catalog provider declares for one model, or
+ * undefined when the provider is not a catalog provider, the model is not
+ * listed, or the listing records no maxOutputTokens for it. Never falls back
+ * to the provider-wide default (see {@link CATALOG_OUTPUT_CEILINGS}).
+ */
+export function getCatalogOutputCeiling(provider, model) {
+    // getSafeMaxTokens has always tolerated a missing provider, so this lookup
+    // must too (callers outside the typed option normalisers can pass one).
+    if (!model || typeof provider !== "string") {
+        return undefined;
+    }
+    const ceilings = CATALOG_OUTPUT_CEILINGS.get(provider.toLowerCase());
+    return ceilings?.get(model) ?? ceilings?.get(model.toLowerCase());
+}
 /** Default context window when provider/model is unknown */
 export const DEFAULT_CONTEXT_WINDOW = 128_000;
 /** Maximum output reserve when maxTokens not specified */

package/dist/constants/enums.d.ts

@@ -85,6 +85,7 @@ export declare enum AIProviderName {
     SAKANA_AI = "sakana-ai",
     SAMBANOVA = "sambanova",
     SARVAM = "sarvam",
+    SCALEDOWN = "scaledown",
     SCALEWAY = "scaleway",
     SILICONFLOW = "siliconflow",
     STACKIT = "stackit",
@@ -1570,6 +1571,10 @@ export declare enum SarvamModels {
     SARVAM_105B = "sarvam-105b",
     SARVAM_105B_CONVERSATIONS = "sarvam-105b-conversations"
 }
+export declare enum ScaleDownModels {
+    CLASSIFY_1 = "classify-1",
+    CLASSIFY = "classify"
+}
 export declare enum ScalewayModels {
     MISTRAL_SMALL_3_2_24B_INSTRUCT_2506 = "mistral-small-3.2-24b-instruct-2506",
     LLAMA_3_3_70B_INSTRUCT = "llama-3.3-70b-instruct",

package/dist/constants/enums.js

@@ -90,6 +90,7 @@ export var AIProviderName;
     AIProviderName["SAKANA_AI"] = "sakana-ai";
     AIProviderName["SAMBANOVA"] = "sambanova";
     AIProviderName["SARVAM"] = "sarvam";
+    AIProviderName["SCALEDOWN"] = "scaledown";
     AIProviderName["SCALEWAY"] = "scaleway";
     AIProviderName["SILICONFLOW"] = "siliconflow";
     AIProviderName["STACKIT"] = "stackit";
@@ -1875,6 +1876,11 @@ export var SarvamModels;
     SarvamModels["SARVAM_105B"] = "sarvam-105b";
     SarvamModels["SARVAM_105B_CONVERSATIONS"] = "sarvam-105b-conversations";
 })(SarvamModels || (SarvamModels = {}));
+export var ScaleDownModels;
+(function (ScaleDownModels) {
+    ScaleDownModels["CLASSIFY_1"] = "classify-1";
+    ScaleDownModels["CLASSIFY"] = "classify";
+})(ScaleDownModels || (ScaleDownModels = {}));
 export var ScalewayModels;
 (function (ScalewayModels) {
     ScalewayModels["MISTRAL_SMALL_3_2_24B_INSTRUCT_2506"] = "mistral-small-3.2-24b-instruct-2506";

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/factories/providerDescriptors.js

@@ -469,18 +469,22 @@ const HAND_DESCRIPTORS = [
     },
     // Decision precedence is decideOrder, not position: typesafe 1, laya 2 and
     // xor 3 (from catalog/laya.json and catalog/xor.json), subq 4 (from
-    // catalog/subq.json), perplexity-decider 5, cloudflare-clef 6 and
-    // openai-decisions 7 (catalog/openai-decisions.json).
+    // catalog/subq.json), perplexity-decider 5, cloudflare-clef 6,
+    // openai-decisions 7 (catalog/openai-decisions.json) and scaledown 8
+    // (catalog/scaledown.json).
     // resolveDefaultDecisionProvider() returns the first configured
     // DECISION_PROVIDERS entry in that order, so a host configured for several
     // keeps Jev for every built-in consumer and reaches the others only by
     // naming them. Renumbering silently changes which model routes, compacts
     // and plans for every such host.
-    // perplexity-decider, cloudflare-clef and openai-decisions come last because
-    // each shares its environment key with a text provider: a key set only for
-    // that text provider must not displace a decision provider a host set up on
+    // perplexity-decider, cloudflare-clef and openai-decisions come after subq
+    // because each shares its environment key with a text provider: a key set only
+    // for that text provider must not displace a decision provider a host set up on
     // purpose. subq is ahead of them only because SUBQ_API_KEY belongs to no other
-    // provider.
+    // provider. scaledown is last by the owner's decision of 2026-10-15, not by
+    // that rule: SCALEDOWN_API_KEY belongs to no other provider either, so an
+    // ambient OPENAI_API_KEY, PERPLEXITY_API_KEY or Cloudflare pair outranks a
+    // ScaleDown key a host set on purpose, and ScaleDown is reached by naming it.
     {
         name: AIProviderName.PERPLEXITY_DECIDER,
         aliases: [],
@@ -552,9 +556,9 @@ const HAND_DESCRIPTORS = [
         credentialsKey: "cloudflareClef",
         envVars: {
             // The same token and account id the `cloudflare` text provider reads, so
-            // ambient Workers AI settings configure this provider too. It sits last
-            // in this list, which is what keeps that from displacing any other
-            // decision provider a host has configured.
+            // ambient Workers AI settings configure this provider too. Its place in
+            // the decision order (see the comment above) keeps that from displacing
+            // TypeSafe, Laya, XOR or SubQ.
             apiKey: "CLOUDFLARE_API_KEY",
             // Cloudflare's own API is the endpoint, so a base URL is optional; but
             // the path carries the account id, so a token alone is useless. Both are

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;