@librechat/agents 3.7.6 → 3.7.8

package/src/eventActor/index.ts

@@ -5,7 +5,15 @@ export {
 export type {
   EventActorAdapterPrepareRequest,
   EventActorAdapterPreparation,
+  EventActorAdapterInvocationResult,
+  EventActorAdapterResumeRequest,
+  EventActorAdapterResumeResult,
+  EventActorAdapterSuspendedResult,
   EventActorAppliedResult,
+  EventActorAdapterCancelSuspensionRequest,
+  EventActorAdapterCancelSuspensionResult,
+  EventActorCancelSuspensionRequest,
+  EventActorCancelSuspensionResult,
   EventActorCheckpointFork,
   EventActorCheckpointReference,
   EventActorCommitRequest,
@@ -21,12 +29,21 @@ export type {
   EventActorInvocation,
   EventActorInvocationContext,
   EventActorIndeterminateResult,
+  EventActorInterrupt,
   EventActorInvocationReference,
   EventActorInvocationResult,
   EventActorPreparation,
   EventActorPreparationContext,
   EventActorPreparedInvocation,
   EventActorPrepareRequest,
+  EventActorResumeRequest,
+  EventActorSettleSuspensionRequest,
+  EventActorSettleSuspensionResult,
+  EventActorSettlementAuthority,
   EventActorSettlementResult,
+  EventActorSuspendRequest,
+  EventActorSuspendResult,
+  EventActorSuspendedResult,
+  EventActorSuspension,
   EventActorTerminalResult,
 } from './types';

package/src/eventActor/types.ts

@@ -74,14 +74,156 @@ export type EventActorTerminalResult<TResult extends EventActorEvent> =
     }
   | { status: 'completed_no_action'; result?: TResult };
 
+/** JSON-safe interrupt descriptor retained with a suspended invocation fork. */
+export interface EventActorInterrupt<
+  TPayload extends EventActorEvent = EventActorEvent,
+> {
+  id: string;
+  payload: TPayload;
+}
+
+/**
+ * Nonterminal adapter outcome. The checkpoint must already contain the pause;
+ * the SDK publishes its authority through `suspend` before exposing it.
+ */
+export interface EventActorAdapterSuspendedResult<
+  TPayload extends EventActorEvent = EventActorEvent,
+> {
+  status: 'suspended';
+  checkpoint: EventActorCheckpointFork;
+  interrupt: EventActorInterrupt<TPayload>;
+}
+
+export type EventActorAdapterInvocationResult<
+  TResult extends EventActorEvent,
+  TPayload extends EventActorEvent = EventActorEvent,
+> =
+  | EventActorTerminalResult<TResult>
+  | EventActorAdapterSuspendedResult<TPayload>;
+
+/**
+ * Authenticated, versioned, JSON-safe evidence for one nonterminal invocation.
+ * Integrity does not make this evidence one-shot; the host's durable current
+ * suspension record is the replay and ownership fence. Hosts must capability-
+ * route each exact version during rolling deploys and drain or migrate current
+ * evidence before rotating away from its signing key.
+ */
+export interface EventActorSuspension<
+  TPayload extends EventActorEvent = EventActorEvent,
+> {
+  version: 1;
+  suspensionId: string;
+  attempt: number;
+  issuedAt: number;
+  expiresAt: number;
+  invocation: EventActorInvocationReference;
+  checkpoint: EventActorCheckpointFork;
+  interrupt: EventActorInterrupt<TPayload>;
+  suspensionDigest: string;
+}
+
+export interface EventActorSuspendedResult<
+  TPayload extends EventActorEvent = EventActorEvent,
+> {
+  status: 'suspended';
+  suspension: EventActorSuspension<TPayload>;
+}
+
+export interface EventActorSuspendRequest {
+  suspension: EventActorSuspension;
+  /** CAS predecessor required when a claimed resume pauses again. */
+  previous?: {
+    suspensionId: string;
+    attempt: number;
+    resumeAttemptId: string;
+  };
+}
+
+export type EventActorSuspendResult =
+  | { status: 'stored' }
+  | { status: 'stale' };
+
+export interface EventActorAdapterResumeRequest {
+  suspension: EventActorSuspension;
+  resumeAttemptId: string;
+  value: EventActorEvent;
+}
+
+export type EventActorAdapterResumeResult<TResult extends EventActorEvent> =
+  | {
+      status: 'claimed';
+      result: EventActorAdapterInvocationResult<TResult>;
+    }
+  | {
+      /** The host proved no action before returning this claimed failure. */
+      status: 'claimed_failed';
+      error: Error;
+    }
+  | { status: 'stale' };
+
+export interface EventActorResumeRequest {
+  suspension: EventActorSuspension;
+  resumeAttemptId: string;
+  value: EventActorEvent;
+  signal?: AbortSignal;
+}
+
+export interface EventActorCancelSuspensionRequest {
+  suspension: EventActorSuspension;
+  cancelAttemptId: string;
+  reason?: 'cancelled' | 'expired';
+  signal?: AbortSignal;
+}
+
+export interface EventActorAdapterCancelSuspensionRequest {
+  suspension: EventActorSuspension;
+  cancelAttemptId: string;
+  reason: 'cancelled' | 'expired';
+}
+
+export type EventActorCancelSuspensionResult =
+  | { status: 'cancelled' }
+  | EventActorIndeterminateResult<EventActorEvent>;
+
+export type EventActorAdapterCancelSuspensionResult =
+  | { status: 'cancelled' }
+  | { status: 'stale' };
+
+export interface EventActorSettleSuspensionRequest {
+  suspensionId: string;
+  attempt: number;
+  resumeAttemptId: string;
+  status: 'completed_no_action' | 'failed';
+}
+
+export type EventActorSettleSuspensionResult =
+  | { status: 'settled' }
+  | { status: 'stale' };
+
 export type EventActorAppliedResult<TResult extends EventActorEvent> = Extract<
   EventActorTerminalResult<TResult>,
   { status: 'applied' }
 > & {
-  /** Executor-issued one-shot settlement for the invocation that produced this action. */
+  /** Executor-issued settlement for the invocation that produced this action. */
   invocation: EventActorInvocationReference;
+  /** Authenticated cross-executor authority for a resumed terminal action. */
+  settlementAuthority?: EventActorSettlementAuthority;
 };
 
+/**
+ * Authenticated fence that binds a resumed terminal result to its claimed
+ * suspension. The host must consume it atomically with the actor-head CAS.
+ */
+export interface EventActorSettlementAuthority {
+  version: 1;
+  suspensionId: string;
+  attempt: number;
+  resumeAttemptId: string;
+  issuedAt: number;
+  expiresAt: number;
+  settlementDigest: string;
+}
+
 export interface EventActorIndeterminateResult<
   TResult extends EventActorEvent,
 > {
@@ -95,6 +237,7 @@ export interface EventActorIndeterminateResult<
 export type EventActorInvocationResult<TResult extends EventActorEvent> =
   | EventActorAppliedResult<TResult>
   | EventActorIndeterminateResult<TResult>
+  | EventActorSuspendedResult
   | Extract<
       EventActorTerminalResult<TResult>,
       { status: 'completed_no_action' }
@@ -128,6 +271,8 @@ export interface EventActorCommitRequest<TResult extends EventActorEvent> {
   expectedHead: EventActorHead;
   checkpoint: EventActorCheckpointFork;
   result: TResult;
+  /** Host must consume this suspension fence atomically with the head CAS. */
+  settlementAuthority?: EventActorSettlementAuthority;
   retention: {
     committedCheckpoints: 2;
     dormantCheckpointTtlMs: number;
@@ -156,7 +301,11 @@ export interface EventActorDiscardRequest {
 /**
  * Host adapter for durable actor state and the concrete agent invocation.
  * `commit` must compare both the expected generation and checkpoint identity
- * atomically before advancing the logical actor head. The host mailbox
+ * atomically before advancing the logical actor head. When settlement authority
+ * is present, that same transaction must also verify and close the exact
+ * suspension/resume-attempt fence, including stale-head outcomes. Retrying an
+ * ambiguous acknowledgement must return the durable outcome rather than apply
+ * the same terminal transition again. The host mailbox
  * deduplicates the logical `invocationId` before entering this seam, while each
  * SDK execution attempt receives a distinct checkpoint namespace. Preparation
  * methods own rollback until they return a ready invocation and must treat the
@@ -170,6 +319,18 @@ export interface EventActorDiscardRequest {
  * fork: the SDK retains and surfaces it as `commit_conflict` for host
  * reconciliation. `discard` must be idempotent for the same invocation because
  * an ambiguous cleanup failure can be retried through the public lifecycle.
+ *
+ * Suspension-capable hosts implement all optional suspension methods. `suspend`
+ * publishes an initial suspension only while its logical invocation is current;
+ * with `previous`, it atomically replaces only the exact claimed predecessor.
+ * `resume` atomically claims the current suspension before applying its value to
+ * the declared interrupt and rejects duplicate or competing claims as `stale`.
+ * It must return `claimed_failed` only when it can prove no qualifying action;
+ * any failure after an action returns `applied`. `settleSuspension` atomically
+ * discards the claimed fork and closes its fence for definite no-action
+ * outcomes. `cancelSuspension`
+ * atomically claims, discards, and closes current state, including expired
+ * evidence; expiration alone never implies a safe action outcome.
  */
 export interface EventActorHostAdapter<
   TEvent extends EventActorEvent,
@@ -187,7 +348,20 @@ export interface EventActorHostAdapter<
   invoke(
     invocation: EventActorInvocation<TEvent>,
     context: EventActorInvocationContext
-  ): Promise<EventActorTerminalResult<TResult>>;
+  ): Promise<EventActorAdapterInvocationResult<TResult>>;
+  suspend?(request: EventActorSuspendRequest): Promise<EventActorSuspendResult>;
+  resume?(
+    request: EventActorAdapterResumeRequest,
+    context: EventActorInvocationContext
+  ): Promise<EventActorAdapterResumeResult<TResult>>;
+  /** Atomically claims, discards, and closes the current suspension. */
+  cancelSuspension?(
+    request: EventActorAdapterCancelSuspensionRequest,
+    context: EventActorPreparationContext
+  ): Promise<EventActorAdapterCancelSuspensionResult>;
+  settleSuspension?(
+    request: EventActorSettleSuspensionRequest
+  ): Promise<EventActorSettleSuspensionResult>;
   commit(
     request: EventActorCommitRequest<TResult>
   ): Promise<EventActorCommitResult>;
@@ -219,6 +393,9 @@ export type EventActorExecutionResult<TResult extends EventActorEvent> =
       status: 'cancelled';
       continuation: 'warm' | 'cold';
     }
+  | (EventActorSuspendedResult & {
+      continuation: 'warm' | 'cold';
+    })
   | {
       /** The action happened, but another head won the CAS. Reconcile; do not retry. */
       status: 'commit_conflict';
@@ -247,4 +424,6 @@ export interface EventActorExecutorOptions {
   dormantCheckpointTtlMs?: number;
   /** Stable private key of at least 32 bytes for cross-lifetime handoffs. */
   preparationSigningKey?: string | Uint8Array;
+  /** Maximum UTF-8 byte size of canonical suspension evidence. */
+  maxSuspensionPayloadBytes?: number;
 }

package/src/graphs/Graph.ts

@@ -153,10 +153,10 @@ import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { createContextPressureMeter } from '@/llm/contextPressureMeter';
-import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
+import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { initializeLangfuseTracing } from '@/instrumentation';
@@ -164,6 +164,7 @@ import { shouldTriggerSummarization } from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
+import { getTruncationStopReason } from '@/llm/truncation';
 import { messagesStateReducer } from '@/messages/reducer';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
@@ -1425,6 +1426,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * hosts persist it as unfinished rather than complete.
    */
   preemptIncomplete = false;
+  /**
+   * True when `routeMessage` sent a turn to `END` because the last AI
+   * message carries no tool call, AND the provider reports it stopped for
+   * hitting the output token ceiling (`getTruncationStopReason`). Plain-text
+   * and reasoning turns cut off this way carry no tool call for
+   * `assertNotTruncatedToolCall` to catch, so `toolsCondition` reads them as
+   * an ordinary finished turn otherwise — hosts read this flag to persist
+   * the turn as unfinished instead of a silently truncated "complete" answer.
+   *
+   * Deliberately separate from `preemptIncomplete`/`preemptHaltReason`: this
+   * has no interaction with the preempt/seal machinery (in particular the
+   * `preemptHaltReason` check at each model node's entry), so setting it
+   * cannot suppress an unrelated agent's turn in a multi-agent graph.
+   */
+  outputTruncatedIncomplete = false;
   /**
    * `stopReason` from a `PreemptBoundary` hook that halted the turn.
    *
@@ -1702,6 +1718,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.preemptEmptyBoundaries = 0;
     this.preemptIncomplete = false;
     this.preemptHaltReason = undefined;
+    this.outputTruncatedIncomplete = false;
   }
 
   /**
@@ -2801,9 +2818,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       provider,
       clientOptions,
       tools,
-      isDeferred: makeIsDeferred(
-        agentContext.getEffectiveToolDefinitions()
-      ),
+      isDeferred: makeIsDeferred(agentContext.getEffectiveToolDefinitions()),
     });
   }
 
@@ -3030,9 +3045,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           messagesToRefine.length > 0;
 
         if (hasPrunedMessages) {
-          const shouldSkip = agentContext.shouldSkipSummarization(
-            messages.length
-          );
+          const shouldSkip =
+            agentContext.summarizationExhausted ||
+            agentContext.shouldSkipSummarization(messages.length);
           const triggerResult =
             !shouldSkip &&
             shouldTriggerSummarization({
@@ -3089,6 +3104,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 messageCount: messages.length,
                 messagesToRefineCount: messagesToRefine.length,
                 contextLength: context.length,
+                summarizationFailures: agentContext.summarizationFailures,
+                summarizationExhausted: agentContext.summarizationExhausted,
               },
               { runId: this.runId, agentId }
             );
@@ -4818,11 +4835,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (state.summarizationRequest != null) {
         return summarizeNode;
       }
-      return toolsCondition(
+      const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,
         this.invokedToolIds
       );
+      /**
+       * `toolsCondition` only looks at `tool_calls` — a plain-text/reasoning
+       * turn cut off by the output token ceiling has none, so it reads as an
+       * ordinary finished turn and routes here to END. Flag it so hosts can
+       * tell a genuinely finished answer from one the model never got to
+       * complete. See `outputTruncatedIncomplete` for why this stays clear
+       * of the preempt/seal halt fields.
+       */
+      if (decision === END) {
+        const { messages } = state as t.BaseGraphState;
+        const lastMessage = messages[messages.length - 1];
+        if (getTruncationStopReason(lastMessage) != null) {
+          this.outputTruncatedIncomplete = true;
+        }
+      }
+      return decision;
     };
 
     const StateAnnotation = Annotation.Root({

package/src/langfuseTraceShaping.ts

@@ -35,6 +35,11 @@ const DEPRECATED_TRACE_INPUT_ATTRIBUTE = 'langfuse.trace.input';
 const DEPRECATED_TRACE_OUTPUT_ATTRIBUTE = 'langfuse.trace.output';
 const OBSERVATION_METADATA_LANGGRAPH_NODE = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`;
 const OBSERVATION_METADATA_OPERATION = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.${LANGFUSE_OPERATION_METADATA_KEY}`;
+const OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.compaction_semantic_index_entries`;
+const COMPACTION_SEMANTIC_INDEX_OPEN = '<compaction-semantic-index>';
+const COMPACTION_SEMANTIC_INDEX_CLOSE = '</compaction-semantic-index>';
+const REDACTED_COMPACTION_SEMANTIC_INDEX =
+  '<compaction-semantic-index redacted="true" />\n\n';
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -66,6 +71,94 @@ function parseAttributeValue(value: unknown): unknown {
   }
 }
 
+type CompactionSemanticIndexRedaction = {
+  value: unknown;
+  redacted: boolean;
+};
+
+function redactCompactionSemanticIndexText(
+  value: string
+): CompactionSemanticIndexRedaction {
+  if (!value.startsWith(COMPACTION_SEMANTIC_INDEX_OPEN)) {
+    return { value, redacted: false };
+  }
+  const start = 0;
+  const close = value.indexOf(COMPACTION_SEMANTIC_INDEX_CLOSE, start);
+  if (close < 0) {
+    return { value, redacted: false };
+  }
+  let end = close + COMPACTION_SEMANTIC_INDEX_CLOSE.length;
+  while (end < value.length && /\s/.test(value[end])) {
+    end++;
+  }
+  return {
+    value:
+      value.slice(0, start) +
+      REDACTED_COMPACTION_SEMANTIC_INDEX +
+      value.slice(end),
+    redacted: true,
+  };
+}
+
+function redactCompactionSemanticIndexValue(
+  value: unknown
+): CompactionSemanticIndexRedaction {
+  if (typeof value === 'string') {
+    return redactCompactionSemanticIndexText(value);
+  }
+  if (Array.isArray(value)) {
+    for (let index = value.length - 1; index >= 0; index--) {
+      const nested = redactCompactionSemanticIndexValue(value[index]);
+      if (nested.redacted) {
+        const result = [...value];
+        result[index] = nested.value;
+        return { value: result, redacted: true };
+      }
+    }
+    return { value, redacted: false };
+  }
+  if (!isRecord(value)) {
+    return { value, redacted: false };
+  }
+  const entries = Object.entries(value);
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const [key, nestedValue] = entries[index];
+    const nested = redactCompactionSemanticIndexValue(nestedValue);
+    if (nested.redacted) {
+      return {
+        value: { ...value, [key]: nested.value },
+        redacted: true,
+      };
+    }
+  }
+  return { value, redacted: false };
+}
+
+function redactCompactionSemanticIndexInput(span: MutableSpan): void {
+  const entryCount =
+    span.attributes[
+      OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES
+    ];
+  const numericEntryCount = Number(entryCount);
+  if (!Number.isFinite(numericEntryCount) || numericEntryCount <= 0) {
+    return;
+  }
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const input = span.attributes[inputKey];
+  if (input == null) {
+    return;
+  }
+  const parsed = parseAttributeValue(input);
+  const redaction = redactCompactionSemanticIndexValue(parsed);
+  if (!redaction.redacted) {
+    return;
+  }
+  span.attributes[inputKey] =
+    typeof redaction.value === 'string' && parsed === input
+      ? redaction.value
+      : JSON.stringify(redaction.value);
+}
+
 function getMessageArray(
   value: unknown
 ): Record<string, unknown>[] | undefined {
@@ -594,6 +687,7 @@ export function shapeLangfuseSpan(span: ReadableSpan): void {
   const mutable = span as MutableSpan;
   delete mutable.attributes[DEPRECATED_TRACE_INPUT_ATTRIBUTE];
   delete mutable.attributes[DEPRECATED_TRACE_OUTPUT_ATTRIBUTE];
+  redactCompactionSemanticIndexInput(mutable);
   const isGraphObservation = isGraphSpan(mutable);
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
     shapeAgentNodeSpan(mutable);

package/src/llm/fake.ts

@@ -14,6 +14,15 @@ export class FakeChatModel extends FakeListChatModel {
   private splitStrategy: SplitStrategy;
   private toolCalls: ToolCall[] = [];
   private addedToolCalls: boolean = false;
+  /**
+   * Attached to the last streamed chunk of every response, mirroring a real
+   * provider's terminal `finish_reason`/`stop_reason` on `generationInfo`.
+   * Lets truncation-path tests (`getTruncationStopReason`) drive a genuine
+   * `Run`/`StandardGraph` without a live provider. `undefined` (the
+   * default) reproduces the previous behavior exactly: no metadata on any
+   * chunk.
+   */
+  private finalChunkGenerationInfo?: Record<string, unknown>;
 
   constructor({
     responses,
@@ -21,16 +30,19 @@ export class FakeChatModel extends FakeListChatModel {
     emitCustomEvent,
     splitStrategy = { type: 'regex', value: /(?<=\s+)|(?=\s+)/ },
     toolCalls = [],
+    finalChunkGenerationInfo,
   }: {
     responses: string[];
     sleep?: number;
     emitCustomEvent?: boolean;
     splitStrategy?: SplitStrategy;
     toolCalls?: ToolCall[];
+    finalChunkGenerationInfo?: Record<string, unknown>;
   }) {
     super({ responses, sleep, emitCustomEvent });
     this.splitStrategy = splitStrategy;
     this.toolCalls = toolCalls;
+    this.finalChunkGenerationInfo = finalChunkGenerationInfo;
   }
 
   private splitText(text: string): string[] {
@@ -47,14 +59,16 @@ export class FakeChatModel extends FakeListChatModel {
   }
   _createResponseChunk(
     text: string,
-    tool_call_chunks?: ToolCallChunk[]
+    tool_call_chunks?: ToolCallChunk[],
+    responseMetadata?: Record<string, unknown>
   ): ChatGenerationChunk {
     return new ChatGenerationChunk({
       text,
-      generationInfo: {},
+      generationInfo: responseMetadata ?? {},
       message: new AIMessageChunk({
         content: text,
         tool_call_chunks,
+        response_metadata: responseMetadata,
         additional_kwargs: tool_call_chunks
           ? {
             tool_calls: tool_call_chunks.map((toolCall) => ({
@@ -87,14 +101,31 @@ export class FakeChatModel extends FakeListChatModel {
     }
 
     const chunks = this.splitText(response);
-    for await (const chunk of chunks) {
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
       await this._sleepIfRequested();
 
       if (options.thrownErrorString != null && options.thrownErrorString) {
         throw new Error(options.thrownErrorString);
       }
 
-      const responseChunk = super._createResponseChunk(chunk);
+      /**
+       * Only the true terminal chunk of the response gets the metadata: when
+       * this response also appends a trailing tool-call chunk below, THAT
+       * chunk is terminal instead (not currently exercised by any test —
+       * a caller wanting truncated-tool-call metadata should attach it
+       * there).
+       */
+      const isTerminalChunk =
+        i === chunks.length - 1 && this.toolCalls.length === 0;
+      const responseChunk =
+        isTerminalChunk && this.finalChunkGenerationInfo != null
+          ? this._createResponseChunk(
+            chunk,
+            undefined,
+            this.finalChunkGenerationInfo
+          )
+          : super._createResponseChunk(chunk);
       yield responseChunk;
       void runManager?.handleLLMNewToken(chunk);
     }