ai-engineering-loop 1.9.3 → 1.10.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.
@@ -2,9 +2,10 @@
2
2
 
3
3
  const { validateRecipe } = require('./recipe.js');
4
4
  const { stableEdgeId } = require('./recipe-graph.js');
5
+ const { listRunInteractions } = require('./run-interactions.js');
5
6
  const { loadRun } = require('./run-state.js');
6
7
  const { inspectRunArtifact } = require('./run-history.js');
7
- const { redactSecrets } = require('./safe-context.js');
8
+ const { redactHomePaths, redactSecrets } = require('./safe-context.js');
8
9
  const { workflowStatus } = require('./workflow-runtime.js');
9
10
 
10
11
  function checkoutError(message, code = 'RUN_CHECKOUT_ERROR') {
@@ -18,15 +19,42 @@ function fallbackPosition(index) {
18
19
  }
19
20
 
20
21
  function redactedValue(value) {
21
- return JSON.parse(redactSecrets(JSON.stringify(value)).text);
22
+ const redactDeep = (item) => {
23
+ if (typeof item === 'string') return redactHomePaths(item);
24
+ if (Array.isArray(item)) return item.map(redactDeep);
25
+ if (item && typeof item === 'object') {
26
+ return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, redactDeep(child)]));
27
+ }
28
+ return item;
29
+ };
30
+ return JSON.parse(redactSecrets(JSON.stringify(redactDeep(value))).text);
22
31
  }
23
32
 
24
- function edgesFromPlan(plan) {
25
- return plan.nodes.flatMap((node) => (node.dependsOn || []).map((from) => ({
26
- id: stableEdgeId(from, node.id),
27
- from,
28
- to: node.id
29
- })));
33
+ function edgeState(sourceStatus, targetStatus) {
34
+ if (targetStatus === 'RUNNING') return 'active';
35
+ if (targetStatus === 'FAILED') return 'failed';
36
+ if (targetStatus === 'SKIPPED') return 'skipped';
37
+ if (targetStatus === 'READY' || targetStatus === 'BLOCKED') return 'waiting';
38
+ if (['PASSED', 'SKIPPED'].includes(sourceStatus) && targetStatus === 'PASSED') return 'passed';
39
+ return 'idle';
40
+ }
41
+
42
+ function edgesFromPlan(plan, state = null) {
43
+ return plan.nodes.flatMap((node) => (node.dependsOn || []).map((from) => {
44
+ const sourceStatus = state?.nodes[from]?.status;
45
+ const targetStatus = state?.nodes[node.id]?.status;
46
+ const stateName = edgeState(sourceStatus, targetStatus);
47
+ return {
48
+ id: stableEdgeId(from, node.id),
49
+ from,
50
+ to: node.id,
51
+ ...(state ? {
52
+ state: stateName,
53
+ traversed: !['idle', 'waiting'].includes(stateName),
54
+ active: stateName === 'active'
55
+ } : {})
56
+ };
57
+ }));
30
58
  }
31
59
 
32
60
  function publicNode(node, state, index) {
@@ -72,7 +100,7 @@ function runCheckout(rootDir, runId) {
72
100
  run: publicRun,
73
101
  graphHash: workflow.plan.graphHash,
74
102
  nodes: workflow.plan.nodes.map((node, index) => publicNode(node, workflow.state, index)),
75
- edges: edgesFromPlan(workflow.plan),
103
+ edges: edgesFromPlan(workflow.plan, workflow.state),
76
104
  loopGroups: (workflow.plan.loopGroups || []).map((group) => ({
77
105
  ...group,
78
106
  runtime: workflow.state.loopGroups[group.id] || null
@@ -110,9 +138,32 @@ function runNodeIo(rootDir, runId, nodeId) {
110
138
  event.type === 'WORKFLOW_CREATED' ||
111
139
  (event.changes || []).some((change) => change.nodeId === nodeId)
112
140
  ).map(({ initialNodes, ...event }) => event);
141
+ const finishedIndex = relevantEvents.findLastIndex((event) =>
142
+ ['NODE_COMPLETED', 'NODE_FAILED'].includes(event.type)
143
+ );
144
+ const finished = relevantEvents[finishedIndex];
145
+ const started = finishedIndex < 0
146
+ ? null
147
+ : relevantEvents.slice(0, finishedIndex).findLast((event) => event.type === 'NODE_STARTED');
148
+ const durationMs = runtime.status !== 'RUNNING' &&
149
+ started && finished && Date.parse(finished.at) >= Date.parse(started.at)
150
+ ? Date.parse(finished.at) - Date.parse(started.at)
151
+ : null;
152
+ let agentInteractions = [];
153
+ let agentInteractionsAvailable = true;
154
+ try {
155
+ agentInteractions = listRunInteractions(rootDir, runId).interactions.slice(-50);
156
+ } catch {
157
+ agentInteractionsAvailable = false;
158
+ }
113
159
  return redactedValue({
114
160
  runId,
115
161
  node: publicNode(node, workflow.state, workflow.plan.nodes.indexOf(node)),
162
+ durationMs,
163
+ loopIteration: runtime.loopIteration || null,
164
+ agentInteractionScope: 'RUN',
165
+ agentInteractionsAvailable,
166
+ agentInteractions,
116
167
  input: {
117
168
  task: node.dependsOn?.length ? null : run.task,
118
169
  constraints: node.dependsOn?.length ? null : (run.constraints || ''),
@@ -160,6 +211,8 @@ function duplicateRunAsRecipe(rootDir, runId, { recipeId } = {}) {
160
211
  function studioAgentHandoff(rootDir, runId) {
161
212
  const run = loadRun(rootDir, runId);
162
213
  const commandRoot = `npx ai-engineering-loop interaction`;
214
+ const lifecycleCommand = `npx ai-engineering-loop activity heartbeat --run ${runId} --phase <phase> --message "<factual update>"`;
215
+ const goalCommand = `npx ai-engineering-loop goal draft --run ${runId} --file <repository-relative-goal.json> --revision <current-revision>`;
163
216
  return redactedValue({
164
217
  runId,
165
218
  externalDispatch: false,
@@ -167,13 +220,17 @@ function studioAgentHandoff(rootDir, runId) {
167
220
  `Continue AI Engineering Loop Run ${runId}.`,
168
221
  `Task: ${run.task}`,
169
222
  run.constraints ? `Constraints: ${run.constraints}` : null,
170
- 'Read the Run state and evidence before acting.',
223
+ 'From the repository root, read the Run state and evidence before acting.',
224
+ `Draft the Goal through the Run-scoped bridge with: ${goalCommand}`,
225
+ `Report persisted lifecycle progress with: ${lifecycleCommand}`,
171
226
  `When blocked, ask with: ${commandRoot} question --run ${runId} --message "Your question"`,
172
227
  `Poll answers with: ${commandRoot} list --run ${runId} --json`,
173
228
  'Do not create a sibling Run or claim completion without Run-bound evidence.'
174
229
  ].filter(Boolean).join('\n'),
175
230
  commands: {
176
231
  inspect: `npx ai-engineering-loop status --run ${runId}`,
232
+ goalDraft: goalCommand,
233
+ lifecycle: lifecycleCommand,
177
234
  question: `${commandRoot} question --run ${runId} --message "Your question"`,
178
235
  answers: `${commandRoot} list --run ${runId} --json`
179
236
  }
@@ -182,6 +239,9 @@ function studioAgentHandoff(rootDir, runId) {
182
239
 
183
240
  module.exports = {
184
241
  duplicateRunAsRecipe,
242
+ edgeState,
243
+ edgesFromPlan,
244
+ redactedValue,
185
245
  runCheckout,
186
246
  runNodeIo,
187
247
  studioAgentHandoff
@@ -0,0 +1,75 @@
1
+ 'use strict';
2
+
3
+ const { loadGoalDraft } = require('./goal-runtime.js');
4
+ const { listRunInteractions } = require('./run-interactions.js');
5
+ const { readAllRunLifecycle } = require('./run-lifecycle.js');
6
+ const { loadRun } = require('./run-state.js');
7
+
8
+ const JOURNEY_STEPS = [
9
+ 'TASK_RECEIVED',
10
+ 'GOAL_DRAFTING',
11
+ 'WAITING_FOR_ANSWERS',
12
+ 'READY_FOR_GOAL_FREEZE',
13
+ 'WORKFLOW_EXECUTION',
14
+ 'RUN_COMPLETE'
15
+ ];
16
+ const TERMINAL_STATES = new Set(['DELIVERED', 'REPORTED', 'ESCALATED', 'CANCELLED']);
17
+
18
+ function runJourney(rootDir, runId, { workflowState = null } = {}) {
19
+ const run = loadRun(rootDir, runId);
20
+ let draft = null;
21
+ let draftAvailable = true;
22
+ let interactions = { pending: [] };
23
+ let interactionsAvailable = true;
24
+ let lifecycle = [];
25
+ let lifecycleAvailable = true;
26
+ try {
27
+ draft = loadGoalDraft(rootDir, runId);
28
+ } catch {
29
+ draftAvailable = false;
30
+ }
31
+ try {
32
+ interactions = listRunInteractions(rootDir, runId);
33
+ } catch {
34
+ interactionsAvailable = false;
35
+ }
36
+ try {
37
+ lifecycle = readAllRunLifecycle(rootDir, runId);
38
+ } catch {
39
+ lifecycleAvailable = false;
40
+ }
41
+ const workflowStarted = Object.values(workflowState?.nodes || {}).some((node) =>
42
+ ['RUNNING', 'PASSED', 'FAILED', 'SKIPPED'].includes(node.status)
43
+ ) || lifecycle.some((event) =>
44
+ ['NODE_STARTED', 'NODE_ACTIVITY', 'NODE_COMPLETED', 'NODE_FAILED', 'LOOP_ITERATED'].includes(event.type)
45
+ );
46
+ const goalFrozen = run.goal?.frozen === true ||
47
+ lifecycle.some((event) => event.type === 'GOAL_FROZEN');
48
+ const complete = TERMINAL_STATES.has(run.state);
49
+ let current = 'TASK_RECEIVED';
50
+ if (draft || lifecycle.some((event) => event.type === 'GOAL_DRAFTING')) current = 'GOAL_DRAFTING';
51
+ if (draft && interactionsAvailable && interactions.pending.length === 0) current = 'READY_FOR_GOAL_FREEZE';
52
+ if (interactions.pending.length > 0 && !workflowStarted) current = 'WAITING_FOR_ANSWERS';
53
+ if (goalFrozen || workflowStarted) current = 'WORKFLOW_EXECUTION';
54
+ if (complete) current = 'RUN_COMPLETE';
55
+ const currentIndex = JOURNEY_STEPS.indexOf(current);
56
+ return {
57
+ runId,
58
+ current,
59
+ blocked: interactionsAvailable ? interactions.pending.length > 0 : null,
60
+ pendingQuestions: interactionsAvailable ? interactions.pending.length : null,
61
+ degradedSources: [
62
+ draftAvailable ? null : 'Goal draft',
63
+ interactionsAvailable ? null : 'Agent Interaction',
64
+ lifecycleAvailable ? null : 'Lifecycle activity'
65
+ ].filter(Boolean),
66
+ sources: { draftAvailable, interactionsAvailable, lifecycleAvailable },
67
+ steps: JOURNEY_STEPS.map((id, index) => ({
68
+ id,
69
+ status: index < currentIndex ? 'COMPLETE' : (index === currentIndex ? 'ACTIVE' : 'PENDING'),
70
+ ...(id === 'WAITING_FOR_ANSWERS' && interactions.pending.length > 0 ? { blocked: true } : {})
71
+ }))
72
+ };
73
+ }
74
+
75
+ module.exports = { JOURNEY_STEPS, runJourney };
@@ -0,0 +1,203 @@
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_EVENTS = 2000;
10
+ const MAX_LEDGER_BYTES = 4 * 1024 * 1024;
11
+ const TYPES = new Set([
12
+ 'GOAL_DRAFTING',
13
+ 'GOAL_DRAFT_UPDATED',
14
+ 'GOAL_READY',
15
+ 'GOAL_FROZEN',
16
+ 'PHASE_COMPLETED',
17
+ 'AGENT_HEARTBEAT',
18
+ 'AGENT_WAITING',
19
+ 'NODE_STARTED',
20
+ 'NODE_ACTIVITY',
21
+ 'NODE_COMPLETED',
22
+ 'NODE_FAILED',
23
+ 'LOOP_ITERATED',
24
+ 'RUN_COMPLETED'
25
+ ]);
26
+ const ID = /^[A-Za-z0-9@._-]{1,64}$/;
27
+ const NODE_TYPES = new Set(['NODE_STARTED', 'NODE_ACTIVITY', 'NODE_COMPLETED', 'NODE_FAILED']);
28
+ const STATUSES = new Set(['WORKING', 'WAITING', 'PASSED', 'FAILED', 'SKIPPED', 'UNKNOWN']);
29
+ const LOCK_STALE_MS = 60_000;
30
+
31
+ function lifecycleError(message, code) {
32
+ const error = new Error(message);
33
+ error.code = code;
34
+ return error;
35
+ }
36
+
37
+ function lifecyclePath(rootDir, runId) {
38
+ assertRunId(runId);
39
+ loadRun(rootDir, runId);
40
+ return path.join(runsDir(rootDir), runId, 'lifecycle.jsonl');
41
+ }
42
+
43
+ function materialHash(event) {
44
+ const { hash, ...material } = event;
45
+ return sha256(material);
46
+ }
47
+
48
+ function readLifecycle(rootDir, runId) {
49
+ const file = lifecyclePath(rootDir, runId);
50
+ if (!fs.existsSync(file)) return [];
51
+ const stat = fs.lstatSync(file);
52
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > MAX_LEDGER_BYTES) {
53
+ throw lifecycleError('Run lifecycle must be a bounded regular file', 'INVALID_RUN_LIFECYCLE');
54
+ }
55
+ const events = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
56
+ try { return JSON.parse(line); } catch { return null; }
57
+ });
58
+ let previousHash = null;
59
+ for (const [index, event] of events.entries()) {
60
+ if (!event || event.runId !== runId || event.sequence !== index + 1 ||
61
+ event.previousHash !== previousHash || event.hash !== materialHash(event) ||
62
+ !TYPES.has(event.type)) {
63
+ throw lifecycleError(`Run lifecycle event ${index + 1} failed integrity validation`, 'INVALID_RUN_LIFECYCLE');
64
+ }
65
+ previousHash = event.hash;
66
+ }
67
+ return events;
68
+ }
69
+
70
+ function withLock(rootDir, runId, operation) {
71
+ const lock = `${lifecyclePath(rootDir, runId)}.lock`;
72
+ let descriptor;
73
+ try {
74
+ try {
75
+ descriptor = fs.openSync(lock, 'wx', 0o600);
76
+ } catch (error) {
77
+ if (error.code !== 'EEXIST') throw error;
78
+ const stat = fs.lstatSync(lock);
79
+ if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
80
+ throw lifecycleError('Another lifecycle update is in progress', 'RUN_LIFECYCLE_BUSY');
81
+ }
82
+ fs.unlinkSync(lock);
83
+ descriptor = fs.openSync(lock, 'wx', 0o600);
84
+ }
85
+ return operation();
86
+ } finally {
87
+ if (descriptor != null) {
88
+ fs.closeSync(descriptor);
89
+ try { fs.unlinkSync(lock); } catch {}
90
+ }
91
+ }
92
+ }
93
+
94
+ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
95
+ return withLock(rootDir, runId, () => {
96
+ if (!TYPES.has(event?.type)) {
97
+ throw lifecycleError('Lifecycle type is not allowed', 'INVALID_LIFECYCLE_TYPE');
98
+ }
99
+ const actor = String(event.actor || 'agent').trim();
100
+ if (!ID.test(actor)) throw lifecycleError('Lifecycle actor is invalid', 'INVALID_LIFECYCLE_ACTOR');
101
+ const phase = event.phase == null ? null : String(event.phase).trim();
102
+ const nodeId = event.nodeId == null ? null : String(event.nodeId).trim();
103
+ if ((phase && !ID.test(phase)) || (nodeId && !ID.test(nodeId))) {
104
+ throw lifecycleError('Lifecycle phase or node is invalid', 'INVALID_LIFECYCLE_SCOPE');
105
+ }
106
+ const run = loadRun(rootDir, runId);
107
+ if (NODE_TYPES.has(event.type)) {
108
+ if (!nodeId) throw lifecycleError('Node lifecycle events require a node Technical ID', 'INVALID_LIFECYCLE_SCOPE');
109
+ if (!run.workflow) throw lifecycleError('Classic Runs cannot publish node-scoped activity', 'INVALID_LIFECYCLE_SCOPE');
110
+ const { workflowStatus } = require('./workflow-runtime.js');
111
+ const workflow = workflowStatus(rootDir, { runId });
112
+ if (!workflow.plan.nodes.some((node) => node.id === nodeId)) {
113
+ throw lifecycleError(`Node ${nodeId} is not part of Run ${runId}`, 'INVALID_LIFECYCLE_SCOPE');
114
+ }
115
+ } else if (nodeId) {
116
+ throw lifecycleError('Run lifecycle events cannot claim a node scope', 'INVALID_LIFECYCLE_SCOPE');
117
+ }
118
+ const status = event.status == null ? null : String(event.status).trim().toUpperCase();
119
+ if (status && !STATUSES.has(status)) {
120
+ throw lifecycleError('Lifecycle status is invalid', 'INVALID_LIFECYCLE_STATUS');
121
+ }
122
+ let evidence = null;
123
+ if (event.evidence != null) {
124
+ const evidencePath = String(event.evidence.path || '').trim();
125
+ const evidenceHash = event.evidence.sha256 == null ? null : String(event.evidence.sha256).trim();
126
+ if (!evidencePath || evidencePath.length > 240 || path.isAbsolute(evidencePath) ||
127
+ evidencePath.split(/[\\/]/).includes('..') ||
128
+ (evidenceHash && !/^[a-f0-9]{64}$/.test(evidenceHash))) {
129
+ throw lifecycleError('Lifecycle evidence reference is invalid', 'INVALID_LIFECYCLE_EVIDENCE');
130
+ }
131
+ evidence = { path: evidencePath, ...(evidenceHash ? { sha256: evidenceHash } : {}) };
132
+ }
133
+ const message = redactSecrets(String(event.message || '').trim()).text;
134
+ if (!message || message.length > 240 ||
135
+ /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(message)) {
136
+ throw lifecycleError('Lifecycle message must be 1-240 printable characters', 'INVALID_LIFECYCLE_MESSAGE');
137
+ }
138
+ const events = readLifecycle(rootDir, runId);
139
+ if (events.length >= MAX_EVENTS) {
140
+ throw lifecycleError('Run lifecycle event limit reached', 'RUN_LIFECYCLE_LIMIT');
141
+ }
142
+ const material = {
143
+ schemaVersion: 1,
144
+ runId,
145
+ sequence: events.length + 1,
146
+ previousHash: events.at(-1)?.hash || null,
147
+ at: now.toISOString(),
148
+ type: event.type,
149
+ actor,
150
+ message,
151
+ ...(phase ? { phase } : {}),
152
+ ...(nodeId ? { nodeId } : {}),
153
+ ...(status ? { status } : {}),
154
+ ...(evidence ? { evidence } : {})
155
+ };
156
+ const result = { ...material, hash: sha256(material) };
157
+ fs.appendFileSync(lifecyclePath(rootDir, runId), `${JSON.stringify(result)}\n`, {
158
+ encoding: 'utf8',
159
+ mode: 0o600,
160
+ flag: 'a'
161
+ });
162
+ return result;
163
+ });
164
+ }
165
+
166
+ function listRunLifecycle(rootDir, runId, { after = 0, limit = 100 } = {}) {
167
+ const cursor = Number(after);
168
+ const pageSize = Number(limit);
169
+ if (!Number.isSafeInteger(cursor) || cursor < 0 ||
170
+ !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
171
+ throw lifecycleError('Lifecycle cursor or limit is invalid', 'INVALID_LIFECYCLE_CURSOR');
172
+ }
173
+ const events = readLifecycle(rootDir, runId).filter((event) => event.sequence > cursor).slice(0, pageSize);
174
+ return {
175
+ runId,
176
+ events,
177
+ nextSequence: events.at(-1)?.sequence || cursor
178
+ };
179
+ }
180
+
181
+ function readAllRunLifecycle(rootDir, runId) {
182
+ return readLifecycle(rootDir, runId);
183
+ }
184
+
185
+ function runAgentPresence(rootDir, runId, { now = new Date() } = {}) {
186
+ const events = readLifecycle(rootDir, runId);
187
+ const last = events.findLast((event) => event.type === 'AGENT_HEARTBEAT');
188
+ if (!last) return { status: 'UNKNOWN', lastHeartbeatAt: null };
189
+ const ageMs = Math.max(0, now.getTime() - Date.parse(last.at));
190
+ return {
191
+ status: ageMs < 10_000 ? 'WORKING' : ageMs <= 30_000 ? 'IDLE' : 'DISCONNECTED',
192
+ lastHeartbeatAt: last.at,
193
+ ageMs
194
+ };
195
+ }
196
+
197
+ module.exports = {
198
+ MAX_EVENTS,
199
+ appendRunLifecycle,
200
+ listRunLifecycle,
201
+ readAllRunLifecycle,
202
+ runAgentPresence
203
+ };
@@ -89,6 +89,16 @@ function redactSecrets(input) {
89
89
  return { text, categories: [...categories].sort() };
90
90
  }
91
91
 
92
+ function redactHomePaths(input) {
93
+ return String(input ?? '')
94
+ .replace(/(?:file:\/\/)?\/Users\/[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
95
+ .replace(/(?:file:\/\/)?\/home\/[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
96
+ .replace(/(?:file:\/\/)?\/root(?=\/|\\|$)/g, '[REDACTED HOME]')
97
+ .replace(/(?:file:\/\/)?(?:\/private)?\/var\/folders\/[A-Za-z0-9._/-]+/g, '[REDACTED TMP]')
98
+ .replace(/\b[A-Za-z]:\\Users\\[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
99
+ .replace(/\\\\[A-Za-z0-9._-]+\\[A-Za-z0-9._$-]+/g, '[REDACTED HOME]');
100
+ }
101
+
92
102
  function sha256(content) {
93
103
  return crypto.createHash('sha256').update(content).digest('hex');
94
104
  }
@@ -188,6 +198,7 @@ module.exports = {
188
198
  isSensitivePath,
189
199
  resolveSafeRepoFile,
190
200
  redactSecrets,
201
+ redactHomePaths,
191
202
  estimateTokens,
192
203
  createContextPack,
193
204
  contextPackSummary
@@ -56,7 +56,7 @@ function createStudioRun(
56
56
  };
57
57
  throw error;
58
58
  }
59
- const loaded = loadRecipe(rootDir, recipeId);
59
+ const loaded = loadRecipe(rootDir, recipeId || 'default');
60
60
  const plan = compileRecipe(loaded.recipe, { mode: normalizedMode });
61
61
  const runId = newRunId(now);
62
62
  const workflow = createWorkflowBundle(plan, runId, {
@@ -29,6 +29,8 @@ const {
29
29
  const { listRunHistory, runHistoryDetail, inspectRunArtifact } = require('./run-history.js');
30
30
  const {
31
31
  duplicateRunAsRecipe,
32
+ edgesFromPlan,
33
+ redactedValue,
32
34
  runCheckout,
33
35
  runNodeIo,
34
36
  studioAgentHandoff
@@ -38,7 +40,9 @@ const {
38
40
  appendRunQuestion,
39
41
  listRunInteractions
40
42
  } = require('./run-interactions.js');
41
- const { saveGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
43
+ const { saveGoalDraft, loadGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
44
+ const { appendRunLifecycle, listRunLifecycle, runAgentPresence } = require('./run-lifecycle.js');
45
+ const { runJourney } = require('./run-journey.js');
42
46
  const { cancelStudioRun, createStudioRun, executeStudioRun } = require('./studio-runtime.js');
43
47
  const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
44
48
  const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
@@ -71,21 +75,64 @@ function readBody(request) {
71
75
  });
72
76
  }
73
77
 
78
+ function streamRunLifecycle(rootDir, runId, after, request, response) {
79
+ let cursor = after;
80
+ response.writeHead(200, {
81
+ 'content-type': 'text/event-stream; charset=utf-8',
82
+ 'cache-control': 'no-store',
83
+ connection: 'keep-alive'
84
+ });
85
+ const publish = () => {
86
+ try {
87
+ const lifecycle = listRunLifecycle(rootDir, runId, { after: cursor, limit: 100 });
88
+ cursor = lifecycle.nextSequence;
89
+ response.write(`data: ${JSON.stringify({
90
+ lifecycle,
91
+ presence: runAgentPresence(rootDir, runId)
92
+ })}\n\n`);
93
+ } catch (error) {
94
+ response.write(`event: error\ndata: ${JSON.stringify({
95
+ code: error.code || 'LIFECYCLE_STREAM_FAILED',
96
+ error: error.message
97
+ })}\n\n`);
98
+ response.end();
99
+ }
100
+ };
101
+ publish();
102
+ const timer = setInterval(publish, 750);
103
+ timer.unref?.();
104
+ request.on('close', () => clearInterval(timer));
105
+ }
106
+
74
107
  function liveSnapshot(rootDir) {
75
108
  const run = getCurrentRun(rootDir);
76
109
  if (!run?.workflow) return null;
77
110
  const workflow = workflowStatus(rootDir, { runId: run.runId });
78
- return {
111
+ return redactedValue({
79
112
  run,
80
113
  plan: workflow.plan,
81
114
  nodes: workflow.state.nodes,
115
+ edges: edgesFromPlan(workflow.plan, workflow.state),
82
116
  loopGroups: workflow.state.loopGroups,
117
+ journey: (() => {
118
+ try {
119
+ return runJourney(rootDir, run.runId, { workflowState: workflow.state });
120
+ } catch {
121
+ return {
122
+ runId: run.runId,
123
+ current: 'UNKNOWN',
124
+ pendingQuestions: 0,
125
+ sources: { available: false },
126
+ steps: []
127
+ };
128
+ }
129
+ })(),
83
130
  budget: budgetStatus(rootDir, { runId: run.runId }),
84
131
  events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
85
132
  ...event,
86
133
  changedNodes: (changes || []).map((change) => change.nodeId)
87
134
  }))
88
- };
135
+ });
89
136
  }
90
137
 
91
138
  function bootstrap(rootDir) {
@@ -152,6 +199,8 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
152
199
  const scopedExecute = url.pathname.match(/^\/api\/runs\/([^/]+)\/execute$/);
153
200
  const scopedCancel = url.pathname.match(/^\/api\/runs\/([^/]+)\/cancel$/);
154
201
  const scopedGoal = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal$/);
202
+ const scopedLifecycle = url.pathname.match(/^\/api\/runs\/([^/]+)\/lifecycle$/);
203
+ const scopedLifecycleStream = url.pathname.match(/^\/api\/runs\/([^/]+)\/lifecycle\/stream$/);
155
204
  const scopedGoalFreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/freeze$/);
156
205
  const scopedGoalUnfreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/unfreeze$/);
157
206
  const scopedCheckout = url.pathname.match(/^\/api\/runs\/([^/]+)\/checkout$/);
@@ -248,6 +297,25 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
248
297
  ok: true,
249
298
  interactions: listRunInteractions(rootDir, decodeURIComponent(scopedInteractions[1]))
250
299
  });
300
+ } else if (request.method === 'GET' && scopedLifecycleStream) {
301
+ const runId = decodeURIComponent(scopedLifecycleStream[1]);
302
+ const after = Number(url.searchParams.get('after') || 0);
303
+ if (!Number.isSafeInteger(after) || after < 0) {
304
+ throw Object.assign(new Error('Lifecycle stream cursor is invalid'), {
305
+ code: 'INVALID_LIFECYCLE_CURSOR'
306
+ });
307
+ }
308
+ streamRunLifecycle(rootDir, runId, after, request, response);
309
+ } else if (request.method === 'GET' && scopedLifecycle) {
310
+ const runId = decodeURIComponent(scopedLifecycle[1]);
311
+ json(response, 200, {
312
+ ok: true,
313
+ lifecycle: listRunLifecycle(rootDir, runId, {
314
+ after: Number(url.searchParams.get('after') || 0),
315
+ limit: Number(url.searchParams.get('limit') || 100)
316
+ }),
317
+ presence: runAgentPresence(rootDir, runId)
318
+ });
251
319
  } else if (request.method === 'POST' && scopedQuestions) {
252
320
  const body = await readBody(request);
253
321
  json(response, 201, {
@@ -278,13 +346,48 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
278
346
  nodes: result.workflow.state.nodes,
279
347
  budget: result.budget
280
348
  });
349
+ } else if (request.method === 'GET' && scopedGoal) {
350
+ json(response, 200, {
351
+ ok: true,
352
+ draft: loadGoalDraft(rootDir, decodeURIComponent(scopedGoal[1]))
353
+ });
281
354
  } else if (request.method === 'PUT' && scopedGoal) {
282
355
  const body = await readBody(request);
283
- const goal = saveGoalDraft(rootDir, decodeURIComponent(scopedGoal[1]), body.goal);
284
- json(response, 200, { ok: true, goal, frozen: false });
356
+ const runId = decodeURIComponent(scopedGoal[1]);
357
+ const actor = body.actor || 'studio-user';
358
+ listRunLifecycle(rootDir, runId);
359
+ const draft = saveGoalDraft(rootDir, runId, body.goal, {
360
+ actor,
361
+ expectedRevision: body.expectedRevision
362
+ });
363
+ appendRunLifecycle(rootDir, runId, {
364
+ type: 'GOAL_DRAFT_UPDATED',
365
+ phase: 'goal',
366
+ actor,
367
+ message: `Goal draft revision ${draft.metadata.revision} was saved in Studio`
368
+ });
369
+ appendRunLifecycle(rootDir, runId, {
370
+ type: 'GOAL_READY',
371
+ phase: 'goal',
372
+ actor,
373
+ message: `Goal draft revision ${draft.metadata.revision} is ready for review`
374
+ });
375
+ json(response, 200, { ok: true, draft, frozen: false });
285
376
  } else if (request.method === 'POST' && scopedGoalFreeze) {
286
377
  const body = await readBody(request);
287
- const run = freezeGoal(rootDir, decodeURIComponent(scopedGoalFreeze[1]), { actor: body.actor });
378
+ const runId = decodeURIComponent(scopedGoalFreeze[1]);
379
+ listRunLifecycle(rootDir, runId);
380
+ const run = freezeGoal(rootDir, runId, {
381
+ actor: body.actor,
382
+ expectedRevision: body.expectedRevision,
383
+ expectedHash: body.expectedHash
384
+ });
385
+ appendRunLifecycle(rootDir, runId, {
386
+ type: 'GOAL_FROZEN',
387
+ phase: 'goal',
388
+ actor: body.actor || 'studio-user',
389
+ message: 'Goal Contract frozen in Studio'
390
+ });
288
391
  json(response, 200, { ok: true, run });
289
392
  } else if (request.method === 'POST' && scopedGoalUnfreeze) {
290
393
  const body = await readBody(request);
@@ -857,8 +857,8 @@ function startWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
857
857
  if (node.type === 'command') {
858
858
  throw runtimeError('Command nodes are disabled in the controlled runtime', 'COMMAND_EXECUTION_DISABLED');
859
859
  }
860
- if (node.type === 'approval' || LEGACY_NODE_TYPES.has(node.type)) {
861
- throw runtimeError(`Node ${nodeId} must use its dedicated approval or gate command`, 'WRONG_NODE_EXECUTOR');
860
+ if (node.type === 'approval') {
861
+ throw runtimeError(`Node ${nodeId} must use its dedicated approval command`, 'WRONG_NODE_EXECUTOR');
862
862
  }
863
863
  const changes = nodeChanges(workflow, nodeId, NODE_STATES.RUNNING, {
864
864
  attempts: workflow.state.nodes[nodeId].attempts + 1,
@@ -965,12 +965,13 @@ function applyWorkflowGate(rootDir, gate, { runId, now = new Date(), transitionO
965
965
  let workflow = loadWorkflow(rootDir, resolved);
966
966
  const node = workflow.plan.nodes.find((candidate) => candidate.legacyGate === gate);
967
967
  if (!node) throw runtimeError(`Workflow has no node for gate ${gate}`, 'GATE_NOT_IN_WORKFLOW');
968
- assertReady(workflow, node.id);
968
+ const before = workflow.state.nodes[node.id];
969
+ if (before.status !== NODE_STATES.RUNNING) assertReady(workflow, node.id);
969
970
  const { applyGate } = require('./gates.js');
970
971
  const run = applyGate(rootDir, gate, { runId: resolved, transitionOptions });
971
972
  workflow.run = run;
972
973
  let changes = nodeChanges(workflow, node.id, NODE_STATES.PASSED, {
973
- attempts: workflow.state.nodes[node.id].attempts + 1,
974
+ attempts: before.attempts + (before.status === NODE_STATES.READY ? 1 : 0),
974
975
  reason: null,
975
976
  activity: null
976
977
  }, now);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.9.3",
3
+ "version": "1.10.0",
4
4
  "description": "A visual workspace that helps AI coding agents plan, build, review, and ship reliable software.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {