ai-engineering-loop 1.9.3 → 1.9.4

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,164 @@
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
+ 'AGENT_HEARTBEAT',
16
+ 'AGENT_WAITING',
17
+ 'NODE_STARTED',
18
+ 'NODE_ACTIVITY',
19
+ 'NODE_COMPLETED',
20
+ 'LOOP_ITERATED',
21
+ 'RUN_COMPLETED'
22
+ ]);
23
+ const ID = /^[A-Za-z0-9@._-]{1,64}$/;
24
+ const LOCK_STALE_MS = 60_000;
25
+
26
+ function lifecycleError(message, code) {
27
+ const error = new Error(message);
28
+ error.code = code;
29
+ return error;
30
+ }
31
+
32
+ function lifecyclePath(rootDir, runId) {
33
+ assertRunId(runId);
34
+ loadRun(rootDir, runId);
35
+ return path.join(runsDir(rootDir), runId, 'lifecycle.jsonl');
36
+ }
37
+
38
+ function materialHash(event) {
39
+ const { hash, ...material } = event;
40
+ return sha256(material);
41
+ }
42
+
43
+ function readLifecycle(rootDir, runId) {
44
+ const file = lifecyclePath(rootDir, runId);
45
+ if (!fs.existsSync(file)) return [];
46
+ const stat = fs.lstatSync(file);
47
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > MAX_LEDGER_BYTES) {
48
+ throw lifecycleError('Run lifecycle must be a bounded regular file', 'INVALID_RUN_LIFECYCLE');
49
+ }
50
+ const events = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
51
+ try { return JSON.parse(line); } catch { return null; }
52
+ });
53
+ let previousHash = null;
54
+ for (const [index, event] of events.entries()) {
55
+ if (!event || event.runId !== runId || event.sequence !== index + 1 ||
56
+ event.previousHash !== previousHash || event.hash !== materialHash(event) ||
57
+ !TYPES.has(event.type)) {
58
+ throw lifecycleError(`Run lifecycle event ${index + 1} failed integrity validation`, 'INVALID_RUN_LIFECYCLE');
59
+ }
60
+ previousHash = event.hash;
61
+ }
62
+ return events;
63
+ }
64
+
65
+ function withLock(rootDir, runId, operation) {
66
+ const lock = `${lifecyclePath(rootDir, runId)}.lock`;
67
+ let descriptor;
68
+ try {
69
+ try {
70
+ descriptor = fs.openSync(lock, 'wx', 0o600);
71
+ } catch (error) {
72
+ if (error.code !== 'EEXIST') throw error;
73
+ const stat = fs.lstatSync(lock);
74
+ if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
75
+ throw lifecycleError('Another lifecycle update is in progress', 'RUN_LIFECYCLE_BUSY');
76
+ }
77
+ fs.unlinkSync(lock);
78
+ descriptor = fs.openSync(lock, 'wx', 0o600);
79
+ }
80
+ return operation();
81
+ } finally {
82
+ if (descriptor != null) {
83
+ fs.closeSync(descriptor);
84
+ try { fs.unlinkSync(lock); } catch {}
85
+ }
86
+ }
87
+ }
88
+
89
+ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
90
+ return withLock(rootDir, runId, () => {
91
+ if (!TYPES.has(event?.type)) {
92
+ throw lifecycleError('Lifecycle type is not allowed', 'INVALID_LIFECYCLE_TYPE');
93
+ }
94
+ const actor = String(event.actor || 'agent').trim();
95
+ if (!ID.test(actor)) throw lifecycleError('Lifecycle actor is invalid', 'INVALID_LIFECYCLE_ACTOR');
96
+ const phase = event.phase == null ? null : String(event.phase).trim();
97
+ const nodeId = event.nodeId == null ? null : String(event.nodeId).trim();
98
+ if ((phase && !ID.test(phase)) || (nodeId && !ID.test(nodeId))) {
99
+ throw lifecycleError('Lifecycle phase or node is invalid', 'INVALID_LIFECYCLE_SCOPE');
100
+ }
101
+ const message = redactSecrets(String(event.message || '').trim()).text;
102
+ if (!message || message.length > 240 ||
103
+ /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(message)) {
104
+ throw lifecycleError('Lifecycle message must be 1-240 printable characters', 'INVALID_LIFECYCLE_MESSAGE');
105
+ }
106
+ const events = readLifecycle(rootDir, runId);
107
+ if (events.length >= MAX_EVENTS) {
108
+ throw lifecycleError('Run lifecycle event limit reached', 'RUN_LIFECYCLE_LIMIT');
109
+ }
110
+ const material = {
111
+ schemaVersion: 1,
112
+ runId,
113
+ sequence: events.length + 1,
114
+ previousHash: events.at(-1)?.hash || null,
115
+ at: now.toISOString(),
116
+ type: event.type,
117
+ actor,
118
+ message,
119
+ ...(phase ? { phase } : {}),
120
+ ...(nodeId ? { nodeId } : {})
121
+ };
122
+ const result = { ...material, hash: sha256(material) };
123
+ fs.appendFileSync(lifecyclePath(rootDir, runId), `${JSON.stringify(result)}\n`, {
124
+ encoding: 'utf8',
125
+ mode: 0o600,
126
+ flag: 'a'
127
+ });
128
+ return result;
129
+ });
130
+ }
131
+
132
+ function listRunLifecycle(rootDir, runId, { after = 0, limit = 100 } = {}) {
133
+ const cursor = Number(after);
134
+ const pageSize = Number(limit);
135
+ if (!Number.isSafeInteger(cursor) || cursor < 0 ||
136
+ !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
137
+ throw lifecycleError('Lifecycle cursor or limit is invalid', 'INVALID_LIFECYCLE_CURSOR');
138
+ }
139
+ const events = readLifecycle(rootDir, runId).filter((event) => event.sequence > cursor).slice(0, pageSize);
140
+ return {
141
+ runId,
142
+ events,
143
+ nextSequence: events.at(-1)?.sequence || cursor
144
+ };
145
+ }
146
+
147
+ function runAgentPresence(rootDir, runId, { now = new Date() } = {}) {
148
+ const events = readLifecycle(rootDir, runId);
149
+ const last = events.findLast((event) => event.type === 'AGENT_HEARTBEAT');
150
+ if (!last) return { status: 'UNKNOWN', lastHeartbeatAt: null };
151
+ const ageMs = Math.max(0, now.getTime() - Date.parse(last.at));
152
+ return {
153
+ status: ageMs < 10_000 ? 'WORKING' : ageMs <= 30_000 ? 'IDLE' : 'DISCONNECTED',
154
+ lastHeartbeatAt: last.at,
155
+ ageMs
156
+ };
157
+ }
158
+
159
+ module.exports = {
160
+ MAX_EVENTS,
161
+ appendRunLifecycle,
162
+ listRunLifecycle,
163
+ runAgentPresence
164
+ };
@@ -38,7 +38,8 @@ const {
38
38
  appendRunQuestion,
39
39
  listRunInteractions
40
40
  } = require('./run-interactions.js');
41
- const { saveGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
41
+ const { saveGoalDraft, loadGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
42
+ const { appendRunLifecycle, listRunLifecycle, runAgentPresence } = require('./run-lifecycle.js');
42
43
  const { cancelStudioRun, createStudioRun, executeStudioRun } = require('./studio-runtime.js');
43
44
  const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
44
45
  const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
@@ -71,6 +72,35 @@ function readBody(request) {
71
72
  });
72
73
  }
73
74
 
75
+ function streamRunLifecycle(rootDir, runId, after, request, response) {
76
+ let cursor = after;
77
+ response.writeHead(200, {
78
+ 'content-type': 'text/event-stream; charset=utf-8',
79
+ 'cache-control': 'no-store',
80
+ connection: 'keep-alive'
81
+ });
82
+ const publish = () => {
83
+ try {
84
+ const lifecycle = listRunLifecycle(rootDir, runId, { after: cursor, limit: 100 });
85
+ cursor = lifecycle.nextSequence;
86
+ response.write(`data: ${JSON.stringify({
87
+ lifecycle,
88
+ presence: runAgentPresence(rootDir, runId)
89
+ })}\n\n`);
90
+ } catch (error) {
91
+ response.write(`event: error\ndata: ${JSON.stringify({
92
+ code: error.code || 'LIFECYCLE_STREAM_FAILED',
93
+ error: error.message
94
+ })}\n\n`);
95
+ response.end();
96
+ }
97
+ };
98
+ publish();
99
+ const timer = setInterval(publish, 750);
100
+ timer.unref?.();
101
+ request.on('close', () => clearInterval(timer));
102
+ }
103
+
74
104
  function liveSnapshot(rootDir) {
75
105
  const run = getCurrentRun(rootDir);
76
106
  if (!run?.workflow) return null;
@@ -152,6 +182,8 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
152
182
  const scopedExecute = url.pathname.match(/^\/api\/runs\/([^/]+)\/execute$/);
153
183
  const scopedCancel = url.pathname.match(/^\/api\/runs\/([^/]+)\/cancel$/);
154
184
  const scopedGoal = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal$/);
185
+ const scopedLifecycle = url.pathname.match(/^\/api\/runs\/([^/]+)\/lifecycle$/);
186
+ const scopedLifecycleStream = url.pathname.match(/^\/api\/runs\/([^/]+)\/lifecycle\/stream$/);
155
187
  const scopedGoalFreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/freeze$/);
156
188
  const scopedGoalUnfreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/unfreeze$/);
157
189
  const scopedCheckout = url.pathname.match(/^\/api\/runs\/([^/]+)\/checkout$/);
@@ -248,6 +280,25 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
248
280
  ok: true,
249
281
  interactions: listRunInteractions(rootDir, decodeURIComponent(scopedInteractions[1]))
250
282
  });
283
+ } else if (request.method === 'GET' && scopedLifecycleStream) {
284
+ const runId = decodeURIComponent(scopedLifecycleStream[1]);
285
+ const after = Number(url.searchParams.get('after') || 0);
286
+ if (!Number.isSafeInteger(after) || after < 0) {
287
+ throw Object.assign(new Error('Lifecycle stream cursor is invalid'), {
288
+ code: 'INVALID_LIFECYCLE_CURSOR'
289
+ });
290
+ }
291
+ streamRunLifecycle(rootDir, runId, after, request, response);
292
+ } else if (request.method === 'GET' && scopedLifecycle) {
293
+ const runId = decodeURIComponent(scopedLifecycle[1]);
294
+ json(response, 200, {
295
+ ok: true,
296
+ lifecycle: listRunLifecycle(rootDir, runId, {
297
+ after: Number(url.searchParams.get('after') || 0),
298
+ limit: Number(url.searchParams.get('limit') || 100)
299
+ }),
300
+ presence: runAgentPresence(rootDir, runId)
301
+ });
251
302
  } else if (request.method === 'POST' && scopedQuestions) {
252
303
  const body = await readBody(request);
253
304
  json(response, 201, {
@@ -278,13 +329,48 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
278
329
  nodes: result.workflow.state.nodes,
279
330
  budget: result.budget
280
331
  });
332
+ } else if (request.method === 'GET' && scopedGoal) {
333
+ json(response, 200, {
334
+ ok: true,
335
+ draft: loadGoalDraft(rootDir, decodeURIComponent(scopedGoal[1]))
336
+ });
281
337
  } else if (request.method === 'PUT' && scopedGoal) {
282
338
  const body = await readBody(request);
283
- const goal = saveGoalDraft(rootDir, decodeURIComponent(scopedGoal[1]), body.goal);
284
- json(response, 200, { ok: true, goal, frozen: false });
339
+ const runId = decodeURIComponent(scopedGoal[1]);
340
+ const actor = body.actor || 'studio-user';
341
+ listRunLifecycle(rootDir, runId);
342
+ const draft = saveGoalDraft(rootDir, runId, body.goal, {
343
+ actor,
344
+ expectedRevision: body.expectedRevision
345
+ });
346
+ appendRunLifecycle(rootDir, runId, {
347
+ type: 'GOAL_DRAFT_UPDATED',
348
+ phase: 'goal',
349
+ actor,
350
+ message: `Goal draft revision ${draft.metadata.revision} was saved in Studio`
351
+ });
352
+ appendRunLifecycle(rootDir, runId, {
353
+ type: 'GOAL_READY',
354
+ phase: 'goal',
355
+ actor,
356
+ message: `Goal draft revision ${draft.metadata.revision} is ready for review`
357
+ });
358
+ json(response, 200, { ok: true, draft, frozen: false });
285
359
  } else if (request.method === 'POST' && scopedGoalFreeze) {
286
360
  const body = await readBody(request);
287
- const run = freezeGoal(rootDir, decodeURIComponent(scopedGoalFreeze[1]), { actor: body.actor });
361
+ const runId = decodeURIComponent(scopedGoalFreeze[1]);
362
+ listRunLifecycle(rootDir, runId);
363
+ const run = freezeGoal(rootDir, runId, {
364
+ actor: body.actor,
365
+ expectedRevision: body.expectedRevision,
366
+ expectedHash: body.expectedHash
367
+ });
368
+ appendRunLifecycle(rootDir, runId, {
369
+ type: 'NODE_COMPLETED',
370
+ phase: 'goal',
371
+ actor: body.actor || 'studio-user',
372
+ message: 'Goal Contract frozen in Studio'
373
+ });
288
374
  json(response, 200, { ok: true, run });
289
375
  } else if (request.method === 'POST' && scopedGoalUnfreeze) {
290
376
  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.9.4",
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": {