jules-orchestrator-kit 0.72.2 → 0.73.0

package/src/mcp.mjs

@@ -107,7 +107,7 @@ export const MCP_TOOLS = [
       properties: {
         title: { type: "string", description: "Short descriptive title for the task" },
         prompt: { type: "string", description: "Detailed task instructions and prompt" },
-        role: { type: "string", description: "Specialist agent role (overseer | bolt | sentinel | janitor)" },
+        role: { type: "string", description: "Specialist agent role (auditor | performance | security | hygiene | resilience | types | debugger | testing | e2e | database | docs | a11y)" },
         tier: { type: "string", description: "Force the Cost Router tier when router.enabled (fast | complex); omit to let the heuristic classifier decide" },
       },
       required: ["prompt"],
@@ -310,8 +310,65 @@ export const MCP_TOOLS = [
       },
     },
   },
+  {
+    name: "jules_approve_plan",
+    description: "Approve a proposed execution plan for a Jules session awaiting plan approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID to approve plan for" },
+      },
+      required: ["sessionId"],
+    },
+  },
+  {
+    name: "jules_send_message",
+    description: "Send feedback, steering instructions, or reply message to an active Jules session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID" },
+        prompt: { type: "string", description: "Instruction or feedback message" },
+      },
+      required: ["sessionId", "prompt"],
+    },
+  },
+  {
+    name: "jules_wait_for_session",
+    description: "Poll a Jules session until it reaches a terminal or action-required state (COMPLETED, FAILED, AWAITING_PLAN_APPROVAL).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sessionId: { type: "string", description: "Jules session ID" },
+        timeoutSeconds: { type: "number", description: "Maximum wait time in seconds (default 300, max 1800)" },
+        pollIntervalSeconds: { type: "number", description: "Interval between polls in seconds (default 10, min 2)" },
+        targetStates: {
+          type: "array",
+          items: { type: "string" },
+          description: "States that stop polling (defaults to COMPLETED, FAILED, AWAITING_PLAN_APPROVAL)",
+        },
+      },
+      required: ["sessionId"],
+    },
+  },
 ];
 
+// Provider-neutral names share the existing schemas and execution paths.
+// Naming aliases do not add capabilities to the configured provider.
+export const MCP_TOOL_ALIASES = Object.freeze({
+  agent_dispatch_task: "dispatch_jules_task",
+  agent_audit_gate: "audit_jules_gate",
+  agent_get_status: "get_jules_status",
+  agent_optimize_prompt: "optimize_jules_prompt",
+  ...Object.fromEntries(MCP_TOOLS.filter((tool) => tool.name.startsWith("jules_"))
+    .map((tool) => [tool.name.replace(/^jules_/, "agent_"), tool.name])),
+});
+
+for (const [alias, original] of Object.entries(MCP_TOOL_ALIASES)) {
+  const tool = MCP_TOOLS.find((entry) => entry.name === original);
+  MCP_TOOLS.push({ ...tool, name: alias });
+}
+
 export async function handleMcpRequest(request, opts = {}) {
   const root = opts.root || resolveRoot();
   const config = opts.config || loadConfig(root);
@@ -327,7 +384,7 @@ export async function handleMcpRequest(request, opts = {}) {
       id,
       result: {
         protocolVersion: "2024-11-05",
-        capabilities: { tools: {} },
+        capabilities: { tools: {}, resources: {} },
         serverInfo: MCP_SERVER_INFO,
       },
     };
@@ -337,6 +394,113 @@ export async function handleMcpRequest(request, opts = {}) {
     return null;
   }
 
+  if (method === "resources/list") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        resources: [
+          {
+            uri: "jules://status",
+            name: "Orchestrator Status",
+            description: "Daily task budget, active locks, provider readiness, and verification profile",
+            mimeType: "application/json",
+          },
+          {
+            uri: "jules://sources",
+            name: "Connected Sources",
+            description: "Connected GitHub repository sources available to the Jules account",
+            mimeType: "application/json",
+          },
+          {
+            uri: "jules://sessions",
+            name: "Recent Sessions",
+            description: "Recent Jules coding sessions snapshot",
+            mimeType: "application/json",
+          },
+        ],
+      },
+    };
+  }
+
+  if (method === "resources/read") {
+    const uri = params?.uri;
+    const isDryRun = Boolean(params?.dryRun ?? opts?.dryRun ?? opts?.config?.dryRun);
+
+    if (uri === "jules://status") {
+      const stackInfo = detectStack(root);
+      const budget = budgetStatus(config, root);
+      const locks = lockStatus(root);
+      const { probeProvider } = await import("./provider-readiness.mjs");
+      const { buildDefaultStages } = await import("./profiles.mjs");
+      const providerProbe = probeProvider(config.provider || "jules");
+      const profileStages = config.verify.stages || buildDefaultStages(config.verify);
+      const status = {
+        version: MCP_SERVER_INFO.version,
+        root,
+        stack: stackInfo.stack,
+        budget: {
+          used: budget.used,
+          limit: budget.limit,
+          remaining: budget.remaining,
+          source: budget.source,
+          enforced: budget.enforced,
+          scope: "this-repository",
+        },
+        activeLocksCount: locks.length,
+        locks,
+        provider: {
+          name: providerProbe.name,
+          kind: providerProbe.kind,
+          ready: providerProbe.ready,
+          reason: providerProbe.reason,
+        },
+        verification: {
+          profile: config.verify.profile,
+          stages: profileStages.map((st) => st.id),
+          skipped: (config.verify.profileSkipped || []).map((sk) => sk.id),
+        },
+      };
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(status, null, 2) }],
+        },
+      };
+    }
+
+    if (uri === "jules://sources") {
+      const provider = createProvider(config.provider || "jules", config);
+      const res = await provider.listSources({ root, dryRun: isDryRun });
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(res, null, 2) }],
+        },
+      };
+    }
+
+    if (uri === "jules://sessions") {
+      const provider = createProvider(config.provider || "jules", config);
+      const res = await provider.listSessions({ root, pageSize: 20, dryRun: isDryRun });
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(res, null, 2) }],
+        },
+      };
+    }
+
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32602, message: `Resource not found: ${uri}` },
+    };
+  }
+
   if (method === "tools/list") {
     return {
       jsonrpc: "2.0",
@@ -346,7 +510,9 @@ export async function handleMcpRequest(request, opts = {}) {
   }
 
   if (method === "tools/call") {
-    const toolName = params?.name;
+    const requestedName = params?.name;
+    const toolName = Object.hasOwn(MCP_TOOL_ALIASES, requestedName)
+      ? MCP_TOOL_ALIASES[requestedName] : requestedName;
     const args = params?.arguments || {};
 
     try {
@@ -563,9 +729,11 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      const isDryRun = Boolean(args.dryRun ?? opts?.dryRun ?? opts?.config?.dryRun);
+
       if (toolName === "jules_list_sessions") {
         const provider = createProvider(config.provider || "jules", config);
-        const res = await provider.listSessions({ root, pageSize: args.pageSize, pageToken: args.pageToken });
+        const res = await provider.listSessions({ root, pageSize: args.pageSize, pageToken: args.pageToken, dryRun: isDryRun });
         return {
           jsonrpc: "2.0",
           id,
@@ -584,7 +752,7 @@ export async function handleMcpRequest(request, opts = {}) {
           };
         }
         const provider = createProvider(config.provider || "jules", config);
-        const res = await provider.listActivities(args.sessionId, { root, pageSize: args.pageSize, pageToken: args.pageToken });
+        const res = await provider.listActivities(args.sessionId, { root, pageSize: args.pageSize, pageToken: args.pageToken, dryRun: isDryRun });
         return {
           jsonrpc: "2.0",
           id,
@@ -621,7 +789,7 @@ export async function handleMcpRequest(request, opts = {}) {
           };
         }
         const provider = createProvider(config.provider || "jules", config);
-        const res = await provider.archiveSession(args.sessionId, { root });
+        const res = await provider.archiveSession(args.sessionId, { root, dryRun: isDryRun });
         return {
           jsonrpc: "2.0",
           id,
@@ -640,7 +808,7 @@ export async function handleMcpRequest(request, opts = {}) {
           };
         }
         const provider = createProvider(config.provider || "jules", config);
-        const res = await provider.deleteSession(args.sessionId, { root });
+        const res = await provider.deleteSession(args.sessionId, { root, dryRun: isDryRun });
         return {
           jsonrpc: "2.0",
           id,
@@ -726,6 +894,127 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "jules_approve_plan") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.approvePlan(args.sessionId, { root, dryRun: isDryRun });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, session: res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_send_message") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        if (!args.prompt) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'prompt'" },
+          };
+        }
+        const provider = createProvider(config.provider || "jules", config);
+        const res = await provider.resume(args.sessionId, args.prompt, { root, dryRun: isDryRun });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, session: res }, null, 2) }],
+          },
+        };
+      }
+
+      if (toolName === "jules_wait_for_session") {
+        if (!args.sessionId) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Missing required parameter 'sessionId'" },
+          };
+        }
+        const timeoutSec = Math.min(Math.max(args.timeoutSeconds || 300, 2), 1800);
+        const intervalSec = Math.min(Math.max(args.pollIntervalSeconds || 10, 1), 60);
+        const targetStates = new Set(
+          (args.targetStates && Array.isArray(args.targetStates)
+            ? args.targetStates
+            : ["COMPLETED", "FAILED", "AWAITING_PLAN_APPROVAL"]
+          ).map((s) => String(s).toUpperCase())
+        );
+        const provider = createProvider(config.provider || "jules", config);
+        const startedAt = Date.now();
+        let lastSession = null;
+
+        if (isDryRun) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+              content: [{
+                type: "text",
+                text: JSON.stringify({ ok: true, dryRun: true, sessionId: args.sessionId, finalState: "COMPLETED", elapsedSeconds: 0 }, null, 2),
+              }],
+            },
+          };
+        }
+
+        while (Date.now() - startedAt < timeoutSec * 1000) {
+          lastSession = await provider.getSession(args.sessionId, { root });
+          const curState = String(lastSession?.state || lastSession?.status || "").toUpperCase();
+          if (targetStates.has(curState)) {
+            return {
+              jsonrpc: "2.0",
+              id,
+              result: {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    ok: true,
+                    sessionId: args.sessionId,
+                    finalState: curState,
+                    elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+                    session: lastSession,
+                  }, null, 2),
+                }],
+              },
+            };
+          }
+          await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        }
+
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                ok: false,
+                timeout: true,
+                sessionId: args.sessionId,
+                lastObservedState: lastSession?.state || "UNKNOWN",
+                elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+              }, null, 2),
+            }],
+            isError: true,
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,

package/src/merge-swarm.mjs

@@ -0,0 +1,202 @@
+/**
+ * Swarm branch merger with 3-way structural JSON/object merge, git merge-file
+ * execution isolated in os.tmpdir(), and safety gate checking.
+ *
+ * This is the home of the logic that used to live in
+ * `scripts/jules-merge-swarm.mjs`; that file is now a minimal CLI entry point.
+ */
+
+import { writeFileSync, readFileSync, existsSync, readdirSync, rmSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { classifyRiskTier, RISK_TIERS } from "./risk.mjs";
+import { git, resolveBase } from "./git.mjs";
+import { normalizePath, loadConfig } from "./config.mjs";
+
+export const EXIT = Object.freeze({
+  SUCCESS: 0,
+  R3_RESTRICTED: 3,
+  MERGE_CONFLICT: 4,
+});
+
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isPlainObject(v) {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === null || Object.getPrototypeOf(v) === Object.prototype)
+  );
+}
+
+function deepClone(v) {
+  if (v === undefined) return undefined;
+  return JSON.parse(JSON.stringify(v));
+}
+
+function stableStringify(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(v).filter((k) => !BLOCKED_KEYS.has(k)).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(",")}}`;
+}
+
+function deepEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+/**
+ * Recursive 3-way structural object & array merge.
+ */
+export function deepMerge3Way(base, ours, theirs, path = "$") {
+  const conflicts = [];
+  if (deepEqual(ours, theirs)) return { merged: deepClone(ours), conflicts };
+  if (deepEqual(ours, base)) return { merged: deepClone(theirs), conflicts };
+  if (deepEqual(theirs, base)) return { merged: deepClone(ours), conflicts };
+
+  if (isPlainObject(base) && isPlainObject(ours) && isPlainObject(theirs)) {
+    const merged = {};
+    const safeBase = base || {};
+    const safeOurs = ours || {};
+    const safeTheirs = theirs || {};
+    const keys = new Set([
+      ...Object.keys(safeBase),
+      ...Object.keys(safeOurs),
+      ...Object.keys(safeTheirs),
+    ]);
+    for (const k of keys) {
+      if (BLOCKED_KEYS.has(k)) continue;
+      const childPath = `${path}.${k}`;
+      const b = safeBase[k], o = safeOurs[k], t = safeTheirs[k];
+      if (o === undefined && t === undefined) continue;
+      if (o === undefined) { merged[k] = deepClone(t); continue; }
+      if (t === undefined) { merged[k] = deepClone(o); continue; }
+      const sub = deepMerge3Way(b, o, t, childPath);
+      merged[k] = sub.merged;
+      conflicts.push(...sub.conflicts);
+    }
+    return { merged, conflicts };
+  }
+
+  if (Array.isArray(ours) && Array.isArray(theirs)) {
+    const baseArr = Array.isArray(base) ? base : [];
+    const minLen = Math.min(ours.length, theirs.length);
+    const merged = [];
+    for (let i = 0; i < minLen; i++) {
+      const sub = deepMerge3Way(baseArr[i], ours[i], theirs[i], `${path}[${i}]`);
+      merged.push(sub.merged);
+      conflicts.push(...sub.conflicts);
+    }
+    if (ours.length > minLen && theirs.length <= minLen) {
+      merged.push(...ours.slice(minLen).map(deepClone));
+    } else if (theirs.length > minLen && ours.length <= minLen) {
+      merged.push(...theirs.slice(minLen).map(deepClone));
+    } else if (ours.length > minLen && theirs.length > minLen) {
+      conflicts.push({
+        path: `${path}[tail]`,
+        base: baseArr.slice(minLen),
+        ours: ours.slice(minLen),
+        theirs: theirs.slice(minLen),
+      });
+      merged.push(...ours.slice(minLen).map(deepClone));
+    }
+    return { merged, conflicts };
+  }
+
+  conflicts.push({ path, base: deepClone(base), ours: deepClone(ours), theirs: deepClone(theirs) });
+  return { merged: deepClone(ours), conflicts };
+}
+
+/**
+ * Executes a function inside a temporary directory in os.tmpdir() with guaranteed cleanup.
+ */
+export function withTempDir(prefix, fn) {
+  const dir = mkdtempSync(join(tmpdir(), prefix || "jules-merge-"));
+  try {
+    return fn(dir);
+  } finally {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch (_) {}
+  }
+}
+
+/**
+ * Attempts a 3-way text file merge using git merge-file inside os.tmpdir().
+ */
+export function attemptCodeMergeFile(repoRoot, relPath, oursContent, baseContent, theirsContent) {
+  return withTempDir("jules-merge-", (tmp) => {
+    const baseFile = join(tmp, "base");
+    const oursFile = join(tmp, "ours");
+    const theirsFile = join(tmp, "theirs");
+    writeFileSync(baseFile, baseContent ?? "", "utf-8");
+    writeFileSync(oursFile, oursContent ?? "", "utf-8");
+    writeFileSync(theirsFile, theirsContent ?? "", "utf-8");
+
+    const res = spawnSync("git", ["merge-file", "-p", "--diff3", oursFile, baseFile, theirsFile], {
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+    if (res.error) {
+      return { ok: false, conflicts: 0, error: res.error.message };
+    }
+    const conflictCount = res.status && res.status > 0 ? res.status : 0;
+    const merged = res.stdout ?? "";
+    return {
+      ok: conflictCount === 0,
+      merged,
+      conflicts: conflictCount,
+    };
+  });
+}
+
+/**
+ * Checks safety gate against active worker locks and risk tiers.
+ */
+export function checkSafetyGate(branchName = "", projectRoot = process.cwd(), opts = {}) {
+  const locksDir = join(projectRoot, ".agent/state/locks");
+  if (existsSync(locksDir)) {
+    try {
+      const files = readdirSync(locksDir);
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        const content = readFileSync(join(locksDir, f), "utf-8");
+        const parsed = JSON.parse(content);
+        if (parsed.branch === branchName) {
+          return { safe: false, reason: `Active lock held by worker ${parsed.agent || "unknown"}` };
+        }
+      }
+    } catch (_) {}
+  }
+
+  // Check R3 risk tier if files modified on target branch
+  if (branchName) {
+    try {
+      const baseBranch = process.env.BASE_BRANCH || "main";
+      const resolvedBase = resolveBase(projectRoot, baseBranch);
+      const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedBase}...${branchName}`], { cwd: projectRoot, raw: true, ignoreError: true }) || "";
+      const files = raw.split("\0").map(normalizePath).filter(Boolean);
+      if (files.length > 0) {
+        // The repository's own risk paths must apply here too, or the gate and
+        // the harvester classify the same branch differently.
+        let config = opts.config;
+        if (!config) {
+          try {
+            config = loadConfig(projectRoot);
+          } catch (_) {
+            config = {};
+          }
+        }
+        const tier = classifyRiskTier(files, { config });
+        if (tier.tier === RISK_TIERS.R3) {
+          return { safe: false, reason: `R3 Restricted Path violation: ${tier.reason}` };
+        }
+      }
+    } catch (_) {}
+  }
+
+  return { safe: true };
+}

package/src/ops/cli-intent.mjs

@@ -25,5 +25,6 @@ export function resolveWizardInteractivity(input = {}) {
   // to edit rather than as a complete invocation.
   if (input.interactive === true) return true;
   if (input.nonInteractive || input.yes || input.fullySpecified) return false;
+  if (input.isTTY === false || input.ci) return false;
   return undefined;
 }