agentsys 5.0.3 → 5.1.0

package/plugins/debate/lib/perf/breaking-point-finder.js

@@ -0,0 +1,52 @@
+/**
+ * Binary search helper for breaking point discovery.
+ *
+ * @module lib/perf/breaking-point-finder
+ */
+
+/**
+ * Find breaking point using binary search.
+ * The runner should return { ok: boolean, data?: any }.
+ *
+ * @param {object} options
+ * @param {number} options.min
+ * @param {number} options.max
+ * @param {(value:number)=>Promise<{ok:boolean,data?:any}>} options.runner
+ * @returns {Promise<{breakingPoint:number|null, attempts:number, history:Array}>}
+ */
+async function findBreakingPoint({ min, max, runner }) {
+  if (typeof min !== 'number' || typeof max !== 'number') {
+    throw new Error('min and max must be numbers');
+  }
+  if (typeof runner !== 'function') {
+    throw new Error('runner must be a function');
+  }
+
+  let low = min;
+  let high = max;
+  let breakingPoint = null;
+  const history = [];
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const result = await runner(mid);
+    history.push({ value: mid, ok: result.ok });
+
+    if (result.ok) {
+      low = mid + 1;
+    } else {
+      breakingPoint = mid;
+      high = mid - 1;
+    }
+  }
+
+  return {
+    breakingPoint,
+    attempts: history.length,
+    history
+  };
+}
+
+module.exports = {
+  findBreakingPoint
+};

package/plugins/debate/lib/perf/breaking-point-runner.js

@@ -0,0 +1,60 @@
+/**
+ * Breaking point runner wrapper for /perf.
+ *
+ * @module lib/perf/breaking-point-runner
+ */
+
+const { runBenchmark, parseMetrics, BINARY_SEARCH_MIN_DURATION } = require('./benchmark-runner');
+const { findBreakingPoint } = require('./breaking-point-finder');
+
+/**
+ * Run a binary search to find the breaking point for a numeric parameter.
+ * The benchmark command should accept the value via an env var.
+ *
+ * @param {object} options
+ * @param {string} options.command
+ * @param {string} options.paramEnv
+ * @param {number} options.min
+ * @param {number} options.max
+ * @returns {Promise<{breakingPoint:number|null, attempts:number, history:Array}>}
+ */
+async function runBreakingPointSearch(options) {
+  const { command, paramEnv, min, max } = options || {};
+
+  if (!command || typeof command !== 'string') {
+    throw new Error('command must be a non-empty string');
+  }
+  if (!paramEnv || typeof paramEnv !== 'string') {
+    throw new Error('paramEnv must be a non-empty string');
+  }
+  if (typeof min !== 'number' || typeof max !== 'number') {
+    throw new Error('min and max must be numbers');
+  }
+
+  const runner = async (value) => {
+    try {
+      const result = runBenchmark(command, {
+        mode: 'binary-search',
+        duration: BINARY_SEARCH_MIN_DURATION,
+        env: {
+          [paramEnv]: String(value)
+        }
+      });
+
+      const parsed = parseMetrics(result.output);
+      if (!parsed.ok) {
+        return { ok: false, data: { error: parsed.error } };
+      }
+
+      return { ok: true, data: { metrics: parsed.metrics } };
+    } catch (error) {
+      return { ok: false, data: { error: error.message } };
+    }
+  };
+
+  return findBreakingPoint({ min, max, runner });
+}
+
+module.exports = {
+  runBreakingPointSearch
+};

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

@@ -0,0 +1,123 @@
+/**
+ * Git checkpoint helper for /perf phases.
+ *
+ * @module lib/perf/checkpoint
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const { getStateDir } = require('../platform/state-dir');
+
+/**
+ * Check if git repo is clean.
+ * @returns {boolean}
+ */
+function isWorkingTreeClean() {
+  const output = execFileSync('git', ['status', '--porcelain'], { encoding: 'utf8' }).trim();
+  return output.length === 0;
+}
+
+/**
+ * Build checkpoint commit message.
+ * @param {object} input
+ * @param {string} input.phase
+ * @param {string} input.id
+ * @param {string} [input.baselineVersion]
+ * @param {string} [input.deltaSummary]
+ * @returns {string}
+ */
+function buildCheckpointMessage(input) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('Checkpoint input must be an object');
+  }
+  const { phase, id, baselineVersion, deltaSummary } = input;
+
+  if (!phase || typeof phase !== 'string') {
+    throw new Error('phase is required');
+  }
+  if (!id || typeof id !== 'string') {
+    throw new Error('id is required');
+  }
+
+  const baseline = baselineVersion || 'n/a';
+  const delta = deltaSummary || 'n/a';
+  return `perf: phase ${phase} [${id}] baseline=${baseline} delta=${delta}`;
+}
+
+/**
+ * Get the most recent git commit message.
+ * @returns {string|null}
+ */
+function getLastCommitMessage() {
+  try {
+    return execFileSync('git', ['log', '-1', '--pretty=%B'], { encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get recent git commit summaries.
+ * @param {number} [limit=5]
+ * @returns {string[]}
+ */
+function getRecentCommits(limit = 5) {
+  try {
+    const count = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 5;
+    const output = execFileSync('git', ['log', `-${count}`, '--pretty=format:%h %s'], { encoding: 'utf8' }).trim();
+    if (!output) return [];
+    return output.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if the next checkpoint would duplicate the last commit.
+ * @param {string} message
+ * @returns {boolean}
+ */
+function isDuplicateCheckpoint(message) {
+  const last = getLastCommitMessage();
+  if (!last) return false;
+  return last.trim() === String(message || '').trim();
+}
+
+/**
+ * Commit a checkpoint for a perf phase.
+ * @param {object} input
+ * @returns {{ ok: boolean, message?: string, reason?: string }}
+ */
+function commitCheckpoint(input) {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+  } catch {
+    return { ok: false, reason: 'not a git repo' };
+  }
+
+  if (isWorkingTreeClean()) {
+    return { ok: false, reason: 'nothing to commit' };
+  }
+
+  const message = buildCheckpointMessage(input);
+  if (isDuplicateCheckpoint(message)) {
+    return { ok: false, reason: 'duplicate checkpoint' };
+  }
+  const perfDir = path.join(getStateDir(), 'perf');
+  try {
+    execFileSync('git', ['add', '-A', '--', perfDir], { stdio: 'ignore' });
+  } catch {
+    execFileSync('git', ['add', '-A'], { stdio: 'ignore' });
+  }
+  execFileSync('git', ['commit', '-m', message], { stdio: 'ignore' });
+  return { ok: true, message };
+}
+
+module.exports = {
+  isWorkingTreeClean,
+  buildCheckpointMessage,
+  getLastCommitMessage,
+  getRecentCommits,
+  isDuplicateCheckpoint,
+  commitCheckpoint
+};

package/plugins/debate/lib/perf/code-paths.js

@@ -0,0 +1,86 @@
+/**
+ * Code-path discovery helpers for /perf.
+ *
+ * @module lib/perf/code-paths
+ */
+
+const DEFAULT_STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'from', 'that', 'this', 'these', 'those',
+  'into', 'over', 'under', 'than', 'then', 'when', 'where', 'what', 'which',
+  'your', 'you', 'our', 'their', 'there', 'have', 'has', 'had', 'will',
+  'would', 'should', 'could', 'about', 'across', 'after', 'before', 'while',
+  'perf', 'performance', 'investigation', 'baseline', 'benchmark', 'scenario'
+]);
+
+function normalizeKeywords(text) {
+  if (!text || typeof text !== 'string') return [];
+  const tokens = text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/g)
+    .filter(Boolean)
+    .filter(token => token.length > 2)
+    .filter(token => !DEFAULT_STOPWORDS.has(token));
+
+  return Array.from(new Set(tokens));
+}
+
+function scoreEntry(entry, keywords) {
+  let score = 0;
+  if (!entry || keywords.length === 0) return score;
+
+  const haystack = [
+    entry.file || '',
+    ...(entry.symbols || [])
+  ].join(' ').toLowerCase();
+
+  for (const keyword of keywords) {
+    if (haystack.includes(keyword)) score += 1;
+  }
+
+  return score;
+}
+
+function extractSymbols(fileData) {
+  if (!fileData || !fileData.symbols) return [];
+  const symbols = [];
+  for (const group of Object.values(fileData.symbols)) {
+    if (!Array.isArray(group)) continue;
+    for (const symbol of group) {
+      if (symbol && symbol.name) symbols.push(symbol.name);
+    }
+  }
+  return symbols;
+}
+
+function collectCodePaths(repoMap, scenario, limit = 12) {
+  if (!repoMap || !repoMap.files) {
+    return { keywords: normalizeKeywords(scenario), paths: [] };
+  }
+
+  const keywords = normalizeKeywords(scenario);
+  const candidates = [];
+
+  for (const [file, data] of Object.entries(repoMap.files)) {
+    const symbols = extractSymbols(data);
+    const entry = { file, symbols };
+    const score = scoreEntry(entry, keywords);
+    if (score <= 0) continue;
+    candidates.push({ ...entry, score });
+  }
+
+  candidates.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+
+  return {
+    keywords,
+    paths: candidates.slice(0, limit).map(item => ({
+      file: item.file,
+      score: item.score,
+      symbols: item.symbols.slice(0, 8)
+    }))
+  };
+}
+
+module.exports = {
+  normalizeKeywords,
+  collectCodePaths
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Baseline consolidation helper.
+ *
+ * @module lib/perf/consolidation
+ */
+
+const baselineStore = require('./baseline-store');
+
+/**
+ * Consolidate a baseline for a version (overwrite existing).
+ * @param {object} input
+ * @param {string} input.version
+ * @param {object} input.baseline
+ * @param {string} [basePath]
+ * @returns {{ version: string, path: string }}
+ */
+function consolidateBaseline(input, basePath = process.cwd()) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('consolidateBaseline requires an input object');
+  }
+  const { version, baseline } = input;
+
+  if (!version || typeof version !== 'string') {
+    throw new Error('version is required');
+  }
+  if (!baseline || typeof baseline !== 'object') {
+    throw new Error('baseline is required');
+  }
+
+  baselineStore.writeBaseline(version, baseline, basePath);
+  const path = baselineStore.getBaselinePath(version, basePath);
+  return { version, path };
+}
+
+module.exports = {
+  consolidateBaseline
+};

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

@@ -0,0 +1,71 @@
+/**
+ * Constraint testing runner for /perf.
+ *
+ * @module lib/perf/constraint-runner
+ */
+
+const { runBenchmarkSeries, DEFAULT_MIN_DURATION } = require('./benchmark-runner');
+const { compareBaselines } = require('./baseline-comparator');
+
+/**
+ * Run baseline and constrained benchmarks sequentially.
+ * Constraints are provided via env vars to keep it cross-platform.
+ *
+ * @param {object} options
+ * @param {string} options.command
+ * @param {object} options.constraints
+ * @param {number} [options.duration]
+ * @param {number} [options.minDuration]
+ * @param {number} [options.runs]
+ * @param {string} [options.aggregate]
+ * @param {object} [options.env]
+ * @returns {{ constraints: object, baseline: object, constrained: object, delta: object }}
+ */
+function runConstraintTest(options) {
+  const { command, constraints, duration, minDuration, runs, aggregate, env } = options || {};
+
+  if (!command || typeof command !== 'string') {
+    throw new Error('command must be a non-empty string');
+  }
+  if (!constraints || typeof constraints !== 'object' || Array.isArray(constraints)) {
+    throw new Error('constraints must be an object');
+  }
+
+  const baselineResult = runBenchmarkSeries(command, {
+    duration: duration ?? DEFAULT_MIN_DURATION,
+    minDuration,
+    runs,
+    aggregate,
+    env: {
+      ...env
+    }
+  });
+
+  const constrainedResult = runBenchmarkSeries(command, {
+    duration: duration ?? DEFAULT_MIN_DURATION,
+    minDuration,
+    runs,
+    aggregate,
+    env: {
+      ...env,
+      PERF_CPU_LIMIT: constraints.cpu,
+      PERF_MEMORY_LIMIT: constraints.memory
+    }
+  });
+
+  const delta = compareBaselines(
+    { metrics: baselineResult.metrics },
+    { metrics: constrainedResult.metrics }
+  );
+
+  return {
+    constraints,
+    baseline: { metrics: baselineResult.metrics },
+    constrained: { metrics: constrainedResult.metrics },
+    delta
+  };
+}
+
+module.exports = {
+  runConstraintTest
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Experiment runner utilities.
+ *
+ * @module lib/perf/experiment-runner
+ */
+
+/**
+ * Run experiments sequentially (never parallel).
+ * @param {Array<object>} experiments
+ * @param {(experiment:object)=>Promise<object>} runner
+ * @returns {Promise<{results:Array<object>}>}
+ */
+async function runExperiments(experiments, runner) {
+  if (!Array.isArray(experiments)) {
+    throw new Error('experiments must be an array');
+  }
+  if (typeof runner !== 'function') {
+    throw new Error('runner must be a function');
+  }
+
+  const results = [];
+  for (const experiment of experiments) {
+    const result = await runner(experiment);
+    results.push(result);
+  }
+
+  return { results };
+}
+
+module.exports = {
+  runExperiments
+};

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

@@ -0,0 +1,41 @@
+/**
+ * Performance investigation utilities
+ *
+ * @module lib/perf
+ */
+
+const investigationState = require('./investigation-state');
+const baselineStore = require('./baseline-store');
+const baselineComparator = require('./baseline-comparator');
+const benchmarkRunner = require('./benchmark-runner');
+const breakingPointFinder = require('./breaking-point-finder');
+const breakingPointRunner = require('./breaking-point-runner');
+const experimentRunner = require('./experiment-runner');
+const constraintRunner = require('./constraint-runner');
+const checkpoint = require('./checkpoint');
+const profilingRunner = require('./profiling-runner');
+const optimizationRunner = require('./optimization-runner');
+const consolidation = require('./consolidation');
+const profilers = require('./profilers');
+const analyzer = require('./analyzer');
+const argumentParser = require('./argument-parser');
+const codePaths = require('./code-paths');
+
+module.exports = {
+  investigationState,
+  baselineStore,
+  baselineComparator,
+  benchmarkRunner,
+  breakingPointFinder,
+  breakingPointRunner,
+  experimentRunner,
+  constraintRunner,
+  checkpoint,
+  profilingRunner,
+  optimizationRunner,
+  consolidation,
+  profilers,
+  analyzer,
+  argumentParser,
+  codePaths
+};