saico 2.3.0 → 2.5.0

package/index.js

@@ -12,15 +12,14 @@
  * - Storage persistence (Redis cache + optional DB backend)
  *
  * Main Components:
+ * - Saico: Master class (external users extend this)
  * - Itask: Base task class for all tasks (supports states, cancellation, promises)
  * - Context: Conversation context with message handling and tool calls
- * - Sid: Session root task (extends Itask, always has a context)
  * - Store: Storage abstraction layer (Redis + optional backends like DynamoDB)
  */
 
 const Itask = require('./itask.js');
 const { Context, createContext } = require('./msgs.js');
-const { Sid, createSid } = require('./sid.js');
 const { Store, DynamoBackend } = require('./store.js');
 const { Saico } = require('./saico.js');
 const { DynamoDBAdapter } = require('./dynamo.js');
@@ -55,7 +54,6 @@ async function init(config = {}) {
  * @param {Object|string} opt - Task options or name string
  * @param {string} opt.name - Task name
  * @param {string} opt.prompt - System prompt (if provided, creates a context)
- * @param {Function} opt.tool_handler - Tool handler function
  * @param {Array} opt.functions - Available functions for AI
  * @param {boolean} opt.cancel - Whether task is cancelable
  * @param {Object} opt.bind - Bind context for state functions
@@ -81,7 +79,6 @@ function createTask(opt, states = []) {
             token_limit: opt.token_limit,
             max_depth: opt.max_depth,
             max_tool_repetition: opt.max_tool_repetition,
-            tool_handler: opt.tool_handler,
             functions: opt.functions,
             sequential_mode: opt.sequential_mode
         });
@@ -100,11 +97,10 @@ function createTask(opt, states = []) {
  * @param {string} tag - Context tag identifier
  * @param {number} token_limit - Token limit for summarization
  * @param {Array} msgs - Initial messages
- * @param {Function} tool_handler - Tool handler function
  * @param {Object} config - Additional configuration
  * @returns {Context} Proxied Context instance
  */
-function createQ(prompt, parent, tag, token_limit, msgs, tool_handler, config = {}) {
+function createQ(prompt, parent, tag, token_limit, msgs, config = {}) {
     // For backward compatibility, if parent is a Context, get its task
     let task = null;
     if (parent && parent.task) {
@@ -115,7 +111,6 @@ function createQ(prompt, parent, tag, token_limit, msgs, tool_handler, config =
         tag,
         token_limit,
         msgs,
-        tool_handler,
         ...config
     });
 
@@ -144,7 +139,6 @@ module.exports = {
     // Core classes
     Itask,
     Context,
-    Sid,
     Store,
     DynamoBackend,
 
@@ -153,7 +147,6 @@ module.exports = {
 
     // Factory functions
     createTask,
-    createSid,
     createContext,
 
     // Legacy compatibility

package/itask.js

@@ -110,7 +110,6 @@ function Itask(opt, states){
     // Store options for context creation (prompt, functions, etc.)
     this.prompt = opt.prompt;
     this.functions = opt.functions;
-    this.tool_handler = opt.tool_handler;
 
     // register root if no explicit spawn_parent provided
     // If opt.spawn_parent provided, spawn under it
@@ -746,9 +745,22 @@ Itask.prototype.closeContext = async function closeContext(){
     await this.context.close();
 };
 
-// Overridable: contextless tasks can provide a state summary that bubbles up
-// into the nearest ancestor context's _getStateSummary().
-Itask.prototype.getStateSummary = function getStateSummary(){ return ''; };
+// Walk DOWN to find the deepest active descendant with a context
+Itask.prototype.findDeepestContext = function findDeepestContext() {
+    let deepest = this.context ? { context: this.context, depth: 0 } : null;
+    const search = (task, depth) => {
+        for (const child of task.child) {
+            if (child._completed) continue;
+            if (child.context) {
+                if (!deepest || depth + 1 >= deepest.depth)
+                    deepest = { context: child.context, depth: depth + 1 };
+            }
+            search(child, depth + 1);
+        }
+    };
+    search(this, 0);
+    return deepest ? deepest.context : null;
+};
 
 // Reference to Context class (set by index.js to avoid circular dependency)
 Itask.Context = null;

package/msgs.js

@@ -24,7 +24,6 @@ class Context {
         this.token_limit = config.token_limit || 1000000000;
         this.lower_limit = this.token_limit * 0.85;
         this.upper_limit = this.token_limit * 0.98;
-        this.tool_handler = config.tool_handler || task?.tool_handler;
         this.functions = config.functions || task?.functions || null;
 
         // Recursive depth and repetition control
@@ -63,45 +62,10 @@ class Context {
     // Set the task reference (used when context is created separately)
     setTask(task) {
         this.task = task;
-        if (!this.tool_handler)
-            this.tool_handler = task?.tool_handler;
         if (!this.functions)
             this.functions = task?.functions;
     }
 
-    // Overridable: extending classes provide current state summary
-    getStateSummary() { return ''; }
-
-    // Recursively collect state summaries from child tasks that have no context
-    // (no msg Q), stopping at children that do have one.
-    _collectChildStateSummaries(task) {
-        if (!task.child || !task.child.size) return '';
-        const parts = [];
-        for (const child of task.child) {
-            if (child.context) continue; // has its own Q — boundary, stop here
-            if (typeof child.getStateSummary === 'function') {
-                const s = child.getStateSummary();
-                if (s) parts.push(s);
-            }
-            const nested = this._collectChildStateSummaries(child);
-            if (nested) parts.push(nested);
-        }
-        return parts.join('\n');
-    }
-
-    // Internal (not overridable): own getStateSummary() + summaries from all
-    // contextless descendants, stopping at the first child that has its own Q.
-    _getStateSummary() {
-        const parts = [];
-        const own = this.getStateSummary();
-        if (own) parts.push(own);
-        if (this.task) {
-            const childSummaries = this._collectChildStateSummaries(this.task);
-            if (childSummaries) parts.push(childSummaries);
-        }
-        return parts.join('\n');
-    }
-
     // Snapshot all public (non-underscore) task properties for dirty detection.
     // Mirrors the observable proxy convention: _ prefix = internal, ignored.
     // Does NOT call serialize() — that is for persistence, not dirty detection.
@@ -320,10 +284,9 @@ class Context {
 
                     try {
                         const correspondingDeferred = deferredGroup.find(d => d.call.id === call.id);
-                        const handler = correspondingDeferred?.originalMessage.opts.handler || this.tool_handler;
                         const timeout = correspondingDeferred?.originalMessage.opts.timeout;
 
-                        result = await this._executeToolCallWithTimeout(call, handler, timeout);
+                        result = await this._executeToolCallWithTimeout(call, timeout);
                         if (_snap !== null &&
                             _snap !== JSON.stringify(this._snapshotPublicProps(this.task)))
                             this._appendToolDigest(call.function.name, result?.content || '');
@@ -702,7 +665,7 @@ class Context {
         }
     }
 
-    async _executeToolCallWithTimeout(call, handler, customTimeoutMs = null) {
+    async _executeToolCallWithTimeout(call, customTimeoutMs = null) {
         const timeoutMs = customTimeoutMs || 5000;
 
         return new Promise(async (resolve) => {
@@ -721,7 +684,7 @@ class Context {
             }, timeoutMs);
 
             try {
-                const result = await this.interpretAndApplyChanges(call, handler);
+                const result = await this.interpretAndApplyChanges(call);
 
                 if (!completed) {
                     completed = true;
@@ -822,52 +785,31 @@ class Context {
         return msgs.slice(startIdx);
     }
 
-    // Build message queue — layered structure:
-    //   Layer 1: System prompts from ancestor hierarchy + own prompt (transient)
-    //   Layer 2: [State Summary] from getStateSummary() override (transient, if non-empty)
-    //   Layer 3: [Tool Activity Log] from tool_digest (transient, if non-empty)
-    //   Layer 4: Ancestor summaries only + last QUEUE_LIMIT of own messages (persistent)
-    _createMsgQ(add_tag, tag_filter) {
-        const fullQueue = [];
-        const ancestorContexts = this.getAncestorContexts();
-
-        // Layer 1+2: Each level's prompt followed immediately by its state summary
-        for (const ctx of ancestorContexts) {
-            if (ctx.prompt) {
-                const prompt = {role: 'system', content: ctx.prompt};
-                if (add_tag) prompt.tag = ctx.tag;
+    // Build message queue.
+    // When preamble is provided (by Saico orchestrator), it is prepended as-is
+    // and does NOT count against QUEUE_LIMIT. Otherwise falls back to standalone
+    // behavior: own prompt + tool digest + own messages.
+    _createMsgQ(preamble, add_tag, tag_filter) {
+        const fullQueue = [...(preamble || [])];
+
+        // Standalone fallback — when no preamble provided, add own prompt/digest
+        if (!preamble) {
+            if (this.prompt) {
+                const prompt = {role: 'system', content: this.prompt};
+                if (add_tag) prompt.tag = this.tag;
                 fullQueue.push(prompt);
             }
-            const ctxSummary = ctx._getStateSummary();
-            if (ctxSummary)
-                fullQueue.push({role: 'system', content: '[State Summary]\n' + ctxSummary});
-        }
-        if (this.prompt) {
-            const prompt = {role: 'system', content: this.prompt};
-            if (add_tag) prompt.tag = this.tag;
-            fullQueue.push(prompt);
-        }
-        const stateSummary = this._getStateSummary();
-        if (stateSummary)
-            fullQueue.push({role: 'system', content: '[State Summary]\n' + stateSummary});
-
-        // Layer 3: Tool digest (if non-empty)
-        if (this.tool_digest.length > 0) {
-            const digestText = this.tool_digest.map(entry =>
-                `[${new Date(entry.tm).toISOString()}] ${entry.tool}: ${entry.result}`
-            ).join('\n');
-            fullQueue.push({role: 'system', content: '[Tool Activity Log]\n' + digestText});
-        }
 
-        // Layer 4: Ancestor summaries only (no full ancestor messages)
-        for (const ctx of ancestorContexts) {
-            const summaries = ctx._msgs
-                .filter(m => m.opts.summary)
-                .map(m => add_tag ? Object.assign({}, m.msg, {tag: ctx.tag}) : m.msg);
-            fullQueue.push(...summaries);
+            if (this.tool_digest.length > 0) {
+                const digestText = this.tool_digest.map(entry =>
+                    `[${new Date(entry.tm).toISOString()}] ${entry.tool}: ${entry.result}`
+                ).join('\n');
+                fullQueue.push({role: 'system', content: '[Tool Activity Log]\n' + digestText});
+            }
         }
 
         // Own messages — filter by tag if requested, then slice to QUEUE_LIMIT
+        // QUEUE_LIMIT only applies here — preamble is not counted
         let my_msgs;
         if (tag_filter !== undefined) {
             my_msgs = this._msgs.filter(m => {
@@ -948,7 +890,7 @@ class Context {
     _debugQDump(Q, functions) {
         if (util.is_mocha && process.env.PROD)
             return;
-        const dbgQ = Q || this._createMsgQ(true);
+        const dbgQ = Q || this._createMsgQ(null, true);
         if (debug) {
             console.log('MSGQDEBUG - Q:', JSON.stringify(dbgQ.map(m => ({
                 role: m.role,
@@ -973,14 +915,22 @@ class Context {
                 this._processWaitingQueue();
             }
 
-            Q = this._createMsgQ(false, o.opts?.tag);
+            Q = this._createMsgQ(o.opts?._preamble, false, o.opts?.tag);
 
-            // Aggregate functions from hierarchy and merge with message-specific functions
-            const hierarchyFuncs = this.getFunctions() || [];
-            const messageFuncs = o.functions || [];
-            const funcs = [...hierarchyFuncs, ...messageFuncs].length > 0
-                ? [...hierarchyFuncs, ...messageFuncs]
-                : null;
+            // Use aggregated functions from Saico if provided, else fall back to own
+            let funcs;
+            if (o.opts?._aggregatedFunctions) {
+                const messageFuncs = o.functions || [];
+                funcs = [...o.opts._aggregatedFunctions, ...messageFuncs].length > 0
+                    ? [...o.opts._aggregatedFunctions, ...messageFuncs]
+                    : null;
+            } else {
+                const hierarchyFuncs = this.getFunctions() || [];
+                const messageFuncs = o.functions || [];
+                funcs = [...hierarchyFuncs, ...messageFuncs].length > 0
+                    ? [...hierarchyFuncs, ...messageFuncs]
+                    : null;
+            }
 
             if (debug)
                 this._debugQDump(Q, funcs);
@@ -1051,7 +1001,7 @@ class Context {
                             ? JSON.stringify(this._snapshotPublicProps(this.task)) : null;
                         try {
                             const result = await this._executeToolCallWithTimeout(
-                                call, o.opts?.handler, o.opts?.timeout);
+                                call, o.opts?.timeout);
                             const item = toolCallsWithResults.find(item => item.call.id === call.id);
                             if (item) item.result = result;
                             if (_snap !== null &&
@@ -1110,27 +1060,84 @@ class Context {
         }
     }
 
-    async interpretAndApplyChanges(call, handler) {
-        _log('apply tool', call.function.name, 'have handler', !!handler, !!this.tool_handler);
+    /**
+     * Search the Saico hierarchy for a TOOL_<toolName> method.
+     * Order: current task → walk UP parents → walk DOWN children (BFS).
+     */
+    _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;
+    }
+
+    async interpretAndApplyChanges(call) {
         if (!call)
             return { content: '', functions: null };
 
-        _log('invoking function', call.function.name);
-        handler ||= this.tool_handler;
-        let result = await handler(call.function.name, call.function.arguments);
+        const toolName = call.function.name;
+        _log('apply tool', toolName);
+
+        const impl = this._findToolImplementation(toolName);
+        if (!impl) {
+            _log('No TOOL_ method found for:', toolName);
+            return {
+                content: `Error: No implementation found for tool "${toolName}". ` +
+                    `Expected a TOOL_${toolName}(args) method on a Saico instance in the hierarchy.`,
+                functions: null
+            };
+        }
+
+        _log('invoking TOOL_' + toolName, 'on', impl.saico.name || impl.saico.constructor.name);
+
+        let parsedArgs;
+        try {
+            parsedArgs = JSON.parse(call.function.arguments);
+        } catch (e) {
+            return {
+                content: `Error: Failed to parse arguments for tool "${toolName}": ${e.message}`,
+                functions: null
+            };
+        }
+
+        let result = await impl.saico[impl.methodName](parsedArgs);
 
         let content = result?.content || result || '';
         let functions = result?.functions || null;
 
         if (content && typeof content !== 'string')
             content = JSON.stringify(content);
-        else if (!content)
-        {
-            content = `tool call ${call.function.name} ${call.id} completed. do not reply. wait for the next msg `
-                +`from the user`;
+        else if (!content) {
+            content = `tool call ${toolName} ${call.id} completed. do not reply. wait for the next msg `
+                + `from the user`;
         }
 
-        _log('FUNCTION RESULT', call.function.name, call.id, content.substring(0, 50) + '...',
+        _log('FUNCTION RESULT', toolName, call.id, content.substring(0, 50) + '...',
             functions ? 'with functions' : 'no functions');
         return { content, functions };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",
@@ -17,7 +17,6 @@
     "itask.js",
     "context.js",
     "msgs.js",
-    "sid.js",
     "saico.js",
     "dynamo.js",
     "openai.js",