agents-relay 2.0.209 → 2.0.211

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.
Files changed (50) hide show
  1. package/dist/cli-help.js +10 -4
  2. package/dist/cli-prompt.js +2 -1
  3. package/dist/cli-revision.js +49 -0
  4. package/dist/cli-worker-task.js +15 -0
  5. package/dist/cli.js +11 -2
  6. package/dist/dashboard-html.js +2 -2
  7. package/dist/dependency-revision-execution.js +152 -0
  8. package/dist/dependency-validity.js +17 -0
  9. package/dist/final-review-role.js +17 -0
  10. package/dist/force-restate-validation.js +3 -2
  11. package/dist/host-invocation-store.js +18 -4
  12. package/dist/interactive-invocation.js +37 -5
  13. package/dist/job-pr-number-migration.js +2 -1
  14. package/dist/managed-worker-input.js +2 -1
  15. package/dist/planner-agent-roles.js +18 -0
  16. package/dist/planner-runtime.js +7 -1
  17. package/dist/planner-task-ids.js +1 -0
  18. package/dist/planner.js +11 -6
  19. package/dist/reconciler-review.js +78 -96
  20. package/dist/reconciler-runtime.js +14 -5
  21. package/dist/reconciler.js +21 -11
  22. package/dist/relay-store.js +2 -0
  23. package/dist/relayd-control.js +31 -0
  24. package/dist/review-evidence.js +44 -0
  25. package/dist/review-generation-fence.js +2 -1
  26. package/dist/review-revision-execution.js +86 -0
  27. package/dist/review-revision-merge.js +15 -0
  28. package/dist/review-revision-model.js +191 -0
  29. package/dist/review-revision-policy.js +49 -0
  30. package/dist/review-revision-settlement.js +54 -0
  31. package/dist/review-revision-stale.js +57 -0
  32. package/dist/reviewer-thread.js +41 -1
  33. package/dist/runtime-status.js +13 -4
  34. package/dist/single-job-task-control.js +1 -1
  35. package/dist/task-context.js +3 -2
  36. package/dist/worker-failure-recovery.js +2 -1
  37. package/dist/workflow/dependency-revision-v2.js +16 -0
  38. package/dist/workflow/entity-creation.js +2 -0
  39. package/dist/workflow/review-v2.js +6 -2
  40. package/dist/workflow/revision-v2.js +32 -0
  41. package/dist/workflow/task-reconcile.js +3 -0
  42. package/package.json +1 -1
  43. package/skills/agents-relay/agents/job-acceptance-reviewer.agent.md +41 -0
  44. package/skills/agents-relay/agents/planner.agent.md +6 -3
  45. package/skills/agents-relay/contracts/event-contract.md +55 -1
  46. package/skills/agents-relay/contracts/task-job-contract.md +6 -0
  47. package/workflow/dependency-revision.mmd +30 -0
  48. package/workflow/interactive-invocation.mmd +8 -2
  49. package/workflow/review-lifecycle.mmd +40 -9
  50. package/workflow/revision-lifecycle.mmd +68 -0
@@ -1,3 +1,6 @@
1
+ import { revisionRequestReady, reconcileReviewRevisions } from './review-revision-execution.js';
2
+ import { reconcileDependencyRevisions } from './dependency-revision-execution.js';
3
+ import { isFinalReviewAgent } from './final-review-role.js';
1
4
  import { deliverPendingEscalations } from './escalation-notifier.js';
2
5
  import { createFailedPlanRecovery } from './planner-recovery.js';
3
6
  import { recoverPlannerChildren } from './planner-child-recovery.js';
@@ -18,7 +21,7 @@ import { retryPendingPlannerUnblocks } from './planner-runtime.js';
18
21
  import { dispatchPlannerOrchestration, plannerOrchestrationFacts } from './workflow/planner-orchestration-v2.js';
19
22
  import { ReconcilerReviewBase } from './reconciler-review.js';
20
23
  import { executeForceRestate } from './force-restate.js';
21
- import { recordThreadDelivery, resolveImplementationTaskThreadDestination, prepareReviewerThreadDelivery, resolveReviewerThreadDestination } from './reviewer-thread.js';
24
+ import { recordThreadDelivery, resolveImplementationTaskThreadDestination, prepareRevisionThreadDelivery, prepareReviewerThreadDelivery, resolveReviewerThreadDestination } from './reviewer-thread.js';
22
25
  import { executeManualPlan } from './manual-plan.js';
23
26
  import { executionEventSource, withExecutionBoundary } from './reconciler-runtime.js';
24
27
  export { executionEventSource } from './reconciler-runtime.js';
@@ -70,7 +73,7 @@ export class Reconciler extends ReconcilerReviewBase {
70
73
  }
71
74
  const capacity = Math.max(0, (this.options.maxConcurrent ?? 4) - this.live.size - this.plannerLive.size);
72
75
  const dispatchable = (jobHasActiveExecution(scheduled) ? [] : scheduled.tasks)
73
- .filter(task => task.state === 'QUEUED'
76
+ .filter(task => revisionRequestReady(scheduled, task) && task.state === 'QUEUED'
74
77
  && task.executionId === null
75
78
  && task.kind !== 'planner'
76
79
  && task.adapter !== 'orchestrator'
@@ -183,6 +186,8 @@ export class Reconciler extends ReconcilerReviewBase {
183
186
  this.cancelExecutionGeneration(job.id, task.id, task.executionId ?? task.executionHistory?.at(-1)?.id);
184
187
  this.plannerLive.get(task.id)?.controller.abort();
185
188
  }
189
+ await reconcileReviewRevisions(this.store, jobId);
190
+ await reconcileDependencyRevisions(this.store, jobId);
186
191
  const beforeSchedule = await this.store.load(jobId);
187
192
  const taskStatesBeforeSchedule = new Map(beforeSchedule.tasks.map(task => [task.id, task.state]));
188
193
  let scheduled = refreshTaskDependencies(beforeSchedule);
@@ -355,16 +360,17 @@ export class Reconciler extends ReconcilerReviewBase {
355
360
  const claimedTask = await withExecutionBoundary(job.id, '__job_execution_slot__', async () => {
356
361
  const freshJob = await this.store.load(job.id);
357
362
  let freshTask = freshJob.tasks.find(item => item.id === task.id);
358
- if (!freshTask || freshTask.state !== 'QUEUED' || !dependencyReady(freshTask, new Map(freshJob.tasks.map(item => [item.id, item]))))
363
+ if (!freshTask || freshTask.state !== 'QUEUED' || !revisionRequestReady(freshJob, freshTask)
364
+ || !dependencyReady(freshTask, new Map(freshJob.tasks.map(item => [item.id, item]))))
359
365
  return;
360
366
  if (freshTask.executionId !== null)
361
367
  return;
362
368
  if (jobHasActiveExecution(freshJob, { taskId: freshTask.id }))
363
369
  return;
364
- if (freshTask.agentName === 'reviewer' && freshTask.planningDecisionId && freshTask.dependencies.length)
370
+ if (isFinalReviewAgent(freshTask.agentName) && freshTask.planningDecisionId && freshTask.dependencies.length)
365
371
  await bindPlannedReviewHead(this.store, freshTask, await this.currentHeadSha(freshJob));
366
372
  const implementationThread = resolveImplementationTaskThreadDestination(freshJob, freshTask);
367
- if ((!freshTask.routing || ((implementationThread || (freshTask.agentName === 'reviewer' && resolveReviewerThreadDestination(freshJob, this.options.reviewer?.threadId))) && freshTask.adapter !== 'chatgpt')) && freshTask.adapter !== 'orchestrator') {
373
+ if ((!freshTask.routing || ((implementationThread || (isFinalReviewAgent(freshTask.agentName) && resolveReviewerThreadDestination(freshJob, this.options.reviewer?.threadId))) && freshTask.adapter !== 'chatgpt')) && freshTask.adapter !== 'orchestrator') {
368
374
  const routed = await this.routeTaskForExecutionFailClosed(freshJob, freshTask);
369
375
  if (!routed)
370
376
  return;
@@ -387,9 +393,11 @@ export class Reconciler extends ReconcilerReviewBase {
387
393
  attempt: freshTask.attempt,
388
394
  startedAt: new Date(startedAt).toISOString(),
389
395
  }].slice(-8);
390
- if (freshTask.agentName === 'reviewer')
396
+ if (isFinalReviewAgent(freshTask.agentName))
391
397
  freshTask.chatgptThreadDelivery = prepareReviewerThreadDelivery(freshJob, freshTask, this.options.reviewer?.threadId);
392
- if (implementationThread && freshTask.adapter === 'chatgpt') {
398
+ if (freshTask.revision?.kind === 'targeted')
399
+ freshTask.chatgptThreadDelivery = prepareRevisionThreadDelivery(freshJob, freshTask);
400
+ if (implementationThread && !freshTask.revision && freshTask.adapter === 'chatgpt') {
393
401
  freshTask.chatgptThreadDelivery = {
394
402
  kind: 'new-turn', threadId: implementationThread, threadSource: 'implementation',
395
403
  requestId: `${freshJob.id}:${freshTask.id}:${freshTask.executionId}`,
@@ -401,7 +409,7 @@ export class Reconciler extends ReconcilerReviewBase {
401
409
  let claimed;
402
410
  await this.store.mutateJob(job.id, current => {
403
411
  const durable = current.tasks.find(item => item.id === freshTask.id);
404
- if (!durable || durable.state !== 'QUEUED' || durable.executionId !== null
412
+ if (!durable || durable.state !== 'QUEUED' || !revisionRequestReady(current, durable) || durable.executionId !== null
405
413
  || !dependencyReady(durable, new Map(current.tasks.map(item => [item.id, item]))))
406
414
  return current;
407
415
  if (freshTask.routing)
@@ -419,9 +427,11 @@ export class Reconciler extends ReconcilerReviewBase {
419
427
  id: durable.executionId, attempt: durable.attempt, startedAt: new Date(startedAt).toISOString(),
420
428
  }].slice(-8);
421
429
  const implementationThread = resolveImplementationTaskThreadDestination(current, durable);
422
- if (durable.agentName === 'reviewer')
430
+ if (isFinalReviewAgent(durable.agentName))
423
431
  durable.chatgptThreadDelivery = prepareReviewerThreadDelivery(current, { ...durable, routing: freshTask.routing }, this.options.reviewer?.threadId);
424
- if (implementationThread && durable.adapter === 'chatgpt') {
432
+ if (durable.revision?.kind === 'targeted')
433
+ durable.chatgptThreadDelivery = prepareRevisionThreadDelivery(current, durable);
434
+ if (implementationThread && !durable.revision && durable.adapter === 'chatgpt') {
425
435
  durable.chatgptThreadDelivery = {
426
436
  kind: 'new-turn', threadId: implementationThread, threadSource: 'implementation',
427
437
  requestId: `${current.id}:${durable.id}:${durable.executionId}`,
@@ -452,7 +462,7 @@ export class Reconciler extends ReconcilerReviewBase {
452
462
  }
453
463
  let executionContext;
454
464
  try {
455
- const role = task.agentName === 'reviewer' ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
465
+ const role = isFinalReviewAgent(task.agentName) ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
456
466
  const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job, task) : task.routing?.cwd ?? process.cwd();
457
467
  executionContext = await this.resolvedContext(job, task, role, projectPath);
458
468
  }
@@ -1,6 +1,7 @@
1
1
  import { currentJobMetadata, loadRelayJob, listRelayJobs } from './relay-job-snapshot-reads.js';
2
2
  import { SQLiteWorkflowOperations } from './relay-workflow-operations.js';
3
3
  import { preserveTaskComments } from './task-comments.js';
4
+ import { preserveReviewRevisionHistory } from './review-revision-merge.js';
4
5
  import { DatabaseSync } from 'node:sqlite';
5
6
  import { migrateLegacyBlockedTasks } from './legacy-blocked-task-migration.js';
6
7
  import { dirname } from 'node:path';
@@ -31,6 +32,7 @@ function mergeRecords(local, remote) {
31
32
  export function mergeInboundJobSnapshot(local, remote) {
32
33
  const base = remote.updatedAt > local.updatedAt ? structuredClone(remote) : structuredClone(local);
33
34
  base.tasks = preserveTaskComments(local.tasks, mergeRecords(local.tasks, remote.tasks));
35
+ preserveReviewRevisionHistory(local, base);
34
36
  const localPlans = local.plans ?? [];
35
37
  const remotePlans = remote.plans ?? [];
36
38
  if (localPlans.length > 0 || remotePlans.length > 0) {
@@ -1,3 +1,5 @@
1
+ import { submitTargetedRevisionRequest } from './review-revision-model.js';
2
+ import { localSourceHead, localWorkingHead } from './local-git-merge.js';
1
3
  import { appendTaskComment } from './task-comments.js';
2
4
  import { InMemoryStore } from './store.js';
3
5
  import { openLocalManagedStore } from './local-managed-store.js';
@@ -7,6 +9,7 @@ import { publishTaskBlocked } from './cli-support.js';
7
9
  import { classifyFailedTask, supersedeCancelledTask } from './task-actions.js';
8
10
  import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
9
11
  import { adoptExistingPullRequestJob } from './cli-job-create.js';
12
+ import { resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
10
13
  export function createWorkspaceControl(deps) {
11
14
  const { client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob } = deps;
12
15
  const workspaceControl = async (body) => {
@@ -137,6 +140,34 @@ export function createWorkspaceControl(deps) {
137
140
  await pool.reconcileLocalJob(jobId, 'control.job.unblock');
138
141
  return await store.load(jobId);
139
142
  }
143
+ if (command === 'task.revise') {
144
+ const repository = typeof body.repository === 'string' ? body.repository : '';
145
+ const originalTaskId = typeof body.taskId === 'string' ? body.taskId : '';
146
+ const reviewTaskId = typeof body.reviewTaskId === 'string' ? body.reviewTaskId : '';
147
+ const reviewExecutionId = typeof body.reviewExecutionId === 'string' ? body.reviewExecutionId : '';
148
+ const headSha = typeof body.headSha === 'string' ? body.headSha : '';
149
+ const requestId = typeof body.requestId === 'string' ? body.requestId : '';
150
+ const findings = body.findings;
151
+ if (!repository || repository !== job.repository || !originalTaskId || !reviewTaskId || !reviewExecutionId || !requestId
152
+ || !/^[a-f0-9]{40,64}$/i.test(headSha) || !Array.isArray(findings) || findings.length < 1 || findings.length > 200)
153
+ throw new Error('task.revise requires matching repository, original/reviewer IDs, active execution ID, valid SHA, stable request ID and nonempty findings');
154
+ // Trust fresh local Git truth, not the caller or PR projection. The
155
+ // atomic reducer independently checks durable head and execution.
156
+ const projectRoot = await resolveManagedProjectPath(job.repository);
157
+ const projectPath = resolveRepositoryProjectPath(projectRoot, job.projectPath);
158
+ const liveHead = job.localMerge?.sourceRef
159
+ ? localSourceHead(projectPath, job.localMerge.sourceRef)
160
+ : localWorkingHead(projectPath);
161
+ if (liveHead !== headSha)
162
+ throw new Error('task.revise rejected: local Git source head changed since immutable review');
163
+ const response = await submitTargetedRevisionRequest(store, jobId, {
164
+ requestId, reviewTaskId, reviewExecutionId, headSha, originalTaskId,
165
+ findings: findings,
166
+ });
167
+ // Reviewer is still RUNNING: verdict event will wake the reconciler.
168
+ // The committed receipt must not be obscured by an unrelated wake failure.
169
+ return response;
170
+ }
140
171
  if (command === 'task.comment') {
141
172
  const taskId = typeof body.taskId === 'string' ? body.taskId : '';
142
173
  const message = typeof body.message === 'string' ? body.message : '';
@@ -0,0 +1,44 @@
1
+ function reviewRecord(value) {
2
+ return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
3
+ }
4
+ function reviewHeadSha(event) {
5
+ const data = reviewRecord(event.data);
6
+ const outcome = reviewRecord(data.outcome);
7
+ const review = reviewRecord(data.review);
8
+ return [outcome.head_sha, outcome.headSha, review.head_sha, review.headSha, data.head_sha, data.headSha]
9
+ .find((value) => typeof value === 'string' && value.length > 0);
10
+ }
11
+ function reviewIssues(event) {
12
+ const data = reviewRecord(event.data);
13
+ const outcome = reviewRecord(data.outcome);
14
+ const review = reviewRecord(data.review);
15
+ const rawIssues = data.findings !== undefined ? data.findings
16
+ : outcome.blocking_findings !== undefined ? outcome.blocking_findings
17
+ : outcome.blockingFindings !== undefined ? outcome.blockingFindings
18
+ : outcome.findings !== undefined ? outcome.findings
19
+ : review.findings !== undefined ? review.findings
20
+ : review.issues !== undefined ? review.issues
21
+ : data.blocking_findings !== undefined ? data.blocking_findings
22
+ : data.issues;
23
+ if (rawIssues === undefined)
24
+ return [];
25
+ if (!Array.isArray(rawIssues))
26
+ return ['[unparseable blocking finding]'];
27
+ return rawIssues.map(item => {
28
+ if (typeof item === 'string')
29
+ return item.trim() || '[unparseable blocking finding]';
30
+ if (!item || typeof item !== 'object' || Array.isArray(item))
31
+ return '[unparseable blocking finding]';
32
+ const value = item;
33
+ const text = [value.summary, value.message, value.finding, value.title, value.id]
34
+ .find(candidate => typeof candidate === 'string' && candidate.trim().length > 0);
35
+ return typeof text === 'string' ? text.trim() : '[unparseable blocking finding]';
36
+ });
37
+ }
38
+ export function normalizeReviewEvidence(event, task) {
39
+ const explicitHeadSha = reviewHeadSha(event);
40
+ const headSha = explicitHeadSha ?? (event.type === 'review.approved' ? task.reviewHeadSha : undefined);
41
+ if (!headSha)
42
+ return null;
43
+ return { headSha, issues: reviewIssues(event) };
44
+ }
@@ -1,3 +1,4 @@
1
+ import { isFinalReviewAgent } from './final-review-role.js';
1
2
  /** Called inside SQLite mutateJob against the latest durable Job snapshot. */
2
3
  export function reviewGenerationMatches(current, original, task, headSha) {
3
4
  const fresh = current.tasks.find(item => item.id === task.id);
@@ -10,7 +11,7 @@ export function reviewGenerationMatches(current, original, task, headSha) {
10
11
  // generation. Reject competing reviewers of that same head deterministically.
11
12
  if (current.review?.outcome === 'stale' && original.review?.outcome === 'stale'
12
13
  && current.review.headSha !== headSha && task.planningDecisionId) {
13
- const currentHeadReviewers = current.tasks.filter(item => item.agentName === 'reviewer'
14
+ const currentHeadReviewers = current.tasks.filter(item => isFinalReviewAgent(item.agentName)
14
15
  && item.reviewHeadSha === headSha && item.state !== 'CANCELLED');
15
16
  return currentHeadReviewers.at(-1)?.id === task.id;
16
17
  }
@@ -0,0 +1,86 @@
1
+ import { decideRevisionLifecycle } from './workflow/revision-v2.js';
2
+ /** Only Graph-authorized, fully covered review feedback can dispatch a child. */
3
+ export function revisionRequestReady(job, task) {
4
+ if (task.revision?.kind !== 'targeted')
5
+ return true;
6
+ const review = job.review;
7
+ if (!review || review.outcome !== 'changes_required' || review.revisionDisposition !== 'targeted'
8
+ || review.taskId !== task.revision.reviewTaskId)
9
+ return false;
10
+ const requests = job.reviewRevisionRequests ?? [];
11
+ return task.revision.requestIds.length > 0 && task.revision.requestIds.every(id => {
12
+ const request = requests.find(item => item.requestId === id);
13
+ return request?.revisionTaskId === task.id && request.status === 'queued'
14
+ && request.reviewHeadSha === task.revision?.basedOnHeadSha;
15
+ });
16
+ }
17
+ function updateStatus(request, next) {
18
+ request.status = next;
19
+ }
20
+ /** Reconstruct Graph transitions from durable correlated Task results on restart.
21
+ * Task completion is independently fenced by the canonical Task Graph and its
22
+ * execution generation. Never infer success from a browser submission receipt.
23
+ */
24
+ export function reconcileReviewRevisionFacts(job) {
25
+ let changed = false;
26
+ for (const request of job.reviewRevisionRequests ?? []) {
27
+ const task = request.revisionTaskId && job.tasks.find(item => item.id === request.revisionTaskId);
28
+ if (!task || task.revision?.reviewTaskId !== request.reviewTaskId || !task.revision.requestIds.includes(request.requestId))
29
+ continue;
30
+ // Only the Task Graph's already-authorized recovery to QUEUED can reopen
31
+ // a failed/in-flight revision request. Never retry from a stale event.
32
+ if ((request.status === 'failed' || request.status === 'running')
33
+ && task.state === 'QUEUED' && task.executionId === null
34
+ && job.review?.outcome === 'changes_required' && job.review.revisionDisposition === 'targeted'
35
+ && job.review.taskId === request.reviewTaskId) {
36
+ const decision = decideRevisionLifecycle(request.status === 'failed' ? 'FAILED' : 'RUNNING', 'revision.retry', { taskRetryQueued: true });
37
+ if (decision.accepted && decision.target === 'QUEUED'
38
+ && decision.actions.some(action => action.id === 'revision.queueTask')) {
39
+ updateStatus(request, 'queued');
40
+ changed = true;
41
+ }
42
+ }
43
+ if (request.status === 'requested' && job.review?.outcome === 'changes_required'
44
+ && job.review.taskId === request.reviewTaskId && job.review.revisionDisposition === 'targeted') {
45
+ const decision = decideRevisionLifecycle('REQUESTED', 'revision.queue', { changesRequiredRecorded: true });
46
+ if (decision.accepted && decision.target === 'QUEUED' && decision.actions.some(action => action.id === 'revision.queueTask')) {
47
+ updateStatus(request, 'queued');
48
+ changed = true;
49
+ }
50
+ }
51
+ if (request.status === 'queued' && ['RUNNING', 'SUCCEEDED', 'FAILED'].includes(task.state)) {
52
+ const started = decideRevisionLifecycle('QUEUED', 'revision.started');
53
+ if (started.accepted && started.target === 'RUNNING') {
54
+ if (task.state === 'RUNNING') {
55
+ updateStatus(request, 'running');
56
+ changed = true;
57
+ }
58
+ else {
59
+ const finished = decideRevisionLifecycle('RUNNING', task.state === 'SUCCEEDED' ? 'revision.verified' : 'revision.failed');
60
+ if (finished.accepted && finished.target === (task.state === 'SUCCEEDED' ? 'VERIFIED' : 'FAILED')) {
61
+ updateStatus(request, task.state === 'SUCCEEDED' ? 'verified' : 'failed');
62
+ changed = true;
63
+ }
64
+ }
65
+ }
66
+ }
67
+ else if (request.status === 'running' && (task.state === 'SUCCEEDED' || task.state === 'FAILED')) {
68
+ const finished = decideRevisionLifecycle('RUNNING', task.state === 'SUCCEEDED' ? 'revision.verified' : 'revision.failed');
69
+ if (finished.accepted && finished.target === (task.state === 'SUCCEEDED' ? 'VERIFIED' : 'FAILED')) {
70
+ updateStatus(request, task.state === 'SUCCEEDED' ? 'verified' : 'failed');
71
+ changed = true;
72
+ }
73
+ }
74
+ }
75
+ if (changed)
76
+ job.updatedAt = new Date().toISOString();
77
+ return changed;
78
+ }
79
+ export async function reconcileReviewRevisions(store, jobId) {
80
+ if (!store.mutateJob)
81
+ return;
82
+ await store.mutateJob(jobId, current => {
83
+ reconcileReviewRevisionFacts(current);
84
+ return current;
85
+ });
86
+ }
@@ -0,0 +1,15 @@
1
+ /** Revision and Review-round provenance belongs exclusively to local SQLite.
2
+ * Collaboration projections must NEVER invent or advance these records.
3
+ * The remote snapshot may be newer for other data, but it is not the source
4
+ * of operational review requests, statuses, or execution generations.
5
+ */
6
+ export function preserveReviewRevisionHistory(local, merged) {
7
+ if (local.reviewRevisionRequests)
8
+ merged.reviewRevisionRequests = structuredClone(local.reviewRevisionRequests);
9
+ else
10
+ delete merged.reviewRevisionRequests;
11
+ if (local.reviewRevisionRounds)
12
+ merged.reviewRevisionRounds = structuredClone(local.reviewRevisionRounds);
13
+ else
14
+ delete merged.reviewRevisionRounds;
15
+ }
@@ -0,0 +1,191 @@
1
+ import { isFinalReviewAgent } from './final-review-role.js';
2
+ import { appendTaskComment } from './task-comments.js';
3
+ import { createHash } from 'node:crypto';
4
+ import { createTaskEntity } from './workflow/entity-creation.js';
5
+ import { decideRevisionLifecycle } from './workflow/revision-v2.js';
6
+ /** A stable child identity per immutable review round and responsible owner.
7
+ * The request IDs are append-only feedback attached to this single child.
8
+ */
9
+ export function targetedRevisionTaskId(reviewTaskId, ownerTaskId) {
10
+ return 'revision-' + createHash('sha256').update(JSON.stringify([reviewTaskId, ownerTaskId])).digest('hex').slice(0, 24);
11
+ }
12
+ /** A request and its source Task comment are one atomic SQLite Job snapshot mutation.
13
+ * The caller MUST execute this reducer inside RelayStore.mutateJob. It is never
14
+ * an out-of-band Task write and never reopens the original result.
15
+ */
16
+ export function recordTargetedRevisionRequest(job, input) {
17
+ if (!input.requestId?.trim() || input.requestId.length > 160)
18
+ throw new Error('revision request requires stable request ID (max 160)');
19
+ if (!input.headSha?.trim() || !input.reviewExecutionId?.trim())
20
+ throw new Error('revision requires exact reviewer execution and immutable head');
21
+ if (!input.findings?.length || input.findings.some(item => !item.id?.trim() || !item.summary?.trim() || item.summary.length > 4000))
22
+ throw new Error('revision requires identified, nonempty findings');
23
+ if (new Set(input.findings.map(item => item.id)).size !== input.findings.length)
24
+ throw new Error('duplicate finding IDs in revision request');
25
+ const existing = job.reviewRevisionRequests?.find(item => item.requestId === input.requestId);
26
+ if (existing) {
27
+ const same = existing.reviewTaskId === input.reviewTaskId
28
+ && existing.reviewExecutionId === input.reviewExecutionId
29
+ && existing.reviewHeadSha === input.headSha
30
+ && existing.originalTaskId === input.originalTaskId
31
+ && JSON.stringify(existing.findings) === JSON.stringify(input.findings);
32
+ if (!same)
33
+ throw new Error('revision request ID reused with different immutable feedback');
34
+ return { request: existing, created: false };
35
+ }
36
+ const reviewer = job.tasks.find(item => item.id === input.reviewTaskId);
37
+ const owner = job.tasks.find(item => item.id === input.originalTaskId);
38
+ const facts = {
39
+ reviewerAuthorized: job.state === 'ACTIVE'
40
+ && isFinalReviewAgent(reviewer?.agentName)
41
+ && reviewer?.state === 'RUNNING'
42
+ && reviewer?.executionId === input.reviewExecutionId,
43
+ reviewHeadCurrent: reviewer?.reviewHeadSha === input.headSha
44
+ && job.headSha === input.headSha
45
+ && (!job.review || (job.review.headSha === input.headSha
46
+ && job.review.taskId === input.reviewTaskId
47
+ && ['pending', 'started'].includes(job.review.outcome))),
48
+ originalTaskSucceeded: owner?.state === 'SUCCEEDED'
49
+ && owner.kind !== 'planner'
50
+ && !isFinalReviewAgent(owner.agentName)
51
+ && owner.id !== reviewer?.id
52
+ && !owner.revision,
53
+ };
54
+ const decision = decideRevisionLifecycle('NONE', 'revision.submit', facts);
55
+ if (!decision.accepted || decision.target !== 'REQUESTED'
56
+ || decision.actions.map(item => item.id).join(',') !== 'revision.recordRequest') {
57
+ throw new Error('revision rejected: reviewer, head, execution or original owner is not current/eligible');
58
+ }
59
+ const now = new Date().toISOString();
60
+ const childId = targetedRevisionTaskId(input.reviewTaskId, input.originalTaskId);
61
+ const request = {
62
+ requestId: input.requestId,
63
+ reviewTaskId: input.reviewTaskId,
64
+ reviewExecutionId: input.reviewExecutionId,
65
+ reviewHeadSha: input.headSha,
66
+ originalTaskId: input.originalTaskId,
67
+ findings: structuredClone(input.findings),
68
+ createdAt: now,
69
+ status: 'requested', revisionTaskId: childId,
70
+ feedbackOrigin: 'final-review',
71
+ };
72
+ job.reviewRevisionRequests = [...(job.reviewRevisionRequests ?? []), request];
73
+ appendTaskComment(job, input.originalTaskId, 'Final Review ' + input.reviewTaskId + ' requested revision at ' + input.headSha + ':\n'
74
+ + input.findings.map(f => '- ' + f.id + ': ' + f.summary).join('\n'), { author: 'reviewer', kind: 'review.feedback', executionId: input.reviewExecutionId,
75
+ transition: 'revision.requested', idempotencyKey: 'review-revision/' + input.requestId });
76
+ // Child creation and finding association are committed together with the
77
+ // request and owner comment: a crash cannot orphan an accepted request.
78
+ const existingChild = job.tasks.find(item => item.id === childId);
79
+ if (existingChild) {
80
+ if (existingChild.revision?.kind !== 'targeted' || existingChild.revision.originalTaskId !== input.originalTaskId
81
+ || existingChild.revision.reviewTaskId !== input.reviewTaskId || existingChild.revision.basedOnHeadSha !== input.headSha
82
+ || existingChild.state !== 'DRAFT')
83
+ throw new Error('revision child no longer accepts feedback in this immutable review round');
84
+ existingChild.revision.requestIds = [...new Set([...existingChild.revision.requestIds, input.requestId])];
85
+ }
86
+ else {
87
+ if (!owner || !reviewer)
88
+ throw new Error('review revision owner/reviewer missing');
89
+ const originalEvidence = owner.result ? JSON.stringify(owner.result) : 'No original result';
90
+ const child = createTaskEntity(job, {
91
+ jobId: job.id, id: childId, kind: 'work', title: 'Revise ' + (owner.title ?? owner.id),
92
+ priority: owner.priority ?? job.priority, storySize: owner.storySize ?? 'M', projectName: owner.projectName,
93
+ agentName: owner.agentName, parentTaskId: owner.id, dependencies: [reviewer.id],
94
+ capabilities: [...owner.capabilities], workerRequirements: owner.workerRequirements,
95
+ adapter: owner.adapter, input: [
96
+ `Revision of original Task ${owner.id} for Job ${job.id}; Final Review ${reviewer.id}, immutable reviewed head ${input.headSha}.`,
97
+ 'Retrieve the authoritative Task Context; follow ALL append-only review.feedback comments and associated request IDs. Repair the original result without changing the historical succeeded Task. Review the full current Job objective and repository head, implement and verify the correction, and include root cause, solution, validation and self-review evidence in the durable result.',
98
+ 'Original Task input:\n' + owner.input,
99
+ 'Original completed evidence:\n' + originalEvidence,
100
+ ].join('\n\n'), output: owner.output ?? { kind: 'task_pr' },
101
+ revision: { kind: 'targeted', originalTaskId: owner.id, requestIds: [input.requestId],
102
+ reviewTaskId: reviewer.id, basedOnHeadSha: input.headSha },
103
+ attempt: 0, maxAttempts: Math.max(3, owner.maxAttempts),
104
+ leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null,
105
+ result: null, error: null, continuation: null, continuationDeliveredAt: null,
106
+ timeoutMs: owner.timeoutMs, createdAt: now, updatedAt: now,
107
+ }, { defer: true });
108
+ job.tasks.push(child);
109
+ }
110
+ appendTaskComment(job, childId, 'Review feedback request ' + input.requestId + ' for owner ' + input.originalTaskId + ' at ' + input.headSha + ':\n'
111
+ + input.findings.map(f => '- ' + f.id + ': ' + f.summary + (f.evidence ? '\n Evidence: ' + f.evidence : '')).join('\n'), { author: 'reviewer', kind: 'review.feedback', executionId: input.reviewExecutionId,
112
+ transition: 'revision.requested', idempotencyKey: 'review-revision-child/' + input.requestId });
113
+ return { request, created: true };
114
+ }
115
+ /** Transaction-safe public intake boundary for the later reviewer CLI.
116
+ * No caller can publish a request or its owner comment outside one SQLite
117
+ * authoritative Job mutation. The store is responsible for rollback.
118
+ */
119
+ export async function submitTargetedRevisionRequest(store, jobId, input) {
120
+ if (!store.mutateJob)
121
+ throw new Error('targeted revision requires an authoritative atomic Job store');
122
+ let created = false;
123
+ const committed = await store.mutateJob(jobId, current => {
124
+ created = recordTargetedRevisionRequest(current, input).created;
125
+ return current;
126
+ });
127
+ const request = committed.reviewRevisionRequests?.find(item => item.requestId === input.requestId);
128
+ if (!request)
129
+ throw new Error('targeted revision mutation did not persist the request');
130
+ return { request, created };
131
+ }
132
+ /** Only exact current-generation targeted requests count for the Review Graph.
133
+ * The record is not a worker success and does not itself authorize dispatch.
134
+ */
135
+ export function targetedRequestsForReview(job, reviewTask, headSha) {
136
+ return (job.reviewRevisionRequests ?? []).filter(request => request.reviewTaskId === reviewTask.id
137
+ && request.reviewExecutionId === reviewTask.executionId
138
+ && request.reviewHeadSha === headSha
139
+ && request.status !== 'stale'
140
+ && job.tasks.some(task => task.id === request.originalTaskId && task.state === 'SUCCEEDED'));
141
+ }
142
+ /** Full finding coverage is a fact supplied to the Review Graph, not a
143
+ * second procedural review policy. Unknown findings fail closed to ownership
144
+ * resolution rather than silently disappearing behind a partial request.
145
+ */
146
+ export function targetedRequestsCoverReview(job, reviewTask, headSha, verdictIssues) {
147
+ if (!verdictIssues.length || verdictIssues.some(issue => issue.trim() === '[unparseable blocking finding]'))
148
+ return false;
149
+ const requests = targetedRequestsForReview(job, reviewTask, headSha);
150
+ if (!requests.length)
151
+ return false;
152
+ const covered = new Set(requests.flatMap(request => request.findings.flatMap(finding => [finding.id.trim(), finding.summary.trim()])));
153
+ return verdictIssues.every(issue => covered.has(issue.trim()));
154
+ }
155
+ export function dependencyValidity(task, dependencyTaskId) {
156
+ if (!task.dependencies.includes(dependencyTaskId))
157
+ throw new Error('dependency is not declared on Task');
158
+ const mode = task.dependencyValidity?.[dependencyTaskId] ?? 'order-only';
159
+ if (mode !== 'order-only' && mode !== 'revalidate' && mode !== 'rerun')
160
+ throw new Error('invalid dependency validity policy');
161
+ return mode;
162
+ }
163
+ /** Deterministic semantic evidence vector; never infer validity from filenames.
164
+ * Historical successful owners remain immutable. The latest successful child
165
+ * is new evidence; pending/failed children must be gated by the future scheduler.
166
+ */
167
+ export function dependencyRevisionVector(job, task) {
168
+ const vector = {};
169
+ for (const dependencyId of [...new Set(task.dependencies)].sort()) {
170
+ if (dependencyValidity(task, dependencyId) === 'order-only')
171
+ continue;
172
+ const original = job.tasks.find(item => item.id === dependencyId);
173
+ if (!original)
174
+ throw new Error('dependency Task not found: ' + dependencyId);
175
+ // Task-array order is not provenance: inbound snapshots and restarts may
176
+ // reorder historical children. Creation time plus ID gives stable ordering.
177
+ const latest = job.tasks.filter(item => item.revision?.originalTaskId === dependencyId && item.state === 'SUCCEEDED').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).at(-1);
178
+ const selected = latest ?? original;
179
+ if (selected.state !== 'SUCCEEDED')
180
+ throw new Error('dependency has no successful evidence: ' + dependencyId);
181
+ // The successful Task ID and attempt identify the generation. Revision
182
+ // children are distinct and never rewrite a successful parent.
183
+ vector[dependencyId] = selected.id + ':' + selected.attempt;
184
+ }
185
+ return vector;
186
+ }
187
+ export function sameDependencyRevisionVector(a, b) {
188
+ const keysA = Object.keys(a).sort(), keysB = Object.keys(b).sort();
189
+ return keysA.length === keysB.length
190
+ && keysA.every((key, index) => key === keysB[index] && a[key] === b[key]);
191
+ }
@@ -0,0 +1,49 @@
1
+ import { createHash } from 'node:crypto';
2
+ function positiveIntegerSetting(env, name, fallback) {
3
+ const raw = env[name];
4
+ if (raw === undefined || raw.trim() === '')
5
+ return fallback;
6
+ const value = Number(raw);
7
+ if (!Number.isSafeInteger(value) || value < 1 || value > 100) {
8
+ throw new Error(`${name} must be an integer from 1 to 100`);
9
+ }
10
+ return value;
11
+ }
12
+ /** Operator-controlled loop bounds; defaults preserve the existing five-round gate. */
13
+ export function reviewRevisionLimits(env = process.env) {
14
+ return {
15
+ maxRounds: positiveIntegerSetting(env, 'AGENTS_RELAY_REVIEW_MAX_ROUNDS', 5),
16
+ maxNoProgressRounds: positiveIntegerSetting(env, 'AGENTS_RELAY_REVIEW_NO_PROGRESS_LIMIT', 1),
17
+ };
18
+ }
19
+ /** Stable identity for the review findings, independent of ordering and whitespace. */
20
+ export function reviewFindingFingerprint(findings) {
21
+ const normalized = [...new Set(findings.map(finding => finding.trim().replace(/\s+/g, ' ').toLocaleLowerCase('en-US')).filter(Boolean))].sort();
22
+ if (!normalized.length)
23
+ return undefined;
24
+ return createHash('sha256').update(JSON.stringify(normalized)).digest('hex');
25
+ }
26
+ /** Derive the fingerprint for pre-field rounds from their durable request evidence. */
27
+ export function reviewRoundFindingFingerprint(job, round) {
28
+ if (round.findingFingerprint)
29
+ return round.findingFingerprint;
30
+ const findings = (job.reviewRevisionRequests ?? [])
31
+ .filter(request => round.requestIds.includes(request.requestId))
32
+ .flatMap(request => request.findings.map(finding => finding.summary));
33
+ return reviewFindingFingerprint(findings);
34
+ }
35
+ export function repeatedFindingRounds(job, currentRound) {
36
+ const currentFingerprint = reviewRoundFindingFingerprint(job, currentRound);
37
+ if (!currentFingerprint || currentRound.status !== 'changes_required')
38
+ return 0;
39
+ let count = 0;
40
+ const previousRounds = (job.reviewRevisionRounds ?? [])
41
+ .filter(round => round.reviewTaskId !== currentRound.reviewTaskId && round.status === 'changes_required')
42
+ .sort((a, b) => a.recordedAt.localeCompare(b.recordedAt) || a.reviewTaskId.localeCompare(b.reviewTaskId));
43
+ for (let index = previousRounds.length - 1; index >= 0; index -= 1) {
44
+ if (reviewRoundFindingFingerprint(job, previousRounds[index]) !== currentFingerprint)
45
+ break;
46
+ count += 1;
47
+ }
48
+ return count;
49
+ }
@@ -0,0 +1,54 @@
1
+ import { appendTaskComment } from './task-comments.js';
2
+ import { dispatchReviewLifecycle } from './workflow/review-v2.js';
3
+ import { repeatedFindingRounds, reviewRevisionLimits } from './review-revision-policy.js';
4
+ /** Pure durable facts for the canonical Review Graph, not an alternate decision engine. */
5
+ function settlementFacts(job, taskId, limits) {
6
+ const requests = (job.reviewRevisionRequests ?? []).filter(item => item.reviewTaskId === taskId);
7
+ const targetedRevisionsVerified = requests.length > 0 && requests.every(request => request.status === 'verified' && job.tasks.some(task => task.id === request.revisionTaskId && task.state === 'SUCCEEDED'));
8
+ const rounds = (job.reviewRevisionRounds ?? []).filter(item => item.status === 'changes_required');
9
+ const currentRound = rounds.find(item => item.reviewTaskId === taskId);
10
+ return {
11
+ targetedRevisionsVerified,
12
+ reviewRoundWithinLimit: rounds.length < limits.maxRounds,
13
+ reviewNoProgressWithinLimit: !currentRound || repeatedFindingRounds(job, currentRound) < limits.maxNoProgressRounds,
14
+ };
15
+ }
16
+ /** The Graph alone decides whether the verified round can proceed or must escalate. */
17
+ export async function settleReviewRevisionRound(store, job) {
18
+ if (!store.mutateJob)
19
+ return job;
20
+ const review = job.review;
21
+ if (review?.outcome !== 'changes_required' || review.revisionDisposition !== 'targeted' || !review.taskId)
22
+ return job;
23
+ const limits = reviewRevisionLimits();
24
+ const facts = settlementFacts(job, review.taskId, limits);
25
+ const decision = await dispatchReviewLifecycle(review.outcome, 'revision.settled', facts);
26
+ if (!decision.accepted)
27
+ return job;
28
+ const action = decision.actions.map(item => item.id);
29
+ const prepare = decision.accepted && decision.target === 'STALE' && action.includes('review.prepareRereview');
30
+ const exhausted = decision.accepted && decision.target === 'CHANGES_REQUIRED' && action.includes('review.requireOwnerResolution');
31
+ if (!prepare && !exhausted)
32
+ return job;
33
+ return store.mutateJob(job.id, current => {
34
+ const latest = current.review;
35
+ if (latest?.outcome !== 'changes_required' || latest.revisionDisposition !== 'targeted'
36
+ || latest.taskId !== review.taskId || latest.headSha !== review.headSha)
37
+ return current;
38
+ const currentFacts = settlementFacts(current, review.taskId, limits);
39
+ if (Object.keys(facts).some(key => currentFacts[key] !== facts[key]))
40
+ return current;
41
+ const at = new Date().toISOString();
42
+ if (exhausted) {
43
+ current.review = { ...latest, revisionDisposition: 'needs-ownership', updatedAt: at };
44
+ const reason = !currentFacts.reviewRoundWithinLimit
45
+ ? `Targeted review loop reached its configured ${limits.maxRounds}-round limit`
46
+ : `The same blocking findings recurred without progress ${limits.maxNoProgressRounds} time(s)`;
47
+ appendTaskComment(current, review.taskId, `${reason}; explicit Planner/owner recovery required. No approval or merge authorized.`, { author: 'relay', idempotencyKey: 'review-round-limit/' + review.taskId });
48
+ }
49
+ else {
50
+ current.review = { ...latest, outcome: 'stale', updatedAt: at };
51
+ }
52
+ return current;
53
+ });
54
+ }