@librechat/agents 4.0.2 → 4.0.4

package/src/protection/providerText.ts

@@ -0,0 +1,325 @@
+import { performance } from 'node:perf_hooks';
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
+import { StreamLimitExceededError } from '@/llm/streamLimits';
+
+export const PROVIDER_TEXT_PROTECTION_VERSION = 1;
+
+export type ProviderTextProtectionErrorCode =
+  | 'blocked'
+  | 'unavailable'
+  | 'timeout'
+  | 'overflow'
+  | 'cancelled'
+  | 'unsupported'
+  | 'incompatible';
+
+export type ProviderTextProtectionResult =
+  | {
+      readonly version: 1;
+      readonly ok: true;
+      readonly value: {
+        readonly content: string;
+        readonly replacements: number;
+        readonly categories: readonly {
+          readonly category: string;
+          readonly count: number;
+        }[];
+      };
+    }
+  | {
+      readonly version: 1;
+      readonly ok: false;
+      readonly error: { readonly code: ProviderTextProtectionErrorCode };
+    };
+
+/** Trusted host adapter. Classification must reject code, JSON and ambiguous text. */
+export interface ProviderTextProtection {
+  readonly version: 1;
+  readonly timeoutMs: number;
+  readonly maxAttemptBytes: number;
+  /** Shared across all attempts using this policy, including child graphs. */
+  readonly maxBufferedBytes: number;
+  readonly classify: (content: string) => 'prose' | 'unsupported';
+  readonly inspect: (input: {
+    readonly version: 1;
+    readonly content: string;
+    readonly target: {
+      readonly source: 'message';
+      readonly field: 'text';
+      readonly provenance: 'model';
+    };
+    readonly signal: AbortSignal;
+  }) => ProviderTextProtectionResult | Promise<ProviderTextProtectionResult>;
+}
+
+export class ProviderTextProtectionError extends Error {
+  constructor(readonly code: ProviderTextProtectionErrorCode) {
+    const safeCode = errorCodes.has(code) ? code : 'incompatible';
+    super(`Provider text protection: ${safeCode}`);
+    this.code = safeCode;
+    this.name = 'ProviderTextProtectionError';
+  }
+}
+
+const restartCancellations = new WeakSet<ProviderTextProtectionError>();
+
+/** Internal control flow, never a host policy decision or public capability. */
+export function createProviderTextRestartCancellation(): ProviderTextProtectionError {
+  const error = new ProviderTextProtectionError('cancelled');
+  restartCancellations.add(error);
+  return error;
+}
+
+export function isProviderTextRestartCancellation(error: unknown): boolean {
+  return error instanceof ProviderTextProtectionError && restartCancellations.has(error);
+}
+
+function protectionAbortError(parent?: AbortSignal): ProviderTextProtectionError | StreamLimitExceededError | PreparedSubagentError {
+  const reason: unknown = parent?.reason;
+  if (reason instanceof StreamLimitExceededError || reason instanceof PreparedSubagentError) return reason;
+  if (reason instanceof ProviderTextProtectionError) {
+    return isProviderTextRestartCancellation(reason) ? reason : new ProviderTextProtectionError(reason.code);
+  }
+  return new ProviderTextProtectionError('cancelled');
+}
+
+const protectedSignals = new WeakSet<AbortSignal>();
+
+/** Provider smoothing must stay lazy while the release boundary owns raw text. */
+export function isProtectedProviderTextSignal(signal?: AbortSignal): boolean {
+  return signal != null && protectedSignals.has(signal);
+}
+
+const budgets = new WeakMap<ProviderTextProtection, { bytes: number }>();
+const errorCodes = new Set<ProviderTextProtectionErrorCode>([
+  'blocked',
+  'unavailable',
+  'timeout',
+  'overflow',
+  'cancelled',
+  'unsupported',
+  'incompatible',
+]);
+
+export function validateProviderTextProtection(
+  policy: ProviderTextProtection
+): void {
+  const version: number = policy.version;
+  if (version !== 1)
+    throw new ProviderTextProtectionError('incompatible');
+  if (
+    typeof policy.inspect !== 'function' ||
+    typeof policy.classify !== 'function'
+  ) {
+    throw new ProviderTextProtectionError('unavailable');
+  }
+  for (const value of [
+    policy.timeoutMs,
+    policy.maxAttemptBytes,
+    policy.maxBufferedBytes,
+  ]) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new ProviderTextProtectionError('incompatible');
+    }
+  }
+  if (
+    policy.timeoutMs > 2_147_483_647 ||
+    policy.maxAttemptBytes > policy.maxBufferedBytes
+  ) {
+    throw new ProviderTextProtectionError('incompatible');
+  }
+}
+
+/** A lease stays charged while a cancellation-ignoring producer/handler still owns raw text. */
+export class ProviderTextAttempt {
+  private readonly controller = new AbortController();
+  private readonly budget: { bytes: number };
+  private readonly deadline: number;
+  private bytes = 0;
+  private textLength = 0;
+  private readonly fragments: string[] = [];
+  private readonly pending = new Set<Promise<unknown>>();
+  private readonly timer: ReturnType<typeof setTimeout>;
+  private readonly abort: () => void;
+  private finished = false;
+
+  constructor(
+    private readonly policy: ProviderTextProtection,
+    private readonly parent?: AbortSignal
+  ) {
+    validateProviderTextProtection(policy);
+    this.deadline = performance.now() + policy.timeoutMs;
+    this.budget = budgets.get(policy) ?? { bytes: 0 };
+    budgets.set(policy, this.budget);
+    if (parent?.aborted === true) throw protectionAbortError(parent);
+    this.charge(512);
+    protectedSignals.add(this.signal);
+    this.abort = (): void =>
+      this.controller.abort(protectionAbortError(this.parent));
+    parent?.addEventListener('abort', this.abort, { once: true });
+    this.timer = setTimeout(() => {
+      this.controller.abort(new ProviderTextProtectionError('timeout'));
+    }, policy.timeoutMs);
+    this.timer.unref();
+  }
+
+  get signal(): AbortSignal {
+    return this.controller.signal;
+  }
+
+  check(): void {
+    if (this.signal.aborted) throw this.signal.reason;
+    if (this.parent?.aborted === true)
+      throw protectionAbortError(this.parent);
+    if (performance.now() >= this.deadline) {
+      this.controller.abort(new ProviderTextProtectionError('timeout'));
+      throw this.signal.reason;
+    }
+  }
+
+  private charge(bytes: number): void {
+    if (
+      this.bytes + bytes > this.policy.maxAttemptBytes ||
+      this.budget.bytes + bytes > this.policy.maxBufferedBytes
+    ) {
+      this.controller.abort(new ProviderTextProtectionError('overflow'));
+      throw this.signal.reason;
+    }
+    this.bytes += bytes;
+    this.budget.bytes += bytes;
+  }
+
+  append(text: string, cumulativeReplay = false): void {
+    this.check();
+    if (cumulativeReplay && this.hasCandidatePrefix(text)) text = text.slice(this.textLength);
+    if (!text) return;
+    const bytes = text.length * 2;
+    this.charge(bytes * 2 + 64);
+    this.fragments.push(text);
+    this.textLength += text.length;
+  }
+
+  /** Compare buffered fragments without allocating an uncharged joined copy. */
+  private hasCandidatePrefix(text: string): boolean {
+    if (this.textLength === 0 || text.length < this.textLength) return false;
+    let offset = 0;
+    for (const fragment of this.fragments) {
+      if (!text.startsWith(fragment, offset)) return false;
+      offset += fragment.length;
+    }
+    return true;
+  }
+
+  matchesText(text: string): boolean {
+    return text.length === this.textLength && (text.length === 0 || this.hasCandidatePrefix(text));
+  }
+
+  retain(bytes: number): void {
+    this.check();
+    this.charge(bytes);
+  }
+
+  observeChunk(): void {
+    this.check();
+    this.charge(128);
+  }
+
+  async wait<T>(work: Promise<T>): Promise<T> {
+    this.pending.add(work);
+    return new Promise<T>((resolve, reject) => {
+      const abort = (): void => {
+        this.signal.removeEventListener('abort', abort);
+        reject(this.signal.reason);
+      };
+      this.signal.addEventListener('abort', abort, { once: true });
+      if (this.signal.aborted) abort();
+      const settle = (): void => {
+        this.signal.removeEventListener('abort', abort);
+        this.pending.delete(work);
+      };
+      void work.then(
+        (value) => { settle(); resolve(value); },
+        (error: Error) => { settle(); reject(error); }
+      );
+    });
+  }
+
+  async release(): Promise<string> {
+    this.check();
+    const content = this.fragments.join('');
+    if (!content) return '';
+    let result: ProviderTextProtectionResult;
+    try {
+      const treatment = this.policy.classify(content);
+      this.check();
+      if (treatment !== 'prose') {
+        throw new ProviderTextProtectionError('unsupported');
+      }
+      result = await this.wait(
+        Promise.resolve(
+          this.policy.inspect({
+            version: 1,
+            content,
+            target: { source: 'message', field: 'text', provenance: 'model' },
+            signal: this.signal,
+          })
+        )
+      );
+    } catch (error) {
+      this.check();
+      if (isProviderTextRestartCancellation(error)) throw error;
+      if (error instanceof ProviderTextProtectionError) throw new ProviderTextProtectionError(error.code);
+      throw new ProviderTextProtectionError('unavailable');
+    }
+    this.check();
+    const canonical = validateResult(result);
+    this.check();
+    this.charge(canonical.length * 2);
+    return canonical;
+  }
+
+  finish(): void {
+    if (this.finished) return;
+    this.finished = true;
+    clearTimeout(this.timer);
+    this.parent?.removeEventListener('abort', this.abort);
+    const dispose = (): void => {
+      this.fragments.length = 0;
+      this.budget.bytes -= this.bytes;
+      this.bytes = 0;
+    };
+    if (this.pending.size === 0) dispose();
+    else void Promise.allSettled([...this.pending]).then(dispose);
+  }
+}
+
+interface UncheckedResult {
+  version?: number;
+  ok?: boolean;
+  value?: { content?: string; replacements?: number; categories?: readonly { category?: string; count?: number }[] };
+  error?: { code?: ProviderTextProtectionErrorCode };
+}
+
+function validateResult(result: UncheckedResult | undefined): string {
+  try {
+    if (result?.version !== 1 || typeof result.ok !== 'boolean') {
+      throw new ProviderTextProtectionError('incompatible');
+    }
+    if (!result.ok) {
+      const code = result.error?.code;
+      throw new ProviderTextProtectionError(code != null && errorCodes.has(code) ? code : 'incompatible');
+    }
+    const value = result.value;
+    if (typeof value?.content !== 'string' || typeof value.replacements !== 'number' ||
+        !Number.isSafeInteger(value.replacements) || value.replacements < 0 ||
+        !Array.isArray(value.categories) || value.categories.length > 32 ||
+        value.categories.some((entry) => typeof entry.category !== 'string' ||
+          typeof entry.count !== 'number' || !Number.isSafeInteger(entry.count) || entry.count <= 0)) {
+      throw new ProviderTextProtectionError('incompatible');
+    }
+    return value.content;
+  } catch (error) {
+    if (error instanceof ProviderTextProtectionError) throw error;
+    throw new ProviderTextProtectionError('incompatible');
+  }
+}

package/src/protection/providerTextInput.ts

@@ -0,0 +1,21 @@
+const inputs = new WeakMap<object, { prototype: object | null; descriptors: PropertyDescriptorMap }>();
+
+/** Internal provenance for the SDK's pure instruction transform, not a host capability. */
+export function markProviderTextInput<T extends object>(input: T): T {
+  inputs.set(input, { prototype: Object.getPrototypeOf(input), descriptors: Object.getOwnPropertyDescriptors(input) });
+  return input;
+}
+
+export function isProviderTextInput(input: object): boolean {
+  const original = inputs.get(input);
+  if (original == null || original.prototype !== Object.getPrototypeOf(input)) return false;
+  const current: Partial<PropertyDescriptorMap> = Object.getOwnPropertyDescriptors(input);
+  const keys = Object.keys(original.descriptors);
+  return keys.length === Object.keys(current).length && keys.every((key) => {
+    const before = original.descriptors[key];
+    const after = current[key];
+    return after != null && before.value === after.value && before.get === after.get &&
+      before.set === after.set && before.writable === after.writable &&
+      before.enumerable === after.enumerable && before.configurable === after.configurable;
+  });
+}

package/src/run.ts

@@ -102,6 +102,7 @@ import {
   createTitleRunnable,
 } from '@/utils/title';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { stampSyntheticProviderMessage } from '@/messages/provenance';
@@ -477,6 +478,7 @@ export class Run<_T extends t.BaseGraphState> {
   private subagentUsageSink?: t.SubagentUsageSink;
   private preemption?: t.StreamPreemption;
   private maxStopContinuations: number;
+  private providerTextProtection?: t.StandardGraphInput['providerTextProtection'];
   private streamLimits?: t.StreamLimits;
   private subagentTasks?: t.SubagentTaskConfig;
   private subagentContext?: t.SubagentContextAdapter;
@@ -578,10 +580,15 @@ export class Run<_T extends t.BaseGraphState> {
       config.maxStopContinuations
     );
     this.streamLimits = config.streamLimits;
+    this.providerTextProtection = config.providerTextProtection;
 
     if (!config.graphConfig) {
       throw new Error('Graph config not provided');
     }
+    if ('providerTextProtection' in config.graphConfig &&
+        config.graphConfig.providerTextProtection != null) {
+      throw new ProviderTextProtectionError('incompatible');
+    }
 
     /** Handle different graph types */
     if (config.graphConfig.type === 'multi-agent') {
@@ -678,6 +685,7 @@ export class Run<_T extends t.BaseGraphState> {
         onSubagentResolutionFailure: this.onSubagentResolutionFailure,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
+        providerTextProtection: this.providerTextProtection,
         toolExecution: this.toolExecution,
         clientDelegatedToolNames: this.clientDelegatedToolNames,
       },
@@ -725,6 +733,7 @@ export class Run<_T extends t.BaseGraphState> {
         onSubagentResolutionFailure: this.onSubagentResolutionFailure,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
+        providerTextProtection: this.providerTextProtection,
         toolExecution: this.toolExecution,
       },
     });

package/src/stream.ts

@@ -58,6 +58,7 @@ import {
 import { createToolCallsDispatchedEvent, safeDispatchCustomEvent } from '@/utils/events';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
 import { snapshotValidatedModelChunk } from '@/graphs/acceptedModelResponse';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
@@ -1687,6 +1688,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
       graph.breakerAbort instanceof AbortController
         ? graph.breakerAbort
         : undefined;
+    const entrySignals = [eventBreaker?.signal, graph.signal, graph.config.signal];
     /** Immutable scope captured at handler entry. A reset while this
      * handler is suspended in an await replaces the object, so ONE
      * reference comparison proves the event still belongs to the live run
@@ -1695,13 +1697,16 @@ export class ChatModelStreamHandler implements t.EventHandler {
     const runScopeInvalidated = (): boolean =>
       entryRunScope != null && graph.runScope !== entryRunScope;
     const throwIfRunBreakerTripped = (): void => {
-      if (
-        eventBreaker != null &&
-        eventBreaker.signal.aborted &&
-        (eventBreaker.signal.reason instanceof StreamLimitExceededError ||
-          eventBreaker.signal.reason instanceof PreparedSubagentError)
-      ) {
-        throw eventBreaker.signal.reason;
+      for (const signal of entrySignals) {
+        if (signal?.aborted === true &&
+            (signal.reason instanceof StreamLimitExceededError ||
+              signal.reason instanceof PreparedSubagentError ||
+              signal.reason instanceof ProviderTextProtectionError)) {
+          throw signal.reason;
+        }
+        if (signal?.aborted === true && graph.providerTextProtection != null) {
+          throw new ProviderTextProtectionError('cancelled');
+        }
       }
     };
 
@@ -1797,6 +1802,8 @@ export class ChatModelStreamHandler implements t.EventHandler {
       metadata,
       agentContext,
     });
+    if (runScopeInvalidated()) return;
+    throwIfRunBreakerTripped();
     if (skipHandling) {
       return;
     }
@@ -1831,6 +1838,8 @@ export class ChatModelStreamHandler implements t.EventHandler {
         content,
         metadata,
       });
+      if (runScopeInvalidated()) return;
+      throwIfRunBreakerTripped();
     }
 
     if (
@@ -2033,6 +2042,23 @@ export class ChatModelStreamHandler implements t.EventHandler {
       });
       runStep = graph.getRunStep(stepId);
     }
+    if (
+      graph.providerTextProtection != null &&
+      runStep?.type === StepTypes.TOOL_CALLS &&
+      agentContext.currentTokenType === ContentTypes.TEXT &&
+      (typeof content === 'string' || content.every(isTextContentPart))
+    ) {
+      stepId = await dispatchMessageCreationStep({
+        graph,
+        stepKey,
+        content,
+        contentType: ContentTypes.TEXT,
+        metadata,
+      });
+      if (runScopeInvalidated()) return;
+      throwIfRunBreakerTripped();
+      runStep = graph.getRunStep(stepId);
+    }
     if (!runStep) {
       console.warn(`\n
 ==============================================================

package/src/summarization/node.ts

@@ -56,6 +56,7 @@ import {
   resolveClientOptionsModel,
 } from '@/llm/request';
 import { renderCompactionSemanticIndex } from '@/summarization/semanticIndex';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
@@ -739,16 +740,6 @@ async function executeSummarizationWithFallback(params: {
     summaryText = result.text;
     summaryUsage = result.usage;
   } catch (primaryError) {
-    const primaryDescribed = describeProviderError(
-      primaryError,
-      clientConfig.provider,
-      clientConfig.modelName
-    );
-    log('error', `Summarization LLM call failed ${primaryDescribed.suffix}`, {
-      ...primaryDescribed.data,
-      messagesToRefineCount: messages.length,
-    });
-
     /**
      * A tripped stream circuit breaker is a safety abort, not a
      * summarization failure to recover from: retrying on fallback providers
@@ -758,7 +749,7 @@ async function executeSummarizationWithFallback(params: {
      * rejects the run. Rethrown so the summarize node fails the run with
      * the actionable limit error, consistent with agent turns and subagents.
      */
-    if (primaryError instanceof StreamLimitExceededError) {
+    if (primaryError instanceof StreamLimitExceededError || primaryError instanceof ProviderTextProtectionError) {
       throw primaryError;
     }
     /** A parallel branch's trip aborts the composed summarization signal,
@@ -777,6 +768,16 @@ async function executeSummarizationWithFallback(params: {
       }
     }
 
+    const primaryDescribed = describeProviderError(
+      primaryError,
+      clientConfig.provider,
+      clientConfig.modelName
+    );
+    log('error', `Summarization LLM call failed ${primaryDescribed.suffix}`, {
+      ...primaryDescribed.data,
+      messagesToRefineCount: messages.length,
+    });
+
     const rawFallbacks = (
       clientConfig.clientOptions as unknown as t.LLMConfig | undefined
     )?.fallbacks;
@@ -819,7 +820,9 @@ async function executeSummarizationWithFallback(params: {
           );
         }
       } catch (fbErr) {
-        if (fbErr instanceof StreamLimitExceededError) {
+        const trip = findStreamLimitAbortReason(graph?.getBreakerSignal?.(), summarizeConfig?.signal);
+        if (trip != null) throw trip;
+        if (fbErr instanceof StreamLimitExceededError || fbErr instanceof ProviderTextProtectionError) {
           throw fbErr;
         }
         const fbDescribed = describeFallbackError(fbErr, fallbacks);
@@ -842,6 +845,8 @@ async function executeSummarizationWithFallback(params: {
     }
   }
 
+  const trip = findStreamLimitAbortReason(graph?.getBreakerSignal?.(), summarizeConfig?.signal);
+  if (trip != null) throw trip;
   return { text: summaryText, usage: summaryUsage, usedMetadataStub };
 }
 
@@ -875,6 +880,11 @@ async function dispatchCompletionEvents(params: {
     messagesAfterCount,
   } = params;
 
+  const assertNotTripped = (): void => {
+    const trip = findStreamLimitAbortReason(graph.getBreakerSignal?.(), runnableConfig?.signal);
+    if (trip != null) throw trip;
+  };
+  assertNotTripped();
   runStep.summary = summaryBlock;
   if (summaryUsage) {
     runStep.usage = {
@@ -892,6 +902,7 @@ async function dispatchCompletionEvents(params: {
     runnableConfig
   );
 
+  assertNotTripped();
   if (runnableConfig) {
     await safeDispatchCustomEvent(
       GraphEvents.ON_SUMMARIZE_COMPLETE,
@@ -904,6 +915,7 @@ async function dispatchCompletionEvents(params: {
     );
   }
 
+  assertNotTripped();
   const sessionId = graph.runId ?? '';
   if (graph.hookRegistry?.hasHookFor('PostCompact', sessionId) === true) {
     const threadId = (
@@ -1017,11 +1029,11 @@ function withBreakerSignal<T extends { signal?: AbortSignal }>(
  * child's private breaker never fires for it. */
 function findStreamLimitAbortReason(
   ...signals: Array<AbortSignal | undefined>
-): StreamLimitExceededError | undefined {
+): StreamLimitExceededError | ProviderTextProtectionError | undefined {
   for (const signal of signals) {
     if (
       signal?.aborted === true &&
-      signal.reason instanceof StreamLimitExceededError
+      (signal.reason instanceof StreamLimitExceededError || signal.reason instanceof ProviderTextProtectionError)
     ) {
       return signal.reason;
     }
@@ -1526,6 +1538,8 @@ export function createSummarizeNode({
       return { summarizationRequest: undefined };
     }
 
+    const postCallTrip = findStreamLimitAbortReason(entryBreakerSignal, config?.signal);
+    if (postCallTrip != null) throw postCallTrip;
     const summaryText = enrichSummary(rawText, messagesToRefine);
 
     const tokenCount = await computeSummaryTokenCount(
@@ -1533,6 +1547,8 @@ export function createSummarizeNode({
       agentContext
     );
 
+    const commitTrip = findStreamLimitAbortReason(entryBreakerSignal, config?.signal);
+    if (commitTrip != null) throw commitTrip;
     if (usedIntraTurnFallback) {
       agentContext.setSummary(summaryText, tokenCount, {
         precedesMessages: true,
@@ -1712,6 +1728,8 @@ export function createSummarizationChunkHandler({
         throw error;
       }
     }
+    const protectionTrip = findStreamLimitAbortReason(graph?.getBreakerController?.().signal, config.signal);
+    if (protectionTrip != null) throw protectionTrip;
     const chunkAny = chunk as Parameters<typeof getChunkContent>[0]['chunk'];
     const raw = getChunkContent({ chunk: chunkAny, provider, reasoningKey });
     if (raw == null || (typeof raw === 'string' && !raw)) {