@agentxjs/types 0.0.9 → 1.1.3

package/dist/Agent-BXUYGlWZ.d.cts

@@ -0,0 +1,510 @@
+import { h as AgentTurnEvent$1, i as TurnRequestEvent$1, j as TurnResponseEvent$1, U as UserMessage } from './ToolResultMessage-CRKMSf5d.cjs';
+import { A as AgentStreamEvent, a as AgentMessageStartEvent, b as AgentMessageDeltaEvent, c as AgentMessageStopEvent, d as AgentTextDeltaEvent, e as AgentToolUseStartEvent, f as AgentInputJsonDeltaEvent, g as AgentToolUseStopEvent, h as AgentToolResultEvent, i as AgentStateEvent$1, C as ConversationQueuedEvent$1, j as ConversationStartEvent$1, k as ConversationThinkingEvent$1, l as ConversationRespondingEvent$1, m as ConversationEndEvent$1, n as ConversationInterruptedEvent$1, T as ToolPlannedEvent$1, o as ToolExecutingEvent$1, p as ToolCompletedEvent$1, q as ToolFailedEvent$1, E as ErrorOccurredEvent$1, r as AgentMessageEvent$1, U as UserMessageEvent$1, s as AssistantMessageEvent$1, t as ToolCallMessageEvent$1, u as ToolResultMessageEvent$1, v as ErrorMessageEvent$1 } from './index-CjFNcCxR.cjs';
+
+/**
+ * EngineEvent - Lightweight event base for AgentEngine domain
+ *
+ * EngineEvent is the simplified event structure used inside AgentEngine.
+ * It only contains: type, timestamp, data
+ *
+ * This is distinct from the full AgentEvent (in @agentxjs/types/event/agent)
+ * which extends SystemEvent with source, category, intent, context.
+ *
+ * ## Relationship
+ *
+ * ```
+ * AgentEvent (Runtime domain)          EngineEvent (Engine domain)
+ * ─────────────────────────────────────────────────────────────────
+ * {                                    {
+ *   type: "text_delta",                  type: "text_delta",
+ *   timestamp: 123,                      timestamp: 123,
+ *   data: { text: "Hi" },                data: { text: "Hi" },
+ *   source: "agent",          ←── not in Engine
+ *   category: "stream",       ←── not in Engine
+ *   intent: "notification",   ←── not in Engine
+ *   context: { ... },         ←── not in Engine
+ * }                                    }
+ * ```
+ *
+ * Use `ToEngineEvent<T>` to convert AgentEvent to EngineEvent.
+ */
+/**
+ * EngineEvent - Lightweight event for Engine internal use
+ *
+ * Only contains the essential fields:
+ * - type: What happened
+ * - timestamp: When it happened
+ * - data: Event payload
+ */
+interface EngineEvent<T extends string = string, D = unknown> {
+    /**
+     * Event type identifier (e.g., "text_delta", "assistant_message")
+     */
+    readonly type: T;
+    /**
+     * Event timestamp (Unix milliseconds)
+     */
+    readonly timestamp: number;
+    /**
+     * Event payload data
+     */
+    readonly data: D;
+}
+/**
+ * ToEngineEvent - Extract lightweight event from full AgentEvent
+ *
+ * Picks only { type, timestamp, data } from the full SystemEvent structure.
+ *
+ * @example
+ * ```typescript
+ * import type { TextDeltaEvent as FullTextDeltaEvent } from "@agentxjs/types/event/agent";
+ * import type { ToEngineEvent } from "./EngineEvent";
+ *
+ * // FullTextDeltaEvent has: type, timestamp, data, source, category, intent, context
+ * // TextDeltaEvent only has: type, timestamp, data
+ * type TextDeltaEvent = ToEngineEvent<FullTextDeltaEvent>;
+ * ```
+ */
+type ToEngineEvent<E> = E extends {
+    type: infer T;
+    timestamp: number;
+    data: infer D;
+} ? EngineEvent<T extends string ? T : string, D> : never;
+/**
+ * ToEngineEventUnion - Convert a union of AgentEvents to EngineEvents
+ *
+ * @example
+ * ```typescript
+ * type AgentStreamEvent = TextDeltaEvent | MessageStartEvent | ...;
+ * type StreamEvent = ToEngineEventUnion<AgentStreamEvent>;
+ * // StreamEvent is now the lightweight version of each event in the union
+ * ```
+ */
+type ToEngineEventUnion<E> = E extends unknown ? ToEngineEvent<E> : never;
+
+/**
+ * Engine Turn Events (Lightweight)
+ *
+ * Lightweight turn events for AgentEngine internal use.
+ * Derived from full AgentTurnEvent in @agentxjs/types/event/agent.
+ */
+
+/**
+ * TurnEvent - Base type for turn events
+ * @deprecated Use specific event types instead
+ */
+interface TurnEvent<T extends string = string, D = unknown> extends EngineEvent<T, D> {
+}
+type TurnRequestEvent = ToEngineEvent<TurnRequestEvent$1>;
+type TurnResponseEvent = ToEngineEvent<TurnResponseEvent$1>;
+/**
+ * AgentTurnEvent - All lightweight turn events
+ */
+type AgentTurnEvent = ToEngineEventUnion<AgentTurnEvent$1>;
+/**
+ * Type guard: is this a turn event?
+ */
+declare function isTurnEvent(event: EngineEvent): event is AgentTurnEvent;
+
+/**
+ * Engine Stream Events (Lightweight)
+ *
+ * Lightweight stream events for AgentEngine internal use.
+ * Derived from full AgentStreamEvent in @agentxjs/types/event/agent.
+ */
+
+type MessageStartEvent = ToEngineEvent<AgentMessageStartEvent>;
+type MessageDeltaEvent = ToEngineEvent<AgentMessageDeltaEvent>;
+type MessageStopEvent = ToEngineEvent<AgentMessageStopEvent>;
+type TextDeltaEvent = ToEngineEvent<AgentTextDeltaEvent>;
+type ToolUseStartEvent = ToEngineEvent<AgentToolUseStartEvent>;
+type InputJsonDeltaEvent = ToEngineEvent<AgentInputJsonDeltaEvent>;
+type ToolUseStopEvent = ToEngineEvent<AgentToolUseStopEvent>;
+type ToolResultEvent = ToEngineEvent<AgentToolResultEvent>;
+/**
+ * StreamEvent - All lightweight stream events
+ */
+type StreamEvent = ToEngineEventUnion<AgentStreamEvent>;
+/**
+ * StreamEventType - String literal union
+ */
+type StreamEventType = StreamEvent["type"];
+
+/**
+ * AgentState
+ *
+ * Agent conversation states for fine-grained monitoring.
+ *
+ * State transitions:
+ * ```
+ * idle → thinking → responding → idle
+ *                       ↓
+ *              planning_tool → awaiting_tool_result
+ *                       ↓
+ *                   thinking → responding → idle
+ *
+ * Any state can transition to error:
+ * thinking/responding/planning_tool/awaiting_tool_result → error → idle
+ * ```
+ */
+/**
+ * Agent state types
+ */
+type AgentState = "idle" | "thinking" | "responding" | "planning_tool" | "awaiting_tool_result" | "error";
+
+/**
+ * Engine State Events (Lightweight)
+ *
+ * Lightweight state events for AgentEngine internal use.
+ * Derived from full AgentStateEvent in @agentxjs/types/event/agent.
+ */
+
+/**
+ * StateEvent - Base type for state events
+ * @deprecated Use specific event types instead
+ */
+interface StateEvent<T extends string = string, D = unknown> extends EngineEvent<T, D> {
+}
+type ConversationQueuedEvent = ToEngineEvent<ConversationQueuedEvent$1>;
+type ConversationStartEvent = ToEngineEvent<ConversationStartEvent$1>;
+type ConversationThinkingEvent = ToEngineEvent<ConversationThinkingEvent$1>;
+type ConversationRespondingEvent = ToEngineEvent<ConversationRespondingEvent$1>;
+type ConversationEndEvent = ToEngineEvent<ConversationEndEvent$1>;
+type ConversationInterruptedEvent = ToEngineEvent<ConversationInterruptedEvent$1>;
+type ToolPlannedEvent = ToEngineEvent<ToolPlannedEvent$1>;
+type ToolExecutingEvent = ToEngineEvent<ToolExecutingEvent$1>;
+type ToolCompletedEvent = ToEngineEvent<ToolCompletedEvent$1>;
+type ToolFailedEvent = ToEngineEvent<ToolFailedEvent$1>;
+type ErrorOccurredEvent = ToEngineEvent<ErrorOccurredEvent$1>;
+/**
+ * Alias for ErrorOccurredEvent (legacy compatibility)
+ */
+type AgentErrorOccurredEvent = ErrorOccurredEvent;
+/**
+ * AgentStateEvent - All lightweight state events
+ */
+type AgentStateEvent = ToEngineEventUnion<AgentStateEvent$1>;
+/**
+ * Type guard: is this a state event?
+ */
+declare function isStateEvent(event: EngineEvent): event is AgentStateEvent;
+
+/**
+ * Engine Message Events (Lightweight)
+ *
+ * Lightweight message events for AgentEngine internal use.
+ * Derived from full AgentMessageEvent in @agentxjs/types/event/agent.
+ */
+
+/**
+ * MessageEvent - Base type for message events
+ * @deprecated Use specific event types instead
+ */
+interface MessageEvent<T extends string = string, D = unknown> extends EngineEvent<T, D> {
+}
+type UserMessageEvent = ToEngineEvent<UserMessageEvent$1>;
+type AssistantMessageEvent = ToEngineEvent<AssistantMessageEvent$1>;
+type ToolCallMessageEvent = ToEngineEvent<ToolCallMessageEvent$1>;
+type ToolResultMessageEvent = ToEngineEvent<ToolResultMessageEvent$1>;
+type ErrorMessageEvent = ToEngineEvent<ErrorMessageEvent$1>;
+/**
+ * AgentMessageEvent - All lightweight message events
+ */
+type AgentMessageEvent = ToEngineEventUnion<AgentMessageEvent$1>;
+/**
+ * Type guard: is this a message event?
+ */
+declare function isMessageEvent(event: EngineEvent): event is AgentMessageEvent;
+
+/**
+ * AgentOutput - Union of all possible agent output events
+ *
+ * Includes all event layers:
+ * - Stream: Real-time streaming events from Driver
+ * - State: State machine transitions
+ * - Message: Assembled messages
+ * - Turn: Turn analytics
+ */
+
+/**
+ * All possible output types from Agent
+ */
+type AgentOutput = StreamEvent | AgentStateEvent | AgentMessageEvent | AgentTurnEvent;
+
+/**
+ * AgentOutputCallback - Event subscription callback types
+ *
+ * Callback function types for subscribing to AgentOutput events.
+ * Renamed from AgentEventHandler to avoid confusion with Handler classes.
+ */
+
+/**
+ * Unsubscribe function returned by on()
+ */
+type Unsubscribe = () => void;
+/**
+ * Agent output event callback function type
+ */
+type AgentOutputCallback<T extends AgentOutput = AgentOutput> = (event: T) => void;
+/**
+ * @deprecated Use AgentOutputCallback instead
+ */
+type AgentEventHandler<T extends AgentOutput = AgentOutput> = AgentOutputCallback<T>;
+
+/**
+ * AgentMiddleware - Input-side interceptor for receive()
+ *
+ * Intercepts user messages before they are processed by the driver.
+ *
+ * Usage:
+ * ```typescript
+ * agent.use(async (message, next) => {
+ *   console.log('[Before]', message.content);
+ *   await next(message);
+ *   console.log('[After]');
+ * });
+ * ```
+ */
+
+/**
+ * Next function to continue the middleware chain
+ */
+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
+ */
+type AgentMiddleware = (message: UserMessage, next: AgentMiddlewareNext) => Promise<void>;
+
+/**
+ * AgentInterceptor - Output-side interceptor for events
+ *
+ * Intercepts events before they are dispatched to handlers.
+ *
+ * Usage:
+ * ```typescript
+ * agent.intercept((event, next) => {
+ *   console.log('Event:', event.type);
+ *
+ *   // Modify event
+ *   if (event.type === 'text_delta') {
+ *     event.data.text = maskSensitive(event.data.text);
+ *   }
+ *
+ *   // Continue to handlers (or skip by not calling next)
+ *   next(event);
+ * });
+ * ```
+ */
+
+/**
+ * Next function to continue the interceptor chain
+ */
+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
+ */
+type AgentInterceptor = (event: AgentOutput, next: AgentInterceptorNext) => void;
+
+/**
+ * MessageQueue - Pending message queue interface
+ *
+ * Exposes read-only queue state for observability.
+ * Queue operations (enqueue/dequeue) are internal to Agent implementation.
+ */
+/**
+ * MessageQueue interface
+ *
+ * Read-only view of the message queue state.
+ */
+interface MessageQueue {
+    /**
+     * Number of messages in queue
+     */
+    readonly length: number;
+    /**
+     * Whether queue is empty
+     */
+    readonly isEmpty: boolean;
+}
+
+/**
+ * AgentEngine - Event Processing Unit
+ *
+ * AgentEngine is a logical processing unit that coordinates:
+ * - Driver: Event producer (LLM interaction)
+ * - MealyMachine: Event assembler (pure Mealy Machine)
+ * - Presenter: Event consumer (side effects)
+ *
+ * ```text
+ * Driver (event producer)
+ *     ↓ Stream Events
+ *   AgentEngine (logical processor)
+ *     - MealyMachine: event assembly
+ *     - State: state management
+ *     ↓ Processed Events
+ * Presenter (event consumer)
+ * ```
+ *
+ * AgentEngine is independent of Runtime system (Container, Session, Bus).
+ * It can be tested in isolation with mock Driver and Presenter.
+ *
+ * Note: This is distinct from runtime/Agent which is the complete runtime entity
+ * with LLM, Sandbox, Session, and lifecycle management (stop/resume).
+ *
+ * API:
+ * - receive(message): Send message to agent
+ * - on(handler): Subscribe to events
+ * - interrupt(): User-initiated stop
+ * - destroy(): Clean up resources
+ */
+
+/**
+ * State change event payload
+ */
+interface StateChange {
+    prev: AgentState;
+    current: AgentState;
+}
+/**
+ * State change handler type
+ */
+type StateChangeHandler = (change: StateChange) => void;
+/**
+ * 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]),
+ * });
+ * ```
+ */
+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]),
+ * });
+ * ```
+ */
+type ReactHandlerMap = Record<string, ((event: AgentOutput) => void) | undefined>;
+/**
+ * AgentEngine interface - Event Processing Unit
+ *
+ * Core responsibilities:
+ * - State management (AgentState)
+ * - Event subscription and distribution
+ * - Middleware/Interceptor chain
+ */
+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>;
+}
+
+export { type TurnResponseEvent as $, type AgentState as A, type ToolPlannedEvent as B, type ConversationQueuedEvent as C, type ToolExecutingEvent as D, type EngineEvent as E, type ToolCompletedEvent as F, type ToolFailedEvent as G, type ErrorOccurredEvent as H, type InputJsonDeltaEvent as I, type AgentErrorOccurredEvent as J, type AgentStateEvent as K, isStateEvent as L, type MessageQueue as M, type MessageEvent as N, type UserMessageEvent as O, type AssistantMessageEvent as P, type ToolCallMessageEvent as Q, type ReactHandlerMap as R, type StateChangeHandler as S, type ToEngineEvent as T, type Unsubscribe as U, type ToolResultMessageEvent as V, type ErrorMessageEvent as W, type AgentMessageEvent as X, isMessageEvent as Y, type TurnEvent as Z, type TurnRequestEvent as _, type AgentOutput as a, type AgentTurnEvent as a0, isTurnEvent as a1, type AgentMiddleware as b, type AgentMiddlewareNext as c, type AgentInterceptor as d, type AgentInterceptorNext as e, type AgentOutputCallback as f, type AgentEventHandler as g, type StreamEvent as h, type AgentEngine as i, type StateChange as j, type EventHandlerMap as k, type ToEngineEventUnion as l, type MessageStartEvent as m, type MessageDeltaEvent as n, type MessageStopEvent as o, type TextDeltaEvent as p, type ToolUseStartEvent as q, type ToolUseStopEvent as r, type ToolResultEvent as s, type StreamEventType as t, type StateEvent as u, type ConversationStartEvent as v, type ConversationThinkingEvent as w, type ConversationRespondingEvent as x, type ConversationEndEvent as y, type ConversationInterruptedEvent as z };