@librechat/agents 3.7.0 → 3.7.2

package/dist/types/session/index.d.ts

@@ -1,5 +1,7 @@
 export { AgentSession, createAgentSession } from './AgentSession';
+export { deriveMessages } from './deriveMessages';
 export { JsonlSessionStore, SessionManager } from './JsonlSessionStore';
 export { createRunHandlers } from './handlers';
 export { serializeMessage, deserializeMessage, extractTextFromContent, } from './messageSerialization';
 export type { AgentSessionConfig, AgentSessionCheckpointLookupOptions, AgentSessionCheckpointReference, AgentSessionCheckpointing, AgentSessionCheckpointingOptions, AgentSessionHandlersResult, AgentSessionInput, AgentSessionRunOptions, AgentSessionRunResult, AgentSessionStream, AgentSessionStreamEvent, AgentSessionUsage, CreateSessionFileOptions, JsonObject, JsonPrimitive, JsonValue, SerializedSessionMessage, SessionBranchOptions, SessionCompactOptions, SessionCheckpointEntry, SessionCompactionEntry, SessionEntry, SessionEntryBase, SessionEntryType, SessionForkOptions, SessionHeader, SessionLabelEntry, SessionListItem, SessionMessageEntry, SessionPosition, SessionRunEventEntry, SessionStateEntry, SessionSummaryEntry, SessionTreeNode, } from './types';
+export type { DerivedSessionMessages } from './deriveMessages';

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

@@ -1,8 +1,9 @@
-import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
+import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlReceipt, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
 export interface InMemorySubagentTaskStoreOptions {
     completedTtlMs?: number;
     maxControlMessageChars?: number;
     maxControlsPerTask?: number;
+    maxControlReceiptsPerTask?: number;
     maxErrorChars?: number;
     maxResultChars?: number;
     maxRunningPerScope?: number;
@@ -25,6 +26,14 @@ export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
     private runningTasks;
     private totalTasks;
     constructor(options?: InMemorySubagentTaskStoreOptions);
+    /**
+     * 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;
     start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
     get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
     list(scopeId: string): SubagentTaskSnapshot[];
@@ -37,6 +46,9 @@ export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
     private sweepBucket;
     private removeTask;
     private dropEmptyBucket;
+    private makeRoomForControlReceipt;
+    private transitionControl;
+    private failPendingControls;
     private scheduleExpiry;
     private clearTaskExpiry;
     private clearTaskTimeout;

package/dist/types/types/graph.d.ts

@@ -452,7 +452,7 @@ export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentS
 /** Graph-aware config accepted by the executor. Graph configs stay eager. */
 export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
-export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'run_step_closed' | 'message_delta' | 'reasoning_delta' | 'control' | 'stop' | 'error';
 export interface SubagentAncestryEntry {
     readonly subagentRunId: string;
     readonly subagentType: string;

package/dist/types/types/subagentTasks.d.ts

@@ -5,6 +5,22 @@ import type { InjectedMessage } from './tools';
 export type SubagentTaskStatus = 'running' | 'completed' | 'error' | 'cancelled';
 /** 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';
@@ -39,6 +55,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/dist/types/types/summarize.d.ts

@@ -5,25 +5,27 @@ export type SummarizationTrigger = {
     value: number;
 };
 /**
- * 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;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -197,80 +197,72 @@
     "sort-imports:check": "node scripts/sort-imports.ts --check",
     "start": "node dist/esm/main.js",
     "clean": "node ./config/clean.js",
-    "script": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli.ts",
+    "script": "tsx -r dotenv/config ./src/scripts/cli.ts",
     "bun:cli": "bun -r dotenv/config ./src/scripts/cli.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "start:cli": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "content": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/content.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "stream": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/stream.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "code_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "image": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/image.ts --provider 'google' --name 'Jo' --location 'New York, NY'",
-    "code_exec_files": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_files.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "code_exec_session": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "code_exec_multi_session": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_multi_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "code_exec_simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_simple.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/simple.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "caching": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/caching.ts --name 'Jo' --location 'New York, NY'",
-    "thinking": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking.ts --name 'Jo' --location 'New York, NY'",
-    "thinking:bedrock": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking-bedrock.ts --name 'Jo' --location 'New York, NY'",
-    "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
-    "bench:cache": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-prompt-cache.ts",
-    "bench:context-pressure": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-context-pressure-cache.ts",
-    "bench:provider-derivation": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-provider-derivation.ts",
-    "bench:execution-world": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-execution-world.ts",
-    "probe:overflow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/context-overflow-probe.ts",
-    "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
-    "subagent:events": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-event-driven-debug.ts",
-    "subagent:tools": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-tools-debug.ts",
-    "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
-    "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "local": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "local:ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "local:hooks": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_hooks.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "local:checkpointer": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_checkpointer.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "local:image": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_image.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "local:compile": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_compile.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "compare:pi": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/compare_pi_vs_ours.ts",
-    "session:live": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/session_live.ts",
-    "local:workspace": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/local_engine_workspace.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "ant_web_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search.ts --name 'Jo' --location 'New York, NY'",
-    "ant_web_search_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_edge_case.ts --name 'Jo' --location 'New York, NY'",
-    "ant_web_search_error_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_error_edge_case.ts --name 'Jo' --location 'New York, NY'",
-    "abort": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/abort.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "start:cli2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli2.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
-    "multi-agent-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-test.ts",
-    "test-tools-before-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-tools-before-handoff.ts",
-    "multi-agent-parallel": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel.ts",
-    "multi-agent-parallel-start": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel-start.ts",
-    "single-agent-metadata-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/single-agent-metadata-test.ts",
-    "multi-agent-chain": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-chain.ts",
-    "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
-    "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
-    "multi-agent-subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
-    "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
-    "test-handoff-preamble": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-preamble.ts",
-    "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",
-    "test-parallel-agent-labeling": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-parallel-agent-labeling.ts",
-    "test-thinking-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-thinking-handoff.ts",
-    "test-thinking-handoff-bedrock": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-thinking-handoff-bedrock.ts",
-    "test-thinking-to-thinking-handoff-bedrock": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-thinking-to-thinking-handoff-bedrock.ts",
-    "multi-agent-hybrid-flow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-hybrid-flow.ts",
-    "test-handoff-input": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-input.ts",
-    "test-custom-prompt-key": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-custom-prompt-key.ts",
-    "script2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/proto/example_test.ts",
-    "script3": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/proto/example_test_anthropic.ts",
-    "script4": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli4.ts --name 'Jo' --location 'New York, NY'",
-    "script5": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli5.ts --name 'Jo' --location 'New York, NY'",
-    "start:standard": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/standard.ts",
-    "start:cg": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/collab.ts",
-    "start:tasks": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tasks.ts",
-    "start:collab": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/main.ts",
-    "start:collab5": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/collab_design_v5.ts",
-    "start:dev": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/main.ts",
-    "supervised": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/supervised.ts --provider anthropic --name Jo --location \"New York, NY\"",
+    "start:cli": "tsx -r dotenv/config ./src/scripts/cli.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "content": "tsx -r dotenv/config ./src/scripts/content.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "stream": "tsx -r dotenv/config ./src/scripts/stream.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "code_exec": "tsx -r dotenv/config ./src/scripts/code_exec.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_files": "tsx -r dotenv/config ./src/scripts/code_exec_files.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_session": "tsx -r dotenv/config ./src/scripts/code_exec_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_multi_session": "tsx -r dotenv/config ./src/scripts/code_exec_multi_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_simple": "tsx -r dotenv/config ./src/scripts/code_exec_simple.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "simple": "tsx -r dotenv/config ./src/scripts/simple.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
+    "caching": "tsx -r dotenv/config ./src/scripts/caching.ts --name 'Jo' --location 'New York, NY'",
+    "thinking": "tsx -r dotenv/config ./src/scripts/thinking.ts --name 'Jo' --location 'New York, NY'",
+    "thinking:bedrock": "tsx -r dotenv/config ./src/scripts/thinking-bedrock.ts --name 'Jo' --location 'New York, NY'",
+    "memory": "tsx -r dotenv/config ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "tool": "tsx --trace-warnings -r dotenv/config ./src/scripts/tools.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
+    "search": "tsx -r dotenv/config ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
+    "tool_search": "tsx -r dotenv/config ./src/scripts/tool_search.ts",
+    "bench:cache": "tsx ./src/scripts/bench-prompt-cache.ts",
+    "bench:context-pressure": "tsx ./src/scripts/bench-context-pressure-cache.ts",
+    "bench:compaction-range": "tsx ./src/scripts/bench-compaction-range.ts",
+    "bench:provider-derivation": "tsx ./src/scripts/bench-provider-derivation.ts",
+    "bench:provider-projection": "tsx ./src/scripts/bench-provider-request-projection.ts",
+    "bench:execution-world": "tsx ./src/scripts/bench-execution-world.ts",
+    "probe:overflow": "tsx -r dotenv/config ./src/scripts/context-overflow-probe.ts",
+    "subagent": "tsx -r dotenv/config ./src/scripts/multi-agent-subagent.ts",
+    "subagent:events": "tsx -r dotenv/config ./src/scripts/subagent-event-driven-debug.ts",
+    "subagent:tools": "tsx -r dotenv/config ./src/scripts/subagent-tools-debug.ts",
+    "programmatic_exec": "tsx -r dotenv/config ./src/scripts/programmatic_exec.ts",
+    "code_exec_ptc": "tsx -r dotenv/config ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "local": "tsx -r dotenv/config ./src/scripts/local_engine.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "local:ptc": "tsx -r dotenv/config ./src/scripts/local_engine_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "local:hooks": "tsx -r dotenv/config ./src/scripts/local_engine_hooks.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "local:checkpointer": "tsx -r dotenv/config ./src/scripts/local_engine_checkpointer.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "local:image": "tsx -r dotenv/config ./src/scripts/local_engine_image.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "local:compile": "tsx -r dotenv/config ./src/scripts/local_engine_compile.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "compare:pi": "tsx -r dotenv/config ./src/scripts/compare_pi_vs_ours.ts",
+    "session:live": "tsx -r dotenv/config ./src/scripts/session_live.ts",
+    "local:workspace": "tsx -r dotenv/config ./src/scripts/local_engine_workspace.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "programmatic_exec_agent": "tsx -r dotenv/config ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "ant_web_search": "tsx -r dotenv/config ./src/scripts/ant_web_search.ts --name 'Jo' --location 'New York, NY'",
+    "ant_web_search_edge_case": "tsx -r dotenv/config ./src/scripts/ant_web_search_edge_case.ts --name 'Jo' --location 'New York, NY'",
+    "ant_web_search_error_edge_case": "tsx -r dotenv/config ./src/scripts/ant_web_search_error_edge_case.ts --name 'Jo' --location 'New York, NY'",
+    "abort": "tsx -r dotenv/config ./src/scripts/abort.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "start:cli2": "tsx -r dotenv/config ./src/scripts/cli2.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
+    "multi-agent-test": "tsx -r dotenv/config ./src/scripts/multi-agent-test.ts",
+    "test-tools-before-handoff": "tsx -r dotenv/config ./src/scripts/test-tools-before-handoff.ts",
+    "multi-agent-parallel": "tsx -r dotenv/config ./src/scripts/multi-agent-parallel.ts",
+    "multi-agent-parallel-start": "tsx -r dotenv/config ./src/scripts/multi-agent-parallel-start.ts",
+    "single-agent-metadata-test": "tsx -r dotenv/config ./src/scripts/single-agent-metadata-test.ts",
+    "multi-agent-chain": "tsx -r dotenv/config ./src/scripts/multi-agent-chain.ts",
+    "multi-agent-sequence": "tsx -r dotenv/config ./src/scripts/multi-agent-sequence.ts",
+    "multi-agent-conditional": "tsx -r dotenv/config ./src/scripts/multi-agent-conditional.ts",
+    "multi-agent-subagent": "tsx -r dotenv/config ./src/scripts/multi-agent-subagent.ts",
+    "multi-agent-supervisor": "tsx -r dotenv/config ./src/scripts/multi-agent-supervisor.ts",
+    "test-handoff-preamble": "tsx -r dotenv/config ./src/scripts/test-handoff-preamble.ts",
+    "multi-agent-list-handoff": "tsx -r dotenv/config ./src/scripts/test-multi-agent-list-handoff.ts",
+    "test-parallel-agent-labeling": "tsx -r dotenv/config ./src/scripts/test-parallel-agent-labeling.ts",
+    "test-thinking-handoff": "tsx -r dotenv/config ./src/scripts/test-thinking-handoff.ts",
+    "test-thinking-handoff-bedrock": "tsx -r dotenv/config ./src/scripts/test-thinking-handoff-bedrock.ts",
+    "test-thinking-to-thinking-handoff-bedrock": "tsx -r dotenv/config ./src/scripts/test-thinking-to-thinking-handoff-bedrock.ts",
+    "multi-agent-hybrid-flow": "tsx -r dotenv/config ./src/scripts/multi-agent-hybrid-flow.ts",
+    "test-handoff-input": "tsx -r dotenv/config ./src/scripts/test-handoff-input.ts",
+    "test-custom-prompt-key": "tsx -r dotenv/config ./src/scripts/test-custom-prompt-key.ts",
+    "script4": "tsx -r dotenv/config ./src/scripts/cli4.ts --name 'Jo' --location 'New York, NY'",
+    "script5": "tsx -r dotenv/config ./src/scripts/cli5.ts --name 'Jo' --location 'New York, NY'",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:live:handoffs": "RUN_HANDOFF_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/agent-handoffs.live.test.ts --runInBand",
     "test:live:ask-user-questions": "RUN_ASK_USER_QUESTIONS_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/ask-user-questions.live.test.ts --runInBand",
@@ -281,7 +273,7 @@
     "lint": "eslint \"{,!(node_modules|venv)/**/}*.{js,jsx,ts,tsx}\" --fix",
     "format": "prettier --write .",
     "audit": "npm audit --omit=dev",
-    "label:eval": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/activity-labels/run.ts",
+    "label:eval": "tsx -r dotenv/config ./src/scripts/activity-labels/run.ts",
     "label:rescore": "node ./src/scripts/activity-labels/rescore.cjs"
   },
   "overrides": {
@@ -365,11 +357,10 @@
     "mongodb-memory-server-core": "^11.2.0",
     "prettier": "^3.6.2",
     "ts-jest": "^29.4.6",
-    "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.10",
-    "tsconfig-paths": "^4.2.0",
     "tsdown": "^0.22.2",
     "tslib": "^2.6.3",
+    "tsx": "^4.23.12",
     "typescript": "^5.5.3",
     "winston": "^3.17.0"
   },

package/src/agents/AgentContext.ts

@@ -357,6 +357,8 @@ export class AgentContext {
    * - `'none'`: no summary present
    */
   private _summaryLocation: 'system_prompt' | 'user_message' | 'none' = 'none';
+  /** Whether a mid-run summary must appear before every retained message. */
+  private summaryPrecedesMessages: boolean = false;
   /**
    * Durable summary that survives reset() calls. Set from initialSummary
    * during fromConfig() and updated by setSummary() so that the latest
@@ -365,6 +367,7 @@ export class AgentContext {
    */
   private _durableSummaryText?: string;
   private _durableSummaryTokenCount: number = 0;
+  private durableSummaryPrecedesMessages: boolean = false;
   /** Number of summarization cycles that have occurred for this agent context */
   private _summaryVersion: number = 0;
   /**
@@ -989,10 +992,10 @@ export class AgentContext {
       return messages;
     }
 
-    const tailIndex = this.getPromptCacheDynamicTailIndex(
-      messages,
-      promptCacheProvider
-    );
+    const tailIndex =
+      this._summaryLocation === 'user_message' && this.summaryPrecedesMessages
+        ? 0
+        : this.getPromptCacheDynamicTailIndex(messages, promptCacheProvider);
     const stablePrefix = messages.slice(0, tailIndex);
     const trailingMessages = messages.slice(tailIndex);
     const cacheablePrefix = this.addStablePromptCacheMarkers(
@@ -1204,6 +1207,7 @@ export class AgentContext {
 
     this.summaryText = this._durableSummaryText;
     this.summaryTokenCount = this._durableSummaryTokenCount;
+    this.summaryPrecedesMessages = this.durableSummaryPrecedesMessages;
     this._lastSummarizationMsgCount = 0;
     this.lastCallUsage = undefined;
     this.totalTokensFresh = false;
@@ -1461,12 +1465,18 @@ export class AgentContext {
     }
   }
 
-  setSummary(text: string, tokenCount: number): void {
+  setSummary(
+    text: string,
+    tokenCount: number,
+    options?: { precedesMessages?: boolean }
+  ): void {
     this.summaryText = text;
     this.summaryTokenCount = tokenCount;
     this._summaryLocation = 'user_message';
+    this.summaryPrecedesMessages = options?.precedesMessages === true;
     this._durableSummaryText = text;
     this._durableSummaryTokenCount = tokenCount;
+    this.durableSummaryPrecedesMessages = this.summaryPrecedesMessages;
     this._summaryVersion += 1;
     this.systemRunnableStale = true;
     this.pruneMessages = undefined;
@@ -1477,8 +1487,10 @@ export class AgentContext {
     this.summaryText = text;
     this.summaryTokenCount = tokenCount;
     this._summaryLocation = 'system_prompt';
+    this.summaryPrecedesMessages = false;
     this._durableSummaryText = text;
     this._durableSummaryTokenCount = tokenCount;
+    this.durableSummaryPrecedesMessages = false;
     this._summaryVersion += 1;
     this.systemRunnableStale = true;
   }
@@ -1683,6 +1695,8 @@ export class AgentContext {
       this.summaryTokenCount = 0;
       this._durableSummaryText = undefined;
       this._durableSummaryTokenCount = 0;
+      this.summaryPrecedesMessages = false;
+      this.durableSummaryPrecedesMessages = false;
       this._summaryLocation = 'none';
       this.systemRunnableStale = true;
     }