ai-engineering-loop 1.7.0 → 1.9.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.
@@ -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() || stat.nlink !== 1 ||
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
+ };
@@ -0,0 +1,184 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { sha256 } = require('./recipe.js');
6
+ const { assertRunId, loadRun, runsDir } = require('./run-state.js');
7
+ const { redactSecrets } = require('./safe-context.js');
8
+
9
+ const MAX_INTERACTIONS = 500;
10
+ const MAX_MESSAGE_LENGTH = 8000;
11
+ const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
12
+ const QUESTION_ID = /^q-[a-f0-9]{12}$/;
13
+ const LOCK_STALE_MS = 60_000;
14
+
15
+ function interactionError(message, code = 'RUN_INTERACTION_ERROR') {
16
+ const error = new Error(message);
17
+ error.code = code;
18
+ return error;
19
+ }
20
+
21
+ function ledgerPath(rootDir, runId) {
22
+ assertRunId(runId);
23
+ loadRun(rootDir, runId);
24
+ return path.join(runsDir(rootDir), runId, 'interactions.jsonl');
25
+ }
26
+
27
+ function withInteractionLock(rootDir, runId, operation) {
28
+ const lock = `${ledgerPath(rootDir, runId)}.lock`;
29
+ let descriptor;
30
+ try {
31
+ try {
32
+ descriptor = fs.openSync(lock, 'wx', 0o600);
33
+ } catch (error) {
34
+ if (error.code !== 'EEXIST') throw error;
35
+ const stat = fs.lstatSync(lock);
36
+ if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
37
+ throw interactionError('Another interaction update is in progress', 'RUN_INTERACTION_BUSY');
38
+ }
39
+ fs.unlinkSync(lock);
40
+ descriptor = fs.openSync(lock, 'wx', 0o600);
41
+ }
42
+ return operation();
43
+ } finally {
44
+ if (descriptor != null) {
45
+ fs.closeSync(descriptor);
46
+ try { fs.unlinkSync(lock); } catch {}
47
+ }
48
+ }
49
+ }
50
+
51
+ function materialHash(event) {
52
+ const { hash, ...material } = event;
53
+ return sha256(material);
54
+ }
55
+
56
+ function readLedger(rootDir, runId) {
57
+ const file = ledgerPath(rootDir, runId);
58
+ if (!fs.existsSync(file)) return [];
59
+ const stat = fs.lstatSync(file);
60
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > 2 * 1024 * 1024) {
61
+ throw interactionError('Run interactions must be a bounded regular file', 'INVALID_RUN_INTERACTIONS');
62
+ }
63
+ const events = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
64
+ try { return JSON.parse(line); } catch { return null; }
65
+ });
66
+ let previousHash = null;
67
+ for (const [index, event] of events.entries()) {
68
+ if (!event || event.runId !== runId || event.sequence !== index + 1 ||
69
+ event.previousHash !== previousHash || event.hash !== materialHash(event) ||
70
+ !['QUESTION', 'ANSWER'].includes(event.type)) {
71
+ throw interactionError(`Run interaction ${index + 1} failed integrity validation`, 'INVALID_RUN_INTERACTIONS');
72
+ }
73
+ previousHash = event.hash;
74
+ }
75
+ return events;
76
+ }
77
+
78
+ function normalizedMessage(value) {
79
+ const message = redactSecrets(String(value || '').trim()).text;
80
+ if (!message || message.length > MAX_MESSAGE_LENGTH) {
81
+ throw interactionError(`Message must be 1-${MAX_MESSAGE_LENGTH} characters`, 'INVALID_INTERACTION_MESSAGE');
82
+ }
83
+ return message;
84
+ }
85
+
86
+ function normalizedActor(value) {
87
+ const actor = String(value || '').trim();
88
+ if (!ACTOR_ID.test(actor)) {
89
+ throw interactionError('Actor must be a short account identifier', 'INVALID_INTERACTION_ACTOR');
90
+ }
91
+ return actor;
92
+ }
93
+
94
+ function append(rootDir, runId, partial, now) {
95
+ const file = ledgerPath(rootDir, runId);
96
+ const events = readLedger(rootDir, runId);
97
+ if (events.length >= MAX_INTERACTIONS) {
98
+ throw interactionError('Run interaction limit reached', 'RUN_INTERACTION_LIMIT');
99
+ }
100
+ const material = {
101
+ schemaVersion: 1,
102
+ runId,
103
+ sequence: events.length + 1,
104
+ previousHash: events.at(-1)?.hash || null,
105
+ at: now.toISOString(),
106
+ ...partial
107
+ };
108
+ const event = { ...material, hash: sha256(material) };
109
+ fs.appendFileSync(file, `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'a' });
110
+ return event;
111
+ }
112
+
113
+ function appendRunQuestion(rootDir, runId, { message, actor = 'agent' } = {}, { now = new Date() } = {}) {
114
+ return withInteractionLock(rootDir, runId, () => {
115
+ const events = readLedger(rootDir, runId);
116
+ const number = events.filter((event) => event.type === 'QUESTION').length + 1;
117
+ const cleanMessage = normalizedMessage(message);
118
+ const cleanActor = normalizedActor(actor);
119
+ if (events.some((event) =>
120
+ event.type === 'QUESTION' && event.message === cleanMessage && event.actor === cleanActor &&
121
+ !events.some((answer) => answer.type === 'ANSWER' && answer.questionId === event.questionId)
122
+ )) {
123
+ throw interactionError('An identical question is already waiting for an answer', 'DUPLICATE_QUESTION');
124
+ }
125
+ const questionId = `q-${sha256({ runId, number, message: cleanMessage, at: now.toISOString() }).slice(0, 12)}`;
126
+ return append(rootDir, runId, {
127
+ type: 'QUESTION',
128
+ questionId,
129
+ number,
130
+ message: cleanMessage,
131
+ actor: cleanActor
132
+ }, now);
133
+ });
134
+ }
135
+
136
+ function appendRunAnswer(
137
+ rootDir,
138
+ runId,
139
+ questionId,
140
+ { message, actor = 'human' } = {},
141
+ { now = new Date() } = {}
142
+ ) {
143
+ return withInteractionLock(rootDir, runId, () => {
144
+ if (!QUESTION_ID.test(String(questionId))) {
145
+ throw interactionError('Question ID is invalid', 'INVALID_QUESTION_ID');
146
+ }
147
+ const events = readLedger(rootDir, runId);
148
+ if (!events.some((event) => event.type === 'QUESTION' && event.questionId === questionId)) {
149
+ throw interactionError(`Question ${questionId} does not exist`, 'QUESTION_NOT_FOUND');
150
+ }
151
+ if (events.some((event) => event.type === 'ANSWER' && event.questionId === questionId)) {
152
+ throw interactionError(`Question ${questionId} is already answered`, 'QUESTION_ALREADY_ANSWERED');
153
+ }
154
+ return append(rootDir, runId, {
155
+ type: 'ANSWER',
156
+ questionId,
157
+ message: normalizedMessage(message),
158
+ actor: normalizedActor(actor)
159
+ }, now);
160
+ });
161
+ }
162
+
163
+ function listRunInteractions(rootDir, runId) {
164
+ const interactions = readLedger(rootDir, runId);
165
+ const answers = new Map(
166
+ interactions.filter((event) => event.type === 'ANSWER').map((event) => [event.questionId, event])
167
+ );
168
+ const questions = interactions.filter((event) => event.type === 'QUESTION')
169
+ .map((question) => ({ ...question, answer: answers.get(question.questionId) || null }));
170
+ return {
171
+ runId,
172
+ interactions,
173
+ questions,
174
+ pending: questions.filter((question) => !question.answer)
175
+ };
176
+ }
177
+
178
+ module.exports = {
179
+ MAX_INTERACTIONS,
180
+ MAX_MESSAGE_LENGTH,
181
+ appendRunAnswer,
182
+ appendRunQuestion,
183
+ listRunInteractions
184
+ };
package/lib/run-state.js CHANGED
@@ -14,7 +14,8 @@ const RUN_STATES = Object.freeze({
14
14
  REVIEWED: 'REVIEWED',
15
15
  JUDGED_PASS: 'JUDGED_PASS',
16
16
  DELIVERED: 'DELIVERED',
17
- ESCALATED: 'ESCALATED'
17
+ ESCALATED: 'ESCALATED',
18
+ CANCELLED: 'CANCELLED'
18
19
  });
19
20
 
20
21
  const RUN_MODES = Object.freeze({
@@ -24,18 +25,24 @@ const RUN_MODES = Object.freeze({
24
25
  });
25
26
 
26
27
  const ALLOWED_TRANSITIONS = Object.freeze({
27
- STARTED: ['GOAL_FROZEN'],
28
- GOAL_FROZEN: ['REPORTED', 'MAKER_COMPLETE'],
28
+ STARTED: ['GOAL_FROZEN', 'CANCELLED'],
29
+ GOAL_FROZEN: ['STARTED', 'REPORTED', 'MAKER_COMPLETE', 'CANCELLED'],
29
30
  REPORTED: [],
30
- MAKER_COMPLETE: ['VERIFIED'],
31
- VERIFIED: ['REVIEWED'],
32
- REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED'],
33
- JUDGED_PASS: ['DELIVERED'],
31
+ MAKER_COMPLETE: ['VERIFIED', 'CANCELLED'],
32
+ VERIFIED: ['REVIEWED', 'CANCELLED'],
33
+ REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED', 'CANCELLED'],
34
+ JUDGED_PASS: ['DELIVERED', 'CANCELLED'],
34
35
  DELIVERED: [],
35
- ESCALATED: []
36
+ ESCALATED: [],
37
+ CANCELLED: []
36
38
  });
37
39
 
38
- const TERMINAL_STATES = new Set([RUN_STATES.REPORTED, RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
40
+ const TERMINAL_STATES = new Set([
41
+ RUN_STATES.REPORTED,
42
+ RUN_STATES.DELIVERED,
43
+ RUN_STATES.ESCALATED,
44
+ RUN_STATES.CANCELLED
45
+ ]);
39
46
 
40
47
  function runsDir(rootDir) {
41
48
  return path.join(rootDir, '.ai-engineering-loop', 'runs');
@@ -98,6 +105,32 @@ function newRunId(now = new Date()) {
98
105
  return `${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
99
106
  }
100
107
 
108
+ function runDisplayMetadata(task, displayName) {
109
+ const normalizedTask = String(task || '').trim().replace(/\s+/g, ' ');
110
+ const safeProposal = String(displayName || '').trim().replace(/\s+/g, ' ');
111
+ const usableProposal = safeProposal &&
112
+ safeProposal.length <= 100 &&
113
+ !/[\u0000-\u001f/\\]/.test(safeProposal);
114
+ const fallbackWords = normalizedTask
115
+ .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
116
+ .trim()
117
+ .split(/\s+/)
118
+ .filter(Boolean)
119
+ .slice(0, 7);
120
+ const fallback = fallbackWords.join(' ') || 'Untitled run';
121
+ const name = usableProposal ? safeProposal : fallback;
122
+ const slug = name.toLocaleLowerCase('en-US')
123
+ .normalize('NFKD')
124
+ .replace(/[^\p{L}\p{N}]+/gu, '-')
125
+ .replace(/^-+|-+$/g, '')
126
+ .slice(0, 80) || 'untitled-run';
127
+ const keywords = [...new Set(
128
+ normalizedTask.toLocaleLowerCase('en-US')
129
+ .match(/[\p{L}\p{N}]{2,}/gu) || []
130
+ )].slice(0, 20);
131
+ return { displayName: name, slug, keywords };
132
+ }
133
+
101
134
  function runStatePath(rootDir, runId) {
102
135
  return path.join(runsDir(rootDir), assertRunId(runId), 'state.json');
103
136
  }
@@ -167,7 +200,15 @@ function normalizeRunMode(mode) {
167
200
 
168
201
  function createRun(
169
202
  rootDir,
170
- { task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date(), workflow = null } = {}
203
+ {
204
+ task = '',
205
+ runId = newRunId(),
206
+ mode = RUN_MODES.ASSISTED,
207
+ now = new Date(),
208
+ workflow = null,
209
+ displayName = '',
210
+ constraints = ''
211
+ } = {}
171
212
  ) {
172
213
  assertRunId(runId);
173
214
  const statePath = runStatePath(rootDir, runId);
@@ -178,6 +219,14 @@ function createRun(
178
219
  }
179
220
 
180
221
  const timestamp = now.toISOString();
222
+ const normalizedTask = String(task || '').trim();
223
+ const normalizedConstraints = String(constraints || '').trim();
224
+ if (normalizedConstraints.length > 8000) {
225
+ const err = new Error('Run constraints must not exceed 8000 characters');
226
+ err.code = 'INVALID_RUN_CONSTRAINTS';
227
+ throw err;
228
+ }
229
+ const presentation = runDisplayMetadata(normalizedTask, displayName);
181
230
  const workflowMetadata = writeWorkflowBundle(rootDir, runId, workflow);
182
231
  const state = {
183
232
  schemaVersion: 1,
@@ -185,7 +234,9 @@ function createRun(
185
234
  state: RUN_STATES.STARTED,
186
235
  mode: normalizeRunMode(mode),
187
236
  iteration: 1,
188
- task: String(task || '').trim(),
237
+ task: normalizedTask,
238
+ constraints: normalizedConstraints,
239
+ ...presentation,
189
240
  startedRevision: getGitRevision(rootDir),
190
241
  createdAt: timestamp,
191
242
  updatedAt: timestamp,
@@ -244,11 +295,55 @@ function createOrResumeRun(
244
295
  };
245
296
  }
246
297
 
298
+ function updateRunDisplayName(rootDir, runId, displayName, { actor = 'human', now = new Date() } = {}) {
299
+ const run = loadRun(rootDir, runId);
300
+ const proposed = String(displayName || '').trim().replace(/\s+/g, ' ');
301
+ if (!proposed || proposed.length > 100 || /[\u0000-\u001f/\\]/.test(proposed)) {
302
+ const err = new Error('Display Name must be 1-100 characters without control characters or path separators');
303
+ err.code = 'INVALID_RUN_DISPLAY_NAME';
304
+ throw err;
305
+ }
306
+ if (!/^[A-Za-z0-9@._-]{1,64}$/.test(String(actor))) {
307
+ const err = new Error('Display Name actor must be a short account identifier');
308
+ err.code = 'INVALID_RUN_ACTOR';
309
+ throw err;
310
+ }
311
+ const timestamp = now.toISOString();
312
+ const presentation = runDisplayMetadata(run.task, proposed);
313
+ const next = {
314
+ ...run,
315
+ ...presentation,
316
+ runId: run.runId,
317
+ updatedAt: timestamp,
318
+ history: [
319
+ ...(run.history || []),
320
+ {
321
+ from: run.state,
322
+ to: run.state,
323
+ gate: 'run-metadata',
324
+ at: timestamp,
325
+ actor: String(actor),
326
+ displayName: presentation.displayName
327
+ }
328
+ ]
329
+ };
330
+ atomicWriteJson(runStatePath(rootDir, runId), next);
331
+ return next;
332
+ }
333
+
247
334
  function transitionRun(
248
335
  rootDir,
249
336
  runId,
250
337
  to,
251
- { gate, artifacts = {}, reason = null, incrementIteration = false, now = new Date() } = {}
338
+ {
339
+ gate,
340
+ artifacts = {},
341
+ reason = null,
342
+ incrementIteration = false,
343
+ statePatch = {},
344
+ historyMetadata = {},
345
+ now = new Date()
346
+ } = {}
252
347
  ) {
253
348
  const run = loadRun(rootDir, runId);
254
349
  if (!RUN_STATES[to]) {
@@ -265,6 +360,8 @@ function transitionRun(
265
360
  const timestamp = now.toISOString();
266
361
  const next = {
267
362
  ...run,
363
+ ...statePatch,
364
+ runId: run.runId,
268
365
  state: to,
269
366
  iteration: incrementIteration ? run.iteration + 1 : run.iteration,
270
367
  updatedAt: timestamp,
@@ -276,7 +373,8 @@ function transitionRun(
276
373
  to,
277
374
  gate: gate || 'unspecified',
278
375
  at: timestamp,
279
- ...(reason ? { reason } : {})
376
+ ...(reason ? { reason } : {}),
377
+ ...historyMetadata
280
378
  }
281
379
  ]
282
380
  };
@@ -298,10 +396,12 @@ module.exports = {
298
396
  atomicWriteJson,
299
397
  getGitRevision,
300
398
  newRunId,
399
+ runDisplayMetadata,
301
400
  normalizeRunMode,
302
401
  loadRun,
303
402
  getCurrentRun,
304
403
  createRun,
305
404
  createOrResumeRun,
405
+ updateRunDisplayName,
306
406
  transitionRun
307
407
  };
@@ -0,0 +1,73 @@
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
+ {
24
+ task,
25
+ constraints = '',
26
+ recipeId,
27
+ mode = RUN_MODES.ASSISTED,
28
+ displayName = '',
29
+ now = new Date()
30
+ } = {}
31
+ ) {
32
+ const normalizedTask = String(task || '').trim();
33
+ if (!normalizedTask || normalizedTask.length > 2000) {
34
+ throw studioRuntimeError('Task must be 1-2000 characters', 'INVALID_RUN_TASK');
35
+ }
36
+ const normalizedMode = normalizeRunMode(mode);
37
+ assertModeAllowed(rootDir, normalizedMode);
38
+ const current = getCurrentRun(rootDir);
39
+ if (current && !TERMINAL_STATES.has(current.state)) {
40
+ throw studioRuntimeError(
41
+ `Run ${current.runId} is already active; finish it before creating a sibling execution`,
42
+ 'ACTIVE_RUN'
43
+ );
44
+ }
45
+ const loaded = loadRecipe(rootDir, recipeId);
46
+ const plan = compileRecipe(loaded.recipe, { mode: normalizedMode });
47
+ const runId = newRunId(now);
48
+ const workflow = createWorkflowBundle(plan, runId, {
49
+ now,
50
+ run: {
51
+ runId,
52
+ mode: normalizedMode,
53
+ state: 'STARTED',
54
+ iteration: 1,
55
+ task: normalizedTask
56
+ }
57
+ });
58
+ return createRun(rootDir, {
59
+ runId,
60
+ task: normalizedTask,
61
+ mode: normalizedMode,
62
+ displayName,
63
+ constraints,
64
+ workflow,
65
+ now
66
+ });
67
+ }
68
+
69
+ function executeStudioRun(rootDir, runId, { now = new Date() } = {}) {
70
+ return startWorkflowExecution(rootDir, { runId, now });
71
+ }
72
+
73
+ module.exports = { createStudioRun, executeStudioRun };