@agentxjs/core 1.9.1-dev

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

@@ -0,0 +1,315 @@
+/**
+ * stateEventProcessor.test.ts - Unit tests for state event processor
+ *
+ * Tests the stateless event transformer: Stream Events -> State Events
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  stateEventProcessor,
+  createInitialStateEventProcessorContext,
+  type StateEventProcessorContext,
+  type StateEventProcessorInput,
+  type StateEventProcessorOutput,
+} from "../../../engine/internal/stateEventProcessor";
+
+// Helper to create test events
+function createStreamEvent(
+  type: string,
+  data: unknown = {},
+  timestamp = Date.now()
+): StateEventProcessorInput {
+  return { type, data, timestamp } as StateEventProcessorInput;
+}
+
+describe("stateEventProcessor", () => {
+  let context: StateEventProcessorContext;
+
+  beforeEach(() => {
+    context = createInitialStateEventProcessorContext();
+  });
+
+  describe("initial context", () => {
+    it("should create empty initial context", () => {
+      const initialContext = createInitialStateEventProcessorContext();
+      expect(initialContext).toEqual({});
+    });
+  });
+
+  describe("message_start event", () => {
+    it("should emit conversation_start event", () => {
+      const event = createStreamEvent("message_start", { messageId: "msg_123" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("conversation_start");
+      expect(outputs[0].data.messageId).toBe("msg_123");
+      expect(outputs[0].timestamp).toBeDefined();
+
+      // Context should remain unchanged
+      expect(newContext).toEqual(context);
+    });
+  });
+
+  describe("message_delta event", () => {
+    it("should not emit any event (no-op)", () => {
+      const event = createStreamEvent("message_delta", { stopReason: "end_turn" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(0);
+      expect(newContext).toEqual(context);
+    });
+  });
+
+  describe("message_stop event", () => {
+    it("should emit conversation_end for end_turn stop reason", () => {
+      const event = createStreamEvent("message_stop", { stopReason: "end_turn" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("conversation_end");
+      expect(outputs[0].data.reason).toBe("completed");
+    });
+
+    it("should emit conversation_end for max_tokens stop reason", () => {
+      const event = createStreamEvent("message_stop", { stopReason: "max_tokens" });
+
+      const [, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("conversation_end");
+    });
+
+    it("should emit conversation_end for stop_sequence stop reason", () => {
+      const event = createStreamEvent("message_stop", { stopReason: "stop_sequence" });
+
+      const [, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("conversation_end");
+    });
+
+    it("should NOT emit conversation_end for tool_use stop reason", () => {
+      const event = createStreamEvent("message_stop", { stopReason: "tool_use" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(0);
+      expect(newContext).toEqual(context);
+    });
+  });
+
+  describe("text_delta event", () => {
+    it("should emit conversation_responding event", () => {
+      const event = createStreamEvent("text_delta", { text: "Hello" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("conversation_responding");
+      expect(outputs[0].data).toEqual({});
+      expect(outputs[0].timestamp).toBeDefined();
+    });
+  });
+
+  describe("tool_use_start event", () => {
+    it("should emit tool_planned and tool_executing events", () => {
+      const event = createStreamEvent("tool_use_start", {
+        toolCallId: "tool_123",
+        toolName: "search",
+      });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(2);
+
+      // First output: tool_planned
+      expect(outputs[0].type).toBe("tool_planned");
+      expect(outputs[0].data.toolId).toBe("tool_123");
+      expect(outputs[0].data.toolName).toBe("search");
+
+      // Second output: tool_executing
+      expect(outputs[1].type).toBe("tool_executing");
+      expect(outputs[1].data.toolId).toBe("tool_123");
+      expect(outputs[1].data.toolName).toBe("search");
+      expect(outputs[1].data.input).toEqual({});
+    });
+  });
+
+  describe("tool_use_stop event", () => {
+    it("should not emit any event (pass through)", () => {
+      const event = createStreamEvent("tool_use_stop", {});
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(0);
+      expect(newContext).toEqual(context);
+    });
+  });
+
+  describe("error_received event", () => {
+    it("should emit error_occurred event with error details", () => {
+      const event = createStreamEvent("error_received", {
+        message: "API rate limit exceeded",
+        errorCode: "rate_limit",
+      });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(1);
+      expect(outputs[0].type).toBe("error_occurred");
+      expect(outputs[0].data.code).toBe("rate_limit");
+      expect(outputs[0].data.message).toBe("API rate limit exceeded");
+      expect(outputs[0].data.recoverable).toBe(true);
+    });
+
+    it("should use unknown_error code when errorCode is missing", () => {
+      const event = createStreamEvent("error_received", {
+        message: "Something went wrong",
+      });
+
+      const [, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs[0].data.code).toBe("unknown_error");
+    });
+  });
+
+  describe("unhandled events", () => {
+    it("should pass through unhandled events without output", () => {
+      const event = createStreamEvent("input_json_delta", { partialJson: "{}" });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(0);
+      expect(newContext).toEqual(context);
+    });
+
+    it("should handle completely unknown event types", () => {
+      const event = createStreamEvent("completely_unknown_event", { anything: true });
+
+      const [newContext, outputs] = stateEventProcessor(context, event);
+
+      expect(outputs).toHaveLength(0);
+      expect(newContext).toEqual(context);
+    });
+  });
+
+  describe("complete conversation flow", () => {
+    it("should produce correct state events for simple message", () => {
+      const allOutputs: StateEventProcessorOutput[] = [];
+
+      // message_start
+      const [, o1] = stateEventProcessor(
+        context,
+        createStreamEvent("message_start", { messageId: "msg_1" })
+      );
+      allOutputs.push(...o1);
+
+      // text_delta
+      const [, o2] = stateEventProcessor(
+        context,
+        createStreamEvent("text_delta", { text: "Hello" })
+      );
+      allOutputs.push(...o2);
+
+      // message_stop
+      const [, o3] = stateEventProcessor(
+        context,
+        createStreamEvent("message_stop", { stopReason: "end_turn" })
+      );
+      allOutputs.push(...o3);
+
+      expect(allOutputs).toHaveLength(3);
+      expect(allOutputs.map((o) => o.type)).toEqual([
+        "conversation_start",
+        "conversation_responding",
+        "conversation_end",
+      ]);
+    });
+
+    it("should produce correct state events for tool call flow", () => {
+      const allOutputs: StateEventProcessorOutput[] = [];
+
+      // message_start
+      const [, o1] = stateEventProcessor(
+        context,
+        createStreamEvent("message_start", { messageId: "msg_1" })
+      );
+      allOutputs.push(...o1);
+
+      // tool_use_start
+      const [, o2] = stateEventProcessor(
+        context,
+        createStreamEvent("tool_use_start", { toolCallId: "tool_1", toolName: "search" })
+      );
+      allOutputs.push(...o2);
+
+      // tool_use_stop
+      const [, o3] = stateEventProcessor(context, createStreamEvent("tool_use_stop", {}));
+      allOutputs.push(...o3);
+
+      // message_stop with tool_use (should NOT emit conversation_end)
+      const [, o4] = stateEventProcessor(
+        context,
+        createStreamEvent("message_stop", { stopReason: "tool_use" })
+      );
+      allOutputs.push(...o4);
+
+      // New message after tool result
+      const [, o5] = stateEventProcessor(
+        context,
+        createStreamEvent("message_start", { messageId: "msg_2" })
+      );
+      allOutputs.push(...o5);
+
+      // text_delta with final response
+      const [, o6] = stateEventProcessor(
+        context,
+        createStreamEvent("text_delta", { text: "Result" })
+      );
+      allOutputs.push(...o6);
+
+      // Final message_stop
+      const [, o7] = stateEventProcessor(
+        context,
+        createStreamEvent("message_stop", { stopReason: "end_turn" })
+      );
+      allOutputs.push(...o7);
+
+      expect(allOutputs.map((o) => o.type)).toEqual([
+        "conversation_start", // msg_1 start
+        "tool_planned", // tool started
+        "tool_executing", // tool executing
+        // No output for tool_use_stop
+        // No conversation_end for tool_use
+        "conversation_start", // msg_2 start
+        "conversation_responding", // text delta
+        "conversation_end", // final end
+      ]);
+    });
+  });
+
+  describe("statelessness", () => {
+    it("should not modify context across multiple calls", () => {
+      const originalContext = createInitialStateEventProcessorContext();
+
+      // Process multiple events
+      stateEventProcessor(originalContext, createStreamEvent("message_start", { messageId: "1" }));
+      stateEventProcessor(originalContext, createStreamEvent("text_delta", { text: "Hello" }));
+      stateEventProcessor(
+        originalContext,
+        createStreamEvent("tool_use_start", { toolCallId: "t1", toolName: "test" })
+      );
+      stateEventProcessor(
+        originalContext,
+        createStreamEvent("error_received", { message: "error" })
+      );
+
+      // Original context should remain unchanged
+      expect(originalContext).toEqual({});
+    });
+  });
+});

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

@@ -0,0 +1,340 @@
+/**
+ * turnTrackerProcessor.test.ts - Unit tests for turn tracker processor
+ *
+ * Tests the pure Mealy transition function that tracks request-response turn pairs.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  turnTrackerProcessor,
+  createInitialTurnTrackerState,
+  type TurnTrackerState,
+  type TurnTrackerInput,
+  type TurnTrackerOutput,
+} from "../../../engine/internal/turnTrackerProcessor";
+
+// Helper to create test events
+function createEvent(type: string, data: unknown, timestamp = Date.now()): TurnTrackerInput {
+  return { type, data, timestamp } as TurnTrackerInput;
+}
+
+// Helper to create user message event
+function createUserMessageEvent(
+  content: string,
+  messageId: string = `msg_${Date.now()}`,
+  timestamp = Date.now()
+): TurnTrackerInput {
+  return createEvent(
+    "user_message",
+    {
+      id: messageId,
+      role: "user",
+      subtype: "user",
+      content,
+      timestamp,
+    },
+    timestamp
+  );
+}
+
+// Helper to create message_stop event
+function createMessageStopEvent(stopReason: string, timestamp = Date.now()): TurnTrackerInput {
+  return createEvent("message_stop", { stopReason }, timestamp);
+}
+
+describe("turnTrackerProcessor", () => {
+  let state: TurnTrackerState;
+
+  beforeEach(() => {
+    state = createInitialTurnTrackerState();
+  });
+
+  describe("initial state", () => {
+    it("should create correct initial state", () => {
+      const initialState = createInitialTurnTrackerState();
+
+      expect(initialState.pendingTurn).toBeNull();
+      expect(initialState.costPerInputToken).toBe(0.000003);
+      expect(initialState.costPerOutputToken).toBe(0.000015);
+    });
+  });
+
+  describe("user_message event", () => {
+    it("should create pending turn and emit turn_request", () => {
+      const event = createUserMessageEvent("Hello", "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();
+
+      // Should emit turn_request
+      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")
+      );
+
+      // Complete the turn
+      const [state2] = turnTrackerProcessor(state1, createMessageStopEvent("end_turn"));
+
+      // Start new turn
+      const [state3, outputs3] = turnTrackerProcessor(
+        state2,
+        createUserMessageEvent("Second", "msg_2")
+      );
+
+      expect(outputs1[0].data.turnId).not.toBe(outputs3[0].data.turnId);
+    });
+
+    it("should handle empty content", () => {
+      const event = createUserMessageEvent("", "msg_empty");
+
+      const [newState, outputs] = turnTrackerProcessor(state, event);
+
+      expect(newState.pendingTurn?.content).toBe("");
+      expect(outputs[0].data.content).toBe("");
+    });
+  });
+
+  describe("message_stop event", () => {
+    describe("with pending turn", () => {
+      beforeEach(() => {
+        // Setup pending turn
+        state = {
+          ...state,
+          pendingTurn: {
+            turnId: "turn_123",
+            messageId: "msg_123",
+            content: "Test message",
+            requestedAt: 1000,
+          },
+        };
+      });
+
+      it("should complete turn and emit turn_response for end_turn", () => {
+        const event = createMessageStopEvent("end_turn", 2000);
+
+        const [newState, outputs] = turnTrackerProcessor(state, event);
+
+        expect(newState.pendingTurn).toBeNull();
+
+        expect(outputs).toHaveLength(1);
+        expect(outputs[0].type).toBe("turn_response");
+        expect(outputs[0].data.turnId).toBe("turn_123");
+        expect(outputs[0].data.messageId).toBe("msg_123");
+        expect(outputs[0].data.duration).toBe(1000); // 2000 - 1000
+        expect(outputs[0].data.timestamp).toBe(2000);
+      });
+
+      it("should complete turn for max_tokens", () => {
+        const event = createMessageStopEvent("max_tokens", 3000);
+
+        const [newState, outputs] = turnTrackerProcessor(state, event);
+
+        expect(newState.pendingTurn).toBeNull();
+        expect(outputs).toHaveLength(1);
+        expect(outputs[0].type).toBe("turn_response");
+        expect(outputs[0].data.duration).toBe(2000); // 3000 - 1000
+      });
+
+      it("should complete turn for stop_sequence", () => {
+        const event = createMessageStopEvent("stop_sequence", 1500);
+
+        const [newState, outputs] = turnTrackerProcessor(state, event);
+
+        expect(newState.pendingTurn).toBeNull();
+        expect(outputs).toHaveLength(1);
+        expect(outputs[0].type).toBe("turn_response");
+        expect(outputs[0].data.duration).toBe(500); // 1500 - 1000
+      });
+
+      it("should NOT complete turn for tool_use", () => {
+        const event = createMessageStopEvent("tool_use", 2000);
+
+        const [newState, outputs] = turnTrackerProcessor(state, event);
+
+        // Should keep pending turn
+        expect(newState.pendingTurn).not.toBeNull();
+        expect(newState.pendingTurn?.turnId).toBe("turn_123");
+
+        // Should not emit output
+        expect(outputs).toHaveLength(0);
+      });
+
+      it("should include usage information", () => {
+        const event = createMessageStopEvent("end_turn", 2000);
+
+        const [, outputs] = turnTrackerProcessor(state, event);
+
+        expect(outputs[0].data.usage).toBeDefined();
+        expect(outputs[0].data.usage.inputTokens).toBe(0);
+        expect(outputs[0].data.usage.outputTokens).toBe(0);
+      });
+    });
+
+    describe("without pending turn", () => {
+      it("should not emit output when no pending turn", () => {
+        const event = createMessageStopEvent("end_turn", 2000);
+
+        const [newState, outputs] = turnTrackerProcessor(state, event);
+
+        expect(newState).toEqual(state);
+        expect(outputs).toHaveLength(0);
+      });
+    });
+  });
+
+  describe("assistant_message event", () => {
+    it("should not emit output (handled in message_stop)", () => {
+      state = {
+        ...state,
+        pendingTurn: {
+          turnId: "turn_123",
+          messageId: "msg_123",
+          content: "Test",
+          requestedAt: 1000,
+        },
+      };
+
+      const event = createEvent("assistant_message", {
+        id: "msg_assistant",
+        role: "assistant",
+        content: [{ type: "text", text: "Response" }],
+      });
+
+      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", () => {
+      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)
+      );
+      currentState = s1;
+      allOutputs.push(...o1);
+
+      // Assistant responds, message_stop at time 2500
+      const [s2, o2] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 2500));
+      currentState = s2;
+      allOutputs.push(...o2);
+
+      expect(allOutputs).toHaveLength(2);
+
+      // turn_request
+      expect(allOutputs[0].type).toBe("turn_request");
+      expect(allOutputs[0].data.content).toBe("What is 2+2?");
+
+      // turn_response
+      expect(allOutputs[1].type).toBe("turn_response");
+      expect(allOutputs[1].data.duration).toBe(1500);
+
+      // State should be clean
+      expect(currentState.pendingTurn).toBeNull();
+    });
+
+    it("should track turn with tool use (turn continues)", () => {
+      const allOutputs: TurnTrackerOutput[] = [];
+      let currentState = createInitialTurnTrackerState();
+
+      // User sends message
+      const [s1, o1] = turnTrackerProcessor(
+        currentState,
+        createUserMessageEvent("Search for X", "msg_1", 1000)
+      );
+      currentState = s1;
+      allOutputs.push(...o1);
+
+      // First message_stop with tool_use - turn should NOT complete
+      const [s2, o2] = turnTrackerProcessor(currentState, createMessageStopEvent("tool_use", 1500));
+      currentState = s2;
+      allOutputs.push(...o2);
+
+      expect(currentState.pendingTurn).not.toBeNull();
+      expect(allOutputs).toHaveLength(1); // Only turn_request
+
+      // Second message_stop with end_turn - turn completes
+      const [s3, o3] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 3000));
+      currentState = s3;
+      allOutputs.push(...o3);
+
+      expect(allOutputs).toHaveLength(2); // turn_request + turn_response
+      expect(allOutputs[1].type).toBe("turn_response");
+      expect(allOutputs[1].data.duration).toBe(2000); // 3000 - 1000
+      expect(currentState.pendingTurn).toBeNull();
+    });
+
+    it("should handle multiple consecutive turns", () => {
+      let currentState = createInitialTurnTrackerState();
+      const allTurnIds: string[] = [];
+
+      // First turn
+      const [s1, o1] = turnTrackerProcessor(
+        currentState,
+        createUserMessageEvent("First", "msg_1", 1000)
+      );
+      currentState = s1;
+      allTurnIds.push(o1[0].data.turnId);
+
+      const [s2] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 1500));
+      currentState = s2;
+
+      // Second turn
+      const [s3, o3] = turnTrackerProcessor(
+        currentState,
+        createUserMessageEvent("Second", "msg_2", 2000)
+      );
+      currentState = s3;
+      allTurnIds.push(o3[0].data.turnId);
+
+      const [s4] = turnTrackerProcessor(currentState, createMessageStopEvent("end_turn", 2500));
+      currentState = s4;
+
+      // Third turn
+      const [s5, o5] = turnTrackerProcessor(
+        currentState,
+        createUserMessageEvent("Third", "msg_3", 3000)
+      );
+      currentState = s5;
+      allTurnIds.push(o5[0].data.turnId);
+
+      // All turn IDs should be unique
+      const uniqueIds = new Set(allTurnIds);
+      expect(uniqueIds.size).toBe(3);
+    });
+  });
+});