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.
@@ -0,0 +1,130 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
6
+
7
+ function verificationSummaryError(message, code = 'VERIFICATION_SUMMARY_ERROR') {
8
+ const err = new Error(message);
9
+ err.code = code;
10
+ return err;
11
+ }
12
+
13
+ function resolveRun(rootDir, runId) {
14
+ if (runId) return loadRun(rootDir, runId);
15
+ const current = getCurrentRun(rootDir);
16
+ if (!current) throw verificationSummaryError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
17
+ return current;
18
+ }
19
+
20
+ function parseCount(patterns, text) {
21
+ for (const pattern of patterns) {
22
+ const match = String(text || '').match(pattern);
23
+ if (match) return Number(match[1]);
24
+ }
25
+ return null;
26
+ }
27
+
28
+ function testCountsFromText(text) {
29
+ const total = parseCount([
30
+ /\btests?\s+(\d+)\b/i,
31
+ /\b(\d+)\s+tests?\b/i,
32
+ /\btotal[:=\s]+(\d+)\b/i
33
+ ], text);
34
+ const passed = parseCount([
35
+ /\bpass(?:ed)?\s+(\d+)\b/i,
36
+ /\b(\d+)\s+pass(?:ed)?\b/i
37
+ ], text);
38
+ const failed = parseCount([
39
+ /\bfail(?:ed)?\s+(\d+)\b/i,
40
+ /\b(\d+)\s+fail(?:ed)?\b/i
41
+ ], text);
42
+ return {
43
+ passed: passed ?? null,
44
+ failed: failed ?? null,
45
+ total: total ?? (passed != null && failed != null ? passed + failed : null)
46
+ };
47
+ }
48
+
49
+ function mergeCounts(left, right) {
50
+ const sumOrNull = (a, b) => (a == null && b == null ? null : (a || 0) + (b || 0));
51
+ return {
52
+ passed: sumOrNull(left.passed, right.passed),
53
+ failed: sumOrNull(left.failed, right.failed),
54
+ total: sumOrNull(left.total, right.total)
55
+ };
56
+ }
57
+
58
+ function failureExcerpt(command) {
59
+ if (Number(command.exitCode || 0) === 0 && !command.timedOut) return null;
60
+ const source = [command.stderr, command.stdout].map((value) => String(value || '').trim()).find(Boolean);
61
+ if (!source) return command.timedOut ? 'Command timed out' : `Command exited ${command.exitCode}`;
62
+ return source.split('\n').map((line) => line.trim()).filter(Boolean).slice(0, 3).join('\n').slice(0, 800);
63
+ }
64
+
65
+ function summarizeCommand(command) {
66
+ const output = `${command.stdout || ''}\n${command.stderr || ''}`;
67
+ return {
68
+ command: String(command.command || ''),
69
+ exitCode: Number(command.exitCode || 0),
70
+ timedOut: Boolean(command.timedOut || command.timeoutStatus === 'TIMED_OUT'),
71
+ durationMs: Number.isFinite(command.durationMs) ? command.durationMs : null,
72
+ startedAt: command.startedAt || null,
73
+ finishedAt: command.finishedAt || null,
74
+ testCounts: testCountsFromText(output),
75
+ failureExcerpt: failureExcerpt(command)
76
+ };
77
+ }
78
+
79
+ function summarizeVerificationBundle(bundle) {
80
+ if (!bundle || typeof bundle !== 'object' || Array.isArray(bundle)) {
81
+ throw verificationSummaryError('verification bundle must be a JSON object', 'INVALID_VERIFICATION');
82
+ }
83
+ const commands = (bundle.commands || []).map(summarizeCommand);
84
+ const testCounts = commands
85
+ .map((command) => command.testCounts)
86
+ .reduce(mergeCounts, { passed: null, failed: null, total: null });
87
+ const exitCode = commands.some((command) => command.timedOut)
88
+ ? 1
89
+ : commands.reduce((highest, command) => Math.max(highest, command.exitCode), 0);
90
+ return {
91
+ schemaVersion: 1,
92
+ runId: bundle.runId || null,
93
+ generatedAt: new Date().toISOString(),
94
+ gitRevision: bundle.gitRevision || bundle.revision || null,
95
+ diffHash: bundle.diffHash || null,
96
+ commandCount: commands.length,
97
+ exitCode,
98
+ passed: exitCode === 0,
99
+ testCounts,
100
+ commands
101
+ };
102
+ }
103
+
104
+ function readVerificationBundle(rootDir, runId) {
105
+ const run = resolveRun(rootDir, runId);
106
+ const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
107
+ let parsed;
108
+ try {
109
+ parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
110
+ } catch (cause) {
111
+ throw verificationSummaryError(`Unable to read verification.json: ${cause.message}`, 'INVALID_VERIFICATION');
112
+ }
113
+ return { run, filePath, bundle: parsed };
114
+ }
115
+
116
+ function writeVerificationSummary(rootDir, { runId } = {}) {
117
+ const { run, bundle } = readVerificationBundle(rootDir, runId);
118
+ const summary = summarizeVerificationBundle({ ...bundle, runId: bundle.runId || run.runId });
119
+ const filePath = path.join(runsDir(rootDir), run.runId, 'verification-summary.json');
120
+ atomicWriteJson(filePath, summary);
121
+ return {
122
+ summary,
123
+ path: path.relative(rootDir, filePath).split(path.sep).join('/')
124
+ };
125
+ }
126
+
127
+ module.exports = {
128
+ summarizeVerificationBundle,
129
+ writeVerificationSummary
130
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.9.4",
3
+ "version": "1.11.0",
4
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": {
@@ -13,15 +13,26 @@ Host files (`.claude/agents/`, `.grok/agents/`, `.agents/`) may differ only in Y
13
13
 
14
14
  - Write `git diff` to `.ai-engineering-loop/tasks/current.diff` before review.
15
15
  - Pass artifact **paths**, not Maker chat.
16
+ - Use the runtime policy `reviewProfile` to size context packs. Default `lean` protects Codex/GPT Plus-style sessions from repeated full-file prompts while keeping all gates intact.
17
+ - Prefer `npx ai-engineering-loop context diff-hunks --run <run-id>` for review. It writes a private hunk-only pack with file summaries and unresolved findings, so reviewers do not need full source bodies unless a cited hunk is insufficient.
18
+ - Run `npx ai-engineering-loop verification summarize --run <run-id>` after writing `verification.json`; pass the summary path to Judge before raw logs.
16
19
  - Spawn DA and Judge as siblings. Do not nest.
17
20
  - Prefer named types `devil-advocate` and `judge`. Use `general-purpose` only if the named type is rejected.
18
21
  - Skip `*.css`, `*report-css*`, generated/vendor. Do not run `git log`.
19
22
 
23
+ | Profile | Intended use | Context behavior |
24
+ |---|---|---|
25
+ | `lean` | Default for normal paid-agent sessions | Smaller packs, compact findings, iteration-delta review |
26
+ | `standard` | Broader routine changes | Moderate packs; still path-first and hunk-first |
27
+ | `thorough` | Explicit human opt-in for expensive review | Previous larger limits; use only when risk justifies cost |
28
+
20
29
  ## Devil's Advocate
21
30
 
22
31
  - At most **8** tool calls, then emit the Finding Ledger.
23
32
  - Read the diff file first. Do not run `git diff` if that path was given.
24
33
  - Open at most **8** files that appear in the diff. Prefer quoting a hunk over opening the whole file.
34
+ - Emit at most **5** findings unless another finding is a BLOCKER. Keep evidence fields short and concrete.
35
+ - On iteration 2+, review only the smart diff-hunk pack's new hunks plus unresolved findings unless the changed evidence reopens an accepted finding.
25
36
  - Report Spec and Standards as separate findings. Do not spawn children to split axes. Do not merge the two axes.
26
37
 
27
38
  ## Judge
@@ -30,3 +41,4 @@ Host files (`.claude/agents/`, `.grok/agents/`, `.agents/`) may differ only in Y
30
41
  - Read the Finding Ledger and Goal Contract first.
31
42
  - Open source only to fact-check a `location` the ledger already cited.
32
43
  - Do not re-review the whole diff. Do not roam the repo.
44
+ - Keep the verdict compact: blocking IDs, accepted tradeoff IDs, and the shortest action that unblocks the next step.
package/studio/app.js CHANGED
@@ -41,6 +41,9 @@ let agentPresence = { status: 'UNKNOWN', lastHeartbeatAt: null };
41
41
  let followExecution = true;
42
42
  let lastFollowedNode;
43
43
  let lifecycleStream;
44
+ let handoffCopiedRunId;
45
+ let onboardingDismissed = false;
46
+ let liveRenderScheduled = false;
44
47
 
45
48
  const DISPLAY_NAME_MAX = 80;
46
49
  const ROOT_TYPES = new Set(['goal-contract', 'trigger']);
@@ -302,15 +305,10 @@ function renderEdges() {
302
305
  if (!from || !to) return;
303
306
  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
304
307
  path.setAttribute('d', edgePath(from, to));
305
- const fromState = catalog.live?.nodes?.[edge.from]?.status;
306
- const toState = catalog.live?.nodes?.[edge.to]?.status;
307
- const liveNodeId = activeLifecycleNodeId();
308
- const active = liveNodeId === edge.to && ['PASSED', 'SKIPPED'].includes(fromState);
309
- const completed = ['PASSED', 'SKIPPED'].includes(fromState) &&
310
- ['PASSED', 'SKIPPED', 'RUNNING'].includes(toState);
308
+ const state = catalog.live?.edges?.find((candidate) => candidate.id === edge.id)?.state || 'idle';
311
309
  path.setAttribute(
312
310
  'class',
313
- `edge${active ? ' active' : ''}${completed ? ' completed' : ''}${selectedEdgeId === edge.id ? ' selected' : ''}`
311
+ `edge edge-${state}${selectedEdgeId === edge.id ? ' selected' : ''}`
314
312
  );
315
313
  path.setAttribute('marker-end', 'url(#arrow)');
316
314
  path.dataset.edgeId = edge.id;
@@ -1196,6 +1194,7 @@ async function ensureStudioRun() {
1196
1194
  });
1197
1195
  }
1198
1196
  activeRunId = created.run.runId;
1197
+ renderHandoffState();
1199
1198
  await refreshLive();
1200
1199
  return activeRunId;
1201
1200
  }
@@ -1203,20 +1202,31 @@ async function ensureStudioRun() {
1203
1202
  function resolveActiveRunConflict(run) {
1204
1203
  return new Promise((resolve) => {
1205
1204
  const dialog = byId('active-run-dialog');
1205
+ let settled = false;
1206
+ const finish = (outcome) => {
1207
+ if (settled) return;
1208
+ settled = true;
1209
+ resolve(outcome);
1210
+ };
1206
1211
  byId('active-run-message').textContent = `${run.displayName || run.runId} · ${run.state}`;
1207
1212
  byId('continue-active-run').onclick = async () => {
1208
- dialog.close();
1209
1213
  activeRunId = run.runId;
1214
+ renderHandoffState();
1210
1215
  byId('goal-dialog').close();
1211
1216
  showWorkspace('runs');
1212
1217
  await loadRuns();
1213
1218
  await loadRunDetail(run.runId);
1214
- resolve('continue');
1219
+ finish('continue');
1220
+ dialog.close();
1221
+ };
1222
+ byId('cancel-active-run-conflict').onclick = () => {
1223
+ dialog.close();
1215
1224
  };
1216
1225
  byId('replace-active-run').onclick = () => {
1226
+ finish('replace');
1217
1227
  dialog.close();
1218
- resolve('replace');
1219
1228
  };
1229
+ dialog.addEventListener('close', () => finish('cancel'), { once: true });
1220
1230
  dialog.showModal();
1221
1231
  });
1222
1232
  }
@@ -1292,7 +1302,17 @@ async function reviewGoal() {
1292
1302
  byId('goal-review').hidden = false;
1293
1303
  byId('goal-review').innerHTML = `
1294
1304
  <strong>${escapeHtml(contract.objective)}</strong>
1295
- <p>${contract.acceptanceCriteria.length} numbered acceptance failure rows are ready.</p>
1305
+ <p class="mono">Revision ${escapeHtml(String(goal.draftRevision))} · ${escapeHtml(goal.draftHash)}</p>
1306
+ <details>
1307
+ <summary>Review all ${contract.acceptanceCriteria.length} criteria</summary>
1308
+ <ol>${contract.acceptanceCriteria.map((criterion) => `
1309
+ <li>
1310
+ <strong>${escapeHtml(criterion.id)} · ${escapeHtml(criterion.statement)}</strong>
1311
+ <p>Evidence: ${escapeHtml(criterion.evidenceRequired)}</p>
1312
+ <p>Failure cases: ${criterion.failureCases.map(escapeHtml).join(' · ')}</p>
1313
+ </li>
1314
+ `).join('')}</ol>
1315
+ </details>
1296
1316
  `;
1297
1317
  byId('confirm-freeze').hidden = false;
1298
1318
  }
@@ -1356,6 +1376,7 @@ function syncGoalFromLive() {
1356
1376
  hydratedGoalKey = null;
1357
1377
  }
1358
1378
  activeRunId = nextRunId;
1379
+ renderHandoffState();
1359
1380
  if (!liveGoal) {
1360
1381
  renderGoalState();
1361
1382
  return;
@@ -1431,13 +1452,23 @@ function startLifecycleStream(runId) {
1431
1452
  ).slice(-100);
1432
1453
  lifecycleSequence = Math.max(lifecycleSequence, result.lifecycle.nextSequence);
1433
1454
  agentPresence = result.presence;
1434
- renderLive();
1455
+ scheduleLiveRender();
1435
1456
  } catch {
1436
1457
  // The regular cursor poll remains the recovery path.
1437
1458
  }
1438
1459
  };
1439
1460
  }
1440
1461
 
1462
+ function scheduleLiveRender() {
1463
+ if (liveRenderScheduled) return;
1464
+ liveRenderScheduled = true;
1465
+ const schedule = window.requestAnimationFrame || ((callback) => setTimeout(callback, 16));
1466
+ schedule(() => {
1467
+ liveRenderScheduled = false;
1468
+ renderLive();
1469
+ });
1470
+ }
1471
+
1441
1472
  function setFollowExecution(enabled) {
1442
1473
  followExecution = enabled;
1443
1474
  const button = byId('follow-execution');
@@ -1555,7 +1586,10 @@ async function loadRunDetail(runId) {
1555
1586
  const y1 = from.position.y + NODE_PORT_Y;
1556
1587
  const x2 = to.position.x;
1557
1588
  const y2 = to.position.y + NODE_PORT_Y;
1558
- return `<path d="M ${x1} ${y1} C ${x1 + 70} ${y1}, ${x2 - 70} ${y2}, ${x2} ${y2}"></path>`;
1589
+ const state = ['idle', 'active', 'passed', 'failed', 'skipped', 'waiting'].includes(edge.state)
1590
+ ? edge.state
1591
+ : 'idle';
1592
+ return `<path class="edge-${state}" d="M ${x1} ${y1} C ${x1 + 70} ${y1}, ${x2 - 70} ${y2}, ${x2} ${y2}"></path>`;
1559
1593
  }).join('');
1560
1594
  const checkoutGroups = (checkout.loopGroups || []).map((group) => {
1561
1595
  const members = checkout.nodes.filter((node) => group.nodeIds.includes(node.id));
@@ -1637,14 +1671,32 @@ async function loadNodeIo(runId, nodeId) {
1637
1671
  const panel = byId('node-io-panel');
1638
1672
  try {
1639
1673
  const { io } = await api(`/api/runs/${encodeURIComponent(runId)}/nodes/${encodeURIComponent(nodeId)}`);
1674
+ const running = io.node.status === 'RUNNING';
1675
+ const interactionEmpty = io.agentInteractionsAvailable === false
1676
+ ? 'Agent Interaction is temporarily unavailable. Other node evidence remains valid.'
1677
+ : 'No Agent Interaction was recorded for this Run.';
1640
1678
  panel.innerHTML = `
1641
- <header><small>NODE I/O · ${escapeHtml(io.node.status)}</small><h3>${escapeHtml(io.node.displayName)}</h3></header>
1642
- <div class="io-grid">
1643
- <section><h4>Input</h4>${io.input.task ? `<p><b>Task</b><br>${escapeHtml(io.input.task)}</p>` : ''}${io.input.constraints ? `<p><b>Constraints</b><br>${escapeHtml(io.input.constraints)}</p>` : ''}${io.input.dependencies.length ? io.input.dependencies.map((dependency) => `<p><b>${escapeHtml(dependency.nodeId)}</b> · ${escapeHtml(dependency.status)}</p>${renderArtifactPreview(dependency.artifact)}`).join('') : '<p class="muted">Root input from this Run.</p>'}</section>
1644
- <section><h4>Output</h4><p><b>${escapeHtml(io.output.status)}</b>${io.output.reason ? ` · ${escapeHtml(io.output.reason)}` : ''}</p>${renderArtifactPreview(io.output.artifact)}</section>
1645
- <section><h4>Evidence</h4>${renderArtifactPreview(io.evidence)}</section>
1646
- <section><h4>Timeline</h4><div class="timeline">${io.timeline.map((event) => `<p><time>${escapeHtml(event.at)}</time><strong>${escapeHtml(event.type)}</strong></p>`).join('') || '<p class="muted">No node events yet.</p>'}</div></section>
1679
+ <header class="node-io-head"><div><small>NODE INSPECTOR · ${escapeHtml(io.node.status)}</small><h3>${escapeHtml(io.node.displayName)}</h3></div><p class="mono">Duration: ${io.durationMs == null ? 'Not available' : `${Number(io.durationMs)} ms`} · Loop Iteration: ${io.loopIteration == null ? 'Not available' : escapeHtml(String(io.loopIteration))}</p></header>
1680
+ <nav class="io-tabs" role="tablist" aria-label="Node details">
1681
+ ${['Input', 'Live Activity', 'Output', 'Evidence', 'Timeline'].map((label, index) => `<button class="io-tab" role="tab" aria-selected="${index === 0}" data-io-tab="${slug(label)}">${label}</button>`).join('')}
1682
+ </nav>
1683
+ <div class="node-data-grid">
1684
+ <section class="io-pane active" data-io-pane="input"><h4>Input</h4>${io.input.task ? `<p><b>Task</b><br>${escapeHtml(io.input.task)}</p>` : ''}${io.input.constraints ? `<p><b>Constraints</b><br>${escapeHtml(io.input.constraints)}</p>` : ''}${io.input.dependencies.length ? io.input.dependencies.map((dependency) => `<p><b>${escapeHtml(dependency.nodeId)}</b> · ${escapeHtml(dependency.status)}</p>${renderArtifactPreview(dependency.artifact)}`).join('') : '<p class="muted">Root input from this Run.</p>'}</section>
1685
+ <section class="io-pane" data-io-pane="live-activity"><h4>Live Activity</h4><p class="muted">Interaction scope: ${escapeHtml(io.agentInteractionScope || 'RUN')} — questions and answers belong to the whole Run, not only this node.</p><p class="node-progress">${running ? 'In progress · waiting for persisted output' : escapeHtml(io.node.status)}</p><div class="timeline">${io.agentInteractions.map((event) => `<p><time>${escapeHtml(event.at)}</time><strong>${escapeHtml(event.type)}</strong> ${escapeHtml(String(event.message ?? ''))}</p>`).join('') || `<p class="muted">${escapeHtml(interactionEmpty)}</p>`}</div></section>
1686
+ <section class="io-pane" data-io-pane="output"><h4>Output</h4><p><b>${running ? 'In progress' : escapeHtml(io.output.status)}</b>${io.output.reason ? ` · ${escapeHtml(io.output.reason)}` : ''}</p>${running ? '<p class="muted">Output will appear after the Agent records a terminal node event.</p>' : renderArtifactPreview(io.output.artifact)}</section>
1687
+ <section class="io-pane" data-io-pane="evidence"><h4>Evidence</h4>${renderArtifactPreview(io.evidence)}</section>
1688
+ <section class="io-pane" data-io-pane="timeline"><h4>Timeline</h4><div class="timeline">${io.timeline.map((event) => `<p><time>${escapeHtml(event.at)}</time><strong>${escapeHtml(event.type)}</strong></p>`).join('') || '<p class="muted">No node events yet.</p>'}</div></section>
1647
1689
  </div>`;
1690
+ panel.querySelectorAll('[data-io-tab]').forEach((button) => {
1691
+ button.onclick = () => {
1692
+ panel.querySelectorAll('[data-io-tab]').forEach((tab) => {
1693
+ tab.setAttribute('aria-selected', String(tab === button));
1694
+ });
1695
+ panel.querySelectorAll('[data-io-pane]').forEach((pane) => {
1696
+ pane.classList.toggle('active', pane.dataset.ioPane === button.dataset.ioTab);
1697
+ });
1698
+ };
1699
+ });
1648
1700
  panel.querySelectorAll('[data-artifact-download]').forEach((button) => {
1649
1701
  button.onclick = async () => {
1650
1702
  try {
@@ -1744,16 +1796,27 @@ async function refreshSelectedCheckout() {
1744
1796
 
1745
1797
  async function copyAgentHandoff(runId = activeRunId) {
1746
1798
  try {
1747
- if (!runId) await ensureStudioRun();
1748
- const result = await api(`/api/runs/${encodeURIComponent(runId || activeRunId)}/agent-handoff`);
1799
+ const targetRunId = runId || await ensureStudioRun();
1800
+ if (!targetRunId) return;
1801
+ const result = await api(`/api/runs/${encodeURIComponent(targetRunId)}/agent-handoff`);
1749
1802
  await navigator.clipboard.writeText(result.handoff.prompt);
1750
- byId('goal-dialog').close();
1803
+ handoffCopiedRunId = targetRunId;
1804
+ renderHandoffState();
1751
1805
  notify('Run-bound prompt copied. Paste it into your AI coding Agent.');
1752
1806
  } catch (error) {
1753
1807
  byId('goal-validation').textContent = error.message;
1754
1808
  }
1755
1809
  }
1756
1810
 
1811
+ function renderHandoffState() {
1812
+ const copied = Boolean(handoffCopiedRunId && handoffCopiedRunId === activeRunId);
1813
+ byId('agent-handoff-state').hidden = !copied;
1814
+ byId('agent-handoff-instructions').textContent = copied
1815
+ ? 'Paste it once into your current AI Agent terminal, then keep Studio open to follow persisted progress.'
1816
+ : '';
1817
+ byId('start-agent').textContent = copied ? 'Copy again' : 'Start with AI Agent';
1818
+ }
1819
+
1757
1820
  function showWorkspace(section) {
1758
1821
  const showingRuns = section === 'runs';
1759
1822
  byId('runs-view').hidden = !showingRuns;
@@ -1997,6 +2060,8 @@ function renderLive() {
1997
2060
  byId('meter').style.width = '0';
1998
2061
  byId('agent-presence').textContent = 'Agent unavailable';
1999
2062
  byId('agent-presence').className = 'agent-presence unknown';
2063
+ const dock = byId('run-activity-dock');
2064
+ if (dock) dock.hidden = true;
2000
2065
  updateRuntimePresentation();
2001
2066
  return;
2002
2067
  }
@@ -2010,6 +2075,23 @@ function renderLive() {
2010
2075
  byId('active-stage').textContent = active?.id || 'Run complete';
2011
2076
  byId('activity').textContent = lifecycle?.message ||
2012
2077
  (active ? runtimeNode.activity || `${runtimeNode.status} · attempt ${runtimeNode.attempts}` : `Final state: ${live.run.state}`);
2078
+ const journeyStatuses = new Set(['pending', 'active', 'complete']);
2079
+ const degradedSources = live.journey?.degradedSources || [];
2080
+ byId('run-journey').dataset.degraded = degradedSources.join(', ');
2081
+ byId('run-journey').innerHTML = (live.journey?.steps || []).map((step) => {
2082
+ const status = String(step?.status || '').toLowerCase();
2083
+ const safeStatus = journeyStatuses.has(status) ? status : 'unknown';
2084
+ const label = String(step?.id || '').replaceAll('_', ' ');
2085
+ const suffix = safeStatus === 'unknown' ? ' (status unavailable)' : '';
2086
+ const blocked = step?.blocked
2087
+ ? (live.journey?.pendingQuestions == null
2088
+ ? ' · unanswered count unavailable'
2089
+ : ` · ${Number(live.journey.pendingQuestions)} unanswered`)
2090
+ : '';
2091
+ return `<li class="${safeStatus}">${escapeHtml(label + suffix + blocked)}</li>`;
2092
+ }).join('') + (degradedSources.length
2093
+ ? `<li class="unknown">${escapeHtml(`${degradedSources.join(' and ')} unavailable — journey may be incomplete`)}</li>`
2094
+ : '');
2013
2095
  const presenceLabel = {
2014
2096
  WORKING: 'Agent working',
2015
2097
  IDLE: 'Agent appears idle',
@@ -2029,10 +2111,34 @@ function renderLive() {
2029
2111
  `).join('') || live.events.slice(-7).reverse().map((event) => `
2030
2112
  <p>${escapeHtml(event.at.slice(11, 19))} · ${escapeHtml(event.type)}</p>
2031
2113
  `).join('');
2114
+ renderRunActivityDock(live, active, runtimeNode, lifecycle);
2032
2115
  updateRuntimePresentation();
2033
2116
  followActiveNode();
2034
2117
  }
2035
2118
 
2119
+ function renderRunActivityDock(live, active, runtimeNode, lifecycle) {
2120
+ const dock = byId('run-activity-dock');
2121
+ if (!dock) return;
2122
+ dock.hidden = false;
2123
+ byId('run-activity-scope').textContent = active ? 'NODE ACTIVITY' : 'RUN ACTIVITY';
2124
+ byId('run-activity-title').textContent = active ? displayName(active) : `Run ${live.run.state}`;
2125
+ byId('run-activity-message').textContent = lifecycle?.message ||
2126
+ runtimeNode?.activity || (active ? runtimeNode?.status : 'Waiting for the next persisted event.');
2127
+ byId('run-activity-status').textContent = runtimeNode?.status || agentPresence.status || live.run.state;
2128
+ const inspect = byId('inspect-live-node');
2129
+ inspect.hidden = !active;
2130
+ inspect.dataset.nodeId = active?.id || '';
2131
+ byId('run-activity-timeline').innerHTML = lifecycleEvents.slice(-4).reverse().map((event) => `
2132
+ <span><time>${escapeHtml(String(event.at || '').slice(11, 19))}</time>${escapeHtml(event.message || event.type)}</span>
2133
+ `).join('');
2134
+ }
2135
+
2136
+ function maybeOpenOnboarding() {
2137
+ const dialog = byId('goal-dialog');
2138
+ if (catalog.live || dialog.open || onboardingDismissed) return;
2139
+ dialog.showModal();
2140
+ }
2141
+
2036
2142
  async function refreshLive() {
2037
2143
  try {
2038
2144
  const result = await api('/api/live');
@@ -2041,12 +2147,19 @@ async function refreshLive() {
2041
2147
  await refreshLifecycle(catalog.live?.run?.runId);
2042
2148
  await refreshGoalDraft(catalog.live?.run?.runId);
2043
2149
  await hydrateGoalFromLive();
2150
+ byId('live-connection-state').hidden = true;
2044
2151
  renderLive();
2045
2152
  await refreshSelectedCheckout();
2046
2153
  await refreshCheckoutInteractions();
2047
2154
  if (!byId('runs-view').hidden) await loadRuns();
2155
+ maybeOpenOnboarding();
2156
+ return true;
2048
2157
  } catch {
2049
- // A transient refresh failure must not discard the draft.
2158
+ // A transient refresh failure must not discard the last valid draft or Run snapshot.
2159
+ byId('live-connection-message').textContent =
2160
+ 'Studio connection lost. Your last valid Run view is preserved.';
2161
+ byId('live-connection-state').hidden = false;
2162
+ return false;
2050
2163
  }
2051
2164
  }
2052
2165
 
@@ -2348,6 +2461,19 @@ async function initialize() {
2348
2461
  byId('close-inspector').onclick = () => byId('inspector-panel').classList.remove('open');
2349
2462
  byId('toggle-execution').onclick = () => byId('execution-panel').classList.toggle('open');
2350
2463
  byId('close-execution').onclick = () => byId('execution-panel').classList.remove('open');
2464
+ byId('open-live-details').onclick = () => byId('execution-panel').classList.add('open');
2465
+ byId('inspect-live-node').onclick = async (event) => {
2466
+ const nodeId = event.currentTarget.dataset.nodeId;
2467
+ if (!activeRunId || !nodeId) return;
2468
+ showWorkspace('runs');
2469
+ await loadRuns();
2470
+ await loadRunDetail(activeRunId);
2471
+ await loadNodeIo(activeRunId, nodeId);
2472
+ };
2473
+ byId('retry-live-connection').onclick = refreshLive;
2474
+ byId('goal-dialog').addEventListener('close', () => {
2475
+ onboardingDismissed = true;
2476
+ });
2351
2477
  await loadRecipe();
2352
2478
  await refreshLive();
2353
2479
  clearInterval(liveTimer);
package/studio/index.html CHANGED
@@ -57,6 +57,20 @@
57
57
  <output id="zoom-level">100%</output>
58
58
  <button id="zoom-in" aria-label="Zoom in">+</button>
59
59
  </div>
60
+ <aside id="run-activity-dock" class="run-activity-dock" aria-live="polite" hidden>
61
+ <span class="activity-orbit" aria-hidden="true"></span>
62
+ <div class="run-activity-copy">
63
+ <small id="run-activity-scope">RUN ACTIVITY</small>
64
+ <strong id="run-activity-title">Waiting for activity</strong>
65
+ <p id="run-activity-message">Persisted Agent activity will appear here.</p>
66
+ </div>
67
+ <div class="run-activity-actions">
68
+ <span id="run-activity-status" class="mono">WAITING</span>
69
+ <button id="inspect-live-node" type="button" hidden>Inspect node</button>
70
+ <button id="open-live-details" type="button">Open live details</button>
71
+ </div>
72
+ <div id="run-activity-timeline" class="run-activity-timeline"></div>
73
+ </aside>
60
74
  <div id="scene">
61
75
  <div id="loop-groups"></div>
62
76
  <svg id="edges" aria-hidden="true">
@@ -105,8 +119,13 @@
105
119
 
106
120
  <aside class="execution-panel" id="execution-panel">
107
121
  <div class="panel-head"><div><small>LIVE EXECUTION</small><h2 id="active-stage">No active run</h2></div><button id="close-execution" aria-label="Close">×</button></div>
122
+ <div id="live-connection-state" class="validation-message" role="status" hidden>
123
+ <span id="live-connection-message"></span>
124
+ <button id="retry-live-connection" type="button">Retry now</button>
125
+ </div>
108
126
  <div class="live-controls"><span id="agent-presence" class="agent-presence unknown">Agent unavailable</span><button id="follow-execution" type="button" aria-pressed="true">Follow execution</button></div>
109
127
  <p id="activity">Waiting for a recipe-bound workflow.</p>
128
+ <ol id="run-journey" class="run-journey" aria-label="Run progress"></ol>
110
129
  <div class="budget-line"><span>Context budget</span><span class="mono" id="budget">—</span></div>
111
130
  <div class="meter"><i id="meter"></i></div>
112
131
  <details>
@@ -162,10 +181,11 @@
162
181
  <form id="goal-form">
163
182
  <header><div><small>GOAL CONTRACT <span id="goal-version">V1</span></small><h2>Start a reliable run</h2></div><div class="dialog-actions"><button type="button" class="dialog-maximize" aria-label="Maximize dialog">□</button><button type="button" data-close="goal-dialog" aria-label="Close">×</button></div></header>
164
183
  <div id="goal-state" class="goal-state draft">Draft · editing allowed</div>
165
- <label for="goal-task">What should the AI Agent deliver?</label><textarea id="goal-task" maxlength="2000" placeholder="Improve Workflow Studio canvas"></textarea>
166
- <label for="goal-constraints">Anything it must keep or avoid? <span class="muted">(optional)</span></label><textarea id="goal-constraints" maxlength="8000" placeholder="Keep existing CLI behavior and do not change the page layout."></textarea>
167
- <details class="advanced-goal">
168
- <summary>Review the Agent's success plan</summary>
184
+ <label for="goal-task">What should the AI Agent deliver?</label><textarea id="goal-task" maxlength="2000" required aria-describedby="goal-task-help" placeholder="Improve Workflow Studio canvas"></textarea>
185
+ <p id="goal-task-help" class="hint">Describe one task. Studio will create one Run and prepare a Run-bound handoff.</p>
186
+ <details id="goal-advanced" class="advanced-goal">
187
+ <summary>Advanced Goal options</summary>
188
+ <label for="goal-constraints">Anything it must keep or avoid? <span class="muted">(optional)</span></label><textarea id="goal-constraints" maxlength="8000" placeholder="Keep existing CLI behavior and do not change the page layout."></textarea>
169
189
  <label for="goal-run-name">Run Display Name</label><input id="goal-run-name" maxlength="100" placeholder="Automatically named from the task">
170
190
  <label for="goal-text">Objective</label><textarea id="goal-text" maxlength="12000" placeholder="The Agent drafts this from your task."></textarea>
171
191
  <label for="goal-criteria">Success checks and failure cases</label>
@@ -173,12 +193,16 @@
173
193
  <p class="hint">The AI Agent drafts these checks. Review them before Freeze.</p>
174
194
  </details>
175
195
  <div id="goal-validation" class="validation-message" aria-live="polite"></div>
196
+ <section id="agent-handoff-state" class="agent-handoff-state" aria-live="polite" hidden>
197
+ <strong>Prompt copied</strong>
198
+ <p id="agent-handoff-instructions">Paste it once into your current AI Agent terminal, then keep Studio open to follow persisted progress.</p>
199
+ </section>
176
200
  <section id="goal-review" class="goal-review" hidden></section>
177
201
  <div id="unfreeze-fields" hidden><label for="unfreeze-reason">Reason for unfreezing</label><textarea id="unfreeze-reason" maxlength="500"></textarea></div>
178
202
  <footer>
179
203
  <button type="button" id="save-goal">Save draft</button>
180
204
  <button type="button" id="unfreeze-goal" hidden>Unfreeze…</button>
181
- <button type="button" id="start-agent" class="primary">Copy for AI Agent</button>
205
+ <button type="button" id="start-agent" class="primary" aria-describedby="agent-handoff-instructions">Start with AI Agent</button>
182
206
  <button type="button" id="review-goal">Review &amp; Freeze</button>
183
207
  <button type="button" id="confirm-freeze" class="primary" hidden>Confirm freeze</button>
184
208
  </footer>
@@ -189,6 +213,7 @@
189
213
  <p id="active-run-message"></p>
190
214
  <div class="goal-state draft">Starting a new Goal will end the current Run. Its history and evidence will remain available.</div>
191
215
  <footer>
216
+ <button type="button" id="cancel-active-run-conflict">Cancel</button>
192
217
  <button type="button" id="continue-active-run">Continue current Run</button>
193
218
  <button type="button" id="replace-active-run" class="primary">End Run &amp; create new Goal</button>
194
219
  </footer>
package/studio/styles.css CHANGED
@@ -50,3 +50,10 @@ dialog{border:1px solid #505057;border-radius:4px;background:var(--panel);color:
50
50
  .wide-dialog{width:min(800px,calc(100vw - 40px))}dialog header{display:flex;align-items:flex-start;justify-content:space-between}dialog header h2{margin:4px 0 18px;font-size:24px;letter-spacing:-.03em}dialog header button{border:0;background:transparent;font-size:20px}dialog label{clear:both;font-size:12px;color:#c7c7cd}dialog input,dialog textarea{width:100%;margin:0 0 18px;padding:12px;border:1px solid #4b4b52;border-radius:3px;background:#19191c;font-size:14px;line-height:1.55}.field-grid{display:grid;grid-template-columns:1fr 1fr;gap:12px}.field-grid.thirds{grid-template-columns:repeat(3,1fr)}.criteria-editor{min-height:170px}.advanced-goal{margin:16px 0;padding:16px;border:1px solid var(--line)}.advanced-goal summary{font-weight:650;margin-bottom:12px}.import-preview,.goal-review{margin:14px 0;padding:16px;border:1px solid var(--line);border-radius:3px;background:#1e1e22}.validation-message{color:#ff9999;line-height:1.55}.goal-state{position:relative;overflow:hidden;margin-bottom:18px;padding:12px;border-radius:3px}.goal-state.draft{background:#493817;color:#f4c46b}.goal-state.frozen{background:var(--accent-soft);color:#91dc7c}.goal-state.frozen::after{content:"❄";position:absolute;right:12px;animation:freeze-pop .7s ease-out both}@keyframes freeze-pop{from{opacity:0;transform:scale(2.4) rotate(-25deg)}to{opacity:1;transform:scale(1) rotate(0)}}.muted{color:var(--muted)}
51
51
  @media(max-width:900px){.run-summary,.secure,#workflow-settings{display:none}.inspector{width:min(360px,calc(100% - 76px))}.library{width:min(300px,calc(100% - 76px))}.canvas-help{display:none}.runs-header{display:block}.run-filters{flex-wrap:wrap}.run-search{width:100%;flex-basis:100%}.runs-layout{grid-template-columns:1fr}.field-grid,.field-grid.thirds,.io-grid{grid-template-columns:1fr}.workspace-tab{padding-inline:8px}.timeline p{grid-template-columns:1fr}.checkout-header{display:block}.checkout-actions{margin-top:14px}.resizable-dialog{min-width:calc(100vw - 24px)}}
52
52
  @media(prefers-reduced-motion:reduce){.edge.active,.goal-state.frozen::after{animation:none}.library,.inspector,.execution-panel,.node{transition:none}}
53
+
54
+ /* Persisted execution states: quiet, legible, and semantic rather than decorative. */
55
+ .node.running,.node.agent-active{border:1px solid var(--accent);box-shadow:0 0 0 1px #28ad0048,0 16px 34px #0008;animation:node-breathe 1.8s ease-in-out infinite}.node.passed{border:1px solid #53614f;box-shadow:0 7px 18px #0005}.node.passed::after,.node.failed::after,.node.skipped::after{position:absolute;right:12px;top:12px;padding:3px 6px;border:1px solid #586154;border-radius:3px;color:#a9c3a2;background:#252a24;content:"✓ PASSED";font:8px ui-monospace,monospace;letter-spacing:.08em}.node.failed::after{content:"× FAILED";border-color:#745150;color:#e09b97;background:#2b2222}.node.skipped::after{content:"— SKIPPED";border-color:#585860;color:#aaaab2;background:#28282d}.node.failed{border-color:#8b4a47}.node.skipped{opacity:.68;border-style:dashed}.node.blocked,.node.waiting{border-color:#806b43;border-style:dashed}.edge.edge-idle{stroke:#66666e}.edge.edge-active{stroke:var(--accent);stroke-width:3;stroke-dasharray:8 10;animation:flow .8s linear infinite}.edge.edge-passed{stroke:#71806d}.edge.edge-failed{stroke:var(--danger);stroke-width:2.5}.edge.edge-skipped{stroke:#696971;stroke-dasharray:4 7}.edge.edge-waiting{stroke:var(--warning);stroke-dasharray:2 7}.checkout-canvas path.edge-active{stroke:var(--accent);stroke-width:3;stroke-dasharray:8 10;animation:flow .8s linear infinite}.checkout-canvas path.edge-passed{stroke:#71806d}.checkout-canvas path.edge-failed{stroke:var(--danger);stroke-width:2.5}.checkout-canvas path.edge-skipped{stroke:#696971;stroke-dasharray:4 7}.checkout-canvas path.edge-waiting{stroke:var(--warning);stroke-dasharray:2 7}.checkout-node.status-running{border:1px solid var(--accent);box-shadow:0 0 0 1px #28ad0048,6px 8px 0 #111114;animation:node-breathe 1.8s ease-in-out infinite}.checkout-node.status-passed{border:1px solid #53614f;box-shadow:6px 6px 0 #111114}.checkout-node.status-passed::after{position:absolute;right:12px;top:12px;padding:3px 6px;border:1px solid #586154;border-radius:3px;color:#a9c3a2;background:#252a24;content:"✓ PASSED";font:8px ui-monospace,monospace;letter-spacing:.08em}@keyframes node-breathe{50%{border-color:#77ce5f;box-shadow:0 0 0 2px #28ad0038,0 18px 38px #0009}}
56
+ .run-activity-dock{position:absolute;z-index:20;top:66px;left:50%;width:min(760px,calc(100% - 64px));transform:translateX(-50%);display:grid;grid-template-columns:auto minmax(0,1fr) auto;gap:12px 16px;align-items:center;padding:13px 15px;border:1px solid #4b4b52;border-radius:7px;background:#252529f7;box-shadow:0 16px 34px #0008}.run-activity-dock[hidden]{display:none}.activity-orbit{width:10px;height:10px;border:2px solid var(--accent);border-radius:50%;box-shadow:0 0 0 4px #28ad0018;animation:activity-orbit 1.5s ease-in-out infinite}.run-activity-copy{min-width:0}.run-activity-copy small{display:block;margin-bottom:3px;color:#91dc7c;font:8px ui-monospace,monospace;letter-spacing:.12em}.run-activity-copy strong,.run-activity-copy p{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.run-activity-copy p{margin:3px 0 0;color:var(--muted);font-size:11px}.run-activity-actions{display:flex;align-items:center;gap:7px}.run-activity-actions .mono{color:var(--muted);font-size:9px}.run-activity-timeline{grid-column:2/-1;display:flex;gap:12px;min-width:0;overflow:hidden;border-top:1px solid #3d3d43;padding-top:7px}.run-activity-timeline span{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:#aaaab1;font-size:9px}.run-activity-timeline time{margin-right:5px;color:#73737c;font-family:ui-monospace,monospace}@keyframes activity-orbit{50%{transform:scale(.72);opacity:.58}}
57
+ .node-io-head{display:flex;justify-content:space-between;gap:20px;align-items:flex-start}.node-io-head p{margin:2px 0;color:var(--muted);font-size:9px}.io-tabs{display:flex;gap:2px;margin-top:18px;border-bottom:1px solid var(--line);overflow-x:auto}.io-tab{border:0;border-bottom:2px solid transparent;border-radius:0;background:transparent;color:var(--muted);white-space:nowrap}.io-tab[aria-selected=true]{border-bottom-color:var(--accent);color:var(--text)}.node-data-grid{display:grid;grid-template-columns:1fr 1fr;gap:1px;background:var(--line)}.io-pane{display:none;min-width:0;min-height:250px;padding:18px;background:#202024}.io-pane.active{display:block}.io-pane h4{margin-top:0;color:#91dc7c;font-size:10px;letter-spacing:.12em;text-transform:uppercase}.io-pane pre{max-height:280px;overflow:auto;white-space:pre-wrap;background:#151518;padding:13px;font-size:11px}.node-progress{padding:10px;border-left:2px solid var(--accent);background:#242a22;color:#c3d9bd}
58
+ @media(max-width:900px){.run-activity-dock{top:58px;width:calc(100% - 24px);grid-template-columns:auto minmax(0,1fr)}.run-activity-actions,.run-activity-timeline{grid-column:2}.run-activity-actions{flex-wrap:wrap}}
59
+ @media(prefers-reduced-motion:reduce){.edge.edge-active,.checkout-canvas path.edge-active,.node.running,.node.agent-active,.checkout-node.status-running,.activity-orbit{animation:none}}