ai-engineering-loop 1.2.1 → 1.5.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 +37 -4
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +305 -10
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +42 -4
- package/lib/doctor.js +25 -2
- package/lib/node-registry.js +155 -0
- package/lib/recipe-builder.js +200 -0
- package/lib/recipe.js +495 -0
- package/lib/run-state.js +50 -3
- package/lib/runtime-files.js +1 -0
- package/lib/workflow-runtime.js +692 -0
- package/package.json +2 -1
- package/recipes/audit.json +32 -0
- package/recipes/bugfix.json +63 -0
- package/recipes/default.json +49 -0
- package/recipes/docs-light.json +63 -0
- package/recipes/high-risk.json +69 -0
- package/recipes/refactor.json +63 -0
- package/schemas/compiled-plan.schema.json +19 -0
- package/schemas/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/workflow-event.schema.json +28 -0
- package/schemas/workflow-state.schema.json +29 -0
package/lib/recipe.js
ADDED
|
@@ -0,0 +1,495 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const crypto = require('crypto');
|
|
4
|
+
const fs = require('fs');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { RUN_MODES, normalizeRunMode } = require('./run-state.js');
|
|
7
|
+
const {
|
|
8
|
+
NODE_TYPES,
|
|
9
|
+
CONDITION_OPERATORS,
|
|
10
|
+
CONDITION_FIELDS,
|
|
11
|
+
FORBIDDEN_COMMANDS,
|
|
12
|
+
getNodeType
|
|
13
|
+
} = require('./node-registry.js');
|
|
14
|
+
|
|
15
|
+
const RECIPE_ID = /^[a-z][a-z0-9-]{0,63}$/;
|
|
16
|
+
const NODE_ID = /^[a-z][a-z0-9-]{0,63}$/;
|
|
17
|
+
const MAX_NODES = 64;
|
|
18
|
+
const BUILTIN_RECIPE_DIR = path.join(__dirname, '..', 'recipes');
|
|
19
|
+
|
|
20
|
+
function recipeError(message, details = [], code = 'INVALID_RECIPE') {
|
|
21
|
+
const err = new Error(message);
|
|
22
|
+
err.code = code;
|
|
23
|
+
err.details = details;
|
|
24
|
+
return err;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function canonicalize(value) {
|
|
28
|
+
if (Array.isArray(value)) return value.map(canonicalize);
|
|
29
|
+
if (value && typeof value === 'object') {
|
|
30
|
+
return Object.fromEntries(
|
|
31
|
+
Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
return value;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function canonicalJson(value) {
|
|
38
|
+
return JSON.stringify(canonicalize(value));
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function sha256(value) {
|
|
42
|
+
return crypto.createHash('sha256').update(
|
|
43
|
+
typeof value === 'string' || Buffer.isBuffer(value) ? value : canonicalJson(value)
|
|
44
|
+
).digest('hex');
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function validateCondition(condition, location, errors) {
|
|
48
|
+
if (!condition || typeof condition !== 'object' || Array.isArray(condition)) {
|
|
49
|
+
errors.push(`${location} must be a structured condition object`);
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
if (!CONDITION_FIELDS.includes(condition.field)) {
|
|
53
|
+
errors.push(`${location}.field must be one of ${CONDITION_FIELDS.join(', ')}`);
|
|
54
|
+
}
|
|
55
|
+
if (!CONDITION_OPERATORS.includes(condition.operator)) {
|
|
56
|
+
errors.push(`${location}.operator must be one of ${CONDITION_OPERATORS.join(', ')}`);
|
|
57
|
+
}
|
|
58
|
+
if (!['exists', 'isEmpty'].includes(condition.operator) && !Object.hasOwn(condition, 'value')) {
|
|
59
|
+
errors.push(`${location}.value is required for ${condition.operator || 'this operator'}`);
|
|
60
|
+
}
|
|
61
|
+
if (condition.operator === 'matchesAny' && !Array.isArray(condition.value)) {
|
|
62
|
+
errors.push(`${location}.value must be an array for matchesAny`);
|
|
63
|
+
}
|
|
64
|
+
if (['greaterThan', 'lessThan'].includes(condition.operator) && typeof condition.value !== 'number') {
|
|
65
|
+
errors.push(`${location}.value must be a number for ${condition.operator}`);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function validateNodeConfiguration(node, index, errors, warnings) {
|
|
70
|
+
const location = `nodes[${index}]`;
|
|
71
|
+
const definition = getNodeType(node.type);
|
|
72
|
+
if (!definition) return;
|
|
73
|
+
if (node.when != null) validateCondition(node.when, `${location}.when`, errors);
|
|
74
|
+
if (definition.builtIn && node.when != null) {
|
|
75
|
+
errors.push(`${location}.when cannot conditionally skip a required safety node`);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
if (node.type === 'condition') {
|
|
79
|
+
validateCondition(node.expression, `${location}.expression`, errors);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
if (node.type === 'agent') {
|
|
83
|
+
if (!String(node.role || '').trim()) errors.push(`${location}.role is required`);
|
|
84
|
+
if (!node.output || typeof node.output !== 'object') {
|
|
85
|
+
errors.push(`${location}.output artifact contract is required`);
|
|
86
|
+
} else {
|
|
87
|
+
if (!String(node.output.artifact || '').trim()) errors.push(`${location}.output.artifact is required`);
|
|
88
|
+
if (!String(node.output.schema || '').trim()) errors.push(`${location}.output.schema is required`);
|
|
89
|
+
const schemaPath = String(node.output.schema || '').replace(/\\/g, '/');
|
|
90
|
+
if (
|
|
91
|
+
/^(?:https?:|file:)/i.test(schemaPath) ||
|
|
92
|
+
path.isAbsolute(schemaPath) ||
|
|
93
|
+
schemaPath.split('/').includes('..')
|
|
94
|
+
) {
|
|
95
|
+
errors.push(`${location}.output.schema must be repository-relative`);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (!Number.isSafeInteger(node.context?.maxFiles) || node.context.maxFiles <= 0) {
|
|
99
|
+
errors.push(`${location}.context.maxFiles must be a positive integer`);
|
|
100
|
+
}
|
|
101
|
+
if (!Number.isSafeInteger(node.context?.maxTokens) || node.context.maxTokens <= 0) {
|
|
102
|
+
errors.push(`${location}.context.maxTokens must be a positive integer`);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
if (node.type === 'command') {
|
|
107
|
+
const executable = String(node.command?.executable || '');
|
|
108
|
+
if (!/^[a-zA-Z0-9._-]+$/.test(executable)) {
|
|
109
|
+
errors.push(`${location}.command.executable must be a bare executable name`);
|
|
110
|
+
} else if (FORBIDDEN_COMMANDS.has(executable.toLowerCase())) {
|
|
111
|
+
errors.push(`${location}.command.executable cannot be a shell or interpreter`);
|
|
112
|
+
}
|
|
113
|
+
if (
|
|
114
|
+
!Array.isArray(node.command?.args) ||
|
|
115
|
+
node.command.args.some((arg) => typeof arg !== 'string' || /[\0\r\n]/.test(arg))
|
|
116
|
+
) {
|
|
117
|
+
errors.push(`${location}.command.args must be an array of strings`);
|
|
118
|
+
}
|
|
119
|
+
if (!Number.isSafeInteger(node.timeoutMs) || node.timeoutMs < 1_000 || node.timeoutMs > 30 * 60 * 1_000) {
|
|
120
|
+
errors.push(`${location}.timeoutMs must be between 1000 and 1800000`);
|
|
121
|
+
}
|
|
122
|
+
if (
|
|
123
|
+
!Array.isArray(node.expectedExitCodes) ||
|
|
124
|
+
node.expectedExitCodes.length === 0 ||
|
|
125
|
+
node.expectedExitCodes.some((code) => !Number.isSafeInteger(code) || code < 0 || code > 255)
|
|
126
|
+
) {
|
|
127
|
+
errors.push(`${location}.expectedExitCodes must not be empty`);
|
|
128
|
+
}
|
|
129
|
+
warnings.push(`${node.id}: project commands execute trusted repository scripts`);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (node.type === 'approval' && !String(node.message || '').trim()) {
|
|
133
|
+
errors.push(`${location}.message is required`);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function topologicalOrder(nodes, byId, errors) {
|
|
138
|
+
const indegree = new Map(nodes.map((node) => [node.id, 0]));
|
|
139
|
+
const dependents = new Map(nodes.map((node) => [node.id, []]));
|
|
140
|
+
for (const node of nodes) {
|
|
141
|
+
for (const dependency of node.dependsOn || []) {
|
|
142
|
+
if (!byId.has(dependency)) continue;
|
|
143
|
+
indegree.set(node.id, indegree.get(node.id) + 1);
|
|
144
|
+
dependents.get(dependency).push(node.id);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
const position = new Map(nodes.map((node, index) => [node.id, index]));
|
|
148
|
+
const ready = nodes.filter((node) => indegree.get(node.id) === 0).map((node) => node.id);
|
|
149
|
+
const ordered = [];
|
|
150
|
+
while (ready.length) {
|
|
151
|
+
ready.sort((left, right) => position.get(left) - position.get(right));
|
|
152
|
+
const id = ready.shift();
|
|
153
|
+
ordered.push(id);
|
|
154
|
+
for (const dependent of dependents.get(id)) {
|
|
155
|
+
indegree.set(dependent, indegree.get(dependent) - 1);
|
|
156
|
+
if (indegree.get(dependent) === 0) ready.push(dependent);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
if (ordered.length !== nodes.length) errors.push('recipe graph contains a dependency cycle');
|
|
160
|
+
return ordered;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function dependsTransitively(byId, nodeId, requiredId) {
|
|
164
|
+
const pending = [nodeId];
|
|
165
|
+
const visited = new Set();
|
|
166
|
+
while (pending.length) {
|
|
167
|
+
const current = pending.pop();
|
|
168
|
+
if (current === requiredId) return true;
|
|
169
|
+
if (visited.has(current)) continue;
|
|
170
|
+
visited.add(current);
|
|
171
|
+
pending.push(...(byId.get(current)?.dependsOn || []));
|
|
172
|
+
}
|
|
173
|
+
return false;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
function firstNodeOfType(nodes, type) {
|
|
177
|
+
return nodes.find((node) => node.type === type);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
function validateSafetyBackbone(recipe, mode, byId, errors) {
|
|
181
|
+
const nodes = recipe.nodes || [];
|
|
182
|
+
for (const type of ['goal-contract', 'maker', 'verification', 'devil-advocate', 'judge', 'report', 'delivery']) {
|
|
183
|
+
if (nodes.filter((node) => node.type === type).length > 1) {
|
|
184
|
+
errors.push(`only one ${type} node is allowed`);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
const goal = firstNodeOfType(nodes, 'goal-contract');
|
|
188
|
+
if (!goal) errors.push('a goal-contract node is required');
|
|
189
|
+
|
|
190
|
+
if (mode === RUN_MODES.REPORT_ONLY) {
|
|
191
|
+
const report = firstNodeOfType(nodes, 'report');
|
|
192
|
+
if (!report) errors.push('REPORT_ONLY requires a report node');
|
|
193
|
+
if (nodes.some((node) => getNodeType(node.type)?.mutation)) {
|
|
194
|
+
errors.push('REPORT_ONLY cannot contain mutation nodes');
|
|
195
|
+
}
|
|
196
|
+
if (nodes.some((node) => getNodeType(node.type)?.sideEffect)) {
|
|
197
|
+
errors.push('REPORT_ONLY cannot contain side-effect nodes');
|
|
198
|
+
}
|
|
199
|
+
if (goal && report && !dependsTransitively(byId, report.id, goal.id)) {
|
|
200
|
+
errors.push('report must depend on goal-contract');
|
|
201
|
+
}
|
|
202
|
+
return;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
if (nodes.some((node) => node.type === 'report')) {
|
|
206
|
+
errors.push(`${mode} recipe cannot contain a report terminal`);
|
|
207
|
+
}
|
|
208
|
+
const chainTypes = ['goal-contract', 'maker', 'verification', 'devil-advocate', 'judge', 'delivery'];
|
|
209
|
+
const chain = chainTypes.map((type) => firstNodeOfType(nodes, type));
|
|
210
|
+
chain.forEach((node, index) => {
|
|
211
|
+
if (!node) errors.push(`${chainTypes[index]} node is required for ${mode}`);
|
|
212
|
+
});
|
|
213
|
+
for (let index = 1; index < chain.length; index++) {
|
|
214
|
+
if (chain[index] && chain[index - 1] && !dependsTransitively(byId, chain[index].id, chain[index - 1].id)) {
|
|
215
|
+
errors.push(`${chain[index].type} must depend on ${chain[index - 1].type}`);
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
if (mode === RUN_MODES.ASSISTED) {
|
|
219
|
+
const judge = firstNodeOfType(nodes, 'judge');
|
|
220
|
+
const approval = nodes.find((node) => (
|
|
221
|
+
node.type === 'approval' && (!node.when || (
|
|
222
|
+
node.when.field === 'run.mode' &&
|
|
223
|
+
node.when.operator === 'equals' &&
|
|
224
|
+
node.when.value === RUN_MODES.ASSISTED
|
|
225
|
+
)) && judge && dependsTransitively(byId, node.id, judge.id)
|
|
226
|
+
));
|
|
227
|
+
const delivery = firstNodeOfType(nodes, 'delivery');
|
|
228
|
+
if (!approval) errors.push('ASSISTED requires a human approval node');
|
|
229
|
+
if (delivery && approval && !dependsTransitively(byId, delivery.id, approval.id)) {
|
|
230
|
+
errors.push('delivery must depend on ASSISTED approval');
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
function validateRecipe(recipe, { mode } = {}) {
|
|
236
|
+
const errors = [];
|
|
237
|
+
const warnings = [];
|
|
238
|
+
if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) {
|
|
239
|
+
return { valid: false, errors: ['recipe must be a JSON object'], warnings, order: [] };
|
|
240
|
+
}
|
|
241
|
+
if (recipe.schemaVersion !== 1) errors.push('schemaVersion must be 1');
|
|
242
|
+
if (!RECIPE_ID.test(String(recipe.id || ''))) errors.push('id must match [a-z][a-z0-9-]{0,63}');
|
|
243
|
+
if (!Number.isSafeInteger(recipe.version) || recipe.version <= 0) errors.push('version must be a positive integer');
|
|
244
|
+
if (!String(recipe.description || '').trim()) errors.push('description is required');
|
|
245
|
+
if (!Array.isArray(recipe.compatibleModes) || recipe.compatibleModes.length === 0) {
|
|
246
|
+
errors.push('compatibleModes must not be empty');
|
|
247
|
+
}
|
|
248
|
+
const compatibleModes = [];
|
|
249
|
+
for (const candidate of recipe.compatibleModes || []) {
|
|
250
|
+
try {
|
|
251
|
+
compatibleModes.push(normalizeRunMode(candidate));
|
|
252
|
+
} catch (cause) {
|
|
253
|
+
errors.push(cause.message);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
if (!Array.isArray(recipe.nodes) || recipe.nodes.length === 0) {
|
|
257
|
+
errors.push('nodes must not be empty');
|
|
258
|
+
} else if (recipe.nodes.length > MAX_NODES) {
|
|
259
|
+
errors.push(`nodes exceeds the maximum of ${MAX_NODES}`);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
const nodes = Array.isArray(recipe.nodes) ? recipe.nodes : [];
|
|
263
|
+
const byId = new Map();
|
|
264
|
+
nodes.forEach((node, index) => {
|
|
265
|
+
const location = `nodes[${index}]`;
|
|
266
|
+
if (!node || typeof node !== 'object' || Array.isArray(node)) {
|
|
267
|
+
errors.push(`${location} must be an object`);
|
|
268
|
+
return;
|
|
269
|
+
}
|
|
270
|
+
if (!NODE_ID.test(String(node.id || ''))) errors.push(`${location}.id is invalid`);
|
|
271
|
+
else if (byId.has(node.id)) errors.push(`duplicate node id: ${node.id}`);
|
|
272
|
+
else byId.set(node.id, node);
|
|
273
|
+
if (!Object.hasOwn(NODE_TYPES, node.type)) errors.push(`${location}.type is unknown: ${node.type}`);
|
|
274
|
+
if (node.dependsOn != null && (
|
|
275
|
+
!Array.isArray(node.dependsOn) ||
|
|
276
|
+
node.dependsOn.some((dependency) => typeof dependency !== 'string')
|
|
277
|
+
)) {
|
|
278
|
+
errors.push(`${location}.dependsOn must be an array of node ids`);
|
|
279
|
+
}
|
|
280
|
+
validateNodeConfiguration(node, index, errors, warnings);
|
|
281
|
+
});
|
|
282
|
+
for (const node of nodes) {
|
|
283
|
+
for (const dependency of node.dependsOn || []) {
|
|
284
|
+
if (!byId.has(dependency)) errors.push(`${node.id} depends on unknown node ${dependency}`);
|
|
285
|
+
if (dependency === node.id) errors.push(`${node.id} cannot depend on itself`);
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
const order = topologicalOrder(nodes, byId, errors);
|
|
289
|
+
const terminals = nodes.filter((node) => ['report', 'delivery'].includes(node.type));
|
|
290
|
+
for (const terminal of terminals) {
|
|
291
|
+
if (nodes.some((node) => (node.dependsOn || []).includes(terminal.id))) {
|
|
292
|
+
errors.push(`${terminal.type} must be a terminal node`);
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
for (const node of nodes) {
|
|
296
|
+
if (!terminals.some((terminal) => dependsTransitively(byId, terminal.id, node.id))) {
|
|
297
|
+
errors.push(`${node.id} must lead to a report or delivery terminal`);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
const modesToCheck = mode ? [normalizeRunMode(mode)] : [...new Set(compatibleModes)];
|
|
301
|
+
for (const selectedMode of modesToCheck) {
|
|
302
|
+
if (!compatibleModes.includes(selectedMode)) {
|
|
303
|
+
errors.push(`recipe ${recipe.id || '(unknown)'} is not compatible with ${selectedMode}`);
|
|
304
|
+
continue;
|
|
305
|
+
}
|
|
306
|
+
validateSafetyBackbone(recipe, selectedMode, byId, errors);
|
|
307
|
+
}
|
|
308
|
+
return { valid: errors.length === 0, errors: [...new Set(errors)], warnings: [...new Set(warnings)], order };
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
function compileRecipe(recipe, { mode } = {}) {
|
|
312
|
+
const selectedMode = normalizeRunMode(mode || recipe?.compatibleModes?.[0]);
|
|
313
|
+
const validation = validateRecipe(recipe, { mode: selectedMode });
|
|
314
|
+
if (!validation.valid) {
|
|
315
|
+
throw recipeError(`Recipe ${recipe?.id || '(unknown)'} is invalid`, validation.errors);
|
|
316
|
+
}
|
|
317
|
+
const byId = new Map(recipe.nodes.map((node) => [node.id, node]));
|
|
318
|
+
const compiledNodes = validation.order.map((id, index) => {
|
|
319
|
+
const node = byId.get(id);
|
|
320
|
+
const definition = getNodeType(node.type);
|
|
321
|
+
return {
|
|
322
|
+
...canonicalize(node),
|
|
323
|
+
order: index + 1,
|
|
324
|
+
status: (node.dependsOn || []).length === 0 ? 'READY' : 'BLOCKED',
|
|
325
|
+
capabilities: {
|
|
326
|
+
repositoryMutation: definition.mutation,
|
|
327
|
+
remoteSideEffect: definition.sideEffect,
|
|
328
|
+
modelRequired: definition.modelRequired
|
|
329
|
+
},
|
|
330
|
+
...(definition.legacyGate ? { legacyGate: definition.legacyGate } : {})
|
|
331
|
+
};
|
|
332
|
+
});
|
|
333
|
+
const graphMaterial = {
|
|
334
|
+
schemaVersion: 1,
|
|
335
|
+
compilerVersion: 1,
|
|
336
|
+
recipe: {
|
|
337
|
+
id: recipe.id,
|
|
338
|
+
version: recipe.version,
|
|
339
|
+
sourceHash: sha256(recipe)
|
|
340
|
+
},
|
|
341
|
+
mode: selectedMode,
|
|
342
|
+
nodes: compiledNodes
|
|
343
|
+
};
|
|
344
|
+
return {
|
|
345
|
+
...graphMaterial,
|
|
346
|
+
graphHash: sha256(graphMaterial),
|
|
347
|
+
warnings: validation.warnings
|
|
348
|
+
};
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
function readRecipeFile(filePath) {
|
|
352
|
+
let stat;
|
|
353
|
+
try {
|
|
354
|
+
stat = fs.lstatSync(filePath);
|
|
355
|
+
} catch (cause) {
|
|
356
|
+
if (cause.code === 'ENOENT') return null;
|
|
357
|
+
throw recipeError(`Unable to inspect recipe: ${cause.message}`, [], 'RECIPE_READ_FAILED');
|
|
358
|
+
}
|
|
359
|
+
if (stat.isSymbolicLink() || !stat.isFile()) {
|
|
360
|
+
throw recipeError('Recipe must be a regular file, not a symlink', [], 'UNSAFE_RECIPE_PATH');
|
|
361
|
+
}
|
|
362
|
+
try {
|
|
363
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
364
|
+
} catch (cause) {
|
|
365
|
+
throw recipeError(`Recipe JSON is invalid: ${cause.message}`, [], 'INVALID_RECIPE_JSON');
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function recipePath(directory, id) {
|
|
370
|
+
if (!RECIPE_ID.test(String(id || ''))) throw recipeError(`Invalid recipe id: ${id || '(empty)'}`);
|
|
371
|
+
return path.join(directory, `${id}.json`);
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
function builtinRecipeIds() {
|
|
375
|
+
return fs.readdirSync(BUILTIN_RECIPE_DIR)
|
|
376
|
+
.filter((name) => name.endsWith('.json'))
|
|
377
|
+
.map((name) => name.slice(0, -5))
|
|
378
|
+
.sort();
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
function projectRecipeIds(directory) {
|
|
382
|
+
let stat;
|
|
383
|
+
try {
|
|
384
|
+
stat = fs.lstatSync(directory);
|
|
385
|
+
} catch (cause) {
|
|
386
|
+
if (cause.code === 'ENOENT') return [];
|
|
387
|
+
throw recipeError(`Unable to inspect recipe directory: ${cause.message}`, [], 'RECIPE_READ_FAILED');
|
|
388
|
+
}
|
|
389
|
+
if (stat.isSymbolicLink() || !stat.isDirectory()) {
|
|
390
|
+
throw recipeError('Project recipe directory must be a regular directory, not a symlink', [], 'UNSAFE_RECIPE_PATH');
|
|
391
|
+
}
|
|
392
|
+
return fs.readdirSync(directory)
|
|
393
|
+
.filter((name) => name.endsWith('.json') && RECIPE_ID.test(name.slice(0, -5)))
|
|
394
|
+
.map((name) => name.slice(0, -5))
|
|
395
|
+
.sort();
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
function listRecipes(rootDir) {
|
|
399
|
+
const builtin = builtinRecipeIds();
|
|
400
|
+
const projectDirectory = path.join(rootDir, '.ai-engineering-loop', 'recipes');
|
|
401
|
+
const project = projectRecipeIds(projectDirectory).filter((id) => !builtin.includes(id));
|
|
402
|
+
return [
|
|
403
|
+
...builtin.map((id) => ({ id, source: 'builtin' })),
|
|
404
|
+
...project.map((id) => ({ id, source: 'project' }))
|
|
405
|
+
];
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
function loadRecipe(rootDir, id) {
|
|
409
|
+
const builtins = builtinRecipeIds();
|
|
410
|
+
const source = builtins.includes(id) ? 'builtin' : 'project';
|
|
411
|
+
const directory = source === 'builtin'
|
|
412
|
+
? BUILTIN_RECIPE_DIR
|
|
413
|
+
: path.join(rootDir, '.ai-engineering-loop', 'recipes');
|
|
414
|
+
if (source === 'project') projectRecipeIds(directory);
|
|
415
|
+
const recipe = readRecipeFile(recipePath(directory, id));
|
|
416
|
+
if (!recipe) throw recipeError(`Recipe not found: ${id}`, [], 'RECIPE_NOT_FOUND');
|
|
417
|
+
if (recipe.id !== id) throw recipeError(`Recipe id must match file name: ${id}`, ['id mismatch']);
|
|
418
|
+
return { recipe, source, path: recipePath(directory, id) };
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
function explainPlan(plan) {
|
|
422
|
+
const lines = [
|
|
423
|
+
`Workflow: ${plan.recipe.id} v${plan.recipe.version}`,
|
|
424
|
+
`Mode: ${plan.mode}`,
|
|
425
|
+
`Graph: ${plan.graphHash}`,
|
|
426
|
+
'',
|
|
427
|
+
'Execution plan:'
|
|
428
|
+
];
|
|
429
|
+
for (const node of plan.nodes) {
|
|
430
|
+
const definition = getNodeType(node.type);
|
|
431
|
+
const conditions = node.when ? ` when ${node.when.field} ${node.when.operator} ${JSON.stringify(node.when.value)}` : '';
|
|
432
|
+
lines.push(`${node.order}. ${definition.label} [${node.id}]${conditions}`);
|
|
433
|
+
}
|
|
434
|
+
lines.push('', 'Capabilities:');
|
|
435
|
+
lines.push(`- Model-backed nodes: ${plan.nodes.filter((node) => node.capabilities.modelRequired).length}`);
|
|
436
|
+
lines.push(`- Repository mutation nodes: ${plan.nodes.filter((node) => node.capabilities.repositoryMutation).length}`);
|
|
437
|
+
lines.push(`- Remote side-effect nodes: ${plan.nodes.filter((node) => node.capabilities.remoteSideEffect).length}`);
|
|
438
|
+
if (plan.warnings.length) {
|
|
439
|
+
lines.push('', 'Warnings:', ...plan.warnings.map((warning) => `- ${warning}`));
|
|
440
|
+
}
|
|
441
|
+
return lines.join('\n');
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
function mermaidPlan(plan) {
|
|
445
|
+
const lines = ['flowchart TD'];
|
|
446
|
+
for (const node of plan.nodes) {
|
|
447
|
+
const label = `${node.order}. ${getNodeType(node.type).label}`.replace(/"/g, '\\"');
|
|
448
|
+
lines.push(` ${node.id.replace(/-/g, '_')}["${label}"]`);
|
|
449
|
+
}
|
|
450
|
+
for (const node of plan.nodes) {
|
|
451
|
+
for (const dependency of node.dependsOn || []) {
|
|
452
|
+
lines.push(` ${dependency.replace(/-/g, '_')} --> ${node.id.replace(/-/g, '_')}`);
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
return lines.join('\n');
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
function simulatePlan(plan) {
|
|
459
|
+
return {
|
|
460
|
+
schemaVersion: 1,
|
|
461
|
+
recipe: plan.recipe,
|
|
462
|
+
mode: plan.mode,
|
|
463
|
+
graphHash: plan.graphHash,
|
|
464
|
+
executable: true,
|
|
465
|
+
executionPerformed: false,
|
|
466
|
+
nodeCount: plan.nodes.length,
|
|
467
|
+
readyNodes: plan.nodes.filter((node) => node.status === 'READY').map((node) => node.id),
|
|
468
|
+
terminalNodes: plan.nodes
|
|
469
|
+
.filter((candidate) => !plan.nodes.some((node) => (node.dependsOn || []).includes(candidate.id)))
|
|
470
|
+
.map((node) => node.id),
|
|
471
|
+
capabilities: {
|
|
472
|
+
modelCalls: plan.nodes.filter((node) => node.capabilities.modelRequired).length,
|
|
473
|
+
repositoryMutations: plan.nodes.filter((node) => node.capabilities.repositoryMutation).length,
|
|
474
|
+
remoteSideEffects: plan.nodes.filter((node) => node.capabilities.remoteSideEffect).length
|
|
475
|
+
},
|
|
476
|
+
warnings: plan.warnings
|
|
477
|
+
};
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
module.exports = {
|
|
481
|
+
RECIPE_ID,
|
|
482
|
+
NODE_ID,
|
|
483
|
+
MAX_NODES,
|
|
484
|
+
BUILTIN_RECIPE_DIR,
|
|
485
|
+
canonicalize,
|
|
486
|
+
canonicalJson,
|
|
487
|
+
sha256,
|
|
488
|
+
validateRecipe,
|
|
489
|
+
compileRecipe,
|
|
490
|
+
listRecipes,
|
|
491
|
+
loadRecipe,
|
|
492
|
+
explainPlan,
|
|
493
|
+
mermaidPlan,
|
|
494
|
+
simulatePlan
|
|
495
|
+
};
|
package/lib/run-state.js
CHANGED
|
@@ -106,6 +106,34 @@ function currentRunPath(rootDir) {
|
|
|
106
106
|
return path.join(runsDir(rootDir), 'current.json');
|
|
107
107
|
}
|
|
108
108
|
|
|
109
|
+
function writeWorkflowBundle(rootDir, runId, workflow) {
|
|
110
|
+
if (!workflow) return null;
|
|
111
|
+
const directory = path.join(runsDir(rootDir), runId);
|
|
112
|
+
const { plan, state, events } = workflow;
|
|
113
|
+
if (
|
|
114
|
+
!plan?.graphHash ||
|
|
115
|
+
state?.graphHash !== plan.graphHash ||
|
|
116
|
+
!Array.isArray(events) ||
|
|
117
|
+
events.length === 0
|
|
118
|
+
) {
|
|
119
|
+
const err = new Error('Workflow bundle is invalid');
|
|
120
|
+
err.code = 'INVALID_WORKFLOW_BUNDLE';
|
|
121
|
+
throw err;
|
|
122
|
+
}
|
|
123
|
+
atomicWriteJson(path.join(directory, 'plan.json'), plan);
|
|
124
|
+
atomicWriteJson(path.join(directory, 'workflow-state.json'), state);
|
|
125
|
+
atomicWritePrivateFile(
|
|
126
|
+
path.join(directory, 'events.jsonl'),
|
|
127
|
+
`${events.map((event) => JSON.stringify(event)).join('\n')}\n`
|
|
128
|
+
);
|
|
129
|
+
return {
|
|
130
|
+
recipeId: plan.recipe.id,
|
|
131
|
+
recipeVersion: plan.recipe.version,
|
|
132
|
+
sourceHash: plan.recipe.sourceHash,
|
|
133
|
+
graphHash: plan.graphHash
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
|
|
109
137
|
function loadRun(rootDir, runId) {
|
|
110
138
|
const state = readJson(runStatePath(rootDir, runId), `run ${runId}`);
|
|
111
139
|
if (
|
|
@@ -137,7 +165,10 @@ function normalizeRunMode(mode) {
|
|
|
137
165
|
return RUN_MODES[normalized];
|
|
138
166
|
}
|
|
139
167
|
|
|
140
|
-
function createRun(
|
|
168
|
+
function createRun(
|
|
169
|
+
rootDir,
|
|
170
|
+
{ task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date(), workflow = null } = {}
|
|
171
|
+
) {
|
|
141
172
|
assertRunId(runId);
|
|
142
173
|
const statePath = runStatePath(rootDir, runId);
|
|
143
174
|
if (fs.existsSync(statePath)) {
|
|
@@ -147,6 +178,7 @@ function createRun(rootDir, { task = '', runId = newRunId(), mode = RUN_MODES.AS
|
|
|
147
178
|
}
|
|
148
179
|
|
|
149
180
|
const timestamp = now.toISOString();
|
|
181
|
+
const workflowMetadata = writeWorkflowBundle(rootDir, runId, workflow);
|
|
150
182
|
const state = {
|
|
151
183
|
schemaVersion: 1,
|
|
152
184
|
runId,
|
|
@@ -158,6 +190,7 @@ function createRun(rootDir, { task = '', runId = newRunId(), mode = RUN_MODES.AS
|
|
|
158
190
|
createdAt: timestamp,
|
|
159
191
|
updatedAt: timestamp,
|
|
160
192
|
artifacts: {},
|
|
193
|
+
...(workflowMetadata ? { workflow: workflowMetadata } : {}),
|
|
161
194
|
history: [
|
|
162
195
|
{
|
|
163
196
|
from: null,
|
|
@@ -173,7 +206,10 @@ function createRun(rootDir, { task = '', runId = newRunId(), mode = RUN_MODES.AS
|
|
|
173
206
|
return state;
|
|
174
207
|
}
|
|
175
208
|
|
|
176
|
-
function createOrResumeRun(
|
|
209
|
+
function createOrResumeRun(
|
|
210
|
+
rootDir,
|
|
211
|
+
{ task = '', runId, mode = null, forceNew = false, now = new Date(), workflow = null } = {}
|
|
212
|
+
) {
|
|
177
213
|
const current = getCurrentRun(rootDir);
|
|
178
214
|
const requestedTask = String(task || '').trim();
|
|
179
215
|
if (current && !TERMINAL_STATES.has(current.state) && !forceNew) {
|
|
@@ -189,10 +225,21 @@ function createOrResumeRun(rootDir, { task = '', mode = null, forceNew = false,
|
|
|
189
225
|
err.code = 'RUN_MODE_MISMATCH';
|
|
190
226
|
throw err;
|
|
191
227
|
}
|
|
228
|
+
if (workflow && current.workflow?.graphHash !== workflow.plan.graphHash) {
|
|
229
|
+
const err = new Error(`Run ${current.runId} is bound to a different workflow graph.`);
|
|
230
|
+
err.code = 'RUN_WORKFLOW_MISMATCH';
|
|
231
|
+
throw err;
|
|
232
|
+
}
|
|
192
233
|
return { run: current, resumed: true };
|
|
193
234
|
}
|
|
194
235
|
return {
|
|
195
|
-
run: createRun(rootDir, {
|
|
236
|
+
run: createRun(rootDir, {
|
|
237
|
+
task: requestedTask,
|
|
238
|
+
...(runId ? { runId } : {}),
|
|
239
|
+
mode: mode || RUN_MODES.ASSISTED,
|
|
240
|
+
now,
|
|
241
|
+
workflow
|
|
242
|
+
}),
|
|
196
243
|
resumed: false
|
|
197
244
|
};
|
|
198
245
|
}
|