jules-orchestrator-kit 0.42.0 → 0.52.0

package/src/ops/checkpoint.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { git, changedFiles, diffText } from "../git.mjs";
-import { resolveRoot } from "../config.mjs";
+import { resolveRoot, isWindowsAbsolutePath } from "../config.mjs";
 
 export class CheckpointError extends Error {
   constructor(message, opts = {}) {
@@ -11,6 +11,29 @@ export class CheckpointError extends Error {
   }
 }
 
+// Checkpoint ids are used verbatim as the snapshot filename under
+// `.agent/state/checkpoints/`. An id that is not a single plain filename —
+// `../…`, `C:\…`, `\\server\share`, or any value carrying a separator — would
+// let a restore read (or a create write) outside that directory. Ids are
+// therefore restricted to one `[A-Za-z0-9]`-led filename component, and the
+// drive/UNC spellings are rejected explicitly on top of the whitelist
+// (`SEC-02` / `P-01`).
+const CHECKPOINT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function assertSafeCheckpointId(id) {
+  if (
+    typeof id !== "string" ||
+    id.length === 0 ||
+    isWindowsAbsolutePath(id) ||
+    !CHECKPOINT_ID_RE.test(id)
+  ) {
+    throw new CheckpointError(
+      `Invalid checkpoint session id '${id}': expected a plain filename (letters, digits, '.', '_', '-') without path separators.`
+    );
+  }
+  return id;
+}
+
 /**
  * Ensures checkpoint storage directory exists.
  */
@@ -29,6 +52,7 @@ export function getCheckpointDir(root = resolveRoot()) {
  * @returns {object} Checkpoint metadata
  */
 export function createCheckpoint(sessionId = `session-${Date.now()}`, options = {}) {
+  const safeId = assertSafeCheckpointId(sessionId);
   const root = options.root || resolveRoot();
   const dir = getCheckpointDir(root);
 
@@ -47,7 +71,7 @@ export function createCheckpoint(sessionId = `session-${Date.now()}`, options =
 
   const snapshot = {
     version: 1,
-    id: sessionId,
+    id: safeId,
     timestamp: new Date().toISOString(),
     headSha,
     branch,
@@ -55,7 +79,7 @@ export function createCheckpoint(sessionId = `session-${Date.now()}`, options =
     diffContent,
   };
 
-  const snapshotPath = join(dir, `${sessionId}.json`);
+  const snapshotPath = join(dir, `${safeId}.json`);
   writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
 
   // Keep last 10 checkpoints
@@ -83,6 +107,10 @@ export function restoreCheckpoint(sessionId = "--latest", options = {}) {
     targetId = list[0].id;
   }
 
+  // A caller-supplied id becomes a filename here; reject anything that is not
+  // a plain filename before `join` can turn it into a path escape (`P-01`).
+  targetId = assertSafeCheckpointId(targetId);
+
   const snapshotFile = join(dir, `${targetId}.json`);
   if (!existsSync(snapshotFile)) {
     throw new CheckpointError(`Checkpoint snapshot file not found for session '${targetId}'.`);

package/src/perf.mjs

@@ -0,0 +1,92 @@
+import { monitorEventLoopDelay } from "node:perf_hooks";
+import { execSync } from "node:child_process";
+import { resolveVerify } from "./config.mjs";
+
+/**
+ * Measures Node.js Event Loop delay during test execution or asynchronous workloads
+ * to detect synchronous blocking, catastrophic regex backtracking, or O(n^2) starvation.
+ *
+ * @param {string|Function} target - Command line string to execute or async/sync function
+ * @param {object} [options]
+ * @param {string} [options.root=process.cwd()] - Working directory
+ * @param {number} [options.maxDelayMs=50] - Maximum allowable p99/max event loop delay in milliseconds
+ * @param {number} [options.resolution=10] - Sampling resolution in milliseconds (default: 10)
+ * @param {number} [options.timeoutMs=60000] - Process timeout in milliseconds
+ * @returns {object} { ok, maxMs, meanMs, p50Ms, p90Ms, p99Ms, minMs, thresholdMs, summary, stdout, stderr, exitCode }
+ */
+export function measureEventLoopDelay(target, options = {}) {
+  const root = options.root || process.cwd();
+  const maxDelayMs = typeof options.maxDelayMs === "number" ? options.maxDelayMs : 50;
+  const resolution = options.resolution || 10;
+  const timeoutMs = options.timeoutMs || 60000;
+
+  const histogram = monitorEventLoopDelay({ resolution });
+  histogram.enable();
+
+  let exitCode = 0;
+  let stdout = "";
+  let stderr = "";
+
+  const startTime = Date.now();
+
+  try {
+    if (typeof target === "function") {
+      target();
+    } else {
+      const cmd = target || resolveVerify(root).testCmd || "npm test";
+      const env = { ...process.env };
+      for (const k of Object.keys(env)) {
+        if (k.startsWith("NODE_TEST_") || k.startsWith("NODE_CHANNEL_")) {
+          delete env[k];
+        }
+      }
+
+      try {
+        stdout = execSync(cmd, {
+          cwd: root,
+          env,
+          timeout: timeoutMs,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        });
+      } catch (err) {
+        exitCode = err.status || 1;
+        stdout = err.stdout ? String(err.stdout) : "";
+        stderr = err.stderr ? String(err.stderr) : err.message;
+      }
+    }
+  } finally {
+    histogram.disable();
+  }
+
+  const durationMs = Date.now() - startTime;
+
+  // Convert nanoseconds to milliseconds
+  const minMs = Math.round((histogram.min / 1e6) * 100) / 100;
+  const maxMs = Math.round((histogram.max / 1e6) * 100) / 100;
+  const meanMs = Number.isFinite(histogram.mean) ? Math.round((histogram.mean / 1e6) * 100) / 100 : 0;
+  const p50Ms = Math.round((histogram.percentile(50) / 1e6) * 100) / 100;
+  const p90Ms = Math.round((histogram.percentile(90) / 1e6) * 100) / 100;
+  const p99Ms = Math.round((histogram.percentile(99) / 1e6) * 100) / 100;
+
+  // If p99 or max exceeds threshold, mark as lag violation
+  const ok = exitCode === 0 && (p99Ms <= maxDelayMs || maxMs <= maxDelayMs);
+
+  const summary = `Event Loop Delay: p99=${p99Ms}ms, max=${maxMs}ms, mean=${meanMs}ms (threshold: ${maxDelayMs}ms, duration: ${durationMs}ms)`;
+
+  return {
+    ok,
+    minMs,
+    maxMs,
+    meanMs,
+    p50Ms,
+    p90Ms,
+    p99Ms,
+    thresholdMs: maxDelayMs,
+    durationMs,
+    exitCode,
+    stdout,
+    stderr,
+    summary,
+  };
+}

package/src/provider.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, extname } from "node:path";
 import { redactSecrets } from "./security.mjs";
+import { resolveWindowsSpawn } from "./git.mjs";
 
 // Extensions node --check can parse as a script. .mjs/.cjs are unambiguous;
 // plain .js is checked as a script too — a stray top-level ESM import would
@@ -509,10 +510,18 @@ export function createProvider(spec = "jules", config = {}) {
 
         const processedArgs = filteredArgs.map((arg) => interpolateString(arg, data));
 
-        const res = spawnSync(command, processedArgs, {
+        // `claude`, `gemini` and `codex` are npm-installed CLI binaries, which on
+        // Windows are `.cmd` shims that `spawnSync(..., { shell: false })` cannot
+        // start (CreateProcess cannot run a batch file). Route them through
+        // cmd.exe with per-argument quoting instead (P-08); on other platforms
+        // this is a null and the command spawns directly as before.
+        const winSpawn = resolveWindowsSpawn(command, processedArgs, process.env);
+
+        const res = spawnSync(winSpawn ? winSpawn.file : command, winSpawn ? winSpawn.args : processedArgs, {
           cwd: config._root || process.cwd(),
           encoding: "utf-8",
           shell: false,
+          windowsVerbatimArguments: Boolean(winSpawn && winSpawn.verbatim),
           input: providerSpec.promptViaStdin ? data.prompt : undefined,
           timeout: providerSpec.timeoutMs || 900000,
           maxBuffer: 32 * 1024 * 1024,
@@ -682,9 +691,9 @@ export function createProvider(spec = "jules", config = {}) {
       }
 
       if (providerSpec.type === "http") {
-        const getSessionUrlTemplate = providerSpec.getSessionUrl || `${providerSpec.url}/${sessionId}`;
+        const getSessionUrlTemplate = ctx.customUrl || providerSpec.getSessionUrl || `${providerSpec.url}/${sessionId}`;
         const urlData = { sessionId, ...ctx };
-        const url = interpolateString(getSessionUrlTemplate, urlData);
+        const url = ctx.customUrl || interpolateString(getSessionUrlTemplate, urlData);
 
         const headerData = { ...urlData, token: rawToken };
         const headers = {};
@@ -711,8 +720,9 @@ export function createProvider(spec = "jules", config = {}) {
           let res;
           try {
             res = await fetch(url, {
-              method: "GET",
+              method: ctx.method || "GET",
               headers,
+              body: ctx.body ? JSON.stringify(ctx.body) : undefined,
               signal: AbortSignal.timeout(timeoutMs),
             });
           } catch (err) {
@@ -807,9 +817,9 @@ export function createProvider(spec = "jules", config = {}) {
       }
 
       if (providerSpec.type === "http") {
-        const approvePlanUrlTemplate = providerSpec.approvePlanUrl || `${providerSpec.url}/${sessionId}:approvePlan`;
+        const approvePlanUrlTemplate = ctx.customUrl || providerSpec.approvePlanUrl || `${providerSpec.url}/${sessionId}:approvePlan`;
         const urlData = { sessionId, ...ctx };
-        const url = interpolateString(approvePlanUrlTemplate, urlData);
+        const url = ctx.customUrl || interpolateString(approvePlanUrlTemplate, urlData);
 
         const headerData = { ...urlData, token: rawToken };
         const headers = {};
@@ -909,6 +919,94 @@ export function createProvider(spec = "jules", config = {}) {
 
       throw new Error(`Unsupported provider type: ${providerSpec.type}`);
     },
+
+    async listSessions(ctx = {}) {
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { sessions: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions";
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          sessions: res?.raw?.sessions || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { sessions: [], raw: {} };
+    },
+
+    async listActivities(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("listActivities() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { activities: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}/activities`;
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          activities: res?.raw?.activities || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { activities: [], raw: {} };
+    },
+
+    async archiveSession(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("archiveSession() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { id: sessionId, archived: true, raw: {} };
+      if (providerSpec.type === "http") {
+        const url = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}:archive`;
+        const res = await this.approvePlan(sessionId, { ...ctx, customUrl: url });
+        return { id: sessionId, archived: true, raw: res?.raw || {} };
+      }
+      return { id: sessionId, archived: true, raw: {} };
+    },
+
+    async deleteSession(sessionId, ctx = {}) {
+      if (!sessionId || typeof sessionId !== "string") {
+        throw new TypeError("deleteSession() requires a valid sessionId string");
+      }
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { id: sessionId, deleted: true, raw: {} };
+      if (providerSpec.type === "http") {
+        const url = `${providerSpec.url || "https://jules.googleapis.com/v1alpha/sessions"}/${sessionId}`;
+        const res = await this.getSession("", { ...ctx, customUrl: url, method: "DELETE" });
+        return { id: sessionId, deleted: true, raw: res?.raw || {} };
+      }
+      return { id: sessionId, deleted: true, raw: {} };
+    },
+
+    async listSources(ctx = {}) {
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      if (ctx.dryRun) return { sources: [], raw: {} };
+      if (providerSpec.type === "http") {
+        const baseUrl = "https://jules.googleapis.com/v1alpha/sources";
+        const params = new URLSearchParams();
+        if (ctx.pageSize) params.set("pageSize", String(ctx.pageSize));
+        if (ctx.pageToken) params.set("pageToken", String(ctx.pageToken));
+        const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+        const res = await this.getSession("", { ...ctx, customUrl: url });
+        return {
+          sources: res?.raw?.sources || [],
+          nextPageToken: res?.raw?.nextPageToken,
+          raw: res?.raw || {},
+        };
+      }
+      return { sources: [], raw: {} };
+    },
   };
 }
 
@@ -1029,6 +1127,26 @@ export function createFailoverProvider(providers = ["jules"], config = {}) {
       }
     },
 
+    async listSessions(ctx = {}) {
+      return providerList[0].listSessions(ctx);
+    },
+
+    async listActivities(sessionId, ctx = {}) {
+      return providerList[0].listActivities(sessionId, ctx);
+    },
+
+    async archiveSession(sessionId, ctx = {}) {
+      return providerList[0].archiveSession(sessionId, ctx);
+    },
+
+    async deleteSession(sessionId, ctx = {}) {
+      return providerList[0].deleteSession(sessionId, ctx);
+    },
+
+    async listSources(ctx = {}) {
+      return providerList[0].listSources(ctx);
+    },
+
     validate() {
       return providerList.every((p) => typeof p.validate !== "function" || p.validate());
     },
@@ -1099,5 +1217,25 @@ export function createSyntaxVerifiedProvider(fastProvider, complexProvider, conf
     approvePlan(...args) {
       return fastProvider.approvePlan(...args);
     },
+
+    listSessions(...args) {
+      return typeof fastProvider.listSessions === "function" ? fastProvider.listSessions(...args) : { sessions: [] };
+    },
+
+    listActivities(...args) {
+      return typeof fastProvider.listActivities === "function" ? fastProvider.listActivities(...args) : { activities: [] };
+    },
+
+    archiveSession(...args) {
+      return typeof fastProvider.archiveSession === "function" ? fastProvider.archiveSession(...args) : { id: args[0], archived: true };
+    },
+
+    deleteSession(...args) {
+      return typeof fastProvider.deleteSession === "function" ? fastProvider.deleteSession(...args) : { id: args[0], deleted: true };
+    },
+
+    listSources(...args) {
+      return typeof fastProvider.listSources === "function" ? fastProvider.listSources(...args) : { sources: [] };
+    },
   };
 }

package/src/remediation.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHash } from "node:crypto";
 import { getStateDir, ensureDir } from "./state.mjs";
 import { redactSecrets } from "./security.mjs";
 
@@ -162,3 +162,156 @@ export function hydrateMemory(root, options = {}) {
   return `[LEARNED_REMEDIATIONS_CONTEXT]\nThe following historical failure-and-fix patterns were harvested from previous OODA runs in this repository. Avoid repeating these failure modes:\n\n${items.join("\n\n")}`;
 }
 
+/**
+ * Creates an OODA Thrash Cycle Breaker.
+ * Tracks rolling SHA-256 fingerprints of diff hunks and failure states in repair loops.
+ * Trips circuit breaker if an identical patch or failure ping-pong cycle is observed.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.maxHistory=10] - Maximum states to retain in ring buffer
+ * @param {number} [opts.threshold=2] - Number of occurrences before tripping (default: 2 -> A -> B -> A)
+ * @returns {{ recordAttempt: (state: { diff?: string, symptom?: string, targetFiles?: string[] }) => { thrash: boolean, cycleLength?: number, fingerprint: string, occurrences: number, reason?: string }, getHistory: () => string[], reset: () => void }}
+ */
+export function createThrashDetector(opts = {}) {
+  const maxHistory = opts.maxHistory || 10;
+  const threshold = opts.threshold || 2;
+  const history = [];
+
+  function computeStateFingerprint(state = {}) {
+    const normDiff = (state.diff || "").trim();
+    const normSymptom = (state.symptom || "").trim();
+    const normFiles = (state.targetFiles || []).slice().sort().join(",");
+    return createHash("sha256")
+      .update(`${normDiff}:::${normSymptom}:::${normFiles}`)
+      .digest("hex");
+  }
+
+  function recordAttempt(state = {}) {
+    const fingerprint = computeStateFingerprint(state);
+    history.push(fingerprint);
+    if (history.length > maxHistory) {
+      history.shift();
+    }
+
+    // Check for duplicate occurrences in history
+    const occurrences = history.filter((h) => h === fingerprint).length;
+    if (occurrences >= threshold) {
+      const firstIdx = history.indexOf(fingerprint);
+      const lastIdx = history.lastIndexOf(fingerprint);
+      const cycleLength = lastIdx - firstIdx;
+
+      return {
+        thrash: true,
+        cycleLength,
+        fingerprint,
+        occurrences,
+        reason: `OODA Thrash Circuit Tripped: State fingerprint ${fingerprint.slice(0, 12)} repeated ${occurrences} times across repair loop (cycle length: ${cycleLength}).`,
+      };
+    }
+
+    return {
+      thrash: false,
+      fingerprint,
+      occurrences,
+    };
+  }
+
+  return {
+    recordAttempt,
+    getHistory: () => [...history],
+    reset: () => {
+      history.length = 0;
+    },
+  };
+}
+
+/**
+ * Creates a Whack-a-Mole Test-Oscillation Detector for OODA repair loops.
+ * Detects when consecutive repair turns oscillate between different failing test sets
+ * (e.g. fixing Test A causes Test B to break, then fixing Test B re-breaks Test A).
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.maxHistory=8] - Maximum test state signatures to retain
+ * @param {number} [opts.threshold=2] - Number of repeating occurrences before triggering
+ * @returns {{ recordTestOutcome: (failingTests: string[] | string) => { whackAMole: boolean, cycleLength?: number, oscillatingTests?: string[], occurrences: number, promptDirective?: string, reason?: string }, getHistory: () => string[], reset: () => void }}
+ */
+export function createWhackAMoleDetector(opts = {}) {
+  const maxHistory = opts.maxHistory || 8;
+  const threshold = opts.threshold || 2;
+  const history = []; // Array of signature strings
+  const testSets = []; // Array of string[]
+
+  function normalizeTestSet(input) {
+    if (!input) return [];
+    if (Array.isArray(input)) {
+      return [...new Set(input.map((s) => String(s).trim()).filter(Boolean))].sort();
+    }
+    const str = String(input).trim();
+    return str ? [str] : [];
+  }
+
+  function recordTestOutcome(failingInput) {
+    const tests = normalizeTestSet(failingInput);
+    const signature = tests.join("||") || "__ALL_PASS__";
+
+    history.push(signature);
+    testSets.push(tests);
+
+    if (history.length > maxHistory) {
+      history.shift();
+      testSets.shift();
+    }
+
+    if (signature === "__ALL_PASS__") {
+      return {
+        whackAMole: false,
+        occurrences: 0,
+      };
+    }
+
+    const occurrences = history.filter((h) => h === signature).length;
+    if (occurrences >= threshold) {
+      const firstIdx = history.indexOf(signature);
+      const lastIdx = history.lastIndexOf(signature);
+      const cycleLength = lastIdx - firstIdx;
+
+      // Extract all distinct failing tests observed in the cycle window
+      const cycleTests = new Set();
+      for (let i = firstIdx; i <= lastIdx; i++) {
+        for (const t of testSets[i]) {
+          cycleTests.add(t);
+        }
+      }
+      const oscillatingTests = [...cycleTests];
+
+      const testSummary = oscillatingTests.length > 0 ? oscillatingTests.join(" <-> ") : "tests";
+      const promptDirective = `[WHACK_A_MOLE_WARNING] You are trapped in a local optimization cycle where fixing one test breaks another (${testSummary}). Do not add more conditional edge-case band-aids. Revert recent patches and refactor the core logic cleanly.`;
+
+      return {
+        whackAMole: true,
+        cycleLength,
+        oscillatingTests,
+        occurrences,
+        promptDirective,
+        reason: `Whack-a-Mole Test Oscillation Detected: Test failure signature repeated across repair turns (${testSummary}).`,
+      };
+    }
+
+    return {
+      whackAMole: false,
+      occurrences,
+    };
+  }
+
+  return {
+    recordTestOutcome,
+    getHistory: () => [...history],
+    reset: () => {
+      history.length = 0;
+      testSets.length = 0;
+    },
+  };
+}
+
+
+

package/src/rules-budget.mjs

@@ -45,8 +45,14 @@ export function checkRulesBudget(root = process.cwd(), opts = {}) {
 
     try {
       const content = readFileSync(fullPath, "utf-8");
-      const charCount = content.length;
-      const lineCount = content.split("\n").length;
+      // A CRLF checkout inflates the character count by one `\r` per line, so
+      // the identical rules file passes as LF and fails as CRLF — a false
+      // budget violation that depends purely on git's autocrlf setting rather
+      // than the content. Normalise line endings before measuring (P-12) so the
+      // budget counts the rule text, not the line-ending dialect.
+      const normalized = content.replace(/\r\n/g, "\n");
+      const charCount = normalized.length;
+      const lineCount = normalized.split("\n").length;
 
       if (charCount > maxChars) {
         violations.push({

package/src/scaffold.mjs

@@ -250,7 +250,7 @@ export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
   }
 
   if (copyDir(join(KIT_ROOT, ".agent/prompts"), join(agentDir, "prompts"), force) > 0) {
-    created.push(".agent/prompts/ (Overseer, Bolt, Sentinel, Janitor)");
+    created.push(".agent/prompts/ (Overseer, Bolt, Sentinel, Janitor, A11y, Scribe, Spectator, Alchemist)");
   }
   if (copyDir(join(KIT_ROOT, ".agent/rules"), join(agentDir, "rules"), force) > 0) {
     created.push(".agent/rules/");