jules-orchestrator-kit 0.27.0 β†’ 0.27.1

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.
Files changed (5) hide show
  1. package/README.md +172 -108
  2. package/bin/agentctl.mjs +1 -1
  3. package/package.json +1 -1
  4. package/src/git.mjs +1 -24
  5. package/src/process-group.mjs +0 -80
package/README.md CHANGED
@@ -4,76 +4,115 @@
4
4
 
5
5
  ### Universal Autonomous AI Agent Orchestration Kernel for Google Jules
6
6
 
7
+ <br/>
8
+
7
9
  [![Jules PR Audit](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml/badge.svg)](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
8
10
  [![npm version](https://img.shields.io/npm/v/jules-orchestrator-kit.svg)](https://www.npmjs.com/package/jules-orchestrator-kit)
9
11
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
12
  [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
11
13
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20native-blue.svg)](https://nodejs.org)
12
- [![Polyglot Stacks](https://img.shields.io/badge/polyglot--stacks-24%2B-8A2BE2.svg)](#-universal-polyglot-support--stack-detection)
14
+
15
+ <br/>
13
16
 
14
17
  <p align="center">
15
- <b>The zero-dependency safety gatekeeper and self-healing engineering kernel for autonomous coding agent swarms.</b><br/>
18
+ <b>The zero-dependency safety gatekeeper and self-healing engineering kernel for autonomous coding agent swarms.</b>
16
19
  Transforms single-turn AI chat assistants into production-grade engineering swarms running 300+ daily sessions across any language or monorepo.
17
20
  </p>
18
21
 
22
+ <br/>
23
+
19
24
  <p align="center">
20
- <a href="#-2-sentence-mental-model">πŸ’‘ What is Kit?</a> β€’
21
- <a href="#-universal-30-second-quickstart-zero-to-verified-pr">⚑ 30s Quickstart</a> β€’
22
- <a href="#-triage-guidelines-when-to-use-vs-when-not-to-use">🎯 Triage Guidelines</a> β€’
23
- <a href="#-feature-comparison-matrix">πŸ“Š Comparison Matrix</a> β€’
24
- <a href="#-system-architecture--visual-diagrams">πŸ›οΈ Architecture</a> β€’
25
- <a href="#-cli-command-reference-agentctl">πŸ› οΈ CLI Reference</a> β€’
26
- <a href="#-v027-next-gen-feature-roadmap">πŸ—ΊοΈ Roadmap</a>
25
+ <a href="#what-is-kit">πŸ’‘&nbsp;What&nbsp;is&nbsp;Kit?</a> &nbsp;β€’&nbsp;
26
+ <a href="#quickstart">⚑&nbsp;Quickstart</a> &nbsp;β€’&nbsp;
27
+ <a href="#triage-guidelines">🎯&nbsp;Triage&nbsp;Guidelines</a> &nbsp;β€’&nbsp;
28
+ <a href="#matrix">πŸ“Š&nbsp;Matrix</a>
29
+ <br/>
30
+ <a href="#architecture">πŸ›οΈ&nbsp;Architecture</a> &nbsp;β€’&nbsp;
31
+ <a href="#cli-docs">πŸ› οΈ&nbsp;CLI&nbsp;Docs</a> &nbsp;β€’&nbsp;
32
+ <a href="#roadmap">πŸ—ΊοΈ&nbsp;Roadmap</a>
27
33
  </p>
28
34
 
29
35
  </div>
30
36
 
37
+ <br/>
38
+
31
39
  ---
32
40
 
41
+ <br/>
42
+
43
+ <a id="what-is-kit"></a>
33
44
  ## πŸ’‘ 2-Sentence Mental Model
34
45
 
46
+ > [!TIP]
35
47
  > **Think of `jules-orchestrator-kit` as an automated Engineering Manager for AI coding agents.**
36
- > **It hands out clear tasks, runs your tests in an isolated sandbox, fixes broken code automatically, and only opens a Pull Request when 100% of your tests pass.**
48
+ > It hands out clear tasks, runs your tests in an isolated sandbox, fixes broken code automatically, and only opens a Pull Request when 100% of your tests pass.
49
+
50
+ <br/>
37
51
 
38
52
  ---
39
53
 
54
+ <br/>
55
+
40
56
  ## 🎯 Why `jules-orchestrator-kit`?
41
57
 
42
58
  Autonomous coding agents can write software at 100Γ— human speedβ€”but unconstrained agents introduce silent regressions, leak API keys, hallucinate test assertions, and thrash shared monorepos.
43
59
 
44
60
  `jules-orchestrator-kit` provides the missing **Safety, Orchestration, and Verification Kernel** for high-reliability AI agent deployments:
45
- - **πŸ”’ Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
46
- - **πŸ›‘οΈ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, redacts high-entropy secrets and PII from dry-runs and git diffs, and rejects PRs exceeding the 75 KB Diff Payload governor.
47
- - **πŸ”„ Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
48
- - **🌐 Universal Polyglot Spine:** Natively auto-detects 24+ tech stacks (PHP/Laravel/WordPress, .NET/C#, Python, Go, Rust, C/C++, Flutter/Swift, Node/Deno/Bun) and transparently wraps verification suites in Docker Compose or Devcontainer sandboxes.
49
- - **πŸ“‚ Scoped Monorepo Boundary Resolver:** Statically maps changed files up directory ancestry to invoke isolated subshell test suites (`(cd backend && pytest) && (cd cli && cargo test)`), eliminating global test thrashing.
50
- - **πŸš€ Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
51
- - **πŸ“ˆ Proven Scale & Reliability:** Empirically tested with **221 unit tests across 54 suites passing in < 1.2s**, supporting 300+ daily agent sessions per repository.
61
+
62
+ * **πŸ”’ Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
63
+
64
+ * **πŸ›‘οΈ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, redacts high-entropy secrets and PII from dry-runs and git diffs, and rejects PRs exceeding the 75 KB Diff Payload governor.
65
+
66
+ * **πŸ”„ Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
67
+
68
+ * **🌐 Universal Polyglot Spine:** Natively auto-detects 24+ tech stacks (PHP/Laravel/WordPress, .NET/C#, Python, Go, Rust, C/C++, Flutter/Swift, Node/Deno/Bun) and transparently wraps verification suites in Docker Compose or Devcontainer sandboxes.
69
+
70
+ * **πŸ“‚ Scoped Monorepo Boundary Resolver:** Statically maps changed files up directory ancestry to invoke isolated subshell test suites (`(cd backend && pytest) && (cd cli && cargo test)`), eliminating global test thrashing.
71
+
72
+ * **πŸš€ Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
73
+
74
+ * **πŸ“ˆ Proven Scale & Reliability:** Empirically tested with **224 unit tests across 55 suites passing in < 1.2s**, supporting 300+ daily agent sessions per repository.
75
+
76
+ <br/>
52
77
 
53
78
  ---
54
79
 
80
+ <br/>
81
+
82
+ <a id="triage-guidelines"></a>
55
83
  ## 🎯 Triage Guidelines: When to Use vs. When NOT to Use
56
84
 
57
85
  To ensure maximum merge success, dispatch tasks according to our deterministic triage boundaries:
58
86
 
87
+ <br/>
88
+
59
89
  ### 🟒 Ideal Tasks for Autonomous Swarms
60
- - βœ… **Scoped Code Changes & Bug Fixes:** Well-defined objectives mechanically verifiable via unit tests (`npm test`, `pytest`, `cargo test`, `dotnet test`).
61
- - βœ… **Type & Linter Migrations:** TypeScript strict mode fixes, PHP 8.3 type hint additions, or Python MyPy type annotation passes.
62
- - βœ… **Dependency Bumps & Security Audits:** Remediating CVEs in lockfiles (`package.json`, `Cargo.toml`, `composer.json`) with hermetic test verification.
63
- - βœ… **Refactoring Legacy Codebases:** Modularizing backend routes, API controllers, or database query layers.
64
- - βœ… **Visual & E2E Testing (via Playwright):** UI changes paired with automated headless Playwright snapshot tests (`npx playwright test`).
90
+
91
+ * βœ… **Scoped Code Changes & Bug Fixes:** Well-defined objectives mechanically verifiable via unit tests (`npm test`, `pytest`, `cargo test`, `dotnet test`).
92
+ * βœ… **Type & Linter Migrations:** TypeScript strict mode fixes, PHP 8.3 type hint additions, or Python MyPy type annotation passes.
93
+ * βœ… **Dependency Bumps & Security Audits:** Remediating CVEs in lockfiles (`package.json`, `Cargo.toml`, `composer.json`) with hermetic test verification.
94
+ * βœ… **Refactoring Legacy Codebases:** Modularizing backend routes, API controllers, or database query layers.
95
+ * βœ… **Visual & E2E Testing (via Playwright):** UI changes paired with automated headless Playwright snapshot tests (`npx playwright test`).
96
+
97
+ <br/>
65
98
 
66
99
  ### πŸ”΄ When NOT to Use (Out of Scope)
67
- - ❌ **Unverifiable Visual UI Tweaks:** Pixel-perfect CSS/Tailwind adjustments lacking automated visual regression tests (agents cannot "see" raw browser output without Playwright).
68
- - ❌ **Closed Proprietary Platforms Without CLI:** Systems lacking local CLI tools or git repositories (e.g., Salesforce, Webflow, closed SAP backends).
69
- - ❌ **Unmocked Live Cloud Systems:** Code requiring live connections to 10+ external cloud APIs without local emulators or mocks.
70
- - ❌ **Protected Infrastructure Paths:** Direct edits to `.github/workflows/`, production deployment keys, or agent security gate rules (enforced fail-closed by `Agent Scope Guard`).
100
+
101
+ * ❌ **Unverifiable Visual UI Tweaks:** Pixel-perfect CSS/Tailwind adjustments lacking automated visual regression tests (agents cannot "see" raw browser output without Playwright).
102
+ * ❌ **Closed Proprietary Platforms Without CLI:** Systems lacking local CLI tools or git repositories (e.g., Salesforce, Webflow, closed SAP backends).
103
+ * ❌ **Unmocked Live Cloud Systems:** Code requiring live connections to 10+ external cloud APIs without local emulators or mocks.
104
+ * ❌ **Protected Infrastructure Paths:** Direct edits to `.github/workflows/`, production deployment keys, or agent security gate rules (enforced fail-closed by `Agent Scope Guard`).
105
+
106
+ <br/>
71
107
 
72
108
  ---
73
109
 
110
+ <br/>
111
+
112
+ <a id="matrix"></a>
74
113
  ## πŸ“Š Feature Comparison Matrix
75
114
 
76
- | Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.26+) |
115
+ | Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.27+) |
77
116
  | :--- | :--- | :--- | :--- |
78
117
  | **Self-Healing Loop** | ❌ None (Crashes on test error) | ❌ None (Fails build; notifies human) | βœ… **Autonomous OODA Loop** (Max 3 repair turns with error fingerprinting) |
79
118
  | **Scope Isolation** | ❌ None (Can modify CI files or lockfiles) | 🟑 Post-commit branch rules only | βœ… **Fail-Closed Scope Guard** (Deny-first evaluation; blocks protected paths) |
@@ -84,12 +123,19 @@ To ensure maximum merge success, dispatch tasks according to our deterministic t
84
123
  | **Secret Leak Prevention**| ❌ Prone to leaking tokens in diffs | 🟑 Post-push secret scanning alerts | βœ… **Pre-Dispatch & Pre-Commit Diff Scanner** (Blocks CVEs/keys before PR creation) |
85
124
  | **Dependency Footprint** | ❌ Requires heavy SDKs & parsers | 🟑 Many external actions & plugins | βœ… **0 Native Dependencies** (100% Node.js 20+ ESM built-ins) |
86
125
 
126
+ <br/>
127
+
87
128
  ---
88
129
 
130
+ <br/>
131
+
132
+ <a id="quickstart"></a>
89
133
  ## ⚑ Universal 30-Second Quickstart (Zero to Verified PR)
90
134
 
91
135
  Get from zero to an autonomously verified GitHub Pull Request across any software ecosystem in 30 seconds.
92
136
 
137
+ <br/>
138
+
93
139
  ### 1️⃣ Node.js / TypeScript (npm, pnpm, yarn, bun, deno)
94
140
  ```bash
95
141
  # Dispatch a scoped task; auto-detects package.json / tsconfig.json and runs type-checked tests
@@ -97,6 +143,8 @@ npx jules-orchestrator-kit dispatch --title "Add rate limiting to API router" \
97
143
  --prompt "Implement IP-based token-bucket rate limiting in src/router.ts with unit tests."
98
144
  ```
99
145
 
146
+ <br/>
147
+
100
148
  ### 2️⃣ Python / FastAPI / Django (pytest, pyproject.toml)
101
149
  ```bash
102
150
  # Bootstrap zero-test or legacy Python repo, then dispatch task
@@ -105,6 +153,8 @@ npx jules-orchestrator-kit dispatch --title "Add OAuth2 JWT validation" \
105
153
  --prompt "Add JWT bearer authentication middleware to backend/api/auth.py and verify via pytest."
106
154
  ```
107
155
 
156
+ <br/>
157
+
108
158
  ### 3️⃣ PHP / Laravel / WordPress (Docker Compose + PHPUnit/Pest)
109
159
  ```bash
110
160
  # Auto-detects docker-compose.yml and wraps test commands in `docker compose exec -T app ...`
@@ -112,6 +162,8 @@ npx jules-orchestrator-kit dispatch --title "Upgrade PHP 8.3 type annotations" \
112
162
  --prompt "Add strict type hints to all repository classes in app/Repositories/."
113
163
  ```
114
164
 
165
+ <br/>
166
+
115
167
  ### 4️⃣ .NET / C# Enterprise (*.sln, *.csproj)
116
168
  ```bash
117
169
  # Auto-detects .sln / .csproj and runs `dotnet test --no-restore --nologo`
@@ -119,6 +171,8 @@ npx jules-orchestrator-kit dispatch --title "Implement OrderService caching" \
119
171
  --prompt "Add IMemoryCache caching to OrderService.cs with xUnit coverage."
120
172
  ```
121
173
 
174
+ <br/>
175
+
122
176
  ### 5️⃣ UI / Frontend E2E (Playwright)
123
177
  ```bash
124
178
  # Dispatch frontend task verified via headless Playwright E2E tests
@@ -126,88 +180,109 @@ npx jules-orchestrator-kit dispatch --title "Add Dark Mode Toggle Component" \
126
180
  --prompt "Create ThemeToggle component in src/components/ThemeToggle.tsx and verify via npx playwright test."
127
181
  ```
128
182
 
183
+ <br/>
184
+
129
185
  ### 6️⃣ Polyglot Monorepo (FastAPI + React + Rust CLI)
130
186
  ```bash
131
187
  # Run a parallel worktree swarm; changed files automatically route to scoped subproject tests
132
188
  npx jules-orchestrator-kit swarm
133
189
  ```
134
190
 
191
+ <br/>
192
+
193
+ <details>
194
+ <summary><b>πŸ” View All 24+ Supported Ecosystems & Stack Triggers</b></summary>
195
+
196
+ <br/>
197
+
198
+ ```
199
+ Ecosystems Natively Supported by src/stack-detector.mjs:
200
+ β”œβ”€β”€ PHP / Laravel / WordPress (composer.json, phpunit.xml, pest.php, artisan, wp-cli.yml)
201
+ β”œβ”€β”€ .NET / C# / F# (*.sln, *.csproj, *.fsproj, global.json)
202
+ β”œβ”€β”€ Mobile / Dart / Flutter (pubspec.yaml)
203
+ β”œβ”€β”€ Mobile / Swift / Xcode (Package.swift)
204
+ β”œβ”€β”€ Mobile / React Native (app.json, react-native.config.js)
205
+ β”œβ”€β”€ Systems / CMake (CMakeLists.txt)
206
+ β”œβ”€β”€ Systems / Rust Cargo (Cargo.toml)
207
+ β”œβ”€β”€ Systems / Go (go.mod)
208
+ β”œβ”€β”€ Systems / Make (Makefile)
209
+ β”œβ”€β”€ Python / FastAPI / Django (pyproject.toml, requirements.txt, setup.py)
210
+ β”œβ”€β”€ Elixir / Phoenix (mix.exs)
211
+ β”œβ”€β”€ Ruby / Rails (Gemfile)
212
+ β”œβ”€β”€ Java / Maven (pom.xml)
213
+ β”œβ”€β”€ Java / Gradle (build.gradle, build.gradle.kts)
214
+ β”œβ”€β”€ JS / TS Workspaces (turbo.json, pnpm-workspace.yaml, nx.json)
215
+ β”œβ”€β”€ JS / TS Runtimes (bunfig.toml, deno.json, package.json)
216
+ └── Devcontainers & Docker Compose (.devcontainer/devcontainer.json, docker-compose.yml, Dockerfile)
217
+ ```
218
+
219
+ </details>
220
+
221
+ <br/>
222
+
135
223
  ---
136
224
 
225
+ <br/>
226
+
227
+ <a id="architecture"></a>
137
228
  ## πŸ›οΈ System Architecture & Visual Diagrams
138
229
 
230
+ <br/>
231
+
139
232
  ### 1. The Autonomous OODA Verification Loop
140
233
  Every task dispatched to `jules-orchestrator-kit` executes within an immutable, fail-closed verification loop:
141
234
 
235
+ ```mermaid
236
+ flowchart TD
237
+ A["πŸ“© Task Envelope"] --> B["1. Validate Scope & Base Freshness"]
238
+ B --> C["2. Create Isolated Git Worktree & VFS Lock"]
239
+ C --> D["3. Dispatch Task to Google Jules / LLM"]
240
+ D --> E["4. Execute Scoped Verification Gate<br/><code>detectPolyglotStack().testCmd</code>"]
241
+
242
+ E -->|PASS| F["5. Security Audit<br/><i>Redact Secrets, Diff < 75KB</i>"]
243
+ F --> G["7. Rebase & Open PR<br/><code>git rebase main && gh pr create</code>"]
244
+
245
+ E -->|FAIL| H["6. Fingerprint Stderr & Flaky Verdict"]
246
+ H -->|Oscillation >= 0.40| I["🚨 Quarantined Test<br/><i>Exit Code 8</i>"]
247
+ H -->|Normal Failure| J["πŸ”„ Attempt OODA Repair Turn<br/><i>Max 3 Retries; Exit 4 on Exhaust</i>"]
248
+ J --> D
142
249
  ```
143
- +---------------------------------------------------------------------------------------------------+
144
- | AUTONOMOUS OODA SELF-HEALING ENGINE (v0.26+) |
145
- | |
146
- | [Task Envelope] --> (1. Validate Scope & Base Freshness) |
147
- | | |
148
- | v |
149
- | (2. Create Isolated Git Worktree / VFS Lock) |
150
- | | |
151
- | v |
152
- | (3. Dispatch AI Task to Google Jules / LLM) |
153
- | | |
154
- | v |
155
- | (4. Execute Scoped Verification Gate) |
156
- | -- detectPolyglotStack().testCmd |
157
- | -- Docker Compose / Devcontainer wrapper |
158
- | | |
159
- | +---------+---------+ |
160
- | | PASS | FAIL |
161
- | v v |
162
- | (5. Security Audit) (6. Fingerprint Stderr / Flaky Verdict) |
163
- | - Redact Secrets | |
164
- | - Check Diff < 75KB +---> Is test QUARANTINED? (Oscillation >= 0.40) |
165
- | | | | |
166
- | v YES NO |
167
- | (7. Rebase & PR) | | |
168
- | - git rebase main v v |
169
- | - gh pr create [Log Quarantined Flake] [Attempt OODA Repair Turn] |
170
- | (Exit Code 8) (Max 3 Retries; Exit 4 on Exhaust) |
171
- +---------------------------------------------------------------------------------------------------+
172
- ```
250
+
251
+ <br/>
173
252
 
174
253
  ### 2. Polyglot Monorepo Scoped Execution Engine
175
254
  In monorepos containing multiple languages, `resolveWorkspaceBoundary(changedFiles)` traverses directory ancestry to isolate verification to affected subprojects:
176
255
 
256
+ ```mermaid
257
+ flowchart TD
258
+ A["πŸ“ Changed Files<br/><code>['backend/api/main.py', 'cli/src/main.rs']</code>"] --> B{"Check Shared Triggers?<br/><i>docker-compose.yml, openapi.yaml</i>"}
259
+ B -->|None Changed| C["Traverse Directory Ancestry"]
260
+ C --> D1["<code>backend/api/main.py</code> β†’ <code>backend/pyproject.toml</code><br/><i>(Python Stack)</i>"]
261
+ C --> D2["<code>cli/src/main.rs</code> β†’ <code>cli/Cargo.toml</code><br/><i>(Rust Stack)</i>"]
262
+ D1 --> E["Synthesize POSIX Subshell Verification Plan<br/><code>(cd backend && pytest) && (cd cli && cargo test)</code>"]
263
+ D2 --> E
177
264
  ```
178
- +---------------------------------------------------------------------------------------------------+
179
- | MONOREPO BOUNDARY RESOLVER (resolveWorkspaceBoundary) |
180
- | |
181
- | changedFiles: ["backend/api/main.py", "cli/src/main.rs", "docs/README.md"] |
182
- | | |
183
- | +---> 1. Check Root Shared Triggers (openapi.yaml, docker-compose.yml, Makefile) |
184
- | | -> None changed. Continue subproject isolation. |
185
- | | |
186
- | +---> 2. Map Files to Subproject Roots by Trigger File Traversal: |
187
- | | - "backend/api/main.py" -> backend/pyproject.toml (Python Stack) |
188
- | | - "cli/src/main.rs" -> cli/Cargo.toml (Rust/Cargo Stack) |
189
- | | - "docs/README.md" -> (Documentation; R0 Cosmetic Risk) |
190
- | | |
191
- | +---> 3. Synthesize Scoped POSIX Subshell Verification Plan: |
192
- | testCmd: "(cd backend && pytest) && (cd cli && cargo test --workspace)" |
193
- | buildCmd: "(cd cli && cargo build)" |
194
- | |
195
- | Result: 100% test isolation, 0 global test thrashing, 0 git index lock collisions. |
196
- +---------------------------------------------------------------------------------------------------+
197
- ```
265
+
266
+ <br/>
198
267
 
199
268
  ---
200
269
 
270
+ <br/>
271
+
272
+ <a id="cli-docs"></a>
201
273
  ## πŸ› οΈ CLI Command Reference (`agentctl`)
202
274
 
203
275
  `agentctl` is the unified command-line interface for `jules-orchestrator-kit`, available via `bin/agentctl.mjs` or `npx jules-orchestrator-kit <command>`.
204
276
 
277
+ <br/>
278
+
205
279
  | Command | Usage | Description | Exit Codes |
206
280
  | :--- | :--- | :--- | :--- |
207
281
  | `dispatch` | `agentctl dispatch --title <t> --prompt <p>` | Dispatches a single task to an AI agent in an isolated worktree. | `0` (Success), `1` (Arg error), `2` (429 Rate limit), `3` (Scope deny), `4` (OODA exhausted), `5` (Diff > 75KB), `6` (Secret leak) |
282
+ | `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
283
+ | `dashboard` | `agentctl dashboard [port]` | Starts zero-dependency local HTTP telemetry and audit visualizer dashboard. | `0` (Running) |
208
284
  | `gate` / `audit`| `agentctl gate --base main --json` | Runs security, secret scanning, and verification gate against current branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
209
285
  | `bootstrap` | `agentctl bootstrap [--force] [--json]` | Inspects an untested repository and synthesizes `.agent/config.yml` with a zero-test verification oracle (`php -l`, `compileall`, `dotnet build`, `tsc`, `smoke`). | `0` (Bootstrapped / Existing) |
210
- | `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
211
286
  | `queue` | `agentctl queue` | Consumes and executes pending markdown task envelopes in `.agent/queue/`. | `0` (Complete) |
212
287
  | `swarm` | `agentctl swarm` | Runs parallel multi-agent swarm across queued tasks with token-bucket concurrency. | `0` (Complete) |
213
288
  | `doctor` | `agentctl doctor` | Diagnostic inspect: displays detected stack, container wrapper, test command, and daily session budget. | `0` (Healthy) |
@@ -215,57 +290,46 @@ In monorepos containing multiple languages, `resolveWorkspaceBoundary(changedFil
215
290
  | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
216
291
  | `init` | `agentctl init` | Scaffolds `.agent/` directory structure and default `.agent/config.yml`. | `0` (Created) |
217
292
  | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
218
- | `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.26.1`). | `0` |
293
+ | `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.27.0`). | `0` |
219
294
 
220
- ---
221
-
222
- ## 🌐 Universal Polyglot Support & Stack Detection
223
-
224
- The table below illustrates the 24+ software ecosystems natively supported by `src/stack-detector.mjs`:
225
-
226
- ```
227
- Ecosystems Supported:
228
- β”œβ”€β”€ PHP / Laravel / WordPress (composer.json, phpunit.xml, pest.php, artisan, wp-cli.yml)
229
- β”œβ”€β”€ .NET / C# / F# (*.sln, *.csproj, *.fsproj, global.json)
230
- β”œβ”€β”€ Mobile / Dart / Flutter (pubspec.yaml)
231
- β”œβ”€β”€ Mobile / Swift / Xcode (Package.swift)
232
- β”œβ”€β”€ Mobile / React Native (app.json, react-native.config.js)
233
- β”œβ”€β”€ Systems / CMake (CMakeLists.txt)
234
- β”œβ”€β”€ Systems / Rust Cargo (Cargo.toml)
235
- β”œβ”€β”€ Systems / Go (go.mod)
236
- β”œβ”€β”€ Systems / Make (Makefile)
237
- β”œβ”€β”€ Python / FastAPI / Django (pyproject.toml, requirements.txt, setup.py)
238
- β”œβ”€β”€ Elixir / Phoenix (mix.exs)
239
- β”œβ”€β”€ Ruby / Rails (Gemfile)
240
- β”œβ”€β”€ Java / Maven (pom.xml)
241
- β”œβ”€β”€ Java / Gradle (build.gradle, build.gradle.kts)
242
- β”œβ”€β”€ JS / TS Workspaces (turbo.json, pnpm-workspace.yaml, nx.json)
243
- β”œβ”€β”€ JS / TS Runtimes (bunfig.toml, deno.json, package.json)
244
- └── Devcontainers & Docker Compose (.devcontainer/devcontainer.json, docker-compose.yml, Dockerfile)
245
- ```
295
+ <br/>
246
296
 
247
297
  ---
248
298
 
299
+ <br/>
300
+
301
+ <a id="roadmap"></a>
249
302
  ## πŸ—ΊοΈ v0.27+ Next-Gen Feature Roadmap
250
303
 
251
304
  | Feature | Module / Command | Architectural Blueprint | Target Release |
252
305
  | :--- | :--- | :--- | :---: |
253
- | **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Implemented prototype)* |
254
- | **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Implemented prototype)* |
255
- | **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** |
306
+ | **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Shipped)* |
307
+ | **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Shipped)* |
308
+ | **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** *(Shipped)* |
256
309
  | **Cross-Language Contract Guard** | `hashCrossLanguageInterface` (`src/merge-blocks.mjs`)| Canonical SHA-256 schema hashing for OpenAPI/Protobuf specs across polyglot task dependencies in `DagExecutor`. | **v0.26.0** *(Shipped)* |
257
310
 
311
+ <br/>
312
+
258
313
  ---
259
314
 
315
+ <br/>
316
+
260
317
  ## πŸ“– Recipes, Documentation & Prior Art
261
318
 
319
+ - [**Google Jules Official Documentation**](https://jules.google) β€” Official platform overview and API specifications for Google Jules.
320
+ - [**Google Labs Code Repositories**](https://github.com/google-labs-code) β€” Official Google Labs public GitHub organization (jules-action, jules-sdk).
262
321
  - [**Universal Polyglot Architecture & Zero-Test Specification**](./docs/UNIVERSAL_POLYGLOT_ARCHITECTURE.md) β€” Comprehensive technical report on boundary resolution, OODA math, and B2B workflows.
322
+ - [**v0.27.0 Architectural Audit & Platform Evolution**](./docs/V0.27_ARCHITECTURAL_AUDIT_AND_EVOLUTION.md) β€” PR review remediation, failover router, and local dashboard specs.
263
323
  - [**Examples & Task Envelope Recipes**](./EXAMPLES.md) β€” Production YAML and Markdown task envelopes.
264
324
  - [**Adversarial Security Audit Phase 4 Report**](./docs/AUDIT_REPORT.md) β€” CWE-77, CWE-1321, and CWE-183 security hardening analysis.
265
325
  - [**Changelog**](./CHANGELOG.md) β€” Full release history and migration guides.
266
326
 
327
+ <br/>
328
+
267
329
  ---
268
330
 
331
+ <br/>
332
+
269
333
  <div align="center">
270
334
  <p><b>jules-orchestrator-kit</b> β€’ Built with zero external dependencies for Google Jules and enterprise AI agent swarms.</p>
271
335
  </div>
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 v0.27.0 β€” Universal Agent Orchestrator & Safety Gatekeeper
17
+ πŸš€ agentctl v0.27.1 β€” Universal Agent Orchestrator & Safety Gatekeeper
18
18
 
19
19
  Usage: agentctl <command> [options]
20
20
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jules-orchestrator-kit",
3
- "version": "0.27.0",
3
+ "version": "0.27.1",
4
4
  "description": "Orchestration kit for running Google Jules autonomous agents.",
5
5
  "repository": {
6
6
  "type": "git",
package/src/git.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { execFileSync } from "node:child_process";
2
2
  import { normalizePath } from "./config.mjs";
3
- import { journalIntent, journalDone } from "./journal.mjs";
3
+
4
4
 
5
5
  export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
6
6
  export const NET_GUARD_FLAG = `--import ${NET_GUARD_PRELOAD_URL}`;
@@ -173,29 +173,6 @@ export function showFromOrigin(root = process.cwd(), base = "main", filePath = "
173
173
  }
174
174
  }
175
175
 
176
- export function createBranch(root = process.cwd(), branch = "") {
177
- const opId = journalIntent(root, { type: "create_branch", branch, targetPath: "" });
178
- try {
179
- const res = git(["branch", branch], { cwd: root });
180
- journalDone(root, opId);
181
- return res;
182
- } catch (err) {
183
- journalDone(root, opId);
184
- throw err;
185
- }
186
- }
187
-
188
- export function worktreeAdd(root = process.cwd(), branch = "agent/task", targetDir = "") {
189
- const opId = journalIntent(root, { type: "worktree_add", targetPath: targetDir, branch });
190
- try {
191
- const res = git(["worktree", "add", targetDir, "-b", branch], { cwd: root });
192
- journalDone(root, opId);
193
- return res;
194
- } catch (err) {
195
- journalDone(root, opId);
196
- throw err;
197
- }
198
- }
199
176
 
200
177
  export function worktreeRemove(root = process.cwd(), targetDir = "") {
201
178
  return git(["worktree", "remove", targetDir, "--force"], { cwd: root });
package/src/process-group.mjs DELETED
@@ -1,80 +0,0 @@
1
- import { spawn } from "node:child_process";
2
-
3
- /**
4
- * ProcessGroupManager manages child processes in isolated process groups
5
- * and ensures 100% leak-free cleanup on process exit or termination signals.
6
- */
7
- export class ProcessGroupManager {
8
- constructor() {
9
- this.activePgids = new Set();
10
- this.activePids = new Set();
11
- this.installed = false;
12
- this.installSignalHandlers();
13
- }
14
-
15
- installSignalHandlers() {
16
- if (this.installed) return;
17
- this.installed = true;
18
-
19
- const cleanup = (signal) => {
20
- this.killAll(signal || "SIGTERM");
21
- };
22
-
23
- process.once("SIGINT", () => {
24
- cleanup("SIGINT");
25
- process.exit(130);
26
- });
27
-
28
- process.once("SIGTERM", () => {
29
- cleanup("SIGTERM");
30
- process.exit(143);
31
- });
32
-
33
- process.once("exit", () => {
34
- this.killAll("SIGKILL");
35
- });
36
- }
37
-
38
- spawnProcess(command, args = [], options = {}) {
39
- const opts = {
40
- ...options,
41
- detached: true,
42
- };
43
-
44
- const child = spawn(command, args, opts);
45
-
46
- if (child.pid) {
47
- const pgid = child.pid;
48
- this.activePgids.add(pgid);
49
- this.activePids.add(child.pid);
50
-
51
- child.on("exit", () => {
52
- this.activePgids.delete(pgid);
53
- this.activePids.delete(child.pid);
54
- });
55
-
56
- child.on("error", () => {
57
- this.activePgids.delete(pgid);
58
- this.activePids.delete(child.pid);
59
- });
60
- }
61
-
62
- return child;
63
- }
64
-
65
- killAll(signal = "SIGTERM") {
66
- for (const pgid of this.activePgids) {
67
- try {
68
- process.kill(-pgid, signal);
69
- } catch (_) {
70
- try {
71
- process.kill(pgid, signal);
72
- } catch (_) {}
73
- }
74
- }
75
- this.activePgids.clear();
76
- this.activePids.clear();
77
- }
78
- }
79
-
80
- export const processGroupManager = new ProcessGroupManager();