ai-engineering-loop 1.7.0 → 1.8.1

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.
@@ -6,15 +6,27 @@ const http = require('http');
6
6
  const path = require('path');
7
7
  const { URL } = require('url');
8
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');
9
+ const {
10
+ applyRecipeImport,
11
+ inspectRecipe,
12
+ installRecipe,
13
+ planRecipeImport,
14
+ recipeCatalog
15
+ } = require('./recipe-builder.js');
16
+ const { getCurrentRun, updateRunDisplayName } = require('./run-state.js');
11
17
  const { budgetStatus } = require('./budget.js');
12
18
  const {
13
19
  workflowStatus,
14
20
  approveWorkflowNode,
21
+ completeWorkflowNode,
22
+ failWorkflowNode,
15
23
  retryWorkflowNode,
24
+ startWorkflowNode,
16
25
  recordWorkflowActivity
17
26
  } = require('./workflow-runtime.js');
27
+ const { listRunHistory, runHistoryDetail, inspectRunArtifact } = require('./run-history.js');
28
+ const { saveGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
29
+ const { createStudioRun, executeStudioRun } = require('./studio-runtime.js');
18
30
  const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
19
31
  const { loadStudioLayout, saveStudioLayout } = require('./studio-layout.js');
20
32
  const {
@@ -121,10 +133,138 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
121
133
  response.setHeader('x-content-type-options', 'nosniff');
122
134
  response.setHeader('referrer-policy', 'no-referrer');
123
135
  try {
136
+ const scopedRun = url.pathname.match(/^\/api\/runs\/([^/]+)$/);
137
+ const scopedArtifact = url.pathname.match(/^\/api\/runs\/([^/]+)\/artifacts$/);
138
+ const scopedExecute = url.pathname.match(/^\/api\/runs\/([^/]+)\/execute$/);
139
+ const scopedGoal = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal$/);
140
+ const scopedGoalFreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/freeze$/);
141
+ const scopedGoalUnfreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/unfreeze$/);
124
142
  if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
125
143
  json(response, 200, { ok: true, ...bootstrap(rootDir) });
126
144
  } else if (request.method === 'GET' && url.pathname === '/api/live') {
127
145
  json(response, 200, { ok: true, live: liveSnapshot(rootDir) });
146
+ } else if (request.method === 'GET' && url.pathname === '/api/runs') {
147
+ json(response, 200, {
148
+ ok: true,
149
+ ...listRunHistory(rootDir, {
150
+ query: url.searchParams.get('q') || '',
151
+ status: url.searchParams.get('status') || undefined,
152
+ mode: url.searchParams.get('mode') || undefined,
153
+ from: url.searchParams.get('from') || undefined,
154
+ to: url.searchParams.get('to') || undefined
155
+ })
156
+ });
157
+ } else if (request.method === 'GET' && scopedRun) {
158
+ json(response, 200, {
159
+ ok: true,
160
+ run: runHistoryDetail(rootDir, decodeURIComponent(scopedRun[1]))
161
+ });
162
+ } else if (request.method === 'GET' && scopedArtifact) {
163
+ json(response, 200, {
164
+ ok: true,
165
+ artifact: inspectRunArtifact(
166
+ rootDir,
167
+ decodeURIComponent(scopedArtifact[1]),
168
+ url.searchParams.get('path')
169
+ )
170
+ });
171
+ } else if (request.method === 'POST' && scopedExecute) {
172
+ const result = executeStudioRun(rootDir, decodeURIComponent(scopedExecute[1]));
173
+ json(response, 200, {
174
+ ok: true,
175
+ runId: result.workflow.run.runId,
176
+ execution: {
177
+ dispatch: 'LOCAL_RUNTIME_ONLY',
178
+ externalDispatch: false,
179
+ triggerNodeId: result.workflow.events.at(-1).triggerNodeId
180
+ },
181
+ nodes: result.workflow.state.nodes,
182
+ budget: result.budget
183
+ });
184
+ } else if (request.method === 'PUT' && scopedGoal) {
185
+ const body = await readBody(request);
186
+ const goal = saveGoalDraft(rootDir, decodeURIComponent(scopedGoal[1]), body.goal);
187
+ json(response, 200, { ok: true, goal, frozen: false });
188
+ } else if (request.method === 'POST' && scopedGoalFreeze) {
189
+ const body = await readBody(request);
190
+ const run = freezeGoal(rootDir, decodeURIComponent(scopedGoalFreeze[1]), { actor: body.actor });
191
+ json(response, 200, { ok: true, run });
192
+ } else if (request.method === 'POST' && scopedGoalUnfreeze) {
193
+ const body = await readBody(request);
194
+ const run = unfreezeGoal(rootDir, decodeURIComponent(scopedGoalUnfreeze[1]), {
195
+ actor: body.actor,
196
+ reason: body.reason
197
+ });
198
+ json(response, 200, { ok: true, run });
199
+ } else if (request.method === 'GET' && url.pathname === '/api/run') {
200
+ json(response, 200, { ok: true, run: runHistoryDetail(rootDir, url.searchParams.get('runId')) });
201
+ } else if (request.method === 'GET' && url.pathname === '/api/run/artifact') {
202
+ json(response, 200, {
203
+ ok: true,
204
+ artifact: inspectRunArtifact(
205
+ rootDir,
206
+ url.searchParams.get('runId'),
207
+ url.searchParams.get('path')
208
+ )
209
+ });
210
+ } else if (request.method === 'POST' && ['/api/runs', '/api/run/create'].includes(url.pathname)) {
211
+ const body = await readBody(request);
212
+ const run = createStudioRun(rootDir, body);
213
+ json(response, 201, { ok: true, run });
214
+ } else if (request.method === 'PATCH' && url.pathname === '/api/run/name') {
215
+ const body = await readBody(request);
216
+ const run = updateRunDisplayName(rootDir, body.runId, body.displayName, {
217
+ actor: body.actor || 'human'
218
+ });
219
+ json(response, 200, { ok: true, run });
220
+ } else if (request.method === 'PUT' && ['/api/goal', '/api/goal/save'].includes(url.pathname)) {
221
+ const body = await readBody(request);
222
+ const goal = saveGoalDraft(rootDir, body.runId, body.goal);
223
+ json(response, 200, { ok: true, goal, frozen: false });
224
+ } else if (request.method === 'POST' && url.pathname === '/api/goal/freeze') {
225
+ const body = await readBody(request);
226
+ const run = freezeGoal(rootDir, body.runId, { actor: body.actor });
227
+ json(response, 200, { ok: true, run });
228
+ } else if (request.method === 'POST' && url.pathname === '/api/goal/unfreeze') {
229
+ const body = await readBody(request);
230
+ const run = unfreezeGoal(rootDir, body.runId, {
231
+ actor: body.actor,
232
+ reason: body.reason
233
+ });
234
+ json(response, 200, { ok: true, run });
235
+ } else if (request.method === 'POST' && ['/api/run/execute', '/api/execute'].includes(url.pathname)) {
236
+ const body = await readBody(request);
237
+ const result = executeStudioRun(rootDir, body.runId);
238
+ json(response, 200, {
239
+ ok: true,
240
+ runId: result.workflow.run.runId,
241
+ execution: {
242
+ dispatch: 'LOCAL_RUNTIME_ONLY',
243
+ externalDispatch: false,
244
+ triggerNodeId: result.workflow.events.at(-1).triggerNodeId
245
+ },
246
+ nodes: result.workflow.state.nodes,
247
+ budget: result.budget
248
+ });
249
+ } else if (request.method === 'POST' && url.pathname === '/api/import/preview') {
250
+ const body = await readBody(request);
251
+ const plan = planRecipeImport(
252
+ body.existingRecipe,
253
+ body.importedRecipe,
254
+ body.operation || 'merge'
255
+ );
256
+ json(response, 200, { ok: true, plan });
257
+ } else if (request.method === 'POST' && url.pathname === '/api/import/apply') {
258
+ const body = await readBody(request);
259
+ const recipe = applyRecipeImport(body.existingRecipe, body.importedRecipe, body.plan);
260
+ const validation = validateRecipe(recipe);
261
+ if (!validation.valid) {
262
+ const error = new Error('Imported workflow is invalid after applying the preview');
263
+ error.code = 'INVALID_RECIPE';
264
+ error.details = validation.errors;
265
+ throw error;
266
+ }
267
+ json(response, 200, { ok: true, recipe, validation });
128
268
  } else if (request.method === 'GET' && url.pathname === '/api/recipe') {
129
269
  const loaded = loadRecipe(rootDir, url.searchParams.get('id'));
130
270
  json(response, 200, { ok: true, source: loaded.source, recipe: loaded.recipe });
@@ -188,6 +328,18 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
188
328
  const body = await readBody(request);
189
329
  approveWorkflowNode(rootDir, body.nodeId, { runId: body.runId, approvedBy: body.approvedBy || 'human' });
190
330
  json(response, 200, { ok: true });
331
+ } else if (request.method === 'POST' && url.pathname === '/api/node/start') {
332
+ const body = await readBody(request);
333
+ startWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
334
+ json(response, 200, { ok: true });
335
+ } else if (request.method === 'POST' && url.pathname === '/api/node/complete') {
336
+ const body = await readBody(request);
337
+ completeWorkflowNode(rootDir, body.nodeId, { runId: body.runId, artifact: body.artifact });
338
+ json(response, 200, { ok: true });
339
+ } else if (request.method === 'POST' && url.pathname === '/api/node/fail') {
340
+ const body = await readBody(request);
341
+ failWorkflowNode(rootDir, body.nodeId, { runId: body.runId, reason: body.reason });
342
+ json(response, 200, { ok: true });
191
343
  } else if (request.method === 'POST' && url.pathname === '/api/node/retry') {
192
344
  const body = await readBody(request);
193
345
  retryWorkflowNode(rootDir, body.nodeId, { runId: body.runId });
@@ -9,7 +9,8 @@ const {
9
9
  atomicWriteJson,
10
10
  getCurrentRun,
11
11
  loadRun,
12
- runsDir
12
+ runsDir,
13
+ transitionRun
13
14
  } = require('./run-state.js');
14
15
 
15
16
  const NODE_STATES = Object.freeze({
@@ -272,8 +273,8 @@ function appendEvent(filePath, event) {
272
273
  }
273
274
  }
274
275
 
275
- function commitChanges(rootDir, workflow, type, changes, metadata = {}, now = new Date()) {
276
- if (changes.length === 0) return workflow;
276
+ function commitChanges(rootDir, workflow, type, changes, metadata = {}, now = new Date(), allowEmpty = false) {
277
+ if (changes.length === 0 && !allowEmpty) return workflow;
277
278
  const event = eventWithHash({
278
279
  schemaVersion: 1,
279
280
  sequence: workflow.state.sequence + 1,
@@ -650,7 +651,7 @@ function descendants(plan, startId) {
650
651
  return result;
651
652
  }
652
653
 
653
- function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
654
+ function applyWorkflowGate(rootDir, gate, { runId, now = new Date(), transitionOptions = {} } = {}) {
654
655
  const resolved = resolveRunId(rootDir, runId);
655
656
  return withWorkflowLock(rootDir, resolved, () => {
656
657
  let workflow = loadWorkflow(rootDir, resolved);
@@ -658,7 +659,7 @@ function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
658
659
  if (!node) throw runtimeError(`Workflow has no node for gate ${gate}`, 'GATE_NOT_IN_WORKFLOW');
659
660
  assertReady(workflow, node.id);
660
661
  const { applyGate } = require('./gates.js');
661
- const run = applyGate(rootDir, gate, { runId: resolved });
662
+ const run = applyGate(rootDir, gate, { runId: resolved, transitionOptions });
662
663
  workflow.run = run;
663
664
  let changes = nodeChanges(workflow, node.id, NODE_STATES.PASSED, {
664
665
  attempts: workflow.state.nodes[node.id].attempts + 1,
@@ -700,11 +701,84 @@ function workflowStatus(rootDir, { runId } = {}) {
700
701
  return loadWorkflow(rootDir, resolveRunId(rootDir, runId));
701
702
  }
702
703
 
704
+ function unfreezeWorkflowGoal(rootDir, { runId, transitionOptions, now = new Date() } = {}) {
705
+ const resolved = resolveRunId(rootDir, runId);
706
+ return withWorkflowLock(rootDir, resolved, () => {
707
+ let workflow = loadWorkflow(rootDir, resolved);
708
+ const goalNode = workflow.plan.nodes.find((node) => node.legacyGate === 'goal');
709
+ if (!goalNode) throw runtimeError('Workflow has no Goal Contract node', 'GATE_NOT_IN_WORKFLOW');
710
+ const run = transitionRun(rootDir, resolved, RUN_STATES.STARTED, {
711
+ gate: 'goal-unfreeze',
712
+ ...transitionOptions,
713
+ now
714
+ });
715
+ workflow.run = run;
716
+ const changes = workflow.plan.nodes.map((node) => {
717
+ const current = workflow.state.nodes[node.id];
718
+ const replacement = {
719
+ status: node.id === goalNode.id ? NODE_STATES.READY : NODE_STATES.PENDING,
720
+ attempts: current.attempts,
721
+ reason: node.id === goalNode.id ? null : 'Goal version changed',
722
+ activity: null,
723
+ updatedAt: now.toISOString()
724
+ };
725
+ workflow.state.nodes[node.id] = replacement;
726
+ return { nodeId: node.id, from: current.status, node: replacement };
727
+ });
728
+ workflow = commitChanges(rootDir, workflow, 'GOAL_UNFROZEN', changes, {
729
+ actor: transitionOptions.historyMetadata.actor,
730
+ reason: transitionOptions.reason,
731
+ goalVersion: transitionOptions.historyMetadata.goalVersion,
732
+ nextGoalVersion: transitionOptions.historyMetadata.nextGoalVersion
733
+ }, now);
734
+ return { run, workflow };
735
+ });
736
+ }
737
+
738
+ function startWorkflowExecution(rootDir, { runId, now = new Date() } = {}) {
739
+ const resolved = resolveRunId(rootDir, runId);
740
+ return withWorkflowLock(rootDir, resolved, () => {
741
+ const workflow = loadWorkflow(rootDir, resolved);
742
+ if (workflow.run.state !== RUN_STATES.GOAL_FROZEN || workflow.run.goal?.frozen !== true) {
743
+ throw runtimeError('Execution requires a deliberately frozen Goal', 'GOAL_NOT_FROZEN');
744
+ }
745
+ if (workflow.run.mode === 'REPORT_ONLY') {
746
+ throw runtimeError('REPORT_ONLY runs cannot execute a workflow', 'UNSUPPORTED_EXECUTION_MODE');
747
+ }
748
+ const roots = workflow.plan.nodes.filter((node) => (node.dependsOn || []).length === 0);
749
+ if (roots.length !== 1 || !['goal-contract', 'trigger'].includes(roots[0].type)) {
750
+ throw runtimeError(
751
+ `Execution requires exactly one permitted trigger/root; found ${roots.length}`,
752
+ 'AMBIGUOUS_WORKFLOW_TRIGGER'
753
+ );
754
+ }
755
+ const latestStart = workflow.events.findLastIndex((event) => event.type === 'WORKFLOW_EXECUTION_STARTED');
756
+ const latestUnfreeze = workflow.events.findLastIndex((event) => event.type === 'GOAL_UNFROZEN');
757
+ if (latestStart > latestUnfreeze) {
758
+ throw runtimeError('Workflow execution is already active for this run', 'WORKFLOW_ALREADY_EXECUTING');
759
+ }
760
+ const { assertModeAllowed } = require('./runtime-policy.js');
761
+ const { assertBudgetAvailable } = require('./budget.js');
762
+ assertModeAllowed(rootDir, workflow.run.mode);
763
+ const budget = assertBudgetAvailable(rootDir, { runId: resolved, now });
764
+ return {
765
+ workflow: commitChanges(rootDir, workflow, 'WORKFLOW_EXECUTION_STARTED', [], {
766
+ triggerNodeId: roots[0].id,
767
+ dispatch: 'LOCAL_RUNTIME_ONLY',
768
+ externalDispatch: false
769
+ }, now, true),
770
+ budget
771
+ };
772
+ });
773
+ }
774
+
703
775
  module.exports = {
704
776
  NODE_STATES,
705
777
  createWorkflowBundle,
706
778
  loadWorkflow,
707
779
  workflowStatus,
780
+ unfreezeWorkflowGoal,
781
+ startWorkflowExecution,
708
782
  startWorkflowNode,
709
783
  completeWorkflowNode,
710
784
  failWorkflowNode,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.7.0",
4
- "description": "A reusable, framework-agnostic AI Engineering Operating System for safe coding agents.",
3
+ "version": "1.8.1",
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": {
7
7
  "ai-engineering-loop": "bin/ai-engineering-loop.js"
@@ -0,0 +1,13 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/edge-definition.schema.json",
4
+ "title": "AI Engineering Loop Edge Definition",
5
+ "type": "object",
6
+ "required": ["id", "from", "to"],
7
+ "properties": {
8
+ "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
9
+ "from": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
10
+ "to": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
11
+ },
12
+ "additionalProperties": false
13
+ }
@@ -6,6 +6,7 @@
6
6
  "required": ["id", "type"],
7
7
  "properties": {
8
8
  "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
9
+ "displayName": { "type": "string", "minLength": 1, "maxLength": 120 },
9
10
  "type": {
10
11
  "enum": [
11
12
  "goal-contract",
@@ -27,7 +28,79 @@
27
28
  "uniqueItems": true,
28
29
  "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
29
30
  },
30
- "when": { "type": "object" }
31
+ "when": { "type": "object" },
32
+ "prompt": { "type": "string", "minLength": 1, "maxLength": 20000 },
33
+ "capabilityRefs": {
34
+ "type": "array",
35
+ "uniqueItems": true,
36
+ "items": {
37
+ "enum": [
38
+ "repository-read",
39
+ "repository-write",
40
+ "artifact-read",
41
+ "artifact-write",
42
+ "mcp-invoke",
43
+ "network-declared"
44
+ ]
45
+ }
46
+ },
47
+ "mcpRefs": {
48
+ "type": "array",
49
+ "uniqueItems": true,
50
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
51
+ },
52
+ "inputArtifacts": {
53
+ "type": "array",
54
+ "uniqueItems": true,
55
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
56
+ },
57
+ "outputArtifacts": {
58
+ "type": "array",
59
+ "minItems": 1,
60
+ "items": {
61
+ "type": "object",
62
+ "required": ["artifact", "schema"],
63
+ "properties": {
64
+ "artifact": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
65
+ "schema": { "type": "string", "minLength": 1 }
66
+ },
67
+ "additionalProperties": false
68
+ }
69
+ },
70
+ "tokenLimit": { "type": "integer", "minimum": 1, "maximum": 1000000 },
71
+ "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 1800000 },
72
+ "retry": {
73
+ "type": "object",
74
+ "required": ["maxAttempts", "backoffMs"],
75
+ "properties": {
76
+ "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
77
+ "backoffMs": { "type": "integer", "minimum": 0, "maximum": 300000 }
78
+ },
79
+ "additionalProperties": false
80
+ }
31
81
  },
82
+ "allOf": [
83
+ {
84
+ "if": {
85
+ "properties": {
86
+ "type": { "const": "agent" },
87
+ "prompt": { "type": "string" }
88
+ },
89
+ "required": ["type", "prompt"]
90
+ },
91
+ "then": {
92
+ "required": [
93
+ "displayName",
94
+ "capabilityRefs",
95
+ "mcpRefs",
96
+ "inputArtifacts",
97
+ "outputArtifacts",
98
+ "tokenLimit",
99
+ "timeoutMs",
100
+ "retry"
101
+ ]
102
+ }
103
+ }
104
+ ],
32
105
  "additionalProperties": true
33
106
  }
@@ -20,6 +20,11 @@
20
20
  "minItems": 1,
21
21
  "maxItems": 64,
22
22
  "items": { "$ref": "node-definition.schema.json" }
23
+ },
24
+ "edges": {
25
+ "type": "array",
26
+ "maxItems": 256,
27
+ "items": { "$ref": "edge-definition.schema.json" }
23
28
  }
24
29
  },
25
30
  "additionalProperties": false