@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/memory/types.ts

@@ -1,7 +1,7 @@
 /**
  * Autonomous memory — core types.
  *
- * Ported from upstream's memory-core pattern, adapted for Postgres + pgvector
+ * Ported from the reference implementation's memory-core pattern, adapted for Postgres + pgvector
  * and shaped so a future graph-backend layer (Graphiti, Neo4j agent-memory, etc.)
  * can be added alongside the vector store without changing the tool contracts.
  *
@@ -79,7 +79,7 @@ export interface MemorySearchOptions {
   minScore?: number;
   /**
    * Phase 2 toggles — when the backend supports them. Each is independently
-   * opt-in; all false = upstream Phase 1 behavior.
+   * opt-in; all false = Phase 1 behavior.
    */
   mmr?: { enabled?: boolean; lambda?: number };
   temporalDecay?: { enabled?: boolean; halfLifeDays?: number };
@@ -156,7 +156,7 @@ export interface MemoryConfig {
   search?: {
     maxResults?: number;
     maxInjectedChars?: number;
-    /** Phase 2 — enable MMR reranking (upstream-aligned defaults when true). */
+    /** Phase 2 — enable MMR reranking (defaults when true). */
     mmr?: { enabled?: boolean; lambda?: number };
     /** Phase 2 — enable temporal decay on dated memory files. */
     temporalDecay?: { enabled?: boolean; halfLifeDays?: number };

package/src/messages/__tests__/contextPruning.test.ts

@@ -0,0 +1,228 @@
+import {
+  AIMessage,
+  BaseMessage,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type { TokenCounter } from '@/types/run';
+import { applyContextPruning } from '../contextPruning';
+
+const counter: TokenCounter = (msg: BaseMessage) => {
+  if (typeof msg.content === 'string') return Math.max(1, msg.content.length);
+  return 1;
+};
+
+describe('applyContextPruning', () => {
+  it('returns zero counts when disabled', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage('thinking'),
+      new ToolMessage({
+        content: 'a'.repeat(10000),
+        tool_call_id: 't1',
+      }),
+    ];
+    const map = { 0: 1, 1: 1, 2: 10000 };
+    const out = applyContextPruning({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: counter,
+      config: { enabled: false },
+    });
+    expect(out.softTrimmed).toBe(0);
+    expect(out.hardCleared).toBe(0);
+    // Message untouched
+    expect((messages[2] as ToolMessage).content).toHaveLength(10000);
+  });
+
+  it('soft-trims an older tool result with content over the threshold', () => {
+    // Build a sequence with an old tool result outside the protected zone.
+    const messages: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('q1'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't', args: {}, id: 'old' }],
+      }),
+      new ToolMessage({
+        // Long string — should soft-trim.
+        content: 'OLD_TOOL_RESULT' + 'a'.repeat(20000),
+        tool_call_id: 'old',
+      }),
+      new HumanMessage('q2'),
+      new AIMessage('answer 1'),
+      new HumanMessage('q3'),
+      new AIMessage('answer 2'),
+      new HumanMessage('q4'),
+      new AIMessage('answer 3'),
+      new HumanMessage('q5'),
+      new AIMessage('answer 4'),
+    ];
+    const map: Record<string, number> = {};
+    for (let i = 0; i < messages.length; i++) {
+      map[i] = counter(messages[i]);
+    }
+
+    const result = applyContextPruning({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: counter,
+      config: {
+        enabled: true,
+        keepLastAssistants: 2,
+        softTrimRatio: 0.3,
+        hardClearRatio: 0.95,
+        minPrunableToolChars: 100,
+        softTrim: { maxChars: 200, headChars: 50, tailChars: 50 },
+        hardClear: { enabled: true, placeholder: '[evicted]' },
+      },
+    });
+
+    // The old tool result at index 3 should be soft-trimmed.
+    expect(result.softTrimmed).toBeGreaterThan(0);
+    const oldToolMsg = messages[3] as ToolMessage;
+    expect((oldToolMsg.content as string).length).toBeLessThan(20000);
+    expect(oldToolMsg.content).toContain('soft-trimmed');
+  });
+
+  it('hard-clears very old tool results when above hardClearRatio', () => {
+    // Position-age = (totalMessages - i) / totalMessages; with totalMessages=12
+    // and i=0, ratio=1.0 (oldest). But system at i=0 is in the protected zone.
+    // i=2 (the AI/tool pair) gives ratio=10/12 ≈ 0.83.
+    const messages: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('q1'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't', args: {}, id: 'oldest' }],
+      }),
+      new ToolMessage({
+        content: 'OLDEST' + 'x'.repeat(5000),
+        tool_call_id: 'oldest',
+      }),
+    ];
+    for (let i = 0; i < 8; i++) {
+      messages.push(new HumanMessage(`recent ${i}`));
+      messages.push(new AIMessage(`reply ${i}`));
+    }
+    const map: Record<string, number> = {};
+    for (let i = 0; i < messages.length; i++) {
+      map[i] = counter(messages[i]);
+    }
+
+    const result = applyContextPruning({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: counter,
+      config: {
+        enabled: true,
+        keepLastAssistants: 2,
+        softTrimRatio: 0.3,
+        hardClearRatio: 0.7,
+        minPrunableToolChars: 100,
+        softTrim: { maxChars: 200, headChars: 50, tailChars: 50 },
+        hardClear: { enabled: true, placeholder: '[evicted]' },
+      },
+    });
+
+    expect(result.hardCleared).toBeGreaterThan(0);
+    const oldToolMsg = messages[3] as ToolMessage;
+    expect(oldToolMsg.content).toBe('[evicted]');
+  });
+
+  it('does not touch tool results inside the protected zone (last N assistant turns)', () => {
+    const messages: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('q1'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't', args: {}, id: 'recent' }],
+      }),
+      new ToolMessage({
+        content: 'RECENT' + 'y'.repeat(20000),
+        tool_call_id: 'recent',
+      }),
+    ];
+    const map: Record<string, number> = {};
+    for (let i = 0; i < messages.length; i++) {
+      map[i] = counter(messages[i]);
+    }
+
+    const result = applyContextPruning({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: counter,
+      config: {
+        enabled: true,
+        keepLastAssistants: 4,
+        softTrimRatio: 0.0,
+        hardClearRatio: 0.0,
+        minPrunableToolChars: 100,
+        softTrim: { maxChars: 200, headChars: 50, tailChars: 50 },
+        hardClear: { enabled: true, placeholder: '[evicted]' },
+      },
+    });
+
+    expect(result.softTrimmed).toBe(0);
+    expect(result.hardCleared).toBe(0);
+    expect((messages[3] as ToolMessage).content).toContain('y'.repeat(100));
+  });
+
+  it('skips messages with image content even when out of protected zone', () => {
+    const imageBlock = {
+      type: 'image_url',
+      image_url: { url: 'data:image/png;base64,iVBORw0K...' },
+    };
+    const messages: BaseMessage[] = [
+      new SystemMessage('sys'),
+      new HumanMessage('q'),
+      new AIMessage({
+        content: 'thinking',
+        tool_calls: [{ name: 't', args: {}, id: 'img' }],
+      }),
+      new ToolMessage({
+        content: [imageBlock] as never, // structured content not pruned
+        tool_call_id: 'img',
+      }),
+    ];
+    for (let i = 0; i < 8; i++) {
+      messages.push(new HumanMessage(`recent ${i}`));
+      messages.push(new AIMessage(`reply ${i}`));
+    }
+    const map: Record<string, number> = {};
+    for (let i = 0; i < messages.length; i++) {
+      map[i] = 1;
+    }
+
+    const result = applyContextPruning({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: counter,
+      config: {
+        enabled: true,
+        keepLastAssistants: 2,
+        softTrimRatio: 0.0,
+        hardClearRatio: 0.0,
+        minPrunableToolChars: 0,
+        softTrim: { maxChars: 200, headChars: 50, tailChars: 50 },
+        hardClear: { enabled: true, placeholder: '[evicted]' },
+      },
+    });
+
+    // Image-containing tool message must not have been touched.
+    expect(result.softTrimmed).toBe(0);
+    expect(Array.isArray((messages[3] as ToolMessage).content)).toBe(true);
+  });
+
+  it('returns zero counts on empty message array', () => {
+    const out = applyContextPruning({
+      messages: [],
+      indexTokenCountMap: {},
+      tokenCounter: counter,
+      config: { enabled: true },
+    });
+    expect(out.softTrimmed).toBe(0);
+    expect(out.hardCleared).toBe(0);
+  });
+});

package/src/messages/cache.test.ts

@@ -412,7 +412,14 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
     expect(first[1]).toEqual({ cachePoint: { type: 'default' } });
   });
 
-  it('works with the example from the langchain pr (with multi-turn behavior)', () => {
+  it('skips system messages (cachePoint added inline by AgentContext.buildSystemRunnable)', () => {
+    /* Contract change (PR #128 alignment): system message
+     * cachePoint is now emitted inline in AgentContext.buildSystemRunnable.
+     * addBedrockCacheControl must therefore SKIP system messages so the
+     * 2-cachePoint per-request budget stays available for the conversation
+     * tail. Caching the system prefix is what unlocks cross-user cost
+     * savings — Bedrock's prompt cache is account-scoped, so a stable
+     * system prefix shared across users hits the same cache entry. */
     const messages: TestMsg[] = [
       {
         role: 'system',
@@ -430,15 +437,17 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
 
     const result = addBedrockCacheControl(messages);
 
-    let system = result[0].content as MessageContentComplex[];
-    let user = result[1].content as MessageContentComplex[];
+    const system = result[0].content as MessageContentComplex[];
+    const user = result[1].content as MessageContentComplex[];
 
-    // Both messages get cachePoints (last 2 eligible messages)
-    expect(system[0]).toEqual({
-      type: ContentTypes.TEXT,
-      text: 'You\'re an advanced AI assistant.',
-    });
-    expect(system[1]).toEqual({ cachePoint: { type: 'default' } });
+    // System message is left untouched — addBedrockCacheControl does NOT
+    // add a cachePoint here. The cachePoint is added in AgentContext when
+    // the system message is first built.
+    expect(system).toEqual([
+      { type: ContentTypes.TEXT, text: 'You\'re an advanced AI assistant.' },
+    ]);
+
+    // User message still gets a cachePoint (last eligible).
     expect(user[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'What is the capital of France?',
@@ -458,30 +467,59 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
 
     const result2 = addBedrockCacheControl(result);
 
-    system = result2[0].content as MessageContentComplex[];
-    user = result2[1].content as MessageContentComplex[];
-    const assistant = result2[2].content as MessageContentComplex[];
+    const system2 = result2[0].content as MessageContentComplex[];
+    const user2 = result2[1].content as MessageContentComplex[];
+    const assistant2 = result2[2].content as MessageContentComplex[];
 
-    // System message no longer has cachePoint (it's not in the last 2 eligible)
-    expect(system[0]).toEqual({
-      type: ContentTypes.TEXT,
-      text: 'You\'re an advanced AI assistant.',
-    });
-    expect(system.length).toBe(1);
+    // System message still untouched.
+    expect(system2).toEqual([
+      { type: ContentTypes.TEXT, text: 'You\'re an advanced AI assistant.' },
+    ]);
 
-    // User message gets cachePoint (second-to-last eligible)
-    expect(user[0]).toEqual({
+    // Both conversation messages now get cachePoints (last 2 eligible).
+    expect(user2[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'What is the capital of France?',
     });
-    expect(user[1]).toEqual({ cachePoint: { type: 'default' } });
+    expect(user2[1]).toEqual({ cachePoint: { type: 'default' } });
 
-    // Assistant message gets cachePoint (last eligible)
-    expect(assistant[0]).toEqual({
+    expect(assistant2[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'Sure! The capital of France is Paris.',
     });
-    expect(assistant[1]).toEqual({ cachePoint: { type: 'default' } });
+    expect(assistant2[1]).toEqual({ cachePoint: { type: 'default' } });
+  });
+
+  it('strips stray Anthropic cache_control from system message (cross-provider safety)', () => {
+    /* If a system message arrives with an Anthropic-style cache_control
+     * marker (e.g. cross-provider switch), addBedrockCacheControl should
+     * sanitize it — Bedrock ignores cache_control and stale markers can
+     * confuse provider validation. */
+    const messages: TestMsg[] = [
+      {
+        role: 'system',
+        content: [
+          {
+            type: ContentTypes.TEXT,
+            text: 'You\'re an advanced AI assistant.',
+            cache_control: { type: 'ephemeral' },
+          } as MessageContentComplex,
+        ],
+      },
+      {
+        role: 'user',
+        content: [{ type: ContentTypes.TEXT, text: 'Hi' }],
+      },
+    ];
+
+    const result = addBedrockCacheControl(messages);
+    const system = result[0].content as MessageContentComplex[];
+
+    expect(system).toHaveLength(1);
+    expect('cache_control' in system[0]).toBe(false);
+    expect((system[0] as { text?: string }).text).toBe(
+      'You\'re an advanced AI assistant.'
+    );
   });
 
   it('is idempotent - calling multiple times does not add duplicate cache points', () => {

package/src/messages/cache.ts

@@ -14,6 +14,61 @@ type MessageWithContent = {
   content?: string | MessageContentComplex[];
 };
 
+type MessageContentWithCacheControl = MessageContentComplex & {
+  cache_control?: unknown;
+};
+
+/**
+ * Strips Anthropic-style `cache_control` markers from every block in the
+ * given content array. Returns the (possibly cloned) content and a flag
+ * indicating whether anything was actually modified — so callers can avoid
+ * unnecessary message clones.
+ *
+ * Used to sanitize a system message's content array before adding Bedrock
+ * cache points, so stray Anthropic markers (e.g. left over from a previous
+ * Anthropic-provider turn) don't prevent the Bedrock provider from caching
+ * the system prefix.
+ */
+function stripAnthropicCacheControlFromBlocks(
+  content: MessageContentComplex[]
+): { content: MessageContentComplex[]; modified: boolean } {
+  let modified = false;
+  const strippedContent = content.map((block) => {
+    if (!('cache_control' in block)) {
+      return block;
+    }
+
+    const cloned: MessageContentWithCacheControl = { ...block };
+    delete cloned.cache_control;
+    modified = true;
+    return cloned;
+  });
+
+  return { content: strippedContent, modified };
+}
+
+/**
+ * For the Bedrock cache pass, system messages must NOT carry Anthropic
+ * cache_control markers (those are an Anthropic-specific encoding and
+ * Bedrock uses cachePoint blocks instead). Strip them before the cache
+ * point insertion logic walks the message.
+ */
+function sanitizeBedrockSystemMessage<T extends MessageWithContent>(
+  message: T
+): T {
+  const content = message.content;
+  if (!Array.isArray(content)) {
+    return message;
+  }
+
+  const stripped = stripAnthropicCacheControlFromBlocks(content);
+  if (!stripped.modified) {
+    return message;
+  }
+
+  return cloneMessage(message, stripped.content);
+}
+
 /** Debug logger for cache operations - set ILLUMA_DEBUG_CACHE=true to enable */
 const debugCache = (message: string, data?: unknown): void => {
   if (process.env.ILLUMA_DEBUG_CACHE === 'true') {
@@ -361,8 +416,36 @@ export function addBedrockCacheControl<
 
   // Clone messages to avoid mutating originals
   const updatedMessages: T[] = messages.map((msg) => {
+    /* PRESERVE cachePoint on system messages — they're added inline by
+     * AgentContext.buildSystemRunnable to mark the cacheable system prefix
+     * for account-level caching. Only strip stray Anthropic cache_control
+     * (which Bedrock ignores). For non-system messages keep the existing
+     * behaviour: full strip + repopulate based on last-2 strategy. */
+    const msgType =
+      'getType' in msg && typeof msg.getType === 'function'
+        ? msg.getType()
+        : undefined;
+    const msgRole = (msg as Record<string, unknown>).role as string | undefined;
+    const isSystem = msgType === 'system' || msgRole === 'system';
+
     const content = msg.content;
     if (Array.isArray(content)) {
+      if (isSystem) {
+        /* System: keep cachePoint, only strip Anthropic cache_control. */
+        if (hasAnthropicCacheControl(content)) {
+          const stripped = content.map((block) => {
+            const rec = block as Record<string, unknown>;
+            if ('cache_control' in rec) {
+              const { cache_control: _, ...rest } = rec;
+              return rest as MessageContentComplex;
+            }
+            return block;
+          });
+          return cloneMessage(msg, stripped) as T;
+        }
+        return cloneMessage(msg, content) as T;
+      }
+
       // Strip existing cachePoint blocks and Anthropic-style cache_control
       const stripped = content
         .filter((block) => !isCachePoint(block))
@@ -456,6 +539,35 @@ export function addBedrockCacheControl<
     const message = updatedMessages[i];
     const msgContent = message.content;
 
+    /* System messages are handled by AgentContext.buildSystemRunnable —
+     * the cachePoint is emitted INLINE in the system message content array
+     * so the cacheable system prefix gets a marker every turn (not just
+     * when the system message happens to be in the last 2 eligible). The
+     * Bedrock converter (src/llm/bedrock/utils/message_inputs.ts:261-294)
+     * passes through cachePoint blocks in system content arrays.
+     *
+     * If we ALSO marked system here, we'd: (a) waste one of the two
+     * cachePoint budget slots that Bedrock honours per-request, starving
+     * the conversation tail, and (b) potentially double-mark a stable
+     * prefix that already has its own cachePoint.
+     *
+     * As a defensive cleanup, strip stray Anthropic-style cache_control
+     * markers from the system message — Bedrock ignores them and they
+     * can confuse provider validation. */
+    const _msgType =
+      'getType' in message && typeof message.getType === 'function'
+        ? message.getType()
+        : undefined;
+    const _msgRole = (message as Record<string, unknown>).role as
+      | string
+      | undefined;
+    if (_msgType === 'system' || _msgRole === 'system') {
+      updatedMessages[i] = sanitizeBedrockSystemMessage(
+        message as MessageWithContent
+      ) as T;
+      continue;
+    }
+
     // Skip empty/whitespace-only content
     if (msgContent == null) continue;
     if (typeof msgContent === 'string' && msgContent.trim() === '') continue;

package/src/messages/contextPruning.ts

@@ -0,0 +1,191 @@
+/**
+ * Position-based context pruning for tool results.
+ *
+ * Uses position-based age: the distance of a message
+ * from the conversation end as a fraction of total messages.
+ *
+ * Two degradation levels:
+ * - Soft-trim: Keep head + tail of tool result content, drop middle.
+ * - Hard-clear: Replace entire content with a placeholder.
+ *
+ * Messages in the "protected zone" (recent assistant turns, system/pre-first-human
+ * messages, and messages with image content) are never pruned.
+ */
+
+import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+import type { ContextPruningConfig } from '@/types/graph';
+import type { TokenCounter } from '@/types/run';
+import type { ContextPruningSettings } from './contextPruningSettings';
+import { resolveContextPruningSettings } from './contextPruningSettings';
+
+/**
+ * Checks if a message contains image content blocks.
+ * Messages with images are skipped by position-based content degradation
+ * because images cannot be meaningfully soft-trimmed or replaced with placeholders.
+ */
+function hasImageContent(message: BaseMessage): boolean {
+  if (!Array.isArray(message.content)) {
+    return false;
+  }
+  return message.content.some(
+    (block) =>
+      typeof block === 'object' &&
+      'type' in block &&
+      (block.type === 'image_url' || block.type === 'image')
+  );
+}
+
+/**
+ * Applies head+tail soft-trim to tool result content.
+ */
+function softTrimContent(
+  content: string,
+  settings: ContextPruningSettings['softTrim']
+): string {
+  const { headChars, tailChars } = settings;
+  const indicator = `\n\n… [soft-trimmed: ${content.length} chars → ${headChars + tailChars} chars, middle removed] …\n\n`;
+  return content.slice(0, headChars) + indicator + content.slice(-tailChars);
+}
+
+export interface ContextPruningResult {
+  /** Number of messages that were soft-trimmed. */
+  softTrimmed: number;
+  /** Number of messages that were hard-cleared. */
+  hardCleared: number;
+}
+
+/**
+ * Applies position-based context pruning to tool result messages.
+ *
+ * Modifies messages in-place and updates indexTokenCountMap with recounted
+ * token values for modified messages.
+ *
+ * @param params.messages - The full message array (modified in-place).
+ * @param params.indexTokenCountMap - Token count map (updated in-place).
+ * @param params.tokenCounter - Function to recount tokens after modification.
+ * @param params.config - Partial context pruning config (merged with defaults).
+ * @returns Counts of soft-trimmed and hard-cleared messages.
+ */
+export function applyContextPruning(params: {
+  messages: BaseMessage[];
+  indexTokenCountMap: Record<string, number | undefined>;
+  tokenCounter: TokenCounter;
+  config?: ContextPruningConfig;
+  resolvedSettings?: ContextPruningSettings;
+}): ContextPruningResult {
+  const {
+    messages,
+    indexTokenCountMap,
+    tokenCounter,
+    config,
+    resolvedSettings,
+  } = params;
+  const settings = resolvedSettings ?? resolveContextPruningSettings(config);
+
+  if (!settings.enabled || messages.length === 0) {
+    return { softTrimmed: 0, hardCleared: 0 };
+  }
+
+  const totalMessages = messages.length;
+  let softTrimmed = 0;
+  let hardCleared = 0;
+
+  // Find the protected zone: last N assistant turns from the end.
+  // An "assistant turn" is a contiguous sequence of AI + Tool messages.
+  const protectedIndices = new Set<number>();
+
+  // Always protect the system message (index 0 if present)
+  if (messages[0]?.getType() === 'system') {
+    protectedIndices.add(0);
+  }
+
+  // Protect messages before the first human message
+  for (let i = 0; i < totalMessages; i++) {
+    if (messages[i].getType() === 'human') {
+      break;
+    }
+    protectedIndices.add(i);
+  }
+
+  // Protect the last N assistant turns (walking backwards)
+  let assistantTurnsFound = 0;
+  let inAssistantSequence = false;
+  for (let i = totalMessages - 1; i >= 0; i--) {
+    const type = messages[i].getType();
+    if (type === 'ai' || type === 'tool') {
+      protectedIndices.add(i);
+      if (!inAssistantSequence) {
+        inAssistantSequence = true;
+      }
+    } else {
+      if (inAssistantSequence) {
+        assistantTurnsFound++;
+        inAssistantSequence = false;
+        if (assistantTurnsFound >= settings.keepLastAssistants) {
+          break;
+        }
+      }
+      // Protect the human message between assistant turns in the protected zone
+      if (assistantTurnsFound < settings.keepLastAssistants) {
+        protectedIndices.add(i);
+      }
+    }
+  }
+
+  // Process each tool message outside the protected zone
+  for (let i = 0; i < totalMessages; i++) {
+    const message = messages[i];
+    if (message.getType() !== 'tool') {
+      continue;
+    }
+    if (protectedIndices.has(i)) {
+      continue;
+    }
+    if (hasImageContent(message)) {
+      continue;
+    }
+
+    const content = message.content;
+    if (typeof content !== 'string') {
+      continue;
+    }
+    if (content.length < settings.minPrunableToolChars) {
+      continue;
+    }
+
+    // Compute age ratio: how far back from the end (0 = latest, 1 = oldest)
+    const ageRatio = (totalMessages - i) / totalMessages;
+
+    if (ageRatio >= settings.hardClearRatio && settings.hardClear.enabled) {
+      // Hard-clear: replace with placeholder
+      const cloned = new ToolMessage({
+        content: settings.hardClear.placeholder,
+        tool_call_id: (message as ToolMessage).tool_call_id,
+        name: message.name,
+        id: message.id,
+        additional_kwargs: message.additional_kwargs,
+        response_metadata: message.response_metadata,
+      });
+      messages[i] = cloned;
+      indexTokenCountMap[i] = tokenCounter(cloned);
+      hardCleared++;
+    } else if (ageRatio >= settings.softTrimRatio) {
+      // Soft-trim: keep head + tail
+      if (content.length > settings.softTrim.maxChars) {
+        const cloned = new ToolMessage({
+          content: softTrimContent(content, settings.softTrim),
+          tool_call_id: (message as ToolMessage).tool_call_id,
+          name: message.name,
+          id: message.id,
+          additional_kwargs: message.additional_kwargs,
+          response_metadata: message.response_metadata,
+        });
+        messages[i] = cloned;
+        indexTokenCountMap[i] = tokenCounter(cloned);
+        softTrimmed++;
+      }
+    }
+  }
+
+  return { softTrimmed, hardCleared };
+}