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

package/src/messages/format.ts

@@ -274,18 +274,90 @@ export const formatFromLangChain = (
   };
 };
 
+/* DeepSeek reasoning roundtrip: when active, accumulate reasoning text
+ * from THINK/THINKING/REASONING blocks and attach to the next AI message
+ * as `additional_kwargs.reasoning_content` so it survives multi-turn
+ * replays through the OpenAI-compatible DeepSeek API. Upstream PR #136. */
+interface FormatAssistantMessageOptions {
+  preserveReasoningContent?: boolean;
+}
+
+interface FormatAgentMessagesOptions {
+  provider?: Providers;
+}
+
+function extractReasoningContent(
+  part: MessageContentComplex | undefined | null
+): string {
+  if (part == null || typeof part !== 'object') return '';
+  if (part.type === ContentTypes.THINK) {
+    const think = (part as ReasoningContentText).think;
+    return typeof think === 'string' ? think : '';
+  }
+  if (part.type === ContentTypes.THINKING) {
+    const thinking = (part as { thinking?: string }).thinking;
+    return typeof thinking === 'string' ? thinking : '';
+  }
+  if (part.type === ContentTypes.REASONING) {
+    const reasoning = (part as { reasoning?: string }).reasoning;
+    return typeof reasoning === 'string' ? reasoning : '';
+  }
+  if (part.type === ContentTypes.REASONING_CONTENT) {
+    /* Bedrock/Google nested shape: { reasoningContent: { text: ... } } */
+    const nested = (part as { reasoningContent?: { text?: string } })
+      .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: Partial<TMessage>
+  message: Partial<TMessage>,
+  options?: FormatAssistantMessageOptions
 ): Array<AIMessage | ToolMessage> {
   const formattedMessages: Array<AIMessage | ToolMessage> = [];
   let currentContent: MessageContentComplex[] = [];
   let lastAIMessage: AIMessage | null = null;
   let hasReasoning = false;
+  let pendingReasoningContent = '';
+  const shouldPreserveReasoningContent =
+    options?.preserveReasoningContent === true;
+
+  const takePendingReasoningContent = (): string | undefined => {
+    if (!shouldPreserveReasoningContent || !pendingReasoningContent) {
+      return undefined;
+    }
+    const reasoningContent = pendingReasoningContent;
+    pendingReasoningContent = '';
+    return reasoningContent;
+  };
+
+  const createAIMessage = (
+    content: string | MessageContentComplex[]
+  ): AIMessage => {
+    const reasoningContent = takePendingReasoningContent();
+    return new AIMessage({
+      content,
+      ...(reasoningContent != null && {
+        additional_kwargs: { reasoning_content: reasoningContent },
+      }),
+    });
+  };
+
+  const attachPendingReasoningContent = (aiMessage: AIMessage): void => {
+    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 as Array<
@@ -308,15 +380,15 @@ function formatAssistantMessage(
           }, '');
           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) {
         // Skip malformed tool call entries without tool_call property
@@ -341,8 +413,10 @@ function formatAssistantMessage(
 
         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: ToolCallPart = _tool_call;
@@ -385,10 +459,12 @@ function formatAssistantMessage(
       } 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 ||
@@ -418,10 +494,10 @@ function formatAssistantMessage(
       .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;
@@ -689,18 +765,41 @@ function extractToolNamesFromSearchOutput(output: string): string[] {
   return [];
 }
 
+/** Extracts the skillName from a skill tool_call's args (string or object). */
+function extractSkillName(args: unknown): string | undefined {
+  let parsed: Record<string, unknown> | undefined;
+  if (typeof args === 'string') {
+    try {
+      parsed = JSON.parse(args) as Record<string, unknown>;
+    } catch {
+      /* malformed args — skip */
+    }
+  } else {
+    parsed = args as Record<string, unknown> | undefined;
+  }
+  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. Upstream PRs #96 / #97.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
 export const formatAgentMessages = (
   payload: TPayload,
   indexTokenCountMap?: Record<number, number | undefined>,
-  tools?: Set<string>
+  tools?: Set<string>,
+  skills?: Map<string, string>,
+  options?: FormatAgentMessagesOptions
 ): {
   messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
   indexTokenCountMap?: Record<number, number>;
@@ -753,6 +852,7 @@ export const formatAgentMessages = (
      * - Dynamically expand the set when tool_search results are encountered
      */
     let processedMessage = message;
+    let pendingSkillNames: Set<string> | undefined;
     if (discoveredTools) {
       const content = message.content;
       if (content && Array.isArray(content)) {
@@ -803,6 +903,16 @@ export const formatAgentMessages = (
           if (discoveredTools.has(toolName)) {
             /** Valid tool - keep it */
             filteredContent.push(part);
+            // Skill body reconstruction (upstream 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 */
             if (
@@ -878,13 +988,55 @@ export const formatAgentMessages = (
       }
     }
 
+    // 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
+    // (upstream 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);

package/src/messages/formatAgentMessages.skills.test.ts

@@ -0,0 +1,413 @@
+import { HumanMessage } from '@langchain/core/messages';
+import type { TPayload } from '@/types';
+import { formatAgentMessages } from './format';
+import { ContentTypes, Constants } from '@/common';
+
+/** Helper to build a skill tool_call content part */
+function skillToolCall(
+  id: string,
+  skillName: string,
+  output = 'Skill loaded.'
+): Record<string, unknown> {
+  return {
+    type: ContentTypes.TOOL_CALL,
+    tool_call: {
+      id,
+      name: Constants.SKILL_TOOL,
+      args: JSON.stringify({ skillName }),
+      output,
+    },
+  };
+}
+
+describe('formatAgentMessages skill body reconstruction', () => {
+  const skillBodies = new Map([
+    ['pdf-analyzer', '# PDF Analyzer\nAnalyze PDF files step by step.'],
+    ['code-review', '# Code Review\nReview the code for issues.'],
+  ]);
+
+  describe('with discoveredTools (tools filtering active)', () => {
+    const tools = new Set([Constants.SKILL_TOOL, 'web_search']);
+
+    it('reconstructs HumanMessage after skill ToolMessage', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Analyze this PDF' },
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: ContentTypes.TEXT,
+              [ContentTypes.TEXT]: "I'll invoke the skill.",
+              tool_call_ids: ['call_1'],
+            },
+            skillToolCall('call_1', 'pdf-analyzer'),
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      // user, AI, ToolMessage, injected HumanMessage
+      expect(messages.length).toBeGreaterThanOrEqual(4);
+      const last = messages[messages.length - 1];
+      expect(last).toBeInstanceOf(HumanMessage);
+      expect(last.content).toBe(
+        '# PDF Analyzer\nAnalyze PDF files step by step.'
+      );
+      expect((last as HumanMessage).additional_kwargs.source).toBe('skill');
+      expect((last as HumanMessage).additional_kwargs.skillName).toBe(
+        'pdf-analyzer'
+      );
+      expect((last as HumanMessage).additional_kwargs.isMeta).toBe(true);
+    });
+
+    it('does NOT inject body when skill tool is not in discoveredTools', () => {
+      const restrictedTools = new Set(['web_search']); // skill NOT allowed
+      const payload: TPayload = [
+        { role: 'user', content: 'Analyze this' },
+        {
+          role: 'assistant',
+          content: [skillToolCall('call_1', 'pdf-analyzer')],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        restrictedTools,
+        skillBodies
+      );
+
+      const humanMessages = messages.filter((m) => m instanceof HumanMessage);
+      // Only the user message, no injected skill body
+      expect(humanMessages).toHaveLength(1);
+    });
+
+    it('does not inject when skill name is not in skills Map', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello' },
+        {
+          role: 'assistant',
+          content: [skillToolCall('call_1', 'unknown-skill')],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const humanMessages = messages.filter((m) => m instanceof HumanMessage);
+      expect(humanMessages).toHaveLength(1); // only the user message
+    });
+  });
+
+  describe('without discoveredTools (no tools filtering)', () => {
+    it('reconstructs HumanMessage when skills Map provided', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Review my code' },
+        {
+          role: 'assistant',
+          content: [skillToolCall('call_1', 'code-review')],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        undefined,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(1);
+      expect(injected[0].content).toBe(
+        '# Code Review\nReview the code for issues.'
+      );
+    });
+
+    it('no injection when skills Map is undefined', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello' },
+        {
+          role: 'assistant',
+          content: [skillToolCall('call_1', 'pdf-analyzer')],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        undefined,
+        undefined
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(0);
+    });
+
+    it('no injection when skills Map is empty', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello' },
+        {
+          role: 'assistant',
+          content: [skillToolCall('call_1', 'pdf-analyzer')],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        undefined,
+        new Map()
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(0);
+    });
+  });
+
+  describe('extractSkillName edge cases', () => {
+    const tools = new Set([Constants.SKILL_TOOL]);
+
+    it('handles object args (not stringified)', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Go' },
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: ContentTypes.TOOL_CALL,
+              tool_call: {
+                id: 'call_1',
+                name: Constants.SKILL_TOOL,
+                args: { skillName: 'pdf-analyzer' }, // object, not string
+                output: 'Loaded.',
+              },
+            },
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(1);
+    });
+
+    it('gracefully skips malformed JSON args', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Go' },
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: ContentTypes.TOOL_CALL,
+              tool_call: {
+                id: 'call_1',
+                name: Constants.SKILL_TOOL,
+                args: '{bad json',
+                output: 'Loaded.',
+              },
+            },
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(0); // gracefully skipped
+    });
+
+    it('skips empty skillName', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Go' },
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: ContentTypes.TOOL_CALL,
+              tool_call: {
+                id: 'call_1',
+                name: Constants.SKILL_TOOL,
+                args: JSON.stringify({ skillName: '' }),
+                output: 'Loaded.',
+              },
+            },
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(0);
+    });
+  });
+
+  describe('deduplication', () => {
+    const tools = new Set([Constants.SKILL_TOOL]);
+
+    it('injects body only once when same skill invoked twice in one message', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Go' },
+        {
+          role: 'assistant',
+          content: [
+            skillToolCall('call_1', 'pdf-analyzer'),
+            skillToolCall('call_2', 'pdf-analyzer'),
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(1);
+    });
+
+    it('injects body for each distinct skill invoked', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Go' },
+        {
+          role: 'assistant',
+          content: [
+            skillToolCall('call_1', 'pdf-analyzer'),
+            skillToolCall('call_2', 'code-review'),
+          ],
+        },
+      ];
+
+      const { messages } = formatAgentMessages(
+        payload,
+        undefined,
+        tools,
+        skillBodies
+      );
+
+      const injected = messages.filter(
+        (m) =>
+          m instanceof HumanMessage &&
+          (m as HumanMessage).additional_kwargs?.source === 'skill'
+      );
+      expect(injected).toHaveLength(2);
+      const names = injected.map(
+        (m) => (m as HumanMessage).additional_kwargs.skillName
+      );
+      expect(names).toContain('pdf-analyzer');
+      expect(names).toContain('code-review');
+    });
+  });
+
+  describe('indexTokenCountMap distribution', () => {
+    const tools = new Set([Constants.SKILL_TOOL]);
+
+    it('excludes injected HumanMessages from assistant token distribution', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Analyze this' },
+        {
+          role: 'assistant',
+          content: [
+            {
+              type: ContentTypes.TEXT,
+              [ContentTypes.TEXT]: 'Invoking skill.',
+              tool_call_ids: ['call_1'],
+            },
+            skillToolCall('call_1', 'pdf-analyzer'),
+          ],
+        },
+      ];
+
+      const inputTokenMap: Record<number, number | undefined> = {
+        0: 100, // user message
+        1: 500, // assistant message
+      };
+
+      const { messages, indexTokenCountMap } = formatAgentMessages(
+        payload,
+        inputTokenMap,
+        tools,
+        skillBodies
+      );
+
+      // There should be messages: user, AI, ToolMessage, injected HumanMessage
+      expect(messages.length).toBeGreaterThanOrEqual(4);
+      const lastMsg = messages[messages.length - 1];
+      expect(lastMsg).toBeInstanceOf(HumanMessage);
+      expect((lastMsg as HumanMessage).additional_kwargs.source).toBe('skill');
+
+      // Token map must be defined when input was provided
+      expect(indexTokenCountMap).toBeDefined();
+
+      // The injected HumanMessage's index should NOT be in the token map
+      const injectedIndex = messages.length - 1;
+      expect(indexTokenCountMap![injectedIndex]).toBeUndefined();
+
+      // The assistant's 500 tokens should be distributed only across
+      // the AI + ToolMessage, NOT the injected HumanMessage
+      let assistantTotal = 0;
+      for (const [idx, count] of Object.entries(indexTokenCountMap!)) {
+        if (Number(idx) > 0 && Number(idx) < injectedIndex) {
+          assistantTotal += count ?? 0;
+        }
+      }
+      expect(assistantTotal).toBe(500);
+    });
+  });
+});