@agentxjs/core 1.9.10-dev → 2.0.1

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

@@ -14,51 +14,54 @@
  * - 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";
 import type {
-  // Input: StreamEvent (from agent layer)
-  StreamEvent,
-  MessageStartEvent,
-  TextDeltaEvent,
-  ToolUseStartEvent,
-  InputJsonDeltaEvent,
-  ToolResultEvent,
-  MessageStopEvent,
-  // Output: Message events
-  AssistantMessageEvent,
-  ToolCallMessageEvent,
-  ToolResultMessageEvent,
-  ErrorMessageEvent,
   // Message types
   AssistantMessage,
-  ToolCallMessage,
-  ToolResultMessage,
+  // Output: Message events
+  AssistantMessageEvent,
   ErrorMessage,
+  ErrorMessageEvent,
+  InputJsonDeltaEvent,
+  MessageStartEvent,
+  MessageStopEvent,
+  // Input: StreamEvent (from agent layer)
+  StreamEvent,
+  TextDeltaEvent,
   // Content parts
   TextPart,
   ToolCallPart,
+  ToolResultEvent,
+  ToolResultMessage,
+  ToolResultMessageEvent,
   ToolResultPart,
+  ToolUseStartEvent,
 } from "../../types";
+import type { Processor, ProcessorDefinition } from "../mealy";
 
 // ===== State Types =====
 
 /**
  * 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,
+  // Mark as assembled in-place (preserves position)
+  const updated = [...state.pendingContents];
+  updated[lastToolIndex] = {
+    ...pendingContent,
+    assembled: true,
+    parsedInput: 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,
-  };
-
-  // 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,

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

@@ -18,25 +18,25 @@
  * - tool_executing
  */
 
-import type { Processor, ProcessorDefinition } from "../mealy";
+import { createLogger } from "commonxjs/logger";
 import type {
+  ConversationEndEvent,
+  ConversationInterruptedEvent,
+  ConversationRespondingEvent,
+  // Output: State events
+  ConversationStartEvent,
   // Base type
   EngineEvent,
-  // Input: StreamEvent (from agent layer)
-  StreamEvent,
+  ErrorOccurredEvent,
   MessageStartEvent,
   MessageStopEvent,
-  ToolUseStartEvent,
-  // Output: State events
-  ConversationStartEvent,
-  ConversationRespondingEvent,
-  ConversationEndEvent,
-  ConversationInterruptedEvent,
-  ToolPlannedEvent,
+  // Input: StreamEvent (from agent layer)
+  StreamEvent,
   ToolExecutingEvent,
-  ErrorOccurredEvent,
+  ToolPlannedEvent,
+  ToolUseStartEvent,
 } from "../../types";
-import { createLogger } from "commonxjs/logger";
+import type { Processor, ProcessorDefinition } from "../mealy";
 
 const logger = createLogger("engine/stateEventProcessor");
 
@@ -50,9 +50,7 @@ const logger = createLogger("engine/stateEventProcessor");
  *
  * Currently empty - no context needed as all information comes from events.
  */
-export interface StateEventProcessorContext {
-  // Empty - all information comes from events
-}
+export type StateEventProcessorContext = {};
 
 /**
  * Initial context factory for StateEventProcessor

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

@@ -2,30 +2,28 @@
  * turnTrackerProcessor
  *
  * Pure Mealy transition function that tracks request-response turn pairs.
+ * Derives turn events entirely from stream-layer events (no external injection).
  *
- * Input Events:
- * - user_message (Message Layer)
- * - message_stop (Stream Layer - contains stop reason)
- * - assistant_message (Message Layer)
+ * Input Events (Stream Layer):
+ * - message_start → emit turn_request (a new turn begins)
+ * - message_stop  → emit turn_response (turn completes, based on stop reason)
  *
  * Output Events (Turn Layer):
  * - turn_request
  * - turn_response
  */
 
-import type { Processor, ProcessorDefinition } from "../mealy";
 import type {
-  // Input: combined stream and message events
-  StreamEvent,
-  AgentMessageEvent,
+  MessageStartEvent,
   MessageStopEvent,
-  UserMessageEvent,
+  StreamEvent,
+  // Data types
+  TokenUsage,
   // Output: Turn events
   TurnRequestEvent,
   TurnResponseEvent,
-  // Data types
-  TokenUsage,
 } from "../../types";
+import type { Processor, ProcessorDefinition } from "../mealy";
 
 // ===== State Types =====
 
@@ -88,9 +86,9 @@ export type TurnTrackerOutput = TurnRequestEvent | TurnResponseEvent;
 
 /**
  * Input event types for TurnTracker
- * Accepts both Stream and Message layer events
+ * Only stream-layer events — turn events are derived, not injected.
  */
-export type TurnTrackerInput = StreamEvent | AgentMessageEvent;
+export type TurnTrackerInput = StreamEvent;
 
 /**
  * turnTrackerProcessor
@@ -104,39 +102,37 @@ export const turnTrackerProcessor: Processor<
   TurnTrackerOutput
 > = (state, input): [TurnTrackerState, TurnTrackerOutput[]] => {
   switch (input.type) {
-    case "user_message":
-      return handleUserMessage(state, input as AgentMessageEvent);
+    case "message_start":
+      return handleMessageStart(state, input as MessageStartEvent);
 
     case "message_stop":
       return handleMessageStop(state, input as StreamEvent);
 
-    case "assistant_message":
-      // Turn completion is handled in message_stop
-      // This handler is kept for potential future use
-      return [state, []];
-
     default:
       return [state, []];
   }
 };
 
 /**
- * Handle user_message event
+ * Handle message_start event — a new turn begins
  */
-function handleUserMessage(
+function handleMessageStart(
   state: Readonly<TurnTrackerState>,
-  event: AgentMessageEvent
+  event: MessageStartEvent
 ): [TurnTrackerState, TurnTrackerOutput[]] {
-  const { data } = event as UserMessageEvent;
-  const turnId = generateId();
+  // If there's already a pending turn (e.g. tool_use didn't end the turn),
+  // don't start a new one
+  if (state.pendingTurn) {
+    return [state, []];
+  }
 
-  // Extract content as string (UserMessage.content can be string or array)
-  const contentText = typeof data.content === "string" ? data.content : "";
+  const turnId = generateId();
+  const messageId = event.data.messageId ?? "";
 
   const pendingTurn: PendingTurn = {
     turnId,
-    messageId: data.id,
-    content: contentText,
+    messageId,
+    content: "",
     requestedAt: event.timestamp,
   };
 
@@ -145,8 +141,8 @@ function handleUserMessage(
     timestamp: Date.now(),
     data: {
       turnId,
-      messageId: data.id,
-      content: contentText,
+      messageId,
+      content: "",
       timestamp: event.timestamp,
     },
   };

package/src/agent/engine/mealy/Mealy.ts

@@ -31,10 +31,10 @@
  * ```
  */
 
+import { createLogger } from "commonxjs/logger";
 import type { Processor } from "./Processor";
-import type { Store } from "./Store";
 import type { Sink, SinkDefinition } from "./Sink";
-import { createLogger } from "commonxjs/logger";
+import type { Store } from "./Store";
 
 const logger = createLogger("engine/Mealy");
 

package/src/agent/engine/mealy/combinators.ts

@@ -28,13 +28,11 @@ import type { Processor } from "./Processor";
  * });
  * ```
  */
-export function combineProcessors<
-  TState extends Record<string, unknown>,
-  TInput,
-  TOutput,
->(processors: {
-  [K in keyof TState]: Processor<TState[K], TInput, TOutput>;
-}): Processor<TState, TInput, TOutput> {
+export function combineProcessors<TState extends Record<string, unknown>, TInput, TOutput>(
+  processors: {
+    [K in keyof TState]: Processor<TState[K], TInput, TOutput>;
+  }
+): Processor<TState, TInput, TOutput> {
   return (state: Readonly<TState>, event: TInput): [TState, TOutput[]] => {
     const newState = {} as TState;
     const allOutputs: TOutput[] = [];
@@ -55,9 +53,11 @@ export function combineProcessors<
 /**
  * combineInitialStates - Helper to create initial state for combined processors
  */
-export function combineInitialStates<TState extends Record<string, unknown>>(initialStates: {
-  [K in keyof TState]: () => TState[K];
-}): () => TState {
+export function combineInitialStates<TState extends Record<string, unknown>>(
+  initialStates: {
+    [K in keyof TState]: () => TState[K];
+  }
+): () => TState {
   return () => {
     const state = {} as TState;
     for (const key in initialStates) {

package/src/agent/engine/mealy/index.ts

@@ -16,30 +16,28 @@
 
 // ===== Core Components =====
 
-// Source - Input (input adapter)
-export { type Source, type SourceDefinition } from "./Source";
-
 // Processor - Processing (pure Mealy transition function)
-export { type Processor, type ProcessorResult, type ProcessorDefinition } from "./Processor";
-
+export type { Processor, ProcessorDefinition, ProcessorResult } from "./Processor";
 // Sink - Output (output adapter)
-export { type Sink, type SinkDefinition } from "./Sink";
+export type { Sink, SinkDefinition } from "./Sink";
+// Source - Input (input adapter)
+export type { Source, SourceDefinition } from "./Source";
 
 // Store - State storage
-export { type Store, MemoryStore } from "./Store";
+export { MemoryStore, type Store } from "./Store";
 
 // ===== Mealy Runtime =====
 
-export { Mealy, createMealy, type MealyConfig, type ProcessResult } from "./Mealy";
+export { createMealy, Mealy, type MealyConfig, type ProcessResult } from "./Mealy";
 
 // ===== Combinators =====
 
 export {
-  combineProcessors,
-  combineInitialStates,
   chainProcessors,
+  combineInitialStates,
+  combineProcessors,
   filterProcessor,
+  identityProcessor,
   mapOutput,
   withLogging,
-  identityProcessor,
 } from "./combinators";