jules-orchestrator-kit 0.9.3 → 0.20.0

package/scripts/jules-merge-swarm.mjs

@@ -1,30 +1,198 @@
 #!/usr/bin/env node
 
 /**
- * Backward compatibility shim for jules-merge-swarm.mjs in v0.9.0.
+ * Swarm branch merger with 3-way structural JSON/object merge, git merge-file execution
+ * isolated in os.tmpdir(), and safety gate checking.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, readdirSync, rmSync, mkdtempSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { classifyRiskTier, RISK_TIERS } from "../src/risk.mjs";
+import { changedFiles } from "../src/git.mjs";
 
+export const EXIT = Object.freeze({
+  SUCCESS: 0,
+  R3_RESTRICTED: 3,
+  MERGE_CONFLICT: 4,
+});
+
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isPlainObject(v) {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === null || Object.getPrototypeOf(v) === Object.prototype)
+  );
+}
+
+function deepClone(v) {
+  if (v === undefined) return undefined;
+  return JSON.parse(JSON.stringify(v));
+}
+
+function stableStringify(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(v).filter((k) => !BLOCKED_KEYS.has(k)).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(",")}}`;
+}
+
+function deepEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+/**
+ * Recursive 3-way structural object & array merge.
+ */
+export function deepMerge3Way(base, ours, theirs, path = "$") {
+  const conflicts = [];
+  if (deepEqual(ours, theirs)) return { merged: deepClone(ours), conflicts };
+  if (deepEqual(ours, base)) return { merged: deepClone(theirs), conflicts };
+  if (deepEqual(theirs, base)) return { merged: deepClone(ours), conflicts };
+
+  if (isPlainObject(base) && isPlainObject(ours) && isPlainObject(theirs)) {
+    const merged = {};
+    const safeBase = base || {};
+    const safeOurs = ours || {};
+    const safeTheirs = theirs || {};
+    const keys = new Set([
+      ...Object.keys(safeBase),
+      ...Object.keys(safeOurs),
+      ...Object.keys(safeTheirs),
+    ]);
+    for (const k of keys) {
+      if (BLOCKED_KEYS.has(k)) continue;
+      const childPath = `${path}.${k}`;
+      const b = safeBase[k], o = safeOurs[k], t = safeTheirs[k];
+      if (o === undefined && t === undefined) continue;
+      if (o === undefined) { merged[k] = deepClone(t); continue; }
+      if (t === undefined) { merged[k] = deepClone(o); continue; }
+      const sub = deepMerge3Way(b, o, t, childPath);
+      merged[k] = sub.merged;
+      conflicts.push(...sub.conflicts);
+    }
+    return { merged, conflicts };
+  }
+
+  if (Array.isArray(ours) && Array.isArray(theirs)) {
+    const baseArr = Array.isArray(base) ? base : [];
+    const minLen = Math.min(ours.length, theirs.length);
+    const merged = [];
+    for (let i = 0; i < minLen; i++) {
+      const sub = deepMerge3Way(baseArr[i], ours[i], theirs[i], `${path}[${i}]`);
+      merged.push(sub.merged);
+      conflicts.push(...sub.conflicts);
+    }
+    if (ours.length > minLen && theirs.length <= minLen) {
+      merged.push(...ours.slice(minLen).map(deepClone));
+    } else if (theirs.length > minLen && ours.length <= minLen) {
+      merged.push(...theirs.slice(minLen).map(deepClone));
+    } else if (ours.length > minLen && theirs.length > minLen) {
+      conflicts.push({
+        path: `${path}[tail]`,
+        base: baseArr.slice(minLen),
+        ours: ours.slice(minLen),
+        theirs: theirs.slice(minLen),
+      });
+      merged.push(...ours.slice(minLen).map(deepClone));
+    }
+    return { merged, conflicts };
+  }
+
+  conflicts.push({ path, base: deepClone(base), ours: deepClone(ours), theirs: deepClone(theirs) });
+  return { merged: deepClone(ours), conflicts };
+}
+
+/**
+ * Executes a function inside a temporary directory in os.tmpdir() with guaranteed cleanup.
+ */
+export function withTempDir(prefix, fn) {
+  const dir = mkdtempSync(join(tmpdir(), prefix || "jules-merge-"));
+  try {
+    return fn(dir);
+  } finally {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch (_) {}
+  }
+}
+
+/**
+ * Attempts a 3-way text file merge using git merge-file inside os.tmpdir().
+ */
+export function attemptCodeMergeFile(repoRoot, relPath, oursContent, baseContent, theirsContent) {
+  return withTempDir("jules-merge-", (tmp) => {
+    const baseFile = join(tmp, "base");
+    const oursFile = join(tmp, "ours");
+    const theirsFile = join(tmp, "theirs");
+    writeFileSync(baseFile, baseContent ?? "", "utf-8");
+    writeFileSync(oursFile, oursContent ?? "", "utf-8");
+    writeFileSync(theirsFile, theirsContent ?? "", "utf-8");
+
+    const res = spawnSync("git", ["merge-file", "-p", "--diff3", oursFile, baseFile, theirsFile], {
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+    if (res.error) {
+      return { ok: false, conflicts: 0, error: res.error.message };
+    }
+    const conflictCount = res.status && res.status > 0 ? res.status : 0;
+    const merged = res.stdout ?? "";
+    return {
+      ok: conflictCount === 0,
+      merged,
+      conflicts: conflictCount,
+    };
+  });
+}
+
+/**
+ * Checks safety gate against active worker locks and risk tiers.
+ */
 export function checkSafetyGate(branchName = "", projectRoot = process.cwd()) {
   const locksDir = join(projectRoot, ".agent/state/locks");
-  if (!existsSync(locksDir)) return { safe: true };
+  if (existsSync(locksDir)) {
+    try {
+      const files = readdirSync(locksDir);
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        const content = readFileSync(join(locksDir, f), "utf-8");
+        const parsed = JSON.parse(content);
+        if (parsed.branch === branchName) {
+          return { safe: false, reason: `Active lock held by worker ${parsed.agent || "unknown"}` };
+        }
+      }
+    } catch (_) {}
+  }
+
+  // Check R3 risk tier if files modified
   try {
-    const files = readdirSync(locksDir);
-    for (const f of files) {
-      if (!f.endsWith(".json")) continue;
-      const content = readFileSync(join(locksDir, f), "utf-8");
-      const parsed = JSON.parse(content);
-      if (parsed.branch === branchName) {
-        return { safe: false, reason: `Active lock held by worker ${parsed.agent || "unknown"}` };
+    const files = changedFiles(projectRoot, process.env.BASE_BRANCH || "main");
+    if (files.length > 0) {
+      const tier = classifyRiskTier(files);
+      if (tier.tier === RISK_TIERS.R3) {
+        return { safe: false, reason: `R3 Restricted Path violation: ${tier.reason}` };
       }
     }
   } catch (_) {}
+
   return { safe: true };
 }
 
 if (process.argv[1] && process.argv[1].endsWith("jules-merge-swarm.mjs")) {
+  const branchName = process.argv[2] || "";
+  const gateResult = checkSafetyGate(branchName);
+  if (!gateResult.safe) {
+    console.error(`[merge-swarm] Safety gate check failed: ${gateResult.reason}`);
+    process.exit(EXIT.R3_RESTRICTED);
+  }
+
   console.log("No open Jules PRs found.");
-  process.exit(0);
+  process.exit(EXIT.SUCCESS);
 }
+

package/src/config.mjs

@@ -278,6 +278,30 @@ export function resolveVerify(root = process.cwd()) {
   return { test: s.testCmd || "", build: s.buildCmd || "" };
 }
 
+export const TIER_PRESETS = {
+  free: {
+    dailyTasks: 15,
+    repairAttempts: 1,
+    concurrency: 1,
+    staggerMs: 3000,
+    diffKb: 50,
+  },
+  pro: {
+    dailyTasks: 100,
+    repairAttempts: 2,
+    concurrency: 2,
+    staggerMs: 1500,
+    diffKb: 75,
+  },
+  ultra: {
+    dailyTasks: 300,
+    repairAttempts: 3,
+    concurrency: 3,
+    staggerMs: 1000,
+    diffKb: 75,
+  },
+};
+
 /**
  * Loads and validates configuration from .agent/config.yml or .agent/jules.yml.
  */
@@ -301,9 +325,16 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
   const buildCmd = parsed.build_cmd || parsed.verify?.build || "";
   const autoVerify = resolveVerify(root);
 
+  const activeTier = String(process.env.JULES_TIER || parsed.tier || "ultra").toLowerCase();
+  const tierLimits = TIER_PRESETS[activeTier] || TIER_PRESETS.ultra;
+
+  const envDailyTasks = process.env.JULES_DAILY_BUDGET ? Number(process.env.JULES_DAILY_BUDGET) : null;
+  const envDiffKb = process.env.JULES_MAX_DIFF_KB ? Number(process.env.JULES_MAX_DIFF_KB) : null;
+
   const config = {
     version: parsed.version || DEFAULTS.version,
     provider: parsed.provider || DEFAULTS.provider,
+    tier: activeTier,
     verify: {
       test: testCmd || autoVerify.test,
       build: buildCmd || autoVerify.build,
@@ -311,7 +342,10 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     scope: normalizeScope(parsed),
     limits: {
       ...DEFAULTS.limits,
+      ...tierLimits,
       ...(parsed.limits || {}),
+      ...(envDailyTasks && !isNaN(envDailyTasks) ? { dailyTasks: envDailyTasks } : {}),
+      ...(envDiffKb && !isNaN(envDiffKb) ? { diffKb: envDiffKb } : {}),
     },
     isolation: parsed.isolation || DEFAULTS.isolation,
     runner: parsed.runner || DEFAULTS.runner,

package/src/engine.mjs

@@ -5,6 +5,33 @@ import { createProvider } from "./provider.mjs";
 import { withBudget, appendLedger, getQueueDir, ensureDir } from "./state.mjs";
 import { readdirSync, readFileSync, renameSync } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+/**
+ * Computes a SHA-256 fingerprint for a failure state (normalized stderr + diff text).
+ */
+export function fingerprintFailureState(failure = {}, root = process.cwd()) {
+  const rawStderr = failure.stderr || failure.stdout || failure.message || "Unknown Error";
+  const normalizedStderr = String(rawStderr)
+    .replace(/:\d+:\d+/g, ":?:?")
+    .replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z?\b/g, "<timestamp>")
+    .replace(/\b[0-9a-f]{7,40}\b/g, "<sha>")
+    .replace(/\/[\w\/-]+\//g, "/?/")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  let diffStat = "0:0";
+  try {
+    const rawDiff = diffText(root) || "";
+    const lines = rawDiff.split("\n");
+    const added = lines.filter((l) => l.startsWith("+")).length;
+    const removed = lines.filter((l) => l.startsWith("-")).length;
+    diffStat = `${added}:${removed}`;
+  } catch (_) {}
+
+  const combined = `${normalizedStderr}::${diffStat}`;
+  return createHash("sha256").update(combined).digest("hex").substring(0, 16);
+}
 
 /**
  * Gatekeeper verification engine (Phase 1: Scope, Phase 2: Payload, Phase 3: Secrets, Phase 4: Verify Commands).
@@ -106,14 +133,77 @@ export async function gate(opts = {}) {
   return { ok: verifyOk, code: verifyOk ? 0 : 4, phases };
 }
 
+/**
+ * Sliding-window ring-buffer circuit breaker for non-convergent OODA loops.
+ */
+export class OODACircuitBreaker {
+  constructor({ windowSize = 6, threshold = 2, cooldownMs = 60000 } = {}) {
+    this.windowSize = windowSize;
+    this.threshold = threshold;
+    this.cooldownMs = cooldownMs;
+    this.ring = [];
+    this.openedAt = 0;
+    this.openedFingerprint = null;
+  }
+
+  observe(fingerprint) {
+    if (!fingerprint || typeof fingerprint !== "string") {
+      return { tripped: false };
+    }
+    if (this.isOpen()) {
+      return { tripped: true, reason: "OODA_CIRCUIT_OPEN", fingerprint: this.openedFingerprint };
+    }
+    const occurrences = this.ring.filter((f) => f === fingerprint).length + 1;
+    this.ring.push(fingerprint);
+    if (this.ring.length > this.windowSize) this.ring.shift();
+
+    if (occurrences >= this.threshold) {
+      this.openedAt = Date.now();
+      this.openedFingerprint = fingerprint;
+      return {
+        tripped: true,
+        reason: "OODA_THRASH_DETECTED",
+        fingerprint,
+        occurrences,
+      };
+    }
+    return { tripped: false, occurrences };
+  }
+
+  isOpen() {
+    if (this.openedAt === 0) return false;
+    if (Date.now() - this.openedAt >= this.cooldownMs) {
+      this.openedAt = 0;
+      this.openedFingerprint = null;
+      this.ring = [];
+      return false;
+    }
+    return true;
+  }
+
+  reset() {
+    this.ring = [];
+    this.openedAt = 0;
+    this.openedFingerprint = null;
+  }
+}
+
 export async function repair(failure, opts = {}) {
   const root = opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
   const maxRetries = config.limits.repairAttempts || 3;
-  const provider = createProvider(config.provider, config);
+  const provider = opts.provider || createProvider(config.provider, config);
   const attempts = [];
+  const breaker = opts.circuitBreaker || new OODACircuitBreaker({
+    windowSize: Math.max(maxRetries + 1, 6),
+    threshold: 2,
+    cooldownMs: 60000,
+  });
 
   let currentFailure = failure;
+  const initialFingerprint = fingerprintFailureState(currentFailure, root);
+  breaker.observe(initialFingerprint);
+
   for (let n = 1; n <= maxRetries; n++) {
     const repairPrompt = buildRepairPrompt(currentFailure, n, config);
     let session;
@@ -137,9 +227,23 @@ export async function repair(failure, opts = {}) {
     // Re-verify after repair attempt
     const gateRes = await gate({ root, config, fix: false });
     if (gateRes.ok) {
+      breaker.reset();
       return { ok: true, attempts, finalStatus: "PASSED" };
     }
+
     currentFailure = gateRes.phases.find((p) => p.phase === "verify")?.testResult || failure;
+    const currentFingerprint = fingerprintFailureState(currentFailure, root);
+
+    const check = breaker.observe(currentFingerprint);
+    if (check.tripped) {
+      return {
+        ok: false,
+        attempts,
+        finalStatus: "DETERMINISTIC_REGRESSION",
+        reason: `Identical failure state fingerprint (${currentFingerprint}) observed during attempt #${n}`,
+        fingerprint: currentFingerprint,
+      };
+    }
   }
 
   return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED" };
@@ -147,11 +251,23 @@ export async function repair(failure, opts = {}) {
 
 function buildRepairPrompt(failure, attempt, _config) {
   const cleanStderr = redactSecrets(failure.stderr || failure.stdout || "Unknown Error");
-  return `Auto-Repair Attempt #${attempt}
+
+  let escalationStrategy = "DIRECT_REPAIR";
+  let escalationDirective = "1. Ground your fix strictly in the error log below. Do NOT guess file contents or function signatures.";
+
+  if (attempt === 2) {
+    escalationStrategy = "DIAGNOSTIC_ANALYSIS";
+    escalationDirective = "1. DIAGNOSE FIRST: Two attempts have failed. Analyze if the root cause is in a different file or component than where the previous patch was applied.";
+  } else if (attempt >= 3) {
+    escalationStrategy = "MINIMAL_SIMPLIFICATION";
+    escalationDirective = "1. SIMPLIFY: Multiple repair attempts have failed. Revert complex refactors and implement the minimal patch that satisfies the failing assertion.";
+  }
+
+  return `Auto-Repair Attempt #${attempt} [Strategy: ${escalationStrategy}]
 Command Failed: ${failure.command || "verify"}
 
 REPAIR DIRECTIVE & STRICT INVARIANTS:
-1. Ground your fix strictly in the error log below. Do NOT guess file contents or function signatures.
+${escalationDirective}
 2. NO WEAKENING: You are STRICTLY FORBIDDEN from deleting tests, commenting out assertions, or weakening expectations to achieve a passing test. Leave unmet requirements RED if the requirement is valid and feature code is missing.
 3. CARRY EVIDENCE: Address the root cause directly and verify the exact fix.
 4. RE-VERIFY: Execute full verification after patching to ensure zero new regressions.

package/src/execution_envelope.mjs

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { resolveRoot } from "./config.mjs";
+import { resolveBase } from "./git.mjs";
+import { classifyRiskTier } from "./risk.mjs";
+
+/**
+ * Generates a SHA-256 hash of the execution envelope payload.
+ */
+export function hashExecutionEnvelope(envelope) {
+  if (!envelope || typeof envelope !== "object") return "";
+  const rawPayload = {
+    id: envelope.id,
+    taskId: envelope.taskId,
+    baseRef: envelope.baseRef,
+    baseSha: envelope.baseSha,
+    configSha: envelope.configSha,
+    scope: envelope.scope,
+    verify: envelope.verify,
+    riskTier: envelope.riskTier,
+    budgetReservationId: envelope.budgetReservationId,
+    capabilities: envelope.capabilities,
+    createdAt: envelope.createdAt,
+  };
+  const sortedKeys = Object.keys(rawPayload).sort();
+  const canonicalPayload = {};
+  for (const k of sortedKeys) {
+    if (rawPayload[k] !== undefined) {
+      canonicalPayload[k] = rawPayload[k];
+    }
+  }
+  return createHash("sha256").update(JSON.stringify(canonicalPayload)).digest("hex");
+}
+
+/**
+ * Deep freezes an execution envelope to prevent modifications during OODA repair loops.
+ */
+export function freezeExecutionEnvelope(envelope) {
+  if (!envelope || typeof envelope !== "object") return envelope;
+  return Object.freeze({
+    ...envelope,
+    scope: Object.freeze({
+      deny: Object.freeze([...(envelope.scope?.deny || [])]),
+      allow: Object.freeze([...(envelope.scope?.allow || [])]),
+      protect: Object.freeze([...(envelope.scope?.protect || [])]),
+    }),
+    verify: Object.freeze({ ...(envelope.verify || {}) }),
+    capabilities: Object.freeze([...(envelope.capabilities || [])]),
+  });
+}
+
+/**
+ * Creates an immutable Capability-Bounded Execution Envelope (CBEE).
+ */
+export function createExecutionEnvelope(task = {}, opts = {}) {
+  const root = opts.root || resolveRoot();
+  const baseRef = opts.base || task.base || "main";
+  const baseSha = resolveBase(root, baseRef);
+
+  const taskId = task.id || opts.taskId || `task-${Date.now()}`;
+  const envelopeId = `env-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+
+  const denyPaths = opts.forbiddenPaths || task.forbiddenPaths || [".github/**", "package-lock.json", "pnpm-lock.yaml"];
+  const allowPaths = opts.allowPaths || task.allowPaths || [];
+  const protectPaths = opts.protectPaths || task.protectPaths || ["package.json", "tsconfig.json", "AGENTS.md"];
+
+  const files = task.files || opts.files || [];
+  const riskMeta = classifyRiskTier(files, { diffLines: opts.diffLines || 0 });
+
+  const rawEnvelope = {
+    id: envelopeId,
+    taskId,
+    baseRef,
+    baseSha,
+    configSha: createHash("sha256").update(JSON.stringify({ denyPaths, allowPaths, protectPaths })).digest("hex"),
+    scope: {
+      deny: denyPaths,
+      allow: allowPaths,
+      protect: protectPaths,
+    },
+    verify: {
+      testCmd: opts.testCmd || task.testCmd || "npm test",
+      buildCmd: opts.buildCmd || task.buildCmd || "npm run build",
+    },
+    riskTier: riskMeta.tier,
+    budgetReservationId: opts.reservationId || null,
+    capabilities: opts.capabilities || ["git:read", "git:diff", "test:run"],
+    createdAt: new Date().toISOString(),
+  };
+
+  const envelopeHash = hashExecutionEnvelope(rawEnvelope);
+  const fullEnvelope = { ...rawEnvelope, hash: envelopeHash };
+
+  return freezeExecutionEnvelope(fullEnvelope);
+}
+
+/**
+ * Validates that an envelope has not been tampered with.
+ */
+export function verifyExecutionEnvelope(envelope) {
+  if (!envelope || !envelope.hash) return false;
+  const expectedHash = hashExecutionEnvelope(envelope);
+  return envelope.hash === expectedHash;
+}

package/src/git.mjs

@@ -16,10 +16,28 @@ function normalizePath(p) {
 
 export function runCmd(command, opts = {}) {
   const cwd = opts.cwd || process.cwd();
+  let binary = "";
+  let args = [];
+
+  if (Array.isArray(command)) {
+    binary = command[0];
+    args = command.slice(1);
+  } else if (typeof command === "string") {
+    const tokens = command.trim().split(/\s+/).filter(Boolean);
+    binary = tokens[0] || "";
+    args = tokens.slice(1);
+  }
+
+  if (!binary) {
+    if (opts.ignoreError) return { status: 0, stdout: "", stderr: "" };
+    throw new GateError("Empty command provided");
+  }
+
   try {
-    const stdout = execFileSync("sh", ["-c", command], {
+    const stdout = execFileSync(binary, args, {
       cwd,
       encoding: "utf-8",
+      shell: false,
       stdio: ["ignore", "pipe", "pipe"],
     });
     return { status: 0, stdout: stdout.trim(), stderr: "" };
@@ -59,7 +77,7 @@ export function git(args = [], opts = {}) {
 }
 
 export function resolveBase(root = process.cwd(), baseRef = "main") {
-  const candidates = [`origin/${baseRef}`, baseRef, `refs/remotes/origin/${baseRef}`, "HEAD"];
+  const candidates = [`origin/${baseRef}`, `refs/remotes/origin/${baseRef}`, baseRef];
   for (const ref of candidates) {
     try {
       const res = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {