saico 2.3.0 → 2.4.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');
@@ -144,7 +143,6 @@ module.exports = {
     // Core classes
     Itask,
     Context,
-    Sid,
     Store,
     DynamoBackend,
 
@@ -153,7 +151,6 @@ module.exports = {
 
     // Factory functions
     createTask,
-    createSid,
     createContext,
 
     // Legacy compatibility

package/itask.js

@@ -746,9 +746,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

@@ -69,39 +69,6 @@ class Context {
             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.
@@ -822,52 +789,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 +894,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 +919,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.3.0",
+  "version": "2.4.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",