saico 2.3.0 → 2.5.0

package/saico.js

@@ -17,6 +17,9 @@ const { Store } = require('./store.js');
  *     message Q context (when opts.createQ is true).
  *   - DB access works before and after activation.
  *
+ * Saico orchestrates the full message payload sent to the LLM by walking its
+ * parent chain to aggregate prompts, tools, digests, and state summaries.
+ *
  * `new Saico(opt)` returns a Redis observable proxy of the instance when
  * Redis is available, enabling automatic persistence of public properties.
  */
@@ -26,14 +29,17 @@ class Saico {
      * @param {string} [opt.id] - Instance ID (auto-generated if omitted)
      * @param {string} [opt.name] - Instance name (defaults to class name)
      * @param {string} [opt.prompt] - Class-level system prompt
-     * @param {Function} [opt.tool_handler] - Tool handler function
      * @param {Array} [opt.functions] - Available AI functions
      * @param {string} [opt.key] - Redis key override (default: 'saico:<id>')
      * @param {boolean} [opt.redis=true] - Set false to skip Redis proxy
+     * @param {boolean} [opt.isolate] - Isolate: don't aggregate from ancestors
      * @param {string} [opt.dynamodb_table] - DynamoDB table name (enables db accessor)
      * @param {string} [opt.dynamodb_region] - AWS region for DynamoDB
      * @param {Object} [opt.dynamodb_client] - Injectable DynamoDB client (for testing)
+     * @param {Object} [opt.db] - Pluggable DB backend
      * @param {Object} [opt.store] - Store instance override
+     * @param {Object} [opt.userData] - Initial user data
+     * @param {Object} [opt.sessionConfig] - Session config overrides
      */
     constructor(opt = {}) {
         // Internal properties (underscore-prefixed, not persisted to Redis)
@@ -41,17 +47,26 @@ class Saico {
         this._task = null;
         this._store = opt.store || Store.instance || null;
         this._opt = opt;
+        this._isolate = opt.isolate || false;
 
         // Public configuration
         this.name = opt.name || this.constructor.name || 'saico';
         this.prompt = opt.prompt || '';
-        this.tool_handler = opt.tool_handler || null;
         this.functions = opt.functions || null;
 
+        // Absorbed from Sid
+        this.userData = opt.userData || {};
+        this.tm_create = Date.now();
+        this.sessionConfig = {
+            token_limit: opt.token_limit,
+            max_depth: opt.max_depth,
+            max_tool_repetition: opt.max_tool_repetition,
+            queue_limit: opt.queue_limit,
+            min_chat_messages: opt.min_chat_messages,
+            ...opt.sessionConfig,
+        };
+
         // DB backend — pluggable storage adapter.
-        // Any adapter that implements the same interface (put/get/delete/query/
-        // getAll/update/updatePath/listAppend/listAppendPath/nextCounterId/
-        // getCounterValue/setCounterValue/countItems) can be used.
         this._db = opt.db || null;
         if (!this._db && opt.dynamodb_table) {
             const { DynamoDBAdapter } = require('./dynamo.js');
@@ -79,7 +94,6 @@ class Saico {
      * @param {Object} opts
      * @param {boolean} [opts.createQ] - If true, attach a message Q (Context)
      * @param {string} [opts.prompt] - Additional prompt (appended to class-level)
-     * @param {Function} [opts.tool_handler] - Override tool handler
      * @param {Array} [opts.functions] - Override functions
      * @param {Array} [opts.states] - Task state functions
      * @param {Itask} [opts.parent] - Parent task to spawn under
@@ -109,7 +123,6 @@ class Saico {
             id: opts.taskId,
             async: true,
             store: this._store,
-            tool_handler: opts.tool_handler || this.tool_handler,
             functions: opts.functions || this.functions,
             bind: this, // State functions run with Saico instance as `this`
         };
@@ -119,22 +132,18 @@ class Saico {
 
         this._task = new Itask(taskOpt, states);
 
-        // Delegate getStateSummary from task to this Saico instance
-        const saicoInstance = this;
-        this._task.getStateSummary = function () {
-            return saicoInstance.getStateSummary();
-        };
+        // Store Saico reference on task for parent chain traversal
+        this._task._saico = this;
 
         // Create message Q context if requested (only via createQ flag, NOT prompt)
         if (opts.createQ) {
             const contextConfig = {
                 tag: opts.tag || this._task.id,
-                token_limit: opts.token_limit,
-                max_depth: opts.max_depth,
-                max_tool_repetition: opts.max_tool_repetition,
-                queue_limit: opts.queue_limit,
-                min_chat_messages: opts.min_chat_messages,
-                tool_handler: taskOpt.tool_handler,
+                token_limit: opts.token_limit ?? this.sessionConfig.token_limit,
+                max_depth: opts.max_depth ?? this.sessionConfig.max_depth,
+                max_tool_repetition: opts.max_tool_repetition ?? this.sessionConfig.max_tool_repetition,
+                queue_limit: opts.queue_limit ?? this.sessionConfig.queue_limit,
+                min_chat_messages: opts.min_chat_messages ?? this.sessionConfig.min_chat_messages,
                 functions: taskOpt.functions,
                 sequential_mode: opts.sequential_mode,
                 msgs: opts.msgs,
@@ -153,28 +162,143 @@ class Saico {
     }
 
     /**
-     * Deactivate — close context, cancel task, clean up.
+     * Deactivate — bubble cleaned messages to parent, close context, cancel task.
+     * Pushes cleaned messages (no tool calls, no BACKEND) into the parent's Q,
+     * then closes the context without the default summary bubbling.
      */
     async deactivate() {
         if (!this._task) return;
-        if (this._task.context)
-            await this._task.closeContext();
+        if (this._task.context) {
+            // Find parent context to bubble cleaned messages
+            let parentTask = this._task.parent;
+            let parentCtx = null;
+            while (parentTask) {
+                if (parentTask.context) { parentCtx = parentTask.context; break; }
+                parentTask = parentTask.parent;
+            }
+            if (parentCtx) {
+                const cleaned = this.getRecentMessages(Infinity);
+                for (const msg of cleaned)
+                    parentCtx.push(msg);
+            }
+            // Clean tool calls and close context without additional summary bubbling.
+            // We already pushed cleaned messages above — closeContext's own
+            // summarization would double-bubble.
+            if (this._task.context_id && typeof this._task.context.cleanToolCallsByTag === 'function')
+                this._task.context.cleanToolCallsByTag(this._task.context_id);
+            this._task.context = null;
+        }
         this._task._ecancel();
         this._task = null;
     }
 
-    // ---- Message relay ----
+    // ---- Saico parent chain traversal ----
+
+    /**
+     * Walk up the Saico parent chain (stop at isolate boundary or root).
+     * Returns array ordered root -> ... -> this.
+     */
+    _getSaicoAncestors() {
+        const chain = [this];
+        if (this._isolate) return chain;
+        let task = this._task?.parent;
+        while (task) {
+            if (task._saico) {
+                chain.unshift(task._saico);
+                if (task._saico._isolate) break;
+            }
+            task = task.parent;
+        }
+        return chain; // root -> ... -> this
+    }
+
+    /**
+     * Build preamble and aggregated functions by walking the Saico chain.
+     * @param {Context} activeCtx - The deepest active context (for state summary logic)
+     * @returns {{ preamble: Array, allFunctions: Array }}
+     */
+    _buildPreamble(activeCtx) {
+        const chain = this._getSaicoAncestors();
+        const preamble = [];
+        const allFunctions = [];
+
+        for (const saico of chain) {
+            // Prompt
+            if (saico.prompt)
+                preamble.push({ role: 'system', content: saico.prompt });
+
+            // State summary (can return array)
+            const summary = saico._getStateSummary(activeCtx);
+            if (Array.isArray(summary)) {
+                for (const item of summary) {
+                    if (typeof item === 'string')
+                        preamble.push({ role: 'system', content: '[State Summary]\n' + item });
+                    else
+                        preamble.push(item); // {role, content} message object
+                }
+            } else if (summary) {
+                preamble.push({ role: 'system', content: '[State Summary]\n' + summary });
+            }
+
+            // Tools digest
+            if (saico.context?.tool_digest?.length > 0) {
+                const digestText = saico.context.tool_digest.map(entry =>
+                    `[${new Date(entry.tm).toISOString()}] ${entry.tool}: ${entry.result}`
+                ).join('\n');
+                preamble.push({ role: 'system', content: '[Tool Activity Log]\n' + digestText });
+            }
+
+            // Collect functions
+            if (saico.functions) allFunctions.push(...saico.functions);
+        }
+
+        return { preamble, allFunctions };
+    }
+
+    // ---- Message orchestration ----
 
     async sendMessage(content, functions, opts) {
         if (!this._task)
             throw new Error('Not activated. Call activate() first.');
-        return this._task.sendMessage(content, functions, opts);
+
+        // Find the active context (own or walk up)
+        let ctx = this._task.getContext() || this._task.findContext();
+        if (!ctx)
+            throw new Error('No context available');
+
+        // Build preamble by walking Saico chain
+        const activeCtx = this._task.findDeepestContext() || ctx;
+        const { preamble, allFunctions } = this._buildPreamble(activeCtx);
+
+        // Merge with call-specific functions
+        if (functions) allFunctions.push(...(Array.isArray(functions) ? functions : [functions]));
+
+        opts = Object.assign({}, opts, {
+            tag: this._task.context_id,
+            _preamble: preamble,
+            _aggregatedFunctions: allFunctions.length > 0 ? allFunctions : null,
+        });
+        return ctx.sendMessage('user', '[BACKEND] ' + content, null, opts);
     }
 
     async recvChatMessage(content, opts) {
         if (!this._task)
             throw new Error('Not activated. Call activate() first.');
-        return this._task.recvChatMessage(content, opts);
+
+        // Route DOWN to deepest descendant with a msg Q
+        const ctx = this._task.findDeepestContext();
+        if (!ctx)
+            throw new Error('No context available');
+
+        // Build preamble by walking Saico chain
+        const { preamble, allFunctions } = this._buildPreamble(ctx);
+
+        opts = Object.assign({}, opts, {
+            tag: ctx.tag,
+            _preamble: preamble,
+            _aggregatedFunctions: allFunctions.length > 0 ? allFunctions : null,
+        });
+        return ctx.sendMessage('user', content, null, opts);
     }
 
     // ---- Task delegation ----
@@ -200,12 +324,11 @@ class Saico {
         if (opt.prompt) {
             const childContext = new Context(opt.prompt, childTask, {
                 tag: opt.tag || childTask.id,
-                token_limit: opt.token_limit,
-                max_depth: opt.max_depth,
-                max_tool_repetition: opt.max_tool_repetition,
-                queue_limit: opt.queue_limit,
-                min_chat_messages: opt.min_chat_messages,
-                tool_handler: opt.tool_handler || this.tool_handler,
+                token_limit: opt.token_limit ?? this.sessionConfig.token_limit,
+                max_depth: opt.max_depth ?? this.sessionConfig.max_depth,
+                max_tool_repetition: opt.max_tool_repetition ?? this.sessionConfig.max_tool_repetition,
+                queue_limit: opt.queue_limit ?? this.sessionConfig.queue_limit,
+                min_chat_messages: opt.min_chat_messages ?? this.sessionConfig.min_chat_messages,
                 functions: opt.functions || this.functions,
             });
             childTask.setContext(childContext);
@@ -238,10 +361,90 @@ class Saico {
         return childTask;
     }
 
+    // ---- State Summary ----
+
+    /**
+     * Override in subclasses to provide a state summary.
+     * @returns {string}
+     */
+    getStateSummary() { return ''; }
+
+    /**
+     * Get recent user/assistant messages (filtering out tool calls and BACKEND msgs).
+     * @param {number} n - Max number of messages to return
+     * @returns {Array<{role: string, content: string}>}
+     */
+    getRecentMessages(n = 5) {
+        if (!this.context) return [];
+        return this.context._msgs
+            .filter(m => {
+                if (m.msg.role === 'tool' || m.msg.tool_calls) return false;
+                if (typeof m.msg.content === 'string' && m.msg.content.startsWith('[BACKEND]')) return false;
+                return m.msg.role === 'user' || m.msg.role === 'assistant';
+            })
+            .slice(-n)
+            .map(m => ({ role: m.msg.role, content: m.msg.content }));
+    }
+
+    /**
+     * Internal state summary builder. Includes own getStateSummary() and,
+     * if this context is NOT the active (deepest) Q, includes recent messages.
+     * @param {Context} activeCtx - The deepest active context
+     * @returns {Array|string|null}
+     */
+    _getStateSummary(activeCtx) {
+        const parts = [];
+        const own = this.getStateSummary();
+        if (own) parts.push(own);
+
+        // If this context is NOT the active (deepest) Q, include recent messages
+        if (this.context && activeCtx && this.context !== activeCtx) {
+            const recent = this.getRecentMessages(5);
+            if (recent.length > 0) parts.push(...recent);
+        }
+
+        return parts.length > 0 ? parts : null;
+    }
+
+    // ---- User Data (absorbed from Sid) ----
+
+    setUserData(key, value) {
+        this.userData[key] = value;
+        return this;
+    }
+
+    getUserData(key) {
+        return key ? this.userData[key] : this.userData;
+    }
+
+    clearUserData() {
+        this.userData = {};
+        return this;
+    }
+
+    // ---- Session Info ----
+
+    getSessionInfo() {
+        return {
+            id: this._id,
+            name: this.name,
+            running: this._task?.running || false,
+            completed: this._task?._completed || false,
+            messageCount: this.context?.length || 0,
+            childCount: this._task?.child?.size || 0,
+            userData: this.userData,
+            uptime: Date.now() - this.tm_create,
+        };
+    }
+
+    async closeSession() {
+        if (!this._task) return;
+        if (this._task.context)
+            await this._task.context.close();
+        this._task._ecancel();
+    }
+
     // ---- Generic DB access ----
-    // These delegate to whatever _db backend was configured (DynamoDB, MongoDB,
-    // etc). Upper layers call these and don't care about the storage impl.
-    // All are no-ops (return undefined) when no backend is configured.
 
     async dbPutItem(item, table) {
         if (!this._db) return;
@@ -250,7 +453,8 @@ class Saico {
 
     async dbGetItem(key, value, table) {
         if (!this._db) return;
-        return this._db.get(key, value, table);
+        const result = await this._db.get(key, value, table);
+        return result ? this._deserializeRecord(result) : result;
     }
 
     async dbDeleteItem(key, value, table) {
@@ -260,12 +464,18 @@ class Saico {
 
     async dbQuery(index, key, value, table) {
         if (!this._db) return;
-        return this._db.query(index, key, value, table);
+        const results = await this._db.query(index, key, value, table);
+        return Array.isArray(results)
+            ? results.map(r => this._deserializeRecord(r))
+            : results;
     }
 
     async dbGetAll(table) {
         if (!this._db) return;
-        return this._db.getAll(table);
+        const results = await this._db.getAll(table);
+        return Array.isArray(results)
+            ? results.map(r => this._deserializeRecord(r))
+            : results;
     }
 
     async dbUpdate(key, keyValue, setKey, item, table) {
@@ -308,14 +518,15 @@ class Saico {
         return this._db.countItems(table);
     }
 
-    // ---- Overridable hooks ----
+    // ---- DB deserialization hook ----
 
     /**
-     * Override in subclasses to provide a state summary that appears
-     * in the message queue sent to the AI model.
-     * @returns {string}
+     * Override in subclasses to transform raw DB records (e.g. restore class instances).
+     * Called by dbGetItem, dbQuery, dbGetAll.
+     * @param {Object} raw - Raw record from DB
+     * @returns {Object} Transformed record
      */
-    getStateSummary() { return ''; }
+    _deserializeRecord(raw) { return raw; }
 
     // ---- Serialization ----
 
@@ -324,6 +535,10 @@ class Saico {
             id: this._id,
             name: this.name,
             prompt: this.prompt,
+            userData: this.userData,
+            sessionConfig: this.sessionConfig,
+            tm_create: this.tm_create,
+            isolate: this._isolate,
         };
         if (this._task) {
             data.task = {
@@ -340,6 +555,55 @@ class Saico {
         }
         return JSON.stringify(data);
     }
+
+    /**
+     * Restore a Saico instance from serialized data.
+     * @param {string|Object} data - Serialized data (JSON string or object)
+     * @param {Object} opt - Options (functions, store, states, etc.)
+     * @returns {Saico}
+     */
+    static deserialize(data, opt = {}) {
+        const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+
+        const instance = new Saico({
+            id: parsed.id,
+            name: parsed.name,
+            prompt: parsed.prompt,
+            userData: parsed.userData,
+            sessionConfig: parsed.sessionConfig,
+            isolate: parsed.isolate,
+            functions: opt.functions || parsed.task?.context?.functions,
+            store: opt.store,
+            redis: false, // No Redis proxy during deserialization
+        });
+
+        instance.tm_create = parsed.tm_create || instance.tm_create;
+
+        // Activate with restored context if task data exists
+        if (parsed.task) {
+            instance.activate({
+                createQ: !!parsed.task.context,
+                taskId: parsed.task.id,
+                tag: parsed.task.context?.tag,
+                chat_history: parsed.task.context?.chat_history,
+                functions: opt.functions || parsed.task.context?.functions,
+                states: opt.states || [],
+                ...opt,
+            });
+
+            // Restore messages to context
+            if (parsed.task.context?.msgs && instance._task.context) {
+                instance._task.context._msgs = parsed.task.context.msgs;
+            }
+
+            // Restore tool_digest
+            if (Array.isArray(parsed.task.context?.tool_digest) && instance._task.context) {
+                instance._task.context.tool_digest = parsed.task.context.tool_digest;
+            }
+        }
+
+        return instance;
+    }
 }
 
 module.exports = { Saico };