xcomponent-ai 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,404 @@
+/**
+ * Core type definitions for xcomponent-ai FSM system
+ * Inspired by XComponent state machine architecture
+ */
+/**
+ * State types following XComponent conventions
+ */
+export declare enum StateType {
+    /** Initial state (unique, black, entry point) */
+    ENTRY = "entry",
+    /** Regular state (white) */
+    REGULAR = "regular",
+    /** Final state (green, disposes instance) */
+    FINAL = "final",
+    /** Error state (purple, implicit, disposes instance) */
+    ERROR = "error"
+}
+/**
+ * Transition types
+ */
+export declare enum TransitionType {
+    /** Regular intra-machine transition (gray) */
+    REGULAR = "regular",
+    /** Inter-machine transition (green, instantiates new instance) */
+    INTER_MACHINE = "inter_machine",
+    /** Timeout transition */
+    TIMEOUT = "timeout",
+    /** Internal self-transition */
+    INTERNAL = "internal",
+    /** Triggerable from code */
+    TRIGGERABLE = "triggerable",
+    /** Auto-transition (triggered automatically when entering state) */
+    AUTO = "auto"
+}
+/**
+ * Guard function for conditional transitions
+ */
+export type GuardFunction = (event: FSMEvent, context: any) => boolean;
+/**
+ * Sender interface for triggered methods
+ * Allows state machines to send events to other instances (XComponent pattern)
+ *
+ * Supports both intra-component (within same component) and
+ * cross-component (between different components) communication
+ */
+export interface Sender {
+    /**
+     * Send event to specific instance by ID (intra-component)
+     */
+    sendTo(instanceId: string, event: FSMEvent): Promise<void>;
+    /**
+     * Send event to specific instance in another component (cross-component)
+     */
+    sendToComponent(componentName: string, instanceId: string, event: FSMEvent): Promise<void>;
+    /**
+     * Broadcast event to instances matching property rules (intra-component)
+     */
+    broadcast(machineName: string, currentState: string, event: FSMEvent): Promise<number>;
+    /**
+     * Broadcast event to instances in another component (cross-component)
+     */
+    broadcastToComponent(componentName: string, machineName: string, currentState: string, event: FSMEvent): Promise<number>;
+    /**
+     * Create new instance (intra-component)
+     */
+    createInstance(machineName: string, initialContext: Record<string, any>): string;
+    /**
+     * Create new instance in another component (cross-component)
+     */
+    createInstanceInComponent(componentName: string, machineName: string, initialContext: Record<string, any>): string;
+}
+/**
+ * Triggered method (async JS hook on entry/transition)
+ * Receives event, context, and sender for cross-instance communication
+ */
+export type TriggeredMethod = (event: FSMEvent, context: any, sender: Sender) => Promise<void>;
+/**
+ * Guard configuration
+ */
+export interface Guard {
+    /** Matching keys */
+    keys?: string[];
+    /** Contains check */
+    contains?: string;
+    /** Custom JavaScript function */
+    customFunction?: string;
+}
+/**
+ * Property matching rule for instance routing
+ * Enables XComponent-style event routing: ExecutionInput.OrderId = Order.Id
+ */
+export interface MatchingRule {
+    /** Property path in event payload (e.g., "OrderId", "customer.id") */
+    eventProperty: string;
+    /** Property path in instance context (e.g., "Id", "customer.id") */
+    instanceProperty: string;
+    /** Optional comparison operator (default: '===') */
+    operator?: '===' | '!==' | '>' | '<' | '>=' | '<=';
+}
+/**
+ * Cascading rule for automatic cross-machine updates
+ * When a source machine reaches a specific state, automatically triggers events on target machines
+ *
+ * Example: When Order reaches Confirmed, start Shipment workflow
+ */
+export interface CascadingRule {
+    /** Target machine name */
+    targetMachine: string;
+    /** Target state filter (only instances in this state) */
+    targetState: string;
+    /** Event to send to target instances */
+    event: string;
+    /** Property matching rules for routing */
+    matchingRules?: MatchingRule[];
+    /** Payload template with {{property}} syntax */
+    payload?: Record<string, any>;
+}
+/**
+ * State definition
+ */
+export interface State {
+    /** State name */
+    name: string;
+    /** State type */
+    type: StateType;
+    /** Entry method name */
+    entryMethod?: string;
+    /** Exit method name */
+    exitMethod?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+    /** Cascading rules triggered when entering this state */
+    cascadingRules?: CascadingRule[];
+}
+/**
+ * Transition definition
+ */
+export interface Transition {
+    /** Source state */
+    from: string;
+    /** Target state */
+    to: string;
+    /** Event that triggers this transition */
+    event: string;
+    /** Transition type */
+    type: TransitionType;
+    /** Guards for conditional execution */
+    guards?: Guard[];
+    /** Timeout in milliseconds (for TIMEOUT type) */
+    timeoutMs?: number;
+    /** Target machine for inter-machine transitions */
+    targetMachine?: string;
+    /** Triggered method name */
+    triggeredMethod?: string;
+    /**
+     * Property matching rules for instance routing (XComponent-style)
+     * When present, event is routed to instances where these property equality checks pass
+     * Example: ExecutionInput.OrderId = Order.Id
+     */
+    matchingRules?: MatchingRule[];
+    /**
+     * Specific triggering rule for differentiation when multiple transitions
+     * from same state use same event
+     * Boolean JavaScript expression evaluated with (event, context)
+     * Example: "event.payload.Quantity === context.RemainingQuantity"
+     */
+    specificTriggeringRule?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * State Machine definition
+ */
+export interface StateMachine {
+    /** Machine name */
+    name: string;
+    /** States */
+    states: State[];
+    /** Transitions */
+    transitions: Transition[];
+    /** Initial state name */
+    initialState: string;
+    /**
+     * Public member type name (XComponent pattern)
+     * Defines the business object type visible to external components
+     * Example: "Order", "Trade", "Customer"
+     */
+    publicMemberType?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Component definition (container for state machines)
+ */
+export interface Component {
+    /** Component name */
+    name: string;
+    /** Version */
+    version: string;
+    /** State machines */
+    stateMachines: StateMachine[];
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * FSM Event
+ */
+export interface FSMEvent {
+    /** Event type */
+    type: string;
+    /** Event payload */
+    payload: Record<string, any>;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * FSM Instance
+ */
+export interface FSMInstance {
+    /** Unique instance ID */
+    id: string;
+    /** Machine name */
+    machineName: string;
+    /** Current state */
+    currentState: string;
+    /**
+     * Context data (legacy/simple usage)
+     * For XComponent pattern, use publicMember + internalMember instead
+     */
+    context: Record<string, any>;
+    /**
+     * Public member (XComponent pattern)
+     * Business object visible to external components/APIs
+     * Example: Order { Id, Quantity, AssetName, ... }
+     */
+    publicMember?: Record<string, any>;
+    /**
+     * Internal member (XComponent pattern)
+     * Private state not exposed externally (rarely used)
+     */
+    internalMember?: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Instance status */
+    status: 'active' | 'completed' | 'error';
+}
+/**
+ * Monitoring log entry
+ */
+export interface LogEntry {
+    /** Instance ID */
+    instanceId: string;
+    /** From state */
+    from: string;
+    /** To state */
+    to: string;
+    /** Event that triggered transition */
+    event: string;
+    /** Timestamp */
+    time: number;
+    /** Error message if any */
+    error?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * WebSocket message for state changes
+ */
+export interface StateChangeMessage {
+    /** Instance ID */
+    instanceId: string;
+    /** New state */
+    newState: string;
+    /** Previous state */
+    previousState: string;
+    /** Event that triggered change */
+    event: FSMEvent;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Agent tool result
+ */
+export interface AgentToolResult {
+    /** Success status */
+    success: boolean;
+    /** Result data */
+    data?: any;
+    /** Error message */
+    error?: string;
+    /** Suggestions */
+    suggestions?: string[];
+}
+/**
+ * Persisted event with causality tracking
+ * Enables full event sourcing and auditability
+ */
+export interface PersistedEvent {
+    /** Unique event ID */
+    id: string;
+    /** Instance ID that received this event */
+    instanceId: string;
+    /** Machine name */
+    machineName: string;
+    /** Component name where this event occurred */
+    componentName: string;
+    /** The FSM event */
+    event: FSMEvent;
+    /** State before transition */
+    stateBefore: string;
+    /** State after transition */
+    stateAfter: string;
+    /** Timestamp when persisted */
+    persistedAt: number;
+    /** Causality: IDs of events that caused this event (cascading/sender) */
+    causedBy?: string[];
+    /** Causality: IDs of events caused by this event */
+    caused?: string[];
+    /** Cross-component: Source component name (if event originated from another component) */
+    sourceComponentName?: string;
+    /** Cross-component: Target component name (if event was sent to another component) */
+    targetComponentName?: string;
+}
+/**
+ * Instance snapshot for fast restoration
+ */
+export interface InstanceSnapshot {
+    /** Instance data */
+    instance: FSMInstance;
+    /** Snapshot timestamp */
+    snapshotAt: number;
+    /** Last event ID processed */
+    lastEventId: string;
+    /** Pending timeouts (relative ms from now) */
+    pendingTimeouts?: Array<{
+        stateKey: string;
+        eventType: string;
+        remainingMs: number;
+    }>;
+}
+/**
+ * Event store interface for persistence
+ */
+export interface EventStore {
+    /**
+     * Append event to store
+     */
+    append(event: PersistedEvent): Promise<void>;
+    /**
+     * Get all events for an instance
+     */
+    getEventsForInstance(instanceId: string): Promise<PersistedEvent[]>;
+    /**
+     * Get events in time range
+     */
+    getEventsByTimeRange(startTime: number, endTime: number): Promise<PersistedEvent[]>;
+    /**
+     * Get events caused by another event (tracing)
+     */
+    getCausedEvents(eventId: string): Promise<PersistedEvent[]>;
+    /**
+     * Get all events (for replay)
+     */
+    getAllEvents(): Promise<PersistedEvent[]>;
+}
+/**
+ * Snapshot store interface
+ */
+export interface SnapshotStore {
+    /**
+     * Save instance snapshot
+     */
+    saveSnapshot(snapshot: InstanceSnapshot): Promise<void>;
+    /**
+     * Get latest snapshot for instance
+     */
+    getSnapshot(instanceId: string): Promise<InstanceSnapshot | null>;
+    /**
+     * Get all snapshots (for full restore)
+     */
+    getAllSnapshots(): Promise<InstanceSnapshot[]>;
+    /**
+     * Delete snapshot
+     */
+    deleteSnapshot(instanceId: string): Promise<void>;
+}
+/**
+ * Persistence configuration
+ */
+export interface PersistenceConfig {
+    /** Enable event sourcing */
+    eventSourcing?: boolean;
+    /** Enable snapshots */
+    snapshots?: boolean;
+    /** Snapshot interval (save every N transitions) */
+    snapshotInterval?: number;
+    /** Event store implementation */
+    eventStore?: EventStore;
+    /** Snapshot store implementation */
+    snapshotStore?: SnapshotStore;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Core type definitions for xcomponent-ai FSM system
+ * Inspired by XComponent state machine architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransitionType = exports.StateType = void 0;
+/**
+ * State types following XComponent conventions
+ */
+var StateType;
+(function (StateType) {
+    /** Initial state (unique, black, entry point) */
+    StateType["ENTRY"] = "entry";
+    /** Regular state (white) */
+    StateType["REGULAR"] = "regular";
+    /** Final state (green, disposes instance) */
+    StateType["FINAL"] = "final";
+    /** Error state (purple, implicit, disposes instance) */
+    StateType["ERROR"] = "error";
+})(StateType || (exports.StateType = StateType = {}));
+/**
+ * Transition types
+ */
+var TransitionType;
+(function (TransitionType) {
+    /** Regular intra-machine transition (gray) */
+    TransitionType["REGULAR"] = "regular";
+    /** Inter-machine transition (green, instantiates new instance) */
+    TransitionType["INTER_MACHINE"] = "inter_machine";
+    /** Timeout transition */
+    TransitionType["TIMEOUT"] = "timeout";
+    /** Internal self-transition */
+    TransitionType["INTERNAL"] = "internal";
+    /** Triggerable from code */
+    TransitionType["TRIGGERABLE"] = "triggerable";
+    /** Auto-transition (triggered automatically when entering state) */
+    TransitionType["AUTO"] = "auto";
+})(TransitionType || (exports.TransitionType = TransitionType = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;GAEG;AACH,IAAY,SASX;AATD,WAAY,SAAS;IACnB,iDAAiD;IACjD,4BAAe,CAAA;IACf,4BAA4B;IAC5B,gCAAmB,CAAA;IACnB,6CAA6C;IAC7C,4BAAe,CAAA;IACf,wDAAwD;IACxD,4BAAe,CAAA;AACjB,CAAC,EATW,SAAS,yBAAT,SAAS,QASpB;AAED;;GAEG;AACH,IAAY,cAaX;AAbD,WAAY,cAAc;IACxB,8CAA8C;IAC9C,qCAAmB,CAAA;IACnB,kEAAkE;IAClE,iDAA+B,CAAA;IAC/B,yBAAyB;IACzB,qCAAmB,CAAA;IACnB,+BAA+B;IAC/B,uCAAqB,CAAA;IACrB,4BAA4B;IAC5B,6CAA2B,CAAA;IAC3B,oEAAoE;IACpE,+BAAa,CAAA;AACf,CAAC,EAbW,cAAc,8BAAd,cAAc,QAazB"}

package/dist/websockets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * WebSocket Infrastructure for Real-time FSM Monitoring
+ * Socket.io-based live state change broadcasting
+ */
+import { Server as SocketIOServer } from 'socket.io';
+import { Server as HTTPServer } from 'http';
+import { FSMRuntime } from './fsm-runtime';
+/**
+ * WebSocket Manager
+ */
+export declare class WebSocketManager {
+    private io;
+    private runtimes;
+    constructor(httpServer: HTTPServer);
+    /**
+     * Register FSM runtime for WebSocket broadcasting
+     */
+    registerRuntime(componentName: string, runtime: FSMRuntime): void;
+    /**
+     * Setup WebSocket handlers
+     */
+    private setupHandlers;
+    /**
+     * Broadcast state change to subscribers
+     */
+    private broadcastStateChange;
+    /**
+     * Get Socket.IO server instance
+     */
+    getIO(): SocketIOServer;
+}
+//# sourceMappingURL=websockets.d.ts.map

package/dist/websockets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websockets.d.ts","sourceRoot":"","sources":["../src/websockets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,QAAQ,CAA0B;gBAE9B,UAAU,EAAE,UAAU;IAYlC;;OAEG;IACH,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAyBjE;;OAEG;IACH,OAAO,CAAC,aAAa;IAwDrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;OAEG;IACH,KAAK,IAAI,cAAc;CAGxB"}

package/dist/websockets.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * WebSocket Infrastructure for Real-time FSM Monitoring
+ * Socket.io-based live state change broadcasting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketManager = void 0;
+const socket_io_1 = require("socket.io");
+/**
+ * WebSocket Manager
+ */
+class WebSocketManager {
+    io;
+    runtimes;
+    constructor(httpServer) {
+        this.io = new socket_io_1.Server(httpServer, {
+            cors: {
+                origin: '*',
+                methods: ['GET', 'POST'],
+            },
+        });
+        this.runtimes = new Map();
+        this.setupHandlers();
+    }
+    /**
+     * Register FSM runtime for WebSocket broadcasting
+     */
+    registerRuntime(componentName, runtime) {
+        this.runtimes.set(componentName, runtime);
+        // Subscribe to state changes
+        runtime.on('state_change', (data) => {
+            this.broadcastStateChange(componentName, data);
+        });
+        runtime.on('instance_created', (instance) => {
+            this.io.to(`component:${componentName}`).emit('instance_created', instance);
+        });
+        runtime.on('instance_disposed', (instance) => {
+            this.io.to(`component:${componentName}`).emit('instance_disposed', instance);
+        });
+        runtime.on('instance_error', (data) => {
+            this.io.to(`component:${componentName}`).emit('instance_error', data);
+        });
+        runtime.on('guard_failed', (data) => {
+            this.io.to(`component:${componentName}`).emit('guard_failed', data);
+        });
+    }
+    /**
+     * Setup WebSocket handlers
+     */
+    setupHandlers() {
+        this.io.on('connection', (socket) => {
+            console.log(`Client connected: ${socket.id}`);
+            // Subscribe to component events
+            socket.on('subscribe_component', (componentName) => {
+                socket.join(`component:${componentName}`);
+                console.log(`Client ${socket.id} subscribed to component: ${componentName}`);
+                socket.emit('subscribed', { componentName });
+            });
+            // Subscribe to specific instance
+            socket.on('subscribe_instance', (data) => {
+                socket.join(`instance:${data.instanceId}`);
+                console.log(`Client ${socket.id} subscribed to instance: ${data.instanceId}`);
+                socket.emit('subscribed', { instanceId: data.instanceId });
+            });
+            // Unsubscribe
+            socket.on('unsubscribe_component', (componentName) => {
+                socket.leave(`component:${componentName}`);
+                console.log(`Client ${socket.id} unsubscribed from component: ${componentName}`);
+            });
+            socket.on('unsubscribe_instance', (instanceId) => {
+                socket.leave(`instance:${instanceId}`);
+                console.log(`Client ${socket.id} unsubscribed from instance: ${instanceId}`);
+            });
+            // Get runtime info
+            socket.on('get_runtime_info', (componentName, callback) => {
+                const runtime = this.runtimes.get(componentName);
+                if (runtime) {
+                    const instances = runtime.getAllInstances();
+                    callback({
+                        success: true,
+                        data: {
+                            componentName,
+                            instanceCount: instances.length,
+                            instances,
+                        },
+                    });
+                }
+                else {
+                    callback({
+                        success: false,
+                        error: `Component ${componentName} not found`,
+                    });
+                }
+            });
+            socket.on('disconnect', () => {
+                console.log(`Client disconnected: ${socket.id}`);
+            });
+        });
+    }
+    /**
+     * Broadcast state change to subscribers
+     */
+    broadcastStateChange(componentName, data) {
+        // Broadcast to component subscribers
+        this.io.to(`component:${componentName}`).emit('state_change', data);
+        // Broadcast to instance subscribers
+        this.io.to(`instance:${data.instanceId}`).emit('state_change', data);
+    }
+    /**
+     * Get Socket.IO server instance
+     */
+    getIO() {
+        return this.io;
+    }
+}
+exports.WebSocketManager = WebSocketManager;
+//# sourceMappingURL=websockets.js.map

package/dist/websockets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websockets.js","sourceRoot":"","sources":["../src/websockets.ts"],"names":[],"mappings":"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"}