@agentxjs/core 1.9.1-dev

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

@@ -0,0 +1,313 @@
+/**
+ * stateEventProcessor
+ *
+ * Stateless event transformer: Stream Events → State Events
+ *
+ * Input Events (Stream Layer):
+ * - message_start
+ * - message_stop
+ * - text_delta (triggers responding state)
+ * - tool_use_start
+ * - tool_use_stop
+ *
+ * Output Events (State Layer):
+ * - conversation_start
+ * - conversation_responding
+ * - conversation_end
+ * - tool_planned
+ * - tool_executing
+ */
+
+import type { Processor, ProcessorDefinition } from "../mealy";
+import type {
+  // Base type
+  EngineEvent,
+  // Input: StreamEvent (from agent layer)
+  StreamEvent,
+  MessageStartEvent,
+  MessageStopEvent,
+  ToolUseStartEvent,
+  // Output: State events
+  ConversationStartEvent,
+  ConversationRespondingEvent,
+  ConversationEndEvent,
+  ConversationInterruptedEvent,
+  ToolPlannedEvent,
+  ToolExecutingEvent,
+  ErrorOccurredEvent,
+} from "../../types";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("engine/stateEventProcessor");
+
+// ===== State Types =====
+
+/**
+ * StateEventProcessorContext
+ *
+ * Minimal context needed for event transformation logic.
+ * Does NOT track agent state - only auxiliary info for decision-making.
+ *
+ * Currently empty - no context needed as all information comes from events.
+ */
+export interface StateEventProcessorContext {
+  // Empty - all information comes from events
+}
+
+/**
+ * Initial context factory for StateEventProcessor
+ */
+export function createInitialStateEventProcessorContext(): StateEventProcessorContext {
+  return {};
+}
+
+// ===== Processor Implementation =====
+
+/**
+ * Output event types from StateEventProcessor
+ */
+export type StateEventProcessorOutput =
+  | ConversationStartEvent
+  | ConversationRespondingEvent
+  | ConversationEndEvent
+  | ConversationInterruptedEvent
+  | ToolPlannedEvent
+  | ToolExecutingEvent
+  | ErrorOccurredEvent;
+
+/**
+ * Input event types for StateEventProcessor
+ */
+export type StateEventProcessorInput = StreamEvent;
+
+/**
+ * stateEventProcessor
+ *
+ * Stateless event transformer: Stream Events → State Events
+ *
+ * Design:
+ * - Does NOT track agent state (that's StateMachine's job)
+ * - Only maintains auxiliary context (timestamps, etc.)
+ * - Emits State Events that StateMachine consumes
+ *
+ * Pattern: (context, input) => [newContext, outputs]
+ */
+export const stateEventProcessor: Processor<
+  StateEventProcessorContext,
+  StateEventProcessorInput,
+  StateEventProcessorOutput
+> = (context, input): [StateEventProcessorContext, StateEventProcessorOutput[]] => {
+  // Log all incoming Stream Events
+  logger.debug(`[Stream Event] ${input.type}`, {
+    context,
+    eventData: "data" in input ? input.data : undefined,
+  });
+
+  switch (input.type) {
+    case "message_start":
+      return handleMessageStart(context, input);
+
+    case "message_delta":
+      return handleMessageDelta(context);
+
+    case "message_stop":
+      return handleMessageStop(context, input);
+
+    case "text_delta":
+      return handleTextDelta(context);
+
+    case "tool_use_start":
+      return handleToolUseStart(context, input);
+
+    case "tool_use_stop":
+      return handleToolUseStop(context);
+
+    case "error_received":
+      return handleErrorReceived(context, input);
+
+    default:
+      // Pass through unhandled events
+      logger.debug(`[Stream Event] ${input.type} (unhandled)`);
+      return [context, []];
+  }
+};
+
+/**
+ * Handle message_start event
+ *
+ * Emits: conversation_start
+ */
+function handleMessageStart(
+  context: Readonly<StateEventProcessorContext>,
+  event: StreamEvent
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  const { data } = event as MessageStartEvent;
+
+  const conversationStartEvent: ConversationStartEvent = {
+    type: "conversation_start",
+    timestamp: Date.now(),
+    data: {
+      messageId: data.messageId,
+    },
+  };
+
+  return [context, [conversationStartEvent]];
+}
+
+/**
+ * Handle message_delta event
+ *
+ * No longer needed as stopReason is now in message_stop event.
+ * Kept for compatibility with event routing.
+ */
+function handleMessageDelta(
+  context: Readonly<StateEventProcessorContext>
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  // No-op: stopReason now comes from message_stop
+  return [context, []];
+}
+
+/**
+ * Handle message_stop event
+ *
+ * Emits: conversation_end (only if stopReason is NOT "tool_use")
+ *
+ * This event signals that Claude has finished streaming a message.
+ * However, if stopReason is "tool_use", the conversation continues
+ * because Claude will execute tools and send more messages.
+ */
+function handleMessageStop(
+  context: Readonly<StateEventProcessorContext>,
+  event: StreamEvent
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  const { data } = event as MessageStopEvent;
+  const stopReason = data.stopReason;
+
+  logger.debug("message_stop received", { stopReason });
+
+  // If stopReason is "tool_use", don't emit conversation_end
+  // The conversation continues after tool execution
+  if (stopReason === "tool_use") {
+    logger.debug("Skipping conversation_end (tool_use in progress)");
+    return [context, []];
+  }
+
+  // For all other cases (end_turn, max_tokens, etc.), emit conversation_end
+  const conversationEndEvent: ConversationEndEvent = {
+    type: "conversation_end",
+    timestamp: Date.now(),
+    data: {
+      reason: "completed",
+    },
+  };
+
+  return [context, [conversationEndEvent]];
+}
+
+/**
+ * Handle text_delta event
+ *
+ * Emits: conversation_responding
+ */
+function handleTextDelta(
+  context: Readonly<StateEventProcessorContext>
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  const respondingEvent: ConversationRespondingEvent = {
+    type: "conversation_responding",
+    timestamp: Date.now(),
+    data: {},
+  };
+
+  return [context, [respondingEvent]];
+}
+
+/**
+ * Handle tool_use_start event
+ *
+ * Emits: tool_planned, tool_executing
+ */
+function handleToolUseStart(
+  context: Readonly<StateEventProcessorContext>,
+  event: StreamEvent
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  const { data } = event as ToolUseStartEvent;
+  const outputs: StateEventProcessorOutput[] = [];
+
+  // Emit ToolPlannedEvent
+  const toolPlannedEvent: ToolPlannedEvent = {
+    type: "tool_planned",
+    timestamp: Date.now(),
+    data: {
+      toolId: data.toolCallId,
+      toolName: data.toolName,
+    },
+  };
+  outputs.push(toolPlannedEvent);
+
+  // Emit ToolExecutingEvent
+  const toolExecutingEvent: ToolExecutingEvent = {
+    type: "tool_executing",
+    timestamp: Date.now(),
+    data: {
+      toolId: data.toolCallId,
+      toolName: data.toolName,
+      input: {},
+    },
+  };
+  outputs.push(toolExecutingEvent);
+
+  return [context, outputs];
+}
+
+/**
+ * Handle tool_use_stop event
+ *
+ * Pass through - no State Event emitted.
+ * StateMachine handles the state transition internally.
+ */
+function handleToolUseStop(
+  context: Readonly<StateEventProcessorContext>
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  // Pass through - no State Event
+  return [context, []];
+}
+
+/**
+ * Handle error_received event
+ *
+ * Emits: error_occurred
+ */
+function handleErrorReceived(
+  context: Readonly<StateEventProcessorContext>,
+  event: StreamEvent
+): [StateEventProcessorContext, StateEventProcessorOutput[]] {
+  const { data } = event as EngineEvent<"error_received", { message: string; errorCode?: string }>;
+
+  const errorOccurredEvent: ErrorOccurredEvent = {
+    type: "error_occurred",
+    timestamp: Date.now(),
+    data: {
+      code: data.errorCode || "unknown_error",
+      message: data.message,
+      recoverable: true,
+    },
+  };
+
+  return [context, [errorOccurredEvent]];
+}
+
+/**
+ * StateEvent Processor Definition
+ *
+ * Stateless event transformer: Stream Events → State Events
+ */
+export const stateEventProcessorDef: ProcessorDefinition<
+  StateEventProcessorContext,
+  StateEventProcessorInput,
+  StateEventProcessorOutput
+> = {
+  name: "StateEventProcessor",
+  description: "Transform Stream Events into State Events",
+  initialState: createInitialStateEventProcessorContext,
+  processor: stateEventProcessor,
+};

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

@@ -0,0 +1,239 @@
+/**
+ * turnTrackerProcessor
+ *
+ * Pure Mealy transition function that tracks request-response turn pairs.
+ *
+ * Input Events:
+ * - user_message (Message Layer)
+ * - message_stop (Stream Layer - contains stop reason)
+ * - assistant_message (Message Layer)
+ *
+ * Output Events (Turn Layer):
+ * - turn_request
+ * - turn_response
+ */
+
+import type { Processor, ProcessorDefinition } from "../mealy";
+import type {
+  // Input: combined stream and message events
+  StreamEvent,
+  AgentMessageEvent,
+  MessageStopEvent,
+  UserMessageEvent,
+  // Output: Turn events
+  TurnRequestEvent,
+  TurnResponseEvent,
+  // Data types
+  TokenUsage,
+} from "../../types";
+
+// ===== State Types =====
+
+/**
+ * Pending turn tracking
+ */
+export interface PendingTurn {
+  turnId: string;
+  messageId: string;
+  content: string;
+  requestedAt: number;
+}
+
+/**
+ * TurnTrackerState
+ *
+ * Tracks the current turn state.
+ */
+export interface TurnTrackerState {
+  /**
+   * Currently pending turn (waiting for response)
+   */
+  pendingTurn: PendingTurn | null;
+
+  /**
+   * Cost per input token (USD)
+   */
+  costPerInputToken: number;
+
+  /**
+   * Cost per output token (USD)
+   */
+  costPerOutputToken: number;
+}
+
+/**
+ * Initial state factory for TurnTracker
+ */
+export function createInitialTurnTrackerState(): TurnTrackerState {
+  return {
+    pendingTurn: null,
+    costPerInputToken: 0.000003, // $3 per 1M tokens
+    costPerOutputToken: 0.000015, // $15 per 1M tokens
+  };
+}
+
+// ===== Processor Implementation =====
+
+/**
+ * Generate a unique ID
+ */
+function generateId(): string {
+  return `turn_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+
+/**
+ * Output event types from TurnTracker
+ */
+export type TurnTrackerOutput = TurnRequestEvent | TurnResponseEvent;
+
+/**
+ * Input event types for TurnTracker
+ * Accepts both Stream and Message layer events
+ */
+export type TurnTrackerInput = StreamEvent | AgentMessageEvent;
+
+/**
+ * turnTrackerProcessor
+ *
+ * Pure Mealy transition function for turn tracking.
+ * Pattern: (state, input) => [newState, outputs]
+ */
+export const turnTrackerProcessor: Processor<
+  TurnTrackerState,
+  TurnTrackerInput,
+  TurnTrackerOutput
+> = (state, input): [TurnTrackerState, TurnTrackerOutput[]] => {
+  switch (input.type) {
+    case "user_message":
+      return handleUserMessage(state, input as AgentMessageEvent);
+
+    case "message_stop":
+      return handleMessageStop(state, input as StreamEvent);
+
+    case "assistant_message":
+      // Turn completion is handled in message_stop
+      // This handler is kept for potential future use
+      return [state, []];
+
+    default:
+      return [state, []];
+  }
+};
+
+/**
+ * Handle user_message event
+ */
+function handleUserMessage(
+  state: Readonly<TurnTrackerState>,
+  event: AgentMessageEvent
+): [TurnTrackerState, TurnTrackerOutput[]] {
+  const { data } = event as UserMessageEvent;
+  const turnId = generateId();
+
+  // Extract content as string (UserMessage.content can be string or array)
+  const contentText = typeof data.content === "string" ? data.content : "";
+
+  const pendingTurn: PendingTurn = {
+    turnId,
+    messageId: data.id,
+    content: contentText,
+    requestedAt: event.timestamp,
+  };
+
+  const turnRequestEvent: TurnRequestEvent = {
+    type: "turn_request",
+    timestamp: Date.now(),
+    data: {
+      turnId,
+      messageId: data.id,
+      content: contentText,
+      timestamp: event.timestamp,
+    },
+  };
+
+  return [
+    {
+      ...state,
+      pendingTurn,
+    },
+    [turnRequestEvent],
+  ];
+}
+
+/**
+ * Handle message_stop event
+ */
+function handleMessageStop(
+  state: Readonly<TurnTrackerState>,
+  event: StreamEvent
+): [TurnTrackerState, TurnTrackerOutput[]] {
+  if (!state.pendingTurn) {
+    return [state, []];
+  }
+
+  const { data } = event as MessageStopEvent;
+  const stopReason = data.stopReason;
+
+  // Complete turn based on stop reason
+  // - "end_turn": Normal completion (no tool use)
+  // - "tool_use": Tool calling in progress, DON'T complete yet
+  // - "max_tokens": Hit token limit, complete turn
+  // - "stop_sequence": Hit stop sequence, complete turn
+  if (stopReason === "end_turn" || stopReason === "max_tokens" || stopReason === "stop_sequence") {
+    return completeTurn(state, event.timestamp);
+  }
+
+  // For tool_use, don't complete turn yet
+  return [state, []];
+}
+
+/**
+ * Complete the turn and emit TurnResponseEvent
+ */
+function completeTurn(
+  state: Readonly<TurnTrackerState>,
+  completedAt: number
+): [TurnTrackerState, TurnTrackerOutput[]] {
+  if (!state.pendingTurn) {
+    return [state, []];
+  }
+
+  const { turnId, messageId, requestedAt } = state.pendingTurn;
+  const duration = completedAt - requestedAt;
+
+  const usage: TokenUsage = { inputTokens: 0, outputTokens: 0 };
+
+  const turnResponseEvent: TurnResponseEvent = {
+    type: "turn_response",
+    timestamp: Date.now(),
+    data: {
+      turnId,
+      messageId,
+      duration,
+      usage,
+      timestamp: completedAt,
+    },
+  };
+
+  return [
+    {
+      ...state,
+      pendingTurn: null,
+    },
+    [turnResponseEvent],
+  ];
+}
+
+/**
+ * TurnTracker Processor Definition
+ */
+export const turnTrackerProcessorDef: ProcessorDefinition<
+  TurnTrackerState,
+  TurnTrackerInput,
+  TurnTrackerOutput
+> = {
+  name: "TurnTracker",
+  description: "Tracks request-response turn pairs",
+  initialState: createInitialTurnTrackerState,
+  processor: turnTrackerProcessor,
+};