onbuzz 4.4.0 → 4.6.0

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

@@ -0,0 +1,324 @@
+/**
+ * Tests for the terminal command dedup module.
+ *
+ * Contract under test:
+ *   - Same agent + same command + STILL RUNNING → deny.
+ *   - Same agent + same command + PRIOR RUN ENDED → allow.
+ *   - Different agents, same command, both running → both allowed.
+ *   - force:true with NO prior denial → silently ignored (still denied
+ *     if duplicate; allowed if not). The "no first-call abuse" property.
+ *   - force:true AFTER a denial of the SAME command → allow + clear token.
+ *   - force:true after denial expires → ignored (must be re-denied).
+ *   - force:true after a denial of a DIFFERENT command → ignored.
+ *   - Whitespace + CRLF normalization.
+ *   - Per-agent config opt-out short-circuits the whole check.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  checkDedup, normalizeCommand, findRunningDuplicate, FORCE_TOKEN_TTL_MS,
+} from '../terminalDedup.js';
+import { TERMINAL_CONFIG } from '../../utilities/constants.js';
+
+const RUNNING = TERMINAL_CONFIG.STATES.RUNNING;
+const COMPLETED = TERMINAL_CONFIG.STATES.COMPLETED;
+const FAILED = TERMINAL_CONFIG.STATES.FAILED;
+
+function trackerWith(...entries) {
+  const m = new Map();
+  for (const e of entries) {
+    m.set(e.commandId, {
+      commandId:        e.commandId,
+      agentId:          e.agentId,
+      command:          e.command,
+      state:            e.state ?? RUNNING,
+      startTime:        e.startTime ?? new Date(Date.now() - 5000).toISOString(),
+      workingDirectory: e.workingDirectory ?? '/tmp',
+    });
+  }
+  return m;
+}
+
+describe('normalizeCommand', () => {
+  test('trims surrounding whitespace', () => {
+    expect(normalizeCommand('  npm test  ')).toBe('npm test');
+  });
+  test('normalizes CRLF to LF', () => {
+    expect(normalizeCommand('echo a\r\necho b')).toBe('echo a\necho b');
+  });
+  test('preserves internal whitespace', () => {
+    expect(normalizeCommand('npm  test')).toBe('npm  test');
+  });
+  test('non-string → empty string (defensive)', () => {
+    expect(normalizeCommand(42)).toBe('');
+    expect(normalizeCommand(null)).toBe('');
+    expect(normalizeCommand(undefined)).toBe('');
+  });
+});
+
+describe('findRunningDuplicate', () => {
+  test('matches same agent + same command + RUNNING', () => {
+    const t = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    expect(findRunningDuplicate(t, 'a', 'npm test')?.commandId).toBe('c1');
+  });
+  test('does NOT match a different agent', () => {
+    const t = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    expect(findRunningDuplicate(t, 'b', 'npm test')).toBeNull();
+  });
+  test('does NOT match a finished command (COMPLETED)', () => {
+    const t = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test', state: COMPLETED });
+    expect(findRunningDuplicate(t, 'a', 'npm test')).toBeNull();
+  });
+  test('does NOT match a finished command (FAILED)', () => {
+    const t = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test', state: FAILED });
+    expect(findRunningDuplicate(t, 'a', 'npm test')).toBeNull();
+  });
+  test('matches across whitespace differences (normalization)', () => {
+    const t = trackerWith({ commandId: 'c1', agentId: 'a', command: '  npm test  ' });
+    expect(findRunningDuplicate(t, 'a', 'npm test')?.commandId).toBe('c1');
+  });
+});
+
+describe('checkDedup — basic allow/deny', () => {
+  test('no duplicate running → allow', () => {
+    const r = checkDedup({
+      commandTracker: trackerWith(),
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'npm test',
+    });
+    expect(r.allow).toBe(true);
+  });
+
+  test('duplicate running for same agent → deny + records token', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const tokens = new Map();
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm test',
+    });
+    expect(r.allow).toBe(false);
+    expect(r.reason).toBe('duplicate-running');
+    expect(r.hint).toMatch(/force:true/);
+    expect(r.status.commandId).toBe('c1');
+    expect(r.status.command).toBe('npm test');
+    expect(r.status.state).toBe(RUNNING);
+    expect(r.status.elapsedSec).toBeGreaterThanOrEqual(0);
+    // Token recorded for THIS agent + command
+    expect(tokens.get('a')).toMatchObject({ command: 'npm test' });
+  });
+
+  test('different agents same command → both allowed', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const tokens = new Map();
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'b',          // different agent
+      command: 'npm test',
+    });
+    expect(r.allow).toBe(true);
+    expect(tokens.size).toBe(0);
+  });
+
+  test('completed prior run → allowed (no-op)', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test', state: COMPLETED });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'npm test',
+    });
+    expect(r.allow).toBe(true);
+  });
+});
+
+describe('checkDedup — force:true semantics (the abuse-prevention property)', () => {
+  test('force:true with NO prior denial → still denied (record token)', () => {
+    // First-ever call with force:true must NOT bypass anything. The flag
+    // is only meaningful as a response to a denial.
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const tokens = new Map();
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm test',
+      force: true,
+    });
+    expect(r.allow).toBe(false);
+    expect(tokens.has('a')).toBe(true);
+  });
+
+  test('force:true with NO duplicate running → allowed (force is silently ignored)', () => {
+    // Important: agents that always pass force should behave identically
+    // to agents that never pass it when there is no conflict. Otherwise
+    // force would become "permission to skip dedup permanently."
+    const tokens = new Map();
+    const r = checkDedup({
+      commandTracker: trackerWith(),
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm test',
+      force: true,
+    });
+    expect(r.allow).toBe(true);
+    expect(tokens.size).toBe(0);
+  });
+
+  test('force:true AFTER a matching denial → allowed + token consumed', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const tokens = new Map();
+    // First call: denied.
+    checkDedup({ commandTracker: tracker, lastDeniedExec: tokens, agentId: 'a', command: 'npm test' });
+    expect(tokens.has('a')).toBe(true);
+    // Second call WITH force: allowed, token consumed.
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm test',
+      force: true,
+    });
+    expect(r.allow).toBe(true);
+    expect(tokens.has('a')).toBe(false);    // single-use
+  });
+
+  test('force:true after denial expires → still denied (token TTL exceeded)', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const t0 = 1_000_000;
+    const tokens = new Map();
+    checkDedup({ commandTracker: tracker, lastDeniedExec: tokens, agentId: 'a', command: 'npm test', now: t0 });
+    // Force long after the TTL expired.
+    const tLate = t0 + FORCE_TOKEN_TTL_MS + 1;
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm test',
+      force: true,
+      now: tLate,
+    });
+    expect(r.allow).toBe(false);
+  });
+
+  test('force:true after denial of a DIFFERENT command → ignored (denied as fresh)', () => {
+    // Agent was denied for "npm test" earlier. Now sends force:true with
+    // "npm build" — different command. The token doesn't apply; force
+    // is ignored; npm-build is denied because it's also already running.
+    const tracker = trackerWith(
+      { commandId: 'c1', agentId: 'a', command: 'npm test' },
+      { commandId: 'c2', agentId: 'a', command: 'npm build' },
+    );
+    const tokens = new Map();
+    checkDedup({ commandTracker: tracker, lastDeniedExec: tokens, agentId: 'a', command: 'npm test' });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: tokens,
+      agentId: 'a',
+      command: 'npm build',     // different command
+      force: true,
+    });
+    expect(r.allow).toBe(false);   // force not honored across commands
+  });
+
+  test('the spam-force exploit: force on every single call doesn\'t bypass dedup', () => {
+    // Adversarial agent: passes force:true on EVERY call. Confirm that
+    // dedup still kicks in on duplicates and the agent can't sneak past.
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'rm -rf node_modules' });
+    const tokens = new Map();
+    // First call (with force) — should be denied because no prior denial.
+    let r = checkDedup({ commandTracker: tracker, lastDeniedExec: tokens, agentId: 'a', command: 'rm -rf node_modules', force: true });
+    expect(r.allow).toBe(false);
+    // Second call (still with force) — token EXISTS now, so this one IS allowed.
+    // That's the legitimate retry path. The exploit fails on the first call.
+    r = checkDedup({ commandTracker: tracker, lastDeniedExec: tokens, agentId: 'a', command: 'rm -rf node_modules', force: true });
+    expect(r.allow).toBe(true);
+    // Critical: the agent had to be denied at least once before force worked.
+    // Spamming force from the start gains nothing on the first call.
+  });
+});
+
+describe('checkDedup — config opt-out', () => {
+  test('config.denyDuplicateConcurrentCommands === false → always allow', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'npm test',
+      config: { denyDuplicateConcurrentCommands: false },
+    });
+    expect(r.allow).toBe(true);
+  });
+
+  test('config.denyDuplicateConcurrentCommands === true (default) → enforced', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'npm test',
+      config: { denyDuplicateConcurrentCommands: true },
+    });
+    expect(r.allow).toBe(false);
+  });
+
+  test('config absent → enforced (default behavior)', () => {
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'npm test' });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'npm test',
+    });
+    expect(r.allow).toBe(false);
+  });
+});
+
+describe('checkDedup — defensive guards', () => {
+  test('missing agentId → allow', () => {
+    expect(checkDedup({
+      commandTracker: trackerWith({ commandId: 'c1', agentId: 'a', command: 'x' }),
+      lastDeniedExec: new Map(),
+      agentId: '',
+      command: 'x',
+    }).allow).toBe(true);
+  });
+
+  test('empty/whitespace command → allow (no fingerprint to match)', () => {
+    expect(checkDedup({
+      commandTracker: trackerWith({ commandId: 'c1', agentId: 'a', command: '' }),
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: '   ',
+    }).allow).toBe(true);
+  });
+});
+
+describe('time-varying commands naturally pass dedup', () => {
+  test('commands with $(date) substitutions get unique strings → not deduped', () => {
+    // `echo $(date)` — the command STRING itself differs by timestamp
+    // when the agent generates them; even if it doesn't, our exact-match
+    // policy means the agent has to deliberately re-issue the same
+    // string. This is the documented behavior, not a bug.
+    const tracker = trackerWith({ commandId: 'c1', agentId: 'a', command: 'echo $(date)' });
+    const r = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'echo $(date)',     // exact-match — IS deduped
+    });
+    expect(r.allow).toBe(false);   // exact match → deduped
+    // But a different invocation:
+    const r2 = checkDedup({
+      commandTracker: tracker,
+      lastDeniedExec: new Map(),
+      agentId: 'a',
+      command: 'echo "now: $(date)"',
+    });
+    expect(r2.allow).toBe(true);   // different string → allowed
+  });
+});

package/src/tools/imageFormat.js

@@ -0,0 +1,249 @@
+/**
+ * Image format helpers for the imageTool.
+ *
+ * The image providers (Flux, GPT-Image-1.5, etc.) typically return PNG
+ * bytes, but our default output is now WebP — meaning we need real
+ * format conversion before saving to disk. This module owns:
+ *
+ *   - Format resolution (what target format does the user want?)
+ *   - Magic-byte detection (what format ARE the provider's bytes?)
+ *   - Transcoding via sharp, with a graceful fallback if sharp fails
+ *     to load (e.g. weird platform without prebuilt binaries — we'd
+ *     rather save the original bytes than fail the whole render)
+ *   - Filename ↔ format mapping
+ *
+ * Pure-ish: `transcodeIfNeeded` is the only function with side effects
+ * (calls sharp, which spins up native code). Everything else is sync
+ * + side-effect-free → easy to unit test.
+ *
+ * Why a separate file: keeps imageTool.js focused on orchestration and
+ * makes the format logic testable WITHOUT mocking the entire tool +
+ * its provider clients.
+ */
+
+import path from 'path';
+
+/** Canonical formats we read/write. */
+export const SUPPORTED_FORMATS = Object.freeze(['png', 'jpeg', 'webp']);
+
+/** Default output when the agent doesn't specify. */
+export const DEFAULT_FORMAT = 'webp';
+
+/**
+ * Map an extension or alias to a canonical format name. Returns null
+ * if the input doesn't map cleanly.
+ *
+ * - 'jpg' / 'jpeg' / '.jpg' / '.jpeg' → 'jpeg'
+ * - 'png' / '.png' → 'png'
+ * - 'webp' / '.webp' → 'webp'
+ */
+export function normalizeFormat(input) {
+  if (typeof input !== 'string') return null;
+  const lower = input.trim().toLowerCase().replace(/^\./, '');
+  if (lower === 'jpg' || lower === 'jpeg') return 'jpeg';
+  if (lower === 'png')  return 'png';
+  if (lower === 'webp') return 'webp';
+  return null;
+}
+
+/**
+ * The on-disk extension for a canonical format. JPEG → "jpg" (the more
+ * common file extension); PNG → "png"; WebP → "webp".
+ */
+export function extensionFor(format) {
+  if (format === 'jpeg') return 'jpg';
+  if (format === 'png')  return 'png';
+  if (format === 'webp') return 'webp';
+  return 'webp';   // fallback — should never hit if callers respect SUPPORTED_FORMATS
+}
+
+/**
+ * Decide what target format to write, given the agent's request.
+ *
+ * Priority:
+ *   1. outputPath extension (e.g. "foo.png" forces PNG, "foo.jpg" → JPEG)
+ *   2. outputType field (explicit format request)
+ *   3. DEFAULT_FORMAT ('webp')
+ *
+ * @param {object} args
+ * @param {string} [args.outputPath]  May or may not have an extension.
+ * @param {string} [args.outputType]  e.g. 'png' | 'webp' | 'jpg' — agent-friendly.
+ * @returns {{ format: 'png'|'jpeg'|'webp', source: 'extension'|'outputType'|'default' }}
+ */
+export function resolveTargetFormat({ outputPath, outputType } = {}) {
+  if (typeof outputPath === 'string' && outputPath.length > 0) {
+    const ext = path.extname(outputPath);
+    const fmt = normalizeFormat(ext);
+    if (fmt) return { format: fmt, source: 'extension' };
+  }
+  if (outputType !== undefined && outputType !== null) {
+    const fmt = normalizeFormat(outputType);
+    if (fmt) return { format: fmt, source: 'outputType' };
+  }
+  return { format: DEFAULT_FORMAT, source: 'default' };
+}
+
+/**
+ * Sniff the encoded format of a buffer by inspecting the first few bytes.
+ * Returns null when nothing matches — caller then assumes "unknown" and
+ * MAY skip transcoding (safer than transcoding bytes we don't recognize).
+ *
+ * Magic-byte references:
+ *   PNG  : 89 50 4E 47 0D 0A 1A 0A
+ *   JPEG : FF D8 FF
+ *   WebP : "RIFF" .... "WEBP"
+ *   GIF  : "GIF87a" or "GIF89a"  (we don't transcode but recognize)
+ *   BMP  : 42 4D
+ */
+export function detectFormatFromBytes(buffer) {
+  if (!buffer || typeof buffer.length !== 'number' || buffer.length < 12) return null;
+  if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) return 'png';
+  if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) return 'jpeg';
+  if (
+    buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+    buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50
+  ) return 'webp';
+  if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) return 'gif';
+  if (buffer[0] === 0x42 && buffer[1] === 0x4D) return 'bmp';
+  return null;
+}
+
+/**
+ * Lazy sharp loader. Caches the module after first import; re-attempts
+ * on null cache so a transient failure (e.g. concurrent install) doesn't
+ * permanently disable transcoding.
+ *
+ * Wrapped in try/catch — if the native module fails to load on the
+ * host (rare but possible on uncommon platforms), we report null and
+ * the caller falls back to writing raw provider bytes.
+ */
+let _sharp = null;
+let _sharpLoadAttempted = false;
+let _sharpLoadError = null;
+async function _getSharp() {
+  if (_sharp) return _sharp;
+  if (_sharpLoadAttempted && _sharpLoadError) {
+    // Retry once after a small grace period rather than caching the
+    // failure forever — node module resolution can race during install.
+  }
+  try {
+    const mod = await import('sharp');
+    _sharp = mod.default || mod;
+    _sharpLoadError = null;
+    return _sharp;
+  } catch (err) {
+    _sharpLoadAttempted = true;
+    _sharpLoadError = err;
+    return null;
+  }
+}
+
+/** Test-only — clear sharp cache so a subsequent call re-imports. */
+export function _resetSharpCacheForTests() {
+  _sharp = null;
+  _sharpLoadAttempted = false;
+  _sharpLoadError = null;
+}
+
+/**
+ * Transcode `buffer` to `targetFormat`. Returns a result describing
+ * what happened so the caller can log + report:
+ *
+ *   { buffer: <out>, transcoded: true,  inputFormat: 'png', outputFormat: 'webp' }
+ *     — sharp converted the bytes
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'webp', outputFormat: 'webp', reason: 'already-target' }
+ *     — input format already matches target; no work
+ *   { buffer: <in>,  transcoded: false, inputFormat: null,   outputFormat: 'webp', reason: 'unknown-input' }
+ *     — couldn't sniff input; safer to write bytes as-is
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'png',  outputFormat: 'webp', reason: 'sharp-unavailable', error }
+ *     — sharp couldn't load; fall back to raw bytes
+ *   { buffer: <in>,  transcoded: false, inputFormat: 'png',  outputFormat: 'webp', reason: 'transcode-failed', error }
+ *     — sharp threw mid-transcode
+ *
+ * @param {Buffer} buffer
+ * @param {'png'|'jpeg'|'webp'} targetFormat
+ * @param {object} [opts]
+ * @param {number} [opts.quality=85]   For JPEG/WebP. PNG ignores it.
+ * @param {object} [opts.logger]
+ */
+export async function transcodeIfNeeded(buffer, targetFormat, opts = {}) {
+  const quality = Number.isFinite(opts.quality) ? opts.quality : 85;
+  const logger  = opts.logger || null;
+  const inputFormat = detectFormatFromBytes(buffer);
+
+  // Already in the desired format — no work, no quality loss.
+  if (inputFormat && inputFormat === targetFormat) {
+    return { buffer, transcoded: false, inputFormat, outputFormat: targetFormat, reason: 'already-target' };
+  }
+  if (!inputFormat) {
+    logger?.warn?.('[imageFormat] could not sniff input format; writing bytes as-is', { targetFormat });
+    return { buffer, transcoded: false, inputFormat: null, outputFormat: targetFormat, reason: 'unknown-input' };
+  }
+  // GIF / BMP — sharp can read these but transcoding GIFs to webp
+  // animation requires more thought; for now write bytes as-is.
+  if (inputFormat === 'gif' || inputFormat === 'bmp') {
+    return { buffer, transcoded: false, inputFormat, outputFormat: targetFormat, reason: 'unsupported-input' };
+  }
+
+  const sharpFn = await _getSharp();
+  if (!sharpFn) {
+    logger?.warn?.('[imageFormat] sharp not available; writing bytes as-is', {
+      targetFormat,
+      error: _sharpLoadError?.message,
+    });
+    return {
+      buffer,
+      transcoded: false,
+      inputFormat,
+      outputFormat: targetFormat,
+      reason: 'sharp-unavailable',
+      error: _sharpLoadError,
+    };
+  }
+
+  try {
+    let pipeline = sharpFn(buffer);
+    if (targetFormat === 'webp') pipeline = pipeline.webp({ quality });
+    else if (targetFormat === 'jpeg') pipeline = pipeline.jpeg({ quality });
+    else if (targetFormat === 'png')  pipeline = pipeline.png();
+    const out = await pipeline.toBuffer();
+    return { buffer: out, transcoded: true, inputFormat, outputFormat: targetFormat };
+  } catch (err) {
+    logger?.warn?.('[imageFormat] transcode failed; writing original bytes as-is', {
+      inputFormat, targetFormat, error: err?.message,
+    });
+    return {
+      buffer,
+      transcoded: false,
+      inputFormat,
+      outputFormat: targetFormat,
+      reason: 'transcode-failed',
+      error: err,
+    };
+  }
+}
+
+/**
+ * Convenience: if the user-supplied outputPath has no extension,
+ * append the target format's extension. Otherwise return as-is.
+ * (The agent might pass `images/foo` without an extension — we'd
+ * normally reject, but for the auto-extension case we just append.)
+ */
+export function ensureExtension(outputPath, targetFormat) {
+  if (!outputPath || typeof outputPath !== 'string') return outputPath;
+  const ext = path.extname(outputPath);
+  if (ext && normalizeFormat(ext)) return outputPath;
+  return `${outputPath}.${extensionFor(targetFormat)}`;
+}
+
+export default {
+  SUPPORTED_FORMATS,
+  DEFAULT_FORMAT,
+  normalizeFormat,
+  extensionFor,
+  resolveTargetFormat,
+  detectFormatFromBytes,
+  transcodeIfNeeded,
+  ensureExtension,
+  _resetSharpCacheForTests,
+};