jules-orchestrator-kit 0.29.1 → 0.32.0

package/src/remediation.mjs

@@ -0,0 +1,164 @@
+import { readFileSync, existsSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getStateDir, ensureDir } from "./state.mjs";
+import { redactSecrets } from "./security.mjs";
+
+/**
+ * Appends a structured remediation pattern entry to .agent/state/remediations.jsonl
+ * when an OODA repair loop successfully resolves a failure.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} entry - Remediation payload
+ * @param {string} [entry.fingerprint] - SHA-256 failure fingerprint from fingerprintFailureState()
+ * @param {Array<string>} [entry.targetFiles] - Array of affected file paths
+ * @param {string} [entry.symptom] - Error output or failure description
+ * @param {string} [entry.remediationHint] - Actionable fix description or diff summary
+ * @returns {Object} Saved remediation entry
+ */
+export function recordRemediation(root, entry = {}) {
+  const stateDir = getStateDir(root);
+  ensureDir(stateDir);
+  const filePath = join(stateDir, "remediations.jsonl");
+
+  const targetFiles = Array.isArray(entry.targetFiles)
+    ? entry.targetFiles.map((f) => String(f).replace(/\\/g, "/"))
+    : entry.targetFile
+    ? [String(entry.targetFile).replace(/\\/g, "/")]
+    : [];
+
+  const record = {
+    id: entry.id || `rem-${Date.now()}-${randomUUID().substring(0, 8)}`,
+    timestamp: new Date().toISOString(),
+    fingerprint: String(entry.fingerprint || "").trim(),
+    targetFiles,
+    symptom: redactSecrets(String(entry.symptom || "").trim()),
+    remediationHint: redactSecrets(String(entry.remediationHint || "").trim()),
+  };
+
+  appendFileSync(filePath, JSON.stringify(record) + "\n", "utf-8");
+  return record;
+}
+
+/**
+ * Reads and queries remediation records from .agent/state/remediations.jsonl.
+ * Matches by targetFiles (path token overlap) or failure fingerprint.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} [query] - Query parameters
+ * @param {Array<string>} [query.targetFiles] - Files to match against remediations
+ * @param {string} [query.fingerprint] - Fingerprint to match against remediations
+ * @param {number} [query.limit=5] - Maximum number of matching remediations to return
+ * @returns {Array<Object>} List of matching remediation records
+ */
+export function queryRemediations(root, query = {}) {
+  const stateDir = getStateDir(root);
+  const filePath = join(stateDir, "remediations.jsonl");
+
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  const targetFiles = (query.targetFiles || []).map((f) => String(f).replace(/\\/g, "/").toLowerCase());
+  const fingerprint = String(query.fingerprint || "").trim();
+  const limit = Math.max(1, Number(query.limit) || 5);
+
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+    const matches = [];
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (matches.length >= limit) break;
+      try {
+        const record = JSON.parse(lines[i]);
+        if (!record || typeof record !== "object") continue;
+
+        let isMatch = false;
+
+        // Exact fingerprint match
+        if (fingerprint && record.fingerprint === fingerprint) {
+          isMatch = true;
+        }
+
+        // File path match
+        if (!isMatch && targetFiles.length > 0 && Array.isArray(record.targetFiles)) {
+          const recordFiles = record.targetFiles.map((f) => String(f).toLowerCase());
+          for (const tf of targetFiles) {
+            if (recordFiles.some((rf) => rf === tf || rf.endsWith(tf) || tf.endsWith(rf))) {
+              isMatch = true;
+              break;
+            }
+          }
+        }
+
+        // If no filter query was specified, match all records
+        if (!fingerprint && targetFiles.length === 0) {
+          isMatch = true;
+        }
+
+        if (isMatch) {
+          matches.push(record);
+        }
+      } catch (_) {}
+    }
+
+    return matches;
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Harvests a failure state or OODA repair outcome into remediations.jsonl.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} details - Failure details
+ * @param {string} [details.symptom] - Error message or failure trace
+ * @param {string} [details.remediationHint] - Fix description or diff snippet
+ * @param {Array<string>} [details.targetFiles] - Affected target files
+ * @param {string} [details.fingerprint] - Optional fingerprint
+ * @returns {Object|null} Harvested remediation record
+ */
+export function harvestFailureRecord(root, details = {}) {
+  if (!details || (!details.symptom && !details.remediationHint)) {
+    return null;
+  }
+  return recordRemediation(root, {
+    symptom: details.symptom || details.error || "OODA Failure Detected",
+    remediationHint: details.remediationHint || details.solution || details.diff || "Verify contract and run test suite.",
+    targetFiles: details.targetFiles || details.referencedPaths || [],
+    fingerprint: details.fingerprint || "",
+  });
+}
+
+/**
+ * Queries relevant past failure remediations and returns a formatted prompt block
+ * for memory hydration.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} [options]
+ * @param {Array<string>} [options.targetFiles=[]] - Files associated with current task
+ * @param {string} [options.fingerprint=""] - Failure fingerprint
+ * @param {number} [options.limit=3] - Maximum memory records to hydrate
+ * @returns {string} Formatted [LEARNED_REMEDIATIONS_CONTEXT] section string (or empty string if none match)
+ */
+export function hydrateMemory(root, options = {}) {
+  const matches = queryRemediations(root, {
+    targetFiles: options.targetFiles || [],
+    fingerprint: options.fingerprint || "",
+    limit: options.limit || 3,
+  });
+
+  if (!matches || matches.length === 0) {
+    return "";
+  }
+
+  const items = matches.map((m, idx) => {
+    const filesStr = Array.isArray(m.targetFiles) && m.targetFiles.length > 0 ? ` (Files: ${m.targetFiles.join(", ")})` : "";
+    return `${idx + 1}. [Symptom${filesStr}]: ${m.symptom}\n   [Proven Fix]: ${m.remediationHint}`;
+  });
+
+  return `[LEARNED_REMEDIATIONS_CONTEXT]\nThe following historical failure-and-fix patterns were harvested from previous OODA runs in this repository. Avoid repeating these failure modes:\n\n${items.join("\n\n")}`;
+}
+

package/src/security.mjs

@@ -1,4 +1,4 @@
-import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync } from "node:fs";
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync, unlinkSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { randomBytes } from "node:crypto";
 import { normalizePath } from "./config.mjs";
@@ -61,18 +61,26 @@ export function safeAtomicWrite(filePath, content, options = {}) {
   const dir = dirname(filePath);
   const tempFile = join(dir, `.tmp-${basename(filePath)}-${randomBytes(6).toString("hex")}`);
 
-  const fd = openSync(tempFile, "wx", mode);
+  let fd;
   try {
+    fd = openSync(tempFile, "wx", mode);
     writeSync(fd, content, null, encoding);
     if (options.sync !== false) {
       fsyncSync(fd);
     }
-  } finally {
     closeSync(fd);
+    fd = undefined;
+    renameSync(tempFile, filePath);
+    return true;
+  } catch (err) {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch (_) {}
+    }
+    try {
+      if (existsSync(tempFile)) unlinkSync(tempFile);
+    } catch (_) {}
+    throw err;
   }
-
-  renameSync(tempFile, filePath);
-  return true;
 }
 
 export function shannonEntropy(str) {

package/src/stack-detector.mjs

@@ -119,7 +119,10 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     return { ...container, stack: "make", testCmd: "make test", buildCmd: "make build", triggerFile: "Makefile" };
   }
 
-  // 5. Python / Elixir / Ruby / Java
+  // 5. Python / Django / Elixir / Ruby / Java
+  if (existsSync(join(projectRoot, "manage.py"))) {
+    return { ...container, stack: "django", testCmd: "python manage.py test --keepdb", buildCmd: "python manage.py check", triggerFile: "manage.py" };
+  }
   if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
     const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";
     return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile };
@@ -138,14 +141,21 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     return { ...container, stack: "gradle", testCmd: "./gradlew test", buildCmd: "./gradlew assemble", triggerFile };
   }
 
-  // 6. JS / TS Runtimes
+  // 6. JS / TS Runtimes & ORMs (Prisma, Drizzle)
+  let setupCmd = "";
+  if (existsSync(join(projectRoot, "prisma", "schema.prisma"))) {
+    setupCmd = "npx prisma db push --schema=prisma/schema.prisma";
+  } else if (existsSync(join(projectRoot, "drizzle.config.ts")) || existsSync(join(projectRoot, "drizzle.config.js"))) {
+    setupCmd = "npx drizzle-kit push";
+  }
+
   if (existsSync(join(projectRoot, "bunfig.toml")) || existsSync(join(projectRoot, "bun.lockb"))) {
     const triggerFile = existsSync(join(projectRoot, "bunfig.toml")) ? "bunfig.toml" : "bun.lockb";
-    return { ...container, stack: "bun", testCmd: "bun test", buildCmd: "bun run build", triggerFile };
+    return { ...container, stack: "bun", setupCmd, testCmd: "bun test", buildCmd: "bun run build", triggerFile };
   }
   if (existsSync(join(projectRoot, "deno.json")) || existsSync(join(projectRoot, "deno.jsonc"))) {
     const triggerFile = existsSync(join(projectRoot, "deno.json")) ? "deno.json" : "deno.jsonc";
-    return { ...container, stack: "deno", testCmd: "deno test", buildCmd: "deno task build", triggerFile };
+    return { ...container, stack: "deno", setupCmd, testCmd: "deno test", buildCmd: "deno task build", triggerFile };
   }
   if (existsSync(join(projectRoot, "package.json"))) {
     let testScript = "npm test";
@@ -161,7 +171,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
       testScript = "npm test";
       buildScript = "npm run build";
     }
-    return { ...container, stack: "node", testCmd: testScript, buildCmd: buildScript, triggerFile: "package.json" };
+    return { ...container, stack: "node", setupCmd, testCmd: testScript, buildCmd: buildScript, triggerFile: "package.json" };
   }
 
   // 7. .NET / C# / F# / PHP / Python root file extension fallback

package/src/state.mjs

@@ -10,10 +10,20 @@ import {
   fsyncSync,
   unlinkSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { hostname } from "node:os";
 import { resolveRoot } from "./config.mjs";
+import { redactSecrets } from "./security.mjs";
+
+function scrubStateValue(value) {
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map(scrubStateValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, scrubStateValue(child)]));
+  }
+  return value;
+}
 
 export function ensureDir(dirPath) {
   if (!dirPath || typeof dirPath !== "string" || dirPath.includes("\0")) {
@@ -109,7 +119,7 @@ export function appendLedger(entry, rootOrOpts = resolveRoot()) {
     }
 
     const timestamp = new Date().toISOString();
-    const rawPayload = { timestamp, ...entry, prevHash };
+    const rawPayload = { timestamp, ...scrubStateValue(entry), prevHash };
     const hash = createHash("sha256").update(JSON.stringify(rawPayload)).digest("hex");
     const payload = { ...rawPayload, hash };
 
@@ -321,7 +331,17 @@ export async function withBudget(fn, root = resolveRoot(), limit = 300) {
     if (err && typeof err === "object") {
       err.reservationId = reservation.reservationId;
     }
-    appendLedger({ event: "budget_reservation_failed", reservationId: reservation.reservationId, error: err.message }, root);
+    try {
+      rollbackBudgetReservation(root, reservation.reservationId);
+      if (err && typeof err === "object") err.budgetReservationRolledBack = true;
+    } catch (_) {}
+    try {
+      appendLedger({
+        event: "budget_reservation_failed",
+        reservationId: reservation.reservationId,
+        error: err?.message || String(err),
+      }, root);
+    } catch (_) {}
     throw err;
   }
 }
@@ -363,8 +383,8 @@ export function isPidAlive(pid, expectedStartTime = null) {
   if (!pid || typeof pid !== "number") return false;
   try {
     process.kill(pid, 0);
-  } catch (_) {
-    return false;
+  } catch (err) {
+    if (err?.code !== "EPERM") return false;
   }
 
   if (expectedStartTime !== null && expectedStartTime !== undefined && process.platform === "linux") {
@@ -381,7 +401,14 @@ export function isPidAlive(pid, expectedStartTime = null) {
   return true;
 }
 
+function assertSafeTaskId(taskId) {
+  if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || basename(taskId) !== taskId) {
+    throw new Error("Invalid task id for lock path");
+  }
+}
+
 export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot(), opts = {}) {
+  assertSafeTaskId(taskId);
   const root = typeof rootOrOpts === "string" ? rootOrOpts : (rootOrOpts?.root || resolveRoot());
   const branch = (typeof rootOrOpts === "object" && rootOrOpts?.branch) || opts?.branch || process.env.JULES_BRANCH || process.env.BRANCH_NAME || "";
   const lockDir = getLockDir(root);
@@ -405,11 +432,13 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   }
 
   const startTime = getProcessStartTime(process.pid);
+  const concurrencyGroup = String(opts?.concurrencyGroup || opts?.concurrency_group || "").trim();
   const payload = {
     agent: agentName,
     taskId,
     branch,
     files,
+    concurrencyGroup,
     pid: process.pid,
     processStartTime: startTime,
     starttime: startTime,
@@ -418,11 +447,11 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     acquiredAt: new Date().toISOString(),
   };
 
+  let fd;
   try {
-    const fd = openSync(lockFile, "wx");
+    fd = openSync(lockFile, "wx");
     writeSync(fd, JSON.stringify(payload, null, 2), "utf-8");
     fsyncSync(fd);
-    closeSync(fd);
     return { ok: true, lockFile };
   } catch (err) {
     if (err.code === "EEXIST") {
@@ -433,11 +462,21 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
         return { ok: false, holder: "unknown", taskId };
       }
     }
+    try { unlinkSync(lockFile); } catch (_) {}
     throw err;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch (_) {}
+    }
   }
 }
 
 export function releaseLock(taskId, rootOrOpts = resolveRoot()) {
+  try {
+    assertSafeTaskId(taskId);
+  } catch (_) {
+    return false;
+  }
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const lockDir = getLockDir(root);
   const lockFile = join(lockDir, `${taskId}.json`);
@@ -469,3 +508,28 @@ export function lockStatus(rootOrOpts = resolveRoot()) {
   return locks;
 }
 
+/**
+ * Checks if a specific concurrency group is currently locked by an active task session.
+ *
+ * @param {string} groupName - Concurrency group name
+ * @param {string|Object} [rootOrOpts=resolveRoot()] - Project root path or options
+ * @param {string} [excludeTaskId=""] - Optional task ID to exclude from check
+ * @returns {boolean} True if group is active/locked
+ */
+export function isConcurrencyGroupLocked(groupName, rootOrOpts = resolveRoot(), excludeTaskId = "") {
+  if (!groupName || typeof groupName !== "string" || !groupName.trim()) {
+    return false;
+  }
+  const targetGroup = groupName.trim().toLowerCase();
+  const locks = lockStatus(rootOrOpts);
+  for (const lock of locks) {
+    if (excludeTaskId && lock.taskId === excludeTaskId) continue;
+    const lockGroup = String(lock.concurrencyGroup || lock.concurrency_group || "").trim().toLowerCase();
+    if (lockGroup === targetGroup) {
+      return true;
+    }
+  }
+  return false;
+}
+
+