saico 2.7.1 → 2.8.1

package/README.md

@@ -156,29 +156,28 @@ When a Saico's context is not the deepest active one, its last 5 user/assistant
 ### Spawning Child Saico Instances
 
 ```js
-// Child with its own conversation context
+// Child with its own conversation context (auto-activated by spawn)
 const child = new Saico({
     name: 'subtask',
     prompt: 'Handle this specific sub-task',
+    createQ: true,
     functions: [/* child-specific tools */],
 });
-child.activate({ createQ: true });
 agent.spawn(child);
 await child.sendMessage('Working on subtask...');
 
 // Child without context (uses parent's via findContext())
 const simple = new Saico({ name: 'simple' });
-simple.activate();
 agent.spawn(simple);
 await simple.sendMessage('Quick operation');
 
 // spawnAndRun: spawn + schedule child task to run on nextTick
 const runner = new Saico({ name: 'runner' });
-runner.activate({ states: [async function() { return await this.sendMessage('Go'); }] });
+runner.states = [async function() { return await this.sendMessage('Go'); }];
 agent.spawnAndRun(runner);
 ```
 
-Both parent and child must be activated before calling `spawn()` or `spawnAndRun()`.
+Parent must be activated before calling `spawn()` or `spawnAndRun()`. Children are auto-activated if needed.
 
 ### Deactivation and Message Bubbling
 
@@ -258,7 +257,10 @@ agent.getSessionInfo();
 //   userData, uptime
 // }
 
-await agent.closeSession();  // Close context and cancel task
+await agent.closeSession();  // Saves full state to Store, cancels task
+
+// Restore from Store
+const restored = await Saico.rehydrate(agent.id, { store });
 ```
 
 ## Database Access
@@ -299,16 +301,16 @@ class MyAgent extends Saico {
 ## Serialization
 
 ```js
-// Save
+// In-memory snapshot (raw msgs, used by Redis proxy)
 const json = agent.serialize();
+const restored = Saico.deserialize(json);
 
-// Restore
-const restored = Saico.deserialize(json, {
-    functions: myFunctions,
-});
+// Durable persistence (compressed msgs, saved to Store)
+await agent.closeSession();
+const restored2 = await Saico.rehydrate(agent.id, { store });
 ```
 
-Serialization includes: id, name, prompt, userData, sessionConfig, tm_create, isolate, and full context state (messages, tool_digest, chat_history).
+`serialize()` includes: id, name, prompt, userData, sessionConfig, tm_create, isolate, and full context state (raw messages, tool_digest). `closeSession()` saves the same shape but with compressed messages for durable storage.
 
 ## Redis Persistence
 
@@ -328,7 +330,7 @@ Properties prefixed with `_` are internal and not persisted.
 
 ## Tool Implementation (TOOL_ methods)
 
-Define tool implementations as `TOOL_`-prefixed methods on your Saico subclass. When the LLM returns a tool call, Context automatically searches the Saico hierarchy (current → up parents → down children) to find and invoke the matching method with parsed arguments.
+Define tool implementations as `TOOL_`-prefixed methods on your Saico subclass. When the LLM returns a tool call, Saico automatically searches the task hierarchy (current → up parents → down children) to find and invoke the matching method with parsed arguments.
 
 ```js
 class MyAgent extends Saico {
@@ -357,13 +359,13 @@ Return a string or `{ content: string, functions?: [] }`.
 
 ## Low-Level API
 
-For cases where you need a standalone context without the Saico master class:
+For cases where you need a standalone message queue without the Saico master class:
 
 ```js
-const { createContext } = require('saico');
+const { createMsgs } = require('saico');
 
-// Standalone context
-const ctx = createContext('System prompt', null, { tag: 'my-tag', token_limit: 4000 });
+// Standalone message queue
+const ctx = createMsgs('System prompt', { tag: 'my-tag', token_limit: 4000 });
 const reply = await ctx.sendMessage('user', 'Hello', functions);
 ```
 
@@ -388,7 +390,7 @@ saico/
 npm test
 ```
 
-284 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
+290 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, persistence (closeSession/rehydrate), and integration flows.
 
 ## Requirements
 

package/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const Itask = require('./itask.js');
-const { Context, createContext } = require('./msgs.js');
+const { Msgs, createMsgs } = require('./msgs.js');
 const { Store, DynamoBackend } = require('./store.js');
 const { Saico } = require('./saico.js');
 const { DynamoDBAdapter } = require('./dynamo.js');
@@ -34,7 +34,7 @@ module.exports = {
 
     // Core classes
     Itask,
-    Context,
+    Msgs,
     Store,
     DynamoBackend,
 
@@ -42,7 +42,7 @@ module.exports = {
     init,
 
     // Factory
-    createContext,
+    createMsgs,
 
     // Utilities (re-export from util.js)
     util: require('./util.js'),

package/msgs.js

@@ -8,23 +8,17 @@ const { _log, _lerr, _ldbg } = util;
 const debug = 0;
 
 /**
- * Context - Conversation context that can be attached to any Itask.
- *
- * Key differences from the old Messages class:
- * - Uses task hierarchy instead of parent/child messages
- * - task reference replaces parent reference
- * - getMsgContext() traverses task hierarchy
- * - _createMsgQ() aggregates from task ancestors
+ * Msgs - Pure message queue with tool call handling, summarization, and LLM communication.
+ * Saico sets callback hooks after construction to wire in hierarchy access.
  */
-class Context {
-    constructor(prompt, task, config = {}) {
+class Msgs {
+    constructor(prompt, config = {}) {
         this.prompt = prompt;
-        this.task = task; // Reference to owning Itask (replaces parent)
         this.tag = config.tag || crypto.randomBytes(4).toString('hex');
         this.token_limit = config.token_limit || 1000000000;
         this.lower_limit = this.token_limit * 0.85;
         this.upper_limit = this.token_limit * 0.98;
-        this.functions = config.functions || task?.functions || null;
+        this.functions = config.functions || null;
 
         // Recursive depth and repetition control
         this.max_depth = config.max_depth || 5;
@@ -33,9 +27,6 @@ class Context {
         this._deferred_tool_calls = [];
         this._tool_call_sequence = [];
 
-        // Chat history persistence
-        this.chat_history = config.chat_history || null;
-
         this._msgs = [];
         this._waitingQueue = [];
         this._active_tool_calls = new Map();
@@ -53,17 +44,60 @@ class Context {
         // Tool digest — persistent history of tool calls that mutated task state
         this.tool_digest = config.tool_digest || [];
 
-        // Initialize messages if provided
+        // Callback hooks — set by Saico after construction
+        this._findToolImpl = null;   // (toolName) => { saico, methodName } | null
+        this._getSnapshot = null;    // () => serializable snapshot for dirty detection
+
+        // Initialize messages: explicit msgs take priority over chat_history
+        this._chat_history = config.chat_history || null;
         (config.msgs || []).forEach(m => this.push(m));
 
-        _log('created Context for tag', this.tag);
+        _log('created Msgs for tag', this.tag);
     }
 
-    // Set the task reference (used when context is created separately)
-    setTask(task) {
-        this.task = task;
-        if (!this.functions)
-            this.functions = task?.functions;
+    /**
+     * Decompress _chat_history into _msgs. Call after construction when
+     * restoring from persisted state. No-op if chat_history is absent or
+     * _msgs were already provided via config.msgs.
+     */
+    async initHistory() {
+        if (!this._chat_history || this._msgs.length > 0)
+            return;
+        const messages = await util.decompressMessages(this._chat_history);
+        if (!Array.isArray(messages) || messages.length === 0)
+            return;
+        for (const m of messages) {
+            this._msgs.push({
+                msg: m,
+                opts: {},
+                msgid: crypto.randomBytes(2).toString('hex'),
+                replied: 1,
+            });
+        }
+    }
+
+    /**
+     * Prepare the message Q for storage. Filters out tool calls, tool
+     * responses, and [BACKEND] messages, trims to QUEUE_LIMIT, compresses.
+     * Returns { chat_history, tool_digest }. Does NOT mutate _msgs.
+     */
+    async prepareForStorage() {
+        const cleaned = this._msgs.filter(m => {
+            if (m.msg.tool_calls) return false;
+            if (m.msg.role === 'tool') return false;
+            if (typeof m.msg.content === 'string' && m.msg.content.startsWith('[BACKEND]')) return false;
+            return true;
+        }).map(m => m.msg);
+
+        const trimmed = cleaned.length > this.QUEUE_LIMIT
+            ? cleaned.slice(-this.QUEUE_LIMIT)
+            : cleaned;
+
+        const chat_history = trimmed.length > 0
+            ? await util.compressMessages(trimmed)
+            : null;
+
+        return { chat_history, tool_digest: this.tool_digest || [] };
     }
 
     // Snapshot all public (non-underscore) task properties for dirty detection.
@@ -92,32 +126,6 @@ class Context {
             this.tool_digest = this.tool_digest.slice(-this.TOOL_DIGEST_LIMIT);
     }
 
-    // Get the parent context by traversing task hierarchy (via Saico)
-    getParentContext() {
-        if (!this.task || !this.task.parent)
-            return null;
-        let task = this.task.parent;
-        while (task) {
-            if (task._saico?.context) return task._saico.context;
-            task = task.parent;
-        }
-        return null;
-    }
-
-    // Get all ancestor contexts via task hierarchy (via Saico)
-    getAncestorContexts() {
-        if (!this.task)
-            return [];
-        const contexts = [];
-        let task = this.task.parent;
-        while (task) {
-            if (task._saico?.context)
-                contexts.unshift(task._saico.context);
-            task = task.parent;
-        }
-        return contexts;
-    }
-
     _hasPendingToolCalls() {
         const toolCallMsgs = this._msgs.filter(m => m.msg.tool_calls);
 
@@ -291,16 +299,15 @@ class Context {
                     };
                 } else {
                     this._trackActiveToolCall(call);
-                    const _snap = this.task
-                        ? JSON.stringify(this._snapshotPublicProps(this.task)) : null;
+                    const _snap = this._getSnapshot
+                        ? JSON.stringify(this._getSnapshot()) : null;
 
                     try {
                         const correspondingDeferred = deferredGroup.find(d => d.call.id === call.id);
                         const timeout = correspondingDeferred?.originalMessage.opts.timeout;
 
                         result = await this._executeToolCallWithTimeout(call, timeout);
-                        if (_snap !== null &&
-                            _snap !== JSON.stringify(this._snapshotPublicProps(this.task)))
+                        if (_snap !== null && _snap !== JSON.stringify(this._getSnapshot()))
                             this._appendToolDigest(call.function.name, result?.content || '');
                     } finally {
                         this._completeActiveToolCall(call);
@@ -390,24 +397,6 @@ class Context {
 
     getSummaries() { return this._msgs.filter(m => m.opts.summary); }
 
-    // Get functions aggregated from this context and all ancestor contexts
-    getFunctions() {
-        const allFunctions = [];
-
-        // Get functions from ancestor contexts via task hierarchy
-        const ancestorContexts = this.getAncestorContexts();
-        for (const ctx of ancestorContexts) {
-            if (ctx.functions && Array.isArray(ctx.functions))
-                allFunctions.push(...ctx.functions);
-        }
-
-        // Add our own functions
-        if (this.functions && Array.isArray(this.functions))
-            allFunctions.push(...this.functions);
-
-        return allFunctions.length > 0 ? allFunctions : null;
-    }
-
     async summarizeMessages() {
         const tokens = util.countTokens(this.__msgs);
         if (tokens < this.lower_limit)
@@ -416,7 +405,7 @@ class Context {
     }
 
     async close() {
-        _log('Closing Context tag', this.tag);
+        _log('Closing Msgs tag', this.tag);
 
         if (this._sequential_mode && this._processing_sequential) {
             _ldbg('Sequential mode: waiting for current message to complete before closing tag', this.tag);
@@ -429,52 +418,10 @@ class Context {
             }
         }
 
-        // Move waiting messages to parent context via task hierarchy
-        const parentCtx = this.getParentContext();
-        if (parentCtx && this._waitingQueue.length > 0) {
-            _log('Moving', this._waitingQueue.length, 'waiting messages to parent context');
-            parentCtx._waitingQueue.push(...this._waitingQueue);
-            this._waitingQueue = [];
-        }
-
-        if (parentCtx && this._sequential_queue.length > 0) {
-            _log('Moving', this._sequential_queue.length, 'sequential queue messages to parent context');
-            parentCtx._sequential_queue.push(...this._sequential_queue);
-            this._sequential_queue = [];
-        }
-
-        await this._summarizeContext(true, parentCtx);
-        _log('Finished closing Context tag', this.tag);
+        await this._summarizeContext(true);
+        _log('Finished closing Msgs tag', this.tag);
     }
 
-    // Load chat history from store into message queue
-    async loadHistory(store) {
-        if (!store || !this.tag)
-            return;
-        const data = await store.load(this.tag);
-        if (!data)
-            return;
-        if (Array.isArray(data.tool_digest))
-            this.tool_digest = data.tool_digest;
-        if (!data.chat_history)
-            return;
-        const messages = await util.decompressMessages(data.chat_history);
-        if (!Array.isArray(messages) || messages.length === 0)
-            return;
-        // Find the index after the last system message to insert history
-        let insertIdx = 0;
-        for (let i = 0; i < this._msgs.length; i++) {
-            if (this._msgs[i].msg.role === 'system')
-                insertIdx = i + 1;
-        }
-        const historyMsgs = messages.map(m => ({
-            msg: m,
-            opts: {},
-            msgid: crypto.randomBytes(2).toString('hex'),
-            replied: 1
-        }));
-        this._msgs.splice(insertIdx, 0, ...historyMsgs);
-    }
 
     // Remove tool-related messages tagged with a specific tag
     cleanToolCallsByTag(tag) {
@@ -576,38 +523,6 @@ class Context {
         return summary;
     }
 
-    // Get message context - walks up task hierarchy to collect prompts and summaries
-    getMsgContext(add_tag) {
-        const msgs = [];
-
-        // Get context from ancestor tasks via task hierarchy
-        const ancestorContexts = this.getAncestorContexts();
-        for (const ctx of ancestorContexts) {
-            if (ctx.prompt)
-                msgs.push({role: 'system', content: ctx.prompt});
-            // Add summaries from ancestor contexts
-            const summaries = ctx._msgs.filter(m => m.opts.summary || m.msg.role === 'system').map(m => {
-                if (add_tag)
-                    m.msg.tag = ctx.tag;
-                return m.msg;
-            });
-            msgs.push(...summaries);
-        }
-
-        // Add this context's prompt
-        if (this.prompt)
-            msgs.push({role: 'system', content: this.prompt});
-
-        // Add this context's summaries
-        const mySummaries = this._msgs.filter(m => m.opts.summary || m.msg.role === 'system').map(m => {
-            if (add_tag)
-                m.msg.tag = this.tag;
-            return m.msg;
-        });
-
-        return msgs.concat(mySummaries);
-    }
-
     _createMsgObj(role, content, functions, opts) {
         const name = opts?.name;
         const tool_call_id = opts?.tool_call_id;
@@ -937,10 +852,10 @@ class Context {
                     ? [...o.opts._aggregatedFunctions, ...messageFuncs]
                     : null;
             } else {
-                const hierarchyFuncs = this.getFunctions() || [];
+                const ownFuncs = this.functions || [];
                 const messageFuncs = o.functions || [];
-                funcs = [...hierarchyFuncs, ...messageFuncs].length > 0
-                    ? [...hierarchyFuncs, ...messageFuncs]
+                funcs = [...ownFuncs, ...messageFuncs].length > 0
+                    ? [...ownFuncs, ...messageFuncs]
                     : null;
             }
 
@@ -1009,15 +924,15 @@ class Context {
 
                 for (const { call, isDuplicate } of toolCallsWithResults) {
                     if (!isDuplicate) {
-                        const _snap = this.task
-                            ? JSON.stringify(this._snapshotPublicProps(this.task)) : null;
+                        const _snap = this._getSnapshot
+                            ? JSON.stringify(this._getSnapshot()) : null;
                         try {
                             const result = await this._executeToolCallWithTimeout(
                                 call, o.opts?.timeout);
                             const item = toolCallsWithResults.find(item => item.call.id === call.id);
                             if (item) item.result = result;
                             if (_snap !== null &&
-                                _snap !== JSON.stringify(this._snapshotPublicProps(this.task)))
+                                _snap !== JSON.stringify(this._getSnapshot()))
                                 this._appendToolDigest(call.function.name, result?.content || '');
                         } finally {
                             this._completeActiveToolCall(call);
@@ -1073,39 +988,11 @@ class Context {
     }
 
     /**
-     * Search the Saico hierarchy for a TOOL_<toolName> method.
-     * Order: current task → walk UP parents → walk DOWN children (BFS).
+     * Find a TOOL_<toolName> implementation. Delegates to _findToolImpl callback
+     * set by Saico, which searches the hierarchy.
      */
     _findToolImplementation(toolName) {
-        const methodName = 'TOOL_' + toolName;
-        const check = (task) =>
-            task?._saico && typeof task._saico[methodName] === 'function' ? task._saico : null;
-
-        // 1. Current task
-        let found = check(this.task);
-        if (found) return { saico: found, methodName };
-
-        // 2. Walk UP parent chain
-        let t = this.task?.parent;
-        while (t) {
-            found = check(t);
-            if (found) return { saico: found, methodName };
-            t = t.parent;
-        }
-
-        // 3. Walk DOWN from this.task (BFS)
-        if (this.task) {
-            const queue = [...this.task.child];
-            while (queue.length > 0) {
-                const child = queue.shift();
-                if (child._completed) continue;
-                found = check(child);
-                if (found) return { saico: found, methodName };
-                if (child.child?.size > 0) queue.push(...child.child);
-            }
-        }
-
-        return null;
+        return this._findToolImpl ? this._findToolImpl(toolName) : null;
     }
 
     async interpretAndApplyChanges(call) {
@@ -1154,35 +1041,11 @@ class Context {
         return { content, functions };
     }
 
-    // Spawn child context (creates a child task with its own context)
-    spawnChild(prompt, tag, config = {}) {
-        if (!this.task) {
-            // If no task, create a standalone context
-            return createContext(prompt, null, { ...config, tag });
-        }
-
-        // Create a child task with its own context
-        const Itask = require('./itask.js');
-        const childTask = new Itask({
-            name: tag || 'child-context',
-            async: true,
-        }, []);
-        this.task.spawn(childTask);
-
-        const childContext = new Context(prompt, childTask, { ...config, tag });
-        // Store context on Saico if present, otherwise just set on task reference
-        if (childTask._saico) {
-            childTask._saico.context = childContext;
-            childTask._saico.context_id = childContext.tag;
-        }
-
-        return childContext;
-    }
 }
 
-// Factory function to create a Context with Proxy wrapper
-function createContext(prompt, task, config = {}) {
-    const instance = new Context(prompt, task, config);
+// Factory function to create a Msgs instance with Proxy wrapper
+function createMsgs(prompt, config = {}) {
+    const instance = new Msgs(prompt, config);
 
     return new Proxy(instance, {
         get(target, prop, receiver) {
@@ -1231,4 +1094,4 @@ function createContext(prompt, task, config = {}) {
     });
 }
 
-module.exports = { Context, createContext };
+module.exports = { Msgs, createMsgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.7.1",
+  "version": "2.8.1",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",

package/saico.js

@@ -2,7 +2,7 @@
 
 const crypto = require('crypto');
 const Itask = require('./itask.js');
-const { Context } = require('./msgs.js');
+const { Msgs } = require('./msgs.js');
 const { Store } = require('./store.js');
 const util = require('./util.js');
 
@@ -47,7 +47,7 @@ class Saico {
      */
     constructor(opt = {}) {
         // Internal properties (underscore-prefixed, not persisted to Redis)
-        this._id = opt.id || crypto.randomBytes(8).toString('hex');
+        this.id = opt.id || crypto.randomBytes(8).toString('hex');
         this._task = null;
         this._store = opt.store || Store.instance || null;
         this._opt = opt;
@@ -91,7 +91,7 @@ class Saico {
         try {
             const redis = require('./redis.js');
             if (redis.rclient && opt.redis !== false) {
-                const key = 'saico:' + (opt.key || this._id);
+                const key = 'saico:' + (opt.key || this.id);
                 return redis.createObservableForRedis(key, this);
             }
         } catch (e) { /* redis not available */ }
@@ -152,14 +152,21 @@ class Saico {
                 sequential_mode: opts.sequential_mode,
                 msgs: opts.msgs,
                 chat_history: opts.chat_history,
+                tool_digest: opts.tool_digest,
                 ...opts.contextConfig,
             };
 
             const augmentedPrompt = effectivePrompt
                 ? effectivePrompt + Saico.BACKEND_EXPLANATION
                 : '';
-            const context = new Context(augmentedPrompt, this._task, contextConfig);
-            this.setContext(context);
+            const msgs = new Msgs(augmentedPrompt, contextConfig);
+            this.context = msgs;
+            this.context_id = makeId(16);
+            msgs.tag = this.context_id;
+
+            // Wire callbacks for hierarchy access
+            msgs._findToolImpl = (toolName) => this._findToolImpl(toolName);
+            msgs._getSnapshot = () => msgs._snapshotPublicProps(this);
         }
 
         return this;
@@ -167,29 +174,6 @@ class Saico {
 
     // ---- Context management (owned by Saico, not Itask) ----
 
-    /**
-     * Set context on this Saico instance.
-     * Generates context_id, sets context.tag, and calls context.setTask().
-     */
-    setContext(context) {
-        this.context = context;
-        // Generate context_id if not already set
-        if (!this.context_id) {
-            if (this._store)
-                this.context_id = this._store.generateId();
-            else if (Store.instance)
-                this.context_id = Store.instance.generateId();
-            else
-                this.context_id = makeId(16);
-        }
-        if (context) {
-            context.tag = this.context_id;
-            if (typeof context.setTask === 'function')
-                context.setTask(this._task);
-        }
-        return this;
-    }
-
     /**
      * Find the nearest context walking UP the Saico/task hierarchy.
      */
@@ -223,51 +207,6 @@ class Saico {
         return deepest ? deepest.context : null;
     }
 
-    /**
-     * Close this Saico's context and bubble summary to parent.
-     */
-    async closeContext() {
-        if (!this.context)
-            return;
-
-        // Clean tool call messages tagged with this context_id
-        if (this.context_id && typeof this.context.cleanToolCallsByTag === 'function')
-            this.context.cleanToolCallsByTag(this.context_id);
-
-        // Filter out tool calls and [BACKEND] messages, compress remaining as chat_history
-        const cleanedMsgs = this.context._msgs.filter(m => {
-            if (m.msg.tool_calls) return false;
-            if (m.msg.role === 'tool') return false;
-            if (typeof m.msg.content === 'string' && m.msg.content.startsWith('[BACKEND]')) return false;
-            return true;
-        }).map(m => m.msg);
-
-        // Trim to last QUEUE_LIMIT before persisting
-        const queueLimit = this.context.QUEUE_LIMIT || 30;
-        const trimmedMsgs = cleanedMsgs.length > queueLimit
-            ? cleanedMsgs.slice(-queueLimit)
-            : cleanedMsgs;
-
-        if (trimmedMsgs.length > 0) {
-            const chat_history = await util.compressMessages(trimmedMsgs);
-            this.context.chat_history = chat_history;
-
-            // Persist to store
-            const store = this._store || Store.instance;
-            if (store && this.context_id) {
-                await store.save(this.context_id, {
-                    chat_history,
-                    tool_digest: this.context.tool_digest || [],
-                    prompt: this.context.prompt,
-                    tag: this.context.tag,
-                    tm_closed: Date.now()
-                });
-            }
-        }
-
-        await this.context.close();
-    }
-
     /**
      * Deactivate — bubble cleaned messages to parent, close context, cancel task.
      * Pushes cleaned messages (no tool calls, no BACKEND) into the parent's Q,
@@ -309,15 +248,16 @@ class Saico {
     spawn(child) {
         if (!this._task)
             throw new Error('Not activated. Call activate() first.');
-        if (!(child instanceof Saico) || !child._task)
-            throw new Error('Child must be an activated Saico instance.');
+        if (!(child instanceof Saico))
+            throw new Error('Child must be a Saico instance.');
+        if (!child._task) child.activate();
         this._task.spawn(child._task);
         return child;
     }
 
     /**
      * Spawn a child Saico and start its task running.
-     * @param {Saico} child - An activated Saico instance
+     * @param {Saico} child - A Saico instance (auto-activated if needed)
      * @returns {Saico} the child (for chaining)
      */
     spawnAndRun(child) {
@@ -487,6 +427,41 @@ class Saico {
         return parts.length > 0 ? parts : null;
     }
 
+    // ---- Tool implementation search ----
+
+    /**
+     * Search the Saico hierarchy for a TOOL_<toolName> method.
+     * Order: current task → walk UP parents → walk DOWN children (BFS).
+     */
+    _findToolImpl(toolName) {
+        const methodName = 'TOOL_' + toolName;
+        const check = (task) =>
+            task?._saico && typeof task._saico[methodName] === 'function' ? task._saico : null;
+
+        let found = check(this._task);
+        if (found) return { saico: found, methodName };
+
+        let t = this._task?.parent;
+        while (t) {
+            found = check(t);
+            if (found) return { saico: found, methodName };
+            t = t.parent;
+        }
+
+        if (this._task) {
+            const queue = [...this._task.child];
+            while (queue.length > 0) {
+                const child = queue.shift();
+                if (child._completed) continue;
+                found = check(child);
+                if (found) return { saico: found, methodName };
+                if (child.child?.size > 0) queue.push(...child.child);
+            }
+        }
+
+        return null;
+    }
+
     // ---- User Data (absorbed from Sid) ----
 
     setUserData(key, value) {
@@ -507,7 +482,7 @@ class Saico {
 
     getSessionInfo() {
         return {
-            id: this._id,
+            id: this.id,
             name: this.name,
             running: this._task?.running || false,
             completed: this._task?._completed || false,
@@ -518,10 +493,38 @@ class Saico {
         };
     }
 
+    /**
+     * Close the session — compress msgs, save full state to Store, cancel task.
+     * The saved object has the same shape as serialize() but with compressed
+     * context messages (chat_history) instead of raw _msgs.
+     */
     async closeSession() {
         if (!this._task) return;
-        if (this.context)
-            await this.context.close();
+
+        // Save full state to Store with compressed msgs
+        const store = this._store || Store.instance;
+        if (store && this.context) {
+            const { chat_history, tool_digest } = await this.context.prepareForStorage();
+            const data = {
+                id: this.id,
+                name: this.name,
+                prompt: this.prompt,
+                userData: this.userData,
+                sessionConfig: this.sessionConfig,
+                tm_create: this.tm_create,
+                isolate: this._isolate,
+                taskId: this._task.id,
+                context_id: this.context_id,
+                context: {
+                    tag: this.context.tag,
+                    chat_history,
+                    tool_digest,
+                    functions: this.context.functions,
+                },
+            };
+            await store.save(this.id, data);
+        }
+
         this._task._ecancel();
     }
 
@@ -625,9 +628,14 @@ class Saico {
 
     // ---- Serialization ----
 
+    /**
+     * Serialize the Saico instance to a JSON string.
+     * Context messages are included as raw _msgs (for Redis / in-memory use).
+     * For durable storage with compressed msgs, use closeSession().
+     */
     serialize() {
         const data = {
-            id: this._id,
+            id: this.id,
             name: this.name,
             prompt: this.prompt,
             userData: this.userData,
@@ -635,24 +643,21 @@ class Saico {
             tm_create: this.tm_create,
             isolate: this._isolate,
         };
-        if (this._task) {
-            data.task = {
-                id: this._task.id,
-                context_id: this.context_id,
-                context: this.context ? {
-                    tag: this.context.tag,
-                    msgs: this.context._msgs,
-                    functions: this.context.functions,
-                    chat_history: this.context.chat_history,
-                    tool_digest: this.context.tool_digest,
-                } : null,
-            };
-        }
+        data.taskId = this._task?.id || null;
+        data.context_id = this.context_id || null;
+        data.context = this.context ? {
+            tag: this.context.tag,
+            msgs: this.context._msgs,
+            functions: this.context.functions,
+            tool_digest: this.context.tool_digest,
+        } : null;
         return JSON.stringify(data);
     }
 
     /**
      * Restore a Saico instance from serialized data.
+     * Supports both raw msgs (from serialize/Redis) and compressed
+     * chat_history (from closeSession/Store).
      * @param {string|Object} data - Serialized data (JSON string or object)
      * @param {Object} opt - Options (functions, store, states, etc.)
      * @returns {Saico}
@@ -667,38 +672,54 @@ class Saico {
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             isolate: parsed.isolate,
-            functions: opt.functions || parsed.task?.context?.functions,
+            functions: opt.functions || parsed.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) {
+        // Activate with restored state if taskId exists
+        if (parsed.taskId) {
+            const ctx = parsed.context;
             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,
+                createQ: !!ctx,
+                taskId: parsed.taskId,
+                tag: ctx?.tag,
+                chat_history: ctx?.chat_history,
+                functions: opt.functions || ctx?.functions,
+                tool_digest: ctx?.tool_digest,
                 states: opt.states || [],
                 ...opt,
             });
 
-            // Restore messages to context
-            if (parsed.task.context?.msgs && instance.context) {
-                instance.context._msgs = parsed.task.context.msgs;
-            }
-
-            // Restore tool_digest
-            if (Array.isArray(parsed.task.context?.tool_digest) && instance.context) {
-                instance.context.tool_digest = parsed.task.context.tool_digest;
+            // Restore raw msgs (from serialize/Redis) — takes priority over chat_history
+            if (ctx?.msgs && instance.context) {
+                instance.context._msgs = ctx.msgs;
             }
         }
 
         return instance;
     }
+
+    /**
+     * Load a Saico instance from Store by id.
+     * @param {string} id - The Saico instance id
+     * @param {Object} opt - Options (store, functions, states, etc.)
+     * @returns {Promise<Saico|null>}
+     */
+    static async rehydrate(id, opt = {}) {
+        const store = opt.store || Store.instance;
+        if (!store)
+            throw new Error('No store available for rehydrate');
+        const data = await store.load(id);
+        if (!data) return null;
+        const instance = Saico.deserialize(data, opt);
+        // Decompress chat_history into _msgs if present
+        if (instance.context)
+            await instance.context.initHistory();
+        return instance;
+    }
 }
 
 // [BACKEND] explanation text appended to context prompts