jules-orchestrator-kit 0.1.2 → 0.2.8

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.1.2",
-  "description": "Framework-agnostic toolkit for orchestrating Google Jules background AI coding workers.",
+  "version": "0.2.8",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FullThrottle83/jules-orchestrator-kit/issues"
+  },
+  "homepage": "https://github.com/FullThrottle83/jules-orchestrator-kit#readme",
   "type": "module",
   "bin": {
     "jules-init": "bin/init.js",
@@ -11,6 +18,8 @@
     "bin/",
     "scripts/",
     ".agent/",
+    ".github/",
+    ".env.example",
     "JULES_RULES_TEMPLATE.md",
     "README.md",
     "LICENSE"

package/scripts/command-resolver.mjs

@@ -39,137 +39,90 @@ export function resolveProjectCommands(projectRoot = process.cwd()) {
         buildCmd: cfg.buildCmd || "",
         source: "jules.config.json",
       };
-    } catch (_) {}
-  }
-
-  // 2. Bun (bunfig.toml or bun.lockb)
-  if (
-    fs.existsSync(path.join(projectRoot, "bunfig.toml")) ||
-    fs.existsSync(path.join(projectRoot, "bun.lockb"))
-  ) {
-    return {
-      testCmd: "bun test",
-      buildCmd: "bun run build",
-      source: "Bun Manifest",
-    };
-  }
-
-  // 3. Deno (deno.json / deno.jsonc)
-  if (
-    fs.existsSync(path.join(projectRoot, "deno.json")) ||
-    fs.existsSync(path.join(projectRoot, "deno.jsonc"))
-  ) {
-    return {
-      testCmd: "deno test",
-      buildCmd: "deno task build",
-      source: "Deno Manifest",
-    };
-  }
-
-  // 4. JavaScript / TypeScript (package.json)
-  const pkgPath = path.join(projectRoot, "package.json");
-  if (fs.existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-      const scripts = pkg.scripts || {};
-      const verifyScript = scripts["check:all"]
-        ? "npm run check:all"
-        : scripts.test
-        ? "npm test"
-        : "";
-      const buildScript = scripts.build ? "npm run build" : "";
-      return {
-        testCmd: verifyScript,
-        buildCmd: buildScript,
-        source: "package.json",
-      };
-    } catch (_) {}
-  }
-
-  // 5. Rust (Cargo.toml)
-  if (fs.existsSync(path.join(projectRoot, "Cargo.toml"))) {
-    return {
-      testCmd: "cargo test --workspace",
-      buildCmd: "cargo build",
-      source: "Cargo.toml",
-    };
-  }
-
-  // 6. Go (go.mod)
-  if (fs.existsSync(path.join(projectRoot, "go.mod"))) {
-    return {
-      testCmd: "go test ./...",
-      buildCmd: "go build ./...",
-      source: "go.mod",
-    };
-  }
-
-  // 7. Python (pyproject.toml / requirements.txt / setup.py)
-  if (
-    fs.existsSync(path.join(projectRoot, "pyproject.toml")) ||
-    fs.existsSync(path.join(projectRoot, "requirements.txt")) ||
-    fs.existsSync(path.join(projectRoot, "setup.py"))
-  ) {
-    return {
-      testCmd: "pytest",
-      buildCmd: "",
-      source: "Python Manifest",
-    };
-  }
-
-  // 8. Elixir (mix.exs)
-  if (fs.existsSync(path.join(projectRoot, "mix.exs"))) {
-    return {
-      testCmd: "mix test",
-      buildCmd: "mix compile",
-      source: "mix.exs",
-    };
-  }
-
-  // 9. Ruby (Gemfile)
-  if (fs.existsSync(path.join(projectRoot, "Gemfile"))) {
-    return {
-      testCmd: "bundle exec rake test",
-      buildCmd: "",
-      source: "Gemfile",
-    };
-  }
-
-  // 10. Swift (Package.swift)
-  if (fs.existsSync(path.join(projectRoot, "Package.swift"))) {
-    return {
-      testCmd: "swift test",
-      buildCmd: "swift build",
-      source: "Package.swift",
-    };
-  }
-
-  // 11. Java (Maven pom.xml / Gradle build.gradle)
-  if (fs.existsSync(path.join(projectRoot, "pom.xml"))) {
-    return {
-      testCmd: "mvn test",
-      buildCmd: "mvn compile",
-      source: "pom.xml",
-    };
-  }
-  if (
-    fs.existsSync(path.join(projectRoot, "build.gradle")) ||
-    fs.existsSync(path.join(projectRoot, "build.gradle.kts"))
-  ) {
-    return {
-      testCmd: "./gradlew test",
-      buildCmd: "./gradlew assemble",
-      source: "build.gradle",
-    };
+    } catch (err) {
+      console.warn("⚠️ Failed to parse jules.config.json:", err.message);
+    }
   }
 
-  // 12. Makefile
-  if (fs.existsSync(path.join(projectRoot, "Makefile"))) {
-    return {
-      testCmd: "make test",
-      buildCmd: "make build",
-      source: "Makefile",
-    };
+  // 2. Dynamic Detector Strategy List
+  const detectors = [
+    {
+      files: ["bunfig.toml", "bun.lockb"],
+      resolve: () => ({ testCmd: "bun test", buildCmd: "bun run build", source: "Bun Manifest" }),
+    },
+    {
+      files: ["deno.json", "deno.jsonc"],
+      resolve: () => ({ testCmd: "deno test", buildCmd: "deno task build", source: "Deno Manifest" }),
+    },
+    {
+      files: ["package.json"],
+      resolve: (root) => {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
+          const scripts = pkg.scripts || {};
+          let verifyScript = scripts["check:all"] ? "npm 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");
+            verifyScript = parts.join(" && ");
+          }
+          const buildScript = scripts.build ? "npm run build" : "";
+          return {
+            testCmd: verifyScript || "npm test",
+            buildCmd: buildScript,
+            source: "package.json",
+          };
+        } catch (err) {
+          console.warn("⚠️ Failed to parse package.json:", err.message);
+          return null;
+        }
+      },
+    },
+    {
+      files: ["Cargo.toml"],
+      resolve: () => ({ testCmd: "cargo test --workspace", buildCmd: "cargo build", source: "Cargo.toml" }),
+    },
+    {
+      files: ["go.mod"],
+      resolve: () => ({ testCmd: "go test ./...", buildCmd: "go build ./...", source: "go.mod" }),
+    },
+    {
+      files: ["pyproject.toml", "requirements.txt", "setup.py"],
+      resolve: () => ({ testCmd: "pytest", buildCmd: "", source: "Python Manifest" }),
+    },
+    {
+      files: ["mix.exs"],
+      resolve: () => ({ testCmd: "mix test", buildCmd: "mix compile", source: "mix.exs" }),
+    },
+    {
+      files: ["Gemfile"],
+      resolve: () => ({ testCmd: "bundle exec rake test", buildCmd: "", source: "Gemfile" }),
+    },
+    {
+      files: ["Package.swift"],
+      resolve: () => ({ testCmd: "swift test", buildCmd: "swift build", source: "Package.swift" }),
+    },
+    {
+      files: ["pom.xml"],
+      resolve: () => ({ testCmd: "mvn test", buildCmd: "mvn compile", source: "pom.xml" }),
+    },
+    {
+      files: ["build.gradle", "build.gradle.kts"],
+      resolve: () => ({ testCmd: "./gradlew test", buildCmd: "./gradlew assemble", source: "build.gradle" }),
+    },
+    {
+      files: ["Makefile"],
+      resolve: () => ({ testCmd: "make test", buildCmd: "make build", source: "Makefile" }),
+    },
+  ];
+
+  for (const detector of detectors) {
+    if (detector.files.some((f) => fs.existsSync(path.join(projectRoot, f)))) {
+      const res = detector.resolve(projectRoot);
+      if (res) return res;
+    }
   }
 
   return {
@@ -185,6 +138,9 @@ export function resolveProjectCommands(projectRoot = process.cwd()) {
  */
 export function resolveWorkspaceExecutionBoundary(modifiedFiles = [], projectRoot = process.cwd()) {
   const baseCmds = resolveProjectCommands(projectRoot);
+  if (baseCmds.source === ".agent/jules.yml" || baseCmds.source === "jules.config.json") {
+    return baseCmds;
+  }
   if (!modifiedFiles || modifiedFiles.length === 0) return baseCmds;
 
   // Find affected package names by walking up from modified files to nearest manifest
@@ -211,8 +167,9 @@ export function resolveWorkspaceExecutionBoundary(modifiedFiles = [], projectRoo
     }
   }
 
-  if (affectedPkgs.size === 0) return baseCmds;
-  const targets = Array.from(affectedPkgs);
+  const SAFE_PKG_NAME = /^[@a-zA-Z0-9._\/-]+$/;
+  const targets = Array.from(affectedPkgs).filter((t) => SAFE_PKG_NAME.test(t));
+  if (targets.length === 0) return baseCmds;
 
   // 1. Turborepo (turbo.json)
   if (fs.existsSync(path.join(projectRoot, "turbo.json"))) {

package/scripts/jules-dispatch.mjs

@@ -3,12 +3,15 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { resolveProjectCommands } from "./command-resolver.mjs";
 
-const taskTitle = process.argv[2];
-const taskPromptArg = process.argv[3];
+const isMainModule = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
 
-if (!taskTitle || !taskPromptArg) {
+const taskTitle = isMainModule ? process.argv[2] : "";
+const taskPromptArg = isMainModule ? process.argv[3] : "";
+
+if (isMainModule && (!taskTitle || !taskPromptArg)) {
   console.error(
     'Usage: node scripts/jules-dispatch.mjs <task-title> <path-to-prompt.md | "raw prompt string">'
   );
@@ -39,9 +42,41 @@ function loadEnv() {
 }
 loadEnv();
 
-// 0.1 Pre-Flight Secret Redaction Gate
-function redactSecrets(text) {
+// 0.1 Shannon Entropy Calculator
+export function calculateEntropy(str) {
+  if (!str) return 0;
+  const len = str.length;
+  const frequencies = {};
+  for (let i = 0; i < len; i++) {
+    const char = str[i];
+    frequencies[char] = (frequencies[char] || 0) + 1;
+  }
+  let entropy = 0;
+  for (const char in frequencies) {
+    const p = frequencies[char] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// 0.2 Pre-Flight Secret Redaction Gate (RegEx + Shannon Entropy + Env Denylist)
+export function redactSecrets(text) {
   if (!text) return "";
+  let sanitized = text;
+
+  // Redact active env secrets from denylist keys (*_KEY, *_SECRET, *_TOKEN, etc.)
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (
+      envVal &&
+      envVal.length >= 6 &&
+      /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH/i.test(envKey)
+    ) {
+      if (sanitized.includes(envVal)) {
+        sanitized = sanitized.split(envVal).join("[REDACTED_ENV_SECRET]");
+      }
+    }
+  }
+
   const patterns = [
     /gh[pusr]_[a-zA-Z0-9]{36}/g,
     /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/g,
@@ -52,99 +87,123 @@ function redactSecrets(text) {
     /sk-(?:ant-api03-|proj-|svcacct-)[a-zA-Z0-9\-\_]{32,}/g,
     /xox[baprs]-[a-zA-Z0-9\-]{10,}/g,
     /eyJ[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}/g,
-    /-----BEGIN (?:RSA|OPENSSH|EC|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|OPENSSH|EC|PRIVATE) KEY-----/,
+    /-----BEGIN (?:RSA|OPENSSH|EC|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|OPENSSH|EC|PRIVATE) KEY-----/g,
   ];
-  let sanitized = text;
   for (const pat of patterns) {
     sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
   }
+  // Exclude file paths (tokens with slashes or common extensions) from entropy redaction
+  sanitized = sanitized.replace(/[a-zA-Z0-9_\-\.]{20,}/g, (token) => {
+    if (
+      token.startsWith("[REDACTED_") ||
+      token.includes("/") ||
+      /\.(?:ts|js|jsx|tsx|json|md|py|rs|go|yml|yaml|toml|html|css|sh|config)$/i.test(token)
+    ) {
+      return token;
+    }
+    const entropy = calculateEntropy(token);
+    if (entropy > 3.6) {
+      return "[REDACTED_ENTROPY_KEY]";
+    }
+    return token;
+  });
   return sanitized;
 }
 
-// 1. Resolve prompt content (file path or inline string)
-let rawPrompt = "";
-const possiblePath = path.resolve(process.cwd(), taskPromptArg);
-if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
-  rawPrompt = fs.readFileSync(possiblePath, "utf-8");
-} else {
-  rawPrompt = taskPromptArg;
+// 0.3 Hardened Path Traversal & Symlink Defense
+export function assertPathWithinWorkspace(targetPath, workspaceRoot = process.cwd()) {
+  const rootReal = fs.existsSync(workspaceRoot) ? fs.realpathSync(path.resolve(workspaceRoot)) : path.resolve(workspaceRoot);
+  const resolvedTarget = path.resolve(rootReal, targetPath);
+  const targetReal = fs.existsSync(resolvedTarget) ? fs.realpathSync(resolvedTarget) : resolvedTarget;
+  const normalizedRoot = rootReal.replace(/\\/g, "/");
+  const normalizedTarget = targetReal.replace(/\\/g, "/");
+  if (!normalizedTarget.startsWith(normalizedRoot)) {
+    throw new Error(`FATAL: Sandboxed directory traversal breach blocked for path: ${targetPath}`);
+  }
+  return targetReal;
 }
-rawPrompt = redactSecrets(rawPrompt);
-
-// 2. Dynamic Guardrail Composition (DGC) from .agent/rules/dynamic-guardrails.json
-function getDynamicGuardrails(promptText) {
-  const guardrailsPath = path.resolve(process.cwd(), ".agent/rules/dynamic-guardrails.json");
-  if (!fs.existsSync(guardrailsPath)) return "";
 
-  try {
-    const data = JSON.parse(fs.readFileSync(guardrailsPath, "utf-8"));
-    if (!data.rules || !Array.isArray(data.rules)) return "";
-
-    const active = [];
-    for (const item of data.rules) {
-      if (new RegExp(item.trigger, "i").test(promptText)) {
-        active.push(item.guardrail);
-      }
-    }
-    return active.join("\n\n");
-  } catch (e) {
-    return "";
+// 0.4 Dynamic Guardrails & Directive Definitions
+export function getDynamicGuardrails(prompt = "") {
+  const guardrails = [];
+  if (/\b(?:astro|components|pages|src\/.*\.astro)\b/i.test(prompt)) {
+    guardrails.push("- Astro Guidance: Ensure zero client JS shipped by default. Use server islands or nano stores if state is required.");
+  }
+  if (/\b(?:db|database|d1|postgres|drizzle|migration|schema)\b/i.test(prompt)) {
+    guardrails.push("- Database Guidance: Do not modify migrations directly without inspecting current schema constraints.");
   }
+  return guardrails.length > 0 ? `## Context-Specific Guardrails\n${guardrails.join("\n")}` : "";
 }
 
-// 3. Dynamic Command Resolution (Language & Framework Detection)
-const resolvedCmds = resolveProjectCommands(process.cwd());
-const verifyDirective = resolvedCmds.testCmd || resolvedCmds.buildCmd
-  ? `\n\n## 🛠️ MANDATORY VERIFICATION COMMANDS\nBefore submitting PR, you MUST execute: \`${[resolvedCmds.testCmd, resolvedCmds.buildCmd].filter(Boolean).join(" && ")}\``
-  : "";
-
-// 4. Load Base Rules / Guardrails
-const rulesPath = fs.existsSync(path.resolve(process.cwd(), "AGENTS.md"))
-  ? path.resolve(process.cwd(), "AGENTS.md")
-  : path.resolve(process.cwd(), "JULES_RULES_TEMPLATE.md");
-
-const baseRules = fs.existsSync(rulesPath)
-  ? fs.readFileSync(rulesPath, "utf-8")
-  : "";
-
-const dynamicRules = getDynamicGuardrails(rawPrompt);
-
-// Machine XML Directives
-const envelope = `
-<MCP_DIRECTIVE>
-  <system_state>HEADLESS_CI_MODE</system_state>
-  <strict_invariants>
-    <rule>1. READ-BEFORE-WRITE (ZERO HALLUCINATION): You are FORBIDDEN from guessing internal API signatures. Before editing, use search tools or MCP doc tools to verify exact signatures.</rule>
-    <rule>2. VERIFICATION LOOP: After patching code, you MUST execute the verification commands and ensure 0 errors.</rule>
-    <rule>3. ABORT CONDITION: On repeated unresolvable test failures, output <status>ABORT_UNRESOLVABLE</status> and terminate.</rule>
-  </strict_invariants>
-</MCP_DIRECTIVE>
-`.trim();
-
-const fullPrompt = redactSecrets(`MCP DIRECTIVE: ${rawPrompt.trim()}${verifyDirective}\n\n---\n\n${envelope}\n\n---\n\n${dynamicRules ? `${dynamicRules}\n\n---\n\n` : ""}${baseRules.trim()}`);
-
-// 5. Log Dispatch History
-const dateStr = new Date().toISOString().split("T")[0];
-const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
-
-const historyDir = path.resolve(process.cwd(), ".agent/history");
-if (!fs.existsSync(historyDir)) {
-  fs.mkdirSync(historyDir, { recursive: true });
+function getBaseRules(projectRoot = process.cwd()) {
+  const templatePath = path.join(projectRoot, "JULES_RULES_TEMPLATE.md");
+  if (fs.existsSync(templatePath)) {
+    return fs.readFileSync(templatePath, "utf-8");
+  }
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  if (fs.existsSync(agentsPath)) {
+    return fs.readFileSync(agentsPath, "utf-8");
+  }
+  return `## Operational Directives
+- **Read Before Write**: Always inspect target files and symbol definitions before modifying code.
+- **Verification**: Execute test and build verification suite and ensure 0 errors.
+- **Anti-Patch Invariant**: Do NOT create out-of-band shell scripts (patch.sh, test-fix.sh) or disable assertions to force tests to pass.`;
 }
-const historyFile = path.join(historyDir, `${dateStr}-dispatch-${slug}.md`);
-fs.writeFileSync(historyFile, `---\ntype: jules_dispatch\ntitle: "${taskTitle}"\ntimestamp: "${new Date().toISOString()}"\n---\n# Jules Task Dispatch: ${taskTitle}\n\n## Prompt\n${rawPrompt}\n`, "utf-8");
 
-console.log(`🚀 Dispatching task to Google Jules: "${taskTitle}"...`);
-console.log(`📝 Logged dispatch history to: ${path.relative(process.cwd(), historyFile)}`);
+// 1. Resolve prompt content and construct directive envelope
+let rawPrompt = "";
+let fullPrompt = "";
+let historyFile = "";
+let tmpPayloadFile = "";
+let tmpDir = "";
+
+const apiKey = process.env.JULES_API_KEY || process.env.GEMINI_API_KEY || "";
+const repo = process.env.JULES_REPO || "";
+
+if (isMainModule) {
+  const possiblePath = path.resolve(process.cwd(), taskPromptArg);
+  if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
+    assertPathWithinWorkspace(possiblePath);
+    rawPrompt = fs.readFileSync(possiblePath, "utf-8");
+  } else {
+    rawPrompt = taskPromptArg;
+  }
+  rawPrompt = redactSecrets(rawPrompt);
+
+  const dynamicRules = getDynamicGuardrails(rawPrompt);
+  const baseRules = getBaseRules(process.cwd());
+  const envelope = `## Envelope Directives
+- **Zero Hallucination:** Inspect exact symbol definitions before editing.
+- **Verification:** Execute project verification suite and ensure 0 errors.
+- **Anti-Patch / Zero Out-of-band Scripts:** Do NOT create workaround runner scripts (e.g. patch.sh, test-fix.sh) or disable assertions to pass tests.`;
+
+  const { testCmd, buildCmd } = resolveProjectCommands(process.cwd());
+  const verifyDirective = testCmd || buildCmd 
+    ? `\n\nVERIFICATION DIRECTIVE: Execute \`${[testCmd, buildCmd].filter(Boolean).join(" && ")}\` after patching.`
+    : "";
+
+  fullPrompt = redactSecrets(`MCP DIRECTIVE: ${rawPrompt.trim()}${verifyDirective}\n\n---\n\n${envelope}\n\n---\n\n${dynamicRules ? `${dynamicRules}\n\n---\n\n` : ""}${baseRules.trim()}`);
+
+  const dateStr = new Date().toISOString().split("T")[0];
+  const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+
+  // Resolve history directory relative to main workspace root, avoiding temporary worktrees
+  const mainWorkspaceRoot = process.env.JULES_PROJECT_ROOT || process.env.INIT_CWD || process.cwd();
+  const historyDir = path.resolve(mainWorkspaceRoot, ".agent/history");
+  if (!fs.existsSync(historyDir)) {
+    fs.mkdirSync(historyDir, { recursive: true });
+  }
+  historyFile = path.join(historyDir, `${dateStr}-dispatch-${slug}.md`);
+  fs.writeFileSync(historyFile, `---\ntype: jules_dispatch\ntitle: "${taskTitle}"\ntimestamp: "${new Date().toISOString()}"\n---\n# Jules Task Dispatch: ${taskTitle}\n\n## Prompt\n${rawPrompt}\n`, "utf-8");
 
-// 6. Dispatch via REST API or Ephemeral Payload File (Avoid ARG_MAX shell limits)
-const apiKey = process.env.JULES_API_KEY;
-const repo = process.env.JULES_REPO;
+  console.log(`🚀 Dispatching task to Google Jules: "${taskTitle}"...`);
+  console.log(`📝 Logged dispatch history to: ${path.relative(process.cwd(), historyFile)}`);
 
-const payloadHash = crypto.createHash("sha256").update(taskTitle + Date.now()).digest("hex").slice(0, 12);
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jules-payload-"));
-const tmpPayloadFile = path.join(tmpDir, `payload_${payloadHash}.json`);
-fs.writeFileSync(tmpPayloadFile, JSON.stringify({ repo, title: taskTitle, prompt: fullPrompt }), { mode: 0o600 });
+  const payloadHash = crypto.createHash("sha256").update(taskTitle + Date.now()).digest("hex").slice(0, 12);
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jules-payload-"));
+  tmpPayloadFile = path.join(tmpDir, `payload_${payloadHash}.json`);
+  fs.writeFileSync(tmpPayloadFile, JSON.stringify({ repo, title: taskTitle, prompt: fullPrompt }), { mode: 0o600 });
+}
 
 function cleanupTmp() {
   try {
@@ -156,6 +215,13 @@ function cleanupTmp() {
 
 async function executeDispatch() {
   try {
+    if (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1") {
+      console.log(`[DRY RUN] Dispatch payload prepared successfully for task: "${taskTitle}".`);
+      console.log(`[DRY RUN] Target Repository: ${repo || "(default)"}`);
+      console.log(`[DRY RUN] Prompt Length: ${fullPrompt.length} chars.`);
+      return;
+    }
+
     if (apiKey && repo) {
       console.log(`🌐 Using Jules REST API for repository ${repo}...`);
       const formattedSource = repo.startsWith("sources/") ? repo : (repo.includes("/") ? `sources/github/${repo}` : repo);
@@ -172,7 +238,8 @@ async function executeDispatch() {
 
       let res;
       try {
-        res = await fetch("https://jules.googleapis.com/v1alpha/sessions", {
+        const apiUrl = process.env.JULES_API_URL || "https://jules.googleapis.com/v1alpha/sessions";
+        res = await fetch(apiUrl, {
           method: "POST",
           headers: {
             "X-Goog-Api-Key": apiKey,
@@ -202,7 +269,9 @@ async function executeDispatch() {
       try {
         const data = await res.json();
         sessionId = data.name || data.id || sessionId;
-      } catch (_) {}
+      } catch (jsonErr) {
+        console.warn("⚠️ Failed to parse REST API JSON response:", jsonErr.message);
+      }
 
       console.log(`✅ REST API Dispatch response: Session ${sessionId} created successfully.`);
       fs.appendFileSync(historyFile, `\n## Session\n- ID: \`${sessionId}\`\n`);
@@ -214,7 +283,6 @@ async function executeDispatch() {
   }
 }
 
-
 function dispatchViaCli(targetRepo, payloadFile, title) {
   try {
     let promptToSend = fullPrompt;
@@ -222,7 +290,9 @@ function dispatchViaCli(targetRepo, payloadFile, title) {
       try {
         const payloadData = JSON.parse(fs.readFileSync(payloadFile, "utf-8"));
         if (payloadData.prompt) promptToSend = payloadData.prompt;
-      } catch (_) {}
+      } catch (jsonErr) {
+        console.warn("⚠️ Failed to parse payload JSON file:", jsonErr.message);
+      }
     }
 
     const args = ["new"];
@@ -239,10 +309,9 @@ function dispatchViaCli(targetRepo, payloadFile, title) {
   }
 }
 
-
-executeDispatch().catch((err) => {
-  console.error("❌ Fatal unhandled rejection in dispatch:", err);
-  process.exit(1);
-});
-
-
+if (isMainModule) {
+  executeDispatch().catch((err) => {
+    console.error("❌ Fatal unhandled rejection in dispatch:", err);
+    process.exit(1);
+  });
+}

package/scripts/jules-queue-runner.mjs

@@ -1,9 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const dispatchScript = path.resolve(__dirname, "jules-dispatch.mjs");
+
 const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
 const completedDir = path.resolve(process.cwd(), ".agent/jules-queue/completed");
+const queueLogFile = path.join(queueDir, "queue.jsonl");
 
 if (!fs.existsSync(queueDir)) {
   console.error(`❌ Queue directory not found: ${queueDir}`);
@@ -14,11 +20,20 @@ if (!fs.existsSync(completedDir)) {
   fs.mkdirSync(completedDir, { recursive: true });
 }
 
+function logQueueState(file, status, error = null) {
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    file,
+    status,
+    error: error ? error.message || String(error) : null,
+  }) + "\n";
+  fs.appendFileSync(queueLogFile, entry, "utf-8");
+}
+
 const files = fs.readdirSync(queueDir).filter(
   (f) => f.endsWith(".md") && f !== "README.md" && !f.startsWith("_") && !f.startsWith(".")
 );
 
-
 if (files.length === 0) {
   console.log("ℹ️ No tasks found in the queue.");
   process.exit(0);
@@ -33,17 +48,20 @@ files.forEach((file, index) => {
   
   console.log(`\n----------------------------------------`);
   console.log(`[${index + 1}/${files.length}] Dispatching queued task: ${title}`);
+  logQueueState(file, "RUNNING");
   
   try {
-    execFileSync("node", ["scripts/jules-dispatch.mjs", title, filePath], {
+    execFileSync("node", [dispatchScript, title, filePath], {
       stdio: "inherit",
     });
     
     // Move to completed
     const destPath = path.join(completedDir, file);
     fs.renameSync(filePath, destPath);
+    logQueueState(file, "COMPLETED");
     console.log(`✅ Moved ${file} to completed/`);
   } catch (error) {
+    logQueueState(file, "FAILED", error);
     console.error(`⚠️ Failed to dispatch task [${title}]:`, error.message);
   }
 });