ai-engineering-loop 1.8.1 → 1.9.2

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,184 @@
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_INTERACTIONS = 500;
10
+ const MAX_MESSAGE_LENGTH = 8000;
11
+ const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
12
+ const QUESTION_ID = /^q-[a-f0-9]{12}$/;
13
+ const LOCK_STALE_MS = 60_000;
14
+
15
+ function interactionError(message, code = 'RUN_INTERACTION_ERROR') {
16
+ const error = new Error(message);
17
+ error.code = code;
18
+ return error;
19
+ }
20
+
21
+ function ledgerPath(rootDir, runId) {
22
+ assertRunId(runId);
23
+ loadRun(rootDir, runId);
24
+ return path.join(runsDir(rootDir), runId, 'interactions.jsonl');
25
+ }
26
+
27
+ function withInteractionLock(rootDir, runId, operation) {
28
+ const lock = `${ledgerPath(rootDir, runId)}.lock`;
29
+ let descriptor;
30
+ try {
31
+ try {
32
+ descriptor = fs.openSync(lock, 'wx', 0o600);
33
+ } catch (error) {
34
+ if (error.code !== 'EEXIST') throw error;
35
+ const stat = fs.lstatSync(lock);
36
+ if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
37
+ throw interactionError('Another interaction update is in progress', 'RUN_INTERACTION_BUSY');
38
+ }
39
+ fs.unlinkSync(lock);
40
+ descriptor = fs.openSync(lock, 'wx', 0o600);
41
+ }
42
+ return operation();
43
+ } finally {
44
+ if (descriptor != null) {
45
+ fs.closeSync(descriptor);
46
+ try { fs.unlinkSync(lock); } catch {}
47
+ }
48
+ }
49
+ }
50
+
51
+ function materialHash(event) {
52
+ const { hash, ...material } = event;
53
+ return sha256(material);
54
+ }
55
+
56
+ function readLedger(rootDir, runId) {
57
+ const file = ledgerPath(rootDir, runId);
58
+ if (!fs.existsSync(file)) return [];
59
+ const stat = fs.lstatSync(file);
60
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > 2 * 1024 * 1024) {
61
+ throw interactionError('Run interactions must be a bounded regular file', 'INVALID_RUN_INTERACTIONS');
62
+ }
63
+ const events = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
64
+ try { return JSON.parse(line); } catch { return null; }
65
+ });
66
+ let previousHash = null;
67
+ for (const [index, event] of events.entries()) {
68
+ if (!event || event.runId !== runId || event.sequence !== index + 1 ||
69
+ event.previousHash !== previousHash || event.hash !== materialHash(event) ||
70
+ !['QUESTION', 'ANSWER'].includes(event.type)) {
71
+ throw interactionError(`Run interaction ${index + 1} failed integrity validation`, 'INVALID_RUN_INTERACTIONS');
72
+ }
73
+ previousHash = event.hash;
74
+ }
75
+ return events;
76
+ }
77
+
78
+ function normalizedMessage(value) {
79
+ const message = redactSecrets(String(value || '').trim()).text;
80
+ if (!message || message.length > MAX_MESSAGE_LENGTH) {
81
+ throw interactionError(`Message must be 1-${MAX_MESSAGE_LENGTH} characters`, 'INVALID_INTERACTION_MESSAGE');
82
+ }
83
+ return message;
84
+ }
85
+
86
+ function normalizedActor(value) {
87
+ const actor = String(value || '').trim();
88
+ if (!ACTOR_ID.test(actor)) {
89
+ throw interactionError('Actor must be a short account identifier', 'INVALID_INTERACTION_ACTOR');
90
+ }
91
+ return actor;
92
+ }
93
+
94
+ function append(rootDir, runId, partial, now) {
95
+ const file = ledgerPath(rootDir, runId);
96
+ const events = readLedger(rootDir, runId);
97
+ if (events.length >= MAX_INTERACTIONS) {
98
+ throw interactionError('Run interaction limit reached', 'RUN_INTERACTION_LIMIT');
99
+ }
100
+ const material = {
101
+ schemaVersion: 1,
102
+ runId,
103
+ sequence: events.length + 1,
104
+ previousHash: events.at(-1)?.hash || null,
105
+ at: now.toISOString(),
106
+ ...partial
107
+ };
108
+ const event = { ...material, hash: sha256(material) };
109
+ fs.appendFileSync(file, `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'a' });
110
+ return event;
111
+ }
112
+
113
+ function appendRunQuestion(rootDir, runId, { message, actor = 'agent' } = {}, { now = new Date() } = {}) {
114
+ return withInteractionLock(rootDir, runId, () => {
115
+ const events = readLedger(rootDir, runId);
116
+ const number = events.filter((event) => event.type === 'QUESTION').length + 1;
117
+ const cleanMessage = normalizedMessage(message);
118
+ const cleanActor = normalizedActor(actor);
119
+ if (events.some((event) =>
120
+ event.type === 'QUESTION' && event.message === cleanMessage && event.actor === cleanActor &&
121
+ !events.some((answer) => answer.type === 'ANSWER' && answer.questionId === event.questionId)
122
+ )) {
123
+ throw interactionError('An identical question is already waiting for an answer', 'DUPLICATE_QUESTION');
124
+ }
125
+ const questionId = `q-${sha256({ runId, number, message: cleanMessage, at: now.toISOString() }).slice(0, 12)}`;
126
+ return append(rootDir, runId, {
127
+ type: 'QUESTION',
128
+ questionId,
129
+ number,
130
+ message: cleanMessage,
131
+ actor: cleanActor
132
+ }, now);
133
+ });
134
+ }
135
+
136
+ function appendRunAnswer(
137
+ rootDir,
138
+ runId,
139
+ questionId,
140
+ { message, actor = 'human' } = {},
141
+ { now = new Date() } = {}
142
+ ) {
143
+ return withInteractionLock(rootDir, runId, () => {
144
+ if (!QUESTION_ID.test(String(questionId))) {
145
+ throw interactionError('Question ID is invalid', 'INVALID_QUESTION_ID');
146
+ }
147
+ const events = readLedger(rootDir, runId);
148
+ if (!events.some((event) => event.type === 'QUESTION' && event.questionId === questionId)) {
149
+ throw interactionError(`Question ${questionId} does not exist`, 'QUESTION_NOT_FOUND');
150
+ }
151
+ if (events.some((event) => event.type === 'ANSWER' && event.questionId === questionId)) {
152
+ throw interactionError(`Question ${questionId} is already answered`, 'QUESTION_ALREADY_ANSWERED');
153
+ }
154
+ return append(rootDir, runId, {
155
+ type: 'ANSWER',
156
+ questionId,
157
+ message: normalizedMessage(message),
158
+ actor: normalizedActor(actor)
159
+ }, now);
160
+ });
161
+ }
162
+
163
+ function listRunInteractions(rootDir, runId) {
164
+ const interactions = readLedger(rootDir, runId);
165
+ const answers = new Map(
166
+ interactions.filter((event) => event.type === 'ANSWER').map((event) => [event.questionId, event])
167
+ );
168
+ const questions = interactions.filter((event) => event.type === 'QUESTION')
169
+ .map((question) => ({ ...question, answer: answers.get(question.questionId) || null }));
170
+ return {
171
+ runId,
172
+ interactions,
173
+ questions,
174
+ pending: questions.filter((question) => !question.answer)
175
+ };
176
+ }
177
+
178
+ module.exports = {
179
+ MAX_INTERACTIONS,
180
+ MAX_MESSAGE_LENGTH,
181
+ appendRunAnswer,
182
+ appendRunQuestion,
183
+ listRunInteractions
184
+ };
package/lib/run-state.js CHANGED
@@ -14,7 +14,8 @@ const RUN_STATES = Object.freeze({
14
14
  REVIEWED: 'REVIEWED',
15
15
  JUDGED_PASS: 'JUDGED_PASS',
16
16
  DELIVERED: 'DELIVERED',
17
- ESCALATED: 'ESCALATED'
17
+ ESCALATED: 'ESCALATED',
18
+ CANCELLED: 'CANCELLED'
18
19
  });
19
20
 
20
21
  const RUN_MODES = Object.freeze({
@@ -24,18 +25,24 @@ const RUN_MODES = Object.freeze({
24
25
  });
25
26
 
26
27
  const ALLOWED_TRANSITIONS = Object.freeze({
27
- STARTED: ['GOAL_FROZEN'],
28
- GOAL_FROZEN: ['STARTED', 'REPORTED', 'MAKER_COMPLETE'],
28
+ STARTED: ['GOAL_FROZEN', 'CANCELLED'],
29
+ GOAL_FROZEN: ['STARTED', 'REPORTED', 'MAKER_COMPLETE', 'CANCELLED'],
29
30
  REPORTED: [],
30
- MAKER_COMPLETE: ['VERIFIED'],
31
- VERIFIED: ['REVIEWED'],
32
- REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED'],
33
- JUDGED_PASS: ['DELIVERED'],
31
+ MAKER_COMPLETE: ['VERIFIED', 'CANCELLED'],
32
+ VERIFIED: ['REVIEWED', 'CANCELLED'],
33
+ REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED', 'CANCELLED'],
34
+ JUDGED_PASS: ['DELIVERED', 'CANCELLED'],
34
35
  DELIVERED: [],
35
- ESCALATED: []
36
+ ESCALATED: [],
37
+ CANCELLED: []
36
38
  });
37
39
 
38
- const TERMINAL_STATES = new Set([RUN_STATES.REPORTED, RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
40
+ const TERMINAL_STATES = new Set([
41
+ RUN_STATES.REPORTED,
42
+ RUN_STATES.DELIVERED,
43
+ RUN_STATES.ESCALATED,
44
+ RUN_STATES.CANCELLED
45
+ ]);
39
46
 
40
47
  function runsDir(rootDir) {
41
48
  return path.join(rootDir, '.ai-engineering-loop', 'runs');
@@ -199,7 +206,8 @@ function createRun(
199
206
  mode = RUN_MODES.ASSISTED,
200
207
  now = new Date(),
201
208
  workflow = null,
202
- displayName = ''
209
+ displayName = '',
210
+ constraints = ''
203
211
  } = {}
204
212
  ) {
205
213
  assertRunId(runId);
@@ -212,6 +220,12 @@ function createRun(
212
220
 
213
221
  const timestamp = now.toISOString();
214
222
  const normalizedTask = String(task || '').trim();
223
+ const normalizedConstraints = String(constraints || '').trim();
224
+ if (normalizedConstraints.length > 8000) {
225
+ const err = new Error('Run constraints must not exceed 8000 characters');
226
+ err.code = 'INVALID_RUN_CONSTRAINTS';
227
+ throw err;
228
+ }
215
229
  const presentation = runDisplayMetadata(normalizedTask, displayName);
216
230
  const workflowMetadata = writeWorkflowBundle(rootDir, runId, workflow);
217
231
  const state = {
@@ -221,6 +235,7 @@ function createRun(
221
235
  mode: normalizeRunMode(mode),
222
236
  iteration: 1,
223
237
  task: normalizedTask,
238
+ constraints: normalizedConstraints,
224
239
  ...presentation,
225
240
  startedRevision: getGitRevision(rootDir),
226
241
  createdAt: timestamp,
@@ -20,7 +20,14 @@ function studioRuntimeError(message, code) {
20
20
 
21
21
  function createStudioRun(
22
22
  rootDir,
23
- { task, recipeId, mode = RUN_MODES.ASSISTED, displayName = '', now = new Date() } = {}
23
+ {
24
+ task,
25
+ constraints = '',
26
+ recipeId,
27
+ mode = RUN_MODES.ASSISTED,
28
+ displayName = '',
29
+ now = new Date()
30
+ } = {}
24
31
  ) {
25
32
  const normalizedTask = String(task || '').trim();
26
33
  if (!normalizedTask || normalizedTask.length > 2000) {
@@ -53,6 +60,7 @@ function createStudioRun(
53
60
  task: normalizedTask,
54
61
  mode: normalizedMode,
55
62
  displayName,
63
+ constraints,
56
64
  workflow,
57
65
  now
58
66
  });
@@ -22,9 +22,22 @@ const {
22
22
  failWorkflowNode,
23
23
  retryWorkflowNode,
24
24
  startWorkflowNode,
25
- recordWorkflowActivity
25
+ recordWorkflowActivity,
26
+ resolveLoopLimit,
27
+ resolveWorkflowDecision
26
28
  } = require('./workflow-runtime.js');
27
29
  const { listRunHistory, runHistoryDetail, inspectRunArtifact } = require('./run-history.js');
30
+ const {
31
+ duplicateRunAsRecipe,
32
+ runCheckout,
33
+ runNodeIo,
34
+ studioAgentHandoff
35
+ } = require('./run-checkout.js');
36
+ const {
37
+ appendRunAnswer,
38
+ appendRunQuestion,
39
+ listRunInteractions
40
+ } = require('./run-interactions.js');
28
41
  const { saveGoalDraft, freezeGoal, unfreezeGoal } = require('./goal-runtime.js');
29
42
  const { createStudioRun, executeStudioRun } = require('./studio-runtime.js');
30
43
  const { createHandoff, handoffBrief, recordDecision } = require('./handoff.js');
@@ -66,6 +79,7 @@ function liveSnapshot(rootDir) {
66
79
  run,
67
80
  plan: workflow.plan,
68
81
  nodes: workflow.state.nodes,
82
+ loopGroups: workflow.state.loopGroups,
69
83
  budget: budgetStatus(rootDir, { runId: run.runId }),
70
84
  events: workflow.events.slice(-50).map(({ initialNodes, changes, ...event }) => ({
71
85
  ...event,
@@ -139,6 +153,15 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
139
153
  const scopedGoal = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal$/);
140
154
  const scopedGoalFreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/freeze$/);
141
155
  const scopedGoalUnfreeze = url.pathname.match(/^\/api\/runs\/([^/]+)\/goal\/unfreeze$/);
156
+ const scopedCheckout = url.pathname.match(/^\/api\/runs\/([^/]+)\/checkout$/);
157
+ const scopedRunNode = url.pathname.match(/^\/api\/runs\/([^/]+)\/nodes\/([^/]+)$/);
158
+ const scopedDecision = url.pathname.match(/^\/api\/runs\/([^/]+)\/nodes\/([^/]+)\/decision$/);
159
+ const scopedLoopLimit = url.pathname.match(/^\/api\/runs\/([^/]+)\/loops\/([^/]+)\/limit$/);
160
+ const scopedDuplicate = url.pathname.match(/^\/api\/runs\/([^/]+)\/duplicate$/);
161
+ const scopedAgentHandoff = url.pathname.match(/^\/api\/runs\/([^/]+)\/agent-handoff$/);
162
+ const scopedInteractions = url.pathname.match(/^\/api\/runs\/([^/]+)\/interactions$/);
163
+ const scopedQuestions = url.pathname.match(/^\/api\/runs\/([^/]+)\/questions$/);
164
+ const scopedAnswer = url.pathname.match(/^\/api\/runs\/([^/]+)\/questions\/([^/]+)\/answer$/);
142
165
  if (request.method === 'GET' && url.pathname === '/api/bootstrap') {
143
166
  json(response, 200, { ok: true, ...bootstrap(rootDir) });
144
167
  } else if (request.method === 'GET' && url.pathname === '/api/live') {
@@ -168,6 +191,79 @@ function createStudioServer(rootDir, { token = crypto.randomBytes(24).toString('
168
191
  url.searchParams.get('path')
169
192
  )
170
193
  });
194
+ } else if (request.method === 'GET' && scopedCheckout) {
195
+ json(response, 200, {
196
+ ok: true,
197
+ checkout: runCheckout(rootDir, decodeURIComponent(scopedCheckout[1]))
198
+ });
199
+ } else if (request.method === 'POST' && scopedDecision) {
200
+ const body = await readBody(request);
201
+ const workflow = resolveWorkflowDecision(
202
+ rootDir,
203
+ decodeURIComponent(scopedDecision[2]),
204
+ {
205
+ runId: decodeURIComponent(scopedDecision[1]),
206
+ outcome: body.outcome,
207
+ actor: body.actor || 'studio-user'
208
+ }
209
+ );
210
+ json(response, 200, { ok: true, nodes: workflow.state.nodes, loopGroups: workflow.state.loopGroups });
211
+ } else if (request.method === 'POST' && scopedLoopLimit) {
212
+ const body = await readBody(request);
213
+ const workflow = resolveLoopLimit(
214
+ rootDir,
215
+ decodeURIComponent(scopedLoopLimit[2]),
216
+ {
217
+ runId: decodeURIComponent(scopedLoopLimit[1]),
218
+ action: body.action,
219
+ expectedIteration: body.expectedIteration,
220
+ actor: body.actor || 'studio-user',
221
+ reason: body.reason
222
+ }
223
+ );
224
+ json(response, 200, { ok: true, nodes: workflow.state.nodes, loopGroups: workflow.state.loopGroups });
225
+ } else if (request.method === 'GET' && scopedRunNode) {
226
+ json(response, 200, {
227
+ ok: true,
228
+ io: runNodeIo(
229
+ rootDir,
230
+ decodeURIComponent(scopedRunNode[1]),
231
+ decodeURIComponent(scopedRunNode[2])
232
+ )
233
+ });
234
+ } else if (request.method === 'POST' && scopedDuplicate) {
235
+ const body = await readBody(request);
236
+ json(response, 200, {
237
+ ok: true,
238
+ preview: duplicateRunAsRecipe(rootDir, decodeURIComponent(scopedDuplicate[1]), body)
239
+ });
240
+ } else if (request.method === 'GET' && scopedAgentHandoff) {
241
+ json(response, 200, {
242
+ ok: true,
243
+ handoff: studioAgentHandoff(rootDir, decodeURIComponent(scopedAgentHandoff[1]))
244
+ });
245
+ } else if (request.method === 'GET' && scopedInteractions) {
246
+ json(response, 200, {
247
+ ok: true,
248
+ interactions: listRunInteractions(rootDir, decodeURIComponent(scopedInteractions[1]))
249
+ });
250
+ } else if (request.method === 'POST' && scopedQuestions) {
251
+ const body = await readBody(request);
252
+ json(response, 201, {
253
+ ok: true,
254
+ question: appendRunQuestion(rootDir, decodeURIComponent(scopedQuestions[1]), body)
255
+ });
256
+ } else if (request.method === 'POST' && scopedAnswer) {
257
+ const body = await readBody(request);
258
+ json(response, 201, {
259
+ ok: true,
260
+ answer: appendRunAnswer(
261
+ rootDir,
262
+ decodeURIComponent(scopedAnswer[1]),
263
+ decodeURIComponent(scopedAnswer[2]),
264
+ body
265
+ )
266
+ });
171
267
  } else if (request.method === 'POST' && scopedExecute) {
172
268
  const result = executeStudioRun(rootDir, decodeURIComponent(scopedExecute[1]));
173
269
  json(response, 200, {