agents-relay 2.0.245 → 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.
@@ -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 {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.245",
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