jules-orchestrator-kit 0.72.2 → 0.73.0

package/src/self-audit.mjs

@@ -0,0 +1,140 @@
+/**
+ * Self-audit gatekeeper: runs the 4-phase safety gate against the working
+ * tree or base branch, plus the ledger/worktree/config audits around it.
+ *
+ * This is the home of the logic that used to live in
+ * `scripts/jules-self-audit.mjs`; that file is now a minimal CLI entry point.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { gate } from "./engine.mjs";
+import { loadConfig, parseYaml } from "./config.mjs";
+import { matchesGlob } from "./security.mjs";
+
+/** Convenience wrapper kept for the historical `matchGlob` name. */
+export function matchGlob(filepath, globPattern) {
+  return matchesGlob(filepath, globPattern);
+}
+
+export const EXECUTION_CONFIG_FILES = ["package.json", "tsconfig.json", "Cargo.toml", "go.mod", "pyproject.toml", "vite.config.ts", "jest.config.js", ".npmrc"];
+export const RESTRICTED_AGENT_FILES = ["AGENTS.md", "JULES_RULES_TEMPLATE.md"];
+export const COMMAND_DEFINING_FILES = ["package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".agent/jules.yml", ".agent/config.yml"];
+
+export function loadForbiddenPatterns(configContent = "") {
+  const defaults = ["scripts/jules-*", ".agent/jules.yml", ".github/**", "**/*.pem"];
+  if (!configContent) return defaults;
+  const parsed = parseYaml(configContent);
+  const userPaths = Array.isArray(parsed.forbidden_paths) ? parsed.forbidden_paths : [];
+  return Array.from(new Set([...defaults, ...userPaths]));
+}
+
+export function loadAllowedPatterns(configContent = "") {
+  if (!configContent) return [];
+  const parsed = parseYaml(configContent);
+  return Array.isArray(parsed.allow_paths) ? parsed.allow_paths : [];
+}
+
+export function validateJulesConfig(_configContent = "", jsonGuardrailsContent = "") {
+  const errors = [];
+  if (jsonGuardrailsContent) {
+    try {
+      const parsed = JSON.parse(jsonGuardrailsContent);
+      if (Array.isArray(parsed.rules)) {
+        for (const rule of parsed.rules) {
+          try {
+            new RegExp(rule.trigger, "i");
+          } catch (err) {
+            errors.push(`Invalid RegExp trigger: ${err.message}`);
+          }
+        }
+      }
+    } catch (err) {
+      errors.push(`JSON Parse Error: ${err.message}`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function parseAndCleanStderr(str = "") {
+  if (typeof str !== "string") return "";
+  return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "").replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+export function getOodaStateFile(mergeBase = "main") {
+  return `.agent/state/ooda-${mergeBase}.json`;
+}
+
+/**
+ * Audit ledger states and verify integrity of ledger/state files.
+ */
+export function auditLedgers(opts = {}) {
+  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
+  const stateDir = join(root, ".agent", "state");
+  const exists = existsSync(stateDir);
+  return { ok: true, stateDir, exists };
+}
+
+/**
+ * Audit git worktrees and active workspace boundaries.
+ */
+export function auditWorktrees(opts = {}) {
+  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
+  const worktreeDir = join(root, ".agent", "worktrees");
+  const exists = existsSync(worktreeDir);
+  return { ok: true, worktreeDir, exists };
+}
+
+/**
+ * Audit gate rules (scope, payload governor, secret scanning, verification suite).
+ */
+export async function auditGates(opts = {}) {
+  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
+  const config = opts.config || loadConfig(root);
+  const base = opts.base || process.env.BASE_BRANCH || config.baseBranch || "main";
+
+  return await gate({
+    root,
+    config,
+    base,
+    fix: process.env.ALLOW_AUTO_REPAIR === "true",
+    allowProtected: process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
+    allowTestChanges: process.env.JULES_ALLOW_TEST_CHANGES || opts.allowTestChanges,
+  });
+}
+
+/**
+ * Main self-audit entrypoint executing validation passes.
+ */
+export async function runSelfAudit(opts = {}) {
+  const root = opts.root || process.env.JULES_PROJECT_ROOT || process.cwd();
+  const config = loadConfig(root);
+  const base = opts.base || process.env.BASE_BRANCH || config.baseBranch || "main";
+
+  const optsWithContext = { ...opts, root, config, base };
+
+  const ledgersResult = auditLedgers(optsWithContext);
+  const worktreesResult = auditWorktrees(optsWithContext);
+  const gatesResult = await auditGates(optsWithContext);
+
+  if (!gatesResult.ok) {
+    return gatesResult;
+  }
+
+  return {
+    ...gatesResult,
+    audits: {
+      ledgers: ledgersResult,
+      worktrees: worktreesResult,
+      gates: gatesResult,
+    },
+  };
+}
+
+/**
+ * Preflight sandbox probe. Retained as a compatibility surface: the sandbox
+ * it once wrapped is now executed by the gate itself, so it reports ok.
+ */
+export async function runPreflightSandbox() {
+  return { ok: true };
+}

package/src/session-ops.mjs

@@ -219,6 +219,35 @@ export async function extractSessionPatch(sessionId, opts = {}) {
  * @param {object} opts
  * @returns {Promise<{ ok: boolean, patchApplied: boolean, checkPassed: boolean, patch: string, files: string[], error?: string }>}
  */
+/**
+ * Fetch a session patch with argument validation at the boundary.
+ * (Moved out of scripts/jules-patch.mjs, which keeps a CLI entry point.)
+ */
+export async function fetchSessionPatch(sessionId, options = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new Error("Session ID is required.");
+  }
+  return await extractSessionPatch(sessionId, options);
+}
+
+/**
+ * Maps a Jules session state to the coarse bucket the status CLI reports.
+ * (Moved out of scripts/jules-status.mjs, which keeps a CLI entry point.)
+ */
+export function categorizeTaskStatus(statusStr = "") {
+  const s = String(statusStr).toUpperCase();
+  if (s === "AWAITING_PLAN_APPROVAL" || s === "AWAITING_USER_FEEDBACK") {
+    return "action_required";
+  }
+  if (s === "IN_PROGRESS" || s === "DISPATCHED") {
+    return "in_progress";
+  }
+  if (s === "COMPLETED" || s === "FAILED") {
+    return "completed";
+  }
+  return "unknown";
+}
+
 export async function applySessionPatch(sessionId, opts = {}) {
   const root = opts.root || resolveRoot();
   const res = await extractSessionPatch(sessionId, { ...opts, root });

package/src/stability.mjs

@@ -1,6 +1,6 @@
 import { execSync } from "node:child_process";
 import { resolveVerify } from "./config.mjs";
-import { computeOscillation } from "./flaky-ledger.mjs";
+import { computeOscillation, recordVerifyRun } from "./flaky-ledger.mjs";
 
 /**
  * Executes a test command repeatedly to probe for race conditions, non-deterministic timers, or test flakiness.
@@ -11,6 +11,7 @@ import { computeOscillation } from "./flaky-ledger.mjs";
  * @param {number} [options.repeat=5] - Number of consecutive iterations to execute
  * @param {number} [options.minPassRate=1.0] - Required minimum pass rate (0.0 - 1.0)
  * @param {number} [options.timeoutMs=30000] - Timeout per iteration in milliseconds
+ * @param {boolean} [options.record=true] - Whether to record run outcomes to .agent/state/flaky.jsonl
  * @returns {object} { ok, repeat, passes, failures, passRate, oscillation, runs, durationMs, summary }
  */
 export function runStabilityProbe(testCmd, options = {}) {
@@ -19,6 +20,7 @@ export function runStabilityProbe(testCmd, options = {}) {
   const repeat = typeof options.repeat === "number" && options.repeat > 0 ? options.repeat : 5;
   const minPassRate = typeof options.minPassRate === "number" ? options.minPassRate : 1.0;
   const timeoutMs = options.timeoutMs || 30000;
+  const shouldRecord = options.record !== false;
 
   const runs = [];
   let passes = 0;
@@ -57,6 +59,11 @@ export function runStabilityProbe(testCmd, options = {}) {
     }
 
     const duration = Date.now() - runStart;
+    if (shouldRecord) {
+      const fingerprint = !pass && stderr ? stderr.trim().slice(0, 200) : null;
+      recordVerifyRun(root, cmd, pass, fingerprint, duration);
+    }
+
     runs.push({
       iteration: i,
       pass,

package/src/stack-detector.mjs

@@ -221,7 +221,10 @@ test("every source file parses", () => {
 }
 
 export function detectEdgeRuntime(projectRoot = process.cwd()) {
-  const isCloudflare = existsSync(join(projectRoot, "wrangler.toml")) || existsSync(join(projectRoot, "wrangler.json"));
+  const isCloudflare =
+    existsSync(join(projectRoot, "wrangler.toml")) ||
+    existsSync(join(projectRoot, "wrangler.json")) ||
+    existsSync(join(projectRoot, "wrangler.jsonc"));
   const isDeno = existsSync(join(projectRoot, "deno.json")) || existsSync(join(projectRoot, "deno.jsonc"));
   const isNetlify = existsSync(join(projectRoot, "netlify.toml"));
 
@@ -441,7 +444,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
 
   // 5. Python / Django / Elixir / Ruby / Java
   if (existsSync(join(projectRoot, "manage.py"))) {
-    return { ...container, stack: "django", testCmd: "python manage.py test --keepdb", buildCmd: "python manage.py check", triggerFile: "manage.py" };
+    return { ...container, stack: "django", testCmd: `${pythonBin()} manage.py test --keepdb`, buildCmd: `${pythonBin()} manage.py check`, triggerFile: "manage.py" };
   }
   if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
     const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";

package/src/state.mjs

@@ -10,6 +10,7 @@ import {
   fsyncSync,
   unlinkSync,
   lstatSync,
+  statSync,
 } from "node:fs";
 import { join, basename } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -57,6 +58,32 @@ export function getDailyLedgerPath(rootOrOpts = resolveRoot()) {
   return join(getStateDir(root), `ledger-${dateStr}.jsonl`);
 }
 
+/**
+ * Delete files in a ledger/state directory older than `retentionDays`.
+ *
+ * Moved out of the deleted scripts/utils.mjs shim; the ledger rotation policy
+ * lives with the ledger.
+ *
+ * @param {string} stateDir
+ * @param {number} [retentionDays=30]
+ */
+export function pruneOldLedgers(stateDir, retentionDays = 30) {
+  if (!existsSync(stateDir)) return;
+  const cutoff = Date.now() - retentionDays * 86400 * 1000;
+  try {
+    const files = readdirSync(stateDir);
+    for (const f of files) {
+      const full = join(stateDir, f);
+      try {
+        const stat = statSync(full);
+        if (stat.isFile() && stat.mtimeMs < cutoff) {
+          unlinkSync(full);
+        }
+      } catch (_) {}
+    }
+  } catch (_) {}
+}
+
 /**
  * How far back a task still counts against the allowance.
  *
@@ -351,6 +378,24 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300, opts = {}) {
   }
 }
 
+/**
+ * Reserve one unit of the daily budget, nameably.
+ *
+ * @param {number} [maxSessions=300]
+ * @param {string} [taskKey=""]
+ * @param {string} [root] - Ledger root. Defaults to the git toplevel. Pass an
+ *   explicit root to keep callers (notably tests) off the operator's real ledger.
+ */
+export function reserveDailyBudget(maxSessions = 300, taskKey = "", root = resolveRoot()) {
+  // The id is what makes the reservation releasable. Written without one, a
+  // reservation counted against the day and no rollback, commit or reconcile
+  // could ever name it again — it stayed charged until the ledger rotated.
+  const reservationId = `res-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  appendLedger({ event: "budget_reserved", reservationId, key: taskKey }, root);
+  const check = checkDailyBudget(root, maxSessions);
+  return { ok: check.ok, used: check.used, budget: maxSessions, reservationId };
+}
+
 export class BudgetError extends Error {
   constructor(message) {
     super(message);

package/src/swarm.mjs

@@ -0,0 +1,76 @@
+/**
+ * Swarm session audit & reservation sync manifest.
+ *
+ * Extracted from the deleted `scripts/utils.mjs` shim. These four functions
+ * are the SDK-level surface index.mjs re-exports (extractPrUrls,
+ * auditSessions, buildSyncManifest, pushReservationManifest): parsing PR
+ * links out of session outputs, bucketing sessions by staleness, and writing
+ * the swarm reservation manifest the merge gate reads.
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+export function extractPrUrls(outputs = []) {
+  const prs = [];
+  const regex = /https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/g;
+  for (const item of outputs) {
+    const text = typeof item === "string" ? item : item?.link || JSON.stringify(item);
+    const matches = text.match(regex);
+    if (matches) {
+      for (const m of matches) {
+        if (!prs.includes(m)) prs.push(m);
+      }
+    }
+  }
+  return prs;
+}
+
+export function auditSessions(sessions = [], opts = {}) {
+  const staleHoursThreshold = opts.staleHoursThreshold || 24;
+  const now = Date.now();
+  const merged = [];
+  const active = [];
+  const stale = [];
+
+  for (const s of sessions) {
+    if (s.state === "MERGED") {
+      merged.push(s);
+    } else {
+      const updatedMs = s.updateTime ? new Date(s.updateTime).getTime() : now;
+      const ageHours = (now - updatedMs) / (1000 * 60 * 60);
+      if (ageHours > staleHoursThreshold) {
+        stale.push(s);
+      } else {
+        active.push(s);
+      }
+    }
+  }
+
+  return { merged, active, stale };
+}
+
+export function buildSyncManifest(tasks = []) {
+  const reservations = tasks.map((t) => ({ id: t.id, title: t.title, scope: t.scope }));
+  return {
+    version: 1,
+    totalTasks: tasks.length,
+    reservations,
+  };
+}
+
+export async function pushReservationManifest(manifest, projectRoot = process.cwd()) {
+  const isDry = process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1";
+  const isRemote = process.env.JULES_SWARM_REMOTE_PUSH === "true";
+
+  const agentDir = join(projectRoot, ".agent");
+  if (!existsSync(agentDir)) {
+    try { mkdirSync(agentDir, { recursive: true }); } catch (_) {}
+  }
+  const manifestPath = join(agentDir, "sync-manifest.json");
+  try { writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8"); } catch (_) {}
+
+  if (isDry) return { status: "DRY_RUN", path: manifestPath };
+  if (isRemote) return { status: "PUSHED", path: manifestPath };
+  return { status: "SAVED_LOCAL", path: manifestPath };
+}

package/src/task-optimizer.mjs

@@ -4,6 +4,7 @@ import { checkScope } from "./security.mjs";
 import { detectStackOracles } from "./wizard-oracle.mjs";
 import { loadConfig } from "./config.mjs";
 import { sanitizePromptVocabulary } from "./prompt-guard.mjs";
+import { buildGuardrailFooter } from "./wizard-task.mjs";
 
 /**
  * Calculates Levenshtein distance between two strings.
@@ -350,7 +351,7 @@ export function optimizeTaskPrompt(promptText, options = {}) {
   const isWeb = Boolean(options.web || (analysis.webIntent && analysis.webIntent.isWeb));
   const includeExplorationBudget = options.explorationBudget !== false;
   const includeCriticGuidance = options.criticGuidance !== false;
-  const verifyCmd = analysis.oracle.command || options.verifyCmd || "npm test";
+  const verifyCmd = analysis.oracle.command || options.verifyCmd || null;
 
   // Construct structured Markdown envelope
   const lines = [];
@@ -359,16 +360,24 @@ export function optimizeTaskPrompt(promptText, options = {}) {
 
   if (includeExplorationBudget) {
     lines.push("## Google Labs Exploration Budget Protocol (3-Phase Discovery)");
-    lines.push("To maximize diagnostic accuracy (Hit@5 57%), execute this task in 3 distinct phases:");
+    lines.push("Use deep planning mode. execute this task in 3 distinct phases (Discovery, Test Formulation, Surgical Implementation):");
     lines.push("1. **PHASE 1: DISCOVERY & SYMBOL TRACING (Stay Silent, Write NO Code)**");
     lines.push("   - Read target source files, definitions, and dependent call sites.");
     lines.push("   - Formulate diagnostic hypothesis and verify exact symbol signatures before making edits.");
     lines.push("2. **PHASE 2: ORACLE FORMULATION**");
-    lines.push(`   - Execute baseline verification: \`${verifyCmd}\`.`);
+    if (verifyCmd) {
+      lines.push(`   - Execute baseline verification: \`${verifyCmd}\`.`);
+    } else {
+      lines.push("   - Execute baseline verification: (None specified - define verification command).");
+    }
     lines.push("   - Identify specific test assertions, benchmarks, or status codes to satisfy.");
     lines.push("3. **PHASE 3: SURGICAL IMPLEMENTATION & VERIFICATION**");
     lines.push("   - Apply minimal, zero-bloat code modifications.");
-    lines.push(`   - Execute \`${verifyCmd}\` and verify 100% clean exit code 0.`);
+    if (verifyCmd) {
+      lines.push(`   - Execute \`${verifyCmd}\` and verify 100% clean exit code 0.`);
+    } else {
+      lines.push("   - Execute automated verification suite and verify 100% clean exit code 0.");
+    }
     lines.push("");
   }
 
@@ -376,6 +385,8 @@ export function optimizeTaskPrompt(promptText, options = {}) {
   lines.push(`- **Goal**: ${promptBody}`);
   if (analysis.oracle.command) {
     lines.push(`- **Verification Command**: \`${analysis.oracle.command}\` (Must pass cleanly with exit code 0)`);
+  } else {
+    lines.push("- **Verification Command**: (None) - WARNING: Missing test oracle.");
   }
   lines.push("- **Falsifiability Criteria**: Zero deleted tests, zero weakened assertions, zero lint errors.");
   lines.push("");
@@ -401,10 +412,26 @@ export function optimizeTaskPrompt(promptText, options = {}) {
     lines.push("");
   }
 
+  const root = options.rootDir || process.cwd();
+  let cfg = options.config;
+  if (!cfg) {
+    try {
+      cfg = loadConfig(root);
+    } catch (_) {
+      cfg = {};
+    }
+  }
+
   lines.push("## Standard Guardrails");
-  lines.push("- Do NOT modify package.json, lockfiles, or .github/ infrastructure files.");
-  lines.push("- Diff Payload Governor: Keep total diff payload under 75 KB (\`git diff | wc -c\`).");
-  lines.push(`- Verify before finishing: Execute \`${verifyCmd}\` and confirm zero errors.`);
+  const rawFooter = buildGuardrailFooter(cfg, {
+    baseBranch: options.baseBranch,
+    diffKb: options.diffKb,
+  }).trim();
+  const cleanedFooter = rawFooter.replace(/^---\s*\n?HARD CONSTRAINTS:\s*\n?/, "").trim();
+  lines.push(cleanedFooter);
+  if (verifyCmd) {
+    lines.push(`- Verify before finishing: Execute \`${verifyCmd}\` and confirm zero errors.`);
+  }
 
   const optimizedPrompt = lines.join("\n");
 

package/src/telemetry.mjs

@@ -226,6 +226,29 @@ export function appendTelemetry(rootOrOpts = resolveRoot(), kind = "event", fiel
   });
 }
 
+/**
+ * Best-effort companion to {@link appendTelemetry}: records the event when it
+ * can, and returns null instead of throwing when it cannot.
+ *
+ * Telemetry is diagnostic data. A gate verdict must never hinge on the mutex
+ * or disk write that logs how the verdict came about, so the safety policy
+ * "telemetry failures are swallowed" lives here, in the module that owns
+ * appending, instead of being re-implemented by each caller that needs it
+ * (src/engine.mjs carried its own copy of this wrapper).
+ *
+ * @param {string} [root]
+ * @param {string} kind
+ * @param {Object} [fields={}]
+ * @returns {Object|null} Appended telemetry record, or null if it was not written
+ */
+export function appendTelemetryBestEffort(root = resolveRoot(), kind = "event", fields = {}) {
+  try {
+    return appendTelemetry(root, kind, fields);
+  } catch (_) {
+    return null;
+  }
+}
+
 /**
  * Days of telemetry kept on disk.
  *