jules-orchestrator-kit 0.5.1 → 0.5.2

package/.env.example

@@ -1,17 +1,63 @@
 # Google Jules Orchestration Kit - Environment Configuration Example
 # Copy this file to .env and populate with your credentials/settings.
 
+# --- Authentication & Core Settings ---
 # Google Jules API Key (Required for direct REST API dispatches)
 JULES_API_KEY=your_google_jules_api_key_here
 
+# Alias for API key (fallback if JULES_API_KEY is not set)
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# Override the Jules REST API URL
+# JULES_API_URL=https://jules.googleapis.com/v1alpha/sessions
+
 # Target GitHub Repository (Format: owner/repo)
-JULES_REPO=FullThrottle83/jules-orchestrator-kit
+JULES_REPO=owner/repo
+
+# Set to "true" or "1" to run in repoless/serverless mode
+# JULES_REPOLESS=false
+
+# Enable Dry-Run mode to simulate payload dispatch without making API calls
+# JULES_DRY_RUN=false
 
+# --- Execution Scope & Git ---
 # Base Branch for PR Audits & Merge-Base Calculations (Default: main)
 BASE_BRANCH=main
 
-# Swarm Concurrency Limit (Maximum parallel dispatches, default: 3)
+# PR Head Branch (Used by CI to dynamically target branches during OODA repair)
+# GITHUB_HEAD_REF=my-feature-branch
+
+# Root directory of the project (Auto-assigned during swarm executions)
+# JULES_PROJECT_ROOT=/path/to/project
+
+# --- Swarm & Concurrency ---
+# Maximum parallel dispatches for swarm runs (Default: 3)
 JULES_SWARM_CONCURRENCY=3
 
-# Swarm Dispatch Stagger Interval in Milliseconds (Default: 1500)
+# Dispatch Stagger Interval in Milliseconds (Default: 1500)
 JULES_SWARM_STAGGER_MS=1500
+
+# Rate-limit for the jules:queue command (Default: 500)
+# JULES_PACE_MS=500
+
+# Use Git Worktrees instead of cloning for swarm isolation
+# JULES_USE_WORKTREES=false
+
+# Current slot index for partitioning tasks (Swarm mode)
+# JULES_SLOT_INDEX=1
+
+# Total number of slots for partitioning tasks (Swarm mode)
+# JULES_SLOT_TOTAL=3
+
+# --- CI & Output ---
+# Is this running in a CI environment? (Changes log output and fail-fast behaviors)
+# CI=true
+
+# Allow OODA Auto-Repair even in CI environments
+# ALLOW_AUTO_REPAIR=true
+
+# GitHub Actions Step Summary File Path
+# GITHUB_STEP_SUMMARY=/path/to/step_summary.md
+
+# Disable color in terminal output
+# NO_COLOR=true

package/.github/workflows/agent-scope-guard.yml

@@ -27,8 +27,8 @@ jobs:
           echo "Checking files modified in PR..."
           MODIFIED_FILES=$(git diff --name-only $BASE_SHA $HEAD_SHA)
           
-          # Read protected paths
-          PROTECTED_PATHS=$(node -e "const paths = require('./.agent/protected-paths.json').protected; console.log(paths.join(' '));")
+          # Read protected paths from origin/main
+          PROTECTED_PATHS=$(node -e "const paths = JSON.parse(require('child_process').execSync('git show origin/main:.agent/protected-paths.json', {encoding:'utf8'})).protected; console.log(paths.join(' '));")
           
           echo "Protected patterns: $PROTECTED_PATHS"
           

package/.github/workflows/jules-audit.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   audit-and-test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['18.x', '20.x', '22.x', '24.x']
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -18,7 +21,10 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: ${{ matrix.node-version }}
+
+      - name: Syntax Check
+        run: node --check scripts/*.mjs bin/*.js
 
       - name: Run Unit Tests
         run: npm test

package/README.md

@@ -60,7 +60,7 @@ npm run jules:status
 - If tests failed, Jules fixed the code and re-ran tests.
 - You'll receive a Pull Request with working, verified code.
 
-> 🔐 **New in v0.3.0 (The Epistemic Bridge)**: The init script generates a cryptographic Handshake Token (`.agent/JULES_WEB_SETUP.md`). Paste this into the Jules Web UI to sync your environment perfectly.
+> 🔐 **New in v0.5.0 (The Epistemic Bridge)**: The init script generates a cryptographic Handshake Token (`.agent/JULES_WEB_SETUP.md`). Paste this into the Jules Web UI to sync your environment perfectly.
 
 ---
 
@@ -193,7 +193,7 @@ allow_paths: []
 | Feature               | What It Does                                 | Example                               |
 | --------------------- | -------------------------------------------- | ------------------------------------- |
 | **Automatic Testing** | Runs test suite against every AI change      | `test_cmd: "npm test"`                |
-| **Self-Fixing**       | Jules automatically corrects failed tests    | Retries up to 4 times before blocking |
+| **Self-Fixing**       | Jules automatically corrects failed tests    | Retries up to 3 times before blocking |
 | **Secret Protection** | Hides API keys, passwords, tokens            | Entropy > 3.6, length ≥ 20            |
 | **Path Restrictions** | Blocks changes to sensitive files            | `.env`, `*.pem`, `.github/**`         |
 | **Scope Boundaries**  | Prevents changes outside task scope          | `scope: ["src/auth/**"]`              |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.5.1",
+  "version": "0.5.2",
+  "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -56,6 +57,6 @@
     "mcp",
     "automation"
   ],
-  "author": "Google Open Source",
+  "author": "FullThrottle83",
   "license": "MIT"
 }

package/scripts/jules-dispatch.mjs

@@ -41,7 +41,9 @@ function loadEnv() {
     }
   }
 }
-loadEnv();
+if (isMainModule) {
+  loadEnv();
+}
 
 // 0.2 Pre-Flight Secret Redaction Gate (RegEx + Env Denylist)
 export function redactSecrets(text) {
@@ -52,7 +54,7 @@ export function redactSecrets(text) {
   for (const [envKey, envVal] of Object.entries(process.env)) {
     if (
       envVal &&
-      envVal.length >= 6 &&
+      envVal.length >= 20 &&
       /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH/i.test(envKey)
     ) {
       if (sanitized.includes(envVal)) {
@@ -155,7 +157,7 @@ if (isMainModule) {
   if (fs.existsSync(possiblePath)) {
     try {
       const verifiedPath = path.resolve(process.cwd(), possiblePath);
-      if (verifiedPath.startsWith(process.cwd())) {
+      if (!path.relative(process.cwd(), verifiedPath).startsWith('..')) {
         const fd = fs.openSync(verifiedPath, "r");
         try {
           const stat = fs.fstatSync(fd);
@@ -269,10 +271,11 @@ async function executeDispatch() {
               "X-Goog-Api-Key": apiKey,
               "Content-Type": "application/json"
             },
-            body: JSON.stringify(payload)
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(30000)
           });
 
-          if (res.ok || res.status === 429) {
+          if (res.ok || res.status === 429 || res.status === 400 || res.status === 401) {
             break;
           }
 
@@ -300,8 +303,17 @@ async function executeDispatch() {
       }
 
       if (res.status === 429) {
-        log.error(`❌ Jules REST API Rate Limit Exceeded (HTTP 429). Will NOT fallback to CLI.`);
-        process.exit(1);
+        const retryAfter = res.headers.get("Retry-After");
+        const err = new Error(`❌ Jules REST API Rate Limit Exceeded (HTTP 429). Retry after: ${retryAfter || 'unknown'}`);
+        err.code = 1;
+        throw err;
+      }
+
+      if (res.status === 400 || res.status === 401) {
+        const errText = await res.text().catch(() => "");
+        const err = new Error(`❌ Jules REST API returned HTTP ${res.status}: ${errText}`);
+        err.code = 1;
+        throw err;
       }
 
       if (!res.ok) {
@@ -350,8 +362,9 @@ function dispatchViaCli(targetRepo, payloadFile, title) {
     execFileSync("jules", args, { input: promptToSend, stdio: ["pipe", "inherit", "inherit"] });
     log.success(`Successfully dispatched task "${title}" to Jules CLI.`);
   } catch (error) {
-    log.error(`Failed to dispatch task to Jules CLI: ${error.message}`);
-    process.exit(1);
+    const err = new Error(`Failed to dispatch task to Jules CLI: ${error.message}`);
+    err.code = 1;
+    throw err;
   }
 }
 

package/scripts/jules-self-audit.mjs

@@ -11,10 +11,9 @@ function runGitCommand(args, ignoreError = false) {
   try {
     return execFileSync("git", args, { encoding: "utf-8" }).trim();
   } catch (error) {
-    if (ignoreError) return "";
-    log.error(`Git command failed: git ${args.join(" ")}`);
-    log.error(error.message);
-    process.exit(1);
+    const err = new Error(`Git command failed: git ${args.join(" ")}\n${error.message}`);
+    err.code = 1;
+    throw err;
   }
 }
 
@@ -153,16 +152,18 @@ export function runSelfAudit() {
   const targetBranch = process.env.BASE_BRANCH || "main";
   const SAFE_BRANCH = /^[a-zA-Z0-9._\/-]+$/;
   if (!SAFE_BRANCH.test(targetBranch)) {
-    log.error(`FATAL: Invalid BASE_BRANCH "${targetBranch}". Must match ^[a-zA-Z0-9._\\/-]+$`);
-    process.exit(2);
+    const err = new Error(`FATAL: Invalid BASE_BRANCH "${targetBranch}". Must match ^[a-zA-Z0-9._\\/-]+$`);
+    err.code = 2;
+    throw err;
   }
   log.info(`Target Branch: ${targetBranch}`);
 
   try {
     execFileSync("git", ["--version"], { stdio: "ignore" });
   } catch {
-    log.error("FATAL: git is not installed or not in PATH.");
-    process.exit(2);
+    const err = new Error("FATAL: git is not installed or not in PATH.");
+    err.code = 2;
+    throw err;
   }
 
   if (process.env.CI) {
@@ -180,8 +181,9 @@ export function runSelfAudit() {
   const mergeBase = runGitCommand(["merge-base", "HEAD", mainRef], true);
 
   if (!mergeBase) {
-    log.error(`FATAL: Could not compute merge-base with ${mainRef}. Make sure git history is unshallowed.`);
-    process.exit(2);
+    const err = new Error(`FATAL: Could not compute merge-base with ${mainRef}. Make sure git history is unshallowed.`);
+    err.code = 2;
+    throw err;
   }
 
   log.info(`Merge-Base Hash: ${mergeBase}`);
@@ -211,10 +213,9 @@ export function runSelfAudit() {
   });
 
   if (violations.length > 0) {
-    log.error("RESTRICTED FILE VIOLATION DETECTED!");
-    log.error("Jules PR attempted to modify forbidden system files:");
-    violations.forEach((v) => log.error(`   - ${v}`));
-    process.exit(3);
+    const err = new Error("RESTRICTED FILE VIOLATION DETECTED!");
+    err.code = 3;
+    throw err;
   }
   log.success("Restricted File Boundary Check: PASSED");
 
@@ -254,7 +255,7 @@ export function runSelfAudit() {
 
   if (!resolvedCmds.testCmd && !resolvedCmds.buildCmd) {
     log.info("No build or test scripts found. Running git status check.");
-    runCommand("git status");
+    execSync("git status", { stdio: "inherit" });
   }
 
   const durationMs = Date.now() - startTime;
@@ -270,45 +271,10 @@ export function runSelfAudit() {
     log.error("OODA SELF-HEALING FEEDBACK LOG:");
     log.dim(failureLog.slice(-1500));
 
-    // OODA Circuit Breaker: Fingerprint failure trace using SHA-256
-    const normalizedError = failureLog
-      .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z/g, "TIMESTAMP")
-      .replace(/0x[0-9a-fA-F]+/g, "HEX")
-      .replace(/\d+/g, "NUM")
-      .trim();
-    const errorHash = crypto.createHash("sha256").update(normalizedError).digest("hex");
-
-    const circuitFile = path.resolve(process.cwd(), ".agent/history/ooda-circuit.json");
-    let prevCircuit = { hash: "", count: 0 };
-    if (fs.existsSync(circuitFile)) {
-      try {
-        prevCircuit = JSON.parse(fs.readFileSync(circuitFile, "utf-8"));
-      } catch (_) {}
-    }
-
-    if (prevCircuit.hash === errorHash && prevCircuit.count >= 1) {
-      log.error("❌ OODA CIRCUIT BREAKER TRIPPED: Consecutive identical failure detected.");
-      log.error("Agent generated code with identical error trace twice in a row. Aborting auto-repair.");
-      try {
-        fs.writeFileSync(circuitFile, JSON.stringify({ hash: "", count: 0 }));
-      } catch (_) {}
-      process.exit(4);
-    }
-
-    try {
-      fs.writeFileSync(
-        circuitFile,
-        JSON.stringify({
-          hash: errorHash,
-          count: prevCircuit.hash === errorHash ? prevCircuit.count + 1 : 1,
-          updatedAt: new Date().toISOString()
-        })
-      );
-    } catch (_) {}
-
     if (process.env.CI && !process.env.ALLOW_AUTO_REPAIR) {
-      log.error("CI environment detected and ALLOW_AUTO_REPAIR is not set. Failing fast to save CI minutes.");
-      process.exit(4);
+      const err = new Error("CI environment detected and ALLOW_AUTO_REPAIR is not set. Failing fast to save CI minutes.");
+      err.code = 4;
+      throw err;
     }
 
     let oodaRetries = 0;
@@ -342,28 +308,29 @@ export function runSelfAudit() {
     } else {
       log.error("❌ OODA Auto-Repair exhausted maximum retries (3). Giving up.");
     }
-    
-    process.exit(4);
+    const err = new Error("OODA Auto-Repair failed or exhausted.");
+    err.code = 4;
+    throw err;
   }
 
   log.success("🎉 JULES PR SELF-AUDIT PASSED SUCCESSFULLY!");
 }
 
 export function runPreflightSandbox() {
-  log.header("Initializing Pre-Flight Sandbox (Steril Simulering)...");
+  log.header("Initializing Pre-Flight Sandbox (Sterile Simulation)...");
   
   const runId = crypto.randomBytes(4).toString("hex");
   const sandboxDir = path.join(os.tmpdir(), `jules-preflight-${runId}`);
   const tempArchive = path.join(os.tmpdir(), `jules-archive-${runId}.tar`);
   
   try {
-    log.step("[1/4]", `Skapar isolerad miljö i ${sandboxDir}...`);
+    log.step("[1/5]", `Creating isolated environment in ${sandboxDir}...`);
     fs.mkdirSync(sandboxDir, { recursive: true });
     
     execSync(`git archive HEAD -o "${tempArchive}"`);
     execSync(`tar -xf "${tempArchive}" -C "${sandboxDir}"`);
     
-    log.step("[2/4]", "Steriliserar miljövariabler...");
+    log.step("[2/5]", "Sterilizing environment variables...");
     const sterileEnv = { ...process.env };
     const stripKeys = ["DATABASE_URL", "NPM_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "AWS_ACCESS_KEY_ID", "STRIPE_TEST_KEY"];
     for (const key of stripKeys) {
@@ -372,11 +339,21 @@ export function runPreflightSandbox() {
       }
     }
     
-    log.step("[3/4]", "Löser beroenden i sandlådan...");
+    log.step("[3/5]", "Installing dependencies in sandbox (npm ci)...");
+    const packageJsonPath = path.join(sandboxDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        execSync("npm ci --ignore-scripts", { cwd: sandboxDir, stdio: "ignore" });
+      } catch (e) {
+        log.warn("npm ci failed or wasn't needed. Proceeding...");
+      }
+    }
+
+    log.step("[4/5]", "Resolving execution boundary in sandbox...");
     const resolvedCmds = resolveWorkspaceExecutionBoundary([], sandboxDir);
     
     if (resolvedCmds.testCmd || resolvedCmds.buildCmd) {
-      log.step("[4/4]", `Kör verifiering: ${resolvedCmds.testCmd || resolvedCmds.buildCmd}`);
+      log.step("[5/5]", `Running verification: ${resolvedCmds.testCmd || resolvedCmds.buildCmd}`);
       execSync(resolvedCmds.testCmd || resolvedCmds.buildCmd, {
         cwd: sandboxDir,
         env: sterileEnv,
@@ -384,14 +361,15 @@ export function runPreflightSandbox() {
       });
       log.success("Pre-Flight Passed. Zero epistemic drift detected.");
     } else {
-      log.info("Inga test/bygg-kommandon hittades för verifiering.");
+      log.info("No test/build commands found for verification.");
       log.success("Pre-Flight Passed (No-Op).");
     }
   } catch (err) {
-    log.error("\nPRE-FLIGHT MISSLYCKADES!");
-    log.error("Agenten skulle förmodligen krascha (The 5-Minute Drop-off) i Web UI på grund av saknade beroenden.");
-    log.error(err.message);
-    process.exit(1);
+    log.error("\nPRE-FLIGHT FAILED!");
+    log.error("The agent would likely crash (The 5-Minute Drop-off) in the Web UI due to missing dependencies.");
+    const wrappedErr = new Error(err.message);
+    wrappedErr.code = 1;
+    throw wrappedErr;
   } finally {
     try {
       fs.rmSync(sandboxDir, { recursive: true, force: true });
@@ -406,10 +384,15 @@ export function runPreflightSandbox() {
 
 // Execute when invoked directly from CLI
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
-  if (process.argv.includes("--preflight")) {
-    runPreflightSandbox();
-  } else {
-    runSelfAudit();
+  try {
+    if (process.argv.includes("--preflight")) {
+      runPreflightSandbox();
+    } else {
+      runSelfAudit();
+    }
+  } catch (err) {
+    if (err.message) log.error(err.message);
+    process.exit(err.code || 1);
   }
 }