ai-engineering-loop 1.1.0 → 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/.agents/workflows/ai-engineering-loop.md +5 -5
- package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
- package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
- package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
- package/README.md +56 -6
- package/README.npm.md +9 -1
- package/SECURITY.md +8 -2
- package/agents/judge.md +5 -5
- package/agents/maker.md +6 -6
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +521 -16
- package/core/configuration-precedence.md +4 -4
- package/core/context-impact-assessment.md +1 -1
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/definition-of-done.md +3 -3
- package/core/escalation-policy.md +2 -2
- package/core/goal-contract.md +2 -2
- package/core/iteration-policy.md +4 -4
- package/core/project-initialization.md +2 -2
- package/core/runtime-safety.md +75 -0
- package/core/verification-loop.md +1 -1
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +258 -0
- package/lib/doctor.js +38 -2
- package/lib/gates.js +55 -1
- package/lib/node-registry.js +155 -0
- package/lib/package-audit.js +78 -0
- package/lib/recipe-builder.js +200 -0
- package/lib/recipe.js +495 -0
- package/lib/run-state.js +94 -8
- package/lib/runtime-files.js +54 -0
- package/lib/runtime-policy.js +118 -0
- package/lib/safe-context.js +3 -0
- package/lib/sandbox.js +305 -0
- package/lib/workflow-runtime.js +692 -0
- package/package.json +7 -3
- package/policies/finding-policy.md +2 -2
- package/policies/no-progress-policy.md +2 -2
- package/profiles/README.md +5 -5
- package/profiles/backend-api.md +1 -1
- package/profiles/library.md +1 -1
- package/profiles/mobile-app.md +1 -1
- package/profiles/monorepo.md +1 -1
- package/profiles/web-app.md +1 -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/delivery.schema.json +2 -1
- package/schemas/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/report.schema.json +17 -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
|
@@ -8,6 +8,7 @@ const { execFileSync } = require('child_process');
|
|
|
8
8
|
const RUN_STATES = Object.freeze({
|
|
9
9
|
STARTED: 'STARTED',
|
|
10
10
|
GOAL_FROZEN: 'GOAL_FROZEN',
|
|
11
|
+
REPORTED: 'REPORTED',
|
|
11
12
|
MAKER_COMPLETE: 'MAKER_COMPLETE',
|
|
12
13
|
VERIFIED: 'VERIFIED',
|
|
13
14
|
REVIEWED: 'REVIEWED',
|
|
@@ -16,9 +17,16 @@ const RUN_STATES = Object.freeze({
|
|
|
16
17
|
ESCALATED: 'ESCALATED'
|
|
17
18
|
});
|
|
18
19
|
|
|
20
|
+
const RUN_MODES = Object.freeze({
|
|
21
|
+
REPORT_ONLY: 'REPORT_ONLY',
|
|
22
|
+
ASSISTED: 'ASSISTED',
|
|
23
|
+
UNATTENDED: 'UNATTENDED'
|
|
24
|
+
});
|
|
25
|
+
|
|
19
26
|
const ALLOWED_TRANSITIONS = Object.freeze({
|
|
20
27
|
STARTED: ['GOAL_FROZEN'],
|
|
21
|
-
GOAL_FROZEN: ['MAKER_COMPLETE'],
|
|
28
|
+
GOAL_FROZEN: ['REPORTED', 'MAKER_COMPLETE'],
|
|
29
|
+
REPORTED: [],
|
|
22
30
|
MAKER_COMPLETE: ['VERIFIED'],
|
|
23
31
|
VERIFIED: ['REVIEWED'],
|
|
24
32
|
REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED'],
|
|
@@ -27,7 +35,7 @@ const ALLOWED_TRANSITIONS = Object.freeze({
|
|
|
27
35
|
ESCALATED: []
|
|
28
36
|
});
|
|
29
37
|
|
|
30
|
-
const TERMINAL_STATES = new Set([RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
|
|
38
|
+
const TERMINAL_STATES = new Set([RUN_STATES.REPORTED, RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
|
|
31
39
|
|
|
32
40
|
function runsDir(rootDir) {
|
|
33
41
|
return path.join(rootDir, '.ai-engineering-loop', 'runs');
|
|
@@ -42,11 +50,11 @@ function assertRunId(runId) {
|
|
|
42
50
|
return runId;
|
|
43
51
|
}
|
|
44
52
|
|
|
45
|
-
function
|
|
53
|
+
function atomicWritePrivateFile(filePath, content) {
|
|
46
54
|
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
47
55
|
const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
|
|
48
56
|
try {
|
|
49
|
-
fs.writeFileSync(temporary,
|
|
57
|
+
fs.writeFileSync(temporary, content, { mode: 0o600 });
|
|
50
58
|
fs.renameSync(temporary, filePath);
|
|
51
59
|
fs.chmodSync(filePath, 0o600);
|
|
52
60
|
} finally {
|
|
@@ -58,6 +66,10 @@ function atomicWriteJson(filePath, value) {
|
|
|
58
66
|
}
|
|
59
67
|
}
|
|
60
68
|
|
|
69
|
+
function atomicWriteJson(filePath, value) {
|
|
70
|
+
atomicWritePrivateFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
|
|
71
|
+
}
|
|
72
|
+
|
|
61
73
|
function readJson(filePath, label) {
|
|
62
74
|
try {
|
|
63
75
|
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
@@ -94,9 +106,41 @@ function currentRunPath(rootDir) {
|
|
|
94
106
|
return path.join(runsDir(rootDir), 'current.json');
|
|
95
107
|
}
|
|
96
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
|
+
|
|
97
137
|
function loadRun(rootDir, runId) {
|
|
98
138
|
const state = readJson(runStatePath(rootDir, runId), `run ${runId}`);
|
|
99
|
-
if (
|
|
139
|
+
if (
|
|
140
|
+
state.runId !== runId ||
|
|
141
|
+
!RUN_STATES[state.state] ||
|
|
142
|
+
(state.mode != null && !Object.values(RUN_MODES).includes(state.mode))
|
|
143
|
+
) {
|
|
100
144
|
const err = new Error(`Run ${runId} has an invalid state document`);
|
|
101
145
|
err.code = 'INVALID_RUN_STATE';
|
|
102
146
|
throw err;
|
|
@@ -111,7 +155,20 @@ function getCurrentRun(rootDir) {
|
|
|
111
155
|
return loadRun(rootDir, assertRunId(runId));
|
|
112
156
|
}
|
|
113
157
|
|
|
114
|
-
function
|
|
158
|
+
function normalizeRunMode(mode) {
|
|
159
|
+
const normalized = String(mode || RUN_MODES.ASSISTED).trim().replace(/-/g, '_').toUpperCase();
|
|
160
|
+
if (!Object.hasOwn(RUN_MODES, normalized)) {
|
|
161
|
+
const err = new Error(`Invalid run mode: ${mode}`);
|
|
162
|
+
err.code = 'INVALID_RUN_MODE';
|
|
163
|
+
throw err;
|
|
164
|
+
}
|
|
165
|
+
return RUN_MODES[normalized];
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function createRun(
|
|
169
|
+
rootDir,
|
|
170
|
+
{ task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date(), workflow = null } = {}
|
|
171
|
+
) {
|
|
115
172
|
assertRunId(runId);
|
|
116
173
|
const statePath = runStatePath(rootDir, runId);
|
|
117
174
|
if (fs.existsSync(statePath)) {
|
|
@@ -121,16 +178,19 @@ function createRun(rootDir, { task = '', runId = newRunId(), now = new Date() }
|
|
|
121
178
|
}
|
|
122
179
|
|
|
123
180
|
const timestamp = now.toISOString();
|
|
181
|
+
const workflowMetadata = writeWorkflowBundle(rootDir, runId, workflow);
|
|
124
182
|
const state = {
|
|
125
183
|
schemaVersion: 1,
|
|
126
184
|
runId,
|
|
127
185
|
state: RUN_STATES.STARTED,
|
|
186
|
+
mode: normalizeRunMode(mode),
|
|
128
187
|
iteration: 1,
|
|
129
188
|
task: String(task || '').trim(),
|
|
130
189
|
startedRevision: getGitRevision(rootDir),
|
|
131
190
|
createdAt: timestamp,
|
|
132
191
|
updatedAt: timestamp,
|
|
133
192
|
artifacts: {},
|
|
193
|
+
...(workflowMetadata ? { workflow: workflowMetadata } : {}),
|
|
134
194
|
history: [
|
|
135
195
|
{
|
|
136
196
|
from: null,
|
|
@@ -146,7 +206,10 @@ function createRun(rootDir, { task = '', runId = newRunId(), now = new Date() }
|
|
|
146
206
|
return state;
|
|
147
207
|
}
|
|
148
208
|
|
|
149
|
-
function createOrResumeRun(
|
|
209
|
+
function createOrResumeRun(
|
|
210
|
+
rootDir,
|
|
211
|
+
{ task = '', runId, mode = null, forceNew = false, now = new Date(), workflow = null } = {}
|
|
212
|
+
) {
|
|
150
213
|
const current = getCurrentRun(rootDir);
|
|
151
214
|
const requestedTask = String(task || '').trim();
|
|
152
215
|
if (current && !TERMINAL_STATES.has(current.state) && !forceNew) {
|
|
@@ -157,9 +220,28 @@ function createOrResumeRun(rootDir, { task = '', forceNew = false, now = new Dat
|
|
|
157
220
|
err.code = 'ACTIVE_RUN';
|
|
158
221
|
throw err;
|
|
159
222
|
}
|
|
223
|
+
if (mode && normalizeRunMode(mode) !== (current.mode || RUN_MODES.ASSISTED)) {
|
|
224
|
+
const err = new Error(`Run ${current.runId} is already ${(current.mode || RUN_MODES.ASSISTED)}; mode cannot change during a run.`);
|
|
225
|
+
err.code = 'RUN_MODE_MISMATCH';
|
|
226
|
+
throw err;
|
|
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
|
+
}
|
|
160
233
|
return { run: current, resumed: true };
|
|
161
234
|
}
|
|
162
|
-
return {
|
|
235
|
+
return {
|
|
236
|
+
run: createRun(rootDir, {
|
|
237
|
+
task: requestedTask,
|
|
238
|
+
...(runId ? { runId } : {}),
|
|
239
|
+
mode: mode || RUN_MODES.ASSISTED,
|
|
240
|
+
now,
|
|
241
|
+
workflow
|
|
242
|
+
}),
|
|
243
|
+
resumed: false
|
|
244
|
+
};
|
|
163
245
|
}
|
|
164
246
|
|
|
165
247
|
function transitionRun(
|
|
@@ -205,14 +287,18 @@ function transitionRun(
|
|
|
205
287
|
|
|
206
288
|
module.exports = {
|
|
207
289
|
RUN_STATES,
|
|
290
|
+
RUN_MODES,
|
|
208
291
|
ALLOWED_TRANSITIONS,
|
|
209
292
|
TERMINAL_STATES,
|
|
210
293
|
runsDir,
|
|
294
|
+
assertRunId,
|
|
211
295
|
runStatePath,
|
|
212
296
|
currentRunPath,
|
|
297
|
+
atomicWritePrivateFile,
|
|
213
298
|
atomicWriteJson,
|
|
214
299
|
getGitRevision,
|
|
215
300
|
newRunId,
|
|
301
|
+
normalizeRunMode,
|
|
216
302
|
loadRun,
|
|
217
303
|
getCurrentRun,
|
|
218
304
|
createRun,
|