jules-orchestrator-kit 0.9.3 → 0.9.4

package/README.md

@@ -58,6 +58,7 @@ sequenceDiagram
     
     box "Control Plane" #E8F4F8
         participant Orc as Orchestrator Core
+        participant Envelope as Task Envelope Validator
         participant Gate as Self-Audit Gatekeeper
     end
     
@@ -66,12 +67,19 @@ sequenceDiagram
         participant Git as Git Worktree Sandbox
     end
 
-    Trigger->>+Orc: Dispatch Task Payload
+    Trigger->>+Orc: Dispatch Task Payload / Envelope
     
-    note over Orc,Git: Phase 1: Security Redaction & Provisioning
-    Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
-    Orc->>+Git: Provision Isolation Sandbox (git worktree)
-    Git-->>-Orc: Sandbox Ready
+    note over Orc,Envelope: Phase 1: Pre-Flight Premise & Security Validation
+    Orc->>+Envelope: Validate Envelope (referenced_paths exist? base commit fresh?)
+    alt Premise Failure / Missing Referenced Paths / Stale Base
+        Envelope-->>Orc: Validation Failed (Premise Error)
+        Orc-->>Trigger: Abort Pre-Dispatch (Exit 1)
+    else Envelope Validated
+        Envelope-->>-Orc: Envelope Approved
+        Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
+        Orc->>+Git: Provision Isolation Sandbox (git worktree)
+        Git-->>-Orc: Sandbox Ready
+    end
     
     loop OODA Repair Cycle (Max 3 Retries)
         note over Orc,Git: Phase 2: Agent Execution & Dispatch
@@ -80,28 +88,29 @@ sequenceDiagram
         Git-->>-API: Changes Written
         API-->>-Orc: Execution Complete
         
-        note over Orc,Gate: Phase 3: Tiered Verification & Gatekeeping
+        note over Orc,Gate: Phase 3: Multi-Gate Verification & Risk Classification
         Orc->>+Gate: Trigger Self-Audit (trusted origin/main rules)
         
-        Gate->>+Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
-        Git-->>-Gate: Diff Stats & File List
+        Gate->>+Git: Run Scope, Payload & Stale-Base Audit (`git diff`)
+        Git-->>-Gate: Diff Stats & Base Commit Age
         
-        alt Scope Breach (Forbidden Path OR Diff Payload > 75 KB)
-            Gate-->>Orc: Security / Scope Violation Detected
+        alt Scope Breach / Payload > 75 KB / Stale Base > 25 commits
+            Gate-->>Orc: Security / Scope / Stale-Base Violation
             Orc->>Orc: Record Telemetry (metrics.jsonl)
             Orc-->>Trigger: Abort Execution (Exit 3)
-            break Fatal Security Error
+            break Fatal Security or Base Error
                 Orc->>Git: Teardown Worktree Sandbox
             end
-        else Scope Verification Passed
-            Gate->>+Git: Run Dynamic Verification (`testCmd` & `buildCmd`)
-            Git-->>-Gate: stdout / stderr verification results
+        else Static Scope & Base Passed
+            Gate->>Gate: Classify Risk Tier (R0 Cosmetic, R1 Routine, R2 Consequential, R3 Restricted)
+            Gate->>+Git: Run Integrity Checks (Asset Magic-Bytes, Rules Budget, testCmd & buildCmd)
+            Git-->>-Gate: Execution & Integrity Proof (stdout/stderr)
         end
 
-        alt 100% Verification Suite Passed
-            Gate-->>-Orc: Verification Success
+        alt 100% Verification Suite & Integrity Passed
+            Gate-->>-Orc: Verification Success + Risk Tier Metadata
             Orc->>+Git: Commit & Push to Remote Branch / PR
-            Git-->>-Orc: PR Ready
+            Git-->>-Orc: PR Ready (Attached Execution Receipts)
             Orc->>Orc: Record Telemetry (metrics.jsonl)
             Orc-->>Trigger: Dispatch Succeeded (Exit 0)
             break Task Completed
@@ -122,10 +131,12 @@ sequenceDiagram
 ```
 
 > 💡 **Core Architectural Invariants**:
+> - **Task Envelope Premise Validation**: Pre-flight checks verify referenced paths and base freshness before dispatching tasks to prevent session burnout.
+> - **Risk Tier Classification Engine (R0–R3)**: Classifies changes by blast radius to route auto-merge vs mandatory human review.
 > - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
+> - **Asset & Rules Integrity**: Guards binary assets against HTML corruption and enforces character/line budgets on rule files.
 > - **Automatic PII & Secret Redaction**: Outbound task prompts are automatically sanitized to redact API secrets and mask sensitive PII (emails, IPs, phone numbers).
 > - **Ledger Hash-Chain Integrity**: Hashing over JSONL event streams detects unauthorized log tampering or record deletions.
-> - **Dynamic Command Resolution (`command-resolver.mjs`)**: Auto-detects workspace boundaries (Turborepo, pnpm, Nx, Cargo, pytest, npm).
 >
 > 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
 

package/bin/agentctl.mjs

@@ -13,7 +13,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.9.0 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.9.4 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -22,6 +22,7 @@ Commands:
   gate | audit          Run CI security and verification gate against current branch
   queue                 Run pending task queue
   swarm                 Run parallel task swarm
+  mcp                   Start stdio Model Context Protocol (MCP) server
   clean                 Clean stale branches, worktrees, locks, and ledgers
   lock <action>         Manage mutex locks (acquire | release | status | cleanup)
   doctor                Run system diagnostics and stack resolution checks
@@ -42,7 +43,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.9.0");
+    console.log("agentctl v0.9.4");
     process.exit(0);
   }
 
@@ -261,6 +262,12 @@ base_branch: main
       break;
     }
 
+    case "mcp": {
+      const { startMcpServer } = await import("../src/mcp.mjs");
+      startMcpServer();
+      break;
+    }
+
     default:
       console.error(`Unknown command: ${command}`);
       printHelp();

package/bin/mcp-server.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { startMcpServer } from "../src/mcp.mjs";
+
+startMcpServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
@@ -14,7 +14,9 @@
   "bin": {
     "agentctl": "bin/agentctl.mjs",
     "jules-init": "bin/init.js",
-    "jules-orchestrator-kit": "bin/agentctl.mjs"
+    "jules-orchestrator-kit": "bin/agentctl.mjs",
+    "jules-mcp": "bin/mcp-server.mjs",
+    "agentctl-mcp": "bin/mcp-server.mjs"
   },
   "main": "index.mjs",
   "exports": {

package/src/mcp.mjs

@@ -0,0 +1,211 @@
+import { createInterface } from "node:readline";
+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.9.4",
+};
+
+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; // Notifications produce no response
+  }
+
+  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 rl = createInterface({ input, output: null, terminal: false });
+
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    try {
+      const request = JSON.parse(trimmed);
+      const response = await handleMcpRequest(request, opts);
+      if (response !== null) {
+        output.write(JSON.stringify(response) + "\n");
+      }
+    } catch (err) {
+      output.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: `Parse error: ${err.message}` },
+        }) + "\n"
+      );
+    }
+  });
+}

package/src/state.mjs

@@ -98,10 +98,18 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
   }
 }
 
+export class BudgetError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BudgetError";
+    this.code = 7;
+  }
+}
+
 export async function withBudget(fn, root = resolveRoot(), limit = 300) {
   const budget = checkDailyBudget(root, limit);
   if (!budget.ok) {
-    throw new Error(`Daily budget exhausted (${budget.used}/${budget.budget} tasks executed)`);
+    throw new BudgetError(`Daily budget exhausted (${budget.used}/${budget.budget} tasks executed)`);
   }
   return fn();
 }