ai-engineering-loop 1.2.1 → 1.6.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 +47 -4
- package/README.npm.md +7 -0
- package/SECURITY.md +3 -1
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +432 -11
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/local-workflow-studio.md +77 -0
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +42 -4
- package/lib/doctor.js +26 -2
- package/lib/handoff.js +209 -0
- package/lib/node-registry.js +155 -0
- package/lib/recipe-builder.js +200 -0
- package/lib/recipe.js +495 -0
- package/lib/run-state.js +50 -3
- package/lib/runtime-files.js +2 -0
- package/lib/studio-server.js +183 -0
- package/lib/workflow-runtime.js +718 -0
- package/package.json +3 -1
- package/recipes/audit.json +32 -0
- package/recipes/bugfix.json +63 -0
- package/recipes/default.json +49 -0
- package/recipes/docs-light.json +63 -0
- package/recipes/high-risk.json +69 -0
- package/recipes/refactor.json +63 -0
- package/schemas/compiled-plan.schema.json +19 -0
- package/schemas/handoff.schema.json +36 -0
- package/schemas/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/workflow-event.schema.json +29 -0
- package/schemas/workflow-state.schema.json +29 -0
- package/studio/app.js +461 -0
- package/studio/index.html +31 -0
- package/studio/styles.css +75 -0
package/README.md
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
|
-
# AI Engineering Loop
|
|
2
|
-
|
|
3
1
|
<div align="center">
|
|
2
|
+
<h1>AI Engineering Loop</h1>
|
|
4
3
|
|
|
5
4
|
[](https://www.npmjs.com/package/ai-engineering-loop)
|
|
6
5
|
[](https://opensource.org/licenses/MIT)
|
|
7
6
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
8
7
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
9
|
-
[](https://github.com/egagofur/ai-engineering-loop/releases)
|
|
10
9
|
|
|
11
10
|
**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
|
|
12
11
|
|
|
@@ -183,6 +182,7 @@ npx ai-engineering-loop refresh
|
|
|
183
182
|
# Start or resume a stateful engineering run
|
|
184
183
|
npx ai-engineering-loop run
|
|
185
184
|
npx ai-engineering-loop run --mode report-only "audit this repository"
|
|
185
|
+
npx ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
|
|
186
186
|
|
|
187
187
|
# Inspect the run ledger
|
|
188
188
|
npx ai-engineering-loop state --json
|
|
@@ -196,6 +196,8 @@ npx ai-engineering-loop budget resume
|
|
|
196
196
|
|
|
197
197
|
# Record actual provider-reported usage after each model response
|
|
198
198
|
npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
|
|
199
|
+
npx ai-engineering-loop budget status --node root-cause --estimate 4000
|
|
200
|
+
npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
|
|
199
201
|
|
|
200
202
|
# Isolate unattended Maker, then capture only its diff
|
|
201
203
|
npx ai-engineering-loop sandbox create
|
|
@@ -219,6 +221,35 @@ npx ai-engineering-loop context judge <files...>
|
|
|
219
221
|
npx ai-engineering-loop doctor
|
|
220
222
|
npx ai-engineering-loop eval
|
|
221
223
|
|
|
224
|
+
# Inspect declarative workflow recipes without executing nodes
|
|
225
|
+
npx ai-engineering-loop recipe list
|
|
226
|
+
npx ai-engineering-loop recipe validate default --mode assisted
|
|
227
|
+
npx ai-engineering-loop recipe explain default --mode assisted
|
|
228
|
+
npx ai-engineering-loop recipe graph default --mode assisted
|
|
229
|
+
npx ai-engineering-loop recipe simulate default --mode assisted
|
|
230
|
+
npx ai-engineering-loop recipe catalog --json
|
|
231
|
+
npx ai-engineering-loop recipe create api-bugfix --from bugfix
|
|
232
|
+
npx ai-engineering-loop recipe inspect api-bugfix --json
|
|
233
|
+
npx ai-engineering-loop recipe diff bugfix api-bugfix
|
|
234
|
+
npx ai-engineering-loop recipe install candidate.json
|
|
235
|
+
npx ai-engineering-loop recipe install candidate-v2.json --replace
|
|
236
|
+
|
|
237
|
+
# Operate a custom node in an immutable recipe-bound run
|
|
238
|
+
npx ai-engineering-loop node status
|
|
239
|
+
npx ai-engineering-loop node start root-cause
|
|
240
|
+
npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
|
|
241
|
+
npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
242
|
+
npx ai-engineering-loop node approve delivery-approval --yes
|
|
243
|
+
|
|
244
|
+
# Open the local workflow canvas (localhost-only, authenticated session)
|
|
245
|
+
npx ai-engineering-loop studio
|
|
246
|
+
npx ai-engineering-loop studio --port 4400 --no-open
|
|
247
|
+
|
|
248
|
+
# Transfer redacted knowledge to another developer or agent
|
|
249
|
+
npx ai-engineering-loop handoff create --audience developer
|
|
250
|
+
npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
|
|
251
|
+
npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
|
|
252
|
+
|
|
222
253
|
# Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
223
254
|
npx ai-engineering-loop sync-hosts
|
|
224
255
|
|
|
@@ -233,6 +264,10 @@ npx ai-engineering-loop generate-workflow --write
|
|
|
233
264
|
|
|
234
265
|
Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Usage, worktrees, locks, context packs, and logs are Git-ignored. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. `ASSISTED` is the default and requires explicit human delivery approval. `UNATTENDED` is disabled until a human enables it. See [`core/runtime-safety.md`](core/runtime-safety.md), [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
|
|
235
266
|
|
|
267
|
+
Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
|
|
268
|
+
|
|
269
|
+
The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, and preserves replaced versions locally. Workflow Studio is a thin local interface over that compiler and controlled runtime: animated DAG state, live activity and budget telemetry, explicit approval/retry controls, decision memory, and integrity-bound handoff export—without model or shell execution in the browser. See [`core/local-workflow-studio.md`](core/local-workflow-studio.md). The host-neutral agent protocol remains available in [`agents/recipe-builder.md`](agents/recipe-builder.md).
|
|
270
|
+
|
|
236
271
|
Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
|
|
237
272
|
|
|
238
273
|
`sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
|
|
@@ -321,7 +356,13 @@ ai-engineering-loop/
|
|
|
321
356
|
│ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
|
|
322
357
|
│
|
|
323
358
|
├── lib/ # Core orchestration & decision engine
|
|
324
|
-
│
|
|
359
|
+
│ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
|
|
360
|
+
│ ├── recipe.js # Declarative graph validator and deterministic compiler
|
|
361
|
+
│ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
|
|
362
|
+
│
|
|
363
|
+
├── recipes/ # Built-in workflow presets; target repos may add their own
|
|
364
|
+
│ ├── default.json # Current production loop represented as a graph
|
|
365
|
+
│ └── audit.json # Read-only report workflow
|
|
325
366
|
│
|
|
326
367
|
├── tests/ # Deterministic test suites
|
|
327
368
|
│ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
|
|
@@ -360,6 +401,8 @@ ai-engineering-loop/
|
|
|
360
401
|
│ ├── escalation-policy.md # Deterministic human escalation triggers
|
|
361
402
|
│ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
|
|
362
403
|
│ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
|
|
404
|
+
│ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
|
|
405
|
+
│ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
|
|
363
406
|
│ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
|
|
364
407
|
│
|
|
365
408
|
├── profiles/ # Project archetype profiles
|
package/README.npm.md
CHANGED
|
@@ -34,6 +34,12 @@ npx ai-engineering-loop run --mode report-only "audit this repository"
|
|
|
34
34
|
npx ai-engineering-loop policy show
|
|
35
35
|
npx ai-engineering-loop budget status
|
|
36
36
|
|
|
37
|
+
# Author and observe deterministic workflow recipes locally
|
|
38
|
+
npx ai-engineering-loop studio
|
|
39
|
+
|
|
40
|
+
# Export a redacted, integrity-bound knowledge handoff
|
|
41
|
+
npx ai-engineering-loop handoff create --audience developer
|
|
42
|
+
|
|
37
43
|
# 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
38
44
|
npx ai-engineering-loop sync-hosts
|
|
39
45
|
```
|
|
@@ -48,6 +54,7 @@ npx ai-engineering-loop sync-hosts
|
|
|
48
54
|
4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
|
|
49
55
|
5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
|
|
50
56
|
6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, a persistent kill switch, and locked disposable Maker worktrees.
|
|
57
|
+
7. **Local Workflow Studio**: A localhost-only authenticated DAG canvas with animated live stage state, token telemetry, explicit approvals, decision memory, atomic recipe installation, and redacted handoff export. It does not execute models or shell commands in the browser.
|
|
51
58
|
|
|
52
59
|
---
|
|
53
60
|
|
package/SECURITY.md
CHANGED
|
@@ -8,6 +8,8 @@ AI Engineering Loop blocks `.env*`, private-key formats, common credential files
|
|
|
8
8
|
|
|
9
9
|
No telemetry is collected. Token usage ledgers stay local and contain counts plus provider model identifiers, not prompts or responses. Stage 0–7 require no AI Engineering Loop network service. Delivery adapters may use authenticated forge tools only after Judge `PASS`; ASSISTED requires explicit human approval before delivery.
|
|
10
10
|
|
|
11
|
+
Workflow Studio binds to `127.0.0.1`, validates local `Host` headers, and requires a random process-local session token exchanged for an HttpOnly SameSite cookie. Its bundled browser client has no model, shell, telemetry, or remote-asset capability. Do not expose the Studio port through a reverse proxy or public tunnel. Handoff exports omit source content and redact recognized secrets and home paths; verify their integrity hash on import, and still review them before sharing because pattern-based redaction cannot recognize every private value.
|
|
12
|
+
|
|
11
13
|
UNATTENDED is disabled by default and Maker uses a locked disposable Git worktree when enabled. This protects the parent checkout and prevents concurrent Maker sessions; it is not an OS sandbox. For untrusted code, use a container or VM with restricted credentials, filesystem, processes, and network. See `core/runtime-safety.md`.
|
|
12
14
|
|
|
13
15
|
Package releases use npm trusted publishing from `.github/workflows/publish.yml`, with a pinned OIDC-capable npm CLI and provenance. The package owner must configure `egagofur/ai-engineering-loop`, workflow `publish.yml`, and environment `npm` as the trusted publisher on npmjs.com. Do not add `NPM_TOKEN` or another long-lived publish credential to the repository or GitHub environment.
|
|
@@ -18,7 +20,7 @@ Package releases use npm trusted publishing from `.github/workflows/publish.yml`
|
|
|
18
20
|
- Never place credentials in `.ai-engineering-loop/`, workflow files, prompts, findings, or delivery reports.
|
|
19
21
|
- Do not pass the parent process environment to a child unless the host owns that boundary.
|
|
20
22
|
- Treat generated run artifacts as sensitive local files. The CLI writes state and context packs with mode `0600` where supported.
|
|
21
|
-
- Keep `runs/`, `usage/`, `worktrees/`, `locks/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
|
|
23
|
+
- Keep `runs/`, `usage/`, `worktrees/`, `locks/`, temporary Studio `drafts/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
|
|
22
24
|
- Use `budget pause` to stop new model boundaries if spend, behavior, or credentials are in doubt. Recording an already completed call remains possible while paused.
|
|
23
25
|
- Run a dedicated secret scanner such as `gitleaks` before delivery when available.
|
|
24
26
|
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Recipe Builder Agent
|
|
2
|
+
|
|
3
|
+
You author workflow proposals; you do not bypass the recipe compiler or execute a proposed workflow.
|
|
4
|
+
|
|
5
|
+
## Interview
|
|
6
|
+
|
|
7
|
+
Ask only unanswered questions:
|
|
8
|
+
|
|
9
|
+
1. What outcome should the workflow produce?
|
|
10
|
+
2. Which modes are allowed: `REPORT_ONLY`, `ASSISTED`, or `UNATTENDED`?
|
|
11
|
+
3. May it mutate the repository?
|
|
12
|
+
4. What analysis is required before Maker?
|
|
13
|
+
5. Where is explicit human approval required?
|
|
14
|
+
6. What are the maximum files and tokens for each agent node?
|
|
15
|
+
7. Is delivery risk low, medium, or high?
|
|
16
|
+
|
|
17
|
+
## Authoring protocol
|
|
18
|
+
|
|
19
|
+
1. Run `ai-engineering-loop recipe catalog --json`.
|
|
20
|
+
2. Select the closest built-in preset.
|
|
21
|
+
3. Run `recipe create <id> --from <preset>`; never start from an unconstrained blank graph.
|
|
22
|
+
4. Make the smallest meaningful edits to the project recipe.
|
|
23
|
+
5. Run `recipe validate`, `recipe inspect`, `recipe diff <preset> <id>`, `recipe explain`, `recipe graph`, and `recipe simulate`.
|
|
24
|
+
6. Present validation, diff, graph hash, model calls, token ceiling, mutations, side effects, and approvals.
|
|
25
|
+
7. Ask for explicit human approval.
|
|
26
|
+
8. For a separately prepared candidate, use `recipe install <path>` only after approval. Existing recipes require `--replace` and a higher version.
|
|
27
|
+
|
|
28
|
+
Never add executable code, shell text, remote schema URLs, conditional mandatory safety gates, or mutation to `REPORT_ONLY`. Never claim validation or simulation executed a workflow.
|