@ag-ui/proto 0.0.27

package/__tests__/run-events.test.ts

@@ -0,0 +1,277 @@
+import {
+  EventType,
+  RunStartedEvent,
+  RunFinishedEvent,
+  RunErrorEvent,
+  StepStartedEvent,
+  StepFinishedEvent,
+  RawEvent,
+  CustomEvent,
+} from "@ag-ui/core";
+import { expect, describe, it } from "@jest/globals";
+import { encode, decode } from "../src/proto";
+import { expectRoundTripEquality } from "./test-utils";
+
+describe("Run Events and Misc Events", () => {
+  describe("Run Events", () => {
+    it("should round-trip encode/decode RunStartedEvent event", () => {
+      const event: RunStartedEvent = {
+        type: EventType.RUN_STARTED,
+        timestamp: Date.now(),
+        threadId: "thread-1234",
+        runId: "run-5678",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should round-trip encode/decode RunFinishedEvent event", () => {
+      const event: RunFinishedEvent = {
+        type: EventType.RUN_FINISHED,
+        timestamp: Date.now(),
+        threadId: "thread-1234",
+        runId: "run-5678",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should round-trip encode/decode RunErrorEvent event", () => {
+      const event: RunErrorEvent = {
+        type: EventType.RUN_ERROR,
+        timestamp: Date.now(),
+        message: "Failed to execute tool call",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle RunErrorEvent with detailed error info", () => {
+      const event: RunErrorEvent = {
+        type: EventType.RUN_ERROR,
+        message: "API request failed",
+        code: "API_ERROR",
+      };
+
+      expectRoundTripEquality(event);
+    });
+  });
+
+  describe("Step Events", () => {
+    it("should round-trip encode/decode StepStartedEvent event", () => {
+      const event: StepStartedEvent = {
+        type: EventType.STEP_STARTED,
+        timestamp: Date.now(),
+        stepName: "data_analysis",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should round-trip encode/decode StepFinishedEvent event", () => {
+      const event: StepFinishedEvent = {
+        type: EventType.STEP_FINISHED,
+        timestamp: Date.now(),
+        stepName: "data_analysis",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle StepStartedEvent with minimal fields", () => {
+      const event: StepStartedEvent = {
+        type: EventType.STEP_STARTED,
+        stepName: "process_payment",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle StepFinishedEvent with minimal fields", () => {
+      const event: StepFinishedEvent = {
+        type: EventType.STEP_FINISHED,
+        stepName: "process_payment",
+      };
+
+      expectRoundTripEquality(event);
+    });
+  });
+
+  describe("RawEvent", () => {
+    it("should round-trip encode/decode RawEvent", () => {
+      const event: RawEvent = {
+        type: EventType.RAW,
+        timestamp: Date.now(),
+        event: {
+          type: "user_action",
+          action: "button_click",
+          elementId: "submit-btn",
+          timestamp: Date.now(),
+        },
+        source: "frontend",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle complex nested data in RawEvent", () => {
+      const event: RawEvent = {
+        type: EventType.RAW,
+        event: {
+          type: "analytics_event",
+          session: {
+            id: "sess-12345",
+            user: {
+              id: "user-456",
+              attributes: {
+                plan: "premium",
+                signupDate: "2023-01-15",
+                preferences: ["feature1", "feature2"],
+              },
+            },
+            actions: [
+              { type: "page_view", path: "/home", timestamp: 1676480210000 },
+              {
+                type: "button_click",
+                elementId: "cta-1",
+                timestamp: 1676480215000,
+              },
+              {
+                type: "form_submit",
+                formId: "signup",
+                timestamp: 1676480230000,
+                data: { email: "user@example.com" },
+              },
+            ],
+          },
+          metadata: {
+            source: "web",
+            version: "1.2.3",
+            environment: "production",
+          },
+        },
+      };
+
+      expectRoundTripEquality(event);
+    });
+  });
+
+  describe("CustomEvent", () => {
+    it("should round-trip encode/decode CustomEvent", () => {
+      const event: CustomEvent = {
+        type: EventType.CUSTOM,
+        timestamp: Date.now(),
+        name: "user_preference_updated",
+        value: {
+          theme: "dark",
+          fontSize: "medium",
+          notifications: true,
+        },
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle CustomEvent without a value", () => {
+      const event: CustomEvent = {
+        type: EventType.CUSTOM,
+        name: "heartbeat",
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle complex values in CustomEvent", () => {
+      const event: CustomEvent = {
+        type: EventType.CUSTOM,
+        name: "analytics_update",
+        value: {
+          metrics: {
+            active_users: 12345,
+            conversion_rate: 0.0354,
+            revenue: 98765.43,
+          },
+          segments: [
+            { name: "new_users", count: 543, growth: 0.12 },
+            { name: "returning_users", count: 876, growth: -0.05 },
+            { name: "power_users", count: 234, growth: 0.08 },
+          ],
+          period: {
+            start: "2023-01-01",
+            end: "2023-01-31",
+            duration_days: 31,
+          },
+          trends: {
+            daily: [10, 12, 15, 14, 18, 20, 22],
+            weekly: [70, 85, 92, 105],
+            monthly: [320, 370],
+          },
+        },
+      };
+
+      expectRoundTripEquality(event);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle basic fields for each event type", () => {
+      const events = [
+        {
+          type: EventType.RUN_STARTED,
+          threadId: "thread-basic",
+          runId: "run-basic",
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          threadId: "thread-basic",
+          runId: "run-basic",
+        },
+        { type: EventType.CUSTOM, name: "empty" },
+      ];
+
+      for (const event of events) {
+        const encoded = encode(event);
+        const decoded = decode(encoded);
+        expect(decoded.type).toBe(event.type);
+      }
+    });
+
+    it("should handle events with all base fields", () => {
+      const runEvents = [
+        {
+          type: EventType.RUN_STARTED,
+          timestamp: Date.now(),
+          threadId: "thread-full",
+          runId: "run-full",
+          rawEvent: { original: "data", from: "external_system" },
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          timestamp: Date.now(),
+          threadId: "thread-full",
+          runId: "run-full",
+          rawEvent: { original: "data", from: "external_system" },
+        },
+      ];
+
+      const nonRunEvents = [
+        {
+          type: EventType.RUN_ERROR,
+          message: "Test error",
+          timestamp: Date.now(),
+          rawEvent: { original: "data", from: "external_system" },
+        },
+        {
+          type: EventType.CUSTOM,
+          name: "full_event",
+          timestamp: Date.now(),
+          rawEvent: { original: "data", from: "external_system" },
+        },
+      ];
+
+      for (const event of [...runEvents, ...nonRunEvents]) {
+        expectRoundTripEquality(event);
+      }
+    });
+  });
+});

package/__tests__/state-events.test.ts

@@ -0,0 +1,237 @@
+import { EventType, StateSnapshotEvent, StateDeltaEvent } from "@ag-ui/core";
+import { expect, describe, it } from "@jest/globals";
+import { encode, decode } from "../src/proto";
+import { expectRoundTripEquality } from "./test-utils";
+
+describe("State Events", () => {
+  describe("StateSnapshotEvent", () => {
+    it("should round-trip encode/decode correctly", () => {
+      const event: StateSnapshotEvent = {
+        type: EventType.STATE_SNAPSHOT,
+        timestamp: Date.now(),
+        snapshot: {
+          counter: 42,
+          items: ["apple", "banana", "cherry"],
+          config: {
+            enabled: true,
+            maxRetries: 3,
+          },
+        },
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle empty snapshot object", () => {
+      const event: StateSnapshotEvent = {
+        type: EventType.STATE_SNAPSHOT,
+        snapshot: {},
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle complex nested objects", () => {
+      const event: StateSnapshotEvent = {
+        type: EventType.STATE_SNAPSHOT,
+        snapshot: {
+          userProfile: {
+            name: "John Doe",
+            age: 30,
+            contact: {
+              email: "john@example.com",
+              phone: "+1234567890",
+              address: {
+                street: "123 Main St",
+                city: "Anytown",
+                country: "USA",
+                coordinates: {
+                  lat: 37.7749,
+                  lng: -122.4194,
+                },
+              },
+            },
+            preferences: {
+              theme: "dark",
+              notifications: true,
+              privateProfile: false,
+            },
+          },
+          serviceConfig: {
+            endpoints: [
+              {
+                name: "api1",
+                url: "https://api1.example.com",
+                methods: ["GET", "POST"],
+              },
+              {
+                name: "api2",
+                url: "https://api2.example.com",
+                methods: ["GET"],
+              },
+            ],
+            retryPolicy: {
+              maxRetries: 3,
+              backoff: "exponential",
+              timeouts: [1000, 2000, 4000],
+            },
+          },
+          stats: {
+            visits: 1042,
+            conversions: 123,
+            bounceRate: 0.25,
+            dataPoints: [
+              { date: "2023-01-01", value: 10 },
+              { date: "2023-01-02", value: 15 },
+              { date: "2023-01-03", value: 8 },
+            ],
+          },
+        },
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle special values in snapshot", () => {
+      const event: StateSnapshotEvent = {
+        type: EventType.STATE_SNAPSHOT,
+        snapshot: {
+          nullValue: null,
+          emptyString: "",
+          zero: 0,
+          negativeNumber: -123,
+          floatNumber: 3.14159,
+          emptyArray: [],
+          emptyObject: {},
+          boolValues: { true: true, false: false },
+          infinityValue: Infinity,
+          nanValue: NaN,
+          dateString: new Date().toISOString(),
+        },
+      };
+
+      const encoded = encode(event);
+      const decoded = decode(encoded) as StateSnapshotEvent;
+
+      // Check specific values that might need special handling
+      expect(decoded.snapshot.nullValue).toBe(event.snapshot.nullValue);
+      expect(decoded.snapshot.emptyString).toBe(event.snapshot.emptyString);
+      expect(decoded.snapshot.zero).toBe(event.snapshot.zero);
+      expect(decoded.snapshot.negativeNumber).toBe(event.snapshot.negativeNumber);
+      expect(decoded.snapshot.floatNumber).toBe(event.snapshot.floatNumber);
+      expect(decoded.snapshot.emptyArray).toEqual(event.snapshot.emptyArray);
+      expect(decoded.snapshot.emptyObject).toEqual(event.snapshot.emptyObject);
+      expect(decoded.snapshot.boolValues).toEqual(event.snapshot.boolValues);
+      expect(decoded.snapshot.dateString).toBe(event.snapshot.dateString);
+
+      // Infinity/NaN don't survive JSON.stringify, so they may not be exactly equal
+      if (Number.isNaN(decoded.snapshot.nanValue)) {
+        expect(Number.isNaN(event.snapshot.nanValue)).toBe(true);
+      }
+    });
+  });
+
+  describe("StateDeltaEvent", () => {
+    it("should round-trip encode/decode correctly", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        timestamp: Date.now(),
+        delta: [
+          { op: "add", path: "/counter", value: 42 },
+          { op: "add", path: "/items", value: ["apple", "banana", "cherry"] },
+        ],
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle all JSON Patch operation types", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [
+          { op: "add", path: "/users/123", value: { name: "John", age: 30 } },
+          { op: "remove", path: "/users/456" },
+          { op: "replace", path: "/users/789/name", value: "Jane Doe" },
+          { op: "move", from: "/users/old", path: "/users/new" },
+          {
+            op: "copy",
+            from: "/templates/default",
+            path: "/users/123/template",
+          },
+          { op: "test", path: "/users/123/active", value: true },
+        ],
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle complex values in add operations", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [
+          {
+            op: "add",
+            path: "/data",
+            value: {
+              nested: {
+                array: [1, 2, 3],
+                object: { key: "value" },
+              },
+              boolean: true,
+              number: 42,
+            },
+          },
+        ],
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle array operations", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [
+          { op: "add", path: "/items", value: [] },
+          { op: "add", path: "/items/0", value: "first" },
+          { op: "add", path: "/items/-", value: "last" },
+          { op: "replace", path: "/items/0", value: "updated first" },
+          { op: "remove", path: "/items/1" },
+        ],
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle special characters in paths", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [
+          { op: "add", path: "/special~0field", value: "value with tilde" },
+          { op: "add", path: "/special~1field", value: "value with slash" },
+          {
+            op: "add",
+            path: "/special/field",
+            value: "value with actual slash",
+          },
+          { op: "add", path: '/special"field', value: "value with quote" },
+          {
+            op: "add",
+            path: "/emoji\u{1F680}field",
+            value: "value with emoji",
+          },
+        ],
+      };
+
+      expectRoundTripEquality(event);
+    });
+
+    it("should handle empty delta array", () => {
+      const event: StateDeltaEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [],
+      };
+
+      expectRoundTripEquality(event);
+    });
+  });
+});

package/__tests__/test-utils.ts

@@ -0,0 +1,33 @@
+import { BaseEvent } from "@ag-ui/core";
+import { encode, decode } from "../src/proto";
+import { expect, describe, it } from "@jest/globals";
+
+/**
+ * Performs a round-trip encode-decode on an event and returns the decoded result
+ */
+export function roundTrip<T extends BaseEvent>(event: T): T {
+  const encoded = encode(event);
+  return decode(encoded) as T;
+}
+
+/**
+ * Verifies that an event is the same after round-trip encoding and decoding
+ */
+export function expectRoundTripEquality<T extends BaseEvent>(event: T): void {
+  const decoded = roundTrip(event);
+
+  // Verify all properties match
+  for (const key in event) {
+    if (Object.prototype.hasOwnProperty.call(event, key)) {
+      expect(decoded[key]).toEqual(event[key]);
+    }
+  }
+}
+
+// Add a simple test to prevent "Your test suite must contain at least one test" error
+describe("Test Utilities", () => {
+  it("should exist as a module for other tests to import from", () => {
+    expect(typeof roundTrip).toBe("function");
+    expect(typeof expectRoundTripEquality).toBe("function");
+  });
+});