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.
Files changed (57) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +5 -5
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
  5. package/README.md +56 -6
  6. package/README.npm.md +9 -1
  7. package/SECURITY.md +8 -2
  8. package/agents/judge.md +5 -5
  9. package/agents/maker.md +6 -6
  10. package/agents/recipe-builder.md +28 -0
  11. package/bin/ai-engineering-loop.js +521 -16
  12. package/core/configuration-precedence.md +4 -4
  13. package/core/context-impact-assessment.md +1 -1
  14. package/core/controlled-workflow-runtime.md +77 -0
  15. package/core/definition-of-done.md +3 -3
  16. package/core/escalation-policy.md +2 -2
  17. package/core/goal-contract.md +2 -2
  18. package/core/iteration-policy.md +4 -4
  19. package/core/project-initialization.md +2 -2
  20. package/core/runtime-safety.md +75 -0
  21. package/core/verification-loop.md +1 -1
  22. package/core/workflow-recipes.md +140 -0
  23. package/lib/budget.js +258 -0
  24. package/lib/doctor.js +38 -2
  25. package/lib/gates.js +55 -1
  26. package/lib/node-registry.js +155 -0
  27. package/lib/package-audit.js +78 -0
  28. package/lib/recipe-builder.js +200 -0
  29. package/lib/recipe.js +495 -0
  30. package/lib/run-state.js +94 -8
  31. package/lib/runtime-files.js +54 -0
  32. package/lib/runtime-policy.js +118 -0
  33. package/lib/safe-context.js +3 -0
  34. package/lib/sandbox.js +305 -0
  35. package/lib/workflow-runtime.js +692 -0
  36. package/package.json +7 -3
  37. package/policies/finding-policy.md +2 -2
  38. package/policies/no-progress-policy.md +2 -2
  39. package/profiles/README.md +5 -5
  40. package/profiles/backend-api.md +1 -1
  41. package/profiles/library.md +1 -1
  42. package/profiles/mobile-app.md +1 -1
  43. package/profiles/monorepo.md +1 -1
  44. package/profiles/web-app.md +1 -1
  45. package/recipes/audit.json +32 -0
  46. package/recipes/bugfix.json +63 -0
  47. package/recipes/default.json +49 -0
  48. package/recipes/docs-light.json +63 -0
  49. package/recipes/high-risk.json +69 -0
  50. package/recipes/refactor.json +63 -0
  51. package/schemas/compiled-plan.schema.json +19 -0
  52. package/schemas/delivery.schema.json +2 -1
  53. package/schemas/node-definition.schema.json +33 -0
  54. package/schemas/recipe.schema.json +26 -0
  55. package/schemas/report.schema.json +17 -0
  56. package/schemas/workflow-event.schema.json +28 -0
  57. 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 atomicWriteJson(filePath, value) {
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, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
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 (state.runId !== runId || !RUN_STATES[state.state]) {
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 createRun(rootDir, { task = '', runId = newRunId(), now = new Date() } = {}) {
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(rootDir, { task = '', forceNew = false, now = new Date() } = {}) {
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 { run: createRun(rootDir, { task: requestedTask, now }), resumed: false };
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,