@agentxjs/core 1.9.1-dev

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

@@ -0,0 +1,176 @@
+/**
+ * Combinators - Functions to compose multiple Processors
+ *
+ * These utilities allow building complex stream processing pipelines
+ * from simple, composable Processor functions.
+ */
+
+import type { Processor } from "./Processor";
+
+/**
+ * combineProcessors - Combine multiple processors into one
+ *
+ * Each sub-processor manages its own slice of state.
+ * All processors receive the same event and their outputs are merged.
+ *
+ * @example
+ * ```typescript
+ * interface CombinedState {
+ *   message: MessageState;
+ *   state: StateMachineState;
+ *   turn: TurnState;
+ * }
+ *
+ * const combinedProcessor = combineProcessors<CombinedState, Event, Event>({
+ *   message: messageProcessor,
+ *   state: stateMachineProcessor,
+ *   turn: turnTrackerProcessor,
+ * });
+ * ```
+ */
+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[] = [];
+
+    for (const key in processors) {
+      const processor = processors[key];
+      const subState = state[key];
+      const [newSubState, outputs] = processor(subState, event);
+
+      newState[key] = newSubState;
+      allOutputs.push(...outputs);
+    }
+
+    return [newState, allOutputs];
+  };
+}
+
+/**
+ * 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 {
+  return () => {
+    const state = {} as TState;
+    for (const key in initialStates) {
+      state[key] = initialStates[key]();
+    }
+    return state;
+  };
+}
+
+/**
+ * chainProcessors - Chain processors where output of one feeds into the next
+ *
+ * Useful for layered event processing:
+ * Stream Events → Message Events → Turn Events
+ *
+ * @example
+ * ```typescript
+ * const pipeline = chainProcessors(
+ *   streamToMessageProcessor,
+ *   messageToTurnProcessor,
+ * );
+ * ```
+ */
+export function chainProcessors<TState, TEvent>(
+  ...processors: Processor<TState, TEvent, TEvent>[]
+): Processor<TState, TEvent, TEvent> {
+  return (state: Readonly<TState>, event: TEvent): [TState, TEvent[]] => {
+    let currentState = state as TState;
+    const finalOutputs: TEvent[] = [];
+
+    // Run the event through all processors
+    for (const processor of processors) {
+      const [newState, outputs] = processor(currentState, event);
+      currentState = newState;
+      finalOutputs.push(...outputs);
+    }
+
+    return [currentState, finalOutputs];
+  };
+}
+
+/**
+ * filterProcessor - Create a processor that only processes certain events
+ *
+ * @example
+ * ```typescript
+ * const textOnlyProcessor = filterProcessor(
+ *   (event) => event.type === 'text_delta',
+ *   textProcessor,
+ * );
+ * ```
+ */
+export function filterProcessor<TState, TInput, TOutput>(
+  predicate: (event: TInput) => boolean,
+  processor: Processor<TState, TInput, TOutput>
+): Processor<TState, TInput, TOutput> {
+  return (state: Readonly<TState>, event: TInput): [TState, TOutput[]] => {
+    if (predicate(event)) {
+      return processor(state, event);
+    }
+    return [state as TState, []];
+  };
+}
+
+/**
+ * mapOutput - Transform output events
+ *
+ * @example
+ * ```typescript
+ * const withTimestamp = mapOutput(
+ *   myProcessor,
+ *   (output) => ({ ...output, processedAt: Date.now() }),
+ * );
+ * ```
+ */
+export function mapOutput<TState, TInput, TOutput, TMapped>(
+  processor: Processor<TState, TInput, TOutput>,
+  mapper: (output: TOutput) => TMapped
+): Processor<TState, TInput, TMapped> {
+  return (state: Readonly<TState>, event: TInput): [TState, TMapped[]] => {
+    const [newState, outputs] = processor(state, event);
+    return [newState, outputs.map(mapper)];
+  };
+}
+
+/**
+ * withLogging - Add logging to a processor (for debugging)
+ *
+ * @example
+ * ```typescript
+ * const debugProcessor = withLogging(myProcessor, 'MyProcessor');
+ * ```
+ */
+export function withLogging<TState, TInput, TOutput>(
+  processor: Processor<TState, TInput, TOutput>,
+  name: string,
+  logger: {
+    debug: (message: string, data?: unknown) => void;
+  } = console
+): Processor<TState, TInput, TOutput> {
+  return (state: Readonly<TState>, event: TInput): [TState, TOutput[]] => {
+    logger.debug(`[${name}] Input:`, { event, state });
+    const [newState, outputs] = processor(state, event);
+    logger.debug(`[${name}] Output:`, { newState, outputs });
+    return [newState, outputs];
+  };
+}
+
+/**
+ * identityProcessor - A processor that does nothing (useful as default)
+ */
+export function identityProcessor<TState, TEvent>(): Processor<TState, TEvent, TEvent> {
+  return (state: Readonly<TState>, _event: TEvent): [TState, TEvent[]] => {
+    return [state as TState, []];
+  };
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Mealy - Functional Mealy Machine Framework
+ *
+ * A Mealy Machine is a finite-state machine where outputs depend on
+ * both the current state AND the input: (state, input) => (state, output)
+ *
+ * Components:
+ * - Source: Receives external input (input adapter with side effects)
+ * - Processor: Pure Mealy transition function (state is means, outputs are goal)
+ * - Sink: Produces output effects (output adapter with side effects)
+ * - Store: State storage (external state persistence)
+ *
+ * Key Insight: Unlike Redux reducers where state is the goal,
+ * in Mealy Machine the state is just a means - outputs are the goal.
+ */
+
+// ===== 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";
+
+// Sink - Output (output adapter)
+export { type Sink, type SinkDefinition } from "./Sink";
+
+// Store - State storage
+export { type Store, MemoryStore } from "./Store";
+
+// ===== Mealy Runtime =====
+
+export { Mealy, createMealy, type MealyConfig, type ProcessResult } from "./Mealy";
+
+// ===== Combinators =====
+
+export {
+  combineProcessors,
+  combineInitialStates,
+  chainProcessors,
+  filterProcessor,
+  mapOutput,
+  withLogging,
+  identityProcessor,
+} from "./combinators";

package/src/agent/index.ts

@@ -0,0 +1,106 @@
+/**
+ * @agentxjs/agent
+ *
+ * Agent package - Event Processing Unit for AI conversations.
+ *
+ * ## Core API
+ *
+ * ```typescript
+ * import { createAgent } from "@agentxjs/agent";
+ *
+ * const agent = createAgent({
+ *   driver: myDriver,
+ *   presenter: myPresenter,
+ * });
+ *
+ * agent.on("text_delta", (e) => console.log(e.data.text));
+ * await agent.receive("Hello!");
+ * ```
+ *
+ * ## Architecture
+ *
+ * - Driver: Produces StreamEvents from LLM
+ * - Agent: Processes events, manages state and queue
+ * - Presenter: Consumes AgentOutput events
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Core API
+// ============================================================================
+
+export { createAgent } from "./createAgent";
+export { AgentStateMachine } from "./AgentStateMachine";
+export type { AgentEngine, CreateAgentOptions } from "./types";
+
+// ============================================================================
+// Types (re-export all types from types.ts)
+// ============================================================================
+
+export * from "./types";
+
+// ============================================================================
+// Engine (Stateless)
+// ============================================================================
+
+// MealyMachine
+export { MealyMachine, createMealyMachine } from "./engine/MealyMachine";
+
+// AgentProcessor (for advanced use cases)
+export {
+  agentProcessor,
+  createInitialAgentEngineState,
+  type AgentEngineState,
+  type AgentProcessorInput,
+  type AgentProcessorOutput,
+} from "./engine/AgentProcessor";
+
+// Internal Processors (for advanced use cases)
+export {
+  // MessageAssembler
+  messageAssemblerProcessor,
+  messageAssemblerProcessorDef,
+  type MessageAssemblerInput,
+  type MessageAssemblerOutput,
+  type MessageAssemblerState,
+  type PendingContent,
+  createInitialMessageAssemblerState,
+  // StateEventProcessor
+  stateEventProcessor,
+  stateEventProcessorDef,
+  type StateEventProcessorInput,
+  type StateEventProcessorOutput,
+  type StateEventProcessorContext,
+  createInitialStateEventProcessorContext,
+  // TurnTracker
+  turnTrackerProcessor,
+  turnTrackerProcessorDef,
+  type TurnTrackerInput,
+  type TurnTrackerOutput,
+  type TurnTrackerState,
+  type PendingTurn,
+  createInitialTurnTrackerState,
+} from "./engine/internal";
+
+// Mealy Machine Core (for building custom processors)
+export {
+  // Core types
+  type Source,
+  type SourceDefinition,
+  type Processor,
+  type ProcessorResult,
+  type ProcessorDefinition,
+  type Sink,
+  type SinkDefinition,
+  type Store,
+  MemoryStore,
+  // Combinators
+  combineProcessors,
+  combineInitialStates,
+  chainProcessors,
+  filterProcessor,
+  mapOutput,
+  withLogging,
+  identityProcessor,
+} from "./engine/mealy";

package/src/agent/types/engine.ts

@@ -0,0 +1,395 @@
+/**
+ * Engine Types - AgentEngine, Driver, Presenter, and related infrastructure
+ *
+ * This file defines:
+ * - MessageQueue: Read-only view of message queue state
+ * - AgentEngine: Event processing unit interface
+ * - AgentDriver: Input adapter for external events
+ * - AgentPresenter: Output adapter for external systems
+ * - Middleware and Interceptor types
+ * - StateMachine interface
+ * - CreateAgentOptions: Factory options
+ *
+ * @packageDocumentation
+ */
+
+import type { UserMessage } from "./message";
+import type {
+  AgentState,
+  AgentOutput,
+  StreamEvent,
+  Unsubscribe,
+  AgentOutputCallback,
+} from "./event";
+
+// =============================================================================
+// Message Queue
+// =============================================================================
+
+/**
+ * MessageQueue interface
+ *
+ * Read-only view of the message queue state.
+ */
+export interface MessageQueue {
+  /**
+   * Number of messages in queue
+   */
+  readonly length: number;
+
+  /**
+   * Whether queue is empty
+   */
+  readonly isEmpty: boolean;
+}
+
+// =============================================================================
+// Middleware & Interceptor
+// =============================================================================
+
+/**
+ * Next function to continue the middleware chain
+ */
+export type AgentMiddlewareNext = (message: UserMessage) => Promise<void>;
+
+/**
+ * Middleware function type
+ *
+ * @param message - The user message being processed
+ * @param next - Call to continue to next middleware or actual receive
+ */
+export type AgentMiddleware = (message: UserMessage, next: AgentMiddlewareNext) => Promise<void>;
+
+/**
+ * Next function to continue the interceptor chain
+ */
+export type AgentInterceptorNext = (event: AgentOutput) => void;
+
+/**
+ * Interceptor function type
+ *
+ * @param event - The event being dispatched
+ * @param next - Call to continue to next interceptor or actual dispatch
+ */
+export type AgentInterceptor = (event: AgentOutput, next: AgentInterceptorNext) => void;
+
+// =============================================================================
+// State Machine
+// =============================================================================
+
+/**
+ * State change event payload
+ */
+export interface StateChange {
+  prev: AgentState;
+  current: AgentState;
+}
+
+/**
+ * State change handler type
+ */
+export type StateChangeHandler = (change: StateChange) => void;
+
+/**
+ * AgentStateMachine interface
+ *
+ * Processes StateEvents to update internal agent state and notify subscribers.
+ */
+export interface AgentStateMachineInterface {
+  /**
+   * Current agent state
+   */
+  readonly state: AgentState;
+
+  /**
+   * Process a StateEvent and update internal state
+   *
+   * @param event - StateEvent from MealyMachine
+   */
+  process(event: AgentOutput): void;
+
+  /**
+   * Subscribe to state changes
+   *
+   * @param handler - Callback receiving { prev, current } state change
+   * @returns Unsubscribe function
+   */
+  onStateChange(handler: StateChangeHandler): Unsubscribe;
+
+  /**
+   * Reset state machine (used on destroy)
+   */
+  reset(): void;
+}
+
+// =============================================================================
+// Event Handler Maps
+// =============================================================================
+
+/**
+ * Event handler map for batch subscription
+ *
+ * Generic handler map - concrete event types are defined in runtime/event.
+ * AgentEngine package is independent of specific event type definitions.
+ *
+ * Usage:
+ * ```typescript
+ * engine.on({
+ *   text_delta: (event) => console.log(event.data.text),
+ *   assistant_message: (event) => setMessages(prev => [...prev, event.data]),
+ * });
+ * ```
+ */
+export type EventHandlerMap = Record<string, ((event: AgentOutput) => void) | undefined>;
+
+/**
+ * React-style handler map for fluent event subscription
+ *
+ * Generic handler map - concrete event types are defined in runtime/event.
+ * AgentEngine package is independent of specific event type definitions.
+ *
+ * Usage:
+ * ```typescript
+ * engine.react({
+ *   onTextDelta: (event) => console.log(event.data.text),
+ *   onAssistantMessage: (event) => setMessages(prev => [...prev, event.data]),
+ * });
+ * ```
+ */
+export type ReactHandlerMap = Record<string, ((event: AgentOutput) => void) | undefined>;
+
+// =============================================================================
+// Agent Engine
+// =============================================================================
+
+/**
+ * AgentEngine interface - Event Processing Unit
+ *
+ * Core responsibilities:
+ * - State management (AgentState)
+ * - Event subscription and distribution
+ * - Middleware/Interceptor chain
+ */
+export interface AgentEngine {
+  /**
+   * Unique agent instance ID
+   */
+  readonly agentId: string;
+
+  /**
+   * Creation timestamp
+   */
+  readonly createdAt: number;
+
+  /**
+   * Current conversation state
+   */
+  readonly state: AgentState;
+
+  /**
+   * Message queue for pending messages
+   */
+  readonly messageQueue: MessageQueue;
+
+  /**
+   * Receive a message from user
+   *
+   * @param message - String content or UserMessage object
+   * @deprecated Use handleStreamEvent for push-based event processing
+   */
+  receive(message: string | UserMessage): Promise<void>;
+
+  /**
+   * Handle a stream event from the driver
+   *
+   * This is the push-based API for event processing.
+   * Events are pushed by BusDriver when DriveableEvents arrive.
+   *
+   * @param event - StreamEvent to process through MealyMachine
+   */
+  handleStreamEvent(event: StreamEvent): void;
+
+  /**
+   * Subscribe to all events
+   */
+  on(handler: AgentOutputCallback): Unsubscribe;
+
+  /**
+   * Batch subscribe to multiple event types
+   */
+  on(handlers: EventHandlerMap): Unsubscribe;
+
+  /**
+   * Subscribe to specific event type by name
+   */
+  on(type: string, handler: AgentOutputCallback): Unsubscribe;
+
+  /**
+   * Subscribe to multiple event types by name
+   */
+  on(types: string[], handler: AgentOutputCallback): Unsubscribe;
+
+  /**
+   * Subscribe to state changes
+   *
+   * @param handler - Callback receiving { prev, current } state change
+   * @returns Unsubscribe function
+   */
+  onStateChange(handler: StateChangeHandler): Unsubscribe;
+
+  /**
+   * React-style fluent event subscription
+   */
+  react(handlers: ReactHandlerMap): Unsubscribe;
+
+  /**
+   * Subscribe to agent ready event
+   *
+   * Called when agent is ready to receive messages.
+   * If already ready, handler is called immediately.
+   */
+  onReady(handler: () => void): Unsubscribe;
+
+  /**
+   * Subscribe to agent destroy event
+   *
+   * Called when agent is destroyed.
+   */
+  onDestroy(handler: () => void): Unsubscribe;
+
+  /**
+   * Add middleware to intercept incoming messages (receive side)
+   */
+  use(middleware: AgentMiddleware): Unsubscribe;
+
+  /**
+   * Add interceptor to intercept outgoing events (event side)
+   */
+  intercept(interceptor: AgentInterceptor): Unsubscribe;
+
+  /**
+   * Interrupt - User-initiated stop
+   *
+   * Stops the current operation gracefully.
+   * The agent will return to idle state.
+   */
+  interrupt(): void;
+
+  /**
+   * Destroy - Clean up resources
+   */
+  destroy(): Promise<void>;
+}
+
+// =============================================================================
+// Source & Presenter (EventBus adapters)
+// =============================================================================
+
+/**
+ * AgentSource interface
+ *
+ * Subscribes to EventBus for StreamEvents and forwards them to AgentEngine.
+ * This is the input adapter: EventBus → AgentEngine
+ *
+ * ```
+ * EventBus ──subscribe──► Source ──handleStreamEvent──► AgentEngine
+ * ```
+ */
+export interface AgentSource {
+  /**
+   * Source name (for identification and logging)
+   */
+  readonly name: string;
+
+  /**
+   * Connect to EventBus and start forwarding StreamEvents
+   *
+   * @param onEvent - Callback to invoke when StreamEvent is received
+   */
+  connect(onEvent: (event: StreamEvent) => void): void;
+
+  /**
+   * Disconnect from EventBus
+   */
+  disconnect(): void;
+}
+
+/**
+ * AgentPresenter interface
+ *
+ * Publishes AgentOutput to EventBus.
+ * This is the output adapter: AgentEngine → EventBus
+ *
+ * ```
+ * AgentEngine ──present──► Presenter ──emit──► EventBus
+ * ```
+ */
+export interface AgentPresenter {
+  /**
+   * Presenter name (for identification and logging)
+   */
+  readonly name: string;
+
+  /**
+   * Publish an agent output to EventBus
+   *
+   * @param agentId - The agent ID
+   * @param output - The output to publish
+   */
+  present(agentId: string, output: AgentOutput): void;
+}
+
+// =============================================================================
+// Factory Options
+// =============================================================================
+
+/**
+ * EventBus interface (minimal subset needed by AgentEngine)
+ */
+export interface AgentEventBus {
+  /**
+   * Emit an event to the bus
+   */
+  emit(event: unknown): void;
+
+  /**
+   * Subscribe to events
+   */
+  on(type: string, handler: (event: unknown) => void): () => void;
+
+  /**
+   * Subscribe to all events
+   */
+  onAny(handler: (event: unknown) => void): () => void;
+}
+
+/**
+ * Options for creating an AgentEngine
+ */
+export interface CreateAgentOptions {
+  /**
+   * Agent ID (optional, auto-generated if not provided)
+   */
+  agentId?: string;
+
+  /**
+   * EventBus connection
+   * AgentEngine uses this to:
+   * - emit user_message when receive() is called
+   * - Source subscribes to StreamEvent
+   * - Presenter emits AgentOutput
+   */
+  bus: AgentEventBus;
+
+  /**
+   * Source - Subscribes to EventBus, forwards StreamEvent to AgentEngine
+   * Optional: default implementation subscribes to StreamEvent types
+   */
+  source?: AgentSource;
+
+  /**
+   * Presenter - Publishes AgentOutput to EventBus
+   * Optional: default implementation emits to bus
+   */
+  presenter?: AgentPresenter;
+}