@olane/o-lane 0.7.12-alpha.74 → 0.7.12-alpha.76

package/dist/src/ag-ui/ag-ui-olane.tool.js

@@ -0,0 +1,257 @@
+import { oLaneTool } from '../o-lane.tool.js';
+import { AGUIEventMapper } from './ag-ui-event-mapper.js';
+import { AGUIStreamManager } from './ag-ui-stream-manager.js';
+import { ONodeAGUITransport } from './transports/onode-transport.js';
+import { ConsoleAGUITransport } from './transports/console-transport.js';
+import { oIntent } from '../intent/o-intent.js';
+import { oLaneContext } from '../o-lane.context.js';
+import { oCapabilityType } from '../capabilities/enums/o-capability.type-enum.js';
+import { oAddress } from '@olane/o-core';
+import { generateRunId, generateThreadId, generateTimestamp, } from './ag-ui-utils.js';
+import { AG_UI_DEFAULTS } from './ag-ui-constants.js';
+/**
+ * AG-UI compatible oLane Tool
+ * Extends oLaneTool with AG-UI event streaming capabilities
+ */
+export class AGUIoLaneTool extends oLaneTool {
+    constructor(config) {
+        super(config);
+        this.agUIConfig = {
+            ...config,
+            enableAGUI: config.enableAGUI ?? AG_UI_DEFAULTS.AGUI_ENABLED,
+            debugAGUI: config.debugAGUI ?? AG_UI_DEFAULTS.DEBUG_ENABLED,
+            stateSnapshotInterval: config.stateSnapshotInterval ?? AG_UI_DEFAULTS.STATE_SNAPSHOT_INTERVAL,
+            maxDeltaHistory: config.maxDeltaHistory ?? AG_UI_DEFAULTS.MAX_DELTA_HISTORY,
+        };
+    }
+    /**
+     * AG-UI compatible intent method with full event streaming
+     * This is the main entry point for AG-UI enabled intent resolution
+     */
+    async _tool_ag_ui_intent(request) {
+        const { intent, context, threadId: providedThreadId, _isStreaming = false, } = request.params;
+        this.logger.debug('AG-UI intent received:', request.params);
+        // Generate IDs
+        const runId = generateRunId();
+        const threadId = providedThreadId || generateThreadId(context);
+        // Create AG-UI event context
+        const eventContext = {
+            threadId,
+            runId,
+            parentRunId: undefined,
+            cycleToMessageId: new Map(),
+            taskToToolCallId: new Map(),
+        };
+        // Create event mapper
+        const eventMapper = new AGUIEventMapper(eventContext, {
+            emitActivityEvents: this.agUIConfig.debugAGUI,
+            emitReasoningEvents: true,
+            textChunkSize: AG_UI_DEFAULTS.TEXT_CHUNK_SIZE,
+        });
+        // Create transport
+        const transport = this.agUIConfig.agUITransport || this.createDefaultTransport(request);
+        // Create stream manager
+        const streamManager = new AGUIStreamManager({
+            transport,
+            debug: this.agUIConfig.debugAGUI,
+            eventFilter: this.agUIConfig.eventFilter,
+            validateEvents: true,
+        });
+        try {
+            // Emit RunStarted
+            await streamManager.emit(eventMapper.mapLaneStartToRunStarted(new oIntent({ intent: intent }), { intent, context }));
+            // Emit preflight step
+            await streamManager.emit(eventMapper.mapCapabilityStartToStepStarted(oCapabilityType.UNKNOWN));
+            // Create lane with AG-UI event emission hooks
+            let previousSequence = [];
+            let cycleNumber = 0;
+            const lane = await this.manager.createLane({
+                intent: new oIntent({ intent: intent }),
+                currentNode: this,
+                caller: this.address,
+                useStream: _isStreaming,
+                requestId: request.id,
+                onChunk: async (chunk) => {
+                    console.log('Chunk received:', chunk);
+                    // Emit chunk as activity event for real-time progress
+                    // Note: This fires AFTER addSequence has emitted full capability events,
+                    // so ActivitySnapshot provides a complementary progress update
+                    try {
+                        const activityEvent = eventMapper.mapChunkToActivity(chunk, cycleNumber);
+                        console.log('Activity event:', activityEvent);
+                        await streamManager.emit(activityEvent);
+                    }
+                    catch (error) {
+                        this.logger.error('Error mapping chunk to activity:', error);
+                    }
+                },
+                context: context
+                    ? new oLaneContext([
+                        `[Chat History Context Begin]\n${context}\n[Chat History Context End]`,
+                    ])
+                    : undefined,
+            });
+            // Emit preflight complete
+            await streamManager.emit(eventMapper.mapCapabilityEndToStepFinished(oCapabilityType.UNKNOWN));
+            // Override lane's addSequence to emit events as capabilities execute
+            const originalAddSequence = lane.addSequence.bind(lane);
+            lane.addSequence = (result) => {
+                // Call original method
+                originalAddSequence(result);
+                // Emit AG-UI events asynchronously
+                (async () => {
+                    try {
+                        cycleNumber++;
+                        // Emit step started
+                        await streamManager.emit(eventMapper.mapCapabilityStartToStepStarted(result.type));
+                        // Map capability to events
+                        const events = eventMapper.mapCapabilityToEvents(result, cycleNumber);
+                        await streamManager.emitBatch(events);
+                        // Emit state updates
+                        if (this.agUIConfig.stateSnapshotInterval &&
+                            cycleNumber % this.agUIConfig.stateSnapshotInterval === 0) {
+                            // Emit full snapshot
+                            await streamManager.emit(eventMapper.mapSequenceToStateSnapshot(lane.sequence));
+                        }
+                        else {
+                            // Emit delta
+                            const delta = eventMapper.mapSequenceToStateDelta(previousSequence, lane.sequence);
+                            if (delta) {
+                                await streamManager.emit(delta);
+                            }
+                        }
+                        previousSequence = [...lane.sequence];
+                        // Emit step finished
+                        await streamManager.emit(eventMapper.mapCapabilityEndToStepFinished(result.type));
+                    }
+                    catch (error) {
+                        this.logger.error('Error emitting AG-UI events:', error);
+                    }
+                })();
+            };
+            // Execute the lane
+            let result;
+            let error;
+            try {
+                result = await lane.execute();
+                // Emit final state snapshot
+                await streamManager.emit(eventMapper.mapSequenceToStateSnapshot(lane.sequence));
+                // Emit RunFinished
+                if (result) {
+                    await streamManager.emit(eventMapper.mapLaneCompleteToRunFinished(result));
+                }
+            }
+            catch (err) {
+                error = err;
+                this.logger.error('Lane execution error:', error);
+                // Emit RunError
+                await streamManager.emit(eventMapper.mapLaneErrorToRunError(error));
+            }
+            // Flush any remaining events
+            await streamManager.flushQueue();
+            // Return standard response
+            const completeResponse = {
+                result: result?.result,
+                humanResult: result?.humanResult,
+                summary: result?.config?.params?.summary,
+                error: error?.message || result?.error,
+                cycles: lane.sequence.length,
+                cid: lane.cid?.toString(),
+                threadId,
+                runId,
+                sequence: lane.sequence.map((s) => s.result),
+            };
+            return completeResponse;
+        }
+        finally {
+            // Close stream manager
+            await streamManager.close();
+        }
+    }
+    /**
+     * Standard intent method - optionally enable AG-UI if configured
+     * Overrides the base _tool_intent to add AG-UI support
+     */
+    async _tool_intent(request) {
+        // If AG-UI is enabled, use AG-UI intent method
+        if (this.agUIConfig.enableAGUI) {
+            return this._tool_ag_ui_intent(request);
+        }
+        // Otherwise, call the parent implementation
+        // Use the standard lane execution from withLane mixin
+        const { intent, context, streamTo, _isStreaming = false } = request.params;
+        const lane = await this.manager.createLane({
+            intent: new oIntent({ intent: intent }),
+            currentNode: this,
+            caller: this.address,
+            streamTo: streamTo ? new oAddress(streamTo) : undefined,
+            useStream: _isStreaming,
+            requestId: request.id,
+            context: context
+                ? new oLaneContext([
+                    `[Chat History Context Begin]\n${context}\n[Chat History Context End]`,
+                ])
+                : undefined,
+        });
+        const response = await lane.execute();
+        return {
+            result: response?.result,
+            humanResult: response?.humanResult,
+            summary: response?.config?.params?.summary,
+            error: response?.error,
+            cycles: lane.sequence.length,
+            cid: lane.cid?.toString(),
+            sequence: lane.sequence.map((s) => s.result),
+        };
+    }
+    /**
+     * Receive AG-UI event from remote sources
+     * Allows other tools to send events to this tool
+     */
+    async _tool_receive_ag_ui_event(request) {
+        const { event } = request.params;
+        this.logger.debug('Received AG-UI event:', event);
+        // Handle the event (can be extended for custom logic)
+        return {
+            received: true,
+            eventType: event.type,
+            timestamp: generateTimestamp(),
+        };
+    }
+    /**
+     * Create default transport based on request configuration
+     */
+    createDefaultTransport(request) {
+        // If streaming is enabled and we have a stream, use ONode transport
+        if (request.params._isStreaming && request.stream) {
+            return new ONodeAGUITransport({
+                stream: request.stream,
+                node: this,
+                requestId: request.id,
+                streamTo: request.params.streamTo
+                    ? new oAddress(request.params.streamTo)
+                    : undefined,
+            });
+        }
+        // Otherwise, use console transport for debugging
+        return new ConsoleAGUITransport(this.agUIConfig.debugAGUI);
+    }
+    /**
+     * Enable or disable AG-UI at runtime
+     */
+    setAGUIEnabled(enabled) {
+        this.agUIConfig.enableAGUI = enabled;
+    }
+    /**
+     * Check if AG-UI is enabled
+     */
+    isAGUIEnabled() {
+        return this.agUIConfig.enableAGUI || false;
+    }
+    /**
+     * Get AG-UI configuration
+     */
+    getAGUIConfig() {
+        return { ...this.agUIConfig };
+    }
+}

package/dist/src/ag-ui/ag-ui-stream-manager.d.ts

@@ -0,0 +1,99 @@
+import { AGUIEvent } from './types/ag-ui-event.types.js';
+import { AGUITransport } from './transports/ag-ui-transport.interface.js';
+import { oObject } from '@olane/o-core';
+/**
+ * Configuration for stream manager
+ */
+export interface AGUIStreamManagerConfig {
+    /**
+     * Event transport mechanism
+     */
+    transport: AGUITransport;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Filter events by type (if undefined, all events are emitted)
+     */
+    eventFilter?: string[];
+    /**
+     * Maximum queue size before forcing emission
+     */
+    maxQueueSize?: number;
+    /**
+     * Enable event validation
+     */
+    validateEvents?: boolean;
+}
+/**
+ * Manages AG-UI event emission with proper ordering and formatting
+ */
+export declare class AGUIStreamManager extends oObject {
+    private transport;
+    private debug;
+    private eventFilter?;
+    private maxQueueSize;
+    private validateEvents;
+    private eventQueue;
+    private emitting;
+    constructor(config: AGUIStreamManagerConfig);
+    /**
+     * Emit a single event
+     */
+    emit(event: AGUIEvent): Promise<void>;
+    /**
+     * Emit multiple events in sequence
+     */
+    emitBatch(events: AGUIEvent[]): Promise<void>;
+    /**
+     * Queue an event for later emission
+     * Useful for buffering events during processing
+     */
+    queueEvent(event: AGUIEvent): void;
+    /**
+     * Queue multiple events
+     */
+    queueBatch(events: AGUIEvent[]): void;
+    /**
+     * Flush all queued events
+     */
+    flushQueue(): Promise<void>;
+    /**
+     * Get the number of queued events
+     */
+    getQueueSize(): number;
+    /**
+     * Clear the event queue without emitting
+     */
+    clearQueue(): void;
+    /**
+     * Check if transport is active
+     */
+    isActive(): boolean;
+    /**
+     * Close the stream manager and transport
+     */
+    close(): Promise<void>;
+    /**
+     * Update the transport
+     */
+    setTransport(transport: AGUITransport): void;
+    /**
+     * Get transport type
+     */
+    getTransportType(): string;
+    /**
+     * Enable/disable debug mode
+     */
+    setDebug(debug: boolean): void;
+    /**
+     * Update event filter
+     */
+    setEventFilter(filter: string[] | undefined): void;
+    /**
+     * Get current event filter
+     */
+    getEventFilter(): string[] | undefined;
+}
+//# sourceMappingURL=ag-ui-stream-manager.d.ts.map

package/dist/src/ag-ui/ag-ui-stream-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui-stream-manager.d.ts","sourceRoot":"","sources":["../../../src/ag-ui/ag-ui-stream-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC;IAEzB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,OAAO;IAC5C,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,MAAM,EAAE,uBAAuB;IAW3C;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B3C;;OAEG;IACG,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAclC;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI;IAMrC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BjC;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAI5C;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI9B;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAIlD;;OAEG;IACH,cAAc,IAAI,MAAM,EAAE,GAAG,SAAS;CAGvC"}

package/dist/src/ag-ui/ag-ui-stream-manager.js

@@ -0,0 +1,160 @@
+import { validateEvent } from './ag-ui-utils.js';
+import { oObject } from '@olane/o-core';
+/**
+ * Manages AG-UI event emission with proper ordering and formatting
+ */
+export class AGUIStreamManager extends oObject {
+    constructor(config) {
+        super('ag-ui-stream-manager');
+        this.eventQueue = [];
+        this.emitting = false;
+        this.transport = config.transport;
+        this.debug = config.debug || false;
+        this.eventFilter = config.eventFilter
+            ? new Set(config.eventFilter)
+            : undefined;
+        this.maxQueueSize = config.maxQueueSize || 100;
+        this.validateEvents = config.validateEvents !== false;
+    }
+    /**
+     * Emit a single event
+     */
+    async emit(event) {
+        // Filter events if configured
+        if (this.eventFilter && !this.eventFilter.has(event.type)) {
+            if (this.debug) {
+                this.logger.debug(`Filtered event: ${event.type}`);
+            }
+            return;
+        }
+        // Validate event if configured
+        if (this.validateEvents && !validateEvent(event)) {
+            this.logger.warn(`Invalid event structure: ${event.type}`);
+            return;
+        }
+        if (this.debug) {
+            this.logger.debug(`Emitting event: ${event.type}`, event);
+        }
+        try {
+            await this.transport.send(event);
+        }
+        catch (error) {
+            this.logger.error(`Error emitting event ${event.type}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Emit multiple events in sequence
+     */
+    async emitBatch(events) {
+        for (const event of events) {
+            await this.emit(event);
+        }
+    }
+    /**
+     * Queue an event for later emission
+     * Useful for buffering events during processing
+     */
+    queueEvent(event) {
+        this.eventQueue.push(event);
+        // Auto-flush if queue is too large
+        if (this.eventQueue.length >= this.maxQueueSize) {
+            this.logger.warn(`Event queue reached max size (${this.maxQueueSize}), flushing...`);
+            this.flushQueue().catch((error) => {
+                this.logger.error('Error flushing queue:', error);
+            });
+        }
+    }
+    /**
+     * Queue multiple events
+     */
+    queueBatch(events) {
+        for (const event of events) {
+            this.queueEvent(event);
+        }
+    }
+    /**
+     * Flush all queued events
+     */
+    async flushQueue() {
+        if (this.emitting) {
+            this.logger.debug('Already emitting, skipping flush');
+            return;
+        }
+        if (this.eventQueue.length === 0) {
+            return;
+        }
+        this.emitting = true;
+        try {
+            const events = [...this.eventQueue];
+            this.eventQueue = [];
+            if (this.debug) {
+                this.logger.debug(`Flushing ${events.length} queued events`);
+            }
+            await this.emitBatch(events);
+        }
+        finally {
+            this.emitting = false;
+        }
+    }
+    /**
+     * Get the number of queued events
+     */
+    getQueueSize() {
+        return this.eventQueue.length;
+    }
+    /**
+     * Clear the event queue without emitting
+     */
+    clearQueue() {
+        this.eventQueue = [];
+    }
+    /**
+     * Check if transport is active
+     */
+    isActive() {
+        return this.transport.isActive();
+    }
+    /**
+     * Close the stream manager and transport
+     */
+    async close() {
+        // Flush any remaining events
+        await this.flushQueue();
+        // Close transport
+        await this.transport.close();
+        if (this.debug) {
+            this.logger.debug('Stream manager closed');
+        }
+    }
+    /**
+     * Update the transport
+     */
+    setTransport(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Get transport type
+     */
+    getTransportType() {
+        return this.transport.getType();
+    }
+    /**
+     * Enable/disable debug mode
+     */
+    setDebug(debug) {
+        this.debug = debug;
+    }
+    /**
+     * Update event filter
+     */
+    setEventFilter(filter) {
+        this.eventFilter = filter ? new Set(filter) : undefined;
+    }
+    /**
+     * Get current event filter
+     */
+    getEventFilter() {
+        return this.eventFilter ? Array.from(this.eventFilter) : undefined;
+    }
+}

package/dist/src/ag-ui/ag-ui-utils.d.ts

@@ -0,0 +1,50 @@
+import { JSONPatchOperation } from './types/ag-ui-event.types.js';
+/**
+ * Utility functions for AG-UI event handling
+ */
+/**
+ * Generate a unique run ID
+ */
+export declare function generateRunId(): string;
+/**
+ * Generate a unique message ID
+ */
+export declare function generateMessageId(): string;
+/**
+ * Generate a unique tool call ID
+ */
+export declare function generateToolCallId(): string;
+/**
+ * Generate a thread ID from context or create a new one
+ */
+export declare function generateThreadId(context?: string): string;
+/**
+ * Generate ISO 8601 timestamp for events
+ */
+export declare function generateTimestamp(): string;
+/**
+ * Generate JSON Patch operations (RFC 6902) for state deltas
+ * Compares old and new state to create minimal patch
+ */
+export declare function generateJSONPatch(oldState: any, newState: any, basePath?: string): JSONPatchOperation[];
+/**
+ * Apply JSON Patch operations to an object
+ */
+export declare function applyJSONPatch(obj: any, patches: JSONPatchOperation[]): any;
+/**
+ * Chunk a string into smaller pieces for streaming
+ */
+export declare function chunkString(str: string, chunkSize: number): string[];
+/**
+ * Validate an AG-UI event has required fields
+ */
+export declare function validateEvent(event: any): boolean;
+/**
+ * Extract capability type from step name
+ */
+export declare function capabilityTypeToStepName(capabilityType: string): string;
+/**
+ * Create a safe JSON string from any value
+ */
+export declare function safeJSONStringify(value: any): string;
+//# sourceMappingURL=ag-ui-utils.d.ts.map

package/dist/src/ag-ui/ag-ui-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui-utils.d.ts","sourceRoot":"","sources":["../../../src/ag-ui/ag-ui-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE;;GAEG;AAEH;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzD;AAeD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,GAAG,EACb,QAAQ,GAAE,MAAW,GACpB,kBAAkB,EAAE,CA+EtB;AAyDD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,GAAG,CAoB3E;AA2DD;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAMpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAWjD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAMpD"}