@lenne.tech/nest-server 11.40.0 → 11.41.0

package/migration-guides/11.40.0-to-11.41.0.md

@@ -0,0 +1,118 @@
+# Migration Guide: 11.40.0 → 11.41.0
+
+> **Why a MINOR.** The MAJOR digit in this package tracks the NestJS major (11.x = NestJS 11), so it
+> is not ours to spend — every behaviour change of our own ships as a MINOR. This release changes
+> when the AI module asks an endpoint for JSON, which a project can notice.
+
+## Overview
+
+| Category | Effort | Applies to |
+|----------|--------|-----------|
+| **Behaviour change** | none | Projects using the AI module — three internal calls stop requesting JSON |
+| Bugfix | none | Everyone using the AI module — capability detection and context windows get more accurate |
+| New feature (opt-in) | none | `ai.maxRunMs` |
+| Internal | none | Nobody — a duplicate index declaration was removed |
+
+Most projects update with `pnpm update @lenne.tech/nest-server` and read no further. **Projects that
+do not use the AI module are unaffected by all of it.**
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+```bash
+# Do you use the AI module at all? If this is empty, you are done.
+grep -rn "CoreAiModule\|aiConnections\|AiTool" src/ 2>/dev/null
+```
+
+## Behaviour change: JSON mode is decided per PROMPT, not per connection
+
+### What changed
+
+A connection with `supportsJsonResponse: true` used to send `response_format: json_object` on
+**every** completion. It is now sent only when the call actually wants structured output.
+
+That was wrong in both directions, and the second one is why it is worth fixing rather than leaving:
+
+- The flag describes what the ENDPOINT can do, not what a given prompt NEEDS. A capability is not
+  an instruction.
+- It leaked into calls that must not be JSON. The final answer to the user, and the compaction step
+  that summarises a long conversation, both want prose — and both were being asked for JSON. The
+  compaction case is the visible one: it spliced JSON-wrapped summaries into the history that the
+  model then had to read back.
+
+### Do I need to do anything?
+
+**No.** There is deliberately no new option to pass: `jsonResponse` lives on `LlmCompletionOptions`,
+which is the PROVIDER-level contract, and the module sets it for itself. It is not a field on the
+prompt input, and nothing in a consumer project needs to change.
+
+Concretely, the narrowing is three call sites, all of which wanted prose and were being asked for
+JSON:
+
+| Call | Now |
+|------|-----|
+| The agent loop, on a connection with NATIVE tool calling | JSON mode off — the tools carry the structure |
+| The final answer to the user | never JSON |
+| Compaction (summarising a long conversation) | never JSON |
+
+A connection WITHOUT native tool calling is untouched: emulated tool calling is built on
+prompt-driven JSON, so those calls still request it.
+
+The one thing to know is the seam the fix deliberately leaves imperfect, because a project can reach
+it: the gate keys on native tool support, not on what the prompt asks for. A project that overrides
+the `native` prompt slot via `CoreAiSlotService` to request JSON anyway will have it narrowed off.
+That degrades gracefully rather than failing — prompt-driven JSON is the fallback the module is
+built around, and its extractor is lenient — but if you have such an override and see prose where
+you expected an object, this is why.
+
+A custom `ILlmProvider` needs no change either: `jsonResponse` is OPTIONAL, so an implementation
+that ignores it keeps compiling and keeps its previous behaviour.
+
+## Bugfixes (no action required)
+
+| Fix | What it was |
+|-----|-------------|
+| **Context window for two model families** | The known-model table matched by substring, so `ministral` did not match `mistral` and `mistral-medium` had no entry at all. Both fell back to the 8192 default instead of their real 131072 — silently truncating history on models that had 16x the room. Both are now listed |
+| **Capability probes recorded permanent false negatives** | A reasoning model spends output tokens on its thinking phase BEFORE emitting `tool_calls`. With the old few-token probe budget the endpoint answered `200` with `finish_reason: 'length'` and no tool call, which read as "native tools unsupported" — persisted, never re-probed, and the assistant degraded to emulated tool calling for good. The probe now budgets 256 tokens and retries once at 1024 before answering `false` |
+| **A thrown detection re-probed on every prompt** | A detection that threw left the capability `undefined`, and `undefined` is what triggers detection — so a transient endpoint blip fired an extra upstream completion before EVERY user prompt, ahead of the rate limiter and outside budget accounting. A 5-minute per-connection backoff now bounds it |
+| **Duplicate `tenantId` index** | Two AI models declared an index the `mongooseTenantPlugin` already creates, producing Mongoose "Duplicate schema index" warnings. Declaration removed; the index itself is unchanged and created by the plugin as before |
+
+## New: `ai.maxRunMs` (opt-in, off by default)
+
+A wall-clock ceiling for ONE prompt run, checked before each agent-loop iteration.
+
+```typescript
+ai: {
+  maxRunMs: 120000,   // 0 or omitted = no limit (previous behaviour)
+}
+```
+
+**Why it is worth setting.** Without it, a run's only bound is `maxIterations` multiplied by the
+connection's per-call timeout — 8 iterations at the 120 s default is a request that can legitimately
+hold a socket, its message buffer and a request context for 16 minutes, with compaction adding a
+call per iteration on top. Set it to something a client would actually wait for.
+
+A misconfigured value degrades to "no limit" rather than to an expired deadline: the check is
+`maxRunMs > 0`, and a non-numeric value arriving through `NSC__AI__MAX_RUN_MS` yields `NaN`, which
+fails that comparison. See `.claude/rules/configurable-features.md` → Numeric Sentinel, Family A.
+
+## Troubleshooting
+
+**"My final answer used to come back as JSON and now returns prose."** That is the behaviour change
+above, and it is the fix rather than a regression: the final answer was never meant to be JSON. If
+you were parsing it, parse the prose or move the structured part into a tool result, which is what
+tool calling is for.
+
+**"An endpoint that supported tools is suddenly using emulated tool calling."** That is the OLD
+defect, and it persisted the wrong flag. Clear the stored capability on the connection so it is
+re-probed with the new budget; detection now records `true` where it previously recorded a false
+negative.
+
+## Module Documentation
+
+- [AI module README](../src/core/modules/ai/README.md)
+- [AI integration checklist](../src/core/modules/ai/INTEGRATION-CHECKLIST.md)
+- [Configurable features](../.claude/rules/configurable-features.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.40.0",
+  "version": "11.41.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/interfaces/server-options.interface.ts

@@ -1901,6 +1901,23 @@ export interface IAi {
   /** Maximum number of agent-loop iterations (tool round-trips). @default 5 */
   maxIterations?: number;
 
+  /**
+   * Wall-clock ceiling for ONE prompt run, in milliseconds. Checked before each
+   * agent-loop iteration; once exceeded the run stops and answers with whatever it
+   * has (or the translated "no final answer" message).
+   *
+   * Without it the only bound is `maxIterations` multiplied by the connection's
+   * PER-CALL timeout — e.g. 8 iterations at the 120 s default is a request that can
+   * legitimately occupy a socket, its message buffer and a request context for 16
+   * minutes, and compaction can add a further call per iteration on top. Set this
+   * to something a client would actually wait for.
+   *
+   * `0` or omitted disables the check (previous behaviour).
+   *
+   * @default 0
+   */
+  maxRunMs?: number;
+
   /** Maximum characters of a tool-results payload fed back to the model. @default 12000 */
   maxToolResultChars?: number;
 

package/src/core/modules/ai/README.md

@@ -118,11 +118,32 @@ never probed). Detection runs in two complementary ways:
   warns — the stored value is never changed. OFF by default because it makes outbound calls to
   the LLM endpoints on every boot; also skipped in the ci/e2e runners.
 
-The probe is provider-agnostic best effort: `response_format: json_object` is sent
-(2xx → JSON supported); a trivial tool with `tool_choice: 'required'` is sent (2xx
-returning a `tool_calls` result → native tools supported; a `4xx` or a silent ignore
-→ unsupported). Override `OpenAiCompatibleProvider.detectCapabilities()` for custom
-backends, or implement the optional `ILlmProvider.detectCapabilities()` in your own provider.
+The probe is provider-agnostic best effort, and a 2xx alone is never the verdict —
+a backend that does not implement a parameter typically ignores it and answers
+normally, which would persist a `true` it never earns:
+
+- **JSON:** `response_format: json_object` is sent and the CONTENT must actually
+  parse. A response truncated by the output budget (`finish_reason: 'length'`, empty
+  OR partial) proves nothing and is retried once with a larger budget before the
+  probe settles on `false`.
+- **Native tools:** a trivial tool with `tool_choice: 'required'` is sent; a
+  `tool_calls` result → supported, a `4xx` or a complete answer without tool calls →
+  unsupported, a truncation → the same one retry.
+
+Both probes run concurrently. Override `OpenAiCompatibleProvider.detectCapabilities()`
+for custom backends, or implement the optional `ILlmProvider.detectCapabilities()` in
+your own provider.
+
+> **`supportsJsonResponse` is a CONNECTION flag, but whether an answer must be JSON is
+> a property of the PROMPT.** The JSON output contract is carried only by the
+> `output_contract` / `tool_protocol_emulated` fragments (both `capability: 'emulated'`)
+> and by `plan_protocol`. A **native**-tools run receives none of them and is asked for
+> prose — attaching `response_format` on top is a contradiction the model can only
+> resolve by inventing a shape of its own, which then reaches the user as the answer.
+> The orchestrator therefore decides JSON mode per CALL, not per connection: pass
+> `jsonResponse: false` in `LlmCompletionOptions` from any call whose prompt asks for
+> prose. The option only ever NARROWS — it can never assert JSON mode for a connection
+> whose endpoint was not probed for it.
 
 ### Backend examples (external, local, CLI)
 

package/src/core/modules/ai/core-ai.controller.ts

@@ -96,7 +96,22 @@ export class CoreAiController {
     res.setHeader('Cache-Control', 'no-cache');
     res.setHeader('Connection', 'keep-alive');
     res.setHeader('Content-Type', 'text/event-stream');
+    // Disable proxy-side response buffering (nginx and friends honour this); without
+    // it an intermediary can hold the events until the response ends, which defeats
+    // the whole point of the stream.
+    res.setHeader('X-Accel-Buffering', 'no');
     res.flushHeaders?.();
+
+    // A prompt run can stay silent for a long time — a multi-step turn measured
+    // 30-40 s, and `ai.maxRunMs` allows up to two minutes. Many proxies close an
+    // idle connection at 60 s, which the client then sees as a turn that silently
+    // vanished. Comment frames are ignored by every SSE client and keep the
+    // connection observably alive.
+    const heartbeat = setInterval(() => {
+      res.write(': keep-alive\n\n');
+    }, 15_000);
+    heartbeat.unref?.();
+
     try {
       for await (const event of this.aiService.promptStream(input, serviceOptions)) {
         res.write(`data: ${JSON.stringify(event)}\n\n`);
@@ -104,6 +119,7 @@ export class CoreAiController {
     } catch (err) {
       res.write(`data: ${JSON.stringify({ message: (err as Error).message, type: 'error' })}\n\n`);
     } finally {
+      clearInterval(heartbeat);
       res.end();
     }
   }

package/src/core/modules/ai/interfaces/llm-provider.interface.ts

@@ -108,6 +108,21 @@ export interface LlmUsage {
  * when omitted.
  */
 export interface LlmCompletionOptions {
+  /**
+   * Set `false` to suppress structured-JSON mode for THIS call even though the
+   * connection advertises `supportsJsonResponse`.
+   *
+   * Narrowing only — it can never switch JSON mode ON for a connection whose
+   * endpoint was not probed for it, because the flag is measured per connection and
+   * asserting it elsewhere is what produces a 4xx nobody expected.
+   *
+   * It exists because `supportsJsonResponse` is CONNECTION state while whether an
+   * answer must be JSON is a property of the PROMPT. A caller that asks for prose —
+   * a summary, a native-tools chat turn, a plan summary — must be able to say so
+   * without rebuilding the connection object around the flag.
+   */
+  jsonResponse?: boolean;
+
   /** Maximum number of tokens to generate. */
   maxTokens?: number;
 

package/src/core/modules/ai/models/core-ai-prompt.model.ts

@@ -89,9 +89,18 @@ export class CoreAiPrompt extends CorePersistenceModel {
 
   /** Tenant id when scope = 'tenant' (set from the creator's tenant at create time). */
   @UnifiedField({
+    // No `index: true`: declaring the `tenantId` PATH is what activates
+    // `mongooseTenantPlugin`, and the plugin then adds `schema.index({ tenantId: 1 })`
+    // itself. Declaring it here as well makes Mongoose log
+    // "Duplicate schema index on {"tenantId":1}" on every boot.
+    //
+    // The `mongoose` key itself MUST stay: `UnifiedField` emits `@Prop` only inside
+    // `if (opts.mongoose)`, so dropping the whole key would remove the schema path —
+    // and `mongooseTenantPlugin` returns early on `!schema.path('tenantId')`, i.e.
+    // the model would lose its tenant filtering entirely.
     description: 'Tenant id (when scope = "tenant")',
     isOptional: true,
-    mongoose: { index: true },
+    mongoose: { type: String },
     roles: RoleEnum.S_USER,
   })
   tenantId?: string = undefined;

package/src/core/modules/ai/models/core-ai-slot.model.ts

@@ -133,9 +133,18 @@ export class CoreAiSlot extends CorePersistenceModel {
    * slot is effectively system-wide.
    */
   @UnifiedField({
+    // No `index: true`: declaring the `tenantId` PATH is what activates
+    // `mongooseTenantPlugin`, and the plugin then adds `schema.index({ tenantId: 1 })`
+    // itself. Declaring it here as well makes Mongoose log
+    // "Duplicate schema index on {"tenantId":1}" on every boot.
+    //
+    // The `mongoose` key itself MUST stay: `UnifiedField` emits `@Prop` only inside
+    // `if (opts.mongoose)`, so dropping the whole key would remove the schema path —
+    // and `mongooseTenantPlugin` returns early on `!schema.path('tenantId')`, i.e.
+    // the model would lose its tenant filtering entirely.
     description: 'Tenant id the slot applies to (auto-set; undefined = system-wide)',
     isOptional: true,
-    mongoose: { index: true },
+    mongoose: { type: String },
     roles: RoleEnum.ADMIN,
   })
   tenantId?: string = undefined;

package/src/core/modules/ai/providers/openai-compatible.provider.ts

@@ -77,7 +77,18 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
         type: 'function',
       }));
     }
-    if (this.capabilities.jsonResponse) {
+    // A per-request `model` overrides the connection's — but the capability flags
+    // were probed against `connection.model` and persisted per CONNECTION, never
+    // per model. Applying them to a different model asserts something that was
+    // never measured: the endpoint may reject `response_format` for it, and the
+    // caller sees a transport error where it expected an answer. Fall back to the
+    // safe subset (prompt-driven JSON + defensive parsing) whenever the model the
+    // request actually targets is not the one the probe ran against.
+    // `options.jsonResponse === false` narrows this off for a single call — the way a
+    // caller whose PROMPT asks for prose says so. It can only ever narrow: the flag
+    // was measured against this connection, so no option may assert it where the
+    // probe never ran.
+    if (this.capabilities.jsonResponse && options?.jsonResponse !== false && body.model === this.connection.model) {
       body.response_format = { type: 'json_object' };
     }
 
@@ -162,6 +173,50 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
     }
   }
 
+  /**
+   * Output budget for the native-tool probe.
+   *
+   * A reasoning model spends output tokens on its thinking phase BEFORE it emits
+   * `tool_calls`. With a budget of a few tokens the endpoint answers `200` with
+   * `finish_reason: 'length'` and no tool call at all — which the probe used to read
+   * as "native tools unsupported", persisting a false negative that is never
+   * re-probed and degrades the assistant to emulated tool calling for good.
+   *
+   * Measured against an OpenAI-compatible hosting endpoint on 2026-07-25
+   * (`tool_choice: 'required'` plus a trivial `ping` tool, varying only
+   * `max_tokens`):
+   *
+   * | model                    |  8 | 64 | 256 |
+   * |--------------------------|----|----|-----|
+   * | Ministral-3-14B-Instruct | ✅ | ✅ | ✅  |
+   * | Mistral-Medium-3.5-128B  | ✅ | ✅ | ✅  |
+   * | gpt-oss-120b             | ❌ | ✅ | ✅  |
+   * | Qwen3.5-122B-A10B-FP8    | ❌ | ✅ | ✅  |
+   * | Qwen3.6-35B-A3B-FP8      | ❌ | ❌ | ✅  |
+   *
+   * 256 covers every model tested and costs a few hundred tokens ONCE per
+   * connection, which is nothing against the cost of the wrong flag.
+   */
+  protected static readonly NATIVE_TOOL_PROBE_MAX_TOKENS = 256;
+
+  /**
+   * Second and FINAL budget for the native-tool probe, used only when the first
+   * attempt came back truncated.
+   *
+   * The retry has to be bounded, and the bound has to live here. An inconclusive
+   * result leaves the capability `undefined`, `detectAndPersistCapabilities` only
+   * persists booleans, and the orchestrator re-runs detection whenever a flag is
+   * undefined — so "just leave it undetected and try again later" would fire one
+   * extra upstream completion before EVERY user prompt, ahead of the rate limiter
+   * and outside any budget accounting. Two attempts, then a definite answer.
+   *
+   * Returning `false` after a model failed to emit a tool call within 1024 output
+   * tokens is not the false negative this fix exists to prevent: a model that needs
+   * more than that before its first tool call cannot drive an agent loop usefully
+   * anyway, and emulated tool calling is the correct fallback for it.
+   */
+  protected static readonly NATIVE_TOOL_PROBE_MAX_TOKENS_RETRY = 1024;
+
   /**
    * The configured egress allowlist as a lowercase array, whatever shape it has.
    *
@@ -221,27 +276,162 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
   /**
    * Probe the backend to auto-detect capabilities for flags the connection left
    * undefined. Explicit flags are authoritative and are NOT probed. Best effort:
-   * - JSON: send `response_format: json_object`; 2xx → true, 4xx → false.
+   * - JSON: send `response_format: json_object`; 2xx AND content that actually
+   *   parses as JSON → true. A 2xx alone is not evidence — a backend that does not
+   *   implement `response_format` simply ignores the field and answers normally.
    * - Native tools: send a trivial tool with `tool_choice: 'required'`; 2xx WITH a
-   *   `tool_calls` result → true, otherwise → false (a backend that silently ignores
-   *   tools returns no tool_calls and is treated as unsupported).
+   *   `tool_calls` result → true. A backend that answers fully but silently ignores
+   *   the tools returns no tool_calls and IS a real negative. A response truncated
+   *   by the token budget (`finish_reason: 'length'` without tool_calls) proves
+   *   nothing, so it is retried ONCE with
+   *   {@link NATIVE_TOOL_PROBE_MAX_TOKENS_RETRY}; a second truncation resolves to
+   *   `false`.
+   *
+   * This method always returns a definite boolean for a flag it probed. That is
+   * deliberate: an `undefined` result is not persisted by
+   * `detectAndPersistCapabilities`, and the orchestrator re-runs detection whenever
+   * a flag is undefined — so an endpoint that keeps truncating would trigger one
+   * extra upstream completion before every user prompt, ahead of the rate limiter
+   * and outside budget accounting.
    *
    * Throws on a transport error so callers can treat the connection as undetected
    * (and retry later) rather than persisting a wrong value.
    */
   async detectCapabilities(): Promise<{ jsonResponse?: boolean; nativeTools?: boolean }> {
+    const needsJson = this.connection.supportsJsonResponse === undefined;
+    const needsTools = this.connection.supportsNativeTools === undefined;
+    // Independent upstream calls, so run them together. This matters more since both
+    // probes gained a truncation retry: sequentially, a fresh connection can now cost
+    // FOUR round trips before the user's own completion starts — and lazy detection
+    // sits inline on the interactive prompt path.
+    const [jsonResponse, nativeTools] = await Promise.all([
+      needsJson ? this.probeJsonResponse() : Promise.resolve(undefined),
+      needsTools ? this.probeNativeTools() : Promise.resolve(undefined),
+    ]);
     const result: { jsonResponse?: boolean; nativeTools?: boolean } = {};
-    if (this.connection.supportsJsonResponse === undefined) {
+    if (needsJson) {
+      result.jsonResponse = jsonResponse;
+    }
+    if (needsTools) {
+      result.nativeTools = nativeTools;
+    }
+    return result;
+  }
+
+  /**
+   * Probe structured-JSON support.
+   *
+   * A 2xx alone is NOT evidence: a backend that does not implement
+   * `response_format` typically ignores the unknown field and answers normally, so
+   * trusting the status code alone persists `supportsJsonResponse: true` for an
+   * endpoint that never honours it — after which `chat()` sends `response_format`
+   * on every single call. Like the native-tool flag this is written once and never
+   * re-probed, so the wrong value is permanent.
+   *
+   * The response content must therefore actually parse as JSON. The budget matches
+   * the tool probe for the same reason: a reasoning model needs room to get past
+   * its thinking phase before it emits anything parseable — INCLUDING the tool
+   * probe's retry on truncation, which this probe needs just as badly.
+   *
+   * Measured against an OpenAI-compatible hosting endpoint on 2026-09-03 (this
+   * same probe, varying only `max_tokens`; the number is the completion tokens the
+   * model actually spent):
+   *
+   * | model                         | 256          | 1024   |
+   * |-------------------------------|--------------|--------|
+   * | Ministral-3-14B-Instruct-2512 | ✅ 9         | —      |
+   * | gpt-oss-120b                  | ✅ 88        | —      |
+   * | Qwen3.6-35B-A3B-FP8           | ✅ 202       | —      |
+   * | Mistral-Medium-3.5-128B       | ❌ truncated | ✅ 878 |
+   * | Qwen3.5-122B-A10B-FP8         | ❌ truncated | ✅ 365 |
+   *
+   * TWO of five need the retry — so without it the probe records "structured JSON
+   * unsupported" for an endpoint that demonstrably supports it.
+   *
+   * That false negative costs on two different paths, and the expensive one is the
+   * quiet one. `detectAndPersistCapabilities` WRITES what the probe returns, and a
+   * written flag is authoritative and never re-probed — so a fresh connection whose
+   * flags are unset is pinned to the wrong `false` for good, silently falling back
+   * to prompt-driven JSON. The loud path is the `ai.capabilityDriftCheck` boot
+   * warning (`supportsJsonResponse declared true but the endpoint reports false`),
+   * which merely reads as endpoint drift and sends the next reader hunting for one
+   * — which is how this was found. Note the warning fires only where that
+   * opt-in check is enabled, while the persisted flag is wrong everywhere.
+   *
+   * A COMPLETE answer that merely is not JSON stays a real negative: the endpoint
+   * ignored `response_format`, and a larger budget cannot change that.
+   */
+  protected async probeJsonResponse(): Promise<boolean> {
+    const budgets = [
+      OpenAiCompatibleProvider.NATIVE_TOOL_PROBE_MAX_TOKENS,
+      OpenAiCompatibleProvider.NATIVE_TOOL_PROBE_MAX_TOKENS_RETRY,
+    ];
+
+    for (const [attempt, maxTokens] of budgets.entries()) {
       const res = await this.probe({
-        max_tokens: 8,
+        max_tokens: maxTokens,
         messages: [{ content: 'Reply with the JSON object {"ok":true}.', role: 'user' }],
         response_format: { type: 'json_object' },
       });
-      result.jsonResponse = res.ok;
+      if (!res.ok) {
+        return false;
+      }
+      const choice = res.json?.choices?.[0];
+      const content = choice?.message?.content;
+      const truncated = choice?.finish_reason === 'length';
+      if (typeof content === 'string' && content.trim()) {
+        try {
+          JSON.parse(content);
+          return true;
+        } catch {
+          // A parse failure is only a REAL negative when the model finished on its
+          // own terms. Truncation is the other reason JSON does not parse, and it
+          // arrives in two shapes depending on how the model emits: a reasoning
+          // model buffers behind its thinking phase and returns EMPTY content, while
+          // one that streams directly returns a partial body like `{"ok":tr`. Both
+          // are `finish_reason: 'length'`, and classifying the partial one here
+          // instead of retrying reaches the exact false negative this ladder exists
+          // to remove — just through the other door.
+          if (!truncated) {
+            this.logger.warn(
+              `JSON-response probe for model "${this.connection.model}" returned non-JSON content — ` +
+                'recording structured JSON as unsupported',
+            );
+            return false;
+          }
+        }
+      } else if (!truncated) {
+        // Empty content that finished on its own terms is a real negative.
+        return false;
+      }
+
+      const isLastAttempt = attempt === budgets.length - 1;
+      this.logger.warn(
+        `JSON-response probe for model "${this.connection.model}" was truncated (finish_reason=length) at ` +
+          `max_tokens=${maxTokens}` +
+          (isLastAttempt
+            ? ' on the final attempt — recording structured JSON as unsupported; a model that cannot emit a ' +
+              'trivial JSON object within a usable output budget is better served by the prompt-driven fallback'
+            : ' — retrying once with a larger budget'),
+      );
     }
-    if (this.connection.supportsNativeTools === undefined) {
+
+    return false;
+  }
+
+  /**
+   * Run the native-tool probe, escalating the output budget once on truncation.
+   * Extracted so the retry policy is overridable and testable on its own.
+   */
+  protected async probeNativeTools(): Promise<boolean> {
+    const budgets = [
+      OpenAiCompatibleProvider.NATIVE_TOOL_PROBE_MAX_TOKENS,
+      OpenAiCompatibleProvider.NATIVE_TOOL_PROBE_MAX_TOKENS_RETRY,
+    ];
+
+    for (const [attempt, maxTokens] of budgets.entries()) {
       const res = await this.probe({
-        max_tokens: 8,
+        max_tokens: maxTokens,
         messages: [{ content: 'Call the ping tool.', role: 'user' }],
         tool_choice: 'required',
         tools: [
@@ -255,9 +445,29 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
           },
         ],
       });
-      result.nativeTools = res.ok && !!res.json?.choices?.[0]?.message?.tool_calls?.length;
+      const choice = res.json?.choices?.[0];
+
+      if (res.ok && choice?.message?.tool_calls?.length) {
+        return true;
+      }
+      // A non-2xx, or a complete answer without tool calls, is a REAL negative —
+      // retrying with a bigger budget would not change it.
+      if (!res.ok || choice?.finish_reason !== 'length') {
+        return false;
+      }
+
+      const isLastAttempt = attempt === budgets.length - 1;
+      this.logger.warn(
+        `Native-tool probe for model "${this.connection.model}" was truncated (finish_reason=length) at ` +
+          `max_tokens=${maxTokens}` +
+          (isLastAttempt
+            ? ' on the final attempt — recording native tools as unsupported; the model does not reach a tool ' +
+              'call within a usable output budget, so emulated tool calling is the correct fallback'
+            : ' — retrying once with a larger budget'),
+      );
     }
-    return result;
+
+    return false;
   }
 
   /**
@@ -306,7 +516,18 @@ export class OpenAiCompatibleProvider implements ILlmProvider {
         128_000,
         ['gpt-4o', 'gpt-4.1', 'gpt-4-turbo', 'o1', 'o3', 'gpt-oss', 'mistral-large', 'mistral-small3', 'command-r'],
       ],
-      [131_072, ['qwen2.5', 'qwen3', 'llama-3.1', 'llama3.1', 'llama-3.3', 'llama3.3']],
+      // Two DIFFERENT gaps, both closed here (measured 2026-07-25 against an
+      // OpenAI-compatible hosting endpoint; both models verified to accept >=163k
+      // prompt tokens):
+      //   - `mistral-medium` DID match the generic `mistral` -> 32768 entry below,
+      //     capping a 256k model at an eighth of its window. It must therefore be
+      //     matched before it -- this bucket is evaluated first.
+      //   - `ministral` matched NOTHING at all: "ministral" does not contain the
+      //     substring "mistral" (m-i-n-i-s-t-r-a-l), so it fell through the whole
+      //     table to the conservative 8192 default.
+      // Pinned one power of two below the verified capacity so the orchestrator
+      // trims before the endpoint rejects.
+      [131_072, ['qwen2.5', 'qwen3', 'llama-3.1', 'llama3.1', 'llama-3.3', 'llama3.3', 'ministral', 'mistral-medium']],
       [65_536, ['mixtral']],
       [32_768, ['qwen2', 'mistral', 'gemma2', 'gemma-2']],
       [16_385, ['gpt-3.5']],