ai-engineering-loop 1.9.4 → 1.11.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.
@@ -46,6 +46,7 @@ const {
46
46
  assertModeAllowed,
47
47
  loadPolicy,
48
48
  normalizeMode,
49
+ normalizeReviewProfile,
49
50
  updatePolicy
50
51
  } = require('../lib/runtime-policy.js');
51
52
  const {
@@ -55,6 +56,11 @@ const {
55
56
  createContextPack,
56
57
  contextPackSummary
57
58
  } = require('../lib/safe-context.js');
59
+ const {
60
+ buildContextIndex,
61
+ createDiffHunkPack,
62
+ smartContextSummary
63
+ } = require('../lib/smart-context.js');
58
64
  const {
59
65
  defaultCasesDir,
60
66
  loadEvaluationCases,
@@ -65,6 +71,9 @@ const {
65
71
  const {
66
72
  assessRunEscalation
67
73
  } = require('../lib/escalation.js');
74
+ const {
75
+ writeVerificationSummary
76
+ } = require('../lib/verification-summary.js');
68
77
  const {
69
78
  runDoctor
70
79
  } = require('../lib/doctor.js');
@@ -1045,9 +1054,11 @@ function handlePolicy() {
1045
1054
  const mode = argValue('--default-mode');
1046
1055
  const allowUnattended = argValue('--allow-unattended');
1047
1056
  const requireSandbox = argValue('--require-sandbox');
1057
+ const reviewProfile = argValue('--review-profile');
1048
1058
  const perRunLimit = argValue('--per-run-token-limit');
1049
1059
  const dailyLimit = argValue('--daily-token-limit');
1050
1060
  if (mode != null) changes.defaultMode = normalizeMode(mode);
1061
+ if (reviewProfile != null) changes.reviewProfile = normalizeReviewProfile(reviewProfile);
1051
1062
  if (allowUnattended != null) {
1052
1063
  changes.allowUnattended = parseBooleanArg('--allow-unattended', allowUnattended);
1053
1064
  }
@@ -1142,6 +1153,35 @@ function handleSandbox() {
1142
1153
  }
1143
1154
  }
1144
1155
 
1156
+ function handleVerification() {
1157
+ const action = process.argv[3] || 'summarize';
1158
+ const json = process.argv.includes('--json');
1159
+ const runId = argValue('--run');
1160
+ try {
1161
+ if (action !== 'summarize') throw new Error('Unknown verification action. Use summarize');
1162
+ const result = writeVerificationSummary(CWD, { runId });
1163
+ if (json) {
1164
+ console.log(JSON.stringify({
1165
+ ok: true,
1166
+ path: result.path,
1167
+ commandCount: result.summary.commandCount,
1168
+ exitCode: result.summary.exitCode,
1169
+ passed: result.summary.passed,
1170
+ testCounts: result.summary.testCounts
1171
+ }));
1172
+ } else {
1173
+ log.success('✓ verification summary created');
1174
+ console.log(`- Path: ${result.path}`);
1175
+ console.log(`- Commands: ${result.summary.commandCount}, exit code: ${result.summary.exitCode}`);
1176
+ console.log(`- Tests: ${JSON.stringify(result.summary.testCounts)}`);
1177
+ }
1178
+ } catch (err) {
1179
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'VERIFICATION_ERROR', error: err.message }));
1180
+ else log.error(err.message);
1181
+ process.exit(1);
1182
+ }
1183
+ }
1184
+
1145
1185
  function handleGate() {
1146
1186
  const gate = process.argv[3];
1147
1187
  const runId = argValue('--run');
@@ -1168,11 +1208,15 @@ function handleGate() {
1168
1208
  const run = target.workflow
1169
1209
  ? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
1170
1210
  : applyGate(CWD, gate, { runId: target.runId });
1211
+ const runCompleted = run.state === 'DELIVERED' || run.state === 'REPORTED';
1171
1212
  appendRunLifecycle(CWD, target.runId, {
1172
- type: run.state === 'DELIVERED' || run.state === 'REPORTED' ? 'RUN_COMPLETED' : 'NODE_COMPLETED',
1173
- ...(lifecycleNode ? { nodeId: lifecycleNode.id } : {}),
1213
+ type: runCompleted
1214
+ ? 'RUN_COMPLETED'
1215
+ : (lifecycleNode ? 'NODE_COMPLETED' : 'PHASE_COMPLETED'),
1216
+ ...(!runCompleted && lifecycleNode ? { nodeId: lifecycleNode.id } : {}),
1174
1217
  phase: gate,
1175
1218
  actor: 'agent',
1219
+ status: 'PASSED',
1176
1220
  message: `${lifecycleNode?.displayName || gate} completed`
1177
1221
  });
1178
1222
  if (json) {
@@ -1325,16 +1369,45 @@ function commandFiles(startIndex, optionsWithValues = []) {
1325
1369
  function handleContext() {
1326
1370
  const stage = process.argv[3];
1327
1371
  const runId = argValue('--run');
1372
+ const profile = argValue('--profile');
1373
+ const base = argValue('--base') || 'HEAD';
1328
1374
  const json = process.argv.includes('--json');
1329
- const files = commandFiles(4, ['--run']);
1375
+ const files = commandFiles(4, ['--run', '--profile', '--base']);
1330
1376
  try {
1331
- const result = createContextPack(CWD, { runId, stage, files });
1377
+ if (stage === 'index') {
1378
+ const result = buildContextIndex(CWD, { files });
1379
+ const summary = smartContextSummary(result);
1380
+ if (json) {
1381
+ console.log(JSON.stringify({ ok: true, ...summary }));
1382
+ } else {
1383
+ log.success('✓ smart context index created');
1384
+ console.log(`- Path: ${summary.path}`);
1385
+ console.log(`- Files: ${summary.files}`);
1386
+ }
1387
+ return;
1388
+ }
1389
+ if (stage === 'diff-hunks' || stage === 'diff-pack') {
1390
+ const result = createDiffHunkPack(CWD, { runId, base, profile });
1391
+ const summary = smartContextSummary(result);
1392
+ if (json) {
1393
+ console.log(JSON.stringify({ ok: true, ...summary }));
1394
+ } else {
1395
+ log.success('✓ smart diff hunk pack created');
1396
+ console.log(`- Path: ${summary.path}`);
1397
+ console.log(`- Review profile: ${summary.reviewProfile}`);
1398
+ console.log(`- Files: ${summary.files}, estimated tokens: ${summary.estimatedTokens}`);
1399
+ console.log(`- Unresolved findings: ${summary.unresolvedFindings}, truncated: ${summary.truncated}`);
1400
+ }
1401
+ return;
1402
+ }
1403
+ const result = createContextPack(CWD, { runId, stage, files, profile });
1332
1404
  const summary = contextPackSummary(result);
1333
1405
  if (json) {
1334
1406
  console.log(JSON.stringify({ ok: true, ...summary }));
1335
1407
  } else {
1336
1408
  log.success(`✓ ${stage} context pack created`);
1337
1409
  console.log(`- Path: ${summary.path}`);
1410
+ console.log(`- Review profile: ${summary.reviewProfile}`);
1338
1411
  console.log(`- Files: ${summary.files}, estimated tokens: ${summary.estimatedTokens}`);
1339
1412
  console.log(`- Redactions: ${summary.redactions}, truncated files: ${summary.truncatedFiles}`);
1340
1413
  }
@@ -1742,7 +1815,7 @@ function handleGoal() {
1742
1815
  expectedHash
1743
1816
  });
1744
1817
  appendRunLifecycle(CWD, runId, {
1745
- type: 'NODE_COMPLETED',
1818
+ type: goalNode ? 'NODE_COMPLETED' : 'GOAL_FROZEN',
1746
1819
  ...(goalNode ? { nodeId: goalNode.id } : {}),
1747
1820
  phase: 'goal',
1748
1821
  actor: argValue('--by') || 'human',
@@ -1769,6 +1842,7 @@ function handleActivity() {
1769
1842
  'node-started': 'NODE_STARTED',
1770
1843
  'node-activity': 'NODE_ACTIVITY',
1771
1844
  'node-completed': 'NODE_COMPLETED',
1845
+ 'node-failed': 'NODE_FAILED',
1772
1846
  'loop-iterated': 'LOOP_ITERATED',
1773
1847
  'run-completed': 'RUN_COMPLETED'
1774
1848
  };
@@ -1786,7 +1860,14 @@ function handleActivity() {
1786
1860
  phase: argValue('--phase'),
1787
1861
  nodeId,
1788
1862
  actor: argValue('--by') || 'agent',
1789
- message: argValue('--message') || 'Agent is working'
1863
+ message: argValue('--message') || 'Agent is working',
1864
+ status: argValue('--status'),
1865
+ ...(argValue('--evidence-path') ? {
1866
+ evidence: {
1867
+ path: argValue('--evidence-path'),
1868
+ sha256: argValue('--evidence-hash')
1869
+ }
1870
+ } : {})
1790
1871
  });
1791
1872
  console.log(JSON.stringify({ ok: true, event, presence: runAgentPresence(CWD, runId) }, null, 2));
1792
1873
  } catch (error) {
@@ -1893,6 +1974,8 @@ Commands:
1893
1974
  show [--run <id>]
1894
1975
  draft --file <json> --revision <n> [--run <id>] [--by <agent>]
1895
1976
  freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
1977
+ verification Summarize verification.json for compact Judge context
1978
+ summarize [--run <id>] [--json]
1896
1979
  activity Publish safe Run lifecycle summaries for Studio
1897
1980
  goal-drafting | goal-ready | heartbeat | waiting
1898
1981
  node-started | node-activity | node-completed | loop-iterated | run-completed
@@ -1913,6 +1996,7 @@ Commands:
1913
1996
  show [--json]
1914
1997
  set [--default-mode <mode>] [--allow-unattended true|false]
1915
1998
  [--require-sandbox true|false]
1999
+ [--review-profile lean|standard|thorough]
1916
2000
  [--per-run-token-limit <n>] [--daily-token-limit <n>]
1917
2001
  budget Enforce actual provider-reported token usage and emergency pause
1918
2002
  status [--run <id>] [--node <id>] [--estimate <n>] [--json]
@@ -1922,7 +2006,11 @@ Commands:
1922
2006
  create | capture | abort | status [--run <id>] [--json]
1923
2007
  context <stage> <files...>
1924
2008
  Build a bounded, redacted context pack for maker, devil-advocate, or judge
2009
+ index [files...] build a private source summary index without file bodies
2010
+ diff-hunks build a hunk-only review pack with unresolved findings
1925
2011
  --run <id> target a non-current run
2012
+ --profile lean|standard|thorough override runtime policy for one pack
2013
+ --base <git-ref> base ref for diff-hunks; default HEAD
1926
2014
  --json print only pack metadata; never print packed content
1927
2015
  eval Validate the 20-case production evaluation catalog
1928
2016
  --results <dir> score host-generated JSON results
@@ -2008,6 +2096,9 @@ switch (command) {
2008
2096
  case 'budget':
2009
2097
  handleBudget();
2010
2098
  break;
2099
+ case 'verification':
2100
+ handleVerification();
2101
+ break;
2011
2102
  case 'sandbox':
2012
2103
  handleSandbox();
2013
2104
  break;
@@ -44,6 +44,32 @@ npx ai-engineering-loop budget resume
44
44
 
45
45
  `pause` sets the persistent kill switch. It blocks new run and context/model boundaries, while `budget record` remains available so an in-flight response can still be accounted.
46
46
 
47
+ ## Review profile
48
+
49
+ Context packs default to the `lean` review profile so paid conversational hosts do not exhaust tokens on repeated full-file review context. The profile changes context limits and reviewer output expectations only; it does not skip Goal Contract, verification, Devil's Advocate, Judge, or delivery gates.
50
+
51
+ ```bash
52
+ npx ai-engineering-loop policy set --review-profile lean
53
+ npx ai-engineering-loop policy set --review-profile standard
54
+ npx ai-engineering-loop policy set --review-profile thorough
55
+ ```
56
+
57
+ Use `lean` for normal Codex/GPT Plus-style sessions, `standard` when the diff is broad but still routine, and `thorough` only when the human explicitly opts into a deeper, more expensive review. A single context pack can override the policy without changing future runs:
58
+
59
+ ```bash
60
+ npx ai-engineering-loop context devil-advocate --profile thorough <files...>
61
+ ```
62
+
63
+ Prefer smart context before opening whole files:
64
+
65
+ ```bash
66
+ npx ai-engineering-loop context index
67
+ npx ai-engineering-loop context diff-hunks --run <run-id>
68
+ npx ai-engineering-loop verification summarize --run <run-id>
69
+ ```
70
+
71
+ The index stores file summaries and hashes, never file bodies, and reuses per-hash summaries when files are unchanged. The diff-hunk pack stores bounded changed hunks, file summaries, token estimates, and unresolved blocking findings from the previous ledger. The verification summary stores command outcomes, counts, and short failure excerpts without raw stdout. Iteration 2+ reviewers should start from these compact artifacts and request full source or logs only when the hunk or summary cannot prove or disprove a finding.
72
+
47
73
  ## Unattended Maker isolation
48
74
 
49
75
  After `gate goal`, create the worktree:
package/lib/budget.js CHANGED
@@ -110,6 +110,29 @@ function resolveRun(rootDir, runId) {
110
110
  return current;
111
111
  }
112
112
 
113
+ function pressureRatio(used, limit) {
114
+ if (!Number.isFinite(limit) || limit <= 0) return 0;
115
+ return used / limit;
116
+ }
117
+
118
+ function budgetWarnings({ runPressure, dayPressure, reviewProfile }) {
119
+ const warnings = [];
120
+ if (runPressure >= 0.9) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; finish or compact context before another model call`);
121
+ else if (runPressure >= 0.75) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; use unresolved findings and changed hunks only`);
122
+ else if (runPressure >= 0.5) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; avoid full logs and repeated source dumps`);
123
+
124
+ if (dayPressure >= 0.9) warnings.push(`daily token usage is at ${Math.round(dayPressure * 100)}%; pause non-critical reviews`);
125
+ else if (dayPressure >= 0.75) warnings.push(`daily token usage is at ${Math.round(dayPressure * 100)}%; prefer lean review context`);
126
+
127
+ if (reviewProfile === 'lean' && (runPressure >= 0.75 || dayPressure >= 0.75)) {
128
+ warnings.push('lean review profile is active; keep DA/Judge to focused deltas unless a blocker requires escalation');
129
+ }
130
+ if (reviewProfile === 'thorough') {
131
+ warnings.push('thorough review profile increases context size; use only when the human explicitly accepts the token cost');
132
+ }
133
+ return [...new Set(warnings)];
134
+ }
135
+
113
136
  function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new Date() } = {}) {
114
137
  validateTokenCount('estimatedTokens', estimatedTokens);
115
138
  const run = resolveRun(rootDir, runId);
@@ -156,6 +179,15 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
156
179
  if (estimatedTokens === 0 && spentToday >= policy.dailyTokenLimit) {
157
180
  reasons.push('daily token limit is exhausted');
158
181
  }
182
+ const pressure = {
183
+ run: pressureRatio(projectedThisRun, policy.perRunTokenLimit),
184
+ day: pressureRatio(projectedToday, policy.dailyTokenLimit)
185
+ };
186
+ const warnings = budgetWarnings({
187
+ runPressure: pressure.run,
188
+ dayPressure: pressure.day,
189
+ reviewProfile: policy.reviewProfile
190
+ });
159
191
 
160
192
  return {
161
193
  schemaVersion: 1,
@@ -163,7 +195,9 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
163
195
  day: utcDay(now),
164
196
  allowed: reasons.length === 0,
165
197
  reasons: [...new Set(reasons)],
198
+ warnings,
166
199
  killSwitch: policy.killSwitch,
200
+ reviewProfile: policy.reviewProfile,
167
201
  spentThisRun,
168
202
  perRunTokenLimit: policy.perRunTokenLimit,
169
203
  remainingThisRun: Math.max(0, policy.perRunTokenLimit - spentThisRun),
@@ -171,6 +205,7 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
171
205
  dailyTokenLimit: policy.dailyTokenLimit,
172
206
  remainingToday: Math.max(0, policy.dailyTokenLimit - spentToday),
173
207
  estimatedTokens,
208
+ pressure,
174
209
  ...(node ? {
175
210
  nodeId,
176
211
  spentThisNode,
@@ -2,9 +2,10 @@
2
2
 
3
3
  const { validateRecipe } = require('./recipe.js');
4
4
  const { stableEdgeId } = require('./recipe-graph.js');
5
+ const { listRunInteractions } = require('./run-interactions.js');
5
6
  const { loadRun } = require('./run-state.js');
6
7
  const { inspectRunArtifact } = require('./run-history.js');
7
- const { redactSecrets } = require('./safe-context.js');
8
+ const { redactHomePaths, redactSecrets } = require('./safe-context.js');
8
9
  const { workflowStatus } = require('./workflow-runtime.js');
9
10
 
10
11
  function checkoutError(message, code = 'RUN_CHECKOUT_ERROR') {
@@ -18,15 +19,42 @@ function fallbackPosition(index) {
18
19
  }
19
20
 
20
21
  function redactedValue(value) {
21
- return JSON.parse(redactSecrets(JSON.stringify(value)).text);
22
+ const redactDeep = (item) => {
23
+ if (typeof item === 'string') return redactHomePaths(item);
24
+ if (Array.isArray(item)) return item.map(redactDeep);
25
+ if (item && typeof item === 'object') {
26
+ return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, redactDeep(child)]));
27
+ }
28
+ return item;
29
+ };
30
+ return JSON.parse(redactSecrets(JSON.stringify(redactDeep(value))).text);
22
31
  }
23
32
 
24
- function edgesFromPlan(plan) {
25
- return plan.nodes.flatMap((node) => (node.dependsOn || []).map((from) => ({
26
- id: stableEdgeId(from, node.id),
27
- from,
28
- to: node.id
29
- })));
33
+ function edgeState(sourceStatus, targetStatus) {
34
+ if (targetStatus === 'RUNNING') return 'active';
35
+ if (targetStatus === 'FAILED') return 'failed';
36
+ if (targetStatus === 'SKIPPED') return 'skipped';
37
+ if (targetStatus === 'READY' || targetStatus === 'BLOCKED') return 'waiting';
38
+ if (['PASSED', 'SKIPPED'].includes(sourceStatus) && targetStatus === 'PASSED') return 'passed';
39
+ return 'idle';
40
+ }
41
+
42
+ function edgesFromPlan(plan, state = null) {
43
+ return plan.nodes.flatMap((node) => (node.dependsOn || []).map((from) => {
44
+ const sourceStatus = state?.nodes[from]?.status;
45
+ const targetStatus = state?.nodes[node.id]?.status;
46
+ const stateName = edgeState(sourceStatus, targetStatus);
47
+ return {
48
+ id: stableEdgeId(from, node.id),
49
+ from,
50
+ to: node.id,
51
+ ...(state ? {
52
+ state: stateName,
53
+ traversed: !['idle', 'waiting'].includes(stateName),
54
+ active: stateName === 'active'
55
+ } : {})
56
+ };
57
+ }));
30
58
  }
31
59
 
32
60
  function publicNode(node, state, index) {
@@ -72,7 +100,7 @@ function runCheckout(rootDir, runId) {
72
100
  run: publicRun,
73
101
  graphHash: workflow.plan.graphHash,
74
102
  nodes: workflow.plan.nodes.map((node, index) => publicNode(node, workflow.state, index)),
75
- edges: edgesFromPlan(workflow.plan),
103
+ edges: edgesFromPlan(workflow.plan, workflow.state),
76
104
  loopGroups: (workflow.plan.loopGroups || []).map((group) => ({
77
105
  ...group,
78
106
  runtime: workflow.state.loopGroups[group.id] || null
@@ -110,9 +138,32 @@ function runNodeIo(rootDir, runId, nodeId) {
110
138
  event.type === 'WORKFLOW_CREATED' ||
111
139
  (event.changes || []).some((change) => change.nodeId === nodeId)
112
140
  ).map(({ initialNodes, ...event }) => event);
141
+ const finishedIndex = relevantEvents.findLastIndex((event) =>
142
+ ['NODE_COMPLETED', 'NODE_FAILED'].includes(event.type)
143
+ );
144
+ const finished = relevantEvents[finishedIndex];
145
+ const started = finishedIndex < 0
146
+ ? null
147
+ : relevantEvents.slice(0, finishedIndex).findLast((event) => event.type === 'NODE_STARTED');
148
+ const durationMs = runtime.status !== 'RUNNING' &&
149
+ started && finished && Date.parse(finished.at) >= Date.parse(started.at)
150
+ ? Date.parse(finished.at) - Date.parse(started.at)
151
+ : null;
152
+ let agentInteractions = [];
153
+ let agentInteractionsAvailable = true;
154
+ try {
155
+ agentInteractions = listRunInteractions(rootDir, runId).interactions.slice(-50);
156
+ } catch {
157
+ agentInteractionsAvailable = false;
158
+ }
113
159
  return redactedValue({
114
160
  runId,
115
161
  node: publicNode(node, workflow.state, workflow.plan.nodes.indexOf(node)),
162
+ durationMs,
163
+ loopIteration: runtime.loopIteration || null,
164
+ agentInteractionScope: 'RUN',
165
+ agentInteractionsAvailable,
166
+ agentInteractions,
116
167
  input: {
117
168
  task: node.dependsOn?.length ? null : run.task,
118
169
  constraints: node.dependsOn?.length ? null : (run.constraints || ''),
@@ -160,6 +211,8 @@ function duplicateRunAsRecipe(rootDir, runId, { recipeId } = {}) {
160
211
  function studioAgentHandoff(rootDir, runId) {
161
212
  const run = loadRun(rootDir, runId);
162
213
  const commandRoot = `npx ai-engineering-loop interaction`;
214
+ const lifecycleCommand = `npx ai-engineering-loop activity heartbeat --run ${runId} --phase <phase> --message "<factual update>"`;
215
+ const goalCommand = `npx ai-engineering-loop goal draft --run ${runId} --file <repository-relative-goal.json> --revision <current-revision>`;
163
216
  return redactedValue({
164
217
  runId,
165
218
  externalDispatch: false,
@@ -167,13 +220,17 @@ function studioAgentHandoff(rootDir, runId) {
167
220
  `Continue AI Engineering Loop Run ${runId}.`,
168
221
  `Task: ${run.task}`,
169
222
  run.constraints ? `Constraints: ${run.constraints}` : null,
170
- 'Read the Run state and evidence before acting.',
223
+ 'From the repository root, read the Run state and evidence before acting.',
224
+ `Draft the Goal through the Run-scoped bridge with: ${goalCommand}`,
225
+ `Report persisted lifecycle progress with: ${lifecycleCommand}`,
171
226
  `When blocked, ask with: ${commandRoot} question --run ${runId} --message "Your question"`,
172
227
  `Poll answers with: ${commandRoot} list --run ${runId} --json`,
173
228
  'Do not create a sibling Run or claim completion without Run-bound evidence.'
174
229
  ].filter(Boolean).join('\n'),
175
230
  commands: {
176
231
  inspect: `npx ai-engineering-loop status --run ${runId}`,
232
+ goalDraft: goalCommand,
233
+ lifecycle: lifecycleCommand,
177
234
  question: `${commandRoot} question --run ${runId} --message "Your question"`,
178
235
  answers: `${commandRoot} list --run ${runId} --json`
179
236
  }
@@ -182,6 +239,9 @@ function studioAgentHandoff(rootDir, runId) {
182
239
 
183
240
  module.exports = {
184
241
  duplicateRunAsRecipe,
242
+ edgeState,
243
+ edgesFromPlan,
244
+ redactedValue,
185
245
  runCheckout,
186
246
  runNodeIo,
187
247
  studioAgentHandoff
@@ -0,0 +1,75 @@
1
+ 'use strict';
2
+
3
+ const { loadGoalDraft } = require('./goal-runtime.js');
4
+ const { listRunInteractions } = require('./run-interactions.js');
5
+ const { readAllRunLifecycle } = require('./run-lifecycle.js');
6
+ const { loadRun } = require('./run-state.js');
7
+
8
+ const JOURNEY_STEPS = [
9
+ 'TASK_RECEIVED',
10
+ 'GOAL_DRAFTING',
11
+ 'WAITING_FOR_ANSWERS',
12
+ 'READY_FOR_GOAL_FREEZE',
13
+ 'WORKFLOW_EXECUTION',
14
+ 'RUN_COMPLETE'
15
+ ];
16
+ const TERMINAL_STATES = new Set(['DELIVERED', 'REPORTED', 'ESCALATED', 'CANCELLED']);
17
+
18
+ function runJourney(rootDir, runId, { workflowState = null } = {}) {
19
+ const run = loadRun(rootDir, runId);
20
+ let draft = null;
21
+ let draftAvailable = true;
22
+ let interactions = { pending: [] };
23
+ let interactionsAvailable = true;
24
+ let lifecycle = [];
25
+ let lifecycleAvailable = true;
26
+ try {
27
+ draft = loadGoalDraft(rootDir, runId);
28
+ } catch {
29
+ draftAvailable = false;
30
+ }
31
+ try {
32
+ interactions = listRunInteractions(rootDir, runId);
33
+ } catch {
34
+ interactionsAvailable = false;
35
+ }
36
+ try {
37
+ lifecycle = readAllRunLifecycle(rootDir, runId);
38
+ } catch {
39
+ lifecycleAvailable = false;
40
+ }
41
+ const workflowStarted = Object.values(workflowState?.nodes || {}).some((node) =>
42
+ ['RUNNING', 'PASSED', 'FAILED', 'SKIPPED'].includes(node.status)
43
+ ) || lifecycle.some((event) =>
44
+ ['NODE_STARTED', 'NODE_ACTIVITY', 'NODE_COMPLETED', 'NODE_FAILED', 'LOOP_ITERATED'].includes(event.type)
45
+ );
46
+ const goalFrozen = run.goal?.frozen === true ||
47
+ lifecycle.some((event) => event.type === 'GOAL_FROZEN');
48
+ const complete = TERMINAL_STATES.has(run.state);
49
+ let current = 'TASK_RECEIVED';
50
+ if (draft || lifecycle.some((event) => event.type === 'GOAL_DRAFTING')) current = 'GOAL_DRAFTING';
51
+ if (draft && interactionsAvailable && interactions.pending.length === 0) current = 'READY_FOR_GOAL_FREEZE';
52
+ if (interactions.pending.length > 0 && !workflowStarted) current = 'WAITING_FOR_ANSWERS';
53
+ if (goalFrozen || workflowStarted) current = 'WORKFLOW_EXECUTION';
54
+ if (complete) current = 'RUN_COMPLETE';
55
+ const currentIndex = JOURNEY_STEPS.indexOf(current);
56
+ return {
57
+ runId,
58
+ current,
59
+ blocked: interactionsAvailable ? interactions.pending.length > 0 : null,
60
+ pendingQuestions: interactionsAvailable ? interactions.pending.length : null,
61
+ degradedSources: [
62
+ draftAvailable ? null : 'Goal draft',
63
+ interactionsAvailable ? null : 'Agent Interaction',
64
+ lifecycleAvailable ? null : 'Lifecycle activity'
65
+ ].filter(Boolean),
66
+ sources: { draftAvailable, interactionsAvailable, lifecycleAvailable },
67
+ steps: JOURNEY_STEPS.map((id, index) => ({
68
+ id,
69
+ status: index < currentIndex ? 'COMPLETE' : (index === currentIndex ? 'ACTIVE' : 'PENDING'),
70
+ ...(id === 'WAITING_FOR_ANSWERS' && interactions.pending.length > 0 ? { blocked: true } : {})
71
+ }))
72
+ };
73
+ }
74
+
75
+ module.exports = { JOURNEY_STEPS, runJourney };
@@ -12,15 +12,20 @@ const TYPES = new Set([
12
12
  'GOAL_DRAFTING',
13
13
  'GOAL_DRAFT_UPDATED',
14
14
  'GOAL_READY',
15
+ 'GOAL_FROZEN',
16
+ 'PHASE_COMPLETED',
15
17
  'AGENT_HEARTBEAT',
16
18
  'AGENT_WAITING',
17
19
  'NODE_STARTED',
18
20
  'NODE_ACTIVITY',
19
21
  'NODE_COMPLETED',
22
+ 'NODE_FAILED',
20
23
  'LOOP_ITERATED',
21
24
  'RUN_COMPLETED'
22
25
  ]);
23
26
  const ID = /^[A-Za-z0-9@._-]{1,64}$/;
27
+ const NODE_TYPES = new Set(['NODE_STARTED', 'NODE_ACTIVITY', 'NODE_COMPLETED', 'NODE_FAILED']);
28
+ const STATUSES = new Set(['WORKING', 'WAITING', 'PASSED', 'FAILED', 'SKIPPED', 'UNKNOWN']);
24
29
  const LOCK_STALE_MS = 60_000;
25
30
 
26
31
  function lifecycleError(message, code) {
@@ -98,6 +103,33 @@ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
98
103
  if ((phase && !ID.test(phase)) || (nodeId && !ID.test(nodeId))) {
99
104
  throw lifecycleError('Lifecycle phase or node is invalid', 'INVALID_LIFECYCLE_SCOPE');
100
105
  }
106
+ const run = loadRun(rootDir, runId);
107
+ if (NODE_TYPES.has(event.type)) {
108
+ if (!nodeId) throw lifecycleError('Node lifecycle events require a node Technical ID', 'INVALID_LIFECYCLE_SCOPE');
109
+ if (!run.workflow) throw lifecycleError('Classic Runs cannot publish node-scoped activity', 'INVALID_LIFECYCLE_SCOPE');
110
+ const { workflowStatus } = require('./workflow-runtime.js');
111
+ const workflow = workflowStatus(rootDir, { runId });
112
+ if (!workflow.plan.nodes.some((node) => node.id === nodeId)) {
113
+ throw lifecycleError(`Node ${nodeId} is not part of Run ${runId}`, 'INVALID_LIFECYCLE_SCOPE');
114
+ }
115
+ } else if (nodeId) {
116
+ throw lifecycleError('Run lifecycle events cannot claim a node scope', 'INVALID_LIFECYCLE_SCOPE');
117
+ }
118
+ const status = event.status == null ? null : String(event.status).trim().toUpperCase();
119
+ if (status && !STATUSES.has(status)) {
120
+ throw lifecycleError('Lifecycle status is invalid', 'INVALID_LIFECYCLE_STATUS');
121
+ }
122
+ let evidence = null;
123
+ if (event.evidence != null) {
124
+ const evidencePath = String(event.evidence.path || '').trim();
125
+ const evidenceHash = event.evidence.sha256 == null ? null : String(event.evidence.sha256).trim();
126
+ if (!evidencePath || evidencePath.length > 240 || path.isAbsolute(evidencePath) ||
127
+ evidencePath.split(/[\\/]/).includes('..') ||
128
+ (evidenceHash && !/^[a-f0-9]{64}$/.test(evidenceHash))) {
129
+ throw lifecycleError('Lifecycle evidence reference is invalid', 'INVALID_LIFECYCLE_EVIDENCE');
130
+ }
131
+ evidence = { path: evidencePath, ...(evidenceHash ? { sha256: evidenceHash } : {}) };
132
+ }
101
133
  const message = redactSecrets(String(event.message || '').trim()).text;
102
134
  if (!message || message.length > 240 ||
103
135
  /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(message)) {
@@ -117,7 +149,9 @@ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
117
149
  actor,
118
150
  message,
119
151
  ...(phase ? { phase } : {}),
120
- ...(nodeId ? { nodeId } : {})
152
+ ...(nodeId ? { nodeId } : {}),
153
+ ...(status ? { status } : {}),
154
+ ...(evidence ? { evidence } : {})
121
155
  };
122
156
  const result = { ...material, hash: sha256(material) };
123
157
  fs.appendFileSync(lifecyclePath(rootDir, runId), `${JSON.stringify(result)}\n`, {
@@ -144,6 +178,10 @@ function listRunLifecycle(rootDir, runId, { after = 0, limit = 100 } = {}) {
144
178
  };
145
179
  }
146
180
 
181
+ function readAllRunLifecycle(rootDir, runId) {
182
+ return readLifecycle(rootDir, runId);
183
+ }
184
+
147
185
  function runAgentPresence(rootDir, runId, { now = new Date() } = {}) {
148
186
  const events = readLifecycle(rootDir, runId);
149
187
  const last = events.findLast((event) => event.type === 'AGENT_HEARTBEAT');
@@ -160,5 +198,6 @@ module.exports = {
160
198
  MAX_EVENTS,
161
199
  appendRunLifecycle,
162
200
  listRunLifecycle,
201
+ readAllRunLifecycle,
163
202
  runAgentPresence
164
203
  };