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

package/dist/esm/messages/contextPruning.mjs

@@ -0,0 +1,154 @@
+import { ToolMessage } from '@langchain/core/messages';
+import { resolveContextPruningSettings } from './contextPruningSettings.mjs';
+
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    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, settings) {
+    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);
+}
+/**
+ * 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.
+ */
+function applyContextPruning(params) {
+    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();
+    // 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.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.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 };
+}
+
+export { applyContextPruning };
+//# sourceMappingURL=contextPruning.mjs.map

package/dist/esm/messages/contextPruning.mjs.map

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

package/dist/esm/messages/contextPruningSettings.mjs

@@ -0,0 +1,50 @@
+/**
+ * Default settings for position-based context pruning.
+ *
+ * These are merged with user-provided overrides so any subset can be customized.
+ */
+const DEFAULT_CONTEXT_PRUNING_SETTINGS = {
+    enabled: false,
+    keepLastAssistants: 3,
+    softTrimRatio: 0.3,
+    hardClearRatio: 0.5,
+    minPrunableToolChars: 50_000,
+    softTrim: {
+        maxChars: 4_000,
+        headChars: 1_500,
+        tailChars: 1_500,
+    },
+    hardClear: {
+        enabled: true,
+        placeholder: '[Old tool result content cleared]',
+    },
+};
+/**
+ * Merges user-provided partial overrides with the defaults.
+ */
+function resolveContextPruningSettings(overrides) {
+    if (!overrides) {
+        return { ...DEFAULT_CONTEXT_PRUNING_SETTINGS };
+    }
+    return {
+        enabled: overrides.enabled ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.enabled,
+        keepLastAssistants: overrides.keepLastAssistants ??
+            DEFAULT_CONTEXT_PRUNING_SETTINGS.keepLastAssistants,
+        softTrimRatio: overrides.softTrimRatio ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrimRatio,
+        hardClearRatio: overrides.hardClearRatio ??
+            DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClearRatio,
+        minPrunableToolChars: overrides.minPrunableToolChars ??
+            DEFAULT_CONTEXT_PRUNING_SETTINGS.minPrunableToolChars,
+        softTrim: {
+            ...DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrim,
+            ...overrides.softTrim,
+        },
+        hardClear: {
+            ...DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClear,
+            ...overrides.hardClear,
+        },
+    };
+}
+
+export { DEFAULT_CONTEXT_PRUNING_SETTINGS, resolveContextPruningSettings };
+//# sourceMappingURL=contextPruningSettings.mjs.map

package/dist/esm/messages/contextPruningSettings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextPruningSettings.mjs","sources":["../../../src/messages/contextPruningSettings.ts"],"sourcesContent":["/**\n * Default settings for position-based context pruning.\n *\n * These are merged with user-provided overrides so any subset can be customized.\n */\n\nexport interface ContextPruningSettings {\n  /** Whether position-based pruning is enabled. Default: false (opt-in). */\n  enabled: boolean;\n  /** Number of recent assistant turns to protect from pruning. Default: 3 */\n  keepLastAssistants: number;\n  /** Age ratio (0-1) at which soft-trim fires. Default: 0.3 */\n  softTrimRatio: number;\n  /** Age ratio (0-1) at which hard-clear fires. Default: 0.5 */\n  hardClearRatio: number;\n  /** Minimum tool result size (chars) before pruning applies. Default: 50000 */\n  minPrunableToolChars: number;\n  softTrim: {\n    /** Maximum total chars after soft-trim. Default: 4000 */\n    maxChars: number;\n    /** Head portion to keep. Default: 1500 */\n    headChars: number;\n    /** Tail portion to keep. Default: 1500 */\n    tailChars: number;\n  };\n  hardClear: {\n    /** Whether hard-clear is enabled. Default: true */\n    enabled: boolean;\n    /** Placeholder text for hard-cleared content. */\n    placeholder: string;\n  };\n}\n\nexport const DEFAULT_CONTEXT_PRUNING_SETTINGS: ContextPruningSettings = {\n  enabled: false,\n  keepLastAssistants: 3,\n  softTrimRatio: 0.3,\n  hardClearRatio: 0.5,\n  minPrunableToolChars: 50_000,\n  softTrim: {\n    maxChars: 4_000,\n    headChars: 1_500,\n    tailChars: 1_500,\n  },\n  hardClear: {\n    enabled: true,\n    placeholder: '[Old tool result content cleared]',\n  },\n};\n\n/**\n * Merges user-provided partial overrides with the defaults.\n */\nexport function resolveContextPruningSettings(\n  overrides?: Partial<{\n    enabled?: boolean;\n    keepLastAssistants?: number;\n    softTrimRatio?: number;\n    hardClearRatio?: number;\n    minPrunableToolChars?: number;\n    softTrim?: Partial<ContextPruningSettings['softTrim']>;\n    hardClear?: Partial<ContextPruningSettings['hardClear']>;\n  }>\n): ContextPruningSettings {\n  if (!overrides) {\n    return { ...DEFAULT_CONTEXT_PRUNING_SETTINGS };\n  }\n  return {\n    enabled: overrides.enabled ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.enabled,\n    keepLastAssistants:\n      overrides.keepLastAssistants ??\n      DEFAULT_CONTEXT_PRUNING_SETTINGS.keepLastAssistants,\n    softTrimRatio:\n      overrides.softTrimRatio ?? DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrimRatio,\n    hardClearRatio:\n      overrides.hardClearRatio ??\n      DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClearRatio,\n    minPrunableToolChars:\n      overrides.minPrunableToolChars ??\n      DEFAULT_CONTEXT_PRUNING_SETTINGS.minPrunableToolChars,\n    softTrim: {\n      ...DEFAULT_CONTEXT_PRUNING_SETTINGS.softTrim,\n      ...overrides.softTrim,\n    },\n    hardClear: {\n      ...DEFAULT_CONTEXT_PRUNING_SETTINGS.hardClear,\n      ...overrides.hardClear,\n    },\n  };\n}\n"],"names":[],"mappings":"AAAA;;;;AAIG;AA6BI,MAAM,gCAAgC,GAA2B;AACtE,IAAA,OAAO,EAAE,KAAK;AACd,IAAA,kBAAkB,EAAE,CAAC;AACrB,IAAA,aAAa,EAAE,GAAG;AAClB,IAAA,cAAc,EAAE,GAAG;AACnB,IAAA,oBAAoB,EAAE,MAAM;AAC5B,IAAA,QAAQ,EAAE;AACR,QAAA,QAAQ,EAAE,KAAK;AACf,QAAA,SAAS,EAAE,KAAK;AAChB,QAAA,SAAS,EAAE,KAAK;AACjB,KAAA;AACD,IAAA,SAAS,EAAE;AACT,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,WAAW,EAAE,mCAAmC;AACjD,KAAA;;AAGH;;AAEG;AACG,SAAU,6BAA6B,CAC3C,SAQE,EAAA;IAEF,IAAI,CAAC,SAAS,EAAE;AACd,QAAA,OAAO,EAAE,GAAG,gCAAgC,EAAE;IAChD;IACA,OAAO;AACL,QAAA,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,gCAAgC,CAAC,OAAO;QACtE,kBAAkB,EAChB,SAAS,CAAC,kBAAkB;AAC5B,YAAA,gCAAgC,CAAC,kBAAkB;AACrD,QAAA,aAAa,EACX,SAAS,CAAC,aAAa,IAAI,gCAAgC,CAAC,aAAa;QAC3E,cAAc,EACZ,SAAS,CAAC,cAAc;AACxB,YAAA,gCAAgC,CAAC,cAAc;QACjD,oBAAoB,EAClB,SAAS,CAAC,oBAAoB;AAC9B,YAAA,gCAAgC,CAAC,oBAAoB;AACvD,QAAA,QAAQ,EAAE;YACR,GAAG,gCAAgC,CAAC,QAAQ;YAC5C,GAAG,SAAS,CAAC,QAAQ;AACtB,SAAA;AACD,QAAA,SAAS,EAAE;YACT,GAAG,gCAAgC,CAAC,SAAS;YAC7C,GAAG,SAAS,CAAC,SAAS;AACvB,SAAA;KACF;AACH;;;;"}

package/dist/esm/messages/format.mjs

@@ -149,16 +149,69 @@ const formatFromLangChain = (message) => {
         ...additional_kwargs,
     };
 };
+function extractReasoningContent(part) {
+    if (part == null || typeof part !== 'object')
+        return '';
+    if (part.type === ContentTypes.THINK) {
+        const think = part.think;
+        return typeof think === 'string' ? think : '';
+    }
+    if (part.type === ContentTypes.THINKING) {
+        const thinking = part.thinking;
+        return typeof thinking === 'string' ? thinking : '';
+    }
+    if (part.type === ContentTypes.REASONING) {
+        const reasoning = part.reasoning;
+        return typeof reasoning === 'string' ? reasoning : '';
+    }
+    if (part.type === ContentTypes.REASONING_CONTENT) {
+        /* Bedrock/Google nested shape: { reasoningContent: { text: ... } } */
+        const nested = part
+            .reasoningContent;
+        if (nested && typeof nested.text === 'string')
+            return nested.text;
+    }
+    return '';
+}
 /**
  * Helper function to format an assistant message
  * @param message The message to format
+ * @param options Optional formatting options (e.g. DeepSeek reasoning roundtrip)
  * @returns Array of formatted messages
  */
-function formatAssistantMessage(message) {
+function formatAssistantMessage(message, options) {
     const formattedMessages = [];
     let currentContent = [];
     let lastAIMessage = null;
     let hasReasoning = false;
+    let pendingReasoningContent = '';
+    const shouldPreserveReasoningContent = options?.preserveReasoningContent === true;
+    const takePendingReasoningContent = () => {
+        if (!shouldPreserveReasoningContent || !pendingReasoningContent) {
+            return undefined;
+        }
+        const reasoningContent = pendingReasoningContent;
+        pendingReasoningContent = '';
+        return reasoningContent;
+    };
+    const createAIMessage = (content) => {
+        const reasoningContent = takePendingReasoningContent();
+        return new AIMessage({
+            content,
+            ...(reasoningContent != null && {
+                additional_kwargs: { reasoning_content: reasoningContent },
+            }),
+        });
+    };
+    const attachPendingReasoningContent = (aiMessage) => {
+        const reasoningContent = takePendingReasoningContent();
+        if (reasoningContent == null)
+            return;
+        aiMessage.additional_kwargs.reasoning_content =
+            typeof aiMessage.additional_kwargs.reasoning_content === 'string'
+                ? `${aiMessage.additional_kwargs.reasoning_content}${reasoningContent}`
+                : reasoningContent;
+    };
     if (Array.isArray(message.content)) {
         for (const part of message.content) {
             if (part == null) {
@@ -178,15 +231,13 @@ function formatAssistantMessage(message) {
                     }, '');
                     content =
                         `${content}\n${part[ContentTypes.TEXT] ?? part.text ?? ''}`.trim();
-                    lastAIMessage = new AIMessage({ content });
+                    lastAIMessage = createAIMessage(content);
                     formattedMessages.push(lastAIMessage);
                     currentContent = [];
                     continue;
                 }
                 // Create a new AIMessage with this text and prepare for tool calls
-                lastAIMessage = new AIMessage({
-                    content: part.text != null ? part.text : '',
-                });
+                lastAIMessage = createAIMessage(part.text != null ? part.text : '');
                 formattedMessages.push(lastAIMessage);
             }
             else if (part.type === ContentTypes.TOOL_CALL) {
@@ -203,9 +254,12 @@ function formatAssistantMessage(message) {
                 }
                 if (!lastAIMessage) {
                     // "Heal" the payload by creating an AIMessage to precede the tool call
-                    lastAIMessage = new AIMessage({ content: '' });
+                    lastAIMessage = createAIMessage('');
                     formattedMessages.push(lastAIMessage);
                 }
+                else {
+                    attachPendingReasoningContent(lastAIMessage);
+                }
                 const tool_call = _tool_call;
                 // TODO: investigate; args as dictionary may need to be providers-or-tool-specific
                 let args = _args;
@@ -241,9 +295,11 @@ function formatAssistantMessage(message) {
             }
             else if (part.type === ContentTypes.THINK ||
                 part.type === ContentTypes.THINKING ||
+                part.type === ContentTypes.REASONING ||
                 part.type === ContentTypes.REASONING_CONTENT ||
                 part.type === 'redacted_thinking') {
                 hasReasoning = true;
+                pendingReasoningContent += extractReasoningContent(part);
                 continue;
             }
             else if (part.type === ContentTypes.ERROR ||
@@ -269,11 +325,11 @@ function formatAssistantMessage(message) {
         }, '')
             .trim();
         if (content) {
-            formattedMessages.push(new AIMessage({ content }));
+            formattedMessages.push(createAIMessage(content));
         }
     }
     else if (currentContent.length > 0) {
-        formattedMessages.push(new AIMessage({ content: currentContent }));
+        formattedMessages.push(createAIMessage(currentContent));
     }
     return formattedMessages;
 }
@@ -481,15 +537,37 @@ function extractToolNamesFromSearchOutput(output) {
     }
     return [];
 }
+/** Extracts the skillName from a skill tool_call's args (string or object). */
+function extractSkillName(args) {
+    let parsed;
+    if (typeof args === 'string') {
+        try {
+            parsed = JSON.parse(args);
+        }
+        catch {
+            /* malformed args — skip */
+        }
+    }
+    else {
+        parsed = args;
+    }
+    const name = parsed?.skillName;
+    return typeof name === 'string' && name !== '' ? name : undefined;
+}
 /**
  * Formats an array of messages for LangChain, handling tool calls and creating ToolMessage instances.
  *
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
+ *   When SkillTool is invoked, the body is injected as a HumanMessage into LangGraph state
+ *   but NOT persisted to conversation history. On follow-up runs the skill body is lost.
+ *   Pass `skills` to reconstruct the HumanMessage at the right position after each skill
+ *   ToolMessage. PRs #96 / #97.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-const formatAgentMessages = (payload, indexTokenCountMap, tools) => {
+const formatAgentMessages = (payload, indexTokenCountMap, tools, skills, options) => {
     const messages = [];
     // If indexTokenCountMap is provided, create a new map to track the updated indices
     const updatedIndexTokenCountMap = {};
@@ -529,6 +607,7 @@ const formatAgentMessages = (payload, indexTokenCountMap, tools) => {
          * - Dynamically expand the set when tool_search results are encountered
          */
         let processedMessage = message;
+        let pendingSkillNames;
         if (discoveredTools) {
             const content = message.content;
             if (content && Array.isArray(content)) {
@@ -566,6 +645,16 @@ const formatAgentMessages = (payload, indexTokenCountMap, tools) => {
                     if (discoveredTools.has(toolName)) {
                         /** Valid tool - keep it */
                         filteredContent.push(part);
+                        // Skill body reconstruction (PRs #96/#97): when a
+                        // SkillTool tool_call is present in this assistant turn, mark
+                        // the skill name so we can reconstruct the body HumanMessage
+                        // after the assistant turn has been pushed.
+                        if (toolName === Constants.SKILL_TOOL && skills?.size) {
+                            const skillName = extractSkillName(part.tool_call.args);
+                            if (skillName) {
+                                (pendingSkillNames ??= new Set()).add(skillName);
+                            }
+                        }
                     }
                     else {
                         /** Invalid tool - convert to string for context preservation */
@@ -625,12 +714,47 @@ const formatAgentMessages = (payload, indexTokenCountMap, tools) => {
                 }
             }
         }
+        // When tools filtering is off, still detect skill tool_calls for body reconstruction.
+        if (!discoveredTools && skills?.size) {
+            const content = processedMessage.content;
+            if (Array.isArray(content)) {
+                for (const part of content) {
+                    if (part.type !== ContentTypes.TOOL_CALL ||
+                        part.tool_call?.name !== Constants.SKILL_TOOL) {
+                        continue;
+                    }
+                    const skillName = extractSkillName(part.tool_call.args);
+                    if (skillName) {
+                        (pendingSkillNames ??= new Set()).add(skillName);
+                    }
+                }
+            }
+        }
         // Process the assistant message using the helper function
-        const formattedMessages = formatAssistantMessage(processedMessage);
+        const formattedMessages = formatAssistantMessage(processedMessage, {
+            preserveReasoningContent: options?.provider === Providers.DEEPSEEK,
+        });
         messages.push(...formattedMessages);
-        // Update the index mapping for this assistant message
-        // Store all indices that were created from this original message
+        // Capture index range BEFORE skill body injection so injected
+        // HumanMessages are excluded from the assistant's token distribution
+        // (PR #97 fix).
         const endMessageIndex = messages.length;
+        if (pendingSkillNames?.size) {
+            for (const skillName of pendingSkillNames) {
+                const body = skills?.get(skillName);
+                if (body) {
+                    messages.push(new HumanMessage({
+                        content: body,
+                        additional_kwargs: {
+                            role: 'user',
+                            isMeta: true,
+                            source: 'skill',
+                            skillName,
+                        },
+                    }));
+                }
+            }
+        }
         const resultIndices = [];
         for (let j = startMessageIndex; j < endMessageIndex; j++) {
             resultIndices.push(j);