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 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
  [![NPM Version](https://img.shields.io/npm/v/ai-engineering-loop.svg?color=cb3837)](https://www.npmjs.com/package/ai-engineering-loop)
6
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
6
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
8
7
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
9
- [![Release](https://img.shields.io/badge/release-v1.2.1-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
8
+ [![Release](https://img.shields.io/badge/release-v1.6.0-purple.svg)](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
- │ └── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
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.