fix(agent-runtime): preserve non-text content blocks in MessageConverter (#426)

jerryliang64 · claude · web-flow · commit 8c4382f33f68 · 2026-04-01T14:23:57.000+08:00
## Summary - **修复 `MessageConverter.toContentBlocks()` 有损转换问题**：原实现通过 `.filter(part => part.type === 'text')` 过滤掉了所有非 text 类型的 content block（如 `tool_use`、`tool_result`），导致基于 `@anthropic-ai/claude-agent-sdk` 实现 `execRun` 时，工具调用信息在转换后丢失 - **修复 `MessageConverter.toInputMessageObjects()` 同样的有损问题**：原实现将所有 content part 当作 text 处理，非 text 块的 `.text` 为 undefined - **扩展类型系统**：在 `ContentBlockType` 中新增 `ToolUse`、`ToolResult`，新增对应的输入/输出类型接口，并增加 `GenericContentBlock` 兜底未来新类型 - **提供 type guard 函数**：`isTextBlock()`、`isToolUseBlock()`、`isToolResultBlock()` 方便业务代码做类型收窄 ## Affected areas | 影响面 | 修复前 | 修复后 | |---|---|---| | Thread 历史消息 | tool_use 块被丢弃 | 完整保留 | | SSE 流式 delta | 不包含 tool_use 事件 | 包含所有 content block | | Run output | 缺少 tool_use block | 完整保留 | ## Test plan - [x] `toContentBlocks` 保留 tool_use content parts - [x] `toContentBlocks` 保留 tool_result content parts（含 is_error 标记） - [x] `toContentBlocks` 保留未知类型 content parts（generic 兜底） - [x] `toContentBlocks` 保持混合类型的顺序 - [x] `toMessageObject` 保留 tool_use blocks - [x] `extractFromStreamMessages` 正确提取包含 tool_use 的消息 - [x] `toInputMessageObjects` 保留 tool_use / tool_result blocks - [x] type guard 函数正确收窄类型 - [x] 所有 116 个测试通过 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **New Features** * Added support for tool use and tool result content blocks in message handling. * Message conversion now preserves all content block types instead of filtering non-text content. * **Improvements** * Enhanced type safety with expanded content block type definitions. * Improved message processing to handle mixed content ordering across text, tool use, and tool result blocks.  Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/core/agent-runtime/src/MessageConverter.ts b/core/agent-runtime/src/MessageConverter.ts
@@ -2,17 +2,35 @@ import type {
   CreateRunInput,
   MessageObject,
   MessageContentBlock,
+  TextContentBlock,
+  ToolUseContentBlock,
+  ToolResultContentBlock,
   AgentStreamMessage,
   AgentStreamMessagePayload,
+  TextInputContentPart,
 } from '@eggjs/tegg-types/agent-runtime';
 import { AgentObjectType, MessageRole, MessageStatus, ContentBlockType } from '@eggjs/tegg-types/agent-runtime';
 
+export function isTextBlock(block: MessageContentBlock): block is TextContentBlock {
+  return block.type === ContentBlockType.Text;
+}
+
+export function isToolUseBlock(block: MessageContentBlock): block is ToolUseContentBlock {
+  return block.type === ContentBlockType.ToolUse;
+}
+
+export function isToolResultBlock(block: MessageContentBlock): block is ToolResultContentBlock {
+  return block.type === ContentBlockType.ToolResult;
+}
+
 import { nowUnix, newMsgId } from './AgentStoreUtils';
 import type { RunUsage } from './RunBuilder';
 
 export class MessageConverter {
   /**
-   * Convert an AgentStreamMessage's message payload into OpenAI MessageContentBlock[].
+   * Convert an AgentStreamMessage's message payload into MessageContentBlock[].
+   * Text blocks are wrapped in { value, annotations } format.
+   * Non-text blocks (tool_use, tool_result, etc.) are passed through as-is.
    */
   static toContentBlocks(msg: AgentStreamMessagePayload): MessageContentBlock[] {
     if (!msg) return [];
@@ -21,9 +39,15 @@ export class MessageConverter {
       return [{ type: ContentBlockType.Text, text: { value: content, annotations: [] } }];
     }
     if (Array.isArray(content)) {
-      return content
-        .filter(part => part.type === ContentBlockType.Text)
-        .map(part => ({ type: ContentBlockType.Text, text: { value: part.text, annotations: [] } }));
+      return content.map(part => {
+        if (part.type === ContentBlockType.Text) {
+          return {
+            type: ContentBlockType.Text,
+            text: { value: (part as TextInputContentPart).text, annotations: [] },
+          } as MessageContentBlock;
+        }
+        return part as MessageContentBlock;
+      });
     }
     return [];
   }
@@ -123,7 +147,15 @@ export class MessageConverter {
         content:
           typeof m.content === 'string'
             ? [{ type: ContentBlockType.Text, text: { value: m.content, annotations: [] } }]
-            : m.content.map(p => ({ type: ContentBlockType.Text, text: { value: p.text, annotations: [] } })),
+            : m.content.map(p => {
+              if (p.type === ContentBlockType.Text) {
+                return {
+                  type: ContentBlockType.Text,
+                  text: { value: (p as TextInputContentPart).text, annotations: [] },
+                } as MessageContentBlock;
+              }
+              return p as MessageContentBlock;
+            }),
       }));
   }
 }
diff --git a/core/agent-runtime/test/AgentRuntime.test.ts b/core/agent-runtime/test/AgentRuntime.test.ts
@@ -9,6 +9,8 @@ import {
   MessageStatus,
   ContentBlockType,
   AgentNotFoundError, AgentConflictError } from '@eggjs/tegg-types/agent-runtime';
+
+import { isTextBlock } from '../src/MessageConverter';
 import type { RunRecord, RunObject, CreateRunInput, AgentStreamMessage } from '@eggjs/tegg-types/agent-runtime';
 
 import { AgentRuntime } from '../src/AgentRuntime';
@@ -180,6 +182,7 @@ describe('test/AgentRuntime.test.ts', () => {
       assert.equal(result.output![0].status, MessageStatus.Completed);
       const content = result.output![0].content;
       assert.equal(content[0].type, ContentBlockType.Text);
+      assert(isTextBlock(content[0]));
       assert.equal(content[0].text.value, 'Hello 1 messages');
       assert(Array.isArray(content[0].text.annotations));
       assert.equal(result.usage!.promptTokens, 10);
@@ -332,6 +335,7 @@ describe('test/AgentRuntime.test.ts', () => {
       const run = await store.getRun(result.id);
       assert.equal(run.status, RunStatus.Completed);
       const outputContent = run.output![0].content;
+      assert(isTextBlock(outputContent[0]));
       assert.equal(outputContent[0].text.value, 'Hello 1 messages');
     });
 
diff --git a/core/agent-runtime/test/MessageConverter.test.ts b/core/agent-runtime/test/MessageConverter.test.ts
@@ -1,9 +1,19 @@
 import assert from 'node:assert';
 
-import type { AgentStreamMessage, AgentStreamMessagePayload } from '@eggjs/tegg-types/agent-runtime';
-import { MessageRole, MessageStatus, AgentObjectType, ContentBlockType } from '@eggjs/tegg-types/agent-runtime';
+import type {
+  AgentStreamMessage,
+  AgentStreamMessagePayload,
+  ToolUseContentBlock,
+  ToolResultContentBlock,
+} from '@eggjs/tegg-types/agent-runtime';
+import {
+  MessageRole,
+  MessageStatus,
+  AgentObjectType,
+  ContentBlockType,
+} from '@eggjs/tegg-types/agent-runtime';
 
-import { MessageConverter } from '../src/MessageConverter';
+import { MessageConverter, isTextBlock, isToolUseBlock, isToolResultBlock } from '../src/MessageConverter';
 
 describe('test/MessageConverter.test.ts', () => {
   describe('toContentBlocks', () => {
@@ -17,6 +27,7 @@ describe('test/MessageConverter.test.ts', () => {
       const result = MessageConverter.toContentBlocks(payload);
       assert.equal(result.length, 1);
       assert.equal(result[0].type, ContentBlockType.Text);
+      assert(isTextBlock(result[0]));
       assert.equal(result[0].text.value, 'hello world');
       assert.deepStrictEqual(result[0].text.annotations, []);
     });
@@ -30,20 +41,89 @@ describe('test/MessageConverter.test.ts', () => {
       };
       const result = MessageConverter.toContentBlocks(payload);
       assert.equal(result.length, 2);
+      assert(isTextBlock(result[0]));
       assert.equal(result[0].text.value, 'part1');
+      assert(isTextBlock(result[1]));
       assert.equal(result[1].text.value, 'part2');
     });
 
-    it('should filter out non-text content parts', () => {
-      const payload: AgentStreamMessagePayload = {
+    it('should preserve tool_use content parts', () => {
+      const payload = {
         content: [
-          { type: 'text', text: 'keep' },
-          { type: 'image' as 'text', text: 'discard' },
+          { type: 'text', text: 'Let me call a tool' },
+          { type: 'tool_use', id: 'toolu_123', name: 'get_weather', input: { city: 'beijing' } },
         ],
-      };
+      } as unknown as AgentStreamMessagePayload;
+      const result = MessageConverter.toContentBlocks(payload);
+      assert.equal(result.length, 2);
+
+      assert(isTextBlock(result[0]));
+      assert.equal(result[0].text.value, 'Let me call a tool');
+
+      assert(isToolUseBlock(result[1]));
+      assert.equal(result[1].id, 'toolu_123');
+      assert.equal(result[1].name, 'get_weather');
+      assert.deepStrictEqual(result[1].input, { city: 'beijing' });
+    });
+
+    it('should preserve tool_result content parts', () => {
+      const payload = {
+        content: [
+          { type: 'tool_result', tool_use_id: 'toolu_123', content: 'sunny, 25°C' },
+        ],
+      } as unknown as AgentStreamMessagePayload;
+      const result = MessageConverter.toContentBlocks(payload);
+      assert.equal(result.length, 1);
+
+      assert(isToolResultBlock(result[0]));
+      assert.equal(result[0].tool_use_id, 'toolu_123');
+      assert.equal(result[0].content, 'sunny, 25°C');
+    });
+
+    it('should preserve tool_result with is_error flag', () => {
+      const payload = {
+        content: [
+          { type: 'tool_result', tool_use_id: 'toolu_456', content: 'Tool not found', is_error: true },
+        ],
+      } as unknown as AgentStreamMessagePayload;
+      const result = MessageConverter.toContentBlocks(payload);
+      assert.equal(result.length, 1);
+
+      assert(isToolResultBlock(result[0]));
+      assert.equal((result[0] as ToolResultContentBlock).is_error, true);
+    });
+
+    it('should preserve unknown content types as generic blocks', () => {
+      const payload = {
+        content: [
+          { type: 'thinking', thinking: 'let me think...' },
+        ],
+      } as unknown as AgentStreamMessagePayload;
       const result = MessageConverter.toContentBlocks(payload);
       assert.equal(result.length, 1);
-      assert.equal(result[0].text.value, 'keep');
+      assert.equal(result[0].type, 'thinking');
+      assert.equal((result[0] as any).thinking, 'let me think...');
+    });
+
+    it('should preserve mixed content types in order', () => {
+      const payload = {
+        content: [
+          { type: 'text', text: 'I will search for you' },
+          { type: 'tool_use', id: 'toolu_1', name: 'search', input: { q: 'test' } },
+          { type: 'text', text: 'Here are the results' },
+        ],
+      } as unknown as AgentStreamMessagePayload;
+      const result = MessageConverter.toContentBlocks(payload);
+      assert.equal(result.length, 3);
+
+      assert(isTextBlock(result[0]));
+      assert.equal(result[0].text.value, 'I will search for you');
+
+      assert(isToolUseBlock(result[1]));
+      assert.equal(result[1].name, 'search');
+
+      assert(isTextBlock(result[2]));
+      assert.equal(result[2].text.value, 'Here are the results');
     });
 
     it('should return empty array for non-string non-array content', () => {
@@ -66,6 +146,7 @@ describe('test/MessageConverter.test.ts', () => {
       assert.equal(typeof msg.createdAt, 'number');
       const content = msg.content;
       assert.equal(content.length, 1);
+      assert(isTextBlock(content[0]));
       assert.equal(content[0].text.value, 'reply');
     });
 
@@ -74,6 +155,20 @@ describe('test/MessageConverter.test.ts', () => {
       const msg = MessageConverter.toMessageObject(payload);
       assert.equal(msg.runId, undefined);
     });
+
+    it('should preserve tool_use blocks in message object', () => {
+      const payload = {
+        content: [
+          { type: 'text', text: 'calling tool' },
+          { type: 'tool_use', id: 'toolu_1', name: 'search', input: { q: 'test' } },
+        ],
+      } as unknown as AgentStreamMessagePayload;
+      const msg = MessageConverter.toMessageObject(payload, 'run_1');
+      assert.equal(msg.content.length, 2);
+      assert(isTextBlock(msg.content[0]));
+      assert(isToolUseBlock(msg.content[1]));
+      assert.equal((msg.content[1] as ToolUseContentBlock).name, 'search');
+    });
   });
 
   describe('createStreamMessage', () => {
@@ -99,14 +194,34 @@ describe('test/MessageConverter.test.ts', () => {
       const { output, usage } = MessageConverter.extractFromStreamMessages(messages, 'run_1');
 
       assert.equal(output.length, 2);
+      assert(isTextBlock(output[0].content[0]));
       assert.equal(output[0].content[0].text.value, 'chunk1');
+      assert(isTextBlock(output[1].content[0]));
       assert.equal(output[1].content[0].text.value, 'chunk2');
       assert.ok(usage);
       assert.equal(usage.promptTokens, 10);
       assert.equal(usage.completionTokens, 13);
       assert.equal(usage.totalTokens, 23);
     });
 
+    it('should extract messages with tool_use content', () => {
+      const messages: AgentStreamMessage[] = [
+        {
+          message: {
+            content: [
+              { type: 'text', text: 'let me search' },
+              { type: 'tool_use', id: 'toolu_1', name: 'search', input: { q: 'test' } },
+            ] as any,
+          },
+        },
+      ];
+      const { output } = MessageConverter.extractFromStreamMessages(messages, 'run_1');
+      assert.equal(output.length, 1);
+      assert.equal(output[0].content.length, 2);
+      assert(isTextBlock(output[0].content[0]));
+      assert(isToolUseBlock(output[0].content[1]));
+    });
+
     it('should return undefined usage when no usage info', () => {
       const messages: AgentStreamMessage[] = [{ message: { content: 'data' } }];
       const { output, usage } = MessageConverter.extractFromStreamMessages(messages);
@@ -143,6 +258,7 @@ describe('test/MessageConverter.test.ts', () => {
       assert.equal(result[1].role, MessageRole.Assistant);
 
       const content0 = result[0].content;
+      assert(isTextBlock(content0[0]));
       assert.equal(content0[0].text.value, 'hi');
     });
 
@@ -169,14 +285,79 @@ describe('test/MessageConverter.test.ts', () => {
       const result = MessageConverter.toInputMessageObjects(messages);
       const content = result[0].content;
       assert.equal(content.length, 2);
+      assert(isTextBlock(content[0]));
       assert.equal(content[0].text.value, 'part1');
+      assert(isTextBlock(content[1]));
       assert.equal(content[1].text.value, 'part2');
     });
 
+    it('should preserve tool_use blocks in input messages', () => {
+      const messages = [
+        {
+          role: MessageRole.Assistant as MessageRole,
+          content: [
+            { type: 'text', text: 'I will search for you' },
+            { type: 'tool_use', id: 'toolu_1', name: 'search', input: { q: 'test' } },
+          ] as any,
+        },
+      ];
+      const result = MessageConverter.toInputMessageObjects(messages);
+      assert.equal(result[0].content.length, 2);
+      assert(isTextBlock(result[0].content[0]));
+      assert.equal(result[0].content[0].text.value, 'I will search for you');
+      assert(isToolUseBlock(result[0].content[1]));
+      assert.equal((result[0].content[1] as ToolUseContentBlock).name, 'search');
+    });
+
+    it('should preserve tool_result blocks in input messages', () => {
+      const messages = [
+        {
+          role: MessageRole.User as MessageRole,
+          content: [
+            { type: 'tool_result', tool_use_id: 'toolu_1', content: 'search result here' },
+          ] as any,
+        },
+      ];
+      const result = MessageConverter.toInputMessageObjects(messages);
+      assert.equal(result[0].content.length, 1);
+      assert(isToolResultBlock(result[0].content[0]));
+      assert.equal((result[0].content[0] as ToolResultContentBlock).tool_use_id, 'toolu_1');
+      assert.equal((result[0].content[0] as ToolResultContentBlock).content, 'search result here');
+    });
+
     it('should work without threadId', () => {
       const messages = [{ role: MessageRole.User as MessageRole, content: 'hi' }];
       const result = MessageConverter.toInputMessageObjects(messages);
       assert.equal(result[0].threadId, undefined);
     });
   });
+
+  describe('type guards', () => {
+    it('isTextBlock should narrow to TextContentBlock', () => {
+      const block = { type: ContentBlockType.Text, text: { value: 'hello', annotations: [] } };
+      assert(isTextBlock(block));
+      assert.equal(block.text.value, 'hello');
+    });
+
+    it('isToolUseBlock should narrow to ToolUseContentBlock', () => {
+      const block = { type: ContentBlockType.ToolUse, id: 'toolu_1', name: 'search', input: { q: 'test' } };
+      assert(isToolUseBlock(block));
+      assert.equal(block.name, 'search');
+    });
+
+    it('isToolResultBlock should narrow to ToolResultContentBlock', () => {
+      const block = { type: ContentBlockType.ToolResult, tool_use_id: 'toolu_1', content: 'result' };
+      assert(isToolResultBlock(block));
+      assert.equal(block.tool_use_id, 'toolu_1');
+    });
+
+    it('type guards should return false for non-matching blocks', () => {
+      const textBlock = { type: ContentBlockType.Text, text: { value: 'hi', annotations: [] } };
+      const toolUseBlock = { type: ContentBlockType.ToolUse, id: 'id', name: 'n', input: {} };
+
+      assert(!isToolUseBlock(textBlock));
+      assert(!isToolResultBlock(textBlock));
+      assert(!isTextBlock(toolUseBlock));
+    });
+  });
 });
diff --git a/core/tegg/agent.ts b/core/tegg/agent.ts
@@ -18,10 +18,19 @@ export type {
   MessageObject,
   InputMessage,
   InputContentPart,
+  TextInputContentPart,
+  ToolUseInputContentPart,
+  ToolResultInputContentPart,
+  GenericInputContentPart,
   MessageContentBlock,
   TextContentBlock,
+  ToolUseContentBlock,
+  ToolResultContentBlock,
+  GenericContentBlock,
   MessageDeltaObject,
   AgentRunConfig,
   AgentRunUsage,
   RunStatus,
 } from '@eggjs/agent-runtime';
+
+export { isTextBlock, isToolUseBlock, isToolResultBlock } from '@eggjs/agent-runtime';
diff --git a/core/types/agent-runtime/AgentMessage.ts b/core/types/agent-runtime/AgentMessage.ts
