agents-relay 2.0.244 → 2.0.246

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.
package/README.md CHANGED
@@ -127,7 +127,7 @@ Jobs separate durable lifecycle from derived runtime status. Durable lifecycle i
127
127
 
128
128
  The **Job Execution Lifecycle (JEL)** is Create → Plan → Execute → Final Review → Merge → Completed. All work/recovery Tasks must reach a terminal state (SUCCEEDED, FAILED, or CANCELLED) before Final Review is eligible; terminal failure is evidence for the reviewer, not automatic acceptance. The independent Final Reviewer records findings. A PASS goes to the merge gate; CHANGES_REQUIRED persists findings and starts a minimal Planner N+1 repair round, then another Final Review. No automatic Plan N+1 is created after successful work. Planner and Workers use the discovered `ponytail` Skill to avoid unnecessary tasks without omitting required verification. For operator discussion, call this lifecycle **JEL**.
129
129
 
130
- The Dashboard Job detail includes a **View JEL chart** link. It opens a read-only Mermaid popup that shows each persisted Plan, execution round, Final Review (including CHANGES_REQUIRED → Plan N+1), merge stage, and completion status. Every node displays wall-clock elapsed time derived from persisted timestamps (including queued time); missing timing data is labeled **unknown**, not estimated. The JEL popup highlights failed attempts in red, repeated worker attempts (Retry) in purple, and Troubleshooter tasks in amber, as dashed read-only diagnostic branches off their Execute round. Historical failure is shown only when a persisted `recoveryForAttempt` record supports it. The chart never changes Job state. Shortcut-runner jobs display their direct execution path instead of fictitious planning, review, or merge stages.
130
+ The Dashboard Job detail includes a **View JEL chart** link. It opens the full-screen graph viewer (Fit, zoom in/out, Ctrl/⌘-wheel zoom, and drag-to-pan) with a read-only Mermaid diagram that shows each persisted Plan, execution round, Final Review (including CHANGES_REQUIRED → Plan N+1), merge stage, and completion status. Every node displays wall-clock elapsed time derived from persisted timestamps (including queued time); missing timing data is labeled **unknown**, not estimated. The JEL popup highlights failed attempts in red, repeated worker attempts (Retry) in purple, and Troubleshooter tasks in amber, as dashed read-only diagnostic branches off their Execute round. Historical failure is shown only when a persisted `recoveryForAttempt` record supports it. The chart never changes Job state. Shortcut-runner jobs display their direct execution path instead of fictitious planning, review, or merge stages.
131
131
 
132
132
  Lifecycle transition authority lives in the directly renderable canonical flowchart sources linked in [Workflow graph navigation](#workflow-graph-navigation). Git history owns prior graph versions; the working tree contains only the current graph set.
133
133
 
@@ -77,6 +77,12 @@ function taskShortcutInput(input) {
77
77
  catch { /* plain Task text remains available */ }
78
78
  return { taskInput: input };
79
79
  }
80
+ /** Task input is untrusted; only Relay may inject accepted review provenance. */
81
+ function safeShortcutTaskInput(input) {
82
+ const data = taskShortcutInput(input);
83
+ delete data.reviewDecision;
84
+ return data;
85
+ }
80
86
  function shortcutJobCompletionAllowed(job) {
81
87
  const graphs = job.tasks.filter(task => task.agentGraph);
82
88
  return job.state === 'ACTIVE' && job.executionMode === 'shortcut' && job.contentOnly === true && job.prNumber === 0 && !job.localMerge && job.autoMerge === false
@@ -222,8 +228,20 @@ export async function runAgentShortcut(options) {
222
228
  throw new Error(`Durable shortcut receipt ${nodeId} no longer matches its wait, execution, or content fingerprint`);
223
229
  }
224
230
  state.inFlight ??= {};
225
- if (currentTask.state === 'QUEUED' && Object.keys(state.inFlight).length > 0)
226
- throw new Error('Shortcut checkpoint contains an interrupted module execution; refusing automatic replay');
231
+ // A host-bound human review suspends the parent Task *during* an in-flight
232
+ // Shortcut module call. The exact accepted invocation authorizes replaying
233
+ // only that node after the same Task is requeued by the lifecycle Graph.
234
+ let resumedReview = null;
235
+ if (currentTask.state === 'QUEUED' && Object.keys(state.inFlight).length > 0) {
236
+ const pending = Object.entries(state.inFlight);
237
+ const inv = currentTask.interactiveInvocation;
238
+ if (pending.length !== 1 || !inv?.decidedAt || !['approved', 'changes_requested'].includes(inv.status) ||
239
+ inv.executionId !== pending[0][1] || !/^[a-f0-9]{40}$/.test(inv.revision))
240
+ throw new Error('Shortcut checkpoint contains an interrupted module execution; refusing automatic replay');
241
+ resumedReview = { nodeId: pending[0][0], status: inv.status,
242
+ revision: inv.revision, invocationId: inv.invocationId, feedback: inv.feedback, comments: inv.comments };
243
+ delete state.inFlight[pending[0][0]];
244
+ }
227
245
  state.artifactHashes ??= {};
228
246
  for (const [nodeId, hashes] of Object.entries(state.artifactHashes ?? {}))
229
247
  for (const [artifact, expected] of Object.entries(hashes)) {
@@ -339,6 +357,11 @@ export async function runAgentShortcut(options) {
339
357
  heartbeatInFlight = true;
340
358
  void store.mutateJob(job.id, fresh => {
341
359
  const t = fresh.tasks.find(item => item.id === task.id);
360
+ // A managed Preview has already suspended this exact Task and released
361
+ // its lease. Do not reinterpret that authorized handoff as lease loss.
362
+ if (t?.state === 'AWAITING_DECISION' && t.interactiveInvocation?.status === 'awaiting_decision' &&
363
+ t.interactiveInvocation.executionId === currentTask.executionId)
364
+ return fresh;
342
365
  if (fresh.state !== 'ACTIVE' || fresh.pause || !t || t.state !== 'RUNNING' || t.executionId !== currentTask.executionId || t.leaseOwner !== owner) {
343
366
  throw new Error('Shortcut execution lease was fenced during module execution');
344
367
  }
@@ -383,7 +406,7 @@ export async function runAgentShortcut(options) {
383
406
  const raw = await raceAbort(shortcut
384
407
  ? (async () => {
385
408
  const module = await import(pathToFileURL(shortcut).href);
386
- return module.run({ input: { ...taskShortcutInput(task.input), projectPath, jobId: job.id, taskId: task.id, nodeId: id, agent: node.agent, predecessorOutputs }, signal: executionAbort.signal, runCommand: trackedRunCommand });
409
+ return module.run({ input: { ...safeShortcutTaskInput(task.input), projectPath, jobId: job.id, taskId: task.id, nodeId: id, agent: node.agent, predecessorOutputs, ...(resumedReview?.nodeId === id ? { reviewDecision: { status: resumedReview.status, revision: resumedReview.revision, invocationId: resumedReview.invocationId, feedback: resumedReview.feedback, comments: resumedReview.comments } } : {}) }, signal: executionAbort.signal, runCommand: trackedRunCommand });
387
410
  })()
388
411
  : options.runModelNode({ id, agent: node.agent, predecessorOutputs, executionId: currentTask.executionId, signal: executionAbort.signal }), executionAbort.signal);
389
412
  if (leaseHeartbeatError)
@@ -393,6 +416,8 @@ export async function runAgentShortcut(options) {
393
416
  const result = raw;
394
417
  if (result.status === 'WAITING_EVENT' && result.event && typeof result.event === 'object')
395
418
  return { id, value: result };
419
+ if (result.status === 'WAITING_REVIEW')
420
+ return { id, value: result };
396
421
  if (!validOutput(result))
397
422
  throw new Error('shortcut returned an invalid COMPLETED result contract');
398
423
  const artifactPaths = Array.isArray(result.artifacts) ? result.artifacts
@@ -447,6 +472,23 @@ export async function runAgentShortcut(options) {
447
472
  return { id, value: null, error: error instanceof Error ? error.message : String(error) };
448
473
  }
449
474
  }));
475
+ const reviewWait = outcomes.find(result => result.value?.status === 'WAITING_REVIEW');
476
+ if (reviewWait) {
477
+ // The wrapper already persisted RUNNING -> AWAITING_DECISION and
478
+ // released the lease. Keep inFlight as a durable fence until the
479
+ // approved/changes-requested invocation requeues this same Task.
480
+ if (batch.length !== 1)
481
+ return await fail('Interactive Shortcut Review requires a single in-flight node');
482
+ const durable = await findTask();
483
+ if (durable.state !== 'AWAITING_DECISION' || durable.interactiveInvocation?.status !== 'awaiting_decision' ||
484
+ durable.interactiveInvocation.executionId !== currentTask.executionId)
485
+ return await fail('Shortcut Review did not bind the current Task through hostInvocation');
486
+ emit({ nodeId: reviewWait.id, type: 'waiting', data: { invocationId: durable.interactiveInvocation.invocationId,
487
+ executionId: durable.interactiveInvocation.executionId } });
488
+ stopHeartbeat();
489
+ return { outcome: { status: 'WAITING_REVIEW', nodeId: reviewWait.id,
490
+ invocationId: durable.interactiveInvocation.invocationId }, task: durable, fallback: false };
491
+ }
450
492
  const failed = outcomes.find(result => !result.value);
451
493
  for (const result of outcomes) {
452
494
  if (!result.value) {
@@ -115,7 +115,7 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
115
115
  const checkpoint = result.task.result?.data?.shortcut;
116
116
  process.exitCode = checkpoint?.terminal?.status === 'TIMED_OUT' ? 4 : checkpoint?.terminal?.status === 'INTERRUPTED' ? 5 : 1;
117
117
  }
118
- else if (result.outcome.status === 'WAITING_EVENT')
118
+ else if (result.outcome.status === 'WAITING_EVENT' || result.outcome.status === 'WAITING_REVIEW')
119
119
  process.exitCode = 3;
120
120
  }
121
121
  finally {
@@ -83,8 +83,8 @@ ${dashboardStyles}
83
83
  </div>
84
84
  </div>
85
85
  </section>
86
- <dialog id="jel-dialog" class="jel-dialog" aria-label="Job Execution Lifecycle chart"><div class="jel-dialog-header"><strong id="jel-dialog-title">Job Execution Lifecycle</strong><button type="button" id="jel-dialog-close" class="refresh-button" aria-label="Close JEL chart">Close</button></div><div class="jel-legend" aria-label="JEL diagnostics"><span class="jel-legend-failed">Failed</span><span class="jel-legend-retry">Retry</span><span class="jel-legend-troubleshooter">Troubleshooter</span></div><div id="jel-chart" class="jel-chart" aria-live="polite"></div><p id="jel-status" class="subtle">Graph derived from the selected job snapshot.</p></dialog>
87
- <dialog id="graph-dialog" class="graph-dialog" aria-label="Workflow graph viewer"><div class="graph-dialog-header"><strong id="graph-dialog-title">Workflow graph</strong><div class="graph-navigation"><button type="button" id="graph-zoom-out" class="refresh-button" aria-label="Zoom out">−</button><span id="graph-zoom-level" aria-live="polite">100%</span><button type="button" id="graph-zoom-in" class="refresh-button" aria-label="Zoom in">+</button><button type="button" id="graph-zoom-reset" class="refresh-button">Fit</button><button type="button" id="graph-dialog-close" class="refresh-button">Close</button></div></div><div id="graph-dialog-viewport" class="graph-dialog-viewport"></div></dialog>
86
+ <div id="jel-chart" class="graph-canvas jel-chart" aria-live="polite" hidden></div>
87
+ <dialog id="graph-dialog" class="graph-dialog" aria-label="Graph viewer"><div class="graph-dialog-header"><strong id="graph-dialog-title">Workflow graph</strong><div class="graph-navigation"><button type="button" id="graph-zoom-out" class="refresh-button" aria-label="Zoom out">−</button><span id="graph-zoom-level" aria-live="polite">100%</span><button type="button" id="graph-zoom-in" class="refresh-button" aria-label="Zoom in">+</button><button type="button" id="graph-zoom-reset" class="refresh-button">Fit</button><button type="button" id="graph-dialog-close" class="refresh-button">Close</button></div></div><div id="graph-jel-meta" class="graph-jel-meta" hidden><div class="jel-legend" aria-label="JEL diagnostics"><span class="jel-legend-failed">Failed</span><span class="jel-legend-retry">Retry</span><span class="jel-legend-troubleshooter">Troubleshooter</span></div><p id="jel-status" class="subtle">Graph derived from the selected job snapshot.</p></div><div id="graph-dialog-viewport" class="graph-dialog-viewport"></div></dialog>
88
88
  <section id="rules-view" role="tabpanel" aria-labelledby="rules-tab" hidden><div class="panel"><div class="panel-head"><h2>Router Rules</h2><span id="rules-meta" class="subtle"></span></div><div class="panel-body"><div class="router-rules-workspace"><div class="router-rules-pane rules-editor"><h3>Rules Editor</h3><p class="rules-help">Execution Router rules with an explicit <code>[choices]</code> section (provider: model [reasoning] entries, additive to profile defaults) and a <code>[routing-instruction]</code> section forwarded verbatim to Laya. Relay deduplicates, applies hard gates, and sends one merged choice list; impossible routes remain excluded by code and Codex stays the deterministic fallback.</p><textarea id="rules-text" class="rules-textarea" spellcheck="true" aria-label="Execution router rules" placeholder="[choices]\nopenai: sol medium, luna high\nzai: glm-5.3-flash high\n\n[routing-instruction]\nPrefer zai until its quota resets; otherwise use the openai default."></textarea><div class="rules-footer"><span id="rules-status" class="subtle" aria-live="polite"></span><div><button id="rules-test" class="rules-save" type="button">Test Router</button> <button id="rules-save" class="rules-save" type="button">Save rules</button></div></div></div><div class="router-rules-pane"><div class="panel-head"><h3>Audit Log</h3><button id="audit-refresh" type="button">Refresh</button></div><div id="audit-log" class="audit-log" aria-live="polite"><p class="empty">Loading latest routing decisions…</p></div></div></div><div class="router-test-panel"><h3>Test Router Result</h3><div id="router-test-results" class="router-test-results" aria-live="polite"><p class="empty">Select a Job and Task, then run Test Router.</p></div></div></div></div></section>
89
89
  <section id="qa-view" role="tabpanel" aria-labelledby="qa-tab" hidden>
90
90
  <div class="panel"><div class="panel-head"><h2>Troubleshooter Q&A</h2><span class="subtle">skills/agents-relay/troubleshooter-qa.md</span></div>
@@ -216,36 +216,33 @@ function syncFilters(){
216
216
  }
217
217
  function repoName(repository){if(typeof repository!=='string'||!repository)return 'unknown-repo';const parts=repository.split('/').filter(Boolean);return parts.at(-1)||repository;}
218
218
  const buildJelDiagram=${jobJelDiagram.toString()};
219
- const jelDialog=document.querySelector('#jel-dialog');
220
219
  const jelChart=document.querySelector('#jel-chart');
221
220
  const jelStatus=document.querySelector('#jel-status');
222
221
  let jelRenderSequence=0;
223
222
  async function openJelChart(job){
224
223
  const renderId=++jelRenderSequence;
225
- jelDialog.querySelector('#jel-dialog-title').textContent='JEL · '+value(job.repository)+'/'+value(job.id);
226
224
  jelChart.replaceChildren(element('p','subtle',text('Rendering job lifecycle…')));
227
225
  jelStatus.textContent='Wall-clock elapsed from persisted timestamps (includes queued time); unknown means timing data is unavailable. Pending stages are not complete.';
228
- jelDialog.showModal();
226
+ showGraphViewer(jelChart,'JEL · '+value(job.repository)+'/'+value(job.id),true);
229
227
  const source=buildJelDiagram(job);
230
228
  try{
231
229
  if(!window.mermaid)throw new Error('Mermaid unavailable');
232
230
  if(!window.__relayMermaidReady){window.mermaid.initialize({startOnLoad:false,securityLevel:'strict',flowchart:{htmlLabels:false}});window.__relayMermaidReady=true;}
233
231
  const rendered=await window.mermaid.render('relay-jel-'+renderId,source);
234
- if(renderId!==jelRenderSequence||!jelDialog.open)return;
232
+ if(renderId!==jelRenderSequence||!graphDialog.open||graphViewerContent!==jelChart)return;
235
233
  const svg=sanitizeGraphSvg(rendered.svg);
236
234
  const definitions=graphNodeDefinitions(source);
237
235
  for(const node of svg.querySelectorAll('g.node')){const entry=Array.from(definitions.entries()).find(([key])=>node.id.includes('-flowchart-'+key+'-'));if(entry)addNodeLabel(node,entry[1]);}
238
236
  applyGraphPalette(svg);
239
237
  applyJelHighlights(svg);
240
238
  jelChart.replaceChildren(svg);
239
+ fitGraphViewer();
241
240
  }catch(error){
242
- if(renderId!==jelRenderSequence||!jelDialog.open)return;
241
+ if(renderId!==jelRenderSequence||!graphDialog.open||graphViewerContent!==jelChart)return;
243
242
  jelChart.replaceChildren(element('pre','jel-source',text(source)));
244
243
  jelStatus.textContent='Graph preview unavailable; showing the JEL source.';
245
244
  }
246
245
  }
247
- jelDialog.querySelector('#jel-dialog-close').addEventListener('click',()=>jelDialog.close());
248
- jelDialog.addEventListener('close',()=>{jelRenderSequence++;});
249
246
  function applyJelHighlights(svg){
250
247
  const palette={failed:['#fee2e2','#b91c1c','#991b1b'],retry:['#ede9fe','#7c3aed','#5b21b6'],troubleshooter:['#fef3c7','#b45309','#92400e']};
251
248
  for(const node of svg.querySelectorAll('g.node')){
@@ -257,7 +254,7 @@ function applyJelHighlights(svg){
257
254
  for(const label of node.querySelectorAll('text,tspan'))label.setAttribute('fill',color);
258
255
  }
259
256
  }
260
- function jelField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('Job Execution Lifecycle')));const line=element('p','detail-value');const link=element('a','',text('View JEL chart'));link.href='#jel-dialog';link.addEventListener('click',event=>{event.preventDefault();void openJelChart(job);});line.append(link);box.append(line);return box;}
257
+ function jelField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('Job Execution Lifecycle')));const line=element('p','detail-value');const link=element('a','',text('View JEL chart'));link.href='#graph-dialog';link.addEventListener('click',event=>{event.preventDefault();void openJelChart(job);});line.append(link);box.append(line);return box;}
261
258
  function shortcutProgress(job){if(job.executionMode!=='shortcut')return null;const root=(job.tasks||[]).find(task=>task.agentGraph);const checkpoint=root?.result?.data?.shortcut;const nodes=Object.keys(checkpoint?.nodes||{});const pending=Object.keys(checkpoint?.inFlight||{});const completed=nodes.filter(id=>checkpoint.nodes[id]?.status==='COMPLETED').length;const current=pending.length?pending.join(', '):'—';return completed+' completed · '+(pending.length?'running: '+current:'no active node');}
262
259
  function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected filters.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));row.addEventListener('click',()=>selectJob(job));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job);});select.append(element('span','job-title',text(repoName(job.repository)+'/'+value(job.id)+(Number(job.prNumber||0)>0?'/PR#'+value(job.prNumber):'')+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))));if(job.executionMode==='shortcut')states.append(element('span','badge shortcut-mode',text('SHORTCUT')));states.append(element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))));if(job.publicationFailure)states.append(element('span','badge FAILED',text('PUBLISH FAILED: '+value(job.publicationFailure.stage))));else if(job.publication?.version)states.append(element('span','badge SUCCEEDED',text('v'+job.publication.version)));else if(Number(job.prNumber||0)>0&&job.githubState==='MERGED')states.append(element('span','badge MERGED',text('PR Merged')));else if(job.state==='COMPLETED'&&job.githubState==='CLOSED')states.append(element('span','badge SUCCEEDED',text('PR Archived')));if(job.state==='ACTIVE'&&job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(job.localMerge?.status==='failed')states.append(element('span','badge FAILED',text('MERGE FAILED: '+value(job.localMerge.error||'Unknown error'))));else if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const primary=element('div','job-primary');primary.append(states);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
263
260
  function taskTagDisplay(job,task){const display=task.tag&&job?.tag?.values?.[task.tag];return typeof display==='string'&&display?display:null;}
@@ -363,7 +360,104 @@ window.addEventListener('hashchange',syncMobileJobsView);
363
360
  usageTab.addEventListener('click',()=>{location.hash='#/usage';showView('usage');});
364
361
  graphsTab.addEventListener('click',()=>{location.hash='#/graphs/entry';showView('graphs');});
365
362
  document.querySelector('#graph-entry').addEventListener('click',()=>navigateGraph('main'));
366
- const graphDialog=document.querySelector('#graph-dialog');const graphViewport=document.querySelector('#graph-dialog-viewport');let graphZoom=1;const graphCanvasHome=graphCanvas.parentNode;function setGraphZoom(value){graphZoom=Math.min(4,Math.max(.35,value));const svg=graphCanvas.querySelector('svg');if(svg){svg.style.width=(Number(svg.getAttribute('width'))||Math.max(900,svg.viewBox.baseVal.width))*graphZoom+'px';svg.style.maxWidth='none';}document.querySelector('#graph-zoom-level').textContent=Math.round(graphZoom*100)+'%';}document.querySelector('#graph-maximize').addEventListener('click',()=>{graphDialog.showModal();graphViewport.append(graphCanvas);document.querySelector('#graph-dialog-title').textContent=graphTitle.textContent;setGraphZoom(1);});function closeGraphViewer(){graphCanvasHome.insertBefore(graphCanvas,graphCanvasHome.querySelector('.graph-source-details'));setGraphZoom(1);}graphDialog.addEventListener('close',closeGraphViewer);document.querySelector('#graph-dialog-close').addEventListener('click',()=>graphDialog.close());document.querySelector('#graph-zoom-in').addEventListener('click',()=>setGraphZoom(graphZoom*1.25));document.querySelector('#graph-zoom-out').addEventListener('click',()=>setGraphZoom(graphZoom/1.25));document.querySelector('#graph-zoom-reset').addEventListener('click',()=>setGraphZoom(1));graphViewport.addEventListener('wheel',event=>{if(!event.ctrlKey&&!event.metaKey)return;event.preventDefault();setGraphZoom(graphZoom*(event.deltaY<0?1.15:1/1.15));},{passive:false});let drag=null;graphViewport.addEventListener('pointerdown',event=>{if(event.target.closest('.drillable'))return;drag={x:event.clientX,y:event.clientY,left:graphViewport.scrollLeft,top:graphViewport.scrollTop};graphViewport.setPointerCapture(event.pointerId);});graphViewport.addEventListener('pointermove',event=>{if(!drag)return;graphViewport.scrollLeft=drag.left-(event.clientX-drag.x);graphViewport.scrollTop=drag.top-(event.clientY-drag.y);});graphViewport.addEventListener('pointerup',()=>drag=null);graphViewport.addEventListener('pointercancel',()=>drag=null);
363
+ const graphDialog=document.querySelector('#graph-dialog');
364
+ const graphViewport=document.querySelector('#graph-dialog-viewport');
365
+ const graphJelMeta=document.querySelector('#graph-jel-meta');
366
+ const graphZoomLevel=document.querySelector('#graph-zoom-level');
367
+ let graphZoom=1;
368
+ let graphViewerContent=null;
369
+ let graphViewerHome=null;
370
+ let graphViewerNext=null;
371
+ let graphViewerWasHidden=false;
372
+ function graphViewerSvg(){return graphViewerContent?.querySelector('svg')||null;}
373
+ function graphIntrinsicSize(svg){
374
+ const view=svg.viewBox?.baseVal;
375
+ const width=view?.width||Number.parseFloat(svg.getAttribute('width'))||svg.getBoundingClientRect().width||900;
376
+ const height=view?.height||Number.parseFloat(svg.getAttribute('height'))||svg.getBoundingClientRect().height||500;
377
+ return {width:Math.max(1,width),height:Math.max(1,height)};
378
+ }
379
+ function setGraphZoom(value,preserveCenter=true){
380
+ const svg=graphViewerSvg();
381
+ const dimensions=svg?graphIntrinsicSize(svg):null;
382
+ const centerX=dimensions?(graphViewport.scrollLeft+graphViewport.clientWidth/2)/(dimensions.width*graphZoom):0;
383
+ const centerY=dimensions?(graphViewport.scrollTop+graphViewport.clientHeight/2)/(dimensions.height*graphZoom):0;
384
+ graphZoom=Math.max(.05,Math.min(6,Number.isFinite(value)?value:1));
385
+ if(svg&&dimensions){
386
+ svg.style.width=dimensions.width*graphZoom+'px';
387
+ svg.style.height=dimensions.height*graphZoom+'px';
388
+ svg.style.maxWidth='none';
389
+ if(preserveCenter){
390
+ graphViewport.scrollLeft=dimensions.width*graphZoom*centerX-graphViewport.clientWidth/2;
391
+ graphViewport.scrollTop=dimensions.height*graphZoom*centerY-graphViewport.clientHeight/2;
392
+ }
393
+ }
394
+ graphZoomLevel.textContent=Math.round(graphZoom*100)+'%';
395
+ }
396
+ function fitGraphViewer(){
397
+ const svg=graphViewerSvg();
398
+ if(!svg){setGraphZoom(1,false);return;}
399
+ const {width,height}=graphIntrinsicSize(svg);
400
+ const availableWidth=Math.max(1,graphViewport.clientWidth-48);
401
+ const availableHeight=Math.max(1,graphViewport.clientHeight-48);
402
+ setGraphZoom(Math.min(availableWidth/width,availableHeight/height),false);
403
+ graphViewport.scrollLeft=Math.max(0,(graphViewport.scrollWidth-graphViewport.clientWidth)/2);
404
+ graphViewport.scrollTop=Math.max(0,(graphViewport.scrollHeight-graphViewport.clientHeight)/2);
405
+ }
406
+ function showGraphViewer(content,title,isJel=false){
407
+ if(graphDialog.open)return;
408
+ // A native dialog close event can arrive after a fast reopen. Restore the
409
+ // previous content synchronously so it is never orphaned by replaceChildren.
410
+ if(graphViewerContent)closeGraphViewer();
411
+ graphViewerContent=content;
412
+ graphViewerHome=content.parentNode;
413
+ graphViewerNext=content.nextSibling;
414
+ graphViewerWasHidden=content.hidden;
415
+ content.hidden=false;
416
+ graphJelMeta.hidden=!isJel;
417
+ graphViewport.replaceChildren(content);
418
+ document.querySelector('#graph-dialog-title').textContent=title;
419
+ graphDialog.showModal();
420
+ graphViewport.scrollLeft=0;
421
+ graphViewport.scrollTop=0;
422
+ fitGraphViewer();
423
+ }
424
+ function closeGraphViewer(){
425
+ const content=graphViewerContent;
426
+ if(!content)return;
427
+ if(content===jelChart)jelRenderSequence++;
428
+ const svg=graphViewerSvg();
429
+ if(svg){svg.style.width='';svg.style.height='';svg.style.maxWidth='';}
430
+ const next=graphViewerNext?.parentNode===graphViewerHome?graphViewerNext:null;
431
+ graphViewerHome.insertBefore(content,next);
432
+ content.hidden=graphViewerWasHidden;
433
+ graphViewerContent=null;
434
+ graphViewerHome=null;
435
+ graphViewerNext=null;
436
+ graphJelMeta.hidden=true;
437
+ graphZoom=1;
438
+ graphZoomLevel.textContent='100%';
439
+ }
440
+ document.querySelector('#graph-maximize').addEventListener('click',()=>showGraphViewer(graphCanvas,graphTitle.textContent));
441
+ function dismissGraphViewer(){if(graphDialog.open)graphDialog.close();closeGraphViewer();}
442
+ graphDialog.addEventListener('close',()=>{if(!graphDialog.open)closeGraphViewer();});
443
+ graphDialog.addEventListener('cancel',event=>{event.preventDefault();dismissGraphViewer();});
444
+ document.querySelector('#graph-dialog-close').addEventListener('click',dismissGraphViewer);
445
+ document.querySelector('#graph-zoom-in').addEventListener('click',()=>setGraphZoom(graphZoom*1.25));
446
+ document.querySelector('#graph-zoom-out').addEventListener('click',()=>setGraphZoom(graphZoom/1.25));
447
+ document.querySelector('#graph-zoom-reset').addEventListener('click',fitGraphViewer);
448
+ graphViewport.addEventListener('wheel',event=>{if(!event.ctrlKey&&!event.metaKey)return;event.preventDefault();setGraphZoom(graphZoom*(event.deltaY<0?1.15:1/1.15));},{passive:false});
449
+ let graphDrag=null;
450
+ graphViewport.addEventListener('pointerdown',event=>{
451
+ if(event.target.closest('.drillable')||event.button!==0)return;
452
+ graphDrag={id:event.pointerId,x:event.clientX,y:event.clientY,left:graphViewport.scrollLeft,top:graphViewport.scrollTop};
453
+ graphViewport.setPointerCapture(event.pointerId);
454
+ });
455
+ graphViewport.addEventListener('pointermove',event=>{
456
+ if(!graphDrag||event.pointerId!==graphDrag.id)return;
457
+ graphViewport.scrollLeft=graphDrag.left-(event.clientX-graphDrag.x);
458
+ graphViewport.scrollTop=graphDrag.top-(event.clientY-graphDrag.y);
459
+ });
460
+ for(const eventName of ['pointerup','pointercancel','lostpointercapture'])graphViewport.addEventListener(eventName,()=>{graphDrag=null;});
367
461
  document.querySelector('#graph-back').addEventListener('click',()=>history.back());
368
462
  document.querySelector('#graph-forward').addEventListener('click',()=>history.forward());
369
463
  window.addEventListener('popstate',()=>{if(graphFromHash()){renderGraphNavigation();showView('graphs');}else if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/troubleshooter-qa')showView('qa');else showView('jobs');});
@@ -131,23 +131,22 @@ export const dashboardStyles = ` <style>
131
131
  .graph-navigation { display:flex; flex-wrap:wrap; align-items:center; gap:.5rem; margin-bottom:.7rem; }
132
132
  .graph-canvas .node.drillable { cursor:pointer; }
133
133
  .graph-canvas .node.drillable text, .graph-canvas .node.drillable tspan { fill:#2367b1; }
134
- .jel-dialog { width:min(1050px,96vw); max-height:90vh; padding:.8rem; border:1px solid var(--border); border-radius:.55rem; background:var(--surface); color:var(--text); }
135
- .jel-dialog::backdrop { background:#17202b99; }
136
- .jel-dialog-header { display:flex; justify-content:space-between; align-items:center; gap:1rem; padding:.2rem .3rem .6rem; }
137
134
  .jel-legend { display:flex; align-items:center; flex-wrap:wrap; gap:.5rem; padding:.1rem .3rem .6rem; font-size:.76rem; font-weight:700; }
138
135
  .jel-legend span { padding:.16rem .5rem; border-radius:.35rem; border:1px solid; }
139
136
  .jel-legend-failed { background:#fee2e2; border-color:#b91c1c!important; color:#991b1b; }
140
137
  .jel-legend-retry { background:#ede9fe; border-color:#7c3aed!important; color:#5b21b6; }
141
138
  .jel-legend-troubleshooter { background:#fef3c7; border-color:#b45309!important; color:#92400e; }
142
- .jel-chart { min-height:14rem; max-height:72vh; overflow:auto; padding:.8rem; border:1px solid var(--border); border-radius:.4rem; background:var(--surface2); }
143
- .jel-chart svg { display:block; min-width:100%; max-width:none; height:auto; }
144
139
  .jel-source { overflow:auto; white-space:pre; font:12px/1.5 ui-monospace,monospace; }
145
- .graph-dialog { width:96vw; height:94vh; max-width:none; max-height:none; padding:.7rem; border:1px solid var(--border); border-radius:.5rem; background:var(--surface); color:var(--text); }
140
+ .graph-dialog { box-sizing:border-box; width:98vw; height:96vh; height:96dvh; max-width:none; max-height:none; padding:.55rem; border:1px solid var(--border); border-radius:.5rem; background:var(--surface); color:var(--text); }
141
+ .graph-dialog[open] { display:flex; flex-direction:column; gap:.25rem; }
146
142
  .graph-dialog::backdrop { background:#17202b99; }
147
143
  .graph-dialog-header { display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:.7rem; padding:.3rem .5rem; }
148
- .graph-dialog-viewport { height:calc(94vh - 5rem); overflow:auto; cursor:grab; background:var(--surface2); border:1px solid var(--border); border-radius:.4rem; }
144
+ .graph-dialog-viewport { flex:1; min-height:0; min-width:0; overflow:auto; cursor:grab; background:var(--surface2); border:1px solid var(--border); border-radius:.4rem; }
145
+ .graph-jel-meta { display:grid; gap:.2rem; padding:.1rem .3rem .25rem; }
146
+ .graph-jel-meta[hidden] { display:none; }
147
+ .graph-jel-meta #jel-status { margin:0; font-size:.74rem; }
149
148
  .graph-dialog-viewport:active { cursor:grabbing; }
150
- .graph-dialog-viewport .graph-canvas { display:block; width:max-content; min-width:100%; min-height:100%; overflow:visible; }
149
+ .graph-dialog-viewport .graph-canvas { display:grid; width:max-content; min-width:100%; min-height:100%; overflow:visible; }
151
150
  .graph-canvas .node text { pointer-events:none; }
152
151
  .graph-source { margin:0; max-height:22rem; overflow:auto; padding:.7rem; border:1px solid var(--border); border-radius:.4rem; background:var(--surface2); color:var(--muted); font:.72rem/1.5 ui-monospace,SFMono-Regular,Menlo,monospace; white-space:pre; }
153
152
  .graph-source-details summary { cursor:pointer; color:var(--muted); font-size:.74rem; font-weight:700; }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.244",
3
+ "version": "2.0.246",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -63,16 +63,14 @@ configuration returns `technical_failure`; it must never be treated as
63
63
  `resolved` or `needs_user`. This direct escalation command is distinct from
64
64
  `task escalate`, which is the durable Troubleshooter/human-blocker transition.
65
65
 
66
- For human Preview/Review, use the **existing** Relay
67
- `review.interactive.begin/wait/ready/fail/abort` lifecycle. Relay provides the
68
- execution-bound invocation and decision contract and emits a provider-neutral
69
- `task.interactive_waiting` with `source.component: interactive-review`.
70
- Preview media compilation, delivery (for example Markcut to Neo Mobile),
71
- notifications, and UI are owned by the calling project/provider. Never invent
72
- an approval from a compile receipt or a preview handoff, never replace the
73
- exact event template with a provider-specific event, and never create an
74
- unnecessary separate Preview Provider framework. Consult the project's own
75
- Review/Preview contract for delivery and version binding.
66
+ Human Preview uses `review.interactive.begin/wait/ready/fail/abort` and the
67
+ canonical `task.interactive_waiting` contract. The provider owns media and
68
+ notifications; a delivery receipt is **not approval**. Never forge event
69
+ identity or create a separate Review Provider. For Shortcut Preview, invoke
70
+ the tool with the **original Task identity**, return `WAITING_REVIEW` after
71
+ Relay durably suspends it, then resume that Task after an authenticated
72
+ decision. Neo Preview commits the Run Git revision automatically; no separate
73
+ checkpoint CLI. See `contracts/event-contract.md` for details.
76
74
 
77
75
  ## 5. Manage services when needed
78
76
 
@@ -58,6 +58,8 @@ Job/Task/Execution source identity.
58
58
  Relay checks the pending invocation, persists RUNNING -> AWAITING_DECISION,
59
59
  clears the execution lease, and releases the Worker. This is a non-failure
60
60
  handoff and is not a Task completion or a Troubleshooter block.
61
+ For Shortcut modules, a host-wrapped `markcut.preview` call uses the **original Shortcut Task identity**, not a reviewer child. The module returns `WAITING_REVIEW` only after the host has durably transitioned that Task to `AWAITING_DECISION`. The foreground runner exits with waiting status, keeping the in-flight node as a durable replay fence. After an authenticated accepted decision, the lifecycle requeues that same Task; a new foreground `job run --id ... --mode shortcut` resumes that node with the real `reviewDecision` in its input. Nonhuman `WAITING_EVENT` receipts are a different mechanism.
62
+
61
63
  The Job stays ACTIVE; the Task does not requeue until a matching
62
64
  `task.interactive_decision` is durably accepted and the Task Graph selects
63
65
  `interactive.resume` -> QUEUED. Retries and daemon restarts must not create