ai-engineering-loop 1.2.1 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -4
- package/README.npm.md +7 -0
- package/SECURITY.md +3 -1
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +432 -11
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/local-workflow-studio.md +77 -0
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +42 -4
- package/lib/doctor.js +26 -2
- package/lib/handoff.js +209 -0
- package/lib/node-registry.js +155 -0
- package/lib/recipe-builder.js +200 -0
- package/lib/recipe.js +495 -0
- package/lib/run-state.js +50 -3
- package/lib/runtime-files.js +2 -0
- package/lib/studio-server.js +183 -0
- package/lib/workflow-runtime.js +718 -0
- package/package.json +3 -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/handoff.schema.json +36 -0
- package/schemas/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/workflow-event.schema.json +29 -0
- package/schemas/workflow-state.schema.json +29 -0
- package/studio/app.js +461 -0
- package/studio/index.html +31 -0
- package/studio/styles.css +75 -0
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
const fs = require('fs');
|
|
14
14
|
const path = require('path');
|
|
15
15
|
const crypto = require('crypto');
|
|
16
|
-
const { execSync } = require('child_process');
|
|
16
|
+
const { execSync, spawn } = require('child_process');
|
|
17
17
|
const {
|
|
18
18
|
homeDir,
|
|
19
19
|
applyHostSync,
|
|
@@ -38,7 +38,8 @@ const {
|
|
|
38
38
|
TERMINAL_STATES,
|
|
39
39
|
createOrResumeRun,
|
|
40
40
|
getCurrentRun,
|
|
41
|
-
loadRun
|
|
41
|
+
loadRun,
|
|
42
|
+
newRunId
|
|
42
43
|
} = require('../lib/run-state.js');
|
|
43
44
|
const {
|
|
44
45
|
DEFAULT_POLICY,
|
|
@@ -82,8 +83,42 @@ const {
|
|
|
82
83
|
createSandbox,
|
|
83
84
|
sandboxStatus
|
|
84
85
|
} = require('../lib/sandbox.js');
|
|
85
|
-
|
|
86
|
-
|
|
86
|
+
const {
|
|
87
|
+
compileRecipe,
|
|
88
|
+
explainPlan,
|
|
89
|
+
listRecipes,
|
|
90
|
+
loadRecipe,
|
|
91
|
+
mermaidPlan,
|
|
92
|
+
simulatePlan,
|
|
93
|
+
validateRecipe
|
|
94
|
+
} = require('../lib/recipe.js');
|
|
95
|
+
const {
|
|
96
|
+
applyWorkflowGate,
|
|
97
|
+
approveWorkflowNode,
|
|
98
|
+
completeWorkflowNode,
|
|
99
|
+
createWorkflowBundle,
|
|
100
|
+
failWorkflowNode,
|
|
101
|
+
recordWorkflowActivity,
|
|
102
|
+
retryWorkflowNode,
|
|
103
|
+
startWorkflowNode,
|
|
104
|
+
workflowStatus
|
|
105
|
+
} = require('../lib/workflow-runtime.js');
|
|
106
|
+
const {
|
|
107
|
+
cloneRecipe,
|
|
108
|
+
diffRecipes,
|
|
109
|
+
inspectRecipe,
|
|
110
|
+
installRecipe,
|
|
111
|
+
recipeCatalog
|
|
112
|
+
} = require('../lib/recipe-builder.js');
|
|
113
|
+
const {
|
|
114
|
+
createHandoff,
|
|
115
|
+
handoffBrief,
|
|
116
|
+
readHandoff,
|
|
117
|
+
verifyHandoff
|
|
118
|
+
} = require('../lib/handoff.js');
|
|
119
|
+
const { createStudioServer } = require('../lib/studio-server.js');
|
|
120
|
+
|
|
121
|
+
const VERSION = '1.6.0';
|
|
87
122
|
const CWD = process.cwd();
|
|
88
123
|
const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
|
|
89
124
|
|
|
@@ -337,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
|
|
|
337
372
|
|
|
338
373
|
// 0. metadata.json (Baseline)
|
|
339
374
|
const metadataJson = {
|
|
340
|
-
contextVersion: '1.
|
|
375
|
+
contextVersion: '1.6.0',
|
|
341
376
|
generatedAt: new Date().toISOString(),
|
|
342
377
|
repositoryRevision: currentRevision,
|
|
343
378
|
projectProfile: discovery.profile,
|
|
@@ -787,6 +822,7 @@ function handleRun() {
|
|
|
787
822
|
const runArgs = process.argv.slice(3);
|
|
788
823
|
const forceNew = runArgs.includes('--new');
|
|
789
824
|
const modeArg = argValue('--mode');
|
|
825
|
+
const recipeArg = argValue('--recipe');
|
|
790
826
|
const taskParts = [];
|
|
791
827
|
for (let index = 0; index < runArgs.length; index++) {
|
|
792
828
|
if (runArgs[index] === '--new') continue;
|
|
@@ -794,6 +830,10 @@ function handleRun() {
|
|
|
794
830
|
index += 1;
|
|
795
831
|
continue;
|
|
796
832
|
}
|
|
833
|
+
if (runArgs[index] === '--recipe') {
|
|
834
|
+
index += 1;
|
|
835
|
+
continue;
|
|
836
|
+
}
|
|
797
837
|
taskParts.push(runArgs[index]);
|
|
798
838
|
}
|
|
799
839
|
const task = taskParts.join(' ').trim();
|
|
@@ -802,9 +842,42 @@ function handleRun() {
|
|
|
802
842
|
const current = getCurrentRun(CWD);
|
|
803
843
|
const policy = loadPolicy(CWD);
|
|
804
844
|
const startsNewRun = forceNew || !current || TERMINAL_STATES.has(current.state);
|
|
805
|
-
|
|
845
|
+
let mode = modeArg ? normalizeMode(modeArg) : (startsNewRun ? policy.defaultMode : null);
|
|
846
|
+
let workflow = null;
|
|
847
|
+
let requestedRunId = null;
|
|
848
|
+
if (recipeArg) {
|
|
849
|
+
const { recipe } = loadRecipe(CWD, recipeArg);
|
|
850
|
+
if (!mode && current) mode = current.mode;
|
|
851
|
+
if (startsNewRun && !modeArg && !recipe.compatibleModes.includes(mode)) {
|
|
852
|
+
if (recipe.compatibleModes.length !== 1) {
|
|
853
|
+
throw new Error(`Recipe ${recipe.id} requires an explicit compatible --mode.`);
|
|
854
|
+
}
|
|
855
|
+
mode = recipe.compatibleModes[0];
|
|
856
|
+
}
|
|
857
|
+
const plan = compileRecipe(recipe, { mode });
|
|
858
|
+
if (startsNewRun) {
|
|
859
|
+
requestedRunId = newRunId();
|
|
860
|
+
workflow = createWorkflowBundle(plan, requestedRunId, {
|
|
861
|
+
run: {
|
|
862
|
+
runId: requestedRunId,
|
|
863
|
+
mode,
|
|
864
|
+
state: 'STARTED',
|
|
865
|
+
iteration: 1,
|
|
866
|
+
task
|
|
867
|
+
}
|
|
868
|
+
});
|
|
869
|
+
} else {
|
|
870
|
+
workflow = { plan };
|
|
871
|
+
}
|
|
872
|
+
}
|
|
806
873
|
if (mode) assertModeAllowed(CWD, mode);
|
|
807
|
-
runResult = createOrResumeRun(CWD, {
|
|
874
|
+
runResult = createOrResumeRun(CWD, {
|
|
875
|
+
task,
|
|
876
|
+
forceNew,
|
|
877
|
+
mode,
|
|
878
|
+
workflow,
|
|
879
|
+
...(requestedRunId ? { runId: requestedRunId } : {})
|
|
880
|
+
});
|
|
808
881
|
assertBudgetAvailable(CWD, { runId: runResult.run.runId });
|
|
809
882
|
} catch (err) {
|
|
810
883
|
log.error(err.message);
|
|
@@ -813,6 +886,14 @@ function handleRun() {
|
|
|
813
886
|
console.log(`- Run: ${runResult.run.runId} (${runResult.resumed ? 'resumed' : 'created'})`);
|
|
814
887
|
console.log(`- State: ${runResult.run.state}, iteration ${runResult.run.iteration}`);
|
|
815
888
|
console.log(`- Mode: ${runResult.run.mode || RUN_MODES.ASSISTED}`);
|
|
889
|
+
if (runResult.run.workflow) {
|
|
890
|
+
const runtime = workflowStatus(CWD, { runId: runResult.run.runId });
|
|
891
|
+
const ready = runtime.plan.nodes
|
|
892
|
+
.filter((node) => runtime.state.nodes[node.id].status === 'READY')
|
|
893
|
+
.map((node) => node.id);
|
|
894
|
+
console.log(`- Recipe: ${runResult.run.workflow.recipeId} (${runResult.run.workflow.graphHash})`);
|
|
895
|
+
console.log(`- Ready nodes: ${ready.join(', ') || 'none'}`);
|
|
896
|
+
}
|
|
816
897
|
|
|
817
898
|
const grok = detectGrokHost();
|
|
818
899
|
|
|
@@ -964,13 +1045,21 @@ function handleBudget() {
|
|
|
964
1045
|
const action = process.argv[3] || 'status';
|
|
965
1046
|
const json = process.argv.includes('--json');
|
|
966
1047
|
const runId = argValue('--run');
|
|
1048
|
+
const nodeId = argValue('--node');
|
|
967
1049
|
try {
|
|
968
1050
|
let result;
|
|
969
1051
|
if (action === 'status') {
|
|
970
|
-
result = budgetStatus(CWD, {
|
|
1052
|
+
result = budgetStatus(CWD, {
|
|
1053
|
+
runId,
|
|
1054
|
+
nodeId,
|
|
1055
|
+
estimatedTokens: argValue('--estimate') == null
|
|
1056
|
+
? 0
|
|
1057
|
+
: parseNonNegativeIntegerArg('--estimate', argValue('--estimate'))
|
|
1058
|
+
});
|
|
971
1059
|
} else if (action === 'record') {
|
|
972
1060
|
result = recordTokenUsage(CWD, {
|
|
973
1061
|
runId,
|
|
1062
|
+
nodeId,
|
|
974
1063
|
inputTokens: parseNonNegativeIntegerArg('--input', argValue('--input')),
|
|
975
1064
|
outputTokens: parseNonNegativeIntegerArg('--output', argValue('--output')),
|
|
976
1065
|
model: argValue('--model')
|
|
@@ -1020,7 +1109,11 @@ function handleGate() {
|
|
|
1020
1109
|
const runId = argValue('--run');
|
|
1021
1110
|
const json = process.argv.includes('--json');
|
|
1022
1111
|
try {
|
|
1023
|
-
const
|
|
1112
|
+
const target = runId ? loadRun(CWD, runId) : getCurrentRun(CWD);
|
|
1113
|
+
if (!target) throw new Error('No current run. Start one with `ai-engineering-loop run`.');
|
|
1114
|
+
const run = target.workflow
|
|
1115
|
+
? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
|
|
1116
|
+
: applyGate(CWD, gate, { runId: target.runId });
|
|
1024
1117
|
if (json) {
|
|
1025
1118
|
console.log(JSON.stringify({
|
|
1026
1119
|
ok: true,
|
|
@@ -1050,6 +1143,83 @@ function handleGate() {
|
|
|
1050
1143
|
}
|
|
1051
1144
|
}
|
|
1052
1145
|
|
|
1146
|
+
function handleNode() {
|
|
1147
|
+
const action = process.argv[3] || 'status';
|
|
1148
|
+
const nodeId = process.argv[4];
|
|
1149
|
+
const runId = argValue('--run');
|
|
1150
|
+
const json = process.argv.includes('--json');
|
|
1151
|
+
try {
|
|
1152
|
+
if (action === 'status') {
|
|
1153
|
+
const workflow = workflowStatus(CWD, { runId });
|
|
1154
|
+
const result = {
|
|
1155
|
+
ok: true,
|
|
1156
|
+
runId: workflow.run.runId,
|
|
1157
|
+
recipe: workflow.plan.recipe,
|
|
1158
|
+
graphHash: workflow.plan.graphHash,
|
|
1159
|
+
nodes: workflow.plan.nodes.map((node) => ({
|
|
1160
|
+
id: node.id,
|
|
1161
|
+
type: node.type,
|
|
1162
|
+
order: node.order,
|
|
1163
|
+
...workflow.state.nodes[node.id]
|
|
1164
|
+
}))
|
|
1165
|
+
};
|
|
1166
|
+
if (json) console.log(JSON.stringify(result));
|
|
1167
|
+
else {
|
|
1168
|
+
console.log(`Workflow: ${workflow.plan.recipe.id} (${workflow.plan.graphHash})`);
|
|
1169
|
+
for (const node of result.nodes) {
|
|
1170
|
+
console.log(`${String(node.order).padStart(2)} ${node.id}: ${node.status}`);
|
|
1171
|
+
}
|
|
1172
|
+
}
|
|
1173
|
+
return;
|
|
1174
|
+
}
|
|
1175
|
+
if (!nodeId || nodeId.startsWith('-')) throw new Error(`node ${action} requires a node id`);
|
|
1176
|
+
let workflow;
|
|
1177
|
+
if (action === 'start') {
|
|
1178
|
+
workflow = startWorkflowNode(CWD, nodeId, { runId });
|
|
1179
|
+
} else if (action === 'complete') {
|
|
1180
|
+
workflow = completeWorkflowNode(CWD, nodeId, { runId, artifact: argValue('--artifact') });
|
|
1181
|
+
} else if (action === 'fail') {
|
|
1182
|
+
workflow = failWorkflowNode(CWD, nodeId, {
|
|
1183
|
+
runId,
|
|
1184
|
+
reason: argValue('--reason') || 'node execution failed'
|
|
1185
|
+
});
|
|
1186
|
+
} else if (action === 'activity') {
|
|
1187
|
+
workflow = recordWorkflowActivity(CWD, nodeId, {
|
|
1188
|
+
runId,
|
|
1189
|
+
message: argValue('--message')
|
|
1190
|
+
});
|
|
1191
|
+
} else if (action === 'retry') {
|
|
1192
|
+
workflow = retryWorkflowNode(CWD, nodeId, { runId });
|
|
1193
|
+
} else if (action === 'approve') {
|
|
1194
|
+
if (!process.argv.includes('--yes')) {
|
|
1195
|
+
throw new Error('Approval requires explicit --yes confirmation');
|
|
1196
|
+
}
|
|
1197
|
+
workflow = approveWorkflowNode(CWD, nodeId, {
|
|
1198
|
+
runId,
|
|
1199
|
+
approvedBy: argValue('--by') || 'human'
|
|
1200
|
+
});
|
|
1201
|
+
} else {
|
|
1202
|
+
throw new Error(`Unknown node action: ${action}`);
|
|
1203
|
+
}
|
|
1204
|
+
const node = workflow.state.nodes[nodeId];
|
|
1205
|
+
if (json) console.log(JSON.stringify({ ok: true, nodeId, ...node }));
|
|
1206
|
+
else log.success(`✓ Node ${nodeId}: ${node.status}`);
|
|
1207
|
+
} catch (err) {
|
|
1208
|
+
if (json) {
|
|
1209
|
+
console.log(JSON.stringify({
|
|
1210
|
+
ok: false,
|
|
1211
|
+
code: err.code || 'NODE_FAILED',
|
|
1212
|
+
error: err.message,
|
|
1213
|
+
details: err.details || []
|
|
1214
|
+
}));
|
|
1215
|
+
} else {
|
|
1216
|
+
log.error(err.message);
|
|
1217
|
+
for (const detail of err.details || []) console.error(`- ${detail}`);
|
|
1218
|
+
}
|
|
1219
|
+
process.exit(1);
|
|
1220
|
+
}
|
|
1221
|
+
}
|
|
1222
|
+
|
|
1053
1223
|
function commandFiles(startIndex, optionsWithValues = []) {
|
|
1054
1224
|
const files = [];
|
|
1055
1225
|
for (let index = startIndex; index < process.argv.length; index++) {
|
|
@@ -1180,6 +1350,219 @@ function handleDoctor() {
|
|
|
1180
1350
|
if (!result.ok) process.exit(1);
|
|
1181
1351
|
}
|
|
1182
1352
|
|
|
1353
|
+
function handleRecipe() {
|
|
1354
|
+
const action = process.argv[3] || 'list';
|
|
1355
|
+
const id = process.argv[4];
|
|
1356
|
+
const mode = argValue('--mode');
|
|
1357
|
+
const json = process.argv.includes('--json');
|
|
1358
|
+
try {
|
|
1359
|
+
if (action === 'catalog') {
|
|
1360
|
+
const result = { ok: true, nodeTypes: recipeCatalog() };
|
|
1361
|
+
console.log(JSON.stringify(result, null, json ? 0 : 2));
|
|
1362
|
+
return;
|
|
1363
|
+
}
|
|
1364
|
+
if (action === 'clone' || action === 'create') {
|
|
1365
|
+
const sourceId = action === 'clone' ? id : (argValue('--from') || 'default');
|
|
1366
|
+
const targetId = action === 'clone' ? process.argv[5] : id;
|
|
1367
|
+
if (!sourceId || !targetId || targetId.startsWith('-')) {
|
|
1368
|
+
throw new Error(`recipe ${action} requires ${action === 'clone' ? '<source> <target>' : '<id> [--from <preset>]'}`);
|
|
1369
|
+
}
|
|
1370
|
+
const result = cloneRecipe(CWD, sourceId, targetId, { description: argValue('--description') });
|
|
1371
|
+
const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
|
|
1372
|
+
console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
|
|
1373
|
+
`Created ${targetId} from ${sourceId} at ${relativePath}\nSource hash: ${result.sourceHash}`);
|
|
1374
|
+
return;
|
|
1375
|
+
}
|
|
1376
|
+
if (action === 'install') {
|
|
1377
|
+
if (!id || id.startsWith('-')) throw new Error('recipe install requires a candidate path');
|
|
1378
|
+
const result = installRecipe(CWD, id, { replace: process.argv.includes('--replace') });
|
|
1379
|
+
const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
|
|
1380
|
+
console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
|
|
1381
|
+
`Installed ${result.recipe.id} v${result.recipe.version}\nSource hash: ${result.sourceHash}`);
|
|
1382
|
+
return;
|
|
1383
|
+
}
|
|
1384
|
+
if (action === 'diff') {
|
|
1385
|
+
const rightId = process.argv[5];
|
|
1386
|
+
if (!id || !rightId) throw new Error('recipe diff requires <left> <right>');
|
|
1387
|
+
const result = diffRecipes(CWD, id, rightId);
|
|
1388
|
+
console.log(JSON.stringify({ ok: true, ...result }, null, json ? 0 : 2));
|
|
1389
|
+
return;
|
|
1390
|
+
}
|
|
1391
|
+
if (action === 'inspect') {
|
|
1392
|
+
if (!id || id.startsWith('-')) throw new Error('recipe inspect requires an id');
|
|
1393
|
+
console.log(JSON.stringify({ ok: true, ...inspectRecipe(CWD, id) }, null, json ? 0 : 2));
|
|
1394
|
+
return;
|
|
1395
|
+
}
|
|
1396
|
+
if (action === 'list') {
|
|
1397
|
+
const recipes = listRecipes(CWD).map((entry) => {
|
|
1398
|
+
const { recipe } = loadRecipe(CWD, entry.id);
|
|
1399
|
+
return {
|
|
1400
|
+
...entry,
|
|
1401
|
+
description: recipe.description,
|
|
1402
|
+
compatibleModes: recipe.compatibleModes
|
|
1403
|
+
};
|
|
1404
|
+
});
|
|
1405
|
+
if (json) console.log(JSON.stringify({ ok: true, recipes }));
|
|
1406
|
+
else {
|
|
1407
|
+
console.log('Workflow recipes:');
|
|
1408
|
+
for (const recipe of recipes) {
|
|
1409
|
+
console.log(`- ${recipe.id} [${recipe.source}] ${recipe.compatibleModes.join(', ')}`);
|
|
1410
|
+
console.log(` ${recipe.description}`);
|
|
1411
|
+
}
|
|
1412
|
+
}
|
|
1413
|
+
return;
|
|
1414
|
+
}
|
|
1415
|
+
|
|
1416
|
+
if (!['show', 'validate', 'explain', 'graph', 'simulate'].includes(action)) {
|
|
1417
|
+
throw Object.assign(new Error(`Unknown recipe action: ${action}`), { code: 'UNKNOWN_RECIPE_ACTION' });
|
|
1418
|
+
}
|
|
1419
|
+
if (!id || id.startsWith('-')) {
|
|
1420
|
+
throw Object.assign(new Error(`recipe ${action} requires an id`), { code: 'RECIPE_ID_REQUIRED' });
|
|
1421
|
+
}
|
|
1422
|
+
const loaded = loadRecipe(CWD, id);
|
|
1423
|
+
if (action === 'show') {
|
|
1424
|
+
console.log(JSON.stringify(loaded.recipe, null, json ? 0 : 2));
|
|
1425
|
+
return;
|
|
1426
|
+
}
|
|
1427
|
+
if (action === 'validate') {
|
|
1428
|
+
const validation = validateRecipe(loaded.recipe, mode ? { mode } : {});
|
|
1429
|
+
const result = { ok: validation.valid, id, source: loaded.source, ...validation };
|
|
1430
|
+
if (json) console.log(JSON.stringify(result));
|
|
1431
|
+
else {
|
|
1432
|
+
console.log(`Recipe ${id}: ${validation.valid ? 'VALID' : 'INVALID'}`);
|
|
1433
|
+
for (const warning of validation.warnings) console.log(`! ${warning}`);
|
|
1434
|
+
for (const error of validation.errors) console.log(`✗ ${error}`);
|
|
1435
|
+
}
|
|
1436
|
+
if (!validation.valid) process.exit(1);
|
|
1437
|
+
return;
|
|
1438
|
+
}
|
|
1439
|
+
|
|
1440
|
+
const plan = compileRecipe(loaded.recipe, mode ? { mode } : {});
|
|
1441
|
+
if (action === 'explain') {
|
|
1442
|
+
console.log(json ? JSON.stringify({ ok: true, source: loaded.source, plan }) : explainPlan(plan));
|
|
1443
|
+
} else if (action === 'graph') {
|
|
1444
|
+
const mermaid = mermaidPlan(plan);
|
|
1445
|
+
console.log(json ? JSON.stringify({ ok: true, graphHash: plan.graphHash, mermaid }) : mermaid);
|
|
1446
|
+
} else {
|
|
1447
|
+
const simulation = simulatePlan(plan);
|
|
1448
|
+
console.log(JSON.stringify({ ok: true, ...simulation }, null, json ? 0 : 2));
|
|
1449
|
+
}
|
|
1450
|
+
} catch (err) {
|
|
1451
|
+
if (json) {
|
|
1452
|
+
console.log(JSON.stringify({
|
|
1453
|
+
ok: false,
|
|
1454
|
+
code: err.code || 'RECIPE_FAILED',
|
|
1455
|
+
error: err.message,
|
|
1456
|
+
details: err.details || []
|
|
1457
|
+
}));
|
|
1458
|
+
} else {
|
|
1459
|
+
log.error(err.message);
|
|
1460
|
+
for (const detail of err.details || []) console.error(`- ${detail}`);
|
|
1461
|
+
}
|
|
1462
|
+
process.exit(1);
|
|
1463
|
+
}
|
|
1464
|
+
}
|
|
1465
|
+
|
|
1466
|
+
function safeHandoffOutput(file) {
|
|
1467
|
+
const absolute = path.resolve(CWD, file);
|
|
1468
|
+
const relative = path.relative(CWD, absolute);
|
|
1469
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`)) {
|
|
1470
|
+
throw Object.assign(new Error('Handoff output must stay inside the repository'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1471
|
+
}
|
|
1472
|
+
const parent = path.dirname(absolute);
|
|
1473
|
+
fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
|
|
1474
|
+
const realRoot = fs.realpathSync(CWD);
|
|
1475
|
+
const realParent = fs.realpathSync(parent);
|
|
1476
|
+
if (realParent !== realRoot && !realParent.startsWith(`${realRoot}${path.sep}`)) {
|
|
1477
|
+
throw Object.assign(new Error('Handoff output escapes the repository through a symlink'), { code: 'UNSAFE_HANDOFF_PATH' });
|
|
1478
|
+
}
|
|
1479
|
+
return absolute;
|
|
1480
|
+
}
|
|
1481
|
+
|
|
1482
|
+
function handleHandoff() {
|
|
1483
|
+
const action = process.argv[3] || 'create';
|
|
1484
|
+
const json = process.argv.includes('--json');
|
|
1485
|
+
try {
|
|
1486
|
+
if (action === 'create') {
|
|
1487
|
+
const bundle = createHandoff(CWD, {
|
|
1488
|
+
runId: argValue('--run'),
|
|
1489
|
+
audience: argValue('--audience') || 'developer'
|
|
1490
|
+
});
|
|
1491
|
+
const requested = argValue('--output');
|
|
1492
|
+
if (requested === '-') {
|
|
1493
|
+
console.log(JSON.stringify(bundle, null, json ? 0 : 2));
|
|
1494
|
+
return;
|
|
1495
|
+
}
|
|
1496
|
+
const output = safeHandoffOutput(requested || `${bundle.runId}.ael-handoff.json`);
|
|
1497
|
+
const descriptor = fs.openSync(output, 'wx', 0o600);
|
|
1498
|
+
try {
|
|
1499
|
+
fs.writeFileSync(descriptor, `${JSON.stringify(bundle, null, 2)}\n`);
|
|
1500
|
+
fs.fsyncSync(descriptor);
|
|
1501
|
+
} finally {
|
|
1502
|
+
fs.closeSync(descriptor);
|
|
1503
|
+
}
|
|
1504
|
+
const result = {
|
|
1505
|
+
ok: true,
|
|
1506
|
+
path: path.relative(CWD, output).split(path.sep).join('/'),
|
|
1507
|
+
runId: bundle.runId,
|
|
1508
|
+
audience: bundle.audience,
|
|
1509
|
+
bundleHash: bundle.bundleHash
|
|
1510
|
+
};
|
|
1511
|
+
console.log(json ? JSON.stringify(result) : `Created ${result.path}\nBundle hash: ${result.bundleHash}`);
|
|
1512
|
+
return;
|
|
1513
|
+
}
|
|
1514
|
+
const file = process.argv[4];
|
|
1515
|
+
if (!file || file.startsWith('-')) throw new Error(`handoff ${action} requires a file`);
|
|
1516
|
+
const bundle = readHandoff(CWD, file);
|
|
1517
|
+
const verification = verifyHandoff(bundle);
|
|
1518
|
+
if (action === 'inspect') {
|
|
1519
|
+
console.log(JSON.stringify({ ok: true, ...verification }, null, json ? 0 : 2));
|
|
1520
|
+
} else if (action === 'brief') {
|
|
1521
|
+
console.log(handoffBrief(bundle));
|
|
1522
|
+
} else {
|
|
1523
|
+
throw new Error('Unknown handoff action. Use create|inspect|brief');
|
|
1524
|
+
}
|
|
1525
|
+
} catch (err) {
|
|
1526
|
+
if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'HANDOFF_FAILED', error: err.message }));
|
|
1527
|
+
else log.error(err.message);
|
|
1528
|
+
process.exitCode = 1;
|
|
1529
|
+
}
|
|
1530
|
+
}
|
|
1531
|
+
|
|
1532
|
+
function openStudio(url) {
|
|
1533
|
+
const command = process.platform === 'darwin'
|
|
1534
|
+
? ['open', [url]]
|
|
1535
|
+
: process.platform === 'win32'
|
|
1536
|
+
? ['cmd', ['/c', 'start', '', url]]
|
|
1537
|
+
: ['xdg-open', [url]];
|
|
1538
|
+
const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
|
|
1539
|
+
child.on('error', () => {});
|
|
1540
|
+
child.unref();
|
|
1541
|
+
}
|
|
1542
|
+
|
|
1543
|
+
function handleStudio() {
|
|
1544
|
+
const requestedPort = argValue('--port');
|
|
1545
|
+
const port = requestedPort == null ? 4317 : Number(requestedPort);
|
|
1546
|
+
if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
|
|
1547
|
+
log.error('--port must be an integer from 0 to 65535');
|
|
1548
|
+
process.exitCode = 1;
|
|
1549
|
+
return;
|
|
1550
|
+
}
|
|
1551
|
+
const { server, token } = createStudioServer(CWD);
|
|
1552
|
+
server.on('error', (error) => {
|
|
1553
|
+
log.error(`Unable to start Studio: ${error.message}`);
|
|
1554
|
+
process.exitCode = 1;
|
|
1555
|
+
});
|
|
1556
|
+
server.listen(port, '127.0.0.1', () => {
|
|
1557
|
+
const address = server.address();
|
|
1558
|
+
const url = `http://127.0.0.1:${address.port}/?token=${token}`;
|
|
1559
|
+
log.success('✓ Workflow Studio is running locally');
|
|
1560
|
+
console.log(url);
|
|
1561
|
+
console.log('Press Ctrl+C to stop. The session token is valid only for this process.');
|
|
1562
|
+
if (!process.argv.includes('--no-open')) openStudio(url);
|
|
1563
|
+
});
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1183
1566
|
// Help Menu
|
|
1184
1567
|
function printHelp() {
|
|
1185
1568
|
console.log(`
|
|
@@ -1196,6 +1579,7 @@ Commands:
|
|
|
1196
1579
|
run [task] Start or resume a stateful engineering run, sync hosts, and instruct the agent
|
|
1197
1580
|
--new start a new run even when another run is active
|
|
1198
1581
|
--mode report-only|assisted|unattended
|
|
1582
|
+
--recipe <id> bind an immutable compiled workflow plan
|
|
1199
1583
|
state Inspect the current run ledger
|
|
1200
1584
|
--run <id> target a non-current run
|
|
1201
1585
|
--json print the complete machine-readable ledger
|
|
@@ -1203,14 +1587,22 @@ Commands:
|
|
|
1203
1587
|
goal | report | maker | verification | review | judge | delivery
|
|
1204
1588
|
--run <id> target a non-current run
|
|
1205
1589
|
--json print machine-readable gate output
|
|
1590
|
+
node Operate custom nodes in a recipe-bound run
|
|
1591
|
+
status [--run <id>] [--json]
|
|
1592
|
+
start <id> [--run <id>] [--json]
|
|
1593
|
+
complete <id> [--artifact <repository-relative-path>] [--json]
|
|
1594
|
+
fail <id> [--reason <text>] [--json]
|
|
1595
|
+
activity <id> --message <safe progress text> [--json]
|
|
1596
|
+
retry <id> [--json]
|
|
1597
|
+
approve <id> --yes [--by <name>] [--json]
|
|
1206
1598
|
policy Inspect or update fail-closed runtime controls
|
|
1207
1599
|
show [--json]
|
|
1208
1600
|
set [--default-mode <mode>] [--allow-unattended true|false]
|
|
1209
1601
|
[--require-sandbox true|false]
|
|
1210
1602
|
[--per-run-token-limit <n>] [--daily-token-limit <n>]
|
|
1211
1603
|
budget Enforce actual provider-reported token usage and emergency pause
|
|
1212
|
-
status [--run <id>] [--json]
|
|
1213
|
-
record --input <n> --output <n> --model <id> [--run <id>]
|
|
1604
|
+
status [--run <id>] [--node <id>] [--estimate <n>] [--json]
|
|
1605
|
+
record --input <n> --output <n> --model <id> [--run <id>] [--node <id>]
|
|
1214
1606
|
pause | resume
|
|
1215
1607
|
sandbox Isolate Maker changes in a locked disposable Git worktree
|
|
1216
1608
|
create | capture | abort | status [--run <id>] [--json]
|
|
@@ -1227,6 +1619,23 @@ Commands:
|
|
|
1227
1619
|
--json print machine-readable reasons
|
|
1228
1620
|
doctor Check runtime, schemas, host assets, package contents, and eval catalog
|
|
1229
1621
|
--json print machine-readable diagnostics
|
|
1622
|
+
recipe Inspect and compile declarative workflow recipes (does not execute nodes)
|
|
1623
|
+
list [--json]
|
|
1624
|
+
catalog [--json]
|
|
1625
|
+
create <id> [--from <preset>] [--description <text>] [--json]
|
|
1626
|
+
clone <source> <target> [--description <text>] [--json]
|
|
1627
|
+
install <path> [--replace] [--json]
|
|
1628
|
+
inspect <id> [--json]
|
|
1629
|
+
diff <left> <right> [--json]
|
|
1630
|
+
show <id> [--json]
|
|
1631
|
+
validate <id> [--mode <mode>] [--json]
|
|
1632
|
+
explain | graph | simulate <id> [--mode <mode>] [--json]
|
|
1633
|
+
studio Open the localhost-only visual workflow editor
|
|
1634
|
+
[--port <0-65535>] [--no-open]
|
|
1635
|
+
handoff Export or verify a redacted, integrity-bound knowledge transfer
|
|
1636
|
+
create [--run <id>] [--audience developer|agent|auditor]
|
|
1637
|
+
[--output <repository-relative-file>|-] [--json]
|
|
1638
|
+
inspect | brief <repository-relative-file> [--json]
|
|
1230
1639
|
sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
1231
1640
|
(only hosts that already exist; DOT skills only if already installed)
|
|
1232
1641
|
--dry-run print the plan without writing
|
|
@@ -1267,6 +1676,9 @@ switch (command) {
|
|
|
1267
1676
|
case 'gate':
|
|
1268
1677
|
handleGate();
|
|
1269
1678
|
break;
|
|
1679
|
+
case 'node':
|
|
1680
|
+
handleNode();
|
|
1681
|
+
break;
|
|
1270
1682
|
case 'policy':
|
|
1271
1683
|
handlePolicy();
|
|
1272
1684
|
break;
|
|
@@ -1288,6 +1700,15 @@ switch (command) {
|
|
|
1288
1700
|
case 'doctor':
|
|
1289
1701
|
handleDoctor();
|
|
1290
1702
|
break;
|
|
1703
|
+
case 'recipe':
|
|
1704
|
+
handleRecipe();
|
|
1705
|
+
break;
|
|
1706
|
+
case 'studio':
|
|
1707
|
+
handleStudio();
|
|
1708
|
+
break;
|
|
1709
|
+
case 'handoff':
|
|
1710
|
+
handleHandoff();
|
|
1711
|
+
break;
|
|
1291
1712
|
case 'sync-hosts':
|
|
1292
1713
|
handleSyncHosts();
|
|
1293
1714
|
break;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Controlled Workflow Runtime
|
|
2
|
+
|
|
3
|
+
The controlled runtime binds a validated recipe to one run without replacing the existing artifact gates. It is opt-in through `run --recipe`; runs started without that option retain the legacy behavior.
|
|
4
|
+
|
|
5
|
+
## Immutable run binding
|
|
6
|
+
|
|
7
|
+
At run creation the CLI compiles the selected recipe and writes private runtime files under `.ai-engineering-loop/runs/<run-id>/`:
|
|
8
|
+
|
|
9
|
+
- `plan.json`: canonical compiled DAG with source and graph hashes
|
|
10
|
+
- `workflow-state.json`: reconstructable scheduler cache
|
|
11
|
+
- `events.jsonl`: append-only, hash-chained transition log
|
|
12
|
+
|
|
13
|
+
The run ledger stores the recipe ID, recipe version, source hash, and graph hash. Resume rejects a different graph. Every load recalculates the plan hash and verifies the full event chain. The state cache is reconstructed from events, so a stale or edited cache cannot grant a node permission to run.
|
|
14
|
+
|
|
15
|
+
## Scheduler rules
|
|
16
|
+
|
|
17
|
+
Node states are:
|
|
18
|
+
|
|
19
|
+
`PENDING → READY → RUNNING → PASSED`
|
|
20
|
+
|
|
21
|
+
Additional outcomes are `FAILED`, `SKIPPED`, and `BLOCKED`.
|
|
22
|
+
|
|
23
|
+
- A node becomes `READY` only after every dependency is `PASSED` or conditionally `SKIPPED`.
|
|
24
|
+
- A failed dependency makes descendants `BLOCKED`.
|
|
25
|
+
- `retry` returns a failed or interrupted custom node to `READY` and recalculates descendants.
|
|
26
|
+
- Structured conditions read only allowlisted run metadata.
|
|
27
|
+
- Legacy gates execute atomically under the workflow lock and mark their corresponding node passed only after existing artifact validation succeeds.
|
|
28
|
+
- Judge `ITERATE` resets Maker and its descendants while preserving upstream analysis.
|
|
29
|
+
- Judge `ESCALATE` blocks unfinished nodes.
|
|
30
|
+
|
|
31
|
+
## Commands
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Create an immutable recipe-bound run
|
|
35
|
+
ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
|
|
36
|
+
|
|
37
|
+
# Inspect scheduler state
|
|
38
|
+
ai-engineering-loop node status --json
|
|
39
|
+
|
|
40
|
+
# Custom agent lifecycle
|
|
41
|
+
ai-engineering-loop node start root-cause
|
|
42
|
+
ai-engineering-loop budget status --node root-cause --estimate 4000
|
|
43
|
+
ai-engineering-loop budget record --node root-cause \
|
|
44
|
+
--input 3000 --output 700 --model provider/model-id
|
|
45
|
+
ai-engineering-loop node complete root-cause \
|
|
46
|
+
--artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
47
|
+
|
|
48
|
+
# Failure and crash recovery
|
|
49
|
+
ai-engineering-loop node fail root-cause --reason provider-timeout
|
|
50
|
+
ai-engineering-loop node retry root-cause
|
|
51
|
+
|
|
52
|
+
# Explicit human checkpoint
|
|
53
|
+
ai-engineering-loop node approve delivery-approval --yes --by account-id
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Existing gate commands remain authoritative for built-in stages:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
ai-engineering-loop gate goal
|
|
60
|
+
ai-engineering-loop gate maker
|
|
61
|
+
ai-engineering-loop gate verification
|
|
62
|
+
ai-engineering-loop gate review
|
|
63
|
+
ai-engineering-loop gate judge
|
|
64
|
+
ai-engineering-loop gate delivery
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Artifact and token boundaries
|
|
68
|
+
|
|
69
|
+
Agent completion requires a regular JSON file inside the repository, rejects symlink escape, binds `runId`, validates the declared repository-relative schema, and records the artifact hash. Artifact content is never copied into the event log.
|
|
70
|
+
|
|
71
|
+
Provider-reported usage can be attributed to a node. `budget status --node --estimate` must be called before a model request; it combines kill switch, daily, run, node-state, and node token limits. `budget record --node` records actual provider usage after the response.
|
|
72
|
+
|
|
73
|
+
## Intentionally disabled
|
|
74
|
+
|
|
75
|
+
The runtime does not execute `command` nodes. Command nodes are conservatively classified as repository mutation, rejected in `REPORT_ONLY`, and fail with `COMMAND_EXECUTION_DISABLED`. Enabling them later requires a separate sandboxed executor with executable allowlists, environment filtering, bounded output, cancellation, and auditable process isolation.
|
|
76
|
+
|
|
77
|
+
The CLI also does not invoke a model itself. Host agents perform model work, record real token usage, and submit structured artifacts through the runtime boundary.
|