agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2ui/integration/agui-sync.d.ts

@@ -0,0 +1,259 @@
+/**
+ * AG-UI Sync Service
+ *
+ * Connects A2UI surfaces to AG-UI state synchronization for reactive updates.
+ * Handles bidirectional sync between AG-UI state events and A2UI surfaces.
+ *
+ * @module adapters/a2ui/integration/agui-sync
+ */
+import { EventEmitter } from 'events';
+import type { StateManager, JsonPatchOperation } from '../../ag-ui/index.js';
+import type { SurfaceGenerator, SurfaceUpdateMessage, DataModelUpdateMessage, DeleteSurfaceMessage, UserActionMessage } from '../renderer/index.js';
+import type { EventAdapter } from '../../ag-ui/event-adapter.js';
+/**
+ * Path mapping between AG-UI state and A2UI surface data
+ */
+export interface PathMapping {
+    /** AG-UI state path (JSON Pointer) */
+    readonly aguiPath: string;
+    /** A2UI surface data path (JSON Pointer) */
+    readonly a2uiPath: string;
+    /** Surface ID this mapping applies to (optional, applies to all if not set) */
+    readonly surfaceId?: string;
+    /** Transform function for value conversion */
+    readonly transform?: (value: unknown) => unknown;
+    /** Inverse transform for bidirectional sync */
+    readonly inverseTransform?: (value: unknown) => unknown;
+}
+/**
+ * A2UI CUSTOM event names
+ */
+export type A2UICustomEventName = 'a2ui:surfaceUpdate' | 'a2ui:surfaceDelete' | 'a2ui:userAction' | 'a2ui:dataUpdate';
+/**
+ * A2UI CUSTOM event payload types
+ */
+export interface A2UICustomEventPayload {
+    'a2ui:surfaceUpdate': SurfaceUpdateMessage;
+    'a2ui:surfaceDelete': DeleteSurfaceMessage;
+    'a2ui:userAction': UserActionMessage;
+    'a2ui:dataUpdate': DataModelUpdateMessage;
+}
+/**
+ * User action to state update mapping
+ */
+export interface ActionStateMapping {
+    /** Action ID pattern (supports wildcards with *) */
+    readonly actionPattern: string;
+    /** State path to update */
+    readonly statePath: string;
+    /** Payload key to use as value (or function) */
+    readonly valueExtractor: string | ((payload: Record<string, unknown>) => unknown);
+}
+/**
+ * AG-UI Sync Service configuration
+ */
+export interface AGUISyncServiceConfig {
+    /** State manager instance (required) */
+    readonly stateManager: StateManager;
+    /** Event adapter for emitting CUSTOM events (optional) */
+    readonly eventAdapter?: EventAdapter;
+    /** Whether to emit surface updates as AG-UI CUSTOM events */
+    readonly emitSurfaceEvents?: boolean;
+    /** Whether to handle user actions and update state */
+    readonly handleUserActions?: boolean;
+    /** Custom ID generator */
+    readonly idGenerator?: () => string;
+    /** Custom timestamp generator */
+    readonly timestampGenerator?: () => string;
+    /** Enable debug logging */
+    readonly debug?: boolean;
+}
+/**
+ * Sync service state
+ */
+export interface SyncServiceState {
+    /** Connected state manager */
+    readonly stateManager: StateManager | null;
+    /** Connected event adapter */
+    readonly eventAdapter: EventAdapter | null;
+    /** Connected surfaces */
+    readonly surfaces: Map<string, SurfaceGenerator>;
+    /** Active path mappings */
+    readonly pathMappings: PathMapping[];
+    /** Action to state mappings */
+    readonly actionMappings: ActionStateMapping[];
+    /** Whether service is connected */
+    readonly isConnected: boolean;
+}
+/**
+ * Sync event for monitoring
+ */
+export interface SyncEvent {
+    readonly type: 'stateToSurface' | 'surfaceToState' | 'userAction';
+    readonly timestamp: string;
+    readonly sourceId: string;
+    readonly targetId?: string;
+    readonly path: string;
+    readonly value?: unknown;
+}
+/**
+ * AG-UI Sync Service
+ *
+ * Provides bidirectional synchronization between AG-UI state manager
+ * and A2UI surface generators.
+ */
+export declare class AGUISyncService extends EventEmitter {
+    private config;
+    private surfaces;
+    private pathMappings;
+    private actionMappings;
+    private isConnected;
+    private stateSubscription;
+    private surfaceSubscriptions;
+    constructor(config: AGUISyncServiceConfig);
+    /**
+     * Connect to state manager and start listening for state changes
+     */
+    connect(): void;
+    /**
+     * Disconnect from state manager and all surfaces
+     */
+    disconnect(): void;
+    /**
+     * Connect a surface generator
+     */
+    connectSurface(surfaceId: string, surface: SurfaceGenerator): void;
+    /**
+     * Disconnect a surface generator
+     */
+    disconnectSurface(surfaceId: string): void;
+    /**
+     * Map an AG-UI state path to an A2UI surface data path
+     */
+    mapStatePath(aguiPath: string, a2uiPath: string, options?: {
+        surfaceId?: string;
+        transform?: (value: unknown) => unknown;
+        inverseTransform?: (value: unknown) => unknown;
+    }): void;
+    /**
+     * Remove a path mapping
+     */
+    unmapStatePath(aguiPath: string, a2uiPath?: string): void;
+    /**
+     * Get all path mappings
+     */
+    getPathMappings(): readonly PathMapping[];
+    /**
+     * Get mappings for a specific AG-UI path
+     */
+    getMappingsForPath(aguiPath: string): PathMapping[];
+    /**
+     * Map user actions to state updates
+     */
+    mapAction(actionPattern: string, statePath: string, valueExtractor: string | ((payload: Record<string, unknown>) => unknown)): void;
+    /**
+     * Remove an action mapping
+     */
+    unmapAction(actionPattern: string): void;
+    /**
+     * Get all action mappings
+     */
+    getActionMappings(): readonly ActionStateMapping[];
+    /**
+     * Handle STATE_SNAPSHOT from AG-UI
+     */
+    onStateSnapshot(state: Record<string, unknown>): void;
+    /**
+     * Handle STATE_DELTA from AG-UI
+     */
+    onStateDelta(delta: JsonPatchOperation[]): void;
+    /**
+     * Emit A2UI surface update as AG-UI CUSTOM event
+     */
+    emitSurfaceUpdate(message: SurfaceUpdateMessage): void;
+    /**
+     * Emit A2UI surface delete as AG-UI CUSTOM event
+     */
+    emitSurfaceDelete(message: DeleteSurfaceMessage): void;
+    /**
+     * Emit A2UI data update as AG-UI CUSTOM event
+     */
+    emitDataUpdate(message: DataModelUpdateMessage): void;
+    /**
+     * Emit user action as AG-UI CUSTOM event
+     */
+    emitUserAction(message: UserActionMessage): void;
+    /**
+     * Handle incoming user action from A2UI
+     */
+    handleUserAction(action: UserActionMessage): void;
+    /**
+     * Get current service state
+     */
+    getState(): SyncServiceState;
+    /**
+     * Get connected surfaces
+     */
+    getSurfaces(): Map<string, SurfaceGenerator>;
+    /**
+     * Get surface by ID
+     */
+    getSurface(surfaceId: string): SurfaceGenerator | undefined;
+    /**
+     * Check if connected
+     */
+    getIsConnected(): boolean;
+    /**
+     * Handle state change event from StateManager
+     */
+    private handleStateChange;
+    /**
+     * Handle state delta event from StateManager
+     */
+    private handleStateDelta;
+    /**
+     * Initialize surface from current state
+     */
+    private initializeSurfaceFromState;
+    /**
+     * Update surface from full state
+     */
+    private updateSurfaceFromState;
+    /**
+     * Apply a single delta operation to affected surfaces
+     */
+    private applyDeltaToSurfaces;
+    /**
+     * Apply delta to a specific surface
+     */
+    private applyDeltaToSurface;
+    /**
+     * Find action mapping by action ID
+     */
+    private findActionMapping;
+    /**
+     * Extract value from action payload
+     */
+    private extractActionValue;
+    /**
+     * Get value at JSON Pointer path
+     */
+    private getValueAtPath;
+    /**
+     * Set value at JSON Pointer path
+     */
+    private setValueAtPath;
+    /**
+     * Delete value at JSON Pointer path
+     */
+    private deleteValueAtPath;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+/**
+ * Create a new AGUISyncService instance
+ */
+export declare function createAGUISyncService(config: AGUISyncServiceConfig): AGUISyncService;
+//# sourceMappingURL=agui-sync.d.ts.map

package/v3/dist/adapters/a2ui/integration/agui-sync.d.ts.map

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