mcp-castor 2026.3.0

package/src/env.js

@@ -0,0 +1,10 @@
+/**
+ * src/env.js — Leaf module: host platform detection.
+ *
+ * Single source of truth for the platform check. Kept as a LEAF (no imports)
+ * so that any module — including config.js and wsl_env.js — can import it
+ * without creating a dependency cycle. Previously this constant lived in
+ * config.js, which forced platform.js to import config.js (and vice versa),
+ * the cycle that produced the TDZ ReferenceError on Linux CI.
+ */
+export const IS_WINDOWS = process.platform === "win32";

package/src/evo_engine.js

@@ -0,0 +1,214 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import { LineageDag } from "./harness/evo/lineage_dag.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Maps a canonical status to the legacy `state` view's status names.
+ * Only a rejected candidate maps to "FAILED"; neutral/pending/unknown map to
+ * their respective names.
+ */
+function mapStatusToLegacy(status) {
+  const s = typeof status === "string" ? status.trim().toLowerCase() : "";
+  if (s === "accepted") return "ACCEPTED";
+  if (s === "rejected") return "FAILED";
+  if (s === "pending") return "PENDING";
+  if (s === "neutral") return "NEUTRAL";
+  return "UNKNOWN";
+}
+
+/**
+ * Evo Lineage Engine.
+ *
+ * Delegates to the unified LineageDag engine to guarantee atomic persistence,
+ * single-writer synchronization, and graph-based candidate tracking.
+ *
+ * The DAG is a per-workspace singleton (LineageDag.forWorkspace), so this
+ * engine and the EvoOperator share one in-memory graph and one
+ * read-modify-write persist path.
+ */
+export class EvoLineageEngine {
+  constructor(cwd) {
+    this.cwd = cwd;
+    this.evoDir = path.join(cwd, ".evo");
+    this.dag = LineageDag.forWorkspace(cwd);
+  }
+
+  async init() {
+    this.dag._load();
+  }
+
+  get state() {
+    // Compatibility view for legacy callers
+    const nodes = Array.from(this.dag.nodes.values());
+    const candidates = nodes
+      .filter((n) => n.id !== "baseline")
+      .map((n) => ({
+        candidateId: n.id,
+        parentCommit: n.parentId,
+        commitSha: n.metrics?.commitSha,
+        hypothesis: n.hypothesis,
+        filesModified: n.filesModified,
+        metricScore: n.metrics?.fitness ?? n.metrics?.score ?? null,
+        // Only a rejected candidate maps to "FAILED".
+        status: mapStatusToLegacy(n.metrics?.status),
+        timestamp: n.timestamp,
+        errorLog: n.metrics?.errorLog ?? null,
+      }));
+
+    const best = this.dag.getBestCandidate();
+    return {
+      initializedAt: nodes[0]?.timestamp || new Date().toISOString(),
+      bestCommit: best?.metrics?.commitSha || "baseline",
+      bestMetric: best?.metrics?.fitness ?? null,
+      targetMetricName: null,
+      higherIsBetter: true,
+      candidates,
+    };
+  }
+
+  /**
+   * Returns the current git commit SHA, or null when it cannot be determined
+   * (no git repo, git unavailable, or a non-zero exit). Callers must treat
+   * null as "unknown".
+   */
+  async getCurrentCommit() {
+    try {
+      const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: this.cwd });
+      const sha = stdout.trim();
+      return sha || null;
+    } catch {
+      return null;
+    }
+  }
+
+  async save() {
+    this.dag.persist();
+  }
+
+  /**
+   * Generates a grounded, hallucination-free lineage brief for the agent.
+   */
+  async getLineageBrief() {
+    await this.init();
+    const nodes = Array.from(this.dag.nodes.values()).filter((n) => n.id !== "baseline");
+    if (nodes.length === 0) {
+      return (
+        `Evo Lineage Status: Fresh baseline.\n` +
+        `No candidate variations evaluated yet.`
+      );
+    }
+
+    const recent = nodes.slice(-8);
+    const summaryLines = recent.map((n) => {
+      const statusIcon = n.metrics?.status === "accepted" ? "[OK]" : "[FAIL]";
+      const metricStr = n.metrics?.fitness !== null && n.metrics?.fitness !== undefined
+        ? `Metric: ${n.metrics.fitness}`
+        : "No metric";
+      const failSnippet = n.metrics?.errorLog ? ` | Error: ${n.metrics.errorLog.slice(0, 120).replace(/\n/g, " ")}` : "";
+      return `${statusIcon} [${n.id}] Hypothesis: "${n.hypothesis}" -> ${n.metrics?.status?.toUpperCase()} (${metricStr})${failSnippet}`;
+    });
+
+    const best = this.dag.getBestCandidate();
+    return (
+      `=== Evo Candidate Lineage History ===\n` +
+      `Active Head: ${this.dag.currentHeadId} (Best Score: ${best?.metrics?.fitness ?? "N/A"})\n` +
+      `Total Candidates Evaluated: ${nodes.length}\n` +
+      `Recent Trajectory (Last ${recent.length}):\n` +
+      summaryLines.join("\n") +
+      `\n============================================`
+    );
+  }
+
+  async getLineageContext() {
+    return this.getLineageBrief();
+  }
+
+  extractMetric(output, name) {
+    if (!output || !name) return null;
+    let value = null;
+    for (const line of String(output).split(/\r?\n/)) {
+      if (!line.toLowerCase().includes(String(name).toLowerCase())) continue;
+      const nums = line.match(/-?\d+(?:\.\d+)?/g);
+      if (nums && nums.length > 0) value = Number(nums[nums.length - 1]);
+    }
+    return value === null || Number.isNaN(value) ? null : value;
+  }
+
+  async recordCandidate({
+    hypothesis,
+    testCommand,
+    metricScore,
+    metricValue,
+    targetMetricName,
+    metricName,
+    higherIsBetter = true,
+    stdout,
+    stderr,
+    testStderr,
+    exitCode,
+    filesModified,
+    status: callerStatus,
+  } = {}) {
+    await this.init();
+    const metric = metricScore ?? metricValue ?? null;
+    const errText = stderr ?? testStderr ?? "";
+    const passed =
+      exitCode !== undefined ? exitCode === 0 : callerStatus !== "FAILED";
+    const candidateId = `cand_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    // getCurrentCommit() returns null when the commit is unknown (no repo /
+    // git unavailable); record that as a null parentage.
+    const currentCommit = await this.getCurrentCommit();
+
+    const best = this.dag.getBestCandidate();
+    const bestScore = best?.metrics?.fitness ?? null;
+
+    let isImprovement = false;
+    if (passed && metric !== null && metric !== undefined) {
+      if (bestScore === null) {
+        isImprovement = true;
+      } else if (higherIsBetter && metric > bestScore) {
+        isImprovement = true;
+      } else if (!higherIsBetter && metric < bestScore) {
+        isImprovement = true;
+      }
+    }
+
+    const status = isImprovement
+      ? "accepted"
+      : passed
+        ? "neutral"
+        : "rejected";
+
+    const node = this.dag.addCandidate({
+      id: candidateId,
+      parentId: this.dag.currentHeadId,
+      hypothesis,
+      filesModified: filesModified ?? [],
+      metrics: {
+        fitness: metric,
+        status,
+        commitSha: currentCommit,
+        errorLog: !passed ? (errText || stdout || "").slice(-800) : null,
+      },
+    });
+
+    if (isImprovement) {
+      this.dag.currentHeadId = candidateId;
+      this.dag.persist();
+      return {
+        status: "ACCEPTED",
+        candidateId,
+        message: `Candidate ${candidateId} improved metric to ${metric} (new active baseline).`,
+      };
+    } else {
+      return {
+        status: status.toUpperCase(),
+        candidateId,
+        message: `Candidate ${candidateId} evaluated (Status: ${status.toUpperCase()}). Working tree preserved for inspection.`,
+      };
+    }
+  }
+}

package/src/harness/core/events.js

@@ -0,0 +1,75 @@
+/**
+ * Castor Event Bus with Reversible Disposers
+ * Provides lifecycle event decoupling where listeners return cleanup disposers.
+ */
+
+export class EventBus {
+  constructor() {
+    this._listeners = new Map();
+  }
+
+  /**
+   * Registers a listener for an event. Returns a disposer function that unbinds it cleanly.
+   * @param {string} event
+   * @param {Function} handler
+   * @returns {() => void} Disposer
+   */
+  on(event, handler) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    const handlers = this._listeners.get(event);
+    handlers.add(handler);
+
+    // Reversible effect disposer
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this._listeners.delete(event);
+      }
+    };
+  }
+
+  /**
+   * Registers a one-shot listener.
+   * @param {string} event
+   * @param {Function} handler
+   * @returns {() => void} Disposer
+   */
+  once(event, handler) {
+    const dispose = this.on(event, (...args) => {
+      dispose();
+      handler(...args);
+    });
+    return dispose;
+  }
+
+  /**
+   * Emits an event synchronously or asynchronously.
+   * @param {string} event
+   * @param  {...any} args
+   * @returns {Promise<any[]>}
+   */
+  async emit(event, ...args) {
+    const handlers = this._listeners.get(event);
+    if (!handlers || handlers.size === 0) return [];
+    const results = [];
+    for (const h of Array.from(handlers)) {
+      try {
+        const res = h(...args);
+        results.push(res instanceof Promise ? await res : res);
+      } catch (err) {
+        console.error(`[EventBus] Error in handler for event '${event}':`, err);
+        results.push({ error: err, isError: true });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this._listeners.clear();
+  }
+}

package/src/harness/core/kernel.js

@@ -0,0 +1,209 @@
+/**
+ * Castor Microkernel Core
+ *
+ * Implements "Everything is a Plugin" with reversible effects:
+ * - Service container with dependency injection
+ * - Pluggable tool registry
+ * - Reversible disposers that unbind listeners and registrations on unmount
+ * - Context hierarchy supporting isolated child contexts
+ */
+
+import { EventBus } from "./events.js";
+
+export class Context {
+  /**
+   * @param {Context|null} parent
+   * @param {string} [name="root"]
+   */
+  constructor(parent = null, name = "root") {
+    this.name = name;
+    this.parent = parent;
+    this.root = parent ? (parent.root || parent) : this;
+    this.events = parent ? parent.events : new EventBus();
+    this.services = parent ? new Map(parent.services) : new Map();
+    this.tools = parent ? new Map(parent.tools) : new Map();
+    this._disposers = new Set();
+    this._plugins = new Map();
+  }
+
+  /**
+   * Registers a reusable service in the container.
+   * @param {string} name
+   * @param {any} service
+   * @returns {() => void} Disposer
+   */
+  provide(name, service) {
+    const target = this.root || this;
+    target.services.set(name, service);
+    target[name] = service;
+    this.services.set(name, service);
+    this[name] = service;
+
+    const dispose = () => {
+      if (this.services.get(name) === service) {
+        this.services.delete(name);
+        delete this[name];
+      }
+      if (target.services.get(name) === service) {
+        target.services.delete(name);
+        delete target[name];
+      }
+    };
+    this._disposers.add(dispose);
+    return dispose;
+  }
+
+  /**
+   * Retrieves a registered service.
+   * @param {string} name
+   */
+  get(name) {
+    if (this.services.has(name)) return this.services.get(name);
+    if (this.root && this.root.services.has(name)) return this.root.services.get(name);
+    return undefined;
+  }
+
+  /**
+   * Registers a tool available to the agent.
+   * @param {string} name
+   * @param {object} definition { description, parameters, execute }
+   * @returns {() => void} Disposer
+   */
+  registerTool(name, definition) {
+    if (!definition || typeof definition.execute !== "function") {
+      throw new Error(`Tool '${name}' must provide an execute(params, ctx) function`);
+    }
+    const target = this.root || this;
+    const toolEntry = {
+      name,
+      description: definition.description || "",
+      parameters: definition.parameters || {},
+      execute: definition.execute,
+    };
+    target.tools.set(name, toolEntry);
+    this.tools.set(name, toolEntry);
+
+    const dispose = () => {
+      this.tools.delete(name);
+      if (target.tools.get(name) === toolEntry) {
+        target.tools.delete(name);
+      }
+    };
+    this._disposers.add(dispose);
+    this.events.emit("tool:registered", toolEntry);
+    return dispose;
+  }
+
+  /**
+   * Lists all available tools formatted for model consumption (OpenAI / MCP schema).
+   * Sorts tools alphabetically by name and canonicalizes parameters (RFC 8785)
+   * to guarantee deterministic token serialization for vLLM RadixAttention KV-cache prefix hits.
+   */
+  listTools() {
+    const toolsMap = this.root ? this.root.tools : this.tools;
+    const sorted = Array.from(toolsMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+    return sorted.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: canonicalizeJson(t.parameters),
+      },
+    }));
+  }
+
+  /**
+   * Executes a registered tool by name with safety wrapping.
+   * @param {string} name
+   * @param {object} args
+   */
+  async executeTool(name, args = {}) {
+    const toolsMap = this.root ? this.root.tools : this.tools;
+    const tool = toolsMap.get(name);
+    if (!tool) {
+      throw new Error(`Tool '${name}' is not registered in the harness kernel`);
+    }
+    await this.events.emit("tool:before_execute", { name, args });
+    const t0 = Date.now();
+    try {
+      const result = await tool.execute(args, this);
+      const dt = Date.now() - t0;
+      await this.events.emit("tool:after_execute", { name, args, result, latencyMs: dt, isError: false });
+      return { isError: false, result, latencyMs: dt };
+    } catch (err) {
+      const dt = Date.now() - t0;
+      await this.events.emit("tool:after_execute", { name, args, error: err.message, latencyMs: dt, isError: true });
+      return { isError: true, error: err.message, latencyMs: dt };
+    }
+  }
+
+  /**
+   * Mounts a plugin into the context.
+   * @param {Function|object} plugin Plugin function (ctx, options) or { apply: (ctx, options) }
+   * @param {object} [options={}]
+   * @returns {() => void} Disposer to cleanly unmount the plugin and all its effects
+   */
+  plugin(plugin, options = {}) {
+    const childCtx = new Context(this, plugin.name || "plugin");
+    let resultDisposer = null;
+
+    if (typeof plugin === "function") {
+      resultDisposer = plugin(childCtx, options);
+    } else if (plugin && typeof plugin.apply === "function") {
+      resultDisposer = plugin.apply(childCtx, options);
+    } else {
+      throw new Error("Plugin must be a callable function or object with an apply() method");
+    }
+
+    const unmount = () => {
+      if (typeof resultDisposer === "function") {
+        try {
+          resultDisposer();
+        } catch {}
+      }
+      childCtx.dispose();
+      this._plugins.delete(plugin);
+    };
+
+    this._plugins.set(plugin, unmount);
+    this._disposers.add(unmount);
+    return unmount;
+  }
+
+  /**
+   * Disposes of the context and cleanly unwinds all registrations and listeners.
+   */
+  dispose() {
+    for (const d of Array.from(this._disposers)) {
+      try {
+        d();
+      } catch {}
+    }
+    this._disposers.clear();
+    this.services.clear();
+    this.tools.clear();
+    this._plugins.clear();
+  }
+}
+
+/**
+ * Canonicalizes an object or array by sorting all object keys lexicographically (RFC 8785).
+ * Ensures deterministic byte serialization across JavaScript Map iteration orders and JSON encodings.
+ * @param {any} obj
+ * @returns {any}
+ */
+export function canonicalizeJson(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(canonicalizeJson);
+  }
+  const sorted = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = canonicalizeJson(obj[key]);
+  }
+  return sorted;
+}
+

package/src/harness/evo/evaluator.js

@@ -0,0 +1,156 @@
+/**
+ * Closed-Loop Metric Evaluator (Evo Fitness Engine)
+ *
+ * Executes evaluation commands and parses feedback into a quantitative FitnessScore.
+ */
+
+import { condenseTraceback } from "./trace_repair.js";
+
+export class ClosedLoopEvaluator {
+  constructor(options = {}) {
+    this.shell = options.shell; // ShellExecutorService instance
+  }
+
+  /**
+   * Evaluates a command line and computes a structured FitnessScore.
+   *
+   * @param {object} params
+   * @param {string} params.command Test or benchmark command (e.g. "npm test", "pytest")
+   * @param {string} [params.cwd]
+   * @param {string} [params.primaryMetric] Name of primary metric ("throughput", "latency_ms", "tests_passed")
+   * @param {number} [params.timeout_ms]
+   * @returns {Promise<{
+   *   passed: boolean,
+   *   fitness: number,
+   *   exitCode: number,
+   *   metrics: object,
+   *   failureDigest: object|null,
+   *   stdout: string,
+   *   stderr: string,
+   *   latencyMs: number
+   * }>}
+   */
+  async evaluate({ command, cwd, primaryMetric = "tests_passed", timeout_ms = 120_000 }) {
+    if (!this.shell) {
+      throw new Error("ClosedLoopEvaluator requires a ShellExecutorService instance");
+    }
+
+    const execResult = await this.shell.execute({
+      command,
+      cwd,
+      timeout_ms,
+    });
+
+    const parsed = this.parseMetrics(execResult.stdout, execResult.stderr, execResult.exitCode);
+    const fitness = this.calculateFitness(parsed, primaryMetric, execResult.latencyMs);
+
+    const failureDigest = !execResult.exitCode || parsed.testsFailed === 0
+      ? null
+      : condenseTraceback({
+          stdout: execResult.stdout,
+          stderr: execResult.stderr,
+          exitCode: execResult.exitCode,
+          timedOut: execResult.timedOut,
+          workspaceRoot: cwd,
+        });
+
+    return {
+      passed: parsed.testsFailed === 0 && execResult.exitCode === 0,
+      fitness,
+      exitCode: execResult.exitCode,
+      metrics: parsed,
+      failureDigest,
+      stdout: execResult.stdout.slice(0, 8000),
+      stderr: execResult.stderr.slice(0, 8000),
+      latencyMs: execResult.latencyMs,
+    };
+  }
+
+  /**
+   * Parses test outputs and numeric metrics from stdout/stderr.
+   */
+  parseMetrics(stdout, stderr, exitCode) {
+    const combined = `${stdout}\n${stderr}`;
+    const metrics = {
+      exitCode,
+      testsTotal: 0,
+      testsPassed: 0,
+      testsFailed: exitCode === 0 ? 0 : 1,
+      throughput: null,
+      latencyMs: null,
+      opsPerSec: null,
+      memoryMb: null,
+    };
+
+    // Pytest match: "X passed, Y failed in Zs"
+    const pytestMatch = combined.match(/(\d+)\s+passed(?:,\s+(\d+)\s+failed)?/i);
+    if (pytestMatch) {
+      metrics.testsPassed = parseInt(pytestMatch[1], 10);
+      metrics.testsFailed = pytestMatch[2] ? parseInt(pytestMatch[2], 10) : 0;
+      metrics.testsTotal = metrics.testsPassed + metrics.testsFailed;
+    }
+
+    // Vitest / Jest match: "Tests: X passed, Y failed, Z total"
+    const jestMatch = combined.match(/Tests:\s+(?:(\d+)\s+failed,?\s*)?(?:(\d+)\s+passed,?\s*)?(\d+)\s+total/i);
+    if (jestMatch) {
+      metrics.testsFailed = jestMatch[1] ? parseInt(jestMatch[1], 10) : 0;
+      metrics.testsPassed = jestMatch[2] ? parseInt(jestMatch[2], 10) : 0;
+      metrics.testsTotal = parseInt(jestMatch[3], 10);
+    }
+
+    // Go test match: "PASS" or "FAIL"
+    if (combined.includes("--- PASS:")) metrics.testsPassed = Math.max(1, metrics.testsPassed);
+    if (combined.includes("--- FAIL:")) metrics.testsFailed = Math.max(1, metrics.testsFailed);
+
+    // Throughput matches: "123.45 ops/sec" or "123.45 req/sec" or "123 tokens/s"
+    const opsMatch = combined.match(/([\d.]+)\s*(?:ops\/s(?:ec)?|req\/s(?:ec)?|tokens?\/s(?:ec)?)/i);
+    if (opsMatch) {
+      metrics.opsPerSec = parseFloat(opsMatch[1]);
+      metrics.throughput = metrics.opsPerSec;
+    }
+
+    // Benchmark Latency: "123.45 ms"
+    const latencyMatch = combined.match(/(?:latency|duration|time):\s*([\d.]+)\s*ms/i);
+    if (latencyMatch) {
+      metrics.latencyMs = parseFloat(latencyMatch[1]);
+    }
+
+    // Memory usage: "123 MB"
+    const memMatch = combined.match(/([\d.]+)\s*MB(?:\s+heap)?/i);
+    if (memMatch) {
+      metrics.memoryMb = parseFloat(memMatch[1]);
+    }
+
+    return metrics;
+  }
+
+  /**
+   * Calculates scalar fitness score.
+   */
+  calculateFitness(parsed, primaryMetric, runDurationMs) {
+    // Severe penalty for non-zero exit code or failed tests
+    if (parsed.exitCode !== 0 || parsed.testsFailed > 0) {
+      return -100 - parsed.testsFailed * 25;
+    }
+
+    // Zero-assertion baseline: a compiler pass or command without test framework assertions
+    // is a neutral syntax gate (score: 50.0), NOT a verified functional optimization (100.0).
+    let baseScore = 50;
+    if (parsed.testsTotal > 0) {
+      baseScore = (parsed.testsPassed / parsed.testsTotal) * 100;
+    }
+
+    // Metric bonus
+    if (primaryMetric === "throughput" && parsed.throughput) {
+      return Number((baseScore + parsed.throughput).toFixed(2));
+    }
+
+    if (primaryMetric === "latency_ms") {
+      const lat = parsed.latencyMs || runDurationMs;
+      // Lower latency yields higher fitness
+      return Number((baseScore + 1000 / Math.max(1, lat)).toFixed(2));
+    }
+
+    return Number(baseScore.toFixed(2));
+  }
+}