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
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Declarative Workflow Recipes
|
|
2
|
+
|
|
3
|
+
Workflow recipes describe a directed acyclic graph of engineering stages in JSON. They are an additive authoring layer over the existing AI Engineering Loop: `recipe` commands provide deterministic validation and inspection, while `run --recipe` opts into the controlled runtime. Runs without a recipe keep their established behavior.
|
|
4
|
+
|
|
5
|
+
This separation is deliberate. A visual editor or an AI agent may eventually author the JSON, but the compiler—not the authoring interface—owns safety invariants.
|
|
6
|
+
|
|
7
|
+
## Sources and precedence
|
|
8
|
+
|
|
9
|
+
Recipes are loaded from two locations:
|
|
10
|
+
|
|
11
|
+
1. Package presets in `recipes/*.json`
|
|
12
|
+
2. Project recipes in `.ai-engineering-loop/recipes/*.json`
|
|
13
|
+
|
|
14
|
+
Built-in IDs are reserved and cannot be shadowed by a project file. Recipe IDs and node IDs use lowercase letters, numbers, and hyphens. Recipe files and the project recipe directory must be regular filesystem entries; symlinks are rejected.
|
|
15
|
+
|
|
16
|
+
The package includes:
|
|
17
|
+
|
|
18
|
+
| Recipe | Purpose | Modes |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `default` | Existing production safety loop | `ASSISTED`, `UNATTENDED` |
|
|
21
|
+
| `audit` | Read-only structured analysis | `REPORT_ONLY` |
|
|
22
|
+
| `bugfix` | Root-cause-first repair | `ASSISTED`, `UNATTENDED` |
|
|
23
|
+
| `docs-light` | Bounded documentation change | `ASSISTED`, `UNATTENDED` |
|
|
24
|
+
| `high-risk` | Blast-radius analysis and pre-mutation approval | `ASSISTED`, `UNATTENDED` |
|
|
25
|
+
| `refactor` | Behavior-baseline-first refactor | `ASSISTED`, `UNATTENDED` |
|
|
26
|
+
|
|
27
|
+
## Safety backbone
|
|
28
|
+
|
|
29
|
+
The graph compiler fails closed.
|
|
30
|
+
|
|
31
|
+
- `REPORT_ONLY` requires `goal-contract → ... → report` and rejects every mutation or remote-side-effect node.
|
|
32
|
+
- `ASSISTED` and `UNATTENDED` require the ordered backbone `goal-contract → maker → verification → devil-advocate → judge → delivery`.
|
|
33
|
+
- `ASSISTED` additionally requires human approval after Judge and before delivery.
|
|
34
|
+
- Required safety nodes cannot be conditional.
|
|
35
|
+
- `report` and `delivery` are graph terminals. Every node must lead to one terminal.
|
|
36
|
+
- Cycles, duplicate singleton safety nodes, missing dependencies, unknown node types, and incompatible modes are invalid.
|
|
37
|
+
|
|
38
|
+
Dependencies may include additional nodes between required stages. A custom analysis node before `maker`, for example, does not weaken the mandatory backbone.
|
|
39
|
+
|
|
40
|
+
## Node catalog
|
|
41
|
+
|
|
42
|
+
| Type | Intended use | Model | Repository mutation | Remote side effect |
|
|
43
|
+
| --- | --- | ---: | ---: | ---: |
|
|
44
|
+
| `goal-contract` | Acceptance contract | No | No | No |
|
|
45
|
+
| `agent` | Bounded structured analysis | Yes | No | No |
|
|
46
|
+
| `command` | Trusted repository executable | No | No | No |
|
|
47
|
+
| `condition` | Structured branch predicate | No | No | No |
|
|
48
|
+
| `approval` | Human checkpoint | No | No | No |
|
|
49
|
+
| `artifact-check` | Deterministic artifact assertion | No | No | No |
|
|
50
|
+
| `maker` | Implementation | Yes | Yes | No |
|
|
51
|
+
| `verification` | Evidence collection | No | No | No |
|
|
52
|
+
| `devil-advocate` | Adversarial review | Yes | No | No |
|
|
53
|
+
| `judge` | Independent verdict | Yes | No | No |
|
|
54
|
+
| `report` | Read-only terminal | No | No | No |
|
|
55
|
+
| `delivery` | Delivery terminal | No | No | Yes |
|
|
56
|
+
|
|
57
|
+
An `agent` node must declare a role, bounded `maxFiles` and `maxTokens`, and a repository-relative output schema. A `command` node must use a bare executable name, an argument array, a bounded timeout, and expected exit codes. Shells and general-purpose interpreters are rejected; command nodes are for trusted repository tools, not arbitrary script text.
|
|
58
|
+
|
|
59
|
+
## Authoring example
|
|
60
|
+
|
|
61
|
+
Project recipe:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"schemaVersion": 1,
|
|
66
|
+
"id": "api-bugfix",
|
|
67
|
+
"version": 1,
|
|
68
|
+
"description": "Analyze an API regression before entering the standard repair loop.",
|
|
69
|
+
"compatibleModes": ["ASSISTED"],
|
|
70
|
+
"nodes": [
|
|
71
|
+
{ "id": "goal", "type": "goal-contract" },
|
|
72
|
+
{
|
|
73
|
+
"id": "api-analysis",
|
|
74
|
+
"type": "agent",
|
|
75
|
+
"dependsOn": ["goal"],
|
|
76
|
+
"role": "api-regression-analyst",
|
|
77
|
+
"context": { "maxFiles": 25, "maxTokens": 8000 },
|
|
78
|
+
"output": {
|
|
79
|
+
"artifact": "api-analysis",
|
|
80
|
+
"schema": "schemas/report.schema.json"
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
{ "id": "maker", "type": "maker", "dependsOn": ["api-analysis"] },
|
|
84
|
+
{ "id": "verification", "type": "verification", "dependsOn": ["maker"] },
|
|
85
|
+
{ "id": "review", "type": "devil-advocate", "dependsOn": ["verification"] },
|
|
86
|
+
{ "id": "judge", "type": "judge", "dependsOn": ["review"] },
|
|
87
|
+
{
|
|
88
|
+
"id": "approval",
|
|
89
|
+
"type": "approval",
|
|
90
|
+
"dependsOn": ["judge"],
|
|
91
|
+
"message": "Approve delivery."
|
|
92
|
+
},
|
|
93
|
+
{ "id": "delivery", "type": "delivery", "dependsOn": ["approval"] }
|
|
94
|
+
]
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Validate and inspect it:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
ai-engineering-loop recipe validate api-bugfix --mode assisted
|
|
102
|
+
ai-engineering-loop recipe explain api-bugfix --mode assisted
|
|
103
|
+
ai-engineering-loop recipe graph api-bugfix --mode assisted
|
|
104
|
+
ai-engineering-loop recipe simulate api-bugfix --mode assisted
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`simulate` compiles the graph and reports capability counts. It never calls a model, mutates the repository, executes a command, or performs delivery.
|
|
108
|
+
|
|
109
|
+
## AI-assisted authoring protocol
|
|
110
|
+
|
|
111
|
+
Until a visual editor exists, an AI agent can safely act as the recipe builder:
|
|
112
|
+
|
|
113
|
+
1. Ask the user for the outcome, allowed run modes, required checkpoints, context limits, and delivery risk.
|
|
114
|
+
2. Start from the closest built-in preset rather than a blank graph.
|
|
115
|
+
3. Add only nodes that change the workflow meaningfully.
|
|
116
|
+
4. Write the candidate to `.ai-engineering-loop/recipes/<id>.json`.
|
|
117
|
+
5. Run `recipe validate`, `recipe explain`, `recipe graph`, and `recipe simulate`.
|
|
118
|
+
6. Present the explanation, graph hash, warnings, and capability counts for human confirmation.
|
|
119
|
+
7. Do not claim execution from validation or simulation. Execution is proven only by a recipe-bound run and its validated event chain.
|
|
120
|
+
|
|
121
|
+
Machine consumers should use `--json`. The compiled plan includes a canonical source hash and graph hash so execution and audit logs bind to the exact graph reviewed by the user. Runtime behavior is specified in `core/controlled-workflow-runtime.md`.
|
|
122
|
+
|
|
123
|
+
The CLI supports safe scaffolding and installation:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
ai-engineering-loop recipe create api-bugfix --from bugfix
|
|
127
|
+
ai-engineering-loop recipe inspect api-bugfix --json
|
|
128
|
+
ai-engineering-loop recipe diff bugfix api-bugfix
|
|
129
|
+
ai-engineering-loop recipe install candidate-v2.json --replace
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Creation never overwrites an existing recipe. Installation validates before writing, reserves built-in IDs, requires `--replace` plus a strictly higher version, and stores the previous document under `.ai-engineering-loop/recipes/.history/<id>/`. Candidate paths and recipe stores reject filesystem escape and symlink traversal.
|
|
133
|
+
|
|
134
|
+
## Schemas
|
|
135
|
+
|
|
136
|
+
- `schemas/recipe.schema.json`: top-level authoring document
|
|
137
|
+
- `schemas/node-definition.schema.json`: node shape and type catalog
|
|
138
|
+
- `schemas/compiled-plan.schema.json`: deterministic compiler output
|
|
139
|
+
|
|
140
|
+
Semantic safety checks are stricter than JSON Schema and are enforced by `recipe validate` and the compiler.
|
package/lib/budget.js
CHANGED
|
@@ -69,6 +69,9 @@ function readUsageFile(filePath) {
|
|
|
69
69
|
throw new Error('totalTokens does not equal inputTokens + outputTokens');
|
|
70
70
|
}
|
|
71
71
|
validateModel(entry.model);
|
|
72
|
+
if (entry.nodeId != null && !/^[a-z][a-z0-9-]{0,63}$/.test(entry.nodeId)) {
|
|
73
|
+
throw new Error('nodeId is invalid');
|
|
74
|
+
}
|
|
72
75
|
if (typeof entry.recordedAt !== 'string' || Number.isNaN(Date.parse(entry.recordedAt))) {
|
|
73
76
|
throw new Error('recordedAt is invalid');
|
|
74
77
|
}
|
|
@@ -107,7 +110,7 @@ function resolveRun(rootDir, runId) {
|
|
|
107
110
|
return current;
|
|
108
111
|
}
|
|
109
112
|
|
|
110
|
-
function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() } = {}) {
|
|
113
|
+
function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new Date() } = {}) {
|
|
111
114
|
validateTokenCount('estimatedTokens', estimatedTokens);
|
|
112
115
|
const run = resolveRun(rootDir, runId);
|
|
113
116
|
const policy = loadPolicy(rootDir);
|
|
@@ -120,6 +123,30 @@ function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() }
|
|
|
120
123
|
const projectedToday = spentToday + estimatedTokens;
|
|
121
124
|
const projectedThisRun = spentThisRun + estimatedTokens;
|
|
122
125
|
const reasons = [];
|
|
126
|
+
let node = null;
|
|
127
|
+
let spentThisNode = 0;
|
|
128
|
+
let nodeTokenLimit = null;
|
|
129
|
+
if (nodeId) {
|
|
130
|
+
const { workflowStatus, NODE_STATES } = require('./workflow-runtime.js');
|
|
131
|
+
const workflow = workflowStatus(rootDir, { runId: run.runId });
|
|
132
|
+
node = workflow.plan.nodes.find((candidate) => candidate.id === nodeId);
|
|
133
|
+
if (!node) throw usageError(`Unknown workflow node: ${nodeId}`);
|
|
134
|
+
if (!node.capabilities.modelRequired) reasons.push(`node ${nodeId} does not permit model usage`);
|
|
135
|
+
const status = workflow.state.nodes[nodeId].status;
|
|
136
|
+
if (![NODE_STATES.READY, NODE_STATES.RUNNING].includes(status)) {
|
|
137
|
+
reasons.push(`node ${nodeId} is ${status}, not READY`);
|
|
138
|
+
}
|
|
139
|
+
nodeTokenLimit = node.context?.maxTokens || null;
|
|
140
|
+
spentThisNode = allEntries
|
|
141
|
+
.filter((entry) => entry.runId === run.runId && entry.nodeId === nodeId)
|
|
142
|
+
.reduce((sum, entry) => sum + entry.totalTokens, 0);
|
|
143
|
+
if (nodeTokenLimit != null && spentThisNode + estimatedTokens > nodeTokenLimit) {
|
|
144
|
+
reasons.push(`node ${nodeId} token limit would be exceeded`);
|
|
145
|
+
}
|
|
146
|
+
if (nodeTokenLimit != null && estimatedTokens === 0 && spentThisNode >= nodeTokenLimit) {
|
|
147
|
+
reasons.push(`node ${nodeId} token limit is exhausted`);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
123
150
|
if (policy.killSwitch) reasons.push('kill switch is active');
|
|
124
151
|
if (projectedThisRun > policy.perRunTokenLimit) reasons.push('per-run token limit would be exceeded');
|
|
125
152
|
if (projectedToday > policy.dailyTokenLimit) reasons.push('daily token limit would be exceeded');
|
|
@@ -143,7 +170,13 @@ function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() }
|
|
|
143
170
|
spentToday,
|
|
144
171
|
dailyTokenLimit: policy.dailyTokenLimit,
|
|
145
172
|
remainingToday: Math.max(0, policy.dailyTokenLimit - spentToday),
|
|
146
|
-
estimatedTokens
|
|
173
|
+
estimatedTokens,
|
|
174
|
+
...(node ? {
|
|
175
|
+
nodeId,
|
|
176
|
+
spentThisNode,
|
|
177
|
+
nodeTokenLimit,
|
|
178
|
+
remainingThisNode: nodeTokenLimit == null ? null : Math.max(0, nodeTokenLimit - spentThisNode)
|
|
179
|
+
} : {})
|
|
147
180
|
};
|
|
148
181
|
}
|
|
149
182
|
|
|
@@ -182,7 +215,7 @@ function appendPrivateLine(rootDir, filePath, line) {
|
|
|
182
215
|
|
|
183
216
|
function recordTokenUsage(
|
|
184
217
|
rootDir,
|
|
185
|
-
{ runId, inputTokens, outputTokens, model, now = new Date() } = {}
|
|
218
|
+
{ runId, nodeId, inputTokens, outputTokens, model, now = new Date() } = {}
|
|
186
219
|
) {
|
|
187
220
|
const run = resolveRun(rootDir, runId);
|
|
188
221
|
validateTokenCount('inputTokens', inputTokens);
|
|
@@ -197,10 +230,15 @@ function recordTokenUsage(
|
|
|
197
230
|
outputTokens,
|
|
198
231
|
totalTokens,
|
|
199
232
|
model: normalizedModel,
|
|
233
|
+
...(nodeId ? { nodeId } : {}),
|
|
200
234
|
recordedAt: now.toISOString()
|
|
201
235
|
};
|
|
236
|
+
if (nodeId) budgetStatus(rootDir, { runId: run.runId, nodeId, now });
|
|
202
237
|
appendPrivateLine(rootDir, usagePath(rootDir, now), `${JSON.stringify(entry)}\n`);
|
|
203
|
-
return {
|
|
238
|
+
return {
|
|
239
|
+
entry,
|
|
240
|
+
status: budgetStatus(rootDir, { runId: run.runId, nodeId, now })
|
|
241
|
+
};
|
|
204
242
|
}
|
|
205
243
|
|
|
206
244
|
function setKillSwitch(rootDir, active) {
|
package/lib/doctor.js
CHANGED
|
@@ -4,6 +4,7 @@ const fs = require('fs');
|
|
|
4
4
|
const path = require('path');
|
|
5
5
|
const { loadEvaluationCases } = require('./evaluation.js');
|
|
6
6
|
const { auditPackage } = require('./package-audit.js');
|
|
7
|
+
const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
|
|
7
8
|
|
|
8
9
|
const REQUIRED_HOST_ASSETS = [
|
|
9
10
|
'.claude/skills/ai-engineering-loop/SKILL.md',
|
|
@@ -24,7 +25,12 @@ const REQUIRED_SCHEMAS = [
|
|
|
24
25
|
'finding-ledger.schema.json',
|
|
25
26
|
'verdict.schema.json',
|
|
26
27
|
'delivery.schema.json',
|
|
27
|
-
'report.schema.json'
|
|
28
|
+
'report.schema.json',
|
|
29
|
+
'recipe.schema.json',
|
|
30
|
+
'node-definition.schema.json',
|
|
31
|
+
'compiled-plan.schema.json',
|
|
32
|
+
'workflow-state.schema.json',
|
|
33
|
+
'workflow-event.schema.json'
|
|
28
34
|
];
|
|
29
35
|
|
|
30
36
|
function check(id, passed, detail) {
|
|
@@ -66,6 +72,23 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
|
|
|
66
72
|
schemaErrors.length ? schemaErrors.join('; ') : `${REQUIRED_SCHEMAS.length} schemas parse`
|
|
67
73
|
));
|
|
68
74
|
|
|
75
|
+
try {
|
|
76
|
+
const recipes = listRecipes(rootDir).filter(({ source }) => source === 'builtin');
|
|
77
|
+
const recipeErrors = recipes.flatMap(({ id }) => {
|
|
78
|
+
const { recipe } = loadRecipe(rootDir, id);
|
|
79
|
+
return recipe.compatibleModes.flatMap((mode) => (
|
|
80
|
+
validateRecipe(recipe, { mode }).errors.map((error) => `${id} (${mode}): ${error}`)
|
|
81
|
+
));
|
|
82
|
+
});
|
|
83
|
+
checks.push(check(
|
|
84
|
+
'workflow-recipes',
|
|
85
|
+
recipes.length > 0 && recipeErrors.length === 0,
|
|
86
|
+
recipeErrors.length ? recipeErrors.join('; ') : `${recipes.length} built-in recipes validate`
|
|
87
|
+
));
|
|
88
|
+
} catch (cause) {
|
|
89
|
+
checks.push(check('workflow-recipes', false, cause.message));
|
|
90
|
+
}
|
|
91
|
+
|
|
69
92
|
try {
|
|
70
93
|
const fixtures = loadEvaluationCases(path.join(rootDir, 'evals', 'cases'));
|
|
71
94
|
checks.push(check('evaluation-catalog', fixtures.length === 20, `${fixtures.length} valid cases; required 20`));
|
|
@@ -74,7 +97,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
|
|
|
74
97
|
}
|
|
75
98
|
|
|
76
99
|
const packageFiles = new Set(pkg.files || []);
|
|
77
|
-
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'schemas/', 'evals/'];
|
|
100
|
+
const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
|
|
78
101
|
const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
|
|
79
102
|
checks.push(check(
|
|
80
103
|
'package-assets',
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const NODE_TYPES = Object.freeze({
|
|
4
|
+
'goal-contract': Object.freeze({
|
|
5
|
+
label: 'Goal Contract',
|
|
6
|
+
category: 'safety',
|
|
7
|
+
builtIn: true,
|
|
8
|
+
mutation: false,
|
|
9
|
+
sideEffect: false,
|
|
10
|
+
modelRequired: false,
|
|
11
|
+
legacyGate: 'goal'
|
|
12
|
+
}),
|
|
13
|
+
agent: Object.freeze({
|
|
14
|
+
label: 'Agent Analysis',
|
|
15
|
+
category: 'custom',
|
|
16
|
+
builtIn: false,
|
|
17
|
+
mutation: false,
|
|
18
|
+
sideEffect: false,
|
|
19
|
+
modelRequired: true
|
|
20
|
+
}),
|
|
21
|
+
command: Object.freeze({
|
|
22
|
+
label: 'Deterministic Command',
|
|
23
|
+
category: 'custom',
|
|
24
|
+
builtIn: false,
|
|
25
|
+
mutation: true,
|
|
26
|
+
sideEffect: false,
|
|
27
|
+
modelRequired: false
|
|
28
|
+
}),
|
|
29
|
+
condition: Object.freeze({
|
|
30
|
+
label: 'Condition',
|
|
31
|
+
category: 'control',
|
|
32
|
+
builtIn: false,
|
|
33
|
+
mutation: false,
|
|
34
|
+
sideEffect: false,
|
|
35
|
+
modelRequired: false
|
|
36
|
+
}),
|
|
37
|
+
approval: Object.freeze({
|
|
38
|
+
label: 'Human Approval',
|
|
39
|
+
category: 'safety',
|
|
40
|
+
builtIn: false,
|
|
41
|
+
mutation: false,
|
|
42
|
+
sideEffect: false,
|
|
43
|
+
modelRequired: false
|
|
44
|
+
}),
|
|
45
|
+
'artifact-check': Object.freeze({
|
|
46
|
+
label: 'Artifact Check',
|
|
47
|
+
category: 'control',
|
|
48
|
+
builtIn: false,
|
|
49
|
+
mutation: false,
|
|
50
|
+
sideEffect: false,
|
|
51
|
+
modelRequired: false
|
|
52
|
+
}),
|
|
53
|
+
maker: Object.freeze({
|
|
54
|
+
label: 'Maker',
|
|
55
|
+
category: 'safety',
|
|
56
|
+
builtIn: true,
|
|
57
|
+
mutation: true,
|
|
58
|
+
sideEffect: false,
|
|
59
|
+
modelRequired: true,
|
|
60
|
+
legacyGate: 'maker'
|
|
61
|
+
}),
|
|
62
|
+
verification: Object.freeze({
|
|
63
|
+
label: 'Verification',
|
|
64
|
+
category: 'safety',
|
|
65
|
+
builtIn: true,
|
|
66
|
+
mutation: false,
|
|
67
|
+
sideEffect: false,
|
|
68
|
+
modelRequired: false,
|
|
69
|
+
legacyGate: 'verification'
|
|
70
|
+
}),
|
|
71
|
+
'devil-advocate': Object.freeze({
|
|
72
|
+
label: "Devil's Advocate",
|
|
73
|
+
category: 'safety',
|
|
74
|
+
builtIn: true,
|
|
75
|
+
mutation: false,
|
|
76
|
+
sideEffect: false,
|
|
77
|
+
modelRequired: true,
|
|
78
|
+
legacyGate: 'review'
|
|
79
|
+
}),
|
|
80
|
+
judge: Object.freeze({
|
|
81
|
+
label: 'Judge',
|
|
82
|
+
category: 'safety',
|
|
83
|
+
builtIn: true,
|
|
84
|
+
mutation: false,
|
|
85
|
+
sideEffect: false,
|
|
86
|
+
modelRequired: true,
|
|
87
|
+
legacyGate: 'judge'
|
|
88
|
+
}),
|
|
89
|
+
report: Object.freeze({
|
|
90
|
+
label: 'Report',
|
|
91
|
+
category: 'terminal',
|
|
92
|
+
builtIn: true,
|
|
93
|
+
mutation: false,
|
|
94
|
+
sideEffect: false,
|
|
95
|
+
modelRequired: false,
|
|
96
|
+
legacyGate: 'report'
|
|
97
|
+
}),
|
|
98
|
+
delivery: Object.freeze({
|
|
99
|
+
label: 'Delivery',
|
|
100
|
+
category: 'terminal',
|
|
101
|
+
builtIn: true,
|
|
102
|
+
mutation: false,
|
|
103
|
+
sideEffect: true,
|
|
104
|
+
modelRequired: false,
|
|
105
|
+
legacyGate: 'delivery'
|
|
106
|
+
})
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
const CONDITION_OPERATORS = Object.freeze([
|
|
110
|
+
'equals',
|
|
111
|
+
'notEquals',
|
|
112
|
+
'contains',
|
|
113
|
+
'matchesAny',
|
|
114
|
+
'exists',
|
|
115
|
+
'isEmpty',
|
|
116
|
+
'greaterThan',
|
|
117
|
+
'lessThan'
|
|
118
|
+
]);
|
|
119
|
+
|
|
120
|
+
const CONDITION_FIELDS = Object.freeze([
|
|
121
|
+
'run.mode',
|
|
122
|
+
'run.state',
|
|
123
|
+
'run.iteration',
|
|
124
|
+
'run.task'
|
|
125
|
+
]);
|
|
126
|
+
|
|
127
|
+
const FORBIDDEN_COMMANDS = new Set([
|
|
128
|
+
'sh',
|
|
129
|
+
'bash',
|
|
130
|
+
'zsh',
|
|
131
|
+
'fish',
|
|
132
|
+
'cmd',
|
|
133
|
+
'cmd.exe',
|
|
134
|
+
'powershell',
|
|
135
|
+
'powershell.exe',
|
|
136
|
+
'pwsh',
|
|
137
|
+
'node',
|
|
138
|
+
'node.exe',
|
|
139
|
+
'python',
|
|
140
|
+
'python3',
|
|
141
|
+
'ruby',
|
|
142
|
+
'perl'
|
|
143
|
+
]);
|
|
144
|
+
|
|
145
|
+
function getNodeType(type) {
|
|
146
|
+
return NODE_TYPES[type] || null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
module.exports = {
|
|
150
|
+
NODE_TYPES,
|
|
151
|
+
CONDITION_OPERATORS,
|
|
152
|
+
CONDITION_FIELDS,
|
|
153
|
+
FORBIDDEN_COMMANDS,
|
|
154
|
+
getNodeType
|
|
155
|
+
};
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const crypto = require('crypto');
|
|
6
|
+
const { NODE_TYPES } = require('./node-registry.js');
|
|
7
|
+
const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
|
|
8
|
+
const {
|
|
9
|
+
RECIPE_ID,
|
|
10
|
+
canonicalJson,
|
|
11
|
+
compileRecipe,
|
|
12
|
+
listRecipes,
|
|
13
|
+
loadRecipe,
|
|
14
|
+
sha256,
|
|
15
|
+
validateRecipe
|
|
16
|
+
} = require('./recipe.js');
|
|
17
|
+
|
|
18
|
+
function builderError(message, code = 'RECIPE_BUILDER_FAILED', details = []) {
|
|
19
|
+
const error = new Error(message);
|
|
20
|
+
error.code = code;
|
|
21
|
+
error.details = details;
|
|
22
|
+
return error;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function recipeDirectory(rootDir) {
|
|
26
|
+
return path.join(rootDir, '.ai-engineering-loop', 'recipes');
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function assertSafeDirectory(rootDir, directory) {
|
|
30
|
+
const relative = path.relative(rootDir, directory);
|
|
31
|
+
let current = rootDir;
|
|
32
|
+
for (const segment of relative.split(path.sep).filter(Boolean)) {
|
|
33
|
+
current = path.join(current, segment);
|
|
34
|
+
if (!fs.existsSync(current)) continue;
|
|
35
|
+
const stat = fs.lstatSync(current);
|
|
36
|
+
if (stat.isSymbolicLink() || !stat.isDirectory()) {
|
|
37
|
+
throw builderError(`${path.relative(rootDir, current)} must be a regular directory`, 'UNSAFE_RECIPE_PATH');
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function atomicWriteJson(filePath, value, { replace = false } = {}) {
|
|
43
|
+
if (!replace && fs.existsSync(filePath)) {
|
|
44
|
+
throw builderError(`Recipe already exists: ${path.basename(filePath, '.json')}`, 'RECIPE_EXISTS');
|
|
45
|
+
}
|
|
46
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
47
|
+
const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
|
|
48
|
+
try {
|
|
49
|
+
fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
|
|
50
|
+
fs.renameSync(temporary, filePath);
|
|
51
|
+
} finally {
|
|
52
|
+
try { fs.unlinkSync(temporary); } catch {}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function assertProjectId(rootDir, id) {
|
|
57
|
+
if (!RECIPE_ID.test(String(id || ''))) throw builderError(`Invalid recipe id: ${id || '(empty)'}`, 'INVALID_RECIPE');
|
|
58
|
+
if (listRecipes(rootDir).some((entry) => entry.id === id && entry.source === 'builtin')) {
|
|
59
|
+
throw builderError(`Built-in recipe id is reserved: ${id}`, 'RESERVED_RECIPE_ID');
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function validateCandidate(recipe) {
|
|
64
|
+
const result = validateRecipe(recipe);
|
|
65
|
+
if (!result.valid) throw builderError(`Recipe ${recipe?.id || '(unknown)'} is invalid`, 'INVALID_RECIPE', result.errors);
|
|
66
|
+
return result;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function cloneRecipe(rootDir, sourceId, targetId, { description } = {}) {
|
|
70
|
+
assertProjectId(rootDir, targetId);
|
|
71
|
+
const source = loadRecipe(rootDir, sourceId).recipe;
|
|
72
|
+
const candidate = {
|
|
73
|
+
...JSON.parse(JSON.stringify(source)),
|
|
74
|
+
id: targetId,
|
|
75
|
+
version: 1,
|
|
76
|
+
description: description || `Project workflow based on ${sourceId}.`
|
|
77
|
+
};
|
|
78
|
+
validateCandidate(candidate);
|
|
79
|
+
ensurePrivateRuntimeIgnores(rootDir);
|
|
80
|
+
const directory = recipeDirectory(rootDir);
|
|
81
|
+
assertSafeDirectory(rootDir, directory);
|
|
82
|
+
const filePath = path.join(directory, `${targetId}.json`);
|
|
83
|
+
atomicWriteJson(filePath, candidate);
|
|
84
|
+
return { recipe: candidate, path: filePath, sourceHash: sha256(candidate) };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function readCandidate(rootDir, candidatePath) {
|
|
88
|
+
const absolute = path.resolve(rootDir, candidatePath);
|
|
89
|
+
if (path.relative(rootDir, absolute).split(path.sep).includes('..')) {
|
|
90
|
+
throw builderError('Candidate must stay inside the repository', 'UNSAFE_RECIPE_PATH');
|
|
91
|
+
}
|
|
92
|
+
assertSafeDirectory(rootDir, path.dirname(absolute));
|
|
93
|
+
const realRoot = fs.realpathSync(rootDir);
|
|
94
|
+
const realFile = fs.realpathSync(absolute);
|
|
95
|
+
if (!realFile.startsWith(`${realRoot}${path.sep}`)) {
|
|
96
|
+
throw builderError('Candidate must stay inside the repository', 'UNSAFE_RECIPE_PATH');
|
|
97
|
+
}
|
|
98
|
+
const stat = fs.lstatSync(absolute);
|
|
99
|
+
if (stat.isSymbolicLink() || !stat.isFile()) {
|
|
100
|
+
throw builderError('Candidate must be a regular file', 'UNSAFE_RECIPE_PATH');
|
|
101
|
+
}
|
|
102
|
+
try {
|
|
103
|
+
return JSON.parse(fs.readFileSync(absolute, 'utf8'));
|
|
104
|
+
} catch (cause) {
|
|
105
|
+
throw builderError(`Candidate JSON is invalid: ${cause.message}`, 'INVALID_RECIPE_JSON');
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function installRecipe(rootDir, candidatePath, { replace = false } = {}) {
|
|
110
|
+
const candidate = readCandidate(rootDir, candidatePath);
|
|
111
|
+
assertProjectId(rootDir, candidate.id);
|
|
112
|
+
validateCandidate(candidate);
|
|
113
|
+
ensurePrivateRuntimeIgnores(rootDir);
|
|
114
|
+
const directory = recipeDirectory(rootDir);
|
|
115
|
+
assertSafeDirectory(rootDir, directory);
|
|
116
|
+
const destination = path.join(directory, `${candidate.id}.json`);
|
|
117
|
+
let previous = null;
|
|
118
|
+
if (fs.existsSync(destination)) {
|
|
119
|
+
previous = loadRecipe(rootDir, candidate.id).recipe;
|
|
120
|
+
if (!replace) throw builderError(`Recipe already exists: ${candidate.id}`, 'RECIPE_EXISTS');
|
|
121
|
+
if (candidate.version <= previous.version) {
|
|
122
|
+
throw builderError(
|
|
123
|
+
`Replacement version must be greater than ${previous.version}`,
|
|
124
|
+
'RECIPE_VERSION_NOT_INCREMENTED'
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
const history = path.join(directory, '.history', candidate.id, `${previous.version}.json`);
|
|
128
|
+
assertSafeDirectory(rootDir, path.dirname(history));
|
|
129
|
+
if (!fs.existsSync(history)) atomicWriteJson(history, previous);
|
|
130
|
+
}
|
|
131
|
+
atomicWriteJson(destination, candidate, { replace: Boolean(previous) });
|
|
132
|
+
return {
|
|
133
|
+
recipe: candidate,
|
|
134
|
+
path: destination,
|
|
135
|
+
sourceHash: sha256(candidate),
|
|
136
|
+
replacedVersion: previous?.version || null
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function recipeCatalog() {
|
|
141
|
+
return Object.entries(NODE_TYPES).map(([type, definition]) => ({
|
|
142
|
+
type,
|
|
143
|
+
label: definition.label,
|
|
144
|
+
category: definition.category,
|
|
145
|
+
capabilities: {
|
|
146
|
+
repositoryMutation: definition.mutation,
|
|
147
|
+
remoteSideEffect: definition.sideEffect,
|
|
148
|
+
modelRequired: definition.modelRequired
|
|
149
|
+
},
|
|
150
|
+
executable: type !== 'command'
|
|
151
|
+
}));
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function inspectRecipe(rootDir, id) {
|
|
155
|
+
const loaded = loadRecipe(rootDir, id);
|
|
156
|
+
const plans = loaded.recipe.compatibleModes.map((mode) => compileRecipe(loaded.recipe, { mode }));
|
|
157
|
+
return {
|
|
158
|
+
id,
|
|
159
|
+
source: loaded.source,
|
|
160
|
+
version: loaded.recipe.version,
|
|
161
|
+
description: loaded.recipe.description,
|
|
162
|
+
sourceHash: sha256(loaded.recipe),
|
|
163
|
+
modes: plans.map((plan) => ({
|
|
164
|
+
mode: plan.mode,
|
|
165
|
+
graphHash: plan.graphHash,
|
|
166
|
+
nodes: plan.nodes.length,
|
|
167
|
+
modelCalls: plan.nodes.filter((node) => node.capabilities.modelRequired).length,
|
|
168
|
+
mutations: plan.nodes.filter((node) => node.capabilities.repositoryMutation).length,
|
|
169
|
+
remoteSideEffects: plan.nodes.filter((node) => node.capabilities.remoteSideEffect).length,
|
|
170
|
+
approvals: plan.nodes.filter((node) => node.type === 'approval').length,
|
|
171
|
+
declaredTokenCeiling: plan.nodes.reduce((sum, node) => sum + (node.context?.maxTokens || 0), 0)
|
|
172
|
+
}))
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
function diffRecipes(rootDir, leftId, rightId) {
|
|
177
|
+
const left = loadRecipe(rootDir, leftId).recipe;
|
|
178
|
+
const right = loadRecipe(rootDir, rightId).recipe;
|
|
179
|
+
const leftNodes = new Map(left.nodes.map((node) => [node.id, node]));
|
|
180
|
+
const rightNodes = new Map(right.nodes.map((node) => [node.id, node]));
|
|
181
|
+
return {
|
|
182
|
+
left: { id: left.id, version: left.version, sourceHash: sha256(left) },
|
|
183
|
+
right: { id: right.id, version: right.version, sourceHash: sha256(right) },
|
|
184
|
+
metadataChanged: left.description !== right.description ||
|
|
185
|
+
canonicalJson(left.compatibleModes) !== canonicalJson(right.compatibleModes),
|
|
186
|
+
added: [...rightNodes.keys()].filter((id) => !leftNodes.has(id)),
|
|
187
|
+
removed: [...leftNodes.keys()].filter((id) => !rightNodes.has(id)),
|
|
188
|
+
changed: [...rightNodes.keys()].filter((id) => (
|
|
189
|
+
leftNodes.has(id) && canonicalJson(leftNodes.get(id)) !== canonicalJson(rightNodes.get(id))
|
|
190
|
+
))
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
module.exports = {
|
|
195
|
+
cloneRecipe,
|
|
196
|
+
installRecipe,
|
|
197
|
+
recipeCatalog,
|
|
198
|
+
inspectRecipe,
|
|
199
|
+
diffRecipes
|
|
200
|
+
};
|