@agentxjs/core 1.9.10-dev → 2.0.1

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

@@ -4,13 +4,13 @@
  * Tests the stateless event transformer: Stream Events -> State Events
  */
 
-import { describe, it, expect, beforeEach } from "bun:test";
+import { beforeEach, describe, expect, it } from "bun:test";
 import {
-  stateEventProcessor,
   createInitialStateEventProcessorContext,
   type StateEventProcessorContext,
   type StateEventProcessorInput,
   type StateEventProcessorOutput,
+  stateEventProcessor,
 } from "../../../engine/internal/stateEventProcessor";
 
 // Helper to create test events
@@ -67,7 +67,7 @@ describe("stateEventProcessor", () => {
     it("should emit conversation_end for end_turn stop reason", () => {
       const event = createStreamEvent("message_stop", { stopReason: "end_turn" });
 
-      const [newContext, outputs] = stateEventProcessor(context, event);
+      const [_newContext, outputs] = stateEventProcessor(context, event);
 
       expect(outputs).toHaveLength(1);
       expect(outputs[0].type).toBe("conversation_end");
@@ -106,7 +106,7 @@ describe("stateEventProcessor", () => {
     it("should emit conversation_responding event", () => {
       const event = createStreamEvent("text_delta", { text: "Hello" });
 
-      const [newContext, outputs] = stateEventProcessor(context, event);
+      const [_newContext, outputs] = stateEventProcessor(context, event);
 
       expect(outputs).toHaveLength(1);
       expect(outputs[0].type).toBe("conversation_responding");
@@ -122,7 +122,7 @@ describe("stateEventProcessor", () => {
         toolName: "search",
       });
 
-      const [newContext, outputs] = stateEventProcessor(context, event);
+      const [_newContext, outputs] = stateEventProcessor(context, event);
 
       expect(outputs).toHaveLength(2);
 
@@ -157,7 +157,7 @@ describe("stateEventProcessor", () => {
         errorCode: "rate_limit",
       });
 
-      const [newContext, outputs] = stateEventProcessor(context, event);
+      const [_newContext, outputs] = stateEventProcessor(context, event);
 
       expect(outputs).toHaveLength(1);
       expect(outputs[0].type).toBe("error_occurred");

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

@@ -2,15 +2,18 @@
  * 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";
+import { beforeEach, describe, expect, it } from "bun:test";
 import {
-  turnTrackerProcessor,
   createInitialTurnTrackerState,
-  type TurnTrackerState,
   type TurnTrackerInput,
   type TurnTrackerOutput,
+  type TurnTrackerState,
+  turnTrackerProcessor,
 } from "../../../engine/internal/turnTrackerProcessor";
 
 // Helper to create test events
@@ -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/__tests__/engine/mealy/Mealy.test.ts

@@ -2,11 +2,11 @@
  * Mealy.test.ts - Unit tests for Mealy Machine runtime
  */
 
-import { describe, it, expect, beforeEach, mock } from "bun:test";
-import { Mealy, createMealy, type MealyConfig } from "../../../engine/mealy/Mealy";
-import { MemoryStore } from "../../../engine/mealy/Store";
+import { beforeEach, describe, expect, it } from "bun:test";
+import { createMealy, Mealy, type MealyConfig } from "../../../engine/mealy/Mealy";
 import type { Processor } from "../../../engine/mealy/Processor";
 import type { Sink, SinkDefinition } from "../../../engine/mealy/Sink";
+import { MemoryStore } from "../../../engine/mealy/Store";
 
 // Test types
 interface TestState {

package/src/agent/__tests__/engine/mealy/Store.test.ts

@@ -2,7 +2,7 @@
  * Store.test.ts - Unit tests for MemoryStore
  */
 
-import { describe, it, expect, beforeEach } from "bun:test";
+import { beforeEach, describe, expect, it } from "bun:test";
 import { MemoryStore, type Store } from "../../../engine/mealy/Store";
 
 describe("MemoryStore", () => {

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

@@ -2,15 +2,15 @@
  * combinators.test.ts - Unit tests for Mealy processor combinators
  */
 
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import {
-  combineProcessors,
-  combineInitialStates,
   chainProcessors,
+  combineInitialStates,
+  combineProcessors,
   filterProcessor,
+  identityProcessor,
   mapOutput,
   withLogging,
-  identityProcessor,
 } from "../../../engine/mealy/combinators";
 import type { Processor } from "../../../engine/mealy/Processor";
 

package/src/agent/createAgent.ts

@@ -21,29 +21,29 @@
  * ```
  */
 
+import { createLogger } from "commonxjs/logger";
+import { isDriveableEvent } from "../event";
+import { AgentStateMachine } from "./AgentStateMachine";
+import { MealyMachine } from "./engine/MealyMachine";
 import type {
   AgentEngine,
-  AgentState,
+  AgentEventBus,
+  AgentInterceptor,
+  AgentMiddleware,
+  AgentOutput,
   AgentOutputCallback,
-  UserMessage,
-  MessageQueue,
-  StateChangeHandler,
+  AgentPresenter,
+  AgentSource,
+  AgentState,
+  CreateAgentOptions,
   EventHandlerMap,
+  MessageQueue,
   ReactHandlerMap,
-  AgentOutput,
-  CreateAgentOptions,
-  AgentSource,
-  AgentPresenter,
-  AgentEventBus,
+  StateChangeHandler,
   StreamEvent,
   Unsubscribe,
-  AgentMiddleware,
-  AgentInterceptor,
+  UserMessage,
 } from "./types";
-import { MealyMachine } from "./engine/MealyMachine";
-import { AgentStateMachine } from "./AgentStateMachine";
-import { createLogger } from "commonxjs/logger";
-import { isDriveableEvent } from "../event";
 
 const logger = createLogger("agent/AgentEngine");
 

package/src/agent/engine/AgentProcessor.ts

@@ -5,24 +5,24 @@
  * Composes MessageAssembler, StateMachine, and TurnTracker processors.
  */
 
-import { combineProcessors, combineInitialStates, type Processor } from "./mealy";
+import type { AgentOutput } from "../types";
 // Note: StreamEventType and MessageEventType are part of AgentOutput (from Presenter)
 // They flow through the system but AgentProcessor doesn't need to import them directly
 import {
-  messageAssemblerProcessor,
-  stateEventProcessor,
-  turnTrackerProcessor,
   createInitialMessageAssemblerState,
   createInitialStateEventProcessorContext,
   createInitialTurnTrackerState,
+  type MessageAssemblerOutput,
   type MessageAssemblerState,
+  messageAssemblerProcessor,
   type StateEventProcessorContext,
-  type TurnTrackerState,
-  type MessageAssemblerOutput,
   type StateEventProcessorOutput,
+  stateEventProcessor,
   type TurnTrackerOutput,
+  type TurnTrackerState,
+  turnTrackerProcessor,
 } from "./internal";
-import type { AgentOutput } from "../types";
+import { combineInitialStates, combineProcessors, type Processor } from "./mealy";
 
 /**
  * Combined state type for the full agent engine

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)
  * ```
  *
@@ -45,14 +45,14 @@
  * ```
  */
 
+import { createLogger } from "commonxjs/logger";
+import type { AgentOutput, StreamEvent } from "../types";
 import {
+  type AgentEngineState,
   agentProcessor,
   createInitialAgentEngineState,
-  type AgentEngineState,
 } from "./AgentProcessor";
 import { MemoryStore } from "./mealy";
-import type { AgentOutput, StreamEvent } from "../types";
-import { createLogger } from "commonxjs/logger";
 
 const logger = createLogger("engine/MealyMachine");
 

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

@@ -6,30 +6,30 @@
  */
 
 export {
-  messageAssemblerProcessor,
-  messageAssemblerProcessorDef,
+  createInitialMessageAssemblerState,
   type MessageAssemblerInput,
   type MessageAssemblerOutput,
   type MessageAssemblerState,
+  messageAssemblerProcessor,
+  messageAssemblerProcessorDef,
   type PendingContent,
-  createInitialMessageAssemblerState,
 } from "./messageAssemblerProcessor";
 
 export {
-  stateEventProcessor,
-  stateEventProcessorDef,
+  createInitialStateEventProcessorContext,
+  type StateEventProcessorContext,
   type StateEventProcessorInput,
   type StateEventProcessorOutput,
-  type StateEventProcessorContext,
-  createInitialStateEventProcessorContext,
+  stateEventProcessor,
+  stateEventProcessorDef,
 } from "./stateEventProcessor";
 
 export {
-  turnTrackerProcessor,
-  turnTrackerProcessorDef,
+  createInitialTurnTrackerState,
+  type PendingTurn,
   type TurnTrackerInput,
   type TurnTrackerOutput,
   type TurnTrackerState,
-  type PendingTurn,
-  createInitialTurnTrackerState,
+  turnTrackerProcessor,
+  turnTrackerProcessorDef,
 } from "./turnTrackerProcessor";