onbuzz 4.1.0 → 4.3.0

package/src/services/galleryService.js

@@ -0,0 +1,257 @@
+/**
+ * @file services/galleryService.js
+ * @description Durable gallery for tool-generated media.
+ *
+ * Why this exists:
+ *   Before, the web-UI gallery listed files by scanning each agent's
+ *   `working-dir/images/` folder. That breaks the moment a file is
+ *   moved, an agent is deleted, or the agent's workingDirectory
+ *   changes — and there's nowhere to store the prompt/model metadata
+ *   that made the image in the first place. GalleryService gives each
+ *   generation a durable home at `{userDataDir}/gallery/{images|videos}/`
+ *   with a `.json` sidecar carrying the full metadata.
+ *
+ * Layout:
+ *   {userDataDir}/gallery/
+ *     images/
+ *       2026-04-22T12-34-56_fox.png           ← the asset
+ *       2026-04-22T12-34-56_fox.png.json      ← metadata sidecar
+ *     videos/
+ *       2026-04-22T12-34-56_dragon.mp4
+ *       2026-04-22T12-34-56_dragon.mp4.json
+ *
+ * Sidecar shape (whatever the caller passed to saveImage/saveVideo):
+ *   {
+ *     filename:        "2026-04-22T12-34-56_fox.png",
+ *     sourcePath:      "/original/path/images/fox.png",
+ *     agentId:         "agent-xyz",
+ *     agentName:       "Alice",
+ *     prompt:          "a fox on a skateboard",
+ *     model:           "dall-e-3",
+ *     size:            "1024x1024",      // or width/height
+ *     duration:        5,                 // video only
+ *     variants:        1,                 // video only
+ *     createdAt:       "2026-04-22T12:34:56.789Z",
+ *     bytes:           834221,
+ *   }
+ *
+ * Save-time naming guarantees:
+ *   - Timestamp prefix prevents collisions when two agents pick the
+ *     same filename.
+ *   - Original filename is retained after the prefix so users can still
+ *     recognise what they asked for.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getUserDataPaths, ensureUserDataDirs } from '../utilities/userDataDir.js';
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+const VIDEO_EXTS = new Set(['.mp4', '.webm', '.mov', '.gif']);
+
+function _ts() {
+  // Filesystem-safe ISO — replaces ':' (illegal on Windows) with '-'.
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function _isImage(name) { return IMAGE_EXTS.has(path.extname(name).toLowerCase()); }
+function _isVideo(name) { return VIDEO_EXTS.has(path.extname(name).toLowerCase()); }
+
+async function _ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+/** Write `data` to `{target}.json` — pretty, atomic-ish (write + rename). */
+async function _writeSidecar(target, data) {
+  const json = JSON.stringify(data, null, 2);
+  const tmp = `${target}.json.tmp`;
+  await fs.writeFile(tmp, json, 'utf8');
+  await fs.rename(tmp, `${target}.json`);
+}
+
+async function _readSidecar(target) {
+  try {
+    const raw = await fs.readFile(`${target}.json`, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort: strip known internal keys before returning to callers. */
+function _sanitiseMeta(meta, file, stat, url) {
+  const out = { ...(meta || {}) };
+  out.filename = file;
+  out.bytes = stat.size;
+  out.mtime = stat.mtime.toISOString();
+  if (url) out.url = url;
+  return out;
+}
+
+class GalleryService {
+  constructor(logger = null) {
+    this.logger = logger;
+    this.paths = getUserDataPaths();
+  }
+
+  /**
+   * Copy a freshly-generated image into the durable gallery.
+   * @param {object} opts
+   * @param {string} opts.sourcePath  absolute path to source file
+   * @param {object} opts.metadata    free-form sidecar data
+   * @param {string} [opts.filenameHint] override the suggested filename
+   * @returns {Promise<{ filename: string, path: string } | null>}
+   *          null when sourcePath couldn't be read (non-fatal)
+   */
+  async saveImage({ sourcePath, metadata = {}, filenameHint } = {}) {
+    if (!sourcePath) return null;
+    if (!_isImage(filenameHint || sourcePath)) return null;
+    try {
+      await _ensureDir(this.paths.galleryImages);
+      const base = path.basename(filenameHint || sourcePath);
+      const final = `${_ts()}_${base}`;
+      const target = path.join(this.paths.galleryImages, final);
+      await fs.copyFile(sourcePath, target);
+      const stat = await fs.stat(target);
+      await _writeSidecar(target, {
+        ...metadata,
+        filename: final,
+        sourcePath,
+        bytes: stat.size,
+        createdAt: metadata.createdAt || new Date().toISOString(),
+        kind: 'image',
+      });
+      this.logger?.info?.('[Gallery] saved image', { final, sourcePath });
+      return { filename: final, path: target };
+    } catch (err) {
+      // Gallery save is non-fatal — the tool's primary save to the
+      // agent's working dir already succeeded.
+      this.logger?.warn?.('[Gallery] saveImage failed', { error: err.message, sourcePath });
+      return null;
+    }
+  }
+
+  /** Same shape as saveImage, but for videos. */
+  async saveVideo({ sourcePath, metadata = {}, filenameHint } = {}) {
+    if (!sourcePath) return null;
+    if (!_isVideo(filenameHint || sourcePath)) return null;
+    try {
+      await _ensureDir(this.paths.galleryVideos);
+      const base = path.basename(filenameHint || sourcePath);
+      const final = `${_ts()}_${base}`;
+      const target = path.join(this.paths.galleryVideos, final);
+      await fs.copyFile(sourcePath, target);
+      const stat = await fs.stat(target);
+      await _writeSidecar(target, {
+        ...metadata,
+        filename: final,
+        sourcePath,
+        bytes: stat.size,
+        createdAt: metadata.createdAt || new Date().toISOString(),
+        kind: 'video',
+      });
+      this.logger?.info?.('[Gallery] saved video', { final, sourcePath });
+      return { filename: final, path: target };
+    } catch (err) {
+      this.logger?.warn?.('[Gallery] saveVideo failed', { error: err.message, sourcePath });
+      return null;
+    }
+  }
+
+  /**
+   * List gallery images, newest first. Optional { agentId } filter.
+   * Returns rich entries populated from the sidecar where available.
+   */
+  async listImages({ agentId } = {}) {
+    return this._listDir(this.paths.galleryImages, _isImage, agentId, 'image');
+  }
+
+  /** Same for videos. */
+  async listVideos({ agentId } = {}) {
+    return this._listDir(this.paths.galleryVideos, _isVideo, agentId, 'video');
+  }
+
+  async _listDir(dir, extCheck, agentId, kind) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return [];
+    }
+    const results = [];
+    for (const name of entries) {
+      if (!extCheck(name)) continue;
+      const abs = path.join(dir, name);
+      let stat;
+      try { stat = await fs.stat(abs); } catch { continue; }
+      if (!stat.isFile()) continue;
+      const meta = (await _readSidecar(abs)) || {};
+      if (agentId && meta.agentId && meta.agentId !== agentId) continue;
+      results.push(_sanitiseMeta({ ...meta, kind }, name, stat, /* url */ null));
+    }
+    // Sort newest-first. Use createdAt from sidecar when available (more
+    // precise than mtime, which can collide at ms resolution on fast
+    // filesystems). Filename fallback works because we embed a timestamp
+    // prefix at save time.
+    results.sort((a, b) => {
+      const ka = a.createdAt || a.filename || '';
+      const kb = b.createdAt || b.filename || '';
+      return kb.localeCompare(ka);
+    });
+    return results;
+  }
+
+  /** Delete a gallery image by filename (+ its sidecar). 404 → false. */
+  async deleteImage(filename) {
+    return this._deleteFile(this.paths.galleryImages, filename, _isImage);
+  }
+
+  /** Delete a gallery video by filename (+ its sidecar). */
+  async deleteVideo(filename) {
+    return this._deleteFile(this.paths.galleryVideos, filename, _isVideo);
+  }
+
+  async _deleteFile(dir, filename, extCheck) {
+    const normalized = path.basename(filename || '');
+    if (!normalized || normalized !== filename) {
+      throw Object.assign(new Error('Invalid filename'), { code: 'INVALID_FILENAME' });
+    }
+    if (!extCheck(normalized)) {
+      throw Object.assign(new Error('Unsupported extension'), { code: 'INVALID_EXT' });
+    }
+    const target = path.join(dir, normalized);
+    let existed = false;
+    try {
+      await fs.unlink(target);
+      existed = true;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+    // Sidecar is best-effort — missing sidecar is fine.
+    await fs.unlink(`${target}.json`).catch(() => {});
+    return existed;
+  }
+
+  /** Diagnostic helper (used by tests). */
+  async _ensureStructure() {
+    await ensureUserDataDirs();
+    await _ensureDir(this.paths.galleryImages);
+    await _ensureDir(this.paths.galleryVideos);
+  }
+}
+
+/* Singleton. Tools and webServer routes share one instance. */
+let _instance = null;
+
+export function getGalleryService(logger = null) {
+  if (!_instance) _instance = new GalleryService(logger);
+  return _instance;
+}
+
+/** Test-only — reset module state. */
+export function _resetGalleryServiceForTests() {
+  _instance = null;
+}
+
+export default GalleryService;
+export { GalleryService };

package/src/tools/__tests__/agentCommunicationTool.test.js

@@ -600,4 +600,118 @@ describe('AgentCommunicationTool', () => {
       expect(result.yourTeams[0].role).toBe('manager');
     });
   });
+
+  // Per-agent toolConfig overrides (agent.toolConfig.agentcommunication).
+  // Effective limits resolve via BaseTool#getEffectiveConfig at each
+  // check-point in the tool.
+  describe('per-agent toolConfig overrides', () => {
+    test('per-agent maxRecipientsPerMessage overrides global default', async () => {
+      const { tool, context } = createTestSetup();
+      // Global default = 3; per-agent override = 1 → sending to 2 must fail.
+      const result = await tool.sendMessage('agent-sender', {
+        recipients: ['agent-recipient', 'agent-other'],
+        subject: 's',
+        message: 'm',
+      }, { ...context, toolConfig: { maxRecipientsPerMessage: 1 } });
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/Maximum 1 recipients allowed/);
+    });
+
+    test('global default still applies when no per-agent override', async () => {
+      const { tool, context } = createTestSetup();
+      // Global default = 3; 4 recipients fails without any override.
+      const result = await tool.sendMessage('agent-sender', {
+        recipients: ['a', 'b', 'c', 'd'],
+        subject: 's',
+        message: 'm',
+      }, context);
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/Maximum 3 recipients allowed/);
+    });
+
+    test('per-agent maxAttachmentsPerMessage overrides global default', async () => {
+      const { tool, context } = createTestSetup();
+      const atts = [
+        { path: '/a.txt' },
+        { path: '/b.txt' },
+        { path: '/c.txt' },
+      ];
+      await expect(
+        tool._processAttachments(atts, 'agent-sender', { ...context, toolConfig: { maxAttachmentsPerMessage: 2 } })
+      ).rejects.toThrow(/Maximum 2 attachments allowed/);
+    });
+
+    test('per-agent maxAttachmentSize overrides global default', async () => {
+      const { tool, context } = createTestSetup();
+      // Stat returns size 100; override to 10 → too large. The tool's
+      // per-attachment try/catch swallows the error and just skips the
+      // attachment, so the emitted array is empty. We also assert the
+      // error was logged as proof the size gate actually fired.
+      fsMock.stat.mockResolvedValue({ size: 100 });
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+      const out = await tool._processAttachments([{ path: '/big.txt' }], 'agent-sender', {
+        ...context,
+        toolConfig: { maxAttachmentSize: 10 },
+      });
+      expect(out).toEqual([]);
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringMatching(/Failed to process attachment/),
+        expect.objectContaining({ message: expect.stringMatching(/exceeds size limit/) })
+      );
+      errorSpy.mockRestore();
+    });
+
+    test('per-agent maxAttachmentSize ALLOWS attachments within limit', async () => {
+      const { tool, context } = createTestSetup();
+      fsMock.stat.mockResolvedValue({ size: 50 });
+      const out = await tool._processAttachments([{ path: '/small.txt' }], 'agent-sender', {
+        ...context,
+        toolConfig: { maxAttachmentSize: 1024 },
+      });
+      expect(out).toHaveLength(1);
+    });
+
+    test('per-agent maxConversationDepth caps reply chain', async () => {
+      // Start a fresh conversation with a per-agent cap of 1: the first
+      // reply goes through, the second hits the limit. Mirrors the
+      // existing "rejects reply when conversation depth limit reached"
+      // test but drives the cap from context.toolConfig instead of
+      // mutating tool.config.
+      const { tool, context } = createTestSetup();
+
+      const sendResult = await tool.execute({
+        action: 'send-message',
+        recipient: 'agent-recipient',
+        subject: 'Deep',
+        message: 'Start',
+      }, { ...context, toolConfig: { maxConversationDepth: 1 } });
+      expect(sendResult.success).toBe(true);
+
+      // First reply (depth 1) — should succeed even under the cap.
+      const reply1 = await tool.execute({
+        action: 'reply-to-message',
+        'message-id': sendResult.messageId,
+        message: 'Reply 1',
+      }, { agentId: 'agent-recipient', agentPool: context.agentPool, toolConfig: { maxConversationDepth: 1 } });
+      expect(reply1.success).toBe(true);
+
+      // Second reply — depth now 1, cap is 1, must fail.
+      const reply2 = await tool.execute({
+        action: 'reply-to-message',
+        'message-id': reply1.messageId,
+        message: 'Reply 2',
+      }, { ...context, toolConfig: { maxConversationDepth: 1 } });
+      expect(reply2.success).toBe(false);
+      expect(reply2.error).toMatch(/depth limit reached \(1\)/);
+    });
+
+    test('_processAttachments with no context uses global config (backward compat)', async () => {
+      const { tool } = createTestSetup();
+      // Global = 5; 4 atts → ok (stat mocked to size 100, global max = 10MB).
+      fsMock.stat.mockResolvedValue({ size: 100 });
+      const atts = [{ path: '/a.txt' }, { path: '/b.txt' }];
+      const out = await tool._processAttachments(atts, 'agent-sender');
+      expect(Array.isArray(out)).toBe(true);
+    });
+  });
 });

package/src/tools/__tests__/baseTool.getEffectiveConfig.test.js

@@ -0,0 +1,77 @@
+/**
+ * Tests for BaseTool#getEffectiveConfig — the helper tools use to merge
+ * global defaults (this.config) with per-agent overrides delivered via
+ * context.toolConfig (from agent.toolConfig[toolId]).
+ *
+ * Contract: per-agent > global > fallbacks. Missing/malformed context
+ * leaves the tool looking only at its own config (no crash).
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { BaseTool } from '../baseTool.js';
+
+function makeTool(config = {}) {
+  const t = new BaseTool(config, { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} });
+  return t;
+}
+
+describe('BaseTool.getEffectiveConfig', () => {
+  test('returns this.config when context is missing', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig(null)).toEqual({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig(undefined)).toEqual({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig({})).toEqual({ allowedCommands: ['git'] });
+  });
+
+  test('returns this.config when context has no toolConfig', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig({ toolConfig: null })).toEqual({ allowedCommands: ['git'] });
+  });
+
+  test('per-agent toolConfig overrides global config field', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    const effective = tool.getEffectiveConfig({
+      toolConfig: { allowedCommands: ['git', 'npm'] },
+    });
+    expect(effective.allowedCommands).toEqual(['git', 'npm']);
+  });
+
+  test('per-agent toolConfig merges extra fields with global config', () => {
+    const tool = makeTool({ allowedCommands: ['git'], maxBackgroundCommandsPerAgent: 3 });
+    const effective = tool.getEffectiveConfig({
+      toolConfig: { blockedCommands: ['rm -rf'] },
+    });
+    expect(effective).toEqual({
+      allowedCommands: ['git'],
+      maxBackgroundCommandsPerAgent: 3,
+      blockedCommands: ['rm -rf'],
+    });
+  });
+
+  test('fallbacks are applied only when neither global nor per-agent sets the field', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    const effective = tool.getEffectiveConfig({ toolConfig: { } }, {
+      maxFileSize: 10_000,
+      allowedCommands: ['SHOULD NOT WIN'],
+    });
+    expect(effective.allowedCommands).toEqual(['git']);    // global wins over fallback
+    expect(effective.maxFileSize).toBe(10_000);            // fallback fills the gap
+  });
+
+  test('malformed toolConfig (array) is ignored', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    const effective = tool.getEffectiveConfig({ toolConfig: ['not', 'an', 'object'] });
+    expect(effective).toEqual({ allowedCommands: ['git'] });
+  });
+
+  test('malformed toolConfig (primitive) is ignored', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig({ toolConfig: 'bogus' })).toEqual({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig({ toolConfig: 42 })).toEqual({ allowedCommands: ['git'] });
+  });
+
+  test('agents with empty toolConfig get plain global config', () => {
+    const tool = makeTool({ allowedCommands: ['git'] });
+    expect(tool.getEffectiveConfig({ toolConfig: {} })).toEqual({ allowedCommands: ['git'] });
+  });
+});