saico 2.0.0 → 2.1.0

package/context.js

@@ -34,6 +34,9 @@ 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();
@@ -397,6 +400,44 @@ class Context {
         _log('Finished closing Context 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 || !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) {
+        this._msgs = this._msgs.filter(m => {
+            if (m.opts.tag !== tag)
+                return true;
+            if (m.msg.tool_calls)
+                return false;
+            if (m.msg.role === 'tool')
+                return false;
+            return true;
+        });
+    }
+
     async _summarizeContext(close, targetCtx) {
         const keep = this._msgs.filter(m => !close && m.summary);
         const summarize = this._msgs.filter(m => (!close || !m.summary) && m.replied);
@@ -971,7 +1012,10 @@ class Context {
         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`;
+        {
+            content = `tool call ${call.function.name} ${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) + '...',
             functions ? 'with functions' : 'no functions');

package/index.js

@@ -9,20 +9,44 @@
  * - Optional conversation contexts attached to tasks
  * - Hierarchical message aggregation with function collection
  * - Full tool_calls support with depth control
+ * - Storage persistence (Redis cache + optional DB backend)
  *
  * Main Components:
  * - 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('./context.js');
 const { Sid, createSid } = require('./sid.js');
+const { Store, DynamoBackend } = require('./store.js');
 
 // Wire up Context class reference in Itask to avoid circular dependency
 Itask.Context = Context;
 
+/**
+ * Initialize Saico with storage configuration.
+ * Sets up the Store singleton and optionally initializes Redis.
+ *
+ * @param {Object} config - Configuration options
+ * @param {boolean} config.redis - Whether to initialize Redis
+ * @param {Object} config.dynamodb - DynamoDB backend config {table, aws}
+ * @returns {Store} The initialized Store instance
+ */
+async function init(config = {}) {
+    const store = Store.init(config);
+
+    if (config.redis) {
+        const redis = require('./redis.js');
+        await redis.init();
+        store.setRedis(redis.rclient);
+    }
+
+    return store;
+}
+
 /**
  * Create a new task with optional context.
  *
@@ -35,6 +59,7 @@ Itask.Context = Context;
  * @param {Object} opt.bind - Bind context for state functions
  * @param {Itask} opt.spawn_parent - Parent task to spawn under
  * @param {boolean} opt.async - If true, don't auto-run
+ * @param {Object} opt.store - Store instance for persistence
  * @param {Array} states - Array of state functions
  * @returns {Itask} The created task
  */
@@ -42,6 +67,9 @@ function createTask(opt, states = []) {
     if (typeof opt === 'string')
         opt = { name: opt };
 
+    if (!opt.store)
+        opt.store = Store.instance;
+
     const task = new Itask(opt, states);
 
     // Auto-create context if prompt is provided
@@ -95,7 +123,8 @@ function createQ(prompt, parent, tag, token_limit, msgs, tool_handler, config =
         const childTask = new Itask({
             name: tag || 'child-context',
             async: true,
-            spawn_parent: parent.task
+            spawn_parent: parent.task,
+            store: Store.instance
         }, []);
         context.setTask(childTask);
         childTask.setContext(context);
@@ -110,6 +139,11 @@ module.exports = {
     Itask,
     Context,
     Sid,
+    Store,
+    DynamoBackend,
+
+    // Initialization
+    init,
 
     // Factory functions
     createTask,

package/itask.js

@@ -18,6 +18,7 @@ const assert = require('assert');
 const EventEmitter = require('events');
 const crypto = require('crypto');
 const util = require('./util.js');
+const { Store } = require('./store.js');
 
 const { _log, lerr , _ldbg, daysSince, minSince, shallowEqual, filterArray, logEvent } = util;
 
@@ -102,6 +103,10 @@ function Itask(opt, states){
     this.context = null;
     this._contextConfig = opt.contextConfig || {};
 
+    // Storage persistence
+    this.context_id = opt.context_id || null;
+    this._store = opt.store || Store.instance || null;
+
     // Store options for context creation (prompt, functions, etc.)
     this.prompt = opt.prompt;
     this.functions = opt.functions;
@@ -370,6 +375,15 @@ Itask.prototype.spawn = function spawn(child){
             Itask.root.delete(child);
             child._root_registered = false;
         }
+        // Auto-wrap with redis observable for live state persistence
+        if (child.context_id) {
+            try {
+                const redis = require('./redis.js');
+                if (redis.rclient) {
+                    redis.createObservableForRedis('saico:' + child.context_id, child);
+                }
+            } catch (e) { /* redis not available */ }
+        }
         // ensure async-created children begin execution
         if (!child.running && !child._completed){
             process.nextTick(() => {
@@ -578,6 +592,11 @@ Itask.ps = function ps(){
 };
 
 /* ---------- context management ---------- */
+// [BACKEND] explanation text appended to context prompts
+Itask.BACKEND_EXPLANATION = '\nNote: Messages prefixed with [BACKEND] are from the backend ' +
+    'server, not the user. They contain server instructions, data updates, or system context. ' +
+    'Treat them as authoritative system-level information.';
+
 // Get the context for this task, optionally creating one if needed
 Itask.prototype.getContext = function getContext(createIfMissing = false){
     if (this.context)
@@ -585,7 +604,9 @@ Itask.prototype.getContext = function getContext(createIfMissing = false){
     if (createIfMissing && this.prompt){
         // Lazy context creation - requires Context class to be set
         if (Itask.Context){
-            this.context = new Itask.Context(this.prompt, this, this._contextConfig);
+            const augmentedPrompt = this.prompt + Itask.BACKEND_EXPLANATION;
+            this.context = new Itask.Context(augmentedPrompt, this, this._contextConfig);
+            this.setContext(this.context);
             return this.context;
         }
     }
@@ -595,8 +616,20 @@ Itask.prototype.getContext = function getContext(createIfMissing = false){
 // Set context for this task
 Itask.prototype.setContext = function setContext(context){
     this.context = context;
-    if (context && typeof context.setTask === 'function')
-        context.setTask(this);
+    // 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);
+    }
     return this;
 };
 
@@ -623,9 +656,10 @@ Itask.prototype.findContext = function findContext(){
     return null;
 };
 
-// Send a message using the context hierarchy
-// Delegates to the task's context, or walks up to find one
-Itask.prototype.sendMessage = async function sendMessage(role, content, functions, opts){
+// Send a backend message using the context hierarchy
+// New signature: sendMessage(content, functions, opts)
+// Always sends as role='user' with '[BACKEND] ' prefix
+Itask.prototype.sendMessage = async function sendMessage(content, functions, opts){
     // First try our own context
     let ctx = this.getContext();
     if (!ctx){
@@ -635,9 +669,21 @@ Itask.prototype.sendMessage = async function sendMessage(role, content, function
     if (!ctx){
         throw new Error('No context available in task hierarchy to send message');
     }
-    // Don't pass functions here - let context aggregate from hierarchy
-    // If caller wants to override, they can pass functions in opts
-    return ctx.sendMessage(role, content, functions, opts);
+    opts = Object.assign({}, opts, { tag: this.context_id });
+    return ctx.sendMessage('user', '[BACKEND] ' + content, functions, opts);
+};
+
+// Receive a user chat message (no [BACKEND] prefix)
+Itask.prototype.recvChatMessage = async function recvChatMessage(content, opts){
+    let ctx = this.getContext();
+    if (!ctx){
+        ctx = this.findContext();
+    }
+    if (!ctx){
+        throw new Error('No context available in task hierarchy to receive message');
+    }
+    opts = Object.assign({}, opts, { tag: this.context_id });
+    return ctx.sendMessage('user', content, null, opts);
 };
 
 // Aggregate functions from all contexts in the hierarchy
@@ -658,6 +704,38 @@ Itask.prototype.getHierarchyFunctions = function getHierarchyFunctions(){
 Itask.prototype.closeContext = async function 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);
+
+    if (cleanedMsgs.length > 0) {
+        const chat_history = await util.compressMessages(cleanedMsgs);
+        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,
+                prompt: this.context.prompt,
+                tag: this.context.tag,
+                tm_closed: Date.now()
+            });
+        }
+    }
+
     await this.context.close();
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",
@@ -20,6 +20,7 @@
     "openai.js",
     "util.js",
     "redis.js",
+    "store.js",
     "README.md",
     "LICENSE"
   ],
@@ -43,7 +44,16 @@
     "test": "NODE_ENV=test mocha --exit 'test/**/*.test.js'",
     "start": "node server.js"
   },
-  "keywords": ["ai", "conversation", "orchestrator", "task", "hierarchy", "openai", "chatgpt", "llm"],
+  "keywords": [
+    "ai",
+    "conversation",
+    "orchestrator",
+    "task",
+    "hierarchy",
+    "openai",
+    "chatgpt",
+    "llm"
+  ],
   "author": "wanderli-ai",
   "license": "ISC"
 }

package/sid.js

@@ -2,6 +2,7 @@
 
 const Itask = require('./itask.js');
 const { Context, createContext } = require('./context.js');
+const { Store } = require('./store.js');
 
 /**
  * Sid - Session/User Context root task.
@@ -25,6 +26,7 @@ class Sid extends Itask {
             ...opt,
             name,
             prompt,
+            store: opt.store || Store.instance || null,
             async: true // We'll manage running ourselves
         }, states);
 
@@ -39,16 +41,23 @@ class Sid extends Itask {
             ...opt.sessionConfig
         };
 
+        // Generate context_id if not already set by parent constructor
+        if (!this.context_id) {
+            const store = this._store || Store.instance;
+            this.context_id = store ? store.generateId() : require('crypto').randomBytes(8).toString('hex');
+        }
+
         // Always create a context for Sid (root session task)
         const contextConfig = {
-            tag: opt.tag || this.id,
+            tag: this.context_id,
             token_limit: this.sessionConfig.token_limit,
             max_depth: this.sessionConfig.max_depth,
             max_tool_repetition: this.sessionConfig.max_tool_repetition,
             tool_handler: opt.tool_handler,
             functions: opt.functions,
             sequential_mode: opt.sequential_mode,
-            msgs: opt.msgs
+            msgs: opt.msgs,
+            chat_history: opt.chat_history
         };
 
         this.context = new Context(prompt, this, contextConfig);
@@ -61,9 +70,17 @@ class Sid extends Itask {
         }
     }
 
-    // Override sendMessage to always use our context
-    async sendMessage(role, content, functions, opts) {
-        return this.context.sendMessage(role, content, functions || this.functions, opts);
+    // Override sendMessage — new signature: sendMessage(content, functions, opts)
+    // Always sends as role='user' with '[BACKEND] ' prefix
+    async sendMessage(content, functions, opts) {
+        opts = Object.assign({}, opts, { tag: this.context_id });
+        return this.context.sendMessage('user', '[BACKEND] ' + content, functions || this.functions, opts);
+    }
+
+    // Receive a user chat message (no [BACKEND] prefix)
+    async recvChatMessage(content, opts) {
+        opts = Object.assign({}, opts, { tag: this.context_id });
+        return this.context.sendMessage('user', content, null, opts);
     }
 
     // Serialize the session for persistence
@@ -72,12 +89,14 @@ class Sid extends Itask {
             id: this.id,
             name: this.name,
             prompt: this.prompt,
+            context_id: this.context_id,
             userData: this.userData,
             sessionConfig: this.sessionConfig,
             context: {
                 tag: this.context.tag,
                 msgs: this.context._msgs,
-                functions: this.context.functions
+                functions: this.context.functions,
+                chat_history: this.context.chat_history
             },
             tm_create: this.tm_create
         });
@@ -90,11 +109,14 @@ class Sid extends Itask {
         const sid = new Sid({
             name: parsed.name,
             prompt: parsed.prompt,
+            context_id: parsed.context_id,
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             tag: parsed.context?.tag,
             tool_handler: opt.tool_handler,
             functions: opt.functions || parsed.context?.functions,
+            chat_history: parsed.context?.chat_history,
+            store: opt.store,
             async: true, // Don't auto-run states
             ...opt
         }, opt.states || []);
@@ -108,6 +130,11 @@ class Sid extends Itask {
             sid.context._msgs = parsed.context.msgs;
         }
 
+        // Load history from store if available
+        if (opt.store && parsed.context?.chat_history) {
+            sid.context.chat_history = parsed.context.chat_history;
+        }
+
         return sid;
     }
 
@@ -119,6 +146,7 @@ class Sid extends Itask {
         const childTask = new Itask({
             ...opt,
             spawn_parent: this,
+            store: this._store,
             async: true
         }, states);
 
@@ -150,6 +178,7 @@ class Sid extends Itask {
         const childTask = new Itask({
             ...opt,
             spawn_parent: this,
+            store: this._store,
             async: true
         }, states);
 

package/store.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const crypto = require('crypto');
+
+let _instance = null;
+
+class DynamoBackend {
+    constructor({ table, aws }) {
+        this.table = table;
+        this.aws = aws;
+    }
+
+    async save(id, data) {
+        await this.aws.dynamoPutItem(this.table, {
+            id,
+            data: typeof data === 'string' ? data : JSON.stringify(data),
+            updated_at: Date.now()
+        });
+    }
+
+    async load(id) {
+        const item = await this.aws.dynamoGetItem(this.table, 'id', id);
+        if (!item)
+            return null;
+        const data = item.data;
+        if (typeof data === 'string') {
+            try { return JSON.parse(data); }
+            catch (e) { return data; }
+        }
+        return data;
+    }
+
+    async delete(id) {
+        await this.aws.dynamoDeleteItem(this.table, 'id', id);
+    }
+}
+
+class Store {
+    constructor(config = {}) {
+        this._redis = null;
+        this._backends = {};
+        this._config = config;
+
+        if (config.dynamodb) {
+            this._backends.dynamodb = new DynamoBackend(config.dynamodb);
+        }
+    }
+
+    static get instance() {
+        return _instance;
+    }
+
+    static set instance(val) {
+        _instance = val;
+    }
+
+    static init(config = {}) {
+        _instance = new Store(config);
+        // If redis module provided or redis is already initialized, grab the client
+        const redis = require('./redis.js');
+        if (redis.rclient)
+            _instance._redis = redis.rclient;
+        return _instance;
+    }
+
+    setRedis(rclient) {
+        this._redis = rclient;
+    }
+
+    addBackend(name, backend) {
+        this._backends[name] = backend;
+    }
+
+    generateId() {
+        return crypto.randomBytes(8).toString('hex');
+    }
+
+    async save(id, data) {
+        const key = 'saico:' + id;
+        const serialized = typeof data === 'string' ? data : JSON.stringify(data);
+
+        // Always save to Redis if available
+        if (this._redis) {
+            try {
+                await this._redis.set(key, serialized);
+            } catch (e) {
+                console.error('Store: Redis save error:', e.message);
+            }
+        }
+
+        // Save to all configured backends
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                await backend.save(id, data);
+            } catch (e) {
+                console.error(`Store: ${name} backend save error:`, e.message);
+            }
+        }
+    }
+
+    async load(id) {
+        const key = 'saico:' + id;
+
+        // Try Redis first
+        if (this._redis) {
+            try {
+                const cached = await this._redis.get(key);
+                if (cached) {
+                    try { return JSON.parse(cached); }
+                    catch (e) { return cached; }
+                }
+            } catch (e) {
+                console.error('Store: Redis load error:', e.message);
+            }
+        }
+
+        // Fall back to backends
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                const data = await backend.load(id);
+                if (data) {
+                    // Cache to Redis for next time
+                    if (this._redis) {
+                        try {
+                            const serialized = typeof data === 'string'
+                                ? data : JSON.stringify(data);
+                            await this._redis.set(key, serialized);
+                        } catch (e) {
+                            console.error('Store: Redis cache-back error:', e.message);
+                        }
+                    }
+                    return data;
+                }
+            } catch (e) {
+                console.error(`Store: ${name} backend load error:`, e.message);
+            }
+        }
+
+        return null;
+    }
+
+    async delete(id) {
+        const key = 'saico:' + id;
+
+        if (this._redis) {
+            try {
+                await this._redis.del(key);
+            } catch (e) {
+                console.error('Store: Redis delete error:', e.message);
+            }
+        }
+
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                await backend.delete(id);
+            } catch (e) {
+                console.error(`Store: ${name} backend delete error:`, e.message);
+            }
+        }
+    }
+}
+
+module.exports = { Store, DynamoBackend };

package/util.js

@@ -1,5 +1,9 @@
 const is_mocha = process.env.NODE_ENV == 'test';
 const tiktoken = require('tiktoken');
+const zlib = require('zlib');
+const { promisify } = require('util');
+const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
 
 const debug = process.env.DEBUG === '1' || process.env.DEBUG === 'true';
 
@@ -58,6 +62,8 @@ const lerr = _lerr;
 
 module.exports = {
     countTokens,
+    compressMessages,
+    decompressMessages,
     is_mocha,
     _log,
     _lerr,
@@ -70,6 +76,34 @@ module.exports = {
     logEvent,
 }
 
+async function compressMessages(messages) {
+    const json = JSON.stringify(messages);
+    const compressed = await gzip(Buffer.from(json, 'utf8'));
+    return compressed.toString('base64');
+}
+
+async function decompressMessages(data) {
+    if (Array.isArray(data))
+        return data;
+    if (typeof data === 'string') {
+        // Try JSON parse first (plain JSON string)
+        try {
+            const parsed = JSON.parse(data);
+            if (Array.isArray(parsed))
+                return parsed;
+        } catch (e) { /* not plain JSON, try base64/gzip */ }
+        // Try base64 gzip
+        try {
+            const buf = Buffer.from(data, 'base64');
+            const decompressed = await gunzip(buf);
+            return JSON.parse(decompressed.toString('utf8'));
+        } catch (e) {
+            throw new Error('decompressMessages: unable to decompress data: ' + e.message);
+        }
+    }
+    throw new Error('decompressMessages: unsupported data type: ' + typeof data);
+}
+
 function countTokens(messages, model = "gpt-4o") {
 	// Load the encoding for the specified model
 	const encoding = tiktoken.encoding_for_model(model);