@jxburros/ai-nugget 0.6.0 → 0.7.3

package/nugget/src/adapters/engines/anthropic.ts

@@ -1,8 +1,8 @@
-import { AIError } from '../../errors.js';
+import { AIError, classify } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, postResponse, sseLines } from '../../transport.js';
 import type { ChatMessage, ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.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';
@@ -25,7 +25,8 @@ export class AnthropicAdapter implements ProviderAdapter {
 
   async *stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent> {
     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: number | null = null;
     let text = '';
     let inputTokens: number | undefined;
@@ -33,6 +34,7 @@ export class AnthropicAdapter implements ProviderAdapter {
     let stopReason: string | undefined;
     let sawTerminal = false;
     const emittedTools: ToolCall[] = [];
+    const responseBlocks = new Map<number, Record<string, unknown>>();
     // Partial tool_use blocks keyed by content-block index (input_json_delta accumulation).
     const blocks = new Map<number, { id: string; name: string; raw: string }>();
     const timeout = streamTimeout(conn, req.signal);
@@ -40,19 +42,27 @@ export class AnthropicAdapter implements ProviderAdapter {
     // 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() as unknown;
         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;
@@ -74,19 +84,30 @@ export class AnthropicAdapter implements ProviderAdapter {
           const record = asRecord(safeParse(line));
           if (!record) continue;
           const type = asString(record.type);
-          if (type === 'message_start') {
+          if (type === 'error') {
+            const error = asRecord(record.error);
+            const statuses: Record<string, number> = { 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;
           } 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: '' });
             }
           } 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) {
@@ -107,6 +128,8 @@ export class AnthropicAdapter implements ProviderAdapter {
             const partial = blocks.get(index);
             if (partial) {
               const call: ToolCall = { 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);
@@ -132,6 +155,7 @@ export class AnthropicAdapter implements ProviderAdapter {
       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),
@@ -175,9 +199,15 @@ function body(req: ChatRequest, jsonMode: boolean): Record<string, unknown> {
     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.
@@ -189,17 +219,48 @@ function body(req: ChatRequest, jsonMode: boolean): Record<string, unknown> {
     else if (req.toolChoice === 'auto') base.tool_choice = { type: 'auto' };
     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: ChatMessage[]): Record<string, unknown>[] {
+function toAnthropicMessages(messages: ChatMessage[], model: string): Record<string, unknown>[] {
   const out: Record<string, unknown>[] = [];
   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: unknown[] = [];
@@ -214,7 +275,10 @@ function toAnthropicMessages(messages: ChatMessage[]): Record<string, unknown>[]
   return out;
 }
 
-function toAnthropicMessage(m: ChatMessage): Record<string, unknown> {
+function toAnthropicMessage(m: ChatMessage, model: string): Record<string, unknown> {
+  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.
 
@@ -279,7 +343,20 @@ function jsonTextFrom(toolCalls: ToolCall[], fallback: string): string {
 
 function mapStop(stop: string | undefined, hasTools: boolean): ChatResult['finishReason'] {
   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: string): boolean {
+  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: string): boolean {
+  return /^claude-(?:fable-|mythos-|opus-5-5(?:-|$))/.test(model);
+}
+function noForcedTools(model: string): boolean {
+  return /^claude-(?:(?:opus|sonnet)-5-5(?:-|$)|(?:fable|mythos)-5-1(?:-|$))/.test(model);
+}

package/nugget/src/adapters/engines/google.ts

@@ -2,7 +2,7 @@ import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, postResponse, sseLines } from '../../transport.js';
 import type { ChatMessage, ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.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 implements ProviderAdapter {
@@ -178,6 +178,13 @@ function body(req: ChatRequest): Record<string, unknown> {
     if (typeof req.toolChoice === 'object') 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 as Record<string, unknown>).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/nugget/src/adapters/engines/ollama.ts

@@ -165,6 +165,11 @@ function body(req: ChatRequest): Record<string, unknown> {
     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/nugget/src/adapters/engines/openaiChat.ts

@@ -34,7 +34,32 @@ export class OpenAIChatAdapter implements ProviderAdapter {
     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: Response;
+      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: ChatRequest = { ...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.
@@ -161,6 +186,9 @@ function openAiBody(req: ChatRequest, profile: ProviderProfile): Record<string,
     stream_options: profile.quirks?.supportsUsageInStream ? { include_usage: true } : undefined,
   };
   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.
@@ -250,3 +278,20 @@ function mapFinish(finish: string | undefined, hasToolCalls: boolean): ChatResul
   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: unknown, req: ChatRequest): boolean {
+  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');
+}

package/nugget/src/agent/loop.ts

@@ -3,7 +3,7 @@ import { AIError } from '../errors.js';
 import { extractJson } from '../json.js';
 import { mergeUsage } from '../tokens.js';
 import type { AIHandler } from '../handler.js';
-import type { AIErrorKind, ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import type { AIErrorKind, ProviderState, ChatMessage, Connection, ReasoningEffort, StreamEvent, ToolCall, Usage } from '../types.js';
 import { asRecord, sleep } from '../util.js';
 import type { ToolSpec } from './tools.js';
 import { validateToolArgs } from './tools.js';
@@ -37,6 +37,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?: {
@@ -125,6 +127,7 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
 
       const calls: ToolCall[] = [];
       let stepText = '';
+      let providerState: ProviderState | undefined;
       let streamFailure: AIError | undefined;
       // In promptJson mode a tool directive must not leak into the visible
       // stream, so directive-looking text is withheld from `delta` events (still
@@ -139,6 +142,7 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
         maxTokens: opts.maxTokens,
         topP: opts.topP,
         stopSequences: opts.stopSequences,
+        reasoningEffort: opts.reasoningEffort,
         providerOptions: opts.providerOptions,
         signal: agentSignal.signal,
         metadata: { ...opts.metadata, agentStep: step },
@@ -154,6 +158,7 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
         if (event.type === 'tool_call') calls.push(event.call);
         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));
         }
@@ -173,7 +178,7 @@ async function* run(opts: AgentOptions, resolveResult: (result: AgentResult) =>
       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) {

package/nugget/src/handler.ts

@@ -2,6 +2,7 @@ import { adapterFor } from './adapters/index.js';
 import { applyAuth, profileFor } from './adapters/profiles.js';
 import { AIError, fromUnknown } from './errors.js';
 import { extractJson } from './json.js';
+import { containsReasoningBlock, createReasoningStripper, stripReasoningBlocks } from './reasoning.js';
 import { allowAllPolicy } from './policy.js';
 import { SessionRedactor } from './redact.js';
 import type {
@@ -56,6 +57,12 @@ export interface HandlerOptions {
    * explicit `policy: allowAllPolicy()` says the same thing and is clearer.
    */
   silencePolicyWarning?: boolean;
+  /**
+   * Strip inline `<think>…</think>`-style reasoning out of `delta` events and `ChatResult.text`,
+   * emitting it as `{ type: 'reasoning' }` events instead (default `true`; see `src/reasoning.ts`).
+   * Set `false` to receive the raw answer text exactly as the provider sent it.
+   */
+  stripInlineReasoning?: boolean;
   /**
    * Optional cost estimator. Called once per successful call/embedding with the
    * final usage; its return value (USD) is stored on the telemetry record's
@@ -130,8 +137,11 @@ export class AIHandler {
       const maxAttempts = this.opts.retry?.maxAttempts ?? 3;
       let emittedStart = false;
       let emittedOutput = false;
+      const stripInline = this.opts.stripInlineReasoning !== false;
       for (;;) {
         attempt += 1;
+        // One stripper per attempt: a retried stream starts its tag state over.
+        const stripper = stripInline ? createReasoningStripper() : null;
         try {
           for await (const event of adapter.stream(resolved, req)) {
             if (event.type === 'start') {
@@ -141,11 +151,28 @@ export class AIHandler {
               }
               continue;
             }
-            if (event.type === 'delta' || event.type === 'tool_call') emittedOutput = true;
+            if (event.type === 'delta' || event.type === 'tool_call' || event.type === 'reasoning') emittedOutput = true;
+            if (event.type === 'delta' && stripper) {
+              // Inline reasoning never reaches `delta`; it rides the reasoning channel like a
+              // provider-native thinking field would.
+              const piece = stripper.push(event.text);
+              if (piece.reasoning) yield { type: 'reasoning', text: piece.reasoning };
+              if (piece.visible) yield { type: 'delta', text: piece.visible };
+              continue;
+            }
             if (event.type === 'done') {
-              await this.recordSuccess(callId, conn, req, startedAt, attempt, event.result);
+              let result = event.result;
+              if (stripper) {
+                const tail = stripper.end();
+                if (tail.reasoning) yield { type: 'reasoning', text: tail.reasoning };
+                if (tail.visible) yield { type: 'delta', text: tail.visible };
+                if (containsReasoningBlock(result.text)) {
+                  result = { ...result, text: stripReasoningBlocks(result.text) };
+                }
+              }
+              await this.recordSuccess(callId, conn, req, startedAt, attempt, result);
               recorded = true;
-              yield event;
+              yield { ...event, result };
               return;
             }
             yield event;

package/nugget/src/index.ts

@@ -2,6 +2,7 @@ export * from './types.js';
 export * from './errors.js';
 export * from './transport.js';
 export * from './json.js';
+export * from './reasoning.js';
 export * from './tokens.js';
 export * from './keys.js';
 export * from './connect.js';

package/nugget/src/reasoning.ts

@@ -0,0 +1,174 @@
+/**
+ * Inline reasoning stripper — keeps a reasoning model's chain of thought out of `delta` events
+ * and `ChatResult.text`, routing it to the `reasoning` stream event instead.
+ *
+ * Reasoning models (deepseek-r1, phi4-reasoning, qwq, …) emit their thinking either in the
+ * provider's dedicated field — which every engine already maps to `{ type: 'reasoning' }` — or
+ * INLINE in the answer as `<think>…</think>`-style blocks. Inline reasoning routinely quotes the
+ * system prompt and tool instructions back verbatim, so an app that streams `delta` straight to
+ * a screen, a database or a JSON parser leaks it. Every consumer would otherwise write this
+ * state machine, and most would get the split-tag and template-opened cases wrong; the handler
+ * runs it once, on every engine, unless `HandlerOptions.stripInlineReasoning` is `false`.
+ *
+ * Ported from AI Server Studio's `services/reasoningFilter.ts` (2026-09-05), which had to exist
+ * because the nugget did not do this.
+ *
+ * Two subtleties the tests pin:
+ *   - Tags may be split across chunks, so a trailing partial `<thi` is held back until the next
+ *     chunk decides whether it opens a tag. An unterminated block is reasoning to the end.
+ *   - The **orphan close**: a closing tag with no opening one at the head of the stream, because
+ *     the runtime's chat template emitted `<think>` itself. Handled once per stream, only before
+ *     any visible text has gone out, and only when the closing tag starts its own line — a
+ *     `</think>` quoted mid-sentence in a real answer is left alone.
+ */
+
+const TAG_PAIRS: { open: string; close: string }[] = [
+  { open: '<think>', close: '</think>' },
+  { open: '<thinking>', close: '</thinking>' },
+  { open: '<reasoning>', close: '</reasoning>' },
+  { open: '<|begin_of_thought|>', close: '<|end_of_thought|>' },
+];
+
+const LONGEST_TAG = Math.max(...TAG_PAIRS.flatMap((p) => [p.open.length, p.close.length]));
+
+export interface ReasoningStripResult {
+  /** Text safe to show from this chunk (may be empty). */
+  visible: string;
+  /** Reasoning text removed from this chunk (may be empty). */
+  reasoning: string;
+}
+
+export interface ReasoningStripper {
+  /** Feed the next raw delta; returns what may be shown and what was reasoning. */
+  push(chunk: string): ReasoningStripResult;
+  /** End of stream: flushes any held-back prefix that never became a tag. */
+  end(): ReasoningStripResult;
+  /** True while inside an unterminated reasoning block. */
+  readonly inReasoning: boolean;
+}
+
+function partialTagSuffixLength(text: string): number {
+  const lower = text.toLowerCase();
+  const maxLen = Math.min(LONGEST_TAG - 1, lower.length);
+  for (let len = maxLen; len >= 1; len -= 1) {
+    const tail = lower.slice(lower.length - len);
+    if (tail[0] !== '<') continue;
+    for (const pair of TAG_PAIRS) {
+      if (pair.open.startsWith(tail) || pair.close.startsWith(tail)) return len;
+    }
+  }
+  return 0;
+}
+
+function closesOwnLine(text: string, idx: number): boolean {
+  let i = idx - 1;
+  while (i >= 0 && (text[i] === ' ' || text[i] === '\t' || text[i] === '\r')) i -= 1;
+  return i < 0 || text[i] === '\n';
+}
+
+export function createReasoningStripper(): ReasoningStripper {
+  let pending = '';
+  let inReasoning = false;
+  let closeTag = '';
+  let emittedVisible = false;
+  let orphanConsumed = false;
+
+  function process(input: string, flushAll: boolean): ReasoningStripResult {
+    let text = pending + input;
+    pending = '';
+    let visible = '';
+    let reasoning = '';
+
+    while (text.length > 0) {
+      const lower = text.toLowerCase();
+      if (inReasoning) {
+        const idx = lower.indexOf(closeTag);
+        if (idx === -1) {
+          const hold = flushAll ? 0 : partialTagSuffixLength(text);
+          const consumed = text.length - hold;
+          reasoning += text.slice(0, consumed);
+          pending = text.slice(consumed);
+          text = '';
+          if (flushAll) {
+            reasoning += pending;
+            pending = '';
+          }
+          break;
+        }
+        reasoning += text.slice(0, idx);
+        text = text.slice(idx + closeTag.length);
+        inReasoning = false;
+        closeTag = '';
+        if (text.startsWith('\n')) text = text.slice(1);
+        continue;
+      }
+      let openIdx = -1;
+      let pair: { open: string; close: string } | null = null;
+      for (const p of TAG_PAIRS) {
+        const i = lower.indexOf(p.open);
+        if (i !== -1 && (openIdx === -1 || i < openIdx)) {
+          openIdx = i;
+          pair = p;
+        }
+      }
+      let orphanCloseIdx = -1;
+      let orphanCloseLen = 0;
+      if (!emittedVisible && !orphanConsumed) {
+        for (const p of TAG_PAIRS) {
+          const i = lower.indexOf(p.close);
+          if (i !== -1 && (orphanCloseIdx === -1 || i < orphanCloseIdx) && closesOwnLine(text, i)) {
+            orphanCloseIdx = i;
+            orphanCloseLen = p.close.length;
+          }
+        }
+      }
+      if (orphanCloseIdx !== -1 && (openIdx === -1 || orphanCloseIdx < openIdx)) {
+        orphanConsumed = true;
+        reasoning += text.slice(0, orphanCloseIdx);
+        text = text.slice(orphanCloseIdx + orphanCloseLen).replace(/^\n+/, '');
+        continue;
+      }
+      if (openIdx === -1 || !pair) {
+        const hold = flushAll ? 0 : partialTagSuffixLength(text);
+        visible += text.slice(0, text.length - hold);
+        pending = text.slice(text.length - hold);
+        text = '';
+        break;
+      }
+      visible += text.slice(0, openIdx);
+      text = text.slice(openIdx + pair.open.length);
+      inReasoning = true;
+      closeTag = pair.close;
+    }
+    if (visible.trim().length > 0) emittedVisible = true;
+    return { visible, reasoning };
+  }
+
+  return {
+    push: (chunk) => process(chunk, false),
+    end: () => process('', true),
+    get inReasoning() {
+      return inReasoning;
+    },
+  };
+}
+
+/** Whole-string form: `{ visible, reasoning }` for already-buffered text. */
+export function stripReasoningBlocksDetailed(text: string): ReasoningStripResult {
+  if (!text) return { visible: '', reasoning: '' };
+  const stripper = createReasoningStripper();
+  const a = stripper.push(text);
+  const b = stripper.end();
+  return { visible: (a.visible + b.visible).trim(), reasoning: a.reasoning + b.reasoning };
+}
+
+/** Whole-string form returning only the visible text. */
+export function stripReasoningBlocks(text: string): string {
+  return stripReasoningBlocksDetailed(text).visible;
+}
+
+/** Cheap pre-check: does `text` carry any inline reasoning tag (open or close)? */
+export function containsReasoningBlock(text: string): boolean {
+  const lower = text.toLowerCase();
+  return TAG_PAIRS.some((p) => lower.includes(p.open) || lower.includes(p.close));
+}

package/nugget/src/types.ts

@@ -11,9 +11,18 @@ export interface ContentPart {
   mimeType?: string;
 }
 
+/** Opaque provider response content, for replay within the same model/tool workflow.
+ * Keep it unmodified; never include it in telemetry or display it as answer text. */
+export interface ProviderState {
+  provider: string;
+  model: string;
+  content: Record<string, unknown>[];
+}
+
 export interface ChatMessage {
   role: Role;
   content: string | ContentPart[];
+  providerState?: ProviderState;
   toolCalls?: ToolCall[];        // role: 'assistant'
   toolCallId?: string;           // role: 'tool' — answers a specific call
   name?: string;                 // role: 'tool' — the tool's name (Gemini keys
@@ -33,12 +42,29 @@ export interface ToolSchema {
   parameters: object;
 }
 
+/**
+ * How hard a reasoning-capable model should think before answering. The nugget
+ * maps one vocabulary onto each provider's own knob (see `docs/providers.md`,
+ * "Reasoning effort"): OpenAI `reasoning_effort`, Anthropic `thinking`
+ * (`budget_tokens` tiers), Google `generationConfig.thinkingConfig.thinkingBudget`,
+ * Ollama `think`. `'none'` disables reasoning where the provider allows it.
+ * Unset means the provider's own default — the nugget never sends the knob
+ * unasked, because non-reasoning models reject it.
+ */
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high';
+
 export interface ChatRequest {
   model: string;
   messages: ChatMessage[];
   temperature?: number;
   maxTokens?: number;
   topP?: number;
+  /**
+   * Reasoning effort for thinking-capable models — see {@link ReasoningEffort}.
+   * A provider-native value in `providerOptions` (e.g. `reasoning_effort`,
+   * `thinking`, `thinkingConfig`, `think`) wins over this on collision.
+   */
+  reasoningEffort?: ReasoningEffort;
   responseFormat?: { type: 'text' } | { type: 'json'; schema?: object };
   tools?: ToolSchema[];
   toolChoice?: 'auto' | 'none' | { name: string };
@@ -109,6 +135,7 @@ export interface Usage {
 
 export interface ChatResult {
   text: string;
+  providerState?: ProviderState;
   toolCalls?: ToolCall[];
   finishReason: 'stop' | 'length' | 'tool' | 'content_filter' | 'error' | 'canceled';
   usage: Usage;