@lenne.tech/nest-server 11.39.0 → 11.41.0

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

@@ -0,0 +1,186 @@
+# Migration Guide: 11.39.0 → 11.40.0
+
+> **Why a MINOR for what looks like a patch.** In this package the MAJOR digit tracks the NestJS
+> major (11.x = NestJS 11), so it is not ours to spend — and every breaking change of our own ships
+> as a MINOR instead. This release contains one: a security control that was silently inert starts
+> being enforced, and a deployment that relied on the inert behaviour can stop working. The number
+> of affected projects is small; the rule does not ask how many, it asks whether a working
+> deployment can break.
+
+## Overview
+
+| Category | Effort | Applies to |
+|----------|--------|-----------|
+| **Breaking (behaviour)** | 5 minutes | Projects that set `ai.allowedBaseUrlHosts` **as a string** (i.e. via `NSC__AI__ALLOWED_BASE_URL_HOSTS`) |
+| Bugfix | none | Everyone using the AI module |
+| Internal tooling | none | Nobody — `scripts/` does not ship |
+
+Almost every project can update with `pnpm update @lenne.tech/nest-server` and read no further.
+**One group cannot**, and for them the change is the uncomfortable kind: a security control that was
+silently inert starts working, and a working deployment can stop working as a result.
+
+## Quick Migration
+
+```bash
+# Does this affect you? If both come back empty, you are done.
+grep -r "NSC__AI__ALLOWED_BASE_URL_HOSTS" . --include="*.env*" --include="*.yml" --include="*.yaml" 2>/dev/null
+grep -rn "allowedBaseUrlHosts" src/ 2>/dev/null
+```
+
+## Breaking Change: `ai.allowedBaseUrlHosts` set as a string was never enforced
+
+### What was wrong
+
+`ai.allowedBaseUrlHosts` is the SSRF egress allowlist for AI connection base URLs. It is reachable
+through the framework's own environment mapping:
+
+```bash
+NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,api.openai.com
+```
+
+`getEnvironmentObject()` turns that into `{ ai: { allowedBaseUrlHosts: '<string>' } }`, and lodash
+`merge` assigns the scalar straight over the configured array.
+
+**And there is no way to avoid that from the environment.** The `NSC__*` reader coerces exactly
+three things — `'true'`, `'false'`, and anything `Number()` accepts — and leaves everything else a
+string. No CSV, JSON array literal or other notation produces an array:
+
+```bash
+NSC__AI__ALLOWED_BASE_URL_HOSTS='["a.example.com"]'   # -> the string '["a.example.com"]'
+NSC__AI__MAX_ITERATIONS=7                             # -> the number 7
+```
+
+So this is not an edge case for people who happened to pick the wrong notation. **If you configured
+the allowlist through the environment at all, it was off — completely, on every deployment, for its
+whole life.** Verified empirically against the built `config.helper.js`, not inferred from the code.
+Reported by the nest-server-starter session, which went looking for why a string arrives in the
+first place.
+
+That gives you a clean dividing line, and it is the only thing you need to check:
+
+| How you set `ai.allowedBaseUrlHosts` | Were you affected? |
+|---|---|
+| `NSC__AI__ALLOWED_BASE_URL_HOSTS` (or any env route) | **Yes — the control was inert** |
+| A real array in `config.env.ts` | No — it worked as documented |
+| Not set at all | No — no restriction was intended |
+
+The guard then did:
+
+```typescript
+if (!Array.isArray(allowedHosts) || !allowedHosts.length) {
+  return;   // read as "no allowlist configured"
+}
+```
+
+So a string was read as **"not configured"** and the check was skipped entirely — no log line, no
+error. An operator who used the canonical `NSC__` spelling (the documented form for every other
+setting) had **no egress restriction at all** while believing the control was on.
+
+### What changes in 11.40.0
+
+A string is now parsed as a comma-separated list, so the setting does what it says.
+
+**This is a behaviour change in the restrictive direction.** If you set it as a string, your
+deployment went from *no restriction* to *enforced*. Any AI connection whose host is not in that
+list now fails with `ServiceUnavailableException` and a WARN naming the host. There is no
+deprecation window, because leaving an SSRF control off for a release cycle is worse than the
+breakage.
+
+### Before upgrading
+
+1. Find the configured value:
+   ```bash
+   grep -r "NSC__AI__ALLOWED_BASE_URL_HOSTS" . --include="*.env*" --include="*.yml" 2>/dev/null
+   ```
+2. List every `baseUrl` your connections actually use — including any seeded via
+   `ai.defaultConnection`, and any added at runtime through `aiConnections`:
+   ```
+   query { aiConnections { name baseUrl enabled } }
+   ```
+3. Confirm every one of those hosts appears in the list. Add the missing ones, or clear the setting
+   entirely if you did not mean to restrict egress:
+   ```bash
+   NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,api.openai.com,localhost:11434
+   ```
+
+**Unset is still permissive**, unchanged — a local Ollama works out of the box.
+
+### Matching rules
+
+Worth reading once, because they are the likely cause of a surprising refusal:
+
+| Entry | Matches | Does not match |
+|-------|---------|----------------|
+| `llm.example.com` | any port on that host | `llm.example.com.evil.test` |
+| `llm.internal:8080` | exactly that port | `llm.internal:9200` |
+| `example.com:443` | `https://example.com/` (default port) | `http://example.com/` |
+| `LLM.Example.com` | `https://llm.example.com/` | — |
+
+Entries and URLs are both trimmed, lowercased and stripped of a fully-qualifying trailing dot, so
+neither side can win by spelling one DNS name differently.
+
+## Bugfix: the allowlist now covers every outbound path
+
+`probeContextWindow()` (the Ollama `/api/show` probe behind `detectContextWindow()`) reached the
+network **without consulting the allowlist**. It is not an admin-only path: `CoreAiService` calls
+`detectAndPersistCapabilities()` on an ordinary user prompt whenever `contextWindow` is undefined,
+and it runs *before* the AI rate limit.
+
+All three outbound paths — chat completions, the capability probe, and the context-window probe —
+now go through the same check. A refusal there degrades to "context window unknown" and falls back
+to the built-in model table, so nothing breaks for an allowed host.
+
+**No action required**, unless you were relying on the context-window probe reaching a host your
+allowlist excludes — in which case add that host.
+
+## Bugfix: a malformed value is now reported
+
+A value that is neither a list nor a string (a number, a boolean, an object — all reachable through
+`NEST_SERVER_CONFIG`) carries no hostnames, so the allowlist cannot be applied. That was silent.
+It is now logged as an error:
+
+```
+ai.allowedBaseUrlHosts is a number and carries no hostnames — the SSRF egress allowlist is
+NOT active. Use an array or a comma-separated string.
+```
+
+The behaviour is unchanged (permissive); only the silence is gone. From the outside, "misconfigured"
+and "deliberately unset" looked identical, which is what let the original defect survive.
+
+## Not consumer-facing
+
+The rest of this release is repository tooling and does not ship: a new `check:overrides` guard for
+stale pnpm overrides and audit suppressions, a `pnpm peers check` step, audit-count accounting in
+`scripts/check.mjs`, and test-evidence work. `package.json` `files` ships `dist` plus docs, and the
+CLI's vendor transformation copies `src/core/` — neither includes `scripts/`.
+
+Four further tooling fixes landed late in the release, all in the same area and all of the same
+kind — a gate that reported safety it had not established:
+
+| Fix | What it was |
+|-----|-------------|
+| Audit hang guard (`CHECK_AUDIT_TIMEOUT`, default 600s) | `pnpm audit` emits no intermediate output, so the existing idle watchdog structurally could not tell a hang from a healthy slow run. A second, absolute cap now kills it with its own cause |
+| `'unreadable'` degradation | An audit exiting **0** with no parseable tally printed a GREEN tick and a literal `0`, having assessed nothing. Reachable in practice: a pnpm version collision writes its error to stderr and exits 0 |
+| 5xx read from the code field only | The signature matched `\b5\d\d\b` against the whole envelope, so pnpm's own `audited 503 packages` degraded a run that had to block |
+| Reachability probe asked the wrong registry | Both check scripts hardcoded `registry.npmjs.org` while pnpm audits against the **configured** registry. Behind a private registry or proxy that reproduces the very false-green the probe removes: the real registry is unreachable, npmjs.org answers, the run reports "clean" |
+| Steps list contradicted the warning | A degraded audit printed a yellow warning and "NOT CHECKED" — and a **green tick** in the Steps list, which hard-coded one per step |
+| JSONC comment stripping | A regex stripper ate glob patterns out of `tsconfig.tests.json` and `.oxlintrc.json` (2783 bytes, and one whole `overrides` entry). Both files still parsed, so the assertions above them ran green against a mutilated config |
+
+None of them changes shipped behaviour; they are recorded because each one made a **check** claim
+something it had not verified, and that is the class of defect a consumer inherits indirectly — via
+a release that passed a gate which was not looking.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| AI stopped working after the update; log shows `host "…" is not in ai.allowedBaseUrlHosts` | The allowlist is now enforced where it previously was not | Add the host, or clear the setting |
+| `ServiceUnavailableException` on one connection only | That connection's `baseUrl` host is missing from the list | Add it — check `aiConnections`, not just `defaultConnection` |
+| Error log says the allowlist is `NOT active` | The value is not a list or a string | Use an array, or a comma-separated string |
+| An entry with `:443` stopped matching an `http://` URL | `:443` is the https default, not http's | Write the host without a port, or with the right one |
+
+## Module Documentation
+
+- `src/core/modules/ai/README.md` → "Egress allowlist (`ai.allowedBaseUrlHosts`)"
+- `.claude/rules/configurable-features.md` → "AI Egress Allowlist (SSRF)"
+- `src/core/common/interfaces/server-options.interface.ts` → `IAi.allowedBaseUrlHosts`

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.39.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",
@@ -25,11 +25,12 @@
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
     "check:consumer": "node scripts/check-consumer.mjs",
-    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:mutations": "node scripts/check-mutations.mjs",
-    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:overrides": "node scripts/check-overrides.mjs",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",

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

@@ -1712,9 +1712,25 @@ export interface IAi {
    * bare `hostname`); unset → permissive (so local providers like Ollama on localhost
    * work out of the box). `baseUrl` is admin-only, so this guards a compromised or
    * misconfigured admin, not end-user input.
+   *
+   * Accepts an array OR a comma-separated string. The string form is not a convenience:
+   * it is the shape the framework's own env mapping produces. `NSC__AI__ALLOWED_BASE_URL_HOSTS`
+   * becomes `{ ai: { allowedBaseUrlHosts: '<string>' } }`, and lodash `merge` assigns that
+   * scalar straight over a configured array — so the canonical `NSC__` spelling MUST be
+   * understood here or the control silently switches itself off.
+   *
+   * Entries are trimmed, lowercased and stripped of a fully-qualifying trailing dot, and the
+   * same normalisation is applied to the URL being checked, so neither side can win by
+   * spelling the same DNS name differently. A bare hostname entry matches any port on that
+   * host; an entry naming the scheme's default port (`example.com:443` for https) also matches
+   * the portless URL. A value that is neither an array nor a string carries no hostnames, so
+   * the allowlist is inactive — that case is LOGGED as an error rather than passed over, since
+   * it looks identical to "correctly unset" from the outside.
+   *
    * @example ['llm.example.com', 'localhost:11434']
+   * @example 'llm.example.com,localhost:11434'   // NSC__AI__ALLOWED_BASE_URL_HOSTS
    */
-  allowedBaseUrlHosts?: string[];
+  allowedBaseUrlHosts?: string | string[];
 
   /**
    * Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
@@ -1885,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)
 
@@ -159,6 +180,39 @@ calling and executes tools itself through `CrudService` with the caller's permis
 the child runs in a temp dir so no `CLAUDE.md`/settings leak into the context. See
 `ClaudeCliProvider` for the full security model and the optional `ai.claudeCli` config.
 
+## Egress allowlist (`ai.allowedBaseUrlHosts`)
+
+A connection's `baseUrl` decides where the server sends outbound HTTP. It is admin-set, so the
+threat model is a compromised or mistyped admin rather than end-user input — but the request still
+leaves from inside your network, which is what makes it an SSRF surface.
+
+**Unset (the default) means no restriction**, so a local provider works out of the box. When set,
+only the listed hosts are reachable and everything else is refused with
+`ServiceUnavailableException` plus a WARN naming the host:
+
+```typescript
+ai: {
+  allowedBaseUrlHosts: ['llm.example.com', 'localhost:11434'],
+}
+```
+
+```bash
+# Same setting via the canonical env spelling — a comma-separated string is understood
+NSC__AI__ALLOWED_BASE_URL_HOSTS=llm.example.com,localhost:11434
+```
+
+Matching details worth knowing before you debug a refusal:
+
+- A bare hostname entry matches **any port** on that host. An entry that names the scheme's default
+  port (`example.com:443` for https) also matches the portless URL.
+- Entries and URLs are both trimmed, lowercased, and stripped of a fully-qualifying trailing dot, so
+  `LLM.Example.com`, `llm.example.com` and `llm.example.com.` are one host.
+- The check covers **all three** outbound paths: chat completions, the capability probe, and the
+  Ollama context-window probe.
+- A value that is neither a list nor a string carries no hostnames. The allowlist is then inactive
+  and the framework logs an error — from the outside that state is indistinguishable from
+  "correctly unset", which is exactly why it is not silent.
+
 ## Connections (DB configuration)
 
 Connections live in the `aiConnections` collection and are managed by admins via

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;