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/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(rootDir, { task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date() } = {}) {
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(rootDir, { task = '', mode = null, forceNew = false, now = new Date() } = {}) {
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, { task: requestedTask, mode: mode || RUN_MODES.ASSISTED, now }),
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
  }
@@ -8,6 +8,7 @@ const PRIVATE_RUNTIME_PATTERNS = Object.freeze([
8
8
  'usage/',
9
9
  'worktrees/',
10
10
  'locks/',
11
+ 'recipes/.history/',
11
12
  'tasks/current.diff',
12
13
  'tasks/*.log'
13
14
  ]);