onbuzz 4.3.0 → 4.5.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/platformControl/ancestry.js

@@ -0,0 +1,85 @@
+/**
+ * Ancestry checks for platformControlTool's hard rules.
+ *
+ * Each agent record carries `createdBy: <agentId> | null`. An agent
+ * created via this tool inherits the caller's id as its parent;
+ * agents created via the UI have `createdBy: null` (no parent).
+ *
+ * The hard rule "no descendant modifies an ancestor" requires walking
+ * UP the caller's chain looking for the target. Done as a pure function
+ * over an `(id) → agent` lookup so it's testable without an agent pool.
+ *
+ * Defenses:
+ *   - Cycle detection (visited set). The data model isn't supposed to
+ *     have cycles, but a corrupt state file shouldn't crash the tool.
+ *   - Depth cap (CHAIN_MAX). Hard ceiling on chain walks; if a real
+ *     deployment ever sees a chain this deep, we have other problems.
+ *   - Missing-agent tolerance. If the lookup returns null mid-walk we
+ *     stop cleanly — orphaned chains are treated as "no further parent".
+ */
+
+export const CHAIN_MAX = 100;
+
+/**
+ * Returns true if `targetId` appears in `callerId`'s ancestor chain.
+ * Self is NOT counted as an ancestor here — the self-modify rule is a
+ * separate check at the call site (`targetId === callerId`).
+ *
+ * @param {string} callerId
+ * @param {string} targetId
+ * @param {(id: string) => ({ id?: string, createdBy?: string|null }|null|undefined)} getAgent
+ * @returns {boolean}
+ */
+export function isAncestor(callerId, targetId, getAgent) {
+  if (!callerId || !targetId) return false;
+  if (callerId === targetId) return false;        // self isn't an ancestor in this sense
+  if (typeof getAgent !== 'function') return false;
+
+  const visited = new Set([callerId]);
+  let cursorId = callerId;
+  for (let i = 0; i < CHAIN_MAX; i++) {
+    const cursor = getAgent(cursorId);
+    if (!cursor) return false;
+    const parentId = cursor.createdBy;
+    if (!parentId) return false;
+    if (parentId === targetId) return true;
+    if (visited.has(parentId)) return false;      // cycle — bail
+    visited.add(parentId);
+    cursorId = parentId;
+  }
+  return false;
+}
+
+/**
+ * Convenience: would `callerId` be blocked by the hard rules from
+ * mutating `targetId`? Combines self-modify + ancestor-modify checks.
+ */
+export function isProtectedFromCaller(callerId, targetId, getAgent) {
+  if (!callerId || !targetId) return false;
+  if (callerId === targetId) return true;          // self-modify forbidden
+  return isAncestor(callerId, targetId, getAgent);
+}
+
+/**
+ * Build a `getAgent` lookup from an iterable of agents (Map, array,
+ * agentPool.getAllAgents() result). Used by the tool when it has the
+ * full set in hand and doesn't want to do async lookups inside the
+ * pure ancestry walk.
+ */
+export function makeAgentLookup(agents) {
+  if (!agents) return () => null;
+  if (typeof agents.get === 'function' && typeof agents.has === 'function') {
+    return (id) => agents.get(id) || null;
+  }
+  if (Array.isArray(agents)) {
+    const map = new Map(agents.filter(a => a && a.id).map(a => [a.id, a]));
+    return (id) => map.get(id) || null;
+  }
+  // Plain object
+  if (typeof agents === 'object') {
+    return (id) => agents[id] || null;
+  }
+  return () => null;
+}
+
+export default { CHAIN_MAX, isAncestor, isProtectedFromCaller, makeAgentLookup };

package/src/tools/platformControl/cascadeService.js

@@ -0,0 +1,146 @@
+/**
+ * Cascade-on-delete service for platformControlTool.
+ *
+ * Independent of the tool's permission logic — that gates whether a
+ * delete is allowed; THIS module does the actual cleanup once the
+ * delete is approved. Modular + testable: every dependency is injected,
+ * each step is independently observable, and failures in earlier steps
+ * don't abort later ones unless `strict:true`.
+ *
+ * Why this lives in its own file:
+ *   - The tool's dispatch is already long; embedding the cleanup choreography
+ *     would obscure the permission logic.
+ *   - The cleanup needs to be testable WITHOUT spinning up real services
+ *     (real ScheduleService writes files, real AgentPool spawns processes).
+ *   - Future deletions (delete-team-with-cascade, delete-agent-with-flow-cleanup)
+ *     can plug new steps in here without touching the tool dispatcher.
+ *
+ * Step order for cascadeDeleteAgent — in this exact order, on purpose:
+ *   1. Schedules: deleted FIRST so they can't fire mid-cleanup and re-spawn work.
+ *   2. Memories: small file deletion; if it fails, agent state is still cleanable.
+ *   3. Team memberships: removes the agentId from every team that contains it.
+ *   4. The agent itself (agentPool.deleteAgent): handles attachments, terminal
+ *      processes, visual editor, persistent state — all already implemented there.
+ *
+ * Each step yields an entry on the report. The caller surfaces this to
+ * the agent making the call so they know what happened.
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.agentId
+ * @param {object} args.scheduleService   — `listSchedules`, `deleteSchedule`
+ * @param {object} args.memoryService     — `deleteMemoryFile(agentId)`
+ * @param {object} args.stateManager      — `getAllTeams`, `removeAgentFromTeam`
+ * @param {object} args.agentPool         — `deleteAgent(agentId)`
+ * @param {object} [args.logger]          — { warn(msg, meta) }
+ * @param {boolean} [args.strict=false]   — abort on first failure
+ * @returns {Promise<{
+ *   schedulesDeleted: number,
+ *   memoriesCleaned: boolean,
+ *   teamsLeft: string[],
+ *   agentDeleted: boolean,
+ *   errors: Array<{ step: string, error: string }>,
+ * }>}
+ */
+export async function cascadeDeleteAgent({
+  agentId,
+  scheduleService,
+  memoryService,
+  stateManager,
+  agentPool,
+  logger,
+  strict = false,
+}) {
+  if (!agentId) throw new Error('cascadeDeleteAgent: agentId is required');
+
+  const report = {
+    schedulesDeleted: 0,
+    memoriesCleaned: false,
+    teamsLeft: [],
+    agentDeleted: false,
+    errors: [],
+  };
+  const log = logger || { warn() {} };
+
+  // Wrapper so each step is independently fail-tolerant. In strict mode,
+  // the first failure throws and skips the rest.
+  const step = async (name, fn) => {
+    try { await fn(); }
+    catch (err) {
+      const msg = err?.message || String(err);
+      report.errors.push({ step: name, error: msg });
+      log.warn(`[cascadeDeleteAgent] step "${name}" failed`, { agentId, error: msg });
+      if (strict) throw err;
+    }
+  };
+
+  // 1. Schedules
+  await step('schedules', async () => {
+    if (!scheduleService) return;
+    const all = typeof scheduleService.listSchedules === 'function'
+      ? scheduleService.listSchedules() : [];
+    const owned = (Array.isArray(all) ? all : []).filter(s =>
+      s && s.targetType === 'agent' && s.targetId === agentId);
+    for (const s of owned) {
+      await scheduleService.deleteSchedule(s.id);
+      report.schedulesDeleted++;
+    }
+  });
+
+  // 2. Memory file
+  await step('memories', async () => {
+    if (!memoryService || typeof memoryService.deleteMemoryFile !== 'function') return;
+    const ok = await memoryService.deleteMemoryFile(agentId);
+    report.memoriesCleaned = !!ok;
+  });
+
+  // 3. Team memberships
+  await step('teams', async () => {
+    if (!stateManager || typeof stateManager.getAllTeams !== 'function') return;
+    const teams = await stateManager.getAllTeams();
+    const containing = (Array.isArray(teams) ? teams : []).filter(t =>
+      t && Array.isArray(t.memberAgentIds) && t.memberAgentIds.includes(agentId));
+    for (const t of containing) {
+      await stateManager.removeAgentFromTeam(t.id, agentId);
+      report.teamsLeft.push(t.id);
+    }
+  });
+
+  // 4. The agent record itself.
+  await step('agentPool', async () => {
+    if (!agentPool || typeof agentPool.deleteAgent !== 'function') {
+      throw new Error('agentPool.deleteAgent unavailable');
+    }
+    await agentPool.deleteAgent(agentId);
+    report.agentDeleted = true;
+  });
+
+  return report;
+}
+
+/**
+ * Team delete is much simpler — `stateManager.deleteTeam` already
+ * removes the team record (and the memberships die with it because
+ * they live INSIDE the team object, not in a separate join table).
+ *
+ * Kept here for symmetry and to centralize "what does cascade-delete
+ * mean per resource type" in one file.
+ */
+export async function cascadeDeleteTeam({ teamId, stateManager, logger }) {
+  if (!teamId) throw new Error('cascadeDeleteTeam: teamId is required');
+  const log = logger || { warn() {} };
+  const report = { teamDeleted: false, errors: [] };
+  try {
+    await stateManager.deleteTeam(teamId);
+    report.teamDeleted = true;
+  } catch (err) {
+    const msg = err?.message || String(err);
+    report.errors.push({ step: 'team', error: msg });
+    log.warn('[cascadeDeleteTeam] failed', { teamId, error: msg });
+    throw err;       // unlike agent cascade, team-delete is a single op; rethrow.
+  }
+  return report;
+}
+
+export default { cascadeDeleteAgent, cascadeDeleteTeam };