@librechat/agents 4.0.1 → 4.0.3

package/src/llm/providerTextBoundary.ts

@@ -0,0 +1,446 @@
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { RunnableBinding, RunnableSequence } from '@langchain/core/runnables';
+import { AIMessage, AIMessageChunk, mergeContent } from '@langchain/core/messages';
+import type { MessageContentComplex } from '@langchain/core/messages';
+import type { ChatResult } from '@langchain/core/outputs';
+import type { ProviderTextProtection } from '@/protection/providerText';
+import type { ChatModel, ProviderName } from '@/types';
+import {
+  getStreamedToolCallAdapter,
+  getStreamedToolCallSeal,
+  STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY,
+  STREAMED_TOOL_CALL_SEAL_METADATA_KEY,
+} from '@/tools/streamedToolCallSeals';
+import { GEMINI_SIGNATURES, RESPONSES_POSITIONS, stringMap, safetyRatings, replayPositions, ResponsesTextProjection, keys } from '@/llm/providerTextControls';
+import {
+  ProviderTextAttempt,
+  ProviderTextProtectionError,
+} from '@/protection/providerText';
+import { isProviderTextInput } from '@/protection/providerTextInput';
+import { createProviderTextChunk } from '@/llm/providerTextChunk';
+import { getChatModelClass } from '@/llm/providers';
+import { Providers } from '@/common';
+
+const additionalKeys = new Set([
+  'tool_calls',
+  'function_call',
+  'reasoning',
+  'reasoning_content',
+  'reasoning_details',
+  'thinking',
+  'signature',
+]);
+const metadataKeys = new Set([
+  'finish_reason', 'stop_reason', 'stop_sequence', 'model_name', 'model', 'model_provider',
+  'system_fingerprint', 'service_tier', 'usage', 'tokenUsage', 'input_tokens', 'output_tokens',
+  'total_tokens', 'index', 'prompt', 'completion', 'output_version',
+]);
+const additionalControls: Readonly<Partial<Record<string, (value: unknown) => boolean>>> = {
+  id: (value) => typeof value === 'string',
+  type: (value) => value === 'message',
+  role: (value) => value === 'assistant',
+  model: (value) => typeof value === 'string',
+  stop_reason: (value) => value == null || typeof value === 'string',
+  stop_sequence: (value) => value == null || typeof value === 'string',
+  usage: (value) => numericMetadata(value),
+};
+
+const geminiControls: Readonly<Partial<Record<string, (value: unknown) => boolean>>> = {
+  [GEMINI_SIGNATURES]: stringMap,
+  finishReason: (value) => ['STOP', 'MAX_TOKENS', 'SAFETY', 'RECITATION', 'OTHER', 'MALFORMED_FUNCTION_CALL', 'FINISH_REASON_UNSPECIFIED'].includes(String(value)),
+  safetyRatings,
+  avgLogprobs: (value) => typeof value === 'number' && Number.isFinite(value),
+  index: (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0,
+};
+
+const controlBlocks = new Set([
+  'thinking',
+  'redacted_thinking',
+  'reasoning',
+  'reasoning_content',
+  'tool_use',
+]);
+
+type TextBlock = MessageContentComplex & {
+  type: 'text';
+  text: string;
+  index?: number;
+};
+
+function copyMessage(
+  message: AIMessage | AIMessageChunk,
+  content: AIMessageChunk['content']
+): AIMessageChunk {
+  const copied = createProviderTextChunk(message, {
+    content,
+    id: message.id,
+    name: message.name,
+    additional_kwargs: message.additional_kwargs,
+    response_metadata: message.response_metadata,
+    tool_calls: message.tool_calls,
+    tool_call_chunks: message instanceof AIMessageChunk ? message.tool_call_chunks : undefined,
+    invalid_tool_calls: message.invalid_tool_calls,
+    usage_metadata: message.usage_metadata,
+  });
+  // Core resets native diagnostics when no argument chunks are present.
+  copied.invalid_tool_calls = message.invalid_tool_calls ?? [];
+  copied.lc_kwargs.invalid_tool_calls = copied.invalid_tool_calls;
+  return copied;
+}
+
+function numericMetadata(value: unknown, depth = 4): boolean {
+  if (value == null) return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value !== 'object' || Array.isArray(value) || depth === 0) return false;
+  const values = Object.values(value);
+  return values.length <= 64 && values.every((entry) => numericMetadata(entry, depth - 1));
+}
+
+function hasKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value) &&
+    Object.keys(value).every((key) => keys.includes(key));
+}
+
+function validateMetadata(metadata: AIMessageChunk['response_metadata'], google = false): void {
+  for (const key of Object.keys(metadata)) {
+    const value: unknown = metadata[key];
+    let valid: boolean;
+    if (google && geminiControls[key] != null) {
+      valid = geminiControls[key](value);
+    } else if (additionalControls[key] != null) {
+      valid = additionalControls[key](value);
+    } else if (key === 'contentBlockIndex') {
+      valid = typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+    } else if (key === STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY) {
+      valid = getStreamedToolCallAdapter(metadata) != null;
+    } else if (key === STREAMED_TOOL_CALL_SEAL_METADATA_KEY) {
+      valid = hasKeys(value, ['kind', 'id', 'index']) && getStreamedToolCallSeal(metadata) != null;
+    } else if (key === 'messageStart') {
+      valid = hasKeys(value, ['role']) && value.role === 'assistant';
+    } else if (key === 'messageStop') {
+      valid = hasKeys(value, ['stopReason']) && typeof value.stopReason === 'string';
+    } else if (key === 'metadata') {
+      valid = hasKeys(value, ['usage', 'metrics']) && numericMetadata(value);
+    } else if (key === 'usage' || key === 'tokenUsage' || key === 'estimatedTokenUsage') {
+      valid = numericMetadata(value);
+    } else {
+      valid = metadataKeys.has(key) && (value == null || typeof value === 'string' ||
+        (typeof value === 'number' && Number.isFinite(value)));
+    }
+    if (!valid) throw new ProviderTextProtectionError('unsupported');
+  }
+}
+
+class Candidate {
+  private block?: TextBlock;
+  private stringContent = false;
+  private readonly toolInputIndices = new Set<number>();
+  private readonly responses: ResponsesTextProjection;
+
+  constructor(private readonly attempt: ProviderTextAttempt, private readonly provider?: ProviderName) { this.responses = new ResponsesTextProjection(attempt); }
+
+  strip(generation: ChatGenerationChunk): ChatGenerationChunk {
+    const message = generation.message;
+    if (!(message instanceof AIMessageChunk))
+      throw new ProviderTextProtectionError('unsupported');
+    this.attempt.observeChunk();
+    for (const key of Object.keys(message.additional_kwargs)) {
+      if (additionalKeys.has(key)) continue;
+      const validate = (this.provider === Providers.GOOGLE ? geminiControls[key] : undefined) ??
+        (key === RESPONSES_POSITIONS ? replayPositions : undefined) ??
+        (key === '__openai_function_call_ids__' ? stringMap : undefined) ?? additionalControls[key];
+      if (validate == null || !validate(message.additional_kwargs[key])) {
+        throw new ProviderTextProtectionError('unsupported');
+      }
+    }
+    let content: AIMessageChunk['content'];
+    if (typeof message.content === 'string') {
+      if (message.content && this.block != null)
+        throw new ProviderTextProtectionError('unsupported');
+      this.stringContent ||= message.content.length > 0;
+      const details = message.additional_kwargs.reasoning_details;
+      this.attempt.append(message.content, this.provider === Providers.OPENROUTER && Array.isArray(details) && details.length > 0);
+      content = '';
+    } else {
+      content = [];
+      for (const block of message.content) {
+        if (typeof block === 'string')
+          throw new ProviderTextProtectionError('unsupported');
+        if (block.type !== 'text') {
+          this.admitControl(block, message);
+          content.push(block);
+          continue;
+        }
+        if (
+          typeof block.text !== 'string' ||
+          this.stringContent ||
+          Object.keys(block).some(
+            (key) => !['type', 'text', 'index', 'annotations', 'phase'].includes(key)
+          ) ||
+          ('annotations' in block && (!Array.isArray(block.annotations) || block.annotations.length > 0)) ||
+          ('phase' in block && block.phase != null && !['commentary', 'final_answer'].includes(String(block.phase)))
+        ) {
+          throw new ProviderTextProtectionError('unsupported');
+        }
+        if (this.block != null && this.block.index !== block.index) {
+          throw new ProviderTextProtectionError('unsupported');
+        }
+        this.block ??= { ...block, text: '' } as TextBlock;
+        this.attempt.append(block.text);
+      }
+    }
+    const metadata = this.responses.strip(message.response_metadata);
+    if (!Object.hasOwn(message.response_metadata, 'output')) validateMetadata(metadata, this.provider === Providers.GOOGLE);
+    validateMetadata(generation.generationInfo ?? {}, this.provider === Providers.GOOGLE);
+    const stripped = copyMessage(message, content);
+    stripped.response_metadata = metadata;
+    stripped.lc_kwargs.response_metadata = metadata;
+    return new ChatGenerationChunk({ text: '', message: stripped, generationInfo: generation.generationInfo });
+  }
+
+  private admitControl(block: MessageContentComplex, message: AIMessageChunk): void {
+    const control: { type?: string; index?: unknown; input?: unknown; id?: unknown; name?: unknown } = block;
+    const { type, index, input, id, name } = control;
+    const part: unknown = block;
+    if (this.provider === Providers.GOOGLE && keys(part, ['functionCall', 'thoughtSignature']) &&
+        keys(part.functionCall, ['name', 'args', 'id'])) {
+      const call = part.functionCall;
+      if (typeof call.name !== 'string' || (part.thoughtSignature != null && typeof part.thoughtSignature !== 'string') ||
+          message.tool_calls?.some((tool) => tool.name === call.name && JSON.stringify(tool.args) === JSON.stringify(call.args)) !== true) {
+        throw new ProviderTextProtectionError('unsupported');
+      }
+      return;
+    }
+    if (!Object.hasOwn(block, 'type')) {
+      if (!hasKeys(block, ['index', 'input']) || typeof index !== 'number' ||
+          !Number.isSafeInteger(index) || index < 0 || typeof input !== 'string' ||
+          !this.toolInputIndices.has(index) ||
+          message.tool_call_chunks?.some((call) => call.index === index && call.args === input) !== true) {
+        throw new ProviderTextProtectionError('unsupported');
+      }
+      return;
+    }
+    if (type == null || !controlBlocks.has(type)) throw new ProviderTextProtectionError('unsupported');
+    if (type === 'tool_use' && index != null) {
+      if (typeof index !== 'number' || !Number.isSafeInteger(index) || index < 0 ||
+          message.tool_call_chunks?.some((call) => call.index === index && call.id === id && call.name === name) !== true) {
+        throw new ProviderTextProtectionError('unsupported');
+      }
+      if (!this.toolInputIndices.has(index)) {
+        this.attempt.observeChunk();
+        this.toolInputIndices.add(index);
+      }
+    }
+  }
+
+  async canonical(): Promise<ChatGenerationChunk | undefined> {
+    const content = await this.attempt.release();
+    const metadata = this.responses.canonical(content);
+    if (!content && metadata == null) return undefined;
+    return new ChatGenerationChunk({
+      text: content,
+      message: new AIMessageChunk({
+        content:
+          this.block == null ? content : [{ ...this.block, text: content }],
+        response_metadata: metadata,
+      }),
+    });
+  }
+}
+
+function clone<T extends object>(value: T): T {
+  return Object.create(
+    Object.getPrototypeOf(value),
+    Object.getOwnPropertyDescriptors(value)
+  ) as T;
+}
+
+function assertBindingShell(model: RunnableBinding<never, unknown>): void {
+  if (model.constructor !== RunnableBinding || (model.configFactories?.length ?? 0) > 0 ||
+      model.invoke !== RunnableBinding.prototype.invoke || model.batch !== RunnableBinding.prototype.batch ||
+      model.stream !== RunnableBinding.prototype.stream || model.transform !== RunnableBinding.prototype.transform ||
+      model._streamIterator !== RunnableBinding.prototype._streamIterator) {
+    throw new ProviderTextProtectionError('unsupported');
+  }
+}
+
+function assertInputStep(input: object): void {
+  if (isProviderTextInput(input)) return;
+  if (input instanceof RunnableBinding) {
+    assertBindingShell(input);
+    assertInputStep(input.bound);
+    return;
+  }
+  throw new ProviderTextProtectionError('unsupported');
+}
+
+function hasStreamingInvocation(
+  model: BaseChatModel,
+  options?: BaseChatModel['ParsedCallOptions']
+): boolean {
+  if ('streaming' in model && model.streaming === true) return true;
+  const params: unknown = model.invocationParams(options);
+  if (params == null || typeof params !== 'object' || Array.isArray(params)) {
+    throw new ProviderTextProtectionError('unsupported');
+  }
+  return 'stream' in params && params.stream != null && params.stream !== false;
+}
+
+function usesInternalStreaming(
+  model: BaseChatModel,
+  options?: BaseChatModel['ParsedCallOptions']
+): boolean {
+  if (hasStreamingInvocation(model, options)) return true;
+  for (const key of ['completions', 'responses'] as const) {
+    const delegate: unknown = Reflect.get(model, key);
+    if (delegate instanceof BaseChatModel && hasStreamingInvocation(delegate, options)) return true;
+  }
+  return false;
+}
+
+/** Clone only known runnable shells. Never mutate a shared provider or its callback configuration. */
+export function withProviderTextBoundary(
+  model: ChatModel,
+  policy: ProviderTextProtection,
+  provider?: ProviderName
+): ChatModel {
+  const protectedModel = clone(model);
+  if (model instanceof RunnableBinding) {
+    assertBindingShell(model);
+    Object.defineProperty(protectedModel, 'bound', {
+      value: withProviderTextBoundary(model.bound as ChatModel, policy, provider),
+    });
+    return protectedModel;
+  }
+  if (model instanceof RunnableSequence) {
+    if (model.constructor !== RunnableSequence ||
+        model.invoke !== RunnableSequence.prototype.invoke || model.batch !== RunnableSequence.prototype.batch ||
+        model.stream !== RunnableSequence.prototype.stream || model.transform !== RunnableSequence.prototype.transform ||
+        model._streamIterator !== RunnableSequence.prototype._streamIterator) {
+      throw new ProviderTextProtectionError('unsupported');
+    }
+    const steps = model.steps;
+    for (let index = 0; index < steps.length - 1; index++) assertInputStep(steps[index]);
+    Object.defineProperty(protectedModel, 'last', {
+      value: withProviderTextBoundary(
+        steps[steps.length - 1] as ChatModel,
+        policy,
+        provider
+      ),
+    });
+    return protectedModel;
+  }
+  if (!(model instanceof BaseChatModel) || model.cache != null) {
+    throw new ProviderTextProtectionError('unsupported');
+  }
+  if (model.transform !== BaseChatModel.prototype.transform ||
+      model._streamIterator !== BaseChatModel.prototype._streamIterator ||
+      model.generate !== BaseChatModel.prototype.generate ||
+      model.generatePrompt !== BaseChatModel.prototype.generatePrompt ||
+      model._generateUncached !== BaseChatModel.prototype._generateUncached) {
+    throw new ProviderTextProtectionError('unsupported');
+  }
+  if (model.stream !== BaseChatModel.prototype.stream || model.invoke !== BaseChatModel.prototype.invoke) {
+    const openAI = getChatModelClass(Providers.OPENAI);
+    if (model.stream !== openAI.prototype.stream || model.invoke !== openAI.prototype.invoke) {
+      throw new ProviderTextProtectionError('unsupported');
+    }
+  }
+  if (model.disableStreaming && usesInternalStreaming(model)) {
+    throw new ProviderTextProtectionError('unsupported');
+  }
+  const protectedChat = clone(model);
+  protectedChat._streamResponseChunks = async function* (
+    messages,
+    options,
+    runManager
+  ): AsyncGenerator<ChatGenerationChunk> {
+    const attempt = new ProviderTextAttempt(policy, options.signal);
+    const candidate = new Candidate(attempt, provider);
+    let source: AsyncGenerator<ChatGenerationChunk> | undefined;
+    try {
+      source = model._streamResponseChunks(
+        messages,
+        { ...options, signal: attempt.signal },
+        undefined
+      );
+      for (;;) {
+        const next = await attempt.wait(source.next());
+        attempt.check();
+        if (next.done === true) break;
+        const chunk = candidate.strip(next.value);
+        yield chunk;
+        await runManager?.handleLLMNewToken(
+          '',
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          { chunk }
+        );
+      }
+      const canonical = await candidate.canonical();
+      attempt.check();
+      if (canonical != null) {
+        yield canonical;
+        attempt.check();
+        await runManager?.handleLLMNewToken(
+          canonical.text,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          { chunk: canonical }
+        );
+      }
+    } finally {
+      try {
+        if (source != null) void attempt.wait(source.return(undefined)).catch(() => {});
+      } finally {
+        attempt.finish();
+      }
+    }
+  };
+  protectedChat._streamChatModelEvents =
+    BaseChatModel.prototype._streamChatModelEvents;
+  protectedChat._generate = async function (messages, options): Promise<ChatResult> {
+    if (usesInternalStreaming(model, options)) throw new ProviderTextProtectionError('unsupported');
+    const attempt = new ProviderTextAttempt(policy, options.signal);
+    try {
+      const result = await attempt.wait(
+        model._generate(
+          messages,
+          { ...options, signal: attempt.signal },
+          undefined
+        )
+      );
+      attempt.check();
+      if (result.llmOutput != null) validateMetadata(result.llmOutput, provider === Providers.GOOGLE);
+      if (result.generations.length !== 1)
+        throw new ProviderTextProtectionError('unsupported');
+      const generation = result.generations[0];
+      if (!(generation.message instanceof AIMessage)) throw new ProviderTextProtectionError('unsupported');
+      const message = generation.message instanceof AIMessageChunk ? generation.message : copyMessage(generation.message, generation.message.content);
+      const candidate = new Candidate(attempt, provider);
+      const stripped = candidate.strip(
+        new ChatGenerationChunk({ ...generation, message })
+      );
+      const canonical = await candidate.canonical();
+      attempt.check();
+      const released = canonical == null ? stripped : new ChatGenerationChunk({
+        text: canonical.text,
+        message: copyMessage(stripped.message as AIMessageChunk, mergeContent(stripped.message.content, canonical.message.content)),
+        generationInfo: stripped.generationInfo,
+      });
+      if (canonical != null) {
+        released.message.response_metadata = { ...released.message.response_metadata, ...canonical.message.response_metadata };
+        released.message.lc_kwargs.response_metadata = released.message.response_metadata;
+      }
+      return { ...result, generations: [released] };
+    } finally {
+      attempt.finish();
+    }
+  };
+  return protectedChat;
+}

package/src/llm/providerTextChunk.ts

@@ -0,0 +1,15 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import type { AIMessageChunkFields } from '@langchain/core/messages';
+
+type ChunkConstructor = new (fields: AIMessageChunkFields) => AIMessageChunk;
+const constructors = new WeakMap<object, ChunkConstructor>();
+
+/** Internal certification for SDK-owned aggregation semantics, not arbitrary provider subclasses. */
+export function registerProviderTextChunkConstructor(constructor: ChunkConstructor): void {
+  constructors.set(constructor.prototype, constructor);
+}
+
+export function createProviderTextChunk(source: object, fields: AIMessageChunkFields): AIMessageChunk {
+  const constructor = constructors.get(Object.getPrototypeOf(source)) ?? AIMessageChunk;
+  return new constructor(fields);
+}

package/src/llm/providerTextControls.ts

@@ -0,0 +1,173 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { ProviderTextAttempt } from '@/protection/providerText';
+import { ProviderTextProtectionError } from '@/protection/providerText';
+
+export const GEMINI_SIGNATURES = '__gemini_function_call_thought_signatures__';
+export const RESPONSES_POSITIONS = '__openai_responses_replay_positions__';
+
+export function keys(value: unknown, allowed: readonly string[]): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value) &&
+    Object.keys(value).every((key) => allowed.includes(key));
+}
+
+export function stringMap(value: unknown): boolean {
+  return value != null && typeof value === 'object' && !Array.isArray(value) &&
+    Object.entries(value).length <= 128 && Object.values(value).every((entry) => typeof entry === 'string');
+}
+
+export function safetyRatings(value: unknown): boolean {
+  return Array.isArray(value) && value.length <= 16 && value.every((entry: unknown) =>
+    keys(entry, ['category', 'probability', 'blocked']) &&
+    typeof entry.category === 'string' && /^HARM_CATEGORY_[A-Z_]+$/.test(entry.category) &&
+    ['NEGLIGIBLE', 'LOW', 'MEDIUM', 'HIGH', 'HARM_PROBABILITY_UNSPECIFIED'].includes(String(entry.probability)) &&
+    (entry.blocked == null || typeof entry.blocked === 'boolean'));
+}
+
+export function replayPositions(value: unknown): boolean {
+  return Array.isArray(value) && value.length <= 128 && value.every((entry: unknown) =>
+    keys(entry, ['itemId', 'kind', 'outputIndex', 'contentIndex']) && typeof entry.itemId === 'string' &&
+    ['message', 'text', 'reasoning', 'output'].includes(String(entry.kind)) &&
+    typeof entry.outputIndex === 'number' && Number.isSafeInteger(entry.outputIndex) && entry.outputIndex >= 0 &&
+    (entry.contentIndex == null || (typeof entry.contentIndex === 'number' && Number.isSafeInteger(entry.contentIndex) && entry.contentIndex >= 0)));
+}
+
+const scalarKeys = new Set([
+  'id', 'model', 'model_name', 'model_provider', 'created_at', 'object', 'status', 'user', 'service_tier',
+  'max_output_tokens', 'max_tool_calls', 'parallel_tool_calls', 'temperature', 'top_p', 'truncation',
+  'store', 'background', 'previous_response_id', 'prompt_cache_key', 'prompt_cache_retention',
+  'safety_identifier', 'completed_at',
+]);
+
+interface OutputText {
+  type: 'output_text';
+  text: string;
+  annotations: [];
+  logprobs?: [];
+}
+interface MessageOutput {
+  type: 'message';
+  id: string;
+  role: 'assistant';
+  status: 'completed' | 'incomplete';
+  phase?: 'commentary' | 'final_answer' | null;
+  content: [OutputText];
+}
+
+function messageOutput(value: unknown): value is MessageOutput {
+  if (!keys(value, ['id', 'type', 'role', 'status', 'phase', 'content']) || value.type !== 'message' ||
+      typeof value.id !== 'string' || value.role !== 'assistant' || !['completed', 'incomplete'].includes(String(value.status)) ||
+      (value.phase != null && !['commentary', 'final_answer'].includes(String(value.phase))) ||
+      !Array.isArray(value.content) || value.content.length !== 1) return false;
+  const part: unknown = value.content[0];
+  return keys(part, ['type', 'text', 'annotations', 'logprobs']) && part.type === 'output_text' &&
+    typeof part.text === 'string' && Array.isArray(part.annotations) && part.annotations.length === 0 &&
+    (part.logprobs === undefined || (Array.isArray(part.logprobs) && part.logprobs.length === 0));
+}
+
+/** One certified prose output. Unknown structured outputs and alternate aliases stay gated. */
+export class ResponsesTextProjection {
+  private metadata?: AIMessageChunk['response_metadata'];
+  private hasOutputAlias = false;
+  private output?: Array<MessageOutput | Record<string, unknown>>;
+
+  constructor(private readonly attempt: ProviderTextAttempt) {}
+
+  strip(metadata: AIMessageChunk['response_metadata']): AIMessageChunk['response_metadata'] {
+    if (!Object.hasOwn(metadata, 'output')) return metadata;
+    if (this.metadata != null || metadata.model_provider !== 'openai' || metadata.object !== 'response' ||
+        !Array.isArray(metadata.output) || metadata.output.length > 32) {
+      throw new ProviderTextProtectionError('unsupported');
+    }
+    let messageCount = 0;
+    const output: Array<MessageOutput | Record<string, unknown>> = metadata.output.map((item: unknown) => {
+      if (messageOutput(item)) {
+        if (++messageCount > 1 || !this.attempt.matchesText(item.content[0].text)) throw new ProviderTextProtectionError('unsupported');
+        return { ...item, content: [{ ...item.content[0], text: '' }] };
+      }
+      if (!responseOutputControl(item)) throw new ProviderTextProtectionError('unsupported');
+      return item;
+    });
+    if ((messageCount === 0 && !this.attempt.matchesText('')) ||
+        (metadata.output_text != null && (typeof metadata.output_text !== 'string' || !this.attempt.matchesText(metadata.output_text)))) {
+      throw new ProviderTextProtectionError('unsupported');
+    }
+    for (const [key, value] of Object.entries(metadata)) {
+      let valid: boolean;
+      if (key === 'output' || key === 'output_text') continue;
+      if (key === 'top_logprobs') valid = value == null || value === 0;
+      else if (key === 'usage') valid = numericTree(value);
+      else if (key === 'text') valid = keys(value, ['format', 'verbosity']) && keys(value.format, ['type']) && value.format.type === 'text' &&
+        (value.verbosity == null || ['low', 'medium', 'high'].includes(String(value.verbosity)));
+      else if (key === 'tools') valid = Array.isArray(value) && value.length <= 32 && value.every(responseTool);
+      else if (key === 'tool_choice') valid = value === 'auto' || value === 'none' || value === 'required' || (keys(value, ['type', 'name']) && value.type === 'function' && typeof value.name === 'string');
+      else if (key === 'reasoning') valid = value == null || (keys(value, ['effort', 'summary']) &&
+        (value.effort == null || ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'].includes(String(value.effort))) &&
+        (value.summary == null || ['auto', 'concise', 'detailed'].includes(String(value.summary))));
+      else if (key === 'metadata') valid = keys(value, []) || value == null;
+      else if (key === 'instructions' || key === 'error') valid = value == null;
+      else if (key === 'incomplete_details') valid = value == null || (keys(value, ['reason']) && ['max_output_tokens', 'content_filter'].includes(String(value.reason)));
+      else valid = scalarKeys.has(key) && (value == null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)));
+      if (!valid) throw new ProviderTextProtectionError('unsupported');
+    }
+    retainTree(metadata, this.attempt);
+    this.output = output;
+    this.hasOutputAlias = Object.hasOwn(metadata, 'output_text');
+    const { output: _output, output_text: _alias, ...controls } = metadata;
+    this.metadata = controls;
+    return controls;
+  }
+
+  canonical(content: string): AIMessageChunk['response_metadata'] | undefined {
+    if (this.metadata == null || this.output == null) return undefined;
+    return {
+      output: this.output.map((item) => messageOutput(item) ? { ...item, content: [{ ...item.content[0], text: content }] } : item),
+      ...(this.hasOutputAlias ? { output_text: content } : {}),
+    };
+  }
+}
+
+function numericTree(value: unknown, depth = 4): boolean {
+  if (value == null) return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value !== 'object' || Array.isArray(value) || depth === 0) return false;
+  const entries = Object.values(value);
+  return entries.length <= 64 && entries.every((entry) => numericTree(entry, depth - 1));
+}
+
+function responseOutputControl(value: unknown): value is Record<string, unknown> {
+  if (!keys(value, ['id', 'type', 'status', 'call_id', 'name', 'arguments', 'summary', 'encrypted_content'])) return false;
+  if (typeof value.id !== 'string' || (value.status != null && !['completed', 'incomplete', 'in_progress'].includes(String(value.status)))) return false;
+  if (value.type === 'function_call') return keys(value, ['id', 'type', 'status', 'call_id', 'name', 'arguments']) &&
+    typeof value.call_id === 'string' && typeof value.name === 'string' && typeof value.arguments === 'string';
+  if (value.type !== 'reasoning' || !keys(value, ['id', 'type', 'status', 'summary', 'encrypted_content'])) return false;
+  return (value.encrypted_content == null || typeof value.encrypted_content === 'string') &&
+    Array.isArray(value.summary) && value.summary.length <= 32 && value.summary.every((entry: unknown) =>
+    keys(entry, ['type', 'text']) && entry.type === 'summary_text' && typeof entry.text === 'string');
+}
+
+function responseTool(value: unknown): boolean {
+  return keys(value, ['type', 'name', 'description', 'strict', 'parameters']) && value.type === 'function' &&
+    typeof value.name === 'string' && (value.description == null || typeof value.description === 'string') &&
+    (value.strict == null || typeof value.strict === 'boolean') && jsonControl(value.parameters);
+}
+
+function jsonControl(value: unknown, depth = 6): boolean {
+  if (value == null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value !== 'object' || depth === 0) return false;
+  const entries = Object.values(value);
+  return entries.length <= 64 && entries.every((entry) => jsonControl(entry, depth - 1));
+}
+
+function retainTree(value: unknown, attempt: ProviderTextAttempt, depth = 8): void {
+  if (typeof value === 'string') { attempt.retain(value.length * 2 + 32); return; }
+  attempt.retain(64);
+  if (value == null || typeof value !== 'object') return;
+  if (depth === 0) throw new ProviderTextProtectionError('unsupported');
+  const entries = Object.entries(value);
+  if (entries.length > 128) throw new ProviderTextProtectionError('unsupported');
+  for (const [key, entry] of entries) {
+    attempt.retain(key.length * 2 + 32);
+    retainTree(entry, attempt, depth - 1);
+  }
+}

package/src/llm/stream/smoother.ts

@@ -1,3 +1,5 @@
+import { isProtectedProviderTextSignal } from '@/protection/providerText';
+
 export const DEFAULT_STREAM_DELAY = 25;
 export const SMOOTH_TARGET_LATENCY_MS = 250;
 export const MAX_STREAM_QUEUE_CHUNKS = 256;
@@ -204,8 +206,8 @@ export async function* smoothStream<TEmit>({
   signal?: AbortSignal;
   abortUpstream?: () => void;
 }): AsyncGenerator<TEmit> {
-  if (!(delayMs > 0)) {
-    /** Disabled smoothing preserves fully lazy streaming: no background
+  if (!(delayMs > 0) || isProtectedProviderTextSignal(signal)) {
+    /** Disabled/protected smoothing preserves fully lazy streaming: no background
      * producer, no read-ahead — each provider chunk is pulled only when the
      * consumer asks, exactly like the pre-engine pass-through paths. */
     for await (const item of source) {