jules-orchestrator-kit 0.22.2 → 0.22.4

package/bin/agentctl.mjs

@@ -13,7 +13,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.22.2 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.22.4 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -43,7 +43,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.22.1");
+    console.log("agentctl v0.22.4");
     process.exit(0);
   }
 
@@ -223,7 +223,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.22.1)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.22.4)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/index.mjs

@@ -48,6 +48,7 @@ export {
 export { checkAssetIntegrity } from "./src/asset_integrity.mjs";
 export { classifyRiskTier, RISK_TIERS } from "./src/risk.mjs";
 export { checkRulesBudget } from "./src/rules_budget.mjs";
+export { DagExecutor, DagCycleError } from "./src/dag-engine.mjs";
 
 // Legacy SDK shims for backward compatibility
 export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";

package/package.json

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

package/src/dag-engine.mjs

@@ -0,0 +1,274 @@
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
+
+/**
+ * Custom error thrown when a circular dependency is detected in the DAG.
+ */
+export class DagCycleError extends Error {
+  constructor(cyclePath) {
+    const pathStr = Array.isArray(cyclePath) ? cyclePath.join(" -> ") : String(cyclePath);
+    super(`Circular dependency detected: ${pathStr}`);
+    this.name = "DagCycleError";
+    this.cyclePath = cyclePath;
+  }
+}
+
+/**
+ * Zero-Dependency Task DAG Executor with cycle detection and interface fingerprinting.
+ */
+export class DagExecutor {
+  constructor({ concurrency = 4 } = {}) {
+    this.concurrency = concurrency;
+    this.tasks = new Map();
+  }
+
+  /**
+   * Registers a task into the DAG.
+   * @param {Object} task
+   * @param {string} task.id
+   * @param {string[]} [task.dependsOn=[]]
+   * @param {string[]} [task.outputs=[]]
+   * @param {Function} [task.runner]
+   */
+  addTask({ id, dependsOn = [], outputs = [], runner }) {
+    if (!id || typeof id !== "string") {
+      throw new Error("Task id must be a non-empty string");
+    }
+    if (this.tasks.has(id)) {
+      throw new Error(`Task with id '${id}' already exists`);
+    }
+    this.tasks.set(id, {
+      id,
+      dependsOn: Array.isArray(dependsOn) ? [...dependsOn] : [],
+      outputs: Array.isArray(outputs) ? [...outputs] : [],
+      runner: runner || (async () => {}),
+    });
+  }
+
+  /**
+   * Validates the DAG, resolves dependencies using Kahn's algorithm, and checks for cycles.
+   * Throws DagCycleError if a cycle is detected.
+   */
+  validateDag() {
+    const totalNodes = this.tasks.size;
+    if (totalNodes === 0) return { executionOrder: [], dependents: new Map() };
+
+    const inDegree = new Map();
+    const dependents = new Map();
+
+    for (const id of this.tasks.keys()) {
+      inDegree.set(id, 0);
+      dependents.set(id, []);
+    }
+
+    for (const [id, task] of this.tasks.entries()) {
+      for (const depId of task.dependsOn) {
+        if (!this.tasks.has(depId)) {
+          throw new Error(`Task '${id}' depends on missing task '${depId}'`);
+        }
+        inDegree.set(id, inDegree.get(id) + 1);
+        dependents.get(depId).push(id);
+      }
+    }
+
+    const queue = [];
+    for (const [id, deg] of inDegree.entries()) {
+      if (deg === 0) {
+        queue.push(id);
+      }
+    }
+    queue.sort();
+
+    const executionOrder = [];
+    let processedNodes = 0;
+    const currentInDegree = new Map(inDegree);
+
+    while (queue.length > 0) {
+      queue.sort();
+      const node = queue.shift();
+      executionOrder.push(node);
+      processedNodes++;
+
+      for (const neighbor of dependents.get(node)) {
+        const newDeg = currentInDegree.get(neighbor) - 1;
+        currentInDegree.set(neighbor, newDeg);
+        if (newDeg === 0) {
+          queue.push(neighbor);
+        }
+      }
+    }
+
+    if (processedNodes !== totalNodes) {
+      const cyclePath = this._findCyclePath();
+      throw new DagCycleError(cyclePath);
+    }
+
+    return { executionOrder, dependents };
+  }
+
+  /**
+   * Finds the exact circular path sequence in the task dependency graph.
+   * @private
+   */
+  _findCyclePath() {
+    const visited = new Set();
+    const stack = [];
+    const stackSet = new Set();
+
+    const dfs = (nodeId) => {
+      visited.add(nodeId);
+      stack.push(nodeId);
+      stackSet.add(nodeId);
+
+      const task = this.tasks.get(nodeId);
+      if (task) {
+        for (const depId of task.dependsOn) {
+          if (!this.tasks.has(depId)) continue;
+          if (!visited.has(depId)) {
+            const res = dfs(depId);
+            if (res) return res;
+          } else if (stackSet.has(depId)) {
+            const cycleStartIdx = stack.indexOf(depId);
+            const rawCycle = stack.slice(cycleStartIdx);
+            rawCycle.push(depId);
+            return rawCycle;
+          }
+        }
+      }
+
+      stack.pop();
+      stackSet.delete(nodeId);
+      return null;
+    };
+
+    // Sort keys lexicographically for deterministic cycle path detection
+    const sortedKeys = Array.from(this.tasks.keys()).sort();
+    for (const id of sortedKeys) {
+      if (!visited.has(id)) {
+        const cycle = dfs(id);
+        if (cycle) {
+          return cycle.reverse();
+        }
+      }
+    }
+
+    return sortedKeys;
+  }
+
+  /**
+   * Computes SHA-256 hash of a file path using node:crypto.
+   * @private
+   */
+  _computeFileHash(filePath) {
+    if (!existsSync(filePath)) {
+      return createHash("sha256").update("").digest("hex");
+    }
+    const content = readFileSync(filePath);
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  /**
+   * Executes tasks in topological order with parallel concurrency and interface fingerprinting.
+   * @param {Object} [options]
+   * @param {number} [options.concurrency]
+   */
+  async execute({ concurrency = this.concurrency } = {}) {
+    const { dependents } = this.validateDag();
+
+    const completed = new Set();
+    const running = new Set();
+    const fingerprints = new Map();
+    const executionHistory = [];
+
+    const inDegree = new Map();
+    for (const [id, task] of this.tasks.entries()) {
+      inDegree.set(id, task.dependsOn.length);
+    }
+
+    return new Promise((resolve, reject) => {
+      let isSettled = false;
+
+      const fail = (err) => {
+        if (!isSettled) {
+          isSettled = true;
+          reject(err);
+        }
+      };
+
+      const checkAndSchedule = async () => {
+        if (isSettled) return;
+
+        if (completed.size === this.tasks.size) {
+          isSettled = true;
+          return resolve({ executionHistory, fingerprints });
+        }
+
+        const readyTasks = [];
+        for (const [id, deg] of inDegree.entries()) {
+          if (deg === 0 && !completed.has(id) && !running.has(id)) {
+            readyTasks.push(id);
+          }
+        }
+
+        readyTasks.sort();
+
+        while (running.size < concurrency && readyTasks.length > 0) {
+          const taskId = readyTasks.shift();
+          const task = this.tasks.get(taskId);
+
+          // Verification Gate & Interface Fingerprint Check
+          try {
+            for (const depId of task.dependsOn) {
+              const depTask = this.tasks.get(depId);
+              for (const outputFile of depTask.outputs) {
+                const expectedHash = fingerprints.get(outputFile);
+                const actualHash = this._computeFileHash(outputFile);
+                if (expectedHash !== actualHash) {
+                  throw new Error(
+                    `Interface fingerprint mismatch for output '${outputFile}' from dependency '${depId}'`
+                  );
+                }
+              }
+            }
+          } catch (gateErr) {
+            return fail(gateErr);
+          }
+
+          running.add(taskId);
+
+          (async () => {
+            try {
+              executionHistory.push(taskId);
+              await task.runner({
+                id: task.id,
+                dependsOn: task.dependsOn,
+                outputs: task.outputs,
+                fingerprints,
+              });
+
+              // Post-task Interface Fingerprinting
+              for (const outputFile of task.outputs) {
+                const hash = this._computeFileHash(outputFile);
+                fingerprints.set(outputFile, hash);
+              }
+
+              running.delete(taskId);
+              completed.add(taskId);
+
+              for (const depNode of dependents.get(taskId)) {
+                inDegree.set(depNode, inDegree.get(depNode) - 1);
+              }
+
+              checkAndSchedule();
+            } catch (err) {
+              running.delete(taskId);
+              fail(err);
+            }
+          })();
+        }
+      };
+
+      checkAndSchedule();
+    });
+  }
+}

package/src/engine.mjs

@@ -113,13 +113,24 @@ export async function gate(opts = {}) {
   let testResult = { ok: true, status: 0 };
   let buildResult = { ok: true, status: 0 };
 
+  const existingNodeOptions = process.env.NODE_OPTIONS || "";
+  const netGuardFlag = "--import ./src/preload-net-guard.mjs";
+  const guardNodeOptions = existingNodeOptions && !existingNodeOptions.includes(netGuardFlag)
+    ? `${existingNodeOptions} ${netGuardFlag}`
+    : existingNodeOptions ? existingNodeOptions : netGuardFlag;
+
+  const testEnv = {
+    ...process.env,
+    NODE_OPTIONS: guardNodeOptions,
+  };
+
   if (testCmd) {
-    const res = runCmd(testCmd, { cwd: root, ignoreError: true });
+    const res = runCmd(testCmd, { cwd: root, ignoreError: true, env: testEnv });
     testResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: testCmd };
   }
 
   if (testResult.ok && buildCmd) {
-    const res = runCmd(buildCmd, { cwd: root, ignoreError: true });
+    const res = runCmd(buildCmd, { cwd: root, ignoreError: true, env: testEnv });
     buildResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: buildCmd };
   }
 

package/src/git.mjs

@@ -39,6 +39,7 @@ export function runCmd(command, opts = {}) {
       encoding: "utf-8",
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
+      env: opts.env || process.env,
     });
     return { status: 0, stdout: stdout.trim(), stderr: "" };
   } catch (err) {

package/src/preload-net-guard.mjs

@@ -0,0 +1,132 @@
+import http from "node:http";
+import https from "node:https";
+
+const ALLOWLIST = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function normalizeHost(host) {
+  if (!host) return "localhost";
+  let h = String(host).trim().toLowerCase();
+  if (h.startsWith("[")) {
+    const closing = h.indexOf("]");
+    if (closing !== -1) {
+      h = h.substring(1, closing);
+    }
+  } else {
+    h = h.split(":")[0];
+  }
+  return h;
+}
+
+function checkHost(rawHost) {
+  const norm = normalizeHost(rawHost);
+  if (!ALLOWLIST.has(norm)) {
+    process.stderr.write(`[FATAL] ERR_UNMOCKED_NET: ${norm}\n`);
+    process.exit(188);
+  }
+}
+
+function extractHostFromFetch(input) {
+  let urlStr = "";
+  if (typeof input === "string") {
+    urlStr = input;
+  } else if (input && typeof input === "object") {
+    if (input instanceof URL) {
+      return input.hostname;
+    }
+    if (input.url) {
+      urlStr = String(input.url);
+    }
+  }
+
+  if (urlStr) {
+    try {
+      const parsed = new URL(urlStr, "http://localhost");
+      return parsed.hostname;
+    } catch (_) {
+      return urlStr;
+    }
+  }
+  return "localhost";
+}
+
+function extractHostFromHttpArgs(args) {
+  if (!args || args.length === 0) return "localhost";
+
+  let urlArg = null;
+  let optionsArg = null;
+
+  if (typeof args[0] === "string" || args[0] instanceof URL) {
+    urlArg = args[0];
+    if (args[1] && typeof args[1] === "object" && !Array.isArray(args[1])) {
+      optionsArg = args[1];
+    }
+  } else if (args[0] && typeof args[0] === "object" && !Array.isArray(args[0])) {
+    optionsArg = args[0];
+  }
+
+  let rawHost = "";
+  if (optionsArg) {
+    rawHost = optionsArg.hostname || optionsArg.host;
+  }
+
+  if (!rawHost && urlArg) {
+    if (urlArg instanceof URL) {
+      rawHost = urlArg.hostname;
+    } else if (typeof urlArg === "string") {
+      try {
+        const u = new URL(urlArg, "http://localhost");
+        rawHost = u.hostname;
+      } catch (_) {
+        rawHost = urlArg;
+      }
+    }
+  }
+
+  if (!rawHost) {
+    rawHost = "localhost";
+  }
+
+  return rawHost;
+}
+
+// Patch globalThis.fetch
+if (typeof globalThis.fetch === "function") {
+  const origFetch = globalThis.fetch;
+  globalThis.fetch = function (input, init) {
+    const rawHost = extractHostFromFetch(input);
+    checkHost(rawHost);
+    return origFetch.call(this, input, init);
+  };
+}
+
+// Patch node:http.request
+const origHttpRequest = http.request;
+http.request = function (...args) {
+  const rawHost = extractHostFromHttpArgs(args);
+  checkHost(rawHost);
+  return origHttpRequest.apply(this, args);
+};
+
+// Patch node:http.get
+const origHttpGet = http.get;
+http.get = function (...args) {
+  const rawHost = extractHostFromHttpArgs(args);
+  checkHost(rawHost);
+  return origHttpGet.apply(this, args);
+};
+
+// Patch node:https.request
+const origHttpsRequest = https.request;
+https.request = function (...args) {
+  const rawHost = extractHostFromHttpArgs(args);
+  checkHost(rawHost);
+  return origHttpsRequest.apply(this, args);
+};
+
+// Patch node:https.get
+const origHttpsGet = https.get;
+https.get = function (...args) {
+  const rawHost = extractHostFromHttpArgs(args);
+  checkHost(rawHost);
+  return origHttpsGet.apply(this, args);
+};