saico 2.5.0 → 2.6.0

package/README.md

@@ -69,7 +69,7 @@ Saico separates construction from activation:
 const agent = new Saico({
     name: 'agent',
     prompt: 'System prompt here',
-    dynamodb_table: 'my_data',  // optional DB
+    dynamodb: { region: 'us-east-1', credentials: { accessKeyId: 'AK', secretAccessKey: 'SK' } },
 });
 
 // DB methods work before activation
@@ -189,8 +189,10 @@ new Saico({
     // Storage
     redis: true,               // Set false to skip Redis proxy
     key: 'custom-redis-key',
-    dynamodb_table: 'table',   // Auto-creates DynamoDB adapter
-    dynamodb_region: 'us-east-1',
+    dynamodb: {                // DynamoDB config (creates adapter)
+        region: 'us-east-1',
+        credentials: { accessKeyId: '...', secretAccessKey: '...' },
+    },
     db: customAdapter,         // Any adapter with put/get/delete/query interface
 
     // User data
@@ -240,26 +242,26 @@ await agent.closeSession();  // Close context and cancel task
 
 ## Database Access
 
-Saico provides backend-agnostic DB methods. Configure via `dynamodb_table` (auto-creates DynamoDB adapter) or `db` (any adapter implementing the interface).
+Saico provides backend-agnostic DB methods. Configure via `opt.dynamodb` (auto-creates DynamoDB 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()`.
 
 ```js
-// CRUD
-await agent.dbPutItem({ id: '123', name: 'test' });
-const item = await agent.dbGetItem('id', '123');
-await agent.dbDeleteItem('id', '123');
-const items = await agent.dbQuery('email-index', 'email', 'user@test.com');
-const all = await agent.dbGetAll();
+// CRUD — table name required on every call
+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');
-await agent.dbUpdatePath('id', '123', [{ key: 'nested' }], 'field', 'value');
-await agent.dbListAppend('id', '123', 'tags', 'new-tag');
+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');
 
 // Counters
-const nextId = await agent.dbNextCounterId('OrderId');
-const count = await agent.dbGetCounterValue('OrderId');
-await agent.dbSetCounterValue('OrderId', 100);
-const total = await agent.dbCountItems();
+const nextId = await agent.dbNextCounterId('OrderId', 'counters');
+const count = await agent.dbGetCounterValue('OrderId', 'counters');
+await agent.dbSetCounterValue('OrderId', 100, 'counters');
+const total = await agent.dbCountItems('my-table');
 ```
 
 Override `_deserializeRecord(raw)` to transform raw DB records on retrieval (e.g., restore class instances):

package/dynamo.js

@@ -3,9 +3,8 @@
 /**
  * DynamoDBAdapter — Generic DynamoDB access layer.
  *
- * Generalized from ../backend/aws.js. Provides CRUD, update, list-append,
- * counter, and scan operations. All methods accept an optional `table`
- * parameter that defaults to `this.defaultTable`.
+ * Provides CRUD, update, list-append, counter, and scan operations.
+ * Table name is required on every call.
  *
  * AWS SDK v3 packages are required only when this module is loaded.
  */
@@ -18,14 +17,16 @@ const { unmarshall, marshall } = require('@aws-sdk/util-dynamodb');
 class DynamoDBAdapter {
     /**
      * @param {Object} opt
-     * @param {string} opt.table - Default table name for all operations
      * @param {string} [opt.region='us-east-1'] - AWS region
+     * @param {Object} [opt.credentials] - AWS credentials { accessKeyId, secretAccessKey }
      * @param {DynamoDBClient} [opt.client] - Injectable DynamoDB client (for testing)
      */
     constructor(opt = {}) {
-        this.defaultTable = opt.table || null;
         this._region = opt.region || 'us-east-1';
-        this._client = opt.client || new DynamoDBClient({ region: this._region });
+        this._client = opt.client || new DynamoDBClient({
+            region: this._region,
+            ...(opt.credentials && { credentials: opt.credentials }),
+        });
         this.__docClient = null;
     }
 
@@ -36,9 +37,8 @@ class DynamoDBAdapter {
     }
 
     _table(table) {
-        const t = table || this.defaultTable;
-        if (!t) throw new Error('DynamoDBAdapter: no table specified');
-        return t;
+        if (!table) throw new Error('DynamoDBAdapter: table name required');
+        return table;
     }
 
     _unmarshall(item) {

package/package.json

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

package/saico.js

@@ -33,9 +33,7 @@ class Saico {
      * @param {string} [opt.key] - Redis key override (default: 'saico:<id>')
      * @param {boolean} [opt.redis=true] - Set false to skip Redis proxy
      * @param {boolean} [opt.isolate] - Isolate: don't aggregate from ancestors
-     * @param {string} [opt.dynamodb_table] - DynamoDB table name (enables db accessor)
-     * @param {string} [opt.dynamodb_region] - AWS region for DynamoDB
-     * @param {Object} [opt.dynamodb_client] - Injectable DynamoDB client (for testing)
+     * @param {Object} [opt.dynamodb] - DynamoDB config { region, credentials: { accessKeyId, secretAccessKey }, client }
      * @param {Object} [opt.db] - Pluggable DB backend
      * @param {Object} [opt.store] - Store instance override
      * @param {Object} [opt.userData] - Initial user data
@@ -68,12 +66,12 @@ class Saico {
 
         // DB backend — pluggable storage adapter.
         this._db = opt.db || null;
-        if (!this._db && opt.dynamodb_table) {
+        if (!this._db && opt.dynamodb) {
             const { DynamoDBAdapter } = require('./dynamo.js');
             this._db = new DynamoDBAdapter({
-                table: opt.dynamodb_table,
-                region: opt.dynamodb_region,
-                client: opt.dynamodb_client,
+                region: opt.dynamodb.region,
+                credentials: opt.dynamodb.credentials,
+                client: opt.dynamodb.client,
             });
         }
 
@@ -446,76 +444,90 @@ class Saico {
 
     // ---- Generic DB access ----
 
+    /**
+     * Find a DB backend — own _db first, then walk UP the parent Saico chain.
+     * Throws if no backend found anywhere.
+     */
+    _getDb() {
+        if (this._db) return this._db;
+        let task = this._task?.parent;
+        while (task) {
+            if (task._saico?._db) return task._saico._db;
+            task = task.parent;
+        }
+        throw new Error('No DB backend configured. Set opt.dynamodb or opt.db on this Saico or an ancestor.');
+    }
+
     async dbPutItem(item, table) {
-        if (!this._db) return;
-        return this._db.put(item, table);
+        const db = this._getDb();
+        return db.put(item, table);
     }
 
     async dbGetItem(key, value, table) {
-        if (!this._db) return;
-        const result = await this._db.get(key, value, table);
+        const db = this._getDb();
+        const result = await db.get(key, value, table);
         return result ? this._deserializeRecord(result) : result;
     }
 
     async dbDeleteItem(key, value, table) {
-        if (!this._db) return;
-        return this._db.delete(key, value, table);
+        const db = this._getDb();
+        return db.delete(key, value, table);
     }
 
     async dbQuery(index, key, value, table) {
-        if (!this._db) return;
-        const results = await this._db.query(index, key, value, table);
+        const db = this._getDb();
+        const results = await db.query(index, key, value, table);
         return Array.isArray(results)
             ? results.map(r => this._deserializeRecord(r))
             : results;
     }
 
     async dbGetAll(table) {
-        if (!this._db) return;
-        const results = await this._db.getAll(table);
+        const db = this._getDb();
+        const results = await db.getAll(table);
         return Array.isArray(results)
             ? results.map(r => this._deserializeRecord(r))
             : results;
     }
 
     async dbUpdate(key, keyValue, setKey, item, table) {
-        if (!this._db) return;
-        return this._db.update(key, keyValue, setKey, item, table);
+        const db = this._getDb();
+        return db.update(key, keyValue, setKey, item, table);
     }
 
     async dbUpdatePath(key, keyValue, path, setKey, item, table) {
-        if (!this._db) return;
-        return this._db.updatePath(key, keyValue, path, setKey, item, table);
+        const db = this._getDb();
+        return db.updatePath(key, keyValue, path, setKey, item, table);
     }
 
     async dbListAppend(key, keyValue, setKey, item, table) {
-        if (!this._db) return;
-        return this._db.listAppend(key, keyValue, setKey, item, table);
+        const db = this._getDb();
+        return db.listAppend(key, keyValue, setKey, item, table);
     }
 
     async dbListAppendPath(key, keyValue, path, setKey, item, table) {
-        if (!this._db) return;
-        return this._db.listAppendPath(key, keyValue, path, setKey, item, table);
+        const db = this._getDb();
+        return db.listAppendPath(key, keyValue, path, setKey, item, table);
     }
 
     async dbNextCounterId(counter, table) {
-        if (!this._db) return;
-        return this._db.nextCounterId(counter, table);
+        const db = this._getDb();
+        return db.nextCounterId(counter, table);
     }
 
     async dbGetCounterValue(counter, table) {
-        if (!this._db) return;
-        return this._db.getCounterValue(counter, table);
+        const db = this._getDb();
+        return db.getCounterValue(counter, table);
     }
 
     async dbSetCounterValue(counter, value, table) {
-        if (!this._db) return;
-        return this._db.setCounterValue(counter, value, table);
+        const db = this._getDb();
+        return db.setCounterValue(counter, value, table);
     }
 
     async dbCountItems(table) {
-        if (!this._db) return;
-        return this._db.countItems(table);
+        const db = this._getDb();
+        return db.countItems(table);
     }
 
     // ---- DB deserialization hook ----