onbuzz 4.8.2 → 4.9.0

package/src/tools/officeTool.js

@@ -0,0 +1,313 @@
+/**
+ * officeTool — single Office tool covering Word (.docx), Excel (.xlsx),
+ * and PowerPoint (.pptx). Replaces the older `doc` and `spreadsheet`
+ * tools (which we keep registered for back-compat for one release).
+ *
+ * Action shape — plural-canonical envelope:
+ *
+ *   {
+ *     toolId: "office",
+ *     actions: [
+ *       { type: "doc.create",   outputPath, content },
+ *       { type: "doc.read",     filePath, format? },
+ *       { type: "doc.info",     filePath },
+ *       { type: "sheet.create", outputPath, content },
+ *       { type: "sheet.read",   filePath, sheetName?, startRow?, endRow?, includeFormulas? },
+ *       { type: "sheet.info",   filePath },
+ *       { type: "pres.create",  outputPath, content },
+ *       { type: "pres.info",    filePath }
+ *     ]
+ *   }
+ *
+ * Forgiving inputs:
+ *   - Accepts both `type` and `action` as the discriminator.
+ *   - Accepts a legacy singular envelope `{action, ...}` for one release
+ *     cycle (reverse-forgiveness pattern). New callers should generate
+ *     the plural envelope.
+ *
+ * Output:
+ *   - Each action returns {success, action, ...payload, output, message}.
+ *   - Multiple actions in one envelope return `{success, summary, results}`
+ *     similar to the bulk-agent endpoint.
+ */
+
+import { BaseTool } from './baseTool.js';
+import TagParser from '../utilities/tagParser.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+import { createDoc, readDoc, docInfo } from './office/officeDoc.js';
+import { createSheet, readSheet, sheetInfo } from './office/officeSheet.js';
+import { createPres, presInfo } from './office/officePres.js';
+
+const SUPPORTED = new Set([
+  'doc.create', 'doc.read', 'doc.info',
+  'sheet.create', 'sheet.read', 'sheet.info',
+  'pres.create', 'pres.info',
+]);
+
+const READ_ACTIONS = new Set(['doc.read', 'doc.info', 'sheet.read', 'sheet.info', 'pres.info']);
+const CREATE_ACTIONS = new Set(['doc.create', 'sheet.create', 'pres.create']);
+
+class OfficeTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+    this.id = 'office';
+    this.name = 'Office Tool';
+    this.description = 'Create + read Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files';
+    this.version = '1.0.0';
+    this.requiresProject = false;
+    this.isAsync = false;
+  }
+
+  getDescription() {
+    return `
+Office Tool: Create and read Word, Excel, and PowerPoint files in one place.
+
+Plural-canonical envelope:
+
+\`\`\`json
+{
+  "toolId": "office",
+  "actions": [
+    { "type": "doc.create",   "outputPath": "out/report.docx",     "content": { "title": "...", "sections": [ { "children": [ ... ] } ] } },
+    { "type": "sheet.create", "outputPath": "out/data.xlsx",       "content": { "sheets": [ { "name": "Q1", "columns": [...], "rows": [...] } ] } },
+    { "type": "pres.create",  "outputPath": "out/deck.pptx",       "content": { "title": "...", "slides": [ { "layout": "title", "title": "..." } ] } },
+    { "type": "doc.read",     "filePath":   "in/notes.docx",       "format": "text" },
+    { "type": "sheet.read",   "filePath":   "in/data.xlsx",        "sheetName": "Q1", "startRow": 1, "endRow": 50 },
+    { "type": "doc.info",     "filePath":   "in/notes.docx" },
+    { "type": "sheet.info",   "filePath":   "in/data.xlsx" },
+    { "type": "pres.info",    "filePath":   "in/deck.pptx" }
+  ]
+}
+\`\`\`
+
+Word (.docx) content nodes:
+  - heading      { level: 1-6, text, color?, alignment? }
+  - paragraph    { text, bold?, italic?, underline?, fontSize?, color?, alignment?, indent? }
+  - richParagraph{ runs: [{ text, bold?, italic?, color?, size?, font? }] }
+  - list         { ordered?: bool, items: ["..."] or [{ text, level: 0-3 }] }
+  - table        { headers: [...], rows: [[...]], widths?, headerFill?, alternateFill?, borderColor? }
+  - callout      { label, content, color? }   — left-bar coloured callout
+  - hyperlink    { text, url }
+  - pageBreak / horizontalRule
+
+Excel (.xlsx) sheet object:
+  - columns      [{ header, key?, width?, type: "text|number|currency|percent|date|duration", numFmt? }]
+  - rows         [ { key: val } | [val, ...] ]   — strings starting with "=" become formulas
+  - headerStyle  { bold?, fontColor?, fill?, alignment?, height? }
+  - alternateRowFill   #RRGGBB for zebra rows
+  - formulas     [{ cell: "C2", formula: "=A2+B2" }]
+  - cellStyles   [{ cell: "B5", bold?, fill?, fontColor?, alignment?, border? }]
+  - mergedCells  [{ range: "A1:C1" }]
+  - freezeRow / freezeColumn
+  - autoFilter   true | { from, to }
+  - conditionalFormatting [{ range, type: "cellIs|containsText|dataBar|colorScale", operator?, value?, fill?, fontColor? }]
+  - namedRanges  [{ name, range }]
+  - charts       [...]   — best-effort
+
+PowerPoint (.pptx) slide:
+  - layout       "title | content | section-header | two-content | blank"
+  - title, subtitle
+  - content      [
+      { type: "text",    text, x?, y?, w?, h?, fontSize?, bold?, color?, align? },
+      { type: "bullets", items: [...], x?, y?, w?, h? },
+      { type: "image",   path: "..." | data: "<base64>", x?, y?, w?, h? },
+      { type: "table",   headers, rows, headerStyle?, cellStyle? },
+      { type: "shape",   shape: "rect|rounded|ellipse|line|triangle", x, y, w, h, fill?, border? },
+      { type: "chart",   chartType: "bar|line|pie|area|doughnut", data: [...], title? }
+    ]
+  - notes        speaker notes string
+  - background   #RRGGBB
+
+Output paths can be relative — they're resolved under the agent's projectDir
+and protected against path traversal.
+    `.trim();
+  }
+
+  parseParameters(content) {
+    // Backwards compatibility for tag-format. Most callers use JSON.
+    try {
+      const typeMatches = TagParser.extractContent(content, 'type');
+      const actionMatches = TagParser.extractContent(content, 'action');
+      const filePathMatches = TagParser.extractContent(content, 'filePath');
+      const outputPathMatches = TagParser.extractContent(content, 'outputPath');
+      const formatMatches = TagParser.extractContent(content, 'format');
+      return {
+        actions: [{
+          type: (typeMatches[0] || actionMatches[0] || 'doc.info').trim(),
+          filePath: (filePathMatches[0] || '').trim(),
+          outputPath: (outputPathMatches[0] || '').trim(),
+          format: (formatMatches[0] || 'text').trim(),
+        }],
+      };
+    } catch (error) {
+      throw new Error(`Failed to parse Office tool parameters: ${error.message}`);
+    }
+  }
+
+  getSupportedActions() {
+    return Array.from(SUPPORTED);
+  }
+
+  async execute(params, context) {
+    const { projectDir } = context || {};
+
+    // Normalise envelope: accept plural-canonical OR legacy singular.
+    let actions = Array.isArray(params?.actions) ? params.actions : null;
+    if (!actions) {
+      const single = params?.action ? { ...params, type: params.action } : params;
+      if (single && (single.type || single.action)) actions = [single];
+    }
+    if (!actions || actions.length === 0) {
+      return {
+        success: false,
+        error: 'No actions provided',
+        output: 'Provide actions array — e.g. [{ "type": "doc.create", "outputPath": "...", "content": { ... } }]',
+      };
+    }
+
+    const results = [];
+    for (const raw of actions) {
+      const type = String(raw.type || raw.action || '').toLowerCase();
+      if (!SUPPORTED.has(type)) {
+        results.push({
+          success: false,
+          type,
+          error: `Unknown action: ${type}`,
+          output: `Unsupported action "${type}". Supported: ${Array.from(SUPPORTED).join(', ')}`,
+        });
+        continue;
+      }
+      try {
+        const result = await this._runOne(type, raw, projectDir);
+        results.push(result);
+      } catch (err) {
+        this.logger?.error?.('officeTool action failed', { type, error: err.message });
+        results.push({ success: false, type, error: err.message, output: err.message });
+      }
+    }
+
+    // Single-action: return its result directly (matches the legacy shape).
+    if (results.length === 1) return results[0];
+
+    const ok = results.filter(r => r.success).length;
+    const failed = results.length - ok;
+    return {
+      success: failed === 0,
+      summary: { total: results.length, ok, failed },
+      results,
+      output: `Office: ${ok}/${results.length} actions succeeded`,
+    };
+  }
+
+  async _runOne(type, action, projectDir) {
+    if (CREATE_ACTIONS.has(type)) {
+      return this._handleCreate(type, action, projectDir);
+    }
+    if (READ_ACTIONS.has(type)) {
+      return this._handleRead(type, action, projectDir);
+    }
+    return { success: false, type, error: 'Unhandled action', output: `Unhandled: ${type}` };
+  }
+
+  async _handleCreate(type, action, projectDir) {
+    let outputPath = action.outputPath;
+    if (!outputPath) {
+      return { success: false, type, error: 'outputPath is required', output: 'Provide an outputPath' };
+    }
+    if (!action.content || typeof action.content !== 'object') {
+      return { success: false, type, error: 'content is required', output: 'Provide a content object' };
+    }
+
+    if (!path.isAbsolute(outputPath)) {
+      outputPath = path.resolve(projectDir || process.cwd(), outputPath);
+    }
+    const baseDir = projectDir || process.cwd();
+    const normalized = path.normalize(outputPath);
+    if (!normalized.startsWith(path.normalize(baseDir))) {
+      return { success: false, type, error: 'Path traversal detected', output: 'outputPath must be inside the project directory' };
+    }
+    await fs.mkdir(path.dirname(normalized), { recursive: true });
+
+    // Ensure extension matches the action type.
+    const extExpected = type === 'doc.create' ? '.docx'
+      : type === 'sheet.create' ? '.xlsx'
+      : '.pptx';
+    let finalPath = normalized;
+    if (!finalPath.toLowerCase().endsWith(extExpected)) {
+      finalPath += extExpected;
+    }
+
+    let writeResult;
+    if (type === 'doc.create')   writeResult = await createDoc(action.content, finalPath);
+    if (type === 'sheet.create') writeResult = await createSheet(action.content, finalPath);
+    if (type === 'pres.create')  writeResult = await createPres(action.content, finalPath);
+
+    return {
+      success: true,
+      type,
+      outputPath: writeResult.path,
+      fileSize: writeResult.size,
+      output: `Created ${path.basename(writeResult.path)} (${(writeResult.size / 1024).toFixed(1)} KB)`,
+      message: `Wrote ${path.basename(writeResult.path)}`,
+      ...(writeResult.sheetCount  ? { sheetCount:  writeResult.sheetCount  } : {}),
+      ...(writeResult.slideCount  ? { slideCount:  writeResult.slideCount  } : {}),
+    };
+  }
+
+  async _handleRead(type, action, projectDir) {
+    let filePath = action.filePath;
+    if (!filePath) {
+      return { success: false, type, error: 'filePath is required', output: 'Provide a filePath' };
+    }
+    if (!path.isAbsolute(filePath)) {
+      filePath = path.resolve(projectDir || process.cwd(), filePath);
+    }
+    try {
+      await fs.access(filePath);
+    } catch {
+      return { success: false, type, error: 'File not found', output: `Not found: ${filePath}` };
+    }
+    // Extension guards
+    const lower = filePath.toLowerCase();
+    if ((type === 'doc.read' || type === 'doc.info') && !/\.docx?$/.test(lower)) {
+      return { success: false, type, error: 'Wrong extension', output: `Expected .docx for ${type}` };
+    }
+    if ((type === 'sheet.read' || type === 'sheet.info') && !/\.(xlsx|xls|csv)$/.test(lower)) {
+      return { success: false, type, error: 'Wrong extension', output: `Expected .xlsx/.csv for ${type}` };
+    }
+    if (type === 'pres.info' && !/\.pptx$/.test(lower)) {
+      return { success: false, type, error: 'Wrong extension', output: `Expected .pptx for ${type}` };
+    }
+
+    if (type === 'doc.info') {
+      const info = await docInfo(filePath);
+      return { success: true, type, filePath, info, output: `Doc info: ${info.fileName} (${info.wordCount} words, ~${info.estimatedPages} pages)` };
+    }
+    if (type === 'doc.read') {
+      const r = await readDoc(filePath, action.format || 'text');
+      return { success: true, type, filePath, format: r.format, content: r.content, output: r.content };
+    }
+    if (type === 'sheet.info') {
+      const info = await sheetInfo(filePath);
+      const summary = info.sheets.map(s => `${s.name} (${s.rowCount}r × ${s.columnCount}c)`).join('; ');
+      return { success: true, type, filePath, info, output: `Sheet info: ${info.fileName} — ${summary}` };
+    }
+    if (type === 'sheet.read') {
+      const r = await readSheet(filePath, action);
+      return {
+        success: true, type, filePath,
+        sheetName: r.sheetName, totalRows: r.totalRows, rowCount: r.rows.length, rows: r.rows,
+        output: `Read ${r.rows.length} rows from "${r.sheetName}"`,
+      };
+    }
+    if (type === 'pres.info') {
+      const info = await presInfo(filePath);
+      return { success: true, type, filePath, info, output: `Pres info: ${info.fileName} (${info.slideCount ?? '?'} slides)` };
+    }
+    return { success: false, type, error: 'Unhandled', output: `Unhandled: ${type}` };
+  }
+}
+
+export default OfficeTool;

package/src/tools/openaiFunctionSchemas.js

@@ -241,65 +241,55 @@ export const OPENAI_FUNCTION_SCHEMAS = [
   //     around         — {mode, messageId, before?, after?, detail?}
   //     byTool         — {mode, toolId?, limit?, cursor?}
   //     read           — {mode, messageId, lineFrom?/lineTo? OR contentFrom?/contentTo?, detail?}
+  // Memory — actions-array (canonical plural shape, matches filesystem /
+  // terminal / taskmanager). Supports batching multiple ops in one
+  // tool call: e.g. read three memories at once, or list+search in
+  // the same turn. Singular {action, ...} is still accepted by the
+  // runtime as backward-compat but the schema teaches plural.
   {
     type: 'function',
     name: 'memory',
-    description: 'Store and retrieve persistent memories across sessions, and browse your own pre-compaction conversation archive via the `reminisce` action.',
+    description: 'Store and retrieve persistent memories across sessions, and browse your own pre-compaction conversation archive via the `reminisce` action. Pack multiple operations into one call.',
     parameters: {
       type: 'object',
       properties: {
-        action:      { type: 'string', enum: ['add', 'update', 'delete', 'read', 'list', 'search', 'stats', 'reminisce'] },
-        id:          { type: 'string', description: 'Memory id. Required for: update, delete, read (of memory entries).' },
-        title:       { type: 'string', description: 'Short title. Required for: add. Optional for: update.' },
-        content:     { type: 'string', description: 'Full memory content. Required for: add. Optional for: update.' },
-        description: { type: 'string', description: 'Short summary. Optional for: add, update.' },
-        query:       { type: 'string', description: 'Search query. Required for memory search AND reminisce search.' },
-        level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for memory list/search output.' },
+        actions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              type:        { type: 'string', enum: ['add', 'update', 'append', 'delete', 'read', 'list', 'search', 'stats', 'reminisce'], description: 'The memory operation to perform.' },
+              id:          { type: 'string', description: 'Memory id. Required for: update, append, delete, read (of memory entries).' },
+              title:       { type: 'string', description: 'Short title. Required for: add. Optional for: update.' },
+              content:     { type: 'string', description: 'Full memory content. Required for: add, append. Optional for: update.' },
+              description: { type: 'string', description: 'Short summary. Optional for: add, update.' },
+              query:       { type: 'string', description: 'Search query. Required for memory search AND reminisce search.' },
+              level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for memory list/search output.' },
 
-        // ── reminisce-specific params ─────────────────────────────────────
-        mode: {
-          type: 'string',
-          enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'],
-          description: 'Reminisce sub-mode. Required when action="reminisce".',
-        },
-        messageId: {
-          type: 'string',
-          description: 'Stable pointer into the conversation archive. Required for reminisce around/read. Get messageIds from overview/search/range/byTool results.',
-        },
-        // range / search / byTool paging
-        from:        { type: 'string', description: 'ISO timestamp lower bound (reminisce range).' },
-        to:          { type: 'string', description: 'ISO timestamp upper bound (reminisce range).' },
-        offset:      { type: 'integer', description: 'Pagination offset (reminisce range).' },
-        limit:       { type: 'integer', description: 'Max entries returned (reminisce range/byTool). 1–100.' },
-        maxResults:  { type: 'integer', description: 'Max search matches returned (reminisce search). 1–50.' },
-        role: {
-          type: 'string',
-          enum: ['user', 'assistant', 'system'],
-          description: 'Filter by message role (reminisce search).',
-        },
-        cursor:      { type: 'string', description: 'Opaque pagination cursor from a previous reminisce search/byTool response. Pass verbatim to continue.' },
-        toolId:      { type: 'string', description: 'Filter by toolId (reminisce byTool).' },
-        // around — MESSAGES on each side of the target
-        before: {
-          type: 'integer',
-          description: 'Number of MESSAGES before the target to include (reminisce around). 0–20.',
-        },
-        after: {
-          type: 'integer',
-          description: 'Number of MESSAGES after the target to include (reminisce around). 0–20.',
-        },
-        // read — sub-message window, mutually exclusive (lines win if both)
-        lineFrom:    { type: 'integer', description: 'First line to read, 1-indexed inclusive (reminisce read).' },
-        lineTo:      { type: 'integer', description: 'Last line to read, 1-indexed inclusive (reminisce read). Window capped at 500 lines.' },
-        contentFrom: { type: 'integer', description: 'First character offset (reminisce read, 0-indexed inclusive). Ignored if lineFrom is set.' },
-        contentTo:   { type: 'integer', description: 'Last character offset (reminisce read, 0-indexed exclusive). Window capped at 16000 chars.' },
-        detail: {
-          type: 'string',
-          enum: ['default', 'full'],
-          description: 'Return shape: "default" truncates content and omits toolExecutions; "full" returns everything (eats tokens fast).',
+              // ── reminisce-specific params ─────────────────────────
+              mode:        { type: 'string', enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'], description: 'Reminisce sub-mode. Required when type="reminisce".' },
+              messageId:   { type: 'string', description: 'Stable pointer into the conversation archive (reminisce around/read).' },
+              from:        { type: 'string', description: 'ISO timestamp lower bound (reminisce range).' },
+              to:          { type: 'string', description: 'ISO timestamp upper bound (reminisce range).' },
+              offset:      { type: 'integer', description: 'Pagination offset (reminisce range).' },
+              limit:       { type: 'integer', description: 'Max entries returned (reminisce range/byTool). 1–100.' },
+              maxResults:  { type: 'integer', description: 'Max search matches returned (reminisce search). 1–50.' },
+              role:        { type: 'string', enum: ['user', 'assistant', 'system'], description: 'Filter by message role (reminisce search).' },
+              cursor:      { type: 'string', description: 'Opaque pagination cursor from a previous reminisce search/byTool response.' },
+              toolId:      { type: 'string', description: 'Filter by toolId (reminisce byTool).' },
+              before:      { type: 'integer', description: 'Number of MESSAGES before the target to include (reminisce around). 0–20.' },
+              after:       { type: 'integer', description: 'Number of MESSAGES after the target to include (reminisce around). 0–20.' },
+              lineFrom:    { type: 'integer', description: 'First line to read (reminisce read).' },
+              lineTo:      { type: 'integer', description: 'Last line to read (reminisce read). Window capped at 500 lines.' },
+              contentFrom: { type: 'integer', description: 'First character offset (reminisce read).' },
+              contentTo:   { type: 'integer', description: 'Last character offset (reminisce read). Window capped at 16000 chars.' },
+              detail:      { type: 'string', enum: ['default', 'full'], description: 'Return shape for reminisce results.' },
+            },
+            required: ['type'],
+          },
         },
       },
-      required: ['action'],
+      required: ['actions'],
     },
   },
 ];

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

@@ -184,6 +184,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;