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/lib/handoff.js
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { canonicalJson, sha256 } = require('./recipe.js');
|
|
6
|
+
const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
7
|
+
const { redactSecrets } = require('./safe-context.js');
|
|
8
|
+
const { workflowStatus } = require('./workflow-runtime.js');
|
|
9
|
+
|
|
10
|
+
const AUDIENCES = new Set(['developer', 'agent', 'auditor']);
|
|
11
|
+
const MAX_BUNDLE_BYTES = 1024 * 1024;
|
|
12
|
+
|
|
13
|
+
function handoffError(message, code = 'HANDOFF_FAILED') {
|
|
14
|
+
const error = new Error(message);
|
|
15
|
+
error.code = code;
|
|
16
|
+
return error;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function resolveRun(rootDir, runId) {
|
|
20
|
+
const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
|
|
21
|
+
if (!run) throw handoffError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
|
|
22
|
+
return run;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function redactValue(value, categories) {
|
|
26
|
+
if (typeof value === 'string') {
|
|
27
|
+
const result = redactSecrets(value);
|
|
28
|
+
result.categories.forEach((category) => categories.add(category));
|
|
29
|
+
const redacted = result.text
|
|
30
|
+
.replace(/(?:file:\/\/)?\/?Users\/[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
|
|
31
|
+
.replace(/\b[A-Z]:\\Users\\[^\\\s]+/gi, '[REDACTED HOME]');
|
|
32
|
+
if (redacted !== result.text) categories.add('HOME_PATH');
|
|
33
|
+
return redacted;
|
|
34
|
+
}
|
|
35
|
+
if (Array.isArray(value)) return value.map((item) => redactValue(item, categories));
|
|
36
|
+
if (value && typeof value === 'object') {
|
|
37
|
+
return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item, categories)]));
|
|
38
|
+
}
|
|
39
|
+
return value;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function loadOptionalJson(filePath) {
|
|
43
|
+
if (!fs.existsSync(filePath)) return null;
|
|
44
|
+
const stat = fs.lstatSync(filePath);
|
|
45
|
+
if (stat.isSymbolicLink() || !stat.isFile()) throw handoffError('Optional handoff input must be a regular file');
|
|
46
|
+
try {
|
|
47
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
48
|
+
} catch (cause) {
|
|
49
|
+
throw handoffError(`Optional handoff input is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF_INPUT');
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function recordDecision(rootDir, {
|
|
54
|
+
runId,
|
|
55
|
+
summary,
|
|
56
|
+
rationale,
|
|
57
|
+
consequences = [],
|
|
58
|
+
now = new Date()
|
|
59
|
+
} = {}) {
|
|
60
|
+
const run = resolveRun(rootDir, runId);
|
|
61
|
+
if (typeof summary !== 'string' || !summary.trim() || summary.trim().length > 160) {
|
|
62
|
+
throw handoffError('Decision summary must be 1-160 characters', 'INVALID_DECISION');
|
|
63
|
+
}
|
|
64
|
+
if (typeof rationale !== 'string' || !rationale.trim() || rationale.trim().length > 1000) {
|
|
65
|
+
throw handoffError('Decision rationale must be 1-1000 characters', 'INVALID_DECISION');
|
|
66
|
+
}
|
|
67
|
+
if (!Array.isArray(consequences) || consequences.length > 20 || consequences.some(
|
|
68
|
+
(item) => typeof item !== 'string' || !item.trim() || item.length > 240
|
|
69
|
+
)) {
|
|
70
|
+
throw handoffError('Decision consequences must contain at most 20 short strings', 'INVALID_DECISION');
|
|
71
|
+
}
|
|
72
|
+
const filePath = path.join(runsDir(rootDir), run.runId, 'decisions.json');
|
|
73
|
+
const decisions = loadOptionalJson(filePath) || [];
|
|
74
|
+
if (!Array.isArray(decisions) || decisions.length >= 100) {
|
|
75
|
+
throw handoffError('Decision memory must be an array with fewer than 100 entries', 'INVALID_DECISION');
|
|
76
|
+
}
|
|
77
|
+
const categories = new Set();
|
|
78
|
+
const entry = redactValue({
|
|
79
|
+
id: `decision-${String(decisions.length + 1).padStart(3, '0')}`,
|
|
80
|
+
summary: summary.trim(),
|
|
81
|
+
rationale: rationale.trim(),
|
|
82
|
+
consequences: consequences.map((item) => item.trim()),
|
|
83
|
+
recordedAt: now.toISOString()
|
|
84
|
+
}, categories);
|
|
85
|
+
atomicWriteJson(filePath, [...decisions, entry]);
|
|
86
|
+
return { runId: run.runId, decision: entry, redactionCategories: [...categories].sort() };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function createHandoff(rootDir, { runId, audience = 'developer', now = new Date() } = {}) {
|
|
90
|
+
if (!AUDIENCES.has(audience)) throw handoffError(`Invalid audience: ${audience}`);
|
|
91
|
+
const run = resolveRun(rootDir, runId);
|
|
92
|
+
const directory = path.join(runsDir(rootDir), run.runId);
|
|
93
|
+
const workflow = run.workflow ? workflowStatus(rootDir, { runId: run.runId }) : null;
|
|
94
|
+
const decisions = loadOptionalJson(path.join(directory, 'decisions.json')) || [];
|
|
95
|
+
if (!Array.isArray(decisions)) throw handoffError('Decision memory must be an array', 'INVALID_HANDOFF_INPUT');
|
|
96
|
+
const categories = new Set();
|
|
97
|
+
const content = redactValue({
|
|
98
|
+
objective: run.task,
|
|
99
|
+
state: run.state,
|
|
100
|
+
mode: run.mode,
|
|
101
|
+
iteration: run.iteration,
|
|
102
|
+
recipe: run.workflow || null,
|
|
103
|
+
nodes: workflow ? workflow.plan.nodes.map((node) => ({
|
|
104
|
+
id: node.id,
|
|
105
|
+
type: node.type,
|
|
106
|
+
status: workflow.state.nodes[node.id].status,
|
|
107
|
+
attempts: workflow.state.nodes[node.id].attempts,
|
|
108
|
+
reason: workflow.state.nodes[node.id].reason || null,
|
|
109
|
+
activity: workflow.state.nodes[node.id].activity || null
|
|
110
|
+
})) : [],
|
|
111
|
+
artifacts: run.artifacts,
|
|
112
|
+
decisions,
|
|
113
|
+
transitions: run.history,
|
|
114
|
+
nextActions: workflow
|
|
115
|
+
? workflow.plan.nodes.filter((node) => workflow.state.nodes[node.id].status === 'READY').map((node) => node.id)
|
|
116
|
+
: []
|
|
117
|
+
}, categories);
|
|
118
|
+
const material = {
|
|
119
|
+
schemaVersion: 1,
|
|
120
|
+
audience,
|
|
121
|
+
runId: run.runId,
|
|
122
|
+
generatedAt: now.toISOString(),
|
|
123
|
+
graphHash: run.workflow?.graphHash || null,
|
|
124
|
+
finalState: run.state,
|
|
125
|
+
redacted: true,
|
|
126
|
+
sourceIncluded: false,
|
|
127
|
+
redactionCategories: [...categories].sort(),
|
|
128
|
+
content
|
|
129
|
+
};
|
|
130
|
+
return { ...material, bundleHash: sha256(material) };
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function handoffBrief(bundle) {
|
|
134
|
+
const lines = [
|
|
135
|
+
'# Engineering Handoff',
|
|
136
|
+
'',
|
|
137
|
+
`Run: ${bundle.runId}`,
|
|
138
|
+
`State: ${bundle.finalState}`,
|
|
139
|
+
`Mode: ${bundle.content.mode}`,
|
|
140
|
+
`Graph: ${bundle.graphHash || 'legacy'}`,
|
|
141
|
+
'',
|
|
142
|
+
'## Objective',
|
|
143
|
+
bundle.content.objective || 'Not recorded.',
|
|
144
|
+
'',
|
|
145
|
+
'## Workflow',
|
|
146
|
+
...bundle.content.nodes.map((node) => `- ${node.id}: ${node.status}${node.reason ? ` — ${node.reason}` : ''}`),
|
|
147
|
+
'',
|
|
148
|
+
'## Decisions',
|
|
149
|
+
...(bundle.content.decisions.length ? bundle.content.decisions.map((decision) => `- ${decision.decision || decision.summary || JSON.stringify(decision)}`) : ['- None recorded.']),
|
|
150
|
+
'',
|
|
151
|
+
'## Evidence',
|
|
152
|
+
...Object.entries(bundle.content.artifacts).map(([name, artifact]) => (
|
|
153
|
+
`- ${name}: ${artifact && typeof artifact === 'object' ? artifact.sha256 || 'recorded' : 'recorded'}`
|
|
154
|
+
)),
|
|
155
|
+
'',
|
|
156
|
+
'## Next actions',
|
|
157
|
+
...(bundle.content.nextActions.length ? bundle.content.nextActions.map((action) => `- ${action}`) : ['- No READY nodes.'])
|
|
158
|
+
];
|
|
159
|
+
return lines.join('\n');
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function verifyHandoff(bundle) {
|
|
163
|
+
if (!bundle || bundle.schemaVersion !== 1 || !AUDIENCES.has(bundle.audience)) {
|
|
164
|
+
throw handoffError('Handoff manifest is invalid', 'INVALID_HANDOFF');
|
|
165
|
+
}
|
|
166
|
+
const { bundleHash, ...material } = bundle;
|
|
167
|
+
if (bundleHash !== sha256(material)) throw handoffError('Handoff bundle hash does not match', 'HANDOFF_TAMPERED');
|
|
168
|
+
return {
|
|
169
|
+
valid: true,
|
|
170
|
+
runId: bundle.runId,
|
|
171
|
+
audience: bundle.audience,
|
|
172
|
+
bundleHash,
|
|
173
|
+
canonicalBytes: Buffer.byteLength(canonicalJson(bundle))
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function readHandoff(rootDir, file) {
|
|
178
|
+
const absolute = path.resolve(rootDir, file);
|
|
179
|
+
const relative = path.relative(rootDir, absolute);
|
|
180
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`)) throw handoffError('Handoff path escapes repository');
|
|
181
|
+
let stat;
|
|
182
|
+
try {
|
|
183
|
+
stat = fs.lstatSync(absolute);
|
|
184
|
+
} catch (cause) {
|
|
185
|
+
throw handoffError(`Unable to inspect handoff: ${cause.message}`, 'INVALID_HANDOFF');
|
|
186
|
+
}
|
|
187
|
+
if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_BUNDLE_BYTES) {
|
|
188
|
+
throw handoffError('Handoff must be a regular file under 1 MiB');
|
|
189
|
+
}
|
|
190
|
+
const realRoot = fs.realpathSync(rootDir);
|
|
191
|
+
const realFile = fs.realpathSync(absolute);
|
|
192
|
+
if (realFile !== realRoot && !realFile.startsWith(`${realRoot}${path.sep}`)) {
|
|
193
|
+
throw handoffError('Handoff path escapes repository through a symlink');
|
|
194
|
+
}
|
|
195
|
+
try {
|
|
196
|
+
return JSON.parse(fs.readFileSync(absolute, 'utf8'));
|
|
197
|
+
} catch (cause) {
|
|
198
|
+
throw handoffError(`Handoff is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF');
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
module.exports = {
|
|
203
|
+
AUDIENCES,
|
|
204
|
+
createHandoff,
|
|
205
|
+
handoffBrief,
|
|
206
|
+
recordDecision,
|
|
207
|
+
verifyHandoff,
|
|
208
|
+
readHandoff
|
|
209
|
+
};
|
package/lib/recipe-builder.js
CHANGED
package/lib/runtime-files.js
CHANGED
|
@@ -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
|
+
};
|
|
@@ -0,0 +1,231 @@
|
|
|
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
|
+
const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
|
|
20
|
+
const {
|
|
21
|
+
SHIPPED_TYPES,
|
|
22
|
+
detectAdapterHints,
|
|
23
|
+
writeShippedAdapter
|
|
24
|
+
} = require('./generate-adapter.js');
|
|
25
|
+
|
|
26
|
+
const MAX_BODY = 256 * 1024;
|
|
27
|
+
const ASSET_DIR = path.join(__dirname, '..', 'studio');
|
|
28
|
+
|
|
29
|
+
function json(response, status, value) {
|
|
30
|
+
response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
|
|
31
|
+
response.end(JSON.stringify(value));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function readBody(request) {
|
|
35
|
+
return new Promise((resolve, reject) => {
|
|
36
|
+
let text = '';
|
|
37
|
+
request.setEncoding('utf8');
|
|
38
|
+
request.on('data', (chunk) => {
|
|
39
|
+
text += chunk;
|
|
40
|
+
if (Buffer.byteLength(text) > MAX_BODY) request.destroy(new Error('Request body exceeds 256 KiB'));
|
|
41
|
+
});
|
|
42
|
+
request.on('end', () => {
|
|
43
|
+
try { resolve(text ? JSON.parse(text) : {}); } catch (error) { reject(error); }
|
|
44
|
+
});
|
|
45
|
+
request.on('error', reject);
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function liveSnapshot(rootDir) {
|
|
50
|
+
const run = getCurrentRun(rootDir);
|
|
51
|
+
if (!run?.workflow) return null;
|
|
52
|
+
const workflow = workflowStatus(rootDir, { runId: run.runId });
|
|
53
|
+
return {
|
|
54
|
+
run,
|
|
55
|
+
plan: workflow.plan,
|
|
56
|
+
nodes: workflow.state.nodes,
|
|
57
|
+
budget: budgetStatus(rootDir, { runId: run.runId }),
|
|
58
|
+
events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
|
|
59
|
+
...event,
|
|
60
|
+
changedNodes: (changes || []).map((change) => change.nodeId)
|
|
61
|
+
}))
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function bootstrap(rootDir) {
|
|
66
|
+
const recipes = listRecipes(rootDir).map(({ id, source }) => ({ ...inspectRecipe(rootDir, id), source }));
|
|
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
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function constantTimeEqual(left, right) {
|
|
82
|
+
const a = Buffer.from(String(left || ''));
|
|
83
|
+
const b = Buffer.from(String(right || ''));
|
|
84
|
+
return a.length === b.length && crypto.timingSafeEqual(a, b);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function localHostname(hostHeader) {
|
|
88
|
+
try {
|
|
89
|
+
return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, '');
|
|
90
|
+
} catch {
|
|
91
|
+
return '';
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('base64url') } = {}) {
|
|
96
|
+
const server = http.createServer(async (request, response) => {
|
|
97
|
+
const hostHeader = String(request.headers.host || '');
|
|
98
|
+
const host = localHostname(hostHeader);
|
|
99
|
+
if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
|
|
100
|
+
response.writeHead(403).end('Forbidden host');
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
const url = new URL(request.url, `http://${hostHeader}`);
|
|
104
|
+
const cookieToken = String(request.headers.cookie || '').split(';').map((item) => item.trim())
|
|
105
|
+
.find((item) => item.startsWith('ael_studio='))?.slice('ael_studio='.length);
|
|
106
|
+
const supplied = request.headers['x-ael-studio-token'] || cookieToken;
|
|
107
|
+
if (url.pathname === '/' && constantTimeEqual(url.searchParams.get('token'), token)) {
|
|
108
|
+
response.writeHead(302, {
|
|
109
|
+
location: '/',
|
|
110
|
+
'set-cookie': `ael_studio=${token}; HttpOnly; SameSite=Strict; Path=/`,
|
|
111
|
+
'cache-control': 'no-store',
|
|
112
|
+
'referrer-policy': 'no-referrer'
|
|
113
|
+
}).end();
|
|
114
|
+
return;
|
|
115
|
+
}
|
|
116
|
+
if (!constantTimeEqual(supplied, token)) {
|
|
117
|
+
response.writeHead(401).end('Studio session required');
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
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'");
|
|
121
|
+
response.setHeader('x-content-type-options', 'nosniff');
|
|
122
|
+
response.setHeader('referrer-policy', 'no-referrer');
|
|
123
|
+
try {
|
|
124
|
+
if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
|
|
125
|
+
json(response, 200, { ok: true, ...bootstrap(rootDir) });
|
|
126
|
+
} else if (request.method === 'GET' && url.pathname === '/api/live') {
|
|
127
|
+
json(response, 200, { ok: true, live: liveSnapshot(rootDir) });
|
|
128
|
+
} else if (request.method === 'GET' && url.pathname === '/api/recipe') {
|
|
129
|
+
const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
|
|
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
|
+
});
|
|
157
|
+
} else if (request.method === 'POST' && url.pathname === '/api/validate') {
|
|
158
|
+
const body = await readBody(request);
|
|
159
|
+
const validation = validateRecipe(body.recipe, body.mode ? { mode: body.mode } : {});
|
|
160
|
+
json(response, validation.valid ? 200 : 422, {
|
|
161
|
+
ok: validation.valid,
|
|
162
|
+
validation,
|
|
163
|
+
plans: validation.valid
|
|
164
|
+
? (body.mode ? [body.mode] : body.recipe.compatibleModes).map((mode) => compileRecipe(body.recipe, { mode }))
|
|
165
|
+
: []
|
|
166
|
+
});
|
|
167
|
+
} else if (request.method === 'POST' && url.pathname === '/api/install') {
|
|
168
|
+
const body = await readBody(request);
|
|
169
|
+
const drafts = path.join(rootDir, '.ai-engineering-loop', 'drafts');
|
|
170
|
+
fs.mkdirSync(drafts, { recursive: true, mode: 0o700 });
|
|
171
|
+
const candidate = path.join(drafts, `${crypto.randomUUID()}.json`);
|
|
172
|
+
fs.writeFileSync(candidate, JSON.stringify(body.recipe), { mode: 0o600 });
|
|
173
|
+
try {
|
|
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
|
+
}
|
|
180
|
+
json(response, 200, { ok: true, id: result.recipe.id, version: result.recipe.version, sourceHash: result.sourceHash });
|
|
181
|
+
} finally {
|
|
182
|
+
try { fs.unlinkSync(candidate); } catch {}
|
|
183
|
+
}
|
|
184
|
+
} else if (request.method === 'GET' && url.pathname === '/api/handoff') {
|
|
185
|
+
const bundle = createHandoff(rootDir, { audience: url.searchParams.get('audience') || 'developer' });
|
|
186
|
+
json(response, 200, { ok: true, bundle, brief: handoffBrief(bundle) });
|
|
187
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/approve') {
|
|
188
|
+
const body = await readBody(request);
|
|
189
|
+
approveWorkflowNode(rootDir, body.nodeId, { runId: body.runId, approvedBy: body.approvedBy || 'human' });
|
|
190
|
+
json(response, 200, { ok: true });
|
|
191
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/retry') {
|
|
192
|
+
const body = await readBody(request);
|
|
193
|
+
retryWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
|
|
194
|
+
json(response, 200, { ok: true });
|
|
195
|
+
} else if (request.method === 'POST' && url.pathname === '/api/node/activity') {
|
|
196
|
+
const body = await readBody(request);
|
|
197
|
+
recordWorkflowActivity(rootDir, body.nodeId, {
|
|
198
|
+
runId: body.runId,
|
|
199
|
+
message: body.message
|
|
200
|
+
});
|
|
201
|
+
json(response, 200, { ok: true });
|
|
202
|
+
} else if (request.method === 'POST' && url.pathname === '/api/decision') {
|
|
203
|
+
const body = await readBody(request);
|
|
204
|
+
const result = recordDecision(rootDir, {
|
|
205
|
+
runId: body.runId,
|
|
206
|
+
summary: body.summary,
|
|
207
|
+
rationale: body.rationale,
|
|
208
|
+
consequences: body.consequences
|
|
209
|
+
});
|
|
210
|
+
json(response, 200, { ok: true, ...result });
|
|
211
|
+
} else {
|
|
212
|
+
const asset = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
|
|
213
|
+
if (!['index.html', 'app.js', 'styles.css'].includes(asset)) {
|
|
214
|
+
response.writeHead(404).end('Not found');
|
|
215
|
+
return;
|
|
216
|
+
}
|
|
217
|
+
const types = { html: 'text/html', js: 'text/javascript', css: 'text/css' };
|
|
218
|
+
response.writeHead(200, {
|
|
219
|
+
'content-type': `${types[asset.split('.').at(-1)]}; charset=utf-8`,
|
|
220
|
+
'cache-control': 'no-store'
|
|
221
|
+
});
|
|
222
|
+
response.end(fs.readFileSync(path.join(ASSET_DIR, asset)));
|
|
223
|
+
}
|
|
224
|
+
} catch (error) {
|
|
225
|
+
json(response, 400, { ok: false, code: error.code || 'STUDIO_ERROR', error: error.message, details: error.details || [] });
|
|
226
|
+
}
|
|
227
|
+
});
|
|
228
|
+
return { server, token };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
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.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": {
|
|
@@ -16,6 +16,8 @@
|
|
|
16
16
|
"adapters/",
|
|
17
17
|
"recipes/",
|
|
18
18
|
"schemas/",
|
|
19
|
+
"studio/",
|
|
20
|
+
"docs/images/",
|
|
19
21
|
"evals/",
|
|
20
22
|
".agents/",
|
|
21
23
|
".grok/",
|