@librechat/agents 3.7.0 → 3.7.1

package/src/summarization/node.ts

@@ -29,6 +29,7 @@ import {
 } from '@/messages/cache';
 import {
   DEFAULT_RETAIN_RECENT_TURNS,
+  resolveIntraTurnRetainTokens,
   splitAtRecencyBoundary,
 } from '@/messages/recency';
 import {
@@ -1091,14 +1092,22 @@ export function createSummarizeNode({
     const runnableConfig = config ?? graph.config;
 
     const retainRecent = agentContext.summarizationConfig?.retainRecent;
-    const { head: messagesToRefine, tailStartIndex } = splitAtRecencyBoundary(
-      restoredMessages,
-      {
-        turns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+    const recencyTokenCounter =
+      agentContext.contextPressureTokenCounts?.count ??
+      agentContext.tokenCounter;
+    const {
+      head: messagesToRefine,
+      tailStartIndex,
+      usedIntraTurnFallback,
+    } = splitAtRecencyBoundary(restoredMessages, {
+      turns: retainRecent?.turns ?? DEFAULT_RETAIN_RECENT_TURNS,
+      tokens: retainRecent?.tokens,
+      tokenCounter: recencyTokenCounter,
+      intraTurnTokens: resolveIntraTurnRetainTokens({
         tokens: retainRecent?.tokens,
-        tokenCounter: agentContext.tokenCounter,
-      }
-    );
+        maxContextTokens: agentContext.maxContextTokens,
+      }),
+    });
     /**
      * Use the *masked* messages for the retained tail so that any
      * truncation prune applied to oversized ToolMessage content stays
@@ -1305,10 +1314,17 @@ export function createSummarizeNode({
      * supposed to preserve. Leave state untouched and let the provider error
      * surface instead.
      */
-    if (usedMetadataStub === true && request.reason === 'overflow') {
+    if (
+      usedMetadataStub === true &&
+      (request.reason === 'overflow' || usedIntraTurnFallback)
+    ) {
+      const preservationReason =
+        request.reason === 'overflow'
+          ? 'overflow recovery'
+          : 'intra-turn compaction';
       log(
         'warn',
-        'Overflow summarization failed; keeping history rather than replacing it with a metadata stub'
+        `Summarization failed during ${preservationReason}; keeping history rather than replacing it with a metadata stub`
       );
       agentContext.markSummarizationTriggered(state.messages.length);
       /**
@@ -1330,8 +1346,7 @@ export function createSummarizeNode({
           {
             id: stepId,
             agentId: request.agentId,
-            error:
-              'Summarization failed during overflow recovery; conversation history was preserved',
+            error: `Summarization failed during ${preservationReason}; conversation history was preserved`,
           } satisfies t.SummarizeCompleteEvent,
           runnableConfig
         );
@@ -1364,7 +1379,13 @@ export function createSummarizeNode({
       agentContext.tokenCounter
     );
 
-    agentContext.setSummary(summaryText, tokenCount);
+    if (usedIntraTurnFallback) {
+      agentContext.setSummary(summaryText, tokenCount, {
+        precedesMessages: true,
+      });
+    } else {
+      agentContext.setSummary(summaryText, tokenCount);
+    }
 
     log('info', 'Summary persisted');
     log('debug', 'Summary details', {
@@ -1596,9 +1617,10 @@ function traceConfig(
 
 /**
  * Cache-friendly compaction: sends raw conversation messages with the
- * summarization instruction appended as the final HumanMessage.
- * Providers with prompt caching get a cache hit on the system prompt +
- * tool definitions prefix.
+ * summarization instruction appended as the final HumanMessage. Bound tool
+ * definitions can reuse their cache prefix. Exact replay of the main request's
+ * system + tools + messages prefix requires a routed-request projection that
+ * this summarization path does not currently own.
  */
 async function summarizeWithCacheHit({
   model,

package/src/tools/subagent/InMemorySubagentTaskStore.ts

@@ -4,6 +4,7 @@ import type {
   SubagentTaskBoundary,
   SubagentTaskClaim,
   SubagentTaskControlCommand,
+  SubagentTaskControlReceipt,
   SubagentTaskControlResult,
   SubagentTaskProgress,
   SubagentTaskRuntime,
@@ -20,6 +21,7 @@ const DEFAULT_MAX_ERROR_CHARS = 4 * 1024;
 const DEFAULT_MAX_MESSAGE_CHARS = 64 * 1024;
 const DEFAULT_TASK_TIMEOUT_MS = 30 * 60 * 1000;
 const DEFAULT_MAX_CONTROLS = 32;
+const DEFAULT_MAX_CONTROL_RECEIPTS = 64;
 const DEFAULT_MAX_RESULT_CHARS = 100_000;
 const DEFAULT_MAX_RUNNING_PER_SCOPE = 10;
 const DEFAULT_MAX_RUNNING_TOTAL = 100;
@@ -30,6 +32,7 @@ export interface InMemorySubagentTaskStoreOptions {
   completedTtlMs?: number;
   maxControlMessageChars?: number;
   maxControlsPerTask?: number;
+  maxControlReceiptsPerTask?: number;
   maxErrorChars?: number;
   maxResultChars?: number;
   maxRunningPerScope?: number;
@@ -57,6 +60,7 @@ type StoredTask = {
   updatedAt: number;
   controller: AbortController;
   controls: PendingControl[];
+  controlReceipts: Map<string, SubagentTaskControlReceipt>;
   progressEvents: number;
   resultClaimed: boolean;
   acceptingControls: boolean;
@@ -107,6 +111,13 @@ function resolveOptions(
       options.maxControlsPerTask,
       DEFAULT_MAX_CONTROLS
     ),
+    maxControlReceiptsPerTask: Math.max(
+      resolvePositiveInteger(
+        options.maxControlReceiptsPerTask,
+        DEFAULT_MAX_CONTROL_RECEIPTS
+      ),
+      resolvePositiveInteger(options.maxControlsPerTask, DEFAULT_MAX_CONTROLS)
+    ),
     maxErrorChars: resolvePositiveInteger(
       options.maxErrorChars,
       DEFAULT_MAX_ERROR_CHARS
@@ -177,11 +188,20 @@ function snapshot(task: StoredTask): SubagentTaskSnapshot {
       task.status === 'completed' && task.result != null && !task.resultClaimed,
     resultClaimed: task.resultClaimed,
     pendingControls: task.controls.length,
+    controlReceipts: [...task.controlReceipts.values()].map((receipt) => ({
+      ...receipt,
+    })),
     ...(task.progress == null ? {} : { progress: { ...task.progress } }),
     ...(task.error == null ? {} : { error: task.error }),
   };
 }
 
+function cloneControlReceipt(
+  receipt: SubagentTaskControlReceipt
+): SubagentTaskControlReceipt {
+  return { ...receipt };
+}
+
 function abortReason(signal: AbortSignal): Error {
   return signal.reason instanceof Error
     ? signal.reason
@@ -206,6 +226,34 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
     this.options = resolveOptions(options);
   }
 
+  /**
+   * Payload-free transition seam for hosts that durably project authoritative
+   * receipts. Implementations must return synchronously, must not reproduce
+   * task-store transition rules, and cannot veto task-store state transitions:
+   * hook failures are deliberately isolated by the caller.
+   */
+  protected onControlReceipt(
+    _scopeId: string,
+    _taskId: string,
+    _receipt: SubagentTaskControlReceipt
+  ): void {}
+
+  private emitControlReceipt(
+    task: StoredTask,
+    receipt: SubagentTaskControlReceipt
+  ): void {
+    try {
+      this.onControlReceipt(
+        task.scopeId,
+        task.id,
+        cloneControlReceipt(receipt)
+      );
+    } catch {
+      // A host projection is observability only. Task admission, draining, and
+      // settlement must remain correct when that projection is unavailable.
+    }
+  }
+
   start(request: SubagentTaskStartRequest): SubagentTaskStartResult {
     const scopeId = request.scopeId.trim();
     const idempotencyKey = request.idempotencyKey.trim();
@@ -272,6 +320,7 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
       updatedAt: now,
       controller: new AbortController(),
       controls: [],
+      controlReceipts: new Map(),
       progressEvents: 0,
       resultClaimed: false,
       acceptingControls: true,
@@ -312,6 +361,7 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
           }
           task.status = 'completed';
           task.acceptingControls = false;
+          this.failPendingControls(task, 'task_completed');
           task.controls.length = 0;
           task.result = truncateMiddle(
             result.content,
@@ -399,9 +449,16 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
       if (index < 0) {
         return { status: 'control_not_found', task: snapshot(task) };
       }
-      task.controls.splice(index, 1);
+      const [control] = task.controls.splice(index, 1);
       task.updatedAt = Date.now();
-      return { status: 'accepted', task: snapshot(task) };
+      this.transitionControl(task, control.id, 'rejected', {
+        reason: 'withdrawn',
+      });
+      return {
+        status: 'accepted',
+        task: snapshot(task),
+        controlId: control.id,
+      };
     }
     const message = command.message.trim();
     if (message === '') {
@@ -419,6 +476,12 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
         message: `Task already has ${this.options.maxControlsPerTask} pending messages.`,
       };
     }
+    if (!this.makeRoomForControlReceipt(task)) {
+      return {
+        status: 'invalid',
+        message: 'Task control receipt capacity is unavailable.',
+      };
+    }
     const control: PendingControl = {
       id: nanoid(),
       action: command.action,
@@ -426,6 +489,15 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
     };
     task.controls.push(control);
     task.updatedAt = Date.now();
+    const receipt: SubagentTaskControlReceipt = {
+      controlId: control.id,
+      action: control.action,
+      status: 'accepted',
+      createdAt: task.updatedAt,
+      updatedAt: task.updatedAt,
+    };
+    task.controlReceipts.set(control.id, receipt);
+    this.emitControlReceipt(task, receipt);
     return {
       status: 'accepted',
       task: snapshot(task),
@@ -525,6 +597,59 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
     }
   }
 
+  private makeRoomForControlReceipt(task: StoredTask): boolean {
+    while (
+      task.controlReceipts.size >= this.options.maxControlReceiptsPerTask
+    ) {
+      const terminal = [...task.controlReceipts].find(
+        ([, receipt]) => receipt.status !== 'accepted'
+      );
+      if (terminal == null) {
+        return false;
+      }
+      task.controlReceipts.delete(terminal[0]);
+    }
+    return true;
+  }
+
+  private transitionControl(
+    task: StoredTask,
+    controlId: string,
+    status: Exclude<SubagentTaskControlReceipt['status'], 'accepted'>,
+    detail: Pick<SubagentTaskControlReceipt, 'boundary' | 'reason'> = {}
+  ): void {
+    const receipt = task.controlReceipts.get(controlId);
+    if (receipt == null || receipt.status !== 'accepted') {
+      return;
+    }
+    const transitioned: SubagentTaskControlReceipt = {
+      ...receipt,
+      status,
+      updatedAt: Date.now(),
+      ...(detail.boundary == null ? {} : { boundary: detail.boundary }),
+      ...(detail.reason == null ? {} : { reason: detail.reason }),
+    };
+    task.controlReceipts.set(controlId, transitioned);
+    this.emitControlReceipt(task, transitioned);
+  }
+
+  private failPendingControls(
+    task: StoredTask,
+    reason: Extract<
+      NonNullable<SubagentTaskControlReceipt['reason']>,
+      'task_completed' | 'task_cancelled' | 'task_failed'
+    >
+  ): void {
+    for (const control of task.controls) {
+      this.transitionControl(
+        task,
+        control.id,
+        reason === 'task_failed' ? 'failed' : 'rejected',
+        { reason }
+      );
+    }
+  }
+
   private scheduleExpiry(task: StoredTask): void {
     this.clearTaskTimeout(task);
     this.clearTaskExpiry(task);
@@ -566,6 +691,10 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
     task.status = status;
     this.runningTasks -= 1;
     task.acceptingControls = false;
+    this.failPendingControls(
+      task,
+      status === 'cancelled' ? 'task_cancelled' : 'task_failed'
+    );
     task.controls.length = 0;
     task.error = message;
     task.updatedAt = Date.now();
@@ -575,6 +704,7 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
 
   private createRuntime(task: StoredTask): SubagentTaskRuntime {
     const take = (
+      boundary: SubagentTaskBoundary,
       accept: (control: PendingControl) => boolean
     ): InjectedMessage[] => {
       if (task.status !== 'running') {
@@ -588,6 +718,9 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
       task.controls = retained;
       if (selected.length > 0) {
         task.updatedAt = Date.now();
+        for (const control of selected) {
+          this.transitionControl(task, control.id, 'applied', { boundary });
+        }
       }
       return selected.map(toInjectedMessage);
     };
@@ -599,15 +732,15 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
         task.controls.some((control) => control.action === 'interrupt'),
       drain: (boundary: SubagentTaskBoundary): InjectedMessage[] => {
         if (boundary === 'preempt') {
-          return take((control) => control.action === 'interrupt');
+          return take(boundary, (control) => control.action === 'interrupt');
         }
         if (boundary === 'tool') {
-          return take((control) => control.action !== 'queue');
+          return take(boundary, (control) => control.action !== 'queue');
         }
-        return take(() => true);
+        return take(boundary, () => true);
       },
       closeTurn: (): { closed: boolean; messages: InjectedMessage[] } => {
-        const messages = take(() => true);
+        const messages = take('turn', () => true);
         if (messages.length > 0) {
           return { closed: false, messages };
         }

package/src/types/graph.ts

@@ -614,6 +614,7 @@ export type SubagentUpdatePhase =
   | 'run_step_closed'
   | 'message_delta'
   | 'reasoning_delta'
+  | 'control'
   | 'stop'
   | 'error';
 

package/src/types/subagentTasks.ts

@@ -12,6 +12,28 @@ export type SubagentTaskStatus =
 /** Where a pending parent message may enter the child run. */
 export type SubagentTaskBoundary = 'preempt' | 'tool' | 'turn';
 
+/**
+ * Lifecycle of one parent-to-child message after the task store accepts it.
+ * Hosts may render a transient `submitted` state before this authoritative
+ * receipt exists; that transport state is intentionally not persisted here.
+ */
+export type SubagentTaskControlReceiptStatus =
+  | 'accepted'
+  | 'applied'
+  | 'rejected'
+  | 'failed';
+
+/** Bounded authoritative receipt for one steer, queue, or interrupt command. */
+export interface SubagentTaskControlReceipt {
+  controlId: string;
+  action: 'steer' | 'queue' | 'interrupt';
+  status: SubagentTaskControlReceiptStatus;
+  createdAt: number;
+  updatedAt: number;
+  boundary?: SubagentTaskBoundary;
+  reason?: 'withdrawn' | 'task_completed' | 'task_cancelled' | 'task_failed';
+}
+
 /** Parent-to-child control operations accepted while a task is running. */
 export type SubagentTaskControlCommand =
   | { action: 'steer' | 'queue' | 'interrupt'; message: string }
@@ -42,6 +64,12 @@ export interface SubagentTaskSnapshot {
   resultAvailable: boolean;
   resultClaimed: boolean;
   pendingControls: number;
+  /**
+   * Bounded receipts emitted by stores that support authoritative control
+   * tracking. Optional so legacy and custom stores remain compatible during
+   * rolling upgrades.
+   */
+  controlReceipts?: SubagentTaskControlReceipt[];
   progress?: SubagentTaskProgress;
   error?: string;
 }

package/src/types/summarize.ts

@@ -11,25 +11,27 @@ export type SummarizationTrigger = {
 };
 
 /**
- * Controls how many recent messages are preserved verbatim during
- * compaction.  The most recent user-led turn is always preserved
- * regardless of these caps, so a single oversized first message is
- * never destroyed by summarization.
+ * Controls how much recent context is preserved verbatim during compaction.
+ * User-turn boundaries are preferred. Under context pressure, older closed
+ * tool units inside an otherwise indivisible turn may be summarized while a
+ * token-priced recent tail is retained. A lone user payload stays intact.
  */
 export type RetainRecentConfig = {
   /**
-   * Maximum number of recent user-led turns to keep in the tail.  A turn
-   * begins at a HumanMessage and includes every following AIMessage and
-   * ToolMessage up to (but not including) the next HumanMessage.  Cutting
-   * at turn boundaries guarantees tool_use / tool_result pairs are never
-   * split.  Set to `0` to disable the recency window (legacy behavior:
-   * summarize everything).  Defaults to `2`.
+   * Maximum number of recent user-led turns to keep in the tail. A turn begins
+   * at a user-authored HumanMessage and includes every following AIMessage and
+   * tool result up to the next user-authored HumanMessage. Provider-native
+   * HumanMessages containing only tool results remain in the current turn.
+   * Set to `0` to disable the recency window (legacy behavior: summarize
+   * everything). Defaults to `2`.
    */
   turns?: number;
   /**
-   * Optional cap on retained-recent tokens beyond the most recent turn.
-   * Older turns are added whole only while cumulative tokens stay below
-   * the cap.  Defaults to undefined (no cap; bounded only by `turns`).
+   * Optional retained-recent token budget. Older turns are added whole only
+   * while cumulative tokens stay below the cap. If a tool-heavy history has
+   * no compactable turn-level head, this is also the minimum recent tail kept
+   * behind a pairing-balanced intra-turn cut. When omitted, that fallback
+   * retains 16% of the configured context window.
    */
   tokens?: number;
 };