saico 2.9.0 → 2.9.2

package/README.md

@@ -1,4 +1,4 @@
-# Saico - Hierarchical AI Conversation Orchestrator
+# Saico - Simple AI-Agent Conversation Orchestrator
 
 Saico is a Node.js library for building AI agents with hierarchical conversations, automatic context aggregation, and enterprise-grade tool calling. It manages nested task trees where each node can have its own message queue, system prompt, tools, and state — and the library automatically assembles the full payload sent to the LLM by walking the tree.
 
@@ -210,7 +210,7 @@ new Saico({
     // Storage
     redis: true,               // Set false to skip Redis proxy
     key: 'custom-redis-key',
-    store: 'my-table',         // Table name for instance persistence (closeSession/rehydrate)
+    store: 'my-table',         // Table name for instance persistence (store/closeSession/restore)
     dynamodb: {                // DynamoDB config (creates instance-level adapter)
         region: 'us-east-1',
         credentials: { accessKeyId: '...', secretAccessKey: '...' },
@@ -258,28 +258,33 @@ agent.getSessionInfo();
 //   userData, uptime
 // }
 
-await agent.closeSession();  // prepareForStorage + save to registered backend, cancels task
+await agent.store();         // save to registered backend independently
+await agent.closeSession();  // store + cancel task
 
 // Restore from registered backend
-const restored = await Saico.rehydrate(agent.id, { store: 'sessions' });
+const restored = await Saico.restore(agent.id, { store: 'sessions' });
 ```
 
 ## Database Access
 
-Saico provides backend-agnostic DB methods. Configure via `Saico.registerBackend('dynamodb', config)` (library-level), `opt.dynamodb` (instance-level auto-creates adapter), or `opt.db` (any adapter). Table name is required on every call. Child Saico instances without their own DB inherit the parent's adapter automatically via `_getDb()`, which also falls back to the registered backend.
+Saico provides backend-agnostic DB methods. Configure via `Saico.registerBackend('dynamodb', config)` (library-level), `opt.dynamodb` (instance-level auto-creates adapter), or `opt.db` (any adapter). Key, key value, and table default to `'id'`, `this.id`, and `this._storeName` — so operating on own record is a one-liner. Child Saico instances inherit the parent's adapter via `_getDb()`, which also falls back to the registered backend.
 
 ```js
-// CRUD — table name required on every call
+// CRUD — shorthand (defaults: key='id', value=this.id, table=this._storeName)
+const me = await agent.dbGetItem();                   // get own record
+await agent.dbDeleteItem();                           // delete own record
+// Explicit
 await agent.dbPutItem({ id: '123', name: 'test' }, 'my-table');
 const item = await agent.dbGetItem('id', '123', 'my-table');
 await agent.dbDeleteItem('id', '123', 'my-table');
 const items = await agent.dbQuery('email-index', 'email', 'user@test.com', 'my-table');
 const all = await agent.dbGetAll('my-table');
 
-// Updates
-await agent.dbUpdate('id', '123', 'status', 'active', 'my-table');
-await agent.dbUpdatePath('id', '123', [{ key: 'nested' }], 'field', 'value', 'my-table');
-await agent.dbListAppend('id', '123', 'tags', 'new-tag', 'my-table');
+// Updates — setKey, item first; key, keyValue, table last (with defaults)
+await agent.dbUpdate('status', 'active');             // update own record
+await agent.dbUpdate('status', 'active', 'id', '123', 'my-table');
+await agent.dbUpdatePath([{ key: 'nested' }], 'field', 'value');
+await agent.dbListAppend('tags', 'new-tag');
 
 // Counters
 const nextId = await agent.dbNextCounterId('OrderId', 'counters');
@@ -312,8 +317,9 @@ const json = await agent.serialize();
 const restored = await Saico.deserialize(json);
 
 // Durable persistence (uses registered backend + opt.store table name)
-await agent.closeSession();
-const restored2 = await Saico.rehydrate(agent.id, { store: 'sessions' });
+await agent.store();         // save independently
+await agent.closeSession();  // store + cancel task
+const restored2 = await Saico.restore(agent.id, { store: 'sessions' });
 ```
 
 `prepareForStorage()` automatically picks up all non-underscore properties (id, name, prompt, userData, sessionConfig, tm_create, isolate, etc.) and produces compressed chat_history for the msgs Q.
@@ -405,7 +411,7 @@ saico/
 npm test
 ```
 
-300 tests covering Saico lifecycle, msgs Q ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, async serialization, prepareForStorage, backend registration, persistence (closeSession/rehydrate via registered backend), storage integration, and full hierarchy flows.
+300 tests covering Saico lifecycle, msgs Q ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, async serialization, prepareForStorage, backend registration, persistence (store/closeSession/restore via registered backend), storage integration, and full hierarchy flows.
 
 ## Requirements
 

package/package.json

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

package/saico.js

@@ -38,7 +38,8 @@ class Saico {
      * @param {boolean} [opt.redis=true] - Set false to skip Redis proxy
      * @param {boolean} [opt.createQ] - Create message Q 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.dynamodb] - DynamoDB config { region, credentials: { accessKeyId, secretAccessKey },
+     *   client }
      * @param {Object} [opt.db] - Pluggable DB backend
      * @param {string} [opt.store] - Table name for instance persistence
      * @param {Object} [opt.userData] - Initial user data
@@ -46,7 +47,8 @@ class Saico {
      */
     constructor(opt = {}) {
         // Internal properties (underscore-prefixed, not persisted to Redis)
-        this.id = opt.id || crypto.randomBytes(8).toString('hex');
+        this.name = opt.name || this.constructor.name || 'saico';
+        this.id = opt.id || this._genId();
         this._task = null;
         this._storeName = (typeof opt.store === 'string') ? opt.store : null;
         this._opt = opt;
@@ -57,7 +59,6 @@ class Saico {
         this.msgs_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;
@@ -501,19 +502,30 @@ class Saico {
     }
 
     /**
-     * Close the session — save state to registered backend, cancel task.
+     * Generate an id. Called by constructor when opt.id is not provided.
+     * Overridable by subclasses for custom ID schemes.
      */
-    async closeSession() {
-        if (!this._task) return;
+    _genId() {
+        return crypto.randomBytes(8).toString('hex');
+    }
 
-        if (this._storeName && this.msgs) {
-            const backend = Saico.getBackend();
-            if (backend) {
-                const data = await this.prepareForStorage();
-                await backend.put(data, this._storeName);
-            }
-        }
+    /**
+     * Save instance state to registered backend under _storeName.
+     */
+    async store() {
+        if (!this._storeName) return;
+        const backend = Saico.getBackend();
+        if (!backend) return;
+        const data = await this.prepareForStorage();
+        await backend.put(data, this._storeName);
+    }
 
+    /**
+     * Close the session — cancel task. Call store() first if persistence needed.
+     */
+    async closeSession() {
+        if (!this._task) return;
+        await this.store();
         this._task._ecancel();
     }
 
@@ -534,23 +546,23 @@ class Saico {
         throw new Error('No DB backend configured. Call Saico.registerBackend() or set opt.db.');
     }
 
-    async dbPutItem(item, table) {
+    async dbPutItem(item, table = this._storeName) {
         const db = this._getDb();
         return db.put(item, table);
     }
 
-    async dbGetItem(key, value, table) {
+    async dbGetItem(key = 'id', value = this.id, table = this._storeName) {
         const db = this._getDb();
         const result = await db.get(key, value, table);
         return result ? this._deserializeRecord(result) : result;
     }
 
-    async dbDeleteItem(key, value, table) {
+    async dbDeleteItem(key = 'id', value = this.id, table = this._storeName) {
         const db = this._getDb();
         return db.delete(key, value, table);
     }
 
-    async dbQuery(index, key, value, table) {
+    async dbQuery(index, key, value, table = this._storeName) {
         const db = this._getDb();
         const results = await db.query(index, key, value, table);
         return Array.isArray(results)
@@ -558,7 +570,7 @@ class Saico {
             : results;
     }
 
-    async dbGetAll(table) {
+    async dbGetAll(table = this._storeName) {
         const db = this._getDb();
         const results = await db.getAll(table);
         return Array.isArray(results)
@@ -566,42 +578,42 @@ class Saico {
             : results;
     }
 
-    async dbUpdate(key, keyValue, setKey, item, table) {
+    async dbUpdate(setKey, item, key = 'id', keyValue = this.id, table = this._storeName) {
         const db = this._getDb();
         return db.update(key, keyValue, setKey, item, table);
     }
 
-    async dbUpdatePath(key, keyValue, path, setKey, item, table) {
+    async dbUpdatePath(path, setKey, item, key = 'id', keyValue = this.id, table = this._storeName) {
         const db = this._getDb();
         return db.updatePath(key, keyValue, path, setKey, item, table);
     }
 
-    async dbListAppend(key, keyValue, setKey, item, table) {
+    async dbListAppend(setKey, item, key = 'id', keyValue = this.id, table = this._storeName) {
         const db = this._getDb();
         return db.listAppend(key, keyValue, setKey, item, table);
     }
 
-    async dbListAppendPath(key, keyValue, path, setKey, item, table) {
+    async dbListAppendPath(path, setKey, item, key = 'id', keyValue = this.id, table = this._storeName) {
         const db = this._getDb();
         return db.listAppendPath(key, keyValue, path, setKey, item, table);
     }
 
-    async dbNextCounterId(counter, table) {
+    async dbNextCounterId(counter, table = this._storeName) {
         const db = this._getDb();
         return db.nextCounterId(counter, table);
     }
 
-    async dbGetCounterValue(counter, table) {
+    async dbGetCounterValue(counter, table = this._storeName) {
         const db = this._getDb();
         return db.getCounterValue(counter, table);
     }
 
-    async dbSetCounterValue(counter, value, table) {
+    async dbSetCounterValue(counter, value, table = this._storeName) {
         const db = this._getDb();
         return db.setCounterValue(counter, value, table);
     }
 
-    async dbCountItems(table) {
+    async dbCountItems(table = this._storeName) {
         const db = this._getDb();
         return db.countItems(table);
     }
@@ -718,7 +730,7 @@ class Saico {
      * @param {Object} opt - Options (store: table name, backend, functions, states, etc.)
      * @returns {Promise<Saico|null>}
      */
-    static async rehydrate(id, opt = {}) {
+    static async restore(id, opt = {}) {
         const backend = opt.backend || Saico.getBackend();
         if (!backend)
             throw new Error('No backend registered. Call Saico.registerBackend() first.');