@jxburros/ai-nugget 0.4.1 → 0.7.0

package/nugget/src/handler.ts

@@ -1,6 +1,8 @@
 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 {
@@ -9,13 +11,18 @@ import type {
   ChatRequest,
   ChatResult,
   Connection,
+  EmbedRequest,
+  EmbedResult,
   GovernancePolicy,
   KeySource,
   ModelInfo,
+  ParsedResult,
   Redactor,
   ResolvedConnection,
+  StandardSchemaV1,
   StreamEvent,
   TelemetrySink,
+  Usage,
 } from './types.js';
 import { promptChars, sleep } from './util.js';
 
@@ -36,7 +43,45 @@ export interface HandlerOptions {
     afterCall?(record: CallRecord): Promise<void>;
   };
   retry?: { maxAttempts?: number; baseDelayMs?: number; maxDelayMs?: number };
+  /**
+   * Concurrency and pacing limits, enforced by an **in-memory queue on this
+   * handler instance only**. There is no shared/external coordination, so N
+   * instances behind a load balancer allow N × `maxConcurrent` in flight against
+   * the provider. Size these per instance, or put a shared limiter in front if a
+   * global ceiling matters.
+   */
   limits?: { maxConcurrent?: number; minIntervalMs?: number };
+  /**
+   * Silence the one-time startup notice logged when no `policy` is supplied.
+   * Set this only when running unrestricted is a deliberate choice — passing an
+   * 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
+   * `costUsd`. Return undefined to leave a call uncosted. Pricing tables live in
+   * the app, not the library — this is only the seam to attach one.
+   */
+  pricing?(info: { provider: string; model: string; usage: Usage }): number | undefined;
+}
+
+/**
+ * A *startup* notice, so it fires once per process rather than once per handler
+ * — an app that builds a handler per request would otherwise flood its logs
+ * with a message that says the same thing every time.
+ */
+let warnedNoPolicy = false;
+
+/** Test seam: reset the once-per-process startup notice. */
+export function resetPolicyWarningForTests(): void {
+  warnedNoPolicy = false;
 }
 
 export class AIHandler {
@@ -48,6 +93,17 @@ export class AIHandler {
 
   constructor(private opts: HandlerOptions) {
     this.policy = opts.policy ?? allowAllPolicy();
+    // `allowAllPolicy()` stays the default — a library must not decide an app's
+    // governance — but "no policy configured" should be visible at runtime, not
+    // only in a README paragraph. Passing an explicit policy (including
+    // `allowAllPolicy()`) is the opt-out.
+    if (!opts.policy && !opts.silencePolicyWarning && !warnedNoPolicy) {
+      warnedNoPolicy = true;
+      globalThis.console?.warn?.(
+        '[ai-nugget] No GovernancePolicy configured — every provider/model is allowed. ' +
+        'Pass `policy` (e.g. allowlistPolicy(...)), or `policy: allowAllPolicy()` / `silencePolicyWarning: true` to accept this deliberately.',
+      );
+    }
   }
 
   async chat(conn: Connection, req: ChatRequest): Promise<ChatResult> {
@@ -64,41 +120,13 @@ export class AIHandler {
     const callId = createCallId();
     const startedAt = Date.now();
     const adapter = adapterFor(conn.provider, conn.baseUrl);
-    const policyResult = this.policy.checkModel(conn.provider, req.model);
-    if (!policyResult.allowed) {
-      const error = new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
 
-    let resolved: ResolvedConnection;
-    try {
-      resolved = await this.resolveConnection(conn);
-    } catch (errorValue) {
-      // Key resolution failures (missing/locked/denied) are a recorded outcome,
-      // not an uncaught throw — the traceability contract covers them too.
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
-    const info: CallInfo = { callId, connection: conn, provider: conn.provider, model: req.model, metadata: req.metadata };
-    try {
-      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
-        const error = new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-        await this.recordFailure(callId, conn, req, startedAt, 1, error);
-        yield { type: 'error', error: this.redactedError(error) };
-        return;
-      }
-    } catch (errorValue) {
-      // A throwing beforeCall hook is a recorded, redacted outcome too — not
-      // an uncaught throw that skips telemetry and the redaction guarantee.
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
+    const preflight = await this.preflight(callId, conn, req.model, req.metadata);
+    if (!preflight.ok) return yield* this.failStream(callId, conn, req, startedAt, 1, preflight.error);
+    // One idempotency key per logical call, reused across every retry attempt,
+    // so a provider that supports it collapses a re-sent generation instead of
+    // billing it twice (see `supportsIdempotencyKey` in the profile table).
+    const resolved = withIdempotencyKey(preflight.resolved, callId);
 
     let acquired = false;
     let recorded = false;
@@ -109,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') {
@@ -121,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;
@@ -132,31 +180,25 @@ export class AIHandler {
           throw new AIError('Provider did not emit a done event', { kind: 'invalid_response', provider: conn.provider });
         } catch (errorValue) {
           const error = fromUnknown(errorValue, conn.provider);
+          // `emittedOutput` stops retries once any byte has reached the caller:
+          // never silently re-run a partially delivered answer.
           if (!error.retryable || attempt >= maxAttempts || req.signal?.aborted || emittedOutput) {
-            await this.recordFailure(callId, conn, req, startedAt, attempt, error);
             recorded = true;
-            yield { type: 'error', error: this.redactedError(error) };
-            return;
+            return yield* this.failStream(callId, conn, req, startedAt, attempt, error);
           }
           const delayMs = this.retryDelay(error, attempt);
           yield { type: 'retry', attempt, reason: error.kind, delayMs };
           try {
             await sleep(delayMs, req.signal);
           } catch (sleepError) {
-            const canceled = fromUnknown(sleepError, conn.provider);
-            await this.recordFailure(callId, conn, req, startedAt, attempt, canceled);
             recorded = true;
-            yield { type: 'error', error: this.redactedError(canceled) };
-            return;
+            return yield* this.failStream(callId, conn, req, startedAt, attempt, fromUnknown(sleepError, conn.provider));
           }
         }
       }
     } catch (errorValue) {
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, Math.max(1, attempt), error);
       recorded = true;
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
+      return yield* this.failStream(callId, conn, req, startedAt, Math.max(1, attempt), fromUnknown(errorValue, conn.provider));
     } finally {
       if (acquired) this.release();
       if (acquired && !recorded) {
@@ -172,6 +214,59 @@ export class AIHandler {
     }
   }
 
+  /**
+   * The shared pre-call preamble: policy check → key resolution → `beforeCall`
+   * hook. Every entry point (`stream`, `embed`, `listModels`/`testConnection`)
+   * runs exactly this sequence, so it lives once. Failures are *returned*, not
+   * recorded — each caller owns its own telemetry shape (`recordFailure` for
+   * chat/probe, `recordEmbed` for embeddings) and records the returned error.
+   */
+  private async preflight(
+    callId: string,
+    conn: Connection,
+    model: string,
+    metadata: Record<string, unknown> | undefined,
+  ): Promise<{ ok: true; resolved: ResolvedConnection } | { ok: false; error: AIError }> {
+    const policyResult = this.policy.checkModel(conn.provider, model);
+    if (!policyResult.allowed) {
+      return { ok: false, error: new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
+    }
+
+    let resolved: ResolvedConnection;
+    try {
+      resolved = await this.resolveConnection(conn);
+    } catch (errorValue) {
+      // Key resolution failures (missing/locked/denied) are a recorded outcome,
+      // not an uncaught throw — the traceability contract covers them too.
+      return { ok: false, error: fromUnknown(errorValue, conn.provider) };
+    }
+
+    try {
+      const info: CallInfo = {
+        callId,
+        connection: safeConnection(conn),
+        provider: conn.provider,
+        model,
+        metadata,
+        resolved: safeResolved(resolved),
+      };
+      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
+        return { ok: false, error: new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
+      }
+    } catch (errorValue) {
+      // A throwing beforeCall hook is a recorded, redacted outcome too — not
+      // an uncaught throw that skips telemetry and the redaction guarantee.
+      return { ok: false, error: fromUnknown(errorValue, conn.provider) };
+    }
+    return { ok: true, resolved };
+  }
+
+  /** Record a failed call and emit the single redacted `error` event for it. */
+  private async *failStream(callId: string, conn: Connection, req: ChatRequest, startedAt: number, attempts: number, error: AIError): AsyncGenerator<StreamEvent> {
+    await this.recordFailure(callId, conn, req, startedAt, attempts, error);
+    yield { type: 'error', error: this.redactedError(error) };
+  }
+
   async listModels(conn: Connection): Promise<ModelInfo[]> {
     return this.runProbe(conn, '__listModels__', async (resolved) => {
       const adapter = adapterFor(conn.provider, conn.baseUrl);
@@ -196,23 +291,112 @@ export class AIHandler {
     }
   }
 
-  private async runProbe<T>(conn: Connection, operation: '__listModels__' | '__testConnection__', action: (resolved: ResolvedConnection) => Promise<T>): Promise<T> {
+  /**
+   * Warm a connection so the first real call doesn't pay cold DNS/TLS and
+   * (for a local daemon) process spin-up on the hot path. Runs a lightweight
+   * health probe and never throws — call it once at boot. Combined with a CJS
+   * `require` path it removes the cold-start "offline" false negative.
+   */
+  async prewarm(conn: Connection): Promise<void> {
+    try {
+      await this.testConnection(conn);
+    } catch {
+      // Warm-up only: a failure here just means the first real call pays the cost.
+    }
+  }
+
+  /**
+   * Chat that returns typed, validated output. Requests JSON mode, extracts the
+   * JSON from the reply, and validates it against any Standard Schema validator
+   * (Zod / Valibot / ArkType). On a validation miss it performs exactly one
+   * corrective retry that shows the model its error, then throws
+   * `invalid_response` if still invalid. No schema library is bundled — the
+   * caller supplies the schema.
+   */
+  async chatParsed<T>(conn: Connection, req: ChatRequest, schema: StandardSchemaV1<T>): Promise<ParsedResult<T>> {
+    const base: ChatRequest = { ...req, responseFormat: req.responseFormat ?? { type: 'json' } };
+    let result = await this.chat(conn, base);
+    let validated = await validateWithSchema(schema, result.text);
+    if (validated.ok) return { data: validated.value, result };
+
+    const retry: ChatRequest = {
+      ...base,
+      messages: [
+        ...base.messages,
+        { role: 'assistant', content: result.text },
+        { role: 'user', content: `That response did not match the required schema (${validated.message}). Reply again with ONLY a valid JSON value that matches it.` },
+      ],
+    };
+    result = await this.chat(conn, retry);
+    validated = await validateWithSchema(schema, result.text);
+    if (validated.ok) return { data: validated.value, result };
+    throw new AIError(`Model output failed schema validation: ${validated.message}`, { kind: 'invalid_response', provider: conn.provider });
+  }
+
+  /**
+   * Produce embeddings through the same governed pipeline as chat: policy check,
+   * key resolution, `beforeCall` hook, concurrency, and exactly one redacted
+   * telemetry record. Throws a typed `invalid_request` error for providers whose
+   * adapter has no `embed` (Anthropic, Google) rather than failing silently.
+   */
+  async embed(conn: Connection, req: EmbedRequest): Promise<EmbedResult> {
     const callId = createCallId();
     const startedAt = Date.now();
-    const req: ChatRequest = { model: operation, messages: [], metadata: { operation } };
-    const policyResult = this.policy.checkModel(conn.provider, operation);
-    if (!policyResult.allowed) {
-      const error = new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
+    const inputChars = (Array.isArray(req.input) ? req.input : [req.input]).reduce((sum, text) => sum + text.length, 0);
+    const fail = async (error: AIError): Promise<never> => {
+      await this.recordEmbed(callId, conn, req, startedAt, { estimated: true }, inputChars, error);
       throw this.redactedError(error);
+    };
+
+    const preflight = await this.preflight(callId, conn, req.model, req.metadata);
+    if (!preflight.ok) return fail(preflight.error);
+    const resolved = preflight.resolved;
+
+    const adapter = adapterFor(conn.provider, conn.baseUrl);
+    if (!adapter.embed) {
+      return fail(new AIError(`Provider ${conn.provider} does not support embeddings`, { kind: 'invalid_request', retryable: false, provider: conn.provider }));
     }
-    let resolved: ResolvedConnection;
+
+    await this.acquire(req.signal);
     try {
-      resolved = await this.resolveConnection(conn);
-      const info: CallInfo = { callId, connection: conn, provider: conn.provider, model: operation, metadata: req.metadata };
-      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
-        throw new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      }
+      const result = await adapter.embed(resolved, req);
+      await this.recordEmbed(callId, conn, req, startedAt, result.usage, inputChars);
+      return result;
+    } catch (errorValue) {
+      return fail(fromUnknown(errorValue, conn.provider));
+    } finally {
+      this.release();
+    }
+  }
+
+  private async recordEmbed(callId: string, conn: Connection, req: EmbedRequest, startedAt: number, usage: Usage, inputChars: number, error?: AIError): Promise<void> {
+    const costUsd = error ? undefined : this.opts.pricing?.({ provider: conn.provider, model: req.model, usage });
+    await this.record({
+      callId,
+      connectionId: conn.id,
+      provider: conn.provider,
+      model: req.model,
+      startedAt,
+      timing: { firstTokenMs: null, totalMs: Date.now() - startedAt },
+      usage,
+      finishReason: error ? (error.kind === 'canceled' ? 'canceled' : 'error') : 'stop',
+      ...(error ? { error: { kind: error.kind, status: error.status, message: error.message } } : {}),
+      attempts: 1,
+      metadata: { ...req.metadata, operation: '__embed__' },
+      promptChars: inputChars,
+      responseChars: 0,
+      ...(costUsd !== undefined ? { costUsd } : {}),
+    });
+  }
+
+  private async runProbe<T>(conn: Connection, operation: '__listModels__' | '__testConnection__', action: (resolved: ResolvedConnection) => Promise<T>): Promise<T> {
+    const callId = createCallId();
+    const startedAt = Date.now();
+    const req: ChatRequest = { model: operation, messages: [], metadata: { operation } };
+    try {
+      const preflight = await this.preflight(callId, conn, operation, req.metadata);
+      if (!preflight.ok) throw preflight.error;
+      const resolved = preflight.resolved;
       await this.acquire(undefined);
       try {
         const value = await action(resolved);
@@ -309,6 +493,7 @@ export class AIHandler {
   }
 
   private async recordSuccess(callId: string, conn: Connection, req: ChatRequest, startedAt: number, attempts: number, result: ChatResult): Promise<void> {
+    const costUsd = this.opts.pricing?.({ provider: conn.provider, model: req.model, usage: result.usage });
     await this.record({
       callId,
       connectionId: conn.id,
@@ -322,6 +507,7 @@ export class AIHandler {
       metadata: req.metadata,
       promptChars: promptChars(req.messages),
       responseChars: result.text.length,
+      ...(costUsd !== undefined ? { costUsd } : {}),
     });
   }
 
@@ -408,6 +594,69 @@ function trimSlash(value: string): string {
   return value.replace(/\/+$/, '');
 }
 
+/**
+ * Drops the resolved API key *and* neutralizes the auth headers built from it,
+ * so a `beforeCall` hook can inspect the endpoint but never the secret.
+ * `keyRef` is scrubbed too — a `{ kind: 'literal' }` ref carries the plaintext
+ * key, and hooks routinely log the whole object.
+ */
+function safeResolved(resolved: ResolvedConnection): Omit<ResolvedConnection, 'apiKey'> {
+  const { apiKey: _apiKey, headers, ...rest } = resolved;
+  return { ...rest, ...safeKeyRef(resolved), headers: maskAuthHeaders(headers) };
+}
+
+/**
+ * The caller's own `Connection`, with any plaintext `keyRef` masked. Hooks get
+ * the connection so they can key off `id`/`provider`/`baseUrl`; they must never
+ * be handed the secret, since logging `info.connection` for audit is the
+ * obvious thing to do and would otherwise ship the key in clear text.
+ */
+function safeConnection(conn: Connection): Connection {
+  return { ...conn, ...safeKeyRef(conn) };
+}
+
+function safeKeyRef(conn: Connection): { keyRef?: Connection['keyRef'] } {
+  if (conn.keyRef?.kind !== 'literal') return conn.keyRef === undefined ? {} : { keyRef: conn.keyRef };
+  return { keyRef: { kind: 'literal', value: REDACTED } };
+}
+
+const REDACTED = '[REDACTED]';
+
+/** Header names whose value is derived from the API key by {@link applyAuth}. */
+const AUTH_HEADERS = new Set(['authorization', 'x-api-key', 'x-goog-api-key', 'api-key']);
+
+function maskAuthHeaders(headers: Record<string, string>): Record<string, string> {
+  const masked: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    masked[name] = AUTH_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+  }
+  return masked;
+}
+
+/**
+ * Attach a per-call `Idempotency-Key` for providers that honor one, so a retry
+ * after a dropped connection can't be billed as a second generation. Only set
+ * where the profile declares support, and never overrides a caller-supplied
+ * header.
+ */
+function withIdempotencyKey(resolved: ResolvedConnection, callId: string): ResolvedConnection {
+  const profile = profileFor(resolved.provider, resolved.baseUrl);
+  if (!profile.quirks?.supportsIdempotencyKey) return resolved;
+  if (Object.keys(resolved.headers).some((name) => name.toLowerCase() === 'idempotency-key')) return resolved;
+  return { ...resolved, headers: { ...resolved.headers, 'idempotency-key': callId } };
+}
+
+async function validateWithSchema<T>(schema: StandardSchemaV1<T>, text: string): Promise<{ ok: true; value: T } | { ok: false; message: string }> {
+  const value = extractJson(text);
+  if (value === null) return { ok: false, message: 'no JSON found in model output' };
+  const result = await schema['~standard'].validate(value);
+  if (result.issues) {
+    const message = result.issues.map((issue) => issue.message).join('; ');
+    return { ok: false, message: message || 'validation failed' };
+  }
+  return { ok: true, value: result.value };
+}
+
 function createCallId(): string {
   return globalThis.crypto?.randomUUID?.() ?? `call_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }

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));
+}