jules-orchestrator-kit 0.9.4 → 0.21.0

package/index.mjs

@@ -5,7 +5,7 @@
  * security auditing, repo gating, and state operations.
  */
 
-export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath } from "./src/config.mjs";
+export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath, TIER_PRESETS } from "./src/config.mjs";
 export {
   shannonEntropy,
   redactSecrets,
@@ -19,14 +19,23 @@ export { createProvider, JULES_PRESET, CLAUDE_PRESET, CODEX_PRESET } from "./src
 export {
   appendLedger,
   readLedger,
+  verifyLedgerIntegrity,
+  reserveBudget,
+  commitBudgetReservation,
   withBudget,
   checkDailyBudget,
   acquireLock,
   releaseLock,
   lockStatus,
 } from "./src/state.mjs";
-export { gate, dispatch, repair, run } from "./src/engine.mjs";
+export { gate, dispatch, repair, run, fingerprintFailureState } from "./src/engine.mjs";
 export { validateEnvelope } from "./src/envelope.mjs";
+export {
+  createExecutionEnvelope,
+  verifyExecutionEnvelope,
+  freezeExecutionEnvelope,
+  hashExecutionEnvelope,
+} from "./src/execution_envelope.mjs";
 export { checkAssetIntegrity } from "./src/asset_integrity.mjs";
 export { classifyRiskTier, RISK_TIERS } from "./src/risk.mjs";
 export { checkRulesBudget } from "./src/rules_budget.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.9.4",
+  "version": "0.21.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
@@ -58,6 +58,7 @@
     "jules:check-asset-integrity": "node scripts/asset-integrity-check.mjs",
     "jules:risk-tier": "node scripts/risk-tier.mjs",
     "jules:rules-lint": "node scripts/rules-lint.mjs",
+    "release": "node scripts/release.mjs",
     "lint": "eslint ."
   },
   "engines": {

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/scripts/release.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Automated Release Orchestrator script for jules-orchestrator-kit.
+ * Verifies test suite, updates git tags, and creates GitHub Release via gh CLI.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { resolveRoot } from "../src/config.mjs";
+
+const root = resolveRoot();
+const pkgPath = join(root, "package.json");
+const changelogPath = join(root, "CHANGELOG.md");
+
+if (!existsSync(pkgPath)) {
+  console.error("❌ Error: package.json not found.");
+  process.exit(1);
+}
+
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+const version = pkg.version;
+const tagName = `v${version}`;
+
+console.log(`🚀 Automated Release Pipeline for ${pkg.name} (${tagName})`);
+console.log("-------------------------------------------------------");
+
+// 1. Verify test suite
+console.log("1. Running unit test verification suite...");
+try {
+  execSync("npm test", { cwd: root, stdio: "inherit" });
+  console.log("   ✅ Test suite passed cleanly.\n");
+} catch (err) {
+  console.error("❌ Release Aborted: Test suite failed.");
+  process.exit(1);
+}
+
+// 2. Extract release notes from CHANGELOG.md
+console.log(`2. Extracting release notes for ${tagName} from CHANGELOG.md...`);
+let notes = "";
+if (existsSync(changelogPath)) {
+  const changelog = readFileSync(changelogPath, "utf-8");
+  const regex = new RegExp(`## \\[${version}\\][^\\n]*\\n([\\s\\S]*?)(?=\\n## \\[|$)`, "i");
+  const match = changelog.match(regex);
+  if (match && match[1]) {
+    notes = match[1].trim();
+  }
+}
+
+if (!notes) {
+  notes = `Release ${tagName}`;
+  console.log("   ⚠️ Warning: Release entry not found in CHANGELOG.md, using default title.");
+} else {
+  console.log("   ✅ Extracted release notes from CHANGELOG.md.\n");
+}
+
+// 3. Create Git Tag if not exists
+console.log(`3. Checking Git tag ${tagName}...`);
+try {
+  const tags = execSync("git tag -l", { cwd: root, encoding: "utf-8" });
+  if (tags.split("\n").includes(tagName)) {
+    console.log(`   ℹ️ Git tag ${tagName} already exists.`);
+  } else {
+    execSync(`git tag -a ${tagName} -m "${pkg.name} ${tagName}"`, { cwd: root, stdio: "inherit" });
+    console.log(`   ✅ Created Git tag ${tagName}.`);
+  }
+} catch (err) {
+  console.error(`❌ Tagging failed: ${err.message}`);
+  process.exit(1);
+}
+
+// 4. Push git commits and tag to origin
+console.log(`4. Pushing main and tag ${tagName} to origin...`);
+try {
+  execSync("git push origin main", { cwd: root, stdio: "inherit" });
+  execSync(`git push origin ${tagName}`, { cwd: root, stdio: "inherit" });
+  console.log("   ✅ Pushed commits and tag to origin.\n");
+} catch (err) {
+  console.error(`❌ Push failed: ${err.message}`);
+  process.exit(1);
+}
+
+// 5. Create GitHub Release via gh CLI
+console.log(`5. Creating GitHub Release via gh CLI...`);
+try {
+  const notesFile = join(root, ".agent", "temp_release_notes.txt");
+  const fs = await import("node:fs");
+  fs.writeFileSync(notesFile, notes, "utf-8");
+  
+  execSync(`gh release create ${tagName} --title "${tagName}" --notes-file "${notesFile}"`, {
+    cwd: root,
+    stdio: "inherit",
+  });
+  
+  if (fs.existsSync(notesFile)) fs.unlinkSync(notesFile);
+  console.log(`   🎉 GitHub Release ${tagName} created successfully!`);
+} catch (err) {
+  console.log(`   ℹ️ Note: gh release creation finished or already exists.`);
+}
+
+console.log("-------------------------------------------------------");
+console.log(`✅ Release ${tagName} Completed Successfully!\n`);

package/src/config.mjs

@@ -278,10 +278,37 @@ 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.
  */
 export function loadConfig(root = resolveRoot(), explicitPath = null) {
+  if (root === null || root === undefined) {
+    root = resolveRoot();
+  }
   const candidates = explicitPath
     ? [explicitPath]
     : [join(root, ".agent/config.yml"), join(root, ".agent/jules.yml")];
@@ -301,9 +328,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 !== undefined ? Number(process.env.JULES_DAILY_BUDGET) : null;
+  const envDiffKb = process.env.JULES_MAX_DIFF_KB !== undefined ? 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 +345,10 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     scope: normalizeScope(parsed),
     limits: {
       ...DEFAULTS.limits,
+      ...tierLimits,
       ...(parsed.limits || {}),
+      ...(envDailyTasks !== null && !isNaN(envDailyTasks) ? { dailyTasks: envDailyTasks } : {}),
+      ...(envDiffKb !== null && !isNaN(envDiffKb) ? { diffKb: envDiffKb } : {}),
     },
     isolation: parsed.isolation || DEFAULTS.isolation,
     runner: parsed.runner || DEFAULTS.runner,

package/src/engine.mjs

@@ -5,6 +5,38 @@ 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(/[\u001b\x1b]\[[0-9;]*[a-zA-Z]/g, "")
+    .replace(/\?[^\s"'\)\\]+/g, "<?>")
+    .replace(/:\d+:\d+/g, ":?:?")
+    .replace(/:\d+/g, ":?")
+    .replace(/\bline \d+/gi, "line ?")
+    .replace(/\bcol(umn)? \d+/gi, "col ?")
+    .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 +138,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 +232,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 +256,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.