ai-engineering-loop 1.5.0 → 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 +12 -2
- 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 +77 -0
- package/lib/doctor.js +3 -2
- package/lib/handoff.js +209 -0
- package/lib/runtime-files.js +1 -0
- package/lib/studio-server.js +183 -0
- package/lib/workflow-runtime.js +30 -4
- package/package.json +2 -1
- package/schemas/handoff.schema.json +36 -0
- package/schemas/workflow-event.schema.json +1 -0
- package/studio/app.js +461 -0
- package/studio/index.html +31 -0
- package/studio/styles.css +75 -0
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const crypto = require('crypto');
|
|
4
|
+
const fs = require('fs');
|
|
5
|
+
const http = require('http');
|
|
6
|
+
const path = require('path');
|
|
7
|
+
const { URL } = require('url');
|
|
8
|
+
const { listRecipes, loadRecipe, validateRecipe, compileRecipe } = require('./recipe.js');
|
|
9
|
+
const { inspectRecipe, installRecipe, recipeCatalog } = require('./recipe-builder.js');
|
|
10
|
+
const { getCurrentRun } = require('./run-state.js');
|
|
11
|
+
const { budgetStatus } = require('./budget.js');
|
|
12
|
+
const {
|
|
13
|
+
workflowStatus,
|
|
14
|
+
approveWorkflowNode,
|
|
15
|
+
retryWorkflowNode,
|
|
16
|
+
recordWorkflowActivity
|
|
17
|
+
} = require('./workflow-runtime.js');
|
|
18
|
+
const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
|
|
19
|
+
|
|
20
|
+
const MAX_BODY = 256 * 1024;
|
|
21
|
+
const ASSET_DIR = path.join(__dirname, '..', 'studio');
|
|
22
|
+
|
|
23
|
+
function json(response, status, value) {
|
|
24
|
+
response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
|
|
25
|
+
response.end(JSON.stringify(value));
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function readBody(request) {
|
|
29
|
+
return new Promise((resolve, reject) => {
|
|
30
|
+
let text = '';
|
|
31
|
+
request.setEncoding('utf8');
|
|
32
|
+
request.on('data', (chunk) => {
|
|
33
|
+
text += chunk;
|
|
34
|
+
if (Buffer.byteLength(text) > MAX_BODY) request.destroy(new Error('Request body exceeds 256 KiB'));
|
|
35
|
+
});
|
|
36
|
+
request.on('end', () => {
|
|
37
|
+
try { resolve(text ? JSON.parse(text) : {}); } catch (error) { reject(error); }
|
|
38
|
+
});
|
|
39
|
+
request.on('error', reject);
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function liveSnapshot(rootDir) {
|
|
44
|
+
const run = getCurrentRun(rootDir);
|
|
45
|
+
if (!run?.workflow) return null;
|
|
46
|
+
const workflow = workflowStatus(rootDir, { runId: run.runId });
|
|
47
|
+
return {
|
|
48
|
+
run,
|
|
49
|
+
plan: workflow.plan,
|
|
50
|
+
nodes: workflow.state.nodes,
|
|
51
|
+
budget: budgetStatus(rootDir, { runId: run.runId }),
|
|
52
|
+
events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
|
|
53
|
+
...event,
|
|
54
|
+
changedNodes: (changes || []).map((change) => change.nodeId)
|
|
55
|
+
}))
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function bootstrap(rootDir) {
|
|
60
|
+
const recipes = listRecipes(rootDir).map(({ id, source }) => ({ ...inspectRecipe(rootDir, id), source }));
|
|
61
|
+
return { recipes, nodeTypes: recipeCatalog(), live: liveSnapshot(rootDir) };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function constantTimeEqual(left, right) {
|
|
65
|
+
const a = Buffer.from(String(left || ''));
|
|
66
|
+
const b = Buffer.from(String(right || ''));
|
|
67
|
+
return a.length === b.length && crypto.timingSafeEqual(a, b);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function localHostname(hostHeader) {
|
|
71
|
+
try {
|
|
72
|
+
return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, '');
|
|
73
|
+
} catch {
|
|
74
|
+
return '';
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('base64url') } = {}) {
|
|
79
|
+
const server = http.createServer(async (request, response) => {
|
|
80
|
+
const hostHeader = String(request.headers.host || '');
|
|
81
|
+
const host = localHostname(hostHeader);
|
|
82
|
+
if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
|
|
83
|
+
response.writeHead(403).end('Forbidden host');
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const url = new URL(request.url, `http://${hostHeader}`);
|
|
87
|
+
const cookieToken = String(request.headers.cookie || '').split(';').map((item) => item.trim())
|
|
88
|
+
.find((item) => item.startsWith('ael_studio='))?.slice('ael_studio='.length);
|
|
89
|
+
const supplied = request.headers['x-ael-studio-token'] || cookieToken;
|
|
90
|
+
if (url.pathname === '/' && constantTimeEqual(url.searchParams.get('token'), token)) {
|
|
91
|
+
response.writeHead(302, {
|
|
92
|
+
location: '/',
|
|
93
|
+
'set-cookie': `ael_studio=${token}; HttpOnly; SameSite=Strict; Path=/`,
|
|
94
|
+
'cache-control': 'no-store',
|
|
95
|
+
'referrer-policy': 'no-referrer'
|
|
96
|
+
}).end();
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
if (!constantTimeEqual(supplied, token)) {
|
|
100
|
+
response.writeHead(401).end('Studio session required');
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
response.setHeader('content-security-policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
|
|
104
|
+
response.setHeader('x-content-type-options', 'nosniff');
|
|
105
|
+
response.setHeader('referrer-policy', 'no-referrer');
|
|
106
|
+
try {
|
|
107
|
+
if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
|
|
108
|
+
json(response, 200, { ok: true, ...bootstrap(rootDir) });
|
|
109
|
+
} else if (request.method === 'GET' && url.pathname === '/api/live') {
|
|
110
|
+
json(response, 200, { ok: true, live: liveSnapshot(rootDir) });
|
|
111
|
+
} else if (request.method === 'GET' && url.pathname === '/api/recipe') {
|
|
112
|
+
const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
|
|
113
|
+
json(response, 200, { ok: true, source: loaded.source, recipe: loaded.recipe });
|
|
114
|
+
} else if (request.method === 'POST' && url.pathname === '/api/validate') {
|
|
115
|
+
const body = await readBody(request);
|
|
116
|
+
const validation = validateRecipe(body.recipe, body.mode ? { mode: body.mode } : {});
|
|
117
|
+
json(response, validation.valid ? 200 : 422, {
|
|
118
|
+
ok: validation.valid,
|
|
119
|
+
validation,
|
|
120
|
+
plans: validation.valid
|
|
121
|
+
? (body.mode ? [body.mode] : body.recipe.compatibleModes).map((mode) => compileRecipe(body.recipe, { mode }))
|
|
122
|
+
: []
|
|
123
|
+
});
|
|
124
|
+
} else if (request.method === 'POST' && url.pathname === '/api/install') {
|
|
125
|
+
const body = await readBody(request);
|
|
126
|
+
const drafts = path.join(rootDir, '.ai-engineering-loop', 'drafts');
|
|
127
|
+
fs.mkdirSync(drafts, { recursive: true, mode: 0o700 });
|
|
128
|
+
const candidate = path.join(drafts, `${crypto.randomUUID()}.json`);
|
|
129
|
+
fs.writeFileSync(candidate, JSON.stringify(body.recipe), { mode: 0o600 });
|
|
130
|
+
try {
|
|
131
|
+
const result = installRecipe(rootDir, path.relative(rootDir, candidate), { replace: body.replace === true });
|
|
132
|
+
json(response, 200, { ok: true, id: result.recipe.id, version: result.recipe.version, sourceHash: result.sourceHash });
|
|
133
|
+
} finally {
|
|
134
|
+
try { fs.unlinkSync(candidate); } catch {}
|
|
135
|
+
}
|
|
136
|
+
} else if (request.method === 'GET' && url.pathname === '/api/handoff') {
|
|
137
|
+
const bundle = createHandoff(rootDir, { audience: url.searchParams.get('audience') || 'developer' });
|
|
138
|
+
json(response, 200, { ok: true, bundle, brief: handoffBrief(bundle) });
|
|
139
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/approve') {
|
|
140
|
+
const body = await readBody(request);
|
|
141
|
+
approveWorkflowNode(rootDir, body.nodeId, { runId: body.runId, approvedBy: body.approvedBy || 'human' });
|
|
142
|
+
json(response, 200, { ok: true });
|
|
143
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/retry') {
|
|
144
|
+
const body = await readBody(request);
|
|
145
|
+
retryWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
|
|
146
|
+
json(response, 200, { ok: true });
|
|
147
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/activity') {
|
|
148
|
+
const body = await readBody(request);
|
|
149
|
+
recordWorkflowActivity(rootDir, body.nodeId, {
|
|
150
|
+
runId: body.runId,
|
|
151
|
+
message: body.message
|
|
152
|
+
});
|
|
153
|
+
json(response, 200, { ok: true });
|
|
154
|
+
} else if (request.method === 'POST' && url.pathname === '/api/decision') {
|
|
155
|
+
const body = await readBody(request);
|
|
156
|
+
const result = recordDecision(rootDir, {
|
|
157
|
+
runId: body.runId,
|
|
158
|
+
summary: body.summary,
|
|
159
|
+
rationale: body.rationale,
|
|
160
|
+
consequences: body.consequences
|
|
161
|
+
});
|
|
162
|
+
json(response, 200, { ok: true, ...result });
|
|
163
|
+
} else {
|
|
164
|
+
const asset = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
|
|
165
|
+
if (!['index.html', 'app.js', 'styles.css'].includes(asset)) {
|
|
166
|
+
response.writeHead(404).end('Not found');
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
const types = { html: 'text/html', js: 'text/javascript', css: 'text/css' };
|
|
170
|
+
response.writeHead(200, {
|
|
171
|
+
'content-type': `${types[asset.split('.').at(-1)]}; charset=utf-8`,
|
|
172
|
+
'cache-control': 'no-store'
|
|
173
|
+
});
|
|
174
|
+
response.end(fs.readFileSync(path.join(ASSET_DIR, asset)));
|
|
175
|
+
}
|
|
176
|
+
} catch (error) {
|
|
177
|
+
json(response, 400, { ok: false, code: error.code || 'STUDIO_ERROR', error: error.message, details: error.details || [] });
|
|
178
|
+
}
|
|
179
|
+
});
|
|
180
|
+
return { server, token };
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
module.exports = { createStudioServer, bootstrap, liveSnapshot };
|
package/lib/workflow-runtime.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
const fs = require('fs');
|
|
4
4
|
const path = require('path');
|
|
5
5
|
const { sha256 } = require('./recipe.js');
|
|
6
|
+
const { redactSecrets } = require('./safe-context.js');
|
|
6
7
|
const {
|
|
7
8
|
RUN_STATES,
|
|
8
9
|
atomicWriteJson,
|
|
@@ -531,6 +532,7 @@ function completeWorkflowNode(rootDir, nodeId, { runId, artifact, now = new Date
|
|
|
531
532
|
let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
|
|
532
533
|
attempts: workflow.state.nodes[nodeId].attempts + (currentStatus === NODE_STATES.READY ? 1 : 0),
|
|
533
534
|
reason: null,
|
|
535
|
+
activity: null,
|
|
534
536
|
...(artifactDescriptor ? { artifact: artifactDescriptor } : {})
|
|
535
537
|
}, now);
|
|
536
538
|
changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
|
|
@@ -551,12 +553,31 @@ function startWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
|
|
|
551
553
|
}
|
|
552
554
|
const changes = nodeChanges(workflow, nodeId, NODE_STATES.RUNNING, {
|
|
553
555
|
attempts: workflow.state.nodes[nodeId].attempts + 1,
|
|
554
|
-
reason: null
|
|
556
|
+
reason: null,
|
|
557
|
+
activity: 'Node started'
|
|
555
558
|
}, now);
|
|
556
559
|
return commitChanges(rootDir, workflow, 'NODE_STARTED', changes, { nodeId }, now);
|
|
557
560
|
});
|
|
558
561
|
}
|
|
559
562
|
|
|
563
|
+
function recordWorkflowActivity(rootDir, nodeId, { runId, message, now = new Date() } = {}) {
|
|
564
|
+
const resolved = resolveRunId(rootDir, runId);
|
|
565
|
+
return withWorkflowLock(rootDir, resolved, () => {
|
|
566
|
+
const workflow = loadWorkflow(rootDir, resolved);
|
|
567
|
+
const current = workflow.state.nodes[nodeId];
|
|
568
|
+
if (!current) throw runtimeError(`Unknown workflow node: ${nodeId}`, 'UNKNOWN_WORKFLOW_NODE');
|
|
569
|
+
if (current.status !== NODE_STATES.RUNNING) {
|
|
570
|
+
throw runtimeError(`Node ${nodeId} is ${current.status}, not RUNNING`, 'INVALID_NODE_TRANSITION');
|
|
571
|
+
}
|
|
572
|
+
const activity = redactSecrets(String(message || '').trim()).text;
|
|
573
|
+
if (!activity || activity.length > 240 || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(activity)) {
|
|
574
|
+
throw runtimeError('Activity must be 1-240 printable characters', 'INVALID_NODE_ACTIVITY');
|
|
575
|
+
}
|
|
576
|
+
const changes = nodeChanges(workflow, nodeId, NODE_STATES.RUNNING, { activity }, now);
|
|
577
|
+
return commitChanges(rootDir, workflow, 'NODE_ACTIVITY', changes, { nodeId }, now);
|
|
578
|
+
});
|
|
579
|
+
}
|
|
580
|
+
|
|
560
581
|
function failWorkflowNode(rootDir, nodeId, { runId, reason = 'node execution failed', now = new Date() } = {}) {
|
|
561
582
|
const resolved = resolveRunId(rootDir, runId);
|
|
562
583
|
return withWorkflowLock(rootDir, resolved, () => {
|
|
@@ -566,9 +587,11 @@ function failWorkflowNode(rootDir, nodeId, { runId, reason = 'node execution fai
|
|
|
566
587
|
if (![NODE_STATES.READY, NODE_STATES.RUNNING].includes(current.status)) {
|
|
567
588
|
throw runtimeError(`Node ${nodeId} cannot fail from ${current.status}`, 'INVALID_NODE_TRANSITION');
|
|
568
589
|
}
|
|
590
|
+
const safeReason = redactSecrets(String(reason)).text.slice(0, 500);
|
|
569
591
|
let changes = nodeChanges(workflow, nodeId, NODE_STATES.FAILED, {
|
|
570
592
|
attempts: current.attempts + (current.status === NODE_STATES.READY ? 1 : 0),
|
|
571
|
-
reason:
|
|
593
|
+
reason: safeReason,
|
|
594
|
+
activity: null
|
|
572
595
|
}, now);
|
|
573
596
|
changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
|
|
574
597
|
return commitChanges(rootDir, workflow, 'NODE_FAILED', changes, { nodeId }, now);
|
|
@@ -584,7 +607,7 @@ function retryWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
|
|
|
584
607
|
if (![NODE_STATES.FAILED, NODE_STATES.RUNNING].includes(current.status)) {
|
|
585
608
|
throw runtimeError(`Node ${nodeId} cannot retry from ${current.status}`, 'INVALID_NODE_TRANSITION');
|
|
586
609
|
}
|
|
587
|
-
let changes = nodeChanges(workflow, nodeId, NODE_STATES.READY, { reason: null }, now);
|
|
610
|
+
let changes = nodeChanges(workflow, nodeId, NODE_STATES.READY, { reason: null, activity: null }, now);
|
|
588
611
|
changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
|
|
589
612
|
return commitChanges(rootDir, workflow, 'NODE_RETRIED', changes, { nodeId }, now);
|
|
590
613
|
});
|
|
@@ -604,6 +627,7 @@ function approveWorkflowNode(rootDir, nodeId, { runId, approvedBy = 'human', now
|
|
|
604
627
|
let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
|
|
605
628
|
attempts: workflow.state.nodes[nodeId].attempts + 1,
|
|
606
629
|
reason: null,
|
|
630
|
+
activity: null,
|
|
607
631
|
approvedBy
|
|
608
632
|
}, now);
|
|
609
633
|
changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
|
|
@@ -638,7 +662,8 @@ function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
|
|
|
638
662
|
workflow.run = run;
|
|
639
663
|
let changes = nodeChanges(workflow, node.id, NODE_STATES.PASSED, {
|
|
640
664
|
attempts: workflow.state.nodes[node.id].attempts + 1,
|
|
641
|
-
reason: null
|
|
665
|
+
reason: null,
|
|
666
|
+
activity: null
|
|
642
667
|
}, now);
|
|
643
668
|
if (gate === 'judge' && run.state === RUN_STATES.GOAL_FROZEN) {
|
|
644
669
|
const maker = workflow.plan.nodes.find((candidate) => candidate.type === 'maker');
|
|
@@ -684,6 +709,7 @@ module.exports = {
|
|
|
684
709
|
completeWorkflowNode,
|
|
685
710
|
failWorkflowNode,
|
|
686
711
|
retryWorkflowNode,
|
|
712
|
+
recordWorkflowActivity,
|
|
687
713
|
approveWorkflowNode,
|
|
688
714
|
applyWorkflowGate,
|
|
689
715
|
evaluateCondition,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-engineering-loop",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.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": {
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
"adapters/",
|
|
17
17
|
"recipes/",
|
|
18
18
|
"schemas/",
|
|
19
|
+
"studio/",
|
|
19
20
|
"evals/",
|
|
20
21
|
".agents/",
|
|
21
22
|
".grok/",
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://github.com/egagofur/ai-engineering-loop/schemas/handoff.schema.json",
|
|
4
|
+
"title": "AI Engineering Loop Redacted Handoff",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": [
|
|
7
|
+
"schemaVersion",
|
|
8
|
+
"audience",
|
|
9
|
+
"runId",
|
|
10
|
+
"generatedAt",
|
|
11
|
+
"finalState",
|
|
12
|
+
"redacted",
|
|
13
|
+
"sourceIncluded",
|
|
14
|
+
"redactionCategories",
|
|
15
|
+
"content",
|
|
16
|
+
"bundleHash"
|
|
17
|
+
],
|
|
18
|
+
"properties": {
|
|
19
|
+
"schemaVersion": { "const": 1 },
|
|
20
|
+
"audience": { "enum": ["developer", "agent", "auditor"] },
|
|
21
|
+
"runId": { "type": "string", "minLength": 1 },
|
|
22
|
+
"generatedAt": { "type": "string", "format": "date-time" },
|
|
23
|
+
"graphHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
|
|
24
|
+
"finalState": { "type": "string", "minLength": 1 },
|
|
25
|
+
"redacted": { "const": true },
|
|
26
|
+
"sourceIncluded": { "const": false },
|
|
27
|
+
"redactionCategories": {
|
|
28
|
+
"type": "array",
|
|
29
|
+
"items": { "type": "string" },
|
|
30
|
+
"uniqueItems": true
|
|
31
|
+
},
|
|
32
|
+
"content": { "type": "object" },
|
|
33
|
+
"bundleHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
|
|
34
|
+
},
|
|
35
|
+
"additionalProperties": false
|
|
36
|
+
}
|