jules-orchestrator-kit 0.7.0 → 0.8.1

package/.env.example

@@ -27,6 +27,9 @@ JULES_REPO=owner/repo
 # Allow modifications to command-defining files (package.json, Cargo.toml, etc.) in PRs (Default: false)
 # JULES_ALLOW_COMMAND_FILE_CHANGES=false
 
+# Allow modifications to agent rule files (AGENTS.md, JULES_RULES_TEMPLATE.md, .agent/rules/**) in PRs (Default: false)
+# JULES_ALLOW_AGENT_RULE_CHANGES=false
+
 # --- Execution Scope & Git ---
 # Base Branch for PR Audits & Merge-Base Calculations (Default: main)
 BASE_BRANCH=main

package/README.md

@@ -167,7 +167,8 @@ All commands are registered in `package.json` and can be run via `npm run <comma
 | `JULES_REPOLESS` | Set to `true` or `1` to run in repoless/serverless mode |
 | `JULES_DRY_RUN` | Set to `true` or `1` to simulate dispatching without making API calls |
 | `JULES_DAILY_BUDGET` | Daily max session budget for autonomous dispatches (Default: `300`) |
-| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Set to `true` to allow PR changes to command-defining files like `package.json` (Default: `false`) |
+| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Set to `true` to allow PR changes to command/config files like `package.json`, `tsconfig.json`, `vite.config.ts` (Default: `false`) |
+| `JULES_ALLOW_AGENT_RULE_CHANGES` | Set to `true` to allow PR changes to agent rule files like `AGENTS.md`, `JULES_RULES_TEMPLATE.md` (Default: `false`) |
 | `BASE_BRANCH` | Base branch for PR Audits & Merge-Base calculations (Default: `main`) |
 | `GITHUB_HEAD_REF` | PR Head Branch (Used dynamically by CI during OODA repair) |
 | `JULES_PROJECT_ROOT` | Root directory of the project (Auto-assigned during swarm executions) |

package/bin/init.js

@@ -265,6 +265,9 @@ const requiredGitignoreEntries = [
   ".env",
   ".agent/history/",
   ".agent/state/",
+  ".agent/jules-queue/.state/",
+  ".agent/jules-queue/failed/",
+  ".agent/jules-queue/.processing/",
   ".agent/jules-queue/*.md",
   "!.agent/jules-queue/README.md"
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/scripts/command-resolver.mjs

@@ -44,6 +44,23 @@ export function resolveProjectCommands(projectRoot = process.cwd()) {
     }
   }
 
+function detectPackageManager(root, pkg = {}) {
+  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(root, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(root, "bun.lockb"))) return "bun";
+  if (fs.existsSync(path.join(root, "package-lock.json"))) return "npm";
+
+  const pm = pkg.packageManager;
+  if (typeof pm === "string") {
+    if (pm.startsWith("pnpm")) return "pnpm";
+    if (pm.startsWith("yarn")) return "yarn";
+    if (pm.startsWith("bun")) return "bun";
+    if (pm.startsWith("npm")) return "npm";
+  }
+
+  return "npm";
+}
+
   // 2. Dynamic Detector Strategy List
   const detectors = [
     {
@@ -59,20 +76,21 @@ export function resolveProjectCommands(projectRoot = process.cwd()) {
       resolve: (root) => {
         try {
           const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
+          const pm = detectPackageManager(root, pkg);
           const scripts = pkg.scripts || {};
-          let verifyScript = scripts["check:all"] ? "npm run check:all" : "";
+          let verifyScript = scripts["check:all"] ? `${pm} run check:all` : "";
           if (!verifyScript) {
             const parts = [];
-            if (scripts.lint) parts.push("npm run lint");
-            else if (scripts.check) parts.push("npm run check");
-            if (scripts.test) parts.push("npm test");
+            if (scripts.lint) parts.push(`${pm} run lint`);
+            else if (scripts.check) parts.push(`${pm} run check`);
+            if (scripts.test) parts.push(`${pm} test`);
             verifyScript = parts.join(" && ");
           }
-          const buildScript = scripts.build ? "npm run build" : "";
+          const buildScript = scripts.build ? `${pm} run build` : "";
           return {
-            testCmd: verifyScript || "npm test",
+            testCmd: verifyScript || `${pm} test`,
             buildCmd: buildScript,
-            source: "package.json",
+            source: `package.json (${pm})`,
           };
         } catch (err) {
           console.warn("⚠️ Failed to parse package.json:", err.message);

package/scripts/jules-queue-runner.mjs

@@ -183,20 +183,26 @@ async function runQueue() {
           logQueueState(file, "FAILED", error);
 
           const failureClass = classifyQueueFailure(error);
-          const NON_RETRYABLE = new Set(["security_violation", "diff_too_large", "budget_exhausted"]);
+          const NON_RETRYABLE = new Set(["security_violation", "diff_too_large"]);
 
           const taskState = getTaskState(file);
-          const attempts = (taskState.attempts || 0) + 1;
 
-          if (NON_RETRYABLE.has(failureClass) || attempts >= 3) {
-            const destPath = path.join(failedDir, file);
-            setTaskState(file, { attempts, status: "FAILED_PERMANENT", failure_class: failureClass, last_error: error.message, updated_at: new Date().toISOString() });
-            try { await safeMoveAsync(processingPath, destPath); } catch (_) {}
-            log.error(`Task [${title}] failed (${failureClass}). Moved to failed/. Error: ${error.message}`);
-          } else {
-            setTaskState(file, { attempts, status: "REQUEUED", failure_class: failureClass, last_error: error.message, updated_at: new Date().toISOString() });
+          if (failureClass === "budget_exhausted") {
+            setTaskState(file, { attempts: taskState.attempts || 0, status: "DEFERRED_BUDGET", failure_class: failureClass, last_error: error.message, updated_at: new Date().toISOString() });
             try { await safeMoveAsync(processingPath, filePath); } catch (_) {}
-            log.warn(`Task [${title}] failed (${failureClass}). Re-queued (Attempt ${attempts}/3). Error: ${error.message}`);
+            log.warn(`Task [${title}] deferred due to daily budget limit. Left in queue for next budget reset.`);
+          } else {
+            const attempts = (taskState.attempts || 0) + 1;
+            if (NON_RETRYABLE.has(failureClass) || attempts >= 3) {
+              const destPath = path.join(failedDir, file);
+              setTaskState(file, { attempts, status: "FAILED_PERMANENT", failure_class: failureClass, last_error: error.message, updated_at: new Date().toISOString() });
+              try { await safeMoveAsync(processingPath, destPath); } catch (_) {}
+              log.error(`Task [${title}] failed (${failureClass}). Moved to failed/. Error: ${error.message}`);
+            } else {
+              setTaskState(file, { attempts, status: "REQUEUED", failure_class: failureClass, last_error: error.message, updated_at: new Date().toISOString() });
+              try { await safeMoveAsync(processingPath, filePath); } catch (_) {}
+              log.warn(`Task [${title}] failed (${failureClass}). Re-queued (Attempt ${attempts}/3). Error: ${error.message}`);
+            }
           }
         }
       })

package/scripts/jules-self-audit.mjs

@@ -208,6 +208,22 @@ export function parseAndCleanStderr(stderrStr) {
   return lines.slice(-100).join("\n");
 }
 
+export function getOodaStateFile(mergeBase = "main") {
+  const oodaDir = path.resolve(process.cwd(), ".agent/state/ooda");
+  if (!fs.existsSync(oodaDir)) fs.mkdirSync(oodaDir, { recursive: true });
+
+  const keyInput = [
+    process.env.GITHUB_REPOSITORY || "",
+    process.env.GITHUB_REF || "",
+    process.env.GITHUB_HEAD_REF || "",
+    mergeBase,
+    process.cwd()
+  ].join("\u0000");
+
+  const key = crypto.createHash("sha256").update(keyInput).digest("hex").slice(0, 16);
+  return path.join(oodaDir, `${key}.json`);
+}
+
 export function logAuditMetrics(metrics) {
   const historyDir = path.resolve(process.cwd(), ".agent/history");
   if (!fs.existsSync(historyDir)) {
@@ -275,7 +291,9 @@ export function runSelfAudit() {
 
   if (commandFileChanges.length > 0 && process.env.JULES_ALLOW_COMMAND_FILE_CHANGES !== "true" && process.env.JULES_ALLOW_COMMAND_FILE_CHANGES !== "1") {
     const err = new Error(
-      "COMMAND FILE CHANGE DETECTED: " + commandFileChanges.join(", ") + ". Refusing to execute verification scripts from untrusted branch."
+      "COMMAND / BUILD CONFIG FILE CHANGE DETECTED: [" + commandFileChanges.join(", ") + "]. " +
+      "Refusing to execute verification scripts from untrusted branch. " +
+      "To override for legitimate dependency updates, set JULES_ALLOW_COMMAND_FILE_CHANGES=true."
     );
     err.code = 3;
     throw err;
@@ -287,7 +305,9 @@ export function runSelfAudit() {
 
   if (agentRuleChanges.length > 0 && process.env.JULES_ALLOW_AGENT_RULE_CHANGES !== "true" && process.env.JULES_ALLOW_AGENT_RULE_CHANGES !== "1") {
     const err = new Error(
-      "AGENT RULE FILE CHANGE DETECTED: " + agentRuleChanges.join(", ") + ". Refusing to load agent rules from untrusted branch."
+      "AGENT RULE FILE CHANGE DETECTED: [" + agentRuleChanges.join(", ") + "]. " +
+      "Refusing to load agent rules from untrusted branch. " +
+      "To override for legitimate rule updates, set JULES_ALLOW_AGENT_RULE_CHANGES=true."
     );
     err.code = 3;
     throw err;
@@ -442,22 +462,6 @@ export function runSelfAudit() {
       throw err;
     }
 
-function getOodaStateFile(mergeBase = "main") {
-  const oodaDir = path.resolve(process.cwd(), ".agent/state/ooda");
-  if (!fs.existsSync(oodaDir)) fs.mkdirSync(oodaDir, { recursive: true });
-
-  const keyInput = [
-    process.env.GITHUB_REPOSITORY || "",
-    process.env.GITHUB_REF || "",
-    process.env.GITHUB_HEAD_REF || "",
-    mergeBase,
-    process.cwd()
-  ].join("\u0000");
-
-  const key = crypto.createHash("sha256").update(keyInput).digest("hex").slice(0, 16);
-  return path.join(oodaDir, `${key}.json`);
-}
-
     let oodaRetries = 0;
     const oodaStateFile = getOodaStateFile(mergeBase);
     try {

package/scripts/jules-status.mjs

@@ -1,17 +1,18 @@
-#!/usr/bin/env node
-/**
- * Jules Task Status Utility
- * Parses the queue.jsonl file and renders a clean console.table
- */
-
 import fs from "node:fs";
 import path from "node:path";
-import { log } from "./utils.mjs";
+import { log, checkDailyBudget } from "./utils.mjs";
 
+const isJson = process.argv.includes("--json");
 const queueLogPath = path.resolve(process.cwd(), ".agent/jules-queue/queue.jsonl");
 
+const budgetInfo = checkDailyBudget();
+
 if (!fs.existsSync(queueLogPath)) {
-  log.info("Queue log is empty. No tasks have been dispatched yet.");
+  if (isJson) {
+    console.log(JSON.stringify({ queue: [], budget: budgetInfo }, null, 2));
+  } else {
+    log.info("Queue log is empty. No tasks have been dispatched yet.");
+  }
   process.exit(0);
 }
 
@@ -20,7 +21,11 @@ try {
   const lines = content.split("\n").filter(Boolean);
   
   if (lines.length === 0) {
-    log.info("Queue log is empty.");
+    if (isJson) {
+      console.log(JSON.stringify({ queue: [], budget: budgetInfo }, null, 2));
+    } else {
+      log.info("Queue log is empty.");
+    }
     process.exit(0);
   }
 
@@ -32,10 +37,11 @@ try {
       const entry = JSON.parse(line);
       if (entry.file) {
         statusMap.set(entry.file, {
+          file: entry.file,
           Task: entry.file.replace(/^TASK-\d+-/, "").replace(/\.md$/, ""),
           Status: entry.status,
-          Timestamp: new Date(entry.timestamp).toLocaleString(),
-          Error: entry.error || "-"
+          Timestamp: entry.timestamp,
+          Error: entry.error || null
         });
       }
     } catch (e) {
@@ -43,15 +49,26 @@ try {
     }
   }
 
-  if (statusMap.size === 0) {
+  const tasksList = Array.from(statusMap.values());
+
+  if (isJson) {
+    console.log(JSON.stringify({ queue: tasksList, budget: budgetInfo }, null, 2));
+    process.exit(0);
+  }
+
+  if (tasksList.length === 0) {
     log.info("No parseable task events found in queue.jsonl");
     process.exit(0);
   }
 
-  log.header("Jules Queue Status");
-  console.table(Array.from(statusMap.values()));
+  log.header(`JULES QUEUE STATUS (Budget: ${budgetInfo.used}/${budgetInfo.budget} sessions used)`);
+  console.table(tasksList.map(t => ({ Task: t.Task, Status: t.Status, Timestamp: new Date(t.Timestamp).toLocaleString(), Error: t.Error || "-" })));
 
 } catch (err) {
-  log.error(`Failed to read queue log: ${err.message}`);
+  if (isJson) {
+    console.log(JSON.stringify({ error: err.message }, null, 2));
+  } else {
+    log.error(`Failed to read queue log: ${err.message}`);
+  }
   process.exit(1);
 }

package/scripts/jules-swarm.mjs

@@ -194,8 +194,8 @@ async function runSwarm() {
             env: {
               ...process.env,
               JULES_PROJECT_ROOT: process.env.JULES_PROJECT_ROOT,
-              JULES_SLOT_INDEX: String(bIdx + 1),
-              JULES_SLOT_TOTAL: String(batch.length)
+              JULES_SLOT_INDEX: String(taskNum),
+              JULES_SLOT_TOTAL: String(tasks.length)
             },
           });
           if (stdout) log.dim(stdout.trim());

package/scripts/utils.mjs

@@ -165,10 +165,34 @@ export function redactSecrets(text) {
   return sanitized;
 }
 
-export function appendLedger(ledgerName, payload) {
-  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state");
+export function pruneOldLedgers(stateDir, retentionDays = 30) {
+  try {
+    if (!fs.existsSync(stateDir)) return;
+    const now = Date.now();
+    const maxAgeMs = retentionDays * 24 * 60 * 60 * 1000;
+    const files = fs.readdirSync(stateDir);
+    files.forEach((file) => {
+      if (file.endsWith(".jsonl")) {
+        const filePath = path.join(stateDir, file);
+        const stat = fs.statSync(filePath);
+        if (now - stat.mtimeMs > maxAgeMs) {
+          try { fs.unlinkSync(filePath); } catch (_) {}
+        }
+      }
+    });
+  } catch (_) {}
+}
+
+export function getDailyLedgerPath(ledgerName = "sessions") {
+  const dateStr = new Date().toISOString().split("T")[0];
+  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state", ledgerName);
   ensureDir(stateDir);
-  const ledgerPath = path.join(stateDir, `${ledgerName}.jsonl`);
+  pruneOldLedgers(stateDir, 30);
+  return path.join(stateDir, `${dateStr}.jsonl`);
+}
+
+export function appendLedger(ledgerName, payload) {
+  const ledgerPath = getDailyLedgerPath(ledgerName);
   const entry = JSON.stringify({
     timestamp: new Date().toISOString(),
     ...payload
@@ -178,34 +202,30 @@ export function appendLedger(ledgerName, payload) {
 }
 
 export function checkDailyBudget(maxSessions = 300) {
-  const dateStr = new Date().toISOString().split("T")[0];
-  const stateDir = path.resolve(process.env.JULES_PROJECT_ROOT || process.cwd(), ".agent/state");
-  const sessionsLedger = path.join(stateDir, "sessions.jsonl");
+  const ledgerPath = getDailyLedgerPath("sessions");
   
-  if (!fs.existsSync(sessionsLedger)) {
+  if (!fs.existsSync(ledgerPath)) {
     return { ok: true, used: 0, budget: maxSessions };
   }
 
-  const content = fs.readFileSync(sessionsLedger, "utf-8");
+  const content = fs.readFileSync(ledgerPath, "utf-8");
   const lines = content.split("\n").filter(Boolean);
   
   let usedToday = 0;
   for (const line of lines) {
     try {
       const entry = JSON.parse(line);
-      if (
-        entry.timestamp &&
-        entry.timestamp.startsWith(dateStr) &&
-        (entry.event === "budget_reserved" || !entry.event)
-      ) {
+      if (entry.event === "budget_reserved" || !entry.event) {
         usedToday++;
       }
-    } catch (e) {
-      // Ignore
-    }
+    } catch (_) {}
   }
 
-  return { ok: usedToday < maxSessions, used: usedToday, budget: maxSessions };
+  return {
+    ok: usedToday < maxSessions,
+    used: usedToday,
+    budget: maxSessions
+  };
 }
 
 function sleepSync(ms) {