ai-engineering-loop 1.6.0 → 1.7.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
@@ -5,7 +5,7 @@
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
6
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
7
7
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
8
- [![Release](https://img.shields.io/badge/release-v1.6.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
8
+ [![Release](https://img.shields.io/badge/release-v1.7.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
9
9
 
10
10
  **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
11
11
 
@@ -19,41 +19,9 @@
19
19
 
20
20
  ## Overview & Philosophy
21
21
 
22
- The AI Engineering Loop enforces clean architectural separation across three core layers:
23
-
24
- ```mermaid
25
- flowchart TD
26
- Start([User Task in Workspace]) --> PreCheck{Pre-Task Drift Check: metadata.json}
27
-
28
- PreCheck -->|Context Missing| AutoInit[Stage 0: Bootstrap .ai-engineering-loop/]
29
- PreCheck -->|Drift Detected| Reconcile[Stage 0: Reconcile Drifted Context]
30
- PreCheck -->|Context Fresh| GC[Stage 1: Goal Contract: Explicit Acceptance Criteria]
31
-
32
- AutoInit --> GC
33
- Reconcile --> GC
34
-
35
- subgraph CoreEngine [AI ENGINEERING OPERATING SYSTEM]
36
- GC --> RCA[Stage 2: Root Cause Analysis]
37
- RCA --> Plan[Stage 3: Implementation Plan]
38
- Plan --> MA[Stage 4: Maker Agent: Surgical Diff & Tests]
39
- MA --> DV{Stage 5: Deterministic Verification<br>Evidence Contract: Exit Code 0 & Full Logs}
40
-
41
- DV -->|Fail| MA
42
- DV -->|Pass| DA[Stage 6: Devil's Advocate Review<br>Capability Registry & Artifact Barrier]
43
-
44
- DA --> JD[Stage 7: Judge Agent: Impartial Magistrate<br>Validity + Severity Decision Matrix]
45
- end
46
-
47
- JD -->|VALID BLOCKER / HIGH: ITERATE| MA
48
- JD -->|INVALID: Dismissed / VALID LOW: Tradeoff| CheckDoD{All ACs Verified?}
49
-
50
- CheckDoD -->|Yes: PASS| ImpactEval{Post-Task Context Impact Assessment}
51
- ImpactEval -->|NONE: Typo, UI tweak| Adapter[Stage 8: Delivery Adapter: GitLab / GitHub]
52
- ImpactEval -->|TARGETED: Dep/route changed| PartialRefresh[Surgical Context Update] --> Adapter
53
- ImpactEval -->|MAJOR: Framework migration| FullRefresh[Full Context Reconciliation] --> Adapter
54
-
55
- Adapter --> TargetRepo[(Target Repository)]
56
- ```
22
+ The AI Engineering Loop keeps one understandable path across four phases. Deterministic gates—not model confidence—decide when work can advance:
23
+
24
+ [![AI Engineering Loop: task and context preparation flow into Specify, Make, Review, and Deliver phases. Failed verification or an ITERATE verdict returns work to Maker; PASS reaches delivery.](docs/images/engineering-loop-overview.svg)](docs/images/engineering-loop-overview.svg)
57
25
 
58
26
  ---
59
27
 
@@ -266,7 +234,7 @@ Every full run stores private local artifacts under `.ai-engineering-loop/runs/<
266
234
 
267
235
  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
236
 
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).
237
+ 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: a pannable and zoomable DAG canvas, drag-and-drop nodes, guarded visual connections, undo/redo, private per-project layouts, Stage 8 adapter selection, 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
238
 
271
239
  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.
272
240
 
@@ -118,7 +118,7 @@ const {
118
118
  } = require('../lib/handoff.js');
119
119
  const { createStudioServer } = require('../lib/studio-server.js');
120
120
 
121
- const VERSION = '1.6.0';
121
+ const VERSION = '1.7.0';
122
122
  const CWD = process.cwd();
123
123
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
124
124
 
@@ -372,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
372
372
 
373
373
  // 0. metadata.json (Baseline)
374
374
  const metadataJson = {
375
- contextVersion: '1.6.0',
375
+ contextVersion: '1.7.0',
376
376
  generatedAt: new Date().toISOString(),
377
377
  repositoryRevision: currentRevision,
378
378
  projectProfile: discovery.profile,
@@ -18,13 +18,24 @@ The canvas loads built-in and project recipes through the same APIs as the CLI:
18
18
 
19
19
  1. Select a recipe.
20
20
  2. Fork a protected built-in by changing its ID.
21
- 3. Add or edit allowlisted node types.
22
- 4. Connect nodes with dependency IDs.
23
- 5. Review graph validation and hashes for every compatible mode.
24
- 6. Install only after explicit confirmation.
21
+ 3. Drag allowlisted node types from the library or click to add them at the viewport center.
22
+ 4. Move nodes freely and drag an output port onto another node to create a dependency.
23
+ 5. Pan, zoom, fit, auto-layout, and use undo/redo without changing recipe semantics.
24
+ 6. Review graph validation and hashes for every compatible mode.
25
+ 7. Install only after explicit confirmation.
25
26
 
26
27
  Installation writes a private temporary candidate, invokes the existing atomic installer, and removes the candidate. Built-ins cannot be overwritten. Replacing a project recipe still requires the version policy enforced by `recipe install --replace`.
27
28
 
29
+ Canvas positions and viewport state are not recipe fields and never contribute to the graph hash. Studio stores them under private `.ai-engineering-loop/studio-layouts/` files, validates IDs and coordinate bounds, rejects symlinks, and writes atomically. This keeps visual organization independent from execution semantics.
30
+
31
+ Visual connections are real `dependsOn` edges. Studio rejects a connection that would introduce a cycle, then the recipe compiler applies the complete safety-backbone and mode validation before installation. Selecting and deleting a node removes its incoming references; undo remains available until the recipe is changed or reloaded.
32
+
33
+ ## Stage 8 delivery adapter
34
+
35
+ The default canvas labels the lifecycle coverage from Stage 1 through Stage 8; Maker contains the Stage 2–4 diagnosis, planning, and implementation sequence. Delivery nodes expose the project-level Stage 8 adapter selected in `.ai-engineering-loop/adapter.md`. Studio can select the shipped `standard`, `github`, `gitlab`, or `dot` adapters and shows the adapter inferred from the repository remote.
36
+
37
+ An adapter belongs to the project, not to one delivery node. For a custom adapter, **Custom with AI** copies a bounded builder request that tells an agent to use the existing `generate-adapter` Q1–Q5 protocol, preserve Stages 0–7, require Judge `PASS`, and keep credentials out of configuration. Once that agent writes `.ai-engineering-loop/adapter.md`, Studio discovers the custom adapter on refresh. The browser never accepts arbitrary adapter code or executes delivery commands.
38
+
28
39
  ## Live execution
29
40
 
30
41
  For a recipe-bound current run, Studio polls a small live snapshot rather than reloading the recipe catalog. It displays:
@@ -73,5 +84,7 @@ Studio improves authoring and observability; it does not weaken runtime gates:
73
84
  - graph validation does not imply execution permission;
74
85
  - command nodes remain disabled;
75
86
  - approvals remain explicit state transitions;
87
+ - connector edits cannot bypass the required safety backbone;
88
+ - delivery adapters cannot run before Judge `PASS`;
76
89
  - token data comes only from the provider-recorded usage ledger;
77
90
  - handoff integrity proves the bundle has not changed after export, not that every original claim was true.
@@ -0,0 +1,114 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1440" height="900" viewBox="0 0 1440 900" role="img" aria-labelledby="title description">
2
+ <title id="title">AI Engineering Loop overview</title>
3
+ <desc id="description">A user task passes through context preparation, Specify, Make, Review, and Deliver. Failed verification and Judge ITERATE decisions return to Maker. Only a Judge PASS reaches delivery.</desc>
4
+ <defs>
5
+ <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
6
+ <path d="M0 0L10 5L0 10Z" fill="#59616d"/>
7
+ </marker>
8
+ <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
9
+ <path d="M0 0L10 5L0 10Z" fill="#e95d37"/>
10
+ </marker>
11
+ <style>
12
+ .title{font:700 38px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#17191d}
13
+ .subtitle{font:400 18px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
14
+ .phase{font:700 14px system-ui,-apple-system,"Segoe UI",sans-serif;letter-spacing:2px;fill:#59616d}
15
+ .number{font:700 16px ui-monospace,SFMono-Regular,Consolas,monospace;fill:#ffffff}
16
+ .node-title{font:700 19px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#17191d}
17
+ .node-copy{font:400 14px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
18
+ .gate{font:700 13px system-ui,-apple-system,"Segoe UI",sans-serif;letter-spacing:1px;fill:#17191d}
19
+ .label{font:700 13px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
20
+ .small{font:400 13px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#6d7480}
21
+ .line{fill:none;stroke:#59616d;stroke-width:3;marker-end:url(#arrow)}
22
+ .feedback{fill:none;stroke:#e95d37;stroke-width:3;stroke-dasharray:8 7;marker-end:url(#arrow-orange)}
23
+ </style>
24
+ </defs>
25
+
26
+ <rect width="1440" height="900" rx="24" fill="#f5f2eb"/>
27
+ <text class="title" x="70" y="72">From task to trusted delivery</text>
28
+ <text class="subtitle" x="70" y="106">One workflow. Eight stages. Evidence advances the work—not AI confidence.</text>
29
+
30
+ <rect x="70" y="145" width="1300" height="98" rx="14" fill="#ffffff" stroke="#d8d3c9" stroke-width="2"/>
31
+ <rect x="94" y="170" width="154" height="48" rx="24" fill="#17191d"/>
32
+ <text x="171" y="200" text-anchor="middle" style="font:700 16px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">USER TASK</text>
33
+ <path class="line" d="M250 194H328"/>
34
+ <text class="node-title" x="355" y="188">Stage 0 · Prepare context</text>
35
+ <text class="node-copy" x="355" y="213">Initialize missing context or reconcile drift before reasoning begins.</text>
36
+ <path class="line" d="M920 194H1120"/>
37
+ <rect x="1132" y="166" width="204" height="56" rx="9" fill="#fff4e8" stroke="#e95d37" stroke-width="2"/>
38
+ <text class="gate" x="1234" y="190" text-anchor="middle">CONTEXT READY</text>
39
+ <text class="small" x="1234" y="210" text-anchor="middle">deterministic check</text>
40
+
41
+ <text class="phase" x="70" y="298">SPECIFY</text>
42
+ <text class="phase" x="380" y="298">MAKE</text>
43
+ <text class="phase" x="835" y="298">REVIEW</text>
44
+ <text class="phase" x="1190" y="298">DELIVER</text>
45
+
46
+ <rect x="70" y="320" width="270" height="322" rx="16" fill="#fff8ef" stroke="#e6b083" stroke-width="2"/>
47
+ <circle cx="104" cy="365" r="18" fill="#e95d37"/><text class="number" x="104" y="371" text-anchor="middle">1</text>
48
+ <text class="node-title" x="135" y="362">Goal Contract</text>
49
+ <text class="node-copy" x="104" y="398">Freeze explicit acceptance</text>
50
+ <text class="node-copy" x="104" y="419">criteria and failure cases.</text>
51
+ <line x1="104" y1="451" x2="306" y2="451" stroke="#e6b083"/>
52
+ <text class="gate" x="104" y="484">OUTPUT</text>
53
+ <text class="node-copy" x="104" y="513">A shared definition of done</text>
54
+ <text class="node-copy" x="104" y="534">that machines can verify.</text>
55
+ <rect x="104" y="570" width="202" height="44" rx="8" fill="#ffffff" stroke="#e6b083"/>
56
+ <text class="gate" x="205" y="597" text-anchor="middle">GOAL GATE</text>
57
+
58
+ <rect x="380" y="320" width="415" height="322" rx="16" fill="#f1f6fb" stroke="#94b5d2" stroke-width="2"/>
59
+ <circle cx="414" cy="365" r="18" fill="#467da8"/><text class="number" x="414" y="371" text-anchor="middle">2</text>
60
+ <text class="node-title" x="445" y="362">Root cause</text>
61
+ <text class="node-copy" x="414" y="394">Reproduce and explain the real problem.</text>
62
+ <path d="M414 422H760" stroke="#b8cad9" stroke-width="2"/>
63
+ <circle cx="414" cy="463" r="18" fill="#467da8"/><text class="number" x="414" y="469" text-anchor="middle">3</text>
64
+ <text class="node-title" x="445" y="460">Implementation plan</text>
65
+ <text class="node-copy" x="414" y="492">Choose seams, tests, and the smallest coherent change.</text>
66
+ <path d="M414 520H760" stroke="#b8cad9" stroke-width="2"/>
67
+ <circle cx="414" cy="561" r="18" fill="#467da8"/><text class="number" x="414" y="567" text-anchor="middle">4</text>
68
+ <text class="node-title" x="445" y="558">Maker</text>
69
+ <text class="node-copy" x="414" y="590">Implement surgical changes with red → green tests.</text>
70
+ <rect x="643" y="550" width="117" height="44" rx="8" fill="#ffffff" stroke="#94b5d2"/>
71
+ <text class="gate" x="701" y="577" text-anchor="middle">DIFF + TESTS</text>
72
+
73
+ <rect x="835" y="320" width="315" height="322" rx="16" fill="#f5f0fa" stroke="#b49bcb" stroke-width="2"/>
74
+ <circle cx="869" cy="365" r="18" fill="#765596"/><text class="number" x="869" y="371" text-anchor="middle">5</text>
75
+ <text class="node-title" x="900" y="362">Verify</text>
76
+ <text class="node-copy" x="869" y="394">Run commands; capture exact evidence.</text>
77
+ <path d="M869 422H1115" stroke="#c9bad7" stroke-width="2"/>
78
+ <circle cx="869" cy="463" r="18" fill="#765596"/><text class="number" x="869" y="469" text-anchor="middle">6</text>
79
+ <text class="node-title" x="900" y="460">Devil’s Advocate</text>
80
+ <text class="node-copy" x="869" y="492">Challenge claims against reality.</text>
81
+ <path d="M869 520H1115" stroke="#c9bad7" stroke-width="2"/>
82
+ <circle cx="869" cy="561" r="18" fill="#765596"/><text class="number" x="869" y="567" text-anchor="middle">7</text>
83
+ <text class="node-title" x="900" y="558">Judge</text>
84
+ <text class="node-copy" x="869" y="590">PASS, ITERATE, or ESCALATE.</text>
85
+
86
+ <rect x="1190" y="320" width="180" height="322" rx="16" fill="#eef8f1" stroke="#81b994" stroke-width="2"/>
87
+ <circle cx="1224" cy="365" r="18" fill="#39885a"/><text class="number" x="1224" y="371" text-anchor="middle">8</text>
88
+ <text class="node-title" x="1255" y="362">Deliver</text>
89
+ <text class="node-copy" x="1224" y="404">Refresh context.</text>
90
+ <text class="node-copy" x="1224" y="428">Require approval.</text>
91
+ <text class="node-copy" x="1224" y="452">Publish through</text>
92
+ <text class="node-copy" x="1224" y="476">the adapter.</text>
93
+ <rect x="1216" y="550" width="128" height="64" rx="9" fill="#39885a"/>
94
+ <text x="1280" y="576" text-anchor="middle" style="font:700 13px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">TARGET</text>
95
+ <text x="1280" y="596" text-anchor="middle" style="font:400 13px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">REPOSITORY</text>
96
+
97
+ <path class="line" d="M340 365H380"/>
98
+ <path class="line" d="M795 561H815V365H835"/>
99
+ <path class="line" d="M1150 561H1170V365H1190"/>
100
+ <rect x="1139" y="505" width="62" height="28" rx="14" fill="#39885a"/>
101
+ <text x="1170" y="524" text-anchor="middle" style="font:700 12px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">PASS</text>
102
+
103
+ <path class="feedback" d="M869 365C810 365 820 700 650 700H590C515 700 500 636 500 610"/>
104
+ <rect x="656" y="676" width="137" height="28" rx="14" fill="#f5f2eb"/>
105
+ <text class="label" x="724" y="695" text-anchor="middle">FAIL → FIX</text>
106
+ <path class="feedback" d="M869 561C815 561 835 770 665 770H575C470 770 455 650 455 610"/>
107
+ <rect x="665" y="746" width="175" height="28" rx="14" fill="#f5f2eb"/>
108
+ <text class="label" x="752" y="765" text-anchor="middle">ITERATE → MAKER</text>
109
+
110
+ <rect x="70" y="815" width="1300" height="48" rx="10" fill="#17191d"/>
111
+ <circle cx="101" cy="839" r="7" fill="#e95d37"/>
112
+ <text x="119" y="845" style="font:600 14px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">Safety invariant:</text>
113
+ <text x="245" y="845" style="font:400 14px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#d5d8dd">a model can propose work, but only contracts, artifacts, verification evidence, and gates can advance the run.</text>
114
+ </svg>
@@ -142,6 +142,7 @@ function recipeCatalog() {
142
142
  type,
143
143
  label: definition.label,
144
144
  category: definition.category,
145
+ builtIn: definition.builtIn,
145
146
  capabilities: {
146
147
  repositoryMutation: definition.mutation,
147
148
  remoteSideEffect: definition.sideEffect,
@@ -9,6 +9,7 @@ const PRIVATE_RUNTIME_PATTERNS = Object.freeze([
9
9
  'worktrees/',
10
10
  'locks/',
11
11
  'drafts/',
12
+ 'studio-layouts/',
12
13
  'recipes/.history/',
13
14
  'tasks/current.diff',
14
15
  'tasks/*.log'
@@ -0,0 +1,113 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { NODE_ID, RECIPE_ID } = require('./recipe.js');
7
+ const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
+
9
+ const MIN_SCALE = 0.2;
10
+ const MAX_SCALE = 2.5;
11
+ const MAX_COORDINATE = 1_000_000;
12
+
13
+ function layoutError(message, code = 'INVALID_STUDIO_LAYOUT') {
14
+ const error = new Error(message);
15
+ error.code = code;
16
+ return error;
17
+ }
18
+
19
+ function finiteCoordinate(value, label) {
20
+ if (!Number.isFinite(value) || Math.abs(value) > MAX_COORDINATE) {
21
+ throw layoutError(`${label} must be a finite coordinate within ${MAX_COORDINATE}`);
22
+ }
23
+ return value;
24
+ }
25
+
26
+ function normalizeStudioLayout(recipeId, value, allowedNodeIds) {
27
+ if (!RECIPE_ID.test(String(recipeId || ''))) throw layoutError('Invalid layout recipe id');
28
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
29
+ throw layoutError('Studio layout must be an object');
30
+ }
31
+ const allowed = allowedNodeIds ? new Set(allowedNodeIds) : null;
32
+ const positions = {};
33
+ for (const [nodeId, position] of Object.entries(value.positions || {})) {
34
+ if (!NODE_ID.test(nodeId)) throw layoutError(`Invalid layout node id: ${nodeId}`);
35
+ if (allowed && !allowed.has(nodeId)) continue;
36
+ if (!position || typeof position !== 'object' || Array.isArray(position)) {
37
+ throw layoutError(`Position for ${nodeId} must be an object`);
38
+ }
39
+ positions[nodeId] = {
40
+ x: finiteCoordinate(position.x, `${nodeId}.x`),
41
+ y: finiteCoordinate(position.y, `${nodeId}.y`)
42
+ };
43
+ }
44
+ const viewport = value.viewport || { x: 0, y: 0, scale: 1 };
45
+ const scale = Number(viewport.scale);
46
+ if (!Number.isFinite(scale) || scale < MIN_SCALE || scale > MAX_SCALE) {
47
+ throw layoutError(`viewport.scale must be between ${MIN_SCALE} and ${MAX_SCALE}`);
48
+ }
49
+ return {
50
+ schemaVersion: 1,
51
+ recipeId,
52
+ positions,
53
+ viewport: {
54
+ x: finiteCoordinate(viewport.x, 'viewport.x'),
55
+ y: finiteCoordinate(viewport.y, 'viewport.y'),
56
+ scale
57
+ }
58
+ };
59
+ }
60
+
61
+ function layoutDirectory(rootDir) {
62
+ return path.join(rootDir, '.ai-engineering-loop', 'studio-layouts');
63
+ }
64
+
65
+ function layoutPath(rootDir, recipeId) {
66
+ if (!RECIPE_ID.test(String(recipeId || ''))) throw layoutError('Invalid layout recipe id');
67
+ return path.join(layoutDirectory(rootDir), `${recipeId}.json`);
68
+ }
69
+
70
+ function loadStudioLayout(rootDir, recipeId, { nodeIds } = {}) {
71
+ const filePath = layoutPath(rootDir, recipeId);
72
+ if (!fs.existsSync(filePath)) return null;
73
+ const stat = fs.lstatSync(filePath);
74
+ if (stat.isSymbolicLink() || !stat.isFile()) {
75
+ throw layoutError('Studio layout must be a regular file', 'UNSAFE_STUDIO_LAYOUT');
76
+ }
77
+ try {
78
+ return normalizeStudioLayout(recipeId, JSON.parse(fs.readFileSync(filePath, 'utf8')), nodeIds);
79
+ } catch (cause) {
80
+ if (cause.code) throw cause;
81
+ throw layoutError(`Unable to read Studio layout: ${cause.message}`);
82
+ }
83
+ }
84
+
85
+ function saveStudioLayout(rootDir, recipeId, value, { nodeIds } = {}) {
86
+ const layout = normalizeStudioLayout(recipeId, value, nodeIds);
87
+ ensurePrivateRuntimeIgnores(rootDir);
88
+ const directory = layoutDirectory(rootDir);
89
+ if (fs.existsSync(directory) && (fs.lstatSync(directory).isSymbolicLink() || !fs.lstatSync(directory).isDirectory())) {
90
+ throw layoutError('Studio layout directory must be a regular directory', 'UNSAFE_STUDIO_LAYOUT');
91
+ }
92
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
93
+ const destination = layoutPath(rootDir, recipeId);
94
+ if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
95
+ throw layoutError('Studio layout must not be a symbolic link', 'UNSAFE_STUDIO_LAYOUT');
96
+ }
97
+ const temporary = `${destination}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
98
+ try {
99
+ fs.writeFileSync(temporary, `${JSON.stringify(layout, null, 2)}\n`, { mode: 0o600 });
100
+ fs.renameSync(temporary, destination);
101
+ } finally {
102
+ try { fs.unlinkSync(temporary); } catch {}
103
+ }
104
+ return layout;
105
+ }
106
+
107
+ module.exports = {
108
+ MIN_SCALE,
109
+ MAX_SCALE,
110
+ normalizeStudioLayout,
111
+ loadStudioLayout,
112
+ saveStudioLayout
113
+ };
@@ -16,6 +16,12 @@ const {
16
16
  recordWorkflowActivity
17
17
  } = require('./workflow-runtime.js');
18
18
  const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
19
+ const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
20
+ const {
21
+ SHIPPED_TYPES,
22
+ detectAdapterHints,
23
+ writeShippedAdapter
24
+ } = require('./generate-adapter.js');
19
25
 
20
26
  const MAX_BODY = 256 * 1024;
21
27
  const ASSET_DIR = path.join(__dirname, '..', 'studio');
@@ -58,7 +64,18 @@ function liveSnapshot(rootDir) {
58
64
 
59
65
  function bootstrap(rootDir) {
60
66
  const recipes = listRecipes(rootDir).map(({ id, source }) => ({ ...inspectRecipe(rootDir, id), source }));
61
- return { recipes, nodeTypes: recipeCatalog(), live: liveSnapshot(rootDir) };
67
+ const adapterHints = detectAdapterHints(rootDir);
68
+ return {
69
+ recipes,
70
+ nodeTypes: recipeCatalog(),
71
+ adapters: {
72
+ types: SHIPPED_TYPES,
73
+ current: adapterHints.existingType || null,
74
+ recommended: adapterHints.recommended,
75
+ ciProvider: adapterHints.ciProvider
76
+ },
77
+ live: liveSnapshot(rootDir)
78
+ };
62
79
  }
63
80
 
64
81
  function constantTimeEqual(left, right) {
@@ -111,6 +128,32 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
111
128
  } else if (request.method === 'GET' && url.pathname === '/api/recipe') {
112
129
  const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
113
130
  json(response, 200, { ok: true, source: loaded.source, recipe: loaded.recipe });
131
+ } else if (request.method === 'GET' && url.pathname === '/api/layout') {
132
+ const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
133
+ const nodeIds = loaded.recipe.nodes.map((node) => node.id);
134
+ json(response, 200, {
135
+ ok: true,
136
+ layout: loadStudioLayout(rootDir, loaded.recipe.id, { nodeIds })
137
+ });
138
+ } else if (request.method === 'PUT' && url.pathname === '/api/layout') {
139
+ const body = await readBody(request);
140
+ const loaded = loadRecipe(rootDir, body.recipeId);
141
+ const nodeIds = loaded.recipe.nodes.map((node) => node.id);
142
+ const layout = saveStudioLayout(rootDir, loaded.recipe.id, body.layout, { nodeIds });
143
+ json(response, 200, { ok: true, layout });
144
+ } else if (request.method === 'POST' && url.pathname === '/api/adapter/select') {
145
+ const body = await readBody(request);
146
+ if (!SHIPPED_TYPES.includes(body.type)) {
147
+ const error = new Error(`Unknown adapter type: ${body.type || '(empty)'}`);
148
+ error.code = 'UNKNOWN_ADAPTER';
149
+ throw error;
150
+ }
151
+ const hints = detectAdapterHints(rootDir);
152
+ const file = writeShippedAdapter(rootDir, { type: body.type, hints });
153
+ json(response, 200, {
154
+ ok: true,
155
+ adapter: { type: body.type, file: path.relative(rootDir, file), ciProvider: hints.ciProvider }
156
+ });
114
157
  } else if (request.method === 'POST' && url.pathname === '/api/validate') {
115
158
  const body = await readBody(request);
116
159
  const validation = validateRecipe(body.recipe, body.mode ? { mode: body.mode } : {});
@@ -129,6 +172,11 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
129
172
  fs.writeFileSync(candidate, JSON.stringify(body.recipe), { mode: 0o600 });
130
173
  try {
131
174
  const result = installRecipe(rootDir, path.relative(rootDir, candidate), { replace: body.replace === true });
175
+ if (body.layout) {
176
+ saveStudioLayout(rootDir, result.recipe.id, body.layout, {
177
+ nodeIds: result.recipe.nodes.map((node) => node.id)
178
+ });
179
+ }
132
180
  json(response, 200, { ok: true, id: result.recipe.id, version: result.recipe.version, sourceHash: result.sourceHash });
133
181
  } finally {
134
182
  try { fs.unlinkSync(candidate); } catch {}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.6.0",
3
+ "version": "1.7.0",
4
4
  "description": "A reusable, framework-agnostic AI Engineering Operating System for safe coding agents.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {
@@ -17,6 +17,7 @@
17
17
  "recipes/",
18
18
  "schemas/",
19
19
  "studio/",
20
+ "docs/images/",
20
21
  "evals/",
21
22
  ".agents/",
22
23
  ".grok/",