jules-orchestrator-kit 0.32.4 → 0.32.5

package/src/router.mjs

@@ -0,0 +1,200 @@
+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) {
+  const fromPrompt = extractPathTokens(task.prompt || "");
+  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/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,