@agentxjs/core 1.9.10-dev → 2.0.0

package/src/agent/__tests__/engine/internal/turnTrackerProcessor.test.ts

@@ -2,6 +2,9 @@
  * turnTrackerProcessor.test.ts - Unit tests for turn tracker processor
  *
  * Tests the pure Mealy transition function that tracks request-response turn pairs.
+ * Turn events are derived entirely from stream-layer events:
+ * - message_start → turn_request
+ * - message_stop  → turn_response
  */
 
 import { describe, it, expect, beforeEach } from "bun:test";
@@ -18,23 +21,12 @@ function createEvent(type: string, data: unknown, timestamp = Date.now()): TurnT
   return { type, data, timestamp } as TurnTrackerInput;
 }
 
-// Helper to create user message event
-function createUserMessageEvent(
-  content: string,
+// Helper to create message_start event (begins a turn)
+function createMessageStartEvent(
   messageId: string = `msg_${Date.now()}`,
   timestamp = Date.now()
 ): TurnTrackerInput {
-  return createEvent(
-    "user_message",
-    {
-      id: messageId,
-      role: "user",
-      subtype: "user",
-      content,
-      timestamp,
-    },
-    timestamp
-  );
+  return createEvent("message_start", { messageId, model: "test-model" }, timestamp);
 }
 
 // Helper to create message_stop event
@@ -59,16 +51,15 @@ describe("turnTrackerProcessor", () => {
     });
   });
 
-  describe("user_message event", () => {
+  describe("message_start event", () => {
     it("should create pending turn and emit turn_request", () => {
-      const event = createUserMessageEvent("Hello", "msg_123", 1000);
+      const event = createMessageStartEvent("msg_123", 1000);
 
       const [newState, outputs] = turnTrackerProcessor(state, event);
 
       // Should have pending turn
       expect(newState.pendingTurn).not.toBeNull();
       expect(newState.pendingTurn?.messageId).toBe("msg_123");
-      expect(newState.pendingTurn?.content).toBe("Hello");
       expect(newState.pendingTurn?.requestedAt).toBe(1000);
       expect(newState.pendingTurn?.turnId).toBeDefined();
 
@@ -76,35 +67,39 @@ describe("turnTrackerProcessor", () => {
       expect(outputs).toHaveLength(1);
       expect(outputs[0].type).toBe("turn_request");
       expect(outputs[0].data.messageId).toBe("msg_123");
-      expect(outputs[0].data.content).toBe("Hello");
       expect(outputs[0].data.timestamp).toBe(1000);
     });
 
     it("should generate unique turn IDs", () => {
-      const [state1, outputs1] = turnTrackerProcessor(
-        state,
-        createUserMessageEvent("First", "msg_1")
-      );
+      const [state1, outputs1] = turnTrackerProcessor(state, createMessageStartEvent("msg_1"));
 
       // Complete the turn
       const [state2] = turnTrackerProcessor(state1, createMessageStopEvent("end_turn"));
 
       // Start new turn
-      const [state3, outputs3] = turnTrackerProcessor(
-        state2,
-        createUserMessageEvent("Second", "msg_2")
-      );
+      const [state3, outputs3] = turnTrackerProcessor(state2, createMessageStartEvent("msg_2"));
 
       expect(outputs1[0].data.turnId).not.toBe(outputs3[0].data.turnId);
     });
 
-    it("should handle empty content", () => {
-      const event = createUserMessageEvent("", "msg_empty");
+    it("should NOT start a new turn if one is already pending", () => {
+      // Start first turn
+      const [state1, outputs1] = turnTrackerProcessor(
+        state,
+        createMessageStartEvent("msg_1", 1000)
+      );
+      expect(outputs1).toHaveLength(1);
 
-      const [newState, outputs] = turnTrackerProcessor(state, event);
+      // Second message_start while turn is pending (e.g. after tool_use)
+      const [state2, outputs2] = turnTrackerProcessor(
+        state1,
+        createMessageStartEvent("msg_2", 1500)
+      );
 
-      expect(newState.pendingTurn?.content).toBe("");
-      expect(outputs[0].data.content).toBe("");
+      // Should NOT emit another turn_request
+      expect(outputs2).toHaveLength(0);
+      // Pending turn should still be the original
+      expect(state2.pendingTurn?.messageId).toBe("msg_1");
     });
   });
 
@@ -117,7 +112,7 @@ describe("turnTrackerProcessor", () => {
           pendingTurn: {
             turnId: "turn_123",
             messageId: "msg_123",
-            content: "Test message",
+            content: "",
             requestedAt: 1000,
           },
         };
@@ -196,14 +191,23 @@ describe("turnTrackerProcessor", () => {
     });
   });
 
-  describe("assistant_message event", () => {
-    it("should not emit output (handled in message_stop)", () => {
+  describe("unhandled events", () => {
+    it("should pass through unhandled events", () => {
+      const event = createEvent("text_delta", { text: "Hello" });
+
+      const [newState, outputs] = turnTrackerProcessor(state, event);
+
+      expect(newState).toEqual(state);
+      expect(outputs).toHaveLength(0);
+    });
+
+    it("should ignore assistant_message (not a stream event)", () => {
       state = {
         ...state,
         pendingTurn: {
           turnId: "turn_123",
           messageId: "msg_123",
-          content: "Test",
+          content: "",
           requestedAt: 1000,
         },
       };
@@ -216,39 +220,22 @@ describe("turnTrackerProcessor", () => {
 
       const [newState, outputs] = turnTrackerProcessor(state, event);
 
-      // State should be unchanged
       expect(newState.pendingTurn).not.toBeNull();
-
-      // No output
-      expect(outputs).toHaveLength(0);
-    });
-  });
-
-  describe("unhandled events", () => {
-    it("should pass through unhandled events", () => {
-      const event = createEvent("text_delta", { text: "Hello" });
-
-      const [newState, outputs] = turnTrackerProcessor(state, event);
-
-      expect(newState).toEqual(state);
       expect(outputs).toHaveLength(0);
     });
   });
 
   describe("complete turn flow", () => {
-    it("should track complete turn from request to response", () => {
+    it("should track complete turn from message_start to message_stop", () => {
       const allOutputs: TurnTrackerOutput[] = [];
       let currentState = createInitialTurnTrackerState();
 
-      // User sends message at time 1000
-      const [s1, o1] = turnTrackerProcessor(
-        currentState,
-        createUserMessageEvent("What is 2+2?", "msg_1", 1000)
-      );
+      // message_start at time 1000
+      const [s1, o1] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_1", 1000));
       currentState = s1;
       allOutputs.push(...o1);
 
-      // Assistant responds, message_stop at time 2500
+      // message_stop at time 2500
       const [s2, o2] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 2500));
       currentState = s2;
       allOutputs.push(...o2);
@@ -257,7 +244,7 @@ describe("turnTrackerProcessor", () => {
 
       // turn_request
       expect(allOutputs[0].type).toBe("turn_request");
-      expect(allOutputs[0].data.content).toBe("What is 2+2?");
+      expect(allOutputs[0].data.messageId).toBe("msg_1");
 
       // turn_response
       expect(allOutputs[1].type).toBe("turn_response");
@@ -271,11 +258,8 @@ describe("turnTrackerProcessor", () => {
       const allOutputs: TurnTrackerOutput[] = [];
       let currentState = createInitialTurnTrackerState();
 
-      // User sends message
-      const [s1, o1] = turnTrackerProcessor(
-        currentState,
-        createUserMessageEvent("Search for X", "msg_1", 1000)
-      );
+      // message_start begins the turn
+      const [s1, o1] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_1", 1000));
       currentState = s1;
       allOutputs.push(...o1);
 
@@ -287,7 +271,13 @@ describe("turnTrackerProcessor", () => {
       expect(currentState.pendingTurn).not.toBeNull();
       expect(allOutputs).toHaveLength(1); // Only turn_request
 
-      // Second message_stop with end_turn - turn completes
+      // Second message_start after tool_use — should NOT start new turn (pending exists)
+      const [s2b, o2b] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_2", 2000));
+      currentState = s2b;
+      allOutputs.push(...o2b);
+      expect(allOutputs).toHaveLength(1); // Still only turn_request
+
+      // Final message_stop with end_turn - turn completes
       const [s3, o3] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 3000));
       currentState = s3;
       allOutputs.push(...o3);
@@ -303,10 +293,7 @@ describe("turnTrackerProcessor", () => {
       const allTurnIds: string[] = [];
 
       // First turn
-      const [s1, o1] = turnTrackerProcessor(
-        currentState,
-        createUserMessageEvent("First", "msg_1", 1000)
-      );
+      const [s1, o1] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_1", 1000));
       currentState = s1;
       allTurnIds.push(o1[0].data.turnId);
 
@@ -314,10 +301,7 @@ describe("turnTrackerProcessor", () => {
       currentState = s2;
 
       // Second turn
-      const [s3, o3] = turnTrackerProcessor(
-        currentState,
-        createUserMessageEvent("Second", "msg_2", 2000)
-      );
+      const [s3, o3] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_2", 2000));
       currentState = s3;
       allTurnIds.push(o3[0].data.turnId);
 
@@ -325,10 +309,7 @@ describe("turnTrackerProcessor", () => {
       currentState = s4;
 
       // Third turn
-      const [s5, o5] = turnTrackerProcessor(
-        currentState,
-        createUserMessageEvent("Third", "msg_3", 3000)
-      );
+      const [s5, o5] = turnTrackerProcessor(currentState, createMessageStartEvent("msg_3", 3000));
       currentState = s5;
       allTurnIds.push(o5[0].data.turnId);
 

package/src/agent/engine/MealyMachine.ts

@@ -19,7 +19,7 @@
  * AgentOutput (to AgentEngine/Presenter)
  * │
  * ├── StateEvent (conversation_start, conversation_end...)
- * ├── MessageEvent (assistant_message, tool_call_message...)
+ * ├── MessageEvent (assistant_message, tool_result_message...)
  * └── TurnEvent (turn_request, turn_response)
  * ```
  *

package/src/agent/engine/internal/messageAssemblerProcessor.ts

@@ -14,9 +14,8 @@
  * - message_stop
  *
  * Output Events (Message Layer):
- * - tool_call_message (Message - AI's request to call a tool)
+ * - assistant_message (Message - includes text and tool calls in content)
  * - tool_result_message (Message - tool execution result)
- * - assistant_message (Message - complete assistant response)
  */
 
 import type { Processor, ProcessorDefinition } from "../mealy";
@@ -31,12 +30,10 @@ import type {
   MessageStopEvent,
   // Output: Message events
   AssistantMessageEvent,
-  ToolCallMessageEvent,
   ToolResultMessageEvent,
   ErrorMessageEvent,
   // Message types
   AssistantMessage,
-  ToolCallMessage,
   ToolResultMessage,
   ErrorMessage,
   // Content parts
@@ -49,16 +46,22 @@ import type {
 
 /**
  * Pending content accumulator
+ *
+ * Tracks content blocks in the order they appear in the stream.
+ * Text and tool_use blocks may be interleaved.
  */
 export interface PendingContent {
   type: "text" | "tool_use";
-  index: number;
   // For text content
   textDeltas?: string[];
   // For tool use
   toolId?: string;
   toolName?: string;
   toolInputJson?: string;
+  /** True when tool_use_stop has been processed and input is fully parsed */
+  assembled?: boolean;
+  /** Parsed tool input (set at tool_use_stop time) */
+  parsedInput?: Record<string, unknown>;
 }
 
 /**
@@ -86,10 +89,10 @@ export interface MessageAssemblerState {
   messageStartTime: number | null;
 
   /**
-   * Pending content blocks being accumulated
-   * Key is the content block index
+   * Pending content blocks in stream order.
+   * Preserves the interleaved order of text and tool_use blocks.
    */
-  pendingContents: Record<number, PendingContent>;
+  pendingContents: PendingContent[];
 
   /**
    * Pending tool calls waiting for results
@@ -105,7 +108,7 @@ export function createInitialMessageAssemblerState(): MessageAssemblerState {
   return {
     currentMessageId: null,
     messageStartTime: null,
-    pendingContents: {},
+    pendingContents: [],
     pendingToolCalls: {},
   };
 }
@@ -119,12 +122,21 @@ function generateId(): string {
   return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 }
 
+/**
+ * Find last index matching a predicate (Array.findLastIndex polyfill)
+ */
+function findLastIndex<T>(arr: readonly T[], predicate: (item: T) => boolean): number {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    if (predicate(arr[i])) return i;
+  }
+  return -1;
+}
+
 /**
  * Output event types from MessageAssembler
  */
 export type MessageAssemblerOutput =
   | AssistantMessageEvent
-  | ToolCallMessageEvent
   | ToolResultMessageEvent
   | ErrorMessageEvent;
 
@@ -188,7 +200,7 @@ function handleMessageStart(
       ...state,
       currentMessageId: data.messageId,
       messageStartTime: event.timestamp,
-      pendingContents: {},
+      pendingContents: [],
     },
     [],
   ];
@@ -196,34 +208,32 @@ function handleMessageStart(
 
 /**
  * Handle text_delta event
+ *
+ * Appends to the last text block if one exists, otherwise creates a new one.
+ * This preserves the interleaved order: text after a tool_use gets its own block.
  */
 function handleTextDelta(
   state: Readonly<MessageAssemblerState>,
   event: StreamEvent
 ): [MessageAssemblerState, MessageAssemblerOutput[]] {
   const { data } = event as TextDeltaEvent;
-  const index = 0; // Text content uses index 0
-  const existingContent = state.pendingContents[index];
-
-  const pendingContent: PendingContent =
-    existingContent?.type === "text"
-      ? {
-          ...existingContent,
-          textDeltas: [...(existingContent.textDeltas || []), data.text],
-        }
-      : {
-          type: "text",
-          index,
-          textDeltas: [data.text],
-        };
+  const lastContent = state.pendingContents[state.pendingContents.length - 1];
+
+  // Append to last text block if it exists
+  if (lastContent?.type === "text") {
+    const updated = [...state.pendingContents];
+    updated[updated.length - 1] = {
+      ...lastContent,
+      textDeltas: [...(lastContent.textDeltas || []), data.text],
+    };
+    return [{ ...state, pendingContents: updated }, []];
+  }
 
+  // Create a new text block (preserves position after any preceding tool_use)
   return [
     {
       ...state,
-      pendingContents: {
-        ...state.pendingContents,
-        [index]: pendingContent,
-      },
+      pendingContents: [...state.pendingContents, { type: "text", textDeltas: [data.text] }],
     },
     [],
   ];
@@ -237,23 +247,19 @@ function handleToolUseStart(
   event: StreamEvent
 ): [MessageAssemblerState, MessageAssemblerOutput[]] {
   const { data } = event as ToolUseStartEvent;
-  const index = 1; // Tool use uses index 1
-
-  const pendingContent: PendingContent = {
-    type: "tool_use",
-    index,
-    toolId: data.toolCallId,
-    toolName: data.toolName,
-    toolInputJson: "",
-  };
 
   return [
     {
       ...state,
-      pendingContents: {
+      pendingContents: [
         ...state.pendingContents,
-        [index]: pendingContent,
-      },
+        {
+          type: "tool_use",
+          toolId: data.toolCallId,
+          toolName: data.toolName,
+          toolInputJson: "",
+        },
+      ],
     },
     [],
   ];
@@ -267,102 +273,76 @@ function handleInputJsonDelta(
   event: StreamEvent
 ): [MessageAssemblerState, MessageAssemblerOutput[]] {
   const { data } = event as InputJsonDeltaEvent;
-  const index = 1; // Tool use uses index 1
-  const existingContent = state.pendingContents[index];
 
-  if (!existingContent || existingContent.type !== "tool_use") {
-    // No pending tool_use content, ignore
+  // Find the last tool_use content in the array
+  const lastToolIndex = findLastIndex(
+    state.pendingContents,
+    (c) => c.type === "tool_use" && !c.assembled
+  );
+  if (lastToolIndex === -1) {
     return [state, []];
   }
 
-  const pendingContent: PendingContent = {
+  const existingContent = state.pendingContents[lastToolIndex];
+  const updated = [...state.pendingContents];
+  updated[lastToolIndex] = {
     ...existingContent,
     toolInputJson: (existingContent.toolInputJson || "") + data.partialJson,
   };
 
-  return [
-    {
-      ...state,
-      pendingContents: {
-        ...state.pendingContents,
-        [index]: pendingContent,
-      },
-    },
-    [],
-  ];
+  return [{ ...state, pendingContents: updated }, []];
 }
 
 /**
  * Handle tool_use_stop event
  *
- * Emits:
- * - tool_call_message (Message Event) - for UI display and tool execution
+ * Marks the tool_use entry as assembled with parsed input.
+ * The entry stays in pendingContents to preserve its position.
+ * No event is emitted — tool calls are part of the assistant message.
  */
 function handleToolUseStop(
   state: Readonly<MessageAssemblerState>,
   _event: StreamEvent
 ): [MessageAssemblerState, MessageAssemblerOutput[]] {
-  const index = 1;
-  const pendingContent = state.pendingContents[index];
-
-  if (!pendingContent || pendingContent.type !== "tool_use") {
+  // Find the last unassembled tool_use content
+  const lastToolIndex = findLastIndex(
+    state.pendingContents,
+    (c) => c.type === "tool_use" && !c.assembled
+  );
+  if (lastToolIndex === -1) {
     return [state, []];
   }
 
-  // Get tool info from pendingContent (saved during tool_use_start)
+  const pendingContent = state.pendingContents[lastToolIndex];
   const toolId = pendingContent.toolId || "";
   const toolName = pendingContent.toolName || "";
 
-  // Parse tool input JSON (accumulated during input_json_delta)
+  // Parse tool input JSON
   let toolInput: Record<string, unknown> = {};
   try {
     toolInput = pendingContent.toolInputJson ? JSON.parse(pendingContent.toolInputJson) : {};
   } catch {
-    // Failed to parse, use empty object
     toolInput = {};
   }
 
-  // Create ToolCallPart
-  const toolCall: ToolCallPart = {
-    type: "tool-call",
-    id: toolId,
-    name: toolName,
-    input: toolInput,
-  };
-
-  // Create ToolCallMessage (complete Message object)
-  // parentId links this tool call to its parent assistant message
-  const messageId = generateId();
-  const timestamp = Date.now();
-  const toolCallMessage: ToolCallMessage = {
-    id: messageId,
-    role: "assistant",
-    subtype: "tool-call",
-    toolCall,
-    timestamp,
-    parentId: state.currentMessageId || undefined,
+  // Mark as assembled in-place (preserves position)
+  const updated = [...state.pendingContents];
+  updated[lastToolIndex] = {
+    ...pendingContent,
+    assembled: true,
+    parsedInput: toolInput,
   };
 
-  // Emit tool_call_message event - data is complete Message object
-  const toolCallMessageEvent: ToolCallMessageEvent = {
-    type: "tool_call_message",
-    timestamp,
-    data: toolCallMessage,
-  };
-
-  // Remove from pending contents, add to pending tool calls
-  const { [index]: _, ...remainingContents } = state.pendingContents;
-
   return [
     {
       ...state,
-      pendingContents: remainingContents,
+      pendingContents: updated,
       pendingToolCalls: {
         ...state.pendingToolCalls,
         [toolId]: { id: toolId, name: toolName },
       },
     },
-    [toolCallMessageEvent],
+    [], // No event emitted
   ];
 }
 
@@ -427,6 +407,9 @@ function handleToolResult(
 
 /**
  * Handle message_stop event
+ *
+ * Assembles the complete AssistantMessage from pendingContents in stream order.
+ * Text and tool call parts are interleaved as they appeared in the stream.
  */
 function handleMessageStop(
   state: Readonly<MessageAssemblerState>,
@@ -438,21 +421,31 @@ function handleMessageStop(
     return [state, []];
   }
 
-  // Assemble all text content
-  const textParts: string[] = [];
-  const sortedContents = Object.values(state.pendingContents).sort((a, b) => a.index - b.index);
+  // Build content parts in stream order from pendingContents
+  const contentParts: Array<TextPart | ToolCallPart> = [];
 
-  for (const pending of sortedContents) {
+  for (const pending of state.pendingContents) {
     if (pending.type === "text" && pending.textDeltas) {
-      textParts.push(pending.textDeltas.join(""));
+      const text = pending.textDeltas.join("");
+      if (text.trim().length > 0) {
+        contentParts.push({ type: "text", text });
+      }
+    } else if (pending.type === "tool_use" && pending.assembled) {
+      contentParts.push({
+        type: "tool-call",
+        id: pending.toolId || "",
+        name: pending.toolName || "",
+        input: pending.parsedInput || {},
+      });
     }
   }
 
-  const textContent = textParts.join("");
+  const hasToolCalls = contentParts.some((p) => p.type === "tool-call");
+  const hasText = contentParts.some((p) => p.type === "text");
 
-  // Skip empty messages (but preserve pendingToolCalls if stopReason is "tool_use")
+  // Skip truly empty messages (no text AND no tool calls)
   const stopReason = data.stopReason;
-  if (!textContent || textContent.trim().length === 0) {
+  if (!hasText && !hasToolCalls) {
     const shouldPreserveToolCalls = stopReason === "tool_use";
     return [
       {
@@ -463,15 +456,7 @@ function handleMessageStop(
     ];
   }
 
-  // Create content parts (new structure uses ContentPart[])
-  const contentParts: TextPart[] = [
-    {
-      type: "text",
-      text: textContent,
-    },
-  ];
-
-  // Create AssistantMessage (complete Message object)
+  // Create AssistantMessage with interleaved content
   const timestamp = state.messageStartTime || Date.now();
   const assistantMessage: AssistantMessage = {
     id: state.currentMessageId,
@@ -481,7 +466,7 @@ function handleMessageStop(
     timestamp,
   };
 
-  // Emit AssistantMessageEvent - data is complete Message object
+  // Emit AssistantMessageEvent
   const assistantEvent: AssistantMessageEvent = {
     type: "assistant_message",
     timestamp,