@jxburros/ai-nugget 0.6.0 → 0.7.3

package/README.md

@@ -1,6 +1,8 @@
 # AI Nugget
 
-**Version 0.6.0** · [What's changed since 0.5.0](#whats-changed-since-050) · [Changelog](./CHANGELOG.md) · [Upgrading](./UPGRADING.md)
+<img src="assets/ai-nugget-logo.png" alt="AI Nugget official logo" width="180" />
+
+**Version 0.7.3** · [What's changed in 0.7.x](#whats-changed-in-07x) · [Changelog](./CHANGELOG.md) · [Upgrading](./UPGRADING.md)
 
 A small, zero-dependency, isomorphic TypeScript nugget for talking to AI model
 providers through one pipeline:
@@ -24,6 +26,13 @@ Requires Node `^20.19.0` or `>=22.12.0` ([why](./docs/distribution.md#requiremen
 npm install @jxburros/ai-nugget
 ```
 
+> **0.7.1–0.7.3 are not on npm yet.** The registry's `latest` is still 0.7.0
+> until the 0.7.3 Release run publishes, so the command above may install 0.7.0
+> (without the 0.7.1 Anthropic fixes or the 0.7.2 `/agent` types fix). Until
+> then, pin a commit from this repository
+> (`npm install github:jxburros/AI-Nugget#<commit>`) or vendor `nugget/` — see
+> [distribution paths](./docs/distribution.md#distribution-paths).
+
 ```ts
 import { AIHandler, envKeySource } from '@jxburros/ai-nugget';
 
@@ -50,7 +59,9 @@ No key? Point at a local model instead — same code, no `keyRef`:
 const conn = { id: 'local', provider: 'ollama', baseUrl: 'http://127.0.0.1:11434' };
 ```
 
-CommonJS works too: `const { AIHandler } = require('@jxburros/ai-nugget')`.
+CommonJS works too: `const { AIHandler } = require('@jxburros/ai-nugget')`. TypeScript
+finds the root and `/agent` types under `node10` (classic `module: commonjs`)
+and `bundler` resolution, and under `node16`/`nodenext` from ESM files.
 
 For a running server, copy a starter from
 [`examples/integrations/`](./examples/integrations/) — Express, Next.js,
@@ -108,12 +119,76 @@ new AIHandler({
 - **Seams** — `KeySource` (env/literal/memory/chain + ref parsing), `Redactor`,
   neutral `GovernancePolicy` (`blocklistPolicy`/`allowlistPolicy`/`composePolicies`),
   `TelemetrySink`, and an optional `pricing` hook. `providerOptions` passes
-  provider-native fields through without waiting for a library release.
+  provider-native fields through without waiting for a library release;
+  `reasoningEffort` is one word for "how hard should the model think", mapped
+  per provider ([docs](./docs/providers.md#reasoning-effort)).
 - **Agent layer** (`@jxburros/ai-nugget/agent`) — `defineTool`, `runAgent()`
   model↔tool loop over the full pipeline, streamed `AgentEvent`s, budgets with
   honest `stopReason`s, an `ApprovalGate` for side-effecting tools, and
   `native`/`promptJson`/`auto` tool modes.
 
+## Anthropic compatibility
+
+Claude Opus/Sonnet/Haiku 5.5 requests omit unsupported sampling parameters.
+Modern Claude JSON schemas use `output_config.format`; requests without a schema
+use a JSON instruction and emit `json_mode_downgraded`. Older models retain the
+forced-tool fallback. Explicit forced-tool choices on models that reject them
+fail with `invalid_request` rather than silently changing the choice.
+
+Anthropic results include opaque `providerState`. Custom tool loops must copy it
+onto the corresponding assistant `ChatMessage`; `runAgent` does this automatically.
+Keep it unchanged and private: it contains signed thinking blocks needed for replay,
+not display or telemetry data. Replay is limited to the same provider and model.
+See [provider details](./docs/providers.md#anthropic-compatibility).
+
+## What's changed in 0.7.x
+
+### 0.7.3
+
+**Release-pipeline fix.** Package contents are identical to 0.7.2; 0.7.3 exists
+because the 0.7.1 and 0.7.2 Release runs failed before publishing (see the
+[changelog](./CHANGELOG.md)).
+
+### 0.7.2
+
+**`/agent` types under classic `node10` resolution.** A `typesVersions` entry
+lets TypeScript projects on `module: commonjs` (default `node10` resolution)
+resolve `@jxburros/ai-nugget/agent`. Otherwise documentation only — notably the
+[JX Runtime guidance](./docs/providers.md#pointing-at-a-jx-runtime-server) for
+JX 1.5, including the `stream_options` opt-in for real streamed token counts.
+No runtime behavior changed.
+
+### 0.7.1
+
+**Anthropic correctness for modern Claude models.** Unsupported sampling
+parameters are omitted, JSON schemas use native structured output, and signed
+thinking is preserved for tool-loop replay through the new opaque
+`providerState` on results (`runAgent` copies it for you; custom tool loops must
+copy it onto the assistant message). SSE API errors become typed failures.
+Details in [Anthropic compatibility](#anthropic-compatibility),
+[UPGRADING.md](./UPGRADING.md#070--071), and the [changelog](./CHANGELOG.md).
+
+### 0.7.0
+
+**0.7.0 is backward-compatible for ordinary consumers** — the first two changes are additive; the third changes what `delta` carries for reasoning models (see UPGRADING). Full detail in the
+[changelog](./CHANGELOG.md) and [UPGRADING.md](./UPGRADING.md#06x--070).
+
+- **`ChatRequest.reasoningEffort`** (`none` / `minimal` / `low` / `medium` /
+  `high`) — one vocabulary for reasoning effort, mapped onto OpenAI
+  `reasoning_effort`, Anthropic `thinking`, Google `thinkingConfig`, and Ollama
+  `think`; forwarded by the agent loop via `AgentOptions.reasoningEffort`.
+  Never sent unless you set it. See [Reasoning effort](./docs/providers.md#reasoning-effort).
+- **OpenAI reasoning models can call tools again.** `/chat/completions` refuses
+  function tools unless `reasoning_effort` is `'none'`; the `openaiChat` engine
+  now retries that one request with it set and emits a
+  `reasoning_effort_disabled_for_tools` context event so the change is visible.
+  Learned from AI Server Studio's Build 3 shakedown, where every tool-using
+  turn on `gpt-5.x`/`gpt-6` 400'd.
+- **Inline `<think>` reasoning never reaches `delta` or `result.text`.** The
+  handler strips it on every engine and emits it as `reasoning` events
+  (`stripInlineReasoning: false` opts out). Ported from the stripper AI Server
+  Studio had to run at every call site. See [Inline reasoning](./docs/providers.md#inline-reasoning-is-stripped-at-the-seam).
+
 ## What's changed since 0.5.0
 
 **0.6.0 is backward-compatible** — every change below is additive. The one thing
@@ -177,3 +252,17 @@ seam), and not a UI. The governance seam ships neutral: it is where an app *can*
 enforce rules, not a place the library imposes its own.
 
 <!-- GitHub Pages deployment is configured in .github/workflows/pages.yml. -->
+
+---
+
+## Project Stewardship
+
+This project is developed by **Jeffrey** through **JX Holdings, LLC**. GitHub: [`jxburros`](https://github.com/jxburros).
+
+## Unified release procedure
+
+`release.json` is the authoritative release manifest. Keep configured embedded versions synchronized and advance affected apps (patch by default) before merging changes into main. The first adoption establishes a baseline; later PRs must pass **Release version validation**.
+
+Use **Actions → Release → Run workflow** from **main**, choose stable or preview, and leave **dry_run** enabled first. Only apps ahead of their published version in their own namespace are selected. Build/test/sign all required packages before publishing. Tag pushes and merges no longer publish migrated apps automatically. After inspecting the dry run, dispatch with dry_run disabled and satisfy configured approvals. Published versions are never overwritten; use a new version for a correction.
+
+See [.release/README.md](.release/README.md) for this repository's inventory, credentials, compatibility, and validation limits. Shared implementation: [JX Holdings release infrastructure](https://github.com/JX-Holdings-LLC/release-infrastructure).

package/UPGRADING.md

@@ -1,5 +1,47 @@
 # Upgrading
 
+## 0.7.2 → 0.7.3
+
+No changes: 0.7.3 republishes the 0.7.2 package contents after a release-pipeline fix.
+
+## 0.7.1 → 0.7.2
+
+No code changes required. `package.json` gains a `typesVersions` entry so
+TypeScript on classic `node10` resolution can find the `/agent` types; consumers
+on `node16`/`nodenext`/`bundler` resolve exactly as before.
+
+## 0.7.0 → 0.7.1
+
+Custom Anthropic tool loops should copy `result.providerState` onto their assistant
+messages to preserve signed thinking; `runAgent` already does this. Sampling fields
+are omitted on known modern Claude models. Native JSON schemas replace forced JSON
+tools there; schema-less requests disclose an instruction-only downgrade. Explicit
+unsupported forced-tool and thinking-off choices fail with `invalid_request`.
+
+## 0.6.x → 0.7.0
+
+**Backward-compatible for ordinary consumers.** Two additive changes and one
+default-behaviour change worth knowing about:
+
+- **Inline reasoning is stripped by default.** A model that writes
+  `<think>…</think>` (or `<thinking>`, `<reasoning>`, `<|begin_of_thought|>`)
+  into its answer no longer has that text in `delta` events or
+  `ChatResult.text`; it arrives as `{ type: 'reasoning', text }` events, the
+  same channel a provider-native thinking field already used. If your app
+  parsed or displayed those tags itself, either delete that code or pass
+  `new AIHandler({ stripInlineReasoning: false })` to keep the raw text.
+
+- **`ChatRequest.reasoningEffort`** (and `AgentOptions.reasoningEffort`) — a
+  new optional field. Nothing is sent to any provider unless you set it. If you
+  already pass `reasoning_effort` / `thinking` / `thinkingConfig` / `think`
+  through `providerOptions`, that keeps winning on collision.
+- **A new `context` stream event, `reasoning_effort_disabled_for_tools`** — the
+  `openaiChat` engine emits it when it retried a tool-using request with
+  `reasoning_effort: 'none'` after OpenAI refused the first attempt. Ignoring
+  it keeps the old behaviour minus the 400. If you *want* the hard failure
+  instead (to route to `/v1/responses` yourself), set `reasoningEffort: 'none'`
+  explicitly on tool-using turns — then no retry happens and any 400 is yours.
+
 ## 0.5.x → 0.6.0
 
 Behavior-compatible for ordinary consumers, with **two things worth checking**.
@@ -62,7 +104,7 @@ signature changed and no default behavior changed, so an app on 0.4.x can bump
 without code edits and adopt the new capabilities as needed.
 
 The numbers in brackets are the suggestion numbers from the AI Server Studio
-production friction report (`docs/reviews/2026-08-09-ai-server-studio-friction-report.md`),
+production friction report ([`docs/archive/2026-08-09-ai-server-studio-friction-report.md`](./docs/archive/2026-08-09-ai-server-studio-friction-report.md)),
 so you can trace each change back to the friction it resolves.
 
 ### Packaging

package/dist/adapters/engines/anthropic.js

@@ -1,7 +1,7 @@
-import { AIError } from '../../errors.js';
+import { AIError, classify } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, postResponse, sseLines } from '../../transport.js';
-import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { applyProviderOptions, REASONING_BUDGET_TOKENS, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
 import { DEFAULT_TIMEOUT_MS, parseArgs, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 const JSON_MODE_TOOL = 'json_output';
 export class AnthropicAdapter {
@@ -23,7 +23,8 @@ export class AnthropicAdapter {
     }
     async *stream(conn, req) {
         const started = Date.now();
-        const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+        const nativeJson = modernModel(req.model);
+        const jsonMode = req.responseFormat?.type === 'json' && !nativeJson && !req.tools?.length;
         let firstTokenMs = null;
         let text = '';
         let inputTokens;
@@ -31,6 +32,7 @@ export class AnthropicAdapter {
         let stopReason;
         let sawTerminal = false;
         const emittedTools = [];
+        const responseBlocks = new Map();
         // Partial tool_use blocks keyed by content-block index (input_json_delta accumulation).
         const blocks = new Map();
         const timeout = streamTimeout(conn, req.signal);
@@ -38,19 +40,29 @@ export class AnthropicAdapter {
         // Anthropic JSON mode is implemented as a forced `json_output` tool, which
         // cannot coexist with the caller's own tools — same silent-downgrade shape
         // as Gemini, so it gets the same signal rather than quietly dropping.
-        if (req.responseFormat?.type === 'json' && req.tools?.length) {
+        if (req.responseFormat?.type === 'json' && !nativeJson && req.tools?.length) {
             yield {
                 type: 'context',
                 kind: 'json_mode_downgraded',
                 data: { reason: 'Anthropic JSON mode uses a forced tool and cannot be combined with caller tools; the request was sent without JSON mode', provider: conn.provider },
             };
         }
+        if (req.responseFormat?.type === 'json' && nativeJson && !req.responseFormat.schema) {
+            yield { type: 'context', kind: 'json_mode_downgraded', data: { provider: conn.provider, reason: 'Claude native JSON outputs require a schema; using a JSON instruction without constrained decoding.' } };
+        }
         try {
             const res = await postResponse(`${conn.baseUrl}/v1/messages`, body(req, jsonMode), conn.headers, timeout.signal, conn.provider);
             const contentType = res.headers.get('content-type') ?? '';
             if (!contentType.includes('text/event-stream')) {
                 const data = await res.json();
                 const parsed = parseResponse(data);
+                const content = asRecord(data)?.content;
+                if (Array.isArray(content))
+                    content.forEach((block, i) => {
+                        const record = asRecord(block);
+                        if (record)
+                            responseBlocks.set(i, record);
+                    });
                 inputTokens = parsed.inputTokens;
                 outputTokens = parsed.outputTokens;
                 stopReason = parsed.stopReason;
@@ -77,7 +89,12 @@ export class AnthropicAdapter {
                     if (!record)
                         continue;
                     const type = asString(record.type);
-                    if (type === 'message_start') {
+                    if (type === 'error') {
+                        const error = asRecord(record.error);
+                        const statuses = { overloaded_error: 529, rate_limit_error: 429, authentication_error: 401, permission_error: 403, invalid_request_error: 400, not_found_error: 404, api_error: 500, billing_error: 402, timeout_error: 504, request_too_large: 413 };
+                        throw classify(statuses[asString(error?.type) ?? ''] ?? 500, JSON.stringify(record), conn.provider);
+                    }
+                    else if (type === 'message_start') {
                         const usage = asRecord(asRecord(record.message)?.usage);
                         inputTokens = asNumber(usage?.input_tokens) ?? inputTokens;
                         outputTokens = asNumber(usage?.output_tokens) ?? outputTokens;
@@ -85,6 +102,8 @@ export class AnthropicAdapter {
                     else if (type === 'content_block_start') {
                         const index = asNumber(record.index) ?? 0;
                         const block = asRecord(record.content_block);
+                        if (block)
+                            responseBlocks.set(index, { ...block });
                         if (block?.type === 'tool_use') {
                             blocks.set(index, { id: asString(block.id) ?? randomId(), name: asString(block.name) ?? 'unknown', raw: '' });
                         }
@@ -92,6 +111,14 @@ export class AnthropicAdapter {
                     else if (type === 'content_block_delta') {
                         const index = asNumber(record.index) ?? 0;
                         const delta = asRecord(record.delta);
+                        const block = responseBlocks.get(index);
+                        if (block && delta) {
+                            const field = delta.type === 'text_delta' ? 'text' : delta.type === 'thinking_delta' ? 'thinking' : delta.type === 'signature_delta' ? 'signature' : undefined;
+                            if (field)
+                                block[field] = String(block[field] ?? '') + String(delta[field] ?? '');
+                            if (delta.type === 'citations_delta')
+                                block.citations = [...(Array.isArray(block.citations) ? block.citations : []), delta.citation];
+                        }
                         if (delta?.type === 'text_delta') {
                             const piece = asString(delta.text) ?? '';
                             if (piece) {
@@ -118,6 +145,9 @@ export class AnthropicAdapter {
                         const partial = blocks.get(index);
                         if (partial) {
                             const call = { id: partial.id, name: partial.name, raw: partial.raw, arguments: parseArgs(partial.raw) };
+                            const block = responseBlocks.get(index);
+                            if (block)
+                                block.input = call.arguments;
                             blocks.delete(index);
                             if (jsonMode && call.name === JSON_MODE_TOOL) {
                                 text = jsonTextFrom([call], text);
@@ -149,6 +179,7 @@ export class AnthropicAdapter {
             const hasTools = emittedTools.length > 0;
             yield { type: 'done', result: {
                     text,
+                    providerState: { provider: conn.provider, model: req.model, content: [...responseBlocks.entries()].sort(([a], [b]) => a - b).map(([, block]) => block) },
                     toolCalls: hasTools ? emittedTools : undefined,
                     finishReason: mapStop(stopReason, hasTools),
                     usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
@@ -192,9 +223,15 @@ function body(req, jsonMode) {
         top_p: req.topP,
         stop_sequences: req.stopSequences,
         system,
-        messages: toAnthropicMessages(req.messages.filter((m) => m.role !== 'system')),
+        messages: toAnthropicMessages(req.messages.filter((m) => m.role !== 'system'), req.model),
         stream: true,
     };
+    if (req.responseFormat?.type === 'json' && modernModel(req.model) && req.responseFormat.schema) {
+        base.output_config = { format: { type: 'json_schema', schema: schemaFor(req) } };
+    }
+    if (req.responseFormat?.type === 'json' && modernModel(req.model) && !req.responseFormat.schema) {
+        base.system = [system, 'Return only valid JSON, without markdown fences or a preamble.'].filter(Boolean).join('\n\n');
+    }
     if (jsonMode) {
         // Forced-tool JSON mode: Anthropic has no response_format, so we make the
         // model answer through a single required tool whose input is the JSON we want.
@@ -210,16 +247,51 @@ function body(req, jsonMode) {
         else if (req.toolChoice === 'none')
             base.tool_choice = { type: 'none' };
     }
+    if (req.reasoningEffort !== undefined) {
+        // First-class reasoning effort → extended thinking. Anthropic requires
+        // `budget_tokens < max_tokens` and rejects temperature/top_p alongside
+        // thinking, so the budget is fitted under max_tokens (raising max_tokens
+        // when the caller's value leaves no room) and the samplers are dropped.
+        if (modernModel(req.model)) {
+            const none = req.reasoningEffort === 'none';
+            if (none && alwaysThinking(req.model))
+                throw new AIError('This Claude model cannot disable thinking; choose a reasoning effort instead.', { kind: 'invalid_request', provider: 'anthropic' });
+            base.thinking = { type: none ? (/^claude-sonnet-5-5(?:-|$)/.test(req.model) ? 'between_tools' : 'disabled') : 'adaptive' };
+            base.output_config = { ...asRecord(base.output_config), effort: none ? 'low' : req.reasoningEffort === 'minimal' ? 'low' : req.reasoningEffort };
+        }
+        else if (req.reasoningEffort === 'none') {
+            base.thinking = { type: 'disabled' };
+        }
+        else {
+            const budget = REASONING_BUDGET_TOKENS[req.reasoningEffort];
+            const maxTokens = typeof base.max_tokens === 'number' ? base.max_tokens : 4096;
+            if (maxTokens <= budget)
+                base.max_tokens = budget + 1024;
+            base.thinking = { type: 'enabled', budget_tokens: budget };
+            delete base.temperature;
+            delete base.top_p;
+        }
+    }
     // providerOptions carries Anthropic-native fields (`thinking`, `metadata`,
     // top-level `cache_control` extras, `service_tier`, …) without a release.
-    return applyProviderOptions(base, req.providerOptions);
+    const result = applyProviderOptions(base, req.providerOptions, ['output_config']);
+    if (modernModel(req.model)) {
+        delete result.temperature;
+        delete result.top_p;
+        delete result.top_k;
+    }
+    const choice = asRecord(result.tool_choice);
+    if (noForcedTools(req.model) && (choice?.type === 'tool' || choice?.type === 'any')) {
+        throw new AIError('This Claude model does not support forced tool choice; use auto or structured outputs.', { kind: 'invalid_request', provider: 'anthropic' });
+    }
+    return result;
 }
-function toAnthropicMessages(messages) {
+function toAnthropicMessages(messages, model) {
     const out = [];
     for (let index = 0; index < messages.length; index += 1) {
         const message = messages[index];
         if (message.role !== 'tool') {
-            out.push(toAnthropicMessage(message));
+            out.push(toAnthropicMessage(message, model));
             continue;
         }
         const content = [];
@@ -233,7 +305,10 @@ function toAnthropicMessages(messages) {
     }
     return out;
 }
-function toAnthropicMessage(m) {
+function toAnthropicMessage(m, model) {
+    if (m.role === 'assistant' && m.providerState?.provider === 'anthropic' && m.providerState.model === model) {
+        return { role: 'assistant', content: m.providerState.content };
+    }
     // Tool-role messages are handled by toAnthropicMessages' batching loop and
     // never reach here, so no tool branch is needed.
     // assistant turns that carried tool calls replay them as tool_use blocks,
@@ -298,8 +373,21 @@ function jsonTextFrom(toolCalls, fallback) {
 function mapStop(stop, hasTools) {
     if (stop === 'tool_use' && hasTools)
         return 'tool';
+    if (stop === 'refusal')
+        return 'content_filter';
     if (stop === 'max_tokens')
         return 'length';
     return 'stop';
 }
+/** Models released after Opus 4.6 use adaptive effort and reject sampling knobs.
+ * Unknown/custom IDs retain legacy behavior rather than guessing capabilities. */
+function modernModel(model) {
+    return /^claude-(?:opus-(?:4-[78]|5(?:-5)?)|sonnet-5(?:-5)?|haiku-5-5|(?:fable|mythos)-5(?:-1)?|mythos-preview)(?:-\d{8}|-latest)?$/.test(model);
+}
+function alwaysThinking(model) {
+    return /^claude-(?:fable-|mythos-|opus-5-5(?:-|$))/.test(model);
+}
+function noForcedTools(model) {
+    return /^claude-(?:(?:opus|sonnet)-5-5(?:-|$)|(?:fable|mythos)-5-1(?:-|$))/.test(model);
+}
 //# sourceMappingURL=anthropic.js.map

package/dist/adapters/engines/google.js

@@ -1,7 +1,7 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, postResponse, sseLines } from '../../transport.js';
-import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.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;
@@ -184,6 +184,13 @@ function body(req) {
             config.allowedFunctionNames = [req.toolChoice.name];
         payload.toolConfig = { functionCallingConfig: config };
     }
+    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.

package/dist/adapters/engines/ollama.js

@@ -172,6 +172,12 @@ 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

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

@@ -13,4 +13,10 @@ export declare class OpenAIChatAdapter implements ProviderAdapter {
     }>;
     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

@@ -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), 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.
@@ -169,6 +196,10 @@ function openAiBody(req, profile) {
     };
     if (req.maxTokens !== undefined)
         body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
+    // 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.
@@ -255,4 +286,23 @@ function mapFinish(finish, hasToolCalls) {
         return 'content_filter';
     return 'stop';
 }
+/**
+ * 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/agent/loop.d.ts

@@ -1,5 +1,5 @@
 import type { AIHandler } from '../handler.js';
-import type { AIErrorKind, ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import type { AIErrorKind, ChatMessage, Connection, ReasoningEffort, StreamEvent, ToolCall, Usage } from '../types.js';
 import type { ToolSpec } from './tools.js';
 export interface AgentOptions {
     handler: AIHandler;
@@ -30,6 +30,8 @@ export interface AgentOptions {
     maxTokens?: number;
     topP?: number;
     stopSequences?: string[];
+    /** Reasoning effort forwarded to every turn — see {@link ChatRequest.reasoningEffort}. */
+    reasoningEffort?: ReasoningEffort;
     /** Provider-native passthrough forwarded to every turn — see {@link ChatRequest.providerOptions}. */
     providerOptions?: Record<string, unknown>;
     budget?: {

package/dist/agent/loop.js

@@ -32,6 +32,7 @@ async function* run(opts, resolveResult) {
             yield emit(opts, { type: 'step_start', step });
             const calls = [];
             let stepText = '';
+            let providerState;
             let streamFailure;
             // In promptJson mode a tool directive must not leak into the visible
             // stream, so directive-looking text is withheld from `delta` events (still
@@ -46,6 +47,7 @@ async function* run(opts, resolveResult) {
                 maxTokens: opts.maxTokens,
                 topP: opts.topP,
                 stopSequences: opts.stopSequences,
+                reasoningEffort: opts.reasoningEffort,
                 providerOptions: opts.providerOptions,
                 signal: agentSignal.signal,
                 metadata: { ...opts.metadata, agentStep: step },
@@ -64,6 +66,7 @@ async function* run(opts, resolveResult) {
                 if (event.type === 'error')
                     streamFailure = event.error;
                 if (event.type === 'done') {
+                    providerState = event.result.providerState;
                     usage = usage ? mergeUsage(usage, event.result.usage) : event.result.usage;
                     if (toolMode === 'promptJson' && calls.length === 0)
                         calls.push(...callsFromPromptJson(stepText));
@@ -84,7 +87,7 @@ async function* run(opts, resolveResult) {
             finalText = stepText;
             messages.push(toolMode === 'promptJson'
                 ? { role: 'assistant', content: stepText }
-                : { role: 'assistant', content: stepText, toolCalls: calls.length ? calls : undefined });
+                : { role: 'assistant', content: stepText, providerState, toolCalls: calls.length ? calls : undefined });
             if (calls.length === 0)
                 return yield* yieldDone('finished');
             for (const call of calls) {