onbuzz 4.8.2 → 4.9.0

package/src/tools/fileTreeTool.js

@@ -484,6 +484,13 @@ LIMITATIONS:
    * @returns {Promise<Object>} Execution result
    */
   async execute(params, context) {
+    // Reverse-forgiveness: accept plural {actions:[{...}]} envelope
+    // (cross-tool envelope unification).
+    if (Array.isArray(params?.actions) && params.actions.length > 0) {
+      const a = params.actions[0] || {};
+      params = { ...params, ...a };
+    }
+
     // Extract params with defaults
     const {
       directory = '.',

package/src/tools/memoryTool.js

@@ -99,12 +99,25 @@ After add/update of a plan/* memory, the tool DOES NOT echo the content back
 in the result — it would duplicate the header injection. You'll see the plan
 in your system prompt on the next turn instead.
 
-USAGE:
+USAGE (canonical plural — same shape across all tools):
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "<action>",
-  "parameters": { ... }
+  "actions": [
+    {"type": "read", "id": "mem-123-abc"}
+  ]
+}
+\`\`\`
+
+BATCH multiple memory operations in one call:
+\`\`\`json
+{
+  "toolId": "memory",
+  "actions": [
+    {"type": "read", "id": "mem-auth-plan"},
+    {"type": "read", "id": "mem-retry-policy"},
+    {"type": "append", "id": "mem-auth-plan", "content": "Step 4 added: revoke v1 tokens"}
+  ]
 }
 \`\`\`
 
@@ -114,11 +127,13 @@ ACTIONS:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "add",
-  "title": "User prefers TypeScript",
-  "description": "Programming language preference",
-  "content": "The user explicitly stated they prefer TypeScript over JavaScript.",
-  "expiration": null
+  "actions": [{
+    "type": "add",
+    "title": "User prefers TypeScript",
+    "description": "Programming language preference",
+    "content": "The user explicitly stated they prefer TypeScript over JavaScript.",
+    "expiration": null
+  }]
 }
 \`\`\`
 
@@ -131,12 +146,14 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "update",
-  "id": "mem-123-abc",
-  "title": "Updated title",
-  "description": "Updated description",
-  "content": "Updated content",
-  "expiration": "2025-12-31"
+  "actions": [{
+    "type": "update",
+    "id": "mem-123-abc",
+    "title": "Updated title",
+    "description": "Updated description",
+    "content": "Updated content",
+    "expiration": "2025-12-31"
+  }]
 }
 \`\`\`
 
@@ -144,8 +161,7 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "delete",
-  "id": "mem-123-abc"
+  "actions": [{"type": "delete", "id": "mem-123-abc"}]
 }
 \`\`\`
 
@@ -153,8 +169,7 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "list",
-  "level": "titles"
+  "actions": [{"type": "list", "level": "titles"}]
 }
 \`\`\`
 
@@ -167,8 +182,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "read",
-  "id": "mem-123-abc"
+  "actions": [{"type": "read", "id": "mem-123-abc"}]
 }
 \`\`\`
 
@@ -176,8 +190,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "search",
-  "query": "TypeScript"
+  "actions": [{"type": "search", "query": "TypeScript"}]
 }
 \`\`\`
 
@@ -185,7 +198,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "stats"
+  "actions": [{"type": "stats"}]
 }
 \`\`\`
 
@@ -389,47 +402,62 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
+    const validActions = ['add', 'update', 'append', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
 
-    if (!params.action) {
-      errors.push('action is required');
-    } else if (!validActions.includes(params.action)) {
-      errors.push(`action must be one of: ${validActions.join(', ')}`);
+    // Normalize to the canonical actions[] shape and validate every action.
+    // Accepts both the canonical plural `{actions: [{type, ...}]}` and the
+    // legacy singular `{action: "X", ...}` shapes — the executor's
+    // _normalizeToActions handles the runtime promotion identically.
+    const actions = this._normalizeToActions(params);
+
+    if (actions.length === 0) {
+      errors.push('action is required (or `actions: [...]` for batched calls)');
     } else {
-      // Validate action-specific requirements
-      switch (params.action) {
-        case 'add':
-          if (!params.title) errors.push('title is required for add action');
-          if (!params.content) errors.push('content is required for add action');
-          break;
-        case 'update':
-          if (!params.id) errors.push('id is required for update action');
-          break;
-        case 'delete':
-          if (!params.id) errors.push('id is required for delete action');
-          break;
-        case 'read':
-          if (!params.id) errors.push('id is required for read action');
-          break;
-        case 'search':
-          if (!params.query) errors.push('query is required for search action');
-          break;
+      for (let i = 0; i < actions.length; i++) {
+        const a = actions[i];
+        const tag = actions.length > 1 ? `actions[${i}]: ` : '';
+        if (!a || typeof a !== 'object') {
+          errors.push(`${tag}must be an object with a "type" field`);
+          continue;
+        }
+        const t = a.type;
+        if (!t) {
+          errors.push(`${tag}"type" is required`);
+          continue;
+        }
+        if (!validActions.includes(t)) {
+          errors.push(`${tag}type must be one of: ${validActions.join(', ')}`);
+          continue;
+        }
+        switch (t) {
+          case 'add':
+            if (!a.title)   errors.push(`${tag}title is required for add`);
+            if (!a.content) errors.push(`${tag}content is required for add`);
+            break;
+          case 'update':
+            if (!a.id) errors.push(`${tag}id is required for update`);
+            break;
+          case 'append':
+            if (!a.id)      errors.push(`${tag}id is required for append`);
+            if (!a.content) errors.push(`${tag}content is required for append`);
+            break;
+          case 'delete':
+            if (!a.id) errors.push(`${tag}id is required for delete`);
+            break;
+          case 'read':
+            if (!a.id) errors.push(`${tag}id is required for read`);
+            break;
+          case 'search':
+            if (!a.query) errors.push(`${tag}query is required for search`);
+            break;
+        }
+        // Length limits (per-action).
+        if (a.title    && a.title.length    > 200)   errors.push(`${tag}title cannot exceed 200 characters`);
+        if (a.description && a.description.length > 500) errors.push(`${tag}description cannot exceed 500 characters`);
+        if (a.content  && a.content.length  > 10000) errors.push(`${tag}content cannot exceed 10000 characters`);
       }
     }
 
-    // Length limits
-    if (params.title && params.title.length > 200) {
-      errors.push('title cannot exceed 200 characters');
-    }
-
-    if (params.description && params.description.length > 500) {
-      errors.push('description cannot exceed 500 characters');
-    }
-
-    if (params.content && params.content.length > 10000) {
-      errors.push('content cannot exceed 10000 characters');
-    }
-
     return {
       valid: errors.length === 0,
       errors
@@ -443,7 +471,6 @@ BEST PRACTICES:
    * @returns {Promise<Object>}
    */
   async execute(params, context) {
-    const { action } = params;
     const { agentId } = context;
 
     if (!agentId) {
@@ -452,32 +479,103 @@ BEST PRACTICES:
 
     const memoryService = await this._ensureMemoryService();
 
+    // PLURAL-CANONICAL DISPATCH — the canonical shape is
+    // `{actions: [{type: "read", id: "X"}, ...]}` matching the rest
+    // of the tool conventions (filesystem, terminal, taskmanager).
+    // Singular `{action: "read", id: "X"}` is auto-promoted as
+    // backward-compat for the agent's training-prior emissions.
+    // See commit 5e6b817 + the "tool envelope unification" thread.
+    const actions = this._normalizeToActions(params);
+
+    if (actions.length === 0) {
+      throw new Error('memory tool requires either `action` (singular) or `actions` (plural array). Each action needs a `type` (or `action`) field.');
+    }
+
+    // Single-action path → return one result directly (no array wrap)
+    // for backward-compat with every existing caller / test that
+    // expects the shape from the singular dispatch.
+    if (actions.length === 1) {
+      return await this._dispatchSingleAction(memoryService, agentId, actions[0], context);
+    }
+
+    // Multi-action path → execute sequentially, return array of results.
+    // Errors on one action don't abort the others — each result
+    // carries its own success/error state.
+    const results = [];
+    for (const a of actions) {
+      try {
+        const r = await this._dispatchSingleAction(memoryService, agentId, a, context);
+        results.push(r);
+      } catch (err) {
+        results.push({ success: false, action: a.type || a.action, error: err.message });
+      }
+    }
+    return {
+      success: results.every(r => r.success !== false),
+      batched: true,
+      actionCount: results.length,
+      results,
+    };
+  }
+
+  /**
+   * Promote a tool-call's params into a canonical actions[] array.
+   * Accepts:
+   *   { actions: [{type, ...}] }            (canonical plural)
+   *   { actions: [{action, ...}] }           (plural with `action` instead of `type`)
+   *   { action: "read", id: "X" }            (legacy singular at top level)
+   *   { action: "read", parameters: {...} }  (legacy singular with nested params)
+   * @private
+   */
+  _normalizeToActions(params) {
+    if (!params || typeof params !== 'object') return [];
+    if (Array.isArray(params.actions)) {
+      // Normalize each item: ensure `type` is set (rename `action`→`type`).
+      return params.actions.map(a => {
+        if (!a || typeof a !== 'object') return a;
+        if (!a.type && a.action) {
+          const { action, ...rest } = a;
+          return { type: action, ...rest };
+        }
+        return a;
+      });
+    }
+    if (params.action) {
+      const { action, parameters, ...rest } = params;
+      // Merge nested `parameters` (some callers wrap fields inside).
+      return [{ type: action, ...(parameters && typeof parameters === 'object' ? parameters : {}), ...rest }];
+    }
+    return [];
+  }
+
+  /**
+   * Dispatch a single normalized action {type, ...fields}.
+   * The downstream _executeX methods expect the legacy params shape
+   * (flat with `action: "X"`), so we adapt before calling.
+   * @private
+   */
+  async _dispatchSingleAction(memoryService, agentId, action, context) {
+    const { type, ...rest } = action;
+    const legacyParams = { action: type, ...rest };
     try {
-      switch (action) {
-        case 'add':
-          return await this._executeAdd(memoryService, agentId, params);
-        case 'update':
-          return await this._executeUpdate(memoryService, agentId, params);
-        case 'delete':
-          return await this._executeDelete(memoryService, agentId, params);
-        case 'list':
-          return await this._executeList(memoryService, agentId, params);
-        case 'read':
-          return await this._executeRead(memoryService, agentId, params);
-        case 'search':
-          return await this._executeSearch(memoryService, agentId, params);
-        case 'stats':
-          return await this._executeStats(memoryService, agentId);
-        case 'reminisce':
-          return await this._executeReminisce(agentId, params, context);
+      switch (type) {
+        case 'add':       return await this._executeAdd(memoryService, agentId, legacyParams);
+        case 'update':    return await this._executeUpdate(memoryService, agentId, legacyParams);
+        case 'append':    return await this._executeAppend(memoryService, agentId, legacyParams);
+        case 'delete':    return await this._executeDelete(memoryService, agentId, legacyParams);
+        case 'list':      return await this._executeList(memoryService, agentId, legacyParams);
+        case 'read':      return await this._executeRead(memoryService, agentId, legacyParams);
+        case 'search':    return await this._executeSearch(memoryService, agentId, legacyParams);
+        case 'stats':     return await this._executeStats(memoryService, agentId);
+        case 'reminisce': return await this._executeReminisce(agentId, legacyParams, context);
         default:
-          throw new Error(`Unknown action: ${action}`);
+          throw new Error(`Unknown memory action: ${type}`);
       }
     } catch (error) {
-      this.logger?.error(`Memory tool execution failed: ${error.message}`, {
+      this.logger?.error(`Memory tool action failed: ${error.message}`, {
         agentId,
-        action,
-        error: error.stack
+        type,
+        error: error.stack,
       });
       throw error;
     }
@@ -546,6 +644,44 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute APPEND action — additive update with a timestamped block.
+   *
+   * Designed for the "memory grows as the agent learns" use case:
+   * agent attaches a memory to a task on creation, then appends
+   * findings/methodology as work progresses. Each append becomes a
+   * dated section so the memory reads like a journal.
+   *
+   * Soft-cap behavior: once total content exceeds ~16K chars, the
+   * service compresses older blocks into a summary on subsequent
+   * appends. See memoryService.appendToMemory.
+   */
+  async _executeAppend(memoryService, agentId, params) {
+    const memory = await memoryService.appendToMemory(agentId, params.id, params.content);
+
+    if (!memory) {
+      return {
+        success: false,
+        action: 'append',
+        message: `Memory not found: ${params.id}`
+      };
+    }
+
+    return {
+      success: true,
+      action: 'append',
+      memory: {
+        id: memory.id,
+        title: memory.title,
+        updatedAt: memory.updatedAt,
+        contentLength: memory.content?.length || 0,
+      },
+      message: isPlanTitle(memory.title)
+        ? `Plan updated (append): "${memory.title}" — full content appears in AGENT WORKING PLAN next turn.`
+        : `Appended to memory: "${memory.title}" (now ${memory.content?.length || 0} chars)`
+    };
+  }
+
   /**
    * Execute DELETE action
    */