jules-orchestrator-kit 0.73.0 → 0.74.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/.agent/rules/jules-protocol.md +5 -37
- package/CHANGELOG.md +24 -24
- package/JULES_RULES_TEMPLATE.md +38 -103
- package/README.md +149 -133
- package/bin/agentctl.mjs +96 -43
- package/bin/init.js +10 -13
- package/package.json +3 -5
- package/scripts/validate-envelope.mjs +23 -4
- package/src/dag-engine.mjs +14 -14
- package/src/engine.mjs +2 -1
- package/src/envelope.mjs +414 -13
- package/src/ops/command-registry.mjs +11 -17
- package/src/review-repair.mjs +1 -2
- package/src/role-resolver.mjs +23 -16
- package/src/scaffold.mjs +69 -2
- package/src/session-ops.mjs +1 -1
- package/src/wizard-init.mjs +16 -7
- package/src/wizard-task.mjs +124 -7
- package/AGENTS.md +0 -117
- package/ROADMAP_V1.md +0 -141
package/README.md
CHANGED
|
@@ -1,197 +1,213 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
1
|
# jules-orchestrator-kit
|
|
4
2
|
|
|
5
|
-
|
|
3
|
+
Task dispatch and local verification for coding agents. Requires Node.js 20+ and
|
|
4
|
+
Git; uses no third-party runtime dependencies.
|
|
6
5
|
|
|
7
|
-
[](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
|
|
8
6
|
[](https://www.npmjs.com/package/jules-orchestrator-kit)
|
|
9
|
-
[](https://nodejs.org)
|
|
11
|
-
[](https://nodejs.org)
|
|
12
|
-
[](https://nodejs.org)
|
|
13
|
-
|
|
14
|
-
**Zero-dependency safety gatekeeper, scoped sandboxing, and automated verification for coding agents.**
|
|
15
|
-
Runs deterministic test verification, secret scrubbing, and automated repair loops across any stack or monorepo before opening Pull Requests.
|
|
16
|
-
|
|
17
|
-
[Quickstart](#quickstart) • [Key Workflows](#key-workflows) • [Architecture](#architecture) • [Verification Profiles](#verification-profiles) • [CLI](#cli) • [Docs](docs/README.md)
|
|
18
|
-
|
|
19
|
-
<img src="docs/assets/hero-flow.svg" alt="Autonomous Orchestration Pipeline" width="100%" />
|
|
7
|
+
[](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
|
|
20
8
|
|
|
21
|
-
</div>
|
|
22
|
-
|
|
23
|
-
---
|
|
24
|
-
|
|
25
|
-
<a id="overview"></a>
|
|
26
9
|
## Overview
|
|
27
10
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
* **Multi-Provider Dispatch:** Google Jules (hosted REST), Claude Code CLI, OpenAI Codex CLI, and Gemini CLI; `agentctl providers` reports what this machine can dispatch to. Vendor-neutral `AGENT_*`/`JULES_*` environment variables.
|
|
32
|
-
* **Dynamic Verification Profiles:** `verify.profile: minimal | standard | max` schedules linting, tests, builds, AST mutation testing, and stability probing per toolchain. Stack-native CI via `agentctl ci init`.
|
|
33
|
-
* **Autonomous OODA Repair Loop:** Captures test stdout/stderr traces, fingerprints failure patterns, and runs automated repair cycles (up to 3 turns) before requesting human intervention.
|
|
34
|
-
* **Fail-Closed Security:** Deny-before-Allow scope rules, high-entropy and base64 secret scrubbing, semantic test-tamper detection (weakened/removed/vacuous assertions, dead-guard conditions), binary & symlink payload inspection, and a strict 75 KB diff governor.
|
|
35
|
-
* **Zero Runtime Dependencies:** Native Node.js 20+ standard modules only. Cross-platform parity verified on Linux, macOS, and Windows (Node 20, 22, 24).
|
|
36
|
-
* **Mechanically Verified:** Comprehensive test suite of **1530 unit tests across 204 suites**, with 59 activation-coverage canaries and 100% pass rate.
|
|
11
|
+
Use the kit to describe a scoped coding task, send it to Google Jules or an
|
|
12
|
+
installed Claude Code, Codex or Gemini CLI, and verify the resulting changes.
|
|
13
|
+
You can also run local checks without connecting an agent provider.
|
|
37
14
|
|
|
38
|
-
|
|
15
|
+
**Dispatch, verification and repair are explicit.** Dispatch sends the task;
|
|
16
|
+
`gate` runs configured checks without mutating the working tree. Use
|
|
17
|
+
`agentctl repair` explicitly for repair workflows. Provider output and passing
|
|
18
|
+
checks still need review before merging.
|
|
39
19
|
|
|
40
|
-
|
|
20
|
+
The current release is **v0.74.0**, a pre-1.0 release. A long-term stability policy is a
|
|
21
|
+
[v1.0 goal](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/ROADMAP_V1.md).
|
|
41
22
|
|
|
42
|
-
<a id="quickstart"></a>
|
|
43
23
|
## Quickstart
|
|
44
24
|
|
|
45
|
-
|
|
25
|
+
Start in an existing Git repository with working tests. Commit or stash unrelated
|
|
26
|
+
changes so that you can review exactly what setup adds. Node.js runs the kit;
|
|
27
|
+
your project's own runtime and test tools must also be installed.
|
|
46
28
|
|
|
47
|
-
|
|
48
|
-
# 1. Scaffold configuration, AGENTS.md, role prompts, and guardrails
|
|
49
|
-
# Auto-detects Python, Rust, Go, Bun, Deno, Node, PHP, .NET, etc.
|
|
50
|
-
# Omit --yes to select provider, plan tier, and verification profile interactively.
|
|
51
|
-
npx jules-orchestrator-kit init --yes
|
|
52
|
-
```
|
|
29
|
+
### 1. Configure the repository
|
|
53
30
|
|
|
54
31
|
```bash
|
|
55
|
-
|
|
56
|
-
# .agent/config.yml is protected by scope guards; committing establishes the trusted base policy.
|
|
57
|
-
git add .agent AGENTS.md SPEC.md CONSTRAINTS.md .gitignore && git commit -m "chore: add agent config"
|
|
32
|
+
npx jules-orchestrator-kit init
|
|
58
33
|
```
|
|
59
34
|
|
|
35
|
+
The wizard detects the project and asks about provider and verification settings.
|
|
36
|
+
Use `init --yes` to accept defaults. By default it writes only the canonical
|
|
37
|
+
`.agent/config.yml` plus runtime-state entries in `.gitignore` when they are
|
|
38
|
+
missing. Inspect the generated configuration and diff, especially the test
|
|
39
|
+
command and protected paths. Use `init --dry-run` to preview the exact writes
|
|
40
|
+
without changing the repository.
|
|
41
|
+
|
|
42
|
+
The historical full scaffold (AGENTS.md, specialist prompts, rules, workflows and
|
|
43
|
+
contract templates) remains available through `agentctl init --force` and the
|
|
44
|
+
legacy `jules-init` entry point during the 0.x migration window; it is no longer
|
|
45
|
+
default-owned by `agentctl init`.
|
|
46
|
+
|
|
60
47
|
```bash
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
npx jules-orchestrator-kit task create -p "Refactor invoice calculation" --verify "npm test"
|
|
48
|
+
git diff
|
|
49
|
+
git status --short
|
|
64
50
|
```
|
|
65
51
|
|
|
52
|
+
Stage the generated files you reviewed, then commit them. The committed
|
|
53
|
+
configuration establishes the trusted base policy used by verification. On an
|
|
54
|
+
already initialized repository, back up and review `.agent/config.yml` before
|
|
55
|
+
rerunning `init`. Existing legacy `.agent/jules.yml` files are left untouched
|
|
56
|
+
by the default path. `--force` deliberately opts back into the legacy full scaffold.
|
|
57
|
+
|
|
58
|
+
### 2. Check provider readiness
|
|
59
|
+
|
|
66
60
|
```bash
|
|
67
|
-
# Which agents can this machine dispatch to, and what is missing for the rest?
|
|
68
61
|
npx jules-orchestrator-kit providers
|
|
62
|
+
```
|
|
69
63
|
|
|
70
|
-
|
|
71
|
-
|
|
64
|
+
This reports which providers are available and what setup is missing. Remote
|
|
65
|
+
Jules dispatch needs credentials; local CLI providers need their installed,
|
|
66
|
+
authenticated CLI. Follow the
|
|
67
|
+
[configuration reference](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/configuration.md).
|
|
68
|
+
Never commit API keys.
|
|
69
|
+
|
|
70
|
+
### 3. Create and review a task
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx jules-orchestrator-kit task create \
|
|
74
|
+
--prompt "Refactor invoice calculation without changing totals" \
|
|
75
|
+
--verify "npm test"
|
|
72
76
|
```
|
|
73
77
|
|
|
74
|
-
|
|
75
|
-
|
|
78
|
+
Replace the example objective and test command with your project's requirements.
|
|
79
|
+
A task envelope is a Markdown file under `.agent/jules-queue/` containing the
|
|
80
|
+
objective, scope and verification command. Review it before sending it to an agent.
|
|
76
81
|
|
|
77
|
-
|
|
82
|
+
```bash
|
|
83
|
+
# Preview queued work without dispatching it
|
|
84
|
+
npx jules-orchestrator-kit queue --dry-run
|
|
78
85
|
|
|
79
|
-
|
|
80
|
-
|
|
86
|
+
# Send the reviewed task, using the path printed by task create
|
|
87
|
+
npx jules-orchestrator-kit dispatch ".agent/jules-queue/TASK-<id>.md"
|
|
88
|
+
```
|
|
81
89
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
| **Repo Maintainers** | Automate bug fixes, dependency bumps, and PR reviews with self-healing test loops. | `agentctl gate`<br/>`agentctl queue` |
|
|
86
|
-
| **Monorepo Teams** | Isolate subproject verification (`backend/`, `frontend/`, `cli/`) so agent edits never thrash global test suites. | `agentctl swarm`<br/>`agentctl lock` |
|
|
87
|
-
| **Platform & Security** | Enforce fail-closed security policies, pre-commit secret scrubbing (including base64), and strict 75 KB diff limits. | `agentctl doctor`<br/>`agentctl dashboard` |
|
|
90
|
+
Replace `TASK-<id>.md` with the actual filename. Dispatch can use provider quota
|
|
91
|
+
or incur provider costs. Jules can pause for plan approval; see the
|
|
92
|
+
[Jules notes](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/providers/jules.md).
|
|
88
93
|
|
|
89
|
-
###
|
|
94
|
+
### 4. Verify and review the changes
|
|
90
95
|
|
|
91
|
-
|
|
96
|
+
Once the provider's changes are available on your local branch:
|
|
92
97
|
|
|
93
|
-
|
|
98
|
+
```bash
|
|
99
|
+
npx jules-orchestrator-kit gate
|
|
100
|
+
```
|
|
94
101
|
|
|
95
|
-
|
|
102
|
+
Inspect the gate report and the complete diff before merging. For hosted Jules,
|
|
103
|
+
fetch and check out the resulting branch first; local CLI providers leave changes
|
|
104
|
+
in the working tree. Creating or dispatching an envelope does not verify the result.
|
|
96
105
|
|
|
97
|
-
|
|
106
|
+
For direct `agentctl` commands, install globally with
|
|
107
|
+
`npm install -g jules-orchestrator-kit`. All examples above also work as
|
|
108
|
+
`agentctl <command>` after installation.
|
|
98
109
|
|
|
99
|
-
|
|
100
|
-
## Architecture
|
|
110
|
+
## Key workflows
|
|
101
111
|
|
|
102
|
-
|
|
112
|
+
| Goal | Command |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| Inspect provider setup | `agentctl providers` |
|
|
115
|
+
| Create a scoped task | `agentctl task create` |
|
|
116
|
+
| Preview queued work | `agentctl queue --dry-run` |
|
|
117
|
+
| Check changes locally | `agentctl gate` |
|
|
118
|
+
| Start an explicit repair workflow | `agentctl repair --input "<failure>" --task` |
|
|
119
|
+
| Diagnose setup | `agentctl doctor` |
|
|
120
|
+
| Inspect a command's flags | `agentctl help <command>` |
|
|
103
121
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
122
|
+
Start with small changes and an observable acceptance condition. Visual decisions,
|
|
123
|
+
production credentials and integration environments need explicit human setup.
|
|
124
|
+
See [task examples](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/EXAMPLES.md).
|
|
107
125
|
|
|
108
|
-
|
|
126
|
+
## Verification profiles
|
|
109
127
|
|
|
110
|
-
|
|
128
|
+
| Profile | Verification stages |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `minimal` | Setup and tests |
|
|
131
|
+
| `standard` | Setup, lint, tests, build and diff anti-tamper checks |
|
|
132
|
+
| `max` | Standard stages plus mutation scoring, Node V8 diff coverage and flakiness probes |
|
|
111
133
|
|
|
112
|
-
|
|
113
|
-
|
|
134
|
+
Select with `agentctl profile --set standard`. Stages depend on the detected stack
|
|
135
|
+
and configuration; unsupported checks are reported. Review those diagnostics
|
|
136
|
+
rather than assuming every profile runs every check on every language.
|
|
114
137
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
| `standard` | Setup → Lint → Tests → Build → Diff Anti-Tamper | Default gate for routine pull requests. |
|
|
119
|
-
| `max` | All stages above → AST Mutation Scoring → V8 Diff Coverage *(Node)* → 3-Pass Flakiness Probe | High-risk refactors or critical infrastructure changes. |
|
|
138
|
+
Local checks do not require a provider API key. The project's configured commands
|
|
139
|
+
may themselves need dependencies, services or network access. Automated repairs
|
|
140
|
+
require a provider.
|
|
120
141
|
|
|
121
|
-
|
|
142
|
+
## Architecture
|
|
122
143
|
|
|
123
|
-
|
|
144
|
+
The dispatch pipeline builds task context and calls a provider. The verification
|
|
145
|
+
pipeline evaluates scope, payload, security findings and configured commands.
|
|
146
|
+
The repository and local state connect them. The package exposes an ESM SDK and a
|
|
147
|
+
stdio MCP server alongside the CLI.
|
|
124
148
|
|
|
125
|
-
|
|
149
|
+
See [architecture and exit codes](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/architecture.md)
|
|
150
|
+
and [SDK/MCP integration](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/sdk.md).
|
|
126
151
|
|
|
127
|
-
<a id="cli"></a>
|
|
128
152
|
## CLI
|
|
129
153
|
|
|
130
|
-
`agentctl` is the unified CLI, available via `npx jules-orchestrator-kit <command>` or `agentctl <command>`. Core commands:
|
|
131
|
-
|
|
132
154
|
| Command | Description |
|
|
133
|
-
|
|
|
134
|
-
| `
|
|
135
|
-
| `task create` / `task template` | Author falsifiable task envelopes, or synthesize pre-calibrated ones (Web, Hardening, Universal, Deep Think). |
|
|
136
|
-
| `dispatch` / `queue` / `swarm` | Send tasks to the active provider, run queued envelopes with DAG resolution, or run parallel worker slots. |
|
|
137
|
-
| `check` / `gate` | Security, secret, scope, payload, and tiered verification gates with `--fix` OODA repair. |
|
|
138
|
-
| `mutate` / `coverage` / `probe` / `perf` | Diff mutation scoring, V8 diff coverage, flakiness probing, event-loop lag. |
|
|
139
|
-
| `providers` / `provider set` / `profile` / `ci init` | Provider readiness, switching, verification depth, stack-native CI generation. |
|
|
140
|
-
| `doctor` / `evidence` / `flaky` / `rollback` | Diagnostics, SHA-256 evidence manifests, flaky quarantine management, checkpoint restore. |
|
|
141
|
-
| `dashboard` | `agentctl dashboard [port] [--port <n>]` — zero-dependency local telemetry & audit visualizer (default port 4100; valid range 1024–65535). |
|
|
142
|
-
| `mcp` / `mcp init` | stdio Model Context Protocol server for Claude, Cursor, and Antigravity, plus 1-click client config. |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `dashboard` | Local telemetry viewer; default port 4100. Set another port with `--port <n>`. |
|
|
143
157
|
|
|
144
|
-
The exhaustive per-command flag reference is generated from the same registry that powers `--help`: [docs/COMMAND_REFERENCE.md](docs/COMMAND_REFERENCE.md). Exit codes `0`–`8` are standardized — see the registry in [AGENTS.md](AGENTS.md#6-exit-code-registry--remediation-matrix).
|
|
145
158
|
|
|
146
|
-
|
|
159
|
+
The [command reference](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/COMMAND_REFERENCE.md)
|
|
160
|
+
is generated from the registry used by `--help`. It covers dispatch, queues,
|
|
161
|
+
verification, evidence, diagnostics and the supported aliases.
|
|
147
162
|
|
|
148
|
-
##
|
|
163
|
+
## Development and verification
|
|
149
164
|
|
|
150
|
-
|
|
165
|
+
Clone this repository to run its tests; the npm package excludes the test suite.
|
|
151
166
|
|
|
152
167
|
```bash
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
.github/workflows/agent-gate.yml \
|
|
161
|
-
.gitlab-ci.agent-gate.yml \
|
|
162
|
-
.cursor/rules/jules.mdc
|
|
163
|
-
|
|
164
|
-
# Remove untracked runtime directories and temporary caches
|
|
165
|
-
rm -rf .agent .agentctl
|
|
166
|
-
|
|
167
|
-
# Revert the appended runtime-state block in .gitignore, then optionally:
|
|
168
|
-
npm uninstall -g jules-orchestrator-kit
|
|
168
|
+
npm ci
|
|
169
|
+
npm test
|
|
170
|
+
npm run lint
|
|
171
|
+
npm run jules:doc-sync
|
|
172
|
+
npm run jules:rules-lint
|
|
173
|
+
npm run package-integrity
|
|
174
|
+
npm run guard-reach
|
|
169
175
|
```
|
|
170
176
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
Start at the **[docs sitemap](docs/README.md)** — it maps "I want to …" workflows to the right page: [Configuration Reference](docs/configuration.md) · [CLI Command Reference](docs/COMMAND_REFERENCE.md) · [Architecture & Pipeline Flow](docs/architecture.md) · [SDK & MCP Integrations](docs/sdk.md) · [Examples & Task Envelopes](EXAMPLES.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP_V1.md) · [Security Policy](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Contributors & Provenance](CONTRIBUTORS.md) · [Google Jules Official Documentation](https://jules.google).
|
|
177
|
+
The recorded baseline is **1553 unit tests across 204 suites**. Doc-sync compares
|
|
178
|
+
that count with an actual run. Counts do not establish correctness for every
|
|
179
|
+
provider or project. See
|
|
180
|
+
[contributing](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CONTRIBUTING.md)
|
|
181
|
+
for the review process.
|
|
178
182
|
|
|
179
|
-
|
|
183
|
+
## Documentation and removal
|
|
180
184
|
|
|
181
|
-
|
|
185
|
+
- [Documentation index](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/README.md)
|
|
186
|
+
- [Configuration](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/configuration.md)
|
|
187
|
+
- [Uninstall and generated-file inventory](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/docs/uninstall.md)
|
|
188
|
+
- [Changelog](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CHANGELOG.md)
|
|
189
|
+
- [Security policy](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/SECURITY.md)
|
|
182
190
|
|
|
183
|
-
|
|
191
|
+
## Complete Uninstall / Removing the Kit (Undo Init)
|
|
184
192
|
|
|
185
|
-
|
|
193
|
+
`agentctl clean` performs operational maintenance; it is not an uninstaller.
|
|
194
|
+
First identify which files setup created and which files already belonged to your
|
|
195
|
+
project. For shared files, remove only the kit's additions using Git history.
|
|
186
196
|
|
|
187
|
-
|
|
197
|
+
For the default minimal setup, remove `.agent/config.yml` and the kit's
|
|
198
|
+
runtime-state block from `.gitignore`. Repositories that previously used the
|
|
199
|
+
legacy full scaffold may also contain AGENTS.md, prompts, rules, workflows and
|
|
200
|
+
contract files; remove those only after confirming ownership.
|
|
188
201
|
|
|
189
|
-
|
|
202
|
+
See the uninstall guide for the complete inventory and legacy cleanup steps.
|
|
190
203
|
|
|
191
|
-
|
|
204
|
+
## Limitations and attribution
|
|
192
205
|
|
|
193
|
-
|
|
206
|
+
Secret scanning, test-tamper detection and prompt transformations are checks with
|
|
207
|
+
coverage limits, not a security guarantee. Prompt substitutions can change meaning;
|
|
208
|
+
review exact operational instructions. See the Jules notes for details.
|
|
194
209
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
210
|
+
Maintained by Jonas Pudas with agent-assisted contributions recorded in Git history
|
|
211
|
+
and the [contributors ledger](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CONTRIBUTORS.md).
|
|
212
|
+
Licensed under MIT. This independent project is not affiliated with or endorsed by
|
|
213
|
+
Google; Google and Google Jules are trademarks of their respective owners.
|
package/bin/agentctl.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { parseArgs } from "node:util";
|
|
4
4
|
import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync } from "node:fs";
|
|
5
|
-
import { join, resolve } from "node:path";
|
|
5
|
+
import { join, resolve, relative } from "node:path";
|
|
6
6
|
import { applyEnvAliases } from "../src/env-aliases.mjs";
|
|
7
7
|
import { selectFailureOutput } from "../src/ops/verify-output.mjs";
|
|
8
8
|
import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
|
|
@@ -22,7 +22,18 @@ import { COMMAND_REGISTRY } from "../src/ops/command-registry.mjs";
|
|
|
22
22
|
applyEnvAliases(process.env);
|
|
23
23
|
|
|
24
24
|
const args = process.argv.slice(2);
|
|
25
|
-
const
|
|
25
|
+
const requestedCommand = args[0] || "";
|
|
26
|
+
const gateCommands = new Set(["gate", "check", "audit"]);
|
|
27
|
+
|
|
28
|
+
if (gateCommands.has(requestedCommand) && args.includes("--fix")) {
|
|
29
|
+
console.error("Error: `agentctl gate` is non-mutating; `--fix` no longer dispatches automated repairs.");
|
|
30
|
+
console.error("Run the gate normally, then use `agentctl repair` explicitly with the failure trace you want repaired.");
|
|
31
|
+
process.exit(2);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// `repair` is the canonical spelling; `fix` remains a 0.x compatibility
|
|
35
|
+
// alias. Both route through the same existing implementation below.
|
|
36
|
+
const command = requestedCommand;
|
|
26
37
|
|
|
27
38
|
export const VERSION = KIT_VERSION;
|
|
28
39
|
|
|
@@ -294,8 +305,13 @@ async function main() {
|
|
|
294
305
|
}
|
|
295
306
|
|
|
296
307
|
const root = resolveRoot();
|
|
297
|
-
|
|
298
|
-
|
|
308
|
+
// Init is a configuration boundary, not an operational maintenance command.
|
|
309
|
+
// In particular, --dry-run must not create .agent/ indirectly by reaping
|
|
310
|
+
// journal intents or mutex directories before init itself gets control.
|
|
311
|
+
if (command !== "init") {
|
|
312
|
+
reapOrphanedIntents(root);
|
|
313
|
+
reapStaleMutexDirs(root);
|
|
314
|
+
}
|
|
299
315
|
const config = loadConfig(root);
|
|
300
316
|
|
|
301
317
|
switch (command) {
|
|
@@ -361,7 +377,7 @@ async function main() {
|
|
|
361
377
|
console.error(
|
|
362
378
|
`Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Auditor, Performance, Security, Hygiene, Testing).`
|
|
363
379
|
);
|
|
364
|
-
console.error(`
|
|
380
|
+
console.error(` Use a canonical shipped role name or add a repository override under .agent/prompts/.`);
|
|
365
381
|
process.exit(1);
|
|
366
382
|
}
|
|
367
383
|
}
|
|
@@ -676,7 +692,7 @@ async function main() {
|
|
|
676
692
|
} else if (failedPhase === "verify" || failedPhase === "evidence") {
|
|
677
693
|
console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
|
|
678
694
|
console.log(` • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);
|
|
679
|
-
console.log(` • To
|
|
695
|
+
console.log(` • To start an explicit repair workflow, pipe the failing command's output to: agentctl repair\n`);
|
|
680
696
|
} else if (res.code === 3) {
|
|
681
697
|
// The same violation has two very different causes. Right after
|
|
682
698
|
// `init`, every offending path is a file the tool itself just wrote
|
|
@@ -965,6 +981,7 @@ async function main() {
|
|
|
965
981
|
break;
|
|
966
982
|
}
|
|
967
983
|
|
|
984
|
+
case "repair":
|
|
968
985
|
case "fix": {
|
|
969
986
|
const { repair, planTaskCreate, resolveRoot, redactSecrets } = await import("../index.mjs");
|
|
970
987
|
const { values, positionals } = parseArgs({
|
|
@@ -996,7 +1013,7 @@ async function main() {
|
|
|
996
1013
|
}
|
|
997
1014
|
|
|
998
1015
|
if (!errorInput.trim()) {
|
|
999
|
-
console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl
|
|
1016
|
+
console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl repair` or provide --file/--input.");
|
|
1000
1017
|
process.exit(1);
|
|
1001
1018
|
}
|
|
1002
1019
|
|
|
@@ -1957,19 +1974,54 @@ async function main() {
|
|
|
1957
1974
|
provider: values.provider,
|
|
1958
1975
|
profile: values.profile,
|
|
1959
1976
|
allowDefaults: true,
|
|
1977
|
+
dryRun: values["dry-run"],
|
|
1978
|
+
// --force is retained as the explicit 0.x compatibility path: it
|
|
1979
|
+
// restores the legacy Jules manifest and full repository scaffold.
|
|
1980
|
+
legacyManifest: values.force,
|
|
1981
|
+
// JSON mode is a protocol surface: progress spinners must not prefix
|
|
1982
|
+
// the payload with human-readable status lines.
|
|
1983
|
+
stdout: values.json ? { write() {} } : process.stdout,
|
|
1960
1984
|
});
|
|
1961
1985
|
|
|
1962
|
-
//
|
|
1963
|
-
//
|
|
1964
|
-
//
|
|
1965
|
-
|
|
1966
|
-
|
|
1967
|
-
|
|
1986
|
+
// Default init deliberately owns only the canonical config plus the
|
|
1987
|
+
// runtime-state ignore block. The old full scaffold is opt-in via
|
|
1988
|
+
// --force (and remains available through the shipped jules-init binary).
|
|
1989
|
+
const {
|
|
1990
|
+
ensureGitignore,
|
|
1991
|
+
planGitignoreEntries,
|
|
1992
|
+
planScaffoldRepoAssets,
|
|
1993
|
+
scaffoldRepoAssets,
|
|
1994
|
+
} = await import("../src/scaffold.mjs");
|
|
1995
|
+
const plannedGitignore = planGitignoreEntries(root);
|
|
1996
|
+
const legacyPlan = values.force ? planScaffoldRepoAssets(root, { force: true }) : { created: [], gitignore: plannedGitignore };
|
|
1997
|
+
const scaffold =
|
|
1998
|
+
values.force && !values["dry-run"]
|
|
1999
|
+
? scaffoldRepoAssets(root, { force: true })
|
|
2000
|
+
: { created: legacyPlan.created, gitignore: plannedGitignore };
|
|
2001
|
+
const gitignore =
|
|
2002
|
+
values["dry-run"]
|
|
2003
|
+
? plannedGitignore
|
|
2004
|
+
: values.force
|
|
2005
|
+
? scaffold.gitignore
|
|
2006
|
+
: ensureGitignore(root);
|
|
2007
|
+
const writes = [
|
|
2008
|
+
...res.writes.map((p) => (relative(root, p) || p).replaceAll("\\", "/")),
|
|
2009
|
+
...legacyPlan.created,
|
|
2010
|
+
...(plannedGitignore.length > 0 ? [".gitignore"] : []),
|
|
2011
|
+
].filter((p, index, all) => all.indexOf(p) === index);
|
|
1968
2012
|
|
|
1969
2013
|
if (values.json) {
|
|
1970
|
-
console.log(JSON.stringify({ ...res,
|
|
2014
|
+
console.log(JSON.stringify({ ...res, writes, gitignore }, null, 2));
|
|
1971
2015
|
} else {
|
|
1972
|
-
console.log(
|
|
2016
|
+
console.log(
|
|
2017
|
+
values["dry-run"]
|
|
2018
|
+
? "🧪 Dry run — no files written."
|
|
2019
|
+
: `✅ Onboarding complete! Manifest generated at ${res.configPath}`
|
|
2020
|
+
);
|
|
2021
|
+
if (values["dry-run"]) {
|
|
2022
|
+
console.log(" Would write:");
|
|
2023
|
+
for (const path of writes) console.log(` - ${path}`);
|
|
2024
|
+
}
|
|
1973
2025
|
console.log(` Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
|
|
1974
2026
|
{
|
|
1975
2027
|
const { probeProvider } = await import("../src/provider-readiness.mjs");
|
|
@@ -1988,34 +2040,35 @@ async function main() {
|
|
|
1988
2040
|
console.log(` Verification Test Command : None detected (run "agentctl bootstrap" to create a test oracle)`);
|
|
1989
2041
|
}
|
|
1990
2042
|
console.log(` Active Presets : ${res.plan.presets.join(", ")}`);
|
|
1991
|
-
|
|
1992
|
-
|
|
1993
|
-
|
|
1994
|
-
|
|
1995
|
-
|
|
1996
|
-
}
|
|
1997
|
-
|
|
1998
|
-
|
|
1999
|
-
|
|
2000
|
-
|
|
2001
|
-
|
|
2002
|
-
|
|
2003
|
-
|
|
2004
|
-
|
|
2005
|
-
|
|
2006
|
-
|
|
2007
|
-
|
|
2008
|
-
|
|
2009
|
-
|
|
2010
|
-
|
|
2011
|
-
|
|
2012
|
-
.filter((
|
|
2013
|
-
|
|
2014
|
-
|
|
2015
|
-
|
|
2016
|
-
|
|
2017
|
-
|
|
2018
|
-
|
|
2043
|
+
if (values.force) {
|
|
2044
|
+
const verb = values["dry-run"] ? "Would scaffold (legacy)" : "Scaffolded (legacy)";
|
|
2045
|
+
for (const item of legacyPlan.created) {
|
|
2046
|
+
console.log(` ${verb.padEnd(26)}: ${item}`);
|
|
2047
|
+
}
|
|
2048
|
+
}
|
|
2049
|
+
if (!values["dry-run"] && gitignore.length > 0) {
|
|
2050
|
+
console.log(` Ignored runtime state : ${gitignore.length} entries added to .gitignore`);
|
|
2051
|
+
}
|
|
2052
|
+
|
|
2053
|
+
if (!values["dry-run"]) {
|
|
2054
|
+
// A fresh `npm install`/`npm init -y` may have created package
|
|
2055
|
+
// manifests the scope rules protect. Include only files that really
|
|
2056
|
+
// exist; minimal init itself owns .agent/config.yml and, when needed,
|
|
2057
|
+
// the .gitignore runtime-state block.
|
|
2058
|
+
const { addableOnboardingArtifacts } = await import("../src/git.mjs");
|
|
2059
|
+
const filesToAdd = [
|
|
2060
|
+
".agent/config.yml",
|
|
2061
|
+
...(values.force ? [".agent/jules.yml", ...legacyPlan.created] : []),
|
|
2062
|
+
...addableOnboardingArtifacts(root),
|
|
2063
|
+
".gitignore",
|
|
2064
|
+
].filter((p, index, all) => all.indexOf(p) === index && existsSync(join(root, p)));
|
|
2065
|
+
console.log(`\n Commit the config so the gate does not read it as an agent edit:`);
|
|
2066
|
+
console.log(` git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
|
|
2067
|
+
|
|
2068
|
+
const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
|
|
2069
|
+
const next = resolveNextStep(root);
|
|
2070
|
+
console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
|
|
2071
|
+
}
|
|
2019
2072
|
}
|
|
2020
2073
|
process.exit(0);
|
|
2021
2074
|
break;
|
package/bin/init.js
CHANGED
|
@@ -40,12 +40,14 @@ try {
|
|
|
40
40
|
|
|
41
41
|
if (isHelp) {
|
|
42
42
|
console.log(`
|
|
43
|
-
Google Jules Orchestration Kit -
|
|
43
|
+
Google Jules Orchestration Kit - Legacy Full Scaffold
|
|
44
44
|
|
|
45
45
|
Usage:
|
|
46
|
-
npx jules-orchestrator-kit [options]
|
|
47
46
|
npx jules-init [options]
|
|
48
47
|
|
|
48
|
+
For the minimal canonical setup, use:
|
|
49
|
+
npx jules-orchestrator-kit init
|
|
50
|
+
|
|
49
51
|
Options:
|
|
50
52
|
-f, --force Overwrite existing AGENTS.md, .agent/jules.yml, and orchestration scripts.
|
|
51
53
|
-i, --interactive Launch interactive wizard to prompt for repository and branch configuration.
|
|
@@ -119,10 +121,9 @@ if (detected.testCmd || detected.buildCmd) {
|
|
|
119
121
|
console.log(` - Build Command: ${detected.buildCmd || "(none)"}`);
|
|
120
122
|
}
|
|
121
123
|
|
|
122
|
-
// 2-3.
|
|
123
|
-
//
|
|
124
|
-
//
|
|
125
|
-
// quickstart pointing at the one that scaffolded less.
|
|
124
|
+
// 2-3. Legacy full scaffold: AGENTS.md, .agent/ role prompts, rules and
|
|
125
|
+
// workflows. The canonical `agentctl init` path is intentionally smaller now;
|
|
126
|
+
// this entry point remains for 0.x repositories that still want the full bundle.
|
|
126
127
|
const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
|
|
127
128
|
const scaffolded = scaffoldRepoAssets(targetDir, { force: isForce });
|
|
128
129
|
for (const item of scaffolded.created) {
|
|
@@ -133,11 +134,8 @@ const agentDir = path.join(targetDir, ".agent");
|
|
|
133
134
|
|
|
134
135
|
// Scaffold the manifest pair.
|
|
135
136
|
//
|
|
136
|
-
// This entry point
|
|
137
|
-
//
|
|
138
|
-
// which of the two scaffolders you happened to run decided whether the
|
|
139
|
-
// repository had a provider, a tier and a verification profile at all. Both
|
|
140
|
-
// now go through `planInit`.
|
|
137
|
+
// This compatibility entry point still writes both manifests, but derives them
|
|
138
|
+
// from the same `planInit` model as the canonical path so values cannot drift.
|
|
141
139
|
const { planInit } = await import("../src/wizard-init.mjs");
|
|
142
140
|
const initPlan = planInit(targetDir, {
|
|
143
141
|
testCmd: detected.testCmd,
|
|
@@ -226,8 +224,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
|
|
|
226
224
|
}
|
|
227
225
|
}
|
|
228
226
|
|
|
229
|
-
// 5b.
|
|
230
|
-
// two entry points cannot disagree about which runtime paths stay untracked.
|
|
227
|
+
// 5b. Reuse the same runtime ignore policy as canonical init.
|
|
231
228
|
if (scaffolded.gitignore.length > 0) {
|
|
232
229
|
console.log(`✅ Added ${scaffolded.gitignore.length} runtime state entries to .gitignore`);
|
|
233
230
|
}
|