@agentxjs/core 1.9.1-dev

package/src/event/README.md

@@ -0,0 +1,237 @@
+# @agentxjs/core/event
+
+Event System for AgentX - Pure memory EventBus with typed events.
+
+## Overview
+
+The event module provides a central event bus for component communication within a process. It's a pure in-memory pub/sub system using RxJS, with no platform dependencies.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        EventBus                              │
+│                                                              │
+│   Producer ──emit()──► Subject ──dispatch()──► Consumers    │
+│                           │                                  │
+│                    ┌──────┴──────┐                          │
+│                    │  Filter     │                          │
+│                    │  Priority   │                          │
+│                    │  Once       │                          │
+│                    └─────────────┘                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Concepts
+
+### Event-Driven Architecture
+
+All components communicate through typed events:
+
+| Source        | Events            | Examples                                   |
+| ------------- | ----------------- | ------------------------------------------ |
+| `environment` | LLM API responses | `message_start`, `text_delta`, `tool_call` |
+| `agent`       | Agent internal    | `conversation_start`, `assistant_message`  |
+| `session`     | Session lifecycle | `session_created`, `session_saved`         |
+| `container`   | Container ops     | `container_created`, `agent_registered`    |
+| `command`     | Request/Response  | `container_create_request/response`        |
+
+### Producer/Consumer Pattern
+
+```typescript
+// Producer - can only emit events
+class ClaudeReceptor {
+  constructor(private producer: EventProducer) {}
+
+  onChunk(text: string) {
+    this.producer.emit({
+      type: "text_delta",
+      timestamp: Date.now(),
+      data: { text },
+      source: "environment",
+      category: "stream",
+      intent: "notification",
+    });
+  }
+}
+
+// Consumer - can only subscribe to events
+class BusDriver {
+  constructor(consumer: EventConsumer) {
+    consumer.on("text_delta", (e) => {
+      console.log("Received:", e.data.text);
+    });
+  }
+}
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { EventBus } from "@agentxjs/core/event";
+
+const bus = new EventBus();
+
+// Subscribe to specific event type
+bus.on("text_delta", (event) => {
+  console.log("Text:", event.data.text);
+});
+
+// Subscribe to all events
+bus.onAny((event) => {
+  console.log("Event:", event.type);
+});
+
+// Emit event
+bus.emit({
+  type: "text_delta",
+  timestamp: Date.now(),
+  data: { text: "Hello!" },
+  source: "environment",
+  category: "stream",
+  intent: "notification",
+});
+```
+
+### Subscription Options
+
+```typescript
+// Filter events
+bus.on("text_delta", handler, {
+  filter: (e) => e.context?.agentId === "agent-1",
+});
+
+// Priority (higher runs first)
+bus.on("text_delta", criticalHandler, { priority: 10 });
+bus.on("text_delta", normalHandler, { priority: 0 });
+
+// One-time subscription
+bus.once("message_stop", (e) => {
+  console.log("Stream ended");
+});
+```
+
+### Command Request/Response
+
+```typescript
+// Send request and wait for response
+const response = await bus.request(
+  "container_create_request",
+  {
+    containerId: "my-container",
+  },
+  30000
+); // 30s timeout
+
+console.log("Created:", response.data.containerId);
+```
+
+### Restricted Views
+
+```typescript
+const bus = new EventBus();
+
+// Give producer to components that emit
+const receptor = new ClaudeReceptor(bus.asProducer());
+
+// Give consumer to components that subscribe
+const driver = new BusDriver(bus.asConsumer());
+```
+
+## Architecture
+
+### Directory Structure
+
+```
+event/
+├── types/
+│   ├── index.ts        # Re-exports all types
+│   ├── base.ts         # SystemEvent, EventSource, EventContext
+│   ├── bus.ts          # EventBus, EventProducer, EventConsumer
+│   ├── agent.ts        # Agent stream/state/message/turn events
+│   ├── session.ts      # Session lifecycle/persist/action events
+│   ├── container.ts    # Container lifecycle/sandbox events
+│   ├── command.ts      # Request/Response events + CommandEventMap
+│   └── environment.ts  # DriveableEvent, ConnectionEvent, StopReason
+│
+├── EventBus.ts         # RxJS-based implementation
+├── __tests__/
+└── index.ts
+```
+
+### Type Hierarchy
+
+```
+BusEvent (simple)
+└── { type, timestamp, data }
+
+SystemEvent (full)
+└── { type, timestamp, data, source, category, intent, context?, broadcastable? }
+```
+
+## API Reference
+
+### EventBus
+
+```typescript
+class EventBus implements EventBusInterface {
+  // Emit
+  emit(event: BusEvent): void;
+  emitBatch(events: BusEvent[]): void;
+  emitCommand<T>(type: T, data: CommandEventMap[T]["data"]): void;
+
+  // Subscribe
+  on(type: string, handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+  on(types: string[], handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+  onAny(handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+  once(type: string, handler: BusEventHandler): Unsubscribe;
+  onCommand<T>(type: T, handler: (event: CommandEventMap[T]) => void): Unsubscribe;
+
+  // Request/Response
+  request<T>(type: T, data: RequestDataFor<T>, timeout?: number): Promise<ResponseEventFor<T>>;
+
+  // Views
+  asProducer(): EventProducer;
+  asConsumer(): EventConsumer;
+
+  // Lifecycle
+  destroy(): void;
+}
+```
+
+### SubscribeOptions
+
+```typescript
+interface SubscribeOptions<E> {
+  filter?: (event: E) => boolean; // Filter events
+  priority?: number; // Execution order (higher first)
+  once?: boolean; // Auto-unsubscribe after first
+}
+```
+
+## Platform Independence
+
+This module has **zero platform dependencies**:
+
+- No `node:*` imports
+- No `bun:*` imports
+- Only depends on `rxjs` (pure JavaScript)
+
+Can run in: Node.js, Bun, Deno, Cloudflare Workers, Browser.
+
+## Not a Message Queue
+
+EventBus is for **in-process** communication only:
+
+|             | EventBus             | MessageQueue      |
+| ----------- | -------------------- | ----------------- |
+| Scope       | Process-internal     | Cross-process     |
+| Persistence | None                 | SQLite/Redis      |
+| Delivery    | Best-effort          | At-least-once     |
+| Use case    | Component decoupling | Reliable delivery |
+
+For cross-process or persistent messaging, use the `mq` module.
+
+## License
+
+MIT

package/src/event/__tests__/EventBus.test.ts

@@ -0,0 +1,251 @@
+/**
+ * EventBus.test.ts - Unit tests for EventBus implementation
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { EventBus } from "../EventBus";
+import type { BusEvent } from "../types";
+
+// Test event factory
+function createEvent(type: string, data: unknown = {}): BusEvent {
+  return {
+    type,
+    timestamp: Date.now(),
+    data,
+    source: "agent",
+    category: "message",
+    intent: "notification",
+  };
+}
+
+describe("EventBus", () => {
+  let bus: EventBus;
+
+  beforeEach(() => {
+    bus = new EventBus();
+  });
+
+  describe("emit and on", () => {
+    it("should emit event to subscriber", () => {
+      const received: BusEvent[] = [];
+      bus.on("test_event", (e) => received.push(e));
+
+      bus.emit(createEvent("test_event", { value: 1 }));
+
+      expect(received).toHaveLength(1);
+      expect(received[0].type).toBe("test_event");
+      expect(received[0].data).toEqual({ value: 1 });
+    });
+
+    it("should not receive events of different type", () => {
+      const received: BusEvent[] = [];
+      bus.on("type_a", (e) => received.push(e));
+
+      bus.emit(createEvent("type_b"));
+
+      expect(received).toHaveLength(0);
+    });
+
+    it("should support multiple subscribers", () => {
+      let count = 0;
+      bus.on("test", () => count++);
+      bus.on("test", () => count++);
+
+      bus.emit(createEvent("test"));
+
+      expect(count).toBe(2);
+    });
+
+    it("should support array of event types", () => {
+      const received: string[] = [];
+      bus.on(["type_a", "type_b"], (e) => received.push(e.type));
+
+      bus.emit(createEvent("type_a"));
+      bus.emit(createEvent("type_b"));
+      bus.emit(createEvent("type_c"));
+
+      expect(received).toEqual(["type_a", "type_b"]);
+    });
+  });
+
+  describe("unsubscribe", () => {
+    it("should stop receiving events after unsubscribe", () => {
+      const received: BusEvent[] = [];
+      const unsubscribe = bus.on("test", (e) => received.push(e));
+
+      bus.emit(createEvent("test"));
+      expect(received).toHaveLength(1);
+
+      unsubscribe();
+
+      bus.emit(createEvent("test"));
+      expect(received).toHaveLength(1);
+    });
+  });
+
+  describe("onAny", () => {
+    it("should receive all events", () => {
+      const received: string[] = [];
+      bus.onAny((e) => received.push(e.type));
+
+      bus.emit(createEvent("type_a"));
+      bus.emit(createEvent("type_b"));
+      bus.emit(createEvent("type_c"));
+
+      expect(received).toEqual(["type_a", "type_b", "type_c"]);
+    });
+  });
+
+  describe("once", () => {
+    it("should only receive first event", () => {
+      let count = 0;
+      bus.once("test", () => count++);
+
+      bus.emit(createEvent("test"));
+      bus.emit(createEvent("test"));
+      bus.emit(createEvent("test"));
+
+      expect(count).toBe(1);
+    });
+  });
+
+  describe("filter option", () => {
+    it("should filter events", () => {
+      const received: BusEvent[] = [];
+      bus.on("test", (e) => received.push(e), {
+        filter: (e) => (e.data as { value: number }).value > 5,
+      });
+
+      bus.emit(createEvent("test", { value: 3 }));
+      bus.emit(createEvent("test", { value: 7 }));
+      bus.emit(createEvent("test", { value: 10 }));
+
+      expect(received).toHaveLength(2);
+      expect((received[0].data as { value: number }).value).toBe(7);
+      expect((received[1].data as { value: number }).value).toBe(10);
+    });
+  });
+
+  describe("priority option", () => {
+    it("should execute higher priority handlers first", () => {
+      const order: number[] = [];
+
+      bus.on("test", () => order.push(1), { priority: 1 });
+      bus.on("test", () => order.push(10), { priority: 10 });
+      bus.on("test", () => order.push(5), { priority: 5 });
+
+      bus.emit(createEvent("test"));
+
+      expect(order).toEqual([10, 5, 1]);
+    });
+  });
+
+  describe("emitBatch", () => {
+    it("should emit multiple events", () => {
+      const received: string[] = [];
+      bus.onAny((e) => received.push(e.type));
+
+      bus.emitBatch([createEvent("a"), createEvent("b"), createEvent("c")]);
+
+      expect(received).toEqual(["a", "b", "c"]);
+    });
+  });
+
+  describe("asProducer and asConsumer", () => {
+    it("should return producer view with only emit methods", () => {
+      const producer = bus.asProducer();
+
+      expect(typeof producer.emit).toBe("function");
+      expect(typeof producer.emitBatch).toBe("function");
+      expect(typeof producer.emitCommand).toBe("function");
+      expect((producer as unknown as { on?: unknown }).on).toBeUndefined();
+    });
+
+    it("should return consumer view with only subscribe methods", () => {
+      const consumer = bus.asConsumer();
+
+      expect(typeof consumer.on).toBe("function");
+      expect(typeof consumer.onAny).toBe("function");
+      expect(typeof consumer.once).toBe("function");
+      expect(typeof consumer.onCommand).toBe("function");
+      expect(typeof consumer.request).toBe("function");
+      expect((consumer as unknown as { emit?: unknown }).emit).toBeUndefined();
+    });
+
+    it("should cache views", () => {
+      const producer1 = bus.asProducer();
+      const producer2 = bus.asProducer();
+      expect(producer1).toBe(producer2);
+
+      const consumer1 = bus.asConsumer();
+      const consumer2 = bus.asConsumer();
+      expect(consumer1).toBe(consumer2);
+    });
+
+    it("producer emit should work", () => {
+      const received: BusEvent[] = [];
+      bus.on("test", (e) => received.push(e));
+
+      const producer = bus.asProducer();
+      producer.emit(createEvent("test"));
+
+      expect(received).toHaveLength(1);
+    });
+
+    it("consumer on should work", () => {
+      const received: BusEvent[] = [];
+      const consumer = bus.asConsumer();
+      consumer.on("test", (e) => received.push(e));
+
+      bus.emit(createEvent("test"));
+
+      expect(received).toHaveLength(1);
+    });
+  });
+
+  describe("destroy", () => {
+    it("should stop emitting after destroy", () => {
+      const received: BusEvent[] = [];
+      bus.on("test", (e) => received.push(e));
+
+      bus.destroy();
+      bus.emit(createEvent("test"));
+
+      expect(received).toHaveLength(0);
+    });
+
+    it("should return no-op unsubscribe after destroy", () => {
+      bus.destroy();
+      const unsubscribe = bus.on("test", () => {});
+
+      // Should not throw
+      expect(() => unsubscribe()).not.toThrow();
+    });
+
+    it("should be idempotent", () => {
+      expect(() => {
+        bus.destroy();
+        bus.destroy();
+        bus.destroy();
+      }).not.toThrow();
+    });
+  });
+
+  describe("error handling", () => {
+    it("should not stop other handlers on error", () => {
+      const received: number[] = [];
+
+      bus.on("test", () => received.push(1));
+      bus.on("test", () => {
+        throw new Error("Handler error");
+      });
+      bus.on("test", () => received.push(3));
+
+      // Should not throw
+      expect(() => bus.emit(createEvent("test"))).not.toThrow();
+
+      // Other handlers should still run
+      expect(received).toEqual([1, 3]);
+    });
+  });
+});

package/src/event/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Event Module
+ *
+ * Central event bus system for ecosystem communication.
+ * Provides type-safe pub/sub event handling with RxJS.
+ *
+ * ## Architecture
+ *
+ * ```
+ * EventBus (interface)
+ * ├── EventProducer (write-only view)
+ * └── EventConsumer (read-only view)
+ *
+ * EventBusImpl (implementation)
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { EventBusImpl, type EventBus } from "@agentxjs/core/event";
+ *
+ * const bus: EventBus = new EventBusImpl();
+ *
+ * // Subscribe to events
+ * bus.on("text_delta", (event) => {
+ *   console.log(event.data.text);
+ * });
+ *
+ * // Emit events
+ * bus.emit({
+ *   type: "text_delta",
+ *   timestamp: Date.now(),
+ *   data: { text: "Hello" },
+ * });
+ *
+ * // Get restricted views for components
+ * const producer = bus.asProducer(); // Can only emit
+ * const consumer = bus.asConsumer(); // Can only subscribe
+ * ```
+ */
+
+// Type definitions from types directory
+export * from "./types";
+
+// Implementation
+export { EventBusImpl } from "./EventBus";