jules-orchestrator-kit 0.32.4 → 0.32.6

package/src/router.mjs

@@ -0,0 +1,205 @@
+import { normalizePath } from "./config.mjs";
+import { matchesGlob } from "./security.mjs";
+import { extractPathTokens } from "./task-optimizer.mjs";
+import { createProvider, createFailoverProvider } from "./provider.mjs";
+
+/**
+ * Dynamic Complexity & Cost Router (Roadmap v0.33.0).
+ *
+ * Zero-dependency, rule-based heuristic classifier — no ML classifier, no
+ * external routing service. Routes trivial tasks (typos, lockfile bumps,
+ * lint fixes) to a cheap/fast provider while reserving the primary provider
+ * for complex, multi-file, or safety-sensitive work. Opt-in via
+ * `config.router.enabled` — disabled by default, zero behavior change for
+ * existing users.
+ */
+
+export const ROUTE_TIERS = {
+  FAST: "fast",
+  COMPLEX: "complex",
+};
+
+const TRIVIAL_SIGNALS = [
+  /\btypo(s)?\b/i,
+  /\brenam(e|ing|ed)\b/i,
+  /\bbump(ed|ing)?\b/i,
+  /\bversion bump\b/i,
+  /\block ?file\b/i,
+  /\bformat(ting)?\b/i,
+  /\blint(ing)?\s*(fix(es)?|error)?\b/i,
+  /\bwhitespace\b/i,
+  /\b(update|fix)\s+comment(s)?\b/i,
+  /\bdead code\b/i,
+  /\bunused (import|variable)s?\b/i,
+  /\breadme\b/i,
+  /\btypo fix\b/i,
+];
+
+const COMPLEX_SIGNALS = [
+  /\brefactor(ing)?\b/i,
+  /\barchitect(ure)?\b/i,
+  /\bmigrat(e|ion|ing)\b/i,
+  /\bredesign\b/i,
+  /\bconcurrency\b/i,
+  /\brace condition\b/i,
+  /\bsecurity\b/i,
+  /\bauth(entication|orization)?\b/i,
+  /\bschema\b/i,
+  /\bbreaking change\b/i,
+  /\bmulti-file\b/i,
+  /\bcross-package\b/i,
+  /\bdatabase\b/i,
+  /\bpayment(s)?\b/i,
+  /\bencrypt(ion)?\b/i,
+];
+
+// Sentinel handles security-sensitive work; the primary provider is always used.
+const FORCE_COMPLEX_ROLES = new Set(["sentinel"]);
+const FAST_LEANING_ROLES = new Set(["janitor", "bolt"]);
+const COMPLEX_LEANING_ROLES = new Set(["overseer", "sentinel"]);
+
+// Supplements config.scope.deny — these are never eligible for the fast tier
+// regardless of user scope config, mirroring src/risk.mjs's RESTRICTED_PATH_PATTERNS.
+const SENSITIVE_PATH_PATTERNS = [
+  "**/auth/**",
+  "**/migrations/**",
+  "**/pricing/**",
+  "**/secrets/**",
+  "**/*.pem",
+  "**/*.key",
+  ".github/**",
+  ".agent/config.yml",
+  ".agent/jules.yml",
+];
+
+function collectReferencedPaths(task) {
+  // extractPathTokens only recognises "/" as a separator, but a Windows author
+  // naturally writes "src\auth\session.mjs" in a prompt. Without this the
+  // sensitive-path guard below never sees the path and the task can be routed
+  // to the cheap tier. targetFiles are separately normalised by normalizePath.
+  const promptText = String(task.prompt || "").replace(/\\/g, "/");
+  const fromPrompt = extractPathTokens(promptText);
+  const explicit = Array.isArray(task.targetFiles)
+    ? task.targetFiles
+    : Array.isArray(task.referenced_paths)
+      ? task.referenced_paths
+      : [];
+  return [...new Set([...fromPrompt, ...explicit])];
+}
+
+function touchesSensitivePath(paths, config) {
+  const denyPatterns = [...SENSITIVE_PATH_PATTERNS, ...((config && config.scope && config.scope.deny) || [])];
+  for (const rawPath of paths) {
+    const p = normalizePath(rawPath);
+    for (const pattern of denyPatterns) {
+      if (matchesGlob(p, pattern)) return { path: p, pattern };
+    }
+  }
+  return null;
+}
+
+/**
+ * Heuristically classifies a task envelope into a FAST or COMPLEX routing tier.
+ * @param {object} task - Task envelope (title, prompt, role, targetFiles, tier).
+ * @param {object} config - Loaded orchestrator config (uses scope.deny, router.threshold).
+ * @returns {{tier: string, score: number|null, forced: boolean, reason: string, signals?: string[]}}
+ */
+export function classifyTaskComplexity(task = {}, config = {}) {
+  const explicitTier = task.tier || task.complexity;
+  if (explicitTier === ROUTE_TIERS.FAST || explicitTier === ROUTE_TIERS.COMPLEX) {
+    return { tier: explicitTier, score: null, forced: true, reason: `Explicit task tier override: '${explicitTier}'` };
+  }
+
+  const paths = collectReferencedPaths(task);
+  const sensitiveHit = touchesSensitivePath(paths, config);
+  if (sensitiveHit) {
+    return {
+      tier: ROUTE_TIERS.COMPLEX,
+      score: null,
+      forced: true,
+      reason: `Touches sensitive path '${sensitiveHit.path}' (matches '${sensitiveHit.pattern}')`,
+    };
+  }
+
+  const role = String(task.role || "").toLowerCase();
+  if (FORCE_COMPLEX_ROLES.has(role)) {
+    return { tier: ROUTE_TIERS.COMPLEX, score: null, forced: true, reason: `Role '${role}' always routes to the primary provider` };
+  }
+
+  const text = `${task.title || ""} ${task.prompt || ""}`;
+  let score = 0;
+  const signals = [];
+
+  for (const pattern of COMPLEX_SIGNALS) {
+    if (pattern.test(text)) {
+      score += 2;
+      signals.push(`+2 complex keyword (${pattern.source})`);
+    }
+  }
+  for (const pattern of TRIVIAL_SIGNALS) {
+    if (pattern.test(text)) {
+      score -= 1;
+      signals.push(`-1 trivial keyword (${pattern.source})`);
+    }
+  }
+
+  if (paths.length >= 4) {
+    score += 3;
+    signals.push(`+3 touches ${paths.length} files`);
+  } else if (paths.length > 0 && paths.length <= 1) {
+    score -= 1;
+    signals.push(`-1 touches a single file`);
+  }
+
+  const promptLen = (task.prompt || "").length;
+  if (promptLen > 1200) {
+    score += 1;
+    signals.push(`+1 long prompt (${promptLen} chars)`);
+  } else if (promptLen > 0 && promptLen < 200) {
+    score -= 1;
+    signals.push(`-1 short prompt (${promptLen} chars)`);
+  }
+
+  if (COMPLEX_LEANING_ROLES.has(role)) {
+    score += 1;
+    signals.push(`+1 role '${role}' leans complex`);
+  }
+  if (FAST_LEANING_ROLES.has(role)) {
+    score -= 2;
+    signals.push(`-2 role '${role}' leans fast`);
+  }
+
+  const threshold = Number.isFinite(config?.router?.threshold) ? config.router.threshold : 0;
+  const tier = score > threshold ? ROUTE_TIERS.COMPLEX : ROUTE_TIERS.FAST;
+
+  return { tier, score, forced: false, threshold, signals, reason: `Heuristic score ${score} vs threshold ${threshold}` };
+}
+
+/**
+ * Resolves the provider adapter to dispatch a task through, honoring
+ * `config.router` (opt-in Dynamic Complexity & Cost Router). Disabled by
+ * default — returns the primary provider unchanged. FAST-tier tasks are
+ * wrapped in a failover cascade so a rate-limited/unavailable fast provider
+ * falls through to the primary provider automatically.
+ * @param {object} task
+ * @param {object} config
+ * @returns {{provider: object, routed: boolean, classification: object|null}}
+ */
+export function resolveRoutedProvider(task = {}, config = {}) {
+  const routerCfg = config.router || {};
+  const complexSpec = routerCfg.complex || config.provider || "jules";
+
+  if (!routerCfg.enabled) {
+    return { provider: createProvider(config.provider, config), routed: false, classification: null };
+  }
+
+  const classification = classifyTaskComplexity(task, config);
+
+  if (classification.tier === ROUTE_TIERS.COMPLEX) {
+    return { provider: createProvider(complexSpec, config), routed: true, classification };
+  }
+
+  const fastSpec = routerCfg.fast || "gemini-flash";
+  const provider = createFailoverProvider([fastSpec, complexSpec], config);
+  return { provider, routed: true, classification };
+}

package/src/security.mjs

@@ -1,7 +1,7 @@
 import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync, unlinkSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { randomBytes } from "node:crypto";
-import { normalizePath } from "./config.mjs";
+import { canonicalizePath } from "./config.mjs";
 import { detectCrossPackageBoundaryViolations } from "./stack-detector.mjs";
 
 export const HIGH_CONFIDENCE_PATTERNS = [
@@ -165,12 +165,28 @@ export function anonymizePii(text) {
   return sanitized;
 }
 
-export function matchesGlob(filePath, globPattern) {
+/**
+ * Glob matcher.
+ *
+ * `caseInsensitive` exists because the same repository is checked out on
+ * Linux, macOS and Windows. On APFS and NTFS, `.GitHub/` and `.github/` are
+ * the *same directory*, but git records whichever case was committed — so a
+ * case-sensitive deny rule can be walked straight past on two of the three
+ * target platforms. Deny and protect matching therefore folds case; allow
+ * matching deliberately does not, so that a case mismatch fails closed
+ * (unmatched by allow = violation) rather than opening a hole.
+ *
+ * @param {string} filePath
+ * @param {string} globPattern
+ * @param {{ caseInsensitive?: boolean }} [opts]
+ */
+export function matchesGlob(filePath, globPattern, opts = {}) {
   if (!filePath || !globPattern) return false;
-  const file = normalizePath(filePath);
-  const pattern = normalizePath(globPattern);
+  const file = canonicalizePath(filePath);
+  const pattern = canonicalizePath(globPattern);
+  const flags = opts.caseInsensitive ? "i" : "";
 
-  if (file === pattern) return true;
+  if (opts.caseInsensitive ? file.toLowerCase() === pattern.toLowerCase() : file === pattern) return true;
 
   const parts = pattern.split("/");
   const regexParts = parts.map((part) => {
@@ -188,16 +204,16 @@ export function matchesGlob(filePath, globPattern) {
     .replace(/___GLOBSTAR___/g, ".*");
 
   try {
-    return new RegExp(`^${regexStr}$`).test(file);
+    return new RegExp(`^${regexStr}$`, flags).test(file);
   } catch (_) {
     return false;
   }
 }
 
 export function isForbiddenPath(filePath, config = {}) {
-  const normFile = normalizePath(filePath);
+  const normFile = canonicalizePath(filePath);
   const forbidden = config.scope?.deny || config.forbidden_paths || [];
-  return forbidden.some((pattern) => matchesGlob(normFile, pattern));
+  return forbidden.some((pattern) => matchesGlob(normFile, pattern, { caseInsensitive: true }));
 }
 
 export function checkScope(files = [], scope = {}, opts = {}) {
@@ -207,14 +223,27 @@ export function checkScope(files = [], scope = {}, opts = {}) {
   const protect = scope.protect || [];
 
   for (const rawFile of files) {
-    const file = normalizePath(rawFile);
+    // Canonicalised so that "./x", "a/../x" and "a//x" cannot present the same
+    // file under a spelling the deny patterns do not literally match.
+    const file = canonicalizePath(rawFile);
+
+    // A path that climbs out of the repository root can never be legitimate and
+    // must not be silently pattern-matched against repo-relative rules.
+    if (file === ".." || file.startsWith("../") || file.startsWith("/")) {
+      violations.push({ file, reason: "Path escapes the repository root", rule: "deny", pattern: "<traversal>" });
+      continue;
+    }
 
-    const matchedDeny = deny.find((pat) => matchesGlob(file, pat));
+    // Deny folds case: on macOS/Windows ".GitHub/" resolves to the same
+    // directory as ".github/", so a case-sensitive deny is bypassable there.
+    const matchedDeny = deny.find((pat) => matchesGlob(file, pat, { caseInsensitive: true }));
     if (matchedDeny) {
       violations.push({ file, reason: `Forbidden path restriction matched pattern "${matchedDeny}"`, rule: "deny", pattern: matchedDeny });
       continue;
     }
 
+    // Allow stays case-sensitive on purpose: a case mismatch here yields "not
+    // allowed" (a violation), which is the fail-closed direction.
     if (allow.length > 0) {
       const isExplicitlyAllowed = allow.some((pat) => matchesGlob(file, pat));
       if (!isExplicitlyAllowed) {
@@ -224,7 +253,7 @@ export function checkScope(files = [], scope = {}, opts = {}) {
     }
 
     if (!opts.allowProtected) {
-      const matchedProtect = protect.find((pat) => matchesGlob(file, pat));
+      const matchedProtect = protect.find((pat) => matchesGlob(file, pat, { caseInsensitive: true }));
       if (matchedProtect) {
         violations.push({ file, reason: `Protected file modification restriction matched pattern "${matchedProtect}"`, rule: "protect", pattern: matchedProtect });
       }
@@ -332,6 +361,29 @@ export function checkCrossPackageImports(diffOrText = "", root = process.cwd(),
   };
 }
 
+// Zero-width and bidi-control characters. Inserting one mid-token defeats a
+// regex without changing how the value renders, copies, or authenticates.
+const INVISIBLE_CHARS = /[\u00AD\u200B-\u200F\u2028\u2029\u202A-\u202E\u2060-\u2064\uFEFF]/g;
+
+// A credential split across a source-level string concatenation is invisible to
+// a line-oriented scanner. This is not only an evasion technique — formatters
+// wrap long string literals exactly this way, so it also happens by accident.
+const STRING_CONCAT_JOIN = /(["'`])\s*\+\s*(["'`])/g;
+
+/**
+ * Produces the variants of the added-line text that secret patterns are run
+ * against: as-written, with invisible characters stripped, and with
+ * source-level string concatenation collapsed.
+ * @param {string} addedLines
+ * @returns {string[]}
+ */
+function secretScanVariants(addedLines) {
+  const stripped = addedLines.replace(INVISIBLE_CHARS, "");
+  // Collapse `"AAA" +\n  "BBB"` into `"AAABBB"` before matching.
+  const dejoined = stripped.replace(/\s*\n\s*/g, " ").replace(STRING_CONCAT_JOIN, "");
+  return [...new Set([addedLines, stripped, dejoined])];
+}
+
 export function scanDiff(diffTextStr = "", options = {}) {
   if (!diffTextStr) return { ok: true, findings: [] };
   const addedLines = diffTextStr
@@ -340,8 +392,9 @@ export function scanDiff(diffTextStr = "", options = {}) {
     .map((line) => line.slice(1))
     .join("\n");
 
-  const hasHigh = hasHighConfidenceSecret(addedLines);
-  const hasLow = !hasHigh && hasLowConfidenceSecret(addedLines);
+  const variants = secretScanVariants(addedLines);
+  const hasHigh = variants.some((v) => hasHighConfidenceSecret(v));
+  const hasLow = !hasHigh && variants.some((v) => hasLowConfidenceSecret(v));
   const findings = [];
 
   if (hasHigh) {

package/src/stack-detector.mjs

@@ -155,6 +155,31 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     return { ...container, stack: "make", testCmd: "make test", buildCmd: "make build", triggerFile: "Makefile" };
   }
 
+  // 4b. Web3 / Solidity / Foundry & Hardhat
+  if (existsSync(join(projectRoot, "foundry.toml")) || existsSync(join(projectRoot, "remappings.txt"))) {
+    const triggerFile = existsSync(join(projectRoot, "foundry.toml")) ? "foundry.toml" : "remappings.txt";
+    return {
+      ...container,
+      stack: "foundry",
+      testCmd: "forge test --offline",
+      buildCmd: "forge build --offline",
+      fmtCmd: "forge fmt --check",
+      fuzzCmd: "forge test --offline --match-test testFuzz",
+      invariantCmd: "forge test --offline --match-test invariant",
+      triggerFile,
+    };
+  }
+  if (existsSync(join(projectRoot, "hardhat.config.js")) || existsSync(join(projectRoot, "hardhat.config.ts"))) {
+    const triggerFile = existsSync(join(projectRoot, "hardhat.config.ts")) ? "hardhat.config.ts" : "hardhat.config.js";
+    return {
+      ...container,
+      stack: "hardhat",
+      testCmd: "npx hardhat test",
+      buildCmd: "npx hardhat compile",
+      triggerFile,
+    };
+  }
+
   // 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" };
@@ -247,6 +272,9 @@ export function findSubprojectRoot(fileRelPath = "", root = process.cwd()) {
 
   const manifestFiles = [
     "package.json",
+    "foundry.toml",
+    "hardhat.config.js",
+    "hardhat.config.ts",
     "Cargo.toml",
     "go.mod",
     "pyproject.toml",

package/src/wizard-task.mjs

@@ -1,5 +1,5 @@
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { writeFileSync, readFileSync, readdirSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
 import { loadConfig } from "./config.mjs";
 import { gate } from "./engine.mjs";
 import { scanDiff, shannonEntropy } from "./security.mjs";
@@ -21,9 +21,38 @@ HARD CONSTRAINTS:
 
 const TRIVIAL_ORACLES = new Set(["true", "echo", ":", "false", "exit 0", "exit 1", "echo ok"]);
 
+/**
+ * Resolves specialist agent role markdown prompt from .agent/prompts/
+ * @param {string} [root=process.cwd()]
+ * @param {string} [roleName=""]
+ * @returns {{ role: string, path: string, content: string } | null}
+ */
+export function resolveRolePrompt(root = process.cwd(), roleName = "") {
+  if (!roleName || typeof roleName !== "string") return null;
+  const cleanName = roleName.trim().toLowerCase();
+  const promptsDir = join(root, ".agent", "prompts");
+  if (!existsSync(promptsDir)) return null;
+
+  try {
+    const files = readdirSync(promptsDir);
+    const matched = files.find(
+      (f) => f.toLowerCase() === `${cleanName}.md` || f.toLowerCase() === cleanName
+    );
+    if (matched) {
+      const fullPath = join(promptsDir, matched);
+      return {
+        role: matched.replace(/\.md$/i, ""),
+        path: fullPath,
+        content: readFileSync(fullPath, "utf-8").trim(),
+      };
+    }
+  } catch (_) {}
+  return null;
+}
+
 /**
  * Pure planning core for task creation & envelope synthesis.
- * Supports web task templates, exploration budgets, and critic agent steering.
+ * Supports web task templates, specialist roles, exploration budgets, and critic agent steering.
  * @param {string} root
  * @param {object} inputObj
  * @returns {{
@@ -33,6 +62,8 @@ const TRIVIAL_ORACLES = new Set(["true", "echo", ":", "false", "exit 0", "exit 1
  *   prompt: string,
  *   fullPrompt: string,
  *   verifyCmd: string,
+ *   role?: string,
+ *   dependsOn?: string[],
  *   flags: { autoPr: boolean, requirePlanApproval: boolean, repoless: boolean, startingBranch: string },
  *   secretFindings: Array<any>,
  *   taskFileContent: string
@@ -45,7 +76,22 @@ export function planTaskCreate(root = process.cwd(), inputObj = {}) {
   let rawPrompt = inputObj.prompt || "";
   let verifyCmd = (inputObj.verifyCmd || config.verify.test || config.verify.build || "").trim();
 
-  // 0. Process Template if specified
+  // 0a. Process Specialist Role if specified
+  let resolvedRole = null;
+  if (inputObj.role) {
+    resolvedRole = resolveRolePrompt(root, inputObj.role);
+    if (!resolvedRole) {
+      throw new Error(
+        `Unknown agent role '${inputObj.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Overseer, Bolt, Sentinel, Janitor).`
+      );
+    }
+    rawPrompt = `${resolvedRole.content}\n\n${rawPrompt}`.trim();
+    if (!title || title === "Agent Task") {
+      title = `${resolvedRole.role}: ${inputObj.title || "Specialist Task"}`;
+    }
+  }
+
+  // 0b. Process Template if specified
   if (inputObj.template) {
     const tpl = getWebTemplate(inputObj.template);
     if (!tpl) {
@@ -57,7 +103,7 @@ export function planTaskCreate(root = process.cwd(), inputObj = {}) {
       criticGuidance: inputObj.criticGuidance
     });
     rawPrompt = rawPrompt ? `${rawPrompt}\n\n${synthesized.prompt}` : synthesized.fullEnvelope;
-    if (!title) title = synthesized.title;
+    if (!title || title === "Agent Task") title = synthesized.title;
     if (!verifyCmd) verifyCmd = synthesized.verifyCmd;
   }
 
@@ -123,12 +169,24 @@ ${GUARDRAIL_FOOTER}`;
 
   const promptAnalysis = scorePromptFalsifiability(rawPrompt, { rootDir: root, verifyCmd });
 
+  const rawDepends = inputObj.dependsOn || inputObj.depends;
+  const dependsOn = Array.isArray(rawDepends)
+    ? rawDepends
+    : typeof rawDepends === "string"
+    ? rawDepends.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+
+  const tier = inputObj.tier === "fast" || inputObj.tier === "complex" ? inputObj.tier : undefined;
+
   const envelopeMetadata = {
     version: 1,
     id: taskId,
     title,
     flags,
     verifyCmd,
+    role: resolvedRole ? resolvedRole.role : (inputObj.role || undefined),
+    dependsOn,
+    tier,
     falsifiabilityScore: promptAnalysis.score,
     grade: promptAnalysis.grade,
   };
@@ -148,6 +206,9 @@ ${fullPrompt}
     prompt: rawPrompt,
     fullPrompt,
     verifyCmd,
+    role: envelopeMetadata.role,
+    dependsOn,
+    tier,
     flags,
     secretFindings,
     promptAnalysis,