jules-orchestrator-kit 0.22.8 → 0.22.9

package/bin/agentctl.mjs

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

package/package.json

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

package/src/dag-engine.mjs

@@ -14,23 +14,50 @@ export class DagCycleError extends Error {
 }
 
 /**
- * Zero-Dependency Task DAG Executor with cycle detection and interface fingerprinting.
+ * Wraps an async runner function with a timeout (default 15 minutes = 900,000 ms).
+ * @param {Function} runner
+ * @param {number} [timeoutMs=900000]
+ * @returns {Promise<any>}
+ */
+export async function withTaskTimeout(runner, timeoutMs = 15 * 60 * 1000) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Task execution timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([runner(), timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Zero-Dependency Task DAG Executor with cycle detection, interface fingerprinting, and execution freezing.
  */
 export class DagExecutor {
-  constructor({ concurrency = 4 } = {}) {
+  constructor({ concurrency = 4, taskTimeout = 15 * 60 * 1000 } = {}) {
     this.concurrency = concurrency;
+    this.taskTimeout = taskTimeout;
     this.tasks = new Map();
+    this.isExecuting = false;
   }
 
   /**
-   * Registers a task into the DAG.
+   * Registers a task into the DAG. Throws if called after execution has started.
    * @param {Object} task
    * @param {string} task.id
    * @param {string[]} [task.dependsOn=[]]
    * @param {string[]} [task.outputs=[]]
    * @param {Function} [task.runner]
+   * @param {number} [task.timeout]
    */
-  addTask({ id, dependsOn = [], outputs = [], runner }) {
+  addTask({ id, dependsOn = [], outputs = [], runner, timeout }) {
+    if (this.isExecuting) {
+      throw new Error("Cannot add task after execution has started");
+    }
     if (!id || typeof id !== "string") {
       throw new Error("Task id must be a non-empty string");
     }
@@ -42,6 +69,7 @@ export class DagExecutor {
       dependsOn: Array.isArray(dependsOn) ? [...dependsOn] : [],
       outputs: Array.isArray(outputs) ? [...outputs] : [],
       runner: runner || (async () => {}),
+      timeout,
     });
   }
 
@@ -171,8 +199,10 @@ export class DagExecutor {
    * Executes tasks in topological order with parallel concurrency and interface fingerprinting.
    * @param {Object} [options]
    * @param {number} [options.concurrency]
+   * @param {number} [options.taskTimeout]
    */
-  async execute({ concurrency = this.concurrency } = {}) {
+  async execute({ concurrency = this.concurrency, taskTimeout = this.taskTimeout } = {}) {
+    this.isExecuting = true;
     const { dependents } = this.validateDag();
 
     const completed = new Set();
@@ -221,7 +251,7 @@ export class DagExecutor {
             for (const depId of task.dependsOn) {
               const depTask = this.tasks.get(depId);
               for (const outputFile of depTask.outputs) {
-                const expectedHash = fingerprints.get(outputFile);
+                const expectedHash = fingerprints.get(`${depId}:${outputFile}`) ?? fingerprints.get(outputFile);
                 const actualHash = this._computeFileHash(outputFile);
                 if (expectedHash !== actualHash) {
                   throw new Error(
@@ -239,16 +269,22 @@ export class DagExecutor {
           (async () => {
             try {
               executionHistory.push(taskId);
-              await task.runner({
-                id: task.id,
-                dependsOn: task.dependsOn,
-                outputs: task.outputs,
-                fingerprints,
-              });
-
-              // Post-task Interface Fingerprinting
+              const timeoutMs = task.timeout || taskTimeout;
+              await withTaskTimeout(
+                () =>
+                  task.runner({
+                    id: task.id,
+                    dependsOn: task.dependsOn,
+                    outputs: task.outputs,
+                    fingerprints,
+                  }),
+                timeoutMs
+              );
+
+              // Post-task Interface Fingerprinting (keyed by taskId:filePath and filePath alias)
               for (const outputFile of task.outputs) {
                 const hash = this._computeFileHash(outputFile);
+                fingerprints.set(`${taskId}:${outputFile}`, hash);
                 fingerprints.set(outputFile, hash);
               }
 

package/src/engine.mjs

@@ -9,7 +9,7 @@ import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 
-export { recordVerifyRun, readVerifyRuns, flakyVerdict };
+export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData };
 
 /**
  * Validates whether a file in .agent/jules-queue/ is a task file.

package/src/mcp.mjs

@@ -7,7 +7,7 @@ import { reapOrphanedIntents, reapStaleMutexDirs } from "./journal.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.22.8",
+  version: "0.22.9",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/merge-blocks.mjs

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Computes SHA-1 hash of a string.
+ * @param {string} content
+ * @returns {string} SHA-1 hex string
+ */
+function sha1(content) {
+  return createHash("sha1").update(content).digest("hex");
+}
+
+/**
+ * Chunks source code text into declaration blocks bounded by column-0 declaration boundaries.
+ * @param {string} text
+ * @param {string} [lang="js"]
+ * @returns {Array<Object>} Array of block descriptors
+ */
+export function chunkBlocks(text = "", lang = "js") {
+  if (typeof text !== "string") {
+    text = String(text || "");
+  }
+
+  const lines = text.split(/\r?\n/);
+  const blocks = [];
+  const nameCounts = new Map();
+
+  const isPython = lang === "py" || lang === "python";
+
+  // Declaration regex matching column 0
+  const declRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\s+([a-zA-Z0-9_$]+)/;
+  const declAnyRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\b/;
+
+  let currentLines = [];
+  let currentType = "prelude";
+  let currentName = null;
+  let inBlock = false;
+  let braceDepth = 0;
+  let blockIndentLevel = 0;
+
+  function flushBlock() {
+    if (currentLines.length === 0) return;
+    const content = currentLines.join("\n");
+    if (currentType === "prelude" && content.trim().length === 0) {
+      currentLines = [];
+      return;
+    }
+    let name = currentName;
+    if (!name) {
+      name = currentType === "prelude" ? `prelude_${blocks.length}` : `block_${blocks.length}`;
+    }
+
+    // Ensure unique block ID if duplicate names exist
+    const count = (nameCounts.get(name) || 0) + 1;
+    nameCounts.set(name, count);
+    const uniqueId = count > 1 ? `${currentType}:${name}:${count}` : `${currentType}:${name}`;
+
+    blocks.push({
+      id: uniqueId,
+      name,
+      type: currentType,
+      lines: [...currentLines],
+      content,
+      hash: sha1(content),
+      indentation: blockIndentLevel,
+    });
+
+    currentLines = [];
+    currentType = "prelude";
+    currentName = null;
+    inBlock = false;
+    braceDepth = 0;
+    blockIndentLevel = 0;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isColumnZero = line.length > 0 && line[0] !== " " && line[0] !== "\t";
+
+    if (isPython) {
+      // Python block logic
+      if (isColumnZero && declAnyRegex.test(line)) {
+        flushBlock();
+        const match = line.match(declRegex);
+        currentType = match ? match[1] : "def";
+        currentName = match ? match[2] : null;
+        inBlock = true;
+        blockIndentLevel = 0;
+      } else if (inBlock && isColumnZero && line.trim().length > 0 && !line.trim().startsWith("#")) {
+        // Dedented back to column 0 in Python
+        flushBlock();
+      }
+    } else {
+      // JS/TS block logic
+      if (isColumnZero && declAnyRegex.test(line)) {
+        flushBlock();
+        const match = line.match(declRegex);
+        currentType = match ? match[1] : "decl";
+        currentName = match ? match[2] : null;
+        inBlock = true;
+        blockIndentLevel = 0;
+      }
+    }
+
+    currentLines.push(line);
+
+    if (!isPython && inBlock) {
+      // Track curly brace balance for JS/TS
+      for (const char of line) {
+        if (char === "{") braceDepth++;
+        if (char === "}") braceDepth--;
+      }
+
+      // Check if block ends on this line
+      const isClosingBraceAtColZero = isColumnZero && line.trim() === "}";
+      const isSingleLineStatement = braceDepth <= 0 && (line.trim().endsWith(";") || isClosingBraceAtColZero);
+
+      if (braceDepth <= 0 && isSingleLineStatement) {
+        flushBlock();
+      }
+    }
+  }
+
+  flushBlock();
+  return blocks;
+}
+
+/**
+ * Performs a 3-way block structural merge between base, ours, and theirs.
+ * @param {string} baseText
+ * @param {string} oursText
+ * @param {string} theirsText
+ * @param {string} [lang="js"]
+ * @returns {Object} { mergedText, classifications, conflicts, toString() }
+ */
+export function mergeBlocks3Way(baseText = "", oursText = "", theirsText = "", lang = "js") {
+  const baseBlocks = chunkBlocks(baseText, lang);
+  const oursBlocks = chunkBlocks(oursText, lang);
+  const theirsBlocks = chunkBlocks(theirsText, lang);
+
+  const baseMap = new Map(baseBlocks.map((b) => [b.id, b]));
+  const theirsMap = new Map(theirsBlocks.map((b) => [b.id, b]));
+
+  const classifications = [];
+  const processed = new Set();
+  const outputBlocks = [];
+  let conflicts = 0;
+
+  // Process oursBlocks first
+  for (const oBlock of oursBlocks) {
+    const id = oBlock.id;
+    processed.add(id);
+
+    const bBlock = baseMap.get(id);
+    const tBlock = theirsMap.get(id);
+
+    if (tBlock && bBlock) {
+      if (oBlock.hash === tBlock.hash) {
+        // Both match exactly
+        classifications.push({ id, type: "IDENTICAL" });
+        outputBlocks.push(oBlock.content);
+      } else if (oBlock.hash === bBlock.hash) {
+        // Ours didn't change, theirs changed
+        classifications.push({ id, type: "ONLY_THEIRS" });
+        outputBlocks.push(tBlock.content);
+      } else if (tBlock.hash === bBlock.hash) {
+        // Theirs didn't change, ours changed
+        classifications.push({ id, type: "ONLY_OURS" });
+        outputBlocks.push(oBlock.content);
+      } else {
+        // Both changed differently
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    } else if (tBlock && !bBlock) {
+      // Added in both ours and theirs
+      if (oBlock.hash === tBlock.hash) {
+        classifications.push({ id, type: "IDENTICAL" });
+        outputBlocks.push(oBlock.content);
+      } else {
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    } else if (!tBlock && bBlock) {
+      // Present in base and ours, missing in theirs
+      if (oBlock.hash === bBlock.hash) {
+        // Deleted by theirs, unchanged by ours
+        classifications.push({ id, type: "DELETED" });
+      } else {
+        // Modified by ours, deleted by theirs -> CONFLICT
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n>>>>>>> THEIRS`);
+      }
+    } else {
+      // !tBlock && !bBlock -> ADDED_OURS
+      classifications.push({ id, type: "ADDED_OURS" });
+      outputBlocks.push(oBlock.content);
+    }
+  }
+
+  // Handle blocks in theirs that were not in ours
+  for (const tBlock of theirsBlocks) {
+    const id = tBlock.id;
+    if (processed.has(id)) continue;
+    processed.add(id);
+
+    const bBlock = baseMap.get(id);
+    if (!bBlock) {
+      // Added in theirs
+      classifications.push({ id, type: "ADDED_THEIRS" });
+      outputBlocks.push(tBlock.content);
+    } else {
+      // Present in base and theirs, deleted by ours
+      if (tBlock.hash === bBlock.hash) {
+        // Deleted by ours, unchanged by theirs
+        classifications.push({ id, type: "DELETED" });
+      } else {
+        // Modified by theirs, deleted by ours -> CONFLICT
+        conflicts++;
+        classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
+        outputBlocks.push(`<<<<<<< OURS\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
+      }
+    }
+  }
+
+  const mergedText = outputBlocks.join("\n\n");
+
+  return {
+    mergedText,
+    classifications,
+    conflicts,
+    toString() {
+      return this.mergedText;
+    },
+  };
+}

package/src/merge-verify.mjs

@@ -0,0 +1,63 @@
+import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Syntax Verification Chain validating merged output via target runtime tools.
+ * @param {string} mergedText
+ * @param {string} fileName
+ * @param {string} [root=process.cwd()]
+ * @returns {{ ok: boolean, tool: string, error?: string }}
+ */
+export function mergeVerifyChain(mergedText, fileName, root = process.cwd()) {
+  const ext = extname(fileName).toLowerCase();
+  const base = basename(fileName) || `temp_file${ext}`;
+  const tempDir = join(tmpdir(), `merge-verify-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  
+  mkdirSync(tempDir, { recursive: true });
+  const tempFilePath = join(tempDir, base);
+
+  try {
+    writeFileSync(tempFilePath, mergedText, "utf8");
+
+    let cmd = "";
+    let args = [];
+    let tool = "";
+
+    if (ext === ".py") {
+      cmd = "python3";
+      args = ["-m", "py_compile", tempFilePath];
+      tool = "python3 -m py_compile";
+    } else if (ext === ".ts" || ext === ".tsx" || ext === ".mts" || ext === ".cts") {
+      const hasTsConfig = existsSync(join(root, "tsconfig.json"));
+      if (hasTsConfig) {
+        cmd = "npx";
+        args = ["tsc", "--noEmit", tempFilePath];
+        tool = "tsc --noEmit";
+      } else {
+        cmd = "node";
+        args = ["--check", tempFilePath];
+        tool = "node --check";
+      }
+    } else {
+      // JS, MJS, CJS or default
+      cmd = "node";
+      args = ["--check", tempFilePath];
+      tool = "node --check";
+    }
+
+    const res = spawnSync(cmd, args, { encoding: "utf8" });
+    const ok = res.status === 0;
+
+    return {
+      ok,
+      tool,
+      ...(ok ? {} : { error: res.stderr || res.stdout || `Process exited with code ${res.status}` }),
+    };
+  } finally {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}