saico 2.7.0 → 2.8.0

package/README.md

@@ -69,14 +69,15 @@ Saico separates construction from activation:
 const agent = new Saico({
     name: 'agent',
     prompt: 'System prompt here',
+    createQ: true,  // message Q created on activate()
     dynamodb: { region: 'us-east-1', credentials: { accessKeyId: 'AK', secretAccessKey: 'SK' } },
 });
 
 // DB methods work before activation
 const item = await agent.dbGetItem('id', '123');
 
-// 2. Activate — creates internal task + optional message queue context
-agent.activate({ createQ: true });
+// 2. Activate — creates internal task + message Q (from this.createQ)
+agent.activate();
 
 // 3. Use — send messages, spawn children
 await agent.sendMessage('Do something');
@@ -86,6 +87,23 @@ await agent.recvChatMessage('User says hello');
 await agent.deactivate();
 ```
 
+Subclasses can also define `this.states` (task functions) in the constructor — `activate()` picks them up automatically:
+
+```js
+class MyAgent extends Saico {
+    constructor() {
+        super({ name: 'agent', prompt: 'You are helpful', createQ: true });
+        this.states = [
+            async function main() {
+                return await this.sendMessage('Starting...');
+            }
+        ];
+    }
+}
+const agent = new MyAgent();
+agent.activate();  // no params needed — uses this.createQ and this.states
+```
+
 ### Message Orchestration
 
 When `sendMessage()` or `recvChatMessage()` is called, Saico walks the parent chain to build the full LLM payload:
@@ -138,29 +156,28 @@ When a Saico's context is not the deepest active one, its last 5 user/assistant
 ### Spawning Child Saico Instances
 
 ```js
-// Child with its own conversation context
+// Child with its own conversation context (auto-activated by spawn)
 const child = new Saico({
     name: 'subtask',
     prompt: 'Handle this specific sub-task',
+    createQ: true,
     functions: [/* child-specific tools */],
 });
-child.activate({ createQ: true });
 agent.spawn(child);
 await child.sendMessage('Working on subtask...');
 
 // Child without context (uses parent's via findContext())
 const simple = new Saico({ name: 'simple' });
-simple.activate();
 agent.spawn(simple);
 await simple.sendMessage('Quick operation');
 
 // spawnAndRun: spawn + schedule child task to run on nextTick
 const runner = new Saico({ name: 'runner' });
-runner.activate({ states: [async function() { return await this.sendMessage('Go'); }] });
+runner.states = [async function() { return await this.sendMessage('Go'); }];
 agent.spawnAndRun(runner);
 ```
 
-Both parent and child must be activated before calling `spawn()` or `spawnAndRun()`.
+Parent must be activated before calling `spawn()` or `spawnAndRun()`. Children are auto-activated if needed.
 
 ### Deactivation and Message Bubbling
 
@@ -177,6 +194,7 @@ new Saico({
     // AI config
     prompt: 'System prompt',
     functions: [],             // OpenAI function definitions
+    createQ: false,            // Create message Q on activate() (also settable as this.createQ)
 
     // Behavior
     isolate: false,            // Stop ancestor aggregation
@@ -207,9 +225,9 @@ new Saico({
 
 ```js
 agent.activate({
-    createQ: true,             // Create message queue context
+    createQ: true,             // Override this.createQ for this activation
     prompt: 'Extra prompt',    // Appended to class-level prompt
-    states: [],                // Task state functions
+    states: [],                // Override this.states for this activation
     taskId: 'custom-id',
     sequential_mode: true,     // Process messages sequentially
 
@@ -239,7 +257,10 @@ agent.getSessionInfo();
 //   userData, uptime
 // }
 
-await agent.closeSession();  // Close context and cancel task
+await agent.closeSession();  // Saves full state to Store, cancels task
+
+// Restore from Store
+const restored = await Saico.rehydrate(agent._id, { store });
 ```
 
 ## Database Access
@@ -280,16 +301,16 @@ class MyAgent extends Saico {
 ## Serialization
 
 ```js
-// Save
+// In-memory snapshot (raw msgs, used by Redis proxy)
 const json = agent.serialize();
+const restored = Saico.deserialize(json);
 
-// Restore
-const restored = Saico.deserialize(json, {
-    functions: myFunctions,
-});
+// Durable persistence (compressed msgs, saved to Store)
+await agent.closeSession();
+const restored2 = await Saico.rehydrate(agent._id, { store });
 ```
 
-Serialization includes: id, name, prompt, userData, sessionConfig, tm_create, isolate, and full context state (messages, tool_digest, chat_history).
+`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.
 
 ## Redis Persistence
 
@@ -369,7 +390,7 @@ saico/
 npm test
 ```
 
-284 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
+296 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/msgs.js

@@ -33,9 +33,6 @@ 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();
@@ -53,7 +50,8 @@ class Context {
         // Tool digest — persistent history of tool calls that mutated task state
         this.tool_digest = config.tool_digest || [];
 
-        // Initialize messages if provided
+        // 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);
@@ -66,6 +64,51 @@ class Context {
             this.functions = task?.functions;
     }
 
+    /**
+     * Decompress _chat_history into _msgs. Call after construction when
+     * restoring from persisted state. No-op if chat_history is absent or
+     * _msgs were already provided via config.msgs.
+     */
+    async initHistory() {
+        if (!this._chat_history || this._msgs.length > 0)
+            return;
+        const messages = await util.decompressMessages(this._chat_history);
+        if (!Array.isArray(messages) || messages.length === 0)
+            return;
+        for (const m of messages) {
+            this._msgs.push({
+                msg: m,
+                opts: {},
+                msgid: crypto.randomBytes(2).toString('hex'),
+                replied: 1,
+            });
+        }
+    }
+
+    /**
+     * Prepare the message Q for storage. Filters out tool calls, tool
+     * responses, and [BACKEND] messages, trims to QUEUE_LIMIT, compresses.
+     * Returns { chat_history, tool_digest }. Does NOT mutate _msgs.
+     */
+    async prepareForStorage() {
+        const cleaned = this._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);
+
+        const trimmed = cleaned.length > this.QUEUE_LIMIT
+            ? cleaned.slice(-this.QUEUE_LIMIT)
+            : cleaned;
+
+        const chat_history = trimmed.length > 0
+            ? await util.compressMessages(trimmed)
+            : null;
+
+        return { chat_history, tool_digest: this.tool_digest || [] };
+    }
+
     // 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.
@@ -447,34 +490,6 @@ 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)
-            return;
-        if (Array.isArray(data.tool_digest))
-            this.tool_digest = data.tool_digest;
-        if (!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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",

package/saico.js

@@ -37,6 +37,7 @@ class Saico {
      * @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
+     * @param {boolean} [opt.createQ] - Create message Q context on activate()
      * @param {boolean} [opt.isolate] - Isolate: don't aggregate from ancestors
      * @param {Object} [opt.dynamodb] - DynamoDB config { region, credentials: { accessKeyId, secretAccessKey }, client }
      * @param {Object} [opt.db] - Pluggable DB backend
@@ -60,6 +61,7 @@ class Saico {
         this.name = opt.name || this.constructor.name || 'saico';
         this.prompt = opt.prompt || '';
         this.functions = opt.functions || null;
+        this.createQ = opt.createQ || false;
 
         // Absorbed from Sid
         this.userData = opt.userData || {};
@@ -99,10 +101,10 @@ class Saico {
      * Create the internal Itask and optionally a message Q context.
      *
      * @param {Object} opts
-     * @param {boolean} [opts.createQ] - If true, attach a message Q (Context)
+     * @param {boolean} [opts.createQ] - Override this.createQ for this activation
      * @param {string} [opts.prompt] - Additional prompt (appended to class-level)
      * @param {Array} [opts.functions] - Override functions
-     * @param {Array} [opts.states] - Task state functions
+     * @param {Array} [opts.states] - Override this.states for this activation
      * @param {string} [opts.taskId] - Custom task ID
      * @param {number} [opts.token_limit] - Token limit for context
      * @param {number} [opts.max_depth] - Max tool call depth
@@ -119,7 +121,7 @@ class Saico {
         if (this._task)
             throw new Error('Already activated. Call deactivate() first.');
 
-        const states = opts.states || [];
+        const states = opts.states || this.states || [];
 
         // Build effective prompt: class-level + activation-level
         const effectivePrompt = [this.prompt, opts.prompt].filter(Boolean).join('\n');
@@ -136,8 +138,8 @@ class Saico {
         // Store Saico reference on task for parent chain traversal
         this._task._saico = this;
 
-        // Create message Q context if requested (only via createQ flag, NOT prompt)
-        if (opts.createQ) {
+        // Create message Q context if requested (class-level or activate-level)
+        if (opts.createQ ?? this.createQ) {
             const functions = opts.functions || this.functions;
             const contextConfig = {
                 tag: opts.tag || this._task.id,
@@ -150,6 +152,7 @@ class Saico {
                 sequential_mode: opts.sequential_mode,
                 msgs: opts.msgs,
                 chat_history: opts.chat_history,
+                tool_digest: opts.tool_digest,
                 ...opts.contextConfig,
             };
 
@@ -221,51 +224,6 @@ class Saico {
         return deepest ? deepest.context : null;
     }
 
-    /**
-     * Close this Saico's context and bubble summary to parent.
-     */
-    async 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);
-
-        // Trim to last QUEUE_LIMIT before persisting
-        const queueLimit = this.context.QUEUE_LIMIT || 30;
-        const trimmedMsgs = cleanedMsgs.length > queueLimit
-            ? cleanedMsgs.slice(-queueLimit)
-            : cleanedMsgs;
-
-        if (trimmedMsgs.length > 0) {
-            const chat_history = await util.compressMessages(trimmedMsgs);
-            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,
-                    tool_digest: this.context.tool_digest || [],
-                    prompt: this.context.prompt,
-                    tag: this.context.tag,
-                    tm_closed: Date.now()
-                });
-            }
-        }
-
-        await this.context.close();
-    }
-
     /**
      * Deactivate — bubble cleaned messages to parent, close context, cancel task.
      * Pushes cleaned messages (no tool calls, no BACKEND) into the parent's Q,
@@ -307,15 +265,16 @@ class Saico {
     spawn(child) {
         if (!this._task)
             throw new Error('Not activated. Call activate() first.');
-        if (!(child instanceof Saico) || !child._task)
-            throw new Error('Child must be an activated Saico instance.');
+        if (!(child instanceof Saico))
+            throw new Error('Child must be a Saico instance.');
+        if (!child._task) child.activate();
         this._task.spawn(child._task);
         return child;
     }
 
     /**
      * Spawn a child Saico and start its task running.
-     * @param {Saico} child - An activated Saico instance
+     * @param {Saico} child - A Saico instance (auto-activated if needed)
      * @returns {Saico} the child (for chaining)
      */
     spawnAndRun(child) {
@@ -516,10 +475,38 @@ class Saico {
         };
     }
 
+    /**
+     * Close the session — compress msgs, save full state to Store, cancel task.
+     * The saved object has the same shape as serialize() but with compressed
+     * context messages (chat_history) instead of raw _msgs.
+     */
     async closeSession() {
         if (!this._task) return;
-        if (this.context)
-            await this.context.close();
+
+        // Save full state to Store with compressed msgs
+        const store = this._store || Store.instance;
+        if (store && this.context) {
+            const { chat_history, tool_digest } = await this.context.prepareForStorage();
+            const data = {
+                id: this._id,
+                name: this.name,
+                prompt: this.prompt,
+                userData: this.userData,
+                sessionConfig: this.sessionConfig,
+                tm_create: this.tm_create,
+                isolate: this._isolate,
+                taskId: this._task.id,
+                context_id: this.context_id,
+                context: {
+                    tag: this.context.tag,
+                    chat_history,
+                    tool_digest,
+                    functions: this.context.functions,
+                },
+            };
+            await store.save(this._id, data);
+        }
+
         this._task._ecancel();
     }
 
@@ -623,6 +610,11 @@ class Saico {
 
     // ---- Serialization ----
 
+    /**
+     * Serialize the Saico instance to a JSON string.
+     * Context messages are included as raw _msgs (for Redis / in-memory use).
+     * For durable storage with compressed msgs, use closeSession().
+     */
     serialize() {
         const data = {
             id: this._id,
@@ -633,24 +625,21 @@ class Saico {
             tm_create: this.tm_create,
             isolate: this._isolate,
         };
-        if (this._task) {
-            data.task = {
-                id: this._task.id,
-                context_id: this.context_id,
-                context: this.context ? {
-                    tag: this.context.tag,
-                    msgs: this.context._msgs,
-                    functions: this.context.functions,
-                    chat_history: this.context.chat_history,
-                    tool_digest: this.context.tool_digest,
-                } : null,
-            };
-        }
+        data.taskId = this._task?.id || null;
+        data.context_id = this.context_id || null;
+        data.context = this.context ? {
+            tag: this.context.tag,
+            msgs: this.context._msgs,
+            functions: this.context.functions,
+            tool_digest: this.context.tool_digest,
+        } : null;
         return JSON.stringify(data);
     }
 
     /**
      * Restore a Saico instance from serialized data.
+     * Supports both raw msgs (from serialize/Redis) and compressed
+     * chat_history (from closeSession/Store).
      * @param {string|Object} data - Serialized data (JSON string or object)
      * @param {Object} opt - Options (functions, store, states, etc.)
      * @returns {Saico}
@@ -665,38 +654,54 @@ class Saico {
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             isolate: parsed.isolate,
-            functions: opt.functions || parsed.task?.context?.functions,
+            functions: opt.functions || parsed.context?.functions,
             store: opt.store,
             redis: false, // No Redis proxy during deserialization
         });
 
         instance.tm_create = parsed.tm_create || instance.tm_create;
 
-        // Activate with restored context if task data exists
-        if (parsed.task) {
+        // Activate with restored state if taskId exists
+        if (parsed.taskId) {
+            const ctx = parsed.context;
             instance.activate({
-                createQ: !!parsed.task.context,
-                taskId: parsed.task.id,
-                tag: parsed.task.context?.tag,
-                chat_history: parsed.task.context?.chat_history,
-                functions: opt.functions || parsed.task.context?.functions,
+                createQ: !!ctx,
+                taskId: parsed.taskId,
+                tag: ctx?.tag,
+                chat_history: ctx?.chat_history,
+                functions: opt.functions || ctx?.functions,
+                tool_digest: ctx?.tool_digest,
                 states: opt.states || [],
                 ...opt,
             });
 
-            // Restore messages to context
-            if (parsed.task.context?.msgs && instance.context) {
-                instance.context._msgs = parsed.task.context.msgs;
-            }
-
-            // Restore tool_digest
-            if (Array.isArray(parsed.task.context?.tool_digest) && instance.context) {
-                instance.context.tool_digest = parsed.task.context.tool_digest;
+            // Restore raw msgs (from serialize/Redis) — takes priority over chat_history
+            if (ctx?.msgs && instance.context) {
+                instance.context._msgs = ctx.msgs;
             }
         }
 
         return instance;
     }
+
+    /**
+     * Load a Saico instance from Store by id.
+     * @param {string} id - The Saico instance id
+     * @param {Object} opt - Options (store, functions, states, etc.)
+     * @returns {Promise<Saico|null>}
+     */
+    static async rehydrate(id, opt = {}) {
+        const store = opt.store || Store.instance;
+        if (!store)
+            throw new Error('No store available for rehydrate');
+        const data = await store.load(id);
+        if (!data) return null;
+        const instance = Saico.deserialize(data, opt);
+        // Decompress chat_history into _msgs if present
+        if (instance.context)
+            await instance.context.initHistory();
+        return instance;
+    }
 }
 
 // [BACKEND] explanation text appended to context prompts