jules-orchestrator-kit 0.8.0 → 0.8.5

package/.agent/rules/dynamic-guardrails.json

@@ -1,9 +1,5 @@
 {
   "rules": [
-    {
-      "trigger": "\\.astro",
-      "guardrail": "## 🟢 ASTRO GUARDRAILS\n- DO NOT run `biome check --write --unsafe` on `.astro` files (destroys frontmatter).\n- DO NOT import 'sharp' into runtime bundles."
-    },
     {
       "trigger": "\\b(db|database|drizzle|sql\\w*|postgres\\w*|sqlite\\w*|mysql\\w*)\\b",
       "guardrail": "## 🗄️ DATABASE GUARDRAILS\n- Always batch multiple database statements.\n- DO NOT write destructive migrations (`DROP TABLE`) without explicit user consent."

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/.github/workflows/jules-audit.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: ['18.x', '20.x', '22.x', '24.x']
+        node-version: ['22.x', '24.x']
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -23,14 +23,25 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Syntax Check
-        run: for f in scripts/*.mjs bin/*.js index.mjs; do node --check "$f" || exit 1; done
+      - name: Cache OODA state & ledgers
+        uses: actions/cache@v4
+        with:
+          path: .agent/state/
+          key: ooda-state-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            ooda-state-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Linter
+        run: npm run lint --if-present
 
       - name: Run Unit Tests
-        run: npm test
+        run: npm test --if-present
 
       - name: Run Jules PR Self-Audit Gatekeeper
-        if: matrix.node-version == '20.x' && github.event_name == 'pull_request' && (startsWith(github.actor, 'google-labs-jules') || contains(github.actor, 'jules'))
+        if: matrix.node-version == '22.x' && github.event_name == 'pull_request'
         run: node scripts/jules-self-audit.mjs
         env:
           CI: "true"

package/JULES_RULES_TEMPLATE.md

@@ -99,7 +99,7 @@ Follow all rules strictly.
 TASK: <description>
 
 HARD CONSTRAINTS:
-- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, astro.config.mjs, wrangler.jsonc, or .github/ files. Enforced in CI by Agent Scope Guard.
+- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files. Enforced in CI by Agent Scope Guard.
 - Diff Payload Governor: Keep total diff payload under 75 KB (`git diff | wc -c`) to prevent API truncation (~80 KB limit).
 - Verify before finishing: Run full type-check, lint, and unit test suites.
 - BEFORE opening the PR: Run `git fetch origin main && git rebase origin/main`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.

package/README.md

@@ -37,14 +37,89 @@ npm run jules:queue
 
 ## How It Works
 
-1. **You Assign Task:** Define what needs fixing or building.
+1. **You Assign Task:** Define what needs fixing or building (supports text and multimodal image mockups).
 2. **Jules Writes Code:** Proposes changes in an isolated Git worktree sandbox.
 3. **Run Tests & Linters:** The Gatekeeper runs your test suite, linters, and type checks.
 4. **Self-Correction:** If anything fails, Jules automatically retries with fixes (OODA loop).
 5. **Safe Delivery:** Once tests pass, the PR is verified and ready for review.
 
+```mermaid
+sequenceDiagram
+    autonumber
+    
+    box "Client Edge" #F4F4F4
+        actor Trigger as Client (CLI / CI / SDK)
+    end
+    
+    box "Control Plane" #E8F4F8
+        participant Orc as Orchestrator Core
+        participant Gate as Self-Audit Gatekeeper
+    end
+    
+    box "Execution Sandbox" #F8E8E8
+        participant API as Google Jules API
+        participant Git as Git Worktree Sandbox
+    end
+
+    Trigger->>+Orc: Dispatch Task Payload
+    
+    note over Orc,Git: Phase 1: Security Redaction & Provisioning
+    Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
+    Orc->>+Git: Provision Isolation Sandbox (git worktree)
+    Git-->>-Orc: Sandbox Ready
+    
+    loop OODA Repair Cycle (Max 3 Retries)
+        note over Orc,Git: Phase 2: Agent Execution & Dispatch
+        Orc->>+API: Dispatch Task + <MCP_DIRECTIVE> & Target Scope
+        API->>+Git: Apply Proposed Code Changes
+        Git-->>-API: Changes Written
+        API-->>-Orc: Execution Complete
+        
+        note over Orc,Gate: Phase 3: Tiered Verification & Gatekeeping
+        Orc->>+Gate: Trigger Self-Audit (trusted origin/main rules)
+        
+        Gate->>+Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
+        Git-->>-Gate: Diff Stats & File List
+        
+        alt Scope Breach (Forbidden Path OR Diff Payload > 75 KB)
+            Gate-->>Orc: Security / Scope Violation Detected
+            Orc->>Orc: Record Telemetry (metrics.jsonl)
+            Orc-->>Trigger: Abort Execution (Exit 3)
+            break Fatal Security Error
+                Orc->>Git: Teardown Worktree Sandbox
+            end
+        else Scope Verification Passed
+            Gate->>+Git: Run Dynamic Verification (`testCmd` & `buildCmd`)
+            Git-->>-Gate: stdout / stderr verification results
+        end
+
+        alt 100% Verification Suite Passed
+            Gate-->>-Orc: Verification Success
+            Orc->>+Git: Commit & Push to Remote Branch / PR
+            Git-->>-Orc: PR Ready
+            Orc->>Orc: Record Telemetry (metrics.jsonl)
+            Orc-->>Trigger: Dispatch Succeeded (Exit 0)
+            break Task Completed
+                Orc->>Git: Teardown Worktree Sandbox
+            end
+        else Verification Failed
+            Gate-->>Orc: Verification Failed (Stderr Trace output)
+            Orc->>Orc: Record Failure Telemetry
+            
+            alt Retries Remaining (< 3)
+                Orc->>Orc: Construct Repair Prompt with Stderr Trace
+            else Max Retries Exceeded (3/3)
+                Orc-->>-Trigger: Abort & Log Diagnostic Feedback (Exit 4)
+                Orc->>Git: Teardown Worktree Sandbox
+            end
+        end
+    end
+```
+
 > 💡 **Core Architectural Invariants**:
 > - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
+> - **Automatic PII & Secret Redaction**: Outbound task prompts are automatically sanitized to redact API secrets and mask sensitive PII (emails, IPs, phone numbers).
+> - **Ledger Hash-Chain Integrity**: Hashing over JSONL event streams detects unauthorized log tampering or record deletions.
 > - **Dynamic Command Resolution (`command-resolver.mjs`)**: Auto-detects workspace boundaries (Turborepo, pnpm, Nx, Cargo, pytest, npm).
 >
 > 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
@@ -96,13 +171,16 @@ If no API key is configured, the kit seamlessly falls back to invoking your loca
 **3. Programmatic Node.js SDK (`index.mjs`)**
 Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
 ```js
-import { runSelfAudit, scanCodebaseForTodos, resolveProjectCommands } from "jules-orchestrator-kit";
+import { runSelfAudit, dispatchTask, anonymizePii, verifyLedgerIntegrity, validateJulesConfig } from "jules-orchestrator-kit";
+
+// Anonymize sensitive PII (emails, IPs, phone numbers) before sending prompts
+const cleanPrompt = anonymizePii("Contact support at john@example.com");
 
-// Run pre-flight sandbox check
-await runPreflightSandbox();
+// Programmatically dispatch tasks
+await dispatchTask({ title: "Refactor Auth", prompt: cleanPrompt });
 
-// Scan codebase for TODO/FIXME tasks
-const tasks = scanCodebaseForTodos(process.cwd());
+// Verify cryptographic hash chain of event ledgers
+const integrity = verifyLedgerIntegrity(".agent/state/sessions/2026-08-03.jsonl");
 ```
 
 ---
@@ -154,6 +232,7 @@ All commands are registered in `package.json` and can be run via `npm run <comma
 | `npm run jules:cleanup` | Audits and closes merged or stale REST sessions |
 | `npm run jules:scan` | Scans the codebase for TODO/FIXME comments and generates a suggested tasks file |
 | `npm run jules:swarm` | Launches a multi-agent swarm in parallel across isolated worktrees |
+| `npm run jules:merge-swarm` | Autonomous PR merge engine: squash-merges passing, disjoint Jules PRs |
 | `npm run jules:nightly` | Nightly maintenance job (usually triggered in CI) |
 
 ### Environment Variables
@@ -167,7 +246,9 @@ 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_MAX_DIFF_KB` | Maximum git diff payload size in KB before aborting with Exit Code 5 (Default: `50`) |
+| `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) |
@@ -192,19 +273,19 @@ The Gatekeeper (`jules-self-audit.mjs` and related scripts) uses standard exit c
 | Code | Meaning | Action Taken |
 | ---- | ------- | ------------ |
 | `0`  | **Success** | All tests and security checks passed. |
-| `1`  | **General Error** | Missing dependencies, syntax error, or general failure. |
-| `2`  | **Setup / Context Error** | Git not found, invalid `BASE_BRANCH`, or trusted base branch extraction failure. |
-| `3`  | **Security Violation** | Modified file breached `forbidden_paths` or changed command-defining files (`package.json`, `Cargo.toml`). Fails closed immediately. |
-| `4`  | **Verification Exhausted** | Tests failed and the OODA Auto-Repair loop either exhausted its max retries or is disabled. |
-| `5`  | **Diff Payload Too Large** | Diff payload size exceeded 75 KB payload governor limit. Split task. |
-| `6`  | **Secret Leak Prevented** | Secret-like pattern detected in diff. Aborted immediately. |
+| `1`  | **Pre-Dispatch / Arg Error** | Missing dependencies, prompt > 50 KB, syntax error, or pre-dispatch failure. |
+| `2`  | **API / Network / Quota Error** | REST API HTTP 429 rate limit, HTTP 400 `FAILED_PRECONDITION` quota (~30 active limit), or connection timeout. |
+| `3`  | **Security / Scope Violation** | Modified file breached `forbidden_paths` or changed command-defining files (`package.json`, `Cargo.toml`). Fails closed immediately. |
+| `4`  | **Verification Exhausted** | Tests failed and the OODA Auto-Repair loop either exhausted its max retries (3) or is disabled. |
+| `5`  | **Diff Payload Limit** | Diff payload size exceeded payload governor budget (`JULES_MAX_DIFF_KB`, default 50 KB). Split task. |
+| `6`  | **Secret Leak Prevented** | High-confidence secret or private key pattern detected in diff. Aborted immediately. |
 | `7`  | **Budget Exhausted** | Daily session budget limit reached or budget state locked. |
 
 ---
 
 ## Contributing
 We welcome contributions! Please follow these core principles:
-1. **Zero External Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
+1. **Zero Runtime Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
 2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`).
 3. **Conventional Commits**: Use standardized prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
 4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.

package/bin/init.js

@@ -157,7 +157,7 @@ if (!fs.existsSync(yamlConfigPath) || isForce) {
 version: 2
 test_cmd: "${detected.testCmd || "npm test"}"
 build_cmd: "${detected.buildCmd || "npm run build"}"
-forbidden_paths: [".github/**", "**/secrets/**", "**/*.pem", "**/lock-manager/**"]
+forbidden_paths: [".github/**", "**/.env*", "**/*.pem", "**/lock-manager*"]
 `;
   fs.writeFileSync(yamlConfigPath, yamlContent, "utf-8");
   console.log("✅ Created: .agent/jules.yml");
@@ -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/index.mjs

@@ -1,11 +1,12 @@
 /**
  * jules-orchestrator-kit Node.js SDK
  * Primary entrypoint for programmatically orchestrating Google Jules workflows.
- * Zero external dependencies.
+ * Zero runtime dependencies.
  */
 
 export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";
-export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob } from "./scripts/jules-self-audit.mjs";
+export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob, validateJulesConfig } from "./scripts/jules-self-audit.mjs";
 export { scanCodebaseForTodos, runScanner } from "./scripts/jules-scan-todos.mjs";
-export { log, logToHistory, ensureDir, resolveMarkdownConflict, redactSecrets } from "./scripts/utils.mjs";
-export { getDynamicGuardrails } from "./scripts/jules-dispatch.mjs";
+export { log, logToHistory, ensureDir, resolveMarkdownConflict, redactSecrets, anonymizePii, verifyLedgerIntegrity, loadEnv } from "./scripts/utils.mjs";
+export { getDynamicGuardrails, dispatchTask } from "./scripts/jules-dispatch.mjs";
+export { classifyQueueFailure } from "./scripts/jules-queue-runner.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.8.0",
+  "version": "0.8.5",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     ".agent/rules/",
     ".agent/workflows/",
     ".agent/jules-queue/README.md",
-    ".github/",
+    ".github/workflows/jules-audit.yml",
     ".env.example",
     "JULES_RULES_TEMPLATE.md",
     "README.md",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "init": "node bin/init.js",
-    "test": "node --test test/kit.test.mjs",
+    "test": "node --test test/*.test.mjs",
     "jules:dispatch": "node scripts/jules-dispatch.mjs",
     "jules:queue": "node scripts/jules-queue-runner.mjs",
     "jules:create": "node scripts/jules-create.mjs",
@@ -44,7 +44,10 @@
     "jules:cleanup": "node scripts/jules-cleanup.mjs",
     "jules:scan": "node scripts/jules-scan-todos.mjs",
     "jules:swarm": "node scripts/jules-swarm.mjs",
-    "jules:nightly": "node scripts/jules-nightly.mjs"
+    "jules:merge-swarm": "node scripts/jules-merge-swarm.mjs",
+    "jules:patch": "node scripts/jules-patch.mjs",
+    "jules:nightly": "node scripts/jules-nightly.mjs",
+    "lint": "eslint ."
   },
   "engines": {
     "node": ">=18.0.0"
@@ -58,5 +61,9 @@
     "automation"
   ],
   "author": "FullThrottle83",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^9.39.5",
+    "globals": "^17.8.0"
+  }
 }

package/scripts/command-resolver.mjs

@@ -1,6 +1,23 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export function detectPackageManager(root = process.cwd(), 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";
+}
+
 /**
  * Dynamic Framework-Agnostic Command Resolver
  * Sniffs project manifests to return proper build & test verification commands.
@@ -44,23 +61,6 @@ 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 = [
     {

package/scripts/jules-cleanup.mjs

@@ -3,36 +3,19 @@
  * Jules Session Cleanup & PR Audit Utility
  * Cross-references active/completed Jules REST API sessions with GitHub PR merge status
  * to report and safely close merged or stale sessions.
- * Zero external dependencies.
+ * Zero runtime dependencies.
  */
 
 import { execFileSync } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
-import { log } from "./utils.mjs";
-
-function loadEnv() {
-  const envPath = path.resolve(process.cwd(), ".env");
-  if (fs.existsSync(envPath)) {
-    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const eqIdx = trimmed.indexOf("=");
-      if (eqIdx > 0) {
-        const key = trimmed.slice(0, eqIdx).trim().replace(/^export\s+/, "");
-        let val = trimmed.slice(eqIdx + 1).trim();
-        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-          val = val.slice(1, -1);
-        }
-        if (!process.env[key]) {
-          process.env[key] = val;
-        }
-      }
-    }
-  }
+import { fileURLToPath } from "node:url";
+import { log, loadEnv } from "./utils.mjs";
+
+const isMainModule = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (isMainModule) {
+  loadEnv();
 }
-loadEnv();
 
 const args = process.argv.slice(2);
 const isDryRun = args.includes("--dry-run") || process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1";
@@ -198,3 +181,10 @@ export async function runCleanup() {
     }
   }
 }
+
+if (isMainModule) {
+  runCleanup().catch((err) => {
+    log.error(`Cleanup audit failed: ${err.message}`);
+    process.exit(1);
+  });
+}

package/scripts/jules-create.mjs

@@ -6,14 +6,18 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { log, ensureDir } from "./utils.mjs";
 
-const taskTitle = process.argv[2];
+const isMainModule = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
 
-if (!taskTitle) {
-  log.error("Usage: npm run jules:create \"Task Title\"");
-  process.exit(1);
-}
+if (isMainModule) {
+  const taskTitle = process.argv[2];
+
+  if (!taskTitle) {
+    log.error("Usage: npm run jules:create \"Task Title\"");
+    process.exit(1);
+  }
 
 const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
 ensureDir(queueDir);
@@ -65,3 +69,4 @@ try {
   log.error(`Failed to create task file: ${err.message}`);
   process.exit(1);
 }
+}