ai-engineering-loop 1.5.0 → 1.7.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.
package/lib/handoff.js ADDED
@@ -0,0 +1,209 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { canonicalJson, sha256 } = require('./recipe.js');
6
+ const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
7
+ const { redactSecrets } = require('./safe-context.js');
8
+ const { workflowStatus } = require('./workflow-runtime.js');
9
+
10
+ const AUDIENCES = new Set(['developer', 'agent', 'auditor']);
11
+ const MAX_BUNDLE_BYTES = 1024 * 1024;
12
+
13
+ function handoffError(message, code = 'HANDOFF_FAILED') {
14
+ const error = new Error(message);
15
+ error.code = code;
16
+ return error;
17
+ }
18
+
19
+ function resolveRun(rootDir, runId) {
20
+ const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
21
+ if (!run) throw handoffError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
22
+ return run;
23
+ }
24
+
25
+ function redactValue(value, categories) {
26
+ if (typeof value === 'string') {
27
+ const result = redactSecrets(value);
28
+ result.categories.forEach((category) => categories.add(category));
29
+ const redacted = result.text
30
+ .replace(/(?:file:\/\/)?\/?Users\/[A-Za-z0-9._-]+/g, '[REDACTED HOME]')
31
+ .replace(/\b[A-Z]:\\Users\\[^\\\s]+/gi, '[REDACTED HOME]');
32
+ if (redacted !== result.text) categories.add('HOME_PATH');
33
+ return redacted;
34
+ }
35
+ if (Array.isArray(value)) return value.map((item) => redactValue(item, categories));
36
+ if (value && typeof value === 'object') {
37
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item, categories)]));
38
+ }
39
+ return value;
40
+ }
41
+
42
+ function loadOptionalJson(filePath) {
43
+ if (!fs.existsSync(filePath)) return null;
44
+ const stat = fs.lstatSync(filePath);
45
+ if (stat.isSymbolicLink() || !stat.isFile()) throw handoffError('Optional handoff input must be a regular file');
46
+ try {
47
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
48
+ } catch (cause) {
49
+ throw handoffError(`Optional handoff input is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF_INPUT');
50
+ }
51
+ }
52
+
53
+ function recordDecision(rootDir, {
54
+ runId,
55
+ summary,
56
+ rationale,
57
+ consequences = [],
58
+ now = new Date()
59
+ } = {}) {
60
+ const run = resolveRun(rootDir, runId);
61
+ if (typeof summary !== 'string' || !summary.trim() || summary.trim().length > 160) {
62
+ throw handoffError('Decision summary must be 1-160 characters', 'INVALID_DECISION');
63
+ }
64
+ if (typeof rationale !== 'string' || !rationale.trim() || rationale.trim().length > 1000) {
65
+ throw handoffError('Decision rationale must be 1-1000 characters', 'INVALID_DECISION');
66
+ }
67
+ if (!Array.isArray(consequences) || consequences.length > 20 || consequences.some(
68
+ (item) => typeof item !== 'string' || !item.trim() || item.length > 240
69
+ )) {
70
+ throw handoffError('Decision consequences must contain at most 20 short strings', 'INVALID_DECISION');
71
+ }
72
+ const filePath = path.join(runsDir(rootDir), run.runId, 'decisions.json');
73
+ const decisions = loadOptionalJson(filePath) || [];
74
+ if (!Array.isArray(decisions) || decisions.length >= 100) {
75
+ throw handoffError('Decision memory must be an array with fewer than 100 entries', 'INVALID_DECISION');
76
+ }
77
+ const categories = new Set();
78
+ const entry = redactValue({
79
+ id: `decision-${String(decisions.length + 1).padStart(3, '0')}`,
80
+ summary: summary.trim(),
81
+ rationale: rationale.trim(),
82
+ consequences: consequences.map((item) => item.trim()),
83
+ recordedAt: now.toISOString()
84
+ }, categories);
85
+ atomicWriteJson(filePath, [...decisions, entry]);
86
+ return { runId: run.runId, decision: entry, redactionCategories: [...categories].sort() };
87
+ }
88
+
89
+ function createHandoff(rootDir, { runId, audience = 'developer', now = new Date() } = {}) {
90
+ if (!AUDIENCES.has(audience)) throw handoffError(`Invalid audience: ${audience}`);
91
+ const run = resolveRun(rootDir, runId);
92
+ const directory = path.join(runsDir(rootDir), run.runId);
93
+ const workflow = run.workflow ? workflowStatus(rootDir, { runId: run.runId }) : null;
94
+ const decisions = loadOptionalJson(path.join(directory, 'decisions.json')) || [];
95
+ if (!Array.isArray(decisions)) throw handoffError('Decision memory must be an array', 'INVALID_HANDOFF_INPUT');
96
+ const categories = new Set();
97
+ const content = redactValue({
98
+ objective: run.task,
99
+ state: run.state,
100
+ mode: run.mode,
101
+ iteration: run.iteration,
102
+ recipe: run.workflow || null,
103
+ nodes: workflow ? workflow.plan.nodes.map((node) => ({
104
+ id: node.id,
105
+ type: node.type,
106
+ status: workflow.state.nodes[node.id].status,
107
+ attempts: workflow.state.nodes[node.id].attempts,
108
+ reason: workflow.state.nodes[node.id].reason || null,
109
+ activity: workflow.state.nodes[node.id].activity || null
110
+ })) : [],
111
+ artifacts: run.artifacts,
112
+ decisions,
113
+ transitions: run.history,
114
+ nextActions: workflow
115
+ ? workflow.plan.nodes.filter((node) => workflow.state.nodes[node.id].status === 'READY').map((node) => node.id)
116
+ : []
117
+ }, categories);
118
+ const material = {
119
+ schemaVersion: 1,
120
+ audience,
121
+ runId: run.runId,
122
+ generatedAt: now.toISOString(),
123
+ graphHash: run.workflow?.graphHash || null,
124
+ finalState: run.state,
125
+ redacted: true,
126
+ sourceIncluded: false,
127
+ redactionCategories: [...categories].sort(),
128
+ content
129
+ };
130
+ return { ...material, bundleHash: sha256(material) };
131
+ }
132
+
133
+ function handoffBrief(bundle) {
134
+ const lines = [
135
+ '# Engineering Handoff',
136
+ '',
137
+ `Run: ${bundle.runId}`,
138
+ `State: ${bundle.finalState}`,
139
+ `Mode: ${bundle.content.mode}`,
140
+ `Graph: ${bundle.graphHash || 'legacy'}`,
141
+ '',
142
+ '## Objective',
143
+ bundle.content.objective || 'Not recorded.',
144
+ '',
145
+ '## Workflow',
146
+ ...bundle.content.nodes.map((node) => `- ${node.id}: ${node.status}${node.reason ? ` — ${node.reason}` : ''}`),
147
+ '',
148
+ '## Decisions',
149
+ ...(bundle.content.decisions.length ? bundle.content.decisions.map((decision) => `- ${decision.decision || decision.summary || JSON.stringify(decision)}`) : ['- None recorded.']),
150
+ '',
151
+ '## Evidence',
152
+ ...Object.entries(bundle.content.artifacts).map(([name, artifact]) => (
153
+ `- ${name}: ${artifact && typeof artifact === 'object' ? artifact.sha256 || 'recorded' : 'recorded'}`
154
+ )),
155
+ '',
156
+ '## Next actions',
157
+ ...(bundle.content.nextActions.length ? bundle.content.nextActions.map((action) => `- ${action}`) : ['- No READY nodes.'])
158
+ ];
159
+ return lines.join('\n');
160
+ }
161
+
162
+ function verifyHandoff(bundle) {
163
+ if (!bundle || bundle.schemaVersion !== 1 || !AUDIENCES.has(bundle.audience)) {
164
+ throw handoffError('Handoff manifest is invalid', 'INVALID_HANDOFF');
165
+ }
166
+ const { bundleHash, ...material } = bundle;
167
+ if (bundleHash !== sha256(material)) throw handoffError('Handoff bundle hash does not match', 'HANDOFF_TAMPERED');
168
+ return {
169
+ valid: true,
170
+ runId: bundle.runId,
171
+ audience: bundle.audience,
172
+ bundleHash,
173
+ canonicalBytes: Buffer.byteLength(canonicalJson(bundle))
174
+ };
175
+ }
176
+
177
+ function readHandoff(rootDir, file) {
178
+ const absolute = path.resolve(rootDir, file);
179
+ const relative = path.relative(rootDir, absolute);
180
+ if (relative === '..' || relative.startsWith(`..${path.sep}`)) throw handoffError('Handoff path escapes repository');
181
+ let stat;
182
+ try {
183
+ stat = fs.lstatSync(absolute);
184
+ } catch (cause) {
185
+ throw handoffError(`Unable to inspect handoff: ${cause.message}`, 'INVALID_HANDOFF');
186
+ }
187
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_BUNDLE_BYTES) {
188
+ throw handoffError('Handoff must be a regular file under 1 MiB');
189
+ }
190
+ const realRoot = fs.realpathSync(rootDir);
191
+ const realFile = fs.realpathSync(absolute);
192
+ if (realFile !== realRoot && !realFile.startsWith(`${realRoot}${path.sep}`)) {
193
+ throw handoffError('Handoff path escapes repository through a symlink');
194
+ }
195
+ try {
196
+ return JSON.parse(fs.readFileSync(absolute, 'utf8'));
197
+ } catch (cause) {
198
+ throw handoffError(`Handoff is invalid JSON: ${cause.message}`, 'INVALID_HANDOFF');
199
+ }
200
+ }
201
+
202
+ module.exports = {
203
+ AUDIENCES,
204
+ createHandoff,
205
+ handoffBrief,
206
+ recordDecision,
207
+ verifyHandoff,
208
+ readHandoff
209
+ };
@@ -142,6 +142,7 @@ function recipeCatalog() {
142
142
  type,
143
143
  label: definition.label,
144
144
  category: definition.category,
145
+ builtIn: definition.builtIn,
145
146
  capabilities: {
146
147
  repositoryMutation: definition.mutation,
147
148
  remoteSideEffect: definition.sideEffect,
@@ -8,6 +8,8 @@ const PRIVATE_RUNTIME_PATTERNS = Object.freeze([
8
8
  'usage/',
9
9
  'worktrees/',
10
10
  'locks/',
11
+ 'drafts/',
12
+ 'studio-layouts/',
11
13
  'recipes/.history/',
12
14
  'tasks/current.diff',
13
15
  'tasks/*.log'
@@ -0,0 +1,113 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { NODE_ID, RECIPE_ID } = require('./recipe.js');
7
+ const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
+
9
+ const MIN_SCALE = 0.2;
10
+ const MAX_SCALE = 2.5;
11
+ const MAX_COORDINATE = 1_000_000;
12
+
13
+ function layoutError(message, code = 'INVALID_STUDIO_LAYOUT') {
14
+ const error = new Error(message);
15
+ error.code = code;
16
+ return error;
17
+ }
18
+
19
+ function finiteCoordinate(value, label) {
20
+ if (!Number.isFinite(value) || Math.abs(value) > MAX_COORDINATE) {
21
+ throw layoutError(`${label} must be a finite coordinate within ${MAX_COORDINATE}`);
22
+ }
23
+ return value;
24
+ }
25
+
26
+ function normalizeStudioLayout(recipeId, value, allowedNodeIds) {
27
+ if (!RECIPE_ID.test(String(recipeId || ''))) throw layoutError('Invalid layout recipe id');
28
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
29
+ throw layoutError('Studio layout must be an object');
30
+ }
31
+ const allowed = allowedNodeIds ? new Set(allowedNodeIds) : null;
32
+ const positions = {};
33
+ for (const [nodeId, position] of Object.entries(value.positions || {})) {
34
+ if (!NODE_ID.test(nodeId)) throw layoutError(`Invalid layout node id: ${nodeId}`);
35
+ if (allowed && !allowed.has(nodeId)) continue;
36
+ if (!position || typeof position !== 'object' || Array.isArray(position)) {
37
+ throw layoutError(`Position for ${nodeId} must be an object`);
38
+ }
39
+ positions[nodeId] = {
40
+ x: finiteCoordinate(position.x, `${nodeId}.x`),
41
+ y: finiteCoordinate(position.y, `${nodeId}.y`)
42
+ };
43
+ }
44
+ const viewport = value.viewport || { x: 0, y: 0, scale: 1 };
45
+ const scale = Number(viewport.scale);
46
+ if (!Number.isFinite(scale) || scale < MIN_SCALE || scale > MAX_SCALE) {
47
+ throw layoutError(`viewport.scale must be between ${MIN_SCALE} and ${MAX_SCALE}`);
48
+ }
49
+ return {
50
+ schemaVersion: 1,
51
+ recipeId,
52
+ positions,
53
+ viewport: {
54
+ x: finiteCoordinate(viewport.x, 'viewport.x'),
55
+ y: finiteCoordinate(viewport.y, 'viewport.y'),
56
+ scale
57
+ }
58
+ };
59
+ }
60
+
61
+ function layoutDirectory(rootDir) {
62
+ return path.join(rootDir, '.ai-engineering-loop', 'studio-layouts');
63
+ }
64
+
65
+ function layoutPath(rootDir, recipeId) {
66
+ if (!RECIPE_ID.test(String(recipeId || ''))) throw layoutError('Invalid layout recipe id');
67
+ return path.join(layoutDirectory(rootDir), `${recipeId}.json`);
68
+ }
69
+
70
+ function loadStudioLayout(rootDir, recipeId, { nodeIds } = {}) {
71
+ const filePath = layoutPath(rootDir, recipeId);
72
+ if (!fs.existsSync(filePath)) return null;
73
+ const stat = fs.lstatSync(filePath);
74
+ if (stat.isSymbolicLink() || !stat.isFile()) {
75
+ throw layoutError('Studio layout must be a regular file', 'UNSAFE_STUDIO_LAYOUT');
76
+ }
77
+ try {
78
+ return normalizeStudioLayout(recipeId, JSON.parse(fs.readFileSync(filePath, 'utf8')), nodeIds);
79
+ } catch (cause) {
80
+ if (cause.code) throw cause;
81
+ throw layoutError(`Unable to read Studio layout: ${cause.message}`);
82
+ }
83
+ }
84
+
85
+ function saveStudioLayout(rootDir, recipeId, value, { nodeIds } = {}) {
86
+ const layout = normalizeStudioLayout(recipeId, value, nodeIds);
87
+ ensurePrivateRuntimeIgnores(rootDir);
88
+ const directory = layoutDirectory(rootDir);
89
+ if (fs.existsSync(directory) && (fs.lstatSync(directory).isSymbolicLink() || !fs.lstatSync(directory).isDirectory())) {
90
+ throw layoutError('Studio layout directory must be a regular directory', 'UNSAFE_STUDIO_LAYOUT');
91
+ }
92
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
93
+ const destination = layoutPath(rootDir, recipeId);
94
+ if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
95
+ throw layoutError('Studio layout must not be a symbolic link', 'UNSAFE_STUDIO_LAYOUT');
96
+ }
97
+ const temporary = `${destination}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
98
+ try {
99
+ fs.writeFileSync(temporary, `${JSON.stringify(layout, null, 2)}\n`, { mode: 0o600 });
100
+ fs.renameSync(temporary, destination);
101
+ } finally {
102
+ try { fs.unlinkSync(temporary); } catch {}
103
+ }
104
+ return layout;
105
+ }
106
+
107
+ module.exports = {
108
+ MIN_SCALE,
109
+ MAX_SCALE,
110
+ normalizeStudioLayout,
111
+ loadStudioLayout,
112
+ saveStudioLayout
113
+ };
@@ -0,0 +1,231 @@
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
+ const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
20
+ const {
21
+ SHIPPED_TYPES,
22
+ detectAdapterHints,
23
+ writeShippedAdapter
24
+ } = require('./generate-adapter.js');
25
+
26
+ const MAX_BODY = 256 * 1024;
27
+ const ASSET_DIR = path.join(__dirname, '..', 'studio');
28
+
29
+ function json(response, status, value) {
30
+ response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
31
+ response.end(JSON.stringify(value));
32
+ }
33
+
34
+ function readBody(request) {
35
+ return new Promise((resolve, reject) => {
36
+ let text = '';
37
+ request.setEncoding('utf8');
38
+ request.on('data', (chunk) => {
39
+ text += chunk;
40
+ if (Buffer.byteLength(text) > MAX_BODY) request.destroy(new Error('Request body exceeds 256 KiB'));
41
+ });
42
+ request.on('end', () => {
43
+ try { resolve(text ? JSON.parse(text) : {}); } catch (error) { reject(error); }
44
+ });
45
+ request.on('error', reject);
46
+ });
47
+ }
48
+
49
+ function liveSnapshot(rootDir) {
50
+ const run = getCurrentRun(rootDir);
51
+ if (!run?.workflow) return null;
52
+ const workflow = workflowStatus(rootDir, { runId: run.runId });
53
+ return {
54
+ run,
55
+ plan: workflow.plan,
56
+ nodes: workflow.state.nodes,
57
+ budget: budgetStatus(rootDir, { runId: run.runId }),
58
+ events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
59
+ ...event,
60
+ changedNodes: (changes || []).map((change) => change.nodeId)
61
+ }))
62
+ };
63
+ }
64
+
65
+ function bootstrap(rootDir) {
66
+ const recipes = listRecipes(rootDir).map(({ id, source }) => ({ ...inspectRecipe(rootDir, id), source }));
67
+ const adapterHints = detectAdapterHints(rootDir);
68
+ return {
69
+ recipes,
70
+ nodeTypes: recipeCatalog(),
71
+ adapters: {
72
+ types: SHIPPED_TYPES,
73
+ current: adapterHints.existingType || null,
74
+ recommended: adapterHints.recommended,
75
+ ciProvider: adapterHints.ciProvider
76
+ },
77
+ live: liveSnapshot(rootDir)
78
+ };
79
+ }
80
+
81
+ function constantTimeEqual(left, right) {
82
+ const a = Buffer.from(String(left || ''));
83
+ const b = Buffer.from(String(right || ''));
84
+ return a.length === b.length && crypto.timingSafeEqual(a, b);
85
+ }
86
+
87
+ function localHostname(hostHeader) {
88
+ try {
89
+ return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, '');
90
+ } catch {
91
+ return '';
92
+ }
93
+ }
94
+
95
+ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('base64url') } = {}) {
96
+ const server = http.createServer(async (request, response) => {
97
+ const hostHeader = String(request.headers.host || '');
98
+ const host = localHostname(hostHeader);
99
+ if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
100
+ response.writeHead(403).end('Forbidden host');
101
+ return;
102
+ }
103
+ const url = new URL(request.url, `http://${hostHeader}`);
104
+ const cookieToken = String(request.headers.cookie || '').split(';').map((item) => item.trim())
105
+ .find((item) => item.startsWith('ael_studio='))?.slice('ael_studio='.length);
106
+ const supplied = request.headers['x-ael-studio-token'] || cookieToken;
107
+ if (url.pathname === '/' && constantTimeEqual(url.searchParams.get('token'), token)) {
108
+ response.writeHead(302, {
109
+ location: '/',
110
+ 'set-cookie': `ael_studio=${token}; HttpOnly; SameSite=Strict; Path=/`,
111
+ 'cache-control': 'no-store',
112
+ 'referrer-policy': 'no-referrer'
113
+ }).end();
114
+ return;
115
+ }
116
+ if (!constantTimeEqual(supplied, token)) {
117
+ response.writeHead(401).end('Studio session required');
118
+ return;
119
+ }
120
+ 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'");
121
+ response.setHeader('x-content-type-options', 'nosniff');
122
+ response.setHeader('referrer-policy', 'no-referrer');
123
+ try {
124
+ if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
125
+ json(response, 200, { ok: true, ...bootstrap(rootDir) });
126
+ } else if (request.method === 'GET' && url.pathname === '/api/live') {
127
+ json(response, 200, { ok: true, live: liveSnapshot(rootDir) });
128
+ } else if (request.method === 'GET' && url.pathname === '/api/recipe') {
129
+ const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
130
+ json(response, 200, { ok: true, source: loaded.source, recipe: loaded.recipe });
131
+ } else if (request.method === 'GET' && url.pathname === '/api/layout') {
132
+ const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
133
+ const nodeIds = loaded.recipe.nodes.map((node) => node.id);
134
+ json(response, 200, {
135
+ ok: true,
136
+ layout: loadStudioLayout(rootDir, loaded.recipe.id, { nodeIds })
137
+ });
138
+ } else if (request.method === 'PUT' && url.pathname === '/api/layout') {
139
+ const body = await readBody(request);
140
+ const loaded = loadRecipe(rootDir, body.recipeId);
141
+ const nodeIds = loaded.recipe.nodes.map((node) => node.id);
142
+ const layout = saveStudioLayout(rootDir, loaded.recipe.id, body.layout, { nodeIds });
143
+ json(response, 200, { ok: true, layout });
144
+ } else if (request.method === 'POST' && url.pathname === '/api/adapter/select') {
145
+ const body = await readBody(request);
146
+ if (!SHIPPED_TYPES.includes(body.type)) {
147
+ const error = new Error(`Unknown adapter type: ${body.type || '(empty)'}`);
148
+ error.code = 'UNKNOWN_ADAPTER';
149
+ throw error;
150
+ }
151
+ const hints = detectAdapterHints(rootDir);
152
+ const file = writeShippedAdapter(rootDir, { type: body.type, hints });
153
+ json(response, 200, {
154
+ ok: true,
155
+ adapter: { type: body.type, file: path.relative(rootDir, file), ciProvider: hints.ciProvider }
156
+ });
157
+ } else if (request.method === 'POST' && url.pathname === '/api/validate') {
158
+ const body = await readBody(request);
159
+ const validation = validateRecipe(body.recipe, body.mode ? { mode: body.mode } : {});
160
+ json(response, validation.valid ? 200 : 422, {
161
+ ok: validation.valid,
162
+ validation,
163
+ plans: validation.valid
164
+ ? (body.mode ? [body.mode] : body.recipe.compatibleModes).map((mode) => compileRecipe(body.recipe, { mode }))
165
+ : []
166
+ });
167
+ } else if (request.method === 'POST' && url.pathname === '/api/install') {
168
+ const body = await readBody(request);
169
+ const drafts = path.join(rootDir, '.ai-engineering-loop', 'drafts');
170
+ fs.mkdirSync(drafts, { recursive: true, mode: 0o700 });
171
+ const candidate = path.join(drafts, `${crypto.randomUUID()}.json`);
172
+ fs.writeFileSync(candidate, JSON.stringify(body.recipe), { mode: 0o600 });
173
+ try {
174
+ const result = installRecipe(rootDir, path.relative(rootDir, candidate), { replace: body.replace === true });
175
+ if (body.layout) {
176
+ saveStudioLayout(rootDir, result.recipe.id, body.layout, {
177
+ nodeIds: result.recipe.nodes.map((node) => node.id)
178
+ });
179
+ }
180
+ json(response, 200, { ok: true, id: result.recipe.id, version: result.recipe.version, sourceHash: result.sourceHash });
181
+ } finally {
182
+ try { fs.unlinkSync(candidate); } catch {}
183
+ }
184
+ } else if (request.method === 'GET' && url.pathname === '/api/handoff') {
185
+ const bundle = createHandoff(rootDir, { audience: url.searchParams.get('audience') || 'developer' });
186
+ json(response, 200, { ok: true, bundle, brief: handoffBrief(bundle) });
187
+ } else if (request.method === 'POST' && url.pathname === '/api/node/approve') {
188
+ const body = await readBody(request);
189
+ approveWorkflowNode(rootDir, body.nodeId, { runId: body.runId, approvedBy: body.approvedBy || 'human' });
190
+ json(response, 200, { ok: true });
191
+ } else if (request.method === 'POST' && url.pathname === '/api/node/retry') {
192
+ const body = await readBody(request);
193
+ retryWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
194
+ json(response, 200, { ok: true });
195
+ } else if (request.method === 'POST' && url.pathname === '/api/node/activity') {
196
+ const body = await readBody(request);
197
+ recordWorkflowActivity(rootDir, body.nodeId, {
198
+ runId: body.runId,
199
+ message: body.message
200
+ });
201
+ json(response, 200, { ok: true });
202
+ } else if (request.method === 'POST' && url.pathname === '/api/decision') {
203
+ const body = await readBody(request);
204
+ const result = recordDecision(rootDir, {
205
+ runId: body.runId,
206
+ summary: body.summary,
207
+ rationale: body.rationale,
208
+ consequences: body.consequences
209
+ });
210
+ json(response, 200, { ok: true, ...result });
211
+ } else {
212
+ const asset = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
213
+ if (!['index.html', 'app.js', 'styles.css'].includes(asset)) {
214
+ response.writeHead(404).end('Not found');
215
+ return;
216
+ }
217
+ const types = { html: 'text/html', js: 'text/javascript', css: 'text/css' };
218
+ response.writeHead(200, {
219
+ 'content-type': `${types[asset.split('.').at(-1)]}; charset=utf-8`,
220
+ 'cache-control': 'no-store'
221
+ });
222
+ response.end(fs.readFileSync(path.join(ASSET_DIR, asset)));
223
+ }
224
+ } catch (error) {
225
+ json(response, 400, { ok: false, code: error.code || 'STUDIO_ERROR', error: error.message, details: error.details || [] });
226
+ }
227
+ });
228
+ return { server, token };
229
+ }
230
+
231
+ 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.7.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,8 @@
16
16
  "adapters/",
17
17
  "recipes/",
18
18
  "schemas/",
19
+ "studio/",
20
+ "docs/images/",
19
21
  "evals/",
20
22
  ".agents/",
21
23
  ".grok/",