saico 2.6.1 → 2.7.1

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:
@@ -135,29 +153,32 @@ class OrderAgent extends Saico {
 
 When a Saico's context is not the deepest active one, its last 5 user/assistant messages are also included in the state summary automatically.
 
-### Spawning Child Tasks
+### Spawning Child Saico Instances
 
 ```js
 // Child with its own conversation context
-const child = agent.spawnTaskWithContext({
+const child = new Saico({
     name: 'subtask',
     prompt: 'Handle this specific sub-task',
-    functions: [/* child-specific tools */]
-}, [
-    async function main() {
-        return await this.sendMessage('Working on subtask...');
-    }
-]);
-
-// Child without context (uses parent's)
-const simple = agent.spawnTask({ name: 'simple' }, [
-    async function main() {
-        await this.sendMessage('Quick operation');
-    }
-]);
+    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'); }] });
+agent.spawnAndRun(runner);
 ```
 
-Child tasks inherit `sessionConfig` defaults (token_limit, max_depth, etc.) from the parent Saico.
+Both parent and child must be activated before calling `spawn()` or `spawnAndRun()`.
 
 ### Deactivation and Message Bubbling
 
@@ -174,6 +195,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
@@ -204,10 +226,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
-    parent: parentTask,        // Parent task to spawn under
+    states: [],                // Override this.states for this activation
     taskId: 'custom-id',
     sequential_mode: true,     // Process messages sequentially
 
@@ -336,21 +357,13 @@ Return a string or `{ content: string, functions?: [] }`.
 
 ## Low-Level API
 
-For cases where you don't need the Saico master class:
+For cases where you need a standalone context without the Saico master class:
 
 ```js
-const { createTask, createContext, createQ } = require('saico');
-
-// Create a task with context
-const task = createTask({
-    name: 'my-task',
-    prompt: 'You are helpful',
-    functions: tools
-});
-const reply = await task.sendMessage('Hello');
+const { createContext } = require('saico');
 
-// Standalone context (legacy)
-const ctx = createQ('System prompt', null, 'tag', 4000);
+// Standalone context
+const ctx = createContext('System prompt', null, { tag: 'my-tag', token_limit: 4000 });
 const reply = await ctx.sendMessage('user', 'Hello', functions);
 ```
 
@@ -358,11 +371,10 @@ const reply = await ctx.sendMessage('user', 'Hello', functions);
 
 ```
 saico/
-+-- index.js      # Entry point, exports all components
-+-- saico.js      # Saico master class
-+-- itask.js      # Base task class (hierarchy, states, cancellation)
++-- index.js      # Thin barrel file, exports all components
++-- saico.js      # Saico master class — owns context, spawn, DB, orchestration
++-- itask.js      # Pure task runner — hierarchy, states, cancellation, promises
 +-- msgs.js       # Conversation context (message queue, tool calls, summarization)
-+-- context.js    # Backward-compat shim for msgs.js
 +-- dynamo.js     # DynamoDB storage adapter
 +-- store.js      # Storage abstraction (Redis + pluggable backends)
 +-- openai.js     # OpenAI API wrapper with retry logic
@@ -376,7 +388,7 @@ saico/
 npm test
 ```
 
-293 tests covering Saico lifecycle, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
+284 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, and integration flows.
 
 ## Requirements
 

package/index.js

@@ -1,32 +1,11 @@
 'use strict';
 
-/**
- * Saico Library - Hierarchical AI Conversation Orchestrator
- *
- * Combines task hierarchy (Itask) with conversation contexts (Context) to create
- * a unified system for managing AI conversations with:
- * - Task-based organizational structure
- * - 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:
- * - 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
- * - Store: Storage abstraction layer (Redis + optional backends like DynamoDB)
- */
-
 const Itask = require('./itask.js');
 const { Context, createContext } = require('./msgs.js');
 const { Store, DynamoBackend } = require('./store.js');
 const { Saico } = require('./saico.js');
 const { DynamoDBAdapter } = require('./dynamo.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.
@@ -48,89 +27,6 @@ async function init(config = {}) {
     return store;
 }
 
-/**
- * Create a new task with optional context.
- *
- * @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 {Array} opt.functions - Available functions for AI
- * @param {boolean} opt.cancel - Whether task is cancelable
- * @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
- */
-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
-    if (opt.prompt) {
-        const context = new Context(opt.prompt, task, {
-            tag: opt.tag || task.id,
-            token_limit: opt.token_limit,
-            max_depth: opt.max_depth,
-            max_tool_repetition: opt.max_tool_repetition,
-            functions: opt.functions,
-            sequential_mode: opt.sequential_mode
-        });
-        task.setContext(context);
-    }
-
-    return task;
-}
-
-/**
- * Legacy createQ function for backward compatibility.
- * Creates a standalone Context (not attached to a task).
- *
- * @param {string} prompt - System prompt
- * @param {Context} parent - Parent context (legacy, will be converted to task-based)
- * @param {string} tag - Context tag identifier
- * @param {number} token_limit - Token limit for summarization
- * @param {Array} msgs - Initial messages
- * @param {Object} config - Additional configuration
- * @returns {Context} Proxied Context instance
- */
-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) {
-        task = parent.task;
-    }
-
-    const context = createContext(prompt, task, {
-        tag,
-        token_limit,
-        msgs,
-        ...config
-    });
-
-    // If there's a parent context, set up the relationship via tasks
-    if (parent && parent.task) {
-        // Create a child task to hold this context
-        const childTask = new Itask({
-            name: tag || 'child-context',
-            async: true,
-            spawn_parent: parent.task,
-            store: Store.instance
-        }, []);
-        context.setTask(childTask);
-        childTask.setContext(context);
-    }
-
-    return context;
-}
-
-// Export all components
 module.exports = {
     // Master class (external users extend this)
     Saico,
@@ -145,13 +41,9 @@ module.exports = {
     // Initialization
     init,
 
-    // Factory functions
-    createTask,
+    // Factory
     createContext,
 
-    // Legacy compatibility
-    createQ,
-
     // Utilities (re-export from util.js)
     util: require('./util.js'),
 
@@ -159,5 +51,5 @@ module.exports = {
     openai: require('./openai.js'),
 
     // Redis persistence (re-export)
-    redis: require('./redis.js')
+    redis: require('./redis.js'),
 };

package/itask.js

@@ -14,13 +14,11 @@
 
 'use strict';
 
-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;
+const { _log, lerr , _ldbg } = util;
 
 /* ---------- utility ---------- */
 function makeId(len = 12){
@@ -99,26 +97,9 @@ function Itask(opt, states){
     this._cancel_state_idx = this.states.findIndex(s => s.cancel);
     this._root_registered = false;
 
-    // Context support - optional conversation context attached to this task
-    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;
-
-    // register root if no explicit spawn_parent provided
-    // If opt.spawn_parent provided, spawn under it
-    if (opt.spawn_parent && opt.spawn_parent instanceof Itask){
-        opt.spawn_parent.spawn(this);
-    } else {
-        Itask.root.add(this);
-        this._root_registered = true;
-    }
+    // All tasks register as root; parent set via itask.spawn()
+    Itask.root.add(this);
+    this._root_registered = true;
 
     // async option defers immediate run
     if (!opt.async){
@@ -376,15 +357,6 @@ 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(() => {
@@ -594,181 +566,6 @@ Itask.ps = function ps(){
     return out || '<no roots>';
 };
 
-/* ---------- 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)
-        return this.context;
-    if (createIfMissing && this.prompt){
-        // Lazy context creation - requires Context class to be set
-        if (Itask.Context){
-            const augmentedPrompt = this.prompt + Itask.BACKEND_EXPLANATION;
-            this.context = new Itask.Context(augmentedPrompt, this, this._contextConfig);
-            this.setContext(this.context);
-            return this.context;
-        }
-    }
-    return null;
-};
-
-// Set context for this task
-Itask.prototype.setContext = function setContext(context){
-    this.context = context;
-    // 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;
-};
-
-// Get all ancestor contexts (walking up the task hierarchy)
-Itask.prototype.getAncestorContexts = function getAncestorContexts(){
-    const contexts = [];
-    let task = this;
-    while (task){
-        if (task.context)
-            contexts.unshift(task.context); // Add to front so ancestors come first
-        task = task.parent;
-    }
-    return contexts;
-};
-
-// Find the nearest context in the hierarchy (this task or ancestors)
-Itask.prototype.findContext = function findContext(){
-    let task = this;
-    while (task){
-        if (task.context)
-            return task.context;
-        task = task.parent;
-    }
-    return null;
-};
-
-// 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){
-        // Walk up to find a context
-        ctx = this.findContext();
-    }
-    if (!ctx){
-        throw new Error('No context available in task hierarchy to send message');
-    }
-    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
-Itask.prototype.getHierarchyFunctions = function getHierarchyFunctions(){
-    const allFunctions = [];
-    const contexts = this.getAncestorContexts();
-    for (const ctx of contexts){
-        if (ctx.functions && Array.isArray(ctx.functions))
-            allFunctions.push(...ctx.functions);
-    }
-    // Add this task's own functions if not already in a context
-    if (this.functions && !this.context)
-        allFunctions.push(...this.functions);
-    return allFunctions;
-};
-
-// Close this task's context (if any) and bubble summary to parent
-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);
-
-    // 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();
-};
-
-// 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;
-
 /* ---------- export ---------- */
 module.exports = Itask;
 

package/msgs.js

@@ -92,18 +92,30 @@ class Context {
             this.tool_digest = this.tool_digest.slice(-this.TOOL_DIGEST_LIMIT);
     }
 
-    // Get the parent context by traversing task hierarchy
+    // Get the parent context by traversing task hierarchy (via Saico)
     getParentContext() {
         if (!this.task || !this.task.parent)
             return null;
-        return this.task.parent.findContext ? this.task.parent.findContext() : null;
+        let task = this.task.parent;
+        while (task) {
+            if (task._saico?.context) return task._saico.context;
+            task = task.parent;
+        }
+        return null;
     }
 
-    // Get all ancestor contexts via task hierarchy
+    // Get all ancestor contexts via task hierarchy (via Saico)
     getAncestorContexts() {
         if (!this.task)
             return [];
-        return this.task.getAncestorContexts().filter(ctx => ctx !== this);
+        const contexts = [];
+        let task = this.task.parent;
+        while (task) {
+            if (task._saico?.context)
+                contexts.unshift(task._saico.context);
+            task = task.parent;
+        }
+        return contexts;
     }
 
     _hasPendingToolCalls() {
@@ -1145,7 +1157,7 @@ class Context {
     // Spawn child context (creates a child task with its own context)
     spawnChild(prompt, tag, config = {}) {
         if (!this.task) {
-            // If no task, create a standalone context (legacy mode)
+            // If no task, create a standalone context
             return createContext(prompt, null, { ...config, tag });
         }
 
@@ -1153,14 +1165,16 @@ class Context {
         const Itask = require('./itask.js');
         const childTask = new Itask({
             name: tag || 'child-context',
-            prompt,
             async: true,
-            spawn_parent: this.task,
-            contextConfig: config
         }, []);
+        this.task.spawn(childTask);
 
         const childContext = new Context(prompt, childTask, { ...config, tag });
-        childTask.setContext(childContext);
+        // Store context on Saico if present, otherwise just set on task reference
+        if (childTask._saico) {
+            childTask._saico.context = childContext;
+            childTask._saico.context_id = childContext.tag;
+        }
 
         return childContext;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",
@@ -15,7 +15,6 @@
   "files": [
     "index.js",
     "itask.js",
-    "context.js",
     "msgs.js",
     "saico.js",
     "dynamo.js",

package/saico.js

@@ -4,6 +4,11 @@ const crypto = require('crypto');
 const Itask = require('./itask.js');
 const { Context } = require('./msgs.js');
 const { Store } = require('./store.js');
+const util = require('./util.js');
+
+function makeId(len = 12){
+    return crypto.randomBytes(Math.ceil(len/2)).toString('hex').slice(0, len);
+}
 
 /**
  * Saico — Master class for building AI-powered services.
@@ -32,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
@@ -47,10 +53,15 @@ class Saico {
         this._opt = opt;
         this._isolate = opt.isolate || false;
 
+        // Context owned directly by Saico (not Itask)
+        this.context = null;
+        this.context_id = null;
+
         // Public configuration
         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 || {};
@@ -90,11 +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 {Itask} [opts.parent] - Parent task to spawn under
+     * @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
@@ -111,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');
@@ -120,21 +130,17 @@ class Saico {
             name: this.name,
             id: opts.taskId,
             async: true,
-            store: this._store,
-            functions: opts.functions || this.functions,
             bind: this, // State functions run with Saico instance as `this`
         };
 
-        if (opts.parent)
-            taskOpt.spawn_parent = opts.parent;
-
         this._task = new Itask(taskOpt, states);
 
         // 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,
                 token_limit: opts.token_limit ?? this.sessionConfig.token_limit,
@@ -142,7 +148,7 @@ 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,
-                functions: taskOpt.functions,
+                functions,
                 sequential_mode: opts.sequential_mode,
                 msgs: opts.msgs,
                 chat_history: opts.chat_history,
@@ -150,15 +156,118 @@ class Saico {
             };
 
             const augmentedPrompt = effectivePrompt
-                ? effectivePrompt + Itask.BACKEND_EXPLANATION
+                ? effectivePrompt + Saico.BACKEND_EXPLANATION
                 : '';
             const context = new Context(augmentedPrompt, this._task, contextConfig);
-            this._task.setContext(context);
+            this.setContext(context);
         }
 
         return this;
     }
 
+    // ---- Context management (owned by Saico, not Itask) ----
+
+    /**
+     * Set context on this Saico instance.
+     * Generates context_id, sets context.tag, and calls context.setTask().
+     */
+    setContext(context) {
+        this.context = context;
+        // 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._task);
+        }
+        return this;
+    }
+
+    /**
+     * Find the nearest context walking UP the Saico/task hierarchy.
+     */
+    findContext() {
+        if (this.context) return this.context;
+        let task = this._task?.parent;
+        while (task) {
+            if (task._saico?.context) return task._saico.context;
+            task = task.parent;
+        }
+        return null;
+    }
+
+    /**
+     * Walk DOWN to find the deepest active descendant with a context.
+     */
+    findDeepestContext() {
+        if (!this._task) return this.context || null;
+        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._saico?.context) {
+                    if (!deepest || depth + 1 >= deepest.depth)
+                        deepest = { context: child._saico.context, depth: depth + 1 };
+                }
+                search(child, depth + 1);
+            }
+        };
+        search(this._task, 0);
+        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,
@@ -166,12 +275,12 @@ class Saico {
      */
     async deactivate() {
         if (!this._task) return;
-        if (this._task.context) {
+        if (this.context) {
             // Find parent context to bubble cleaned messages
             let parentTask = this._task.parent;
             let parentCtx = null;
             while (parentTask) {
-                if (parentTask.context) { parentCtx = parentTask.context; break; }
+                if (parentTask._saico?.context) { parentCtx = parentTask._saico.context; break; }
                 parentTask = parentTask.parent;
             }
             if (parentCtx) {
@@ -180,16 +289,45 @@ class Saico {
                     parentCtx.push(msg);
             }
             // Clean tool calls and close context without additional summary bubbling.
-            // We already pushed cleaned messages above — closeContext's own
-            // summarization would double-bubble.
-            if (this._task.context_id && typeof this._task.context.cleanToolCallsByTag === 'function')
-                this._task.context.cleanToolCallsByTag(this._task.context_id);
-            this._task.context = null;
+            if (this.context_id && typeof this.context.cleanToolCallsByTag === 'function')
+                this.context.cleanToolCallsByTag(this.context_id);
+            this.context = null;
+            this.context_id = null;
         }
         this._task._ecancel();
         this._task = null;
     }
 
+    // ---- Spawn ----
+
+    /**
+     * Spawn a child Saico under this Saico's task hierarchy.
+     * Both parent and child must be activated.
+     * @param {Saico} child - An activated Saico instance
+     * @returns {Saico} the child (for chaining)
+     */
+    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.');
+        this._task.spawn(child._task);
+        return child;
+    }
+
+    /**
+     * Spawn a child Saico and start its task running.
+     * @param {Saico} child - An activated Saico instance
+     * @returns {Saico} the child (for chaining)
+     */
+    spawnAndRun(child) {
+        this.spawn(child);
+        process.nextTick(() => {
+            try { child._task._run(); } catch (e) { console.error(e); }
+        });
+        return child;
+    }
+
     // ---- Saico parent chain traversal ----
 
     /**
@@ -260,19 +398,19 @@ class Saico {
             throw new Error('Not activated. Call activate() first.');
 
         // Find the active context (own or walk up)
-        let ctx = this._task.getContext() || this._task.findContext();
+        let ctx = this.findContext();
         if (!ctx)
             throw new Error('No context available');
 
         // Build preamble by walking Saico chain
-        const activeCtx = this._task.findDeepestContext() || ctx;
+        const activeCtx = this.findDeepestContext() || ctx;
         const { preamble, allFunctions } = this._buildPreamble(activeCtx);
 
         // Merge with call-specific functions
         if (functions) allFunctions.push(...(Array.isArray(functions) ? functions : [functions]));
 
         opts = Object.assign({}, opts, {
-            tag: this._task.context_id,
+            tag: this.context_id,
             _preamble: preamble,
             _aggregatedFunctions: allFunctions.length > 0 ? allFunctions : null,
         });
@@ -284,7 +422,7 @@ class Saico {
             throw new Error('Not activated. Call activate() first.');
 
         // Route DOWN to deepest descendant with a msg Q
-        const ctx = this._task.findDeepestContext();
+        const ctx = this.findDeepestContext();
         if (!ctx)
             throw new Error('No context available');
 
@@ -302,63 +440,8 @@ class Saico {
     // ---- Task delegation ----
 
     get task() { return this._task; }
-    get context() { return this._task?.context || null; }
-    get context_id() { return this._task?.context_id || null; }
     get isActive() { return !!this._task && !this._task._completed; }
 
-    spawnTaskWithContext(opt, states) {
-        if (!this._task)
-            throw new Error('Not activated. Call activate() first.');
-        if (typeof opt === 'string')
-            opt = { name: opt };
-
-        const childTask = new Itask({
-            ...opt,
-            spawn_parent: this._task,
-            store: this._store,
-            async: true,
-        }, states || []);
-
-        if (opt.prompt) {
-            const childContext = new Context(opt.prompt, childTask, {
-                tag: opt.tag || childTask.id,
-                token_limit: opt.token_limit ?? this.sessionConfig.token_limit,
-                max_depth: opt.max_depth ?? this.sessionConfig.max_depth,
-                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,
-                functions: opt.functions || this.functions,
-            });
-            childTask.setContext(childContext);
-        }
-
-        process.nextTick(() => {
-            try { childTask._run(); } catch (e) { console.error(e); }
-        });
-
-        return childTask;
-    }
-
-    spawnTask(opt, states) {
-        if (!this._task)
-            throw new Error('Not activated. Call activate() first.');
-        if (typeof opt === 'string')
-            opt = { name: opt };
-
-        const childTask = new Itask({
-            ...opt,
-            spawn_parent: this._task,
-            store: this._store,
-            async: true,
-        }, states || []);
-
-        process.nextTick(() => {
-            try { childTask._run(); } catch (e) { console.error(e); }
-        });
-
-        return childTask;
-    }
-
     // ---- State Summary ----
 
     /**
@@ -437,8 +520,8 @@ class Saico {
 
     async closeSession() {
         if (!this._task) return;
-        if (this._task.context)
-            await this._task.context.close();
+        if (this.context)
+            await this.context.close();
         this._task._ecancel();
     }
 
@@ -555,13 +638,13 @@ class Saico {
         if (this._task) {
             data.task = {
                 id: this._task.id,
-                context_id: this._task.context_id,
-                context: this._task.context ? {
-                    tag: this._task.context.tag,
-                    msgs: this._task.context._msgs,
-                    functions: this._task.context.functions,
-                    chat_history: this._task.context.chat_history,
-                    tool_digest: this._task.context.tool_digest,
+                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,
             };
         }
@@ -604,13 +687,13 @@ class Saico {
             });
 
             // Restore messages to context
-            if (parsed.task.context?.msgs && instance._task.context) {
-                instance._task.context._msgs = parsed.task.context.msgs;
+            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._task.context) {
-                instance._task.context.tool_digest = parsed.task.context.tool_digest;
+            if (Array.isArray(parsed.task.context?.tool_digest) && instance.context) {
+                instance.context.tool_digest = parsed.task.context.tool_digest;
             }
         }
 
@@ -618,4 +701,9 @@ class Saico {
     }
 }
 
+// [BACKEND] explanation text appended to context prompts
+Saico.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.';
+
 module.exports = { Saico };

package/context.js

@@ -1,5 +0,0 @@
-// context.js — backward compatibility shim
-// The Context class has moved to msgs.js. This file re-exports for compatibility.
-'use strict';
-const { Context, createContext } = require('./msgs.js');
-module.exports = { Context, createContext };