agents-relay 2.0.234 → 2.0.236

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
@@ -91,21 +91,23 @@ EOF
91
91
  npx agents-relay job create --repo OWNER/REPO \
92
92
  --title "Objective" --objective-file job.md
93
93
 
94
- # The orchestrator decides the initial batch separately
94
+ # Create-only example: the orchestrator explicitly adds these Tasks.
95
+ # For normal autonomous execution, instead pass --initial-plan at creation
96
+ # and let the Planner choose the minimal Tasks; do not also create these manually.
95
97
  cat > task.md <<'EOF'
96
98
  # Work
97
99
 
98
100
  Implement this phase using the Job objective as context.
99
101
  EOF
100
- npx agents-relay task create --repo OWNER/REPO --id job-1 \
102
+ npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
101
103
  --task-id initial --output task-pr --input-file task.md
102
104
 
103
- npx agents-relay task create --repo OWNER/REPO --id job-1 \
105
+ npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
104
106
  --task-id child --output task-pr \
105
107
  --input "Implement the described child task and publish a terminal event."
106
108
 
107
- npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
108
- npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1
109
+ npx agents-relay reconcile --repo OWNER/REPO --id JOB_ID
110
+ npx agents-relay job show --id JOB_ID
109
111
  ~~~
110
112
 
111
113
  Task readiness is explicit: `DRAFT` means the durable task exists but is not executable yet; `QUEUED` means Relay may execute it now; `RUNNING` means worker execution has started. Tasks created with dependencies start `DRAFT` and become `QUEUED` when those dependencies succeed. A dependency-free task created with `--draft` stays held until `task update --queue`. After binding an interactive request, a running Task may enter `AWAITING_DECISION` and release its Worker. Approved or changes-requested decisions requeue the same Task; `BLOCKED` is reserved for Troubleshooter escalation. Ordinary `DRAFT` Tasks remain unstarted/dependency-held.
@@ -113,37 +115,41 @@ Task readiness is explicit: `DRAFT` means the durable task exists but is not exe
113
115
  Mutable draft/queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
114
116
 
115
117
  ~~~sh
116
- npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \
118
+ npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child \
117
119
  --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
118
120
  --capabilities model,chatgpt,browser-harness
119
121
 
120
122
  # Explicitly release a held DRAFT task
121
- npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child --queue
123
+ npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child --queue
122
124
  ~~~
123
125
 
124
126
  Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created Job is DRAFT, and creating executable work or starting the Planner activates it. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, and locally confirmed merge facts and is never persisted as lifecycle truth.
125
127
 
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
+
126
130
  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.
127
131
 
128
132
  The canonical Mermaid Graph Engine is the authoritative durable workflow decision path. Job/Task lifecycle transitions plus Review, Planner, Blocker/Unblock, and Troubleshooter orchestration branches are defined by the canonical workflow graphs and executed through the shared graph runtime. TypeScript supplies facts and primitive action/effect implementations; it must not duplicate those workflow branches as a second procedural state machine.
129
133
 
130
- Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
134
+ Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. SQLite owns Job metadata and objectives. Any display PR or historical PR marker is a compatibility/audit projection, not the source of lifecycle truth.
131
135
 
132
- Every Job is objective-driven. `job create` persists only the durable Job and never
133
- creates executable tasks. The caller can either create work directly with
136
+ Every Job is objective-driven. By default, `job create` persists only a DRAFT
137
+ Job; `--initial-plan` also initializes the first real Planner round and its
138
+ validated work. For a create-only Job, the caller can add Tasks directly with
134
139
  `task create` or invoke the Planner explicitly with `plan`. Direct
135
140
  orchestrator-created tasks are persisted directly and are not wrapped in a
136
141
  synthetic Plan. `agents-relay plan` works immediately on a zero-task DRAFT Job,
137
142
  activates it, persists a real `plan-N` planning round, and materializes validated
138
143
  `next_tasks`. Reconciliation does not invent the first round for an untouched
139
- zero-task DRAFT Job; once work starts, every Job automatically creates later
140
- Planner rounds until its latest Plan is satisfied.
144
+ zero-task DRAFT Job. Once work starts, Relay waits for all work/recovery Tasks
145
+ to terminate and triggers Final Review. Only a CHANGES_REQUIRED review verdict
146
+ can start the next Planner round; PASS proceeds to the local merge gate.
141
147
 
142
148
  Manual planning syntax:
143
149
 
144
150
  ~~~sh
145
- npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt "Plan the implementation from the durable objective"
146
- npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt-file guidance.md
151
+ npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt "Plan the implementation from the durable objective"
152
+ npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt-file guidance.md
147
153
  ~~~
148
154
 
149
155
  The optional prompt is additional round guidance; it does not replace the durable Job objective. New planning rounds use `plan-N`; historical `planner-N` records remain readable.
@@ -167,7 +173,7 @@ Use `job update` for partial mutable metadata changes on an already healthy Job
167
173
  npx agents-relay job update --id JOB_ID --priority P0 --no-auto-merge
168
174
  ~~~
169
175
 
170
- Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --pr NUMBER --id JOB_ID`.
176
+ Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --id JOB_ID`.
171
177
  Pass optional `--thread-id THREAD_ID` to persist a reviewer-thread override for subsequent
172
178
  review routing. Without it, Relay uses the stored reviewer thread, then creator thread,
173
179
  or the legacy review path when neither exists. This request wakes graph-owned
@@ -190,7 +196,7 @@ Managed GitHub task create/update/show/list/retry/cancel and reconcile/serve com
190
196
  The original init command remains supported for backward compatibility:
191
197
 
192
198
  ~~~sh
193
- npx agents-relay init --repo OWNER/REPO --pr 1 --id job-1 --title "Objective"
199
+ npx agents-relay init --repo OWNER/REPO --pr 1 --id JOB_ID --title "Objective"
194
200
  ~~~
195
201
 
196
202
  ## npm publishing
@@ -275,7 +281,7 @@ Relay does not discover Skill directories or invoke a separate runtime.
275
281
  The ChatGPT adapter uses Relay's `agents/chatgpt-worker.agent.md` lifecycle contract. A new worker uses `webhelm platform run chatgpt new-thread --session-id SESSION_ID --config <file>` in a caller-owned Session. This is a regular persistent ChatGPT thread, which supports the connected Neo MCP in the verified account. Relay closes the Session after submission, but the ChatGPT thread remains in history. Existing-thread review and handoff continue through `new-turn`. File paths are included in the worker message for Neo MCP reading; they are not uploaded as browser attachments. Submission receipts retain `status: submitted`; the event bus owns task completion.
276
282
 
277
283
  ~~~sh
278
- npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
284
+ npx agents-relay task create --repo OWNER/REPO --pr 5 --id JOB_ID \
279
285
  --task-id research-ui --adapter chatgpt \
280
286
  --capabilities model,chatgpt,browser-harness \
281
287
  --provider openai --model MODEL \
@@ -283,13 +289,13 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
283
289
  --input "Research the dashboard UX and write the final report to the declared output file."
284
290
  ~~~
285
291
 
286
- GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows PR state, durable Job lifecycle, and derived runtime status separately. A merged PR reconciles lifecycle to `COMPLETED`; a closed, unmerged PR reconciles lifecycle to `CANCELLED`.
292
+ SQLite and the canonical Graphs are authoritative for terminal lifecycle. A remote PR merge/close is an audit observation, not a state transition. Final Review PASS authorizes local Git merge; confirmed local-merge evidence gates `COMPLETED`. The dashboard exposes `/api/jobs` and distinguishes durable Job lifecycle from derived runtime status. Shortcut execution is shown separately from managed queue execution: an externally triggered Shortcut is WAITING until its foreground runner starts, then RUNNING, and never shows MERGE_PENDING solely because its content-only Task completed. The Shortcut badge and selected Job details expose execution mode and graph-node progress. For model-backed Shortcut nodes, the same caller-configured `--shared-root` (or `AGENTS_RELAY_SHARED_ROOT`) must be supplied to child Worker execution context, not just Shortcut discovery.
287
293
 
288
294
  Relay has no orchestrator worker adapter for new work. Orchestrators are external clients that create/plan durable Tasks; Execution Router selects a real worker route (`codex` or `chatgpt`). The CLI and dashboard do not expose manual orchestrator-only `task start`, `task complete`, or synthetic `record` paths.
289
295
 
290
296
  Historical stores may still contain `adapter: orchestrator`. Reconciliation treats that value only as legacy migration evidence: QUEUED work that never started can be converted in place to normal worker requirements; RUNNING work with an unknown outcome is quarantined as BLOCKED instead of replayed; only explicit durable `externalCompletionVerified` evidence can complete legacy work without execution. New Task creation and Task update reject that adapter.
291
297
 
292
- For managed jobs, the GitHub PR body is the canonical collaboration surface while SQLite remains lifecycle authority.
298
+ For managed Jobs, SQLite is the canonical collaboration and lifecycle record; an optional GitHub display PR carries audit information only.
293
299
 
294
300
  ### Automatic task troubleshooting
295
301
 
package/dist/cli-help.js CHANGED
@@ -43,9 +43,9 @@ Actions:
43
43
  run Opt in to direct Agent Graph shortcuts for one existing Task
44
44
  shortcut-receipt Atomically record a validated nonhuman result for a persisted wait
45
45
  list List managed Jobs in a repository
46
- merge Queue a retryable external PR merge; Graph completes the Job only after confirmation
46
+ merge Legacy entry point; local Git merge is Graph-owned (no CLI PR merge)
47
47
  unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
48
- cancel Close the backing PR and cancel the Job
48
+ cancel Cancel the Job through the SQLite/Graph lifecycle (no PR required)
49
49
  pause Persistently stop dispatch and interrupt active generations; lifecycle state remains unchanged
50
50
  resume Clear pause metadata and requeue interrupted work
51
51
 
package/dist/cli.js CHANGED
@@ -541,7 +541,7 @@ export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegist
541
541
  const modelRuntime = arg(args, '--codex', 'codex');
542
542
  const policy = chatGptTabClosePolicy(args);
543
543
  const planner = runtimePlanner(args);
544
- return new Reconciler(store, { shortcutRunnerOwner, noGitHub: noGitHubMode(args), owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy }), new ZAdapter()], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(args), eventBus: bus, emit, chatgptTabClosePolicy: policy, executionContextRoots: { workspaceRoot: arg(args, '--workspace-root') || process.env.AGENTS_RELAY_WORKSPACE_ROOT }, projectPathForJob: async (job, task) => {
544
+ return new Reconciler(store, { shortcutRunnerOwner, noGitHub: noGitHubMode(args), owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy }), new ZAdapter()], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(args), eventBus: bus, emit, chatgptTabClosePolicy: policy, executionContextRoots: { workspaceRoot: arg(args, '--workspace-root') || process.env.AGENTS_RELAY_WORKSPACE_ROOT, sharedRoot: arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined, globalRoot: arg(args, '--global-root') || process.env.AGENTS_HOME || undefined }, projectPathForJob: async (job, task) => {
545
545
  const workspaceRoot = await resolveWorkspaceRoot(arg(args, '--workspace-root') || undefined);
546
546
  const canonical = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : job.repository, arg(args, '--project-path'), workspaceRoot);
547
547
  if (!(task ? taskRequiresManagedWorktree(job, task) : Boolean(job.localMerge?.sourceRef)))
@@ -208,7 +208,7 @@ function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.pa
208
208
  function safePrUrl(repository,prNumber){if(typeof repository!=='string'||!Number.isInteger(prNumber)||prNumber<=0)return null;const parts=repository.split('/');if(parts.length!==2)return null;const [owner,repo]=parts;if(!owner||!repo||owner==='.'||owner==='..'||repo==='.'||repo==='..')return null;if(!/^[A-Za-z0-9-]+$/.test(owner)||!/^[A-Za-z0-9._-]+$/.test(repo))return null;return 'https://github.com/'+owner+'/'+repo+'/pull/'+prNumber;}
209
209
  function safeCommitUrl(repository,sha){if(typeof repository!=='string'||typeof sha!=='string'||!/^[0-9a-f]{7,64}$/i.test(sha))return null;const parts=repository.split('/');if(parts.length!==2||!parts[0]||!parts[1])return null;return 'https://github.com/'+parts[0]+'/'+parts[1]+'/commit/'+sha;}
210
210
  function commitField(label,job,sha){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)));const line=element('p','detail-value');const url=safeCommitUrl(job?.repository,sha);if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent=sha.slice(0,7);line.append(link);}else line.append(text(sha||'—'));box.append(line);return box;}
211
- function prField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('GitHub PR')));const line=element('p','detail-value');const prNumber=Number(job.prNumber||0);const url=safePrUrl(job.repository,prNumber);if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='PR #'+prNumber;line.append(link);}else line.append(text('unavailable'));box.append(line);return box;}
211
+ function prField(job){if(job.executionMode==='shortcut')return field('GitHub PR','Not applicable');const box=element('div','detail-group');box.append(element('p','detail-label',text('GitHub PR')));const line=element('p','detail-value');const prNumber=Number(job.prNumber||0);const url=safePrUrl(job.repository,prNumber);if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='PR #'+prNumber;line.append(link);}else line.append(text('unavailable'));box.append(line);return box;}
212
212
  function safeWorkerThreadUrl(input,adapter){try{const url=new URL(input);const parts=url.pathname.split('/');const domain=adapter==='z'?'chat.z.ai':'chatgpt.com';if(url.protocol!=='https:'||url.hostname!==domain||parts.length!==3||parts[1]!=='c'||!/^[A-Za-z0-9_-]{8,160}$/.test(parts[2]))return null;return url.origin+url.pathname;}catch{return null;}}
213
213
  function chatField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('Worker threads')));const items=Array.isArray(task.threadHistory)?task.threadHistory.slice(-8).reverse():[];if(items.length===0)items.push({threadUrl:task.threadUrl,attempt:task.attempt});let shown=0;for(const item of items){const url=safeWorkerThreadUrl(item.threadUrl,task.adapter);if(!url)continue;const line=element('p','detail-value');const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='Open '+(task.adapter==='z'?'Z.ai':'ChatGPT')+' thread'+(Number.isInteger(item.attempt)?' · attempt '+item.attempt:'');line.append(link);box.append(line);shown++;}if(!shown){const line=element('p','detail-value');if(task.adapter==='chatgpt'&&typeof task.threadId==='string'){const url=safeWorkerThreadUrl('https://chatgpt.com/c/'+encodeURIComponent(task.threadId),'chatgpt');if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='Open ChatGPT thread';line.append(link);shown++;}}if(!shown)line.append(text('—'));box.append(line);}return box;}
214
214
  function taskCommentField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('PR comment')));const line=element('p','detail-value');if(typeof task.taskUrl==='string'&&task.taskUrl.startsWith('https://github.com/')){const link=document.createElement('a');link.className='task-link';link.href=task.taskUrl;link.target='_blank';link.rel='noopener noreferrer';link.textContent='Open task comment';line.append(link);}else line.append(text('—'));box.append(line);return box;}
@@ -244,7 +244,8 @@ function jobChatRef(job){const pr=Number(job?.prNumber||0);return repoName(job?.
244
244
  function chatShortcutUrl(prompt){return 'https://chatgpt.com/?prompt='+encodeURIComponent(prompt);}
245
245
  const CHAT_SHORTCUT_TARGET='agents-relay-shortcut';
246
246
  function chatShortcutField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('ChatGPT shortcut')));const select=document.createElement('select');select.className='job-filter job-chat-shortcut-select';select.setAttribute('aria-label','ChatGPT shortcut');select.append(new Option('',''));for(const item of parseChatShortcuts(chatShortcutText()))select.append(new Option(item.name,item.prompt));select.value='';select.addEventListener('change',()=>{if(!select.value)return;const prompt=select.value.replaceAll('%1',jobChatRef(job));window.open(chatShortcutUrl(prompt),CHAT_SHORTCUT_TARGET,'noopener');select.value='';});box.append(select);return box;}
247
- 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))),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));}}
247
+ 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');}
248
+ 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));}}
248
249
  function taskTagDisplay(job,task){const display=task.tag&&job?.tag?.values?.[task.tag];return typeof display==='string'&&display?display:null;}
249
250
  function taskVerdict(job,task){if(task.state!=="SUCCEEDED")return null;const data=task.result?.data||{};if(["reviewer","job-acceptance-reviewer"].includes(task.agentName)){const verdict=data.verdict||((job?.review?.taskId===task.id)?job.review.outcome:null);return ({approved:"APPROVED",pass:"APPROVED","changes-required":"CHANGES REQUIRED",changes_required:"CHANGES REQUIRED"})[verdict]||null;}if(task.agentName==="troubleshooter"){const original=job?.tasks?.find(t=>t.id===task.parentTaskId);const resolution=original?.resolution;if(resolution?.state!=="resolved"||resolution.owner!=="troubleshooter")return null;return ({exact_original_retry:"RETRY VERIFIED",same_job_dependency:"DEPENDENCY REGISTERED",blocker_job_dependency:"BLOCKER REGISTERED",cancel_supersede:"SUPERSEDED"})[resolution.path]||null;}return null;}function taskSubtreeComplete(task,children){return ['SUCCEEDED','CANCELLED'].includes(task.state)&&(children.get(task.id)||[]).every(child=>taskSubtreeComplete(child,children));}
250
251
  function taskStateLabel(task){const resolution=task?.resolution?.state;return task?.state==='FAILED'&&typeof resolution==='string'&&resolution.trim()?task.state+' / '+resolution:task.state;}
@@ -260,7 +261,7 @@ function taskStateField(task){const box=element('div','detail-group');box.append
260
261
  function manualOverrideField(task){const rows=Array.isArray(task.manualStateOverrides)?task.manualStateOverrides:[];const last=rows.at(-1);return field('Manual override',last?last.from+' → '+last.to+' · '+relativeTime(last.at):'—');}
261
262
  function iconSvg(name){const paths={close:'M5 5l14 14M19 5 5 19',detail:'M7 3h7l4 4v14H7zM14 3v5h4M10 12h5m-5 4h5'};const ns='http://www.w3.org/2000/svg';const svg=document.createElementNS(ns,'svg');svg.setAttribute('viewBox','0 0 24 24');svg.setAttribute('aria-hidden','true');const path=document.createElementNS(ns,'path');path.setAttribute('d',paths[name]);svg.append(path);return svg;}
262
263
  function showDetailsDialog(title,sections){const dialog=element('dialog','details-dialog');dialog.setAttribute('aria-label',title);const head=element('div','details-dialog-head');const name=element('strong','',text(title));const close=element('button','icon-button');close.append(iconSvg('close'));close.type='button';close.setAttribute('aria-label','Close details');close.title='Close details';close.addEventListener('click',()=>dialog.close());head.append(name,close);dialog.append(head);for(const [label,value] of sections){if(value===undefined||value===null||value==='')continue;dialog.append(element('h3','',text(label)));const content=element('pre');content.textContent=typeof value==='string'?value:JSON.stringify(value,null,2);dialog.append(content);}dialog.addEventListener('close',()=>dialog.remove());document.body.append(dialog);dialog.showModal();}function openJobDetails(){const job=selected();if(!job)return;showDetailsDialog('Job '+job.id+' · '+value(job.title),[['Objective',job.objective],['Description',job.description],['State',job.state],['Plans',job.plans?.map(p=>({id:p.id,status:p.status,assessment:p.assessment,error:p.error,generatedTaskIds:p.generatedTaskIds}))],['Review',job.review],['Outcome',job.result],['Publication',job.publication],['Failure',job.error]]);}function openTaskDetails(task){const result=task.result?.data??task.result;showDetailsDialog('Task '+task.id+' · '+value(task.title),[['Input / task objective',task.input],['State',task.state],['Conclusion',result],['Result summary',task.result?.summary],['Planner assessment',task.plannerResult?.assessment],['Resolution',task.resolution],['Resolution classification',task.resolutionClassification],['Failure',task.failureReason||task.error],['Dependencies',task.dependencies]]);}document.querySelector('#job-content-open').addEventListener('click',openJobDetails);function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Title',task.title||'—'),field('Task ID',task.id),field('Kind',task.kind||'work'),taskStateField(task),...(task.state==='FAILED'&&task.resolution?.state?[field('Resolution state',task.resolution.state),field('Resolution path',task.resolution.path||'—'),field('Resolution target',task.resolution.targetTaskId||'—')]:[]),manualOverrideField(task),field('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),...(task.resolutionClassification?[field('Resolution classification',task.resolutionClassification.kind),field('Resolution target',task.resolutionClassification.targetTaskId),field('Resolution evidence',task.resolutionClassification.evidence),field('Resolution reason',task.resolutionClassification.reason)]:[]),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),taskCommentField(task),chatField(task));const job=selected();if(task.reviewHeadSha&&job)groups.append(commitField('HEAD commit',job,task.reviewHeadSha));const graph=agentGraphField(task);if(graph)groups.append(graph);if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));const result=task.result?.data??task.result;if(result){groups.append(field('Conclusion',result.verdict||result.outcome?.verdict||task.result?.summary||'Available'));}taskDetailRoot.append(groups);const details=element('button','icon-button');details.append(iconSvg('detail'));details.type='button';details.setAttribute('aria-label','Task details and conclusion');details.title='Task details and conclusion';details.addEventListener('click',()=>openTaskDetails(task));taskDetailRoot.append(details);}
263
- function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>['reviewer','job-acceptance-reviewer'].includes(task.agentName)&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobContentButton.disabled=true;jobContentButton.dataset.state='IDLE';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent=value(job.title||job.id);jobContentButton.disabled=false;jobContentButton.dataset.state=JOB_STATES.includes(job.state)?job.state:'IDLE';jobContentButton.setAttribute('aria-label','Job details · '+value(job.state));jobContentButton.title='Job details · '+value(job.state);if(jobSelectionKey(job)!==selectedJob){selectedJob=jobSelectionKey(job);selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('PR state',job.githubState||'UNKNOWN'),jobStateField(job),field('Runtime status',job.runtimeStatus||'IDLE'),field('Review',reviewStatus(job)),field('Creator thread',job.creatorThreadId||'—'),threadField('Implementation thread',job.implementationThreadId),threadField('Reviewer thread',job.reviewerThreadId),commitField('Review head SHA',job,job.review?.headSha||job.headSha||''),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)),chatShortcutField(job));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();syncMobileJobsView();}
264
+ function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>['reviewer','job-acceptance-reviewer'].includes(task.agentName)&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobContentButton.disabled=true;jobContentButton.dataset.state='IDLE';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent=value(job.title||job.id);jobContentButton.disabled=false;jobContentButton.dataset.state=JOB_STATES.includes(job.state)?job.state:'IDLE';jobContentButton.setAttribute('aria-label','Job details · '+value(job.state));jobContentButton.title='Job details · '+value(job.state);if(jobSelectionKey(job)!==selectedJob){selectedJob=jobSelectionKey(job);selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('PR state',job.executionMode==='shortcut'?'Not applicable':job.githubState||'UNKNOWN'),jobStateField(job),field('Runtime status',job.runtimeStatus||'IDLE'),field('Execution mode',job.executionMode==='shortcut'?'Shortcut Runner (external trigger)':'Managed'),...(job.executionMode==='shortcut'?[field('Shortcut nodes',shortcutProgress(job))]:[]),field('Review',job.executionMode==='shortcut'?'Not required':reviewStatus(job)),field('Creator thread',job.creatorThreadId||'—'),threadField('Implementation thread',job.implementationThreadId),threadField('Reviewer thread',job.reviewerThreadId),commitField('Review head SHA',job,job.review?.headSha||job.headSha||''),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)),chatShortcutField(job));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();syncMobileJobsView();}
264
265
  function isCompleteUnmerged(job){return job.runtimeStatus==='MERGE_PENDING';}
265
266
  function compareJobs(a,b){const lifecycleGroup=job=>job.state==='COMPLETED'||job.state==='CANCELLED'?1:0;const timestamp=job=>{const updated=Date.parse(job.updatedAt||'');if(Number.isFinite(updated))return updated;const created=Date.parse(job.createdAt||'');return Number.isFinite(created)?created:0;};return lifecycleGroup(a)-lifecycleGroup(b)||timestamp(b)-timestamp(a)||String(a.repository||'').localeCompare(String(b.repository||''))||String(a.id||'').localeCompare(String(b.id||''));}
266
267
  async function loadJSON(url){const response=await fetch(url);if(!response.ok)throw new Error(response.status+' '+response.statusText);return response.json();}
@@ -368,12 +369,13 @@ window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){ev
368
369
  function parseMessage(message){try{return JSON.parse(message.data);}catch{return null;}}
369
370
  function isFreshEnough(incoming,current){const a=Date.parse(incoming||''),b=Date.parse(current||'');return !Number.isFinite(b)||!Number.isFinite(a)||a>=b;}
370
371
  function applyStatePatch(patch){if(!patch?.jobId)return false;const job=jobs.find(candidate=>candidate.id===patch.jobId);if(!job)return false;if(patch.jobState&&isFreshEnough(patch.jobUpdatedAt,job.updatedAt)){job['state']=patch.jobState;if(patch.jobUpdatedAt)job.updatedAt=patch.jobUpdatedAt;}if(patch.taskId&&patch.taskState){const task=(job.tasks||[]).find(candidate=>candidate.id===patch.taskId);if(task&&isFreshEnough(patch.taskUpdatedAt,task.updatedAt)){task['state']=patch.taskState;if(patch.taskUpdatedAt)task.updatedAt=patch.taskUpdatedAt;}}return true;}
372
+ async function refreshJobSnapshot(jobId){const known=jobs.find(job=>job.id===jobId);if(!known)return;try{const params=new URLSearchParams({id:known.id,repo:known.repository,pr:String(known.prNumber||0)});const latest=await loadJSON('/api/job?'+params);upsertFreshJob(latest);renderAll();}catch{/* The current stream and next manual refresh remain available. */}}
371
373
  function upsertFreshJob(incoming){if(!incoming)return;const index=jobs.findIndex(job=>jobSelectionKey(job)===jobSelectionKey(incoming));if(index<0){jobs.push(incoming);return;}if(isFreshEnough(incoming.updatedAt,jobs[index].updatedAt))jobs[index]={...incoming,prNumber:Number(incoming.prNumber||0)>0?incoming.prNumber:jobs[index].prNumber};}
372
374
  const stream=new EventSource('/events');
373
375
  stream.onopen=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream connected');connection.className='status-pill ok';};
374
376
  stream.onerror=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream reconnecting');connection.className='status-pill warn';};
375
377
  stream.onmessage=message=>{const payload=parseMessage(message);if(payload?.job){upsertFreshJob(payload.job);renderAll();void drawRuntimeSummary();}};
376
- stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.job)upsertFreshJob(payload.job);else if(payload?.statePatch)applyStatePatch(payload.statePatch);if(payload?.event)addEvent(payload.event);renderAll();void drawRuntimeSummary();});
378
+ stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.job)upsertFreshJob(payload.job);else if(payload?.statePatch)applyStatePatch(payload.statePatch);if(payload?.statePatch)void refreshJobSnapshot(payload.statePatch.jobId);if(payload?.event)addEvent(payload.event);renderAll();void drawRuntimeSummary();});
377
379
  if(location.hash==='#/usage')showView('usage');else if(graphFromHash())showView('graphs');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else if(location.hash==='#/troubleshooter-qa')showView('qa');else showView('jobs');void refresh(false);
378
380
  setInterval(()=>{if(location.hash==='#/usage')void drawUsage();},30000);
379
381
  setInterval(()=>void refreshVersion(),30000);
@@ -81,6 +81,7 @@ export const dashboardStyles = ` <style>
81
81
  .status-pill.bad,.badge.FAILED { background:#ffe8e8; color:var(--bad); }
82
82
  .status-pill.neutral,.badge.IDLE,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
83
83
  .badge.DRAFT { background:#eef2ff; color:#3f51b5; }
84
+ .badge.shortcut-mode { background:var(--accent2); color:var(--accent); border:1px solid var(--accent); }
84
85
  .badge.MERGE_PENDING { background:#ffe3a3; color:#7a4a00; }
85
86
  .details-dialog { width:min(850px,calc(100vw - 2rem)); max-height:85vh; overflow:auto; border:1px solid var(--border); border-radius:.6rem; background:var(--surface); color:var(--text); box-shadow:0 18px 55px #0004; padding:1rem; } .details-dialog::backdrop { background:#17202b99; } .details-dialog-head { display:flex; justify-content:space-between; align-items:center; gap:1rem; position:sticky; top:-1rem; background:var(--surface); padding:.5rem 0; } .details-dialog pre { white-space:pre-wrap; overflow-wrap:anywhere; background:var(--surface2); padding:.7rem; border-radius:.4rem; } .details-dialog h3 { font-size:.8rem; margin:1rem 0 .3rem; }
86
87
  .job-summary,.detail-groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:.55rem; }
@@ -36,6 +36,21 @@ export function deriveJobRuntimeStatus(job, _prState = 'OPEN') {
36
36
  return 'COMPLETED';
37
37
  if (job.state === 'DRAFT')
38
38
  return 'IDLE';
39
+ // A Shortcut Job is owned by an external foreground runner, not the Relay
40
+ // scheduler queue. Do not advertise a not-yet-invoked Shortcut as QUEUED,
41
+ // or a content-only Shortcut as pending a PR merge/review.
42
+ if (job.executionMode === 'shortcut' && job.contentOnly === true) {
43
+ const children = job.tasks.filter(task => task.parentTaskId !== null);
44
+ if (children.some(task => task.state === 'BLOCKED') && !children.some(task => task.state === 'RUNNING'))
45
+ return 'BLOCKED';
46
+ if (children.some(task => task.state === 'FAILED') && !children.some(task => task.state === 'RUNNING'))
47
+ return 'FAILED';
48
+ if (job.tasks.some(task => task.state === 'AWAITING_DECISION'))
49
+ return 'WAITING';
50
+ if (job.tasks.some(task => task.state === 'RUNNING'))
51
+ return 'RUNNING';
52
+ return 'WAITING'; // External Shortcut Runner has not started or needs a resume.
53
+ }
39
54
  const currentPlan = job.plans?.at(-1);
40
55
  // An unresolved planner failure is a Job failure, not an idle Job.
41
56
  // Active task execution still takes precedence below.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.234",
3
+ "version": "2.0.236",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",