@jxburros/ai-nugget 0.6.0 → 0.7.0

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, 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?: {
@@ -139,6 +141,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 },

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') {
@@ -142,10 +152,27 @@ export class AIHandler {
               continue;
             }
             if (event.type === 'delta' || event.type === 'tool_call') 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

@@ -33,12 +33,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 };

package/nugget/src/util.ts

@@ -104,3 +104,17 @@ export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
     }
   });
 }
+
+/**
+ * Token budgets behind the {@link ReasoningEffort} tiers for providers that
+ * express effort as a thinking-token budget (Anthropic `budget_tokens`, Google
+ * `thinkingBudget`). `'none'` is 0. Deliberately conservative: they are floors
+ * a model may stop under, not ceilings it fills.
+ */
+export const REASONING_BUDGET_TOKENS: Record<'none' | 'minimal' | 'low' | 'medium' | 'high', number> = {
+  none: 0,
+  minimal: 1024,
+  low: 2048,
+  medium: 8192,
+  high: 16384,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxburros/ai-nugget",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Small isomorphic AI model nugget for provider calls, policy, redaction, telemetry, and agent loops.",