saico 2.4.0 → 2.5.0

package/README.md

@@ -27,7 +27,6 @@ class MyAgent extends Saico {
         super({
             name: 'my-agent',
             prompt: 'You are a helpful assistant.',
-            tool_handler: (name, args) => this.handleTool(name, args),
             functions: [{
                 type: 'function',
                 function: {
@@ -43,11 +42,9 @@ class MyAgent extends Saico {
         });
     }
 
-    async handleTool(name, argsString) {
-        const args = JSON.parse(argsString);
-        if (name === 'get_weather')
-            return `Weather in ${args.location}: 72F, sunny`;
-        return 'Unknown tool';
+    // Tool implementations — define TOOL_ prefix methods
+    async TOOL_get_weather(args) {
+        return `Weather in ${args.location}: 72F, sunny`;
     }
 }
 
@@ -145,7 +142,6 @@ When a Saico's context is not the deepest active one, its last 5 user/assistant
 const child = agent.spawnTaskWithContext({
     name: 'subtask',
     prompt: 'Handle this specific sub-task',
-    tool_handler: (name, args) => handleSubTools(name, args),
     functions: [/* child-specific tools */]
 }, [
     async function main() {
@@ -177,7 +173,6 @@ new Saico({
 
     // AI config
     prompt: 'System prompt',
-    tool_handler: fn,          // async (name, argsString) => result
     functions: [],             // OpenAI function definitions
 
     // Behavior
@@ -286,7 +281,6 @@ const json = agent.serialize();
 
 // Restore
 const restored = Saico.deserialize(json, {
-    tool_handler: myHandler,
     functions: myFunctions,
 });
 ```
@@ -309,16 +303,26 @@ agent.someProperty = 'value';  // Auto-saved to Redis
 
 Properties prefixed with `_` are internal and not persisted.
 
-## Tool Handler Interface
+## 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.
 
 ```js
-async function toolHandler(toolName, argumentsString) {
-    const args = JSON.parse(argumentsString);
-    // Execute tool logic
-    return result;  // string or { content: string, functions?: [] }
+class MyAgent extends Saico {
+    async TOOL_get_weather(args) {
+        // args is already JSON.parse'd
+        return `Weather in ${args.location}: 72F, sunny`;
+    }
+
+    async TOOL_search(args) {
+        const results = await search(args.query);
+        return { content: JSON.stringify(results), functions: updatedTools };
+    }
 }
 ```
 
+Return a string or `{ content: string, functions?: [] }`.
+
 ### Tool Safety Features
 
 - **Depth control** — `max_depth` (default: 5) prevents infinite tool call recursion
@@ -339,13 +343,12 @@ const { createTask, createContext, createQ } = require('saico');
 const task = createTask({
     name: 'my-task',
     prompt: 'You are helpful',
-    tool_handler: handler,
     functions: tools
 });
 const reply = await task.sendMessage('Hello');
 
 // Standalone context (legacy)
-const ctx = createQ('System prompt', null, 'tag', 4000, null, handler);
+const ctx = createQ('System prompt', null, 'tag', 4000);
 const reply = await ctx.sendMessage('user', 'Hello', functions);
 ```
 
@@ -371,7 +374,7 @@ saico/
 npm test
 ```
 
-294 tests covering Saico lifecycle, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
+293 tests covering Saico lifecycle, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
 
 ## Requirements
 

package/index.js

@@ -54,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
@@ -80,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
         });
@@ -99,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) {
@@ -114,7 +111,6 @@ function createQ(prompt, parent, tag, token_limit, msgs, tool_handler, config =
         tag,
         token_limit,
         msgs,
-        tool_handler,
         ...config
     });
 

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

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,8 +62,6 @@ 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;
     }
@@ -287,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 || '');
@@ -669,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) => {
@@ -688,7 +684,7 @@ class Context {
             }, timeoutMs);
 
             try {
-                const result = await this.interpretAndApplyChanges(call, handler);
+                const result = await this.interpretAndApplyChanges(call);
 
                 if (!completed) {
                     completed = true;
@@ -1005,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 &&
@@ -1064,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.4.0",
+  "version": "2.5.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",

package/saico.js

@@ -29,7 +29,6 @@ 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
@@ -53,7 +52,6 @@ class Saico {
         // 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
@@ -96,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
@@ -126,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`
         };
@@ -148,7 +144,6 @@ class Saico {
                 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,
-                tool_handler: taskOpt.tool_handler,
                 functions: taskOpt.functions,
                 sequential_mode: opts.sequential_mode,
                 msgs: opts.msgs,
@@ -334,7 +329,6 @@ class Saico {
                 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,
-                tool_handler: opt.tool_handler || this.tool_handler,
                 functions: opt.functions || this.functions,
             });
             childTask.setContext(childContext);
@@ -565,7 +559,7 @@ class Saico {
     /**
      * Restore a Saico instance from serialized data.
      * @param {string|Object} data - Serialized data (JSON string or object)
-     * @param {Object} opt - Options (tool_handler, functions, store, states, etc.)
+     * @param {Object} opt - Options (functions, store, states, etc.)
      * @returns {Saico}
      */
     static deserialize(data, opt = {}) {
@@ -578,7 +572,6 @@ class Saico {
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             isolate: parsed.isolate,
-            tool_handler: opt.tool_handler,
             functions: opt.functions || parsed.task?.context?.functions,
             store: opt.store,
             redis: false, // No Redis proxy during deserialization
@@ -593,7 +586,6 @@ class Saico {
                 taskId: parsed.task.id,
                 tag: parsed.task.context?.tag,
                 chat_history: parsed.task.context?.chat_history,
-                tool_handler: opt.tool_handler,
                 functions: opt.functions || parsed.task.context?.functions,
                 states: opt.states || [],
                 ...opt,