agents-relay 2.0.210 → 2.0.212

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
@@ -87,7 +87,7 @@ npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
87
87
  npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1
88
88
  ~~~
89
89
 
90
- 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`. Once a task has run, external waiting is represented as `BLOCKED`, never by returning to `DRAFT`.
90
+ 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.
91
91
 
92
92
  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:
93
93
 
@@ -203,7 +203,7 @@ function shortManagedId(id,repository,kind){const parts=String(repository||'').s
203
203
  function jobForSelection(selection){return jobs.find(job=>jobSelectionKey(job)===selection)||jobs.find(job=>job.id===selection)||null;}
204
204
  function selected(){return jobForSelection(selectedJob)||jobs[0]||null;}
205
205
  function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
206
- function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','DRAFT','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
206
+ function compactCounts(input){const order=['RUNNING','AWAITING_DECISION','BLOCKED','FAILED','QUEUED','DRAFT','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
207
207
  function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.parse(timestamp);if(!Number.isFinite(parsed))return value(timestamp);const seconds=Math.max(0,Math.round((Date.now()-parsed)/1000));if(seconds<60)return 'just now';if(seconds<3600)return Math.floor(seconds/60)+'m ago';if(seconds<86400)return Math.floor(seconds/3600)+'h ago';return Math.floor(seconds/86400)+'d ago';}
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;}
@@ -254,7 +254,7 @@ function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Nu
254
254
  const JOB_STATES=['DRAFT','ACTIVE','COMPLETED','CANCELLED'];
255
255
  async function setJobState(job,state,select){if(!job||state===job.state)return;select.disabled=true;try{const params=new URLSearchParams({id:job.id,state,repo:job.repository,pr:String(job.prNumber)});const response=await fetch('/api/job-state?'+params.toString(),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>jobSelectionKey(candidate)===jobSelectionKey(job));if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){select.title='Set job lifecycle state: '+error.message;select.value=job.state;}finally{select.disabled=false;}}
256
256
  function jobStateField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('Lifecycle state')));const select=document.createElement('select');select.className='job-filter job-state-select';select.dataset.state=job.state;select.setAttribute('aria-label','Job lifecycle state');for(const state of JOB_STATES)select.append(new Option(state,state));select.value=job.state;select.addEventListener('change',()=>void setJobState(job,select.value,select));box.append(select);return box;}
257
- const TASK_STATES=['DRAFT','QUEUED','RUNNING','BLOCKED','SUCCEEDED','FAILED','CANCELLED'];
257
+ const TASK_STATES=['DRAFT','QUEUED','RUNNING','AWAITING_DECISION','BLOCKED','SUCCEEDED','FAILED','CANCELLED'];
258
258
  async function setTaskState(task,state,select){const job=selected();if(!job||state===task.state)return;select.disabled=true;try{const params=new URLSearchParams({id:job.id,task:task.id,state,repo:job.repository,pr:String(job.prNumber)});const response=await fetch('/api/task-state?'+params.toString(),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>jobSelectionKey(candidate)===jobSelectionKey(job));if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){select.title='Set task state: '+error.message;select.value=task.state;}finally{select.disabled=false;}}
259
259
  function taskStateField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('State')));const select=document.createElement('select');select.className='job-filter task-state-select';select.setAttribute('aria-label','Task state');for(const state of TASK_STATES)select.append(new Option(state,state));select.value=task.state;select.addEventListener('change',()=>void setTaskState(task,select.value,select));box.append(select);return box;}
260
260
  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):'—');}
@@ -77,7 +77,7 @@ export const dashboardStyles = ` <style>
77
77
  .job-status-line .badge { flex:0 0 auto; }
78
78
  .status-pill,.badge { display:inline-flex; align-items:center; border-radius:999px; padding:.06rem .42rem; min-height:1.35rem; font-size:.68rem; font-weight:800; }
79
79
  .status-pill.ok,.badge.ACTIVE,.badge.RUNNING,.badge.SUCCEEDED,.badge.COMPLETED,.badge.MERGED { background:#e5f3e9; color:var(--ok); }
80
- .status-pill.warn,.badge.BLOCKED,.badge.DRAFT,.badge.QUEUED,.badge.WAITING,.badge.OPEN { background:#fff1d2; color:var(--warn); }
80
+ .status-pill.warn,.badge.BLOCKED,.badge.DRAFT,.badge.QUEUED,.badge.WAITING,.badge.AWAITING_DECISION,.badge.OPEN { background:#fff1d2; color:var(--warn); }
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; }
package/dist/dashboard.js CHANGED
@@ -374,7 +374,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
374
374
  const repository = url.searchParams.get('repo') ?? undefined;
375
375
  const parsedPr = Number(url.searchParams.get('pr'));
376
376
  const prNumber = Number.isInteger(parsedPr) && parsedPr > 0 ? parsedPr : undefined;
377
- const validState = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'].includes(requestedState);
377
+ const validState = ['DRAFT', 'QUEUED', 'RUNNING', 'AWAITING_DECISION', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'].includes(requestedState);
378
378
  if (req.method !== 'POST' || !/^[A-Za-z0-9_.-]+$/.test(requestedJobId) || !isTaskId(requestedTaskId) || !validState || !resolvedActions?.taskSetState) {
379
379
  res.writeHead(404);
380
380
  res.end('Task state override unavailable');
@@ -1,3 +1,4 @@
1
+ import { eventOnlyReviewEligible } from './interactive-invocation.js';
1
2
  export const hostInvocationTablesSql = `
2
3
  CREATE TABLE IF NOT EXISTS host_invocation_event (
3
4
  job_id TEXT NOT NULL,
@@ -51,9 +52,21 @@ export function recordHostInvocationDecision(db, delivery, fingerprint, writeSna
51
52
  const job = snapshot?.json ? JSON.parse(snapshot.json) : null;
52
53
  const task = job?.tasks.find(item => item.id === delivery.taskId);
53
54
  const invocation = task?.interactiveInvocation;
54
- if (!job || !task || !invocation || !(['RUNNING', 'DRAFT'].includes(task.state)) || invocation.executionId !== delivery.executionId ||
55
- (task.executionId !== delivery.executionId && task.state !== 'DRAFT') ||
56
- invocation.status !== 'awaiting_decision' || invocation.invocationId !== delivery.invocationId || invocation.revision !== delivery.revision) {
55
+ const bound = invocation && ['RUNNING', 'AWAITING_DECISION'].includes(task?.state ?? '') &&
56
+ invocation.executionId === delivery.executionId &&
57
+ (task?.executionId === delivery.executionId || task?.state === 'AWAITING_DECISION') &&
58
+ invocation.status === 'awaiting_decision' && invocation.invocationId === delivery.invocationId &&
59
+ invocation.revision === delivery.revision;
60
+ // Event-only reviews are claims against an ACTIVE execution, not permission to
61
+ // release an arbitrary waiting/failed/cancelled Task or replay an older revision.
62
+ const active = job?.state === 'ACTIVE' && task?.state === 'RUNNING' &&
63
+ task.executionId === delivery.executionId && eventOnlyReviewEligible(delivery);
64
+ const seen = db.prepare('SELECT 1 FROM host_invocation_decision WHERE job_id=? AND task_id=? AND execution_id=? AND revision=?')
65
+ .get(delivery.jobId, delivery.taskId, delivery.executionId, delivery.revision);
66
+ const eventOnly = active && !seen && (!invocation ||
67
+ (invocation.status === 'changes_requested' && invocation.executionId === delivery.executionId &&
68
+ invocation.revision !== delivery.revision));
69
+ if (!job || !task || job.state !== 'ACTIVE' || (!bound && !eventOnly)) {
57
70
  recordHostInvocationEvent(db, delivery, 'stale', fingerprint);
58
71
  db.exec('COMMIT');
59
72
  return { outcome: 'stale', reason: 'invocation_or_revision_mismatch' };
@@ -65,7 +78,8 @@ export function recordHostInvocationDecision(db, delivery, fingerprint, writeSna
65
78
  const decidedInvocation = {
66
79
  invocationId: delivery.invocationId, revision: delivery.revision, executionId: delivery.executionId,
67
80
  status: delivery.decision === 'approved' ? 'approved' : 'changes_requested',
68
- boundAt: invocation.boundAt, decidedAt: delivery.deliveredAt, feedback: delivery.feedback,
81
+ boundAt: bound ? invocation.boundAt : delivery.deliveredAt, decidedAt: delivery.deliveredAt,
82
+ feedback: delivery.feedback, comments: delivery.comments, idempotencyKey: delivery.idempotencyKey,
69
83
  };
70
84
  task.interactiveInvocation = decidedInvocation;
71
85
  const candidate = Date.parse(delivery.deliveredAt);
@@ -9,6 +9,8 @@ export const interactiveInvocationGraph = new GraphRuntime(graphSource, {
9
9
  currentInvocation: facts => facts.durableFacts.currentInvocation === true,
10
10
  awaitingDecision: facts => facts.durableFacts.awaitingDecision === true,
11
11
  currentRevision: facts => facts.durableFacts.currentRevision === true,
12
+ eventOnlyCurrentExecution: facts => facts.durableFacts.eventOnlyCurrentExecution === true,
13
+ eventOnlyNextRevision: facts => facts.durableFacts.eventOnlyNextRevision === true,
12
14
  duplicateDelivery: facts => facts.durableFacts.duplicateDelivery === true,
13
15
  changesRequested: facts => facts.durableFacts.changesRequested === true,
14
16
  },
@@ -50,10 +52,26 @@ export function normalizeInteractiveDecision(event) {
50
52
  const decision = value.decision === 'approved' || value.decision === 'changes_requested' ? value.decision : null;
51
53
  if (!jobId || !taskId || !executionId || !invocationId || !revision || !decision)
52
54
  return null;
53
- const feedback = string('feedback');
55
+ if (event.source?.id !== `job/${jobId}/task/${taskId}/execution/${executionId}`)
56
+ return null;
57
+ if (value.contentHash !== undefined && typeof value.feedback !== 'string')
58
+ return null;
59
+ const feedback = typeof value.feedback === 'string' ? value.feedback : null;
60
+ const contentHash = string('contentHash');
61
+ if (contentHash && contentHash !== revision)
62
+ return null;
63
+ const comments = value.comments;
64
+ if (comments !== undefined && (!Array.isArray(comments) || comments.length > 100 ||
65
+ comments.some(comment => !comment || typeof comment !== 'object' || Array.isArray(comment) ||
66
+ typeof comment.text !== 'string')))
67
+ return null;
54
68
  return {
55
69
  jobId, taskId, executionId, invocationId, revision, decision,
56
70
  feedback: feedback ?? undefined,
71
+ contentHash: contentHash ?? undefined, revisionId: string('revisionId') ?? undefined,
72
+ previewId: string('previewId') ?? undefined, requestId: string('requestId') ?? undefined,
73
+ idempotencyKey: string('idempotencyKey') ?? undefined,
74
+ comments: comments,
57
75
  eventId: event.event_id,
58
76
  deliveredAt: event.timestamp,
59
77
  };
@@ -67,12 +85,20 @@ export function interactiveDecisionFingerprint(decision) {
67
85
  revision: decision.revision,
68
86
  decision: decision.decision,
69
87
  feedback: decision.feedback ?? null,
88
+ comments: decision.comments ?? null,
70
89
  })).digest('hex');
71
90
  }
91
+ /** First event for an unbound interaction must carry immutable video identity. */
92
+ export function eventOnlyReviewEligible(delivery) {
93
+ return Boolean(delivery.contentHash && /^[a-f0-9]{64}$/.test(delivery.contentHash) &&
94
+ delivery.revision === delivery.contentHash && delivery.feedback !== undefined &&
95
+ [delivery.revisionId, delivery.requestId, delivery.idempotencyKey, delivery.invocationId]
96
+ .every(value => typeof value === 'string' && value.length > 0 && value.length <= 128));
97
+ }
72
98
  function invocationState(invocation) {
73
99
  return invocation?.status ?? 'awaiting_decision';
74
100
  }
75
- async function decideInteractiveInvocation(task, delivery, duplicateDelivery) {
101
+ async function decideInteractiveInvocation(task, delivery, duplicateDelivery, jobActive) {
76
102
  const invocation = task.interactiveInvocation;
77
103
  const result = await dispatchWorkflowGraph(interactiveInvocationGraph, {
78
104
  initialState: invocationState(invocation),
@@ -81,6 +107,12 @@ async function decideInteractiveInvocation(task, delivery, duplicateDelivery) {
81
107
  currentInvocation: invocation?.invocationId === delivery.invocationId,
82
108
  awaitingDecision: invocation?.status === 'awaiting_decision',
83
109
  currentRevision: invocation?.revision === delivery.revision,
110
+ eventOnlyCurrentExecution: jobActive && !invocation && task.state === 'RUNNING' &&
111
+ task.executionId === delivery.executionId && eventOnlyReviewEligible(delivery),
112
+ eventOnlyNextRevision: jobActive && invocation?.status === 'changes_requested' &&
113
+ invocation.executionId === delivery.executionId && task.state === 'RUNNING' &&
114
+ task.executionId === delivery.executionId && invocation.revision !== delivery.revision &&
115
+ eventOnlyReviewEligible(delivery),
84
116
  duplicateDelivery,
85
117
  changesRequested: delivery.decision === 'changes_requested',
86
118
  },
@@ -166,13 +198,13 @@ export class HostInteractiveInvocationCoordinator {
166
198
  }
167
199
  const job = await this.options.store.loadJob(delivery.jobId);
168
200
  const task = job?.tasks.find((item) => item.id === delivery.taskId);
169
- if (!job || !task || task.interactiveInvocation?.executionId !== delivery.executionId ||
170
- (task.executionId !== delivery.executionId && task.state !== 'DRAFT')) {
201
+ if (!job || !task ||
202
+ (task.executionId !== delivery.executionId && task.state !== 'AWAITING_DECISION')) {
171
203
  await this.options.store.recordHostInvocationEvent?.(delivery, 'stale', interactiveDecisionFingerprint(delivery));
172
204
  return { outcome: 'stale', reason: 'execution_not_bound' };
173
205
  }
174
206
  const duplicate = await this.options.store.hasHostInvocationDecision?.(delivery.jobId, delivery.taskId, delivery.invocationId, interactiveDecisionFingerprint(delivery)) ?? false;
175
- const graphDecision = await decideInteractiveInvocation(task, delivery, duplicate);
207
+ const graphDecision = await decideInteractiveInvocation(task, delivery, duplicate, job.state === 'ACTIVE');
176
208
  const selected = graphDecision.actions.some(action => action === 'interactive.requestChanges' || action === 'interactive.approve');
177
209
  if (!graphDecision.accepted || !selected || duplicate) {
178
210
  const outcome = duplicate ? 'duplicate' : 'stale';
@@ -187,7 +219,7 @@ export class HostInteractiveInvocationCoordinator {
187
219
  const accepted = {
188
220
  jobId: delivery.jobId, taskId: delivery.taskId, executionId: delivery.executionId,
189
221
  invocationId: delivery.invocationId, revision: delivery.revision, decision: delivery.decision,
190
- feedback: delivery.feedback, event,
222
+ feedback: delivery.feedback, comments: delivery.comments, idempotencyKey: delivery.idempotencyKey, event,
191
223
  };
192
224
  const key = `${accepted.jobId}:${accepted.taskId}:${accepted.executionId}:${accepted.invocationId}`;
193
225
  const waiter = this.waiters.get(key);
@@ -8,12 +8,12 @@ export async function resumeInteractiveTask(store, jobId, taskId, invocationId,
8
8
  await store.mutateJob(jobId, job => {
9
9
  const task = job.tasks.find(item => item.id === taskId);
10
10
  const invocation = task?.interactiveInvocation;
11
- if (!task || task.state !== 'DRAFT' || !invocation ||
11
+ if (!task || task.state !== 'AWAITING_DECISION' || !invocation ||
12
12
  invocation.invocationId !== invocationId || invocation.revision !== revision ||
13
13
  invocation.status !== decision || !invocation.decidedAt)
14
14
  return job;
15
- // Accepted interactive decisions release the same waiting Task from DRAFT.
16
- if (!tryTransitionTaskEvent(task, 'release').accepted) {
15
+ // Accepted interactive decisions requeue the same waiting Task through the canonical Graph.
16
+ if (!tryTransitionTaskEvent(task, 'interactive.resume').accepted) {
17
17
  throw new Error('Interactive Task release rejected by canonical lifecycle Graph');
18
18
  }
19
19
  applyTaskUnblockRetrySnapshot(task);
@@ -30,7 +30,7 @@ export async function recoverInteractiveDecisions(store, jobId) {
30
30
  const job = await store.load(jobId);
31
31
  let recovered = false;
32
32
  for (const task of job.tasks) {
33
- if (task.state !== 'DRAFT' || !task.interactiveInvocation?.decidedAt)
33
+ if (task.state !== 'AWAITING_DECISION' || !task.interactiveInvocation?.decidedAt)
34
34
  continue;
35
35
  const invocation = task.interactiveInvocation;
36
36
  if (invocation.status === 'awaiting_decision' || !await shouldRecoverInteractiveDecision(invocation.status))
@@ -15,7 +15,7 @@ export function jobHasActiveExecution(job, except = {}) {
15
15
  && task.leaseOwner === null && shortcut && typeof shortcut === 'object'
16
16
  && shortcut.waits
17
17
  && Object.keys(shortcut.waits).length > 0;
18
- return !durableWait && !delegatedWorker && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
18
+ return task.state !== 'AWAITING_DECISION' && !durableWait && !delegatedWorker && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
19
19
  });
20
20
  const planner = (job.plans ?? []).some(plan => plan.id !== except.planId
21
21
  && plan.executionId !== null && plan.status === 'PLANNING');
@@ -12,7 +12,7 @@ import { publishLocalCommit } from './local-commit-events.js';
12
12
  * not lifecycle storage. An explicit one-time import must use RelayStore directly.
13
13
  */
14
14
  const TASK_STATE_ORDER = {
15
- DRAFT: 0, QUEUED: 1, RUNNING: 2, BLOCKED: 3,
15
+ DRAFT: 0, QUEUED: 1, RUNNING: 2, AWAITING_DECISION: 3, BLOCKED: 4,
16
16
  SUCCEEDED: 5, FAILED: 5, CANCELLED: 5,
17
17
  };
18
18
  export class LocalAuthorityDurableStore {
@@ -72,7 +72,7 @@ export class ReconcilerRuntimeBase {
72
72
  }
73
73
  });
74
74
  }
75
- async applyHostInvocationEvent(event) { const result = await this.hostInvocations.applyEvent(event); const resumed = result.resumeWorker && result.decision ? await resumeInteractiveTask(this.store, result.decision.jobId, result.decision.taskId, result.decision.invocationId, result.decision.revision, result.decision.decision) : false; return { applied: result.outcome !== 'ignored', reconcile: resumed, reason: `task.interactive_decision.${result.outcome}` }; }
75
+ async applyHostInvocationEvent(event) { const result = await this.hostInvocations.applyEvent(event); const resumed = result.resumeWorker && result.decision ? await resumeInteractiveTask(this.store, result.decision.jobId, result.decision.taskId, result.decision.invocationId, result.decision.revision, result.decision.decision) : false; return { applied: result.outcome !== 'ignored', reconcile: resumed || result.outcome === 'accepted', reason: `task.interactive_decision.${result.outcome}` }; }
76
76
  bindInteractiveInvocation(jobId, task, executionId, invocationId, revision) { return this.hostInvocations.bind(jobId, task, executionId, invocationId, revision); }
77
77
  async applyJobEffectOutcomes(job, outcomes) {
78
78
  await applyJobEffectOutcomes(this.store, event => this.emit(event), job, outcomes);
@@ -102,7 +102,7 @@ export class ReconcilerRuntimeBase {
102
102
  if (normalized)
103
103
  return normalized.type === 'task.failed' ? this.applyTerminalEvent(normalized) : this.applyReviewEvent(normalized);
104
104
  }
105
- if (['task.completed', 'task.failed', 'task.blocked', 'task.cancelled'].includes(event.type)) {
105
+ if (['task.completed', 'task.failed', 'task.blocked', 'task.cancelled', 'task.interactive_waiting'].includes(event.type)) {
106
106
  const result = await this.applyTerminalEvent(event);
107
107
  if (event.type !== 'task.failed' || event.source?.watchdog !== true || event.data?.workflowEvent !== 'watchdog.failed' || result.reconcile)
108
108
  return result;
@@ -400,15 +400,17 @@ export class ReconcilerRuntimeBase {
400
400
  }
401
401
  const liveAtTerminal = this.live.get(event.task_id);
402
402
  const terminalEventExecutionId = executionIdFromSource(eventSourceId(event), event.job_id, event.task_id);
403
- const lifecycleEvent = event.type === 'task.blocked'
404
- ? (await this.store.load(event.job_id)).tasks.find(task => task.id === event.task_id)?.interactiveInvocation?.status === 'awaiting_decision'
405
- ? 'interactive.waiting' : event.type
406
- : event.type;
403
+ const lifecycleEvent = event.type;
407
404
  const transition = await withExecutionBoundary(event.job_id, event.task_id, () => this.taskTransitions.apply(event.job_id, event.task_id, lifecycleEvent, {
408
405
  eligible: (_job, task) => {
409
406
  if (!['codex', 'chatgpt', 'z', 'orchestrator'].includes(task.adapter))
410
407
  return false;
411
- if (event.type === 'task.blocked' && lifecycleEvent !== 'interactive.waiting' && (!trustedInternal || task.agentName !== 'troubleshooter'))
408
+ if (event.type === 'task.blocked' && (!trustedInternal || task.agentName !== 'troubleshooter'))
409
+ return false;
410
+ if (event.type === 'task.interactive_waiting' &&
411
+ (task.interactiveInvocation?.status !== 'awaiting_decision' ||
412
+ task.interactiveInvocation.executionId !== task.executionId ||
413
+ !isCorrelatedWorkerEvent(task, event)))
412
414
  return false;
413
415
  if (isFinalReviewAgent(task.agentName) && event.type === 'task.completed')
414
416
  return false;
@@ -427,7 +429,7 @@ export class ReconcilerRuntimeBase {
427
429
  facts: (_job, task) => {
428
430
  const processExitedAfterPublishedTerminal = task.failureReason === 'worker_exit_without_terminal_event';
429
431
  const freshEnough = processExitedAfterPublishedTerminal || isCorrelatedWorkerEvent(task, event);
430
- return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough, awaitingInteractiveDecision: lifecycleEvent === 'interactive.waiting' && task.interactiveInvocation?.status === 'awaiting_decision' };
432
+ return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough, awaitingInteractiveDecision: lifecycleEvent === 'task.interactive_waiting' && task.interactiveInvocation?.status === 'awaiting_decision' };
431
433
  },
432
434
  mutate: (job, task) => {
433
435
  const modelBacked = ['codex', 'chatgpt', 'z'].includes(task.adapter);
@@ -458,7 +460,7 @@ export class ReconcilerRuntimeBase {
458
460
  task.error = event.message || `Task ${task.id} failed`;
459
461
  task.failureReason = typeof event.data?.reason === 'string' ? event.data.reason : undefined;
460
462
  }
461
- else if (event.type === 'task.blocked' && lifecycleEvent !== 'interactive.waiting') {
463
+ else if (event.type === 'task.blocked') {
462
464
  task.error = event.message || `Task ${task.id} blocked`;
463
465
  const data = event.data ?? {};
464
466
  const head = ['candidate_head', 'candidate_head_sha', 'pr_head', 'head_sha']
@@ -478,7 +480,7 @@ export class ReconcilerRuntimeBase {
478
480
  }));
479
481
  if (!transition?.decision.accepted)
480
482
  return { applied: false, reconcile: false, reason: `${event.type}.ignored` };
481
- if (lifecycleEvent !== 'interactive.waiting')
483
+ if (lifecycleEvent !== 'task.interactive_waiting')
482
484
  await recordTerminalRouteOutcome(this.options.decisionAuditStore, transition.task, event, terminalEventExecutionId ?? null);
483
485
  if (transition.task.adapter === 'codex' && liveAtTerminal && !liveAtTerminal.processSettled && liveAtTerminal.jobId === event.job_id && (!terminalEventExecutionId || liveAtTerminal.executionId === terminalEventExecutionId)) {
484
486
  liveAtTerminal.controller.abort();
@@ -487,7 +489,7 @@ export class ReconcilerRuntimeBase {
487
489
  if (event.type === 'task.completed')
488
490
  await this.deliverContinuation(transition.job, transition.task);
489
491
  const reviewWorker = isFinalReviewAgent(transition.task.agentName);
490
- return { applied: true, reconcile: lifecycleEvent !== 'interactive.waiting' && (!reviewWorker || event.type === 'task.failed'), reason: reviewWorker ? `${event.type}.review-worker` : event.type, reconcileMode: reviewWorker || lifecycleEvent === 'interactive.waiting' ? undefined : 'detached' };
492
+ return { applied: true, reconcile: lifecycleEvent !== 'task.interactive_waiting' && (!reviewWorker || event.type === 'task.failed'), reason: reviewWorker ? `${event.type}.review-worker` : event.type, reconcileMode: reviewWorker || lifecycleEvent === 'task.interactive_waiting' ? undefined : 'detached' };
491
493
  }
492
494
  terminalWait(taskId, executionId, launchBarrier) {
493
495
  let resolve;
@@ -61,7 +61,7 @@ export function deriveJobRuntimeStatus(job, _prState = 'OPEN') {
61
61
  const staleRevisions = staleTargetedRevisionTaskIds(job);
62
62
  if (job.tasks.some(task => task.state === 'FAILED' && !staleRevisions.has(task.id)))
63
63
  return 'FAILED';
64
- if (job.tasks.some(task => task.state === 'DRAFT'))
64
+ if (job.tasks.some(task => task.state === 'AWAITING_DECISION' || task.state === 'DRAFT'))
65
65
  return 'WAITING';
66
66
  if (plannerFailed)
67
67
  return 'FAILED';
@@ -59,7 +59,7 @@ export async function driveShortcutWorkers(options) {
59
59
  });
60
60
  return { status: 'COMPLETED', job };
61
61
  }
62
- if (job.tasks.some(task => task.state === 'BLOCKED'))
62
+ if (job.tasks.some(task => task.state === 'BLOCKED' || task.state === 'AWAITING_DECISION'))
63
63
  return { status: 'WAITING_EVENT', job };
64
64
  if (job.tasks.some(task => task.agentName === 'troubleshooter' && task.state === 'FAILED' && task.attempt >= task.maxAttempts))
65
65
  return { status: 'FAILED', job };
package/dist/types.js CHANGED
@@ -12,6 +12,15 @@ export function normalizeLegacyTaskLifecycle(task) {
12
12
  task.maxAttempts = Math.max(3, task.maxAttempts ?? 0, task.attempt + 1);
13
13
  task.unblock = task.unblock ? { ...task.unblock, event: 'task.unblocked' } : undefined;
14
14
  }
15
+ // Migrate persisted interactive waits from their former overloaded DRAFT state.
16
+ // Ordinary dependency-held DRAFT Tasks remain untouched.
17
+ if (legacy.state === 'DRAFT' && task.attempt > 0 && task.interactiveInvocation &&
18
+ !task.executionId && task.interactiveInvocation.boundAt && !task.unblock &&
19
+ (task.interactiveInvocation.status === 'awaiting_decision' ||
20
+ (Boolean(task.interactiveInvocation.decidedAt) &&
21
+ Date.parse(task.updatedAt) <= Date.parse(task.interactiveInvocation.decidedAt)))) {
22
+ legacy.state = 'AWAITING_DECISION';
23
+ }
15
24
  if (legacy.state === 'BLOCKED' && task.kind !== 'planner' && task.agentName !== 'troubleshooter') {
16
25
  legacy.state = 'FAILED';
17
26
  task.failureReason ??= task.failureReason === 'worker_outcome_unknown' ? task.failureReason : 'legacy_ordinary_blocked';
@@ -12,7 +12,7 @@ export const WORKFLOW_EVENT_NAMES = [
12
12
  'hold',
13
13
  'lease.expired',
14
14
  'implementation.completed',
15
- 'interactive.waiting',
15
+ 'task.interactive_waiting',
16
16
  'local.completed',
17
17
  'local.merge.requested',
18
18
  'effect.deliverLocalMerge.failed',
@@ -26,6 +26,7 @@ export const WORKFLOW_EVENT_NAMES = [
26
26
  'reconcile',
27
27
  'recovery.reopen',
28
28
  'release',
29
+ 'interactive.resume',
29
30
  'retry',
30
31
  'review.started',
31
32
  'review.approved',
@@ -45,7 +46,6 @@ export const WORKFLOW_EVENT_NAMES = [
45
46
  'effect.launchShortcut.failed',
46
47
  'effect.resumeShortcut.failed',
47
48
  'task.unblocked',
48
- 'interactive.waiting',
49
49
  'watchdog.failed',
50
50
  'worker.delivery_failed',
51
51
  'worker.start_ack_failed',
@@ -2,7 +2,7 @@ import { ConditionRegistry, booleanCondition } from './conditions.js';
2
2
  import { readFileSync } from 'node:fs';
3
3
  import { GraphRuntime } from './graph-v2.js';
4
4
  import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, } from './contracts.js';
5
- const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
5
+ const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'AWAITING_DECISION', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
6
6
  const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
7
7
  const conditionRegistry = new ConditionRegistry([
8
8
  ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady', 'shortcutCompletionAllowed'])
@@ -62,7 +62,7 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
62
62
  hasSeedWork: !((job.plans?.length ?? 0) === 0 && job.tasks.filter(task => task.kind !== 'planner').length === 0),
63
63
  noActivePlanner: failedPlan?.manualPlanning ? false : unblockNeedsNewPlan(job) || !unconsumedUnblockTrigger(job) ? !scopedPlans.some(plan => plan.status === 'PLANNING') : false,
64
64
  noBlockedWork: Boolean(unconsumedUnblockTrigger(job)) || !scopedTasks.some(task => task.kind !== 'planner' && isEffectivelyBlocked(task)),
65
- noActiveImplementation: !scopedTasks.some(task => task.kind !== 'planner' && (['QUEUED', 'RUNNING'].includes(task.state) || (task.state === 'DRAFT' && !task.unblock))),
65
+ noActiveImplementation: !scopedTasks.some(task => task.kind !== 'planner' && (['QUEUED', 'RUNNING', 'AWAITING_DECISION'].includes(task.state) || (task.state === 'DRAFT' && !task.unblock))),
66
66
  resolutionOwnedByTroubleshooter: scopedTasks.some(task => task.kind !== 'planner' && task.resolution?.owner === 'troubleshooter' && ['active', 'waiting'].includes(task.resolution.state)),
67
67
  continuationMaterialized: Boolean(unconsumedUnblockTrigger(job)) || !(latestObjective === 'in_progress' && latestId && !job.tasks.some(task => task.kind !== 'planner' && task.planningDecisionId === latestId)),
68
68
  objectiveUnsatisfied: latestObjective !== 'satisfied',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.210",
3
+ "version": "2.0.212",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,6 +42,71 @@ The automatically created `job-acceptance-reviewer` (historical `reviewer` recor
42
42
  A fix child reports its **own** correlated completion after verified repair. Downstream `dependencyValidity` policy is `order-only` by default, or explicitly `revalidate`/`rerun` per declared input. All changed upstream generations must settle before a fan-in consumer can verify or rerun. Relay derives successful revision lineage from durable Task results, then creates another fresh immutable-head Job Acceptance Review. A partially submitted message, unverified terminal, historical result or stale source SHA does not count as a fix or approval.
43
43
 
44
44
 
45
+ ## Interactive Task suspension
46
+
47
+ After binding a host invocation, a RUNNING Worker waiting for human input
48
+ publishes `task.interactive_waiting` with its exact Job/Task/Execution source identity.
49
+ Relay checks the pending invocation, persists RUNNING -> AWAITING_DECISION,
50
+ clears the execution lease, and releases the Worker. This is a non-failure
51
+ handoff and is not a Task completion or a Troubleshooter block.
52
+ The Job stays ACTIVE; the Task does not requeue until a matching
53
+ `task.interactive_decision` is durably accepted and the Task Graph selects
54
+ `interactive.resume` -> QUEUED. Retries and daemon restarts must not create
55
+ another Task. Cancellation remains legal while awaiting a decision.
56
+
57
+ The invocation record holds immutable request/revision identity and the
58
+ decision outcome. Its status is not the authority for the Task execution
59
+ lifecycle; Task.state is. The older overloaded DRAFT waiting snapshots
60
+ are normalized to AWAITING_DECISION when the SQLite store starts.
61
+ Do not use `task.blocked` to suspend an interactive Task.
62
+
63
+ ## Generic interactive decision event (human review)
64
+
65
+ **Canonical type:** `task.interactive_decision`. This is a human decision for an in-progress Task (video preview, document review, image approval, etc.), **not** an Implementation terminal event or a Job Final Reviewer verdict. A UI such as Markcut is a generic publisher: it receives a caller-supplied template and fills only the declared review-result fields. It must not invent Task/Execution/source identity or a new Relay-specific event type.
66
+
67
+ **Producer event template**, based on the exact managed Task execution context (illustrative identities only):
68
+
69
+ ```json
70
+ {
71
+ "type": "task.interactive_decision",
72
+ "source": "job/556/task/producer/execution/exec-abc",
73
+ "data": {
74
+ "interactive": {
75
+ "jobId": "556",
76
+ "taskId": "producer",
77
+ "executionId": "exec-abc",
78
+ "invocationId": "review-request-123"
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ The caller provides this as `markcut.preview({path, review:{delivery:"event", eventTemplate}})` or the same metadata in a Neo Mobile review request. `source` and the four template identity fields are immutable. They must match the current Job/Task/Execution. An invocation ID is a stable unique identifier for the human review request; it is not a video revision, a new Task, or a generated execution ID.
85
+
86
+ **On human Submit**, the Preview UI fills the following fields under `data.interactive`, preserving every caller-owned field:
87
+
88
+ | Field | Rule |
89
+ | --- | --- |
90
+ | `decision` | **Required**: `approved` or `changes_requested`; only the human sets it. |
91
+ | `feedback` | **Required** string: plain-language feedback, or `""` on approval. |
92
+ | `comments` | Optional structured scene/timestamp comments; do not flatten or discard when available. |
93
+ | `revision` | **Required**: immutable content SHA-256 for the reviewed video in event-only mode. |
94
+ | `contentHash` | **Required** in event-only mode; equals `revision`, exact 64 lowercase hex. |
95
+ | `revisionId` | **Required** in event-only mode: human-visible immutable preview revision identifier. |
96
+ | `previewId`, `requestId` | Optional/required respectively in event-only mode; bind the original review request. |
97
+ | `idempotencyKey` | **Required** in event-only mode, stable across delivery retries. |
98
+
99
+ For a human clicking Approve or Request Changes, **one submitted decision generates one event**. Editing individual comments does not publish events. The Preview and Neo Mobile use the same field paths. Events Bus still accepts `{type,source,data}`; via Neo MCP `events`, call `{command:"publish",args:{type,source,data}}`. A successful publish is only a transport receipt, **not** an accepted Relay decision or a completed revision.
100
+
101
+ **Relay admission and Graph semantics:**
102
+
103
+ 1. Normalize the event, validate the source identity against the data and current Task, then consult the canonical `workflow/interactive-invocation.mmd` Graph. Reject stale executions, invalid decisions/versions, wrong identities, cancelled Jobs and duplicated/conflicting decisions; record the decision atomically in Relay-owned durable state.
104
+ 2. Legacy host-bound invocations remain supported. An event-only decision may arrive **without a preceding `bindInteractiveInvocation()`** when the Job is ACTIVE, the Task is RUNNING in the exact matching Execution, and the event carries complete immutable content identity. A later video revision may be submitted for the same execution only after `changes_requested`; already decided revisions may not be replayed as new ones.
105
+ 3. `changes_requested` records actionable feedback for the owning Task. `approved` passes only the human interaction gate for **that exact content**; it does not mark a Task or Job complete. Graph-selected continuation/recovery is separate from the Event Bus receipt. A RUNNING Worker that did not register a waiting Promise must consume the accepted decision via its event-driven workflow; accepting the event alone does not create a new Agent Turn.
106
+ 4. **Limitation of an entirely unbound event**: Relay cannot independently prove that a never-before-seen content hash is the *latest* Markcut preview solely from the Event payload. The Preview provider and mobile client must reject superseded revisions before publishing; a future trusted, durable preview-generation fact is necessary if Relay must independently reject every previously unreviewed stale version. Do not present client-declared revision fields as cryptographic authorization.
107
+
108
+ `review.approved` and `review.changes_required` belong to immutable-head Job Acceptance Review; do **not** emit those or `task.completed` from a Preview UI. Consumers outside Relay may use their own event type, but managed Relay review templates must use `task.interactive_decision`.
109
+
45
110
  ## Troubleshooter human escalation
46
111
 
47
112
  Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
@@ -52,7 +117,7 @@ See [task-recovery-flows.md](task-recovery-flows.md) for unified architecture, o
52
117
 
53
118
  Reviewer unavailable evidence is an execution failure (`task.failed`), not a blocked Task. Legacy Reviewer verdict `blocked` is normalized to failure and must dispatch Troubleshooter. Only Relay blocks a Troubleshooter during human escalation.
54
119
 
55
- A host-mediated interactive invocation is a separate Relay-controlled wait. It requires an already-bound `interactiveInvocation` with status `awaiting_decision`. It is not permission for a Worker or Reviewer to choose a blocked terminal outcome.
120
+ A host-mediated interactive invocation remains a Relay-controlled wait when explicitly bound. The event-only path above accepts complete decisions from current active executions without requiring prior binding; neither route authorizes a Worker or Reviewer to choose a blocked terminal outcome.
56
121
 
57
122
  A legacy Job-level `review: blocked` gate is reset to `pending` only after authoritative `task.unblocked` metadata exists on its bound Reviewer Task and the immutable review head still matches. The same Reviewer Task then resumes without creating a duplicate.
58
123
 
@@ -10,6 +10,8 @@ approved["state: approved"]
10
10
  context["guard: currentInvocation"]
11
11
  awaiting["guard: awaitingDecision"]
12
12
  revision["guard: currentRevision"]
13
+ unbound["guard: eventOnlyCurrentExecution"]
14
+ newRevision["guard: eventOnlyNextRevision"]
13
15
  duplicateChanges["guard: duplicateDelivery"]
14
16
  duplicateApproved["guard: duplicateDelivery"]
15
17
  decisionKind["guard: changesRequested"]
@@ -22,11 +24,16 @@ awaiting_decision -->|on: task.interactive_decision| context
22
24
  changes -->|on: task.interactive_decision| duplicateChanges
23
25
  approved -->|on: task.interactive_decision| duplicateApproved
24
26
  context -->|true| awaiting
25
- context -->|false| awaiting_decision
27
+ context -->|false| unbound
28
+ unbound -->|true| decisionKind
29
+ unbound -->|false| awaiting_decision
26
30
  awaiting -->|true| revision
27
31
  awaiting -->|false| awaiting_decision
28
32
  revision -->|true| decisionKind
29
33
  revision -->|false| awaiting_decision
34
+ duplicateChanges -->|false| newRevision
35
+ newRevision -->|true| decisionKind
36
+ newRevision -->|false| changes
30
37
  decisionKind -->|true| requestChanges
31
38
  decisionKind -->|false| approve
32
39
  requestChanges --> wakeChanges
@@ -34,7 +41,6 @@ wakeChanges -->|to: changes_requested| changes
34
41
  approve --> wake
35
42
  wake -->|to: approved| approved
36
43
  duplicateChanges -->|true| wakeChanges
37
- duplicateChanges -->|false| changes
38
44
  duplicateApproved -->|true| wake
39
45
  duplicateApproved -->|false| approved
40
46
  changes -->|on: task.interactive_recover| wakeChanges
@@ -7,6 +7,7 @@ flowchart LR
7
7
  draft["state: DRAFT"]
8
8
  queued["state: QUEUED"]
9
9
  running["state: RUNNING"]
10
+ awaitingDecision["state: AWAITING_DECISION"]
10
11
  blocked["state: BLOCKED"]
11
12
  succeeded["state: SUCCEEDED"]
12
13
  failed["state: FAILED"]
@@ -168,12 +169,14 @@ leaseFailQueuedClearLease --> leaseFailQueuedClearExecution
168
169
  leaseFailQueuedClearExecution --> failed
169
170
  queued -->|on: cancel| cancelled
170
171
 
171
- running -->|on: interactive.waiting| interactiveWaitAllowed
172
+ running -->|on: task.interactive_waiting| interactiveWaitAllowed
172
173
  interactiveWaitAllowed -->|true| runningWaitClearLease
173
174
  runningWaitClearLease["action: mutation.clearLease"]
174
175
  runningWaitClearLease --> runningWaitClearExecution
175
176
  runningWaitClearExecution["action: mutation.clearExecution"]
176
- runningWaitClearExecution --> draft
177
+ runningWaitClearExecution --> awaitingDecision
178
+ awaitingDecision -->|on: interactive.resume| releaseClearError
179
+ awaitingDecision -->|on: cancel| cancelled
177
180
  running -->|on: task.blocked| runningBlockAllowed
178
181
  runningBlockAllowed -->|true| blocked
179
182
  runningBlockAllowed -->|false| failed