feat(ai): send a per-entry reasoning effort to Local and gateway providers

Reasoning models on Ollama and similar servers think by default and can
spend the whole max_tokens budget before the visible answer starts, so
the call comes back empty or times out. The Local and OpenAI-compatible
chain entries now carry an optional reasoning setting: Default sends
nothing, Off sends reasoning_effort "none", Low / Medium / High send
their own value. It is stored on the entry in aiProviderChain, so a
chain can mix a thinking model with one that does not know the field.

- Every exported resolver binds the entry's value onto the client, the
  connection test included, keyed on the instance type so the operator
  provider, OpenAI, Anthropic and Codex never carry it.
- PATCH /api/user/ai-provider accepts localReasoningEffort and
  compatReasoningEffort and GET reports them. A provider absent from
  the chain holds its value on a disabled entry; restating Default on a
  chain that was never customised writes nothing.
- PUT /api/insights/provider-chain accepts reasoningEffort on local and
  openai-compatible entries, refuses it on any other, and keeps the
  stored value when the body leaves it out. Its schema is now shared
  with the OpenAPI registry.
- A Default request body is byte-identical to the one sent before.

Refs #1126
This commit is contained in:
Marc-André Bombeck committed 2026-10-04 10:42:59 +02:00
1 parent 808b2672cd
commit befac59576
18 files changed
+1350 -84

No files matched your search

@@ -0,0 +1,124 @@
/**
* Structural guard (#1126): `reasoning_effort` reaches a model only through
* the setting the resolver bound to the provider instance.
*
* Default must send nothing, so the key may not appear on any wire except as
* the bound value, and only the two clients whose endpoint a person chose may
* carry it. Pinned here:
*
* 1. the key appears in exactly the Local client and the OpenAI client,
* once each, and only as `reasoning_effort: this.reasoningEffort`;
* 2. nothing but the binder assigns `.reasoningEffort`;
* 3. every exported resolver in `provider.ts` calls `bindReasoningEffort`.
*
* That clients are constructed only in `provider.ts` (so a resolver always
* binds them) is frozen by `ai-call-timeout-guard.test.ts`.
*
* Its limit: it reads source text. A body built under a computed key, or a
* resolver that binds through an alias, would slip it.
* `reasoning-effort.test.ts` and `provider-reasoning-effort.test.ts` prove
* the behaviour on the wire.
*
* Mutation check: hard-code `reasoning_effort: "none"` into either client,
* set `client.reasoningEffort = ...` in a route, or drop `bindReasoningEffort`
* from `resolveProviderForTest`: each one goes red here.
*/
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { walkSourceFiles } from "./helpers/source-files";
const SRC = join(process.cwd(), "src");
function stripComments(source: string): string {
return source
.replace(/\/\*[\s\S]*?\*\//g, "")
.replace(/(^|[^:])\/\/.*$/gm, "$1");
}
function code(rel: string): string {
return stripComments(readFileSync(join(SRC, rel), "utf8"));
}
const files = walkSourceFiles(SRC, { floor: 3000 })
.filter((p) => !p.startsWith("generated/"))
.filter((p) => !p.includes("__tests__"))
.filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"));
describe("reasoning_effort on the wire", () => {
// As an object key: the published descriptions name the field in prose.
const KEY = /\breasoning_effort["']?\s*:/g;
const sites = files.filter((rel) => new RegExp(KEY).test(code(rel)));
it("appears in the Local and the OpenAI client only", () => {
expect(sites.sort()).toEqual([
"lib/ai/local-client.ts",
"lib/ai/openai-client.ts",
]);
});
it.each(["lib/ai/local-client.ts", "lib/ai/openai-client.ts"])(
"%s sends it once, as the bound value",
(rel) => {
const source = code(rel);
expect(source.match(new RegExp(KEY))?.length).toBe(1);
expect(source).toMatch(
/\breasoning_effort\s*:\s*this\s*\.\s*reasoningEffort\b/,
);
},
);
});
/** Where `.reasoningEffort` may be assigned, and why. */
const ASSIGNMENT_SITES: Record<string, string> = {
"lib/ai/reasoning-effort.ts":
"The binder, the one place a provider instance gets its value.",
"lib/ai/provider-chain.ts":
"Writes the stored chain entry, not a provider instance.",
};
describe("only the binder assigns it to a provider", () => {
it("names every assignment site, with a reason", () => {
const sites = files.filter((rel) =>
/\.\s*reasoningEffort\s*=(?!=)/.test(code(rel)),
);
expect(sites.sort()).toEqual(Object.keys(ASSIGNMENT_SITES).sort());
});
});
describe("every exported resolver binds it", () => {
const source = code("lib/ai/provider.ts");
const resolvers = source
.split(/\nexport\s+/)
.map((chunk) => {
const m = /^async\s+function\s+(\w+)\s*\(/.exec(chunk);
if (!m) return null;
const header = chunk.slice(0, chunk.indexOf("{\n"));
if (
!/Promise<\s*(?:AIProvider|ProviderChainResolved\[\])\s*>/.test(header)
) {
return null;
}
const end = chunk.indexOf("\n}\n");
return { name: m[1], body: chunk.slice(header.length, end) };
})
.filter((r): r is { name: string; body: string } => r !== null);
it("finds the resolvers (an empty set is a failure, not a pass)", () => {
expect(resolvers.map((r) => r.name).sort()).toEqual([
"resolveProvider",
"resolveProviderChain",
"resolveProviderForTest",
]);
});
it.each(resolvers.map((r) => r.name))(
"%s calls bindReasoningEffort",
(name) => {
const resolver = resolvers.find((r) => r.name === name);
expect(resolver?.body ?? "").toMatch(/\bbindReasoningEffort\s*\(/);
},
);
});