ai-engineering-loop 1.7.0 → 1.8.1
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 +149 -353
- package/bin/ai-engineering-loop.js +2 -2
- package/core/local-workflow-studio.md +28 -7
- package/docs/images/studio-hero.svg +124 -0
- package/lib/gates.js +3 -2
- package/lib/goal-runtime.js +130 -0
- package/lib/recipe-builder.js +27 -1
- package/lib/recipe-graph.js +92 -0
- package/lib/recipe.js +137 -7
- package/lib/run-history.js +193 -0
- package/lib/run-state.js +90 -5
- package/lib/studio-runtime.js +65 -0
- package/lib/studio-server.js +154 -2
- package/lib/workflow-runtime.js +79 -5
- package/package.json +2 -2
- package/schemas/edge-definition.schema.json +13 -0
- package/schemas/node-definition.schema.json +74 -1
- package/schemas/recipe.schema.json +5 -0
- package/studio/app.js +856 -59
- package/studio/index.html +95 -7
- package/studio/styles.css +20 -10
package/lib/recipe.js
CHANGED
|
@@ -11,6 +11,12 @@ const {
|
|
|
11
11
|
FORBIDDEN_COMMANDS,
|
|
12
12
|
getNodeType
|
|
13
13
|
} = require('./node-registry.js');
|
|
14
|
+
const {
|
|
15
|
+
EDGE_ID,
|
|
16
|
+
MAX_EDGES,
|
|
17
|
+
migrateLegacyRecipe,
|
|
18
|
+
withDependencies
|
|
19
|
+
} = require('./recipe-graph.js');
|
|
14
20
|
|
|
15
21
|
const RECIPE_ID = /^[a-z][a-z0-9-]{0,63}$/;
|
|
16
22
|
const NODE_ID = /^[a-z][a-z0-9-]{0,63}$/;
|
|
@@ -66,6 +72,33 @@ function validateCondition(condition, location, errors) {
|
|
|
66
72
|
}
|
|
67
73
|
}
|
|
68
74
|
|
|
75
|
+
function validateRepositorySchemaPath(value, location, errors) {
|
|
76
|
+
if (!String(value || '').trim()) {
|
|
77
|
+
errors.push(`${location} is required`);
|
|
78
|
+
return;
|
|
79
|
+
}
|
|
80
|
+
const schemaPath = String(value).replace(/\\/g, '/');
|
|
81
|
+
if (
|
|
82
|
+
/^(?:https?:|file:)/i.test(schemaPath) ||
|
|
83
|
+
path.isAbsolute(schemaPath) ||
|
|
84
|
+
schemaPath.split('/').includes('..')
|
|
85
|
+
) {
|
|
86
|
+
errors.push(`${location} must be repository-relative`);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function forbiddenAuthorityPaths(value, location, result = []) {
|
|
91
|
+
if (!value || typeof value !== 'object') return result;
|
|
92
|
+
for (const [key, child] of Object.entries(value)) {
|
|
93
|
+
const childLocation = `${location}.${key}`;
|
|
94
|
+
if (/^(?:command|shell|secret|secretValue|environment|filesystem|network)$/i.test(key)) {
|
|
95
|
+
result.push(childLocation);
|
|
96
|
+
}
|
|
97
|
+
forbiddenAuthorityPaths(child, childLocation, result);
|
|
98
|
+
}
|
|
99
|
+
return result;
|
|
100
|
+
}
|
|
101
|
+
|
|
69
102
|
function validateNodeConfiguration(node, index, errors, warnings) {
|
|
70
103
|
const location = `nodes[${index}]`;
|
|
71
104
|
const definition = getNodeType(node.type);
|
|
@@ -79,7 +112,66 @@ function validateNodeConfiguration(node, index, errors, warnings) {
|
|
|
79
112
|
validateCondition(node.expression, `${location}.expression`, errors);
|
|
80
113
|
}
|
|
81
114
|
|
|
82
|
-
if (node.type === 'agent') {
|
|
115
|
+
if (node.type === 'agent' && node.prompt != null) {
|
|
116
|
+
const allowedCapabilities = new Set([
|
|
117
|
+
'repository-read',
|
|
118
|
+
'repository-write',
|
|
119
|
+
'artifact-read',
|
|
120
|
+
'artifact-write',
|
|
121
|
+
'mcp-invoke',
|
|
122
|
+
'network-declared'
|
|
123
|
+
]);
|
|
124
|
+
if (!String(node.displayName || '').trim() || String(node.displayName).length > 120) {
|
|
125
|
+
errors.push(`${location}.displayName must be between 1 and 120 characters`);
|
|
126
|
+
}
|
|
127
|
+
if (!String(node.prompt || '').trim() || String(node.prompt).length > 20_000) {
|
|
128
|
+
errors.push(`${location}.prompt must be between 1 and 20000 characters`);
|
|
129
|
+
}
|
|
130
|
+
if (!Array.isArray(node.capabilityRefs) ||
|
|
131
|
+
node.capabilityRefs.some((ref) => !allowedCapabilities.has(ref))) {
|
|
132
|
+
errors.push(`${location}.capabilityRefs contains unsupported authority`);
|
|
133
|
+
}
|
|
134
|
+
if (!Array.isArray(node.mcpRefs) || node.mcpRefs.some((ref) => !NODE_ID.test(String(ref)))) {
|
|
135
|
+
errors.push(`${location}.mcpRefs must contain declared reference ids`);
|
|
136
|
+
}
|
|
137
|
+
if (!Array.isArray(node.inputArtifacts) ||
|
|
138
|
+
node.inputArtifacts.some((ref) => !NODE_ID.test(String(ref)))) {
|
|
139
|
+
errors.push(`${location}.inputArtifacts must contain artifact reference ids`);
|
|
140
|
+
}
|
|
141
|
+
if (!Array.isArray(node.outputArtifacts) || node.outputArtifacts.length === 0) {
|
|
142
|
+
errors.push(`${location}.outputArtifacts must not be empty`);
|
|
143
|
+
} else {
|
|
144
|
+
node.outputArtifacts.forEach((output, outputIndex) => {
|
|
145
|
+
if (!NODE_ID.test(String(output?.artifact || ''))) {
|
|
146
|
+
errors.push(`${location}.outputArtifacts[${outputIndex}].artifact is invalid`);
|
|
147
|
+
}
|
|
148
|
+
validateRepositorySchemaPath(
|
|
149
|
+
output?.schema,
|
|
150
|
+
`${location}.outputArtifacts[${outputIndex}].schema`,
|
|
151
|
+
errors
|
|
152
|
+
);
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
if (!Number.isSafeInteger(node.tokenLimit) || node.tokenLimit < 1 || node.tokenLimit > 1_000_000) {
|
|
156
|
+
errors.push(`${location}.tokenLimit must be between 1 and 1000000`);
|
|
157
|
+
}
|
|
158
|
+
if (!Number.isSafeInteger(node.timeoutMs) || node.timeoutMs < 1_000 || node.timeoutMs > 30 * 60 * 1_000) {
|
|
159
|
+
errors.push(`${location}.timeoutMs must be between 1000 and 1800000`);
|
|
160
|
+
}
|
|
161
|
+
if (
|
|
162
|
+
!Number.isSafeInteger(node.retry?.maxAttempts) ||
|
|
163
|
+
node.retry.maxAttempts < 1 ||
|
|
164
|
+
node.retry.maxAttempts > 10 ||
|
|
165
|
+
!Number.isSafeInteger(node.retry?.backoffMs) ||
|
|
166
|
+
node.retry.backoffMs < 0 ||
|
|
167
|
+
node.retry.backoffMs > 300_000
|
|
168
|
+
) {
|
|
169
|
+
errors.push(`${location}.retry must define bounded maxAttempts and backoffMs`);
|
|
170
|
+
}
|
|
171
|
+
if (forbiddenAuthorityPaths(node, location).length) {
|
|
172
|
+
errors.push(`${location} cannot persist commands, secret values, or unrestricted authority`);
|
|
173
|
+
}
|
|
174
|
+
} else if (node.type === 'agent') {
|
|
83
175
|
if (!String(node.role || '').trim()) errors.push(`${location}.role is required`);
|
|
84
176
|
if (!node.output || typeof node.output !== 'object') {
|
|
85
177
|
errors.push(`${location}.output artifact contract is required`);
|
|
@@ -238,6 +330,7 @@ function validateRecipe(recipe, { mode } = {}) {
|
|
|
238
330
|
if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) {
|
|
239
331
|
return { valid: false, errors: ['recipe must be a JSON object'], warnings, order: [] };
|
|
240
332
|
}
|
|
333
|
+
recipe = migrateLegacyRecipe(recipe);
|
|
241
334
|
if (recipe.schemaVersion !== 1) errors.push('schemaVersion must be 1');
|
|
242
335
|
if (!RECIPE_ID.test(String(recipe.id || ''))) errors.push('id must match [a-z][a-z0-9-]{0,63}');
|
|
243
336
|
if (!Number.isSafeInteger(recipe.version) || recipe.version <= 0) errors.push('version must be a positive integer');
|
|
@@ -279,20 +372,47 @@ function validateRecipe(recipe, { mode } = {}) {
|
|
|
279
372
|
}
|
|
280
373
|
validateNodeConfiguration(node, index, errors, warnings);
|
|
281
374
|
});
|
|
282
|
-
|
|
375
|
+
if (!Array.isArray(recipe.edges)) {
|
|
376
|
+
errors.push('edges must be an array');
|
|
377
|
+
} else if (recipe.edges.length > MAX_EDGES) {
|
|
378
|
+
errors.push(`edges exceeds the maximum of ${MAX_EDGES}`);
|
|
379
|
+
}
|
|
380
|
+
const edgeIds = new Set();
|
|
381
|
+
const connections = new Set();
|
|
382
|
+
for (const [index, edge] of (recipe.edges || []).entries()) {
|
|
383
|
+
const location = `edges[${index}]`;
|
|
384
|
+
if (!edge || typeof edge !== 'object' || Array.isArray(edge)) {
|
|
385
|
+
errors.push(`${location} must be an object`);
|
|
386
|
+
continue;
|
|
387
|
+
}
|
|
388
|
+
if (!EDGE_ID.test(String(edge.id || ''))) errors.push(`${location}.id is invalid`);
|
|
389
|
+
else if (edgeIds.has(edge.id)) errors.push(`duplicate edge id: ${edge.id}`);
|
|
390
|
+
else edgeIds.add(edge.id);
|
|
391
|
+
const connection = `${edge.from}\0${edge.to}`;
|
|
392
|
+
if (connections.has(connection)) errors.push(`duplicate edge connection: ${edge.from} -> ${edge.to}`);
|
|
393
|
+
else connections.add(connection);
|
|
394
|
+
if (!byId.has(edge.from)) errors.push(`${edge.id || location} references unknown from node ${edge.from}`);
|
|
395
|
+
if (!byId.has(edge.to)) errors.push(`${edge.id || location} references unknown to node ${edge.to}`);
|
|
396
|
+
if (edge.from === edge.to) errors.push(`${edge.id || location} cannot connect a node to itself`);
|
|
397
|
+
}
|
|
398
|
+
recipe = withDependencies(recipe);
|
|
399
|
+
const projectedNodes = recipe.nodes;
|
|
400
|
+
byId.clear();
|
|
401
|
+
for (const node of projectedNodes) byId.set(node.id, node);
|
|
402
|
+
for (const node of projectedNodes) {
|
|
283
403
|
for (const dependency of node.dependsOn || []) {
|
|
284
404
|
if (!byId.has(dependency)) errors.push(`${node.id} depends on unknown node ${dependency}`);
|
|
285
405
|
if (dependency === node.id) errors.push(`${node.id} cannot depend on itself`);
|
|
286
406
|
}
|
|
287
407
|
}
|
|
288
|
-
const order = topologicalOrder(
|
|
289
|
-
const terminals =
|
|
408
|
+
const order = topologicalOrder(projectedNodes, byId, errors);
|
|
409
|
+
const terminals = projectedNodes.filter((node) => ['report', 'delivery'].includes(node.type));
|
|
290
410
|
for (const terminal of terminals) {
|
|
291
|
-
if (
|
|
411
|
+
if (projectedNodes.some((node) => (node.dependsOn || []).includes(terminal.id))) {
|
|
292
412
|
errors.push(`${terminal.type} must be a terminal node`);
|
|
293
413
|
}
|
|
294
414
|
}
|
|
295
|
-
for (const node of
|
|
415
|
+
for (const node of projectedNodes) {
|
|
296
416
|
if (!terminals.some((terminal) => dependsTransitively(byId, terminal.id, node.id))) {
|
|
297
417
|
errors.push(`${node.id} must lead to a report or delivery terminal`);
|
|
298
418
|
}
|
|
@@ -309,6 +429,7 @@ function validateRecipe(recipe, { mode } = {}) {
|
|
|
309
429
|
}
|
|
310
430
|
|
|
311
431
|
function compileRecipe(recipe, { mode } = {}) {
|
|
432
|
+
recipe = withDependencies(recipe);
|
|
312
433
|
const selectedMode = normalizeRunMode(mode || recipe?.compatibleModes?.[0]);
|
|
313
434
|
const validation = validateRecipe(recipe, { mode: selectedMode });
|
|
314
435
|
if (!validation.valid) {
|
|
@@ -318,8 +439,15 @@ function compileRecipe(recipe, { mode } = {}) {
|
|
|
318
439
|
const compiledNodes = validation.order.map((id, index) => {
|
|
319
440
|
const node = byId.get(id);
|
|
320
441
|
const definition = getNodeType(node.type);
|
|
442
|
+
const customAgentRuntime = node.type === 'agent' && node.prompt != null
|
|
443
|
+
? {
|
|
444
|
+
context: { ...(node.context || {}), maxTokens: node.tokenLimit },
|
|
445
|
+
output: node.outputArtifacts[0]
|
|
446
|
+
}
|
|
447
|
+
: {};
|
|
321
448
|
return {
|
|
322
449
|
...canonicalize(node),
|
|
450
|
+
...canonicalize(customAgentRuntime),
|
|
323
451
|
order: index + 1,
|
|
324
452
|
status: (node.dependsOn || []).length === 0 ? 'READY' : 'BLOCKED',
|
|
325
453
|
capabilities: {
|
|
@@ -415,7 +543,7 @@ function loadRecipe(rootDir, id) {
|
|
|
415
543
|
const recipe = readRecipeFile(recipePath(directory, id));
|
|
416
544
|
if (!recipe) throw recipeError(`Recipe not found: ${id}`, [], 'RECIPE_NOT_FOUND');
|
|
417
545
|
if (recipe.id !== id) throw recipeError(`Recipe id must match file name: ${id}`, ['id mismatch']);
|
|
418
|
-
return { recipe, source, path: recipePath(directory, id) };
|
|
546
|
+
return { recipe: migrateLegacyRecipe(recipe), source, path: recipePath(directory, id) };
|
|
419
547
|
}
|
|
420
548
|
|
|
421
549
|
function explainPlan(plan) {
|
|
@@ -481,10 +609,12 @@ module.exports = {
|
|
|
481
609
|
RECIPE_ID,
|
|
482
610
|
NODE_ID,
|
|
483
611
|
MAX_NODES,
|
|
612
|
+
MAX_EDGES,
|
|
484
613
|
BUILTIN_RECIPE_DIR,
|
|
485
614
|
canonicalize,
|
|
486
615
|
canonicalJson,
|
|
487
616
|
sha256,
|
|
617
|
+
migrateLegacyRecipe,
|
|
488
618
|
validateRecipe,
|
|
489
619
|
compileRecipe,
|
|
490
620
|
listRecipes,
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { assertRunId, loadRun, runDisplayMetadata, runsDir } = require('./run-state.js');
|
|
6
|
+
const { redactSecrets } = require('./safe-context.js');
|
|
7
|
+
|
|
8
|
+
const MAX_ARTIFACT_BYTES = 64 * 1024;
|
|
9
|
+
|
|
10
|
+
function historyError(message, code = 'RUN_HISTORY_ERROR') {
|
|
11
|
+
const error = new Error(message);
|
|
12
|
+
error.code = code;
|
|
13
|
+
return error;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function redactedValue(value) {
|
|
17
|
+
return JSON.parse(redactSecrets(JSON.stringify(value)).text);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function regularRunDirectory(rootDir, runId) {
|
|
21
|
+
assertRunId(runId);
|
|
22
|
+
const directory = path.join(runsDir(rootDir), runId);
|
|
23
|
+
let directoryStat;
|
|
24
|
+
let stateStat;
|
|
25
|
+
try {
|
|
26
|
+
directoryStat = fs.lstatSync(directory);
|
|
27
|
+
stateStat = fs.lstatSync(path.join(directory, 'state.json'));
|
|
28
|
+
} catch (cause) {
|
|
29
|
+
throw historyError(`Run ${runId} is unavailable: ${cause.message}`, 'RUN_NOT_FOUND');
|
|
30
|
+
}
|
|
31
|
+
if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory() ||
|
|
32
|
+
stateStat.isSymbolicLink() || !stateStat.isFile()) {
|
|
33
|
+
throw historyError(`Run ${runId} is not a regular persisted run`, 'INVALID_RUN_HISTORY');
|
|
34
|
+
}
|
|
35
|
+
return directory;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function summaryFor(run) {
|
|
39
|
+
const presentation = run.displayName && run.slug
|
|
40
|
+
? { displayName: run.displayName, slug: run.slug, keywords: run.keywords || [] }
|
|
41
|
+
: runDisplayMetadata(run.task);
|
|
42
|
+
return redactedValue({
|
|
43
|
+
runId: run.runId,
|
|
44
|
+
...presentation,
|
|
45
|
+
task: run.task,
|
|
46
|
+
status: run.state,
|
|
47
|
+
mode: run.mode,
|
|
48
|
+
createdAt: run.createdAt,
|
|
49
|
+
updatedAt: run.updatedAt,
|
|
50
|
+
goalVersion: run.goal?.version || null,
|
|
51
|
+
goalFrozen: run.goal?.frozen === true
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function searchableText(rootDir, run) {
|
|
56
|
+
const workflowTerms = run.workflow
|
|
57
|
+
? JSON.stringify(require('./workflow-runtime.js').workflowStatus(rootDir, { runId: run.runId }))
|
|
58
|
+
: '';
|
|
59
|
+
const artifactTerms = run.artifacts ? JSON.stringify(run.artifacts) : '';
|
|
60
|
+
return `${JSON.stringify(summaryFor(run))} ${workflowTerms} ${artifactTerms}`.toLocaleLowerCase('en-US');
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function listRunHistory(rootDir, { query = '', status, mode, from, to } = {}) {
|
|
64
|
+
const directory = runsDir(rootDir);
|
|
65
|
+
if (!fs.existsSync(directory)) return { runs: [], corrupt: [] };
|
|
66
|
+
const needle = String(query || '').trim().toLocaleLowerCase('en-US');
|
|
67
|
+
const runs = [];
|
|
68
|
+
const corrupt = [];
|
|
69
|
+
for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
|
|
70
|
+
if (entry.name === 'current.json' || !entry.isDirectory()) continue;
|
|
71
|
+
try {
|
|
72
|
+
regularRunDirectory(rootDir, entry.name);
|
|
73
|
+
const run = loadRun(rootDir, entry.name);
|
|
74
|
+
if (run.workflow) require('./workflow-runtime.js').workflowStatus(rootDir, { runId: run.runId });
|
|
75
|
+
const created = Date.parse(run.createdAt);
|
|
76
|
+
if (status && run.state !== status) continue;
|
|
77
|
+
if (mode && run.mode !== mode) continue;
|
|
78
|
+
if (from && (!Number.isFinite(created) || created < Date.parse(from))) continue;
|
|
79
|
+
if (to && (!Number.isFinite(created) || created > Date.parse(to))) continue;
|
|
80
|
+
if (needle && !searchableText(rootDir, run).includes(needle)) continue;
|
|
81
|
+
runs.push(summaryFor(run));
|
|
82
|
+
} catch (error) {
|
|
83
|
+
corrupt.push({ runId: entry.name, code: error.code || 'INVALID_RUN_HISTORY', error: error.message });
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
runs.sort((left, right) =>
|
|
87
|
+
String(right.createdAt || '').localeCompare(String(left.createdAt || '')) ||
|
|
88
|
+
left.runId.localeCompare(right.runId)
|
|
89
|
+
);
|
|
90
|
+
corrupt.sort((left, right) => left.runId.localeCompare(right.runId));
|
|
91
|
+
return { runs, corrupt };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function runHistoryDetail(rootDir, runId) {
|
|
95
|
+
const directory = regularRunDirectory(rootDir, runId);
|
|
96
|
+
const run = loadRun(rootDir, runId);
|
|
97
|
+
let workflow = null;
|
|
98
|
+
let decisions = [];
|
|
99
|
+
const decisionsPath = path.join(directory, 'decisions.json');
|
|
100
|
+
if (fs.existsSync(decisionsPath)) {
|
|
101
|
+
const stat = fs.lstatSync(decisionsPath);
|
|
102
|
+
if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_ARTIFACT_BYTES) {
|
|
103
|
+
throw historyError('Run decisions must be a bounded regular file', 'INVALID_RUN_HISTORY');
|
|
104
|
+
}
|
|
105
|
+
try {
|
|
106
|
+
decisions = JSON.parse(fs.readFileSync(decisionsPath, 'utf8'));
|
|
107
|
+
} catch (cause) {
|
|
108
|
+
throw historyError(`Run decisions are invalid: ${cause.message}`, 'INVALID_RUN_HISTORY');
|
|
109
|
+
}
|
|
110
|
+
if (!Array.isArray(decisions)) throw historyError('Run decisions must be an array', 'INVALID_RUN_HISTORY');
|
|
111
|
+
}
|
|
112
|
+
let events = [];
|
|
113
|
+
if (run.workflow) {
|
|
114
|
+
workflow = require('./workflow-runtime.js').workflowStatus(rootDir, { runId });
|
|
115
|
+
events = workflow.events.map(({ initialNodes, changes, ...event }) => ({
|
|
116
|
+
...event,
|
|
117
|
+
changedNodes: (changes || []).map((change) => change.nodeId)
|
|
118
|
+
}));
|
|
119
|
+
}
|
|
120
|
+
const nodeArtifacts = Object.fromEntries(
|
|
121
|
+
Object.entries(workflow?.state?.nodes || {})
|
|
122
|
+
.filter(([, node]) => node.artifact?.path)
|
|
123
|
+
.map(([nodeId, node]) => [`node:${nodeId}`, node.artifact])
|
|
124
|
+
);
|
|
125
|
+
const artifacts = { ...(run.artifacts || {}), ...nodeArtifacts };
|
|
126
|
+
const artifactValues = Object.values(artifacts);
|
|
127
|
+
return redactedValue({
|
|
128
|
+
...summaryFor(run),
|
|
129
|
+
history: run.history || [],
|
|
130
|
+
events,
|
|
131
|
+
decisions,
|
|
132
|
+
artifacts,
|
|
133
|
+
evidence: {
|
|
134
|
+
present: artifactValues.some((artifact) =>
|
|
135
|
+
artifact && typeof artifact === 'object' &&
|
|
136
|
+
/(?:evidence|verification|findings|verdict)/i.test(String(artifact.path || ''))
|
|
137
|
+
)
|
|
138
|
+
},
|
|
139
|
+
workflow: run.workflow || null
|
|
140
|
+
});
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function inspectRunArtifact(rootDir, runId, relativePath, { maxBytes = MAX_ARTIFACT_BYTES } = {}) {
|
|
144
|
+
const directory = regularRunDirectory(rootDir, runId);
|
|
145
|
+
if (!relativePath || path.isAbsolute(relativePath)) {
|
|
146
|
+
throw historyError('Artifact path must be relative to its run', 'UNSAFE_HISTORY_PATH');
|
|
147
|
+
}
|
|
148
|
+
const normalized = String(relativePath).replace(/\\/g, '/');
|
|
149
|
+
const descriptorPrefix = `.ai-engineering-loop/runs/${runId}/`;
|
|
150
|
+
const runRelativePath = normalized.startsWith(descriptorPrefix)
|
|
151
|
+
? normalized.slice(descriptorPrefix.length)
|
|
152
|
+
: normalized;
|
|
153
|
+
const requested = path.resolve(directory, runRelativePath);
|
|
154
|
+
const relative = path.relative(directory, requested);
|
|
155
|
+
if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
|
|
156
|
+
throw historyError('Artifact path escapes its owning run', 'UNSAFE_HISTORY_PATH');
|
|
157
|
+
}
|
|
158
|
+
let stat;
|
|
159
|
+
let real;
|
|
160
|
+
try {
|
|
161
|
+
stat = fs.lstatSync(requested);
|
|
162
|
+
real = fs.realpathSync(requested);
|
|
163
|
+
} catch (cause) {
|
|
164
|
+
throw historyError(`Artifact is unavailable: ${cause.message}`, 'HISTORY_ARTIFACT_NOT_FOUND');
|
|
165
|
+
}
|
|
166
|
+
const realDirectory = fs.realpathSync(directory);
|
|
167
|
+
const realRelative = path.relative(realDirectory, real);
|
|
168
|
+
if (stat.isSymbolicLink() || !stat.isFile() ||
|
|
169
|
+
realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
|
|
170
|
+
throw historyError('Artifact must be a regular file inside its owning run', 'UNSAFE_HISTORY_PATH');
|
|
171
|
+
}
|
|
172
|
+
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_ARTIFACT_BYTES) {
|
|
173
|
+
throw historyError(`Artifact limit must be between 1 and ${MAX_ARTIFACT_BYTES} bytes`, 'INVALID_HISTORY_LIMIT');
|
|
174
|
+
}
|
|
175
|
+
if (stat.size > maxBytes) {
|
|
176
|
+
throw historyError(`Artifact exceeds the ${maxBytes} byte inspection limit`, 'HISTORY_ARTIFACT_TOO_LARGE');
|
|
177
|
+
}
|
|
178
|
+
const redacted = redactSecrets(fs.readFileSync(real, 'utf8'));
|
|
179
|
+
return {
|
|
180
|
+
runId,
|
|
181
|
+
path: relative.split(path.sep).join('/'),
|
|
182
|
+
size: stat.size,
|
|
183
|
+
content: redacted.text,
|
|
184
|
+
redactions: redacted.categories
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
module.exports = {
|
|
189
|
+
MAX_ARTIFACT_BYTES,
|
|
190
|
+
listRunHistory,
|
|
191
|
+
runHistoryDetail,
|
|
192
|
+
inspectRunArtifact
|
|
193
|
+
};
|
package/lib/run-state.js
CHANGED
|
@@ -25,7 +25,7 @@ const RUN_MODES = Object.freeze({
|
|
|
25
25
|
|
|
26
26
|
const ALLOWED_TRANSITIONS = Object.freeze({
|
|
27
27
|
STARTED: ['GOAL_FROZEN'],
|
|
28
|
-
GOAL_FROZEN: ['REPORTED', 'MAKER_COMPLETE'],
|
|
28
|
+
GOAL_FROZEN: ['STARTED', 'REPORTED', 'MAKER_COMPLETE'],
|
|
29
29
|
REPORTED: [],
|
|
30
30
|
MAKER_COMPLETE: ['VERIFIED'],
|
|
31
31
|
VERIFIED: ['REVIEWED'],
|
|
@@ -98,6 +98,32 @@ function newRunId(now = new Date()) {
|
|
|
98
98
|
return `${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
|
|
99
99
|
}
|
|
100
100
|
|
|
101
|
+
function runDisplayMetadata(task, displayName) {
|
|
102
|
+
const normalizedTask = String(task || '').trim().replace(/\s+/g, ' ');
|
|
103
|
+
const safeProposal = String(displayName || '').trim().replace(/\s+/g, ' ');
|
|
104
|
+
const usableProposal = safeProposal &&
|
|
105
|
+
safeProposal.length <= 100 &&
|
|
106
|
+
!/[\u0000-\u001f/\\]/.test(safeProposal);
|
|
107
|
+
const fallbackWords = normalizedTask
|
|
108
|
+
.replace(/[^\p{L}\p{N}\s-]/gu, ' ')
|
|
109
|
+
.trim()
|
|
110
|
+
.split(/\s+/)
|
|
111
|
+
.filter(Boolean)
|
|
112
|
+
.slice(0, 7);
|
|
113
|
+
const fallback = fallbackWords.join(' ') || 'Untitled run';
|
|
114
|
+
const name = usableProposal ? safeProposal : fallback;
|
|
115
|
+
const slug = name.toLocaleLowerCase('en-US')
|
|
116
|
+
.normalize('NFKD')
|
|
117
|
+
.replace(/[^\p{L}\p{N}]+/gu, '-')
|
|
118
|
+
.replace(/^-+|-+$/g, '')
|
|
119
|
+
.slice(0, 80) || 'untitled-run';
|
|
120
|
+
const keywords = [...new Set(
|
|
121
|
+
normalizedTask.toLocaleLowerCase('en-US')
|
|
122
|
+
.match(/[\p{L}\p{N}]{2,}/gu) || []
|
|
123
|
+
)].slice(0, 20);
|
|
124
|
+
return { displayName: name, slug, keywords };
|
|
125
|
+
}
|
|
126
|
+
|
|
101
127
|
function runStatePath(rootDir, runId) {
|
|
102
128
|
return path.join(runsDir(rootDir), assertRunId(runId), 'state.json');
|
|
103
129
|
}
|
|
@@ -167,7 +193,14 @@ function normalizeRunMode(mode) {
|
|
|
167
193
|
|
|
168
194
|
function createRun(
|
|
169
195
|
rootDir,
|
|
170
|
-
{
|
|
196
|
+
{
|
|
197
|
+
task = '',
|
|
198
|
+
runId = newRunId(),
|
|
199
|
+
mode = RUN_MODES.ASSISTED,
|
|
200
|
+
now = new Date(),
|
|
201
|
+
workflow = null,
|
|
202
|
+
displayName = ''
|
|
203
|
+
} = {}
|
|
171
204
|
) {
|
|
172
205
|
assertRunId(runId);
|
|
173
206
|
const statePath = runStatePath(rootDir, runId);
|
|
@@ -178,6 +211,8 @@ function createRun(
|
|
|
178
211
|
}
|
|
179
212
|
|
|
180
213
|
const timestamp = now.toISOString();
|
|
214
|
+
const normalizedTask = String(task || '').trim();
|
|
215
|
+
const presentation = runDisplayMetadata(normalizedTask, displayName);
|
|
181
216
|
const workflowMetadata = writeWorkflowBundle(rootDir, runId, workflow);
|
|
182
217
|
const state = {
|
|
183
218
|
schemaVersion: 1,
|
|
@@ -185,7 +220,8 @@ function createRun(
|
|
|
185
220
|
state: RUN_STATES.STARTED,
|
|
186
221
|
mode: normalizeRunMode(mode),
|
|
187
222
|
iteration: 1,
|
|
188
|
-
task:
|
|
223
|
+
task: normalizedTask,
|
|
224
|
+
...presentation,
|
|
189
225
|
startedRevision: getGitRevision(rootDir),
|
|
190
226
|
createdAt: timestamp,
|
|
191
227
|
updatedAt: timestamp,
|
|
@@ -244,11 +280,55 @@ function createOrResumeRun(
|
|
|
244
280
|
};
|
|
245
281
|
}
|
|
246
282
|
|
|
283
|
+
function updateRunDisplayName(rootDir, runId, displayName, { actor = 'human', now = new Date() } = {}) {
|
|
284
|
+
const run = loadRun(rootDir, runId);
|
|
285
|
+
const proposed = String(displayName || '').trim().replace(/\s+/g, ' ');
|
|
286
|
+
if (!proposed || proposed.length > 100 || /[\u0000-\u001f/\\]/.test(proposed)) {
|
|
287
|
+
const err = new Error('Display Name must be 1-100 characters without control characters or path separators');
|
|
288
|
+
err.code = 'INVALID_RUN_DISPLAY_NAME';
|
|
289
|
+
throw err;
|
|
290
|
+
}
|
|
291
|
+
if (!/^[A-Za-z0-9@._-]{1,64}$/.test(String(actor))) {
|
|
292
|
+
const err = new Error('Display Name actor must be a short account identifier');
|
|
293
|
+
err.code = 'INVALID_RUN_ACTOR';
|
|
294
|
+
throw err;
|
|
295
|
+
}
|
|
296
|
+
const timestamp = now.toISOString();
|
|
297
|
+
const presentation = runDisplayMetadata(run.task, proposed);
|
|
298
|
+
const next = {
|
|
299
|
+
...run,
|
|
300
|
+
...presentation,
|
|
301
|
+
runId: run.runId,
|
|
302
|
+
updatedAt: timestamp,
|
|
303
|
+
history: [
|
|
304
|
+
...(run.history || []),
|
|
305
|
+
{
|
|
306
|
+
from: run.state,
|
|
307
|
+
to: run.state,
|
|
308
|
+
gate: 'run-metadata',
|
|
309
|
+
at: timestamp,
|
|
310
|
+
actor: String(actor),
|
|
311
|
+
displayName: presentation.displayName
|
|
312
|
+
}
|
|
313
|
+
]
|
|
314
|
+
};
|
|
315
|
+
atomicWriteJson(runStatePath(rootDir, runId), next);
|
|
316
|
+
return next;
|
|
317
|
+
}
|
|
318
|
+
|
|
247
319
|
function transitionRun(
|
|
248
320
|
rootDir,
|
|
249
321
|
runId,
|
|
250
322
|
to,
|
|
251
|
-
{
|
|
323
|
+
{
|
|
324
|
+
gate,
|
|
325
|
+
artifacts = {},
|
|
326
|
+
reason = null,
|
|
327
|
+
incrementIteration = false,
|
|
328
|
+
statePatch = {},
|
|
329
|
+
historyMetadata = {},
|
|
330
|
+
now = new Date()
|
|
331
|
+
} = {}
|
|
252
332
|
) {
|
|
253
333
|
const run = loadRun(rootDir, runId);
|
|
254
334
|
if (!RUN_STATES[to]) {
|
|
@@ -265,6 +345,8 @@ function transitionRun(
|
|
|
265
345
|
const timestamp = now.toISOString();
|
|
266
346
|
const next = {
|
|
267
347
|
...run,
|
|
348
|
+
...statePatch,
|
|
349
|
+
runId: run.runId,
|
|
268
350
|
state: to,
|
|
269
351
|
iteration: incrementIteration ? run.iteration + 1 : run.iteration,
|
|
270
352
|
updatedAt: timestamp,
|
|
@@ -276,7 +358,8 @@ function transitionRun(
|
|
|
276
358
|
to,
|
|
277
359
|
gate: gate || 'unspecified',
|
|
278
360
|
at: timestamp,
|
|
279
|
-
...(reason ? { reason } : {})
|
|
361
|
+
...(reason ? { reason } : {}),
|
|
362
|
+
...historyMetadata
|
|
280
363
|
}
|
|
281
364
|
]
|
|
282
365
|
};
|
|
@@ -298,10 +381,12 @@ module.exports = {
|
|
|
298
381
|
atomicWriteJson,
|
|
299
382
|
getGitRevision,
|
|
300
383
|
newRunId,
|
|
384
|
+
runDisplayMetadata,
|
|
301
385
|
normalizeRunMode,
|
|
302
386
|
loadRun,
|
|
303
387
|
getCurrentRun,
|
|
304
388
|
createRun,
|
|
305
389
|
createOrResumeRun,
|
|
390
|
+
updateRunDisplayName,
|
|
306
391
|
transitionRun
|
|
307
392
|
};
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { compileRecipe, loadRecipe } = require('./recipe.js');
|
|
4
|
+
const {
|
|
5
|
+
RUN_MODES,
|
|
6
|
+
TERMINAL_STATES,
|
|
7
|
+
createRun,
|
|
8
|
+
getCurrentRun,
|
|
9
|
+
newRunId,
|
|
10
|
+
normalizeRunMode
|
|
11
|
+
} = require('./run-state.js');
|
|
12
|
+
const { assertModeAllowed } = require('./runtime-policy.js');
|
|
13
|
+
const { createWorkflowBundle, startWorkflowExecution } = require('./workflow-runtime.js');
|
|
14
|
+
|
|
15
|
+
function studioRuntimeError(message, code) {
|
|
16
|
+
const error = new Error(message);
|
|
17
|
+
error.code = code;
|
|
18
|
+
return error;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function createStudioRun(
|
|
22
|
+
rootDir,
|
|
23
|
+
{ task, recipeId, mode = RUN_MODES.ASSISTED, displayName = '', now = new Date() } = {}
|
|
24
|
+
) {
|
|
25
|
+
const normalizedTask = String(task || '').trim();
|
|
26
|
+
if (!normalizedTask || normalizedTask.length > 2000) {
|
|
27
|
+
throw studioRuntimeError('Task must be 1-2000 characters', 'INVALID_RUN_TASK');
|
|
28
|
+
}
|
|
29
|
+
const normalizedMode = normalizeRunMode(mode);
|
|
30
|
+
assertModeAllowed(rootDir, normalizedMode);
|
|
31
|
+
const current = getCurrentRun(rootDir);
|
|
32
|
+
if (current && !TERMINAL_STATES.has(current.state)) {
|
|
33
|
+
throw studioRuntimeError(
|
|
34
|
+
`Run ${current.runId} is already active; finish it before creating a sibling execution`,
|
|
35
|
+
'ACTIVE_RUN'
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
const loaded = loadRecipe(rootDir, recipeId);
|
|
39
|
+
const plan = compileRecipe(loaded.recipe, { mode: normalizedMode });
|
|
40
|
+
const runId = newRunId(now);
|
|
41
|
+
const workflow = createWorkflowBundle(plan, runId, {
|
|
42
|
+
now,
|
|
43
|
+
run: {
|
|
44
|
+
runId,
|
|
45
|
+
mode: normalizedMode,
|
|
46
|
+
state: 'STARTED',
|
|
47
|
+
iteration: 1,
|
|
48
|
+
task: normalizedTask
|
|
49
|
+
}
|
|
50
|
+
});
|
|
51
|
+
return createRun(rootDir, {
|
|
52
|
+
runId,
|
|
53
|
+
task: normalizedTask,
|
|
54
|
+
mode: normalizedMode,
|
|
55
|
+
displayName,
|
|
56
|
+
workflow,
|
|
57
|
+
now
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function executeStudioRun(rootDir, runId, { now = new Date() } = {}) {
|
|
62
|
+
return startWorkflowExecution(rootDir, { runId, now });
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
module.exports = { createStudioRun, executeStudioRun };
|