@stackfactor/agent-utils 1.2.11 → 1.2.14

package/README.md

@@ -300,3 +300,7 @@ The `config` object accepted by LangChain methods supports the following keys:
 ## License
 
 Not licensed — proprietary software of StackFactor Inc.
+
+## Development and release
+
+See [docs/README.md](docs/README.md) — branch flow, how to cut a release, and troubleshooting.

package/dist/cjs/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBA6lB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAstBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA1/B8B,GAAG,KAAG,MAAM;+CA/jB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCA+kBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAiiCT,wBASE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAktB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA//B8B,GAAG,KAAG,MAAM;+CAprB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAosBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAsiCT,wBASE"}

package/dist/cjs/langChain.js

@@ -12,7 +12,8 @@ const const_js_1 = __importDefault(require("./const.js"));
 const langchain_1 = require("langchain");
 const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
-const zod_to_json_schema_1 = require("zod-to-json-schema");
+const zod_1 = require("zod");
+const transform_json_schema_1 = require("@anthropic-ai/sdk/lib/transform-json-schema");
 const runtimeContext_js_1 = require("./runtimeContext.js");
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
@@ -23,6 +24,74 @@ CRITICAL - Your response must be valid JSON. Escape ALL special characters in st
 - Backslashes → \\\\
 Do NOT include raw newlines, tabs, or unescaped quotes inside JSON string values.
 `.trim();
+/**
+ * Providers for which `getLLMModel` configures native, schema-constrained JSON
+ * output (OpenAI `response_format`, Anthropic `output_config.format`, Gemini
+ * `responseSchema` + JSON mode). For these the model emits JSON directly, so the
+ * prompt-injected schema and the schema-validation retry are skipped. Other
+ * providers (DeepSeek/Kimi/GLM via the OpenAI-compatible shim) have no native
+ * support here and continue to rely on prompt instructions + validation.
+ * @param modelName - The model identifier being routed
+ * @returns `true` when native structured output is wired up for the provider
+ */
+const supportsNativeSchema = (modelName) => modelName.startsWith("gpt-") ||
+    modelName.startsWith("claude-") ||
+    modelName.startsWith("gemini-");
+/**
+ * Converts a Zod v4 schema to a JSON Schema using zod's built-in
+ * `z.toJSONSchema`. The classic `zod-to-json-schema` package only understands
+ * zod v3 and silently returns `{}` for v4 schemas, which would send empty
+ * schemas to every provider. Targets OpenAPI 3.0 — the dialect omits the
+ * `$schema` keyword and is the widest-compatible across providers — and inlines
+ * reused subschemas so the result carries no `$ref`/`$defs` (which Gemini's
+ * `responseSchema` rejects).
+ * @param schema - A Zod schema
+ * @returns The equivalent JSON Schema object
+ */
+const buildJsonSchema = (schema) => zod_1.z.toJSONSchema(schema, { target: "openapi-3.0", reused: "inline" });
+/**
+ * Recursively enforces OpenAI strict structured-output rules on a JSON Schema:
+ * every object gets `additionalProperties: false` and lists all of its
+ * properties in `required`. OpenAI's `strict: true` mode rejects optional
+ * properties, so all fields are marked required (matching OpenAI's own schema
+ * transform). Mutates and returns the schema.
+ * @param s - A JSON Schema object (mutated in place)
+ * @returns The same object, made strict-compatible
+ */
+const strictifyJsonSchema = (s) => {
+    if (!s || typeof s !== "object")
+        return s;
+    if (s.type === "object" && s.properties) {
+        s.additionalProperties = false;
+        s.required = Object.keys(s.properties);
+        for (const key of Object.keys(s.properties)) {
+            strictifyJsonSchema(s.properties[key]);
+        }
+    }
+    if (s.type === "array" && s.items)
+        strictifyJsonSchema(s.items);
+    return s;
+};
+/**
+ * Recursively removes JSON Schema keywords that Google Gemini's `responseSchema`
+ * (an OpenAPI 3.0 subset) rejects — notably `additionalProperties`, which the
+ * API returns a 400 for. Mutates and returns the schema.
+ * @param s - A JSON Schema object (mutated in place)
+ * @returns The same object, accepted by Gemini's `responseSchema`
+ */
+const sanitizeGeminiSchema = (s) => {
+    if (!s || typeof s !== "object")
+        return s;
+    delete s.additionalProperties;
+    if (s.properties) {
+        for (const key of Object.keys(s.properties)) {
+            sanitizeGeminiSchema(s.properties[key]);
+        }
+    }
+    if (s.items)
+        sanitizeGeminiSchema(s.items);
+    return s;
+};
 const checkIfAIProviderConfigured = (config) => {
     if (!config ||
         !config.openAIAPIKey ||
@@ -469,28 +538,102 @@ const getOpenAICompatibleProvider = (modelName, config) => {
     }
     return null;
 };
+/**
+ * Whether a model accepts the `temperature` sampling parameter at all. Some
+ * models reject it with an HTTP 400, so it must be omitted rather than clamped:
+ *  - Anthropic removed sampling params (temperature/top_p/top_k) on Claude
+ *    Opus 4.7 and later (Opus 4.7/4.8) and on the 5-series (Sonnet 5, Fable 5,
+ *    Mythos 5). Opus 4.6, Sonnet 4.6, claude-3-5-sonnet, and Haiku 4.5 still
+ *    accept it.
+ *  - OpenAI reasoning models (the GPT-5 family and the o-series) reject it;
+ *    gpt-4o still accepts it.
+ * DeepSeek, Kimi/Moonshot, GLM, and Gemini all accept temperature.
+ * @param modelName - the model identifier being routed
+ * @returns `true` when the model accepts a `temperature` parameter
+ */
+const modelSupportsTemperature = (modelName) => {
+    if (!modelName)
+        return false;
+    // OpenAI reasoning families reject sampling params (gpt-5*, o1/o3/...).
+    if (/^gpt-5/.test(modelName) || /^o\d/.test(modelName))
+        return false;
+    // Anthropic dropped sampling params on Opus 4.7+ and the 5-series.
+    if (/^claude-opus-4-(7|8|9|\d\d)\b/.test(modelName))
+        return false;
+    if (/^claude-(sonnet|opus|haiku)-5\b/.test(modelName))
+        return false;
+    if (/^claude-(fable|mythos)-5\b/.test(modelName))
+        return false;
+    return true;
+};
+/**
+ * Per-provider valid `temperature` range, used to clamp caller-supplied values.
+ * Anthropic, Kimi (Moonshot), and GLM (Zhipu) cap at 1.0; OpenAI, Gemini, and
+ * DeepSeek accept up to 2.0. Only consulted for models that support temperature
+ * at all (see `modelSupportsTemperature`).
+ */
+const getTemperatureRange = (modelName) => {
+    if (modelName.startsWith("claude-") ||
+        modelName.startsWith("kimi-") ||
+        modelName.startsWith("moonshot-") ||
+        modelName.startsWith("glm-")) {
+        return { min: 0, max: 1 };
+    }
+    // gpt-, gemini-, deepseek-
+    return { min: 0, max: 2 };
+};
+/**
+ * Resolves the `temperature` model setting for a given model. Applied in order:
+ *  1. presence/type — only a finite number is forwarded (`temperature: 0` is
+ *     valid; `undefined`/`null`/non-numeric leaves the provider default);
+ *  2. support — models that reject the parameter (Opus 4.7+, GPT-5/o-series)
+ *     get it omitted, with a warning, to avoid an HTTP 400;
+ *  3. range — values outside the provider's range are clamped, with a warning.
+ * Returns an object to spread into the LangChain model settings (`{}` when the
+ * field should be omitted).
+ */
+const resolveTemperatureSetting = (modelName, config) => {
+    const temperature = config?.temperature;
+    if (typeof temperature !== "number" || !Number.isFinite(temperature)) {
+        return {};
+    }
+    if (!modelSupportsTemperature(modelName)) {
+        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Model "${modelName}" does not accept a temperature parameter; ignoring configured temperature ${temperature}.`);
+        return {};
+    }
+    const { min, max } = getTemperatureRange(modelName);
+    const clamped = Math.min(Math.max(temperature, min), max);
+    if (clamped !== temperature) {
+        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Temperature ${temperature} is outside the supported range [${min}, ${max}] for "${modelName}"; clamping to ${clamped}.`);
+    }
+    return { temperature: clamped };
+};
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model
  * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
  * `ChatGoogleGenerativeAI`, and `gpt-` maps to `ChatOpenAI`. DeepSeek (`deepseek-`),
  * Kimi/Moonshot (`kimi-`, `moonshot-`), and GLM/Zhipu (`glm-`) models are routed
  * through `ChatOpenAI` against each provider's OpenAI-compatible endpoint. When a Zod
- * `schema` is provided for a GPT model, native `response_format` with `json_schema` is
- * configured for structured output. Throws a `BAD_REQUEST` error for unrecognised
- * model names.
+ * `schema` is provided, native structured output is configured per provider: OpenAI
+ * via `response_format` with `json_schema`, Anthropic via `output_config.format`, and
+ * Gemini via JSON mode (`json: true`) plus `responseSchema`. In every case the model
+ * emits JSON as the message text, so the caller's parse/validate pipeline is unchanged.
+ * The schema is ignored for the OpenAI-compatible providers (DeepSeek/Kimi/GLM), which
+ * have no native structured-output support here. Throws a `BAD_REQUEST` error for
+ * unrecognised model names.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`, `"deepseek-chat"`, `"kimi-k2-0905-preview"`, `"glm-4.6"`
  * @param config - Configuration object containing API keys (`openAIAPIKey`,
  *   `anthropicAPIKey`, `googleAPIKey`, `deepSeekAPIKey`, `kimiAPIKey`, `glmAPIKey`),
  *   optional `maxTokens`, and optional `temperature`
- * @param schema - Optional Zod schema used to configure structured JSON output for
- *   OpenAI GPT models via `response_format`; ignored for other providers
- * @returns A configured LangChain chat model instance
+ * @param schema - Optional Zod schema used to configure native structured JSON output
+ *   for GPT / Claude / Gemini models; ignored for OpenAI-compatible providers
+ * @returns A configured LangChain chat model (or bound runnable) instance
  */
 const getLLMModel = (modelName, config, schema = null) => {
-    const modelSettings = {
-        ...(config.temperature ? { temperature: config.temperature } : {}),
-    };
+    // Resolve `temperature` with presence/support/range handling (see
+    // resolveTemperatureSetting). Applied uniformly to every provider below.
+    const modelSettings = resolveTemperatureSetting(modelName, config);
     // Claude models (Anthropic)
     if (modelName.startsWith("claude-")) {
         // Anthropic's SDK rejects non-streamed requests when max_tokens is large
@@ -499,23 +642,53 @@ const getLLMModel = (modelName, config, schema = null) => {
         // through the streaming endpoint internally — callers see no interface
         // change, but the guard is bypassed.
         const maxTokens = config.maxTokens || 16384;
+        // Native structured output: Anthropic's `output_config.format` constrains
+        // decoding to the schema while still emitting JSON as the message text, so
+        // the downstream streaming + parse/validate pipeline is unchanged.
+        // `transformJSONSchema` applies the same strict-schema normalisation
+        // (additionalProperties: false, required fields) that @langchain/anthropic
+        // uses internally, which the API requires.
+        const outputConfig = schema
+            ? {
+                outputConfig: {
+                    format: {
+                        type: "json_schema",
+                        schema: (0, transform_json_schema_1.transformJSONSchema)(zod_1.z.toJSONSchema(schema)),
+                    },
+                },
+            }
+            : {};
         return new anthropic_1.ChatAnthropic({
             apiKey: config.anthropicAPIKey,
             maxTokens,
             modelName: modelName,
             streaming: maxTokens > 16384,
             invocationKwargs: { cache_control: { type: "ephemeral" } },
+            ...outputConfig,
             ...modelSettings,
         });
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
-        return new google_genai_1.ChatGoogleGenerativeAI({
+        const model = new google_genai_1.ChatGoogleGenerativeAI({
             apiKey: config.googleAPIKey,
             maxOutputTokens: config.maxTokens || 200000,
             model: modelName,
+            // `json: true` forces responseMimeType=application/json, guaranteeing the
+            // model returns valid JSON text (never prose) for the parse pipeline.
+            ...(schema ? { json: true } : {}),
             ...modelSettings,
         });
+        // `responseSchema` additionally constrains the output shape. It is a
+        // call-time option (not a constructor field), so it is bound onto the model
+        // via `withConfig`. Gemini's schema is an OpenAPI 3.0 subset, so
+        // `additionalProperties` is stripped. Output stays text, so the
+        // parse/validate pipeline is unchanged.
+        if (schema) {
+            const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
+            return model.withConfig({ responseSchema: jsonSchema });
+        }
+        return model;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -527,7 +700,7 @@ const getLLMModel = (modelName, config, schema = null) => {
         };
         // Use native response_format with JSON schema for structured output
         if (schema) {
-            const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(schema, { target: "openApi3" });
+            const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
             openAISettings.modelKwargs = {
                 response_format: {
                     type: "json_schema",
@@ -1027,7 +1200,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
     }
     if (onProgressReport) {
         // Streaming mode: use server-side chunk-based progress for all models
-        const useNativeSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        const useNativeSchema = expectsJsonResponse && !!schema && supportsNativeSchema(modelName);
         const llm = getLLMModel(modelName, config, useNativeSchema ? schema : null);
         // Build messages with JSON instructions if needed
         let messagesToSend;
@@ -1036,7 +1209,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 ? "Respond with valid JSON."
                 : JSON_ESCAPE_INSTRUCTION;
             if (schema && !useNativeSchema) {
-                const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(schema, { target: "openApi3" });
+                const jsonSchema = buildJsonSchema(schema);
                 systemContent += `\n\nYour response MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
             }
             if (messages.length > 0 && messages[0].role === "system") {
@@ -1174,17 +1347,22 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         }
     }
     else {
-        // Non-streaming mode: use native response_format for OpenAI when schema is provided
-        const useNativeSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        // Non-streaming mode: use native structured output when the provider
+        // supports it (OpenAI/Anthropic/Gemini); otherwise fall back to prompt
+        // instructions + validation retry.
+        const useNativeSchema = expectsJsonResponse && !!schema && supportsNativeSchema(modelName);
         const llm = getLLMModel(modelName, config, useNativeSchema ? schema : null);
-        // Add escape instruction to help LLM produce valid JSON (only if expecting JSON)
-        // For non-OpenAI models with schema, also include schema in prompt as fallback
+        // Add escape instruction to help LLM produce valid JSON (only if expecting JSON).
+        // When native structured output is in use the model is already constrained,
+        // so a light instruction suffices and the schema is not re-injected.
         let messagesToSend;
         if (expectsJsonResponse) {
-            let systemContent = JSON_ESCAPE_INSTRUCTION;
-            // Include schema in prompt for non-OpenAI models (OpenAI uses native response_format)
-            if (schema && !modelName.startsWith("gpt-")) {
-                const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(schema, { target: "openApi3" });
+            let systemContent = useNativeSchema
+                ? "Respond with valid JSON."
+                : JSON_ESCAPE_INSTRUCTION;
+            // Include the schema in the prompt only when not using native output.
+            if (schema && !useNativeSchema) {
+                const jsonSchema = buildJsonSchema(schema);
                 systemContent += `\n\nYour response MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
             }
             if (messages.length > 0 && messages[0].role === "system") {

package/dist/esm/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBA6lB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAstBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA1/B8B,GAAG,KAAG,MAAM;+CA/jB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCA+kBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAiiCT,wBASE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAktB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA//B8B,GAAG,KAAG,MAAM;+CAprB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAosBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAsiCT,wBASE"}

package/dist/esm/langChain.js

@@ -7,7 +7,8 @@ import constants from "./const.js";
 import { createAgent as createLangChainAgent } from "langchain";
 import errorHandlingHelper from "./errorHandling.js";
 import logger from "./logger.js";
-import { zodToJsonSchema } from "zod-to-json-schema";
+import { z } from "zod";
+import { transformJSONSchema } from "@anthropic-ai/sdk/lib/transform-json-schema";
 import { getAbortSignal } from "./runtimeContext.js";
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
@@ -18,6 +19,74 @@ CRITICAL - Your response must be valid JSON. Escape ALL special characters in st
 - Backslashes → \\\\
 Do NOT include raw newlines, tabs, or unescaped quotes inside JSON string values.
 `.trim();
+/**
+ * Providers for which `getLLMModel` configures native, schema-constrained JSON
+ * output (OpenAI `response_format`, Anthropic `output_config.format`, Gemini
+ * `responseSchema` + JSON mode). For these the model emits JSON directly, so the
+ * prompt-injected schema and the schema-validation retry are skipped. Other
+ * providers (DeepSeek/Kimi/GLM via the OpenAI-compatible shim) have no native
+ * support here and continue to rely on prompt instructions + validation.
+ * @param modelName - The model identifier being routed
+ * @returns `true` when native structured output is wired up for the provider
+ */
+const supportsNativeSchema = (modelName) => modelName.startsWith("gpt-") ||
+    modelName.startsWith("claude-") ||
+    modelName.startsWith("gemini-");
+/**
+ * Converts a Zod v4 schema to a JSON Schema using zod's built-in
+ * `z.toJSONSchema`. The classic `zod-to-json-schema` package only understands
+ * zod v3 and silently returns `{}` for v4 schemas, which would send empty
+ * schemas to every provider. Targets OpenAPI 3.0 — the dialect omits the
+ * `$schema` keyword and is the widest-compatible across providers — and inlines
+ * reused subschemas so the result carries no `$ref`/`$defs` (which Gemini's
+ * `responseSchema` rejects).
+ * @param schema - A Zod schema
+ * @returns The equivalent JSON Schema object
+ */
+const buildJsonSchema = (schema) => z.toJSONSchema(schema, { target: "openapi-3.0", reused: "inline" });
+/**
+ * Recursively enforces OpenAI strict structured-output rules on a JSON Schema:
+ * every object gets `additionalProperties: false` and lists all of its
+ * properties in `required`. OpenAI's `strict: true` mode rejects optional
+ * properties, so all fields are marked required (matching OpenAI's own schema
+ * transform). Mutates and returns the schema.
+ * @param s - A JSON Schema object (mutated in place)
+ * @returns The same object, made strict-compatible
+ */
+const strictifyJsonSchema = (s) => {
+    if (!s || typeof s !== "object")
+        return s;
+    if (s.type === "object" && s.properties) {
+        s.additionalProperties = false;
+        s.required = Object.keys(s.properties);
+        for (const key of Object.keys(s.properties)) {
+            strictifyJsonSchema(s.properties[key]);
+        }
+    }
+    if (s.type === "array" && s.items)
+        strictifyJsonSchema(s.items);
+    return s;
+};
+/**
+ * Recursively removes JSON Schema keywords that Google Gemini's `responseSchema`
+ * (an OpenAPI 3.0 subset) rejects — notably `additionalProperties`, which the
+ * API returns a 400 for. Mutates and returns the schema.
+ * @param s - A JSON Schema object (mutated in place)
+ * @returns The same object, accepted by Gemini's `responseSchema`
+ */
+const sanitizeGeminiSchema = (s) => {
+    if (!s || typeof s !== "object")
+        return s;
+    delete s.additionalProperties;
+    if (s.properties) {
+        for (const key of Object.keys(s.properties)) {
+            sanitizeGeminiSchema(s.properties[key]);
+        }
+    }
+    if (s.items)
+        sanitizeGeminiSchema(s.items);
+    return s;
+};
 const checkIfAIProviderConfigured = (config) => {
     if (!config ||
         !config.openAIAPIKey ||
@@ -464,28 +533,102 @@ const getOpenAICompatibleProvider = (modelName, config) => {
     }
     return null;
 };
+/**
+ * Whether a model accepts the `temperature` sampling parameter at all. Some
+ * models reject it with an HTTP 400, so it must be omitted rather than clamped:
+ *  - Anthropic removed sampling params (temperature/top_p/top_k) on Claude
+ *    Opus 4.7 and later (Opus 4.7/4.8) and on the 5-series (Sonnet 5, Fable 5,
+ *    Mythos 5). Opus 4.6, Sonnet 4.6, claude-3-5-sonnet, and Haiku 4.5 still
+ *    accept it.
+ *  - OpenAI reasoning models (the GPT-5 family and the o-series) reject it;
+ *    gpt-4o still accepts it.
+ * DeepSeek, Kimi/Moonshot, GLM, and Gemini all accept temperature.
+ * @param modelName - the model identifier being routed
+ * @returns `true` when the model accepts a `temperature` parameter
+ */
+const modelSupportsTemperature = (modelName) => {
+    if (!modelName)
+        return false;
+    // OpenAI reasoning families reject sampling params (gpt-5*, o1/o3/...).
+    if (/^gpt-5/.test(modelName) || /^o\d/.test(modelName))
+        return false;
+    // Anthropic dropped sampling params on Opus 4.7+ and the 5-series.
+    if (/^claude-opus-4-(7|8|9|\d\d)\b/.test(modelName))
+        return false;
+    if (/^claude-(sonnet|opus|haiku)-5\b/.test(modelName))
+        return false;
+    if (/^claude-(fable|mythos)-5\b/.test(modelName))
+        return false;
+    return true;
+};
+/**
+ * Per-provider valid `temperature` range, used to clamp caller-supplied values.
+ * Anthropic, Kimi (Moonshot), and GLM (Zhipu) cap at 1.0; OpenAI, Gemini, and
+ * DeepSeek accept up to 2.0. Only consulted for models that support temperature
+ * at all (see `modelSupportsTemperature`).
+ */
+const getTemperatureRange = (modelName) => {
+    if (modelName.startsWith("claude-") ||
+        modelName.startsWith("kimi-") ||
+        modelName.startsWith("moonshot-") ||
+        modelName.startsWith("glm-")) {
+        return { min: 0, max: 1 };
+    }
+    // gpt-, gemini-, deepseek-
+    return { min: 0, max: 2 };
+};
+/**
+ * Resolves the `temperature` model setting for a given model. Applied in order:
+ *  1. presence/type — only a finite number is forwarded (`temperature: 0` is
+ *     valid; `undefined`/`null`/non-numeric leaves the provider default);
+ *  2. support — models that reject the parameter (Opus 4.7+, GPT-5/o-series)
+ *     get it omitted, with a warning, to avoid an HTTP 400;
+ *  3. range — values outside the provider's range are clamped, with a warning.
+ * Returns an object to spread into the LangChain model settings (`{}` when the
+ * field should be omitted).
+ */
+const resolveTemperatureSetting = (modelName, config) => {
+    const temperature = config?.temperature;
+    if (typeof temperature !== "number" || !Number.isFinite(temperature)) {
+        return {};
+    }
+    if (!modelSupportsTemperature(modelName)) {
+        logger.log(null, logger.levels.warn, `Model "${modelName}" does not accept a temperature parameter; ignoring configured temperature ${temperature}.`);
+        return {};
+    }
+    const { min, max } = getTemperatureRange(modelName);
+    const clamped = Math.min(Math.max(temperature, min), max);
+    if (clamped !== temperature) {
+        logger.log(null, logger.levels.warn, `Temperature ${temperature} is outside the supported range [${min}, ${max}] for "${modelName}"; clamping to ${clamped}.`);
+    }
+    return { temperature: clamped };
+};
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model
  * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
  * `ChatGoogleGenerativeAI`, and `gpt-` maps to `ChatOpenAI`. DeepSeek (`deepseek-`),
  * Kimi/Moonshot (`kimi-`, `moonshot-`), and GLM/Zhipu (`glm-`) models are routed
  * through `ChatOpenAI` against each provider's OpenAI-compatible endpoint. When a Zod
- * `schema` is provided for a GPT model, native `response_format` with `json_schema` is
- * configured for structured output. Throws a `BAD_REQUEST` error for unrecognised
- * model names.
+ * `schema` is provided, native structured output is configured per provider: OpenAI
+ * via `response_format` with `json_schema`, Anthropic via `output_config.format`, and
+ * Gemini via JSON mode (`json: true`) plus `responseSchema`. In every case the model
+ * emits JSON as the message text, so the caller's parse/validate pipeline is unchanged.
+ * The schema is ignored for the OpenAI-compatible providers (DeepSeek/Kimi/GLM), which
+ * have no native structured-output support here. Throws a `BAD_REQUEST` error for
+ * unrecognised model names.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`, `"deepseek-chat"`, `"kimi-k2-0905-preview"`, `"glm-4.6"`
  * @param config - Configuration object containing API keys (`openAIAPIKey`,
  *   `anthropicAPIKey`, `googleAPIKey`, `deepSeekAPIKey`, `kimiAPIKey`, `glmAPIKey`),
  *   optional `maxTokens`, and optional `temperature`
- * @param schema - Optional Zod schema used to configure structured JSON output for
- *   OpenAI GPT models via `response_format`; ignored for other providers
- * @returns A configured LangChain chat model instance
+ * @param schema - Optional Zod schema used to configure native structured JSON output
+ *   for GPT / Claude / Gemini models; ignored for OpenAI-compatible providers
+ * @returns A configured LangChain chat model (or bound runnable) instance
  */
 const getLLMModel = (modelName, config, schema = null) => {
-    const modelSettings = {
-        ...(config.temperature ? { temperature: config.temperature } : {}),
-    };
+    // Resolve `temperature` with presence/support/range handling (see
+    // resolveTemperatureSetting). Applied uniformly to every provider below.
+    const modelSettings = resolveTemperatureSetting(modelName, config);
     // Claude models (Anthropic)
     if (modelName.startsWith("claude-")) {
         // Anthropic's SDK rejects non-streamed requests when max_tokens is large
@@ -494,23 +637,53 @@ const getLLMModel = (modelName, config, schema = null) => {
         // through the streaming endpoint internally — callers see no interface
         // change, but the guard is bypassed.
         const maxTokens = config.maxTokens || 16384;
+        // Native structured output: Anthropic's `output_config.format` constrains
+        // decoding to the schema while still emitting JSON as the message text, so
+        // the downstream streaming + parse/validate pipeline is unchanged.
+        // `transformJSONSchema` applies the same strict-schema normalisation
+        // (additionalProperties: false, required fields) that @langchain/anthropic
+        // uses internally, which the API requires.
+        const outputConfig = schema
+            ? {
+                outputConfig: {
+                    format: {
+                        type: "json_schema",
+                        schema: transformJSONSchema(z.toJSONSchema(schema)),
+                    },
+                },
+            }
+            : {};
         return new ChatAnthropic({
             apiKey: config.anthropicAPIKey,
             maxTokens,
             modelName: modelName,
             streaming: maxTokens > 16384,
             invocationKwargs: { cache_control: { type: "ephemeral" } },
+            ...outputConfig,
             ...modelSettings,
         });
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
-        return new ChatGoogleGenerativeAI({
+        const model = new ChatGoogleGenerativeAI({
             apiKey: config.googleAPIKey,
             maxOutputTokens: config.maxTokens || 200000,
             model: modelName,
+            // `json: true` forces responseMimeType=application/json, guaranteeing the
+            // model returns valid JSON text (never prose) for the parse pipeline.
+            ...(schema ? { json: true } : {}),
             ...modelSettings,
         });
+        // `responseSchema` additionally constrains the output shape. It is a
+        // call-time option (not a constructor field), so it is bound onto the model
+        // via `withConfig`. Gemini's schema is an OpenAPI 3.0 subset, so
+        // `additionalProperties` is stripped. Output stays text, so the
+        // parse/validate pipeline is unchanged.
+        if (schema) {
+            const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
+            return model.withConfig({ responseSchema: jsonSchema });
+        }
+        return model;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -522,7 +695,7 @@ const getLLMModel = (modelName, config, schema = null) => {
         };
         // Use native response_format with JSON schema for structured output
         if (schema) {
-            const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+            const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
             openAISettings.modelKwargs = {
                 response_format: {
                     type: "json_schema",
@@ -1022,7 +1195,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
     }
     if (onProgressReport) {
         // Streaming mode: use server-side chunk-based progress for all models
-        const useNativeSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        const useNativeSchema = expectsJsonResponse && !!schema && supportsNativeSchema(modelName);
         const llm = getLLMModel(modelName, config, useNativeSchema ? schema : null);
         // Build messages with JSON instructions if needed
         let messagesToSend;
@@ -1031,7 +1204,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 ? "Respond with valid JSON."
                 : JSON_ESCAPE_INSTRUCTION;
             if (schema && !useNativeSchema) {
-                const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+                const jsonSchema = buildJsonSchema(schema);
                 systemContent += `\n\nYour response MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
             }
             if (messages.length > 0 && messages[0].role === "system") {
@@ -1169,17 +1342,22 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         }
     }
     else {
-        // Non-streaming mode: use native response_format for OpenAI when schema is provided
-        const useNativeSchema = expectsJsonResponse && schema && modelName.startsWith("gpt-");
+        // Non-streaming mode: use native structured output when the provider
+        // supports it (OpenAI/Anthropic/Gemini); otherwise fall back to prompt
+        // instructions + validation retry.
+        const useNativeSchema = expectsJsonResponse && !!schema && supportsNativeSchema(modelName);
         const llm = getLLMModel(modelName, config, useNativeSchema ? schema : null);
-        // Add escape instruction to help LLM produce valid JSON (only if expecting JSON)
-        // For non-OpenAI models with schema, also include schema in prompt as fallback
+        // Add escape instruction to help LLM produce valid JSON (only if expecting JSON).
+        // When native structured output is in use the model is already constrained,
+        // so a light instruction suffices and the schema is not re-injected.
         let messagesToSend;
         if (expectsJsonResponse) {
-            let systemContent = JSON_ESCAPE_INSTRUCTION;
-            // Include schema in prompt for non-OpenAI models (OpenAI uses native response_format)
-            if (schema && !modelName.startsWith("gpt-")) {
-                const jsonSchema = zodToJsonSchema(schema, { target: "openApi3" });
+            let systemContent = useNativeSchema
+                ? "Respond with valid JSON."
+                : JSON_ESCAPE_INSTRUCTION;
+            // Include the schema in the prompt only when not using native output.
+            if (schema && !useNativeSchema) {
+                const jsonSchema = buildJsonSchema(schema);
                 systemContent += `\n\nYour response MUST conform to this JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`;
             }
             if (messages.length > 0 && messages[0].role === "system") {

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.2.11",
+  "version": "1.2.14",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -13,7 +13,12 @@
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && echo '{\"type\":\"module\"}' > dist/esm/package.json"
+    "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "work:start": "bash scripts/work-start.sh",
+    "work:commit": "bash scripts/work-commit.sh",
+    "work:release": "bash scripts/release.sh",
+    "release": "bash scripts/release.sh",
+    "release:fanout": "bash scripts/release-fanout.sh"
   },
   "repository": {
     "type": "git",
@@ -51,8 +56,7 @@
     "mongoose": "^9.3.1",
     "openai": "^6.32.0",
     "winston": "^3.19.0",
-    "zod": "^4.3.6",
-    "zod-to-json-schema": "^3.25.1"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "typescript": "^5.9.3"