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/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
- for (const node of nodes) {
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(nodes, byId, errors);
289
- const terminals = nodes.filter((node) => ['report', 'delivery'].includes(node.type));
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 (nodes.some((node) => (node.dependsOn || []).includes(terminal.id))) {
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 nodes) {
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
- { task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date(), workflow = null } = {}
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: String(task || '').trim(),
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
- { gate, artifacts = {}, reason = null, incrementIteration = false, now = new Date() } = {}
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 };