ai-engineering-loop 1.5.0 → 1.6.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,183 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const http = require('http');
6
+ const path = require('path');
7
+ const { URL } = require('url');
8
+ const { listRecipes, loadRecipe, validateRecipe, compileRecipe } = require('./recipe.js');
9
+ const { inspectRecipe, installRecipe, recipeCatalog } = require('./recipe-builder.js');
10
+ const { getCurrentRun } = require('./run-state.js');
11
+ const { budgetStatus } = require('./budget.js');
12
+ const {
13
+ workflowStatus,
14
+ approveWorkflowNode,
15
+ retryWorkflowNode,
16
+ recordWorkflowActivity
17
+ } = require('./workflow-runtime.js');
18
+ const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
19
+
20
+ const MAX_BODY = 256 * 1024;
21
+ const ASSET_DIR = path.join(__dirname, '..', 'studio');
22
+
23
+ function json(response, status, value) {
24
+ response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
25
+ response.end(JSON.stringify(value));
26
+ }
27
+
28
+ function readBody(request) {
29
+ return new Promise((resolve, reject) => {
30
+ let text = '';
31
+ request.setEncoding('utf8');
32
+ request.on('data', (chunk) => {
33
+ text += chunk;
34
+ if (Buffer.byteLength(text) > MAX_BODY) request.destroy(new Error('Request body exceeds 256 KiB'));
35
+ });
36
+ request.on('end', () => {
37
+ try { resolve(text ? JSON.parse(text) : {}); } catch (error) { reject(error); }
38
+ });
39
+ request.on('error', reject);
40
+ });
41
+ }
42
+
43
+ function liveSnapshot(rootDir) {
44
+ const run = getCurrentRun(rootDir);
45
+ if (!run?.workflow) return null;
46
+ const workflow = workflowStatus(rootDir, { runId: run.runId });
47
+ return {
48
+ run,
49
+ plan: workflow.plan,
50
+ nodes: workflow.state.nodes,
51
+ budget: budgetStatus(rootDir, { runId: run.runId }),
52
+ events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
53
+ ...event,
54
+ changedNodes: (changes || []).map((change) => change.nodeId)
55
+ }))
56
+ };
57
+ }
58
+
59
+ function bootstrap(rootDir) {
60
+ const recipes = listRecipes(rootDir).map(({ id, source }) => ({ ...inspectRecipe(rootDir, id), source }));
61
+ return { recipes, nodeTypes: recipeCatalog(), live: liveSnapshot(rootDir) };
62
+ }
63
+
64
+ function constantTimeEqual(left, right) {
65
+ const a = Buffer.from(String(left || ''));
66
+ const b = Buffer.from(String(right || ''));
67
+ return a.length === b.length && crypto.timingSafeEqual(a, b);
68
+ }
69
+
70
+ function localHostname(hostHeader) {
71
+ try {
72
+ return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, '');
73
+ } catch {
74
+ return '';
75
+ }
76
+ }
77
+
78
+ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('base64url') } = {}) {
79
+ const server = http.createServer(async (request, response) => {
80
+ const hostHeader = String(request.headers.host || '');
81
+ const host = localHostname(hostHeader);
82
+ if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
83
+ response.writeHead(403).end('Forbidden host');
84
+ return;
85
+ }
86
+ const url = new URL(request.url, `http://${hostHeader}`);
87
+ const cookieToken = String(request.headers.cookie || '').split(';').map((item) => item.trim())
88
+ .find((item) => item.startsWith('ael_studio='))?.slice('ael_studio='.length);
89
+ const supplied = request.headers['x-ael-studio-token'] || cookieToken;
90
+ if (url.pathname === '/' && constantTimeEqual(url.searchParams.get('token'), token)) {
91
+ response.writeHead(302, {
92
+ location: '/',
93
+ 'set-cookie': `ael_studio=${token}; HttpOnly; SameSite=Strict; Path=/`,
94
+ 'cache-control': 'no-store',
95
+ 'referrer-policy': 'no-referrer'
96
+ }).end();
97
+ return;
98
+ }
99
+ if (!constantTimeEqual(supplied, token)) {
100
+ response.writeHead(401).end('Studio session required');
101
+ return;
102
+ }
103
+ response.setHeader('content-security-policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
104
+ response.setHeader('x-content-type-options', 'nosniff');
105
+ response.setHeader('referrer-policy', 'no-referrer');
106
+ try {
107
+ if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
108
+ json(response, 200, { ok: true, ...bootstrap(rootDir) });
109
+ } else if (request.method === 'GET' && url.pathname === '/api/live') {
110
+ json(response, 200, { ok: true, live: liveSnapshot(rootDir) });
111
+ } else if (request.method === 'GET' && url.pathname === '/api/recipe') {
112
+ const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
113
+ json(response, 200, { ok: true, source: loaded.source, recipe: loaded.recipe });
114
+ } else if (request.method === 'POST' && url.pathname === '/api/validate') {
115
+ const body = await readBody(request);
116
+ const validation = validateRecipe(body.recipe, body.mode ? { mode: body.mode } : {});
117
+ json(response, validation.valid ? 200 : 422, {
118
+ ok: validation.valid,
119
+ validation,
120
+ plans: validation.valid
121
+ ? (body.mode ? [body.mode] : body.recipe.compatibleModes).map((mode) => compileRecipe(body.recipe, { mode }))
122
+ : []
123
+ });
124
+ } else if (request.method === 'POST' && url.pathname === '/api/install') {
125
+ const body = await readBody(request);
126
+ const drafts = path.join(rootDir, '.ai-engineering-loop', 'drafts');
127
+ fs.mkdirSync(drafts, { recursive: true, mode: 0o700 });
128
+ const candidate = path.join(drafts, `${crypto.randomUUID()}.json`);
129
+ fs.writeFileSync(candidate, JSON.stringify(body.recipe), { mode: 0o600 });
130
+ try {
131
+ const result = installRecipe(rootDir, path.relative(rootDir, candidate), { replace: body.replace === true });
132
+ json(response, 200, { ok: true, id: result.recipe.id, version: result.recipe.version, sourceHash: result.sourceHash });
133
+ } finally {
134
+ try { fs.unlinkSync(candidate); } catch {}
135
+ }
136
+ } else if (request.method === 'GET' && url.pathname === '/api/handoff') {
137
+ const bundle = createHandoff(rootDir, { audience: url.searchParams.get('audience') || 'developer' });
138
+ json(response, 200, { ok: true, bundle, brief: handoffBrief(bundle) });
139
+ } else if (request.method === 'POST' && url.pathname === '/api/node/approve') {
140
+ const body = await readBody(request);
141
+ approveWorkflowNode(rootDir, body.nodeId, { runId: body.runId, approvedBy: body.approvedBy || 'human' });
142
+ json(response, 200, { ok: true });
143
+ } else if (request.method === 'POST' && url.pathname === '/api/node/retry') {
144
+ const body = await readBody(request);
145
+ retryWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
146
+ json(response, 200, { ok: true });
147
+ } else if (request.method === 'POST' && url.pathname === '/api/node/activity') {
148
+ const body = await readBody(request);
149
+ recordWorkflowActivity(rootDir, body.nodeId, {
150
+ runId: body.runId,
151
+ message: body.message
152
+ });
153
+ json(response, 200, { ok: true });
154
+ } else if (request.method === 'POST' && url.pathname === '/api/decision') {
155
+ const body = await readBody(request);
156
+ const result = recordDecision(rootDir, {
157
+ runId: body.runId,
158
+ summary: body.summary,
159
+ rationale: body.rationale,
160
+ consequences: body.consequences
161
+ });
162
+ json(response, 200, { ok: true, ...result });
163
+ } else {
164
+ const asset = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
165
+ if (!['index.html', 'app.js', 'styles.css'].includes(asset)) {
166
+ response.writeHead(404).end('Not found');
167
+ return;
168
+ }
169
+ const types = { html: 'text/html', js: 'text/javascript', css: 'text/css' };
170
+ response.writeHead(200, {
171
+ 'content-type': `${types[asset.split('.').at(-1)]}; charset=utf-8`,
172
+ 'cache-control': 'no-store'
173
+ });
174
+ response.end(fs.readFileSync(path.join(ASSET_DIR, asset)));
175
+ }
176
+ } catch (error) {
177
+ json(response, 400, { ok: false, code: error.code || 'STUDIO_ERROR', error: error.message, details: error.details || [] });
178
+ }
179
+ });
180
+ return { server, token };
181
+ }
182
+
183
+ module.exports = { createStudioServer, bootstrap, liveSnapshot };
@@ -3,6 +3,7 @@
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
5
  const { sha256 } = require('./recipe.js');
6
+ const { redactSecrets } = require('./safe-context.js');
6
7
  const {
7
8
  RUN_STATES,
8
9
  atomicWriteJson,
@@ -531,6 +532,7 @@ function completeWorkflowNode(rootDir, nodeId, { runId, artifact, now = new Date
531
532
  let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
532
533
  attempts: workflow.state.nodes[nodeId].attempts + (currentStatus === NODE_STATES.READY ? 1 : 0),
533
534
  reason: null,
535
+ activity: null,
534
536
  ...(artifactDescriptor ? { artifact: artifactDescriptor } : {})
535
537
  }, now);
536
538
  changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
@@ -551,12 +553,31 @@ function startWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
551
553
  }
552
554
  const changes = nodeChanges(workflow, nodeId, NODE_STATES.RUNNING, {
553
555
  attempts: workflow.state.nodes[nodeId].attempts + 1,
554
- reason: null
556
+ reason: null,
557
+ activity: 'Node started'
555
558
  }, now);
556
559
  return commitChanges(rootDir, workflow, 'NODE_STARTED', changes, { nodeId }, now);
557
560
  });
558
561
  }
559
562
 
563
+ function recordWorkflowActivity(rootDir, nodeId, { runId, message, now = new Date() } = {}) {
564
+ const resolved = resolveRunId(rootDir, runId);
565
+ return withWorkflowLock(rootDir, resolved, () => {
566
+ const workflow = loadWorkflow(rootDir, resolved);
567
+ const current = workflow.state.nodes[nodeId];
568
+ if (!current) throw runtimeError(`Unknown workflow node: ${nodeId}`, 'UNKNOWN_WORKFLOW_NODE');
569
+ if (current.status !== NODE_STATES.RUNNING) {
570
+ throw runtimeError(`Node ${nodeId} is ${current.status}, not RUNNING`, 'INVALID_NODE_TRANSITION');
571
+ }
572
+ const activity = redactSecrets(String(message || '').trim()).text;
573
+ if (!activity || activity.length > 240 || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(activity)) {
574
+ throw runtimeError('Activity must be 1-240 printable characters', 'INVALID_NODE_ACTIVITY');
575
+ }
576
+ const changes = nodeChanges(workflow, nodeId, NODE_STATES.RUNNING, { activity }, now);
577
+ return commitChanges(rootDir, workflow, 'NODE_ACTIVITY', changes, { nodeId }, now);
578
+ });
579
+ }
580
+
560
581
  function failWorkflowNode(rootDir, nodeId, { runId, reason = 'node execution failed', now = new Date() } = {}) {
561
582
  const resolved = resolveRunId(rootDir, runId);
562
583
  return withWorkflowLock(rootDir, resolved, () => {
@@ -566,9 +587,11 @@ function failWorkflowNode(rootDir, nodeId, { runId, reason = 'node execution fai
566
587
  if (![NODE_STATES.READY, NODE_STATES.RUNNING].includes(current.status)) {
567
588
  throw runtimeError(`Node ${nodeId} cannot fail from ${current.status}`, 'INVALID_NODE_TRANSITION');
568
589
  }
590
+ const safeReason = redactSecrets(String(reason)).text.slice(0, 500);
569
591
  let changes = nodeChanges(workflow, nodeId, NODE_STATES.FAILED, {
570
592
  attempts: current.attempts + (current.status === NODE_STATES.READY ? 1 : 0),
571
- reason: String(reason).slice(0, 500)
593
+ reason: safeReason,
594
+ activity: null
572
595
  }, now);
573
596
  changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
574
597
  return commitChanges(rootDir, workflow, 'NODE_FAILED', changes, { nodeId }, now);
@@ -584,7 +607,7 @@ function retryWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
584
607
  if (![NODE_STATES.FAILED, NODE_STATES.RUNNING].includes(current.status)) {
585
608
  throw runtimeError(`Node ${nodeId} cannot retry from ${current.status}`, 'INVALID_NODE_TRANSITION');
586
609
  }
587
- let changes = nodeChanges(workflow, nodeId, NODE_STATES.READY, { reason: null }, now);
610
+ let changes = nodeChanges(workflow, nodeId, NODE_STATES.READY, { reason: null, activity: null }, now);
588
611
  changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
589
612
  return commitChanges(rootDir, workflow, 'NODE_RETRIED', changes, { nodeId }, now);
590
613
  });
@@ -604,6 +627,7 @@ function approveWorkflowNode(rootDir, nodeId, { runId, approvedBy = 'human', now
604
627
  let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
605
628
  attempts: workflow.state.nodes[nodeId].attempts + 1,
606
629
  reason: null,
630
+ activity: null,
607
631
  approvedBy
608
632
  }, now);
609
633
  changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
@@ -638,7 +662,8 @@ function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
638
662
  workflow.run = run;
639
663
  let changes = nodeChanges(workflow, node.id, NODE_STATES.PASSED, {
640
664
  attempts: workflow.state.nodes[node.id].attempts + 1,
641
- reason: null
665
+ reason: null,
666
+ activity: null
642
667
  }, now);
643
668
  if (gate === 'judge' && run.state === RUN_STATES.GOAL_FROZEN) {
644
669
  const maker = workflow.plan.nodes.find((candidate) => candidate.type === 'maker');
@@ -684,6 +709,7 @@ module.exports = {
684
709
  completeWorkflowNode,
685
710
  failWorkflowNode,
686
711
  retryWorkflowNode,
712
+ recordWorkflowActivity,
687
713
  approveWorkflowNode,
688
714
  applyWorkflowGate,
689
715
  evaluateCondition,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "A reusable, framework-agnostic AI Engineering Operating System for safe coding agents.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {
@@ -16,6 +16,7 @@
16
16
  "adapters/",
17
17
  "recipes/",
18
18
  "schemas/",
19
+ "studio/",
19
20
  "evals/",
20
21
  ".agents/",
21
22
  ".grok/",
@@ -0,0 +1,36 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/handoff.schema.json",
4
+ "title": "AI Engineering Loop Redacted Handoff",
5
+ "type": "object",
6
+ "required": [
7
+ "schemaVersion",
8
+ "audience",
9
+ "runId",
10
+ "generatedAt",
11
+ "finalState",
12
+ "redacted",
13
+ "sourceIncluded",
14
+ "redactionCategories",
15
+ "content",
16
+ "bundleHash"
17
+ ],
18
+ "properties": {
19
+ "schemaVersion": { "const": 1 },
20
+ "audience": { "enum": ["developer", "agent", "auditor"] },
21
+ "runId": { "type": "string", "minLength": 1 },
22
+ "generatedAt": { "type": "string", "format": "date-time" },
23
+ "graphHash": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
24
+ "finalState": { "type": "string", "minLength": 1 },
25
+ "redacted": { "const": true },
26
+ "sourceIncluded": { "const": false },
27
+ "redactionCategories": {
28
+ "type": "array",
29
+ "items": { "type": "string" },
30
+ "uniqueItems": true
31
+ },
32
+ "content": { "type": "object" },
33
+ "bundleHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
34
+ },
35
+ "additionalProperties": false
36
+ }
@@ -13,6 +13,7 @@
13
13
  "enum": [
14
14
  "WORKFLOW_CREATED",
15
15
  "NODE_STARTED",
16
+ "NODE_ACTIVITY",
16
17
  "NODE_COMPLETED",
17
18
  "NODE_FAILED",
18
19
  "NODE_RETRIED",