jules-orchestrator-kit 0.24.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +143 -255
- package/bin/agentctl.mjs +3 -3
- package/index.mjs +1 -1
- package/package.json +7 -11
- package/src/mcp.mjs +1 -1
- package/.agent/jules-queue/README.md +0 -30
- package/.agent/jules.yml +0 -13
- package/.env.example +0 -73
- package/.github/workflows/jules-audit.yml +0 -49
package/README.md
CHANGED
|
@@ -7,314 +7,202 @@
|
|
|
7
7
|
[](https://opensource.org/licenses/MIT)
|
|
8
8
|
[](https://nodejs.org)
|
|
9
9
|
|
|
10
|
-
> **
|
|
11
|
-
> Built specifically to execute 300+ daily agent sessions and parallel swarms safely
|
|
10
|
+
> **Zero-dependency safety kernel for autonomous AI agent swarms.**
|
|
11
|
+
> Built specifically to execute 300+ daily agent sessions and parallel swarms safely with zero external runtime dependencies. Built strictly on native Node.js 20+ ESM standard library.
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
## 🏗️ Architecture Layer Diagram
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
===================================================================================
|
|
19
|
+
JULES ORCHESTRATOR KIT — ARCHITECTURE LAYERS
|
|
20
|
+
===================================================================================
|
|
21
|
+
|
|
22
|
+
+-------------------------------------------------------------------------------+
|
|
23
|
+
| GOVERNANCE PLANE |
|
|
24
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
25
|
+
| | Scope Guard | | Secret Scanner | | Risk Classifier | |
|
|
26
|
+
| | (builtin & custom) | | (entropy > 3.6b) | | (R0 Cosmetic - R3 Restr)| |
|
|
27
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
28
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
29
|
+
| | Prompt Firewall | | Dynamic Guardrails | | Flaky Test Quarantine | |
|
|
30
|
+
| | (injection strip) | | (rule budget sync) | | (Wilson CI / Exit 8) | |
|
|
31
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
32
|
+
+----------------------------------------+--------------------------------------+
|
|
33
|
+
|
|
|
34
|
+
v
|
|
35
|
+
+-------------------------------------------------------------------------------+
|
|
36
|
+
| EXECUTION PLANE |
|
|
37
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
38
|
+
| | Agent Envelope | | Task DAG Engine | | OODA Auto-Repair | |
|
|
39
|
+
| | (sanitized payload)| | (Kahn's / Fingerpr)| | (3-strike thrash guard) | |
|
|
40
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
41
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
42
|
+
| | Process Group Mgr | | Hermetic Net Guard | | 3-Way Structural Merger | |
|
|
43
|
+
| | (detached / SIGKILL| | (ERR_UNMOCKED_NET) | | (AST/JSON & block diff) | |
|
|
44
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
45
|
+
+----------------------------------------+--------------------------------------+
|
|
46
|
+
|
|
|
47
|
+
v
|
|
48
|
+
+-------------------------------------------------------------------------------+
|
|
49
|
+
| KERNEL PLANE |
|
|
50
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
51
|
+
| | VFS Mutex | | Telemetry Spine | | Stdio MCP Stream | |
|
|
52
|
+
| | (linearizable CAS) | | (O(1) SHA-256 chain)| | (Content-Length 4MB) | |
|
|
53
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
54
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
55
|
+
| | Intent Journal | | Worktree Reaper | | Atomic Budget Ledger | |
|
|
56
|
+
| | (append-only sync) | | (zombie PID prune) | | (sliding window / proc) | |
|
|
57
|
+
| +--------------------+ +--------------------+ +-------------------------+ |
|
|
58
|
+
+-------------------------------------------------------------------------------+
|
|
59
|
+
===================================================================================
|
|
60
|
+
```
|
|
16
61
|
|
|
17
62
|
---
|
|
18
63
|
|
|
19
|
-
## ⚡
|
|
64
|
+
## ⚡ Quick Start Guide
|
|
65
|
+
|
|
66
|
+
### 1. Command Line Interface (`agentctl`)
|
|
20
67
|
|
|
21
|
-
|
|
68
|
+
Install globally or run via `npx`:
|
|
22
69
|
|
|
23
70
|
```bash
|
|
24
|
-
#
|
|
25
|
-
npx
|
|
71
|
+
# Initialize orchestrator structure and configuration in target project
|
|
72
|
+
npx agentctl init
|
|
26
73
|
|
|
27
|
-
#
|
|
74
|
+
# Dispatch an autonomous coding task (Dry-run mode for local simulation)
|
|
28
75
|
JULES_DRY_RUN=1 npx agentctl dispatch \
|
|
29
|
-
--title "
|
|
76
|
+
--title "Implement JWT Validator" \
|
|
30
77
|
--prompt "Implement JWT validation middleware with unit tests"
|
|
31
78
|
|
|
32
|
-
#
|
|
79
|
+
# Run the 4-phase security and verification gatekeeper against current workspace
|
|
33
80
|
npx agentctl gate
|
|
34
81
|
|
|
35
|
-
#
|
|
36
|
-
npx agentctl
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
> 📖 **Looking for production deployment patterns?**
|
|
40
|
-
> Check out [**EXAMPLES.md**](./EXAMPLES.md) for 6 real-world recipes (Nightly TODO Scanner, Composite CI Action, Multi-Worktree Swarms, OODA Auto-Fix, MCP IDE setup, and Specialist Rosters).
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## 🎯 Why jules-orchestrator-kit?
|
|
45
|
-
|
|
46
|
-
Whether you are dispatching your first automated coding task or managing high-throughput CI/CD swarms across large engineering teams, `jules-orchestrator-kit` provides total operational safety:
|
|
47
|
-
|
|
48
|
-
| Feature | 🐣 For Rookies & Beginners | 🛠️ For Senior Developers & Infrastructure Engineers |
|
|
49
|
-
| :--- | :--- | :--- |
|
|
50
|
-
| **Safety First** | Never breaks `main` branch or pushes failing code. | 4-Phase Safety Gatekeeper fails closed on scope drift, high entropy secrets, or test regressions. |
|
|
51
|
-
| **Token Budget Protection** | Prevents runaway loops from burning API quotas. | Sliding-window OODA thrash detector ($A \rightarrow B \rightarrow A \rightarrow B$) halts non-convergent repair cycles automatically. |
|
|
52
|
-
| **Zero Setup Hassle** | Works out of the box with standard `npm test`. | **Zero External Runtime Dependencies** (`node:fs`, `node:path`, `node:crypto`, `node:child_process`). |
|
|
53
|
-
| **Multi-Agent Swarms** | Run multiple tasks simultaneously without conflict. | Deterministic VFS mutex and 3-way structural merge engine resolve parallel worktree changes cleanly. |
|
|
54
|
-
| **IDE & Tooling** | Seamlessly connects to your favorite editor. | Native Model Context Protocol (MCP) server over memory-bounded stdio streams. |
|
|
55
|
-
|
|
56
|
-
---
|
|
57
|
-
|
|
58
|
-
<details open>
|
|
59
|
-
<summary><b>⚙️ Control Plane Architecture & Deep Dive</b></summary>
|
|
60
|
-
|
|
61
|
-
<br/>
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
<br/>
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
### Engine System Highlights
|
|
70
|
-
|
|
71
|
-
- **Native Task DAG Executor (`src/dag-engine.mjs`)**: Zero-dependency `DagExecutor` with Kahn's topological sort algorithm, SHA-256 interface fingerprinting post-task execution, and pre-execution cycle detection (`DagCycleError`).
|
|
72
|
-
- **Intent Journaling & Zombie Worktree Reaper (`src/journal.mjs`)**: Automatic boot-time scan (`reapOrphanedIntents`) in `agentctl` and MCP server that tracks git operations in `.agent/state/journal.jsonl` and prunes orphaned worktrees left by crashed/recycled processes.
|
|
73
|
-
- **Hermetic Network Egress Guard (`src/preload-net-guard.mjs`)**: Intercepts and blocks unmocked outbound HTTP/HTTPS egress during test execution (`NODE_OPTIONS="--import ./src/preload-net-guard.mjs"`), enforcing hermetic testing while allowing local loopback (`localhost`, `127.0.0.1`).
|
|
74
|
-
- **Linearizable VFS Mutex (`src/state.mjs`)**: Kernel-level directory mutex (`withVfsMutex`) guaranteeing serial linearizability for SHA-256 hash-chained session ledgers with atomic budget reservation (`reserveBudgetAtomic`).
|
|
75
|
-
- **PID Recycling & Stale Lock Protection (`src/state.mjs`)**: Linux `/proc/<pid>/stat` launch-time validation and random UUID nonces prevent false-positive lock reaps from recycled OS process IDs.
|
|
76
|
-
- **Memory-Bounded Content-Length MCP Streaming (`src/mcp.mjs`)**: Native MCP server over stdio streams using `McpFrameDecoder` with a 4 MB memory safety ceiling and panic boundaries to prevent stdout stack trace leaks.
|
|
77
|
-
- **Process Group Isolation (`src/process-group.mjs`)**: `ProcessGroupManager` creates isolated process groups (`detached: true`) and catches `SIGINT`/`SIGTERM`/`exit` signals to execute `process.kill(-pgid)`, guaranteeing zero zombie processes.
|
|
78
|
-
- **TOCTOU & Symlink Defense (`src/security.mjs`)**: `safeAtomicWrite()` uses `O_CREAT | O_EXCL | O_WRONLY` temp files with `fsyncSync` + `renameSync` and `lstatSync`/`realpathSync` symlink checks.
|
|
79
|
-
- **3-Way Structural AST/JSON Merge (`scripts/jules-merge-swarm.mjs`)**: Pure Node `deepMerge3Way()` algorithm for recursive object and array merges executed in isolated temporary directories (`os.tmpdir()`).
|
|
80
|
-
|
|
81
|
-
</details>
|
|
82
|
-
|
|
83
|
-
<details>
|
|
84
|
-
<summary><b>🛡️ Zero-Trust Security Gatekeeper</b></summary>
|
|
85
|
-
|
|
86
|
-
<br/>
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
### The 4-Phase Safety Audit & Security Boundary (`agentctl gate`)
|
|
91
|
-
|
|
92
|
-
1. **Scope Fencing (`forbidden_paths`)**: Ensures agents cannot modify protected files (`package.json`, `.github/`, deployment keys) without explicit overrides.
|
|
93
|
-
2. **Diff Payload Governor**: Rejects oversized diffs (> 75 KB) to prevent truncation and hidden payload injections.
|
|
94
|
-
3. **Secret Entropy Scanner**: Scans diffs for high-confidence secrets (AWS keys, Stripe keys, GitHub tokens, SSH private keys) using Shannon Entropy analysis (> 3.6 bits).
|
|
95
|
-
4. **Trusted Verification Suite**: Executes auto-detected unit tests and linters (`npm test`) inside a hermetic network sandbox to guarantee zero regressions before merging.
|
|
96
|
-
5. **Prompt Guard Boundary (`src/prompt-guard.mjs`)**: `sanitizeUntrustedData` strips bidi control characters, ANSI escape sequences, zero-width unicode, and neutralizes prompt injection tags (`<|im_start|>`, `[INST]`).
|
|
97
|
-
6. **MCP Stream Isolation (`src/mcp.mjs`)**: Seals `process.stdout.write` framing stream to prevent log output from corrupting JSON-RPC stdio frames.
|
|
98
|
-
|
|
99
|
-
> [!NOTE]
|
|
100
|
-
> All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
|
|
101
|
-
|
|
102
|
-
</details>
|
|
103
|
-
|
|
104
|
-
<details>
|
|
105
|
-
<summary><b>🔌 Model Context Protocol (MCP) & IDE Integration</b></summary>
|
|
106
|
-
|
|
107
|
-
<br/>
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
### Connecting to Claude Desktop, Cursor, or Antigravity
|
|
112
|
-
|
|
113
|
-
Start the native stdio MCP server:
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
npx agentctl mcp
|
|
82
|
+
# Launch parallel multi-agent swarm in isolated git worktrees
|
|
83
|
+
npx agentctl swarm
|
|
117
84
|
```
|
|
118
85
|
|
|
119
|
-
|
|
120
|
-
- `dispatch_jules_task`: Dispatch autonomous coding tasks directly from your LLM prompt.
|
|
121
|
-
- `audit_jules_gate`: Execute the 4-phase safety gate against the workspace.
|
|
122
|
-
- `check_risk_tier`: Classify workspace changes into Risk Tiers (R0 Cosmetic to R3 Restricted).
|
|
123
|
-
- `get_jules_status`: Fetch real-time status of active, pending, and completed tasks.
|
|
86
|
+
### 2. Model Context Protocol (MCP) Client Configuration (`agentctl-mcp`)
|
|
124
87
|
|
|
125
|
-
|
|
88
|
+
Connect `jules-orchestrator-kit` directly to **Claude Desktop**, **Cursor IDE**, or **Antigravity IDE** via native stdio MCP framing.
|
|
126
89
|
|
|
127
|
-
|
|
128
|
-
<summary><b>🤖 Specialist Agent Prompt Presets (.agent/prompts/)</b></summary>
|
|
90
|
+
#### Claude Desktop Configuration (`claude_desktop_config.json`)
|
|
129
91
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
# Example: Dispatch a cleanup task using the Janitor preset
|
|
143
|
-
npx agentctl dispatch \
|
|
144
|
-
--prompt "$(cat .agent/prompts/Janitor.md) Prune unused helper methods in src/utils.mjs"
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"jules-orchestrator": {
|
|
96
|
+
"command": "npx",
|
|
97
|
+
"args": ["agentctl-mcp"],
|
|
98
|
+
"env": {
|
|
99
|
+
"JULES_API_KEY": "YOUR_JULES_API_KEY"
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
145
104
|
```
|
|
146
105
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
action: 'gate'
|
|
162
|
-
base_branch: 'main'
|
|
163
|
-
tier: 'ultra'
|
|
164
|
-
env:
|
|
165
|
-
JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
|
|
106
|
+
#### Cursor / VS Code MCP Configuration (`.vscode/mcp.json`)
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"mcpServers": {
|
|
111
|
+
"agentctl-mcp": {
|
|
112
|
+
"command": "npx",
|
|
113
|
+
"args": ["-y", "jules-orchestrator-kit", "mcp"],
|
|
114
|
+
"env": {
|
|
115
|
+
"JULES_API_KEY": "YOUR_JULES_API_KEY"
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
166
120
|
```
|
|
167
121
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
<details>
|
|
171
|
-
<summary><b>🛠️ CLI Command Reference (`agentctl`)</b></summary>
|
|
172
|
-
|
|
173
|
-
<br/>
|
|
174
|
-
|
|
175
|
-
| Command | Usage Example | Description |
|
|
176
|
-
| :--- | :--- | :--- |
|
|
177
|
-
| **`init`** | `npx agentctl init` | Initializes `.agent/` configuration, workflows, and task queue directory |
|
|
178
|
-
| **`dispatch`** | `agentctl dispatch --title "Fix Bug" --prompt "..."` | Dispatches an autonomous task to Google Jules |
|
|
179
|
-
| **`gate`** | `agentctl gate [--fix] [--base main]` | Runs 4-phase safety gatekeeper audit against workspace |
|
|
180
|
-
| **`queue`** | `agentctl queue` | Processes pending task queue sequentially from `.agent/jules-queue/` |
|
|
181
|
-
| **`swarm`** | `agentctl swarm` | Launches parallel multi-agent swarm in isolated git worktrees |
|
|
182
|
-
| **`merge-swarm`** | `agentctl merge-swarm` | Performs 3-way structural merge on completed swarm PRs |
|
|
183
|
-
| **`mcp`** | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) JSON-RPC 2.0 server |
|
|
184
|
-
| **`doctor`** | `agentctl doctor` | Verifies stack configuration, environment keys, and daily token budget |
|
|
185
|
-
| **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
|
|
186
|
-
| **`clean`** | `agentctl clean` | Audits and cleans up stale git worktrees, orphaned intents, locks, and temporary state files |
|
|
187
|
-
|
|
188
|
-
</details>
|
|
189
|
-
|
|
190
|
-
<details>
|
|
191
|
-
<summary><b>💳 Subscription Tier Presets (Free / Pro / Ultra)</b></summary>
|
|
192
|
-
|
|
193
|
-
<br/>
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
<br/>
|
|
198
|
-
|
|
199
|
-
Tailor session limits and rate-limiting behavior to your Google Jules API subscription tier:
|
|
200
|
-
|
|
201
|
-
| Tier | `dailyTasks` | `repairAttempts` | `concurrency` | `staggerMs` | Target Usage |
|
|
202
|
-
| :--- | :---: | :---: | :---: | :---: | :--- |
|
|
203
|
-
| **`free`** | `15` | `1` | `1` | `3000 ms` | **Hobby / Free Tier:** Conserves quota, prevents HTTP 429 rate limits. |
|
|
204
|
-
| **`pro`** | `100` | `2` | `2` | `1500 ms` | **Developer Pro:** Balanced throughput for everyday work. |
|
|
205
|
-
| **`ultra`** *(default)* | `300` | `3` | `3` | `1000 ms` | **Swarm / Enterprise:** Maximum parallel throughput & CI/CD. |
|
|
206
|
-
|
|
207
|
-
**How to activate:**
|
|
208
|
-
- **Environment Variable:** `export JULES_TIER=free` (or set in `.env`)
|
|
209
|
-
- **Config File (`.agent/jules.yml`):** Set `tier: free`
|
|
210
|
-
|
|
211
|
-
</details>
|
|
212
|
-
|
|
213
|
-
<details>
|
|
214
|
-
<summary><b>📝 Configuration Reference (`.agent/jules.yml`)</b></summary>
|
|
122
|
+
---
|
|
215
123
|
|
|
216
|
-
|
|
124
|
+
## 📝 Configuration Reference (`.agent/config.yml`)
|
|
217
125
|
|
|
218
|
-
|
|
126
|
+
The orchestrator reads configuration from `.agent/config.yml` (or legacy `.agent/jules.yml`). Scaffolded automatically via `agentctl init`:
|
|
219
127
|
|
|
220
128
|
```yaml
|
|
129
|
+
# Google Jules Repository Configuration
|
|
221
130
|
version: 2
|
|
222
|
-
tier: "
|
|
131
|
+
tier: "ultra" # Preset options: free, pro, ultra (default: ultra)
|
|
132
|
+
provider: "jules"
|
|
133
|
+
|
|
134
|
+
# Automated verification suite commands (auto-detected if omitted)
|
|
223
135
|
test_cmd: "npm test"
|
|
224
136
|
build_cmd: "npm run build"
|
|
137
|
+
|
|
138
|
+
# Scope protection boundaries (builtin protections are automatically merged)
|
|
225
139
|
forbidden_paths:
|
|
226
|
-
- ".github
|
|
140
|
+
- ".github/**"
|
|
227
141
|
- "package.json"
|
|
142
|
+
- ".agent/config.yml"
|
|
228
143
|
- ".agent/jules.yml"
|
|
144
|
+
|
|
229
145
|
allow_paths: []
|
|
146
|
+
|
|
147
|
+
# Operational limits & budgets
|
|
230
148
|
limits:
|
|
231
|
-
dailyTasks: 300
|
|
232
|
-
repairAttempts: 3
|
|
233
|
-
diffKb: 75
|
|
149
|
+
dailyTasks: 300 # Maximum agent tasks per 24-hour cycle window
|
|
150
|
+
repairAttempts: 3 # Maximum OODA auto-repair retries on test failure
|
|
151
|
+
diffKb: 75 # Git diff payload ceiling in KB (Governor)
|
|
152
|
+
concurrency: 3 # Maximum parallel worktree swarm workers
|
|
153
|
+
staggerMs: 1000 # Dispatch stagger delay in milliseconds
|
|
234
154
|
```
|
|
235
155
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
<details>
|
|
239
|
-
<summary><b>🚦 Exit Code Registry & Troubleshooting</b></summary>
|
|
156
|
+
---
|
|
240
157
|
|
|
241
|
-
|
|
158
|
+
## 🚦 Exit Code Reference Table
|
|
242
159
|
|
|
243
|
-
Standardized exit codes enforced across all CLI
|
|
160
|
+
Standardized exit codes enforced across all CLI commands (`agentctl`), scripts, and CI/CD pipelines:
|
|
244
161
|
|
|
245
|
-
| Exit Code |
|
|
162
|
+
| Exit Code | Classification | Description & Immediate Remediation Action |
|
|
246
163
|
| :---: | :--- | :--- |
|
|
247
|
-
| `0` | **Success** |
|
|
248
|
-
| `1` | **
|
|
249
|
-
| `2` | **API / Network Failure** | Jules API rate-limit
|
|
250
|
-
| `3` | **Scope Violation** | Attempted modification of
|
|
251
|
-
| `4` | **
|
|
252
|
-
| `5` | **Diff Payload
|
|
253
|
-
| `6` | **Secret
|
|
254
|
-
| `7` | **Budget Exhausted** | Daily task session quota limit reached (`limits.dailyTasks`, default 300). |
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
<details>
|
|
259
|
-
<summary><b>🔐 Environment Variables Reference</b></summary>
|
|
260
|
-
|
|
261
|
-
<br/>
|
|
262
|
-
|
|
263
|
-
| Variable | Description | Default |
|
|
264
|
-
| :--- | :--- | :--- |
|
|
265
|
-
| `JULES_API_KEY` | Google Jules REST API key | *(none)* |
|
|
266
|
-
| `JULES_REPO` | Target GitHub Repository (`owner/repo`) | Auto-detected from `git remote` |
|
|
267
|
-
| `JULES_TIER` | Subscription tier preset (`free`, `pro`, `ultra`) | `ultra` |
|
|
268
|
-
| `JULES_DRY_RUN` | Set to `1` or `true` for dry-run simulation mode | `false` |
|
|
269
|
-
| `JULES_DAILY_BUDGET` | Custom daily session budget limit | `300` |
|
|
270
|
-
| `JULES_MAX_DIFF_KB` | Custom git diff payload limit in KB | `75` |
|
|
271
|
-
| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Allow PR changes to command files (`package.json`, etc.) | `false` |
|
|
272
|
-
| `JULES_ALLOW_AGENT_RULE_CHANGES` | Allow PR changes to agent rule files (`AGENTS.md`, etc.) | `false` |
|
|
273
|
-
| `BASE_BRANCH` | Base branch for PR Audits & Merge-Base checks | `main` |
|
|
274
|
-
| `NO_COLOR` | Set to `true` to disable ANSI color output | `false` |
|
|
275
|
-
|
|
276
|
-
</details>
|
|
277
|
-
|
|
278
|
-
<details>
|
|
279
|
-
<summary><b>🌐 Supported Tech Stacks & Auto-Detection</b></summary>
|
|
280
|
-
|
|
281
|
-
<br/>
|
|
282
|
-
|
|
283
|
-
The orchestrator automatically infers verification and build commands across ecosystems:
|
|
284
|
-
|
|
285
|
-
| Stack / Ecosystem | Manifest File | Inferred Test Command | Inferred Build Command |
|
|
286
|
-
| :--- | :--- | :--- | :--- |
|
|
287
|
-
| **Turborepo** | `turbo.json` | `npx turbo run test` | `npx turbo run build` |
|
|
288
|
-
| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm test` | `pnpm build` |
|
|
289
|
-
| **Nx Workspace** | `nx.json` | `npx nx run-many -t test` | `npx nx run-many -t build` |
|
|
290
|
-
| **JavaScript / TypeScript** | `package.json` | `npm test` | `npm run build` |
|
|
291
|
-
| **Rust** | `Cargo.toml` | `cargo test --workspace` | `cargo build` |
|
|
292
|
-
| **Go** | `go.mod` | `go test ./...` | `go build ./...` |
|
|
293
|
-
| **Python** | `pyproject.toml` | `pytest` | *(none)* |
|
|
294
|
-
| **Bun / Deno** | `bunfig.toml` / `deno.json` | `bun test` / `deno test` | `bun run build` |
|
|
295
|
-
| **Elixir / Ruby** | `mix.exs` / `Gemfile` | `mix test` / `rake test` | *(standard build)* |
|
|
296
|
-
| **Java / C / C++** | `pom.xml` / `Makefile` | `mvn test` / `make test` | `mvn compile` / `make` |
|
|
297
|
-
|
|
298
|
-
</details>
|
|
164
|
+
| `0` | **Gate Approved / Success** | Verification suite passed; task, audit, or gate operation completed cleanly. |
|
|
165
|
+
| `1` | **Git Base / Config Error** | Pre-dispatch argument error, missing git repository root, invalid prompt (>50 KB), or bad configuration. |
|
|
166
|
+
| `2` | **API / Network Failure** | Jules REST API HTTP 429 rate-limit, `FAILED_PRECONDITION` quota limit, or connection timeout. |
|
|
167
|
+
| `3` | **Scope Guard Violation** | Attempted modification of protected/forbidden files (`package.json`, `.github/`, deployment keys). |
|
|
168
|
+
| `4` | **Verification Failure** | Unit test or build command failed after 3 OODA auto-repair attempts or hit non-convergent loop. |
|
|
169
|
+
| `5` | **Diff Payload Governor** | Post-change git diff exceeded maximum payload budget (`limits.diffKb`, default >75 KB limit). |
|
|
170
|
+
| `6` | **Secret Scanner Finding** | High-confidence secret, API token, or SSH private key detected in diff (Shannon entropy > 3.6 bits). |
|
|
171
|
+
| `7` | **Budget Exhausted** | Daily task session quota limit reached (`limits.dailyTasks`, default 300 per 24h cycle). |
|
|
172
|
+
| `8` | **FLAKY_QUARANTINE** | Statistical test flakiness detected (oscillation >= 0.4, Wilson CI); OODA repair suppressed. |
|
|
173
|
+
| `124` | **Execution Timeout** | Subprocess execution exceeded hard execution timeout limit (default 10 minutes). |
|
|
174
|
+
| `188` | **ERR_UNMOCKED_NET** | Unmocked outbound HTTP/HTTPS egress intercepted during test execution by hermetic network guard. |
|
|
299
175
|
|
|
300
176
|
---
|
|
301
177
|
|
|
302
|
-
##
|
|
178
|
+
## 🛡️ Security Model & Honest Boundaries
|
|
303
179
|
|
|
304
|
-
|
|
180
|
+
### Security Guarantees
|
|
305
181
|
|
|
306
|
-
1. **Zero
|
|
307
|
-
2. **
|
|
308
|
-
3. **
|
|
182
|
+
1. **Zero-Trust Scope Fencing**: Scope guard enforces strict forbidden path lists (`.github/`, credentials, agent rules). User additions complement builtin rules without override vulnerabilities.
|
|
183
|
+
2. **Shannon Entropy Secret Scanner**: Scans diffs for high-confidence secrets (AWS, Stripe, GitHub tokens, RSA private keys) using Shannon Entropy analysis (> 3.6 bits).
|
|
184
|
+
3. **Hermetic Network Guard (`ERR_UNMOCKED_NET`)**: Intercepts unmocked outbound HTTP/HTTPS egress during verification runs (`node:http`, `node:https`, `fetch`), enforcing offline-first hermetic execution while permitting local loopback.
|
|
185
|
+
4. **Prompt Firewall (`src/prompt-guard.mjs`)**: Neutralizes prompt injection patterns, strips zero-width unicode, bidi control characters, and ANSI escape codes before payloads reach LLM context boundaries.
|
|
186
|
+
5. **Linearizable VFS Directory Mutex (`src/state.mjs`)**: CAS directory mutex guarantees serial linearizability across multi-process swarms. Process start time validation against `/proc/<pid>/stat` prevents stale lock corruption from recycled OS process IDs.
|
|
187
|
+
6. **O(1) SHA-256 Telemetry Hash-Spine (`src/telemetry.mjs`)**: Cryptographically links all session events in an append-only ledger with automatic head-desync self-healing.
|
|
188
|
+
|
|
189
|
+
### Honest System Boundaries
|
|
190
|
+
|
|
191
|
+
- **Zero External Dependencies**: The orchestrator core uses **100% native Node.js ESM modules** (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:stream`). No supply-chain dependency risk.
|
|
192
|
+
- **Diff Governor Envelope Ceiling**: Hard diff payload limit of 75 KB prevents hidden payload injection and API payload truncation.
|
|
193
|
+
- **Process Subtree Cleanup**: `ProcessGroupManager` creates detached process groups and handles system termination signals (`SIGINT`/`SIGTERM`) to kill whole subtrees, guaranteeing zero zombie processes.
|
|
194
|
+
- **Rule Verification Scope**: Security checks are evaluated strictly against `origin/main` baseline to prevent untrusted PR branches from modifying their own guardrails.
|
|
195
|
+
|
|
196
|
+
---
|
|
309
197
|
|
|
310
|
-
|
|
198
|
+
## 🤝 Contributing & Testing
|
|
311
199
|
|
|
312
200
|
```bash
|
|
313
|
-
# Clone
|
|
201
|
+
# Clone repository
|
|
314
202
|
git clone https://github.com/FullThrottle83/jules-orchestrator-kit.git
|
|
315
203
|
cd jules-orchestrator-kit
|
|
316
204
|
|
|
317
|
-
# Run ESLint
|
|
205
|
+
# Run ESLint and comprehensive unit test suite
|
|
318
206
|
npm run lint
|
|
319
207
|
npm test
|
|
320
208
|
```
|
package/bin/agentctl.mjs
CHANGED
|
@@ -14,7 +14,7 @@ const command = args[0];
|
|
|
14
14
|
|
|
15
15
|
function printHelp() {
|
|
16
16
|
console.log(`
|
|
17
|
-
🚀 agentctl
|
|
17
|
+
🚀 agentctl v1.0.0 — Universal Agent Orchestrator & Safety Gatekeeper
|
|
18
18
|
|
|
19
19
|
Usage: agentctl <command> [options]
|
|
20
20
|
|
|
@@ -44,7 +44,7 @@ async function main() {
|
|
|
44
44
|
}
|
|
45
45
|
|
|
46
46
|
if (command === "version" || command === "--version" || command === "-v") {
|
|
47
|
-
console.log("agentctl
|
|
47
|
+
console.log("agentctl v1.0.0");
|
|
48
48
|
process.exit(0);
|
|
49
49
|
}
|
|
50
50
|
|
|
@@ -226,7 +226,7 @@ async function main() {
|
|
|
226
226
|
}
|
|
227
227
|
|
|
228
228
|
case "doctor": {
|
|
229
|
-
console.log(`\n🔍 agentctl System Diagnostics (
|
|
229
|
+
console.log(`\n🔍 agentctl System Diagnostics (v1.0.0)`);
|
|
230
230
|
console.log(`--------------------------------------------------`);
|
|
231
231
|
console.log(` Project Root : ${root}`);
|
|
232
232
|
console.log(` Config File : ${config._file || "None (Using defaults)"}`);
|
package/index.mjs
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "jules-orchestrator-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Orchestration kit for running Google Jules autonomous agents.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -23,20 +23,16 @@
|
|
|
23
23
|
".": "./index.mjs"
|
|
24
24
|
},
|
|
25
25
|
"files": [
|
|
26
|
-
"index.mjs",
|
|
27
|
-
"src/",
|
|
28
26
|
"bin/",
|
|
27
|
+
"src/",
|
|
29
28
|
"scripts/",
|
|
30
|
-
".
|
|
29
|
+
"index.mjs",
|
|
30
|
+
"LICENSE",
|
|
31
|
+
"README.md",
|
|
32
|
+
"JULES_RULES_TEMPLATE.md",
|
|
31
33
|
".agent/rules/",
|
|
32
34
|
".agent/prompts/",
|
|
33
|
-
".agent/workflows/"
|
|
34
|
-
".agent/jules-queue/README.md",
|
|
35
|
-
".github/workflows/jules-audit.yml",
|
|
36
|
-
".env.example",
|
|
37
|
-
"JULES_RULES_TEMPLATE.md",
|
|
38
|
-
"README.md",
|
|
39
|
-
"LICENSE"
|
|
35
|
+
".agent/workflows/"
|
|
40
36
|
],
|
|
41
37
|
"scripts": {
|
|
42
38
|
"init": "node bin/init.js",
|
package/src/mcp.mjs
CHANGED
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
# Jules Task Queue Directory
|
|
2
|
-
|
|
3
|
-
Drop markdown task specification files here (e.g. `TASK-001-feature-name.md`) to queue tasks for background execution by Google Jules.
|
|
4
|
-
|
|
5
|
-
### File Format Example
|
|
6
|
-
|
|
7
|
-
```markdown
|
|
8
|
-
# TASK-001: Implement User Rate Limiting
|
|
9
|
-
|
|
10
|
-
## Objective
|
|
11
|
-
Implement sliding window rate limiting for public API routes.
|
|
12
|
-
|
|
13
|
-
## Execution Rules
|
|
14
|
-
- Use Redis / memory store for tracking hit counts.
|
|
15
|
-
- Must return HTTP 429 Too Many Requests when limit is exceeded.
|
|
16
|
-
- Must pass `npm test` before submitting PR.
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
Process all queued tasks in batch:
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
agentctl queue
|
|
23
|
-
# or npm run jules:queue
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Or dispatch a single task using `agentctl dispatch`:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
agentctl dispatch --title "TASK-001 Rate Limiting" --prompt "$(cat .agent/jules-queue/TASK-001-rate-limiting.md)"
|
|
30
|
-
```
|
package/.agent/jules.yml
DELETED
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
# Google Jules Repository Configuration (Version 2)
|
|
2
|
-
version: 2
|
|
3
|
-
test_cmd: "npm test"
|
|
4
|
-
build_cmd: ""
|
|
5
|
-
forbidden_paths:
|
|
6
|
-
- ".github/**"
|
|
7
|
-
- "**/secrets/**"
|
|
8
|
-
- "**/*.pem"
|
|
9
|
-
- "**/lock-manager/**"
|
|
10
|
-
- "scripts/jules-self-audit.mjs"
|
|
11
|
-
- ".agent/jules.yml"
|
|
12
|
-
allow_paths: []
|
|
13
|
-
|
package/.env.example
DELETED
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
# Google Jules Orchestration Kit - Environment Configuration Example
|
|
2
|
-
# Copy this file to .env and populate with your credentials/settings.
|
|
3
|
-
|
|
4
|
-
# --- Authentication & Core Settings ---
|
|
5
|
-
# Google Jules API Key (Required for direct REST API dispatches)
|
|
6
|
-
JULES_API_KEY=your_google_jules_api_key_here
|
|
7
|
-
|
|
8
|
-
# Alias for API key (fallback if JULES_API_KEY is not set)
|
|
9
|
-
# GEMINI_API_KEY=your_gemini_api_key_here
|
|
10
|
-
|
|
11
|
-
# Override the Jules REST API URL
|
|
12
|
-
# JULES_API_URL=https://jules.googleapis.com/v1alpha/sessions
|
|
13
|
-
|
|
14
|
-
# Target GitHub Repository (Format: owner/repo)
|
|
15
|
-
JULES_REPO=owner/repo
|
|
16
|
-
|
|
17
|
-
# Set to "true" or "1" to run in repoless/serverless mode
|
|
18
|
-
# JULES_REPOLESS=false
|
|
19
|
-
|
|
20
|
-
# Enable Dry-Run mode to simulate payload dispatch without making API calls
|
|
21
|
-
# JULES_DRY_RUN=false
|
|
22
|
-
|
|
23
|
-
# --- Budget & Security Gatekeeper ---
|
|
24
|
-
# Daily max session limit for autonomous dispatches (Default: 300)
|
|
25
|
-
# JULES_DAILY_BUDGET=300
|
|
26
|
-
|
|
27
|
-
# Allow modifications to command-defining files (package.json, Cargo.toml, etc.) in PRs (Default: false)
|
|
28
|
-
# JULES_ALLOW_COMMAND_FILE_CHANGES=false
|
|
29
|
-
|
|
30
|
-
# Allow modifications to agent rule files (AGENTS.md, JULES_RULES_TEMPLATE.md, .agent/rules/**) in PRs (Default: false)
|
|
31
|
-
# JULES_ALLOW_AGENT_RULE_CHANGES=false
|
|
32
|
-
|
|
33
|
-
# --- Execution Scope & Git ---
|
|
34
|
-
# Base Branch for PR Audits & Merge-Base Calculations (Default: main)
|
|
35
|
-
BASE_BRANCH=main
|
|
36
|
-
|
|
37
|
-
# PR Head Branch (Used by CI to dynamically target branches during OODA repair)
|
|
38
|
-
# GITHUB_HEAD_REF=my-feature-branch
|
|
39
|
-
|
|
40
|
-
# Root directory of the project (Auto-assigned during swarm executions)
|
|
41
|
-
# JULES_PROJECT_ROOT=/path/to/project
|
|
42
|
-
|
|
43
|
-
# --- Swarm & Concurrency ---
|
|
44
|
-
# Maximum parallel dispatches for swarm runs (Default: 3)
|
|
45
|
-
JULES_SWARM_CONCURRENCY=3
|
|
46
|
-
|
|
47
|
-
# Dispatch Stagger Interval in Milliseconds (Default: 1500)
|
|
48
|
-
JULES_SWARM_STAGGER_MS=1500
|
|
49
|
-
|
|
50
|
-
# Rate-limit for the jules:queue command (Default: 500)
|
|
51
|
-
# JULES_PACE_MS=500
|
|
52
|
-
|
|
53
|
-
# Use Git Worktrees instead of cloning for swarm isolation
|
|
54
|
-
# JULES_USE_WORKTREES=false
|
|
55
|
-
|
|
56
|
-
# Current slot index for partitioning tasks (Swarm mode)
|
|
57
|
-
# JULES_SLOT_INDEX=1
|
|
58
|
-
|
|
59
|
-
# Total number of slots for partitioning tasks (Swarm mode)
|
|
60
|
-
# JULES_SLOT_TOTAL=3
|
|
61
|
-
|
|
62
|
-
# --- CI & Output ---
|
|
63
|
-
# Is this running in a CI environment? (Changes log output and fail-fast behaviors)
|
|
64
|
-
# CI=true
|
|
65
|
-
|
|
66
|
-
# Allow OODA Auto-Repair even in CI environments
|
|
67
|
-
# ALLOW_AUTO_REPAIR=true
|
|
68
|
-
|
|
69
|
-
# GitHub Actions Step Summary File Path
|
|
70
|
-
# GITHUB_STEP_SUMMARY=/path/to/step_summary.md
|
|
71
|
-
|
|
72
|
-
# Disable color in terminal output
|
|
73
|
-
# NO_COLOR=true
|
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
name: Jules PR Audit & Test Gatekeeper
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
push:
|
|
5
|
-
branches: [ main ]
|
|
6
|
-
pull_request:
|
|
7
|
-
branches: [ main ]
|
|
8
|
-
|
|
9
|
-
jobs:
|
|
10
|
-
audit-and-test:
|
|
11
|
-
runs-on: ubuntu-latest
|
|
12
|
-
strategy:
|
|
13
|
-
matrix:
|
|
14
|
-
node-version: ['20.x', '22.x', '24.x']
|
|
15
|
-
steps:
|
|
16
|
-
- name: Checkout repository
|
|
17
|
-
uses: actions/checkout@v4
|
|
18
|
-
with:
|
|
19
|
-
fetch-depth: 0
|
|
20
|
-
|
|
21
|
-
- name: Setup Node.js
|
|
22
|
-
uses: actions/setup-node@v4
|
|
23
|
-
with:
|
|
24
|
-
node-version: ${{ matrix.node-version }}
|
|
25
|
-
|
|
26
|
-
- name: Cache OODA state & ledgers
|
|
27
|
-
uses: actions/cache@v4
|
|
28
|
-
with:
|
|
29
|
-
path: .agent/state/
|
|
30
|
-
key: ooda-state-${{ runner.os }}-${{ github.run_id }}
|
|
31
|
-
restore-keys: |
|
|
32
|
-
ooda-state-${{ runner.os }}-
|
|
33
|
-
|
|
34
|
-
- name: Install dependencies
|
|
35
|
-
run: npm install
|
|
36
|
-
|
|
37
|
-
- name: Run Linter
|
|
38
|
-
run: npm run lint --if-present
|
|
39
|
-
|
|
40
|
-
- name: Run Unit Tests
|
|
41
|
-
run: npm test --if-present
|
|
42
|
-
|
|
43
|
-
- name: Run Jules PR Self-Audit Gatekeeper
|
|
44
|
-
if: matrix.node-version == '22.x' && github.event_name == 'pull_request'
|
|
45
|
-
run: node scripts/jules-self-audit.mjs
|
|
46
|
-
env:
|
|
47
|
-
CI: "true"
|
|
48
|
-
BASE_BRANCH: "main"
|
|
49
|
-
|