onbuzz 4.8.3 → 4.9.1

package/src/tools/platformControlTool.js

@@ -250,6 +250,11 @@ NOTES:
     if (!params || typeof params !== 'object') {
       return { success: false, error: 'params must be an object' };
     }
+    // Reverse-forgiveness: accept plural {actions:[{...}]} envelope.
+    if (Array.isArray(params?.actions) && params.actions.length > 0) {
+      const a = params.actions[0] || {};
+      params = { ...params, ...a, action: a.type || a.action || params.action };
+    }
     const action = params.action || 'list-capabilities';
     const callerAgentId = context?.agentId || null;
 

package/src/tools/seekTool.js

@@ -262,7 +262,42 @@ LIMITS:
    * @returns {Promise<Object>} Execution result
    */
   async execute(params, context) {
-    const { filePaths, searchTerms } = params;
+    // Forgiving normalization — production agents (gpt-5.4, Kimi-K2.6,
+    // gpt-4.1-mini) reliably call seek with the natural-feeling shape
+    // `{query, filePattern}` instead of the documented
+    // `{searchTerms: [], filePaths: []}`. Live trace evidence:
+    // agent-agent-v2-v2-s2-multi-topic-1779570320941 hit
+    // "Cannot read properties of undefined (reading 'length')" 3 times
+    // and cascaded into task drift. Accept both shapes — coerce
+    // singular strings to arrays, alternate names to canonical.
+    const filePathsRaw = params.filePaths != null ? params.filePaths
+      : params.filePath  != null ? params.filePath
+      : params.filePattern != null ? params.filePattern
+      : params.paths != null ? params.paths
+      : null;
+    const searchTermsRaw = params.searchTerms != null ? params.searchTerms
+      : params.searchTerm != null ? params.searchTerm
+      : params.query != null ? params.query
+      : params.terms != null ? params.terms
+      : null;
+    const filePaths = Array.isArray(filePathsRaw) ? filePathsRaw
+      : (filePathsRaw != null && filePathsRaw !== '') ? [filePathsRaw] : [];
+    const searchTerms = Array.isArray(searchTermsRaw) ? searchTermsRaw
+      : (searchTermsRaw != null && searchTermsRaw !== '') ? [searchTermsRaw] : [];
+
+    if (filePaths.length === 0) {
+      return {
+        success: false,
+        error: 'seek requires `filePaths` (array of glob patterns, e.g. ["src/**/*.js"]). Singular `filePath` or `filePattern` also accepted.',
+      };
+    }
+    if (searchTerms.length === 0) {
+      return {
+        success: false,
+        error: 'seek requires `searchTerms` (array of strings to find). Singular `searchTerm` or `query` also accepted.',
+      };
+    }
+
     const { projectDir, agentId, directoryAccess } = context;
 
     // IMPORTANT: Get all accessible directories for the agent

package/src/tools/skillsTool.js

@@ -22,6 +22,7 @@
 import { BaseTool } from './baseTool.js';
 import { getSkillsService } from '../services/skillsService.js';
 import { SKILLS_ACTIONS } from '../utilities/toolConstants.js';
+import { SkillsIndexer } from '../services/embeddings/indexers/skillsIndexer.js';
 
 class SkillsTool extends BaseTool {
   constructor(config = {}, logger = null) {
@@ -184,6 +185,16 @@ SKILL NAMING: Names must be kebab-case (lowercase, hyphens). Example: "code-revi
   }
 
   async execute(params, context = {}) {
+    // Reverse-forgiveness: this tool's canonical shape is singular
+    // {action, ...} (single-action-by-design — no batching value).
+    // Accept plural {actions:[{type/action, ...}]} too, in case the
+    // agent's pattern-match from filesystem/memory/etc. drifts here.
+    // See cross-tool envelope unification thread.
+    if (Array.isArray(params?.actions) && params.actions.length > 0) {
+      const a = params.actions[0] || {};
+      params = { ...params, ...a, action: a.type || a.action || params.action };
+    }
+
     const service = await this._ensureSkillsService();
     const { action } = params;
 
@@ -217,6 +228,12 @@ SKILL NAMING: Names must be kebab-case (lowercase, hyphens). Example: "code-revi
         case SKILLS_ACTIONS.IMPORT:
           return this._formatResult(await service.importSkill(params.source, params.name || null, params.description || null), `Skill imported: ${params.name || params.source}`);
 
+        case SKILLS_ACTIONS.SEARCH:
+          return await this._executeSearch(service, params);
+
+        case SKILLS_ACTIONS.BACKFILL_SEARCH_INDEX:
+          return await this._executeBackfillSearchIndex(service);
+
         default:
           return { success: false, error: `Unknown action: ${action}` };
       }
@@ -233,6 +250,122 @@ SKILL NAMING: Names must be kebab-case (lowercase, hyphens). Example: "code-revi
     };
   }
 
+  /**
+   * Lazy SkillsIndexer accessor — cached on the tool instance; null
+   * when no embedding service is attached.
+   * @private
+   */
+  _getSkillsIndexer() {
+    if (this._skillsIndexer) return this._skillsIndexer;
+    const svc = this.aiService?.getEmbeddingService?.();
+    if (!svc) return null;
+    this._skillsIndexer = new SkillsIndexer({ embeddingService: svc, logger: this.logger });
+    return this._skillsIndexer;
+  }
+
+  /**
+   * Search skills by meaning. Falls back to substring-on-name when
+   * embeddings are disabled, so the action is always callable.
+   *
+   * Params: { query, topK?=5, hybrid?=true }
+   * @private
+   */
+  async _executeSearch(service, params) {
+    const query = typeof params?.query === 'string' ? params.query.trim() : '';
+    if (!query) return { success: false, error: 'query is required for search' };
+    const topK = Number.isInteger(params.topK) && params.topK > 0 ? params.topK : 5;
+    const hybrid = params.hybrid !== false;
+
+    const indexer = this._getSkillsIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      // Substring fallback over the skill list (name + description).
+      const allSkills = await service.listSkills();
+      const lower = query.toLowerCase();
+      const matches = (allSkills || [])
+        .filter(s => (
+          (s.name || '').toLowerCase().includes(lower) ||
+          (s.description || '').toLowerCase().includes(lower)
+        ))
+        .slice(0, topK);
+      return {
+        success: true,
+        result: { mode: 'substring-fallback', query, hits: matches },
+        message: matches.length === 0
+          ? `Embeddings disabled; substring search found no matches for "${query}"`
+          : `Embeddings disabled; substring search found ${matches.length} skills`,
+      };
+    }
+
+    const { hits, error } = await indexer.search(query, { topK, hybrid });
+    return {
+      success: !error,
+      result: {
+        mode: hybrid ? 'hybrid' : 'semantic',
+        query,
+        hits,
+        ...(error ? { error } : {}),
+      },
+      message: error
+        ? `Skill search failed: ${error}`
+        : hits.length === 0
+          ? `No skills matched "${query}"`
+          : `Found ${hits.length} skills ranked by similarity to "${query}"`,
+    };
+  }
+
+  /**
+   * Drop the skills vector index and rebuild from `service.listSkills()`.
+   * Use after enabling embeddings or after a model swap. The full
+   * content of each skill is read via the service so the embedding
+   * captures more than just the name + description preview.
+   * @private
+   */
+  async _executeBackfillSearchIndex(service) {
+    const indexer = this._getSkillsIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        result: null,
+        message: 'Embeddings are not enabled — nothing to backfill. Enable a provider in Settings → Embeddings first.',
+      };
+    }
+
+    // listSkills returns name + description metadata. Hydrate each with
+    // its full content so the embedding gets a semantic fingerprint.
+    let allSkills;
+    try { allSkills = await service.listSkills(); }
+    catch (err) {
+      return { success: false, result: null, message: `listSkills failed: ${err?.message || err}` };
+    }
+    const hydrated = [];
+    for (const s of allSkills || []) {
+      if (!s?.name) continue;
+      try {
+        const full = await service.readSkill(s.name);
+        hydrated.push({ name: s.name, description: s.description || full?.description || '', content: full?.content || '' });
+      } catch (_err) {
+        // If a single skill fails to read, fall back to its bare metadata.
+        hydrated.push({ name: s.name, description: s.description || '' });
+      }
+    }
+
+    const r = await indexer.backfill(hydrated);
+    return {
+      success: r.ok !== false && !r.error,
+      result: {
+        indexed: r.indexed || 0,
+        skipped: r.skipped || 0,
+        failed: r.failed || 0,
+        ...(r.error ? { error: r.error } : {}),
+      },
+      message: r.ok === false
+        ? `Skills backfill failed: ${r.reason || r.error || 'unknown'}`
+        : `Indexed ${r.indexed || 0} skills` +
+          (r.skipped ? `, skipped ${r.skipped}` : '') +
+          (r.failed ? `, failed ${r.failed}` : '') + '.',
+    };
+  }
+
   getParameterSchema() {
     return {
       type: 'object',

package/src/tools/taskManagerTool.js

@@ -10,6 +10,7 @@
 import { BaseTool } from './baseTool.js';
 import { v4 as uuidv4 } from 'uuid';
 import { getMemoryService } from '../services/memoryService.js';
+import { TaskIndexer } from '../services/embeddings/indexers/taskIndexer.js';
 
 class TaskManagerTool extends BaseTool {
   constructor(config = {}) {
@@ -18,8 +19,8 @@ class TaskManagerTool extends BaseTool {
       description: config.description || 'Task management tool for organizing and tracking work',
       ...config
     });
-    
-    this.supportedActions = ['create', 'update', 'list', 'complete', 'cancel', 'clear', 'depend', 'relate', 'subtask', 'prioritize', 'template', 'progress', 'analytics', 'sync'];
+
+    this.supportedActions = ['create', 'update', 'list', 'complete', 'cancel', 'clear', 'depend', 'relate', 'subtask', 'prioritize', 'template', 'progress', 'analytics', 'sync', 'search', 'backfill-search-index'];
     this.taskStatuses = ['pending', 'in_progress', 'blocked', 'completed', 'cancelled'];
     this.taskPriorities = ['urgent', 'high', 'medium', 'low'];
     this.dependencyTypes = ['blocks', 'relates', 'subtask', 'parent'];
@@ -345,6 +346,57 @@ Always use a detailed task description to provide context for the task, and leve
     return description;
   }
 
+  /**
+   * Build the `currentFocus` signal emitted on every taskmanager
+   * response. Tells the agent which task it is CURRENTLY working on
+   * and warns about discipline violations (zero or multiple
+   * in-progress tasks).
+   *
+   * Three shapes:
+   *   { current: {taskId,title,description}, inProgressCount: 1, ok: true }
+   *   { current: null, inProgressCount: 0, ok: false,
+   *     warning: 'No task is in_progress…' }
+   *   { current: [...], inProgressCount: N>1, ok: false,
+   *     warning: 'Multiple tasks are in_progress…' }
+   *
+   * Production rationale: agents lose task focus after cascading tool
+   * errors and revert to earlier tasks. Surfacing the focus on every
+   * taskmanager turn keeps the anchor visible. See baseTool.js
+   * OPERATING POSTURE → TASK DISCIPLINE section.
+   *
+   * @private
+   */
+  _buildCurrentFocus(tasks) {
+    const inProgress = (tasks || []).filter(t => t.status === 'in_progress');
+    const shortDesc = (d) => {
+      if (typeof d !== 'string') return '';
+      const trimmed = d.trim();
+      return trimmed.length > 140 ? trimmed.slice(0, 140) + '…' : trimmed;
+    };
+    if (inProgress.length === 1) {
+      const t = inProgress[0];
+      return {
+        ok: true,
+        inProgressCount: 1,
+        current: { taskId: t.id, title: t.title, description: shortDesc(t.description) },
+      };
+    }
+    if (inProgress.length === 0) {
+      return {
+        ok: false,
+        inProgressCount: 0,
+        current: null,
+        warning: 'No task is in_progress. BEFORE doing any work, call `taskmanager` → `update` with status `in_progress` on the task you are about to work on. The transition IS the signal that you have started.',
+      };
+    }
+    return {
+      ok: false,
+      inProgressCount: inProgress.length,
+      current: inProgress.map(t => ({ taskId: t.id, title: t.title, description: shortDesc(t.description) })),
+      warning: `Multiple tasks are in_progress (${inProgress.length}). Pick ONE to remain in_progress; transition the others to \`blocked\` or \`completed\` so the task list reflects what you are actually doing right now.`,
+    };
+  }
+
   /**
    * Extract memory IDs from task descriptions
    * @private
@@ -436,12 +488,15 @@ Always use a detailed task description to provide context for the task, and leve
           firstAction = unwrappedAction;
         }
 
-        // Extract action type from 'type' field in the actions array
-        if (firstAction.type && !params.action) {
-          params.action = firstAction.type;
+        // Extract action type — accept both `type` (canonical) and
+        // `action` (used by jobdone/docx/excel/pdf). Cross-tool field-
+        // name unification.
+        const itemType = firstAction.type || firstAction.action;
+        if (itemType && !params.action) {
+          params.action = itemType;
           // Merge all other properties from the action object into params
           for (const [key, value] of Object.entries(firstAction)) {
-            if (key !== 'type' && !(key in params)) {
+            if (key !== 'type' && key !== 'action' && !(key in params)) {
               params[key] = value;
             }
           }
@@ -506,7 +561,7 @@ Always use a detailed task description to provide context for the task, and leve
           result = await this.createTask(agent, params, context);
           break;
         case 'update':
-          result = await this.updateTask(agent, params);
+          result = await this.updateTask(agent, params, context);
           break;
         case 'list':
           result = await this.listTasks(agent, params);
@@ -544,6 +599,12 @@ Always use a detailed task description to provide context for the task, and leve
         case 'sync':
           result = await this.syncTasks(agent, params, context);
           break;
+        case 'search':
+          result = await this.searchTasks(agent, params);
+          break;
+        case 'backfill-search-index':
+          result = await this.backfillTasksSearchIndex(agent);
+          break;
         default:
           throw new Error(`Unknown action: ${action}`);
       }
@@ -583,16 +644,22 @@ Always use a detailed task description to provide context for the task, and leve
       // so UI views (TaskPanel, TeamTaskBoard) can render the agent's current
       // state without fetching on every render. Previously only the `list`
       // action's inner result carried `tasks`, so every `create`/`update`/
-      // `complete`/`cancel`/`clear` call left the panel looking stale: the
-      // renderer's walk-back found the latest taskmanager call but found no
-      // tasks in its result and showed an empty panel. Emitting the full
-      // list on every action makes the most-recent-taskmanager-result
-      // contract always authoritative.
+      // `complete`/`cancel`/`clear` call left the panel looking stale.
+      //
+      // `currentFocus` is the task-discipline signal — see baseTool.js
+      // OPERATING POSTURE addition. It tells the agent which task it is
+      // CURRENTLY working on, warns when zero or multiple tasks are
+      // in_progress, and stays visible across every taskmanager turn so
+      // tool-error cascades don't shake the agent off its task. Production
+      // observation: Kimi-K2.6 + gpt-5.4 lost task focus mid-session after
+      // cascading tool failures and reverted to earlier tasks. Surfacing
+      // the focus on every response keeps the anchor visible.
       return {
         success: true,
         action,
         result,
         tasks: agent.taskList.tasks,
+        currentFocus: this._buildCurrentFocus(agent.taskList.tasks),
         summary: this.generateTaskSummary(agent.taskList) + noTasksHint
       };
 
@@ -858,7 +925,7 @@ Always use a detailed task description to provide context for the task, and leve
    * Update an existing task
    * @private
    */
-  async updateTask(agent, params) {
+  async updateTask(agent, params, context = {}) {
     const { taskId, status, priority, title, description } = params;
 
     if (!taskId) {
@@ -870,6 +937,8 @@ Always use a detailed task description to provide context for the task, and leve
       throw new Error(`Task not found: ${taskId}`);
     }
 
+    const prevStatus = task.status;
+
     if (status) {
       if (!this.taskStatuses.includes(status.toLowerCase())) {
         throw new Error(`Invalid status: ${status}. Must be: ${this.taskStatuses.join(', ')}`);
@@ -892,19 +961,198 @@ Always use a detailed task description to provide context for the task, and leve
     // only mutate fields the model actually set to a meaningful value.
     if (typeof title === 'string' && title.trim().length > 0) task.title = title;
     if (typeof description === 'string' && description.trim().length > 0) task.description = description;
-    
+
     task.updatedAt = new Date().toISOString();
 
-    return {
+    const result = {
       message: 'Task updated successfully',
-      task
+      task,
     };
+
+    // ── Task-transition memory handler ────────────────────────────────
+    // When a task transitions INTO `in_progress`, we either:
+    //   (a) Auto-load its attached memory (if the description carries a
+    //       `[memory:mem-...]` marker) and embed the content in the tool
+    //       result so the agent reads it on the same turn — no extra
+    //       `memory read` call required, no nudge needed.
+    //   (b) If no memory is attached, emit a one-line nudge pointing the
+    //       agent at the `## AGENT MEMORY` catalog in the system prompt
+    //       so it can scan for adjacent context.
+    //
+    // Production observation (Monopoly trace): 0 memory ops across
+    // 1556 messages. Memories that DO get created are not consulted.
+    // Surfacing the attached memory at the transition moment makes it
+    // un-missable; the conditional nudge keeps the prompt clean when
+    // there's nothing to attach.
+    const becameInProgress = prevStatus !== 'in_progress' && task.status === 'in_progress';
+    if (becameInProgress && context.agentId) {
+      const memMatch = typeof task.description === 'string'
+        ? task.description.match(/\[memory:(mem-[A-Za-z0-9_-]+)\]/)
+        : null;
+      if (memMatch) {
+        try {
+          const memoryService = getMemoryService(this.logger);
+          await memoryService.initialize();
+          const all = await memoryService.loadMemories(context.agentId);
+          const mem = (all || []).find(m => m.id === memMatch[1]);
+          if (mem) {
+            result.attachedMemory = {
+              id: mem.id,
+              title: mem.title,
+              content: mem.content,
+              _hint: 'This memory was auto-loaded because the task references it. Use `memory append` (id: ' + mem.id + ') if your work yields new findings or methodology worth recording.',
+            };
+          } else {
+            // Reference exists but memory was deleted — surface that fact.
+            result.attachedMemory = {
+              id: memMatch[1],
+              error: 'Memory referenced in task description was not found (may have been deleted). Consider attaching a fresh one.',
+            };
+          }
+        } catch (e) {
+          this.logger?.debug?.('Auto-load of attached memory failed', { error: e.message });
+        }
+      } else {
+        // No memory attached — emit a nudge pointing at the catalog.
+        //
+        // Wording is gated by LOXIA_MEMORY_NUDGE_VARIANT (env) so the
+        // memory-bench can A/B baseline ('descriptive') vs directive
+        // ('directive') on production code WITHOUT requiring two
+        // separate builds.
+        //
+        // Default is 'directive' (the ship in 9a6957f). Validation
+        // pass scheduled to compare against 'descriptive' on
+        // production-relevant models (Kimi-K2.6, gpt-5.4) before
+        // confirming the ship or reverting.
+        const variant = (process.env.LOXIA_MEMORY_NUDGE_VARIANT || 'directive').toLowerCase();
+        if (variant === 'descriptive' || variant === 'baseline') {
+          result.memoryNudge =
+            'No memory is attached to this task (description has no `[memory:mem-...]` marker). ' +
+            'Scan the `## AGENT MEMORY` catalog in your system prompt for adjacent context that may inform this work. ' +
+            'If you produce findings or methodology worth preserving, create a memory with `memory add` (title prefix `task-context/...` recommended) and reference it in this task.';
+        } else {
+          // 'directive' (default / current ship).
+          result.memoryNudge =
+            'No memory is attached to this task (description has no `[memory:mem-...]` marker). ' +
+            'Your VERY NEXT tool call MUST be `memory list` to check for applicable rules, preferences, or prior findings before doing the work. ' +
+            'If you produce findings or methodology worth preserving, create a memory with `memory add` (title prefix `task-context/...` recommended) and reference it in this task.';
+        }
+      }
+    }
+
+    return result;
   }
 
   /**
    * List all tasks
    * @private
    */
+  /**
+   * Lazy TaskIndexer accessor — cached per tool instance. Null when no
+   * embedding service is attached to aiService.
+   * @private
+   */
+  _getTaskIndexer() {
+    if (this._taskIndexer) return this._taskIndexer;
+    const svc = this.aiService?.getEmbeddingService?.();
+    if (!svc) return null;
+    this._taskIndexer = new TaskIndexer({ embeddingService: svc, logger: this.logger });
+    return this._taskIndexer;
+  }
+
+  /**
+   * Semantic search over the agent's tasks. Falls back to substring
+   * filtering when embeddings are disabled. Optional `status` filter
+   * narrows to one task state.
+   *
+   * Params: { query, topK?=10, hybrid?=true, status? }
+   */
+  async searchTasks(agent, params) {
+    const query = typeof params?.query === 'string' ? params.query.trim() : '';
+    if (!query) return { success: false, error: 'query is required for search' };
+    const topK = Number.isInteger(params.topK) && params.topK > 0 ? params.topK : 10;
+    const hybrid = params.hybrid !== false;
+    const statusFilter = typeof params.status === 'string' ? params.status.toLowerCase() : null;
+
+    const indexer = this._getTaskIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      // Fallback: filter by substring on title/description.
+      const lower = query.toLowerCase();
+      const matches = (agent.taskList?.tasks || [])
+        .filter(t => (
+          (statusFilter ? t.status === statusFilter : true) &&
+          ((t.title || '').toLowerCase().includes(lower) ||
+           (t.description || '').toLowerCase().includes(lower))
+        ))
+        .slice(0, topK);
+      return {
+        success: true,
+        action: 'search',
+        mode: 'substring-fallback',
+        query,
+        results: matches,
+        totalResults: matches.length,
+        message: matches.length === 0
+          ? `Embeddings disabled; substring search found no matches for "${query}"`
+          : `Embeddings disabled; substring search found ${matches.length} tasks`,
+      };
+    }
+
+    const { hits, error } = await indexer.search(agent.id, query, { topK, hybrid, statusFilter });
+    // Hydrate back to live tasks from agent.taskList so latest content is shown.
+    const byId = new Map((agent.taskList?.tasks || []).map(t => [t.id, t]));
+    const results = hits
+      .map(h => {
+        const live = byId.get(h.id);
+        return live ? { ...live, score: h.score } : { id: h.id, score: h.score, missing: true, ...h.metadata };
+      });
+
+    return {
+      success: !error,
+      action: 'search',
+      mode: hybrid ? 'hybrid' : 'semantic',
+      query,
+      results,
+      totalResults: results.length,
+      ...(error ? { error } : {}),
+      message: error
+        ? `Task search failed: ${error}`
+        : results.length === 0
+          ? `No tasks matched "${query}"`
+          : `Found ${results.length} tasks ranked by similarity to "${query}"`,
+    };
+  }
+
+  /**
+   * Rebuild the tasks vector index from agent.taskList.tasks. Use after
+   * enabling embeddings or after a model swap.
+   */
+  async backfillTasksSearchIndex(agent) {
+    const indexer = this._getTaskIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'backfill-search-index',
+        message: 'Embeddings are not enabled — nothing to backfill. Enable a provider in Settings → Embeddings first.',
+      };
+    }
+    const tasks = agent.taskList?.tasks || [];
+    const r = await indexer.backfill(agent.id, tasks);
+    return {
+      success: r.ok !== false && !r.error,
+      action: 'backfill-search-index',
+      indexed: r.indexed || 0,
+      skipped: r.skipped || 0,
+      failed: r.failed || 0,
+      ...(r.error ? { error: r.error } : {}),
+      message: r.ok === false
+        ? `Tasks backfill failed: ${r.reason || r.error || 'unknown'}`
+        : `Indexed ${r.indexed || 0} tasks` +
+          (r.skipped ? `, skipped ${r.skipped}` : '') +
+          (r.failed ? `, failed ${r.failed}` : '') + '.',
+    };
+  }
+
   async listTasks(agent, params) {
     const { status, priority } = params;
     let tasks = [...agent.taskList.tasks];

package/src/tools/terminalTool.js

@@ -380,11 +380,14 @@ After each invocation you will get a tool-result embedded in the following user
     } else {
       // Validate each action
       for (const [index, action] of params.actions.entries()) {
+        // Accept both `type` and `action` as item discriminator
+        // (cross-tool field-name unification).
+        if (!action.type && action.action) action.type = action.action;
         if (!action.type) {
           errors.push(`Action ${index + 1}: type is required`);
           continue;
         }
-        
+
         switch (action.type) {
           case 'run-command':
             if (!action.command || !action.command.trim()) {
@@ -431,6 +434,25 @@ After each invocation you will get a tool-result embedded in the following user
    * @returns {Promise<Object>} Execution result
    */
   async execute(params, context) {
+    // Forgiving normalization — production agents commonly call with
+    // the natural singular shape `{command: "ls"}` instead of the
+    // documented plural `{actions: [{type: "run-command", command: "ls"}]}`.
+    // Live trace: gpt-5.4 + Kimi-K2.6 both hit "actions is not iterable"
+    // on this. Accept singular forms here and promote to canonical.
+    if ((!params.actions || !Array.isArray(params.actions)) && params.command) {
+      const { command, type, ...rest } = params;
+      params = { ...params, actions: [{ type: type || 'run-command', command, ...rest }] };
+    }
+
+    // Normalize discriminator on each action item (accept both `type`
+    // and `action`). Same rationale as fileSystemTool — execute() may
+    // be called bypassing validation in production.
+    if (Array.isArray(params.actions)) {
+      for (const a of params.actions) {
+        if (a && !a.type && a.action) a.type = a.action;
+      }
+    }
+
     const { actions, timeout: customTimeout, async: forceAsync } = params;
     const { agentId, projectDir, directoryAccess } = context;
 

package/src/tools/visionTool.js

@@ -123,6 +123,13 @@ ANSWERS: Structured, direct answers only — no filler text.`;
   }
 
   async execute(params, context = {}) {
+    // Reverse-forgiveness: accept plural envelope {actions:[{type/action}]}
+    // even though this tool's canonical shape is singular.
+    if (Array.isArray(params?.actions) && params.actions.length > 0) {
+      const a = params.actions[0] || {};
+      params = { ...params, ...a, action: a.type || a.action || params.action };
+    }
+
     this._ensureCleanup();
 
     try {

package/src/tools/visualEditorTool.js

@@ -319,6 +319,13 @@ Code:
    * @returns {Promise<Object>} Execution result
    */
   async execute(params, context = {}) {
+    // Reverse-forgiveness: accept plural {actions:[{...}]} envelope
+    // (cross-tool unification).
+    if (Array.isArray(params?.actions) && params.actions.length > 0) {
+      const a = params.actions[0] || {};
+      params = { ...params, ...a, action: a.type || a.action || params.action };
+    }
+
     // FIRST THING: an unconditional console.log so we can always see that
     // the tool was invoked — before any early-return (parse failure,
     // bridge disabled, validation fail) or thrown error could swallow it.