ai-engineering-loop 1.7.0 → 1.9.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.
@@ -5,6 +5,11 @@ const path = require('path');
5
5
  const crypto = require('crypto');
6
6
  const { NODE_TYPES } = require('./node-registry.js');
7
7
  const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
+ const {
9
+ mergeGraphs,
10
+ migrateLegacyRecipe,
11
+ planGraphMerge
12
+ } = require('./recipe-graph.js');
8
13
  const {
9
14
  RECIPE_ID,
10
15
  canonicalJson,
@@ -66,6 +71,25 @@ function validateCandidate(recipe) {
66
71
  return result;
67
72
  }
68
73
 
74
+ function planRecipeImport(existingRecipe, importedRecipe, operation) {
75
+ if (!['replace', 'merge', 'cancel'].includes(operation)) {
76
+ throw builderError('Import operation must be replace, merge, or cancel', 'INVALID_IMPORT_OPERATION');
77
+ }
78
+ validateCandidate(existingRecipe);
79
+ validateCandidate(importedRecipe);
80
+ if (operation !== 'merge') return { operation, nodeIdMap: {}, edgeIdMap: {} };
81
+ return { operation, ...planGraphMerge(existingRecipe, importedRecipe) };
82
+ }
83
+
84
+ function applyRecipeImport(existingRecipe, importedRecipe, plan) {
85
+ if (!plan || !['replace', 'merge', 'cancel'].includes(plan.operation)) {
86
+ throw builderError('A valid import preview is required', 'INVALID_IMPORT_PLAN');
87
+ }
88
+ if (plan.operation === 'cancel') return existingRecipe;
89
+ if (plan.operation === 'replace') return migrateLegacyRecipe(importedRecipe);
90
+ return mergeGraphs(existingRecipe, importedRecipe, plan);
91
+ }
92
+
69
93
  function cloneRecipe(rootDir, sourceId, targetId, { description } = {}) {
70
94
  assertProjectId(rootDir, targetId);
71
95
  const source = loadRecipe(rootDir, sourceId).recipe;
@@ -107,7 +131,7 @@ function readCandidate(rootDir, candidatePath) {
107
131
  }
108
132
 
109
133
  function installRecipe(rootDir, candidatePath, { replace = false } = {}) {
110
- const candidate = readCandidate(rootDir, candidatePath);
134
+ const candidate = migrateLegacyRecipe(readCandidate(rootDir, candidatePath));
111
135
  assertProjectId(rootDir, candidate.id);
112
136
  validateCandidate(candidate);
113
137
  ensurePrivateRuntimeIgnores(rootDir);
@@ -193,8 +217,10 @@ function diffRecipes(rootDir, leftId, rightId) {
193
217
  }
194
218
 
195
219
  module.exports = {
220
+ applyRecipeImport,
196
221
  cloneRecipe,
197
222
  installRecipe,
223
+ planRecipeImport,
198
224
  recipeCatalog,
199
225
  inspectRecipe,
200
226
  diffRecipes
@@ -0,0 +1,111 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+
5
+ const EDGE_ID = /^[a-z][a-z0-9-]{0,63}$/;
6
+ const MAX_EDGES = 256;
7
+
8
+ function clone(value) {
9
+ return JSON.parse(JSON.stringify(value));
10
+ }
11
+
12
+ function stableEdgeId(from, to) {
13
+ const digest = crypto.createHash('sha256').update(`${from}\0${to}`).digest('hex').slice(0, 16);
14
+ return `edge-${digest}`;
15
+ }
16
+
17
+ function migrateLegacyRecipe(recipe) {
18
+ const migrated = clone(recipe);
19
+ if (!migrated || typeof migrated !== 'object' || Array.isArray(migrated)) return migrated;
20
+ if (!Array.isArray(migrated.edges)) {
21
+ migrated.edges = [];
22
+ for (const node of Array.isArray(migrated.nodes) ? migrated.nodes : []) {
23
+ for (const dependency of Array.isArray(node?.dependsOn) ? node.dependsOn : []) {
24
+ migrated.edges.push({ id: stableEdgeId(dependency, node.id), from: dependency, to: node.id });
25
+ }
26
+ }
27
+ }
28
+ for (const node of Array.isArray(migrated.nodes) ? migrated.nodes : []) {
29
+ if (node && typeof node === 'object') delete node.dependsOn;
30
+ }
31
+ return migrated;
32
+ }
33
+
34
+ function withDependencies(recipe) {
35
+ const projected = migrateLegacyRecipe(recipe);
36
+ const byId = new Map((projected.nodes || []).map((node) => [node.id, node]));
37
+ for (const node of projected.nodes || []) node.dependsOn = [];
38
+ for (const edge of projected.edges || []) {
39
+ if (byId.has(edge?.to)) byId.get(edge.to).dependsOn.push(edge.from);
40
+ }
41
+ return projected;
42
+ }
43
+
44
+ function uniqueId(preferred, occupied) {
45
+ if (!occupied.has(preferred)) {
46
+ occupied.add(preferred);
47
+ return preferred;
48
+ }
49
+ for (let suffix = 2; ; suffix++) {
50
+ const ending = `-${suffix}`;
51
+ const candidate = `${preferred.slice(0, 64 - ending.length)}${ending}`;
52
+ if (!occupied.has(candidate)) {
53
+ occupied.add(candidate);
54
+ return candidate;
55
+ }
56
+ }
57
+ }
58
+
59
+ function planGraphMerge(existingRecipe, importedRecipe) {
60
+ const existing = migrateLegacyRecipe(existingRecipe);
61
+ const imported = migrateLegacyRecipe(importedRecipe);
62
+ const nodeIds = new Set((existing.nodes || []).map((node) => node.id));
63
+ const edgeIds = new Set((existing.edges || []).map((edge) => edge.id));
64
+ const loopGroupIds = new Set((existing.loopGroups || []).map((group) => group.id));
65
+ const nodeIdMap = {};
66
+ const edgeIdMap = {};
67
+ const loopGroupIdMap = {};
68
+ for (const node of imported.nodes || []) nodeIdMap[node.id] = uniqueId(node.id, nodeIds);
69
+ for (const edge of imported.edges || []) edgeIdMap[edge.id] = uniqueId(edge.id, edgeIds);
70
+ for (const group of imported.loopGroups || []) {
71
+ loopGroupIdMap[group.id] = uniqueId(group.id, loopGroupIds);
72
+ }
73
+ return { nodeIdMap, edgeIdMap, loopGroupIdMap };
74
+ }
75
+
76
+ function mergeGraphs(existingRecipe, importedRecipe, plan) {
77
+ const existing = migrateLegacyRecipe(existingRecipe);
78
+ const imported = migrateLegacyRecipe(importedRecipe);
79
+ const nodes = imported.nodes.map((node) => ({ ...node, id: plan.nodeIdMap[node.id] }));
80
+ const edges = imported.edges.map((edge) => ({
81
+ ...edge,
82
+ id: plan.edgeIdMap[edge.id],
83
+ from: plan.nodeIdMap[edge.from],
84
+ to: plan.nodeIdMap[edge.to]
85
+ }));
86
+ const loopGroups = (imported.loopGroups || []).map((group) => ({
87
+ ...group,
88
+ id: plan.loopGroupIdMap[group.id],
89
+ nodeIds: group.nodeIds.map((nodeId) => plan.nodeIdMap[nodeId]),
90
+ entryNodeId: plan.nodeIdMap[group.entryNodeId],
91
+ decisionNodeId: plan.nodeIdMap[group.decisionNodeId],
92
+ repeatTargetId: plan.nodeIdMap[group.repeatTargetId],
93
+ exitTargetId: plan.nodeIdMap[group.exitTargetId]
94
+ }));
95
+ return {
96
+ ...existing,
97
+ nodes: [...existing.nodes, ...nodes],
98
+ edges: [...existing.edges, ...edges],
99
+ loopGroups: [...(existing.loopGroups || []), ...loopGroups]
100
+ };
101
+ }
102
+
103
+ module.exports = {
104
+ EDGE_ID,
105
+ MAX_EDGES,
106
+ mergeGraphs,
107
+ migrateLegacyRecipe,
108
+ planGraphMerge,
109
+ stableEdgeId,
110
+ withDependencies
111
+ };
package/lib/recipe.js CHANGED
@@ -11,6 +11,13 @@ const {
11
11
  FORBIDDEN_COMMANDS,
12
12
  getNodeType
13
13
  } = require('./node-registry.js');
14
+ const {
15
+ EDGE_ID,
16
+ MAX_EDGES,
17
+ migrateLegacyRecipe,
18
+ withDependencies
19
+ } = require('./recipe-graph.js');
20
+ const { validateLoopGroups } = require('./loop-groups.js');
14
21
 
15
22
  const RECIPE_ID = /^[a-z][a-z0-9-]{0,63}$/;
16
23
  const NODE_ID = /^[a-z][a-z0-9-]{0,63}$/;
@@ -66,6 +73,33 @@ function validateCondition(condition, location, errors) {
66
73
  }
67
74
  }
68
75
 
76
+ function validateRepositorySchemaPath(value, location, errors) {
77
+ if (!String(value || '').trim()) {
78
+ errors.push(`${location} is required`);
79
+ return;
80
+ }
81
+ const schemaPath = String(value).replace(/\\/g, '/');
82
+ if (
83
+ /^(?:https?:|file:)/i.test(schemaPath) ||
84
+ path.isAbsolute(schemaPath) ||
85
+ schemaPath.split('/').includes('..')
86
+ ) {
87
+ errors.push(`${location} must be repository-relative`);
88
+ }
89
+ }
90
+
91
+ function forbiddenAuthorityPaths(value, location, result = []) {
92
+ if (!value || typeof value !== 'object') return result;
93
+ for (const [key, child] of Object.entries(value)) {
94
+ const childLocation = `${location}.${key}`;
95
+ if (/^(?:command|shell|secret|secretValue|environment|filesystem|network)$/i.test(key)) {
96
+ result.push(childLocation);
97
+ }
98
+ forbiddenAuthorityPaths(child, childLocation, result);
99
+ }
100
+ return result;
101
+ }
102
+
69
103
  function validateNodeConfiguration(node, index, errors, warnings) {
70
104
  const location = `nodes[${index}]`;
71
105
  const definition = getNodeType(node.type);
@@ -79,7 +113,66 @@ function validateNodeConfiguration(node, index, errors, warnings) {
79
113
  validateCondition(node.expression, `${location}.expression`, errors);
80
114
  }
81
115
 
82
- if (node.type === 'agent') {
116
+ if (node.type === 'agent' && node.prompt != null) {
117
+ const allowedCapabilities = new Set([
118
+ 'repository-read',
119
+ 'repository-write',
120
+ 'artifact-read',
121
+ 'artifact-write',
122
+ 'mcp-invoke',
123
+ 'network-declared'
124
+ ]);
125
+ if (!String(node.displayName || '').trim() || String(node.displayName).length > 120) {
126
+ errors.push(`${location}.displayName must be between 1 and 120 characters`);
127
+ }
128
+ if (!String(node.prompt || '').trim() || String(node.prompt).length > 20_000) {
129
+ errors.push(`${location}.prompt must be between 1 and 20000 characters`);
130
+ }
131
+ if (!Array.isArray(node.capabilityRefs) ||
132
+ node.capabilityRefs.some((ref) => !allowedCapabilities.has(ref))) {
133
+ errors.push(`${location}.capabilityRefs contains unsupported authority`);
134
+ }
135
+ if (!Array.isArray(node.mcpRefs) || node.mcpRefs.some((ref) => !NODE_ID.test(String(ref)))) {
136
+ errors.push(`${location}.mcpRefs must contain declared reference ids`);
137
+ }
138
+ if (!Array.isArray(node.inputArtifacts) ||
139
+ node.inputArtifacts.some((ref) => !NODE_ID.test(String(ref)))) {
140
+ errors.push(`${location}.inputArtifacts must contain artifact reference ids`);
141
+ }
142
+ if (!Array.isArray(node.outputArtifacts) || node.outputArtifacts.length === 0) {
143
+ errors.push(`${location}.outputArtifacts must not be empty`);
144
+ } else {
145
+ node.outputArtifacts.forEach((output, outputIndex) => {
146
+ if (!NODE_ID.test(String(output?.artifact || ''))) {
147
+ errors.push(`${location}.outputArtifacts[${outputIndex}].artifact is invalid`);
148
+ }
149
+ validateRepositorySchemaPath(
150
+ output?.schema,
151
+ `${location}.outputArtifacts[${outputIndex}].schema`,
152
+ errors
153
+ );
154
+ });
155
+ }
156
+ if (!Number.isSafeInteger(node.tokenLimit) || node.tokenLimit < 1 || node.tokenLimit > 1_000_000) {
157
+ errors.push(`${location}.tokenLimit must be between 1 and 1000000`);
158
+ }
159
+ if (!Number.isSafeInteger(node.timeoutMs) || node.timeoutMs < 1_000 || node.timeoutMs > 30 * 60 * 1_000) {
160
+ errors.push(`${location}.timeoutMs must be between 1000 and 1800000`);
161
+ }
162
+ if (
163
+ !Number.isSafeInteger(node.retry?.maxAttempts) ||
164
+ node.retry.maxAttempts < 1 ||
165
+ node.retry.maxAttempts > 10 ||
166
+ !Number.isSafeInteger(node.retry?.backoffMs) ||
167
+ node.retry.backoffMs < 0 ||
168
+ node.retry.backoffMs > 300_000
169
+ ) {
170
+ errors.push(`${location}.retry must define bounded maxAttempts and backoffMs`);
171
+ }
172
+ if (forbiddenAuthorityPaths(node, location).length) {
173
+ errors.push(`${location} cannot persist commands, secret values, or unrestricted authority`);
174
+ }
175
+ } else if (node.type === 'agent') {
83
176
  if (!String(node.role || '').trim()) errors.push(`${location}.role is required`);
84
177
  if (!node.output || typeof node.output !== 'object') {
85
178
  errors.push(`${location}.output artifact contract is required`);
@@ -238,6 +331,7 @@ function validateRecipe(recipe, { mode } = {}) {
238
331
  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) {
239
332
  return { valid: false, errors: ['recipe must be a JSON object'], warnings, order: [] };
240
333
  }
334
+ recipe = migrateLegacyRecipe(recipe);
241
335
  if (recipe.schemaVersion !== 1) errors.push('schemaVersion must be 1');
242
336
  if (!RECIPE_ID.test(String(recipe.id || ''))) errors.push('id must match [a-z][a-z0-9-]{0,63}');
243
337
  if (!Number.isSafeInteger(recipe.version) || recipe.version <= 0) errors.push('version must be a positive integer');
@@ -279,20 +373,49 @@ function validateRecipe(recipe, { mode } = {}) {
279
373
  }
280
374
  validateNodeConfiguration(node, index, errors, warnings);
281
375
  });
282
- for (const node of nodes) {
376
+ if (!Array.isArray(recipe.edges)) {
377
+ errors.push('edges must be an array');
378
+ } else if (recipe.edges.length > MAX_EDGES) {
379
+ errors.push(`edges exceeds the maximum of ${MAX_EDGES}`);
380
+ }
381
+ const edgeIds = new Set();
382
+ const connections = new Set();
383
+ for (const [index, edge] of (recipe.edges || []).entries()) {
384
+ const location = `edges[${index}]`;
385
+ if (!edge || typeof edge !== 'object' || Array.isArray(edge)) {
386
+ errors.push(`${location} must be an object`);
387
+ continue;
388
+ }
389
+ if (!EDGE_ID.test(String(edge.id || ''))) errors.push(`${location}.id is invalid`);
390
+ else if (edgeIds.has(edge.id)) errors.push(`duplicate edge id: ${edge.id}`);
391
+ else edgeIds.add(edge.id);
392
+ const connection = `${edge.from}\0${edge.to}`;
393
+ if (connections.has(connection)) errors.push(`duplicate edge connection: ${edge.from} -> ${edge.to}`);
394
+ else connections.add(connection);
395
+ if (!byId.has(edge.from)) errors.push(`${edge.id || location} references unknown from node ${edge.from}`);
396
+ if (!byId.has(edge.to)) errors.push(`${edge.id || location} references unknown to node ${edge.to}`);
397
+ if (edge.from === edge.to) errors.push(`${edge.id || location} cannot connect a node to itself`);
398
+ }
399
+ recipe = withDependencies(recipe);
400
+ const projectedNodes = recipe.nodes;
401
+ byId.clear();
402
+ for (const node of projectedNodes) byId.set(node.id, node);
403
+ for (const node of projectedNodes) {
283
404
  for (const dependency of node.dependsOn || []) {
284
405
  if (!byId.has(dependency)) errors.push(`${node.id} depends on unknown node ${dependency}`);
285
406
  if (dependency === node.id) errors.push(`${node.id} cannot depend on itself`);
286
407
  }
287
408
  }
288
- const order = topologicalOrder(nodes, byId, errors);
289
- const terminals = nodes.filter((node) => ['report', 'delivery'].includes(node.type));
409
+ const loopValidation = validateLoopGroups(recipe);
410
+ errors.push(...loopValidation.errors);
411
+ const order = topologicalOrder(projectedNodes, byId, errors);
412
+ const terminals = projectedNodes.filter((node) => ['report', 'delivery'].includes(node.type));
290
413
  for (const terminal of terminals) {
291
- if (nodes.some((node) => (node.dependsOn || []).includes(terminal.id))) {
414
+ if (projectedNodes.some((node) => (node.dependsOn || []).includes(terminal.id))) {
292
415
  errors.push(`${terminal.type} must be a terminal node`);
293
416
  }
294
417
  }
295
- for (const node of nodes) {
418
+ for (const node of projectedNodes) {
296
419
  if (!terminals.some((terminal) => dependsTransitively(byId, terminal.id, node.id))) {
297
420
  errors.push(`${node.id} must lead to a report or delivery terminal`);
298
421
  }
@@ -309,6 +432,7 @@ function validateRecipe(recipe, { mode } = {}) {
309
432
  }
310
433
 
311
434
  function compileRecipe(recipe, { mode } = {}) {
435
+ recipe = withDependencies(recipe);
312
436
  const selectedMode = normalizeRunMode(mode || recipe?.compatibleModes?.[0]);
313
437
  const validation = validateRecipe(recipe, { mode: selectedMode });
314
438
  if (!validation.valid) {
@@ -318,8 +442,15 @@ function compileRecipe(recipe, { mode } = {}) {
318
442
  const compiledNodes = validation.order.map((id, index) => {
319
443
  const node = byId.get(id);
320
444
  const definition = getNodeType(node.type);
445
+ const customAgentRuntime = node.type === 'agent' && node.prompt != null
446
+ ? {
447
+ context: { ...(node.context || {}), maxTokens: node.tokenLimit },
448
+ output: node.outputArtifacts[0]
449
+ }
450
+ : {};
321
451
  return {
322
452
  ...canonicalize(node),
453
+ ...canonicalize(customAgentRuntime),
323
454
  order: index + 1,
324
455
  status: (node.dependsOn || []).length === 0 ? 'READY' : 'BLOCKED',
325
456
  capabilities: {
@@ -339,7 +470,8 @@ function compileRecipe(recipe, { mode } = {}) {
339
470
  sourceHash: sha256(recipe)
340
471
  },
341
472
  mode: selectedMode,
342
- nodes: compiledNodes
473
+ nodes: compiledNodes,
474
+ loopGroups: canonicalize(recipe.loopGroups || [])
343
475
  };
344
476
  return {
345
477
  ...graphMaterial,
@@ -415,7 +547,7 @@ function loadRecipe(rootDir, id) {
415
547
  const recipe = readRecipeFile(recipePath(directory, id));
416
548
  if (!recipe) throw recipeError(`Recipe not found: ${id}`, [], 'RECIPE_NOT_FOUND');
417
549
  if (recipe.id !== id) throw recipeError(`Recipe id must match file name: ${id}`, ['id mismatch']);
418
- return { recipe, source, path: recipePath(directory, id) };
550
+ return { recipe: migrateLegacyRecipe(recipe), source, path: recipePath(directory, id) };
419
551
  }
420
552
 
421
553
  function explainPlan(plan) {
@@ -481,10 +613,12 @@ module.exports = {
481
613
  RECIPE_ID,
482
614
  NODE_ID,
483
615
  MAX_NODES,
616
+ MAX_EDGES,
484
617
  BUILTIN_RECIPE_DIR,
485
618
  canonicalize,
486
619
  canonicalJson,
487
620
  sha256,
621
+ migrateLegacyRecipe,
488
622
  validateRecipe,
489
623
  compileRecipe,
490
624
  listRecipes,
@@ -0,0 +1,175 @@
1
+ 'use strict';
2
+
3
+ const { validateRecipe } = require('./recipe.js');
4
+ const { stableEdgeId } = require('./recipe-graph.js');
5
+ const { loadRun } = require('./run-state.js');
6
+ const { inspectRunArtifact } = require('./run-history.js');
7
+ const { redactSecrets } = require('./safe-context.js');
8
+ const { workflowStatus } = require('./workflow-runtime.js');
9
+
10
+ function checkoutError(message, code = 'RUN_CHECKOUT_ERROR') {
11
+ const error = new Error(message);
12
+ error.code = code;
13
+ return error;
14
+ }
15
+
16
+ function fallbackPosition(index) {
17
+ return { x: 100 + (index % 4) * 300, y: 100 + Math.floor(index / 4) * 190 };
18
+ }
19
+
20
+ function redactedValue(value) {
21
+ return JSON.parse(redactSecrets(JSON.stringify(value)).text);
22
+ }
23
+
24
+ function edgesFromPlan(plan) {
25
+ return plan.nodes.flatMap((node) => (node.dependsOn || []).map((from) => ({
26
+ id: stableEdgeId(from, node.id),
27
+ from,
28
+ to: node.id
29
+ })));
30
+ }
31
+
32
+ function publicNode(node, state, index) {
33
+ const runtime = state.nodes[node.id] || {};
34
+ return {
35
+ id: node.id,
36
+ displayName: node.displayName || node.name || node.id,
37
+ type: node.type,
38
+ status: runtime.status || 'PENDING',
39
+ attempts: runtime.attempts || 0,
40
+ reason: runtime.reason || null,
41
+ loopGroupId: runtime.loopGroupId || null,
42
+ loopIteration: runtime.loopIteration || null,
43
+ updatedAt: runtime.updatedAt || null,
44
+ position: fallbackPosition(index)
45
+ };
46
+ }
47
+
48
+ function runCheckout(rootDir, runId) {
49
+ const run = loadRun(rootDir, runId);
50
+ const workflow = workflowStatus(rootDir, { runId });
51
+ return redactedValue({
52
+ run: {
53
+ runId: run.runId,
54
+ displayName: run.displayName,
55
+ task: run.task,
56
+ constraints: run.constraints || '',
57
+ state: run.state,
58
+ createdAt: run.createdAt,
59
+ updatedAt: run.updatedAt
60
+ },
61
+ graphHash: workflow.plan.graphHash,
62
+ nodes: workflow.plan.nodes.map((node, index) => publicNode(node, workflow.state, index)),
63
+ edges: edgesFromPlan(workflow.plan),
64
+ loopGroups: (workflow.plan.loopGroups || []).map((group) => ({
65
+ ...group,
66
+ runtime: workflow.state.loopGroups[group.id] || null
67
+ })),
68
+ readOnly: true
69
+ });
70
+ }
71
+
72
+ function safeArtifact(rootDir, runId, artifact) {
73
+ if (!artifact?.path) return null;
74
+ try {
75
+ return { descriptor: artifact, preview: inspectRunArtifact(rootDir, runId, artifact.path) };
76
+ } catch (error) {
77
+ return { descriptor: artifact, unavailable: true, code: error.code || 'HISTORY_ARTIFACT_UNAVAILABLE' };
78
+ }
79
+ }
80
+
81
+ function runNodeIo(rootDir, runId, nodeId) {
82
+ const run = loadRun(rootDir, runId);
83
+ const workflow = workflowStatus(rootDir, { runId });
84
+ const node = workflow.plan.nodes.find((candidate) => candidate.id === nodeId);
85
+ if (!node) throw checkoutError(`Node ${nodeId} is not part of Run ${runId}`, 'RUN_NODE_NOT_FOUND');
86
+ const runtime = workflow.state.nodes[nodeId] || {};
87
+ const upstream = (node.dependsOn || []).map((id) => {
88
+ const upstreamState = workflow.state.nodes[id] || {};
89
+ return {
90
+ nodeId: id,
91
+ status: upstreamState.status || 'PENDING',
92
+ artifact: safeArtifact(rootDir, runId, upstreamState.artifact)
93
+ };
94
+ });
95
+ const relevantEvents = workflow.events.filter((event) =>
96
+ event.nodeId === nodeId ||
97
+ event.type === 'WORKFLOW_CREATED' ||
98
+ (event.changes || []).some((change) => change.nodeId === nodeId)
99
+ ).map(({ initialNodes, ...event }) => event);
100
+ return redactedValue({
101
+ runId,
102
+ node: publicNode(node, workflow.state, workflow.plan.nodes.indexOf(node)),
103
+ input: {
104
+ task: node.dependsOn?.length ? null : run.task,
105
+ constraints: node.dependsOn?.length ? null : (run.constraints || ''),
106
+ goal: node.dependsOn?.length ? null : (run.goal || null),
107
+ dependencies: upstream
108
+ },
109
+ output: {
110
+ status: runtime.status || 'PENDING',
111
+ reason: runtime.reason || null,
112
+ loopGroupId: runtime.loopGroupId || null,
113
+ loopIteration: runtime.loopIteration || null,
114
+ artifact: safeArtifact(rootDir, runId, runtime.artifact)
115
+ },
116
+ evidence: safeArtifact(rootDir, runId, runtime.artifact),
117
+ timeline: relevantEvents
118
+ });
119
+ }
120
+
121
+ function authoringNode(node) {
122
+ const omitted = new Set(['dependsOn', 'order', 'legacyGate', 'capabilities', 'status']);
123
+ return Object.fromEntries(Object.entries(node).filter(([key]) => !omitted.has(key)));
124
+ }
125
+
126
+ function duplicateRunAsRecipe(rootDir, runId, { recipeId } = {}) {
127
+ const workflow = workflowStatus(rootDir, { runId });
128
+ const id = String(recipeId || `${workflow.plan.recipe.id || 'workflow'}-copy`).trim();
129
+ const recipe = {
130
+ schemaVersion: 1,
131
+ id,
132
+ name: `${workflow.plan.recipe.name || workflow.plan.recipe.id || 'Workflow'} copy`,
133
+ description: 'Created from an immutable Run plan.',
134
+ version: 1,
135
+ compatibleModes: [workflow.plan.mode],
136
+ nodes: workflow.plan.nodes.map(authoringNode),
137
+ edges: edgesFromPlan(workflow.plan),
138
+ loopGroups: workflow.plan.loopGroups || []
139
+ };
140
+ const validation = validateRecipe(recipe);
141
+ if (!validation.valid) {
142
+ throw checkoutError(`Run cannot be duplicated: ${validation.errors.join('; ')}`, 'INVALID_RUN_DUPLICATE');
143
+ }
144
+ return { sourceRunId: runId, recipe, validation, installed: false };
145
+ }
146
+
147
+ function studioAgentHandoff(rootDir, runId) {
148
+ const run = loadRun(rootDir, runId);
149
+ const commandRoot = `npx ai-engineering-loop interaction`;
150
+ return redactedValue({
151
+ runId,
152
+ externalDispatch: false,
153
+ prompt: [
154
+ `Continue AI Engineering Loop Run ${runId}.`,
155
+ `Task: ${run.task}`,
156
+ run.constraints ? `Constraints: ${run.constraints}` : null,
157
+ 'Read the Run state and evidence before acting.',
158
+ `When blocked, ask with: ${commandRoot} question --run ${runId} --message "Your question"`,
159
+ `Poll answers with: ${commandRoot} list --run ${runId} --json`,
160
+ 'Do not create a sibling Run or claim completion without Run-bound evidence.'
161
+ ].filter(Boolean).join('\n'),
162
+ commands: {
163
+ inspect: `npx ai-engineering-loop status --run ${runId}`,
164
+ question: `${commandRoot} question --run ${runId} --message "Your question"`,
165
+ answers: `${commandRoot} list --run ${runId} --json`
166
+ }
167
+ });
168
+ }
169
+
170
+ module.exports = {
171
+ duplicateRunAsRecipe,
172
+ runCheckout,
173
+ runNodeIo,
174
+ studioAgentHandoff
175
+ };