@librechat/agents 3.7.7 → 3.7.9

package/src/summarization/shared.ts

@@ -0,0 +1,130 @@
+/**
+ * Summarization primitives shared by the in-run summarize node and by callers
+ * that compact a conversation outside a run. Kept apart from `node.ts` so the
+ * package can export them without exporting the graph node itself.
+ */
+
+/**
+ * Instruction that follows the summary body inside the carrier. Private on
+ * purpose: it is only ever correct alongside `buildSummaryCarrierText`, and a
+ * caller that reaches for the text separately is a caller that can drift from
+ * the accounting.
+ */
+const SUMMARY_CARRIER_INSTRUCTION =
+  'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+
+/**
+ * Wraps a persisted summary in the carrier it is re-injected as, ahead of the
+ * messages that survived compaction.
+ *
+ * A stored summary costs what this returns, not what its body costs, so a
+ * caller budgeting for one measures this rather than adding a remembered
+ * constant to the bare text. The wrapper alone is ~48 tokens on `o200k_base`
+ * and more on Anthropic: too much to leave out of a context calculation, and
+ * too easy to get wrong from memory once the instruction is edited.
+ */
+export function buildSummaryCarrierText(summaryText: string): string {
+  return (
+    '<summary>\n' +
+    summaryText +
+    '\n</summary>\n\n' +
+    SUMMARY_CARRIER_INSTRUCTION
+  );
+}
+
+/** Structured checkpoint prompt for fresh summarization (no prior summary). */
+export const DEFAULT_SUMMARIZATION_PROMPT = `Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.
+
+Don't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.
+
+## Checkpoint
+
+## Goal
+What I asked you to do and any sub-goals you identified.
+
+## Constraints & Preferences
+Any rules, preferences, or configuration I established.
+
+## Progress
+### Done
+- What you completed and the outcomes
+
+### In Progress
+- What you're currently working on
+
+## Key Decisions
+Decisions you made and why.
+
+## Next Steps
+Concrete task actions remaining, in priority order.
+
+## Critical Context
+Exact identifiers, names, error messages, URLs, and details you need to preserve verbatim.
+
+Rules:
+- Record what you did and observed, don't judge or re-evaluate it
+- For each tool call: the tool name, key inputs, and the outcome
+- Preserve exact identifiers, names, errors, and references verbatim
+- Short declarative sentences
+- Skip empty sections`;
+
+/** Prompt for re-compaction when a prior summary exists. */
+export const DEFAULT_UPDATE_SUMMARIZATION_PROMPT = `Hold on again, update your checkpoint. Merge the new messages into your existing checkpoint and give me a single consolidated replacement.
+
+Keep it roughly the same length as your last checkpoint. Compress older details to make room for what's new, don't just append. Give recent actions more detail, compress older items to one-liners.
+
+Don't fact-check or second-guess anything, your tool results are ground truth. If a tool result appears truncated, that's just a display artifact: the tool executed fully. Only the checkpoint, don't respond to me or continue the conversation.
+
+Rules:
+- Merge new progress into existing sections, don't duplicate headers
+- Compress older completed items into one-line entries
+- Move items from "In Progress" to "Done" when you completed them
+- Update "Next Steps" to reflect current task priorities.
+- For each new tool call: the tool name, key inputs, and the outcome
+- Preserve exact identifiers, names, errors, and references verbatim
+- Skip empty sections`;
+
+const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
+
+export function separateSummarizationParameters(
+  parameters: Record<string, unknown>
+): {
+  llmParams: Record<string, unknown>;
+  maxSummaryTokens?: number;
+} {
+  const llmParams: Record<string, unknown> = {};
+  let maxSummaryTokens: number | undefined;
+
+  for (const [key, value] of Object.entries(parameters)) {
+    if (SUMMARIZATION_PARAM_KEYS.has(key)) {
+      if (
+        key === 'maxSummaryTokens' &&
+        typeof value === 'number' &&
+        value > 0
+      ) {
+        maxSummaryTokens = value;
+      }
+    } else {
+      llmParams[key] = value;
+    }
+  }
+
+  return { llmParams, maxSummaryTokens };
+}
+
+export function buildSummarizationInstruction(
+  promptText: string,
+  updatePromptText: string | undefined,
+  priorSummaryText?: string,
+  semanticIndexAppendix = ''
+): string {
+  const prior = priorSummaryText?.trim() ?? '';
+  const effectivePrompt = prior ? (updatePromptText ?? promptText) : promptText;
+  const parts = semanticIndexAppendix
+    ? [semanticIndexAppendix, '\n\n', effectivePrompt]
+    : [effectivePrompt];
+  if (prior) {
+    parts.push(`\n\n<previous-summary>\n${prior}\n</previous-summary>`);
+  }
+  return parts.join('');
+}

package/src/tools/runStepResume.ts

@@ -23,6 +23,15 @@ export function isRunStepResumeState(
     (state.revision ?? -1) < 0 ||
     !Number.isSafeInteger(state.nextIndex) ||
     (state.nextIndex ?? -1) < 0 ||
+    (state.stopContinuationCount != null &&
+      (!Number.isSafeInteger(state.stopContinuationCount) ||
+        state.stopContinuationCount < 0)) ||
+    (state.stopContinuationExecutionId != null &&
+      (typeof state.stopContinuationExecutionId !== 'string' ||
+        state.stopContinuationExecutionId.length === 0)) ||
+    (state.streamSegment != null &&
+      (!Number.isSafeInteger(state.streamSegment) ||
+        state.streamSegment < 0)) ||
     !Array.isArray(state.toolCallSteps) ||
     !Array.isArray(state.steps)
   ) {

package/src/tools/subagent/SubagentExecutor.ts

@@ -131,6 +131,7 @@ import { stripRunStepResumeState } from '@/tools/runStepResume';
 import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
 import { convertInjectedMessages } from '@/messages/injected';
+import { resolveClientOptionsModel } from '@/llm/request';
 import { composeAbortSignals } from '@/utils/misc';
 import { HandlerRegistry } from '@/events';
 
@@ -1091,8 +1092,7 @@ export class SubagentExecutor {
       return JSON.stringify({
         status: 'rejected',
         tool: Constants.SUBAGENT,
-        message:
-          'Child-thread continuation is not enabled by this host.',
+        message: 'Child-thread continuation is not enabled by this host.',
       });
     }
     const detachedHandlers = new HandlerRegistry();
@@ -2261,9 +2261,7 @@ export class SubagentExecutor {
     }
     if (this.maxDepth <= 0) {
       return Promise.resolve(
-        createSubagentFailure(
-          'Error: Maximum subagent nesting depth exceeded.'
-        )
+        createSubagentFailure('Error: Maximum subagent nesting depth exceeded.')
       );
     }
     if (
@@ -3300,7 +3298,7 @@ function createUsageCaptureHandler(args: {
         defaultMember?.[1];
       const model =
         callInfo?.model ??
-        (memberInput == null ? undefined : extractConfiguredModel(memberInput));
+        resolveClientOptionsModel(memberInput?.clientOptions);
       const callProvider = callInfo?.provider ?? memberInput?.provider;
       for (const generationGroup of output.generations) {
         /**
@@ -3423,27 +3421,6 @@ function getGraphEventMemberAgentId({
     : undefined;
 }
 
-/**
- * Best-effort read of the configured model from a subagent's client
- * options. Providers disagree on the key (`model` vs `modelName`), and the
- * value is only a fallback for calls that carry no `ls_model_name`.
- */
-function extractConfiguredModel(agentInputs: AgentInputs): string | undefined {
-  const clientOptions = agentInputs.clientOptions as
-    | { model?: unknown; modelName?: unknown }
-    | undefined;
-  if (typeof clientOptions?.model === 'string' && clientOptions.model !== '') {
-    return clientOptions.model;
-  }
-  if (
-    typeof clientOptions?.modelName === 'string' &&
-    clientOptions.modelName !== ''
-  ) {
-    return clientOptions.modelName;
-  }
-  return undefined;
-}
-
 function sanitizeResolverConfigurable(
   parentConfigurable: Record<string, unknown>
 ): SubagentResolveConfigurable | undefined {

package/src/tools/subagent/childGraphConfig.ts

@@ -600,6 +600,9 @@ function prepareChildInputs({
     initialSummary: undefined,
     discoveredTools: undefined,
     graphTools: self ? undefined : agentInputs.graphTools,
+    compactionSemanticIndex: self
+      ? undefined
+      : agentInputs.compactionSemanticIndex,
   };
   if (allowNested) {
     childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);

package/src/types/graph.ts

@@ -13,6 +13,7 @@ import type { GoogleAIToolType } from '@langchain/google-common';
 import type {
   SummarizationNodeInput,
   SummarizeCompleteEvent,
+  CompactionSemanticIndex,
   SummarizationConfig,
   SummarizeStartEvent,
   SummarizeDeltaEvent,
@@ -871,6 +872,14 @@ interface AgentInputFields {
   discoveredTools?: string[];
   summarizationEnabled?: boolean;
   summarizationConfig?: SummarizationConfig;
+  /**
+   * Optional host-supplied, user-visible guidance for compaction. The SDK
+   * validates, bounds, and scopes entries to the messages being compacted;
+   * raw conversation messages remain authoritative. Captured when the
+   * AgentContext is constructed; labels committed later in the same run are
+   * outside this construction-time interface.
+   */
+  compactionSemanticIndex?: CompactionSemanticIndex;
   /** Cross-run summary from a previous run, forwarded from formatAgentMessages.
    *  Injected into the dynamic system tail via AgentContext. */
   initialSummary?: { text: string; tokenCount: number };

package/src/types/run.ts

@@ -252,6 +252,14 @@ export type RunConfig = {
    * block to prevent leaks.
    */
   hooks?: HookRegistry;
+  /**
+   * Maximum number of times a `Stop` hook may keep this Run warm by returning
+   * `decision: 'block'` with messages to inject. Defaults to
+   * `DEFAULT_MAX_STOP_CONTINUATIONS`; non-finite values use the default and
+   * values at or below zero disable terminal continuation while preserving the
+   * final Stop notification.
+   */
+  maxStopContinuations?: number;
   /**
    * Opt-in cooperative preemption for this run. Requires a `hooks` registry
    * with a `PreemptBoundary` matcher — the seal only stops the stream, the

package/src/types/stream.ts

@@ -116,6 +116,12 @@ export interface RunStepResumeState {
   version: 1;
   revision: number;
   nextIndex: number;
+  /** Warm terminal continuations already admitted for this execution. */
+  stopContinuationCount?: number;
+  /** Identifies the fresh execution that owns this continuation lifecycle. */
+  stopContinuationExecutionId?: string;
+  /** Distinguishes LangGraph event keys when a warm continuation restarts steps. */
+  streamSegment?: number;
   toolCallSteps: Array<{ toolCallId: string; stepId: string }>;
   steps: RunStepResumeEntry[];
 }

package/src/types/summarize.ts

@@ -36,6 +36,59 @@ export type RetainRecentConfig = {
   tokens?: number;
 };
 
+export type CompactionSemanticIndexStatus = 'committed' | 'pending';
+
+type CompactionSemanticIndexEntryBase = {
+  /** Persisted message that owns the indexed content. */
+  sourceMessageId: string;
+  /** Zero-based content-part index within the persisted source message. */
+  sourceContentIndex: number;
+  /** Monotonic host revision for this logical entry. */
+  revision: number;
+  /** Only committed entries may guide compaction. */
+  status: CompactionSemanticIndexStatus;
+  /** User-visible semantic guidance. Hidden reasoning must never be supplied. */
+  text: string;
+  /** Omits the entry entirely when host policy redacts its source. */
+  redacted?: boolean;
+};
+
+export type CompactionToolSemanticIndexEntry =
+  CompactionSemanticIndexEntryBase & {
+    type: 'tool_intent' | 'tool_outcome';
+    toolCallId: string;
+  };
+
+export type CompactionActivitySemanticIndexEntry =
+  CompactionSemanticIndexEntryBase & {
+    type: 'activity_phase';
+  };
+
+export type CompactionReasoningSemanticIndexEntry =
+  CompactionSemanticIndexEntryBase & {
+    type: 'reasoning_label';
+    /** Stable identity shared by every user-visible label revision. */
+    reasoningStepId: string;
+  };
+
+/**
+ * Source-addressed navigation hints for the compaction model. Entries remain
+ * advisory: raw messages are always sent and remain authoritative.
+ */
+export type CompactionSemanticIndexEntry =
+  | CompactionToolSemanticIndexEntry
+  | CompactionActivitySemanticIndexEntry
+  | CompactionReasoningSemanticIndexEntry;
+
+export type CompactionSemanticIndex = readonly CompactionSemanticIndexEntry[];
+
+/** Serializable continuation state for a bounded compaction semantic index. */
+export type CompactionSemanticIndexSnapshot = {
+  entries: CompactionSemanticIndex;
+  /** Cumulative entries supplied before validation and bounded retention. */
+  providedEntryCount: number;
+};
+
 export type SummarizationConfig = {
   provider?: ProviderName;
   model?: string;
@@ -96,6 +149,10 @@ export interface SummarizeStartEvent {
   messagesToRefineCount: number;
   /** Which summarization cycle this is (1-based, increments each time summarization fires) */
   summaryVersion: number;
+  /** Committed, source-valid semantic hints included in the request. */
+  semanticIndexEntryCount?: number;
+  /** Serialized semantic-index characters included in the request. */
+  semanticIndexCharCount?: number;
 }
 
 export interface SummarizeDeltaEvent {

package/src/utils/tokens.ts

@@ -6,8 +6,8 @@ import {
   isAtomicToolContentBlock,
   serializeStructuredValueBounded,
 } from './toolContent';
-import { ContentTypes } from '@/common/enum';
 import { markTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
+import { ContentTypes } from '@/common/enum';
 
 export type EncodingName = 'o200k_base' | 'claude';
 
@@ -1257,6 +1257,25 @@ export function apportionTokenCounts(
  */
 const CLAUDE_TOKEN_CORRECTION = 1.1;
 
+const tokenCounterEncodings = new WeakMap<
+  (message: BaseMessage) => number,
+  EncodingName
+>();
+
+/**
+ * Encoding a counter measures in, for counters built here.
+ *
+ * `undefined` for a counter the host supplied itself: unknown, not wrong. A
+ * caller that needs a count in a specific encoding can therefore tell "counts
+ * in the encoding I need" from "counts in a different one" without treating
+ * every foreign counter as suspect.
+ */
+export function encodingOfTokenCounter(
+  tokenCounter: (message: BaseMessage) => number
+): EncodingName | undefined {
+  return tokenCounterEncodings.get(tokenCounter);
+}
+
 /**
  * Creates a token counter function using the specified encoding.
  * Lazily loads the encoding data on first use via dynamic import.
@@ -1267,13 +1286,17 @@ export const createTokenCounter = async (
   const tok = await getTokenizer(encoding);
   const countTokens = (text: string): number => tok.count(text);
   const isClaude = encoding === 'claude';
-  return markTokenCounterCacheCompatible((message: BaseMessage): number => {
-    const count = getTokenCountForMessage(message, countTokens, encoding);
-    const correctedCount = isClaude
-      ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION)
-      : count;
-    return ensureSafeTokenMeasurement(correctedCount, 'message');
-  });
+  const counter = markTokenCounterCacheCompatible(
+    (message: BaseMessage): number => {
+      const count = getTokenCountForMessage(message, countTokens, encoding);
+      const correctedCount = isClaude
+        ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION)
+        : count;
+      return ensureSafeTokenMeasurement(correctedCount, 'message');
+    }
+  );
+  tokenCounterEncodings.set(counter, encoding);
+  return counter;
 };
 
 /** Utility to manage the token encoder lifecycle explicitly. */