saico 2.8.0 → 2.8.1

package/README.md

@@ -260,7 +260,7 @@ agent.getSessionInfo();
 await agent.closeSession();  // Saves full state to Store, cancels task
 
 // Restore from Store
-const restored = await Saico.rehydrate(agent._id, { store });
+const restored = await Saico.rehydrate(agent.id, { store });
 ```
 
 ## Database Access
@@ -307,7 +307,7 @@ const restored = Saico.deserialize(json);
 
 // Durable persistence (compressed msgs, saved to Store)
 await agent.closeSession();
-const restored2 = await Saico.rehydrate(agent._id, { store });
+const restored2 = await Saico.rehydrate(agent.id, { store });
 ```
 
 `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.
@@ -330,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 {
@@ -359,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);
 ```
 
@@ -390,7 +390,7 @@ saico/
 npm test
 ```
 
-296 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, persistence (closeSession/rehydrate), 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;
@@ -50,18 +44,15 @@ class Context {
         // Tool digest — persistent history of tool calls that mutated task state
         this.tool_digest = config.tool_digest || [];
 
+        // 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);
-    }
-
-    // Set the task reference (used when context is created separately)
-    setTask(task) {
-        this.task = task;
-        if (!this.functions)
-            this.functions = task?.functions;
+        _log('created Msgs for tag', this.tag);
     }
 
     /**
@@ -135,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);
 
@@ -334,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);
@@ -433,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)
@@ -459,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);
@@ -472,22 +418,8 @@ 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);
     }
 
 
@@ -591,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;
@@ -952,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;
             }
 
@@ -1024,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);
@@ -1088,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) {
@@ -1169,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) {
@@ -1246,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.8.0",
+  "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 */ }
@@ -159,8 +159,14 @@ class Saico {
             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;
@@ -168,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.
      */
@@ -444,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) {
@@ -464,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,
@@ -488,7 +506,7 @@ class Saico {
         if (store && this.context) {
             const { chat_history, tool_digest } = await this.context.prepareForStorage();
             const data = {
-                id: this._id,
+                id: this.id,
                 name: this.name,
                 prompt: this.prompt,
                 userData: this.userData,
@@ -504,7 +522,7 @@ class Saico {
                     functions: this.context.functions,
                 },
             };
-            await store.save(this._id, data);
+            await store.save(this.id, data);
         }
 
         this._task._ecancel();
@@ -617,7 +635,7 @@ class Saico {
      */
     serialize() {
         const data = {
-            id: this._id,
+            id: this.id,
             name: this.name,
             prompt: this.prompt,
             userData: this.userData,