ai-engineering-loop 1.7.0 → 1.9.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.
@@ -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({
@@ -87,7 +88,11 @@ function refreshNodes(plan, state, run) {
87
88
  const dependencies = (node.dependsOn || []).map((id) => state.nodes[id]);
88
89
  let nextStatus = current.status;
89
90
  let reason = null;
90
- if (dependencies.some((dependency) => dependency.status === NODE_STATES.FAILED)) {
91
+ const exitGuard = (plan.loopGroups || []).find((group) => group.exitTargetId === node.id);
92
+ if (exitGuard && state.loopGroups?.[exitGuard.id]?.status !== 'EXITED') {
93
+ nextStatus = NODE_STATES.PENDING;
94
+ reason = `waiting for ${exitGuard.id} to exit`;
95
+ } else if (dependencies.some((dependency) => dependency.status === NODE_STATES.FAILED)) {
91
96
  nextStatus = NODE_STATES.BLOCKED;
92
97
  reason = 'dependency failed';
93
98
  } else if (dependencies.every((dependency) => SUCCESS_STATES.has(dependency.status))) {
@@ -127,18 +132,35 @@ function createWorkflowBundle(plan, runId, { now = new Date(), run } = {}) {
127
132
  iteration: 1,
128
133
  task: ''
129
134
  };
135
+ const loopMembership = new Map();
136
+ for (const group of plan.loopGroups || []) {
137
+ for (const nodeId of group.nodeIds) loopMembership.set(nodeId, group.id);
138
+ }
130
139
  const state = {
131
140
  schemaVersion: 1,
132
141
  runId,
133
142
  graphHash: plan.graphHash,
134
143
  sequence: 0,
135
144
  eventHash: null,
145
+ loopGroups: Object.fromEntries((plan.loopGroups || []).map((group) => [
146
+ group.id,
147
+ {
148
+ status: 'PENDING',
149
+ iteration: 1,
150
+ maxIterations: group.maxIterations,
151
+ lastOutcome: null,
152
+ updatedAt: now.toISOString()
153
+ }
154
+ ])),
136
155
  nodes: Object.fromEntries(plan.nodes.map((node) => [
137
156
  node.id,
138
157
  {
139
158
  status: NODE_STATES.PENDING,
140
159
  attempts: 0,
141
160
  reason: null,
161
+ ...(loopMembership.has(node.id)
162
+ ? { loopGroupId: loopMembership.get(node.id), loopIteration: 1 }
163
+ : {}),
142
164
  updatedAt: now.toISOString()
143
165
  }
144
166
  ]))
@@ -152,7 +174,8 @@ function createWorkflowBundle(plan, runId, { now = new Date(), run } = {}) {
152
174
  type: 'WORKFLOW_CREATED',
153
175
  runId,
154
176
  graphHash: plan.graphHash,
155
- initialNodes: state.nodes
177
+ initialNodes: state.nodes,
178
+ initialLoopGroups: state.loopGroups
156
179
  });
157
180
  state.sequence = event.sequence;
158
181
  state.eventHash = event.hash;
@@ -214,6 +237,7 @@ function verifyPlan(plan, expectedHash) {
214
237
  mode: plan.mode,
215
238
  nodes: plan.nodes
216
239
  };
240
+ if (Object.hasOwn(plan, 'loopGroups')) material.loopGroups = plan.loopGroups;
217
241
  if (plan.graphHash !== expectedHash || sha256(material) !== plan.graphHash) {
218
242
  throw runtimeError('Compiled workflow plan failed integrity validation', 'WORKFLOW_PLAN_TAMPERED');
219
243
  }
@@ -230,10 +254,12 @@ function recoverState(state, events) {
230
254
  graphHash: state.graphHash,
231
255
  sequence: created.sequence,
232
256
  eventHash: created.hash,
233
- nodes: created.initialNodes
257
+ nodes: created.initialNodes,
258
+ loopGroups: created.initialLoopGroups || {}
234
259
  };
235
260
  for (const event of events.slice(1)) {
236
261
  for (const change of event.changes || []) recovered.nodes[change.nodeId] = change.node;
262
+ for (const change of event.loopChanges || []) recovered.loopGroups[change.groupId] = change.loop;
237
263
  recovered.sequence = event.sequence;
238
264
  recovered.eventHash = event.hash;
239
265
  }
@@ -272,8 +298,17 @@ function appendEvent(filePath, event) {
272
298
  }
273
299
  }
274
300
 
275
- function commitChanges(rootDir, workflow, type, changes, metadata = {}, now = new Date()) {
276
- if (changes.length === 0) return workflow;
301
+ function commitChanges(
302
+ rootDir,
303
+ workflow,
304
+ type,
305
+ changes,
306
+ metadata = {},
307
+ now = new Date(),
308
+ allowEmpty = false,
309
+ loopChanges = []
310
+ ) {
311
+ if (changes.length === 0 && loopChanges.length === 0 && !allowEmpty) return workflow;
277
312
  const event = eventWithHash({
278
313
  schemaVersion: 1,
279
314
  sequence: workflow.state.sequence + 1,
@@ -283,6 +318,7 @@ function commitChanges(rootDir, workflow, type, changes, metadata = {}, now = ne
283
318
  runId: workflow.run.runId,
284
319
  graphHash: workflow.plan.graphHash,
285
320
  changes,
321
+ ...(loopChanges.length ? { loopChanges } : {}),
286
322
  ...metadata
287
323
  });
288
324
  const paths = workflowPaths(rootDir, workflow.run.runId);
@@ -343,6 +379,63 @@ function nodeChanges(workflow, nodeId, status, metadata = {}, now = new Date())
343
379
  return [{ nodeId, from: current.status, node: replacement }];
344
380
  }
345
381
 
382
+ function loopChange(workflow, groupId, metadata, now = new Date()) {
383
+ const current = workflow.state.loopGroups[groupId];
384
+ if (!current) throw runtimeError(`Unknown Loop Group: ${groupId}`, 'UNKNOWN_LOOP_GROUP');
385
+ const replacement = { ...current, ...metadata, updatedAt: now.toISOString() };
386
+ workflow.state.loopGroups[groupId] = replacement;
387
+ return { groupId, from: current.status, loop: replacement };
388
+ }
389
+
390
+ function loopForDecision(plan, nodeId) {
391
+ return (plan.loopGroups || []).find((group) => group.decisionNodeId === nodeId);
392
+ }
393
+
394
+ function descendantsWithinLoop(plan, group) {
395
+ const members = new Set(group.nodeIds);
396
+ const result = new Set([group.repeatTargetId]);
397
+ let changed = true;
398
+ while (changed) {
399
+ changed = false;
400
+ for (const node of plan.nodes) {
401
+ if (
402
+ members.has(node.id) &&
403
+ !result.has(node.id) &&
404
+ (node.dependsOn || []).some((dependency) => result.has(dependency))
405
+ ) {
406
+ result.add(node.id);
407
+ changed = true;
408
+ }
409
+ }
410
+ }
411
+ return result;
412
+ }
413
+
414
+ function resetLoopNodes(workflow, group, iteration, now) {
415
+ const changes = [];
416
+ for (const nodeId of descendantsWithinLoop(workflow.plan, group)) {
417
+ const current = workflow.state.nodes[nodeId];
418
+ const replacement = {
419
+ status: NODE_STATES.PENDING,
420
+ attempts: current.attempts,
421
+ reason: 'reset for next Loop iteration',
422
+ activity: null,
423
+ loopGroupId: group.id,
424
+ loopIteration: iteration,
425
+ updatedAt: now.toISOString()
426
+ };
427
+ workflow.state.nodes[nodeId] = replacement;
428
+ changes.push({ nodeId, from: current.status, node: replacement });
429
+ }
430
+ return changes;
431
+ }
432
+
433
+ function assertDecisionActor(actor) {
434
+ if (!/^[A-Za-z0-9@._-]{1,64}$/.test(String(actor || ''))) {
435
+ throw runtimeError('actor must be a short account identifier', 'INVALID_LOOP_ACTOR');
436
+ }
437
+ }
438
+
346
439
  function assertReady(workflow, nodeId) {
347
440
  const node = workflow.plan.nodes.find((candidate) => candidate.id === nodeId);
348
441
  if (!node) throw runtimeError(`Unknown workflow node: ${nodeId}`, 'UNKNOWN_WORKFLOW_NODE');
@@ -520,6 +613,9 @@ function completeWorkflowNode(rootDir, nodeId, { runId, artifact, now = new Date
520
613
  if (node.type === 'command') {
521
614
  throw runtimeError('Command nodes are disabled in the controlled runtime', 'COMMAND_EXECUTION_DISABLED');
522
615
  }
616
+ if (node.type === 'decision') {
617
+ throw runtimeError(`Node ${nodeId} requires an explicit decision outcome`, 'WRONG_NODE_EXECUTOR');
618
+ }
523
619
  if (node.type === 'approval' || LEGACY_NODE_TYPES.has(node.type)) {
524
620
  throw runtimeError(`Node ${nodeId} must use its dedicated approval or gate command`, 'WRONG_NODE_EXECUTOR');
525
621
  }
@@ -540,6 +636,219 @@ function completeWorkflowNode(rootDir, nodeId, { runId, artifact, now = new Date
540
636
  });
541
637
  }
542
638
 
639
+ function resolveWorkflowDecision(
640
+ rootDir,
641
+ nodeId,
642
+ { runId, outcome, actor = 'agent', now = new Date() } = {}
643
+ ) {
644
+ const resolved = resolveRunId(rootDir, runId);
645
+ return withWorkflowLock(rootDir, resolved, () => {
646
+ assertDecisionActor(actor);
647
+ const normalizedOutcome = String(outcome || '').trim();
648
+ if (!normalizedOutcome || normalizedOutcome.length > 80) {
649
+ throw runtimeError('A bounded decision outcome is required', 'INVALID_DECISION_OUTCOME');
650
+ }
651
+ const workflow = loadWorkflow(rootDir, resolved);
652
+ const node = assertReady(workflow, nodeId);
653
+ if (node.type !== 'decision' && node.type !== 'trigger') {
654
+ throw runtimeError(`Node ${nodeId} is not a decision node`, 'WRONG_NODE_EXECUTOR');
655
+ }
656
+ const group = loopForDecision(workflow.plan, nodeId);
657
+ if (group && ![group.repeatOutcome, group.exitOutcome].includes(normalizedOutcome)) {
658
+ throw runtimeError(
659
+ `Outcome must be ${group.repeatOutcome} or ${group.exitOutcome}`,
660
+ 'INVALID_LOOP_OUTCOME'
661
+ );
662
+ }
663
+
664
+ const currentLoop = group ? workflow.state.loopGroups[group.id] : null;
665
+ const metadata = {
666
+ nodeId,
667
+ outcome: redactSecrets(normalizedOutcome),
668
+ actor,
669
+ ...(group ? { groupId: group.id, iteration: currentLoop.iteration } : {})
670
+ };
671
+ if (!group) {
672
+ let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
673
+ attempts: workflow.state.nodes[nodeId].attempts + 1,
674
+ reason: null,
675
+ activity: null,
676
+ outcome: normalizedOutcome
677
+ }, now);
678
+ changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
679
+ return commitChanges(rootDir, workflow, 'DECISION_RESOLVED', changes, metadata, now);
680
+ }
681
+
682
+ if (normalizedOutcome === group.exitOutcome) {
683
+ let changes = nodeChanges(workflow, nodeId, NODE_STATES.PASSED, {
684
+ attempts: workflow.state.nodes[nodeId].attempts + 1,
685
+ reason: null,
686
+ activity: null,
687
+ outcome: normalizedOutcome,
688
+ loopGroupId: group.id,
689
+ loopIteration: currentLoop.iteration
690
+ }, now);
691
+ const loopChanges = [loopChange(workflow, group.id, {
692
+ status: 'EXITED',
693
+ lastOutcome: normalizedOutcome
694
+ }, now)];
695
+ changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
696
+ return commitChanges(rootDir, workflow, 'LOOP_EXITED', changes, metadata, now, false, loopChanges);
697
+ }
698
+
699
+ if (currentLoop.iteration >= currentLoop.maxIterations) {
700
+ const changes = nodeChanges(workflow, nodeId, NODE_STATES.BLOCKED, {
701
+ attempts: workflow.state.nodes[nodeId].attempts + 1,
702
+ reason: 'Loop iteration limit reached',
703
+ activity: null,
704
+ outcome: normalizedOutcome,
705
+ loopGroupId: group.id,
706
+ loopIteration: currentLoop.iteration
707
+ }, now);
708
+ const loopChanges = [loopChange(workflow, group.id, {
709
+ status: 'BLOCKED',
710
+ lastOutcome: normalizedOutcome
711
+ }, now)];
712
+ return commitChanges(
713
+ rootDir,
714
+ workflow,
715
+ 'LOOP_LIMIT_REACHED',
716
+ changes,
717
+ metadata,
718
+ now,
719
+ false,
720
+ loopChanges
721
+ );
722
+ }
723
+
724
+ const nextIteration = currentLoop.iteration + 1;
725
+ let changes = resetLoopNodes(workflow, group, nextIteration, now);
726
+ const loopChanges = [loopChange(workflow, group.id, {
727
+ status: 'RUNNING',
728
+ iteration: nextIteration,
729
+ lastOutcome: normalizedOutcome
730
+ }, now)];
731
+ changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
732
+ return commitChanges(
733
+ rootDir,
734
+ workflow,
735
+ 'LOOP_REPEATED',
736
+ changes,
737
+ { ...metadata, nextIteration },
738
+ now,
739
+ false,
740
+ loopChanges
741
+ );
742
+ });
743
+ }
744
+
745
+ function resolveLoopLimit(
746
+ rootDir,
747
+ groupId,
748
+ { runId, action, expectedIteration, actor, reason, now = new Date() } = {}
749
+ ) {
750
+ const resolved = resolveRunId(rootDir, runId);
751
+ return withWorkflowLock(rootDir, resolved, () => {
752
+ assertDecisionActor(actor);
753
+ const cleanReason = String(reason || '').trim();
754
+ if (!cleanReason || cleanReason.length > 500) {
755
+ throw runtimeError('A reason between 1 and 500 characters is required', 'INVALID_LOOP_REASON');
756
+ }
757
+ if (!['EXTRA_ITERATION', 'EXIT', 'STOP'].includes(action)) {
758
+ throw runtimeError('Loop action must be EXTRA_ITERATION, EXIT, or STOP', 'INVALID_LOOP_ACTION');
759
+ }
760
+ const workflow = loadWorkflow(rootDir, resolved);
761
+ const group = (workflow.plan.loopGroups || []).find((candidate) => candidate.id === groupId);
762
+ if (!group) throw runtimeError(`Unknown Loop Group: ${groupId}`, 'UNKNOWN_LOOP_GROUP');
763
+ const currentLoop = workflow.state.loopGroups[groupId];
764
+ if (currentLoop.status !== 'BLOCKED') {
765
+ throw runtimeError(`Loop Group ${groupId} is not blocked`, 'LOOP_NOT_BLOCKED');
766
+ }
767
+ if (currentLoop.iteration !== expectedIteration) {
768
+ throw runtimeError('Loop Group iteration changed; refresh before approving', 'STALE_LOOP_APPROVAL');
769
+ }
770
+ const metadata = {
771
+ groupId,
772
+ action,
773
+ iteration: currentLoop.iteration,
774
+ actor,
775
+ reason: redactSecrets(cleanReason)
776
+ };
777
+
778
+ if (action === 'EXTRA_ITERATION') {
779
+ const nextIteration = currentLoop.iteration + 1;
780
+ let changes = resetLoopNodes(workflow, group, nextIteration, now);
781
+ const loopChanges = [loopChange(workflow, groupId, {
782
+ status: 'RUNNING',
783
+ iteration: nextIteration
784
+ }, now)];
785
+ changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
786
+ return commitChanges(
787
+ rootDir,
788
+ workflow,
789
+ 'LOOP_LIMIT_OVERRIDE',
790
+ changes,
791
+ { ...metadata, nextIteration },
792
+ now,
793
+ false,
794
+ loopChanges
795
+ );
796
+ }
797
+
798
+ if (action === 'EXIT') {
799
+ let changes = nodeChanges(workflow, group.decisionNodeId, NODE_STATES.PASSED, {
800
+ reason: null,
801
+ activity: null,
802
+ approvedBy: actor
803
+ }, now);
804
+ const loopChanges = [loopChange(workflow, groupId, { status: 'EXITED' }, now)];
805
+ changes = changes.concat(refreshNodes(workflow.plan, workflow.state, workflow.run));
806
+ return commitChanges(
807
+ rootDir,
808
+ workflow,
809
+ 'LOOP_LIMIT_EXITED',
810
+ changes,
811
+ metadata,
812
+ now,
813
+ false,
814
+ loopChanges
815
+ );
816
+ }
817
+
818
+ const changes = [];
819
+ workflow.run = transitionRun(rootDir, resolved, RUN_STATES.CANCELLED, {
820
+ gate: 'loop-limit-stop',
821
+ reason: redactSecrets(cleanReason),
822
+ historyMetadata: {
823
+ actor,
824
+ loopGroupId: groupId,
825
+ loopIteration: currentLoop.iteration
826
+ },
827
+ now
828
+ });
829
+ for (const node of workflow.plan.nodes) {
830
+ const current = workflow.state.nodes[node.id];
831
+ if (!SUCCESS_STATES.has(current.status)) {
832
+ changes.push(...nodeChanges(workflow, node.id, NODE_STATES.BLOCKED, {
833
+ reason: 'Run stopped after Loop limit',
834
+ activity: null
835
+ }, now));
836
+ }
837
+ }
838
+ const loopChanges = [loopChange(workflow, groupId, { status: 'STOPPED' }, now)];
839
+ return commitChanges(
840
+ rootDir,
841
+ workflow,
842
+ 'LOOP_RUN_STOPPED',
843
+ changes,
844
+ metadata,
845
+ now,
846
+ false,
847
+ loopChanges
848
+ );
849
+ });
850
+ }
851
+
543
852
  function startWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
544
853
  const resolved = resolveRunId(rootDir, runId);
545
854
  return withWorkflowLock(rootDir, resolved, () => {
@@ -650,7 +959,7 @@ function descendants(plan, startId) {
650
959
  return result;
651
960
  }
652
961
 
653
- function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
962
+ function applyWorkflowGate(rootDir, gate, { runId, now = new Date(), transitionOptions = {} } = {}) {
654
963
  const resolved = resolveRunId(rootDir, runId);
655
964
  return withWorkflowLock(rootDir, resolved, () => {
656
965
  let workflow = loadWorkflow(rootDir, resolved);
@@ -658,7 +967,7 @@ function applyWorkflowGate(rootDir, gate, { runId, now = new Date() } = {}) {
658
967
  if (!node) throw runtimeError(`Workflow has no node for gate ${gate}`, 'GATE_NOT_IN_WORKFLOW');
659
968
  assertReady(workflow, node.id);
660
969
  const { applyGate } = require('./gates.js');
661
- const run = applyGate(rootDir, gate, { runId: resolved });
970
+ const run = applyGate(rootDir, gate, { runId: resolved, transitionOptions });
662
971
  workflow.run = run;
663
972
  let changes = nodeChanges(workflow, node.id, NODE_STATES.PASSED, {
664
973
  attempts: workflow.state.nodes[node.id].attempts + 1,
@@ -700,13 +1009,88 @@ function workflowStatus(rootDir, { runId } = {}) {
700
1009
  return loadWorkflow(rootDir, resolveRunId(rootDir, runId));
701
1010
  }
702
1011
 
1012
+ function unfreezeWorkflowGoal(rootDir, { runId, transitionOptions, now = new Date() } = {}) {
1013
+ const resolved = resolveRunId(rootDir, runId);
1014
+ return withWorkflowLock(rootDir, resolved, () => {
1015
+ let workflow = loadWorkflow(rootDir, resolved);
1016
+ const goalNode = workflow.plan.nodes.find((node) => node.legacyGate === 'goal');
1017
+ if (!goalNode) throw runtimeError('Workflow has no Goal Contract node', 'GATE_NOT_IN_WORKFLOW');
1018
+ const run = transitionRun(rootDir, resolved, RUN_STATES.STARTED, {
1019
+ gate: 'goal-unfreeze',
1020
+ ...transitionOptions,
1021
+ now
1022
+ });
1023
+ workflow.run = run;
1024
+ const changes = workflow.plan.nodes.map((node) => {
1025
+ const current = workflow.state.nodes[node.id];
1026
+ const replacement = {
1027
+ status: node.id === goalNode.id ? NODE_STATES.READY : NODE_STATES.PENDING,
1028
+ attempts: current.attempts,
1029
+ reason: node.id === goalNode.id ? null : 'Goal version changed',
1030
+ activity: null,
1031
+ updatedAt: now.toISOString()
1032
+ };
1033
+ workflow.state.nodes[node.id] = replacement;
1034
+ return { nodeId: node.id, from: current.status, node: replacement };
1035
+ });
1036
+ workflow = commitChanges(rootDir, workflow, 'GOAL_UNFROZEN', changes, {
1037
+ actor: transitionOptions.historyMetadata.actor,
1038
+ reason: transitionOptions.reason,
1039
+ goalVersion: transitionOptions.historyMetadata.goalVersion,
1040
+ nextGoalVersion: transitionOptions.historyMetadata.nextGoalVersion
1041
+ }, now);
1042
+ return { run, workflow };
1043
+ });
1044
+ }
1045
+
1046
+ function startWorkflowExecution(rootDir, { runId, now = new Date() } = {}) {
1047
+ const resolved = resolveRunId(rootDir, runId);
1048
+ return withWorkflowLock(rootDir, resolved, () => {
1049
+ const workflow = loadWorkflow(rootDir, resolved);
1050
+ if (workflow.run.state !== RUN_STATES.GOAL_FROZEN || workflow.run.goal?.frozen !== true) {
1051
+ throw runtimeError('Execution requires a deliberately frozen Goal', 'GOAL_NOT_FROZEN');
1052
+ }
1053
+ if (workflow.run.mode === 'REPORT_ONLY') {
1054
+ throw runtimeError('REPORT_ONLY runs cannot execute a workflow', 'UNSUPPORTED_EXECUTION_MODE');
1055
+ }
1056
+ const roots = workflow.plan.nodes.filter((node) => (node.dependsOn || []).length === 0);
1057
+ if (roots.length !== 1 || !['goal-contract', 'trigger'].includes(roots[0].type)) {
1058
+ throw runtimeError(
1059
+ `Execution requires exactly one permitted trigger/root; found ${roots.length}`,
1060
+ 'AMBIGUOUS_WORKFLOW_TRIGGER'
1061
+ );
1062
+ }
1063
+ const latestStart = workflow.events.findLastIndex((event) => event.type === 'WORKFLOW_EXECUTION_STARTED');
1064
+ const latestUnfreeze = workflow.events.findLastIndex((event) => event.type === 'GOAL_UNFROZEN');
1065
+ if (latestStart > latestUnfreeze) {
1066
+ throw runtimeError('Workflow execution is already active for this run', 'WORKFLOW_ALREADY_EXECUTING');
1067
+ }
1068
+ const { assertModeAllowed } = require('./runtime-policy.js');
1069
+ const { assertBudgetAvailable } = require('./budget.js');
1070
+ assertModeAllowed(rootDir, workflow.run.mode);
1071
+ const budget = assertBudgetAvailable(rootDir, { runId: resolved, now });
1072
+ return {
1073
+ workflow: commitChanges(rootDir, workflow, 'WORKFLOW_EXECUTION_STARTED', [], {
1074
+ triggerNodeId: roots[0].id,
1075
+ dispatch: 'LOCAL_RUNTIME_ONLY',
1076
+ externalDispatch: false
1077
+ }, now, true),
1078
+ budget
1079
+ };
1080
+ });
1081
+ }
1082
+
703
1083
  module.exports = {
704
1084
  NODE_STATES,
705
1085
  createWorkflowBundle,
706
1086
  loadWorkflow,
707
1087
  workflowStatus,
1088
+ unfreezeWorkflowGoal,
1089
+ startWorkflowExecution,
708
1090
  startWorkflowNode,
709
1091
  completeWorkflowNode,
1092
+ resolveWorkflowDecision,
1093
+ resolveLoopLimit,
710
1094
  failWorkflowNode,
711
1095
  retryWorkflowNode,
712
1096
  recordWorkflowActivity,
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.9.0",
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"
@@ -13,6 +13,11 @@
13
13
  },
14
14
  "mode": { "enum": ["REPORT_ONLY", "ASSISTED", "UNATTENDED"] },
15
15
  "nodes": { "type": "array", "minItems": 1, "maxItems": 64 },
16
+ "loopGroups": {
17
+ "type": "array",
18
+ "maxItems": 16,
19
+ "items": { "$ref": "./loop-group.schema.json" }
20
+ },
16
21
  "graphHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
17
22
  },
18
23
  "additionalProperties": true
@@ -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
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/loop-group.schema.json",
4
+ "title": "AI Engineering Loop Loop Group",
5
+ "type": "object",
6
+ "required": [
7
+ "id",
8
+ "displayName",
9
+ "nodeIds",
10
+ "entryNodeId",
11
+ "decisionNodeId",
12
+ "repeatTargetId",
13
+ "exitTargetId",
14
+ "maxIterations",
15
+ "repeatOutcome",
16
+ "exitOutcome",
17
+ "repeatLabel",
18
+ "exitLabel"
19
+ ],
20
+ "properties": {
21
+ "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
22
+ "displayName": { "type": "string", "minLength": 1, "maxLength": 80 },
23
+ "nodeIds": {
24
+ "type": "array",
25
+ "minItems": 2,
26
+ "maxItems": 64,
27
+ "uniqueItems": true,
28
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
29
+ },
30
+ "entryNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
31
+ "decisionNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
32
+ "repeatTargetId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
33
+ "exitTargetId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
34
+ "maxIterations": { "type": "integer", "minimum": 1, "maximum": 100 },
35
+ "repeatOutcome": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$" },
36
+ "exitOutcome": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$" },
37
+ "repeatLabel": { "type": "string", "minLength": 1, "maxLength": 40 },
38
+ "exitLabel": { "type": "string", "minLength": 1, "maxLength": 40 }
39
+ },
40
+ "additionalProperties": false
41
+ }
@@ -6,12 +6,14 @@
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",
12
13
  "agent",
13
14
  "command",
14
15
  "condition",
16
+ "decision",
15
17
  "approval",
16
18
  "artifact-check",
17
19
  "maker",
@@ -27,7 +29,79 @@
27
29
  "uniqueItems": true,
28
30
  "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
29
31
  },
30
- "when": { "type": "object" }
32
+ "when": { "type": "object" },
33
+ "prompt": { "type": "string", "minLength": 1, "maxLength": 20000 },
34
+ "capabilityRefs": {
35
+ "type": "array",
36
+ "uniqueItems": true,
37
+ "items": {
38
+ "enum": [
39
+ "repository-read",
40
+ "repository-write",
41
+ "artifact-read",
42
+ "artifact-write",
43
+ "mcp-invoke",
44
+ "network-declared"
45
+ ]
46
+ }
47
+ },
48
+ "mcpRefs": {
49
+ "type": "array",
50
+ "uniqueItems": true,
51
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
52
+ },
53
+ "inputArtifacts": {
54
+ "type": "array",
55
+ "uniqueItems": true,
56
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" }
57
+ },
58
+ "outputArtifacts": {
59
+ "type": "array",
60
+ "minItems": 1,
61
+ "items": {
62
+ "type": "object",
63
+ "required": ["artifact", "schema"],
64
+ "properties": {
65
+ "artifact": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
66
+ "schema": { "type": "string", "minLength": 1 }
67
+ },
68
+ "additionalProperties": false
69
+ }
70
+ },
71
+ "tokenLimit": { "type": "integer", "minimum": 1, "maximum": 1000000 },
72
+ "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 1800000 },
73
+ "retry": {
74
+ "type": "object",
75
+ "required": ["maxAttempts", "backoffMs"],
76
+ "properties": {
77
+ "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 },
78
+ "backoffMs": { "type": "integer", "minimum": 0, "maximum": 300000 }
79
+ },
80
+ "additionalProperties": false
81
+ }
31
82
  },
83
+ "allOf": [
84
+ {
85
+ "if": {
86
+ "properties": {
87
+ "type": { "const": "agent" },
88
+ "prompt": { "type": "string" }
89
+ },
90
+ "required": ["type", "prompt"]
91
+ },
92
+ "then": {
93
+ "required": [
94
+ "displayName",
95
+ "capabilityRefs",
96
+ "mcpRefs",
97
+ "inputArtifacts",
98
+ "outputArtifacts",
99
+ "tokenLimit",
100
+ "timeoutMs",
101
+ "retry"
102
+ ]
103
+ }
104
+ }
105
+ ],
32
106
  "additionalProperties": true
33
107
  }