ai-engineering-loop 1.5.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 +15 -37
- package/README.npm.md +7 -0
- package/SECURITY.md +3 -1
- package/bin/ai-engineering-loop.js +130 -4
- package/core/local-workflow-studio.md +90 -0
- package/docs/images/engineering-loop-overview.svg +114 -0
- package/lib/doctor.js +3 -2
- package/lib/handoff.js +209 -0
- package/lib/recipe-builder.js +1 -0
- package/lib/runtime-files.js +2 -0
- package/lib/studio-layout.js +113 -0
- package/lib/studio-server.js +231 -0
- package/lib/workflow-runtime.js +30 -4
- package/package.json +3 -1
- package/schemas/handoff.schema.json +36 -0
- package/schemas/workflow-event.schema.json +1 -0
- package/studio/app.js +928 -0
- package/studio/index.html +95 -0
- package/studio/styles.css +36 -0
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
7
7
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
8
|
-
[](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
|
|
23
|
-
|
|
24
|
-
|
|
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
|
+
[](docs/images/engineering-loop-overview.svg)
|
|
57
25
|
|
|
58
26
|
---
|
|
59
27
|
|
|
@@ -237,9 +205,19 @@ npx ai-engineering-loop recipe install candidate-v2.json --replace
|
|
|
237
205
|
# Operate a custom node in an immutable recipe-bound run
|
|
238
206
|
npx ai-engineering-loop node status
|
|
239
207
|
npx ai-engineering-loop node start root-cause
|
|
208
|
+
npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
|
|
240
209
|
npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
241
210
|
npx ai-engineering-loop node approve delivery-approval --yes
|
|
242
211
|
|
|
212
|
+
# Open the local workflow canvas (localhost-only, authenticated session)
|
|
213
|
+
npx ai-engineering-loop studio
|
|
214
|
+
npx ai-engineering-loop studio --port 4400 --no-open
|
|
215
|
+
|
|
216
|
+
# Transfer redacted knowledge to another developer or agent
|
|
217
|
+
npx ai-engineering-loop handoff create --audience developer
|
|
218
|
+
npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
|
|
219
|
+
npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
|
|
220
|
+
|
|
243
221
|
# Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
244
222
|
npx ai-engineering-loop sync-hosts
|
|
245
223
|
|
|
@@ -256,7 +234,7 @@ Every full run stores private local artifacts under `.ai-engineering-loop/runs/<
|
|
|
256
234
|
|
|
257
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).
|
|
258
236
|
|
|
259
|
-
The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, preserves replaced versions locally, and
|
|
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).
|
|
260
238
|
|
|
261
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.
|
|
262
240
|
|
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
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
const fs = require('fs');
|
|
14
14
|
const path = require('path');
|
|
15
15
|
const crypto = require('crypto');
|
|
16
|
-
const { execSync } = require('child_process');
|
|
16
|
+
const { execSync, spawn } = require('child_process');
|
|
17
17
|
const {
|
|
18
18
|
homeDir,
|
|
19
19
|
applyHostSync,
|
|
@@ -98,6 +98,7 @@ const {
|
|
|
98
98
|
completeWorkflowNode,
|
|
99
99
|
createWorkflowBundle,
|
|
100
100
|
failWorkflowNode,
|
|
101
|
+
recordWorkflowActivity,
|
|
101
102
|
retryWorkflowNode,
|
|
102
103
|
startWorkflowNode,
|
|
103
104
|
workflowStatus
|
|
@@ -109,8 +110,15 @@ const {
|
|
|
109
110
|
installRecipe,
|
|
110
111
|
recipeCatalog
|
|
111
112
|
} = require('../lib/recipe-builder.js');
|
|
112
|
-
|
|
113
|
-
|
|
113
|
+
const {
|
|
114
|
+
createHandoff,
|
|
115
|
+
handoffBrief,
|
|
116
|
+
readHandoff,
|
|
117
|
+
verifyHandoff
|
|
118
|
+
} = require('../lib/handoff.js');
|
|
119
|
+
const { createStudioServer } = require('../lib/studio-server.js');
|
|
120
|
+
|
|
121
|
+
const VERSION = '1.7.0';
|
|
114
122
|
const CWD = process.cwd();
|
|
115
123
|
const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
|
|
116
124
|
|
|
@@ -364,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
|
|
|
364
372
|
|
|
365
373
|
// 0. metadata.json (Baseline)
|
|
366
374
|
const metadataJson = {
|
|
367
|
-
contextVersion: '1.
|
|
375
|
+
contextVersion: '1.7.0',
|
|
368
376
|
generatedAt: new Date().toISOString(),
|
|
369
377
|
repositoryRevision: currentRevision,
|
|
370
378
|
projectProfile: discovery.profile,
|
|
@@ -1175,6 +1183,11 @@ function handleNode() {
|
|
|
1175
1183
|
runId,
|
|
1176
1184
|
reason: argValue('--reason') || 'node execution failed'
|
|
1177
1185
|
});
|
|
1186
|
+
} else if (action === 'activity') {
|
|
1187
|
+
workflow = recordWorkflowActivity(CWD, nodeId, {
|
|
1188
|
+
runId,
|
|
1189
|
+
message: argValue('--message')
|
|
1190
|
+
});
|
|
1178
1191
|
} else if (action === 'retry') {
|
|
1179
1192
|
workflow = retryWorkflowNode(CWD, nodeId, { runId });
|
|
1180
1193
|
} else if (action === 'approve') {
|
|
@@ -1450,6 +1463,106 @@ function handleRecipe() {
|
|
|
1450
1463
|
}
|
|
1451
1464
|
}
|
|
1452
1465
|
|
|
1466
|
+
function safeHandoffOutput(file) {
|
|
1467
|
+
const absolute = path.resolve(CWD, file);
|
|
1468
|
+
const relative = path.relative(CWD, absolute);
|
|
1469
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`)) {
|
|
1470
|
+
throw Object.assign(new Error('Handoff output must stay inside the repository'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1471
|
+
}
|
|
1472
|
+
const parent = path.dirname(absolute);
|
|
1473
|
+
fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
|
|
1474
|
+
const realRoot = fs.realpathSync(CWD);
|
|
1475
|
+
const realParent = fs.realpathSync(parent);
|
|
1476
|
+
if (realParent !== realRoot && !realParent.startsWith(`${realRoot}${path.sep}`)) {
|
|
1477
|
+
throw Object.assign(new Error('Handoff output escapes the repository through a symlink'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1478
|
+
}
|
|
1479
|
+
return absolute;
|
|
1480
|
+
}
|
|
1481
|
+
|
|
1482
|
+
function handleHandoff() {
|
|
1483
|
+
const action = process.argv[3] || 'create';
|
|
1484
|
+
const json = process.argv.includes('--json');
|
|
1485
|
+
try {
|
|
1486
|
+
if (action === 'create') {
|
|
1487
|
+
const bundle = createHandoff(CWD, {
|
|
1488
|
+
runId: argValue('--run'),
|
|
1489
|
+
audience: argValue('--audience') || 'developer'
|
|
1490
|
+
});
|
|
1491
|
+
const requested = argValue('--output');
|
|
1492
|
+
if (requested === '-') {
|
|
1493
|
+
console.log(JSON.stringify(bundle, null, json ? 0 : 2));
|
|
1494
|
+
return;
|
|
1495
|
+
}
|
|
1496
|
+
const output = safeHandoffOutput(requested || `${bundle.runId}.ael-handoff.json`);
|
|
1497
|
+
const descriptor = fs.openSync(output, 'wx', 0o600);
|
|
1498
|
+
try {
|
|
1499
|
+
fs.writeFileSync(descriptor, `${JSON.stringify(bundle, null, 2)}\n`);
|
|
1500
|
+
fs.fsyncSync(descriptor);
|
|
1501
|
+
} finally {
|
|
1502
|
+
fs.closeSync(descriptor);
|
|
1503
|
+
}
|
|
1504
|
+
const result = {
|
|
1505
|
+
ok: true,
|
|
1506
|
+
path: path.relative(CWD, output).split(path.sep).join('/'),
|
|
1507
|
+
runId: bundle.runId,
|
|
1508
|
+
audience: bundle.audience,
|
|
1509
|
+
bundleHash: bundle.bundleHash
|
|
1510
|
+
};
|
|
1511
|
+
console.log(json ? JSON.stringify(result) : `Created ${result.path}\nBundle hash: ${result.bundleHash}`);
|
|
1512
|
+
return;
|
|
1513
|
+
}
|
|
1514
|
+
const file = process.argv[4];
|
|
1515
|
+
if (!file || file.startsWith('-')) throw new Error(`handoff ${action} requires a file`);
|
|
1516
|
+
const bundle = readHandoff(CWD, file);
|
|
1517
|
+
const verification = verifyHandoff(bundle);
|
|
1518
|
+
if (action === 'inspect') {
|
|
1519
|
+
console.log(JSON.stringify({ ok: true, ...verification }, null, json ? 0 : 2));
|
|
1520
|
+
} else if (action === 'brief') {
|
|
1521
|
+
console.log(handoffBrief(bundle));
|
|
1522
|
+
} else {
|
|
1523
|
+
throw new Error('Unknown handoff action. Use create|inspect|brief');
|
|
1524
|
+
}
|
|
1525
|
+
} catch (err) {
|
|
1526
|
+
if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'HANDOFF_FAILED', error: err.message }));
|
|
1527
|
+
else log.error(err.message);
|
|
1528
|
+
process.exitCode = 1;
|
|
1529
|
+
}
|
|
1530
|
+
}
|
|
1531
|
+
|
|
1532
|
+
function openStudio(url) {
|
|
1533
|
+
const command = process.platform === 'darwin'
|
|
1534
|
+
? ['open', [url]]
|
|
1535
|
+
: process.platform === 'win32'
|
|
1536
|
+
? ['cmd', ['/c', 'start', '', url]]
|
|
1537
|
+
: ['xdg-open', [url]];
|
|
1538
|
+
const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
|
|
1539
|
+
child.on('error', () => {});
|
|
1540
|
+
child.unref();
|
|
1541
|
+
}
|
|
1542
|
+
|
|
1543
|
+
function handleStudio() {
|
|
1544
|
+
const requestedPort = argValue('--port');
|
|
1545
|
+
const port = requestedPort == null ? 4317 : Number(requestedPort);
|
|
1546
|
+
if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
|
|
1547
|
+
log.error('--port must be an integer from 0 to 65535');
|
|
1548
|
+
process.exitCode = 1;
|
|
1549
|
+
return;
|
|
1550
|
+
}
|
|
1551
|
+
const { server, token } = createStudioServer(CWD);
|
|
1552
|
+
server.on('error', (error) => {
|
|
1553
|
+
log.error(`Unable to start Studio: ${error.message}`);
|
|
1554
|
+
process.exitCode = 1;
|
|
1555
|
+
});
|
|
1556
|
+
server.listen(port, '127.0.0.1', () => {
|
|
1557
|
+
const address = server.address();
|
|
1558
|
+
const url = `http://127.0.0.1:${address.port}/?token=${token}`;
|
|
1559
|
+
log.success('✓ Workflow Studio is running locally');
|
|
1560
|
+
console.log(url);
|
|
1561
|
+
console.log('Press Ctrl+C to stop. The session token is valid only for this process.');
|
|
1562
|
+
if (!process.argv.includes('--no-open')) openStudio(url);
|
|
1563
|
+
});
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1453
1566
|
// Help Menu
|
|
1454
1567
|
function printHelp() {
|
|
1455
1568
|
console.log(`
|
|
@@ -1479,6 +1592,7 @@ Commands:
|
|
|
1479
1592
|
start <id> [--run <id>] [--json]
|
|
1480
1593
|
complete <id> [--artifact <repository-relative-path>] [--json]
|
|
1481
1594
|
fail <id> [--reason <text>] [--json]
|
|
1595
|
+
activity <id> --message <safe progress text> [--json]
|
|
1482
1596
|
retry <id> [--json]
|
|
1483
1597
|
approve <id> --yes [--by <name>] [--json]
|
|
1484
1598
|
policy Inspect or update fail-closed runtime controls
|
|
@@ -1516,6 +1630,12 @@ Commands:
|
|
|
1516
1630
|
show <id> [--json]
|
|
1517
1631
|
validate <id> [--mode <mode>] [--json]
|
|
1518
1632
|
explain | graph | simulate <id> [--mode <mode>] [--json]
|
|
1633
|
+
studio Open the localhost-only visual workflow editor
|
|
1634
|
+
[--port <0-65535>] [--no-open]
|
|
1635
|
+
handoff Export or verify a redacted, integrity-bound knowledge transfer
|
|
1636
|
+
create [--run <id>] [--audience developer|agent|auditor]
|
|
1637
|
+
[--output <repository-relative-file>|-] [--json]
|
|
1638
|
+
inspect | brief <repository-relative-file> [--json]
|
|
1519
1639
|
sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
1520
1640
|
(only hosts that already exist; DOT skills only if already installed)
|
|
1521
1641
|
--dry-run print the plan without writing
|
|
@@ -1583,6 +1703,12 @@ switch (command) {
|
|
|
1583
1703
|
case 'recipe':
|
|
1584
1704
|
handleRecipe();
|
|
1585
1705
|
break;
|
|
1706
|
+
case 'studio':
|
|
1707
|
+
handleStudio();
|
|
1708
|
+
break;
|
|
1709
|
+
case 'handoff':
|
|
1710
|
+
handleHandoff();
|
|
1711
|
+
break;
|
|
1586
1712
|
case 'sync-hosts':
|
|
1587
1713
|
handleSyncHosts();
|
|
1588
1714
|
break;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Local Workflow Studio
|
|
2
|
+
|
|
3
|
+
Workflow Studio is a localhost-only visual control plane for declarative recipes and recipe-bound runs. It does not execute models, shell commands, or arbitrary node code. The existing recipe compiler and controlled workflow runtime remain the source of truth.
|
|
4
|
+
|
|
5
|
+
## Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
ai-engineering-loop studio
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The CLI binds only to `127.0.0.1`, creates a random process-local session token, and opens a tokenized bootstrap URL. The server exchanges that URL for an `HttpOnly; SameSite=Strict` cookie and removes the token from the address bar. Use `--no-open` when you want to copy the printed URL manually, or `--port 0` to let the operating system choose an available port.
|
|
12
|
+
|
|
13
|
+
The server rejects non-local `Host` headers. Static assets are bundled in the npm package; there are no CDNs, analytics, remote fonts, or browser-side model calls. Responses use a restrictive Content Security Policy and are not cached.
|
|
14
|
+
|
|
15
|
+
## Authoring model
|
|
16
|
+
|
|
17
|
+
The canvas loads built-in and project recipes through the same APIs as the CLI:
|
|
18
|
+
|
|
19
|
+
1. Select a recipe.
|
|
20
|
+
2. Fork a protected built-in by changing its ID.
|
|
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.
|
|
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`.
|
|
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
|
+
|
|
39
|
+
## Live execution
|
|
40
|
+
|
|
41
|
+
For a recipe-bound current run, Studio polls a small live snapshot rather than reloading the recipe catalog. It displays:
|
|
42
|
+
|
|
43
|
+
- current node states and the append-only event stream;
|
|
44
|
+
- an animated connector leaving the running node;
|
|
45
|
+
- provider-recorded run token spend and configured limit;
|
|
46
|
+
- explicit approval and retry controls;
|
|
47
|
+
- a short redacted activity message reported by the host:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
ai-engineering-loop node activity <node-id> \
|
|
51
|
+
--message "Comparing the failing test with the implementation"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Activity can only be attached to a `RUNNING` node. It is capped at 240 printable characters, secret-redacted before persistence, and added to the integrity-bound workflow event chain.
|
|
55
|
+
|
|
56
|
+
## Decision memory
|
|
57
|
+
|
|
58
|
+
Studio can record a concise decision and rationale against the current run. Decision memory is private runtime data under the run directory, is bounded to 100 entries, and is redacted before persistence. It becomes part of exported handoffs so the next developer or agent receives the “why,” not only the final state.
|
|
59
|
+
|
|
60
|
+
Do not use decision memory as a credential store or as a replacement for a repository ADR when a durable architectural decision belongs in version control.
|
|
61
|
+
|
|
62
|
+
## Knowledge handoff
|
|
63
|
+
|
|
64
|
+
The top bar provides two forms:
|
|
65
|
+
|
|
66
|
+
- **Copy Brief** creates a human-readable developer summary.
|
|
67
|
+
- **Export Handoff** downloads a machine-readable `.ael-handoff.json` bundle for another agent.
|
|
68
|
+
|
|
69
|
+
The bundle contains objective, workflow state, artifact descriptors, decisions, transitions, and ready next actions. It deliberately excludes source contents. Strings pass through secret and home-path redaction, and the complete canonical manifest is bound to `bundleHash`.
|
|
70
|
+
|
|
71
|
+
Verify a received bundle before trusting it:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
ai-engineering-loop handoff inspect run-id.ael-handoff.json
|
|
75
|
+
ai-engineering-loop handoff brief run-id.ael-handoff.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Inspection accepts only regular files smaller than 1 MiB inside the repository, rejects symlinks and path escapes, and fails if any field no longer matches the bundle hash.
|
|
79
|
+
|
|
80
|
+
## Trust boundary
|
|
81
|
+
|
|
82
|
+
Studio improves authoring and observability; it does not weaken runtime gates:
|
|
83
|
+
|
|
84
|
+
- graph validation does not imply execution permission;
|
|
85
|
+
- command nodes remain disabled;
|
|
86
|
+
- approvals remain explicit state transitions;
|
|
87
|
+
- connector edits cannot bypass the required safety backbone;
|
|
88
|
+
- delivery adapters cannot run before Judge `PASS`;
|
|
89
|
+
- token data comes only from the provider-recorded usage ledger;
|
|
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>
|
package/lib/doctor.js
CHANGED
|
@@ -30,7 +30,8 @@ const REQUIRED_SCHEMAS = [
|
|
|
30
30
|
'node-definition.schema.json',
|
|
31
31
|
'compiled-plan.schema.json',
|
|
32
32
|
'workflow-state.schema.json',
|
|
33
|
-
'workflow-event.schema.json'
|
|
33
|
+
'workflow-event.schema.json',
|
|
34
|
+
'handoff.schema.json'
|
|
34
35
|
];
|
|
35
36
|
|
|
36
37
|
function check(id, passed, detail) {
|
|
@@ -97,7 +98,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
|
|
|
97
98
|
}
|
|
98
99
|
|
|
99
100
|
const packageFiles = new Set(pkg.files || []);
|
|
100
|
-
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
|
|
101
|
+
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/', 'studio/'];
|
|
101
102
|
const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
|
|
102
103
|
checks.push(check(
|
|
103
104
|
'package-assets',
|