@agentuity/runtime 0.0.107 → 0.0.108

package/dist/session.js

@@ -233,18 +233,251 @@ export class DefaultThreadIDProvider {
         return threadId;
     }
 }
-export class DefaultThread {
+export class LazyThreadState {
+    #status = 'idle';
+    #state = new Map();
+    #pendingOperations = [];
     #initialStateJson;
+    #restoreFn;
+    #loadingPromise = null;
+    constructor(restoreFn) {
+        this.#restoreFn = restoreFn;
+    }
+    get loaded() {
+        return this.#status === 'loaded';
+    }
+    get dirty() {
+        if (this.#status === 'pending-writes') {
+            return this.#pendingOperations.length > 0;
+        }
+        if (this.#status === 'loaded') {
+            const currentJson = JSON.stringify(Object.fromEntries(this.#state));
+            return currentJson !== this.#initialStateJson;
+        }
+        return false;
+    }
+    async ensureLoaded() {
+        if (this.#status === 'loaded') {
+            return;
+        }
+        if (this.#loadingPromise) {
+            await this.#loadingPromise;
+            return;
+        }
+        this.#loadingPromise = (async () => {
+            try {
+                await this.doLoad();
+            }
+            finally {
+                this.#loadingPromise = null;
+            }
+        })();
+        await this.#loadingPromise;
+    }
+    async doLoad() {
+        const { state } = await this.#restoreFn();
+        // Initialize state from restored data
+        this.#state = new Map(state);
+        this.#initialStateJson = JSON.stringify(Object.fromEntries(this.#state));
+        // Apply any pending operations
+        for (const op of this.#pendingOperations) {
+            switch (op.op) {
+                case 'clear':
+                    this.#state.clear();
+                    break;
+                case 'set':
+                    if (op.key !== undefined) {
+                        this.#state.set(op.key, op.value);
+                    }
+                    break;
+                case 'delete':
+                    if (op.key !== undefined) {
+                        this.#state.delete(op.key);
+                    }
+                    break;
+                case 'push':
+                    if (op.key !== undefined) {
+                        const existing = this.#state.get(op.key);
+                        if (Array.isArray(existing)) {
+                            existing.push(op.value);
+                            // Apply maxRecords limit
+                            if (op.maxRecords !== undefined && existing.length > op.maxRecords) {
+                                existing.splice(0, existing.length - op.maxRecords);
+                            }
+                        }
+                        else if (existing === undefined) {
+                            this.#state.set(op.key, [op.value]);
+                        }
+                        // If existing is non-array, silently skip (error would have been thrown if loaded)
+                    }
+                    break;
+            }
+        }
+        this.#pendingOperations = [];
+        this.#status = 'loaded';
+    }
+    async get(key) {
+        await this.ensureLoaded();
+        return this.#state.get(key);
+    }
+    async set(key, value) {
+        if (this.#status === 'loaded') {
+            this.#state.set(key, value);
+        }
+        else {
+            this.#pendingOperations.push({ op: 'set', key, value });
+            if (this.#status === 'idle') {
+                this.#status = 'pending-writes';
+            }
+        }
+    }
+    async has(key) {
+        await this.ensureLoaded();
+        return this.#state.has(key);
+    }
+    async delete(key) {
+        if (this.#status === 'loaded') {
+            this.#state.delete(key);
+        }
+        else {
+            this.#pendingOperations.push({ op: 'delete', key });
+            if (this.#status === 'idle') {
+                this.#status = 'pending-writes';
+            }
+        }
+    }
+    async clear() {
+        if (this.#status === 'loaded') {
+            this.#state.clear();
+        }
+        else {
+            // Clear replaces all previous pending operations
+            this.#pendingOperations = [{ op: 'clear' }];
+            if (this.#status === 'idle') {
+                this.#status = 'pending-writes';
+            }
+        }
+    }
+    async entries() {
+        await this.ensureLoaded();
+        return Array.from(this.#state.entries());
+    }
+    async keys() {
+        await this.ensureLoaded();
+        return Array.from(this.#state.keys());
+    }
+    async values() {
+        await this.ensureLoaded();
+        return Array.from(this.#state.values());
+    }
+    async size() {
+        await this.ensureLoaded();
+        return this.#state.size;
+    }
+    async push(key, value, maxRecords) {
+        if (this.#status === 'loaded') {
+            // When loaded, push to local array
+            const existing = this.#state.get(key);
+            if (Array.isArray(existing)) {
+                existing.push(value);
+                // Apply maxRecords limit
+                if (maxRecords !== undefined && existing.length > maxRecords) {
+                    existing.splice(0, existing.length - maxRecords);
+                }
+            }
+            else if (existing === undefined) {
+                this.#state.set(key, [value]);
+            }
+            else {
+                throw new Error(`Cannot push to non-array value at key "${key}"`);
+            }
+        }
+        else {
+            // Queue push operation for merge
+            const op = { op: 'push', key, value };
+            if (maxRecords !== undefined) {
+                op.maxRecords = maxRecords;
+            }
+            this.#pendingOperations.push(op);
+            if (this.#status === 'idle') {
+                this.#status = 'pending-writes';
+            }
+        }
+    }
+    /**
+     * Get the current status for save logic
+     * @internal
+     */
+    getStatus() {
+        return this.#status;
+    }
+    /**
+     * Get pending operations for merge command
+     * @internal
+     */
+    getPendingOperations() {
+        return [...this.#pendingOperations];
+    }
+    /**
+     * Get serialized state for full save.
+     * Ensures state is loaded before serializing.
+     * @internal
+     */
+    async getSerializedState() {
+        await this.ensureLoaded();
+        return Object.fromEntries(this.#state);
+    }
+}
+export class DefaultThread {
     id;
     state;
-    metadata;
+    #metadata = null;
+    #metadataDirty = false;
+    #metadataLoadPromise = null;
     provider;
-    constructor(provider, id, initialStateJson, metadata) {
+    #restoreFn;
+    #restoredMetadata;
+    constructor(provider, id, restoreFn, initialMetadata) {
         this.provider = provider;
         this.id = id;
-        this.state = new Map();
-        this.#initialStateJson = initialStateJson;
-        this.metadata = metadata || {};
+        this.#restoreFn = restoreFn;
+        this.#restoredMetadata = initialMetadata;
+        this.state = new LazyThreadState(restoreFn);
+    }
+    async ensureMetadataLoaded() {
+        if (this.#metadata !== null) {
+            return;
+        }
+        // If we have initial metadata from thread creation, use it
+        if (this.#restoredMetadata !== undefined) {
+            this.#metadata = this.#restoredMetadata;
+            return;
+        }
+        if (this.#metadataLoadPromise) {
+            await this.#metadataLoadPromise;
+            return;
+        }
+        this.#metadataLoadPromise = (async () => {
+            try {
+                await this.doLoadMetadata();
+            }
+            finally {
+                this.#metadataLoadPromise = null;
+            }
+        })();
+        await this.#metadataLoadPromise;
+    }
+    async doLoadMetadata() {
+        const { metadata } = await this.#restoreFn();
+        this.#metadata = metadata;
+    }
+    async getMetadata() {
+        await this.ensureMetadataLoaded();
+        return { ...this.#metadata };
+    }
+    async setMetadata(metadata) {
+        this.#metadata = metadata;
+        this.#metadataDirty = true;
     }
     addEventListener(eventName, callback) {
         let listeners = threadEventListeners.get(this);
@@ -275,38 +508,79 @@ export class DefaultThread {
         await this.provider.destroy(this);
     }
     /**
-     * Check if thread state has been modified since restore
+     * Check if thread has any data (state or metadata)
+     */
+    async empty() {
+        const stateSize = await this.state.size();
+        // Check both loaded metadata and initial metadata from constructor
+        const meta = this.#metadata ?? this.#restoredMetadata ?? {};
+        return stateSize === 0 && Object.keys(meta).length === 0;
+    }
+    /**
+     * Check if thread needs saving
      * @internal
      */
-    isDirty() {
-        if (this.state.size === 0 && !this.#initialStateJson) {
-            return false;
+    needsSave() {
+        return this.state.dirty || this.#metadataDirty;
+    }
+    /**
+     * Get the save mode for this thread
+     * @internal
+     */
+    getSaveMode() {
+        const stateStatus = this.state.getStatus();
+        if (stateStatus === 'idle' && !this.#metadataDirty) {
+            return 'none';
+        }
+        if (stateStatus === 'pending-writes') {
+            return 'merge';
+        }
+        if (stateStatus === 'loaded' && (this.state.dirty || this.#metadataDirty)) {
+            return 'full';
         }
-        const currentJson = JSON.stringify(Object.fromEntries(this.state));
-        return currentJson !== this.#initialStateJson;
+        // Only metadata was changed without loading state
+        if (this.#metadataDirty) {
+            return 'merge';
+        }
+        return 'none';
     }
     /**
-     * Check if thread has any data (state or metadata)
+     * Get pending operations for merge command
+     * @internal
+     */
+    getPendingOperations() {
+        return this.state.getPendingOperations();
+    }
+    /**
+     * Get metadata for saving (returns null if not loaded/modified)
+     * @internal
      */
-    empty() {
-        return this.state.size === 0 && Object.keys(this.metadata).length === 0;
+    getMetadataForSave() {
+        if (this.#metadataDirty && this.#metadata) {
+            return this.#metadata;
+        }
+        return undefined;
     }
     /**
-     * Get serialized state for saving
+     * Get serialized state for full save.
+     * Ensures state is loaded before serializing.
      * @internal
      */
-    getSerializedState() {
-        const hasState = this.state.size > 0;
-        const hasMetadata = Object.keys(this.metadata).length > 0;
+    async getSerializedState() {
+        const state = await this.state.getSerializedState();
+        // Also ensure metadata is loaded
+        const meta = this.#metadata ?? this.#restoredMetadata ?? {};
+        const hasState = Object.keys(state).length > 0;
+        const hasMetadata = Object.keys(meta).length > 0;
         if (!hasState && !hasMetadata) {
             return '';
         }
         const data = {};
         if (hasState) {
-            data.state = Object.fromEntries(this.state);
+            data.state = state;
         }
         if (hasMetadata) {
-            data.metadata = this.metadata;
+            data.metadata = meta;
         }
         return JSON.stringify(data);
     }
@@ -625,6 +899,42 @@ export class ThreadWebSocketClient {
             }, this.requestTimeoutMs);
         });
     }
+    async merge(threadId, operations, metadata) {
+        // Wait for connection/reconnection if in progress
+        if (this.wsConnecting) {
+            await this.wsConnecting;
+        }
+        if (!this.authenticated || !this.ws) {
+            throw new Error('WebSocket not connected or authenticated');
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = crypto.randomUUID();
+            this.pendingRequests.set(requestId, {
+                resolve: () => resolve(),
+                reject,
+            });
+            const data = {
+                thread_id: threadId,
+                operations,
+            };
+            if (metadata && Object.keys(metadata).length > 0) {
+                data.metadata = metadata;
+            }
+            const message = {
+                id: requestId,
+                action: 'merge',
+                data,
+            };
+            this.ws.send(JSON.stringify(message));
+            // Timeout after configured duration
+            setTimeout(() => {
+                if (this.pendingRequests.has(requestId)) {
+                    this.pendingRequests.delete(requestId);
+                    reject(new Error('Request timeout'));
+                }
+            }, this.requestTimeoutMs);
+        });
+    }
     cleanup() {
         // Mark as disposed to prevent new reconnection attempts
         this.isDisposed = true;
@@ -680,79 +990,86 @@ export class DefaultThreadProvider {
     async restore(ctx) {
         const threadId = await this.threadIDProvider.getThreadId(this.appState, ctx);
         validateThreadIdOrThrow(threadId);
-        internal.info('[thread] restoring thread %s', threadId);
-        // Wait for WebSocket connection if still connecting
-        if (this.wsConnecting) {
-            internal.info('[thread] waiting for WebSocket connection');
-            await this.wsConnecting;
-        }
-        // Restore thread state and metadata from WebSocket if available
-        let initialStateJson;
-        let restoredMetadata;
-        if (this.wsClient) {
+        internal.info('[thread] creating lazy thread %s (no eager restore)', threadId);
+        // Create a restore function that will be called lazily when state/metadata is accessed
+        const restoreFn = async () => {
+            internal.info('[thread] lazy loading state for thread %s', threadId);
+            // Wait for WebSocket connection if still connecting
+            if (this.wsConnecting) {
+                internal.info('[thread] waiting for WebSocket connection');
+                await this.wsConnecting;
+            }
+            if (!this.wsClient) {
+                internal.info('[thread] no WebSocket client available, returning empty state');
+                return { state: new Map(), metadata: {} };
+            }
             try {
-                internal.info('[thread] restoring state from WebSocket');
                 const restoredData = await this.wsClient.restore(threadId);
                 if (restoredData) {
                     internal.info('[thread] restored state: %d bytes', restoredData.length);
                     const { flatStateJson, metadata } = parseThreadData(restoredData);
-                    initialStateJson = flatStateJson;
-                    restoredMetadata = metadata;
-                }
-                else {
-                    internal.info('[thread] no existing state found');
+                    const state = new Map();
+                    if (flatStateJson) {
+                        try {
+                            const data = JSON.parse(flatStateJson);
+                            for (const [key, value] of Object.entries(data)) {
+                                state.set(key, value);
+                            }
+                        }
+                        catch {
+                            internal.info('[thread] failed to parse state JSON');
+                        }
+                    }
+                    return { state, metadata: metadata || {} };
                 }
+                internal.info('[thread] no existing state found');
+                return { state: new Map(), metadata: {} };
             }
             catch (err) {
                 internal.info('[thread] WebSocket restore failed: %s', err);
-                // Continue with empty state rather than failing
-            }
-        }
-        else {
-            internal.info('[thread] no WebSocket client available');
-        }
-        const thread = new DefaultThread(this, threadId, initialStateJson, restoredMetadata);
-        // Populate thread state from restored data
-        if (initialStateJson) {
-            try {
-                const data = JSON.parse(initialStateJson);
-                for (const [key, value] of Object.entries(data)) {
-                    thread.state.set(key, value);
-                }
-                internal.info('[thread] populated state with %d keys', thread.state.size);
+                return { state: new Map(), metadata: {} };
             }
-            catch (err) {
-                internal.info('[thread] failed to parse state JSON: %s', err);
-                // Continue with empty state if parsing fails
-            }
-        }
+        };
+        const thread = new DefaultThread(this, threadId, restoreFn);
         await fireEvent('thread.created', thread);
         return thread;
     }
     async save(thread) {
         if (thread instanceof DefaultThread) {
-            internal.info('[thread] DefaultThreadProvider.save() - thread %s, isDirty: %s, hasWsClient: %s', thread.id, thread.isDirty(), !!this.wsClient);
+            const saveMode = thread.getSaveMode();
+            internal.info('[thread] DefaultThreadProvider.save() - thread %s, saveMode: %s, hasWsClient: %s', thread.id, saveMode, !!this.wsClient);
+            if (saveMode === 'none') {
+                internal.info('[thread] skipping save - no changes');
+                return;
+            }
             // Wait for WebSocket connection if still connecting
             if (this.wsConnecting) {
                 internal.info('[thread] waiting for WebSocket connection');
                 await this.wsConnecting;
             }
-            // Only save to WebSocket if state has changed
-            if (this.wsClient && thread.isDirty()) {
-                try {
-                    const serialized = thread.getSerializedState();
+            if (!this.wsClient) {
+                internal.info('[thread] no WebSocket client available, skipping save');
+                return;
+            }
+            try {
+                if (saveMode === 'merge') {
+                    const operations = thread.getPendingOperations();
+                    const metadata = thread.getMetadataForSave();
+                    internal.info('[thread] sending merge command with %d operations', operations.length);
+                    await this.wsClient.merge(thread.id, operations, metadata);
+                    internal.info('[thread] WebSocket merge completed');
+                }
+                else if (saveMode === 'full') {
+                    const serialized = await thread.getSerializedState();
                     internal.info('[thread] saving to WebSocket, serialized length: %d', serialized.length);
-                    const metadata = Object.keys(thread.metadata).length > 0 ? thread.metadata : undefined;
+                    const metadata = thread.getMetadataForSave();
                     await this.wsClient.save(thread.id, serialized, metadata);
                     internal.info('[thread] WebSocket save completed');
                 }
-                catch (err) {
-                    internal.info('[thread] WebSocket save failed: %s', err);
-                    // Don't throw - allow request to complete even if save fails
-                }
             }
-            else {
-                internal.info('[thread] skipping save - no wsClient or thread not dirty');
+            catch (err) {
+                internal.info('[thread] WebSocket save/merge failed: %s', err);
+                // Don't throw - allow request to complete even if save fails
             }
         }
     }