@jxburros/ai-nugget 0.4.1 → 0.7.0

package/dist/adapters/engines/google.js

@@ -1,8 +1,8 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, postResponse, sseLines } from '../../transport.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+import { applyProviderOptions, REASONING_BUDGET_TOKENS, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 export class GoogleAdapter {
     provider;
     constructor(provider) {
@@ -30,12 +30,23 @@ export class GoogleAdapter {
         const toolCalls = [];
         const timeout = streamTimeout(conn, req.signal);
         yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        // Gemini rejects `responseMimeType: application/json` combined with function
+        // declarations, so `body()` drops JSON mode when tools are present. Surface
+        // that downgrade instead of silently returning unstructured text.
+        if (jsonModeDowngraded(req)) {
+            yield {
+                type: 'context',
+                kind: 'json_mode_downgraded',
+                data: { reason: 'Gemini does not accept JSON response mode together with tools; the request was sent without JSON mode', provider: conn.provider },
+            };
+        }
         try {
             const streamUrl = `${conn.baseUrl}/v1beta/models/${encodeURIComponent(req.model)}:streamGenerateContent?alt=sse`;
             const res = await postResponse(streamUrl, body(req), conn.headers, timeout.signal, conn.provider);
             const contentType = res.headers.get('content-type') ?? '';
             const chunks = contentType.includes('text/event-stream') ? sseLines(res) : singleJsonLine(res);
             for await (const line of chunks) {
+                timeout.bump();
                 const parsed = safeParse(line);
                 const record = asRecord(parsed);
                 const promptFeedback = asRecord(record?.promptFeedback);
@@ -44,6 +55,12 @@ export class GoogleAdapter {
                 for (const part of candidateParts(record)) {
                     const partText = asString(asRecord(part)?.text);
                     if (partText) {
+                        // Gemini marks reasoning parts with `thought: true`; route those to
+                        // the reasoning channel so they don't blend into the answer text.
+                        if (asRecord(part)?.thought === true) {
+                            yield { type: 'reasoning', text: partText };
+                            continue;
+                        }
                         if (firstTokenMs === null)
                             firstTokenMs = Date.now() - started;
                         text += partText;
@@ -66,6 +83,8 @@ export class GoogleAdapter {
                 inputTokens = asNumber(usage?.promptTokenCount) ?? inputTokens;
                 outputTokens = asNumber(usage?.candidatesTokenCount) ?? outputTokens;
             }
+            if (!finish)
+                yield streamAnomaly('stream ended without a finishReason');
             const hasTools = toolCalls.length > 0;
             yield { type: 'done', result: {
                     text,
@@ -92,7 +111,7 @@ export class GoogleAdapter {
      */
     async health(conn) {
         try {
-            await fetchJson(`${conn.baseUrl}/v1beta/models`, {
+            await fetchJson(joinUrl(conn.baseUrl, '/v1beta/models'), {
                 method: 'GET',
                 headers: conn.headers,
                 timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
@@ -104,6 +123,41 @@ export class GoogleAdapter {
             return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
         }
     }
+    /**
+     * Lists models from Google's `/v1beta/models`. Strips the `models/` name
+     * prefix, and maps `inputTokenLimit` → `contextWindow` and
+     * `supportedGenerationMethods` → `capabilities`.
+     */
+    async listModels(conn) {
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/v1beta/models'), {
+            method: 'GET',
+            headers: conn.headers,
+            timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 15_000),
+            provider: conn.provider,
+        });
+        const rows = Array.isArray(asRecord(data)?.models) ? asRecord(data).models : [];
+        const models = [];
+        for (const value of rows) {
+            const row = asRecord(value);
+            const name = asString(row?.name);
+            if (!name)
+                continue;
+            const id = name.startsWith('models/') ? name.slice('models/'.length) : name;
+            const model = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
+            const contextWindow = asNumber(row?.inputTokenLimit);
+            if (contextWindow !== undefined)
+                model.contextWindow = contextWindow;
+            const methods = row?.supportedGenerationMethods;
+            if (Array.isArray(methods) && methods.every((m) => typeof m === 'string'))
+                model.capabilities = methods;
+            models.push(model);
+        }
+        return models;
+    }
+}
+/** True when the caller asked for JSON mode but tools force it off. */
+function jsonModeDowngraded(req) {
+    return req.responseFormat?.type === 'json' && !!req.tools?.length;
 }
 function body(req) {
     const systemText = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n');
@@ -130,7 +184,17 @@ function body(req) {
             config.allowedFunctionNames = [req.toolChoice.name];
         payload.toolConfig = { functionCallingConfig: config };
     }
-    return payload;
+    if (req.reasoningEffort !== undefined) {
+        // First-class reasoning effort → Gemini's thinking budget. 0 disables
+        // thinking on models that allow it; others treat it as a minimum.
+        payload.generationConfig.thinkingConfig = {
+            thinkingBudget: REASONING_BUDGET_TOKENS[req.reasoningEffort],
+        };
+    }
+    // providerOptions reaches Google-native fields: top-level `safetySettings`,
+    // `cachedContent`, and `generationConfig` extras (`thinkingConfig`,
+    // `responseModalities`, …) merged one level deep into generationConfig.
+    return applyProviderOptions(payload, req.providerOptions, ['generationConfig']);
 }
 function toGoogleContents(messages) {
     const contents = [];
@@ -152,29 +216,27 @@ function toGoogleContents(messages) {
     return contents;
 }
 function toGoogleContent(m) {
-    if (m.role === 'tool') {
-        return {
-            role: 'user',
-            parts: [{ functionResponse: { name: m.name ?? 'unknown', response: toolResponseObject(m) } }],
-        };
-    }
+    // Tool-role messages are handled by toGoogleContents' batching loop and never
+    // reach here, so no tool branch is needed.
     if (m.role === 'assistant' && m.toolCalls?.length) {
-        const parts = [];
-        if (typeof m.content === 'string' && m.content)
-            parts.push({ text: m.content });
+        const parts = [...googleParts(m.content)];
         for (const call of m.toolCalls)
             parts.push({ functionCall: { name: call.name, args: call.arguments ?? {} } });
         return { role: 'model', parts };
     }
     return {
         role: m.role === 'assistant' ? 'model' : 'user',
-        parts: typeof m.content === 'string'
-            ? [{ text: m.content }]
-            : m.content.map((part) => part.type === 'image'
-                ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
-                : { text: part.text ?? '' }),
+        parts: googleParts(m.content),
     };
 }
+/** Maps text/image content — a string or a ContentPart[] — onto Google parts. */
+function googleParts(content) {
+    if (typeof content === 'string')
+        return content ? [{ text: content }] : [];
+    return content.map((part) => part.type === 'image'
+        ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+        : { text: part.text ?? '' });
+}
 function textContent(content) {
     if (typeof content === 'string')
         return content;
@@ -223,15 +285,4 @@ function mapFinish(finish, hasTools) {
         return 'content_filter';
     return 'stop';
 }
-function safeParse(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-function randomId() {
-    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}
 //# sourceMappingURL=google.js.map

package/dist/adapters/engines/ollama.d.ts

@@ -1,10 +1,11 @@
-import type { ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ChatRequest, ChatResult, EmbedRequest, EmbedResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
 export declare class OllamaAdapter implements ProviderAdapter {
     readonly provider: string;
     constructor(provider: string);
     chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
     stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
     listModels(conn: ResolvedConnection): Promise<ModelInfo[]>;
+    embed(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
     private showModel;
 }
 //# sourceMappingURL=ollama.d.ts.map

package/dist/adapters/engines/ollama.js

@@ -1,8 +1,10 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, ndjsonLines, postResponse } from '../../transport.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, mapWithConcurrency, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, parseArgs, randomId, streamAnomaly, streamError, streamTimeout } from './base.js';
+/** Max concurrent /api/show probes when listing models — enough to be fast, few enough to be polite to a local daemon. */
+const SHOW_CONCURRENCY = 6;
 export class OllamaAdapter {
     provider;
     constructor(provider) {
@@ -27,14 +29,19 @@ export class OllamaAdapter {
         let inputTokens;
         let outputTokens;
         let doneReason;
+        let sawTerminal = false;
         const toolCalls = [];
         const timeout = streamTimeout(conn, req.signal);
         yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
         try {
-            const res = await postResponse(`${conn.baseUrl}/api/chat`, body(req), conn.headers, timeout.signal, conn.provider);
+            const res = await postResponse(joinUrl(conn.baseUrl, '/api/chat'), body(req), conn.headers, timeout.signal, conn.provider);
             for await (const value of ndjsonLines(res)) {
+                timeout.bump();
                 const record = asRecord(value);
                 const message = asRecord(record?.message);
+                const thinking = asString(message?.thinking);
+                if (thinking)
+                    yield { type: 'reasoning', text: thinking };
                 const piece = asString(message?.content);
                 if (piece) {
                     if (firstTokenMs === null)
@@ -45,6 +52,8 @@ export class OllamaAdapter {
                 inputTokens = asNumber(record?.prompt_eval_count) ?? inputTokens;
                 outputTokens = asNumber(record?.eval_count) ?? outputTokens;
                 doneReason = asString(record?.done_reason) ?? doneReason;
+                if (record?.done === true)
+                    sawTerminal = true;
                 const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
                 for (const callValue of calls) {
                     const fn = asRecord(asRecord(callValue)?.function);
@@ -52,13 +61,18 @@ export class OllamaAdapter {
                     const toolCall = {
                         id: randomId(),
                         name: asString(fn?.name) ?? 'unknown',
-                        arguments: args,
+                        // Ollama itself sends a native object, but llama.cpp-style backends
+                        // behind the same protocol send a JSON *string* — coerce either into
+                        // the object `validateToolArgs` expects.
+                        arguments: parseArgs(args),
                         raw: typeof args === 'string' ? args : JSON.stringify(args),
                     };
                     toolCalls.push(toolCall);
                     yield { type: 'tool_call', call: toolCall };
                 }
             }
+            if (!sawTerminal)
+                yield streamAnomaly('NDJSON stream ended without a done record');
             const hasTools = toolCalls.length > 0;
             yield { type: 'done', result: {
                     text,
@@ -86,19 +100,39 @@ export class OllamaAdapter {
         });
         const models = Array.isArray(asRecord(data)?.models) ? asRecord(data).models : [];
         const ids = models.map((model) => asString(asRecord(model)?.name) ?? asString(asRecord(model)?.model) ?? '').filter(Boolean);
-        // Probe /api/show per model for context window + capabilities (best effort, sequential
-        // to avoid overwhelming a local Ollama instance).
-        const results = [];
-        for (const id of ids) {
+        // Probe /api/show per model for context window + capabilities (best effort),
+        // with bounded concurrency so a large model list resolves quickly without
+        // opening an unbounded number of sockets against a local daemon.
+        return mapWithConcurrency(ids, SHOW_CONCURRENCY, async (id) => {
             const info = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
             const probed = await this.showModel(conn, id).catch(() => undefined);
             if (probed?.contextWindow !== undefined)
                 info.contextWindow = probed.contextWindow;
             if (probed?.capabilities)
                 info.capabilities = probed.capabilities;
-            results.push(info);
-        }
-        return results;
+            return info;
+        });
+    }
+    async embed(conn, req) {
+        const inputs = Array.isArray(req.input) ? req.input : [req.input];
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/api/embed'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...conn.headers },
+            body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+            timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            provider: conn.provider,
+        });
+        const record = asRecord(data);
+        const rows = Array.isArray(record?.embeddings) ? record.embeddings : [];
+        const embeddings = rows.map((row) => (Array.isArray(row) ? row.filter((n) => typeof n === 'number') : []));
+        const inputTokens = asNumber(record?.prompt_eval_count);
+        return {
+            embeddings,
+            model: req.model,
+            usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+            source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+            raw: data,
+        };
     }
     async showModel(conn, model) {
         const { data } = await fetchJson(`${conn.baseUrl}/api/show`, {
@@ -130,7 +164,7 @@ export class OllamaAdapter {
     }
 }
 function body(req) {
-    return {
+    const base = {
         model: req.model,
         messages: req.messages.map(toOllamaMessage),
         stream: true,
@@ -138,6 +172,17 @@ function body(req) {
         format: req.responseFormat?.type === 'json' ? (req.responseFormat.schema ?? 'json') : undefined,
         tools: req.tools?.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })),
     };
+    // First-class reasoning effort → Ollama's `think` flag (reasoning arrives in
+    // `message.thinking`, which this engine already routes to `reasoning` events).
+    // Ollama has no graded effort for most models, so anything but `'none'` is
+    // `true`. Only sent when asked for: a model without thinking support rejects it.
+    if (req.reasoningEffort !== undefined)
+        base.think = req.reasoningEffort !== 'none';
+    // providerOptions reaches Ollama's real request fields — `options.num_ctx`,
+    // `options.num_keep`, top-level `keep_alive`, `think`, etc. `options` is
+    // merged one level deep so num_ctx joins the samplers above rather than
+    // replacing them.
+    return applyProviderOptions(base, req.providerOptions, ['options']);
 }
 function toOllamaMessage(m) {
     const images = typeof m.content === 'string' ? undefined : m.content.filter((part) => part.type === 'image').map((part) => part.imageBase64).filter(Boolean);
@@ -154,7 +199,4 @@ function toOllamaMessage(m) {
     }
     return message;
 }
-function randomId() {
-    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}
 //# sourceMappingURL=ollama.js.map

package/dist/adapters/engines/openaiChat.d.ts

@@ -1,4 +1,4 @@
-import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ChatRequest, ChatResult, EmbedRequest, EmbedResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
 import type { ProviderProfile } from '../profiles.js';
 export declare class OpenAIChatAdapter implements ProviderAdapter {
     private profile;
@@ -11,5 +11,12 @@ export declare class OpenAIChatAdapter implements ProviderAdapter {
         ok: boolean;
         detail?: string;
     }>;
+    embed(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
 }
+/**
+ * True when a `/chat/completions` 400 is the "function tools with reasoning_effort
+ * are not supported" refusal AND the request actually carried tools AND the caller
+ * did not already pin `reasoning_effort` (in which case the choice is theirs).
+ */
+export declare function shouldRetryWithoutReasoningEffort(error: unknown, req: ChatRequest): boolean;
 //# sourceMappingURL=openaiChat.d.ts.map

package/dist/adapters/engines/openaiChat.js

@@ -1,8 +1,8 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { health, listOpenModels, streamError, streamTimeout } from './base.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, health, listOpenModels, parseArgs, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 export class OpenAIChatAdapter {
     profile;
     provider;
@@ -34,7 +34,34 @@ export class OpenAIChatAdapter {
         const timeout = streamTimeout(conn, req.signal);
         yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
         try {
-            const res = await postResponse(urlFor(conn, this.profile, req.model), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+            let res;
+            try {
+                res = await postResponse(urlFor(conn, this.profile, req), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+            }
+            catch (error) {
+                // OpenAI's `/chat/completions` refuses function tools on a reasoning model
+                // unless `reasoning_effort` is `'none'` ("Function tools with reasoning_effort
+                // are not supported … use /v1/responses or set reasoning_effort to 'none'").
+                // The nugget never sets `reasoning_effort` itself, so the provider default
+                // applies and every tool-using turn 400s. Rather than make each app learn
+                // this the hard way, retry the one request once with the effort disabled
+                // and say so on the stream. Reactive on purpose: sending
+                // `reasoning_effort` up front would 400 on non-reasoning models instead.
+                // A caller-requested effort is overridden too — the alternative is a hard
+                // 400 with no tool call at all — and the context event says so.
+                if (!shouldRetryWithoutReasoningEffort(error, req))
+                    throw error;
+                yield {
+                    type: 'context',
+                    kind: 'reasoning_effort_disabled_for_tools',
+                    data: {
+                        reason: 'provider rejected function tools with reasoning_effort; retried with reasoning_effort: none',
+                        requested: req.providerOptions?.reasoning_effort ?? req.reasoningEffort ?? null,
+                    },
+                };
+                const retryReq = { ...req, providerOptions: { ...req.providerOptions, reasoning_effort: 'none' } };
+                res = await postResponse(urlFor(conn, this.profile, retryReq), openAiBody(retryReq, this.profile), conn.headers, timeout.signal, conn.provider);
+            }
             const contentType = res.headers.get('content-type') ?? '';
             if (!contentType.includes('text/event-stream')) {
                 // Server ignored stream:true (or is a buffered gateway) — recover the whole body.
@@ -47,6 +74,8 @@ export class OpenAIChatAdapter {
                 outputTokens = parsed.outputTokens;
                 finish = parsed.finish;
                 sawTerminal = true;
+                if (parsed.reasoning)
+                    yield { type: 'reasoning', text: parsed.reasoning };
                 if (text)
                     yield { type: 'delta', text };
                 for (const call of toolCalls)
@@ -55,6 +84,7 @@ export class OpenAIChatAdapter {
             else {
                 const partialTools = new Map();
                 for await (const line of sseLines(res)) {
+                    timeout.bump();
                     const chunk = safeParse(line);
                     const record = asRecord(chunk);
                     if (!record)
@@ -68,6 +98,11 @@ export class OpenAIChatAdapter {
                     if (choice?.finish_reason)
                         sawTerminal = true;
                     const delta = asRecord(choice?.delta);
+                    // Reasoning tokens (DeepSeek `reasoning_content`, others `reasoning`)
+                    // ride their own channel so they don't contaminate the answer text.
+                    const reasoning = asString(delta?.reasoning_content) ?? asString(delta?.reasoning);
+                    if (reasoning)
+                        yield { type: 'reasoning', text: reasoning };
                     const piece = asString(delta?.content);
                     if (piece) {
                         if (firstTokenMs === null)
@@ -96,9 +131,8 @@ export class OpenAIChatAdapter {
                 for (const call of toolCalls)
                     yield { type: 'tool_call', call };
             }
-            if (!sawTerminal) {
-                yield { type: 'context', kind: 'stream_anomaly', data: { reason: 'stream ended without a finish_reason' } };
-            }
+            if (!sawTerminal)
+                yield streamAnomaly('stream ended without a finish_reason');
             const result = makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens);
             yield { type: 'done', result };
         }
@@ -115,6 +149,34 @@ export class OpenAIChatAdapter {
     health(conn) {
         return health(conn, this.profile);
     }
+    async embed(conn, req) {
+        const inputs = Array.isArray(req.input) ? req.input : [req.input];
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/embeddings'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...conn.headers },
+            body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+            timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            provider: conn.provider,
+        });
+        const record = asRecord(data);
+        const rows = Array.isArray(record?.data) ? record.data : [];
+        // Order by the `index` each row reports, falling back to array order.
+        const byIndex = rows
+            .map((row, i) => ({ index: asNumber(asRecord(row)?.index) ?? i, embedding: asEmbedding(asRecord(row)?.embedding) }))
+            .sort((a, b) => a.index - b.index);
+        const usage = asRecord(record?.usage);
+        const inputTokens = asNumber(usage?.prompt_tokens);
+        return {
+            embeddings: byIndex.map((row) => row.embedding),
+            model: req.model,
+            usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+            source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+            raw: data,
+        };
+    }
+}
+function asEmbedding(value) {
+    return Array.isArray(value) ? value.filter((n) => typeof n === 'number') : [];
 }
 function openAiBody(req, profile) {
     const body = {
@@ -134,7 +196,16 @@ function openAiBody(req, profile) {
     };
     if (req.maxTokens !== undefined)
         body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
-    return body;
+    // First-class reasoning effort → OpenAI's `reasoning_effort`. Only sent when
+    // asked for: non-reasoning models reject the parameter outright.
+    if (req.reasoningEffort !== undefined)
+        body.reasoning_effort = req.reasoningEffort;
+    // providerOptions carries OpenAI-native fields the nugget doesn't model
+    // (`reasoning_effort`, `parallel_tool_calls`, `seed`, `logprobs`, …). `apiVersion`
+    // is consumed by urlFor for Azure and stripped here so it never hits the body.
+    const { apiVersion, ...passthrough } = req.providerOptions ?? {};
+    void apiVersion;
+    return applyProviderOptions(body, Object.keys(passthrough).length ? passthrough : undefined);
 }
 function responseFormatFor(req, profile) {
     if (req.responseFormat?.type !== 'json')
@@ -157,11 +228,18 @@ function toOpenAiMessage(message) {
         tool_calls: message.toolCalls?.map((call) => ({ id: call.id, type: 'function', function: { name: call.name, arguments: call.raw ?? JSON.stringify(call.arguments) } })),
     };
 }
-function urlFor(conn, profile, model) {
+function urlFor(conn, profile, req) {
     if (profile.quirks?.urlTemplate) {
-        return profile.quirks.urlTemplate.replace('{baseUrl}', conn.baseUrl).replace('{model}', encodeURIComponent(model));
+        // `{apiVersion}` (Azure) is filled from a per-call override, then the
+        // profile default — so a retired Azure api-version is fixable without a
+        // library release: pass `providerOptions: { apiVersion: '2025-01-01-preview' }`.
+        const apiVersion = asString(req.providerOptions?.apiVersion) ?? profile.quirks.apiVersion ?? '';
+        return profile.quirks.urlTemplate
+            .replace('{baseUrl}', conn.baseUrl)
+            .replace('{model}', encodeURIComponent(req.model))
+            .replace('{apiVersion}', apiVersion);
     }
-    return `${conn.baseUrl}/chat/completions`;
+    return joinUrl(conn.baseUrl, '/chat/completions');
 }
 function parseOpenAiResponse(raw) {
     const record = asRecord(raw);
@@ -169,9 +247,11 @@ function parseOpenAiResponse(raw) {
     const choice = asRecord(Array.isArray(record?.choices) ? record.choices[0] : undefined);
     const message = asRecord(choice?.message);
     const text = asString(message?.content) ?? asString(record?.text) ?? '';
+    const reasoning = asString(message?.reasoning_content) ?? asString(message?.reasoning);
     const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
     return {
         text,
+        reasoning,
         finish: asString(choice?.finish_reason),
         toolCalls: calls.map((value) => {
             const call = asRecord(value);
@@ -206,23 +286,23 @@ function mapFinish(finish, hasToolCalls) {
         return 'content_filter';
     return 'stop';
 }
-function parseArgs(raw) {
-    try {
-        return raw ? JSON.parse(raw) : {};
-    }
-    catch {
-        return {};
-    }
-}
-function safeParse(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-function randomId() {
-    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+/**
+ * True when a `/chat/completions` 400 is the "function tools with reasoning_effort
+ * are not supported" refusal AND the request actually carried tools AND the caller
+ * did not already pin `reasoning_effort` (in which case the choice is theirs).
+ */
+export function shouldRetryWithoutReasoningEffort(error, req) {
+    if (!(error instanceof AIError) || error.status !== 400)
+        return false;
+    if (!req.tools || req.tools.length === 0)
+        return false;
+    // Already `'none'` (from either knob) — the refusal is about something else.
+    const effective = req.providerOptions && 'reasoning_effort' in req.providerOptions
+        ? req.providerOptions.reasoning_effort
+        : req.reasoningEffort;
+    if (effective === 'none')
+        return false;
+    const text = `${error.raw ?? ''} ${error.message}`.toLowerCase();
+    return text.includes('reasoning_effort') && text.includes('tool');
 }
 //# sourceMappingURL=openaiChat.js.map

package/dist/adapters/profiles.d.ts

@@ -32,11 +32,31 @@ export interface ProviderProfile {
         maxTokensRequired?: boolean;
         maxTokensParam?: 'max_tokens' | 'max_completion_tokens';
         supportsJsonSchema?: boolean;
+        /**
+         * Default value for the `{apiVersion}` token in `urlTemplate` (Azure OpenAI).
+         * Overridable per call via `ChatRequest.providerOptions.apiVersion`, so a
+         * retired Azure api-version never requires a library release.
+         */
+        apiVersion?: string;
+        /**
+         * Provider honors an `Idempotency-Key` request header. When set, the handler
+         * attaches one key per logical call and reuses it across retries, so a retry
+         * after a connection drops post-generation is deduped by the provider rather
+         * than billed twice. Left off unless the provider documents the header —
+         * sending an unknown header is harmless, but claiming the guarantee is not.
+         */
+        supportsIdempotencyKey?: boolean;
     };
     listModelsPath?: string;
     healthPath?: string;
 }
-export declare const PROVIDER_PROFILES: Record<string, ProviderProfile>;
+/**
+ * The provider keys that have a profile in {@link PROVIDER_PROFILES}. Used to
+ * type `Connection.provider` so IDEs autocomplete valid names and typos are a
+ * compile error rather than a silent fall-through to `openai-compat`.
+ */
+export type KnownProvider = 'openai' | 'azure-openai' | 'openrouter' | 'groq' | 'deepseek' | 'mistral' | 'together' | 'fireworks' | 'cerebras' | 'moonshot' | 'cohere' | 'perplexity' | 'lmstudio' | 'llamacpp' | 'vllm' | 'ollama' | 'anthropic' | 'google' | 'openai-compat';
+export declare const PROVIDER_PROFILES: Record<KnownProvider, ProviderProfile> & Record<string, ProviderProfile>;
 export declare function profileFor(provider: string, baseUrl?: string): ProviderProfile;
 export declare function applyAuth(profile: ProviderProfile, apiKey: string | null, headers: Record<string, string>): Record<string, string>;
 //# sourceMappingURL=profiles.d.ts.map

package/dist/adapters/profiles.js

@@ -7,13 +7,13 @@ export const PROVIDER_PROFILES = {
         auth: 'bearer',
         listModelsPath: '/models',
         capabilities: HOSTED_CLOUD,
-        quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+        quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true, supportsIdempotencyKey: true },
     },
     'azure-openai': {
         engine: 'openaiChat',
         auth: 'api-key-header',
         capabilities: HOSTED_CLOUD,
-        quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version=2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+        quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version={apiVersion}', apiVersion: '2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
     },
     openrouter: {
         engine: 'openaiChat',
@@ -29,6 +29,12 @@ export const PROVIDER_PROFILES = {
     mistral: { engine: 'openaiChat', defaultBaseUrl: 'https://api.mistral.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
     together: { engine: 'openaiChat', defaultBaseUrl: 'https://api.together.xyz/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
     fireworks: { engine: 'openaiChat', defaultBaseUrl: 'https://api.fireworks.ai/inference/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    cerebras: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cerebras.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    moonshot: { engine: 'openaiChat', defaultBaseUrl: 'https://api.moonshot.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    // Cohere's OpenAI-compatible surface lives under /compatibility/v1.
+    cohere: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cohere.ai/compatibility/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    // Perplexity has no public model-listing endpoint, so listModels resolves empty.
+    perplexity: { engine: 'openaiChat', defaultBaseUrl: 'https://api.perplexity.ai', auth: 'bearer', capabilities: HOSTED_CLOUD },
     lmstudio: {
         engine: 'openaiChat',
         defaultBaseUrl: 'http://localhost:1234/v1',
@@ -86,6 +92,10 @@ export const PROVIDER_PROFILES = {
         // Unknown endpoint — usually pointed at a local/self-hosted server, so
         // assume the conservative local-runtime defaults rather than the hosted-cloud ones.
         capabilities: LOCAL_RUNTIME,
+        // Most servers reached through this escape hatch (JX Runtime and other
+        // local OpenAI-compatible runtimes) don't require a key at all; keep
+        // `auth: 'bearer'` for the ones that do (a key is only sent if provided).
+        quirks: { keyOptional: true },
     },
 };
 export function profileFor(provider, baseUrl) {