jules-orchestrator-kit 0.26.1 → 0.27.0

package/README.md

@@ -19,11 +19,11 @@
 <p align="center">
   <a href="#-2-sentence-mental-model">💡 What is Kit?</a> •
   <a href="#-universal-30-second-quickstart-zero-to-verified-pr">⚡ 30s Quickstart</a> •
+  <a href="#-triage-guidelines-when-to-use-vs-when-not-to-use">🎯 Triage Guidelines</a> •
   <a href="#-feature-comparison-matrix">📊 Comparison Matrix</a> •
   <a href="#-system-architecture--visual-diagrams">🏛️ Architecture</a> •
   <a href="#-cli-command-reference-agentctl">🛠️ CLI Reference</a> •
-  <a href="#-v027-next-gen-feature-roadmap">🗺️ Roadmap</a> •
-  <a href="./docs/UNIVERSAL_POLYGLOT_ARCHITECTURE.md">📖 Polyglot Spec</a>
+  <a href="#-v027-next-gen-feature-roadmap">🗺️ Roadmap</a>
 </p>
 
 </div>
@@ -52,6 +52,25 @@ Autonomous coding agents can write software at 100× human speed—but unconstra
 
 ---
 
+## 🎯 Triage Guidelines: When to Use vs. When NOT to Use
+
+To ensure maximum merge success, dispatch tasks according to our deterministic triage boundaries:
+
+### 🟢 Ideal Tasks for Autonomous Swarms
+- ✅ **Scoped Code Changes & Bug Fixes:** Well-defined objectives mechanically verifiable via unit tests (`npm test`, `pytest`, `cargo test`, `dotnet test`).
+- ✅ **Type & Linter Migrations:** TypeScript strict mode fixes, PHP 8.3 type hint additions, or Python MyPy type annotation passes.
+- ✅ **Dependency Bumps & Security Audits:** Remediating CVEs in lockfiles (`package.json`, `Cargo.toml`, `composer.json`) with hermetic test verification.
+- ✅ **Refactoring Legacy Codebases:** Modularizing backend routes, API controllers, or database query layers.
+- ✅ **Visual & E2E Testing (via Playwright):** UI changes paired with automated headless Playwright snapshot tests (`npx playwright test`).
+
+### 🔴 When NOT to Use (Out of Scope)
+- ❌ **Unverifiable Visual UI Tweaks:** Pixel-perfect CSS/Tailwind adjustments lacking automated visual regression tests (agents cannot "see" raw browser output without Playwright).
+- ❌ **Closed Proprietary Platforms Without CLI:** Systems lacking local CLI tools or git repositories (e.g., Salesforce, Webflow, closed SAP backends).
+- ❌ **Unmocked Live Cloud Systems:** Code requiring live connections to 10+ external cloud APIs without local emulators or mocks.
+- ❌ **Protected Infrastructure Paths:** Direct edits to `.github/workflows/`, production deployment keys, or agent security gate rules (enforced fail-closed by `Agent Scope Guard`).
+
+---
+
 ## 📊 Feature Comparison Matrix
 
 | Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.26+) |
@@ -100,7 +119,14 @@ npx jules-orchestrator-kit dispatch --title "Implement OrderService caching" \
   --prompt "Add IMemoryCache caching to OrderService.cs with xUnit coverage."
 ```
 
-### 5️⃣ Polyglot Monorepo (FastAPI + React + Rust CLI)
+### 5️⃣ UI / Frontend E2E (Playwright)
+```bash
+# Dispatch frontend task verified via headless Playwright E2E tests
+npx jules-orchestrator-kit dispatch --title "Add Dark Mode Toggle Component" \
+  --prompt "Create ThemeToggle component in src/components/ThemeToggle.tsx and verify via npx playwright test."
+```
+
+### 6️⃣ Polyglot Monorepo (FastAPI + React + Rust CLI)
 ```bash
 # Run a parallel worktree swarm; changed files automatically route to scoped subproject tests
 npx jules-orchestrator-kit swarm
@@ -189,7 +215,7 @@ In monorepos containing multiple languages, `resolveWorkspaceBoundary(changedFil
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
 | `init` | `agentctl init` | Scaffolds `.agent/` directory structure and default `.agent/config.yml`. | `0` (Created) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
-| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.26.0`). | `0` |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.26.1`). | `0` |
 
 ---
 

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.26.1 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.27.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -28,6 +28,8 @@ Commands:
   lock <action>         Manage mutex locks (acquire | release | status | cleanup)
   doctor                Run system diagnostics and stack resolution checks
   bootstrap             Bootstrap zero-test repository with verification oracle
+  review-repair         Parse PR review comments and synthesize OODA repair tasks
+  dashboard             Start local HTTP telemetry and audit dashboard
   init                  Scaffold .agent/ directory and config.yml
   version               Output agentctl version
 
@@ -45,7 +47,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.26.1");
+    console.log("agentctl v0.27.0");
     process.exit(0);
   }
 
@@ -263,6 +265,31 @@ async function main() {
       break;
     }
 
+    case "review-repair": {
+      const fileArg = args[1];
+      if (!fileArg || !existsSync(fileArg)) {
+        console.error("Error: Please provide a valid JSON file containing PR review comments.");
+        process.exit(1);
+      }
+      const { parseReviewComments, createReviewRepairTask } = await import("../src/review-repair.mjs");
+      const raw = readFileSync(fileArg, "utf-8");
+      const comments = parseReviewComments(raw);
+      console.log(`✅ Parsed ${comments.length} actionable review comment(s).`);
+      for (const c of comments) {
+        const task = createReviewRepairTask(c);
+        console.log(`   Task: ${task.title} (Author: @${c.author}, Line: ${c.line || "N/A"})`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    case "dashboard": {
+      const port = Number(args[1] || 4100);
+      const { startDashboardServer } = await import("../src/dashboard.mjs");
+      startDashboardServer(port, root);
+      break;
+    }
+
     case "init": {
       const agentDir = join(root, ".agent");
       ensureDir(agentDir);

package/package.json

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

package/src/dashboard.mjs

@@ -0,0 +1,136 @@
+/**
+ * Zero-Dependency Local Telemetry & Audit HTTP Dashboard for jules-orchestrator-kit (v0.27.0).
+ * Uses node:http to serve real-time HTML/CSS dark mode visualizer and REST JSON endpoints.
+ */
+
+import http from "node:http";
+import { readTelemetry, verifyTelemetryIntegrity } from "./telemetry.mjs";
+import { readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
+import { lockStatus } from "./state.mjs";
+
+export function getDashboardHtml(root = process.cwd()) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>jules-orchestrator-kit Dashboard</title>
+  <style>
+    body { background-color: #0d1117; color: #c9d1d9; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 0; padding: 24px; }
+    h1 { color: #58a6ff; font-size: 24px; margin-bottom: 8px; }
+    .subtitle { color: #8b949e; font-size: 14px; margin-bottom: 24px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; margin-bottom: 24px; }
+    .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+    .card h2 { font-size: 16px; color: #f0f6fc; margin-top: 0; border-bottom: 1px solid #21262d; padding-bottom: 8px; }
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th, td { text-align: left; padding: 8px; border-bottom: 1px solid #21262d; }
+    th { color: #8b949e; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 12px; font-weight: 600; }
+    .badge-success { background: rgba(46, 160, 67, 0.15); color: #3fb950; border: 1px solid rgba(46, 160, 67, 0.4); }
+    .badge-warn { background: rgba(210, 153, 34, 0.15); color: #d29922; border: 1px solid rgba(210, 153, 34, 0.4); }
+    code { font-family: monospace; background: #21262d; padding: 2px 4px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.27.0)</h1>
+  <div class="subtitle">Repository: <code>${root}</code></div>
+
+  <div class="grid">
+    <div class="card">
+      <h2>🛡️ SHA-256 Telemetry Integrity</h2>
+      <div id="telemetry-status">Loading...</div>
+    </div>
+    <div class="card">
+      <h2>⚖️ Wilson-Score Flaky Ledger</h2>
+      <div id="flaky-status">Loading...</div>
+    </div>
+    <div class="card">
+      <h2>🔒 Active VFS Mutex Locks</h2>
+      <div id="locks-status">Loading...</div>
+    </div>
+  </div>
+
+  <script>
+    async function updateDashboard() {
+      try {
+        const [telRes, flakyRes, locksRes] = await Promise.all([
+          fetch('/api/telemetry?limit=10').then(r => r.json()),
+          fetch('/api/flaky').then(r => r.json()),
+          fetch('/api/locks').then(r => r.json())
+        ]);
+
+        document.getElementById('telemetry-status').innerHTML = telRes.integrity?.valid
+          ? '<span class="badge badge-success">✓ SHA-256 Hash Chain Valid</span> <p>Events logged: ' + telRes.events.length + '</p>'
+          : '<span class="badge badge-warn">⚠ Check Telemetry Logs</span>';
+
+        document.getElementById('flaky-status').innerHTML = '<p>Verdict: <code>' + (flakyRes.verdict?.action || 'CLEAN') + '</code></p><p>Tracked test runs: ' + flakyRes.count + '</p>';
+        document.getElementById('locks-status').innerHTML = '<p>Active VFS Locks: <code>' + locksRes.count + '</code></p>';
+      } catch (err) {
+        console.error("Dashboard update failed:", err);
+      }
+    }
+    updateDashboard();
+    setInterval(updateDashboard, 5000);
+  </script>
+</body>
+</html>`;
+}
+
+export function createDashboardServer({ root = process.cwd(), port: _port = 4100 } = {}) {
+  return http.createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      return res.end();
+    }
+
+    if (url.pathname === "/" || url.pathname === "/index.html") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      return res.end(getDashboardHtml(root));
+    }
+
+    if (url.pathname === "/api/status") {
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, version: "0.27.0", root, ts: new Date().toISOString() }));
+    }
+
+    if (url.pathname === "/api/telemetry") {
+      const limit = Number(url.searchParams.get("limit") || "50");
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(
+        JSON.stringify({
+          ok: true,
+          count: limit,
+          integrity: verifyTelemetryIntegrity(root),
+          events: readTelemetry(root, limit),
+        })
+      );
+    }
+
+    if (url.pathname === "/api/flaky") {
+      const runs = readVerifyRuns(root);
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, count: runs.length, verdict: flakyVerdict(runs), runs }));
+    }
+
+    if (url.pathname === "/api/locks") {
+      const locks = lockStatus(root);
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, count: locks.length, locks }));
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: "Not Found", path: url.pathname }));
+  });
+}
+
+export function startDashboardServer(port = 4100, root = process.cwd()) {
+  const server = createDashboardServer({ root, port });
+  server.listen(port, "0.0.0.0", () => {
+    console.log(`🚀 jules-orchestrator-kit Dashboard running at http://localhost:${port}`);
+  });
+  return server;
+}

package/src/provider.mjs

@@ -218,7 +218,6 @@ export function createProvider(spec = "jules", config = {}) {
         const rawArgs = providerSpec.args || (providerSpec.command ? providerSpec.command.split(" ").slice(1) : []);
         const command = providerSpec.command ? providerSpec.command.split(" ")[0] : "claude";
 
-        // CRITICAL H-a FIX: Filter out '{prompt}' argument if prompt is passed via stdin
         const filteredArgs = providerSpec.promptViaStdin
           ? rawArgs.filter((arg) => !arg.includes("{prompt}"))
           : rawArgs;
@@ -228,7 +227,7 @@ export function createProvider(spec = "jules", config = {}) {
         const res = spawnSync(command, processedArgs, {
           cwd: config._root || process.cwd(),
           encoding: "utf-8",
-          shell: false, // CRITICAL: Ban shell execution to eliminate CWE-77
+          shell: false,
           input: providerSpec.promptViaStdin ? data.prompt : undefined,
           timeout: providerSpec.timeoutMs || 900000,
           maxBuffer: 32 * 1024 * 1024,
@@ -259,3 +258,44 @@ export function createProvider(spec = "jules", config = {}) {
     },
   };
 }
+
+/**
+ * Creates a failover provider router that attempts dispatches sequentially across an ordered array of providers.
+ * Intercepts rate limits (429) and 5xx unavailability, logging telemetry events before falling over.
+ */
+export function createFailoverProvider(providers = ["jules"], config = {}) {
+  const providerList = (Array.isArray(providers) && providers.length > 0 ? providers : ["jules"]).map((spec) =>
+    spec && typeof spec === "object" && typeof spec.dispatch === "function" ? spec : createProvider(spec, config)
+  );
+
+  return {
+    name: `failover:${providerList.map((p) => p.name).join("->")}`,
+
+    async dispatch(task, ctx = {}) {
+      const errors = [];
+      for (let i = 0; i < providerList.length; i++) {
+        const provider = providerList[i];
+        try {
+          const res = await provider.dispatch(task, ctx);
+          return { ...res, _routedProvider: provider.name, _failoverAttempts: i };
+        } catch (err) {
+          errors.push({ provider: provider.name, error: err });
+          const isRecoverable =
+            err instanceof ProviderRateLimitError ||
+            err instanceof ProviderUnavailableError ||
+            (err.status && err.status >= 500 && err.status < 600) ||
+            err.status === 429;
+
+          if (i === providerList.length - 1 || !isRecoverable) {
+            err._failoverErrors = errors;
+            throw err;
+          }
+        }
+      }
+    },
+
+    validate() {
+      return providerList.every((p) => p.validate());
+    },
+  };
+}

package/src/review-repair.mjs

@@ -0,0 +1,53 @@
+/**
+ * PR Review Auto-Remediation Engine for jules-orchestrator-kit (v0.27.0).
+ * Parses GitHub PR review comments, filters conversational praise/noise,
+ * and synthesizes actionable OODA repair task envelopes.
+ */
+
+export function parseReviewComments(input) {
+  let comments = typeof input === "string" ? (() => { try { return JSON.parse(input); } catch { return []; } })() : input;
+  comments = Array.isArray(comments) ? comments : comments?.comments || comments?.reviews || [comments];
+
+  const actionable = [];
+  let idx = 0;
+  for (const c of comments) {
+    if (!c || typeof c !== "object") continue;
+
+    const state = String(c.state || c.status || "").toUpperCase();
+    if (state === "APPROVED" || state === "DISMISSED" || c.isResolved === true || c.resolved === true) continue;
+
+    const body = String(c.body || c.comment || "").trim();
+    if (body.length < 5) continue;
+
+    const praiseRegex = /^(?:lgtm|looks good(?: to me)?|nice|awesome|thanks|thank you|great work|approved|ship it)[\s.!]*$/i;
+    if (praiseRegex.test(body)) continue;
+
+    idx++;
+    const path = c.path || c.file || null;
+    const line = c.line || c.original_line || null;
+    const author = c.user?.login || c.author || "reviewer";
+
+    actionable.push({
+      id: String(c.id || `review-${idx}`),
+      path,
+      line: line ? Number(line) : null,
+      author,
+      body,
+      actionable: true,
+      prompt: `Fix PR review comment by @${author} on ${path || "code"}${line ? ` line ${line}` : ""}:\n\n"${body}"\n\nEnsure all unit tests and safety gates pass cleanly after applying fix.`,
+    });
+  }
+
+  return actionable;
+}
+
+export function createReviewRepairTask(comment, baseBranch = "main") {
+  return {
+    id: `repair-${comment.id}`,
+    title: `PR Review Repair: ${comment.path || "code"} (${comment.id})`,
+    prompt: comment.prompt || `Fix review feedback: ${comment.body}`,
+    baseBranch,
+    targetFiles: comment.path ? [comment.path] : [],
+    metadata: { source: "pr-review", commentId: comment.id, author: comment.author, line: comment.line },
+  };
+}