jules-orchestrator-kit 0.9.3 → 0.20.0

package/src/mcp.mjs

@@ -0,0 +1,297 @@
+import { Transform } from "node:stream";
+import { loadConfig, resolveRoot, detectStack } from "./config.mjs";
+import { gate, dispatch } from "./engine.mjs";
+import { classifyRiskTier } from "./risk.mjs";
+import { checkDailyBudget, lockStatus } from "./state.mjs";
+
+export const MCP_SERVER_INFO = {
+  name: "jules-orchestrator-kit",
+  version: "0.20.0",
+};
+
+export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
+
+/**
+ * Memory-bounded MCP Frame Decoder supporting both Content-Length headers and line-delimited JSON-RPC messages.
+ */
+export class McpFrameDecoder extends Transform {
+  constructor(options = {}) {
+    super({ ...options, readableObjectMode: true });
+    this.buffer = Buffer.alloc(0);
+    this.maxFrameSize = options.maxFrameSize || MAX_MCP_FRAME_SIZE;
+  }
+
+  _transform(chunk, encoding, callback) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+
+    if (this.buffer.length > this.maxFrameSize * 2) {
+      this.emit("error", new Error(`MCP Stdio buffer exceeded max limit of ${this.maxFrameSize} bytes`));
+      this.buffer = Buffer.alloc(0);
+      return callback();
+    }
+
+    while (this.buffer.length > 0) {
+      const str = this.buffer.toString("utf-8");
+      const headerMatch = /Content-Length:\s*(\d+)\r?\n\r?\n/i.exec(str);
+
+      if (headerMatch) {
+        const contentLength = parseInt(headerMatch[1], 10);
+        if (contentLength > this.maxFrameSize) {
+          this.emit("error", new Error(`Frame Content-Length (${contentLength}) exceeds limit (${this.maxFrameSize})`));
+          this.buffer = Buffer.alloc(0);
+          return callback();
+        }
+
+        const headerLength = headerMatch.index + headerMatch[0].length;
+        const totalFrameLength = headerLength + contentLength;
+
+        if (this.buffer.length >= totalFrameLength) {
+          const payloadBuf = this.buffer.subarray(headerLength, totalFrameLength);
+          this.buffer = this.buffer.subarray(totalFrameLength);
+          try {
+            const parsed = JSON.parse(payloadBuf.toString("utf-8"));
+            this.push(parsed);
+          } catch (err) {
+            this.emit("error", new Error(`Malformed JSON payload in framed message: ${err.message}`));
+          }
+          continue;
+        } else {
+          break;
+        }
+      }
+
+      const newlineIndex = this.buffer.indexOf(0x0a);
+      if (newlineIndex !== -1) {
+        const lineBuf = this.buffer.subarray(0, newlineIndex);
+        this.buffer = this.buffer.subarray(newlineIndex + 1);
+
+        const lineStr = lineBuf.toString("utf-8").trim();
+        if (!lineStr) continue;
+
+        if (/^Content-Length:\s*\d+/i.test(lineStr)) continue;
+
+        try {
+          const parsed = JSON.parse(lineStr);
+          this.push(parsed);
+        } catch (err) {
+          this.emit("error", new Error(`Malformed JSON in line-delimited message: ${err.message}`));
+        }
+        continue;
+      }
+
+      break;
+    }
+
+    callback();
+  }
+}
+
+export const MCP_TOOLS = [
+  {
+    name: "dispatch_jules_task",
+    description: "Dispatch an autonomous task to the Jules AI agent provider with security bounds and budget check.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short descriptive title for the task" },
+        prompt: { type: "string", description: "Detailed task instructions and prompt" },
+      },
+      required: ["prompt"],
+    },
+  },
+  {
+    name: "audit_jules_gate",
+    description: "Run the 4-phase safety gatekeeper (Scope, Payload, Secrets, Verify) against the current workspace branch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        base: { type: "string", description: "Base branch to diff against (defaults to main)" },
+        fix: { type: "boolean", description: "Attempt OODA auto-repair loop on verification failure" },
+        allowProtected: { type: "boolean", description: "Allow edits to protected files" },
+      },
+    },
+  },
+  {
+    name: "check_risk_tier",
+    description: "Classify changed files into Risk Tiers (R0 Cosmetic, R1 Routine, R2 Consequential, R3 Restricted).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of file paths changed",
+        },
+        diffLines: { type: "number", description: "Total lines changed in diff" },
+      },
+      required: ["files"],
+    },
+  },
+  {
+    name: "get_jules_status",
+    description: "Retrieve orchestrator status including daily task budget, active locks, and stack diagnostics.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+export async function handleMcpRequest(request, opts = {}) {
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const { id, method, params } = request;
+
+  if (method === "ping") {
+    return { jsonrpc: "2.0", id, result: {} };
+  }
+
+  if (method === "initialize") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: MCP_SERVER_INFO,
+      },
+    };
+  }
+
+  if (method === "notifications/initialized") {
+    return null;
+  }
+
+  if (method === "tools/list") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { tools: MCP_TOOLS },
+    };
+  }
+
+  if (method === "tools/call") {
+    const toolName = params?.name;
+    const args = params?.arguments || {};
+
+    try {
+      if (toolName === "dispatch_jules_task") {
+        const session = await dispatch(
+          { title: args.title || "MCP Task Dispatch", prompt: args.prompt },
+          { root, config }
+        );
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, session }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "audit_jules_gate") {
+        const res = await gate({
+          root,
+          config,
+          base: args.base || config.baseBranch || "main",
+          fix: args.fix || false,
+          allowProtected: args.allowProtected || false,
+        });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "check_risk_tier") {
+        const tierResult = classifyRiskTier(args.files || [], { diffLines: args.diffLines || 0 });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(tierResult, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "get_jules_status") {
+        const stackInfo = detectStack(root);
+        const budget = checkDailyBudget(root, config.limits.dailyTasks);
+        const locks = lockStatus(root);
+        const status = {
+          version: MCP_SERVER_INFO.version,
+          root,
+          stack: stackInfo.stack,
+          budget: { used: budget.used, limit: budget.budget, remaining: budget.budget - budget.used },
+          activeLocksCount: locks.length,
+          locks,
+        };
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+          },
+        };
+      }
+
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: `Unknown tool: ${toolName}` },
+      };
+    } catch (err) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: JSON.stringify({ ok: false, error: err.message }, null, 2) }],
+          isError: true,
+        },
+      };
+    }
+  }
+
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` },
+  };
+}
+
+export function startMcpServer(input = process.stdin, output = process.stdout, opts = {}) {
+  const decoder = new McpFrameDecoder({ maxFrameSize: opts.maxFrameSize || MAX_MCP_FRAME_SIZE });
+
+  decoder.on("data", async (request) => {
+    try {
+      const response = await handleMcpRequest(request, opts);
+      if (response !== null && response !== undefined) {
+        output.write(JSON.stringify(response) + "\n");
+      }
+    } catch (err) {
+      // Panic boundary: Catch unhandled async exceptions and send valid JSON-RPC error
+      output.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: request?.id || null,
+          error: { code: -32603, message: `Internal server panic: ${err.message}` },
+        }) + "\n"
+      );
+    }
+  });
+
+  decoder.on("error", (err) => {
+    output.write(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: `MCP Stream framing error: ${err.message}` },
+      }) + "\n"
+    );
+  });
+
+  input.pipe(decoder);
+}

package/src/process-group.mjs

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+
+/**
+ * ProcessGroupManager manages child processes in isolated process groups
+ * and ensures 100% leak-free cleanup on process exit or termination signals.
+ */
+export class ProcessGroupManager {
+  constructor() {
+    this.activePgids = new Set();
+    this.activePids = new Set();
+    this.installed = false;
+    this.installSignalHandlers();
+  }
+
+  installSignalHandlers() {
+    if (this.installed) return;
+    this.installed = true;
+
+    const cleanup = (signal) => {
+      this.killAll(signal || "SIGTERM");
+    };
+
+    process.once("SIGINT", () => {
+      cleanup("SIGINT");
+      process.exit(130);
+    });
+
+    process.once("SIGTERM", () => {
+      cleanup("SIGTERM");
+      process.exit(143);
+    });
+
+    process.once("exit", () => {
+      this.killAll("SIGKILL");
+    });
+  }
+
+  spawnProcess(command, args = [], options = {}) {
+    const opts = {
+      ...options,
+      detached: true,
+    };
+
+    const child = spawn(command, args, opts);
+
+    if (child.pid) {
+      const pgid = child.pid;
+      this.activePgids.add(pgid);
+      this.activePids.add(child.pid);
+
+      child.on("exit", () => {
+        this.activePgids.delete(pgid);
+        this.activePids.delete(child.pid);
+      });
+
+      child.on("error", () => {
+        this.activePgids.delete(pgid);
+        this.activePids.delete(child.pid);
+      });
+    }
+
+    return child;
+  }
+
+  killAll(signal = "SIGTERM") {
+    for (const pgid of this.activePgids) {
+      try {
+        process.kill(-pgid, signal);
+      } catch (_) {
+        try {
+          process.kill(pgid, signal);
+        } catch (_) {}
+      }
+    }
+    this.activePgids.clear();
+    this.activePids.clear();
+  }
+}
+
+export const processGroupManager = new ProcessGroupManager();

package/src/risk.mjs

@@ -1,4 +1,5 @@
 import { normalizePath } from "./config.mjs";
+import { matchesGlob } from "./security.mjs";
 
 export const RISK_TIERS = {
   R0: "R0_COSMETIC",     // Docs, markdown, comments, safe devDep patches
@@ -54,7 +55,7 @@ export function classifyRiskTier(files = [], opts = {}) {
   for (const rawFile of files) {
     const file = normalizePath(rawFile);
     for (const pat of RESTRICTED_PATH_PATTERNS) {
-      if (file.includes(pat.replace(/\*/g, "")) || file.endsWith(pat)) {
+      if (matchesGlob(file, pat) || file.endsWith(pat)) {
         return {
           tier: RISK_TIERS.R3,
           reason: `Matches restricted security/financial path pattern '${pat}'`,
@@ -78,7 +79,7 @@ export function classifyRiskTier(files = [], opts = {}) {
   for (const rawFile of files) {
     const file = normalizePath(rawFile);
     for (const pat of CONSEQUENTIAL_PATH_PATTERNS) {
-      if (file.includes(pat.replace(/\*/g, ""))) {
+      if (matchesGlob(file, pat)) {
         return {
           tier: RISK_TIERS.R2,
           reason: `Matches consequential component/DB path pattern '${pat}'`,

package/src/rules_budget.mjs

@@ -1,9 +1,13 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 
 const DEFAULT_MAX_CHARS = 10000; // Safe threshold below Antigravity 12k & Claude 25k limits
 const DEFAULT_MAX_LINES = 250;
 
+export const SENTINEL_BEGIN = "JULES_RULES_SENTINEL BEGIN";
+export const SENTINEL_END = "JULES_RULES_SENTINEL END";
+
 /**
  * Audit character and line counts of compiled instruction files to prevent truncation.
  *
@@ -68,6 +72,103 @@ export function checkRulesBudget(root = process.cwd(), opts = {}) {
   };
 }
 
+/**
+ * Compiles markdown/rules files into a single unified context block wrapped
+ * in SHA-256 and byte-length anti-truncation sentinels.
+ */
+export function compileRules(root = process.cwd(), _opts = {}) {
+  const candidateFiles = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+    "JULES_RULES_TEMPLATE.md",
+  ];
+
+  const rulesDir = join(root, ".agent", "rules");
+  try {
+    const files = readdirSync(rulesDir);
+    for (const f of files) {
+      if (f.endsWith(".md")) {
+        candidateFiles.push(join(".agent", "rules", f));
+      }
+    }
+  } catch (_) {}
+
+  const sources = [];
+  const sections = [];
+
+  for (const relPath of candidateFiles) {
+    const fullPath = join(root, relPath);
+    if (!existsSync(fullPath)) continue;
+    try {
+      const raw = readFileSync(fullPath, "utf-8");
+      const body = raw.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+      if (!body) continue;
+      sections.push(`<!-- source: ${relPath} -->\n${body}`);
+      sources.push(relPath);
+    } catch (_) {}
+  }
+
+  const body = sections.join("\n\n---\n\n");
+  const bodyLen = Buffer.byteLength(body, "utf-8");
+  const sha256 = createHash("sha256").update(body).digest("hex");
+
+  const header = `<!-- ${SENTINEL_BEGIN} len=${bodyLen} sha256=${sha256} -->`;
+  const footer = `<!-- ${SENTINEL_END} len=${bodyLen} sha256=${sha256} -->`;
+  const compiled = `${header}\n${body}\n${footer}\n`;
+
+  return { compiled, body, bodyLen, sha256, sources };
+}
+
+/**
+ * Verifies that a compiled rule string has not been truncated or tampered with by downstream LLMs.
+ */
+export function verifyRulesSentinel(compiled) {
+  const errors = [];
+  if (typeof compiled !== "string" || compiled.length === 0) {
+    return { ok: false, errors: ["empty input"] };
+  }
+
+  const beginRe = new RegExp(`<!--\\s*${SENTINEL_BEGIN.replace(/ /g, "\\s+")}\\s+len=(\\d+)\\s+sha256=([0-9a-f]{64})\\s*-->`);
+  const endRe = new RegExp(`<!--\\s*${SENTINEL_END.replace(/ /g, "\\s+")}\\s+len=(\\d+)\\s+sha256=([0-9a-f]{64})\\s*-->`);
+
+  const beginMatch = beginRe.exec(compiled);
+  const endMatch = endRe.exec(compiled);
+
+  if (!beginMatch) { errors.push("missing or malformed BEGIN sentinel"); return { ok: false, errors }; }
+  if (!endMatch) { errors.push("missing or malformed END sentinel"); return { ok: false, errors }; }
+
+  const beginLen = Number(beginMatch[1]);
+  const beginSha = beginMatch[2];
+  const endLen = Number(endMatch[1]);
+  const endSha = endMatch[2];
+
+  if (beginLen !== endLen) errors.push(`length mismatch: BEGIN=${beginLen} END=${endLen}`);
+  if (beginSha !== endSha) errors.push("checksum mismatch between BEGIN and END sentinels");
+
+  const bodyStart = beginMatch.index + beginMatch[0].length;
+  const bodyEnd = endMatch.index;
+  const body = compiled.slice(bodyStart, bodyEnd).replace(/^\r?\n/, "").replace(/\r?\n$/, "");
+  const actualLen = Buffer.byteLength(body, "utf-8");
+
+  if (actualLen !== beginLen) {
+    errors.push(`body length ${actualLen} != declared ${beginLen} (possible truncation or injection)`);
+  }
+
+  const recomputed = createHash("sha256").update(body).digest("hex");
+  if (recomputed !== beginSha) {
+    errors.push(`body checksum ${recomputed} != declared ${beginSha} (content tampered or truncated)`);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    bodyLen: actualLen,
+    sha256: recomputed,
+  };
+}
+
 function existsSync(p) {
   try {
     return statSync(p).isFile();
@@ -75,3 +176,4 @@ function existsSync(p) {
     return false;
   }
 }
+

package/src/security.mjs

@@ -1,3 +1,6 @@
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
 import { normalizePath } from "./config.mjs";
 
 export const HIGH_CONFIDENCE_PATTERNS = [
@@ -6,34 +9,70 @@ export const HIGH_CONFIDENCE_PATTERNS = [
   /\bghu_[A-Za-z0-9_]{36,255}\b/g,
   /\bghs_[A-Za-z0-9_]{36,255}\b/g,
   /\bghr_[A-Za-z0-9_]{36,255}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{22,255}\b/g,
 
   /\bAKIA[0-9A-Z]{16}\b/g,
   /\bASIA[0-9A-Z]{16}\b/g,
   /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/g,
 
-  /-----BEGIN\s+(?:RSA|DSA|EC|OPENSSH|PRIVATE)\s+KEY-----[\s\S]*?-----END\s+(?:RSA|DSA|EC|OPENSSH|PRIVATE)\s+KEY-----/g,
+  /-----BEGIN (?:RSA|DSA|EC|OPENSSH|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|DSA|EC|OPENSSH|PRIVATE) KEY-----/g,
   /PuTTY-User-Key-File-[0-9]:[^\n]+/g,
 
   /\bsk_live_[0-9a-zA-Z]{24,99}\b/g,
   /\brk_live_[0-9a-zA-Z]{24,99}\b/g,
   /\bnpm_[0-9a-zA-Z]{36}\b/g,
-  /\bglpat-[0-9a-zA-Z_-]{20,}\b/g,
-  /\bGOCSPX-[0-9a-zA-Z_-]{28}\b/g,
+  /\bglpat-[0-9a-zA-Z_-]{20,99}\b/g,
+  /\bGOCSPX-[0-9a-zA-Z_-]{28,99}\b/g,
 
   /\bAIzaSy[A-Za-z0-9_-]{33}\b/g,
+  /\bya29\.[A-Za-z0-9_-]{20,255}\b/g,
+  /\b(?:sk-ant-api03-|sk-proj-)[A-Za-z0-9_-]{32,255}\b/g,
 
-  /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]+\/B[A-Za-z0-9_]+\/[A-Za-z0-9_]+/g,
+  /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]{8,}\/B[A-Za-z0-9_]{8,}\/[A-Za-z0-9_]{24,}/g,
+  /\bxox[baprs]-[0-9a-zA-Z-]{10,48}\b/g,
 
   /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
 ];
 
 export const LOW_CONFIDENCE_PATTERNS = [
-  /Bearer\s+[A-Za-z0-9._~+/-]{10,}/gi,
-  /Authorization:\s*Bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+  /Bearer\s+[A-Za-z0-9._~+/-]{10,255}/gi,
+  /Authorization:\s*Bearer\s+[A-Za-z0-9._~+/-]{10,255}/gi,
   /\bsk_test_[0-9a-zA-Z]{24,99}\b/g,
   /(?:api[_-]?key|secret|password|passwd|token|auth[_-]?token)\s*[:=]\s*['"]([^'"]{8,128})['"]/gi,
 ];
 
+/**
+ * TOCTOU-safe atomic file write using O_CREAT|O_EXCL|O_WRONLY temp file in target dir.
+ */
+export function safeAtomicWrite(filePath, content, options = {}) {
+  const mode = options.mode || 0o644;
+  const encoding = options.encoding || "utf-8";
+
+  if (existsSync(filePath)) {
+    const stat = lstatSync(filePath);
+    if (stat.isSymbolicLink()) {
+      const realPath = realpathSync(filePath);
+      if (options.rejectSymlinks) {
+        throw new Error(`TOCTOU Guard: Refusing to write to symlink ${filePath} -> ${realPath}`);
+      }
+    }
+  }
+
+  const dir = dirname(filePath);
+  const tempFile = join(dir, `.tmp-${basename(filePath)}-${randomBytes(6).toString("hex")}`);
+
+  const fd = openSync(tempFile, "wx", mode);
+  try {
+    writeSync(fd, content, null, encoding);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+
+  renameSync(tempFile, filePath);
+  return true;
+}
+
 export function shannonEntropy(str) {
   if (!str || typeof str !== "string") return 0;
   const len = str.length;