@librechat/agents 4.0.1 → 4.0.3

package/src/decisions/transport.ts

@@ -0,0 +1,335 @@
+import type { AwaitWithinDeadline } from './deadline';
+import type { DecisionCredential } from './types';
+import { withDecisionDeadline } from './deadline';
+import { DecisionError } from './types';
+
+const DEFAULT_TIMEOUT_MS = 4_000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_RESPONSE_BYTES = 256 * 1024;
+const BACKOFF_MS = [250, 750, 1_500, 3_000, 6_000];
+const MAX_RETRY_AFTER_MS = 10_000;
+
+export type DecisionFetch = (
+  input: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+    redirect: 'error';
+  }
+) => Promise<Pick<Response, 'ok' | 'status' | 'headers' | 'body'>>;
+
+export interface TransportOptions {
+  providerId: string;
+  apiKey?: DecisionCredential;
+  requiresAuth?: boolean;
+  /** Full URL, not a base path. */
+  endpoint: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetch?: DecisionFetch;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  /** Called only after the response parses, with no state, answers, or credentials. */
+  onAnswered?: (label: string, ms: number) => void;
+}
+
+export type Transport = <T>(
+  prepare: () => { payload: string; parse: (body: string) => T },
+  signal: AbortSignal | undefined,
+  label: string,
+  timeoutOverrideMs?: number
+) => Promise<T>;
+
+export function failureForStatus(
+  status: number
+): 'unauthorized' | 'rate_limited' | 'server_error' | 'bad_request' {
+  if (status === 401 || status === 403) {
+    return 'unauthorized';
+  }
+  if (status === 429) {
+    return 'rate_limited';
+  }
+  if (status >= 500) {
+    return 'server_error';
+  }
+  return 'bad_request';
+}
+
+export function retryAfterMs(header: string | null): number | undefined {
+  if (header == null || header === '') {
+    return undefined;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.min(seconds * 1_000, MAX_RETRY_AFTER_MS);
+  }
+  const at = Date.parse(header);
+  return Number.isFinite(at)
+    ? Math.min(Math.max(at - Date.now(), 0), MAX_RETRY_AFTER_MS)
+    : undefined;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted === true) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+  });
+}
+
+/** Stream successful bodies only, so neither errors nor oversized replies are ever buffered. */
+async function readResponse(
+  body: ReadableStream<Uint8Array> | null,
+  waitFor: AwaitWithinDeadline,
+  provider: string
+): Promise<string> {
+  if (!body) {
+    return '';
+  }
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text = '';
+  try {
+    for (;;) {
+      const chunk = await waitFor(reader.read());
+      if (chunk.done) {
+        return text + decoder.decode();
+      }
+      bytes += chunk.value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        throw new DecisionError(
+          'malformed_response',
+          'decision model response too large',
+          {
+            provider,
+          }
+        );
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+  } catch (error) {
+    void reader.cancel().catch(() => {});
+    throw error;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // A timed-out read still holds the lock until cancellation settles.
+    }
+  }
+}
+
+/** One immutable transport; every call owns its signal, deadline, and credentials. */
+export function createTransport(options: TransportOptions): Transport {
+  const { providerId } = options;
+  const credential = options.apiKey;
+  if (
+    options.requiresAuth !== false &&
+    (credential == null ||
+      (typeof credential === 'string' && credential.trim() === ''))
+  ) {
+    throw new DecisionError(
+      'unauthorized',
+      'decision model requires an API key',
+      {
+        provider: providerId,
+      }
+    );
+  }
+  const endpoint = options.endpoint.trim();
+  if (!endpoint) {
+    throw new DecisionError(
+      'bad_request',
+      'decision model requires an endpoint',
+      {
+        provider: providerId,
+      }
+    );
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const sleep = options.sleep ?? defaultSleep;
+  const onAnswered = options.onAnswered;
+  if (!Number.isSafeInteger(maxRetries) || maxRetries < 0 || maxRetries > 5) {
+    throw new DecisionError(
+      'bad_request',
+      'invalid decision model retry limit',
+      {
+        provider: providerId,
+      }
+    );
+  }
+  const fetchImpl: DecisionFetch = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new DecisionError('network', 'no fetch implementation available', {
+      provider: providerId,
+    });
+  }
+
+  async function resolveKey(
+    refresh: boolean,
+    signal: AbortSignal
+  ): Promise<string | null> {
+    if (typeof credential === 'string') {
+      return credential.trim() || null;
+    }
+    if (!credential) {
+      return null;
+    }
+    const minted: string = await credential({ refresh, signal });
+    const token = typeof minted === 'string' ? minted.trim() : '';
+    if (!token) {
+      throw new DecisionError(
+        'unauthorized',
+        'credential function returned no token',
+        {
+          provider: providerId,
+        }
+      );
+    }
+    return token;
+  }
+
+  return async function send(prepare, callerSignal, label, timeoutOverrideMs) {
+    const started = performance.now();
+    return withDecisionDeadline(
+      providerId,
+      timeoutOverrideMs ?? timeoutMs,
+      callerSignal,
+      async (signal, waitFor) => {
+        let prepared: ReturnType<typeof prepare>;
+        try {
+          prepared = prepare();
+        } catch (error) {
+          if (error instanceof DecisionError) {
+            throw error;
+          }
+          throw new DecisionError(
+            'bad_request',
+            'invalid decision model request',
+            {
+              provider: providerId,
+            }
+          );
+        }
+        const { payload, parse } = prepared;
+        await waitFor(Promise.resolve());
+        const wasAborted = (): boolean => signal.aborted;
+        const interrupted = (): DecisionError =>
+          new DecisionError(
+            callerSignal?.aborted === true ? 'aborted' : 'timeout',
+            'decision model request interrupted',
+            { provider: providerId }
+          );
+        let refreshed = false;
+        let key: string | null | undefined;
+        let lastError: DecisionError | undefined;
+        for (let attemptNo = 0; attemptNo <= maxRetries; attemptNo++) {
+          if (wasAborted()) {
+            throw interrupted();
+          }
+          try {
+            if (key === undefined) {
+              key = await waitFor(resolveKey(refreshed, signal));
+            }
+            const response = await waitFor(
+              fetchImpl(endpoint, {
+                method: 'POST',
+                headers: {
+                  ...(key !== null ? { Authorization: `Bearer ${key}` } : {}),
+                  'Content-Type': 'application/json',
+                },
+                body: payload,
+                signal,
+                redirect: 'error',
+              })
+            );
+            if (!response.ok) {
+              void response.body?.cancel().catch(() => {});
+              const error = new DecisionError(
+                failureForStatus(response.status),
+                `decision model returned HTTP ${response.status}`,
+                { provider: providerId, status: response.status }
+              );
+              error.retryAfterMs = retryAfterMs(
+                response.headers.get('retry-after')
+              );
+              throw error;
+            }
+            const body = await readResponse(response.body, waitFor, providerId);
+            const result = await waitFor(Promise.resolve(parse(body)));
+            try {
+              onAnswered?.(label, performance.now() - started);
+            } catch {
+              // Observability must not turn a valid answer into a retried request.
+            }
+            return result;
+          } catch (error) {
+            if (wasAborted()) {
+              throw interrupted();
+            }
+            if (error instanceof DecisionError) {
+              lastError = error;
+            } else {
+              lastError = new DecisionError(
+                'network',
+                'decision model request failed',
+                { provider: providerId }
+              );
+            }
+            if (
+              lastError.status === 401 &&
+              typeof credential === 'function' &&
+              !refreshed
+            ) {
+              refreshed = true;
+              key = undefined;
+              attemptNo -= 1;
+              continue;
+            }
+            if (
+              attemptNo === maxRetries ||
+              !['rate_limited', 'server_error', 'network'].includes(
+                lastError.failure
+              )
+            ) {
+              break;
+            }
+            const wait =
+              lastError.retryAfterMs ??
+              BACKOFF_MS[Math.min(attemptNo, BACKOFF_MS.length - 1)];
+            try {
+              await waitFor(sleep(wait, signal));
+            } catch (error) {
+              if (error instanceof DecisionError) {
+                throw error;
+              }
+              throw new DecisionError(
+                'network',
+                'decision model backoff failed',
+                {
+                  provider: providerId,
+                }
+              );
+            }
+          }
+        }
+        throw (
+          lastError ??
+          new DecisionError('network', 'decision model request failed', {
+            provider: providerId,
+          })
+        );
+      }
+    );
+  };
+}

package/src/decisions/types.ts

@@ -0,0 +1,193 @@
+/** Typed decisions over content, independent of the model that makes them. */
+
+export type DecisionJson =
+  | string
+  | number
+  | boolean
+  | null
+  | DecisionJson[]
+  | { [key: string]: DecisionJson };
+
+export type DecisionText =
+  | string
+  | DecisionJson[]
+  | { [key: string]: DecisionJson };
+
+export type DecisionState = DecisionText;
+
+export interface BooleanCriteria {
+  true?: DecisionText;
+  false?: DecisionText;
+}
+
+/** A string criterion describes the yes side of a yes/no question. */
+export interface BooleanQuestion {
+  type: 'boolean';
+  instructions: DecisionText;
+  criteria?: BooleanCriteria | string;
+}
+
+export interface ChoiceQuestion {
+  type: 'choice';
+  instructions: DecisionText;
+  criteria: Record<string, DecisionText | null>;
+}
+
+/** The measured answer is an expected level, which may fall between two rubric levels. */
+export interface ScoreQuestion {
+  type: 'score';
+  instructions: DecisionText;
+  criteria: DecisionText[];
+}
+
+export type DecisionQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;
+
+/** `null` is an unmeasured decision, not a probability of zero. */
+export type BooleanAnswer =
+  | { type: 'boolean'; probability: number; decision?: never }
+  | { type: 'boolean'; probability: null; decision: boolean };
+
+export interface ChoiceAnswer {
+  type: 'choice';
+  choice: string;
+  /** Backend-specific concentration measure; Jev and Laya use different definitions. */
+  confidence: number | null;
+  /** `null` when no distribution was measured; never substitute an empty distribution. */
+  probabilities: Record<string, number> | null;
+}
+
+export interface ScoreAnswer {
+  type: 'score';
+  /** Expected value over rubric levels, not an LLM's selection of one level. */
+  score: number;
+  /** Backend-specific concentration measure; do not transfer thresholds between checkpoints. */
+  confidence: number | null;
+  probabilities: Record<string, number> | null;
+}
+
+export type DecisionAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer;
+
+/** Unknown counts are omitted, never inferred from an answer or replaced by zero. */
+export interface DecisionUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+export interface DecisionRequest {
+  state: DecisionState;
+  questions: Record<string, DecisionQuestion>;
+  signal?: AbortSignal;
+  label?: string;
+  /** Overrides the provider's timeout for this request alone. */
+  timeoutMs?: number;
+}
+
+export interface DecisionResult {
+  model: string;
+  /** A requested answer can be omitted; callers must handle `undefined` explicitly. */
+  answers: Record<string, DecisionAnswer | undefined>;
+  usage: DecisionUsage | null;
+}
+
+export interface DecisionModel {
+  readonly id: string;
+  readonly model: string;
+  decide(request: DecisionRequest): Promise<DecisionResult>;
+}
+
+export type DecisionDialect = 'port' | 'systemone';
+
+/** A bearer key, or a per-request token minter; a 401 requests one fresh token for that call. */
+export type DecisionCredential =
+  | string
+  | ((options: { refresh: boolean; signal?: AbortSignal }) => Promise<string>);
+
+export interface DecisionProviderSettings {
+  /** Full URL of the decision endpoint, not a base path. */
+  baseURL?: string;
+  model?: string;
+  dialect?: DecisionDialect;
+  requestKey?: string;
+  responseKey?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  /** Auth is required by default; self-hosted Laya can be unauthenticated. */
+  requiresAuth?: boolean;
+  apiKeyEnv?: string;
+}
+
+export type DecisionFailure =
+  | 'timeout'
+  | 'aborted'
+  | 'rate_limited'
+  | 'unauthorized'
+  | 'bad_request'
+  | 'server_error'
+  | 'network'
+  | 'unsupported_question'
+  | 'unsupported_mode'
+  | 'malformed_response';
+
+export class DecisionError extends Error {
+  readonly failure: DecisionFailure;
+  readonly provider: string;
+  readonly status?: number;
+  retryAfterMs?: number;
+
+  constructor(
+    failure: DecisionFailure,
+    message: string,
+    options?: { provider?: string; status?: number }
+  ) {
+    super(message);
+    this.name = 'DecisionError';
+    this.failure = failure;
+    this.provider = options?.provider ?? 'unknown';
+    this.status = options?.status;
+  }
+}
+
+/** A JSON boundary guard; never trust a parsed response's declared TypeScript type. */
+export function isDecisionObject(
+  value: unknown
+): value is { [key: string]: unknown } {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function readDecisionUsage(raw: unknown): DecisionUsage | null {
+  if (!isDecisionObject(raw)) {
+    return null;
+  }
+  const input = raw.input_tokens;
+  const output = raw.output_tokens;
+  const usage: DecisionUsage = {};
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input >= 0) {
+    usage.inputTokens = input;
+  }
+  if (
+    typeof output === 'number' &&
+    Number.isSafeInteger(output) &&
+    output >= 0
+  ) {
+    usage.outputTokens = output;
+  }
+  return Object.keys(usage).length > 0 ? usage : null;
+}
+
+export function isBooleanAnswer(
+  answer: DecisionAnswer | undefined
+): answer is BooleanAnswer {
+  return answer?.type === 'boolean';
+}
+
+export function isChoiceAnswer(
+  answer: DecisionAnswer | undefined
+): answer is ChoiceAnswer {
+  return answer?.type === 'choice';
+}
+
+export function isScoreAnswer(
+  answer: DecisionAnswer | undefined
+): answer is ScoreAnswer {
+  return answer?.type === 'score';
+}

package/src/graphs/Graph.ts

@@ -131,6 +131,10 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  ProviderTextProtectionError,
+  validateProviderTextProtection,
+} from '@/protection/providerText';
 import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
@@ -139,6 +143,10 @@ import {
   InvalidModelToolCallError,
   snapshotAcceptedModelResponse,
 } from './acceptedModelResponse';
+import {
+  collectSubagentHostArgNames,
+  pickSubagentHostArgInput,
+} from '@/tools/subagent/hostArgs';
 import {
   prepareProviderRequest,
   usesNativeOpenAIResponses,
@@ -1369,6 +1377,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
   readonly subagentExecutionContext?: t.SubagentExecutionContext;
   private readonly subagentContext?: t.SubagentContextAdapter;
+  private readonly onSubagentResolutionFailure?: t.StandardGraphInput['onSubagentResolutionFailure'];
   /** See {@link t.StandardGraphInput.preemption}. */
   preemption?: t.StreamPreemption;
   /**
@@ -1377,6 +1386,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * these on every streamed chunk event.
    */
   streamLimits: ResolvedStreamLimits;
+  /** Default-off mandatory provider prose release. */
+  providerTextProtection?: t.StandardGraphInput['providerTextProtection'];
   /**
    * Cumulative streamed argument bytes per in-flight tool call, keyed by
    * generation key + chunk index (see `resolveGenerationKey`). Per-run
@@ -1422,25 +1433,31 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * attempt lease; spans resets on purpose. */
   activeStreamLimitGenerations?: Set<string>;
 
-  /** The stream-limit error behind an already-fired breaker, whether this
+  /** The safety error behind an already-fired breaker, whether this
    * graph's own controller tripped or a parent run's breaker arrived through
    * the composed constructor signal (child graphs own separate controllers).
    * Providers can translate either abort into a generic error, and recovery
    * paths must not run in that state. */
   protected resolveTrippedBreakerReason(
     breakerSignal: AbortSignal = this.breakerAbort.signal
-  ): StreamLimitExceededError | PreparedSubagentError | undefined {
+  ):
+    | StreamLimitExceededError
+    | PreparedSubagentError
+    | ProviderTextProtectionError
+    | undefined {
     if (
       breakerSignal.aborted &&
       (breakerSignal.reason instanceof StreamLimitExceededError ||
-        breakerSignal.reason instanceof PreparedSubagentError)
+        breakerSignal.reason instanceof PreparedSubagentError ||
+        breakerSignal.reason instanceof ProviderTextProtectionError)
     ) {
       return breakerSignal.reason;
     }
     if (
       this.signal?.aborted === true &&
       (this.signal.reason instanceof StreamLimitExceededError ||
-        this.signal.reason instanceof PreparedSubagentError)
+        this.signal.reason instanceof PreparedSubagentError ||
+        this.signal.reason instanceof ProviderTextProtectionError)
     ) {
       return this.signal.reason;
     }
@@ -1547,8 +1564,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       subagentScope,
       subagentExecutionContext,
       subagentContext,
+      onSubagentResolutionFailure,
       preemption,
       streamLimits,
+      providerTextProtection,
       toolExecution,
       clientDelegatedToolNames,
     }: t.StandardGraphInput,
@@ -1575,10 +1594,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.subagentScope = subagentScope === true;
     this.subagentExecutionContext = subagentExecutionContext;
     this.subagentContext = subagentContext;
+    this.onSubagentResolutionFailure = onSubagentResolutionFailure;
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
+    if (providerTextProtection != null)
+      validateProviderTextProtection(providerTextProtection);
+    this.providerTextProtection = providerTextProtection;
     this.toolExecution = toolExecution;
-    if (clientDelegatedToolNames != null && clientDelegatedToolNames.length > 0) {
+    if (
+      clientDelegatedToolNames != null &&
+      clientDelegatedToolNames.length > 0
+    ) {
       if (agents.length !== 1) {
         throw new Error('Client tool delegation requires a single-agent graph');
       }
@@ -4401,7 +4427,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
-        if (primaryError instanceof InvalidModelToolCallError) {
+        if (
+          primaryError instanceof InvalidModelToolCallError ||
+          primaryError instanceof ProviderTextProtectionError
+        ) {
+          if (primaryError instanceof ProviderTextProtectionError)
+            attemptBreaker.abort(primaryError);
           throw primaryError;
         }
         if (
@@ -4744,7 +4775,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
-          if (fallbackError instanceof InvalidModelToolCallError) {
+          if (
+            fallbackError instanceof InvalidModelToolCallError ||
+            fallbackError instanceof ProviderTextProtectionError
+          ) {
+            if (fallbackError instanceof ProviderTextProtectionError)
+              attemptBreaker.abort(fallbackError);
             throw fallbackError;
           }
           if (
@@ -5342,7 +5378,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           usageSink: this.subagentUsageSink,
           taskConfig: this.subagentTasks,
           subagentContext: this.subagentContext,
+          onResolutionFailure: this.onSubagentResolutionFailure,
           streamLimits: this.streamLimits,
+          providerTextProtection: this.providerTextProtection,
           humanInTheLoop: this.humanInTheLoop,
           checkpointer: this.compileOptions?.checkpointer,
           maxDepth: effectiveSubagentDepth,
@@ -5357,6 +5395,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           ): GraphFactory => snapshotChildGraphFactory(parentHandlerRegistry),
         });
         this.registerSubagentExecutor(executor);
+        const hostArgNames = collectSubagentHostArgNames(executableConfigs);
 
         const subagentTool = tool(
           async (rawInput, config) => {
@@ -5366,6 +5405,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               subagent_thread_id?: string;
               run_in_background?: boolean;
             };
+            const hostArgInput = pickSubagentHostArgInput(input, hostArgNames);
+            if (!hostArgInput.ok) {
+              return hostArgInput.message;
+            }
             const description =
               typeof input.description === 'string' &&
               input.description.trim().length > 0
@@ -5422,6 +5465,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               parentConfigurable: config.configurable as
                 | Record<string, unknown>
                 | undefined,
+              ...(hostArgInput.hostArgs == null
+                ? {}
+                : { hostArgs: hostArgInput.hostArgs }),
             };
             if (input.run_in_background === true) {
               return executor.executeInBackground({
@@ -5552,8 +5598,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const delegatedNames = this.clientDelegatedToolNames;
       if (delegatedNames != null && delegatedNames.size > 0) {
         const { messages } = state as t.BaseGraphState;
-        const last = messages[messages.length - 1] as AIMessageChunk | undefined;
-        const calls = last?.getType() === 'ai' ? last.tool_calls ?? [] : [];
+        const last = messages[messages.length - 1] as
+          | AIMessageChunk
+          | undefined;
+        const calls = last?.getType() === 'ai' ? (last.tool_calls ?? []) : [];
         if (calls.some((call) => delegatedNames.has(call.name))) {
           if (
             calls.some(