agentsys 5.0.2 → 5.1.0

package/plugins/debate/lib/perf/optimization-runner.js

@@ -0,0 +1,79 @@
+/**
+ * Optimization runner for /perf experiments.
+ *
+ * @module lib/perf/optimization-runner
+ */
+
+const { runBenchmark, runBenchmarkSeries, DEFAULT_MIN_DURATION } = require('./benchmark-runner');
+const { compareBaselines } = require('./baseline-comparator');
+const { isWorkingTreeClean } = require('./checkpoint');
+
+/**
+ * Run a single optimization experiment with two benchmark runs.
+ * NOTE: This helper does not modify code; it assumes the change was applied externally.
+ *
+ * @param {object} options
+ * @param {string} options.command
+ * @param {string} options.changeSummary
+ * @param {number} [options.duration]
+ * @param {number} [options.minDuration]
+ * @param {number} [options.runs]
+ * @param {string} [options.aggregate]
+ * @param {object} [options.env]
+ * @returns {{ baseline: object, experiment: object, delta: object, verdict: string, change: string }}
+ */
+function runOptimizationExperiment(options) {
+  const { command, changeSummary, duration, minDuration, runs, aggregate, env } = options || {};
+
+  if (!command || typeof command !== 'string') {
+    throw new Error('command must be a non-empty string');
+  }
+  if (!changeSummary || typeof changeSummary !== 'string') {
+    throw new Error('changeSummary must be a non-empty string');
+  }
+
+  const shouldCheckClean = options?.requireClean !== false && process.env.PERF_ALLOW_DIRTY !== '1';
+  if (shouldCheckClean && !isWorkingTreeClean()) {
+    throw new Error('working tree is dirty before experiment');
+  }
+
+  const baselineEnv = { ...env, PERF_EXPERIMENT: '0' };
+  const experimentEnv = { ...env, PERF_EXPERIMENT: '1' };
+  const seriesOptions = {
+    duration: duration ?? DEFAULT_MIN_DURATION,
+    minDuration,
+    runs,
+    aggregate
+  };
+
+  const baselineRun = runBenchmarkSeries(command, { ...seriesOptions, env: baselineEnv });
+
+  // NOTE: Caller is responsible for applying the experiment change here.
+  // Warm up the system (caches/JIT) before capturing experiment metrics.
+  const runMode = runs && runs > 1 ? 'oneshot' : 'duration';
+  runBenchmark(command, {
+    duration: duration ?? DEFAULT_MIN_DURATION,
+    minDuration,
+    env: experimentEnv,
+    runMode,
+    setDurationEnv: runMode !== 'oneshot'
+  });
+  const experimentRun = runBenchmarkSeries(command, { ...seriesOptions, env: experimentEnv });
+
+  const delta = compareBaselines(
+    { metrics: baselineRun.metrics },
+    { metrics: experimentRun.metrics }
+  );
+
+  return {
+    change: changeSummary,
+    baseline: { metrics: baselineRun.metrics },
+    experiment: { metrics: experimentRun.metrics },
+    delta,
+    verdict: 'inconclusive'
+  };
+}
+
+module.exports = {
+  runOptimizationExperiment
+};

package/plugins/debate/lib/perf/profilers/go.js

@@ -0,0 +1,22 @@
+/**
+ * Go pprof helper.
+ *
+ * @module lib/perf/profilers/go
+ */
+
+module.exports = {
+  id: 'pprof',
+  tool: 'pprof',
+  buildCommand(options = {}) {
+    const command = options.command || 'go test';
+    const output = options.output || 'cpu.pprof';
+    return `${command} -cpuprofile=${output}`;
+  },
+  parseOutput() {
+    return {
+      tool: 'pprof',
+      hotspots: [],
+      artifacts: []
+    };
+  }
+};

package/plugins/debate/lib/perf/profilers/index.js

@@ -0,0 +1,46 @@
+/**
+ * Profilers registry for /perf.
+ *
+ * @module lib/perf/profilers
+ */
+
+const fs = require('fs');
+const path = require('path');
+const cliEnhancers = require('../../patterns/cli-enhancers');
+const nodeProfiler = require('./node');
+const pythonProfiler = require('./python');
+const goProfiler = require('./go');
+const rustProfiler = require('./rust');
+const javaProfiler = require('./java');
+
+function hasJavaIndicators(repoPath) {
+  const indicators = ['pom.xml', 'build.gradle', 'build.gradle.kts'];
+  return indicators.some((file) => fs.existsSync(path.join(repoPath, file)));
+}
+
+function selectProfiler(repoPath = process.cwd()) {
+  const languages = cliEnhancers.detectProjectLanguages(repoPath);
+
+  if (hasJavaIndicators(repoPath)) return javaProfiler;
+  if (languages.includes('typescript') || languages.includes('javascript')) return nodeProfiler;
+  if (languages.includes('go')) return goProfiler;
+  if (languages.includes('python')) return pythonProfiler;
+  if (languages.includes('rust')) return rustProfiler;
+
+  return nodeProfiler;
+}
+
+function listAvailable() {
+  return [
+    nodeProfiler.id,
+    javaProfiler.id,
+    pythonProfiler.id,
+    goProfiler.id,
+    rustProfiler.id
+  ];
+}
+
+module.exports = {
+  listAvailable,
+  selectProfiler
+};

package/plugins/debate/lib/perf/profilers/java.js

@@ -0,0 +1,23 @@
+/**
+ * Java JFR profiler helper.
+ *
+ * @module lib/perf/profilers/java
+ */
+
+module.exports = {
+  id: 'jfr',
+  tool: 'jfr',
+  buildCommand(options = {}) {
+    const command = options.command || 'java';
+    const output = options.output || 'profile.jfr';
+    const duration = options.duration || '60s';
+    return `${command} -XX:StartFlightRecording=duration=${duration},filename=${output}`;
+  },
+  parseOutput() {
+    return {
+      tool: 'jfr',
+      hotspots: [],
+      artifacts: []
+    };
+  }
+};

package/plugins/debate/lib/perf/profilers/node.js

@@ -0,0 +1,27 @@
+/**
+ * Node.js profiler helper.
+ *
+ * @module lib/perf/profilers/node
+ */
+
+module.exports = {
+  id: 'node',
+  tool: '--cpu-prof',
+  buildCommand(options = {}) {
+    const command = options.command || 'node';
+    const output = options.output || 'node.cpuprofile';
+    const trimmed = command.trim();
+    if (trimmed.startsWith('node ')) {
+      const rest = trimmed.slice(5);
+      return `node --cpu-prof --cpu-prof-name=${output} ${rest}`.trim();
+    }
+    return `${command} --cpu-prof --cpu-prof-name=${output}`.trim();
+  },
+  parseOutput() {
+    return {
+      tool: 'node',
+      hotspots: [],
+      artifacts: []
+    };
+  }
+};

package/plugins/debate/lib/perf/profilers/python.js

@@ -0,0 +1,23 @@
+/**
+ * Python cProfile helper.
+ *
+ * @module lib/perf/profilers/python
+ */
+
+module.exports = {
+  id: 'cprofile',
+  tool: 'cProfile',
+  buildCommand(options = {}) {
+    const command = options.command || 'python';
+    const target = options.target || '-m';
+    const output = options.output || 'profile.prof';
+    return `${command} -m cProfile -o ${output} ${target}`;
+  },
+  parseOutput() {
+    return {
+      tool: 'cprofile',
+      hotspots: [],
+      artifacts: []
+    };
+  }
+};

package/plugins/debate/lib/perf/profilers/rust.js

@@ -0,0 +1,23 @@
+/**
+ * Rust perf helper (Linux).
+ *
+ * @module lib/perf/profilers/rust
+ */
+
+module.exports = {
+  id: 'perf',
+  tool: 'perf',
+  buildCommand(options = {}) {
+    const command = options.command || 'perf record';
+    const output = options.output || 'perf.data';
+    const target = options.target || './target/release/app';
+    return `${command} -o ${output} ${target}`;
+  },
+  parseOutput() {
+    return {
+      tool: 'perf',
+      hotspots: [],
+      artifacts: []
+    };
+  }
+};

package/plugins/debate/lib/perf/profiling-runner.js

@@ -0,0 +1,75 @@
+/**
+ * Profiling execution helper.
+ *
+ * @module lib/perf/profiling-runner
+ */
+
+const { execFileSync } = require('child_process');
+const profilers = require('./profilers');
+const { parseCommand, resolveExecutableForPlatform } = require('../utils/command-parser');
+
+/**
+ * Run a profiling command and return artifacts/hotspots metadata.
+ * @param {object} options
+ * @param {string} [options.repoPath]
+ * @param {object} [options.profileOptions]
+ * @returns {{ ok: boolean, result?: object, error?: string }}
+ */
+function runProfiling(options = {}) {
+  const repoPath = options.repoPath || process.cwd();
+  const timeoutMs = Number.isFinite(options.timeoutMs)
+    ? Math.max(1, Math.floor(options.timeoutMs))
+    : null;
+  const profiler = profilers.selectProfiler(repoPath);
+
+  if (!profiler || typeof profiler.buildCommand !== 'function') {
+    return { ok: false, error: 'No profiler available' };
+  }
+
+  const command = profiler.buildCommand({
+    command: options.command,
+    output: options.output,
+    ...(options.profileOptions || {})
+  });
+  const parsedCommand = parseCommand(command, 'Profiling command');
+  const executable = resolveExecutableForPlatform(parsedCommand.executable);
+  const env = {
+    ...process.env,
+    ...(options.env || {})
+  };
+  try {
+    const execOptions = {
+      stdio: 'pipe',
+      env,
+      cwd: repoPath,
+      windowsHide: true
+    };
+    if (timeoutMs !== null) {
+      execOptions.timeout = timeoutMs;
+    }
+
+    execFileSync(executable, parsedCommand.args, execOptions);
+  } catch (error) {
+    const stderr = error.stderr ? String(error.stderr).trim() : '';
+    const stdout = error.stdout ? String(error.stdout).trim() : '';
+    const details = stderr || stdout || error.message;
+    return { ok: false, error: `Profiling command failed: ${details}` };
+  }
+
+  const parsed = typeof profiler.parseOutput === 'function'
+    ? profiler.parseOutput()
+    : { tool: profiler.id, hotspots: [], artifacts: [] };
+
+  const result = {
+    tool: profiler.id,
+    command: parsedCommand.display,
+    hotspots: parsed.hotspots || [],
+    artifacts: parsed.artifacts || []
+  };
+
+  return { ok: true, result };
+}
+
+module.exports = {
+  runProfiling
+};

package/plugins/debate/lib/perf/schemas.js

@@ -0,0 +1,140 @@
+/**
+ * Schema validation helpers for /perf.
+ *
+ * @module lib/perf/schemas
+ */
+
+const REQUIRED_INVESTIGATION_FIELDS = ['schemaVersion', 'id', 'status', 'phase', 'scenario'];
+const REQUIRED_BASELINE_FIELDS = ['version', 'recordedAt', 'metrics', 'command'];
+
+function isObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateInvestigationState(state) {
+  const errors = [];
+
+  if (!isObject(state)) {
+    return { ok: false, errors: ['state must be an object'] };
+  }
+
+  for (const field of REQUIRED_INVESTIGATION_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(state, field)) {
+      errors.push(`missing ${field}`);
+    }
+  }
+
+  if (typeof state.id !== 'string' || state.id.trim().length === 0) {
+    errors.push('id must be a non-empty string');
+  }
+
+  if (typeof state.phase !== 'string' || state.phase.trim().length === 0) {
+    errors.push('phase must be a non-empty string');
+  }
+
+  if (!isObject(state.scenario)) {
+    errors.push('scenario must be an object');
+  } else {
+    if (typeof state.scenario.description !== 'string') {
+      errors.push('scenario.description must be a string');
+    }
+    if (!Array.isArray(state.scenario.metrics)) {
+      errors.push('scenario.metrics must be an array');
+    }
+    if (typeof state.scenario.successCriteria !== 'string') {
+      errors.push('scenario.successCriteria must be a string');
+    }
+    if (state.scenario.scenarios != null) {
+      if (!Array.isArray(state.scenario.scenarios)) {
+        errors.push('scenario.scenarios must be an array when provided');
+      } else {
+        state.scenario.scenarios.forEach((scenario, index) => {
+          if (!isObject(scenario)) {
+            errors.push(`scenario.scenarios[${index}] must be an object`);
+            return;
+          }
+          if (typeof scenario.name !== 'string' || scenario.name.trim().length === 0) {
+            errors.push(`scenario.scenarios[${index}].name must be a non-empty string`);
+          }
+          if (scenario.params != null && !isObject(scenario.params)) {
+            errors.push(`scenario.scenarios[${index}].params must be an object when provided`);
+          }
+        });
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function validateBaseline(baseline) {
+  const errors = [];
+
+  if (!isObject(baseline)) {
+    return { ok: false, errors: ['baseline must be an object'] };
+  }
+
+  for (const field of REQUIRED_BASELINE_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(baseline, field)) {
+      errors.push(`missing ${field}`);
+    }
+  }
+
+  if (typeof baseline.version !== 'string' || baseline.version.trim().length === 0) {
+    errors.push('version must be a non-empty string');
+  }
+
+  if (typeof baseline.recordedAt !== 'string' || baseline.recordedAt.trim().length === 0) {
+    errors.push('recordedAt must be an ISO8601 string');
+  }
+
+  if (typeof baseline.command !== 'string' || baseline.command.trim().length === 0) {
+    errors.push('command must be a non-empty string');
+  }
+
+  if (!isObject(baseline.metrics)) {
+    errors.push('metrics must be an object');
+  } else {
+    if (baseline.metrics.scenarios != null) {
+      if (!isObject(baseline.metrics.scenarios)) {
+        errors.push('metrics.scenarios must be an object when provided');
+      } else {
+        for (const [scenarioName, scenarioMetrics] of Object.entries(baseline.metrics.scenarios)) {
+          if (!isObject(scenarioMetrics)) {
+            errors.push(`metrics.scenarios.${scenarioName} must be an object`);
+            continue;
+          }
+          for (const [key, value] of Object.entries(scenarioMetrics)) {
+            if (typeof value !== 'number' || Number.isNaN(value)) {
+              errors.push(`metric ${scenarioName}.${key} must be a number`);
+            }
+          }
+        }
+      }
+    } else {
+      for (const [key, value] of Object.entries(baseline.metrics)) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+          errors.push(`metric ${key} must be a number`);
+        }
+      }
+    }
+  }
+
+  if (baseline.env && !isObject(baseline.env)) {
+    errors.push('env must be an object when provided');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function assertValid(result, message) {
+  if (!result.ok) {
+    throw new Error(`${message}: ${result.errors.join(', ')}`);
+  }
+}
+
+module.exports = {
+  validateInvestigationState,
+  validateBaseline,
+  assertValid
+};