jules-orchestrator-kit 0.9.4 → 0.20.0

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}`], {

package/src/mcp.mjs

@@ -1,4 +1,4 @@
-import { createInterface } from "node:readline";
+import { Transform } from "node:stream";
 import { loadConfig, resolveRoot, detectStack } from "./config.mjs";
 import { gate, dispatch } from "./engine.mjs";
 import { classifyRiskTier } from "./risk.mjs";
@@ -6,9 +6,86 @@ import { checkDailyBudget, lockStatus } from "./state.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.9.4",
+  version: "0.20.0",
 };
 
+export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
+
+/**
+ * Memory-bounded MCP Frame Decoder supporting both Content-Length headers and line-delimited JSON-RPC messages.
+ */
+export class McpFrameDecoder extends Transform {
+  constructor(options = {}) {
+    super({ ...options, readableObjectMode: true });
+    this.buffer = Buffer.alloc(0);
+    this.maxFrameSize = options.maxFrameSize || MAX_MCP_FRAME_SIZE;
+  }
+
+  _transform(chunk, encoding, callback) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+
+    if (this.buffer.length > this.maxFrameSize * 2) {
+      this.emit("error", new Error(`MCP Stdio buffer exceeded max limit of ${this.maxFrameSize} bytes`));
+      this.buffer = Buffer.alloc(0);
+      return callback();
+    }
+
+    while (this.buffer.length > 0) {
+      const str = this.buffer.toString("utf-8");
+      const headerMatch = /Content-Length:\s*(\d+)\r?\n\r?\n/i.exec(str);
+
+      if (headerMatch) {
+        const contentLength = parseInt(headerMatch[1], 10);
+        if (contentLength > this.maxFrameSize) {
+          this.emit("error", new Error(`Frame Content-Length (${contentLength}) exceeds limit (${this.maxFrameSize})`));
+          this.buffer = Buffer.alloc(0);
+          return callback();
+        }
+
+        const headerLength = headerMatch.index + headerMatch[0].length;
+        const totalFrameLength = headerLength + contentLength;
+
+        if (this.buffer.length >= totalFrameLength) {
+          const payloadBuf = this.buffer.subarray(headerLength, totalFrameLength);
+          this.buffer = this.buffer.subarray(totalFrameLength);
+          try {
+            const parsed = JSON.parse(payloadBuf.toString("utf-8"));
+            this.push(parsed);
+          } catch (err) {
+            this.emit("error", new Error(`Malformed JSON payload in framed message: ${err.message}`));
+          }
+          continue;
+        } else {
+          break;
+        }
+      }
+
+      const newlineIndex = this.buffer.indexOf(0x0a);
+      if (newlineIndex !== -1) {
+        const lineBuf = this.buffer.subarray(0, newlineIndex);
+        this.buffer = this.buffer.subarray(newlineIndex + 1);
+
+        const lineStr = lineBuf.toString("utf-8").trim();
+        if (!lineStr) continue;
+
+        if (/^Content-Length:\s*\d+/i.test(lineStr)) continue;
+
+        try {
+          const parsed = JSON.parse(lineStr);
+          this.push(parsed);
+        } catch (err) {
+          this.emit("error", new Error(`Malformed JSON in line-delimited message: ${err.message}`));
+        }
+        continue;
+      }
+
+      break;
+    }
+
+    callback();
+  }
+}
+
 export const MCP_TOOLS = [
   {
     name: "dispatch_jules_task",
@@ -82,7 +159,7 @@ export async function handleMcpRequest(request, opts = {}) {
   }
 
   if (method === "notifications/initialized") {
-    return null; // Notifications produce no response
+    return null;
   }
 
   if (method === "tools/list") {
@@ -186,26 +263,35 @@ export async function handleMcpRequest(request, opts = {}) {
 }
 
 export function startMcpServer(input = process.stdin, output = process.stdout, opts = {}) {
-  const rl = createInterface({ input, output: null, terminal: false });
-
-  rl.on("line", async (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) return;
+  const decoder = new McpFrameDecoder({ maxFrameSize: opts.maxFrameSize || MAX_MCP_FRAME_SIZE });
 
+  decoder.on("data", async (request) => {
     try {
-      const request = JSON.parse(trimmed);
       const response = await handleMcpRequest(request, opts);
-      if (response !== null) {
+      if (response !== null && response !== undefined) {
         output.write(JSON.stringify(response) + "\n");
       }
     } catch (err) {
+      // Panic boundary: Catch unhandled async exceptions and send valid JSON-RPC error
       output.write(
         JSON.stringify({
           jsonrpc: "2.0",
-          id: null,
-          error: { code: -32700, message: `Parse error: ${err.message}` },
+          id: request?.id || null,
+          error: { code: -32603, message: `Internal server panic: ${err.message}` },
         }) + "\n"
       );
     }
   });
+
+  decoder.on("error", (err) => {
+    output.write(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: `MCP Stream framing error: ${err.message}` },
+      }) + "\n"
+    );
+  });
+
+  input.pipe(decoder);
 }

package/src/process-group.mjs

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+
+/**
+ * ProcessGroupManager manages child processes in isolated process groups
+ * and ensures 100% leak-free cleanup on process exit or termination signals.
+ */
+export class ProcessGroupManager {
+  constructor() {
+    this.activePgids = new Set();
+    this.activePids = new Set();
+    this.installed = false;
+    this.installSignalHandlers();
+  }
+
+  installSignalHandlers() {
+    if (this.installed) return;
+    this.installed = true;
+
+    const cleanup = (signal) => {
+      this.killAll(signal || "SIGTERM");
+    };
+
+    process.once("SIGINT", () => {
+      cleanup("SIGINT");
+      process.exit(130);
+    });
+
+    process.once("SIGTERM", () => {
+      cleanup("SIGTERM");
+      process.exit(143);
+    });
+
+    process.once("exit", () => {
+      this.killAll("SIGKILL");
+    });
+  }
+
+  spawnProcess(command, args = [], options = {}) {
+    const opts = {
+      ...options,
+      detached: true,
+    };
+
+    const child = spawn(command, args, opts);
+
+    if (child.pid) {
+      const pgid = child.pid;
+      this.activePgids.add(pgid);
+      this.activePids.add(child.pid);
+
+      child.on("exit", () => {
+        this.activePgids.delete(pgid);
+        this.activePids.delete(child.pid);
+      });
+
+      child.on("error", () => {
+        this.activePgids.delete(pgid);
+        this.activePids.delete(child.pid);
+      });
+    }
+
+    return child;
+  }
+
+  killAll(signal = "SIGTERM") {
+    for (const pgid of this.activePgids) {
+      try {
+        process.kill(-pgid, signal);
+      } catch (_) {
+        try {
+          process.kill(pgid, signal);
+        } catch (_) {}
+      }
+    }
+    this.activePgids.clear();
+    this.activePids.clear();
+  }
+}
+
+export const processGroupManager = new ProcessGroupManager();

package/src/risk.mjs

@@ -1,4 +1,5 @@
 import { normalizePath } from "./config.mjs";
+import { matchesGlob } from "./security.mjs";
 
 export const RISK_TIERS = {
   R0: "R0_COSMETIC",     // Docs, markdown, comments, safe devDep patches
@@ -54,7 +55,7 @@ export function classifyRiskTier(files = [], opts = {}) {
   for (const rawFile of files) {
     const file = normalizePath(rawFile);
     for (const pat of RESTRICTED_PATH_PATTERNS) {
-      if (file.includes(pat.replace(/\*/g, "")) || file.endsWith(pat)) {
+      if (matchesGlob(file, pat) || file.endsWith(pat)) {
         return {
           tier: RISK_TIERS.R3,
           reason: `Matches restricted security/financial path pattern '${pat}'`,
@@ -78,7 +79,7 @@ export function classifyRiskTier(files = [], opts = {}) {
   for (const rawFile of files) {
     const file = normalizePath(rawFile);
     for (const pat of CONSEQUENTIAL_PATH_PATTERNS) {
-      if (file.includes(pat.replace(/\*/g, ""))) {
+      if (matchesGlob(file, pat)) {
         return {
           tier: RISK_TIERS.R2,
           reason: `Matches consequential component/DB path pattern '${pat}'`,