@librechat/agents 3.6.12 → 3.6.14

package/src/index.ts

@@ -69,6 +69,7 @@ export {
 export type { Interrupt } from '@langchain/langgraph';
 
 /* LLM */
+export { markTokenCounterCacheCompatible } from './llm/tokenCounterCacheCompatibility';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type {

package/src/llm/contextPressureMeter.ts

@@ -1,6 +1,7 @@
+import { isProxy } from 'node:util/types';
 import { ToolMessage } from '@langchain/core/messages';
 
-import type { BaseMessage } from '@langchain/core/messages';
+import type { AIMessage, BaseMessage } from '@langchain/core/messages';
 import type { ProviderPayloadMeasurement } from '@/llm/prepareProviderRequest';
 import type * as t from '@/types';
 
@@ -19,6 +20,7 @@ interface ContextPressureUsage {
 
 interface ContextPressureMeterParams {
   tokenCounter?: t.TokenCounter;
+  tokenCountCache?: ExactTokenCountCache;
   sourceMessages: BaseMessage[];
   retainedMessages: BaseMessage[];
   indexTokenCountMap: Record<string, number | undefined>;
@@ -51,6 +53,164 @@ export interface ContextPressureMeter {
   ): ProviderPayloadMeasurement;
 }
 
+export interface ExactTokenCountCache {
+  count(message: BaseMessage): number;
+}
+
+interface StableTokenSurface {
+  content: string;
+  messageType: string;
+  role?: string;
+  additionalType?: string;
+}
+
+interface ExactTokenCountCacheEntry {
+  surface: StableTokenSurface;
+  tokens: number;
+}
+
+function readDataProperty(
+  owner: object,
+  property: PropertyKey
+): { own: boolean; safe: boolean; value?: unknown } {
+  let descriptor: PropertyDescriptor | undefined;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(owner, property);
+  } catch {
+    return { own: false, safe: false };
+  }
+  if (descriptor == null) {
+    return { own: false, safe: true };
+  }
+  return 'value' in descriptor
+    ? { own: true, safe: true, value: descriptor.value }
+    : { own: true, safe: false };
+}
+
+function getStableTokenSurface(
+  message: BaseMessage
+): StableTokenSurface | undefined {
+  if (isProxy(message)) {
+    return undefined;
+  }
+  const contentProperty = readDataProperty(message, 'content');
+  if (
+    !contentProperty.safe ||
+    !contentProperty.own ||
+    typeof contentProperty.value !== 'string'
+  ) {
+    return undefined;
+  }
+  const messageType = message.getType();
+  const roleProperty = readDataProperty(message, 'role');
+  if (!roleProperty.safe || (!roleProperty.own && 'role' in message)) {
+    return undefined;
+  }
+  const role = roleProperty.value;
+  if (role != null && typeof role !== 'string') {
+    return undefined;
+  }
+
+  const additionalKwargsProperty = readDataProperty(
+    message,
+    'additional_kwargs'
+  );
+  if (!additionalKwargsProperty.safe || !additionalKwargsProperty.own) {
+    return undefined;
+  }
+  const rawAdditionalKwargs = additionalKwargsProperty.value;
+  if (
+    rawAdditionalKwargs == null ||
+    typeof rawAdditionalKwargs !== 'object' ||
+    isProxy(rawAdditionalKwargs)
+  ) {
+    return undefined;
+  }
+  const additionalKwargs = rawAdditionalKwargs;
+  const typeProperty = readDataProperty(additionalKwargs, 'type');
+  if (!typeProperty.safe) {
+    return undefined;
+  }
+  if (messageType === 'ai' || role === 'assistant') {
+    const toolCallsProperty = readDataProperty(
+      message as AIMessage,
+      'tool_calls'
+    );
+    if (
+      !toolCallsProperty.safe ||
+      (!toolCallsProperty.own && 'tool_calls' in message)
+    ) {
+      return undefined;
+    }
+    const toolCalls = toolCallsProperty.value;
+    if (
+      toolCalls != null &&
+      (!Array.isArray(toolCalls) || isProxy(toolCalls) || toolCalls.length > 0)
+    ) {
+      return undefined;
+    }
+    const functionCall = readDataProperty(additionalKwargs, 'function_call');
+    if (!functionCall.safe || functionCall.value != null) {
+      return undefined;
+    }
+  }
+
+  let additionalType: string | undefined;
+  if (messageType === 'tool') {
+    const typeValue = typeProperty.value;
+    if (typeValue != null && typeof typeValue !== 'string') {
+      return undefined;
+    }
+    additionalType = typeof typeValue === 'string' ? typeValue : undefined;
+  }
+
+  return {
+    content: contentProperty.value,
+    messageType,
+    ...(role != null && { role }),
+    ...(additionalType != null && { additionalType }),
+  };
+}
+
+function tokenSurfacesMatch(
+  left: StableTokenSurface,
+  right: StableTokenSurface
+): boolean {
+  return (
+    left.content === right.content &&
+    left.messageType === right.messageType &&
+    left.role === right.role &&
+    left.additionalType === right.additionalType
+  );
+}
+
+/** Reuses exact counts only while every token-relevant stable field matches. */
+export function createExactTokenCountCache(
+  tokenCounter: t.TokenCounter
+): ExactTokenCountCache {
+  const entries = new WeakMap<BaseMessage, ExactTokenCountCacheEntry>();
+  return {
+    count(message): number {
+      const surface = getStableTokenSurface(message);
+      const cached = entries.get(message);
+      if (
+        surface != null &&
+        cached != null &&
+        tokenSurfacesMatch(cached.surface, surface)
+      ) {
+        return cached.tokens;
+      }
+      const tokens = tokenCounter(message);
+      if (surface != null) {
+        entries.set(message, { surface, tokens });
+      } else {
+        entries.delete(message);
+      }
+      return tokens;
+    },
+  };
+}
+
 function getProviderMessageOriginKey(message: BaseMessage): string | undefined {
   const type = message.getType();
   if (
@@ -69,6 +229,7 @@ function getProviderMessageOriginKey(message: BaseMessage): string | undefined {
 /** Measures repeated provider projections while tokenizing each message object once. */
 export function createContextPressureMeter({
   tokenCounter,
+  tokenCountCache,
   sourceMessages,
   retainedMessages,
   indexTokenCountMap,
@@ -88,12 +249,16 @@ export function createContextPressureMeter({
     if (cached != null) {
       return cached;
     }
-    const tokens = tokenCounter?.(message) ?? 0;
+    const tokens =
+      tokenCountCache?.count(message) ?? tokenCounter?.(message) ?? 0;
     tokenCounts.set(message, tokens);
     return tokens;
   };
 
-  if (contextUsage != null && tokenCounter != null) {
+  if (
+    contextUsage != null &&
+    (tokenCounter != null || tokenCountCache != null)
+  ) {
     const sourceIndices = new WeakMap<BaseMessage, number>();
     for (let i = 0; i < sourceMessages.length; i++) {
       sourceIndices.set(sourceMessages[i], i);
@@ -179,7 +344,7 @@ export function createContextPressureMeter({
       contextUsage?.effectiveInstructionTokens ??
       (forceRawRecount ? instructionTokens : undefined);
     if (
-      tokenCounter == null ||
+      (tokenCounter == null && tokenCountCache == null) ||
       contextBudget == null ||
       effectiveInstructionTokens == null
     ) {

package/src/llm/tokenCounterCacheCompatibility.ts

@@ -0,0 +1,22 @@
+import type { BaseMessage } from '@langchain/core/messages';
+
+const stableMessageTokenCounters = new WeakSet<
+  (message: BaseMessage) => number
+>();
+
+/**
+ * Opts a deterministic counter into stable-message count reuse. The counter
+ * must depend only on the message surface consumed by `getTokenCountForMessage`.
+ */
+export function markTokenCounterCacheCompatible<
+  TCounter extends (message: BaseMessage) => number,
+>(tokenCounter: TCounter): TCounter {
+  stableMessageTokenCounters.add(tokenCounter);
+  return tokenCounter;
+}
+
+export function isTokenCounterCacheCompatible(
+  tokenCounter: (message: BaseMessage) => number
+): boolean {
+  return stableMessageTokenCounters.has(tokenCounter);
+}

package/src/tools/cloudflare/CloudflareSandboxExecutionEngine.ts

@@ -5,11 +5,11 @@ import type { WriteFileOptions, MakeDirectoryOptions, Stats } from 'fs';
 import type { ChildProcessWithoutNullStreams } from 'child_process';
 import type { FileHandle } from 'fs/promises';
 import type { WorkspaceFS, ReaddirEntry } from '@/tools/local/workspaceFS';
+import type * as t from '@/types';
 import {
   WorkspaceClientTimeoutError,
   isWorkspaceClientTimeoutError,
 } from '@/tools/local/workspaceFS';
-import type * as t from '@/types';
 import {
   LOCAL_SPAWN_TIMEOUT_MS,
   validateBashCommand,
@@ -44,9 +44,28 @@ type SandboxRuntimeContext = {
   shell: string;
 };
 
+type ExecutionWorldCacheEntry = {
+  world: t.ExecutionWorld;
+  workspaceRoot: string;
+  timeoutMs: number;
+  sandbox: t.CloudflareSandboxExecutionConfig['sandbox'];
+};
+
+const executionWorldCache = new WeakMap<
+  t.CloudflareSandboxExecutionConfig,
+  ExecutionWorldCacheEntry
+>();
+
+type SandboxFactoryCacheEntry = {
+  sandbox: () =>
+    | t.CloudflareSandboxRuntime
+    | Promise<t.CloudflareSandboxRuntime>;
+  promise: Promise<t.CloudflareSandboxRuntime>;
+};
+
 const sandboxFactoryCache = new WeakMap<
   t.CloudflareSandboxExecutionConfig,
-  Promise<t.CloudflareSandboxRuntime>
+  SandboxFactoryCacheEntry
 >();
 
 function normalizeWorkspaceRoot(workspaceRoot: string): string {
@@ -69,17 +88,20 @@ export async function resolveCloudflareSandbox(
   if (typeof sandbox !== 'function') {
     return sandbox;
   }
-  let cached = sandboxFactoryCache.get(config);
-  if (cached == null) {
-    cached = Promise.resolve()
-      .then(() => sandbox())
-      .catch((error: unknown) => {
-        sandboxFactoryCache.delete(config);
-        throw error;
-      });
-    sandboxFactoryCache.set(config, cached);
+  const cached = sandboxFactoryCache.get(config);
+  if (cached?.sandbox === sandbox) {
+    return cached.promise;
   }
-  return cached;
+  const promise = Promise.resolve()
+    .then(() => sandbox())
+    .catch((error: unknown) => {
+      if (sandboxFactoryCache.get(config)?.promise === promise) {
+        sandboxFactoryCache.delete(config);
+      }
+      throw error;
+    });
+  sandboxFactoryCache.set(config, { sandbox, promise });
+  return promise;
 }
 
 async function getRuntimeContext(
@@ -687,6 +709,39 @@ function createCloudflareSpawn(
   };
 }
 
+/**
+ * Returns one stable filesystem/process world for a Cloudflare configuration.
+ * Probe caches key on the spawn identity, so retaining it avoids repeating
+ * remote capability checks whenever an agent binding rebuilds its tools.
+ */
+export function createCloudflareExecutionWorld(
+  config: t.CloudflareSandboxExecutionConfig
+): t.ExecutionWorld {
+  const workspaceRoot = getCloudflareWorkspaceRoot(config);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const cached = executionWorldCache.get(config);
+  if (
+    cached?.workspaceRoot === workspaceRoot &&
+    Object.is(cached.timeoutMs, timeoutMs) &&
+    cached.sandbox === config.sandbox
+  ) {
+    return cached.world;
+  }
+  const fs = Object.freeze(createCloudflareWorkspaceFS(config));
+  const world = Object.freeze({
+    spawn: createCloudflareSpawn(config),
+    fs,
+    sandboxed: true,
+  });
+  executionWorldCache.set(config, {
+    world,
+    workspaceRoot,
+    timeoutMs,
+    sandbox: config.sandbox,
+  });
+  return world;
+}
+
 export function createCloudflareLocalExecutionConfig(
   config: t.CloudflareSandboxExecutionConfig
 ): t.LocalExecutionConfig {
@@ -694,11 +749,7 @@ export function createCloudflareLocalExecutionConfig(
   return {
     cwd: workspaceRoot,
     workspace: { root: workspaceRoot },
-    exec: {
-      spawn: createCloudflareSpawn(config),
-      fs: createCloudflareWorkspaceFS(config),
-      sandboxed: true,
-    },
+    exec: createCloudflareExecutionWorld(config),
     shell: config.shell ?? 'bash',
     timeoutMs: config.timeoutMs,
     maxOutputChars: config.maxOutputChars,

package/src/tools/cloudflare/CloudflareSandboxTools.ts

@@ -2,8 +2,8 @@ import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
+  createCloudflareExecutionWorld,
   createCloudflareLocalExecutionConfig,
-  createCloudflareWorkspaceFS,
   executeCloudflareBash,
   executeCloudflareCode,
   formatCloudflareOutput,
@@ -161,7 +161,7 @@ export function createCloudflareCodingTools(
     options.checkpointer ??
     (config.fileCheckpointing === true
       ? createLocalFileCheckpointer({
-        fs: createCloudflareWorkspaceFS(config),
+        fs: createCloudflareExecutionWorld(config).fs,
       })
       : undefined);
   const tools = [
@@ -193,11 +193,12 @@ export function createCloudflareCodingToolBundle(
   config: t.CloudflareSandboxExecutionConfig,
   options: { checkpointer?: t.LocalFileCheckpointer } = {}
 ): CloudflareCodingToolBundle {
+  const world = createCloudflareExecutionWorld(config);
   const checkpointer =
     options.checkpointer ??
     (config.fileCheckpointing === true
       ? createLocalFileCheckpointer({
-        fs: createCloudflareWorkspaceFS(config),
+        fs: world.fs,
       })
       : undefined);
   return {

package/src/tools/local/LocalCodingTools.ts

@@ -4,16 +4,19 @@ import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
-  createLocalBashProgrammaticToolCallingTool,
-  createLocalProgrammaticToolCallingTool,
-} from './LocalProgrammaticToolCalling';
-import {
+  commandAvailabilityEnvCacheKey,
   getSpawn,
   getWorkspaceFS,
+  probeLocalCommandAvailability,
   resolveWorkspacePathSafe,
+  setCommandAvailabilityCacheEntry,
   spawnLocalProcess,
   truncateLocalOutput,
 } from './LocalExecutionEngine';
+import {
+  createLocalBashProgrammaticToolCallingTool,
+  createLocalProgrammaticToolCallingTool,
+} from './LocalProgrammaticToolCalling';
 import {
   createLocalBashExecutionTool,
   createLocalCodeExecutionTool,
@@ -736,30 +739,14 @@ export function createLocalEditFileTool(
  * spawn-per-search.
  */
 // Per-backend × per-env cache. Codex P1 #34 — keying by spawn
-// backend alone misses the case where two Runs share a backend but
-// vary `local.env` (especially PATH). Stale cache then claims `rg`
-// is available, the rg path runs, and the spawn fails with ENOENT
-// instead of falling back to the Node walker. The inner Map is
-// keyed by a stable JSON hash of the effective env so each unique
-// env gets its own probe.
+// backend alone misses the case where two Runs share a backend but vary
+// `local.env`. The inner map uses non-plaintext environment hashes and is
+// bounded so stable worlds do not retain unbounded variants or raw secrets.
 let ripgrepAvailabilityByBackend = new WeakMap<
   t.LocalSpawn,
-  Map<string, Promise<boolean>>
+  Map<string, ReturnType<typeof probeLocalCommandAvailability>>
 >();
 
-function envCacheKey(env: NodeJS.ProcessEnv | undefined): string {
-  // PATH is the only env entry that affects command lookup, but
-  // hashing the whole env keeps the key correct for hosts that
-  // vary anything else relevant. Stable JSON via sorted keys so
-  // {A:1,B:2} and {B:2,A:1} produce the same hash.
-  if (env == null) return '';
-  const sorted: Record<string, string | undefined> = {};
-  for (const k of Object.keys(env).sort()) {
-    sorted[k] = env[k];
-  }
-  return JSON.stringify(sorted);
-}
-
 async function isRipgrepAvailable(
   config: t.LocalExecutionConfig
 ): Promise<boolean> {
@@ -769,20 +756,23 @@ async function isRipgrepAvailable(
     envMap = new Map();
     ripgrepAvailabilityByBackend.set(backend, envMap);
   }
-  const envKey = envCacheKey(config.env);
+  const envKey = commandAvailabilityEnvCacheKey(config.env);
   let probePromise = envMap.get(envKey);
   if (probePromise == null) {
-    probePromise = spawnLocalProcess(
-      'rg',
-      ['--version'],
-      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
-      { internal: true }
-    )
-      .then((probe) => probe.exitCode === 0)
-      .catch(() => false);
-    envMap.set(envKey, probePromise);
+    probePromise = probeLocalCommandAvailability('rg', ['--version'], config);
+    setCommandAvailabilityCacheEntry(envMap, envKey, probePromise);
+  }
+  const result = await probePromise;
+  if (!result.cacheable && envMap.get(envKey) === probePromise) {
+    envMap.delete(envKey);
+  }
+  if (result.cacheUntil != null && result.cacheUntil <= Date.now()) {
+    if (envMap.get(envKey) === probePromise) {
+      envMap.delete(envKey);
+    }
+    return isRipgrepAvailable(config);
   }
-  return probePromise;
+  return result.available;
 }
 
 /**

package/src/tools/local/LocalExecutionEngine.ts

@@ -21,6 +21,36 @@ const DEFAULT_MAX_OUTPUT_CHARS = 200000;
 const DEFAULT_MAX_SPAWNED_BYTES = 50 * 1024 * 1024;
 const DEFAULT_LOCAL_SESSION_ID = 'local';
 const DEFAULT_SHELL = process.platform === 'win32' ? 'bash.exe' : 'bash';
+const MAX_COMMAND_AVAILABILITY_ENVIRONMENTS = 16;
+const NEGATIVE_COMMAND_AVAILABILITY_TTL_MS = 5000;
+
+/** Produces a stable, non-plaintext key for environment-sensitive probes. */
+export function commandAvailabilityEnvCacheKey(
+  env: NodeJS.ProcessEnv | undefined
+): string {
+  if (env == null) {
+    return '';
+  }
+  const sorted = Object.keys(env)
+    .sort()
+    .map((key): [string, string | null] => [key, env[key] ?? null]);
+  return createHash('sha256').update(JSON.stringify(sorted)).digest('hex');
+}
+
+/** Adds a probe entry while bounding retained environment variants. */
+export function setCommandAvailabilityCacheEntry<T>(
+  cache: Map<string, T>,
+  key: string,
+  value: T
+): void {
+  if (!cache.has(key) && cache.size >= MAX_COMMAND_AVAILABILITY_ENVIRONMENTS) {
+    const oldestKey = cache.keys().next().value;
+    if (oldestKey !== undefined) {
+      cache.delete(oldestKey);
+    }
+  }
+  cache.set(key, value);
+}
 
 // `(?:--\s+)?` before each destructive-target alternation: GNU/BSD
 // utilities accept `--` as an end-of-options marker, so `rm -rf -- /`
@@ -259,13 +289,34 @@ export function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[] {
   return out;
 }
 
+/** Node-host execution world used when no backend override is configured. */
+export const nodeExecutionWorld: t.ExecutionWorld = Object.freeze({
+  spawn: spawn as t.LocalSpawn,
+  fs: nodeWorkspaceFS,
+  sandboxed: false,
+});
+
+/** Resolves filesystem and subprocess capabilities as one execution world. */
+export function getExecutionWorld(
+  config?: t.LocalExecutionConfig
+): t.ExecutionWorld {
+  if (config?.exec == null && config?.spawn == null) {
+    return nodeExecutionWorld;
+  }
+  return {
+    spawn: config.exec?.spawn ?? config.spawn ?? nodeExecutionWorld.spawn,
+    fs: config.exec?.fs ?? nodeExecutionWorld.fs,
+    sandboxed: config.exec?.sandboxed ?? false,
+  };
+}
+
 /**
  * Pluggable spawn resolver. Honours `local.exec.spawn` first, falls
  * back to the legacy top-level `local.spawn`, then to Node's
  * `child_process.spawn`. Centralised so engine swapping is one knob.
  */
 export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
-  return (config?.exec?.spawn ?? config?.spawn ?? spawn) as t.LocalSpawn;
+  return getExecutionWorld(config).spawn;
 }
 
 /**
@@ -274,7 +325,7 @@ export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
  * its own implementation here and inherits every file-touching tool.
  */
 export function getWorkspaceFS(config?: t.LocalExecutionConfig): WorkspaceFS {
-  return config?.exec?.fs ?? nodeWorkspaceFS;
+  return getExecutionWorld(config).fs;
 }
 
 /**
@@ -345,7 +396,7 @@ function maybeWarnSandboxOff(config: t.LocalExecutionConfig): void {
   if (
     sandboxOffWarned ||
     shouldUseLocalSandbox(config) ||
-    config.exec?.sandboxed === true
+    getExecutionWorld(config).sandboxed
   ) {
     return;
   }
@@ -904,6 +955,72 @@ export async function spawnLocalProcess(
   });
 }
 
+/** Result of a command-availability probe and whether its verdict is stable. */
+export type CommandAvailabilityProbe = {
+  available: boolean;
+  cacheable: boolean;
+  cacheUntil?: number;
+};
+
+async function isDurableCommandLookupError(
+  error: object,
+  config: t.LocalExecutionConfig
+): Promise<boolean> {
+  if (!('code' in error) || error.code !== 'ENOENT') {
+    return false;
+  }
+  try {
+    const cwd = getLocalCwd(config);
+    return (await getWorkspaceFS(config).stat(cwd)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probes one executable without turning transient backend failures into
+ * permanent capability facts. Exit 126/127 is a definite unusable/missing
+ * executable. A native ENOENT is stable only when the current working
+ * directory exists; timeouts, transport failures, and ambiguous lookup
+ * failures are retried.
+ */
+export async function probeLocalCommandAvailability(
+  command: string,
+  args: string[],
+  config: t.LocalExecutionConfig
+): Promise<CommandAvailabilityProbe> {
+  try {
+    const result = await spawnLocalProcess(
+      command,
+      args,
+      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+      { internal: true }
+    );
+    const available = result.exitCode === 0;
+    const durableNegative =
+      result.exitCode === 126 || result.exitCode === 127;
+    return {
+      available,
+      cacheable: available || durableNegative,
+      ...(durableNegative
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  } catch (error) {
+    const cacheable =
+      typeof error === 'object' &&
+      error != null &&
+      (await isDurableCommandLookupError(error, config));
+    return {
+      available: false,
+      cacheable,
+      ...(cacheable
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  }
+}
+
 export async function executeLocalBash(
   command: string,
   config: t.LocalExecutionConfig = {}