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.
- package/.agents/workflows/ai-engineering-loop.md +2 -2
- package/.claude/skills/ai-engineering-loop/SKILL.md +3 -1
- package/.gemini/skills/ai-engineering-loop/SKILL.md +3 -1
- package/.grok/skills/ai-engineering-loop/SKILL.md +3 -1
- package/bin/ai-engineering-loop.js +248 -0
- package/lib/goal-runtime.js +149 -15
- package/lib/run-lifecycle.js +164 -0
- package/lib/studio-server.js +90 -4
- package/lib/workflow-runtime.js +5 -4
- package/package.json +1 -1
- package/studio/app.js +213 -18
- package/studio/index.html +1 -0
- package/studio/styles.css +4 -2
|
@@ -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
|
+
};
|
package/lib/studio-server.js
CHANGED
|
@@ -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
|
|
284
|
-
|
|
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
|
|
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);
|
package/lib/workflow-runtime.js
CHANGED
|
@@ -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'
|
|
861
|
-
throw runtimeError(`Node ${nodeId} must use its dedicated approval
|
|
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
|
-
|
|
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:
|
|
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