@librechat/agents 4.0.1 → 4.0.3

package/dist/types/types/run.d.ts

@@ -24,8 +24,9 @@ export type LegacyGraphConfig = BaseGraphConfig & {
 } & Omit<g.StandardGraphInput, 
 /** `streamLimits` is excluded because legacy graphs receive limits only
  * via the top-level `RunConfig.streamLimits`; accepting the field here
- * would type-check but be silently ignored by `createLegacyGraph`. */
-'provider' | 'clientOptions' | 'agents' | 'streamLimits'> & Omit<g.AgentInputs, 'provider' | 'clientOptions' | 'agentId'>;
+ * would type-check but be silently ignored by `createLegacyGraph`.
+ * Required provider-text protection also belongs only to RunConfig. */
+'provider' | 'clientOptions' | 'agents' | 'streamLimits' | 'providerTextProtection'> & Omit<g.AgentInputs, 'provider' | 'clientOptions' | 'agentId'>;
 export type SupervisedGraphConfig = BaseGraphConfig & {
     type: 'supervised';
     /** Enable supervised router; when false, fall back to standard loop */
@@ -281,6 +282,8 @@ export type RunConfig = {
     subagentTasks?: SubagentTaskConfig;
     /** Authorizes and supplies host-owned context to isolated child runs. */
     subagentContext?: g.SubagentContextAdapter;
+    /** Host diagnostic sink for foreground, detached, and nested startup failures. */
+    onSubagentResolutionFailure?: g.StandardGraphInput['onSubagentResolutionFailure'];
     /**
      * Pre-constructed hook registry for this run. Hooks fire at lifecycle
      * points in `processStream` (RunStart, UserPromptSubmit, Stop,
@@ -315,6 +318,7 @@ export type RunConfig = {
      * tool-call argument byte cap is ON by default, the per-turn event cap is
      * opt-in. See {@link StreamLimits}.
      */
+    providerTextProtection?: g.StandardGraphInput['providerTextProtection'];
     streamLimits?: StreamLimits;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;

package/dist/types/types/tools.d.ts

@@ -502,6 +502,8 @@ export type JsonSchemaType = {
     properties?: Record<string, JsonSchemaType>;
     required?: string[];
     description?: string;
+    pattern?: string;
+    maxLength?: number;
     additionalProperties?: boolean | JsonSchemaType;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -329,7 +329,7 @@
     "uuid": "^11.1.1"
   },
   "peerDependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.67"
+    "@anthropic-ai/sandbox-runtime": "^0.0.78"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sandbox-runtime": {
@@ -337,7 +337,7 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.67",
+    "@anthropic-ai/sandbox-runtime": "0.0.78",
     "@anthropic-ai/vertex-sdk": "^0.12.0",
     "@eslint/js": "^10.0.1",
     "@langchain/langgraph-checkpoint-mongodb": "^1.4.1",
@@ -360,7 +360,7 @@
     "mongodb-memory-server-core": "^11.2.0",
     "prettier": "^3.6.2",
     "ts-jest": "^29.4.12",
-    "tsc-alias": "^1.8.10",
+    "tsc-alias": "^1.9.7",
     "tsdown": "^0.22.2",
     "tslib": "^2.6.3",
     "tsx": "^4.23.12",

package/src/agents/AgentContext.ts

@@ -58,6 +58,7 @@ import {
 import { isTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
 import { snapshotCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import { createExactTokenCountCache } from '@/llm/contextPressureMeter';
+import { markProviderTextInput } from '@/protection/providerTextInput';
 import { buildSummaryCarrierText } from '@/summarization/shared';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { apportionTokenCounts } from '@/utils/tokens';
@@ -960,7 +961,7 @@ export class AgentContext {
         : 0;
     }
 
-    return RunnableLambda.from((messages: BaseMessage[]) => {
+    return markProviderTextInput(RunnableLambda.from((messages: BaseMessage[]) => {
       const prefix: BaseMessage[] = systemMessage ? [systemMessage] : [];
 
       // Build the non-system portion (summary + conversation), then apply
@@ -998,7 +999,7 @@ export class AgentContext {
         );
       }
       return [...prefix, ...body];
-    }).withConfig({ runName: 'prompt' });
+    })).withConfig({ runName: 'prompt' });
   }
 
   private buildSummaryHumanMessage(

package/src/decisions/deadline.ts

@@ -0,0 +1,92 @@
+import { DecisionError } from './types';
+
+export type AwaitWithinDeadline = <T>(task: Promise<T>) => Promise<T>;
+
+/** Bounds even non-cooperative credential minters, fetches, body reads, and model calls. */
+export async function withDecisionDeadline<T>(
+  provider: string,
+  timeoutMs: number,
+  callerSignal: AbortSignal | undefined,
+  operation: (signal: AbortSignal, waitFor: AwaitWithinDeadline) => Promise<T>
+): Promise<T> {
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs <= 0 ||
+    timeoutMs > 3_600_000
+  ) {
+    throw new DecisionError('bad_request', 'invalid decision model timeout', {
+      provider,
+    });
+  }
+  if (callerSignal?.aborted === true) {
+    throw new DecisionError('aborted', 'caller aborted the request', {
+      provider,
+    });
+  }
+
+  const expiresAt = performance.now() + timeoutMs;
+  const deadline = new AbortController();
+  const signal = callerSignal
+    ? AbortSignal.any([callerSignal, deadline.signal])
+    : deadline.signal;
+  const timer = setTimeout(() => deadline.abort(), timeoutMs);
+  const expired = (): boolean => {
+    if (performance.now() >= expiresAt) {
+      deadline.abort();
+    }
+    return signal.aborted;
+  };
+  const abortError = (): DecisionError => {
+    if (callerSignal?.aborted === true) {
+      return new DecisionError('aborted', 'caller aborted the request', {
+        provider,
+      });
+    }
+    return new DecisionError('timeout', 'decision model deadline exceeded', {
+      provider,
+    });
+  };
+
+  const waitFor: AwaitWithinDeadline = <U>(task: Promise<U>): Promise<U> =>
+    new Promise<U>((resolve, reject) => {
+      if (expired()) {
+        void task.catch(() => {});
+        reject(abortError());
+        return;
+      }
+      const onAbort = (): void => {
+        signal.removeEventListener('abort', onAbort);
+        reject(abortError());
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+      if (expired()) {
+        onAbort();
+      }
+      task.then(
+        (value) => {
+          signal.removeEventListener('abort', onAbort);
+          if (expired()) {
+            reject(abortError());
+          } else {
+            resolve(value);
+          }
+        },
+        (error: unknown) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(expired() ? abortError() : error);
+        }
+      );
+    });
+
+  try {
+    return await waitFor(operation(signal, waitFor));
+  } catch (error) {
+    if (expired()) {
+      throw abortError();
+    }
+    throw error;
+  } finally {
+    expired();
+    clearTimeout(timer);
+  }
+}

package/src/decisions/dialect.ts

@@ -0,0 +1,200 @@
+import type {
+  DecisionAnswer,
+  DecisionDialect,
+  DecisionQuestion,
+} from './types';
+import { isDecisionObject } from './types';
+
+interface WireQuestion {
+  type: string;
+  instructions: DecisionQuestion['instructions'];
+  criteria?: DecisionQuestion['criteria'];
+}
+
+interface WireAnswer {
+  type?: unknown;
+  probability?: unknown;
+  noul?: unknown;
+  choice?: unknown;
+  score?: unknown;
+  confidence?: unknown;
+  probabilities?: unknown;
+}
+
+/** System One calls a yes/no question a `noul`; both dialects use a `{true, false}` criterion. */
+export function toWireQuestion(
+  question: DecisionQuestion,
+  dialect: DecisionDialect
+): WireQuestion {
+  const type =
+    dialect === 'systemone' && question.type === 'boolean'
+      ? 'noul'
+      : question.type;
+  if (question.criteria == null) {
+    return { type, instructions: question.instructions };
+  }
+  const criteria =
+    question.type === 'boolean' && typeof question.criteria === 'string'
+      ? { true: question.criteria }
+      : question.criteria;
+  return { type, instructions: question.instructions, criteria };
+}
+
+function isProbability(value: unknown): value is number {
+  return (
+    typeof value === 'number' &&
+    Number.isFinite(value) &&
+    value >= 0 &&
+    value <= 1
+  );
+}
+
+/** `undefined` means malformed; `null` means no distribution was reported. */
+function probabilitiesOf(
+  raw: unknown,
+  answerType: 'choice' | 'score',
+  question?: DecisionQuestion,
+  selectedChoice?: string
+): Record<string, number> | null | undefined {
+  if (raw == null) {
+    return null;
+  }
+  if (!isDecisionObject(raw)) {
+    return undefined;
+  }
+  const entries = Object.entries(raw);
+  if (entries.length === 0) {
+    return null;
+  }
+  if (
+    (question?.type === 'choice' &&
+      entries.length !== Object.keys(question.criteria).length) ||
+    (question?.type === 'score' && entries.length !== question.criteria.length)
+  ) {
+    return undefined;
+  }
+  const probabilities: Record<string, number> = Object.create(null);
+  let total = 0;
+  let maximum = 0;
+  for (const [key, value] of entries) {
+    if (!isProbability(value)) {
+      return undefined;
+    }
+    if (question?.type === 'choice' && !Object.hasOwn(question.criteria, key)) {
+      return undefined;
+    }
+    if (
+      answerType === 'score' &&
+      (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= entries.length)
+    ) {
+      return undefined;
+    }
+    probabilities[key] = value;
+    total += value;
+    maximum = Math.max(maximum, value);
+  }
+  if (
+    selectedChoice !== undefined &&
+    (!Object.hasOwn(probabilities, selectedChoice) ||
+      probabilities[selectedChoice] < maximum)
+  ) {
+    return undefined;
+  }
+  const roundingTolerance = Math.min(
+    0.02,
+    Math.max(0.01, entries.length * 0.00005 + 0.001)
+  );
+  return Math.abs(total - 1) <= roundingTolerance ? probabilities : undefined;
+}
+
+/** A validated answer, or `null` for one that cannot safely be read. */
+export function readAnswer(
+  answer: unknown,
+  dialect: DecisionDialect,
+  question?: DecisionQuestion
+): DecisionAnswer | null {
+  if (!isDecisionObject(answer)) {
+    return null;
+  }
+  const record: WireAnswer = answer;
+  const booleanType = dialect === 'systemone' ? 'noul' : 'boolean';
+  const probability =
+    dialect === 'systemone' ? record.noul : record.probability;
+  if (record.type === booleanType) {
+    if (
+      !isProbability(probability) ||
+      (question != null && question.type !== 'boolean')
+    ) {
+      return null;
+    }
+    return { type: 'boolean', probability };
+  }
+  if (record.type !== 'choice' && record.type !== 'score') {
+    return null;
+  }
+  const confidence = record.confidence;
+  if (confidence != null && !isProbability(confidence)) {
+    return null;
+  }
+  const probabilities = probabilitiesOf(
+    record.probabilities,
+    record.type,
+    question,
+    record.type === 'choice' && typeof record.choice === 'string'
+      ? record.choice
+      : undefined
+  );
+  if (probabilities === undefined) {
+    return null;
+  }
+  if (record.type === 'choice') {
+    if (
+      typeof record.choice !== 'string' ||
+      (question != null &&
+        (question.type !== 'choice' ||
+          !Object.hasOwn(question.criteria, record.choice)))
+    ) {
+      return null;
+    }
+    return {
+      type: 'choice',
+      choice: record.choice,
+      confidence: confidence ?? null,
+      probabilities,
+    };
+  }
+  if (
+    typeof record.score !== 'number' ||
+    !Number.isFinite(record.score) ||
+    record.score < 0 ||
+    (question != null &&
+      (question.type !== 'score' ||
+        record.score > question.criteria.length - 1))
+  ) {
+    return null;
+  }
+  if (probabilities !== null) {
+    let weightedScore = 0;
+    let levels = 0;
+    for (const [level, probability] of Object.entries(probabilities)) {
+      weightedScore += Number(level) * probability;
+      levels += 1;
+    }
+    const roundingTolerance = Math.min(
+      0.02,
+      0.00005 * (1 + (levels * (levels - 1)) / 2) + 0.001
+    );
+    if (
+      !Number.isFinite(weightedScore) ||
+      Math.abs(record.score - weightedScore) > roundingTolerance
+    ) {
+      return null;
+    }
+  }
+  return {
+    type: 'score',
+    score: record.score,
+    confidence: confidence ?? null,
+    probabilities,
+  };
+}

package/src/decisions/http.ts

@@ -0,0 +1,175 @@
+import type {
+  DecisionModel,
+  DecisionAnswer,
+  DecisionResult,
+  DecisionRequest,
+  DecisionDialect,
+  DecisionCredential,
+  DecisionQuestion,
+} from './types';
+import type { DecisionFetch } from './transport';
+import { DecisionError, isDecisionObject, readDecisionUsage } from './types';
+import { validateDecisionQuestions } from './questions';
+import { toWireQuestion, readAnswer } from './dialect';
+import { createTransport } from './transport';
+
+export const HTTP_PROVIDER_ID = 'http';
+
+export interface HttpDecisionModelOptions {
+  providerId?: string;
+  apiKey?: DecisionCredential;
+  requiresAuth?: boolean;
+  /** Full URL, not a base path. */
+  endpoint: string;
+  model?: string;
+  dialect?: DecisionDialect;
+  requestKey?: string;
+  responseKey?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetch?: DecisionFetch;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  onAnswered?: (label: string, ms: number) => void;
+}
+
+export function parseEnvelope(
+  body: string,
+  providerId: string,
+  readOne: (
+    answer: unknown,
+    question?: DecisionQuestion
+  ) => DecisionAnswer | null,
+  responseKey?: string,
+  expected?: Record<string, DecisionQuestion>
+): DecisionResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new DecisionError('malformed_response', 'response was not JSON', {
+      provider: providerId,
+    });
+  }
+  if (!isDecisionObject(parsed)) {
+    throw new DecisionError(
+      'malformed_response',
+      'response was not an object',
+      {
+        provider: providerId,
+      }
+    );
+  }
+  const unwrapped =
+    responseKey != null && responseKey !== '' ? parsed[responseKey] : parsed;
+  if (
+    !isDecisionObject(unwrapped) ||
+    !isDecisionObject(unwrapped.answers) ||
+    Object.keys(unwrapped.answers).length === 0
+  ) {
+    throw new DecisionError(
+      'malformed_response',
+      'response carried no answers',
+      {
+        provider: providerId,
+      }
+    );
+  }
+
+  const answers: DecisionResult['answers'] = Object.create(null);
+  for (const [id, answer] of Object.entries(unwrapped.answers)) {
+    if (expected && !Object.hasOwn(expected, id)) {
+      throw new DecisionError(
+        'malformed_response',
+        'response carried an unknown answer',
+        {
+          provider: providerId,
+        }
+      );
+    }
+    const mapped = readOne(answer, expected?.[id]);
+    if (!mapped) {
+      throw new DecisionError(
+        'malformed_response',
+        'response carried an invalid answer',
+        {
+          provider: providerId,
+        }
+      );
+    }
+    answers[id] = mapped;
+  }
+
+  return {
+    model: typeof unwrapped.model === 'string' ? unwrapped.model : 'unknown',
+    answers,
+    usage: readDecisionUsage(unwrapped.usage),
+  };
+}
+
+/** Jev and Laya use the same System One HTTP dialect, but may report different confidence metrics. */
+export function createHttpDecisionModel(
+  options: HttpDecisionModelOptions
+): DecisionModel {
+  const providerId = options.providerId ?? HTTP_PROVIDER_ID;
+  const send = createTransport({ ...options, providerId });
+  const model = options.model ?? '';
+  const dialect: DecisionDialect = options.dialect ?? 'port';
+  const { requestKey, responseKey } = options;
+
+  return {
+    id: providerId,
+    model,
+    async decide(request: DecisionRequest): Promise<DecisionResult> {
+      return send(
+        () => {
+          const entries = validateDecisionQuestions(
+            request.questions,
+            providerId
+          );
+          const questions: Record<
+            string,
+            ReturnType<typeof toWireQuestion>
+          > = Object.create(null);
+          const expected: Record<string, DecisionQuestion> =
+            Object.create(null);
+          for (const [id, question] of entries) {
+            questions[id] = toWireQuestion(question, dialect);
+            expected[id] = question;
+          }
+          const inner = { state: request.state, questions };
+          let payload: string;
+          try {
+            payload = JSON.stringify({
+              ...(model !== '' ? { model } : {}),
+              ...(requestKey != null && requestKey !== ''
+                ? { [requestKey]: inner }
+                : inner),
+            });
+          } catch {
+            throw new DecisionError(
+              'bad_request',
+              'invalid decision model request',
+              {
+                provider: providerId,
+              }
+            );
+          }
+          return {
+            payload,
+            parse: (body: string) =>
+              parseEnvelope(
+                body,
+                providerId,
+                (answer, question) => readAnswer(answer, dialect, question),
+                responseKey,
+                expected
+              ),
+          };
+        },
+        request.signal,
+        request.label ?? 'decide',
+        request.timeoutMs
+      );
+    },
+  };
+}

package/src/decisions/index.ts

@@ -0,0 +1,14 @@
+export * from './types';
+export * from './questions';
+export * from './presets';
+export {
+  createHttpDecisionModel,
+  parseEnvelope,
+  HTTP_PROVIDER_ID,
+} from './http';
+export { createStructuredChatDecisionModel } from './structuredChat';
+export type { HttpDecisionModelOptions } from './http';
+export type { StructuredChatDecisionModelOptions } from './structuredChat';
+export { toWireQuestion, readAnswer } from './dialect';
+export { createTransport } from './transport';
+export type { DecisionFetch, Transport, TransportOptions } from './transport';

package/src/decisions/presets.ts

@@ -0,0 +1,111 @@
+import type {
+  DecisionModel,
+  DecisionCredential,
+  DecisionProviderSettings,
+} from './types';
+import type { DecisionFetch } from './transport';
+import { createHttpDecisionModel } from './http';
+
+export const DEFAULT_API_KEY_ENV = 'DECISION_API_KEY';
+
+/**
+ * Known HTTP hosts as settings, not new decision model implementations. Jev and Laya speak the
+ * same wire protocol, but their confidence measures and checkpoint calibration differ.
+ */
+export const DECISION_PRESETS: Readonly<
+  Record<string, Readonly<DecisionProviderSettings>>
+> = Object.freeze({
+  http: Object.freeze({
+    dialect: 'port',
+    requiresAuth: true,
+    apiKeyEnv: DEFAULT_API_KEY_ENV,
+  }),
+  typesafe: Object.freeze({
+    baseURL: 'https://api.typesafe.ai/v1/systemone',
+    model: 'jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'TYPESAFE_API_KEY',
+  }),
+  laya: Object.freeze({
+    /** Supply the server's full /v1/systemone URL; no model lets Laya route by language. */
+    dialect: 'systemone',
+    requiresAuth: false,
+  }),
+  clickhouse: Object.freeze({
+    /** ClickHouse's inference gateway; the token is what `dataplanectl chai auth token` prints, hourly. */
+    baseURL: 'https://inference-internal.clickhouse.cloud/v1/systemone',
+    model: 'jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'CHAI_AUTH_TOKEN',
+  }),
+  openrouter: Object.freeze({
+    baseURL: 'https://openrouter.ai/api/alpha/decisions',
+    model: '~typesafe/jev-latest',
+    dialect: 'systemone',
+    requiresAuth: true,
+    apiKeyEnv: 'OPENROUTER_KEY',
+  }),
+  cloudflare: Object.freeze({
+    /** No default URL: the account id is part of it. */
+    model: 'typesafe/jev',
+    dialect: 'systemone',
+    requestKey: 'input',
+    responseKey: 'result',
+    requiresAuth: true,
+    apiKeyEnv: 'CLOUDFLARE_API_TOKEN',
+  }),
+});
+
+export function decisionPreset(
+  name: string | undefined
+): DecisionProviderSettings | null {
+  if (name == null || name === '') {
+    return null;
+  }
+  return Object.hasOwn(DECISION_PRESETS, name)
+    ? { ...DECISION_PRESETS[name] }
+    : null;
+}
+
+/** Caller settings win except that required preset authentication cannot be weakened. */
+export function mergeDecisionSettings(
+  preset: DecisionProviderSettings | null,
+  configured: DecisionProviderSettings | undefined
+): DecisionProviderSettings {
+  return {
+    ...(preset ?? {}),
+    ...(configured ?? {}),
+    ...(preset?.requiresAuth === true ? { requiresAuth: true } : {}),
+  };
+}
+
+export function decisionProviderNames(): string[] {
+  return Object.keys(DECISION_PRESETS);
+}
+
+export function createDecisionModel(
+  settings: DecisionProviderSettings,
+  apiKey?: DecisionCredential,
+  options?: {
+    fetch?: DecisionFetch;
+    providerId?: string;
+    onAnswered?: (label: string, ms: number) => void;
+  }
+): DecisionModel {
+  return createHttpDecisionModel({
+    providerId: options?.providerId,
+    apiKey,
+    requiresAuth: settings.requiresAuth,
+    endpoint: settings.baseURL ?? '',
+    model: settings.model,
+    dialect: settings.dialect,
+    requestKey: settings.requestKey,
+    responseKey: settings.responseKey,
+    timeoutMs: settings.timeoutMs,
+    maxRetries: settings.maxRetries,
+    fetch: options?.fetch,
+    onAnswered: options?.onAnswered,
+  });
+}