ai-engineering-loop 2.1.0 → 2.3.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.
Files changed (108) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  7. package/.claude/agents/judge.md +5 -2
  8. package/.grok/agents/judge.md +5 -2
  9. package/CHANGELOG.md +46 -0
  10. package/agents/maker.md +1 -1
  11. package/agents/shared/judge.body.md +5 -2
  12. package/bin/ai-engineering-loop.js +303 -77
  13. package/core/definition-of-done.md +2 -2
  14. package/core/escalation-policy.md +1 -1
  15. package/core/goal-contract.md +1 -1
  16. package/core/iteration-policy.md +2 -1
  17. package/core/judge-policy.md +10 -4
  18. package/core/local-workflow-studio.md +12 -7
  19. package/core/orchestration-model.md +8 -7
  20. package/core/repo-config-schema.md +2 -2
  21. package/core/runtime-safety.md +3 -3
  22. package/lib/auto-update.js +8 -14
  23. package/lib/claimed-vs-reality.js +2 -2
  24. package/lib/cli-args.js +3 -1
  25. package/lib/docs.js +1 -1
  26. package/lib/doctor.js +0 -6
  27. package/lib/escalation.js +1 -1
  28. package/lib/fsutil.js +88 -0
  29. package/lib/gates.js +69 -27
  30. package/lib/generate-workflow.js +0 -29
  31. package/lib/goal-runtime.js +3 -2
  32. package/lib/guard-hooks.js +26 -7
  33. package/lib/guard.js +100 -10
  34. package/lib/hosts/doctor.js +1 -5
  35. package/lib/impact-map.js +4 -9
  36. package/lib/jsonl-ledger.js +104 -0
  37. package/lib/learn.js +4 -9
  38. package/lib/loop-groups.js +0 -25
  39. package/lib/migrations.js +1 -5
  40. package/lib/no-progress.js +119 -0
  41. package/lib/node-evidence.js +873 -0
  42. package/lib/orchestration.js +5 -361
  43. package/lib/personal-workflow.js +1 -1
  44. package/lib/quick.js +152 -0
  45. package/lib/receipt.js +1 -5
  46. package/lib/recipe-builder.js +3 -35
  47. package/lib/recipe-graph.js +2 -63
  48. package/lib/recipe.js +2 -4
  49. package/lib/review-ingest.js +116 -0
  50. package/lib/run-abandon.js +2 -1
  51. package/lib/run-checkout.js +8 -13
  52. package/lib/run-compaction.js +4 -12
  53. package/lib/run-interactions.js +16 -71
  54. package/lib/run-lifecycle.js +25 -77
  55. package/lib/run-state.js +68 -17
  56. package/lib/run-watcher.js +11 -14
  57. package/lib/runtime-files.js +45 -1
  58. package/lib/safe-context.js +17 -6
  59. package/lib/sandbox.js +2 -1
  60. package/lib/smart-context.js +3 -13
  61. package/lib/spawn-command.js +94 -0
  62. package/lib/studio-layout.js +2 -8
  63. package/lib/studio-runtime.js +2 -1
  64. package/lib/studio-server.js +25 -5
  65. package/lib/tier.js +36 -10
  66. package/lib/user-state.js +2 -17
  67. package/lib/verification-lanes.js +115 -0
  68. package/lib/verification-recorder.js +110 -22
  69. package/lib/workflow-runtime.js +7 -4
  70. package/package.json +1 -2
  71. package/policies/review-budget.md +1 -1
  72. package/studio/app.js +734 -132
  73. package/studio/index.html +13 -4
  74. package/studio/styles.css +75 -20
  75. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  76. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  77. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  78. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  79. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  80. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  81. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  82. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  83. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  84. package/.claude/skills/animate/RECIPES.md +0 -324
  85. package/.claude/skills/animate/SKILL.md +0 -207
  86. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  87. package/.claude/skills/animate-expo/SKILL.md +0 -263
  88. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  89. package/.claude/skills/apple-design/SKILL.md +0 -290
  90. package/.claude/skills/ask-sonner/API.md +0 -64
  91. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  92. package/.claude/skills/backend-development/SKILL.md +0 -272
  93. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  94. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  95. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  96. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  97. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  98. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  99. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  100. package/.claude/skills/improve-animations/SKILL.md +0 -109
  101. package/.claude/skills/mobile-native/SKILL.md +0 -311
  102. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  103. package/.claude/skills/prototype/PICKER.md +0 -197
  104. package/.claude/skills/prototype/SKILL.md +0 -98
  105. package/.claude/skills/review-animations/SKILL.md +0 -120
  106. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  107. package/.claude/skills/write-swift/SKILL.md +0 -396
  108. package/lib/intern-catalog.js +0 -53
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
3
+ const { sha256 } = require('./fsutil.js');
4
4
 
5
5
  const EDGE_ID = /^[a-z][a-z0-9-]{0,63}$/;
6
6
  const MAX_EDGES = 256;
@@ -10,7 +10,7 @@ function clone(value) {
10
10
  }
11
11
 
12
12
  function stableEdgeId(from, to) {
13
- const digest = crypto.createHash('sha256').update(`${from}\0${to}`).digest('hex').slice(0, 16);
13
+ const digest = sha256(`${from}\0${to}`).slice(0, 16);
14
14
  return `edge-${digest}`;
15
15
  }
16
16
 
@@ -41,71 +41,10 @@ function withDependencies(recipe) {
41
41
  return projected;
42
42
  }
43
43
 
44
- function uniqueId(preferred, occupied) {
45
- if (!occupied.has(preferred)) {
46
- occupied.add(preferred);
47
- return preferred;
48
- }
49
- for (let suffix = 2; ; suffix++) {
50
- const ending = `-${suffix}`;
51
- const candidate = `${preferred.slice(0, 64 - ending.length)}${ending}`;
52
- if (!occupied.has(candidate)) {
53
- occupied.add(candidate);
54
- return candidate;
55
- }
56
- }
57
- }
58
-
59
- function planGraphMerge(existingRecipe, importedRecipe) {
60
- const existing = migrateLegacyRecipe(existingRecipe);
61
- const imported = migrateLegacyRecipe(importedRecipe);
62
- const nodeIds = new Set((existing.nodes || []).map((node) => node.id));
63
- const edgeIds = new Set((existing.edges || []).map((edge) => edge.id));
64
- const loopGroupIds = new Set((existing.loopGroups || []).map((group) => group.id));
65
- const nodeIdMap = {};
66
- const edgeIdMap = {};
67
- const loopGroupIdMap = {};
68
- for (const node of imported.nodes || []) nodeIdMap[node.id] = uniqueId(node.id, nodeIds);
69
- for (const edge of imported.edges || []) edgeIdMap[edge.id] = uniqueId(edge.id, edgeIds);
70
- for (const group of imported.loopGroups || []) {
71
- loopGroupIdMap[group.id] = uniqueId(group.id, loopGroupIds);
72
- }
73
- return { nodeIdMap, edgeIdMap, loopGroupIdMap };
74
- }
75
-
76
- function mergeGraphs(existingRecipe, importedRecipe, plan) {
77
- const existing = migrateLegacyRecipe(existingRecipe);
78
- const imported = migrateLegacyRecipe(importedRecipe);
79
- const nodes = imported.nodes.map((node) => ({ ...node, id: plan.nodeIdMap[node.id] }));
80
- const edges = imported.edges.map((edge) => ({
81
- ...edge,
82
- id: plan.edgeIdMap[edge.id],
83
- from: plan.nodeIdMap[edge.from],
84
- to: plan.nodeIdMap[edge.to]
85
- }));
86
- const loopGroups = (imported.loopGroups || []).map((group) => ({
87
- ...group,
88
- id: plan.loopGroupIdMap[group.id],
89
- nodeIds: group.nodeIds.map((nodeId) => plan.nodeIdMap[nodeId]),
90
- entryNodeId: plan.nodeIdMap[group.entryNodeId],
91
- decisionNodeId: plan.nodeIdMap[group.decisionNodeId],
92
- repeatTargetId: plan.nodeIdMap[group.repeatTargetId],
93
- exitTargetId: plan.nodeIdMap[group.exitTargetId]
94
- }));
95
- return {
96
- ...existing,
97
- nodes: [...existing.nodes, ...nodes],
98
- edges: [...existing.edges, ...edges],
99
- loopGroups: [...(existing.loopGroups || []), ...loopGroups]
100
- };
101
- }
102
-
103
44
  module.exports = {
104
45
  EDGE_ID,
105
46
  MAX_EDGES,
106
- mergeGraphs,
107
47
  migrateLegacyRecipe,
108
- planGraphMerge,
109
48
  stableEdgeId,
110
49
  withDependencies
111
50
  };
package/lib/recipe.js CHANGED
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
5
+ const { sha256: sha256Text } = require('./fsutil.js');
6
6
  const { RUN_MODES, normalizeRunMode } = require('./run-state.js');
7
7
  const {
8
8
  NODE_TYPES,
@@ -80,9 +80,7 @@ function canonicalJson(value) {
80
80
  }
81
81
 
82
82
  function sha256(value) {
83
- return crypto.createHash('sha256').update(
84
- typeof value === 'string' || Buffer.isBuffer(value) ? value : canonicalJson(value)
85
- ).digest('hex');
83
+ return sha256Text(typeof value === 'string' || Buffer.isBuffer(value) ? value : canonicalJson(value));
86
84
  }
87
85
 
88
86
  function validateCondition(condition, location, errors) {
@@ -0,0 +1,116 @@
1
+ 'use strict';
2
+
3
+ // `review ingest`: bind the Finding Ledger to the Devil's Advocate's raw
4
+ // output, so the Maker cannot silently drop or downgrade a finding.
5
+
6
+ const crypto = require('crypto');
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { loadRun, getCurrentRun, runsDir } = require('./run-state.js');
10
+
11
+ const RAW_FILE = 'review-raw.txt';
12
+ const MAX_RAW_BYTES = 2 * 1024 * 1024;
13
+ const SEVERITY_RANK = Object.freeze({ LOW: 0, MEDIUM: 1, HIGH: 2, BLOCKER: 3 });
14
+
15
+ function ingestError(message, code, details = []) {
16
+ return Object.assign(new Error(message), { code, details });
17
+ }
18
+
19
+ function sha256(content) {
20
+ return crypto.createHash('sha256').update(content).digest('hex');
21
+ }
22
+
23
+ // The last JSON object with a `findings` array: fenced ```json blocks first,
24
+ // then the whole text, then every balanced {...} candidate.
25
+ function extractLedger(text) {
26
+ const candidates = [];
27
+ for (const match of String(text).matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)) candidates.push(match[1]);
28
+ candidates.push(text);
29
+ const source = String(text);
30
+ for (let start = source.indexOf('{'); start !== -1; start = source.indexOf('{', start + 1)) {
31
+ let depth = 0;
32
+ let inString = false;
33
+ for (let index = start; index < source.length; index += 1) {
34
+ const char = source[index];
35
+ if (inString) {
36
+ if (char === '\\') index += 1;
37
+ else if (char === '"') inString = false;
38
+ } else if (char === '"') inString = true;
39
+ else if (char === '{') depth += 1;
40
+ else if (char === '}' && --depth === 0) {
41
+ candidates.push(source.slice(start, index + 1));
42
+ break;
43
+ }
44
+ }
45
+ }
46
+ let found = null;
47
+ for (const candidate of candidates) {
48
+ try {
49
+ const value = JSON.parse(candidate);
50
+ if (value && Array.isArray(value.findings)) found = value;
51
+ } catch {
52
+ // not JSON
53
+ }
54
+ }
55
+ return found;
56
+ }
57
+
58
+ function ingestReview(rootDir, { runId, childId, file } = {}) {
59
+ if (!String(childId || '').trim()) throw ingestError('--child-id is required (the reviewer subagent\'s own id)', 'INVALID_USAGE');
60
+ if (!file) throw ingestError('--file <child-output> is required', 'INVALID_USAGE');
61
+ const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
62
+ if (!run) throw ingestError('No current Run. Pass --run <id>.', 'NO_CURRENT_RUN');
63
+ if (run.state !== 'VERIFIED') throw ingestError(`review ingest needs a VERIFIED Run (state is ${run.state})`, 'INVALID_STATE');
64
+ const source = path.resolve(rootDir, file);
65
+ const stat = fs.lstatSync(source);
66
+ if (!stat.isFile() || stat.isSymbolicLink()) throw ingestError('--file must be a regular file', 'INVALID_FILE');
67
+ if (stat.size > MAX_RAW_BYTES) throw ingestError(`--file is larger than ${MAX_RAW_BYTES} bytes`, 'INVALID_FILE');
68
+ const raw = fs.readFileSync(source);
69
+ const ledger = extractLedger(raw.toString('utf8'));
70
+ if (!ledger) throw ingestError('No JSON ledger with a findings array in the reviewer output', 'NO_LEDGER_IN_OUTPUT');
71
+ const runDir = path.join(runsDir(rootDir), run.runId);
72
+ fs.writeFileSync(path.join(runDir, RAW_FILE), raw, { mode: 0o600 });
73
+ const document = {
74
+ ...ledger,
75
+ schemaVersion: 1,
76
+ runId: run.runId,
77
+ diffHash: run.artifacts?.diff?.sha256,
78
+ reviewer: { name: 'devil-advocate', childId: String(childId).trim(), rawSha256: sha256(raw) },
79
+ findings: ledger.findings
80
+ };
81
+ fs.writeFileSync(path.join(runDir, 'findings.json'), `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
82
+ return { runId: run.runId, findings: ledger.findings.length, rawSha256: document.reviewer.rawSha256 };
83
+ }
84
+
85
+ // Checks a ledger against the raw reviewer output it claims to come from.
86
+ // Returns { binding: 'BOUND'|'UNBOUND'|'NOT_REQUIRED', errors }.
87
+ function checkLedgerBinding(rootDir, run, ledger) {
88
+ if ((run.tier?.current || null) === 'T0') return { binding: 'NOT_REQUIRED', errors: [] };
89
+ const rawSha256 = ledger?.reviewer?.rawSha256;
90
+ if (!rawSha256) return { binding: 'UNBOUND', errors: [] };
91
+ const errors = [];
92
+ let raw;
93
+ try {
94
+ raw = fs.readFileSync(path.join(runsDir(rootDir), run.runId, RAW_FILE));
95
+ } catch {
96
+ return { binding: 'BOUND', errors: [`${RAW_FILE} is missing; re-run review ingest`] };
97
+ }
98
+ if (sha256(raw) !== rawSha256) return { binding: 'BOUND', errors: [`${RAW_FILE} does not match reviewer.rawSha256`] };
99
+ const original = extractLedger(raw.toString('utf8'))?.findings || [];
100
+ const current = new Map((ledger.findings || []).map((finding) => [finding.id, finding]));
101
+ for (const finding of original) {
102
+ const now = current.get(finding.id);
103
+ if (!now) {
104
+ errors.push(`finding ${finding.id} from the reviewer was removed`);
105
+ continue;
106
+ }
107
+ const downgraded = (finding.validity === 'VALID' && now.validity !== 'VALID')
108
+ || (SEVERITY_RANK[now.severity] ?? 0) < (SEVERITY_RANK[finding.severity] ?? 0);
109
+ if (downgraded && !String(now.dismissal?.evidence || '').trim()) {
110
+ errors.push(`finding ${finding.id} was downgraded without dismissal.evidence`);
111
+ }
112
+ }
113
+ return { binding: 'BOUND', errors };
114
+ }
115
+
116
+ module.exports = { RAW_FILE, extractLedger, ingestReview, checkLedgerBinding };
@@ -7,6 +7,7 @@
7
7
  // The current.json pointer is released only when it pointed at that run.
8
8
 
9
9
  const fs = require('fs');
10
+ const { ACTOR_ID } = require('./fsutil.js');
10
11
  const {
11
12
  RUN_STATES,
12
13
  TERMINAL_STATES,
@@ -62,7 +63,7 @@ function planAbandon(rootDir, { runId = null, reason, by } = {}) {
62
63
  throw abandonError(`Run ${run.runId} is already finished (${run.state}); nothing to abandon.`, 'RUN_ALREADY_FINISHED', 2);
63
64
  }
64
65
  const actor = String(by || '').trim();
65
- if (!/^[A-Za-z0-9@._-]{1,64}$/.test(actor)) {
66
+ if (!ACTOR_ID.test(actor)) {
66
67
  throw abandonError('--by <name> is required (letters, digits, @._-; max 64).', 'INVALID_RUN_ACTOR');
67
68
  }
68
69
  const cleanReason = redactSecrets(String(reason || '').trim()).text;
@@ -5,6 +5,7 @@ const { stableEdgeId } = require('./recipe-graph.js');
5
5
  const { listRunInteractions } = require('./run-interactions.js');
6
6
  const { loadRun } = require('./run-state.js');
7
7
  const { inspectRunArtifact } = require('./run-history.js');
8
+ const { inspectNodeRun } = require('./node-evidence.js');
8
9
  const { redactHomePaths, redactSecrets } = require('./safe-context.js');
9
10
  const { workflowStatus } = require('./workflow-runtime.js');
10
11
 
@@ -138,17 +139,7 @@ function runNodeIo(rootDir, runId, nodeId) {
138
139
  event.type === 'WORKFLOW_CREATED' ||
139
140
  (event.changes || []).some((change) => change.nodeId === nodeId)
140
141
  ).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;
142
+ const inspected = inspectNodeRun(rootDir, run, node, runtime, workflow.events);
152
143
  let agentInteractions = [];
153
144
  let agentInteractionsAvailable = true;
154
145
  try {
@@ -159,7 +150,8 @@ function runNodeIo(rootDir, runId, nodeId) {
159
150
  return redactedValue({
160
151
  runId,
161
152
  node: publicNode(node, workflow.state, workflow.plan.nodes.indexOf(node)),
162
- durationMs,
153
+ durationMs: inspected.durationMs,
154
+ finishedAt: inspected.finishedAt,
163
155
  loopIteration: runtime.loopIteration || null,
164
156
  agentInteractionScope: 'RUN',
165
157
  agentInteractionsAvailable,
@@ -175,10 +167,13 @@ function runNodeIo(rootDir, runId, nodeId) {
175
167
  reason: runtime.reason || null,
176
168
  loopGroupId: runtime.loopGroupId || null,
177
169
  loopIteration: runtime.loopIteration || null,
170
+ summary: inspected.nodeEvidence?.summary || null,
178
171
  artifact: safeArtifact(rootDir, runId, runtime.artifact)
179
172
  },
180
173
  evidence: safeArtifact(rootDir, runId, runtime.artifact),
181
- timeline: relevantEvents
174
+ nodeEvidence: inspected.nodeEvidence,
175
+ timeline: relevantEvents,
176
+ timelineGroups: inspected.timelineGroups
182
177
  });
183
178
  }
184
179
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
+ const { readJsonOptional } = require('./fsutil.js');
5
6
  const { atomicWriteJson, atomicWritePrivateFile, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
6
7
  const { writeVerificationSummary } = require('./verification-summary.js');
7
8
  const { loadPolicy } = require('./runtime-policy.js');
@@ -19,15 +20,6 @@ function resolveRun(rootDir, runId) {
19
20
  return current;
20
21
  }
21
22
 
22
- function readOptionalJson(filePath) {
23
- if (!fs.existsSync(filePath)) return null;
24
- try {
25
- return JSON.parse(fs.readFileSync(filePath, 'utf8'));
26
- } catch {
27
- return null;
28
- }
29
- }
30
-
31
23
  function firstPresent(...values) {
32
24
  return values.find((value) => value != null && value !== '') ?? null;
33
25
  }
@@ -119,12 +111,12 @@ function markdownSummary(document) {
119
111
  function compactRun(rootDir, { runId } = {}) {
120
112
  const run = resolveRun(rootDir, runId);
121
113
  const runDir = path.join(runsDir(rootDir), run.runId);
122
- const goal = readOptionalJson(path.join(runDir, 'goal-contract.json'));
123
- let verification = readOptionalJson(path.join(runDir, 'verification-summary.json'));
114
+ const goal = readJsonOptional(path.join(runDir, 'goal-contract.json'));
115
+ let verification = readJsonOptional(path.join(runDir, 'verification-summary.json'));
124
116
  if (!verification && fs.existsSync(path.join(runDir, 'verification.json'))) {
125
117
  verification = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
126
118
  }
127
- const findingsDocument = readOptionalJson(path.join(runDir, 'findings.json'));
119
+ const findingsDocument = readJsonOptional(path.join(runDir, 'findings.json'));
128
120
  const openFindings = compactFindings(findingsDocument);
129
121
  const summary = {
130
122
  schemaVersion: 1,
@@ -1,16 +1,13 @@
1
1
  'use strict';
2
2
 
3
- const fs = require('fs');
4
- const path = require('path');
3
+ const { ACTOR_ID } = require('./fsutil.js');
4
+ const { createLedger } = require('./jsonl-ledger.js');
5
5
  const { sha256 } = require('./recipe.js');
6
- const { assertRunId, loadRun, runsDir } = require('./run-state.js');
7
6
  const { redactSecrets } = require('./safe-context.js');
8
7
 
9
8
  const MAX_INTERACTIONS = 500;
10
9
  const MAX_MESSAGE_LENGTH = 8000;
11
- const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
12
10
  const QUESTION_ID = /^q-[a-f0-9]{12}$/;
13
- const LOCK_STALE_MS = 60_000;
14
11
 
15
12
  function interactionError(message, code = 'RUN_INTERACTION_ERROR') {
16
13
  const error = new Error(message);
@@ -18,61 +15,20 @@ function interactionError(message, code = 'RUN_INTERACTION_ERROR') {
18
15
  return error;
19
16
  }
20
17
 
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
- }
18
+ const ledger = createLedger({
19
+ fileName: 'interactions.jsonl',
20
+ maxBytes: 2 * 1024 * 1024,
21
+ types: new Set(['QUESTION', 'ANSWER']),
22
+ codes: { invalid: 'INVALID_RUN_INTERACTIONS', busy: 'RUN_INTERACTION_BUSY' },
23
+ messages: {
24
+ bounded: 'Run interactions must be a bounded regular file',
25
+ event: 'Run interaction',
26
+ busy: 'Another interaction update is in progress'
48
27
  }
49
- }
50
-
51
- function materialHash(event) {
52
- const { hash, ...material } = event;
53
- return sha256(material);
54
- }
28
+ });
55
29
 
56
30
  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;
31
+ return ledger.read(rootDir, runId);
76
32
  }
77
33
 
78
34
  function normalizedMessage(value) {
@@ -92,26 +48,15 @@ function normalizedActor(value) {
92
48
  }
93
49
 
94
50
  function append(rootDir, runId, partial, now) {
95
- const file = ledgerPath(rootDir, runId);
96
51
  const events = readLedger(rootDir, runId);
97
52
  if (events.length >= MAX_INTERACTIONS) {
98
53
  throw interactionError('Run interaction limit reached', 'RUN_INTERACTION_LIMIT');
99
54
  }
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;
55
+ return ledger.append(rootDir, runId, events, partial, now);
111
56
  }
112
57
 
113
58
  function appendRunQuestion(rootDir, runId, { message, actor = 'agent' } = {}, { now = new Date() } = {}) {
114
- return withInteractionLock(rootDir, runId, () => {
59
+ return ledger.withLock(rootDir, runId, () => {
115
60
  const events = readLedger(rootDir, runId);
116
61
  const number = events.filter((event) => event.type === 'QUESTION').length + 1;
117
62
  const cleanMessage = normalizedMessage(message);
@@ -140,7 +85,7 @@ function appendRunAnswer(
140
85
  { message, actor = 'human' } = {},
141
86
  { now = new Date() } = {}
142
87
  ) {
143
- return withInteractionLock(rootDir, runId, () => {
88
+ return ledger.withLock(rootDir, runId, () => {
144
89
  if (!QUESTION_ID.test(String(questionId))) {
145
90
  throw interactionError('Question ID is invalid', 'INVALID_QUESTION_ID');
146
91
  }
@@ -1,9 +1,9 @@
1
1
  'use strict';
2
2
 
3
- const fs = require('fs');
4
3
  const path = require('path');
5
- const { sha256 } = require('./recipe.js');
6
- const { assertRunId, loadRun, runsDir } = require('./run-state.js');
4
+ const { ACTOR_ID } = require('./fsutil.js');
5
+ const { createLedger } = require('./jsonl-ledger.js');
6
+ const { loadRun } = require('./run-state.js');
7
7
  const { redactSecrets } = require('./safe-context.js');
8
8
 
9
9
  const MAX_EVENTS = 2000;
@@ -23,10 +23,8 @@ const TYPES = new Set([
23
23
  'LOOP_ITERATED',
24
24
  'RUN_COMPLETED'
25
25
  ]);
26
- const ID = /^[A-Za-z0-9@._-]{1,64}$/;
27
26
  const NODE_TYPES = new Set(['NODE_STARTED', 'NODE_ACTIVITY', 'NODE_COMPLETED', 'NODE_FAILED']);
28
27
  const STATUSES = new Set(['WORKING', 'WAITING', 'PASSED', 'FAILED', 'SKIPPED', 'UNKNOWN']);
29
- const LOCK_STALE_MS = 60_000;
30
28
 
31
29
  function lifecycleError(message, code) {
32
30
  const error = new Error(message);
@@ -34,73 +32,32 @@ function lifecycleError(message, code) {
34
32
  return error;
35
33
  }
36
34
 
37
- function lifecyclePath(rootDir, runId) {
38
- assertRunId(runId);
39
- loadRun(rootDir, runId);
40
- return path.join(runsDir(rootDir), runId, 'lifecycle.jsonl');
41
- }
42
-
43
- function materialHash(event) {
44
- const { hash, ...material } = event;
45
- return sha256(material);
46
- }
47
-
48
- function readLifecycle(rootDir, runId) {
49
- const file = lifecyclePath(rootDir, runId);
50
- if (!fs.existsSync(file)) return [];
51
- const stat = fs.lstatSync(file);
52
- if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > MAX_LEDGER_BYTES) {
53
- throw lifecycleError('Run lifecycle must be a bounded regular file', 'INVALID_RUN_LIFECYCLE');
54
- }
55
- const events = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
56
- try { return JSON.parse(line); } catch { return null; }
57
- });
58
- let previousHash = null;
59
- for (const [index, event] of events.entries()) {
60
- if (!event || event.runId !== runId || event.sequence !== index + 1 ||
61
- event.previousHash !== previousHash || event.hash !== materialHash(event) ||
62
- !TYPES.has(event.type)) {
63
- throw lifecycleError(`Run lifecycle event ${index + 1} failed integrity validation`, 'INVALID_RUN_LIFECYCLE');
64
- }
65
- previousHash = event.hash;
35
+ const ledger = createLedger({
36
+ fileName: 'lifecycle.jsonl',
37
+ maxBytes: MAX_LEDGER_BYTES,
38
+ types: TYPES,
39
+ codes: { invalid: 'INVALID_RUN_LIFECYCLE', busy: 'RUN_LIFECYCLE_BUSY' },
40
+ messages: {
41
+ bounded: 'Run lifecycle must be a bounded regular file',
42
+ event: 'Run lifecycle event',
43
+ busy: 'Another lifecycle update is in progress'
66
44
  }
67
- return events;
68
- }
45
+ });
69
46
 
70
- function withLock(rootDir, runId, operation) {
71
- const lock = `${lifecyclePath(rootDir, runId)}.lock`;
72
- let descriptor;
73
- try {
74
- try {
75
- descriptor = fs.openSync(lock, 'wx', 0o600);
76
- } catch (error) {
77
- if (error.code !== 'EEXIST') throw error;
78
- const stat = fs.lstatSync(lock);
79
- if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
80
- throw lifecycleError('Another lifecycle update is in progress', 'RUN_LIFECYCLE_BUSY');
81
- }
82
- fs.unlinkSync(lock);
83
- descriptor = fs.openSync(lock, 'wx', 0o600);
84
- }
85
- return operation();
86
- } finally {
87
- if (descriptor != null) {
88
- fs.closeSync(descriptor);
89
- try { fs.unlinkSync(lock); } catch {}
90
- }
91
- }
47
+ function readLifecycle(rootDir, runId) {
48
+ return ledger.read(rootDir, runId);
92
49
  }
93
50
 
94
51
  function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
95
- return withLock(rootDir, runId, () => {
52
+ return ledger.withLock(rootDir, runId, () => {
96
53
  if (!TYPES.has(event?.type)) {
97
54
  throw lifecycleError('Lifecycle type is not allowed', 'INVALID_LIFECYCLE_TYPE');
98
55
  }
99
56
  const actor = String(event.actor || 'agent').trim();
100
- if (!ID.test(actor)) throw lifecycleError('Lifecycle actor is invalid', 'INVALID_LIFECYCLE_ACTOR');
57
+ if (!ACTOR_ID.test(actor)) throw lifecycleError('Lifecycle actor is invalid', 'INVALID_LIFECYCLE_ACTOR');
101
58
  const phase = event.phase == null ? null : String(event.phase).trim();
102
59
  const nodeId = event.nodeId == null ? null : String(event.nodeId).trim();
103
- if ((phase && !ID.test(phase)) || (nodeId && !ID.test(nodeId))) {
60
+ if ((phase && !ACTOR_ID.test(phase)) || (nodeId && !ACTOR_ID.test(nodeId))) {
104
61
  throw lifecycleError('Lifecycle phase or node is invalid', 'INVALID_LIFECYCLE_SCOPE');
105
62
  }
106
63
  const run = loadRun(rootDir, runId);
@@ -139,12 +96,7 @@ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
139
96
  if (events.length >= MAX_EVENTS) {
140
97
  throw lifecycleError('Run lifecycle event limit reached', 'RUN_LIFECYCLE_LIMIT');
141
98
  }
142
- const material = {
143
- schemaVersion: 1,
144
- runId,
145
- sequence: events.length + 1,
146
- previousHash: events.at(-1)?.hash || null,
147
- at: now.toISOString(),
99
+ return ledger.append(rootDir, runId, events, {
148
100
  type: event.type,
149
101
  actor,
150
102
  message,
@@ -152,25 +104,21 @@ function appendRunLifecycle(rootDir, runId, event, { now = new Date() } = {}) {
152
104
  ...(nodeId ? { nodeId } : {}),
153
105
  ...(status ? { status } : {}),
154
106
  ...(evidence ? { evidence } : {})
155
- };
156
- const result = { ...material, hash: sha256(material) };
157
- fs.appendFileSync(lifecyclePath(rootDir, runId), `${JSON.stringify(result)}\n`, {
158
- encoding: 'utf8',
159
- mode: 0o600,
160
- flag: 'a'
161
- });
162
- return result;
107
+ }, now);
163
108
  });
164
109
  }
165
110
 
166
- function listRunLifecycle(rootDir, runId, { after = 0, limit = 100 } = {}) {
111
+ // `latest: true` pages from the newest end so snapshots and cursors reflect the
112
+ // current tail of a long ledger instead of its first page.
113
+ function listRunLifecycle(rootDir, runId, { after = 0, limit = 100, latest = false } = {}) {
167
114
  const cursor = Number(after);
168
115
  const pageSize = Number(limit);
169
116
  if (!Number.isSafeInteger(cursor) || cursor < 0 ||
170
117
  !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
171
118
  throw lifecycleError('Lifecycle cursor or limit is invalid', 'INVALID_LIFECYCLE_CURSOR');
172
119
  }
173
- const events = readLifecycle(rootDir, runId).filter((event) => event.sequence > cursor).slice(0, pageSize);
120
+ const remaining = readLifecycle(rootDir, runId).filter((event) => event.sequence > cursor);
121
+ const events = latest ? remaining.slice(-pageSize) : remaining.slice(0, pageSize);
174
122
  return {
175
123
  runId,
176
124
  events,