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.
@@ -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
- const VERSION = '1.2.1';
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.2.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
- const mode = modeArg ? normalizeMode(modeArg) : (startsNewRun ? policy.defaultMode : null);
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, { task, forceNew, mode });
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, { runId });
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 run = applyGate(CWD, gate, { runId });
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.