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/README.md +37 -4
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +305 -10
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +42 -4
- package/lib/doctor.js +25 -2
- 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 +1 -0
- package/lib/workflow-runtime.js +692 -0
- package/package.json +2 -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/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/workflow-event.schema.json +28 -0
- package/schemas/workflow-state.schema.json +29 -0
package/README.md
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
|
-
# AI Engineering Loop
|
|
2
|
-
|
|
3
1
|
<div align="center">
|
|
2
|
+
<h1>AI Engineering Loop</h1>
|
|
4
3
|
|
|
5
4
|
[](https://www.npmjs.com/package/ai-engineering-loop)
|
|
6
5
|
[](https://opensource.org/licenses/MIT)
|
|
7
6
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
8
7
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
9
|
-
[](https://github.com/egagofur/ai-engineering-loop/releases)
|
|
10
9
|
|
|
11
10
|
**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
|
|
12
11
|
|
|
@@ -183,6 +182,7 @@ npx ai-engineering-loop refresh
|
|
|
183
182
|
# Start or resume a stateful engineering run
|
|
184
183
|
npx ai-engineering-loop run
|
|
185
184
|
npx ai-engineering-loop run --mode report-only "audit this repository"
|
|
185
|
+
npx ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
|
|
186
186
|
|
|
187
187
|
# Inspect the run ledger
|
|
188
188
|
npx ai-engineering-loop state --json
|
|
@@ -196,6 +196,8 @@ npx ai-engineering-loop budget resume
|
|
|
196
196
|
|
|
197
197
|
# Record actual provider-reported usage after each model response
|
|
198
198
|
npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
|
|
199
|
+
npx ai-engineering-loop budget status --node root-cause --estimate 4000
|
|
200
|
+
npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
|
|
199
201
|
|
|
200
202
|
# Isolate unattended Maker, then capture only its diff
|
|
201
203
|
npx ai-engineering-loop sandbox create
|
|
@@ -219,6 +221,25 @@ npx ai-engineering-loop context judge <files...>
|
|
|
219
221
|
npx ai-engineering-loop doctor
|
|
220
222
|
npx ai-engineering-loop eval
|
|
221
223
|
|
|
224
|
+
# Inspect declarative workflow recipes without executing nodes
|
|
225
|
+
npx ai-engineering-loop recipe list
|
|
226
|
+
npx ai-engineering-loop recipe validate default --mode assisted
|
|
227
|
+
npx ai-engineering-loop recipe explain default --mode assisted
|
|
228
|
+
npx ai-engineering-loop recipe graph default --mode assisted
|
|
229
|
+
npx ai-engineering-loop recipe simulate default --mode assisted
|
|
230
|
+
npx ai-engineering-loop recipe catalog --json
|
|
231
|
+
npx ai-engineering-loop recipe create api-bugfix --from bugfix
|
|
232
|
+
npx ai-engineering-loop recipe inspect api-bugfix --json
|
|
233
|
+
npx ai-engineering-loop recipe diff bugfix api-bugfix
|
|
234
|
+
npx ai-engineering-loop recipe install candidate.json
|
|
235
|
+
npx ai-engineering-loop recipe install candidate-v2.json --replace
|
|
236
|
+
|
|
237
|
+
# Operate a custom node in an immutable recipe-bound run
|
|
238
|
+
npx ai-engineering-loop node status
|
|
239
|
+
npx ai-engineering-loop node start root-cause
|
|
240
|
+
npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
|
|
241
|
+
npx ai-engineering-loop node approve delivery-approval --yes
|
|
242
|
+
|
|
222
243
|
# Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
223
244
|
npx ai-engineering-loop sync-hosts
|
|
224
245
|
|
|
@@ -233,6 +254,10 @@ npx ai-engineering-loop generate-workflow --write
|
|
|
233
254
|
|
|
234
255
|
Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Usage, worktrees, locks, context packs, and logs are Git-ignored. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. `ASSISTED` is the default and requires explicit human delivery approval. `UNATTENDED` is disabled until a human enables it. See [`core/runtime-safety.md`](core/runtime-safety.md), [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
|
|
235
256
|
|
|
257
|
+
Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
|
|
258
|
+
|
|
259
|
+
The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, preserves replaced versions locally, and exposes catalog/inspect/diff JSON for AI agents and a future UI. The host-neutral agent protocol is in [`agents/recipe-builder.md`](agents/recipe-builder.md).
|
|
260
|
+
|
|
236
261
|
Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
|
|
237
262
|
|
|
238
263
|
`sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
|
|
@@ -321,7 +346,13 @@ ai-engineering-loop/
|
|
|
321
346
|
│ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
|
|
322
347
|
│
|
|
323
348
|
├── lib/ # Core orchestration & decision engine
|
|
324
|
-
│
|
|
349
|
+
│ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
|
|
350
|
+
│ ├── recipe.js # Declarative graph validator and deterministic compiler
|
|
351
|
+
│ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
|
|
352
|
+
│
|
|
353
|
+
├── recipes/ # Built-in workflow presets; target repos may add their own
|
|
354
|
+
│ ├── default.json # Current production loop represented as a graph
|
|
355
|
+
│ └── audit.json # Read-only report workflow
|
|
325
356
|
│
|
|
326
357
|
├── tests/ # Deterministic test suites
|
|
327
358
|
│ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
|
|
@@ -360,6 +391,8 @@ ai-engineering-loop/
|
|
|
360
391
|
│ ├── escalation-policy.md # Deterministic human escalation triggers
|
|
361
392
|
│ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
|
|
362
393
|
│ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
|
|
394
|
+
│ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
|
|
395
|
+
│ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
|
|
363
396
|
│ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
|
|
364
397
|
│
|
|
365
398
|
├── profiles/ # Project archetype profiles
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Recipe Builder Agent
|
|
2
|
+
|
|
3
|
+
You author workflow proposals; you do not bypass the recipe compiler or execute a proposed workflow.
|
|
4
|
+
|
|
5
|
+
## Interview
|
|
6
|
+
|
|
7
|
+
Ask only unanswered questions:
|
|
8
|
+
|
|
9
|
+
1. What outcome should the workflow produce?
|
|
10
|
+
2. Which modes are allowed: `REPORT_ONLY`, `ASSISTED`, or `UNATTENDED`?
|
|
11
|
+
3. May it mutate the repository?
|
|
12
|
+
4. What analysis is required before Maker?
|
|
13
|
+
5. Where is explicit human approval required?
|
|
14
|
+
6. What are the maximum files and tokens for each agent node?
|
|
15
|
+
7. Is delivery risk low, medium, or high?
|
|
16
|
+
|
|
17
|
+
## Authoring protocol
|
|
18
|
+
|
|
19
|
+
1. Run `ai-engineering-loop recipe catalog --json`.
|
|
20
|
+
2. Select the closest built-in preset.
|
|
21
|
+
3. Run `recipe create <id> --from <preset>`; never start from an unconstrained blank graph.
|
|
22
|
+
4. Make the smallest meaningful edits to the project recipe.
|
|
23
|
+
5. Run `recipe validate`, `recipe inspect`, `recipe diff <preset> <id>`, `recipe explain`, `recipe graph`, and `recipe simulate`.
|
|
24
|
+
6. Present validation, diff, graph hash, model calls, token ceiling, mutations, side effects, and approvals.
|
|
25
|
+
7. Ask for explicit human approval.
|
|
26
|
+
8. For a separately prepared candidate, use `recipe install <path>` only after approval. Existing recipes require `--replace` and a higher version.
|
|
27
|
+
|
|
28
|
+
Never add executable code, shell text, remote schema URLs, conditional mandatory safety gates, or mutation to `REPORT_ONLY`. Never claim validation or simulation executed a workflow.
|
|
@@ -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,34 @@ 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
|
+
retryWorkflowNode,
|
|
102
|
+
startWorkflowNode,
|
|
103
|
+
workflowStatus
|
|
104
|
+
} = require('../lib/workflow-runtime.js');
|
|
105
|
+
const {
|
|
106
|
+
cloneRecipe,
|
|
107
|
+
diffRecipes,
|
|
108
|
+
inspectRecipe,
|
|
109
|
+
installRecipe,
|
|
110
|
+
recipeCatalog
|
|
111
|
+
} = require('../lib/recipe-builder.js');
|
|
112
|
+
|
|
113
|
+
const VERSION = '1.5.0';
|
|
87
114
|
const CWD = process.cwd();
|
|
88
115
|
const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
|
|
89
116
|
|
|
@@ -337,7 +364,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
|
|
|
337
364
|
|
|
338
365
|
// 0. metadata.json (Baseline)
|
|
339
366
|
const metadataJson = {
|
|
340
|
-
contextVersion: '1.
|
|
367
|
+
contextVersion: '1.5.0',
|
|
341
368
|
generatedAt: new Date().toISOString(),
|
|
342
369
|
repositoryRevision: currentRevision,
|
|
343
370
|
projectProfile: discovery.profile,
|
|
@@ -787,6 +814,7 @@ function handleRun() {
|
|
|
787
814
|
const runArgs = process.argv.slice(3);
|
|
788
815
|
const forceNew = runArgs.includes('--new');
|
|
789
816
|
const modeArg = argValue('--mode');
|
|
817
|
+
const recipeArg = argValue('--recipe');
|
|
790
818
|
const taskParts = [];
|
|
791
819
|
for (let index = 0; index < runArgs.length; index++) {
|
|
792
820
|
if (runArgs[index] === '--new') continue;
|
|
@@ -794,6 +822,10 @@ function handleRun() {
|
|
|
794
822
|
index += 1;
|
|
795
823
|
continue;
|
|
796
824
|
}
|
|
825
|
+
if (runArgs[index] === '--recipe') {
|
|
826
|
+
index += 1;
|
|
827
|
+
continue;
|
|
828
|
+
}
|
|
797
829
|
taskParts.push(runArgs[index]);
|
|
798
830
|
}
|
|
799
831
|
const task = taskParts.join(' ').trim();
|
|
@@ -802,9 +834,42 @@ function handleRun() {
|
|
|
802
834
|
const current = getCurrentRun(CWD);
|
|
803
835
|
const policy = loadPolicy(CWD);
|
|
804
836
|
const startsNewRun = forceNew || !current || TERMINAL_STATES.has(current.state);
|
|
805
|
-
|
|
837
|
+
let mode = modeArg ? normalizeMode(modeArg) : (startsNewRun ? policy.defaultMode : null);
|
|
838
|
+
let workflow = null;
|
|
839
|
+
let requestedRunId = null;
|
|
840
|
+
if (recipeArg) {
|
|
841
|
+
const { recipe } = loadRecipe(CWD, recipeArg);
|
|
842
|
+
if (!mode && current) mode = current.mode;
|
|
843
|
+
if (startsNewRun && !modeArg && !recipe.compatibleModes.includes(mode)) {
|
|
844
|
+
if (recipe.compatibleModes.length !== 1) {
|
|
845
|
+
throw new Error(`Recipe ${recipe.id} requires an explicit compatible --mode.`);
|
|
846
|
+
}
|
|
847
|
+
mode = recipe.compatibleModes[0];
|
|
848
|
+
}
|
|
849
|
+
const plan = compileRecipe(recipe, { mode });
|
|
850
|
+
if (startsNewRun) {
|
|
851
|
+
requestedRunId = newRunId();
|
|
852
|
+
workflow = createWorkflowBundle(plan, requestedRunId, {
|
|
853
|
+
run: {
|
|
854
|
+
runId: requestedRunId,
|
|
855
|
+
mode,
|
|
856
|
+
state: 'STARTED',
|
|
857
|
+
iteration: 1,
|
|
858
|
+
task
|
|
859
|
+
}
|
|
860
|
+
});
|
|
861
|
+
} else {
|
|
862
|
+
workflow = { plan };
|
|
863
|
+
}
|
|
864
|
+
}
|
|
806
865
|
if (mode) assertModeAllowed(CWD, mode);
|
|
807
|
-
runResult = createOrResumeRun(CWD, {
|
|
866
|
+
runResult = createOrResumeRun(CWD, {
|
|
867
|
+
task,
|
|
868
|
+
forceNew,
|
|
869
|
+
mode,
|
|
870
|
+
workflow,
|
|
871
|
+
...(requestedRunId ? { runId: requestedRunId } : {})
|
|
872
|
+
});
|
|
808
873
|
assertBudgetAvailable(CWD, { runId: runResult.run.runId });
|
|
809
874
|
} catch (err) {
|
|
810
875
|
log.error(err.message);
|
|
@@ -813,6 +878,14 @@ function handleRun() {
|
|
|
813
878
|
console.log(`- Run: ${runResult.run.runId} (${runResult.resumed ? 'resumed' : 'created'})`);
|
|
814
879
|
console.log(`- State: ${runResult.run.state}, iteration ${runResult.run.iteration}`);
|
|
815
880
|
console.log(`- Mode: ${runResult.run.mode || RUN_MODES.ASSISTED}`);
|
|
881
|
+
if (runResult.run.workflow) {
|
|
882
|
+
const runtime = workflowStatus(CWD, { runId: runResult.run.runId });
|
|
883
|
+
const ready = runtime.plan.nodes
|
|
884
|
+
.filter((node) => runtime.state.nodes[node.id].status === 'READY')
|
|
885
|
+
.map((node) => node.id);
|
|
886
|
+
console.log(`- Recipe: ${runResult.run.workflow.recipeId} (${runResult.run.workflow.graphHash})`);
|
|
887
|
+
console.log(`- Ready nodes: ${ready.join(', ') || 'none'}`);
|
|
888
|
+
}
|
|
816
889
|
|
|
817
890
|
const grok = detectGrokHost();
|
|
818
891
|
|
|
@@ -964,13 +1037,21 @@ function handleBudget() {
|
|
|
964
1037
|
const action = process.argv[3] || 'status';
|
|
965
1038
|
const json = process.argv.includes('--json');
|
|
966
1039
|
const runId = argValue('--run');
|
|
1040
|
+
const nodeId = argValue('--node');
|
|
967
1041
|
try {
|
|
968
1042
|
let result;
|
|
969
1043
|
if (action === 'status') {
|
|
970
|
-
result = budgetStatus(CWD, {
|
|
1044
|
+
result = budgetStatus(CWD, {
|
|
1045
|
+
runId,
|
|
1046
|
+
nodeId,
|
|
1047
|
+
estimatedTokens: argValue('--estimate') == null
|
|
1048
|
+
? 0
|
|
1049
|
+
: parseNonNegativeIntegerArg('--estimate', argValue('--estimate'))
|
|
1050
|
+
});
|
|
971
1051
|
} else if (action === 'record') {
|
|
972
1052
|
result = recordTokenUsage(CWD, {
|
|
973
1053
|
runId,
|
|
1054
|
+
nodeId,
|
|
974
1055
|
inputTokens: parseNonNegativeIntegerArg('--input', argValue('--input')),
|
|
975
1056
|
outputTokens: parseNonNegativeIntegerArg('--output', argValue('--output')),
|
|
976
1057
|
model: argValue('--model')
|
|
@@ -1020,7 +1101,11 @@ function handleGate() {
|
|
|
1020
1101
|
const runId = argValue('--run');
|
|
1021
1102
|
const json = process.argv.includes('--json');
|
|
1022
1103
|
try {
|
|
1023
|
-
const
|
|
1104
|
+
const target = runId ? loadRun(CWD, runId) : getCurrentRun(CWD);
|
|
1105
|
+
if (!target) throw new Error('No current run. Start one with `ai-engineering-loop run`.');
|
|
1106
|
+
const run = target.workflow
|
|
1107
|
+
? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
|
|
1108
|
+
: applyGate(CWD, gate, { runId: target.runId });
|
|
1024
1109
|
if (json) {
|
|
1025
1110
|
console.log(JSON.stringify({
|
|
1026
1111
|
ok: true,
|
|
@@ -1050,6 +1135,78 @@ function handleGate() {
|
|
|
1050
1135
|
}
|
|
1051
1136
|
}
|
|
1052
1137
|
|
|
1138
|
+
function handleNode() {
|
|
1139
|
+
const action = process.argv[3] || 'status';
|
|
1140
|
+
const nodeId = process.argv[4];
|
|
1141
|
+
const runId = argValue('--run');
|
|
1142
|
+
const json = process.argv.includes('--json');
|
|
1143
|
+
try {
|
|
1144
|
+
if (action === 'status') {
|
|
1145
|
+
const workflow = workflowStatus(CWD, { runId });
|
|
1146
|
+
const result = {
|
|
1147
|
+
ok: true,
|
|
1148
|
+
runId: workflow.run.runId,
|
|
1149
|
+
recipe: workflow.plan.recipe,
|
|
1150
|
+
graphHash: workflow.plan.graphHash,
|
|
1151
|
+
nodes: workflow.plan.nodes.map((node) => ({
|
|
1152
|
+
id: node.id,
|
|
1153
|
+
type: node.type,
|
|
1154
|
+
order: node.order,
|
|
1155
|
+
...workflow.state.nodes[node.id]
|
|
1156
|
+
}))
|
|
1157
|
+
};
|
|
1158
|
+
if (json) console.log(JSON.stringify(result));
|
|
1159
|
+
else {
|
|
1160
|
+
console.log(`Workflow: ${workflow.plan.recipe.id} (${workflow.plan.graphHash})`);
|
|
1161
|
+
for (const node of result.nodes) {
|
|
1162
|
+
console.log(`${String(node.order).padStart(2)} ${node.id}: ${node.status}`);
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
1165
|
+
return;
|
|
1166
|
+
}
|
|
1167
|
+
if (!nodeId || nodeId.startsWith('-')) throw new Error(`node ${action} requires a node id`);
|
|
1168
|
+
let workflow;
|
|
1169
|
+
if (action === 'start') {
|
|
1170
|
+
workflow = startWorkflowNode(CWD, nodeId, { runId });
|
|
1171
|
+
} else if (action === 'complete') {
|
|
1172
|
+
workflow = completeWorkflowNode(CWD, nodeId, { runId, artifact: argValue('--artifact') });
|
|
1173
|
+
} else if (action === 'fail') {
|
|
1174
|
+
workflow = failWorkflowNode(CWD, nodeId, {
|
|
1175
|
+
runId,
|
|
1176
|
+
reason: argValue('--reason') || 'node execution failed'
|
|
1177
|
+
});
|
|
1178
|
+
} else if (action === 'retry') {
|
|
1179
|
+
workflow = retryWorkflowNode(CWD, nodeId, { runId });
|
|
1180
|
+
} else if (action === 'approve') {
|
|
1181
|
+
if (!process.argv.includes('--yes')) {
|
|
1182
|
+
throw new Error('Approval requires explicit --yes confirmation');
|
|
1183
|
+
}
|
|
1184
|
+
workflow = approveWorkflowNode(CWD, nodeId, {
|
|
1185
|
+
runId,
|
|
1186
|
+
approvedBy: argValue('--by') || 'human'
|
|
1187
|
+
});
|
|
1188
|
+
} else {
|
|
1189
|
+
throw new Error(`Unknown node action: ${action}`);
|
|
1190
|
+
}
|
|
1191
|
+
const node = workflow.state.nodes[nodeId];
|
|
1192
|
+
if (json) console.log(JSON.stringify({ ok: true, nodeId, ...node }));
|
|
1193
|
+
else log.success(`✓ Node ${nodeId}: ${node.status}`);
|
|
1194
|
+
} catch (err) {
|
|
1195
|
+
if (json) {
|
|
1196
|
+
console.log(JSON.stringify({
|
|
1197
|
+
ok: false,
|
|
1198
|
+
code: err.code || 'NODE_FAILED',
|
|
1199
|
+
error: err.message,
|
|
1200
|
+
details: err.details || []
|
|
1201
|
+
}));
|
|
1202
|
+
} else {
|
|
1203
|
+
log.error(err.message);
|
|
1204
|
+
for (const detail of err.details || []) console.error(`- ${detail}`);
|
|
1205
|
+
}
|
|
1206
|
+
process.exit(1);
|
|
1207
|
+
}
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1053
1210
|
function commandFiles(startIndex, optionsWithValues = []) {
|
|
1054
1211
|
const files = [];
|
|
1055
1212
|
for (let index = startIndex; index < process.argv.length; index++) {
|
|
@@ -1180,6 +1337,119 @@ function handleDoctor() {
|
|
|
1180
1337
|
if (!result.ok) process.exit(1);
|
|
1181
1338
|
}
|
|
1182
1339
|
|
|
1340
|
+
function handleRecipe() {
|
|
1341
|
+
const action = process.argv[3] || 'list';
|
|
1342
|
+
const id = process.argv[4];
|
|
1343
|
+
const mode = argValue('--mode');
|
|
1344
|
+
const json = process.argv.includes('--json');
|
|
1345
|
+
try {
|
|
1346
|
+
if (action === 'catalog') {
|
|
1347
|
+
const result = { ok: true, nodeTypes: recipeCatalog() };
|
|
1348
|
+
console.log(JSON.stringify(result, null, json ? 0 : 2));
|
|
1349
|
+
return;
|
|
1350
|
+
}
|
|
1351
|
+
if (action === 'clone' || action === 'create') {
|
|
1352
|
+
const sourceId = action === 'clone' ? id : (argValue('--from') || 'default');
|
|
1353
|
+
const targetId = action === 'clone' ? process.argv[5] : id;
|
|
1354
|
+
if (!sourceId || !targetId || targetId.startsWith('-')) {
|
|
1355
|
+
throw new Error(`recipe ${action} requires ${action === 'clone' ? '<source> <target>' : '<id> [--from <preset>]'}`);
|
|
1356
|
+
}
|
|
1357
|
+
const result = cloneRecipe(CWD, sourceId, targetId, { description: argValue('--description') });
|
|
1358
|
+
const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
|
|
1359
|
+
console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
|
|
1360
|
+
`Created ${targetId} from ${sourceId} at ${relativePath}\nSource hash: ${result.sourceHash}`);
|
|
1361
|
+
return;
|
|
1362
|
+
}
|
|
1363
|
+
if (action === 'install') {
|
|
1364
|
+
if (!id || id.startsWith('-')) throw new Error('recipe install requires a candidate path');
|
|
1365
|
+
const result = installRecipe(CWD, id, { replace: process.argv.includes('--replace') });
|
|
1366
|
+
const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
|
|
1367
|
+
console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
|
|
1368
|
+
`Installed ${result.recipe.id} v${result.recipe.version}\nSource hash: ${result.sourceHash}`);
|
|
1369
|
+
return;
|
|
1370
|
+
}
|
|
1371
|
+
if (action === 'diff') {
|
|
1372
|
+
const rightId = process.argv[5];
|
|
1373
|
+
if (!id || !rightId) throw new Error('recipe diff requires <left> <right>');
|
|
1374
|
+
const result = diffRecipes(CWD, id, rightId);
|
|
1375
|
+
console.log(JSON.stringify({ ok: true, ...result }, null, json ? 0 : 2));
|
|
1376
|
+
return;
|
|
1377
|
+
}
|
|
1378
|
+
if (action === 'inspect') {
|
|
1379
|
+
if (!id || id.startsWith('-')) throw new Error('recipe inspect requires an id');
|
|
1380
|
+
console.log(JSON.stringify({ ok: true, ...inspectRecipe(CWD, id) }, null, json ? 0 : 2));
|
|
1381
|
+
return;
|
|
1382
|
+
}
|
|
1383
|
+
if (action === 'list') {
|
|
1384
|
+
const recipes = listRecipes(CWD).map((entry) => {
|
|
1385
|
+
const { recipe } = loadRecipe(CWD, entry.id);
|
|
1386
|
+
return {
|
|
1387
|
+
...entry,
|
|
1388
|
+
description: recipe.description,
|
|
1389
|
+
compatibleModes: recipe.compatibleModes
|
|
1390
|
+
};
|
|
1391
|
+
});
|
|
1392
|
+
if (json) console.log(JSON.stringify({ ok: true, recipes }));
|
|
1393
|
+
else {
|
|
1394
|
+
console.log('Workflow recipes:');
|
|
1395
|
+
for (const recipe of recipes) {
|
|
1396
|
+
console.log(`- ${recipe.id} [${recipe.source}] ${recipe.compatibleModes.join(', ')}`);
|
|
1397
|
+
console.log(` ${recipe.description}`);
|
|
1398
|
+
}
|
|
1399
|
+
}
|
|
1400
|
+
return;
|
|
1401
|
+
}
|
|
1402
|
+
|
|
1403
|
+
if (!['show', 'validate', 'explain', 'graph', 'simulate'].includes(action)) {
|
|
1404
|
+
throw Object.assign(new Error(`Unknown recipe action: ${action}`), { code: 'UNKNOWN_RECIPE_ACTION' });
|
|
1405
|
+
}
|
|
1406
|
+
if (!id || id.startsWith('-')) {
|
|
1407
|
+
throw Object.assign(new Error(`recipe ${action} requires an id`), { code: 'RECIPE_ID_REQUIRED' });
|
|
1408
|
+
}
|
|
1409
|
+
const loaded = loadRecipe(CWD, id);
|
|
1410
|
+
if (action === 'show') {
|
|
1411
|
+
console.log(JSON.stringify(loaded.recipe, null, json ? 0 : 2));
|
|
1412
|
+
return;
|
|
1413
|
+
}
|
|
1414
|
+
if (action === 'validate') {
|
|
1415
|
+
const validation = validateRecipe(loaded.recipe, mode ? { mode } : {});
|
|
1416
|
+
const result = { ok: validation.valid, id, source: loaded.source, ...validation };
|
|
1417
|
+
if (json) console.log(JSON.stringify(result));
|
|
1418
|
+
else {
|
|
1419
|
+
console.log(`Recipe ${id}: ${validation.valid ? 'VALID' : 'INVALID'}`);
|
|
1420
|
+
for (const warning of validation.warnings) console.log(`! ${warning}`);
|
|
1421
|
+
for (const error of validation.errors) console.log(`✗ ${error}`);
|
|
1422
|
+
}
|
|
1423
|
+
if (!validation.valid) process.exit(1);
|
|
1424
|
+
return;
|
|
1425
|
+
}
|
|
1426
|
+
|
|
1427
|
+
const plan = compileRecipe(loaded.recipe, mode ? { mode } : {});
|
|
1428
|
+
if (action === 'explain') {
|
|
1429
|
+
console.log(json ? JSON.stringify({ ok: true, source: loaded.source, plan }) : explainPlan(plan));
|
|
1430
|
+
} else if (action === 'graph') {
|
|
1431
|
+
const mermaid = mermaidPlan(plan);
|
|
1432
|
+
console.log(json ? JSON.stringify({ ok: true, graphHash: plan.graphHash, mermaid }) : mermaid);
|
|
1433
|
+
} else {
|
|
1434
|
+
const simulation = simulatePlan(plan);
|
|
1435
|
+
console.log(JSON.stringify({ ok: true, ...simulation }, null, json ? 0 : 2));
|
|
1436
|
+
}
|
|
1437
|
+
} catch (err) {
|
|
1438
|
+
if (json) {
|
|
1439
|
+
console.log(JSON.stringify({
|
|
1440
|
+
ok: false,
|
|
1441
|
+
code: err.code || 'RECIPE_FAILED',
|
|
1442
|
+
error: err.message,
|
|
1443
|
+
details: err.details || []
|
|
1444
|
+
}));
|
|
1445
|
+
} else {
|
|
1446
|
+
log.error(err.message);
|
|
1447
|
+
for (const detail of err.details || []) console.error(`- ${detail}`);
|
|
1448
|
+
}
|
|
1449
|
+
process.exit(1);
|
|
1450
|
+
}
|
|
1451
|
+
}
|
|
1452
|
+
|
|
1183
1453
|
// Help Menu
|
|
1184
1454
|
function printHelp() {
|
|
1185
1455
|
console.log(`
|
|
@@ -1196,6 +1466,7 @@ Commands:
|
|
|
1196
1466
|
run [task] Start or resume a stateful engineering run, sync hosts, and instruct the agent
|
|
1197
1467
|
--new start a new run even when another run is active
|
|
1198
1468
|
--mode report-only|assisted|unattended
|
|
1469
|
+
--recipe <id> bind an immutable compiled workflow plan
|
|
1199
1470
|
state Inspect the current run ledger
|
|
1200
1471
|
--run <id> target a non-current run
|
|
1201
1472
|
--json print the complete machine-readable ledger
|
|
@@ -1203,14 +1474,21 @@ Commands:
|
|
|
1203
1474
|
goal | report | maker | verification | review | judge | delivery
|
|
1204
1475
|
--run <id> target a non-current run
|
|
1205
1476
|
--json print machine-readable gate output
|
|
1477
|
+
node Operate custom nodes in a recipe-bound run
|
|
1478
|
+
status [--run <id>] [--json]
|
|
1479
|
+
start <id> [--run <id>] [--json]
|
|
1480
|
+
complete <id> [--artifact <repository-relative-path>] [--json]
|
|
1481
|
+
fail <id> [--reason <text>] [--json]
|
|
1482
|
+
retry <id> [--json]
|
|
1483
|
+
approve <id> --yes [--by <name>] [--json]
|
|
1206
1484
|
policy Inspect or update fail-closed runtime controls
|
|
1207
1485
|
show [--json]
|
|
1208
1486
|
set [--default-mode <mode>] [--allow-unattended true|false]
|
|
1209
1487
|
[--require-sandbox true|false]
|
|
1210
1488
|
[--per-run-token-limit <n>] [--daily-token-limit <n>]
|
|
1211
1489
|
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>]
|
|
1490
|
+
status [--run <id>] [--node <id>] [--estimate <n>] [--json]
|
|
1491
|
+
record --input <n> --output <n> --model <id> [--run <id>] [--node <id>]
|
|
1214
1492
|
pause | resume
|
|
1215
1493
|
sandbox Isolate Maker changes in a locked disposable Git worktree
|
|
1216
1494
|
create | capture | abort | status [--run <id>] [--json]
|
|
@@ -1227,6 +1505,17 @@ Commands:
|
|
|
1227
1505
|
--json print machine-readable reasons
|
|
1228
1506
|
doctor Check runtime, schemas, host assets, package contents, and eval catalog
|
|
1229
1507
|
--json print machine-readable diagnostics
|
|
1508
|
+
recipe Inspect and compile declarative workflow recipes (does not execute nodes)
|
|
1509
|
+
list [--json]
|
|
1510
|
+
catalog [--json]
|
|
1511
|
+
create <id> [--from <preset>] [--description <text>] [--json]
|
|
1512
|
+
clone <source> <target> [--description <text>] [--json]
|
|
1513
|
+
install <path> [--replace] [--json]
|
|
1514
|
+
inspect <id> [--json]
|
|
1515
|
+
diff <left> <right> [--json]
|
|
1516
|
+
show <id> [--json]
|
|
1517
|
+
validate <id> [--mode <mode>] [--json]
|
|
1518
|
+
explain | graph | simulate <id> [--mode <mode>] [--json]
|
|
1230
1519
|
sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
1231
1520
|
(only hosts that already exist; DOT skills only if already installed)
|
|
1232
1521
|
--dry-run print the plan without writing
|
|
@@ -1267,6 +1556,9 @@ switch (command) {
|
|
|
1267
1556
|
case 'gate':
|
|
1268
1557
|
handleGate();
|
|
1269
1558
|
break;
|
|
1559
|
+
case 'node':
|
|
1560
|
+
handleNode();
|
|
1561
|
+
break;
|
|
1270
1562
|
case 'policy':
|
|
1271
1563
|
handlePolicy();
|
|
1272
1564
|
break;
|
|
@@ -1288,6 +1580,9 @@ switch (command) {
|
|
|
1288
1580
|
case 'doctor':
|
|
1289
1581
|
handleDoctor();
|
|
1290
1582
|
break;
|
|
1583
|
+
case 'recipe':
|
|
1584
|
+
handleRecipe();
|
|
1585
|
+
break;
|
|
1291
1586
|
case 'sync-hosts':
|
|
1292
1587
|
handleSyncHosts();
|
|
1293
1588
|
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.
|