jules-orchestrator-kit 0.29.1 → 0.31.0

package/package.json

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

package/src/config.mjs

@@ -196,9 +196,19 @@ export function detectStack(projectRoot = process.cwd()) {
   return detectPolyglotStack(projectRoot);
 }
 
-export function resolveVerify(root = process.cwd()) {
+export function resolveVerify(root = process.cwd(), userVerify = {}) {
   const s = detectStack(root);
-  return { test: s.testCmd || "", build: s.buildCmd || "" };
+  return {
+    setup: userVerify.setup ?? s.setupCmd ?? "",
+    test: userVerify.test ?? s.testCmd ?? "",
+    teardown: userVerify.teardown ?? s.teardownCmd ?? "",
+    build: userVerify.build ?? s.buildCmd ?? "",
+    server: userVerify.server ? {
+      command: userVerify.server.command || "",
+      url: userVerify.server.url || "http://localhost:3000",
+      timeoutMs: Number(userVerify.server.timeoutMs || 15000),
+    } : null,
+  };
 }
 
 export const TIER_PRESETS = {
@@ -247,8 +257,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     }
   }
 
+  const setupCmd = parsed.setup_cmd || parsed.verify?.setup || "";
   const testCmd = parsed.test_cmd || parsed.verify?.test || "";
+  const teardownCmd = parsed.teardown_cmd || parsed.verify?.teardown || "";
   const buildCmd = parsed.build_cmd || parsed.verify?.build || "";
+  const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 60000;
   const autoVerify = resolveVerify(root);
 
   const activeTier = String(process.env.JULES_TIER || parsed.tier || "ultra").toLowerCase();
@@ -275,8 +288,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     provider: parsed.provider || DEFAULTS.provider,
     tier: activeTier,
     verify: {
+      setup: setupCmd || autoVerify.setup || "",
       test: testCmd || autoVerify.test,
+      teardown: teardownCmd || autoVerify.teardown || "",
       build: buildCmd || autoVerify.build,
+      timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
     },
     scope: normalizeScope(parsed),
     limits: {

package/src/dag-engine.mjs

@@ -330,3 +330,79 @@ export class DagExecutor {
     });
   }
 }
+
+/**
+ * Global Contract Trigger List:
+ * Files matching these patterns are considered global structural contracts.
+ * If ANY modified file matches these patterns, selective test execution MUST yield to full test suite execution (returns null).
+ */
+export const GLOBAL_CONTRACT_PATTERNS = [
+  /^package(-lock)?\.json$/,
+  /^pnpm-lock\.yaml$/,
+  /^yarn\.lock$/,
+  /^tsconfig.*\.json$/,
+  /^schema\./,
+  /\.d\.ts$/,
+  /^\.env/,
+  /^\.agent\//,
+  /^Cargo\.(toml|lock)$/,
+  /^go\.(mod|sum)$/,
+  /^composer\.(json|lock)$/,
+];
+
+/**
+ * Checks if a relative file path matches global contract triggers.
+ */
+export function isGlobalContractFile(filePath = "") {
+  if (typeof filePath !== "string") return false;
+  const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const baseName = normalized.split("/").pop();
+  return GLOBAL_CONTRACT_PATTERNS.some((pattern) => pattern.test(normalized) || pattern.test(baseName));
+}
+
+/**
+ * Resolves affected test files based on modified files and static import analysis.
+ * Returns null if full test suite should be executed (due to global contract change or unknown dependency),
+ * or an array of affected test file paths.
+ */
+export function resolveAffectedTests(modifiedFiles = [], options = {}) {
+  if (!Array.isArray(modifiedFiles) || modifiedFiles.length === 0) {
+    return [];
+  }
+
+  // 1. Check Global Contract Trigger List
+  for (const file of modifiedFiles) {
+    if (isGlobalContractFile(file)) {
+      return null; // Force full test suite execution
+    }
+  }
+
+  const knownTestFiles = Array.isArray(options.knownTestFiles) ? options.knownTestFiles : [];
+  const testSuffixRegex = options.testSuffixRegex || /\.(test|spec)\.(m?[jt]sx?|py|rs|go)$/i;
+
+  const affected = new Set();
+
+  for (const file of modifiedFiles) {
+    if (typeof file !== "string") continue;
+    const normalized = file.replace(/\\/g, "/").replace(/^\.\//, "");
+
+    // If the modified file itself is a test file, add it directly
+    if (testSuffixRegex.test(normalized)) {
+      affected.add(normalized);
+      continue;
+    }
+
+    // Match known test files that import or reference this file/module
+    const baseNameNoExt = normalized.split("/").pop().replace(/\.[^/.]+$/, "");
+    for (const testFile of knownTestFiles) {
+      if (typeof testFile !== "string") continue;
+      const normTest = testFile.replace(/\\/g, "/").replace(/^\.\//, "");
+      if (normTest.includes(baseNameNoExt)) {
+        affected.add(normTest);
+      }
+    }
+  }
+
+  return affected.size > 0 ? Array.from(affected) : null;
+}
+

package/src/engine.mjs

@@ -6,11 +6,26 @@ import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReserva
 import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import fs, { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { createHash } from "node:crypto";
-import { appendTelemetry } from "./telemetry.mjs";
+import { appendTelemetry as appendTelemetryUnsafe } from "./telemetry.mjs";
 
-export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData };
+import { spawn } from "node:child_process";
+import { resolveAffectedTests } from "./dag-engine.mjs";
+
+export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData, resolveAffectedTests };
+
+function appendTelemetry(root, kind, fields = {}) {
+  try {
+    return appendTelemetryUnsafe(root, kind, fields);
+  } catch (_) {
+    return null;
+  }
+}
+
+function isSafeQueueFileName(fileName) {
+  return typeof fileName === "string" && fileName.length > 0 && basename(fileName) === fileName && fileName !== "." && fileName !== "..";
+}
 
 /**
  * Validates whether a file in .agent/jules-queue/ is a task file.
@@ -128,8 +143,11 @@ export async function gate(opts = {}) {
       trustedScope = normalizeScope(parsed);
       if (parsed.verify || parsed.test_cmd || parsed.build_cmd) {
         trustedVerify = {
+          setup: parsed.verify?.setup || config.verify.setup,
           test: parsed.verify?.test || parsed.test_cmd || config.verify.test,
+          teardown: parsed.verify?.teardown || config.verify.teardown,
           build: parsed.verify?.build || parsed.build_cmd || config.verify.build,
+          timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
       }
     } catch (_) {}
@@ -201,34 +219,79 @@ export async function gate(opts = {}) {
   let flakyVerdictResult = null;
 
   if (testCmd) {
-    const startTime = Date.now();
-    const res = runCmd(testCmd, { cwd: root, ignoreError: true, env: testEnv });
-    const durationMs = Date.now() - startTime;
-    testResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: testCmd };
-
-    const fingerprint = !testResult.ok ? fingerprintFailureState(testResult, root) : null;
-    recordVerifyRun(root, testCmd, testResult.ok, fingerprint, durationMs);
-
-    if (!testResult.ok) {
-      const runs = readVerifyRuns(root, testCmd);
-      flakyVerdictResult = flakyVerdict(runs);
-      if (flakyVerdictResult.verdict === "QUARANTINED") {
-        phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult });
-        appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
-        appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
-        return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
+    const setupCmd = trustedVerify.setup;
+    const teardownCmd = trustedVerify.teardown;
+    const verifyTimeout = trustedVerify.timeoutMs;
+
+    try {
+      if (setupCmd) {
+        const setupRes = runCmd(setupCmd, { cwd: root, ignoreError: true, env: testEnv, timeout: verifyTimeout });
+        if (setupRes.status !== 0) {
+          testResult = {
+            ok: false,
+            status: setupRes.status,
+            stdout: redactSecrets(setupRes.stdout || ""),
+            stderr: redactSecrets(setupRes.stderr || ""),
+            command: setupCmd,
+            phase: "setup",
+          };
+        }
+      }
+
+      if (testResult.ok) {
+        const startTime = Date.now();
+        const res = runCmd(testCmd, { cwd: root, ignoreError: true, env: testEnv, timeout: verifyTimeout });
+        const durationMs = Date.now() - startTime;
+        testResult = {
+          ok: res.status === 0,
+          status: res.status,
+          stdout: redactSecrets(res.stdout || ""),
+          stderr: redactSecrets(res.stderr || ""),
+          command: testCmd,
+        };
+
+        const fingerprint = !testResult.ok ? fingerprintFailureState(testResult, root) : null;
+        recordVerifyRun(root, testCmd, testResult.ok, fingerprint, durationMs);
+
+        if (!testResult.ok) {
+          const runs = readVerifyRuns(root, testCmd);
+          flakyVerdictResult = flakyVerdict(runs);
+          if (flakyVerdictResult.verdict === "QUARANTINED") {
+            phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult });
+            appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
+            appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
+            return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
+          }
+        }
+      }
+    } finally {
+      if (teardownCmd) {
+        try {
+          runCmd(teardownCmd, { cwd: root, ignoreError: true, env: testEnv });
+        } catch (_) {}
       }
     }
   }
 
   if (testResult.ok && buildCmd) {
     const res = runCmd(buildCmd, { cwd: root, ignoreError: true, env: testEnv });
-    buildResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: buildCmd };
+    buildResult = {
+      ok: res.status === 0,
+      status: res.status,
+      stdout: redactSecrets(res.stdout || ""),
+      stderr: redactSecrets(res.stderr || ""),
+      command: buildCmd,
+    };
+  }
+
+  let serverResult = { ok: true, status: 0 };
+  if (testResult.ok && buildResult.ok && trustedVerify.server && trustedVerify.server.command) {
+    serverResult = await probeDevServer(trustedVerify.server, root);
   }
 
-  const verifyOk = testResult.ok && buildResult.ok;
-  const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : null;
-  phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult });
+  const verifyOk = testResult.ok && buildResult.ok && serverResult.ok;
+  const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : !serverResult.ok ? serverResult : null;
+  phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult, serverResult });
   appendTelemetry(root, "gate_phase", { phase: "verify", ok: verifyOk });
   if (progressBus && progressToken) {
     progressBus.reportProgress(progressToken, 100, 100, "Phase 4/4: Automated Test & Build Verification complete");
@@ -342,7 +405,7 @@ export async function repair(failure, opts = {}) {
       );
     } catch (err) {
       if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
-        if (err.reservationId) {
+        if (err.reservationId && !err.budgetReservationRolledBack) {
           rollbackBudgetReservation(root, err.reservationId);
         }
         const retryAfterMs = err.retryAfterMs || 60000;
@@ -473,7 +536,10 @@ Stderr:
 ${cleanStderr}`;
 }
 
-export async function dispatch(task, opts = {}) {
+export async function dispatch(task = {}, opts = {}) {
+  if (!task || typeof task !== "object") {
+    throw new TypeError("Dispatch task must be an object");
+  }
   const root = opts.config?._root || opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
   const provider = createProvider(config.provider, config);
@@ -503,7 +569,7 @@ export async function dispatch(task, opts = {}) {
     );
   } catch (err) {
     if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
-      if (err.reservationId) {
+      if (err.reservationId && !err.budgetReservationRolledBack) {
         rollbackBudgetReservation(root, err.reservationId);
       }
       const retryAfterMs = err.retryAfterMs || 60000;
@@ -534,7 +600,8 @@ export async function run(tasksOrOpts = {}, opts = {}) {
 
   const root = options.root || process.cwd();
   const config = options.config || loadConfig(root);
-  const concurrency = options.concurrency || config.limits.concurrency || 1;
+  const requestedConcurrency = Number(options.concurrency ?? config.limits.concurrency ?? 1);
+  const concurrency = Number.isInteger(requestedConcurrency) && requestedConcurrency > 0 ? requestedConcurrency : 1;
   const isDry = options.dryRun !== undefined ? options.dryRun : (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1");
   const queueDir = getQueueDir(root);
   const completedDir = join(queueDir, "completed");
@@ -553,9 +620,12 @@ export async function run(tasksOrOpts = {}, opts = {}) {
     const batch = filesToProcess.slice(i, i + concurrency);
     await Promise.all(
       batch.map(async (fileOrItem) => {
-        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem.id || fileOrItem.file || fileOrItem.title || "task";
-        const srcPath = join(queueDir, fileName);
+        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem?.id || fileOrItem?.file || fileOrItem?.title || "task";
         try {
+          if (!isSafeQueueFileName(fileName)) {
+            throw new Error(`Unsafe queue task path: ${fileName}`);
+          }
+          const srcPath = join(queueDir, fileName);
           let prompt = typeof fileOrItem === "object" && fileOrItem.prompt ? fileOrItem.prompt : "";
           let title = typeof fileOrItem === "object" && fileOrItem.title ? fileOrItem.title : fileName;
           if (!prompt && existsSync(srcPath)) {
@@ -569,6 +639,9 @@ export async function run(tasksOrOpts = {}, opts = {}) {
           } else {
             const dstPath = join(completedDir, fileName);
             if (existsSync(srcPath)) {
+              if (existsSync(dstPath)) {
+                throw new Error(`Completed task destination already exists: ${fileName}`);
+              }
               renameSync(srcPath, dstPath);
             }
             appendLedger({ event: "task_completed", file: fileName, session }, root);
@@ -583,3 +656,195 @@ export async function run(tasksOrOpts = {}, opts = {}) {
 
   return { processed: results.length, results };
 }
+
+/**
+ * Synthesizes a structured, evidence-backed PR description body for GitHub PR creation.
+ * @param {object} session - Session or dispatch result
+ * @param {object} gateResult - Gate evaluation result
+ * @param {object} [options]
+ * @returns {string} Markdown PR description body
+ */
+export function synthesizePrDescription(session = {}, gateResult = {}, options = {}) {
+  const sessionId = session.id || session.name || "jules-session";
+  const attemptsCount = session.attempts?.length || session._warmAttempts || 1;
+  const maxAttempts = options.maxAttempts || 3;
+  const durationMs = options.durationMs || session.durationMs || 0;
+  const durationSec = (durationMs / 1000).toFixed(1);
+  const isWarm = Boolean(session.resumed || session._warmResumed);
+
+  const phases = gateResult.phases || [];
+  const scopePhase = phases.find((p) => p.phase === "scope") || { ok: true, violations: [] };
+  const payloadPhase = phases.find((p) => p.phase === "payload") || { ok: true, bytes: 0, limitBytes: 76800 };
+  const secretPhase = phases.find((p) => p.phase === "secrets") || { ok: true, findings: [] };
+
+  const kbDiff = ((payloadPhase.bytes || 0) / 1024).toFixed(1);
+  const kbLimit = ((payloadPhase.limitBytes || 76800) / 1024).toFixed(0);
+
+  const modifiedFiles = options.modifiedFiles || [];
+  const affectedTests = resolveAffectedTests(modifiedFiles, options);
+
+  const prBody = `## 🚀 Autonomous Jules Agent Execution Evidence
+
+### ⏱️ OODA Verification Trace
+- **Session ID:** \`${sessionId}\`
+- **OODA Turns:** \`${attemptsCount}/${maxAttempts}\`
+- **Warm Resumption:** ${isWarm ? "✅ Active Context Stream" : "Cold Start"}
+- **Execution Latency:** \`${durationSec}s\`
+
+### 🛡️ Zero-Trust Security Audit Matrix
+- **Scope Guard:** ${scopePhase.ok ? "✅ PASS (0 protected path violations)" : "❌ FAIL"}
+- **Diff Payload Governor:** ${payloadPhase.ok ? `✅ PASS (${kbDiff} KB / ${kbLimit} KB limit)` : "❌ EXCEEDED"}
+- **Secret Scanner:** ${secretPhase.ok ? "✅ PASS (0 high-entropy leaks detected)" : "❌ LEAKS FOUND"}
+
+### 🧪 Terminal Verification Evidence
+\`\`\`text
+${options.testOutput || "All verification tests passed with Exit Code 0."}
+\`\`\`
+
+### 📂 AST Impact & Dependency Graph
+${
+  affectedTests === null
+    ? "- **Impact Scope:** ⚠️ Global contract change detected (`package.json`/`tsconfig`/`schema`). Full test suite executed."
+    : affectedTests.length > 0
+    ? `- **Affected Test Suites (${affectedTests.length}):**\n` + affectedTests.map((t) => `  - \`${t}\``).join("\n")
+    : "- **Impact Scope:** Isolated leaf implementation change."
+}
+
+---
+*Generated automatically by [jules-orchestrator-kit](https://github.com/FullThrottle83/jules-orchestrator-kit)*
+`;
+
+  return prBody;
+}
+
+/**
+ * Live Dev Server & SSR Hydration Smoke Prober.
+ * Spawns the server in a detached process group, polls the URL via globalThis.fetch,
+ * intercepts SSR hydration errors, and cleanly kills the process group in a finally block.
+ * @param {object} serverConfig
+ * @param {string} serverConfig.command
+ * @param {string} [serverConfig.url="http://localhost:3000"]
+ * @param {number} [serverConfig.timeoutMs=15000]
+ * @param {string} root
+ * @returns {Promise<object>} Probe result { ok: boolean, status: number, error: string, logs: string }
+ */
+export async function probeDevServer(serverConfig = {}, root = process.cwd()) {
+  if (!serverConfig || !serverConfig.command) {
+    return { ok: true, skipped: true, reason: "No server command configured" };
+  }
+
+  const cmd = serverConfig.command;
+  const url = serverConfig.url || "http://localhost:3000";
+  const timeoutMs = Number(serverConfig.timeoutMs || 15000);
+
+  const isWin = process.platform === "win32";
+  const shellBin = isWin ? (process.env.ComSpec || "cmd.exe") : "/bin/sh";
+  const shellArgs = isWin ? ["/d", "/s", "/c", cmd] : ["-c", cmd];
+
+  let child;
+  let stdoutLogs = "";
+  let stderrLogs = "";
+
+  try {
+    child = spawn(shellBin, shellArgs, {
+      cwd: root,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdoutLogs += chunk.toString("utf-8");
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderrLogs += chunk.toString("utf-8");
+      });
+    }
+
+    const startTime = Date.now();
+    let pollResponse = null;
+    let pollError = null;
+
+    while (Date.now() - startTime < timeoutMs) {
+      if (child.exitCode !== null) {
+        return {
+          ok: false,
+          status: child.exitCode,
+          error: `Dev server process exited prematurely with code ${child.exitCode}`,
+          logs: (stderrLogs || stdoutLogs).slice(-2000),
+        };
+      }
+
+      try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+        const bodyText = await res.text();
+        pollResponse = { status: res.status, bodyText, ok: res.ok };
+        break;
+      } catch (err) {
+        pollError = err;
+      }
+
+      await new Promise((r) => setTimeout(r, 400));
+    }
+
+    if (!pollResponse) {
+      return {
+        ok: false,
+        status: 504,
+        error: `Dev server probe timed out after ${timeoutMs}ms attempting to reach ${url}. ${pollError ? pollError.message : ""}`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    const combinedLogs = (stderrLogs + "\n" + pollResponse.bodyText).toLowerCase();
+    const hydrationPanics = [
+      "hydration failed",
+      "text content did not match",
+      "unhandled runtime error",
+      "minified react error #418",
+      "minified react error #423",
+      "minified react error #425",
+    ];
+
+    const detectedPanic = hydrationPanics.find((panic) => combinedLogs.includes(panic));
+    if (detectedPanic) {
+      return {
+        ok: false,
+        status: 500,
+        error: `SSR Hydration Smoke Probe Failure: Detected '${detectedPanic}' error in server response or stderr.`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    if (!pollResponse.ok) {
+      return {
+        ok: false,
+        status: pollResponse.status,
+        error: `Dev server responded with HTTP status ${pollResponse.status}`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    return {
+      ok: true,
+      status: pollResponse.status,
+      url,
+      logs: stdoutLogs.slice(-500),
+    };
+  } finally {
+    if (child && child.pid) {
+      try {
+        if (isWin) {
+          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+        } else {
+          process.kill(-child.pid, "SIGTERM");
+        }
+      } catch (_) {}
+    }
+  }
+}
+
+

package/src/envelope.mjs

@@ -2,7 +2,7 @@ import { git, runCmd, resolveBase } from "./git.mjs";
 import { checkScope } from "./security.mjs";
 import { normalizeScope } from "./config.mjs";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { resolve, relative, isAbsolute } from "node:path";
 
 /**
  * Validates a Task Envelope before dispatch or during CI triage.
@@ -67,7 +67,12 @@ export function validateEnvelope(envelope = {}, opts = {}) {
   if (Array.isArray(envelope.referenced_paths)) {
     for (const relPath of envelope.referenced_paths) {
       if (typeof relPath !== "string") continue;
-      const absPath = join(root, relPath);
+      const absPath = resolve(root, relPath);
+      const rootRelative = relative(resolve(root), absPath);
+      if (isAbsolute(rootRelative) || rootRelative === ".." || rootRelative.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+        errors.push(`Premise failure: referenced path '${relPath}' escapes repository root.`);
+        continue;
+      }
       let existsInGit = false;
       if (resolvedBase) {
         const catRes = runCmd(["git", "cat-file", "-e", `${resolvedBase}:${relPath}`], { cwd: root, ignoreError: true });
@@ -103,3 +108,20 @@ export function validateEnvelope(envelope = {}, opts = {}) {
     warnings,
   };
 }
+
+/**
+ * Parse JSON metadata payload embedded in HTML comment JULES_TASK_ENVELOPE.
+ * @param {string} content
+ * @returns {Record<string, any> | null}
+ */
+export function parseEnvelopeHeader(content) {
+  if (!content) return null;
+  const match = String(content).match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+

package/src/mcp.mjs

@@ -148,6 +148,19 @@ export const MCP_TOOLS = [
       },
     },
   },
+  {
+    name: "optimize_jules_prompt",
+    description: "Evaluate task prompt falsifiability, check static path validity, and synthesize optimized task envelope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Raw task prompt instructions to analyze or optimize" },
+        fix: { type: "boolean", description: "If true, synthesizes and returns an optimized task envelope" },
+        verifyCmd: { type: "string", description: "Optional explicit verification command" },
+      },
+      required: ["prompt"],
+    },
+  },
 ];
 
 export async function handleMcpRequest(request, opts = {}) {
@@ -291,6 +304,27 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "optimize_jules_prompt") {
+        if (!args || typeof args.prompt !== "string") {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Invalid parameters: 'prompt' must be a string" },
+          };
+        }
+        const { scorePromptFalsifiability, optimizeTaskPrompt } = await import("./task-optimizer.mjs");
+        const res = args.fix
+          ? optimizeTaskPrompt(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd })
+          : scorePromptFalsifiability(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,